@speclynx/apidom-traverse 4.0.3 → 4.0.4

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.0.4](https://github.com/speclynx/apidom/compare/v4.0.3...v4.0.4) (2026-03-12)
+
+### Bug Fixes
+
+- **release:** override minimatch 10.2.3 to fix glob pattern regression in lerna publish ([#157](https://github.com/speclynx/apidom/issues/157)) ([c2d65a0](https://github.com/speclynx/apidom/commit/c2d65a06a2187e8563a9dc9db74ba27255450e0b)), closes [lerna/lerna#4305](https://github.com/lerna/lerna/issues/4305) [isaacs/minimatch#284](https://github.com/isaacs/minimatch/issues/284)
+
 ## [4.0.3](https://github.com/speclynx/apidom/compare/v4.0.2...v4.0.3) (2026-03-11)
 
 ### Bug Fixes

package/package.json

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

package/src/Path.ts

@@ -1,368 +0,0 @@
-import {
-  isMemberElement,
-  isArrayElement,
-  isStringElement,
-  type Element,
-} from '@speclynx/apidom-datamodel';
-import { compile as compileJSONPointer } from '@speclynx/apidom-json-pointer';
-import { NormalizedPath } from '@speclynx/apidom-json-path';
-
-/**
- * Possible return values from a visitor function.
- * @public
- */
-export type VisitorResult<TNode> = void | undefined | TNode | Promise<void | undefined | TNode>;
-
-/**
- * Visitor function signature - receives a Path object.
- * @public
- */
-export type VisitorFn<TNode, TVisitor = unknown> = (
-  this: TVisitor,
-  path: Path<TNode>,
-) => VisitorResult<TNode>;
-
-/**
- * Path represents a node's position in the tree during traversal.
- * Inspired by Babel's NodePath API.
- * @public
- */
-export class Path<TNode = Element> {
-  /**
-   * The current AST node.
-   */
-  public node: TNode;
-
-  /**
-   * The key of this node in its parent.
-   * `undefined` for the root node.
-   */
-  public readonly key: PropertyKey | undefined;
-
-  /**
-   * The index if this node is in an array.
-   * Same as `key` when parent property is an array, `undefined` otherwise.
-   */
-  public readonly index: number | undefined;
-
-  /**
-   * The parent node.
-   * `undefined` for the root node.
-   */
-  public readonly parent: TNode | undefined;
-
-  /**
-   * The parent Path.
-   * `null` for the root node.
-   */
-  public readonly parentPath: Path<TNode> | null;
-
-  /**
-   * Whether this node is inside an array in the parent.
-   */
-  public readonly inList: boolean;
-
-  /**
-   * Internal state for traversal control.
-   */
-  #shouldSkip: boolean = false;
-  #shouldStop: boolean = false;
-  #removed: boolean = false;
-  #replaced: boolean = false;
-  #replacementNode: TNode | undefined;
-  #stale: boolean = false;
-
-  constructor(
-    node: TNode,
-    parent: TNode | undefined,
-    parentPath: Path<TNode> | null,
-    key: PropertyKey | undefined,
-    inList: boolean,
-  ) {
-    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(): boolean {
-    return this.#shouldSkip;
-  }
-
-  /**
-   * Whether stop() was called on this path.
-   */
-  get shouldStop(): boolean {
-    return this.#shouldStop;
-  }
-
-  /**
-   * Whether this node was removed.
-   */
-  get removed(): boolean {
-    return this.#removed;
-  }
-
-  // ===========================================================================
-  // Ancestry
-  // ===========================================================================
-
-  /**
-   * Returns true if this is the root path.
-   */
-  isRoot(): boolean {
-    return this.parentPath === null;
-  }
-
-  /**
-   * Get the depth of this path (0 for root).
-   */
-  get depth(): number {
-    let depth = 0;
-    let current: Path<TNode> | null = this.parentPath;
-    while (current !== null) {
-      depth += 1;
-      current = current.parentPath;
-    }
-    return depth;
-  }
-
-  /**
-   * Get all ancestor paths from immediate parent to root.
-   */
-  getAncestry(): Path<TNode>[] {
-    const ancestry: Path<TNode>[] = [];
-    let current: Path<TNode> | null = this.parentPath;
-    while (current !== null) {
-      ancestry.push(current);
-      current = current.parentPath;
-    }
-    return ancestry;
-  }
-
-  /**
-   * Get all ancestor nodes from immediate parent to root.
-   */
-  getAncestorNodes(): TNode[] {
-    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(): PropertyKey[] {
-    const keys: PropertyKey[] = [];
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let current: Path<TNode> | null = this;
-
-    while (current !== null && current.key !== undefined) {
-      const { key, parent, parentPath } = current;
-
-      if (isMemberElement(parent) && key === 'value') {
-        // Inside MemberElement.value → push the member's key
-        if (!isStringElement(parent.key)) {
-          throw new TypeError('MemberElement.key must be a StringElement');
-        }
-        keys.unshift(parent.key.toValue() as PropertyKey);
-      } else if (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' | 'jsonpath' = 'jsonpointer'): string {
-    const parts = this.getPathKeys();
-
-    // Root node
-    if (parts.length === 0) {
-      return pathFormat === 'jsonpath' ? '$' : '';
-    }
-
-    if (pathFormat === 'jsonpath') {
-      // RFC 9535 Normalized JSONPath
-      return NormalizedPath.from(parts as (string | number)[]);
-    }
-
-    // RFC 6901 JSON Pointer
-    return compileJSONPointer(parts as string[]);
-  }
-
-  /**
-   * Find the closest ancestor path that satisfies the predicate.
-   */
-  findParent(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null {
-    let current: Path<TNode> | null = 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: (path: Path<TNode>) => boolean): Path<TNode> | null {
-    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
-  declare traverse: (visitor: any, options?: any) => TNode;
-
-  /**
-   * Async version of traverse.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  declare traverseAsync: (visitor: any, options?: any) => Promise<TNode>;
-
-  // ===========================================================================
-  // Traversal control
-  // ===========================================================================
-
-  /**
-   * Skip traversing the children of this node.
-   */
-  skip(): void {
-    this.#shouldSkip = true;
-  }
-
-  /**
-   * Stop all traversal completely.
-   */
-  stop(): void {
-    this.#shouldStop = true;
-  }
-
-  // ===========================================================================
-  // Modification
-  // ===========================================================================
-
-  /**
-   * Replace this node with a new node.
-   */
-  replaceWith(replacement: TNode): void {
-    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(): void {
-    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(): TNode | undefined {
-    return this.#replacementNode;
-  }
-
-  /**
-   * @internal
-   */
-  _wasReplaced(): boolean {
-    return this.#replaced;
-  }
-
-  /**
-   * @internal
-   */
-  _reset(): void {
-    this.#shouldSkip = false;
-    this.#shouldStop = false;
-    this.#removed = false;
-    this.#replaced = false;
-    this.#replacementNode = undefined;
-  }
-
-  /**
-   * Mark this path as stale (visit completed).
-   * @internal
-   */
-  _markStale(): void {
-    this.#stale = true;
-  }
-}

package/src/index.ts

@@ -1,44 +0,0 @@
-import { Path } from './Path.ts';
-import { traverse, traverseAsync } from './traversal.ts';
-
-// Wire up Path.prototype.traverse methods to avoid circular imports
-Path.prototype.traverse = function (this: Path<any>, visitor: any, options?: any) {
-  return traverse(this.node, visitor, options);
-};
-
-Path.prototype.traverseAsync = function (this: Path<any>, visitor: any, options?: any) {
-  return traverseAsync(this.node, visitor, options);
-};
-
-export { Path };
-export type { VisitorFn, VisitorResult } from './Path.ts';
-export {
-  getNodeType,
-  getNodePrimitiveType,
-  isNode,
-  cloneNode,
-  mutateNode,
-  getNodeKeys,
-  getVisitFn,
-  mergeVisitors,
-  mergeVisitorsAsync,
-} from './visitors.ts';
-export type {
-  NodeVisitor,
-  MergeVisitorsOptions,
-  MergedVisitor,
-  MergedVisitorAsync,
-} from './visitors.ts';
-export { traverse, traverseAsync } from './traversal.ts';
-export type { TraverseOptions } from './traversal.ts';
-
-// Operations
-export { default as filter } from './operations/filter.ts';
-export { default as find } from './operations/find.ts';
-export { default as some } from './operations/some.ts';
-export { default as reject } from './operations/reject.ts';
-export { default as forEach } from './operations/for-each.ts';
-export type { Callback as ForEachCallback, ForEachOptions } from './operations/for-each.ts';
-export { default as parents } from './operations/parents.ts';
-export { default as findAtOffset } from './operations/find-at-offset.ts';
-export type { FindAtOffsetOptions } from './operations/find-at-offset.ts';

package/src/operations/filter.ts

@@ -1,27 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import { traverse } from '../traversal.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * Finds all paths whose elements match the predicate.
- * @public
- */
-const filter = <T extends Element>(
-  element: T,
-  predicate: (path: Path<Element>) => boolean,
-): Path<Element>[] => {
-  const result: Path<Element>[] = [];
-
-  traverse(element, {
-    enter(path: Path<Element>) {
-      if (predicate(path)) {
-        result.push(path);
-      }
-    },
-  });
-
-  return result;
-};
-
-export default filter;

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

@@ -1,61 +0,0 @@
-import { Element, hasElementSourceMap } from '@speclynx/apidom-datamodel';
-
-import { traverse } from '../traversal.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * @public
- */
-export interface FindAtOffsetOptions {
-  offset: number;
-  includeRightBound?: boolean;
-}
-
-/**
- * Finds the path of the most inner node at the given offset.
- * If includeRightBound is set, also finds nodes that end at the given offset.
- * @public
- */
-const findAtOffset = <T extends Element>(
-  element: T,
-  options: number | FindAtOffsetOptions,
-): Path<Element> | undefined => {
-  let offset: number;
-  let includeRightBound: boolean;
-
-  if (typeof options === 'number') {
-    offset = options;
-    includeRightBound = false;
-  } else {
-    offset = options.offset ?? 0;
-    includeRightBound = options.includeRightBound ?? false;
-  }
-
-  const result: Path<Element>[] = [];
-
-  traverse(element, {
-    enter(path: Path<Element>) {
-      const node = path.node;
-
-      if (!hasElementSourceMap(node)) {
-        return; // dive in
-      }
-
-      const startOffset: number = node.startOffset!;
-      const endOffset: number = node.endOffset!;
-      const isWithinOffsetRange =
-        offset >= startOffset && (offset < endOffset || (includeRightBound && offset <= endOffset));
-
-      if (isWithinOffsetRange) {
-        result.push(path);
-        return; // push to stack and dive in
-      }
-
-      path.skip(); // skip entire sub-tree
-    },
-  });
-
-  return result.at(-1);
-};
-
-export default findAtOffset;

package/src/operations/find.ts

@@ -1,28 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import { traverse } from '../traversal.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * Finds first path whose element satisfies the provided predicate.
- * @public
- */
-const find = <T extends Element>(
-  element: T,
-  predicate: (path: Path<Element>) => boolean,
-): Path<Element> | undefined => {
-  let result: Path<Element> | undefined;
-
-  traverse(element, {
-    enter(path: Path<Element>) {
-      if (predicate(path)) {
-        result = path;
-        path.stop();
-      }
-    },
-  });
-
-  return result;
-};
-
-export default find;

package/src/operations/for-each.ts

@@ -1,44 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import { traverse } from '../traversal.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * @public
- */
-export type Callback = (path: Path<Element>) => void;
-
-/**
- * @public
- */
-export interface ForEachOptions {
-  callback?: Callback;
-  predicate?: (path: Path<Element>) => boolean;
-}
-
-/**
- * Executes the callback on this element's path and all descendant paths.
- * @public
- */
-const forEach = <T extends Element>(element: T, options: Callback | ForEachOptions): void => {
-  let callback: Callback;
-  let predicate: (path: Path<Element>) => boolean;
-
-  if (typeof options === 'function') {
-    callback = options;
-    predicate = () => true;
-  } else {
-    callback = options.callback ?? (() => {});
-    predicate = options.predicate ?? (() => true);
-  }
-
-  traverse(element, {
-    enter(path: Path<Element>) {
-      if (predicate(path)) {
-        callback(path);
-      }
-    },
-  });
-};
-
-export default forEach;

package/src/operations/parents.ts

@@ -1,24 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import { traverse } from '../traversal.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * Computes upwards edges from every child to its parent.
- * @public
- */
-const parents = <T extends Element>(element: T): WeakMap<Element, Element | undefined> => {
-  const parentEdges = new WeakMap<Element, Element | undefined>();
-
-  traverse(element, {
-    enter(path: Path<Element>) {
-      // Use parentPath.node to get the actual Element parent.
-      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
-      parentEdges.set(path.node, path.parentPath?.node);
-    },
-  });
-
-  return parentEdges;
-};
-
-export default parents;

package/src/operations/reject.ts

@@ -1,17 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import filter from './filter.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * Complement of filter. Finds all paths whose elements do NOT match the predicate.
- * @public
- */
-const reject = <T extends Element>(
-  element: T,
-  predicate: (path: Path<Element>) => boolean,
-): Path<Element>[] => {
-  return filter(element, (path) => !predicate(path));
-};
-
-export default reject;

package/src/operations/some.ts

@@ -1,17 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import find from './find.ts';
-import type { Path } from '../Path.ts';
-
-/**
- * Tests whether at least one path's element passes the predicate.
- * @public
- */
-const some = <T extends Element>(
-  element: T,
-  predicate: (path: Path<Element>) => boolean,
-): boolean => {
-  return find(element, predicate) !== undefined;
-};
-
-export default some;