@descent-vtt/spec-guard 0.2.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
@@ -109,7 +127,14 @@ export interface EnumerationBudget {
  */
 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'>> & {
     /** Scans a file list that the caller already enumerated. */
@@ -133,6 +158,9 @@ export declare const javascriptEngine: BatchEngine;
  * 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":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -17,7 +17,8 @@
 import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { createGlobMatcher, toPosix, walkFiles } from './glob.js';
+import { createCommentMask } from './comments.js';
+import { createExcludeMatcher, createGlobMatcher, toPosix, walkFiles } from './glob.js';
 /** Files larger than this are skipped by both engines, keeping them in sync. */
 export const MAX_FILE_SIZE = 20 * 1024 * 1024;
 /** Hard cap on collected locations; the reporter only ever shows a handful. */
@@ -31,11 +32,31 @@ function truncate(value) {
     const trimmed = value.replace(/\r?\n$/, '');
     return trimmed.length > MAX_SNIPPET_LENGTH ? `${trimmed.slice(0, MAX_SNIPPET_LENGTH)}…` : trimmed;
 }
-function sortLocations(locations) {
+/**
+ * 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 function byteColumnToCharacter(line, byteOffset) {
+    // One byte per character, so the offset is already a character count. This
+    // also covers the case where ripgrep gave us no line text to measure.
+    if (line.length === Buffer.byteLength(line))
+        return byteOffset + 1;
+    return Buffer.from(line, 'utf8').subarray(0, byteOffset).toString('utf8').length + 1;
+}
+/**
+ * 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 function sortLocations(locations) {
     return locations.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
 }
 function emptyTally() {
-    return { count: 0, locations: [] };
+    return { count: 0, locations: [], commentCount: 0 };
 }
 /**
  * True when no two of these literals can ever match overlapping text, which is
@@ -75,6 +96,8 @@ function sharesOnePass(requests) {
         request.options.ignoreCase === first.options.ignoreCase &&
         request.options.globs.length === first.options.globs.length &&
         request.options.globs.every((glob, index) => glob === first.options.globs[index]) &&
+        request.options.excludeGlobs.length === first.options.excludeGlobs.length &&
+        request.options.excludeGlobs.every((glob, index) => glob === first.options.excludeGlobs[index]) &&
         request.options.excludeFiles === first.options.excludeFiles);
 }
 /** Runs requests through the batch API when the engine has one. */
@@ -131,6 +154,10 @@ export function buildRipgrepArgs(request, patterns = [request.symbol]) {
         args.push('--ignore-case');
     for (const glob of options.globs)
         args.push('--glob', glob);
+    // ripgrep reads a leading "!" as an exclusion, with gitignore semantics that
+    // createExcludeMatcher mirrors for the JavaScript engine.
+    for (const glob of options.excludeGlobs)
+        args.push('--glob', `!${glob}`);
     for (const pattern of patterns)
         args.push('--regexp', pattern);
     args.push('--');
@@ -147,6 +174,10 @@ class RipgrepEngine {
         this.binary = binary;
     }
     async search(request) {
+        if (request.options.ignoreComments) {
+            const [result] = await this.commentAware(request, [request.symbol], [request]);
+            return result;
+        }
         const tallies = await this.run(request, [request.symbol]);
         return this.toResult(tallies.get(request.symbol));
     }
@@ -155,6 +186,15 @@ class RipgrepEngine {
         if (!first)
             return [];
         const patterns = [...new Set(requests.map((request) => request.symbol))];
+        // Comment-aware counting needs the file's text, which ripgrep's match
+        // stream does not carry. Rather than re-implement classification twice,
+        // ripgrep is used for what it is unmatched at - telling us which handful of
+        // files out of thousands contain the symbol at all - and those files are
+        // then counted by the scanner, which already knows about comments. Both
+        // engines therefore produce comment-aware counts through one code path.
+        if (first.options.ignoreComments) {
+            return this.commentAware(first, patterns, requests);
+        }
         if (!shouldBatchPatterns(patterns, first.options)) {
             return Promise.all(requests.map((request) => this.search(request)));
         }
@@ -168,9 +208,63 @@ class RipgrepEngine {
             return Promise.all(requests.map((request) => this.search(request)));
         }
     }
+    /**
+     * Two-phase search, used whenever comments must be classified.
+     *
+     * The result still names ripgrep: it did the searching, and classification is
+     * a post-step both engines share rather than a different engine.
+     */
+    async commentAware(request, patterns, requests) {
+        const files = await this.filesWithMatches(request, patterns);
+        const results = await javascriptEngine.searchFiles(files, requests);
+        return results.map((result) => ({ ...result, engine: this.name }));
+    }
+    /** Phase one: which files contain any of these patterns at all. */
+    filesWithMatches(request, patterns) {
+        return new Promise((resolve, reject) => {
+            const args = buildRipgrepArgs(request, patterns).map((argument) => argument === '--json' ? '--files-with-matches' : argument);
+            const child = spawn(this.binary, args, {
+                cwd: request.root,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => (stdout += chunk));
+            child.stderr.setEncoding('utf8');
+            child.stderr.on('data', (chunk) => (stderr += chunk));
+            child.once('error', reject);
+            child.once('close', (code) => {
+                // 0 = matches, 1 = none, anything else is a real failure.
+                if (code !== 0 && code !== 1) {
+                    reject(new Error(`ripgrep exited with code ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
+                    return;
+                }
+                const files = [];
+                for (const line of stdout.split('\n')) {
+                    const trimmed = line.trim();
+                    if (trimmed.length === 0)
+                        continue;
+                    const absolutePath = path.resolve(request.root, trimmed);
+                    if (request.options.excludeFiles.has(absolutePath))
+                        continue;
+                    files.push({ absolutePath, relativePath: toPosix(path.relative(request.root, absolutePath)) });
+                }
+                files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+                resolve(files);
+            });
+        });
+    }
     toResult(tally) {
         const resolved = tally ?? emptyTally();
-        return { count: resolved.count, matches: sortLocations(resolved.locations), engine: this.name };
+        return {
+            count: resolved.count,
+            commentMatches: resolved.commentCount,
+            unclassifiedFiles: 0,
+            matches: sortLocations(resolved.locations),
+            engine: this.name,
+        };
     }
     /** One ripgrep pass; returns a tally per pattern. */
     run(request, patterns) {
@@ -266,7 +360,8 @@ export function createRipgrepSink(request, patterns) {
                 return;
             const file = toPosix(path.relative(request.root, absolute));
             const lineNumber = data.line_number ?? 0;
-            const text_ = truncate(decodeText(data.lines));
+            const lineText = decodeText(data.lines);
+            const text_ = truncate(lineText);
             for (const submatch of submatches) {
                 // With --fixed-strings and no --ignore-case the matched text is the
                 // pattern verbatim, which is what makes attribution exact.
@@ -282,7 +377,13 @@ export function createRipgrepSink(request, patterns) {
                     last.count += 1;
                 }
                 else if (tally.locations.length < MAX_COLLECTED_MATCHES) {
-                    tally.locations.push({ file, line: lineNumber, column: (submatch.start ?? 0) + 1, text: text_, count: 1 });
+                    tally.locations.push({
+                        file,
+                        line: lineNumber,
+                        column: byteColumnToCharacter(lineText, submatch.start ?? 0),
+                        text: text_,
+                        count: 1,
+                    });
                 }
             }
         },
@@ -338,6 +439,7 @@ class JavaScriptEngine {
         const concurrency = Math.min(16, Math.max(1, files.length));
         let cursor = 0;
         const perFile = new Map();
+        let unclassifiedFiles = 0;
         const worker = async () => {
             while (cursor < files.length) {
                 const file = files[cursor++];
@@ -348,10 +450,19 @@ class JavaScriptEngine {
                 if (!buffer || isProbablyBinary(buffer))
                     continue;
                 const content = buffer.toString('utf8');
+                let mask;
+                const getMask = first.options.ignoreComments
+                    ? () => (mask ??= createCommentMask(content, file.relativePath))
+                    : undefined;
                 const scanned = new Map();
                 for (const [pattern, regexp] of regexps) {
-                    scanned.set(pattern, scanContent(content, file.relativePath, regexp));
+                    scanned.set(pattern, scanContent(content, file.relativePath, regexp, getMask));
                 }
+                // A mask exists only if some pattern matched, since that is the only
+                // thing that calls getMask - so reaching here already means this file
+                // matched and its language was not understood.
+                if (mask && !mask.classified)
+                    unclassifiedFiles += 1;
                 perFile.set(file.relativePath, scanned);
             }
         };
@@ -364,6 +475,7 @@ class JavaScriptEngine {
             for (const [pattern, tally] of scanned) {
                 const total = tallies.get(pattern);
                 total.count += tally.count;
+                total.commentCount += tally.commentCount;
                 for (const location of tally.locations) {
                     if (total.locations.length < MAX_COLLECTED_MATCHES)
                         total.locations.push(location);
@@ -372,7 +484,13 @@ class JavaScriptEngine {
         }
         return requests.map((request) => {
             const tally = tallies.get(request.symbol) ?? emptyTally();
-            return { count: tally.count, matches: tally.locations, engine: this.name };
+            return {
+                count: tally.count,
+                commentMatches: tally.commentCount,
+                unclassifiedFiles,
+                matches: tally.locations,
+                engine: this.name,
+            };
         });
     }
     /** Every file a request should look at, sorted by relative path. */
@@ -390,6 +508,8 @@ class JavaScriptEngine {
  */
 export async function enumerateCandidates(request, budget) {
     const matcher = createGlobMatcher(request.options.globs);
+    const excluded = createExcludeMatcher(request.options.excludeGlobs);
+    const admits = (relativePath) => matcher(relativePath) && !excluded(relativePath);
     const found = new Map();
     let bytes = 0;
     let exceeded = false;
@@ -409,7 +529,7 @@ export async function enumerateCandidates(request, budget) {
             continue;
         if (stats.isFile()) {
             const relativePath = toPosix(path.relative(request.root, absoluteTarget));
-            if (stats.size <= MAX_FILE_SIZE && matcher(relativePath)) {
+            if (stats.size <= MAX_FILE_SIZE && admits(relativePath)) {
                 if (!admit(absoluteTarget, relativePath, stats.size))
                     break outer;
             }
@@ -419,7 +539,7 @@ export async function enumerateCandidates(request, budget) {
             if (file.size > MAX_FILE_SIZE)
                 continue;
             const relativePath = toPosix(path.relative(request.root, file.absolutePath));
-            if (!matcher(relativePath))
+            if (!admits(relativePath))
                 continue;
             if (!admit(file.absolutePath, relativePath, file.size))
                 break outer;
@@ -431,9 +551,17 @@ export async function enumerateCandidates(request, budget) {
     return { files, exceeded, bytes };
 }
 /** Counts matches in one file and records per-line snippets. */
-export function scanContent(content, relativePath, regexp) {
+export function scanContent(content, relativePath, 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) {
     regexp.lastIndex = 0;
     let count = 0;
+    let commentCount = 0;
     const byLine = new Map();
     // Lazily built line index: only paid for when the file actually matches.
     let lineStarts = null;
@@ -458,6 +586,12 @@ export function scanContent(content, relativePath, regexp) {
     };
     let match;
     while ((match = regexp.exec(content)) !== null) {
+        if (getMask?.().isComment(match.index)) {
+            commentCount += 1;
+            if (match[0].length === 0)
+                regexp.lastIndex += 1;
+            continue;
+        }
         count += 1;
         const { line, column } = lineOf(match.index);
         const existing = byLine.get(line);
@@ -478,7 +612,11 @@ export function scanContent(content, relativePath, regexp) {
         if (match[0].length === 0)
             regexp.lastIndex += 1;
     }
-    return { count, locations: [...byLine.values()].sort((a, b) => a.line - b.line) };
+    // No sort: exec scans forward, so lines are discovered in increasing order and
+    // a Map preserves insertion order. Sorting here was dead code - mutation
+    // testing found it by reporting that neither reversing nor removing the
+    // comparator changed any result.
+    return { count, locations: [...byLine.values()], commentCount };
 }
 export const javascriptEngine = new JavaScriptEngine();
 /**
@@ -500,7 +638,9 @@ export const javascriptEngine = new JavaScriptEngine();
 export const SMALL_TREE_BUDGET = process.platform === 'win32' ? { maxFiles: 512, maxBytes: 1024 * 1024 } : { maxFiles: 32, maxBytes: 64 * 1024 };
 /** Spawn failures that mean "this binary is not installed", not "search failed". */
 const MISSING_BINARY_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EINVAL', 'UNKNOWN']);
-function isMissingBinary(error) {
+/** Exported so the code list can be asserted; EACCES and friends are not
+ * reproducible on demand from a real spawn. */
+export function isMissingBinary(error) {
     const code = error?.code;
     return typeof code === 'string' && MISSING_BINARY_CODES.has(code);
 }
@@ -528,6 +668,7 @@ function enumerationKey(request) {
         request.root,
         request.targets,
         request.options.globs,
+        request.options.excludeGlobs,
         excludeSetId(request.options.excludeFiles),
     ]);
 }
@@ -614,6 +755,7 @@ export function createCachedEngine(engine) {
         request.options.word,
         request.options.ignoreCase,
         request.options.globs,
+        request.options.excludeGlobs,
         [...request.options.excludeFiles].sort(),
     ]);
     const recordFallback = (error) => {