@speclynx/apidom-traverse 4.10.1 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-traverse",
-  "version": "4.10.1",
+  "version": "4.12.0",
   "description": "Traversal and visitor utilities for walking and transforming ApiDOM structures.",
   "keywords": [
     "apidom",
@@ -60,12 +60,12 @@
   "author": "Vladimir Gorej",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "4.10.1",
-    "@speclynx/apidom-error": "4.10.1",
-    "@speclynx/apidom-json-path": "4.10.1",
-    "@speclynx/apidom-json-pointer": "4.10.1",
-    "ramda-adjunct": "^6.0.0"
+    "@babel/runtime-corejs3": "^8.0.0",
+    "@speclynx/apidom-datamodel": "4.12.0",
+    "@speclynx/apidom-error": "4.12.0",
+    "@speclynx/apidom-json-path": "4.12.0",
+    "@speclynx/apidom-json-pointer": "4.12.0",
+    "ramda-adjunct": "^6.1.0"
   },
   "files": [
     "src/**/*.mjs",
@@ -77,5 +77,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "fb6a0a6f3f5da22443865a3ee73503d0a269c511"
+  "gitHead": "7d5549ba93000f249ebbe1480ae01d1aaeb2ce15"
 }

package/src/Path.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.Path = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
@@ -55,6 +57,14 @@ class Path {
    */
   inList;
 
+  /**
+   * True when this node is a non-descending revisit of an already-visited node
+   * (only under skipVisited: 'enter-only'). Children are not traversed.
+   * Set on both the enter and the matching leave phase, so it is meaningful
+   * in either phase.
+   */
+  revisited = false;
+
   /**
    * Internal state for traversal control.
    */

package/src/Path.mjs

@@ -52,6 +52,14 @@ export class Path {
    */
   inList;
 
+  /**
+   * True when this node is a non-descending revisit of an already-visited node
+   * (only under skipVisited: 'enter-only'). Children are not traversed.
+   * Set on both the enter and the matching leave phase, so it is meaningful
+   * in either phase.
+   */
+  revisited = false;
+
   /**
    * Internal state for traversal control.
    */

package/src/index.cjs

@@ -1,37 +1,133 @@
 "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;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Path", {
+  enumerable: true,
+  get: function () {
+    return _Path.Path;
+  }
+});
+Object.defineProperty(exports, "cloneNode", {
+  enumerable: true,
+  get: function () {
+    return _visitors.cloneNode;
+  }
+});
+Object.defineProperty(exports, "filter", {
+  enumerable: true,
+  get: function () {
+    return _filter.default;
+  }
+});
+Object.defineProperty(exports, "find", {
+  enumerable: true,
+  get: function () {
+    return _find.default;
+  }
+});
+Object.defineProperty(exports, "findAtOffset", {
+  enumerable: true,
+  get: function () {
+    return _findAtOffset.default;
+  }
+});
+Object.defineProperty(exports, "forEach", {
+  enumerable: true,
+  get: function () {
+    return _forEach.default;
+  }
+});
+Object.defineProperty(exports, "getNodeKeys", {
+  enumerable: true,
+  get: function () {
+    return _visitors.getNodeKeys;
+  }
+});
+Object.defineProperty(exports, "getNodePrimitiveType", {
+  enumerable: true,
+  get: function () {
+    return _visitors.getNodePrimitiveType;
+  }
+});
+Object.defineProperty(exports, "getNodeType", {
+  enumerable: true,
+  get: function () {
+    return _visitors.getNodeType;
+  }
+});
+Object.defineProperty(exports, "getVisitFn", {
+  enumerable: true,
+  get: function () {
+    return _visitors.getVisitFn;
+  }
+});
+Object.defineProperty(exports, "isNode", {
+  enumerable: true,
+  get: function () {
+    return _visitors.isNode;
+  }
+});
+Object.defineProperty(exports, "mergeVisitors", {
+  enumerable: true,
+  get: function () {
+    return _visitors.mergeVisitors;
+  }
+});
+Object.defineProperty(exports, "mergeVisitorsAsync", {
+  enumerable: true,
+  get: function () {
+    return _visitors.mergeVisitorsAsync;
+  }
+});
+Object.defineProperty(exports, "mutateNode", {
+  enumerable: true,
+  get: function () {
+    return _visitors.mutateNode;
+  }
+});
+Object.defineProperty(exports, "parents", {
+  enumerable: true,
+  get: function () {
+    return _parents.default;
+  }
+});
+Object.defineProperty(exports, "reject", {
+  enumerable: true,
+  get: function () {
+    return _reject.default;
+  }
+});
+Object.defineProperty(exports, "some", {
+  enumerable: true,
+  get: function () {
+    return _some.default;
+  }
+});
+Object.defineProperty(exports, "traverse", {
+  enumerable: true,
+  get: function () {
+    return _traversal.traverse;
+  }
+});
+Object.defineProperty(exports, "traverseAsync", {
+  enumerable: true,
+  get: function () {
+    return _traversal.traverseAsync;
+  }
+});
 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);

package/src/operations/filter.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _traversal = require("../traversal.cjs");
 /**

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

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _traversal = require("../traversal.cjs");

package/src/operations/find.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _traversal = require("../traversal.cjs");
 /**

package/src/operations/for-each.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _traversal = require("../traversal.cjs");
 /**

package/src/operations/parents.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _traversal = require("../traversal.cjs");
 /**

package/src/operations/reject.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _filter = _interopRequireDefault(require("./filter.cjs"));
 /**

package/src/operations/some.cjs

@@ -1,7 +1,9 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.default = void 0;
 var _find = _interopRequireDefault(require("./find.cjs"));
 /**

package/src/traversal.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.traverseAsync = exports.traverse = void 0;
 var _apidomError = require("@speclynx/apidom-error");
 var _ramdaAdjunct = require("ramda-adjunct");
@@ -12,6 +14,11 @@ var _visitors = require("./visitors.cjs");
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Controls handling of already-visited nodes during traversal.
+ * @public
+ */
+
 /**
  * Options for the traverse function.
  * @public
@@ -21,6 +28,11 @@ var _visitors = require("./visitors.cjs");
 // Internal types for generator
 // =============================================================================
 
+const normalizeSkipVisited = v => {
+  if (v === true) return 'skip';
+  if (v === false || v === undefined) return 'never';
+  return v;
+};
 // =============================================================================
 // Core generator
 // =============================================================================
@@ -38,7 +50,7 @@ function* traverseGenerator(root, visitor, options) {
     mutationFn
   } = options;
   const keyMapIsFunction = typeof keyMap === 'function';
-  const visitedNodes = skipVisited ? new WeakSet() : null;
+  const visitedNodes = skipVisited !== 'never' ? new WeakSet() : null;
   let stack;
   let inArray = Array.isArray(root);
   let keys = [root];
@@ -53,6 +65,7 @@ function* traverseGenerator(root, visitor, options) {
     index += 1;
     const isLeaving = index === keys.length;
     let key;
+    let revisitNoDescend = false;
     const isEdited = isLeaving && edits.length !== 0;
     if (isLeaving) {
       key = ancestors.length === 0 ? undefined : currentPath?.key;
@@ -94,6 +107,7 @@ function* traverseGenerator(root, visitor, options) {
         edits = stack.edits;
         const parentInArray = stack.inArray;
         parentPath = stack.parentPath;
+        revisitNoDescend = stack.revisitNoDescend;
         stack = stack.prev;
 
         // Push the edited node to parent's edits for propagation up the tree
@@ -125,15 +139,22 @@ function* traverseGenerator(root, visitor, options) {
       }
 
       // Skip already-visited nodes (handles DAG structures from cloneShallow)
-      if (skipVisited && !isLeaving) {
+      if (skipVisited !== 'never' && !isLeaving) {
         if (visitedNodes.has(node)) {
-          continue;
+          if (skipVisited === 'enter-only') {
+            // fire enter/leave for this occurrence, but don't re-descend
+            revisitNoDescend = true;
+          } else {
+            continue;
+          }
+        } else {
+          visitedNodes.add(node);
         }
-        visitedNodes.add(node);
       }
 
       // Always create Path for the current node (needed for parentPath chain)
       currentPath = new _Path.Path(node, parent, parentPath, key, inArray);
+      currentPath.revisited = revisitNoDescend;
       const visitFn = (0, _visitors.getVisitFn)(visitor, nodeTypeGetter(node), isLeaving);
       if (visitFn) {
         // Assign state to visitor
@@ -197,10 +218,13 @@ function* traverseGenerator(root, visitor, options) {
         keys,
         edits,
         parentPath,
+        revisitNoDescend,
         prev: stack
       };
       inArray = Array.isArray(node);
-      if (inArray) {
+      if (revisitNoDescend) {
+        keys = [];
+      } else if (inArray) {
         keys = node;
       } else if (keyMapIsFunction) {
         keys = keyMap(node);
@@ -275,7 +299,7 @@ const traverse = (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors.cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors.mutateNode
   };
@@ -308,7 +332,7 @@ const traverseAsync = async (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors.cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors.mutateNode
   };

package/src/traversal.mjs

@@ -8,6 +8,10 @@ import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { isPromise } from 'ramda-adjunct';
 import { Path } from "./Path.mjs";
 import { getNodeType, isNode, cloneNode, mutateNode, getVisitFn, getNodeKeys } from "./visitors.mjs";
+/**
+ * Controls handling of already-visited nodes during traversal.
+ * @public
+ */
 /**
  * Options for the traverse function.
  * @public
@@ -15,6 +19,12 @@ import { getNodeType, isNode, cloneNode, mutateNode, getVisitFn, getNodeKeys } f
 // =============================================================================
 // Internal types for generator
 // =============================================================================
+
+const normalizeSkipVisited = v => {
+  if (v === true) return 'skip';
+  if (v === false || v === undefined) return 'never';
+  return v;
+};
 // =============================================================================
 // Core generator
 // =============================================================================
@@ -32,7 +42,7 @@ function* traverseGenerator(root, visitor, options) {
     mutationFn
   } = options;
   const keyMapIsFunction = typeof keyMap === 'function';
-  const visitedNodes = skipVisited ? new WeakSet() : null;
+  const visitedNodes = skipVisited !== 'never' ? new WeakSet() : null;
   let stack;
   let inArray = Array.isArray(root);
   let keys = [root];
@@ -47,6 +57,7 @@ function* traverseGenerator(root, visitor, options) {
     index += 1;
     const isLeaving = index === keys.length;
     let key;
+    let revisitNoDescend = false;
     const isEdited = isLeaving && edits.length !== 0;
     if (isLeaving) {
       key = ancestors.length === 0 ? undefined : currentPath?.key;
@@ -88,6 +99,7 @@ function* traverseGenerator(root, visitor, options) {
         edits = stack.edits;
         const parentInArray = stack.inArray;
         parentPath = stack.parentPath;
+        revisitNoDescend = stack.revisitNoDescend;
         stack = stack.prev;
 
         // Push the edited node to parent's edits for propagation up the tree
@@ -119,15 +131,22 @@ function* traverseGenerator(root, visitor, options) {
       }
 
       // Skip already-visited nodes (handles DAG structures from cloneShallow)
-      if (skipVisited && !isLeaving) {
+      if (skipVisited !== 'never' && !isLeaving) {
         if (visitedNodes.has(node)) {
-          continue;
+          if (skipVisited === 'enter-only') {
+            // fire enter/leave for this occurrence, but don't re-descend
+            revisitNoDescend = true;
+          } else {
+            continue;
+          }
+        } else {
+          visitedNodes.add(node);
         }
-        visitedNodes.add(node);
       }
 
       // Always create Path for the current node (needed for parentPath chain)
       currentPath = new Path(node, parent, parentPath, key, inArray);
+      currentPath.revisited = revisitNoDescend;
       const visitFn = getVisitFn(visitor, nodeTypeGetter(node), isLeaving);
       if (visitFn) {
         // Assign state to visitor
@@ -191,10 +210,13 @@ function* traverseGenerator(root, visitor, options) {
         keys,
         edits,
         parentPath,
+        revisitNoDescend,
         prev: stack
       };
       inArray = Array.isArray(node);
-      if (inArray) {
+      if (revisitNoDescend) {
+        keys = [];
+      } else if (inArray) {
         keys = node;
       } else if (keyMapIsFunction) {
         keys = keyMap(node);
@@ -269,7 +291,7 @@ export const traverse = (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? isNode,
     nodeCloneFn: options.nodeCloneFn ?? cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? mutateNode
   };
@@ -301,7 +323,7 @@ export const traverseAsync = async (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? isNode,
     nodeCloneFn: options.nodeCloneFn ?? cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? mutateNode
   };

package/src/visitors.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
-exports.__esModule = true;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
 exports.mutateNode = exports.mergeVisitorsAsync = exports.mergeVisitors = exports.isNode = exports.getVisitFn = exports.getNodeType = exports.getNodePrimitiveType = exports.getNodeKeys = exports.cloneNode = void 0;
 var _apidomError = require("@speclynx/apidom-error");
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
@@ -440,5 +442,7 @@ mergeVisitors[Symbol.for('nodejs.util.promisify.custom')] = mergeVisitorsAsync;
  * @internal
  */
 function createPathProxy(originalPath, currentNode) {
-  return new _Path.Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  const proxy = new _Path.Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  proxy.revisited = originalPath.revisited;
+  return proxy;
 }

package/src/visitors.mjs

@@ -427,5 +427,7 @@ mergeVisitors[Symbol.for('nodejs.util.promisify.custom')] = mergeVisitorsAsync;
  * @internal
  */
 function createPathProxy(originalPath, currentNode) {
-  return new Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  const proxy = new Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  proxy.revisited = originalPath.revisited;
+  return proxy;
 }

package/types/apidom-traverse.d.ts

@@ -196,6 +196,13 @@ export declare class Path<TNode = Element_2> {
      * Whether this node is inside an array in the parent.
      */
     readonly inList: boolean;
+    /**
+     * True when this node is a non-descending revisit of an already-visited node
+     * (only under skipVisited: 'enter-only'). Children are not traversed.
+     * Set on both the enter and the matching leave phase, so it is meaningful
+     * in either phase.
+     */
+    revisited: boolean;
     constructor(node: TNode, parent: TNode | undefined, parentPath: Path<TNode> | null, key: PropertyKey | undefined, inList: boolean);
     /**
      * Whether skip() was called on this path.
@@ -321,6 +328,17 @@ export declare class Path<TNode = Element_2> {
  */
 export declare const reject: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2>[];
 
+/**
+ * SPDX-FileCopyrightText: Copyright (c) GraphQL Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Controls handling of already-visited nodes during traversal.
+ * @public
+ */
+export declare type SkipVisitedMode = 'never' | 'skip' | 'enter-only';
+
 /**
  * Tests whether at least one path's element passes the predicate.
  * @public
@@ -375,11 +393,6 @@ export declare const traverse: <TNode>(root: TNode, visitor: object, options?: T
  */
 export declare const traverseAsync: <TNode>(root: TNode, visitor: object, options?: TraverseOptions<TNode>) => Promise<TNode>;
 
-/**
- * SPDX-FileCopyrightText: Copyright (c) GraphQL Contributors
- *
- * SPDX-License-Identifier: MIT
- */
 /**
  * Options for the traverse function.
  * @public
@@ -412,13 +425,21 @@ export declare interface TraverseOptions<TNode> {
      */
     detectCycles?: boolean;
     /**
-     * Whether to skip already-visited nodes. Defaults to false.
-     * When true, uses a WeakSet to track visited nodes and skips any node
-     * encountered a second time, regardless of the path taken to reach it.
+     * Controls handling of already-visited nodes (by identity, via a WeakSet).
+     * Defaults to 'never'.
+     * - 'never'      : no skipping (default).
+     * - 'skip'       : skip the node entirely on re-encounter (no enter/leave, no descent).
+     * - 'enter-only' : on re-encounter still fire enter/leave, but DO NOT descend into
+     *                  the (already-walked) subtree. Lets visitors observe every
+     *                  occurrence of a shared node while preserving the
+     *                  no-combinatorial-explosion guarantee.
      * Useful for traversing dereferenced trees that contain shared structure
      * from cloneShallow (DAG) which would otherwise cause combinatorial explosion.
+     *
+     * Legacy booleans are still accepted at runtime for backward compatibility:
+     * `false` maps to 'never' and `true` maps to 'skip'.
      */
-    skipVisited?: boolean;
+    skipVisited?: SkipVisitedMode;
     /**
      * If true, edits modify the original tree in place.
      * If false (default), creates a new tree with changes applied.