@cairn-tool/cairn 2.0.0

package/dist/fix/registry.js

@@ -0,0 +1,28 @@
+import { markdownlintFixer } from "./markdownlint-fixer.js";
+import { relativeLinksFixer } from "./relative-links-fixer.js";
+import { snippetsFixer } from "./snippets-fixer.js";
+import { tocFixer } from "./toc-fixer.js";
+export const FIXERS = [
+    markdownlintFixer,
+    relativeLinksFixer,
+    tocFixer,
+    snippetsFixer,
+];
+/**
+ * Resolves `--rule` names, defaulting to every offline default fixer.
+ *
+ * An unknown name is a usage error rather than a silent no-op, so
+ * `md fix --rule typo --check` can never exit 0 and look like a pass.
+ */
+export function selectFixers(names) {
+    if (!names.length)
+        return FIXERS.filter((fixer) => !fixer.network && fixer.default);
+    const available = FIXERS.map((fixer) => fixer.name).join(", ");
+    return names.map((name) => {
+        const fixer = FIXERS.find((candidate) => candidate.name === name);
+        if (!fixer)
+            throw new Error(`Unknown rule: ${name}. Available rules: ${available}`);
+        return fixer;
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/fix/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/fix/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAyC1C,MAAM,CAAC,MAAM,MAAM,GAAqB;IACtC,iBAAiB;IACjB,kBAAkB;IAClB,QAAQ;IACR,aAAa;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IACpF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAClE,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,sBAAsB,SAAS,EAAE,CAAC,CAAC;QACpF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/fix/relative-links-fixer.d.ts

@@ -0,0 +1,21 @@
+import type { Fixer } from "./registry.js";
+/**
+ * Respells a local target so it resolves to exactly the same absolute path.
+ *
+ * Deliberately narrow, so the result is deterministic, idempotent, and causes
+ * no churn on a first run over an existing repository:
+ *
+ * - the path is recomputed in the original's own addressing mode, which is what
+ *   normalizes `a/../b.md`, `.//b.md`, and `docs/./api.md`;
+ * - a `./` prefix is preserved, never added and never removed — which of the
+ *   two spellings is "canonical" is a style opinion, and flipping it would
+ *   rewrite every link in a repository;
+ * - percent-encoding is preserved, never introduced. Encoding a link that
+ *   already renders is churn, and `encodeURI` double-encodes a literal `%`;
+ * - backslash separators become `/`, which is a real correctness fix;
+ * - query and fragment are preserved byte for byte.
+ *
+ * Returns undefined when the target is already canonical.
+ */
+export declare function canonicalLocalTarget(rawTarget: string, sourceFile: string, root: string): string | undefined;
+export declare const relativeLinksFixer: Fixer;

package/dist/fix/relative-links-fixer.js

@@ -0,0 +1,96 @@
+import path from "node:path";
+import { extractLinks, parseMarkdown } from "../markdown-ast.js";
+import { composeTarget, escapeTargetParens, resolveLocalPath, splitLocalTarget, targetStyle, } from "../link-target.js";
+/** A target naming another protocol, which is never a workspace path. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/**
+ * Respells a local target so it resolves to exactly the same absolute path.
+ *
+ * Deliberately narrow, so the result is deterministic, idempotent, and causes
+ * no churn on a first run over an existing repository:
+ *
+ * - the path is recomputed in the original's own addressing mode, which is what
+ *   normalizes `a/../b.md`, `.//b.md`, and `docs/./api.md`;
+ * - a `./` prefix is preserved, never added and never removed — which of the
+ *   two spellings is "canonical" is a style opinion, and flipping it would
+ *   rewrite every link in a repository;
+ * - percent-encoding is preserved, never introduced. Encoding a link that
+ *   already renders is churn, and `encodeURI` double-encodes a literal `%`;
+ * - backslash separators become `/`, which is a real correctness fix;
+ * - query and fragment are preserved byte for byte.
+ *
+ * Returns undefined when the target is already canonical.
+ */
+export function canonicalLocalTarget(rawTarget, sourceFile, root) {
+    const split = splitLocalTarget(rawTarget);
+    if (!split.path)
+        return undefined;
+    const style = targetStyle(rawTarget);
+    const forwardSlashed = split.path.split("\\").join("/");
+    const absolute = resolveLocalPath(sourceFile, forwardSlashed, root);
+    let nextPath;
+    if (style.rootRelative) {
+        nextPath = `/${path.relative(root, absolute).split(path.sep).join("/")}`;
+    }
+    else {
+        nextPath = path.relative(path.dirname(sourceFile), absolute).split(path.sep).join("/");
+        if (!nextPath)
+            nextPath = path.basename(absolute);
+    }
+    const next = composeTarget(nextPath, split, style);
+    return next === rawTarget ? undefined : next;
+}
+export const relativeLinksFixer = {
+    name: "relative-links",
+    description: "Normalize local link paths without changing what they point at",
+    network: false,
+    default: true,
+    plan(files, context) {
+        const edits = [];
+        for (const file of files) {
+            const snapshot = context.snapshot(file);
+            const content = snapshot.content;
+            // Several links can share one reference definition, so a destination span
+            // must only be edited once.
+            const seen = new Set();
+            for (const link of extractLinks(parseMarkdown(content), content)) {
+                if (link.isExternal || link.isAnchorOnly)
+                    continue;
+                if (link.destinationStart === undefined || link.destinationEnd === undefined)
+                    continue;
+                if (SCHEME.test(link.target))
+                    continue;
+                const raw = content.slice(link.destinationStart, link.destinationEnd);
+                // Where the source text and the parsed target diverge the offsets do not
+                // delimit a plain target and there is nothing safe to rewrite. Escaped
+                // parentheses are the one legitimate divergence: the span is still
+                // exactly the target, just written with backslashes, and the escaping is
+                // restored on output.
+                if (raw.replace(/\\([()])/g, "$1") !== link.target)
+                    continue;
+                const key = `${link.destinationStart}:${link.destinationEnd}`;
+                if (seen.has(key))
+                    continue;
+                const next = canonicalLocalTarget(link.target, file, context.root);
+                if (!next)
+                    continue;
+                seen.add(key);
+                edits.push({
+                    file,
+                    start: link.destinationStart,
+                    end: link.destinationEnd,
+                    expected: raw,
+                    replacement: escapeTargetParens(next, targetStyle(link.target, raw)),
+                    value: escapeTargetParens(next, targetStyle(link.target, raw)),
+                    diagnostic: {
+                        rule: "relative-links",
+                        line: link.destinationLine,
+                        message: `Link path is not canonical: ${raw} -> ${next}`,
+                    },
+                });
+            }
+        }
+        return Promise.resolve({ edits, unfixable: [] });
+    },
+};
+//# sourceMappingURL=relative-links-fixer.js.map

package/dist/fix/relative-links-fixer.js.map

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

package/dist/fix/snippets-fixer.d.ts

@@ -0,0 +1,2 @@
+import type { Fixer } from "./registry.js";
+export declare const snippetsFixer: Fixer;

package/dist/fix/snippets-fixer.js

@@ -0,0 +1,64 @@
+import { extractCodeBlocks, parseMarkdown } from "../markdown-ast.js";
+import { createSourceReader, snippetEdits, synchronizeSnippets } from "../snippets.js";
+import { runtime } from "../runtime.js";
+export const snippetsFixer = {
+    name: "snippets",
+    description: "Refresh fenced blocks that declare a source file and region",
+    network: false,
+    // Opt-in: `md fix --write` with no --rule runs every default fixer, and that
+    // command must not silently start reading arbitrary source files and
+    // rewriting documentation bodies from them. `md check-snippets` is the
+    // command that does this by default.
+    default: false,
+    plan(files, context) {
+        const edits = [];
+        const unfixable = [];
+        // Deliberately not `context.root`. That is the containment root for
+        // *writes*, which for `md fix docs` is docs/ and would reject every source
+        // under src/. Reads are bounded by the workspace instead.
+        const readRoot = runtime().config.root;
+        const read = createSourceReader(readRoot);
+        for (const file of files) {
+            const snapshot = context.snapshot(file);
+            const document = runtime().workspace.document(file);
+            // Offsets address the snapshot's bytes, so the cached tree is only safe
+            // to reuse when it was parsed from exactly those bytes.
+            const blocks = document.content === snapshot.content
+                ? extractCodeBlocks(document.tree)
+                : extractCodeBlocks(parseMarkdown(snapshot.content));
+            const results = synchronizeSnippets(snapshot.content, blocks, {
+                file,
+                root: readRoot,
+                read,
+            });
+            edits.push(...snippetEdits(file, snapshot.content, results));
+            for (const result of results) {
+                if (result.status === "current")
+                    continue;
+                if (result.status === "stale") {
+                    // A stale block with a write plan is handled by the edit; only one
+                    // the fence cannot accept is reported here.
+                    if (result.write)
+                        continue;
+                    unfixable.push({
+                        file,
+                        line: result.line,
+                        rule: "snippets",
+                        message: `Snippet is out of date with ${result.target}`,
+                        reason: result.unwritable.reason,
+                    });
+                    continue;
+                }
+                unfixable.push({
+                    file,
+                    line: result.line,
+                    rule: "snippets",
+                    message: result.message,
+                    reason: result.reason,
+                });
+            }
+        }
+        return Promise.resolve({ edits, unfixable });
+    },
+};
+//# sourceMappingURL=snippets-fixer.js.map

package/dist/fix/snippets-fixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets-fixer.js","sourceRoot":"","sources":["../../src/fix/snippets-fixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAIxC,MAAM,CAAC,MAAM,aAAa,GAAU;IAClC,IAAI,EAAE,UAAU;IAChB,WAAW,EAAE,6DAA6D;IAC1E,OAAO,EAAE,KAAK;IACd,6EAA6E;IAC7E,qEAAqE;IACrE,uEAAuE;IACvE,qCAAqC;IACrC,OAAO,EAAE,KAAK;IAEd,IAAI,CAAC,KAAwB,EAAE,OAAqB;QAClD,MAAM,KAAK,GAAkB,EAAE,CAAC;QAChC,MAAM,SAAS,GAAuB,EAAE,CAAC;QACzC,oEAAoE;QACpE,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;QACvC,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxC,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACpD,wEAAwE;YACxE,wDAAwD;YACxD,MAAM,MAAM,GACV,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO;gBACnC,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAClC,CAAC,CAAC,iBAAiB,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YAEzD,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE;gBAC5D,IAAI;gBACJ,IAAI,EAAE,QAAQ;gBACd,IAAI;aACL,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;YAE7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;oBAAE,SAAS;gBAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;oBAC9B,mEAAmE;oBACnE,4CAA4C;oBAC5C,IAAI,MAAM,CAAC,KAAK;wBAAE,SAAS;oBAC3B,SAAS,CAAC,IAAI,CAAC;wBACb,IAAI;wBACJ,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,IAAI,EAAE,UAAU;wBAChB,OAAO,EAAE,+BAA+B,MAAM,CAAC,MAAM,EAAE;wBACvD,MAAM,EAAE,MAAM,CAAC,UAAW,CAAC,MAAM;qBAClC,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBACD,SAAS,CAAC,IAAI,CAAC;oBACb,IAAI;oBACJ,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,IAAI,EAAE,UAAU;oBAChB,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,MAAM,EAAE,MAAM,CAAC,MAAM;iBACtB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC"}

package/dist/fix/toc-fixer.d.ts

@@ -0,0 +1,2 @@
+import type { Fixer } from "./registry.js";
+export declare const tocFixer: Fixer;

package/dist/fix/toc-fixer.js

@@ -0,0 +1,94 @@
+import { minimatch } from "minimatch";
+import path from "node:path";
+import { extractCodeBlocks } from "../markdown-ast.js";
+import { renderToc, synchronizeToc, TOC_START } from "../toc.js";
+import { runtime } from "../runtime.js";
+/** 1-based line containing `offset`. */
+function lineAt(content, offset) {
+    let line = 1;
+    for (let index = 0; index < offset && index < content.length; index++) {
+        if (content[index] === "\n")
+            line++;
+    }
+    return line;
+}
+/**
+ * Whether this document is one the project asks to keep a TOC in.
+ *
+ * With `toc.files` configured the globs decide, matching `md audit`. Without
+ * it, only documents that already carry a marker pair are considered — `md fix`
+ * never decides on its own that a document should gain a table of contents.
+ */
+function selected(file, content) {
+    const patterns = runtime().config.toc.files;
+    if (!patterns.length)
+        return content.includes(TOC_START);
+    const relative = path.relative(runtime().config.root, file).split(path.sep).join("/");
+    return patterns.some((pattern) => minimatch(relative, pattern, { dot: true, nonegate: true }));
+}
+export const tocFixer = {
+    name: "toc",
+    description: "Synchronize the generated block between TOC markers",
+    network: false,
+    default: true,
+    plan(files, context) {
+        const edits = [];
+        const unfixable = [];
+        for (const file of files) {
+            const snapshot = context.snapshot(file);
+            if (!selected(file, snapshot.content))
+                continue;
+            const document = runtime().workspace.document(file);
+            // Ranges address the snapshot's bytes while headings come from the
+            // workspace cache. If those ever disagree the offsets are meaningless,
+            // so the file is skipped rather than edited from stale structure.
+            if (document.content !== snapshot.content) {
+                unfixable.push({
+                    file,
+                    line: 1,
+                    rule: "toc",
+                    message: "Document changed while it was being planned",
+                    reason: "stale workspace cache",
+                });
+                continue;
+            }
+            const maxDepth = Math.min(6, Math.max(1, parseInt(context.toc.maxDepth, 10) || 6));
+            const minDepth = Math.min(6, Math.max(1, parseInt(context.toc.minDepth, 10) || 1));
+            const headings = document.headings.filter((heading) => heading.depth >= minDepth && heading.depth <= maxDepth);
+            const sync = synchronizeToc(snapshot.content, renderToc(headings, context.toc.ordered), extractCodeBlocks(document.tree));
+            // Inserting markers is an authoring decision, not a fix. A document whose
+            // only markers sit inside a fenced code sample lands here too, since
+            // synchronizeToc does not count those.
+            if (sync.status === "missing")
+                continue;
+            if (sync.status === "malformed") {
+                // A throw would let one bad document kill a whole-tree run.
+                unfixable.push({
+                    file,
+                    line: 1,
+                    rule: "toc",
+                    message: sync.message,
+                    reason: "malformed markers",
+                });
+                continue;
+            }
+            if (sync.status === "current")
+                continue;
+            edits.push({
+                file,
+                start: sync.range.start,
+                end: sync.range.end,
+                expected: snapshot.content.slice(sync.range.start, sync.range.end),
+                replacement: sync.interior,
+                value: sync.interior,
+                diagnostic: {
+                    rule: "toc",
+                    line: lineAt(snapshot.content, sync.range.start),
+                    message: "Generated TOC is stale",
+                },
+            });
+        }
+        return Promise.resolve({ edits, unfixable });
+    },
+};
+//# sourceMappingURL=toc-fixer.js.map

package/dist/fix/toc-fixer.js.map

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

package/dist/formats.d.ts

@@ -0,0 +1,22 @@
+import type { OutputFormat } from "./types.js";
+/** Every format the CLI can emit. */
+export declare const ALL_FORMATS: readonly OutputFormat[];
+/** Formats every command supports. */
+export declare const BASE_FORMATS: readonly OutputFormat[];
+/**
+ * `md` commands that additionally accept the automation formats. These emit
+ * `Issue` diagnostics, which are the only payload jsonl and sarif can represent.
+ */
+export declare const DIAGNOSTIC_FORMAT_COMMANDS: readonly string[];
+export declare function supportsDiagnosticFormats(mdCommand: string): boolean;
+/** Formats accepted by `md <mdCommand>`. */
+export declare function formatsFor(mdCommand: string): readonly OutputFormat[];
+/**
+ * `agent` subcommands that additionally accept SARIF.
+ *
+ * Deliberately not `ALL_FORMATS`: `jsonl`'s published `diagnostic-record`
+ * schema is the `Issue` shape, which an `AgentDiagnostic` does not fit.
+ */
+export declare const AGENT_SARIF_COMMANDS: readonly string[];
+/** Formats accepted by `agent <agentCommand>`. */
+export declare function agentFormatsFor(agentCommand: string): readonly OutputFormat[];

package/dist/formats.js

@@ -0,0 +1,34 @@
+/** Every format the CLI can emit. */
+export const ALL_FORMATS = ["llm", "human", "json", "jsonl", "sarif"];
+/** Formats every command supports. */
+export const BASE_FORMATS = ["llm", "human", "json"];
+/**
+ * `md` commands that additionally accept the automation formats. These emit
+ * `Issue` diagnostics, which are the only payload jsonl and sarif can represent.
+ */
+export const DIAGNOSTIC_FORMAT_COMMANDS = [
+    "lint",
+    "lint-dir",
+    "audit",
+    "validate-frontmatter",
+    "check-urls",
+];
+export function supportsDiagnosticFormats(mdCommand) {
+    return DIAGNOSTIC_FORMAT_COMMANDS.includes(mdCommand);
+}
+/** Formats accepted by `md <mdCommand>`. */
+export function formatsFor(mdCommand) {
+    return supportsDiagnosticFormats(mdCommand) ? ALL_FORMATS : BASE_FORMATS;
+}
+/**
+ * `agent` subcommands that additionally accept SARIF.
+ *
+ * Deliberately not `ALL_FORMATS`: `jsonl`'s published `diagnostic-record`
+ * schema is the `Issue` shape, which an `AgentDiagnostic` does not fit.
+ */
+export const AGENT_SARIF_COMMANDS = ["audit"];
+/** Formats accepted by `agent <agentCommand>`. */
+export function agentFormatsFor(agentCommand) {
+    return AGENT_SARIF_COMMANDS.includes(agentCommand) ? [...BASE_FORMATS, "sarif"] : BASE_FORMATS;
+}
+//# sourceMappingURL=formats.js.map

package/dist/formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAEA,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAE/F,sCAAsC;AACtC,MAAM,CAAC,MAAM,YAAY,GAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,MAAM;IACN,UAAU;IACV,OAAO;IACP,sBAAsB;IACtB,YAAY;CACb,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,OAAO,0BAA0B,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,yBAAyB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAsB,CAAC,OAAO,CAAC,CAAC;AAEjE,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,OAAO,oBAAoB,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;AACjG,CAAC"}

package/dist/formatters.d.ts

@@ -0,0 +1,11 @@
+import type { Issue, OutputFormat } from "./types.js";
+import { type DiagnosticSummary } from "./automation.js";
+/**
+ * Identifies the emitting command so `--envelope` can wrap the finding list.
+ * Omitted by callers that have no envelope option.
+ */
+export interface IssueContract {
+    command: string;
+    envelope?: boolean;
+}
+export declare function formatIssues(issues: Issue[], file: string, format: OutputFormat, summary?: Partial<DiagnosticSummary>, contract?: IssueContract): string;

package/dist/formatters.js

@@ -0,0 +1,48 @@
+import { formatDiagnostics } from "./automation.js";
+import { jsonPayload } from "./result.js";
+function formatLlm(issues, file) {
+    if (issues.length === 0)
+        return "";
+    const lines = [`${issues.length} issue(s) in ${file}:`];
+    for (const i of issues) {
+        lines.push(`  ${i.file}:${i.line} [${i.checker}] ${i.message}`);
+    }
+    return lines.join("\n");
+}
+function formatHuman(issues, file) {
+    if (issues.length === 0)
+        return "";
+    const lines = [`\n\x1b[1;31m✖ ${issues.length} issue(s) in ${file}\x1b[0m\n`];
+    for (const i of issues) {
+        const loc = `\x1b[36m${i.file}:${i.line}\x1b[0m`;
+        const rule = `\x1b[33m[${i.checker}]\x1b[0m`;
+        lines.push(`  ${loc} ${rule} ${i.message}`);
+    }
+    return lines.join("\n");
+}
+function formatJson(issues, contract) {
+    if (!contract)
+        return JSON.stringify(issues, null, 2);
+    return jsonPayload(contract.command, issues, contract, {
+        exitCode: issues.length ? 2 : 0,
+        summary: { findings: issues.length },
+    }).trimEnd();
+}
+export function formatIssues(issues, file, format, summary = {}, contract) {
+    const automated = formatDiagnostics(issues, format, {
+        files: summary.files ?? (new Set(issues.map((issue) => issue.file)).size || 1),
+        findings: summary.findings ?? issues.length,
+        ...summary,
+    });
+    if (automated !== undefined)
+        return automated;
+    switch (format) {
+        case "json":
+            return formatJson(issues, contract);
+        case "human":
+            return formatHuman(issues, file);
+        default:
+            return formatLlm(issues, file);
+    }
+}
+//# sourceMappingURL=formatters.js.map

package/dist/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,SAAS,SAAS,CAAC,MAAe,EAAE,IAAY;IAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,gBAAgB,IAAI,GAAG,CAAC,CAAC;IACxD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,WAAW,CAAC,MAAe,EAAE,IAAY;IAChD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,iBAAiB,MAAM,CAAC,MAAM,gBAAgB,IAAI,WAAW,CAAC,CAAC;IAC9E,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,SAAS,CAAC;QACjD,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,OAAO,UAAU,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAWD,SAAS,UAAU,CAAC,MAAe,EAAE,QAAwB;IAC3D,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtD,OAAO,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE;QACrD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;KACrC,CAAC,CAAC,OAAO,EAAE,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAe,EACf,IAAY,EACZ,MAAoB,EACpB,UAAsC,EAAE,EACxC,QAAwB;IAExB,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE;QAClD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QAC9E,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM;QAC3C,GAAG,OAAO;KACX,CAAC,CAAC;IACH,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC;YACE,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/frontmatter-validation.d.ts

@@ -0,0 +1,11 @@
+import type { FrontmatterRulesConfig } from "./config.js";
+import type { Issue } from "./types.js";
+import type { MarkdownDocument } from "./workspace.js";
+export declare class FrontmatterValidator {
+    readonly rules: FrontmatterRulesConfig;
+    private readonly schema?;
+    private readonly formatValidators;
+    constructor(rules: FrontmatterRulesConfig, schemaPath?: string);
+    validate(document: MarkdownDocument): Issue[];
+    validateMany(documents: MarkdownDocument[]): Issue[];
+}