Support a Metapath execution stack (#336)

* Added support for an execution stack on the DynamicContext that tracks the expressions entered and exited during Metapath evaluation. This will be useful context for debugging and error reporting.
* Fixed typo.

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/DynamicContext.java

@@ -17,26 +17,32 @@
 import gov.nist.secauto.metaschema.core.metapath.item.node.IDocumentNodeItem;
 import gov.nist.secauto.metaschema.core.model.IUriResolver;
 import gov.nist.secauto.metaschema.core.qname.IEnhancedQName;
+import gov.nist.secauto.metaschema.core.util.CollectionUtil;
 import gov.nist.secauto.metaschema.core.util.ObjectUtils;
 
 import java.io.IOException;
 import java.net.URI;
 import java.time.Clock;
 import java.time.ZoneId;
 import java.time.ZonedDateTime;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
 import java.util.Collections;
+import java.util.Deque;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
 // TODO: add support for in-scope namespaces
 /**
- * The implementation of a Metapath
- * <a href="https://www.w3.org/TR/xpath-31/#eval_context">dynamic context</a>.
+ * The implementation of a Metapath <a href="https://www.w3.org/TR/xpath-31/#eval_context">dynamic
+ * context</a>.
  */
 public class DynamicContext { // NOPMD - intentional data class
   @NonNull
@@ -82,6 +88,8 @@ private static class SharedState {
     private CachingLoader documentLoader;
     @NonNull
     private final IMutableConfiguration<MetapathEvaluationFeature<?>> configuration;
+    @NonNull
+    private final Deque<IExpression> executionStack = new ArrayDeque<>();
 
     public SharedState(@NonNull StaticContext staticContext) {
       this.staticContext = staticContext;
@@ -103,10 +111,9 @@ public SharedState(@NonNull StaticContext staticContext) {
   /**
    * Generate a new dynamic context that is a copy of this dynamic context.
    * <p>
-   * This method can be used to create a new sub-context where changes can be made
-   * without affecting this context. This is useful for setting information that
-   * is only used in a limited evaluation sub-scope, such as for handling variable
-   * assignment.
+   * This method can be used to create a new sub-context where changes can be made without affecting
+   * this context. This is useful for setting information that is only used in a limited evaluation
+   * sub-scope, such as for handling variable assignment.
    *
    * @return a new dynamic context
    */
@@ -146,8 +153,7 @@ public ZonedDateTime getCurrentDateTime() {
   }
 
   /**
-   * Get the mapping of loaded documents from the document URI to the document
-   * node.
+   * Get the mapping of loaded documents from the document URI to the document node.
    *
    * @return the map of document URIs to document nodes
    */
@@ -162,8 +168,7 @@ public Map<URI, IDocumentNodeItem> getAvailableDocuments() {
    *
    * @return the loader
    * @throws DynamicMetapathException
-   *           with an error code
-   *           {@link DynamicMetapathException#DYNAMIC_CONTEXT_ABSENT} if a
+   *           with an error code {@link DynamicMetapathException#DYNAMIC_CONTEXT_ABSENT} if a
    *           document loader is not configured for this dynamic context
    */
   @NonNull
@@ -187,12 +192,11 @@ public void setDocumentLoader(@NonNull IDocumentLoader documentLoader) {
   }
 
   /**
-   * Get the cached function call result for evaluating a function that has the
-   * property {@link FunctionProperty#DETERMINISTIC}.
+   * Get the cached function call result for evaluating a function that has the property
+   * {@link FunctionProperty#DETERMINISTIC}.
    *
    * @param callingContext
-   *          the function calling context information that distinguishes the call
-   *          from any other call
+   *          the function calling context information that distinguishes the call from any other call
    * @return the cached result sequence for the function call
    */
   @Nullable
@@ -201,12 +205,10 @@ public ISequence<?> getCachedResult(@NonNull CalledContext callingContext) {
   }
 
   /**
-   * Cache a function call result for a that has the property
-   * {@link FunctionProperty#DETERMINISTIC}.
+   * Cache a function call result for a that has the property {@link FunctionProperty#DETERMINISTIC}.
    *
    * @param callingContext
-   *          the calling context information that distinguishes the call from any
-   *          other call
+   *          the calling context information that distinguishes the call from any other call
    * @param result
    *          the function call result
    */
@@ -216,12 +218,10 @@ public void cacheResult(@NonNull CalledContext callingContext, @NonNull ISequenc
   }
 
   /**
-   * Used to disable the evaluation of predicate expressions during Metapath
-   * evaluation.
+   * Used to disable the evaluation of predicate expressions during Metapath evaluation.
    * <p>
-   * This can be useful for determining the potential targets identified by a
-   * Metapath expression as a partial evaluation, without evaluating that these
-   * targets match the predicate.
+   * This can be useful for determining the potential targets identified by a Metapath expression as a
+   * partial evaluation, without evaluating that these targets match the predicate.
    *
    * @return this dynamic context
    */
@@ -232,8 +232,7 @@ public DynamicContext disablePredicateEvaluation() {
   }
 
   /**
-   * Used to enable the evaluation of predicate expressions during Metapath
-   * evaluation.
+   * Used to enable the evaluation of predicate expressions during Metapath evaluation.
    * <p>
    * This is the default behavior if unchanged.
    *
@@ -256,15 +255,13 @@ public IConfiguration<MetapathEvaluationFeature<?>> getConfiguration() {
   }
 
   /**
-   * Get the sequence value assigned to a let variable with the provided qualified
-   * name.
+   * Get the sequence value assigned to a let variable with the provided qualified name.
    *
    * @param name
    *          the variable qualified name
    * @return the non-null variable value
    * @throws MetapathException
-   *           of the variable has not been assigned or if the variable value is
-   *           {@code null}
+   *           of the variable has not been assigned or if the variable value is {@code null}
    */
   @NonNull
   public ISequence<?> getVariableValue(@NonNull IEnhancedQName name) {
@@ -289,8 +286,8 @@ public ISequence<?> getVariableValue(@NonNull IEnhancedQName name) {
    *          the number of arguments in the requested function
    * @return the function
    * @throws StaticMetapathException
-   *           with the code {@link StaticMetapathException#NO_FUNCTION_MATCH} if
-   *           a matching function was not found
+   *           with the code {@link StaticMetapathException#NO_FUNCTION_MATCH} if a matching function
+   *           was not found
    */
   @NonNull
   public IFunction getFunction(@NonNull IEnhancedQName name, int arity) {
@@ -312,6 +309,51 @@ public DynamicContext bindVariableValue(@NonNull IEnhancedQName name, @NonNull I
     return this;
   }
 
+  /**
+   * Push the current expression under evaluation to the execution queue.
+   *
+   * @param expression
+   *          the expression to push
+   */
+  public void pushExecutionStack(@NonNull IExpression expression) {
+    this.sharedState.executionStack.push(expression);
+  }
+
+  /**
+   * Pop the expression that was under evaluation from the execution queue.
+   *
+   * @param expression
+   *          the expected expression to be popped
+   */
+  public void popExecutionStack(@NonNull IExpression expression) {
+    IExpression popped = this.sharedState.executionStack.pop();
+    if (!expression.equals(popped)) {
+        throw new IllegalStateException("Popped expression does not match expected expression");
+    }
+  }
+
+  /**
+   * Return a copy of the current execution stack.
+   *
+   * @return the execution stack
+   */
+  @NonNull
+  public List<IExpression> getExecutionStack() {
+    return CollectionUtil.unmodifiableList(new ArrayList<>(this.sharedState.executionStack));
+  }
+
+  /**
+   * Provides a formatted stack trace.
+   *
+   * @return the formatted stack trace
+   */
+  @NonNull
+  public String formatExecutionStackTrace() {
+    return ObjectUtils.notNull(getExecutionStack().stream()
+        .map(IExpression::toCSTString)
+        .collect(Collectors.joining("\n-> ")));
+  }
+
   private class CachingLoader implements IDocumentLoader {
     @NonNull
     private final IDocumentLoader proxy;
@@ -351,8 +393,7 @@ public class ContextUriResolver implements IUriResolver {
       /**
        * {@inheritDoc}
        * <p>
-       * This method first resolves the provided URI against the static context's base
-       * URI.
+       * This method first resolves the provided URI against the static context's base URI.
        */
       @Override
       public URI resolve(URI uri) {
@@ -370,5 +411,4 @@ public URI resolve(URI uri) {
       }
     }
   }
-
 }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/IExpression.java → core/src/main/java/gov/nist/secauto/metaschema/core/metapath/IExpression.java

@@ -3,9 +3,9 @@
  * SPDX-License-Identifier: CC0-1.0
  */
 
-package gov.nist.secauto.metaschema.core.metapath.cst;
+package gov.nist.secauto.metaschema.core.metapath;
 
-import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.IItem;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
 
@@ -77,7 +77,7 @@ default Class<? extends IItem> getStaticResultType() {
    */
   @SuppressWarnings("null")
   @NonNull
-  default String toASTString() {
+  default String toCSTString() {
     return String.format("%s[]", getClass().getName());
   }
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/MetapathExpression.java

@@ -11,7 +11,6 @@
 import gov.nist.secauto.metaschema.core.metapath.antlr.ParseTreePrinter;
 import gov.nist.secauto.metaschema.core.metapath.cst.BuildCSTVisitor;
 import gov.nist.secauto.metaschema.core.metapath.cst.CSTPrinter;
-import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.path.ContextItem;
 import gov.nist.secauto.metaschema.core.metapath.item.IItem;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
@@ -163,12 +162,12 @@ public String getPath() {
   }
 
   /**
-   * Get the compiled abstract syntax tree (AST) representation of the Metapath.
+   * Get the compiled compact syntax tree (CST) representation of the Metapath.
    *
-   * @return the Metapath AST
+   * @return the Metapath CST
    */
   @NonNull
-  protected IExpression getASTNode() {
+  protected IExpression getCSTNode() {
     return expression;
   }
 
@@ -179,7 +178,7 @@ public StaticContext getStaticContext() {
 
   @Override
   public String toString() {
-    return CSTPrinter.toString(getASTNode());
+    return CSTPrinter.toString(getCSTNode());
   }
 
   @Override
@@ -188,7 +187,7 @@ public <T extends IItem> ISequence<T> evaluate(
       @Nullable IItem focus,
       @NonNull DynamicContext dynamicContext) {
     try {
-      return ObjectUtils.asType(getASTNode().accept(dynamicContext, ISequence.of(focus)).reusable());
+      return ObjectUtils.asType(getCSTNode().accept(dynamicContext, ISequence.of(focus)).reusable());
     } catch (MetapathException ex) {
       throw new MetapathException(
           String.format("An error occurred while evaluating the expression '%s'. %s",

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractBinaryExpression.java

@@ -5,6 +5,8 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
+
 import java.util.List;
 import java.util.Objects;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractCSTVisitorBase.java

@@ -5,6 +5,7 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.StaticContext;
 import gov.nist.secauto.metaschema.core.metapath.StaticMetapathException;
 import gov.nist.secauto.metaschema.core.metapath.antlr.AbstractAstVisitor;

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractExpression.java

@@ -5,6 +5,11 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
+import gov.nist.secauto.metaschema.core.metapath.item.IItem;
+import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
+
 import edu.umd.cs.findbugs.annotations.NonNull;
 
 /**
@@ -34,4 +39,28 @@ public String getText() {
   public String toString() {
     return CSTPrinter.toString(this);
   }
+
+  @Override
+  public ISequence<?> accept(DynamicContext dynamicContext, ISequence<?> focus) {
+    dynamicContext.pushExecutionStack(this);
+    try {
+      return evaluate(dynamicContext, focus);
+    } finally {
+      dynamicContext.popExecutionStack(this);
+    }
+  }
+
+  /**
+   * Evaluate this expression, producing a sequence result.
+   *
+   * @param dynamicContext
+   *          the dynamic evaluation context
+   * @param focus
+   *          the outer focus of the expression
+   * @return the result of evaluation
+   */
+  @NonNull
+  protected abstract ISequence<? extends IItem> evaluate(
+      @NonNull DynamicContext dynamicContext,
+      @NonNull ISequence<?> focus);
 }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractExpressionVisitor.java

@@ -5,6 +5,7 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.items.ArraySequenceConstructor;
 import gov.nist.secauto.metaschema.core.metapath.cst.items.ArraySquareConstructor;
 import gov.nist.secauto.metaschema.core.metapath.cst.items.DecimalLiteral;

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractNAryExpression.java

@@ -5,6 +5,8 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
+
 import java.util.List;
 import java.util.Objects;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractUnaryExpression.java

@@ -5,6 +5,8 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
+import gov.nist.secauto.metaschema.core.metapath.IExpression;
+
 import java.util.List;
 import java.util.Objects;