@mergesignal/shared 0.2.7 → 0.2.8

package/dist/actionsStepSummary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actionsStepSummary.d.ts","sourceRoot":"","sources":["../src/actionsStepSummary.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,SAAS,EACT,cAAc,EACd,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,aAAa,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,gDAAgD;AAChD,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,6EAA6E;AAC7E,eAAO,MAAM,8BAA8B,OAAO,CAAC;AACnD,4DAA4D;AAC5D,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAyBnD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAK3E;AAOD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6C7D;AA4ED,8GAA8G;AAC9G,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAiBf;AASD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAa3E;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,cAAc,EAAE,GACrB,cAAc,EAAE,CAelB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxE;AAaD,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAgiBD,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACpD,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GAAG,MAAM,CAoJT"}
+{"version":3,"file":"actionsStepSummary.d.ts","sourceRoot":"","sources":["../src/actionsStepSummary.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,SAAS,EACT,cAAc,EACd,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,aAAa,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,gDAAgD;AAChD,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,6EAA6E;AAC7E,eAAO,MAAM,8BAA8B,OAAO,CAAC;AACnD,4DAA4D;AAC5D,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAyBnD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAK3E;AAOD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6C7D;AA4ED,8GAA8G;AAC9G,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAiBf;AASD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAa3E;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,cAAc,EAAE,GACrB,cAAc,EAAE,CAelB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxE;AAaD,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAygBD,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACpD,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GAAG,MAAM,CAoJT"}

package/dist/actionsStepSummary.js

@@ -9,7 +9,7 @@
  * - `## Recommended actions` + time heuristics → default “what to do” + `<details> More actions`
  * - `<details> Risk breakdown` + layer table + graph one-liner → score + graph `<details>` blocks
  */
-import { deriveScanSummaryText } from "./deriveScanSummaryText.js";
+import { collectWhyBulletsFromResult } from "./collectNarrativeWhyBullets.js";
 import { formatInsight } from "./formatInsight.js";
 import { mergePostureLabel } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
@@ -516,34 +516,7 @@ function buildTrustedTitleLines(result, flat) {
     return titleLines;
 }
 function collectWhyBullets(result, max) {
-    const out = [];
-    const reasoning = result.decision?.reasoning;
-    if (Array.isArray(reasoning)) {
-        for (const r of reasoning) {
-            const s = humanizeEngineSurfaceText(String(r).trim());
-            if (s && !out.includes(s))
-                out.push(s);
-            if (out.length >= max)
-                return dedupeDriverDisplayPhrases(out).slice(0, max);
-        }
-    }
-    const reasons = result.explain?.reasons;
-    if (Array.isArray(reasons) && out.length < max) {
-        for (const r of reasons) {
-            const title = String(r?.title ?? r?.id ?? "").trim();
-            const readable = humanizeEngineSurfaceText(title);
-            if (readable && !out.includes(readable))
-                out.push(readable);
-            if (out.length >= max)
-                break;
-        }
-    }
-    if (out.length === 0) {
-        const one = deriveScanSummaryText(result);
-        if (one)
-            out.push(one);
-    }
-    return dedupeDriverDisplayPhrases(out).slice(0, max);
+    return dedupeDriverDisplayPhrases(collectWhyBulletsFromResult(result, max));
 }
 function buildWhatToDoItems(result) {
     const sortedI = sortPRInsightsForDisplay(Array.isArray(result.insights) ? result.insights : []);

package/dist/collectNarrativeWhyBullets.d.ts

@@ -0,0 +1,12 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
+import type { ScanResult } from "./types.js";
+/**
+ * Why bullets from narrative facts (tier-1/tier-2). Preferred for GitHub + Actions.
+ */
+export declare function collectWhyBulletsFromFacts(facts: ScanNarrativeFacts, max: number): string[];
+/**
+ * Legacy why bullets from raw ScanResult (fallback when facts are thin).
+ */
+export declare function collectWhyBulletsFromResult(result: ScanResult, max: number): string[];
+export declare function collectWhyBullets(facts: ScanNarrativeFacts, result: ScanResult, max: number): string[];
+//# sourceMappingURL=collectNarrativeWhyBullets.d.ts.map

package/dist/collectNarrativeWhyBullets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectNarrativeWhyBullets.d.ts","sourceRoot":"","sources":["../src/collectNarrativeWhyBullets.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS7C;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAsCV;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAwBV;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAiBV"}

package/dist/collectNarrativeWhyBullets.js

@@ -0,0 +1,104 @@
+import { deriveScanSummaryText } from "./deriveScanSummaryText.js";
+import { humanizeEngineSurfaceText, truncateWithEllipsis, } from "./actionsStepSummary.js";
+import { composeContextLineFromFacts, formatBlastRadiusDetailLine, formatUsageSummaryLine, labelReachabilityKind, selectReviewerGuidance, } from "./narrativePresentation.js";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+function pushUnique(out, line, max) {
+    const t = normalizeGeneratedText(line.trim());
+    if (!t || out.includes(t))
+        return;
+    out.push(t);
+    if (out.length > max)
+        out.length = max;
+}
+/**
+ * Why bullets from narrative facts (tier-1/tier-2). Preferred for GitHub + Actions.
+ */
+export function collectWhyBulletsFromFacts(facts, max) {
+    const prIntel = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    if (!prIntel)
+        return [];
+    const out = [];
+    if (prIntel) {
+        const context = composeContextLineFromFacts(facts, {
+            includePathSample: true,
+            maxAreas: 2,
+        });
+        if (context)
+            pushUnique(out, context, max);
+        const usage = formatUsageSummaryLine(facts, 1);
+        if (usage)
+            pushUnique(out, usage, max);
+        const blast = formatBlastRadiusDetailLine(facts, 2);
+        if (blast)
+            pushUnique(out, blast, max);
+        for (const area of facts.affectedAreas) {
+            if (out.length >= max)
+                break;
+            pushUnique(out, area.label, max);
+        }
+        const reach = labelReachabilityKind(facts);
+        if (reach)
+            pushUnique(out, reach, max);
+    }
+    if (out.length < max) {
+        for (const g of selectReviewerGuidance(facts, { max: max - out.length })) {
+            if (out.length >= max)
+                break;
+            pushUnique(out, truncateWithEllipsis(g.message.trim(), 200), max);
+        }
+    }
+    return out.slice(0, max);
+}
+/**
+ * Legacy why bullets from raw ScanResult (fallback when facts are thin).
+ */
+export function collectWhyBulletsFromResult(result, max) {
+    const out = [];
+    const reasoning = result.decision?.reasoning;
+    if (Array.isArray(reasoning)) {
+        for (const r of reasoning) {
+            const s = humanizeEngineSurfaceText(String(r).trim());
+            if (s)
+                pushUnique(out, s, max);
+            if (out.length >= max)
+                return out.slice(0, max);
+        }
+    }
+    const reasons = result.explain?.reasons;
+    if (Array.isArray(reasons) && out.length < max) {
+        for (const r of reasons) {
+            const title = String(r?.title ?? r?.id ?? "").trim();
+            const readable = humanizeEngineSurfaceText(title);
+            if (readable)
+                pushUnique(out, readable, max);
+            if (out.length >= max)
+                break;
+        }
+    }
+    if (out.length === 0) {
+        const one = deriveScanSummaryText(result);
+        if (one)
+            pushUnique(out, one, max);
+    }
+    return out.slice(0, max);
+}
+export function collectWhyBullets(facts, result, max) {
+    const fromFacts = collectWhyBulletsFromFacts(facts, max);
+    if (fromFacts.length >= max)
+        return fromFacts;
+    if (facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1) {
+        return fromFacts;
+    }
+    const legacy = collectWhyBulletsFromResult(result, max);
+    if (fromFacts.length === 0)
+        return legacy;
+    const merged = [...fromFacts];
+    for (const line of legacy) {
+        pushUnique(merged, line, max);
+        if (merged.length >= max)
+            break;
+    }
+    return merged.slice(0, max);
+}

package/dist/deriveScanNarrative.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deriveScanNarrative.d.ts","sourceRoot":"","sources":["../src/deriveScanNarrative.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAM5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAQL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAIV,UAAU,EACX,MAAM,YAAY,CAAC;AAqPpB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACpC,kBAAkB,CA8GpB;AAED,8DAA8D;AAC9D,OAAO,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,CAAC"}
+{"version":3,"file":"deriveScanNarrative.d.ts","sourceRoot":"","sources":["../src/deriveScanNarrative.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAM5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAYL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAKV,UAAU,EACX,MAAM,YAAY,CAAC;AAkZpB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACpC,kBAAkB,CAiGpB;AAED,8DAA8D;AAC9D,OAAO,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,CAAC"}

package/dist/deriveScanNarrative.js

@@ -1,6 +1,6 @@
 import { extractRepositoryContextFacts } from "./extractRepositoryContextFacts.js";
 import { normalizeReachabilityKind, normalizeRuntimeSurfaceKind, parseRepoIntelligence, readBlastLevel, readReachabilityFromLoose, readSurfaceFromLoose, } from "./repoIntelligenceSchema.js";
-import { EMPTY_SCAN_NARRATIVE_FACTS, } from "./scanNarrativeFacts.js";
+import { EMPTY_SCAN_NARRATIVE_FACTS, NARRATIVE_FACT_MAX_AREAS, NARRATIVE_FACT_MAX_HOTSPOTS, NARRATIVE_FACT_MAX_PATHS, } from "./scanNarrativeFacts.js";
 import { mergePostureFromDecision } from "./riskVocabulary.js";
 import { selectTopAffectedAreas } from "./selectTopAffectedAreas.js";
 function parseChangedPackages(changed) {
@@ -20,28 +20,132 @@ function blastLevelFromChangedCount(count) {
         return "moderate";
     return "narrow";
 }
+function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const v of values) {
+        const t = v.trim();
+        if (!t || seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}
+function usageEntryPackageName(entry) {
+    const name = (entry.packageName ?? entry.package ?? "").trim();
+    return name || null;
+}
+function collectPackageUsageForChanged(ri, changed) {
+    const byPackage = new Map();
+    const ensure = (packageName) => {
+        let row = byPackage.get(packageName);
+        if (!row) {
+            row = {
+                packageName,
+                paths: [],
+                criticalPaths: [],
+                files: [],
+                areas: [],
+            };
+            byPackage.set(packageName, row);
+        }
+        return row;
+    };
+    const mergeEntry = (entry, packageNameOverride) => {
+        const name = packageNameOverride ?? usageEntryPackageName(entry);
+        if (!name || !changed.all.includes(name))
+            return;
+        const row = ensure(name);
+        row.paths = uniqueStrings([...row.paths, ...(entry.paths ?? [])]);
+        row.criticalPaths = uniqueStrings([
+            ...row.criticalPaths,
+            ...(entry.criticalPaths ?? []),
+        ]);
+        row.files = uniqueStrings([...row.files, ...(entry.files ?? [])]);
+        row.areas = uniqueStrings([...row.areas, ...(entry.areas ?? [])]);
+    };
+    for (const name of changed.all) {
+        const pkgIntel = ri.packages?.[name];
+        if (pkgIntel?.usage)
+            mergeEntry(pkgIntel.usage, name);
+        if (pkgIntel?.packageUsage)
+            mergeEntry(pkgIntel.packageUsage, name);
+        if (pkgIntel?.areas?.length) {
+            const row = ensure(name);
+            row.areas = uniqueStrings([...row.areas, ...pkgIntel.areas]);
+        }
+    }
+    if (Array.isArray(ri.packageUsage)) {
+        for (const entry of ri.packageUsage) {
+            mergeEntry(entry);
+        }
+    }
+    return changed.all
+        .map((name) => byPackage.get(name))
+        .filter((row) => row != null);
+}
+function allUsagePaths(usage) {
+    const paths = [];
+    for (const row of usage) {
+        paths.push(...row.paths, ...row.criticalPaths, ...row.files);
+    }
+    return uniqueStrings(paths).slice(0, NARRATIVE_FACT_MAX_PATHS);
+}
+function collectFrameworks(ri) {
+    return uniqueStrings(ri.frameworks ?? []);
+}
+function collectCodeHotspots(ri, primary) {
+    const hotspots = [];
+    const pkgIntel = primary && ri.packages?.[primary] ? ri.packages[primary] : undefined;
+    const riHotspots = ri.hotspots ?? pkgIntel?.hotspots ?? [];
+    for (const h of riHotspots) {
+        const name = (h.packageName ?? primary ?? "").trim();
+        if (!name)
+            continue;
+        hotspots.push({
+            packageName: name,
+            source: h.source === "graph" ? "graph" : "code",
+            depth: h.depth,
+            paths: uniqueStrings(h.paths ?? []),
+        });
+    }
+    return hotspots;
+}
+function mergeGraphHotspots(codeHotspots, graphHotspots) {
+    const byName = new Map();
+    for (const h of codeHotspots) {
+        byName.set(h.packageName, h);
+    }
+    for (const g of graphHotspots ?? []) {
+        const name = g.packageName?.trim();
+        if (!name || byName.has(name))
+            continue;
+        byName.set(name, {
+            packageName: name,
+            source: "graph",
+            depth: g.depth,
+            paths: [],
+        });
+    }
+    return [...byName.values()].slice(0, NARRATIVE_FACT_MAX_HOTSPOTS);
+}
 function extractTier1FromRepoIntelligence(ri, changed) {
     const primary = changed.primary;
     const pkgIntel = primary && ri.packages?.[primary] ? ri.packages[primary] : undefined;
+    const packageUsage = collectPackageUsageForChanged(ri, changed);
+    const frameworks = collectFrameworks(ri);
+    const paths = allUsagePaths(packageUsage);
     const runtimeRaw = pkgIntel?.runtimeSurface ?? ri.runtimeSurface ?? undefined;
     const reachRaw = pkgIntel?.reachability ?? ri.reachability ?? undefined;
     const runtimeKind = readSurfaceFromLoose(runtimeRaw) ?? (primary ? "unknown" : null);
     const reachKind = readReachabilityFromLoose(reachRaw);
-    const usageEntry = pkgIntel?.usage ??
-        pkgIntel?.packageUsage ??
-        ri.packageUsage?.find((u) => (u.packageName ?? u.package) === primary ||
-            changed.all.includes(u.packageName ?? u.package ?? ""));
-    const paths = [
-        ...(usageEntry?.paths ?? []),
-        ...(usageEntry?.criticalPaths ?? []),
-        ...(usageEntry?.files ?? []),
-    ].filter(Boolean);
     const runtimeSurface = runtimeKind != null
         ? {
             kind: runtimeKind,
             evidence: {
                 packages: primary ? [primary] : changed.all.slice(0, 3),
-                paths: paths.length > 0 ? paths.slice(0, 8) : undefined,
+                paths,
             },
         }
         : null;
@@ -49,8 +153,8 @@ function extractTier1FromRepoIntelligence(ri, changed) {
         ? {
             kind: reachKind,
             evidence: {
-                paths: paths.length > 0 ? paths.slice(0, 8) : undefined,
-                frameworks: ri.frameworks?.length ? ri.frameworks : undefined,
+                paths,
+                frameworks,
             },
         }
         : null;
@@ -63,44 +167,37 @@ function extractTier1FromRepoIntelligence(ri, changed) {
         ? {
             level: blastLevel,
             changedPackageCount: blastFromRi?.changedPackageCount ?? changed.all.length,
-            factors: blastFromRi?.factors,
+            factors: uniqueStrings(blastFromRi?.factors ?? []),
         }
         : null;
     const areasRaw = ri.applicationAreas ?? ri.affectedAreas ?? [];
-    const usageAreas = usageEntry?.areas ?? pkgIntel?.areas ?? [];
     const affectedAreas = [];
     for (const area of areasRaw) {
         affectedAreas.push({ id: area.id, label: area.label });
     }
-    for (const label of usageAreas) {
-        const id = label.toLowerCase().replace(/\s+/g, "_");
-        if (!affectedAreas.some((a) => a.id === id)) {
-            affectedAreas.push({ id, label });
+    for (const row of packageUsage) {
+        for (const label of row.areas) {
+            const id = label.toLowerCase().replace(/\s+/g, "_");
+            if (!affectedAreas.some((a) => a.id === id)) {
+                affectedAreas.push({ id, label });
+            }
         }
     }
-    const hotspots = [];
-    const riHotspots = ri.hotspots ?? pkgIntel?.hotspots ?? [];
-    for (const h of riHotspots) {
-        const name = h.packageName ?? primary;
-        if (!name)
-            continue;
-        hotspots.push({
-            packageName: name,
-            source: h.source === "graph" ? "graph" : "code",
-            depth: h.depth,
-            paths: h.paths,
-        });
-    }
+    const codeHotspots = collectCodeHotspots(ri, primary);
     return {
+        packageUsage,
+        frameworks,
         runtimeSurface,
         reachability,
         blastRadius,
-        affectedAreas: affectedAreas.slice(0, 6),
-        hotspots: hotspots.slice(0, 8),
+        affectedAreas: affectedAreas.slice(0, NARRATIVE_FACT_MAX_AREAS),
+        hotspots: codeHotspots.slice(0, NARRATIVE_FACT_MAX_HOTSPOTS),
     };
 }
 function hasMeaningfulTier1(tier1) {
-    return (tier1.runtimeSurface != null ||
+    return (tier1.packageUsage.length > 0 ||
+        tier1.frameworks.length > 0 ||
+        tier1.runtimeSurface != null ||
         tier1.reachability != null ||
         tier1.blastRadius != null ||
         tier1.affectedAreas.length > 0 ||
@@ -176,6 +273,24 @@ function resolveAvailabilityMode(tier1, tier2, codeIntelligenceAvailable) {
         return "insights";
     return "graph_fallback";
 }
+function emptyTier1Blocks() {
+    return {
+        packageUsage: [],
+        frameworks: [],
+        runtimeSurface: null,
+        reachability: null,
+        blastRadius: null,
+        affectedAreas: [],
+        hotspots: [],
+    };
+}
+function blastRadiusFromChangedCount(count) {
+    return {
+        level: blastLevelFromChangedCount(count),
+        changedPackageCount: count,
+        factors: [],
+    };
+}
 /**
  * Consumer-agnostic scan intelligence — structured facts only (no UI copy).
  */
@@ -191,28 +306,17 @@ export function deriveScanNarrative(result) {
     const codeIntelligenceAvailable = result.analysisPreparation?.codeIntelligenceAvailable !== false;
     const parsedRi = parseRepoIntelligence(result.repoIntelligence);
     const corpusGate = codeIntelligenceAvailable && parsedRi != null;
-    let tier1Blocks = {
-        runtimeSurface: null,
-        reachability: null,
-        blastRadius: null,
-        affectedAreas: [],
-        hotspots: [],
-    };
+    let tier1Blocks = emptyTier1Blocks();
     if (corpusGate && parsedRi) {
         tier1Blocks = extractTier1FromRepoIntelligence(parsedRi, changedPackages);
     }
     else if (changedPackages.all.length > 0) {
         tier1Blocks = {
-            runtimeSurface: null,
-            reachability: null,
-            blastRadius: {
-                level: blastLevelFromChangedCount(changedPackages.all.length),
-                changedPackageCount: changedPackages.all.length,
-            },
-            affectedAreas: [],
-            hotspots: [],
+            ...emptyTier1Blocks(),
+            blastRadius: blastRadiusFromChangedCount(changedPackages.all.length),
         };
     }
+    tier1Blocks.hotspots = mergeGraphHotspots(tier1Blocks.hotspots, result.graphInsights?.hotspots);
     const tier1 = corpusGate && hasMeaningfulTier1(tier1Blocks);
     const reviewerGuidance = collectReviewerGuidance(result);
     const tier2 = reviewerGuidance.some((g) => g.scope === "changed" || g.kind === "insight");
@@ -228,10 +332,7 @@ export function deriveScanNarrative(result) {
             : null,
     };
     if (!tier1 && mode === "graph_fallback" && changedPackages.all.length > 0) {
-        tier1Blocks.blastRadius = {
-            level: blastLevelFromChangedCount(changedPackages.all.length),
-            changedPackageCount: changedPackages.all.length,
-        };
+        tier1Blocks.blastRadius = blastRadiusFromChangedCount(changedPackages.all.length);
     }
     let affectedAreas = tier1Blocks.affectedAreas;
     if (affectedAreas.length === 0) {
@@ -251,6 +352,8 @@ export function deriveScanNarrative(result) {
             },
         },
         changedPackages,
+        packageUsage: tier1Blocks.packageUsage,
+        frameworks: tier1Blocks.frameworks,
         runtimeSurface: tier1Blocks.runtimeSurface,
         reachability: tier1Blocks.reachability,
         blastRadius: tier1Blocks.blastRadius,

package/dist/deriveScanNarrative.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { deriveScanNarrative } from "./deriveScanNarrative.js";
-import { fixtureRepoIntelligenceEmpty, fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceTypescript, } from "./fixtures/repoIntelligenceFixtures.js";
+import { fixtureRepoIntelligenceEmpty, fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceMultiPackage, fixtureRepoIntelligenceTypescript, } from "./fixtures/repoIntelligenceFixtures.js";
 const baseResult = {
     totalScore: 10,
     layerScores: {
@@ -96,6 +96,61 @@ describe("deriveScanNarrative", () => {
         expect(facts.reachability?.kind).toBe("build_only");
         expect(facts.blastRadius?.level).toBe("narrow");
     });
+    it("extracts packageUsage for all changed packages with blast factors and frameworks", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["lodash", "axios"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceMultiPackage,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.packageUsage).toHaveLength(2);
+        expect(facts.packageUsage.map((u) => u.packageName)).toEqual([
+            "lodash",
+            "axios",
+        ]);
+        expect(facts.packageUsage[0]?.paths).toContain("apps/billing/export.ts");
+        expect(facts.blastRadius?.factors).toEqual([
+            "multiple_runtime_consumers",
+            "shared_middleware",
+        ]);
+        expect(facts.frameworks).toEqual(["express", "react"]);
+        expect(facts.reachability?.evidence.frameworks).toEqual([
+            "express",
+            "react",
+        ]);
+    });
+    it("merges graph hotspots without duplicating code hotspots", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["fastify"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+            graphInsights: {
+                maxDepth: 3,
+                nodes: 10,
+                edges: 12,
+                hotspots: [
+                    {
+                        kind: "hotspot",
+                        packageName: "fastify",
+                        direct: true,
+                        depth: 2,
+                    },
+                    {
+                        kind: "hotspot",
+                        packageName: "transitive-only-pkg",
+                        direct: false,
+                        depth: 4,
+                    },
+                ],
+            },
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.hotspots.map((h) => h.packageName)).toContain("fastify");
+        expect(facts.hotspots.map((h) => h.packageName)).toContain("transitive-only-pkg");
+        expect(facts.hotspots.filter((h) => h.packageName === "fastify")).toHaveLength(1);
+    });
     it("treats empty packages-only repoIntelligence as absent", () => {
         const result = {
             ...baseResult,

package/dist/fixtures/repoIntelligenceFixtures.d.ts

@@ -5,4 +5,6 @@ export declare const fixtureRepoIntelligenceFastify: RepoIntelligence;
 export declare const fixtureRepoIntelligenceTypescript: RepoIntelligence;
 /** Empty corpus stub (engine-test-fixture default). */
 export declare const fixtureRepoIntelligenceEmpty: RepoIntelligence;
+/** Multi-package PR with distinct usage per package. */
+export declare const fixtureRepoIntelligenceMultiPackage: RepoIntelligence;
 //# sourceMappingURL=repoIntelligenceFixtures.d.ts.map

package/dist/fixtures/repoIntelligenceFixtures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repoIntelligenceFixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/repoIntelligenceFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,iEAAiE;AACjE,eAAO,MAAM,8BAA8B,EAAE,gBA8B5C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,iCAAiC,EAAE,gBAS/C,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,4BAA4B,EAAE,gBAE1C,CAAC"}
+{"version":3,"file":"repoIntelligenceFixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/repoIntelligenceFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,iEAAiE;AACjE,eAAO,MAAM,8BAA8B,EAAE,gBA8B5C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,iCAAiC,EAAE,gBAS/C,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,4BAA4B,EAAE,gBAE1C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,mCAAmC,EAAE,gBA4CjD,CAAC"}

package/dist/fixtures/repoIntelligenceFixtures.js

@@ -45,3 +45,49 @@ export const fixtureRepoIntelligenceTypescript = {
 export const fixtureRepoIntelligenceEmpty = {
     packages: {},
 };
+/** Multi-package PR with distinct usage per package. */
+export const fixtureRepoIntelligenceMultiPackage = {
+    packages: {
+        lodash: {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            usage: {
+                packageName: "lodash",
+                paths: ["apps/billing/export.ts"],
+                areas: ["Billing"],
+            },
+        },
+        axios: {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            usage: {
+                packageName: "axios",
+                paths: ["apps/api/client.ts"],
+                areas: ["API"],
+            },
+        },
+    },
+    packageUsage: [
+        {
+            packageName: "lodash",
+            paths: ["apps/billing/export.ts"],
+        },
+        {
+            packageName: "axios",
+            paths: ["apps/api/client.ts"],
+        },
+    ],
+    blastRadius: {
+        level: "moderate",
+        factors: ["multiple_runtime_consumers", "shared_middleware"],
+        changedPackageCount: 2,
+    },
+    frameworks: ["express", "react"],
+    hotspots: [
+        {
+            packageName: "lodash",
+            source: "code",
+            paths: ["apps/billing/export.ts"],
+        },
+    ],
+};

package/dist/formatInsight.d.ts

@@ -1,4 +1,4 @@
-import type { PRInsight, PRDecision, PRDecisionRecommendation } from "./types.js";
+import type { PRInsight, PRDecisionRecommendation } from "./types.js";
 export type FormattedInsight = {
     message: string;
     where: string;
@@ -6,5 +6,5 @@ export type FormattedInsight = {
 };
 export declare function decisionTitle(recommendation: PRDecisionRecommendation): string;
 export declare function formatInsight(insight: PRInsight): FormattedInsight;
-export declare function renderInsightsAsMarkdown(insights: PRInsight[], decision: PRDecision): string;
+export { renderInsightsAsMarkdown } from "./presentGitHubPrComment.js";
 //# sourceMappingURL=formatInsight.d.ts.map

package/dist/formatInsight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatInsight.d.ts","sourceRoot":"","sources":["../src/formatInsight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AASF,wBAAgB,aAAa,CAC3B,cAAc,EAAE,wBAAwB,GACvC,MAAM,CAER;AAgBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAMlE;AAkBD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,EAAE,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAMR"}
+{"version":3,"file":"formatInsight.d.ts","sourceRoot":"","sources":["../src/formatInsight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AASF,wBAAgB,aAAa,CAC3B,cAAc,EAAE,wBAAwB,GACvC,MAAM,CAER;AAgBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAMlE;AAiBD,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/formatInsight.js

@@ -1,7 +1,7 @@
 const DECISION_TITLES = {
     safe: "No significant dependency risks detected",
     needs_review: "Elevated dependency merge risk",
-    risky: "Merge blocked — critical dependency risk",
+    risky: "Merge blocked - critical dependency risk",
 };
 // Title rendered once per PR comment, not per insight
 export function decisionTitle(recommendation) {
@@ -41,9 +41,4 @@ function renderInsightAsMarkdown(f) {
         f.action,
     ].join("\n");
 }
-// Renders a full PR comment: one bold title + all insights separated by dividers
-export function renderInsightsAsMarkdown(insights, decision) {
-    const title = `**${decisionTitle(decision.recommendation)}**`;
-    const blocks = insights.map((insight) => renderInsightAsMarkdown(formatInsight(insight)));
-    return [title, "", ...blocks].join("\n\n---\n\n").trimEnd();
-}
+export { renderInsightsAsMarkdown } from "./presentGitHubPrComment.js";

package/dist/formatInsight.test.js

@@ -88,7 +88,7 @@ describe("renderInsightsAsMarkdown", () => {
             remediation: "fix text",
         });
         const output = renderInsightsAsMarkdown([insight], decision);
-        expect(output).toContain("Elevated dependency merge risk");
+        expect(output).toContain("Needs review");
         expect(output).toContain("msg text");
         expect(output).toContain("ctx text");
         expect(output).toContain("fix text");