readfirst 0.9.0 → 0.10.0

package/README.md

@@ -10,6 +10,8 @@ knowledge in one file next to the code and hands it out, file by file, at the mo
 
 No server, no account, no model calls. It reads your git checkout and `.readfirst/map.json`.
 
+Filled maps for real repositories (vercel/ai, cal.com, excalidraw and two more), with sample output: [examples/](examples/).
+
 ## Start
 
 Any language; needs Node 20+ for `npx`.
@@ -25,6 +27,10 @@ In a monorepo, each workspace package with its own `package.json` becomes a grou
 (`pnpm --filter @acme/db test`, `yarn workspace …`, `npm test -w …`), so `verify` runs that package's tests, not the
 whole repository's, and its description becomes the group's title.
 
+The first map is the part nobody gets to. [readfirst-app](https://readfirst-cloud.vercel.app/) can write it for you: it
+reads the repository and your notes, and opens the map as a pull request with the file and line behind every risk.
+Free once per account; see [Hosted](#hosted-readfirst-app).
+
 Commit `.readfirst/map.json`. From then on:
 
 ```sh
@@ -73,6 +79,8 @@ choose to).
 npx readfirst view               # the map as a city in one HTML page: .readfirst/local/view.html
 ```
 
+![vercel/ai as a city: each workspace package is a neighbourhood, and the panel shows the rules for one file](docs/readfirst-city.jpg)
+
 Groups are neighbourhoods, files are buildings (taller when more code depends on them), and traffic between
 neighbourhoods is the imports between them. A red-lit building has a risk on it; an amber one is under a rule. Point at a
 building to see its read list. The page loads three.js from a CDN.
@@ -196,6 +204,9 @@ runs. If your branch protection requires checks, pass a GitHub App or personal t
   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.
+- **hotspots** (optional, usually written by a tool): functions where risky code meets a rule, as
+  `{ "file", "symbol", "line", "labels": ["db-write", "money"], "rules"?: [...], "note"? }`. `read` lists the ones in the
+  file being changed under "Hot spots in this code"; `fix` drops those whose file is gone.
 
 Tests are found from imports: a test that imports the file directly, or through other files, is listed.
 Imports are read for JavaScript/TypeScript, Python, Go, Rust, Elixir, C#, Java, Kotlin, Ruby (including Rails autoloaded
@@ -205,6 +216,20 @@ constants) and PHP (through composer's PSR-4 map). `init` suggests the checks th
 
 readfirst needs Node 20 or newer to run, whatever language the project is in. `npx` comes with Node.
 
+## Hosted (readfirst-app)
+
+Everything above is free and stays free. The GitHub App adds the parts that take a person's time:
+
+- **First map:** install [readfirst-app](https://github.com/apps/readfirst-app/installations/new) on a repository and
+  comment `/readfirst fill` on any issue. 5–20 minutes later a pull request arrives with the map, each risk and rule
+  citing the file and line it came from. Free once per account, for repositories up to 200 files.
+- **Pro, $19/month:** fills for up to 3 private repositories that also read where the code broke before and the known
+  traps of its libraries; after each merge, a small PR when the map needs it; on every pull request, a comment on the
+  files it touches that broke before. [Get Pro](https://readfirst-cloud.vercel.app/#pricing).
+
+The CLI, hook, MCP server and Action never send your code anywhere. What the app reads and keeps is listed on
+[the site](https://readfirst-cloud.vercel.app/#your-code).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.9.0",
+  "version": "0.10.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/map.mjs

@@ -42,11 +42,35 @@ const checkList = (v, where, p) => {
   });
 };
 
+// Hot spots: functions where code that does something risky (writes the database, moves money, calls out) meets a rule.
+// Optional; written by tools, read by `read`. Each names a tracked file, a symbol in it and the line it starts on.
+export const MAX_HOTSPOTS = 500;
+function hotspotProblems(map, files, p) {
+  if (!Array.isArray(map.hotspots)) { p.push('hotspots: a list'); return; }
+  if (map.hotspots.length > MAX_HOTSPOTS) p.push(`hotspots: at most ${MAX_HOTSPOTS}`);
+  const ruleIds = new Set((Array.isArray(map.rules) ? map.rules : []).map((r) => r?.id));
+  const tracked = new Set(files);
+  map.hotspots.forEach((h, i) => {
+    const at = `hotspots[${i}]`;
+    if (!isRecord(h)) { p.push(`${at}: { file, symbol, line, labels, rules?, note? }`); return; }
+    only(h, ['file', 'symbol', 'line', 'labels', 'rules', 'note'], at, p);
+    if (typeof h.file !== 'string' || !h.file) p.push(`${at}.file: a path`);
+    else if (!tracked.has(h.file)) p.push(`${at}.file: ${h.file} is not a tracked file`);
+    if (!text(h.symbol, 200)) p.push(`${at}.symbol: text`);
+    if (!Number.isInteger(h.line) || h.line < 1) p.push(`${at}.line: a line number`);
+    const labels = strings(h.labels, `${at}.labels`, p, 64);
+    if (!labels.length) p.push(`${at}.labels: at least one label`);
+    for (const l of labels) if (!ID.test(l)) p.push(`${at}.labels: ${l}: lowercase letters, digits and "-"`);
+    if (h.rules !== undefined) for (const r of strings(h.rules, `${at}.rules`, p, 64)) if (!ruleIds.has(r)) p.push(`${at}.rules: no rule ${r}`);
+    if (h.note !== undefined && !text(h.note, 500)) p.push(`${at}.note: text`);
+  });
+}
+
 // Problems with the map against the list of tracked files. An empty list means the map is good.
 export function mapProblems(map, files, { placement = true } = {}) {
   const p = [];
   if (!isRecord(map)) return ['map: a JSON object'];
-  only(map, ['format', 'groups', 'rules', 'ignore'], 'map', p);
+  only(map, ['format', 'groups', 'rules', 'ignore', 'hotspots'], '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();
@@ -90,6 +114,7 @@ export function mapProblems(map, files, { placement = true } = {}) {
     }
   }
   if (map.ignore !== undefined) strings(map.ignore, 'ignore', p);
+  if (map.hotspots !== undefined) hotspotProblems(map, files, p);
   if (p.length || !placement) return p;
 
   // Placement: each tracked file in exactly one group or ignored; each group pattern matches something.
@@ -226,6 +251,14 @@ export function fixMap(map, files) {
     if (keep.length) r.files = keep;
   }
 
+  if (Array.isArray(out.hotspots)) {
+    const tracked = new Set(files);
+    const gone = out.hotspots.filter((h) => !tracked.has(h?.file));
+    for (const h of gone) changes.push(`hotspots: dropped ${h?.symbol} in ${h?.file} (file gone)`);
+    out.hotspots = out.hotspots.filter((h) => tracked.has(h?.file));
+    if (!out.hotspots.length) delete out.hotspots;
+  }
+
   const ignored = matcher(out.ignore ?? []);
   const owner = (f) => out.groups.find((g) => matcher(g.files)(f));
   const unplaced = files.filter((f) => f !== MAP_PATH && !ignored(f) && !owner(f));

package/src/readlist.mjs

@@ -9,7 +9,7 @@ const TEST = /(^|\/)(?:tests?|__tests__|spec|e2e)\/|\.(?:test|spec)\.[cm]?[jt]sx
 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 const emptyList = (commit = null) => ({ format: READ_LIST_FORMAT, commit, targets: [], rules: [], risks: [], hotspots: [], 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');
@@ -18,8 +18,8 @@ export function readList({ map, files, imports, targets, commit = null, limit =
   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 out = { format: READ_LIST_FORMAT, commit, targets: [], rules: [], risks: [], hotspots: [], checks: [], tests: [], usedBy: [], usedByIndirectly: 0, notCovered: [] };
+  const seen = { rules: new Map(), risks: new Map(), hotspots: 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; }
@@ -52,6 +52,7 @@ export function readList({ map, files, imports, targets, commit = null, limit =
       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 h of map.hotspots ?? []) if (h.file === target) note('hotspots', `${h.file}\0${h.symbol}\0${h.line}`, { file: h.file, symbol: h.symbol, line: h.line, labels: h.labels, rules: h.rules ?? [], note: h.note ?? null }, 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);
@@ -73,6 +74,7 @@ export function readList({ map, files, imports, targets, commit = null, limit =
     }
     if (isTest(target)) note('tests', target, { path: target, via: null }, target);
   }
+  out.hotspots.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
   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));
@@ -97,6 +99,7 @@ export function toMarkdown(list, { checklist = false, heading } = {}) {
   };
   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('Hot spots in this code', list.hotspots ?? [], (h) => `- \`${h.symbol}\` (\`${h.file}:${h.line}\`): ${h.labels.join(', ')}${h.rules.length ? `, under ${h.rules.map((r) => `**${r}**`).join(', ')}` : ''}${h.note ? `: ${h.note}` : ''}`);
   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`);
@@ -104,7 +107,7 @@ export function toMarkdown(list, { checklist = false, heading } = {}) {
   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)
+  if (!list.rules.length && !list.risks.length && !(list.hotspots ?? []).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');
 }