@descent-vtt/spec-guard 0.1.0

package/dist/cli.js

@@ -0,0 +1,243 @@
+/**
+ * Command line entrypoint.
+ *
+ * Exit codes are the contract CI depends on:
+ *   0 - every assertion held
+ *   1 - an assertion failed, or a directive was invalid
+ *   2 - spec-guard could not run (bad usage, no spec files, missing engine)
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { formatJson, formatReport, shouldUseAscii, shouldUseColor } from './reporter.js';
+import { DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, runSpecGuard } from './runner.js';
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_ERROR = 2;
+export class UsageError extends Error {
+}
+function version() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../package.json');
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        /* c8 ignore next 2 -- only reachable from a broken install */
+        return '0.0.0';
+    }
+}
+export const HELP = `spec-guard - Executable architecture assertions for Markdown specs & ADRs
+
+Usage
+  spec-guard [patterns...] [options]
+
+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.
+
+Options
+  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)
+  -v, --verbose           Print passing assertions too
+      --fail-fast         Stop at the first failing assertion
+      --json              Emit a machine-readable JSON report
+      --engine <name>     auto | rg | js  (default: auto - ripgrep when available)
+      --strict            Treat a target path that does not exist as a failure
+      --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
+      --color/--no-color  Force colour on or off (NO_COLOR is honoured)
+  -h, --help              Show this help
+      --version           Print the version
+
+Directives
+  <!-- @assert-absence target="src/" symbol="LegacyGateway" -->
+  <!-- @assert-count   target="src/" symbol="SessionManager" expected="1" -->
+  <!-- @assert-present file="SECURITY.md" -->
+
+Exit codes
+  0 all assertions passed   1 an assertion failed   2 spec-guard could not run`;
+const ENGINE_ALIASES = {
+    auto: 'auto',
+    rg: 'ripgrep',
+    ripgrep: 'ripgrep',
+    js: 'javascript',
+    javascript: 'javascript',
+    node: 'javascript',
+};
+function requireValue(name, value) {
+    if (value === undefined || value.startsWith('-')) {
+        throw new UsageError(`Option ${name} requires a value.`);
+    }
+    return value;
+}
+function positiveInteger(name, value) {
+    if (!/^\d+$/.test(value))
+        throw new UsageError(`Option ${name} expects a non-negative integer, got "${value}".`);
+    return Number.parseInt(value, 10);
+}
+/** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
+export function parseArgs(argv, cwd) {
+    const options = {
+        patterns: [],
+        root: cwd,
+        verbose: false,
+        failFast: false,
+        json: false,
+        engine: 'auto',
+        strictTargets: false,
+        includeSpecs: false,
+        allowEmpty: false,
+        maxSnippets: DEFAULT_MAX_SNIPPETS,
+        concurrency: DEFAULT_CONCURRENCY,
+        help: false,
+        version: false,
+    };
+    let onlyPositional = false;
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (onlyPositional || !argument.startsWith('-') || argument === '-') {
+            options.patterns.push(argument);
+            continue;
+        }
+        if (argument === '--') {
+            onlyPositional = true;
+            continue;
+        }
+        const equals = argument.indexOf('=');
+        const name = equals === -1 ? argument : argument.slice(0, equals);
+        const inlineValue = equals === -1 ? undefined : argument.slice(equals + 1);
+        const nextValue = () => {
+            if (inlineValue !== undefined)
+                return requireValue(name, inlineValue);
+            index += 1;
+            return requireValue(name, argv[index]);
+        };
+        switch (name) {
+            case '-h':
+            case '--help':
+                options.help = true;
+                break;
+            case '--version':
+                options.version = true;
+                break;
+            case '-v':
+            case '--verbose':
+                options.verbose = true;
+                break;
+            case '--fail-fast':
+                options.failFast = true;
+                break;
+            case '--json':
+                options.json = true;
+                break;
+            case '--strict':
+                options.strictTargets = true;
+                break;
+            case '--include-specs':
+                options.includeSpecs = true;
+                break;
+            case '--allow-empty':
+                options.allowEmpty = true;
+                break;
+            case '--color':
+                options.color = true;
+                break;
+            case '--no-color':
+                options.color = false;
+                break;
+            case '-r':
+            case '--root':
+                options.root = path.resolve(cwd, nextValue());
+                break;
+            case '--engine': {
+                const value = nextValue().toLowerCase();
+                const engine = ENGINE_ALIASES[value];
+                if (!engine) {
+                    throw new UsageError(`Unknown engine "${value}". Expected auto, rg or js.`);
+                }
+                options.engine = engine;
+                break;
+            }
+            case '--max-snippets':
+                options.maxSnippets = positiveInteger(name, nextValue());
+                break;
+            case '--concurrency':
+                options.concurrency = Math.max(1, positiveInteger(name, nextValue()));
+                break;
+            default:
+                throw new UsageError(`Unknown option "${name}". Run spec-guard --help.`);
+        }
+    }
+    if (options.patterns.length === 0)
+        options.patterns = ['docs/**/*.md'];
+    return options;
+}
+function defaultIO() {
+    return {
+        stdout: (text) => process.stdout.write(`${text}\n`),
+        stderr: (text) => process.stderr.write(`${text}\n`),
+        env: process.env,
+        cwd: process.cwd(),
+        isTTY: Boolean(process.stdout.isTTY),
+    };
+}
+/** Runs the CLI and resolves to the process exit code. */
+export async function main(argv = process.argv.slice(2), io = defaultIO()) {
+    let options;
+    try {
+        options = parseArgs(argv, io.cwd);
+    }
+    catch (error) {
+        io.stderr(error instanceof UsageError ? error.message : String(error));
+        io.stderr('');
+        io.stderr(HELP);
+        return EXIT_ERROR;
+    }
+    if (options.help) {
+        io.stdout(HELP);
+        return EXIT_OK;
+    }
+    if (options.version) {
+        io.stdout(version());
+        return EXIT_OK;
+    }
+    let report;
+    try {
+        report = await runSpecGuard({
+            patterns: options.patterns,
+            root: options.root,
+            engine: options.engine,
+            failFast: options.failFast,
+            strictTargets: options.strictTargets,
+            includeSpecs: options.includeSpecs,
+            concurrency: options.concurrency,
+            maxSnippets: options.maxSnippets,
+        });
+    }
+    catch (error) {
+        io.stderr(`spec-guard: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_ERROR;
+    }
+    if (report.summary.specs === 0) {
+        if (options.json) {
+            io.stdout(formatJson(report));
+        }
+        else {
+            io.stderr(`spec-guard: no spec files matched ${options.patterns.map((p) => `"${p}"`).join(', ')}`);
+        }
+        return options.allowEmpty ? EXIT_OK : EXIT_ERROR;
+    }
+    if (options.json) {
+        io.stdout(formatJson(report));
+    }
+    else {
+        io.stdout(formatReport(report, {
+            color: shouldUseColor({ isTTY: io.isTTY }, options.color, io.env),
+            verbose: options.verbose,
+            ascii: shouldUseAscii(io.env),
+        }, options.maxSnippets));
+    }
+    return report.ok ? EXIT_OK : EXIT_FAILED;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Search engines.
+ *
+ * Primary: native `ripgrep`, consumed as newline-delimited JSON. ripgrep is
+ * multi-threaded, gitignore-aware and binary-skipping, which is why spec-guard
+ * reaches for it before doing anything clever itself.
+ *
+ * Fallback: a pure-JS walker with identical assertion semantics, used when `rg`
+ * is not on PATH (or when `--engine js` is passed). Nothing about spec-guard's
+ * behaviour depends on ripgrep being installed - only its speed does.
+ *
+ * Both engines expose a batch API. Scanning a tree costs the same whether you
+ * look for one symbol or twenty, so assertions that share a target set and
+ * flags are answered by a single pass. Measured on a 2,000 file / 5 MB tree,
+ * eight assertions cost ~280ms as eight ripgrep passes and ~90ms as one.
+ */
+import type { EngineName, MatchLocation, SearchOptions, SearchResult } from './types.js';
+/** Files larger than this are skipped by both engines, keeping them in sync. */
+export declare const MAX_FILE_SIZE: number;
+export interface SearchRequest {
+    /** Absolute root directory. All targets are resolved against it. */
+    root: string;
+    /** Literal string or regular expression source. */
+    symbol: string;
+    /** Existing target paths, relative to root, POSIX separators. */
+    targets: string[];
+    options: SearchOptions;
+}
+export interface Engine {
+    readonly name: EngineName;
+    search(request: SearchRequest): Promise<SearchResult>;
+    /**
+     * Answers several requests that share a root, target list and options.
+     * Optional: `runSearches` falls back to parallel `search` calls.
+     */
+    searchBatch?(requests: SearchRequest[]): Promise<SearchResult[]>;
+}
+export type EnginePreference = 'auto' | 'ripgrep' | 'javascript';
+export declare function escapeRegExp(value: string): string;
+/** Per-pattern accumulator used by both engines. */
+interface Tally {
+    count: number;
+    locations: MatchLocation[];
+}
+/**
+ * True when no two of these literals can ever match overlapping text, which is
+ * exactly when merging them into one ripgrep alternation is safe.
+ *
+ * Two ways an alternation loses a match that separate passes would find:
+ *   containment - ["Primary", "PrimaryButton"] on "PrimaryButton"; and
+ *   dovetailing - ["abc", "cd"] on "abcd", where the scan resumes past "cd".
+ * Rejecting both leaves batching indistinguishable from separate passes.
+ */
+export declare function canBatchLiterals(patterns: readonly string[]): boolean;
+/** Runs requests through the batch API when the engine has one. */
+export declare function runSearches(engine: Engine, requests: SearchRequest[]): Promise<SearchResult[]>;
+export declare function resetRipgrepProbe(): void;
+/** Locates a usable `rg` binary. `SPEC_GUARD_RG` overrides PATH lookup. */
+export declare function findRipgrep(): Promise<string | null>;
+/** Builds the argv for one ripgrep pass over `patterns`. */
+export declare function buildRipgrepArgs(request: SearchRequest, patterns?: readonly string[]): string[];
+/** Builds the matching RegExp shared by the JS engine. */
+export declare function buildJsRegExp(symbol: string, options: SearchOptions): RegExp;
+/** Counts matches in one file and records per-line snippets. */
+export declare function scanContent(content: string, relativePath: string, regexp: RegExp): Tally;
+/** An engine that is guaranteed to implement the batch API. */
+export type BatchEngine = Engine & Required<Pick<Engine, 'searchBatch'>>;
+export declare const javascriptEngine: BatchEngine;
+/** Resolves the engine to use, honouring an explicit preference. */
+export declare function resolveEngine(preference?: EnginePreference): Promise<Engine>;
+export type CachedEngine = Engine & {
+    fallbacks: string[];
+};
+/**
+ * Wraps an engine with a de-duplicating cache plus an automatic fallback to the
+ * JS engine, so a ripgrep hiccup degrades to "slower" instead of "broken".
+ */
+export declare function createCachedEngine(engine: Engine): CachedEngine;
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzF,gFAAgF;AAChF,eAAO,MAAM,aAAa,QAAmB,CAAC;AAQ9C,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACtD;;;OAGG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAClE;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;AAEjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAWD,oDAAoD;AACpD,UAAU,KAAK;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAWrE;AAqBD,mEAAmE;AACnE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAMpG;AAOD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAepD;AAeD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,GAAE,SAAS,MAAM,EAAqB,GAAG,MAAM,EAAE,CAWjH;AA4ID,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAS5E;AA6GD,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CA8CxF;AAID,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAEzE,eAAO,MAAM,gBAAgB,EAAE,WAAoC,CAAC;AA8CpE,oEAAoE;AACpE,wBAAsB,aAAa,CAAC,UAAU,GAAE,gBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU1F;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAgE/D"}