@mergesignal/shared 0.2.6 → 0.2.8

package/dist/scanCardSummary.js

@@ -1,9 +1,9 @@
-import { deriveCardOperationalObservations } from "./deriveCardOperationalObservations.js";
-import { mergePostureFromDecision, MERGE_POSTURE_LABEL, } from "./riskVocabulary.js";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { presentScanCardSummary } from "./presentScanCardSummary.js";
+import { mergePostureFromDecision, } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
-import { selectTopAffectedAreas } from "./selectTopAffectedAreas.js";
 const STALE_SUBLINE = "Based on earlier commit";
-export const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results…";
+export const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results...";
 function normalizePipelineStatus(status) {
     const st = String(status ?? "")
         .trim()
@@ -59,7 +59,8 @@ export function isPipelineCardSummary(summary) {
         summary.riskIndex === null &&
         (summary.headline === scanSurfaceCopy.pipeline.scanRunning ||
             summary.headline === scanSurfaceCopy.pipeline.analysisIncomplete ||
-            summary.headline === scanSurfaceCopy.pipeline.scanUnavailable));
+            summary.headline === scanSurfaceCopy.pipeline.scanUnavailable) &&
+        summary.narrativeMode === "denormalized");
 }
 /** Single source for risk index color bands (aligns with decision score bands). */
 export function deriveRiskIndexBand(score) {
@@ -101,68 +102,26 @@ export function aggregateFindingCounts(findings) {
  */
 export function deriveScanCardSummary(result, pipelineStatus) {
     if (pipelineStatus === "queued" || pipelineStatus === "running") {
-        return {
-            mergePosture: null,
-            riskIndex: null,
-            riskIndexBand: null,
-            headline: scanSurfaceCopy.pipeline.scanRunning,
-            summaryLine: SCAN_CARD_SCANNING_SUMMARY,
-            findingCounts: null,
-            topAffectedAreas: [],
-            operationalObservations: [],
-            supportingLine: null,
-        };
+        return presentScanCardSummary(deriveScanNarrative(null), {
+            pipelineStatus,
+        });
     }
     if (pipelineStatus === "failed") {
-        return {
-            mergePosture: null,
-            riskIndex: null,
-            riskIndexBand: null,
-            headline: scanSurfaceCopy.pipeline.analysisIncomplete,
-            summaryLine: null,
-            findingCounts: null,
-            topAffectedAreas: [],
-            operationalObservations: [],
-            supportingLine: null,
-        };
+        return presentScanCardSummary(deriveScanNarrative(null), {
+            pipelineStatus: "failed",
+        });
     }
     if (!result) {
         return {
-            mergePosture: null,
-            riskIndex: null,
-            riskIndexBand: null,
+            ...presentScanCardSummary(deriveScanNarrative(null), { pipelineStatus }),
             headline: scanSurfaceCopy.pipeline.scanUnavailable,
-            summaryLine: null,
-            findingCounts: null,
-            topAffectedAreas: [],
-            operationalObservations: [],
-            supportingLine: null,
         };
     }
-    const posture = mergePostureFromDecision(result.decision?.recommendation) ?? null;
-    const riskIndex = typeof result.totalScore === "number" ? result.totalScore : null;
-    const riskIndexBand = deriveRiskIndexBand(riskIndex);
-    const findingCounts = aggregateFindingCounts(result.findings);
-    const headline = posture
-        ? MERGE_POSTURE_LABEL[posture]
-        : scanSurfaceCopy.checkRun.mergePostureUnavailable;
-    const topAffectedAreas = selectTopAffectedAreas(result, { max: 2 });
-    const { operationalObservations, supportingLine } = deriveCardOperationalObservations(result, {
-        mergePosture: posture,
-        hasFullResult: true,
-        max: 3,
+    const facts = deriveScanNarrative(result);
+    return presentScanCardSummary(facts, {
+        pipelineStatus,
+        findings: result.findings,
     });
-    return {
-        mergePosture: posture,
-        riskIndex,
-        riskIndexBand,
-        headline,
-        summaryLine: null,
-        findingCounts,
-        topAffectedAreas,
-        operationalObservations,
-        supportingLine,
-    };
 }
 /** Subline appended when scan results are stale (head SHA mismatch). */
 export function staleScanSubline() {

package/dist/scanCardSummary.test.js

@@ -1,6 +1,21 @@
 import { describe, it, expect } from "vitest";
 import { isCatalogPhrase } from "./cardObservationCatalog.js";
 import { aggregateFindingCounts, deriveRiskIndexBand, deriveScanCardSummary, deriveScanCardSummaryFromDenormalized, isPipelineCardSummary, isPipelinePlaceholderCopy, resolvePipelineStatus, resolvePrScanCardSummary, staleScanSubline, } from "./scanCardSummary.js";
+const pipelinePresentationDefaults = {
+    narrativeMode: "denormalized",
+    codeIntelligenceAvailable: false,
+    changedPackagesDisplay: null,
+    runtimeSurfaceLabel: null,
+    reachabilityLabel: null,
+    blastRadiusLabel: null,
+    affectedAreas: [],
+    primaryInsight: null,
+    structuralOnlyDisclaimer: null,
+    usageSummary: null,
+    verificationLine: null,
+    blastRadiusDetail: null,
+    frameworksSummary: null,
+};
 const baseResult = {
     totalScore: 10,
     layerScores: {
@@ -53,7 +68,7 @@ describe("deriveScanCardSummary", () => {
     it("returns scanning copy for queued/running", () => {
         const queued = deriveScanCardSummary(null, "queued");
         expect(queued.headline).toBe("Scan in progress");
-        expect(queued.summaryLine).toBe("Waiting for results…");
+        expect(queued.summaryLine).toBe("Waiting for results...");
         expect(queued.mergePosture).toBeNull();
         const running = deriveScanCardSummary(null, "running");
         expect(running.headline).toBe("Scan in progress");
@@ -173,11 +188,12 @@ describe("isPipelineCardSummary", () => {
             riskIndex: null,
             riskIndexBand: null,
             headline: "Scan in progress",
-            summaryLine: "Waiting for results…",
+            summaryLine: "Waiting for results...",
             findingCounts: null,
             topAffectedAreas: [],
             operationalObservations: [],
             supportingLine: null,
+            ...pipelinePresentationDefaults,
         })).toBe(true);
     });
     it("detects hybrid completed posture with pipeline summary line", () => {
@@ -186,17 +202,18 @@ describe("isPipelineCardSummary", () => {
             riskIndex: 72,
             riskIndexBand: "high",
             headline: "Risky",
-            summaryLine: "Waiting for results…",
+            summaryLine: "Waiting for results...",
             findingCounts: null,
             topAffectedAreas: [],
             operationalObservations: [],
             supportingLine: null,
+            ...pipelinePresentationDefaults,
         })).toBe(true);
     });
 });
 describe("isPipelinePlaceholderCopy", () => {
     it("identifies waiting copy", () => {
-        expect(isPipelinePlaceholderCopy("Waiting for results…")).toBe(true);
+        expect(isPipelinePlaceholderCopy("Waiting for results...")).toBe(true);
         expect(isPipelinePlaceholderCopy("Auth change")).toBe(false);
     });
 });
@@ -210,9 +227,9 @@ describe("deriveScanCardSummaryFromDenormalized", () => {
         expect(summary.operationalObservations).toEqual([]);
     });
     it("does not inject pipeline placeholder summaryText", () => {
-        const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Waiting for results…", "done");
+        const summary = deriveScanCardSummaryFromDenormalized("risky", 72, "Waiting for results...", "done");
         expect(summary.mergePosture).toBe("risky");
-        expect(summary.summaryLine).not.toBe("Waiting for results…");
+        expect(summary.summaryLine).not.toBe("Waiting for results...");
     });
     it("does not inject raw generic summaryText on quiet safe cards", () => {
         const summary = deriveScanCardSummaryFromDenormalized("safe", 12, "No high-confidence merge risks from this PR dependency change", "done");
@@ -226,11 +243,11 @@ describe("resolvePrScanCardSummary", () => {
             pipelineStatus: "running",
             decision: "risky",
             totalScore: 80,
-            summaryText: "Waiting for results…",
+            summaryText: "Waiting for results...",
             result: null,
         });
         expect(summary.mergePosture).toBe("risky");
         expect(summary.headline).toBe("Risky");
-        expect(summary.summaryLine).not.toBe("Waiting for results…");
+        expect(summary.summaryLine).not.toBe("Waiting for results...");
     });
 });

package/dist/scanDetailViewModel.d.ts

@@ -1,3 +1,4 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
 import { type ScanDetailRecommendationCenter } from "./deriveScanDetailRecommendations.js";
 import { type ScanDetailSignalSummary } from "./deriveRiskScoreSummary.js";
 import { type MergePosture } from "./riskVocabulary.js";
@@ -57,6 +58,22 @@ export type ScanDetailTopology = {
         via: string[];
     }>;
 };
+export type ScanDetailNarrativeContext = {
+    mode: import("./scanNarrativeFacts.js").NarrativeAvailabilityMode;
+    codeIntelligenceAvailable: boolean;
+    changedPackagesDisplay: string | null;
+    runtimeSurfaceLabel: string | null;
+    reachabilityLabel: string | null;
+    blastRadiusLabel: string | null;
+    affectedAreas: string[];
+    structuralOnlyDisclaimer: string | null;
+    usageHighlights: string[];
+    frameworks: string[];
+    blastRadiusFactors: string[];
+    hotspotNames: string[];
+    usageContextLine: string | null;
+    upgradeContextLine: string | null;
+};
 export type ScanDetailViewModel = {
     verdict: ScanDetailVerdict;
     signalSummary: ScanDetailSignalSummary | null;
@@ -79,12 +96,14 @@ export type ScanDetailViewModel = {
         status: "loaded";
         comparisonLine: string;
     };
+    narrativeContext: ScanDetailNarrativeContext;
     metadata: {
         scanId: string;
         generatedAt?: string;
         methodologyVersion?: string | null;
         changedPackagesSummary?: string;
         codeAnalysisTimedOut?: boolean;
+        codeIntelligenceAvailable?: boolean;
     };
 };
 export type DeriveScanDetailOptions = {
@@ -102,6 +121,9 @@ export declare function sanitizeAct2Theme(raw: string): string | null;
 export declare function deriveVerdictLine(posture: MergePosture | null, totalScore: number | null | undefined): string;
 export declare function deriveAct2Themes(result: ScanResult): string[];
 export declare function deriveOperationalImpact(result: ScanResult, verifyLabels?: Set<string>): ScanDetailOperationalImpact;
+export declare function presentScanDetailNarrativeContext(facts: ScanNarrativeFacts): ScanDetailNarrativeContext;
+/** Scan detail presentation from shared narrative facts. */
+export declare function presentScanDetailViewModel(facts: ScanNarrativeFacts, result: ScanResult, options: DeriveScanDetailOptions): ScanDetailViewModel;
 export declare function deriveScanDetailViewModel(result: ScanResult | null | undefined, options: DeriveScanDetailOptions): ScanDetailViewModel | null;
 /** Tier 1 recall test helper — true when message describes application-level impact. */
 export declare function tier1PassesRecallTest(operationalImpact: ScanDetailOperationalImpact): boolean;

package/dist/scanDetailViewModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanDetailViewModel.d.ts","sourceRoot":"","sources":["../src/scanDetailViewModel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scanDetailViewModel.d.ts","sourceRoot":"","sources":["../src/scanDetailViewModel.ts"],"names":[],"mappings":"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"}

package/dist/scanDetailViewModel.js

@@ -1,5 +1,9 @@
 import { humanizeEngineSurfaceText, layerRiskBandLabel, sortPRInsightsForDisplay, truncateWithEllipsis, } from "./actionsStepSummary.js";
 import { mapFindingToCatalogPhrase, mapGraphInsightsToCatalogPhrases, phraseForFamily, } from "./cardObservationCatalog.js";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { formatCardAreaLabels } from "./formatCardAreaLabels.js";
+import { composeContextLineFromFacts, formatChangedPackagesShort, formatUsageSummaryLine, labelBlastRadiusLevel, labelReachabilityKind, labelRuntimeSurface, summarizeBlastRadius, } from "./narrativePresentation.js";
+import { normalizeGeneratedText, normalizeGeneratedTextNullable, } from "./normalizeGeneratedText.js";
 import { deriveCardOperationalObservations } from "./deriveCardOperationalObservations.js";
 import { deriveScanDetailRecommendations, recommendationTitlesForDedupe, } from "./deriveScanDetailRecommendations.js";
 import { deriveSignalSummary, } from "./deriveRiskScoreSummary.js";
@@ -206,6 +210,72 @@ function graphInsightToPackage(item, severity, evidence) {
         evidence,
     };
 }
+function usageWhereFromFacts(facts) {
+    const primary = facts.changedPackages.primary;
+    const row = facts.packageUsage.find((u) => u.packageName === primary) ??
+        facts.packageUsage[0];
+    if (!row)
+        return undefined;
+    const paths = [...row.paths, ...row.criticalPaths, ...row.files].filter(Boolean);
+    if (paths.length === 0 && row.areas.length > 0) {
+        return row.areas.slice(0, 3).join(", ");
+    }
+    if (paths.length === 0)
+        return undefined;
+    const sample = paths.slice(0, 3).join(", ");
+    if (paths.length > 3) {
+        return `${sample} (+${paths.length - 3} more)`;
+    }
+    return sample;
+}
+function buildAttentionAreasFromFacts(facts) {
+    const areas = [];
+    if (facts.hotspots.length > 0) {
+        const packages = facts.hotspots.map((h) => ({
+            name: h.packageName,
+            direct: true,
+            evidence: h.paths[0],
+        }));
+        areas.push({
+            problemLabel: "Dependency hotspots",
+            problemDescription: "Packages where paths converge or corpus analysis flagged critical usage.",
+            packages: packages.slice(0, ACT3_EVIDENCE_COLLAPSE_THRESHOLD),
+            overflowCount: Math.max(0, packages.length - ACT3_EVIDENCE_COLLAPSE_THRESHOLD),
+        });
+    }
+    const blast = facts.blastRadius;
+    if (blast &&
+        (blast.level === "wide" || (blast.changedPackageCount ?? 0) >= 8)) {
+        const names = facts.changedPackages.all;
+        if (names.length > 0) {
+            const packages = names
+                .slice(0, ACT3_EVIDENCE_COLLAPSE_THRESHOLD)
+                .map((name) => ({ name, direct: true }));
+            areas.push({
+                problemLabel: phraseForFamily("blast_radius"),
+                problemDescription: blast.factors.length > 0
+                    ? `Wide blast radius: ${blast.factors.slice(0, 3).join(", ").replace(/_/g, " ")}`
+                    : "Many packages changed in this upgrade.",
+                packages,
+                overflowCount: Math.max(0, names.length - ACT3_EVIDENCE_COLLAPSE_THRESHOLD),
+            });
+        }
+    }
+    return areas;
+}
+function mergeAttentionAreas(fromFacts, fromGraph) {
+    if (fromFacts.length === 0)
+        return fromGraph;
+    const factPackageNames = new Set(fromFacts.flatMap((a) => a.packages.map((p) => p.name)));
+    const filteredGraph = fromGraph.filter((area) => {
+        if (area.problemLabel !== phraseForFamily("transitive_hotspots")) {
+            return true;
+        }
+        const onlyDupes = area.packages.every((p) => factPackageNames.has(p.name));
+        return !onlyDupes;
+    });
+    return [...fromFacts, ...filteredGraph];
+}
 function buildAttentionAreas(result) {
     const areas = [];
     const gi = result.graphInsights;
@@ -310,7 +380,7 @@ function buildTopology(result) {
         }))
         : [];
     return {
-        summaryLine: `${nodes} packages · ${edges} edges · max depth ${maxDepth}`,
+        summaryLine: normalizeGeneratedText(`${nodes} packages | ${edges} edges | max depth ${maxDepth}`),
         deepest,
     };
 }
@@ -344,44 +414,173 @@ function deriveConfidenceCaveat(result) {
     }
     return undefined;
 }
-function changedPackagesSummary(changed) {
-    if (!changed?.length)
-        return undefined;
-    if (changed.length === 1)
-        return changed[0];
-    return `${changed[0]} +${changed.length - 1} changed`;
+export function presentScanDetailNarrativeContext(facts) {
+    const affectedAreas = [];
+    for (const area of facts.affectedAreas) {
+        const formatted = formatCardAreaLabels([area.label], 1);
+        if (formatted[0])
+            affectedAreas.push(formatted[0]);
+        if (affectedAreas.length >= 4)
+            break;
+    }
+    const usageHighlights = [];
+    for (const row of facts.packageUsage.slice(0, 4)) {
+        const paths = [...row.paths, ...row.criticalPaths, ...row.files];
+        if (paths[0])
+            usageHighlights.push(paths[0]);
+    }
+    const blast = summarizeBlastRadius(facts, 5);
+    return {
+        mode: facts.availability.mode,
+        codeIntelligenceAvailable: facts.availability.codeIntelligenceAvailable,
+        changedPackagesDisplay: formatChangedPackagesShort(facts, 4),
+        runtimeSurfaceLabel: labelRuntimeSurface(facts),
+        reachabilityLabel: labelReachabilityKind(facts),
+        blastRadiusLabel: labelBlastRadiusLevel(facts),
+        affectedAreas,
+        structuralOnlyDisclaimer: facts.availability.mode === "graph_fallback" &&
+            !facts.availability.tiersPresent.tier1
+            ? scanSurfaceCopy.narrativeCard.structuralOnlyDisclaimer
+            : null,
+        usageHighlights: usageHighlights.slice(0, 5),
+        frameworks: facts.frameworks.slice(0, 5),
+        blastRadiusFactors: blast.factors.map((f) => f.replace(/_/g, " ")),
+        hotspotNames: facts.hotspots.map((h) => h.packageName).slice(0, 8),
+        usageContextLine: normalizeGeneratedTextNullable(formatUsageSummaryLine(facts, 2)),
+        upgradeContextLine: normalizeGeneratedTextNullable(composeContextLineFromFacts(facts, {
+            includePathSample: true,
+            maxAreas: 4,
+        })),
+    };
 }
-export function deriveScanDetailViewModel(result, options) {
-    if (!result || options.status !== "done")
+function narrativeContextFromFacts(facts) {
+    return presentScanDetailNarrativeContext(facts);
+}
+function guidanceToImpactItem(g, verifyLabels, facts) {
+    const verify = g.remediation &&
+        !verifyLabels.has(g.remediation.toLowerCase().replace(/\s+/g, " ").trim())
+        ? g.remediation
+        : undefined;
+    let where = g.context?.trim() || undefined;
+    if (!where &&
+        facts &&
+        (facts.availability.mode === "pr_intelligence" ||
+            facts.availability.tiersPresent.tier1)) {
+        where = usageWhereFromFacts(facts);
+    }
+    return {
+        message: normalizeGeneratedText(g.message),
+        where: where ? normalizeGeneratedText(where) : undefined,
+        verify: verify ? normalizeGeneratedText(verify) : undefined,
+        affectedFiles: g.affectedFiles,
+    };
+}
+function deriveOperationalImpactFromFacts(facts, result, verifyLabels) {
+    const changedGuidance = facts.reviewerGuidance.filter((g) => g.scope === "changed" || g.kind === "insight");
+    if (facts.availability.mode === "pr_intelligence" ||
+        (facts.availability.tiersPresent.tier1 && changedGuidance.length > 0)) {
+        const items = changedGuidance
+            .slice(0, 6)
+            .map((g) => guidanceToImpactItem(g, verifyLabels, facts));
+        if (items.length > 0) {
+            return { status: "rich", items };
+        }
+    }
+    if (changedGuidance.length > 0) {
+        const insightCount = Array.isArray(result.insights)
+            ? result.insights.length
+            : 0;
+        if (insightCount > TIER1_MAX_VISIBLE_IMPACTS) {
+            return deriveOperationalImpact(result, verifyLabels);
+        }
+        return {
+            status: "rich",
+            items: changedGuidance
+                .slice(0, 6)
+                .map((g) => guidanceToImpactItem(g, verifyLabels, facts)),
+        };
+    }
+    return deriveOperationalImpact(result, verifyLabels);
+}
+function themeCandidateFromLabel(label) {
+    const trimmed = label.trim();
+    if (!trimmed)
         return null;
+    return sanitizeAct2Theme(trimmed) ?? trimmed.slice(0, ACT2_MAX_THEME_CHARS);
+}
+function deriveBecauseThemesFromFacts(facts) {
+    const themes = [];
+    const seen = new Set();
+    const prIntelligence = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    const pushTheme = (raw) => {
+        if (!raw)
+            return;
+        const normalized = normalizeGeneratedText(raw);
+        const key = normalized.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        themes.push(normalized);
+    };
+    if (prIntelligence) {
+        for (const area of facts.affectedAreas) {
+            pushTheme(themeCandidateFromLabel(area.label));
+            if (themes.length >= ACT2_MAX_THEMES)
+                return themes;
+        }
+        for (const factor of facts.blastRadius?.factors ?? []) {
+            pushTheme(themeCandidateFromLabel(factor.replace(/_/g, " ")));
+            if (themes.length >= ACT2_MAX_THEMES)
+                return themes;
+        }
+        const reachLabel = labelReachabilityKind(facts);
+        if (reachLabel)
+            pushTheme(reachLabel);
+    }
+    for (const g of facts.reviewerGuidance.slice(0, ACT2_MAX_THEMES + 2)) {
+        pushTheme(sanitizeAct2Theme(g.message));
+        if (themes.length >= ACT2_MAX_THEMES)
+            return themes;
+    }
+    if (themes.length < ACT2_MAX_THEMES && !prIntelligence) {
+        for (const ctx of facts.repositoryContext) {
+            pushTheme(sanitizeAct2Theme(phraseForFamily(ctx.family)));
+            if (themes.length >= ACT2_MAX_THEMES)
+                break;
+        }
+    }
+    return themes.slice(0, ACT2_MAX_THEMES);
+}
+function deriveVerdictLineFromFacts(facts, result) {
+    const topGuidance = facts.reviewerGuidance.find((g) => (g.scope === "changed" || g.kind === "insight") && g.message.trim());
+    if (topGuidance) {
+        return truncateWithEllipsis(topGuidance.message.trim(), VERDICT_LINE_MAX_CHARS);
+    }
+    const posture = mergePostureFromDecision(result.decision?.recommendation);
+    return truncateWithEllipsis(deriveVerdictLine(posture, result.totalScore), VERDICT_LINE_MAX_CHARS);
+}
+/** Scan detail presentation from shared narrative facts. */
+export function presentScanDetailViewModel(facts, result, options) {
     const posture = mergePostureFromDecision(result.decision?.recommendation);
     const scopeChip = deriveDetailReachChip(result.totalScore);
-    const verdictLine = truncateWithEllipsis(deriveVerdictLine(posture, result.totalScore), VERDICT_LINE_MAX_CHARS);
+    const verdictLine = deriveVerdictLineFromFacts(facts, result);
+    const narrativeContext = narrativeContextFromFacts(facts);
     const recommendedActions = deriveScanDetailRecommendations(result);
     const signalSummary = deriveSignalSummary(result);
     const verifyLabels = recommendationTitlesForDedupe(recommendedActions);
-    const operationalImpact = deriveOperationalImpact(result, verifyLabels);
-    const themes = deriveAct2Themes(result);
+    const operationalImpact = deriveOperationalImpactFromFacts(facts, result, verifyLabels);
+    const themes = deriveBecauseThemesFromFacts(facts);
     const confidenceCaveat = deriveConfidenceCaveat(result);
-    const because = themes.length > 0 || confidenceCaveat
-        ? {
-            themes,
-            confidenceCaveat,
-        }
-        : null;
-    const attentionAreas = buildAttentionAreas(result);
+    const because = themes.length > 0 || confidenceCaveat ? { themes, confidenceCaveat } : null;
+    const factsAttention = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1
+        ? buildAttentionAreasFromFacts(facts)
+        : [];
+    const attentionAreas = mergeAttentionAreas(factsAttention, buildAttentionAreas(result));
     const allFindings = annotateFindingsWithCoverage(buildFindingRows(result), recommendedActions);
-    const findings = allFindings;
     const topology = buildTopology(result);
-    const hasEvidence = attentionAreas.length > 0 || allFindings.length > 0 || topology !== null;
-    const evidence = hasEvidence
-        ? {
-            attentionAreas,
-            findings,
-            findingsOverflowCount: Math.max(0, allFindings.length - ACT3_EVIDENCE_COLLAPSE_THRESHOLD),
-            topology,
-        }
-        : null;
+    const hasEvidence = attentionAreas.length > 0 || allFindings.length > 0 || topology != null;
     return {
         verdict: {
             posture,
@@ -394,17 +593,34 @@ export function deriveScanDetailViewModel(result, options) {
         recommendedActions,
         operationalImpact,
         because,
-        evidence,
+        evidence: hasEvidence
+            ? {
+                attentionAreas,
+                findings: allFindings,
+                findingsOverflowCount: Math.max(0, allFindings.length - ACT3_EVIDENCE_COLLAPSE_THRESHOLD),
+                topology,
+            }
+            : null,
         repoContext: options.repoContext ?? { status: "hidden" },
+        narrativeContext,
         metadata: {
             scanId: options.scanId,
             generatedAt: result.generatedAt,
             methodologyVersion: options.methodologyVersion,
-            changedPackagesSummary: changedPackagesSummary(result.changedPackages),
+            changedPackagesSummary: narrativeContext.changedPackagesDisplay ??
+                facts.changedPackages.primary ??
+                undefined,
             codeAnalysisTimedOut: result.codeAnalysisMetrics?.timedOut === true,
+            codeIntelligenceAvailable: facts.availability.codeIntelligenceAvailable,
         },
     };
 }
+export function deriveScanDetailViewModel(result, options) {
+    if (!result || options.status !== "done")
+        return null;
+    const facts = deriveScanNarrative(result);
+    return presentScanDetailViewModel(facts, result, options);
+}
 /** Tier 1 recall test helper — true when message describes application-level impact. */
 export function tier1PassesRecallTest(operationalImpact) {
     if (operationalImpact.status === "rich") {

package/dist/scanDetailViewModel.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { primaryPrExample } from "./productMessaging.js";
-import { ACT2_MAX_THEMES, deriveAct2Themes, deriveOperationalImpact, deriveFollowUpBridgeNote, deriveScanDetailViewModel, deriveVerdictLine, sanitizeAct2Theme, tier1PassesRecallTest, } from "./scanDetailViewModel.js";
+import { ACT2_MAX_THEMES, TIER1_MAX_VISIBLE_IMPACTS, deriveAct2Themes, deriveOperationalImpact, deriveFollowUpBridgeNote, deriveScanDetailViewModel, deriveVerdictLine, sanitizeAct2Theme, tier1PassesRecallTest, } from "./scanDetailViewModel.js";
+import { fixtureRepoIntelligenceFastify } from "./fixtures/repoIntelligenceFixtures.js";
 const baseResult = {
     totalScore: 10,
     layerScores: {
@@ -58,7 +59,7 @@ describe("reach vocabulary on fixtures", () => {
             changedPackages: Array.from({ length: 14 }, (_, i) => `pkg-${i}`),
         }, { scanId: "s2", status: "done" });
         expect(vm?.verdict.scopeChip).toBe("Wide reach");
-        expect(vm?.verdict.verdictLine).toBe("No merge blockers · wide upgrade footprint");
+        expect(vm?.verdict.verdictLine).toBe("No merge blockers - wide upgrade footprint");
     });
     it("needs review + limited reach — minimalResult score 42", () => {
         const vm = deriveScanDetailViewModel(minimalResult(), {
@@ -128,6 +129,31 @@ describe("deriveVerdictLine", () => {
     });
 });
 describe("Tier 1 success criterion", () => {
+    it("surfaces package usage paths in narrative context and evidence when corpus available", () => {
+        const vm = deriveScanDetailViewModel({
+            ...baseResult,
+            changedPackages: ["fastify"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+            insights: [
+                {
+                    type: "usage_risk",
+                    priority: "high",
+                    confidence: "confirmed",
+                    scope: "changed",
+                    message: "Fastify middleware ordering may shift",
+                    context: "",
+                    remediation: "Run auth integration tests",
+                },
+            ],
+        }, { scanId: "corpus", status: "done" });
+        expect(vm?.narrativeContext.usageHighlights.length).toBeGreaterThan(0);
+        expect(vm?.narrativeContext.usageContextLine).toMatch(/Used in/);
+        expect(vm?.narrativeContext.blastRadiusFactors.length).toBeGreaterThan(0);
+        const hotspotArea = vm?.evidence?.attentionAreas.find((a) => a.problemLabel.includes("hotspot"));
+        expect(hotspotArea?.packages[0]?.name).toBe("fastify");
+        expect(tier1PassesRecallTest(vm.operationalImpact)).toBe(true);
+    });
     it("insight-rich scan passes recall test", () => {
         const vm = deriveScanDetailViewModel({
             ...minimalResult(),
@@ -469,7 +495,7 @@ describe("scenario matrix", () => {
             scanId: "fat",
             status: "done",
         });
-        expect(vm?.operationalImpact.items.length).toBe(30);
+        expect(vm?.operationalImpact.items.length).toBeGreaterThan(TIER1_MAX_VISIBLE_IMPACTS);
         expect(vm?.evidence?.findings.length).toBe(40);
         expect(vm?.recommendedActions.items.length).toBeLessThanOrEqual(3);
         expect(vm?.recommendedActions.items[0]?.detail.whyNow.length).toBeGreaterThan(0);