@amritk/lint 0.2.0 → 0.3.0

package/README.md

@@ -214,6 +214,24 @@ The structural rules validate against the **official `spec.openapis.org` meta-sc
 
 ---
 
+## Benchmarks
+
+The `bench/` suite pits `@amritk/lint` head-to-head against **[Spectral](https://github.com/stoplightio/spectral)** — the OpenAPI linter this package is modelled on (hence the `spectral:oas` alias) — over the real-world specs the test suite lints: Swagger's petstore, the DigitalOcean API, and the OpenAI API (~17 KB to ~2.8 MB, spanning a small config and a genuinely large document). Both do the same job: **parse → dereference internal `$ref`s → run their recommended OpenAPI ruleset** (mjst dereferences in memory with [`@amritk/resolve-refs`](../resolve-refs), exactly as the CLI does; Spectral uses its own default resolver). Representative numbers (Bun 1.3, Linux x64 — your hardware will differ, run `bun run bench` yourself):
+
+| document | size | mjst | Spectral | speedup | findings (mjst / Spectral) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| petstore (Swagger) | 17 KB | ~6 ms | ~124 ms | **~19×** | 2 / 2 |
+| digitalocean | 105 KB | ~37 ms | ~477 ms | **~13×** | 3507 / 4319 |
+| openai | 2.8 MB | ~1.3 s | errored¹ | — | 1176 / — |
+
+¹ Spectral's JSONPath engine (`nimma`) throws on the 2.8 MB OpenAI spec under Bun, so that row is mjst-only; mjst lints it end to end.
+
+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.
+
+**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.06 ms**, versus **~0.4 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.
+
+---
+
 ## License
 
 MIT

package/dist/core/glob.d.ts

@@ -1,4 +1,4 @@
-/** Compiles a glob pattern (`**`, `*`, `?`) into an anchored RegExp. */
+/** Compiles a glob pattern (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp, cached by string. */
 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

@@ -1,10 +1,73 @@
 /**
  * Minimal glob → RegExp for matching override `files` patterns against document
- * paths. Supports `**` (any path segments), `*` (within a segment), and `?`.
+ * paths. Supports `**` (any path segments), `*` (within a segment), `?`, and
+ * brace expansion (`{a,b}`).
  */
 const REGEXP_SPECIAL = /[\\^$.*+?()[\]{}|/]/;
-/** Compiles a glob pattern (`**`, `*`, `?`) into an anchored RegExp. */
-export const globToRegExp = (glob) => {
+/** Splits brace-group content on top-level commas (commas nested in inner braces stay put). */
+const splitTopLevel = (body) => {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of body) {
+        if (ch === '{')
+            depth++;
+        else if (ch === '}')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+};
+/**
+ * Expands brace alternations (`a.{yaml,yml}` → `a.yaml`, `a.yml`) into concrete
+ * globs, cartesian across multiple groups. A group with no top-level comma is
+ * left literal (mirroring minimatch), so `{}` in a path does not vanish.
+ */
+const expandBraces = (glob) => {
+    const open = glob.indexOf('{');
+    if (open === -1)
+        return [glob];
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < glob.length; i++) {
+        if (glob[i] === '{')
+            depth++;
+        else if (glob[i] === '}') {
+            depth--;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close === -1)
+        return [glob];
+    const prefix = glob.slice(0, open);
+    const body = glob.slice(open + 1, close);
+    const suffix = glob.slice(close + 1);
+    const options = splitTopLevel(body);
+    if (options.length === 1) {
+        // No alternation — keep the braces as literal characters.
+        return expandBraces(suffix).map((rest) => `${prefix}{${body}}${rest}`);
+    }
+    const results = [];
+    for (const option of options) {
+        for (const expandedOption of expandBraces(option)) {
+            for (const expandedSuffix of expandBraces(suffix)) {
+                results.push(prefix + expandedOption + expandedSuffix);
+            }
+        }
+    }
+    return results;
+};
+/** Compiles a single (brace-free) glob into an un-anchored RegExp source. */
+const globInnerSource = (glob) => {
     let source = '';
     for (let i = 0; i < glob.length; i++) {
         const char = glob[i];
@@ -33,7 +96,20 @@ export const globToRegExp = (glob) => {
             source += char;
         }
     }
-    return new RegExp(`^${source}$`);
+    return source;
+};
+// Compiled patterns are cached by their glob string; the ruleset's override
+// globs are re-tested against every linted source, so compiling once matters.
+const regexCache = new Map();
+/** Compiles a glob pattern (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp, cached by string. */
+export const globToRegExp = (glob) => {
+    const cached = regexCache.get(glob);
+    if (cached)
+        return cached;
+    const alternatives = expandBraces(glob).map(globInnerSource);
+    const regex = new RegExp(`^(?:${alternatives.join('|')})$`);
+    regexCache.set(glob, regex);
+    return regex;
 };
 /** Returns true if `path` matches any of the glob patterns. */
 export const matchesGlob = (path, patterns) => {
@@ -43,6 +119,14 @@ export const matchesGlob = (path, patterns) => {
         if (regex.test(path))
             return true;
         // A pattern without a slash also matches the basename.
-        return !pattern.includes('/') && regex.test(basename);
+        if (!pattern.includes('/'))
+            return regex.test(basename);
+        // A relative pattern that contains a slash matches an absolute source by
+        // suffix, so `src/api.yaml` matches `/home/user/repo/src/api.yaml` — the
+        // minimatch/Spectral behavior for override globs against absolute paths.
+        if (!pattern.startsWith('/') && !pattern.startsWith('**')) {
+            return globToRegExp(`**/${pattern}`).test(path);
+        }
+        return false;
     });
 };

package/dist/core/index.d.ts

@@ -2,7 +2,7 @@ export { createDocument, type Document, type IDocumentOptions } from './document
 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 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

@@ -2,7 +2,7 @@ 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 { lint, lintWithResult, } from './lint.js';
 export { runPlugins, } from './plugin.js';
 export { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, } from './pointers.js';
 export { createRuleset, } from './ruleset.js';

package/dist/core/jsonpath.d.ts

@@ -4,7 +4,7 @@ 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 FilterFn = (value: unknown, property: string | number | undefined, parent: unknown, root: unknown, path: string, parentProperty: string | number | undefined) => boolean;
 type Selector = {
     kind: 'child';
     name: string;
@@ -16,6 +16,14 @@ type Selector = {
 } | {
     kind: 'union';
     names: (string | number)[];
+} | {
+    kind: 'slice';
+    start?: number;
+    end?: number;
+    step?: number;
+} | {
+    kind: 'scriptIndex';
+    offset: number;
 } | {
     kind: 'filter';
     test: FilterFn;
@@ -25,6 +33,8 @@ type Selector = {
     kind: 'parent';
 } | {
     kind: 'keys';
+} | {
+    kind: 'none';
 };
 /** One compiled segment of a path: a selector and whether it follows a `..` descent. */
 export type Step = {
@@ -38,6 +48,12 @@ export type CompiledPath = {
     readonly steps: Step[];
     /** True when the path contains at least one `..` step. */
     readonly hasDescent: boolean;
+    /**
+     * A parse error, when the expression is malformed (an unterminated bracket, a
+     * missing `$` root, an unsupported script subscript, …). A compiled path with
+     * an error matches nothing; callers such as {@link createRuleset} surface it.
+     */
+    readonly error?: string;
 };
 /** Compiles a JSONPath `expression` into a {@link CompiledPath}, cached by string so repeats are free. */
 export declare const compileQuery: (expression: string) => CompiledPath;

package/dist/core/jsonpath.js

@@ -10,24 +10,89 @@ const normalizeSegment = (segment) => {
     return segment;
 };
 const normalizePath = (path) => path.map(normalizeSegment);
+/**
+ * Renders a concrete path as the jsonpath-plus string form (`$['a'][0]`). This
+ * is what `@path` exposes inside a filter, so ruleset filters authored for
+ * Spectral (which run on jsonpath-plus) see the same value.
+ */
+const pathToJsonPathString = (path) => {
+    let out = '$';
+    for (const segment of path) {
+        if (typeof segment === 'number')
+            out += `[${segment}]`;
+        else
+            out += `['${segment.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`;
+    }
+    return out;
+};
 // ---------------------------------------------------------------------------
 // Compilation
 // ---------------------------------------------------------------------------
 const compileCache = new Map();
 const filterCache = new Map();
+/**
+ * Rewrites jsonpath-plus' `@`-context tokens onto real identifiers, skipping any
+ * `@` that sits inside a quoted string literal (so an expression like
+ * `@.name.indexOf("@")` keeps the literal `@` intact). Longer tokens are matched
+ * first so `@parentProperty` is not eaten by `@parent`.
+ */
+const substituteContext = (source) => {
+    let out = '';
+    let quote = '';
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            out += ch;
+            if (ch === '\\' && i + 1 < source.length) {
+                out += source[i + 1];
+                i++;
+            }
+            else if (ch === quote) {
+                quote = '';
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === '@') {
+            const rest = source.slice(i);
+            if (rest.startsWith('@parentProperty')) {
+                out += '_pp';
+                i += '@parentProperty'.length - 1;
+            }
+            else if (rest.startsWith('@parent')) {
+                out += '_parent';
+                i += '@parent'.length - 1;
+            }
+            else if (rest.startsWith('@property')) {
+                out += '_prop';
+                i += '@property'.length - 1;
+            }
+            else if (rest.startsWith('@path')) {
+                out += '_path';
+                i += '@path'.length - 1;
+            }
+            else if (rest.startsWith('@root')) {
+                out += '_root';
+                i += '@root'.length - 1;
+            }
+            else {
+                out += '_v';
+            }
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+};
 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');
+    const body = substituteContext(source);
     let fn;
     try {
         // `_pp` (`@parentProperty`) is supplied directly by the caller rather than
@@ -42,7 +107,7 @@ const compileFilter = (source) => {
     filterCache.set(source, fn);
     return fn;
 };
-/** Splits bracket content on top-level commas, respecting quotes. */
+/** Splits bracket content on top-level commas, respecting quotes (and their escapes). */
 const splitUnion = (content) => {
     const parts = [];
     let depth = 0;
@@ -51,6 +116,11 @@ const splitUnion = (content) => {
     for (let i = 0; i < content.length; i++) {
         const ch = content[i];
         if (quote) {
+            if (ch === '\\' && i + 1 < content.length) {
+                current += ch + content[i + 1];
+                i++;
+                continue;
+            }
             if (ch === quote)
                 quote = '';
             current += ch;
@@ -75,14 +145,54 @@ const splitUnion = (content) => {
     parts.push(current);
     return parts;
 };
+/** Unquotes a `'...'` / `"..."` token, honoring backslash escapes; returns null when not a quoted literal. */
 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);
+    const quote = t[0];
+    if (t.length < 2 || (quote !== '"' && quote !== "'"))
+        return null;
+    let out = '';
+    let i = 1;
+    let closed = false;
+    while (i < t.length) {
+        const ch = t[i];
+        if (ch === '\\' && i + 1 < t.length) {
+            out += t[i + 1];
+            i += 2;
+            continue;
+        }
+        if (ch === quote) {
+            closed = true;
+            i++;
+            break;
+        }
+        out += ch;
+        i++;
     }
-    return null;
+    // A valid literal closes exactly at the end of the token.
+    if (!closed || i !== t.length)
+        return null;
+    return out;
 };
-const bracketSelector = (content) => {
+// A slice is `start:end` or `start:end:step`, each part optional and possibly
+// negative, e.g. `0:2`, `-1:`, `::2`, `:`.
+const SLICE_RE = /^-?\d*:-?\d*(:-?\d+)?$/;
+const buildSlice = (trimmed) => {
+    const [s, e, st] = trimmed.split(':');
+    const num = (value) => value === undefined || value === '' ? undefined : Number(value);
+    const selector = { kind: 'slice' };
+    const start = num(s);
+    const end = num(e);
+    const step = num(st);
+    if (start !== undefined)
+        selector.start = start;
+    if (end !== undefined)
+        selector.end = end;
+    if (step !== undefined)
+        selector.step = step;
+    return selector;
+};
+const bracketSelector = (content, onError) => {
     const trimmed = content.trim();
     if (trimmed === '*')
         return { kind: 'wildcard' };
@@ -93,6 +203,23 @@ const bracketSelector = (content) => {
         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') };
     }
+    if (trimmed.startsWith('(') && trimmed.endsWith(')')) {
+        // Script subscript `[(expr)]`. We support the common `(@.length - N)` form
+        // (a from-the-end index); anything else is rejected loudly so a typo does not
+        // silently match nothing.
+        const inner = trimmed.slice(1, -1).trim();
+        const lengthOnly = /^@\.length$/.test(inner);
+        const withOffset = /^@\.length\s*-\s*(\d+)$/.exec(inner);
+        if (lengthOnly)
+            return { kind: 'scriptIndex', offset: 0 };
+        if (withOffset)
+            return { kind: 'scriptIndex', offset: -Number(withOffset[1]) };
+        onError(`Unsupported script subscript "[${content}]"`);
+        return { kind: 'none' };
+    }
+    // A slice is only a slice when it is a single (comma-free) `:`-delimited token.
+    if (!content.includes(',') && SLICE_RE.test(trimmed))
+        return buildSlice(trimmed);
     const parts = splitUnion(content);
     const names = [];
     for (const part of parts) {
@@ -114,13 +241,18 @@ const bracketSelector = (content) => {
     }
     return { kind: 'union', names };
 };
-/** Finds the index of the `]` that closes the `[` at `start`, respecting quotes/nesting. */
+/** Finds the index of the `]` that closes the `[` at `start`, respecting quotes (and escapes) and 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 === '\\') {
+                // Skip the escaped character so an escaped quote does not end the string.
+                i++;
+                continue;
+            }
             if (ch === quote)
                 quote = '';
             continue;
@@ -151,10 +283,18 @@ export const compileQuery = (expression) => {
     if (cached)
         return cached;
     const steps = [];
+    const errors = [];
+    const onError = (message) => {
+        errors.push(message);
+    };
     let hasDescent = false;
     let i = 0;
+    // Every well-formed JSONPath is rooted at `$`. Without it the expression would
+    // otherwise compile to zero steps and match the document root — a silent bug.
     if (expression[0] === '$')
         i = 1;
+    else
+        onError('JSONPath must start with "$"');
     let recursive = false;
     while (i < expression.length) {
         const ch = expression[i];
@@ -181,21 +321,27 @@ export const compileQuery = (expression) => {
         }
         if (ch === '[') {
             const end = findBracketEnd(expression, i);
-            if (end === -1)
+            if (end === -1) {
+                onError(`Unterminated "[" in "${expression}"`);
                 break;
+            }
             const content = expression.slice(i + 1, end);
-            steps.push({ recursive, selector: bracketSelector(content) });
+            steps.push({ recursive, selector: bracketSelector(content, onError) });
             recursive = false;
             i = end + 1;
             continue;
         }
         if (ch === '^') {
-            steps.push({ recursive: false, selector: { kind: 'parent' } });
+            // Honor a pending `..` so `$..^` selects every node's parent (fixing a
+            // flag leak where the descent was dropped and the selector matched nothing).
+            steps.push({ recursive, selector: { kind: 'parent' } });
+            recursive = false;
             i++;
             continue;
         }
         if (ch === '~') {
-            steps.push({ recursive: false, selector: { kind: 'keys' } });
+            steps.push({ recursive, selector: { kind: 'keys' } });
+            recursive = false;
             i++;
             continue;
         }
@@ -217,11 +363,15 @@ export const compileQuery = (expression) => {
         }
         i++;
     }
-    const compiled = { expression, steps, hasDescent };
+    const compiled = {
+        expression,
+        steps,
+        hasDescent,
+        ...(errors.length > 0 ? { error: errors.join('; ') } : {}),
+    };
     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;
@@ -286,13 +436,48 @@ const applySelector = (node, selector, root, out) => {
             }
             return;
         }
+        case 'slice': {
+            if (!Array.isArray(value))
+                return;
+            const len = value.length;
+            const step = selector.step ?? 1;
+            if (step === 0)
+                return;
+            const clamp = (raw, fallback) => {
+                if (raw === undefined)
+                    return fallback;
+                return raw < 0 ? raw + len : raw;
+            };
+            if (step > 0) {
+                const start = Math.max(0, clamp(selector.start, 0));
+                const end = Math.min(len, clamp(selector.end, len));
+                for (let idx = start; idx < end; idx += step)
+                    out.push({ value: value[idx], parent: node, key: idx });
+            }
+            else {
+                const start = Math.min(len - 1, clamp(selector.start, len - 1));
+                const end = Math.max(-1, clamp(selector.end, -1));
+                for (let idx = start; idx > end; idx += step)
+                    out.push({ value: value[idx], parent: node, key: idx });
+            }
+            return;
+        }
+        case 'scriptIndex': {
+            // `[(@.length - N)]` indexes from the end; N === 0 (`@.length`) is out of range.
+            if (!Array.isArray(value))
+                return;
+            const idx = value.length + selector.offset;
+            if (idx >= 0 && idx < value.length)
+                out.push({ value: value[idx], parent: node, key: idx });
+            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;
+                    const path = selector.usesPath ? pathToJsonPathString(pathOf(child)) : '';
                     if (selector.test(value[idx], idx, value, root, path, pp))
                         out.push(child);
                 }
@@ -300,7 +485,7 @@ const applySelector = (node, selector, root, out) => {
             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;
+                    const path = selector.usesPath ? pathToJsonPathString(pathOf(child)) : '';
                     if (selector.test(value[key], key, value, root, path, pp))
                         out.push(child);
                 }
@@ -319,6 +504,8 @@ const applySelector = (node, selector, root, out) => {
             out.push({ value: node.key, parent: node.parent, key: node.key });
             return;
         }
+        case 'none':
+            return;
     }
 };
 /** Visits `node` and every descendant (preorder), invoking `visit` on each. */
@@ -362,6 +549,9 @@ const toMatches = (nodes) => {
 };
 /** Evaluates a pre-compiled path against `data`. */
 export const queryCompiled = (data, compiled) => {
+    // A malformed path matches nothing rather than falling back to the root.
+    if (compiled.error !== undefined)
+        return [];
     if (data === null || data === undefined)
         return [];
     return toMatches(runSteps(data, compiled.steps));
@@ -386,6 +576,11 @@ export const queryMany = (data, compiled) => {
     const recursive = [];
     for (let i = 0; i < compiled.length; i++) {
         const c = compiled[i];
+        // Skip malformed paths entirely; they contribute no matches.
+        if (c.error !== undefined) {
+            out[i] = [];
+            continue;
+        }
         const first = c.steps[0];
         if (first?.recursive)
             recursive.push(i);

package/dist/core/lint.d.ts

@@ -2,21 +2,28 @@ import { type Document, type IDocumentOptions } from './document.js';
 import type { LintPlugin } from './plugin.js';
 import type { Ruleset } from './ruleset.js';
 import { type IDiagnostic, type ISourceSet } from './types.js';
+/**
+ * What a {@link LintResolver} returns: the dereferenced tree, an optional source
+ * set mapping inlined nodes back to their origin, and any diagnostics raised
+ * while resolving (e.g. a `$ref` that could not be dereferenced). Surfacing
+ * resolution failures as diagnostics keeps a typo'd ref or a failed fetch
+ * visible instead of silently dropping it.
+ */
+export type LintResolverResult = {
+    resolved: unknown;
+    sources?: ISourceSet;
+    diagnostics?: IDiagnostic[];
+};
 /**
  * How a resolved (`$ref`-dereferenced) tree is produced from a parsed document.
  * The engine stays free of any `$ref` resolver: a caller may inject one (for
  * example wrapping `@amritk/resolve-refs`). Returning no `sources` means
- * findings map back to the root document only.
+ * findings map back to the root document only; `diagnostics` reports refs that
+ * failed to resolve.
  */
 export type LintResolver = (document: Document, context: {
     input: string;
-}) => {
-    resolved: unknown;
-    sources?: ISourceSet;
-} | Promise<{
-    resolved: unknown;
-    sources?: ISourceSet;
-}>;
+}) => LintResolverResult | Promise<LintResolverResult>;
 /** Options for {@link lint} / {@link lintWithResult}. */
 export type LintOptions = IDocumentOptions & {
     /** A normalized ruleset to evaluate (built via {@link createRuleset}). */

package/dist/core/lint.js

@@ -18,7 +18,13 @@ const toParserSeverity = (value) => {
     };
     return names[value];
 };
-const byPosition = (a, b) => a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character;
+const byPosition = (a, b) => {
+    const sa = a.source ?? '';
+    const sb = b.source ?? '';
+    if (sa !== sb)
+        return sa < sb ? -1 : 1;
+    return a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character;
+};
 /**
  * Lints `input` against a normalized `ruleset`, returning the full
  * {@link LintResult} (findings plus anything the configured `plugins` produced).
@@ -42,12 +48,15 @@ export const lintWithResult = async (input, options) => {
         return { diagnostics: [], pluginData: {} };
     let resolved = document.data;
     let sources;
+    let resolverDiagnostics = [];
     if (resolve) {
         const result = await resolve(document, { input });
         resolved = result.resolved;
         sources = result.sources;
+        if (result.diagnostics)
+            resolverDiagnostics = result.diagnostics;
     }
-    const ruleResults = createLinter(ruleset).run(document, { resolved, ...(sources ? { sources } : {}) });
+    const ruleResults = await createLinter(ruleset).run(document, { resolved, ...(sources ? { sources } : {}) });
     const parserResults = document.diagnostics.map((diagnostic) => {
         const result = {
             code: 'parser',
@@ -60,7 +69,7 @@ export const lintWithResult = async (input, options) => {
             result.source = document.source;
         return result;
     });
-    const diagnostics = [...parserResults, ...ruleResults].sort(byPosition);
+    const diagnostics = [...parserResults, ...resolverDiagnostics, ...ruleResults].sort(byPosition);
     if (!plugins || plugins.length === 0)
         return { diagnostics, pluginData: {} };
     const format = documentOptions.format ?? detectFormat(input);