@descent-vtt/spec-guard 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -5,7 +5,71 @@ 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.
 
-## Unreleased
+## 0.8.0
+
+An architecture document can now state conventions about names and layout: what
+the files in a directory are called, what every package holds, and which files
+come in pairs. [ADR-0013](docs/adr/0013-structure-assertions.md).
+
+### Added
+
+- **`@assert-structure`**, with exactly one of three claims per directive:
+  - `pattern="*.entity.ts, index.ts"` - every file in scope is named by one of
+    the patterns;
+  - `required="package.json, README.md"` - every directory holds each entry.
+    The directories are the targets, or with `dirs="*"` their children and with
+    `dirs="**"` every directory below them, empty ones included. An entry may be
+    a path, may end in a glob, and must be a directory when it ends in `/`;
+  - `partner="[name].test.[ext], tests/[dir]/test_[name].py"` - every file has
+    one of its partners. Three placeholders and no other grammar: `[name]` and
+    `[ext]` split the file name at its last dot, and `[dir]` is the file's
+    directory below its target.
+
+  Names are compared exactly from directory listings, never by looking a path
+  up, so `Readme.md` does not satisfy `README.md` on Windows or macOS any more
+  than it does on Linux. A scope with no files or no directories fails, as does
+  a partner template naming the file itself and a `required` target that is a
+  file. When a file has no partner because it *is* one, the report says so and
+  suggests the `exclude`. Takes `glob`, `exclude`, `max`, `allow-empty`,
+  `baseline` and `ratchet`. Spec files are in scope, and symbolic links are not
+  followed. All structure rules in a run share one walk per target and read
+  each directory once.
+- `spec-guard query` and the MCP server show what a structure rule asks of a
+  path: whether a file's name is allowed, the partners it needs, and - for a
+  file in a directory a `required` rule holds - that rule.
+- The JSON report carries `claim` on structure results. A match with `line: 0`
+  is a path rather than a place in one, and SARIF annotates a misnamed or
+  partnerless file at its first line, and a directory missing an entry at the
+  directive, with the directory in the message.
+- `checkStructure`, `createTreeIndex`, `expandPartner`, `partnerTemplateIssue`
+  and `requiredEntryIssue` are exported, with their types. `walkPaths` takes an
+  `onDirectory` callback.
+
+### Changed
+
+- **`executeAssertion` needs a `tree`** in its options: `createTreeIndex(root)`,
+  the run's directory listings, beside the `imports` and `hasFiles` caches it
+  already takes. Only code calling `executeAssertion` directly is affected;
+  `runSpecGuard` and the command line create it themselves.
+- The MCP server's instructions and the `get_architectural_rules` description
+  tell an agent that the rules for a path now include what it must be named and
+  the partner files it needs.
+- **Mutation score 98.63%** over 6,939 mutants, up from 0.7.0's 98.47%, with 92
+  survivors - one fewer than before the 676 mutants this release adds.
+  `structure.ts` is at 100%, and every other module has exactly the survivors it
+  had, less one in `glob.ts` that the new tests turned into a genuine hang. A
+  local sweep had reported four survivors in the new listing cache as killed; CI
+  found them, and they are tested. See
+  [ADR-0003](docs/adr/0003-mutation-testing.md).
+
+## 0.7.0
+
+Two things an architecture document could not do before. It can state the shape
+of a codebase: which layers depend on which, and that nothing imports itself
+round a loop. And it can be asked, before any code is written, which of its
+rules govern the file about to change - from the command line, or by an AI agent
+over the Model Context Protocol. Building the second found a false green older
+than every release, and it is fixed below.
 
 ### Added
 
@@ -30,16 +94,76 @@ with the flag that restores the previous behaviour.
   and for why the other four languages are not in the graph.
 - `buildGraph`, `resolveReference`, `stronglyConnected`, `cyclicComponents`,
   `witness`, `checkLayers` and `referenceForms` are exported, with their types.
+- **`spec-guard query <paths...>`** - the rules in force for a file or directory,
+  grouped by the document that states them, with each rule's reason, a path's
+  position in every layer order (`may import`, `must not import`), and any
+  baseline entry that exempts it. Answered from the specs alone, without reading
+  the codebase, so it works for a file that does not exist yet; `--json` for
+  scripts. Rules in documents that are not in force are counted and named, and
+  listed with `--ignore-status`. The arithmetic behind it is tested against the
+  files a real run searches, under both engines and on random trees; see
+  [ADR-0012](docs/adr/0012-query-and-mcp.md) for the three things it cannot see.
+- **`spec-guard mcp`** - a Model Context Protocol server on stdio, with no
+  dependency on the MCP SDK. Tools `get_architectural_rules` (the query) and
+  `check_architecture` (a run, narrowed to the rules governing given paths, each
+  judged over its whole scope, with violations marked as in those paths or not);
+  resources `spec://rules` and `spec://doc/{+path}`. Serves clients that open
+  with `initialize` (2024-10-07 to 2025-11-25) and clients on 2026-07-28 that
+  version every request and probe with `server/discover`, classifying each
+  request the way the TypeScript SDK's own server does. Run end to end against
+  the official clients: `@modelcontextprotocol/sdk` 1.30.0, and
+  `@modelcontextprotocol/client` 2.0.0 pinned to 2026-07-28, probing, and on
+  the legacy handshake.
+- **`--spec <pattern>`**, repeatable: where `query` and `mcp` take their specs,
+  and an alternative to positional patterns for a run.
+- `select` on `runSpecGuard`, to execute only some of the resolved assertions.
+  `readSpecs`, `parseDocument`, `parseTitle`, `walkPaths`, `governs`,
+  `queryRules`, `createMcpHandler` and `serveStdio` are exported, with their types.
+
+### Fixed
+
+- **A rule whose every `target` was missing searched the whole repository**
+  under `--allow-missing-targets`, because an empty target list means the root
+  to the engine. So `@assert-count target="src/auth" symbol="verifyToken"
+  min="1"` kept passing after `src/auth` was deleted, as long as a test still
+  named `verifyToken`; import, layer and cycle rules did the same. This has been
+  true since 0.1.0 - the 0.3.0 entry below that describes the old behaviour as
+  "search nothing, find nothing" was wrong about what the code did. Such a rule
+  now has an empty scope: it fails as one, and with `--allow-empty-scope` or
+  `allow-empty="true"` it finds nothing. **If you rely on
+  `--allow-missing-targets` for a rule whose only target is gone, add
+  `--allow-empty-scope`.**
+- An import rule whose only target is missing, without `--allow-missing-targets`,
+  now says the target does not exist instead of that its scope is empty.
 
 ### Changed
 
-- **Mutation score 97.97%** over 5,078 mutants, up from 0.6.0's 97.77%. The two
-  new modules are at 99.51% (`graph.ts`) and 96.43% (`layers.ts`), and each of
-  their three survivors was shown equivalent by running the mutated build
-  against the real one on thousands of random inputs. The first sweep of this
-  work found 34 survivors that 37 hand-written negative controls had not; see
-  [ADR-0003](docs/adr/0003-mutation-testing.md) for how they were replayed from
-  the report and killed.
+- **`query` and `mcp` are commands when they are the first argument.** A spec
+  file literally named `query` or `mcp`, passed as the first pattern, now starts
+  a command instead; write `./query`, or put it after `--`.
+- **A rule whose every `target` is missing has an empty scope under
+  `--allow-missing-targets`**, where it used to search the whole repository -
+  see Fixed. Add `--allow-empty-scope`, or `allow-empty="true"` on the rule, for
+  it to pass. Searching the root in its place is not restorable: it was the bug.
+- **Mutation score 98.47%** over 6,263 mutants, up from 0.6.0's 97.77%, with 93
+  survivors - four fewer than before the 1,185 mutants this release adds. The
+  layering and cycle modules are at 99.51% (`graph.ts`) and 96.43%
+  (`layers.ts`); their three survivors were shown equivalent by running the
+  mutated build against the real one on thousands of random inputs. The query
+  and the server (`query.ts`, `rules.ts`, `mcp.ts`, `specs.ts`) are all at 100%;
+  most of the survivors found on the way were code nothing could observe, and it
+  was deleted. See [ADR-0003](docs/adr/0003-mutation-testing.md) for both
+  accounts, and for why one sweep's count is good to about three.
+- `version(manifest?)` takes the manifest to read, so its fallback for a broken
+  install - `0.0.0` rather than a crash - is tested.
+- **Reading specs is several times faster**, which a query's budget made worth
+  measuring. `maskCode` builds ranges instead of blanking a character array
+  (7.8 ms to 1.1 ms over this repository's specs, identical output on 72 real
+  documents and 100,000 random inputs); spec globs no longer stat every file
+  they list (102 ms to 18 ms over 1,200 specs on Windows); and specs are read
+  16 at a time. A query over this repository went from 24.6 ms to 5.1 ms. A run
+  spends most of its time searching code, so this repository's selfcheck gained
+  about 8%.
 - The SARIF fingerprint of an assertion that names neither a symbol nor a file
   now includes its description. Only the two new kinds are affected; every
   existing alert keeps its identity. Without it, two cycle rules on one target

package/README.md

@@ -422,6 +422,99 @@ reading `tsconfig.json`, which is the resolver
 [ADR-0011](docs/adr/0011-layers-and-cycles.md) declines to become, for the
 reasons it gives.
 
+### `@assert-structure` - what files are called, and what comes with them
+
+Architecture documents state conventions over sets of files rather than naming
+files one by one. Each directive makes exactly one of three claims:
+
+```md
+<!-- @assert-structure target="src/domain" exclude="*.test.ts" pattern="*.entity.ts, index.ts" -->
+<!-- @assert-structure target="packages" dirs="*" required="package.json, README.md" -->
+<!-- @assert-structure target="src/handlers" exclude="*.test.ts" partner="[name].test.ts" -->
+```
+
+- **`pattern`** - every file in scope is named by one of the patterns. They are
+  globs, read like `glob=`: without a `/` against the file name, with one
+  against the path from the root.
+- **`required`** - every directory holds every entry. Without `dirs` the
+  directories are the targets; `dirs="*"` means their immediate children and
+  `dirs="**"` every directory below them. An entry may be a path
+  (`src/index.ts`), may end in a glob (`*.csproj`), and must be a directory
+  when it ends in `/`.
+- **`partner`** - every file has a partner, named by a template.
+
+Each failure names the file or directory, since there is no line to point at:
+
+```text
+✖ docs/architecture.md:3  @assert-structure
+    files in src/domain must be named *.entity.ts or index.ts (excluding *.test.ts)
+    expected no misnamed files, found 1
+      src/domain/helpers.ts  matches none of *.entity.ts, index.ts
+
+✖ docs/architecture.md:4  @assert-structure
+    directories matching * under packages must contain package.json, README.md
+    expected no directories missing an entry, found 2
+      packages/billing  missing README.md
+      packages/web  missing package.json, README.md
+
+✖ docs/architecture.md:5  @assert-structure
+    files in src/handlers must each have a partner [name].test.ts (excluding *.test.ts)
+    expected no files without a partner, found 1
+      src/handlers/refund.ts  has no partner src/handlers/refund.test.ts
+```
+
+A partner template has three placeholders and nothing else - no regular
+expressions, no conditionals - so a reader can expand one by eye:
+
+| Placeholder | For `src/api/user.handler.ts`, `target="src"` |
+| --- | --- |
+| `[name]` | `user.handler` - the file name up to its last dot |
+| `[ext]` | `ts` - what follows that dot |
+| `[dir]` | `api` - the file's directory below the target, empty at the top |
+
+A template without a `/` names a file beside it. One with a `/` is a path from
+the root, which is how a mirrored test tree is written:
+`partner="tests/[dir]/test_[name].py"`. A comma-separated list gives
+alternatives, any one of which will do.
+
+The partners themselves are in scope unless `exclude` says otherwise. Forgetting
+to exclude them is loud rather than silent, and says what probably happened:
+
+```text
+      src/handlers/order.test.ts  has no partner src/handlers/order.test.test.ts (it is the partner of src/handlers/order.ts - exclude it?)
+```
+
+Some things fail rather than pass, because each is a rule that would otherwise
+check nothing:
+- a scope holding no files, or selecting no directories (`allow-empty` as
+  everywhere else);
+- a template that names the file itself (`partner="[name].[ext]"`);
+- a `required` target that is a file.
+
+**Names are compared exactly, on every platform.** Whether `README.md` exists is
+decided by reading its directory, never by asking the filesystem for the path.
+That lookup finds `Readme.md` on Windows and macOS and does not find it on Linux,
+and the same rule would pass on a laptop and fail in CI.
+
+A structure rule reads names, never contents. It walks with the run's usual
+skips, follows no symbolic link, and counts the spec files - which every other
+rule leaves out, and which a naming rule about `docs/adr` is about. `max`,
+`baseline` and `ratchet` work as they do on `@assert-absence`, and a baseline
+lists files or directories. `spec-guard query` shows what a rule asks of a file
+that does not exist yet:
+
+```text
+src/handlers/invoice.ts (does not exist yet)
+  1 rule from 1 document
+
+  Architecture  (docs/architecture.md)
+    :5 @assert-structure  files in src/handlers must each have a partner [name].test.ts (excluding *.test.ts)
+      partner: src/handlers/invoice.test.ts
+```
+
+[ADR-0013](docs/adr/0013-structure-assertions.md) has the design and what it
+costs.
+
 ### `@assert-present` - this file exists
 
 ```md
@@ -435,23 +528,27 @@ Passes when every listed path exists relative to `--root`. Directories count.
 
 | Attribute | Applies to | Meaning |
 | --- | --- | --- |
-| `target` | absence, count | Comma-separated paths to search, relative to `--root`. Default `.` |
+| `target` | all but present | Comma-separated paths, relative to `--root`. Default `.` |
 | `symbol` | absence, count | The literal string to search for (or a regex with `regex="true"`) |
 | `file` | present | Comma-separated paths that must exist |
-| `expected` | absence, count | Upper bound for absence; exact count for count |
-| `min` / `max` | count (`max` also on absence) | Inclusive bounds |
-| `glob` | absence, count | Include-only file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
-| `exclude` | absence, count | Paths to leave out, gitignore-style: `src/config/**`, `tests`, `*.test.ts` |
+| `expected` | all but present | Exact count for count; an upper bound everywhere else |
+| `min` / `max` | count (`max` on all but present) | Inclusive bounds |
+| `glob` | absence, count, structure | Include-only file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
+| `exclude` | all but present | Paths to leave out, gitignore-style: `src/config/**`, `tests`, `*.test.ts` |
 | `regex` | absence, count | Treat `symbol` as a regular expression |
 | `word` | absence, count | Require word boundaries, so `Primary` does not match `PrimaryButton` |
 | `ignore-case` | absence, count | Case-insensitive matching |
 | `comments` | absence, count | `ignore` (default) or `include` for matches inside comments |
 | `module` | import-absence, import-count | Which dependency, matched like `exclude` |
 | `order` | layers | The layers, from the one everything may depend on to the one that may depend on everything |
+| `pattern` | structure | The names every file in scope must match one of |
+| `required` | structure | The entries every chosen directory must hold; a trailing `/` means a directory |
+| `dirs` | structure, with `required` | Which directories below each target: `*` for children, `**` for all |
+| `partner` | structure | Partner templates, any one of which must exist: `[name].test.[ext]` |
 | `types` | import assertions, layers, cycles | `include` (default) or `ignore` for `import type` |
-| `allow-empty` | absence, count, import assertions, layers, cycles | Tolerate a scope that holds no files, or a layer that matches none. Off by default - see below |
-| `baseline` | absence, import-absence, layers | Known violations that do not count: `path` or `path:count` |
-| `ratchet` | absence, import-absence, layers | `two-sided` (default) or `one-way` - see below |
+| `allow-empty` | all but present | Tolerate a scope that holds no files, a layer that matches none, or no chosen directories. Off by default - see below |
+| `baseline` | absence, import-absence, layers, structure | Known violations that do not count: `path` or `path:count` |
+| `ratchet` | absence, import-absence, layers, structure | `two-sided` (default) or `one-way` - see below |
 | `reason` | all | Human-readable justification, printed on failure |
 
 Unknown attributes are an error, not a shrug: `expct="1"` fails the run instead
@@ -575,15 +672,100 @@ pass if you accepted it today.
 [ADR-0010](docs/adr/0010-spec-status.md) has the full reasoning, including why
 there is no per-directive `if-status` attribute.
 
+## Asking before writing - `query` and the MCP server
+
+A run tells you, after the fact, that code broke a rule. `spec-guard query`
+tells you which rules a file is under before you touch it:
+
+```bash
+spec-guard query src/domain/user.ts --spec "docs/**/*.md"
+```
+
+```text
+src/domain/user.ts
+  3 rules from 2 documents
+
+  ADR-0004: No legacy client  (docs/adr/0004-legacy.md, accepted)
+    :12 @assert-absence  "LegacyClient" must not appear in src
+
+  ADR-0011: Layering constraints  (docs/adr/0011-layers.md, accepted)
+    :40 @assert-layers  src must keep its layers in order, src/domain < src/application < src/infrastructure
+      layer: src/domain (1 of 3)
+      may import: src/domain
+      must not import: src/application, src/infrastructure
+      reason: the domain depends on nothing
+    :41 @assert-import-absence  src/domain must not import "pg"
+
+  1 more rule would govern this path if docs/adr/0014-clocks.md (proposed) were in force; --ignore-status lists it
+
+14 spec files read in 6.1ms
+```
+
+It answers from the specs alone, without reading the codebase, so it works for
+a file that does not exist yet. A directory lists every rule that could reach a
+file under it. `--json` is the same answer for a script. Rules in documents that
+are not in force are counted and named, never silently left out.
+
+The arithmetic that decides whether a rule governs a path is tested against the
+walk a real run makes, file for file, under both engines and on randomly
+generated trees. [ADR-0012](docs/adr/0012-query-and-mcp.md) lists the three
+things it cannot see: file content (binary, oversized, unreadable), symbolic
+links, and letter case on case-insensitive filesystems.
+
+### The MCP server
+
+`spec-guard mcp` serves the same answer to an AI agent over the
+[Model Context Protocol](https://modelcontextprotocol.io) on stdio, with no
+dependency on the MCP SDK. Register it with your client as a stdio server; the
+usual `mcpServers` entry is:
+
+```json
+{
+  "mcpServers": {
+    "spec-guard": {
+      "command": "npx",
+      "args": ["spec-guard", "mcp", "--spec", "docs/**/*.md"]
+    }
+  }
+}
+```
+
+The root defaults to the directory the client starts the server in; pass
+`--root` if yours starts servers somewhere else. On Windows, `npx` is a `.cmd`
+script that a client spawning without a shell cannot launch; point `command` at
+`node` and the first argument at
+`node_modules/@descent-vtt/spec-guard/bin/spec-guard.js` instead. Run flags such
+as `--engine`, `--strict`, `--ignore-status` and `--allow-missing-targets` apply
+to its checks.
+
+| Tool | What it does |
+| --- | --- |
+| `get_architectural_rules(path, include_inactive?)` | The query above, as text and as structured content |
+| `check_architecture(paths?)` | A run. Given paths, only the rules that govern them, each over its whole scope, with every violation marked as in those paths or not |
+
+| Resource | What it holds |
+| --- | --- |
+| `spec://rules` | Every rule in force, as JSON |
+| `spec://doc/{+path}` | Any spec document, in force or not |
+
+Both protocol eras are served: clients that open with `initialize` (revisions
+2024-10-07 to 2025-11-25), and clients on 2026-07-28 that put the protocol
+version on every request and probe with `server/discover`. Nothing is cached, so
+an ADR edited mid-session is read as edited. ADR-0012 has the shapes, the
+sources they follow, and what is deliberately not implemented.
+
 ## CLI
 
 ```bash
-spec-guard [patterns...] [options]
+spec-guard [patterns...] [options]     # execute the directives
+spec-guard query <paths...> [options]  # the rules in force for files or directories
+spec-guard mcp [options]               # serve the rules over MCP on stdio
 ```
 
 | 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 |
 | `-v, --verbose` | Print passing assertions too |
 | `--fail-fast` | Stop at the first failing assertion |
 | `--json` | Machine-readable report on stdout (same as `--format json`) |

package/dist/cli.d.ts

@@ -6,6 +6,7 @@
  *   1 - an assertion failed, or a directive was invalid
  *   2 - spec-guard could not run (bad usage, no spec files, missing engine)
  */
+import type { Readable } from 'node:stream';
 import type { EnginePreference } from './engine.js';
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
@@ -16,11 +17,18 @@ export interface CliIO {
     env: NodeJS.ProcessEnv;
     cwd: string;
     isTTY: boolean;
+    /** Where `spec-guard mcp` reads its messages. Only that command reads input. */
+    stdin?: Readable;
 }
+/** What the command line asked for: a run, a query, or a server. */
+export type Command = 'check' | 'query' | 'mcp';
 /** How a finished run is written out. */
 export type OutputFormat = 'human' | 'json' | 'sarif';
 export interface CliOptions {
+    command: Command;
     patterns: string[];
+    /** The paths `spec-guard query` asks about. */
+    paths: string[];
     root: string;
     verbose: boolean;
     failFast: boolean;
@@ -44,8 +52,15 @@ export interface CliOptions {
 }
 export declare class UsageError extends Error {
 }
-export declare function version(): string;
-export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]\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.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)\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\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\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
+/**
+ * The installed version, or `0.0.0` when the manifest cannot say.
+ *
+ * The manifest is a parameter so the fallback can be tested: it is what a
+ * broken install reports instead of crashing, and a fallback nothing runs is a
+ * 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";
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
 /** Runs the CLI and resolves to the process exit code. */

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,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;CAChB;AAED,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,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,wBAAgB,OAAO,IAAI,MAAM,CAShC;AAED,eAAO,MAAM,IAAI,wlFA4C8D,CAAC;AAgChF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAkI1E;AAYD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4EpH"}
+{"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"}