codebase-onboarder 0.6.0 → 0.7.0

package/server/tunnel.js

@@ -6,92 +6,87 @@
 // is installed, the exact command that would expose the current settings, and
 // the install hint for when it isn't. The CLI (`onboarder tunnel`) is what
 // actually spawns anything; the HTTP layer only ever reads this status.
-
 import { spawnSync } from 'node:child_process';
-
 import { isLoopbackHost, normalizeSettings } from './config.js';
-
 // `spawnSync` on a missing binary resolves with an ENOENT error rather than
 // throwing, which is exactly the signal we need. `--version` is a flag every
 // CLI here answers; anything that doesn't is treated as absent.
 export function findOnPath(name) {
-  try {
-    const res = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
-    if (res.error) return { installed: false };
-    const first = String(res.stdout || res.stderr || '').trim().split('\n')[0] || '';
-    return { installed: true, version: first.slice(0, 120) };
-  } catch {
-    return { installed: false };
-  }
+    try {
+        const res = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
+        if (res.error)
+            return { installed: false };
+        const first = String(res.stdout || res.stderr || '').trim().split('\n')[0] || '';
+        return { installed: true, version: first.slice(0, 120) };
+    }
+    catch {
+        return { installed: false };
+    }
 }
-
 // The one address a tunnel should forward to. Tunnels always dial loopback —
 // that is what makes "loopback behind a tunnel" a safe self-hosted layout, so
 // even a 0.0.0.0 bind is proxied from 127.0.0.1.
 export function tunnelTarget(settings) {
-  const s = normalizeSettings(settings);
-  return `http://127.0.0.1:${s.port}`;
+    const s = normalizeSettings(settings);
+    return `http://127.0.0.1:${s.port}`;
 }
-
 export function cloudflareCommand(settings) {
-  // A "quick tunnel": no account, no DNS edit, a random trycloudflare.com name
-  // that lives as long as the process. The named-tunnel route (a fixed domain
-  // on the person's own Cloudflare account) is a `cloudflared tunnel` setup of
-  // its own; the wizard says so rather than pretending one command covers both.
-  return `cloudflared tunnel --url ${tunnelTarget(settings)}`;
+    // A "quick tunnel": no account, no DNS edit, a random trycloudflare.com name
+    // that lives as long as the process. The named-tunnel route (a fixed domain
+    // on the person's own Cloudflare account) is a `cloudflared tunnel` setup of
+    // its own; the wizard says so rather than pretending one command covers both.
+    return `cloudflared tunnel --url ${tunnelTarget(settings)}`;
 }
-
 export function tailscaleCommand(settings) {
-  const s = normalizeSettings(settings);
-  // serve puts the machine's tailnet name (https://host.tailnet.ts.net) in
-  // front of the port, visible only to the tailnet. funnel would go further
-  // and publish it to the internet — mentioned, never run for you.
-  return `tailscale serve --bg --https=443 ${tunnelTarget(s)}`;
+    const s = normalizeSettings(settings);
+    // serve puts the machine's tailnet name (https://host.tailnet.ts.net) in
+    // front of the port, visible only to the tailnet. funnel would go further
+    // and publish it to the internet — mentioned, never run for you.
+    return `tailscale serve --bg --https=443 ${tunnelTarget(s)}`;
 }
-
 export function installHint(name) {
-  if (name === 'caddy') {
+    if (name === 'caddy') {
+        return process.platform === 'darwin'
+            ? 'brew install caddy'
+            : 'Install Caddy with: sudo apt install caddy';
+    }
+    if (name === 'cloudflared') {
+        return process.platform === 'darwin'
+            ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'
+            : 'See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+    }
     return process.platform === 'darwin'
-      ? 'brew install caddy'
-      : 'Install Caddy with: sudo apt install caddy';
-  }
-  if (name === 'cloudflared') {
-    return process.platform === 'darwin'
-      ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'
-      : 'See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
-  }
-  return process.platform === 'darwin'
-    ? 'brew install --cask tailscale  (or see https://tailscale.com/download)'
-    : 'See https://tailscale.com/download';
+        ? 'brew install --cask tailscale  (or see https://tailscale.com/download)'
+        : 'See https://tailscale.com/download';
 }
-
 // The settings drawer's tunnel section and `onboarder doctor` both render this:
 // what is enabled, what is installed, and what to run. Never spawns anything.
 export function tunnelStatus(settings) {
-  const s = normalizeSettings(settings);
-  const cf = findOnPath('cloudflared');
-  const ts = findOnPath('tailscale');
-  return {
-    target: tunnelTarget(s),
-    cloudflare: {
-      enabled: s.tunnel.cloudflare,
-      installed: cf.installed,
-      version: cf.version || '',
-      command: cloudflareCommand(s),
-      install: cf.installed ? '' : installHint('cloudflared'),
-    },
-    tailscale: {
-      enabled: s.tunnel.tailscale,
-      installed: ts.installed,
-      version: ts.version || '',
-      command: tailscaleCommand(s),
-      install: ts.installed ? '' : installHint('tailscale'),
-    },
-    // A tunnel answering a bind the server refused is the classic misread of
-    // "self-hosted": the tunnel terminates TLS and dials loopback, so the bind
-    // stays 127.0.0.1. Worth one explicit line everywhere the status is shown.
-    note: isLoopbackHost(s.host)
-      ? 'Loopback bind — a tunnel is the right way to reach this server remotely.'
-      : 'Network bind — a tunnel is optional; the access key is not.',
-  };
+    const s = normalizeSettings(settings);
+    const cf = findOnPath('cloudflared');
+    const ts = findOnPath('tailscale');
+    return {
+        target: tunnelTarget(s),
+        cloudflare: {
+            enabled: s.tunnel.cloudflare,
+            installed: cf.installed,
+            version: cf.version || '',
+            command: cloudflareCommand(s),
+            install: cf.installed ? '' : installHint('cloudflared'),
+        },
+        tailscale: {
+            enabled: s.tunnel.tailscale,
+            installed: ts.installed,
+            version: ts.version || '',
+            command: tailscaleCommand(s),
+            install: ts.installed ? '' : installHint('tailscale'),
+        },
+        // A tunnel answering a bind the server refused is the classic misread of
+        // "self-hosted": the tunnel terminates TLS and dials loopback, so the bind
+        // stays 127.0.0.1. Worth one explicit line everywhere the status is shown.
+        note: isLoopbackHost(s.host)
+            ? 'Loopback bind — a tunnel is the right way to reach this server remotely.'
+            : 'Network bind — a tunnel is optional; the access key is not.',
+    };
 }
+//# sourceMappingURL=tunnel.js.map

package/server/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../src/server/tunnel.ts"],"names":[],"mappings":"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","sourcesContent":["// The two tunnels this server knows how to sit behind, and nothing else.\n//\n// A tunnel here is not a feature of the server — it is another program the\n// person runs that forwards a public name to our port. What this module owns\n// is everything we can honestly say about that arrangement: whether the tool\n// is installed, the exact command that would expose the current settings, and\n// the install hint for when it isn't. The CLI (`onboarder tunnel`) is what\n// actually spawns anything; the HTTP layer only ever reads this status.\n\nimport { spawnSync } from 'node:child_process';\n\nimport { isLoopbackHost, normalizeSettings } from './config.js';\n\n// `spawnSync` on a missing binary resolves with an ENOENT error rather than\n// throwing, which is exactly the signal we need. `--version` is a flag every\n// CLI here answers; anything that doesn't is treated as absent.\nexport function findOnPath(name) {\n  try {\n    const res = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });\n    if (res.error) return { installed: false };\n    const first = String(res.stdout || res.stderr || '').trim().split('\\n')[0] || '';\n    return { installed: true, version: first.slice(0, 120) };\n  } catch {\n    return { installed: false };\n  }\n}\n\n// The one address a tunnel should forward to. Tunnels always dial loopback —\n// that is what makes \"loopback behind a tunnel\" a safe self-hosted layout, so\n// even a 0.0.0.0 bind is proxied from 127.0.0.1.\nexport function tunnelTarget(settings) {\n  const s = normalizeSettings(settings);\n  return `http://127.0.0.1:${s.port}`;\n}\n\nexport function cloudflareCommand(settings) {\n  // A \"quick tunnel\": no account, no DNS edit, a random trycloudflare.com name\n  // that lives as long as the process. The named-tunnel route (a fixed domain\n  // on the person's own Cloudflare account) is a `cloudflared tunnel` setup of\n  // its own; the wizard says so rather than pretending one command covers both.\n  return `cloudflared tunnel --url ${tunnelTarget(settings)}`;\n}\n\nexport function tailscaleCommand(settings) {\n  const s = normalizeSettings(settings);\n  // serve puts the machine's tailnet name (https://host.tailnet.ts.net) in\n  // front of the port, visible only to the tailnet. funnel would go further\n  // and publish it to the internet — mentioned, never run for you.\n  return `tailscale serve --bg --https=443 ${tunnelTarget(s)}`;\n}\n\nexport function installHint(name) {\n  if (name === 'caddy') {\n    return process.platform === 'darwin'\n      ? 'brew install caddy'\n      : 'Install Caddy with: sudo apt install caddy';\n  }\n  if (name === 'cloudflared') {\n    return process.platform === 'darwin'\n      ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'\n      : 'See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';\n  }\n  return process.platform === 'darwin'\n    ? 'brew install --cask tailscale  (or see https://tailscale.com/download)'\n    : 'See https://tailscale.com/download';\n}\n\n// The settings drawer's tunnel section and `onboarder doctor` both render this:\n// what is enabled, what is installed, and what to run. Never spawns anything.\nexport function tunnelStatus(settings) {\n  const s = normalizeSettings(settings);\n  const cf = findOnPath('cloudflared');\n  const ts = findOnPath('tailscale');\n  return {\n    target: tunnelTarget(s),\n    cloudflare: {\n      enabled: s.tunnel.cloudflare,\n      installed: cf.installed,\n      version: cf.version || '',\n      command: cloudflareCommand(s),\n      install: cf.installed ? '' : installHint('cloudflared'),\n    },\n    tailscale: {\n      enabled: s.tunnel.tailscale,\n      installed: ts.installed,\n      version: ts.version || '',\n      command: tailscaleCommand(s),\n      install: ts.installed ? '' : installHint('tailscale'),\n    },\n    // A tunnel answering a bind the server refused is the classic misread of\n    // \"self-hosted\": the tunnel terminates TLS and dials loopback, so the bind\n    // stays 127.0.0.1. Worth one explicit line everywhere the status is shown.\n    note: isLoopbackHost(s.host)\n      ? 'Loopback bind — a tunnel is the right way to reach this server remotely.'\n      : 'Network bind — a tunnel is optional; the access key is not.',\n  };\n}\n"]}

package/shared/analyzer/docs.d.ts

@@ -0,0 +1,16 @@
+export declare function parseFolderDoc(text: any): {
+    folderBrief: string;
+    files: Map<any, any>;
+};
+export declare function fileFactsLine(path: any, scan: any, facts: any): string;
+export declare function fileStaticDoc(path: any, scan: any, facts: any): any;
+export declare function folderStaticDoc(folder: any, scan: any, facts: any, subfolderCount?: number): string;
+export declare function docFileRow(path: any, scan: any, facts: any): {
+    path: any;
+    name: any;
+    parsed: boolean;
+    fanIn: any;
+    fanOut: any;
+    role: string;
+    functions: any;
+};

package/shared/analyzer/docs.js

@@ -6,9 +6,7 @@
 // docs page shows before anyone presses "Generate", and what it keeps showing if
 // no endpoint is ever configured. It used to sit in app.js, where it could not
 // be tested; it is pure text-from-facts, so it belongs next to `explainLocal`.
-
 import { factIndex, scanIndex } from './graph.js';
-
 // Parses the model's folder-brief answer, which we ask to be shaped like:
 //
 //   FOLDER: two plain sentences about what lives here and why.
@@ -18,118 +16,126 @@ import { factIndex, scanIndex } from './graph.js';
 // Deliberately forgiving: missing markers fall back to taking the first
 // couple of non-empty lines as the folder brief.
 export function parseFolderDoc(text) {
-  const out = { folderBrief: '', files: new Map() };
-  if (!text) return out;
-
-  const fallback = [];
-  for (const raw of text.split('\n')) {
-    const line = raw.trim();
-    if (!line) continue;
-
-    const folderMatch = line.match(/^FOLDER:\s*(.+)$/i);
-    if (folderMatch) {
-      out.folderBrief = (out.folderBrief ? out.folderBrief + ' ' : '') + folderMatch[1].trim();
-      continue;
+    const out = { folderBrief: '', files: new Map() };
+    if (!text)
+        return out;
+    const fallback = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const folderMatch = line.match(/^FOLDER:\s*(.+)$/i);
+        if (folderMatch) {
+            out.folderBrief = (out.folderBrief ? out.folderBrief + ' ' : '') + folderMatch[1].trim();
+            continue;
+        }
+        const fileMatch = line.match(/^FILE:\s*([^:]+?):\s+(.+)$/i);
+        if (fileMatch) {
+            out.files.set(fileMatch[1].trim(), fileMatch[2].trim());
+            continue;
+        }
+        fallback.push(line);
     }
-    const fileMatch = line.match(/^FILE:\s*([^:]+?):\s+(.+)$/i);
-    if (fileMatch) {
-      out.files.set(fileMatch[1].trim(), fileMatch[2].trim());
-      continue;
+    if (!out.folderBrief && fallback.length) {
+        out.folderBrief = fallback.slice(0, 2).join(' ');
     }
-    fallback.push(line);
-  }
-
-  if (!out.folderBrief && fallback.length) {
-    out.folderBrief = fallback.slice(0, 2).join(' ');
-  }
-  return out;
+    return out;
 }
-
 // ---- documentation from the graph, no model involved -----------------------
-
 // The one-line facts strip under a file's name in the generated docs.
 export function fileFactsLine(path, scan, facts) {
-  const f = scanIndex(scan).fileAt(path);
-  if (!f) return 'not parsed';
-  const fx = factIndex(facts);
-  const fin = facts.fanIn[path] || 0;
-  const fout = facts.fanOut[path] || 0;
-  const bits = [];
-  if (fx.entries.has(path)) bits.push('entry');
-  if (fin >= 5) bits.push('hub');
-  if (fx.inCycle.has(path)) bits.push('in a cycle');
-  bits.push(`${fin} dependents · pulls in ${fout}`);
-  if (f.functions.length) bits.push(`${f.functions.length} functions`);
-  return bits.join(' · ');
+    const f = scanIndex(scan).fileAt(path);
+    if (!f)
+        return 'not parsed';
+    const fx = factIndex(facts);
+    const fin = facts.fanIn[path] || 0;
+    const fout = facts.fanOut[path] || 0;
+    const bits = [];
+    if (fx.entries.has(path))
+        bits.push('entry');
+    if (fin >= 5)
+        bits.push('hub');
+    if (fx.inCycle.has(path))
+        bits.push('in a cycle');
+    bits.push(`${fin} dependents · pulls in ${fout}`);
+    if (f.functions.length)
+        bits.push(`${f.functions.length} functions`);
+    return bits.join(' · ');
 }
-
 // A paragraph about one file. The branches are ordered by how much they tell
 // you: being an entry point is the most useful thing to say about a file, being
 // load-bearing is next, and "pulls in N, answers to M" is the fallback that
 // always holds.
 export function fileStaticDoc(path, scan, facts) {
-  const f = scanIndex(scan).fileAt(path);
-  if (!f) return 'Not parsed — kept as an asset or data file.';
-  const fin = facts.fanIn[path] || 0;
-  const fout = facts.fanOut[path] || 0;
-  const importers = (facts.importers[path] || []).map((p) => p.split('/').pop());
-  let s;
-  if (factIndex(facts).entries.has(path)) {
-    s = `${f.name} is one of the ways into the codebase — it pulls in ${fout} other ${fout === 1 ? 'file' : 'files'} and answers to nothing above it.`;
-  } else if (fin >= 5) {
-    s = `${f.name} is load-bearing: ${fin} files import it directly${importers.length ? `, ${importers.slice(0, 2).join(', ')} among them` : ''}.`;
-  } else if (!fin && !fout) {
-    s = `${f.name} stands alone — nothing imports it and it imports nothing we can see.`;
-  } else if (!fout) {
-    s = `${f.name} sits at the end of a chain — it imports nothing and is leaned on by ${fin} ${fin === 1 ? 'file' : 'files'}.`;
-  } else if (!fin) {
-    s = `${f.name} pulls in ${fout} ${fout === 1 ? 'file' : 'files'} but nothing imports it — a door we didn't recognize, or dead code.`;
-  } else {
-    s = `${f.name} pulls in ${fout} and answers to ${fin}.`;
-  }
-  if (f.functions.length) {
-    s += ` It defines ${f.functions.length} function${f.functions.length === 1 ? '' : 's'} — ${f.functions.slice(0, 4).map((fn) => fn.name).join(', ')}${f.functions.length > 4 ? `, and ${f.functions.length - 4} more` : ''}.`;
-  }
-  if (f.exports.length) {
-    s += ` Exports: ${f.exports.slice(0, 4).map((e) => e.name).join(', ')}${f.exports.length > 4 ? ', …' : ''}.`;
-  }
-  return s;
+    const f = scanIndex(scan).fileAt(path);
+    if (!f)
+        return 'Not parsed — kept as an asset or data file.';
+    const fin = facts.fanIn[path] || 0;
+    const fout = facts.fanOut[path] || 0;
+    const importers = (facts.importers[path] || []).map((p) => p.split('/').pop());
+    let s;
+    if (factIndex(facts).entries.has(path)) {
+        s = `${f.name} is one of the ways into the codebase — it pulls in ${fout} other ${fout === 1 ? 'file' : 'files'} and answers to nothing above it.`;
+    }
+    else if (fin >= 5) {
+        s = `${f.name} is load-bearing: ${fin} files import it directly${importers.length ? `, ${importers.slice(0, 2).join(', ')} among them` : ''}.`;
+    }
+    else if (!fin && !fout) {
+        s = `${f.name} stands alone — nothing imports it and it imports nothing we can see.`;
+    }
+    else if (!fout) {
+        s = `${f.name} sits at the end of a chain — it imports nothing and is leaned on by ${fin} ${fin === 1 ? 'file' : 'files'}.`;
+    }
+    else if (!fin) {
+        s = `${f.name} pulls in ${fout} ${fout === 1 ? 'file' : 'files'} but nothing imports it — a door we didn't recognize, or dead code.`;
+    }
+    else {
+        s = `${f.name} pulls in ${fout} and answers to ${fin}.`;
+    }
+    if (f.functions.length) {
+        s += ` It defines ${f.functions.length} function${f.functions.length === 1 ? '' : 's'} — ${f.functions.slice(0, 4).map((fn) => fn.name).join(', ')}${f.functions.length > 4 ? `, and ${f.functions.length - 4} more` : ''}.`;
+    }
+    if (f.exports.length) {
+        s += ` Exports: ${f.exports.slice(0, 4).map((e) => e.name).join(', ')}${f.exports.length > 4 ? ', …' : ''}.`;
+    }
+    return s;
 }
-
 // A paragraph about one folder. `subfolderCount` is passed rather than read off
 // a tree node, so nothing in the shared layer needs to know the view's tree
 // shape.
 export function folderStaticDoc(folder, scan, facts, subfolderCount = 0) {
-  const here = scanIndex(scan).filesIn(folder);
-  let s = `${here.length} parsed ${here.length === 1 ? 'file lives' : 'files live'} here`;
-  if (subfolderCount) s += `, with ${subfolderCount} subfolder${subfolderCount === 1 ? '' : 's'} inside`;
-  s += '.';
-  const heaviest = here
-    .map((f) => ({ name: f.name, fanIn: facts.fanIn[f.path] || 0 }))
-    .sort((a, b) => b.fanIn - a.fanIn)[0];
-  if (heaviest && heaviest.fanIn >= 3) {
-    s += ` The one everything leans on is ${heaviest.name}, with ${heaviest.fanIn} dependents.`;
-  }
-  const entries = factIndex(facts).entries;
-  const entriesHere = here.filter((f) => entries.has(f.path));
-  if (entriesHere.length) s += ` The way in: ${entriesHere.map((f) => f.name).join(', ')}.`;
-  return s;
+    const here = scanIndex(scan).filesIn(folder);
+    let s = `${here.length} parsed ${here.length === 1 ? 'file lives' : 'files live'} here`;
+    if (subfolderCount)
+        s += `, with ${subfolderCount} subfolder${subfolderCount === 1 ? '' : 's'} inside`;
+    s += '.';
+    const heaviest = here
+        .map((f) => ({ name: f.name, fanIn: facts.fanIn[f.path] || 0 }))
+        .sort((a, b) => b.fanIn - a.fanIn)[0];
+    if (heaviest && heaviest.fanIn >= 3) {
+        s += ` The one everything leans on is ${heaviest.name}, with ${heaviest.fanIn} dependents.`;
+    }
+    const entries = factIndex(facts).entries;
+    const entriesHere = here.filter((f) => entries.has(f.path));
+    if (entriesHere.length)
+        s += ` The way in: ${entriesHere.map((f) => f.name).join(', ')}.`;
+    return s;
 }
-
 // The facts about one file as the prompts want them. Two identical copies of
 // this used to sit in app.js — one for a single doc tab, one for the
 // folder-by-folder pass — and they had to agree for the two pages to describe
 // the same file the same way.
 export function docFileRow(path, scan, facts) {
-  const f = scanIndex(scan).fileAt(path);
-  const fanIn = facts.fanIn[path] || 0;
-  return {
-    path,
-    name: path.split('/').pop(),
-    parsed: Boolean(f),
-    fanIn,
-    fanOut: facts.fanOut[path] || 0,
-    role: factIndex(facts).entries.has(path) ? 'entry' : fanIn >= 5 ? 'hub' : 'module',
-    functions: f ? f.functions.map((fn) => fn.name) : [],
-  };
+    const f = scanIndex(scan).fileAt(path);
+    const fanIn = facts.fanIn[path] || 0;
+    return {
+        path,
+        name: path.split('/').pop(),
+        parsed: Boolean(f),
+        fanIn,
+        fanOut: facts.fanOut[path] || 0,
+        role: factIndex(facts).entries.has(path) ? 'entry' : fanIn >= 5 ? 'hub' : 'module',
+        functions: f ? f.functions.map((fn) => fn.name) : [],
+    };
 }
+//# sourceMappingURL=docs.js.map

package/shared/analyzer/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/shared/analyzer/docs.ts"],"names":[],"mappings":"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","sourcesContent":["// Documentation written from the import graph alone.\n//\n// Two halves live here. The first parses the model's answer back into rows. The\n// second writes the documentation *without* a model — plain sentences about what\n// a file is and what leans on it. That half is the offline floor: it is what the\n// docs page shows before anyone presses \"Generate\", and what it keeps showing if\n// no endpoint is ever configured. It used to sit in app.js, where it could not\n// be tested; it is pure text-from-facts, so it belongs next to `explainLocal`.\n\nimport { factIndex, scanIndex } from './graph.js';\n\n// Parses the model's folder-brief answer, which we ask to be shaped like:\n//\n//   FOLDER: two plain sentences about what lives here and why.\n//   FILE: scan.js: one sentence about this file.\n//   FILE: graph.js: one sentence about this file.\n//\n// Deliberately forgiving: missing markers fall back to taking the first\n// couple of non-empty lines as the folder brief.\nexport function parseFolderDoc(text) {\n  const out = { folderBrief: '', files: new Map() };\n  if (!text) return out;\n\n  const fallback = [];\n  for (const raw of text.split('\\n')) {\n    const line = raw.trim();\n    if (!line) continue;\n\n    const folderMatch = line.match(/^FOLDER:\\s*(.+)$/i);\n    if (folderMatch) {\n      out.folderBrief = (out.folderBrief ? out.folderBrief + ' ' : '') + folderMatch[1].trim();\n      continue;\n    }\n    const fileMatch = line.match(/^FILE:\\s*([^:]+?):\\s+(.+)$/i);\n    if (fileMatch) {\n      out.files.set(fileMatch[1].trim(), fileMatch[2].trim());\n      continue;\n    }\n    fallback.push(line);\n  }\n\n  if (!out.folderBrief && fallback.length) {\n    out.folderBrief = fallback.slice(0, 2).join(' ');\n  }\n  return out;\n}\n\n// ---- documentation from the graph, no model involved -----------------------\n\n// The one-line facts strip under a file's name in the generated docs.\nexport function fileFactsLine(path, scan, facts) {\n  const f = scanIndex(scan).fileAt(path);\n  if (!f) return 'not parsed';\n  const fx = factIndex(facts);\n  const fin = facts.fanIn[path] || 0;\n  const fout = facts.fanOut[path] || 0;\n  const bits = [];\n  if (fx.entries.has(path)) bits.push('entry');\n  if (fin >= 5) bits.push('hub');\n  if (fx.inCycle.has(path)) bits.push('in a cycle');\n  bits.push(`${fin} dependents · pulls in ${fout}`);\n  if (f.functions.length) bits.push(`${f.functions.length} functions`);\n  return bits.join(' · ');\n}\n\n// A paragraph about one file. The branches are ordered by how much they tell\n// you: being an entry point is the most useful thing to say about a file, being\n// load-bearing is next, and \"pulls in N, answers to M\" is the fallback that\n// always holds.\nexport function fileStaticDoc(path, scan, facts) {\n  const f = scanIndex(scan).fileAt(path);\n  if (!f) return 'Not parsed — kept as an asset or data file.';\n  const fin = facts.fanIn[path] || 0;\n  const fout = facts.fanOut[path] || 0;\n  const importers = (facts.importers[path] || []).map((p) => p.split('/').pop());\n  let s;\n  if (factIndex(facts).entries.has(path)) {\n    s = `${f.name} is one of the ways into the codebase — it pulls in ${fout} other ${fout === 1 ? 'file' : 'files'} and answers to nothing above it.`;\n  } else if (fin >= 5) {\n    s = `${f.name} is load-bearing: ${fin} files import it directly${importers.length ? `, ${importers.slice(0, 2).join(', ')} among them` : ''}.`;\n  } else if (!fin && !fout) {\n    s = `${f.name} stands alone — nothing imports it and it imports nothing we can see.`;\n  } else if (!fout) {\n    s = `${f.name} sits at the end of a chain — it imports nothing and is leaned on by ${fin} ${fin === 1 ? 'file' : 'files'}.`;\n  } else if (!fin) {\n    s = `${f.name} pulls in ${fout} ${fout === 1 ? 'file' : 'files'} but nothing imports it — a door we didn't recognize, or dead code.`;\n  } else {\n    s = `${f.name} pulls in ${fout} and answers to ${fin}.`;\n  }\n  if (f.functions.length) {\n    s += ` It defines ${f.functions.length} function${f.functions.length === 1 ? '' : 's'} — ${f.functions.slice(0, 4).map((fn) => fn.name).join(', ')}${f.functions.length > 4 ? `, and ${f.functions.length - 4} more` : ''}.`;\n  }\n  if (f.exports.length) {\n    s += ` Exports: ${f.exports.slice(0, 4).map((e) => e.name).join(', ')}${f.exports.length > 4 ? ', …' : ''}.`;\n  }\n  return s;\n}\n\n// A paragraph about one folder. `subfolderCount` is passed rather than read off\n// a tree node, so nothing in the shared layer needs to know the view's tree\n// shape.\nexport function folderStaticDoc(folder, scan, facts, subfolderCount = 0) {\n  const here = scanIndex(scan).filesIn(folder);\n  let s = `${here.length} parsed ${here.length === 1 ? 'file lives' : 'files live'} here`;\n  if (subfolderCount) s += `, with ${subfolderCount} subfolder${subfolderCount === 1 ? '' : 's'} inside`;\n  s += '.';\n  const heaviest = here\n    .map((f) => ({ name: f.name, fanIn: facts.fanIn[f.path] || 0 }))\n    .sort((a, b) => b.fanIn - a.fanIn)[0];\n  if (heaviest && heaviest.fanIn >= 3) {\n    s += ` The one everything leans on is ${heaviest.name}, with ${heaviest.fanIn} dependents.`;\n  }\n  const entries = factIndex(facts).entries;\n  const entriesHere = here.filter((f) => entries.has(f.path));\n  if (entriesHere.length) s += ` The way in: ${entriesHere.map((f) => f.name).join(', ')}.`;\n  return s;\n}\n\n// The facts about one file as the prompts want them. Two identical copies of\n// this used to sit in app.js — one for a single doc tab, one for the\n// folder-by-folder pass — and they had to agree for the two pages to describe\n// the same file the same way.\nexport function docFileRow(path, scan, facts) {\n  const f = scanIndex(scan).fileAt(path);\n  const fanIn = facts.fanIn[path] || 0;\n  return {\n    path,\n    name: path.split('/').pop(),\n    parsed: Boolean(f),\n    fanIn,\n    fanOut: facts.fanOut[path] || 0,\n    role: factIndex(facts).entries.has(path) ? 'entry' : fanIn >= 5 ? 'hub' : 'module',\n    functions: f ? f.functions.map((fn) => fn.name) : [],\n  };\n}\n"]}

package/shared/analyzer/explainLocal.d.ts

@@ -0,0 +1,4 @@
+export declare function explainFile(path: any, file: any, facts: any): string;
+export declare function explainFolder(path: any, scan: any, facts: any): string;
+export declare function explainOverview(scan: any, facts: any, manifest: any): string;
+export declare function scanCaveats(scan: any): any[];