@cairn-tool/cairn 2.0.0

package/dist/commands/audit.js

@@ -0,0 +1,325 @@
+import path from "node:path";
+import fs from "node:fs";
+import { minimatch } from "minimatch";
+import { lintFile } from "../lint.js";
+import { buildWorkspaceGraph } from "../graph.js";
+import { FrontmatterValidator } from "../frontmatter-validation.js";
+import { tocSynchronizationIssue } from "./toc.js";
+import { checkUrlOccurrences } from "./check-urls.js";
+import { outputPath, runtime } from "../runtime.js";
+import { requireDirectory } from "../input.js";
+import { terminate } from "../command-result.js";
+import { formatDiagnostics } from "../automation.js";
+import { changedMarkdownFiles } from "../input-selection.js";
+import { extractCodeBlocks } from "../markdown-ast.js";
+import { createSourceReader, synchronizeSnippets } from "../snippets.js";
+import { jsonPayload } from "../result.js";
+import { packageName, packageVersion } from "../version.js";
+import { applyBaseline, buildBaseline, readBaseline, writeBaseline, } from "../audit-baseline.js";
+async function concurrent(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+    return results;
+}
+function graphFindings(graph) {
+    return [
+        ...graph.broken.map((edge) => ({
+            file: edge.source,
+            line: edge.line,
+            checker: "graph/broken",
+            message: `Markdown target not found: ${edge.target}`,
+        })),
+        ...graph.unreachable.map((file) => ({
+            file,
+            line: 1,
+            checker: "graph/unreachable",
+            message: "Document is unreachable from configured entry points",
+        })),
+    ];
+}
+/**
+ * Snippet drift, reported but never repaired.
+ *
+ * The checker names are prefixed `snippets/` so the audit category derived
+ * from the checker matches the `enabled` entry. Messages carry the target as
+ * the author wrote it and no line number, because `--baseline` keys on
+ * checker, workspace-relative path, and message.
+ */
+function snippetFindings(files) {
+    const root = runtime().config.root;
+    const read = createSourceReader(root);
+    const issues = [];
+    for (const file of files) {
+        const document = runtime().workspace.document(file);
+        const results = synchronizeSnippets(document.content, extractCodeBlocks(document.tree), {
+            file,
+            root,
+            read,
+        });
+        for (const result of results) {
+            if (result.status === "current")
+                continue;
+            if (result.status === "stale") {
+                issues.push({
+                    file,
+                    line: result.line,
+                    checker: "snippets/drift",
+                    message: `Snippet is out of date with ${result.target}`,
+                });
+                continue;
+            }
+            const kind = result.reason.startsWith("source-")
+                ? "source"
+                : result.reason.startsWith("region-")
+                    ? "region"
+                    : "meta";
+            issues.push({
+                file,
+                line: result.line,
+                checker: `snippets/${kind}`,
+                message: result.message,
+            });
+        }
+    }
+    return issues;
+}
+export async function auditAction(directory, opts) {
+    const dir = requireDirectory(directory, opts);
+    let files = runtime().workspace.markdownFiles(dir, {
+        include: opts.include,
+        exclude: opts.exclude,
+    });
+    if (opts.changedSince) {
+        const changed = new Set(changedMarkdownFiles(opts.changedSince));
+        files = files.filter((file) => changed.has(file));
+    }
+    const enabled = [];
+    const skipped = [];
+    let findings = [];
+    const lintNames = [
+        ["markdownlint", opts.style],
+        ["mermaid", opts.mermaid],
+        ["katex", opts.katex],
+        ["references", opts.references],
+    ];
+    for (const [name, active] of lintNames)
+        (active ? enabled : skipped).push(name);
+    const lintResults = await concurrent(files, parseInt(opts.concurrency, 10) || 1, (file) => lintFile(file, {
+        style: opts.style,
+        mermaid: opts.mermaid,
+        katex: opts.katex,
+        references: opts.references,
+    }));
+    findings.push(...lintResults.flat());
+    let graph;
+    if (opts.graph) {
+        enabled.push("graph");
+        const entries = opts.entry.map((entry) => path.resolve(entry));
+        for (const entry of entries) {
+            if (!fs.existsSync(entry) || !fs.statSync(entry).isFile()) {
+                throw new Error(`Entry point not found: ${entry}`);
+            }
+        }
+        graph = buildWorkspaceGraph(runtime().workspace, files, entries);
+        const graphIssues = graphFindings(graph);
+        const duplicate = new Set(graph.broken.map((edge) => `${edge.source}\0${edge.line}\0${edge.target}`));
+        findings = findings.filter((issue) => {
+            const target = issue.message.replace(/^Link target not found: /, "");
+            return !(issue.checker === "ref/link" && duplicate.has(`${issue.file}\0${issue.line}\0${target}`));
+        });
+        findings.push(...graphIssues);
+    }
+    else
+        skipped.push("graph");
+    const hasFrontmatter = Boolean(runtime().config.frontmatter.schema) ||
+        Object.values(runtime().config.frontmatter.rules).some((value) => Array.isArray(value) ? value.length : Object.keys(value).length);
+    if (opts.frontmatter && hasFrontmatter) {
+        enabled.push("frontmatter");
+        findings.push(...new FrontmatterValidator(runtime().config.frontmatter.rules, runtime().config.frontmatter.schema).validateMany(files.map((file) => runtime().workspace.document(file))));
+    }
+    else
+        skipped.push("frontmatter");
+    if (opts.toc && runtime().config.toc.files.length) {
+        enabled.push("toc");
+        for (const file of files) {
+            const relative = path.relative(runtime().config.root, file).split(path.sep).join("/");
+            if (!runtime().config.toc.files.some((pattern) => minimatch(relative, pattern, { dot: true, nonegate: true })))
+                continue;
+            const result = tocSynchronizationIssue(file, opts);
+            if (result.malformed)
+                throw new Error(`${file}: ${result.malformed}`);
+            if (!result.current)
+                findings.push({ file, line: 1, checker: "toc", message: result.issue });
+        }
+    }
+    else
+        skipped.push("toc");
+    if (opts.snippets) {
+        enabled.push("snippets");
+        findings.push(...snippetFindings(files));
+    }
+    else
+        skipped.push("snippets");
+    if (opts.external) {
+        enabled.push("external");
+        const occurrences = files.flatMap((file) => runtime()
+            .workspace.document(file)
+            .references.filter((ref) => ref.isExternal &&
+            /^https?:/i.test(ref.target) &&
+            !runtime().config.urls.ignore.some((pattern) => minimatch(ref.target, pattern, { nonegate: true })) &&
+            !runtime().config.urls.ignoreDomains.some((domain) => {
+                try {
+                    const host = new URL(ref.target).hostname.toLowerCase();
+                    const normalized = domain.toLowerCase().replace(/^\*\./, "");
+                    return host === normalized || host.endsWith(`.${normalized}`);
+                }
+                catch {
+                    return false;
+                }
+            }))
+            .map((ref) => ({ file, line: ref.line, url: ref.target })));
+        const results = await checkUrlOccurrences(occurrences, {
+            timeout: parseInt(opts.timeout, 10) || 5000,
+            concurrency: parseInt(opts.concurrency, 10) || 5,
+            retries: parseInt(opts.retry, 10) || 0,
+            allowedStatuses: runtime().config.urls.allowedStatuses,
+            headFallbackStatuses: runtime().config.urls.headFallbackStatuses,
+            cache: runtime().config.urls.cache,
+            cacheTtl: runtime().config.urls.cacheTtl,
+        });
+        findings.push(...results
+            .filter((result) => !result.ok)
+            .map((result) => ({
+            file: result.file,
+            line: result.line,
+            checker: "external",
+            message: `${result.url}: ${result.status ?? result.error ?? "request failed"}`,
+        })));
+    }
+    else
+        skipped.push("external");
+    findings.sort((a, b) => a.checker.localeCompare(b.checker) || a.file.localeCompare(b.file) || a.line - b.line);
+    const root = runtime().config.root;
+    if (opts.writeBaseline) {
+        // Recording is a separate act from checking: writing the file a run is
+        // simultaneously being judged against has no meaning.
+        if (opts.baseline)
+            throw new Error("--baseline and --write-baseline cannot be combined");
+        writeBaseline(opts.writeBaseline, buildBaseline(findings, root, { name: packageName, version: packageVersion }));
+        process.stdout.write(`Wrote ${findings.length} baseline entr${findings.length === 1 ? "y" : "ies"} to ${opts.writeBaseline}\n`);
+        return;
+    }
+    let baseline;
+    if (opts.baseline) {
+        const applied = applyBaseline(findings, readBaseline(opts.baseline), root);
+        if (applied.foreign) {
+            findings.push({
+                file: path.resolve(opts.baseline),
+                line: 1,
+                checker: "baseline",
+                message: "Not a cairn-md-audit-baseline document; no findings were suppressed",
+            });
+            findings.sort((a, b) => a.checker.localeCompare(b.checker) || a.file.localeCompare(b.file) || a.line - b.line);
+        }
+        else {
+            findings = applied.kept;
+        }
+        baseline = {
+            path: outputPath(path.resolve(opts.baseline), opts),
+            suppressed: applied.suppressed,
+            stale: applied.stale,
+        };
+    }
+    const shown = findings.map((issue) => ({ ...issue, file: outputPath(issue.file, opts) }));
+    const byCheck = Object.fromEntries(enabled.map((check) => [check, 0]));
+    const byFile = {};
+    for (const issue of shown) {
+        const rawCategory = issue.checker.split("/")[0];
+        const category = rawCategory === "ref" ? "references" : rawCategory;
+        byCheck[category] = (byCheck[category] ?? 0) + 1;
+        byFile[issue.file] = (byFile[issue.file] ?? 0) + 1;
+    }
+    const result = {
+        directory: outputPath(dir, opts),
+        enabled,
+        skipped,
+        totals: {
+            files: files.length,
+            findings: shown.length,
+            filesWithFindings: Object.keys(byFile).length,
+            byCheck,
+            byFile,
+        },
+        findings: shown,
+        ...(baseline ? { baseline } : {}),
+        ...(graph
+            ? {
+                graph: {
+                    nodes: graph.nodes.length,
+                    edges: graph.edges.length,
+                    broken: graph.broken.length,
+                    unreachable: graph.unreachable.length,
+                    deadEnds: graph.nodes.filter((node) => node.deadEnd).length,
+                    components: graph.components.length,
+                    cycles: graph.cycles.length,
+                    reachabilityEvaluated: graph.reachabilityEvaluated,
+                },
+            }
+            : {}),
+    };
+    // One value decides the payload counts, the stream, and the exit code.
+    // Reading `findings` for the stream while the payload counted `shown` was a
+    // latent split that baseline suppression would have turned into a real bug.
+    const actionable = shown.length;
+    // Suppression and staleness are described, never judged: a stale entry means
+    // something was fixed, which must not fail a build.
+    const baselineLines = baseline
+        ? [
+            `Baseline: ${baseline.suppressed} suppressed, ${baseline.stale.length} stale (${baseline.path})`,
+        ]
+        : [];
+    let payload;
+    if (opts.format === "json")
+        payload = jsonPayload("md audit", result, opts, {
+            exitCode: actionable ? 2 : 0,
+            summary: {
+                findings: actionable,
+                files: result.totals.files,
+                ...(baseline ? { suppressed: baseline.suppressed } : {}),
+            },
+        }).trimEnd();
+    else if (opts.format === "jsonl" || opts.format === "sarif")
+        payload = formatDiagnostics(shown, opts.format, {
+            files: files.length,
+            findings: actionable,
+            enabled,
+            skipped,
+            ...(baseline ? { suppressed: baseline.suppressed } : {}),
+        });
+    else if (opts.summary)
+        payload = [
+            `Audit: ${result.totals.files} file(s), ${result.totals.findings} finding(s)`,
+            ...baselineLines,
+            ...Object.entries(byCheck).map(([check, count]) => `  ${check}: ${count}`),
+            ...Object.entries(byFile).map(([file, count]) => `  ${file}: ${count}`),
+        ].join("\n");
+    else
+        payload = (actionable
+            ? [
+                `${actionable} audit finding(s) in ${result.directory}:`,
+                ...shown.map((issue) => `  ${issue.file}:${issue.line} [${issue.checker}] ${issue.message}`),
+                ...baselineLines,
+            ]
+            : [`Audit passed for ${files.length} file(s) in ${result.directory}`, ...baselineLines]).join("\n");
+    (actionable ? process.stderr : process.stdout).write(payload + "\n");
+    if (actionable)
+        terminate(2);
+}
+//# sourceMappingURL=audit.js.map

package/dist/commands/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"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"}

package/dist/commands/check-snippets.d.ts

@@ -0,0 +1,58 @@
+import { type SnippetReason } from "../snippets.js";
+export type CheckSnippetsMode = "check" | "dry-run" | "write";
+interface CheckSnippetsOptions {
+    envelope?: boolean;
+    format: string;
+    paths?: string;
+    check?: boolean;
+    write?: boolean;
+    dryRun?: boolean;
+    includeOk: boolean;
+    include: string[];
+    exclude: string[];
+}
+export interface SnippetFindingJson {
+    file: string;
+    /** 1-based line of the opening fence. */
+    line: number;
+    endLine: number;
+    status: "current" | "stale" | "unresolved" | "malformed";
+    /** The attribute value as written. Absent when it could not be parsed. */
+    target?: string;
+    /** Absolute or relative per --paths. Absent until the path resolves. */
+    source?: string;
+    /** Present on everything except a clean match. */
+    reason?: SnippetReason;
+    message?: string;
+    /** --dry-run only: the two bodies, container indentation removed. */
+    documented?: string;
+    expected?: string;
+    /** Stale blocks outside --check: false when the fence cannot be rewritten. */
+    writable?: boolean;
+    /** --write only: whether this block's bytes changed. */
+    applied?: boolean;
+}
+export interface CheckSnippetsPayload {
+    mode: CheckSnippetsMode;
+    filesScanned: number;
+    /** Fences carrying a snippet link. An unlinked fence is never counted. */
+    linked: number;
+    current: number;
+    drift: number;
+    unresolved: number;
+    malformed: number;
+    /** Stale blocks the fence cannot accept. Always 0 under --check. */
+    unwritable: number;
+    /** Files whose bytes changed. Always 0 outside --write. */
+    applied: number;
+    /** `current` entries appear only under --include-ok. */
+    findings: SnippetFindingJson[];
+    conflicts: Array<{
+        kind: string;
+        file: string;
+        message: string;
+        rules: string[];
+    }>;
+}
+export declare function checkSnippetsAction(inputs: string[], opts: CheckSnippetsOptions): Promise<void>;
+export {};

package/dist/commands/check-snippets.js

@@ -0,0 +1,247 @@
+import { applyPlan, buildPlan, containmentRoot, snapshot, } from "../edit-plan.js";
+import { extractCodeBlocks, parseMarkdown } from "../markdown-ast.js";
+import { createSourceReader, snippetEdits, synchronizeSnippets, } from "../snippets.js";
+import { fingerprint } from "../workspace-index.js";
+import { resolveMarkdownInputs } from "../input-selection.js";
+import { outputPath, runtime } from "../runtime.js";
+import { terminate } from "../command-result.js";
+import { jsonPayload } from "../result.js";
+function resolveFormat(opts) {
+    const fmt = opts.format;
+    if (fmt === "llm" || fmt === "human" || fmt === "json")
+        return fmt;
+    return "llm";
+}
+/**
+ * Which of check, dry-run, and write was asked for.
+ *
+ * A plain guard is enough, as in `md fix`: those three keys are deliberately
+ * absent from `COMMAND_OPTIONS["check-snippets"]`, so a checked-in config can
+ * never turn this checker into a writer and there is no config-versus-CLI
+ * ambiguity to disentangle. That rule matters more here than anywhere else,
+ * because `--write` copies the contents of arbitrary source files into tracked
+ * documents.
+ */
+function resolveMode(opts) {
+    const requested = [
+        ["check", opts.check],
+        ["write", opts.write],
+        ["dry-run", opts.dryRun],
+    ]
+        .filter(([, enabled]) => enabled)
+        .map(([name]) => name);
+    if (requested.length > 1) {
+        throw new Error("--check, --write, and --dry-run cannot be used together");
+    }
+    return requested[0] ?? "check";
+}
+function truncate(value, limit = 120) {
+    const flat = value.replace(/\n/g, "\\n");
+    return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+}
+function toFinding(file, result, mode, applied, opts) {
+    const base = {
+        file: outputPath(file, opts),
+        line: result.line,
+        endLine: result.endLine,
+    };
+    if (result.status === "malformed") {
+        return { ...base, status: "malformed", reason: result.reason, message: result.message };
+    }
+    if (result.status === "unresolved") {
+        return {
+            ...base,
+            status: "unresolved",
+            target: result.target,
+            ...(result.source ? { source: outputPath(result.source, opts) } : {}),
+            reason: result.reason,
+            message: result.message,
+        };
+    }
+    if (result.status === "current") {
+        return {
+            ...base,
+            status: "current",
+            target: result.target,
+            source: outputPath(result.source, opts),
+        };
+    }
+    return {
+        ...base,
+        status: "stale",
+        target: result.target,
+        source: outputPath(result.source, opts),
+        ...(result.unwritable && mode !== "check"
+            ? { reason: result.unwritable.reason, message: result.unwritable.message }
+            : {}),
+        ...(mode === "dry-run" ? { documented: result.documented, expected: result.expected } : {}),
+        ...(mode === "check" ? {} : { writable: Boolean(result.write) }),
+        ...(applied ? { applied: applied.has(file) && Boolean(result.write) } : {}),
+    };
+}
+function renderText(payload, human) {
+    const bold = (value) => (human ? `\x1b[1m${value}\x1b[0m` : value);
+    const red = (value) => (human ? `\x1b[31m${value}\x1b[0m` : value);
+    const green = (value) => (human ? `\x1b[32m${value}\x1b[0m` : value);
+    const cyan = (value) => (human ? `\x1b[36m${value}\x1b[0m` : value);
+    const lines = [];
+    const headline = payload.mode === "write"
+        ? payload.applied
+            ? `Refreshed ${payload.applied} file(s) of ${payload.linked} linked snippet(s).`
+            : `Nothing to refresh in ${payload.linked} linked snippet(s).`
+        : payload.drift + payload.unresolved + payload.malformed
+            ? bold(`${payload.drift} stale, ${payload.unresolved} unresolved, ${payload.malformed} malformed ` +
+                `of ${payload.linked} linked snippet(s) in ${payload.filesScanned} file(s)`)
+            : `${payload.linked} linked snippet(s) up to date in ${payload.filesScanned} file(s)`;
+    for (const finding of payload.findings) {
+        const where = cyan(`${finding.file}:L${finding.line}`);
+        if (finding.status === "current") {
+            lines.push(`  ${where}  ok  ${finding.target}`);
+            continue;
+        }
+        if (finding.status === "stale") {
+            const suffix = finding.writable === false ? `  (not rewritten: ${finding.reason})` : "";
+            lines.push(`  ${where}  stale  ${finding.target}${suffix}`);
+            if (payload.mode === "dry-run") {
+                lines.push(`    ${red(`- ${truncate(finding.documented ?? "")}`)}`);
+                lines.push(`    ${green(`+ ${truncate(finding.expected ?? "")}`)}`);
+            }
+            continue;
+        }
+        lines.push(`  ${where}  ${finding.status}  ${finding.reason}  ${finding.message}`);
+    }
+    lines.push(headline);
+    if (payload.mode === "dry-run" && payload.drift) {
+        lines.push("(dry run — no files modified)");
+    }
+    if (payload.mode === "check" && payload.drift) {
+        lines.push("Run with --dry-run to see the full plan, or --write to refresh.");
+    }
+    if (payload.conflicts.length) {
+        lines.push("", bold("Conflicts (nothing will be written):"));
+        for (const conflict of payload.conflicts) {
+            lines.push(`  ${conflict.file}  ${conflict.kind}  ${conflict.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function checkSnippetsAction(inputs, opts) {
+    const format = resolveFormat(opts);
+    const mode = resolveMode(opts);
+    // --write has no path to write stdin back to, and a snippet link is only
+    // meaningful relative to a document that has a location on disk.
+    if (inputs.includes("-"))
+        throw new Error("md check-snippets does not accept stdin");
+    const files = resolveMarkdownInputs(inputs, { include: opts.include, exclude: opts.exclude });
+    // Two roots, deliberately. Source reads are bounded by the workspace, because
+    // a document under docs/ legitimately points at ../src; writes are bounded by
+    // the md fix containment root, which for `md check-snippets docs` is docs/
+    // itself and would reject every real source.
+    const readRoot = runtime().config.root;
+    const writeRoot = containmentRoot(files, runtime().config);
+    const read = createSourceReader(readRoot);
+    const snapshots = new Map();
+    const perFile = [];
+    const edits = [];
+    for (const file of files) {
+        const taken = snapshot(file);
+        snapshots.set(file, taken);
+        const document = runtime().workspace.document(file);
+        // Offsets address the snapshot's bytes; the cached tree is only safe to
+        // reuse when it was parsed from exactly those bytes.
+        const blocks = document.content === taken.content
+            ? extractCodeBlocks(document.tree)
+            : extractCodeBlocks(parseMarkdown(taken.content));
+        const results = synchronizeSnippets(taken.content, blocks, { file, root: readRoot, read });
+        if (!results.length)
+            continue;
+        perFile.push({ file, results });
+        edits.push(...snippetEdits(file, taken.content, results));
+    }
+    const plan = mode === "write"
+        ? buildPlan(writeRoot, edits, snapshots)
+        : { root: writeRoot, files: [], conflicts: [] };
+    let applied;
+    if (mode === "write" && !plan.conflicts.length) {
+        // applyPlan re-fingerprints its edit targets but knows nothing about the
+        // sources the replacements were read from, so a source edited mid-run
+        // would otherwise land already stale.
+        for (const { results } of perFile) {
+            for (const result of results) {
+                if (result.status !== "stale" || !result.write)
+                    continue;
+                const current = fingerprint(result.source);
+                if (current.size !== result.sourceFingerprint.size ||
+                    current.mtimeMs !== result.sourceFingerprint.mtimeMs) {
+                    throw new Error(`Aborted: ${result.source} changed after the plan was built`);
+                }
+            }
+        }
+        const result = applyPlan(plan, { invalidate: (file) => runtime().workspace.invalidate(file) });
+        applied = new Set(result.files.filter((entry) => entry.changed).map((entry) => entry.file));
+    }
+    const findings = [];
+    let linked = 0;
+    let current = 0;
+    let drift = 0;
+    let unresolved = 0;
+    let malformed = 0;
+    let unwritable = 0;
+    for (const entry of perFile) {
+        for (const result of entry.results) {
+            linked++;
+            if (result.status === "current")
+                current++;
+            else if (result.status === "unresolved")
+                unresolved++;
+            else if (result.status === "malformed")
+                malformed++;
+            else {
+                drift++;
+                if (!result.write && mode !== "check")
+                    unwritable++;
+            }
+            if (result.status === "current" && !opts.includeOk)
+                continue;
+            findings.push(toFinding(entry.file, result, mode, applied, opts));
+        }
+    }
+    const payload = {
+        mode,
+        filesScanned: files.length,
+        linked,
+        current,
+        drift,
+        unresolved,
+        malformed,
+        unwritable,
+        applied: applied?.size ?? 0,
+        findings,
+        conflicts: plan.conflicts.map((conflict) => ({
+            ...conflict,
+            file: outputPath(conflict.file, opts),
+        })),
+    };
+    // Unlike `md fix`, a finding with no available fix fails every mode. This
+    // command's job is checking, so a snippet naming a deleted file or a deleted
+    // region is the most severe drift it can report — exiting 0 would let CI pass
+    // over provably wrong documentation. Drift itself only fails the modes that
+    // are not about to correct it.
+    const actionable = payload.conflicts.length > 0 ||
+        payload.malformed + payload.unresolved + payload.unwritable > 0 ||
+        (mode !== "write" && payload.drift > 0);
+    const rendered = format === "json"
+        ? jsonPayload("md check-snippets", payload, opts, {
+            exitCode: actionable ? 2 : 0,
+            summary: {
+                linked: payload.linked,
+                drift: payload.drift,
+                unresolved: payload.unresolved + payload.malformed,
+            },
+        }).trimEnd()
+        : renderText(payload, format === "human");
+    (actionable ? process.stderr : process.stdout).write(rendered + "\n");
+    if (actionable)
+        terminate(2);
+}
+//# sourceMappingURL=check-snippets.js.map