@speclynx/apidom-traverse 3.2.0 → 4.0.0

package/src/Path.mjs

@@ -1,332 +0,0 @@
-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

@@ -1,43 +0,0 @@
-"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

@@ -1,19 +0,0 @@
-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

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

package/src/operations/filter.mjs

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

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

@@ -1,45 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _traversal = require("../traversal.cjs");
-/**
- * @public
- */
-
-/**
- * Finds 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(node);
-        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

@@ -1,40 +0,0 @@
-import { hasElementSourceMap } from '@speclynx/apidom-datamodel';
-import { traverse } from "../traversal.mjs";
-/**
- * @public
- */
-/**
- * Finds 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(node);
-        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

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

package/src/operations/find.mjs

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

package/src/operations/for-each.cjs

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

package/src/operations/for-each.mjs

@@ -1,31 +0,0 @@
-import { isElement } from '@speclynx/apidom-datamodel';
-import { traverse } from "../traversal.mjs";
-/**
- * @public
- */
-/**
- * @public
- */
-/**
- * Executes the callback on this element and all descendants.
- * @public
- */
-const forEach = (element, options) => {
-  let callback;
-  let predicate;
-  if (typeof options === 'function') {
-    callback = options;
-    predicate = isElement;
-  } else {
-    callback = options.callback ?? (() => {});
-    predicate = options.predicate ?? isElement;
-  }
-  traverse(element, {
-    enter(path) {
-      if (predicate(path.node)) {
-        callback(path.node);
-      }
-    }
-  });
-};
-export default forEach;

package/src/operations/parents.cjs

@@ -1,21 +0,0 @@
-"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

@@ -1,17 +0,0 @@
-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

@@ -1,14 +0,0 @@
-"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 elements NOT matching the predicate.
- * @public
- */
-const reject = (element, predicate) => {
-  return (0, _filter.default)(element, el => !predicate(el));
-};
-var _default = exports.default = reject;