codebase-onboarder 0.4.1 → 0.6.0

package/cli/explorer/commands.js

@@ -0,0 +1,369 @@
+// The command table.
+//
+// One list, used three ways: to dispatch what someone typed, to build the `help`
+// screen, and to assert in the tests that every command is reachable, has a
+// summary, and is wired to a real view. A command that exists in one of those
+// places but not the others is the kind of thing nobody notices until a user
+// types it, so the table is the only place a command is defined at all.
+//
+// `run(ctx, args)` returns a string to print, or a marker the app layer acts on
+// (`EXIT`, `CLEAR`). `args` is an array of already-parsed words, so quoting is
+// handled once, in the tokenizer, and every command sees the same shape.
+
+import * as V from './views.js';
+import * as A from './advanced.js';
+import { lineNumber } from './session.js';
+import { bold, cyan, dim, ok, fit, termWidth } from '../ui.js';
+import { wrapText } from './wrap.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+export const EXIT = Symbol('exit');
+export const CLEAR = Symbol('clear');
+
+export const COMMANDS = [
+  {
+    name: 'help', aliases: ['?'], group: 'basics',
+    usage: 'help [command]', summary: 'This list, or everything about one command.',
+    // The topic is forwarded. `help find` used to ignore its argument and print
+    // the whole list, which reads as the command not working.
+    run: (ctx, args) => ctx.help(args.join(' ')),
+  },
+  {
+    name: 'map', aliases: ['overview', 'home'], group: 'basics',
+    usage: 'map', summary: 'What this repo is, and where to start.',
+    run: (ctx) => V.overview(ctx.repo),
+  },
+  {
+    name: 'tour', aliases: ['start', 'onboarding'], group: 'basics',
+    usage: 'tour', summary: 'The reading order a new teammate should follow.',
+    run: (ctx) => V.tour(ctx.repo),
+  },
+  {
+    name: 'explain', aliases: ['why', 'what'], group: 'basics',
+    usage: 'explain [file|folder]', summary: 'This repo, or one file/folder, in prose. No AI key needed.',
+    run: (ctx, args) => V.explain(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'tree', aliases: ['ls', 'files'], group: 'navigate',
+    usage: 'tree [folder] [depth]', summary: 'The file tree, with entries and hubs marked.',
+    run: (ctx, args) => {
+      // A lone number is the depth, not a folder called "2". `tree 3` is what
+      // everyone types when they want to see more; making them spell
+      // `tree . 3` would be pedantry in a tool built to be forgiving. `.` is the
+      // root, so it must not be taken as a folder name either.
+      const onlyDepth = args.length === 1 && /^\d+$/.test(args[0]);
+      const sub = onlyDepth ? '' : (args[0] || '');
+      return V.tree(ctx.repo, {
+        sub: sub === '.' ? '' : sub,
+        depth: onlyDepth ? Number(args[0]) : (Number(args[1]) || 2),
+      });
+    },
+  },
+  {
+    name: 'find', aliases: ['search', 'grep'], group: 'navigate',
+    usage: 'find <query>', summary: 'Search. Supports ext:js, -exclude, "phrases", /regex/.',
+    run: (ctx, args) => V.find(ctx.repo, { query: args.join(' ') }),
+  },
+  {
+    name: 'show', aliases: ['open', 'cat', 'read'], group: 'navigate',
+    usage: 'show <file> [from] [count]', summary: 'Read a file. Name it loosely: `show logger.js` works.',
+    run: (ctx, args) => V.show(ctx.repo, {
+      target: args[0] || '',
+      from: lineNumber(args[1], 0),
+      count: lineNumber(args[2], 0),
+    }),
+  },
+  {
+    name: 'deps', aliases: ['connections'], group: 'navigate',
+    usage: 'deps <file>', summary: 'What a file imports, and what imports it.',
+    run: (ctx, args) => V.deps(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'health', aliases: ['grade'], group: 'analyze',
+    usage: 'health', summary: 'Health grade, riskiest files, debt.',
+    run: (ctx) => V.health(ctx.repo),
+  },
+  {
+    name: 'hubs', aliases: ['core'], group: 'analyze',
+    usage: 'hubs', summary: 'The most depended-on files.',
+    run: (ctx) => V.hubs(ctx.repo),
+  },
+  {
+    name: 'layers', aliases: ['depth'], group: 'analyze',
+    usage: 'layers', summary: 'Import depth, shallowest first.',
+    run: (ctx) => V.layers(ctx.repo),
+  },
+  {
+    name: 'patterns', aliases: ['architecture'], group: 'analyze',
+    usage: 'patterns', summary: 'What the architecture looks like, in prose.',
+    run: (ctx) => V.patterns(ctx.repo),
+  },
+  {
+    name: 'stats', aliases: ['numbers'], group: 'analyze',
+    usage: 'stats', summary: 'Languages, biggest folders and files, complexity.',
+    run: (ctx) => V.stats(ctx.repo),
+  },
+  {
+    name: 'security', aliases: ['audit'], group: 'analyze',
+    usage: 'security', summary: 'Heuristic findings from the built-in rules.',
+    run: (ctx) => V.security(ctx.repo),
+  },
+  {
+    name: 'stack', aliases: ['packages'], group: 'analyze',
+    usage: 'stack', summary: 'Declared dependencies and frameworks.',
+    run: (ctx) => V.stack(ctx.repo),
+  },
+  {
+    name: 'entry', aliases: ['entries'], group: 'analyze',
+    usage: 'entry', summary: 'Recognized entry points and how far they reach.',
+    run: (ctx) => V.entry(ctx.repo),
+  },
+  {
+    name: 'externals', aliases: ['drift'], group: 'analyze',
+    usage: 'externals', summary: 'External packages, plus dependency drift.',
+    run: (ctx) => V.externals(ctx.repo),
+  },
+  {
+    name: 'graph', aliases: ['tree-graph'], group: 'navigate',
+    usage: 'graph <file> [depth]', summary: 'The dependency tree around a file, as arrows.',
+    run: (ctx, args) => A.graph(ctx.repo, { target: args[0] || '', depth: Number(args[1]) || 2 }),
+  },
+  {
+    name: 'blast', aliases: ['impact', 'radius'], group: 'navigate',
+    usage: 'blast <file>', summary: 'What breaks if this file breaks, transitively.',
+    run: (ctx, args) => A.blast(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'symbols', aliases: ['outline', 'functions'], group: 'navigate',
+    usage: 'symbols <file>', summary: 'Functions, classes and exports in a file.',
+    run: (ctx, args) => A.symbols(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'docs', aliases: ['document'], group: 'analyze',
+    usage: 'docs [file|folder] | docs --write', summary: 'Prose docs for a file, or write ONBOARDER.md.',
+    run: async (ctx, args) => {
+      // `--write` is the one command here that touches the filesystem. It is
+      // opt-in, explicit, and prints where it wrote — a map tool should never
+      // leave a file behind just because someone asked what the docs say.
+      if (args[0] === '--write') {
+        const abs = await A.writeDocs(ctx.repo, args[1] || 'ONBOARDER.md');
+        return '  ' + ok('Wrote ') + cyan(abs);
+      }
+      return A.docs(ctx.repo, { target: args.filter((a) => a !== '--write').join(' ') });
+    },
+  },
+  {
+    name: 'log', aliases: ['history', 'commits'], group: 'git',
+    usage: 'log [count]', summary: 'Recent commits, and who wrote them.',
+    run: (ctx, args) => A.log(ctx.repo, { limit: Number(args[0]) || 15 }),
+  },
+  {
+    name: 'hotspots', aliases: ['churn'], group: 'git',
+    usage: 'hotspots [count]', summary: 'Files that are both complex and frequently changed.',
+    run: (ctx, args) => A.hotspots(ctx.repo, { limit: Number(args[0]) || 12 }),
+  },
+  {
+    name: 'blame', aliases: ['authors'], group: 'git',
+    usage: 'blame <file>', summary: 'Who wrote each line of a file.',
+    run: (ctx, args) => A.blame(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'coupling', aliases: ['matrix', 'heatmap'], group: 'analyze',
+    usage: 'coupling', summary: 'Folder-to-folder import traffic, as a heat grid.',
+    run: (ctx) => A.coupling(ctx.repo),
+  },
+  {
+    name: 'clusters', aliases: ['communities', 'modules'], group: 'analyze',
+    usage: 'clusters', summary: 'Groups of files that import each other more than the rest.',
+    run: (ctx) => A.clusters(ctx.repo),
+  },
+  {
+    name: 'diagram', aliases: ['mermaid'], group: 'analyze',
+    usage: 'diagram [file]', summary: 'Mermaid source for the repo, or one file.',
+    run: (ctx, args) => A.diagram(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'layers-diagram', aliases: [], group: 'analyze',
+    usage: 'layers-diagram', summary: 'Mermaid source for the layer stack.',
+    run: (ctx) => A.layerDiagram(ctx.repo),
+  },
+  {
+    name: 'risks', aliases: ['problems', 'smells'], group: 'analyze',
+    usage: 'risks', summary: 'Cycles, orphans, dead exports, drift — in one list.',
+    run: (ctx) => A.risks(ctx.repo),
+  },
+  {
+    name: 'about', aliases: ['version'], group: 'session',
+    usage: 'about', summary: 'Version, repo path, and what is indexed.',
+    run: (ctx) => V.about(ctx.repo, ctx.version),
+  },
+  {
+    name: 'rescan', aliases: ['reload'], group: 'session',
+    usage: 'rescan', summary: 'Re-read the repo from disk.',
+    run: (ctx) => ctx.rescan(),
+  },
+  {
+    name: 'github', aliases: ['remote', 'repo'], group: 'session',
+    usage: 'github', summary: "What GitHub says about this repo — stars, issues, license.",
+    run: (ctx) => ctx.github(),
+  },
+  {
+    name: 'cd', aliases: ['open-repo', 'use'], group: 'session',
+    usage: 'cd <folder|url>', summary: 'Load another repository, or clone one by URL.',
+    run: (ctx, args) => ctx.loadRepo(args.join(' ')),
+  },
+  {
+    name: 'web', aliases: ['site', 'serve'], group: 'session',
+    usage: 'web', summary: 'Start the web UI and print its URL.',
+    run: (ctx) => ctx.web(),
+  },
+  {
+    name: 'clear', aliases: ['cls'], group: 'session',
+    usage: 'clear', summary: 'Clear the screen.',
+    run: () => CLEAR,
+  },
+  {
+    name: 'exit', aliases: ['quit', 'q'], group: 'session',
+    usage: 'exit', summary: 'Leave. Ctrl-D does the same.',
+    run: () => EXIT,
+  },
+];
+
+// One lookup for every spelling a person might type, built once at import.
+const BY_NAME = new Map();
+for (const cmd of COMMANDS) {
+  BY_NAME.set(cmd.name, cmd);
+  for (const a of cmd.aliases) BY_NAME.set(a, cmd);
+}
+
+export function lookup(word) {
+  return BY_NAME.get(String(word || '').toLowerCase());
+}
+
+// Every canonical name, for "did you mean" matching. Aliases are deliberately
+// excluded: suggesting `open` when someone typed `sho` is less useful than
+// suggesting `show`, which is the word they were reaching for.
+export function commandNames() {
+  return COMMANDS.map((c) => c.name);
+}
+
+// `help <command>` answers about one command; bare `help` lists them, grouped so
+// the shape of the tool is visible rather than alphabetical. Every row is
+// fitted, because a long summary on a narrow terminal used to wrap into the
+// next row and make the list unreadable.
+export function helpText(ctx, topic = '') {
+  const w = termWidth();
+  if (topic) {
+    const cmd = lookup(topic);
+    if (!cmd) return fit(`  No command called "${topic}". Try \`help\`.`, Math.max(10, w - 2));
+    const also = cmd.aliases.length ? `  (also: ${cmd.aliases.join(', ')})` : '';
+    return [
+      fit('  ' + cmd.usage + also, Math.max(10, w - 2)),
+      wrapText(cmd.summary, '    '),
+    ].join('\n');
+  }
+  const groups = new Map();
+  for (const cmd of COMMANDS) {
+    if (!groups.has(cmd.group)) groups.set(cmd.group, []);
+    groups.get(cmd.group).push(cmd);
+  }
+  // Two cells of indent, two of gap, and the summary gets whatever is left. The
+  // usage column shrinks with the terminal rather than pushing the text off it.
+  const longest = Math.max(...COMMANDS.map((c) => c.usage.length));
+  const usageRoom = Math.max(8, Math.min(longest, Math.floor(w * 0.4)));
+  const out = [];
+  for (const [group, list] of groups) {
+    out.push(fit('  ' + group.toUpperCase(), Math.max(10, w - 2)));
+    for (const c of list) {
+      const left = '    ' + fit(c.usage, usageRoom);
+      const room = w - left.length - 2;
+      out.push(room > 8 ? left + '  ' + fit(c.summary, room, { tail: false }) : left);
+    }
+  }
+  out.push('');
+  out.push(fit('  ' + (ctx?.repo ? ctx.repo.name : 'onboarder')
+    + ' · Ctrl-D or `exit` to leave · Ctrl-C twice to quit', Math.max(10, w - 2)));
+  return out.join('\n');
+}
+
+// Split a typed line into words, honoring quotes so `find "exact phrase"` and
+// `show "my file.js"` arrive as one argument each. Done once, here, so no
+// command has to re-implement it.
+export function tokenize(line) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(String(line || '')))) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+// Tab completion, because a REPL where you retype `shared/analyzer/graph.js` one
+// letter at a time is not a REPL, it is a punishment.
+//
+// Two contexts, chosen by what is already typed. Before the first space, the line
+// is a command name, so it completes against the command table — including
+// aliases, because a person who types `ls` wants `tree` to finish. After a space,
+// it is an argument, so it completes against real file paths in the loaded repo,
+// which is the thing that is tedious to type and impossible to remember.
+//
+// `shellEscape` is the other half of a good REPL: `!git status` runs a shell
+// command and hands the output back, so nobody has to leave the session to run
+// one thing. It is deliberately the *only* way out to a shell, so the set of
+// things that can happen in a session stays legible.
+function completer(repo) {
+  return function complete(line) {
+    const trailingSpace = /\s$/.test(line);
+    const parts = line.split(/\s+/);
+    // Completing a command (no space yet, or trailing space after one word).
+    if (parts.length <= 1 || (parts.length === 2 && trailingSpace)) {
+      const hits = [...BY_NAME.keys()].filter((n) => n.startsWith(parts[0] || '')).sort();
+      return [hits.length ? hits : parts, parts[0] || ''];
+    }
+    // Completing a path argument against the loaded repo. Matches at any depth,
+    // not just from the root: `show rend` should find `src/render.js`, which is
+    // the case the resolver's forgiving path lookup already handles — the
+    // completer has to agree with it or Tab contradicts what the command does.
+    const frag = parts[parts.length - 1] || '';
+    const slash = frag.lastIndexOf('/');
+    const dir = slash === -1 ? '' : frag.slice(0, slash + 1);
+    const base = slash === -1 ? frag : frag.slice(slash + 1);
+    const seen = new Set();
+    const hits = [];
+    for (const f of repo.scan.allFiles || repo.scan.files) {
+      if (dir && !f.startsWith(dir)) continue;
+      // With no directory typed, match the *last* segment so `rend` finds
+      // `src/render.js`; with one typed, match the segment being completed.
+      const name = dir ? f.slice(dir.length) : f.slice(f.lastIndexOf('/') + 1);
+      if (!name.startsWith(base)) continue;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      hits.push(name);
+      if (hits.length >= 200) break;
+    }
+    return [hits.length ? hits : [frag], frag];
+  };
+}
+
+// Run a shell command and capture its output. A non-zero exit is not a crash —
+// `grep` that finds nothing is a normal answer — so the code is reported, not
+// thrown. There is no `shell: true`: the whole line is the argument vector, so
+// nothing in a filename can be interpreted as a second command.
+async function shellEscape(line, cwd) {
+  const parts = tokenize(line);
+  if (!parts.length) return null;
+  try {
+    const { stdout, stderr } = await run(parts[0], parts.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
+    const out = String(stdout || '').trimEnd();
+    const err = String(stderr || '').trimEnd();
+    return [out, err].filter(Boolean).join('\n') || dim('  (no output)');
+  } catch (e) {
+    const code = e.code ?? e.status;
+    const err = String(e.stderr || '').trimEnd() || String(e.message || '').trimEnd();
+    return dim('  exit ' + (code ?? '?') + (err ? '\n  ' + err : ''));
+  }
+}
+
+export { completer, shellEscape };

package/cli/explorer/github.js

@@ -0,0 +1,75 @@
+// Asking GitHub what it knows about a repository — the terminal half of the
+// feature the web app calls "From the remote".
+//
+// The `fetch` lives here rather than in `shared/analyzer/github.js` because it
+// can only happen in one runtime at a time, and because this side can do
+// something the browser cannot: send a token. `GITHUB_TOKEN` (or `GH_TOKEN`, the
+// name the `gh` CLI uses) turns GitHub's 60-requests-an-hour guest allowance
+// into 5,000. The browser has nowhere to keep a secret, which is precisely why
+// this is better in a terminal than on the web.
+//
+// A failed lookup is never fatal. `github` on a repo with no remote, a private
+// one, or a machine with no network is a normal thing to type, so every path
+// returns the honest reason instead of throwing.
+
+import { githubRepoPath, remoteError, remoteFacts } from '../../shared/analyzer/github.js';
+
+const API = 'https://api.github.com/repos/';
+const TIMEOUT_MS = 8000;
+
+// The token is read per call rather than at import: a session that exports one
+// mid-flight should not need to be restarted to pick it up.
+function token() {
+  const t = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  return typeof t === 'string' && t.trim() ? t.trim() : '';
+}
+
+/**
+ * Look up a GitHub repository's public facts.
+ *
+ * `fetchImpl` is a parameter so this is testable without a network, and so the
+ * caller can pass an already-aborted-aware fetch if it has one.
+ *
+ * Returns `{ ok: true, facts, repoPath }` or `{ ok: false, reason }`. Never
+ * throws — the reason is the return value, because every failure here is
+ * something to print, not something to crash a session over.
+ */
+export async function fetchRepoFacts(url, { fetchImpl = globalThis.fetch } = {}) {
+  const repoPath = githubRepoPath(url);
+  if (!repoPath) {
+    return { ok: false, reason: 'That is not a GitHub URL, so there are no remote facts to ask for.' };
+  }
+  if (typeof fetchImpl !== 'function') {
+    return { ok: false, reason: 'This runtime has no fetch, so GitHub cannot be asked.' };
+  }
+
+  const headers = { accept: 'application/vnd.github+json', 'user-agent': 'onboarder' };
+  const auth = token();
+  if (auth) headers.authorization = 'Bearer ' + auth;
+
+  let res;
+  try {
+    res = await fetchImpl(API + repoPath, {
+      headers,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (err) {
+    // A timeout and a refused connection are the same thing to the person who
+    // typed the command: it did not come back. The message is kept because
+    // "GitHub could not be reached" and "the certificate is not trusted" are
+    // very different problems on very different machines.
+    const detail = /timeout|abort/i.test(err?.message || '') ? ' (it took too long)' : '';
+    return { ok: false, reason: 'Could not reach GitHub' + detail + ' — ' + (err?.message || err) };
+  }
+
+  if (!res.ok) return { ok: false, reason: remoteError(res.status) };
+
+  let facts;
+  try {
+    facts = remoteFacts(await res.json());
+  } catch {
+    return { ok: false, reason: 'GitHub sent something that is not JSON.' };
+  }
+  if (!facts) return { ok: false, reason: 'GitHub sent no repository facts.' };
+  return { ok: true, facts, repoPath };
+}

package/cli/explorer/graphs.js

@@ -0,0 +1,178 @@
+// Rendering primitives that the terminal can do and a browser cannot afford to.
+//
+// The site's coupling matrix is a canvas heat grid and its mind map is SVG. In a
+// terminal the honest translation of "a heat grid" is block characters, and the
+// honest translation of "a dependency tree" is the one everybody already knows
+// how to read: an indented tree with arrows. Neither is a worse version of the
+// web view — they are the terminal's own idiom, drawn from the same numbers.
+
+import { fit, termWidth } from '../ui.js';
+import { width } from '../../server/layout.js';
+
+// Five ramp steps. Unicode 2591–2588, with an ASCII floor for terminals that
+// cannot show them. Density reads as "how dark", which survives being printed in
+// black and white, redirected to a file, or read by someone who cannot tell the
+// ramp apart — the thing a color-only heatmap cannot promise.
+const RAMP_UNICODE = [' ', '░', '▒', '▓', '█'];
+const RAMP_ASCII = ['.', ':', '+', '*', '#'];
+
+// A row that is `marker + value + tail`, where the tail is the first thing to go
+// when the terminal is too narrow to hold it.
+//
+// This is the same mistake in five places — health risks, security findings,
+// entry points, symbol rows, and layer notes — and fixing each by hand means the
+// sixth gets it wrong too. The rule in one place: if the tail leaves less than
+// `MIN_PATH` cells for the value, drop the tail and give the value the rest.
+//
+// `marker` may be styled, so its width is measured with `width()` (which strips
+// ANSI) rather than `.length`. Measuring a styled string counts escape-sequence
+// characters as if they occupied cells, which is how a "fitted" row still
+// overflows by the length of the color codes.
+const MIN_PATH = 8;
+
+// `pad` is the indent *inside* the width budget, not a prefix glued on
+// afterwards. An earlier version returned `marker + value` and let the caller
+// prepend `'    '`, which is four cells the helper could not see — so every row
+// came out four cells too wide, which is exactly the overflow this exists to
+// prevent. The indent is part of the row now.
+//
+// The value always gets at least one cell and never more than the terminal has
+// left, even when the marker alone is wider than the terminal. That last case is
+// the one a `Math.max(1, …)` floor gets wrong: a floor of 1 plus an
+// over-wide marker is still an overflow, so the value is clamped by `w` itself
+// and the marker is fitted too.
+export function labelled(marker, value, tail = '', { pad = 0 } = {}) {
+  const w = termWidth();
+  const indent = ' '.repeat(Math.max(0, Math.min(pad, Math.max(0, w - 1))));
+  const markerRoom = Math.max(0, w - width(indent) - 1);
+  const head = fit(marker, markerRoom);
+  const lead = width(indent) + width(head);
+  const withTail = w - lead - width(tail);
+  if (tail && withTail > MIN_PATH) return indent + head + fit(value, withTail) + tail;
+  return indent + head + fit(value, Math.max(0, w - lead));
+}
+
+const glyphs = () => (process.platform === 'win32' && !process.env.WT_SESSION ? RAMP_ASCII : RAMP_UNICODE);
+
+// The strongest signal a number gets, as a fraction of the largest, in five
+// steps. Zero is always the blank cell rather than the faintest mark: "nothing"
+// and "a little" are different facts, and a heat grid that gives zero a speck of
+// ink makes every map look busier than it is.
+//
+// Returns the *character*, always a string — an early version returned the
+// number 0 for "empty", which then blew up on `.padEnd()` the first time a
+// genuinely-zero cell was drawn, i.e. only on repos with real structure.
+function step(value, max) {
+  const ramp = glyphs();
+  if (!value || max <= 0) return ramp[0];
+  const i = Math.min(ramp.length - 1, Math.max(1, Math.ceil((value / max) * (ramp.length - 1))));
+  return ramp[i];
+}
+
+export { step };
+
+// A horizontal bar, sized as a fraction of the largest value. Exported so every
+// ranked list draws its bars identically instead of each view re-deriving the
+// scale and drifting.
+export function bar(value, max, room) {
+  if (room <= 0 || !value || max <= 0) return '';
+  const ramp = glyphs();
+  const full = Math.max(1, Math.round((value / max) * room));
+  return ramp[ramp.length - 1].repeat(Math.min(room, full));
+}
+
+// A vertical bar chart, because some questions are about magnitude across
+// categories and reading them off a horizontal list is harder than it needs to
+// be. Columns collapse to a single row when the terminal is too narrow to hold
+// them, rather than drawing a squeezed, unreadable grid.
+export function columns(items, { room = 40, rows = 10 } = {}) {
+  if (!items.length) return [];
+  const width = Math.max(1, Math.min(items.length, room));
+  const stepSize = Math.ceil(items.length / width);
+  const shown = stepSize > 1 ? items.filter((_, i) => i % stepSize === 0).slice(0, width) : items;
+  const top = Math.max(...shown.map((i) => i.value)) || 1;
+  const solid = glyphs()[glyphs().length - 1];
+  const out = [];
+  for (let level = rows; level >= 1; level--) {
+    const threshold = (level / rows) * top;
+    const line = shown.map((i) => (i.value >= threshold ? solid : ' ')).join('');
+    if (line.trim()) out.push('  ' + line);
+  }
+  out.push('  ' + shown.map((i) => String(i.label).slice(0, 1)).join(''));
+  return out;
+}
+
+// The folder-to-folder coupling grid, as a matrix. Row label, then one cell per
+// folder, heaviest traffic darkest. Columns are addressed by letter so a cell
+// can be named rather than counted. The diagonal is blank: a folder's traffic
+// with itself is not coupling, it is just being that folder.
+export function couplingGrid(repo, { maxFolders = 8, columns: cols } = {}) {
+  const matrix = repo.coupling;
+  if (!matrix || !matrix.folders.length) return [];
+  const folders = matrix.folders.slice(0, maxFolders);
+  const w = cols || termWidth();
+  const labelRoom = Math.min(18, Math.max(...folders.map((f) => f.length)) + 1);
+  const cellRoom = Math.max(1, Math.floor((w - labelRoom - 4) / folders.length));
+  const cellW = Math.max(1, Math.min(2, cellRoom));
+
+  const head = ' '.repeat(labelRoom) + folders.map((_, i) => String.fromCharCode(65 + i).padEnd(cellW)).join('');
+  // The rule is sized to the grid but never past the terminal, so a very narrow
+  // window gets a short rule rather than a wrapped one.
+  const rule = '─'.repeat(Math.max(1, Math.min(labelRoom + folders.length * cellW, Math.max(1, w - 2))));
+  const out = ['  ' + fit(head, w - 2), '  ' + rule];
+
+  folders.forEach((from, r) => {
+    let line = fit(from, labelRoom);
+    folders.forEach((to, c) => {
+      if (r === c) {
+        line += ' '.repeat(cellW);
+        return;
+      }
+      const n = matrix.counts.get(from + '->' + to) || 0;
+      line += step(n, matrix.max).padEnd(cellW);
+    });
+    out.push('  ' + fit(line, w - 2));
+  });
+  return out;
+}
+
+// A dependency tree rooted at a file, drawn as a tree with the one piece of
+// information that makes a tree readable — which way each edge points. This is
+// the terminal's answer to the site's force-directed graph: a browser can show
+// every edge at once, a terminal cannot, so it shows the part that answers "what
+// breaks if I break this".
+//
+// The `seen` set makes the walk terminate on a cyclic graph — without it, a
+// two-file import cycle would recurse until the stack gave out. The cost is that
+// a file reached by two different paths is drawn only under the first, which is
+// the right trade for a bounded tree.
+export function depTree(repo, rootPath, { depth = 2, direction = 'both', room } = {}) {
+  const w = room || termWidth();
+  const out = [];
+  const seen = new Set([rootPath]);
+
+  const walk = (path, prefix, left, arrow) => {
+    out.push(fit(prefix + arrow + ' ' + path, w - 2));
+    if (left <= 0) return;
+
+    const kids = [];
+    if (direction !== 'up') {
+      for (const child of repo.facts.importsOf[path] || []) {
+        if (!seen.has(child)) kids.push({ path: child, arrow: '→' });
+      }
+    }
+    if (direction !== 'down') {
+      for (const parent of repo.facts.importers[path] || []) {
+        if (!seen.has(parent)) kids.push({ path: parent, arrow: '←' });
+      }
+    }
+    kids.forEach((k, i) => {
+      if (seen.has(k.path)) return;
+      seen.add(k.path);
+      walk(k.path, prefix + (i === kids.length - 1 ? '  ' : '│ '), left - 1, k.arrow);
+    });
+  };
+
+  walk(rootPath, '', depth, '●');
+  return out;
+}