@amritk/lint 0.7.1 → 0.8.0

package/dist/core/jsonpath.js

@@ -128,7 +128,13 @@ const bracketSelector = (content, onError) => {
       onError(filter.error);
       return { kind: "none" };
     }
-    return { kind: "filter", test: filter.test, source: expr, usesPath: filter.usesPath };
+    return {
+      kind: "filter",
+      test: filter.test,
+      source: expr,
+      usesPath: filter.usesPath,
+      objectsOnly: filter.objectsOnly
+    };
   }
   if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
     const inner = trimmed.slice(1, -1).trim();
@@ -410,31 +416,87 @@ const applySelector = (node, selector, root, out) => {
       return;
   }
 };
-const walkDescendants = (node, visit) => {
+const DATA_KEYWORDS = /* @__PURE__ */ new Set(["example", "examples", "default", "const", "enum"]);
+const NAME_MAP_KEYWORDS = /* @__PURE__ */ new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "schemas",
+  "responses",
+  "parameters",
+  "headers",
+  "requestBodies",
+  "securitySchemes",
+  "links",
+  "callbacks",
+  "pathItems",
+  "webhooks",
+  "encoding",
+  "variables",
+  "dependencies",
+  "messages",
+  "channels",
+  "operations",
+  "servers",
+  "serverVariables",
+  "messageTraits",
+  "operationTraits",
+  "correlationIds",
+  "replies",
+  "replyAddresses",
+  "serverBindings",
+  "channelBindings",
+  "operationBindings",
+  "messageBindings"
+]);
+const isNameMap = (node) => {
+  const chain = [];
+  for (let n = node; n !== void 0 && n.parent !== void 0; n = n.parent)
+    chain.push(n);
+  let nameMap = false;
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const key = chain[i].key;
+    nameMap = !nameMap && typeof key === "string" && NAME_MAP_KEYWORDS.has(key);
+  }
+  return nameMap;
+};
+const isDataChild = (node) => typeof node.key === "string" && DATA_KEYWORDS.has(node.key) && isObject(node.parent?.value) && !isNameMap(node.parent);
+const walkDescendants = (node, visit, schemaAware) => {
   const stack = [node];
+  const nameMaps = [schemaAware && isNameMap(node)];
   while (stack.length > 0) {
     const current = stack.pop();
+    const nameMap = nameMaps.pop();
     visit(current);
     const value = current.value;
     if (Array.isArray(value)) {
-      for (let idx = value.length - 1; idx >= 0; idx--)
+      for (let idx = value.length - 1; idx >= 0; idx--) {
         stack.push({ value: value[idx], parent: current, key: idx });
+        nameMaps.push(false);
+      }
     } else if (isObject(value)) {
       const keys = Object.keys(value);
       for (let k = keys.length - 1; k >= 0; k--) {
         const key = keys[k];
+        if (schemaAware && !nameMap && DATA_KEYWORDS.has(key))
+          continue;
         stack.push({ value: value[key], parent: current, key });
+        nameMaps.push(schemaAware && !nameMap && NAME_MAP_KEYWORDS.has(key));
       }
     }
   }
 };
-const applySteps = (root, initial, steps) => {
+const applySteps = (root, initial, steps, schemaAware = false) => {
   let current = initial;
   for (const step of steps) {
-    const next = [];
+    let next = [];
     if (step.recursive) {
       for (const node of current)
-        walkDescendants(node, (n) => applySelector(n, step.selector, root, next));
+        walkDescendants(node, (n) => applySelector(n, step.selector, root, next), schemaAware);
+      if (schemaAware)
+        next = next.filter((n) => !isDataChild(n));
     } else {
       for (const node of current)
         applySelector(node, step.selector, root, next);
@@ -443,7 +505,7 @@ const applySteps = (root, initial, steps) => {
   }
   return current;
 };
-const runSteps = (root, steps) => applySteps(root, [{ value: root, parent: void 0, key: void 0 }], steps);
+const runSteps = (root, steps, schemaAware = false) => applySteps(root, [{ value: root, parent: void 0, key: void 0 }], steps, schemaAware);
 const toMatches = (nodes) => {
   const out = new Array(nodes.length);
   for (let i = 0; i < nodes.length; i++) {
@@ -452,92 +514,274 @@ const toMatches = (nodes) => {
   }
   return out;
 };
-const queryCompiled = (data, compiled) => {
+const queryCompiled = (data, compiled, options = {}) => {
   if (compiled.error !== void 0)
     return [];
   if (data === null || data === void 0)
     return [];
-  return toMatches(runSteps(data, compiled.steps));
+  return toMatches(runSteps(data, compiled.steps, options.schemaAware === true));
 };
-const queryMany = (data, compiled) => {
+const queryMany = (data, compiled, options = []) => {
   const out = new Array(compiled.length);
   if (data === null || data === void 0) {
     for (let i = 0; i < compiled.length; i++)
       out[i] = [];
     return out;
   }
-  const recursive = [];
+  const shared = [];
+  const descents = [];
   for (let i = 0; i < compiled.length; i++) {
     const c = compiled[i];
     if (c.error !== void 0) {
       out[i] = [];
       continue;
     }
-    const first = c.steps[0];
-    if (first?.recursive)
-      recursive.push(i);
-    else
-      out[i] = queryCompiled(data, c);
+    const schemaAware = options[i]?.schemaAware === true;
+    const descent = c.hasDescent ? toDescent(c.steps, schemaAware) : void 0;
+    if (descent === void 0) {
+      out[i] = queryCompiled(data, c, { schemaAware });
+      continue;
+    }
+    shared.push(i);
+    descents.push(descent);
   }
-  if (recursive.length > 0) {
-    const firsts = recursive.map((i) => compiled[i].steps[0]);
-    const seeds = recursive.map(() => []);
-    seedDescents(data, firsts, seeds);
-    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)));
+  if (descents.length > 0) {
+    const seeds = descents.map(() => []);
+    walkShared(data, descents, seeds);
+    for (let d = 0; d < descents.length; d++) {
+      const { rest, schemaAware } = descents[d];
+      const seeded = seeds[d];
+      out[shared[d]] = toMatches(rest.length === 0 ? seeded : applySteps(data, seeded, rest, schemaAware));
     }
   }
   return out;
 };
-const seedDescents = (data, firsts, seeds) => {
+const childPathString = (parent, key) => {
+  const path = pathOf(parent);
+  path.push(key);
+  return pathToJsonPathString(path);
+};
+const toDescent = (steps, schemaAware) => {
+  const prefix = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (step.recursive)
+      return { prefix, first: step.selector, rest: steps.slice(i + 1), schemaAware };
+    const kind = step.selector.kind;
+    if (kind !== "child" && kind !== "index" && kind !== "wildcard" && kind !== "filter")
+      return void 0;
+    prefix.push(step.selector);
+  }
+  return void 0;
+};
+const prefixSelects = (selector, parent, key, child, root) => {
+  const value = parent.value;
+  switch (selector.kind) {
+    case "child":
+      return typeof key === "number" ? selector.index === key : selector.name === key;
+    case "index": {
+      if (typeof key === "number") {
+        const idx = selector.index < 0 ? value.length + selector.index : selector.index;
+        return idx === key;
+      }
+      return key === String(selector.index);
+    }
+    case "wildcard":
+      return true;
+    case "filter":
+      return selector.test(child, key, value, root, selector.usesPath ? childPathString(parent, key) : "", parent.key);
+    default:
+      return false;
+  }
+};
+const createScope = (descents, active, pending) => {
   const byName = /* @__PURE__ */ new Map();
   const numericChild = [];
+  const wildcards = [];
+  const filters = [];
   const others = [];
-  for (let r = 0; r < firsts.length; r++) {
-    const selector = firsts[r].selector;
-    if (selector.kind !== "child") {
-      others.push(r);
-      continue;
+  let schemaAware = false;
+  for (const d of active) {
+    if (descents[d].schemaAware)
+      schemaAware = true;
+    const selector = descents[d].first;
+    if (selector.kind === "child") {
+      const existing = byName.get(selector.name);
+      if (existing === void 0)
+        byName.set(selector.name, [d]);
+      else
+        existing.push(d);
+      if (selector.index !== void 0)
+        numericChild.push(d);
+    } else if (selector.kind === "wildcard")
+      wildcards.push(d);
+    else if (selector.kind === "filter")
+      filters.push(d);
+    else
+      others.push(d);
+  }
+  return {
+    active,
+    pending,
+    byName,
+    numericChild,
+    wildcards,
+    filters,
+    others,
+    settled: void 0,
+    next: /* @__PURE__ */ new Map(),
+    schemaAware,
+    outsideData: void 0
+  };
+};
+const outsideDataScope = (descents, scope) => {
+  if (scope.outsideData === void 0) {
+    scope.outsideData = createScope(descents, scope.active.filter((d) => !descents[d].schemaAware), scope.pending);
+  }
+  return scope.outsideData;
+};
+const settledScope = (descents, scope) => {
+  if (scope.pending.length === 0)
+    return scope;
+  if (scope.settled === void 0)
+    scope.settled = createScope(descents, scope.active, []);
+  return scope.settled;
+};
+const childScope = (descents, scope, parent, key, child, root) => {
+  const pending = scope.pending;
+  if (pending.length === 0)
+    return scope;
+  let advanced;
+  for (const entry of pending) {
+    const [d, step] = entry;
+    const prefix = descents[d].prefix;
+    if (prefixSelects(prefix[step], parent, key, child, root)) {
+      if (advanced === void 0)
+        advanced = [];
+      advanced.push(entry);
     }
-    const existing = byName.get(selector.name);
-    if (existing === void 0)
-      byName.set(selector.name, [r]);
+  }
+  if (advanced === void 0)
+    return settledScope(descents, scope);
+  let signature = "";
+  for (const [d, step] of advanced)
+    signature += `${d}:${step},`;
+  const cached = scope.next.get(signature);
+  if (cached !== void 0)
+    return cached;
+  const active = scope.active.slice();
+  const stillPending = [];
+  for (const [d, step] of advanced) {
+    if (step + 1 === descents[d].prefix.length)
+      active.push(d);
     else
-      existing.push(r);
-    if (selector.index !== void 0)
-      numericChild.push(r);
+      stillPending.push([d, step + 1]);
   }
-  const stack = [{ value: data, parent: void 0, key: void 0 }];
-  while (stack.length > 0) {
-    const current = stack.pop();
+  const built = createScope(descents, active, stillPending);
+  scope.next.set(signature, built);
+  return built;
+};
+const isLive = (scope) => scope.active.length > 0 || scope.pending.length > 0;
+const walkShared = (data, descents, seeds) => {
+  const rootActive = [];
+  const rootPending = [];
+  for (let d = 0; d < descents.length; d++) {
+    if (descents[d].prefix.length === 0)
+      rootActive.push(d);
+    else
+      rootPending.push([d, 0]);
+  }
+  const nodes = [{ value: data, parent: void 0, key: void 0 }];
+  const scopes = [createScope(descents, rootActive, rootPending)];
+  const tracksNameMaps = descents.some((descent) => descent.schemaAware);
+  const nameMaps = [false];
+  while (nodes.length > 0) {
+    const current = nodes.pop();
+    const outer = scopes.pop();
+    const nameMap = tracksNameMaps ? nameMaps.pop() : false;
     const value = current.value;
-    if (Array.isArray(value)) {
-      for (let idx = value.length - 1; idx >= 0; idx--)
-        stack.push({ value: value[idx], parent: current, key: idx });
-      for (const r of numericChild)
-        applySelector(current, firsts[r].selector, data, seeds[r]);
-    } else if (isObject(value)) {
-      const base = stack.length;
-      for (const key of Object.keys(value)) {
-        const child = { value: value[key], parent: current, key };
-        stack.push(child);
-        const interested = byName.get(key);
-        if (interested !== void 0)
-          for (const r of interested)
-            seeds[r].push(child);
+    const base = nodes.length;
+    if (typeof value === "object" && value !== null) {
+      const isArray = Array.isArray(value);
+      const keys = isArray ? void 0 : Object.keys(value);
+      const length = isArray ? value.length : keys.length;
+      for (let i = 0; i < length; i++) {
+        const key = isArray ? i : keys[i];
+        const child = value[key];
+        const scope = outer.schemaAware && !isArray && !nameMap && DATA_KEYWORDS.has(key) ? outsideDataScope(descents, outer) : outer;
+        const { byName, wildcards, filters } = scope;
+        let node;
+        if (!isArray) {
+          const interested = byName.get(key);
+          if (interested !== void 0) {
+            node = { value: child, parent: current, key };
+            for (const d of interested)
+              seeds[d].push(node);
+          }
+        }
+        if (wildcards.length > 0) {
+          if (node === void 0)
+            node = { value: child, parent: current, key };
+          for (const d of wildcards)
+            seeds[d].push(node);
+        }
+        if (filters.length > 0) {
+          const childIsObject = isObject(child);
+          for (const d of filters) {
+            const selector = descents[d].first;
+            if (selector.objectsOnly && !childIsObject)
+              continue;
+            const path = selector.usesPath ? childPathString(current, key) : "";
+            if (selector.test(child, key, value, data, path, current.key)) {
+              if (node === void 0)
+                node = { value: child, parent: current, key };
+              seeds[d].push(node);
+            }
+          }
+        }
+        const inner = childScope(descents, scope, current, key, child, data);
+        const visit = typeof child === "object" && child !== null ? isLive(inner) : inner.others.length > 0;
+        if (visit) {
+          nodes.push(node === void 0 ? { value: child, parent: current, key } : node);
+          scopes.push(inner);
+          if (tracksNameMaps)
+            nameMaps.push(!isArray && !nameMap && NAME_MAP_KEYWORDS.has(key));
+        }
       }
-      for (let i = base, j = stack.length - 1; i < j; i++, j--) {
-        const held = stack[i];
-        stack[i] = stack[j];
-        stack[j] = held;
+      if (isArray) {
+        for (const d of outer.numericChild) {
+          applySelector(current, descents[d].first, data, seeds[d]);
+        }
+      }
+      for (let i = base, j = nodes.length - 1; i < j; i++, j--) {
+        const heldNode = nodes[i];
+        nodes[i] = nodes[j];
+        nodes[j] = heldNode;
+        const heldScope = scopes[i];
+        scopes[i] = scopes[j];
+        scopes[j] = heldScope;
+        if (tracksNameMaps) {
+          const heldNameMap = nameMaps[i];
+          nameMaps[i] = nameMaps[j];
+          nameMaps[j] = heldNameMap;
+        }
+      }
+    }
+    for (const d of outer.others) {
+      const descent = descents[d];
+      if (!descent.schemaAware) {
+        applySelector(current, descent.first, data, seeds[d]);
+        continue;
       }
+      const found = [];
+      applySelector(current, descent.first, data, found);
+      for (const node of found)
+        if (!isDataChild(node))
+          seeds[d].push(node);
     }
-    for (const r of others)
-      applySelector(current, firsts[r].selector, data, seeds[r]);
   }
 };
-const query = (data, expression) => queryCompiled(data, compileQuery(expression));
+const query = (data, expression, options = {}) => queryCompiled(data, compileQuery(expression), options);
 export {
   compileQuery,
   query,

package/dist/core/lint.d.ts

@@ -28,9 +28,20 @@ export type LintResolverResult = {
  * `@amritk/resolve-refs` keeps the `$ref` node in place when a chain would close
  * a cycle, which is what makes its output safe here.
  */
-export type LintResolver = (document: Document, context: {
+export type LintResolver = (document: Document, 
+/** `input` is the document text: `''` when the caller linted data without it. */
+context: {
     input: string;
 }) => LintResolverResult | Promise<LintResolverResult>;
+/**
+ * What {@link lint} reads: the document text, or data the caller has already
+ * parsed — optionally with the text it came from, which is only read to put
+ * line:column ranges on findings. See {@link createDocumentFromData}.
+ */
+export type LintInput = string | {
+    data: unknown;
+    text?: string;
+};
 /** Options for {@link lint} / {@link lintWithResult}. */
 export type LintOptions = IDocumentOptions & {
     /** A normalized ruleset to evaluate (built via {@link createRuleset}). */
@@ -65,7 +76,12 @@ export type LintResult = {
  * level entry point (such as `@amritk/lint`) supplies the ruleset, and
  * optionally a resolver and format-skip predicate; {@link lint} is a thin
  * wrapper returning just the diagnostics.
+ *
+ * Handed `{ data, text? }` instead of a string, the parse is skipped: the
+ * run starts from the caller's data, and `text` (when given) is consulted
+ * only to put ranges on findings. The resolver then sees `text` (or `''`)
+ * as its `input`.
  */
-export declare const lintWithResult: (input: string, options: LintOptions) => Promise<LintResult>;
+export declare const lintWithResult: (input: LintInput, options: LintOptions) => Promise<LintResult>;
 /** Lints `input` against a normalized `ruleset` and returns just the findings. */
-export declare const lint: (input: string, options: LintOptions) => Promise<IDiagnostic[]>;
+export declare const lint: (input: LintInput, options: LintOptions) => Promise<IDiagnostic[]>;

package/dist/core/lint.js

@@ -1,5 +1,5 @@
 import { detectFormat } from "../parsers/index.js";
-import { createDocument } from "./document.js";
+import { createDocument, createDocumentFromData } from "./document.js";
 import { bySourceThenPosition, withoutDuplicates } from "./order.js";
 import { runPlugins } from "./plugin.js";
 import { createLinter } from "./runner.js";
@@ -13,20 +13,35 @@ const toParserSeverity = (value) => {
 };
 const lintWithResult = async (input, options) => {
   const { ruleset, resolve, skip, plugins, ...documentOptions } = options;
-  const duplicateKeys = toParserSeverity(ruleset.parserOptions?.duplicateKeys);
-  const incompatibleValues = toParserSeverity(ruleset.parserOptions?.incompatibleValues);
-  const document = createDocument(input, {
-    ...documentOptions,
-    ...duplicateKeys !== void 0 ? { duplicateKeys } : {},
-    ...incompatibleValues !== void 0 ? { incompatibleValues } : {}
-  });
+  let document;
+  let text;
+  if (typeof input === "string") {
+    const duplicateKeys = toParserSeverity(ruleset.parserOptions?.duplicateKeys);
+    const incompatibleValues = toParserSeverity(ruleset.parserOptions?.incompatibleValues);
+    document = createDocument(input, {
+      ...documentOptions,
+      ...duplicateKeys !== void 0 ? { duplicateKeys } : {},
+      ...incompatibleValues !== void 0 ? { incompatibleValues } : {}
+    });
+    text = input;
+  } else {
+    if (plugins && plugins.length > 0 && input.text === void 0) {
+      throw new Error("Plugins need the document text: pass `text` alongside `data`");
+    }
+    document = createDocumentFromData(input.data, {
+      ...documentOptions.source !== void 0 ? { source: documentOptions.source } : {},
+      ...documentOptions.format !== void 0 ? { format: documentOptions.format } : {},
+      ...input.text !== void 0 ? { text: input.text } : {}
+    });
+    text = input.text ?? "";
+  }
   if (skip?.(document.data))
     return { diagnostics: [], pluginData: {} };
   let resolved = document.data;
   let sources;
   let resolverDiagnostics = [];
   if (resolve) {
-    const result = await resolve(document, { input });
+    const result = await resolve(document, { input: text });
     resolved = result.resolved;
     sources = result.sources;
     if (result.diagnostics)
@@ -48,9 +63,9 @@ const lintWithResult = async (input, options) => {
   const diagnostics = withoutDuplicates([...parserResults, ...resolverDiagnostics, ...ruleResults].sort(bySourceThenPosition));
   if (!plugins || plugins.length === 0)
     return { diagnostics, pluginData: {} };
-  const format = documentOptions.format ?? detectFormat(input);
+  const format = documentOptions.format ?? detectFormat(text);
   const run = runPlugins(plugins, diagnostics, {
-    input,
+    input: text,
     format,
     document,
     resolved,

package/dist/core/ruleset.js

@@ -67,6 +67,7 @@ const normalizeRule = (name, def, modifier, declaring = {}) => {
     formats: formats ? new Set(formats) : void 0,
     recommended,
     resolved: def.resolved ?? true,
+    ...def.descent === "schema" ? { descent: "schema" } : {},
     documentationUrl
   };
 };

package/dist/core/runner.js

@@ -81,19 +81,21 @@ const runPlan = async (ruleset, rules, data, document, formats, out, sources) =>
       out.push(errorDiagnostic(rule, [], `Rule "${rule.name}" references unknown function "${missing}"`, ZERO_RANGE, document.source));
       continue;
     }
+    const schemaAware = rule.descent === "schema";
     for (const given of ruleset.expandGiven(rule.given, formats)) {
-      let group = groups.get(given);
+      const key = schemaAware ? `${given}\0schema` : given;
+      let group = groups.get(key);
       if (!group) {
-        group = { compiled: compileQuery(given), rules: [] };
-        groups.set(given, group);
-        order.push(given);
+        group = { compiled: compileQuery(given), schemaAware, rules: [] };
+        groups.set(key, group);
+        order.push(key);
       }
       if (group.rules[group.rules.length - 1] !== rule)
         group.rules.push(rule);
     }
   }
-  const compiled = order.map((given) => groups.get(given).compiled);
-  const matchesPerGiven = queryMany(data, compiled);
+  const planned = order.map((key) => groups.get(key));
+  const matchesPerGiven = queryMany(data, planned.map((group) => group.compiled), planned.map((group) => group.schemaAware ? { schemaAware: true } : void 0));
   for (let i = 0; i < order.length; i++) {
     const group = groups.get(order[i]);
     const matches = matchesPerGiven[i];

package/dist/core/types.d.ts

@@ -63,6 +63,16 @@ export type IRuleDefinition = {
     recommended?: boolean;
     /** When false, the rule runs against the unresolved document. Default true. */
     resolved?: boolean;
+    /**
+     * How `..` in `given` reads the document. `'all'` (the default) visits every
+     * node. `'schema'` treats it as JSON Schema — or an OpenAPI/AsyncAPI document
+     * — and stays 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`. Use it for
+     * rules about schemas, so an example payload that reads `"type": "object"`
+     * is not mistaken for one.
+     */
+    descent?: 'all' | 'schema';
     documentationUrl?: string;
 };
 /** Shorthand a rule may take in `rules`: a definition, a boolean, or a severity. */
@@ -124,6 +134,8 @@ export type ResolvedRule = {
     formats?: Set<string> | undefined;
     recommended: boolean;
     resolved: boolean;
+    /** See {@link IRuleDefinition.descent}; absent means `'all'`. */
+    descent?: 'all' | 'schema' | undefined;
     documentationUrl?: string | undefined;
 };
 /** A single finding emitted by the runner, mapped back to a source range. */

package/dist/core/validate-ruleset.js

@@ -57,6 +57,9 @@ const validateRule = (name, entry, path, problems) => {
   } else {
     validateThen(entry["then"], [...path, "then"], problems);
   }
+  if (entry["descent"] !== void 0 && entry["descent"] !== "all" && entry["descent"] !== "schema") {
+    problems.push({ message: `Rule "${name}" \`descent\` must be "all" or "schema"`, path: [...path, "descent"] });
+  }
   if (entry["severity"] !== void 0 && !isValidSeverity(entry["severity"])) {
     problems.push({ message: `Rule "${name}" has invalid severity`, path: [...path, "severity"] });
   }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { type IDocumentOptions, type LintPlugin, type LintResolver, type ResolvedExtend, type Ruleset } from './core/index.js';
+import { type IDocumentOptions, type LintInput, type LintPlugin, type LintResolver, type ResolvedExtend, type Ruleset } from './core/index.js';
 import type { IDiagnostic, RulesetDefinition } from './core/types.js';
 import { type AppliedFix, type FixerRegistry } from './fix/index.js';
 import { type IRulesetTrustOptions } from './ruleset-files.js';
-export { type AliasDefinition, type CompiledPath, compileQuery, createDocument, createLinter, type Document, detectFormats, type ExtendModifier, type ExtendResolver, type Format, globToRegExp, type IDocumentOptions, type IQueryMatch, type IRulesetProblem, type IRunOptions, type Linter, type LintOptions, type LintPlugin, type LintPluginContext, type LintPluginResult, type LintResolver, type LintResolverResult, type LintResult, lint, lintWithResult, matchesGlob, type PluginRunResult, pointerToPath, query, queryCompiled, queryMany, type ResolvedExtend, type Ruleset, type RulesetOptions, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, runPlugins, validateRuleset, } from './core/index.js';
+export { type AliasDefinition, type CompiledPath, compileQuery, createDocument, createDocumentFromData, createLinter, type Document, detectFormats, type ExtendModifier, type ExtendResolver, type Format, globToRegExp, type IDataDocumentOptions, type IDocumentOptions, type IQueryMatch, type IRulesetProblem, type IRunOptions, type Linter, type LintInput, type LintOptions, type LintPlugin, type LintPluginContext, type LintPluginResult, type LintResolver, type LintResolverResult, type LintResult, lint, lintWithResult, matchesGlob, type PluginRunResult, pointerToPath, query, queryCompiled, queryMany, type ResolvedExtend, type Ruleset, type RulesetOptions, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, runPlugins, validateRuleset, } from './core/index.js';
 export { type AppliedFix, type ApplyFixesOptions, applyFixes, createFixPlugin, type EditOp, FIX_PLUGIN_NAME, type FixContext, type Fixer, type FixerRegistry, type FixPluginData, type FixResult, type ParserFormat, } from './fix/index.js';
 export { alphabetical, builtinFunctions, type CasingType, casing, defined, enumeration, falsy, type IAlphabeticalOptions, type ICasingOptions, type IOrOptions, type ISchemaOptions, type IUnreferencedReusableObjectOptions, type IXorOptions, length, or, pattern, schema, truthy, typedEnum, undefinedFn, unreferencedReusableObject, xor, } from './functions/index.js';
 export { detectFormat, parseWithPointers } from './parsers/index.js';
@@ -87,6 +87,10 @@ export type ILintResult = {
  * ruleset. Returns just the findings; use {@link lintDocumentWithResult} for the
  * full result.
  *
+ * A caller that has already parsed the document passes `{ data, text? }`
+ * instead of the string, and the parse is skipped: `text` is only read to
+ * put line:column ranges on the findings (see `createDocumentFromData`).
+ *
  * @example
  * ```ts
  * const ruleset = {
@@ -99,13 +103,13 @@ export type ILintResult = {
  * // findings[].severity is numeric (0 error, 1 warn, 2 info, 3 hint).
  * ```
  */
-export declare const lintDocument: (input: string, options?: ILintOptions) => Promise<IDiagnostic[]>;
+export declare const lintDocument: (input: LintInput, options?: ILintOptions) => Promise<IDiagnostic[]>;
 /**
  * Like {@link lintDocument}, but returns the full {@link ILintResult} — including
  * anything the configured `plugins` produced (e.g. the auto-fix plugin's
  * rewritten `output`).
  */
-export declare const lintDocumentWithResult: (input: string, options?: ILintOptions) => Promise<ILintResult>;
+export declare const lintDocumentWithResult: (input: LintInput, options?: ILintOptions) => Promise<ILintResult>;
 /** Options for {@link fixDocument}: the lint options plus auto-fix controls. */
 export type IFixOptions = Omit<ILintOptions, 'plugins'> & {
     /** The fixers to apply, keyed by rule code. Defaults to an empty registry (no fixes). */