readfirst 0.6.1 → 0.7.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
@@ -109,12 +111,15 @@ 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 |
 | `limit` | `30` | most tests and users listed per section |
 
@@ -157,7 +162,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.1",
+  "version": "0.7.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,14 @@ 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 = [] }) {
   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 (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 +50,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;
@@ -67,8 +78,7 @@ 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 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 });
   summary(body);
 
   if ((env.INPUT_COMMENT ?? 'true') !== 'false') {

package/src/cli.mjs

@@ -16,7 +16,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,7 +28,7 @@ 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>
@@ -50,6 +50,7 @@ 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 === '-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 +87,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,
@@ -218,6 +220,23 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     if (out) io.out(`${out}\n`);
     return 0;
   }
+  if (cmd === 'mcp') {
+    // The server starts and answers initialize and tools/list anywhere, also outside a git repository (directories
+    // start it in an empty container to check it). The repository is looked up at each tool call.
+    const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const run = (argv) => {
+      let out = ''; let err = ''; let code;
+      try {
+        const root = args.root ?? (() => {
+          try { return git(process.cwd(), 'rev-parse', '--show-toplevel').trim(); } catch { throw new Error(`not inside a git repository (${process.cwd()}): start the server in your repository, or pass --root <dir>`); }
+        })();
+        code = main(['--root', root, ...argv], { out: (s) => { out += s; }, err: (s) => { err += s; } });
+      } catch (e) { code = 2; err += e.message; }
+      return { code, out, err };
+    };
+    serveMcp({ handle: mcpHandler({ run, version }), input: process.stdin, output: process.stdout });
+    return 0;
+  }
   const root = args.root ?? git(process.cwd(), 'rev-parse', '--show-toplevel').trim();
   const files = repoFiles(root);
   const commit = (() => { try { return git(root, 'rev-parse', 'HEAD').trim(); } catch { return null; } })();
@@ -262,9 +281,16 @@ 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') {
@@ -298,16 +324,6 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     io.out(args.json ? `${JSON.stringify(list, null, 2)}\n` : `${toMarkdown(list)}\n`);
     return 0;
   }
-  if (cmd === 'mcp') {
-    const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-    const run = (argv) => {
-      let out = ''; let err = ''; let code;
-      try { code = main(['--root', root, ...argv], { out: (s) => { out += s; }, err: (s) => { err += s; } }); } catch (e) { code = 2; err += e.message; }
-      return { code, out, err };
-    };
-    serveMcp({ handle: mcpHandler({ run, version }), input: process.stdin, output: process.stdout });
-    return 0;
-  }
   if (cmd === 'verify') {
     const map = loadMapLenient(root, files, io);
     const changed = changedFiles(root, args.base);

package/src/imports.mjs

@@ -1,7 +1,9 @@
 // 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.
+// (import a.b, from a.b import c, relative from . imports) 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;
@@ -62,5 +64,6 @@ export function importEdges(files, read) {
       }
     }
   }
+  moreEdges([...files].sort(), read, add);
   return out;
 }

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.