dsh-composition-doctor 0.2.1 → 0.3.0

package/dist/client/report-view.js

@@ -35,7 +35,55 @@ export 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 ?? [] }
+    };
+}
+export function compositionNodeDetail(report, nodeId) {
+    const facts = report.compositionFacts;
+    const node = facts?.nodes.find((candidate) => candidate.id === nodeId);
+    if (facts === undefined || node === undefined)
+        return undefined;
+    const relatedRows = facts.rows.filter((candidate) => {
+        if (node.rowKey !== undefined)
+            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 === undefined || candidate.layerOrder === node.layerOrder);
+        if (node.entity === 'diagnostic')
+            return node.diagnosticId !== undefined && 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 !== undefined)
+        fields.push({ label: 'layer', value: node.layer });
+    if (node.layerOrder !== undefined)
+        fields.push({ label: 'layer order', value: String(node.layerOrder) });
+    if (node.packageName !== undefined)
+        fields.push({ label: 'package', value: `${node.packageName}${node.packageVersion === undefined ? '' : `@${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(' → ')}`).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 === undefined ? [] : 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: [...new Set([...relatedRows.flatMap((row) => row.unknown), ...facts.unknownSurfaces])]
+    };
 }
 function renderConflictGraph(document, graph) {
     const section = document.createElement('section');
@@ -59,6 +107,99 @@ function renderConflictGraph(document, graph) {
     section.append(list);
     return section;
 }
+export 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 === undefined ? { 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 detail = compositionNodeDetail(report, node.id);
+                if (detail === undefined)
+                    return;
+                const panel = section.querySelector('[data-composition-detail]');
+                if (panel === null)
+                    return;
+                panel.replaceChildren();
+                const title = document.createElement('h4');
+                title.textContent = detail.title;
+                panel.append(title);
+                const fields = document.createElement('dl');
+                for (const field of detail.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 detail.diagnostics) {
+                    const entry = document.createElement('li');
+                    entry.textContent = `[${diagnostic.severity}] ${diagnostic.title}: ${diagnostic.explanation}`;
+                    diagnostics.append(entry);
+                }
+                if (detail.diagnostics.length > 0)
+                    panel.append(diagnostics);
+                const unknown = document.createElement('ul');
+                for (const value of detail.unknown) {
+                    const entry = document.createElement('li');
+                    entry.textContent = value;
+                    unknown.append(entry);
+                }
+                if (detail.unknown.length > 0) {
+                    const unknownTitle = document.createElement('h4');
+                    unknownTitle.textContent = 'Unknown / not modelled';
+                    panel.append(unknownTitle, unknown);
+                }
+            });
+            select.dataset.compositionNode = node.id;
+            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 === undefined || target.entity === 'diagnostic')
+                        continue;
+                    const relationship = document.createElement('li');
+                    relationship.textContent = `${edge.relation} → ${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;
@@ -145,6 +286,7 @@ export function createReportView(document = globalThis.document, translate = (ke
         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(createCompositionExplorer(document, report));
         const list = document.createElement('ul');
         for (const diagnostic of report.diagnostics) {
             const item = document.createElement('li');

package/dist/client.js

@@ -106,7 +106,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 +171,94 @@ window.__ModuleLoader__.load({
 		  section.append(list);
 		  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;
+		      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 +349,7 @@ 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(createCompositionExplorer(document, report));
 		    const list = document.createElement("ul");
 		    for (const diagnostic of report.diagnostics) {
 		      const item = document.createElement("li");

package/dist/core/composition-provenance.js

@@ -1,3 +1,209 @@
+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 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 rowKey = `row:${stableKey(`${rowIdentity}|${normalizeCompositionSource(row.source, model.profileDir)}|${row.layer ?? ''}|${row.layerOrder ?? index}`)}`;
+        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.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);

package/dist/core/rules.js

@@ -1,4 +1,5 @@
 import { satisfies as semverSatisfies } from 'semver';
+import { buildCompositionFacts, redactDiagnosticPaths } from './composition-provenance.js';
 function evidence(source, subject, detail, evidenceKind, packageName, version) {
     return { source, subject, detail, evidenceKind, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) };
 }
@@ -157,6 +158,18 @@ export function analyseComposition(model) {
     }
     diagnostics.sort((left, right) => left.id.localeCompare(right.id) || left.title.localeCompare(right.title) || left.evidence[0]?.source.localeCompare(right.evidence[0]?.source ?? '') || 0);
     const evidenceMode = runtimeObserved ? 'runtime-observed' : requestedMode === 'runtime-observed' ? 'composed' : requestedMode;
-    const unverifiedFindings = diagnostics.filter((item) => item.id === 'runtime-composition-unavailable' || item.evidence.some((entry) => entry.evidenceKind === 'static')).map((item) => item.id);
-    return { schemaVersion: 1, evidenceSchemaVersion: 2, generatedAt: new Date().toISOString(), profileDir: model.profileDir, evidenceMode, runtimeObserved, ...(model.metadataCoverage === undefined ? {} : { metadataCoverage: model.metadataCoverage }), unverifiedFindings, diagnostics };
+    const redactedDiagnostics = redactDiagnosticPaths(diagnostics, model);
+    const unverifiedFindings = redactedDiagnostics.filter((item) => item.id === 'runtime-composition-unavailable' || item.evidence.some((entry) => entry.evidenceKind === 'static')).map((item) => item.id);
+    const reportBase = {
+        schemaVersion: 1,
+        evidenceSchemaVersion: 2,
+        generatedAt: new Date().toISOString(),
+        profileDir: '<PROFILE>',
+        evidenceMode,
+        runtimeObserved,
+        ...(model.metadataCoverage === undefined ? {} : { metadataCoverage: model.metadataCoverage }),
+        unverifiedFindings,
+        diagnostics: redactedDiagnostics
+    };
+    return { ...reportBase, compositionFacts: buildCompositionFacts({ ...model, evidenceMode }, redactedDiagnostics) };
 }

package/dist/reports/schema.js

@@ -12,6 +12,44 @@ export const analysisReportJsonSchema = {
         evidenceMode: { enum: ['static', 'composed', 'runtime-observed', 'mixed'] },
         runtimeObserved: { type: 'boolean' },
         unverifiedFindings: { type: 'array', items: { type: 'string' } },
+        compositionFacts: {
+            type: 'object',
+            required: ['schemaVersion', 'evidenceMode', 'nodes', 'edges', 'rows', 'unknownSurfaces'],
+            properties: {
+                schemaVersion: { const: 1 },
+                evidenceMode: { enum: ['static', 'composed', 'runtime-observed', 'mixed'] },
+                nodes: { type: 'array', items: {
+                        type: 'object', required: ['id', 'entity', 'label'],
+                        properties: {
+                            id: { type: 'string' }, entity: { enum: ['bundle', 'source', 'layer', 'row', 'diagnostic'] }, label: { type: 'string' },
+                            source: { type: 'string' }, layer: { type: 'string' }, layerOrder: { type: 'number' },
+                            packageName: { type: 'string' }, packageVersion: { type: 'string' },
+                            evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] }, rowKey: { type: 'string' }, diagnosticId: { type: 'string' }
+                        }, additionalProperties: false
+                    } },
+                edges: { type: 'array', items: {
+                        type: 'object', required: ['from', 'to', 'relation', 'basis', 'evidenceMode'],
+                        properties: {
+                            from: { type: 'string' }, to: { type: 'string' },
+                            relation: { enum: ['introduced', 'patched-by', 'source-of', 'contains', 'diagnosed-by', 'package-source'] },
+                            basis: { enum: ['observed', 'derived'] }, evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] }
+                        }, additionalProperties: false
+                    } },
+                rows: { type: 'array', items: {
+                        type: 'object', required: ['entity', 'key', 'source', 'sourceBasis', 'provenance', 'replacement', 'configKeys', 'configKeysBasis', 'evidenceMode', 'relatedDiagnosticIds', 'unknown'],
+                        properties: {
+                            entity: { const: 'row' }, key: { type: 'string' }, id: { type: 'string' }, name: { type: 'string' },
+                            source: { type: 'string' }, sourceBasis: { const: 'observed' }, layer: { type: 'string' }, layerOrder: { type: 'number' },
+                            provenance: { type: 'array', items: { type: 'object', required: ['source', 'sourceBasis', 'relation', 'basis'], properties: { source: { type: 'string' }, sourceBasis: { const: 'observed' }, relation: { enum: ['introduced', 'patched-by'] }, basis: { enum: ['observed', 'derived'] } }, additionalProperties: false } },
+                            replacement: { type: 'object', required: ['state', 'basis'], properties: { state: { enum: ['yes', 'no', 'unknown'] }, basis: { enum: ['observed', 'derived', 'unknown'] } }, additionalProperties: false },
+                            configKeys: { type: 'array', items: { type: 'string' } }, configKeysBasis: { enum: ['observed', 'derived'] }, evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] },
+                            packageName: { type: 'string' }, packageVersion: { type: 'string' }, relatedDiagnosticIds: { type: 'array', items: { type: 'string' } },
+                            removedConfigKeys: { type: 'array', items: { type: 'string' } }, unknown: { type: 'array', items: { type: 'string' } }
+                        }, additionalProperties: false
+                    } },
+                unknownSurfaces: { type: 'array', items: { type: 'string' } }
+            }, additionalProperties: false
+        },
         diagnostics: {
             type: 'array',
             items: {