Files
plan2code/src/skill-scripts/test-map.mjs
T

354 lines
15 KiB
JavaScript

#!/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 section body's link into .agents-docs/ (`docs`, the path under it);
* with none, `outside` holds the first other relative .md link.
*/
function linkIn(lines, fenced, start, end) {
let outside = null;
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 };
outside ??= target;
}
}
return outside === null ? null : { outside };
}
/**
* 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) };
}
/**
* One rendered row line (`| Area | Paths | Run | Shared |`) read back into
* `{ area, paths, run, shared }`, unchecked: pass it to validRows. Null when
* the line is not four cells or Shared is neither yes nor no.
*/
export function rowFromLine(line) {
if (typeof line !== "string" || /[\r\n]/.test(line.trim())) return null;
const cells = cellsOf(line);
if (cells.length !== COLUMNS.length) return null;
const [area, paths, run, shared] = cells;
if (!/^(?:yes|no)$/i.test(shared)) return null;
return { area, paths: splitPaths(paths), run: unquote(run), shared: /^yes$/i.test(shared) };
}
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"} |`),
];
}
/** Validate rows as `write` does: exit 4 `invalid-rows` naming the first bad row. Returns the cleaned rows. */
export 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");
// A backtick or line break would break the table; an unsupported glob
// would be written, then dropped by the next read.
if ([r.area, r.run, ...r.paths].some((s) => /[`\r\n]/.test(s))) bad("has a backtick or line break in a cell");
for (const p of r.paths) {
const why = unsupported(p.trim());
if (why) bad(`has an unsupported glob "${p.trim()}": ${why}`);
}
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`. */
export 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] && !/^#{1,6}(\s|$)/.test(lines[i])) {
while (i < section.end && lines[i].trim() !== "") i++;
at = i;
}
return insertAt(lines, at, table).join(nl);
}
/** The file a map's table is written to: the linked .agents-docs/ file, or AGENTS.md. */
export function tableFile(root, map) {
return map.source && map.source !== "AGENTS.md" ? map.file : path.join(root, "AGENTS.md");
}
/**
* The splice: the new text of the map's file (`current`, null when a linked
* file does not exist yet) with `table` in place. Every line outside the table
* stays byte-identical.
*/
export function spliceTable(root, map, current, table) {
if (map.source && map.source !== "AGENTS.md") {
if (current === null) {
return ["# Test map", "", `> Part of [AGENTS.md](${"../".repeat(map.source.split("/").length - 1)}AGENTS.md): which checks cover which files.`, "", ...table, ""].join(eol(readText(path.join(root, "AGENTS.md")) || "\n"));
}
return placeIn(current, table, { linked: true });
}
return placeIn(current, table, { linked: false });
}
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 file = tableFile(root, map);
const next = spliceTable(root, map, readText(file), renderTable(rows));
const source = map.source && map.source !== "AGENTS.md" ? 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);