@mergesignal/shared 0.2.7 → 0.3.0

package/dist/engineWireRegression.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { deriveScanCardSummary } from "./scanCardSummary.js";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceMultiPackage, } from "./fixtures/repoIntelligenceFixtures.js";
+import { validateRepoIntelligenceWire } from "./repoIntelligenceSchema.js";
+const baseScan = {
+    totalScore: 55,
+    layerScores: {
+        security: 10,
+        maintainability: 20,
+        ecosystem: 30,
+        upgradeImpact: 15,
+    },
+    findings: [],
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    analysisPreparation: {
+        codeIntelligenceAvailable: true,
+        warnings: [],
+        repoIntelligenceValidation: {
+            status: "valid",
+            abi: "1",
+            validatedAt: "2026-01-01T00:00:00.000Z",
+        },
+    },
+};
+describe("engine wire regression (canonical fixtures)", () => {
+    it("fastify fixture: parse → tier1 pr_intelligence → card usage lines", () => {
+        validateRepoIntelligenceWire(fixtureRepoIntelligenceFastify);
+        const result = {
+            ...baseScan,
+            changedPackages: ["fastify"],
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.tiersPresent.tier1).toBe(true);
+        expect(facts.availability.mode).toBe("pr_intelligence");
+        expect(facts.availability.repoIntelligenceParse).toBe("ok");
+        expect(facts.packageUsage[0]?.packageName).toBe("fastify");
+        const card = deriveScanCardSummary(result, "done");
+        expect(card.usageSummary).toBeTruthy();
+        expect(card.verificationLine).toBeTruthy();
+    });
+    it("multi-package fixture: both packages in packageUsage", () => {
+        validateRepoIntelligenceWire(fixtureRepoIntelligenceMultiPackage);
+        const result = {
+            ...baseScan,
+            changedPackages: ["lodash", "axios"],
+            repoIntelligence: fixtureRepoIntelligenceMultiPackage,
+        };
+        const facts = deriveScanNarrative(result);
+        expect(facts.availability.mode).toBe("pr_intelligence");
+        expect(facts.packageUsage.map((u) => u.packageName)).toEqual([
+            "lodash",
+            "axios",
+        ]);
+    });
+});

package/dist/fixtures/legacyEngineRepoIntelligence.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pre-contract engine wire shape (Wave 1/2 drift). Used to assert strict schema rejection
+ * and narrative fallback while preserving raw payload for forensics.
+ */
+export declare const legacyEngineRepoIntelligenceJwt: {
+    readonly packageUsage: readonly [{
+        readonly name: "jsonwebtoken";
+        readonly files: readonly ["src/auth/auth.service.ts", "src/auth/login.controller.ts"];
+        readonly reachability: "moderate";
+        readonly runtimeSurface: "runtime";
+        readonly areas: readonly ["authentication"];
+        readonly blastRadius: "moderate";
+    }];
+    readonly hotspots: readonly [{
+        readonly file: "src/auth/auth.service.ts";
+        readonly fanIn: 2;
+        readonly areas: readonly ["authentication"];
+    }];
+    readonly frameworks: readonly [{
+        readonly framework: "express";
+        readonly roles: readonly ["middleware"];
+    }];
+    readonly blastRadius: {
+        readonly level: "large";
+        readonly factors: readonly ["reaches runtime application code"];
+    };
+};
+//# sourceMappingURL=legacyEngineRepoIntelligence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"legacyEngineRepoIntelligence.d.ts","sourceRoot":"","sources":["../../src/fixtures/legacyEngineRepoIntelligence.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;CAuBlC,CAAC"}

package/dist/fixtures/legacyEngineRepoIntelligence.js

@@ -0,0 +1,28 @@
+/**
+ * Pre-contract engine wire shape (Wave 1/2 drift). Used to assert strict schema rejection
+ * and narrative fallback while preserving raw payload for forensics.
+ */
+export const legacyEngineRepoIntelligenceJwt = {
+    packageUsage: [
+        {
+            name: "jsonwebtoken",
+            files: ["src/auth/auth.service.ts", "src/auth/login.controller.ts"],
+            reachability: "moderate",
+            runtimeSurface: "runtime",
+            areas: ["authentication"],
+            blastRadius: "moderate",
+        },
+    ],
+    hotspots: [
+        {
+            file: "src/auth/auth.service.ts",
+            fanIn: 2,
+            areas: ["authentication"],
+        },
+    ],
+    frameworks: [{ framework: "express", roles: ["middleware"] }],
+    blastRadius: {
+        level: "large",
+        factors: ["reaches runtime application code"],
+    },
+};

package/dist/fixtures/repoIntelligenceFixtures.d.ts

@@ -3,6 +3,6 @@ import type { RepoIntelligence } from "../repoIntelligenceSchema.js";
 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

@@ -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,gBAmC5C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,iCAAiC,EAAE,gBAc/C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,mCAAmC,EAAE,gBAgDjD,CAAC"}

package/dist/fixtures/repoIntelligenceFixtures.js

@@ -6,6 +6,11 @@ export const fixtureRepoIntelligenceFastify = {
             reachability: "on_runtime_paths",
             usage: {
                 packageName: "fastify",
+                files: [
+                    "apps/api/src/server.ts",
+                    "apps/api/src/routes/account.ts",
+                    "apps/api/src/middleware/auth.ts",
+                ],
                 paths: ["apps/api/src/server.ts", "apps/api/src/routes/account.ts"],
                 criticalPaths: ["apps/api/src/middleware/auth.ts"],
                 areas: ["API", "Auth middleware"],
@@ -36,12 +41,63 @@ export const fixtureRepoIntelligenceTypescript = {
         typescript: {
             runtimeSurface: "build",
             reachability: "build_only",
+            usage: {
+                packageName: "typescript",
+                files: ["tsconfig.json"],
+                paths: [],
+            },
         },
     },
     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",
+                files: ["apps/billing/export.ts"],
+                paths: ["apps/billing/export.ts"],
+                areas: ["Billing"],
+            },
+        },
+        axios: {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            usage: {
+                packageName: "axios",
+                files: ["apps/api/client.ts"],
+                paths: ["apps/api/client.ts"],
+                areas: ["API"],
+            },
+        },
+    },
+    packageUsage: [
+        {
+            packageName: "lodash",
+            files: ["apps/billing/export.ts"],
+            paths: ["apps/billing/export.ts"],
+        },
+        {
+            packageName: "axios",
+            files: ["apps/api/client.ts"],
+            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/fixtures/repoIntelligenceTestHelpers.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisPreparation } from "../types.js";
+/** Worker-shaped preparation for tests that consume trusted repoIntelligence. */
+export declare function analysisPreparationWithValidRepoIntel(over?: Partial<AnalysisPreparation>): AnalysisPreparation;
+export declare function analysisPreparationWithInvalidRepoIntel(over?: Partial<AnalysisPreparation>): AnalysisPreparation;
+//# sourceMappingURL=repoIntelligenceTestHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repoIntelligenceTestHelpers.d.ts","sourceRoot":"","sources":["../../src/fixtures/repoIntelligenceTestHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,iFAAiF;AACjF,wBAAgB,qCAAqC,CACnD,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,mBAAmB,CAWrB;AAED,wBAAgB,uCAAuC,CACrD,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,mBAAmB,CAarB"}

package/dist/fixtures/repoIntelligenceTestHelpers.js

@@ -0,0 +1,28 @@
+import { REPO_INTELLIGENCE_ABI } from "../repoIntelligenceSchema.js";
+/** Worker-shaped preparation for tests that consume trusted repoIntelligence. */
+export function analysisPreparationWithValidRepoIntel(over) {
+    return {
+        codeIntelligenceAvailable: true,
+        warnings: [],
+        repoIntelligenceValidation: {
+            status: "valid",
+            abi: REPO_INTELLIGENCE_ABI,
+            validatedAt: "2026-01-01T00:00:00.000Z",
+        },
+        ...over,
+    };
+}
+export function analysisPreparationWithInvalidRepoIntel(over) {
+    return {
+        codeIntelligenceAvailable: true,
+        warnings: [],
+        repoIntelligenceValidation: {
+            status: "invalid",
+            abi: REPO_INTELLIGENCE_ABI,
+            issueCount: 1,
+            representativeIssues: ["packages: at least one package required"],
+            validatedAt: "2026-01-01T00:00:00.000Z",
+        },
+        ...over,
+    };
+}

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

@@ -13,9 +13,15 @@ export * from "./deriveCardOperationalObservations.js";
 export * from "./deriveCardDisplaySummary.js";
 export * from "./scanNarrativeFacts.js";
 export * from "./repoIntelligenceSchema.js";
+export * from "./repoIntelligenceMappers.js";
+export * from "./repoIntelligenceValidation.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,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,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"}
+{"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,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,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

@@ -13,9 +13,15 @@ export * from "./deriveCardOperationalObservations.js";
 export * from "./deriveCardDisplaySummary.js";
 export * from "./scanNarrativeFacts.js";
 export * from "./repoIntelligenceSchema.js";
+export * from "./repoIntelligenceMappers.js";
+export * from "./repoIntelligenceValidation.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,65 @@
+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";
+import { analysisPreparationWithValidRepoIntel } from "./fixtures/repoIntelligenceTestHelpers.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: analysisPreparationWithValidRepoIntel(),
+            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":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,GACxB,MAAM,GAAG,IAAI,CAEf;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,SAAI,GACX,MAAM,GAAG,IAAI,CAQf;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,GACxB,MAAM,EAAE,CAEV;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,4BAAiC,GACzC,mBAAmB,GAAG,IAAI,CA6B5B;AAED,iBAAS,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAIrE;AAED,iBAAS,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED,iBAAS,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,SAAI,GACX,mBAAmB,CAUrB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,UAAU,SAAI,GACb,kBAAkB,CAOpB;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,GAAG,SAAI,GACN,KAAK,CAAC;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAMD;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,6BAAkC,GAC1C,kBAAkB,CAAC,kBAAkB,CAAC,CASxC;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,kBAAkB,GACxB,MAAM,GAAG,IAAI,CAYf;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,SAAI,GACX,MAAM,GAAG,IAAI,CAiBf;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EACzB,UAAU,SAAI,GACb,MAAM,GAAG,IAAI,CAQf;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,EACzB,GAAG,SAAI,GACN,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,MAAM,GAAG,IAAI,CA4Bf;AAED,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/narrativePresentation.js

@@ -0,0 +1,180 @@
+import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
+export function selectPrimaryChangedPackage(facts) {
+    return facts.changedPackages.primary;
+}
+export function formatChangedPackagesShort(facts, maxNames = 2) {
+    const { primary, others } = facts.changedPackages;
+    if (!primary)
+        return null;
+    if (others.length === 0)
+        return primary;
+    if (maxNames >= 2 && others.length === 1) {
+        return `${primary}, ${others[0]}`;
+    }
+    return `${primary} +${others.length}`;
+}
+export function formatChangedPackagesDetail(facts) {
+    return facts.changedPackages.all;
+}
+export function summarizePackageUsage(facts, options = {}) {
+    const maxPaths = options.maxPaths ?? 3;
+    const maxPackages = options.maxPackages ?? 5;
+    const rows = facts.packageUsage.slice(0, maxPackages);
+    if (rows.length === 0)
+        return null;
+    const pathSamples = [];
+    let pathCount = 0;
+    const areaLabels = [];
+    const packageNames = [];
+    for (const row of rows) {
+        packageNames.push(row.packageName);
+        const rowPaths = [...row.paths, ...row.criticalPaths, ...row.files].filter(Boolean);
+        pathCount += rowPaths.length;
+        for (const p of rowPaths) {
+            if (pathSamples.length >= maxPaths)
+                break;
+            if (!pathSamples.includes(p))
+                pathSamples.push(p);
+        }
+        for (const a of row.areas) {
+            if (!areaLabels.includes(a))
+                areaLabels.push(a);
+        }
+    }
+    if (pathCount === 0 && areaLabels.length === 0)
+        return null;
+    return { pathCount, pathSamples, areaLabels, packageNames };
+}
+function labelRuntimeSurface(facts) {
+    const rs = facts.runtimeSurface;
+    if (!rs)
+        return null;
+    return scanSurfaceCopy.narrativeCard.runtimeSurface[rs.kind];
+}
+function labelReachabilityKind(facts) {
+    const r = facts.reachability;
+    if (!r)
+        return null;
+    return scanSurfaceCopy.narrativeCard.reachability[r.kind];
+}
+function labelBlastRadiusLevel(facts) {
+    const br = facts.blastRadius;
+    if (!br)
+        return null;
+    return scanSurfaceCopy.narrativeCard.blastRadius[br.level];
+}
+export function summarizeReachability(facts, maxPaths = 1) {
+    const kindLabel = labelReachabilityKind(facts);
+    const paths = facts.reachability?.evidence.paths ?? [];
+    const frameworks = facts.reachability?.evidence.frameworks ?? facts.frameworks;
+    return {
+        kindLabel,
+        pathSamples: paths.slice(0, maxPaths),
+        frameworks: frameworks.slice(0, 3),
+    };
+}
+export function summarizeBlastRadius(facts, maxFactors = 3) {
+    const br = facts.blastRadius;
+    return {
+        levelLabel: labelBlastRadiusLevel(facts),
+        factors: (br?.factors ?? []).slice(0, maxFactors),
+        changedPackageCount: br?.changedPackageCount ?? null,
+    };
+}
+export function summarizeHotspots(facts, max = 5) {
+    return facts.hotspots.slice(0, max).map((h) => ({
+        packageName: h.packageName,
+        source: h.source,
+        pathSample: h.paths[0] ?? null,
+    }));
+}
+export function selectReviewerGuidance(facts, options = {}) {
+    const max = options.max ?? 6;
+    let list = facts.reviewerGuidance;
+    if (options.scope === "changed") {
+        list = list.filter((g) => g.scope === "changed");
+    }
+    else if (options.scope === "all") {
+        list = list.filter((g) => g.scope === "all");
+    }
+    return list.slice(0, max);
+}
+export function composeVerificationPrompt(facts) {
+    const changed = selectReviewerGuidance(facts, { scope: "changed", max: 1 });
+    const remediation = changed[0]?.remediation?.trim();
+    if (remediation)
+        return remediation;
+    const usage = summarizePackageUsage(facts, { maxPaths: 1 });
+    if (usage?.pathSamples[0]) {
+        return `Confirm behavior where this dependency is used (${usage.pathSamples[0]}).`;
+    }
+    const any = selectReviewerGuidance(facts, { max: 1 });
+    return any[0]?.remediation?.trim() ?? null;
+}
+export function formatUsageSummaryLine(facts, maxPaths = 1) {
+    const usage = summarizePackageUsage(facts, { maxPaths });
+    if (!usage)
+        return null;
+    if (usage.pathSamples.length > 0) {
+        const sample = usage.pathSamples[0];
+        if (usage.pathCount <= 1) {
+            return `Used in ${sample}`;
+        }
+        return `Used in ${usage.pathCount} paths (${sample})`;
+    }
+    if (usage.areaLabels.length > 0) {
+        return `Used in ${usage.areaLabels.slice(0, 2).join(", ")}`;
+    }
+    return null;
+}
+export function formatBlastRadiusDetailLine(facts, maxFactors = 1) {
+    const summary = summarizeBlastRadius(facts, maxFactors);
+    if (summary.factors.length === 0)
+        return null;
+    const factor = summary.factors[0].replace(/_/g, " ");
+    if (summary.levelLabel) {
+        return `${summary.levelLabel}: ${factor}`;
+    }
+    return factor;
+}
+export function formatFrameworksSummary(facts, max = 2) {
+    const frameworks = facts.frameworks.slice(0, max);
+    if (frameworks.length === 0)
+        return null;
+    if (frameworks.length === 1)
+        return frameworks[0];
+    return frameworks.join(", ");
+}
+export function composeContextLineFromFacts(facts, options = {}) {
+    const parts = [];
+    const runtime = labelRuntimeSurface(facts);
+    const reach = summarizeReachability(facts, options.includePathSample ? 1 : 0);
+    const blast = labelBlastRadiusLevel(facts);
+    if (runtime)
+        parts.push(runtime);
+    if (reach.kindLabel) {
+        if (options.includePathSample && reach.pathSamples[0]) {
+            parts.push(`${reach.kindLabel} (${reach.pathSamples[0]})`);
+        }
+        else {
+            parts.push(reach.kindLabel);
+        }
+    }
+    if (blast)
+        parts.push(blast);
+    const maxAreas = options.maxAreas ?? 2;
+    const areaLabels = [];
+    for (const area of facts.affectedAreas) {
+        if (areaLabels.length >= maxAreas)
+            break;
+        if (!areaLabels.includes(area.label))
+            areaLabels.push(area.label);
+    }
+    if (areaLabels.length > 0) {
+        parts.push(areaLabels.join(scanSurfaceCopy.narrativeCard.areasSeparator));
+    }
+    if (parts.length === 0)
+        return null;
+    return parts.join(scanSurfaceCopy.narrativeCard.contextSeparator);
+}
+export { labelRuntimeSurface, labelReachabilityKind, labelBlastRadiusLevel };