@speclynx/apidom-traverse 4.10.1 → 4.12.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.12.0](https://github.com/speclynx/apidom/compare/v4.11.1...v4.12.0) (2026-06-23)
+
+**Note:** Version bump only for package @speclynx/apidom-traverse
+
+## [4.11.1](https://github.com/speclynx/apidom/compare/v4.11.0...v4.11.1) (2026-06-10)
+
+**Note:** Version bump only for package @speclynx/apidom-traverse
+
+# [4.11.0](https://github.com/speclynx/apidom/compare/v4.10.1...v4.11.0) (2026-06-10)
+
+### Features
+
+- **traverse:** skipVisited 'enter-only' mode and path.revisited ([#333](https://github.com/speclynx/apidom/issues/333)) ([fe944df](https://github.com/speclynx/apidom/commit/fe944df0eaab437a65d5761e6a3e14d490d2d3d6))
+
 ## [4.10.1](https://github.com/speclynx/apidom/compare/v4.10.0...v4.10.1) (2026-05-20)
 
 **Note:** Version bump only for package @speclynx/apidom-traverse

package/dist/apidom-traverse.browser.js

@@ -76,6 +76,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.
    */
@@ -609,6 +617,11 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/**
+ * Controls handling of already-visited nodes during traversal.
+ * @public
+ */
+
 /**
  * Options for the traverse function.
  * @public
@@ -618,6 +631,11 @@ __webpack_require__.r(__webpack_exports__);
 // Internal types for generator
 // =============================================================================
 
+const normalizeSkipVisited = v => {
+  if (v === true) return 'skip';
+  if (v === false || v === undefined) return 'never';
+  return v;
+};
 // =============================================================================
 // Core generator
 // =============================================================================
@@ -635,7 +653,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];
@@ -650,6 +668,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;
@@ -691,6 +710,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
@@ -722,15 +742,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_ts__WEBPACK_IMPORTED_MODULE_2__.Path(node, parent, parentPath, key, inArray);
+      currentPath.revisited = revisitNoDescend;
       const visitFn = (0,_visitors_ts__WEBPACK_IMPORTED_MODULE_3__.getVisitFn)(visitor, nodeTypeGetter(node), isLeaving);
       if (visitFn) {
         // Assign state to visitor
@@ -794,10 +821,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);
@@ -872,7 +902,7 @@ const traverse = (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };
@@ -904,7 +934,7 @@ const traverseAsync = async (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
-    skipVisited: options.skipVisited ?? false,
+    skipVisited: normalizeSkipVisited(options.skipVisited),
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_ts__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };
@@ -1374,7 +1404,9 @@ mergeVisitors[Symbol.for('nodejs.util.promisify.custom')] = mergeVisitorsAsync;
  * @internal
  */
 function createPathProxy(originalPath, currentNode) {
-  return new _Path_ts__WEBPACK_IMPORTED_MODULE_4__.Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  const proxy = new _Path_ts__WEBPACK_IMPORTED_MODULE_4__.Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+  proxy.revisited = originalPath.revisited;
+  return proxy;
 }
 
 /***/ },