@descent-vtt/spec-guard 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -10,6 +10,114 @@ 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.22.0
+
+A spec pattern that matches no file, beside others that do, is refused by
+name, exit 2, where it was dropped without a word and the run reported on
+the rest: a directory of specs that was renamed no longer leaves a green
+check behind. `--allow-empty` lets such a pattern through, and `--watch` and
+the server carry on and say which it is.
+
+### Changed
+
+- **A spec pattern that matches no file beside others that do is refused,
+  where it was dropped without a word.** A directory of specs that was
+  renamed left its pattern behind: its rules stopped running and the check
+  stayed green. A run, `prove`, `impact` and `query` now exit 2 with a line
+  that names each such pattern, from the command line or `specs`; documents a
+  script reads are still written, the JSON ones with the patterns as
+  `unmatchedSpecs`, and `--watch` and the server carry on and say which
+  pattern it is
+  ([ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md)).
+  Upgrading: remove the pattern, or give `--allow-empty` to a run, `prove` or
+  `impact` where a pattern is meant to match nothing yet. `query` takes no
+  such option, so until the pattern is removed spec-harness's `context`
+  packet lists no rules and says why; its guard and its hooks ask spec-guard
+  nothing and are as they were.
+
+### Fixed
+
+- A ripgrep that failed is said once in a report. Under `--engine auto`, with
+  `SPEC_GUARD_RG` naming a program that is not ripgrep, the warning that the
+  scanner had answered was repeated for every group of searches, four times
+  for four rules over four targets; failures that differ are still each said.
+- `FORCE_COLOR=false` turns colour off, as Node and `supports-color` read it,
+  where it forced colour on. Exactly `0` and `false` are off, on a terminal
+  too, and any other value still forces colour.
+
+## 0.21.0
+
+An input that is set and names nothing is refused, exit 2, by a line that
+names it, where it was read as if it had not been given: an empty spec
+pattern or `--root`, a root that is no directory, `--exclude ","`,
+`--concurrency 0`, a value given to an option that takes none, and an
+`--engine rg` whose binary is not ripgrep. A wrong command line is answered
+in that one line, and no longer with the whole help after it.
+
+### Changed
+
+- **An empty spec pattern is refused, where it was every spec under the
+  root.** `--spec ""`, or `""` for a pattern, was read as the root and ran
+  every Markdown file under it, for a run, `query`, `prove`, `cites`,
+  `impact` and the server; it is exit 2 and `invalid spec pattern "": it is
+  empty`, and `runSpecGuard` and the rest of the package throw the same
+  ([ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md)).
+  Upgrading: write `.` where every Markdown file under the root is meant, and
+  have the shell refuse a variable that is not set, as `"${DOCS:?}"` does.
+- **An empty `--root`, and a root that is not a directory, are refused by
+  every command.** `--root ""` ran in the working directory. A root that was
+  a file or was not there was "no spec files matched", which `--allow-empty`
+  made exit 0, `cites` exited 0 with nothing to look for, and the server
+  started; each is exit 2 and a line that names the root. Upgrading: name a
+  directory that exists, or leave the option out.
+- **`--concurrency 0` is refused**, as `"concurrency": 0` in a configuration
+  always was; it ran as 1. Upgrading: write 1 or more, or leave it out for 8.
+- **`--exclude` given separators and nothing else, as in `","`, is
+  refused**, where it cleared the configuration's list. Upgrading: `--exclude=`
+  with nothing still clears it.
+- **An option that takes no value is refused with one.** What followed the
+  `=` was never read, so `--strict=false` was strict, `--default-skips=false`
+  kept the default skips, `--allow-empty=false` let an empty run through and
+  `--json=false` wrote JSON. Upgrading: give the option alone or leave it
+  out; `--no-strict`, `--no-default-skips` and the other opposites turn one
+  off.
+- **`--engine rg` is refused where `SPEC_GUARD_RG` names no ripgrep that
+  runs, in a line that names the variable.** A program that answers
+  `--version` and is not ripgrep was taken for one: every search failed, the
+  scanner answered, and the run exited 0 with a warning for each. A path that
+  was not there was blamed on `PATH`, and on Windows a file that is no
+  program ended the run with `spawn EFTYPE`. Each is exit 2 before anything
+  is searched, and `findRipgrep()` from the package answers `null` for each
+  ([ADR-0004](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0004-adaptive-engine.md)).
+  Upgrading: set the variable to the path of an `rg` that runs, unset it to
+  use the one on `PATH`, or leave `--engine rg` out: `auto` still leaves a
+  binary it cannot use to the scanner.
+- **`FORCE_COLOR=0` and `TERM=dumb` turn colour off on a terminal**, as the
+  family reads them (spec-core's
+  [ADR-0005](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md)).
+  `FORCE_COLOR=0` only declined to force colour, and `TERM` was not read for
+  colour, so a terminal that says it draws none was written escapes. Any
+  other `FORCE_COLOR` and `--color` still force it, over `TERM=dumb` too.
+  Upgrading: unset the variable, or pass `--color`.
+
+### Fixed
+
+- A wrong command line is answered in one line, `spec-guard:` and what was
+  wrong, as every other refusal is. The whole help followed it, a hundred
+  lines, so the reason was the first line of a log that is read from its
+  end. Exit 2, as before; `spec-guard --help` prints the help.
+- A `package.json` or `.spec-guard.json` that is not JSON is refused in one
+  line. The parser quotes a short file whole, line breaks and all, so a file
+  of three lines made a refusal of three; each run of line breaks and spaces
+  in what it says is now one space. Exit 2, as before.
+
+### Documentation
+
+- `--help` and the README's options table name `SPEC_GUARD_RG` beside
+  `--engine`, and `FORCE_COLOR` and `TERM=dumb` beside `--color`, and say
+  that `NO_COLOR`, `FORCE_COLOR` or `SPEC_GUARD_RG` set to nothing is as
+  unset.
+
 ## 0.20.1
 
 A reader that closed the output, as `| head` does, was answered with

package/README.md

@@ -1064,6 +1064,13 @@ instructions tell an agent when to call each: the rules before creating or
 changing a file, the dependents before changing a file others import, and the
 check after changing files.
 
+The server starts whatever its patterns match, since a spec may be written
+while it runs. Where no spec file matches, the first two tools answer with an
+error that names the patterns. Where one pattern matches none beside others
+that do, each answer is given from the rest and ends by naming the pattern it
+holds no rule from, with `unmatchedSpecs` in its structured content and in
+`spec://rules`.
+
 | Resource | What it holds |
 | --- | --- |
 | `spec://rules` | Every rule in force, as JSON |
@@ -1251,7 +1258,9 @@ src/db/client.ts
 - **Exit 2** for a path that does not exist, and for a run of `impact` in which
   no spec matched, as `query` does: the dependents are still written, but "no
   rules" over no specs is nothing measured. `--allow-empty` asks for the
-  dependents alone, and exits 0.
+  dependents alone, and exits 0. A spec pattern that matched no file beside
+  others that did is the same: the dependents and the rules that were read
+  are written, and it is exit 2 unless `--allow-empty`.
 - **The MCP server** answers the same question as `get_dependents`, with the
   same document.
 [ADR-0018](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0018-impact.md) has the table and what it leaves out.
@@ -1270,27 +1279,27 @@ spec-guard impact <paths...>           # the files that depend on each path, and
 
 | Option | Description |
 | --- | --- |
-| `-r, --root <path>` | Codebase root that assertions resolve against (default: cwd) |
-| `--spec <pattern>` | A spec glob or path, repeatable. `query` and `mcp` take their specs only from here |
+| `-r, --root <path>` | Codebase root that assertions resolve against, a directory (default: cwd). One that is not there, or is a file, is exit 2 from every command |
+| `--spec <pattern>` | A spec glob or path, repeatable. `query` and `mcp` take their specs only from here. An empty one is refused: `.` is every Markdown file under the root. So is one that matches no file beside others that do (below) |
 | `-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 |
-| `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
+| `--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 |
 | `--allow-empty-scope` / `--no-allow-empty-scope` | Warn instead of failing when an assertion inspects no files |
 | `--print-baseline` | Print the `baseline="..."` that would exempt today's violations, and exit |
 | `--no-default-skips` / `--default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
-| `--exclude <globs>` | Paths no assertion looks at, beside each directive's own `exclude`. Repeatable; replaces the configuration's list, and `--exclude=` clears it |
+| `--exclude <globs>` | Paths no assertion looks at, beside each directive's own `exclude`. Repeatable; replaces the configuration's list, and `--exclude=` clears it. Separators with nothing between them, `","`, are refused |
 | `--ignore-status` / `--no-ignore-status` | Execute directives in documents not in force too: draft, proposed, rejected, deprecated, superseded or archived |
 | `--include-specs` / `--no-include-specs` | Also count matches inside the spec files themselves |
 | `--max-snippets <n>` | Failure snippets per assertion (default 5) |
-| `--concurrency <n>` | Search passes in flight at once (default 8) |
+| `--concurrency <n>` | Search passes in flight at once, 1 or more (default 8) |
 | `--depth <n>` | `impact` only: follow dependents at most `n` imports away (default: all) |
-| `--allow-empty` | Exit 0 when no spec file matched the patterns, for a run, `prove` or `impact` (about the run, not an assertion) |
-| `--color` / `--no-color` | Force colour on or off (`NO_COLOR` honoured) |
+| `--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 |
 
 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.
@@ -1301,6 +1310,41 @@ An option that means nothing to a command is refused rather than ignored, so
 `--no-color`: its output never has colour, and scripts pass the flag to every
 command they run.
 
+So is an option that is set and names nothing, which is exit 2 and a line
+that names it, never a run as if it had not been given. `--root "$DIR"` and
+`--spec "$DOCS"` with the variable unset were the working directory and every
+Markdown file under the root; `--concurrency 0` was 1; and an option that is
+on when it is given was on whatever followed its `=`, so `--strict=false` was
+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.
+
+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
+running, and the check was green. A run, `prove`, `impact` and `query` now
+exit 2 with one line that names each such pattern, wherever it was written, on
+the command line or in `specs`:
+
+```text
+spec-guard: the pattern "old-docs" matched no spec file. Remove it from "specs" in package.json, or give --allow-empty where a pattern is meant to match nothing.
+```
+
+- **`--allow-empty`** lets a run, `prove` or `impact` through, for a place
+  nothing is written in yet, and the pattern is still named on stderr.
+  `query` takes no such option.
+- **A document a script reads is still written**, by `--json`,
+  `--format sarif` and `--format gitlab`, and the JSON ones carry the
+  patterns as `unmatchedSpecs`. The key is there only when a pattern matched
+  no file, and `formatVersion` stays 1: a field added does not move it.
+- **`--watch` and `mcp` carry on**, since the file may yet appear. A session
+  says which pattern it is waiting on under each report, and each answer the
+  server gives names the pattern it holds no rule from, with `unmatchedSpecs`
+  in its structured content.
+- **No spec at all is as it was**: `no spec files matched ...`, exit 2, or 0
+  under `--allow-empty`. So is `docs/**/*.md`, the pattern read when none is
+  given, which is alone and so matches or leaves no spec at all.
+
 ### Configuration
 
 The options that are a project's policy can live in `package.json`, under
@@ -1415,7 +1459,9 @@ goes.
 
 `--watch` scans in-process, where it can see what each rule reads, so it refuses
 `--engine`, and `--json`, `--format json|sarif`, `--print-baseline`,
-`--fail-fast` and `--allow-empty`, which each describe a single run. It exits
+`--fail-fast` and `--allow-empty`, which each describe a single run. A spec
+pattern that matches no file does not stop a session: it waits for one to
+appear, and says which pattern that is under each report. It exits
 130 when stopped, since a session is neither a pass nor a failure. What it
 cannot see: a change the operating system never reports, a change behind a
 symbolic link, and anything outside the root. CI stays the authority.
@@ -1431,7 +1477,7 @@ should be able to tell them apart, so they are 1 and 2:
 | `1` | An assertion failed, or a directive was malformed; under `--strict`, the specs matched state no rule in force, so no assertion was executed |
 | `1`, `prove` | A rule survived, or under `--strict` none was proved |
 | `1`, `cites` | A comment cites a document that does not exist, or under `--strict` a citation is stale, a file was read in part, or no source file was read |
-| `2` | spec-guard could not run, or its answer did not arrive: bad usage, a malformed configuration, no spec files matched, `--engine rg` with no ripgrep, a watch that could not start, a `cites` family whose files match no document, a stdout its reader closed before all of the output was written, as a pipeline into `head` does, said in one line on stderr, or an error spec-guard did not expect, reported on stderr as `spec-guard: unexpected error:` with its stack |
+| `2` | spec-guard could not run, or its answer did not arrive: bad usage, an option set to something that names nothing, a root that is not a directory, a malformed configuration, no spec files matched, a spec pattern that matched none beside others that did, `--engine rg` with no ripgrep, a watch that could not start, a `cites` family whose files match no document, a stdout its reader closed before all of the output was written, as a pipeline into `head` does, said in one line on stderr, or an error spec-guard did not expect, reported on stderr as `spec-guard: unexpected error:` with its stack |
 | `130` | A `--watch` session was stopped |
 
 ## CI integration
@@ -1491,10 +1537,22 @@ runs:
 | Windows | `winget install BurntSushi.ripgrep.MSVC` |
 
 spec-guard looks for `rg` on `PATH`. `SPEC_GUARD_RG=/path/to/rg` names the
-binary instead, for one that is not on `PATH` or not called `rg`. Under the
-default `--engine auto`, a binary that cannot be run leaves the built-in
-scanner to do the work, and the report's engine says `javascript`; under
-`--engine rg` it is exit 2.
+binary instead, for one that is not on `PATH` or not called `rg`; set to
+nothing, it is as unset. Under the default `--engine auto`, a binary that
+cannot be run leaves the built-in scanner to do the work, and the report's
+engine says `javascript`. `--engine rg`, or `"engine": "rg"` in the
+configuration, is ripgrep asked for, and a run that cannot have it is exit 2
+before anything is searched, never a run on the scanner: where the variable
+names a path that is not there, a file that is no program, or a program that
+does not answer `--version` as ripgrep does, the line names the variable and
+what it holds:
+
+```text
+spec-guard: SPEC_GUARD_RG is "/opt/tools/rg", which did not answer --version as ripgrep does, and the rg engine was asked for. Set it to the path of an rg that runs, or unset it to use the rg on PATH.
+```
+
+A program that runs and is not ripgrep fails each search `auto` hands it; the
+scanner answers that search, and the report carries a warning for it.
 
 As a pre-commit hook, in a project that installed it:
 
@@ -1840,8 +1898,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.16% of 12,346 mutants
-(0.20.1), and every survivor a release adds is replayed before it ships
+Line coverage is 100%, CI's full mutation sweep kills 99.23% of 12,580 mutants
+(0.22.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

@@ -5,8 +5,9 @@
  *   0 - every assertion held
  *   1 - an assertion failed, a directive was invalid, or under --strict no
  *       assertion was executed
- *   2 - spec-guard could not run (bad usage, no spec files, missing engine),
- *       or met an error it did not expect, whose stack is on stderr
+ *   2 - spec-guard could not run (bad usage, no spec files, a spec pattern
+ *       that matched none beside others that did, missing engine), or met an
+ *       error it did not expect, whose stack is on stderr
  */
 import type { Readable } from 'node:stream';
 import { type ConfigKey, type ProjectConfig } from './config.js';
@@ -94,7 +95,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 (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      --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 (default: 8)\n      --depth <n>         impact: follow dependents at most n imports away (default: all)\n      --allow-empty       Exit 0 when no spec files matched (a run, prove or impact; not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR is honoured)\n  -h, --help              Show this help\n      --version           Print the version\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.\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  -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.\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.\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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"}