codebase-onboarder 0.5.0 → 0.6.0

package/cli/main.js

@@ -12,6 +12,7 @@ import {
   runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
 } from './commands.js';
 import { runExplore } from './explorer/app.js';
+import { setColorEnabled } from './ui.js';
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -20,7 +21,7 @@ const HELP = `
 
   Usage
     onboarder                     Explore a codebase here, interactively
-    onboarder explore [folder]    The same, pointed somewhere else (alias: tui)
+    onboarder explore [folder|url]  The same, pointed somewhere else (alias: tui)
     onboarder start               Start the web UI in the foreground (Ctrl-C stops it)
     onboarder start background    Start detached — keeps running after you close the terminal
     onboarder start startup       Run automatically at login [install|remove|status]
@@ -37,10 +38,16 @@ const HELP = `
   In the explorer
     map tour explain             what this is, where to start, and why
     tree find show deps          browse it, search it, read it, trace it
+    graph blast symbols          the dependency tree, the blast radius, the outline
     health hubs layers patterns  the analysis, in the same words the site uses
-    stats security stack entry   numbers, findings, dependencies
-    cd rescan web                switch repo, reload, open the web UI
+    coupling clusters risks      the heat grid, the module groups, what is wrong
+    log hotspots blame           git history, hot files, who wrote a line
+    diagram docs                 Mermaid source, and prose you can write out
+    cd rescan web                switch repo (or clone a URL), reload, open the web UI
+    github                       what GitHub says about this repo — stars, issues, license
+    !<command>                   run a shell command without leaving
     help exit                    everything, and the way out
+    Tab                          completes commands, then file paths
 
   Setup flags (interactive wizard skips what they answer)
     --mode local|self-hosted   --host <addr>   --port <n>   --domain <name>
@@ -68,6 +75,7 @@ const HELP = `
   Examples
     onboarder                           # explore the repo you are standing in
     onboarder explore ~/code/my-app     # explore somewhere else
+    onboarder explore https://github.com/expressjs/express   # clone one and read it
     onboarder start background          # leave the web UI running, close the terminal
     onboarder logs -f                   # watch what it is doing
     onboarder start startup install     # also start it every time you log in
@@ -85,7 +93,7 @@ const OPTIONS = {
   reveal: { type: 'boolean' },
   verbose: { type: 'boolean' },
   start: { type: 'boolean' },
-  color: { type: 'boolean' }, // --no-color falls out of parseArgs for free
+  color: { type: 'boolean' }, // `--no-color` is lifted out by extractNegatedFlags; --color forces it on
   config: { type: 'string' },
   mode: { type: 'string' },
   host: { type: 'string' },
@@ -117,10 +125,32 @@ function normalizeFlags(values) {
   return out;
 }
 
+// `parseArgs` cannot express a negated boolean. `--color=false` is rejected
+// outright, `--color false` sets `color: true` and leaves `false` behind as a
+// positional, and `--no-color` is an unknown option — so the documented flag
+// had never worked, for any command, and `--no-color status` would try to run a
+// command called `no-color`.
+//
+// There is no parser-level spelling for "this boolean is false", so the flag is
+// lifted out of argv before parsing and applied to the parsed flags after. That
+// keeps `parseArgs` strict about genuinely unknown options (which is the point
+// of a tool that writes a config file) while making the one negation the CLI
+// documents actually work.
+function extractNegatedFlags(argv) {
+  const rest = [];
+  let noColor = false;
+  for (const arg of argv) {
+    if (arg === '--no-color') noColor = true;
+    else rest.push(arg);
+  }
+  return { argv: rest, noColor };
+}
+
 export async function main(argv = process.argv.slice(2)) {
+  const { argv: argsIn, noColor } = extractNegatedFlags(argv);
   let parsed;
   try {
-    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
+    parsed = parseArgs({ args: argsIn, options: OPTIONS, allowPositionals: true });
   } catch (e) {
     console.error('  ' + e.message + '\n' + HELP);
     return 2;
@@ -128,6 +158,20 @@ export async function main(argv = process.argv.slice(2)) {
   const { values, positionals } = parsed;
   const flags = normalizeFlags(values);
 
+  // Color is decided here, after the flags exist and before anything is
+  // painted. An explicit `--no-color` wins over `FORCE_COLOR`: a person who
+  // typed the flag meant it, and a stray `FORCE_COLOR` inherited from a CI
+  // profile should not override the thing they just asked for.
+  if (noColor) {
+    flags.color = false;
+    setColorEnabled(false);
+  } else if (flags.color === true) {
+    // `--color` was accepted by the parser and then ignored, which is the same
+    // lie in the other direction. It is the documented way to keep ANSI in a
+    // captured log, so it has to actually turn color on.
+    setColorEnabled(true);
+  }
+
   if (flags.help) { console.log(HELP); return 0; }
   if (flags.version) { console.log(PACKAGE.version); return 0; }
 

package/cli/ui.js

@@ -4,7 +4,36 @@
 // all strip styling in one place. Nothing here is load-bearing — every message
 // has to read fine as plain text, because that is how logs and CI see it.
 
-export const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+// Color resolution, in strict precedence order:
+//
+//   1. An explicit `--no-color` / `NO_COLOR`  → off. A person who asked for plain
+//      text gets plain text, whatever the environment says.
+//   2. An explicit `--color` / `FORCE_COLOR`   → on. This is the documented way
+//      to keep ANSI in a captured log or a pipe, so it has to beat the TTY sniff.
+//   3. Otherwise, a TTY                         → on.
+//   4. Otherwise                               → off.
+//
+// Every step reads live rather than caching at import, because `main` parses
+// flags *after* the module graph has loaded. The old `const supportsColor = ...`
+// decided once, at import, which is before `--no-color` was knowable — so the
+// documented flags were silently ignored everywhere.
+let forced = null; // null = undecided, true = force on, false = force off
+
+export function setColorEnabled(on) {
+  forced = on === undefined ? null : Boolean(on);
+}
+
+export function colorEnabled() {
+  if (forced === false) return false;
+  if (forced === true) return true;
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+export function supportsColor() {
+  return colorEnabled();
+}
 
 const CODES = {
   reset: 0, bold: 1, dim: 2, italic: 3,
@@ -12,7 +41,7 @@ const CODES = {
 };
 
 export function paint(text, ...styles) {
-  if (!supportsColor || !styles.length) return String(text);
+  if (!colorEnabled() || !styles.length) return String(text);
   const open = styles.map((s) => `\x1b[${CODES[s]}m`).join('');
   return `${open}${text}\x1b[0m`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.5.0",
+  "version": "0.6.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/public/js/about.js

@@ -239,11 +239,18 @@ export function lineageCoverage(scan) {
   return out.join('\n');
 }
 
-// Both URL shapes git accepts: https://github.com/owner/repo(.git) and
-// git@github.com:owner/repo(.git). Anything else is not GitHub and gets no
-// remote lookup.
+// The GitHub URL parsing and the reading of the API payload also exist in
+// `/shared/analyzer/github.js`, where the terminal reads them. This copy is not
+// an oversight and cannot simply be deleted: this module is loaded by Node tests
+// (`tests/about.test.js`), and a `/shared/…` specifier does not resolve in Node,
+// so importing the shared version here would make this whole file unloadable
+// outside a browser. The duplication is therefore pinned by a test —
+// "the two GitHub URL parsers agree" — rather than left to drift, which is what
+// two unconnected copies of this regex had already done: the browser counted
+// `watchers_count` (a legacy alias for the *stargazer* count) and called it
+// "watching", printing the star number twice.
 export function githubRepoPath(url) {
-  const m = String(url).match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/);
+  const m = String(url ?? '').match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/);
   return m ? m[1] : null;
 }
 
@@ -262,21 +269,27 @@ async function loadRemoteInfo(repoPath) {
         : `GitHub answered ${res.status}.`);
     }
     const r = await res.json();
+    // `subscribers_count`, not `watchers_count`. The API carries both and
+    // `watchers_count` is a legacy alias for the *stargazer* count, so reading
+    // it printed the star number a second time and called it "watching". The
+    // real watcher count is the subscribers number.
+    const watching = Number.isFinite(r.subscribers_count) ? r.subscribers_count : 0;
+    const license = r.license?.spdx_id && r.license.spdx_id !== 'NOASSERTION' ? r.license.spdx_id : '';
     box.innerHTML = `
       <div class="about-numbers">
         ${aboutNum(r.stargazers_count ?? 0, 'stars')}
         ${aboutNum(r.forks_count ?? 0, 'forks')}
-        ${aboutNum(r.watchers_count ?? 0, 'watching')}
+        ${aboutNum(watching, 'watching')}
         ${aboutNum(r.open_issues_count ?? 0, 'open issues')}
       </div>
       ${r.description ? `<p class="about-desc">${escapeHtml(r.description)}</p>` : ''}
       <ul class="about-lineage">
-        ${r.license?.spdx_id ? `<li>License: ${escapeHtml(r.license.spdx_id)}</li>` : ''}
+        ${license ? `<li>License: ${escapeHtml(license)}</li>` : ''}
         <li>Created ${aboutDate(r.created_at)} · last push ${aboutDate(r.pushed_at)}.</li>
         ${r.default_branch ? `<li>Default branch: <code>${escapeHtml(r.default_branch)}</code></li>` : ''}
         ${r.topics?.length ? `<li>Topics: ${r.topics.map((t) => `<span class="stat-chip">${escapeHtml(t)}</span>`).join(' ')}</li>` : ''}
         ${r.homepage ? `<li><a href="${escapeHtml(r.homepage)}" target="_blank" rel="noopener noreferrer">${escapeHtml(r.homepage)}</a></li>` : ''}
-        <li class="doc-readme-none">GitHub keeps view counts private to the repo's owner — “watching” is the closest public number.</li>
+        <li class="doc-readme-none">These are GitHub's numbers, not this repository's — <code>health</code> and <code>risks</code> are about the code.</li>
       </ul>`;
   } catch (err) {
     box.innerHTML = `<span class="doc-readme-none">${escapeHtml(err.message)}</span>`;

package/server/gitRemote.js

@@ -0,0 +1,61 @@
+// The URL a local checkout came from — `git remote get-url origin`.
+//
+// The web app never needs this: it only shows remote facts for a repo it cloned
+// itself, where it already knows the URL it was given. A terminal session is
+// usually started *inside* somebody's checkout, so `github` there has no URL to
+// work from and has to ask git. That is the one place this surface is a strict
+// improvement on the site rather than a copy of it.
+//
+// Same discipline as `gitHistory.js`: git is spawned with an argument array,
+// never through a shell, and a repo with no remote is an expected outcome rather
+// than an error — a plain folder, a tarball, and a checkout with the remote
+// removed are all normal.
+
+import { spawn } from 'node:child_process';
+
+const TIMEOUT_MS = 10_000;
+
+/**
+ * The `origin` remote of a checkout, or null with a reason.
+ *
+ * `origin` specifically, not "the first remote": origin is the one that means
+ * "where this came from". A fork's `upstream` is a different repository, and
+ * reporting that repo's stars for a fork is a confident wrong answer.
+ */
+export function gitRemoteOrigin(root) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('git', ['-C', root, 'remote', 'get-url', 'origin'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({ ok: false, reason: 'Could not run git: ' + err.message });
+      return;
+    }
+
+    let out = '';
+    let stderr = '';
+    const cap = (buf, max) => (buf.length > max ? buf.slice(-max) : buf);
+    child.stdout.on('data', (c) => { out = cap(out + c, 2000); });
+    child.stderr.on('data', (c) => { stderr = cap(stderr + c, 2000); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve({ ok: false, reason: 'git took too long to say where this came from.' });
+    }, TIMEOUT_MS);
+
+    // `once`, and the promise is only ever settled once, so a timeout that
+    // races a late `close` cannot resolve an already-resolved promise.
+    const settle = (value) => { clearTimeout(timer); resolve(value); };
+
+    child.on('error', (err) => settle({ ok: false, reason: 'Could not run git: ' + err.message }));
+    child.on('close', (code) => {
+      const url = out.trim();
+      if (code === 0 && url) settle({ ok: true, url });
+      else if (/not a git repository/i.test(stderr)) settle({ ok: false, reason: 'This folder is not a git checkout, so it has no remote.' });
+      else if (code === 0) settle({ ok: false, reason: 'This checkout has no origin remote.' });
+      else settle({ ok: false, reason: 'git would not say: ' + (stderr.trim().split('\n').pop() || ('exited ' + code)) });
+    });
+  });
+}

package/server/layout.js

@@ -44,26 +44,53 @@ export function fit(text, max, { tail = true } = {}) {
 // '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);
+  // The hard ceiling is the terminal, and it is the *only* ceiling. This used to
+  // clamp to a 24-column floor "to guard against a nonsensical zero", but a
+  // floor above the available width is precisely the overflow this function
+  // exists to prevent: in a 10-column terminal it produced 26-column lines and
+  // wrapped the border. A terminal can be narrower than a box; below the point
+  // where a bordered box is readable at all, the frame degrades to a plain
+  // aligned list, which is still honest output instead of a lie about width.
+  const total = Math.max(1, Math.floor(columns || termWidth()) - indent.length);
+
+  // A border costs 2 cells on each side; the label column costs `labelWidth`,
+  // then a 2-cell gap, then a content indent. Below what is left there is no
+  // room for a readable value, so the border is dropped entirely rather than
+  // drawn wider than the terminal. The content indent goes too: at a 3-column
+  // terminal, indent(2) + content(2) + one character is already 5, and the
+  // indent is decoration, not information.
+  const borderWorthIt = total >= 16;
+  const bodyIndent = total >= 8 ? 2 : 0;
+  const labelWidth = borderWorthIt ? Math.min(12, Math.max(...rows.map((r) => width(r.label ?? '')), 0)) : 0;
+  const gap = labelWidth ? 2 : 0;
+  const valueRoom = Math.max(1, total - (borderWorthIt ? 2 : 0) - labelWidth - gap - bodyIndent);
+
   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)));
+    ? ' '.repeat(labelWidth + gap) + paint(fit(r.hint, valueRoom), 'hint')
+    : (labelWidth ? paint(fit(r.label ?? '', labelWidth).padEnd(labelWidth), 'label') + ' '.repeat(gap) : '')
+      + fit(r.value ?? '', valueRoom)));
+
+  if (!borderWorthIt) {
+    // No room for a frame. Still fitted, still labeled, just not boxed. The
+    // indent goes first — it is decoration, and at a 1–2 column terminal the
+    // 2-space indent plus a single content character is already 3, which wraps.
+    const lead = ' '.repeat(Math.max(0, Math.min(indent.length, total - 1)));
+    return [
+      paint(fit(title, total), 'title'),
+      ...body.map((line) => lead + ' '.repeat(bodyIndent) + fit(line, Math.max(1, total - lead.length - bodyIndent))),
+    ].join('\n');
+  }
 
   // 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));
+  // The 2-cell content indent belongs to the body, so it counts toward the
+  // width the border has to enclose.
+  const wanted = Math.max(...body.map((line) => width('  ' + line)), 1);
+  const inner = Math.min(total - 2, Math.max(1, wanted));
+  const shownTitle = fit(title, Math.max(0, 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');
+  return [indent + top, ...body.map((line) => indent + '  ' + line), indent + bottom].join('\n');
 }
 
 // A one-line note rendered in the panel's muted voice.

package/shared/analyzer/github.js

@@ -0,0 +1,81 @@
+// Reading a GitHub repository's public facts — the part the browser and the
+// terminal both need, and the part that was quietly wrong in one of them.
+//
+// This module is pure: it takes an already-parsed API payload and returns plain
+// data. The `fetch` deliberately stays on either side of it, because the two
+// callers can do things the other cannot — the browser must not hold a token,
+// and the terminal can. `shared/` may not know which runtime it is in, so the
+// network call is not here; only the reading of the answer is.
+//
+// One implementation, because the previous arrangement had the browser with its
+// own copy of the URL regex and its own idea of which counter means "watching",
+// and the two drifted apart without anything noticing.
+
+/**
+ * The `owner/repo` a git URL points at, or null if it is not a GitHub URL.
+ *
+ * Both URL shapes git accepts: `https://github.com/owner/repo(.git)` and
+ * `git@github.com:owner/repo(.git)`. Anything else is not GitHub, and gets no
+ * remote lookup — a GitLab or Bitbucket clone is a real outcome, not an error.
+ */
+export function githubRepoPath(url) {
+  const m = String(url ?? '').match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * The public facts worth showing, read out of `GET /repos/{owner}/{repo}`.
+ *
+ * Returns null for anything that is not an object, so a caller can tell "no
+ * facts" from "all zeroes" without a try/catch around every field.
+ */
+export function remoteFacts(json) {
+  if (!json || typeof json !== 'object') return null;
+  const count = (v) => (Number.isFinite(v) && v >= 0 ? Math.trunc(v) : 0);
+
+  return {
+    stars: count(json.stargazers_count),
+    forks: count(json.forks_count),
+    // `subscribers_count`, not `watchers_count`. The API has carried both for
+    // years and `watchers_count` is a legacy alias for the *stargazer* count —
+    // so labelling it "watching" printed the star number twice and called one
+    // of them watchers. The real watcher count is the subscribers number.
+    watching: count(json.subscribers_count),
+    issues: count(json.open_issues_count),
+    description: typeof json.description === 'string' ? json.description.trim() : '',
+    // "NOASSERTION" is GitHub's way of saying it found a license file it could
+    // not identify, which is not a license anyone can comply with.
+    license: json.license?.spdx_id && json.license.spdx_id !== 'NOASSERTION'
+      ? json.license.spdx_id
+      : '',
+    created: typeof json.created_at === 'string' ? json.created_at : '',
+    pushed: typeof json.pushed_at === 'string' ? json.pushed_at : '',
+    branch: typeof json.default_branch === 'string' ? json.default_branch : '',
+    topics: Array.isArray(json.topics)
+      ? json.topics.filter((t) => typeof t === 'string' && t).slice(0, 12)
+      : [],
+    homepage: typeof json.homepage === 'string' ? json.homepage.trim() : '',
+    archived: Boolean(json.archived),
+  };
+}
+
+/**
+ * Why a remote lookup did not produce facts, in the words a person can act on.
+ *
+ * 403, 404 and 429 are separated because they mean opposite things — one is
+ * "ask less often, or authenticate", one is "private, or gone, or never there",
+ * and one is "slow down" — and collapsing them into "GitHub said no" helps
+ * nobody diagnose anything.
+ */
+export function remoteError(status) {
+  if (status === 403) {
+    return 'GitHub rate-limited the ask — the unauthenticated allowance is 60 an hour.';
+  }
+  if (status === 404) {
+    return 'GitHub has no such repository, or it is private.';
+  }
+  if (status === 429) {
+    return 'GitHub is throttling this machine — try again in a minute.';
+  }
+  return 'GitHub answered ' + status + '.';
+}