Add the test map reader and two-way test matcher scripts

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-03 20:53:42 -08:00
1 parent e681d1f70d
commit aecc3afb4c
11 files changed
+1647 -27

No files matched your search

+109
View File
@@ -0,0 +1,109 @@
// glob.mjs: the small glob subset the test map uses, as RegExps.
//
// A library, no CLI. The test map's Paths cells hold globs, and every script
// that reads them (test-map.mjs, test-match.mjs) matches them the same way:
//
// ** any number of path segments, including none
// * any characters except /
// ? one character except /
// {a,b} alternation, no nesting
//
// Everything else is literal. unsupported() names anything outside the subset
// so the test map can report it instead of matching it wrongly. Paths are
// forward-slash normalized; on Windows both sides are lower-cased, as file
// names there are case-insensitive.
const FOLD = process.platform === "win32";
const fold = (s) => (FOLD ? s.toLowerCase() : s);
/** Backslashes to /, a leading ./ dropped. */
export function toPosix(p) {
return String(p).replace(/\\/g, "/").replace(/^(\.\/)+/, "");
}
/** A reason string for a glob outside the subset, or null when it is supported. */
export function unsupported(glob) {
const g = String(glob);
if (!g.trim()) return "empty glob";
if (/[[\]]/.test(g)) return "character classes ([...]) are not supported";
if (g.startsWith("!")) return "negation (!) is not supported";
if (g.includes("***")) return "*** is not a glob; use ** for any folders";
let depth = 0;
for (const ch of g) {
if (ch === "{") {
if (++depth > 1) return "nested braces are not supported";
} else if (ch === "}") {
if (--depth < 0) return "a } has no matching {";
}
}
if (depth !== 0) return "a { has no matching }";
return null;
}
const escape = (s) => s.replace(/[.+^$()|\\/]/g, "\\$&");
// One alternative's text (no braces) to RegExp source.
function plain(text) {
let src = "";
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === "*") {
if (text[i + 1] === "*") {
const before = i === 0 || text[i - 1] === "/";
const after = i + 2 === text.length || text[i + 2] === "/";
if (before && after) {
if (text[i + 2] === "/") {
src += "(?:[^/]*/)*"; // **/ : any folders, including none
i += 2;
} else if (i > 0) {
src = src.replace(/\\\/$/, "") + "(?:/.*)?"; // /** at the end: the folder and everything in it
i += 1;
} else {
src += ".*"; // a lone **
i += 1;
}
continue;
}
i += 1; // ** inside a segment reads as *
}
src += "[^/]*";
} else if (ch === "?") src += "[^/]";
else src += escape(ch);
}
return src;
}
/** The glob as an anchored RegExp. Throws on a glob unsupported() rejects. */
export function globToRegExp(glob) {
const why = unsupported(glob);
if (why) throw new Error(`Unsupported glob "${glob}": ${why}`);
const g = fold(toPosix(glob));
let src = "";
let i = 0;
while (i < g.length) {
const open = g.indexOf("{", i);
if (open === -1) {
src += g.slice(i);
break;
}
src += g.slice(i, open);
const close = g.indexOf("}", open);
src += `\u0000${g.slice(open + 1, close)}\u0001`;
i = close + 1;
}
// Brace groups are marked with \0 ... \1 so the text around them converts
// as one piece (a ** next to a brace still sees its neighbors).
const parts = src.split(/(\u0000[^\u0001]*\u0001)/);
let out = "";
for (const part of parts) {
if (part.startsWith("\u0000")) out += `(?:${part.slice(1, -1).split(",").map(plain).join("|")})`;
else out += plain(part);
}
return new RegExp(`^${out}$`);
}
/** Does the path match the glob? Unsupported globs match nothing. */
export function matchGlob(glob, p) {
if (unsupported(glob)) return false;
return globToRegExp(glob).test(fold(toPosix(p)));
}
+323
View File
@@ -0,0 +1,323 @@
#!/usr/bin/env node
// test-map.mjs: read and write the project test map.
//
// The test map is one Markdown table under a `## Test map` heading in
// AGENTS.md, or in .agents-docs/AGENTS-test-map.md behind one link from that
// section: `| Area | Paths | Run | Shared |`. It tells pr-prep and test which
// checks cover which files. Parsing it, validating its globs and rewriting it
// without touching any other line are mechanical, so they live here; what goes
// in the rows is the agent's call.
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { EXIT, fail, out, parseArgs, run, readText, writeIfChanged, eol } from "./common.mjs";
import { toPosix, unsupported } from "./glob.mjs";
const USAGE = `
test-map.mjs: the project test map (## Test map in AGENTS.md). JSON on stdout.
node test-map.mjs read [--root <dir>]
The table's rows: { area, paths[], run, shared }, read from AGENTS.md
or from the one .agents-docs/ file its Test map section links to.
found is false when AGENTS.md has no ## Test map heading. problems lists
what could not be read (a missing column, an unsupported glob, a Shared
value that is not yes or no, a link outside .agents-docs/).
node test-map.mjs write --rows <file.json> [--dry-run] [--root <dir>]
Write the table from a JSON array of { area, paths: [..], run, shared }.
An existing table is replaced in place, a heading with no table gets
one, and no heading appends a ## Test map section to AGENTS.md. Every
line outside the table stays byte-identical.
Globs: ** (any folders), * and ? (within one folder), {a,b}. Anything else is
a problem and matches nothing.
Exit: 0 ok (check "found") · 2 bad arguments · 3 no AGENTS.md, or no --rows
file · 4 invalid rows · 5 refused: the section links outside .agents-docs/.
`;
const HEADING = /^## +test map\s*$/i;
const FENCE = /^\s*(```|~~~)/;
const COLUMNS = ["area", "paths", "run", "shared"];
/** Split text into lines, keeping track of which sit inside a code fence. */
function linesOf(text) {
const lines = text.split(/\r?\n/);
let inFence = false;
const fenced = lines.map((l) => {
if (FENCE.test(l)) {
inFence = !inFence;
return true;
}
return inFence;
});
return { lines, fenced };
}
/** The Test map section: heading line index and body [start, end) line range. */
function findSection(lines, fenced) {
const at = lines.findIndex((l, i) => !fenced[i] && HEADING.test(l));
if (at === -1) return null;
let end = lines.length;
for (let i = at + 1; i < lines.length; i++) {
if (!fenced[i] && /^#{1,2} /.test(lines[i])) {
end = i;
break;
}
}
return { heading: at, start: at + 1, end };
}
const isRow = (l) => /^\s*\|/.test(l);
const isSeparator = (l) => /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/.test(l);
/** The first table between start and end, outside fences: [start, end) or null. */
function findTable(lines, fenced, start, end) {
for (let i = start; i < end - 1; i++) {
if (fenced[i] || !isRow(lines[i]) || !isSeparator(lines[i + 1])) continue;
let j = i + 2;
while (j < end && !fenced[j] && isRow(lines[j])) j++;
return { start: i, end: j };
}
return null;
}
/** Cells of one table row; `\|` stays inside its cell as `|`. */
function cellsOf(line) {
let s = line.trim();
if (s.startsWith("|")) s = s.slice(1);
if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
const cells = [];
let cur = "";
for (let i = 0; i < s.length; i++) {
if (s[i] === "\\" && s[i + 1] === "|") {
cur += "|";
i++;
} else if (s[i] === "|") {
cells.push(cur.trim());
cur = "";
} else cur += s[i];
}
cells.push(cur.trim());
return cells;
}
const unquote = (s) => (s.length >= 2 && s.startsWith("`") && s.endsWith("`") ? s.slice(1, -1).trim() : s);
/** A Paths cell split on commas outside braces and backticks. */
function splitPaths(cell) {
const parts = [];
let cur = "";
let depth = 0;
let tick = false;
for (const ch of cell) {
if (ch === "`") tick = !tick;
else if (!tick && ch === "{") depth++;
else if (!tick && ch === "}") depth = Math.max(0, depth - 1);
if (ch === "," && depth === 0 && !tick) {
parts.push(cur);
cur = "";
} else cur += ch;
}
parts.push(cur);
return parts.map((p) => unquote(p.trim())).filter(Boolean);
}
/** Rows and problems from the table's lines. */
function parseTable(lines, table) {
const problems = [];
const header = cellsOf(lines[table.start]).map((c) => c.toLowerCase());
const index = Object.fromEntries(COLUMNS.map((c) => [c, header.indexOf(c)]));
const missing = COLUMNS.filter((c) => index[c] === -1);
if (missing.length) {
const names = missing.map((c) => c[0].toUpperCase() + c.slice(1));
return { rows: [], problems: [`The test map table has no ${names.join(", ")} column${names.length > 1 ? "s" : ""}; no rows were read`] };
}
const rows = [];
for (let i = table.start + 2; i < table.end; i++) {
const cells = cellsOf(lines[i]);
if (cells.every((c) => !c)) continue;
const n = rows.length + 1;
const area = cells[index.area] || "";
const label = `Row ${n}${area ? ` (${area})` : ""}`;
const paths = [];
for (const glob of splitPaths(cells[index.paths] || "")) {
const why = unsupported(glob);
if (why) problems.push(`${label}: path "${glob}" was dropped: ${why}`);
else paths.push(toPosix(glob));
}
const sharedCell = (cells[index.shared] || "").trim();
const yes = /^yes$/i.test(sharedCell);
if (!yes && !/^no$/i.test(sharedCell)) problems.push(`${label}: Shared is "${sharedCell}", not yes or no; read as no`);
rows.push({ area, paths, run: unquote(cells[index.run] || ""), shared: yes });
}
return { rows, problems };
}
/**
* The first relative .md link in the section body. `docs` is the path under
* .agents-docs/ when it points there, else `outside` holds the target.
*/
function linkIn(lines, fenced, start, end) {
for (let i = start; i < end; i++) {
if (fenced[i]) continue;
for (const m of lines[i].matchAll(/\]\(([^)\s]+)\)/g)) {
const target = m[1].replace(/#.*$/, "");
if (/^[a-z][a-z0-9+.-]*:/i.test(target) || !/\.md$/i.test(target)) continue;
const norm = path.posix.normalize(toPosix(target));
if (/^\.agents-docs\/[^/]+\.md$/i.test(norm)) return { docs: norm };
return { outside: target };
}
}
return null;
}
/**
* The test map of the project at `root`. Never throws for a missing map:
* `agentsMd` false means there is no AGENTS.md, `found` false no heading.
* `file` is the absolute path the table lives in (or would be written to).
*/
export function readTestMap(root) {
const agentsFile = path.join(root, "AGENTS.md");
const text = readText(agentsFile);
if (text === null) return { agentsMd: false, found: false, source: null, rows: [], problems: [] };
const { lines, fenced } = linesOf(text);
const section = findSection(lines, fenced);
if (!section) return { agentsMd: true, found: false, source: null, rows: [], problems: [] };
const link = linkIn(lines, fenced, section.start, section.end);
if (link && link.outside) {
return { agentsMd: true, found: true, source: "AGENTS.md", rows: [], linkOutside: link.outside, problems: [`The Test map section links to ${link.outside}, outside .agents-docs/; no table was read`] };
}
if (link && link.docs) {
const file = path.join(root, link.docs);
const linked = readText(file);
if (linked === null) return { agentsMd: true, found: true, source: link.docs, file, rows: [], problems: [`The Test map section links to ${link.docs}, which does not exist`] };
const l = linesOf(linked);
const table = findTable(l.lines, l.fenced, 0, l.lines.length);
if (!table) return { agentsMd: true, found: true, source: link.docs, file, rows: [], problems: [`${link.docs} has no table`] };
return { agentsMd: true, found: true, source: link.docs, file, ...parseTable(l.lines, table) };
}
const table = findTable(lines, fenced, section.start, section.end);
if (!table) return { agentsMd: true, found: true, source: "AGENTS.md", file: agentsFile, rows: [], problems: ["The Test map section has no table"] };
return { agentsMd: true, found: true, source: "AGENTS.md", file: agentsFile, ...parseTable(lines, table) };
}
const cell = (s) => String(s).replace(/\|/g, "\\|");
/** The table's lines for `rows`. */
export function renderTable(rows) {
return [
"| Area | Paths | Run | Shared |",
"|---|---|---|---|",
...rows.map((r) => `| ${cell(r.area)} | ${r.paths.map((p) => `\`${cell(p)}\``).join(", ")} | \`${cell(r.run)}\` | ${r.shared ? "yes" : "no"} |`),
];
}
function validRows(data) {
if (!Array.isArray(data)) fail(EXIT.INVALID, "invalid-rows", "The rows file must hold a JSON array of { area, paths, run, shared }.", "Fix the rows file and run write again.");
return data.map((r, i) => {
const bad = (what) => fail(EXIT.INVALID, "invalid-rows", `Row ${i} ${what}.`, "Fix the rows file and run write again.", { row: i });
if (!r || typeof r !== "object") bad("is not an object");
if (typeof r.area !== "string" || !r.area.trim()) bad("has no area");
if (typeof r.run !== "string" || !r.run.trim()) bad("has no run command");
if (!Array.isArray(r.paths) || !r.paths.length || r.paths.some((p) => typeof p !== "string" || !p.trim())) bad("has no paths");
return { area: r.area.trim(), paths: r.paths.map((p) => toPosix(p.trim())), run: r.run.trim(), shared: r.shared === true };
});
}
// Insert `table` into `lines` at index `at`, with a blank line before it and
// one after it unless one is already there.
function insertAt(lines, at, table) {
const after = at < lines.length && lines[at] !== "" ? [""] : [];
return [...lines.slice(0, at), "", ...table, ...after, ...lines.slice(at)];
}
/** The new text of a file whose Test map section (or whole body) gets `table`. */
function placeIn(text, table, { linked }) {
const nl = eol(text);
const { lines, fenced } = linesOf(text);
if (linked) {
const t = findTable(lines, fenced, 0, lines.length);
if (t) return [...lines.slice(0, t.start), ...table, ...lines.slice(t.end)].join(nl);
const trimmed = text.replace(/(\r?\n)*$/, "");
return `${trimmed}${nl}${nl}${table.join(nl)}${nl}`;
}
const section = findSection(lines, fenced);
if (!section) {
const lead = text === "" || text.endsWith("\n") ? "" : nl;
return `${text}${lead}${nl}## Test map${nl}${nl}${table.join(nl)}${nl}`;
}
const t = findTable(lines, fenced, section.start, section.end);
if (t) return [...lines.slice(0, t.start), ...table, ...lines.slice(t.end)].join(nl);
// After the heading's first paragraph, or right under the heading.
let i = section.start;
while (i < section.end && lines[i].trim() === "") i++;
let at = section.start;
if (i < section.end && !fenced[i] && !/^#/.test(lines[i])) {
while (i < section.end && lines[i].trim() !== "") i++;
at = i;
}
return insertAt(lines, at, table).join(nl);
}
function write(root, rowsFile, dryRun) {
const raw = readText(path.resolve(rowsFile));
if (raw === null) fail(EXIT.NOT_FOUND, "no-rows-file", `No rows file at ${rowsFile}.`, "Write the rows as a JSON array to a file and pass its path to --rows.");
let data;
try {
data = JSON.parse(raw);
} catch (err) {
fail(EXIT.INVALID, "invalid-rows", `The rows file is not JSON: ${err.message}`, "Fix the rows file and run write again.");
}
const rows = validRows(data);
const map = readTestMap(root);
if (!map.agentsMd) fail(EXIT.NOT_FOUND, "no-agents-md", `No AGENTS.md in ${root}.`, "Create AGENTS.md first (Init), then write the test map.");
if (map.linkOutside) fail(EXIT.REFUSED, "link-outside", `The Test map section links to ${map.linkOutside}, outside .agents-docs/.`, "Point the link at .agents-docs/AGENTS-test-map.md, or remove it, then write again.");
const table = renderTable(rows);
const linked = map.source && map.source !== "AGENTS.md";
let file;
let next;
if (linked) {
file = map.file;
const current = readText(file);
next =
current === null
? ["# Test map", "", "> Part of [AGENTS.md](../AGENTS.md): which checks cover which files.", "", ...table, ""].join(eol(readText(path.join(root, "AGENTS.md")) || "\n"))
: placeIn(current, table, { linked: true });
} else {
file = path.join(root, "AGENTS.md");
next = placeIn(readText(file), table, { linked: false });
}
const source = linked ? map.source : "AGENTS.md";
const written = dryRun ? false : writeIfChanged(file, next);
return { ok: true, written, source, dryRun: !!dryRun };
}
async function main(argv) {
const args = parseArgs(argv, { values: ["root", "rows"], booleans: ["dry-run"] });
const root = path.resolve(args.root || ".");
const cmd = args._[0];
if (cmd === "read") {
const map = readTestMap(root);
if (!map.agentsMd) fail(EXIT.NOT_FOUND, "no-agents-md", `No AGENTS.md in ${root}.`, "There is no test map to read; offer to create AGENTS.md (Init).");
out({ ok: true, found: map.found, source: map.source, rows: map.rows, problems: map.problems });
return;
}
if (cmd === "write") {
if (!args.rows) fail(EXIT.USAGE, "missing-rows", "write needs --rows <file.json>.", "Run with --help for usage.");
out(write(root, args.rows, args["dry-run"]));
return;
}
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: read, write. Run with --help.");
}
// Run as a script; imported (by test-match.mjs), do nothing.
const isMain = (() => {
try {
return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
})();
if (isMain) run(USAGE, main);
+589
View File
@@ -0,0 +1,589 @@
#!/usr/bin/env node
// test-match.mjs: files to tests, in both directions.
//
// pr-prep asks which checks cover a branch's changed files; test asks which
// source files no test covers, and which existing tests to read for style.
// Both answers come from the same rules, in the same order: the project's
// test map first, then name, folder and import matching. Anything these rules
// cannot settle (a path alias, a bare package name) is left unmatched for the
// agent to judge, never guessed.
import fs from "node:fs";
import path from "node:path";
import { execFileSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import { EXIT, HERE, fail, out, parseArgs, run, readText, isDir, now } from "./common.mjs";
import { toPosix, matchGlob } from "./glob.mjs";
import { readTestMap } from "./test-map.mjs";
const USAGE = `
test-match.mjs: match files to tests, both ways. JSON on stdout.
node test-match.mjs covers (--files <a,b,...> | --stdin) [--root <dir>]
Changed files to the checks that cover them. --stdin takes
review-scope.mjs JSON (files[].path). matched: test map rows that cover
at least one file, in table order. unmatched: { file, tests, method }
for every file no row covers; tests and method come from the name,
folder and import rules (method null when nothing was found).
sharedHits: { file, why }: why is "row" (a Shared: yes row) or a hint
for the agent to judge ("config", "test-helper", "fixture").
node test-match.mjs gaps --scope branch|all|path [--path <p>] [--base <b>] [--root <dir>]
Source files no test covers: { file, area, runner, commits90d,
lastTouched }, newest first, then by commits in the last 90 days.
branch: the files review-scope.mjs reports; all: every tracked file;
path: every file under --path. Capped at 2,000 source files (capped).
node test-match.mjs nearest --file <f> [--root <dir>]
Up to 3 existing test files to read for the project's test style.
Exit: 0 ok · 2 bad arguments · 3 not a git repository (gaps --scope branch).
`;
/* ------------------------------------------------------------- files */
const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "vendor", "target", ".venv"]);
const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec"]);
const CODE_EXT = new Set(["js", "mjs", "cjs", "ts", "tsx", "jsx", "py", "go", "rs", "java", "kt", "cs", "rb", "php", "swift"]);
const SOURCE_SKIP = new Set(["node_modules", "vendor", "dist", "build", "target", ".venv", "specs", "specs--completed"]);
const CAP = 2000;
const fold = (s) => (process.platform === "win32" ? s.toLowerCase() : s);
const extOf = (p) => (path.posix.extname(p).slice(1) || "").toLowerCase();
const baseOf = (p) => path.posix.basename(p);
const dirOf = (p) => {
const d = path.posix.dirname(p);
return d === "." ? "" : d;
};
const segs = (d) => (d ? d.split("/") : []);
function git(root, args) {
try {
return execFileSync("git", ["-c", "core.quotePath=false", ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
} catch {
return null;
}
}
const inGit = (root) => git(root, ["rev-parse", "--show-toplevel"]) !== null;
function walk(root) {
const found = [];
const visit = (dir, relDir) => {
let entries;
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const e of entries) {
const r = relDir ? `${relDir}/${e.name}` : e.name;
if (e.isDirectory()) {
if (!SKIP_DIRS.has(e.name)) visit(path.join(dir, e.name), r);
} else if (e.isFile()) found.push(r);
}
};
visit(root, "");
return found;
}
// Every file in the project, once per run: tracked plus untracked files git
// does not ignore, or a walk outside git. Paths relative to root.
const fileLists = new Map();
function allFiles(root) {
if (!fileLists.has(root)) {
let list;
if (inGit(root)) {
const tracked = (git(root, ["ls-files"]) || "").split("\n");
const untracked = (git(root, ["ls-files", "--others", "--exclude-standard"]) || "").split("\n");
list = [...new Set([...tracked, ...untracked].filter(Boolean))].filter((f) => fs.existsSync(path.join(root, f)));
} else list = walk(root);
fileLists.set(root, list.map(toPosix).sort());
}
return fileLists.get(root);
}
/** Is this path a test file by name or by folder? */
export function isTestFile(p) {
const file = toPosix(p);
const base = baseOf(file);
if (/\.(test|spec)\.[^./]+$/i.test(base)) return true;
if (/^test_.+\.py$/i.test(base) || /_test\.py$/i.test(base) || /_test\.go$/i.test(base)) return true;
if (/Tests?\.(java|kt|cs)$/.test(base)) return true;
return segs(dirOf(file)).some((s) => TEST_DIRS.has(s));
}
/** The project's test files with a code extension. */
export function listTestFiles(root) {
return allFiles(root).filter((f) => isTestFile(f) && (CODE_EXT.has(extOf(f)) || JS_EXT.has(extOf(f))));
}
/* ------------------------------------------------------- name and folder */
// A file's name without its extension and without test markers:
// foo.test.js, test_foo.py, foo_test.go and FooTests.cs all give "foo"/"Foo".
function stemOf(p) {
const base = baseOf(p);
const dot = base.lastIndexOf(".");
let stem = dot > 0 ? base.slice(0, dot) : base;
stem = stem.replace(/\.(test|spec)$/i, "");
if (/^test_/i.test(stem) && extOf(p) === "py") stem = stem.slice(5);
stem = stem.replace(/_test$/i, "");
if (/^(java|kt|cs)$/.test(extOf(p))) stem = stem.replace(/Tests?$/, "");
return stem;
}
function nameMatch(source, test) {
const ext = extOf(source);
const stem = stemOf(source);
const base = baseOf(test);
const tdot = base.lastIndexOf(".");
const tname = tdot > 0 ? base.slice(0, tdot) : base;
const same = (a, b) => fold(a) === fold(b);
if (ext === "py") return extOf(test) === "py" && (same(tname, `test_${stem}`) || same(tname, `${stem}_test`));
if (ext === "go") return same(test, `${dirOf(source) ? `${dirOf(source)}/` : ""}${stem}_test.go`);
if (ext === "cs" || ext === "java" || ext === "kt") return extOf(test) === ext && (same(tname, `${stem}Tests`) || same(tname, `${stem}Test`));
return same(tname, `${stem}.test`) || same(tname, `${stem}.spec`);
}
// Does the test file sit in a test folder that mirrors the source file's
// folder? src/a/b.js mirrors to src/a/__tests__/, tests/a/, test/src/a/ and
// the like: the part of the path before the test folder must be an ancestor of
// the source, and the part after it the rest of the source's folder (with a
// leading src/ or lib/ optional).
function mirrors(source, test) {
const sd = segs(dirOf(source)).map(fold);
const td = segs(dirOf(test)).map(fold);
const k = td.findIndex((s) => TEST_DIRS.has(s));
if (k === -1) return false;
const prefix = td.slice(0, k);
const rest = td.slice(k + 1);
if (prefix.some((s, i) => sd[i] !== s)) return false;
const remaining = sd.slice(prefix.length);
const eq = (a, b) => a.length === b.length && a.every((s, i) => s === b[i]);
if (eq(remaining, rest)) return true;
return (remaining[0] === "src" || remaining[0] === "lib") && eq(remaining.slice(1), rest);
}
const folderMatch = (source, test) => mirrors(source, test) && fold(stemOf(source)) === fold(stemOf(test));
/* --------------------------------------------------------------- imports */
const JS_EXT = new Set(["js", "mjs", "cjs", "ts", "tsx", "jsx", "mts", "cts"]);
const JS_TRY = ["", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
const JS_PATTERNS = [
/\bimport\s+(?:[\w*{}\s,$]+?\s+from\s+)?["']([^"'\n]+)["']/g,
/\bexport\s+[\w*{}\s,$]+?\s+from\s+["']([^"'\n]+)["']/g,
/\brequire\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
/\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
];
const isFile = (p) => {
try {
return fs.statSync(p).isFile();
} catch {
return false;
}
};
// Repo-relative path for `p` (already posix, relative to root), or null when
// it climbs out of the project.
const inside = (p) => {
const n = path.posix.normalize(p);
return n === ".." || n.startsWith("../") || path.posix.isAbsolute(n) ? null : n;
};
function resolveJs(root, test, spec) {
if (!spec.startsWith("./") && !spec.startsWith("../")) return [];
const target = inside(path.posix.join(dirOf(test) || ".", spec));
if (!target) return [];
for (const ext of JS_TRY) if (isFile(path.join(root, target + ext))) return [target + ext];
for (const ext of JS_TRY.slice(1)) if (isFile(path.join(root, `${target}/index${ext}`))) return [`${target}/index${ext}`];
return [];
}
function resolvePyModule(root, bases, dotted) {
const rel = dotted.split(".").filter(Boolean).join("/");
if (!rel) return [];
for (const base of bases) {
const p = inside(base ? `${base}/${rel}` : rel);
if (!p) continue;
if (isFile(path.join(root, `${p}.py`))) return [`${p}.py`];
if (isFile(path.join(root, `${p}/__init__.py`))) return [`${p}/__init__.py`];
}
return [];
}
function pythonImports(root, test, text) {
const found = [];
const own = dirOf(test);
for (const m of text.matchAll(/^[ \t]*import[ \t]+([\w.]+(?:[ \t]*,[ \t]*[\w.]+)*)/gm)) {
for (const name of m[1].split(",")) found.push(...resolvePyModule(root, ["", own], name.trim()));
}
for (const m of text.matchAll(/^[ \t]*from[ \t]+(\.*)([\w.]*)[ \t]+import[ \t]+\(?([\w\s,]+)/gm)) {
const dots = m[1].length;
const mod = m[2];
const names = m[3].split(",").map((s) => s.trim().split(/\s+/)[0]).filter(Boolean);
let bases;
if (dots) {
let base = own;
for (let i = 1; i < dots; i++) base = dirOf(base);
bases = [base];
} else bases = ["", own];
if (mod) found.push(...resolvePyModule(root, bases, mod));
for (const n of names) found.push(...resolvePyModule(root, bases, mod ? `${mod}.${n}` : n));
}
return found;
}
// The module path and folder of the go.mod nearest to `file`, walking up.
const goMods = new Map();
function goModFor(root, file) {
let dir = dirOf(file);
for (;;) {
const key = `${root}\0${dir}`;
if (!goMods.has(key)) {
const text = readText(path.join(root, dir, "go.mod"));
const m = text && text.match(/^module\s+(\S+)/m);
goMods.set(key, m ? { module: m[1], dir } : null);
}
if (goMods.get(key)) return goMods.get(key);
if (!dir) return null;
dir = dirOf(dir);
}
}
// Go imports name packages: the result is folders, prefixed "dir:".
function goImports(root, test, text) {
const mod = goModFor(root, test);
if (!mod) return [];
const specs = [];
for (const m of text.matchAll(/^\s*import\s+(?:[\w.]+\s+)?"([^"]+)"/gm)) specs.push(m[1]);
for (const m of text.matchAll(/^\s*import\s*\(([\s\S]*?)\)/gm)) {
for (const l of m[1].matchAll(/(?:^|\n)\s*(?:[\w.]+\s+)?"([^"]+)"/g)) specs.push(l[1]);
}
const found = [];
for (const s of specs) {
if (s !== mod.module && !s.startsWith(`${mod.module}/`)) continue;
const sub = s.slice(mod.module.length).replace(/^\//, "");
const dir = inside([mod.dir, sub].filter(Boolean).join("/") || ".");
if (dir) found.push(`dir:${dir === "." ? "" : dir}`);
}
return found;
}
// Source path (or "dir:<folder>" for Go) to the test files that import it,
// built once per root from every test file.
const importIndexes = new Map();
function importIndex(root, testFiles) {
if (importIndexes.has(root)) return importIndexes.get(root);
const index = new Map();
const add = (target, test) => {
const k = fold(target);
if (!index.has(k)) index.set(k, new Set());
index.get(k).add(test);
};
for (const test of testFiles) {
const ext = extOf(test);
if (!JS_EXT.has(ext) && ext !== "py" && ext !== "go") continue;
const text = readText(path.join(root, test));
if (text === null || text.length > 2 * 1024 * 1024) continue;
if (JS_EXT.has(ext)) {
for (const re of JS_PATTERNS) for (const m of text.matchAll(re)) for (const t of resolveJs(root, test, m[1])) add(t, test);
} else if (ext === "py") for (const t of pythonImports(root, test, text)) add(t, test);
else for (const t of goImports(root, test, text)) add(t, test);
}
importIndexes.set(root, index);
return index;
}
/**
* The tests that cover `file` after the test map: by name, then by mirrored
* folder, then by imports. `{ tests, method }`, method null when none did.
*/
export function findTests(root, file, testFiles = listTestFiles(root)) {
const f = toPosix(file);
const others = testFiles.filter((t) => fold(t) !== fold(f));
const byName = others.filter((t) => nameMatch(f, t));
if (byName.length) return { tests: byName, method: "name" };
const byFolder = others.filter((t) => folderMatch(f, t));
if (byFolder.length) return { tests: byFolder, method: "folder" };
const index = importIndex(root, testFiles);
const hits = new Set([...(index.get(fold(f)) || [])]);
if (extOf(f) === "go" && !isTestFile(f)) for (const t of index.get(fold(`dir:${dirOf(f)}`)) || []) hits.add(t);
hits.delete(f);
if (hits.size) return { tests: [...hits].sort(), method: "imports" };
return { tests: [], method: null };
}
/* ---------------------------------------------------------------- covers */
const CONFIG_NAMES = new Set(["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "jsconfig.json", "pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini", "go.mod", "go.sum", "cargo.toml", "makefile", "directory.build.props"]);
/** A shared-ground hint for a file the agent should judge, or null. */
export function hintFor(file) {
const f = toPosix(file);
const base = baseOf(f);
const lower = base.toLowerCase();
const dirs = segs(dirOf(f));
if (CONFIG_NAMES.has(lower) || /^tsconfig.*\.json$/i.test(base) || /\.config\.(js|cjs|mjs|ts)$/i.test(base) || /^\.babelrc/i.test(base) || /\.csproj$/i.test(base)) return "config";
if (dirs.some((d) => ["fixtures", "__fixtures__", "testdata"].includes(d))) return "fixture";
if (dirs.some((d) => ["helpers", "test-utils", "testutils", "support"].includes(d))) return "test-helper";
if (/helpers/i.test(base) && /\.(js|mjs|ts|py|go)$/i.test(base) && dirs.some((d) => TEST_DIRS.has(d))) return "test-helper";
return null;
}
const rowMatches = (row, file) => row.paths.some((g) => matchGlob(g, file));
function covers(root, files) {
const map = readTestMap(root);
const rows = map.found ? map.rows : [];
const matched = rows.map((r) => ({ area: r.area, run: r.run, shared: r.shared, files: [] }));
const unmatched = [];
const sharedHits = [];
let testFiles;
for (const file of files) {
let hit = false;
let sharedRow = false;
rows.forEach((r, i) => {
if (!rowMatches(r, file)) return;
hit = true;
matched[i].files.push(file);
if (r.shared) sharedRow = true;
});
if (!hit) {
testFiles ||= listTestFiles(root);
const { tests, method } = findTests(root, file, testFiles);
unmatched.push({ file, tests, method });
}
const why = sharedRow ? "row" : hintFor(file);
if (why) sharedHits.push({ file, why });
}
return { ok: true, mapFound: map.found, matched: matched.filter((m) => m.files.length), unmatched, sharedHits };
}
function readStdin() {
try {
return fs.readFileSync(0, "utf8");
} catch {
return "";
}
}
/* ------------------------------------------------------------------ gaps */
/**
* The branch's changed files, relative to root: review-scope.mjs's list when
* it ships beside this script, else the same git commands it runs.
*/
export function branchFiles(root, base) {
const top = git(root, ["rev-parse", "--show-toplevel"]);
if (top === null) fail(EXIT.NOT_FOUND, "not-a-repo", `${root} is not inside a git repository.`, "Use --scope all or --scope path, or ask which files to look at.");
const prefix = (git(root, ["rev-parse", "--show-prefix"]) || "").trim();
let list;
const scope = path.join(HERE, "review-scope.mjs");
if (fs.existsSync(scope)) {
let stdout;
try {
stdout = execFileSync(process.execPath, [scope, "--root", root, ...(base ? ["--base", base] : [])], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
} catch (err) {
stdout = err.stdout;
}
let json;
try {
json = JSON.parse(stdout);
} catch {
fail(EXIT.CRASH, "review-scope-failed", "review-scope.mjs printed no JSON.", "Run review-scope.mjs on its own to see why.");
}
if (!json.ok) fail(EXIT.NOT_FOUND, json.error, json.message, json.next);
list = json.files.map((f) => f.path);
} else {
const pick = base ? [base, `origin/${base}`] : ["main", "origin/main", "master", "origin/master"];
const ref = pick.find((r) => git(root, ["rev-parse", "--verify", "--quiet", `${r}^{commit}`]) !== null);
if (base && !ref) fail(EXIT.NOT_FOUND, "no-base", `No branch named ${base} (or origin/${base}).`, "Pass an existing --base, or omit it to use main / master.");
const lines = (args) => (git(top.trim(), args) || "").split("\n").filter(Boolean);
list = [
...(ref ? lines(["diff", "--name-only", `${ref}...HEAD`]) : []),
...lines(["diff", "--name-only", "--cached"]),
...lines(["diff", "--name-only"]),
...lines(["ls-files", "--others", "--exclude-standard"]),
];
}
return [...new Set(list.map(toPosix))]
.filter((f) => f.startsWith(prefix))
.map((f) => f.slice(prefix.length))
.filter((f) => fs.existsSync(path.join(root, f)));
}
function isSource(file) {
const f = toPosix(file);
if (!CODE_EXT.has(extOf(f)) || /\.d\.ts$/i.test(f) || isTestFile(f)) return false;
return !segs(dirOf(f)).some((s) => SOURCE_SKIP.has(s));
}
// Commits in the last 90 days per file, and the newest commit time, from one
// git log read. Paths relative to root.
function churn(root) {
const prefix = (git(root, ["rev-parse", "--show-prefix"]) || "").trim();
const since = new Date(now().getTime() - 90 * 24 * 3600 * 1000).toISOString();
const text = git(root, ["log", `--since=${since}`, "--name-only", "--format=%x00%ct"]) || "";
const stats = new Map();
for (const chunk of text.split("\0")) {
const lines = chunk.split("\n");
const ts = Number(lines[0]);
if (!ts) continue;
for (const raw of new Set(lines.slice(1).filter(Boolean))) {
if (!raw.startsWith(prefix)) continue;
const f = raw.slice(prefix.length);
const s = stats.get(f) || { commits: 0, newest: 0 };
s.commits++;
s.newest = Math.max(s.newest, ts);
stats.set(f, s);
}
}
return stats;
}
function gaps(root, { scope, sub, base }) {
const repo = inGit(root);
let files;
if (scope === "branch") files = branchFiles(root, base);
else {
files = allFiles(root);
if (scope === "path") {
const p = toPosix(sub).replace(/\/+$/, "");
files = files.filter((f) => fold(f) === fold(p) || fold(f).startsWith(`${fold(p)}/`));
}
}
let sources = [...new Set(files)].filter(isSource).sort();
const capped = sources.length > CAP;
if (capped) sources = sources.slice(0, CAP);
const map = readTestMap(root);
const rows = map.found ? map.rows : [];
const testFiles = listTestFiles(root);
const stats = repo ? churn(root) : null;
const list = [];
let covered = 0;
for (const file of sources) {
// Any matching row with a run command covers the file, as in covers, so
// a gap's area is set only by a row that names it without one.
const row = rows.find((r) => rowMatches(r, file));
if (rows.some((r) => r.run && rowMatches(r, file)) || findTests(root, file, testFiles).tests.length) {
covered++;
continue;
}
const s = stats && stats.get(file);
list.push({
file,
area: row ? row.area : null,
runner: row && row.run ? row.run : null,
commits90d: stats ? (s ? s.commits : 0) : null,
lastTouched: s ? new Date(s.newest * 1000).toISOString().slice(0, 10) : null,
});
}
list.sort((a, b) => {
if (a.lastTouched !== b.lastTouched) {
if (a.lastTouched === null) return 1;
if (b.lastTouched === null) return -1;
return a.lastTouched < b.lastTouched ? 1 : -1;
}
if ((b.commits90d || 0) !== (a.commits90d || 0)) return (b.commits90d || 0) - (a.commits90d || 0);
return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
});
return { ok: true, scope, gaps: list, scanned: sources.length, covered, capped };
}
/* --------------------------------------------------------------- nearest */
// Path tokens in a Run command that name a file or folder in the project.
function runPaths(root, cmd) {
return (cmd || "")
.split(/\s+/)
.map((t) => toPosix(t.replace(/^["']|["']$/g, "")).replace(/\/+$/, ""))
.filter((t) => t && !t.startsWith("-") && inside(t) && fs.existsSync(path.join(root, t)));
}
function nearest(root, file) {
const f = toPosix(file);
const testFiles = listTestFiles(root).filter((t) => fold(t) !== fold(f));
const picked = [];
const take = (list) => {
for (const t of list) {
if (picked.length >= 3) return;
if (!picked.includes(t)) picked.push(t);
}
};
take(findTests(root, f, testFiles).tests);
take(testFiles.filter((t) => fold(dirOf(t)) === fold(dirOf(f))));
take(testFiles.filter((t) => mirrors(f, t)));
if (picked.length < 3) {
const map = readTestMap(root);
const row = map.found ? map.rows.find((r) => rowMatches(r, f)) : null;
if (row) {
for (const p of runPaths(root, row.run)) {
take(isDir(path.join(root, p)) ? testFiles.filter((t) => t.startsWith(`${p}/`)) : testFiles.filter((t) => t === p));
}
}
}
if (picked.length < 3) {
const mine = segs(dirOf(f));
const shared = (t) => {
const ts = segs(dirOf(t));
let n = 0;
while (n < mine.length && n < ts.length && fold(mine[n]) === fold(ts[n])) n++;
return n;
};
// Same language first: a Python test teaches nothing about a JS file's style.
const lang = (p) => (JS_EXT.has(extOf(p)) ? "js" : extOf(p));
const other = (t) => (lang(t) === lang(f) ? 0 : 1);
take([...testFiles].sort((a, b) => other(a) - other(b) || shared(b) - shared(a) || (a < b ? -1 : a > b ? 1 : 0)));
}
return { ok: true, file: f, tests: picked };
}
/* ------------------------------------------------------------------ main */
const listArg = (s) => String(s).split(",").map((x) => toPosix(x.trim())).filter(Boolean);
async function main(argv) {
const args = parseArgs(argv, { values: ["root", "files", "scope", "path", "base", "file"], booleans: ["stdin"] });
const root = path.resolve(args.root || ".");
const cmd = args._[0];
if (cmd === "covers") {
let files;
if (args.files) files = listArg(args.files);
else if (args.stdin) {
let json;
try {
json = JSON.parse(readStdin());
} catch {
fail(EXIT.USAGE, "bad-stdin", "--stdin needs review-scope.mjs JSON.", "Pipe review-scope.mjs output in, or pass --files.");
}
if (!json || !Array.isArray(json.files)) fail(EXIT.USAGE, "bad-stdin", "The JSON on stdin has no files list.", "Pipe review-scope.mjs output in, or pass --files.");
files = json.files.map((f) => toPosix(f.path)).filter(Boolean);
} else fail(EXIT.USAGE, "missing-files", "covers needs --files <a,b,...> or --stdin.", "Run with --help for usage.");
out(covers(root, [...new Set(files)]));
return;
}
if (cmd === "gaps") {
if (!["branch", "all", "path"].includes(args.scope)) fail(EXIT.USAGE, "bad-scope", "gaps needs --scope branch, all or path.", "Run with --help for usage.");
if (args.scope === "path" && !args.path) fail(EXIT.USAGE, "missing-path", "--scope path needs --path <p>.", "Run with --help for usage.");
out(gaps(root, { scope: args.scope, sub: args.path, base: args.base }));
return;
}
if (cmd === "nearest") {
if (!args.file) fail(EXIT.USAGE, "missing-file", "nearest needs --file <f>.", "Run with --help for usage.");
out(nearest(root, args.file));
return;
}
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: covers, gaps, nearest. Run with --help.");
}
const isMain = (() => {
try {
return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
})();
if (isMain) run(USAGE, main);
@@ -1066,9 +1066,10 @@ export function wagonArt(d) {
ctx.restore();
}
// The mob's meter along the top left: how far back they are, red as they close, with a word when it matters.
function meter(ctx, v, c) {
const x = 4;
// The mob's meter along the top left of the screen (`cam` is the view's left edge: `front` draws in
// room units, so it follows the camera): how far back they are, red as they close, with a word when it matters.
function meter(ctx, v, c, cam) {
const x = cam + 4;
const y = 9.2;
const w = 34;
const near = clamp(1 - c.gap / GAP_MAX, 0, 1);
@@ -1147,7 +1148,7 @@ export function wagonArt(d) {
ctx.fillRect(cam, 0, 40, FH);
ctx.globalAlpha = 1;
}
meter(ctx, v, c);
meter(ctx, v, c, cam);
}
}
+5
View File
@@ -508,6 +508,9 @@ function blip(c, type, from, to, t0, seconds, peak) {
osc.type = type;
osc.frequency.setValueAtTime(from, t0);
osc.frequency.exponentialRampToValueAtTime(to, end);
// Silent from the start: a gain node is 1 until its first scheduled value,
// which made a part that starts later click.
gain.gain.value = FLOOR;
gain.gain.setValueAtTime(FLOOR, t0);
gain.gain.exponentialRampToValueAtTime(peak, t0 + ATTACK);
gain.gain.exponentialRampToValueAtTime(FLOOR, end);
@@ -524,6 +527,8 @@ function voice(c, p, t0, peak, k) {
const end = t0 + p.seconds;
const gain = c.createGain();
const top = Math.max(FLOOR * 10, peak * (p.gain ?? 1));
// Silent from the start (see blip): no click before a delayed part begins.
gain.gain.value = FLOOR;
gain.gain.setValueAtTime(FLOOR, t0);
gain.gain.exponentialRampToValueAtTime(top, t0 + Math.min(p.attack ?? ATTACK, p.seconds * 0.8));
gain.gain.exponentialRampToValueAtTime(FLOOR, end);