@speclynx/apidom-traverse 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.0.3](https://github.com/speclynx/apidom/compare/v4.0.2...v4.0.3) (2026-03-11)
+
+### Bug Fixes
+
+- **release:** fix v4.0.2 failed release ([b4dc1c4](https://github.com/speclynx/apidom/commit/b4dc1c48e8d9b2986a70e49b5554eb0a166d7528))
+
+## [4.0.2](https://github.com/speclynx/apidom/compare/v4.0.1...v4.0.2) (2026-03-11)
+
+**Note:** Version bump only for package @speclynx/apidom-traverse
+
 ## [4.0.1](https://github.com/speclynx/apidom/compare/v4.0.0...v4.0.1) (2026-03-11)
 
 **Note:** Version bump only for package @speclynx/apidom-traverse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-traverse",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Traversal and visitor utilities for walking and transforming ApiDOM structures.",
   "keywords": [
     "apidom",
@@ -61,15 +61,14 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "4.0.1",
-    "@speclynx/apidom-error": "4.0.1",
-    "@speclynx/apidom-json-path": "4.0.1",
-    "@speclynx/apidom-json-pointer": "4.0.1",
+    "@speclynx/apidom-datamodel": "4.0.3",
+    "@speclynx/apidom-error": "4.0.3",
+    "@speclynx/apidom-json-path": "4.0.3",
+    "@speclynx/apidom-json-pointer": "4.0.3",
     "ramda-adjunct": "^6.0.0"
   },
   "files": [
-    "src/**/*.mjs",
-    "src/**/*.cjs",
+    "src/",
     "dist/",
     "types/apidom-traverse.d.ts",
     "LICENSES",
@@ -77,5 +76,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "223132a9b00081ca04842efc2736a491f7876f44"
+  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
 }

package/src/Path.cjs

@@ -0,0 +1,342 @@
+"use strict";
+
+exports.__esModule = true;
+exports.Path = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomJsonPath = require("@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
+ */
+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 ((0, _apidomDatamodel.isMemberElement)(parent) && key === 'value') {
+        // Inside MemberElement.value → push the member's key
+        if (!(0, _apidomDatamodel.isStringElement)(parent.key)) {
+          throw new TypeError('MemberElement.key must be a StringElement');
+        }
+        keys.unshift(parent.key.toValue());
+      } else if ((0, _apidomDatamodel.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 _apidomJsonPath.NormalizedPath.from(parts);
+    }
+
+    // RFC 6901 JSON Pointer
+    return (0, _apidomJsonPointer.compile)(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;
+  }
+}
+exports.Path = Path;