codebase-onboarder 0.1.0

package/public/js/mindmap.js

@@ -0,0 +1,289 @@
+// The Map view: the whole repository as a left-to-right tree of cells.
+// Folders expand into their contents; files expand into the cells they are
+// connected to (what they pull in, who leans on them); click again to
+// shrink. Every cell carries a one-line description. Layout is a small
+// tidy-tree: leaves get rows in order, parents center on their children.
+// Pure logic up front so it can be unit-tested without a DOM.
+
+export const GEOMETRY = {
+  colW: 250,
+  rowH: 58,
+  cellW: 204,
+  cellH: 46,
+  pad: 10,
+  maxFolderChildren: 30,
+  maxNeighbors: 6,
+};
+
+// Builds the root spec from the file tree. The app supplies the prose:
+//   folderInfo(node) -> { summary, cls }
+//   fileInfo(path)   -> { summary, cls, parsed, neighbors: [{path, relation}] }
+// `expanded` is a Set of spec ids ('dir:…', 'file:…') currently open.
+export function buildSpecs({ root, expanded, folderInfo, fileInfo, rootSummary }) {
+  const folderSpec = (node) => ({
+    id: 'dir:' + node.path,
+    kind: node.path ? 'folder' : 'root',
+    name: node.path ? node.name + '/' : rootSummary.name,
+    summary: node.path ? folderInfo(node).summary : rootSummary.summary,
+    cls: node.path ? folderInfo(node).cls || '' : 'is-root',
+    expandable: true,
+    nav: node.path || null,
+    kids: () => folderKids(node),
+  });
+
+  const folderKids = (node) => {
+    const dirs = [...node.dirs.values()]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map(folderSpec);
+    const files = node.files.slice().sort().map(fileSpec);
+    const shown = files.slice(0, GEOMETRY.maxFolderChildren);
+    const hidden = files.length - shown.length;
+    const more = hidden > 0
+      ? [{
+          id: 'more:' + node.path,
+          kind: 'more',
+          name: '+ ' + hidden + ' more',
+          summary: 'see them in Files view',
+          cls: 'is-ghost',
+          expandable: false,
+          navFolder: node.path,
+          kids: null,
+        }]
+      : [];
+    return [...dirs, ...shown, ...more];
+  };
+
+  const fileSpec = (path) => {
+    const info = fileInfo(path);
+    const name = path.split('/').pop();
+    if (!info.parsed) {
+      return {
+        id: 'file:' + path,
+        kind: 'file',
+        name,
+        summary: info.summary,
+        cls: 'is-plain',
+        expandable: false,
+        nav: path,
+        kids: null,
+      };
+    }
+    const neighbors = info.neighbors || [];
+    return {
+      id: 'file:' + path,
+      kind: 'file',
+      name,
+      summary: info.summary,
+      cls: info.cls || '',
+      expandable: neighbors.length > 0,
+      nav: path,
+      kids: () => {
+        const shown = neighbors.slice(0, GEOMETRY.maxNeighbors);
+        const hidden = neighbors.length - shown.length;
+        const specs = shown.map((n) => ({
+          id: 'g:' + path + ':' + n.path,
+          kind: 'ghost',
+          name: n.path.split('/').pop(),
+          summary: `${n.relation} · ${dirPart(n.path)}`,
+          cls: 'is-ghost',
+          expandable: false,
+          nav: n.path,
+          kids: null,
+        }));
+        if (hidden > 0) {
+          specs.push({
+            id: 'gmore:' + path,
+            kind: 'more',
+            name: '+ ' + hidden + ' more',
+            summary: 'open the deep-dive',
+            cls: 'is-ghost',
+            expandable: false,
+            nav: path,
+            kids: null,
+          });
+        }
+        return specs;
+      },
+    };
+  };
+
+  return folderSpec(root);
+}
+
+// Lays out the visible cells. Returns flat cell + edge lists with absolute
+// coordinates, plus the total size of the drawing.
+export function layoutMindMap(rootSpec, expanded) {
+  const cells = [];
+  const edges = [];
+  let nextRow = 0;
+  let maxDepth = 0;
+  const G = GEOMETRY;
+
+  const walk = (spec, depth) => {
+    const cell = {
+      id: spec.id,
+      kind: spec.kind,
+      name: spec.name,
+      summary: spec.summary,
+      cls: spec.cls,
+      expandable: spec.expandable,
+      nav: spec.nav ?? null,
+      navFolder: spec.navFolder ?? null,
+      depth,
+      x: G.pad + depth * G.colW,
+      w: G.cellW,
+      h: G.cellH,
+    };
+    cells.push(cell);
+    maxDepth = Math.max(maxDepth, depth);
+
+    const open = spec.expandable && expanded.has(spec.id);
+    const kidSpecs = open && spec.kids ? spec.kids() : [];
+    const kidCells = kidSpecs.map((k) => {
+      const kc = walk(k, depth + 1);
+      edges.push({ from: cell, to: kc, dashed: k.kind === 'ghost' || k.kind === 'more' });
+      return kc;
+    });
+    cell.row = kidCells.length
+      ? (kidCells[0].row + kidCells[kidCells.length - 1].row) / 2
+      : nextRow++;
+    cell.y = G.pad + cell.row * G.rowH;
+    return cell;
+  };
+
+  walk(rootSpec, 0);
+
+  return {
+    cells,
+    edges,
+    width: G.pad * 2 + (maxDepth + 1) * G.colW,
+    height: G.pad * 2 + nextRow * G.rowH,
+  };
+}
+// Draws the layout into the canvas: SVG elbow edges underneath, HTML cells
+// on top (better text handling and click targets than SVG text).
+// handlers: onToggle(cell) for real cells, onNavigate(cell) for ghosts.
+export function renderMindMap(container, layout, expanded, handlers) {
+  container.innerHTML = '';
+
+  const wrap = document.createElement('div');
+  wrap.className = 'mm';
+  wrap.style.width = layout.width + 'px';
+  wrap.style.height = layout.height + 'px';
+
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('class', 'mm-svg');
+  svg.setAttribute('width', layout.width);
+  svg.setAttribute('height', layout.height);
+
+  const edgePaths = new Map(); // edge -> svgPath
+  const cellElements = new Map(); // cellId -> domElement
+  const parentMap = new Map(); // cell -> { parentCell, edge }
+  const childMap = new Map(); // cell -> Array<{ childCell, edge }>
+
+  for (const edge of layout.edges) {
+    const x1 = edge.from.x + edge.from.w;
+    const y1 = edge.from.y + edge.from.h / 2;
+    const x2 = edge.to.x;
+    const y2 = edge.to.y + edge.to.h / 2;
+    const bend = Math.max(30, (x2 - x1) / 2);
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', `M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}`);
+    path.setAttribute('class', 'mm-edge' + (edge.dashed ? ' is-dashed' : ''));
+    svg.appendChild(path);
+    edgePaths.set(edge, path);
+
+    parentMap.set(edge.to, { parentCell: edge.from, edge });
+    if (!childMap.has(edge.from)) childMap.set(edge.from, []);
+    childMap.get(edge.from).push({ childCell: edge.to, edge });
+  }
+  wrap.appendChild(svg);
+
+  for (const cell of layout.cells) {
+    const el = document.createElement('div');
+    el.className = 'mm-cell ' + (cell.cls || '') + ' kind-' + cell.kind;
+    el.style.left = cell.x + 'px';
+    el.style.top = cell.y + 'px';
+    el.style.width = cell.w + 'px';
+    el.style.minHeight = cell.h + 'px';
+    cellElements.set(cell.id, el);
+
+    const head = document.createElement('div');
+    head.className = 'mm-head';
+    if (cell.expandable) {
+      const caret = document.createElement('span');
+      caret.className = 'mm-caret';
+      caret.textContent = expanded.has(cell.id) ? '▾' : '▸';
+      head.appendChild(caret);
+    }
+    const name = document.createElement('span');
+    name.className = 'mm-name';
+    name.textContent = cell.name;
+    name.title = cell.nav || cell.name;
+    head.appendChild(name);
+    el.appendChild(head);
+
+    if (cell.summary) {
+      const sum = document.createElement('div');
+      sum.className = 'mm-sum';
+      sum.textContent = cell.summary;
+      el.appendChild(sum);
+    }
+
+    // Branch hover highlighting
+    el.addEventListener('mouseenter', () => {
+      wrap.classList.add('has-hover');
+      el.classList.add('is-active-branch');
+
+      // Trace ancestors up to root
+      let cur = cell;
+      while (parentMap.has(cur)) {
+        const { parentCell, edge } = parentMap.get(cur);
+        const edgePath = edgePaths.get(edge);
+        if (edgePath) edgePath.classList.add('is-active');
+        const pEl = cellElements.get(parentCell.id);
+        if (pEl) pEl.classList.add('is-active-branch');
+        cur = parentCell;
+      }
+
+      // Trace direct children
+      const kids = childMap.get(cell) || [];
+      for (const { childCell, edge } of kids) {
+        const edgePath = edgePaths.get(edge);
+        if (edgePath) edgePath.classList.add('is-active');
+        const cEl = cellElements.get(childCell.id);
+        if (cEl) cEl.classList.add('is-active-branch');
+      }
+    });
+
+    el.addEventListener('mouseleave', () => {
+      wrap.classList.remove('has-hover');
+      for (const edgePath of edgePaths.values()) {
+        edgePath.classList.remove('is-active');
+      }
+      for (const cellEl of cellElements.values()) {
+        cellEl.classList.remove('is-active-branch');
+      }
+    });
+
+    el.addEventListener('click', (event) => {
+      event.stopPropagation();
+      if (cell.kind === 'ghost' || cell.kind === 'more') {
+        handlers.onNavigate(cell);
+      } else if (cell.expandable) {
+        handlers.onToggle(cell);
+      } else {
+        handlers.onNavigate(cell);
+      }
+    });
+    wrap.appendChild(el);
+  }
+
+  container.appendChild(wrap);
+  return wrap;
+}
+
+function dirPart(path) {
+  const i = path.lastIndexOf('/');
+  return i === -1 ? '(root)' : path.slice(0, i);
+}

package/public/js/repoFiles.js

@@ -0,0 +1,44 @@
+// Reading a file out of whichever repo is loaded, and packing up what the
+// prompts need to know about it.
+//
+// Two sources, one signature: a server-side scan fetches over HTTP, a
+// browser-picked folder reads from the File System Access handle it kept. Every
+// caller that wants file text goes through here, so neither the docs view nor
+// the code tab has to know which kind of repo it is looking at.
+
+import { roleOf, scanIndex } from '/shared/analyzer/graph.js';
+import { state } from './state.js';
+import { fetchFileText } from './api.js';
+
+export async function readRepoFile(path) {
+  if (state.browserSource) return state.browserSource.read(path);
+  if (state.scanId) return fetchFileText(state.scanId, path);
+  throw new Error('no file source for this repo');
+}
+
+// Everything the AI prompts want about one file: its place in the graph, plus
+// its source if we can get it. A failed read is not an error — the prompts are
+// written to work from the graph alone, and say so.
+export async function gatherFileContext(path) {
+  const file = scanIndex(state.scan).fileAt(path);
+  let source = '';
+  try {
+    source = await readRepoFile(path);
+  } catch {
+    source = '';
+  }
+  return {
+    path,
+    // Read from the graph, not from whatever the inspector happens to be
+    // showing. This used to be `document.querySelector('#inspRole').textContent`,
+    // which is why one caller overwrote the field immediately afterwards.
+    role: roleOf(path, state.facts),
+    fanIn: state.facts.fanIn[path] || 0,
+    fanOut: state.facts.fanOut[path] || 0,
+    importers: state.facts.importers[path] || [],
+    imports: state.facts.importsOf[path] || [],
+    functions: file?.functions.map((f) => f.name),
+    exports_: file?.exports.map((e) => e.name),
+    source,
+  };
+}

package/public/js/sbomView.js

@@ -0,0 +1,142 @@
+// Software Bill of Materials (SBOM) & License Compliance View.
+// Renders dependency inventory, license classification, and copyleft compliance audit.
+
+import { escapeHtml } from './html.js';
+
+export function renderSbom(container, { scan }) {
+  if (!container) return;
+
+  const report = scan?.licenseReport || {
+    projectLicense: scan?.license || { id: 'UNKNOWN', name: 'Unknown', type: 'unknown' },
+    sbom: scan?.sbom || [],
+    counts: { permissive: 0, copyleft: 0, weakCopyleft: 0, unknown: 0, total: 0 },
+    complianceStatus: 'clean',
+  };
+
+  const sbom = report.sbom || [];
+  const counts = report.counts || { permissive: 0, copyleft: 0, weakCopyleft: 0, unknown: 0, total: sbom.length };
+  const projectLicense = report.projectLicense || { id: 'UNKNOWN', name: 'Unknown' };
+
+  // The filter bar is pointless when there is nothing to filter.
+  // Built as a separate template — nesting backticks inline breaks the
+  // dangling-call lint (nested template literals defeat its string blanking).
+  const filterBar = sbom.length ? `
+      <div class="sbom-filter-bar">
+        <input type="text" class="text-input sbom-search-input" id="sbomSearchInput" placeholder="Filter dependencies or licenses…">
+        <div class="sbom-filter-chips">
+          <button class="btn btn-ghost btn-sm is-active" data-filter="all">All (${sbom.length})</button>
+          <button class="btn btn-ghost btn-sm" data-filter="prod">Production</button>
+          <button class="btn btn-ghost btn-sm" data-filter="dev">Development</button>
+          <button class="btn btn-ghost btn-sm" data-filter="copyleft">Copyleft (${counts.copyleft})</button>
+        </div>
+      </div>` : '';
+
+  container.innerHTML = `
+    <div class="sbom-layout">
+      <!-- License Header & Summary -->
+      <header class="sbom-header">
+        <div class="sbom-lic-card">
+          <span class="sbom-lic-label">Project License</span>
+          <div class="sbom-lic-val">
+            <span class="sbom-badge is-${projectLicense.type || 'permissive'}">${escapeHtml(projectLicense.id)}</span>
+            <span class="sbom-lic-name">${escapeHtml(projectLicense.name)}</span>
+          </div>
+        </div>
+
+        <div class="sbom-stat-cards">
+          <div class="sbom-stat-chip">
+            <b>${counts.total}</b> Total Packages
+          </div>
+          <div class="sbom-stat-chip is-permissive">
+            <b>${counts.permissive}</b> Permissive
+          </div>
+          <div class="sbom-stat-chip is-copyleft">
+            <b>${counts.copyleft}</b> Copyleft
+          </div>
+          <div class="sbom-stat-chip is-weak">
+            <b>${counts.weakCopyleft}</b> Weak Copyleft
+          </div>
+        </div>
+      </header>
+
+      <!-- Search & Filter Controls (only useful with packages to filter) -->
+      ${filterBar}
+
+      <!-- Dependencies Inventory Table -->
+      <div class="sbom-table-wrap">
+        <table class="sbom-table" id="sbomTable">
+          <thead>
+            <tr>
+              <th>Package Name</th>
+              <th>Version</th>
+              <th>Ecosystem</th>
+              <th>Type</th>
+              <th>License</th>
+            </tr>
+          </thead>
+          <tbody id="sbomTableBody">
+            ${renderSbomRows(sbom)}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  `;
+
+  // Wire search & filtering
+  const searchInput = container.querySelector('#sbomSearchInput');
+  const tableBody = container.querySelector('#sbomTableBody');
+  const filterBtns = container.querySelectorAll('.sbom-filter-chips button');
+
+  let activeFilter = 'all';
+
+  function applyFilter() {
+    const q = (searchInput?.value || '').toLowerCase().trim();
+    const filtered = sbom.filter((item) => {
+      if (activeFilter === 'prod' && item.isDev) return false;
+      if (activeFilter === 'dev' && !item.isDev) return false;
+      if (activeFilter === 'copyleft' && item.license?.type !== 'copyleft') return false;
+
+      if (!q) return true;
+      return item.name.toLowerCase().includes(q)
+        || item.ecosystem.toLowerCase().includes(q)
+        || String(item.license?.id || '').toLowerCase().includes(q);
+    });
+
+    if (tableBody) tableBody.innerHTML = renderSbomRows(filtered, { filtered: true });
+  }
+
+  searchInput?.addEventListener('input', applyFilter);
+
+  filterBtns.forEach((btn) => {
+    btn.addEventListener('click', () => {
+      filterBtns.forEach((b) => b.classList.remove('is-active'));
+      btn.classList.add('is-active');
+      activeFilter = btn.dataset.filter;
+      applyFilter();
+    });
+  });
+}
+
+function renderSbomRows(items, { filtered } = {}) {
+  if (!items.length) {
+    // Distinguish "nothing matched your filter" from "this project simply
+    // declares no dependencies" — the latter is a finding, not a dead end.
+    if (!filtered) {
+      return '<tr><td colspan="5" class="sbom-no-results">No dependency manifests found — this project declares no npm, pip, Go, or Cargo dependencies.</td></tr>';
+    }
+    return '<tr><td colspan="5" class="sbom-no-results">No packages match the current filter.</td></tr>';
+  }
+
+  return items.map((item) => {
+    const lic = item.license || { id: 'Unknown', type: 'unknown' };
+    return `
+      <tr>
+        <td class="sbom-cell-pkg"><b>${escapeHtml(item.name)}</b></td>
+        <td class="sbom-cell-ver"><code>${escapeHtml(item.version)}</code></td>
+        <td class="sbom-cell-eco"><span class="eco-tag eco-${item.ecosystem}">${escapeHtml(item.ecosystem)}</span></td>
+        <td class="sbom-cell-dev"><span class="dep-type-chip ${item.isDev ? 'is-dev' : 'is-prod'}">${item.isDev ? 'dev' : 'prod'}</span></td>
+        <td class="sbom-cell-lic"><span class="sbom-badge is-${lic.type}">${escapeHtml(lic.id)}</span></td>
+      </tr>
+    `;
+  }).join('');
+}

package/public/js/scanCache.js

@@ -0,0 +1,76 @@
+// Scan caching & trend analysis. Pure logic so it is unit-tested without a browser.
+
+export function hashString(str) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16);
+}
+
+export function repoCacheKey(scan) {
+  if (!scan) return '';
+  const id = scan.gitUrl || scan.root || scan.name || '';
+  const summary = (scan.files || [])
+    .slice(0, 100)
+    .map((f) => `${f.path}:${f.size}:${f.loc}`)
+    .join('|');
+  return `onboarder.cache.${hashString(id)}.${hashString(summary)}`;
+}
+
+export function compareScans(prev, curr) {
+  if (!prev || !curr) return null;
+  const prevScore = prev.health?.score ?? prev.score ?? 100;
+  const currScore = curr.health?.score ?? curr.score ?? 100;
+  const scoreDiff = currScore - prevScore;
+  const prevFiles = prev.scan?.files?.length ?? prev.files?.length ?? 0;
+  const currFiles = curr.scan?.files?.length ?? curr.files?.length ?? 0;
+  const filesDiff = currFiles - prevFiles;
+
+  return {
+    scoreDiff,
+    filesDiff,
+    trend: scoreDiff > 0 ? 'improving' : scoreDiff < 0 ? 'degrading' : 'stable',
+    summary: scoreDiff > 0
+      ? `Health improved by +${scoreDiff} pts since last scan.`
+      : scoreDiff < 0
+        ? `Health decreased by ${scoreDiff} pts since last scan.`
+        : 'Health score matches previous scan.',
+  };
+}
+
+export class ScanCache {
+  constructor(storage = typeof localStorage !== 'undefined' ? localStorage : null) {
+    this.storage = storage;
+    this.memory = new Map();
+  }
+
+  get(key) {
+    if (this.memory.has(key)) return this.memory.get(key);
+    if (!this.storage) return null;
+    try {
+      const raw = this.storage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      this.memory.set(key, parsed);
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  set(key, val) {
+    this.memory.set(key, val);
+    if (!this.storage) return;
+    try {
+      this.storage.setItem(key, JSON.stringify(val));
+    } catch {
+      // Quota exceeded or disabled
+    }
+  }
+
+  clear() {
+    this.memory.clear();
+  }
+}