@orkestrel/scaffold 0.0.107 → 0.0.109

package/dist/agents/skills/orkestrel-harden/scripts/discovery.js

@@ -1,27 +1,65 @@
 // Let Vitest select each gate's tests, then compare its identities with each config/mode universe.
 // Run from the checkout root:
 //   node .agents/skills/orkestrel-harden/scripts/discovery.ts [--config vite.config.ts] [--projects a,b] [--json]
-// Follow root npm script chains and forwarded arguments. Collect an unfiltered full listing for
-// each config/mode/root/dir, including the base config. Pass gate arguments verbatim except the
-// reporter, output-file, coverage, color, cache, silent, UI, watch, run-mode, inspector, and
-// standalone options;
-// use filesOnly for file selection and full collection for name, tag, line, and shard selection.
-// Compare file/project/name/line/column identities without renaming projects. With --projects,
-// ask Vitest for the reporting scope. Preserve duplicate names within a listing and merge across units.
-// Ignore bench, list, mergeReports, listTags, and clearCache invocations as gates. Flag partly ungated rows, empty chained projects,
-// and undiscovered files under tests/. Report marker counts and empty standalone workbenches.
+// Each value is a separate argument: `--flag=value` and any flag the script does not read exit 64.
+// Roots are the package scripts no `npm run` invokes; `npm test` runs the root `test`, which stays a
+// root. Follow root chains and forwarded arguments through `npm run [-s|--silent] NAME`,
+// `npm run-script`, `npm test`, and `npm t`. Read a command past an environment prefix, `cross-env`,
+// and a redirection. A gate is a Vitest run; list, bench, watch, dev, `--watch` without `=false`, and
+// the mergeReports, listTags, and clearCache invocations are not gates. A test file counts as gated
+// by a command only when `node` runs it as an argument (`node FILE`, `node --test FILE`).
+// Collect an unfiltered full listing for each config/mode/root/dir, including the base config. Pass
+// gate arguments verbatim except the reporter, output-file, coverage, color, cache, silent, UI,
+// watch, run-mode, inspector, and standalone options; use filesOnly for file selection and full
+// collection with --staticParse=false for name, tag, line, and shard selection, so runtime titles,
+// setup modules, and the worker sequencer participate. Compare file/project/name/line/column
+// identities without renaming projects. Preserve duplicate names within a listing and merge across
+// units. Exit 2 naming the Vitest version when the option table lacks a required option.
+// With --projects, list only the named projects: the universe, each gate listing, each project
+// reading, the units enumerated, and the empty-project rescan carry the names, and a gate that
+// reaches none of them is not listed. An exact name never lists a project outside the set, and the
+// refusal for a name that matches none lists no other project either. A name holding `*` or opening
+// with `!` is a Vitest pattern the script cannot match beforehand, so a gate that names projects
+// keeps its own and a listing for such a name can reach projects beyond the names. Exit 64 for a
+// name no project in the config matches, and skip the undiscovered scan.
+// Flag ungated projects, empty chained projects, and undiscovered files under tests/ (the test
+// and spec names, any extension). Report marker counts for the forms that need a ruling (`.todo`,
+// `.skipIf`, `.runIf`, `.fails`, a `retry` option, a timeout option or a numeric last argument),
+// read as call forms outside comments and strings; `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse `.only` and `.skip`. Report empty
+// standalone workbenches without a flag: an empty project no chain containing " > " names.
 // Retry when test files change during collection; refuse another change during that retry.
-// Exit 0 with no flag, 3 with a flag, 2 for missing Vitest, unsupported related commands,
-// CLI/help/argument/listing/output failures, repeated test-file changes, or filesystem/JSON errors;
-// exit 64 on usage.
+// Exit 0 with no flag, 3 with a flag, 2 for missing Vitest, an option table without a required
+// option, unsupported related commands, CLI/help/argument/listing/output failures, repeated
+// test-file changes, or filesystem/JSON errors; exit 64 on usage.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join, relative, resolve } from 'node:path';
-import { listFiles, readMissingFlags, readOption, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const VITEST = 'node_modules/vitest/vitest.mjs';
-const MARKERS = ['.skip(', '.todo(', '.skipIf(', '.runIf(', 'retry:', 'timeout:'];
-const OMITTED = new Set([
+/** Names the Vitest entry the census runs. */
+export const VITEST = 'node_modules/vitest/vitest.mjs';
+/** Lists the marker names the census counts, in report order. */
+export const MARKERS = [
+    '.todo',
+    '.skipIf',
+    '.runIf',
+    '.fails',
+    'retry',
+    'timeout',
+];
+/** Lists the options the scraped Vitest help table must hold before a listing runs. */
+export const REQUIRED_OPTIONS = [
+    '--reporter',
+    '--project',
+    '--config',
+    '--filesOnly',
+    '--staticParse',
+];
+/** Lists the flags this script reads, value flags and switches alike. */
+export const FLAGS = ['--config', '--projects', '--json'];
+/** Holds the usage line printed on a usage refusal. */
+export const USAGE = 'usage: discovery.ts [--config vite.config.ts] [--projects a,b] [--json]';
+/** Names the options a gate listing drops, because they change the run and not the selection. */
+export const OMITTED = new Set([
     'reporter',
     'outputFile',
     'coverage',
@@ -35,10 +73,171 @@ const OMITTED = new Set([
     'inspectBrk',
     'standalone',
 ]);
-// Bounds one listing, so an option that waits for input exits 2 naming its gate instead of
-// hanging the census.
-const LISTING_TIMEOUT = 600_000;
-function readCLIOptions() {
+/** Bounds one listing, so an option that waits for input exits 2 naming its gate. */
+export const LISTING_TIMEOUT = 600_000;
+/** Caps the characters of a name an error message echoes. */
+export const NAME_LIMIT = 80;
+/** Names the directories a tree walk skips by default, so build output and notes stay unread. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/** Names the only directories the undiscovered scan skips. */
+export const UNDISCOVERED_SKIPS = new Set(['node_modules', '.git']);
+/** Matches the test file names the modification snapshot watches. */
+export const TEST_FILE_PATTERN = /\.test\.[cm]?[jt]sx?$/u;
+/** Matches the test and spec file names the undiscovered scan reports. */
+export const DISCOVERABLE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
+/** Matches a test file path a `node` command can run as an argument. */
+export const TEST_ARGUMENT_PATTERN = /^(?:tests|src|app)\/[A-Za-z0-9_./-]+\.test\.[cm]?ts$/u;
+/** Matches one command token, keeping a quoted run, an `&`-form redirection, or a separator whole. */
+export const COMMAND_TOKEN_PATTERN = /\d*[<>]&[\d-]+|&>>?|(?:[^\s"';&|]+|"[^"]*"|'[^']*')+|[;&|]+/gu;
+/** Matches a redirection operator that takes the next token as its target. */
+export const REDIRECT_OPERATOR_PATTERN = /^(?:\d*>>?|\d*<|&>>?)$/u;
+/** Matches a redirection that carries its target or duplicates a descriptor. */
+export const REDIRECT_TARGET_PATTERN = /^(?:(?:\d*>>?|\d*<|&>>?)[^\s<>&]\S*|\d*[<>]&[\d-]+)$/u;
+/** Matches a leading `NAME=value` environment assignment. */
+export const ENVIRONMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+/** Matches a `--watch` switch that is not turned off in its own token. */
+export const WATCH_PATTERN = /^(?:--watch|--watch=(?!false$).*|-w)$/u;
+/** Matches the reporting and cache-maintenance switches that make an invocation no gate. */
+export const MAINTENANCE_PATTERN = /^(?:--mergeReports|--merge-reports|--listTags|--list-tags|--clearCache|--clear-cache)(?:=|$)/u;
+/** Matches the options and filters that make a gate select tests by name, tag, line, or shard. */
+export const FULL_PATTERN = /^(?:-t|--testNamePattern|--test-name-pattern|--tagsFilter|--tags-filter|--shard|--(?:no-)?allowOnly|--(?:no-)?allow-only|--(?:no-)?strictTags|--(?:no-)?strict-tags)(?:=|$)/u;
+/** Matches a numeric literal token such as a timeout argument. */
+export const NUMBER_PATTERN = /^\d[\d_]*(?:\.\d+)?(?:e\d+)?$/iu;
+/** Matches the quoted string literals the scanner keeps whole. */
+export const STRING_PATTERN = /^(?:'(?:\\[\s\S]|[^'\\\r\n])*'|"(?:\\[\s\S]|[^"\\\r\n])*")/u;
+/** Matches a regular expression literal opening at a slash. */
+export const REGEX_PATTERN = /^\/(?:\\.|\[(?:\\.|[^\]\\\r\n])*\]|[^/\\[\r\n])+\/[a-z]*/u;
+/** Matches an identifier or a number as one scanner word. */
+export const WORD_PATTERN = /^(?:[\p{ID_Start}_$][\p{ID_Continue}$]*|\d[\w.]*)/u;
+/** Names the keywords after which a slash opens a regular expression. */
+export const REGEX_KEYWORDS = new Set([
+    'return',
+    'typeof',
+    'case',
+    'throw',
+    'in',
+    'of',
+    'void',
+    'delete',
+    'yield',
+    'await',
+    'else',
+    'do',
+    'instanceof',
+    'new',
+]);
+/** Lists the tokens that open a bracket group. */
+export const OPENERS = ['(', '[', '{'];
+/** Lists the tokens that close a bracket group. */
+export const CLOSERS = [')', ']', '}'];
+/** Names the calls whose first argument list precedes the registration call. */
+export const ARGUMENT_MODIFIERS = new Set(['each', 'skipIf', 'runIf', 'for']);
+/** Names the registration modifiers that need a ruling when a test file carries them. */
+export const CHAIN_MARKERS = new Set(['todo', 'skipIf', 'runIf', 'fails']);
+/** Names the identifiers that open a test registration. */
+export const REGISTRARS = new Set(['it', 'test', 'describe', 'suite']);
+/**
+ * Normalizes a host path to forward slashes.
+ *
+ * @param path - A host path.
+ * @returns The same path with every backslash replaced by a slash.
+ */
+export function normalizeSlashes(path) {
+    return path.split('\\').join('/');
+}
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
+ * and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--config`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
+ * reads `--flag value` pairs only.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Lists every regular file beneath a directory, skipping the named directories at any depth.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: {@link SKIPPED_DIRECTORIES}.
+ * @returns Each file's forward-slash path and modification time, in walk order.
+ * @throws Thrown when `directory` does not exist or cannot be read; check `existsSync` first.
+ */
+export function listFiles(directory, skipped = SKIPPED_DIRECTORIES) {
+    const files = [];
+    const pending = [directory];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (skipped.has(entry.name))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (entry.isFile()) {
+                files.push({ path: normalizeSlashes(path), modified: statSync(path).mtimeMs });
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Describes a name for an error message, JSON-encoded and length-capped.
+ *
+ * @param name - The untrusted name to echo.
+ * @returns The encoded name, cut where it exceeds the cap.
+ */
+export function describeName(name) {
+    return JSON.stringify(name.length > NAME_LIMIT ? `${name.slice(0, NAME_LIMIT)}…` : name);
+}
+/**
+ * Reads the Vitest option table the installed CLI prints for its list command.
+ *
+ * @returns Each option keyed by its long, kebab, negated, and short spellings.
+ * @throws Thrown when the help command fails.
+ */
+export function readCLIOptions() {
     const help = spawnSync(process.execPath, [VITEST, 'list', '--help', '--expand-help'], {
         encoding: 'utf8',
         windowsHide: true,
@@ -60,8 +259,40 @@ function readCLIOptions() {
         ];
     }));
 }
-// An option that takes a value consumes the token after it, so that token is never read as a runner.
-function skipRunnerOptions(command, index) {
+/**
+ * Names the required options an option table lacks.
+ *
+ * @param options - The table `readCLIOptions` returned.
+ * @returns Each required option the table does not hold, in required order.
+ */
+export function readMissingOptions(options) {
+    return REQUIRED_OPTIONS.filter((name) => !options.has(name));
+}
+/**
+ * Reads the installed Vitest version.
+ *
+ * @returns The version string, or `unknown` when the manifest names none.
+ */
+export function readVitestVersion() {
+    const parsed = JSON.parse(readFileSync('node_modules/vitest/package.json', 'utf8'));
+    return typeof parsed === 'object' &&
+        parsed !== null &&
+        'version' in parsed &&
+        typeof parsed.version === 'string'
+        ? parsed.version
+        : 'unknown';
+}
+/**
+ * Skips the options of a `node` command so the first non-option token is the runner.
+ *
+ * @remarks
+ * An option that takes a value consumes the token after it, so that token is never read as a runner.
+ *
+ * @param command - The command tokens.
+ * @param index - The index to start reading options at.
+ * @returns The index of the first non-option token, or -1 for an eval, print, or check command.
+ */
+export function skipRunnerOptions(command, index) {
     const skipped = [...command.entries()].reduce((state, [position, option]) => {
         if (state.found !== undefined || position < state.next)
             return state;
@@ -90,7 +321,13 @@ function skipRunnerOptions(command, index) {
     }, { next: index, found: undefined });
     return skipped.found ?? skipped.next;
 }
-function findRunner(command) {
+/**
+ * Finds the Vitest runner in a command.
+ *
+ * @param command - The command tokens, past any environment prefix.
+ * @returns The runner's index, or -1 when the command does not run Vitest.
+ */
+export function findRunner(command) {
     const executable = basename(command[0] ?? '').replace(/\.(?:exe|cmd)$/u, '');
     const start = executable === 'npm'
         ? command[1] === 'exec'
@@ -106,9 +343,18 @@ function findRunner(command) {
         ? index
         : -1;
 }
-// The first `--` ends the options, so the rest of the arguments pass verbatim. A runner option that
-// takes a value consumes the argument after it, so a step below `skip` reads nothing.
-function readSelection(argv, options) {
+/**
+ * Keeps the tokens of a gate command that select tests and drops the run-mode options.
+ *
+ * @remarks
+ * The first `--` ends the options, so the rest of the arguments pass verbatim. A runner option that
+ * takes a value consumes the argument after it, so a step below `skip` reads nothing.
+ *
+ * @param argv - The tokens after the Vitest runner and verb.
+ * @param options - The option table `readCLIOptions` returned.
+ * @returns The tokens to pass to a listing.
+ */
+export function readSelection(argv, options) {
     return argv.reduce((state, token, index) => {
         if (state.closed || index < state.skip)
             return state;
@@ -133,7 +379,14 @@ function readSelection(argv, options) {
         return { ...state, skip: index + (valued ? 2 : 1) };
     }, { selected: [], skip: 0, closed: false }).selected;
 }
-function readArguments(argv, names) {
+/**
+ * Reads every value a named flag carries before the first `--`.
+ *
+ * @param argv - The tokens to read.
+ * @param names - The flag spellings to read.
+ * @returns Each value of the flag in either the `--flag value` or the `--flag=value` form.
+ */
+export function readArguments(argv, names) {
     const end = argv.indexOf('--');
     return (end < 0 ? argv : argv.slice(0, end)).flatMap((token, index) => {
         const equals = token.indexOf('=');
@@ -143,7 +396,12 @@ function readArguments(argv, names) {
         return value !== undefined && !value.startsWith('-') ? [value] : [];
     });
 }
-function readScripts() {
+/**
+ * Reads the script table of the package manifest in the working directory.
+ *
+ * @returns Each script name with its command text.
+ */
+export function readScripts() {
     const parsed = JSON.parse(readFileSync('package.json', 'utf8'));
     if (typeof parsed !== 'object' || parsed === null)
         return {};
@@ -152,96 +410,311 @@ function readScripts() {
         return {};
     return Object.fromEntries(Object.entries(scripts).flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : []));
 }
-function readCommands(text) {
-    const tokens = [...text.matchAll(/(?:[^\s"';&|]+|"[^"]*"|'[^']*')+|[;&|]+/gu)].map((match) => match[0]);
+/**
+ * Drops the redirections from a command's tokens.
+ *
+ * @param tokens - The raw command tokens, quotes still attached.
+ * @returns The tokens without a redirection operator, its target, or a descriptor duplication.
+ */
+export function stripRedirections(tokens) {
+    return tokens.filter((token, index) => {
+        const previous = tokens[index - 1];
+        return (!(previous !== undefined && REDIRECT_OPERATOR_PATTERN.test(previous)) &&
+            !REDIRECT_OPERATOR_PATTERN.test(token) &&
+            !REDIRECT_TARGET_PATTERN.test(token));
+    });
+}
+/**
+ * Drops the leading `cross-env` word and `NAME=value` assignments from a command's tokens.
+ *
+ * @param tokens - The command tokens.
+ * @returns The tokens from the first word that is neither, empty when the command is only a prefix.
+ */
+export function stripEnvironment(tokens) {
+    const start = tokens.findIndex((token) => token !== 'cross-env' && !ENVIRONMENT_PATTERN.test(token));
+    return start < 0 ? [] : tokens.slice(start);
+}
+/**
+ * Splits a script's text into its commands.
+ *
+ * @param text - The script text, with `;`, `&`, and `|` separating commands.
+ * @returns The commands as tokens, past redirections and environment prefixes, quotes removed.
+ */
+export function readCommands(text) {
+    const tokens = [...text.matchAll(COMMAND_TOKEN_PATTERN)].map((match) => match[0]);
     // A separator token ends a command, so the commands are the runs of tokens between the cuts.
     const cuts = tokens.flatMap((token, index) => (/^[;&|]+$/u.test(token) ? [index] : []));
-    return [-1, ...cuts].map((cut, at) => tokens.slice(cut + 1, cuts[at] ?? tokens.length).map((token) => token.replace(/["']/gu, '')));
+    return [-1, ...cuts].map((cut, at) => stripEnvironment(stripRedirections(tokens.slice(cut + 1, cuts[at] ?? tokens.length))).map((token) => token.replace(/["']/gu, '')));
 }
-function listInvocations(commands) {
+/**
+ * Lists the script calls the commands make.
+ *
+ * @remarks
+ * Reads `npm run [-s|--silent] NAME`, `npm run-script NAME`, `npm test`, and `npm t`; the last two
+ * are shorthand, which runs a script a person also starts directly. Arguments after `--` forward.
+ *
+ * @param commands - The commands to read.
+ * @returns One invocation per script call.
+ */
+export function listInvocations(commands) {
     return commands.flatMap((command) => {
         const index = command.indexOf('npm');
-        const name = command[index + 2];
-        if (index < 0 || command[index + 1] !== 'run' || name === undefined)
+        if (index < 0)
             return [];
-        const separator = command.indexOf('--', index + 3);
-        return [{ name, args: separator < 0 ? [] : command.slice(separator + 1), ancestors: [] }];
+        const verb = command[index + 1];
+        const separator = command.indexOf('--', index + 2);
+        const args = separator < 0 ? [] : command.slice(separator + 1);
+        if (verb === 'test' || verb === 't') {
+            return [{ name: 'test', args, ancestors: [], shorthand: true }];
+        }
+        if (verb !== 'run' && verb !== 'run-script')
+            return [];
+        const name = (separator < 0 ? command.slice(index + 2) : command.slice(index + 2, separator)).find((token) => !token.startsWith('-'));
+        return name === undefined ? [] : [{ name, args, ancestors: [], shorthand: false }];
     });
 }
-function readGates(scripts, config, options) {
+/**
+ * Walks the scripts a root reaches, last-pushed first, each script once per forwarded arguments.
+ *
+ * @param commands - The commands of every script, by name.
+ * @param root - The root script the chain starts at.
+ * @param pending - The invocations left to visit.
+ * @param visited - The name and argument keys already visited.
+ * @returns One visit per script reached, in visit order.
+ */
+export function walkInvocations(commands, root, pending, visited) {
+    const invocation = pending.at(-1);
+    if (invocation === undefined)
+        return [];
+    const rest = pending.slice(0, -1);
+    const { name, args, ancestors } = invocation;
+    const key = JSON.stringify([name, args]);
+    if (visited.has(key) || ancestors.includes(name)) {
+        return walkInvocations(commands, root, rest, visited);
+    }
+    const seen = new Set([...visited, key]);
+    const script = commands[name];
+    if (script === undefined)
+        return walkInvocations(commands, root, rest, seen);
+    const expanded = script.map((command, index) => index === script.length - 1 ? [...command, ...args] : command);
+    const children = listInvocations(expanded).map((entry) => ({
+        ...entry,
+        ancestors: [...ancestors, name],
+    }));
+    return [
+        { chain: root === name ? name : `${root} > ${name}`, commands: expanded },
+        ...walkInvocations(commands, root, [...rest, ...children], seen),
+    ];
+}
+/**
+ * Checks whether a command's options name a reporting or cache-maintenance invocation.
+ *
+ * @param before - The tokens before the first `--`.
+ * @returns True if a maintenance switch is present and not turned off.
+ */
+export function isMaintenance(before) {
+    return before.some((token, position) => MAINTENANCE_PATTERN.test(token) &&
+        !token.endsWith('=false') &&
+        before[position + 1] !== 'false');
+}
+/**
+ * Checks whether a command's options start watch mode.
+ *
+ * @param before - The tokens before the first `--`.
+ * @returns True if `--watch` or `-w` is present and not turned off.
+ */
+export function isWatching(before) {
+    return before.some((token, position) => WATCH_PATTERN.test(token) && before[position + 1] !== 'false');
+}
+/**
+ * Reads the gate a command makes, or none when the command does not run a test selection.
+ *
+ * @param command - The command tokens.
+ * @param chain - The root chain label.
+ * @param config - The base config path, forward-slashed and relative.
+ * @param options - The option table `readCLIOptions` returned.
+ * @returns The gate, or undefined for a command that is no Vitest run or no gate.
+ * @throws Thrown for a `related` command, which `vitest list` cannot select.
+ */
+export function readGate(command, chain, config, options) {
+    const index = findRunner(command);
+    if (index < 0)
+        return undefined;
+    const verb = command[index + 1];
+    if (verb === 'list' || verb === 'bench' || verb === 'watch' || verb === 'dev')
+        return undefined;
+    const tokens = command.slice(index + (verb === 'run' ? 2 : 1));
+    const separator = tokens.indexOf('--');
+    const before = separator < 0 ? tokens : tokens.slice(0, separator);
+    if (isMaintenance(before) || isWatching(before))
+        return undefined;
+    if (verb === 'related') {
+        throw new Error(`${chain}: Vitest list exposes no related command or --related option`);
+    }
+    const flags = readSelection(tokens, options);
+    const mode = readArguments(flags, ['--mode'])[0];
+    const directory = readArguments(flags, ['--root', '-r'])[0];
+    const dir = readArguments(flags, ['--dir'])[0];
+    const configured = readArguments(flags, ['--config', '-c'])[0];
+    const path = configured ?? (directory === undefined && dir === undefined ? config : undefined);
+    return {
+        config: path === undefined ? undefined : normalizeSlashes(relative(process.cwd(), resolve(path))),
+        mode: mode === 'test' ? undefined : mode,
+        ...(directory === undefined ? {} : { root: directory }),
+        ...(dir === undefined ? {} : { dir }),
+        projects: readArguments(flags, ['--project']),
+        chain,
+        args: configured === undefined && path !== undefined ? ['--config', path, ...flags] : flags,
+        full: before.some((flag) => FULL_PATTERN.test(flag) || /:\d+(?:-\d+)?$/u.test(flag)),
+    };
+}
+/**
+ * Reads the test files a `node` command runs as its arguments.
+ *
+ * @param command - The command tokens.
+ * @returns The test file arguments of `node FILE` or `node --test FILE...`; none for any other runner.
+ */
+export function readFileCredits(command) {
+    if (basename(command[0] ?? '').replace(/\.exe$/u, '') !== 'node')
+        return [];
+    const first = skipRunnerOptions(command, 1);
+    if (first < 0)
+        return [];
+    const candidates = command.includes('--test')
+        ? command.slice(first)
+        : command.slice(first, first + 1);
+    return candidates.filter((argument) => TEST_ARGUMENT_PATTERN.test(argument));
+}
+/**
+ * Reads the gates and node-run test files every root script chain reaches.
+ *
+ * @param scripts - The package scripts by name.
+ * @param config - The base config path, forward-slashed and relative.
+ * @param options - The option table `readCLIOptions` returned.
+ * @returns The gates in visit order, and the earliest chain that runs each test file with `node`.
+ */
+export function readGates(scripts, config, options) {
     const commands = Object.fromEntries(Object.entries(scripts).map(([name, text]) => [name, readCommands(text)]));
+    // A shorthand call (`npm test`) runs a script a person also starts directly, so it stays a root.
     const invoked = new Set(Object.values(commands)
         .flatMap(listInvocations)
+        .filter((entry) => !entry.shorthand)
         .map((entry) => entry.name));
-    const units = [];
-    const files = new Map();
-    for (const root of Object.keys(scripts).filter((name) => !invoked.has(name))) {
-        const visited = new Set();
-        const pending = [{ name: root, args: [], ancestors: [] }];
-        while (pending.length > 0) {
-            const invocation = pending.pop();
-            if (invocation === undefined)
-                continue;
-            const { name, args, ancestors } = invocation;
-            const key = JSON.stringify([name, args]);
-            if (visited.has(key) || ancestors.includes(name))
-                continue;
-            visited.add(key);
-            const script = commands[name];
-            if (script === undefined)
-                continue;
-            const expanded = script.map((command, index) => index === script.length - 1 ? [...command, ...args] : command);
-            for (const entry of listInvocations(expanded)) {
-                pending.push({ ...entry, ancestors: [...ancestors, name] });
-            }
-            const gate = root === name ? name : `${root} > ${name}`;
-            for (const command of expanded) {
-                const index = findRunner(command);
-                if (index >= 0) {
-                    const verb = command[index + 1];
-                    if (verb === 'list' || verb === 'bench')
-                        continue;
-                    const tokens = command.slice(index + (['run', 'watch', 'dev'].includes(verb ?? '') ? 2 : 1));
-                    const separator = tokens.indexOf('--');
-                    const before = separator < 0 ? tokens : tokens.slice(0, separator);
-                    if (before.some((token, position) => /^(?:--mergeReports|--merge-reports|--listTags|--list-tags|--clearCache|--clear-cache)(?:=|$)/u.test(token) &&
-                        !token.endsWith('=false') &&
-                        before[position + 1] !== 'false'))
-                        continue;
-                    if (verb === 'related')
-                        throw new Error(`${gate}: Vitest list exposes no related command or --related option`);
-                    const flags = readSelection(tokens, options);
-                    const mode = readArguments(flags, ['--mode'])[0];
-                    const directory = readArguments(flags, ['--root', '-r'])[0];
-                    const dir = readArguments(flags, ['--dir'])[0];
-                    const configured = readArguments(flags, ['--config', '-c'])[0];
-                    const path = configured ?? (directory === undefined && dir === undefined ? config : undefined);
-                    units.push({
-                        config: path === undefined
-                            ? undefined
-                            : relative(process.cwd(), resolve(path)).split('\\').join('/'),
-                        mode: mode === 'test' ? undefined : mode,
-                        ...(directory === undefined ? {} : { root: directory }),
-                        ...(dir === undefined ? {} : { dir }),
-                        projects: readArguments(flags, ['--project']),
-                        chain: gate,
-                        args: configured === undefined && path !== undefined ? ['--config', path, ...flags] : flags,
-                        full: before.some((flag) => /^(?:-t|--testNamePattern|--test-name-pattern|--tagsFilter|--tags-filter|--shard|--(?:no-)?allowOnly|--(?:no-)?allow-only|--(?:no-)?strictTags|--(?:no-)?strict-tags)(?:=|$)/u.test(flag) || /:\d+(?:-\d+)?$/u.test(flag)),
-                    });
-                    continue;
-                }
-                for (const argument of command) {
-                    if (/^(?:tests|src|app)\/[A-Za-z0-9_./-]+\.test\.[cm]?ts$/u.test(argument) &&
-                        !files.has(argument))
-                        files.set(argument, gate);
-                }
-            }
-        }
-    }
+    const visits = Object.keys(scripts)
+        .filter((name) => !invoked.has(name))
+        .flatMap((root) => walkInvocations(commands, root, [{ name: root, args: [], ancestors: [], shorthand: false }], new Set()));
+    const units = visits.flatMap((visit) => visit.commands.flatMap((command) => {
+        const gate = readGate(command, visit.chain, config, options);
+        return gate === undefined ? [] : [gate];
+    }));
+    // A Map keeps the last entry of a key, so the reversed credits leave the earliest chain.
+    const files = new Map(visits
+        .flatMap((visit) => visit.commands.flatMap((command) => findRunner(command) >= 0
+        ? []
+        : readFileCredits(command).map((file) => [file, visit.chain])))
+        .toReversed());
     return { units, files };
 }
-function listCollected(args, full, cache) {
-    const parameters = [...(full ? ['--includeTaskLocation'] : ['--filesOnly']), ...args];
+/**
+ * Checks whether a project name is a literal name and not a Vitest pattern.
+ *
+ * @param name - The project name or pattern.
+ * @returns True if the name holds no `*` and does not open with `!`.
+ */
+export function isConcreteName(name) {
+    return !name.includes('*') && !name.startsWith('!');
+}
+/**
+ * Checks whether a name matches a wildcard pattern the way Vitest matches a project filter.
+ *
+ * @param pattern - The pattern, where `*` matches any run of characters.
+ * @param name - The name to test.
+ * @returns True if the whole name matches, ignoring case.
+ */
+export function matchesWildcard(pattern, name) {
+    const body = pattern
+        .split('*')
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${body}$`, 'iu').test(name);
+}
+/**
+ * Checks whether a gate's project filters reach a project name.
+ *
+ * @remarks
+ * A browser instance name such as `web (chromium)` is also tested by its base name, because Vitest
+ * keeps every instance of a project whose base name a positive filter matches and drops them all
+ * when a negative filter matches it.
+ *
+ * @param filters - The gate's `--project` values, where a leading `!` negates.
+ * @param name - The concrete project name.
+ * @returns True if no negative filter matches and some positive filter does, or none is positive.
+ */
+export function matchesProjectFilter(filters, name) {
+    const names = [name, name.replace(/ \([^)]*\)$/u, '')];
+    const negative = filters
+        .filter((filter) => filter.startsWith('!'))
+        .map((filter) => filter.slice(1));
+    const positive = filters.filter((filter) => !filter.startsWith('!'));
+    if (negative.some((pattern) => names.some((candidate) => matchesWildcard(pattern, candidate)))) {
+        return false;
+    }
+    return (positive.length === 0 ||
+        positive.some((pattern) => names.some((candidate) => matchesWildcard(pattern, candidate))));
+}
+/**
+ * Replaces the `--project` flags of a gate's arguments.
+ *
+ * @param args - The gate arguments.
+ * @param projects - The project names to pass in place of the existing flags.
+ * @returns The arguments with one `--project NAME` pair per name, before any bare `--`.
+ */
+export function replaceProjects(args, projects) {
+    const end = args.indexOf('--');
+    const head = end < 0 ? args : args.slice(0, end);
+    const tail = end < 0 ? [] : args.slice(end);
+    const kept = head.filter((token, index) => token !== '--project' && !token.startsWith('--project=') && head[index - 1] !== '--project');
+    return [...kept, ...projects.flatMap((project) => ['--project', project]), ...tail];
+}
+/**
+ * Narrows the gates to the named projects, so no listing runs for a project outside the names.
+ *
+ * @remarks
+ * A gate with no project filter lists the named projects alone. A gate that names projects lists the
+ * named ones its filters reach and is dropped when it reaches none. A pattern among the names
+ * (`*`, or a leading `!`) cannot be matched beforehand, so a gate that names projects keeps them.
+ *
+ * @param gates - The gates the root chains reach.
+ * @param named - The `--projects` names, empty for no narrowing.
+ * @returns The gates to list, each with its narrowed arguments.
+ */
+export function narrowGates(gates, named) {
+    if (named.length === 0)
+        return gates;
+    const concrete = named.filter(isConcreteName);
+    const patterned = concrete.length < named.length;
+    return gates.flatMap((gate) => {
+        if (gate.projects.length === 0)
+            return [{ ...gate, args: replaceProjects(gate.args, named) }];
+        if (patterned)
+            return [gate];
+        const reached = concrete.filter((name) => matchesProjectFilter(gate.projects, name));
+        return reached.length === 0 ? [] : [{ ...gate, args: replaceProjects(gate.args, reached) }];
+    });
+}
+/**
+ * Lists the tests one Vitest listing collects.
+ *
+ * @param args - The arguments to pass after `vitest list`.
+ * @param full - True to collect each test with its name and location; false for files only.
+ * @param cache - The listings already read, keyed by their arguments.
+ * @returns The tests and whether the project filter matched, or undefined when Vitest refuses.
+ */
+export function listCollected(args, full, cache) {
+    const parameters = [
+        ...(full ? ['--includeTaskLocation', '--staticParse=false'] : ['--filesOnly']),
+        ...args,
+    ];
     const key = JSON.stringify(parameters);
     const cached = cache.get(key);
     if (cached !== undefined)
@@ -257,9 +730,11 @@ function listCollected(args, full, cache) {
         });
         if (args.includes('--project') &&
             result.status === 1 &&
-            result.stderr.includes('No projects matched the filter "')) {
-            cache.set(key, []);
-            return [];
+            (result.stderr.includes('No projects matched the filter "') ||
+                result.stderr.includes('The filter matched no projects:'))) {
+            const unmatched = { entries: [], matched: false };
+            cache.set(key, unmatched);
+            return unmatched;
         }
         if (result.status !== 0 || !existsSync(listing)) {
             const diagnostic = result.stderr || result.error?.message || result.stdout;
@@ -287,7 +762,7 @@ function listCollected(args, full, cache) {
             }
             return [
                 {
-                    file: relative(process.cwd(), record.file).split('\\').join('/'),
+                    file: normalizeSlashes(relative(process.cwd(), record.file)),
                     projectName: record.projectName ?? '',
                     name: typeof record.name === 'string' ? record.name : undefined,
                     line: typeof location.line === 'number' ? location.line : undefined,
@@ -295,8 +770,9 @@ function listCollected(args, full, cache) {
                 },
             ];
         });
-        cache.set(key, collected);
-        return collected;
+        const listed = { entries: collected, matched: true };
+        cache.set(key, listed);
+        return listed;
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -306,86 +782,340 @@ function listCollected(args, full, cache) {
         rmSync(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     }
 }
-function listTestFiles(directory) {
+/**
+ * Lists the test and spec files beneath a directory.
+ *
+ * @param directory - The directory to walk; a missing directory holds none.
+ * @returns The forward-slash paths of every test or spec file, skipping only `node_modules` and `.git`.
+ */
+export function listTestFiles(directory) {
     if (!existsSync(directory))
         return [];
-    return listFiles(directory)
+    return listFiles(directory, UNDISCOVERED_SKIPS)
         .map((file) => file.path)
-        .filter((path) => /\.test\.[cm]?ts$/u.test(path));
+        .filter((path) => DISCOVERABLE_PATTERN.test(path));
 }
-function countMarkers(file) {
-    const text = readFileSync(file, 'utf8');
-    return Object.fromEntries(MARKERS.map((marker) => [marker, text.split(marker).length - 1]).filter(([, count]) => count > 0));
+/**
+ * Scans source text into tokens that tell code from comments and strings.
+ *
+ * @remarks
+ * Comments are dropped. A string, a template (whole, with its expressions), and a regular expression
+ * literal each become one token. A slash opens a regular expression after an operator, an opening
+ * bracket, or a keyword, and divides after a word, a literal, or a closing bracket. The scanner
+ * pairs each opening bracket with its closing bracket as it reads.
+ */
+export class CodeScanner {
+    #text;
+    #tokens = [];
+    #closes = new Map();
+    #opened = [];
+    #position = 0;
+    #last = undefined;
+    constructor(text) {
+        this.#text = text;
+    }
+    scan() {
+        while (this.#position < this.#text.length) {
+            const token = this.#read();
+            if (token === undefined)
+                continue;
+            if (token.kind === 'punct' && OPENERS.includes(token.text)) {
+                this.#opened.push(this.#tokens.length);
+            }
+            if (token.kind === 'punct' && CLOSERS.includes(token.text)) {
+                const open = this.#opened.pop();
+                if (open !== undefined)
+                    this.#closes.set(open, this.#tokens.length);
+            }
+            this.#tokens.push(token);
+        }
+        return { tokens: this.#tokens, closes: this.#closes };
+    }
+    #read() {
+        const rest = this.#text.slice(this.#position);
+        const skipped = /^(?:\s+|\/\/[^\r\n]*|\/\*[\s\S]*?(?:\*\/|$))/u.exec(rest);
+        if (skipped !== null) {
+            this.#position += skipped[0].length;
+            return undefined;
+        }
+        if (rest.startsWith('`'))
+            return this.#take('template', this.#readTemplate());
+        const quoted = STRING_PATTERN.exec(rest);
+        if (quoted !== null)
+            return this.#take('string', quoted[0]);
+        if (rest.startsWith('/') && this.#expectsRegex()) {
+            const regex = REGEX_PATTERN.exec(rest);
+            if (regex !== null)
+                return this.#take('regex', regex[0]);
+        }
+        const word = WORD_PATTERN.exec(rest);
+        if (word !== null)
+            return this.#take('word', word[0]);
+        return this.#take('punct', rest.slice(0, 1));
+    }
+    #take(kind, text) {
+        if (kind !== 'template')
+            this.#position += text.length;
+        const token = { kind, text };
+        this.#last = token;
+        return token;
+    }
+    #expectsRegex() {
+        const last = this.#last;
+        if (last === undefined)
+            return true;
+        if (last.kind === 'punct')
+            return !CLOSERS.includes(last.text);
+        if (last.kind === 'word')
+            return REGEX_KEYWORDS.has(last.text);
+        return false;
+    }
+    #readTemplate() {
+        const start = this.#position;
+        this.#position += 1;
+        while (this.#position < this.#text.length) {
+            const character = this.#text[this.#position];
+            if (character === '\\') {
+                this.#position += 2;
+            }
+            else if (character === '`') {
+                this.#position += 1;
+                return this.#text.slice(start, this.#position);
+            }
+            else if (this.#text.startsWith('${', this.#position)) {
+                this.#position += 2;
+                this.#skipExpression();
+            }
+            else {
+                this.#position += 1;
+            }
+        }
+        return this.#text.slice(start, this.#position);
+    }
+    #skipExpression() {
+        while (this.#position < this.#text.length) {
+            const token = this.#read();
+            if (token?.kind !== 'punct')
+                continue;
+            if (token.text === '}')
+                return;
+            if (token.text === '{')
+                this.#skipExpression();
+        }
+    }
 }
-function collectListings(config, named, gates) {
-    const base = { config, mode: undefined };
-    // A gate joins the units unless the base unit or an earlier gate already names the same unit.
-    const units = [
-        base,
-        ...gates.units
-            .filter((gate, index) => ![base, ...gates.units.slice(0, index)].some((unit) => isSameUnit(unit, gate)))
-            .map((gate) => ({
-            config: gate.config,
-            mode: gate.mode,
-            ...(gate.root === undefined ? {} : { root: gate.root }),
-            ...(gate.dir === undefined ? {} : { dir: gate.dir }),
-        })),
-    ];
-    // A listing is a memo keyed by its arguments: each key is written once, on its first miss.
-    const cache = new Map();
-    const readings = collectReadings(units, (unit) => readUnit(unit, named, gates, cache));
-    if (readings === undefined)
+/**
+ * Checks whether a token is a punctuation mark with the given text.
+ *
+ * @param token - The token, or undefined past the end.
+ * @param text - The punctuation text.
+ * @returns True if the token is that punctuation mark.
+ */
+export function isPunct(token, text) {
+    return token?.kind === 'punct' && token.text === text;
+}
+/**
+ * Reads the modifier chain after a registrar, up to its registration call.
+ *
+ * @param scan - The scanned source.
+ * @param at - The index after the registrar or the last chain element.
+ * @param names - The modifier names read so far; an empty name marks a consumed argument group.
+ * @returns The names and the index of the registration call's opening parenthesis, or undefined when
+ * the tokens are no registration call.
+ */
+export function readChain(scan, at, names) {
+    const token = scan.tokens[at];
+    if (token === undefined)
         return undefined;
-    const listings = readings.map(({ listing }) => listing);
-    const populated = new Set(readings.flatMap((reading) => reading.populated));
-    // A project empty under one unit may still list tests under another, so each unit is asked for it.
-    const rescans = collectReadings([...new Set(listings.flatMap((listing) => listing.empty))]
-        .filter((name) => !populated.has(name))
-        .flatMap((name) => units.map((unit) => ({ name, unit }))), ({ name, unit }) => {
-        const selection = listCollected([...readUnitArguments(unit), '--project', name], false, cache);
-        return selection === undefined ? undefined : { name, listed: selection.length > 0 };
-    });
-    if (rescans === undefined)
+    const last = names.at(-1) ?? '';
+    if (isPunct(token, '.')) {
+        const name = scan.tokens[at + 1];
+        return name?.kind === 'word' ? readChain(scan, at + 2, [...names, name.text]) : undefined;
+    }
+    if (token.kind === 'template' && ARGUMENT_MODIFIERS.has(last)) {
+        return readChain(scan, at + 1, [...names, '']);
+    }
+    if (!isPunct(token, '('))
         return undefined;
-    const resolved = new Set([
-        ...populated,
-        ...rescans.filter(({ listed }) => listed).map(({ name }) => name),
-    ]);
-    return listings.map((listing) => ({
-        ...listing,
-        empty: listing.empty.filter((name) => !resolved.has(name)),
-    }));
+    if (!ARGUMENT_MODIFIERS.has(last))
+        return { names, call: at };
+    const close = scan.closes.get(at);
+    return close === undefined ? undefined : readChain(scan, close + 1, [...names, '']);
+}
+/**
+ * Splits a token range into its top-level arguments, jumping over bracket groups.
+ *
+ * @param scan - The scanned source.
+ * @param start - The index the current argument starts at.
+ * @param at - The index being read.
+ * @param end - The index the range ends at, excluded.
+ * @returns One span per non-empty argument.
+ */
+export function splitArguments(scan, start, at, end) {
+    if (at >= end)
+        return start < end ? [{ start, end }] : [];
+    const token = scan.tokens[at];
+    if (token?.kind === 'punct' && OPENERS.includes(token.text)) {
+        return splitArguments(scan, start, (scan.closes.get(at) ?? at) + 1, end);
+    }
+    if (isPunct(token, ',')) {
+        return [{ start, end: at }, ...splitArguments(scan, at + 1, at + 1, end)];
+    }
+    return splitArguments(scan, start, at + 1, end);
+}
+/**
+ * Reads the property keys at the top level of an object literal's token range.
+ *
+ * @param scan - The scanned source.
+ * @param at - The index being read.
+ * @param end - The index the range ends at, excluded.
+ * @returns Each key that follows `{` or `,` and precedes `:`, `,`, or `}`, quotes removed.
+ */
+export function readKeys(scan, at, end) {
+    const token = scan.tokens[at];
+    if (token === undefined || at >= end)
+        return [];
+    if (token.kind === 'punct' && OPENERS.includes(token.text)) {
+        return readKeys(scan, (scan.closes.get(at) ?? at) + 1, end);
+    }
+    const previous = scan.tokens[at - 1];
+    const following = scan.tokens[at + 1];
+    const spelled = token.kind === 'word'
+        ? token.text
+        : token.kind === 'string'
+            ? token.text.slice(1, -1)
+            : undefined;
+    const isKey = spelled !== undefined &&
+        (isPunct(previous, '{') || isPunct(previous, ',')) &&
+        (isPunct(following, ':') || isPunct(following, ',') || isPunct(following, '}'));
+    return [...(isKey ? [spelled] : []), ...readKeys(scan, at + 1, end)];
+}
+/**
+ * Reads the retry and timeout markers a registration's arguments carry.
+ *
+ * @param scan - The scanned source.
+ * @param spans - The registration call's top-level arguments.
+ * @returns A `timeout` entry for a numeric last argument after the title, and an entry for each
+ * `retry` or `timeout` key of an object-literal argument.
+ */
+export function readArgumentMarkers(scan, spans) {
+    const last = spans.at(-1);
+    const lastToken = last === undefined ? undefined : scan.tokens[last.start];
+    const numeric = spans.length >= 2 &&
+        last !== undefined &&
+        last.end - last.start === 1 &&
+        lastToken?.kind === 'word' &&
+        NUMBER_PATTERN.test(lastToken.text);
+    const keys = spans.flatMap((span) => isPunct(scan.tokens[span.start], '{') && scan.closes.get(span.start) === span.end - 1
+        ? readKeys(scan, span.start + 1, span.end - 1)
+        : []);
+    return [
+        ...(numeric ? ['timeout'] : []),
+        ...keys.filter((key) => key === 'retry' || key === 'timeout'),
+    ];
+}
+/**
+ * Reads the markers one registration carries.
+ *
+ * @param scan - The scanned source.
+ * @param index - The index of the registrar identifier.
+ * @returns The chain markers (`.todo`, `.skipIf`, `.runIf`, `.fails`) and the argument markers.
+ */
+export function readHits(scan, index) {
+    const chain = readChain(scan, index + 1, []);
+    if (chain === undefined)
+        return [];
+    const close = scan.closes.get(chain.call);
+    const spans = close === undefined ? [] : splitArguments(scan, chain.call + 1, chain.call + 1, close);
+    return [
+        ...chain.names.filter((name) => CHAIN_MARKERS.has(name)).map((name) => `.${name}`),
+        ...readArgumentMarkers(scan, spans),
+    ];
 }
-// Runs one read per item in order and stops at the first refusal, so no later read spawns.
-function collectReadings(items, read) {
-    return items.reduce((readings, item) => {
-        if (readings === undefined)
+/**
+ * Counts the markers a scanned test file carries, as call forms outside comments and strings.
+ *
+ * @param scan - The scanned source.
+ * @returns Each marker with a nonzero count, in marker order.
+ */
+export function readMarkers(scan) {
+    const hits = scan.tokens.flatMap((token, index) => token.kind === 'word' && REGISTRARS.has(token.text) && !isPunct(scan.tokens[index - 1], '.')
+        ? readHits(scan, index)
+        : []);
+    return Object.fromEntries(MARKERS.map((marker) => [marker, hits.filter((hit) => hit === marker).length]).filter(([, count]) => count > 0));
+}
+/**
+ * Counts the markers of a test file on disk.
+ *
+ * @param file - The test file path.
+ * @returns Each marker with a nonzero count.
+ */
+export function countMarkers(file) {
+    return readMarkers(new CodeScanner(readFileSync(file, 'utf8')).scan());
+}
+/**
+ * Runs one read per item in order and stops at the first refusal, so no later read spawns.
+ *
+ * @param items - The items to read.
+ * @param read - The read for one item; undefined refuses.
+ * @returns The readings in order, or undefined once any read refuses.
+ */
+export function collectResults(items, read) {
+    return items.reduce((results, item) => {
+        if (results === undefined)
             return undefined;
-        const reading = read(item);
-        return reading === undefined ? undefined : [...readings, reading];
+        const result = read(item);
+        return result === undefined ? undefined : [...results, result];
     }, []);
 }
-function isSameUnit(left, right) {
+/**
+ * Checks whether two units run under the same config, mode, root, and dir.
+ *
+ * @param left - The first unit.
+ * @param right - The second unit.
+ * @returns True if every field is equal.
+ */
+export function isSameUnit(left, right) {
     return (left.config === right.config &&
         left.mode === right.mode &&
         left.root === right.root &&
         left.dir === right.dir);
 }
-function readUnit(unit, named, gates, cache) {
+/**
+ * Builds the arguments that select a unit's config, mode, root, and dir.
+ *
+ * @param unit - The unit.
+ * @returns The arguments to pass to `vitest list`.
+ */
+export function readUnitArguments(unit) {
+    return [
+        ...(unit.config === undefined ? [] : ['--config', unit.config]),
+        ...(unit.mode === undefined ? [] : ['--mode', unit.mode]),
+        ...(unit.root === undefined ? [] : ['--root', unit.root]),
+        ...(unit.dir === undefined ? [] : ['--dir', unit.dir]),
+    ];
+}
+/**
+ * Reads one unit's universe, gate selections, and project readings.
+ *
+ * @param unit - The unit to read.
+ * @param named - The `--projects` names; the universe and every listing carry them when present.
+ * @param gates - The narrowed gates.
+ * @param cache - The listings already read.
+ * @returns The unit's reading, or undefined when a listing refuses.
+ */
+export function readUnit(unit, named, gates, cache) {
     const reached = gates.units.filter((gate) => isSameUnit(gate, unit));
     const parameters = readUnitArguments(unit);
-    const collected = listCollected(parameters, true, cache);
-    if (collected === undefined)
+    const universeArguments = [...parameters, ...named.flatMap((name) => ['--project', name])];
+    const universe = listCollected(universeArguments, true, cache);
+    if (universe === undefined)
         return undefined;
-    const scope = named.length === 0
-        ? undefined
-        : listCollected([...parameters, ...named.flatMap((name) => ['--project', name])], false, cache);
-    if (named.length > 0 && scope === undefined)
-        return undefined;
-    const selected = collectReadings(reached, (gate) => {
-        const selection = JSON.stringify(gate.args) === JSON.stringify(parameters)
+    const collected = universe.entries;
+    const selected = collectResults(reached, (gate) => {
+        const selection = JSON.stringify(gate.args) === JSON.stringify(universeArguments)
             ? collected
-            : listCollected(gate.args, gate.full, cache);
+            : listCollected(gate.args, gate.full, cache)?.entries;
         if (selection === undefined) {
             console.error(`discovery: gate ${gate.chain}: vitest list refused ${gate.args.join(' ')}`);
             return undefined;
@@ -401,7 +1131,8 @@ function readUnit(unit, named, gates, cache) {
     });
     if (selected === undefined)
         return undefined;
-    const readings = collectReadings([...new Set([...reached.flatMap((gate) => gate.projects), ...named])].filter((project) => !project.includes('*') && !project.startsWith('!')), (project) => {
+    const candidates = named.length === 0 ? reached.flatMap((gate) => gate.projects) : named;
+    const projects = collectResults([...new Set(candidates)].filter(isConcreteName), (project) => {
         if (selected.some(({ gate, identities }) => gate.projects.length === 1 && gate.projects[0] === project && identities.size > 0)) {
             return { project, populated: true, empty: false };
         }
@@ -410,21 +1141,18 @@ function readUnit(unit, named, gates, cache) {
             return undefined;
         return {
             project,
-            populated: selection.length > 0,
-            empty: selection.length === 0 &&
+            populated: selection.entries.length > 0,
+            empty: selection.entries.length === 0 &&
                 (reached.some((gate) => gate.projects.includes(project)) || named.includes(project)) &&
                 (named.length === 0 || named.includes(project)),
         };
     });
-    if (readings === undefined)
+    if (projects === undefined)
         return undefined;
     return {
         listing: {
             ...unit,
-            collected: collected
-                .filter((entry) => scope === undefined ||
-                scope.some((chosen) => chosen.file === entry.file && chosen.projectName === entry.projectName))
-                .map((entry) => ({
+            collected: collected.map((entry) => ({
                 ...entry,
                 gate: selected.find(({ gate, identities }) => identities.has(JSON.stringify([
                     entry.file,
@@ -432,25 +1160,93 @@ function readUnit(unit, named, gates, cache) {
                     ...(gate.full ? [entry.name, entry.line, entry.column] : []),
                 ])))?.gate.chain,
             })),
-            empty: readings.filter(({ empty }) => empty).map(({ project }) => project),
+            empty: projects.filter(({ empty }) => empty).map(({ project }) => project),
         },
-        populated: readings.filter(({ populated }) => populated).map(({ project }) => project),
+        populated: projects.filter(({ populated }) => populated).map(({ project }) => project),
     };
 }
-function readUnitArguments(unit) {
-    return [
-        ...(unit.config === undefined ? [] : ['--config', unit.config]),
-        ...(unit.mode === undefined ? [] : ['--mode', unit.mode]),
-        ...(unit.root === undefined ? [] : ['--root', unit.root]),
-        ...(unit.dir === undefined ? [] : ['--dir', unit.dir]),
+/**
+ * Reads the listing of every unit the narrowed gates reach.
+ *
+ * @param config - The base config path.
+ * @param named - The `--projects` names.
+ * @param gates - The narrowed gates.
+ * @returns One listing per unit, or undefined when a listing refuses.
+ */
+export function collectListings(config, named, gates) {
+    const base = { config, mode: undefined };
+    // A gate joins the units unless the base unit or an earlier gate already names the same unit.
+    const units = [
+        base,
+        ...gates.units
+            .filter((gate, index) => ![base, ...gates.units.slice(0, index)].some((unit) => isSameUnit(unit, gate)))
+            .map((gate) => ({
+            config: gate.config,
+            mode: gate.mode,
+            ...(gate.root === undefined ? {} : { root: gate.root }),
+            ...(gate.dir === undefined ? {} : { dir: gate.dir }),
+        })),
     ];
+    // A listing is a memo keyed by its arguments: each key is written once, on its first miss.
+    const cache = new Map();
+    const results = collectResults(units, (unit) => readUnit(unit, named, gates, cache));
+    if (results === undefined)
+        return undefined;
+    const listings = results.map(({ listing }) => listing);
+    const populated = new Set(results.flatMap((result) => result.populated));
+    // A project empty under one unit may still list tests under another, so each unit is asked for it.
+    const rescans = collectResults([...new Set(listings.flatMap((listing) => listing.empty))]
+        .filter((name) => !populated.has(name))
+        .flatMap((name) => units.map((unit) => ({ name, unit }))), ({ name, unit }) => {
+        const selection = listCollected([...readUnitArguments(unit), '--project', name], false, cache);
+        return selection === undefined ? undefined : { name, listed: selection.entries.length > 0 };
+    });
+    if (rescans === undefined)
+        return undefined;
+    const resolved = new Set([
+        ...populated,
+        ...rescans.filter(({ listed }) => listed).map(({ name }) => name),
+    ]);
+    return listings.map((listing) => ({
+        ...listing,
+        empty: listing.empty.filter((name) => !resolved.has(name)),
+    }));
+}
+/**
+ * Names the `--projects` entries the base config's projects do not match.
+ *
+ * @param unit - The base unit.
+ * @param named - The `--projects` names.
+ * @param cache - The listings already read.
+ * @returns The names Vitest matched to no project, or undefined when a listing refuses.
+ */
+export function readUnmatched(unit, named, cache) {
+    const matches = collectResults(named, (name) => {
+        const listed = listCollected([...readUnitArguments(unit), '--project', name], false, cache);
+        return listed === undefined ? undefined : { name, matched: listed.matched };
+    });
+    return matches?.filter(({ matched }) => !matched).map(({ name }) => name);
 }
-function identifyCollected(entry) {
+/**
+ * Identifies a collected test by its file, project, name, and location.
+ *
+ * @param entry - The collected test.
+ * @returns A key two listings share for the same test.
+ */
+export function identifyCollected(entry) {
     return JSON.stringify([entry.file, entry.projectName, entry.name, entry.line, entry.column]);
 }
-// The same test listed twice in one listing is two occurrences, and the same occurrence listed by
-// two listings is one test: the last listing's fields win, and the gate is the last one any named.
-function mergeCollected(listings) {
+/**
+ * Merges the tests of several listings into one list.
+ *
+ * @remarks
+ * The same test listed twice in one listing is two occurrences, and the same occurrence listed by
+ * two listings is one test: the last listing's fields win, and the gate is the last one any named.
+ *
+ * @param listings - The listings to merge.
+ * @returns The merged tests.
+ */
+export function mergeCollected(listings) {
     const keyed = listings.flatMap((listing) => {
         const positions = new Map([...Map.groupBy(listing.collected, identifyCollected).values()].flatMap((group) => group.map((entry, position) => [entry, position + 1])));
         return listing.collected.map((entry) => ({
@@ -470,7 +1266,13 @@ function mergeCollected(listings) {
             ];
     });
 }
-function readSnapshot(gates) {
+/**
+ * Reads the modification times of every test file the census can collect.
+ *
+ * @param gates - The narrowed gates, whose roots and dirs add watched directories.
+ * @returns A JSON text two reads share when no test file changed.
+ */
+export function readSnapshot(gates) {
     const bases = [
         process.cwd(),
         ...gates.units.flatMap((gate) => [gate.root, gate.dir].filter((path) => path !== undefined).map((path) => resolve(path))),
@@ -479,12 +1281,22 @@ function readSnapshot(gates) {
     // A later listing of the same path replaces the earlier modification time at the earlier position.
     const files = new Map([...roots].flatMap((root) => existsSync(root)
         ? listFiles(root)
-            .filter((file) => /\.test\.[cm]?[jt]sx?$/u.test(file.path))
+            .filter((file) => TEST_FILE_PATTERN.test(file.path))
             .map((file) => [file.path, file.modified])
         : []));
     return JSON.stringify([...files].sort(([left], [right]) => left.localeCompare(right)));
 }
-function collectStableListings(config, named, gates, attempt = 0) {
+/**
+ * Reads the listings, repeating once when a test file changed during the first read.
+ *
+ * @param config - The base config path.
+ * @param named - The `--projects` names.
+ * @param gates - The narrowed gates.
+ * @param attempt - The attempt number, zero for the first.
+ * @returns One listing per unit, or undefined when a listing refuses.
+ * @throws Thrown when test files changed during both attempts.
+ */
+export function collectStableListings(config, named, gates, attempt = 0) {
     const before = readSnapshot(gates);
     const listings = collectListings(config, named, gates);
     if (before === readSnapshot(gates))
@@ -493,7 +1305,18 @@ function collectStableListings(config, named, gates, attempt = 0) {
         throw new Error('Test files changed during both census attempts');
     return collectStableListings(config, named, gates, attempt + 1);
 }
-function main(argv) {
+/**
+ * Runs the census and prints its report.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 no flag, 3 a flag, 2 a tool failure, 64 usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`discovery: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, ['--config', '--projects']);
     if (missing.length > 0) {
         console.error(`discovery: ${missing.join(', ')} given with no value`);
@@ -501,16 +1324,38 @@ function main(argv) {
     }
     const config = readOption(argv, '--config') ?? 'vite.config.ts';
     if (!existsSync(config) || !existsSync('package.json')) {
-        console.error('usage: discovery.ts [--config vite.config.ts] [--projects a,b] [--json]');
+        console.error(USAGE);
         return 64;
     }
     if (!existsSync(VITEST)) {
         console.error(`discovery: ${VITEST} is missing; run npm ci first`);
         return 2;
     }
-    const canonical = relative(process.cwd(), resolve(config)).split('\\').join('/');
-    const gates = readGates(readScripts(), canonical, readCLIOptions());
-    const named = (readOption(argv, '--projects') ?? '').split(',').filter((name) => name !== '');
+    const canonical = normalizeSlashes(relative(process.cwd(), resolve(config)));
+    const options = readCLIOptions();
+    const absent = readMissingOptions(options);
+    if (absent.length > 0) {
+        console.error(`discovery: Vitest ${readVitestVersion()} lists no ${absent.join(', ')} option; the help layout this script reads has changed`);
+        return 2;
+    }
+    const named = [
+        ...new Set((readOption(argv, '--projects') ?? '').split(',').filter((name) => name !== '')),
+    ];
+    const read = readGates(readScripts(), canonical, options);
+    if (named.length > 0) {
+        const base = { config: canonical, mode: undefined };
+        const cache = new Map();
+        const unmatched = readUnmatched(base, named, cache);
+        if (unmatched === undefined) {
+            console.error('discovery: vitest list failed');
+            return 2;
+        }
+        if (unmatched.length > 0) {
+            console.error(`discovery: --projects ${unmatched.map(describeName).join(', ')} matches no project in ${describeName(canonical)}; run without --projects to list every project that collects tests, since naming them here would collect the projects outside the set`);
+            return 64;
+        }
+    }
+    const gates = { ...read, units: narrowGates(read.units, named) };
     const listings = collectStableListings(canonical, named, gates);
     if (listings === undefined) {
         console.error('discovery: vitest list failed');
@@ -594,10 +1439,12 @@ function main(argv) {
     }
     return flagged ? 3 : 0;
 }
-try {
-    process.exitCode = main(process.argv.slice(2));
-}
-catch (error) {
-    console.error(`discovery: ${error instanceof Error ? error.message : String(error)}`);
-    process.exitCode = 2;
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    try {
+        process.exitCode = main(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(`discovery: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 2;
+    }
 }