@descent-vtt/spec-guard 0.11.0 → 0.12.1

package/dist/cli.d.ts

@@ -10,7 +10,7 @@ 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';
+import type { CiteFamily, ConfigUse } from './types.js';
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_ERROR = 2;
@@ -32,15 +32,23 @@ export interface CliIO {
     /** 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';
+/**
+ * What the command line asked for: a run, a query, a server, a proof that the
+ * rules can fail, the citations of specs in code comments, or who depends on a
+ * path.
+ */
+export type Command = 'check' | 'query' | 'mcp' | 'prove' | 'cites' | 'impact';
 /** How a finished run is written out. */
-export type OutputFormat = 'human' | 'json' | 'sarif';
+export type OutputFormat = 'human' | 'json' | 'sarif' | 'github' | 'gitlab';
 export interface CliOptions {
     command: Command;
     patterns: string[];
-    /** The paths `spec-guard query` asks about. */
+    /** The paths `spec-guard query` and `spec-guard impact` ask about, and the ones `spec-guard cites` reads. */
     paths: string[];
+    /** How many imports away `spec-guard impact` follows dependents; all of them when absent. */
+    depth?: number;
+    /** The documents comments cite, from a configuration; derived from the specs when absent. */
+    cites?: CiteFamily[];
     root: string;
     verbose: boolean;
     failFast: boolean;
@@ -84,7 +92,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\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      --exclude <globs>   Paths no assertion looks at, beside each directive's exclude; repeatable\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, 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\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";
+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 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\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   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;
 /**

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -8,17 +8,40 @@
  */
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { CitesError, findCitations } from './cites.js';
 import { CONFIG_KEYS, ConfigError, engineNamed, findConfig } from './config.js';
-import { excludeListError } from './glob.js';
+import { formatImpact, formatImpactJson, impactOf } from './impact.js';
+import { excludeListError, patternListError, specPatternError } from './glob.js';
 import { nodeIo, readText, watchTree } from './io.js';
 import { createMcpHandler, serveStdio } from './mcp.js';
-import { formatQuery, formatQueryJson, queryRules } from './query.js';
-import { formatBaselines, formatConfigUse, formatJson, formatReport, formatSarif, shouldUseAscii, shouldUseColor } from './reporter.js';
+import { formatQuery, formatQueryJson, queryRules, resolveQueryPath } from './query.js';
+import { proveSpecGuard } from './prove.js';
+import { citesAnnotations, formatBaselines, formatCites, formatCitesJson, formatCitesSarif, formatConfigUse, formatGithub, formatGitlab, formatJson, formatProve, formatProveJson, formatProveSarif, formatReport, formatSarif, proveAnnotations, runAnnotations, shouldUseAscii, shouldUseColor, } from './reporter.js';
 import { DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, runSpecGuard, splitList } from './runner.js';
 import { createSession, runWatch } from './watch.js';
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_ERROR = 2;
+/** The words that name a command when they come first. */
+const COMMANDS = new Set(['query', 'mcp', 'prove', 'cites', 'impact']);
+/**
+ * The formats each command writes. A command that lists rules rather than
+ * findings has nothing to put on a line of code, so it has no SARIF, GitHub or
+ * GitLab form; `mcp` writes the protocol, and refuses `--format` altogether.
+ */
+const FORMATS = {
+    check: ['human', 'json', 'sarif', 'github', 'gitlab'],
+    prove: ['human', 'json', 'sarif', 'github', 'gitlab'],
+    cites: ['human', 'json', 'sarif', 'github', 'gitlab'],
+    query: ['human', 'json'],
+    impact: ['human', 'json'],
+};
+/** What a command without line-level formats lists instead of results, for the message refusing one. */
+const LISTS = { query: 'rules', impact: 'files and rules' };
+/** `a or b`, `a, b or c`: every command that takes a format has at least two. */
+function either(words) {
+    return `${words.slice(0, -1).join(', ')} or ${words[words.length - 1]}`;
+}
 export class UsageError extends Error {
 }
 /**
@@ -44,11 +67,15 @@ Usage
   spec-guard [patterns...] [options]     execute the directives in the specs
   spec-guard query <paths...> [options]  list the rules in force for files or directories
   spec-guard mcp [options]               serve the rules to an AI agent over MCP on stdio
+  spec-guard prove [patterns...] [options]
+                                         show each rule a violation of itself, in memory, and report any that pass
+  spec-guard cites [paths...] [options]  check that each spec a code comment cites exists and is in force
+  spec-guard impact <paths...> [options] the files that depend on each path, and the rules in play there
 
 Patterns
   Globs or paths to the Markdown specs to execute. A directory expands to the
-  Markdown files inside it. Defaults to "docs/**/*.md" when omitted. query and
-  mcp take theirs from --spec.
+  Markdown files inside it. Defaults to "docs/**/*.md" when omitted. query,
+  mcp, cites and impact take theirs from --spec.
 
 Options
   -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)
@@ -57,7 +84,8 @@ Options
       --watch             Run again as the tree changes, until Ctrl+C (human output only)
       --fail-fast         Stop at the first failing assertion
       --json              Emit a machine-readable JSON report (same as --format json)
-      --format <name>     human | json | sarif  (sarif uploads to GitHub code scanning)
+      --format <name>     human | json | sarif | github | gitlab  (sarif uploads to code scanning,
+                          github annotates a pull request from the log, gitlab is Code Quality)
       --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)
       --strict            Treat analysis that could not be completed as a failure
       --allow-missing-targets
@@ -66,11 +94,12 @@ Options
       --print-baseline    Print the baseline="..." that would exempt today's violations, and exit
       --no-default-skips  Search .git, .hg, .svn and node_modules too
       --exclude <globs>   Paths no assertion looks at, beside each directive's exclude; repeatable
-      --ignore-status     Execute directives in draft, proposed and superseded documents too
+      --ignore-status     Execute directives in documents not in force too (see Directives)
       --include-specs     Also count matches inside the spec files themselves
       --max-snippets <n>  Failure snippets per assertion (default: ${DEFAULT_MAX_SNIPPETS})
       --concurrency <n>   Assertions executed in parallel (default: ${DEFAULT_CONCURRENCY})
-      --allow-empty       Exit 0 when no spec files matched (about the run, not an assertion)
+      --depth <n>         impact: follow dependents at most n imports away (default: all)
+      --allow-empty       Exit 0 when no spec files matched (a run, prove or impact; not an assertion)
       --color/--no-color  Force colour on or off (NO_COLOR is honoured)
   -h, --help              Show this help
       --version           Print the version
@@ -82,6 +111,9 @@ Configuration
   keep them in .spec-guard.json instead, but not in both. A flag wins over the
   file, every on/off option there also takes its opposite (--no-strict,
   --default-skips, ...), and --exclude= with nothing clears exclude.
+  "cites": [{ "id": "ADR-{n}", "files": "docs/adr/{n}-*.md" }] names the
+  documents code comments cite; without it, cites reads them off the titles of
+  numbered specs.
 
 Directives
   <!-- @assert-absence target="src/" symbol="LegacyGateway" exclude="src/legacy/**" -->
@@ -93,12 +125,29 @@ Directives
 
   Matches inside comments do not count; add comments="include" to count them.
   An assertion whose scope holds no files fails; add allow-empty="true" to allow it.
-  A document whose status is draft, proposed, rejected, deprecated or superseded
-  is reported and not executed; --ignore-status runs it anyway.
+  A document whose status is draft, proposed, rejected, deprecated, superseded
+  or archived is reported and not executed; --ignore-status runs it anyway.
+
+prove adds, changes or removes files in memory only - never on disk - to make
+the violation each rule forbids, and runs the rule over that tree. A rule that
+still passes survived, and exits 1; one no violation could be made for is
+unprovable, and exits 1 under --strict.
+
+cites reads comment text only - not strings, not Markdown - for ids such as
+ADR-0007, ADR-7 and ADR-007, which are one document. A ghost citation names no
+document, and exits 1; a stale one names a document superseded, deprecated,
+rejected or archived, and exits 1 under --strict. A family whose files match no
+document exits 2.
+
+impact follows the import graph backwards: relative JavaScript, TypeScript and
+Python imports that name a file. Go, Rust, C# and absolute Python imports name
+modules, and are counted rather than followed; an import that names no file is
+listed, never guessed at.
 
 query answers from the specs alone, without reading the codebase, so it works
-for a file that does not exist yet. mcp offers the same answer, and a check,
-as the tools get_architectural_rules and check_architecture.
+for a file that does not exist yet. mcp offers the same answer, a check and
+impact's, as the tools get_architectural_rules, check_architecture and
+get_dependents.
 
 Exit codes
   0 all assertions passed   1 an assertion failed   2 spec-guard could not run
@@ -150,7 +199,50 @@ const NOT_FOR = {
         '--concurrency',
         '--color',
     ]),
+    // Who depends on a path is answered from the graph, and the rules from the
+    // specs, as a query answers them: nothing is run, so nothing about running
+    // applies. `--allow-empty` does: the dependents are an answer without specs.
+    impact: new Set([
+        '--verbose',
+        '--watch',
+        '--fail-fast',
+        '--engine',
+        '--strict',
+        '--no-strict',
+        '--allow-missing-targets',
+        '--no-allow-missing-targets',
+        '--allow-empty-scope',
+        '--no-allow-empty-scope',
+        '--print-baseline',
+        '--max-snippets',
+        '--concurrency',
+        '--color',
+    ]),
     mcp: new Set(['--verbose', '--watch', '--fail-fast', '--json', '--format', '--print-baseline', '--allow-empty', '--color', '--no-color']),
+    // A proof runs every rule, one at a time, with the scanner reading through a
+    // door ripgrep cannot see through, and prints no snippets.
+    prove: new Set(['--watch', '--fail-fast', '--print-baseline', '--engine', '--concurrency', '--max-snippets']),
+    // Citations are read from comments, not from rules: nothing is executed, so
+    // nothing about how rules run applies, and a document's status is the
+    // answer rather than something to ignore.
+    cites: new Set([
+        '--verbose',
+        '--watch',
+        '--fail-fast',
+        '--engine',
+        '--allow-missing-targets',
+        '--no-allow-missing-targets',
+        '--allow-empty-scope',
+        '--no-allow-empty-scope',
+        '--print-baseline',
+        '--ignore-status',
+        '--no-ignore-status',
+        '--include-specs',
+        '--no-include-specs',
+        '--max-snippets',
+        '--concurrency',
+        '--allow-empty',
+    ]),
 };
 /**
  * Options a watch session refuses, and why.
@@ -171,7 +263,7 @@ const NOT_WITH_WATCH = [
 const LONG_NAMES = { '-v': '--verbose' };
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export function parseArgs(argv, cwd) {
-    const command = argv[0] === 'query' || argv[0] === 'mcp' ? argv[0] : 'check';
+    const command = COMMANDS.has(argv[0]) ? argv[0] : 'check';
     const specs = [];
     const options = {
         command,
@@ -208,7 +300,7 @@ export function parseArgs(argv, cwd) {
         if (onlyPositional || !argument.startsWith('-') || argument === '-') {
             if (command === 'mcp')
                 throw new UsageError(`spec-guard mcp takes no arguments, got "${argument}". Name specs with --spec.`);
-            (command === 'query' ? options.paths : options.patterns).push(argument);
+            (command === 'query' || command === 'cites' || command === 'impact' ? options.paths : options.patterns).push(argument);
             continue;
         }
         if (argument === '--') {
@@ -252,11 +344,14 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--format': {
                 const value = nextValue().toLowerCase();
-                if (command === 'query' && value === 'sarif') {
-                    throw new UsageError('spec-guard query has no sarif format: it lists rules, not results. Expected human or json.');
-                }
-                if (value !== 'human' && value !== 'json' && value !== 'sarif') {
-                    throw new UsageError(`Unknown format "${value}". Expected human, json or sarif.`);
+                // mcp refused --format above, so every command that gets here writes one.
+                const formats = FORMATS[command];
+                if (!formats.includes(value)) {
+                    // Only a command that lists leaves out one of check's formats, so
+                    // one refused here is refused by a command LISTS names.
+                    throw new UsageError(FORMATS.check.includes(value)
+                        ? `spec-guard ${command} has no ${value} format: it lists ${LISTS[command]}, not results. Expected ${either(formats)}.`
+                        : `Unknown format "${value}". Expected ${either(formats)}.`);
                 }
                 options.format = value;
                 options.json = value === 'json';
@@ -341,6 +436,15 @@ export function parseArgs(argv, cwd) {
                 options.concurrency = Math.max(1, positiveInteger(name, nextValue()));
                 set.add('concurrency');
                 break;
+            case '--depth': {
+                if (command !== 'impact')
+                    throw new UsageError('Option --depth applies only to spec-guard impact.');
+                const depth = positiveInteger(name, nextValue());
+                if (depth === 0)
+                    throw new UsageError('Option --depth expects 1 or more: a depth of 0 would follow no import.');
+                options.depth = depth;
+                break;
+            }
             default:
                 throw new UsageError(`Unknown option "${name}". Run spec-guard --help.`);
         }
@@ -360,10 +464,26 @@ export function parseArgs(argv, cwd) {
     if (command === 'query' && options.paths.length === 0 && !options.help && !options.version) {
         throw new UsageError('spec-guard query needs a path to ask about, e.g. spec-guard query src/domain/user.ts.');
     }
+    if (command === 'impact' && options.paths.length === 0 && !options.help && !options.version) {
+        throw new UsageError('spec-guard impact needs a path to ask about, e.g. spec-guard impact src/db/client.ts.');
+    }
     return options;
 }
 /** The configurable options a query reads; the rest are about running rules. */
 const QUERY_KEYS = new Set(['specs', 'exclude', 'ignoreStatus', 'includeSpecs', 'defaultSkips']);
+/** The configurable options a citation check reads: which specs, what to leave out, and how strictly. */
+const CITES_KEYS = new Set(['specs', 'exclude', 'strict', 'defaultSkips', 'cites']);
+/** The configurable options a proof reads: what decides whether a rule passes, and not how a run is scheduled. */
+const PROVE_KEYS = new Set([
+    'specs',
+    'exclude',
+    'strict',
+    'allowMissingTargets',
+    'allowEmptyScope',
+    'ignoreStatus',
+    'includeSpecs',
+    'defaultSkips',
+]);
 /** Where each key of a configuration lands on the command line's options. */
 const SETTERS = {
     specs: (options, value) => {
@@ -399,6 +519,9 @@ const SETTERS = {
     concurrency: (options, value) => {
         options.concurrency = value;
     },
+    cites: (options, value) => {
+        options.cites = value.map((family) => ({ ...family }));
+    },
 };
 /**
  * Fills in what the command line left unset from a configuration, and says what
@@ -417,7 +540,14 @@ export function applyConfig(options, config, file = 'package.json') {
         const value = config[key];
         if (value === undefined)
             continue;
-        if (options.command === 'query' ? !QUERY_KEYS.has(key) : options.watch && key === 'engine')
+        const reads = options.command === 'query' || options.command === 'impact'
+            ? QUERY_KEYS.has(key)
+            : options.command === 'prove'
+                ? PROVE_KEYS.has(key)
+                : options.command === 'cites'
+                    ? CITES_KEYS.has(key)
+                    : key !== 'cites' && !(options.watch && key === 'engine');
+        if (!reads)
             continue;
         if (options.fromCommandLine.has(key)) {
             overridden.push(key);
@@ -592,6 +722,144 @@ async function runMcp(options, commandLine, io, use) {
     await serveStdio(io.stdin, io.stdout, handler);
     return EXIT_OK;
 }
+/**
+ * `spec-guard prove`: each rule shown a violation of itself, in memory. ADR-0016.
+ *
+ * Exit 1 when a rule survived, or a directive could not be read; under
+ * `--strict`, when a rule is unprovable too, since a rule nobody can show
+ * failing is analysis that could not be completed.
+ */
+async function runProve(options, io, use) {
+    let report;
+    try {
+        report = {
+            ...(await proveSpecGuard({
+                patterns: options.patterns,
+                root: options.root,
+                allowMissingTargets: options.allowMissingTargets,
+                strictTargets: options.strictTargets,
+                allowEmptyScope: options.allowEmptyScope,
+                includeSpecs: options.includeSpecs,
+                defaultSkips: options.defaultSkips,
+                exclude: options.exclude,
+                ignoreStatus: options.ignoreStatus,
+            })),
+            config: use,
+        };
+    }
+    catch (error) {
+        io.stderr(`spec-guard: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_ERROR;
+    }
+    if (report.summary.specs === 0 && (options.format === 'human' || options.format === 'github')) {
+        io.stderr(`spec-guard: no spec files matched ${options.patterns.map((p) => `"${p}"`).join(', ')}`);
+        return options.allowEmpty ? EXIT_OK : EXIT_ERROR;
+    }
+    const written = options.format === 'sarif'
+        ? formatProveSarif(report, { version: version() })
+        : options.format === 'json'
+            ? formatProveJson(report)
+            : options.format === 'gitlab'
+                ? formatGitlab(proveAnnotations(report))
+                : options.format === 'github'
+                    ? formatGithub(proveAnnotations(report))
+                    : formatProve(report, {
+                        color: shouldUseColor({ isTTY: io.isTTY }, options.color, io.env),
+                        verbose: options.verbose,
+                        ascii: shouldUseAscii(io.env),
+                    });
+    // GitHub's commands are one per finding, and a proof with none has no line to write.
+    if (written !== '')
+        io.stdout(written);
+    if (report.summary.specs === 0)
+        return options.allowEmpty ? EXIT_OK : EXIT_ERROR;
+    return report.ok && !(options.strictTargets && report.summary.unprovable > 0) ? EXIT_OK : EXIT_FAILED;
+}
+/**
+ * `spec-guard impact`: the files that depend on each path, and the rules in
+ * play there. ADR-0018. Exit 2 for a path outside the root or not there, and
+ * when no spec matched, as a query does: the dependents are written, but "no
+ * rules" over no specs is nothing measured, which the family contract says is
+ * not clean. `--allow-empty` asks for the dependents alone.
+ */
+async function runImpact(options, io, use) {
+    let report;
+    try {
+        report = await impactOf({
+            patterns: options.patterns,
+            root: options.root,
+            paths: options.paths,
+            // Absent and undefined are one answer to impactOf: every dependent.
+            depth: options.depth,
+            includeInactive: options.ignoreStatus,
+            includeSpecs: options.includeSpecs,
+            defaultSkips: options.defaultSkips,
+            exclude: options.exclude,
+        });
+    }
+    catch (error) {
+        io.stderr(`spec-guard: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_ERROR;
+    }
+    const answered = { ...report, config: use };
+    io.stdout(options.format === 'json' ? formatImpactJson(answered) : formatImpact(answered));
+    if (report.specFiles.length > 0)
+        return EXIT_OK;
+    if (options.format !== 'json')
+        io.stderr(`spec-guard: no spec files matched ${options.patterns.map((p) => `"${p}"`).join(', ')}`);
+    return options.allowEmpty ? EXIT_OK : EXIT_ERROR;
+}
+/**
+ * `spec-guard cites`: the specs code comments cite, and whether each is still
+ * there and in force. ADR-0017.
+ *
+ * Exit 1 for a ghost, and under `--strict` for a stale citation or a file
+ * whose comments could not all be read; 2 when the answer could not be
+ * trusted - a family whose files match no document, a path outside the root.
+ */
+async function runCites(options, io, use) {
+    let report;
+    try {
+        const paths = await Promise.all(options.paths.map((entry) => resolveQueryPath(entry, options.root)));
+        for (const entry of paths) {
+            if (!entry.exists)
+                throw new CitesError(`"${entry.path}" does not exist, so there are no comments in it to read`);
+        }
+        report = {
+            ...(await findCitations({
+                root: options.root,
+                patterns: options.patterns,
+                // Undefined, as absent, derives the families from the specs.
+                families: options.cites,
+                ...(paths.length === 0 ? {} : { paths: paths.map((entry) => entry.path) }),
+                exclude: options.exclude,
+                defaultSkips: options.defaultSkips,
+                strict: options.strictTargets,
+            })),
+            config: use,
+        };
+    }
+    catch (error) {
+        io.stderr(`spec-guard: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_ERROR;
+    }
+    const written = options.format === 'json'
+        ? formatCitesJson(report)
+        : options.format === 'sarif'
+            ? formatCitesSarif(report, { version: version() })
+            : options.format === 'gitlab'
+                ? formatGitlab(citesAnnotations(report))
+                : options.format === 'github'
+                    ? formatGithub(citesAnnotations(report))
+                    : formatCites(report, {
+                        color: shouldUseColor({ isTTY: io.isTTY }, options.color, io.env),
+                        verbose: false,
+                        ascii: shouldUseAscii(io.env),
+                    });
+    if (written !== '')
+        io.stdout(written);
+    return report.ok ? EXIT_OK : EXIT_FAILED;
+}
 /** Runs the CLI and resolves to the process exit code. */
 export async function main(argv = process.argv.slice(2), io = defaultIO()) {
     let options;
@@ -612,6 +880,14 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
         io.stdout(version());
         return EXIT_OK;
     }
+    // Before any command starts, so a server, a watch session and a proof refuse
+    // a pattern as a run does, rather than each answering with fewer documents.
+    // The configuration's are refused where it is read, naming the file.
+    const patternError = patternListError(options.patterns, specPatternError);
+    if (patternError !== null) {
+        io.stderr(`spec-guard: ${patternError}`);
+        return EXIT_ERROR;
+    }
     // Read after --help and --version, which must work in a project whose
     // package.json is broken, and before anything that runs a rule.
     const commandLine = { ...options, patterns: [...options.patterns] };
@@ -621,8 +897,14 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
     const { use } = configured;
     if (options.command === 'query')
         return runQuery(options, io, use);
+    if (options.command === 'cites')
+        return runCites(options, io, use);
+    if (options.command === 'impact')
+        return runImpact(options, io, use);
     if (options.command === 'mcp')
         return runMcp(options, commandLine, io, use);
+    if (options.command === 'prove')
+        return runProve(options, io, use);
     if (options.watch)
         return runWatchSession(commandLine, io);
     let report;
@@ -639,8 +921,11 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
         return EXIT_ERROR;
     }
     if (report.summary.specs === 0) {
-        if (options.format !== 'human') {
-            io.stdout(options.format === 'sarif' ? formatSarif(report, { version: version() }) : formatJson(report));
+        // A document a script reads is still written, empty, for the script to
+        // read. GitHub's commands have nothing to annotate, and the person reading
+        // the job's log is told why, as a person at a terminal is.
+        if (options.format === 'sarif' || options.format === 'json' || options.format === 'gitlab') {
+            io.stdout(options.format === 'sarif' ? formatSarif(report, { version: version() }) : options.format === 'gitlab' ? formatGitlab([]) : formatJson(report));
         }
         else {
             io.stderr(`spec-guard: no spec files matched ${options.patterns.map((p) => `"${p}"`).join(', ')}`);
@@ -659,6 +944,14 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
     else if (options.format === 'json') {
         io.stdout(formatJson(report));
     }
+    else if (options.format === 'gitlab') {
+        io.stdout(formatGitlab(runAnnotations(report)));
+    }
+    else if (options.format === 'github') {
+        const annotations = formatGithub(runAnnotations(report));
+        if (annotations !== '')
+            io.stdout(annotations);
+    }
     else {
         io.stdout(formatReport(report, {
             color: shouldUseColor({ isTTY: io.isTTY }, options.color, io.env),