@speclynx/apidom-traverse 1.12.2

package/src/visitors.mjs

@@ -0,0 +1,407 @@
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { isElement, isMemberElement, isArrayElement, isObjectElement, cloneShallow } from '@speclynx/apidom-datamodel';
+import { isPromise } from 'ramda-adjunct';
+import { Path } from "./Path.mjs";
+/**
+ * Enter/leave visitor structure for a specific node type.
+ * @public
+ */
+// =============================================================================
+// Default implementations for ApiDOM
+// =============================================================================
+
+/**
+ * Default node type getter - reads the `element` property and converts to Element class name.
+ * E.g., "string" -\> "StringElement", "openApi3_1" -\> "OpenApi3_1Element"
+ * @public
+ */
+export const getNodeType = node => {
+  const type = node?.element;
+  if (type === undefined || type === 'element') return 'Element';
+  return `${type.charAt(0).toUpperCase()}${type.slice(1)}Element`;
+};
+
+/**
+ * Alternative node type getter using primitive type.
+ * Returns the base element class name based on the node's primitive type.
+ * E.g., ContactElement (primitive='object') -\> "ObjectElement"
+ *
+ * Use this with `nodeTypeGetter` option when you want polymorphic behavior
+ * where specific elements fall back to their primitive type handlers.
+ * @public
+ */
+export const getNodePrimitiveType = node => {
+  const type = node.primitive();
+  if (type === undefined || type === 'element') return 'Element';
+  return `${type.charAt(0).toUpperCase()}${type.slice(1)}Element`;
+};
+
+/**
+ * Default node predicate - checks if value is an ApiDOM Element.
+ * @public
+ */
+export const isNode = value => isElement(value);
+
+/**
+ * Default node clone function - creates a shallow clone of ApiDOM Elements.
+ * Uses cloneShallow from apidom-datamodel for proper handling of meta/attributes.
+ * @public
+ */
+export const cloneNode = node => cloneShallow(node);
+
+/**
+ * Default mutation function that handles ApiDOM structures.
+ * - MemberElement: sets parent.value
+ * - Arrays: sets parent[key]
+ * - Objects: sets parent[key] or deletes if null
+ * @public
+ */
+export const mutateNode = (parent, key, value) => {
+  if (isMemberElement(parent)) {
+    // MemberElement stores value in .value property
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    parent.value = value;
+  } else if (Array.isArray(parent)) {
+    if (value === null) {
+      // For arrays, set to undefined (caller handles cleanup)
+      parent[key] = undefined;
+    } else {
+      parent[key] = value;
+    }
+  } else if (value === null) {
+    delete parent[key];
+  } else {
+    parent[key] = value;
+  }
+};
+
+/**
+ * Default function to get traversable keys for a node.
+ * Uses predicates to handle all ApiDOM element types automatically.
+ * @public
+ */
+export const getNodeKeys = node => {
+  if (isMemberElement(node)) return ['key', 'value'];
+  if (isArrayElement(node) || isObjectElement(node)) return ['content'];
+  return [];
+};
+
+// =============================================================================
+// Visitor function resolution
+// =============================================================================
+
+/**
+ * Lookup by type with pipe-separated key support ("TypeA|TypeB").
+ * Optimized: no array allocations, uses indexOf + boundary checks.
+ */
+const lookup = (record, type) => {
+  // Fast path: exact match
+  if (record[type] !== undefined) return record[type];
+
+  // Slow path: check pipe-separated keys
+  const len = type.length;
+  for (const key in record) {
+    // Skip keys without pipe (most common case)
+    if (!key.includes('|')) continue;
+    const idx = key.indexOf(type);
+    if (idx === -1) continue;
+
+    // Verify it's a complete segment (bounded by | or string edges)
+    const before = idx === 0 || key[idx - 1] === '|';
+    const after = idx + len === key.length || key[idx + len] === '|';
+    if (before && after) return record[key];
+  }
+  return undefined;
+};
+
+/**
+ * Gets the appropriate visitor function for a node type and phase.
+ * Supports pipe-separated type keys like "TypeA|TypeB".
+ * @public
+ */
+export const getVisitFn = (visitor, type, isLeaving) => {
+  if (type === undefined) return null;
+  const visitorRecord = visitor;
+  const phase = isLeaving ? 'leave' : 'enter';
+
+  // Pattern 1: { Type() {} } - shorthand for enter only
+  const typeVisitor = lookup(visitorRecord, type);
+  if (!isLeaving && typeof typeVisitor === 'function') {
+    return typeVisitor;
+  }
+
+  // Pattern 2: { Type: { enter, leave } }
+  if (typeVisitor != null) {
+    const phaseVisitor = typeVisitor[phase];
+    if (typeof phaseVisitor === 'function') {
+      return phaseVisitor;
+    }
+  }
+
+  // Pattern 3: { enter() {}, leave() {} }
+  const genericVisitor = visitorRecord[phase];
+  if (typeof genericVisitor === 'function') {
+    return genericVisitor;
+  }
+
+  // Pattern 4: { enter: { Type() {} } }
+  if (genericVisitor != null) {
+    const typeInPhase = lookup(genericVisitor, type);
+    if (typeof typeInPhase === 'function') {
+      return typeInPhase;
+    }
+  }
+  return null;
+};
+
+// =============================================================================
+// Visitor merging
+// =============================================================================
+
+/**
+ * Options for mergeVisitors.
+ * @public
+ */
+
+/**
+ * Sync version of merged visitor.
+ * @public
+ */
+
+/**
+ * Async version of merged visitor.
+ * @public
+ */
+
+/**
+ * Creates a new visitor instance which delegates to many visitors to run in
+ * parallel. Each visitor will be visited for each node before moving on.
+ *
+ * If a prior visitor edits a node, no following visitors will see that node.
+ * `exposeEdits=true` can be used to expose the edited node from the previous visitors.
+ * @public
+ */
+export const mergeVisitors = (visitors, options = {}) => {
+  const {
+    visitFnGetter = getVisitFn,
+    nodeTypeGetter = getNodeType,
+    exposeEdits = false
+  } = options;
+
+  // Internal symbols for tracking visitor state
+  const internalSkipSymbol = Symbol('internal-skip');
+  const breakSymbol = Symbol('break');
+  // Tracks which visitors should be skipped for current subtree or permanently stopped
+  const skipping = new Array(visitors.length).fill(internalSkipSymbol);
+  return {
+    enter(path) {
+      let currentNode = path.node;
+      let hasChanged = false;
+      for (let i = 0; i < visitors.length; i += 1) {
+        if (skipping[i] === internalSkipSymbol) {
+          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), false);
+          if (typeof visitFn === 'function') {
+            // Create a proxy path that tracks changes per-visitor
+            const proxyPath = createPathProxy(path, currentNode);
+            const result = visitFn.call(visitors[i], proxyPath);
+
+            // Check if the visitor is async
+            if (isPromise(result)) {
+              throw new ApiDOMStructuredError('Async visitor not supported in sync mode', {
+                visitor: visitors[i],
+                visitFn
+              });
+            }
+
+            // Handle path-based control flow
+            if (proxyPath.shouldStop) {
+              skipping[i] = breakSymbol;
+              break;
+            }
+            if (proxyPath.shouldSkip) {
+              skipping[i] = currentNode;
+            }
+            if (proxyPath.removed) {
+              path.remove();
+              return undefined;
+            }
+            if (proxyPath._wasReplaced()) {
+              const replacement = proxyPath._getReplacementNode();
+              if (exposeEdits) {
+                currentNode = replacement;
+                hasChanged = true;
+              } else {
+                path.replaceWith(replacement);
+                return replacement;
+              }
+            } else if (result !== undefined) {
+              // Support return value replacement for backwards compatibility
+              if (exposeEdits) {
+                currentNode = result;
+                hasChanged = true;
+              } else {
+                path.replaceWith(result);
+                return result;
+              }
+            }
+          }
+        }
+      }
+      if (hasChanged) {
+        path.replaceWith(currentNode);
+        return currentNode;
+      }
+      return undefined;
+    },
+    leave(path) {
+      const currentNode = path.node;
+      for (let i = 0; i < visitors.length; i += 1) {
+        if (skipping[i] === internalSkipSymbol) {
+          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), true);
+          if (typeof visitFn === 'function') {
+            // Create a proxy path for leave phase
+            const proxyPath = createPathProxy(path, currentNode);
+            const result = visitFn.call(visitors[i], proxyPath);
+
+            // Check if the visitor is async
+            if (isPromise(result)) {
+              throw new ApiDOMStructuredError('Async visitor not supported in sync mode', {
+                visitor: visitors[i],
+                visitFn
+              });
+            }
+
+            // Handle path-based control flow
+            if (proxyPath.shouldStop) {
+              skipping[i] = breakSymbol;
+              break;
+            }
+            if (proxyPath.removed) {
+              path.remove();
+              return undefined;
+            }
+            if (proxyPath._wasReplaced()) {
+              const replacement = proxyPath._getReplacementNode();
+              path.replaceWith(replacement);
+              return replacement;
+            } else if (result !== undefined) {
+              path.replaceWith(result);
+              return result;
+            }
+          }
+        } else if (skipping[i] === currentNode) {
+          // Reset skip state when leaving the node that was skipped
+          skipping[i] = internalSkipSymbol;
+        }
+      }
+      return undefined;
+    }
+  };
+};
+
+/**
+ * Async version of mergeVisitors.
+ * @public
+ */
+export const mergeVisitorsAsync = (visitors, options = {}) => {
+  const {
+    visitFnGetter = getVisitFn,
+    nodeTypeGetter = getNodeType,
+    exposeEdits = false
+  } = options;
+  const internalSkipSymbol = Symbol('internal-skip');
+  const breakSymbol = Symbol('break');
+  const skipping = new Array(visitors.length).fill(internalSkipSymbol);
+  return {
+    async enter(path) {
+      let currentNode = path.node;
+      let hasChanged = false;
+      for (let i = 0; i < visitors.length; i += 1) {
+        if (skipping[i] === internalSkipSymbol) {
+          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), false);
+          if (typeof visitFn === 'function') {
+            const proxyPath = createPathProxy(path, currentNode);
+            const result = await visitFn.call(visitors[i], proxyPath);
+            if (proxyPath.shouldStop) {
+              skipping[i] = breakSymbol;
+              break;
+            }
+            if (proxyPath.shouldSkip) {
+              skipping[i] = currentNode;
+            }
+            if (proxyPath.removed) {
+              path.remove();
+              return undefined;
+            }
+            if (proxyPath._wasReplaced()) {
+              const replacement = proxyPath._getReplacementNode();
+              if (exposeEdits) {
+                currentNode = replacement;
+                hasChanged = true;
+              } else {
+                path.replaceWith(replacement);
+                return replacement;
+              }
+            } else if (result !== undefined) {
+              if (exposeEdits) {
+                currentNode = result;
+                hasChanged = true;
+              } else {
+                path.replaceWith(result);
+                return result;
+              }
+            }
+          }
+        }
+      }
+      if (hasChanged) {
+        path.replaceWith(currentNode);
+        return currentNode;
+      }
+      return undefined;
+    },
+    async leave(path) {
+      const currentNode = path.node;
+      for (let i = 0; i < visitors.length; i += 1) {
+        if (skipping[i] === internalSkipSymbol) {
+          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), true);
+          if (typeof visitFn === 'function') {
+            const proxyPath = createPathProxy(path, currentNode);
+            const result = await visitFn.call(visitors[i], proxyPath);
+            if (proxyPath.shouldStop) {
+              skipping[i] = breakSymbol;
+              break;
+            }
+            if (proxyPath.removed) {
+              path.remove();
+              return undefined;
+            }
+            if (proxyPath._wasReplaced()) {
+              const replacement = proxyPath._getReplacementNode();
+              path.replaceWith(replacement);
+              return replacement;
+            } else if (result !== undefined) {
+              path.replaceWith(result);
+              return result;
+            }
+          }
+        } else if (skipping[i] === currentNode) {
+          skipping[i] = internalSkipSymbol;
+        }
+      }
+      return undefined;
+    }
+  };
+};
+
+// Attach async version for promisify compatibility
+mergeVisitors[Symbol.for('nodejs.util.promisify.custom')] = mergeVisitorsAsync;
+
+/**
+ * Creates a proxy Path that allows individual visitors to track their own
+ * control flow state without affecting the original Path.
+ * @internal
+ */
+function createPathProxy(originalPath, currentNode) {
+  return new Path(currentNode, originalPath.parent, originalPath.parentPath, originalPath.key, originalPath.inList);
+}