dsh-composition-doctor 0.2.2 → 0.4.0

package/dist/client.js

@@ -37,6 +37,39 @@ window.__ModuleLoader__.load({
 		// src/client/report-view.ts
 		var import_react = require("react");
 		
+		// src/reports/failure.ts
+		function renderFailure(result, markdown = false) {
+		  const lines = [
+		    markdown ? "# DSH Composition Doctor \u2014 Failure Explanation" : "DSH Composition Doctor \u2014 Failure Explanation",
+		    "",
+		    `Profile: ${result.profile}; runtime: ${result.runtime}`,
+		    ""
+		  ];
+		  if (result.explanations.length === 0) lines.push(result.outcome === "no-match" ? "No supported failure signature matched. Cause: unknown." : result.outcome === "unknown" ? "Selected metadata could not be fully inspected. Cause: unknown." : "No supported composition issue was observed. Runtime health: unknown.", "");
+		  for (const item of result.explanations.slice(0, markdown ? 50 : 3)) {
+		    lines.push(
+		      `${markdown ? "## " : ""}${item.detectedFailure}`,
+		      `${item.origin}; evidence: ${item.evidenceLevel}`,
+		      "",
+		      `Cause: ${item.observableCause}`,
+		      ""
+		    );
+		    for (const [index, path] of item.provenancePaths.entries()) {
+		      lines.push(
+		        `Path ${index + 1}: ${path.packageName === void 0 ? "" : `bundle ${path.packageName} \u2192 `}${path.source}`,
+		        `  ${path.layer === void 0 ? "layer: unknown" : `layer: ${path.layer}`}${path.rowId === void 0 ? "" : ` \u2192 row: ${path.rowId}`}`
+		      );
+		      if (path.provenance.length > (markdown ? 0 : 1)) lines.push(`  provenance: ${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(" \u2192 ")}`);
+		    }
+		    const unknown = markdown ? item.unknowns.join(" ") : `runtime not observed / not-run${item.evidenceLevel === "static" ? "; final composition unknown" : ""}${item.causeStatus === "unknown" ? "; cause unproven" : ""}.`;
+		    lines.push("", `Unknown: ${unknown}`, `Next: ${item.manualRemediation}`, "");
+		  }
+		  if (!markdown && result.explanations.length > 3) lines.push(`${result.explanations.length - 3} more explanation(s); use --format json or markdown.`, "");
+		  if (markdown || result.explanations.length === 0 || result.input.log === "not-provided") lines.push(result.nextStep);
+		  lines.push("Doctor did not modify your profile.", "");
+		  return lines.join("\n");
+		}
+		
 		// src/reports/markdown.ts
 		function formatEvidence(item) {
 		  const subject = item.subject === void 0 ? "" : ` \u2014 ${item.subject}`;
@@ -56,7 +89,9 @@ window.__ModuleLoader__.load({
 		}
 		function renderMarkdown(report) {
 		  const summary = ["error", "warning", "info"].map((severity) => `${severity}: ${report.diagnostics.filter((item) => item.severity === severity).length}`).join(", ");
-		  const body = report.diagnostics.length === 0 ? "No diagnostics were produced." : report.diagnostics.map(formatDiagnostic).join("\n\n");
+		  const diagnosticBody = report.diagnostics.length === 0 ? "No diagnostics were produced." : report.diagnostics.map(formatDiagnostic).join("\n\n");
+		  const body = report.failureExplanation === void 0 ? diagnosticBody : `${renderFailure(report.failureExplanation, true)}
+		${diagnosticBody}`;
 		  const coverage = report.metadataCoverage === void 0 ? "" : `
 		Metadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join("; ")}
 		`;
@@ -106,7 +141,48 @@ window.__ModuleLoader__.load({
 		function toReportViewModel(report) {
 		  const counts = { info: 0, warning: 0, error: 0 };
 		  for (const diagnostic of report.diagnostics) counts[diagnostic.severity] += 1;
-		  return { report, counts, graph: buildConflictGraph(report) };
+		  return {
+		    report,
+		    counts,
+		    graph: buildConflictGraph(report),
+		    compositionGraph: { nodes: report.compositionFacts?.nodes ?? [], edges: report.compositionFacts?.edges ?? [] }
+		  };
+		}
+		function compositionNodeDetail(report, nodeId) {
+		  const facts = report.compositionFacts;
+		  const node = facts?.nodes.find((candidate) => candidate.id === nodeId);
+		  if (facts === void 0 || node === void 0) return void 0;
+		  const relatedRows = facts.rows.filter((candidate) => {
+		    if (node.rowKey !== void 0) return candidate.key === node.rowKey;
+		    if (node.entity === "bundle") return candidate.packageName === node.packageName || candidate.provenance.some((step) => step.source === node.label);
+		    if (node.entity === "source") return candidate.source === node.source || candidate.provenance.some((step) => step.source === node.source);
+		    if (node.entity === "layer") return candidate.layer === node.layer && (node.layerOrder === void 0 || candidate.layerOrder === node.layerOrder);
+		    if (node.entity === "diagnostic") return node.diagnosticId !== void 0 && candidate.relatedDiagnosticIds.includes(node.diagnosticId);
+		    return false;
+		  });
+		  const fields = [
+		    { label: "entity", value: node.entity },
+		    { label: "source", value: node.source ?? node.label },
+		    { label: "evidence", value: node.evidenceMode ?? "unknown" }
+		  ];
+		  if (node.layer !== void 0) fields.push({ label: "layer", value: node.layer });
+		  if (node.layerOrder !== void 0) fields.push({ label: "layer order", value: String(node.layerOrder) });
+		  if (node.packageName !== void 0) fields.push({ label: "package", value: `${node.packageName}${node.packageVersion === void 0 ? "" : `@${node.packageVersion}`}` });
+		  if (relatedRows.length > 0) {
+		    fields.push({ label: "related rows", value: relatedRows.map((row) => row.id ?? row.name ?? row.key).join(", ") });
+		    fields.push({ label: "config keys", value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.configKeys.length === 0 ? "(none observed)" : row.configKeys.join(", ")}`).join("\n") });
+		    fields.push({ label: "replacement", value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.replacement.state} (${row.replacement.basis})`).join("\n") });
+		    fields.push({ label: "provenance", value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.provenance.length === 0 ? "unknown" : row.provenance.map((item) => `${item.relation}: ${item.source} (${item.basis})`).join(" \u2192 ")}`).join("\n") });
+		  }
+		  const relatedDiagnosticIds = new Set(relatedRows.flatMap((row) => row.relatedDiagnosticIds));
+		  const rowDiagnostics = report.diagnostics.filter((item) => relatedDiagnosticIds.has(item.id));
+		  const nodeDiagnostic = node.diagnosticId === void 0 ? [] : report.diagnostics.filter((item) => item.id === node.diagnosticId);
+		  return {
+		    title: node.label,
+		    fields,
+		    diagnostics: [...new Map([...rowDiagnostics, ...nodeDiagnostic].map((item) => [item.id, item])).values()],
+		    unknown: [.../* @__PURE__ */ new Set([...relatedRows.flatMap((row) => row.unknown), ...facts.unknownSurfaces])]
+		  };
 		}
 		function renderConflictGraph(document, graph) {
 		  const section = document.createElement("section");
@@ -130,6 +206,137 @@ window.__ModuleLoader__.load({
 		  section.append(list);
 		  return section;
 		}
+		function createFailureExplanation(document, report) {
+		  const section = document.createElement("section");
+		  section.dataset.failureExplanation = "true";
+		  const heading = document.createElement("h3");
+		  heading.textContent = "Failure Explanation";
+		  section.append(heading);
+		  const result = report.failureExplanation;
+		  if (result === void 0) {
+		    const message = document.createElement("p");
+		    message.textContent = "No failure explanation in this report. Run dsh-doctor diagnose --profile <dir> --report-dir <doctor-reports> to create one.";
+		    section.append(message);
+		    return section;
+		  }
+		  const status = document.createElement("p");
+		  status.textContent = `Outcome: ${result.outcome}; runtime: ${result.runtime}. Log signatures are reported claims, not composition evidence.`;
+		  section.append(status);
+		  for (const explanation of result.explanations) {
+		    const details = document.createElement("details");
+		    const summary = document.createElement("summary");
+		    summary.textContent = `${explanation.detectedFailure} (${explanation.origin}; ${explanation.evidenceLevel})`;
+		    const cause = document.createElement("p");
+		    cause.textContent = explanation.observableCause;
+		    const paths = document.createElement("pre");
+		    paths.textContent = explanation.provenancePaths.map((path) => `${path.packageName ?? "profile"} \u2192 ${path.source} \u2192 ${path.layer ?? "unknown layer"} \u2192 ${path.rowId ?? "unknown row"}
+		${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(" \u2192 ")}`).join("\n\n");
+		    const unknown = document.createElement("p");
+		    unknown.textContent = `Unknown: ${explanation.unknowns.join(" ")}`;
+		    const diagnostics = document.createElement("p");
+		    diagnostics.textContent = `Related diagnostics: ${explanation.relatedDiagnostics.map((item) => item.id).join(", ") || "none observed"}`;
+		    const remediation = document.createElement("p");
+		    remediation.textContent = `Manual next step: ${explanation.manualRemediation}`;
+		    details.append(summary, cause, paths, diagnostics, unknown, remediation);
+		    section.append(details);
+		  }
+		  const next = document.createElement("p");
+		  next.textContent = `${result.nextStep} Doctor did not modify your profile.`;
+		  section.append(next);
+		  return section;
+		}
+		function createCompositionExplorer(document, report) {
+		  const section = document.createElement("section");
+		  section.setAttribute("aria-labelledby", "dsh-composition-doctor-explorer");
+		  const heading = document.createElement("h3");
+		  heading.id = "dsh-composition-doctor-explorer";
+		  heading.textContent = "Composition Explorer";
+		  section.append(heading);
+		  const facts = report.compositionFacts;
+		  const graph = facts === void 0 ? { nodes: [], edges: [] } : { nodes: facts.nodes, edges: facts.edges };
+		  if (graph.nodes.length === 0) {
+		    const message = document.createElement("p");
+		    message.textContent = "Composition provenance is unavailable in this legacy report.";
+		    section.append(message);
+		  } else {
+		    const list = document.createElement("ul");
+		    for (const node of graph.nodes.filter((value) => value.entity !== "diagnostic")) {
+		      const item = document.createElement("li");
+		      const select = button(document, `${node.entity}: ${node.label}`, () => {
+		        const detail2 = compositionNodeDetail(report, node.id);
+		        if (detail2 === void 0) return;
+		        const panel = section.querySelector("[data-composition-detail]");
+		        if (panel === null) return;
+		        panel.replaceChildren();
+		        const title = document.createElement("h4");
+		        title.textContent = detail2.title;
+		        panel.append(title);
+		        const fields = document.createElement("dl");
+		        for (const field of detail2.fields) {
+		          const term = document.createElement("dt");
+		          term.textContent = field.label;
+		          const value = document.createElement("dd");
+		          value.textContent = field.value;
+		          fields.append(term, value);
+		        }
+		        panel.append(fields);
+		        const diagnostics = document.createElement("ul");
+		        for (const diagnostic of detail2.diagnostics) {
+		          const entry = document.createElement("li");
+		          entry.textContent = `[${diagnostic.severity}] ${diagnostic.title}: ${diagnostic.explanation}`;
+		          diagnostics.append(entry);
+		        }
+		        if (detail2.diagnostics.length > 0) panel.append(diagnostics);
+		        const unknown = document.createElement("ul");
+		        for (const value of detail2.unknown) {
+		          const entry = document.createElement("li");
+		          entry.textContent = value;
+		          unknown.append(entry);
+		        }
+		        if (detail2.unknown.length > 0) {
+		          const unknownTitle2 = document.createElement("h4");
+		          unknownTitle2.textContent = "Unknown / not modelled";
+		          panel.append(unknownTitle2, unknown);
+		        }
+		      });
+		      select.dataset.compositionNode = node.id;
+		      if (report.failureExplanation?.explanations.some((item2) => item2.provenancePaths.some((path) => path.rowKey === node.rowKey && node.rowKey !== void 0 || path.packageName === node.packageName && node.packageName !== void 0))) {
+		        select.dataset.failureRelated = "true";
+		        select.textContent = `${node.entity}: ${node.label} [failure evidence]`;
+		      }
+		      item.append(select);
+		      const outgoing = graph.edges.filter((edge) => edge.from === node.id);
+		      if (outgoing.length > 0) {
+		        const relationships = document.createElement("ul");
+		        for (const edge of outgoing) {
+		          const target = graph.nodes.find((candidate) => candidate.id === edge.to);
+		          if (target === void 0 || target.entity === "diagnostic") continue;
+		          const relationship = document.createElement("li");
+		          relationship.textContent = `${edge.relation} \u2192 ${target.label} (${edge.basis}; ${edge.evidenceMode})`;
+		          relationships.append(relationship);
+		        }
+		        item.append(relationships);
+		      }
+		      list.append(item);
+		    }
+		    section.append(list);
+		    const detail = document.createElement("section");
+		    detail.dataset.compositionDetail = "true";
+		    detail.setAttribute("aria-live", "polite");
+		    detail.textContent = "Select a bundle, source, layer, or row to inspect its evidence.";
+		    section.append(detail);
+		    const unknownList = document.createElement("ul");
+		    for (const value of facts?.unknownSurfaces ?? []) {
+		      const entry = document.createElement("li");
+		      entry.textContent = value;
+		      unknownList.append(entry);
+		    }
+		    const unknownTitle = document.createElement("h4");
+		    unknownTitle.textContent = "Other surfaces";
+		    section.append(unknownTitle, unknownList);
+		  }
+		  return section;
+		}
 		function isReport(value) {
 		  if (value === null || typeof value !== "object") return false;
 		  const candidate = value;
@@ -220,6 +427,8 @@ window.__ModuleLoader__.load({
 		    status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
 		    status.append(document.createTextNode(" "), badge);
 		    root.append(renderConflictGraph(document, model.graph));
+		    root.append(createFailureExplanation(document, report));
+		    root.append(createCompositionExplorer(document, report));
 		    const list = document.createElement("ul");
 		    for (const diagnostic of report.diagnostics) {
 		      const item = document.createElement("li");

package/dist/core/bundle-inventory.js

@@ -3,12 +3,12 @@ import { inspectInstalledPackage } from './package-provenance.js';
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
-function diagnostic(id, title, source, detail) {
+function diagnostic(id, title, source, detail, packageName) {
     return {
         id,
         severity: 'warning',
         title,
-        evidence: [{ source, detail, evidenceKind: 'static' }],
+        evidence: [{ source, detail, evidenceKind: 'static', ...(packageName === undefined ? {} : { packageName, subject: packageName }) }],
         explanation: detail,
         remediation: 'Install the declared bundle in the selected profile or provide the missing public manifest/patch metadata.'
     };
@@ -32,7 +32,10 @@ function bundleNames(manifest) {
 export async function inspectBundleInventory(profileDir, packageJsonText) {
     let manifest;
     try {
-        manifest = JSON.parse(packageJsonText);
+        const parsed = record(JSON.parse(packageJsonText));
+        if (parsed === undefined)
+            throw new Error('Manifest must be an object');
+        manifest = parsed;
     }
     catch {
         return { packages: [], diagnostics: [diagnostic('bundle-inventory-manifest-invalid', 'Profile package manifest is invalid', 'package.json', 'The profile package.json could not be parsed, so dsh.profile.bundles cannot be inspected.')] };
@@ -48,18 +51,18 @@ export async function inspectBundleInventory(profileDir, packageJsonText) {
                     await access(fact.bundlePatch);
                 }
                 catch {
-                    diagnostics.push(diagnostic('bundle-patch-missing', 'Bundle patch metadata is missing', fact.packageJsonSource, `${declared.name} declares dsh.bundle.patch at ${fact.bundlePatch}, but that file is not readable.`));
+                    diagnostics.push(diagnostic('bundle-patch-missing', 'Bundle patch metadata is missing', fact.packageJsonSource, 'The declared dsh.bundle.patch file is not readable.', declared.name));
                 }
             }
             else {
-                diagnostics.push(diagnostic('bundle-patch-unavailable', 'Bundle patch metadata is unavailable', fact.packageJsonSource, `${declared.name} has no readable dsh.bundle.patch declaration.`));
+                diagnostics.push(diagnostic('bundle-patch-unavailable', 'Bundle patch metadata is unavailable', fact.packageJsonSource, 'The bundle has no readable dsh.bundle.patch declaration.', declared.name));
             }
             if (fact.integrity === undefined && fact.gitRef === undefined) {
                 diagnostics.push(diagnostic('bundle-provenance-unavailable', 'Bundle immutable provenance is unavailable', fact.packageJsonSource, `${declared.name} has neither registry integrity nor a fixed Git reference in its readable manifest.`));
             }
         }
         catch (error) {
-            diagnostics.push(diagnostic('bundle-not-installed', 'Declared bundle is not installed or readable', 'package.json', `${declared.name}${declared.requestedSpec === undefined ? '' : `@${declared.requestedSpec}`} could not be resolved from the selected profile: ${error instanceof Error ? error.message : String(error)}`));
+            diagnostics.push(diagnostic('bundle-not-installed', 'Declared bundle is not installed or readable', 'package.json', 'The declared bundle could not be resolved inside the selected profile.', /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(declared.name) ? declared.name : undefined));
         }
     }
     return { packages, diagnostics };

package/dist/core/composition-provenance.js

@@ -1,3 +1,214 @@
+import { createHash } from 'node:crypto';
+import { basename, isAbsolute, relative, win32 } from 'node:path';
+const unknownSurfaces = [
+    'route ownership: not observed / not modelled',
+    'slot ownership: not observed / not modelled',
+    'runtime hook ownership: not observed / not modelled',
+    'arbitrary dependencies: not modelled',
+    'possible dependents: not modelled'
+];
+function stableKey(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+/** Replace profile and external absolute paths before any composition fact is serialized. */
+export function normalizeCompositionSource(source, profileDir) {
+    if (source.startsWith('<') && source.endsWith('>'))
+        return source;
+    const windowsAbsolute = /^[a-z]:[\\/]/i.test(source) || source.startsWith('\\\\');
+    const posixAbsolute = source.startsWith('/');
+    if (!windowsAbsolute && !posixAbsolute && !isAbsolute(source))
+        return source.replaceAll('\\', '/');
+    try {
+        if (windowsAbsolute || /^[a-z]:[\\/]/i.test(profileDir)) {
+            const relativePath = win32.relative(win32.resolve(profileDir), win32.resolve(source)).replaceAll('\\', '/');
+            if (relativePath === '')
+                return '<PROFILE>';
+            if (relativePath !== '..' && !relativePath.startsWith('../') && !/^[a-z]:/i.test(relativePath))
+                return `<PROFILE>/${relativePath}`;
+        }
+        else {
+            const relativePath = relative(profileDir, source).replaceAll('\\', '/');
+            if (relativePath === '')
+                return '<PROFILE>';
+            if (relativePath !== '..' && !relativePath.startsWith('../') && !isAbsolute(relativePath))
+                return `<PROFILE>/${relativePath}`;
+        }
+    }
+    catch { /* malformed paths are reduced to a basename below */ }
+    return `<EXTERNAL>/${basename(source.replaceAll('\\', '/'))}`;
+}
+function rowConfigKeys(row) {
+    if (row.configKeys !== undefined)
+        return [...new Set(row.configKeys)].sort();
+    if (row.config !== null && typeof row.config === 'object' && !Array.isArray(row.config))
+        return Object.keys(row.config).sort();
+    return [];
+}
+function matchingPackages(model, sources) {
+    const labels = new Set(sources);
+    return (model.installedPackages ?? []).filter((fact) => labels.has(fact.name));
+}
+function relatedDiagnostics(row, packageNames, diagnostics, profileDir) {
+    const sources = new Set([row.source, ...(row.provenance ?? [])].map((source) => normalizeCompositionSource(source, profileDir)));
+    return diagnostics.filter((diagnostic) => diagnostic.evidence.some((item) => (row.id !== undefined && item.subject === row.id) ||
+        packageNames.includes(item.packageName ?? '') ||
+        sources.has(item.source))).map((item) => item.id).sort();
+}
+export function buildCompositionFacts(model, diagnostics) {
+    const nodes = new Map();
+    const edgeMap = new Map();
+    const rows = [];
+    const keyOccurrences = new Map();
+    const packages = model.installedPackages ?? [];
+    const reportMode = model.evidenceMode ?? 'static';
+    const addNode = (node) => nodes.set(node.id, node);
+    const addEdge = (edge) => edgeMap.set(`${edge.from}\0${edge.relation}\0${edge.to}`, edge);
+    for (const packageFact of packages) {
+        const bundleId = `bundle:${encodeURIComponent(packageFact.name)}`;
+        addNode({ id: bundleId, entity: 'bundle', label: packageFact.name, source: normalizeCompositionSource(packageFact.packageJsonSource, model.profileDir), packageName: packageFact.name, ...(packageFact.installedVersion === undefined ? {} : { packageVersion: packageFact.installedVersion }), evidenceMode: 'static' });
+    }
+    for (const [index, row] of model.rows.entries()) {
+        const rowIdentity = row.id ?? row.name ?? `${normalizeCompositionSource(row.source, model.profileDir)}:${index}`;
+        const keyBase = `row:${stableKey(`${rowIdentity}|${normalizeCompositionSource(row.source, model.profileDir)}|${row.layer ?? ''}|${row.layerOrder ?? index}`)}`;
+        const occurrence = keyOccurrences.get(keyBase) ?? 0;
+        keyOccurrences.set(keyBase, occurrence + 1);
+        const rowKey = occurrence === 0 ? keyBase : `${keyBase}:${occurrence}`;
+        const chain = row.provenance === undefined ? [] : [...row.provenance];
+        const chainSources = chain.map((source) => normalizeCompositionSource(source, model.profileDir));
+        const source = normalizeCompositionSource(row.source, model.profileDir);
+        const directPackages = matchingPackages(model, chain.length > 0 ? chain : [row.source]);
+        const associatedPackage = directPackages.length === 1 ? directPackages[0] : undefined;
+        const replacement = row.replacement === true && row.replacementBasis !== 'derived'
+            ? { state: 'yes', basis: 'observed' }
+            : row.replacement === true
+                ? { state: 'unknown', basis: 'unknown' }
+                : row.replacement === false
+                    ? { state: 'no', basis: 'observed' }
+                    : { state: 'unknown', basis: 'unknown' };
+        const unknown = [];
+        if (chain.length === 0)
+            unknown.push('provenance chain is unavailable');
+        if (row.layer === undefined)
+            unknown.push('layer is unknown');
+        if (row.replacement === true)
+            unknown.push(row.replacementBasis !== 'derived'
+                ? 'field-level owner and prior config values are unknown'
+                : 'source chain indicates patching, but whole-row/config replacement, removed keys, and field owners are unknown');
+        if (row.evidenceKind === 'static')
+            unknown.push('final composed row is unknown; this is a static declaration');
+        if (model.runtimeObservation?.observed !== true)
+            unknown.push('runtime behavior was not observed; runtime-dependent values remain unknown/not-run');
+        const provenance = chain.length === 0
+            ? []
+            : chain.map((chainSource, chainIndex) => ({
+                source: chainSources[chainIndex],
+                sourceBasis: 'observed',
+                relation: (chainIndex === 0 ? 'introduced' : 'patched-by'),
+                basis: 'derived'
+            }));
+        const fact = {
+            entity: 'row', key: rowKey,
+            ...(row.operation === undefined ? {} : { operation: row.operation }),
+            ...(row.id === undefined ? {} : { id: row.id }),
+            ...(row.name === undefined ? {} : { name: row.name }),
+            source,
+            sourceBasis: 'observed',
+            ...(row.layer === undefined ? {} : { layer: row.layer }),
+            ...(row.layerOrder === undefined ? {} : { layerOrder: row.layerOrder }),
+            provenance,
+            replacement,
+            configKeys: rowConfigKeys(row),
+            configKeysBasis: row.configKeys === undefined ? 'derived' : 'observed',
+            evidenceMode: row.evidenceKind,
+            ...(associatedPackage === undefined ? {} : { packageName: associatedPackage.name, ...(associatedPackage.installedVersion === undefined ? {} : { packageVersion: associatedPackage.installedVersion }) }),
+            relatedDiagnosticIds: relatedDiagnostics(row, directPackages.map((item) => item.name), diagnostics, model.profileDir),
+            unknown: [...new Set(unknown)].sort()
+        };
+        rows.push(fact);
+        addNode({ id: rowKey, entity: 'row', label: row.id ?? row.name ?? 'anonymous row', source, ...(row.layer === undefined ? {} : { layer: row.layer }), ...(row.layerOrder === undefined ? {} : { layerOrder: row.layerOrder }), ...(fact.packageName === undefined ? {} : { packageName: fact.packageName }), ...(fact.packageVersion === undefined ? {} : { packageVersion: fact.packageVersion }), evidenceMode: row.evidenceKind, rowKey });
+        if (row.layer !== undefined) {
+            const layerId = `layer:${stableKey(`${row.layer}:${row.layerOrder ?? ''}`)}`;
+            addNode({ id: layerId, entity: 'layer', label: row.layer, layer: row.layer, ...(row.layerOrder === undefined ? {} : { layerOrder: row.layerOrder }), evidenceMode: row.evidenceKind });
+            addEdge({ from: layerId, to: rowKey, relation: 'contains', basis: 'observed', evidenceMode: row.evidenceKind });
+        }
+        const linkSources = chain.length === 0 ? [row.source] : chain;
+        linkSources.forEach((label, chainIndex) => {
+            const normalized = normalizeCompositionSource(label, model.profileDir);
+            const matched = packages.filter((pkg) => pkg.name === label);
+            const packageFact = matched.length === 1 ? matched[0] : undefined;
+            const sourceId = `source:${stableKey(normalized)}`;
+            addNode({ id: sourceId, entity: 'source', label: normalized, source: normalized, evidenceMode: row.evidenceKind });
+            if (packageFact !== undefined) {
+                const bundleId = `bundle:${encodeURIComponent(packageFact.name)}`;
+                addNode({ id: bundleId, entity: 'bundle', label: packageFact.name, source: normalizeCompositionSource(packageFact.packageJsonSource, model.profileDir), packageName: packageFact.name, ...(packageFact.installedVersion === undefined ? {} : { packageVersion: packageFact.installedVersion }), evidenceMode: 'static' });
+                addEdge({ from: bundleId, to: sourceId, relation: 'package-source', basis: 'derived', evidenceMode: row.evidenceKind });
+            }
+            addEdge({
+                from: sourceId,
+                to: rowKey,
+                relation: chain.length === 0 ? 'source-of' : chainIndex === 0 ? 'introduced' : 'patched-by',
+                basis: chain.length === 0 ? 'observed' : 'derived',
+                evidenceMode: row.evidenceKind
+            });
+        });
+        for (const diagnosticId of fact.relatedDiagnosticIds) {
+            const diagnostic = diagnostics.find((item) => item.id === diagnosticId);
+            if (diagnostic === undefined)
+                continue;
+            const diagnosticKey = `diagnostic:${diagnosticId}`;
+            addNode({ id: diagnosticKey, entity: 'diagnostic', label: diagnostic.title, diagnosticId, evidenceMode: diagnostic.evidence[0]?.evidenceKind ?? row.evidenceKind });
+            addEdge({ from: rowKey, to: diagnosticKey, relation: 'diagnosed-by', basis: 'derived', evidenceMode: diagnostic.evidence[0]?.evidenceKind ?? row.evidenceKind });
+        }
+    }
+    rows.sort((left, right) => left.key.localeCompare(right.key));
+    return {
+        schemaVersion: 1,
+        evidenceMode: reportMode,
+        nodes: [...nodes.values()].sort((left, right) => left.id.localeCompare(right.id)),
+        edges: [...edgeMap.values()].sort((left, right) => `${left.from}:${left.relation}:${left.to}`.localeCompare(`${right.from}:${right.relation}:${right.to}`)),
+        rows,
+        unknownSurfaces
+    };
+}
+export function findCompositionRow(facts, id) {
+    return facts.rows.find((row) => row.id === id);
+}
+export function compositionBundleImpact(report, name) {
+    const facts = report.compositionFacts;
+    const rows = facts?.rows.filter((row) => row.packageName === name || row.provenance.some((item) => item.source === name)) ?? [];
+    const rowKeys = new Set(rows.map((row) => row.key));
+    const sourceLabels = new Set(rows.flatMap((row) => row.provenance.map((item) => item.source)));
+    const sourceIds = new Set(facts?.nodes.filter((node) => node.entity === 'source' && sourceLabels.has(node.label)).map((node) => node.id) ?? []);
+    const bundleId = `bundle:${encodeURIComponent(name)}`;
+    const edges = facts?.edges.filter((edge) => rowKeys.has(edge.to) || rowKeys.has(edge.from) || sourceIds.has(edge.from) || sourceIds.has(edge.to) || edge.from === bundleId || edge.to === bundleId) ?? [];
+    const diagnosticIds = new Set(rows.flatMap((row) => row.relatedDiagnosticIds));
+    const diagnostics = report.diagnostics.filter((diagnostic) => diagnosticIds.has(diagnostic.id) || diagnostic.evidence.some((item) => item.packageName === name));
+    return {
+        schemaVersion: 1,
+        bundle: name,
+        evidenceMode: facts?.evidenceMode ?? (report.evidenceMode === 'resolved' ? 'static' : report.evidenceMode),
+        rows,
+        edges,
+        diagnostics,
+        unknown: facts?.unknownSurfaces ?? [...unknownSurfaces]
+    };
+}
+/** Normalize paths in diagnostic evidence before adding them to a report. */
+export function redactDiagnosticPaths(diagnostics, model) {
+    const knownPaths = [model.profileDir, ...(model.installedPackages ?? []).flatMap((fact) => [fact.packageJsonSource, ...(fact.bundlePatch === undefined ? [] : [fact.bundlePatch])])]
+        .filter((value) => value.length > 0);
+    return diagnostics.map((diagnostic) => ({
+        ...diagnostic,
+        evidence: diagnostic.evidence.map((item) => {
+            let detail = item.detail;
+            for (const path of knownPaths) {
+                const normalized = path.replaceAll('\\', '/');
+                detail = detail.replaceAll(path, normalizeCompositionSource(path, model.profileDir)).replaceAll(normalized, normalizeCompositionSource(path, model.profileDir));
+            }
+            return { ...item, source: normalizeCompositionSource(item.source, model.profileDir), detail };
+        })
+    }));
+}
 export function rowEvidence(row) {
     return {
         source: row.source,

package/dist/core/dsh-dump-parser.js

@@ -83,6 +83,7 @@ export function parseDshDump(stdout, stderr = '') {
         const provenance = provenanceParts(typeof object.source === 'string' ? object.source : provenanceHints[index] ?? legacyProvenanceHints[index]);
         const source = typeof object.source === 'string' ? object.source : provenance.source ?? '<DSH dump>';
         const config = object.config;
+        const explicitReplacement = object.replacement === true || object.overridden === true;
         const row = {
             ...(typeof object.id === 'string' ? { id: object.id } : {}),
             ...(typeof object.name === 'string' ? { name: object.name } : typeof object.plugin === 'string' ? { name: object.plugin } : {}),
@@ -92,7 +93,9 @@ export function parseDshDump(stdout, stderr = '') {
             ...(typeof object.layer === 'string' ? { layer: object.layer } : {}),
             ...(typeof object.layerOrder === 'number' ? { layerOrder: object.layerOrder } : {}),
             ...(provenance.provenance === undefined ? {} : { provenance: provenance.provenance }),
-            ...(object.replacement === true || object.overridden === true || (provenance.provenance !== undefined && provenance.provenance.length > 1) || (typeof object.id === 'string' && seenIds.has(object.id) && seenIds.get(object.id) !== source) ? { replacement: true } : {})
+            ...(explicitReplacement || (provenance.provenance !== undefined && provenance.provenance.length > 1) || (typeof object.id === 'string' && seenIds.has(object.id) && seenIds.get(object.id) !== source)
+                ? { replacement: true, replacementBasis: explicitReplacement ? 'observed' : 'derived' }
+                : {})
         };
         if (row.id !== undefined)
             seenIds.set(row.id, row.source);
@@ -103,7 +106,7 @@ export function parseDshDump(stdout, stderr = '') {
     for (const detail of unmatched)
         diagnostics.push({
             id: 'unmatched-patch-target', severity: 'warning', title: 'Resolved patch target did not match a row',
-            evidence: [{ source: '<DSH stderr>', detail, evidenceKind: 'composed' }],
+            evidence: [{ source: '<DSH stderr>', detail, evidenceKind: 'composed', ...(detail.match(/entry ["']([a-z0-9_.:-]+)["'] not found/i)?.[1] === undefined ? {} : { subject: detail.match(/entry ["']([a-z0-9_.:-]+)["'] not found/i)[1] }) }],
             explanation: 'The public DSH dump reported a patch target that did not match a resolved row.',
             remediation: 'Verify the patch row id against the selected bundle/profile composition.'
         });