@descent-vtt/spec-guard 0.1.0 → 0.3.0

package/dist/comments.js

@@ -0,0 +1,241 @@
+/**
+ * Comment classification.
+ *
+ * A documented codebase defeats a plain text search in the most ironic way
+ * available: the comment recording that a symbol was deleted is itself a match
+ * for that symbol. `@assert-absence symbol="LegacyThing"` then fails on
+ *
+ *   // LegacyThing was removed in ADR-398
+ *
+ * which is the sentence proving the assertion true. So matches are classified
+ * and, by default, those inside comments do not count.
+ *
+ * The scanner tracks strings as well as comments, and it has to: a `//` inside
+ * a string literal is not a comment, and misreading one is the dangerous
+ * direction. Consider
+ *
+ *   const url = "http://example.com"; const x = LegacyThing;
+ *
+ * Treating `//` in that URL as a comment start would hide a real use of
+ * LegacyThing and turn a violation into a silent pass. Every uncertainty here
+ * therefore resolves the same way: **when in doubt, it is code**. A match
+ * wrongly kept is a visible failure someone can argue with; a match wrongly
+ * dropped is a lie.
+ *
+ * Languages it does not recognise get no comment ranges at all, so their
+ * matches all count - and the result says so rather than implying the file was
+ * understood.
+ */
+import path from 'node:path';
+const QUOTES = [
+    { open: '"', close: '"', escape: true },
+    { open: "'", close: "'", escape: true },
+];
+const C_LIKE = {
+    name: 'c-like',
+    line: ['//'],
+    block: [['/*', '*/']],
+    nested: false,
+    strings: QUOTES,
+};
+const JS_LIKE = {
+    ...C_LIKE,
+    name: 'javascript',
+    strings: [...QUOTES, { open: '`', close: '`', escape: true }],
+};
+const C_SHARP = {
+    ...C_LIKE,
+    name: 'c#',
+    // Verbatim strings come first so @" wins over ".
+    strings: [{ open: '@"', close: '"', escape: false }, ...QUOTES],
+};
+const RUST = {
+    name: 'rust',
+    line: ['//'],
+    block: [['/*', '*/']],
+    // Rust block comments nest, so /* /* */ */ is one comment, not one and a half.
+    nested: true,
+    strings: [
+        { open: 'r#"', close: '"#', escape: false },
+        { open: 'r"', close: '"', escape: false },
+        ...QUOTES,
+    ],
+};
+const GO = {
+    ...C_LIKE,
+    name: 'go',
+    strings: [...QUOTES, { open: '`', close: '`', escape: false }],
+};
+const HASH = {
+    name: 'hash',
+    line: ['#'],
+    block: [],
+    nested: false,
+    // Triple quotes first: a Python docstring is a string, not a comment, and
+    // treating it as code is the conservative reading.
+    strings: [
+        { open: '"""', close: '"""', escape: true },
+        { open: "'''", close: "'''", escape: true },
+        ...QUOTES,
+    ],
+};
+const SQL_LIKE = {
+    name: 'sql-like',
+    line: ['--'],
+    block: [['/*', '*/']],
+    nested: false,
+    strings: QUOTES,
+};
+const MARKUP = {
+    name: 'markup',
+    line: [],
+    block: [['<!--', '-->']],
+    nested: false,
+    strings: [],
+};
+/**
+ * Formats with no comments at all.
+ *
+ * Worth naming rather than leaving unknown: "this file has no comments" is
+ * something we know about JSON, and saying "I could not read it" instead would
+ * attach a caveat to every match in a package.json. Dialects that do allow
+ * comments in practice - tsconfig.json and its `//` lines - simply have them
+ * counted as code, which is the direction that fails loudly.
+ */
+const NO_COMMENTS = {
+    name: 'none',
+    line: [],
+    block: [],
+    nested: false,
+    strings: [],
+};
+/** Extension to comment syntax. Anything absent is left unclassified. */
+const BY_EXTENSION = new Map([
+    ...['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx'].map((extension) => [extension, JS_LIKE]),
+    ...['.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.java', '.kt', '.kts', '.scala', '.swift', '.dart', '.php', '.m', '.mm', '.zig'].map((extension) => [extension, C_LIKE]),
+    ...['.cs', '.csx'].map((extension) => [extension, C_SHARP]),
+    ...['.rs'].map((extension) => [extension, RUST]),
+    ...['.go'].map((extension) => [extension, GO]),
+    ...['.py', '.pyi', '.rb', '.sh', '.bash', '.zsh', '.yaml', '.yml', '.toml', '.tf', '.pl', '.r'].map((extension) => [extension, HASH]),
+    ...['.sql', '.lua', '.hs', '.elm'].map((extension) => [extension, SQL_LIKE]),
+    ...['.html', '.htm', '.xml', '.svg', '.vue', '.svelte', '.md', '.markdown'].map((extension) => [extension, MARKUP]),
+    // .jsonc is named for the comments it allows, so it gets the C-style reader.
+    ...['.jsonc'].map((extension) => [extension, C_LIKE]),
+    ...['.json', '.txt', '.csv', '.tsv', '.lock', '.log'].map((extension) => [extension, NO_COMMENTS]),
+]);
+/** The comment syntax for a path, or null when the language is unknown. */
+export function syntaxFor(filePath) {
+    return BY_EXTENSION.get(path.extname(filePath).toLowerCase()) ?? null;
+}
+/** Where the literal opened at `at` ends, or the end of the file. */
+function endOfString(source, at, rule) {
+    let index = at + rule.open.length;
+    while (index < source.length) {
+        if (rule.escape && source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source.startsWith(rule.close, index))
+            return index + rule.close.length;
+        index += 1;
+    }
+    return source.length;
+}
+/** Where the block comment opened at `at` ends, or the end of the file. */
+function endOfBlock(source, at, pair, nested) {
+    const [open, close] = pair;
+    let index = at + open.length;
+    let depth = 1;
+    while (index < source.length && depth > 0) {
+        if (nested && source.startsWith(open, index)) {
+            depth += 1;
+            index += open.length;
+            continue;
+        }
+        if (source.startsWith(close, index)) {
+            depth -= 1;
+            index += close.length;
+            continue;
+        }
+        index += 1;
+    }
+    return index;
+}
+/**
+ * Finds every comment in the source.
+ *
+ * One pass, tracking strings so that comment markers inside them are ignored.
+ * An unterminated comment or string runs to the end of the file, which matches
+ * how a compiler would read it.
+ *
+ * The scan is written so that it cannot stand still: whatever the branches
+ * below decide, the loop advances by at least one character. That guarantee is
+ * the difference between a wrong answer and a hang, and this loop appends as it
+ * goes - standing still here would not spin, it would eat memory until the
+ * process died, on somebody's file, in somebody's CI.
+ */
+export function commentRanges(source, syntax) {
+    const ranges = [];
+    let index = 0;
+    while (index < source.length) {
+        const start = index;
+        const startsWith = (token) => source.startsWith(token, start);
+        // First match wins, in this order: a literal hides comment markers inside
+        // it, and a line comment hides a block opener on the same line. Each lookup
+        // sits in the branch that needs it, so none of them runs speculatively.
+        const stringRule = syntax.strings.find((rule) => startsWith(rule.open));
+        if (stringRule) {
+            index = endOfString(source, start, stringRule);
+        }
+        else {
+            const lineToken = syntax.line.find((token) => startsWith(token));
+            if (lineToken !== undefined) {
+                const newline = source.indexOf('\n', start);
+                index = newline === -1 ? source.length : newline;
+                ranges.push([start, index]);
+            }
+            else {
+                const blockPair = syntax.block.find(([open]) => startsWith(open));
+                if (blockPair) {
+                    index = endOfBlock(source, start, blockPair, syntax.nested);
+                    ranges.push([start, index]);
+                }
+            }
+        }
+        // The single advance point, and the only place termination depends on.
+        if (index <= start)
+            index = start + 1;
+    }
+    return ranges;
+}
+const UNCLASSIFIED = {
+    classified: false,
+    syntax: null,
+    isComment: () => false,
+};
+export function createCommentMask(source, filePath) {
+    const syntax = syntaxFor(filePath);
+    if (!syntax)
+        return UNCLASSIFIED;
+    const ranges = commentRanges(source, syntax);
+    return {
+        classified: true,
+        syntax: syntax.name,
+        isComment(offset) {
+            let low = 0;
+            let high = ranges.length - 1;
+            while (low <= high) {
+                const mid = (low + high) >> 1;
+                const [start, end] = ranges[mid];
+                if (offset < start)
+                    high = mid - 1;
+                else if (offset >= end)
+                    low = mid + 1;
+                else
+                    return true;
+            }
+            return false;
+        },
+    };
+}
+//# sourceMappingURL=comments.js.map

package/dist/comments.js.map

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

package/dist/engine.d.ts

@@ -14,6 +14,7 @@
  * 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 CommentMask } from './comments.js';
 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;
@@ -37,10 +38,27 @@ export interface Engine {
 }
 export type EnginePreference = 'auto' | 'ripgrep' | 'javascript';
 export declare function escapeRegExp(value: string): string;
+/**
+ * Converts ripgrep's byte column into a character column.
+ *
+ * ripgrep counts bytes; the scanner counts characters, and so does every editor
+ * that a reader will paste the location into. On an ASCII line the two agree,
+ * which is why the difference went unnoticed - it only appears once a line
+ * holds a non-ASCII character before the match, and then the two engines report
+ * different columns for the same match.
+ */
+export declare function byteColumnToCharacter(line: string, byteOffset: number): number;
+/**
+ * Orders matches by path, then by line. ripgrep searches in parallel and emits
+ * files in no fixed order, so this is what makes snippet output stable.
+ */
+export declare function sortLocations(locations: MatchLocation[]): MatchLocation[];
 /** Per-pattern accumulator used by both engines. */
 interface Tally {
     count: number;
     locations: MatchLocation[];
+    /** Matches skipped because they were inside a comment. */
+    commentCount: number;
 }
 /**
  * True when no two of these literals can ever match overlapping text, which is
@@ -59,13 +77,90 @@ export declare function resetRipgrepProbe(): void;
 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[];
+/**
+ * Whether a set of patterns may share one ripgrep pass.
+ *
+ * Kept separate from the engine so the decision can be asserted directly: from
+ * the outside a correct batch and a correct set of separate passes are
+ * indistinguishable by design, which makes this the only place the rule is
+ * observable.
+ */
+export declare function shouldBatchPatterns(patterns: readonly string[], options: SearchOptions): boolean;
+export interface RipgrepSink {
+    /** Feeds one line of ripgrep --json output. */
+    line(text: string): void;
+    readonly tallies: Map<string, Tally>;
+    readonly failure: Error | null;
+}
+/**
+ * Parses ripgrep's newline-delimited JSON into per-pattern tallies.
+ *
+ * This is deliberately pure and separate from the subprocess: every interesting
+ * case here - a base64 path, a match with no submatches, an excluded file, an
+ * unattributable match - is trivial to exercise as data and nearly impossible
+ * to provoke from a real ripgrep on demand.
+ */
+export declare function createRipgrepSink(request: SearchRequest, patterns: readonly string[]): RipgrepSink;
 /** Builds the matching RegExp shared by the JS engine. */
 export declare function buildJsRegExp(symbol: string, options: SearchOptions): RegExp;
+interface CandidateFile {
+    absolutePath: string;
+    relativePath: string;
+}
+export interface Enumeration {
+    files: CandidateFile[];
+    /** True when the walk stopped early because the budget was reached. */
+    exceeded: boolean;
+    bytes: number;
+}
+export interface EnumerationBudget {
+    maxFiles: number;
+    maxBytes: number;
+}
+/**
+ * Lists the files a request would search, sorted by relative path.
+ *
+ * With a budget, the walk abandons as soon as the tree proves bigger than the
+ * budget allows. That makes it usable as a cheap probe: enumeration is stat-only
+ * work, so finding out a tree is "too big" costs a bounded number of stats
+ * rather than a full traversal.
+ */
+export declare function enumerateCandidates(request: SearchRequest, budget?: EnumerationBudget): Promise<Enumeration>;
 /** Counts matches in one file and records per-line snippets. */
-export declare function scanContent(content: string, relativePath: string, regexp: RegExp): Tally;
+export declare function scanContent(content: string, relativePath: string, regexp: RegExp, 
+/**
+ * Resolved lazily, and only once the file has produced a match. Classifying
+ * every file in scope would mean a comment scan of the whole tree; this way
+ * the cost is proportional to matches, which for an architecture assertion is
+ * usually zero.
+ */
+getMask?: () => CommentMask): Tally;
 /** An engine that is guaranteed to implement the batch API. */
-export type BatchEngine = Engine & Required<Pick<Engine, 'searchBatch'>>;
+export type BatchEngine = Engine & Required<Pick<Engine, 'searchBatch'>> & {
+    /** Scans a file list that the caller already enumerated. */
+    searchFiles(files: readonly CandidateFile[], requests: SearchRequest[]): Promise<SearchResult[]>;
+};
 export declare const javascriptEngine: BatchEngine;
+/**
+ * How much scanning the JavaScript engine may do before ripgrep is worth a
+ * process spawn.
+ *
+ * Measured with scripts/bench-engines.mjs. ripgrep's cost is dominated by
+ * process startup and is nearly flat in tree size; the JavaScript scanner grows
+ * linearly. The crossover is therefore wherever a spawn costs, and that differs
+ * by an order of magnitude between platforms:
+ *
+ *   Windows 11, Node 24, rg 15   spawn floor ~130ms   crossover ~575 files
+ *   Linux (container), Node 22, rg 13   spawn floor ~15ms   crossover ~25 files
+ *
+ * The budget is set just below each crossover, so choosing JavaScript is never
+ * the slower option by more than a few milliseconds, while a small tree on
+ * Windows avoids a spawn that would cost ten times the whole search.
+ */
+export declare const SMALL_TREE_BUDGET: EnumerationBudget;
+/** Exported so the code list can be asserted; EACCES and friends are not
+ * reproducible on demand from a real spawn. */
+export declare function isMissingBinary(error: unknown): boolean;
 /** Resolves the engine to use, honouring an explicit preference. */
 export declare function resolveEngine(preference?: EnginePreference): Promise<Engine>;
 export type CachedEngine = Engine & {

package/dist/engine.d.ts.map

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