@speclynx/apidom-traverse 4.0.2 → 4.0.3

package/src/Path.mjs

@@ -0,0 +1,338 @@
+import { isMemberElement, isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { compile as compileJSONPointer } from '@speclynx/apidom-json-pointer';
+import { NormalizedPath } from '@speclynx/apidom-json-path';
+
+/**
+ * Possible return values from a visitor function.
+ * @public
+ */
+
+/**
+ * Visitor function signature - receives a Path object.
+ * @public
+ */
+
+/**
+ * Path represents a node's position in the tree during traversal.
+ * Inspired by Babel's NodePath API.
+ * @public
+ */
+export class Path {
+  /**
+   * The current AST node.
+   */
+  node;
+
+  /**
+   * The key of this node in its parent.
+   * `undefined` for the root node.
+   */
+  key;
+
+  /**
+   * The index if this node is in an array.
+   * Same as `key` when parent property is an array, `undefined` otherwise.
+   */
+  index;
+
+  /**
+   * The parent node.
+   * `undefined` for the root node.
+   */
+  parent;
+
+  /**
+   * The parent Path.
+   * `null` for the root node.
+   */
+  parentPath;
+
+  /**
+   * Whether this node is inside an array in the parent.
+   */
+  inList;
+
+  /**
+   * Internal state for traversal control.
+   */
+  #shouldSkip = false;
+  #shouldStop = false;
+  #removed = false;
+  #replaced = false;
+  #replacementNode;
+  #stale = false;
+  constructor(node, parent, parentPath, key, inList) {
+    this.node = node;
+    this.parent = parent;
+    this.parentPath = parentPath;
+    this.key = key;
+    this.index = inList && typeof key === 'number' ? key : undefined;
+    this.inList = inList;
+  }
+
+  // ===========================================================================
+  // Traversal state
+  // ===========================================================================
+
+  /**
+   * Whether skip() was called on this path.
+   */
+  get shouldSkip() {
+    return this.#shouldSkip;
+  }
+
+  /**
+   * Whether stop() was called on this path.
+   */
+  get shouldStop() {
+    return this.#shouldStop;
+  }
+
+  /**
+   * Whether this node was removed.
+   */
+  get removed() {
+    return this.#removed;
+  }
+
+  // ===========================================================================
+  // Ancestry
+  // ===========================================================================
+
+  /**
+   * Returns true if this is the root path.
+   */
+  isRoot() {
+    return this.parentPath === null;
+  }
+
+  /**
+   * Get the depth of this path (0 for root).
+   */
+  get depth() {
+    let depth = 0;
+    let current = this.parentPath;
+    while (current !== null) {
+      depth += 1;
+      current = current.parentPath;
+    }
+    return depth;
+  }
+
+  /**
+   * Get all ancestor paths from immediate parent to root.
+   */
+  getAncestry() {
+    const ancestry = [];
+    let current = this.parentPath;
+    while (current !== null) {
+      ancestry.push(current);
+      current = current.parentPath;
+    }
+    return ancestry;
+  }
+
+  /**
+   * Get all ancestor nodes from immediate parent to root.
+   */
+  getAncestorNodes() {
+    return this.getAncestry().map(p => p.node);
+  }
+
+  /**
+   * Get the semantic path from root as an array of keys.
+   * Returns logical document keys (property names, array indices) rather than
+   * internal ApiDOM structure keys.
+   *
+   * @example
+   * // For a path to $.paths['/pets'].get in an OpenAPI document:
+   * ```
+   * path.getPathKeys(); // => ['paths', '/pets', 'get']
+   * ```
+   */
+  getPathKeys() {
+    const keys = [];
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current = this;
+    while (current !== null && current.key !== undefined) {
+      const {
+        key,
+        parent,
+        parentPath
+      } = current;
+      if (isMemberElement(parent) && key === 'value') {
+        // Inside MemberElement.value → push the member's key
+        if (!isStringElement(parent.key)) {
+          throw new TypeError('MemberElement.key must be a StringElement');
+        }
+        keys.unshift(parent.key.toValue());
+      } else if (isArrayElement(parentPath?.node) && typeof key === 'number') {
+        // Inside ArrayElement → push the numeric index
+        keys.unshift(key);
+      }
+      current = current.parentPath;
+    }
+    return keys;
+  }
+
+  /**
+   * Format path as RFC 6901 JSON Pointer or RFC 9535 Normalized JSONPath.
+   *
+   * @param pathFormat - Output format: "jsonpointer" (default) or "jsonpath"
+   * @returns JSONPointer string like "/paths/~1pets/get/responses/200"
+   *          or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
+   *
+   * @example
+   * ```
+   * // JSON Pointer examples:
+   * path.formatPath(); // "" (root)
+   * path.formatPath(); // "/info"
+   * path.formatPath(); // "/paths/~1pets/get"
+   * path.formatPath(); // "/paths/~1users~1{id}/parameters/0"
+   * ```
+   *
+   * @example
+   * ```
+   * // JSONPath examples:
+   * path.formatPath('jsonpath'); // "$" (root)
+   * path.formatPath('jsonpath'); // "$['info']"
+   * path.formatPath('jsonpath'); // "$['paths']['/pets']['get']"
+   * path.formatPath('jsonpath'); // "$['paths']['/users/{id}']['parameters'][0]"
+   * ```
+   */
+  formatPath(pathFormat = 'jsonpointer') {
+    const parts = this.getPathKeys();
+
+    // Root node
+    if (parts.length === 0) {
+      return pathFormat === 'jsonpath' ? '$' : '';
+    }
+    if (pathFormat === 'jsonpath') {
+      // RFC 9535 Normalized JSONPath
+      return NormalizedPath.from(parts);
+    }
+
+    // RFC 6901 JSON Pointer
+    return compileJSONPointer(parts);
+  }
+
+  /**
+   * Find the closest ancestor path that satisfies the predicate.
+   */
+  findParent(predicate) {
+    let current = this.parentPath;
+    while (current !== null) {
+      if (predicate(current)) {
+        return current;
+      }
+      current = current.parentPath;
+    }
+    return null;
+  }
+
+  /**
+   * Find the closest path (including this one) that satisfies the predicate.
+   */
+  find(predicate) {
+    if (predicate(this)) {
+      return this;
+    }
+    return this.findParent(predicate);
+  }
+
+  // ===========================================================================
+  // Nested traversal
+  // ===========================================================================
+
+  /**
+   * Traverse into the current node with a new visitor.
+   * Populated by the traversal module to avoid circular imports.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Async version of traverse.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+  // ===========================================================================
+  // Traversal control
+  // ===========================================================================
+
+  /**
+   * Skip traversing the children of this node.
+   */
+  skip() {
+    this.#shouldSkip = true;
+  }
+
+  /**
+   * Stop all traversal completely.
+   */
+  stop() {
+    this.#shouldStop = true;
+  }
+
+  // ===========================================================================
+  // Modification
+  // ===========================================================================
+
+  /**
+   * Replace this node with a new node.
+   */
+  replaceWith(replacement) {
+    if (this.#stale) {
+      console.warn('Warning: replaceWith() called on a stale Path. ' + 'This path belongs to a node whose visit has already completed. ' + 'The replacement will have no effect. ' + "To replace a parent node, do so from the parent's own visitor.");
+    }
+    this.#replaced = true;
+    this.#replacementNode = replacement;
+    this.node = replacement;
+  }
+
+  /**
+   * Remove this node from the tree.
+   */
+  remove() {
+    if (this.#stale) {
+      console.warn('Warning: remove() called on a stale Path. ' + 'This path belongs to a node whose visit has already completed. ' + 'The removal will have no effect. ' + "To remove a parent node, do so from the parent's own visitor.");
+    }
+    this.#removed = true;
+  }
+
+  // ===========================================================================
+  // Internal methods for traversal engine
+  // ===========================================================================
+
+  /**
+   * @internal
+   */
+  _getReplacementNode() {
+    return this.#replacementNode;
+  }
+
+  /**
+   * @internal
+   */
+  _wasReplaced() {
+    return this.#replaced;
+  }
+
+  /**
+   * @internal
+   */
+  _reset() {
+    this.#shouldSkip = false;
+    this.#shouldStop = false;
+    this.#removed = false;
+    this.#replaced = false;
+    this.#replacementNode = undefined;
+  }
+
+  /**
+   * Mark this path as stale (visit completed).
+   * @internal
+   */
+  _markStale() {
+    this.#stale = true;
+  }
+}

package/src/Path.ts

@@ -0,0 +1,368 @@
+import {
+  isMemberElement,
+  isArrayElement,
+  isStringElement,
+  type Element,
+} from '@speclynx/apidom-datamodel';
+import { compile as compileJSONPointer } from '@speclynx/apidom-json-pointer';
+import { NormalizedPath } from '@speclynx/apidom-json-path';
+
+/**
+ * Possible return values from a visitor function.
+ * @public
+ */
+export type VisitorResult<TNode> = void | undefined | TNode | Promise<void | undefined | TNode>;
+
+/**
+ * Visitor function signature - receives a Path object.
+ * @public
+ */
+export type VisitorFn<TNode, TVisitor = unknown> = (
+  this: TVisitor,
+  path: Path<TNode>,
+) => VisitorResult<TNode>;
+
+/**
+ * Path represents a node's position in the tree during traversal.
+ * Inspired by Babel's NodePath API.
+ * @public
+ */
+export class Path<TNode = Element> {
+  /**
+   * The current AST node.
+   */
+  public node: TNode;
+
+  /**
+   * The key of this node in its parent.
+   * `undefined` for the root node.
+   */
+  public readonly key: PropertyKey | undefined;
+
+  /**
+   * The index if this node is in an array.
+   * Same as `key` when parent property is an array, `undefined` otherwise.
+   */
+  public readonly index: number | undefined;
+
+  /**
+   * The parent node.
+   * `undefined` for the root node.
+   */
+  public readonly parent: TNode | undefined;
+
+  /**
+   * The parent Path.
+   * `null` for the root node.
+   */
+  public readonly parentPath: Path<TNode> | null;
+
+  /**
+   * Whether this node is inside an array in the parent.
+   */
+  public readonly inList: boolean;
+
+  /**
+   * Internal state for traversal control.
+   */
+  #shouldSkip: boolean = false;
+  #shouldStop: boolean = false;
+  #removed: boolean = false;
+  #replaced: boolean = false;
+  #replacementNode: TNode | undefined;
+  #stale: boolean = false;
+
+  constructor(
+    node: TNode,
+    parent: TNode | undefined,
+    parentPath: Path<TNode> | null,
+    key: PropertyKey | undefined,
+    inList: boolean,
+  ) {
+    this.node = node;
+    this.parent = parent;
+    this.parentPath = parentPath;
+    this.key = key;
+    this.index = inList && typeof key === 'number' ? key : undefined;
+    this.inList = inList;
+  }
+
+  // ===========================================================================
+  // Traversal state
+  // ===========================================================================
+
+  /**
+   * Whether skip() was called on this path.
+   */
+  get shouldSkip(): boolean {
+    return this.#shouldSkip;
+  }
+
+  /**
+   * Whether stop() was called on this path.
+   */
+  get shouldStop(): boolean {
+    return this.#shouldStop;
+  }
+
+  /**
+   * Whether this node was removed.
+   */
+  get removed(): boolean {
+    return this.#removed;
+  }
+
+  // ===========================================================================
+  // Ancestry
+  // ===========================================================================
+
+  /**
+   * Returns true if this is the root path.
+   */
+  isRoot(): boolean {
+    return this.parentPath === null;
+  }
+
+  /**
+   * Get the depth of this path (0 for root).
+   */
+  get depth(): number {
+    let depth = 0;
+    let current: Path<TNode> | null = this.parentPath;
+    while (current !== null) {
+      depth += 1;
+      current = current.parentPath;
+    }
+    return depth;
+  }
+
+  /**
+   * Get all ancestor paths from immediate parent to root.
+   */
+  getAncestry(): Path<TNode>[] {
+    const ancestry: Path<TNode>[] = [];
+    let current: Path<TNode> | null = this.parentPath;
+    while (current !== null) {
+      ancestry.push(current);
+      current = current.parentPath;
+    }
+    return ancestry;
+  }
+
+  /**
+   * Get all ancestor nodes from immediate parent to root.
+   */
+  getAncestorNodes(): TNode[] {
+    return this.getAncestry().map((p) => p.node);
+  }
+
+  /**
+   * Get the semantic path from root as an array of keys.
+   * Returns logical document keys (property names, array indices) rather than
+   * internal ApiDOM structure keys.
+   *
+   * @example
+   * // For a path to $.paths['/pets'].get in an OpenAPI document:
+   * ```
+   * path.getPathKeys(); // => ['paths', '/pets', 'get']
+   * ```
+   */
+  getPathKeys(): PropertyKey[] {
+    const keys: PropertyKey[] = [];
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: Path<TNode> | null = this;
+
+    while (current !== null && current.key !== undefined) {
+      const { key, parent, parentPath } = current;
+
+      if (isMemberElement(parent) && key === 'value') {
+        // Inside MemberElement.value → push the member's key
+        if (!isStringElement(parent.key)) {
+          throw new TypeError('MemberElement.key must be a StringElement');
+        }
+        keys.unshift(parent.key.toValue() as PropertyKey);
+      } else if (isArrayElement(parentPath?.node) && typeof key === 'number') {
+        // Inside ArrayElement → push the numeric index
+        keys.unshift(key);
+      }
+
+      current = current.parentPath;
+    }
+
+    return keys;
+  }
+
+  /**
+   * Format path as RFC 6901 JSON Pointer or RFC 9535 Normalized JSONPath.
+   *
+   * @param pathFormat - Output format: "jsonpointer" (default) or "jsonpath"
+   * @returns JSONPointer string like "/paths/~1pets/get/responses/200"
+   *          or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
+   *
+   * @example
+   * ```
+   * // JSON Pointer examples:
+   * path.formatPath(); // "" (root)
+   * path.formatPath(); // "/info"
+   * path.formatPath(); // "/paths/~1pets/get"
+   * path.formatPath(); // "/paths/~1users~1{id}/parameters/0"
+   * ```
+   *
+   * @example
+   * ```
+   * // JSONPath examples:
+   * path.formatPath('jsonpath'); // "$" (root)
+   * path.formatPath('jsonpath'); // "$['info']"
+   * path.formatPath('jsonpath'); // "$['paths']['/pets']['get']"
+   * path.formatPath('jsonpath'); // "$['paths']['/users/{id}']['parameters'][0]"
+   * ```
+   */
+  formatPath(pathFormat: 'jsonpointer' | 'jsonpath' = 'jsonpointer'): string {
+    const parts = this.getPathKeys();
+
+    // Root node
+    if (parts.length === 0) {
+      return pathFormat === 'jsonpath' ? '$' : '';
+    }
+
+    if (pathFormat === 'jsonpath') {
+      // RFC 9535 Normalized JSONPath
+      return NormalizedPath.from(parts as (string | number)[]);
+    }
+
+    // RFC 6901 JSON Pointer
+    return compileJSONPointer(parts as string[]);
+  }
+
+  /**
+   * Find the closest ancestor path that satisfies the predicate.
+   */
+  findParent(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null {
+    let current: Path<TNode> | null = this.parentPath;
+    while (current !== null) {
+      if (predicate(current)) {
+        return current;
+      }
+      current = current.parentPath;
+    }
+    return null;
+  }
+
+  /**
+   * Find the closest path (including this one) that satisfies the predicate.
+   */
+  find(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null {
+    if (predicate(this)) {
+      return this;
+    }
+    return this.findParent(predicate);
+  }
+
+  // ===========================================================================
+  // Nested traversal
+  // ===========================================================================
+
+  /**
+   * Traverse into the current node with a new visitor.
+   * Populated by the traversal module to avoid circular imports.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  declare traverse: (visitor: any, options?: any) => TNode;
+
+  /**
+   * Async version of traverse.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  declare traverseAsync: (visitor: any, options?: any) => Promise<TNode>;
+
+  // ===========================================================================
+  // Traversal control
+  // ===========================================================================
+
+  /**
+   * Skip traversing the children of this node.
+   */
+  skip(): void {
+    this.#shouldSkip = true;
+  }
+
+  /**
+   * Stop all traversal completely.
+   */
+  stop(): void {
+    this.#shouldStop = true;
+  }
+
+  // ===========================================================================
+  // Modification
+  // ===========================================================================
+
+  /**
+   * Replace this node with a new node.
+   */
+  replaceWith(replacement: TNode): void {
+    if (this.#stale) {
+      console.warn(
+        'Warning: replaceWith() called on a stale Path. ' +
+          'This path belongs to a node whose visit has already completed. ' +
+          'The replacement will have no effect. ' +
+          "To replace a parent node, do so from the parent's own visitor.",
+      );
+    }
+    this.#replaced = true;
+    this.#replacementNode = replacement;
+    this.node = replacement;
+  }
+
+  /**
+   * Remove this node from the tree.
+   */
+  remove(): void {
+    if (this.#stale) {
+      console.warn(
+        'Warning: remove() called on a stale Path. ' +
+          'This path belongs to a node whose visit has already completed. ' +
+          'The removal will have no effect. ' +
+          "To remove a parent node, do so from the parent's own visitor.",
+      );
+    }
+    this.#removed = true;
+  }
+
+  // ===========================================================================
+  // Internal methods for traversal engine
+  // ===========================================================================
+
+  /**
+   * @internal
+   */
+  _getReplacementNode(): TNode | undefined {
+    return this.#replacementNode;
+  }
+
+  /**
+   * @internal
+   */
+  _wasReplaced(): boolean {
+    return this.#replaced;
+  }
+
+  /**
+   * @internal
+   */
+  _reset(): void {
+    this.#shouldSkip = false;
+    this.#shouldStop = false;
+    this.#removed = false;
+    this.#replaced = false;
+    this.#replacementNode = undefined;
+  }
+
+  /**
+   * Mark this path as stale (visit completed).
+   * @internal
+   */
+  _markStale(): void {
+    this.#stale = true;
+  }
+}