@amritk/lint 0.2.0 → 0.3.0

package/dist/core/plugin.d.ts

@@ -55,5 +55,11 @@ export type PluginRunResult = {
  * Runs `plugins` in order over `diagnostics`. Each plugin sees the (possibly
  * already transformed) diagnostics from the previous one; when a plugin returns
  * `output`, later plugins and the context see that rewritten text as `input`.
+ *
+ * Note: only `input` (and the diagnostics) are refreshed between plugins. The
+ * `document` and `resolved` tree in the context are the *originally* parsed ones,
+ * so after a plugin rewrites `output` those become stale relative to the new
+ * text. A plugin that must operate on the up-to-date parsed tree should re-parse
+ * `context.input` itself rather than trust `document`/`resolved`.
  */
 export declare const runPlugins: (plugins: readonly LintPlugin[], diagnostics: IDiagnostic[], context: LintPluginContext) => PluginRunResult;

package/dist/core/plugin.js

@@ -2,6 +2,12 @@
  * Runs `plugins` in order over `diagnostics`. Each plugin sees the (possibly
  * already transformed) diagnostics from the previous one; when a plugin returns
  * `output`, later plugins and the context see that rewritten text as `input`.
+ *
+ * Note: only `input` (and the diagnostics) are refreshed between plugins. The
+ * `document` and `resolved` tree in the context are the *originally* parsed ones,
+ * so after a plugin rewrites `output` those become stale relative to the new
+ * text. A plugin that must operate on the up-to-date parsed tree should re-parse
+ * `context.input` itself rather than trust `document`/`resolved`.
  */
 export const runPlugins = (plugins, diagnostics, context) => {
     let currentDiagnostics = diagnostics;

package/dist/core/pointers.js

@@ -1,7 +1,20 @@
 import { dirname, resolve as resolvePath } from 'node:path';
 const isContainer = (value) => typeof value === 'object' && value !== null;
+/**
+ * Decodes one JSON-pointer segment the way `getByPointer` does: percent-escapes
+ * first (pointers arrive inside URI-reference `$ref`s), then the JSON-pointer
+ * escapes `~1`/`~0`, then all-digit segments become numbers. Shared by both the
+ * `#/...` and fragment parsers so they decode identically.
+ */
 const decodeSegment = (segment) => {
-    const decoded = segment.replace(/~1/g, '/').replace(/~0/g, '~');
+    let decoded = segment;
+    try {
+        decoded = decodeURIComponent(segment);
+    }
+    catch {
+        // Leave invalid percent-escapes as-is rather than throwing.
+    }
+    decoded = decoded.replace(/~1/g, '/').replace(/~0/g, '~');
     return /^\d+$/.test(decoded) ? Number(decoded) : decoded;
 };
 /** Parses an internal JSON pointer (`#/a/b`) into a path; returns undefined for external refs. */
@@ -41,20 +54,7 @@ const splitRef = (ref) => {
 const fragmentToPath = (fragment) => {
     if (fragment === '' || fragment === '/')
         return [];
-    return fragment
-        .replace(/^\//, '')
-        .split('/')
-        .map((segment) => {
-        let decoded = segment;
-        try {
-            decoded = decodeURIComponent(segment);
-        }
-        catch {
-            // leave invalid percent-escapes as-is
-        }
-        decoded = decoded.replace(/~1/g, '/').replace(/~0/g, '~');
-        return /^\d+$/.test(decoded) ? Number(decoded) : decoded;
-    });
+    return fragment.replace(/^\//, '').split('/').map(decodeSegment);
 };
 const getAtPath = (root, path) => {
     let node = root;

package/dist/core/runner.d.ts

@@ -15,7 +15,12 @@ export type IRunOptions = {
 };
 /** Evaluates a normalized ruleset against a document. Produced by {@link createLinter}. */
 export type Linter = {
-    run(document: Document, options?: IRunOptions): IDiagnostic[];
+    /**
+     * Runs the ruleset over `document`. Async because a rule function may return a
+     * Promise (Spectral-style async functions); synchronous functions resolve
+     * immediately.
+     */
+    run(document: Document, options?: IRunOptions): Promise<IDiagnostic[]>;
 };
 /** Creates a {@link Linter} runner bound to a normalized `ruleset`. */
 export declare const createLinter: (ruleset: Ruleset) => Linter;

package/dist/core/runner.js

@@ -1,6 +1,6 @@
 import { detectFormats } from './formats.js';
 import { matchesGlob } from './glob.js';
-import { compileQuery, queryMany } from './jsonpath.js';
+import { compileQuery, query, queryMany } from './jsonpath.js';
 import { pointerToPath, resolveSourcePath } from './pointers.js';
 import { DiagnosticSeverity, } from './types.js';
 const SEVERITY_NAMES = {
@@ -10,20 +10,36 @@ const SEVERITY_NAMES = {
     hint: DiagnosticSeverity.Hint,
 };
 const ZERO_RANGE = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
-const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isIndexable = (value) => typeof value === 'object' && value !== null;
+const isThenable = (value) => typeof value?.then === 'function';
+/**
+ * Narrows a matched value to the nodes a `then` runs against, mirroring
+ * Spectral's `getLintTargets`. Both objects and arrays are indexable containers,
+ * so `@key` yields keys/indices and a numeric field indexes into an array; a
+ * field against a primitive lints the matched value itself; a `$`-prefixed field
+ * runs as a sub-query.
+ */
 const resolveTargets = (value, path, field) => {
     if (field === undefined)
         return [{ value, path }];
-    if (field === '$')
+    // A field only narrows into a container; against a primitive (or null) the
+    // matched value itself is the target.
+    if (!isIndexable(value))
         return [{ value, path }];
     if (field === '@key') {
-        if (!isObject(value))
-            return [];
-        return Object.keys(value).map((key) => ({ value: key, path: [...path, key] }));
+        // Object.keys over an array yields its indices (as strings); normalize those
+        // back to numbers for the path so lookups stay consistent.
+        return Object.keys(value).map((key) => ({
+            value: key,
+            path: [...path, Array.isArray(value) ? Number(key) : key],
+        }));
     }
-    if (isObject(value))
-        return [{ value: value[field], path: [...path, field] }];
-    return [];
+    if (field.startsWith('$')) {
+        return query(value, field).map((match) => ({ value: match.value, path: [...path, ...match.path] }));
+    }
+    // A plain property name, or a numeric index into an array.
+    const key = Array.isArray(value) && /^\d+$/.test(field) ? Number(field) : field;
+    return [{ value: value[key], path: [...path, key] }];
 };
 const stringify = (value) => {
     if (value === undefined)
@@ -36,18 +52,69 @@ const applyTemplate = (template, ctx) => template.replace(/\{\{([^}]+)\}\}/g, (_
     const key = raw.trim();
     return key in ctx ? stringify(ctx[key]) : '';
 });
+/** Resolves where a finding's `path` maps to in the source: its range and originating `source`. */
+const locate = (rule, path, document, sources) => {
+    // A resolved finding may sit on a node inlined from another file. With a source
+    // set, follow the `$ref` chain across documents so the range and `source` point
+    // at the originating file; otherwise fall back to the root document, following
+    // internal `$ref`s only.
+    let originDocument = document;
+    let sourcePath;
+    if (rule.resolved && sources) {
+        const origin = sources.origin(path);
+        originDocument = sources.get(origin.location) ?? document;
+        sourcePath = origin.path;
+    }
+    else {
+        sourcePath = rule.resolved ? resolveSourcePath(document.data, path) : path;
+    }
+    const location = originDocument.getLocationForJsonPath(sourcePath, true);
+    return { range: location?.range ?? ZERO_RANGE, source: originDocument.source };
+};
+/** Builds an error-severity diagnostic (a failed rule function or an unknown-function reference). */
+const errorDiagnostic = (rule, path, message, range, source) => {
+    const diagnostic = {
+        code: rule.name,
+        message,
+        path,
+        severity: DiagnosticSeverity.Error,
+        range,
+    };
+    if (source !== undefined)
+        diagnostic.source = source;
+    return diagnostic;
+};
+/** Returns the name of the first `then` function this rule references that is not registered. */
+const missingFunction = (ruleset, rule) => {
+    for (const then of rule.then) {
+        if (typeof then?.function === 'string' && !ruleset.getFunction(then.function))
+            return then.function;
+    }
+    return undefined;
+};
 /**
  * Builds a deduped query plan for `rules` against `data`: each distinct
  * (expanded) `given` is compiled and evaluated once, then its matches fan out to
  * every rule that shares it. Recursive descents are evaluated with a single
  * shared tree walk inside `queryMany`.
+ *
+ * A rule that references an unknown named function is reported once (not per
+ * node) and skipped; a rule function that throws (or rejects) becomes an
+ * error-severity diagnostic on that node so one bad rule cannot abort the run.
  */
-const runPlan = (ruleset, rules, data, document, formats, out, sources) => {
+const runPlan = async (ruleset, rules, data, document, formats, out, sources) => {
     if (rules.length === 0)
         return;
     const order = [];
     const groups = new Map();
     for (const rule of rules) {
+        // Surface an unknown-function reference once for the whole rule, then skip it
+        // rather than throwing mid-run at the first matched node.
+        const missing = missingFunction(ruleset, rule);
+        if (missing !== undefined) {
+            out.push(errorDiagnostic(rule, [], `Rule "${rule.name}" references unknown function "${missing}"`, ZERO_RANGE, document.source));
+            continue;
+        }
         for (const given of ruleset.expandGiven(rule.given, formats)) {
             let group = groups.get(given);
             if (!group) {
@@ -68,7 +135,7 @@ const runPlan = (ruleset, rules, data, document, formats, out, sources) => {
         for (const match of matches) {
             for (const rule of group.rules) {
                 for (const then of rule.then) {
-                    runThen(ruleset, rule, then, match.value, match.path, document, out, sources);
+                    await runThen(ruleset, rule, then, match.value, match.path, document, out, sources);
                 }
             }
         }
@@ -96,6 +163,10 @@ const applyScopedOverrides = (ruleset, source, diagnostics) => {
     if (scoped.length === 0)
         return diagnostics;
     const isPrefix = (prefix, path) => prefix.every((segment, index) => String(path[index]) === String(segment));
+    // Note: a pointer-scoped override can *disable* (`off`/`false`) or *remap the
+    // severity* of a finding under its path, but it cannot *enable* a rule — it
+    // filters/adjusts findings that were already produced, so a rule turned off
+    // elsewhere has no finding here to switch back on.
     const result = [];
     for (const diagnostic of diagnostics) {
         let dropped = false;
@@ -120,22 +191,38 @@ const applyScopedOverrides = (ruleset, source, diagnostics) => {
     }
     return result;
 };
-const runThen = (ruleset, rule, then, value, path, document, out, sources) => {
+const runThen = async (ruleset, rule, then, value, path, document, out, sources) => {
     // A malformed rule (e.g. a `then` with no `function`, which `validateRuleset`
     // warns about) is skipped rather than crashing the whole run.
     if (!then || (typeof then.function !== 'function' && typeof then.function !== 'string'))
         return;
     const fn = typeof then.function === 'function' ? then.function : ruleset.getFunction(then.function);
+    // Unknown named functions are handled once per rule in `runPlan`; nothing to do.
     if (!fn)
-        throw new Error(`Rule "${rule.name}" references unknown function "${String(then.function)}"`);
+        return;
     for (const target of resolveTargets(value, path, then.field)) {
-        const results = fn(target.value, then.functionOptions ?? {}, {
-            document,
-            path: target.path,
-            value: target.value,
-            rule,
-            functionOptions: then.functionOptions,
-        });
+        let results;
+        try {
+            // The declared signature is synchronous, but a function reference may in
+            // fact return a Promise (a Spectral-style async function), so treat the raw
+            // result as unknown and await it when it is thenable.
+            const raw = fn(target.value, then.functionOptions ?? {}, {
+                document,
+                path: target.path,
+                value: target.value,
+                rule,
+                functionOptions: then.functionOptions,
+            });
+            results = (isThenable(raw) ? await raw : raw);
+        }
+        catch (error) {
+            // Isolate the failure: convert it into an error diagnostic on this node so
+            // the rest of the run (and already-collected findings) survive.
+            const { range, source } = locate(rule, target.path, document, sources);
+            const reason = error instanceof Error ? error.message : String(error);
+            out.push(errorDiagnostic(rule, target.path, `Rule "${rule.name}" threw: ${reason}`, range, source));
+            continue;
+        }
         if (!results)
             continue;
         for (const result of results) {
@@ -155,30 +242,16 @@ const toDiagnostic = (rule, result, target, document, sources) => {
             description: rule.description ?? '',
         })
         : result.message;
-    // A resolved finding may sit on a node inlined from another file. With a source
-    // set, follow the `$ref` chain across documents so the range and `source` point
-    // at the originating file; otherwise fall back to the root document, following
-    // internal `$ref`s only.
-    let originDocument = document;
-    let sourcePath;
-    if (rule.resolved && sources) {
-        const origin = sources.origin(path);
-        originDocument = sources.get(origin.location) ?? document;
-        sourcePath = origin.path;
-    }
-    else {
-        sourcePath = rule.resolved ? resolveSourcePath(document.data, path) : path;
-    }
-    const location = originDocument.getLocationForJsonPath(sourcePath, true);
+    const { range, source } = locate(rule, path, document, sources);
     const diagnostic = {
         code: rule.name,
         message,
         path,
         severity: rule.severity,
-        range: location?.range ?? ZERO_RANGE,
+        range,
     };
-    if (originDocument.source !== undefined)
-        diagnostic.source = originDocument.source;
+    if (source !== undefined)
+        diagnostic.source = source;
     return diagnostic;
 };
 const hasIntersection = (a, b) => {
@@ -188,10 +261,21 @@ const hasIntersection = (a, b) => {
     }
     return false;
 };
-const byPosition = (a, b) => a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character;
+/**
+ * Orders findings by source, then line, then character. Sorting by position
+ * alone interleaves findings from different files once a run spans multiple
+ * sources; grouping by `source` first keeps each file's findings contiguous.
+ */
+const bySourceThenPosition = (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;
+};
 /** Creates a {@link Linter} runner bound to a normalized `ruleset`. */
 export const createLinter = (ruleset) => ({
-    run: (document, options = {}) => {
+    run: async (document, options = {}) => {
         const documentFormats = detectFormats(document.data, ruleset.formats);
         const diagnostics = [];
         // Rules split by which document they run against (resolved vs raw). Each
@@ -213,10 +297,10 @@ export const createLinter = (ruleset) => ({
         // Raw rules run against the root's unresolved tree, so positions always come
         // straight from the root document; only resolved rules can land on inlined
         // external nodes and need the source set.
-        runPlan(ruleset, rawRules, document.data, document, documentFormats, diagnostics, undefined);
+        await runPlan(ruleset, rawRules, document.data, document, documentFormats, diagnostics, undefined);
         if (resolvedRules.length > 0) {
-            runPlan(ruleset, resolvedRules, options.resolved, document, documentFormats, diagnostics, options.sources);
+            await runPlan(ruleset, resolvedRules, options.resolved, document, documentFormats, diagnostics, options.sources);
         }
-        return applyScopedOverrides(ruleset, document.source, diagnostics).sort(byPosition);
+        return applyScopedOverrides(ruleset, document.source, diagnostics).sort(bySourceThenPosition);
     },
 });

package/dist/core/types.d.ts

@@ -24,8 +24,18 @@ export type IFunctionContext = {
 /**
  * A rule function: given the matched `input`, its authored `options`, and the
  * run `context`, returns any findings (or `undefined`/`[]` for none).
+ *
+ * The declared return type is synchronous because the built-in functions are,
+ * but the runner also awaits a thenable result at run time, so a Spectral-style
+ * async function works when passed as a reference (see {@link AsyncRulesetFunction}).
  */
 export type RulesetFunction<I = unknown, O = unknown> = (input: I, options: O, context: IFunctionContext) => IFunctionResult[] | undefined;
+/**
+ * A rule function that resolves its findings asynchronously. The runner awaits a
+ * thenable result, so such a function may be passed by reference in a JS ruleset;
+ * cast it to {@link RulesetFunction} at the `then.function` site.
+ */
+export type AsyncRulesetFunction<I = unknown, O = unknown> = (input: I, options: O, context: IFunctionContext) => Promise<IFunctionResult[] | undefined>;
 /** Functions a ruleset can invoke by name in `then.function`, keyed by that name. */
 export type FunctionRegistry = Record<string, RulesetFunction>;
 /** One action a rule takes on each match: a function plus how to target/configure it. */
@@ -57,11 +67,16 @@ export type IRuleDefinition = {
 };
 /** Shorthand a rule may take in `rules`: a definition, a boolean, or a severity. */
 export type RuleEntry = IRuleDefinition | boolean | HumanReadableSeverity;
+/**
+ * A per-file override: `files` globs select the documents it applies to, and
+ * `rules` re-toggles or re-severities rules for them. Spectral's `extends` and
+ * `formats` on an override are intentionally omitted here — they were never
+ * applied by the engine, so carrying them in the type only advertised support
+ * that did not exist. Re-add them alongside a real implementation if needed.
+ */
 export type IRulesetOverride = {
     files: string[];
     rules?: Record<string, RuleEntry>;
-    extends?: RulesetExtends;
-    formats?: string[];
 };
 /**
  * The shape of a ruleset's `extends`: a single target or a list, where each

package/dist/core/validate-ruleset.js

@@ -1,3 +1,4 @@
+import { compileQuery } from './jsonpath.js';
 const SEVERITIES = new Set(['error', 'warn', 'info', 'hint', 'off']);
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const isValidSeverity = (value) => {
@@ -42,6 +43,21 @@ const validateRule = (name, entry, path, problems) => {
     else if (typeof entry['given'] !== 'string' && !Array.isArray(entry['given'])) {
         problems.push({ message: `Rule "${name}" \`given\` must be a string or array`, path: [...path, 'given'] });
     }
+    else {
+        // Flag a malformed JSONPath expression so it does not silently match nothing
+        // at run time. Alias references (`#Alias`) are only valid once expanded, so
+        // they are skipped here.
+        const givens = Array.isArray(entry['given']) ? entry['given'] : [entry['given']];
+        givens.forEach((given, index) => {
+            if (typeof given !== 'string' || given.startsWith('#'))
+                return;
+            const error = compileQuery(given).error;
+            if (error !== undefined) {
+                const at = Array.isArray(entry['given']) ? [...path, 'given', index] : [...path, 'given'];
+                problems.push({ message: `Rule "${name}" has an invalid \`given\` "${given}": ${error}`, path: at });
+            }
+        });
+    }
     if (entry['then'] === undefined) {
         problems.push({ message: `Rule "${name}" is missing \`then\``, path: [...path, 'then'] });
     }

package/dist/fix/apply.d.ts

@@ -15,7 +15,13 @@ export type ApplyFixesOptions = {
  * `data` is the *unresolved* parsed document: fixers read the real node at a
  * finding's path to derive the edit, and edits whose path no longer resolves are
  * dropped — so a finding on an inlined `$ref` node simply isn't fixed rather than
- * corrupting the source. A finding is only reported in `applied` when one of its
- * edits actually changed the text, so dropped edits are not mistaken for fixes.
+ * corrupting the source.
+ *
+ * When two ops in one batch would both reshape the same array, only the first is
+ * applied this pass; the second is *deferred* and its finding is left unreported,
+ * so the surrounding fixpoint loop re-derives it against the already-edited
+ * document (where the indices are fresh) on the next pass. A finding is reported
+ * in `applied` only when *every* edit it contributed actually changed the text —
+ * a partially-applied or deferred fix is retried rather than falsely counted.
  */
 export declare const applyFixes: (input: string, format: ParserFormat, data: unknown, diagnostics: IDiagnostic[], fixers: FixerRegistry, options?: ApplyFixesOptions) => FixResult;

package/dist/fix/apply.js

@@ -1,4 +1,24 @@
 import { applyEditOpsWithChanges } from '../parsers/index.js';
+/** The ops that structurally reshape an array, invalidating positional indices into it. */
+const STRUCTURAL_ARRAY_OPS = new Set(['removeItems', 'reorderArray', 'insertItem']);
+const isStructuralArrayOp = (op) => STRUCTURAL_ARRAY_OPS.has(op.op);
+/**
+ * Whether `path` addresses (or reaches into) an array that an earlier op in this
+ * batch already reshaped. After a `removeItems`/`reorderArray`/`insertItem`, the
+ * element indices of that array are stale, so a second op that either targets the
+ * same array or indexes into it by position would act on the wrong element. Such
+ * an op is deferred to the next fixpoint pass, which re-derives indices from the
+ * freshly-parsed document.
+ */
+const touchesModifiedArray = (path, modified) => modified.some((array) => {
+    if (array.length > path.length)
+        return false;
+    if (!array.every((segment, i) => segment === path[i]))
+        return false;
+    // Another structural op on the same array conflicts; a deeper op conflicts
+    // only when it indexes the array by position (the stale part).
+    return array.length === path.length || typeof path[array.length] === 'number';
+});
 /**
  * Computes the structural edits for every fixable finding in `diagnostics`, then
  * applies them to `input` in one pass. Edits from different findings that come
@@ -8,15 +28,19 @@ import { applyEditOpsWithChanges } from '../parsers/index.js';
  * `data` is the *unresolved* parsed document: fixers read the real node at a
  * finding's path to derive the edit, and edits whose path no longer resolves are
  * dropped — so a finding on an inlined `$ref` node simply isn't fixed rather than
- * corrupting the source. A finding is only reported in `applied` when one of its
- * edits actually changed the text, so dropped edits are not mistaken for fixes.
+ * corrupting the source.
+ *
+ * When two ops in one batch would both reshape the same array, only the first is
+ * applied this pass; the second is *deferred* and its finding is left unreported,
+ * so the surrounding fixpoint loop re-derives it against the already-edited
+ * document (where the indices are fresh) on the next pass. A finding is reported
+ * in `applied` only when *every* edit it contributed actually changed the text —
+ * a partially-applied or deferred fix is retried rather than falsely counted.
  */
 export const applyFixes = (input, format, data, diagnostics, fixers, options = {}) => {
     const safeOnly = options.safeOnly !== false;
-    const ops = [];
-    const indexByKey = new Map();
-    // Each candidate finding remembers the edits it contributed (by key) so we can
-    // tell afterwards whether any of them actually landed.
+    // Gather each candidate finding's ops up front so we can reason about conflicts
+    // across the whole batch before lowering anything to text.
     const candidates = [];
     for (const diagnostic of diagnostics) {
         const fixer = fixers[String(diagnostic.code)];
@@ -27,25 +51,51 @@ export const applyFixes = (input, format, data, diagnostics, fixers, options = {
         const produced = fixer.fix({ diagnostic, data, format });
         if (!produced)
             continue;
-        const keys = [];
-        for (const op of Array.isArray(produced) ? produced : [produced]) {
+        const ops = Array.isArray(produced) ? produced : [produced];
+        if (ops.length === 0)
+            continue;
+        candidates.push({ fix: { code: diagnostic.code, path: diagnostic.path }, ops });
+    }
+    const ops = [];
+    const indexByKey = new Map();
+    const modifiedArrays = [];
+    // Per candidate: the batch index of each op that made it into this pass, and
+    // whether any op had to be deferred (which keeps the finding unreported so it
+    // is retried once the earlier structural edit has landed).
+    const planned = [];
+    for (const candidate of candidates) {
+        const indices = [];
+        let deferred = false;
+        for (const op of candidate.ops) {
             const key = JSON.stringify(op);
             // De-duplicate identical edits (e.g. several findings on one array all asking
-            // for the same reorder) so the edit is applied — and counted — once.
-            if (!indexByKey.has(key)) {
-                indexByKey.set(key, ops.length);
-                ops.push(op);
+            // for the same reorder): the same edit is applied — and counted — once, and
+            // is never a conflict with itself.
+            const existing = indexByKey.get(key);
+            if (existing !== undefined) {
+                indices.push(existing);
+                continue;
+            }
+            // A distinct op that would reshape or index into an already-reshaped array
+            // is deferred to the next pass, where indices are re-derived from fresh data.
+            if (touchesModifiedArray(op.path, modifiedArrays)) {
+                deferred = true;
+                continue;
             }
-            keys.push(key);
+            const index = ops.length;
+            indexByKey.set(key, index);
+            ops.push(op);
+            if (isStructuralArrayOp(op))
+                modifiedArrays.push(op.path);
+            indices.push(index);
         }
-        if (keys.length > 0)
-            candidates.push({ fix: { code: diagnostic.code, path: diagnostic.path }, keys });
+        planned.push({ fix: candidate.fix, indices, deferred });
     }
     if (ops.length === 0)
         return { output: input, applied: [], changed: false };
     const { output, changed } = applyEditOpsWithChanges(input, format, ops);
-    const applied = candidates
-        .filter((candidate) => candidate.keys.some((key) => changed[indexByKey.get(key)]))
-        .map((candidate) => candidate.fix);
+    const applied = planned
+        .filter((plan) => !plan.deferred && plan.indices.length > 0 && plan.indices.every((index) => changed[index]))
+        .map((plan) => plan.fix);
     return { output, applied, changed: output !== input };
 };

package/dist/functions/alphabetical.js

@@ -1,28 +1,55 @@
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const isStringOrNumber = (value) => typeof value === 'string' || typeof value === 'number';
+/** A string made up only of digits, e.g. an integer-like object key such as "10". */
+const isIntegerLike = (value) => typeof value === 'string' && /^(?:0|[1-9]\d*)$/.test(value);
 const compare = (a, b) => {
-    if (typeof a === 'number' && typeof b === 'number')
-        return a - b;
-    return String(a).localeCompare(String(b));
+    // Deliberate deviation from Spectral, which relies on source order and falls
+    // back to `localeCompare`: JavaScript enumerates integer-like object keys in
+    // ascending numeric order ({ "2": …, "10": … }), yet `localeCompare` sorts
+    // "10" before "2" and would flag that natural key order as a violation.
+    // Comparing integer-like strings numerically avoids that false positive.
+    if (isIntegerLike(a) && isIntegerLike(b))
+        return Math.sign(Number(a) - Number(b));
+    // Match Spectral: when either side is a real number or a numeric string,
+    // compare numerically so mixed inputs like [2, "10"] read as ordered.
+    if ((typeof a === 'number' || Number.isNaN(Number(a))) && (typeof b === 'number' || !Number.isNaN(Number(b)))) {
+        return Math.min(1, Math.max(-1, Number(a) - Number(b)));
+    }
+    if (typeof a !== 'string' || typeof b !== 'string')
+        return 0;
+    return a.localeCompare(b);
 };
 /** Flags array items or object keys that are not in ascending (optionally `keyedBy`) order. */
 export const alphabetical = (input, options, context) => {
     if (typeof input !== 'object' || input === null)
         return [];
     const isArray = Array.isArray(input);
-    const items = isArray ? input : Object.keys(input);
+    const rawItems = isArray ? input : Object.keys(input);
     const keyedBy = options?.keyedBy;
-    const results = [];
-    for (let i = 0; i < items.length - 1; i++) {
-        let current = items[i];
-        let next = items[i + 1];
+    // Resolve the actual comparands. With `keyedBy` we read a property off each
+    // item, which is only meaningful when every item is an object; otherwise the
+    // comparison would silently run against `undefined`. Surface the same explicit
+    // findings Spectral does instead of producing a misleading order violation.
+    const items = [];
+    for (const item of rawItems) {
         if (keyedBy) {
-            current = isRecord(current) ? current[keyedBy] : current;
-            next = isRecord(next) ? next[keyedBy] : next;
+            if (!isRecord(item))
+                return [{ message: 'The value must be an object' }];
+            items.push(item[keyedBy]);
+        }
+        else {
+            items.push(item);
         }
-        if (compare(current, next) > 0) {
-            const path = isArray ? [...context.path, i + 1] : [...context.path, items[i + 1]];
+    }
+    if (!items.every(isStringOrNumber)) {
+        return [{ message: 'The value must be one of the allowed types: number, string' }];
+    }
+    const results = [];
+    for (let i = 0; i < items.length - 1; i++) {
+        if (compare(items[i], items[i + 1]) > 0) {
+            const path = isArray ? [...context.path, i + 1] : [...context.path, rawItems[i + 1]];
             results.push({ message: 'The items must be in alphabetical order', path });
         }
     }
     return results;
 };
-const isRecord = (value) => typeof value === 'object' && value !== null;