@speclynx/apidom-traverse 4.0.2 → 4.0.4

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/index.cjs

@@ -0,0 +1,43 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.some = exports.reject = exports.parents = exports.mutateNode = exports.mergeVisitorsAsync = exports.mergeVisitors = exports.isNode = exports.getVisitFn = exports.getNodeType = exports.getNodePrimitiveType = exports.getNodeKeys = exports.forEach = exports.findAtOffset = exports.find = exports.filter = exports.cloneNode = void 0;
+var _Path = require("./Path.cjs");
+exports.Path = _Path.Path;
+var _traversal = require("./traversal.cjs");
+exports.traverse = _traversal.traverse;
+exports.traverseAsync = _traversal.traverseAsync;
+var _visitors = require("./visitors.cjs");
+exports.getNodeType = _visitors.getNodeType;
+exports.getNodePrimitiveType = _visitors.getNodePrimitiveType;
+exports.isNode = _visitors.isNode;
+exports.cloneNode = _visitors.cloneNode;
+exports.mutateNode = _visitors.mutateNode;
+exports.getNodeKeys = _visitors.getNodeKeys;
+exports.getVisitFn = _visitors.getVisitFn;
+exports.mergeVisitors = _visitors.mergeVisitors;
+exports.mergeVisitorsAsync = _visitors.mergeVisitorsAsync;
+var _filter = _interopRequireDefault(require("./operations/filter.cjs"));
+exports.filter = _filter.default;
+var _find = _interopRequireDefault(require("./operations/find.cjs"));
+exports.find = _find.default;
+var _some = _interopRequireDefault(require("./operations/some.cjs"));
+exports.some = _some.default;
+var _reject = _interopRequireDefault(require("./operations/reject.cjs"));
+exports.reject = _reject.default;
+var _forEach = _interopRequireDefault(require("./operations/for-each.cjs"));
+exports.forEach = _forEach.default;
+var _parents = _interopRequireDefault(require("./operations/parents.cjs"));
+exports.parents = _parents.default;
+var _findAtOffset = _interopRequireDefault(require("./operations/find-at-offset.cjs"));
+exports.findAtOffset = _findAtOffset.default;
+// Wire up Path.prototype.traverse methods to avoid circular imports
+_Path.Path.prototype.traverse = function (visitor, options) {
+  return (0, _traversal.traverse)(this.node, visitor, options);
+};
+_Path.Path.prototype.traverseAsync = function (visitor, options) {
+  return (0, _traversal.traverseAsync)(this.node, visitor, options);
+};
+
+// Operations

package/src/index.mjs

@@ -0,0 +1,19 @@
+import { Path } from "./Path.mjs";
+import { traverse, traverseAsync } from "./traversal.mjs"; // Wire up Path.prototype.traverse methods to avoid circular imports
+Path.prototype.traverse = function (visitor, options) {
+  return traverse(this.node, visitor, options);
+};
+Path.prototype.traverseAsync = function (visitor, options) {
+  return traverseAsync(this.node, visitor, options);
+};
+export { Path };
+export { getNodeType, getNodePrimitiveType, isNode, cloneNode, mutateNode, getNodeKeys, getVisitFn, mergeVisitors, mergeVisitorsAsync } from "./visitors.mjs";
+export { traverse, traverseAsync } from "./traversal.mjs";
+// Operations
+export { default as filter } from "./operations/filter.mjs";
+export { default as find } from "./operations/find.mjs";
+export { default as some } from "./operations/some.mjs";
+export { default as reject } from "./operations/reject.mjs";
+export { default as forEach } from "./operations/for-each.mjs";
+export { default as parents } from "./operations/parents.mjs";
+export { default as findAtOffset } from "./operations/find-at-offset.mjs";

package/src/operations/filter.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Finds all paths whose elements match the predicate.
+ * @public
+ */
+const filter = (element, predicate) => {
+  const result = [];
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result.push(path);
+      }
+    }
+  });
+  return result;
+};
+var _default = exports.default = filter;

package/src/operations/filter.mjs

@@ -0,0 +1,17 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Finds all paths whose elements match the predicate.
+ * @public
+ */
+const filter = (element, predicate) => {
+  const result = [];
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result.push(path);
+      }
+    }
+  });
+  return result;
+};
+export default filter;

package/src/operations/find-at-offset.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _traversal = require("../traversal.cjs");
+/**
+ * @public
+ */
+
+/**
+ * Finds the path of the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+const findAtOffset = (element, options) => {
+  let offset;
+  let includeRightBound;
+  if (typeof options === 'number') {
+    offset = options;
+    includeRightBound = false;
+  } else {
+    offset = options.offset ?? 0;
+    includeRightBound = options.includeRightBound ?? false;
+  }
+  const result = [];
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      const node = path.node;
+      if (!(0, _apidomDatamodel.hasElementSourceMap)(node)) {
+        return; // dive in
+      }
+      const startOffset = node.startOffset;
+      const endOffset = node.endOffset;
+      const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
+      if (isWithinOffsetRange) {
+        result.push(path);
+        return; // push to stack and dive in
+      }
+      path.skip(); // skip entire sub-tree
+    }
+  });
+  return result.at(-1);
+};
+var _default = exports.default = findAtOffset;

package/src/operations/find-at-offset.mjs

@@ -0,0 +1,40 @@
+import { hasElementSourceMap } from '@speclynx/apidom-datamodel';
+import { traverse } from "../traversal.mjs";
+/**
+ * @public
+ */
+/**
+ * Finds the path of the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+const findAtOffset = (element, options) => {
+  let offset;
+  let includeRightBound;
+  if (typeof options === 'number') {
+    offset = options;
+    includeRightBound = false;
+  } else {
+    offset = options.offset ?? 0;
+    includeRightBound = options.includeRightBound ?? false;
+  }
+  const result = [];
+  traverse(element, {
+    enter(path) {
+      const node = path.node;
+      if (!hasElementSourceMap(node)) {
+        return; // dive in
+      }
+      const startOffset = node.startOffset;
+      const endOffset = node.endOffset;
+      const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
+      if (isWithinOffsetRange) {
+        result.push(path);
+        return; // push to stack and dive in
+      }
+      path.skip(); // skip entire sub-tree
+    }
+  });
+  return result.at(-1);
+};
+export default findAtOffset;

package/src/operations/find.cjs

@@ -0,0 +1,22 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Finds first path whose element satisfies the provided predicate.
+ * @public
+ */
+const find = (element, predicate) => {
+  let result;
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result = path;
+        path.stop();
+      }
+    }
+  });
+  return result;
+};
+var _default = exports.default = find;

package/src/operations/find.mjs

@@ -0,0 +1,18 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Finds first path whose element satisfies the provided predicate.
+ * @public
+ */
+const find = (element, predicate) => {
+  let result;
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result = path;
+        path.stop();
+      }
+    }
+  });
+  return result;
+};
+export default find;

package/src/operations/for-each.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * Executes the callback on this element's path and all descendant paths.
+ * @public
+ */
+const forEach = (element, options) => {
+  let callback;
+  let predicate;
+  if (typeof options === 'function') {
+    callback = options;
+    predicate = () => true;
+  } else {
+    callback = options.callback ?? (() => {});
+    predicate = options.predicate ?? (() => true);
+  }
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        callback(path);
+      }
+    }
+  });
+};
+var _default = exports.default = forEach;

package/src/operations/for-each.mjs

@@ -0,0 +1,30 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * Executes the callback on this element's path and all descendant paths.
+ * @public
+ */
+const forEach = (element, options) => {
+  let callback;
+  let predicate;
+  if (typeof options === 'function') {
+    callback = options;
+    predicate = () => true;
+  } else {
+    callback = options.callback ?? (() => {});
+    predicate = options.predicate ?? (() => true);
+  }
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        callback(path);
+      }
+    }
+  });
+};
+export default forEach;

package/src/operations/parents.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+const parents = element => {
+  const parentEdges = new WeakMap();
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      // Use parentPath.node to get the actual Element parent.
+      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
+      parentEdges.set(path.node, path.parentPath?.node);
+    }
+  });
+  return parentEdges;
+};
+var _default = exports.default = parents;

package/src/operations/parents.mjs

@@ -0,0 +1,17 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+const parents = element => {
+  const parentEdges = new WeakMap();
+  traverse(element, {
+    enter(path) {
+      // Use parentPath.node to get the actual Element parent.
+      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
+      parentEdges.set(path.node, path.parentPath?.node);
+    }
+  });
+  return parentEdges;
+};
+export default parents;

package/src/operations/reject.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _filter = _interopRequireDefault(require("./filter.cjs"));
+/**
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
+ * @public
+ */
+const reject = (element, predicate) => {
+  return (0, _filter.default)(element, path => !predicate(path));
+};
+var _default = exports.default = reject;