@descent-vtt/spec-graph 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,108 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 0.3.0
+
+Found by writing a corpus designed to break the scanner and reading the edges it
+produced, which is the practice [CLAUDE.md](CLAUDE.md) asks for and the reason
+it is there. The mutation score could not have found any of it: a mutant is a
+change to code that exists, and a construct nobody parsed has no code to mutate.
+
+### Fixed
+
+**A reference-style link was read as a citation of its own label.**
+
+```md
+This depends on [ADR-0001][one].
+
+[one]: 0001-target.md
+```
+
+Every renderer reads that as a link to `0001-target.md`. spec-graph read it as a
+citation of the word `one`, which resolved to nothing - so those two lines
+produced a false `broken-reference` **and** no `depends-on` edge at all. The
+missing half is the worse one: an absent edge is invisible in a report that says
+everything is consistent.
+
+Definitions are now the destination table the labelled forms are read through. A
+label nothing defines is prose, because `[design][one]` renders verbatim when
+nothing says what `one` is. A broken one is reported at the definition, which is
+the line that fixes it, however many places use the label.
+
+**A `@spec-node` directive inside `<script>` or `<pre>` was honoured**, so a page
+explaining how to annotate a document could annotate itself. The four elements
+whose content is not Markdown are masked now, which is the CommonMark reading.
+`<div>` and `<details>` keep their content: a decision written inside a collapsed
+section is still a decision.
+
+**A document could take an id that was not a name.** `id=\"ADR-9\"` inside a
+JavaScript string parses its bare value as a lone backslash, and the document
+then collided with itself, reported a duplicate id against its own file,
+contained itself, and exported as invalid Mermaid. A declared id must carry a
+letter or a digit.
+
+**A percent-escaped destination resolved to nothing.**
+`[Design](docs/my%20design.md)` is what a renderer, a documentation site and
+GitHub's own copy-link all produce for a file with a space in its name. The
+escapes are read as a fallback, so a filename that genuinely contains one keeps
+resolving by the spelling it was written with, and a stray `100%` is left alone.
+
+See [ADR-0013](docs/adr/0013-the-scanner-hands-back-prose.md).
+
+**Front matter knew half of each relation.** `depends-on` was a key and
+`depended-on-by` was not, so a repository whose filing convention records
+dependents wrote the inverse spelling and got no edge, no warning, and a graph
+that reported itself as consistent. Every directional kind is spelled both ways
+now - twenty-five keys became fifty-six - and a test holds the invariant.
+`relates-to` is symmetric and exempt.
+
+Keys also fold on separators and case, so `depends-on`, `depends_on` and
+`dependsOn` are one key rather than the two that happened to be written out.
+See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
+
+**`--verbose --format json` printed human lines onto stdout beside the JSON.**
+
+### Added
+
+- **`unknown-relation-key`** (warn). A front-matter key one edit from a relation,
+  carrying something that could name a document, is reported rather than
+  ignored. Both halves of that gate matter: `deprecated: true` is one edit from
+  `deprecates` and a boolean is not a citation. It says what is true - *"the key
+  declares no relation"* - and offers the near spellings rather than asserting
+  one. See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
+- **`--ratchet`**, and `"ratchet": true` in the configuration. The other side of
+  a baseline: with it, a declared finding that no longer occurs fails the build,
+  named, with `--record-baseline` as the fix. Off by default, because
+  [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md) is right that failing a
+  build because somebody fixed something is a strange way to encourage them -
+  and on for a team that has decided its debt only moves one way, because a note
+  on a green build is a line that scrolls past.
+- **`--format sarif`**. SARIF 2.1.0, for `check`, so
+  `github/codeql-action/upload-sarif` can turn findings into annotations on the
+  diff with no integration on either side. The `partialFingerprints` are the
+  same rule/specification/citation identity a baseline is keyed on, so an
+  annotation survives a reformat. Deterministic and timestamp-free like every
+  other output here. See
+  [ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+
+### Not added
+
+**`--watch`.** A full run is 60 ms, so the loop is one line of shell in whatever
+the developer already uses. A resident process, a debounce timer and `fs.watch`
+semantics that differ on all three platforms would be the one part of this
+program that could not honour byte-determinism, inside a codebase whose whole
+test strategy rests on everything between the edges being a pure function of
+text. Reasoning in
+[ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+
+### Measured
+
+684 tests, and a mutation score of **79.69% over 8,126 mutants** - up from
+77.16% over 7,720. The guard stays at `break: 70`, because the same source
+measured twice on the same machine, with only test cases added between the runs,
+moved nine untouched files by more than a point each in both directions. See
+[ADR-0007](docs/adr/0007-mutation-testing.md).
+
 ## 0.2.3
 
 ### Fixed

package/README.md

@@ -78,6 +78,7 @@ npx @descent-vtt/spec-graph "docs/**/*.md"
 | `ambiguous-reference` | warn | A citation matching more than one document |
 | `unreciprocated-supersession` | warn | A retired document that never says what replaced it |
 | `state-conflict` | warn | An item whose two state signals disagree about whether work remains |
+| `unknown-relation-key` | warn | A front-matter key one edit from a relation, carrying what looks like a citation |
 | `self-reference` | info | A document delegating to, or depending on, itself |
 
 Override any of them:
@@ -266,6 +267,38 @@ still a relation in the graph no matter what you exclude — not even
 `--ignore-ref "*"` can delete one. See
 [ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
 
+#### A gap that is deliberate
+
+Real filing histories have holes: an ADR number reserved and then withdrawn, a
+document that was folded into another before it was ever committed. Something
+still cites it, and the citation is not a mistake.
+
+There are two mechanisms and the difference is what you are declaring.
+
+**The target is never going to exist** — `ADR-0006` was withdrawn before filing.
+That is a fact about the repository, so declare it once in
+`.spec-graph.json`:
+
+```json
+{ "ignoreReferences": ["ADR-0006"] }
+```
+
+Every citation of it stays quiet, wherever it is written, forever. A glob is
+available and rarely what you want here: `ADR-0006` names one target exactly.
+
+**This particular citation is accepted for now** — it should resolve, one day it
+will, and until then the build should not stop. That is debt, not a fact, and it
+belongs in the baseline, keyed to the one document and the one target:
+
+```json
+{ "rule": "broken-reference", "document": "ADR-0004", "subject": "docs/plans/x.md", "count": 1 }
+```
+
+The same citation from a different document is still reported, and `--ratchet`
+makes the entry disappear the day it is paid. Reach for the first when the
+absence is permanent, the second when it is temporary — and if you cannot say
+which, it is the second.
+
 ### Relations
 
 Relations are read from front matter, from link context, and from explicit
@@ -426,7 +459,54 @@ A baseline that expires when somebody reformats a paragraph is worse than none,
 so the entry survives edits, reordering, and the file being renamed — because
 `ADR-0004` is the decision's name, not its location. Repeats are counted rather
 than told apart, which is the deliberate cost of a key with no position in it.
-See [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+
+By default that line is a note and the build stays green: failing because
+somebody fixed something is a strange way to encourage them. But a note in CI
+is a line that scrolls past, and an exemption nobody strikes outlives the defect
+it was written for. A team that has decided its debt only moves one way turns on
+the other side of the ratchet:
+
+```bash
+spec-graph check --baseline .spec-graph-baseline.json --ratchet
+```
+
+Now an undeclared finding fails **and** a declared one that no longer occurs
+fails, each named, with `--record-baseline` as the fix — and the diff of that
+file is the record of what was paid off. See
+[ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+
+## In CI
+
+The exit code is the contract: `0` clean, `1` findings, `2` the tool could not
+run. That is all most pipelines need.
+
+For annotations on the diff rather than a line in a log, emit SARIF and hand it
+to the uploader that already exists:
+
+```yaml
+- run: npx spec-graph --format sarif > spec-graph.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: spec-graph.sarif
+```
+
+Findings land as comments on the changed lines, and they persist across commits
+without drifting, because the `partialFingerprints` spec-graph writes are the
+same identity a baseline is keyed on — the rule, the specification, and the
+citation, with no line number in it (ADR-0012).
+
+`--format json` is the other machine-readable output, and the one to parse if
+you are building something of your own: it carries the baseline note, the
+summary and the per-file detail that SARIF has nowhere to put.
+
+**There is no `--watch`.** A full run on this repository takes 60 ms, so the
+loop that would justify a resident process is one line of shell, and it belongs
+to whatever the developer already uses rather than to this tool:
+
+```bash
+npx spec-graph --format json | jq -r '.summary'
+```
 
 ## Configuration
 
@@ -441,6 +521,7 @@ command. spec-graph reads the first of `.spec-graph.json`,
   "ignoreFamilies": ["RFC"],
   "historyPatterns": ["**/JOURNAL_*.md"],
   "baseline": ".spec-graph-baseline.json",
+  "ratchet": true,
   "severities": { "self-reference": "off" },
   "strict": true
 }
@@ -493,8 +574,9 @@ spec-graph rules [--explain]         List the diagnostics.
 --history <glob>        Files that log decisions rather than making them
 --baseline <file>       Accept these findings; report only what is new
 --record-baseline <f>   Write today's findings as accepted debt, exit 0
+--ratchet               Also fail when a baseline entry no longer occurs
 --no-config             Ignore .spec-graph.json and the package.json key
---format human|json     Report format
+--format <fmt>          human | json | sarif
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -590,6 +672,9 @@ Twelve ADRs, which `spec-graph` validates on every CI run:
 - [ADR-0010 — Configuration belongs to the repository](docs/adr/0010-configuration-belongs-to-the-repository.md)
 - [ADR-0011 — A historical record is not a specification](docs/adr/0011-a-record-is-not-a-specification.md)
 - [ADR-0012 — A baseline is a ratchet, keyed on identity](docs/adr/0012-a-baseline-is-a-ratchet.md)
+- [ADR-0013 — When the scanner is unsure, it hands back prose](docs/adr/0013-the-scanner-hands-back-prose.md)
+- [ADR-0014 — A relation is spelled in both directions](docs/adr/0014-a-relation-is-spelled-both-ways.md)
+- [ADR-0015 — Feedback goes where the tools already look](docs/adr/0015-feedback-goes-where-the-tools-already-look.md)
 
 **Zero runtime dependencies.** Node 22+, native ESM, TypeScript strict with
 `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The Markdown

package/dist/cli.d.ts

@@ -34,9 +34,18 @@ export interface CliOptions {
     readonly baseline: string | null;
     /** Where to write the current findings as accepted debt. */
     readonly recordBaseline: string | null;
+    /**
+     * Fail when the baseline allows something that no longer happens.
+     *
+     * The other side of the ratchet, and off by default for the reason ADR-0012
+     * gives: failing a build because somebody fixed something is a strange way to
+     * encourage them. A team that has decided its debt only goes one way asks for
+     * it explicitly, and then a dead exemption cannot outlive the defect.
+     */
+    readonly ratchet: boolean;
     /** Skip the repository configuration file entirely. */
     readonly noConfig: boolean;
-    readonly format: 'human' | 'json';
+    readonly format: 'human' | 'json' | 'sarif';
     readonly graphFormat: GraphFormat;
     readonly severities: Partial<Record<RuleId, Severity>>;
     readonly color: boolean | null;
@@ -59,7 +68,7 @@ export interface CliIO {
     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";
+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  --ratchet               Also fail when a baseline entry no longer occurs, so\n                          a paid-off exemption cannot outlive the defect.\n  --no-config             Ignore .spec-graph.json and the package.json key.\n  --format <fmt>          human, json, or sarif - the interchange format\n                          GitHub code scanning and editors already read\n                          (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. */

package/dist/cli.js

@@ -12,7 +12,7 @@ import { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline } from './
 import { loadConfig } from './config.js';
 import { underRoot } from './glob.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.js';
-import { formatGraph, formatJson, formatReport, shouldUseAscii, shouldUseColor } from './report.js';
+import { formatGraph, formatJson, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
 import { DEFAULT_SEVERITIES, resolveStrict, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES } from './rules.js';
 import { formatRef } from './source.js';
 import { execute, parseQuery, QueryError, renderMatch } from './select.js';
@@ -57,8 +57,12 @@ OPTIONS
                           only what is new since. Missing file = accept nothing.
   --record-baseline <f>   Write today's findings to this file as accepted debt,
                           and exit 0 without judging them.
+  --ratchet               Also fail when a baseline entry no longer occurs, so
+                          a paid-off exemption cannot outlive the defect.
   --no-config             Ignore .spec-graph.json and the package.json key.
-  --format human|json     Report format (default: human)
+  --format <fmt>          human, json, or sarif - the interchange format
+                          GitHub code scanning and editors already read
+                          (default: human)
   --graph-format <fmt>    dot, mermaid or json (default: dot)
   --documents-only        Leave items out of the exported graph
   --rule <id>=<severity>  Override one rule: error, warn, info or off. Repeatable.
@@ -160,6 +164,7 @@ export function parseArgs(argv, cwd) {
     let maxWarnings = -1;
     let strict = false;
     let baseline = null;
+    let ratchet = false;
     let recordBaseline = null;
     let selector = null;
     let help = false;
@@ -210,6 +215,9 @@ export function parseArgs(argv, cwd) {
             case '--strict':
                 strict = true;
                 break;
+            case '--ratchet':
+                ratchet = true;
+                break;
             case '--explain':
                 verbose = true;
                 break;
@@ -250,8 +258,8 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--format': {
                 const value = next(arg, i);
-                if (value !== 'human' && value !== 'json') {
-                    throw new UsageError(`--format must be human or json, got "${value}"`);
+                if (value !== 'human' && value !== 'json' && value !== 'sarif') {
+                    throw new UsageError(`--format must be human, json or sarif, got "${value}"`);
                 }
                 format = value;
                 i += 1;
@@ -297,6 +305,12 @@ export function parseArgs(argv, cwd) {
                 throw new UsageError(`unknown option "${arg}"\n  run "spec-graph --help" to see the available options`);
         }
     }
+    // SARIF is a report about findings, and only `check` produces those. Falling
+    // back to JSON would hand a pipeline something its uploader rejects with a
+    // message about a schema rather than about the command that was run.
+    if (format === 'sarif' && command !== 'check' && !help && !version) {
+        throw new UsageError(`--format sarif reports findings, so it belongs to check, not to ${command}`);
+    }
     if (command === 'query' && selector === null && !help && !version) {
         throw new UsageError('query needs a selector, for example:\n  spec-graph query \'item[openness=open]\'');
     }
@@ -310,6 +324,7 @@ export function parseArgs(argv, cwd) {
         ignoreFamilies,
         historyPatterns,
         baseline,
+        ratchet,
         recordBaseline,
         noConfig,
         format,
@@ -433,7 +448,7 @@ export async function main(io = {}) {
         case 'query': {
             try {
                 const matches = execute(result.graph, parseQuery(options.selector));
-                out(renderMatches(matches, options.format, result.graph.nodes.size));
+                out(renderMatches(matches, options.format === 'json' ? 'json' : 'human', result.graph.nodes.size));
                 return matches.length > 0 ? EXIT_OK : EXIT_FAILED;
             }
             catch (error) {
@@ -463,6 +478,7 @@ export async function main(io = {}) {
                 return EXIT_OK;
             }
             const source = options.baseline ?? file.baseline ?? null;
+            const ratchet = options.ratchet || file.ratchet === true;
             let reported = result;
             let note;
             if (source !== null) {
@@ -471,18 +487,25 @@ export async function main(io = {}) {
                     err(`spec-graph: ${problem}\n`);
                 const outcome = applyBaseline(result.graph, result.diagnostics, held.baseline);
                 reported = withDiagnostics(result, outcome.kept);
-                note = { source, suppressed: outcome.suppressed, stale: outcome.stale.length };
-                if (options.verbose) {
+                note = { source, suppressed: outcome.suppressed, stale: outcome.stale.length, ratchet };
+                // Listed rather than counted when the run turns on them: a number is
+                // enough to know the file has slack, and not enough to strike it. Never
+                // in JSON, where the entries are already in the report and a stray line
+                // on stdout is the difference between parsing and not.
+                if (options.format === 'human' && (options.verbose || (ratchet && outcome.stale.length > 0))) {
                     for (const entry of outcome.stale) {
                         out(`  paid: ${entry.rule} ${entry.document}${entry.subject === '' ? '' : ` "${entry.subject}"`}\n`);
                     }
                 }
             }
+            const looseBaseline = note !== undefined && note.ratchet && note.stale > 0;
             const baselineNote = note === undefined ? {} : { baseline: note };
-            out(options.format === 'json'
-                ? formatJson(reported, { escalated, ...baselineNote })
-                : `${formatReport(reported, { color, ascii, verbose: options.verbose, max: options.max, escalated, ...baselineNote })}\n`);
-            if (!reported.ok)
+            out(options.format === 'sarif'
+                ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated })
+                : options.format === 'json'
+                    ? formatJson(reported, { escalated, ...baselineNote })
+                    : `${formatReport(reported, { color, ascii, verbose: options.verbose, max: options.max, escalated, ...baselineNote })}\n`);
+            if (!reported.ok || looseBaseline)
                 return EXIT_FAILED;
             if (options.maxWarnings >= 0 && reported.summary.warnings > options.maxWarnings)
                 return EXIT_FAILED;

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The command line.\n *\n * Four verbs, because there are four questions worth asking of a specification\n * graph: is it consistent (`check`), what does it contain (`query`), what does\n * it look like (`graph`), and what will you check for me (`rules`).\n *\n * Exit codes are the contract with CI: `0` clean, `1` findings, `2` the tool\n * itself could not run. A usage mistake never masquerades as a passing build.\n */\n\nimport { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline, type Baseline } from './baseline.js';\nimport { loadConfig, type SpecGraphConfig } from './config.js';\nimport { underRoot } from './glob.js';\nimport { analyse, DEFAULT_PATTERNS, withDiagnostics, type AnalyseOptions } from './runner.js';\nimport { formatGraph, formatJson, formatReport, shouldUseAscii, shouldUseColor, type GraphFormat } from './report.js';\nimport { DEFAULT_SEVERITIES, resolveStrict, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES } from './rules.js';\nimport { formatRef } from './source.js';\nimport { execute, parseQuery, QueryError, renderMatch, type Match } from './select.js';\nimport type { RuleId, Severity, SpecNode } from './types.js';\n\nexport const EXIT_OK = 0;\nexport const EXIT_FAILED = 1;\nexport const EXIT_ERROR = 2;\n\nexport class UsageError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UsageError';\n  }\n}\n\nexport type Command = 'check' | 'query' | 'graph' | 'rules';\n\nexport interface CliOptions {\n  readonly command: Command;\n  readonly patterns: readonly string[];\n  readonly root: string;\n  readonly ignore: readonly string[];\n  /** Reference targets to leave unreported when they do not resolve. */\n  readonly ignoreReferences: readonly string[];\n  /** Families a bare identifier may name. Empty means any family in the corpus. */\n  readonly families: readonly string[];\n  /** Families that are never citations. */\n  readonly ignoreFamilies: readonly string[];\n  /** Files that log what was decided rather than deciding it. */\n  readonly historyPatterns: readonly string[];\n  /** Accepted-debt file to read. `null` means none was asked for. */\n  readonly baseline: string | null;\n  /** Where to write the current findings as accepted debt. */\n  readonly recordBaseline: string | null;\n  /** Skip the repository configuration file entirely. */\n  readonly noConfig: boolean;\n  readonly format: 'human' | 'json';\n  readonly graphFormat: GraphFormat;\n  readonly severities: Partial<Record<RuleId, Severity>>;\n  readonly color: boolean | null;\n  readonly ascii: boolean | null;\n  readonly verbose: boolean;\n  readonly documentsOnly: boolean;\n  readonly max: number;\n  readonly maxWarnings: number;\n  /** Raise every warning to an error. Explicit `--rule` overrides still win. */\n  readonly strict: boolean;\n  readonly selector: string | null;\n  readonly help: boolean;\n  readonly version: boolean;\n}\n\nexport interface CliIO {\n  readonly argv?: readonly string[] | undefined;\n  readonly cwd?: string | undefined;\n  readonly stdout?: ((text: string) => void) | undefined;\n  readonly stderr?: ((text: string) => void) | undefined;\n  readonly env?: Readonly<Record<string, string | undefined>> | undefined;\n  readonly isTTY?: boolean | undefined;\n}\n\nexport 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`;\n\nconst SEVERITIES: readonly Severity[] = ['error', 'warn', 'info', 'off'];\n\n/** Parses argv into options. Throws {@link UsageError} on anything malformed. */\nexport function parseArgs(argv: readonly string[], cwd: string): CliOptions {\n  const args = [...argv];\n  let command: Command = 'check';\n\n  if (args.length > 0 && !((args[0] as string).startsWith('-'))) {\n    const first = args[0] as string;\n    if (first === 'check' || first === 'query' || first === 'graph' || first === 'rules') {\n      command = first;\n      args.shift();\n    }\n  }\n\n  const patterns: string[] = [];\n  const ignore: string[] = [];\n  const ignoreReferences: string[] = [];\n  const families: string[] = [];\n  const ignoreFamilies: string[] = [];\n  const historyPatterns: string[] = [];\n  let noConfig = false;\n  const severities: Partial<Record<RuleId, Severity>> = {};\n  let root = cwd;\n  let format: 'human' | 'json' = 'human';\n  let graphFormat: GraphFormat = 'dot';\n  let color: boolean | null = null;\n  let ascii: boolean | null = null;\n  let verbose = false;\n  let documentsOnly = false;\n  let max = 0;\n  let maxWarnings = -1;\n  let strict = false;\n  let baseline: string | null = null;\n  let recordBaseline: string | null = null;\n  let selector: string | null = null;\n  let help = false;\n  let version = false;\n\n  const next = (flag: string, index: number): string => {\n    const value = args[index + 1];\n    if (value === undefined) throw new UsageError(`${flag} needs a value`);\n    return value;\n  };\n\n  for (let i = 0; i < args.length; i += 1) {\n    const arg = args[i] as string;\n\n    if (arg === '--') {\n      patterns.push(...args.slice(i + 1));\n      break;\n    }\n\n    if (!arg.startsWith('-')) {\n      if (command === 'query' && selector === null) selector = arg;\n      else patterns.push(arg);\n      continue;\n    }\n\n    switch (arg) {\n      case '-h':\n      case '--help':\n        help = true;\n        break;\n      case '-v':\n      case '--version':\n        version = true;\n        break;\n      case '--verbose':\n        verbose = true;\n        break;\n      case '--color':\n        color = true;\n        break;\n      case '--no-color':\n        color = false;\n        break;\n      case '--ascii':\n        ascii = true;\n        break;\n      case '--documents-only':\n        documentsOnly = true;\n        break;\n      case '--strict':\n        strict = true;\n        break;\n      case '--explain':\n        verbose = true;\n        break;\n      case '--root':\n        root = next(arg, i);\n        i += 1;\n        break;\n      case '--ignore':\n        ignore.push(next(arg, i));\n        i += 1;\n        break;\n      case '--ignore-ref':\n        ignoreReferences.push(next(arg, i));\n        i += 1;\n        break;\n      case '--family':\n        families.push(next(arg, i));\n        i += 1;\n        break;\n      case '--ignore-family':\n        ignoreFamilies.push(next(arg, i));\n        i += 1;\n        break;\n      case '--history':\n        historyPatterns.push(next(arg, i));\n        i += 1;\n        break;\n      case '--baseline':\n        baseline = next(arg, i);\n        i += 1;\n        break;\n      case '--record-baseline':\n        recordBaseline = next(arg, i);\n        i += 1;\n        break;\n      case '--no-config':\n        noConfig = true;\n        break;\n      case '--format': {\n        const value = next(arg, i);\n        if (value !== 'human' && value !== 'json') {\n          throw new UsageError(`--format must be human or json, got \"${value}\"`);\n        }\n        format = value;\n        i += 1;\n        break;\n      }\n      case '--graph-format': {\n        const value = next(arg, i);\n        if (value !== 'dot' && value !== 'mermaid' && value !== 'json') {\n          throw new UsageError(`--graph-format must be dot, mermaid or json, got \"${value}\"`);\n        }\n        graphFormat = value;\n        i += 1;\n        break;\n      }\n      case '--rule': {\n        const value = next(arg, i);\n        const equals = value.indexOf('=');\n        if (equals === -1) throw new UsageError(`--rule expects <id>=<severity>, got \"${value}\"`);\n        const id = value.slice(0, equals) as RuleId;\n        const level = value.slice(equals + 1) as Severity;\n        if (!RULE_IDS.includes(id)) {\n          throw new UsageError(`unknown rule \"${id}\"\\n  known rules: ${RULE_IDS.join(', ')}`);\n        }\n        if (!SEVERITIES.includes(level)) {\n          throw new UsageError(`unknown severity \"${level}\", expected one of: ${SEVERITIES.join(', ')}`);\n        }\n        severities[id] = level;\n        i += 1;\n        break;\n      }\n      case '--max': {\n        max = parseCount(arg, next(arg, i));\n        i += 1;\n        break;\n      }\n      case '--max-warnings': {\n        maxWarnings = parseCount(arg, next(arg, i));\n        i += 1;\n        break;\n      }\n      default:\n        throw new UsageError(`unknown option \"${arg}\"\\n  run \"spec-graph --help\" to see the available options`);\n    }\n  }\n\n  if (command === 'query' && selector === null && !help && !version) {\n    throw new UsageError('query needs a selector, for example:\\n  spec-graph query \\'item[openness=open]\\'');\n  }\n\n  return {\n    command,\n    patterns,\n    root,\n    ignore,\n    ignoreReferences,\n    families,\n    ignoreFamilies,\n    historyPatterns,\n    baseline,\n    recordBaseline,\n    noConfig,\n    format,\n    graphFormat,\n    severities,\n    color,\n    ascii,\n    verbose,\n    documentsOnly,\n    max,\n    maxWarnings,\n    strict,\n    selector,\n    help,\n    version,\n  };\n}\n\nfunction count(n: number, word: string, many?: string): string {\n  return `${n} ${n === 1 ? word : (many ?? `${word}s`)}`;\n}\n\n/**\n * Reads a baseline file.\n *\n * A missing file is not an error: `--baseline` against a repository that has\n * not recorded one yet should report everything, which is exactly what an empty\n * baseline does.\n */\nasync function readBaseline(path: string, source: string): Promise<ReturnType<typeof parseBaseline>> {\n  let raw: string;\n  try {\n    const { readFile } = await import('node:fs/promises');\n    raw = await readFile(path, 'utf8');\n  } catch {\n    return { baseline: EMPTY_BASELINE, problems: [] };\n  }\n  return parseBaseline(raw, source);\n}\n\nfunction parseCount(flag: string, value: string): number {\n  const parsed = Number.parseInt(value, 10);\n  if (!Number.isFinite(parsed) || parsed < 0 || String(parsed) !== value.trim()) {\n    throw new UsageError(`${flag} expects a non-negative whole number, got \"${value}\"`);\n  }\n  return parsed;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Entry point                                                                */\n/* -------------------------------------------------------------------------- */\n\n/** Runs the CLI and returns the process exit code. Never throws. */\nexport async function main(io: CliIO = {}): Promise<number> {\n  const argv = io.argv ?? process.argv.slice(2);\n  const cwd = io.cwd ?? process.cwd();\n  const out = io.stdout ?? ((text) => process.stdout.write(text));\n  const err = io.stderr ?? ((text) => process.stderr.write(text));\n  const env = io.env ?? process.env;\n\n  let options: CliOptions;\n  try {\n    options = parseArgs(argv, cwd);\n  } catch (error) {\n    if (error instanceof UsageError) {\n      err(`spec-graph: ${error.message}\\n`);\n      return EXIT_ERROR;\n    }\n    throw error;\n  }\n\n  if (options.help) {\n    out(HELP);\n    return EXIT_OK;\n  }\n  if (options.version) {\n    out(`${await readVersion()}\\n`);\n    return EXIT_OK;\n  }\n\n  const color = options.color ?? shouldUseColor({ isTTY: io.isTTY, env });\n  const ascii = options.ascii ?? shouldUseAscii({ env });\n\n  if (options.command === 'rules') {\n    out(renderRules(options.verbose));\n    return EXIT_OK;\n  }\n\n  // Configuration is what is true of the repository; a flag is somebody\n  // overriding it for one run. So a flag always wins, and lists add rather than\n  // replace - a `--ignore-ref` on the command line is one more exclusion, not a\n  // decision to throw away the ones the repository already declared.\n  const loaded = options.noConfig ? { config: {} as SpecGraphConfig, source: null, problems: [] } : loadConfig(options.root);\n  for (const problem of loaded.problems) err(`spec-graph: ${problem}\\n`);\n  const file = loaded.config;\n\n  const patterns =\n    options.patterns.length > 0 ? options.patterns : (file.patterns ?? DEFAULT_PATTERNS);\n  const severityOverrides = { ...(file.severities ?? {}), ...options.severities };\n  const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false));\n\n  const analyseOptions: AnalyseOptions = {\n    root: options.root,\n    patterns,\n    ignore: [...(file.ignore ?? []), ...options.ignore],\n    ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],\n    families: [...(file.families ?? []), ...options.families],\n    ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],\n    historyPatterns: [...(file.historyPatterns ?? []), ...options.historyPatterns],\n    severities,\n    ...(file.maxRelated !== undefined ? { maxRelated: file.maxRelated } : {}),\n  };\n\n  if (options.verbose && loaded.source !== null) out(`configuration: ${loaded.source}\\n`);\n\n  let result;\n  try {\n    result = await analyse(analyseOptions);\n  } catch (error) {\n    err(`spec-graph: ${(error as Error).message}\\n`);\n    return EXIT_ERROR;\n  }\n\n  if (result.files.length === 0) {\n    err(\n      `spec-graph: no specifications matched ${\n        options.patterns.length > 0 ? options.patterns.map((p) => `\"${p}\"`).join(', ') : 'the default patterns'\n      }\\n  looked under ${options.root}\\n`,\n    );\n    return EXIT_ERROR;\n  }\n\n  switch (options.command) {\n    case 'graph':\n      out(formatGraph(result.graph, options.graphFormat, { documentsOnly: options.documentsOnly }));\n      return EXIT_OK;\n\n    case 'query': {\n      try {\n        const matches = execute(result.graph, parseQuery(options.selector as string));\n        out(renderMatches(matches, options.format, result.graph.nodes.size));\n        return matches.length > 0 ? EXIT_OK : EXIT_FAILED;\n      } catch (error) {\n        if (error instanceof QueryError) {\n          err(renderQueryError(options.selector as string, error));\n          return EXIT_ERROR;\n        }\n        throw error;\n      }\n    }\n\n    default: {\n      // Recording is not checking. It writes down what is wrong today so that\n      // tomorrow can be compared against it, and says nothing about whether\n      // today is acceptable - so it reports what it wrote and exits clean.\n      if (options.recordBaseline !== null) {\n        const text = formatBaseline(result.graph, result.diagnostics);\n        try {\n          const { writeFile } = await import('node:fs/promises');\n          await writeFile(underRoot(options.root, options.recordBaseline), text, 'utf8');\n        } catch (error) {\n          err(`spec-graph: cannot write ${options.recordBaseline}: ${(error as Error).message}\\n`);\n          return EXIT_ERROR;\n        }\n        const entries = (JSON.parse(text) as Baseline).findings.length;\n        out(\n          `recorded ${count(result.diagnostics.length, 'finding')} as ${count(entries, 'entry', 'entries')} in ${options.recordBaseline}\\n`,\n        );\n        return EXIT_OK;\n      }\n\n      const source = options.baseline ?? file.baseline ?? null;\n      let reported = result;\n      let note: { source: string; suppressed: number; stale: number } | undefined;\n      if (source !== null) {\n        const held = await readBaseline(underRoot(options.root, source), source);\n        for (const problem of held.problems) err(`spec-graph: ${problem}\\n`);\n        const outcome = applyBaseline(result.graph, result.diagnostics, held.baseline);\n        reported = withDiagnostics(result, outcome.kept);\n        note = { source, suppressed: outcome.suppressed, stale: outcome.stale.length };\n        if (options.verbose) {\n          for (const entry of outcome.stale) {\n            out(`  paid: ${entry.rule} ${entry.document}${entry.subject === '' ? '' : ` \"${entry.subject}\"`}\\n`);\n          }\n        }\n      }\n\n      const baselineNote = note === undefined ? {} : { baseline: note };\n      out(\n        options.format === 'json'\n          ? formatJson(reported, { escalated, ...baselineNote })\n          : `${formatReport(reported, { color, ascii, verbose: options.verbose, max: options.max, escalated, ...baselineNote })}\\n`,\n      );\n      if (!reported.ok) return EXIT_FAILED;\n      if (options.maxWarnings >= 0 && reported.summary.warnings > options.maxWarnings) return EXIT_FAILED;\n      return EXIT_OK;\n    }\n  }\n}\n\n/* -------------------------------------------------------------------------- */\n/* Rendering                                                                  */\n/* -------------------------------------------------------------------------- */\n\nfunction renderRules(explain: boolean): string {\n  const width = Math.max(...RULE_IDS.map((id) => id.length));\n  const lines: string[] = [];\n  for (const id of RULE_IDS) {\n    lines.push(`${id.padEnd(width)}  ${DEFAULT_SEVERITIES[id].padEnd(5)}  ${RULE_DESCRIPTIONS[id]}`);\n    const query = RULE_QUERIES[id];\n    if (explain && query) lines.push(`${' '.repeat(width)}         ${query}`);\n  }\n  return `${lines.join('\\n')}\\n`;\n}\n\nfunction renderMatches(matches: readonly Match[], format: 'human' | 'json', total: number): string {\n  if (format === 'json') {\n    return `${JSON.stringify(\n      {\n        version: 1,\n        count: matches.length,\n        matches: matches.map((match) => ({\n          nodes: match.nodes.map((node) => nodeSummary(node)),\n          edges: match.edges.map((edge) => ({\n            kind: edge.kind,\n            from: edge.from,\n            to: edge.to,\n            file: edge.declaredAt.file,\n            line: edge.declaredAt.span.start.line,\n          })),\n        })),\n      },\n      null,\n      2,\n    )}\\n`;\n  }\n\n  if (matches.length === 0) return `no matches (searched ${total} nodes)\\n`;\n\n  const lines: string[] = [];\n  for (const match of matches) {\n    const head = match.nodes[0] as SpecNode;\n    const tail = match.nodes[match.nodes.length - 1] as SpecNode;\n    lines.push(renderMatch(match));\n    lines.push(`  ${formatRef(head.at)}${match.nodes.length > 1 ? `  ${formatRef(tail.at)}` : ''}`);\n  }\n  lines.push(`${matches.length} ${matches.length === 1 ? 'match' : 'matches'}`);\n  return `${lines.join('\\n')}\\n`;\n}\n\nfunction nodeSummary(node: SpecNode): Record<string, unknown> {\n  return {\n    id: node.id,\n    kind: node.kind,\n    title: node.title,\n    file: node.at.file,\n    line: node.at.span.start.line,\n    ...(node.kind === 'document' ? { phase: node.phase } : { state: node.disposition, openness: node.openness }),\n  };\n}\n\n/** Points at the exact character of a selector that failed to parse. */\nfunction renderQueryError(selector: string, error: QueryError): string {\n  const caret = `${' '.repeat(Math.max(0, error.offset))}^`;\n  return `spec-graph: ${error.message}\\n  ${selector}\\n  ${caret}\\n`;\n}\n\nasync function readVersion(): Promise<string> {\n  try {\n    const { readFile } = await import('node:fs/promises');\n    const url = new URL('../package.json', import.meta.url);\n    const parsed: unknown = JSON.parse(await readFile(url, 'utf8'));\n    if (typeof parsed === 'object' && parsed !== null && 'version' in parsed) {\n      return String((parsed as { version: unknown }).version);\n    }\n  } catch {\n    // Fall through to the placeholder rather than failing `--version`.\n  }\n  return '0.0.0';\n}\n"]}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The command line.\n *\n * Four verbs, because there are four questions worth asking of a specification\n * graph: is it consistent (`check`), what does it contain (`query`), what does\n * it look like (`graph`), and what will you check for me (`rules`).\n *\n * Exit codes are the contract with CI: `0` clean, `1` findings, `2` the tool\n * itself could not run. A usage mistake never masquerades as a passing build.\n */\n\nimport { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline, type Baseline } from './baseline.js';\nimport { loadConfig, type SpecGraphConfig } from './config.js';\nimport { underRoot } from './glob.js';\nimport { analyse, DEFAULT_PATTERNS, withDiagnostics, type AnalyseOptions } from './runner.js';\nimport {\n  formatGraph,\n  formatJson,\n  formatReport,\n  formatSarif,\n  shouldUseAscii,\n  shouldUseColor,\n  type GraphFormat,\n} from './report.js';\nimport { DEFAULT_SEVERITIES, resolveStrict, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES } from './rules.js';\nimport { formatRef } from './source.js';\nimport { execute, parseQuery, QueryError, renderMatch, type Match } from './select.js';\nimport type { RuleId, Severity, SpecNode } from './types.js';\n\nexport const EXIT_OK = 0;\nexport const EXIT_FAILED = 1;\nexport const EXIT_ERROR = 2;\n\nexport class UsageError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UsageError';\n  }\n}\n\nexport type Command = 'check' | 'query' | 'graph' | 'rules';\n\nexport interface CliOptions {\n  readonly command: Command;\n  readonly patterns: readonly string[];\n  readonly root: string;\n  readonly ignore: readonly string[];\n  /** Reference targets to leave unreported when they do not resolve. */\n  readonly ignoreReferences: readonly string[];\n  /** Families a bare identifier may name. Empty means any family in the corpus. */\n  readonly families: readonly string[];\n  /** Families that are never citations. */\n  readonly ignoreFamilies: readonly string[];\n  /** Files that log what was decided rather than deciding it. */\n  readonly historyPatterns: readonly string[];\n  /** Accepted-debt file to read. `null` means none was asked for. */\n  readonly baseline: string | null;\n  /** Where to write the current findings as accepted debt. */\n  readonly recordBaseline: string | null;\n  /**\n   * Fail when the baseline allows something that no longer happens.\n   *\n   * The other side of the ratchet, and off by default for the reason ADR-0012\n   * gives: failing a build because somebody fixed something is a strange way to\n   * encourage them. A team that has decided its debt only goes one way asks for\n   * it explicitly, and then a dead exemption cannot outlive the defect.\n   */\n  readonly ratchet: boolean;\n  /** Skip the repository configuration file entirely. */\n  readonly noConfig: boolean;\n  readonly format: 'human' | 'json' | 'sarif';\n  readonly graphFormat: GraphFormat;\n  readonly severities: Partial<Record<RuleId, Severity>>;\n  readonly color: boolean | null;\n  readonly ascii: boolean | null;\n  readonly verbose: boolean;\n  readonly documentsOnly: boolean;\n  readonly max: number;\n  readonly maxWarnings: number;\n  /** Raise every warning to an error. Explicit `--rule` overrides still win. */\n  readonly strict: boolean;\n  readonly selector: string | null;\n  readonly help: boolean;\n  readonly version: boolean;\n}\n\nexport interface CliIO {\n  readonly argv?: readonly string[] | undefined;\n  readonly cwd?: string | undefined;\n  readonly stdout?: ((text: string) => void) | undefined;\n  readonly stderr?: ((text: string) => void) | undefined;\n  readonly env?: Readonly<Record<string, string | undefined>> | undefined;\n  readonly isTTY?: boolean | undefined;\n}\n\nexport 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  --ratchet               Also fail when a baseline entry no longer occurs, so\n                          a paid-off exemption cannot outlive the defect.\n  --no-config             Ignore .spec-graph.json and the package.json key.\n  --format <fmt>          human, json, or sarif - the interchange format\n                          GitHub code scanning and editors already read\n                          (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`;\n\nconst SEVERITIES: readonly Severity[] = ['error', 'warn', 'info', 'off'];\n\n/** Parses argv into options. Throws {@link UsageError} on anything malformed. */\nexport function parseArgs(argv: readonly string[], cwd: string): CliOptions {\n  const args = [...argv];\n  let command: Command = 'check';\n\n  if (args.length > 0 && !((args[0] as string).startsWith('-'))) {\n    const first = args[0] as string;\n    if (first === 'check' || first === 'query' || first === 'graph' || first === 'rules') {\n      command = first;\n      args.shift();\n    }\n  }\n\n  const patterns: string[] = [];\n  const ignore: string[] = [];\n  const ignoreReferences: string[] = [];\n  const families: string[] = [];\n  const ignoreFamilies: string[] = [];\n  const historyPatterns: string[] = [];\n  let noConfig = false;\n  const severities: Partial<Record<RuleId, Severity>> = {};\n  let root = cwd;\n  let format: 'human' | 'json' | 'sarif' = 'human';\n  let graphFormat: GraphFormat = 'dot';\n  let color: boolean | null = null;\n  let ascii: boolean | null = null;\n  let verbose = false;\n  let documentsOnly = false;\n  let max = 0;\n  let maxWarnings = -1;\n  let strict = false;\n  let baseline: string | null = null;\n  let ratchet = false;\n  let recordBaseline: string | null = null;\n  let selector: string | null = null;\n  let help = false;\n  let version = false;\n\n  const next = (flag: string, index: number): string => {\n    const value = args[index + 1];\n    if (value === undefined) throw new UsageError(`${flag} needs a value`);\n    return value;\n  };\n\n  for (let i = 0; i < args.length; i += 1) {\n    const arg = args[i] as string;\n\n    if (arg === '--') {\n      patterns.push(...args.slice(i + 1));\n      break;\n    }\n\n    if (!arg.startsWith('-')) {\n      if (command === 'query' && selector === null) selector = arg;\n      else patterns.push(arg);\n      continue;\n    }\n\n    switch (arg) {\n      case '-h':\n      case '--help':\n        help = true;\n        break;\n      case '-v':\n      case '--version':\n        version = true;\n        break;\n      case '--verbose':\n        verbose = true;\n        break;\n      case '--color':\n        color = true;\n        break;\n      case '--no-color':\n        color = false;\n        break;\n      case '--ascii':\n        ascii = true;\n        break;\n      case '--documents-only':\n        documentsOnly = true;\n        break;\n      case '--strict':\n        strict = true;\n        break;\n      case '--ratchet':\n        ratchet = true;\n        break;\n      case '--explain':\n        verbose = true;\n        break;\n      case '--root':\n        root = next(arg, i);\n        i += 1;\n        break;\n      case '--ignore':\n        ignore.push(next(arg, i));\n        i += 1;\n        break;\n      case '--ignore-ref':\n        ignoreReferences.push(next(arg, i));\n        i += 1;\n        break;\n      case '--family':\n        families.push(next(arg, i));\n        i += 1;\n        break;\n      case '--ignore-family':\n        ignoreFamilies.push(next(arg, i));\n        i += 1;\n        break;\n      case '--history':\n        historyPatterns.push(next(arg, i));\n        i += 1;\n        break;\n      case '--baseline':\n        baseline = next(arg, i);\n        i += 1;\n        break;\n      case '--record-baseline':\n        recordBaseline = next(arg, i);\n        i += 1;\n        break;\n      case '--no-config':\n        noConfig = true;\n        break;\n      case '--format': {\n        const value = next(arg, i);\n        if (value !== 'human' && value !== 'json' && value !== 'sarif') {\n          throw new UsageError(`--format must be human, json or sarif, got \"${value}\"`);\n        }\n        format = value;\n        i += 1;\n        break;\n      }\n      case '--graph-format': {\n        const value = next(arg, i);\n        if (value !== 'dot' && value !== 'mermaid' && value !== 'json') {\n          throw new UsageError(`--graph-format must be dot, mermaid or json, got \"${value}\"`);\n        }\n        graphFormat = value;\n        i += 1;\n        break;\n      }\n      case '--rule': {\n        const value = next(arg, i);\n        const equals = value.indexOf('=');\n        if (equals === -1) throw new UsageError(`--rule expects <id>=<severity>, got \"${value}\"`);\n        const id = value.slice(0, equals) as RuleId;\n        const level = value.slice(equals + 1) as Severity;\n        if (!RULE_IDS.includes(id)) {\n          throw new UsageError(`unknown rule \"${id}\"\\n  known rules: ${RULE_IDS.join(', ')}`);\n        }\n        if (!SEVERITIES.includes(level)) {\n          throw new UsageError(`unknown severity \"${level}\", expected one of: ${SEVERITIES.join(', ')}`);\n        }\n        severities[id] = level;\n        i += 1;\n        break;\n      }\n      case '--max': {\n        max = parseCount(arg, next(arg, i));\n        i += 1;\n        break;\n      }\n      case '--max-warnings': {\n        maxWarnings = parseCount(arg, next(arg, i));\n        i += 1;\n        break;\n      }\n      default:\n        throw new UsageError(`unknown option \"${arg}\"\\n  run \"spec-graph --help\" to see the available options`);\n    }\n  }\n\n  // SARIF is a report about findings, and only `check` produces those. Falling\n  // back to JSON would hand a pipeline something its uploader rejects with a\n  // message about a schema rather than about the command that was run.\n  if (format === 'sarif' && command !== 'check' && !help && !version) {\n    throw new UsageError(`--format sarif reports findings, so it belongs to check, not to ${command}`);\n  }\n\n  if (command === 'query' && selector === null && !help && !version) {\n    throw new UsageError('query needs a selector, for example:\\n  spec-graph query \\'item[openness=open]\\'');\n  }\n\n  return {\n    command,\n    patterns,\n    root,\n    ignore,\n    ignoreReferences,\n    families,\n    ignoreFamilies,\n    historyPatterns,\n    baseline,\n    ratchet,\n    recordBaseline,\n    noConfig,\n    format,\n    graphFormat,\n    severities,\n    color,\n    ascii,\n    verbose,\n    documentsOnly,\n    max,\n    maxWarnings,\n    strict,\n    selector,\n    help,\n    version,\n  };\n}\n\nfunction count(n: number, word: string, many?: string): string {\n  return `${n} ${n === 1 ? word : (many ?? `${word}s`)}`;\n}\n\n/**\n * Reads a baseline file.\n *\n * A missing file is not an error: `--baseline` against a repository that has\n * not recorded one yet should report everything, which is exactly what an empty\n * baseline does.\n */\nasync function readBaseline(path: string, source: string): Promise<ReturnType<typeof parseBaseline>> {\n  let raw: string;\n  try {\n    const { readFile } = await import('node:fs/promises');\n    raw = await readFile(path, 'utf8');\n  } catch {\n    return { baseline: EMPTY_BASELINE, problems: [] };\n  }\n  return parseBaseline(raw, source);\n}\n\nfunction parseCount(flag: string, value: string): number {\n  const parsed = Number.parseInt(value, 10);\n  if (!Number.isFinite(parsed) || parsed < 0 || String(parsed) !== value.trim()) {\n    throw new UsageError(`${flag} expects a non-negative whole number, got \"${value}\"`);\n  }\n  return parsed;\n}\n\n/* -------------------------------------------------------------------------- */\n/* Entry point                                                                */\n/* -------------------------------------------------------------------------- */\n\n/** Runs the CLI and returns the process exit code. Never throws. */\nexport async function main(io: CliIO = {}): Promise<number> {\n  const argv = io.argv ?? process.argv.slice(2);\n  const cwd = io.cwd ?? process.cwd();\n  const out = io.stdout ?? ((text) => process.stdout.write(text));\n  const err = io.stderr ?? ((text) => process.stderr.write(text));\n  const env = io.env ?? process.env;\n\n  let options: CliOptions;\n  try {\n    options = parseArgs(argv, cwd);\n  } catch (error) {\n    if (error instanceof UsageError) {\n      err(`spec-graph: ${error.message}\\n`);\n      return EXIT_ERROR;\n    }\n    throw error;\n  }\n\n  if (options.help) {\n    out(HELP);\n    return EXIT_OK;\n  }\n  if (options.version) {\n    out(`${await readVersion()}\\n`);\n    return EXIT_OK;\n  }\n\n  const color = options.color ?? shouldUseColor({ isTTY: io.isTTY, env });\n  const ascii = options.ascii ?? shouldUseAscii({ env });\n\n  if (options.command === 'rules') {\n    out(renderRules(options.verbose));\n    return EXIT_OK;\n  }\n\n  // Configuration is what is true of the repository; a flag is somebody\n  // overriding it for one run. So a flag always wins, and lists add rather than\n  // replace - a `--ignore-ref` on the command line is one more exclusion, not a\n  // decision to throw away the ones the repository already declared.\n  const loaded = options.noConfig ? { config: {} as SpecGraphConfig, source: null, problems: [] } : loadConfig(options.root);\n  for (const problem of loaded.problems) err(`spec-graph: ${problem}\\n`);\n  const file = loaded.config;\n\n  const patterns =\n    options.patterns.length > 0 ? options.patterns : (file.patterns ?? DEFAULT_PATTERNS);\n  const severityOverrides = { ...(file.severities ?? {}), ...options.severities };\n  const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false));\n\n  const analyseOptions: AnalyseOptions = {\n    root: options.root,\n    patterns,\n    ignore: [...(file.ignore ?? []), ...options.ignore],\n    ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],\n    families: [...(file.families ?? []), ...options.families],\n    ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],\n    historyPatterns: [...(file.historyPatterns ?? []), ...options.historyPatterns],\n    severities,\n    ...(file.maxRelated !== undefined ? { maxRelated: file.maxRelated } : {}),\n  };\n\n  if (options.verbose && loaded.source !== null) out(`configuration: ${loaded.source}\\n`);\n\n  let result;\n  try {\n    result = await analyse(analyseOptions);\n  } catch (error) {\n    err(`spec-graph: ${(error as Error).message}\\n`);\n    return EXIT_ERROR;\n  }\n\n  if (result.files.length === 0) {\n    err(\n      `spec-graph: no specifications matched ${\n        options.patterns.length > 0 ? options.patterns.map((p) => `\"${p}\"`).join(', ') : 'the default patterns'\n      }\\n  looked under ${options.root}\\n`,\n    );\n    return EXIT_ERROR;\n  }\n\n  switch (options.command) {\n    case 'graph':\n      out(formatGraph(result.graph, options.graphFormat, { documentsOnly: options.documentsOnly }));\n      return EXIT_OK;\n\n    case 'query': {\n      try {\n        const matches = execute(result.graph, parseQuery(options.selector as string));\n        out(renderMatches(matches, options.format === 'json' ? 'json' : 'human', result.graph.nodes.size));\n        return matches.length > 0 ? EXIT_OK : EXIT_FAILED;\n      } catch (error) {\n        if (error instanceof QueryError) {\n          err(renderQueryError(options.selector as string, error));\n          return EXIT_ERROR;\n        }\n        throw error;\n      }\n    }\n\n    default: {\n      // Recording is not checking. It writes down what is wrong today so that\n      // tomorrow can be compared against it, and says nothing about whether\n      // today is acceptable - so it reports what it wrote and exits clean.\n      if (options.recordBaseline !== null) {\n        const text = formatBaseline(result.graph, result.diagnostics);\n        try {\n          const { writeFile } = await import('node:fs/promises');\n          await writeFile(underRoot(options.root, options.recordBaseline), text, 'utf8');\n        } catch (error) {\n          err(`spec-graph: cannot write ${options.recordBaseline}: ${(error as Error).message}\\n`);\n          return EXIT_ERROR;\n        }\n        const entries = (JSON.parse(text) as Baseline).findings.length;\n        out(\n          `recorded ${count(result.diagnostics.length, 'finding')} as ${count(entries, 'entry', 'entries')} in ${options.recordBaseline}\\n`,\n        );\n        return EXIT_OK;\n      }\n\n      const source = options.baseline ?? file.baseline ?? null;\n      const ratchet = options.ratchet || file.ratchet === true;\n      let reported = result;\n      let note: { source: string; suppressed: number; stale: number; ratchet: boolean } | undefined;\n      if (source !== null) {\n        const held = await readBaseline(underRoot(options.root, source), source);\n        for (const problem of held.problems) err(`spec-graph: ${problem}\\n`);\n        const outcome = applyBaseline(result.graph, result.diagnostics, held.baseline);\n        reported = withDiagnostics(result, outcome.kept);\n        note = { source, suppressed: outcome.suppressed, stale: outcome.stale.length, ratchet };\n        // Listed rather than counted when the run turns on them: a number is\n        // enough to know the file has slack, and not enough to strike it. Never\n        // in JSON, where the entries are already in the report and a stray line\n        // on stdout is the difference between parsing and not.\n        if (options.format === 'human' && (options.verbose || (ratchet && outcome.stale.length > 0))) {\n          for (const entry of outcome.stale) {\n            out(`  paid: ${entry.rule} ${entry.document}${entry.subject === '' ? '' : ` \"${entry.subject}\"`}\\n`);\n          }\n        }\n      }\n      const looseBaseline = note !== undefined && note.ratchet && note.stale > 0;\n\n      const baselineNote = note === undefined ? {} : { baseline: note };\n      out(\n        options.format === 'sarif'\n          ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated })\n          : options.format === 'json'\n            ? formatJson(reported, { escalated, ...baselineNote })\n            : `${formatReport(reported, { color, ascii, verbose: options.verbose, max: options.max, escalated, ...baselineNote })}\\n`,\n      );\n      if (!reported.ok || looseBaseline) return EXIT_FAILED;\n      if (options.maxWarnings >= 0 && reported.summary.warnings > options.maxWarnings) return EXIT_FAILED;\n      return EXIT_OK;\n    }\n  }\n}\n\n/* -------------------------------------------------------------------------- */\n/* Rendering                                                                  */\n/* -------------------------------------------------------------------------- */\n\nfunction renderRules(explain: boolean): string {\n  const width = Math.max(...RULE_IDS.map((id) => id.length));\n  const lines: string[] = [];\n  for (const id of RULE_IDS) {\n    lines.push(`${id.padEnd(width)}  ${DEFAULT_SEVERITIES[id].padEnd(5)}  ${RULE_DESCRIPTIONS[id]}`);\n    const query = RULE_QUERIES[id];\n    if (explain && query) lines.push(`${' '.repeat(width)}         ${query}`);\n  }\n  return `${lines.join('\\n')}\\n`;\n}\n\nfunction renderMatches(matches: readonly Match[], format: 'human' | 'json', total: number): string {\n  if (format === 'json') {\n    return `${JSON.stringify(\n      {\n        version: 1,\n        count: matches.length,\n        matches: matches.map((match) => ({\n          nodes: match.nodes.map((node) => nodeSummary(node)),\n          edges: match.edges.map((edge) => ({\n            kind: edge.kind,\n            from: edge.from,\n            to: edge.to,\n            file: edge.declaredAt.file,\n            line: edge.declaredAt.span.start.line,\n          })),\n        })),\n      },\n      null,\n      2,\n    )}\\n`;\n  }\n\n  if (matches.length === 0) return `no matches (searched ${total} nodes)\\n`;\n\n  const lines: string[] = [];\n  for (const match of matches) {\n    const head = match.nodes[0] as SpecNode;\n    const tail = match.nodes[match.nodes.length - 1] as SpecNode;\n    lines.push(renderMatch(match));\n    lines.push(`  ${formatRef(head.at)}${match.nodes.length > 1 ? `  ${formatRef(tail.at)}` : ''}`);\n  }\n  lines.push(`${matches.length} ${matches.length === 1 ? 'match' : 'matches'}`);\n  return `${lines.join('\\n')}\\n`;\n}\n\nfunction nodeSummary(node: SpecNode): Record<string, unknown> {\n  return {\n    id: node.id,\n    kind: node.kind,\n    title: node.title,\n    file: node.at.file,\n    line: node.at.span.start.line,\n    ...(node.kind === 'document' ? { phase: node.phase } : { state: node.disposition, openness: node.openness }),\n  };\n}\n\n/** Points at the exact character of a selector that failed to parse. */\nfunction renderQueryError(selector: string, error: QueryError): string {\n  const caret = `${' '.repeat(Math.max(0, error.offset))}^`;\n  return `spec-graph: ${error.message}\\n  ${selector}\\n  ${caret}\\n`;\n}\n\nasync function readVersion(): Promise<string> {\n  try {\n    const { readFile } = await import('node:fs/promises');\n    const url = new URL('../package.json', import.meta.url);\n    const parsed: unknown = JSON.parse(await readFile(url, 'utf8'));\n    if (typeof parsed === 'object' && parsed !== null && 'version' in parsed) {\n      return String((parsed as { version: unknown }).version);\n    }\n  } catch {\n    // Fall through to the placeholder rather than failing `--version`.\n  }\n  return '0.0.0';\n}\n"]}

package/dist/config.d.ts

@@ -43,6 +43,8 @@ export interface SpecGraphConfig {
     readonly historyPatterns?: readonly string[] | undefined;
     /** Path to the accepted-debt baseline, relative to the root. See ADR-0012. */
     readonly baseline?: string | undefined;
+    /** Fail when a baseline entry no longer occurs. See ADR-0012. */
+    readonly ratchet?: boolean | undefined;
     readonly severities?: Partial<Record<RuleId, Severity>> | undefined;
     readonly strict?: boolean | undefined;
     readonly maxRelated?: number | undefined;