@descent-vtt/spec-graph 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -11,6 +11,70 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.16.0
+
+`--color` beside `--no-color` is refused, exit 2, where the later of the
+two decided and the earlier went unread, as `--ascii` beside `--no-ascii`
+already was.
+
+### Changed
+
+- **`--color` beside `--no-color` is refused.** The later of the two
+  decided and the earlier went unread, with no word of it: `check --color
+  --no-color` printed a report without colour and `check --no-color --color`
+  one with it. Given together, in either order and in every format of a
+  check, they are exit `2` now, `--color is given beside --no-color, and a
+  report is coloured or it is not: give one of the two`, as `--ascii` beside
+  `--no-ascii` is since 0.15.0. Those are the two pairs the command line
+  has, so every option given beside its own opposite is refused. Either
+  alone wins over `NO_COLOR`, `FORCE_COLOR` and the terminal as before, the
+  same option twice is that option once, and `--help` and `--version` are
+  answered first
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+  Upgrading: where a script adds `--no-color` or `--color` to a command line
+  that may already hold the other, keep the one the run should have and drop
+  the other.
+
+## 0.15.0
+
+A list of families that names one no document belongs to, and leaves out
+one the documents do belong to, stops the check, exit 2: `RFCS` written
+for `RFC` took every citation of an RFC out of the check, which reported a
+consistent graph. And `--no-ascii` asks for the Unicode glyphs outright.
+
+### Added
+
+- **`--no-ascii` asks for the Unicode glyphs outright.** `--ascii` and
+  `SPEC_GRAPH_ASCII` ask for ASCII, and nothing asked for the other set: on
+  Windows a console that sets neither `WT_SESSION` nor `TERM_PROGRAM` got
+  ASCII whatever was to draw the report. `--no-ascii` draws the Unicode
+  glyphs on any platform and wins over the variable and over the console,
+  as `--ascii` wins the other way. It is a check's option, as `--color` is:
+  the other commands draw no glyph and refuse it by name, `--no-ascii
+  belongs to check, not to query`, and take `--ascii` as before. The two
+  given together are refused, exit `2`
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+
+### Changed
+
+- **A list of families that mistypes one of them stops the check.**
+  `--family ADR --family RFCS`, in a repository of ADRs and RFCs, left the
+  RFCs' own family off the list, so every citation of an RFC was prose:
+  `check` printed `the specification graph is consistent` over a citation of
+  an RFC nobody wrote, under `--strict` too, where the run without the list
+  exits `1`, and all that said so was a line on stderr. Where a list names a
+  family no document here belongs to and leaves out a family the documents
+  do belong to, the check is exit `2` now, for `--family` and `families`
+  alike, and the line names both. A name with no document on a list that
+  leaves no such family out is said on stderr and fails nothing, as before:
+  a family listed before its first document, or one whose documents the run
+  does not read
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+  Upgrading: write the name as the documents carry it, `RFC` for
+  `RFC-0007`. Where the family is left out on purpose and the other name is
+  one not started yet, say so with `--ignore-family` or `ignoreFamilies`, or
+  leave the new name off the list until its first document is written.
+
 ## 0.14.1
 
 `FORCE_COLOR=false` forced colour on, and a Windows console with

package/README.md

@@ -1006,15 +1006,34 @@ spec-graph: no document here belongs to a family named by --family (RFC); the do
 ```
 
 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.
+`ADR-0007` is with `ADR`. One name with no document, beside names that have
+them, stops the check where the list also leaves out a family the documents do
+belong to. `--family ADR --family RFCS`, in a repository of ADRs and RFCs,
+passes over every citation of an RFC, and the check that fails without the
+list would report a consistent graph. One name is most likely meant for the
+other, so the line names both, and the exit is `2`:
+
+```text
+spec-graph: no document here belongs to RFCS, named by --family; the documents here belong to ADR and RFC, and the list leaves out RFC
+  name each family as its documents do, or leave it off the list until its first document is written
+```
+
+Where every family the documents belong to is on the list, a further name with
+no document is a family the repository means to start, or one whose documents
+this run does not read. The list then passes over nothing the run would have
+read without it, so the name 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`
+A family on `ignoreFamilies` was taken out on purpose and is not one the list
+leaves out. A list that is narrower on purpose, `--family ADR` over ADRs and
+RFCs, has no name without a document and sees no line; where it also names a
+family not started yet, `ignoreFamilies` is how it says which family it leaves
+out on purpose.
+
+A list whose every name has a document sees none of them. `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.
 
@@ -1075,8 +1094,8 @@ spec-graph diff <before> <after>     Compare two JSON graph exports.
 --strict                Raise every warning to an error
 --max <n>               Show at most n findings
 --max-warnings <n>      Fail when warnings exceed n
---color / --no-color    Force colour
---ascii                 ASCII glyphs only, as SPEC_GRAPH_ASCII=1 asks too
+--color / --no-color    Force colour on or off; one of the two, not both
+--ascii / --no-ascii    ASCII glyphs or Unicode ones; SPEC_GRAPH_ASCII=1 asks for ASCII
 --verbose               Include parse problems
 ```
 
@@ -1101,12 +1120,16 @@ variable in `--family "$FAMILIES"` is the usual way to write one:
 - 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));
+  here belongs to, or one that names a family with no document and leaves
+  out a family the documents do belong 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;
+- an option beside its own opposite, `--color` beside `--no-color` or
+  `--ascii` beside `--no-ascii`, in either order: the later would decide and
+  the earlier go unread ([Colour and glyphs](#colour-and-glyphs));
 - 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.
@@ -1129,15 +1152,17 @@ into the file.
 | `--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` |
+| `--ignore-ref`, `--family`, `--ignore-family`, `--baseline`, `--record-baseline`, `--ratchet`, `--rule`, `--strict`, `--max`, `--max-warnings`, `--color`, `--no-ascii` | `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.
+script can pass them to whatever it runs. `--color` and `--no-ascii` are a
+check's alone: taken by a query, each would say the query drew what only a
+check draws. 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
@@ -1155,11 +1180,33 @@ npx --no-install @descent-vtt/spec-graph --format json | jq -r '.summary'
 else that is not empty turns it on; 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`, or sets them to nothing,
-gets ASCII and every other terminal the Unicode glyphs, `✖`, `⚠`, `↳` and
-the like.
+`--ascii` draws the report in ASCII glyphs and `--no-ascii` in the Unicode
+ones, `✖`, `⚠`, `↳` and the like, on any platform and whatever the
+environment says. `--no-ascii` belongs to `check`, as `--color` does; a format
+of a check that draws no glyph takes it all the same.
+
+An option given beside its own opposite is refused, exit `2`, whichever of
+the two comes first and in every format of a check:
+
+```text
+spec-graph: --color is given beside --no-color, and a report is coloured or it is not: give one of the two
+spec-graph: --ascii is given beside --no-ascii, and the glyphs are drawn one way: give one of the two
+```
+
+The later of the two would decide and the earlier go unread, and a script
+that adds `--no-color` to a line already holding `--color` would be told
+nothing of which it got. Those are the two pairs the command line has; no
+other option has an opposite to be given beside. Either of a pair alone wins
+over the environment, which is what it is for, and the same option given
+twice is that option once. `--help` and `--version` are answered whatever
+else is on the line.
+
+Without either, `SPEC_GRAPH_ASCII` set to anything but `0`, `false` or nothing
+asks for ASCII; and without that, a Windows console that sets neither
+`WT_SESSION` nor `TERM_PROGRAM`, or sets them to nothing, gets ASCII and every
+other terminal the Unicode glyphs. Where those two variables say nothing of
+the terminal that draws the report, `--no-ascii` asks for the Unicode glyphs
+outright.
 
 ## In CI
 
@@ -1420,9 +1467,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,148 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 2,264 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.50% over 8,841 mutants, measured by CI's full sweep, and a build
+score - 96.56% over 8,901 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/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. 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";
+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. It stops too where\n                          a name has no document and the list leaves out a\n                          family the documents do belong to, as RFCS for RFC\n                          does: one is most likely meant for the other.\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, whatever NO_COLOR, FORCE_COLOR\n                          and the terminal say. The two together are refused\n  --ascii / --no-ascii    ASCII glyphs or Unicode ones. SPEC_GRAPH_ASCII asks\n                          for ASCII, unless it is empty, 0 or false. Either\n                          option wins over it, and over what the terminal is\n                          taken for. The two together are refused\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. --color and\n  --no-ascii are not: each would say that a command drew what only a check\n  draws.\n\n  An option beside its own opposite is refused, whichever comes first:\n  --color beside --no-color, and --ascii beside --no-ascii. The later would\n  decide and the earlier go unread. Either alone wins over the environment,\n  and the same option twice is that option once.\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. So is\n  an option beside its own opposite, of which one would go unread.\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;
 /**

package/dist/cli.js

@@ -73,7 +73,10 @@ OPTIONS
                           name each time, the prefix its identifiers are
                           written with, ADR for ADR-0007. A document here has
                           to belong to one of them, or the check stops: a list
-                          that names none allows nothing.
+                          that names none allows nothing. It stops too where
+                          a name has no document and the list leaves out a
+                          family the documents do belong to, as RFCS for RFC
+                          does: one is most likely meant for the other.
   --ignore-family <name>  Families that are never citations - RFC when the repo
                           cites RFC 2119 and keeps its own RFCs. Repeatable,
                           one name each time.
@@ -108,9 +111,12 @@ OPTIONS
   --max-warnings <n>      Fail when warnings exceed n (default: no limit)
   --strict                Raise every warning to an error. An explicit --rule
                           still wins, so --strict --rule x=warn exempts x.
-  --color / --no-color    Force colour on or off
-  --ascii                 Use ASCII glyphs only. SPEC_GRAPH_ASCII asks for the
-                          same, unless it is empty, 0 or false
+  --color / --no-color    Force colour on or off, whatever NO_COLOR, FORCE_COLOR
+                          and the terminal say. The two together are refused
+  --ascii / --no-ascii    ASCII glyphs or Unicode ones. SPEC_GRAPH_ASCII asks
+                          for ASCII, unless it is empty, 0 or false. Either
+                          option wins over it, and over what the terminal is
+                          taken for. The two together are refused
   --verbose               Include parse problems, per-file detail, and every
                           reference --ignore-ref or --ignore-family silenced
   --explain               With rules: add each rule's selector and the ADR
@@ -129,7 +135,14 @@ OPTIONS
     every other option                  check
 
   --no-config, --no-color and --ascii are taken by every command: each is
-  true already of a command with nothing to read it for.
+  true already of a command with nothing to read it for. --color and
+  --no-ascii are not: each would say that a command drew what only a check
+  draws.
+
+  An option beside its own opposite is refused, whichever comes first:
+  --color beside --no-color, and --ascii beside --no-ascii. The later would
+  decide and the earlier go unread. Either alone wins over the environment,
+  and the same option twice is that option once.
 
   A value that begins with -- reads as an option, so the option before it is
   refused as missing its value. A name that does begin so is written ./--name
@@ -163,7 +176,8 @@ EXIT CODES
   An input that is set and names nothing is a 2, named on stderr, and never
   read as if it had not been given: an empty value, a family name no family
   has, a list of families no document here belongs to, a --root that is no
-  directory, a second word after rules, an option of another command.
+  directory, a second word after rules, an option of another command. So is
+  an option beside its own opposite, of which one would go unread.
 
 CONFIGURATION
   Anything repeated on every run belongs in the repository rather than in the
@@ -263,7 +277,11 @@ const SEVERITIES = ['error', 'warn', 'info', 'off'];
  * Each is true already of what the commands that do not read it write - none
  * of them colours or draws a glyph, and `diff` reads no configuration - and
  * a script passes them to every command it runs. `--color` is not one of
- * them: it would promise colour that only a check prints.
+ * them: it would promise colour that only a check prints. Nor is
+ * `--no-ascii`, for the same reason: taken by a query, it would say the
+ * Unicode glyphs were drawn where none is. An option is refused where
+ * taking it would say what is not so, and taken where it asks a command to
+ * leave out what it never does (spec-core's ADR-0005, 2026-10-11).
  *
  * A function and not a table, so that none of it runs when the module loads:
  * a mutant of a table built at import pays for the whole suite (ADR-0007).
@@ -294,10 +312,33 @@ function readersOf(option) {
         case '--max':
         case '--max-warnings':
         case '--color':
+        case '--no-ascii':
             return ['check'];
     }
     return undefined;
 }
+/**
+ * The option that undoes this one, or nothing for an option that has none.
+ *
+ * Given both, the later decided and the earlier went unread: a script that
+ * adds `--no-color` to a line already holding `--color` was told nothing of
+ * which it got, and two things of which one would go unread are refused
+ * together (spec-core's ADR-0005, 2026-10-11). Either alone still wins over
+ * the environment, which is what it is for.
+ *
+ * Asked of the affirmative alone, so each pair is found once, by the option
+ * that names it, and each name here decides a refusal. A function and not a
+ * table, for the reason `readersOf` is one.
+ */
+function oppositeOf(option) {
+    switch (option) {
+        case '--color':
+            return { option: '--no-color', decided: 'a report is coloured or it is not' };
+        case '--ascii':
+            return { option: '--no-ascii', decided: 'the glyphs are drawn one way' };
+    }
+    return undefined;
+}
 /** `a`, `a or b`, `a, b or c`: one name or more in a sentence, with the word that joins the last. */
 function listed(names, joint) {
     return names.length < 2 ? names[0] : `${names.slice(0, -1).join(', ')} ${joint} ${names[names.length - 1]}`;
@@ -409,6 +450,9 @@ export function parseArgs(argv, cwd) {
             case '--ascii':
                 ascii = true;
                 break;
+            case '--no-ascii':
+                ascii = false;
+                break;
             case '--documents-only':
                 documentsOnly = true;
                 break;
@@ -485,8 +529,10 @@ export function parseArgs(argv, cwd) {
                 const equals = value.indexOf('=');
                 if (equals === -1)
                     throw new UsageError(`--rule expects <id>=<severity>, got "${value}"`);
-                const id = value.slice(0, equals);
-                const level = value.slice(equals + 1);
+                const before = value.slice(0, equals);
+                const after = value.slice(equals + 1);
+                const id = before;
+                const level = after;
                 // A project rule is taken on its namespace here and checked for real
                 // once the configuration defining it has been read: arguments are
                 // parsed before any file is opened, and a flag has to be usable on that
@@ -540,6 +586,15 @@ export function parseArgs(argv, cwd) {
                 throw new UsageError(`${option} belongs to ${listed(readers, 'or')}, not to ${command}`);
             }
         }
+        // After the loop above, so that an option of another command is named
+        // before the pair it is half of: `query --color --no-color` is told
+        // that `--color` is a check's, which is the line to act on first.
+        for (const option of given) {
+            const opposite = oppositeOf(option);
+            if (opposite !== undefined && given.has(opposite.option)) {
+                throw new UsageError(`${option} is given beside ${opposite.option}, and ${opposite.decided}: give one of the two`);
+            }
+        }
     }
     // The second word given to `rules` was dropped, so `rules a b` listed `a`
     // and said nothing of `b`.
@@ -787,8 +842,10 @@ async function run(io, err) {
     const patterns = typed.patterns.length > 0 ? typed.patterns : (file.patterns ?? DEFAULT_PATTERNS);
     const severityOverrides = { ...(file.severities ?? {}), ...options.severities };
     const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false), projectRules);
-    // The list the check is held against, once it has read the documents.
+    // The list the check is held against, once it has read the documents, and
+    // the families taken out on purpose, which that list is not held to.
     const families = [...(file.families ?? []), ...options.families];
+    const ignoreFamilies = [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies];
     const analyseOptions = {
         root,
         patterns,
@@ -800,7 +857,7 @@ async function run(io, err) {
         ignore: [...(file.ignore ?? []), ...typed.ignore],
         ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],
         families,
-        ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],
+        ignoreFamilies,
         historyPatterns: [...(file.historyPatterns ?? []), ...typed.history],
         severities,
         projectRules,
@@ -871,10 +928,19 @@ async function run(io, err) {
             // has: every citation is then prose, and the run that failed on a
             // dangling one reported a consistent graph - for `--family ADRS` as it
             // did for `--family ""`. Nothing was measured, which is not clean
-            // (spec-core's ADR-0005), so the run stops before it says anything. A
-            // list that names such a family beside one the corpus has is a family
-            // the repository means to start, or a typo in half of it: said, and
-            // nothing fails.
+            // (spec-core's ADR-0005), so the run stops before it says anything.
+            //
+            // One such name beside names that have documents costs the run a
+            // finding only where the list also leaves out a family the documents
+            // do belong to: `ADR` and `RFCS` over ADRs and RFCs pass over every
+            // citation of an RFC, and the run that fails without the list reports
+            // a consistent graph. One name is most likely meant for the other, and
+            // the run stops there too. Where every family the corpus has is on the
+            // list, the name is a family the repository means to start, or one
+            // whose documents this run does not read; the list passes over nothing
+            // the run would have read without it, so it is said, and nothing
+            // fails. A family on `--ignore-family` was taken out on purpose, and
+            // is not one the list leaves out (ADR-0010, 2026-10-12).
             const allowed = [...new Set(families.map((family) => family.trim().toUpperCase()))];
             const absent = allowed.filter((family) => !result.corpus.families.includes(family));
             if (absent.length > 0) {
@@ -884,11 +950,19 @@ async function run(io, err) {
                 if (file.families !== undefined && file.families.length > 0)
                     lists.push(`"families" in ${loaded.source}`);
                 const here = `the documents here belong to ${result.corpus.families.length > 0 ? listed(result.corpus.families, 'and') : 'no family'}`;
+                const named = lists.join(' and ');
                 if (absent.length === allowed.length) {
-                    err(`spec-graph: no document here belongs to a family named by ${lists.join(' and ')} (${allowed.join(', ')}); ${here}\n  name a family the documents belong to, or leave the list out\n`);
+                    err(`spec-graph: no document here belongs to a family named by ${named} (${allowed.join(', ')}); ${here}\n  name a family the documents belong to, or leave the list out\n`);
+                    return EXIT_ERROR;
+                }
+                const ignored = ignoreFamilies.map((family) => family.trim().toUpperCase());
+                const left = result.corpus.families.filter((family) => !allowed.includes(family) && !ignored.includes(family));
+                const said = `spec-graph: no document here belongs to ${listed(absent, 'or')}, named by ${named}; ${here}`;
+                if (left.length > 0) {
+                    err(`${said}, and the list leaves out ${listed(left, 'and')}\n  name each family as its documents do, or leave it off the list until its first document is written\n`);
                     return EXIT_ERROR;
                 }
-                err(`spec-graph: no document here belongs to ${listed(absent, 'or')}, named by ${lists.join(' and ')}; ${here}\n`);
+                err(`${said}\n`);
             }
             // Recording is not checking. It writes down what is wrong today so that
             // tomorrow can be compared against it, and says nothing about whether