@descent-vtt/spec-guard 0.7.0 → 0.9.0

package/dist/config.js

@@ -0,0 +1,165 @@
+/**
+ * The options a project keeps in its `package.json`, under `"specGuard"`.
+ *
+ * Validated from a value, never read from a file: the command line reads the
+ * file, and every malformed option can then be tested on a plain object. The
+ * keys are the options that are a project's policy - which specs, and how
+ * strictly to hold them - and nothing that describes one invocation. See
+ * ADR-0014.
+ */
+/** The name the options sit under in `package.json`. */
+export const CONFIG_KEY = 'specGuard';
+/** Every key, in the order the documentation lists them. */
+export const CONFIG_KEYS = [
+    'specs',
+    'engine',
+    'strict',
+    'allowMissingTargets',
+    'allowEmptyScope',
+    'ignoreStatus',
+    'includeSpecs',
+    'defaultSkips',
+    'maxSnippets',
+    'concurrency',
+];
+/**
+ * Options that exist on the command line and are refused here by name.
+ *
+ * Each describes one invocation rather than a project. `"format": "sarif"`
+ * would make every developer's local run print SARIF, and `root` is where the
+ * configuration was found in the first place.
+ */
+export const INVOCATION_OPTIONS = new Set([
+    'root',
+    'format',
+    'json',
+    'verbose',
+    'color',
+    'failFast',
+    'printBaseline',
+    'allowEmpty',
+    'watch',
+]);
+/** A configuration that cannot be used, with the words to say why. */
+export class ConfigError extends Error {
+}
+const ENGINE_ALIASES = {
+    auto: 'auto',
+    rg: 'ripgrep',
+    ripgrep: 'ripgrep',
+    js: 'javascript',
+    javascript: 'javascript',
+    node: 'javascript',
+};
+/**
+ * The engine a name asks for, whether the name came from a flag or a file.
+ *
+ * One function, so `--engine rgg` and `"engine": "rgg"` fail with the same
+ * words. Case is ignored, as the flag always has.
+ */
+export function engineNamed(name) {
+    const engine = ENGINE_ALIASES[name.toLowerCase()];
+    if (engine === undefined)
+        throw new ConfigError(`Unknown engine "${name}". Expected auto, rg or js.`);
+    return engine;
+}
+/** A value as a message names it: `"yes"`, `3`, `null`, an array, an object. */
+function describe(value) {
+    if (Array.isArray(value))
+        return 'an array';
+    if (value !== null && typeof value === 'object')
+        return 'an object';
+    return JSON.stringify(value);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Checks one key's value, or says what is wrong with it.
+ *
+ * A string is not a boolean and a number in a string is not a number. JSON has
+ * both types, and accepting `"true"` would be a second grammar for one file.
+ */
+function checkValue(key, value) {
+    switch (key) {
+        case 'specs':
+            return Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === 'string' && entry.trim() !== '')
+                ? null
+                : `must be a non-empty list of spec globs, got ${describe(value)}`;
+        case 'engine':
+            return typeof value === 'string' ? null : `must be a string, got ${describe(value)}`;
+        case 'maxSnippets':
+            return Number.isInteger(value) && value >= 0 ? null : `must be an integer, 0 or more, got ${describe(value)}`;
+        case 'concurrency':
+            return Number.isInteger(value) && value >= 1 ? null : `must be an integer, 1 or more, got ${describe(value)}`;
+        default:
+            return typeof value === 'boolean' ? null : `must be true or false, got ${describe(value)}`;
+    }
+}
+/**
+ * The configuration in a root's `package.json`, read by whoever is asking.
+ *
+ * The reader is a parameter because this module reads nothing itself: the
+ * command line passes the filesystem, and a watch session passes the door that
+ * records what it read, so an edit to `package.json` reaches the session like
+ * an edit to any other file. A file that is not there - or a root that is not a
+ * directory - is no configuration. A file that is there and cannot be read is
+ * an error, because nobody can tell what it would have said.
+ */
+export async function loadConfig(root, read) {
+    // Joined by hand rather than with node:path, which would be this module's
+    // only import: a root with either separator at its end is still one root.
+    const file = `${root.replace(/[\\/]+$/, '')}/package.json`;
+    let text;
+    try {
+        text = await read(file);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return {};
+        throw new ConfigError(`package.json could not be read (${error.message}), so its "${CONFIG_KEY}" options cannot be read.`);
+    }
+    return parseConfig(text);
+}
+/**
+ * The configuration in a `package.json`'s text, or none.
+ *
+ * A `package.json` with no `"specGuard"` is no configuration rather than a
+ * mistake. Anything else that cannot be used throws a `ConfigError` naming the
+ * file and the key, so a run never starts under options nobody meant.
+ */
+export function parseConfig(text, file = 'package.json') {
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${file} is not valid JSON (${error.message}), so its "${CONFIG_KEY}" options cannot be read.`);
+    }
+    const options = isObject(manifest) ? manifest[CONFIG_KEY] : undefined;
+    if (options === undefined)
+        return {};
+    if (!isObject(options))
+        throw new ConfigError(`${file}: "${CONFIG_KEY}" must be an object, got ${describe(options)}.`);
+    const config = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (INVOCATION_OPTIONS.has(key)) {
+            throw new ConfigError(`${file}: "${CONFIG_KEY}.${key}" is chosen on the command line, not in ${file}.`);
+        }
+        if (!CONFIG_KEYS.includes(key)) {
+            throw new ConfigError(`${file}: unknown option "${key}" in "${CONFIG_KEY}". Options are ${CONFIG_KEYS.join(', ')}.`);
+        }
+        const issue = checkValue(key, value);
+        if (issue !== null)
+            throw new ConfigError(`${file}: "${CONFIG_KEY}.${key}" ${issue}.`);
+        try {
+            config[key] = key === 'engine' ? engineNamed(value) : value;
+        }
+        catch (error) {
+            throw new ConfigError(`${file}: "${CONFIG_KEY}.${key}": ${error.message}`);
+        }
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/engine.d.ts

@@ -19,7 +19,8 @@
  * flags are answered by a single pass.
  */
 import { type CommentMask } from './comments.js';
-import { type DirectoryReader } from './glob.js';
+import { type Io } from './io.js';
+import { type Memo } from './memo.js';
 import { type SkippedPath } from './scope.js';
 import type { EngineName, MatchLocation, SearchOptions, SearchResult } from './types.js';
 /** Files larger than this are skipped by both engines, keeping them in sync. */
@@ -222,13 +223,13 @@ export declare const ANY_FILE_PROBE: EnumerationBudget;
  */
 export declare function enumerateCandidates(request: WalkRequest, budget?: EnumerationBudget, 
 /**
- * Directory reader, forwarded to the walk. Exists for the same reason
- * `walkFiles` takes one: the interesting behaviour here is what the
- * enumeration does with a directory it *cannot* read, and there is no
- * portable way to create one - Windows has no chmod, and a permission bit set
- * by a test is a permission bit a failed test leaves behind.
+ * The door the enumeration reads through, forwarded to the walk. Injectable
+ * for the same reason `walkFiles` takes one: the interesting behaviour here
+ * is what the enumeration does with a directory it *cannot* read, and there
+ * is no portable way to create one - Windows has no chmod, and a permission
+ * bit set by a test is a permission bit a failed test leaves behind.
  */
-readDirectory?: DirectoryReader): Promise<Enumeration>;
+io?: Io): Promise<Enumeration>;
 /** Counts matches in one file and records per-line snippets. */
 export declare function scanContent(content: string, relativePath: string, regexp: RegExp, 
 /**
@@ -243,6 +244,15 @@ export type BatchEngine = Engine & Required<Pick<Engine, 'searchBatch'>> & {
     /** Scans a file list that the caller already enumerated. */
     searchFiles(files: readonly CandidateFile[], requests: SearchRequest[], unreadable?: readonly string[], skipped?: readonly SkippedPath[]): Promise<SearchResult[]>;
 };
+/**
+ * A scanner that reads through the given door, and remembers its scans in the
+ * given memo.
+ *
+ * One per watch session rule, so the session sees what each rule read
+ * (ADR-0014). A plain run shares the one below, which reads the filesystem and
+ * remembers nothing.
+ */
+export declare function createJavaScriptEngine(io?: Io, memo?: Memo): BatchEngine;
 export declare const javascriptEngine: BatchEngine;
 /**
  * How much scanning the JavaScript engine may do before ripgrep is worth a
@@ -283,7 +293,11 @@ export type CachedEngine = Engine & Required<Pick<Engine, 'searchBatch'>> & {
 /**
  * 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".
+ *
+ * The fallback is a parameter because a watch session's scanner reads through a
+ * door of its own, and falling back to the shared one would read past it.
+ * Nothing falls back from the fallback: its failure is the run's failure.
  */
-export declare function createCachedEngine(engine: Engine): CachedEngine;
+export declare function createCachedEngine(engine: Engine, fallback?: BatchEngine): CachedEngine;
 export {};
 //# sourceMappingURL=engine.d.ts.map

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

@@ -19,10 +19,11 @@
  * flags are answered by a single pass.
  */
 import { spawn } from 'node:child_process';
-import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { createCommentMask } from './comments.js';
-import { createExcludeMatcher, createGlobMatcher, statOrNull, toPosix, walkFiles, } from './glob.js';
+import { createExcludeMatcher, createGlobMatcher, toPosix, walkFiles } from './glob.js';
+import { nodeIo } from './io.js';
+import { NO_MEMO } from './memo.js';
 import { isBinary, LedgerBuilder, UNCERTAIN_REASONS } from './scope.js';
 import { lineStarts, locate } from './text.js';
 /** Files larger than this are skipped by both engines, keeping them in sync. */
@@ -409,8 +410,33 @@ export function buildJsRegExp(symbol, options) {
     const source = options.word ? `(?<![\\p{L}\\p{N}_])(?:${escaped})(?![\\p{L}\\p{N}_])` : escaped;
     return new RegExp(source, `${flags}u`);
 }
+/**
+ * Scans one file's bytes for every pattern of a pass.
+ *
+ * A pure function of the bytes, the path (which decides the comment syntax),
+ * the patterns and how they match, which is what lets a watch session remember
+ * it (ADR-0014).
+ */
+function scanFile(buffer, relativePath, regexps, ignoreComments) {
+    const content = buffer.toString('utf8');
+    let mask;
+    const getMask = ignoreComments ? () => (mask ??= createCommentMask(content, relativePath)) : undefined;
+    const tallies = new Map();
+    for (const [pattern, regexp] of regexps) {
+        tallies.set(pattern, scanContent(content, relativePath, regexp, getMask));
+    }
+    // Read after the loop, where every pattern has had its chance to ask.
+    const built = mask;
+    return { tallies, binary: isBinary(buffer), classified: built?.classified };
+}
 class JavaScriptEngine {
+    io;
+    memo;
     name = 'javascript';
+    constructor(io, memo) {
+        this.io = io;
+        this.memo = memo;
+    }
     async search(request) {
         const [result] = await this.searchBatch([request]);
         return result;
@@ -424,7 +450,7 @@ class JavaScriptEngine {
         const [first] = requests;
         if (!first)
             return [];
-        const enumeration = await enumerateCandidates(first);
+        const enumeration = await enumerateCandidates(first, undefined, this.io);
         return this.searchFiles(enumeration.files, requests, [], enumeration.skipped);
     }
     /**
@@ -438,48 +464,68 @@ class JavaScriptEngine {
         const [first] = requests;
         if (!first)
             return [];
-        const ledger = new LedgerBuilder();
-        for (const entry of skipped)
-            ledger.add(entry.path, entry.reason, entry.matches);
-        for (const entry of unreadable)
-            ledger.add(entry, 'unreadable');
         const patterns = [...new Set(requests.map((request) => request.symbol))];
         const regexps = new Map(patterns.map((pattern) => [pattern, buildJsRegExp(pattern, first.options)]));
         const tallies = new Map(patterns.map((pattern) => [pattern, emptyTally()]));
+        // One ledger and one count of unclassified files per pattern, not one for
+        // the pass. A pass answers every rule over the same scope at once, and a
+        // binary file holding one rule's symbol is not a gap in another rule's
+        // answer - yet a shared ledger reported it against every rule in the pass,
+        // with all their matches added up, and --strict failed rules over a file
+        // that did not hold their symbol. Found by holding ADR-0014's watch
+        // session, which runs each rule alone, to a plain run.
+        const ledgers = new Map(patterns.map((pattern) => [pattern, new LedgerBuilder()]));
+        const unclassified = new Map(patterns.map((pattern) => [pattern, 0]));
+        for (const ledger of ledgers.values()) {
+            // What every rule shares: what the walk could not list, and what ripgrep
+            // could not read.
+            for (const entry of skipped)
+                ledger.add(entry.path, entry.reason, entry.matches);
+            for (const entry of unreadable)
+                ledger.add(entry, 'unreadable');
+        }
+        // Everything a file's scan depends on besides its bytes and its path, which
+        // decides its comment syntax. See memo.ts for why a missing input here is
+        // the one defect a memo can have.
+        const { regex, word, ignoreCase, ignoreComments } = first.options;
+        const scanInputs = [JSON.stringify([regex, word, ignoreCase, ignoreComments]), JSON.stringify(patterns)];
         // No floor of 1: an empty file list starts no readers, and a loop that
         // never runs produces the same empty tallies as one that runs once and
         // finds nothing. The guard was defending against an outcome it shared.
         const concurrency = readConcurrency(files.length);
         let cursor = 0;
-        const perFile = new Map();
-        // Per pattern, how many matches each file holds. Only files that matched
-        // appear, so this is smaller than perFile, which already holds an entry for
-        // every file scanned - there is no new memory shape here.
-        const byFile = new Map(patterns.map((pattern) => [pattern, new Map()]));
-        let unclassifiedFiles = 0;
+        // What each reader found, by file. Entered in the ledgers and the tallies
+        // in walk order below, rather than by each reader as its read ends: that
+        // was the order reads happened to finish in, which differed between two
+        // runs of one tree - and past a ledger's cap, so did which paths it named.
+        const scans = new Map();
         const worker = async () => {
             while (cursor < files.length) {
                 const file = files[cursor++];
                 /* c8 ignore next -- cursor is bounded by files.length */
                 if (!file)
                     return;
-                const buffer = await fs.readFile(file.absolutePath).catch(() => null);
-                if (!buffer) {
-                    // A file we cannot open might hold anything, so it is recorded rather
-                    // than passed over as though it had been read and found clean.
+                const buffer = await this.io.readFile(file.absolutePath).catch(() => null);
+                // A file we cannot open might hold anything, so it is recorded rather
+                // than passed over as though it had been read and found clean.
+                scans.set(file.relativePath, buffer === null
+                    ? null
+                    : this.memo.remember(buffer, [...scanInputs, file.relativePath], () => scanFile(buffer, file.relativePath, regexps, ignoreComments)));
+            }
+        };
+        await Promise.all(Array.from({ length: concurrency }, worker));
+        // Merge in walk order so snippets come out sorted by path, like ripgrep's,
+        // and so do the ledgers.
+        const byFile = new Map(patterns.map((pattern) => [pattern, new Map()]));
+        for (const file of files) {
+            const scan = scans.get(file.relativePath);
+            if (scan === null) {
+                for (const ledger of ledgers.values())
                     ledger.add(file.relativePath, 'unreadable');
-                    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, getMask));
-                }
-                if (isBinary(buffer)) {
+                continue;
+            }
+            for (const [pattern, tally] of scan.tallies) {
+                if (scan.binary) {
                     // Searched, but not counted. Skipping binary files silently was a way
                     // to pass an assertion by never looking; searching them and saying
                     // what was found leaves the decision with the reader.
@@ -489,26 +535,17 @@ class JavaScriptEngine {
                     // found clean - and leaving it out is also what keeps the two engines
                     // reporting the same thing, since ripgrep only ever hands the scanner
                     // files that matched.
-                    const found = [...scanned.values()].reduce((total, tally) => total + tally.count, 0);
-                    if (found > 0)
-                        ledger.add(file.relativePath, 'binary', found);
+                    if (tally.count > 0)
+                        ledgers.get(pattern).add(file.relativePath, 'binary', tally.count);
                     continue;
                 }
-                // 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);
-            }
-        };
-        await Promise.all(Array.from({ length: concurrency }, worker));
-        // Merge in walk order so snippets come out sorted by path, like ripgrep's.
-        for (const file of files) {
-            const scanned = perFile.get(file.relativePath);
-            if (!scanned)
-                continue;
-            for (const [pattern, tally] of scanned) {
+                // A mask is built only once some pattern has matched, and a file this
+                // pattern did not match is not one whose comments it counted as code.
+                // No comment count here: a file whose comments cannot be told from its
+                // code has none, so every match it holds is in the count.
+                if (scan.classified === false && tally.count > 0) {
+                    unclassified.set(pattern, unclassified.get(pattern) + 1);
+                }
                 const total = tallies.get(pattern);
                 total.count += tally.count;
                 total.commentCount += tally.commentCount;
@@ -520,16 +557,15 @@ class JavaScriptEngine {
                 }
             }
         }
-        const scope = ledger.build();
         return requests.map((request) => {
-            const tally = tallies.get(request.symbol) ?? emptyTally();
+            const tally = tallies.get(request.symbol);
             return {
                 count: tally.count,
                 commentMatches: tally.commentCount,
-                unclassifiedFiles,
+                unclassifiedFiles: unclassified.get(request.symbol),
                 matches: tally.locations,
-                fileCounts: byFile.get(request.symbol) ?? new Map(),
-                scope,
+                fileCounts: byFile.get(request.symbol),
+                scope: ledgers.get(request.symbol).build(),
                 engine: this.name,
             };
         });
@@ -554,13 +590,13 @@ export const ANY_FILE_PROBE = { maxFiles: 0, maxBytes: 0 };
  */
 export async function enumerateCandidates(request, budget, 
 /**
- * Directory reader, forwarded to the walk. Exists for the same reason
- * `walkFiles` takes one: the interesting behaviour here is what the
- * enumeration does with a directory it *cannot* read, and there is no
- * portable way to create one - Windows has no chmod, and a permission bit set
- * by a test is a permission bit a failed test leaves behind.
+ * The door the enumeration reads through, forwarded to the walk. Injectable
+ * for the same reason `walkFiles` takes one: the interesting behaviour here
+ * is what the enumeration does with a directory it *cannot* read, and there
+ * is no portable way to create one - Windows has no chmod, and a permission
+ * bit set by a test is a permission bit a failed test leaves behind.
  */
-readDirectory) {
+io = nodeIo) {
     const matcher = createGlobMatcher(request.options.globs);
     const excluded = createExcludeMatcher(request.options.excludeGlobs);
     // excludeFiles is applied here rather than after the walk so that a budgeted
@@ -597,7 +633,7 @@ readDirectory) {
     };
     outer: for (const target of targetsOf(request)) {
         const absoluteTarget = path.resolve(request.root, target);
-        const stats = await statOrNull(absoluteTarget);
+        const stats = await io.stat(absoluteTarget);
         if (!stats)
             continue;
         if (stats.isFile()) {
@@ -612,7 +648,7 @@ readDirectory) {
         const walkOptions = {
             scope: request.options.scope,
             onSkip: (relativePath, reason) => note(prefix ? `${prefix}/${relativePath}` : relativePath, reason),
-            ...(readDirectory ? { readDirectory } : {}),
+            io,
         };
         for await (const file of walkFiles(absoluteTarget, walkOptions)) {
             if (!withinSizeLimit(file.size))
@@ -681,7 +717,18 @@ getMask) {
     // comparator changed any result.
     return { count, locations: [...byLine.values()], commentCount };
 }
-export const javascriptEngine = new JavaScriptEngine();
+/**
+ * A scanner that reads through the given door, and remembers its scans in the
+ * given memo.
+ *
+ * One per watch session rule, so the session sees what each rule read
+ * (ADR-0014). A plain run shares the one below, which reads the filesystem and
+ * remembers nothing.
+ */
+export function createJavaScriptEngine(io = nodeIo, memo = NO_MEMO) {
+    return new JavaScriptEngine(io, memo);
+}
+export const javascriptEngine = createJavaScriptEngine();
 /**
  * How much scanning the JavaScript engine may do before ripgrep is worth a
  * process spawn.
@@ -806,8 +853,12 @@ export async function resolveEngine(preference = 'auto') {
 /**
  * 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".
+ *
+ * The fallback is a parameter because a watch session's scanner reads through a
+ * door of its own, and falling back to the shared one would read past it.
+ * Nothing falls back from the fallback: its failure is the run's failure.
  */
-export function createCachedEngine(engine) {
+export function createCachedEngine(engine, fallback = javascriptEngine) {
     const cache = new Map();
     const fallbacks = [];
     const keyOf = searchKey;
@@ -826,10 +877,10 @@ export function createCachedEngine(engine) {
             let result = cache.get(key);
             if (!result) {
                 result = engine.search(request).catch(async (error) => {
-                    if (engine === javascriptEngine)
+                    if (engine === fallback)
                         throw error;
                     recordFallback(error);
-                    return javascriptEngine.search(request);
+                    return fallback.search(request);
                 });
                 cache.set(key, result);
             }
@@ -844,10 +895,10 @@ export function createCachedEngine(engine) {
             // does nothing. The guard could not change an outcome, which is why
             // nothing could be written to hold it in place.
             const pending = runSearches(engine, uncached).catch(async (error) => {
-                if (engine === javascriptEngine)
+                if (engine === fallback)
                     throw error;
                 recordFallback(error);
-                return runSearches(javascriptEngine, uncached);
+                return runSearches(fallback, uncached);
             });
             uncached.forEach((request, index) => {
                 cache.set(keyOf(request), pending.then((results) => results[index]));