readfirst 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeonghun917
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# readfirst
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**What to read and check before you — or your AI agent — change a file.**
+
+Coding agents can follow imports. What they don't know is what your team knows: "amounts here are in cents",
+"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.
+```
+
+No server, no account, no model calls. It reads your git checkout and `.readfirst/map.json`.
+
+## Start
+
+```sh
+npx readfirst init      # first map from your folders: one group per folder, media folders ignored
+npx readfirst prompt    # a brief for your coding agent to fill in titles, checks, risks and rules
+npx readfirst check     # every tracked file is in exactly one group (or ignored); rules point at real files
+```
+
+Commit `.readfirst/map.json`. From then on:
+
+```sh
+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
+```
+
+### Tell your agent to use it
+
+Add this to `CLAUDE.md`, `AGENTS.md` or `.cursorrules`:
+
+```md
+Before changing a file, run `npx readfirst read <file>` and follow what it says: keep the rules, read the risks, run the
+checks it lists. Before you finish, run `npx readfirst diff` and run every check it lists.
+When you learn something a newcomer would get wrong, add it as a risk in .readfirst/map.json.
+```
+
+## On every pull request (GitHub Action)
+
+```yaml
+# .github/workflows/readfirst.yml
+name: readfirst
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  readfirst:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jeonghun917/readfirst@v0
+```
+
+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.
+
+| Input | Default | Meaning |
+|---|---|---|
+| `fail-on-map-problems` | `true` | `false` reports map problems without failing |
+| `comment` | `true` | `false` writes only the job summary |
+| `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.
+
+## The map
+
+```json
+{
+  "format": "readfirst/map@1",
+  "groups": [
+    {
+      "id": "src-billing",
+      "title": "charging cards",
+      "files": ["src/billing/**"],
+      "checks": [{ "run": "npm test -- billing", "why": "charges" }],
+      "risks": [
+        { "text": "amounts are in cents" },
+        { "text": "index re-exports everything; a rename breaks the API", "files": ["src/billing/index.ts"] }
+      ]
+    }
+  ],
+  "rules": [
+    {
+      "id": "no-double-charge",
+      "rule": "a charge runs once per order",
+      "why": "refunds are manual",
+      "files": ["src/billing/**", "src/api/route.js"],
+      "checks": [{ "run": "npm run e2e:pay" }]
+    }
+  ],
+  "ignore": ["img/**"]
+}
+```
+
+- **files**: a path, `folder/**`, or a `*` glob inside one path segment (`src/*.js`, `**/*.md`).
+- **groups**: every tracked file belongs to exactly one group or to `ignore`. `readfirst check` fails otherwise, so the
+  map can't quietly fall behind the code (run it in CI).
+- **risks**: what a newcomer would get wrong. Leave out `files` when the risk covers the whole group.
+- **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.
+
+## License
+
+MIT

package/bin/readfirst.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+try { process.exitCode = main(process.argv.slice(2)); } catch (e) { process.stderr.write(`readfirst: ${e.message}\n`); process.exitCode = 2; }

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "readfirst",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "repository": { "type": "git", "url": "git+https://github.com/jeonghun917/readfirst.git" },
+  "homepage": "https://github.com/jeonghun917/readfirst#readme",
+  "bugs": "https://github.com/jeonghun917/readfirst/issues",
+  "bin": { "readfirst": "bin/readfirst.mjs" },
+  "files": ["bin", "src", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "keywords": ["ai", "agents", "claude-code", "cursor", "code-review", "impact-analysis", "monorepo"]
+}

package/src/action.mjs

@@ -0,0 +1,91 @@
+// The GitHub Action: on a pull request, one comment with the read list for the files the PR changes (kept up to date
+// on each push), and a failed check when the map no longer covers the code. Off a pull request it only checks the map.
+// The changed files come from the GitHub API, so any checkout depth works.
+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 { readList, toMarkdown } from './readlist.mjs';
+
+export const MARKER = '<!-- readfirst:pr-comment -->';
+const MAX_COMMENT = 60000;
+
+async function api(fetchImpl, env, method, path, body) {
+  const res = await fetchImpl(`${env.GITHUB_API_URL ?? 'https://api.github.com'}${path}`, {
+    method,
+    headers: { authorization: `Bearer ${env.INPUT_TOKEN}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', ...(body ? { 'content-type': 'application/json' } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(`GitHub API ${method} ${path}: ${res.status} ${(await res.text()).slice(0, 300)}`);
+  return res.status === 204 ? null : res.json();
+}
+
+async function pages(fetchImpl, env, path) {
+  const all = [];
+  for (let page = 1; page <= 30; page++) {
+    const batch = await api(fetchImpl, env, 'GET', `${path}${path.includes('?') ? '&' : '?'}per_page=100&page=${page}`);
+    all.push(...batch);
+    if (batch.length < 100) break;
+  }
+  return all;
+}
+
+export function commentBody({ list, problems, removed, commit }) {
+  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 (list) parts.push(toMarkdown(list, { checklist: true, heading: null }));
+  else if (!problems.length) parts.push('No changed files to look up.', '');
+  if (removed.length) parts.push(`Removed in this PR: ${removed.map((f) => `\`${f}\``).join(', ')}`, '');
+  parts.push(`<sub>From \`${MAP_PATH}\`${commit ? ` at ${commit.slice(0, 7)}` : ''}. Tick each check once it has run.</sub>`);
+  let body = parts.join('\n');
+  if (body.length > MAX_COMMENT) body = `${body.slice(0, MAX_COMMENT)}\n\n…cut here: run \`npx readfirst diff\` for the whole list.`;
+  return body;
+}
+
+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);
+  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;
+  const summary = (s) => { if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, `${s}\n`); };
+
+  if (!pr) {
+    log(problems.length ? `${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}` : `${MAP_PATH} is good: ${files.length} files.`);
+    return { ok: !(problems.length && failOnProblems), problems };
+  }
+  const repo = env.GITHUB_REPOSITORY;
+  const changed = await pages(fetchImpl, env, `/repos/${repo}/pulls/${pr.number}/files`);
+  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 body = commentBody({ list, problems, removed, commit: pr.head?.sha ?? null });
+  summary(body);
+
+  if ((env.INPUT_COMMENT ?? 'true') !== 'false') {
+    const comments = await pages(fetchImpl, env, `/repos/${repo}/issues/${pr.number}/comments`);
+    const mine = comments.find((c) => typeof c.body === 'string' && c.body.startsWith(MARKER));
+    try {
+      if (mine) await api(fetchImpl, env, 'PATCH', `/repos/${repo}/issues/comments/${mine.id}`, { body });
+      else await api(fetchImpl, env, 'POST', `/repos/${repo}/issues/${pr.number}/comments`, { body });
+      log(`${mine ? 'updated' : 'posted'} the readfirst comment on #${pr.number}`);
+    } catch (e) {
+      // A PR from a fork gets a read-only token: the read list stays in the job summary.
+      if (!/: 403 /u.test(e.message)) throw e;
+      log(`::warning::readfirst could not comment (read-only token, e.g. a PR from a fork); the read list is in the job summary.`);
+    }
+  }
+  if (problems.length) log(`${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}`);
+  return { ok: !(problems.length && failOnProblems), problems, list, body };
+}
+
+if (process.argv[1]?.endsWith('/src/action.mjs')) {
+  runAction().then((r) => { process.exitCode = r.ok ? 0 : 1; }, (e) => { process.stderr.write(`::error::readfirst: ${e.message}\n`); process.exitCode = 1; });
+}

package/src/cli.mjs

@@ -0,0 +1,117 @@
+// readfirst: what to read and check before changing a file.
+//   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 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>.
+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 { agentBrief } from './prompt.mjs';
+import { emptyList, readList, toMarkdown } from './readlist.mjs';
+
+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 read <file>...       read list for files you are about to change
+  readfirst diff [--base <ref>]  read list for files changed since <ref>
+
+Options: --root <dir>, --json, --limit <n>, --force (init: replace the map)`;
+
+function parse(argv) {
+  const args = { _: [], json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') args.json = true;
+    else if (a === '--force') args.force = 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);
+  }
+  return args;
+}
+
+const git = (root, ...a) => execFileSync('git', ['-C', root, ...a], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+
+export function repoFiles(root) {
+  // Tracked files plus new files not ignored by .gitignore, so a file being added can be looked up before its commit.
+  return git(root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard').split('\0').filter(Boolean)
+    .filter((f) => existsSync(join(root, f))).sort();
+}
+
+export const readText = (root) => (path) => {
+  try { return readFileSync(join(root, path), 'utf8'); } catch { return null; }
+};
+
+export function readMapFile(root) {
+  const at = join(root, MAP_PATH);
+  if (!existsSync(at)) throw new Error(`no ${MAP_PATH} here: run \`readfirst init\` first`);
+  try { return JSON.parse(readFileSync(at, 'utf8')); } catch (e) { throw new Error(`${MAP_PATH} is not valid JSON: ${e.message}`); }
+}
+
+function loadMap(root, files) {
+  return assertMap(readMapFile(root), files);
+}
+
+function changedFiles(root, base) {
+  const ref = base ?? ['origin/main', 'main', 'origin/master', 'master'].find((r) => { try { git(root, 'rev-parse', '--verify', '--quiet', r); return true; } catch { return false; } });
+  if (!ref) throw new Error('no base branch found: pass --base <ref>');
+  const since = git(root, 'merge-base', ref, 'HEAD').trim();
+  const names = new Set([
+    ...git(root, 'diff', '--name-only', since).split('\n'),
+    ...git(root, 'ls-files', '--others', '--exclude-standard').split('\n'),
+  ].filter(Boolean));
+  return { ref, files: [...names].sort() };
+}
+
+export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) }) {
+  const args = parse(argv);
+  const [cmd, ...rest] = args._;
+  if (args.help || !cmd) { io.out(`${HELP}\n`); return cmd || args.help ? 0 : 2; }
+  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; } })();
+
+  if (cmd === 'init') {
+    const at = join(root, MAP_PATH);
+    if (existsSync(at) && args.force !== true) throw new Error(`${MAP_PATH} already exists (pass --force to replace it)`);
+    const map = draftMap(files);
+    mkdirSync(join(root, '.readfirst'), { recursive: true });
+    writeFileSync(at, `${JSON.stringify(map, null, 2)}\n`);
+    io.out(`wrote ${MAP_PATH}: ${map.groups.length} groups, ${map.ignore.length} ignored folders.\nNext: run \`readfirst prompt\` and give the brief to your coding agent, or fill in titles, checks, risks and rules by hand.\n`);
+    return 0;
+  }
+  if (cmd === 'prompt') {
+    io.out(agentBrief(loadMap(root, files)));
+    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`);
+    return problems.length ? 1 : 0;
+  }
+  if (cmd === 'read' || cmd === 'diff') {
+    const map = loadMap(root, files);
+    let targets = rest;
+    if (cmd === 'diff') {
+      const changed = changedFiles(root, args.base);
+      targets = changed.files;
+      if (!targets.length) {
+        io.out(args.json ? `${JSON.stringify(emptyList(commit), null, 2)}\n` : `no files changed since ${changed.ref}.\n`);
+        return 0;
+      }
+    }
+    const limit = Number(args.limit ?? 30);
+    if (!Number.isInteger(limit) || limit < 1) throw new Error('--limit needs a whole number of 1 or more');
+    const list = readList({ map, files, imports: importEdges(files, readText(root)), targets, commit, limit });
+    io.out(args.json ? `${JSON.stringify(list, null, 2)}\n` : `${toMarkdown(list)}\n`);
+    return 0;
+  }
+  throw new Error(`unknown command ${cmd}\n\n${HELP}`);
+}

package/src/imports.mjs

@@ -0,0 +1,66 @@
+// 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 { posix } from 'node:path';
+
+const JS = /\.(?:m?js|cjs|tsx?|jsx|mts|cts|vue|svelte)$/u;
+const PY = /\.py$/u;
+const JS_IMPORT = /\b(?:import|export)\s+(?:type\s+)?(?:[\w*{}\s,$]+?\s+from\s*)?['"]([^'"\n]+)['"]|\bimport\(\s*['"]([^'"\n]+)['"]\s*\)|\brequire\(\s*['"]([^'"\n]+)['"]\s*\)/gu;
+// `from a import (b,\n c)` may span lines inside its parentheses.
+const PY_IMPORT = /^[ \t]*(?:from[ \t]+(\.*[\w.]*)[ \t]+import[ \t]+(\([^)]*\)|[\w*, \t]+)|import[ \t]+([\w., \t]+))/gmu;
+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;
+
+export function importEdges(files, read) {
+  const tracked = new Set(files);
+  const out = [];
+  const seen = new Set();
+  const add = (from, to, line) => {
+    if (!to || to === from || seen.has(`${from}\0${to}`)) return;
+    seen.add(`${from}\0${to}`);
+    out.push({ from, to, line });
+  };
+  const pyModule = (dotted, baseDir) => {
+    const base = posix.join(baseDir, ...dotted.split('.').filter(Boolean));
+    return [`${base}.py`, `${base}/__init__.py`].find((c) => tracked.has(c));
+  };
+  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;
+        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')];
+        add(from, candidates.find((c) => tracked.has(c)), lineAt(body, m.index));
+      }
+    } else if (PY.test(from)) {
+      const body = read(from);
+      if (body === null) continue;
+      for (const m of body.matchAll(PY_IMPORT)) {
+        const line = lineAt(body, m.index + m[0].search(/\S/u));
+        if (m[1] !== undefined) {
+          const dots = m[1].match(/^\.*/u)[0].length;
+          const mod = m[1].slice(dots);
+          // Relative: one dot is this package. Absolute: from the repository root, or from a src/ layout.
+          const roots = dots ? [posix.join(posix.dirname(from), ...Array(dots - 1).fill('..'))] : ['', 'src'];
+          for (const root of roots) {
+            const target = mod ? pyModule(mod, root) : null;
+            if (target) { add(from, target, line); }
+            // "from pkg import mod" may name sub-modules.
+            for (const name of m[2].replace(/[()]|#[^\n]*/gu, '').split(',').map((s) => s.trim().split(/\s+/u)[0]).filter((s) => s && s !== '*'))
+              add(from, pyModule(mod ? `${mod}.${name}` : name, root), line);
+            if (target) break;
+          }
+        } else {
+          for (const name of m[3].split(',').map((s) => s.trim().split(/\s+/u)[0]).filter(Boolean))
+            add(from, pyModule(name, '') ?? pyModule(name, 'src'), line);
+        }
+      }
+    }
+  }
+  return out;
+}

package/src/map.mjs

@@ -0,0 +1,163 @@
+// The map file: groups of files with what to check and what to watch out for, plus project rules.
+// Paths are repository paths with forward slashes. A pattern is a path, a folder ending in "/**", or a "*" glob
+// within one path segment ("src/*.js", "*.md"). Every tracked file belongs to exactly one group or to "ignore".
+
+export const MAP_FORMAT = 'readfirst/map@1';
+export const MAP_PATH = '.readfirst/map.json';
+
+const ID = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const text = (v, max = 2000) => typeof v === 'string' && v.trim() !== '' && v.length <= max;
+
+export function patternToRegExp(pattern) {
+  // Within one segment: `*` is any run of characters, `?` one character; everything else is literal.
+  const segment = (s) => s.replace(/[.+^${}()|[\]\\]/gu, '\\$&').replace(/\*/gu, '[^/]*').replace(/\?/gu, '[^/]');
+  if (pattern.endsWith('/**')) return new RegExp(`^${segment(pattern.slice(0, -3))}/`, 'u');
+  if (pattern === '**') return /^/u;
+  const body = pattern.split('**/').map(segment).join('(?:.*/)?');
+  return new RegExp(`^${body}$`, 'u');
+}
+
+export const matcher = (patterns) => {
+  const res = patterns.map(patternToRegExp);
+  return (path) => res.some((r) => r.test(path));
+};
+
+const strings = (v, where, p, max = 500) => {
+  if (!Array.isArray(v) || !v.every((s) => text(s, max))) p.push(`${where}: a list of non-empty strings`);
+  return Array.isArray(v) ? v.filter((s) => text(s, max)) : [];
+};
+
+const only = (v, keys, where, p) => {
+  for (const k of Object.keys(v)) if (!keys.includes(k)) p.push(`${where}.${k}: unknown field`);
+};
+
+const checkList = (v, where, p) => {
+  if (v === undefined) return;
+  if (!Array.isArray(v)) { p.push(`${where}: a list`); return; }
+  v.forEach((c, i) => {
+    if (!isRecord(c) || !text(c.run, 500)) { p.push(`${where}[${i}]: { run, why? }`); return; }
+    only(c, ['run', 'why'], `${where}[${i}]`, p);
+    if (c.why !== undefined && !text(c.why)) p.push(`${where}[${i}].why: text`);
+  });
+};
+
+// Problems with the map against the list of tracked files. An empty list means the map is good.
+export function mapProblems(map, files) {
+  const p = [];
+  if (!isRecord(map)) return ['map: a JSON object'];
+  only(map, ['format', 'groups', 'rules', 'ignore'], 'map', p);
+  if (map.format !== MAP_FORMAT) p.push(`format: "${MAP_FORMAT}"`);
+  if (!Array.isArray(map.groups) || !map.groups.length) return [...p, 'groups: at least one group'];
+  const ids = new Set();
+  map.groups.forEach((g, i) => {
+    const at = `groups[${i}]`;
+    if (!isRecord(g)) { p.push(`${at}: an object`); return; }
+    only(g, ['id', 'title', 'files', 'checks', 'risks'], at, p);
+    if (typeof g.id !== 'string' || !ID.test(g.id)) p.push(`${at}.id: lowercase letters, digits and "-"`);
+    else if (ids.has(g.id)) p.push(`${at}.id: ${g.id} is used twice`);
+    ids.add(g.id);
+    if (!text(g.title, 200)) p.push(`${at}.title: text`);
+    if (!strings(g.files, `${at}.files`, p).length) p.push(`${at}.files: at least one path or pattern`);
+    checkList(g.checks, `${at}.checks`, p);
+    if (g.risks !== undefined) {
+      if (!Array.isArray(g.risks)) p.push(`${at}.risks: a list`);
+      else g.risks.forEach((r, j) => {
+        if (!isRecord(r) || !text(r.text)) { p.push(`${at}.risks[${j}]: { text, files? }`); return; }
+        only(r, ['text', 'files'], `${at}.risks[${j}]`, p);
+        if (r.files !== undefined) strings(r.files, `${at}.risks[${j}].files`, p);
+      });
+    }
+  });
+  if (map.rules !== undefined) {
+    if (!Array.isArray(map.rules)) p.push('rules: a list');
+    else {
+      const ruleIds = new Set();
+      map.rules.forEach((r, i) => {
+        const at = `rules[${i}]`;
+        if (!isRecord(r)) { p.push(`${at}: an object`); return; }
+        only(r, ['id', 'rule', 'why', 'files', 'checks'], at, p);
+        if (typeof r.id !== 'string' || !ID.test(r.id)) p.push(`${at}.id: lowercase letters, digits and "-"`);
+        else if (ruleIds.has(r.id)) p.push(`${at}.id: ${r.id} is used twice`);
+        ruleIds.add(r.id);
+        if (!text(r.rule)) p.push(`${at}.rule: text`);
+        if (r.why !== undefined && !text(r.why)) p.push(`${at}.why: text`);
+        if (!strings(r.files, `${at}.files`, p).length) p.push(`${at}.files: at least one path or pattern`);
+        checkList(r.checks, `${at}.checks`, p);
+        for (const f of Array.isArray(r.files) ? r.files.filter((x) => typeof x === 'string') : [])
+          if (!files.some(matcher([f]))) p.push(`${at}.files: ${f} matches no tracked file`);
+      });
+    }
+  }
+  if (map.ignore !== undefined) strings(map.ignore, 'ignore', p);
+  if (p.length) return p;
+
+  // Placement: each tracked file in exactly one group or ignored; each group pattern matches something.
+  const ignored = matcher(map.ignore ?? []);
+  const groupMatch = map.groups.map((g) => [g.id, matcher(g.files)]);
+  const unplaced = [];
+  for (const f of files) {
+    if (f === MAP_PATH) continue;
+    const owners = groupMatch.filter(([, m]) => m(f)).map(([id]) => id);
+    if (owners.length > 1) p.push(`${f}: in more than one group (${owners.join(', ')})`);
+    else if (!owners.length && !ignored(f)) unplaced.push(f);
+  }
+  if (unplaced.length) p.push(`${unplaced.length} file(s) in no group and not ignored: ${unplaced.slice(0, 10).join(', ')}${unplaced.length > 10 ? ', ...' : ''}`);
+  for (const g of map.groups) for (const pat of g.files)
+    if (!files.some(matcher([pat]))) p.push(`groups.${g.id}.files: ${pat} matches no tracked file`);
+  return p;
+}
+
+export function assertMap(map, files) {
+  const p = mapProblems(map, files);
+  if (p.length) throw new Error(`${MAP_PATH} has problems:\n- ${p.join('\n- ')}`);
+  return map;
+}
+
+export const groupOf = (map, path) => map.groups.find((g) => matcher(g.files)(path)) ?? null;
+
+// A first map from the file tree alone: one group per top folder (one per sub-folder under src/, lib/ and app/),
+// tests together. Folders of only media or fonts get a group of their own too: code usually loads them, so the risks of
+// that code belong there; "ignore" is left for a person to fill with what nothing depends on. Titles and risks are left
+// for a person or an agent to write.
+const MEDIA = /\.(?:png|jpe?g|gif|webp|svg|ico|mp3|wav|ogg|m4a|flac|mp4|webm|mov|woff2?|ttf|otf|eot|glb|gltf|fbx|blend|zip|pdf)$/iu;
+export function draftMap(files) {
+  const nested = new Set(['src', 'lib', 'app', 'packages', 'apps']);
+  const keyOf = (path) => {
+    const parts = path.split('/');
+    if (parts.length === 1) return { key: 'root', pattern: null };
+    if (/^(?:tests?|__tests__|spec|e2e)$/u.test(parts[0])) return { key: 'tests', pattern: `${parts[0]}/**` };
+    if (nested.has(parts[0]) && parts.length > 2) return { key: `${parts[0]}-${parts[1]}`, pattern: `${parts[0]}/${parts[1]}/**` };
+    return { key: parts[0], pattern: `${parts[0]}/**` };
+  };
+  const groups = new Map();
+  const ignore = new Set();
+  const byFolder = new Map();
+  for (const f of files) {
+    if (f === MAP_PATH) continue;
+    const { key, pattern } = keyOf(f);
+    const slot = byFolder.get(key) ?? { pattern, files: [] };
+    slot.files.push(f);
+    byFolder.set(key, slot);
+  }
+  for (const [key, slot] of byFolder) {
+    const media = Boolean(slot.pattern) && slot.files.every((f) => MEDIA.test(f));
+    const id = key.toLowerCase().replace(/[^a-z0-9-]+/gu, '-').replace(/^-+|-+$/gu, '').slice(0, 64) || 'group';
+    const patterns = slot.pattern ? [slot.pattern] : slot.files;
+    const prev = groups.get(id);
+    const title = media
+      ? `TODO: what loads the media files in ${slot.pattern} (binary, not read)`
+      : `TODO: what ${slot.pattern ?? 'the top-level files'} ${slot.pattern ? 'is' : 'are'} for`;
+    groups.set(id, { id, title, files: prev ? [...prev.files, ...patterns] : patterns, checks: [], risks: [] });
+  }
+  // A nested pattern ("src/a/**") and the parent's loose files ("src/x.js") must not overlap; loose files under a nested root
+  // become their own group.
+  for (const root of nested) {
+    const loose = files.filter((f) => f.startsWith(`${root}/`) && f.split('/').length === 2);
+    if (!loose.length) continue;
+    const covered = groups.get(root);
+    const hasNested = [...byFolder.values()].some((slot) => slot.pattern?.startsWith(`${root}/`) && slot.pattern !== `${root}/**`);
+    if (covered && hasNested) covered.files = covered.files.filter((p) => p !== `${root}/**`).concat(loose);
+  }
+  return { format: MAP_FORMAT, groups: [...groups.values()].sort((a, b) => a.id.localeCompare(b.id)), rules: [], ignore: [...ignore].sort() };
+}

package/src/prompt.mjs

@@ -0,0 +1,26 @@
+// The brief for a coding agent (Claude Code, Cursor, Codex...) to turn the drafted map into a useful one. The map is
+// filled by the agent the team already uses, so readfirst itself calls no model and needs no key.
+import { MAP_FORMAT, MAP_PATH } from './map.mjs';
+
+export function agentBrief(map) {
+  return `You are filling in ${MAP_PATH} for this repository. readfirst uses it to tell people and coding agents what to
+read and check before they change a file. A first draft is already there (groups by folder, format ${MAP_FORMAT}).
+
+Do this:
+1. For each group, read its files enough to write:
+   - "title": one line on what this part of the code does.
+   - "checks": the commands that prove this part still works, e.g. {"run": "npm test -- auth", "why": "login and sessions"}.
+     Use commands that exist in this repo (package.json scripts, Makefile, pytest...). Leave the list empty if there is none.
+   - "risks": things a newcomer would get wrong here, each {"text": "...", "files": ["optional/path/or/pattern/**"]}.
+     Good risks are specific: hidden coupling, data that must stay compatible, money or auth paths, slow or paid calls,
+     generated files that must not be edited by hand. Do not write generic advice ("be careful", "write tests").
+2. Split or merge groups when the folder split is wrong. Every tracked file must stay in exactly one group or in "ignore".
+   Patterns: a path, "folder/**", or a "*" glob within one segment.
+3. Add "rules": promises the code must keep, each {"id": "kebab-id", "rule": "...", "why": "...", "files": [...],
+   "checks": [{"run": "..."}]}. Take them from comments, docs, tests and commit messages. Only write rules you can point to
+   in the code or docs. Ask the user for the ones only they know.
+4. Run \`npx readfirst check\` until it says the map is good, then show the user the diff of ${MAP_PATH}.
+
+Current groups: ${map.groups.map((g) => `${g.id} (${g.files.join(', ')})`).join('; ')}.
+`;
+}

package/src/readlist.mjs

@@ -0,0 +1,101 @@
+// The read list for files someone is about to change: the rules that cover them, the risks written for their group,
+// the checks to run (the group's commands, the rules' commands, and the tests that import them), and who uses them.
+import { 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;
+export const isTest = (path) => TEST.test(path);
+
+// The read list for no files, so `diff --json` is always JSON.
+export const emptyList = (commit = null) => ({ format: READ_LIST_FORMAT, commit, targets: [], rules: [], risks: [], checks: [], tests: [], usedBy: [], usedByIndirectly: 0, notCovered: [], truncated: { tests: 0, usedBy: 0 } });
+
+export function readList({ map, files, imports, targets, commit = null, limit = 30 }) {
+  if (!targets.length || targets.some((t) => !t.trim())) throw new Error('give at least one file path, none empty');
+  const tracked = new Set(files);
+  const ignored = matcher(map.ignore ?? []);
+  const importers = new Map();
+  for (const e of imports) importers.set(e.to, [...(importers.get(e.to) ?? []), e]);
+
+  const out = { format: READ_LIST_FORMAT, commit, targets: [], rules: [], risks: [], checks: [], tests: [], usedBy: [], usedByIndirectly: 0, notCovered: [] };
+  const seen = { rules: new Map(), risks: new Map(), checks: new Map(), tests: new Map(), usedBy: new Map() };
+  const note = (kind, key, item, target) => {
+    const have = seen[kind].get(key);
+    if (have) { if (!have.for.includes(target)) have.for.push(target); return; }
+    const row = { ...item, for: [target] };
+    seen[kind].set(key, row);
+    out[kind].push(row);
+  };
+  const indirect = new Set();
+
+  for (const raw of targets) {
+    const target = raw.replace(/^\.\//u, '').replace(/\\/gu, '/');
+    if (!tracked.has(target) && target !== MAP_PATH) {
+      out.targets.push({ path: target, group: null, status: 'NOT_TRACKED' });
+      out.notCovered.push({ path: target, why: 'not a tracked file at this commit (new, deleted or misspelt)' });
+      continue;
+    }
+    if (target === MAP_PATH) { out.targets.push({ path: target, group: null, status: 'MAP' }); continue; }
+    const group = groupOf(map, target);
+    out.targets.push({ path: target, group: group?.id ?? null, status: group ? 'IN_MAP' : ignored(target) ? 'IGNORED' : 'NO_GROUP' });
+    if (!group) {
+      out.notCovered.push({ path: target, why: ignored(target) ? 'ignored by the map' : 'in no group: run `readfirst check`' });
+    } else {
+      for (const r of group.risks ?? []) if (!r.files || matcher(r.files)(target)) note('risks', `${group.id}\0${r.text}`, { group: group.id, text: r.text }, target);
+      for (const c of group.checks ?? []) note('checks', c.run, { run: c.run, why: c.why ?? `checks for ${group.title}`, from: `group ${group.id}` }, target);
+    }
+    for (const rule of map.rules ?? []) {
+      if (!matcher(rule.files)(target)) continue;
+      note('rules', rule.id, { id: rule.id, rule: rule.rule, why: rule.why ?? null, files: rule.files }, target);
+      for (const c of rule.checks ?? []) note('checks', c.run, { run: c.run, why: c.why ?? `keeps rule ${rule.id}`, from: `rule ${rule.id}` }, target);
+    }
+    // Who reaches the target through imports: direct importers by line, then everything further up, for tests.
+    const depth = new Map([[target, 0]]);
+    const queue = [target];
+    while (queue.length) {
+      const at = queue.shift();
+      for (const e of importers.get(at) ?? []) {
+        if (depth.has(e.from)) continue;
+        depth.set(e.from, depth.get(at) + 1);
+        queue.push(e.from);
+        if (at === target && !isTest(e.from)) note('usedBy', e.from, { path: e.from, line: e.line }, target);
+        if (isTest(e.from)) note('tests', e.from, { path: e.from, via: at === target ? null : at }, target);
+        else if (at !== target) indirect.add(e.from);
+      }
+    }
+    if (isTest(target)) note('tests', target, { path: target, via: null }, target);
+  }
+  for (const u of out.usedBy) indirect.delete(u.path);
+  out.usedByIndirectly = indirect.size;
+  out.tests.sort((a, b) => Number(a.via !== null) - Number(b.via !== null) || a.path.localeCompare(b.path));
+  out.truncated = { tests: Math.max(0, out.tests.length - limit), usedBy: Math.max(0, out.usedBy.length - limit) };
+  out.tests = out.tests.slice(0, limit);
+  out.usedBy = out.usedBy.slice(0, limit);
+  return out;
+}
+
+// checklist: checks as task-list boxes (for PR comments); heading: the title line, or null for none.
+export function toMarkdown(list, { checklist = false, heading } = {}) {
+  const title = heading === undefined ? `# Read first: ${list.targets.map((t) => `\`${t.path}\``).join(', ')}` : heading;
+  const lines = title === null ? [] : [title, ''];
+  const many = list.targets.length > 1;
+  const forWhom = (row, also = null) => {
+    const parts = [also, many ? row.for.join(', ') : null].filter(Boolean);
+    return parts.length ? ` _(${parts.join(' · ')})_` : '';
+  };
+  const section = (title, rows, render) => {
+    if (!rows.length) return;
+    lines.push(`## ${title}`, '', ...rows.map(render), '');
+  };
+  section('Rules that must keep holding', list.rules, (r) => `- **${r.id}**: ${r.rule}${r.why ? ` — why: ${r.why}` : ''}${forWhom(r)}`);
+  section('Watch out', list.risks, (r) => `- ${r.text}${forWhom(r, `group ${r.group}`)}`);
+  section('Run these checks', list.checks, (c) => `- ${checklist ? '[ ] ' : ''}\`${c.run}\` — ${c.why}${forWhom(c)}`);
+  section('Tests that reach this code', list.tests, (t) => `- \`${t.path}\`${t.via ? ` (through \`${t.via}\`)` : ''}${forWhom(t)}`);
+  if (list.truncated?.tests) lines.splice(lines.length - 1, 0, `- …and ${list.truncated.tests} more`);
+  section('Used by', list.usedBy, (u) => `- \`${u.path}:${u.line}\`${forWhom(u)}`);
+  if (list.truncated?.usedBy) lines.splice(lines.length - 1, 0, `- …and ${list.truncated.usedBy} more direct users`);
+  if (list.usedByIndirectly) lines.push(`${list.usedByIndirectly} more file(s) use this code indirectly.`, '');
+  section('Not covered by the map', list.notCovered, (n) => `- \`${n.path}\`: ${n.why}`);
+  if (!list.rules.length && !list.risks.length && !list.checks.length && !list.tests.length && !list.usedBy.length && !list.notCovered.length)
+    lines.push('Nothing in the map is tied to these files.', '');
+  return lines.join('\n');
+}