readfirst 0.6.2 → 0.8.0

package/README.md

@@ -12,6 +12,8 @@ No server, no account, no model calls. It reads your git checkout and `.readfirs
 
 ## Start
 
+Any language; needs Node 20+ for `npx`.
+
 ```sh
 npx readfirst init --agent   # first map from your folders, checks from your scripts, plus the line for CLAUDE.md / AGENTS.md
 npx readfirst prompt         # a brief for your coding agent to fill in titles, checks, risks and rules
@@ -48,6 +50,18 @@ npx readfirst hook --install
 adds a hook to `.claude/settings.json`. Before each Edit or Write, Claude Code gets the rules, risks and checks for that
 file as context, once per file per session. Nothing to remember, and the edit is never blocked.
 
+Want the checks enforced, not just suggested?
+
+```sh
+npx readfirst hook --install --verify
+```
+
+also adds a Stop hook: before Claude Code finishes its turn, it runs the map's checks for the files it edited in that
+session. If one fails, Claude Code cannot finish yet and gets the failure to fix. It gets one try per turn, so a check
+it cannot fix never traps the session. It runs only check commands that the map on your main branch already lists: a
+command someone's branch adds or changes is named, not run, until it is merged (`npx readfirst verify` runs it when you
+choose to).
+
 ### See the map
 
 ```sh
@@ -109,17 +123,39 @@ Each PR gets one comment, updated on every push, that lists:
 - the rules, risks and checks for the files the PR changes, with the checks as boxes to tick;
 - 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. The comment lists what `npx readfirst fix` would change, so the fix is usually one command.
+A new file next to files the map already places joins their group without anyone touching the map: the check passes
+and the comment notes where it went (`npx readfirst fix` writes it down whenever you like). The check fails only on what
+needs a person: a new top-level folder, a rule whose files are all gone, a map that is broken in itself. The comment
+lists what `npx readfirst fix` would change.
 
 | Input | Default | Meaning |
 |---|---|---|
 | `fail-on-map-problems` | `true` | `false` reports map problems without failing |
+| `strict` | `false` | `true` also fails on new files that are only placed by their neighbours |
 | `comment` | `true` | `false` writes only the job summary |
+| `auto-fix` | `false` | `true` commits what `readfirst fix` settles (new files placed by their neighbours) to the PR branch |
 | `limit` | `30` | most tests and users listed per section |
 
 On a PR from a fork, the token is read-only. The list then goes to the job summary instead of a comment.
 
+### Keep the map in step without thinking about it
+
+```yaml
+permissions:
+  contents: write        # for auto-fix
+  pull-requests: write
+# ...
+      - uses: jeonghun917/readfirst@v0
+        with:
+          auto-fix: true
+```
+
+With `auto-fix`, when a PR adds files next to ones the map already places, the Action writes them into the map and
+commits that to the PR branch. That is the mechanical part `npx readfirst fix` does, nothing else: new risks and
+rules stay for a person. It skips PRs from forks, and it skips the commit if the branch's map changed since the run
+started, so a push is never overwritten. A commit made with the default `GITHUB_TOKEN` does not start new workflow
+runs. If your branch protection requires checks, pass a GitHub App or personal token as `token`.
+
 ## The map
 
 ```json
@@ -157,7 +193,12 @@ On a PR from a fork, the token is read-only. The list then goes to the job summa
 - **rules**: promises the code must keep. A rule can span groups.
 
 Tests are found from imports: a test that imports the file directly, or through other files, is listed.
-Imports are read for JavaScript/TypeScript (`import`, `export … from`, `import()`, `require`) and Python.
+Imports are read for JavaScript/TypeScript, Python, Go, Rust, Elixir, C#, Java, Kotlin, Ruby (including Rails autoloaded
+constants) and PHP (through composer's PSR-4 map). `init` suggests the checks those projects already have: `npm test`,
+`pytest`, `go test ./...`, `cargo test`, `mix test`, `dotnet test`, `./gradlew test` or `mvn test`, `bundle exec rspec`,
+`composer test`.
+
+readfirst needs Node 20 or newer to run, whatever language the project is in. `npx` comes with Node.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "mcpName": "io.github.jeonghun917/readfirst",
   "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",

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 { fixMap, MAP_PATH, mapProblems } from './map.mjs';
+import { MAP_PATH, settleMap } from './map.mjs';
 import { readList, toMarkdown } from './readlist.mjs';
 
 export const MARKER = '<!-- readfirst:pr-comment -->';
@@ -30,12 +30,16 @@ async function pages(fetchImpl, env, path) {
   return all;
 }
 
-export function commentBody({ list, problems, removed, commit, fixes = [] }) {
+export function commentBody({ list, problems, removed, commit, fixes = [], settled = [], committed = null }) {
   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`] : []), '');
+  } else if (committed) {
+    parts.push(`<details><summary>readfirst placed ${settled.length} new file(s) in the map and committed it to this branch (${committed.slice(0, 7)})</summary>`, '', ...settled.slice(0, 20).map((f) => `- ${f}`), ...(settled.length > 20 ? [`- …and ${settled.length - 20} more`] : []), '', 'Pull before your next push.', '</details>', '');
+  } else if (settled.length) {
+    parts.push(`<details><summary>New files placed by their neighbours (${settled.length})</summary>`, '', ...settled.slice(0, 20).map((f) => `- ${f}`), ...(settled.length > 20 ? [`- …and ${settled.length - 20} more`] : []), '', '`npx readfirst fix` writes this into the map; nothing to do for this PR.', '</details>', '');
   }
   if (list) parts.push(toMarkdown(list, { checklist: true, heading: null }));
   else if (!problems.length) parts.push('No changed files to look up.', '');
@@ -48,8 +52,17 @@ export function commentBody({ list, problems, removed, commit, fixes = [] }) {
 
 export async function runAction({ env = process.env, fetchImpl = fetch, root = env.GITHUB_WORKSPACE ?? process.cwd(), log = (s) => process.stdout.write(`${s}\n`) } = {}) {
   const files = repoFiles(root);
-  const map = readMapFile(root);
-  const problems = mapProblems(map, files);
+  // New files beside placed ones and patterns for deleted files are settled as `fix` would; only the rest fails.
+  const strict = (env.INPUT_STRICT ?? 'false') === 'true';
+  const raw = readMapFile(root);
+  const s = settleMap(raw, files);
+  // Strict: what fix would settle still counts as a problem, and the map is used as written.
+  const strictOff = !strict || !s.settled.length;
+  const map = strictOff ? s.map : raw;
+  const problems = strictOff ? s.problems : [...s.problems, ...s.settled.map((c) => `not yet written in the map: ${c}`)];
+  // With problems left, what fix would change is the help; without, it is a note.
+  const settled = problems.length ? [] : s.settled;
+  const fixes = problems.length ? s.settled : [];
   const failOnProblems = (env['INPUT_FAIL-ON-MAP-PROBLEMS'] ?? env.INPUT_FAIL_ON_MAP_PROBLEMS ?? 'true') !== 'false';
   const event = env.GITHUB_EVENT_PATH ? JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, 'utf8')) : {};
   const pr = event.pull_request;
@@ -61,14 +74,16 @@ export async function runAction({ env = process.env, fetchImpl = fetch, root = e
   }
   const repo = env.GITHUB_REPOSITORY;
   const changed = await pages(fetchImpl, env, `/repos/${repo}/pulls/${pr.number}/files`);
+  const committed = (env['INPUT_AUTO-FIX'] ?? env.INPUT_AUTO_FIX ?? 'false') === 'true' && settled.length
+    ? await commitFix({ fetchImpl, env, repo, pr, raw, fixed: map, settled, log })
+    : null;
   const removed = changed.filter((f) => f.status === 'removed').map((f) => f.filename);
   const targets = changed.filter((f) => f.status !== 'removed').map((f) => f.filename);
   // A broken map still gets a comment (the problems), but no read list from it.
   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 fixes = problems.length ? (() => { try { return fixMap(map, files).changes; } catch { return []; } })() : [];
-  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null, fixes });
+  const body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null, fixes, settled, committed });
   summary(body);
 
   if ((env.INPUT_COMMENT ?? 'true') !== 'false') {
@@ -85,7 +100,39 @@ export async function runAction({ env = process.env, fetchImpl = fetch, root = e
     }
   }
   if (problems.length) log(`${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}`);
-  return { ok: !(problems.length && failOnProblems), problems, list, body };
+  return { ok: !(problems.length && failOnProblems), problems, list, body, committed };
+}
+
+// auto-fix: write what `readfirst fix` settles (new files placed by their neighbours, patterns for deleted files) into
+// the map on the PR's branch, as one commit through the contents API. Only the mechanical part, never anything a person
+// has to decide; only on a branch of this repository; only when the branch's map is the one this run read, so a push in
+// between is never overwritten. Returns the new commit's sha, or null with a warning.
+async function commitFix({ fetchImpl, env, repo, pr, raw, fixed, settled, log }) {
+  if (pr.head?.repo?.full_name !== repo || !pr.head?.ref) {
+    log('::warning::readfirst auto-fix: this PR comes from a fork, so the map update stays a suggestion in the comment.');
+    return null;
+  }
+  const path = MAP_PATH.split('/').map(encodeURIComponent).join('/');
+  try {
+    const now = await api(fetchImpl, env, 'GET', `/repos/${repo}/contents/${path}?ref=${encodeURIComponent(pr.head.ref)}`);
+    let onBranch = null;
+    try { onBranch = JSON.parse(Buffer.from(now.content ?? '', 'base64').toString('utf8')); } catch { onBranch = null; }
+    if (JSON.stringify(onBranch) !== JSON.stringify(raw)) {
+      log('::warning::readfirst auto-fix: the map on the branch differs from the one this run read (a newer push, or the base changed it); nothing committed.');
+      return null;
+    }
+    const res = await api(fetchImpl, env, 'PUT', `/repos/${repo}/contents/${path}`, {
+      message: `readfirst fix: place ${settled.length} new file(s) in the map`,
+      content: Buffer.from(`${JSON.stringify(fixed, null, 2)}\n`, 'utf8').toString('base64'),
+      sha: now.sha,
+      branch: pr.head.ref,
+    });
+    log(`readfirst auto-fix: committed the map update to ${pr.head.ref}`);
+    return res?.commit?.sha ?? 'committed';
+  } catch (e) {
+    log(`::warning::readfirst auto-fix could not commit (${/: 403 /u.test(e.message) ? 'the token needs contents: write' : e.message.slice(0, 200)}); the comment says what \`npx readfirst fix\` would change.`);
+    return null;
+  }
 }
 
 if (process.argv[1]?.endsWith('/src/action.mjs')) {

package/src/cli.mjs

@@ -8,6 +8,7 @@
 //   readfirst diff [--base <ref>]  the read list for the files changed since <ref> (default: origin/main, else main)
 //   readfirst verify [--base <ref>] run the checks the read list names for the changed files; exit 1 if one fails
 //   readfirst hook [--install]     a Claude Code PreToolUse hook: the read list for the file an Edit or Write is about to change
+//                                  (--install --verify also adds a Stop hook, `hook --stop`, that runs verify before Claude Code finishes)
 //   readfirst mcp                  an MCP server on stdio: read_list, changed_read_list and check_map as tools for any agent
 //   readfirst view [--out <file>]  the map as a city in one HTML page (default .readfirst/local/view.html)
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
@@ -16,7 +17,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, relative } from 'node:path';
 import { importEdges } from './imports.mjs';
-import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems } from './map.mjs';
+import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems, settleMap } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
@@ -28,12 +29,13 @@ const HELP = `readfirst — what to read and check before changing a file
 
   readfirst init [--agent]       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 check [--strict]     check the map covers every tracked file (new files beside placed ones pass; --strict fails on them)
   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>
   readfirst verify [--base <ref>]  run the checks for the files changed since <ref> (--dry-run lists them)
-  readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json)
+  readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json;
+                                 --install --verify also runs the checks for edited files before Claude Code finishes)
   readfirst view [--out <file>]  the map as a city in one HTML page
   readfirst mcp                  MCP server on stdio for Cursor, Codex, Windsurf and other agents
   readfirst prompt --labels <lang>  brief for your agent to write personal labels for the view (e.g. ko, en)
@@ -50,6 +52,9 @@ function parse(argv) {
     else if (a === '--agent') args.agent = true;
     else if (a === '--install') args.install = true;
     else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--strict') args.strict = true;
+    else if (a === '--verify') args.verify = true;
+    else if (a === '--stop') args.stop = true;
     else if (a === '-h' || a === '--help') args.help = true;
     else if (a.startsWith('--')) { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); args[a.slice(2)] = v; }
     else args._.push(a);
@@ -86,9 +91,10 @@ function loadMapLenient(root, files, io) {
   const map = readMapFile(root);
   const broken = mapProblems(map, files, { placement: false });
   if (broken.length) throw new Error(`${MAP_PATH} has problems:\n- ${broken.join('\n- ')}`);
-  const behind = mapProblems(map, files);
+  const { map: settled, problems: behind, settled: placed } = settleMap(map, files);
   if (behind.length) io.err(`note: ${MAP_PATH} is behind the code (${behind.length} problem${behind.length > 1 ? 's' : ''}); \`readfirst fix\` repairs most of it.\n`);
-  return map;
+  else if (placed.length) io.err(`note: ${placed.length} change${placed.length > 1 ? 's' : ''} not yet written in ${MAP_PATH} (new files placed by their neighbours); \`readfirst fix\` writes ${placed.length > 1 ? 'them' : 'it'} down.\n`);
+  return settled;
 }
 
 // The one line that makes a coding agent use readfirst, added to the agent notes the project already has (CLAUDE.md,
@@ -162,6 +168,9 @@ export function brief(list) {
   return lines;
 }
 
+// Which files the PreToolUse hook has seen in a session: the Stop hook verifies those.
+const seenFile = (stateDir, session) => join(stateDir, `readfirst-hook-${String(session ?? 'none').replace(/[^\w-]/gu, '')}.json`);
+
 // Claude Code PreToolUse hook. Reads the hook's JSON on stdin; for an Edit, Write or MultiEdit of a file the map covers,
 // prints the read list as additionalContext, once per file per session. Never blocks the edit: any problem means no output.
 export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
@@ -173,7 +182,7 @@ export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
     const root = git(cwd, 'rev-parse', '--show-toplevel').trim();
     const path = (isAbsolute(file) ? relative(root, file) : file).replace(/\\/gu, '/');
     if (path.startsWith('..') || path === MAP_PATH || !existsSync(join(root, MAP_PATH))) return null;
-    const seenAt = join(stateDir, `readfirst-hook-${String(event.session_id ?? 'none').replace(/[^\w-]/gu, '')}.json`);
+    const seenAt = seenFile(stateDir, event.session_id);
     let seen = {};
     try { seen = JSON.parse(readFileSync(seenAt, 'utf8')); } catch { seen = {}; }
     if (seen[path] && now - seen[path] < 6 * 3600_000) return null;
@@ -193,17 +202,78 @@ export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
   }
 }
 
+// The check commands of the map as the base branch has it. The Stop hook runs a command without anyone asking, so it
+// runs only these: a command a branch adds or changes in the map is repository content nobody has merged yet.
+function trustedRuns(root) {
+  try {
+    const { ref } = changedFiles(root);
+    const since = git(root, 'merge-base', ref, 'HEAD').trim();
+    const map = JSON.parse(git(root, 'show', `${since}:${MAP_PATH}`));
+    return new Set([...(map.groups ?? []), ...(map.rules ?? [])].flatMap((x) => (x.checks ?? []).map((c) => c.run)));
+  } catch {
+    return new Set();
+  }
+}
+
+// Claude Code Stop hook (opt-in, `hook --install --verify`): before Claude Code ends its turn, run the map's checks for the
+// files it edited in this session that are still changed. A failing check blocks the stop once, with the failure as the
+// reason, so the agent fixes it; on the second stop of the same turn it lets go, so a check it cannot fix never traps
+// the session. Only commands the base branch's map already lists run; others are named for `readfirst verify`, which
+// someone runs on purpose. Nothing edited, nothing changed or no checks: no output.
+export function runStopHook(input, { stateDir = tmpdir(), timeout = 600 } = {}) {
+  let event;
+  try { event = JSON.parse(input); } catch { return null; }
+  if (event.stop_hook_active) return null;
+  try {
+    const root = git(event.cwd ?? process.cwd(), 'rev-parse', '--show-toplevel').trim();
+    if (!existsSync(join(root, MAP_PATH))) return null;
+    let seen = {};
+    try { seen = JSON.parse(readFileSync(seenFile(stateDir, event.session_id), 'utf8')); } catch { return null; }
+    const dirty = new Set(git(root, 'status', '--porcelain', '-z', '--untracked-files=all').split('\0').filter(Boolean).map((l) => l.slice(3)));
+    let changed = [];
+    try { changed = changedFiles(root).files; } catch { /* no base branch: the working tree is enough */ }
+    const targets = Object.keys(seen).filter((f) => dirty.has(f) || changed.includes(f)).sort();
+    if (!targets.length) return null;
+    const files = repoFiles(root);
+    const map = readMapFile(root);
+    if (mapProblems(map, files, { placement: false }).length) return null;
+    const list = readList({ map, files, imports: importEdges(files, readText(root)), targets, limit: 1 });
+    if (!list.checks.length) return null;
+    const trusted = trustedRuns(root);
+    const skipped = list.checks.filter((c) => !trusted.has(c.run)).map((c) => c.run);
+    const result = verifyChecks(root, list.checks.filter((c) => trusted.has(c.run)), { timeout });
+    const failed = result.filter((c) => c.status !== 'pass');
+    const notRun = skipped.length ? ` Not run, because the base branch's map does not list them yet: ${skipped.map((r) => `\`${r}\``).join(', ')}; run \`npx readfirst verify\` to run them on purpose.` : '';
+    if (!failed.length) return JSON.stringify({ systemMessage: `readfirst verify: ${result.length} check(s) passed for ${targets.length} edited file(s).${notRun}` });
+    const reason = [
+      `readfirst verify: ${failed.length} of ${result.length} check(s) the map lists for the files you edited failed. Fix them before you finish.${notRun}`,
+      ...failed.map((c) => `\n--- ${c.run} (${c.status}${c.code != null ? `, exit ${c.code}` : ''})${c.why ? ` covers ${c.why}` : ''}; last lines:\n${c.output ?? ''}`),
+    ].join('\n');
+    return JSON.stringify({ decision: 'block', reason });
+  } catch {
+    return null;
+  }
+}
+
 export const HOOK_COMMAND = 'npx --yes readfirst hook';
-// Adds the hook to the project's .claude/settings.json, keeping everything already there.
-export function installHook(root) {
+export const STOP_HOOK_COMMAND = 'npx --yes readfirst hook --stop';
+// Adds the hook to the project's .claude/settings.json, keeping everything already there. With verify, also the Stop
+// hook that runs the checks before Claude Code finishes.
+export function installHook(root, { verify = false } = {}) {
   const at = join(root, '.claude', 'settings.json');
   let settings = {};
   if (existsSync(at)) {
     try { settings = JSON.parse(readFileSync(at, 'utf8')); } catch { throw new Error('.claude/settings.json is not valid JSON; fix it first'); }
   }
   const pre = ((settings.hooks ??= {}).PreToolUse ??= []);
-  if (pre.some((m) => (m.hooks ?? []).some((h) => /readfirst hook/u.test(h.command ?? '')))) return false;
-  pre.push({ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 15 }] });
+  const has = (list) => list.some((m) => (m.hooks ?? []).some((h) => /readfirst hook/u.test(h.command ?? '')));
+  let added = false;
+  if (!has(pre)) { pre.push({ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 15 }] }); added = true; }
+  if (verify) {
+    const stop = (settings.hooks.Stop ??= []);
+    if (!has(stop)) { stop.push({ hooks: [{ type: 'command', command: STOP_HOOK_COMMAND, timeout: 1800 }] }); added = true; }
+  }
+  if (!added) return false;
   mkdirSync(join(root, '.claude'), { recursive: true });
   writeFileSync(at, `${JSON.stringify(settings, null, 2)}\n`);
   return true;
@@ -214,7 +284,7 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
   const [cmd, ...rest] = args._;
   if (args.help || !cmd) { io.out(`${HELP}\n`); return cmd || args.help ? 0 : 2; }
   if (cmd === 'hook' && !args.install) {
-    const out = runHook(stdin());
+    const out = args.stop ? runStopHook(stdin()) : runHook(stdin());
     if (out) io.out(`${out}\n`);
     return 0;
   }
@@ -279,13 +349,22 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     return 0;
   }
   if (cmd === 'check') {
-    const problems = mapProblems(readMapFile(root), files);
-    if (args.json) io.out(`${JSON.stringify({ ok: !problems.length, problems }, null, 2)}\n`);
-    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`);
+    // Placing new files next to their neighbours and dropping patterns for deleted files is what `fix` does; check
+    // settles those the same way and passes. --strict fails on them too.
+    const map = readMapFile(root);
+    const { problems, settled } = args.strict ? { problems: mapProblems(map, files), settled: [] } : settleMap(map, files);
+    if (args.json) io.out(`${JSON.stringify({ ok: !problems.length, problems, settled }, null, 2)}\n`);
+    else {
+      if (problems.length) io.out(`${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}\n`);
+      else io.out(`${MAP_PATH} is good: ${files.length} files.\n`);
+      if (settled.length) io.out(`settled without writing (\`readfirst fix\` writes it down):\n- ${settled.join('\n- ')}\n`);
+    }
     return problems.length ? 1 : 0;
   }
   if (cmd === 'hook') {
-    io.out(installHook(root) ? 'added the readfirst hook to .claude/settings.json: Claude Code now sees the read list before each edit.\n' : '.claude/settings.json already has the readfirst hook.\n');
+    io.out(installHook(root, { verify: args.verify })
+      ? `added the readfirst hook to .claude/settings.json: Claude Code now sees the read list before each edit${args.verify ? ', and cannot finish while a check for a file it edited fails (it gets one try to fix it)' : ''}.\n`
+      : '.claude/settings.json already has the readfirst hook.\n');
     return 0;
   }
   if (cmd === 'fix') {

package/src/imports.mjs

@@ -1,7 +1,10 @@
-// Which tracked file imports which, read from the code. Only imports that resolve to a tracked file count: packages and
-// unresolved specifiers are left out. JavaScript/TypeScript (import, export from, import(), require) and Python
-// (import a.b, from a.b import c, relative from . imports) are read.
+// Which tracked file imports which, read from the code. Only imports that resolve to a tracked file count: packages from
+// outside the repository and unresolved specifiers are left out. JavaScript/TypeScript (import, export from, import(),
+// require; relative paths, the repository's own workspace packages and tsconfig/jsconfig "paths" aliases) and Python
+// (import a.b, from a.b import c, relative from . imports, and "a.b.c" strings that name a module of the repository,
+// as hooks and settings do) are read here; Go, Rust, Elixir, C#, Java/Kotlin, Ruby and PHP in langs.mjs.
 import { posix } from 'node:path';
+import { moreEdges } from './langs.mjs';
 
 const JS = /\.(?:m?js|cjs|tsx?|jsx|mts|cts|vue|svelte)$/u;
 const PY = /\.py$/u;
@@ -11,6 +14,87 @@ const PY_IMPORT = /^[ \t]*(?:from[ \t]+(\.*[\w.]*)[ \t]+import[ \t]+(\([^)]*\)|[
 const JS_EXT = ['', '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.mts', '.vue', '.svelte', '/index.js', '/index.ts', '/index.tsx', '/index.mjs'];
 
 const lineAt = (body, index) => body.slice(0, index).split('\n').length;
+const dirOf = (f) => (posix.dirname(f) === '.' ? '' : posix.dirname(f));
+const within = (dir, file) => dir === '' || file.startsWith(`${dir}/`);
+
+// tsconfig.json allows comments and trailing commas.
+export function parseJsonc(text) {
+  if (text === null || text === undefined) return null;
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') {
+      const end = text.slice(i).match(/^"(?:[^"\\\n]|\\.)*"/u);
+      if (!end) return null;
+      out += end[0]; i += end[0].length - 1;
+    } else if (c === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+    } else if (c === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close < 0) return null;
+      i = close + 1;
+    } else out += c;
+  }
+  try { return JSON.parse(out.replace(/,(\s*[}\]])/gu, '$1')); } catch { return null; }
+}
+
+// Bare specifiers that point back into the repository: a workspace package by the name in its package.json
+// ("@acme/db", "@acme/db/schema"), or a "paths" alias from the tsconfig/jsconfig that covers the importing file ("@/lib/x").
+function jsResolver(files, tracked, read) {
+  const jsCandidates = (base) => [...JS_EXT.map((e) => base + e), base.replace(/\.(m|c)?js$/u, '.$1ts'), base.replace(/\.js$/u, '.tsx')];
+  const firstTracked = (bases) => {
+    for (const b of bases) {
+      const hit = jsCandidates(posix.normalize(b)).find((c) => tracked.has(c));
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const pkgs = [];
+  for (const f of files) {
+    if (!/(?:^|\/)package\.json$/u.test(f) || f.includes('node_modules/')) continue;
+    let j;
+    try { j = JSON.parse(read(f) ?? ''); } catch { continue; }
+    if (typeof j?.name !== 'string' || !j.name || dirOf(f) === '') continue;
+    const dot = typeof j.exports === 'string' ? j.exports : j.exports?.['.'];
+    const exp = typeof dot === 'string' ? [dot] : dot && typeof dot === 'object' ? ['types', 'import', 'default', 'require'].map((k) => dot[k]).filter((v) => typeof v === 'string') : [];
+    // An entry pointing at build output (dist/index.js) is read as the source next to it (src/index.ts).
+    const entries = [j.source, ...exp, j.types, j.typings, j.module, j.main].filter((v) => typeof v === 'string')
+      .flatMap((e) => [e, e.replace(/^\.?\/?(?:dist|build|lib|out)\//u, 'src/').replace(/\.d\.ts$/u, '.ts')]);
+    pkgs.push({ name: j.name, dir: dirOf(f), entries: [...entries, 'src/index', 'index'] });
+  }
+  pkgs.sort((a, b) => b.name.length - a.name.length);
+  const aliases = [];
+  for (const f of files) {
+    if (!/(?:^|\/)(?:tsconfig|jsconfig)(?:\.[\w-]+)?\.json$/u.test(f) || f.includes('node_modules/')) continue;
+    const opts = parseJsonc(read(f))?.compilerOptions;
+    if (!opts?.paths || typeof opts.paths !== 'object') continue;
+    const base = posix.join(dirOf(f), opts.baseUrl ?? '.');
+    for (const [pattern, targets] of Object.entries(opts.paths)) {
+      if (Array.isArray(targets)) aliases.push({ scope: dirOf(f), pattern, targets: targets.filter((t) => typeof t === 'string').map((t) => posix.join(base, t)) });
+    }
+  }
+  // The nearest config wins, as it would for the compiler.
+  aliases.sort((a, b) => b.scope.length - a.scope.length);
+  return (from, spec) => {
+    for (const a of aliases) {
+      if (!within(a.scope, from)) continue;
+      const star = a.pattern.indexOf('*');
+      let rest = null;
+      if (star < 0) rest = spec === a.pattern ? '' : null;
+      else if (spec.startsWith(a.pattern.slice(0, star)) && spec.endsWith(a.pattern.slice(star + 1))) rest = spec.slice(star, spec.length - (a.pattern.length - star - 1));
+      if (rest === null) continue;
+      const hit = firstTracked(a.targets.map((t) => t.replace('*', rest)));
+      if (hit) return hit;
+    }
+    const pkg = pkgs.find((p) => spec === p.name || spec.startsWith(`${p.name}/`));
+    if (!pkg) return undefined;
+    const sub = spec.slice(pkg.name.length + 1);
+    return sub
+      ? firstTracked([posix.join(pkg.dir, sub), posix.join(pkg.dir, 'src', sub)])
+      : firstTracked(pkg.entries.map((e) => posix.join(pkg.dir, e.replace(/\.(?:m|c)?js$|\.tsx?$/u, ''))));
+  };
+}
 
 export function importEdges(files, read) {
   const tracked = new Set(files);
@@ -25,13 +109,19 @@ export function importEdges(files, read) {
     const base = posix.join(baseDir, ...dotted.split('.').filter(Boolean));
     return [`${base}.py`, `${base}/__init__.py`].find((c) => tracked.has(c));
   };
+  let bare = null;
   for (const from of [...files].sort()) {
     if (JS.test(from)) {
       const body = read(from);
       if (body === null) continue;
       for (const m of body.matchAll(JS_IMPORT)) {
         const spec = (m[1] ?? m[2] ?? m[3]).split('?')[0];
-        if (!spec.startsWith('.')) continue;
+        if (!spec.startsWith('.')) {
+          if (spec.startsWith('node:') || /^[a-z]+:/u.test(spec)) continue;
+          bare ??= jsResolver(files, tracked, read);
+          add(from, bare(from, spec), lineAt(body, m.index));
+          continue;
+        }
         const base = posix.normalize(posix.join(posix.dirname(from), spec));
         // TypeScript sources import "./x.js" for the file "./x.ts".
         const candidates = [...JS_EXT.map((e) => base + e), base.replace(/\.(m|c)?js$/u, '.$1ts'), base.replace(/\.js$/u, '.tsx')];
@@ -62,5 +152,33 @@ export function importEdges(files, read) {
       }
     }
   }
+  dottedEdges(files, tracked, read, pyModule, add);
+  moreEdges([...files].sort(), read, add);
   return out;
 }
+
+// Python projects name code by dotted path in strings: Frappe hooks.py ("app.module.function"), frappe.call from
+// JavaScript, Django settings and urls, Celery task names. A string counts when its first part is a top-level Python
+// package of the repository and the longest leading part names one of its modules.
+function dottedEdges(files, tracked, read, pyModule, add) {
+  const top = new Map();
+  for (const f of files) {
+    const m = f.match(/^(?:(src)\/)?([A-Za-z_]\w*)\/__init__\.py$/u);
+    if (m) top.set(m[2], m[1] ?? '');
+  }
+  if (!top.size) return;
+  const DOTTED = /["'`]([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+)["'`]/gu;
+  for (const from of files) {
+    if (!/\.(?:py|m?js|tsx?|json)$/u.test(from) || from.includes('node_modules/')) continue;
+    const body = read(from);
+    if (body === null || body.length > 2_000_000) continue;
+    for (const m of body.matchAll(DOTTED)) {
+      const parts = m[1].split('.');
+      if (!top.has(parts[0])) continue;
+      for (let n = parts.length; n >= 2; n--) {
+        const to = pyModule(parts.slice(0, n).join('.'), top.get(parts[0]));
+        if (to) { add(from, to, lineAt(body, m.index)); break; }
+      }
+    }
+  }
+}

package/src/langs.mjs

@@ -0,0 +1,238 @@
+// Who uses which file, for languages whose imports name modules, packages or types rather than paths: Go, Rust,
+// Elixir, C#, Java/Kotlin, Ruby and PHP. Like the JavaScript and Python readers in imports.mjs, only edges that land on
+// a tracked file count; anything that names a package from outside the repository is left out. Each reader is a
+// careful approximation of the language's own rules, good enough to find the tests and callers of a file.
+import { posix } from 'node:path';
+
+const lineAt = (body, index) => body.slice(0, index).split('\n').length;
+const dirOf = (f) => posix.dirname(f);
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+// Comments are blanked (same length, so line numbers stay right) before looking for names in code.
+const blank = (body, re) => body.replace(re, (m) => m.replace(/[^\n]/gu, ' '));
+const noComments = (body) => blank(body, /\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu);
+
+// Go: `import "module/path/pkg"` reaches every non-test .go file of that package's folder. The module path comes from
+// the nearest go.mod.
+function goEdges(files, read, add) {
+  const mods = files.filter((f) => /(?:^|\/)go\.mod$/u.test(f)).map((f) => {
+    const m = (read(f) ?? '').match(/^module\s+(\S+)/mu);
+    return m ? { dir: dirOf(f) === '.' ? '' : dirOf(f), path: m[1] } : null;
+  }).filter(Boolean).sort((a, b) => b.path.length - a.path.length);
+  if (!mods.length) return;
+  const byDir = new Map();
+  for (const f of files) if (/\.go$/u.test(f) && !/_test\.go$/u.test(f)) byDir.set(dirOf(f), [...(byDir.get(dirOf(f)) ?? []), f]);
+  for (const from of files.filter((f) => /\.go$/u.test(f))) {
+    const body = read(from);
+    if (body === null) continue;
+    const specs = [];
+    for (const m of body.matchAll(/^\s*import\s*\(([\s\S]*?)\)/gmu)) for (const s of m[1].matchAll(/"([^"\n]+)"/gu)) specs.push([s[1], m.index + m[0].indexOf(s[0])]);
+    for (const m of body.matchAll(/^\s*import\s+(?:[\w.]+\s+)?"([^"\n]+)"/gmu)) specs.push([m[1], m.index]);
+    for (const [spec, at] of specs) {
+      const mod = mods.find((x) => spec === x.path || spec.startsWith(`${x.path}/`));
+      if (!mod) continue;
+      const dir = posix.join(mod.dir, spec.slice(mod.path.length).replace(/^\//u, '')) || '.';
+      for (const to of byDir.get(dir === '' ? '.' : dir) ?? []) add(from, to, lineAt(body, at));
+    }
+  }
+}
+
+// Rust: `mod x;` declares a child module file; `use crate::a::b` (and `super::`, `self::`, or the crate's own name
+// from tests/) reaches the file of the longest module path that exists.
+function rustEdges(files, read, add) {
+  const tracked = new Set(files);
+  const rs = files.filter((f) => /\.rs$/u.test(f));
+  if (!rs.length) return;
+  const crates = files.filter((f) => /(?:^|\/)Cargo\.toml$/u.test(f)).map((f) => {
+    const name = (read(f) ?? '').match(/^\s*name\s*=\s*"([^"]+)"/mu)?.[1]?.replace(/-/gu, '_');
+    const root = dirOf(f) === '.' ? '' : dirOf(f);
+    return { root, name, src: posix.join(root, 'src') };
+  });
+  const crateOf = (f) => crates.filter((c) => !c.root || f.startsWith(`${c.root}/`)).sort((a, b) => b.root.length - a.root.length)[0] ?? { root: '', name: null, src: 'src' };
+  const moduleFile = (dir, parts) => {
+    for (let n = parts.length; n > 0; n--) {
+      const base = posix.join(dir, ...parts.slice(0, n));
+      const hit = [`${base}.rs`, `${base}/mod.rs`].find((c) => tracked.has(c));
+      if (hit) return hit;
+    }
+    return null;
+  };
+  // The folder a file's own child modules live in: src/a.rs and src/a/mod.rs both keep theirs in src/a/.
+  const childDir = (f) => (/(?:^|\/)(?:mod|lib|main)\.rs$/u.test(f) ? dirOf(f) : f.replace(/\.rs$/u, ''));
+  const modulePath = (f, c) => {
+    const rel = posix.relative(c.src, f).replace(/\.rs$/u, '').split('/');
+    if (['lib', 'main'].includes(rel.at(-1)) && rel.length === 1) return [];
+    if (rel.at(-1) === 'mod') rel.pop();
+    return rel;
+  };
+  for (const from of rs) {
+    const body = read(from);
+    if (body === null) continue;
+    const code = noComments(body);
+    const c = crateOf(from);
+    for (const m of code.matchAll(/^\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+(\w+)\s*;/gmu)) add(from, moduleFile(childDir(from), [m[1]]), lineAt(body, m.index));
+    // `use a::b::{c, d::e}` is read as a::b::c and a::b::d::e (one level of braces).
+    const paths = [];
+    for (const m of code.matchAll(/\buse\s+((?:crate|super|self|\w+)(?:::\w+)*)(?:::\{([^}]*)\})?/gu)) {
+      const inner = (m[2] ?? '').split(',').map((x) => x.trim().replace(/\s+as\s+\w+$/u, '')).filter((x) => /^\w+(?:::\w+)*$/u.test(x) && x !== 'self');
+      for (const p of inner.length ? inner.map((x) => `${m[1]}::${x}`) : [m[1]]) paths.push([p, m.index]);
+    }
+    for (const [path, index] of paths) {
+      const m = { index };
+      const parts = path.split('::');
+      let base;
+      if (parts[0] === 'crate' || (c.name && parts[0] === c.name)) base = [];
+      else if (parts[0] === 'self') base = modulePath(from, c);
+      else if (parts[0] === 'super') { base = modulePath(from, c); while (parts[0] === 'super') { parts.shift(); base = base.slice(0, -1); } parts.unshift('_'); }
+      else continue;
+      // Nothing below the crate root names a file: the crate root itself (lib.rs, else main.rs) is what is used.
+      add(from, moduleFile(c.src, [...base, ...parts.slice(1)]) ?? (base.length ? null : [posix.join(c.src, 'lib.rs'), posix.join(c.src, 'main.rs')].find((x) => tracked.has(x) && x !== from)), lineAt(body, m.index));
+    }
+  }
+}
+
+// Elixir: modules are found by `defmodule`; any dotted module name the code names (alias, import, use, require or a
+// call such as MyApp.Billing.charge) reaches the file that defines it. `alias A.{B, C}` is expanded.
+function elixirEdges(files, read, add) {
+  const ex = files.filter((f) => /\.exs?$/u.test(f));
+  const defines = new Map();
+  const bodies = new Map();
+  for (const f of ex) {
+    const body = read(f);
+    if (body === null) continue;
+    bodies.set(f, body);
+    for (const m of body.matchAll(/^\s*defmodule\s+([A-Z][\w.]*)/gmu)) if (!defines.has(m[1])) defines.set(m[1], f);
+  }
+  if (!defines.size) return;
+  for (const [from, body] of bodies) {
+    const code = blank(body, /#[^\n]*/gu);
+    for (const m of code.matchAll(/\balias\s+([A-Z][\w.]*)\.\{([^}]*)\}/gu))
+      for (const n of m[2].split(',').map((s) => s.trim()).filter(Boolean)) add(from, defines.get(`${m[1]}.${n}`), lineAt(body, m.index));
+    for (const m of code.matchAll(/(?<![\w.])([A-Z]\w*(?:\.[A-Z]\w*)+)/gu)) {
+      // The longest defined prefix: MyApp.Billing.Invoice.new names MyApp.Billing.Invoice.
+      const parts = m[1].split('.');
+      for (let n = parts.length; n > 0; n--) {
+        const to = defines.get(parts.slice(0, n).join('.'));
+        if (to) { add(from, to, lineAt(body, m.index)); break; }
+      }
+    }
+  }
+}
+
+// Types by namespace, for C# and Java/Kotlin: a file reaches the files declaring types it names, when that type's
+// namespace (package) is its own or one it imports. Names are matched as whole words, outside comments and strings.
+function typeEdges(files, read, add, { ext, nsRe, typeRe, importRe, wildcard }) {
+  const src = files.filter((f) => ext.test(f));
+  if (!src.length) return;
+  const types = new Map(); // namespace -> Map(type -> file)
+  const info = new Map();
+  for (const f of src) {
+    const body = read(f);
+    if (body === null) continue;
+    const code = blank(noComments(body), /"(?:[^"\\\n]|\\.)*"/gu);
+    const ns = code.match(nsRe)?.[1] ?? '';
+    const declared = new Set([...code.matchAll(typeRe)].map((m) => m[1]));
+    if (!declared.size && /\.(?:java|kt)$/u.test(f)) declared.add(posix.basename(f).replace(/\.\w+$/u, ''));
+    const space = types.get(ns) ?? new Map();
+    for (const t of declared) if (!space.has(t)) space.set(t, f);
+    types.set(ns, space);
+    info.set(f, { body, code, ns, declared });
+  }
+  for (const [from, { body, code, ns, declared }] of info) {
+    const spaces = new Set([ns]);
+    const single = new Map();
+    for (const m of code.matchAll(importRe)) {
+      const name = m[1];
+      if (wildcard(name)) spaces.add(wildcard(name));
+      else if (types.has(name)) spaces.add(name);
+      else { const i = name.lastIndexOf('.'); if (i > 0) single.set(name.slice(i + 1), name.slice(0, i)); }
+    }
+    // C#: an enclosing namespace's types are visible too (Company.App.Billing sees Company.App).
+    for (let n = ns; n.includes('.'); ) { n = n.slice(0, n.lastIndexOf('.')); spaces.add(n); }
+    const candidates = new Map();
+    for (const s of spaces) for (const [t, f] of types.get(s) ?? []) if (!candidates.has(t)) candidates.set(t, f);
+    for (const [t, s] of single) { const f = types.get(s)?.get(t); if (f) candidates.set(t, f); }
+    for (const [t, to] of candidates) {
+      if (to === from || declared.has(t)) continue;
+      const m = new RegExp(`\\b${escape(t)}\\b`, 'u').exec(code);
+      if (m) add(from, to, lineAt(body, m.index));
+    }
+  }
+}
+
+const csharpEdges = (files, read, add) => typeEdges(files, read, add, {
+  ext: /\.cs$/u,
+  nsRe: /^\s*namespace\s+([\w.]+)/mu,
+  typeRe: /\b(?:class|record|interface|struct|enum)\s+(\w+)/gu,
+  importRe: /^\s*(?:global\s+)?using\s+(?:static\s+)?([\w.]+)\s*;/gmu,
+  wildcard: () => null,
+});
+
+const jvmEdges = (files, read, add) => typeEdges(files, read, add, {
+  ext: /\.(?:java|kt)$/u,
+  nsRe: /^\s*package\s+([\w.]+)/mu,
+  typeRe: /\b(?:class|interface|enum|record|object)\s+(\w+)/gu,
+  importRe: /^\s*import\s+(?:static\s+)?([\w.]+(?:\.\*)?)\s*;?/gmu,
+  wildcard: (name) => (name.endsWith('.*') ? name.slice(0, -2) : null),
+});
+
+// Ruby: require_relative and require of a file in lib/, plus Rails-style constants (Billing::Invoice) found by the file
+// path that autoloading would use (app/*/billing/invoice.rb, lib/billing/invoice.rb).
+const camel = (s) => s.split('_').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+function rubyEdges(files, read, add) {
+  const tracked = new Set(files);
+  const rb = files.filter((f) => /\.rb$/u.test(f));
+  if (!rb.length) return;
+  const constants = new Map();
+  for (const f of rb) {
+    const m = f.match(/^(?:app\/[^/]+|lib)\/(.+)\.rb$/u);
+    if (m && !f.startsWith('app/views/')) constants.set(m[1].split('/').map(camel).join('::'), f);
+  }
+  for (const from of rb) {
+    const body = read(from);
+    if (body === null) continue;
+    const code = blank(body, /#[^\n{]*$/gmu);
+    for (const m of code.matchAll(/\brequire_relative\s+['"]([^'"]+)['"]/gu)) {
+      const p = posix.normalize(posix.join(dirOf(from), m[1]));
+      add(from, [p, `${p}.rb`].find((c) => tracked.has(c)), lineAt(body, m.index));
+    }
+    for (const m of code.matchAll(/\brequire\s+['"]([^'"]+)['"]/gu)) add(from, [`lib/${m[1]}.rb`, `${m[1]}.rb`].find((c) => tracked.has(c)), lineAt(body, m.index));
+    for (const m of code.matchAll(/(?<![\w:])((?:[A-Z]\w*::)*[A-Z]\w*)/gu)) add(from, constants.get(m[1]), lineAt(body, m.index));
+  }
+}
+
+// PHP: `use Vendor\Pkg\Class;` and fully qualified names, mapped to files through composer.json's PSR-4 prefixes.
+function phpEdges(files, read, add) {
+  const tracked = new Set(files);
+  const php = files.filter((f) => /\.php$/u.test(f));
+  if (!php.length) return;
+  const prefixes = [];
+  for (const c of files.filter((f) => /(?:^|\/)composer\.json$/u.test(f))) {
+    let j;
+    try { j = JSON.parse(read(c) ?? '{}'); } catch { continue; }
+    for (const section of [j.autoload, j['autoload-dev']]) for (const [ns, dirs] of Object.entries(section?.['psr-4'] ?? {}))
+      for (const d of [dirs].flat()) prefixes.push({ ns: ns.replace(/\\+$/u, ''), dir: posix.join(dirOf(c), d) });
+  }
+  prefixes.sort((a, b) => b.ns.length - a.ns.length);
+  const fileOf = (fq) => {
+    const name = fq.replace(/^\\/u, '');
+    for (const p of prefixes) if (name === p.ns || name.startsWith(`${p.ns}\\`)) {
+      const f = posix.join(p.dir, `${name.slice(p.ns.length + 1).replace(/\\/gu, '/')}.php`);
+      if (tracked.has(f)) return f;
+    }
+    return null;
+  };
+  if (!prefixes.length) return;
+  for (const from of php) {
+    const body = read(from);
+    if (body === null) continue;
+    const code = noComments(body);
+    for (const m of code.matchAll(/^\s*use\s+([\w\\]+)(?:\s+as\s+\w+)?\s*;/gmu)) add(from, fileOf(m[1]), lineAt(body, m.index));
+    for (const m of code.matchAll(/\\?\b([A-Z]\w*(?:\\[A-Z]\w*)+)\b/gu)) add(from, fileOf(m[1]), lineAt(body, m.index));
+  }
+}
+
+export const LANGUAGES = ['Go', 'Rust', 'Elixir', 'C#', 'Java', 'Kotlin', 'Ruby', 'PHP'];
+
+export function moreEdges(files, read, add) {
+  for (const reader of [goEdges, rustEdges, elixirEdges, csharpEdges, jvmEdges, rubyEdges, phpEdges]) reader(files, read, add);
+}

package/src/map.mjs

@@ -219,6 +219,22 @@ export function fixMap(map, files) {
   return { map: out, changes, problems: mapProblems(out, files) };
 }
 
+// A map that is only behind the code (new files that have a neighbour's group, patterns for deleted files) is settled
+// the way `fix` would settle it, without writing anything; only what fix cannot decide stays a problem. Read lists,
+// check and the Action use the settled map, so adding a file to an existing folder never fails a pull request.
+// A new top-level folder is the one placement fix guesses at (it joins the root files' group), so it stays a problem:
+// someone should give it a group.
+export function settleMap(map, files) {
+  const problems = mapProblems(map, files);
+  if (!problems.length) return { map, problems: [], settled: [] };
+  let fixed;
+  try { fixed = fixMap(map, files); } catch { return { map, problems, settled: [] }; }
+  const owned = matcher(map.groups.flatMap((g) => g.files));
+  const newTop = fixed.changes.map((c) => c.match(/^groups\.[^:]+: added ((\w[^/]*)\/.*)$/u)).filter((m) => m && !files.some((f) => f.startsWith(`${m[2]}/`) && owned(f)));
+  const left = [...fixed.problems, ...newTop.map((m) => `new top-level folder ${m[2]}/ is in no group: give it one (\`readfirst fix\` would put ${m[1]} with the root files)`)];
+  return { map: left.length ? map : fixed.map, problems: left.length ? problems.filter((p) => !/in no group|matches no/u.test(p)).concat(left) : [], settled: left.length ? fixed.changes.filter((c) => !newTop.some((m) => c.endsWith(`added ${m[1]}`))) : fixed.changes };
+}
+
 // The project's own check commands, found in its build files, so a first map already says what to run. Repository-wide
 // on purpose: narrowing a check to the group it covers is left to a person or an agent.
 export function draftChecks(files, read = () => null) {
@@ -240,5 +256,19 @@ export function draftChecks(files, read = () => null) {
   if (has.has('Cargo.toml')) add('cargo test', 'the Rust tests');
   const py = has.has('pyproject.toml') || has.has('setup.py') || has.has('pytest.ini');
   if (py && files.some((f) => /(?:^|\/)(?:test_[^/]*|[^/]*_test)\.py$/u.test(f))) add('pytest', 'the Python tests');
+  if (files.some((f) => /\.(?:sln|csproj|fsproj)$/u.test(f))) add('dotnet test', 'the .NET tests');
+  if (has.has('mix.exs')) add('mix test', 'the Elixir tests');
+  if (has.has('gradlew') || has.has('build.gradle') || has.has('build.gradle.kts')) add(has.has('gradlew') ? './gradlew test' : 'gradle test', 'the JVM tests (Gradle)');
+  else if (has.has('pom.xml')) add(has.has('mvnw') ? './mvnw test' : 'mvn test', 'the JVM tests (Maven)');
+  if (has.has('Gemfile')) {
+    if (files.some((f) => /(?:^|\/)spec\/.*_spec\.rb$/u.test(f))) add('bundle exec rspec', 'the Ruby specs');
+    else if (files.some((f) => /(?:^|\/)test\/.*_test\.rb$/u.test(f))) add(has.has('bin/rails') ? 'bin/rails test' : 'bundle exec rake test', 'the Ruby tests');
+  }
+  if (has.has('composer.json')) {
+    let scripts = {};
+    try { scripts = JSON.parse(read('composer.json') ?? '{}').scripts ?? {}; } catch { scripts = {}; }
+    if (scripts.test) add('composer test', 'the PHP tests');
+    else if (has.has('phpunit.xml') || has.has('phpunit.xml.dist')) add('vendor/bin/phpunit', 'the PHP tests');
+  }
   return out;
 }

package/src/readlist.mjs

@@ -3,7 +3,9 @@
 import { fixMap, groupOf, matcher, MAP_PATH } from './map.mjs';
 
 export const READ_LIST_FORMAT = 'readfirst/read-list@1';
-const TEST = /(^|\/)(?:tests?|__tests__|spec|e2e)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(^|\/)test[-_][^/]*\.(?:[cm]?[jt]sx?|py)$|_test\.(?:py|go)$/u;
+// Test files by folder or name, across the languages imports.mjs reads: JS/TS, Python, Go, Rust (tests/), Elixir,
+// C# (*Tests.cs, *.Tests/ projects), Java/Kotlin (src/test/, *Test), Ruby (spec/, *_spec.rb) and PHP (*Test.php).
+const TEST = /(^|\/)(?:tests?|__tests__|spec|e2e)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(^|\/)test[-_][^/]*\.(?:[cm]?[jt]sx?|py)$|_test\.(?:py|go|exs|rb)$|_spec\.rb$|(^|\/)[^/]+\.(?:Unit|Integration)?Tests?\/|Tests?\.(?:cs|java|kt|php)$|(^|\/)src\/(?:test|androidTest|integrationTest)\//u;
 export const isTest = (path) => TEST.test(path);
 
 // The read list for no files, so `diff --json` is always JSON.