@dev-tren/mapd 0.21.0

package/src/core/configLint.js

@@ -0,0 +1,141 @@
+/**
+ * configLint.js — `mapd config lint`. Catches configuration that quietly lies
+ * to you: an annotation on a file you also excluded (so it never takes effect),
+ * an annotation whose glob matches nothing (a stale path), a glob broad enough
+ * to sweep in files you never meant, a dead exclude that matches nothing, and
+ * manual assertions with no attribution (who said this, why, when).
+ *
+ * Every finding carries a concrete suggested patch. Deterministic: it reads the
+ * resolved config, the real on-disk file list, and the scored graph — no guesses.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../config/index.js";
+import { DEFAULTS } from "../config/schema.js";
+import { buildScoredGraph } from "./intelligence.js";
+import { globToRegex } from "./reachability.js";
+import { bold, dim, red, green, yellow, cyan } from "./theme.js";
+
+/** Minimal recursive source walk (posix-relative), skipping the dirs a parser never reads. */
+function listDiskFiles(rootDir) {
+  const SKIP = new Set(["node_modules", ".git", ".mapd"]);
+  const out = [];
+  const walk = (abs, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.name !== ".mapdrc") { if (SKIP.has(e.name)) continue; }
+      if (SKIP.has(e.name)) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(abs, e.name), childRel);
+      else out.push(childRel);
+    }
+  };
+  walk(rootDir, "");
+  return out;
+}
+
+const DEFAULT_EXCLUDES = new Set(DEFAULTS.project.exclude);
+
+/** Attribution fields present on an object-form annotation value. */
+function attribution(raw) {
+  if (!raw || typeof raw !== "object") return [];
+  return ["reason", "source", "date"].filter((k) => raw[k]);
+}
+
+export function lintConfig(rootDir) {
+  const abs = path.resolve(rootDir);
+  const config = loadConfig(abs);
+  const graph = buildScoredGraph(abs);
+
+  const graphFiles = graph.files.map((f) => f.file);
+  const graphSet = new Set(graphFiles);
+  const diskFiles = listDiskFiles(abs);
+  const excludedFiles = diskFiles.filter((f) => !graphSet.has(f)); // on disk but dropped by excludes/ignores
+  const wfFiles = new Set(graph.workflows.flatMap((w) => w.files));
+
+  const annotations = config.project?.annotations ?? {};
+  const excludes = config.project?.exclude ?? [];
+
+  const findings = [];
+  const add = (level, code, message, patch) => findings.push({ level, code, message, suggestedPatch: patch });
+
+  const matchIn = (list, pattern) => { const re = globToRegex(pattern); return list.filter((f) => re.test(f)); };
+
+  for (const [pattern, raw] of Object.entries(annotations)) {
+    const classification = typeof raw === "string" ? raw : raw?.classification;
+    const inGraph = matchIn(graphFiles, pattern);
+    const inExcluded = matchIn(excludedFiles, pattern);
+
+    if (inGraph.length === 0 && inExcluded.length > 0) {
+      add("error", "excluded-but-annotated",
+        `annotation "${pattern}" (${classification}) only matches files that project.exclude removed from the map (${inExcluded.slice(0, 3).join(", ")}${inExcluded.length > 3 ? ", …" : ""}) — the annotation can never take effect.`,
+        `remove the annotation, or stop excluding those files (a file cannot be both excluded and, e.g., an entrypoint).`);
+    } else if (inGraph.length === 0) {
+      add("warn", "stale-annotation",
+        `annotation "${pattern}" (${classification}) matches no current file — a stale or mistyped path.`,
+        `remove it: \`mapd annotate remove ${pattern}\`, or fix the glob.`);
+    }
+
+    if (inGraph.length > 1 && graphFiles.length >= 5 && inGraph.length / graphFiles.length > 0.4) {
+      add("warn", "over-broad-annotation",
+        `annotation "${pattern}" (${classification}) matches ${inGraph.length}/${graphFiles.length} files — far broader than a targeted assertion.`,
+        `narrow the glob to the specific file(s) or directory you mean.`);
+    }
+
+    if (classification && typeof raw === "string") {
+      add("advice", "unattributed-annotation",
+        `annotation "${pattern}" (${classification}) has no attribution — who asserted it, why, and when.`,
+        `record it as { "classification": "${classification}", "reason": "…", "source": "you/PR", "date": "${new Date().toISOString().slice(0, 10)}" }.`);
+    } else if (raw && typeof raw === "object" && attribution(raw).length < 3) {
+      const missing = ["reason", "source", "date"].filter((k) => !raw[k]);
+      add("advice", "partial-attribution",
+        `annotation "${pattern}" is missing attribution field(s): ${missing.join(", ")}.`,
+        `add the missing field(s) so the manual assertion is auditable.`);
+    }
+  }
+
+  // User-added excludes (beyond the shipped defaults) that match nothing on disk.
+  for (const pattern of excludes) {
+    if (DEFAULT_EXCLUDES.has(pattern)) continue;
+    if (matchIn(diskFiles, pattern).length === 0) {
+      add("warn", "dead-exclude",
+        `project.exclude "${pattern}" matches no file on disk — a stale or ineffective exclude.`,
+        `remove it from project.exclude.`);
+    }
+  }
+
+  // An exclude that removes files which ARE reached by a workflow is almost
+  // always a mistake (you're hiding live code from the map). Detect via the
+  // set difference: excluded files whose basename still appears wired in.
+  for (const pattern of excludes) {
+    if (DEFAULT_EXCLUDES.has(pattern)) continue;
+    const excludedHit = matchIn(excludedFiles, pattern).filter((f) => wfFiles.has(f));
+    if (excludedHit.length) {
+      add("error", "excludes-live-code", `project.exclude "${pattern}" removes files a workflow still reaches: ${excludedHit.slice(0, 3).join(", ")}.`,
+        `stop excluding them, or annotate them intentional-dormant if they really are dead.`);
+    }
+  }
+
+  const errors = findings.filter((f) => f.level === "error").length;
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  return {
+    ok: errors === 0,
+    counts: { error: errors, warn: warnings, advice: findings.filter((f) => f.level === "advice").length },
+    findings,
+  };
+}
+
+export function renderConfigLint(result) {
+  const glyph = { error: red("✗"), warn: yellow("⚠"), advice: cyan("i") };
+  const lines = [`\n${bold("config lint")}`];
+  if (!result.findings.length) { lines.push(green("  No configuration problems found.")); return lines.join("\n"); }
+  for (const f of result.findings) {
+    lines.push(`  ${glyph[f.level]} ${bold(f.code)}  ${f.message}`);
+    lines.push(dim(`      patch: ${f.suggestedPatch}`));
+  }
+  const c = result.counts;
+  lines.push(`\n  ${c.error ? red(`${c.error} error(s)`) : green("0 errors")}, ${c.warn} warning(s), ${c.advice} advisory(ies).`);
+  return lines.join("\n");
+}

package/src/core/diagnose.js

@@ -0,0 +1,262 @@
+/**
+ * diagnose.js — Map'd's self-awareness report.
+ *
+ * This is deliberately deterministic: it does not ask a provider to judge the
+ * repo. It inspects the graph, package scripts, confidence signals, runtime
+ * blind spots, and env-variable contract, then says where Map'd's
+ * understanding is strong or incomplete.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { buildScoredGraph } from "./intelligence.js";
+import { loadPkg } from "./graph.js";
+import { loadConfig } from "../config/index.js";
+
+const RUNTIME_SCRIPT_NAMES = new Set(["start", "dev", "serve", "preview", "server", "worker", "electron", "desktop"]);
+const NON_RUNTIME_SCRIPT_NAMES = new Set(["test", "lint", "typecheck", "type-check", "build", "coverage", "format", "prettier"]);
+const RUNTIME_SCRIPT_RE = /\b(node|tsx|ts-node|vite|next|nuxt|astro|remix|electron|nodemon|webpack-dev-server)\b/i;
+const ENV_DOT_RE = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)\b/g;
+const ENV_BRACKET_RE = /\bprocess\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+const ENV_DYNAMIC_RE = /\bprocess\.env\[[^\]'"][^\]]*\]/g;
+const ENV_DESTRUCTURE_RE = /\b(?:const|let|var)\s*\{([^}]+)\}\s*=\s*process\.env\b/g;
+
+function sortedEntries(obj = {}) {
+  return Object.entries(obj).sort(([a], [b]) => a.localeCompare(b));
+}
+
+function scriptLooksRuntime(name, command) {
+  const lower = String(name ?? "").toLowerCase();
+  if (NON_RUNTIME_SCRIPT_NAMES.has(lower) || lower.startsWith("test:") || lower.startsWith("lint:")) return false;
+  if (RUNTIME_SCRIPT_NAMES.has(lower) || lower.endsWith(":dev") || lower.endsWith(":start")) return true;
+  return RUNTIME_SCRIPT_RE.test(String(command ?? ""));
+}
+
+function collectRuntimeScripts(pkg, graph) {
+  const mappedNpmScripts = new Set((graph.entryPoints ?? [])
+    .filter((e) => e.kind === "npm-script")
+    .map((e) => e.detail));
+  return sortedEntries(pkg?.scripts ?? {})
+    .filter(([name, command]) => scriptLooksRuntime(name, command))
+    .map(([name, command]) => ({
+      name,
+      command,
+      mappedAsEntry: mappedNpmScripts.has(name),
+    }));
+}
+
+function addEnvKey(map, key, file) {
+  if (!key) return;
+  const item = map.get(key) ?? { key, files: new Set(), count: 0 };
+  item.files.add(file);
+  item.count++;
+  map.set(key, item);
+}
+
+function collectEnvReads(rootDir, graph) {
+  const abs = path.resolve(rootDir);
+  const keys = new Map();
+  const dynamic = [];
+  for (const f of graph.files ?? []) {
+    let source = "";
+    try { source = fs.readFileSync(path.join(abs, f.file), "utf8"); } catch { continue; }
+
+    for (const re of [ENV_DOT_RE, ENV_BRACKET_RE]) {
+      re.lastIndex = 0;
+      for (const m of source.matchAll(re)) addEnvKey(keys, m[1], f.file);
+    }
+
+    ENV_DESTRUCTURE_RE.lastIndex = 0;
+    for (const m of source.matchAll(ENV_DESTRUCTURE_RE)) {
+      for (const raw of m[1].split(",")) {
+        const key = raw.trim().split(/[:=]/)[0]?.trim();
+        if (/^[A-Z_][A-Z0-9_]*$/.test(key)) addEnvKey(keys, key, f.file);
+      }
+    }
+
+    ENV_DYNAMIC_RE.lastIndex = 0;
+    const dynamicCount = [...source.matchAll(ENV_DYNAMIC_RE)].length;
+    if (dynamicCount) dynamic.push({ file: f.file, count: dynamicCount });
+  }
+
+  return {
+    keys: [...keys.values()]
+      .map((v) => ({ key: v.key, count: v.count, files: [...v.files].sort() }))
+      .sort((a, b) => a.key.localeCompare(b.key)),
+    dynamic,
+    hasExampleFile: fs.existsSync(path.join(abs, ".env.example")),
+  };
+}
+
+function signalIssues(confidence) {
+  return Object.entries(confidence?.signals ?? {})
+    .filter(([, s]) => s.unavailable || s.value == null || s.value < 0.7)
+    .map(([name, s]) => ({
+      signal: name,
+      value: s.value ?? null,
+      unavailable: !!s.unavailable,
+      weight: s.weight,
+    }));
+}
+
+function collectWeakWorkflows(graph, threshold, top) {
+  return [...(graph.workflows ?? [])]
+    .filter((wf) => (wf.confidence?.score ?? 1) < threshold || signalIssues(wf.confidence).length)
+    .sort((a, b) => (a.confidence?.score ?? 1) - (b.confidence?.score ?? 1) || a.id.localeCompare(b.id))
+    .slice(0, top)
+    .map((wf) => ({
+      id: wf.id,
+      entry: wf.entry,
+      fileCount: wf.files.length,
+      score: wf.confidence?.score ?? null,
+      signalCoverage: wf.confidence?.signalCoverage ?? null,
+      weakSignals: signalIssues(wf.confidence),
+    }));
+}
+
+function collectCallExamples(graph, resolution, top) {
+  return (graph.callEdges ?? [])
+    .filter((e) => e.resolution === resolution)
+    .slice(0, top)
+    .map((e) => ({
+      from: e.from,
+      name: e.unresolvedName ?? e.dynamicReceiver ?? null,
+    }));
+}
+
+function buildRecommendations({ graph, weakWorkflows, runtimeScripts, env, unresolvedImports, unresolvedCalls, dynamicCalls, threshold }) {
+  const recs = [];
+  if ((graph.repoConfidence ?? 1) < threshold) {
+    recs.push("Raise repo confidence by adding tests or entry-point coverage for the weakest workflows first.");
+  }
+  if (weakWorkflows.some((wf) => wf.weakSignals.some((s) => s.signal === "testPresence"))) {
+    recs.push("Add tests near low-testPresence workflow files; Map'd cannot infer behavior that tests never exercise.");
+  }
+  if ((graph.stats?.callResolutionRate ?? 1) < 0.9 || unresolvedCalls.length || dynamicCalls.length) {
+    recs.push("For dynamic call paths, add integration tests or annotations around plugin/runtime dispatch so static findings stay properly caveated.");
+  }
+  if (unresolvedImports.length) {
+    recs.push("Fix unresolved imports or extend resolver configuration; broken aliases lower trust before any AI reasoning begins.");
+  }
+  if (runtimeScripts.some((s) => !s.mappedAsEntry)) {
+    recs.push("Make runtime scripts map-friendly by pointing them at explicit entry files, or add annotations for framework/runtime entry conventions.");
+  }
+  if (env.keys.length && !env.hasExampleFile) {
+    recs.push("Add a .env.example documenting required keys; Map'd reports env names only and never reads secret values.");
+  }
+  if (graph.unsupported?.length) {
+    recs.push("Add parser support or exclude/annotate unsupported languages so Map'd does not overstate its coverage.");
+  }
+  if (graph.stats?.heuristicFileCount) {
+    recs.push("Non-JS/TS files are mapped heuristically (regex-tier imports/functions, half confidence credit). " +
+      "Annotate real entry points with `mapd annotate add <pattern> entrypoint` so their workflows form, " +
+      "or set .mapdrc mapping.polyglot=false to exclude them from the map entirely.");
+  }
+  if (!recs.length) recs.push("No major understanding blockers detected by the deterministic diagnosis pass.");
+  return recs;
+}
+
+export function buildDiagnosis(rootDir, { top = 5 } = {}) {
+  const abs = path.resolve(rootDir);
+  const graph = buildScoredGraph(abs);
+  const pkg = loadPkg(abs);
+  const config = loadConfig(abs);
+  const threshold = config.mapping?.confidenceThreshold ?? 0.8;
+  const limit = Math.max(1, Number.parseInt(top, 10) || 5);
+
+  const weakWorkflows = collectWeakWorkflows(graph, threshold, limit);
+  const runtimeScripts = collectRuntimeScripts(pkg, graph);
+  const env = collectEnvReads(abs, graph);
+  const unresolvedImports = (graph.importEdges ?? []).filter((e) => e.unresolved).slice(0, limit);
+  const unresolvedCalls = collectCallExamples(graph, "unresolved", limit);
+  const dynamicCalls = collectCallExamples(graph, "dynamic", limit);
+
+  return {
+    root: abs,
+    generatedAt: new Date().toISOString(),
+    summary: {
+      fileCount: graph.stats.fileCount,
+      workflowCount: graph.workflows.length,
+      repoConfidence: graph.repoConfidence,
+      confidenceThreshold: threshold,
+      callResolutionRate: graph.stats.callResolutionRate,
+      importResolutionRate: graph.stats.importResolutionRate,
+      orphanCount: graph.orphans.length,
+      unsupportedLanguageFiles: graph.stats.unsupportedLanguageFiles,
+      heuristicFileCount: graph.stats.heuristicFileCount ?? 0,
+      unparsed: graph.stats.unparsed,
+    },
+    confidence: {
+      weakWorkflowCount: weakWorkflows.length,
+      weakWorkflows,
+    },
+    runtime: {
+      entryPoints: graph.entryPoints,
+      runtimeScripts,
+      unmappedRuntimeScripts: runtimeScripts.filter((s) => !s.mappedAsEntry),
+      dynamicCallCount: graph.stats.dynamicCalls,
+      dynamicCalls,
+      unresolvedCalls,
+      unresolvedImports,
+      dynamicallyLoadedFiles: graph.reachability?.dynamicallyLoaded ?? [],
+    },
+    env,
+    coverageGaps: {
+      orphans: graph.orphans.slice(0, limit),
+      generatedFiles: (graph.generatedFiles ?? []).slice(0, limit),
+      unsupported: (graph.unsupported ?? []).slice(0, limit),
+      heuristicUnverified: (graph.reachability?.heuristicUnverified ?? []).slice(0, limit),
+    },
+    recommendations: buildRecommendations({ graph, weakWorkflows, runtimeScripts, env, unresolvedImports, unresolvedCalls, dynamicCalls, threshold }),
+  };
+}
+
+function signalText(signals) {
+  if (!signals.length) return "no weak signals";
+  return signals.map((s) => `${s.signal}=${s.unavailable ? "unavailable" : s.value}`).join(", ");
+}
+
+export function renderDiagnosis(data) {
+  const lines = [];
+  lines.push(`Map'd diagnosis — ${data.root}`);
+  lines.push(`files: ${data.summary.fileCount}  workflows: ${data.summary.workflowCount}  confidence: ${data.summary.repoConfidence}  call resolution: ${(data.summary.callResolutionRate * 100).toFixed(1)}%`);
+  if (data.summary.heuristicFileCount) {
+    lines.push(`heuristic-parsed (non-JS/TS) files: ${data.summary.heuristicFileCount} — mapped with regex-tier extraction, half confidence credit; orphan claims about them are never asserted`);
+  }
+
+  lines.push("");
+  lines.push("Confidence blockers");
+  if (!data.confidence.weakWorkflows.length) {
+    lines.push("  none above the configured threshold");
+  } else {
+    for (const wf of data.confidence.weakWorkflows) {
+      lines.push(`  ${wf.id}  score ${wf.score}  (${wf.fileCount} files; ${signalText(wf.weakSignals)})`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Runtime blind spots");
+  if (!data.runtime.unmappedRuntimeScripts.length && !data.runtime.unresolvedCalls.length && !data.runtime.unresolvedImports.length && !data.runtime.dynamicCalls.length) {
+    lines.push("  no major runtime blind spots detected");
+  } else {
+    for (const s of data.runtime.unmappedRuntimeScripts) lines.push(`  unmapped script "${s.name}": ${s.command}`);
+    for (const e of data.runtime.unresolvedImports) lines.push(`  unresolved import from ${e.from}: ${e.unresolved}`);
+    for (const c of data.runtime.unresolvedCalls) lines.push(`  unresolved call from ${c.from}: ${c.name}`);
+    for (const c of data.runtime.dynamicCalls) lines.push(`  dynamic receiver from ${c.from}: ${c.name}`);
+  }
+
+  lines.push("");
+  lines.push("Env contract");
+  if (!data.env.keys.length && !data.env.dynamic.length) {
+    lines.push("  no process.env reads detected");
+  } else {
+    for (const key of data.env.keys) lines.push(`  ${key.key}  (${key.count} read${key.count === 1 ? "" : "s"} in ${key.files.join(", ")})`);
+    for (const item of data.env.dynamic) lines.push(`  dynamic process.env[...] read in ${item.file} (${item.count})`);
+    lines.push(`  .env.example: ${data.env.hasExampleFile ? "present" : "missing"}`);
+  }
+
+  lines.push("");
+  lines.push("Next actions");
+  for (const rec of data.recommendations) lines.push(`  - ${rec}`);
+  return lines.join("\n");
+}

package/src/core/docs.js

@@ -0,0 +1,140 @@
+/**
+ * docs.js — Renders MAP.md from the scored graph. Structure and numbers are
+ * fully deterministic; LLM narration (if available) is inserted into clearly
+ * marked sections so a reader can always tell derived fact from prose.
+ */
+
+import { narrateWorkflow, llmAvailable } from "../agents/llm.js";
+import { verifyGrounding, describeGrounding } from "./grounding.js";
+
+const bar = (score) => {
+  const n = Math.round(score * 10);
+  return "█".repeat(n) + "░".repeat(10 - n);
+};
+
+/* ---- Mermaid rendering: every node/edge below is a graph fact ---- */
+
+const mmId = (() => {
+  const seen = new Map();
+  return (label) => {
+    if (!seen.has(label)) seen.set(label, `n${seen.size}`);
+    return seen.get(label);
+  };
+})();
+const mmLabel = (f) => f.replace(/"/g, "'");
+
+const MERMAID_NODE_CAP = 30; // declared cap: beyond this a workflow gets a summary node, never a truncated-silently diagram
+
+function mermaidOverview(graph) {
+  const lines = ["```mermaid", "graph LR"];
+  for (const wf of graph.workflows) {
+    const e = mmId(`entry:${wf.id}`);
+    const w = mmId(wf.id);
+    lines.push(`  ${e}(["${mmLabel(wf.entry.kind)}: ${mmLabel(wf.entry.file)}"]) --> ${w}["${wf.files.length} files / ${wf.functionCount} fns<br/>confidence ${wf.confidence?.score ?? "?"}"]`);
+  }
+  if (graph.orphans.length) lines.push(`  ${mmId("orphans")}["orphans: ${graph.orphans.length} file(s)"]`);
+  lines.push("```");
+  return lines.join("\n");
+}
+
+function mermaidWorkflow(wf, graph) {
+  const inWf = new Set(wf.files);
+  const edges = graph.importEdges.filter((e) => e.to && inWf.has(e.from) && inWf.has(e.to));
+  const lines = ["```mermaid", "graph LR"];
+  if (wf.files.length > MERMAID_NODE_CAP) {
+    lines.push(`  ${mmId(wf.id + ":big")}["${wf.files.length} files — exceeds ${MERMAID_NODE_CAP}-node diagram cap; see file list below"]`);
+  } else {
+    for (const f of wf.files) lines.push(`  ${mmId(wf.id + f)}["${mmLabel(f)}"]`);
+    for (const e of edges) lines.push(`  ${mmId(wf.id + e.from)} --> ${mmId(wf.id + e.to)}`);
+    if (!edges.length && wf.files.length === 1) lines.push(`  %% single-file workflow, no internal import edges`);
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+
+export async function renderDocs(graph, { withNarration = true } = {}) {
+  const s = graph.stats;
+  const lines = [];
+  lines.push(`# Project Map`);
+  lines.push(``);
+  lines.push(`> Generated by Map'd on ${graph.generatedAt} — every number below is derived from AST analysis, not estimated.`);
+  lines.push(``);
+  lines.push(`**Repo confidence: ${graph.repoConfidence}** (size-weighted composite across workflows)`);
+  lines.push(``);
+  lines.push(`| Metric | Value |`);
+  lines.push(`|---|---|`);
+  lines.push(`| Files mapped | ${s.fileCount} (${s.totalLoc.toLocaleString()} LOC) |`);
+  lines.push(`| Parsed cleanly | ${s.parsedCleanly} |`);
+  lines.push(`| Parsed with recovery | ${s.parsedWithRecovery} |`);
+  lines.push(`| Unparsed | ${s.unparsed} |`);
+  lines.push(`| Unsupported-language files | ${s.unsupportedLanguageFiles} |`);
+  lines.push(`| Import resolution rate | ${(s.importResolutionRate * 100).toFixed(1)}% |`);
+  lines.push(`| Call resolution rate | ${(s.callResolutionRate * 100).toFixed(1)}% (${s.resolvedCalls}/${s.totalCalls}) |`);
+  lines.push(``);
+
+  lines.push(`## Topology`);
+  lines.push(``);
+  lines.push(mermaidOverview(graph));
+  lines.push(``);
+  lines.push(`## Workflows (${graph.workflows.length})`);
+  lines.push(``);
+
+  const narrate = withNarration && llmAvailable();
+
+  for (const wf of graph.workflows) {
+    const c = wf.confidence;
+    lines.push(`### \`${wf.id}\``);
+    lines.push(``);
+    lines.push(`- **Entry:** \`${wf.entry.file}\` (${wf.entry.kind}: ${wf.entry.detail})`);
+    lines.push(`- **Scope:** ${wf.files.length} files, ${wf.functionCount} functions`);
+    lines.push(`- **Confidence:** \`${bar(c.score)}\` **${c.score}** (signal coverage ${c.signalCoverage})`);
+    lines.push(``);
+    lines.push(`| Signal | Value | Weight |`);
+    lines.push(`|---|---|---|`);
+    for (const [k, sig] of Object.entries(c.signals)) {
+      lines.push(`| ${k} | ${sig.unavailable ? "unavailable" : sig.value} | ${sig.weight} |`);
+    }
+    lines.push(``);
+    lines.push(mermaidWorkflow(wf, graph));
+    lines.push(``);
+    lines.push(`**Files:** ${wf.files.map((f) => `\`${f}\``).join(", ")}`);
+    if (wf.exportedSurface.length) {
+      lines.push(``);
+      lines.push(`**Exported surface:** ${wf.exportedSurface.map((e) => `\`${e}\``).join(", ")}`);
+    }
+    if (narrate) {
+      const prose = await narrateWorkflow(wf, s);
+      if (prose) {
+        lines.push(``);
+        lines.push(`<!-- llm-narration: model-generated prose, structure above is ground truth -->`);
+        lines.push(prose.trim());
+        // same mechanical check chat answers get: unsupported claims are marked in the doc itself
+        const check = verifyGrounding(prose, { files: graph.files.map((f) => f.file), workflowIds: graph.workflows.map((w) => w.id), graph });
+        const { bad } = describeGrounding(check);
+        if (bad.length) {
+          lines.push(``);
+          lines.push(`> ⚠ Unverified by the map: ${bad.join("; ")}.`);
+        }
+      }
+    }
+    lines.push(``);
+  }
+
+  if (graph.orphans.length) {
+    lines.push(`## Orphaned files (${graph.orphans.length})`);
+    lines.push(``);
+    lines.push(`Not reachable from any detected entry point — candidates for dead code or missing entry-point detection:`);
+    lines.push(``);
+    for (const f of graph.orphans) lines.push(`- \`${f}\``);
+    lines.push(``);
+  }
+
+  if (graph.unsupported.length) {
+    lines.push(`## Unmapped (no parser adapter yet)`);
+    lines.push(``);
+    for (const f of graph.unsupported) lines.push(`- \`${f}\``);
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}

package/src/core/doctor.js

@@ -0,0 +1,134 @@
+/**
+ * doctor.js — `mapd doctor`: inspects the local environment and project
+ * state without mutating anything. Every check is real (actually reads
+ * files / runs git / validates config) — nothing here is a placeholder.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { loadConfig, validateConfig } from "../config/index.js";
+import { loadBaseline } from "./regression.js";
+import { loadPkg, detectPackageManager } from "./graph.js";
+import { getProvider } from "../agents/provider.js";
+import { describeModelChoice } from "../agents/modelResolver.js";
+import { checkEnvFiles } from "./envFiles.js";
+import { checkReportFreshness } from "./staleness.js";
+import { platformCommand } from "./proc.js";
+
+function hasGitRepo(rootDir) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: rootDir, stdio: ["ignore", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Real semver-major comparison against the package's stated engines.node — never assumed. */
+function checkNodeVersion(pkg) {
+  const required = pkg?.engines?.node ?? ">=20";
+  const requiredMajorMatch = /(\d+)/.exec(required);
+  const requiredMajor = requiredMajorMatch ? parseInt(requiredMajorMatch[1], 10) : 20;
+  const actualMajor = parseInt(process.versions.node.split(".")[0], 10);
+  const ok = actualMajor >= requiredMajor;
+  return { ok, detail: `${process.version} (project requires ${required})${ok ? "" : " — UPGRADE NODE, this will cause real failures"}` };
+}
+
+/** Is the detected (or default) package manager binary actually resolvable, not just assumed present? */
+function packageManagerAvailable(manager) {
+  try {
+    const pc = platformCommand(manager, ["--version"], { stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync(pc.file, pc.args, pc.options);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function checkMapdDirWritable(abs) {
+  const dir = path.join(abs, ".mapd");
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const probe = path.join(dir, ".doctor-write-test");
+    fs.writeFileSync(probe, "x");
+    fs.rmSync(probe, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function runDoctor(rootDir) {
+  const abs = path.resolve(rootDir);
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  const pkg = loadPkg(abs);
+
+  const nodeCheck = checkNodeVersion(pkg);
+  add("node-version", nodeCheck.ok, nodeCheck.detail);
+
+  const { manager, lockfile } = detectPackageManager(abs);
+  if (!lockfile) {
+    add("package-manager", true, "no lockfile detected (npm/yarn/pnpm/bun) — FIX-G2 will assume npm if you add package.json scripts");
+  } else {
+    const available = packageManagerAvailable(manager);
+    add("package-manager", available,
+      available ? `${manager} detected (${lockfile}) and resolvable on PATH` : `${manager} detected (${lockfile}) but NOT found on PATH — FIX-G2 script runs will fail`);
+  }
+
+  const config = loadConfig(abs);
+  const { ok: configOk, errors } = validateConfig(config);
+  add("config-valid", configOk, configOk ? "resolved configuration is valid" : errors.join("; "));
+
+  const provider = getProvider(config);
+  add("provider-configured", true, provider.available()
+    ? `${provider.name} provider available${provider.name === "anthropic" ? ` — model: ${describeModelChoice(config)}` : provider.model ? ` — model: ${provider.model}` : ""}`
+    : "none configured — deterministic mode only");
+
+  const { project: projectEnv, user: userEnv } = checkEnvFiles(abs);
+  const envParts = [];
+  envParts.push(projectEnv.present
+    ? `project .env: ${projectEnv.keys.length ? `defines ${projectEnv.keys.join(", ")}` : "present, no recognized provider keys"}`
+    : "no project .env");
+  envParts.push(userEnv.present
+    ? `~/.env: ${userEnv.keys.length ? `defines ${userEnv.keys.join(", ")}` : "present, no recognized provider keys"}`
+    : "no ~/.env");
+  add("env-file", true, !projectEnv.present && !userEnv.present
+    ? "no .env found (project or user-level) — optional; copy .env.example, or export variables directly"
+    : envParts.join("  |  "));
+
+  const mapdWritable = checkMapdDirWritable(abs);
+  add("mapd-dir-writable", mapdWritable, mapdWritable ? `${path.join(abs, ".mapd")} is writable` : "not writable — check permissions");
+
+  const cacheDir = path.join(abs, ".mapd", "cache");
+  add("cache-health", true, fs.existsSync(cacheDir) ? "cache directory present" : "not yet created (created on first `mapd watch` run)");
+
+  const baseline = loadBaseline(abs);
+  add(
+    "baseline-health",
+    !baseline || !baseline.schemaMismatch,
+    baseline
+      ? (baseline.schemaMismatch ? `schema mismatch — found v${baseline.schemaMismatch.found}, expected v${baseline.schemaMismatch.expected}; re-run \`mapd baseline\`` : "present and schema-current")
+      : "none — run `mapd baseline` to create one",
+  );
+
+  add("parser-availability", true, "Babel parser (JavaScript/TypeScript/JSX) available");
+
+  const freshness = checkReportFreshness(abs);
+  add("findings-freshness", !freshness.stale,
+    !freshness.checked ? "no check/modernize reports on disk yet"
+      : freshness.stale ? `STALE — the following report(s) predate a more recent source change: ${freshness.staleReports.join(", ")}; re-run \`mapd check\`/\`mapd modernize\``
+        : "reports are current with the working tree");
+
+  const scripts = pkg?.scripts ? Object.keys(pkg.scripts) : [];
+  add("project-scripts", true, scripts.length ? `detected: ${scripts.join(", ")}` : "no package.json scripts detected");
+
+  const gitAvailable = hasGitRepo(abs);
+  add("git-availability", true, gitAvailable ? "git repository detected — patch isolation will use worktrees" : "no git repository — patch isolation will use tmpdir copies (fully supported)");
+
+  add("mcp-readiness", true, "`mapd mcp` is available (stdio transport)");
+
+  return { ok: checks.every((c) => c.ok), checks };
+}