@dev-tren/mapd 0.21.0

package/src/core/grounding.js

@@ -0,0 +1,235 @@
+/**
+ * grounding.js — the single shared mechanism any LLM-touching surface in
+ * mapd uses to verify a model's output against the real data it was allowed
+ * to draw from. Extracted from solutions.js's narrateSolutions (the first
+ * place this pattern existed) so every new LLM surface routes through the
+ * same check instead of reinventing it — or, as chat's grounded Q&A did
+ * until now, not having a mechanical check at all, only a prompt asking the
+ * model to self-qualify.
+ *
+ * Intentionally mechanical, not another LLM call: regex-extract concrete
+ * claims (file paths, workflow IDs, finding IDs) from the text, check each
+ * against the real ground-truth sets the caller provides, and report
+ * exactly which claims verified and which didn't. Never a fuzzy judgment —
+ * a claim either matches something real or it's a violation.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { GLOBALS } from "./graph.js";
+
+// "Next.js", "Node.js"… are technology names, not file claims.
+const TECH_NAMES = /^(?:next|node|nuxt|vue|react|express|three|d3|chart|moment|ember|backbone|angular|nest|deno|bun|solid|svelte|electron|socket\.io|p5|pixi|ml5|tf|brain|anime|video|highlight|marked|mermaid|alpine|preact|lit|remix|gatsby|astro|vite|webpack)\.js$/i;
+function extractPathLikeTokens(text) {
+  return (text.match(/[\w./-]+\.(?:js|jsx|ts|tsx|mjs|cjs|json|md)\b/g) ?? []).filter((t) => !TECH_NAMES.test(t));
+}
+function extractWorkflowIds(text) {
+  return text.match(/wf:[\w:./-]+/g) ?? [];
+}
+// mapd's finding IDs are 8-hex-char content hashes (id8() in review.js).
+// Matched only as a bare 8-char hex token so normal prose hex-looking words
+// don't false-positive as often (still possible, but rare, and callers only
+// check this when they actually pass findingIds — see below).
+function extractFindingIds(text) {
+  return text.match(/\b[0-9a-f]{8}\b/g) ?? [];
+}
+function basenamesOf(files) {
+  return new Set(files.map((f) => f.split("/").pop()));
+}
+
+const METADATA_FILES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "tsconfig.json",
+  "jsconfig.json",
+  ".mapdrc",
+  "README.md",
+  "MAP.md",
+];
+
+/**
+ * Grounding needs "files this answer may cite", not only "source files Map'd
+ * parsed into the AST graph." package.json/tsconfig/README are real project
+ * data Map'd consumes or documents, even though they are not JS/TS FileNodes.
+ */
+export function buildGroundingFileList(rootDir, graph) {
+  const abs = path.resolve(rootDir);
+  const files = new Set((graph.files ?? []).map((f) => f.file));
+  for (const file of METADATA_FILES) {
+    if (fs.existsSync(path.join(abs, file))) files.add(file);
+  }
+  return [...files].sort();
+}
+
+/**
+ * `groundTruth`: { files?: string[], workflowIds?: string[], findingIds?: string[] }
+ * Only claim types with a corresponding ground-truth array get checked at
+ * all — omitting `findingIds` means finding-ID-shaped tokens are never
+ * flagged, so a caller can't be falsely told something is "grounded" for a
+ * claim type it never actually verified.
+ *
+ * Returns { grounded, violations: [{type, value}], checkedTypes }.
+ */
+export function verifyGrounding(text, groundTruth = {}) {
+  const violations = [];
+  const verified = [];
+  const checkedTypes = [];
+  let remaining = text;
+
+  if (groundTruth.workflowIds) {
+    checkedTypes.push("workflowIds");
+    const valid = new Set(groundTruth.workflowIds);
+    const found = extractWorkflowIds(remaining);
+    for (const w of found) {
+      if (valid.has(w)) verified.push({ type: "workflow", value: w });
+      else violations.push({ type: "workflowId", value: w });
+    }
+    // strip matched workflow IDs before file-token scanning so a workflow
+    // ID's own trailing filename-looking segment isn't double-counted as an
+    // unrelated bare file claim (a workflow ID often embeds an entry file).
+    remaining = found.reduce((t, w) => t.split(w).join(" "), remaining);
+  }
+
+  if (groundTruth.findingIds) {
+    checkedTypes.push("findingIds");
+    const valid = new Set(groundTruth.findingIds);
+    for (const id of extractFindingIds(remaining)) {
+      if (valid.has(id)) verified.push({ type: "finding", value: id });
+      else violations.push({ type: "findingId", value: id });
+    }
+  }
+
+  if (groundTruth.files) {
+    checkedTypes.push("files");
+    const validFiles = new Set(groundTruth.files);
+    const validBasenames = basenamesOf(groundTruth.files);
+    for (const p of extractPathLikeTokens(remaining)) {
+      if (!validFiles.has(p) && !validBasenames.has(p.split("/").pop())) violations.push({ type: "file", value: p });
+      else verified.push({ type: "file", value: p });
+    }
+  }
+
+  if (groundTruth.graph) {
+    checkedTypes.push("relations", "symbols");
+    const index = graphIndex(groundTruth.graph);
+    for (const claim of extractRelationClaims(text, index)) {
+      const ok = claim.verb === "calls" ? fileCalls(index, claim.file, claim.target) : fileImports(index, claim.file, claim.target);
+      const value = `${claim.file} ${claim.verb} ${claim.target}`;
+      if (ok) verified.push({ type: "relation", value });
+      else violations.push({ type: "relation", value, detail: `no ${claim.verb === "calls" ? "call to" : "import of"} ${claim.target} in ${claim.file}` });
+    }
+    for (const sym of extractSymbolClaims(text)) {
+      const head = sym.split(".")[0];
+      if (index.symbols.has(sym) || index.symbols.has(sym.split(".").pop()) || GLOBALS.has(head) || MAPD_TERMS.has(sym)) verified.push({ type: "symbol", value: sym });
+      else violations.push({ type: "symbol", value: sym, detail: "no function, export, or import by that name in the map" });
+    }
+  }
+
+  return { grounded: violations.length === 0, violations, verified, checkedTypes };
+}
+
+/** One-line human summary of a verifyGrounding result — what was checked, and what failed. */
+export function describeGrounding(check) {
+  const counts = {};
+  for (const v of check.verified ?? []) counts[v.type] = (counts[v.type] ?? 0) + 1;
+  const ok = Object.entries(counts).map(([t, n]) => `${n} ${t}${n > 1 ? "s" : ""}`).join(", ");
+  const bad = check.violations.map((v) => `${v.type} "${v.value}"${v.detail ? ` (${v.detail})` : ""}`);
+  return { ok, bad };
+}
+
+// ── claims about code: relations ("x.js calls `foo`") and symbols (`foo()`) ──
+
+const graphIndexCache = new WeakMap();
+function graphIndex(graph) {
+  let idx = graphIndexCache.get(graph);
+  if (idx) return idx;
+  const byFile = new Map((graph.files ?? []).map((f) => [f.file, f]));
+  const byBasename = new Map();
+  for (const f of byFile.keys()) {
+    const b = f.split("/").pop();
+    byBasename.set(b, byBasename.has(b) ? null : f); // null = ambiguous basename
+  }
+  const symbols = new Set();
+  for (const f of byFile.values()) {
+    for (const fn of f.functions ?? []) for (const part of String(fn.name).split(/\.|#/)) if (part && part !== "prototype") symbols.add(part);
+    for (const e of f.exports ?? []) symbols.add(e);
+    for (const imp of f.imports ?? []) { for (const n of imp.names ?? []) symbols.add(n); symbols.add(imp.source); }
+  }
+  idx = { byFile, byBasename, symbols };
+  graphIndexCache.set(graph, idx);
+  return idx;
+}
+
+function resolveFileClaim(index, token) {
+  if (index.byFile.has(token)) return token;
+  return index.byBasename.get(token.split("/").pop()) ?? null;
+}
+
+const lastSegment = (name) => String(name).replace(/\(\)$/, "").split(/\.|#/).pop();
+const stemOf = (file) => file.split("/").pop().replace(/\.[^.]+$/, "");
+
+function fileCalls(index, file, target) {
+  const want = lastSegment(target);
+  const node = index.byFile.get(file);
+  return (node?.functions ?? []).some((fn) => (fn.calls ?? []).some((c) => lastSegment(c) === want));
+}
+
+function fileImports(index, file, target) {
+  const node = index.byFile.get(file);
+  const want = lastSegment(target);
+  const targetStem = /\.[a-z]+$/i.test(target) ? stemOf(target) : null;
+  return (node?.imports ?? []).some((imp) =>
+    (imp.names ?? []).includes(want) || (targetStem && stemOf(imp.source ?? "") === targetStem) || imp.source === target);
+}
+
+// Third-person verb forms only: "call site", "import edge", "require()" are nouns, not claims.
+const VERBS = { calls: "calls", invokes: "calls", imports: "imports", requires: "imports" };
+// Map'd's own vocabulary shows up in answers about the map and is not a code symbol.
+const MAPD_TERMS = new Set([
+  "dynamicallyLoaded", "trulyOrphaned", "generatedArtifacts", "intentionalDormant", "heuristicUnverified",
+  "parseIntegrity", "resolutionRate", "testPresence", "stability", "coverageOfRepo", "signalCoverage",
+  "repoConfidence", "callResolutionRate", "importResolutionRate", "exportedSurface", "entryPoints",
+]);
+const NEGATION = /\b(?:not|never|no longer|doesn.?t|don.?t|isn.?t|without)\b/i;
+const TOKEN = "`?([\\w./-]+\\.(?:js|jsx|ts|tsx|mjs|cjs))`?";
+
+/**
+ * "`a.js` calls `foo`", "a.js imports b.js" → { file, verb, target }. Only
+ * sentences whose subject is a REAL mapped file are checkable; everything else
+ * is left alone rather than guessed at. Negated sentences are skipped.
+ */
+function extractRelationClaims(text, index) {
+  const claims = [];
+  const re = new RegExp(`${TOKEN}[^.\\n\`]{0,40}?\\b(calls|invokes|imports|requires)\\b[^.\\n\`]{0,40}?\`([\\w$./-]+?)(?:\\(\\))?\``, "g");
+  for (const sentence of text.split(/(?<=[.!?])\s+|\n+/)) {
+    if (NEGATION.test(sentence)) continue;
+    for (const m of sentence.matchAll(re)) {
+      const file = resolveFileClaim(index, m[1]);
+      if (!file) continue; // an unknown file is already reported by the file check
+      const verb = VERBS[m[2].toLowerCase()];
+      if (verb === "calls" && /\.(?:js|jsx|ts|tsx|mjs|cjs)$/.test(m[3])) continue; // a file is imported, not called
+      claims.push({ file, verb, target: m[3] });
+    }
+  }
+  return claims;
+}
+
+/**
+ * Backticked identifiers that are unmistakably code — called (`foo()`),
+ * camelCase/PascalCase, or dotted members — never plain words, flags,
+ * ALL_CAPS env vars, or file paths (files have their own check).
+ */
+function extractSymbolClaims(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)(\(\))?`/g)) {
+    const [, name, called] = m;
+    if (/^[A-Z0-9_]+$/.test(name)) continue;
+    if (/\.(?:js|jsx|ts|tsx|mjs|cjs|json|md)$/.test(name)) continue;
+    const codeShaped = called || name.includes(".") || /[a-z][A-Z]/.test(name) || /^[A-Z][a-z]+[A-Z]/.test(name);
+    if (codeShaped) out.add(name);
+  }
+  return [...out];
+}

package/src/core/handoff.js

@@ -0,0 +1,157 @@
+/**
+ * handoff.js — `mapd handoff`: package the highest-priority open findings
+ * into a structured prompt for an external coding agent (Claude Code, Codex)
+ * to execute. Mapd never edits code itself — chat is a project-understanding
+ * and verification layer, not a general agent (see chat/repl.js) — so this
+ * automates the manual step of turning findings into an agent-ready prompt,
+ * instead of a human hand-writing one from the review queue each time.
+ *
+ * Every section is built ONLY from real, already-computed data (the review
+ * queue, the workflow graph, the baseline diff) — never an invented file
+ * grouping, task description, or priority beyond what the underlying
+ * finding/scoring already produced.
+ */
+
+import path from "node:path";
+import { buildScoredGraph, detectStack } from "./intelligence.js";
+import { loadPkg } from "./graph.js";
+import { loadBaseline, diffGraphs } from "./regression.js";
+import { pending, loadQueue } from "./review.js";
+import { loadFinding } from "./fix.js";
+import { priorityOf, filesOf } from "./findingScoring.js";
+import { checkReportFreshness } from "./staleness.js";
+
+/**
+ * Top-N open (check + modernize) findings, ranked by severity/priority across
+ * both sources. Findings sourced from a STALE report (one that predates a
+ * more recent source change — see staleness.js) are excluded from the ranked
+ * list entirely, not just annotated: a banner next to a fully-formed action
+ * plan is easy to skip past, and acting on a stale finding means fixing
+ * something that may already be fixed. The exclusion itself is disclosed
+ * (count + which reports), never silent. `staleReports` is
+ * checkReportFreshness's `staleReports` (report basenames).
+ */
+export function collectTopFindings(rootDir, { top = 5, staleReports = [] } = {}) {
+  const abs = path.resolve(rootDir);
+  const staleSet = new Set(staleReports);
+  const items = pending(loadQueue(abs)).filter((i) => i.source === "check" || i.source.startsWith("modernize-"));
+  const fresh = items.filter((i) => !staleSet.has(path.basename(i.file)));
+  const excludedStaleCount = items.length - fresh.length;
+  const findings = fresh
+    .map((item) => {
+      const loaded = loadFinding(abs, item.id);
+      if (!loaded) return null;
+      return { item, finding: loaded.finding, priority: priorityOf(loaded.finding, item) };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.priority - a.priority)
+    .slice(0, top);
+  return { findings, excludedStaleCount };
+}
+
+/** Workflows newly added since the last baseline — files an external agent should treat as fragile. */
+function newWorkflowsSinceBaseline(rootDir, graph) {
+  const abs = path.resolve(rootDir);
+  const loaded = loadBaseline(abs);
+  if (!loaded || loaded.schemaMismatch) return [];
+  const diff = diffGraphs(loaded.graph, graph);
+  const ids = diff.filter((f) => f.kind === "workflow-added").map((f) => /^New workflow (\S+) detected/.exec(f.detail)?.[1]).filter(Boolean);
+  return graph.workflows.filter((w) => ids.includes(w.id)).map((w) => ({ id: w.id, entry: w.entry.file, fileCount: w.files.length }));
+}
+
+/** Builds the structured handoff data — pure data, no formatting decisions. */
+export function buildHandoff(rootDir, { top = 5 } = {}) {
+  const abs = path.resolve(rootDir);
+  const graph = buildScoredGraph(abs);
+  const pkg = loadPkg(abs);
+  const stack = detectStack(pkg, graph);
+  const freshness = checkReportFreshness(abs);
+  const { findings: topFindings, excludedStaleCount } = collectTopFindings(abs, { top, staleReports: freshness.staleReports });
+
+  return {
+    root: abs,
+    project: pkg?.name ?? path.basename(abs),
+    stack,
+    fileCount: graph.stats.fileCount,
+    workflowCount: graph.workflows.length,
+    repoConfidence: graph.repoConfidence,
+    callResolutionRate: graph.stats.callResolutionRate,
+    freshness,
+    excludedStaleCount,
+    newWorkflows: newWorkflowsSinceBaseline(abs, graph),
+    tasks: topFindings.map(({ item, finding, priority }, i) => ({
+      order: i + 1,
+      id: item.id,
+      source: item.source,
+      kind: finding.kind ?? finding.rule,
+      severity: finding.severity ?? null,
+      priority: Number(priority.toFixed(3)),
+      detail: finding.detail,
+      files: filesOf(finding),
+      suggestion: finding.suggestion ?? null,
+    })),
+  };
+}
+
+/** Renders `buildHandoff`'s data as a plain-text prompt, ready to paste into an external agent. */
+export function renderHandoffPrompt(data) {
+  const lines = [];
+  const stackLabel = [...data.stack.languages, ...data.stack.frameworks].join(" + ") || "JavaScript";
+
+  if (data.freshness?.stale && data.excludedStaleCount > 0) {
+    lines.push(`⚠ STALE REPORTS EXCLUDED: ${data.freshness.staleReports.join(", ")} predate a more recent source change. ` +
+      `${data.excludedStaleCount} finding(s) sourced from them were EXCLUDED from the tasks below (not just flagged) — ` +
+      "every task shown is backed by a report that is current with the working tree. " +
+      "Re-run `mapd check`/`mapd modernize` to refresh the stale report(s) and include their findings.");
+    lines.push("");
+  } else if (data.freshness?.stale) {
+    // stale report(s) exist but contributed no open findings — one quiet line,
+    // not a warning banner about zero exclusions
+    lines.push(`note: ${data.freshness.staleReports.join(", ")} predate a more recent source change but contributed no open findings; re-run \`mapd check\`/\`mapd modernize\` to refresh.`);
+    lines.push("");
+  }
+
+  lines.push("CONTEXT");
+  lines.push("=======");
+  lines.push(`${data.fileCount}-file ${stackLabel} project (${data.project}).`);
+  lines.push(`repo confidence: ${data.repoConfidence}  call resolution: ${(data.callResolutionRate * 100).toFixed(1)}%`);
+  if (data.tasks.length) {
+    lines.push(`Map'd identified ${data.tasks.length} priority finding(s) below, highest first. Work through them in order.`);
+    lines.push("Do not refactor beyond the stated scope for each task.");
+  }
+  lines.push("");
+
+  if (data.newWorkflows.length) {
+    lines.push("REGRESSION GUARD");
+    lines.push("================");
+    lines.push("These workflows were newly detected since the last baseline — treat their files as fragile;");
+    lines.push("preserve existing import/export surface unless a task below explicitly targets them.");
+    for (const wf of data.newWorkflows) lines.push(`  - ${wf.id}  (entry: ${wf.entry}, ${wf.fileCount} files)`);
+    lines.push("");
+  }
+
+  if (!data.tasks.length) {
+    lines.push(data.excludedStaleCount > 0
+      ? `All ${data.excludedStaleCount} open finding(s) come from stale report(s) — nothing current to hand off. Re-run \`mapd check\`/\`mapd modernize\` first.`
+      : "No open findings — nothing to hand off. Run `mapd check` / `mapd modernize` first.");
+    return lines.join("\n");
+  }
+
+  lines.push("━".repeat(70));
+  for (const task of data.tasks) {
+    const header = `TASK ${task.order} — ${String(task.kind).toUpperCase()}`;
+    lines.push("");
+    lines.push(header);
+    lines.push("=".repeat(header.length));
+    lines.push(`Finding ID: ${task.id}  |  source: ${task.source}  |  priority: ${task.priority}` +
+      (task.severity ? `  |  severity: ${task.severity}` : ""));
+    lines.push(`Problem: ${task.detail}`);
+    if (task.files.length) lines.push(`Files: ${task.files.join(", ")}`);
+    if (task.suggestion) lines.push(`Suggested direction: ${task.suggestion}`);
+    lines.push("After this task: run `mapd check` and re-verify no new regressions before moving to the next task.");
+  }
+  lines.push("");
+  lines.push("━".repeat(70));
+  lines.push(`EXECUTION ORDER: Task 1 → Task ${data.tasks.length}, in order. One commit per task. Do not batch.`);
+  return lines.join("\n");
+}

package/src/core/importResolver.js

@@ -0,0 +1,218 @@
+/**
+ * importResolver.js — resolves import specifiers the way the project's OWN
+ * toolchain resolves them, not just by relative-path guessing. Every alias
+ * mapd can't resolve becomes a false "unresolved edge" that depresses call
+ * resolution and inflates orphan candidates — so this attacks orphan/
+ * confidence accuracy at the root instead of adding downstream caveats.
+ *
+ * Sources of truth, all read from the project's real configuration:
+ *   - tsconfig.json / jsconfig.json  `compilerOptions.paths` + `baseUrl`
+ *     (root-level file only; `extends` chains are not followed — a miss
+ *     falls through to the old behavior, never a wrong resolution)
+ *   - package.json `imports`  (Node's `#`-prefixed subpath imports)
+ *   - package.json `exports`  (self-referencing imports of the package's
+ *     own name — Node resolves these through the exports map)
+ *   - TypeScript's node16/nodenext ESM convention: source says
+ *     `import "./x.js"` but the file on disk is `x.ts`/`x.tsx`
+ *
+ * DESIGN RULE (same as everywhere else): a candidate only resolves if the
+ * target file actually exists in the project's file set. An alias that
+ * matches but points at nothing stays "unresolved" — never fabricated.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Tolerates // and block comments plus trailing commas — tsconfig.json is
+ * JSONC in practice. Must be string-aware, not regex-based: tsconfig paths
+ * keys literally contain "/*" (e.g. "@/*"), which a naive block-comment
+ * regex would eat as a comment opener and corrupt the whole document.
+ */
+function stripJsonc(raw) {
+  let out = "";
+  let inString = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (inString) {
+      out += ch;
+      if (ch === "\\") { out += raw[++i] ?? ""; continue; } // escaped char, incl. \"
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; out += ch; continue; }
+    if (ch === "/" && raw[i + 1] === "/") { while (i < raw.length && raw[i] !== "\n") i++; out += "\n"; continue; }
+    if (ch === "/" && raw[i + 1] === "*") { i += 2; while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++; i++; continue; }
+    if (ch === "}" || ch === "]") { out = out.replace(/,\s*$/, ""); } // trailing comma, only ever outside strings here
+    out += ch;
+  }
+  return out;
+}
+
+function readJsonc(absPath) {
+  let raw;
+  try { raw = fs.readFileSync(absPath, "utf8"); } catch { return null; }
+  try {
+    return JSON.parse(stripJsonc(raw));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Loads `paths` aliases from tsconfig.json (preferred) or jsconfig.json.
+ * Returns [{ keyPrefix, keySuffix, targets: [{prefix, suffix}] }] where a
+ * single `*` wildcard splits key/target into prefix+suffix (TS allows at
+ * most one `*` per pattern); exact keys have keySuffix === null.
+ */
+export function loadPathAliases(rootDir) {
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    const config = readJsonc(path.join(rootDir, name));
+    const paths = config?.compilerOptions?.paths;
+    if (!paths || typeof paths !== "object") continue;
+    const baseUrl = config.compilerOptions.baseUrl ?? ".";
+    const aliases = [];
+    for (const [key, targets] of Object.entries(paths)) {
+      if (!Array.isArray(targets)) continue;
+      const starIdx = key.indexOf("*");
+      const entry = {
+        keyPrefix: starIdx === -1 ? key : key.slice(0, starIdx),
+        keySuffix: starIdx === -1 ? null : key.slice(starIdx + 1),
+        targets: targets
+          .filter((t) => typeof t === "string")
+          .map((t) => {
+            const tStar = t.indexOf("*");
+            const joined = (p) => path.posix.normalize(path.posix.join(baseUrl, p));
+            return tStar === -1
+              ? { prefix: joined(t), suffix: "" }
+              : { prefix: joined(t.slice(0, tStar)), suffix: t.slice(tStar + 1) };
+          }),
+      };
+      if (entry.targets.length) aliases.push(entry);
+    }
+    if (aliases.length) return aliases;
+  }
+  return [];
+}
+
+/** Unwraps a package.json imports/exports value: plain string, or a conditions object (first matching common condition). */
+function unwrapConditional(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    for (const cond of ["import", "require", "node", "default"]) {
+      if (typeof value[cond] === "string") return value[cond];
+      if (value[cond] && typeof value[cond] === "object") {
+        const nested = unwrapConditional(value[cond]);
+        if (nested) return nested;
+      }
+    }
+  }
+  return null;
+}
+
+/** Matches `spec` against a subpath map (package.json imports/exports): exact first, then single-`*` patterns. */
+function resolveSubpathMap(map, spec) {
+  if (!map || typeof map !== "object") return null;
+  if (map[spec] !== undefined) return unwrapConditional(map[spec]);
+  for (const [key, value] of Object.entries(map)) {
+    const starIdx = key.indexOf("*");
+    if (starIdx === -1) continue;
+    const prefix = key.slice(0, starIdx);
+    const suffix = key.slice(starIdx + 1);
+    if (spec.startsWith(prefix) && spec.endsWith(suffix) && spec.length >= prefix.length + suffix.length) {
+      const matched = spec.slice(prefix.length, spec.length - suffix.length || undefined);
+      const target = unwrapConditional(value);
+      return target ? target.replace("*", matched) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Creates the resolver used for every import edge in buildGraph.
+ * `resolve(fromFile, spec)` returns exactly the old resolveImport contract:
+ * `{internal}` | `{external}` | `{unresolved}`.
+ */
+export function createImportResolver(rootDir, fileSet, pkg) {
+  const aliases = loadPathAliases(rootDir);
+  const importsMap = pkg?.imports ?? null;
+  const exportsMap = pkg?.exports ?? null;
+  const pkgName = typeof pkg?.name === "string" ? pkg.name : null;
+
+  /** Existence-checked candidate expansion; includes the TS-ESM `.js` → `.ts` swap. */
+  function tryFile(basePosix) {
+    const base = path.posix.normalize(basePosix);
+    const candidates = [
+      base,
+      `${base}.js`, `${base}.ts`, `${base}.jsx`, `${base}.tsx`, `${base}.mjs`, `${base}.cjs`,
+      `${base}/index.js`, `${base}/index.ts`,
+    ];
+    // node16/nodenext TypeScript: the import says .js/.mjs/.cjs but the file
+    // on disk is the .ts flavor — the compiler rewrites at emit time.
+    const extSwap = { ".js": [".ts", ".tsx"], ".mjs": [".mts"], ".cjs": [".cts"] };
+    for (const [from, tos] of Object.entries(extSwap)) {
+      if (base.endsWith(from)) for (const to of tos) candidates.push(base.slice(0, -from.length) + to);
+    }
+    for (const c of candidates) {
+      const norm = path.posix.normalize(c);
+      if (fileSet.has(norm)) return norm;
+    }
+    return null;
+  }
+
+  function resolve(fromFile, spec) {
+    // 1. relative / absolute — the original behavior, plus the extension swap
+    if (spec.startsWith(".") || spec.startsWith("/")) {
+      const base = path.posix.join(path.posix.dirname(fromFile.split(path.sep).join("/")), spec);
+      const hit = tryFile(base);
+      return hit ? { internal: hit } : { unresolved: spec };
+    }
+
+    // 2. package.json "imports" — Node reserves the # prefix for these, so an
+    //    unmatched #-spec can never be an external package: honest unresolved.
+    if (spec.startsWith("#")) {
+      const target = importsMap ? resolveSubpathMap(importsMap, spec) : null;
+      if (target) {
+        const hit = tryFile(target.startsWith("./") ? target.slice(2) : target);
+        if (hit) return { internal: hit };
+      }
+      return { unresolved: spec };
+    }
+
+    // 3. tsconfig/jsconfig paths aliases
+    for (const alias of aliases) {
+      let remainder = null;
+      if (alias.keySuffix === null) {
+        if (spec === alias.keyPrefix) remainder = "";
+        else continue;
+      } else if (spec.startsWith(alias.keyPrefix) && spec.endsWith(alias.keySuffix)) {
+        remainder = spec.slice(alias.keyPrefix.length, spec.length - alias.keySuffix.length || undefined);
+      } else continue;
+      for (const t of alias.targets) {
+        const hit = tryFile(path.posix.join(t.prefix, remainder + t.suffix));
+        if (hit) return { internal: hit };
+      }
+      // alias matched but no target file exists — a real broken alias, not an
+      // external package; report it honestly rather than misclassifying.
+      return { unresolved: spec };
+    }
+
+    // 4. self-referencing import of the package's own name via "exports"
+    if (pkgName && (spec === pkgName || spec.startsWith(`${pkgName}/`))) {
+      const subpath = spec === pkgName ? "." : `./${spec.slice(pkgName.length + 1)}`;
+      const target = typeof exportsMap === "string" && subpath === "."
+        ? exportsMap
+        : resolveSubpathMap(exportsMap, subpath);
+      if (target) {
+        const hit = tryFile(target.startsWith("./") ? target.slice(2) : target);
+        if (hit) return { internal: hit };
+      }
+      // fall through: a package importing its own name with no matching
+      // export behaves like an external lookup at runtime too
+    }
+
+    return { external: spec };
+  }
+
+  return { resolve, aliasCount: aliases.length };
+}