readfirst 0.8.0 → 0.10.0

package/README.md

@@ -10,16 +10,27 @@ 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`.
 
 ```sh
-npx readfirst init --agent   # first map from your folders, checks from your scripts, plus the line for CLAUDE.md / AGENTS.md
+npx readfirst init --agent --ci   # first map from your folders, checks from your scripts, the line for CLAUDE.md / AGENTS.md,
+                                  # and the GitHub Action that comments on PRs and keeps the map in step
 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
 ```
 
+In a monorepo, each workspace package with its own `package.json` becomes a group with its own checks
+(`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
@@ -68,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.
@@ -191,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
@@ -200,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.8.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/cli.mjs

@@ -1,5 +1,5 @@
 // readfirst: what to read and check before changing a file.
-//   readfirst init [--agent]       write a first .readfirst/map.json from the file tree (and the agent-notes line)
+//   readfirst init [--agent] [--ci] write a first .readfirst/map.json from the file tree (and the agent-notes line, the Action)
 //   readfirst prompt               the brief for a coding agent to fill in titles, checks, risks and rules
 //   readfirst prompt --labels <lang>  the brief for personal labels (a translation and plain notes) for the view
 //   readfirst check                the map covers every tracked file and is well formed
@@ -15,9 +15,9 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { basename, isAbsolute, join, relative } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import { importEdges } from './imports.mjs';
-import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems, settleMap } from './map.mjs';
+import { MAP_PATH, assertMap, draftChecks, draftMap, fixMap, mapProblems, settleMap } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
@@ -27,7 +27,7 @@ import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
 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 init [--agent] [--ci] write a first ${MAP_PATH} from the file tree
   readfirst prompt               brief for your coding agent to fill in the map
   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
@@ -41,7 +41,8 @@ const HELP = `readfirst — what to read and check before changing a file
   readfirst prompt --labels <lang>  brief for your agent to write personal labels for the view (e.g. ko, en)
 
 Options: --root <dir>, --json, --limit <n>, --timeout <s> (verify, per check; default 900), --force (init: replace the map),
-         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules)`;
+         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules),
+         --ci (init: add .github/workflows/readfirst.yml, the Action with auto-fix)`;
 
 function parse(argv) {
   const args = { _: [], json: false };
@@ -54,6 +55,7 @@ function parse(argv) {
     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 === '--ci') args.ci = 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; }
@@ -255,6 +257,34 @@ export function runStopHook(input, { stateDir = tmpdir(), timeout = 600 } = {})
   }
 }
 
+export const WORKFLOW_PATH = '.github/workflows/readfirst.yml';
+// The Action as `init --ci` writes it: on each PR, the read-list comment, and new files placed in the map on the PR's
+// branch (auto-fix). Never over a workflow that is already there.
+export function writeWorkflow(root) {
+  const at = join(root, WORKFLOW_PATH);
+  if (existsSync(at)) return false;
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, [
+    '# readfirst: one comment per PR with the rules, risks and checks for the files it changes,',
+    '# and new files placed in .readfirst/map.json on the PR branch (auto-fix). https://github.com/jeonghun917/readfirst',
+    'name: readfirst',
+    'on: pull_request',
+    'permissions:',
+    '  contents: write       # auto-fix commits the map update to the PR branch',
+    '  pull-requests: write  # the comment',
+    'jobs:',
+    '  readfirst:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0',
+    '      - uses: jeonghun917/readfirst@v0',
+    '        with:',
+    '          auto-fix: true',
+    '',
+  ].join('\n'));
+  return true;
+}
+
 export const HOOK_COMMAND = 'npx --yes readfirst hook';
 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
@@ -315,14 +345,21 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     const map = draftMap(files, readText(root));
     mkdirSync(join(root, '.readfirst'), { recursive: true });
     writeFileSync(at, `${JSON.stringify(map, null, 2)}\n`);
-    const checks = map.groups.find((g) => g.checks.length)?.checks ?? [];
-    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? "" : "s"}${checks.length ? `, checks found: ${checks.map((c) => c.run).join(', ')}` : ''}.\n`);
+    const repoChecks = draftChecks(files, readText(root)).map((c) => c.run);
+    const scoped = map.groups.filter((g) => g.checks.length && g.checks.some((c) => !repoChecks.includes(c.run))).length;
+    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? '' : 's'}${repoChecks.length ? `, checks found: ${repoChecks.join(', ')}` : ''}${scoped ? `; ${scoped} workspace package${scoped === 1 ? '' : 's'} got ${scoped === 1 ? 'its' : 'their'} own checks` : ''}.\n`);
     if (args.agent) {
       const wrote = addAgentLine(root);
       io.out(wrote.length ? `added the read-first line to ${wrote.join(', ')}.\n` : 'your agent notes already mention readfirst.\n');
-      io.out('Using Claude Code? `readfirst hook --install` hands it the read list automatically before each edit.\n');
     }
-    io.out(`Next: run \`readfirst prompt\` and give the brief to your coding agent, or fill in titles, checks, risks and rules by hand.${args.agent ? '' : '\nTip: `readfirst init --agent` also adds the one line your coding agent needs to CLAUDE.md or AGENTS.md.'}\n`);
+    if (args.ci) io.out(writeWorkflow(root) ? `wrote ${WORKFLOW_PATH}: a PR comment with the read list, and new files placed in the map on the PR branch.\n` : `${WORKFLOW_PATH} already exists; left as it is.\n`);
+    const next = [
+      'run `readfirst prompt` and give the brief to your coding agent (or fill in titles, risks and rules by hand)',
+      ...(args.agent ? [] : ['`readfirst init --agent` would add the one line your agent needs to CLAUDE.md or AGENTS.md']),
+      'Claude Code: `readfirst hook --install` gives it the read list before each edit (`--verify` also runs the checks before it finishes)',
+      ...(args.ci ? [] : ['`readfirst init --ci` would add the GitHub Action that comments on PRs and keeps the map in step']),
+    ];
+    io.out(`Next:\n${next.map((n) => `- ${n}`).join('\n')}\n`);
     return 0;
   }
   if (cmd === 'prompt') {

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.
@@ -160,9 +185,44 @@ export function draftMap(files, read = () => null) {
     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);
   }
+  // A folder that is a workspace package of its own (packages/db/package.json) gets that package's checks, run through the
+  // package manager's workspace filter, so verify runs the package's tests instead of the whole repository's. Its title
+  // comes from the package's description when it has one.
+  for (const g of groups.values()) {
+    const dir = g.files.length === 1 && /^(.+)\/\*\*$/u.exec(g.files[0])?.[1];
+    if (!dir || !files.includes(`${dir}/package.json`)) continue;
+    let pkg;
+    try { pkg = JSON.parse(read(`${dir}/package.json`) ?? ''); } catch { continue; }
+    const checks = workspaceChecks(files, dir, pkg);
+    if (checks.length) g.checks = checks;
+    const about = typeof pkg?.description === 'string' ? pkg.description.trim().replace(/\s+/gu, ' ') : '';
+    if (about && g.title.startsWith('TODO:')) g.title = `${typeof pkg.name === 'string' ? `${pkg.name}: ` : ''}${about}`.slice(0, 200);
+  }
   return { format: MAP_FORMAT, groups: [...groups.values()].sort((a, b) => a.id.localeCompare(b.id)), rules: [], ignore: [...ignore].sort() };
 }
 
+const packageManager = (has) => (has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm');
+const PLACEHOLDER = /no test specified/u;
+// The scripts worth running as checks, in order, with what each covers.
+const scriptChecks = (scripts, run) => [
+  ...(typeof scripts.test === 'string' && !PLACEHOLDER.test(scripts.test) ? [{ run: run('test'), why: 'the test suite' }] : []),
+  ...['typecheck', 'type-check', 'check-types', 'lint'].filter((n) => typeof scripts[n] === 'string').map((n) => ({ run: run(n), why: n === 'lint' ? 'lint rules' : 'types' })),
+];
+
+// One workspace package's own scripts, scoped to it: pnpm --filter, yarn workspace, bun --filter or npm -w.
+export function workspaceChecks(files, dir, pkg) {
+  const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const name = typeof pkg?.name === 'string' && pkg.name ? pkg.name : null;
+  const pm = packageManager(new Set(files));
+  const run = (script) => {
+    if (pm === 'pnpm') return `pnpm --filter ${name ?? `./${dir}`} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'yarn' && name) return `yarn workspace ${name} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'bun' && name) return `bun --filter ${name} run ${script}`;
+    return script === 'test' ? `npm test -w ${dir}` : `npm run ${script} -w ${dir}`;
+  };
+  return scriptChecks(scripts, run).map((c) => ({ ...c, why: `${c.why} of ${name ?? dir}` }));
+}
+
 // Repairs the two ways a good map goes stale as code moves, without guessing at meaning:
 // - a tracked file in no group joins the group of its nearest neighbour (same folder, else the closest parent folder);
 //   a new folder whose files are all unplaced joins as "<folder>/**", a lone new file by its path;
@@ -191,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));
@@ -244,11 +312,9 @@ export function draftChecks(files, read = () => null) {
   if (has.has('package.json')) {
     let scripts = {};
     try { scripts = JSON.parse(read('package.json') ?? '{}').scripts ?? {}; } catch { scripts = {}; }
-    const pm = has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm';
+    const pm = packageManager(has);
     const run = (name) => (pm === 'npm' ? (name === 'test' ? 'npm test' : `npm run ${name}`) : `${pm} ${name === 'test' && pm !== 'bun' ? 'test' : `run ${name}`}`);
-    const placeholder = /no test specified/u;
-    if (typeof scripts.test === 'string' && !placeholder.test(scripts.test)) add(run('test'), 'the test suite');
-    for (const name of ['typecheck', 'type-check', 'check-types', 'lint']) if (typeof scripts[name] === 'string') add(run(name), name === 'lint' ? 'lint rules' : 'types');
+    for (const c of scriptChecks(scripts, run)) add(c.run, c.why);
   }
   const makefile = has.has('Makefile') ? read('Makefile') ?? '' : '';
   if (/^test:/mu.test(makefile)) add('make test', 'the test suite (Makefile)');

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');
 }