codebase-onboarder 0.1.0

package/public/js/about.js

@@ -0,0 +1,284 @@
+// The About view: what this repo is, what it's built from, and how the scan
+// that produced this page actually went.
+//
+// The rendering needs the DOM, but the parts worth checking — the coverage
+// prose, the GitHub URL parsing, date formatting — are pure and exported for
+// that reason. Nothing here runs at import time.
+
+import { escapeHtml } from './html.js';
+import { state } from './state.js';
+import { streamExplain } from './api.js';
+import { mdLite } from './markdown.js';
+import * as llm from './llm.js';
+
+let host = null;
+let hooks = { onToast: () => {}, onOpenSettings: () => {}, repoOverview: () => '' };
+
+export function initAbout(options) {
+  host = options.host;
+  hooks = { ...hooks, ...options };
+  host.addEventListener('click', (event) => {
+    const b = event.target.closest('[data-stack-sum]');
+    if (b) summarizeStackItem(b.dataset.stackSum);
+  });
+}
+
+export function renderAbout() {
+  if (state.about.rendered) return;
+  state.about.rendered = true;
+  const { scan, facts } = state;
+  const gh = scan.gitUrl ? githubRepoPath(scan.gitUrl) : null;
+
+  const sourceLine = scan.gitUrl
+    ? `Cloned from ${scan.gitUrl}`
+    : state.browserSource
+      ? 'Picked in the browser — files never left this tab.'
+      : `Read in place from ${scan.root}`;
+
+  host.innerHTML = `
+    <div class="doc-page">
+      <h1 class="doc-title">${escapeHtml(scan.name)}</h1>
+      <p class="doc-sub">${escapeHtml(scan.tempId ? scan.tempId + ' — a temp clone' : scan.root)}</p>
+      <p class="doc-sub">${escapeHtml(sourceLine)}</p>
+
+      <div class="about-numbers">
+        ${aboutNum(scan.stats.filesParsed, 'code files')}
+        ${aboutNum(scan.stats.edgeCount, 'connections')}
+        ${aboutNum(facts.entries.length, 'entry points')}
+        ${aboutNum(facts.hubs.length, 'hubs')}
+        ${aboutNum(facts.cycles.length, 'cycles')}
+        ${aboutNum(Object.keys(scan.stats.languages).length, 'languages')}
+      </div>
+
+      <h2 class="doc-section-h">Stack</h2>
+      <div id="stackZone"></div>
+
+      ${renderHistorySection(state.history)}
+
+      <h2 class="doc-section-h">From the remote</h2>
+      <div id="aboutRemote">${
+        gh
+          ? '<span class="doc-readme-none">Asking GitHub…</span>'
+          : `<span class="doc-readme-none">${scan.gitUrl ? 'Not a GitHub URL — no remote facts to fetch.' : 'A local repo — no remote to ask about.'}</span>`
+      }</div>
+
+      <h2 class="doc-section-h">Lineage</h2>
+      <ul class="about-lineage">
+        <li>Scanned ${new Date(scan.scannedAt).toLocaleString()} in ${scan.stats.tookMs} ms.</li>
+        ${lineageCoverage(scan)}
+        ${scan.tempId ? `<li>The clone lives in your temp folder as <code>${escapeHtml(scan.tempId)}</code> until you hit New repo.</li>` : ''}
+      </ul>
+    </div>`;
+
+  if (gh) loadRemoteInfo(gh);
+  if (state.stack) renderStackZone(host.querySelector('#stackZone'));
+}
+
+function renderHistorySection(h) {
+  if (!h) return '';
+  if (!h.available) {
+    return `<h2 class="doc-section-h">History</h2><p class="doc-readme-none">${escapeHtml(h.reason || 'No history available.')}</p>`;
+  }
+  return `
+    <h2 class="doc-section-h">History & Activity</h2>
+    <div class="about-numbers">
+      ${aboutNum(h.commitCount, h.truncated ? 'commits analyzed' : 'commits')}
+      ${aboutNum(h.authors.length, 'contributors')}
+      ${aboutNum(h.soloFiles, 'solo-author files')}
+      ${aboutNum(h.coChanged.length, 'co-change pairs')}
+    </div>
+    <ul class="about-lineage">
+      ${h.firstCommitAt ? `<li>First commit: <b>${aboutDate(h.firstCommitAt)}</b> · Latest: <b>${aboutDate(h.lastCommitAt)}</b></li>` : ''}
+      ${h.authors.length ? `<li>Top contributors: ${h.authors.slice(0, 5).map((a) => `<b>${escapeHtml(a.name || a.email)}</b> (${a.commits})`).join(', ')}.</li>` : ''}
+    </ul>
+  `;
+}
+
+// ---- Stack: detected languages, package managers, and frameworks ----------
+
+function renderStackZone(zone) {
+  const st = state.stack;
+  if (!st) return (zone.innerHTML = '');
+
+  const langs = Object.entries(st.languages)
+    .map(([name, count]) => `<span class="stack-lang"><i>${count}</i> ${escapeHtml(name)}</span>`)
+    .join('');
+
+  const rows = st.items
+    .map(
+      (it) => `
+      <div class="stack-item">
+        <span class="stack-name">${escapeHtml(it.name)}</span>
+        <span class="stack-cat">${escapeHtml(it.category)}</span>
+        ${it.version ? `<span class="stack-ver">v${escapeHtml(it.version)}</span>` : ''}
+        ${it.dev ? '<span class="stack-dev">dev</span>' : ''}
+        <span class="stack-lang">${escapeHtml(it.lang)}</span>
+        <a class="stack-doc" href="${escapeHtml(it.docs)}" target="_blank" rel="noopener">docs ↗</a>
+        <button class="stack-sum" data-stack-sum="${escapeHtml(it.name)}" title="Summarize from official docs">summarize</button>
+        <div class="stack-body" data-stack-body></div>
+      </div>`
+    )
+    .join('');
+
+  zone.innerHTML = `
+    <div class="stack-block">
+      <div class="stack-langs">${langs || '<span class="doc-readme-none">No languages parsed.</span>'}</div>
+      ${st.pm.length ? `<p class="stack-pm">package managers: ${escapeHtml(st.pm.join(', '))}</p>` : ''}
+      ${st.items.length
+        ? `<div class="stack-grid">${rows}</div>
+           <p class="stack-hint">Each “summarize” fetches that library’s official docs and folds them into an AI field note.</p>`
+        : '<p class="doc-readme-none">No declared dependencies — nothing to analyze.</p>'}
+    </div>`;
+}
+
+// Fetch a library's official docs (server-side, SSRF-safe) and summarize it
+// with the AI, streamed into the row.
+async function summarizeStackItem(name) {
+  const item = state.stack.items.find((i) => i.name === name);
+  if (!item) return hooks.onToast('Unknown dependency.');
+  if (!llm.isConfigured()) {
+    hooks.onOpenSettings();
+    return hooks.onToast('Add an endpoint and model first.');
+  }
+  const row = host.querySelector(`[data-stack-sum="${CSS.escape(name)}"]`)?.closest('.stack-item');
+  const body = row?.querySelector('[data-stack-body]');
+  if (!body) return;
+
+  row.querySelector('.stack-sum').textContent = 'looking…';
+  row.querySelector('.stack-sum').disabled = true;
+
+  let docsText = '';
+  let docsTitle = '';
+  try {
+    const r = await fetch('/api/doc', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ url: item.docs }),
+    });
+    const j = await r.json();
+    if (j.text) {
+      docsText = j.text;
+      docsTitle = j.title || item.docs;
+    }
+  } catch { /* summarized from knowledge */ }
+
+  body.innerHTML = '<br><div class="stack-body-text"><span class="caret"></span></div>';
+  const slot = body.querySelector('.stack-body-text');
+  const settings = llm.getSettings();
+  const messages = llm.stackSummaryMessages({
+    repoName: state.scan.name,
+    item,
+    docsText,
+    repoNote: hooks.repoOverview(),
+  });
+  let text = '';
+  try {
+    for await (const delta of streamExplain({ ...settings, messages, maxTokens: 700 })) {
+      text += delta;
+      slot.innerHTML = mdLite(text) + '<span class="caret"></span>';
+    }
+    slot.innerHTML = mdLite(text)
+      + `<p class="explain-src">${docsText ? `From ${escapeHtml(docsTitle)}` : 'No docs fetched — general knowledge'} · ${settings.model}</p>`;
+  } catch (err) {
+    slot.innerHTML = `<p style="color:var(--warn)">${escapeHtml(err.message)}</p>`;
+  } finally {
+    const btn = row.querySelector('.stack-sum');
+    if (btn) {
+      btn.textContent = body.textContent.trim() ? 'summarize again' : 'summarize';
+      btn.disabled = false;
+    }
+  }
+}
+
+// ---- the pure parts -------------------------------------------------------
+
+export function aboutNum(value, label) {
+  return `<div class="about-num"><b>${value}</b><span>${label}</span></div>`;
+}
+
+// What the scan left out, itemized. The line here used to read "N files skipped
+// by the ignore rules", which was one number covering eight unrelated reasons —
+// most of them not the ignore rules at all.
+export function lineageCoverage(scan) {
+  const s = scan.stats;
+  const k = s.skips || {};
+  const out = [];
+
+  if (s.truncated) {
+    out.push(
+      `<li><b>Partial scan.</b> Stopped at the ${s.truncated.atFiles}-file cap with ` +
+      `${s.truncated.dirsQueued} ${s.truncated.dirsQueued === 1 ? 'directory' : 'directories'} ` +
+      `still unvisited — every count below is a floor, not a total.</li>`
+    );
+  }
+
+  const reasons = [
+    [k.ignored, 'matched .gitignore'],
+    [k.vendorDir, 'in vendor or build folders'],
+    [k.notSource, 'not source (images, lockfiles, bundles)'],
+    [k.notCode, 'no analyzer for the extension'],
+    [k.tooLarge, 'over the size cap'],
+    [k.readFailed, 'could not be read'],
+    [k.analyzeFailed, 'could not be parsed'],
+    [k.listFailed, 'directories that would not list'],
+  ].filter(([n]) => n > 0).map(([n, why]) => `${n} ${why}`);
+  if (reasons.length) {
+    out.push(`<li>${s.filesParsed} of ${s.filesTotal} files analyzed. Left out: ${reasons.join('; ')}.</li>`);
+  }
+
+  const imp = s.imports;
+  if (imp?.total) {
+    const worst = imp.worst?.length
+      ? ` Most common misses: ${imp.worst.slice(0, 3).map((w) => `<code>${escapeHtml(w.spec)}</code>`).join(', ')}.`
+      : '';
+    out.push(
+      `<li><b>${imp.confidence}% of ${imp.total} imports placed</b> — ${imp.internal} internal, ` +
+      `${imp.external} external packages, ${imp.unresolved} unresolved.${imp.unresolved ? worst : ''}</li>`
+    );
+  }
+  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.
+export function githubRepoPath(url) {
+  const m = String(url).match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/);
+  return m ? m[1] : null;
+}
+
+export function aboutDate(iso) {
+  if (!iso) return 'unknown';
+  return new Date(iso).toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+}
+
+async function loadRemoteInfo(repoPath) {
+  const box = host.querySelector('#aboutRemote');
+  try {
+    const res = await fetch(`https://api.github.com/repos/${repoPath}`);
+    if (!res.ok) {
+      throw new Error(res.status === 403
+        ? 'GitHub rate-limited the ask — unauthenticated allowance is 60 an hour.'
+        : `GitHub answered ${res.status}.`);
+    }
+    const r = await res.json();
+    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(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>` : ''}
+        <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>
+      </ul>`;
+  } catch (err) {
+    box.innerHTML = `<span class="doc-readme-none">${escapeHtml(err.message)}</span>`;
+  }
+}

package/public/js/aiDraft.js

@@ -0,0 +1,163 @@
+// The "AI draft" button: ask a model to redraw whatever the canvas is showing.
+//
+// Every view has a static diagram built from the import graph, and that is what
+// loads. This is the optional second opinion — the model gets a fact sheet (see
+// aiFacts.js) and answers with Mermaid, which is cached per view so flipping
+// between the two is instant afterwards.
+//
+// Three states for one button: draw, drawn (flip back to static), and drawing.
+// Nothing here is required for the app to work; with no endpoint configured the
+// button opens the settings drawer and says so.
+
+import { extractAIDiagram, matchNodeText } from '/shared/diagram/aiMermaid.js';
+import { streamExplain } from './api.js';
+import { state, aiViewKey } from './state.js';
+import { gatherFileContext } from './repoFiles.js';
+import {
+  diagramTarget, externalsFor, overviewFacts, layersFacts, servicesFacts,
+  fileFacts, tourStopFacts, folderFacts,
+} from '/shared/diagram/aiFacts.js';
+import * as llm from './llm.js';
+
+const MAX_TOKENS = 4000;
+const PROGRESS_MS = 250;
+
+let btn = null;
+let statusEl = null;
+let nodeHost = null;
+let hooks = {
+  onRender: () => {},
+  onOpenFile: () => {},
+  onOpenSettings: () => {},
+  onToast: () => {},
+};
+
+export function initAiDraft(options) {
+  btn = options.host;
+  statusEl = options.statusEl;
+  nodeHost = options.nodeHost;
+  hooks = { ...hooks, ...options };
+
+  btn.addEventListener('click', () => {
+    const key = aiViewKey();
+    if (state.aiActiveKey === key) {
+      state.aiActiveKey = null; // back to static
+      hooks.onRender();
+      return;
+    }
+    if (state.aiDiagrams[key]) {
+      state.aiActiveKey = key; // cached draft, instant
+      hooks.onRender();
+      return;
+    }
+    drawWithAI(key);
+  });
+}
+
+// Which of the three things the button currently offers. Called on every canvas
+// render, because the answer depends on the view.
+export function updateAiBtn(key = aiViewKey()) {
+  btn.hidden = state.view === 'docs' || state.view === 'about'
+    || (state.view === 'atlas' && !state.atlasOpen);
+  if (state.aiActiveKey === key) {
+    btn.textContent = 'Static';
+    btn.title = 'Back to the static diagram';
+  } else {
+    btn.textContent = state.aiDiagrams[key] ? 'AI draft ✓' : 'AI draft';
+    btn.title = 'Ask the AI to draw this view';
+  }
+}
+
+// AI nodes carry no stable ids — clicks are matched by label text instead.
+export function wireAIClicks() {
+  for (const g of nodeHost.querySelectorAll('g.node')) {
+    const path = matchNodeText(g.textContent, state.scan.files);
+    if (!path) continue;
+    g.style.cursor = 'pointer';
+    g.addEventListener('click', (event) => {
+      event.stopPropagation();
+      hooks.onOpenFile(path);
+    });
+  }
+}
+
+async function drawWithAI(key) {
+  if (!llm.isConfigured()) {
+    hooks.onOpenSettings();
+    hooks.onToast('Add an endpoint and model first.');
+    return;
+  }
+  const settings = llm.getSettings();
+  btn.disabled = true;
+  btn.textContent = 'drawing…';
+  statusEl.hidden = false;
+
+  // Live progress: elapsed time plus how much the model has written so far. A
+  // reasoning model can be quiet for half a minute, and a canvas that says
+  // nothing is indistinguishable from one that has hung.
+  const startedAt = Date.now();
+  let received = 0;
+  const tick = () => {
+    const secs = Math.round((Date.now() - startedAt) / 1000);
+    const kb = received >= 1000 ? (received / 1000).toFixed(1) + 'k' : String(received);
+    statusEl.textContent = `The AI is sketching this view… ${kb} chars · ${secs}s`;
+  };
+  tick();
+  const progressTimer = setInterval(tick, PROGRESS_MS);
+
+  try {
+    const { kind, facts } = await factsForView();
+    const messages = llm.diagramMessages({ repoName: state.scan.name, kind, facts });
+    let text = '';
+    // Big budget, and no visible thinking where the dialect allows it:
+    // reasoning models otherwise spend the whole allowance before a single
+    // diagram line appears. Azure rejects that parameter outright.
+    const providerOptions = llm.isAzureHost(settings.baseUrl) ? {} : { reasoning: { exclude: true } };
+    for await (const delta of streamExplain({ ...settings, messages, maxTokens: MAX_TOKENS, providerOptions })) {
+      text += delta;
+      received += delta.length;
+    }
+    const parsed = extractAIDiagram(text);
+    if (!parsed) throw new Error('The model answered without a diagram. Try again.');
+    state.aiDiagrams[key] = { body: parsed.body, caption: parsed.caption };
+    state.aiActiveKey = key;
+    statusEl.hidden = true;
+    hooks.onRender();
+  } catch (err) {
+    statusEl.hidden = true;
+    hooks.onToast(err.message);
+  } finally {
+    clearInterval(progressTimer);
+    btn.disabled = false;
+    updateAiBtn(key);
+  }
+}
+
+// Picks the sheet for the current view and fetches the source the file-shaped
+// ones need. The choosing is pure and tested in aiFacts.js; this is the read.
+async function factsForView() {
+  const { scan, facts, manifest, patterns } = state;
+  const target = diagramTarget(state);
+
+  switch (target.view) {
+    case 'map': return overviewFacts(scan, facts);
+    case 'patterns': return layersFacts(facts, patterns);
+    case 'services': return servicesFacts(scan, manifest);
+    case 'tour': {
+      const stop = state.tour.stops[state.tour.idx];
+      if (!stop) return tourStopFacts({ stop: null });
+      return tourStopFacts({
+        ctx: await gatherFileContext(target.path),
+        externals: externalsFor(scan, target.path),
+        stop,
+        index: state.tour.idx,
+        total: state.tour.stops.length,
+      });
+    }
+    case 'file': return fileFacts({
+      ctx: await gatherFileContext(target.path),
+      externals: externalsFor(scan, target.path),
+    });
+    default: return folderFacts(scan, facts, target.path);
+  }
+}