@descent-vtt/spec-graph 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,134 @@
 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
+
+**A path spelled without naming a file exactly could resolve to the wrong file.**
+`docs/A` is two things at once - `docs/A.md` with its extension dropped, and
+`docs/A/README.md` standing for its directory - and the index answering such
+spellings held one id per key. A second claimant therefore did not make the link
+ambiguous; it overwrote the first, and the link went to whichever file was
+indexed last.
+
+[ADR-0004](docs/adr/0004-reference-resolution.md) has always said two candidates
+is worse than none, and a reference matching several documents is reported as
+ambiguous rather than bound to whichever was indexed first. That now holds for
+paths too.
+
+Naming a file exactly is never ambiguous, whatever else is spelled the same way,
+and a spelling only one file answers to still resolves in silence - so
+`docs/adr/0007` addressing `docs/adr/0007/README.md` is unchanged.
+
+**This can surface a new warning on upgrade**, in the one situation where it is
+earned: a deliberate link written as a path that genuinely names two files. It
+is a warning rather than an error, it lists both candidates, and prose that
+happens to mention such a path stays silent, because an ambiguity nobody wrote
+down is not a mistake anybody made.
+
 ## 0.2.2
 
 ### 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;