Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Scan: keep files over the size limit on the map, and say so

Hayden Smitha9a9881f39a8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 865aab9..abc4e63 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
- **Fewer false Health alarms on FastAPI:** a check added where a router is included, like `app.include_router(admin.router, dependencies=[Depends(require_admin)])`, now protects every endpoint of that router, as `app.use('/admin', requireStaff, adminRouter)` already did on Express. A database session added there still doesn't count as a sign-in check. Fixed by @stevensiht in #15.
- **FastAPI routers found by the name they're imported under:** a router imported under another name (`from app.routes import campaigns as campaign_routes`) gets its prefix and its checks, and a package that shares a router's name (`from app.platform import pricing` beside a `platform` router) is no longer mistaken for it. Fixed by @stevensiht in #15.
- **No more false alarm for analytics and map tokens:** Health no longer calls Cloudflare Web Analytics' beacon token or a Mapbox public token (`pk.…`) a leaked secret. Both are public by design: the page has to send them for analytics or maps to work. Reported by @CplSyx in #23.
+- **Big files no longer vanish from the map:** files up to 2 MB are now read in full (up from 512 KB). A file over the limit still appears with its line count, the scan lists it, Health includes it among the very large files, and its card says its connections and secrets weren't checked. Reported by @Rasherb69 in #16.
## 0.3.0 (2026-10-29)
diff --git a/docs/development.md b/docs/development.md
index 42f00fd..ad09cc8 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -82,6 +82,7 @@ The tests use Node's built-in test runner, so there's nothing to install (`npm t
| `firebase.test.mjs` | Firebase Cloud Functions: callables and onRequest functions as endpoints, the website's calls to them, Screens, Health, background functions (React + Firebase sample in `fixtures/`) |
| `blueprint.test.mjs` | a map planned from a PRD before any code exists: plan.json errors, endpoints and calls, Screens, the design review, refreshing and switching to the real code (sample PRD in `fixtures/`) |
| `blueprint-change.test.mjs` | changing a blueprint from the map: the agent's updated plan is checked, saved and highlighted, retried once when it fails the checks, and undone (stand-in CLI in `fixtures/fake-cli/`) |
+| `large-files.test.mjs` | files over the scan's size limit stay on the map with their line count, and the scan, Health and the map say they weren't read |
| `sample-app.test.mjs` | a whole map of a two-repo shop: endpoints, cross-repo requests, Health, offline map, no secret values written, updates |
| `serve.test.mjs` | the map's server: 127.0.0.1 only, token and same-origin checks, nothing served from outside its folder |
| `ask.test.mjs` | asking through Claude Code or Codex: which one is used, read-only, follow-ups, sign-in errors (stand-in CLIs in `fixtures/fake-cli/`) |
diff --git a/skills/floorplan/assets/viewer.html b/skills/floorplan/assets/viewer.html
index 385b82d..82fc819 100644
--- a/skills/floorplan/assets/viewer.html
+++ b/skills/floorplan/assets/viewer.html
@@ -1471,6 +1471,7 @@ function itemPanel(item, viaConnector) {
} else if (i.type === 'file' || i.type === 'module') {
const f = i.f, fid = 'f:' + f.p, url = editorUrl(f.p);
if (f.note) html += `<div class="callout">${h(f.note)}</div>`;
+ if (f.tooLarge) html += `<div class="callout">Too big for Floorplan to read, so what it uses, its endpoints and any secrets in it weren’t checked. Ask Claude or Codex to update the floorplan with a bigger file limit to include it.</div>`;
html += pathBox(f.p);
if (url) actions.push(`<a class="btn soft" href="${url}">${iconI('open')}Open in editor</a>`);
if (actions.length) html += `<div class="actions">${actions.join('')}</div>`;
diff --git a/skills/floorplan/scripts/build.mjs b/skills/floorplan/scripts/build.mjs
index 94b767f..d84c587 100644
--- a/skills/floorplan/scripts/build.mjs
+++ b/skills/floorplan/scripts/build.mjs
@@ -397,6 +397,7 @@ const graph = {
p: f.path, n: owner.get(f.path), r: f.repo, l: f.lang || f.category, loc: f.loc,
name: d?.name || f.name || fallbackFileName(f.path), d: d?.d || f.desc || f.doc || '', ...(d?.d || f.desc ? {} : { auto: true }),
...(f.doc ? { doc: f.doc } : {}),
+ ...(f.tooLarge ? { tooLarge: true } : {}),
...(d?.review ? { review: d.review } : {}),
...(f.h ? { h: f.h, sig: f.sig } : {}),
...(f.symbols ? { s: f.symbols.map((s) => [s.name, s.kind, s.line, s.default ? 1 : 0, s.doc || '']) } : {}),
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
index ed13ff5..56370fd 100644
--- a/skills/floorplan/scripts/lib/health.mjs
+++ b/skills/floorplan/scripts/lib/health.mjs
@@ -676,7 +676,7 @@ export function buildHealth({ graph, scan, arch, root }) {
const want = new Map(candidates.map((f) => [stemOf(f.p), f.p]));
const mentioned = new Set();
for (const f of scan.files) {
- if (!['code', 'config', 'docs'].includes(f.category) || f.bytes > 524288) continue;
+ if (!['code', 'config', 'docs'].includes(f.category) || f.tooLarge) continue;
let src;
try { src = fs.readFileSync(path.join(root, f.path), 'utf8'); } catch { continue; }
for (const tok of new Set(src.match(/[\w$-]+/g) || [])) { const p = want.get(tok); if (p && p !== f.path) mentioned.add(p); }
@@ -713,7 +713,7 @@ export function buildHealth({ graph, scan, arch, root }) {
title: big.length === 1 ? 'One file is very large' : `${big.length} files are very large`,
detail: `${big.length === 1 ? 'This file has' : 'These files each have'} over 1,000 lines${huge.length ? ` (the biggest has ${big[0].loc.toLocaleString('en-US')})` : ''}. AI assistants read and edit big files less reliably: they lose track of what's where and can break one part while fixing another. Splitting them into smaller files by job makes future changes safer.`,
items: big.slice(0, 24).map((f) => 'f:' + f.p),
- notes: Object.fromEntries(big.slice(0, 24).map((f) => ['f:' + f.p, `${f.loc.toLocaleString('en-US')} lines`])),
+ notes: Object.fromEntries(big.slice(0, 24).map((f) => ['f:' + f.p, `${f.loc.toLocaleString('en-US')} lines${f.tooLarge ? ': too big for Floorplan to read, so what it connects to and any secrets in it weren’t checked' : ''}`])),
locations: big.map((f) => ({ file: f.p, line: 1 })),
fix: [`Refactor plan: these files are very large:`, ...big.slice(0, 15).map((f) => `- ${f.p} (${f.loc.toLocaleString('en-US')} lines)`), ``, `Start with ${big[0].p}. Read it and propose how to split it into smaller files, each with one clear job (for example by feature or by type of work), keeping every public function name and behaviour the same. Show me the plan first. After I approve, move code in small steps, update the imports, and run the tests after each step. Don't change behaviour.`].join('\n'),
});
diff --git a/skills/floorplan/scripts/scan.mjs b/skills/floorplan/scripts/scan.mjs
index 6da05d7..c2eced4 100644
--- a/skills/floorplan/scripts/scan.mjs
+++ b/skills/floorplan/scripts/scan.mjs
@@ -3,7 +3,7 @@
// symbols and HTTP routes/calls, resolve them, and write floorplan/.cache/scan.json.
// Prints a compact summary meant to be read by Claude (the JSON itself can be large).
//
-// usage: node scan.mjs [root] [--out <file>] [--include-worktrees] [--max-file-kb 512]
+// usage: node scan.mjs [root] [--out <file>] [--include-worktrees] [--max-file-kb 2048]
import fs from 'node:fs';
import { createHash } from 'node:crypto';
@@ -19,7 +19,7 @@ const args = parseArgs(process.argv.slice(2));
const root = path.resolve(args._[0] || '.');
const outDir = args.out ? path.dirname(path.dirname(path.resolve(args.out))) : mapDir(root);
const outFile = path.resolve(args.out || path.join(outDir, '.cache', 'scan.json'));
-const maxBytes = (Number(args['max-file-kb']) || 512) * 1024;
+const maxBytes = (Number(args['max-file-kb']) || 2048) * 1024;
const t0 = Date.now();
const hash = (s) => createHash('sha1').update(s).digest('hex').slice(0, 12);
@@ -84,12 +84,28 @@ for (const { path: p, repo } of fileList) {
try { const iss = findIssues(src, f); if (iss?.length) f.issues = iss; } catch (e) { f.healthError = String(e.message || e); }
try { const scr = findScreens(src, f); if (scr?.length) f.screens = scr; } catch (e) { f.screensError = String(e.message || e); }
}
- } else if (category === 'code') {
+ } else if (category === 'code' || category === 'config' || category === 'docs') {
+ // too big to read and parse, but still on the map: count its lines without loading it all
f.tooLarge = true;
+ f.loc = countLines(abs);
}
files.push(f);
}
+/** Lines in a file, read in chunks so a huge file is never held in memory at once. */
+function countLines(abs) {
+ let fd, n = 0, last = 10;
+ try {
+ fd = fs.openSync(abs, 'r');
+ const buf = Buffer.alloc(1 << 20);
+ for (let got; (got = fs.readSync(fd, buf, 0, buf.length, null)) > 0;) {
+ for (let i = 0; i < got; i++) if (buf[i] === 10) n++;
+ last = buf[got - 1];
+ }
+ } catch { return 0; } finally { if (fd !== undefined) fs.closeSync(fd); }
+ return n + (last === 10 ? 0 : 1);
+}
+
// ---------- 3. resolve imports ----------
const resolve = createResolver(root, files);
const edges = [];
@@ -289,5 +305,12 @@ if (hostCounts.size) {
line();
const big = code.filter((f) => f.loc > 1500).sort((a, b) => b.loc - a.loc).slice(0, 10);
if (big.length) { line('LARGEST FILES'); for (const f of big) line(` ${fmtNum(f.loc).padStart(6)} ${f.path}`); line(); }
+const unread = files.filter((f) => f.tooLarge).sort((a, b) => b.bytes - a.bytes);
+if (unread.length) {
+ line(`NOT READ ${unread.length} file(s) over ${fmtNum(maxBytes / 1024)} KB: on the map, but their imports, endpoints, requests and secrets weren't checked. Re-run scan.mjs with --max-file-kb <bigger> to read them.`);
+ for (const f of unread.slice(0, 15)) line(` ${fmtNum(Math.round(f.bytes / 1024)).padStart(6)} KB ${f.path}`);
+ if (unread.length > 15) line(` … ${unread.length - 15} more`);
+ line();
+}
line('Next: read references/schema.md, explore entrypoints, then write floorplan/architecture.json and run build.mjs.');
console.log(out.join('\n'));
diff --git a/tests/large-files.test.mjs b/tests/large-files.test.mjs
new file mode 100644
index 0000000..067d210
--- /dev/null
+++ b/tests/large-files.test.mjs
@@ -0,0 +1,55 @@
+// Files over the scan's size limit aren't read, but they stay on the map with their line count, and the
+// scan, Health and the map say they weren't checked (#16). The limit is lowered here to keep the sample small.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { makeProject, run, readGraph, readJson, cleanup } from './helpers.mjs';
+
+const BIG_LINES = 1500;
+let root, scanOut, graph;
+before(() => {
+ const big = Array.from({ length: BIG_LINES }, (_, i) => `def step_${i}(x):\n return x + ${i}\n`).join('').split('\n').slice(0, BIG_LINES).join('\n') + '\n';
+ root = makeProject({
+ 'app/main.py': 'from app import rules\n\nprint(rules.step_1(1))\n',
+ 'app/rules.py': big,
+ }, { arch: { project: { name: 'Sample', summary: 'A small sample.' }, nodes: [{ id: 'app', label: 'App', kind: 'service', summary: 'The app.', paths: ['app/**'] }] } });
+ scanOut = run('scan.mjs', root, '--max-file-kb', '8');
+ run('build.mjs', root, '--no-claude-md');
+ graph = readGraph(root);
+});
+after(() => cleanup(root));
+
+test('a file over the limit stays on the map with its line count', () => {
+ const scan = readJson(path.join(root, 'floorplan', '.cache', 'scan.json'));
+ const f = scan.files.find((x) => x.path === 'app/rules.py');
+ assert.equal(f.tooLarge, true);
+ assert.equal(f.loc, BIG_LINES);
+ const g = graph.files.find((x) => x.p === 'app/rules.py');
+ assert.equal(g.tooLarge, true);
+ assert.equal(g.loc, BIG_LINES);
+ assert.equal(graph.files.find((x) => x.p === 'app/main.py').tooLarge, undefined);
+});
+
+test('the scan says which files it did not read and how to include them', () => {
+ assert.match(scanOut, /NOT READ {2}1 file\(s\) over 8 KB/);
+ assert.match(scanOut, /--max-file-kb/);
+ assert.match(scanOut, /KB {2}app\/rules\.py/);
+});
+
+test('Health lists it as a large file and says it was not checked', () => {
+ const big = graph.health.issues.find((i) => i.id === 'large-files');
+ assert.ok(big, 'expected a large-files item');
+ assert.match(big.notes['f:app/rules.py'], /^1,500 lines: too big for Floorplan to read/);
+});
+
+test('the default limit reads a file over the old 512 KB limit', () => {
+ const r = makeProject({ 'app/main.py': 'x = 1\n'.repeat(110000) });
+ try {
+ assert.ok(fs.statSync(path.join(r, 'app', 'main.py')).size > 512 * 1024);
+ run('scan.mjs', r);
+ const f = readJson(path.join(r, 'floorplan', '.cache', 'scan.json')).files.find((x) => x.path === 'app/main.py');
+ assert.equal(f.tooLarge, undefined);
+ assert.equal(f.loc, 110000);
+ } finally { cleanup(r); }
+});