@mergesignal/shared 0.2.6 → 0.2.8

package/dist/deriveScanNarrative.test.js

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { fixtureRepoIntelligenceEmpty, fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceMultiPackage, fixtureRepoIntelligenceTypescript, } from "./fixtures/repoIntelligenceFixtures.js";
+const baseResult = {
+    totalScore: 10,
+    layerScores: {
+        security: 1,
+        maintainability: 2,
+        ecosystem: 3,
+        upgradeImpact: 4,
+    },
+    findings: [],
+    generatedAt: "2026-01-01T00:00:00.000Z",
+};
+describe("deriveScanNarrative", () => {
+    it("returns denormalized empty facts for null result", () => {
+        const facts = deriveScanNarrative(null);
+        expect(facts.availability.mode).toBe("denormalized");
+        expect(facts.changedPackages.all).toEqual([]);
+    });
+    it("populates tier1 from repoIntelligence when corpus available", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["fastify"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.mode).toBe("pr_intelligence");
+        expect(facts.availability.codeIntelligenceAvailable).toBe(true);
+        expect(facts.changedPackages.primary).toBe("fastify");
+        expect(facts.runtimeSurface?.kind).toBe("runtime");
+        expect(facts.reachability?.kind).toBe("on_runtime_paths");
+        expect(facts.blastRadius?.level).toBe("moderate");
+        expect(facts.affectedAreas.map((a) => a.id)).toContain("api");
+        expect(facts.hotspots[0]?.source).toBe("code");
+    });
+    it("prefers changed-scope insights for reviewer guidance ordering", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["lodash"],
+            insights: [
+                {
+                    type: "dependency_risk",
+                    priority: "medium",
+                    confidence: "likely",
+                    scope: "all",
+                    message: "Repository-wide duplicate paths",
+                    context: "c",
+                    remediation: "r",
+                },
+                {
+                    type: "usage_risk",
+                    priority: "high",
+                    confidence: "confirmed",
+                    scope: "changed",
+                    message: "lodash used in billing export",
+                    context: "c2",
+                    remediation: "r2",
+                },
+            ],
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.reviewerGuidance[0]?.scope).toBe("changed");
+        expect(facts.reviewerGuidance[0]?.message).toContain("billing");
+    });
+    it("uses graph_fallback with structured repository context", () => {
+        const result = {
+            ...baseResult,
+            explain: {
+                reasons: [
+                    {
+                        id: "1",
+                        layer: "ecosystem",
+                        title: "graph.transitive volume",
+                        scoreImpact: 18,
+                    },
+                ],
+            },
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.mode).toBe("graph_fallback");
+        expect(facts.repositoryContext.length).toBeGreaterThan(0);
+        expect(facts.repositoryContext[0]?.family).toBe("transitive_volume");
+    });
+    it("populates build-only runtime surface from repoIntelligence", () => {
+        const result = {
+            ...baseResult,
+            changedPackages: ["typescript"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceTypescript,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.mode).toBe("pr_intelligence");
+        expect(facts.runtimeSurface?.kind).toBe("build");
+        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,
+            changedPackages: ["react"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceEmpty,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.tiersPresent.tier1).toBe(false);
+    });
+});

package/dist/extractRepositoryContextFacts.d.ts

@@ -0,0 +1,16 @@
+import { type ObservationSignalFamily } from "./cardObservationCatalog.js";
+import type { RepositoryContextSource } from "./scanNarrativeFacts.js";
+import type { ScanResult } from "./types.js";
+export type RepositoryContextFact = {
+    family: ObservationSignalFamily;
+    source: RepositoryContextSource;
+    refs?: {
+        packageNames?: string[];
+        metric?: Record<string, number>;
+    };
+};
+/**
+ * Tier 3 structured signal refs for the intelligence layer (no catalog phrases).
+ */
+export declare function extractRepositoryContextFacts(result: ScanResult): RepositoryContextFact[];
+//# sourceMappingURL=extractRepositoryContextFacts.d.ts.map

package/dist/extractRepositoryContextFacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractRepositoryContextFacts.d.ts","sourceRoot":"","sources":["../src/extractRepositoryContextFacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,uBAAuB,CAAC;IAChC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CACrE,CAAC;AAYF;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,UAAU,GACjB,qBAAqB,EAAE,CAiEzB"}

package/dist/extractRepositoryContextFacts.js

@@ -0,0 +1,71 @@
+import { mapExplainReasonToCatalogPhrase, mapFindingToCatalogPhrase, mapGraphInsightsToCatalogPhrases, mapRecommendationToCatalogPhrase, matchSignalFamily, } from "./cardObservationCatalog.js";
+function addFact(bucket, seen, fact) {
+    if (seen.has(fact.family))
+        return;
+    seen.add(fact.family);
+    bucket.push(fact);
+}
+/**
+ * Tier 3 structured signal refs for the intelligence layer (no catalog phrases).
+ */
+export function extractRepositoryContextFacts(result) {
+    const facts = [];
+    const seen = new Set();
+    const gi = result.graphInsights;
+    if (gi && typeof gi === "object") {
+        for (const { family } of mapGraphInsightsToCatalogPhrases(gi)) {
+            const metric = {};
+            if (typeof gi.nodes === "number")
+                metric.nodes = gi.nodes;
+            if (typeof gi.maxDepth === "number")
+                metric.maxDepth = gi.maxDepth;
+            const vuln = Array.isArray(gi.vulnerable) ? gi.vulnerable : [];
+            const hotspots = Array.isArray(gi.hotspots) ? gi.hotspots : [];
+            addFact(facts, seen, {
+                family,
+                source: "graphInsights",
+                refs: {
+                    packageNames: [
+                        ...vuln.map((v) => v.packageName),
+                        ...hotspots.map((h) => h.packageName),
+                    ].slice(0, 12),
+                    metric: Object.keys(metric).length > 0 ? metric : undefined,
+                },
+            });
+        }
+    }
+    if (Array.isArray(result.explain?.reasons)) {
+        for (const reason of result.explain.reasons) {
+            const mapped = mapExplainReasonToCatalogPhrase(reason);
+            if (!mapped) {
+                const family = matchSignalFamily(`${reason.id} ${reason.title} ${reason.layer}`);
+                if (family) {
+                    addFact(facts, seen, { family, source: "explain" });
+                }
+                continue;
+            }
+            addFact(facts, seen, { family: mapped.family, source: "explain" });
+        }
+    }
+    if (Array.isArray(result.findings)) {
+        for (const finding of result.findings) {
+            const mapped = mapFindingToCatalogPhrase(finding);
+            if (mapped) {
+                addFact(facts, seen, {
+                    family: mapped.family,
+                    source: "finding",
+                    refs: { packageNames: [finding.packageName] },
+                });
+            }
+        }
+    }
+    if (Array.isArray(result.recommendations)) {
+        for (const rec of result.recommendations) {
+            const mapped = mapRecommendationToCatalogPhrase(rec);
+            if (mapped) {
+                addFact(facts, seen, { family: mapped.family, source: "finding" });
+            }
+        }
+    }
+    return facts;
+}

package/dist/fixtures/repoIntelligenceFixtures.d.ts

@@ -0,0 +1,10 @@
+import type { RepoIntelligence } from "../repoIntelligenceSchema.js";
+/** Corpus-enabled runtime framework upgrade (auth/API paths). */
+export declare const fixtureRepoIntelligenceFastify: RepoIntelligence;
+/** Build-only toolchain change — no runtime paths. */
+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

@@ -0,0 +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;AAEF,wDAAwD;AACxD,eAAO,MAAM,mCAAmC,EAAE,gBA4CjD,CAAC"}

package/dist/fixtures/repoIntelligenceFixtures.js

@@ -0,0 +1,93 @@
+/** Corpus-enabled runtime framework upgrade (auth/API paths). */
+export const fixtureRepoIntelligenceFastify = {
+    packages: {
+        fastify: {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            usage: {
+                packageName: "fastify",
+                paths: ["apps/api/src/server.ts", "apps/api/src/routes/account.ts"],
+                criticalPaths: ["apps/api/src/middleware/auth.ts"],
+                areas: ["API", "Auth middleware"],
+            },
+        },
+    },
+    blastRadius: {
+        level: "moderate",
+        factors: ["middleware_ordering", "route_handlers"],
+        changedPackageCount: 1,
+    },
+    applicationAreas: [
+        { id: "api", label: "API routes" },
+        { id: "auth", label: "Auth middleware" },
+    ],
+    hotspots: [
+        {
+            packageName: "fastify",
+            source: "code",
+            paths: ["apps/api/src/middleware/auth.ts"],
+        },
+    ],
+    frameworks: ["fastify"],
+};
+/** Build-only toolchain change — no runtime paths. */
+export const fixtureRepoIntelligenceTypescript = {
+    packages: {
+        typescript: {
+            runtimeSurface: "build",
+            reachability: "build_only",
+        },
+    },
+    blastRadius: { level: "narrow", changedPackageCount: 1 },
+    applicationAreas: [],
+};
+/** Empty corpus stub (engine-test-fixture default). */
+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");

package/dist/index.d.ts

@@ -11,6 +11,15 @@ export * from "./formatCardExposureDisplay.js";
 export * from "./cardObservationCatalog.js";
 export * from "./deriveCardOperationalObservations.js";
 export * from "./deriveCardDisplaySummary.js";
+export * from "./scanNarrativeFacts.js";
+export * from "./repoIntelligenceSchema.js";
+export * from "./deriveScanNarrative.js";
+export * from "./extractRepositoryContextFacts.js";
+export * from "./presentScanCardSummary.js";
+export * from "./narrativePresentation.js";
+export * from "./normalizeGeneratedText.js";
+export * from "./collectNarrativeWhyBullets.js";
+export * from "./presentGitHubPrComment.js";
 export * from "./scanCardSummary.js";
 export * from "./deriveScanDetailRecommendations.js";
 export * from "./deriveRiskScoreSummary.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sCAAsC,CAAC;AACrD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sCAAsC,CAAC;AACrD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -11,6 +11,15 @@ export * from "./formatCardExposureDisplay.js";
 export * from "./cardObservationCatalog.js";
 export * from "./deriveCardOperationalObservations.js";
 export * from "./deriveCardDisplaySummary.js";
+export * from "./scanNarrativeFacts.js";
+export * from "./repoIntelligenceSchema.js";
+export * from "./deriveScanNarrative.js";
+export * from "./extractRepositoryContextFacts.js";
+export * from "./presentScanCardSummary.js";
+export * from "./narrativePresentation.js";
+export * from "./normalizeGeneratedText.js";
+export * from "./collectNarrativeWhyBullets.js";
+export * from "./presentGitHubPrComment.js";
 export * from "./scanCardSummary.js";
 export * from "./deriveScanDetailRecommendations.js";
 export * from "./deriveRiskScoreSummary.js";

package/dist/narrativeParity.test.d.ts

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

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

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

package/dist/narrativeParity.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { buildPrCheckRunSummaryMarkdown } from "./prCheckRunPresentation.js";
+import { deriveScanCardSummary } from "./scanCardSummary.js";
+import { deriveScanDetailViewModel } from "./scanDetailViewModel.js";
+import { presentGitHubPrComment } from "./presentGitHubPrComment.js";
+import { fixtureRepoIntelligenceFastify } from "./fixtures/repoIntelligenceFixtures.js";
+const ORIGIN = "https://app.example.com";
+const SCAN_ID = "22222222-2222-4222-8222-222222222222";
+describe("narrative parity across consumers", () => {
+    it("card, detail, GitHub share primary package and reachability story", () => {
+        const result = {
+            totalScore: 55,
+            layerScores: {
+                security: 10,
+                maintainability: 20,
+                ecosystem: 30,
+                upgradeImpact: 15,
+            },
+            findings: [],
+            generatedAt: "2026-01-01T00:00:00.000Z",
+            changedPackages: ["fastify"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+            decision: {
+                recommendation: "needs_review",
+                confidence: "medium",
+                reasoning: [],
+            },
+            insights: [
+                {
+                    type: "usage_risk",
+                    priority: "high",
+                    confidence: "confirmed",
+                    scope: "changed",
+                    message: "Review fastify middleware ordering",
+                    context: "apps/api/src/middleware/auth.ts",
+                    remediation: "Run auth smoke tests",
+                },
+            ],
+        };
+        const card = deriveScanCardSummary(result, "done");
+        const detail = deriveScanDetailViewModel(result, {
+            scanId: SCAN_ID,
+            status: "done",
+        });
+        const checkRun = buildPrCheckRunSummaryMarkdown({
+            result,
+            scanId: SCAN_ID,
+            webAppOrigin: ORIGIN,
+            baseline: false,
+        });
+        const prComment = presentGitHubPrComment(deriveScanNarrative(result), result);
+        expect(card.changedPackagesDisplay).toContain("fastify");
+        expect(detail?.narrativeContext.changedPackagesDisplay).toContain("fastify");
+        expect(card.reachabilityLabel).toBe("On runtime paths");
+        expect(detail?.narrativeContext.reachabilityLabel).toBe("On runtime paths");
+        const asciiOnly = /^[\x00-\x7F]*$/;
+        expect(asciiOnly.test(checkRun)).toBe(true);
+        expect(asciiOnly.test(prComment)).toBe(true);
+        expect(checkRun.toLowerCase()).toContain("fastify");
+        expect(prComment.toLowerCase()).toContain("fastify");
+    });
+});

package/dist/narrativePresentation.d.ts

@@ -0,0 +1,50 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
+export type SummarizePackageUsageOptions = {
+    maxPaths?: number;
+    maxPackages?: number;
+};
+export type PackageUsageSummary = {
+    pathCount: number;
+    pathSamples: string[];
+    areaLabels: string[];
+    packageNames: string[];
+};
+export type ReachabilitySummary = {
+    kindLabel: string | null;
+    pathSamples: string[];
+    frameworks: string[];
+};
+export type BlastRadiusSummary = {
+    levelLabel: string | null;
+    factors: string[];
+    changedPackageCount: number | null;
+};
+export declare function selectPrimaryChangedPackage(facts: ScanNarrativeFacts): string | null;
+export declare function formatChangedPackagesShort(facts: ScanNarrativeFacts, maxNames?: number): string | null;
+export declare function formatChangedPackagesDetail(facts: ScanNarrativeFacts): string[];
+export declare function summarizePackageUsage(facts: ScanNarrativeFacts, options?: SummarizePackageUsageOptions): PackageUsageSummary | null;
+declare function labelRuntimeSurface(facts: ScanNarrativeFacts): string | null;
+declare function labelReachabilityKind(facts: ScanNarrativeFacts): string | null;
+declare function labelBlastRadiusLevel(facts: ScanNarrativeFacts): string | null;
+export declare function summarizeReachability(facts: ScanNarrativeFacts, maxPaths?: number): ReachabilitySummary;
+export declare function summarizeBlastRadius(facts: ScanNarrativeFacts, maxFactors?: number): BlastRadiusSummary;
+export declare function summarizeHotspots(facts: ScanNarrativeFacts, max?: number): Array<{
+    packageName: string;
+    source: "code" | "graph";
+    pathSample: string | null;
+}>;
+export type SelectReviewerGuidanceOptions = {
+    scope?: "changed" | "all" | "any";
+    max?: number;
+};
+export declare function selectReviewerGuidance(facts: ScanNarrativeFacts, options?: SelectReviewerGuidanceOptions): ScanNarrativeFacts["reviewerGuidance"];
+export declare function composeVerificationPrompt(facts: ScanNarrativeFacts): string | null;
+export declare function formatUsageSummaryLine(facts: ScanNarrativeFacts, maxPaths?: number): string | null;
+export declare function formatBlastRadiusDetailLine(facts: ScanNarrativeFacts, maxFactors?: number): string | null;
+export declare function formatFrameworksSummary(facts: ScanNarrativeFacts, max?: number): string | null;
+export declare function composeContextLineFromFacts(facts: ScanNarrativeFacts, options?: {
+    includePathSample?: boolean;
+    maxAreas?: number;
+}): string | null;
+export { labelRuntimeSurface, labelReachabilityKind, labelBlastRadiusLevel };
+//# sourceMappingURL=narrativePresentation.d.ts.map

package/dist/narrativePresentation.d.ts.map

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