Setup of the coverage index.

PiperOrigin-RevId: 805684099

Author: ChinmayMadeshi

parser/src/main/java/dev/cel/parser/CelUnparserVisitor.java

@@ -66,6 +66,11 @@ public String unparse() {
     return stringBuilder.toString();
   }
 
+  public String unparse(CelExpr expr) {
+    visit(expr);
+    return stringBuilder.toString();
+  }
+
   private static String maybeQuoteField(String field) {
     if (RESTRICTED_FIELD_NAMES.contains(field)
         || !IDENTIFIER_SEGMENT_PATTERN.matcher(field).matches()) {

testing/src/main/java/dev/cel/testing/testrunner/BUILD.bazel

@@ -15,6 +15,7 @@ java_library(
     ],
     deps = [
         ":annotations",
+        ":cel_coverage_index",
         ":cel_test_suite",
         ":cel_test_suite_exception",
         ":cel_test_suite_text_proto_parser",
@@ -33,7 +34,11 @@ java_library(
     srcs = ["JUnitXmlReporter.java"],
     tags = [
     ],
-    deps = ["@maven//:com_google_guava_guava"],
+    deps = [
+        ":cel_coverage_index",
+        "@maven//:com_google_guava_guava",
+        "@maven//:org_jspecify_jspecify",
+    ],
 )
 
 java_library(
@@ -42,11 +47,31 @@ java_library(
     tags = [
     ],
     deps = [
+        ":cel_coverage_index",
         ":cel_expression_source",
         ":cel_test_context",
         ":cel_test_suite",
         ":test_runner_library",
         "@maven//:junit_junit",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+java_library(
+    name = "cel_coverage_index",
+    srcs = ["CelCoverageIndex.java"],
+    tags = [
+    ],
+    deps = [
+        "//common:cel_ast",
+        "//common/ast",
+        "//common/navigation",
+        "//common/types:type_providers",
+        "//parser:unparser_visitor",
+        "//runtime:evaluation_listener",
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
     ],
 )
 
@@ -56,6 +81,7 @@ java_library(
     tags = [
     ],
     deps = [
+        ":cel_coverage_index",
         ":cel_expression_source",
         ":cel_test_context",
         ":cel_test_suite",
@@ -80,6 +106,7 @@ java_library(
         "@cel_spec//proto/cel/expr:expr_java_proto",
         "@maven//:com_google_guava_guava",
         "@maven//:com_google_protobuf_protobuf_java",
+        "@maven//:org_jspecify_jspecify",
     ],
 )
 

testing/src/main/java/dev/cel/testing/testrunner/CelCoverageIndex.java

@@ -0,0 +1,231 @@
+// 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.testing.testrunner;
+
+import static com.google.common.collect.ImmutableList.toImmutableList;
+
+import javax.annotation.concurrent.ThreadSafe;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.ast.CelExpr;
+import dev.cel.common.ast.CelExpr.ExprKind;
+import dev.cel.common.navigation.CelNavigableAst;
+import dev.cel.common.navigation.CelNavigableExpr;
+import dev.cel.common.types.CelKind;
+import dev.cel.parser.CelUnparserVisitor;
+import dev.cel.runtime.CelEvaluationListener;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import java.util.logging.Logger;
+
+/**
+ * A class for managing the coverage index for CEL tests.
+ *
+ * <p>This class is used to manage the coverage index for CEL tests. It provides a method for
+ * getting the coverage index for a given test case.
+ */
+final class CelCoverageIndex {
+
+  private static final Logger logger = Logger.getLogger(CelCoverageIndex.class.getName());
+
+  private CelAbstractSyntaxTree ast;
+  private final Map<Long, NodeCoverageStats> nodeCoverageStatsMap = new HashMap<>();
+
+  public void setAst(CelAbstractSyntaxTree ast) {
+    this.ast = ast;
+    CelNavigableExpr.fromExpr(ast.getExpr())
+        .allNodes()
+        .forEach(
+            celNavigableExpr -> {
+              NodeCoverageStats nodeCoverageStats = new NodeCoverageStats();
+              nodeCoverageStats.isBooleanNode = inferBooleanNodeType(celNavigableExpr.expr());
+              nodeCoverageStatsMap.put(celNavigableExpr.id(), nodeCoverageStats);
+            });
+  }
+
+  /**
+   * Returns the evaluation listener for the CEL test suite.
+   *
+   * <p>This listener is used to track the coverage of the CEL test suite.
+   */
+  public CelEvaluationListener getEvaluationListener() {
+    return new EvaluationListener(nodeCoverageStatsMap);
+  }
+
+  /** Returns the coverage report for the CEL test suite. */
+  public CoverageReport getCoverageReport() {
+    CoverageReport report = new CoverageReport();
+    traverseAndCalculateCoverage(
+        CelNavigableAst.fromAst(ast).getRoot(), nodeCoverageStatsMap, true, "", report);
+    report.celExpr = new CelUnparserVisitor(ast).unparse(ast.getExpr());
+    logger.info("CEL Expression: " + report.celExpr);
+    logger.info("Nodes: " + report.nodes);
+    logger.info("Covered Nodes: " + report.coveredNodes);
+    logger.info("Branches: " + report.branches);
+    logger.info("Covered Boolean Outcomes: " + report.coveredBooleanOutcomes);
+    logger.info("Unencountered Nodes: \n" + String.join("\n", report.unencounteredNodes));
+    logger.info("Unencountered Branches: \n" + String.join("\n", report.unencounteredBranches));
+    return report;
+  }
+
+
+  /** A class for managing the coverage report for a CEL test suite. */
+  public static final class CoverageReport {
+    String celExpr;
+    long nodes = 0L;
+    long coveredNodes = 0L;
+    long branches = 0L;
+    long coveredBooleanOutcomes = 0L;
+    List<String> unencounteredNodes = new ArrayList<>();
+    List<String> unencounteredBranches = new ArrayList<>();
+  }
+
+  /** A class for managing the coverage stats for a CEL node. */
+  private static final class NodeCoverageStats {
+    Boolean isBooleanNode;
+    Boolean covered = false;
+    Boolean hasTrueBranch = false;
+    Boolean hasFalseBranch = false;
+  }
+
+  private Boolean inferBooleanNodeType(CelExpr celExpr) {
+    return ast.getTypeMap().containsKey(celExpr.id())
+        && ast.getTypeMap().get(celExpr.id()).kind().equals(CelKind.BOOL);
+  }
+
+  private void traverseAndCalculateCoverage(
+      CelNavigableExpr node,
+      Map<Long, NodeCoverageStats> statsMap,
+      boolean logUnencountered,
+      String precedingTabs,
+      CoverageReport report) {
+    long nodeId = node.id();
+    NodeCoverageStats stats = statsMap.getOrDefault(nodeId, new NodeCoverageStats());
+    report.nodes++;
+
+    boolean isInterestingBooleanNode = isInterestingBooleanNode(node, stats);
+
+    // Only unparse if the node is interesting (boolean node) and we need to log
+    // unencountered nodes.
+    String exprText = "";
+    if (isInterestingBooleanNode && logUnencountered) {
+      exprText = new CelUnparserVisitor(ast).unparse(node.expr());
+    }
+
+    // Update coverage for the current node and determine if we should continue logging unencountered.
+    logUnencountered = updateNodeCoverage(nodeId, stats, isInterestingBooleanNode, exprText, logUnencountered, report);
+
+    if (isInterestingBooleanNode) {
+      precedingTabs = updateBooleanBranchCoverage(nodeId, stats, exprText, precedingTabs, logUnencountered, report);
+    }
+
+    for (CelNavigableExpr child : node.children().collect(toImmutableList())) {
+      traverseAndCalculateCoverage(child, statsMap, logUnencountered, precedingTabs, report);
+    }
+  }
+
+  private boolean isInterestingBooleanNode(CelNavigableExpr node, NodeCoverageStats stats) {
+    return stats.isBooleanNode
+        && !node.expr().getKind().equals(ExprKind.Kind.CONSTANT)
+        && !(node.expr().getKind().equals(ExprKind.Kind.CALL)
+            && node.expr().call().function().equals("cel.@block"));
+  }
+
+  /**
+   * Updates the coverage report based on whether the current node was covered.
+   * Returns true if logging of unencountered nodes should continue for children, false otherwise.
+   */
+  private boolean updateNodeCoverage(
+      long nodeId,
+      NodeCoverageStats stats,
+      boolean isInterestingBooleanNode,
+      String exprText,
+      boolean logUnencountered,
+      CoverageReport report) {
+    if (stats.covered) {
+      report.coveredNodes++;
+      return logUnencountered;
+    } else {
+      if (logUnencountered) {
+        if (isInterestingBooleanNode) {
+          report.unencounteredNodes.add(String.format("Expression ID %d ('%s')", nodeId, exprText));
+        }
+        // Once an unencountered node is found, we don't log further unencountered nodes in its
+        // subtree to avoid noise.
+        return false;
+      }
+      return logUnencountered;
+    }
+  }
+
+  /**
+   * Updates the coverage report for boolean nodes, including branch coverage.
+   * Returns the potentially modified `precedingTabs` string.
+   */
+  private String updateBooleanBranchCoverage(
+      long nodeId,
+      NodeCoverageStats stats,
+      String exprText,
+      String precedingTabs,
+      boolean logUnencountered,
+      CoverageReport report) {
+    report.branches += 2;
+    if (stats.hasTrueBranch) {
+      report.coveredBooleanOutcomes++;
+    } else if (logUnencountered) {
+      report.unencounteredBranches.add(
+          String.format(
+              "%sExpression ID %d ('%s'): Never evaluated to 'true'",
+              precedingTabs, nodeId, exprText));
+      precedingTabs += "\t\t";
+    }
+    if (stats.hasFalseBranch) {
+      report.coveredBooleanOutcomes++;
+    } else if (logUnencountered) {
+      report.unencounteredBranches.add(
+          String.format(
+              "%sExpression ID %d ('%s'): Never evaluated to 'false'",
+              precedingTabs, nodeId, exprText));
+      precedingTabs += "\t\t";
+    }
+    return precedingTabs;
+  }
+
+  @ThreadSafe
+  private static final class EvaluationListener implements CelEvaluationListener {
+
+    private final Map<Long, NodeCoverageStats> nodeCoverageStatsMap;
+
+    EvaluationListener(Map<Long, NodeCoverageStats> nodeCoverageStatsMap) {
+      this.nodeCoverageStatsMap = nodeCoverageStatsMap;
+    }
+
+    @Override
+    public void callback(CelExpr celExpr, Object evaluationResult) {
+      NodeCoverageStats nodeCoverageStats = nodeCoverageStatsMap.get(celExpr.id());
+      nodeCoverageStats.covered = true;
+      if (nodeCoverageStats.isBooleanNode) {
+        if (evaluationResult instanceof Boolean) {
+          if ((Boolean) evaluationResult) {
+            nodeCoverageStats.hasTrueBranch = true;
+          } else {
+            nodeCoverageStats.hasFalseBranch = true;
+          }
+        }
+      }
+    }
+  }
+}

testing/src/main/java/dev/cel/testing/testrunner/CelUserTestTemplate.java

@@ -15,6 +15,7 @@
 package dev.cel.testing.testrunner;
 
 import dev.cel.testing.testrunner.CelTestSuite.CelTestSection.CelTestCase;
+import org.jspecify.annotations.Nullable;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.Parameterized;
@@ -27,7 +28,12 @@
 @RunWith(Parameterized.class)
 public abstract class CelUserTestTemplate {
 
-  @Parameter public CelTestCase testCase;
+  @Parameter(0)
+  public CelTestCase testCase;
+
+  @Parameter(1)
+  public @Nullable CelCoverageIndex celCoverageIndex;
+
   private final CelTestContext celTestContext;
 
   public CelUserTestTemplate(CelTestContext celTestContext) {
@@ -36,7 +42,11 @@ public CelUserTestTemplate(CelTestContext celTestContext) {
 
   @Test
   public void test() throws Exception {
-    TestRunnerLibrary.runTest(testCase, updateCelTestContext(celTestContext));
+    if (celCoverageIndex != null) {
+      TestRunnerLibrary.runTest(testCase, updateCelTestContext(celTestContext), celCoverageIndex);
+    } else {
+      TestRunnerLibrary.runTest(testCase, updateCelTestContext(celTestContext));
+    }
   }
 
   /**