@mergesignal/shared 0.2.6 → 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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +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,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

@@ -0,0 +1,370 @@
+import { extractRepositoryContextFacts } from "./extractRepositoryContextFacts.js";
+import { normalizeReachabilityKind, normalizeRuntimeSurfaceKind, parseRepoIntelligence, readBlastLevel, readReachabilityFromLoose, readSurfaceFromLoose, } 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) {
+    const all = Array.isArray(changed)
+        ? changed.map((p) => p.trim()).filter(Boolean)
+        : [];
+    return {
+        primary: all[0] ?? null,
+        others: all.slice(1),
+        all,
+    };
+}
+function blastLevelFromChangedCount(count) {
+    if (count >= 8)
+        return "wide";
+    if (count >= 3)
+        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 runtimeSurface = runtimeKind != null
+        ? {
+            kind: runtimeKind,
+            evidence: {
+                packages: primary ? [primary] : changed.all.slice(0, 3),
+                paths,
+            },
+        }
+        : null;
+    const reachability = reachKind
+        ? {
+            kind: reachKind,
+            evidence: {
+                paths,
+                frameworks,
+            },
+        }
+        : null;
+    const blastFromRi = ri.blastRadius;
+    const blastLevel = readBlastLevel(blastFromRi?.level) ??
+        (changed.all.length > 0
+            ? blastLevelFromChangedCount(changed.all.length)
+            : null);
+    const blastRadius = blastLevel
+        ? {
+            level: blastLevel,
+            changedPackageCount: blastFromRi?.changedPackageCount ?? changed.all.length,
+            factors: uniqueStrings(blastFromRi?.factors ?? []),
+        }
+        : null;
+    const areasRaw = ri.applicationAreas ?? ri.affectedAreas ?? [];
+    const affectedAreas = [];
+    for (const area of areasRaw) {
+        affectedAreas.push({ id: area.id, label: area.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 codeHotspots = collectCodeHotspots(ri, primary);
+    return {
+        packageUsage,
+        frameworks,
+        runtimeSurface,
+        reachability,
+        blastRadius,
+        affectedAreas: affectedAreas.slice(0, NARRATIVE_FACT_MAX_AREAS),
+        hotspots: codeHotspots.slice(0, NARRATIVE_FACT_MAX_HOTSPOTS),
+    };
+}
+function hasMeaningfulTier1(tier1) {
+    return (tier1.packageUsage.length > 0 ||
+        tier1.frameworks.length > 0 ||
+        tier1.runtimeSurface != null ||
+        tier1.reachability != null ||
+        tier1.blastRadius != null ||
+        tier1.affectedAreas.length > 0 ||
+        tier1.hotspots.length > 0);
+}
+function insightScope(scope) {
+    if (scope === "changed" || scope === "all")
+        return scope;
+    return "unknown";
+}
+function guidanceFromInsight(insight, index) {
+    return {
+        kind: "insight",
+        id: `insight:${index}:${insight.type}`,
+        scope: insightScope(insight.scope),
+        priority: insight.priority,
+        message: insight.message,
+        context: insight.context,
+        remediation: insight.remediation,
+        affectedFiles: insight.affectedFiles,
+    };
+}
+function guidanceFromFinding(finding) {
+    return {
+        kind: "finding",
+        id: finding.id,
+        scope: "unknown",
+        priority: finding.severity,
+        message: finding.title,
+        context: finding.description,
+        remediation: finding.recommendation,
+    };
+}
+function guidanceFromRecommendation(rec) {
+    return {
+        kind: "recommendation",
+        id: rec.id,
+        scope: "unknown",
+        priority: String(rec.priorityScore ?? rec.rank ?? "medium"),
+        message: rec.title,
+        context: rec.rationale,
+        remediation: rec.impact,
+    };
+}
+function collectReviewerGuidance(result) {
+    const guidance = [];
+    const insights = Array.isArray(result.insights) ? result.insights : [];
+    const changedFirst = [
+        ...insights.filter((i) => i.scope === "changed"),
+        ...insights.filter((i) => i.scope !== "changed"),
+    ];
+    changedFirst.forEach((insight, index) => {
+        guidance.push(guidanceFromInsight(insight, index));
+    });
+    const findings = Array.isArray(result.findings) ? result.findings : [];
+    const severityOrder = { critical: 4, high: 3, medium: 2, low: 1 };
+    const sortedFindings = [...findings].sort((a, b) => (severityOrder[b.severity] ?? 0) - (severityOrder[a.severity] ?? 0));
+    for (const finding of sortedFindings) {
+        guidance.push(guidanceFromFinding(finding));
+    }
+    const recs = Array.isArray(result.recommendations)
+        ? result.recommendations
+        : [];
+    for (const rec of recs) {
+        guidance.push(guidanceFromRecommendation(rec));
+    }
+    return guidance;
+}
+function resolveAvailabilityMode(tier1, tier2, codeIntelligenceAvailable) {
+    if (tier1 && codeIntelligenceAvailable)
+        return "pr_intelligence";
+    if (tier2)
+        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).
+ */
+export function deriveScanNarrative(result) {
+    if (!result) {
+        return { ...EMPTY_SCAN_NARRATIVE_FACTS };
+    }
+    const changedPackages = parseChangedPackages(result.changedPackages);
+    const mergePosture = mergePostureFromDecision(result.decision?.recommendation) ?? null;
+    const riskIndex = typeof result.totalScore === "number" && Number.isFinite(result.totalScore)
+        ? result.totalScore
+        : null;
+    const codeIntelligenceAvailable = result.analysisPreparation?.codeIntelligenceAvailable !== false;
+    const parsedRi = parseRepoIntelligence(result.repoIntelligence);
+    const corpusGate = codeIntelligenceAvailable && parsedRi != null;
+    let tier1Blocks = emptyTier1Blocks();
+    if (corpusGate && parsedRi) {
+        tier1Blocks = extractTier1FromRepoIntelligence(parsedRi, changedPackages);
+    }
+    else if (changedPackages.all.length > 0) {
+        tier1Blocks = {
+            ...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");
+    const repositoryContext = extractRepositoryContextFacts(result);
+    const tier3 = repositoryContext.length > 0;
+    const mode = resolveAvailabilityMode(tier1, tier2 || reviewerGuidance.length > 0, codeIntelligenceAvailable);
+    const decisionConf = result.decision?.confidence;
+    const confidence = {
+        decision: decisionConf === "low" ||
+            decisionConf === "medium" ||
+            decisionConf === "high"
+            ? decisionConf
+            : null,
+    };
+    if (!tier1 && mode === "graph_fallback" && changedPackages.all.length > 0) {
+        tier1Blocks.blastRadius = blastRadiusFromChangedCount(changedPackages.all.length);
+    }
+    let affectedAreas = tier1Blocks.affectedAreas;
+    if (affectedAreas.length === 0) {
+        affectedAreas = selectTopAffectedAreas(result, { max: 2 }).map((label) => ({
+            id: label.toLowerCase().replace(/\s+/g, "_").slice(0, 48),
+            label,
+        }));
+    }
+    return {
+        availability: {
+            mode,
+            codeIntelligenceAvailable,
+            tiersPresent: {
+                tier1,
+                tier2: reviewerGuidance.length > 0,
+                tier3,
+            },
+        },
+        changedPackages,
+        packageUsage: tier1Blocks.packageUsage,
+        frameworks: tier1Blocks.frameworks,
+        runtimeSurface: tier1Blocks.runtimeSurface,
+        reachability: tier1Blocks.reachability,
+        blastRadius: tier1Blocks.blastRadius,
+        affectedAreas,
+        hotspots: tier1Blocks.hotspots,
+        reviewerGuidance,
+        confidence,
+        repositoryContext,
+        mergePosture,
+        riskIndex,
+    };
+}
+/** @internal Test helper — normalize loose engine strings. */
+export { normalizeReachabilityKind, normalizeRuntimeSurfaceKind };

package/dist/deriveScanNarrative.test.d.ts

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

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

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