2026-11-03 20:53:42 -08:00
#!/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 };
}
/**
2026-11-04 10:24:07 -08:00
* The section body's link into .agents-docs/ (`docs`, the path under it);
* with none, `outside` holds the first other relative .md link.
2026-11-03 20:53:42 -08:00
*/
function linkIn ( lines , fenced , start , end ) {
2026-11-04 10:24:07 -08:00
let outside = null ;
2026-11-03 20:53:42 -08:00
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 ));
2026-11-04 10:24:07 -08:00
if ( /^\.agents-docs\/.+\.md$/i . test ( norm )) return { docs : norm };
outside ??= target ;
2026-11-03 20:53:42 -08:00
}
}
2026-11-04 10:24:07 -08:00
return outside === null ? null : { outside };
2026-11-03 20:53:42 -08:00
}
/**
* 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 ) };
}
2026-11-13 23:29:12 -08:00
/**
* 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 ) };
}
2026-11-03 20:53:42 -08:00
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" } |` ),
];
}
2026-11-13 23:29:12 -08:00
/** Validate rows as `write` does: exit 4 `invalid-rows` naming the first bad row. Returns the cleaned rows. */
export function validRows ( data ) {
2026-11-03 20:53:42 -08:00
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" );
2026-11-04 10:24:07 -08:00
// 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 } `);
}
2026-11-03 20:53:42 -08:00
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 `. */
2026-11-13 23:29:12 -08:00
export function placeIn(text, table, { linked }) {
2026-11-03 20:53:42 -08:00
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;
2026-11-04 10:24:07 -08:00
if (i < section.end && !fenced[i] && !/^#{1,6}(\s|$)/.test(lines[i])) {
2026-11-03 20:53:42 -08:00
while (i < section.end && lines[i].trim() !== "") i++;
at = i;
}
return insertAt(lines, at, table).join(nl);
}
2026-11-13 23:29:12 -08:00
/** 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 });
}
2026-11-03 20:53:42 -08:00
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.");
2026-11-13 23:29:12 -08:00
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";
2026-11-03 20:53:42 -08:00
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);