@beignet/cli 0.0.40 → 0.0.42

package/src/explain.ts

@@ -0,0 +1,894 @@
+import {
+  type AppMapEdge,
+  type AppMapNode,
+  type AppMapNodeKind,
+  type AppMapNodeStatus,
+  type AppMapResult,
+  type AppMapSource,
+  mapApp,
+  projectAppMap,
+} from "./app-map.js";
+import { appMapNodeKinds } from "./app-map-schema.js";
+
+/** Targets supported by `beignet explain` and the MCP `explain` tool. */
+export const explainTargetKinds = [...appMapNodeKinds, "diagnostic"] as const;
+
+/** One supported explanation target kind. */
+export type ExplainTargetKind = (typeof explainTargetKinds)[number];
+
+/** Options for resolving one app concept into a deterministic explanation. */
+export type ExplainAppOptions = {
+  cwd?: string;
+  kind: ExplainTargetKind;
+  target: string;
+};
+
+/** Identity and source metadata for the resolved explanation target. */
+export type ExplainTarget = {
+  kind: ExplainTargetKind;
+  id: string;
+  name: string;
+  runtimeName?: string;
+  feature?: string;
+  source?: AppMapSource;
+  status?: AppMapNodeStatus;
+  details?: Record<string, unknown>;
+};
+
+/** Compact app-map node embedded in an explained relationship. */
+export type ExplainRelatedNode = {
+  id: string;
+  kind: AppMapNodeKind;
+  name: string;
+  runtimeName?: string;
+  feature?: string;
+  source: AppMapSource;
+  status?: AppMapNodeStatus;
+  details?: Record<string, unknown>;
+};
+
+/** One source-backed relationship connected to the explanation scope. */
+export type ExplainRelationship = {
+  kind: AppMapEdge["kind"];
+  from: ExplainRelatedNode;
+  to: ExplainRelatedNode;
+  evidence: AppMapEdge["evidence"];
+  details?: Record<string, unknown>;
+};
+
+/** Normalized doctor, lint, or app-map finding relevant to the target. */
+export type ExplainFinding = {
+  source: "doctor" | "lint" | "app-map";
+  severity: "error" | "warning" | "hint";
+  code: string;
+  message: string;
+  location?: AppMapSource;
+  details?: Record<string, unknown>;
+};
+
+/** Source location supporting one part of the explanation. */
+export type ExplainEvidence = {
+  source: AppMapSource;
+  reason: string;
+};
+
+/** Source file suggested for inspection, with the reasons it is relevant. */
+export type ExplainSuggestedFile = {
+  file: string;
+  line?: number;
+  column?: number;
+  reasons: string[];
+};
+
+/** Deterministic next action derived from the mapped target and findings. */
+export type ExplainSuggestedAction = {
+  kind: "inspect" | "address-finding" | "validate";
+  description: string;
+  command?: string;
+  cwd?: string;
+  file?: string;
+};
+
+/** Version 1 deterministic explanation of one app-map target. */
+export type ExplainAppResult = {
+  schemaVersion: 1;
+  targetDir: string;
+  app: AppMapResult["app"];
+  query: {
+    kind: ExplainTargetKind;
+    target: string;
+  };
+  target: ExplainTarget;
+  summary: string;
+  scope: {
+    nodes: number;
+    relationships: number;
+    returnedRelationships: number;
+    findings: number;
+    truncated: boolean;
+  };
+  evidence: ExplainEvidence[];
+  relationships: ExplainRelationship[];
+  conventions: string[];
+  findings: ExplainFinding[];
+  suggestedFiles: ExplainSuggestedFile[];
+  suggestedActions: ExplainSuggestedAction[];
+};
+
+type ExplanationScope = {
+  nodes: AppMapNode[];
+  edges: AppMapEdge[];
+  findings: ExplainFinding[];
+};
+
+/** Explain one source-backed Beignet app concept without generating advice. */
+export async function explainApp(
+  options: ExplainAppOptions,
+): Promise<ExplainAppResult> {
+  const targetText = options.target.trim();
+  if (!targetText) {
+    throw new Error(
+      `Pass a non-empty ${options.kind} target to beignet explain.`,
+    );
+  }
+
+  const appMap = await mapApp({ cwd: options.cwd, strict: true });
+  const scope =
+    options.kind === "diagnostic"
+      ? diagnosticScope(appMap, targetText)
+      : nodeScope(appMap, resolveTargetNode(appMap, options.kind, targetText));
+  const target =
+    options.kind === "diagnostic"
+      ? diagnosticTarget(targetText, scope.findings)
+      : nodeTarget(options.kind, scope.nodes[0]);
+  const selectedEdges = selectExplanationEdges(scope.edges, target.id);
+  const relationships = explainRelationships(scope.nodes, selectedEdges);
+  const evidenceNodes = scope.nodes.filter((node) => node.id === target.id);
+  const evidence = explainEvidence(
+    evidenceNodes,
+    relationships,
+    scope.findings,
+    target,
+  );
+  const suggestedFiles = suggestedFilesFromEvidence([
+    ...evidence,
+    ...relationshipNodeEvidence(relationships),
+  ]);
+
+  return {
+    schemaVersion: 1,
+    targetDir: appMap.targetDir,
+    app: appMap.app,
+    query: { kind: options.kind, target: targetText },
+    target,
+    summary: explainSummary(target, scope.nodes, scope.edges, scope.findings),
+    scope: {
+      nodes: scope.nodes.length,
+      relationships: scope.edges.length,
+      returnedRelationships: relationships.length,
+      findings: scope.findings.length,
+      truncated: relationships.length < scope.edges.length,
+    },
+    evidence,
+    relationships,
+    conventions: conventionsFor(options.kind),
+    findings: scope.findings,
+    suggestedFiles,
+    suggestedActions: suggestedActions(
+      target,
+      scope.findings,
+      appMap.targetDir,
+    ),
+  };
+}
+
+/** Format a concise, source-backed explanation for terminal use. */
+export function formatExplain(result: ExplainAppResult): string {
+  const relationshipLines = result.relationships.map(
+    (relationship) =>
+      `- ${relationship.from.id} --${relationship.kind}--> ${relationship.to.id} (${formatSource(relationship.evidence)})`,
+  );
+  const findingLines = result.findings.map(
+    (finding) =>
+      `- [${finding.source}/${finding.severity}] ${finding.code}: ${finding.message}${finding.location ? ` (${formatSource(finding.location)})` : ""}`,
+  );
+  const fileLines = result.suggestedFiles.map(
+    (file) => `- ${formatSource(file)} — ${file.reasons.join("; ")}`,
+  );
+  const actionLines = result.suggestedActions.map((action) => {
+    const details = [
+      ...(action.cwd ? [`  cwd: ${action.cwd}`] : []),
+      ...(action.command ? [`  ${action.command}`] : []),
+    ];
+    return `- ${action.description}${details.length > 0 ? `\n${details.join("\n")}` : ""}`;
+  });
+
+  return [
+    `Explain ${result.query.kind}: ${result.target.name}`,
+    `App root: ${result.targetDir}`,
+    `Target: ${result.target.id}${result.target.status ? ` (${result.target.status})` : ""}`,
+    result.target.source ? `Source: ${formatSource(result.target.source)}` : "",
+    `Summary: ${result.summary}`,
+    `Scope: ${result.scope.nodes} nodes, ${result.scope.returnedRelationships} of ${result.scope.relationships} relationships, ${result.scope.findings} findings${result.scope.truncated ? " (relationship list truncated)" : ""}`,
+    "",
+    "Conventions:",
+    ...result.conventions.map((convention) => `- ${convention}`),
+    "",
+    "Relationships:",
+    ...(relationshipLines.length > 0 ? relationshipLines : ["- None found."]),
+    "",
+    "Findings:",
+    ...(findingLines.length > 0 ? findingLines : ["- None found."]),
+    "",
+    "Suggested files:",
+    ...(fileLines.length > 0 ? fileLines : ["- None found."]),
+    "",
+    "Suggested actions:",
+    ...actionLines,
+  ]
+    .filter((line, index, lines) => line !== "" || lines[index - 1] !== "")
+    .join("\n");
+}
+
+function nodeScope(
+  appMap: AppMapResult,
+  targetNode: AppMapNode,
+): ExplanationScope {
+  if (targetNode.kind === "feature") {
+    const projection = projectAppMap(appMap, { feature: targetNode.name });
+    return {
+      nodes: moveTargetFirst(projection.nodes, targetNode.id),
+      edges: projection.edges,
+      findings: allFindings(projection),
+    };
+  }
+
+  const connectedEdges = appMap.edges.filter(
+    (edge) => edge.from === targetNode.id || edge.to === targetNode.id,
+  );
+  const connectedIds = new Set<string>([targetNode.id]);
+  for (const edge of connectedEdges) {
+    connectedIds.add(edge.from);
+    connectedIds.add(edge.to);
+  }
+  const nodes = moveTargetFirst(
+    appMap.nodes.filter((node) => connectedIds.has(node.id)),
+    targetNode.id,
+  );
+  const files = scopeFiles(nodes, connectedEdges);
+  const terms = targetTerms(targetNode);
+  const findings = allFindings(appMap).filter(
+    (finding) =>
+      (finding.location && files.has(finding.location.file)) ||
+      terms.some((term) => normalized(finding.message).includes(term)),
+  );
+
+  return { nodes, edges: connectedEdges, findings };
+}
+
+function diagnosticScope(
+  appMap: AppMapResult,
+  target: string,
+): ExplanationScope {
+  const code = normalized(target);
+  const findings = allFindings(appMap).filter(
+    (finding) => normalized(finding.code) === code,
+  );
+  if (findings.length === 0) {
+    const codes = [
+      ...new Set(allFindings(appMap).map((finding) => finding.code)),
+    ]
+      .sort()
+      .slice(0, 20);
+    throw new Error(
+      `Could not explain diagnostic "${target}". ${codes.length > 0 ? `Available diagnostic codes: ${codes.join(", ")}.` : "This app has no diagnostics."}`,
+    );
+  }
+
+  const seedIds = new Set(
+    appMap.nodes
+      .filter((node) =>
+        findings.some((finding) => findingMatchesNode(finding, node)),
+      )
+      .map((node) => node.id),
+  );
+  const connectedEdges = appMap.edges.filter(
+    (edge) => seedIds.has(edge.from) || seedIds.has(edge.to),
+  );
+  const connectedIds = new Set(seedIds);
+  for (const edge of connectedEdges) {
+    connectedIds.add(edge.from);
+    connectedIds.add(edge.to);
+  }
+
+  return {
+    nodes: appMap.nodes.filter((node) => connectedIds.has(node.id)),
+    edges: connectedEdges,
+    findings,
+  };
+}
+
+function resolveTargetNode(
+  appMap: AppMapResult,
+  kind: Exclude<ExplainTargetKind, "diagnostic">,
+  target: string,
+): AppMapNode {
+  const nodeKind: AppMapNodeKind = kind;
+  const candidates = appMap.nodes.filter((node) => node.kind === nodeKind);
+  const query = normalized(target);
+  const idMatches = candidates.filter((node) => normalized(node.id) === query);
+  if (idMatches.length === 1) return idMatches[0];
+
+  let matches = candidates.filter((node) =>
+    aliasesForNode(node).some(
+      (alias) => normalized(alias) === query && normalized(node.id) !== query,
+    ),
+  );
+
+  if (kind === "provider" && matches.length === 0) {
+    const portIds = new Set(
+      appMap.nodes
+        .filter(
+          (node) =>
+            node.kind === "port" &&
+            [node.id, node.name].some((alias) => normalized(alias) === query),
+        )
+        .map((node) => node.id),
+    );
+    matches = candidates.filter((node) =>
+      appMap.edges.some(
+        (edge) =>
+          edge.kind === "provides" &&
+          edge.from === node.id &&
+          portIds.has(edge.to),
+      ),
+    );
+    const packageProviders = matches.filter(
+      (node) => node.details?.sourceType !== "app-binding",
+    );
+    if (packageProviders.length > 0) matches = packageProviders;
+  }
+
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw new Error(
+      `The ${kind} target "${target}" is ambiguous. Matches: ${matches.map((node) => node.id).join(", ")}.`,
+    );
+  }
+
+  const available = [...new Set(candidates.map(canonicalNodeSelector))]
+    .sort()
+    .slice(0, 20);
+  throw new Error(
+    `Could not explain ${kind} "${target}". ${available.length > 0 ? `Available ${kind} targets: ${available.join(", ")}.` : `This app has no mapped ${kind} targets.`}`,
+  );
+}
+
+function canonicalNodeSelector(node: AppMapNode): string {
+  return node.runtimeName ?? node.name;
+}
+
+function aliasesForNode(node: AppMapNode): string[] {
+  const aliases = [node.id, node.name, node.source.file];
+  if (node.runtimeName) aliases.push(node.runtimeName);
+  if (node.source.exportName) {
+    aliases.push(
+      node.source.exportName,
+      `${node.source.file}#${node.source.exportName}`,
+    );
+  }
+  if (node.id.includes("#"))
+    aliases.push(node.id.slice(node.id.lastIndexOf("#") + 1));
+  if (node.kind === "route" && typeof node.details?.path === "string") {
+    aliases.push(node.details.path);
+  }
+  if (node.kind === "provider") {
+    aliases.push(node.name.replace(/^@beignet\//, ""));
+    if (typeof node.details?.displayName === "string") {
+      aliases.push(node.details.displayName);
+    }
+  }
+  return aliases;
+}
+
+function targetTerms(node: AppMapNode): string[] {
+  return aliasesForNode(node)
+    .map(normalized)
+    .filter((term) => term.length >= 4);
+}
+
+function diagnosticTarget(
+  query: string,
+  findings: ExplainFinding[],
+): ExplainTarget {
+  const code = findings[0]?.code ?? query;
+  return {
+    kind: "diagnostic",
+    id: `diagnostic:${code}`,
+    name: code,
+    ...(findings[0]?.location ? { source: findings[0].location } : {}),
+    details: {
+      matches: findings.length,
+      sources: [...new Set(findings.map((finding) => finding.source))].sort(),
+    },
+  };
+}
+
+function nodeTarget(
+  kind: Exclude<ExplainTargetKind, "diagnostic">,
+  node: AppMapNode | undefined,
+): ExplainTarget {
+  if (!node)
+    throw new Error(`Could not resolve the ${kind} explanation target.`);
+  return {
+    kind,
+    id: node.id,
+    name: node.name,
+    ...(node.runtimeName ? { runtimeName: node.runtimeName } : {}),
+    ...(node.feature ? { feature: node.feature } : {}),
+    source: node.source,
+    ...(node.status ? { status: node.status } : {}),
+    ...(node.details ? { details: node.details } : {}),
+  };
+}
+
+function explainRelationships(
+  nodes: AppMapNode[],
+  edges: AppMapEdge[],
+): ExplainRelationship[] {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  return edges.flatMap((edge) => {
+    const from = byId.get(edge.from);
+    const to = byId.get(edge.to);
+    if (!from || !to) return [];
+    return [
+      {
+        kind: edge.kind,
+        from: relatedNode(from),
+        to: relatedNode(to),
+        evidence: edge.evidence,
+        ...(edge.details ? { details: edge.details } : {}),
+      },
+    ];
+  });
+}
+
+function selectExplanationEdges(
+  edges: AppMapEdge[],
+  targetId: string,
+): AppMapEdge[] {
+  const maximumRelationships = 80;
+  if (edges.length <= maximumRelationships) return edges;
+
+  return [...edges]
+    .sort((left, right) => {
+      const priority =
+        edgePriority(left, targetId) - edgePriority(right, targetId);
+      if (priority !== 0) return priority;
+      return `${left.kind}:${left.from}:${left.to}`.localeCompare(
+        `${right.kind}:${right.from}:${right.to}`,
+      );
+    })
+    .slice(0, maximumRelationships);
+}
+
+function edgePriority(edge: AppMapEdge, targetId: string): number {
+  if (edge.kind === "depends-on") return 0;
+  if (edge.kind === "executes" || edge.kind === "binds") return 1;
+  if (
+    [
+      "authorizes",
+      "dispatches",
+      "emits",
+      "listens-to",
+      "publishes",
+      "sends",
+    ].includes(edge.kind)
+  ) {
+    return 2;
+  }
+  if (edge.from === targetId || edge.to === targetId) return 3;
+  return 4;
+}
+
+function relationshipNodeEvidence(
+  relationships: ExplainRelationship[],
+): ExplainEvidence[] {
+  const evidence: ExplainEvidence[] = [];
+  for (const relationship of relationships) {
+    evidence.push({
+      source: relationship.from.source,
+      reason: `related ${relationship.from.kind} ${relationship.from.id}`,
+    });
+    evidence.push({
+      source: relationship.to.source,
+      reason: `related ${relationship.to.kind} ${relationship.to.id}`,
+    });
+  }
+  return evidence;
+}
+
+function relatedNode(node: AppMapNode): ExplainRelatedNode {
+  return {
+    id: node.id,
+    kind: node.kind,
+    name: node.name,
+    ...(node.runtimeName ? { runtimeName: node.runtimeName } : {}),
+    ...(node.feature ? { feature: node.feature } : {}),
+    source: node.source,
+    ...(node.status ? { status: node.status } : {}),
+    ...(node.details ? { details: node.details } : {}),
+  };
+}
+
+function allFindings(appMap: AppMapResult): ExplainFinding[] {
+  return [
+    ...appMap.diagnostics.doctor.map(
+      (diagnostic): ExplainFinding => ({
+        source: "doctor",
+        severity: diagnostic.severity,
+        code: diagnostic.code,
+        message: diagnostic.message,
+        ...(diagnostic.file
+          ? {
+              location: {
+                file: diagnostic.file,
+                ...(diagnostic.contract
+                  ? { exportName: diagnostic.contract }
+                  : {}),
+              },
+            }
+          : {}),
+      }),
+    ),
+    ...appMap.diagnostics.lint.map(
+      (diagnostic): ExplainFinding => ({
+        source: "lint",
+        severity: diagnostic.severity,
+        code: diagnostic.code,
+        message: diagnostic.message,
+        location: {
+          file: diagnostic.file,
+          ...(diagnostic.line ? { line: diagnostic.line } : {}),
+          ...(diagnostic.column ? { column: diagnostic.column } : {}),
+        },
+        details: { importPath: diagnostic.importPath },
+      }),
+    ),
+    ...appMap.unresolved.map(
+      (unresolved): ExplainFinding => ({
+        source: "app-map",
+        severity: "warning",
+        code: unresolved.code,
+        message: unresolved.message,
+        location: unresolved.source,
+      }),
+    ),
+  ].sort(compareFindings);
+}
+
+function findingMatchesNode(
+  finding: ExplainFinding,
+  node: AppMapNode,
+): boolean {
+  if (finding.location?.file === node.source.file) return true;
+  if (
+    finding.location?.exportName &&
+    finding.location.exportName === node.source.exportName
+  ) {
+    return true;
+  }
+  const message = normalized(finding.message);
+  if (
+    /\.(ts|tsx|mts|cts|json)$/.test(node.source.file) &&
+    message.includes(normalized(node.source.file))
+  ) {
+    return true;
+  }
+  return [node.runtimeName, node.source.exportName]
+    .filter((term): term is string => Boolean(term && term.length >= 4))
+    .some((term) => message.includes(normalized(term)));
+}
+
+function explainEvidence(
+  nodes: AppMapNode[],
+  relationships: ExplainRelationship[],
+  findings: ExplainFinding[],
+  target: ExplainTarget,
+): ExplainEvidence[] {
+  const evidence: ExplainEvidence[] = [];
+  for (const node of nodes) {
+    evidence.push({
+      source: node.source,
+      reason: `${node.kind} ${node.id}`,
+    });
+  }
+  for (const relationship of relationships) {
+    evidence.push({
+      source: relationship.evidence,
+      reason: `${relationship.from.id} ${relationship.kind} ${relationship.to.id}`,
+    });
+  }
+  for (const finding of findings) {
+    if (finding.location) {
+      evidence.push({
+        source: finding.location,
+        reason: `${finding.source} finding ${finding.code}`,
+      });
+    }
+  }
+  for (const source of providerRegistrationSources(target)) {
+    evidence.push({
+      source,
+      reason: `provider registration ${target.id}`,
+    });
+  }
+
+  const seen = new Set<string>();
+  return evidence.filter((item) => {
+    const key = `${sourceKey(item.source)}:${item.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function suggestedFilesFromEvidence(
+  evidence: ExplainEvidence[],
+): ExplainSuggestedFile[] {
+  const files = new Map<string, ExplainSuggestedFile>();
+  for (const item of evidence) {
+    const key = item.source.file;
+    const existing = files.get(key);
+    if (existing) {
+      if (
+        existing.line !== item.source.line ||
+        existing.column !== item.source.column
+      ) {
+        delete existing.line;
+        delete existing.column;
+      }
+      if (!existing.reasons.includes(item.reason)) {
+        existing.reasons.push(item.reason);
+      }
+      continue;
+    }
+    files.set(key, {
+      file: item.source.file,
+      ...(item.source.line ? { line: item.source.line } : {}),
+      ...(item.source.column ? { column: item.source.column } : {}),
+      reasons: [item.reason],
+    });
+  }
+  return [...files.values()];
+}
+
+function suggestedActions(
+  target: ExplainTarget,
+  findings: ExplainFinding[],
+  targetDir: string,
+): ExplainSuggestedAction[] {
+  const inspectCommand = inspectCommandForTarget(target, findings);
+  const actions: ExplainSuggestedAction[] = [
+    {
+      kind: "inspect",
+      description: `Inspect the source-backed ${target.kind} context.`,
+      command: inspectCommand,
+      cwd: targetDir,
+    },
+  ];
+  for (const finding of findings) {
+    actions.push({
+      kind: "address-finding",
+      description: `${finding.code}: ${finding.message}`,
+      ...(finding.location ? { file: finding.location.file } : {}),
+    });
+  }
+  actions.push({
+    kind: "validate",
+    description: "Run the complete validation loop after making changes.",
+    command: "beignet check",
+    cwd: targetDir,
+  });
+  return actions;
+}
+
+function inspectCommandForTarget(
+  target: ExplainTarget,
+  findings: ExplainFinding[],
+): string {
+  if (target.kind === "feature") {
+    return `beignet map --feature ${target.name} --json`;
+  }
+  if (
+    target.kind === "contract" ||
+    target.kind === "route" ||
+    target.kind === "route-group" ||
+    target.kind === "openapi"
+  ) {
+    return "beignet routes --json";
+  }
+  if (target.kind === "port" || target.kind === "provider") {
+    return "beignet provider audit --json";
+  }
+  if (target.kind === "diagnostic") {
+    return findings.every((finding) => finding.source === "lint")
+      ? "beignet lint --json"
+      : "beignet doctor --strict --json";
+  }
+  if (target.feature) {
+    return `beignet map --feature ${target.feature} --json`;
+  }
+  return `beignet map --kind ${target.kind} --json`;
+}
+
+function providerRegistrationSources(target: ExplainTarget): AppMapSource[] {
+  if (target.kind !== "provider") return [];
+  const sources = target.details?.registrationSources;
+  if (!Array.isArray(sources)) return [];
+  return sources.filter(isAppMapSource);
+}
+
+function isAppMapSource(value: unknown): value is AppMapSource {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "file" in value &&
+    typeof value.file === "string"
+  );
+}
+
+function explainSummary(
+  target: ExplainTarget,
+  nodes: AppMapNode[],
+  edges: AppMapEdge[],
+  findings: ExplainFinding[],
+): string {
+  const fileCount = new Set([
+    ...nodes.map((node) => node.source.file),
+    ...findings.flatMap((finding) =>
+      finding.location ? [finding.location.file] : [],
+    ),
+  ]).size;
+  if (target.kind === "diagnostic") {
+    return `${target.name} has ${countLabel(findings.length, "finding")} across ${countLabel(fileCount, "mapped source")}.`;
+  }
+  return `${target.name} is ${target.status ?? "mapped"} with ${countLabel(edges.length, "relationship")}, ${countLabel(fileCount, "source")}, and ${countLabel(findings.length, "relevant finding")}.`;
+}
+
+const conventionsByTargetKind = {
+  feature: [
+    "Feature-owned contracts, use cases, policies, ports, workflows, clients, components, and tests stay under features/<feature>/.",
+    "Feature route groups and workflow artifacts register through the central server entrypoints.",
+  ],
+  contract: [
+    "Contracts own HTTP method, path, schemas, responses, metadata, and route errors.",
+    "Contracts stay transport-focused and bind to application behavior through feature routes.",
+  ],
+  route: [
+    "Routes bind contracts to use cases and policies without importing concrete infrastructure.",
+    "Feature route groups compose centrally in server/routes.ts and runtime route adapters stay thin.",
+  ],
+  "route-group": [
+    "Feature route groups are declared in features/<feature>/routes.ts and composed centrally in server/routes.ts.",
+    "Route groups bind contracts to use cases while preserving the app's dependency direction.",
+  ],
+  "use-case": [
+    "Use cases own validated application workflows and may depend on ports, policies, and domain code, not concrete infrastructure or UI.",
+    "Use cases remain callable outside HTTP so routes, tasks, jobs, and agent capabilities can reuse the same behavior.",
+  ],
+  policy: [
+    "Feature policies own business authorization for resources owned by that feature.",
+    "Authorization remains enforced in application workflows even when contract metadata also declares an ability.",
+  ],
+  ability: [
+    "An ability belongs to the policy of the feature that owns the resource being authorized.",
+    "Contracts may name authorization abilities, while policies and use cases enforce the business rule.",
+  ],
+  event: [
+    "Events represent facts that happened and belong to the feature that owns the fact.",
+    "Durable event publication registers through the app's workflow and outbox boundaries.",
+  ],
+  listener: [
+    "Listeners react to registered events and delegate application work through ports, jobs, notifications, or use cases.",
+    "Feature listeners register through the central listener registry used by runtime wiring and integrity checks.",
+  ],
+  job: [
+    "Jobs represent background work and remain explicit at provider-backed execution boundaries.",
+    "Feature jobs register through central runtime or outbox registries before workers can dispatch them.",
+  ],
+  schedule: [
+    "Schedules represent time-based triggers and delegate work to application workflows.",
+    "Feature schedules register centrally so runtime wiring, doctor, and beignet schedule run inspect the same surface.",
+  ],
+  task: [
+    "Tasks are explicit operational entrypoints for maintenance, backfills, and other bounded application work.",
+    "Feature tasks register centrally so beignet task run and runtime integrity checks use the same definitions.",
+  ],
+  notification: [
+    "Notifications represent user-facing communication intent, separate from provider-specific delivery.",
+    "Queued notification definitions register with the central notification and job runtime.",
+  ],
+  upload: [
+    "Uploads define feature-owned validation and storage workflows while storage remains behind an app port.",
+    "Upload route adapters stay thin and reuse the registered feature upload definition.",
+  ],
+  "agent-capability": [
+    "Agent capabilities expose curated, validated inputs and outputs by adapting existing application use cases.",
+    "Delegated context and authorization resolve centrally before an agent capability executes.",
+  ],
+  registry: [
+    "Registries explicitly compose feature declarations into the runtime surface inspected by doctor and app-map.",
+    "Central registries remain the source of truth for runtime wiring and integrity checks.",
+  ],
+  port: [
+    "Ports define app-facing dependency interfaces; infrastructure adapters provide their concrete implementations.",
+    "App ports wire through infra/port-wiring.ts and remain available to use cases through application context.",
+  ],
+  provider: [
+    "Ports define app-facing interfaces, providers adapt external systems, and app infrastructure wires them together.",
+    "Lifecycle providers register in server/providers.ts and provider-backed app ports wire through infra/port-wiring.ts.",
+  ],
+  table: [
+    "Database tables remain infrastructure-owned persistence details rather than domain or use-case dependencies.",
+    "Configured schema sources and migrations must describe the same deployed database surface.",
+  ],
+  openapi: [
+    "OpenAPI documents derive from the same registered contract surface served by the application.",
+    "Documented methods, paths, schemas, errors, and operation IDs stay aligned with their contracts.",
+  ],
+  entrypoint: [
+    "Runtime entrypoints compose the server or expose thin framework adapters over registered routes.",
+    "Entrypoints reuse central context, routes, providers, and workflow registries instead of duplicating application behavior.",
+  ],
+  test: [
+    "Feature behavior tests stay under features/<feature>/tests and exercise use cases, routes, policies, workflows, and UI.",
+    "Infrastructure and server integration tests may remain adjacent to the modules they exercise.",
+  ],
+  diagnostic: [
+    "Doctor findings describe framework convention drift; lint findings describe dependency-direction violations.",
+    "Fix the app structure or wiring named by the finding, then run the complete validation loop.",
+  ],
+} as const satisfies Record<ExplainTargetKind, readonly string[]>;
+
+function conventionsFor(kind: ExplainTargetKind): string[] {
+  return [...conventionsByTargetKind[kind]];
+}
+
+function scopeFiles(nodes: AppMapNode[], edges: AppMapEdge[]): Set<string> {
+  return new Set([
+    ...nodes.map((node) => node.source.file),
+    ...edges.map((edge) => edge.evidence.file),
+  ]);
+}
+
+function moveTargetFirst(nodes: AppMapNode[], id: string): AppMapNode[] {
+  const target = nodes.find((node) => node.id === id);
+  return target ? [target, ...nodes.filter((node) => node.id !== id)] : nodes;
+}
+
+function compareFindings(left: ExplainFinding, right: ExplainFinding): number {
+  return `${left.code}:${left.location?.file ?? ""}:${left.location?.line ?? 0}:${left.message}`.localeCompare(
+    `${right.code}:${right.location?.file ?? ""}:${right.location?.line ?? 0}:${right.message}`,
+  );
+}
+
+function sourceKey(source: AppMapSource): string {
+  return `${source.file}:${source.line ?? 0}:${source.column ?? 0}:${source.exportName ?? ""}`;
+}
+
+function formatSource(source: {
+  file: string;
+  line?: number;
+  column?: number;
+}): string {
+  return `${source.file}${source.line ? `:${source.line}${source.column ? `:${source.column}` : ""}` : ""}`;
+}
+
+function normalized(value: string): string {
+  return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function countLabel(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}