@descent-vtt/spec-guard 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -10,6 +10,108 @@ what to do when upgrading; the family's policy, including how a flag or field
 is deprecated before it goes, is spec-core's
 [ADR-0009](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md).
 
+## 0.26.0
+
+An option that takes one value is refused given two, exit 2, and so is
+`--json` beside a `--format` that names another format, where the later
+was read with no word of the earlier. And a Python import statement is
+read as Python reads it: `from a import(b)` was read as no import, and an
+import rule passed over it.
+
+### Changed
+
+- **An option that takes one value is refused where it is given two, and
+  `--json` beside a `--format` that names another format.** `--json
+  --format sarif` wrote SARIF and `--format sarif --json` wrote JSON, with
+  no word of the one that lost; and so it was for `--format`, `--root`,
+  `--engine`, `--max-snippets`, `--concurrency` and `--depth` given twice
+  with two values, on every command that takes them. Each is now exit 2 and
+  one line that names both as they were written. The same value given twice
+  is read as once, however it is spelled, and so is `--json` beside
+  `--format json`; and `--spec` and `--exclude` are lists, as they were.
+  Such a line is refused with `--help` or `--version` on it too, as a line
+  with a pair has been since 0.25.0: `--json --format sarif --help` printed
+  the help and is exit 2
+  ([ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md)).
+  Upgrading: give the option once. A script that adds `--format` or `--root`
+  to a line it was handed, to override the one already there, takes that
+  one off the line instead.
+- **A Python import statement is read as Python reads it.** `from a
+  import(b)`, with no blank before the parenthesis, was read as no import,
+  and so were `from a import*`, `from.a import b`, `from . a import b`, a
+  dotted name with blanks about its dots, a form feed between two words,
+  and a `from` statement whose module has a letter beyond ASCII: an import
+  rule passed over each. A statement is now read by Python's own grammar,
+  token by token, and reported on the line it stands on, which was another
+  for a statement after a `;` that followed one of several lines. Python
+  3.15's `lazy import` and `lazy from ... import` are read as the imports
+  they are. And a statement Python refuses is read as nothing, where
+  `from a import b,`, `import (a)`, `import a b` and `import os, , sys`
+  were each read as an import. Of 322 spellings given to Python 3.11.9 and
+  to spec-guard, 0.25.0 read 59 otherwise than Python does and found an
+  import in 78 that Python refuses; over the 4,341 files of that Python's
+  own library both read all 32,777 imports alike
+  ([ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md)).
+  Upgrading: an `@assert-import-absence`, `@assert-import-count`,
+  `@assert-layers` or `@assert-import-cycle` rule over Python that passed
+  may now fail for an import written one of those ways; mend the import it
+  names, or give the rule a `baseline`. A rule that failed only for a
+  statement Python refuses now passes over it. `impact` lists the
+  dependents those imports make, and `logicalLines`, from the package, also
+  says where each physical line of a statement begins, as `starts`.
+
+## 0.25.0
+
+A Python file with CRLF line endings is read as it is read with LF: an
+import rule over one passed in a Windows checkout where the same file
+fails it anywhere else. An option given beside its own opposite is
+refused, exit 2, where the last of the two won with no word of the other.
+And a report asked for in ASCII is ASCII.
+
+### Changed
+
+- **An option given beside its own opposite is refused, where the last of
+  the two won.** `--strict --no-strict` ran as `--no-strict` alone, and
+  `--no-color --color` in colour, with no word of the option that lost: so
+  it was for the colour pair and for each on/off option a configuration can
+  set, `--strict`, `--allow-missing-targets`, `--allow-empty-scope`,
+  `--default-skips`, `--ignore-status` and `--include-specs`, on every
+  command that takes both. Each pair is now exit 2 and one line that names
+  both, in either order, as `--ascii` beside `--no-ascii` has been since
+  0.24.0; that pair's line now reads as the others do. The same option
+  given twice is read as once, an opposite alone still wins over a
+  configuration, and a command that takes only one of a pair refuses the
+  other as it did
+  ([ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md)).
+  Upgrading: give one of the two. A script that adds an opposite to a line
+  it was handed, to turn an option off, takes the option off the line
+  instead; a configuration is overridden by the opposite alone, as before.
+- **A Python file with CRLF line endings is read as it is read with LF.**
+  A line ended at LF alone, so in a CRLF file every line kept its carriage
+  return: no `from x import y` was read from the file, and a backslash at
+  the end of a line continued nothing, so `import a, \` named a module `\`.
+  An import rule over such a file passed where the same file with LF fails
+  it, as in a Windows checkout with `core.autocrlf` on. A line now ends
+  where Python ends one, at LF, at CRLF and at a lone carriage return, and
+  each import is reported on the line it was on. Go, Rust, C#, JavaScript
+  and TypeScript were read right already
+  ([ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md)).
+  Upgrading: an `@assert-import-absence`, `@assert-import-count`,
+  `@assert-layers` or `@assert-import-cycle` rule over Python that passed
+  in a CRLF checkout may now fail there, as it does in an LF one; mend the
+  import it names, or give the rule a `baseline`. `impact` lists the
+  dependents those imports make.
+
+### Fixed
+
+- A report asked for in ASCII is ASCII. Under `--ascii`, `SPEC_GUARD_ASCII`
+  or a Windows console that names no terminal, the lines of a run, `prove`,
+  `cites` and a watch session still held `·` between their counts, and a
+  snippet whose line was cut still ended in `…`. They are ` - ` and `...`
+  now, and so in the text of the server's `check_architecture`, which asks
+  for its report in ASCII. Where the marks are drawn nothing changes, and
+  `--json` and `--format sarif` carry a cut snippet as they did.
+
 ## 0.24.0
 
 A `cites --strict` that fails for a file read in part, or for a family that

package/README.md

@@ -231,7 +231,7 @@ These read the dependency rather than the text, in **five languages**:
 | Language | Extensions | Reads |
 | --- | --- | --- |
 | JavaScript / TypeScript | `.js .mjs .cjs .jsx .ts .mts .cts .tsx` | `import`, `export ... from`, `require()`, `import()` |
-| Python | `.py .pyi` | `import a.b`, `from .rel import x`, `importlib.import_module("x")` |
+| Python | `.py .pyi` | `import a.b` and `from .rel import x` in every spelling Python's grammar takes, 3.15's `lazy import` among them, and `importlib.import_module("x")` |
 | Go | `.go` | `import "x"` and grouped `import ( ... )`, including aliases and `_` |
 | Rust | `.rs` | `use a::{b, c}` with nested groups, `pub use`, `extern crate` |
 | C# | `.cs .csx` | `using`, `using static`, `global using`, `using X = A.B`, `global::` and extern-alias qualifiers, and a using relative to its namespace |
@@ -1301,8 +1301,8 @@ spec-guard impact <paths...>           # the files that depend on each path, and
 | `-v, --verbose` | Print passing assertions too |
 | `--watch` | Report, then report again as the tree changes, until Ctrl+C |
 | `--fail-fast` | Stop at the first failing assertion |
-| `--json` | Machine-readable report on stdout (same as `--format json`), versioned by `formatVersion` |
-| `--format <human\|json\|sarif\|github\|gitlab>` | Output format. `sarif` uploads to GitHub code scanning, `github` annotates a pull request from the job's log, `gitlab` is a GitLab Code Quality report |
+| `--json` | Machine-readable report on stdout (same as `--format json`), versioned by `formatVersion`. Beside a `--format` that names another format it is refused (below) |
+| `--format <human\|json\|sarif\|github\|gitlab>` | Output format. `sarif` uploads to GitHub code scanning, `github` annotates a pull request from the job's log, `gitlab` is a GitLab Code Quality report. Given twice with two formats it is refused, as every option that takes one value is (below) |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones). ripgrep is `rg` on `PATH`, or the program `SPEC_GUARD_RG` names; `rg` with no ripgrep that runs is exit 2 ([below](#ci-integration)) |
 | `--strict` / `--no-strict` | Treat analysis that could not be completed as a failure, and a run that executed no assertion: its specs matched and state no rule in force |
 | `--allow-missing-targets` / `--no-allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
@@ -1317,28 +1317,31 @@ spec-guard impact <paths...>           # the files that depend on each path, and
 | `--depth <n>` | `impact` only: follow dependents at most `n` imports away (default: all) |
 | `--allow-empty` | Let a run, `prove` or `impact` through when no spec file matched the patterns, or when one pattern matched none beside others that did, each of which is exit 2 without it; such a pattern is still named on stderr (about the run, not an assertion) |
 | `--color` / `--no-color` | Force colour on or off. Without either flag, `NO_COLOR` set to anything turns it off; otherwise `FORCE_COLOR` turns it on, and `FORCE_COLOR=0` or `FORCE_COLOR=false` off; otherwise `TERM=dumb` turns it off; otherwise a terminal has colour. `NO_COLOR` or `FORCE_COLOR` set to nothing is as unset |
-| `--ascii` / `--no-ascii` | Draw a report's marks in ASCII, or as the marks, on any platform. Either wins over the environment, and the two together are refused, exit 2. Without either, `SPEC_GUARD_ASCII` set to anything but nothing, `0` or `false` asks for ASCII; otherwise Windows decides as below |
+| `--ascii` / `--no-ascii` | Write a report in ASCII, or with the marks, on any platform. Either wins over the environment. Without either, `SPEC_GUARD_ASCII` set to anything but nothing, `0` or `false` asks for ASCII; otherwise Windows decides as below |
 
 Patterns are expanded by spec-guard itself, so quoted globs behave identically
 on Windows, macOS and Linux. A directory expands to the Markdown files in it.
-The second form of each on/off option exists to override a configuration.
-
-On Windows a report's marks are drawn in ASCII, `+`, `x`, `!`, `o` and `...`
-for `✔`, `✖`, `⚠`, `○` and `…`, unless `WT_SESSION` or `TERM_PROGRAM` is set
-to something: Windows Terminal sets the first, and VS Code's terminal and
-mintty the second. `TERM` is not read for it, since Git for Windows and the
-Cygwin and MSYS2 runtimes set it for whatever they start, in a console whose
-fonts hold none of the first three marks. Anywhere else the marks are always
-drawn.
-
-Either can be asked for outright. `--ascii` draws the ASCII marks and
-`--no-ascii` the others, on any platform and whatever the environment says:
-an ssh session into Windows names no terminal, and `--no-ascii` is how it
-gets the marks its own terminal draws. `SPEC_GUARD_ASCII=1` asks for ASCII
+The second form of each on/off option exists to override a configuration;
+beside the first, on one command line, it is refused (below).
+
+On Windows a report is written in ASCII unless `WT_SESSION` or `TERM_PROGRAM`
+is set to something: Windows Terminal sets the first, and VS Code's terminal
+and mintty the second. `TERM` is not read for it, since Git for Windows and
+the Cygwin and MSYS2 runtimes set it for whatever they start, in a console
+whose fonts hold none of the first three marks. Anywhere else the marks are
+always drawn. In ASCII a report holds no character of its own beyond it:
+`+`, `x`, `!` and `o` for `✔`, `✖`, `⚠` and `○`, `...` for the `…` of what is
+left out, a cut line among it, and `-` for the `·` between the counts of a
+line. A path, a line of source or a reason is written as the project wrote
+it.
+
+Either can be asked for outright. `--ascii` writes a report in ASCII and
+`--no-ascii` with the marks, on any platform and whatever the environment
+says: an ssh session into Windows names no terminal, and `--no-ascii` is how
+it gets the marks its own terminal draws. `SPEC_GUARD_ASCII=1` asks for ASCII
 for every run that inherits it; set to nothing, `0` or `false`, in any case,
 it asks for nothing, and it never asks for the marks. An option wins over
-the variable, and `--ascii` beside `--no-ascii` is exit 2, since one of the
-two would go unread.
+the variable.
 
 An option that means nothing to a command is refused rather than ignored, so
 `spec-guard query --strict` does not look like a strict query. `query` does take
@@ -1356,6 +1359,40 @@ strict and `--allow-empty=false` let an empty run through. An option a
 configuration can set has an opposite to turn it off, `--no-strict`; any
 other is left out.
 
+So is an option given beside its own opposite, in either order: `--strict`
+beside `--no-strict`, `--color` beside `--no-color`, and every other pair of
+the table. The last of the two used to win, and nothing said the other had
+been given; a line that asks for both was not meant, and one of the two would
+go unread:
+
+```text
+spec-guard: Option --strict is given beside --no-strict, and one of the two would go unread. Give one of the two.
+```
+
+The same option given twice is read as once. An opposite alone still wins
+over a configuration, which is what it is for. And where a command takes
+only one of a pair, as `query` takes `--no-color` and not `--color`, the
+other is refused for that, as it was.
+
+So is an option that takes one value and is given two: `--root`, `--format`,
+`--engine`, `--max-snippets`, `--concurrency` and `--depth`. The later of the
+two used to be read, and nothing said the earlier had been given. And so is
+`--json` beside a `--format` that names another format, since `--json` is
+`--format json`: `--json --format sarif` wrote SARIF, and
+`--format sarif --json` wrote JSON. Each is named as it was written, in the
+order the two were given:
+
+```text
+spec-guard: Option --json is given beside --format "sarif", and one of the two would go unread. Give one of the two.
+```
+
+The same value given twice is read as once, however it is spelled: `--root .`
+beside `--root ./`, `--format JSON` beside `--format json`, and `--json`
+beside `--format json`. `--spec` and `--exclude` are lists, and each use adds
+to its list; `--exclude=` adds nothing to it, and the configuration's list is
+replaced either way. Such a line is refused with `--help` or `--version` on
+it too, as a line with a pair is.
+
 And so is a spec pattern that matches no file beside others that do. After
 `old-docs` was renamed, `spec-guard docs old-docs` ran the specs under `docs`
 and said nothing of the rest: every rule in the renamed directory had stopped
@@ -1941,8 +1978,8 @@ build fails if they stop being true. CI proves every one of those rules can
 fail, and `spec-guard cites` holds every ADR a comment in the code cites to
 existing and being in force.
 
-Line coverage is 100%, CI's full mutation sweep kills 99.19% of 12,826 mutants
-(0.24.0), and every survivor a release adds is replayed before it ships
+Line coverage is 100%, CI's full mutation sweep kills 99.26% of 12,993 mutants
+(0.26.0), and every survivor a release adds is replayed before it ships
 ([ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md));
 [CONTRIBUTING.md](https://github.com/DescentVTT/spec-guard/blob/main/CONTRIBUTING.md)
 has how to build, test and release, and

package/dist/cli.d.ts

@@ -101,7 +101,7 @@ export declare class UsageError extends Error {
  * fallback nobody knows still works.
  */
 export declare function version(manifest?: string): string;
-export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]     execute the directives in the specs\n  spec-guard query <paths...> [options]  list the rules in force for files or directories\n  spec-guard mcp [options]               serve the rules to an AI agent over MCP on stdio\n  spec-guard prove [patterns...] [options]\n                                         show each rule a violation of itself, in memory, and report any that pass\n  spec-guard cites [paths...] [options]  check that each spec a code comment cites exists and is in force\n  spec-guard impact <paths...> [options] the files that depend on each path, and the rules in play there\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted. query,\n  mcp, cites and impact take theirs from --spec.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against, a directory (default: cwd)\n      --spec <pattern>    A spec glob or path; repeatable (default: \"docs/**/*.md\")\n  -v, --verbose           Print passing assertions too\n      --watch             Run again as the tree changes, until Ctrl+C (human output only)\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report (same as --format json)\n      --format <name>     human | json | sarif | github | gitlab  (sarif uploads to code scanning,\n                          github annotates a pull request from the log, gitlab is Code Quality)\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n                          ripgrep is rg on PATH, or the program SPEC_GUARD_RG names; where that\n                          is no ripgrep that runs, rg is exit 2 and auto leaves it to the scanner\n      --strict            Treat analysis that could not be completed, and a run that\n                          executed no assertion, as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --allow-empty-scope Tolerate assertions whose scope holds no files (they fail by default)\n      --print-baseline    Print the baseline=\"...\" that would exempt today's violations, and exit\n      --no-default-skips  Search .git, .hg, .svn and node_modules too\n      --exclude <globs>   Paths no assertion looks at, beside each directive's exclude; repeatable\n      --ignore-status     Execute directives in documents not in force too (see Directives)\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel, 1 or more (default: 8)\n      --depth <n>         impact: follow dependents at most n imports away (default: all)\n      --allow-empty       Let a run, prove or impact through when no spec file matched, or when\n                          one pattern matched none beside others that did (not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR, FORCE_COLOR and TERM=dumb are honoured)\n      --ascii/--no-ascii  Draw a report's marks as + x ! o, or as their Unicode forms, on any\n                          platform; the two together are refused. Without either,\n                          SPEC_GUARD_ASCII asks for ASCII unless it is empty, 0 or false\n  -h, --help              Show this help\n      --version           Print the version\n\n  An option that is set and names nothing is refused, exit 2, never read as if\n  it were not there: an empty --root or spec pattern, --exclude \",\" (--exclude=\n  with nothing clears the list), --concurrency 0, a root that is no directory,\n  and a value given to an option that takes none, as in --strict=false.\n\n  A spec pattern that matches no file, beside others that do, is refused the\n  same way and by name, since none of its rules was read: a run, prove, impact\n  and query exit 2. --allow-empty lets the first three through and still names\n  it; --watch and mcp carry on, and say which pattern it is; cites names it\n  and goes on, and exits 1 for it under --strict (see cites, below).\n\nConfiguration\n  package.json in the root can hold specs, exclude, engine, strict,\n  allowMissingTargets, allowEmptyScope, ignoreStatus, includeSpecs, defaultSkips,\n  maxSnippets and concurrency under \"specGuard\"; a root with no package.json can\n  keep them in .spec-guard.json instead, but not in both. A flag wins over the\n  file, every on/off option there also takes its opposite (--no-strict,\n  --default-skips, ...), and --exclude= with nothing clears exclude.\n  \"cites\": [{ \"id\": \"ADR-{n}\", \"files\": \"docs/adr/{n}-*.md\" }] names the\n  documents code comments cite; without it, cites reads them off the titles of\n  numbered specs.\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n  <!-- @assert-import-cycle target=\"src/\" types=\"ignore\" -->\n  <!-- @assert-layers target=\"src/\" order=\"domain, application, infrastructure\" -->\n  <!-- @assert-structure target=\"src/\" exclude=\"*.test.ts\" partner=\"[name].test.ts\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n  An assertion whose scope holds no files fails; add allow-empty=\"true\" to allow it.\n  A document whose status is draft, proposed, rejected, deprecated, superseded\n  or archived is reported and not executed; --ignore-status runs it anyway.\n  The status is read in English, whatever language the document is written in:\n  status: superseded.\n\nprove adds, changes or removes files in memory only - never on disk - to make\nthe violation each rule forbids, and runs the rule over that tree. A rule that\nstill passes survived, and exits 1; one no violation could be made for is\nunprovable, and exits 1 under --strict.\n\ncites reads comment text only - not strings, not Markdown - for ids such as\nADR-0007, ADR-7 and ADR-007, which are one document. A ghost citation names no\ndocument, and exits 1; a stale one names a document superseded, deprecated,\nrejected or archived, and exits 1 under --strict. A family whose files match no\ndocument exits 2. A spec pattern that matches no file beside others that do is\nnamed on stderr. Without \"cites\" in the configuration the families are read off\nthe specs, so one kept under that pattern was not read and no citation of it\nwas looked for: exit 1 under --strict. Families \"cites\" names lose nothing.\n\nimpact follows the import graph backwards: relative JavaScript, TypeScript and\nPython imports that name a file. Go, Rust, C# and absolute Python imports name\nmodules, and are counted rather than followed; an import that names no file is\nlisted, never guessed at.\n\nquery answers from the specs alone, without reading the codebase, so it works\nfor a file that does not exist yet. mcp offers the same answer, a check and\nimpact's, as the tools get_architectural_rules, check_architecture and\nget_dependents.\n\nExit codes\n  0 all assertions passed   1 an assertion failed, or none ran under --strict\n  2 spec-guard could not run   130 a --watch session was stopped";
+export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]     execute the directives in the specs\n  spec-guard query <paths...> [options]  list the rules in force for files or directories\n  spec-guard mcp [options]               serve the rules to an AI agent over MCP on stdio\n  spec-guard prove [patterns...] [options]\n                                         show each rule a violation of itself, in memory, and report any that pass\n  spec-guard cites [paths...] [options]  check that each spec a code comment cites exists and is in force\n  spec-guard impact <paths...> [options] the files that depend on each path, and the rules in play there\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted. query,\n  mcp, cites and impact take theirs from --spec.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against, a directory (default: cwd)\n      --spec <pattern>    A spec glob or path; repeatable (default: \"docs/**/*.md\")\n  -v, --verbose           Print passing assertions too\n      --watch             Run again as the tree changes, until Ctrl+C (human output only)\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report (same as --format json)\n      --format <name>     human | json | sarif | github | gitlab  (sarif uploads to code scanning,\n                          github annotates a pull request from the log, gitlab is Code Quality)\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n                          ripgrep is rg on PATH, or the program SPEC_GUARD_RG names; where that\n                          is no ripgrep that runs, rg is exit 2 and auto leaves it to the scanner\n      --strict            Treat analysis that could not be completed, and a run that\n                          executed no assertion, as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --allow-empty-scope Tolerate assertions whose scope holds no files (they fail by default)\n      --print-baseline    Print the baseline=\"...\" that would exempt today's violations, and exit\n      --no-default-skips  Search .git, .hg, .svn and node_modules too\n      --exclude <globs>   Paths no assertion looks at, beside each directive's exclude; repeatable\n      --ignore-status     Execute directives in documents not in force too (see Directives)\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel, 1 or more (default: 8)\n      --depth <n>         impact: follow dependents at most n imports away (default: all)\n      --allow-empty       Let a run, prove or impact through when no spec file matched, or when\n                          one pattern matched none beside others that did (not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR, FORCE_COLOR and TERM=dumb are honoured)\n      --ascii/--no-ascii  Write a report in ASCII, its marks as + x ! o, or with their Unicode\n                          forms, on any platform. Without either, SPEC_GUARD_ASCII asks for\n                          ASCII unless it is empty, 0 or false\n  -h, --help              Show this help\n      --version           Print the version\n\n  An option that is set and names nothing is refused, exit 2, never read as if\n  it were not there: an empty --root or spec pattern, --exclude \",\" (--exclude=\n  with nothing clears the list), --concurrency 0, a root that is no directory,\n  and a value given to an option that takes none, as in --strict=false.\n\n  An option given beside its own opposite is refused the same way, in either\n  order, since one of the two would go unread: --strict beside --no-strict,\n  --color beside --no-color, and each other pair. The same option given twice\n  is read as once.\n\n  So is an option that takes one value and is given two, since the first of\n  them would go unread: --root a --root b, --format json --format sarif, and\n  --json beside a --format that names another format. The same value given\n  twice is read as once, as --json beside --format json is. --spec and\n  --exclude are lists, and each use adds to its list. Such a line is refused\n  with --help or --version on it too, as a line with a pair is.\n\n  A spec pattern that matches no file, beside others that do, is refused the\n  same way and by name, since none of its rules was read: a run, prove, impact\n  and query exit 2. --allow-empty lets the first three through and still names\n  it; --watch and mcp carry on, and say which pattern it is; cites names it\n  and goes on, and exits 1 for it under --strict (see cites, below).\n\nConfiguration\n  package.json in the root can hold specs, exclude, engine, strict,\n  allowMissingTargets, allowEmptyScope, ignoreStatus, includeSpecs, defaultSkips,\n  maxSnippets and concurrency under \"specGuard\"; a root with no package.json can\n  keep them in .spec-guard.json instead, but not in both. A flag wins over the\n  file, every on/off option there also takes its opposite (--no-strict,\n  --default-skips, ...), and --exclude= with nothing clears exclude.\n  \"cites\": [{ \"id\": \"ADR-{n}\", \"files\": \"docs/adr/{n}-*.md\" }] names the\n  documents code comments cite; without it, cites reads them off the titles of\n  numbered specs.\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n  <!-- @assert-import-cycle target=\"src/\" types=\"ignore\" -->\n  <!-- @assert-layers target=\"src/\" order=\"domain, application, infrastructure\" -->\n  <!-- @assert-structure target=\"src/\" exclude=\"*.test.ts\" partner=\"[name].test.ts\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n  An assertion whose scope holds no files fails; add allow-empty=\"true\" to allow it.\n  A document whose status is draft, proposed, rejected, deprecated, superseded\n  or archived is reported and not executed; --ignore-status runs it anyway.\n  The status is read in English, whatever language the document is written in:\n  status: superseded.\n\nprove adds, changes or removes files in memory only - never on disk - to make\nthe violation each rule forbids, and runs the rule over that tree. A rule that\nstill passes survived, and exits 1; one no violation could be made for is\nunprovable, and exits 1 under --strict.\n\ncites reads comment text only - not strings, not Markdown - for ids such as\nADR-0007, ADR-7 and ADR-007, which are one document. A ghost citation names no\ndocument, and exits 1; a stale one names a document superseded, deprecated,\nrejected or archived, and exits 1 under --strict. A family whose files match no\ndocument exits 2. A spec pattern that matches no file beside others that do is\nnamed on stderr. Without \"cites\" in the configuration the families are read off\nthe specs, so one kept under that pattern was not read and no citation of it\nwas looked for: exit 1 under --strict. Families \"cites\" names lose nothing.\n\nimpact follows the import graph backwards: relative JavaScript, TypeScript and\nPython imports that name a file. Go, Rust, C# and absolute Python imports name\nmodules, and are counted rather than followed; an import that names no file is\nlisted, never guessed at.\n\nquery answers from the specs alone, without reading the codebase, so it works\nfor a file that does not exist yet. mcp offers the same answer, a check and\nimpact's, as the tools get_architectural_rules, check_architecture and\nget_dependents.\n\nExit codes\n  0 all assertions passed   1 an assertion failed, or none ran under --strict\n  2 spec-guard could not run   130 a --watch session was stopped";
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
 /**

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -109,9 +109,9 @@ Options
       --allow-empty       Let a run, prove or impact through when no spec file matched, or when
                           one pattern matched none beside others that did (not an assertion)
       --color/--no-color  Force colour on or off (NO_COLOR, FORCE_COLOR and TERM=dumb are honoured)
-      --ascii/--no-ascii  Draw a report's marks as + x ! o, or as their Unicode forms, on any
-                          platform; the two together are refused. Without either,
-                          SPEC_GUARD_ASCII asks for ASCII unless it is empty, 0 or false
+      --ascii/--no-ascii  Write a report in ASCII, its marks as + x ! o, or with their Unicode
+                          forms, on any platform. Without either, SPEC_GUARD_ASCII asks for
+                          ASCII unless it is empty, 0 or false
   -h, --help              Show this help
       --version           Print the version
 
@@ -120,6 +120,18 @@ Options
   with nothing clears the list), --concurrency 0, a root that is no directory,
   and a value given to an option that takes none, as in --strict=false.
 
+  An option given beside its own opposite is refused the same way, in either
+  order, since one of the two would go unread: --strict beside --no-strict,
+  --color beside --no-color, and each other pair. The same option given twice
+  is read as once.
+
+  So is an option that takes one value and is given two, since the first of
+  them would go unread: --root a --root b, --format json --format sarif, and
+  --json beside a --format that names another format. The same value given
+  twice is read as once, as --json beside --format json is. --spec and
+  --exclude are lists, and each use adds to its list. Such a line is refused
+  with --help or --version on it too, as a line with a pair is.
+
   A spec pattern that matches no file, beside others that do, is refused the
   same way and by name, since none of its rules was read: a run, prove, impact
   and query exit 2. --allow-empty lets the first three through and still names
@@ -294,7 +306,7 @@ const NOT_WITH_WATCH = [
     ['--engine', 'a session always scans in-process, where it can see what each rule reads'],
 ];
 /** The long name of an option, whichever way it was spelled. */
-const LONG_NAMES = { '-v': '--verbose' };
+const LONG_NAMES = { '-v': '--verbose', '-r': '--root' };
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export function parseArgs(argv, cwd) {
     const command = COMMANDS.has(argv[0]) ? argv[0] : 'check';
@@ -328,6 +340,14 @@ export function parseArgs(argv, cwd) {
     const set = options.fromCommandLine;
     /** Every option given, by its long name, for the refusals that depend on another option. */
     const given = new Set();
+    /**
+     * What each thing that is one value was first asked to be: as the option
+     * stood on the command line, for the refusal, and as it was read, since
+     * `--root .` and `--root ./` name one directory and ask for one thing.
+     */
+    const asked = new Map();
+    /** The first two options that ask for one thing as two values, as each was written. */
+    let unread;
     let onlyPositional = false;
     for (let index = command === 'check' ? 0 : 1; index < argv.length; index++) {
         const argument = argv[index];
@@ -352,10 +372,23 @@ export function parseArgs(argv, cwd) {
             index += 1;
             return requireValue(name, argv[index]);
         };
-        if (command !== 'check' && NOT_FOR[command].has(LONG_NAMES[name] ?? name)) {
+        const long = LONG_NAMES[name] ?? name;
+        if (command !== 'check' && NOT_FOR[command].has(long)) {
             throw new UsageError(`Option ${name} does not apply to spec-guard ${command}.`);
         }
-        given.add(LONG_NAMES[name] ?? name);
+        given.add(long);
+        // Called by an option that takes one value, with what it read: the same
+        // thing asked twice is asked once, and a second value is kept for the
+        // refusal below. An option is the thing it asks for, by its long name;
+        // `--json` asks for a format.
+        const asks = (read, value, thing = long) => {
+            const written = value === undefined ? name : `${name} ${JSON.stringify(value)}`;
+            const first = asked.get(thing);
+            if (first === undefined)
+                asked.set(thing, { written, read });
+            else if (first.read !== read)
+                unread ??= [first.written, written];
+        };
         switch (name) {
             case '-h':
             case '--help':
@@ -377,9 +410,11 @@ export function parseArgs(argv, cwd) {
             case '--json':
                 options.json = true;
                 options.format = 'json';
+                asks('json', undefined, '--format');
                 break;
             case '--format': {
-                const written = nextValue().toLowerCase();
+                const raw = nextValue();
+                const written = raw.toLowerCase();
                 // Whether it is a format at all is decided just below, by the lists.
                 const value = written;
                 // mcp refused --format above, so every command that gets here writes one.
@@ -393,6 +428,7 @@ export function parseArgs(argv, cwd) {
                 }
                 options.format = value;
                 options.json = value === 'json';
+                asks(value, raw);
                 break;
             }
             case '--strict':
@@ -471,13 +507,15 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(`Option ${name} expects a directory, got ${JSON.stringify(value)}. Name one, or leave the option out to run in the working directory.`);
                 }
                 options.root = path.resolve(cwd, value);
+                asks(options.root, value);
                 break;
             }
             case '--spec':
                 specs.push(nextValue());
                 break;
             case '--engine': {
-                const value = nextValue().toLowerCase();
+                const raw = nextValue();
+                const value = raw.toLowerCase();
                 try {
                     options.engine = engineNamed(value);
                 }
@@ -485,29 +523,37 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(error.message);
                 }
                 set.add('engine');
+                asks(options.engine, raw);
                 break;
             }
-            case '--max-snippets':
-                options.maxSnippets = positiveInteger(name, nextValue());
+            case '--max-snippets': {
+                const value = nextValue();
+                options.maxSnippets = positiveInteger(name, value);
                 set.add('maxSnippets');
+                asks(options.maxSnippets, value);
                 break;
+            }
             case '--concurrency': {
                 // Refused as the configuration's key refuses it. Made 1, it was a run
                 // somebody had asked something else of.
-                const concurrency = positiveInteger(name, nextValue());
+                const value = nextValue();
+                const concurrency = positiveInteger(name, value);
                 if (concurrency === 0)
                     throw new UsageError('Option --concurrency expects 1 or more: a concurrency of 0 would run no search.');
                 options.concurrency = concurrency;
                 set.add('concurrency');
+                asks(concurrency, value);
                 break;
             }
             case '--depth': {
                 if (command !== 'impact')
                     throw new UsageError('Option --depth applies only to spec-guard impact.');
-                const depth = positiveInteger(name, nextValue());
+                const value = nextValue();
+                const depth = positiveInteger(name, value);
                 if (depth === 0)
                     throw new UsageError('Option --depth expects 1 or more: a depth of 0 would follow no import.');
                 options.depth = depth;
+                asks(depth, value);
                 break;
             }
             default:
@@ -520,11 +566,30 @@ export function parseArgs(argv, cwd) {
             throw new UsageError(`Option ${name} takes no value, got "${inlineValue}". Give it alone or leave it out; an option a configuration can set has an opposite that turns it off, as --no-strict is to --strict.`);
         }
     }
-    // The last of `--color` and `--no-color` wins, and says nothing of the
-    // other. This pair is refused together: one of the two would go unread, and
-    // a line that asks for both ways of drawing the marks was not meant.
-    if (given.has('--ascii') && given.has('--no-ascii')) {
-        throw new UsageError('Option --ascii is given beside --no-ascii, and the marks are drawn one way or the other. Give one of the two.');
+    // An option beside its own opposite, in either order: one of the two would
+    // go unread, and a line that asks for both was not meant. The last of them
+    // won, with no word of the other, for every pair but the one that draws the
+    // marks (ADR-0014, amended 2026-10-12). Named by the option that turns
+    // something on, whichever came first. The same option twice asks for one
+    // thing and is read as once, and an opposite alone is what overrides a
+    // configuration.
+    for (const off of given) {
+        // `--no-strict` is `--strict` turned off. An option that begins any other
+        // way reads back as itself, and is no pair with itself.
+        const on = off.replace('--no-', '--');
+        if (on !== off && given.has(on)) {
+            throw new UsageError(`Option ${on} is given beside ${off}, and one of the two would go unread. Give one of the two.`);
+        }
+    }
+    // Two values for a thing that is one: the later was read and the earlier
+    // went unread, with no word of it, for each option that takes one value and
+    // for `--json` beside a `--format` that names another format (ADR-0014,
+    // amended 2026-10-14). Named in the order they were given, each as it was
+    // written. Refused with `--help` or `--version` on the line too, as the
+    // pair above is: both are a wrong command line, and one tool does not
+    // answer the two first for some wrong lines and after others.
+    if (unread !== undefined) {
+        throw new UsageError(`Option ${unread[0]} is given beside ${unread[1]}, and one of the two would go unread. Give one of the two.`);
     }
     if (options.watch) {
         for (const [option, reason] of NOT_WITH_WATCH) {