@dev-tren/mapd 0.21.0

package/src/core/trace.js

@@ -0,0 +1,151 @@
+/**
+ * trace.js — `mapd trace <file>` and `mapd trace <from> <to>`.
+ *
+ * One command answers both reachability questions the wishlist asked for:
+ *   trace <file>         why this file is in / out of a workflow — its workflow
+ *                        membership, the shortest import/call chain from an entry
+ *                        point that reaches it, or the exact reason it's uncovered
+ *                        (orphan, generated, dynamically-loaded, annotated dormant,
+ *                        heuristic-unverified, or excluded).
+ *   trace <from> <to>    the concrete import/call chain connecting two files.
+ *
+ * Deterministic: it walks the real import and cross-file call edges the graph
+ * already computed. If two files are connected only dynamically, it says so
+ * rather than inventing a path.
+ */
+
+import path from "node:path";
+
+/** Resolve a user-typed path to a real graph file: exact, else unique suffix match. */
+export function resolveFile(graph, arg) {
+  const norm = arg.replace(/^\.\//, "");
+  if (graph.files.some((f) => f.file === norm)) return { file: norm };
+  const suffix = graph.files.filter((f) => f.file === norm || f.file.endsWith(`/${norm}`) || path.posix.basename(f.file) === norm);
+  if (suffix.length === 1) return { file: suffix[0].file };
+  if (suffix.length > 1) return { ambiguous: suffix.map((f) => f.file) };
+  return { notFound: true };
+}
+
+/** file→[{to, via}] adjacency over internal import edges and cross-file call edges. */
+function buildAdjacency(graph) {
+  const adj = new Map();
+  const push = (from, to, via) => {
+    if (from === to) return;
+    if (!adj.has(from)) adj.set(from, []);
+    const list = adj.get(from);
+    if (!list.some((e) => e.to === to && e.via === via)) list.push({ to, via });
+  };
+  for (const e of graph.importEdges ?? []) if (e.to) push(e.from, e.to, "import");
+  for (const e of graph.callEdges ?? []) {
+    if (e.resolution === "cross-file" && e.to) {
+      const toFile = String(e.to).split("#")[0];
+      const fromFile = String(e.from).split("#")[0];
+      push(fromFile, toFile, "call");
+    }
+  }
+  return adj;
+}
+
+/** Shortest edge path from `start` to `goal` (BFS). Returns [{from,to,via}] or null. */
+function shortestPath(adj, start, goal) {
+  if (start === goal) return [];
+  const prev = new Map([[start, null]]);
+  const q = [start];
+  while (q.length) {
+    const cur = q.shift();
+    for (const e of adj.get(cur) ?? []) {
+      if (prev.has(e.to)) continue;
+      prev.set(e.to, { from: cur, via: e.via });
+      if (e.to === goal) {
+        const chain = [];
+        let node = goal;
+        while (prev.get(node)) { const p = prev.get(node); chain.unshift({ from: p.from, to: node, via: p.via }); node = p.from; }
+        return chain;
+      }
+      q.push(e.to);
+    }
+  }
+  return null;
+}
+
+const REACH_LABELS = {
+  generatedArtifacts: "a generated/build artifact",
+  dynamicallyLoaded: "loaded dynamically (detected)",
+  intentionalDormant: "annotated intentional-dormant",
+  heuristicUnverified: "heuristic-parsed and unverifiable by import tracing",
+  trulyOrphaned: "an orphan — reached by no entry point",
+};
+
+/** Why is <file> in / out of a workflow? */
+export function traceFile(graph, file) {
+  const adj = buildAdjacency(graph);
+  const workflows = graph.workflows.filter((w) => w.files.includes(file));
+  const importers = (graph.importEdges ?? []).filter((e) => e.to === file).map((e) => e.from);
+
+  const result = { file, inWorkflow: workflows.length > 0, workflows: workflows.map((w) => w.id), importers };
+
+  if (workflows.length) {
+    // shortest chain from the containing workflow's entry to this file
+    for (const w of workflows) {
+      const p = shortestPath(adj, w.entry.file, file);
+      if (p) { result.reachedFrom = { entry: w.entry.file, workflow: w.id, chain: p }; break; }
+    }
+    if (!result.reachedFrom) result.reachedNote = "in the workflow's file set but not via a static import/call chain from the entry (likely wired by a detected dynamic edge or annotation).";
+    return result;
+  }
+
+  // uncovered — find the exact reason
+  const r = graph.reachability ?? {};
+  const has = (bucket) => (r[bucket] ?? []).some((x) => (typeof x === "string" ? x : x.file) === file);
+  for (const bucket of Object.keys(REACH_LABELS)) if (has(bucket)) { result.classification = bucket; result.reason = REACH_LABELS[bucket]; return result; }
+  if ((graph.orphans ?? []).includes(file)) { result.classification = "trulyOrphaned"; result.reason = REACH_LABELS.trulyOrphaned; return result; }
+  if ((graph.generatedFiles ?? []).some((g) => (g.file ?? g) === file)) { result.classification = "generatedArtifacts"; result.reason = REACH_LABELS.generatedArtifacts; return result; }
+  result.classification = "uncovered";
+  result.reason = "not in any workflow and not classified — it may be imported only by uncovered files, or reachable only dynamically.";
+  return result;
+}
+
+/** The import/call chain from <from> to <to> (or the reverse if that's the real direction). */
+export function tracePath(graph, from, to) {
+  const adj = buildAdjacency(graph);
+  const forward = shortestPath(adj, from, to);
+  if (forward) return { from, to, direction: "forward", chain: forward };
+  const backward = shortestPath(adj, to, from);
+  if (backward) return { from, to, direction: "reverse", chain: backward, note: `${to} reaches ${from}, not the other way around.` };
+  return { from, to, chain: null, note: "no static import/call chain connects these files — they may be linked only through a dynamic edge, or not at all." };
+}
+
+// ── renderers ────────────────────────────────────────────────────────────────
+
+export function renderTraceFile(data, theme) {
+  const { bold, dim, green, yellow, red, cyan } = theme;
+  const lines = [`\n${bold("trace")} ${cyan(data.file)}`];
+  if (data.inWorkflow) {
+    lines.push(`  ${green("in workflow(s):")} ${data.workflows.join(", ")}`);
+    if (data.reachedFrom) {
+      lines.push(`  reached from ${bold(data.reachedFrom.entry)} ${dim(`(${data.reachedFrom.workflow})`)}:`);
+      lines.push(`      ${data.reachedFrom.entry}`);
+      for (const step of data.reachedFrom.chain) lines.push(`        ${dim(step.via === "call" ? "──calls──▶" : "──imports──▶")} ${step.to}`);
+    } else if (data.reachedNote) {
+      lines.push(dim(`  ${data.reachedNote}`));
+    }
+  } else {
+    lines.push(`  ${yellow("not in any workflow")} — ${data.reason}`);
+    lines.push(dim(`  classification: ${data.classification}`));
+  }
+  if (data.importers.length) lines.push(dim(`  imported by: ${data.importers.slice(0, 8).join(", ")}${data.importers.length > 8 ? " …" : ""}`));
+  else if (!data.inWorkflow) lines.push(dim("  imported by: (nothing static)"));
+  return lines.join("\n");
+}
+
+export function renderTracePath(data, theme) {
+  const { bold, dim, green, red, cyan } = theme;
+  const lines = [`\n${bold("trace")} ${cyan(data.from)} ${dim("→")} ${cyan(data.to)}`];
+  if (!data.chain) { lines.push(`  ${red("no path")} — ${data.note}`); return lines.join("\n"); }
+  if (data.note) lines.push(dim(`  ${data.note}`));
+  const start = data.direction === "reverse" ? data.to : data.from;
+  lines.push(`  ${green("path")} (${data.chain.length} hop(s)):`);
+  lines.push(`      ${start}`);
+  for (const step of data.chain) lines.push(`        ${dim(step.via === "call" ? "──calls──▶" : "──imports──▶")} ${step.to}`);
+  return lines.join("\n");
+}

package/src/core/verify.js

@@ -0,0 +1,123 @@
+/**
+ * verify.js — one command to prove the project is in a known-good state.
+ *
+ * `mapd verify` runs the gates a human or CI would otherwise run by hand —
+ * config validate, build the scored map, doctor, baseline regression compare,
+ * score delta, report freshness — and collapses them into a single verdict with
+ * a CI-friendly exit code and a PR-ready one-liner.
+ *
+ * It is pure orchestration: every gate calls the existing engine, so verify can
+ * never disagree with the individual commands. The CI contract is the wishlist's
+ * rule — FAIL on MEANINGFUL regressions (invalid config, new parse failures,
+ * high-severity workflow regressions), not on low-value modernization noise or a
+ * schema bump.
+ */
+
+import { buildScoredGraph } from "./intelligence.js";
+import { loadConfig, validateConfig } from "../config/index.js";
+import { runDoctor } from "./doctor.js";
+import { loadBaseline, diffGraphs } from "./regression.js";
+import { checkReportFreshness } from "./staleness.js";
+import { deltaScore, ceilingScore } from "./score.js";
+import { bold, dim, red, green, yellow, cyan, confidenceColor } from "./theme.js";
+
+const HIGH_MEANING = new Set(["workflow-removed", "export-removed", "parse-failure"]);
+
+export function runVerify(rootDir, { strict = false } = {}) {
+  const abs = rootDir;
+  const gates = [];
+  const gate = (name, status, detail) => gates.push({ name, status, detail });
+
+  // 1. config
+  const cfg = validateConfig(loadConfig(abs));
+  gate("config", cfg.ok ? "pass" : "fail", cfg.ok ? "resolved configuration is valid" : cfg.errors.join("; "));
+
+  // 2. map (building the scored graph is itself the check that the tree parses into a model)
+  const current = buildScoredGraph(abs);
+  gate("map", "pass", `${current.stats.fileCount} files, ${current.workflows.length} workflow(s), repo confidence ${current.repoConfidence}`);
+
+  // 3. doctor — environment/readiness. Its failures are informational (stale reports,
+  //    node version), not code regressions, so a failure is a WARN here.
+  const doc = runDoctor(abs);
+  const failedChecks = doc.checks.filter((c) => !c.ok).map((c) => c.name);
+  gate("doctor", doc.ok ? "pass" : "warn", doc.ok ? "all readiness checks passed" : `failing: ${failedChecks.join(", ")}`);
+
+  // 4. baseline regression compare + score delta
+  let findings = null, delta = null, baselineState;
+  const loaded = loadBaseline(abs);
+  if (!loaded) {
+    baselineState = "none";
+    gate("baseline", "warn", "no baseline — run `mapd baseline` to enable regression checks");
+  } else if (loaded.schemaMismatch) {
+    baselineState = "schema-mismatch";
+    gate("baseline", "warn", `baseline schema v${loaded.schemaMismatch.found} != v${loaded.schemaMismatch.expected}; re-baseline to compare (not a regression)`);
+  } else {
+    baselineState = "present";
+    findings = diffGraphs(loaded.graph, current);
+    delta = deltaScore(loaded.graph, current);
+    const high = findings.filter((f) => f.severity === "high");
+    const meaningful = high.filter((f) => HIGH_MEANING.has(f.kind) || f.kind === "confidence-regression");
+    if (meaningful.length) {
+      gate("regression", "fail", `${meaningful.length} high-severity regression(s): ${meaningful.map((f) => f.kind).join(", ")}`);
+    } else if (findings.length) {
+      gate("regression", "warn", `${findings.length} non-blocking finding(s) (${findings.map((f) => f.severity).join(", ")})`);
+    } else {
+      gate("regression", "pass", `no regressions; confidence ${delta.from} → ${delta.to} (${delta.delta >= 0 ? "+" : ""}${delta.delta})`);
+    }
+  }
+
+  // 5. report freshness
+  const fresh = checkReportFreshness(abs);
+  gate("freshness", fresh.stale ? "warn" : "pass",
+    fresh.stale ? `stale report(s): ${fresh.staleReports.join(", ")} — re-run mapd check/modernize` : "reports current");
+
+  const ceiling = ceilingScore(abs, current);
+
+  const hasFail = gates.some((g) => g.status === "fail");
+  const hasWarn = gates.some((g) => g.status === "warn");
+  const verdict = hasFail ? "fail" : hasWarn ? "warn" : "pass";
+  const exitCode = hasFail ? 2 : (strict && hasWarn) ? 1 : 0;
+
+  const prSummary = delta
+    ? `Map'd: confidence ${delta.from} → ${delta.to} (${delta.delta >= 0 ? "+" : ""}${delta.delta})` +
+      (delta.signals.length ? `, mainly ${delta.signals.slice(0, 2).map((s) => `${s.delta >= 0 ? "+" : ""}${s.delta} ${s.signal}`).join(", ")}` : "") +
+      `. Verdict: ${verdict.toUpperCase()}.`
+    : `Map'd: repo confidence ${current.repoConfidence} (no comparable baseline). Verdict: ${verdict.toUpperCase()}.`;
+
+  return {
+    verdict, ok: !hasFail, exitCode, strict,
+    gates,
+    summary: {
+      repoConfidence: current.repoConfidence,
+      baseline: baselineState,
+      delta,
+      findings: findings ? {
+        total: findings.length,
+        high: findings.filter((f) => f.severity === "high").length,
+        medium: findings.filter((f) => f.severity === "medium").length,
+        low: findings.filter((f) => f.severity === "low").length,
+      } : null,
+      ceiling: { value: ceiling.ceiling, signalCoverage: ceiling.ceilingSignalCoverage },
+      stale: { stale: fresh.stale, reports: fresh.staleReports ?? [] },
+      heuristicFiles: current.stats.heuristicFileCount ?? 0,
+    },
+    prSummary,
+  };
+}
+
+export function renderVerify(v) {
+  const glyph = { pass: green("✓"), warn: yellow("⚠"), fail: red("✗") };
+  const lines = [`\n${bold("Map'd verify")}`];
+  for (const g of v.gates) lines.push(`  ${glyph[g.status]} ${bold(g.name.padEnd(11))} ${dim(g.detail)}`);
+
+  const s = v.summary;
+  lines.push("");
+  lines.push(`  repo confidence: ${confidenceColor(s.repoConfidence)(s.repoConfidence)}  ${dim(`ceiling ${s.ceiling.value} (signalCoverage ${s.ceiling.signalCoverage})`)}`);
+  if (s.delta) lines.push(`  since baseline:  ${s.delta.from} → ${s.delta.to}  ${s.delta.delta >= 0 ? green(`+${s.delta.delta}`) : red(String(s.delta.delta))}`);
+
+  const vColor = v.verdict === "pass" ? green : v.verdict === "warn" ? yellow : red;
+  lines.push("");
+  lines.push(`  ${bold("verdict:")} ${vColor(v.verdict.toUpperCase())}  ${dim(`(exit ${v.exitCode}${v.strict ? ", strict" : ""})`)}`);
+  lines.push(dim(`  PR: ${v.prSummary}`));
+  return lines.join("\n");
+}

package/src/core/view.js

@@ -0,0 +1,221 @@
+/**
+ * view.js — `mapd view`. Emits ONE self-contained HTML file (no server, no CDN,
+ * data inlined) with three views the wishlist asked for:
+ *   • graph  — workflows, their entry, and the file/edge counts (dynamic +
+ *              unresolved edges and annotations called out)
+ *   • heatmap — every file as a cell, recolorable by confidence-workflow, test
+ *              credit, reachability, or dynamic-call density
+ *   • diff    — per-workflow confidence vs the saved baseline (when present)
+ *
+ * Everything shown is derived from the real scored graph — no invented numbers.
+ */
+
+import { buildScoredGraph } from "./intelligence.js";
+import { loadBaseline } from "./regression.js";
+import { classifyTestCredit } from "./testGuidance.js";
+import { ceilingScore } from "./score.js";
+
+const ANON = /^<anon[:>]/;
+
+export function buildViewModel(rootDir) {
+  const graph = buildScoredGraph(rootDir);
+  const credit = new Map(classifyTestCredit(graph).map((c) => [c.file, c.status]));
+  const wfByFile = new Map();
+  for (const w of graph.workflows) for (const f of w.files) {
+    if (!wfByFile.has(f)) wfByFile.set(f, []);
+    wfByFile.get(f).push(w.id);
+  }
+
+  // per-file dynamic/unresolved call density
+  const dyn = new Map();
+  for (const e of graph.callEdges ?? []) {
+    if (e.resolution === "dynamic" || e.resolution === "unresolved") {
+      const f = String(e.from).split("#")[0];
+      dyn.set(f, (dyn.get(f) ?? 0) + 1);
+    }
+  }
+  const reachClass = (file) => {
+    const r = graph.reachability ?? {};
+    for (const [bucket, label] of Object.entries({ generatedArtifacts: "generated", dynamicallyLoaded: "dynamic", intentionalDormant: "dormant", heuristicUnverified: "heuristic", trulyOrphaned: "orphan" })) {
+      if ((r[bucket] ?? []).some((x) => (typeof x === "string" ? x : x.file) === file)) return label;
+    }
+    return wfByFile.has(file) ? "reachable" : "uncovered";
+  };
+
+  const files = graph.files.map((f) => ({
+    file: f.file,
+    loc: f.loc ?? 0,
+    parser: f.parserKind ?? "ast",
+    test: credit.get(f.file) ?? "untested",
+    reach: reachClass(f.file),
+    dynamic: dyn.get(f.file) ?? 0,
+    anon: (f.functions ?? []).filter((fn) => !fn.name || ANON.test(fn.name)).length,
+    workflows: wfByFile.get(f.file) ?? [],
+    annotated: !!(graph.reachability?.intentionalDormant ?? []).some?.((x) => (typeof x === "string" ? x : x.file) === f.file),
+  }));
+
+  const loaded = loadBaseline(rootDir);
+  const baseWf = loaded && !loaded.schemaMismatch ? new Map(loaded.graph.workflows.map((w) => [w.id, w.confidence.score])) : null;
+
+  const workflows = graph.workflows.map((w) => ({
+    id: w.id,
+    entry: w.entry.file,
+    kind: w.entry.kind,
+    fileCount: w.files.length,
+    confidence: w.confidence.score,
+    signalCoverage: w.confidence.signalCoverage,
+    signals: Object.fromEntries(Object.entries(w.confidence.signals).map(([k, s]) => [k, s.value])),
+    baseline: baseWf ? baseWf.get(w.id) ?? null : null,
+    dynamicEdges: (w.files.reduce((a, f) => a + (dyn.get(f) ?? 0), 0)),
+  }));
+
+  const ceiling = ceilingScore(rootDir, graph);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    root: rootDir,
+    repoConfidence: graph.repoConfidence,
+    ceiling: { value: ceiling.ceiling, signalCoverage: ceiling.ceilingSignalCoverage },
+    stats: { files: graph.files.length, workflows: graph.workflows.length, orphans: (graph.orphans ?? []).length, resolutionRate: graph.stats.callResolutionRate },
+    baselinePresent: !!baseWf,
+    workflows,
+    files,
+  };
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+
+export function renderViewHtml(model, { serve = false } = {}) {
+  const json = JSON.stringify(model).replace(/</g, "\\u003c");
+  const askTab = serve ? `<button class="tab" data-v="ask">💬 Ask Map'd</button>` : "";
+  const askView = serve ? `<section class="view" id="v-ask">
+<div class="card mut" style="font-size:13px">Ask about anything you see here — I read the real map and reports. Try: <b>what should I work on</b>, <b>what's the honest ceiling</b>, <b>show test gaps</b>, <b>explain finding &lt;id&gt;</b>, <b>is the project passing</b>. (Read-only: fixes &amp; approvals stay in the terminal.)</div>
+<div id="chatlog"></div>
+<div style="display:flex;gap:8px;margin-top:10px"><input id="chatin" placeholder="Ask Map'd…" style="flex:1;padding:9px 12px;border:1px solid var(--line);border-radius:8px;background:var(--panel);color:var(--fg);font:inherit"><button id="chatsend" class="tab on" style="cursor:pointer">Send</button></div>
+</section>` : "";
+  const askCss = serve ? `.msg{margin:8px 0;padding:9px 12px;border-radius:8px;max-width:90%;white-space:pre-wrap;font-size:13px;overflow-x:auto}
+.msg.you{background:var(--acc);color:#fff;margin-left:auto}.msg.mapd{background:var(--panel);border:1px solid var(--line)}
+#chatlog{display:flex;flex-direction:column;min-height:120px}` : "";
+  const askJs = serve ? `
+const log=document.getElementById('chatlog'),inp=document.getElementById('chatin'),snd=document.getElementById('chatsend');
+function add(who,txt){const d=document.createElement('div');d.className='msg '+who;d.textContent=txt;log.appendChild(d);log.scrollTop=log.scrollHeight;return d;}
+const CMD=/(work on|ceiling|test gap|padding|passing|status|explain|score|improve|verify|resolution|trace|solution|diagnose|which files|untested)/i;
+async function ask(){const q=inp.value.trim();if(!q)return;inp.value='';add('you',q);
+  const slow=!CMD.test(q);const t=add('mapd',slow?'thinking… (free-form answers use the LLM and can take up to a minute)':'…');
+  snd.disabled=true;inp.disabled=true;
+  const ac=new AbortController();const to=setTimeout(()=>ac.abort(),180000);
+  try{const r=await fetch('/api/chat',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({message:q}),signal:ac.signal});const j=await r.json();t.textContent=j.reply;}
+  catch(e){t.textContent=e.name==='AbortError'?'(that took too long and timed out — try a command-style question like "what should I work on", which answers instantly)':'(could not reach the Map\\'d server — is it still running in your terminal?)';}
+  finally{clearTimeout(to);snd.disabled=false;inp.disabled=false;inp.focus();log.scrollTop=log.scrollHeight;}}
+snd.onclick=ask;inp.addEventListener('keydown',e=>{if(e.key==='Enter'&&!snd.disabled)ask();});
+inp.focus();` : "";
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Map'd — ${esc(model.root)}</title>
+<style>
+:root{--bg:#0f1115;--panel:#171a21;--line:#262b36;--fg:#e6e9ef;--dim:#8b93a3;--good:#3fb950;--warn:#d29922;--bad:#f85149;--acc:#58a6ff}
+@media (prefers-color-scheme:light){:root{--bg:#f6f8fa;--panel:#fff;--line:#d0d7de;--fg:#1f2328;--dim:#656d76;--acc:#0969da}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+header{padding:20px 24px;border-bottom:1px solid var(--line)}h1{margin:0 0 4px;font-size:18px}.sub{color:var(--dim);font-size:13px}
+.big{font-size:30px;font-weight:700}.stats{display:flex;gap:28px;flex-wrap:wrap;margin-top:12px}.stat b{display:block;font-size:20px}
+main{padding:20px 24px;max-width:1200px;margin:0 auto}.tabs{display:flex;gap:8px;margin:16px 0}
+.tab{padding:6px 14px;border:1px solid var(--line);border-radius:20px;background:var(--panel);color:var(--fg);cursor:pointer;font-size:13px}
+.tab.on{background:var(--acc);border-color:var(--acc);color:#fff}
+.view{display:none}.view.on{display:block}
+.card{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:14px 16px;margin-bottom:12px}
+.wf{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:10px}
+.bar{height:8px;border-radius:4px;background:var(--line);overflow:hidden;flex:1;min-width:120px}.bar>i{display:block;height:100%}
+.sig{display:grid;grid-template-columns:130px 1fr 48px;gap:8px;align-items:center;margin-top:6px;font-size:12px;color:var(--dim)}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(16px,1fr));gap:3px;margin-top:8px}
+.cell{aspect-ratio:1;border-radius:3px;cursor:pointer;border:1px solid rgba(0,0,0,.15)}
+.legend{display:flex;gap:14px;flex-wrap:wrap;margin:10px 0;font-size:12px;color:var(--dim)}.legend span{display:inline-flex;align-items:center;gap:5px}
+.sw{width:12px;height:12px;border-radius:3px;display:inline-block}
+.metric{display:flex;gap:6px;flex-wrap:wrap;margin:10px 0}.metric button{font-size:12px;padding:4px 10px;border:1px solid var(--line);background:var(--panel);color:var(--fg);border-radius:6px;cursor:pointer}.metric button.on{border-color:var(--acc);color:var(--acc)}
+#detail{position:sticky;bottom:0;background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:10px 14px;margin-top:10px;font-size:13px;min-height:20px}
+table{border-collapse:collapse;width:100%;font-size:13px}td,th{border-bottom:1px solid var(--line);padding:7px 8px;text-align:left}
+.up{color:var(--good)}.down{color:var(--bad)}.mut{color:var(--dim)}
+.pill{font-size:11px;padding:1px 7px;border-radius:10px;border:1px solid var(--line);color:var(--dim)}
+${askCss}
+</style></head><body>
+<header>
+<h1>Map'd <span class="sub">— ${esc(model.root)}</span></h1>
+<div class="stats">
+<div class="stat"><span class="sub">repo confidence</span><b class="big" id="rc"></b></div>
+<div class="stat"><span class="sub">honest ceiling</span><b id="cl"></b></div>
+<div class="stat"><span class="sub">files</span><b id="nf"></b></div>
+<div class="stat"><span class="sub">workflows</span><b id="nw"></b></div>
+<div class="stat"><span class="sub">call resolution</span><b id="rr"></b></div>
+</div>
+<div class="sub" style="margin-top:6px" id="gen"></div>
+</header>
+<main>
+<div class="tabs">
+<button class="tab on" data-v="graph">Graph</button>
+<button class="tab" data-v="heat">Heatmap</button>
+<button class="tab" data-v="diff">Diff vs baseline</button>
+${askTab}
+</div>
+${askView}
+<section class="view on" id="v-graph"></section>
+<section class="view" id="v-heat">
+<div class="metric" id="metricbar"></div>
+<div class="legend" id="legend"></div>
+<div class="grid" id="heat"></div>
+<div id="detail" class="mut">Hover or click a cell for file details.</div>
+</section>
+<section class="view" id="v-diff"></section>
+</main>
+<script id="data" type="application/json">${json}</script>
+<script>
+const M=JSON.parse(document.getElementById('data').textContent);
+const conf=v=>v>=.8?'var(--good)':v>=.6?'var(--warn)':'var(--bad)';
+document.getElementById('rc').textContent=M.repoConfidence;document.getElementById('rc').style.color=conf(M.repoConfidence);
+document.getElementById('cl').textContent=M.ceiling.value+' ('+M.ceiling.signalCoverage+')';
+document.getElementById('nf').textContent=M.stats.files;document.getElementById('nw').textContent=M.stats.workflows;
+document.getElementById('rr').textContent=(M.stats.resolutionRate*100).toFixed(1)+'%';
+document.getElementById('gen').textContent='generated '+M.generatedAt+(M.stats.orphans?(' · '+M.stats.orphans+' orphan(s)'):'');
+
+// GRAPH: workflow cards with signal bars
+const SIG=['parseIntegrity','resolutionRate','testPresence','stability'];
+document.getElementById('v-graph').innerHTML=M.workflows.map(w=>{
+  const bars=SIG.map(s=>{const v=w.signals[s];const val=v==null?0:v;const txt=v==null?'n/a':val.toFixed(2);
+    return '<div class="sig"><span>'+s+'</span><div class="bar"><i style="width:'+(val*100)+'%;background:'+conf(val)+'"></i></div><span>'+txt+'</span></div>';}).join('');
+  return '<div class="card"><div class="wf"><div><b>'+w.id+'</b> <span class="pill">'+w.kind+'</span> <span class="mut">entry '+w.entry+'</span></div>'+
+    '<div style="text-align:right"><b style="color:'+conf(w.confidence)+';font-size:18px">'+w.confidence+'</b><br><span class="mut">'+w.fileCount+' files · sigCov '+w.signalCoverage+(w.dynamicEdges?' · '+w.dynamicEdges+' dyn edges':'')+'</span></div></div>'+bars+'</div>';
+}).join('');
+
+// HEATMAP
+const METRICS={
+  confidence:{label:'workflow confidence',color:f=>{const w=M.workflows.filter(w=>f.workflows.includes(w.id));if(!w.length)return '#3a3f4b';return conf(Math.min(...w.map(x=>x.confidence)));},legend:[['#3fb950','high ≥.8'],['#d29922','.6–.8'],['#f85149','<.6'],['#3a3f4b','uncovered']]},
+  test:{label:'test credit',color:f=>({'tested-real':'#3fb950','tested-shallow':'#58a6ff','tested-nameonly':'#d29922','untested':'#f85149'}[f.test]||'#3a3f4b'),legend:[['#3fb950','real'],['#58a6ff','shallow'],['#d29922','name-only'],['#f85149','untested']]},
+  reach:{label:'reachability',color:f=>({reachable:'#3fb950',dynamic:'#58a6ff',dormant:'#8b5cf6',generated:'#8b93a3',heuristic:'#d29922',orphan:'#f85149',uncovered:'#3a3f4b'}[f.reach]||'#3a3f4b'),legend:[['#3fb950','reachable'],['#58a6ff','dynamic'],['#d29922','heuristic'],['#f85149','orphan'],['#8b93a3','generated']]},
+  dynamic:{label:'dynamic-call density',color:f=>{const d=f.dynamic;return d===0?'#3a3f4b':d<3?'#d29922':d<10?'#e8703a':'#f85149';},legend:[['#3a3f4b','0'],['#d29922','1–2'],['#e8703a','3–9'],['#f85149','10+']]}
+};
+let metric='test';
+const mbar=document.getElementById('metricbar');
+mbar.innerHTML=Object.entries(METRICS).map(([k,m])=>'<button data-m="'+k+'"'+(k===metric?' class="on"':'')+'>'+m.label+'</button>').join('');
+function drawHeat(){
+  const m=METRICS[metric];
+  document.getElementById('legend').innerHTML=m.legend.map(([c,l])=>'<span><i class="sw" style="background:'+c+'"></i>'+l+'</span>').join('');
+  document.getElementById('heat').innerHTML=M.files.map((f,i)=>'<div class="cell" data-i="'+i+'" title="'+f.file.replace(/"/g,'')+'" style="background:'+m.color(f)+'"></div>').join('');
+}
+mbar.onclick=e=>{if(e.target.dataset.m){metric=e.target.dataset.m;[...mbar.children].forEach(b=>b.classList.toggle('on',b.dataset.m===metric));drawHeat();}};
+const det=document.getElementById('detail');
+document.getElementById('heat').addEventListener('mouseover',e=>{const i=e.target.dataset.i;if(i==null)return;const f=M.files[i];
+  det.className='';det.innerHTML='<b>'+f.file+'</b> · '+f.loc+' LOC · '+f.parser+' · test: '+f.test+' · '+f.reach+(f.dynamic?' · '+f.dynamic+' dynamic calls':'')+(f.anon?' · '+f.anon+' anon fn':'')+(f.workflows.length?' · '+f.workflows.join(', '):' · not in a workflow');});
+drawHeat();
+
+// DIFF
+const dv=document.getElementById('v-diff');
+if(!M.baselinePresent){dv.innerHTML='<div class="card mut">No comparable baseline. Run <code>mapd baseline</code> to enable the diff view.</div>';}
+else{dv.innerHTML='<table><tr><th>workflow</th><th>baseline</th><th>current</th><th>Δ</th></tr>'+M.workflows.map(w=>{const b=w.baseline;const d=b==null?null:+(w.confidence-b).toFixed(3);
+  const cls=d==null?'mut':d>0?'up':d<0?'down':'mut';return '<tr><td>'+w.id+'</td><td>'+(b==null?'—':b)+'</td><td>'+w.confidence+'</td><td class="'+cls+'">'+(d==null?'new':(d>0?'+':'')+d)+'</td></tr>';}).join('')+'</table>';}
+
+// TABS
+document.querySelectorAll('.tab').forEach(t=>t.onclick=()=>{
+  document.querySelectorAll('.tab').forEach(x=>x.classList.toggle('on',x===t));
+  document.querySelectorAll('.view').forEach(v=>v.classList.remove('on'));
+  document.getElementById('v-'+t.dataset.v).classList.add('on');
+});
+${askJs}
+</script></body></html>`;
+}

package/src/core/viewServer.js

@@ -0,0 +1,88 @@
+/**
+ * viewServer.js — `mapd view --serve`. A tiny localhost-only HTTP server that
+ * serves the HTML view AND backs an embedded chat panel, so you can ask Map'd
+ * what's going on and what to work on right in the browser.
+ *
+ * The chat panel drives the EXACT same engine as `mapd chat` (createChatContext
+ * + handleInput), but READ-ONLY: it will run the analysis/reporting commands and
+ * answer grounded questions, and it refuses anything that writes to the project
+ * (fix, approve/dismiss, shell commands, report-writing commands). Those still
+ * require explicit local confirmation in the terminal. Binds to 127.0.0.1 only.
+ */
+
+import http from "node:http";
+import { spawn } from "node:child_process";
+import { createChatContext, handleInput } from "../chat/repl.js";
+import { classifyIntent } from "../chat/intent.js";
+import { recordTurn } from "./session.js";
+import { buildViewModel, renderViewHtml } from "./view.js";
+
+// Slash commands that only READ (no .mapd or source writes). Everything else is
+// refused in the browser: baseline/check/docs/modernize/transcript write files;
+// fix/approve/dismiss/dev-commands mutate or execute.
+const READONLY_SLASH = new Set([
+  "map", "status", "score", "ceiling", "test-gaps", "test-credit", "improve",
+  "verify", "review", "findings", "evidence", "project", "diagnose", "solutions",
+  "context", "resolution", "trace", "help", "clear",
+]);
+
+const stripAnsi = (s) => String(s).replace(/\[[0-9;]*m/g, "");
+
+export async function answerReadOnly(text, ctx) {
+  const trimmed = String(text ?? "").trim();
+  if (!trimmed) return 'Ask me something — e.g. "what should I work on", "what\'s the honest ceiling", "show test gaps", "explain finding <id>", "is the project passing".';
+  const intent = classifyIntent(trimmed);
+  if (["fix", "review-action", "dev-command", "watch"].includes(intent.type)) {
+    return "That action changes the project (a fix, approval, or command), so it's disabled in the read-only browser view. Run it in the terminal with `mapd chat`.";
+  }
+  if (intent.type === "slash" && !READONLY_SLASH.has(intent.command.replace(/^\//, ""))) {
+    return `\`${intent.command}\` writes to the project, so it's disabled here. Use it in \`mapd chat\`.`;
+  }
+  recordTurn(ctx.session, "user", trimmed);
+  const reply = stripAnsi(await handleInput(trimmed, ctx));
+  recordTurn(ctx.session, "assistant", reply);
+  return reply;
+}
+
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch { /* best effort */ }
+}
+
+export function startViewServer(rootDir, { port = 0, open = true } = {}) {
+  const ctx = createChatContext(rootDir);
+  const server = http.createServer((req, res) => {
+    const send = (code, type, body) => { res.writeHead(code, { "content-type": type }); res.end(body); };
+    if (req.method === "GET" && (req.url === "/" || req.url.startsWith("/?"))) {
+      return send(200, "text/html; charset=utf-8", renderViewHtml(buildViewModel(rootDir), { serve: true }));
+    }
+    if (req.method === "GET" && req.url === "/api/model") {
+      return send(200, "application/json", JSON.stringify(buildViewModel(rootDir)));
+    }
+    if (req.method === "POST" && req.url === "/api/chat") {
+      let body = "";
+      req.on("data", (c) => { body += c; if (body.length > 8000) req.destroy(); });
+      req.on("end", async () => {
+        let message = "";
+        try { message = JSON.parse(body).message ?? ""; } catch { /* ignore */ }
+        try {
+          const reply = await answerReadOnly(String(message).slice(0, 2000), ctx);
+          send(200, "application/json", JSON.stringify({ reply }));
+        } catch (e) {
+          send(200, "application/json", JSON.stringify({ reply: `Something went wrong answering that: ${e.message}` }));
+        }
+      });
+      return;
+    }
+    send(404, "text/plain", "not found");
+  });
+
+  return new Promise((resolve) => {
+    server.listen(port, "127.0.0.1", () => {
+      const url = `http://127.0.0.1:${server.address().port}/`;
+      if (open) openBrowser(url);
+      resolve({ server, url, port: server.address().port, providerAvailable: !!ctx.provider?.available?.() });
+    });
+  });
+}