@descent-vtt/spec-graph 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -11,6 +11,115 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.14.0
+
+An input that is set and names nothing - a family name no family has, a list
+of families no document belongs to, a `--root` that is no directory, a blank
+value, an option of another command - was read as if it had not been given.
+It is refused now: exit 2 and one line that names it
+([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+
+### Changed
+
+- **A family name no family has is refused.** `--family ""`, which an unset
+  variable leaves, and `--family ADR,RFC` allowed no family at all, so every
+  citation was prose and a check that failed on a dangling one exited 0. Each
+  is exit 2 now, `--family expects one family's name, such as ADR, got ""`,
+  and so are `--ignore-family`, `families` and `ignoreFamilies` in the
+  configuration, and `createFamilyFilter()` from the package.
+  Upgrading: give one name each time, the prefix the identifiers are written
+  with, as in `--family ADR --family RFC`, and leave the option out where
+  there is none to give.
+- **A `--root` that is no directory is refused by name.** `rules --root` given
+  a path that is not there, a file or an empty value listed the built-in rules
+  and exited 0, and `check`, `query` and `graph` exited 2 saying only that no
+  specification matched. Each ends with exit 2 and the option named: `--root
+  "<path>" is not there`, `is not a directory`, or `--root expects a
+  directory, got ""`.
+  Upgrading: name a directory that exists, or leave `--root` out and the
+  directory holding the configuration is the root.
+- **A configuration file that is there and cannot be read stops the run.** A
+  directory called `.spec-graph.json`, or a file the run may not open, was
+  passed over as absent, and the run checked on defaults or on the
+  configuration of a directory above. It is a problem in the configuration
+  now, exit 2.
+  Upgrading: remove or repair the file, or run with `--no-config`.
+- **A blank `--ignore` or `--record-baseline` is refused, as an empty one
+  was.** `--ignore " "` was read as a directory's name since 0.9.0 and
+  ignored nothing, `"ignore": [" "]` in the configuration likewise, and
+  `--record-baseline " "` wrote a file named with a space.
+  Upgrading: pass the option only where its variable is set, as in
+  `${IGNORE:+--ignore "$IGNORE"}`.
+- **`rules` takes one rule id.** `spec-graph rules a b` listed `a` and said
+  nothing of `b`; it is exit 2 now, with both named.
+  Upgrading: one run for each rule, or no id for all of them.
+- **`--format json` is refused by `graph` and `rules`.** `graph --format
+  json` wrote DOT and `rules --format json` its list, each with exit 0, as
+  `--format sarif` was already refused there.
+  Upgrading: `graph --graph-format json` writes the graph as JSON; `rules`
+  has one format.
+- **A list of families that names none the documents belong to stops the
+  check.** `--family RFC` in a repository of ADRs, or `ADRS` for `ADR`,
+  allowed nothing, as `--family ""` did: `check` printed `the specification
+  graph is consistent` over a dangling citation, under `--strict` too. It is
+  exit 2 now, for `--family` and `families` alike, with the list and the
+  families the documents do belong to; a list that names such a family beside
+  one they belong to gets a line on stderr and fails nothing.
+  Upgrading: name a family whose identifiers the documents carry, `ADR` for
+  `ADR-0007`, or leave the list out until the first such document is written.
+- **An option a command does not read is refused by that command.** `query
+  --strict`, `graph --record-baseline f`, `rules --max 1`, `diff --root x` and
+  some sixty more pairings ran as if the option were absent, and `spec-graph
+  --graph-format mermaid > graph.mmd` wrote the check's report into the file.
+  Each is exit 2 with the option, the command and the commands that read it:
+  `--graph-format belongs to graph, not to check`. `--no-config`,
+  `--no-color` and `--ascii` are taken everywhere
+  ([the table](README.md#cli)).
+  Upgrading: drop the option from the command that does not read it, or move
+  what every run repeats into `.spec-graph.json`, which every command reads.
+- **A value that begins with `--` is not taken as a value.** `--ignore
+  --strict` ignored a directory called `--strict` and left the check
+  unstrict, and `--record-baseline --verbose` wrote a file of that name; each
+  option that takes a value now says `--ignore needs a value, and --strict
+  reads as an option`, and so does one followed by `-h` or `-v`.
+  Upgrading: give the value, or for a name that does begin with two dashes
+  write `./--name` for a file, `[-]-name` in a pattern and `\--name` for a
+  reference target.
+- **`CI` no longer turns colour off.** With `CI` set and stdout a terminal the
+  report was plain; it is coloured there, as spec-brief's and spec-guard's
+  are, and where stdout is no terminal it is plain as before.
+  Upgrading: set `NO_COLOR=1` or pass `--no-color` where a pipeline's
+  terminal should stay plain.
+
+### Fixed
+
+- `SPEC_GRAPH_ASCII=0`, `false` and a blank value no longer turn ASCII glyphs
+  on: the variable was read for being set. `--help` and the README name it
+  beside `--ascii`, and the README says how colour is decided; neither was
+  written anywhere.
+- An empty `--baseline` or `--record-baseline` is refused by the option's
+  name, `--baseline expects a file, got ""`, where the line was `cannot read
+  the baseline : EISDIR: illegal operation on a directory, read`. Exit 2, as
+  before.
+- An empty name given to `diff` is refused as `diff expects a graph export on
+  each side, got "" for the first`, where the line was `cannot read : EISDIR`.
+  Exit 2, as before.
+
+## 0.13.1
+
+A reader that closed the output, as `| head` does, was answered with
+`unexpected error:` and a stack; it is one line now, and still exit 2.
+
+### Fixed
+
+- **A reader that closes the output is answered in one line, not a stack.**
+  `spec-graph graph | head` ended with `spec-graph: unexpected error: Error:
+  EPIPE: broken pipe, write` and a stack once `head` had left before the
+  graph was written; it now prints `spec-graph: stdout was closed before all
+  of the output was written` on stderr, from every command. The exit code is
+  2, as it was
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+
 ## 0.13.0
 
 An error spec-graph did not expect ended the run with exit 1, which reads as

package/README.md

@@ -869,7 +869,8 @@ SARIF — and is 8 unless set; `0` lists none.
 
 A broken config stops the run with exit `2`, each problem named on stderr:
 invalid JSON, a value of the wrong type, an unknown key, a rule that does not
-compile. Why a mistake stops the run:
+compile, a family name no family has, a file that is there and cannot be read.
+Why a mistake stops the run:
 
 - A configuration that did not load checks a different repository than the one
   configured, and would report *that* one as consistent: a `{1.phse}` for
@@ -986,6 +987,37 @@ Every specification cites RFC 2119. In a repository that also keeps its own
 `families` is the stronger statement — *these* are the families this repository
 has — and turns every other noun-number construct back into prose.
 
+Each entry, and each `--family` or `--ignore-family`, is one family's name:
+the prefix its identifiers are written with, `ADR` for `ADR-0007`, in any case.
+A name no family has — `""`, or `"ADR,RFC"` where two entries go — stops the
+run with exit `2`: alone in `families` it allowed nothing, so every citation
+was prose and a dangling one passed.
+
+A name that is a family's, and that no document here belongs to, allows
+nothing either. `--family RFC` in a repository of ADRs, or `ADRS` for `ADR`,
+leaves every citation as prose, and the check would report a consistent graph
+over a citation of an ADR nobody wrote. So a list has to name a family a
+document belongs to, or the check stops with exit `2`, before it reports or
+records anything:
+
+```text
+spec-graph: no document here belongs to a family named by --family (RFC); the documents here belong to ADR
+  name a family the documents belong to, or leave the list out
+```
+
+A document belongs to a family when its identifier is written with it, as
+`ADR-0007` is with `ADR`. A list that names such a family beside one the
+documents do belong to is a family the repository means to start, or a typo in
+half the list: it is said on stderr and fails nothing.
+
+```text
+spec-graph: no document here belongs to RFC, named by --family; the documents here belong to ADR
+```
+
+A list whose every name has a document sees neither line. `ignoreFamilies`
+needs no such check: a name on it passes over citations of that family alone,
+so a mistyped one passes over nothing and the run reports more, not less.
+
 Both are consulted only after resolution has already failed, so `RFC 0001` still
 resolves to your local RFC-0001 with `RFC` on the ignore list. No configuration
 can delete an edge. See
@@ -1025,15 +1057,18 @@ spec-graph diff <before> <after>     Compare two JSON graph exports.
                         its directory is the root
 --ignore <glob>         Skip paths (repeatable)
 --ignore-ref <glob>     Do not report these reference targets (repeatable)
---family <name>         Families a bare identifier may name (repeatable)
---ignore-family <name>  Families that are never citations (repeatable)
+--family <name>         Families a bare identifier may name (repeatable, one
+                        name each time)
+--ignore-family <name>  Families that are never citations (repeatable, one
+                        name each time)
 --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 <fmt>          human | json | sarif (check) | github (check)
-                        | gitlab (check) | markdown (check, diff)
+--format <fmt>          human | json (check, query, diff) | sarif (check)
+                        | github (check) | gitlab (check)
+                        | markdown (check, diff)
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -1041,7 +1076,7 @@ spec-graph diff <before> <after>     Compare two JSON graph exports.
 --max <n>               Show at most n findings
 --max-warnings <n>      Fail when warnings exceed n
 --color / --no-color    Force colour
---ascii                 ASCII glyphs only
+--ascii                 ASCII glyphs only, as SPEC_GRAPH_ASCII=1 asks too
 --verbose               Include parse problems
 ```
 
@@ -1049,7 +1084,60 @@ Exit codes: `0` clean, `1` findings, `2` the tool could not run. A mistyped flag
 never masquerades as a passing build, and neither does a pattern that matches
 nothing, a configuration file that did not load, or a `--baseline` that is not
 there. An error spec-graph did not expect is `2` as well, never findings: it is
-reported on stderr as `spec-graph: unexpected error:` with its stack.
+reported on stderr as `spec-graph: unexpected error:` with its stack. So is a
+stdout its reader closed before all of the output was written, as a pipeline
+into `head` does: the answer did not arrive, and one line on stderr says so.
+
+**An input that is set and names nothing is refused**: exit `2` and one line
+that names it, never a run that reads it as if it had not been given. An unset
+variable in `--family "$FAMILIES"` is the usual way to write one:
+
+- a `--family` or `--ignore-family` holding a name no family has - empty,
+  blank, or a list such as `ADR,RFC` where one name goes. Alone on the
+  allowlist it would leave every citation as prose, and a dangling one
+  unreported;
+- a `--root` that is empty, is not there, or is a file, for every command
+  that reads one, `rules` included;
+- an empty or blank `--baseline`, `--record-baseline`, `--ignore`,
+  `--ignore-ref`, `--history` or pattern;
+- a list of families, `--family` or `families`, none of which a document
+  here belongs to ([Family rules](#family-rules));
+- a second word after `rules`, which takes one rule id, and an empty name
+  given to `diff`;
+- `--format json` asked of `graph`, whose JSON is `--graph-format json`, or
+  of `rules`, which has one format;
+- an option given to a command that does not read it, in the table below;
+- a value that begins with `--`, which reads as the option after one whose
+  value was forgotten: `--ignore --strict` would ignore a directory called
+  `--strict`, and `--record-baseline --verbose` write a file of that name.
+  A name that does begin so is written `./--name` for a file, `[-]-name` in
+  a pattern and `\--name` for a reference target;
+- a configuration file that is there and cannot be read, a directory called
+  `.spec-graph.json` among them.
+
+An option belongs to the commands that read it. Any other command refuses it
+by name, `--strict belongs to check, not to query`, rather than run as if the
+option were absent: `query --strict` would be no stricter, `graph
+--record-baseline` would write no file, and with the command forgotten,
+`spec-graph --graph-format mermaid > graph.mmd` would write the check's report
+into the file.
+
+| Option | Read by |
+| --- | --- |
+| `--root`, `--verbose` | `check`, `query`, `graph`, `rules` |
+| `--ignore`, `--history` | `check`, `query`, `graph` |
+| `--format` | `check`, `query`, `diff` |
+| `--graph-format`, `--documents-only` | `graph` |
+| `--explain` | `rules` |
+| `--ignore-ref`, `--family`, `--ignore-family`, `--baseline`, `--record-baseline`, `--ratchet`, `--rule`, `--strict`, `--max`, `--max-warnings`, `--color` | `check` |
+| `--no-config`, `--no-color`, `--ascii`, `--help`, `--version` | every command |
+
+`--no-config`, `--no-color` and `--ascii` are taken by every command because
+each is true already of a command with nothing to read it for: only a check
+colours its report or draws a glyph, and `diff` reads no configuration. A
+script can pass them to whatever it runs. The configuration file is not an
+option: `ignoreReferences` in `.spec-graph.json` stops no `graph`, which
+draws the same graph with it as without.
 
 **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
@@ -1059,6 +1147,18 @@ to whatever the developer already uses rather than to this tool:
 npx --no-install @descent-vtt/spec-graph --format json | jq -r '.summary'
 ```
 
+### Colour and glyphs
+
+`--color` and `--no-color` decide, then the environment, in this order:
+`NO_COLOR` set and not empty turns colour off; `FORCE_COLOR` set and not empty
+turns it on, and `0` turns it off; a `TERM` of `dumb` turns it off; otherwise
+the report is coloured when stdout is a terminal. `CI` is not read.
+
+`--ascii` draws the report in ASCII glyphs, and so does `SPEC_GRAPH_ASCII`
+set to anything but `0`, `false` or nothing. Without either, a Windows console
+that sets neither `WT_SESSION` nor `TERM_PROGRAM` gets ASCII and every other
+terminal the box-drawing characters.
+
 ## In CI
 
 The exit code is the contract: `0` clean, `1` findings, `2` the tool could not
@@ -1318,9 +1418,9 @@ tools share, whose code is copied into `src/vendor/` and checked by hash rather
 than installed. So the whole package is auditable in an afternoon — and nothing
 in the pipeline can take longer than its input.
 
-**Verified, not just covered.** 2,074 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 2,141 tests; 99.4% statement and 99.8% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation
-score - 96.38% over 8,544 mutants, measured by CI's full sweep, and a build
+score - 96.50% over 8,832 mutants, measured by CI's full sweep, and a build
 fails under 93 - because a vocabulary entry or a boundary
 condition can be weakened by an ordinary-looking refactor without a single test
 going red. [ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) is straight about what

package/bin/spec-graph.js

@@ -8,8 +8,15 @@ import { pathToFileURL } from 'node:url';
 // main answers the errors it awaits with exit 2. What nothing awaits - a
 // stream's error, a timer's, a promise nobody holds - Node ends with exit 1,
 // which a script reads as findings: the same answer for those.
+//
+// A reader that closed stdout, as `| head` does, is no defect, and it arrives
+// here, as the stream's error: one line, with no stack to send a person
+// looking for a bug. The code alone names it, since stdout and stderr are the
+// only pipes spec-graph writes to, and a line about a closed stderr reaches
+// nobody.
 process.on('uncaughtException', (error) => {
-  process.stderr.write(`spec-graph: unexpected error: ${error?.stack ?? error}\n`);
+  const said = error?.code === 'EPIPE' ? 'stdout was closed before all of the output was written' : `unexpected error: ${error?.stack ?? error}`;
+  process.stderr.write(`spec-graph: ${said}\n`);
   process.exit(2);
 });
 

package/dist/cli.d.ts

@@ -78,7 +78,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|project:rule> [patterns...] [options]\n  spec-graph graph [patterns...] [--graph-format dot|mermaid|json]\n  spec-graph rules [rule-id] [--explain]\n  spec-graph diff <before.json> <after.json> [--format human|json|markdown]\n\nCOMMANDS\n  check     Validate the specification graph. The default.\n  query     Run a selector - or a registered project rule, by its id - and\n            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. Name one\n            to see only that one; --explain adds its selector and the ADR that\n            decided it.\n  diff      Compare two graph exports: documents added, removed, moved or\n            accepted; relations added or removed; and obligations resolved or\n            reopened where they can be told apart. Make both exports with the\n            same spec-graph. Exits 0 whether anything changed or not.\n\nOPTIONS\n  --root <dir>            Directory the patterns resolve against. Without it,\n                          .spec-graph.json is looked for in the working\n                          directory and then upward as far as the repository,\n                          and the directory holding it becomes the root - so a\n                          run from a subdirectory reports what a run from the\n                          top reports. Paths typed on the command line stay\n                          relative to where they were typed.\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. The file has to be there: a\n                          path that reads nothing accepts nothing and says so\n                          nowhere. A \"baseline\" in the configuration may name a\n                          file not recorded yet; a path typed here may not.\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, sarif, github, gitlab or markdown. sarif\n                          is the interchange format GitHub code scanning and\n                          editors already read, github the workflow commands a\n                          GitHub Actions log turns into annotations, and gitlab\n                          the Code Quality report a GitLab merge request reads,\n                          all three for check; markdown is a table for a\n                          pull-request comment or $GITHUB_STEP_SUMMARY, for\n                          check or diff (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 regular expression, matched by an automaton that cannot\n               backtrack: linear in the subject, whatever the pattern. It reads\n               the usual syntax minus backreferences and lookaround, which are\n               not regular - both are refused when the selector is read, with\n               the character pointed at\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      \"maxRelated\": 3 }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it. maxRelated has no flag: it caps how many related locations one\n  finding lists, 8 unless set, and 0 lists none.\n\n  A problem in that file stops the run with exit 2, named on stderr: invalid\n  JSON, an unknown key, a rule that does not compile. A configuration that did\n  not load checks a different repository than the one configured, and would\n  report that one as consistent. --no-config runs on defaults instead.\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\n  To see what one matches without copying its selector out of the file:\n\n    spec-graph query project:no-draft-dependency --verbose\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 rules ghost-handover --explain      # and why it exists\n  spec-graph check --rule project:no-draft-dependency=off\n  spec-graph query project:no-draft-dependency   # what does that rule match?\n  spec-graph check --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n  spec-graph check --format github             # annotations from an Actions log\n  spec-graph check --format gitlab > gl-code-quality-report.json\n  spec-graph diff base.json head.json --format markdown >> \"$GITHUB_STEP_SUMMARY\"\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|project:rule> [patterns...] [options]\n  spec-graph graph [patterns...] [--graph-format dot|mermaid|json]\n  spec-graph rules [rule-id] [--explain]\n  spec-graph diff <before.json> <after.json> [--format human|json|markdown]\n\nCOMMANDS\n  check     Validate the specification graph. The default.\n  query     Run a selector - or a registered project rule, by its id - and\n            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. Name one\n            to see only that one; --explain adds its selector and the ADR that\n            decided it.\n  diff      Compare two graph exports: documents added, removed, moved or\n            accepted; relations added or removed; and obligations resolved or\n            reopened where they can be told apart. Make both exports with the\n            same spec-graph. Exits 0 whether anything changed or not.\n\nOPTIONS\n  --root <dir>            Directory the patterns resolve against. Without it,\n                          .spec-graph.json is looked for in the working\n                          directory and then upward as far as the repository,\n                          and the directory holding it becomes the root - so a\n                          run from a subdirectory reports what a run from the\n                          top reports. Paths typed on the command line stay\n                          relative to where they were typed. It has to be a\n                          directory that is there.\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: one\n                          name each time, the prefix its identifiers are\n                          written with, ADR for ADR-0007. A document here has\n                          to belong to one of them, or the check stops: a list\n                          that names none allows nothing.\n  --ignore-family <name>  Families that are never citations - RFC when the repo\n                          cites RFC 2119 and keeps its own RFCs. Repeatable,\n                          one name each time.\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. The file has to be there: a\n                          path that reads nothing accepts nothing and says so\n                          nowhere. A \"baseline\" in the configuration may name a\n                          file not recorded yet; a path typed here may not.\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, sarif, github, gitlab or markdown. json\n                          is for check, query or diff. sarif is the interchange\n                          format GitHub code scanning and editors already read,\n                          github the workflow commands a GitHub Actions log\n                          turns into annotations, and gitlab the Code Quality\n                          report a GitLab merge request reads, all three for\n                          check; markdown is a table for a pull-request comment\n                          or $GITHUB_STEP_SUMMARY, for check or diff (default:\n                          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. SPEC_GRAPH_ASCII asks for the\n                          same, unless it is empty, 0 or false\n  --verbose               Include parse problems, per-file detail, and every\n                          reference --ignore-ref or --ignore-family silenced\n  --explain               With rules: add each rule's selector and the ADR\n                          that decided it\n  -h, --help              Show this help\n  -v, --version           Show the version\n\n  An option belongs to the commands that read it, and any other command\n  refuses it by name:\n\n    --root, --verbose                   check, query, graph, rules\n    --ignore, --history                 check, query, graph\n    --format                            check, query, diff\n    --graph-format, --documents-only    graph\n    --explain                           rules\n    every other option                  check\n\n  --no-config, --no-color and --ascii are taken by every command: each is\n  true already of a command with nothing to read it for.\n\n  A value that begins with -- reads as an option, so the option before it is\n  refused as missing its value. A name that does begin so is written ./--name\n  for a file, [-]-name in a pattern and \\--name for a reference target.\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 regular expression, matched by an automaton that cannot\n               backtrack: linear in the subject, whatever the pattern. It reads\n               the usual syntax minus backreferences and lookaround, which are\n               not regular - both are refused when the selector is read, with\n               the character pointed at\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\n  An input that is set and names nothing is a 2, named on stderr, and never\n  read as if it had not been given: an empty value, a family name no family\n  has, a list of families no document here belongs to, a --root that is no\n  directory, a second word after rules, an option of another command.\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      \"maxRelated\": 3 }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it. maxRelated has no flag: it caps how many related locations one\n  finding lists, 8 unless set, and 0 lists none.\n\n  A problem in that file stops the run with exit 2, named on stderr: invalid\n  JSON, an unknown key, a rule that does not compile, a file that is there and\n  cannot be read. A configuration that did not load checks a different\n  repository than the one configured, and would report that one as consistent.\n  --no-config runs on defaults instead.\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\n  To see what one matches without copying its selector out of the file:\n\n    spec-graph query project:no-draft-dependency --verbose\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 rules ghost-handover --explain      # and why it exists\n  spec-graph check --rule project:no-draft-dependency=off\n  spec-graph query project:no-draft-dependency   # what does that rule match?\n  spec-graph check --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n  spec-graph check --format github             # annotations from an Actions log\n  spec-graph check --format gitlab > gl-code-quality-report.json\n  spec-graph diff base.json head.json --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n";
 /** Parses argv into options. Throws {@link UsageError} on anything malformed. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
 /**
@@ -90,5 +90,12 @@ export declare function parseArgs(argv: readonly string[], cwd: string): CliOpti
  * error, exit 1, which CI reads as findings. The stack is what makes a report
  * of it something to act on, and it goes to stderr alone: a script that reads
  * a document from stdout is handed no part of one.
+ *
+ * A write its reader had closed the pipe for is not such an error: the answer
+ * was not delivered, which is still 2, and nothing in spec-graph is at fault,
+ * so it is said in a line and no stack sends a person looking for a defect.
+ * The process's own streams report it as an event, which the launcher answers
+ * in the same words; here it is a caller's stream that throws it. It is read
+ * by its code: stdout and stderr are the only pipes spec-graph writes to.
  */
 export declare function main(io?: CliIO): Promise<number>;