@descent-vtt/spec-guard 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,96 @@ All notable changes to this project are documented here. Versions follow
 may change in a minor release — each such change is listed under **Changed**
 with the flag that restores the previous behaviour.
 
+## 0.9.0
+
+A project's policy can live in its `package.json`, and `spec-guard --watch`
+reports again as the tree changes, re-executing only the rules a change
+affected. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
+
+### Added
+
+- **Options in `package.json`, under `"specGuard"`:** `specs`, `engine`,
+  `strict`, `allowMissingTargets`, `allowEmptyScope`, `ignoreStatus`,
+  `includeSpecs`, `defaultSkips`, `maxSnippets` and `concurrency`.
+  - Read from the root's `package.json` only, never a parent directory's.
+  - Validated before anything runs. An unknown key, an option that belongs to one
+    invocation (`format`, `verbose`, `watch`, ...), a string where a boolean goes
+    or a count out of range is exit 2, naming the file and the key. `--help` and
+    `--version` still work under a broken `package.json`.
+  - The command line wins: patterns replace `specs`, and every on/off option the
+    file can set gained its opposite - `--no-strict`,
+    `--no-allow-missing-targets`, `--no-allow-empty-scope`, `--no-ignore-status`,
+    `--no-include-specs` and `--default-skips`.
+  - A report that took anything from the file names it in a line above its
+    summary, with what the command line overrode; the JSON report carries
+    `config`.
+  - `query` applies the keys a query reads. The MCP server reads the file again
+    for every request, as it reads the specs.
+- **`spec-guard --watch`.** Reports, then reports again whenever something under
+  the root changes, until Ctrl+C, which exits 130.
+  - Saves are batched: 50 ms of quiet, or 500 ms after the first change. Enter
+    re-runs everything. A change no rule reads updates the status line only.
+  - Only the rules whose directive or inputs changed are re-executed. On this
+    repository a save in `src` re-executes 21 of 60 rules in a median of 21 ms -
+    over the 15 ms it was built to, as ADR-0014 reports - and a save elsewhere
+    takes 2-3 ms.
+  - One recursive `fs.watch` on the root, and no dependency.
+  - Refuses `--engine` - it scans in-process, where it sees what each rule reads -
+    and `--json`, `--format json|sarif`, `--print-baseline`, `--fail-fast` and
+    `--allow-empty`.
+  - A test changes trees at random and requires every report a session gives to
+    equal a fresh run's, however the change is reported, and six deliberately
+    broken sessions have to fail it.
+- **One door for every read** (`Io`, `nodeIo`, `readText`, `watchTree`), and the
+  session behind watch mode (`createSession`, `runWatch`, `createFactCache`,
+  `createMemo`) in the programmatic API. `runSpecGuard` is `planRun`, an
+  execution and `reportRun`, and those two are exported.
+  `createJavaScriptEngine(io, memo)` builds a scanner over a door, and
+  `createCachedEngine(engine, fallback)` names what it falls back to.
+- `scripts/bench-watch.mjs`, which measures a session on a copy of this
+  repository.
+
+### Changed
+
+- **API:** `defaultDirectoryReader` and `statOrNull` are gone for `nodeIo`.
+  `WalkOptions.readDirectory` is `WalkOptions.io`, `enumerateCandidates` takes an
+  `Io` as its third argument, and `createTreeIndex(root, io)` takes a whole door.
+  `Assertion.missingTargets` is gone: only execution ever wrote to it.
+- This repository keeps its specs in `package.json`, and its selfcheck, CI run
+  and SARIF upload run `spec-guard` without patterns.
+- **Mutation testing in CI runs in four parallel shards.** The full sweep took
+  42m39s against a 45-minute job limit, and a slower runner was cancelled on the
+  same source. Hosted runners vary by a fifth or more on identical work.
+  - Each shard mutates its own files, balanced on per-file minutes read from
+    sweep logs (`scripts/mutation-timeline.mjs`).
+  - A final job merges the reports (`scripts/mutation-shards.mjs`). It refuses a
+    missing shard, a file mutated twice or by the wrong shard, and shards that ran
+    different tests, then applies the 97% gate to the merged score.
+  - Every shard runs every test: Stryker's vitest runner now has `related: false`.
+  - A full sweep starts from no incremental file, and a branch's shard from only
+    its own part of main's. Stryker reports the verdicts an incremental file holds
+    for files a run does not mutate, and on the first sharded sweep every shard
+    reported every other shard's files with the previous sweep's verdicts. The
+    merge refused that sweep.
+  - No mutants were left out, the per-mutant timeout is unchanged, and the gate
+    is unchanged. [ADR-0003](docs/adr/0003-mutation-testing.md).
+
+### Fixed
+
+- **A binary file was a gap for every rule sharing its pass.** A plain run scans
+  every rule over one scope together, and kept one ledger for them: a binary file
+  holding one rule's symbol was reported against all of them with their matches
+  summed, so `--strict` failed rules over files that did not hold their symbol.
+  The count of files whose comments could not be classified leaked the same way.
+  Each rule now has its own.
+- **Two runs of one tree could list skipped files in different orders**, and past
+  the ledger's cap of 100, name different ones: files entered the ledger as their
+  reads finished. They now enter in walk order.
+- Executing one resolved assertion twice named each missing target twice. Nothing
+  did so before watch mode.
+- A test of the MCP server's durations that failed about one run in 53, on
+  floating-point error in the test.
+
 ## 0.8.0
 
 An architecture document can now state conventions about names and layout: what

package/README.md

@@ -758,6 +758,7 @@ sources they follow, and what is deliberately not implemented.
 
 ```bash
 spec-guard [patterns...] [options]     # execute the directives
+spec-guard --watch [patterns...]       # execute them again whenever the tree changes
 spec-guard query <paths...> [options]  # the rules in force for files or directories
 spec-guard mcp [options]               # serve the rules over MCP on stdio
 ```
@@ -767,17 +768,18 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 | `-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 |
 | `-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`) |
 | `--format <human\|json\|sarif>` | Output format. `sarif` uploads to GitHub code scanning |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
-| `--strict` | Treat analysis that could not be completed as a failure |
-| `--allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
-| `--allow-empty-scope` | Warn instead of failing when an assertion inspects no files |
+| `--strict` / `--no-strict` | Treat analysis that could not be completed as a failure |
+| `--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` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
-| `--ignore-status` | Execute directives in draft, proposed and superseded documents too |
-| `--include-specs` | Also count matches inside the spec files themselves |
+| `--no-default-skips` / `--default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
+| `--ignore-status` / `--no-ignore-status` | Execute directives in draft, proposed and superseded documents too |
+| `--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) |
 | `--allow-empty` | Exit 0 when no spec file matched the patterns (about the run, not an assertion) |
@@ -785,6 +787,93 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 
 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.
+
+### Configuration
+
+The options that are a project's policy can live in `package.json`, under
+`"specGuard"`, so CI, a pre-commit hook and the MCP server an agent starts all
+hold the same rules the same way:
+
+```json
+{
+  "specGuard": {
+    "specs": ["docs/**/*.md", "README.md"],
+    "strict": true
+  }
+}
+```
+
+| Key | Command line | Value |
+| --- | --- | --- |
+| `specs` | patterns, `--spec` | a non-empty array of globs |
+| `engine` | `--engine` | `"auto"`, `"rg"` or `"js"` |
+| `strict`, `allowMissingTargets`, `allowEmptyScope`, `ignoreStatus`, `includeSpecs`, `defaultSkips` | the flag of that name | `true` or `false` |
+| `maxSnippets` | `--max-snippets` | an integer, 0 or more |
+| `concurrency` | `--concurrency` | an integer, 1 or more |
+
+- **Only the root's `package.json`** is read: the `--root` directory, or the
+  working directory. Nothing is inherited from a parent directory.
+- **The command line wins, both ways.** Patterns replace `specs`, and
+  `--no-strict` beats `"strict": true`.
+- **A malformed configuration is exit 2, before anything runs**, naming the file
+  and the key: an unknown key, `"true"` where `true` goes, or an option that
+  belongs to one invocation, such as `format` or `verbose`.
+- **Every report says what it took from the file**: a line above the summary
+  such as `options from package.json: specs, strict`, and a `config` field in
+  JSON. An
+  option nobody can see should never decide a result.
+- `query` applies what a query reads, and the MCP server reads the file again
+  for every request.
+
+### Watch mode
+
+```bash
+spec-guard --watch
+```
+
+Prints the report, then prints it again whenever something under the root
+changes, until Ctrl+C. Saves are batched: a batch starts after 50 ms without a
+new change, or 500 ms after its first. On a terminal the screen is redrawn;
+otherwise each report is appended under the time. A change that no rule reads
+updates the status line and nothing else:
+
+```text
+watching 15 specs · 1 change · 21 of 60 rules re-executed · 21 ms · Enter re-runs everything, Ctrl+C stops
+```
+
+A session re-executes only the rules whose directive or inputs changed. Every
+filesystem read goes through one module, so the session can record which rule
+read what. A watcher's event only evicts what it may have changed, and the
+evicted facts are read again and compared, so noise costs one directory read,
+and a renamed directory's contents need no events of their own. Work that is a
+pure function of a file's bytes - tokenizing, comment masking, scanning - is
+remembered by the bytes' hash. Each of those is a way to report a tree that no
+longer exists, so a test changes trees at random and requires every report a
+session gives to equal a fresh run's, with six deliberately broken sessions
+that it has to catch. [ADR-0014](docs/adr/0014-configuration-and-watch.md) has
+the design, the measurements and the limits.
+
+On this repository, from a change to the report, in the quietest of four runs
+(a plain warm run took 69 ms in it):
+
+| Edit | Rules re-executed | Median |
+| --- | --- | --- |
+| a file in `src` | 21 of 60 | 21 ms |
+| a test file | 1 of 60 | 3.3 ms |
+| a file no rule reads | 0 | 2.0 ms |
+| an ADR's prose | 0 | 2.4 ms |
+
+The 15 ms this was built to is missed for a save in `src`, which re-executes the
+two layer rules and every text rule over `src`; ADR-0014 says where the time
+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
+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.
 
 ### Exit codes
 
@@ -792,7 +881,8 @@ on Windows, macOS and Linux. A directory expands to the Markdown files in it.
 | --- | --- |
 | `0` | Every assertion held |
 | `1` | An assertion failed, or a directive was malformed |
-| `2` | spec-guard could not run: bad usage, no spec files matched, `--engine rg` with no ripgrep |
+| `2` | spec-guard could not run: bad usage, a malformed configuration, no spec files matched, `--engine rg` with no ripgrep, a watch that could not start |
+| `130` | A `--watch` session was stopped |
 
 ## CI integration
 
@@ -854,9 +944,10 @@ spec-guard's claims are about a whole repository - "this symbol appears nowhere
 in `src`" - and a language server is handed one buffer at a time. Answering a
 repository-wide question on every keystroke means rescanning the tree on every
 keystroke; the alternative is answering a smaller question and calling it the
-same one. The CLI does a full run of this repository in about 130 ms, so a
-pre-commit hook or a watch loop already closes the feedback gap without a
-daemon, an extension per editor, or a protocol version matrix.
+same one. `--watch` re-evaluates this repository in milliseconds after a save
+by re-executing only what the save affected, and a pre-commit hook closes the
+rest of the gap, without a daemon, an extension per editor, or a protocol
+version matrix.
 
 ## How it works
 
@@ -1099,7 +1190,7 @@ npm install
 npm run build      # tsc -> dist/
 npm test           # vitest
 npm run test:coverage
-npm run test:mutation  # stryker (~16 min in CI; over two hours locally)
+npm run test:mutation  # stryker (four parallel jobs in CI; hours locally)
 npm run lint       # tsc --noEmit
 npm run selfcheck  # run spec-guard on its own docs
 ```
@@ -1114,10 +1205,13 @@ prebuilt binary and is never a runtime dependency.
 
 Coverage says a line ran. It does not say an assertion would notice if the line
 behaved differently. This repository measures the difference: line coverage is
-**100%**, and **97.65%** of 4,299 mutants are killed in CI, with no file below
-95%. The second number is the one worth reading - and it is the ceiling, not a
-way-point: every surviving mutant has been checked individually and the 101 that
-are left produce byte-identical output.
+**100%**, and **98.84%** of 7,763 mutants are killed in CI, with 87 survivors and
+no file below 95%. The second number is the one worth reading, and what was done
+about the survivors matters more than the score. At 0.5.1 every surviving mutant
+was checked individually, and the 101 left then produced byte-identical output.
+Each release since has replayed the survivors its own code added before it
+shipped: they were killed, deleted as dead code, or shown equivalent and
+recorded in [ADR-0003](docs/adr/0003-mutation-testing.md) with the evidence.
 
 That gap is the point. The first run scored 77.23%, and the weakest file was the
 reporter at 65.48% - not because it lacked tests, but because its tests were
@@ -1158,13 +1252,19 @@ quoted above; a full sweep is also what publishes the cache the branches start
 from, so an incremental verdict can never be built on another incremental
 verdict.
 
-The full sweep was 6m54s at 2,118 mutants, 15m51s at 3,493, and is 17m at
-4,299. That growth is why the tiers exist: a check that gets quietly more
-expensive every release is a check somebody eventually proposes lowering.
+The full sweep was 6m54s at 2,118 mutants, 15m51s at 3,493, and 42m39s at 7,763.
+That growth is why the tiers exist: a check that gets quietly more expensive
+every release is a check somebody eventually proposes lowering. It is also why
+both tiers now run in four parallel shards. One runner
+could no longer finish the full sweep reliably inside the job's limit, and the
+answer was to split the sweep rather than raise the limit or drop mutants.
+Each shard mutates its own files against every test, and a final job merges the
+reports. The merge refuses anything that is not exactly one sweep, and applies
+the 97% gate to the merged score with the same library Stryker's gate uses.
 
 Run it locally with `npm run test:mutation` if you like, but do not calibrate
 anything on the result: on the Windows machine this was developed on the same
-suite takes over two hours against 21 minutes hosted, and it scores *higher*,
+suite takes hours against 43 minutes of hosted time, and it scores *higher*,
 because far more mutants hang there and Stryker counts a hang as a kill. Linux
 CI is the measurement.
 

package/dist/cli.d.ts

@@ -7,7 +7,10 @@
  *   2 - spec-guard could not run (bad usage, no spec files, missing engine)
  */
 import type { Readable } from 'node:stream';
+import { type ConfigKey, type ProjectConfig } from './config.js';
+import { watchTree } from './io.js';
 import type { EnginePreference } from './engine.js';
+import type { ConfigUse } from './types.js';
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_ERROR = 2;
@@ -17,8 +20,17 @@ export interface CliIO {
     env: NodeJS.ProcessEnv;
     cwd: string;
     isTTY: boolean;
-    /** Where `spec-guard mcp` reads its messages. Only that command reads input. */
+    /**
+     * Where `spec-guard mcp` reads its messages, and where a watch session hears
+     * Enter. Nothing else reads input.
+     */
     stdin?: Readable;
+    /** Writes to stdout as it is, with no newline added: a watch session redraws. */
+    write?: (text: string) => void;
+    /** Starts a recursive watch on a directory; a test passes one it drives itself. */
+    watch?: typeof watchTree;
+    /** Registers what Ctrl+C and SIGTERM do, and returns how to unregister it. */
+    onInterrupt?: (handler: () => void) => () => void;
 }
 /** What the command line asked for: a run, a query, or a server. */
 export type Command = 'check' | 'query' | 'mcp';
@@ -47,8 +59,18 @@ export interface CliOptions {
     maxSnippets: number;
     concurrency: number;
     color?: boolean;
+    /** Re-run as the tree changes, until stopped. ADR-0014. */
+    watch: boolean;
     help: boolean;
     version: boolean;
+    /**
+     * The configurable options the command line set, either way.
+     *
+     * A configuration fills in only what is not here, so a flag always wins - and
+     * `--strict` given alongside `"strict": true` is still reported as the command
+     * line's doing, not the file's.
+     */
+    fromCommandLine: Set<ConfigKey>;
 }
 export declare class UsageError extends Error {
 }
@@ -60,9 +82,22 @@ 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\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 and\n  mcp 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      --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  (sarif uploads to GitHub code scanning)\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 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      --ignore-status     Execute directives in draft, proposed and superseded documents too\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      --allow-empty       Exit 0 when no spec files matched (about the run, 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\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 or superseded\n  is reported and not executed; --ignore-status runs it anyway.\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, and a check,\nas the tools get_architectural_rules and check_architecture.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
+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\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 and\n  mcp 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  (sarif uploads to GitHub code scanning)\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 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      --ignore-status     Execute directives in draft, proposed and superseded documents too\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      --allow-empty       Exit 0 when no spec files matched (about the run, 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, engine, strict, allowMissingTargets,\n  allowEmptyScope, ignoreStatus, includeSpecs, defaultSkips, maxSnippets and\n  concurrency under \"specGuard\". A flag wins over the file, and every on/off\n  option there also takes its opposite (--no-strict, --default-skips, ...).\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 or superseded\n  is reported and not executed; --ignore-status runs it anyway.\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, and a check,\nas the tools get_architectural_rules and check_architecture.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run\n  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;
+/**
+ * Fills in what the command line left unset from a configuration, and says what
+ * it took.
+ *
+ * A key the command does not read is neither applied nor overridden: `strict`
+ * is written for the runs, and a query that ignores it has not been told
+ * anything about strictness. A watch session scans in-process, so `engine` is
+ * not one of its keys either. Returns nothing when the configuration had
+ * nothing to say to this command, so a report says nothing about it.
+ */
+export declare function applyConfig(options: CliOptions, config: ProjectConfig, file?: string): ConfigUse | undefined;
+/** The process's own streams, signals and filesystem watcher. */
+export declare function defaultIO(): CliIO;
 /** Runs the CLI and resolves to the process exit code. */
 export declare function main(argv?: readonly string[], io?: CliIO): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEhD,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,SAAoB,GAAG,MAAM,CAQ5D;AAED,eAAO,MAAM,IAAI,mvGAqD8D,CAAC;AA2DhF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAqJ1E;AAoED,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}