@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/plugins.js

@@ -0,0 +1,313 @@
+import { importLexiconModule, importLexiconPackage, lexiconModulePath, lexiconNames, registerLexiconDeclarations, resolveFromProject } from "../lexicon-module.js";
+import { readLexiconDeclarationsStatically } from "../config-static.js";
+export { unknownPathLexiconsNotice } from "../config-static.js";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isLexiconPlugin } from "../lexicon.js";
+import { loadChantConfigUpward } from "../config.js";
+import { findInfraFiles, detectLexicons } from "../index.js";
+import { isNoLexiconDetected } from "../detectLexicon.js";
+import { checkConflicts, describeConflict } from "./conflict-check.js";
+import { prepareProjectCodegen } from "../project-codegen.js";
+/**
+ * chant#2591 — record the lexicons the chant.config nearest `dir` declares by
+ * path (../lexicon-module.ts), for a command that does not otherwise read the
+ * config: `init --force`, `dev onboard` and `import --agents`.
+ *
+ * The config is read statically (../config-static.ts) and never evaluated,
+ * so these commands run no project code to learn it. When the `lexicons`
+ * value cannot be read that way, nothing is recorded, every lexicon keeps its
+ * package behaviour, and the returned read carries the reason; the caller
+ * prints {@link unknownPathLexiconsNotice} for it.
+ */
+export function recordProjectLexicons(dir) {
+    const read = readLexiconDeclarationsStatically(dir);
+    if (read.status === "read")
+        registerLexiconDeclarations(read.entries, dirname(read.configPath));
+    return read;
+}
+/**
+ * Load a single lexicon plugin by lexicon name.
+ *
+ * Dynamically imports `@intentius/chant-lexicon-{name}` and looks for a
+ * LexiconPlugin export. Falls back to wrapping a raw Serializer export.
+ */
+export async function loadPlugin(lexiconName) {
+    // chant #2520 — a lexicon declared by module path loads from that module.
+    const modulePath = lexiconModulePath(lexiconName);
+    if (modulePath !== undefined) {
+        const mod = (await importLexiconModule(lexiconName));
+        for (const value of Object.values(mod)) {
+            if (isLexiconPlugin(value)) {
+                if (value.name !== lexiconName) {
+                    throw new Error(`lexicon "${lexiconName}" is declared with module ${modulePath}, but the plugin it exports is named "${value.name}"`);
+                }
+                return value;
+            }
+        }
+        throw new Error(`Module ${modulePath} (lexicon "${lexiconName}") does not export a LexiconPlugin`);
+    }
+    const packageName = `@intentius/chant-lexicon-${lexiconName}`;
+    const mod = (await importLexiconPackage(packageName));
+    // Look for an explicit LexiconPlugin export
+    for (const value of Object.values(mod)) {
+        if (isLexiconPlugin(value)) {
+            return value;
+        }
+    }
+    // Fallback: wrap a raw Serializer export into a minimal plugin
+    const serializer = mod.serializer ?? mod.default?.serializer ?? mod[`${lexiconName}Serializer`];
+    if (serializer && typeof serializer === "object" && "name" in serializer && "serialize" in serializer) {
+        const notSupported = (op) => async () => {
+            throw new Error(`${serializer.name}: ${op} is not supported (raw serializer fallback)`);
+        };
+        return {
+            name: serializer.name,
+            serializer,
+            generate: notSupported("generate"),
+            validate: notSupported("validate"),
+            coverage: notSupported("coverage"),
+            package: notSupported("package"),
+        };
+    }
+    throw new Error(`Package ${packageName} does not export a LexiconPlugin or Serializer`);
+}
+const LEXICON_PACKAGE_PREFIX = "chant-lexicon-";
+/**
+ * The names of the lexicon packages installed where {@link loadPlugin} can
+ * load them (#2965), sorted. `loadPlugin` imports
+ * `@intentius/chant-lexicon-<name>` from chant's own install and then from the
+ * project (`importLexiconPackage`), so this lists the `@intentius` scope of
+ * every `node_modules` directory Node would search from either place: each
+ * ancestor of chant's own module and each ancestor of `projectDir`. A name
+ * being listed does not promise it loads; the caller still handles a failure.
+ */
+export function listInstalledLexicons(projectDir = process.cwd()) {
+    const names = new Set();
+    const starts = [dirname(fileURLToPath(import.meta.url)), resolve(projectDir)];
+    for (const start of starts) {
+        let dir = start;
+        for (;;) {
+            const scope = join(dir, "node_modules", "@intentius");
+            let entries = [];
+            try {
+                entries = readdirSync(scope, { withFileTypes: true });
+            }
+            catch {
+                // No @intentius scope here.
+            }
+            for (const entry of entries) {
+                if (!entry.name.startsWith(LEXICON_PACKAGE_PREFIX))
+                    continue;
+                if (!entry.isDirectory() && !entry.isSymbolicLink())
+                    continue;
+                const name = entry.name.slice(LEXICON_PACKAGE_PREFIX.length);
+                if (name !== "")
+                    names.add(name);
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return [...names].sort();
+}
+/**
+ * The installed version of each named lexicon package (chant #1442).
+ *
+ * A `LexiconPlugin` does not carry its own version — `LexiconManifest` does,
+ * but that is an artifact type describing generated output, not something the
+ * plugin object exposes. The version wanted here is a property of the
+ * *installed package*, so it is read from the package's own `package.json`.
+ *
+ * Resolved by walking up from the package's entry point rather than resolving
+ * `<pkg>/package.json` directly: lexicon packages declare an `exports` map
+ * that does not include `./package.json`, so the direct specifier is blocked
+ * by Node. `./manifest` (→ `dist/manifest.json`) is not used either — it is a
+ * `prepack` build artifact, absent in a monorepo dev tree, and its absence
+ * once read as four unrelated bugs (#1367).
+ *
+ * A lexicon whose version cannot be determined is omitted rather than
+ * recorded as `"unknown"`: a digest that says nothing is honest, one that
+ * says `unknown` compares unequal to itself across builds.
+ */
+export function resolveLexiconVersions(lexiconNames) {
+    const require_ = createRequire(import.meta.url);
+    const versions = {};
+    for (const name of lexiconNames) {
+        // chant #2520 — a lexicon declared by module path is not an installed
+        // package, so it has no package version to report.
+        if (lexiconModulePath(name) !== undefined)
+            continue;
+        const packageName = `@intentius/chant-lexicon-${name}`;
+        try {
+            // chant#2845 — a lexicon chant's own install can't reach is resolved from the project.
+            let entry;
+            try {
+                entry = require_.resolve(packageName);
+            }
+            catch (err) {
+                entry = resolveFromProject(packageName);
+                if (entry === undefined)
+                    throw err;
+            }
+            let dir = dirname(entry);
+            // Bounded walk — a resolved entry point is never deeply nested inside
+            // its own package, and an unbounded loop here would climb to `/`.
+            for (let depth = 0; depth < 10; depth++) {
+                const candidate = join(dir, "package.json");
+                if (existsSync(candidate)) {
+                    const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+                    // Only the lexicon's OWN package.json — a nested dependency's
+                    // manifest would otherwise be read as the lexicon's version.
+                    if (pkg.name === packageName && pkg.version) {
+                        versions[name] = pkg.version;
+                        break;
+                    }
+                }
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch {
+            // Not installed, or not resolvable from here — omit it.
+        }
+    }
+    return versions;
+}
+/**
+ * Bind each loaded plugin's `buildRoots` hook (#1548 piece 3) to this
+ * invocation's config and project root, producing the closures
+ * `BuildOptions.buildRoots` takes — the same extract-then-thread shape the
+ * CLI uses for `intrinsics`. Plugins without the hook contribute nothing;
+ * an empty array is the common case and `build()` treats it as absent.
+ */
+export function collectBuildRootContributors(plugins, config, projectRoot) {
+    // Project-local codegen (../project-codegen.ts) rides the same seam: every
+    // build path that renders build roots also has to refuse generated code
+    // that drifted from its declared sources, and to let the lexicon load that
+    // code (the k8s kinds its serializer must know) before serialization. Its
+    // contributor adds no entities; a drift is thrown, which the merge reports
+    // as a build error. Runs first, so a build-root hook sees loaded kinds.
+    const codegen = (plugins ?? [])
+        .filter((plugin) => typeof plugin.projectCodegen === "function")
+        .map((plugin) => async () => {
+        await prepareProjectCodegen(plugin, projectRoot, config);
+        return { entities: new Map() };
+    });
+    const roots = (plugins ?? [])
+        .filter((plugin) => typeof plugin.buildRoots === "function")
+        // `entities` is not bindable here — discovery has not run — so the merge
+        // hands it in when it calls the closure (#1828 / SOPS provenance).
+        .map((plugin) => (ctx) => plugin.buildRoots({ projectRoot, config, entities: ctx?.entities, ...(ctx?.sourceDir !== undefined ? { sourceDir: ctx.sourceDir } : {}) }));
+    return [...codegen, ...roots];
+}
+/**
+ * Bind each loaded plugin's `subscribeChanges` seam (#1981) to one environment
+ * and its declared entities, producing the `ChangeSubscriber` list `chant
+ * operator`'s loop takes, in the same extract-then-thread shape
+ * {@link collectBuildRootContributors} uses, and for the same reason: core's
+ * operator must not import plugins.
+ *
+ * Plugins without the seam contribute nothing, so a project whose lexicons all
+ * lack it gets a loop that is exactly the timer it always was. `entities` is
+ * the per-lexicon slice of a build's declared entities, which is the bound on
+ * what a subscription may watch; a lexicon with no declared entities is
+ * skipped rather than handed an empty scope to widen.
+ */
+export function collectChangeSubscribers(plugins, options) {
+    return (plugins ?? [])
+        .filter((plugin) => typeof plugin.subscribeChanges === "function")
+        .filter((plugin) => (options.entities.get(plugin.name)?.size ?? 0) > 0)
+        .map((plugin) => ({
+        lexicon: plugin.name,
+        subscribe: (ctx) => plugin.subscribeChanges({
+            environment: options.environment,
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+            entities: options.entities.get(plugin.name),
+            onChange: ctx.onChange,
+            onError: ctx.onError,
+            signal: ctx.signal,
+        }),
+    }));
+}
+/**
+ * Load plugins for all detected lexicon names.
+ * Calls `init()` on each plugin if present.
+ */
+export async function loadPlugins(lexiconNames) {
+    const plugins = [];
+    for (const name of lexiconNames) {
+        const plugin = await loadPlugin(name);
+        if (plugin.init) {
+            await plugin.init();
+        }
+        plugins.push(plugin);
+    }
+    // Cross-lexicon conflict detection
+    const report = checkConflicts(plugins);
+    for (const warning of report.warnings) {
+        console.warn(`[chant] warning: ${warning.type} "${warning.key}" is provided by multiple lexicons: ${warning.plugins.join(", ")}`);
+    }
+    if (report.conflicts.length > 0) {
+        const details = report.conflicts.map(describeConflict).join("\n");
+        throw new Error(`Cross-lexicon conflicts detected:\n${details}`);
+    }
+    return plugins;
+}
+/**
+ * Resolve lexicon names for a project directory.
+ *
+ * Reads `lexicons` from `chant.config.ts` / `chant.config.json` if present.
+ * Falls back to source-file detection via `detectLexicons()`.
+ *
+ * chant #1045 Phase 2 — this used to fall back to a full `discover()` call
+ * just to read its `sourceFiles` list, which imports and RUNS every project
+ * source file to collect entities that are then discarded here. That ran
+ * unconditionally, on every command that reaches this function without an
+ * explicit `chant.config.ts` `lexicons` list (`build`, `lint`, `doctor`,
+ * `import`, `graph`, the MCP server — effectively the whole CLI), with no
+ * `--fold`/`--sandbox` involved at all: a project could omit `lexicons` and
+ * every file would execute here, in the CLI's own process, before the
+ * caller's OWN (possibly folded, possibly sandboxed) build ever ran. Fixed
+ * by using `findInfraFiles()` alone — the pure directory walk `discover()`
+ * itself starts from, no import, no execution — since `detectLexicons()` is
+ * already a plain text/regex scan over file contents (`../detectLexicon.ts`)
+ * that never needed live module exports to begin with. This is strictly
+ * better than routing the detection through the sandbox: it removes the
+ * execution entirely rather than containing it, at no bundling/spawn cost.
+ *
+ * chant #1117 — walks up from `projectPath` to the project root
+ * (`loadChantConfigUpward`) rather than reading `projectPath` alone: `chant
+ * build src/<stack>` calls this with the stack's own subdirectory, and a
+ * project that declares `lexicons` only in its root `chant.config.ts` (never
+ * detectable by `detectLexicons()`'s import scan alone, e.g. a lexicon that's
+ * loaded but never imported by name in that particular stack's files) would
+ * otherwise silently miss it.
+ */
+export async function resolveProjectLexicons(projectPath, options = {}) {
+    const requested = options.lexicon;
+    const { config } = await loadChantConfigUpward(projectPath);
+    let names;
+    if (config.lexicons && config.lexicons.length > 0) {
+        names = lexiconNames(config.lexicons);
+    }
+    else {
+        // Fallback: detect from source imports — a pure text scan, no execution.
+        const files = await findInfraFiles(projectPath);
+        try {
+            names = await detectLexicons(files);
+        }
+        catch (error) {
+            if (requested && isNoLexiconDetected(error))
+                return [requested];
+            throw error;
+        }
+    }
+    return requested && !names.includes(requested) ? [...names, requested] : names;
+}

package/dist/cli/registry.js

@@ -0,0 +1,23 @@
+/**
+ * Resolve a command from parsed CLI args against the registry.
+ *
+ * Supports compound commands like "dev generate" where args.command="dev"
+ * and args.path="generate". Falls back to simple command matching.
+ */
+/** Short command aliases. `chant lc …` is sugar for `chant lifecycle …`. */
+const COMMAND_ALIASES = { lc: "lifecycle" };
+export function resolveCommand(args, registry) {
+    const command = COMMAND_ALIASES[args.command] ?? args.command;
+    // Try compound command first: "dev generate", "serve lsp", "init lexicon"
+    const compound = `${command} ${args.path}`;
+    const compoundMatch = registry.find((c) => c.name === compound);
+    if (compoundMatch) {
+        return { def: compoundMatch, compound: true };
+    }
+    // Try simple command
+    const simpleMatch = registry.find((c) => c.name === command);
+    if (simpleMatch) {
+        return { def: simpleMatch, compound: false };
+    }
+    return null;
+}

package/dist/cli/reporters/stylish.js

@@ -0,0 +1,329 @@
+import { pathToFileURL } from "node:url";
+/**
+ * ANSI color codes
+ */
+const colors = {
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    underline: "\x1b[4m",
+};
+/**
+ * Check if colors should be used
+ */
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+/**
+ * Apply color if enabled
+ */
+function color(text, colorCode) {
+    if (!useColors())
+        return text;
+    return `${colorCode}${text}${colors.reset}`;
+}
+/**
+ * Format diagnostics in stylish format (similar to ESLint)
+ * Groups by file, shows severity, message, and rule ID
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param suppressed - Suppressed diagnostics with optional reason (optional). When
+ *   present and non-empty, a "Suppressed" section is appended (#1866, design #1059)
+ *   below the active diagnostics, mirroring SARIF's `suppressed` param on
+ *   {@link formatSarif} rather than changing what "diagnostics" means here.
+ * @param bundle - The project's loaded OKF knowledge bundle (`../../okf-read`'s
+ *   `loadOkfBundle`), used to resolve `okf:` citations in suppression reasons.
+ *   Omitted (or a bundle with no matching concept) falls back to printing the
+ *   raw reason with a warning — this never affects suppression itself, only
+ *   how a cited reason renders.
+ */
+export function formatStylish(diagnostics, suppressed, bundle) {
+    const hasSuppressed = suppressed !== undefined && suppressed.length > 0;
+    if (diagnostics.length === 0 && !hasSuppressed) {
+        return formatSummary(0, 0);
+    }
+    const lines = [];
+    let errorCount = 0;
+    let warningCount = 0;
+    if (diagnostics.length > 0) {
+        // Group by file
+        const byFile = new Map();
+        for (const diag of diagnostics) {
+            const existing = byFile.get(diag.file) ?? [];
+            existing.push(diag);
+            byFile.set(diag.file, existing);
+        }
+        for (const [file, fileDiags] of byFile) {
+            // File header with underline
+            lines.push("");
+            lines.push(color(file, colors.underline));
+            // Sort by line, then column
+            fileDiags.sort((a, b) => {
+                if (a.line !== b.line)
+                    return a.line - b.line;
+                return a.column - b.column;
+            });
+            for (const diag of fileDiags) {
+                // Count errors and warnings
+                if (diag.severity === "error") {
+                    errorCount++;
+                }
+                else if (diag.severity === "warning") {
+                    warningCount++;
+                }
+                // Format: "  line:col  severity  message  ruleId"
+                const location = color(`${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`, colors.gray);
+                const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
+                const severity = color(diag.severity.padEnd(7), severityColor);
+                const ruleId = color(diag.ruleId, colors.gray);
+                lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+            }
+        }
+    }
+    if (hasSuppressed) {
+        lines.push(...formatSuppressedSection(suppressed, bundle));
+    }
+    // Summary line
+    lines.push("");
+    const summary = formatSummary(errorCount, warningCount);
+    lines.push(summary);
+    return lines.join("\n");
+}
+/**
+ * Resolve a suppression reason's `okf:<path>` citation (#1866, design #1059)
+ * against a loaded bundle's concepts, matched on `OkfConcept.path`. Not an
+ * `okf:` citation at all: returns `null`, and the reason renders as plain
+ * text, same as before this section existed. A leading `/` on the cited path
+ * is accepted and stripped — `okf-read.ts`'s bundle-relative paths never
+ * carry one, but the design doc's worked example writes citations with one
+ * (mirroring an absolute-from-bundle-root reading), so both forms resolve.
+ */
+function resolveOkfCitation(reason, bundle) {
+    const prefix = "okf:";
+    if (!reason.startsWith(prefix))
+        return null;
+    const token = reason.slice(prefix.length).trim().replace(/^\/+/, "");
+    const concept = bundle?.concepts.find((c) => c.path === token);
+    if (concept) {
+        return { label: concept.title ?? concept.path, path: concept.path, unresolved: false };
+    }
+    return { label: reason, unresolved: true };
+}
+/**
+ * Render the "Suppressed" section: every suppressed diagnostic, grouped by
+ * file like the active section above, with an `okf:` reason resolved to its
+ * concept's title (and bundle-relative path on the line below) when
+ * `bundle` has a match. A citation naming no concept — including when no
+ * `bundle` was loaded at all — prints the raw reason plus a warning; a
+ * plain (non-`okf:`) reason prints as-is. Never affects which diagnostics
+ * are suppressed, only how the reason renders (design #1059: "a cited
+ * suppression suppresses exactly as an uncited one does").
+ */
+function formatSuppressedSection(suppressed, bundle) {
+    const lines = [];
+    const byFile = new Map();
+    for (const diag of suppressed) {
+        const existing = byFile.get(diag.file) ?? [];
+        existing.push(diag);
+        byFile.set(diag.file, existing);
+    }
+    lines.push("");
+    lines.push(color("Suppressed", colors.underline));
+    for (const [file, fileDiags] of byFile) {
+        lines.push("");
+        lines.push(color(file, colors.underline));
+        fileDiags.sort((a, b) => {
+            if (a.line !== b.line)
+                return a.line - b.line;
+            return a.column - b.column;
+        });
+        for (const diag of fileDiags) {
+            const locationPlain = `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`;
+            const location = color(locationPlain, colors.gray);
+            const severity = color("suppressed", colors.cyan);
+            const ruleId = color(diag.ruleId, colors.gray);
+            const citation = diag.reason ? resolveOkfCitation(diag.reason, bundle) : null;
+            const indent = " ".repeat(2 + locationPlain.length + 2 + "suppressed".length + 2 + diag.ruleId.length + 2);
+            if (citation) {
+                lines.push(`  ${location}  ${severity}  ${ruleId}  ${citation.label}`);
+                if (!citation.unresolved) {
+                    lines.push(`${indent}${color(citation.path, colors.gray)}`);
+                }
+                else {
+                    lines.push(`${indent}${color("⚠ unresolved okf citation", colors.yellow)}`);
+                }
+            }
+            else if (diag.reason) {
+                lines.push(`  ${location}  ${severity}  ${ruleId}  ${diag.reason}`);
+            }
+            else {
+                lines.push(`  ${location}  ${severity}  ${ruleId}`);
+            }
+        }
+    }
+    return lines;
+}
+/**
+ * Format the summary line
+ */
+export function formatSummary(errorCount, warningCount) {
+    const parts = [];
+    if (errorCount > 0) {
+        parts.push(color(`${errorCount} error${errorCount === 1 ? "" : "s"}`, colors.red));
+    }
+    if (warningCount > 0) {
+        parts.push(color(`${warningCount} warning${warningCount === 1 ? "" : "s"}`, colors.yellow));
+    }
+    if (parts.length === 0) {
+        return color("✓ No problems found", colors.green);
+    }
+    const symbol = errorCount > 0 ? "✖" : "⚠";
+    return `${symbol} ${parts.join(", ")}`;
+}
+/**
+ * Format diagnostics as JSON
+ */
+export function formatJson(diagnostics) {
+    return JSON.stringify(diagnostics, null, 2);
+}
+/**
+ * Map lint severity to SARIF level
+ */
+function mapSeverity(severity) {
+    if (severity === "error")
+        return "error";
+    if (severity === "warning")
+        return "warning";
+    return "note";
+}
+/**
+ * Build a SARIF region object, only including endLine/endColumn when available
+ */
+function buildRegion(diag) {
+    const region = {
+        startLine: diag.line,
+        startColumn: diag.column,
+    };
+    if (diag.endLine !== undefined)
+        region.endLine = diag.endLine;
+    if (diag.endColumn !== undefined)
+        region.endColumn = diag.endColumn;
+    return region;
+}
+/**
+ * Build a SARIF result from a diagnostic
+ */
+function buildSarifResult(diag, ruleIndex) {
+    const result = {
+        ruleId: diag.ruleId,
+        ruleIndex: ruleIndex.get(diag.ruleId),
+        level: mapSeverity(diag.severity),
+        message: { text: diag.message },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: {
+                        uri: diag.file.startsWith("/") ? pathToFileURL(diag.file).href : diag.file,
+                    },
+                    region: buildRegion(diag),
+                },
+            },
+        ],
+        fingerprints: {
+            "chant/v1": `${diag.ruleId}:${diag.file}:${diag.line}:${diag.column}`,
+        },
+    };
+    return result;
+}
+/**
+ * Format diagnostics as SARIF (Static Analysis Results Interchange Format)
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param rules - Full list of loaded LintRules for rich metadata (optional)
+ * @param suppressed - Suppressed diagnostics with optional reason (optional)
+ * @param version - Tool version string (optional, defaults to "0.1.0")
+ */
+export function formatSarif(diagnostics, rules, suppressed, version) {
+    // Build rule metadata from LintRule objects when available, otherwise from diagnostics
+    const { sarifRules, ruleIndex } = buildRuleMetadata(diagnostics, suppressed ?? [], rules);
+    // Build active results
+    const results = diagnostics.map((diag) => buildSarifResult(diag, ruleIndex));
+    // Append suppressed results with SARIF suppressions
+    if (suppressed) {
+        for (const diag of suppressed) {
+            const result = buildSarifResult(diag, ruleIndex);
+            result.suppressions = [
+                {
+                    kind: "inSource",
+                    ...(diag.reason ? { justification: diag.reason } : {}),
+                },
+            ];
+            results.push(result);
+        }
+    }
+    const sarif = {
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "chant",
+                        version: version ?? "0.1.0",
+                        informationUri: "https://intentius.io/chant",
+                        rules: sarifRules,
+                    },
+                },
+                results,
+            },
+        ],
+    };
+    return JSON.stringify(sarif, null, 2);
+}
+/**
+ * Build SARIF rule metadata from loaded LintRules and/or diagnostics.
+ * Returns both the rules array and a ruleId→index map for result references.
+ */
+function buildRuleMetadata(diagnostics, suppressed, rules) {
+    // Build a lookup from rule objects
+    const ruleMap = new Map();
+    if (rules) {
+        for (const r of rules) {
+            ruleMap.set(r.id, r);
+        }
+    }
+    // Collect all unique rule IDs from diagnostics + suppressed
+    const seen = new Set();
+    const orderedIds = [];
+    for (const diag of [...diagnostics, ...suppressed]) {
+        if (!seen.has(diag.ruleId)) {
+            seen.add(diag.ruleId);
+            orderedIds.push(diag.ruleId);
+        }
+    }
+    const sarifRules = [];
+    const ruleIndex = new Map();
+    for (const id of orderedIds) {
+        const rule = ruleMap.get(id);
+        const descText = rule?.description || id;
+        const entry = {
+            id,
+            shortDescription: { text: descText },
+            fullDescription: { text: descText },
+            helpUri: rule?.helpUri || `https://intentius.io/chant/lint-rules/${id.toLowerCase()}`,
+            defaultConfiguration: {
+                level: mapSeverity(rule?.severity ?? "warning"),
+            },
+        };
+        if (rule?.category) {
+            entry.properties = { category: rule.category };
+        }
+        ruleIndex.set(id, sarifRules.length);
+        sarifRules.push(entry);
+    }
+    return { sarifRules, ruleIndex };
+}

package/dist/cli/version.js

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+/**
+ * The installed chant's version, read from `@intentius/chant`'s own
+ * package.json, or "0.0.0" when it can't be read. The path is the same from
+ * `src/cli/` and `dist/cli/`, so it holds whether chant runs from source or
+ * from its build.
+ */
+export const CHANT_VERSION = (() => {
+    try {
+        return createRequire(import.meta.url)("../../package.json").version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();