readfirst 0.1.1 → 0.2.0

package/README.md

@@ -6,29 +6,7 @@ Coding agents can follow imports. What they don't know is what your team knows:
 "this table is read by the mobile app, keep old columns", "run the payment e2e after touching this". readfirst keeps that
 knowledge in one file next to the code and hands it out, file by file, at the moment someone is about to change something.
 
-```text
-$ npx readfirst read src/billing/charge.ts
-
-# Read first: `src/billing/charge.ts`
-
-## Rules that must keep holding
-- **no-double-charge**: a charge runs once per order — why: refunds are manual
-
-## Watch out
-- amounts are in cents _(group src-billing)_
-
-## Run these checks
-- `npm test -- billing` — charges
-- `npm run e2e:pay` — keeps rule no-double-charge
-
-## Tests that reach this code
-- `test/charge.test.ts`
-- `test/route.test.js` (through `src/api/route.js`)
-
-## Used by
-- `src/billing/index.ts:1`
-2 more file(s) use this code indirectly.
-```
+![npx readfirst read src/imports.mjs prints the rules, risks, checks, tests and callers for that file](docs/readfirst-read.gif)
 
 No server, no account, no model calls. It reads your git checkout and `.readfirst/map.json`.
 
@@ -46,6 +24,7 @@ Commit `.readfirst/map.json`. From then on:
 npx readfirst read <file>...     # before changing files
 npx readfirst diff               # everything your branch changed since main
 npx readfirst diff --json        # the same, for tools and agents
+npx readfirst fix                # after moving code: place new files, drop patterns for deleted ones
 ```
 
 ### Tell your agent to use it
@@ -80,7 +59,7 @@ Each PR gets one comment, updated on every push, that lists:
 - the tests that reach the changed code.
 
 The check fails when `.readfirst/map.json` no longer covers the code, for example when a new file is in no group. So the
-map is fixed in the same PR.
+map is fixed in the same PR. The comment lists what `npx readfirst fix` would change, so the fix is usually one command.
 
 | Input | Default | Meaning |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "What to read and check before you (or your AI agent) change a file: project rules, risks and tests tied to code.",
   "type": "module",
   "license": "MIT",

package/src/action.mjs

@@ -4,7 +4,7 @@
 import { appendFileSync, readFileSync } from 'node:fs';
 import { readMapFile, readText, repoFiles } from './cli.mjs';
 import { importEdges } from './imports.mjs';
-import { MAP_PATH, mapProblems } from './map.mjs';
+import { fixMap, MAP_PATH, mapProblems } from './map.mjs';
 import { readList, toMarkdown } from './readlist.mjs';
 
 export const MARKER = '<!-- readfirst:pr-comment -->';
@@ -30,11 +30,12 @@ async function pages(fetchImpl, env, path) {
   return all;
 }
 
-export function commentBody({ list, problems, removed, commit }) {
+export function commentBody({ list, problems, removed, commit, fixes = [] }) {
   const parts = [MARKER, '## readfirst', ''];
   if (problems.length) {
     parts.push(`> [!WARNING]\n> \`${MAP_PATH}\` no longer matches the code (${problems.length} problem${problems.length > 1 ? 's' : ''}). Run \`npx readfirst check\` and fix the map in this PR.`, '');
     parts.push(...problems.slice(0, 20).map((p) => `- ${p}`), ...(problems.length > 20 ? [`- …and ${problems.length - 20} more`] : []), '');
+    if (fixes.length) parts.push('`npx readfirst fix` would make these changes:', ...fixes.slice(0, 10).map((f) => `- ${f}`), ...(fixes.length > 10 ? [`- …and ${fixes.length - 10} more`] : []), '');
   }
   if (list) parts.push(toMarkdown(list, { checklist: true, heading: null }));
   else if (!problems.length) parts.push('No changed files to look up.', '');
@@ -66,7 +67,8 @@ export async function runAction({ env = process.env, fetchImpl = fetch, root = e
   const list = targets.length && !problems.length
     ? readList({ map, files, imports: importEdges(files, readText(root)), targets, commit: pr.head?.sha ?? null, limit: Number(env.INPUT_LIMIT || 30) })
     : null;
-  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null });
+  const fixes = problems.length ? (() => { try { return fixMap(map, files).changes; } catch { return []; } })() : [];
+  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null, fixes });
   summary(body);
 
   if ((env.INPUT_COMMENT ?? 'true') !== 'false') {

package/src/cli.mjs

@@ -2,6 +2,7 @@
 //   readfirst init                 write a first .readfirst/map.json from the file tree
 //   readfirst prompt               the brief for a coding agent to fill in titles, checks, risks and rules
 //   readfirst check                the map covers every tracked file and is well formed
+//   readfirst fix                  place new files and drop patterns for deleted ones, then check
 //   readfirst read <file>...       the read list for files you are about to change
 //   readfirst diff [--base <ref>]  the read list for the files changed since <ref> (default: origin/main, else main)
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
@@ -9,7 +10,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { importEdges } from './imports.mjs';
-import { assertMap, draftMap, MAP_PATH, mapProblems } from './map.mjs';
+import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
@@ -18,6 +19,7 @@ const HELP = `readfirst — what to read and check before changing a file
   readfirst init                 write a first ${MAP_PATH} from the file tree
   readfirst prompt               brief for your coding agent to fill in the map
   readfirst check                check the map covers every tracked file
+  readfirst fix                  place new files, drop patterns for deleted ones
   readfirst read <file>...       read list for files you are about to change
   readfirst diff [--base <ref>]  read list for files changed since <ref>
 
@@ -96,6 +98,16 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     else io.out(problems.length ? `${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}\n` : `${MAP_PATH} is good: ${files.length} files.\n`);
     return problems.length ? 1 : 0;
   }
+  if (cmd === 'fix') {
+    const { map, changes, problems } = fixMap(readMapFile(root), files);
+    if (changes.length) writeFileSync(join(root, MAP_PATH), `${JSON.stringify(map, null, 2)}\n`);
+    if (args.json) io.out(`${JSON.stringify({ ok: !problems.length, changes, problems }, null, 2)}\n`);
+    else {
+      io.out(changes.length ? `updated ${MAP_PATH}:\n- ${changes.join('\n- ')}\n` : 'nothing to fix automatically.\n');
+      io.out(problems.length ? `still to fix by hand:\n- ${problems.join('\n- ')}\n` : `${MAP_PATH} is good: ${files.length} files.\n`);
+    }
+    return problems.length ? 1 : 0;
+  }
   if (cmd === 'read' || cmd === 'diff') {
     const map = loadMap(root, files);
     let targets = rest;

package/src/map.mjs

@@ -161,3 +161,59 @@ export function draftMap(files) {
   }
   return { format: MAP_FORMAT, groups: [...groups.values()].sort((a, b) => a.id.localeCompare(b.id)), rules: [], ignore: [...ignore].sort() };
 }
+
+// Repairs the two ways a good map goes stale as code moves, without guessing at meaning:
+// - a tracked file in no group joins the group of its nearest neighbour (same folder, else the closest parent folder);
+//   a new folder whose files are all unplaced joins as "<folder>/**", a lone new file by its path;
+// - a pattern that no longer matches any file is dropped (from a group, a risk or a rule), unless it is the last one.
+// What it cannot decide (a file with no placed neighbour, a group or rule left with no files) stays for a person.
+// Returns the fixed map, the changes as sentences, and the problems still left.
+export function fixMap(map, files) {
+  const out = structuredClone(map);
+  const changes = [];
+  const live = (pat) => files.some(matcher([pat]));
+  for (const g of out.groups) {
+    const keep = g.files.filter(live);
+    for (const pat of g.files.filter((p) => !live(p))) {
+      if (keep.length) changes.push(`groups.${g.id}: dropped ${pat} (matches no file)`);
+    }
+    if (keep.length) g.files = keep;
+    for (const r of g.risks ?? []) if (Array.isArray(r.files)) {
+      const k = r.files.filter(live);
+      for (const pat of r.files.filter((p) => !live(p))) changes.push(`groups.${g.id} risk "${r.text.slice(0, 40)}": dropped ${pat}`);
+      if (k.length) r.files = k; else delete r.files;
+    }
+  }
+  for (const r of out.rules ?? []) {
+    const keep = r.files.filter(live);
+    for (const pat of r.files.filter((p) => !live(p))) if (keep.length) changes.push(`rules.${r.id}: dropped ${pat} (matches no file)`);
+    if (keep.length) r.files = keep;
+  }
+
+  const ignored = matcher(out.ignore ?? []);
+  const owner = (f) => out.groups.find((g) => matcher(g.files)(f));
+  const unplaced = files.filter((f) => f !== MAP_PATH && !ignored(f) && !owner(f));
+  const dir = (f) => (f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '');
+  const placedIn = (d) => files.filter((f) => f !== MAP_PATH && dir(f) === d && owner(f));
+  const doneDirs = new Set();
+  for (const f of unplaced) {
+    if (owner(f)) continue; // placed by a folder pattern added earlier in this loop
+    // The nearest folder, going up, that holds a placed file decides the group.
+    let d = dir(f);
+    let neighbours = placedIn(d);
+    while (!neighbours.length && d) { d = dir(d); neighbours = placedIn(d); }
+    if (!neighbours.length) continue;
+    const counts = new Map();
+    for (const n of neighbours) { const g = owner(n); counts.set(g, (counts.get(g) ?? 0) + 1); }
+    const group = [...counts].sort((a, b) => b[1] - a[1])[0][0];
+    // A whole new folder (nothing in it or under it placed or ignored) joins as one pattern.
+    const own = dir(f);
+    const under = files.filter((x) => x.startsWith(`${own}/`));
+    const fresh = own && own !== d && !doneDirs.has(own) && under.every((x) => unplaced.includes(x));
+    const pat = fresh ? `${own}/**` : f;
+    if (fresh) doneDirs.add(own);
+    group.files.push(pat);
+    changes.push(`groups.${group.id}: added ${pat}`);
+  }
+  return { map: out, changes, problems: mapProblems(out, files) };
+}