Support attribute qualification, plan select, allow parsed-only ident resolution on enums

PiperOrigin-RevId: 840949005

Author: l46kok

common/src/main/java/dev/cel/common/values/CelValueConverter.java

@@ -33,7 +33,7 @@
 @SuppressWarnings("unchecked") // Unchecked cast of generics due to type-erasure (ex: MapValue).
 @Internal
 @Immutable
-abstract class CelValueConverter {
+public abstract class CelValueConverter {
 
   /** Adapts a {@link CelValue} to a plain old Java Object. */
   public Object unwrap(CelValue celValue) {

runtime/src/main/java/dev/cel/runtime/CelEvaluationExceptionBuilder.java

@@ -83,10 +83,16 @@ public static CelEvaluationExceptionBuilder newBuilder(String message, Object...
    */
   @Internal
   public static CelEvaluationExceptionBuilder newBuilder(CelRuntimeException celRuntimeException) {
+    // TODO: Temporary until migration is complete.
     Throwable cause = celRuntimeException.getCause();
-    return new CelEvaluationExceptionBuilder(cause.getMessage())
-        .setCause(cause)
-        .setErrorCode(celRuntimeException.getErrorCode());
+    String message =
+        cause == null
+            ? celRuntimeException.getMessage()
+            : celRuntimeException.getCause().getMessage();
+
+    return new CelEvaluationExceptionBuilder(message)
+        .setErrorCode(celRuntimeException.getErrorCode())
+        .setCause(cause);
   }
 
   private CelEvaluationExceptionBuilder(String message) {

runtime/src/main/java/dev/cel/runtime/planner/Attribute.java

@@ -14,64 +14,13 @@
 
 package dev.cel.runtime.planner;
 
-
-import com.google.common.collect.ImmutableList;
 import com.google.errorprone.annotations.Immutable;
-import dev.cel.common.types.CelTypeProvider;
-import dev.cel.common.types.TypeType;
 import dev.cel.runtime.GlobalResolver;
 
+/** Represents a resolvable symbol or path (such as a variable or a field selection). */
 @Immutable
 interface Attribute {
   Object resolve(GlobalResolver ctx);
 
-  final class MaybeAttribute implements Attribute {
-    private final ImmutableList<Attribute> attributes;
-
-    @Override
-    public Object resolve(GlobalResolver ctx) {
-      for (Attribute attr : attributes) {
-        Object value = attr.resolve(ctx);
-        if (value != null) {
-          return value;
-        }
-      }
-
-      // TODO: Handle unknowns
-      throw new UnsupportedOperationException("Unknown attributes is not supported yet");
-    }
-
-    MaybeAttribute(ImmutableList<Attribute> attributes) {
-      this.attributes = attributes;
-    }
-  }
-
-  final class NamespacedAttribute implements Attribute {
-    private final ImmutableList<String> namespacedNames;
-    private final CelTypeProvider typeProvider;
-
-    @Override
-    public Object resolve(GlobalResolver ctx) {
-      for (String name : namespacedNames) {
-        Object value = ctx.resolve(name);
-        if (value != null) {
-          // TODO: apply qualifiers
-          return value;
-        }
-
-        TypeType type = typeProvider.findType(name).map(TypeType::create).orElse(null);
-        if (type != null) {
-          return type;
-        }
-      }
-
-      // TODO: Handle unknowns
-      throw new UnsupportedOperationException("Unknown attributes is not supported yet");
-    }
-
-    NamespacedAttribute(CelTypeProvider typeProvider, ImmutableList<String> namespacedNames) {
-      this.typeProvider = typeProvider;
-      this.namespacedNames = namespacedNames;
-    }
-  }
+  Attribute addQualifier(Qualifier qualifier);
 }

runtime/src/main/java/dev/cel/runtime/planner/AttributeFactory.java

@@ -15,35 +15,46 @@
 package dev.cel.runtime.planner;
 
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.Immutable;
 import dev.cel.common.CelContainer;
 import dev.cel.common.types.CelTypeProvider;
-import dev.cel.runtime.planner.Attribute.MaybeAttribute;
-import dev.cel.runtime.planner.Attribute.NamespacedAttribute;
+import dev.cel.common.values.CelValueConverter;
 
 @Immutable
 final class AttributeFactory {
 
-  private final CelContainer unusedContainer;
+  private final CelContainer container;
   private final CelTypeProvider typeProvider;
+  private final CelValueConverter celValueConverter;
 
   NamespacedAttribute newAbsoluteAttribute(String... names) {
-    return new NamespacedAttribute(typeProvider, ImmutableList.copyOf(names));
+    return new NamespacedAttribute(typeProvider, celValueConverter, ImmutableSet.copyOf(names));
   }
 
-  MaybeAttribute newMaybeAttribute(String... names) {
-    // TODO: Resolve container names
+  RelativeAttribute newRelativeAttribute(PlannedInterpretable operand) {
+    return new RelativeAttribute(operand, celValueConverter);
+  }
+
+  MaybeAttribute newMaybeAttribute(String name) {
     return new MaybeAttribute(
-        ImmutableList.of(new NamespacedAttribute(typeProvider, ImmutableList.copyOf(names))));
+        this,
+        ImmutableList.of(
+            new NamespacedAttribute(
+                typeProvider, celValueConverter, container.resolveCandidateNames(name))));
   }
 
   static AttributeFactory newAttributeFactory(
-      CelContainer celContainer, CelTypeProvider typeProvider) {
-    return new AttributeFactory(celContainer, typeProvider);
+      CelContainer celContainer,
+      CelTypeProvider typeProvider,
+      CelValueConverter celValueConverter) {
+    return new AttributeFactory(celContainer, typeProvider, celValueConverter);
   }
 
-  private AttributeFactory(CelContainer container, CelTypeProvider typeProvider) {
-    this.unusedContainer = container;
+  private AttributeFactory(
+      CelContainer container, CelTypeProvider typeProvider, CelValueConverter celValueConverter) {
+    this.container = container;
     this.typeProvider = typeProvider;
+    this.celValueConverter = celValueConverter;
   }
 }

runtime/src/main/java/dev/cel/runtime/planner/BUILD.bazel

@@ -26,8 +26,11 @@ java_library(
         ":eval_unary",
         ":eval_var_args_call",
         ":eval_zero_arity",
+        ":interpretable_attribute",
         ":planned_interpretable",
         ":planned_program",
+        ":qualifier",
+        ":string_qualifier",
         "//:auto_value",
         "//common:cel_ast",
         "//common:container",
@@ -36,11 +39,11 @@ java_library(
         "//common/ast",
         "//common/types",
         "//common/types:type_providers",
+        "//common/values",
         "//common/values:cel_value_provider",
         "//runtime:dispatcher",
         "//runtime:evaluation_exception",
         "//runtime:evaluation_exception_builder",
-        "//runtime:interpretable",
         "//runtime:program",
         "//runtime:resolved_overload",
         "@maven//:com_google_code_findbugs_annotations",
@@ -84,28 +87,67 @@ java_library(
     ],
 )
 
+java_library(
+    name = "interpretable_attribute",
+    srcs = ["InterpretableAttribute.java"],
+    deps = [
+        ":planned_interpretable",
+        ":qualifier",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)
+
 java_library(
     name = "attribute",
     srcs = [
         "Attribute.java",
         "AttributeFactory.java",
+        "MaybeAttribute.java",
+        "MissingAttribute.java",
+        "NamespacedAttribute.java",
+        "RelativeAttribute.java",
     ],
     deps = [
+        ":eval_helpers",
+        ":planned_interpretable",
+        ":qualifier",
         "//common:container",
+        "//common/exceptions:attribute_not_found",
         "//common/types",
         "//common/types:type_providers",
+        "//common/values",
+        "//common/values:cel_value",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
     ],
 )
 
+java_library(
+    name = "qualifier",
+    srcs = ["Qualifier.java"],
+    deps = [
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)
+
+java_library(
+    name = "string_qualifier",
+    srcs = ["StringQualifier.java"],
+    deps = [
+        ":qualifier",
+        "//common/exceptions:attribute_not_found",
+        "//common/values",
+    ],
+)
+
 java_library(
     name = "eval_attribute",
     srcs = ["EvalAttribute.java"],
     deps = [
         ":attribute",
-        ":planned_interpretable",
+        ":interpretable_attribute",
+        ":qualifier",
         "//runtime:evaluation_listener",
         "//runtime:function_resolver",
         "//runtime:interpretable",

runtime/src/main/java/dev/cel/runtime/planner/EvalAttribute.java

@@ -20,13 +20,18 @@
 import dev.cel.runtime.GlobalResolver;
 
 @Immutable
-final class EvalAttribute extends PlannedInterpretable {
+final class EvalAttribute extends InterpretableAttribute {
 
   private final Attribute attr;
 
   @Override
   public Object eval(GlobalResolver resolver) {
-    return attr.resolve(resolver);
+    Object resolved = attr.resolve(resolver);
+    if (resolved instanceof MissingAttribute) {
+      ((MissingAttribute) resolved).resolve(resolver);
+    }
+
+    return resolved;
   }
 
   @Override
@@ -46,9 +51,16 @@ public Object eval(
       GlobalResolver resolver,
       CelFunctionResolver lateBoundFunctionResolver,
       CelEvaluationListener listener) {
+    // TODO: Implement support
     throw new UnsupportedOperationException("Not yet supported");
   }
 
+  @Override
+  public EvalAttribute addQualifier(long exprId, Qualifier qualifier) {
+    Attribute newAttribute = attr.addQualifier(qualifier);
+    return create(exprId, newAttribute);
+  }
+
   static EvalAttribute create(long exprId, Attribute attr) {
     return new EvalAttribute(exprId, attr);
   }

runtime/src/main/java/dev/cel/runtime/planner/InterpretableAttribute.java

@@ -0,0 +1,27 @@
+// 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
+//
+//      https://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 dev.cel.runtime.planner;
+
+import com.google.errorprone.annotations.Immutable;
+
+@Immutable
+abstract class InterpretableAttribute extends PlannedInterpretable {
+
+  abstract InterpretableAttribute addQualifier(long exprId, Qualifier qualifier);
+
+  InterpretableAttribute(long exprId) {
+    super(exprId);
+  }
+}

runtime/src/main/java/dev/cel/runtime/planner/MaybeAttribute.java

@@ -0,0 +1,81 @@
+// 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
+//
+//      https://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 dev.cel.runtime.planner;
+
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.annotations.Immutable;
+import dev.cel.runtime.GlobalResolver;
+
+/**
+ * An attribute that attempts to resolve a variable against a list of potential namespaced
+ * attributes. This is used during parsed-only evaluation.
+ */
+@Immutable
+final class MaybeAttribute implements Attribute {
+  private final AttributeFactory attrFactory;
+  private final ImmutableList<NamespacedAttribute> attributes;
+
+  @Override
+  public Object resolve(GlobalResolver ctx) {
+    MissingAttribute maybeError = null;
+    for (NamespacedAttribute attr : attributes) {
+      Object value = attr.resolve(ctx);
+      if (value == null) {
+        continue;
+      }
+
+      if (value instanceof MissingAttribute) {
+        maybeError = (MissingAttribute) value;
+        // When the variable is missing in a maybe attribute, defer erroring.
+        // The variable may exist in other namespaced attributes.
+        continue;
+      }
+
+      return value;
+    }
+
+    return maybeError;
+  }
+
+  @Override
+  public Attribute addQualifier(Qualifier qualifier) {
+    Object strQualifier = qualifier.value();
+    ImmutableList.Builder<String> augmentedNamesBuilder = ImmutableList.builder();
+    ImmutableList.Builder<NamespacedAttribute> attributesBuilder = ImmutableList.builder();
+    for (NamespacedAttribute attr : attributes) {
+      if (strQualifier instanceof String && attr.qualifiers().isEmpty()) {
+        for (String varName : attr.candidateVariableNames()) {
+          augmentedNamesBuilder.add(varName + "." + strQualifier);
+        }
+      }
+
+      attributesBuilder.add(attr.addQualifier(qualifier));
+    }
+    ImmutableList<String> augmentedNames = augmentedNamesBuilder.build();
+    ImmutableList.Builder<NamespacedAttribute> namespacedAttributeBuilder = ImmutableList.builder();
+    if (!augmentedNames.isEmpty()) {
+      namespacedAttributeBuilder.add(
+          attrFactory.newAbsoluteAttribute(augmentedNames.toArray(new String[0])));
+    }
+
+    namespacedAttributeBuilder.addAll(attributesBuilder.build());
+    return new MaybeAttribute(attrFactory, namespacedAttributeBuilder.build());
+  }
+
+  MaybeAttribute(AttributeFactory attrFactory, ImmutableList<NamespacedAttribute> attributes) {
+    this.attrFactory = attrFactory;
+    this.attributes = attributes;
+  }
+}