proto upgrade + better naming for scripts vars (#14)

Author: alireza-pazooki

gradle.properties

@@ -1,2 +1,2 @@
-version=1.34.4-1
+version=1.34.10-1
 org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

src/main/proto/cel/expr/checked.proto

@@ -236,6 +236,20 @@ message Decl {
     Constant value = 2;
 
     // Documentation string for the identifier.
+    //
+    // Provide a brief description of what the variable represents and whether
+    // there are any constraints on the formatting or supported value range.
+    //
+    // Examples:
+    //
+    //    'request.auth.principal' - string which uniquely identifies an
+    //    authenticated principal. For JSON Web Tokens (JWTs), the principal
+    //    is the combination of the issuer ('iss') and subject ('sub') token
+    //    fields concatenated by a forward slash: iss + `/` + sub.
+    //
+    //    'min_cpus' - integer value indicates the minimum number of CPUs
+    //    required for a compute cluster. The 'min_cpus' value must be 
+    //    greater than zero and less than 'max_cpus' or 64 whichever is less.
     string doc = 3;
   }
 
@@ -293,11 +307,45 @@ message Decl {
       bool is_instance_function = 5;
 
       // Documentation string for the overload.
+      //
+      // Provide examples of the overload behavior, preferring to use literal
+      // values as input with a comment on the return value.
+      //
+      // Examples:
+      //
+      //    // Determine whether a value of type <V> exists within a list<V>.
+      //    2 in [1, 2, 3] // returns true
+      //
+      //    // Determine whether a key of type <K> exists within a map<K,V>.
+      //    'hello' in {'hi': 'you', 'hello': 'there'}  // returns true
+      //    'help' in {'hi': 'you', 'hello': 'there'}  // returns false
+      //
+      //    // Take the substring of a string starting at a specific character
+      //    // offset (inclusive).
+      //    "tacocat".substring(1) // returns "acocat"
+      //    "tacocat".substring(20) // error
+      //
+      //    // Take the substring of a string starting at a specific character
+      //    // offset (inclusive) and ending at the given offset (exclusive).
+      //    "tacocat".substring(1, 6) // returns "acoca"
       string doc = 6;
     }
 
     // Required. List of function overloads, must contain at least one overload.
     repeated Overload overloads = 1;
+
+    // Documentation string for the function that indicates the general purpose
+    // of the function and its behavior.
+    //
+    // Documentation strings for the function should be general purpose with
+    // specific examples provided in the overload doc string.
+    //
+    // Examples:
+    // 
+    //     The 'in' operator tests whether an item exists in a collection.
+    //
+    //     The 'substring' function returns a substring of a target string.
+    string doc = 2;
   }
 
   // The fully qualified name of the declaration.

src/main/proto/cel/expr/conformance/env_config.proto

@@ -0,0 +1,183 @@
+// Copyright 2025 Google LLC
+//
+// 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.
+
+syntax = "proto3";
+
+package cel.expr.conformance;
+
+import "cel/expr/checked.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/descriptor.proto";
+
+option cc_enable_arenas = true;
+option go_package = "cel.dev/expr/conformance";
+option java_multiple_files = true;
+option java_outer_classname = "EnvironmentProto";
+option java_package = "cel.dev.expr.conformance";
+
+// Representation of a CEL Environment, defining what features and extensions
+// are available for conformance testing.
+message Environment {
+  // Name of the environment
+  string name = 1;
+
+  // Description for the current environment
+  string description = 2;
+
+  // Sets the namespace (container) for the expression.
+  // This is used to simplify resolution.
+  // For example with container
+  //   `google.rpc.context`
+  //  an identifier of `google.rpc.context.AttributeContext` could be referred
+  //  to simply as `AttributeContext` in the CEL expression.
+  string container = 3;
+
+  // Import represents a type name that will be abbreviated by its simple name
+  // making it easier to reference simple type names from packages other than
+  // the expression container.
+  // For ex:
+  //   Import{name: 'google.rpc.Status'}
+  // The above import will ensure that `google.rpc.Status` is available by the
+  // simple name `Status` within CEL expressions.
+  message Import {
+    // Qualified type name which will be abbreviated
+    string name = 1;
+  }
+
+  // List of abbreviations to be added to the CEL environment
+  repeated Import imports = 4;
+
+  // Set of options to subset a subsettable library
+  LibrarySubset stdlib = 5;
+
+  // List of extensions to enable in the CEL environment.
+  repeated Extension extensions = 6;
+
+  // ContextVariable represents a message type to be made available as a
+  // context variable to the CEL environment.
+  message ContextVariable {
+    // Fully qualified type name of the context proto.
+    string type_name = 1;
+  }
+
+  // If set, adds a context declaration from a proto message.
+  //
+  // Context messages have all of their top-level fields available as variables
+  // in the type checker.
+  ContextVariable context_variable = 7;
+
+  // List of declarations to be configured in the CEL environment.
+  //
+  // Note: The CEL environment can be configured with either the
+  // context_variable or a set of ident_decls provided as part of declarations.
+  // Providing both will result in an error.
+  repeated cel.expr.Decl declarations = 8;
+
+  // List of validators for validating the parsed ast.
+  repeated Validator validators = 9;
+
+  // List of feature flags to be enabled or disabled.
+  repeated Feature features = 10;
+
+  // Disables including the declarations from the standard CEL environment.
+  //
+  // NOTE: Do not disable the standard CEL declarations unless you are aware of
+  // the implications and have discussed your use case on cel-discuss@
+  // or with the members of the cel-governance-team@
+  //
+  // Deprecated: Use LibrarySubset to disable standard cel declarations instead:
+  //   stdlib = LibrarySubset{ disable: true }
+  bool disable_standard_cel_declarations = 11;
+
+  // If provided, uses the provided FileDescriptorSet to extend types available
+  // the CEL expression. All "well-known" protobuf messages (google.protobuf.*)
+  // are known to the CEL compiler, but all others must be provided for type
+  // checking.
+  google.protobuf.FileDescriptorSet message_type_extension = 12;
+
+  // When macro call tracking is enabled, the resulting SourceInfo in the
+  // CheckedExpr will contain a collection of expressions representing the
+  // function calls which were replaced by macros.
+  //
+  // Deprecated: Use Feature to enable macro call tracking
+  //  Feature{ name: "cel.feature.macro_call_tracking", enabled: true }
+  bool enable_macro_call_tracking = 13;
+}
+
+// Represents a named validator with an optional map-based configuration object.
+// Naming convention followed by validators:
+//   <domain>.validator.<validator_name>
+// For ex:
+//   `cel.validator.timestamp`
+//
+// Note: the map-keys must directly correspond to the internal representation of
+// the original validator, and should only use primitive scalar types as values
+// at this time.
+message Validator {
+  string name = 1;
+
+  // Additional configurations to be included as part of the validation
+  map<string, google.protobuf.Value> config = 2;
+}
+
+// Represents a named boolean feature flag supported by CEL.
+// Naming convention followed by features:
+//   <domain>.feature.<feature_name>
+// For ex:
+//   `cel.feature.cross_type_numeric_comparisons`
+message Feature {
+  // Name of the feature flag.
+  string name = 1;
+
+  // State of the feature flab.
+  bool enabled = 2;
+}
+
+// Extension represents a versioned extension library reference to enable in the
+// CEL environment.
+message Extension {
+  // Name of the extension library.
+  string name = 1;
+  // Version of the extension library.
+  string version = 2;
+}
+
+// LibrarySubset indicates a subset of the macros and functions supported by a
+// subsettable library.
+message LibrarySubset {
+  // Indicates whether the library has been disabled, typically only
+  // used for default-enabled libraries like stdlib.
+  bool disabled = 1;
+
+  // Disables macros for the given library.
+  bool disable_macros = 2;
+
+  // Specifies a set of macro function names to include in the subset.
+  repeated string include_macros = 3;
+
+  // Specifies a set of macro function names to exclude from the subset.
+  // Note: if IncludeMacros is non-empty, then ExcludeFunctions is ignored.
+  repeated string exclude_macros = 4;
+
+  // Specifies a set of functions to include in the subset.
+  //
+  // Note: the overloads specified in the subset need only specify their ID.
+  // Note: if IncludeFunctions is non-empty, then ExcludeFunctions is ignored.
+  repeated cel.expr.Decl include_functions = 5;
+
+  // Specifies the set of functions to exclude from the subset.
+  //
+  // Note: the overloads specified in the subset need only specify their ID.
+  repeated cel.expr.Decl exclude_functions = 6;
+}

src/main/proto/cel/expr/conformance/envcheck.proto

@@ -1,9 +1,25 @@
+// Copyright 2024 Google LLC
+//
+// 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.
+
 syntax = "proto2";
 
 package cel.expr.conformance.proto2;
 
 import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/protobuf/wrappers.proto";
@@ -47,6 +63,9 @@ message TestAllTypes {
   optional string single_string = 14 [default = "empty"];
   optional bytes single_bytes = 15 [default = "none"];
 
+  // Collides with 'in' operator.
+  optional bool in = 18;
+
   // Wellknown.
   optional google.protobuf.Any single_any = 100;
   optional google.protobuf.Duration single_duration = 101;
@@ -65,6 +84,8 @@ message TestAllTypes {
   optional google.protobuf.ListValue list_value = 114;
   optional google.protobuf.NullValue null_value = 115;
   optional google.protobuf.NullValue optional_null_value = 116;
+  optional google.protobuf.FieldMask field_mask = 117;
+  optional google.protobuf.Empty empty = 118;
 
   // Nested messages
   oneof nested_type {
@@ -96,7 +117,7 @@ message TestAllTypes {
   repeated NestedEnum repeated_nested_enum = 52;
   repeated string repeated_string_piece = 53 [ctype = STRING_PIECE];
   repeated string repeated_cord = 54 [ctype = CORD];
-  repeated NestedMessage repeated_lazy_message = 55 [lazy = true];
+  repeated NestedMessage repeated_lazy_message = 55;
 
   // Repeated wellknown.
   repeated google.protobuf.Any repeated_any = 120;
@@ -286,6 +307,19 @@ message TestAllTypes {
   map<string, google.protobuf.StringValue> map_string_string_wrapper = 321;
   map<string, google.protobuf.BoolValue> map_string_bool_wrapper = 322;
   map<string, google.protobuf.BytesValue> map_string_bytes_wrapper = 323;
+
+  oneof kind {
+    NestedTestAllTypes oneof_type = 400;
+    NestedMessage oneof_msg = 401;
+    bool oneof_bool = 402;
+  }
+
+  optional group NestedGroup = 403 {
+    optional int32 single_id = 404;
+    optional string single_name = 405;
+  }
+
+  extensions 1000 to max;
 }
 
 // This proto includes a recursively nested message.