Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,13 @@
- Fix the `PROTOVALIDATE` lint rule to check constant arguments to `duration`, `timestamp`, and
`matches` in CEL expressions, such as `duration('1d')` or an invalid regex, which otherwise only
fail when the rules are evaluated.
- Add LSP completion, hover, and go-to-definition for CEL expressions in protovalidate predefined
rules, including the `rule` and `rules` variables. Type-check CEL expressions against the file's
messages, so that hover shows the types of fields and only the overloads a function call resolved
to, and completions after an operator such as `this.name == ` match the left operand's type. CEL
features no longer treat strings in other options as CEL expressions.
- Fix LSP document links for versioned remote plugins in `buf.gen.yaml`, which pointed to a
nonexistent BSR page.
- Fix LSP hover and highlighting of CEL expressions whose proto strings contain escape sequences, which placed the ranges of string literals, and of tokens after a `\u` or `\U` escape, wrongly.
- Write module and Well-Known Type files to the cache as read-only, so that files opened from
LSP go-to-definition cannot be accidentally edited.
- Fix LSP hover and highlighting of CEL expressions whose proto strings contain escape sequences,
Expand Down
22 changes: 14 additions & 8 deletions private/buf/buflsp/cel.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,21 @@ func celIsIdentChar(c byte) bool {
return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '_'
}

// isCELKeyword returns true if the identifier is a CEL reserved keyword.
// See https://github.com/google/cel-spec/blob/master/doc/langdef.md#syntax
func isCELKeyword(name string) bool {
switch name {
case "true", "false", "null", // literals
"this", "now": // protovalidate special variables
return true
// celRootIdent returns the identifier expr starts with, such as "this" in
// "this.items[0]".
func celRootIdent(expr string) string {
expr = strings.TrimSpace(expr)
end := 0
for end < len(expr) && celIsIdentChar(expr[end]) {
end++
}
return false
return expr[:end]
}

// isCELKeyword returns true if the identifier is a CEL literal keyword or a
// protovalidate variable; see [celKeywords].
func isCELKeyword(name string) bool {
return slices.Contains(celKeywords, name)
}

// isCELMacroFunction returns true if the function name is a CEL macro (comprehension or special function).
Expand Down
236 changes: 236 additions & 0 deletions private/buf/buflsp/cel_variables.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
// Copyright 2020-2026 Buf Technologies, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package buflsp

import (
"log/slog"

"buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go/buf/validate"
"buf.build/go/standard/xlog/xslog"
"cel.dev/cel-go/cel"
"cel.dev/cel-go/common/types"
"github.com/bufbuild/buf/private/gen/data/datawkt"
"github.com/bufbuild/buf/private/pkg/protoencoding"
"github.com/bufbuild/protocompile/experimental/fdp"
"github.com/bufbuild/protocompile/experimental/ir"
"google.golang.org/protobuf/reflect/protodesc"
"google.golang.org/protobuf/reflect/protoreflect"
"google.golang.org/protobuf/reflect/protoregistry"
"google.golang.org/protobuf/types/descriptorpb"
"google.golang.org/protobuf/types/known/fieldmaskpb"
)

// celVariableNames are the protovalidate variables bound per expression. The
// global "now" is declared by the base environment.
//
// https://protovalidate.com/reference/cel_extensions/#variables
var celVariableNames = []string{"this", "rule", "rules"}

// celVariable returns the IR element type of the protovalidate variable name
// in the expression, and the member whose cardinality applies to it. Either
// may be zero: message-level `this` has no member, and the `this` of a
// predefined rule is not a proto type (see [celExpressionInfo.celEnv]).
func (e celExpressionInfo) celVariable(name string) (ir.Type, ir.Member) {
if e.predefined {
switch name {
case "rule":
return e.irMember.Element(), e.irMember
case "rules":
return e.irMember.Container(), ir.Member{}
}
return ir.Type{}, ir.Member{}
}
if name == "this" {
return e.thisIRType, e.thisMember
}
return ir.Type{}, ir.Member{}
}

// celDeclares reports whether the expression declares the protovalidate
// variable name: `rule` and `rules` are only declared in predefined rules.
func (e celExpressionInfo) celDeclares(name string) bool {
switch name {
case "rule", "rules":
return e.predefined
}
return true
}

// celVariableIRTypes returns the IR element types of the protovalidate
// variables in the expression that have one, keyed by name.
func (e celExpressionInfo) celVariableIRTypes() map[string]ir.Type {
vars := map[string]ir.Type{}
for _, name := range celVariableNames {
if irType, _ := e.celVariable(name); !irType.IsZero() {
vars[name] = irType
}
}
return vars
}

// celEnv returns base extended with the types of file (see [file.celEnv]) and
// the protovalidate variables in the expression. Variables that cannot be
// declared are left out.
func (e celExpressionInfo) celEnv(file *file, base *cel.Env) *cel.Env {
base = file.celEnv(base)
var options []cel.EnvOption
if e.predefined {
if thisType := celStandardRulesTypes[e.irMember.Container().FullName()]; thisType != nil {
options = append(options, cel.Variable("this", thisType))
}
}
for _, name := range celVariableNames {
if celType := celMemberType(e.celVariable(name)); celType != nil {
options = append(options, cel.Variable(name, celType))
}
}
if len(options) == 0 {
return base
}
env, err := base.Extend(options...)
if err != nil {
return base
}
return env
}

// celMemberType returns the CEL type of a value with element type irType and
// the cardinality of member, or nil if it has no CEL type.
func celMemberType(irType ir.Type, member ir.Member) *types.Type {
switch {
case member.IsMap():
return celMapEntryToCELType(irType)
case member.IsRepeated():
if elemType := celProtoTypeToExprType(irType); elemType != nil {
return types.NewListType(elemType)
}
return nil
default:
return celProtoTypeToExprType(irType)
}
}

// celStandardRulesTypes are the CEL types of `this` in a predefined rule,
// keyed by the buf.validate.*Rules message the rule extends.
var celStandardRulesTypes = map[ir.FullName]*types.Type{
celMessageName(&validate.AnyRules{}): types.AnyType,
celMessageName(&validate.BoolRules{}): types.BoolType,
celMessageName(&validate.BytesRules{}): types.BytesType,
celMessageName(&validate.StringRules{}): types.StringType,
celMessageName(&validate.Int32Rules{}): types.IntType,
celMessageName(&validate.Int64Rules{}): types.IntType,
celMessageName(&validate.SInt32Rules{}): types.IntType,
celMessageName(&validate.SInt64Rules{}): types.IntType,
celMessageName(&validate.SFixed32Rules{}): types.IntType,
celMessageName(&validate.SFixed64Rules{}): types.IntType,
celMessageName(&validate.EnumRules{}): types.IntType,
celMessageName(&validate.UInt32Rules{}): types.UintType,
celMessageName(&validate.UInt64Rules{}): types.UintType,
celMessageName(&validate.Fixed32Rules{}): types.UintType,
celMessageName(&validate.Fixed64Rules{}): types.UintType,
celMessageName(&validate.FloatRules{}): types.DoubleType,
celMessageName(&validate.DoubleRules{}): types.DoubleType,
celMessageName(&validate.MapRules{}): types.NewMapType(types.DynType, types.DynType),
celMessageName(&validate.RepeatedRules{}): types.NewListType(types.DynType),
celMessageName(&validate.DurationRules{}): types.DurationType,
celMessageName(&validate.TimestampRules{}): types.TimestampType,
celMessageName(&validate.FieldMaskRules{}): types.NewObjectType(string(celMessageName(&fieldmaskpb.FieldMask{}))),
}

// celEnv returns base extended with the message and enum types of the file
// and its imports, so that expressions selecting their fields type-check.
// It returns base if the file has no IR or its descriptors cannot be built.
//
// The environment is cached until the file's IR changes.
func (f *file) celEnv(base *cel.Env) *cel.Env {
if f.celTypesEnv != nil {
return f.celTypesEnv
}
f.celTypesEnv = base
if f.ir == nil {
return base
}
files, err := celFileTypes(f.ir)
if err != nil {
f.lsp.logger.Debug("failed to build CEL types for file", slog.String("uri", string(f.uri)), xslog.ErrorAttr(err))
return base
}
env, err := base.Extend(cel.TypeDescs(files))
if err != nil {
f.lsp.logger.Debug("failed to register CEL types for file", slog.String("uri", string(f.uri)), xslog.ErrorAttr(err))
return base
}
f.celTypesEnv = env
return env
}

// celFileTypes returns the descriptors of irFile and its imports.
//
// References that do not resolve, as in a file with errors, become
// placeholders rather than failing the file. The Well-Known Types are left
// out of the descriptor set and resolve from [protoregistry.GlobalFiles].
func celFileTypes(irFile *ir.File) (*protoregistry.Files, error) {
data, err := fdp.DescriptorSetBytes([]*ir.File{irFile}, fdp.ExcludeFiles(celWKTExcluder{}))
if err != nil {
return nil, err
}
// Unmarshaling parses the option values that fdp writes as unknown fields,
// such as EnumOptions.allow_alias, which protodesc validates against.
fds := new(descriptorpb.FileDescriptorSet)
if err := protoencoding.NewWireUnmarshaler(nil).Unmarshal(data, fds); err != nil {
return nil, err
}
files := new(protoregistry.Files)
resolver := celFileResolver{files}
options := protodesc.FileOptions{AllowUnresolvable: true}
for _, fileProto := range fds.GetFile() {
fileDescriptor, err := options.New(fileProto, resolver)
if err != nil {
// The types of a file that fails to build are left out.
continue
}
if err := files.RegisterFile(fileDescriptor); err != nil {
continue
}
}
return files, nil
}

// celWKTExcluder excludes the Well-Known Types from descriptor sets.
type celWKTExcluder struct{}

func (celWKTExcluder) Exclude(file *ir.File) bool {
return datawkt.Exists(file.Path())
}

// celFileResolver resolves descriptors from files, then from
// [protoregistry.GlobalFiles].
type celFileResolver struct {
files *protoregistry.Files
}

func (r celFileResolver) FindFileByPath(path string) (protoreflect.FileDescriptor, error) {
if fileDescriptor, err := r.files.FindFileByPath(path); err == nil {
return fileDescriptor, nil
}
return protoregistry.GlobalFiles.FindFileByPath(path)
}

func (r celFileResolver) FindDescriptorByName(name protoreflect.FullName) (protoreflect.Descriptor, error) {
if descriptor, err := r.files.FindDescriptorByName(name); err == nil {
return descriptor, nil
}
return protoregistry.GlobalFiles.FindDescriptorByName(name)
}
Loading