@amritk/lint 0.7.0 → 0.8.0

package/AI.md

@@ -118,7 +118,12 @@ createAsyncApiRuleset({
 ## Exports
 
 - `lintDocument(input, options?)` → findings only. `options.ruleset` is either a
-  definition to build or an already-built `Ruleset`.
+  definition to build or an already-built `Ruleset`. `input` is the text, or
+  `{ data, text? }` when the caller has already parsed it: the parse is skipped
+  (so no parser diagnostics) and `text` is read only for finding ranges (zero
+  ranges without it).
+- A rule's `descent: 'schema'` keeps `..` out of `example`, `examples`,
+  `default`, `const` and `enum` values. Use it for rules about schemas.
 - `lintDocumentWithResult(input, options?)` → `{ diagnostics, output?, pluginData }`.
 - `fixDocument(input, options?)` → `{ output, fixed, applied, remaining, converged, passes }`
   (needs `fixers`; `converged: false` means the 10-pass cap was hit with the

package/README.md

@@ -62,6 +62,16 @@ const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.
 
 `severity` is a `DiagnosticSeverity` — `0` error, `1` warning, `2` info, `3` hint — and `range` is a zero-based `{ line, character }` span you can render a squiggle from.
 
+### Lint data you already parsed
+
+A caller that has the document parsed already — a loader that read and normalized it — passes the data instead of the text, and the parse is skipped:
+
+```ts
+const findings = await lintDocument({ data: spec, text: source }, { ruleset, source: 'openapi.json' })
+```
+
+`text` is optional and only read to put `line:column` ranges on findings, lazily: JSON text is scanned for just the paths that carry findings, YAML text is parsed on the first lookup. A path the caller's normalization added resolves to its closest ancestor in the text, and without `text` every range is the zero range. Since the data is not parsed, there are no parser diagnostics: `parserOptions` (`duplicateKeys`, `incompatibleValues`) and syntax errors are only reported when linting the text. Plugins that rewrite the document (auto-fix) need `text`. `createDocumentFromData(data, { text })` builds the same document for the lower-level `createLinter(ruleset).run()`.
+
 ### Validate against a JSON Schema
 
 The built-in `schema` function runs an arbitrary JSON Schema (Draft 2020-12) over the matched node, via [`@amritk/runtime-validators`](../runtime-validators):
@@ -129,7 +139,7 @@ One thing `restrictTo` does not cover: a regular expression a ruleset writes —
 
 ### Auto-fix
 
-`fixDocument` runs the linter and applies a `FixerRegistry` — fixers keyed by rule `code` that map a finding to a formatting-preserving text edit — to a fixpoint, then re-lints:
+`fixDocument` runs the linter and applies a `FixerRegistry` — fixers keyed by rule `code` that map a finding to a formatting-preserving text edit — to a fixpoint, then reports the findings that remain:
 
 ```ts
 import { fixDocument, type FixerRegistry } from '@amritk/lint'
@@ -161,7 +171,7 @@ const { output, applied } = await fixDocument(source, {
 })
 ```
 
-Fixing runs to a fixpoint, capped at 10 passes. The result reports how that ended: **`converged`** is `false` when the cap was hit while the document was still changing (usually two fixers undoing each other), and **`passes`** counts the passes that changed something. `applied` is de-duplicated by rule code and path, so a report can safely say "fixed N problems".
+Fixing runs to a fixpoint, capped at 10 passes. `remaining` comes from the pass that found nothing left to fix, so a run that converges does not lint the fixed document a second time; only one that hits the cap does. The result reports how that ended: **`converged`** is `false` when the cap was hit while the document was still changing (usually two fixers undoing each other), and **`passes`** counts the passes that changed something. `applied` is de-duplicated by rule code and path, so a report can safely say "fixed N problems".
 
 ### Rendering findings
 
@@ -193,12 +203,13 @@ A ruleset is a plain object (authored as YAML, JSON, or a JS module):
 
 | Field | Description |
 | --- | --- |
-| `rules` | Map of `name → rule`. A rule has `given` (one or more JSONPath expressions), `then` (a function to run, or a list), `severity` (`error`/`warn`/`info`/`hint`/`off`), and optional `message`, `description`, `formats`, `recommended`, `resolved` (default `true`; `false` runs the rule against the document as written, before `$ref` dereferencing), and `documentationUrl`. |
+| `rules` | Map of `name → rule`. A rule has `given` (one or more JSONPath expressions), `then` (a function to run, or a list), `severity` (`error`/`warn`/`info`/`hint`/`off`), and optional `message`, `description`, `formats`, `recommended`, `resolved` (default `true`; `false` runs the rule against the document as written, before `$ref` dereferencing), `descent` (default `all`; `schema` keeps `..` out of `example`, `examples`, `default`, `const` and `enum` values, so a rule about schemas does not match an example payload), and `documentationUrl`. |
 | `then` | `{ function, field?, functionOptions? }` — `field` narrows the match to a child (`@key` targets the property name). |
 | `extends` | A ruleset (or list) to inherit rules from: a file path or npm package. `[target, 'recommended' \| 'all' \| 'off']` controls what it contributes. |
 | `functions` / `functionsDir` | Custom functions to load by name (default dir `functions/`). |
 | `overrides` | Per-file-glob rule tweaks. |
 | `aliases` | Reusable `given` fragments referenced as `#alias`. |
+| `parserOptions` | YAML parser strictness, each set to a severity. `duplicateKeys` reports a repeated key (default `error`; `off` allows it, and the last value wins). `incompatibleValues` is off by default and reports `.nan` / `.inf` / `-.inf`, which `JSON.stringify` silently turns into `null`. Parser findings carry the code `parser`. |
 
 Built-in functions: `alphabetical`, `casing`, `defined`, `enumeration`, `falsy`, `length`, `or`, `pattern`, `schema`, `truthy`, `undefined`, `unreferencedReusableObject`, `xor`, `typedEnum`.
 
@@ -223,7 +234,7 @@ Anything outside that grammar is a ruleset error (`createRuleset` throws and nam
 
 | Export | What it does |
 | --- | --- |
-| `lintDocument(input, options?)` | Parse `input` and lint it against `options.ruleset` — a definition, or a `Ruleset` you already built; returns `IDiagnostic[]`. |
+| `lintDocument(input, options?)` | Parse `input` and lint it against `options.ruleset` — a definition, or a `Ruleset` you already built; returns `IDiagnostic[]`. `input` is the text, or `{ data, text? }` for a document already parsed. |
 | `lintDocumentWithResult(input, options?)` | Like `lintDocument`, but returns `{ diagnostics, output?, pluginData }` (including any plugin's rewritten `output`). |
 | `fixDocument(input, options?)` | Lint and apply `options.fixers` to a fixpoint; returns `{ output, fixed, applied, remaining, converged, passes }`. |
 | `createRuleset(definition?, basePath?, options?)` | Normalize a ruleset definition into a runnable `Ruleset`, layering the built-in functions and resolving `extends`. Memoized per `(definition object, basePath, restrictTo)` — treat a definition you have passed in as frozen. |
@@ -324,6 +335,19 @@ runtime-specific and may come back.
 
 Each `lint` figure is the mean wall time of one whole pass — **every rule, not a subset** — dominated by real work: JSONPath matching, the rule functions, and the dereference pass. A fresh document is parsed on every iteration on both sides, matching how the tools are actually called. The finding counts differ because the two rulesets are not byte-identical (different rule implementations and `$ref` resolution), so this is a **throughput** comparison rather than a correctness parity check — but on petstore both land on the same two findings.
 
+**Large documents.** `bun run bench:large <document.json>` times each phase of a lint run on its own, against any large OpenAPI document (or a synthetic one built from the fixtures when none is given), and fingerprints the findings so two runs can be checked for identical output. On a 26 MB public OpenAPI 3.0 document (3,700 operations, 7,100 component schemas; Bun 1.4.2, 4 vCPUs), medians:
+
+| phase | before | after |
+| --- | ---: | ---: |
+| `createDocument` (source-mapped parse) | 1,342 ms | 129 ms |
+| three `$.components.schemas..[?(...)]` rules on parsed data | 608 ms | ~36–60 ms |
+| the same checks as a hand-written walk | 24 ms | 24 ms |
+| `lint(text)`, three rules | 1,570 ms | ~290 ms |
+| `lint({ data, text })`, three rules | — | ~145 ms |
+| recommended OpenAPI preset, `$ref`s resolved | 5.5 s | 2.8 s |
+
+The findings — paths, ranges, messages — are byte-identical before and after.
+
 **Assembling the ruleset** is timed separately, because a process pays it once and then lints many documents: `createOpenApiRuleset` (compiling every rule's JSONPath and wiring up functions and format detectors) measures **~0.07 ms** on Bun and **~0.06 ms** on Node, versus **~0.26 ms** and **~0.24 ms** for `new Spectral()` + `setRuleset(oas)`. The benchmark warms up before timing and reports the mean over a fixed time budget; micro-benchmark figures vary by machine and runtime.
 
 ---

package/dist/core/document.d.ts

@@ -17,3 +17,28 @@ export type Document<T = unknown> = {
 };
 /** 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>;
+/** Options for {@link createDocumentFromData}: where the data came from, if the caller still has it. */
+export type IDataDocumentOptions = {
+    /** Display path carried onto findings (e.g. a path relative to cwd, or a URL). */
+    source?: string;
+    /**
+     * The text the data was parsed from. Findings get line:column ranges from
+     * it; without it every range is the zero range. Paths that the caller's own
+     * normalization moved resolve to the closest ancestor the text has.
+     */
+    text?: string;
+    /** The format of `text`; detected from its first character when omitted. */
+    format?: ParserFormat;
+};
+/**
+ * Wraps data a caller has already parsed in a {@link Document}, so a lint run
+ * does not parse the text a second time.
+ *
+ * Positions are worked out only when asked for, which in a lint run means
+ * only for the nodes that carry findings. For JSON text that is a scan of
+ * just the containers on the way to each path; YAML text is parsed on the
+ * first request (YAML positions cannot be found without a parse). The
+ * document reports no parser diagnostics: the caller's own parse already had
+ * its say on the text.
+ */
+export declare const createDocumentFromData: <T = unknown>(data: T, options?: IDataDocumentOptions) => Document<T>;

package/dist/core/document.js

@@ -1,4 +1,4 @@
-import { parseWithPointers } from "../parsers/index.js";
+import { createJsonLocator, detectFormat, parseWithPointers, parseYaml } from "../parsers/index.js";
 const createDocument = (input, options = {}) => {
   const parsed = parseWithPointers(input, options);
   return {
@@ -8,6 +8,21 @@ const createDocument = (input, options = {}) => {
     getLocationForJsonPath: (path, closest = false) => parsed.getLocationForJsonPath(path, closest)
   };
 };
+const createDocumentFromData = (data, options = {}) => {
+  const { text } = options;
+  let locate;
+  const getLocationForJsonPath = (path, closest = false) => {
+    if (text === void 0)
+      return void 0;
+    if (locate === void 0) {
+      const format = options.format ?? detectFormat(text);
+      locate = format === "json" ? createJsonLocator(text) : parseYaml(text).getLocationForJsonPath;
+    }
+    return locate(path, closest);
+  };
+  return { source: options.source, data, diagnostics: [], getLocationForJsonPath };
+};
 export {
-  createDocument
+  createDocument,
+  createDocumentFromData
 };

package/dist/core/filter.d.ts

@@ -11,6 +11,12 @@ export type FilterFn = (value: unknown, property: string | number | undefined, p
 export type CompiledFilter = {
     readonly test: FilterFn;
     readonly usesPath: boolean;
+    /**
+     * True when the filter can only match a plain object, worked out from its
+     * shape (see {@link matchesOnlyObjects}). A walk may then skip calling it
+     * on scalars and arrays, which on a typical document are most nodes.
+     */
+    readonly objectsOnly: boolean;
 } | {
     readonly error: string;
 };

package/dist/core/filter.js

@@ -1,10 +1,24 @@
 import { createBoundedCache } from "./bounded-cache.js";
 import { parseFilterExpression } from "./filter-expression.js";
-const filterRuntimeError = (message) => new Error(message);
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+let failed = false;
+const fail = () => {
+  failed = true;
+  return void 0;
+};
 const readMember = (object, name) => {
-  if (object === null || object === void 0) {
-    throw filterRuntimeError(`Cannot read "${name}" of ${object === null ? "null" : "undefined"}`);
+  if (object === null || object === void 0)
+    return fail();
+  if (typeof object === "object") {
+    if (Array.isArray(object)) {
+      if (name === "length")
+        return object.length;
+      const index = typeof name === "number" ? name : Number(name);
+      return Number.isInteger(index) ? object[index] : void 0;
+    }
+    const member = object[name];
+    if (member === void 0)
+      return void 0;
+    return Object.prototype.propertyIsEnumerable.call(object, name) ? member : void 0;
   }
   if (typeof object === "string") {
     if (name === "length")
@@ -12,14 +26,6 @@ const readMember = (object, name) => {
     const index = typeof name === "number" ? name : Number(name);
     return Number.isInteger(index) ? object[index] : void 0;
   }
-  if (Array.isArray(object)) {
-    if (name === "length")
-      return object.length;
-    const index = typeof name === "number" ? name : Number(name);
-    return Number.isInteger(index) ? object[index] : void 0;
-  }
-  if (isPlainObject(object))
-    return Object.prototype.propertyIsEnumerable.call(object, name) ? object[name] : void 0;
   return void 0;
 };
 const toStringArgument = (value) => {
@@ -28,14 +34,14 @@ const toStringArgument = (value) => {
   if (typeof value === "number" || typeof value === "boolean" || value === null || value === void 0) {
     return String(value);
   }
-  throw filterRuntimeError("Expected a string-like argument");
+  return fail();
 };
 const toRegExpArgument = (value) => {
   if (value instanceof RegExp)
     return value;
   if (typeof value === "string")
     return new RegExp(value);
-  throw filterRuntimeError("Expected a regular expression argument");
+  return fail();
 };
 const callMethod = (receiver, name, args) => {
   const [first] = args;
@@ -47,47 +53,47 @@ const callMethod = (receiver, name, args) => {
       }
       if (Array.isArray(receiver))
         return name === "indexOf" ? receiver.indexOf(first) : receiver.lastIndexOf(first);
-      throw filterRuntimeError(`"${name}" is not a function`);
+      return fail();
     }
     case "includes": {
       if (typeof receiver === "string")
         return receiver.includes(toStringArgument(first));
       if (Array.isArray(receiver))
         return receiver.includes(first);
-      throw filterRuntimeError('"includes" is not a function');
+      return fail();
     }
     case "startsWith":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"startsWith" is not a function');
+        return fail();
       return receiver.startsWith(toStringArgument(first));
     case "endsWith":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"endsWith" is not a function');
+        return fail();
       return receiver.endsWith(toStringArgument(first));
     case "match":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"match" is not a function');
+        return fail();
       return receiver.match(toRegExpArgument(first));
     case "test": {
       if (!(receiver instanceof RegExp))
-        throw filterRuntimeError('"test" is not a function');
+        return fail();
       receiver.lastIndex = 0;
       return receiver.test(toStringArgument(first));
     }
     case "toLowerCase":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"toLowerCase" is not a function');
+        return fail();
       return receiver.toLowerCase();
     case "toUpperCase":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"toUpperCase" is not a function');
+        return fail();
       return receiver.toUpperCase();
     case "trim":
       if (typeof receiver !== "string")
-        throw filterRuntimeError('"trim" is not a function');
+        return fail();
       return receiver.trim();
     default:
-      throw filterRuntimeError(`"${name}" is not a function`);
+      return fail();
   }
 };
 const looseEquals = (left, right) => {
@@ -129,6 +135,44 @@ const compareRelational = (operator, left, right) => {
       return a >= b;
   }
 };
+const memberChain = (node) => {
+  const names = [];
+  let current = node;
+  while (true) {
+    if (current.kind === "member")
+      names.push(current.name);
+    else if (current.kind === "computed" && current.index.kind === "literal" && (typeof current.index.value === "string" || typeof current.index.value === "number")) {
+      names.push(current.index.value);
+    } else
+      break;
+    current = current.object;
+  }
+  if (names.length === 0)
+    return void 0;
+  names.reverse();
+  return { base: current, names };
+};
+const compileMemberChain = ({ base, names }) => {
+  const count = names.length;
+  const read = (object2) => {
+    let current = object2;
+    for (let i = 0; i < count; i++) {
+      current = readMember(current, names[i]);
+      if (failed)
+        return void 0;
+    }
+    return current;
+  };
+  if (base.kind === "context" && base.ref === "value") {
+    if (count === 1) {
+      const name = names[0];
+      return (value) => readMember(value, name);
+    }
+    return (value) => read(value);
+  }
+  const object = compileNode(base);
+  return (value, property, parent, parentProperty, path, root) => read(object(value, property, parent, parentProperty, path, root));
+};
 const compileNode = (node) => {
   switch (node.kind) {
     case "literal":
@@ -152,18 +196,18 @@ const compileNode = (node) => {
           return (_value, _property, _parent, _parentProperty, _path, root) => root;
       }
     }
-    case "member": {
-      const object = compileNode(node.object);
-      const name = node.name;
-      return (value, property, parent, parentProperty, path, root) => readMember(object(value, property, parent, parentProperty, path, root), name);
-    }
+    case "member":
     case "computed": {
-      const object = compileNode(node.object);
-      const index = compileNode(node.index);
+      const chain = memberChain(node);
+      if (chain !== void 0)
+        return compileMemberChain(chain);
+      const computed = node;
+      const object = compileNode(computed.object);
+      const index = compileNode(computed.index);
       return (value, property, parent, parentProperty, path, root) => {
         const key = index(value, property, parent, parentProperty, path, root);
         if (typeof key !== "string" && typeof key !== "number") {
-          throw filterRuntimeError("A computed member must be a string or a number");
+          return fail();
         }
         return readMember(object(value, property, parent, parentProperty, path, root), key);
       };
@@ -178,7 +222,10 @@ const compileNode = (node) => {
         for (let i = 0; i < arity; i++) {
           values[i] = args[i](value, property, parent, parentProperty, path, root);
         }
-        return callMethod(object(value, property, parent, parentProperty, path, root), name, values);
+        const receiver = object(value, property, parent, parentProperty, path, root);
+        if (failed)
+          return void 0;
+        return callMethod(receiver, name, values);
       };
     }
     case "unary": {
@@ -195,21 +242,48 @@ const compileNode = (node) => {
       return (value, property, parent, parentProperty, path, root) => -Number(operand(value, property, parent, parentProperty, path, root));
     }
     case "logical": {
-      const left = compileNode(node.left);
-      const right = compileNode(node.right);
-      if (node.operator === "&&") {
+      const operator = node.operator;
+      const operands = [];
+      const collect = (operand) => {
+        if (operand.kind === "logical" && operand.operator === operator) {
+          collect(operand.left);
+          collect(operand.right);
+        } else
+          operands.push(compileNode(operand));
+      };
+      collect(node);
+      const count = operands.length;
+      if (operator === "&&") {
         return (value, property, parent, parentProperty, path, root) => {
-          const outcome = left(value, property, parent, parentProperty, path, root);
-          return outcome ? right(value, property, parent, parentProperty, path, root) : outcome;
+          let outcome;
+          for (let i = 0; i < count; i++) {
+            outcome = operands[i](value, property, parent, parentProperty, path, root);
+            if (failed)
+              return void 0;
+            if (!outcome)
+              return outcome;
+          }
+          return outcome;
         };
       }
       return (value, property, parent, parentProperty, path, root) => {
-        const outcome = left(value, property, parent, parentProperty, path, root);
-        return outcome ? outcome : right(value, property, parent, parentProperty, path, root);
+        let outcome;
+        for (let i = 0; i < count; i++) {
+          outcome = operands[i](value, property, parent, parentProperty, path, root);
+          if (failed)
+            return void 0;
+          if (outcome)
+            return outcome;
+        }
+        return outcome;
       };
     }
     case "comparison": {
       const left = compileNode(node.left);
+      if (node.right.kind === "literal" && (node.operator === "===" || node.operator === "!==")) {
+        const constant = node.right.value;
+        return node.operator === "===" ? (value, property, parent, parentProperty, path, root) => left(value, property, parent, parentProperty, path, root) === constant : (value, property, parent, parentProperty, path, root) => left(value, property, parent, parentProperty, path, root) !== constant;
+      }
       const right = compileNode(node.right);
       switch (node.operator) {
         case "===":
@@ -231,20 +305,66 @@ const compileNode = (node) => {
 const toFilterFn = (parsed) => {
   const test = compileNode(parsed.node);
   return (value, property, parent, root, path, parentProperty) => {
+    failed = false;
     try {
-      return Boolean(test(value, property, parent, parentProperty, path, root));
+      const outcome = test(value, property, parent, parentProperty, path, root);
+      return failed ? false : Boolean(outcome);
     } catch {
       return false;
+    } finally {
+      failed = false;
     }
   };
 };
+const objectOnlyName = (name) => typeof name === "string" && name !== "length" && !Number.isInteger(Number(name));
+const readsOffObject = (node) => {
+  let current = node;
+  while (true) {
+    if (current.kind === "call") {
+      current = current.object;
+      continue;
+    }
+    const inner = current.kind === "member" || current.kind === "computed" ? current.object : void 0;
+    if (inner === void 0)
+      return false;
+    if (inner.kind === "context" && inner.ref === "value") {
+      if (current.kind === "member")
+        return objectOnlyName(current.name);
+      const index = current.index;
+      return index.kind === "literal" && (typeof index.value === "string" || typeof index.value === "number") ? objectOnlyName(index.value) : false;
+    }
+    current = inner;
+  }
+};
+const matchesOnlyObjects = (node) => {
+  switch (node.kind) {
+    case "member":
+    case "computed":
+    case "call":
+      return readsOffObject(node);
+    case "comparison": {
+      if (node.operator !== "===" && node.operator !== "==")
+        return false;
+      const definedLiteral = (side) => side.kind === "literal" ? side.value !== void 0 && side.value !== null : side.kind === "regex";
+      if (definedLiteral(node.right))
+        return readsOffObject(node.left);
+      if (definedLiteral(node.left))
+        return readsOffObject(node.right);
+      return false;
+    }
+    case "logical":
+      return node.operator === "&&" ? matchesOnlyObjects(node.left) || matchesOnlyObjects(node.right) : matchesOnlyObjects(node.left) && matchesOnlyObjects(node.right);
+    default:
+      return false;
+  }
+};
 const filterCache = createBoundedCache(500);
 const compileFilter = (source) => {
   const cached = filterCache.get(source);
   if (cached)
     return cached;
   const parsed = parseFilterExpression(source);
-  const compiled = "error" in parsed ? { error: parsed.error } : { test: toFilterFn(parsed), usesPath: parsed.usesPath };
+  const compiled = "error" in parsed ? { error: parsed.error } : { test: toFilterFn(parsed), usesPath: parsed.usesPath, objectsOnly: matchesOnlyObjects(parsed.node) };
   filterCache.set(source, compiled);
   return compiled;
 };

package/dist/core/index.d.ts

@@ -1,10 +1,10 @@
 export { type BoundedCache, createBoundedCache } from './bounded-cache.js';
-export { createDocument, type Document, type IDocumentOptions } from './document.js';
+export { createDocument, createDocumentFromData, type Document, type IDataDocumentOptions, type IDocumentOptions, } from './document.js';
 export { type CompiledFilter, compileFilter, type FilterFn } from './filter.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 LintResolverResult, type LintResult, lint, lintWithResult, } from './lint.js';
+export { type LintInput, type LintOptions, type LintResolver, type LintResolverResult, 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';

package/dist/core/index.js

@@ -1,5 +1,5 @@
 import { createBoundedCache } from "./bounded-cache.js";
-import { createDocument } from "./document.js";
+import { createDocument, createDocumentFromData } from "./document.js";
 import { compileFilter } from "./filter.js";
 import { detectFormats } from "./formats.js";
 import { globToRegExp, matchesGlob } from "./glob.js";
@@ -15,6 +15,7 @@ export {
   compileQuery,
   createBoundedCache,
   createDocument,
+  createDocumentFromData,
   createLinter,
   createRuleset,
   detectFormats,

package/dist/core/jsonpath.d.ts

@@ -37,6 +37,7 @@ type Selector =
     test: FilterFn;
     source: string;
     usesPath: boolean;
+    objectsOnly: boolean;
 } | {
     kind: 'parent';
 } | {
@@ -65,19 +66,32 @@ export type CompiledPath = {
 };
 /** Compiles a JSONPath `expression` into a {@link CompiledPath}, cached by string so repeats are free. */
 export declare const compileQuery: (expression: string) => CompiledPath;
+/** How a path's `..` descents read the document. */
+export type QueryOptions = {
+    /**
+     * Treat the document as JSON Schema (or an OpenAPI/AsyncAPI document) and
+     * keep `..` out of instance data: the values of `example`, `examples`,
+     * `default`, `const` and `enum` are neither visited nor matched, except
+     * where those words are names in a map such as `properties`. A rule that
+     * looks at schemas then does not trip over an example payload that happens
+     * to read `"type": "object"`, and does not pay to walk it.
+     */
+    schemaAware?: boolean;
+};
 /** Evaluates a pre-compiled path against `data`. */
-export declare const queryCompiled: (data: unknown, compiled: CompiledPath) => IQueryMatch[];
+export declare const queryCompiled: (data: unknown, compiled: CompiledPath, options?: QueryOptions) => 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).
+ * Evaluates many pre-compiled paths against `data` with **one** walk of the
+ * tree for every path that contains a `..` descent, wherever that descent
+ * starts. `$..enum`, `$.paths.*..parameters` and
+ * `$.components.schemas..[?(@.deprecated)]` all ride the same traversal: a
+ * node is visited once, however many rules want to look at it, and a subtree
+ * no descent can reach is not visited at all. Paths without a descent are
+ * evaluated directly (cheap, no walk).
  *
  * Returns one match array per input path, index-aligned with `compiled`.
  */
-export declare const queryMany: (data: unknown, compiled: CompiledPath[]) => IQueryMatch[][];
+export declare const queryMany: (data: unknown, compiled: CompiledPath[], options?: readonly (QueryOptions | undefined)[]) => IQueryMatch[][];
 /** Runs a JSONPath expression and returns each match with its concrete path. */
-export declare const query: (data: unknown, expression: string) => IQueryMatch[];
+export declare const query: (data: unknown, expression: string, options?: QueryOptions) => IQueryMatch[];
 export {};