@mergesignal/shared 0.2.7 → 0.3.0

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

@@ -1,10 +1,7 @@
-import { normalizeReachabilityKind, normalizeRuntimeSurfaceKind } from "./repoIntelligenceSchema.js";
 import { type ScanNarrativeFacts } from "./scanNarrativeFacts.js";
 import type { ScanResult } from "./types.js";
 /**
  * Consumer-agnostic scan intelligence — structured facts only (no UI copy).
  */
 export declare function deriveScanNarrative(result: ScanResult | null | undefined): ScanNarrativeFacts;
-/** @internal Test helper — normalize loose engine strings. */
-export { normalizeReachabilityKind, normalizeRuntimeSurfaceKind };
 //# sourceMappingURL=deriveScanNarrative.d.ts.map

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":"AAMA,OAAO,EAaL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAKV,UAAU,EACX,MAAM,YAAY,CAAC;AAgapB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACpC,kBAAkB,CAsGpB"}

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 { readBlastLevel, safeParseRepoIntelligence, } from "./repoIntelligenceSchema.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,124 @@ 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 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 ?? entry.packageName.trim();
+        if (!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?.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 ?? [];
+    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 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 packageUsage = collectPackageUsageForChanged(ri, changed);
+    const frameworks = collectFrameworks(ri);
+    const paths = allUsagePaths(packageUsage);
+    const runtimeKind = pkgIntel?.runtimeSurface ?? null;
+    const reachKind = pkgIntel?.reachability ?? null;
     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 +145,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 +159,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 +265,42 @@ 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: [],
+    };
+}
+function resolveTrustedRepoIntelligence(result) {
+    const raw = result.repoIntelligence;
+    const validationStatus = result.analysisPreparation?.repoIntelligenceValidation?.status;
+    if (raw == null) {
+        return { parsed: null, parseStatus: "absent" };
+    }
+    if (validationStatus === "invalid") {
+        return { parsed: null, parseStatus: "untrusted" };
+    }
+    if (validationStatus !== "valid") {
+        return { parsed: null, parseStatus: "absent" };
+    }
+    const parsed = safeParseRepoIntelligence(raw);
+    if (parsed.ok) {
+        return { parsed: parsed.value, parseStatus: "ok" };
+    }
+    return { parsed: null, parseStatus: "invalid" };
+}
 /**
  * Consumer-agnostic scan intelligence — structured facts only (no UI copy).
  */
@@ -189,30 +314,21 @@ export function deriveScanNarrative(result) {
         ? result.totalScore
         : null;
     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: [],
-    };
+    const { parsed: parsedRi, parseStatus: repoIntelligenceParse } = resolveTrustedRepoIntelligence(result);
+    const corpusGate = codeIntelligenceAvailable &&
+        repoIntelligenceParse === "ok" &&
+        parsedRi != null;
+    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 +344,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) {
@@ -249,8 +362,11 @@ export function deriveScanNarrative(result) {
                 tier2: reviewerGuidance.length > 0,
                 tier3,
             },
+            repoIntelligenceParse,
         },
         changedPackages,
+        packageUsage: tier1Blocks.packageUsage,
+        frameworks: tier1Blocks.frameworks,
         runtimeSurface: tier1Blocks.runtimeSurface,
         reachability: tier1Blocks.reachability,
         blastRadius: tier1Blocks.blastRadius,
@@ -263,5 +379,3 @@ export function deriveScanNarrative(result) {
         riskIndex,
     };
 }
-/** @internal Test helper — normalize loose engine strings. */
-export { normalizeReachabilityKind, normalizeRuntimeSurfaceKind };

package/dist/deriveScanNarrative.test.js

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import { deriveScanNarrative } from "./deriveScanNarrative.js";
-import { fixtureRepoIntelligenceEmpty, fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceTypescript, } from "./fixtures/repoIntelligenceFixtures.js";
+import { legacyEngineRepoIntelligenceJwt } from "./fixtures/legacyEngineRepoIntelligence.js";
+import { fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceMultiPackage, fixtureRepoIntelligenceTypescript, } from "./fixtures/repoIntelligenceFixtures.js";
+import { analysisPreparationWithInvalidRepoIntel, analysisPreparationWithValidRepoIntel, } from "./fixtures/repoIntelligenceTestHelpers.js";
 const baseResult = {
     totalScore: 10,
     layerScores: {
@@ -18,15 +20,42 @@ describe("deriveScanNarrative", () => {
         expect(facts.availability.mode).toBe("denormalized");
         expect(facts.changedPackages.all).toEqual([]);
     });
+    it("ignores repoIntelligence when validation status is not valid", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["fastify"],
+            analysisPreparation: {
+                codeIntelligenceAvailable: true,
+                warnings: [],
+            },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.repoIntelligenceParse).toBe("absent");
+        expect(facts.availability.tiersPresent.tier1).toBe(false);
+    });
+    it("treats worker-invalid repoIntelligence as untrusted (raw retained, not consumed)", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["jsonwebtoken"],
+            analysisPreparation: analysisPreparationWithInvalidRepoIntel(),
+            repoIntelligence: legacyEngineRepoIntelligenceJwt,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.repoIntelligenceParse).toBe("untrusted");
+        expect(facts.availability.tiersPresent.tier1).toBe(false);
+        expect(facts.packageUsage).toHaveLength(0);
+    });
     it("populates tier1 from repoIntelligence when corpus available", () => {
         const result = {
             ...baseResult,
             changedPackages: ["fastify"],
-            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            analysisPreparation: analysisPreparationWithValidRepoIntel(),
             repoIntelligence: fixtureRepoIntelligenceFastify,
         };
         const facts = deriveScanNarrative(result);
         expect(facts.availability.mode).toBe("pr_intelligence");
+        expect(facts.availability.repoIntelligenceParse).toBe("ok");
         expect(facts.availability.codeIntelligenceAvailable).toBe(true);
         expect(facts.changedPackages.primary).toBe("fastify");
         expect(facts.runtimeSurface?.kind).toBe("runtime");
@@ -87,7 +116,7 @@ describe("deriveScanNarrative", () => {
         const result = {
             ...baseResult,
             changedPackages: ["typescript"],
-            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            analysisPreparation: analysisPreparationWithValidRepoIntel(),
             repoIntelligence: fixtureRepoIntelligenceTypescript,
         };
         const facts = deriveScanNarrative(result);
@@ -96,14 +125,69 @@ describe("deriveScanNarrative", () => {
         expect(facts.reachability?.kind).toBe("build_only");
         expect(facts.blastRadius?.level).toBe("narrow");
     });
-    it("treats empty packages-only repoIntelligence as absent", () => {
+    it("extracts packageUsage for all changed packages with blast factors and frameworks", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["lodash", "axios"],
+            analysisPreparation: analysisPreparationWithValidRepoIntel(),
+            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: analysisPreparationWithValidRepoIntel(),
+            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("does not tier1 when repoIntelligence block is omitted", () => {
         const result = {
             ...baseResult,
             changedPackages: ["react"],
-            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
-            repoIntelligence: fixtureRepoIntelligenceEmpty,
+            analysisPreparation: analysisPreparationWithValidRepoIntel(),
         };
         const facts = deriveScanNarrative(result);
+        expect(facts.availability.repoIntelligenceParse).toBe("absent");
         expect(facts.availability.tiersPresent.tier1).toBe(false);
     });
 });

package/dist/engineWireRegression.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engineWireRegression.test.d.ts.map

package/dist/engineWireRegression.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineWireRegression.test.d.ts","sourceRoot":"","sources":["../src/engineWireRegression.test.ts"],"names":[],"mappings":""}