@descent-vtt/spec-graph 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -11,6 +11,65 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.17.0
+
+Two things of which one went unread are refused, exit 2: an option that
+takes one value given two, `--baseline` beside `--record-baseline`, and a
+family given to both `--family` and `--ignore-family`. And a negation is
+read whatever mark stands after it: `Blocked by none: [ADR-0002](0002.md)`
+was a `blocked-by` edge, the opposite of its sentence.
+
+### Changed
+
+- **An option that takes one value is refused given two.** The later was
+  read and the earlier went unread, with no word of it: `check --root
+  nowhere --root .` checked `.` and never said that `nowhere` is not there,
+  and `query --format sarif --format json` wrote JSON where the two the
+  other way round are refused. `--root`, `--baseline`, `--record-baseline`,
+  `--format`, `--graph-format`, `--max` and `--max-warnings` given two
+  values, and one rule given two severities by `--rule`, are exit `2` now,
+  with a line that names both: `--root is given "nowhere" and ".", and takes
+  one value: give one of the two`. The same value twice is that value once,
+  compared as typed, an option that is repeatable takes each of its values
+  as before, 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 such an option to a command line that may
+  already hold it, keep the value the run should have and drop the other.
+- **`--baseline` beside `--record-baseline` is refused.** A recording writes
+  every finding of the run and opens no baseline, so the file `--baseline`
+  named went unread: `check --baseline nowhere.json --record-baseline
+  out.json` recorded and exited `0`, where `--baseline nowhere.json` alone
+  is exit `2`. The two together are exit `2` now, in either order, and
+  nothing is written. A `"baseline"` in the configuration is recorded over
+  as before. Upgrading: to record, give `--record-baseline` alone; to check
+  against a baseline, `--baseline` alone.
+- **A family given to both `--family` and `--ignore-family` is refused.**
+  The list that ignores decided, and the family's name on the other said
+  nothing: `check --family ADR --ignore-family ADR` passed over every
+  citation in prose and printed `the specification graph is consistent`,
+  exit `0`, where either option alone exits `1` on a citation nobody wrote.
+  It is exit `2` now, in either order and in any case of the name, `--family
+  ADR is given beside --ignore-family ADR, and a family's citations are read
+  or they are passed over: give one of the two`. One family asked for beside
+  another ignored is taken as before. Upgrading: take the family off the
+  option that does not say what the run should do with it.
+- **A negation is read whatever mark stands after it.** A governing phrase
+  is cancelled by a negation between it and the reference, and the word was
+  read only where a space or the reference followed it: `Blocked by none:
+  [ADR-0002](0002.md)` was a `blocked-by` edge and `Deferred to nothing: see
+  [ADR-0002](0002.md)` a delegation, each the opposite of its sentence. The
+  word ends now at anything but a letter, a digit or a hyphen, a colon and a
+  dash among them, and those are citations and no more. A hyphen joins the
+  word to the next, so `blocked by the no-op in` is read as it was. A
+  `ghost-handover` or `stale-premise` such a sentence caused goes; an open
+  question in a retired document that was read as handed to a live one by
+  such a sentence is an `orphaned-obligation`, so a check that passed can
+  fail
+  ([ADR-0006](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0006-false-positives-cost-more.md)).
+  Upgrading: run `check`; where it now reports an `orphaned-obligation`, the
+  question is owed by nobody, as its sentence says: close it, or hand it to
+  a live document in so many words.
+
 ## 0.16.0
 
 `--color` beside `--no-color` is refused, exit 2, where the later of the

package/README.md

@@ -461,7 +461,10 @@ Blocked by [ADR-0009](0009-compliance.md).                       → blocked-by
 A phrase governs a reference when it stands no more than 40 characters before
 it, in the same statement: a sentence, a paragraph, a list item or a table cell.
 
-- A negation between the two - `owned by nobody` - cancels it.
+- A negation between the two - `owned by nobody` - cancels it, whatever mark
+  stands after the word: `blocked by none: [ADR-0002](0002.md)` is a citation
+  and no more. A hyphen joins the word to the next, which names a thing, so
+  `blocked by the no-op in` cancels nothing.
 - A sentence written in Chinese ends at `。`, `？`, `！` or `；`, with a space
   after it or none, so `Deferred to later。另見 ADR-0002` hands nothing to
   ADR-0002. A stop only ends a statement sooner: it reads less, never more.
@@ -1130,6 +1133,22 @@ variable in `--family "$FAMILIES"` is the usual way to write one:
 - 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));
+- an option that takes one value, given two: `--root`, `--baseline`,
+  `--record-baseline`, `--format`, `--graph-format`, `--max` or
+  `--max-warnings`, and one rule given two severities by `--rule`. The later
+  would be read and the earlier go unread: `--root nowhere --root .` would
+  check `.` and never say that `nowhere` is not there. The line names both,
+  `--root is given "nowhere" and ".", and takes one value: give one of the
+  two`. The same value twice is that value once, as typed, and an option
+  that is repeatable above takes each of its values;
+- `--baseline` beside `--record-baseline`: a recording writes every finding
+  of the run and opens no baseline, so the one to read would go unread. A
+  `"baseline"` in the configuration is no option, and is recorded over as
+  before;
+- one family given to both `--family` and `--ignore-family`, whose citations
+  are passed over whatever asked for them: alone on the allowlist it would
+  leave every citation as prose. One family asked for beside another ignored
+  is taken, since both are read;
 - 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.
@@ -1467,9 +1486,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,264 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 2,260 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.56% over 8,901 mutants, measured by CI's full sweep, and a build
+score - 96.60% over 9,004 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. 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";
+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  An option that takes one value is refused given two, as in --root a\n  --root b: the later would be read and the earlier go unread. That is each\n  option above with a value that is not marked Repeatable, and one rule\n  given two severities by --rule. The same value twice is that value once.\n\n  A baseline to read is refused beside one to record, --baseline beside\n  --record-baseline: a recording writes every finding and opens no\n  baseline. So is one family given to both --family and --ignore-family,\n  whose citations are passed over whatever asked for them. One family asked\n  for beside another ignored is taken.\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\n  are two things of which one would go unread: an option beside its own\n  opposite, an option that takes one value given two, --baseline beside\n  --record-baseline, a family both asked for and ignored.\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

@@ -144,6 +144,17 @@ OPTIONS
   decide and the earlier go unread. Either alone wins over the environment,
   and the same option twice is that option once.
 
+  An option that takes one value is refused given two, as in --root a
+  --root b: the later would be read and the earlier go unread. That is each
+  option above with a value that is not marked Repeatable, and one rule
+  given two severities by --rule. The same value twice is that value once.
+
+  A baseline to read is refused beside one to record, --baseline beside
+  --record-baseline: a recording writes every finding and opens no
+  baseline. So is one family given to both --family and --ignore-family,
+  whose citations are passed over whatever asked for them. One family asked
+  for beside another ignored is taken.
+
   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
   for a file, [-]-name in a pattern and \\--name for a reference target.
@@ -176,8 +187,10 @@ 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. So is
-  an option beside its own opposite, of which one would go unread.
+  directory, a second word after rules, an option of another command. So
+  are two things of which one would go unread: an option beside its own
+  opposite, an option that takes one value given two, --baseline beside
+  --record-baseline, a family both asked for and ignored.
 
 CONFIGURATION
   Anything repeated on every run belongs in the repository rather than in the
@@ -318,24 +331,33 @@ function readersOf(option) {
     return undefined;
 }
 /**
- * The option that undoes this one, or nothing for an option that has none.
+ * The option beside which this one goes unread, 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.
+ * Two of the three are an option and the one that undoes it. 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.
+ * The third is a baseline to read beside one to record. A recording writes
+ * every finding of the run and opens no baseline, so `--baseline nowhere.json
+ * --record-baseline out.json` recorded and exited 0, where the first option
+ * alone is refused for a file that is not there.
+ *
+ * Asked of the first of each pair 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) {
+function unreadBeside(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' };
+        case '--baseline':
+            return { option: '--record-baseline', decided: 'a check holds its findings against a baseline or records them as one' };
     }
     return undefined;
 }
@@ -415,6 +437,25 @@ export function parseArgs(argv, cwd) {
             throw new UsageError(`${flag} expects one family's name, such as ADR, got "${value}"`);
         return value;
     };
+    // What an option that takes one value was first given, and the line for
+    // the first such option given another. The later was read and the earlier
+    // went unread: `--root nowhere --root .` checked `.` and never said that
+    // `nowhere` is not there, and `query --format sarif --format json` wrote
+    // JSON where the two the other way round are refused. The same value
+    // again is that value once, as an option that takes none is. Values are
+    // compared as they were typed: a path spelled two ways is two values to
+    // whoever reads the line. The line is thrown after the loop, with what
+    // else help and the version are answered before.
+    const taken = new Map();
+    let second = null;
+    const once = (flag, value, key = flag, takes = 'takes one value') => {
+        const held = taken.get(key);
+        if (held === undefined)
+            taken.set(key, value);
+        else if (held !== value)
+            second ??= `${flag} is given "${held}" and "${value}", and ${takes}: give one of the two`;
+        return value;
+    };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === '--') {
@@ -466,7 +507,7 @@ export function parseArgs(argv, cwd) {
                 verbose = true;
                 break;
             case '--root':
-                root = filled(arg, i, 'a directory');
+                root = once(arg, filled(arg, i, 'a directory'));
                 rootExplicit = true;
                 i += 1;
                 break;
@@ -491,11 +532,11 @@ export function parseArgs(argv, cwd) {
                 i += 1;
                 break;
             case '--baseline':
-                baseline = filled(arg, i, 'a file');
+                baseline = once(arg, filled(arg, i, 'a file'));
                 i += 1;
                 break;
             case '--record-baseline':
-                recordBaseline = filled(arg, i, 'a file');
+                recordBaseline = once(arg, filled(arg, i, 'a file'));
                 i += 1;
                 break;
             case '--no-config':
@@ -512,6 +553,7 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(`--format must be human, json, sarif, markdown, gitlab or github, got "${value}"`);
                 }
                 format = value;
+                once(arg, value);
                 i += 1;
                 break;
             }
@@ -521,6 +563,7 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(`--graph-format must be dot, mermaid or json, got "${value}"`);
                 }
                 graphFormat = value;
+                once(arg, value);
                 i += 1;
                 break;
             }
@@ -544,16 +587,17 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(`unknown severity "${level}", expected one of: ${SEVERITIES.join(', ')}`);
                 }
                 severities[id] = level;
+                once(arg, value, `${arg} ${id}`, 'a rule has one severity');
                 i += 1;
                 break;
             }
             case '--max': {
-                max = parseCount(arg, next(arg, i));
+                max = parseCount(arg, once(arg, next(arg, i)));
                 i += 1;
                 break;
             }
             case '--max-warnings': {
-                maxWarnings = parseCount(arg, next(arg, i));
+                maxWarnings = parseCount(arg, once(arg, next(arg, i)));
                 i += 1;
                 break;
             }
@@ -590,9 +634,23 @@ export function parseArgs(argv, cwd) {
         // 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`);
+            const other = unreadBeside(option);
+            if (other !== undefined && given.has(other.option)) {
+                throw new UsageError(`${option} is given beside ${other.option}, and ${other.decided}: give one of the two`);
+            }
+        }
+        if (second !== null)
+            throw new UsageError(second);
+        // A family on both lists is passed over, since the list that ignores is
+        // asked first, and its name on the other says nothing: `--family ADR
+        // --family RFC --ignore-family RFC` is `--family ADR`. Where it is the
+        // only name there, every citation in prose is passed over, and the check
+        // that fails without the two reported a consistent graph. Two families,
+        // one asked for and another ignored, are both read, and are taken.
+        for (const asked of families) {
+            const ignored = ignoreFamilies.find((name) => name.trim().toUpperCase() === asked.trim().toUpperCase());
+            if (ignored !== undefined) {
+                throw new UsageError(`--family ${asked} is given beside --ignore-family ${ignored}, and a family's citations are read or they are passed over: give one of the two`);
             }
         }
     }