@speclynx/apidom-traverse 1.12.2

package/src/traversal.cjs

@@ -0,0 +1,313 @@
+"use strict";
+
+exports.__esModule = true;
+exports.traverseAsync = exports.traverse = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _Path = require("./Path.cjs");
+var _visitors = require("./visitors.cjs");
+/**
+ * SPDX-FileCopyrightText: Copyright (c) GraphQL Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Options for the traverse function.
+ * @public
+ */
+
+// =============================================================================
+// Internal types for generator
+// =============================================================================
+
+// =============================================================================
+// Core generator
+// =============================================================================
+
+function* traverseGenerator(root, visitor, options) {
+  const {
+    keyMap,
+    state,
+    nodeTypeGetter,
+    nodePredicate,
+    nodeCloneFn,
+    detectCycles,
+    mutable,
+    mutationFn
+  } = options;
+  const keyMapIsFunction = typeof keyMap === 'function';
+  let stack;
+  let inArray = Array.isArray(root);
+  let keys = [root];
+  let index = -1;
+  let parent;
+  let edits = [];
+  let node = root;
+  let currentPath = null;
+  let parentPath = null;
+  const ancestors = [];
+  do {
+    index += 1;
+    const isLeaving = index === keys.length;
+    let key;
+    const isEdited = isLeaving && edits.length !== 0;
+    if (isLeaving) {
+      key = ancestors.length === 0 ? undefined : currentPath?.key;
+      node = parent;
+      parent = ancestors.pop();
+      parentPath = currentPath?.parentPath?.parentPath ?? null;
+      if (isEdited) {
+        if (mutable) {
+          // Mutable mode: modify in place using mutationFn
+          for (const [editKey, editValue] of edits) {
+            mutationFn(node, editKey, editValue);
+          }
+        } else {
+          // Immutable mode: clone then modify
+          if (inArray) {
+            node = node.slice();
+            let editOffset = 0;
+            for (const [editKey, editValue] of edits) {
+              const arrayKey = editKey - editOffset;
+              if (editValue === null) {
+                node.splice(arrayKey, 1);
+                editOffset += 1;
+              } else {
+                node[arrayKey] = editValue;
+              }
+            }
+          } else {
+            node = nodeCloneFn(node);
+            for (const [editKey, editValue] of edits) {
+              node[editKey] = editValue;
+            }
+          }
+        }
+      }
+      if (stack !== undefined) {
+        // Restore parent's state
+        index = stack.index;
+        keys = stack.keys;
+        edits = stack.edits;
+        const parentInArray = stack.inArray;
+        parentPath = stack.parentPath;
+        stack = stack.prev;
+
+        // Push the edited node to parent's edits for propagation up the tree
+        // Use the restored index to get the correct key for this node in its parent
+        // Only needed in immutable mode - mutable mode modifies in place
+        if (isEdited && !mutable) {
+          const editKey = parentInArray ? index : keys[index];
+          edits.push([editKey, node]);
+        }
+        inArray = parentInArray;
+      }
+    } else if (parent !== undefined) {
+      key = inArray ? index : keys[index];
+      node = parent[key];
+      if (node === undefined) {
+        continue;
+      }
+    }
+    if (!Array.isArray(node)) {
+      if (!nodePredicate(node)) {
+        throw new _apidomError.ApiDOMStructuredError(`Invalid AST Node: ${String(node)}`, {
+          node
+        });
+      }
+
+      // Cycle detection
+      if (detectCycles && ancestors.includes(node)) {
+        continue;
+      }
+
+      // Always create Path for the current node (needed for parentPath chain)
+      currentPath = new _Path.Path(node, parent, parentPath, key, inArray);
+      const visitFn = (0, _visitors.getVisitFn)(visitor, nodeTypeGetter(node), isLeaving);
+      if (visitFn) {
+        // Assign state to visitor
+        for (const [stateKey, stateValue] of Object.entries(state)) {
+          visitor[stateKey] = stateValue;
+        }
+
+        // Yield to caller to execute visitor
+        const result = yield {
+          visitFn,
+          path: currentPath,
+          isLeaving
+        };
+
+        // Handle path-based control flow
+        if (currentPath.shouldStop) {
+          break;
+        }
+        if (currentPath.shouldSkip) {
+          if (!isLeaving) {
+            continue;
+          }
+        }
+        if (currentPath.removed) {
+          edits.push([key, null]);
+          if (!isLeaving) {
+            continue;
+          }
+        } else if (currentPath._wasReplaced()) {
+          const replacement = currentPath._getReplacementNode();
+          edits.push([key, replacement]);
+          if (!isLeaving) {
+            if (nodePredicate(replacement)) {
+              node = replacement;
+            } else {
+              continue;
+            }
+          }
+        } else if (result !== undefined) {
+          // Support return value replacement for backwards compatibility
+          edits.push([key, result]);
+          if (!isLeaving) {
+            if (nodePredicate(result)) {
+              node = result;
+            } else {
+              continue;
+            }
+          }
+        }
+
+        // Mark path as stale after processing - warns if used from child visitors
+        currentPath._markStale();
+      }
+    }
+    if (!isLeaving) {
+      stack = {
+        inArray,
+        index,
+        keys,
+        edits,
+        parentPath,
+        prev: stack
+      };
+      inArray = Array.isArray(node);
+      if (inArray) {
+        keys = node;
+      } else if (keyMapIsFunction) {
+        keys = keyMap(node);
+      } else {
+        const nodeType = nodeTypeGetter(node);
+        keys = nodeType !== undefined ? keyMap[nodeType] ?? [] : [];
+      }
+      index = -1;
+      edits = [];
+      if (parent !== undefined) {
+        ancestors.push(parent);
+      }
+      parent = node;
+      parentPath = currentPath;
+    }
+  } while (stack !== undefined);
+  if (edits.length !== 0) {
+    return edits.at(-1)[1];
+  }
+  return root;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * traverse() walks through a tree using preorder depth-first traversal, calling
+ * the visitor's enter function at each node, and calling leave after visiting
+ * that node and all its children.
+ *
+ * Visitors receive a Path object with:
+ * - `path.node` - the current node
+ * - `path.parent` - the parent node
+ * - `path.key` - key in parent
+ * - `path.parentPath` - parent Path (linked list structure)
+ * - `path.replaceWith(node)` - replace current node
+ * - `path.remove()` - remove current node
+ * - `path.skip()` - skip children (enter only)
+ * - `path.stop()` - stop all traversal
+ *
+ * When editing, the original tree is not modified. A new version with changes
+ * applied is returned.
+ *
+ * @example
+ * ```typescript
+ * const edited = traverse(ast, {
+ *   enter(path) {
+ *     console.log(path.node);
+ *     if (shouldSkip) path.skip();
+ *     if (shouldReplace) path.replaceWith(newNode);
+ *   },
+ *   leave(path) {
+ *     if (shouldRemove) path.remove();
+ *   }
+ * });
+ * ```
+ *
+ * Visitor patterns supported:
+ * 1. `{ Kind(path) {} }` - enter specific node type
+ * 2. `{ Kind: { enter(path) {}, leave(path) {} } }` - enter/leave specific type
+ * 3. `{ enter(path) {}, leave(path) {} }` - enter/leave any node
+ * 4. `{ enter: { Kind(path) {} }, leave: { Kind(path) {} } }` - parallel style
+ *
+ * @public
+ */
+const traverse = (root, visitor, options = {}) => {
+  const resolvedOptions = {
+    keyMap: options.keyMap ?? _visitors.getNodeKeys,
+    state: options.state ?? {},
+    nodeTypeGetter: options.nodeTypeGetter ?? _visitors.getNodeType,
+    nodePredicate: options.nodePredicate ?? _visitors.isNode,
+    nodeCloneFn: options.nodeCloneFn ?? _visitors.cloneNode,
+    detectCycles: options.detectCycles ?? true,
+    mutable: options.mutable ?? false,
+    mutationFn: options.mutationFn ?? _visitors.mutateNode
+  };
+  const generator = traverseGenerator(root, visitor, resolvedOptions);
+  let step = generator.next();
+  while (!step.done) {
+    const call = step.value;
+    const result = call.visitFn.call(visitor, call.path);
+    if ((0, _ramdaAdjunct.isPromise)(result)) {
+      throw new _apidomError.ApiDOMStructuredError('Async visitor not supported in sync mode', {
+        visitor,
+        visitFn: call.visitFn
+      });
+    }
+    step = generator.next(result);
+  }
+  return step.value;
+};
+
+/**
+ * Async version of traverse().
+ * @public
+ */
+exports.traverse = traverse;
+const traverseAsync = async (root, visitor, options = {}) => {
+  const resolvedOptions = {
+    keyMap: options.keyMap ?? _visitors.getNodeKeys,
+    state: options.state ?? {},
+    nodeTypeGetter: options.nodeTypeGetter ?? _visitors.getNodeType,
+    nodePredicate: options.nodePredicate ?? _visitors.isNode,
+    nodeCloneFn: options.nodeCloneFn ?? _visitors.cloneNode,
+    detectCycles: options.detectCycles ?? true,
+    mutable: options.mutable ?? false,
+    mutationFn: options.mutationFn ?? _visitors.mutateNode
+  };
+  const generator = traverseGenerator(root, visitor, resolvedOptions);
+  let step = generator.next();
+  while (!step.done) {
+    const call = step.value;
+    const result = await call.visitFn.call(visitor, call.path);
+    step = generator.next(result);
+  }
+  return step.value;
+};
+
+// Attach async version for promisify compatibility
+exports.traverseAsync = traverseAsync;
+traverse[Symbol.for('nodejs.util.promisify.custom')] = traverseAsync;

package/src/traversal.mjs

@@ -0,0 +1,305 @@
+/**
+ * SPDX-FileCopyrightText: Copyright (c) GraphQL Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+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";
+/**
+ * Options for the traverse function.
+ * @public
+ */
+// =============================================================================
+// Internal types for generator
+// =============================================================================
+// =============================================================================
+// Core generator
+// =============================================================================
+
+function* traverseGenerator(root, visitor, options) {
+  const {
+    keyMap,
+    state,
+    nodeTypeGetter,
+    nodePredicate,
+    nodeCloneFn,
+    detectCycles,
+    mutable,
+    mutationFn
+  } = options;
+  const keyMapIsFunction = typeof keyMap === 'function';
+  let stack;
+  let inArray = Array.isArray(root);
+  let keys = [root];
+  let index = -1;
+  let parent;
+  let edits = [];
+  let node = root;
+  let currentPath = null;
+  let parentPath = null;
+  const ancestors = [];
+  do {
+    index += 1;
+    const isLeaving = index === keys.length;
+    let key;
+    const isEdited = isLeaving && edits.length !== 0;
+    if (isLeaving) {
+      key = ancestors.length === 0 ? undefined : currentPath?.key;
+      node = parent;
+      parent = ancestors.pop();
+      parentPath = currentPath?.parentPath?.parentPath ?? null;
+      if (isEdited) {
+        if (mutable) {
+          // Mutable mode: modify in place using mutationFn
+          for (const [editKey, editValue] of edits) {
+            mutationFn(node, editKey, editValue);
+          }
+        } else {
+          // Immutable mode: clone then modify
+          if (inArray) {
+            node = node.slice();
+            let editOffset = 0;
+            for (const [editKey, editValue] of edits) {
+              const arrayKey = editKey - editOffset;
+              if (editValue === null) {
+                node.splice(arrayKey, 1);
+                editOffset += 1;
+              } else {
+                node[arrayKey] = editValue;
+              }
+            }
+          } else {
+            node = nodeCloneFn(node);
+            for (const [editKey, editValue] of edits) {
+              node[editKey] = editValue;
+            }
+          }
+        }
+      }
+      if (stack !== undefined) {
+        // Restore parent's state
+        index = stack.index;
+        keys = stack.keys;
+        edits = stack.edits;
+        const parentInArray = stack.inArray;
+        parentPath = stack.parentPath;
+        stack = stack.prev;
+
+        // Push the edited node to parent's edits for propagation up the tree
+        // Use the restored index to get the correct key for this node in its parent
+        // Only needed in immutable mode - mutable mode modifies in place
+        if (isEdited && !mutable) {
+          const editKey = parentInArray ? index : keys[index];
+          edits.push([editKey, node]);
+        }
+        inArray = parentInArray;
+      }
+    } else if (parent !== undefined) {
+      key = inArray ? index : keys[index];
+      node = parent[key];
+      if (node === undefined) {
+        continue;
+      }
+    }
+    if (!Array.isArray(node)) {
+      if (!nodePredicate(node)) {
+        throw new ApiDOMStructuredError(`Invalid AST Node: ${String(node)}`, {
+          node
+        });
+      }
+
+      // Cycle detection
+      if (detectCycles && ancestors.includes(node)) {
+        continue;
+      }
+
+      // Always create Path for the current node (needed for parentPath chain)
+      currentPath = new Path(node, parent, parentPath, key, inArray);
+      const visitFn = getVisitFn(visitor, nodeTypeGetter(node), isLeaving);
+      if (visitFn) {
+        // Assign state to visitor
+        for (const [stateKey, stateValue] of Object.entries(state)) {
+          visitor[stateKey] = stateValue;
+        }
+
+        // Yield to caller to execute visitor
+        const result = yield {
+          visitFn,
+          path: currentPath,
+          isLeaving
+        };
+
+        // Handle path-based control flow
+        if (currentPath.shouldStop) {
+          break;
+        }
+        if (currentPath.shouldSkip) {
+          if (!isLeaving) {
+            continue;
+          }
+        }
+        if (currentPath.removed) {
+          edits.push([key, null]);
+          if (!isLeaving) {
+            continue;
+          }
+        } else if (currentPath._wasReplaced()) {
+          const replacement = currentPath._getReplacementNode();
+          edits.push([key, replacement]);
+          if (!isLeaving) {
+            if (nodePredicate(replacement)) {
+              node = replacement;
+            } else {
+              continue;
+            }
+          }
+        } else if (result !== undefined) {
+          // Support return value replacement for backwards compatibility
+          edits.push([key, result]);
+          if (!isLeaving) {
+            if (nodePredicate(result)) {
+              node = result;
+            } else {
+              continue;
+            }
+          }
+        }
+
+        // Mark path as stale after processing - warns if used from child visitors
+        currentPath._markStale();
+      }
+    }
+    if (!isLeaving) {
+      stack = {
+        inArray,
+        index,
+        keys,
+        edits,
+        parentPath,
+        prev: stack
+      };
+      inArray = Array.isArray(node);
+      if (inArray) {
+        keys = node;
+      } else if (keyMapIsFunction) {
+        keys = keyMap(node);
+      } else {
+        const nodeType = nodeTypeGetter(node);
+        keys = nodeType !== undefined ? keyMap[nodeType] ?? [] : [];
+      }
+      index = -1;
+      edits = [];
+      if (parent !== undefined) {
+        ancestors.push(parent);
+      }
+      parent = node;
+      parentPath = currentPath;
+    }
+  } while (stack !== undefined);
+  if (edits.length !== 0) {
+    return edits.at(-1)[1];
+  }
+  return root;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * traverse() walks through a tree using preorder depth-first traversal, calling
+ * the visitor's enter function at each node, and calling leave after visiting
+ * that node and all its children.
+ *
+ * Visitors receive a Path object with:
+ * - `path.node` - the current node
+ * - `path.parent` - the parent node
+ * - `path.key` - key in parent
+ * - `path.parentPath` - parent Path (linked list structure)
+ * - `path.replaceWith(node)` - replace current node
+ * - `path.remove()` - remove current node
+ * - `path.skip()` - skip children (enter only)
+ * - `path.stop()` - stop all traversal
+ *
+ * When editing, the original tree is not modified. A new version with changes
+ * applied is returned.
+ *
+ * @example
+ * ```typescript
+ * const edited = traverse(ast, {
+ *   enter(path) {
+ *     console.log(path.node);
+ *     if (shouldSkip) path.skip();
+ *     if (shouldReplace) path.replaceWith(newNode);
+ *   },
+ *   leave(path) {
+ *     if (shouldRemove) path.remove();
+ *   }
+ * });
+ * ```
+ *
+ * Visitor patterns supported:
+ * 1. `{ Kind(path) {} }` - enter specific node type
+ * 2. `{ Kind: { enter(path) {}, leave(path) {} } }` - enter/leave specific type
+ * 3. `{ enter(path) {}, leave(path) {} }` - enter/leave any node
+ * 4. `{ enter: { Kind(path) {} }, leave: { Kind(path) {} } }` - parallel style
+ *
+ * @public
+ */
+export const traverse = (root, visitor, options = {}) => {
+  const resolvedOptions = {
+    keyMap: options.keyMap ?? getNodeKeys,
+    state: options.state ?? {},
+    nodeTypeGetter: options.nodeTypeGetter ?? getNodeType,
+    nodePredicate: options.nodePredicate ?? isNode,
+    nodeCloneFn: options.nodeCloneFn ?? cloneNode,
+    detectCycles: options.detectCycles ?? true,
+    mutable: options.mutable ?? false,
+    mutationFn: options.mutationFn ?? mutateNode
+  };
+  const generator = traverseGenerator(root, visitor, resolvedOptions);
+  let step = generator.next();
+  while (!step.done) {
+    const call = step.value;
+    const result = call.visitFn.call(visitor, call.path);
+    if (isPromise(result)) {
+      throw new ApiDOMStructuredError('Async visitor not supported in sync mode', {
+        visitor,
+        visitFn: call.visitFn
+      });
+    }
+    step = generator.next(result);
+  }
+  return step.value;
+};
+
+/**
+ * Async version of traverse().
+ * @public
+ */
+export const traverseAsync = async (root, visitor, options = {}) => {
+  const resolvedOptions = {
+    keyMap: options.keyMap ?? getNodeKeys,
+    state: options.state ?? {},
+    nodeTypeGetter: options.nodeTypeGetter ?? getNodeType,
+    nodePredicate: options.nodePredicate ?? isNode,
+    nodeCloneFn: options.nodeCloneFn ?? cloneNode,
+    detectCycles: options.detectCycles ?? true,
+    mutable: options.mutable ?? false,
+    mutationFn: options.mutationFn ?? mutateNode
+  };
+  const generator = traverseGenerator(root, visitor, resolvedOptions);
+  let step = generator.next();
+  while (!step.done) {
+    const call = step.value;
+    const result = await call.visitFn.call(visitor, call.path);
+    step = generator.next(result);
+  }
+  return step.value;
+};
+
+// Attach async version for promisify compatibility
+traverse[Symbol.for('nodejs.util.promisify.custom')] = traverseAsync;