@descent-vtt/spec-graph 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,178 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 0.4.0
+
+Ten open questions across the ADR suite, answered. Five shipped, three declined
+with a reason, one settled by measuring it, and one withdrawn because it turned
+out not to be true.
+
+### Added
+
+**A repository can write its own rules.** `rules` in `.spec-graph.json` takes a
+selector, a message, a hint and a severity, and runs it beside the built-ins:
+
+```json
+"rules": {
+  "no-draft-dependency": {
+    "query": "document[phase=active] -depends-on-> document[phase=draft]",
+    "message": "{0} depends on {1}, which is still a draft",
+    "hint": "wait for {1} to be accepted, or drop it from {0.path}",
+    "severity": "error"
+  }
+}
+```
+
+[ADR-0005](docs/adr/0005-rules-are-queries.md) claimed for three releases that
+the selector language was expressive enough for a team to write the equivalent
+of a built-in rule. It was only true at a prompt: `spec-graph query` could find
+the thing, and nothing could make finding it fail. Three ADRs recorded the same
+gap and stopped at the same sentence - a query needs a severity and a message
+before it is a rule.
+
+The id is the name with `project:` in front, and a built-in id can never contain
+a colon. That one fact is why `--rule`, `--strict`, `--record-baseline`, the
+severity table, the record exemption, the sort order and the SARIF `ruleId` all
+carry a user-defined rule without being taught what one is.
+
+Messages interpolate over the path the query already numbers: `{0}` and `{1}`
+for node ids, `{1.phase}` and `{0.fm.owner}` for anything a selector can read. A
+selector that does not parse, a `{2}` no query can reach, or an attribute
+nothing answers to is reported when the file is read - a rule that cannot work
+has to say so, because silence from a linter is indistinguishable from health.
+`query` also takes a list, read as a union.
+
+See [ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md).
+
+**A broken reference suggests the document it was probably meant to name.**
+`ARD-0015` gets `did you mean ADR-0015?`; `0002-cacheing.md` gets its sibling
+one letter away. `ADR-0003` in a repository of two ADRs gets nothing, and that
+restraint is the design rather than a limitation of it: a family name is a word
+people misremember, a number *is* the identity, and every number sits one edit
+from its neighbours. Each gate ends the same way - exactly one candidate, or
+silence. See [ADR-0004](docs/adr/0004-reference-resolution.md).
+
+**A stale baseline entry says `paid` or `gone`.** `paid` is the ratchet working.
+`gone` means the document was not in this corpus at all, so nothing is known
+about the defect - and the ordinary way to produce one is to narrow an include
+pattern. Both still trip `--ratchet`, but the verdict now says how many entries
+name documents the run did not see and asks a team to check their patterns,
+rather than congratulating them for losing sight of a problem.
+
+**Stale entries are named in the JSON report**, under `baseline.entries`, each
+with its label. A count is enough to know the file has slack and never enough to
+strike it.
+
+**`--verbose` lists what configuration silenced.** Every reference
+`ignoreReferences` or `ignoreFamilies` suppressed, grouped by target and naming
+which of the two did it; the JSON report carries every site under `suppressed`
+without the flag. A single over-broad glob looks exactly like a clean repository
+from the outside, and nothing said otherwise. Not listed: a bare identifier
+spec-graph read as prose on its own - that was nobody's decision.
+
+**A NUL byte is reported as a parse problem.** Not a finding: nothing about the
+graph is wrong and it never fails a build. It earns the line because spec-graph
+is likely the only tool that read the file at all - grep, diff and every review
+interface treat it as binary - and the message names the usual cause, which is
+UTF-16 read as UTF-8 rather than anybody's keystroke.
+
+### Fixed
+
+Nothing that a corpus had hit. Two findings came out of probing rather than out
+of the suite, which is the practice [CLAUDE.md](CLAUDE.md) asks for:
+
+- A near-miss gate that suggested a file which had moved **never fired**.
+  Resolution already binds a path by its basename, so the suggestion had nothing
+  left to suggest. Removed before it shipped rather than after.
+- Hand-mutating each remaining gate found two that no test could kill. One was
+  genuinely equivalent code and is now one line shorter; the other was masked by
+  a length floor, and the test now writes a number long enough to clear it.
+
+### Not added
+
+- **SARIF `fixes`.** Counted the findings with a fix that is an edit rather than
+  a judgement, and there is one. Everything else has to be *inserted*, into front
+  matter that may not exist, at a position only a human can choose. The new
+  near-miss suggestions made the case weaker rather than stronger: they are
+  deliberately a guess, and promoting a guess to a machine-applicable edit throws
+  away the restraint that makes it worth printing.
+- **Hybrid documents** - a specification with a changelog section. The premise
+  turned out to be wrong: regions cannot express it, because `record` is decided
+  once per file and inherited by everything in it. Making it work means a second
+  source of truth for `record`, traded against a free workaround - put the
+  changelog in its own file, which is where it belongs.
+- **Cross-repository references.** Every way of doing it puts network or
+  discovery underneath a pipeline whose test strategy rests on being a pure
+  function of text.
+- **A guard for `~=`.** Probing confirmed `[title~=(a+)+$]` never returns. The
+  hang has been reachable from `query` since 0.1.0; what 0.4.0 changes is that it
+  now lives in a file that runs on every build. Rejecting nested quantifiers
+  catches `(a+)+` and misses `(a|a)+`, and a guard that is incomplete and says it
+  is safe is worse than no guard. Documented instead, with the alternatives
+  weighed in ADR-0016.
+
+### Measured
+
+**The near-miss gate for front-matter keys stays at one edit**, and this is the
+first time anybody checked. Across 73 keys that Jekyll, Hugo, Docusaurus, Astro,
+MADR, KEP, the IETF datatracker and Obsidian actually write, one edit reads
+*none* of them as a near-miss and two edits reads exactly one: `rfc`, which it
+would tell an author to spell `refs`. [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md)
+said two edits would catch `dependancies`; one edit already did, along with
+every other typo anybody produced to argue the case. Two buys nothing and costs
+a false positive on a key that carries citations in exactly the corpora this
+tool is pointed at.
+
+### Verified
+
+| | |
+|---|---|
+| `npm run lint` | pass |
+| `npm test` | 754 passing, 20 files |
+| `npm run selfcheck` | pass, over 19 documents and 124 relations |
+| `npm run test:mutation` | 79.41% over 8,585 mutants, 64m30s |
+| hosted full run, which governs | **75.40%**, 102m48s |
+| `break` | unchanged at 70 |
+
+79.69% over 8,126 mutants at 0.3.0 against 79.41% over 8,585 here, on the same
+machine. The new code carries itself: `project-rules.ts` at **99.50%** with one
+survivor - a genuinely equivalent `<` against `<=` in a comparator whose inputs
+are object keys and therefore never equal.
+
+That 99.50% is what reading the survivor list bought. The first full run put the
+module at 86.89%, a targeted re-measurement with `coverageAnalysis all` agreed at
+86.41% - so the gap was real and not `perTest` mis-attribution - and sixteen of
+those survivors turned out to be tests nobody had written. The whole-corpus
+figure moved 0.38 points for it.
+
+The hosted number is the one that actually governs, because it is where the build
+fails: **75.40%**, up from 75.14% at 0.3.0. Lose every timeout on a loaded runner
+and it reads 71.76%, which is the most margin `break: 70` has ever had.
+
+That run also caught the other half of a claim
+[ADR-0007](docs/adr/0007-mutation-testing.md) narrowed at 0.3.0. The `main` push
+and the `v0.4.0` tag were the same commit on the same runner, and the incremental
+read **1.29 points low** against the rebuild - having read 3.18 points *high* at
+0.3.0. Two observations, opposite signs. The direction is not a property, and the
+incremental run took 110 minutes to the rebuild's 103, because a change this wide
+leaves it nothing to reuse.
+
+### Withdrawn
+
+[ADR-0013](docs/adr/0013-the-scanner-hands-back-prose.md) said a lone `\r` was
+not treated as a line ending. It always was - `createLineIndex` has recognised
+all three terminators since 0.1.0 and says so in its own doc comment. The claim
+came from reading the scanner and not the table underneath it, and nobody had
+executed it. One corpus through `\n`, `\r\n` and `\r` now produces identical
+items, findings and line numbers, as a test.
+
+### Changed
+
+For anyone using the programmatic API: `Diagnostic.rule` is now `AnyRuleId`,
+which is `RuleId` plus the `project:` namespace. An exhaustive `switch` over the
+built-ins needs a default arm. `BaselineOutcome.stale` carries `reason`, and
+`ResolvedCorpus` carries `suppressed`.
+
 ## 0.3.0
 
 Found by writing a corpus designed to break the scanner and reading the edges it
@@ -99,11 +271,12 @@ text. Reasoning in
 
 ### 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).
+684 tests, and a mutation score of **75.14% on the hosted runner** - the figure
+that governs, up from 73.32% at v0.2.0 - against 79.69% over 8,126 mutants on a
+developer machine. The guard stays at `break: 70`. See
+[ADR-0007](docs/adr/0007-mutation-testing.md), which 0.3.0 also amended: an
+incremental run read 3.18 points *high* against a full rebuild of the same
+commit, so the claim that incremental errs low was wrong.
 
 ## 0.2.3
 

package/README.md

@@ -363,6 +363,9 @@ gate without writing any code:
     ! npx spec-graph query 'document[path^=docs/prd] -depends-on-> document[phase=draft]'
 ```
 
+That shell line is a rule wearing a disguise. Give it a name and a sentence and
+it becomes one — see [your own rules](#your-own-rules) below.
+
 **Grammar**
 
 ```text
@@ -383,6 +386,64 @@ Items inherit their document's lifecycle, so `item[phase=retired]` means what yo
 expect. A query evaluates to **paths**, not endpoints, which is why a finding can
 name both ends and the line that connects them.
 
+## Your own rules
+
+A convention spec-graph never anticipated is a selector plus a sentence. Write
+both in the config file and it becomes a rule like any other:
+
+```json
+{
+  "rules": {
+    "no-draft-dependency": {
+      "query": "document[phase=active] -depends-on-> document[phase=draft]",
+      "message": "{0} depends on {1}, which is still a draft",
+      "hint": "wait for {1} to be accepted, or drop it from {0.path}",
+      "severity": "error"
+    }
+  }
+}
+```
+
+```text
+x docs/adr/0002-delivery.md:4:13  project:no-draft-dependency
+    ADR-0002 depends on ADR-0001, which is still a draft
+    > wait for ADR-0001 to be accepted, or drop it from docs/adr/0002-delivery.md
+```
+
+The finding points at the line that *declares* the relation, because that is
+where a human goes to change the answer — the same discipline every built-in
+follows.
+
+| Field | |
+|---|---|
+| `query` | One selector, or a list of them read as a union. |
+| `message` | The headline. `{0}` is the first node on the path, `{1}` the next; `{1.phase}` and `{0.fm.owner}` read any selector attribute. |
+| `hint` | The next action. Optional, templated the same way. |
+| `severity` | `error`, `warn`, `info` or `off`. Defaults to `warn`. |
+
+It defaults to `warn` on purpose: a rule a team has just written has not yet
+earned the right to fail their build, and the first run of a new convention is
+when it is most likely to be wrong.
+
+The id is the name with `project:` in front, which is why it can never collide
+with a built-in — and why everything else already works. It is baselined by
+`--record-baseline`, silenced by `--rule project:no-draft-dependency=off`,
+escalated by `--strict`, listed by `spec-graph rules`, exempted on journals like
+every other rule about obligations, and emitted as a first-class `ruleId` in
+SARIF, where a project rule describes itself by the selector it is.
+
+Mistakes are reported when the file is read, not discovered as a rule that
+quietly finds nothing:
+
+```text
+spec-graph: .spec-graph.json: rules.no-drafts: mismatched arrow: use -kind-> for
+  one hop or =kind=> for transitive (at character 10)
+spec-graph: .spec-graph.json: rules.owner: "{1.phse}" asks for an attribute
+  nothing has
+```
+
+See [ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md).
+
 ## Directives
 
 Inference covers almost everything, but inference you cannot override is a trap.
@@ -523,7 +584,13 @@ command. spec-graph reads the first of `.spec-graph.json`,
   "baseline": ".spec-graph-baseline.json",
   "ratchet": true,
   "severities": { "self-reference": "off" },
-  "strict": true
+  "strict": true,
+  "rules": {
+    "no-draft-dependency": {
+      "query": "document[phase=active] -depends-on-> document[phase=draft]",
+      "message": "{0} depends on {1}, which is still a draft"
+    }
+  }
 }
 ```
 
@@ -554,6 +621,20 @@ resolves to your local RFC-0001 with `RFC` on the ignore list. No configuration
 can delete an edge. See
 [ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md).
 
+`--verbose` lists everything they silenced, so one over-broad glob cannot quietly
+turn the check off and look like a clean repository:
+
+```text
+i docs/adr/0001-traps.md:15:3   ignored reference: trap 55 (2 times)
+i docs/rfcs/0002-transport.md:7:69  ignored family: RFC 2119
+```
+
+The JSON report carries the same rows under `suppressed`, without needing the
+flag. What is deliberately *not* listed is a bare identifier spec-graph read as
+prose on its own — `T-1000` was nobody's decision, and listing it would bury the
+entries that were. See
+[ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
+
 Prose like `Phase 1`, `R69`, `Q-120`, `Table 2` and `Step 4` has never needed
 this: an identifier found in prose is only read as a citation when its family
 already exists in the corpus.

package/dist/baseline.d.ts

@@ -14,12 +14,12 @@
  * the same reason extraction never touches a disk.
  */
 import type { SpecGraph } from './graph.js';
-import type { Diagnostic, RuleId } from './types.js';
+import { type AnyRuleId, type Diagnostic } from './types.js';
 /** The current file format. Bumped only for a change old files cannot survive. */
 export declare const BASELINE_VERSION = 1;
 /** One class of accepted finding, and how many of it there were. */
 export interface BaselineEntry {
-    readonly rule: RuleId;
+    readonly rule: AnyRuleId;
     /** The specification the finding is about, not the file it was found in. */
     readonly document: string;
     /** What within it: a citation target, or the document at the other end. */
@@ -70,18 +70,32 @@ export interface ParsedBaseline {
 }
 /** Parses a baseline file. Never throws; an unusable file yields an empty one. */
 export declare function parseBaseline(raw: string, source: string): ParsedBaseline;
+/**
+ * An entry the run did not spend, and why.
+ *
+ * The distinction is the whole value of the label. `paid` is the ratchet
+ * working: the defect was fixed and the exemption can be struck. `gone` is not
+ * an achievement at all - the document the entry is about was not in this
+ * corpus, so nothing whatever is known about the defect. Both make the file
+ * stale and both need it re-recorded, but only one of them is good news, and a
+ * report that says "paid" over a narrowed `patterns` glob is congratulating a
+ * team for losing sight of the problem.
+ */
+export interface StaleEntry extends BaselineEntry {
+    readonly reason: 'paid' | 'gone';
+}
 export interface BaselineOutcome {
     /** Findings the baseline does not account for. These are the report. */
     readonly kept: readonly Diagnostic[];
     /** How many were accounted for. Reported as a number, not as a list. */
     readonly suppressed: number;
     /**
-     * Entries whose debt has been paid, wholly or partly.
+     * Entries whose debt was not spent, wholly or partly.
      *
      * The ratchet: once a repository is clean of something, saying so in the file
      * stops it coming back unnoticed.
      */
-    readonly stale: readonly BaselineEntry[];
+    readonly stale: readonly StaleEntry[];
 }
 /**
  * Removes the findings a baseline accounts for.

package/dist/baseline.js

@@ -14,6 +14,7 @@
  * the same reason extraction never touches a disk.
  */
 import { RULE_IDS } from './rules.js';
+import { isProjectRule } from './types.js';
 /** The current file format. Bumped only for a change old files cannot survive. */
 export const BASELINE_VERSION = 1;
 export const EMPTY_BASELINE = Object.freeze({ version: BASELINE_VERSION, findings: [] });
@@ -128,7 +129,12 @@ function readEntry(row, where, problems) {
     }
     const fields = row;
     const rule = fields['rule'];
-    if (typeof rule !== 'string' || !RULE_IDS.includes(rule)) {
+    // A project rule is accepted on its namespace alone, because the baseline is
+    // read before the configuration that defines it has any say - and an entry
+    // rejected here would silently un-accept debt a team had already signed off.
+    // A name nothing defines suppresses nothing and is reported as stale, which
+    // is the same answer by a route that keeps the file readable.
+    if (typeof rule !== 'string' || !(RULE_IDS.includes(rule) || isProjectRule(rule))) {
         problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);
         return null;
     }
@@ -177,7 +183,13 @@ export function applyBaseline(graph, diagnostics, baseline) {
         const unspent = budget.get(key) ?? 0;
         if (unspent <= 0)
             continue;
-        stale.push({ ...entry, count: Math.min(unspent, entry.count) });
+        // Asked of the graph rather than of the filesystem, because the graph is
+        // what this run looked at. A document that still exists on disk and fell
+        // outside the include patterns is gone for the purposes of the answer, and
+        // that is the case worth telling apart - it is the one a team reaches by
+        // editing a glob rather than by fixing anything.
+        const reason = graph.document(entry.document) === undefined ? 'gone' : 'paid';
+        stale.push({ ...entry, count: Math.min(unspent, entry.count), reason });
         // An entry counted once; a duplicate key in a hand-edited file must not
         // claim the same surplus twice.
         budget.set(key, 0);

package/dist/baseline.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Accepted debt, and the ratchet that keeps it from growing.\n *\n * A linter introduced to a repository that predates it reports everything at\n * once. Fifty findings on day one is not a report, it is a decision to be\n * ignored: the team cannot stop to fix them, so they turn the tool off, or they\n * turn the rules off and the next specification rots unwatched.\n *\n * A baseline is the third answer. It records what was already wrong on the day\n * the tool arrived, and reports only what happened since. Debt can be paid down\n * whenever there is room, and in the meantime nothing new gets in.\n *\n * The whole module is pure. Reading and writing the file is the CLI's job, for\n * the same reason extraction never touches a disk.\n */\n\nimport type { SpecGraph } from './graph.js';\nimport { RULE_IDS } from './rules.js';\nimport type { Diagnostic, RuleId } from './types.js';\n\n/** The current file format. Bumped only for a change old files cannot survive. */\nexport const BASELINE_VERSION = 1;\n\n/** One class of accepted finding, and how many of it there were. */\nexport interface BaselineEntry {\n  readonly rule: RuleId;\n  /** The specification the finding is about, not the file it was found in. */\n  readonly document: string;\n  /** What within it: a citation target, or the document at the other end. */\n  readonly subject: string;\n  readonly count: number;\n}\n\nexport interface Baseline {\n  readonly version: number;\n  readonly findings: readonly BaselineEntry[];\n}\n\nexport const EMPTY_BASELINE: Baseline = Object.freeze({ version: BASELINE_VERSION, findings: [] });\n\n/**\n * What makes two findings the same finding.\n *\n * Not the line. A baseline keyed on line numbers is invalidated by any edit\n * above it, which turns every unrelated pull request into a wall of findings\n * nobody introduced. Not the message either: rewording a diagnostic would\n * silently expire every baseline in the world.\n *\n * What survives is the pair the finding is actually about - which specification,\n * and what within it. Both are ids that outlive a file being renamed, a section\n * being moved into its own file, or an obligation being reordered, because that\n * is exactly what identifiers were made stable for (ADR-0009).\n *\n * The cost is deliberate coarseness: two broken links from one document to the\n * same target are one entry with a count of two. Paying that buys a baseline\n * that does not lie the first time somebody reformats a paragraph.\n */\nexport function fingerprintOf(graph: SpecGraph, diagnostic: Diagnostic): { document: string; subject: string } {\n  const first = diagnostic.nodes[0] ?? '';\n  const document = graph.owningDocument(first)?.id ?? first;\n  if (diagnostic.target !== null) return { document, subject: diagnostic.target };\n\n  const second = diagnostic.nodes[1];\n  const subject = second === undefined ? '' : (graph.owningDocument(second)?.id ?? second);\n  // A document-level rule lists its own items as the rest of `nodes`, so the\n  // other end resolves back to where it started. Saying so twice in the file\n  // would only invite a reader to look for a distinction that is not there.\n  return { document, subject: subject === document ? '' : subject };\n}\n\nfunction keyOf(rule: RuleId, document: string, subject: string): string {\n  // Tab-joined: the three parts are ids and targets, and a tab is the one\n  // character none of them can contain.\n  return `${rule}\\t${document}\\t${subject}`;\n}\n\n/** Counts findings by fingerprint. */\nfunction tally(graph: SpecGraph, diagnostics: readonly Diagnostic[]): Map<string, BaselineEntry> {\n  const out = new Map<string, BaselineEntry>();\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const seen = out.get(key);\n    out.set(key, {\n      rule: diagnostic.rule,\n      document,\n      subject,\n      count: (seen?.count ?? 0) + 1,\n    });\n  }\n  return out;\n}\n\n/**\n * Renders a baseline for the findings given.\n *\n * Sorted by rule, then document, then subject, and written with two-space\n * indentation: the file lands in a repository and is read in diffs, so its byte\n * order has to be a function of its content and nothing else. No timestamp, for\n * the same reason - a generated date makes every re-record a change even when\n * nothing changed.\n */\nexport function formatBaseline(graph: SpecGraph, diagnostics: readonly Diagnostic[]): string {\n  const findings = [...tally(graph, diagnostics).values()].sort(compareEntries);\n  return `${JSON.stringify({ version: BASELINE_VERSION, findings }, null, 2)}\\n`;\n}\n\nfunction compareEntries(a: BaselineEntry, b: BaselineEntry): number {\n  if (a.rule !== b.rule) return a.rule < b.rule ? -1 : 1;\n  if (a.document !== b.document) return a.document < b.document ? -1 : 1;\n  if (a.subject !== b.subject) return a.subject < b.subject ? -1 : 1;\n  return 0;\n}\n\nexport interface ParsedBaseline {\n  readonly baseline: Baseline;\n  /** Reported, never silently dropped. A baseline nobody can read is worse\n   * than none: it suppresses findings the reader cannot account for. */\n  readonly problems: readonly string[];\n}\n\n/** Parses a baseline file. Never throws; an unusable file yields an empty one. */\nexport function parseBaseline(raw: string, source: string): ParsedBaseline {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);\n  } catch (error) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} is not valid JSON: ${(error as Error).message}`] };\n  }\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} must contain a JSON object`] };\n  }\n\n  const record = parsed as Record<string, unknown>;\n  const problems: string[] = [];\n  if (record['version'] !== BASELINE_VERSION) {\n    return {\n      baseline: EMPTY_BASELINE,\n      problems: [`${source} is version ${String(record['version'])}, and this build reads version ${BASELINE_VERSION}`],\n    };\n  }\n\n  const rows = record['findings'];\n  if (!Array.isArray(rows)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source}: \"findings\" must be an array`] };\n  }\n\n  const findings: BaselineEntry[] = [];\n  for (const [index, row] of rows.entries()) {\n    const entry = readEntry(row, `${source}: findings[${index}]`, problems);\n    if (entry !== null) findings.push(entry);\n  }\n  return { baseline: { version: BASELINE_VERSION, findings }, problems };\n}\n\nfunction readEntry(row: unknown, where: string, problems: string[]): BaselineEntry | null {\n  if (typeof row !== 'object' || row === null || Array.isArray(row)) {\n    problems.push(`${where} must be an object`);\n    return null;\n  }\n  const fields = row as Record<string, unknown>;\n  const rule = fields['rule'];\n  if (typeof rule !== 'string' || !RULE_IDS.includes(rule as RuleId)) {\n    problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);\n    return null;\n  }\n  const document = fields['document'];\n  const subject = fields['subject'] ?? '';\n  const count = fields['count'] ?? 1;\n  if (typeof document !== 'string' || typeof subject !== 'string') {\n    problems.push(`${where}: \"document\" and \"subject\" must be strings`);\n    return null;\n  }\n  if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {\n    problems.push(`${where}: \"count\" must be a whole number of at least 1`);\n    return null;\n  }\n  return { rule: rule as RuleId, document, subject, count };\n}\n\nexport interface BaselineOutcome {\n  /** Findings the baseline does not account for. These are the report. */\n  readonly kept: readonly Diagnostic[];\n  /** How many were accounted for. Reported as a number, not as a list. */\n  readonly suppressed: number;\n  /**\n   * Entries whose debt has been paid, wholly or partly.\n   *\n   * The ratchet: once a repository is clean of something, saying so in the file\n   * stops it coming back unnoticed.\n   */\n  readonly stale: readonly BaselineEntry[];\n}\n\n/**\n * Removes the findings a baseline accounts for.\n *\n * Where a baseline allows two of something and three exist, one is reported.\n * Which one is not a meaningful question - they share a fingerprint - so the\n * findings are taken in report order and the surplus is what is left.\n */\nexport function applyBaseline(\n  graph: SpecGraph,\n  diagnostics: readonly Diagnostic[],\n  baseline: Baseline,\n): BaselineOutcome {\n  const budget = new Map<string, number>();\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    budget.set(key, (budget.get(key) ?? 0) + entry.count);\n  }\n\n  const kept: Diagnostic[] = [];\n  let suppressed = 0;\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const left = budget.get(key) ?? 0;\n    if (left <= 0) {\n      kept.push(diagnostic);\n      continue;\n    }\n    budget.set(key, left - 1);\n    suppressed += 1;\n  }\n\n  const stale: BaselineEntry[] = [];\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    const unspent = budget.get(key) ?? 0;\n    if (unspent <= 0) continue;\n    stale.push({ ...entry, count: Math.min(unspent, entry.count) });\n    // An entry counted once; a duplicate key in a hand-edited file must not\n    // claim the same surplus twice.\n    budget.set(key, 0);\n  }\n\n  return { kept, suppressed, stale: stale.sort(compareEntries) };\n}\n"]}
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Accepted debt, and the ratchet that keeps it from growing.\n *\n * A linter introduced to a repository that predates it reports everything at\n * once. Fifty findings on day one is not a report, it is a decision to be\n * ignored: the team cannot stop to fix them, so they turn the tool off, or they\n * turn the rules off and the next specification rots unwatched.\n *\n * A baseline is the third answer. It records what was already wrong on the day\n * the tool arrived, and reports only what happened since. Debt can be paid down\n * whenever there is room, and in the meantime nothing new gets in.\n *\n * The whole module is pure. Reading and writing the file is the CLI's job, for\n * the same reason extraction never touches a disk.\n */\n\nimport type { SpecGraph } from './graph.js';\nimport { RULE_IDS } from './rules.js';\nimport { isProjectRule, type AnyRuleId, type Diagnostic, type RuleId } from './types.js';\n\n/** The current file format. Bumped only for a change old files cannot survive. */\nexport const BASELINE_VERSION = 1;\n\n/** One class of accepted finding, and how many of it there were. */\nexport interface BaselineEntry {\n  readonly rule: AnyRuleId;\n  /** The specification the finding is about, not the file it was found in. */\n  readonly document: string;\n  /** What within it: a citation target, or the document at the other end. */\n  readonly subject: string;\n  readonly count: number;\n}\n\nexport interface Baseline {\n  readonly version: number;\n  readonly findings: readonly BaselineEntry[];\n}\n\nexport const EMPTY_BASELINE: Baseline = Object.freeze({ version: BASELINE_VERSION, findings: [] });\n\n/**\n * What makes two findings the same finding.\n *\n * Not the line. A baseline keyed on line numbers is invalidated by any edit\n * above it, which turns every unrelated pull request into a wall of findings\n * nobody introduced. Not the message either: rewording a diagnostic would\n * silently expire every baseline in the world.\n *\n * What survives is the pair the finding is actually about - which specification,\n * and what within it. Both are ids that outlive a file being renamed, a section\n * being moved into its own file, or an obligation being reordered, because that\n * is exactly what identifiers were made stable for (ADR-0009).\n *\n * The cost is deliberate coarseness: two broken links from one document to the\n * same target are one entry with a count of two. Paying that buys a baseline\n * that does not lie the first time somebody reformats a paragraph.\n */\nexport function fingerprintOf(graph: SpecGraph, diagnostic: Diagnostic): { document: string; subject: string } {\n  const first = diagnostic.nodes[0] ?? '';\n  const document = graph.owningDocument(first)?.id ?? first;\n  if (diagnostic.target !== null) return { document, subject: diagnostic.target };\n\n  const second = diagnostic.nodes[1];\n  const subject = second === undefined ? '' : (graph.owningDocument(second)?.id ?? second);\n  // A document-level rule lists its own items as the rest of `nodes`, so the\n  // other end resolves back to where it started. Saying so twice in the file\n  // would only invite a reader to look for a distinction that is not there.\n  return { document, subject: subject === document ? '' : subject };\n}\n\nfunction keyOf(rule: AnyRuleId, document: string, subject: string): string {\n  // Tab-joined: the three parts are ids and targets, and a tab is the one\n  // character none of them can contain.\n  return `${rule}\\t${document}\\t${subject}`;\n}\n\n/** Counts findings by fingerprint. */\nfunction tally(graph: SpecGraph, diagnostics: readonly Diagnostic[]): Map<string, BaselineEntry> {\n  const out = new Map<string, BaselineEntry>();\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const seen = out.get(key);\n    out.set(key, {\n      rule: diagnostic.rule,\n      document,\n      subject,\n      count: (seen?.count ?? 0) + 1,\n    });\n  }\n  return out;\n}\n\n/**\n * Renders a baseline for the findings given.\n *\n * Sorted by rule, then document, then subject, and written with two-space\n * indentation: the file lands in a repository and is read in diffs, so its byte\n * order has to be a function of its content and nothing else. No timestamp, for\n * the same reason - a generated date makes every re-record a change even when\n * nothing changed.\n */\nexport function formatBaseline(graph: SpecGraph, diagnostics: readonly Diagnostic[]): string {\n  const findings = [...tally(graph, diagnostics).values()].sort(compareEntries);\n  return `${JSON.stringify({ version: BASELINE_VERSION, findings }, null, 2)}\\n`;\n}\n\nfunction compareEntries(a: BaselineEntry, b: BaselineEntry): number {\n  if (a.rule !== b.rule) return a.rule < b.rule ? -1 : 1;\n  if (a.document !== b.document) return a.document < b.document ? -1 : 1;\n  if (a.subject !== b.subject) return a.subject < b.subject ? -1 : 1;\n  return 0;\n}\n\nexport interface ParsedBaseline {\n  readonly baseline: Baseline;\n  /** Reported, never silently dropped. A baseline nobody can read is worse\n   * than none: it suppresses findings the reader cannot account for. */\n  readonly problems: readonly string[];\n}\n\n/** Parses a baseline file. Never throws; an unusable file yields an empty one. */\nexport function parseBaseline(raw: string, source: string): ParsedBaseline {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);\n  } catch (error) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} is not valid JSON: ${(error as Error).message}`] };\n  }\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source} must contain a JSON object`] };\n  }\n\n  const record = parsed as Record<string, unknown>;\n  const problems: string[] = [];\n  if (record['version'] !== BASELINE_VERSION) {\n    return {\n      baseline: EMPTY_BASELINE,\n      problems: [`${source} is version ${String(record['version'])}, and this build reads version ${BASELINE_VERSION}`],\n    };\n  }\n\n  const rows = record['findings'];\n  if (!Array.isArray(rows)) {\n    return { baseline: EMPTY_BASELINE, problems: [`${source}: \"findings\" must be an array`] };\n  }\n\n  const findings: BaselineEntry[] = [];\n  for (const [index, row] of rows.entries()) {\n    const entry = readEntry(row, `${source}: findings[${index}]`, problems);\n    if (entry !== null) findings.push(entry);\n  }\n  return { baseline: { version: BASELINE_VERSION, findings }, problems };\n}\n\nfunction readEntry(row: unknown, where: string, problems: string[]): BaselineEntry | null {\n  if (typeof row !== 'object' || row === null || Array.isArray(row)) {\n    problems.push(`${where} must be an object`);\n    return null;\n  }\n  const fields = row as Record<string, unknown>;\n  const rule = fields['rule'];\n  // A project rule is accepted on its namespace alone, because the baseline is\n  // read before the configuration that defines it has any say - and an entry\n  // rejected here would silently un-accept debt a team had already signed off.\n  // A name nothing defines suppresses nothing and is reported as stale, which\n  // is the same answer by a route that keeps the file readable.\n  if (typeof rule !== 'string' || !(RULE_IDS.includes(rule as RuleId) || isProjectRule(rule as AnyRuleId))) {\n    problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);\n    return null;\n  }\n  const document = fields['document'];\n  const subject = fields['subject'] ?? '';\n  const count = fields['count'] ?? 1;\n  if (typeof document !== 'string' || typeof subject !== 'string') {\n    problems.push(`${where}: \"document\" and \"subject\" must be strings`);\n    return null;\n  }\n  if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {\n    problems.push(`${where}: \"count\" must be a whole number of at least 1`);\n    return null;\n  }\n  return { rule: rule as AnyRuleId, document, subject, count };\n}\n\n/**\n * An entry the run did not spend, and why.\n *\n * The distinction is the whole value of the label. `paid` is the ratchet\n * working: the defect was fixed and the exemption can be struck. `gone` is not\n * an achievement at all - the document the entry is about was not in this\n * corpus, so nothing whatever is known about the defect. Both make the file\n * stale and both need it re-recorded, but only one of them is good news, and a\n * report that says \"paid\" over a narrowed `patterns` glob is congratulating a\n * team for losing sight of the problem.\n */\nexport interface StaleEntry extends BaselineEntry {\n  readonly reason: 'paid' | 'gone';\n}\n\nexport interface BaselineOutcome {\n  /** Findings the baseline does not account for. These are the report. */\n  readonly kept: readonly Diagnostic[];\n  /** How many were accounted for. Reported as a number, not as a list. */\n  readonly suppressed: number;\n  /**\n   * Entries whose debt was not spent, wholly or partly.\n   *\n   * The ratchet: once a repository is clean of something, saying so in the file\n   * stops it coming back unnoticed.\n   */\n  readonly stale: readonly StaleEntry[];\n}\n\n/**\n * Removes the findings a baseline accounts for.\n *\n * Where a baseline allows two of something and three exist, one is reported.\n * Which one is not a meaningful question - they share a fingerprint - so the\n * findings are taken in report order and the surplus is what is left.\n */\nexport function applyBaseline(\n  graph: SpecGraph,\n  diagnostics: readonly Diagnostic[],\n  baseline: Baseline,\n): BaselineOutcome {\n  const budget = new Map<string, number>();\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    budget.set(key, (budget.get(key) ?? 0) + entry.count);\n  }\n\n  const kept: Diagnostic[] = [];\n  let suppressed = 0;\n  for (const diagnostic of diagnostics) {\n    const { document, subject } = fingerprintOf(graph, diagnostic);\n    const key = keyOf(diagnostic.rule, document, subject);\n    const left = budget.get(key) ?? 0;\n    if (left <= 0) {\n      kept.push(diagnostic);\n      continue;\n    }\n    budget.set(key, left - 1);\n    suppressed += 1;\n  }\n\n  const stale: StaleEntry[] = [];\n  for (const entry of baseline.findings) {\n    const key = keyOf(entry.rule, entry.document, entry.subject);\n    const unspent = budget.get(key) ?? 0;\n    if (unspent <= 0) continue;\n    // Asked of the graph rather than of the filesystem, because the graph is\n    // what this run looked at. A document that still exists on disk and fell\n    // outside the include patterns is gone for the purposes of the answer, and\n    // that is the case worth telling apart - it is the one a team reaches by\n    // editing a glob rather than by fixing anything.\n    const reason = graph.document(entry.document) === undefined ? 'gone' : 'paid';\n    stale.push({ ...entry, count: Math.min(unspent, entry.count), reason });\n    // An entry counted once; a duplicate key in a hand-edited file must not\n    // claim the same surplus twice.\n    budget.set(key, 0);\n  }\n\n  return { kept, suppressed, stale: stale.sort(compareEntries) };\n}\n"]}

package/dist/cli.d.ts

@@ -9,7 +9,7 @@
  * itself could not run. A usage mistake never masquerades as a passing build.
  */
 import { type GraphFormat } from './report.js';
-import type { RuleId, Severity } from './types.js';
+import { type AnyRuleId, type Severity } from './types.js';
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_ERROR = 2;
@@ -47,7 +47,7 @@ export interface CliOptions {
     readonly noConfig: boolean;
     readonly format: 'human' | 'json' | 'sarif';
     readonly graphFormat: GraphFormat;
-    readonly severities: Partial<Record<RuleId, Severity>>;
+    readonly severities: Partial<Record<AnyRuleId, Severity>>;
     readonly color: boolean | null;
     readonly ascii: boolean | null;
     readonly verbose: boolean;
@@ -68,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  --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";
+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 diagnostics that will run, built in and project.\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. A project\n                          rule is named in full: project:no-draft-dependency.\n                          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, per-file detail, and every\n                          reference --ignore-ref or --ignore-family silenced\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               ~= is a JavaScript regular expression, run once per node; ^= $=\n               and *= cover most cases and cannot backtrack\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\nPROJECT RULES\n  A convention spec-graph never anticipated is a selector plus a sentence, and\n  belongs in the same file. Every rule declared here runs beside the built-ins\n  and is reported, baselined, escalated by --strict and silenced by --rule in\n  exactly the same way.\n\n    { \"rules\": {\n        \"no-draft-dependency\": {\n          \"query\": \"document[phase=active] -depends-on-> document[phase=draft]\",\n          \"message\": \"{0} depends on {1}, which is still a draft\",\n          \"hint\": \"wait for {1} to be accepted, or drop it from {0.path}\",\n          \"severity\": \"error\" } } }\n\n  query     One selector, or a list of them read as a union.\n  message   The headline. {0} is the first node on the path, {1} the next;\n            {1.phase} and {0.fm.owner} read any selector attribute.\n  hint      The next action. Optional, and templated the same way.\n  severity  error, warn, info or off. Defaults to warn - a rule a team has\n            just written has not yet earned the right to fail their build.\n\n  The id is the name with project: in front, which is why it can never collide\n  with a built-in. A selector that does not parse, or a {2} the query can never\n  reach, is reported when the file is read rather than found missing later.\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  spec-graph rules --explain                # including this repository's own\n  spec-graph check --rule project:no-draft-dependency=off\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. */