import { Element as Element_2 } from '@speclynx/apidom-datamodel';

/**
 * Default node clone function - creates a shallow clone of ApiDOM Elements.
 * Uses cloneShallow from apidom-datamodel for proper handling of meta/attributes.
 * @public
 */
export declare const cloneNode: <TNode>(node: TNode) => TNode;

/**
 * Finds all paths whose elements match the predicate.
 * @public
 */
export declare const filter: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2>[];

/**
 * Finds first path whose element satisfies the provided predicate.
 * @public
 */
export declare const find: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2> | undefined;

/**
 * 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
 */
export declare const findAtOffset: <T extends Element_2>(element: T, options: number | FindAtOffsetOptions) => Path<Element_2> | undefined;

/**
 * @public
 */
export declare interface FindAtOffsetOptions {
    offset: number;
    includeRightBound?: boolean;
}

/**
 * Executes the callback on this element's path and all descendant paths.
 * @public
 */
export declare const forEach: <T extends Element_2>(element: T, options: ForEachCallback | ForEachOptions) => void;

/**
 * @public
 */
export declare type ForEachCallback = (path: Path<Element_2>) => void;

/**
 * @public
 */
export declare interface ForEachOptions {
    callback?: ForEachCallback;
    predicate?: (path: Path<Element_2>) => boolean;
}

/**
 * Default function to get traversable keys for a node.
 * Uses predicates to handle all ApiDOM element types automatically.
 * @public
 */
export declare const getNodeKeys: <TNode>(node: TNode) => readonly string[];

/**
 * 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 declare const getNodePrimitiveType: <TNode>(node: TNode) => string;

/**
 * Default node type getter - reads the `element` property and converts to Element class name.
 * E.g., "string" -\> "StringElement", "openApi3_1" -\> "OpenApi3_1Element"
 * @public
 */
export declare const getNodeType: <TNode>(node: TNode) => string;

/**
 * Gets the appropriate visitor function for a node type and phase.
 * Supports pipe-separated type keys like "TypeA|TypeB".
 * @public
 */
export declare const getVisitFn: <TNode>(visitor: object, type: string | undefined, isLeaving: boolean) => VisitorFn<TNode> | null;

/**
 * Default node predicate - checks if value is an ApiDOM Element.
 * @public
 */
export declare const isNode: <TNode>(value: unknown) => value is TNode;

/**
 * Sync version of merged visitor.
 * @public
 */
export declare interface MergedVisitor<TNode> {
    enter?: VisitorFn<TNode>;
    leave?: VisitorFn<TNode>;
    [key: string]: VisitorFn<TNode> | NodeVisitor<TNode> | undefined;
}

/**
 * Async version of merged visitor.
 * @public
 */
export declare interface MergedVisitorAsync<TNode> {
    enter?: VisitorFn<TNode>;
    leave?: VisitorFn<TNode>;
    [key: string]: VisitorFn<TNode> | NodeVisitor<TNode> | undefined;
}

/**
 * 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 declare const mergeVisitors: <TNode>(visitors: object[], options?: MergeVisitorsOptions<TNode>) => MergedVisitor<TNode>;

/**
 * Async version of mergeVisitors.
 * @public
 */
export declare const mergeVisitorsAsync: <TNode>(visitors: object[], options?: MergeVisitorsOptions<TNode>) => MergedVisitorAsync<TNode>;

/**
 * Options for mergeVisitors.
 * @public
 */
export declare interface MergeVisitorsOptions<TNode> {
    visitFnGetter?: typeof getVisitFn;
    nodeTypeGetter?: (node: TNode) => string | undefined;
    exposeEdits?: boolean;
}

/**
 * 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 declare const mutateNode: <TNode>(parent: TNode, key: PropertyKey, value: TNode | null) => void;

/**
 * Enter/leave visitor structure for a specific node type.
 * @public
 */
export declare interface NodeVisitor<TNode, TVisitor = unknown> {
    enter?: VisitorFn<TNode, TVisitor>;
    leave?: VisitorFn<TNode, TVisitor>;
}

/**
 * Computes upwards edges from every child to its parent.
 * @public
 */
export declare const parents: <T extends Element_2>(element: T) => WeakMap<Element_2, Element_2 | undefined>;

/**
 * Path represents a node's position in the tree during traversal.
 * Inspired by Babel's NodePath API.
 * @public
 */
export declare class Path<TNode = Element_2> {
    #private;
    /**
     * The current AST node.
     */
    node: TNode;
    /**
     * The key of this node in its parent.
     * `undefined` for the root node.
     */
    readonly key: PropertyKey | undefined;
    /**
     * The index if this node is in an array.
     * Same as `key` when parent property is an array, `undefined` otherwise.
     */
    readonly index: number | undefined;
    /**
     * The parent node.
     * `undefined` for the root node.
     */
    readonly parent: TNode | undefined;
    /**
     * The parent Path.
     * `null` for the root node.
     */
    readonly parentPath: Path<TNode> | null;
    /**
     * 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.
     */
    get shouldSkip(): boolean;
    /**
     * Whether stop() was called on this path.
     */
    get shouldStop(): boolean;
    /**
     * Whether this node was removed.
     */
    get removed(): boolean;
    /**
     * Returns true if this is the root path.
     */
    isRoot(): boolean;
    /**
     * Get the depth of this path (0 for root).
     */
    get depth(): number;
    /**
     * Get all ancestor paths from immediate parent to root.
     */
    getAncestry(): Path<TNode>[];
    /**
     * Get all ancestor nodes from immediate parent to root.
     */
    getAncestorNodes(): TNode[];
    /**
     * 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[];
    /**
     * 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'): string;
    /**
     * Find the closest ancestor path that satisfies the predicate.
     */
    findParent(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null;
    /**
     * Find the closest path (including this one) that satisfies the predicate.
     */
    find(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null;
    /**
     * Traverse into the current node with a new visitor.
     * Populated by the traversal module to avoid circular imports.
     */
    traverse: (visitor: any, options?: any) => TNode;
    /**
     * Async version of traverse.
     */
    traverseAsync: (visitor: any, options?: any) => Promise<TNode>;
    /**
     * Skip traversing the children of this node.
     */
    skip(): void;
    /**
     * Stop all traversal completely.
     */
    stop(): void;
    /**
     * Replace this node with a new node.
     */
    replaceWith(replacement: TNode): void;
    /**
     * Remove this node from the tree.
     */
    remove(): void;
    /**
     * @internal
     */
    _getReplacementNode(): TNode | undefined;
    /**
     * @internal
     */
    _wasReplaced(): boolean;
    /**
     * @internal
     */
    _reset(): void;
    /**
     * Mark this path as stale (visit completed).
     * @internal
     */
    _markStale(): void;
}

/**
 * Complement of filter. Finds all paths whose elements do NOT match the predicate.
 * @public
 */
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
 */
export declare const some: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => boolean;

/**
 * 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 declare const traverse: <TNode>(root: TNode, visitor: object, options?: TraverseOptions<TNode>) => TNode;

/**
 * Async version of traverse().
 * @public
 */
export declare const traverseAsync: <TNode>(root: TNode, visitor: object, options?: TraverseOptions<TNode>) => Promise<TNode>;

/**
 * Options for the traverse function.
 * @public
 */
export declare interface TraverseOptions<TNode> {
    /**
     * Map of node types to their traversable keys, or a function that returns keys for a node.
     * Defaults to predicate-based detection for ApiDOM elements.
     */
    keyMap?: Record<string, readonly string[]> | ((node: TNode) => readonly string[]) | null;
    /**
     * State object to assign to visitor during traversal.
     */
    state?: Record<string, unknown>;
    /**
     * Function to get the type of a node. Defaults to `node.type`.
     */
    nodeTypeGetter?: (node: TNode) => string | undefined;
    /**
     * Predicate to check if a value is a valid node.
     */
    nodePredicate?: (value: unknown) => value is TNode;
    /**
     * Function to clone a node. Used when edits are made in immutable mode.
     */
    nodeCloneFn?: (node: TNode) => TNode;
    /**
     * Whether to detect and skip cycles using ancestor tracking. Defaults to true.
     * Catches true identity cycles where a node is its own ancestor.
     */
    detectCycles?: boolean;
    /**
     * 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?: SkipVisitedMode;
    /**
     * If true, edits modify the original tree in place.
     * If false (default), creates a new tree with changes applied.
     */
    mutable?: boolean;
    /**
     * Custom function for applying mutations in mutable mode.
     * Handles ApiDOM structures (MemberElement, arrays) by default.
     */
    mutationFn?: (parent: TNode, key: PropertyKey, value: TNode | null) => void;
}

/**
 * Visitor function signature - receives a Path object.
 * @public
 */
export declare type VisitorFn<TNode, TVisitor = unknown> = (this: TVisitor, path: Path<TNode>) => VisitorResult<TNode>;

/**
 * Possible return values from a visitor function.
 * @public
 */
export declare type VisitorResult<TNode> = void | undefined | TNode | Promise<void | undefined | TNode>;

export { }