@amritk/lint 0.0.0 → 0.2.0

package/README.md

@@ -19,7 +19,9 @@
 
 `@amritk/lint` lints **any** JSON or YAML document against a ruleset you define. A rule matches nodes with a **JSONPath** (`given`) and runs a **function** (`then`) over each match — structural validation against a **JSON Schema**, style checks (`casing`, `pattern`, `alphabetical`, `length`, …), or your own custom function. Every finding carries an exact `line:column` range, because the parser keeps source positions on every node.
 
-It is **format-agnostic**: the engine ships no built-in ruleset and knows nothing about OpenAPI or any other schema — you bring the rules. This is JSON/YAML style-guide linting with JSON Schema and custom rules, and nothing else.
+It is **format-agnostic**: the core engine ships no built-in ruleset and knows nothing about OpenAPI or any other schema — you bring the rules. This is JSON/YAML style-guide linting with JSON Schema and custom rules at its core.
+
+For OpenAPI specifically, the `@amritk/lint/rules/openapi` subpath ships a ready-made preset on top of that engine — see [OpenAPI ruleset](#openapi-ruleset) below.
 
 The CLI lives in the [`mjst`](../cli) binary as `mjst lint`; this package is the programmatic library behind it.
 
@@ -181,6 +183,37 @@ The engine internals (`createDocument`, `lint`, `query`, `validateRuleset`, `par
 
 ---
 
+## OpenAPI ruleset
+
+The core package is format-agnostic, but OpenAPI is common enough to ship a ready-made preset. It lives at the **`@amritk/lint/rules/openapi`** subpath — a self-contained layer on top of the engine that adds **no dependencies** beyond what `@amritk/lint` already uses.
+
+```ts
+import { lint } from '@amritk/lint'
+import { createOpenApiRuleset } from '@amritk/lint/rules/openapi'
+
+// Defaults to `extends: [oas]` (recommended rules only, like `spectral:oas`).
+const ruleset = createOpenApiRuleset()
+const findings = await lint(spec, { ruleset })
+```
+
+`createOpenApiRuleset(definition?, basePath?)` builds a runnable `Ruleset` with the OpenAPI functions and format detectors layered over the built-ins, and with `extends` resolution that understands the `oas` / `loupe:oas` / `spectral:oas` names (the last two accepted so existing Spectral-style rulesets extend unchanged). Enable every rule with `createOpenApiRuleset({ extends: [['oas', 'all']] })`, or pass your own definition to override severities, add rules, or point `extends` at a file/npm package.
+
+| Export | What it does |
+| --- | --- |
+| `createOpenApiRuleset(definition?, basePath?)` | Build a runnable OpenAPI `Ruleset` (functions + formats + `extends` resolution). |
+| `resolveOpenApiRuleset(name, basePath?)` | Resolve an `extends` reference, including the `oas` / `loupe:oas` / `spectral:oas` names. |
+| `oas` | The built-in OpenAPI ruleset definition. |
+| `oasFunctions` / `allFunctions` | The OpenAPI-specific functions; `allFunctions` = built-ins + OpenAPI. |
+| `oasFormats` | OpenAPI version detectors (`oas2`, `oas3`, `oas3.0`, `oas3.1`, `oas3.2`). |
+| `oasFixers` | Auto-fixers for the mechanically-repairable OpenAPI rules (pass to `fixDocument`). |
+| `loadOasSchema(version)` | Lazily load one OpenAPI version's official structural meta-schema (`'2.0'` / `'3.0'` / `'3.1'` / `'3.2'`), vendored as raw `.json` from `spec.openapis.org` (3.0/3.1/3.2 verbatim; 2.0 with its external draft-04 metaschema refs inlined). See [`schemas/README.md`](./src/rules/openapi/schemas/README.md). |
+
+The structural rules validate against the **official `spec.openapis.org` meta-schemas, vendored as raw `.json`** ([`schemas/`](./src/rules/openapi/schemas/)). 3.0/3.1/3.2 are byte-for-byte verbatim; only 2.0 differs (its external draft-04 metaschema refs are inlined, since the offline interpreter never fetches remote refs). OpenAPI 3.1/3.2 express Schema Objects as JSON Schema 2020-12 via a local `$dynamicRef`/`$dynamicAnchor`, which `@amritk/runtime-validators` resolves natively — so the whole document envelope is validated against the official schema with no bundling or dialect engine, while Schema Object internals stay permissive.
+
+`$ref` resolution stays the caller's job: the preset doesn't pull in a resolver, so for rules that need the dereferenced document (`resolved: true`) pass a `resolve` function to the core `lintWithResult` (for example wrapping [`@amritk/resolve-refs`](../resolve-refs)). The `mjst lint` CLI already wires one up.
+
+---
+
 ## License
 
 MIT

package/dist/core/document.d.ts

@@ -0,0 +1,19 @@
+import { type IDiagnostic, type ILocation, type IParserOptions, type JsonPath, type ParserFormat } from '../parsers/index.js';
+/** Options for {@link createDocument}: the parser options plus a display `source` and an explicit `format`. */
+export type IDocumentOptions = IParserOptions & {
+    source?: string;
+    format?: ParserFormat;
+};
+/**
+ * A source string paired with its parsed data and the source map that resolves
+ * JSON paths back to line:column ranges. Parsing happens up front in
+ * {@link createDocument}, so every field here is ready to read.
+ */
+export type Document<T = unknown> = {
+    readonly source?: string | undefined;
+    readonly data: T;
+    readonly diagnostics: IDiagnostic[];
+    getLocationForJsonPath(path: JsonPath, closest?: boolean): ILocation | undefined;
+};
+/** Parses `input` into a {@link Document} with a source map for position lookups. */
+export declare const createDocument: <T = unknown>(input: string, options?: IDocumentOptions) => Document<T>;

package/dist/core/document.js

@@ -0,0 +1,11 @@
+import { parseWithPointers, } from '../parsers/index.js';
+/** Parses `input` into a {@link Document} with a source map for position lookups. */
+export const createDocument = (input, options = {}) => {
+    const parsed = parseWithPointers(input, options);
+    return {
+        source: options.source,
+        data: parsed.data,
+        diagnostics: parsed.diagnostics,
+        getLocationForJsonPath: (path, closest = false) => parsed.getLocationForJsonPath(path, closest),
+    };
+};

package/dist/core/formats.d.ts

@@ -0,0 +1,9 @@
+/** A predicate that reports whether a parsed document matches a given format. */
+export type Format = (document: unknown) => boolean;
+/**
+ * Returns the set of registered format names that match the document. The
+ * `formats` registry is supplied by the caller (a preset provides its own
+ * format detectors); the engine itself is format-agnostic, so the
+ * default registry is empty and rules with no `formats` gate run regardless.
+ */
+export declare const detectFormats: (document: unknown, formats?: Record<string, Format>) => Set<string>;

package/dist/core/formats.js

@@ -0,0 +1,14 @@
+/**
+ * Returns the set of registered format names that match the document. The
+ * `formats` registry is supplied by the caller (a preset provides its own
+ * format detectors); the engine itself is format-agnostic, so the
+ * default registry is empty and rules with no `formats` gate run regardless.
+ */
+export const detectFormats = (document, formats = {}) => {
+    const matched = new Set();
+    for (const [name, detector] of Object.entries(formats)) {
+        if (detector(document))
+            matched.add(name);
+    }
+    return matched;
+};

package/dist/core/glob.d.ts

@@ -0,0 +1,4 @@
+/** Compiles a glob pattern (`**`, `*`, `?`) into an anchored RegExp. */
+export declare const globToRegExp: (glob: string) => RegExp;
+/** Returns true if `path` matches any of the glob patterns. */
+export declare const matchesGlob: (path: string, patterns: string[]) => boolean;

package/dist/core/glob.js

@@ -0,0 +1,48 @@
+/**
+ * Minimal glob → RegExp for matching override `files` patterns against document
+ * paths. Supports `**` (any path segments), `*` (within a segment), and `?`.
+ */
+const REGEXP_SPECIAL = /[\\^$.*+?()[\]{}|/]/;
+/** Compiles a glob pattern (`**`, `*`, `?`) into an anchored RegExp. */
+export const globToRegExp = (glob) => {
+    let source = '';
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === '*') {
+            if (glob[i + 1] === '*') {
+                i++;
+                if (glob[i + 1] === '/') {
+                    i++;
+                    source += '(?:.*/)?';
+                }
+                else {
+                    source += '.*';
+                }
+            }
+            else {
+                source += '[^/]*';
+            }
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else if (char && REGEXP_SPECIAL.test(char)) {
+            source += `\\${char}`;
+        }
+        else {
+            source += char;
+        }
+    }
+    return new RegExp(`^${source}$`);
+};
+/** Returns true if `path` matches any of the glob patterns. */
+export const matchesGlob = (path, patterns) => {
+    const basename = path.split('/').pop() ?? path;
+    return patterns.some((pattern) => {
+        const regex = globToRegExp(pattern);
+        if (regex.test(path))
+            return true;
+        // A pattern without a slash also matches the basename.
+        return !pattern.includes('/') && regex.test(basename);
+    });
+};

package/dist/core/index.d.ts

@@ -0,0 +1,11 @@
+export { createDocument, type Document, type IDocumentOptions } from './document.js';
+export { detectFormats, type Format } from './formats.js';
+export { globToRegExp, matchesGlob } from './glob.js';
+export { type CompiledPath, compileQuery, type IQueryMatch, query, queryCompiled, queryMany } from './jsonpath.js';
+export { type LintOptions, type LintResolver, type LintResult, lint, lintWithResult } from './lint.js';
+export { type LintPlugin, type LintPluginContext, type LintPluginResult, type PluginRunResult, runPlugins, } from './plugin.js';
+export { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, } from './pointers.js';
+export { type AliasDefinition, createRuleset, type ExtendModifier, type ExtendResolver, type ResolvedExtend, type Ruleset, type RulesetOptions, } from './ruleset.js';
+export { createLinter, type IRunOptions, type Linter } from './runner.js';
+export * from './types.js';
+export { type IRulesetProblem, validateRuleset } from './validate-ruleset.js';

package/dist/core/index.js

@@ -0,0 +1,11 @@
+export { createDocument } from './document.js';
+export { detectFormats } from './formats.js';
+export { globToRegExp, matchesGlob } from './glob.js';
+export { compileQuery, query, queryCompiled, queryMany } from './jsonpath.js';
+export { lint, lintWithResult } from './lint.js';
+export { runPlugins, } from './plugin.js';
+export { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, } from './pointers.js';
+export { createRuleset, } from './ruleset.js';
+export { createLinter } from './runner.js';
+export * from './types.js';
+export { validateRuleset } from './validate-ruleset.js';

package/dist/core/jsonpath.d.ts

@@ -0,0 +1,59 @@
+import type { JsonPath } from './types.js';
+/** A single JSONPath match: the matched value and its concrete path from the root. */
+export type IQueryMatch = {
+    value: unknown;
+    path: JsonPath;
+};
+type FilterFn = (value: unknown, property: string | number | undefined, parent: unknown, root: unknown, path: JsonPath, parentProperty: string | number | undefined) => boolean;
+type Selector = {
+    kind: 'child';
+    name: string;
+} | {
+    kind: 'index';
+    index: number;
+} | {
+    kind: 'wildcard';
+} | {
+    kind: 'union';
+    names: (string | number)[];
+} | {
+    kind: 'filter';
+    test: FilterFn;
+    source: string;
+    usesPath: boolean;
+} | {
+    kind: 'parent';
+} | {
+    kind: 'keys';
+};
+/** One compiled segment of a path: a selector and whether it follows a `..` descent. */
+export type Step = {
+    /** Whether this step is reached via `..` (descendant-or-self). */
+    recursive: boolean;
+    selector: Selector;
+};
+/** A JSONPath expression compiled into flat steps; the runner's query planner groups on these. */
+export type CompiledPath = {
+    readonly expression: string;
+    readonly steps: Step[];
+    /** True when the path contains at least one `..` step. */
+    readonly hasDescent: boolean;
+};
+/** Compiles a JSONPath `expression` into a {@link CompiledPath}, cached by string so repeats are free. */
+export declare const compileQuery: (expression: string) => CompiledPath;
+/** Evaluates a pre-compiled path against `data`. */
+export declare const queryCompiled: (data: unknown, compiled: CompiledPath) => IQueryMatch[];
+/**
+ * Evaluates many pre-compiled paths against `data`, sharing a *single* recursive
+ * descent of the tree across every `$..`-rooted path. The ruleset has ~16
+ * descent `given`s; walking the (post-deref, ~60k-node) tree once and testing
+ * each path's first selector at every node — instead of one full traversal per
+ * path — is the dominant rule-run speedup on large specs. Non-recursive paths
+ * are evaluated directly (cheap, no descent).
+ *
+ * Returns one match array per input path, index-aligned with `compiled`.
+ */
+export declare const queryMany: (data: unknown, compiled: CompiledPath[]) => IQueryMatch[][];
+/** Runs a JSONPath expression and returns each match with its concrete path. */
+export declare const query: (data: unknown, expression: string) => IQueryMatch[];
+export {};

package/dist/core/jsonpath.js

@@ -0,0 +1,415 @@
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// jsonpath-plus emits numeric array indices as strings and Linter historically
+// normalized *any* all-digit segment (including object keys like "200") to a
+// number. Replicate that exactly so source-map lookups are unchanged.
+const normalizeSegment = (segment) => {
+    if (typeof segment === 'number')
+        return segment;
+    if (segment.length > 0 && /^\d+$/.test(segment))
+        return Number(segment);
+    return segment;
+};
+const normalizePath = (path) => path.map(normalizeSegment);
+// ---------------------------------------------------------------------------
+// Compilation
+// ---------------------------------------------------------------------------
+const compileCache = new Map();
+const filterCache = new Map();
+const compileFilter = (source) => {
+    const cached = filterCache.get(source);
+    if (cached)
+        return cached;
+    // Map jsonpath-plus' `@`-context tokens onto real identifiers, longest first
+    // so `@parentProperty` is not eaten by `@parent`.
+    const body = source
+        .replace(/@parentProperty/g, '_pp')
+        .replace(/@parent/g, '_parent')
+        .replace(/@property/g, '_prop')
+        .replace(/@path/g, '_path')
+        .replace(/@root/g, '_root')
+        .replace(/@/g, '_v');
+    let fn;
+    try {
+        // `_pp` (`@parentProperty`) is supplied directly by the caller rather than
+        // derived from a materialized path, so most filters never force a path
+        // allocation. `_path` (`@path`) is only materialized for filters that use it.
+        const compiled = new Function('_v', '_prop', '_parent', '_root', '_path', '_pp', `try { return !!(${body}); } catch (_e) { return false; }`);
+        fn = compiled;
+    }
+    catch {
+        fn = () => false;
+    }
+    filterCache.set(source, fn);
+    return fn;
+};
+/** Splits bracket content on top-level commas, respecting quotes. */
+const splitUnion = (content) => {
+    const parts = [];
+    let depth = 0;
+    let quote = '';
+    let current = '';
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        if (quote) {
+            if (ch === quote)
+                quote = '';
+            current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '[' || ch === '(')
+            depth++;
+        else if (ch === ']' || ch === ')')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+};
+const unquote = (token) => {
+    const t = token.trim();
+    if (t.length >= 2 && (t[0] === '"' || t[0] === "'") && t[t.length - 1] === t[0]) {
+        return t.slice(1, -1);
+    }
+    return null;
+};
+const bracketSelector = (content) => {
+    const trimmed = content.trim();
+    if (trimmed === '*')
+        return { kind: 'wildcard' };
+    if (trimmed.startsWith('?')) {
+        // `?(expr)` — extract the inner expression between the first `(` and last `)`.
+        const open = trimmed.indexOf('(');
+        const close = trimmed.lastIndexOf(')');
+        const expr = open !== -1 && close > open ? trimmed.slice(open + 1, close) : trimmed.slice(1);
+        return { kind: 'filter', test: compileFilter(expr), source: expr, usesPath: expr.includes('@path') };
+    }
+    const parts = splitUnion(content);
+    const names = [];
+    for (const part of parts) {
+        const token = part.trim();
+        const literal = unquote(token);
+        if (literal !== null) {
+            names.push(literal);
+        }
+        else if (/^-?\d+$/.test(token)) {
+            names.push(Number(token));
+        }
+        else {
+            names.push(token);
+        }
+    }
+    if (names.length === 1) {
+        const only = names[0];
+        return typeof only === 'number' ? { kind: 'index', index: only } : { kind: 'child', name: only };
+    }
+    return { kind: 'union', names };
+};
+/** Finds the index of the `]` that closes the `[` at `start`, respecting quotes/nesting. */
+const findBracketEnd = (expression, start) => {
+    let depth = 0;
+    let quote = '';
+    for (let i = start; i < expression.length; i++) {
+        const ch = expression[i];
+        if (quote) {
+            if (ch === quote)
+                quote = '';
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === '[' || ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        else if (ch === ']') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+};
+const readName = (expression, start) => {
+    let i = start;
+    while (i < expression.length && !'.[]^~'.includes(expression[i]))
+        i++;
+    return { name: expression.slice(start, i), end: i };
+};
+/** Compiles a JSONPath `expression` into a {@link CompiledPath}, cached by string so repeats are free. */
+export const compileQuery = (expression) => {
+    const cached = compileCache.get(expression);
+    if (cached)
+        return cached;
+    const steps = [];
+    let hasDescent = false;
+    let i = 0;
+    if (expression[0] === '$')
+        i = 1;
+    let recursive = false;
+    while (i < expression.length) {
+        const ch = expression[i];
+        if (ch === '.') {
+            if (expression[i + 1] === '.') {
+                recursive = true;
+                hasDescent = true;
+                i += 2;
+                // A bare `..` followed by `.`/end is unusual; loop handles the selector.
+                continue;
+            }
+            i++;
+            if (expression[i] === '*') {
+                steps.push({ recursive, selector: { kind: 'wildcard' } });
+                recursive = false;
+                i++;
+                continue;
+            }
+            const { name, end } = readName(expression, i);
+            steps.push({ recursive, selector: { kind: 'child', name } });
+            recursive = false;
+            i = end;
+            continue;
+        }
+        if (ch === '[') {
+            const end = findBracketEnd(expression, i);
+            if (end === -1)
+                break;
+            const content = expression.slice(i + 1, end);
+            steps.push({ recursive, selector: bracketSelector(content) });
+            recursive = false;
+            i = end + 1;
+            continue;
+        }
+        if (ch === '^') {
+            steps.push({ recursive: false, selector: { kind: 'parent' } });
+            i++;
+            continue;
+        }
+        if (ch === '~') {
+            steps.push({ recursive: false, selector: { kind: 'keys' } });
+            i++;
+            continue;
+        }
+        if (ch === '*') {
+            steps.push({ recursive, selector: { kind: 'wildcard' } });
+            recursive = false;
+            i++;
+            continue;
+        }
+        // Bare name following `..` (e.g. `$..foo`) or other unexpected token.
+        if (recursive) {
+            const { name, end } = readName(expression, i);
+            if (end > i) {
+                steps.push({ recursive: true, selector: { kind: 'child', name } });
+                recursive = false;
+                i = end;
+                continue;
+            }
+        }
+        i++;
+    }
+    const compiled = { expression, steps, hasDescent };
+    compileCache.set(expression, compiled);
+    return compiled;
+};
+const EMPTY_PATH = [];
+/** Materializes the concrete (un-normalized) path from root to `node`. */
+const pathOf = (node) => {
+    let depth = 0;
+    for (let n = node; n !== undefined && n.parent !== undefined; n = n.parent)
+        depth++;
+    const out = new Array(depth);
+    let i = depth - 1;
+    for (let n = node; n !== undefined && n.parent !== undefined; n = n.parent) {
+        out[i--] = n.key;
+    }
+    return out;
+};
+const applySelector = (node, selector, root, out) => {
+    const value = node.value;
+    switch (selector.kind) {
+        case 'child': {
+            if (isObject(value)) {
+                if (Object.hasOwn(value, selector.name))
+                    out.push({ value: value[selector.name], parent: node, key: selector.name });
+            }
+            else if (Array.isArray(value) && /^\d+$/.test(selector.name)) {
+                const idx = Number(selector.name);
+                if (idx < value.length)
+                    out.push({ value: value[idx], parent: node, key: idx });
+            }
+            return;
+        }
+        case 'index': {
+            if (Array.isArray(value)) {
+                const idx = selector.index < 0 ? value.length + selector.index : selector.index;
+                if (idx >= 0 && idx < value.length)
+                    out.push({ value: value[idx], parent: node, key: idx });
+            }
+            else if (isObject(value) && Object.hasOwn(value, selector.index)) {
+                out.push({ value: value[selector.index], parent: node, key: selector.index });
+            }
+            return;
+        }
+        case 'wildcard': {
+            if (Array.isArray(value)) {
+                for (let idx = 0; idx < value.length; idx++)
+                    out.push({ value: value[idx], parent: node, key: idx });
+            }
+            else if (isObject(value)) {
+                for (const key of Object.keys(value))
+                    out.push({ value: value[key], parent: node, key });
+            }
+            return;
+        }
+        case 'union': {
+            for (const name of selector.names) {
+                if (Array.isArray(value)) {
+                    if (typeof name === 'number') {
+                        const idx = name < 0 ? value.length + name : name;
+                        if (idx >= 0 && idx < value.length)
+                            out.push({ value: value[idx], parent: node, key: idx });
+                    }
+                }
+                else if (isObject(value) && Object.hasOwn(value, name)) {
+                    out.push({ value: value[name], parent: node, key: name });
+                }
+            }
+            return;
+        }
+        case 'filter': {
+            // `@parentProperty` is `node.key`; `@path` is materialized only when used.
+            const pp = node.key;
+            if (Array.isArray(value)) {
+                for (let idx = 0; idx < value.length; idx++) {
+                    const child = { value: value[idx], parent: node, key: idx };
+                    const path = selector.usesPath ? pathOf(child) : EMPTY_PATH;
+                    if (selector.test(value[idx], idx, value, root, path, pp))
+                        out.push(child);
+                }
+            }
+            else if (isObject(value)) {
+                for (const key of Object.keys(value)) {
+                    const child = { value: value[key], parent: node, key };
+                    const path = selector.usesPath ? pathOf(child) : EMPTY_PATH;
+                    if (selector.test(value[key], key, value, root, path, pp))
+                        out.push(child);
+                }
+            }
+            return;
+        }
+        case 'parent': {
+            if (node.parent !== undefined)
+                out.push(node.parent);
+            return;
+        }
+        case 'keys': {
+            if (node.parent === undefined)
+                return;
+            // The selected value is the node's own key, but it occupies the same path.
+            out.push({ value: node.key, parent: node.parent, key: node.key });
+            return;
+        }
+    }
+};
+/** Visits `node` and every descendant (preorder), invoking `visit` on each. */
+const walkDescendants = (node, visit) => {
+    visit(node);
+    const value = node.value;
+    if (Array.isArray(value)) {
+        for (let idx = 0; idx < value.length; idx++)
+            walkDescendants({ value: value[idx], parent: node, key: idx }, visit);
+    }
+    else if (isObject(value)) {
+        for (const key of Object.keys(value))
+            walkDescendants({ value: value[key], parent: node, key }, visit);
+    }
+};
+/** Applies a list of steps to an existing set of nodes. */
+const applySteps = (root, initial, steps) => {
+    let current = initial;
+    for (const step of steps) {
+        const next = [];
+        if (step.recursive) {
+            for (const node of current)
+                walkDescendants(node, (n) => applySelector(n, step.selector, root, next));
+        }
+        else {
+            for (const node of current)
+                applySelector(node, step.selector, root, next);
+        }
+        current = next;
+    }
+    return current;
+};
+const runSteps = (root, steps) => applySteps(root, [{ value: root, parent: undefined, key: undefined }], steps);
+const toMatches = (nodes) => {
+    const out = new Array(nodes.length);
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        out[i] = { value: node.value, path: normalizePath(pathOf(node)) };
+    }
+    return out;
+};
+/** Evaluates a pre-compiled path against `data`. */
+export const queryCompiled = (data, compiled) => {
+    if (data === null || data === undefined)
+        return [];
+    return toMatches(runSteps(data, compiled.steps));
+};
+/**
+ * Evaluates many pre-compiled paths against `data`, sharing a *single* recursive
+ * descent of the tree across every `$..`-rooted path. The ruleset has ~16
+ * descent `given`s; walking the (post-deref, ~60k-node) tree once and testing
+ * each path's first selector at every node — instead of one full traversal per
+ * path — is the dominant rule-run speedup on large specs. Non-recursive paths
+ * are evaluated directly (cheap, no descent).
+ *
+ * Returns one match array per input path, index-aligned with `compiled`.
+ */
+export const queryMany = (data, compiled) => {
+    const out = new Array(compiled.length);
+    if (data === null || data === undefined) {
+        for (let i = 0; i < compiled.length; i++)
+            out[i] = [];
+        return out;
+    }
+    const recursive = [];
+    for (let i = 0; i < compiled.length; i++) {
+        const c = compiled[i];
+        const first = c.steps[0];
+        if (first?.recursive)
+            recursive.push(i);
+        else
+            out[i] = queryCompiled(data, c);
+    }
+    if (recursive.length > 0) {
+        // Walk the whole tree exactly once, applying every descent path's first
+        // selector at each visited node in the same pass (fused descent), so the
+        // ~15k-node resolved tree is traversed a single time rather than once per
+        // `$..` given. Each path's surviving seeds then run its remaining steps.
+        const firsts = recursive.map((i) => compiled[i].steps[0]);
+        const seeds = recursive.map(() => []);
+        const root = { value: data, parent: undefined, key: undefined };
+        walkDescendants(root, (node) => {
+            for (let r = 0; r < recursive.length; r++)
+                applySelector(node, firsts[r].selector, data, seeds[r]);
+        });
+        for (let r = 0; r < recursive.length; r++) {
+            const c = compiled[recursive[r]];
+            out[recursive[r]] = toMatches(applySteps(data, seeds[r], c.steps.slice(1)));
+        }
+    }
+    return out;
+};
+/** Runs a JSONPath expression and returns each match with its concrete path. */
+export const query = (data, expression) => queryCompiled(data, compileQuery(expression));