codebase-onboarder 0.4.0 → 0.5.0

package/cli/ui.js

@@ -54,36 +54,20 @@ export const tick = ok('  ✓ ');
 export const cross = bad('  ✗ ');
 export const dash = dim('  – ');
 
-// Visible width, ANSI codes excluded. Padding has to be computed on what the
-// terminal *shows*, not on the bytes we wrote, or every colored row grows a
-// few columns and the column stops being a column.
-export function width(text) {
-  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
-}
-
-// A titled block of rows. The box is drawn from the widest row rather than a
-// fixed 80 columns, so it stays aligned in a narrow terminal and does not stretch
-// across a wide one.
-export function panel(title, rows, { indent = '  ' } = {}) {
-  const labelWidth = Math.max(...rows.map((r) => width(r.label ?? '')), 0);
-  // Every row starts two columns in; the label column is then as wide as the
-  // longest label, so all the values line up regardless of label length.
-  const body = rows.map((r) => r.hint
-    ? '  ' + ' '.repeat(labelWidth + 4) + dim(r.hint)
-    : '  ' + paint((r.label ?? '').padEnd(labelWidth), 'gray') + '  ' + (r.value ?? ''));
-  // The frame is sized from its contents: a long path widens the box instead of
-  // spilling out of it, and a short one does not stretch to 80 columns.
-  const inner = Math.max(title.length + 4, ...body.map(width), 24);
-  const top = '┌─ ' + bold(title) + ' ' + '─'.repeat(Math.max(1, inner - title.length - 3)) + '┐';
-  const bottom = '└' + '─'.repeat(inner) + '┘';
-  return [top, ...body, bottom].map((line) => indent + (line === top || line === bottom ? paint(line, 'gray') : line)).join('\n');
-}
+// The layout math (width, fit, panel) lives in `server/layout.js` so the server's
+// own startup banner can use the identical geometry without importing this file
+// and inverting the dependency. This module is only the *color* on top of it.
+import { width, fit, termWidth, panel as layoutPanel, hint, row } from '../server/layout.js';
 
-// A one-line hint under a row, wrapped in the panel's dim voice.
-export const hint = (text) => ({ hint: text });
+export { width, fit, termWidth, hint, row };
 
-// Multi-line values (a command, a path list) still align on the first line.
-export function row(label, value) {
-  return { label, value: String(value) };
+// A titled block of rows that fits the terminal it is printed into. Same shape
+// the server banner uses; the difference is only that this one paints.
+export function panel(title, rows, options = {}) {
+  const styles = { label: 'gray', frame: 'gray', hint: 'gray', title: 'bold' };
+  return layoutPanel(title, rows, {
+    ...options,
+    paint: (text, style) => paint(text, styles[style] || 'gray'),
+  });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Drop a path. Get a map. A zero-dependency codebase visualizer with a CLI onboarding wizard, a web UI, and an optional key-gated self-hosted mode.",
   "type": "module",
   "bin": {

package/server/index.js

@@ -25,6 +25,7 @@ import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from
 import { tunnelStatus } from './tunnel.js';
 import { pidIsAlive, readPidFile, removePidFile, writePidFile, writeRunInfo, runInfoPath } from './pidfile.js';
 import { logPath } from './daemon.js';
+import { panel, row } from './layout.js';
 
 const logger = createLogger();
 
@@ -64,42 +65,45 @@ export function createServer(config = CONFIG) {
 
 // What the terminal shows once the socket is listening. A pure string builder
 // so the CLI prints exactly this too, and so a test can read it.
-export function startupBanner(settings, { configFile } = {}) {
+//
+// The shape is label/value rows, not prose, because every fact here has to be
+// readable at a glance and copy-pasteable. The one long sentence it used to
+// print — "self-hosted — the network can reach this; every API call needs the
+// access key" — wrapped unpredictably at any terminal width and buried the URL
+// people actually need. Now the detail lives on its own row.
+export function startupBanner(settings, { configFile, columns } = {}) {
   const urls = serverUrls(settings);
-  const lines = ['', '  Onboarder is up.'];
-  lines.push(settings.mode === 'self-hosted'
-    ? (isLoopbackHost(settings.host)
-      ? '  Mode    self-hosted — loopback bind; use a tunnel or change the host for direct network access'
-      : '  Mode    self-hosted — the network can reach this; every API call needs the access key')
-    : '  Mode    local — only this machine can reach it');
-  lines.push('  Local   ' + urls.local);
-  if (urls.network) lines.push('  Network ' + urls.network);
-  if (urls.domain) {
-    lines.push('  Domain  ' + urls.domain);
-    if (settings.domain && !settings.https) {
-      lines.push('  HTTPS   disabled — `onboarder setup` or `onboarder https setup` enables trusted TLS');
-    } else if (settings.https) {
-      lines.push('  HTTPS   Caddy obtains, renews, and terminates TLS for this domain');
-    }
-  }
-  if (settings.mode === 'self-hosted' && settings.accessKey) {
-    lines.push('  Remote browsers show an access-key sign-in page; the key is never put in the URL.');
+  const rows = [];
+  const add = (label, value) => rows.push([label, value]);
+
+  add('URL', urls.local);
+  if (urls.network) add('Network', urls.network);
+  if (urls.domain) add('Public', urls.domain);
+  add('Bind', `${settings.host}:${settings.port}`);
+  add('Mode', settings.mode === 'self-hosted'
+    ? (isLoopbackHost(settings.host) ? 'self-hosted (loopback — use a tunnel)' : 'self-hosted (network reachable)')
+    : 'local (this machine only)');
+
+  if (settings.mode === 'self-hosted') {
+    add('Auth', settings.accessKey
+      ? 'access key required for remote browsers'
+      : 'NO ACCESS KEY — every API call is refused');
   }
-  if (settings.mode === 'self-hosted' && !settings.accessKey) {
-    lines.push('  WARNING self-hosted with no access key — every API call is refused until one is set.');
-    lines.push('          Run `onboarder setup` or `onboarder config key rotate`.');
+  if (settings.domain) {
+    add('HTTPS', settings.https ? 'Caddy terminates TLS for this domain' : 'off — `onboarder https setup` enables it');
   }
   const tunnels = tunnelStatus(settings);
   for (const name of ['cloudflare', 'tailscale']) {
     const t = tunnels[name];
     if (!t.enabled) continue;
-    lines.push(t.installed
-      ? `  Tunnel  ${name}: ${t.command}`
-      : `  Tunnel  ${name} is enabled but its CLI is not installed — ${t.install}`);
+    add('Tunnel', t.installed ? `${name}: ${t.command}` : `${name} enabled, CLI missing — ${t.install}`);
   }
-  if (configFile) lines.push('  Config  ' + configFile);
-  lines.push('');
-  return lines.join('\n');
+  if (configFile) add('Config', configFile);
+
+  // Rendered through the same panel helper the CLI uses, so `node server/index.js`
+  // and `onboarder start` cannot drift apart — and so both adapt to the terminal
+  // width instead of assuming 80 columns.
+  return '\n' + panel('Onboarder is up', rows.map(([label, value]) => row(label, value)), { columns }) + '\n';
 }
 
 // Ask the OS to open the app. Best-effort and detached: a missing opener on a

package/server/layout.js

@@ -0,0 +1,73 @@
+// Terminal geometry, with no color and no dependencies.
+//
+// This lives here, under `server/`, because two very different callers need
+// identical layout: the CLI (which paints) and the server's own startup banner
+// (which must not import `cli/ui.js` — that would invert the dependency, since
+// the CLI sits on top of the server). So the *shape* is here and the *color* is
+// injected by the caller as a `paint(text, style)` function.
+//
+// Everything is pure string math on purpose: a layout decision is a thing you
+// want to unit-test without spawning a terminal, and the whole reason panels
+// used to look broken is that this math was scattered through the callers.
+
+export function width(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// The terminal we are drawing into, asked at call time rather than cached at
+// import: a panel printed after the user resized their window should use the
+// new size. Falls back to COLUMNS, then 80, so a pipe or a log file still gets
+// sane output instead of `undefined`.
+export function termWidth(stream = process.stdout) {
+  return stream.columns || Number(process.env.COLUMNS) || 80;
+}
+
+// Shorten to fit, with a real ellipsis. The middle is elided rather than the
+// tail, because in a path or URL the end is the part that identifies it.
+export function fit(text, max, { tail = true } = {}) {
+  const value = String(text);
+  if (max <= 0) return '';
+  if (value.length <= max) return value;
+  if (max === 1) return '…';
+  if (!tail) return value.slice(0, max - 1) + '…';
+  const head = Math.ceil((max - 1) * 0.4);
+  const rest = max - 1 - head;
+  return (head ? value.slice(0, head) + '…' : '…') + value.slice(value.length - rest);
+}
+
+// A titled block of rows that fits the terminal it is printed into. The frame is
+// sized from its contents, then clamped to the available width, and every value
+// is elided to fit rather than allowed to spill past the border — a panel whose
+// right edge is off-screen is what makes output "mess the terminal".
+//
+// `paint` is injected: `(text, style) => string`, where style is 'label' or
+// 'frame'. The default is identity, which is what the server banner and the
+// `--no-color` path want.
+export function panel(title, rows, { indent = '  ', columns, paint = (t) => String(t) } = {}) {
+  // The hard ceiling is the terminal. A floor below it would be a lie: on a 40
+  // column terminal a 59-wide panel is exactly the overflow this exists to
+  // prevent, so the floor only guards against a nonsensical zero, and short
+  // titles/values are handled by the `fit` calls below rather than by a minimum.
+  const available = Math.max(24, (columns || termWidth()) - indent.length);
+  const labelWidth = Math.min(12, Math.max(...rows.map((r) => width(r.label ?? '')), 0));
+  // indent(2) + gap(2) + label + gap(2) + value + right border(2)
+  const valueRoom = Math.max(8, available - 2 - labelWidth - 2 - 2);
+  const body = rows.map((r) => (r.hint
+    ? '  ' + ' '.repeat(labelWidth + 2) + paint(fit(r.hint, valueRoom), 'hint')
+    : '  ' + paint(fit(r.label ?? '', labelWidth).padEnd(labelWidth), 'label') + '  ' + fit(r.value ?? '', valueRoom)));
+
+  // Frame width = whatever the body needs, capped to what the terminal has.
+  const wanted = Math.max(...body.map(width), 12);
+  const inner = Math.max(8, Math.min(available - 2, wanted));
+  const shownTitle = fit(title, Math.max(2, inner - 4));
+  const top = paint('┌─ ', 'frame') + paint(shownTitle, 'title')
+    + ' ' + paint('─'.repeat(Math.max(0, inner - shownTitle.length - 3)) + '┐', 'frame');
+  const bottom = paint('└' + '─'.repeat(inner) + '┘', 'frame');
+  return [top, ...body, bottom].map((line) => indent + line).join('\n');
+}
+
+// A one-line note rendered in the panel's muted voice.
+export const hint = (text) => ({ hint: text });
+
+// A label/value row. Values are stringified here so a caller can pass a number.
+export const row = (label, value) => ({ label, value: String(value) });

package/server/logger.js

@@ -25,7 +25,38 @@ function paint(text, color, enabled) {
 }
 
 // Fields that are part of the envelope or already rendered into the message.
-const ENVELOPE = new Set(['ts', 'time', 'level', 'msg', 'method', 'path', 'status', 'ms', 'line', 'scope']);
+// `summary` is here so the suppressed-noise footer does not print itself as
+// `summary=true` — it is a rendering flag, not data.
+const ENVELOPE = new Set(['ts', 'time', 'level', 'msg', 'method', 'path', 'status', 'ms', 'line', 'scope', 'summary']);
+
+// Request classification — the difference between a person doing something and
+// a browser fetching a file.
+//
+// This is the single most important thing about Onboarder's logs. A page load
+// pulls ~90 ES modules, a stylesheet, and two vendored libraries: 90 log lines
+// describing zero user actions, repeated on every reload and on every auth
+// check. The MCP status poll adds one more line every nine seconds, forever. Log
+// all of it and the real events — a scan, a login, a 500 — are buried.
+//
+// So: a request is an **action** if it is an API call, and **noise** if it is a
+// static asset. Noise is not thrown away, it is *counted* (see `NoiseCounter`),
+// because "nothing happened" and "90 files were served" are different facts and
+// only one of them is interesting most of the time.
+export function classifyPath(pathname = '') {
+  const path = String(pathname).split('?')[0];
+  if (path === '/api/health') return 'poll';      // uptime checks
+  if (path.startsWith('/api/')) return 'action';
+  return 'noise';
+}
+
+export function classifyRequest(req = {}) {
+  const kind = classifyPath(req.path);
+  // A failure is always an action, whatever it was: a 404 on a missing asset is
+  // a broken build, and a 500 is a bug. Neither is noise to be summarized away.
+  if (Number(req.status) >= 400) return 'action';
+  if (req.method && req.method !== 'GET' && req.method !== 'HEAD') return 'action';
+  return kind;
+}
 
 // One line, no styling: what a log file holds and what a test asserts on.
 export function formatMessage(entry) {
@@ -48,16 +79,179 @@ export function formatMessage(entry) {
 const LEVEL_WIDTH = 5;
 const GUTTER = '  ';
 
-export function formatEntry(entry) {
-  const time = String(entry.time || String(entry.ts || '').slice(11, 23));
-  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
-  return `${time}${GUTTER}${level}${GUTTER}${formatMessage(entry)}`;
+// The part of a path that identifies it: the filename with its extension. When
+// a line has to be cut, this is what must survive — `…typescript.js` is useful,
+// `…script` is not. A path with no filename (`/` or `/a/`) falls back to its tail.
+export function identifyingTail(text) {
+  const value = String(text);
+  const name = value.slice(value.lastIndexOf('/') + 1);
+  return name.length >= 4 ? name : value.slice(-8);
+}
+
+// How the message area adapts to the terminal. Wide terminals get the whole
+// path; narrow ones get the part that identifies it, elided in the middle — the
+// tail of a path is the informative half, so it survives and the boring prefix
+// is what gets dropped.
+export function fitPath(text, max) {
+  const value = String(text);
+  if (max <= 0) return '';
+  if (value.length <= max) return value;
+  if (max === 1) return '…';
+  // An ellipsis stands in for the dropped prefix, so do not also add a leading
+  // slash: `/…/file.js` reads as a path, `//file.js` reads as a typo. The kept
+  // tail is the filename, so a long path loses its directories rather than
+  // losing its extension — `…typescript.js` is useful, `…typescript` is not.
+  const tail = identifyingTail(value);
+  if (tail.length + 1 <= max) return '…' + tail;
+  return '…' + value.slice(-(max - 1));
+}
+
+// How much room the message gets, and whether the level column is affordable.
+//
+// The fixed prefix is the time, two gutters, and the level column. On a narrow
+// terminal that fixed cost eats the whole line, so two things give way: below 52
+// columns the level column is dropped, and below 24 the timestamp reduces to
+// HH:MM. Below 12 there is no room for any prefix at all, so both are dropped.
+//
+// Crucially the prefix never exceeds the terminal. An earlier version floored
+// `messageWidth` at 12, which meant a 20-column line asked for 20 columns of
+// message, overflowed, and got clamped from the front — producing `pt.js 200`,
+// the tail of a line with its head cut off. The prefix is the part that must
+// yield, not the message.
+export const LEVEL_MIN_COLUMNS = 52;
+export const SHORT_TIME_COLUMNS = 24;
+export const NO_TIME_COLUMNS = 12;
+
+export function showLevel(columns) {
+  return (columns || 80) >= LEVEL_MIN_COLUMNS;
+}
+
+export function showFullTime(columns) {
+  return (columns || 80) >= SHORT_TIME_COLUMNS;
+}
+
+export function showTime(columns) {
+  return (columns || 80) >= NO_TIME_COLUMNS;
+}
+
+// The time as it will actually be printed, so callers do not re-derive the same
+// decision and get it subtly wrong.
+export function timeColumn(entry, columns) {
+  if (!showTime(columns)) return '';
+  const raw = String(entry.time || String(entry.ts || '').slice(11, 19));
+  return showFullTime(columns) ? raw : raw.slice(0, 5);
+}
+
+// Everything before the message: time + gutter + optional level + gutter.
+//
+// Deliberately computed from the *width* alone, not from an entry: an earlier
+// version asked `timeColumn({}, columns)`, which has no timestamp and so
+// reported a zero-width prefix — and then every line was built 19 columns too
+// long and overflowed. The prefix is a property of the terminal, not of the log
+// line, so it is computed from the terminal.
+export function prefixWidth(columns) {
+  if (!showTime(columns)) return 0;
+  const time = showFullTime(columns) ? 12 : 5;
+  return time + GUTTER.length + (showLevel(columns) ? LEVEL_WIDTH + GUTTER.length : 0);
+}
+
+export function messageWidth(columns) {
+  const total = columns || 80;
+  return Math.max(0, total - prefixWidth(total));
+}
+
+export function formatEntry(entry, { columns } = {}) {
+  const time = timeColumn(entry, columns);
+  const level = showLevel(columns) ? entryLevel(entry) + GUTTER : '';
+  const head = time ? time + GUTTER + level : '';
+  // The message was already fitted to `messageWidth` and the head is exactly
+  // `prefixWidth`, so the line is exactly the terminal width by construction —
+  // no trailing clamp, and therefore no risk of cutting a word in half.
+  return head + fitMessage(entry, columns);
+}
+
+// One line, fitted to the terminal.
+//
+// What gets sacrificed as space runs out, in order: the timing, then the HTTP
+// status, then the level column, then the *method* — and the path's tail is
+// protected, because the filename is the one thing that still identifies the
+// request. A 40-column terminal gets `…zer/languages/typescript.js` (the
+// extension intact); an 80-column one gets the whole sentence.
+function fitMessage(entry, columns) {
+  const text = formatMessage(entry);
+  const room = messageWidth(columns);
+  if (text.length <= room) return text;
+  if (!entry.method || !entry.path) return fitPath(text, room);
+
+  const status = entry.status === undefined ? '' : ` ${entry.status}`;
+  const method = `${entry.method} `;
+  // Drop the status before the method, and the method before any of the path.
+  const withStatus = method + fitPath(entry.path, room - method.length - status.length) + status;
+  if (withStatus.length <= room) return withStatus;
+  const withoutStatus = method + fitPath(entry.path, room - method.length);
+  if (withoutStatus.length <= room) return withoutStatus;
+  // Last resort: the path alone, at exactly the room available. `fitPath` is
+  // given the exact width, so this is always exactly `room` — never over, which
+  // is what would make the caller's clamp cut the *front* of the line and leave
+  // an unreadable tail like `pt.js 200`.
+  return fitPath(entry.path, room);
+}
+
+// A summary of suppressed noise renders as a footnote, not an event: dim, and
+// with no level column, so the eye skips it while scanning for real lines. It
+// occupies the same time gutter so it still lines up in the scrollback.
+export function renderEntry(entry, { color = false, columns } = {}) {
+  const message = fitMessage(entry, columns);
+  const limit = Math.max(8, columns || 80);
+  if (entry.summary) {
+    const pad = showLevel(columns) ? ' '.repeat(LEVEL_WIDTH) + GUTTER : '';
+    return paint(timeColumn(entry, columns), 'gray', color)
+      + GUTTER + paint(GUTTER + pad + message, 'gray', color);
+  }
+  const painted = paint(timeColumn(entry, columns), 'gray', color) + GUTTER
+    + (showLevel(columns) ? paint(entryLevel(entry), LEVEL_COLOR[entry.level] || 'gray', color) + GUTTER : '')
+    + message;
+  // Clamp on *visible* width: the ANSI codes cost nothing on screen, so slicing
+  // the painted string by character count would cut a real character and leave
+  // the escape sequence unterminated.
+  return visibleWidth(painted) <= limit ? painted : trimVisible(painted, limit);
+}
+
+// Visible width, ANSI excluded.
+function visibleWidth(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// Cut a painted string to `max` visible columns, passing escape sequences through
+// and never splitting one, then resetting so the terminal is left clean.
+function trimVisible(text, max) {
+  const pattern = /\x1b\[[0-9;]*m/g;
+  let out = '';
+  let seen = 0;
+  let last = 0;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    const chunk = text.slice(last, match.index);
+    if (seen + chunk.length >= max) return out + chunk.slice(0, Math.max(0, max - seen)) + '\x1b[0m';
+    out += chunk + match[0];
+    seen += chunk.length;
+    last = pattern.lastIndex;
+  }
+  const rest = text.slice(last);
+  return out + (seen + rest.length > max ? rest.slice(0, max - seen) : rest);
 }
 
-export function renderEntry(entry, { color = false } = {}) {
-  const time = String(entry.time || String(entry.ts || '').slice(11, 19));
-  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
-  return paint(time, 'gray', color) + GUTTER + paint(level, LEVEL_COLOR[entry.level] || 'gray', color) + GUTTER + formatMessage(entry);
+function entryLevel(entry) {
+  return String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+}
+
+// A human summary of suppressed noise, so silence is never ambiguous. "Nothing
+// happened" and "94 files were served" are different facts; printing the second
+// as one line every so often keeps the first honest.
+export function noiseSummary(count, ms = 0) {
+  const files = `${count} static file${count === 1 ? '' : 's'}`;
+  const took = ms >= 1000 ? ` in ${(ms / 1000).toFixed(1)}s` : ms ? ` in ${ms}ms` : '';
+  return `served ${files}${took}`;
 }
 
 export function logEntry(level, msg, extra = {}) {
@@ -86,13 +280,38 @@ export function createLogger(level = process.env.LOG_LEVEL || 'info', options =
   const out = options.stdout || process.stdout;
   const err = options.stderr || process.stderr;
 
+  // The noise policy. `info` (the default) drops successful static assets and
+  // uptime polls; `debug` shows every request, which is what you want when you
+  // are debugging the server rather than watching it. ONBOARDER_LOG_VERBOSE=1 is
+  // the same escape hatch without changing the level.
+  const quiet = options.quiet ?? (minLevel > levels.debug && process.env.ONBOARDER_LOG_VERBOSE !== '1');
+  // Read the terminal width per write, not once at construction: a log line
+  // printed after the user resized their window should use the new width.
+  const columns = options.columns ?? (() => out.columns || undefined);
+
+  // Suppressed-asset accounting. Assets are counted, not printed, and the tally
+  // is flushed as ONE dim summary line once it reaches `flushAt` — so a page
+  // load that serves 94 files produces one line, and a terminal that is idle
+  // still admits the server is busy rather than looking dead.
+  const flushAt = options.flushAt ?? 40;
+  let suppressed = 0;
+  let since = Date.now();
+
+  function flush(force = false) {
+    if (!suppressed) return;
+    if (!force && suppressed < flushAt) return;
+    write(logEntry('info', noiseSummary(suppressed, Date.now() - since), { summary: true }));
+    suppressed = 0;
+    since = Date.now();
+  }
+
   function write(entry) {
     if (format === 'json') {
       const line = JSON.stringify(entry) + '\n';
       (entry.level === 'warn' || entry.level === 'error' ? err : out).write(line);
       return;
     }
-    (entry.level === 'warn' || entry.level === 'error' ? err : out).write(renderEntry(entry, { color }) + '\n');
+    (entry.level === 'warn' || entry.level === 'error' ? err : out).write(renderEntry(entry, { color, columns: columns() }) + '\n');
   }
 
   function log(lvl, msg, extra = {}) {
@@ -105,6 +324,20 @@ export function createLogger(level = process.env.LOG_LEVEL || 'info', options =
     info: (msg, extra) => log('info', msg, extra),
     warn: (msg, extra) => log('warn', msg, extra),
     error: (msg, extra) => log('error', msg, extra),
-    http: (req) => log(req.status >= 500 ? 'error' : 'info', 'http', req),
+    // The one place the noise policy lives. A successful GET of a static file is
+    // counted, not printed; a scan, a login, or any failure is printed.
+    http: (req) => {
+      if (quiet && classifyRequest(req) === 'noise') {
+        suppressed += 1;
+        flush();
+        return;
+      }
+      if (quiet && classifyPath(req.path) === 'poll') return;
+      flush();
+      log(Number(req.status) >= 500 ? 'error' : 'info', 'http', req);
+    },
+    // Let a shutdown path (or a test) get the tally out before the process dies.
+    flush: () => flush(true),
+    suppressed: () => suppressed,
   };
 }

package/shared/analyzer/graph.js

@@ -52,9 +52,14 @@ export function computeFacts(scan, manifest = {}) {
     .map((f) => f.path)
     .sort();
 
+  // A hub is a file other files depend on. The threshold is 2, not 3: in a
+  // repo with 20 files, "imported by two others" *is* the most-depended-upon
+  // file, and a threshold of 3 reported no hubs at all for a whole small project
+  // — the map of a small repo is exactly where a hub is most useful. Two is the
+  // lowest value that still means "more than one other file reaches for this".
   const hubs = files
     .map((f) => ({ path: f.path, fanIn: fanIn.get(f.path) || 0, fanOut: fanOut.get(f.path) || 0 }))
-    .filter((h) => h.fanIn >= 3)
+    .filter((h) => h.fanIn >= 2)
     .sort((a, b) => b.fanIn - a.fanIn);
 
   const orphans = files

package/shared/analyzer/languages/csharp.js

@@ -1,19 +1,40 @@
 // C# analyzer
-import { blankComments, lineCounter, uniqueBy } from '../util.js';
+//
+// C# is namespace-rooted exactly as Java is package-rooted: a file's path is its
+// namespace spelled with slashes, under a project root. The difference that
+// matters is the import. Java's `import a.b.C;` names a *class*, so one path
+// answers it; C#'s `using A.B;` names a *namespace*, and the classes inside it
+// are not knowable from the import string. So a namespace import resolves to a
+// directory and the scanner links to every file in it — the same shape Go uses
+// for packages.
+import { blankComments, lineCounter } from '../util.js';
 
 export const extensions = ['.cs'];
 
+const NAMESPACE_RE = /^\s*namespace\s+([A-Za-z0-9_.]+)\s*[;{]/m;
+
 export function analyze(source, path) {
   const clean = blankComments(source);
   const lineAt = lineCounter(clean);
 
+  // The file's own namespace. Captured first because every import is resolved
+  // relative to it — this declaration is the only place the root is written down.
+  // Block-scoped namespaces (`namespace A.B { }`) are the norm, and the regex
+  // accepts both the `;` and `{` forms.
+  const namespace = (clean.match(NAMESPACE_RE) || [])[1] || '';
+
   const imports = [];
-  for (const m of clean.matchAll(/\busing\s+([a-zA-Z0-9_.]+)\s*;/g)) {
-    imports.push({ spec: m[1], line: lineAt(m.index) });
+  // `using static A.B.C;` names a type (and optionally a member of it); plain
+  // `using A.B;` names a namespace. The distinction decides whether we look for
+  // a file or a directory.
+  for (const m of clean.matchAll(/\busing\s+(static\s+)?([A-Za-z0-9_.]+)\s*;/g)) {
+    imports.push({ spec: m[2], static: !!m[1], namespace, line: lineAt(m.index) });
   }
+  // `using X = Y;` aliases and global usings are out of scope; a spec that fails
+  // to resolve is reported as unresolved rather than guessed at.
 
   const classes = [];
-  for (const m of clean.matchAll(/(\[[^\]]+\]\s*)*\b(?:public\s+|private\s+|protected\s+|internal\s+)*(?:abstract\s+|sealed\s+)?(?:class|interface|struct|record|enum)\s+([a-zA-Z0-9_]+)/g)) {
+  for (const m of clean.matchAll(/(\[[^\]]+\]\s*)*\b(?:public\s+|private\s+|protected\s+|internal\s+)*(?:abstract\s+|sealed\s+|static\s+|partial\s+)*(?:class|interface|struct|record|enum)\s+([a-zA-Z0-9_]+)/g)) {
     const attributes = [];
     if (m[1]) {
       for (const am of m[1].matchAll(/\[([A-Za-z0-9_]+)/g)) {
@@ -30,10 +51,64 @@ export function analyze(source, path) {
     exports: classes.map(c => ({ name: c.name, kind: 'class' })),
     functions: [],
     classes,
-    hasMain
+    hasMain,
+    namespace,
   };
 }
 
-export function resolveImport(spec, fromPath, has, context = {}) {
+// A C# `using` is resolved by *path suffix*, not by a root prefix. See
+// `resolveImport` below for why that distinction matters — it is the whole
+// difference between C# and Java, and getting it backwards drops every import.
+//
+// `sourceRootFor` is kept and exported because it is the answer for the layouts
+// where a project *does* mirror the full namespace (`Acme/Services/User.cs`).
+// It is a fallback, not the main path.
+export function sourceRootFor(fromPath, namespace) {
+  if (!namespace) return null;
+  const suffix = namespace.replace(/\./g, '/');
+  const normalized = String(fromPath).replace(/\\/g, '/');
+  const nested = normalized.lastIndexOf('/' + suffix + '/');
+  if (nested >= 0) return normalized.slice(0, nested + 1);
+  if (normalized === suffix || normalized.startsWith(suffix + '/')) return '';
+  return null;
+}
+
+export function resolveImport(spec, fromPath, has, context = {}, meta = {}) {
+  const parts = spec.split('.').filter(Boolean);
+  const findDir = (segments) => (segments.length ? context.findDirEndingWith?.(segments.join('/')) : null);
+  if (!parts.length) return { unresolved: spec };
+
+  // A C# `using` is ambiguous from the string alone: in `using Acme.Models;`,
+  // `Models` might be a namespace (link its directory) or a type (link the
+  // file). Both readings are tried, most specific first.
+  //
+  // The other half of the puzzle is that C# resolves by *path suffix*, not by a
+  // root prefix the way Java does. `namespace Acme.Services` conventionally
+  // lives in `src/Services/`: the folders mirror the namespace, but the leading
+  // `Acme` — the project or company root — is not a directory. So the namespace
+  // segments are matched against the *tail* of a real directory path, which is
+  // what `findDirEndingWith` answers. Stripping the whole namespace instead, the
+  // Java approach, matches nothing here and silently drops every import.
+
+  // Reading 1: the last segment is a type. Find the directory holding its
+  // namespace, then the file named after it.
+  const namespaceParts = parts.slice(0, -1);
+  for (let take = namespaceParts.length; take > 0; take -= 1) {
+    const dir = findDir(namespaceParts.slice(namespaceParts.length - take));
+    if (!dir) continue;
+    const exact = dir + '/' + parts[parts.length - 1] + '.cs';
+    if (has(exact)) return { path: exact };
+    if (meta.static) return { unresolved: spec }; // `using static A.B.C;` is always a type
+  }
+
+  // Reading 2: the whole spec is a namespace, so link its directory.
+  for (let take = parts.length; take > 0; take -= 1) {
+    const dir = findDir(parts.slice(parts.length - take));
+    if (dir) return { packageDir: dir };
+  }
+
+  // The BCL (`System`, `System.Collections.Generic`) and every NuGet package land
+  // here. Staying unresolved is the honest answer: a file we invent would be a
+  // node in the graph that does not exist.
   return { unresolved: spec };
 }