@amritk/lint 0.0.0 → 0.2.0

package/dist/core/lint.d.ts

@@ -0,0 +1,57 @@
+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';
+/**
+ * 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.
+ */
+export type LintResolver = (document: Document, context: {
+    input: string;
+}) => {
+    resolved: unknown;
+    sources?: ISourceSet;
+} | Promise<{
+    resolved: unknown;
+    sources?: ISourceSet;
+}>;
+/** Options for {@link lint} / {@link lintWithResult}. */
+export type LintOptions = IDocumentOptions & {
+    /** A normalized ruleset to evaluate (built via {@link createRuleset}). */
+    ruleset: Ruleset;
+    /**
+     * Produces the resolved tree for rules with `resolved: true`. When omitted the
+     * raw parsed data is used as-is (no `$ref` dereferencing).
+     */
+    resolve?: LintResolver;
+    /**
+     * Checked against the parsed data before any resolution: when it returns true
+     * the document is skipped and produces no findings. Presets use this to skip
+     * documents of an unrecognized format without paying for `$ref` resolution.
+     */
+    skip?: (data: unknown) => boolean;
+    /** Plugins run after the rule pass via {@link runPlugins} (e.g. auto-fix). */
+    plugins?: LintPlugin[];
+};
+/** The full result of a {@link lintWithResult} run: findings plus plugin output. */
+export type LintResult = {
+    diagnostics: IDiagnostic[];
+    /** A rewritten document, when a plugin (e.g. auto-fix) produced one. */
+    output?: string;
+    /** Per-plugin structured output, keyed by plugin name. */
+    pluginData: Record<string, unknown>;
+};
+/**
+ * Lints `input` against a normalized `ruleset`, returning the full
+ * {@link LintResult} (findings plus anything the configured `plugins` produced).
+ * This is the format-agnostic pipeline — parse with source maps → resolve (via
+ * the injected {@link LintResolver}) → run the ruleset → run plugins. A higher
+ * 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.
+ */
+export declare const lintWithResult: (input: string, 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[]>;

package/dist/core/lint.js

@@ -0,0 +1,82 @@
+import { detectFormat } from '../parsers/index.js';
+import { createDocument } from './document.js';
+import { runPlugins } from './plugin.js';
+import { createLinter } from './runner.js';
+import { DiagnosticSeverity } from './types.js';
+const toParserSeverity = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return value;
+    if (value === 'off')
+        return 'off';
+    const names = {
+        error: DiagnosticSeverity.Error,
+        warn: DiagnosticSeverity.Warning,
+        info: DiagnosticSeverity.Information,
+        hint: DiagnosticSeverity.Hint,
+    };
+    return names[value];
+};
+const byPosition = (a, b) => 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).
+ * This is the format-agnostic pipeline — parse with source maps → resolve (via
+ * the injected {@link LintResolver}) → run the ruleset → run plugins. A higher
+ * 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.
+ */
+export 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 !== undefined ? { duplicateKeys } : {}),
+        ...(incompatibleValues !== undefined ? { incompatibleValues } : {}),
+    });
+    // Skip unrecognized-format documents before paying for resolution or the run.
+    if (skip?.(document.data))
+        return { diagnostics: [], pluginData: {} };
+    let resolved = document.data;
+    let sources;
+    if (resolve) {
+        const result = await resolve(document, { input });
+        resolved = result.resolved;
+        sources = result.sources;
+    }
+    const ruleResults = createLinter(ruleset).run(document, { resolved, ...(sources ? { sources } : {}) });
+    const parserResults = document.diagnostics.map((diagnostic) => {
+        const result = {
+            code: 'parser',
+            message: diagnostic.message,
+            path: diagnostic.path ?? [],
+            severity: diagnostic.severity,
+            range: diagnostic.range,
+        };
+        if (document.source !== undefined)
+            result.source = document.source;
+        return result;
+    });
+    const diagnostics = [...parserResults, ...ruleResults].sort(byPosition);
+    if (!plugins || plugins.length === 0)
+        return { diagnostics, pluginData: {} };
+    const format = documentOptions.format ?? detectFormat(input);
+    const run = runPlugins(plugins, diagnostics, {
+        input,
+        format,
+        document,
+        resolved,
+        ruleset,
+        ...(documentOptions.source !== undefined ? { source: documentOptions.source } : {}),
+    });
+    return {
+        diagnostics: run.diagnostics,
+        pluginData: run.data,
+        ...(run.output !== undefined ? { output: run.output } : {}),
+    };
+};
+/** Lints `input` against a normalized `ruleset` and returns just the findings. */
+export const lint = async (input, options) => (await lintWithResult(input, options)).diagnostics;

package/dist/core/plugin.d.ts

@@ -0,0 +1,59 @@
+import type { ParserFormat } from '../parsers/index.js';
+import type { Document } from './document.js';
+import type { Ruleset } from './ruleset.js';
+import type { IDiagnostic } from './types.js';
+/**
+ * Everything a plugin needs about the document it is post-processing: the raw
+ * input text and its format (so a plugin can produce text edits), the parsed
+ * {@link Document} with its source map, the dereferenced tree, and the ruleset
+ * that produced the findings.
+ */
+export type LintPluginContext = {
+    source?: string | undefined;
+    /** The original, unparsed document text. */
+    input: string;
+    /** Which concrete parser the document was routed to (drives text-edit serialization). */
+    format: ParserFormat;
+    document: Document;
+    /** The dereferenced document data, as passed to the runner. */
+    resolved: unknown;
+    ruleset: Ruleset;
+};
+/**
+ * What a plugin's `afterLint` hook may return. Every field is optional: a plugin
+ * that only observes returns nothing. A plugin that rewrites the document (e.g.
+ * auto-fix) returns `output`; one that resolves or adds findings returns
+ * `diagnostics`; structured results go in `data` (keyed by plugin name).
+ */
+export type LintPluginResult = {
+    /** A rewritten version of the document text (e.g. with fixes applied). */
+    output?: string;
+    /** Diagnostics that replace the ones passed in (e.g. with fixed ones removed). */
+    diagnostics?: IDiagnostic[];
+    /** Arbitrary structured output, surfaced under the plugin's name. */
+    data?: unknown;
+};
+/**
+ * A Linter plugin. The lint pipeline invokes registered plugins after the rule
+ * run via {@link runPlugins}. The hook is intentionally small — a single
+ * post-lint pass — so the core engine stays unaware of any specific plugin (the
+ * auto-fix subsystem, for instance, is just a plugin that returns `output`).
+ */
+export type LintPlugin = {
+    name: string;
+    afterLint?: (diagnostics: IDiagnostic[], context: LintPluginContext) => LintPluginResult | undefined;
+};
+/** The combined result of running every plugin over a document's findings. */
+export type PluginRunResult = {
+    diagnostics: IDiagnostic[];
+    /** The last `output` any plugin produced, if any rewrote the document. */
+    output?: string;
+    /** Per-plugin structured `data`, keyed by plugin name. */
+    data: Record<string, unknown>;
+};
+/**
+ * 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`.
+ */
+export declare const runPlugins: (plugins: readonly LintPlugin[], diagnostics: IDiagnostic[], context: LintPluginContext) => PluginRunResult;

package/dist/core/plugin.js

@@ -0,0 +1,25 @@
+/**
+ * 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`.
+ */
+export const runPlugins = (plugins, diagnostics, context) => {
+    let currentDiagnostics = diagnostics;
+    let currentInput = context.input;
+    let output;
+    const data = {};
+    for (const plugin of plugins) {
+        const result = plugin.afterLint?.(currentDiagnostics, { ...context, input: currentInput });
+        if (!result)
+            continue;
+        if (result.diagnostics)
+            currentDiagnostics = result.diagnostics;
+        if (result.output !== undefined) {
+            output = result.output;
+            currentInput = result.output;
+        }
+        if (result.data !== undefined)
+            data[plugin.name] = result.data;
+    }
+    return { diagnostics: currentDiagnostics, data, ...(output !== undefined ? { output } : {}) };
+};

package/dist/core/pointers.d.ts

@@ -0,0 +1,35 @@
+import type { IDocumentRegistry, IOriginMap, ISourceOrigin, JsonPath } from './types.js';
+/** Parses an internal JSON pointer (`#/a/b`) into a path; returns undefined for external refs. */
+export declare const pointerToPath: (pointer: string) => JsonPath | undefined;
+/**
+ * Translates a path into the *resolved* (dereferenced) document back into the
+ * equivalent path in the *original* source document, following internal `$ref`s.
+ * This lets findings produced against the resolved tree resolve to the exact
+ * line:column of the original `$ref` target. External refs stop the walk at the
+ * `$ref` site.
+ */
+export declare const resolveSourcePath: (root: unknown, path: JsonPath) => JsonPath;
+/**
+ * Cross-document generalization of {@link resolveSourcePath}: translates a path
+ * in the *resolved* (dereferenced) tree back to the document it actually came
+ * from and the path within it, following both internal (`#/...`) and external
+ * (other-file / remote) `$ref`s through the {@link IDocumentRegistry}. This is
+ * what lets a finding on a node inlined from `./pet.yaml` report `pet.yaml`'s own
+ * line:column instead of the `$ref` site in the root.
+ *
+ * The walk re-derives the resolver's traversal over the *unresolved* documents,
+ * so a `$ref` whose target file is not in the registry (e.g. it failed to load)
+ * stops the walk at the last known location rather than guessing. Prefer
+ * {@link resolveSourceOriginFromMap} when the resolver supplies an origin map —
+ * it avoids re-deriving this traversal.
+ */
+export declare const resolveSourceOrigin: (registry: IDocumentRegistry, path: JsonPath) => ISourceOrigin;
+/**
+ * Single-walk equivalent of {@link resolveSourceOrigin} that uses the resolver's
+ * per-node origin map instead of re-walking the unresolved documents. We descend
+ * the *resolved* tree along `path`; whenever we step onto a node the resolver
+ * stamped (it was inlined from a `$ref`), we re-base onto that node's origin
+ * document and in-file path, then keep appending the remaining segments. Nodes
+ * straight from the root carry no stamp, so they stay attributed to the root.
+ */
+export declare const resolveSourceOriginFromMap: (resolved: unknown, origins: IOriginMap, rootLocation: string, path: JsonPath) => ISourceOrigin;

package/dist/core/pointers.js

@@ -0,0 +1,169 @@
+import { dirname, resolve as resolvePath } from 'node:path';
+const isContainer = (value) => typeof value === 'object' && value !== null;
+const decodeSegment = (segment) => {
+    const decoded = segment.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. */
+export const pointerToPath = (pointer) => {
+    if (pointer === '#')
+        return [];
+    if (!pointer.startsWith('#/'))
+        return undefined;
+    return pointer.slice(2).split('/').map(decodeSegment);
+};
+const isRemote = (location) => /^https?:\/\//i.test(location);
+/**
+ * Resolves the location of `ref` (its file/URL part) relative to `base`, exactly
+ * as `@amritk/resolve-refs` does, so the keys we look up in the source set match
+ * the documents the resolver loaded.
+ */
+const joinLocation = (base, ref) => {
+    if (isRemote(ref))
+        return ref;
+    if (isRemote(base))
+        return new URL(ref, base).href;
+    return resolvePath(dirname(base), ref);
+};
+/** Splits a `$ref` into its document part and JSON-pointer fragment (without `#`). */
+const splitRef = (ref) => {
+    const hashIndex = ref.indexOf('#');
+    return {
+        filePart: hashIndex === -1 ? ref : ref.slice(0, hashIndex),
+        fragment: hashIndex === -1 ? '' : ref.slice(hashIndex + 1),
+    };
+};
+/**
+ * Parses a JSON-pointer fragment (the part after `#`, e.g. `/a/b`) into a path,
+ * mirroring `getByPointer`'s decoding (`%XX` then `~1`/`~0`) so cross-file
+ * pointers resolve to the same nodes the resolver inlined.
+ */
+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;
+    });
+};
+const getAtPath = (root, path) => {
+    let node = root;
+    for (const segment of path) {
+        if (!isContainer(node))
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+};
+/**
+ * Translates a path into the *resolved* (dereferenced) document back into the
+ * equivalent path in the *original* source document, following internal `$ref`s.
+ * This lets findings produced against the resolved tree resolve to the exact
+ * line:column of the original `$ref` target. External refs stop the walk at the
+ * `$ref` site.
+ */
+export const resolveSourcePath = (root, path) => {
+    let originalPath = [];
+    let node = root;
+    const followRefs = () => {
+        let guard = 0;
+        while (isContainer(node) && !Array.isArray(node) && typeof node['$ref'] === 'string' && guard++ < 100) {
+            const target = pointerToPath(node['$ref']);
+            if (!target)
+                return;
+            originalPath = [...target];
+            node = getAtPath(root, target);
+        }
+    };
+    followRefs();
+    for (const segment of path) {
+        if (!isContainer(node))
+            break;
+        originalPath.push(segment);
+        node = node[segment];
+        followRefs();
+    }
+    return originalPath;
+};
+/**
+ * Cross-document generalization of {@link resolveSourcePath}: translates a path
+ * in the *resolved* (dereferenced) tree back to the document it actually came
+ * from and the path within it, following both internal (`#/...`) and external
+ * (other-file / remote) `$ref`s through the {@link IDocumentRegistry}. This is
+ * what lets a finding on a node inlined from `./pet.yaml` report `pet.yaml`'s own
+ * line:column instead of the `$ref` site in the root.
+ *
+ * The walk re-derives the resolver's traversal over the *unresolved* documents,
+ * so a `$ref` whose target file is not in the registry (e.g. it failed to load)
+ * stops the walk at the last known location rather than guessing. Prefer
+ * {@link resolveSourceOriginFromMap} when the resolver supplies an origin map —
+ * it avoids re-deriving this traversal.
+ */
+export const resolveSourceOrigin = (registry, path) => {
+    let location = registry.rootLocation;
+    let root = registry.get(location)?.data;
+    let originalPath = [];
+    let node = root;
+    const followRefs = () => {
+        let guard = 0;
+        while (isContainer(node) && !Array.isArray(node) && typeof node['$ref'] === 'string' && guard++ < 1000) {
+            const { filePart, fragment } = splitRef(node['$ref']);
+            if (filePart !== '') {
+                const target = joinLocation(location, filePart);
+                const doc = registry.get(target);
+                if (!doc)
+                    return;
+                location = target;
+                root = doc.data;
+            }
+            originalPath = fragmentToPath(fragment);
+            node = getAtPath(root, originalPath);
+        }
+    };
+    followRefs();
+    for (const segment of path) {
+        if (!isContainer(node))
+            break;
+        originalPath.push(segment);
+        node = node[segment];
+        followRefs();
+    }
+    return { location, path: originalPath };
+};
+/**
+ * Single-walk equivalent of {@link resolveSourceOrigin} that uses the resolver's
+ * per-node origin map instead of re-walking the unresolved documents. We descend
+ * the *resolved* tree along `path`; whenever we step onto a node the resolver
+ * stamped (it was inlined from a `$ref`), we re-base onto that node's origin
+ * document and in-file path, then keep appending the remaining segments. Nodes
+ * straight from the root carry no stamp, so they stay attributed to the root.
+ */
+export const resolveSourceOriginFromMap = (resolved, origins, rootLocation, path) => {
+    let location = rootLocation;
+    let inFilePath = [];
+    let node = resolved;
+    for (const segment of path) {
+        if (!isContainer(node))
+            break;
+        node = node[segment];
+        const stamp = isContainer(node) ? origins.get(node) : undefined;
+        if (stamp) {
+            location = stamp.location;
+            inFilePath = [...stamp.pointer];
+        }
+        else {
+            inFilePath.push(segment);
+        }
+    }
+    return { location, path: inFilePath };
+};

package/dist/core/ruleset.d.ts

@@ -0,0 +1,52 @@
+import type { Format } from './formats.js';
+import type { FunctionRegistry, IRulesetOverride, ResolvedRule, RulesetDefinition, RulesetFunction } from './types.js';
+/** Controls which rules an `extends` target contributes: everything, only recommended, or none. */
+export type ExtendModifier = 'all' | 'recommended' | 'off';
+/** A ruleset resolved from an `extends` reference, plus the base directory its own extends resolve from. */
+export type ResolvedExtend = {
+    definition: RulesetDefinition;
+    basePath: string;
+};
+/**
+ * Resolves a string `extends` target (a built-in name, file path, or npm package)
+ * to a ruleset definition. `basePath` is the directory the reference is relative to.
+ */
+export type ExtendResolver = (name: string, basePath: string) => ResolvedExtend;
+/** An alias target: either a flat list of `given`s, or per-format `given`s with an optional description. */
+export type AliasDefinition = string[] | {
+    description?: string;
+    targets: {
+        formats: string[];
+        given: string[];
+    }[];
+};
+/** Inputs {@link createRuleset} needs beyond the definition: functions, formats, and how to resolve `extends`. */
+export type RulesetOptions = {
+    functions?: FunctionRegistry;
+    formats?: Record<string, Format>;
+    resolve?: ExtendResolver;
+    /** Directory that string `extends` references resolve relative to. Defaults to the cwd. */
+    basePath?: string;
+};
+/**
+ * A normalized ruleset: every `extends`, severity override, and modifier already
+ * applied, exposing the helpers the runner needs to evaluate it against a
+ * document. Produced by {@link createRuleset}.
+ */
+export type Ruleset = {
+    readonly rules: ResolvedRule[];
+    readonly functions: FunctionRegistry;
+    readonly formats: Record<string, Format>;
+    readonly aliases: Record<string, AliasDefinition>;
+    readonly overrides: IRulesetOverride[];
+    readonly parserOptions: RulesetDefinition['parserOptions'];
+    /** The subset of `rules` that are enabled. */
+    readonly enabledRules: ResolvedRule[];
+    getFunction(name: string): RulesetFunction | undefined;
+    /** Returns the effective rules for a document, applying matching overrides by file glob. */
+    rulesForSource(source: string | undefined): ResolvedRule[];
+    /** Resolves `#alias` references in `given` expressions for the document's formats. */
+    expandGiven(given: string[], formats: Set<string>): string[];
+};
+/** Normalizes a ruleset definition into a {@link Ruleset} ready to run. */
+export declare const createRuleset: (definition: RulesetDefinition, options?: RulesetOptions) => Ruleset;

package/dist/core/ruleset.js

@@ -0,0 +1,170 @@
+import { DiagnosticSeverity } from '../parsers/index.js';
+import { matchesGlob } from './glob.js';
+const SEVERITY_NAMES = {
+    error: DiagnosticSeverity.Error,
+    warn: DiagnosticSeverity.Warning,
+    info: DiagnosticSeverity.Information,
+    hint: DiagnosticSeverity.Hint,
+    off: 'off',
+};
+const parseSeverity = (value) => {
+    if (value === undefined)
+        return { severity: DiagnosticSeverity.Warning, enabled: true };
+    if (typeof value === 'number')
+        return { severity: value, enabled: true };
+    const mapped = SEVERITY_NAMES[value];
+    if (mapped === 'off')
+        return { severity: DiagnosticSeverity.Warning, enabled: false };
+    return { severity: mapped, enabled: true };
+};
+const toArray = (value) => (Array.isArray(value) ? value : [value]);
+const normalizeRule = (name, def, modifier) => {
+    const { severity, enabled } = parseSeverity(def.severity);
+    const recommended = def.recommended ?? true;
+    // Under the 'recommended' modifier only recommended rules are on; 'all' turns
+    // everything on; 'off' turns everything off.
+    const modifierEnabled = modifier === 'off' ? false : modifier === 'recommended' ? recommended : true;
+    return {
+        name,
+        description: def.description,
+        message: def.message,
+        severity,
+        enabled: enabled && modifierEnabled,
+        given: toArray(def.given),
+        then: toArray(def.then),
+        formats: def.formats ? new Set(def.formats) : undefined,
+        recommended,
+        resolved: def.resolved ?? true,
+        documentationUrl: def.documentationUrl,
+    };
+};
+const applyEntry = (rules, name, entry) => {
+    if (typeof entry === 'boolean') {
+        const existing = rules.get(name);
+        if (existing)
+            existing.enabled = entry;
+        return;
+    }
+    if (typeof entry === 'string') {
+        const existing = rules.get(name);
+        const { severity, enabled } = parseSeverity(entry);
+        if (existing) {
+            existing.severity = severity;
+            existing.enabled = enabled;
+        }
+        return;
+    }
+    // Full definition: define or replace (always enabled per its own severity).
+    rules.set(name, normalizeRule(name, entry, 'all'));
+};
+const collectExtends = (extendsValue, defaultModifier, resolve, into, basePath) => {
+    const entries = Array.isArray(extendsValue) ? extendsValue : [extendsValue];
+    for (const entry of entries) {
+        let target;
+        let modifier = defaultModifier;
+        if (Array.isArray(entry)) {
+            target = entry[0];
+            modifier = entry[1];
+        }
+        else {
+            target = entry;
+        }
+        if (typeof target === 'string') {
+            // A resolved file/package brings its own base directory for any nested extends.
+            const resolved = resolveNamed(target, resolve, basePath);
+            mergeInto(resolved.definition, modifier, resolve, into, resolved.basePath);
+        }
+        else {
+            mergeInto(target, modifier, resolve, into, basePath);
+        }
+    }
+};
+const resolveNamed = (name, resolve, basePath) => {
+    if (!resolve)
+        throw new Error(`Cannot resolve extended ruleset "${name}": no resolver provided`);
+    return resolve(name, basePath);
+};
+const mergeInto = (definition, modifier, resolve, into, basePath) => {
+    if (definition.extends) {
+        collectExtends(definition.extends, 'recommended', resolve, into, basePath);
+    }
+    if (definition.rules) {
+        for (const [name, entry] of Object.entries(definition.rules)) {
+            if (typeof entry === 'object') {
+                into.set(name, normalizeRule(name, entry, modifier));
+            }
+            else {
+                applyEntry(into, name, entry);
+            }
+        }
+    }
+};
+const cloneRule = (rule) => ({
+    ...rule,
+    given: [...rule.given],
+    then: [...rule.then],
+    formats: rule.formats ? new Set(rule.formats) : undefined,
+});
+/** Normalizes a ruleset definition into a {@link Ruleset} ready to run. */
+export const createRuleset = (definition, options = {}) => {
+    const functions = options.functions ?? {};
+    const formats = options.formats ?? {};
+    const aliases = (definition.aliases ?? {});
+    const overrides = definition.overrides ?? [];
+    const map = new Map();
+    mergeInto(definition, 'all', options.resolve, map, options.basePath ?? process.cwd());
+    const rules = [...map.values()];
+    const resolveAlias = (name, documentFormats) => {
+        const alias = aliases[name];
+        if (!alias)
+            return [];
+        if (Array.isArray(alias))
+            return alias;
+        for (const target of alias.targets) {
+            if (target.formats.some((format) => documentFormats.has(format)))
+                return target.given;
+        }
+        return [];
+    };
+    return {
+        rules,
+        functions,
+        formats,
+        aliases,
+        overrides,
+        parserOptions: definition.parserOptions,
+        enabledRules: rules.filter((rule) => rule.enabled),
+        getFunction: (name) => functions[name],
+        rulesForSource: (source) => {
+            if (!source || overrides.length === 0)
+                return rules;
+            const scoped = new Map(rules.map((rule) => [rule.name, cloneRule(rule)]));
+            for (const override of overrides) {
+                // Pointer-scoped entries (`file#/path`) are applied per-finding, not here.
+                const patterns = override.files.filter((file) => !file.includes('#'));
+                if (patterns.length === 0 || !matchesGlob(source, patterns))
+                    continue;
+                if (override.rules) {
+                    for (const [name, entry] of Object.entries(override.rules))
+                        applyEntry(scoped, name, entry);
+                }
+            }
+            return [...scoped.values()];
+        },
+        expandGiven: (given, documentFormats) => {
+            const out = [];
+            for (const expression of given) {
+                const match = /^#([A-Za-z0-9_-]+)(.*)$/.exec(expression);
+                if (match) {
+                    const aliasName = match[1];
+                    const rest = match[2] ?? '';
+                    for (const base of resolveAlias(aliasName, documentFormats))
+                        out.push(base + rest);
+                    continue;
+                }
+                out.push(expression);
+            }
+            return out;
+        },
+    };
+};

package/dist/core/runner.d.ts

@@ -0,0 +1,21 @@
+import type { Document } from './document.js';
+import type { Ruleset } from './ruleset.js';
+import { type IDiagnostic, type ISourceSet } from './types.js';
+/** Optional inputs to a runner's `run`: the dereferenced tree and its source documents. */
+export type IRunOptions = {
+    /** Dereferenced document data, used by rules with `resolved: true`. */
+    resolved?: unknown;
+    /**
+     * The source documents that fed the resolved tree, keyed by absolute location.
+     * When provided, findings on nodes inlined from external (`$ref`'d) files map
+     * back to that file's own line:column and `source` instead of the `$ref` site
+     * in the root document. Omit for in-memory / internal-only resolution.
+     */
+    sources?: ISourceSet;
+};
+/** Evaluates a normalized ruleset against a document. Produced by {@link createLinter}. */
+export type Linter = {
+    run(document: Document, options?: IRunOptions): IDiagnostic[];
+};
+/** Creates a {@link Linter} runner bound to a normalized `ruleset`. */
+export declare const createLinter: (ruleset: Ruleset) => Linter;