@getodk/xforms-engine 0.2.0 → 0.4.0

package/src/parse/xpath/dependency-analysis.ts

@@ -0,0 +1,105 @@
+import { expressionParser } from '@getodk/xpath/expressionParser.js';
+import {
+	resolvePath,
+	resolvePredicateReference,
+	serializeNodesetReference,
+} from './path-resolution.ts';
+import { findPredicateReferences } from './predicate-analysis.ts';
+import type { PathExpressionNode } from './semantic-analysis.ts';
+import { findLocationPathSubExpressionNodes, getPathExpressionNode } from './semantic-analysis.ts';
+
+export interface PathResolutionOptions {
+	/**
+	 * Excludes direct references to the nodeset specified as a context. This flag
+	 * has earlier precedent as `ignoreContextReference` in similar internal APIs.
+	 * The intent, in part, is to allow for certain in-spec exceptions to cycle
+	 * analysis (which we previously did explicitly, and foresee reintroducing in
+	 * some form relatively soon). As such, the default for this flag should be
+	 * overridden when a computation is (A) not among the core `<bind>`
+	 * computations or (B) is a computation which is explicitly expected to have
+	 * self-references (such as `constraint`).
+	 *
+	 * @default false
+	 *
+	 * @todo It is highly likely we will eliminate this in the future. We
+	 * considered removing its precursor (and existing code now referencing this)
+	 * in {@link https://github.com/getodk/web-forms/pull/67}, but ran into issues
+	 * with some of the reactive logic introduced there. It's likely that
+	 * subsequent improvements have addressed those issues, but it's also likely
+	 * that we will want similar special casing when we reintroduce explicit graph
+	 * cycle analysis.
+	 */
+	readonly ignoreReferenceToContextPath?: boolean;
+}
+
+const defaultPathResolutionOptions: Required<PathResolutionOptions> = {
+	ignoreReferenceToContextPath: false,
+};
+
+/**
+ * Resolves XPath paths referenced by an arbitrary expression to XForms
+ * `nodeset` references:
+ *
+ * 1. The provided {@link expression} is analyzed to find path sub-expressions
+ *    (LocationPaths, sub-expressions with a node-set producing FilterExpr).
+ *
+ * 2. When a {@link contextNodeset} is available, each sub-expression is
+ *    resolved to that context. See {@link resolvePath} for additional
+ *    detail.
+ *
+ * 3. Once resolved, each dependency path is further analyzed to identify
+ *    sub-expressions in any of its predicates, resolving each to their
+ *    respective predicates' Steps. See {@link resolvePredicateReference} for
+ *    additional detail.
+ */
+export const resolveDependencyNodesets = (
+	contextNodeset: string | null,
+	expression: string,
+	options: PathResolutionOptions = {}
+): readonly string[] => {
+	const { ignoreReferenceToContextPath } = {
+		...defaultPathResolutionOptions,
+		...options,
+	};
+
+	let contextNode: PathExpressionNode | null = null;
+
+	if (contextNodeset != null) {
+		contextNode = getPathExpressionNode(contextNodeset);
+	}
+
+	const expressionRootNode = expressionParser.parse(expression).rootNode;
+	const subExpressions = findLocationPathSubExpressionNodes(expressionRootNode);
+
+	const resolvedPathLists = subExpressions.flatMap((subExpression) => {
+		const pathNodes = resolvePath(contextNode, subExpression);
+		const predicateReferences = findPredicateReferences(pathNodes);
+		const resolvedPredicateReferences = predicateReferences.map((reference) => {
+			return resolvePredicateReference(
+				contextNode,
+				reference.stepContextNodes,
+				reference.predicatePathNode
+			);
+		});
+
+		return [pathNodes, ...resolvedPredicateReferences];
+	});
+
+	const serializedPaths = Array.from(
+		new Set(
+			resolvedPathLists.map((resolvedPathList) => {
+				return serializeNodesetReference(resolvedPathList, {
+					stripPredicates: true,
+				});
+			})
+		)
+	);
+
+	if (ignoreReferenceToContextPath) {
+		return serializedPaths.filter((result) => {
+			return result !== contextNodeset;
+		});
+	}
+
+	return serializedPaths;
+};

package/src/parse/xpath/path-resolution.ts

@@ -0,0 +1,475 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type {
+	AbsoluteLocationPathNode,
+	AbsoluteRootLocationPathNode,
+	FilterExprNode,
+	PredicateNode,
+	RelativeStepSyntaxLiteralNode,
+	StepNode,
+} from '@getodk/xpath/static/grammar/SyntaxNode.js';
+import type { PathExpressionNode } from './semantic-analysis.ts';
+import { isCurrentPath } from './semantic-analysis.ts';
+
+type AbsolutePathHead =
+	/** / - as first character in LocationPath */
+	| AbsoluteRootLocationPathNode
+
+	/** // - as first characters in LocationPath */
+	| RelativeStepSyntaxLiteralNode;
+
+/**
+ * fn(...args) - as first (and potentially only) part of a path expression,
+ * where the function is either known to produce a node-set result, or where
+ * other aspects of the exression's syntax are inherently node-set producing.
+ */
+type FilterPathExprHead = FilterExprNode;
+
+type StepLikeNode =
+	/** // - shorthand for `/descendant-or-self::node()/`  */
+	| RelativeStepSyntaxLiteralNode
+
+	/** Any _actual_ Step in a LocationPath */
+	| StepNode;
+
+type PathNodeListHead = AbsolutePathHead | FilterPathExprHead | StepLikeNode;
+
+/**
+ * A path node list is a semi-flattened representation of...
+ *
+ * - Any XPath LocationPath expression:
+ *   - AbsoluteLocationPath
+ *   - RelativeLocationPath
+ *
+ * - Any expression beginning with a FilterExpr which is known to produce a
+ *   node-set result
+ *
+ * The flattening of these syntax representations is used to perform various
+ * aspects of path resolution logic, accounting for complexities of XPath syntax
+ * and semantics in a roughly linear/list processing manner.
+ */
+// prettier-ignore
+export type PathNodeList<
+	Head extends PathNodeListHead = PathNodeListHead
+> = readonly [
+	head: Head,
+	...tail: StepLikeNode[]
+];
+
+/**
+ * Produces a semi-flattened representation of an AbsoluteLocationPath.
+ *
+ * @see {@link PathNodeList}
+ */
+const absolutePathNodeList = (
+	pathNode: AbsoluteLocationPathNode
+): PathNodeList<AbsolutePathHead> => {
+	const [head, ...tail] = pathNode.children;
+
+	switch (head.type) {
+		case 'abbreviated_absolute_location_path': {
+			return head.children;
+		}
+
+		case 'absolute_root_location_path':
+			return [head, ...tail];
+
+		default:
+			throw new UnreachableError(head);
+	}
+};
+
+const pathNodeList = (pathNode: PathExpressionNode): PathNodeList => {
+	switch (pathNode.type) {
+		case 'absolute_location_path':
+			return absolutePathNodeList(pathNode);
+
+		case 'filter_path_expr':
+			return pathNode.children satisfies PathNodeList<FilterExprNode>;
+
+		case 'relative_location_path':
+			return pathNode.children satisfies PathNodeList<StepLikeNode>;
+
+		default:
+			throw new UnreachableError(pathNode);
+	}
+};
+
+const optionalPathNodeList = (pathNode: PathExpressionNode | null): PathNodeList | null => {
+	if (pathNode == null) {
+		return null;
+	}
+
+	return pathNodeList(pathNode);
+};
+
+type UnresolvedContextualizedPathListNode = FilterExprNode | StepLikeNode;
+
+/**
+ * Like {@link PathNodeList}, provides a semi-flattened representation of path
+ * syntax. Distinct from that type, an unresolved list represents an
+ * intermediate concatenation of:
+ *
+ * - A **contextual** {@link PathNodeList} against which the to-be-resolved path
+ *   will eventually be resolved.
+ *
+ * - The same structural representation of the to-be-resolved path.
+ */
+type UnresolvedPathNodeList = readonly [
+	head: PathNodeListHead,
+	...tail: UnresolvedContextualizedPathListNode[],
+];
+
+type ResolvableTraversalType = 'parent' | 'self';
+
+const abbreviatedStepTextToResolvableStepType = {
+	'..': 'parent',
+	'.': 'self',
+} as const satisfies Record<string, ResolvableTraversalType>;
+
+const getResolvableTraversalType = (syntaxNode: StepNode): ResolvableTraversalType | null => {
+	const [stepTest, ...predicates] = syntaxNode.children;
+
+	// Ensure that we preserve self/parent traversal Steps with predicates
+	if (predicates.length > 0) {
+		return null;
+	}
+
+	if (stepTest.type === 'abbreviated_step') {
+		return abbreviatedStepTextToResolvableStepType[stepTest.text];
+	}
+
+	if (stepTest.type !== 'axis_test' || predicates.length > 0) {
+		return null;
+	}
+
+	const [axisNameNode, axisTest] = stepTest.children;
+	const axisName = axisNameNode.text;
+
+	if (axisName !== 'parent' && axisName !== 'self') {
+		return null;
+	}
+
+	const axisTestType = axisTest.type;
+
+	if (
+		// `self::*`, `parent::*`
+		axisTestType === 'unprefixed_wildcard_name_test' ||
+		// `self::node()`, `parent::node()`
+		(axisTestType === 'node_type_test' && axisTest.text.startsWith('node'))
+	) {
+		return axisName;
+	}
+
+	return null;
+};
+
+/**
+ * Resolves the component parts of an XPath LocationPath/path-like expression
+ * (as represented by an {@link UnresolvedPathNodeList}
+ */
+const resolvePathNodeList = (nodes: UnresolvedPathNodeList): PathNodeList => {
+	const [head, ...tail] = nodes;
+	const lastTailIndex = tail.length - 1;
+
+	// Local representation, mutable during resolution
+	type PathNodeResolution = [...PathNodeList];
+
+	return tail.reduce<PathNodeResolution>(
+		(acc, node, index) => {
+			// Because we've filtered non-`current()` cases before we reach this point,
+			// we can safely assume this is a `current()` call. For resolving **nodeset
+			// references** specifically, we treat this as equivalent to `.`.
+			//
+			// TODO: can we make this check/result more self-documenting, and reduce
+			// coupling with the `current()` check? Probably! We could move the check
+			// here, returning `acc` for `current()`, and returning `[node]` (i.e.
+			// establishing a new absolute-like context) otherwise. It seems like we
+			// could even do a similar check for the actual AbsoluteLocationPath case,
+			// and probably eliminate a bunch of the special cases in the main
+			// `resolvePathExpression` body.
+			if (node.type === 'filter_expr') {
+				return acc;
+			}
+
+			const [currentHead, ...currentTail] = acc;
+
+			// Special case `//` shorthand (1):
+			if (
+				// - Current accumulated path is a single head node.
+				currentTail.length === 0 &&
+				// - Head is `//` shorthand.
+				currentHead.type === '//' &&
+				// - Current node is last in source expression.
+				index === lastTailIndex
+			) {
+				// Even if current node could otherwise be resolved, we must append
+				// because `//` without a following Step-like node does not produce a
+				// valid XPath expression.
+				acc.push(node);
+
+				return acc;
+			}
+
+			// Special case `//` shorthand (2):
+			//
+			// Current node is `//`, and will be guaranteed (by `tree-sitter-xpath`
+			// grammar) to be followed by a valid Step-like node. Append and continue.
+			if (node.type === '//') {
+				acc.push(node);
+
+				return acc;
+			}
+
+			// Any further cases are Step syntax
+			node satisfies StepNode;
+
+			const traversalType = getResolvableTraversalType(node);
+
+			if (traversalType == null) {
+				acc.push(node);
+
+				return acc;
+			}
+
+			if (traversalType === 'self') {
+				return acc;
+			}
+
+			// All further cases are parent traversal, which we will resolve where
+			// possible. Each variation is detailed below.
+			traversalType satisfies 'parent';
+
+			// For our resolution purposes, the following expressions are
+			// functionally equivalent:
+			//
+			// - `$head/$currentTail/$Step-like/..`
+			// - `$head/$currentTail`
+			//
+			// As such, when we encounter `..` which is currently preceded by
+			// any non-head, Step-like node, we can remove that trailing node
+			// rather than appending `..`.
+			//
+			// Note: `$head/..` (without any intervening Step-like nodes) is
+			// more complicated. It is handled below, explaining each case in
+			// greater detail.
+			if (currentTail.length > 0) {
+				return [currentHead, ...currentTail.slice(0, -1)];
+			}
+
+			// Resolving `$head/..`, with no intervening Step-like nodes...
+			switch (currentHead.type) {
+				// Head of expression is `/`. `/..` cannot resolve to any node-set,
+				// but it **is a valid LocationPath expression**. We concatenate
+				// here to produce that expression, as a concession that this is
+				// the only valid outcome.
+				case 'absolute_root_location_path':
+					return [currentHead, node];
+
+				// Head of expression is a FilterExpr. Attempting to resolve parent step
+				// would lose that original context. Concatenating instead is a
+				// concession to this fact: we cannot fully resolve the nodeset/path
+				// path in this context.
+				//
+				// If the head FilterExpr is a `current()` call, it is possible that the
+				// path may be further resolved against another context (likely one from
+				// an outer element in the form definition, or any other case which
+				// would establish further context and be reached by recursing up the
+				// definition hierarchy). For now, we must accept that the resulting
+				// LocationPath will not be fully resolved.
+				//
+				// If the FilterExpr is an `instance("id")` call, this will effectively
+				// terminate resolution of the step:
+				// `instance("id")/../$remainingTail` **is a valid expression**;
+				// however, downstream evaluation of that expression is expected to
+				// produce an empty node-set (as it traverses into a part of the
+				// document outside of the subtree[s] handled by the `@getodk/xpath`
+				// evaluator).
+				case 'filter_expr':
+					return [currentHead, node];
+
+				// Head of expression is relative. Resolution is as follows:
+				case 'step': {
+					// - If head is a self-reference, we replace that head with this step.
+					//   This is safe (and correct) because `./../$remainingTail` is
+					//   functionally equivalent to `../$remainingTail`.
+					if (getResolvableTraversalType(currentHead) === 'self') {
+						return [node];
+					}
+
+					// - If head is any other Step-like node we concatenate (e.g.
+					//   where head is `foo`, we will produce `foo/..`), with the same
+					//   reasoning as the above FilterExpr case. And as with that
+					//   case, it is possible some downstream processing may allow
+					//   further resolution.
+					return [currentHead, node];
+				}
+
+				// Head of current path is `//`. Above, we already handled the special
+				// case where this parent traversal would be the end of the path
+				// expression, so here we can safely collapse `//../$remainingTail`
+				// to `//$remainingTail`
+				case '//': {
+					return acc;
+				}
+
+				default:
+					throw new UnreachableError(currentHead);
+			}
+		},
+		[head]
+	);
+};
+
+export const resolvePath = (
+	contextNode: PathExpressionNode | null,
+	pathNode: PathExpressionNode
+): PathNodeList => {
+	const contextNodes = optionalPathNodeList(contextNode) ?? [];
+
+	// Path expression is **resolved without context** (or as its own context) in
+	// any of the following conditions...
+	//
+	// - No context is available
+	// - Expression path is absolute
+	// - Expression begins with any FilterExpr besides a `current()` call
+	//
+	// We still resolve the Step-like syntax parts **within the path**, e.g.
+	// allowing us to collapse `Step/..` pairs.
+	if (
+		// - We have no context, so there's nothing to resolve the expression path
+		//   against, regardless of any other factor
+		contextNode == null ||
+		// - Expression path is absolute, so it is its own context
+		pathNode.type === 'absolute_location_path' ||
+		// - Expression path has leading FilterExpr, which is **not** a call to
+		//   `current()`, in which case it is treated as if it were absolute.
+		(pathNode.type === 'filter_path_expr' && !isCurrentPath(pathNode))
+	) {
+		const pathNodes = pathNodeList(pathNode);
+
+		return resolvePathNodeList(pathNodes);
+	}
+
+	const contextualizedNodes: UnresolvedPathNodeList = [...contextNodes, ...pathNode.children];
+
+	return resolvePathNodeList(contextualizedNodes);
+};
+
+/**
+ * Resolves the parsed path {@link predicatePathNode}, in the context of:
+ *
+ * - The {@link contextNode} context, representing the original expression's
+ *   context (if one was available)
+ *
+ * - The {@link stepContextNodes} context, representing the cumulative portion
+ *   of the source path where {@link predicatePathNode} was parsed from a
+ *   Predicate sub-expression
+ *
+ * Both contexts are necessary for resolution to ensure that:
+ *
+ * - A `current()` call within the predicate's sub-expression is contextualized
+ *   to the current `nodeset` reference associated with the original expression
+ *
+ * - A `.` self-reference within the predicate's sub-expression is
+ *   contextualized to the Step in which it occurred
+ */
+export const resolvePredicateReference = (
+	contextNode: PathExpressionNode | null,
+	stepContextNodes: PathNodeList,
+	predicatePathNode: PathExpressionNode
+): PathNodeList => {
+	const predicatePathNodes = pathNodeList(predicatePathNode);
+
+	const [head, ...tail] = predicatePathNodes;
+
+	if (head.type === 'absolute_root_location_path' || head.type === '//') {
+		return predicatePathNodes;
+	}
+
+	let contextNodes: PathNodeList;
+
+	if (
+		contextNode != null &&
+		predicatePathNode.type === 'filter_path_expr' &&
+		isCurrentPath(predicatePathNode)
+	) {
+		contextNodes = pathNodeList(contextNode);
+	} else {
+		contextNodes = stepContextNodes;
+	}
+
+	const contextualizedNodes: UnresolvedPathNodeList = [...contextNodes, head, ...tail];
+
+	return resolvePathNodeList(contextualizedNodes);
+};
+interface PathSerializationOptions {
+	/**
+	 * @default false
+	 */
+	readonly stripPredicates: boolean;
+}
+
+type AnyPathNode = PathNodeList[number];
+
+const serializePathNode = (node: AnyPathNode, options: PathSerializationOptions): string => {
+	const { type, text } = node;
+	if (type === 'step') {
+		switch (getResolvableTraversalType(node)) {
+			case 'self':
+				return '.';
+
+			case 'parent':
+				return '..';
+		}
+	}
+
+	if (options.stripPredicates) {
+		switch (type) {
+			case 'absolute_root_location_path':
+			case '//':
+				return text;
+
+			case 'filter_expr':
+			case 'step': {
+				const [head, ..._predicates] = node.children;
+
+				_predicates satisfies readonly PredicateNode[];
+
+				return head.text;
+			}
+		}
+	}
+
+	return text;
+};
+
+/**
+ * Serializes a resolved {@link PathNodeList} to its XPath expression
+ * representation, optionally stripping predicates.
+ */
+export const serializeNodesetReference = (
+	nodes: PathNodeList,
+	options: PathSerializationOptions
+): string => {
+	const [head, ...tail] = nodes;
+	const strings: string[] = [serializePathNode(head, options)];
+
+	let previousNode = head;
+
+	for (const node of tail) {
+		const previousNodeType = previousNode.type;
+
+		if (
+			previousNodeType !== 'absolute_root_location_path' &&
+			previousNodeType !== '//' &&
+			node.type !== '//'
+		) {
+			strings.push('/');
+		}
+
+		strings.push(serializePathNode(node, options));
+		previousNode = node;
+	}
+
+	return strings.join('');
+};

package/src/parse/xpath/predicate-analysis.ts

@@ -0,0 +1,61 @@
+import type { PathNodeList } from './path-resolution.ts';
+import type { PathExpressionNode } from './semantic-analysis.ts';
+import { findLocationPathSubExpressionNodes } from './semantic-analysis.ts';
+
+/**
+ * Represents a pair of:
+ *
+ * - Path expression syntax referenced within a particular predicate, on any
+ *   Step within a source LocationPath and/or FilterExpr path. This
+ *   sub-expression is resolved as a member of the dependencies which may be
+ *   referenced by any arbitrary form expression.
+ *
+ * - The cumulative set of path nodes, from the start of the source path
+ *   expression, to the Step and Predicate where the sub-expression reference
+ *   was identified. This representation is used as **part** of the context used
+ *   to resolve the identified Predicate sub-expression for downstream
+ *   dependency subscriptions. (Each predicate sub-expression is **further
+ *   contextualized** by the original context in which the source path is
+ *   defined.)
+ */
+export interface PredicateReference {
+	readonly predicatePathNode: PathExpressionNode;
+	readonly stepContextNodes: PathNodeList;
+}
+
+/**
+ * Identifies path sub-expressions within any of a path's Predicates, along with
+ * the step context in which they are found.
+ *
+ * @see {@link PredicateReference} for details on the produced structures.
+ */
+export const findPredicateReferences = (pathNodes: PathNodeList): readonly PredicateReference[] => {
+	const [head, ...tail] = pathNodes;
+
+	return pathNodes.flatMap((targetNode, i) => {
+		const cumulativePath: PathNodeList = [head, ...tail.slice(0, i)];
+
+		switch (targetNode.type) {
+			case 'absolute_root_location_path':
+			case '//':
+				return [];
+		}
+
+		const [, ...predicates] = targetNode.children;
+
+		if (predicates.length === 0) {
+			return [];
+		}
+
+		return predicates.flatMap((predicate) => {
+			const predicateSubExpressions = findLocationPathSubExpressionNodes(predicate);
+
+			return predicateSubExpressions.map((predicatePathNode) => {
+				return {
+					predicatePathNode,
+					stepContextNodes: cumulativePath,
+				};
+			});
+		});
+	});
+};