@descent-vtt/spec-graph 0.2.0

package/dist/baseline.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Accepted debt, and the ratchet that keeps it from growing.
+ *
+ * A linter introduced to a repository that predates it reports everything at
+ * once. Fifty findings on day one is not a report, it is a decision to be
+ * ignored: the team cannot stop to fix them, so they turn the tool off, or they
+ * turn the rules off and the next specification rots unwatched.
+ *
+ * A baseline is the third answer. It records what was already wrong on the day
+ * the tool arrived, and reports only what happened since. Debt can be paid down
+ * whenever there is room, and in the meantime nothing new gets in.
+ *
+ * The whole module is pure. Reading and writing the file is the CLI's job, for
+ * the same reason extraction never touches a disk.
+ */
+import type { SpecGraph } from './graph.js';
+import type { Diagnostic, RuleId } from './types.js';
+/** The current file format. Bumped only for a change old files cannot survive. */
+export declare const BASELINE_VERSION = 1;
+/** One class of accepted finding, and how many of it there were. */
+export interface BaselineEntry {
+    readonly rule: RuleId;
+    /** The specification the finding is about, not the file it was found in. */
+    readonly document: string;
+    /** What within it: a citation target, or the document at the other end. */
+    readonly subject: string;
+    readonly count: number;
+}
+export interface Baseline {
+    readonly version: number;
+    readonly findings: readonly BaselineEntry[];
+}
+export declare const EMPTY_BASELINE: Baseline;
+/**
+ * What makes two findings the same finding.
+ *
+ * Not the line. A baseline keyed on line numbers is invalidated by any edit
+ * above it, which turns every unrelated pull request into a wall of findings
+ * nobody introduced. Not the message either: rewording a diagnostic would
+ * silently expire every baseline in the world.
+ *
+ * What survives is the pair the finding is actually about - which specification,
+ * and what within it. Both are ids that outlive a file being renamed, a section
+ * being moved into its own file, or an obligation being reordered, because that
+ * is exactly what identifiers were made stable for (ADR-0009).
+ *
+ * The cost is deliberate coarseness: two broken links from one document to the
+ * same target are one entry with a count of two. Paying that buys a baseline
+ * that does not lie the first time somebody reformats a paragraph.
+ */
+export declare function fingerprintOf(graph: SpecGraph, diagnostic: Diagnostic): {
+    document: string;
+    subject: string;
+};
+/**
+ * Renders a baseline for the findings given.
+ *
+ * Sorted by rule, then document, then subject, and written with two-space
+ * indentation: the file lands in a repository and is read in diffs, so its byte
+ * order has to be a function of its content and nothing else. No timestamp, for
+ * the same reason - a generated date makes every re-record a change even when
+ * nothing changed.
+ */
+export declare function formatBaseline(graph: SpecGraph, diagnostics: readonly Diagnostic[]): string;
+export interface ParsedBaseline {
+    readonly baseline: Baseline;
+    /** Reported, never silently dropped. A baseline nobody can read is worse
+     * than none: it suppresses findings the reader cannot account for. */
+    readonly problems: readonly string[];
+}
+/** Parses a baseline file. Never throws; an unusable file yields an empty one. */
+export declare function parseBaseline(raw: string, source: string): ParsedBaseline;
+export interface BaselineOutcome {
+    /** Findings the baseline does not account for. These are the report. */
+    readonly kept: readonly Diagnostic[];
+    /** How many were accounted for. Reported as a number, not as a list. */
+    readonly suppressed: number;
+    /**
+     * Entries whose debt has been paid, wholly or partly.
+     *
+     * The ratchet: once a repository is clean of something, saying so in the file
+     * stops it coming back unnoticed.
+     */
+    readonly stale: readonly BaselineEntry[];
+}
+/**
+ * Removes the findings a baseline accounts for.
+ *
+ * Where a baseline allows two of something and three exist, one is reported.
+ * Which one is not a meaningful question - they share a fingerprint - so the
+ * findings are taken in report order and the surplus is what is left.
+ */
+export declare function applyBaseline(graph: SpecGraph, diagnostics: readonly Diagnostic[], baseline: Baseline): BaselineOutcome;

package/dist/baseline.js

@@ -0,0 +1,187 @@
+/**
+ * Accepted debt, and the ratchet that keeps it from growing.
+ *
+ * A linter introduced to a repository that predates it reports everything at
+ * once. Fifty findings on day one is not a report, it is a decision to be
+ * ignored: the team cannot stop to fix them, so they turn the tool off, or they
+ * turn the rules off and the next specification rots unwatched.
+ *
+ * A baseline is the third answer. It records what was already wrong on the day
+ * the tool arrived, and reports only what happened since. Debt can be paid down
+ * whenever there is room, and in the meantime nothing new gets in.
+ *
+ * The whole module is pure. Reading and writing the file is the CLI's job, for
+ * the same reason extraction never touches a disk.
+ */
+import { RULE_IDS } from './rules.js';
+/** The current file format. Bumped only for a change old files cannot survive. */
+export const BASELINE_VERSION = 1;
+export const EMPTY_BASELINE = Object.freeze({ version: BASELINE_VERSION, findings: [] });
+/**
+ * What makes two findings the same finding.
+ *
+ * Not the line. A baseline keyed on line numbers is invalidated by any edit
+ * above it, which turns every unrelated pull request into a wall of findings
+ * nobody introduced. Not the message either: rewording a diagnostic would
+ * silently expire every baseline in the world.
+ *
+ * What survives is the pair the finding is actually about - which specification,
+ * and what within it. Both are ids that outlive a file being renamed, a section
+ * being moved into its own file, or an obligation being reordered, because that
+ * is exactly what identifiers were made stable for (ADR-0009).
+ *
+ * The cost is deliberate coarseness: two broken links from one document to the
+ * same target are one entry with a count of two. Paying that buys a baseline
+ * that does not lie the first time somebody reformats a paragraph.
+ */
+export function fingerprintOf(graph, diagnostic) {
+    const first = diagnostic.nodes[0] ?? '';
+    const document = graph.owningDocument(first)?.id ?? first;
+    if (diagnostic.target !== null)
+        return { document, subject: diagnostic.target };
+    const second = diagnostic.nodes[1];
+    const subject = second === undefined ? '' : (graph.owningDocument(second)?.id ?? second);
+    // A document-level rule lists its own items as the rest of `nodes`, so the
+    // other end resolves back to where it started. Saying so twice in the file
+    // would only invite a reader to look for a distinction that is not there.
+    return { document, subject: subject === document ? '' : subject };
+}
+function keyOf(rule, document, subject) {
+    // Tab-joined: the three parts are ids and targets, and a tab is the one
+    // character none of them can contain.
+    return `${rule}\t${document}\t${subject}`;
+}
+/** Counts findings by fingerprint. */
+function tally(graph, diagnostics) {
+    const out = new Map();
+    for (const diagnostic of diagnostics) {
+        const { document, subject } = fingerprintOf(graph, diagnostic);
+        const key = keyOf(diagnostic.rule, document, subject);
+        const seen = out.get(key);
+        out.set(key, {
+            rule: diagnostic.rule,
+            document,
+            subject,
+            count: (seen?.count ?? 0) + 1,
+        });
+    }
+    return out;
+}
+/**
+ * Renders a baseline for the findings given.
+ *
+ * Sorted by rule, then document, then subject, and written with two-space
+ * indentation: the file lands in a repository and is read in diffs, so its byte
+ * order has to be a function of its content and nothing else. No timestamp, for
+ * the same reason - a generated date makes every re-record a change even when
+ * nothing changed.
+ */
+export function formatBaseline(graph, diagnostics) {
+    const findings = [...tally(graph, diagnostics).values()].sort(compareEntries);
+    return `${JSON.stringify({ version: BASELINE_VERSION, findings }, null, 2)}\n`;
+}
+function compareEntries(a, b) {
+    if (a.rule !== b.rule)
+        return a.rule < b.rule ? -1 : 1;
+    if (a.document !== b.document)
+        return a.document < b.document ? -1 : 1;
+    if (a.subject !== b.subject)
+        return a.subject < b.subject ? -1 : 1;
+    return 0;
+}
+/** Parses a baseline file. Never throws; an unusable file yields an empty one. */
+export function parseBaseline(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+    }
+    catch (error) {
+        return { baseline: EMPTY_BASELINE, problems: [`${source} is not valid JSON: ${error.message}`] };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { baseline: EMPTY_BASELINE, problems: [`${source} must contain a JSON object`] };
+    }
+    const record = parsed;
+    const problems = [];
+    if (record['version'] !== BASELINE_VERSION) {
+        return {
+            baseline: EMPTY_BASELINE,
+            problems: [`${source} is version ${String(record['version'])}, and this build reads version ${BASELINE_VERSION}`],
+        };
+    }
+    const rows = record['findings'];
+    if (!Array.isArray(rows)) {
+        return { baseline: EMPTY_BASELINE, problems: [`${source}: "findings" must be an array`] };
+    }
+    const findings = [];
+    for (const [index, row] of rows.entries()) {
+        const entry = readEntry(row, `${source}: findings[${index}]`, problems);
+        if (entry !== null)
+            findings.push(entry);
+    }
+    return { baseline: { version: BASELINE_VERSION, findings }, problems };
+}
+function readEntry(row, where, problems) {
+    if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+        problems.push(`${where} must be an object`);
+        return null;
+    }
+    const fields = row;
+    const rule = fields['rule'];
+    if (typeof rule !== 'string' || !RULE_IDS.includes(rule)) {
+        problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);
+        return null;
+    }
+    const document = fields['document'];
+    const subject = fields['subject'] ?? '';
+    const count = fields['count'] ?? 1;
+    if (typeof document !== 'string' || typeof subject !== 'string') {
+        problems.push(`${where}: "document" and "subject" must be strings`);
+        return null;
+    }
+    if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
+        problems.push(`${where}: "count" must be a whole number of at least 1`);
+        return null;
+    }
+    return { rule: rule, document, subject, count };
+}
+/**
+ * Removes the findings a baseline accounts for.
+ *
+ * Where a baseline allows two of something and three exist, one is reported.
+ * Which one is not a meaningful question - they share a fingerprint - so the
+ * findings are taken in report order and the surplus is what is left.
+ */
+export function applyBaseline(graph, diagnostics, baseline) {
+    const budget = new Map();
+    for (const entry of baseline.findings) {
+        const key = keyOf(entry.rule, entry.document, entry.subject);
+        budget.set(key, (budget.get(key) ?? 0) + entry.count);
+    }
+    const kept = [];
+    let suppressed = 0;
+    for (const diagnostic of diagnostics) {
+        const { document, subject } = fingerprintOf(graph, diagnostic);
+        const key = keyOf(diagnostic.rule, document, subject);
+        const left = budget.get(key) ?? 0;
+        if (left <= 0) {
+            kept.push(diagnostic);
+            continue;
+        }
+        budget.set(key, left - 1);
+        suppressed += 1;
+    }
+    const stale = [];
+    for (const entry of baseline.findings) {
+        const key = keyOf(entry.rule, entry.document, entry.subject);
+        const unspent = budget.get(key) ?? 0;
+        if (unspent <= 0)
+            continue;
+        stale.push({ ...entry, count: Math.min(unspent, entry.count) });
+        // An entry counted once; a duplicate key in a hand-edited file must not
+        // claim the same surplus twice.
+        budget.set(key, 0);
+    }
+    return { kept, suppressed, stale: stale.sort(compareEntries) };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAiBlC,MAAM,CAAC,MAAM,cAAc,GAAa,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;AAEnG;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAgB,EAAE,UAAsB;IACpE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,KAAK,CAAC;IAC1D,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;IAEhF,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,MAAM,CAAC,CAAC;IACzF,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,KAAK,CAAC,IAAY,EAAE,QAAgB,EAAE,OAAe;IAC5D,wEAAwE;IACxE,sCAAsC;IACtC,OAAO,GAAG,IAAI,KAAK,QAAQ,KAAK,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED,sCAAsC;AACtC,SAAS,KAAK,CAAC,KAAgB,EAAE,WAAkC;IACjE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC7C,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE;YACX,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,QAAQ;YACR,OAAO;YACP,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB,EAAE,WAAkC;IACjF,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC9E,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AACjF,CAAC;AAED,SAAS,cAAc,CAAC,CAAgB,EAAE,CAAgB;IACxD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC;AACX,CAAC;AASD,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,MAAc;IACvD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,uBAAwB,KAAe,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;IAC9G,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,6BAA6B,CAAC,EAAE,CAAC;IAC1F,CAAC;IAED,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,gBAAgB,EAAE,CAAC;QAC3C,OAAO;YACL,QAAQ,EAAE,cAAc;YACxB,QAAQ,EAAE,CAAC,GAAG,MAAM,eAAe,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,kCAAkC,gBAAgB,EAAE,CAAC;SAClH,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,+BAA+B,CAAC,EAAE,CAAC;IAC5F,CAAC;IAED,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,MAAM,cAAc,KAAK,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxE,IAAI,KAAK,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,SAAS,CAAC,GAAY,EAAE,KAAa,EAAE,QAAkB;IAChE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,oBAAoB,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAc,CAAC,EAAE,CAAC;QACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,kBAAkB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,4CAA4C,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACvE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,gDAAgD,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5D,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAgB,EAChB,WAAkC,EAClC,QAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7D,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QAC1B,UAAU,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,OAAO,IAAI,CAAC;YAAE,SAAS;QAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChE,wEAAwE;QACxE,gCAAgC;QAChC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;AACjE,CAAC","sourcesContent":["/**\n * Accepted debt, and the ratchet that keeps it from growing.\n *\n * A linter introduced to a repository that predates it reports everything at\n * once. Fifty findings on day one is not a report, it is a decision to be\n * ignored: the team cannot stop to fix them, so they turn the tool off, or they\n * turn the rules off and the next specification rots unwatched.\n *\n * A baseline is the third answer. It records what was already wrong on the day\n * the tool arrived, and reports only what happened since. Debt can be paid down\n * whenever there is room, and in the meantime nothing new gets in.\n *\n * The whole module is pure. Reading and writing the file is the CLI's job, for\n * the same reason extraction never touches a disk.\n */\n\nimport type { SpecGraph } from './graph.js';\nimport { RULE_IDS } from './rules.js';\nimport type { Diagnostic, RuleId } from './types.js';\n\n/** The current file format. Bumped only for a change old files cannot survive. */\nexport const BASELINE_VERSION = 1;\n\n/** One class of accepted finding, and how many of it there were. */\nexport interface BaselineEntry {\n  readonly rule: RuleId;\n  /** The specification the finding is about, not the file it was found in. */\n  readonly document: string;\n  /** What within it: a citation target, or the document at the other end. */\n  readonly subject: string;\n  readonly count: number;\n}\n\nexport interface Baseline {\n  readonly version: number;\n  readonly findings: readonly BaselineEntry[];\n}\n\nexport const EMPTY_BASELINE: Baseline = Object.freeze({ version: BASELINE_VERSION, findings: [] });\n\n/**\n * What makes two findings the same finding.\n *\n * Not the line. A baseline keyed on line numbers is invalidated by any edit\n * above it, which turns every unrelated pull request into a wall of findings\n * nobody introduced. Not the message either: rewording a diagnostic would\n * silently expire every baseline in the world.\n *\n * What survives is the pair the finding is actually about - which specification,\n * and what within it. Both are ids that outlive a file being renamed, a section\n * being moved into its own file, or an obligation being reordered, because that\n * is exactly what identifiers were made stable for (ADR-0009).\n *\n * The cost is deliberate coarseness: two broken links from one document to the\n * same target are one entry with a count of two. Paying that buys a baseline\n * that does not lie the first time somebody reformats a paragraph.\n */\nexport function fingerprintOf(graph: SpecGraph, diagnostic: Diagnostic): { document: string; subject: string } {\n  const first = diagnostic.nodes[0] ?? '';\n  const document = graph.owningDocument(first)?.id ?? first;\n  if (diagnostic.target !== null) return { document, subject: diagnostic.target };\n\n  const second = diagnostic.nodes[1];\n  const subject = second === undefined ? '' : (graph.owningDocument(second)?.id ?? second);\n  // A document-level rule lists its own items as the rest of `nodes`, so the\n  // other end resolves back to where it started. Saying so twice in the file\n  // would only invite a reader to look for a distinction that is not there.\n  return { document, subject: subject === document ? '' : subject };\n}\n\nfunction keyOf(rule: RuleId, document: string, subject: string): string {\n  // Tab-joined: the three parts are ids and targets, and a tab is the one\n  // character none of them can contain.\n  return `${rule}\\t${document}\\t${subject}`;\n}\n\n/** Counts findings by fingerprint. */\nfunction tally(graph: SpecGraph, diagnostics: readonly Diagnostic[]): Map<string, BaselineEntry> {\n  const out = new Map<string, BaselineEntry>();\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const seen = out.get(key);\n    out.set(key, {\n      rule: diagnostic.rule,\n      document,\n      subject,\n      count: (seen?.count ?? 0) + 1,\n    });\n  }\n  return out;\n}\n\n/**\n * Renders a baseline for the findings given.\n *\n * Sorted by rule, then document, then subject, and written with two-space\n * indentation: the file lands in a repository and is read in diffs, so its byte\n * order has to be a function of its content and nothing else. No timestamp, for\n * the same reason - a generated date makes every re-record a change even when\n * nothing changed.\n */\nexport function formatBaseline(graph: SpecGraph, diagnostics: readonly Diagnostic[]): string {\n  const findings = [...tally(graph, diagnostics).values()].sort(compareEntries);\n  return `${JSON.stringify({ version: BASELINE_VERSION, findings }, null, 2)}\\n`;\n}\n\nfunction compareEntries(a: BaselineEntry, b: BaselineEntry): number {\n  if (a.rule !== b.rule) return a.rule < b.rule ? -1 : 1;\n  if (a.document !== b.document) return a.document < b.document ? -1 : 1;\n  if (a.subject !== b.subject) return a.subject < b.subject ? -1 : 1;\n  return 0;\n}\n\nexport interface ParsedBaseline {\n  readonly baseline: Baseline;\n  /** Reported, never silently dropped. A baseline nobody can read is worse\n   * than none: it suppresses findings the reader cannot account for. */\n  readonly problems: readonly string[];\n}\n\n/** Parses a baseline file. Never throws; an unusable file yields an empty one. */\nexport function parseBaseline(raw: string, source: string): ParsedBaseline {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);\n  } catch (error) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} is not valid JSON: ${(error as Error).message}`] };\n  }\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} must contain a JSON object`] };\n  }\n\n  const record = parsed as Record<string, unknown>;\n  const problems: string[] = [];\n  if (record['version'] !== BASELINE_VERSION) {\n    return {\n      baseline: EMPTY_BASELINE,\n      problems: [`${source} is version ${String(record['version'])}, and this build reads version ${BASELINE_VERSION}`],\n    };\n  }\n\n  const rows = record['findings'];\n  if (!Array.isArray(rows)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source}: \"findings\" must be an array`] };\n  }\n\n  const findings: BaselineEntry[] = [];\n  for (const [index, row] of rows.entries()) {\n    const entry = readEntry(row, `${source}: findings[${index}]`, problems);\n    if (entry !== null) findings.push(entry);\n  }\n  return { baseline: { version: BASELINE_VERSION, findings }, problems };\n}\n\nfunction readEntry(row: unknown, where: string, problems: string[]): BaselineEntry | null {\n  if (typeof row !== 'object' || row === null || Array.isArray(row)) {\n    problems.push(`${where} must be an object`);\n    return null;\n  }\n  const fields = row as Record<string, unknown>;\n  const rule = fields['rule'];\n  if (typeof rule !== 'string' || !RULE_IDS.includes(rule as RuleId)) {\n    problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);\n    return null;\n  }\n  const document = fields['document'];\n  const subject = fields['subject'] ?? '';\n  const count = fields['count'] ?? 1;\n  if (typeof document !== 'string' || typeof subject !== 'string') {\n    problems.push(`${where}: \"document\" and \"subject\" must be strings`);\n    return null;\n  }\n  if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {\n    problems.push(`${where}: \"count\" must be a whole number of at least 1`);\n    return null;\n  }\n  return { rule: rule as RuleId, document, subject, count };\n}\n\nexport interface BaselineOutcome {\n  /** Findings the baseline does not account for. These are the report. */\n  readonly kept: readonly Diagnostic[];\n  /** How many were accounted for. Reported as a number, not as a list. */\n  readonly suppressed: number;\n  /**\n   * Entries whose debt has been paid, wholly or partly.\n   *\n   * The ratchet: once a repository is clean of something, saying so in the file\n   * stops it coming back unnoticed.\n   */\n  readonly stale: readonly BaselineEntry[];\n}\n\n/**\n * Removes the findings a baseline accounts for.\n *\n * Where a baseline allows two of something and three exist, one is reported.\n * Which one is not a meaningful question - they share a fingerprint - so the\n * findings are taken in report order and the surplus is what is left.\n */\nexport function applyBaseline(\n  graph: SpecGraph,\n  diagnostics: readonly Diagnostic[],\n  baseline: Baseline,\n): BaselineOutcome {\n  const budget = new Map<string, number>();\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    budget.set(key, (budget.get(key) ?? 0) + entry.count);\n  }\n\n  const kept: Diagnostic[] = [];\n  let suppressed = 0;\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const left = budget.get(key) ?? 0;\n    if (left <= 0) {\n      kept.push(diagnostic);\n      continue;\n    }\n    budget.set(key, left - 1);\n    suppressed += 1;\n  }\n\n  const stale: BaselineEntry[] = [];\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    const unspent = budget.get(key) ?? 0;\n    if (unspent <= 0) continue;\n    stale.push({ ...entry, count: Math.min(unspent, entry.count) });\n    // An entry counted once; a duplicate key in a hand-edited file must not\n    // claim the same surplus twice.\n    budget.set(key, 0);\n  }\n\n  return { kept, suppressed, stale: stale.sort(compareEntries) };\n}\n"]}

package/dist/cli.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The command line.
+ *
+ * Four verbs, because there are four questions worth asking of a specification
+ * graph: is it consistent (`check`), what does it contain (`query`), what does
+ * it look like (`graph`), and what will you check for me (`rules`).
+ *
+ * Exit codes are the contract with CI: `0` clean, `1` findings, `2` the tool
+ * itself could not run. A usage mistake never masquerades as a passing build.
+ */
+import { type GraphFormat } from './report.js';
+import type { RuleId, Severity } from './types.js';
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_ERROR = 2;
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+export type Command = 'check' | 'query' | 'graph' | 'rules';
+export interface CliOptions {
+    readonly command: Command;
+    readonly patterns: readonly string[];
+    readonly root: string;
+    readonly ignore: readonly string[];
+    /** Reference targets to leave unreported when they do not resolve. */
+    readonly ignoreReferences: readonly string[];
+    /** Families a bare identifier may name. Empty means any family in the corpus. */
+    readonly families: readonly string[];
+    /** Families that are never citations. */
+    readonly ignoreFamilies: readonly string[];
+    /** Files that log what was decided rather than deciding it. */
+    readonly historyPatterns: readonly string[];
+    /** Accepted-debt file to read. `null` means none was asked for. */
+    readonly baseline: string | null;
+    /** Where to write the current findings as accepted debt. */
+    readonly recordBaseline: string | null;
+    /** Skip the repository configuration file entirely. */
+    readonly noConfig: boolean;
+    readonly format: 'human' | 'json';
+    readonly graphFormat: GraphFormat;
+    readonly severities: Partial<Record<RuleId, Severity>>;
+    readonly color: boolean | null;
+    readonly ascii: boolean | null;
+    readonly verbose: boolean;
+    readonly documentsOnly: boolean;
+    readonly max: number;
+    readonly maxWarnings: number;
+    /** Raise every warning to an error. Explicit `--rule` overrides still win. */
+    readonly strict: boolean;
+    readonly selector: string | null;
+    readonly help: boolean;
+    readonly version: boolean;
+}
+export interface CliIO {
+    readonly argv?: readonly string[] | undefined;
+    readonly cwd?: string | undefined;
+    readonly stdout?: ((text: string) => void) | undefined;
+    readonly stderr?: ((text: string) => void) | undefined;
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    readonly isTTY?: boolean | undefined;
+}
+export declare const HELP = "spec-graph - turn Markdown specifications into a verifiable graph\n\nUSAGE\n  spec-graph [check] [patterns...] [options]\n  spec-graph query <selector> [patterns...] [options]\n  spec-graph graph [patterns...] [--graph-format dot|mermaid|json]\n  spec-graph rules [--explain]\n\nCOMMANDS\n  check     Validate the specification graph. The default.\n  query     Run a selector and print the matching paths.\n  graph     Export the graph for Graphviz, Mermaid, or another tool.\n  rules     List the built-in diagnostics.\n\nOPTIONS\n  --root <dir>            Directory the patterns resolve against (default: cwd)\n  --ignore <glob>         Skip paths. Repeatable.\n  --ignore-ref <glob>     Do not report these reference targets when they fail\n                          to resolve, for repositories where [[...]] tags a\n                          concept rather than naming a file. Repeatable.\n                          Suppresses findings only, never edges.\n  --family <name>         Families a bare identifier in prose may name. When\n                          given, everything else stays prose. Repeatable.\n  --ignore-family <name>  Families that are never citations - RFC when the repo\n                          cites RFC 2119 and keeps its own RFCs. Repeatable.\n  --history <glob>        Files that log what was decided rather than deciding\n                          it - journals, changelogs, minutes. Their links are\n                          still checked; their obligations are not. Repeatable.\n  --baseline <file>       Accept the findings recorded in this file and report\n                          only what is new since. Missing file = accept nothing.\n  --record-baseline <f>   Write today's findings to this file as accepted debt,\n                          and exit 0 without judging them.\n  --no-config             Ignore .spec-graph.json and the package.json key.\n  --format human|json     Report format (default: human)\n  --graph-format <fmt>    dot, mermaid or json (default: dot)\n  --documents-only        Leave items out of the exported graph\n  --rule <id>=<severity>  Override one rule: error, warn, info or off. Repeatable.\n  --max <n>               Show at most n findings (0 = no limit)\n  --max-warnings <n>      Fail when warnings exceed n (default: no limit)\n  --strict                Raise every warning to an error. An explicit --rule\n                          still wins, so --strict --rule x=warn exempts x.\n  --color / --no-color    Force colour on or off\n  --ascii                 Use ASCII glyphs only\n  --verbose               Include parse problems and per-file detail\n  -h, --help              Show this help\n  -v, --version           Show the version\n\nSELECTORS\n  A selector is a path through the graph.\n\n    item[openness=open] -delegates-to-> document[phase=retired]\n    document[phase=active] -assumes-> document[phase=retired]\n    document =supersedes=> document\n    *[path^=docs/adr] -contains-> item[state=accepted-debt]\n\n  Node types:  document, item, * (any)\n  Attributes:  id, kind, title, path, file, line, phase, status, receptivity,\n               alias, document, state (or disposition), openness, section,\n               text, body, evidence, conflicted, fm.<front-matter-key>\n  Operators:   = != ^= $= *= ~=   and [attr] for \"is present\"\n  Relations:   -kind->  <-kind-   =kind=>  <=kind=   (= forms are transitive)\n\nEXIT CODES\n  0  clean\n  1  findings at error severity (or over --max-warnings)\n  2  the tool could not run\n\nCONFIGURATION\n  Anything repeated on every run belongs in the repository rather than in the\n  command. spec-graph reads the first of these that exists:\n\n    .spec-graph.json, spec-graph.config.json, or a \"spec-graph\" key in\n    package.json\n\n    { \"patterns\": [\"docs/**/*.md\"],\n      \"ignoreReferences\": [\"trap *\"],\n      \"ignoreFamilies\": [\"RFC\"],\n      \"historyPatterns\": [\"**/JOURNAL_*.md\", \"archive/**\"],\n      \"baseline\": \".spec-graph-baseline.json\",\n      \"severities\": { \"self-reference\": \"off\" },\n      \"strict\": true }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it.\n\nADOPTING THIS ON AN OLD REPOSITORY\n  Record what is already wrong, then report only what happens next:\n\n    spec-graph check --record-baseline .spec-graph-baseline.json\n    git add .spec-graph-baseline.json\n\n  The file is keyed by specification and citation, not by line number, so it\n  survives edits, moves and renames. Findings that stop occurring are reported\n  so the file can be tightened; nothing new gets in.\n\nEXAMPLES\n  spec-graph \"docs/**/*.md\"\n  spec-graph check --rule self-reference=off --format json\n  spec-graph query 'item[openness=open] -delegates-to-> document[phase=retired]'\n  spec-graph check --ignore-ref \"trap *\"    # [[trap 55]] tags a concept, not a file\n  spec-graph graph --documents-only --graph-format mermaid > graph.mmd\n  spec-graph check --history \"**/JOURNAL_*.md\"   # a log is not a specification\n  spec-graph check --baseline .spec-graph-baseline.json\n";
+/** Parses argv into options. Throws {@link UsageError} on anything malformed. */
+export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
+/** Runs the CLI and returns the process exit code. Never throws. */
+export declare function main(io?: CliIO): Promise<number>;