@mergesignal/shared 0.2.7 → 0.2.8

package/dist/index.d.ts

@@ -16,6 +16,10 @@ 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,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,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

@@ -16,6 +16,10 @@ 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":"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 };

package/dist/narrativePresentation.test.d.ts

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

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

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

package/dist/narrativePresentation.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { fixtureRepoIntelligenceFastify } from "./fixtures/repoIntelligenceFixtures.js";
+import { composeVerificationPrompt, formatChangedPackagesShort, formatUsageSummaryLine, summarizePackageUsage, } from "./narrativePresentation.js";
+const baseResult = {
+    totalScore: 10,
+    layerScores: {
+        security: 1,
+        maintainability: 2,
+        ecosystem: 3,
+        upgradeImpact: 4,
+    },
+    findings: [],
+    generatedAt: "2026-01-01T00:00:00.000Z",
+};
+describe("narrativePresentation", () => {
+    it("formats changed packages with second name when only one other", () => {
+        const facts = deriveScanNarrative({
+            ...baseResult,
+            changedPackages: ["lodash", "axios"],
+        });
+        expect(formatChangedPackagesShort(facts, 2)).toBe("lodash, axios");
+    });
+    it("summarizes package usage paths from facts", () => {
+        const facts = deriveScanNarrative({
+            ...baseResult,
+            changedPackages: ["fastify"],
+            analysisPreparation: { codeIntelligenceAvailable: true, warnings: [] },
+            repoIntelligence: fixtureRepoIntelligenceFastify,
+        });
+        const usage = summarizePackageUsage(facts);
+        expect(usage?.pathCount).toBeGreaterThan(0);
+        expect(formatUsageSummaryLine(facts)).toMatch(/Used in/);
+    });
+    it("composes verification from remediation when present", () => {
+        const facts = deriveScanNarrative({
+            ...baseResult,
+            changedPackages: ["pkg"],
+            insights: [
+                {
+                    type: "usage_risk",
+                    priority: "high",
+                    confidence: "confirmed",
+                    scope: "changed",
+                    message: "Risk in billing",
+                    context: "billing",
+                    remediation: "Run export job smoke test",
+                },
+            ],
+        });
+        expect(composeVerificationPrompt(facts)).toBe("Run export job smoke test");
+    });
+});

package/dist/normalizeGeneratedText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Enforce ASCII-safe generated user-facing text (hyphens, separators, ellipsis).
+ */
+export declare function normalizeGeneratedText(text: string): string;
+export declare function normalizeGeneratedTextNullable(text: string | null | undefined): string | null;
+/** Normalize every string field on a shallow object (presenter DTOs). */
+export declare function normalizeGeneratedStrings<T extends Record<string, unknown>>(obj: T): T;
+//# sourceMappingURL=normalizeGeneratedText.d.ts.map

package/dist/normalizeGeneratedText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeGeneratedText.d.ts","sourceRoot":"","sources":["../src/normalizeGeneratedText.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,MAAM,GAAG,IAAI,CAIf;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzE,GAAG,EAAE,CAAC,GACL,CAAC,CAYH"}

package/dist/normalizeGeneratedText.js

@@ -0,0 +1,31 @@
+const TYPOGRAPHIC_DASH = /[\u2010-\u2015\u2212\uFE58\uFE63\uFF0D]/g;
+/**
+ * Enforce ASCII-safe generated user-facing text (hyphens, separators, ellipsis).
+ */
+export function normalizeGeneratedText(text) {
+    return text
+        .replace(TYPOGRAPHIC_DASH, "-")
+        .replace(/\u00B7/g, " | ")
+        .replace(/\u2026/g, "...")
+        .replace(/–/gi, "-")
+        .replace(/—/gi, "-");
+}
+export function normalizeGeneratedTextNullable(text) {
+    if (text == null)
+        return null;
+    const normalized = normalizeGeneratedText(text);
+    return normalized.length > 0 ? normalized : null;
+}
+/** Normalize every string field on a shallow object (presenter DTOs). */
+export function normalizeGeneratedStrings(obj) {
+    const out = { ...obj };
+    for (const [key, value] of Object.entries(out)) {
+        if (typeof value === "string") {
+            out[key] = normalizeGeneratedText(value);
+        }
+        else if (Array.isArray(value)) {
+            out[key] = value.map((item) => typeof item === "string" ? normalizeGeneratedText(item) : item);
+        }
+    }
+    return out;
+}

package/dist/normalizeGeneratedText.test.d.ts

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

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

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

package/dist/normalizeGeneratedText.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+import { scanSurfaceCopyFlat } from "./scanSurfaceCopy.js";
+describe("normalizeGeneratedText", () => {
+    it("replaces typographic dashes with ASCII hyphen-minus", () => {
+        expect(normalizeGeneratedText("foo – bar — baz")).toBe("foo - bar - baz");
+        expect(normalizeGeneratedText("a—b–c")).toBe("a-b-c");
+    });
+    it("leaves ASCII text unchanged", () => {
+        expect(normalizeGeneratedText("Safe - Needs review")).toBe("Safe - Needs review");
+    });
+    it("scanSurfaceCopy flat strings are ASCII-safe", () => {
+        const asciiOnly = /^[\x00-\x7F]*$/;
+        for (const value of Object.values(scanSurfaceCopyFlat())) {
+            expect(asciiOnly.test(value), value).toBe(true);
+        }
+    });
+});

package/dist/prCheckRunPresentation.d.ts

@@ -1,3 +1,4 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
 import type { ScanResult } from "./types.js";
 export declare const CHECK_RUN_MAX_WHY_BULLETS = 3;
 export declare const CHECK_RUN_MAX_ACTION_BULLETS = 3;
@@ -57,9 +58,9 @@ export type CheckRunSection = {
 export declare function formatScanDashboardUrl(webAppOrigin: string, scanId: string): string;
 export declare function buildPrCheckRunTitle(opts?: PrCheckRunTitleOptions): string;
 /** Strong drivers for optional repo-context line (full mode only). */
-export declare function hasStrongRepoGraphDrivers(result: ScanResult): boolean;
-export declare function deriveCheckRunPolicy(result: ScanResult, ctx: Pick<PrCheckRunSummaryContext, "baseline">): CheckRunPolicy;
-export declare function buildPrCheckRunSections(policy: CheckRunPolicy, result: ScanResult, ctx: PrCheckRunSummaryContext): CheckRunSection[];
+export declare function hasStrongRepoGraphDrivers(result: ScanResult, facts?: ScanNarrativeFacts): boolean;
+export declare function deriveCheckRunPolicy(result: ScanResult, ctx: Pick<PrCheckRunSummaryContext, "baseline">, facts?: ScanNarrativeFacts): CheckRunPolicy;
+export declare function buildPrCheckRunSections(policy: CheckRunPolicy, result: ScanResult, ctx: PrCheckRunSummaryContext, facts?: ScanNarrativeFacts): CheckRunSection[];
 export declare function renderCheckRunMarkdown(sections: CheckRunSection[]): string;
 export declare function buildPrCheckRunSummaryMarkdown(ctx: PrCheckRunSummaryContext): string;
 /** Whether baseline scan has no actionable PR bullets (for tests / callers). */

package/dist/prCheckRunPresentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prCheckRunPresentation.d.ts","sourceRoot":"","sources":["../src/prCheckRunPresentation.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,iCAAiC,IAAI,CAAC;AACnD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAqB7C,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAUnD,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,IAAI,GAAE,sBAA2B,GAChC,MAAM,CAMR;AA4BD,sEAAsE;AACtE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAGrE;AAkGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAC9C,cAAc,CA0BhB;AAqBD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,wBAAwB,GAC5B,eAAe,EAAE,CAmDnB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,CA4E1E;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,wBAAwB,GAC5B,MAAM,CAIR;AAED,gFAAgF;AAChF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAExE"}
+{"version":3,"file":"prCheckRunPresentation.d.ts","sourceRoot":"","sources":["../src/prCheckRunPresentation.ts"],"names":[],"mappings":"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"}