Introduce common helpers for handling AST navigation

PiperOrigin-RevId: 960507413

Author: l46kok

common/navigation/BUILD.bazel

@@ -25,3 +25,13 @@ java_library(
     name = "mutable_navigation",
     exports = ["//common/src/main/java/dev/cel/common/navigation:mutable_navigation"],
 )
+
+java_library(
+    name = "expr_util",
+    exports = ["//common/src/main/java/dev/cel/common/navigation:expr_util"],
+)
+
+cel_android_library(
+    name = "expr_util_android",
+    exports = ["//common/src/main/java/dev/cel/common/navigation:expr_util_android"],
+)

common/src/main/java/dev/cel/common/navigation/BUILD.bazel

@@ -48,6 +48,36 @@ cel_android_library(
     ],
 )
 
+java_library(
+    name = "expr_util",
+    srcs = [
+        "CelNavigableExprUtil.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":common",
+        "//common/ast",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+    ],
+)
+
+cel_android_library(
+    name = "expr_util_android",
+    srcs = [
+        "CelNavigableExprUtil.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":common_android",
+        "//common/ast:ast_android",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven_android//:com_google_guava_guava",
+    ],
+)
+
 java_library(
     name = "navigation",
     srcs = [

common/src/main/java/dev/cel/common/navigation/BaseNavigableExpr.java

@@ -16,6 +16,7 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.errorprone.annotations.CheckReturnValue;
+import com.google.errorprone.annotations.DoNotMock;
 import dev.cel.common.ast.CelExpr;
 import dev.cel.common.ast.CelExpr.ExprKind;
 import dev.cel.common.ast.Expression;
@@ -25,9 +26,15 @@
 /**
  * BaseNavigableExpr represents the base navigable expression value with methods to inspect the
  * parent and child expressions.
+ *
+ * <p>This class is intentionally non-extensible outside of the {@code dev.cel.common.navigation}
+ * package.
  */
+@DoNotMock("Use CelNavigableExpr or CelNavigableMutableExpr")
 @SuppressWarnings("unchecked") // Generic types are properly bound to Expression
-abstract class BaseNavigableExpr<E extends Expression> {
+public abstract class BaseNavigableExpr<E extends Expression> {
+
+  BaseNavigableExpr() {}
 
   public abstract E expr();
 

common/src/main/java/dev/cel/common/navigation/CelNavigableExprUtil.java

@@ -0,0 +1,102 @@
+// Copyright 2026 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.common.navigation;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.errorprone.annotations.CheckReturnValue;
+import dev.cel.common.ast.CelExpr.ExprKind.Kind;
+import dev.cel.common.ast.Expression;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Optional;
+
+/** Utility class for common AST navigation and scoping inspections on {@link BaseNavigableExpr}. */
+@CheckReturnValue
+public final class CelNavigableExprUtil {
+
+  /**
+   * Returns true if {@code variableName} is in scope and shadowed by an enclosing comprehension
+   * above {@code expr}.
+   */
+  public static boolean isVariableShadowed(BaseNavigableExpr<?> expr, String variableName) {
+    return areVariablesShadowed(expr, Collections.singleton(variableName));
+  }
+
+  /**
+   * Returns true if any of {@code variableNames} is in scope and shadowed by an enclosing
+   * comprehension above {@code expr}.
+   */
+  public static boolean areVariablesShadowed(
+      BaseNavigableExpr<?> expr, Collection<String> variableNames) {
+    checkNotNull(expr);
+    checkNotNull(variableNames);
+    if (variableNames.isEmpty()) {
+      return false;
+    }
+    BaseNavigableExpr<?> curr = expr;
+    Optional<? extends BaseNavigableExpr<?>> maybeParent = curr.parent();
+    while (maybeParent.isPresent()) {
+      BaseNavigableExpr<?> parent = maybeParent.get();
+      if (parent.getKind() == Kind.COMPREHENSION) {
+        Expression.Comprehension<?> comp = parent.expr().comprehension();
+        long currId = curr.id();
+        long iterRangeId = comp.iterRange().id();
+        long accuInitId = comp.accuInit().id();
+        long resultId = comp.result().id();
+
+        if (currId != iterRangeId && currId != accuInitId) {
+          if (currId == resultId) {
+            if (variableNames.contains(comp.accuVar())) {
+              return true;
+            }
+          } else {
+            if (variableNames.contains(comp.iterVar())
+                || variableNames.contains(comp.iterVar2())
+                || variableNames.contains(comp.accuVar())) {
+              return true;
+            }
+          }
+        }
+      }
+      curr = parent;
+      maybeParent = parent.parent();
+    }
+    return false;
+  }
+
+  /**
+   * Returns true if {@code expr} is an {@code IDENT} node that references a variable declared by an
+   * enclosing comprehension.
+   */
+  public static boolean isComprehensionVariable(BaseNavigableExpr<?> expr) {
+    checkNotNull(expr);
+    return expr.getKind() == Kind.IDENT
+        && areVariablesShadowed(expr, Collections.singleton(expr.expr().ident().name()));
+  }
+
+  /**
+   * Returns true if {@code expr} or any identifier within {@code expr} references a variable
+   * declared by an enclosing comprehension.
+   */
+  public static boolean hasComprehensionVariable(BaseNavigableExpr<?> expr) {
+    checkNotNull(expr);
+    return expr.allNodes()
+        .filter(node -> node.getKind() == Kind.IDENT)
+        .anyMatch(CelNavigableExprUtil::isComprehensionVariable);
+  }
+
+  private CelNavigableExprUtil() {}
+}

common/src/test/java/dev/cel/common/navigation/BUILD.bazel

@@ -21,6 +21,7 @@ java_library(
         "//common/ast:mutable_expr",
         "//common/navigation",
         "//common/navigation:common",
+        "//common/navigation:expr_util",
         "//common/navigation:mutable_navigation",
         "//common/types",
         "//compiler",