@mergesignal/shared 0.2.6 → 0.2.8

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":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAUlE,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;AAED,sEAAsE;AACtE,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,EAClB,KAAK,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAaT;AA4ID,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,EAC/C,KAAK,CAAC,EAAE,kBAAkB,GACzB,cAAc,CA4BhB;AAqBD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,wBAAwB,EAC7B,KAAK,CAAC,EAAE,kBAAkB,GACzB,eAAe,EAAE,CA4DnB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,CAkF1E;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,wBAAwB,GAC5B,MAAM,CASR;AAED,gFAAgF;AAChF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAExE"}

package/dist/prCheckRunPresentation.js

@@ -2,9 +2,12 @@
  * GitHub Check Run markdown — policy → sections → dumb renderer.
  * Thin projection of ScanResult for PR decision support (not a presentation framework).
  */
-import { deriveScanSummaryText } from "./deriveScanSummaryText.js";
+import { collectWhyBullets } from "./collectNarrativeWhyBullets.js";
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
 import { formatInsight } from "./formatInsight.js";
-import { humanizeEngineSurfaceText, layerDriverSummary, sortPRInsightsForDisplay, sortRecommendationsForDisplay, truncateWithEllipsis, } from "./actionsStepSummary.js";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+import { selectReviewerGuidance } from "./narrativePresentation.js";
+import { layerDriverSummary, sortPRInsightsForDisplay, sortRecommendationsForDisplay, truncateWithEllipsis, } from "./actionsStepSummary.js";
 import { mergePostureLabel } from "./riskVocabulary.js";
 import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
 // --- Caps (change only with tests) ---
@@ -40,43 +43,17 @@ export function formatScanDashboardUrl(webAppOrigin, scanId) {
 export function buildPrCheckRunTitle(opts = {}) {
     const base = scanSurfaceCopy.checkRun.titleBase;
     if (opts.baselineOnly) {
-        return `${base} – ${scanSurfaceCopy.checkRun.titleBaselineSuffix}`;
+        return `${base} - ${scanSurfaceCopy.checkRun.titleBaselineSuffix}`;
     }
     return base;
 }
-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 out;
-        }
-    }
-    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 out.slice(0, max);
-}
 /** Strong drivers for optional repo-context line (full mode only). */
-export function hasStrongRepoGraphDrivers(result) {
-    const phrases = collectWhyBullets(result, CHECK_RUN_MAX_REPO_DRIVER_PHRASES);
+export function hasStrongRepoGraphDrivers(result, facts) {
+    if (facts?.availability.mode === "pr_intelligence" ||
+        facts?.availability.tiersPresent.tier1) {
+        return false;
+    }
+    const phrases = collectWhyBullets(facts ?? deriveScanNarrative(result), result, CHECK_RUN_MAX_REPO_DRIVER_PHRASES);
     return phrases.some((p) => p.trim().length >= 12);
 }
 function hasActionableBullets(result) {
@@ -92,7 +69,7 @@ function insightToBullet(insight) {
     const msg = truncateWithEllipsis(f.message, CHECK_RUN_ACTION_BULLET_MAX_CHARS);
     const action = f.action.trim();
     if (action && action.length < 120) {
-        return `${msg} — ${truncateWithEllipsis(action, 100)}`;
+        return normalizeGeneratedText(`${msg} - ${truncateWithEllipsis(action, 100)}`);
     }
     return msg;
 }
@@ -100,7 +77,7 @@ function recommendationToBullet(rec) {
     const title = String(rec.title ?? "").trim();
     const rat = String(rec.rationale ?? "").trim();
     const pkgs = Array.isArray(rec.packages) && rec.packages.length > 0
-        ? ` (${rec.packages.slice(0, 3).join(", ")}${rec.packages.length > 3 ? ", …" : ""})`
+        ? ` (${rec.packages.slice(0, 3).join(", ")}${rec.packages.length > 3 ? ", ..." : ""})`
         : "";
     if (rat && (!title || rat.length > title.length)) {
         return truncateWithEllipsis(rat, CHECK_RUN_ACTION_BULLET_MAX_CHARS) + pkgs;
@@ -113,6 +90,31 @@ function findingToBullet(f) {
     const pkg = f.packageName ? ` (\`${f.packageName}\`)` : "";
     return (truncateWithEllipsis(title || f.description, CHECK_RUN_ACTION_BULLET_MAX_CHARS) + pkg);
 }
+function guidanceToActionBullet(g) {
+    const msg = truncateWithEllipsis(g.message.trim(), CHECK_RUN_ACTION_BULLET_MAX_CHARS);
+    const action = g.remediation?.trim();
+    if (action && action.length < 120) {
+        return normalizeGeneratedText(`${msg} - ${truncateWithEllipsis(action, 100)}`);
+    }
+    return normalizeGeneratedText(msg);
+}
+function buildActionBulletsFromFacts(facts, result, max) {
+    const prIntel = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    if (!prIntel) {
+        return buildActionBullets(result, max);
+    }
+    const out = [];
+    for (const g of selectReviewerGuidance(facts, { scope: "changed", max })) {
+        out.push(guidanceToActionBullet(g));
+        if (out.length >= max)
+            return out.slice(0, max);
+    }
+    if (out.length >= max)
+        return out.slice(0, max);
+    const legacy = buildActionBullets(result, max - out.length);
+    return [...out, ...legacy].slice(0, max);
+}
 function buildActionBullets(result, max) {
     const out = [];
     const sortedI = sortPRInsightsForDisplay(Array.isArray(result.insights) ? result.insights : []);
@@ -156,12 +158,13 @@ function layerScoreRows(result) {
     }
     return rows;
 }
-export function deriveCheckRunPolicy(result, ctx) {
+export function deriveCheckRunPolicy(result, ctx, facts) {
+    const resolvedFacts = facts ?? deriveScanNarrative(result);
     const baseline = ctx.baseline;
-    const actionBullets = buildActionBullets(result, CHECK_RUN_MAX_ACTION_BULLETS);
+    const actionBullets = buildActionBulletsFromFacts(resolvedFacts, result, CHECK_RUN_MAX_ACTION_BULLETS);
     const layerRows = layerScoreRows(result);
     const showRepoGraphContext = !baseline &&
-        hasStrongRepoGraphDrivers(result) &&
+        hasStrongRepoGraphDrivers(result, resolvedFacts) &&
         typeof result.totalScore === "number" &&
         Number.isFinite(result.totalScore);
     const showLayerScores = !baseline && layerRows.length > 0;
@@ -189,14 +192,15 @@ function buildLeadSection(result, policy) {
         : null;
     return { kind: "lead", posture, riskIndexLine };
 }
-export function buildPrCheckRunSections(policy, result, ctx) {
+export function buildPrCheckRunSections(policy, result, ctx, facts) {
+    const resolvedFacts = facts ?? deriveScanNarrative(result);
     const sections = {};
     sections.lead = buildLeadSection(result, policy);
-    const why = collectWhyBullets(result, policy.maxWhyBullets);
+    const why = collectWhyBullets(resolvedFacts, result, policy.maxWhyBullets);
     if (why.length > 0) {
         sections.why = { kind: "why", bullets: why };
     }
-    const actions = buildActionBullets(result, policy.maxActionBullets);
+    const actions = buildActionBulletsFromFacts(resolvedFacts, result, policy.maxActionBullets);
     if (actions.length > 0) {
         sections.actions = { kind: "actions", bullets: actions };
     }
@@ -212,7 +216,7 @@ export function buildPrCheckRunSections(policy, result, ctx) {
         sections.repoContext = {
             kind: "repoContext",
             score,
-            driverPhrases: collectWhyBullets(result, policy.maxRepoDriverPhrases),
+            driverPhrases: collectWhyBullets(resolvedFacts, result, policy.maxRepoDriverPhrases),
         };
     }
     if (policy.showLayerScores) {
@@ -270,8 +274,8 @@ export function renderCheckRunMarkdown(sections) {
                 break;
             }
             case "repoContext": {
-                const drivers = section.driverPhrases.join(" · ");
-                parts.push(`${scanSurfaceCopy.checkRun.repoContextLabel} ${section.score}/100 — ${drivers}`);
+                const drivers = section.driverPhrases.join(" | ");
+                parts.push(normalizeGeneratedText(`${scanSurfaceCopy.checkRun.repoContextLabel} ${section.score}/100 - ${drivers}`));
                 parts.push("");
                 break;
             }
@@ -280,7 +284,7 @@ export function renderCheckRunMarkdown(sections) {
                 parts.push(`<summary>${scanSurfaceCopy.checkRun.layerScoresDetailsSummary}</summary>`);
                 parts.push("");
                 for (const row of section.rows) {
-                    parts.push(`- **${row.label}** ${row.score}/100 — ${row.driver}`);
+                    parts.push(normalizeGeneratedText(`- **${row.label}** ${row.score}/100 - ${row.driver}`));
                 }
                 parts.push("");
                 parts.push("</details>");
@@ -297,15 +301,16 @@ export function renderCheckRunMarkdown(sections) {
             }
         }
     }
-    let md = parts.join("\n").trimEnd();
+    let md = normalizeGeneratedText(parts.join("\n").trimEnd());
     if (md.length > CHECK_RUN_SOFT_MAX_CHARS) {
-        md = md.slice(0, CHECK_RUN_SOFT_MAX_CHARS - 1) + "…";
+        md = md.slice(0, CHECK_RUN_SOFT_MAX_CHARS - 1) + "...";
     }
     return md;
 }
 export function buildPrCheckRunSummaryMarkdown(ctx) {
-    const policy = deriveCheckRunPolicy(ctx.result, { baseline: ctx.baseline });
-    const sections = buildPrCheckRunSections(policy, ctx.result, ctx);
+    const facts = deriveScanNarrative(ctx.result);
+    const policy = deriveCheckRunPolicy(ctx.result, { baseline: ctx.baseline }, facts);
+    const sections = buildPrCheckRunSections(policy, ctx.result, ctx, facts);
     return renderCheckRunMarkdown(sections);
 }
 /** Whether baseline scan has no actionable PR bullets (for tests / callers). */

package/dist/prCheckRunPresentation.test.js

@@ -38,7 +38,7 @@ describe("buildPrCheckRunTitle", () => {
         expect(buildPrCheckRunTitle()).not.toContain("—");
     });
     it("appends baseline suffix when requested", () => {
-        expect(buildPrCheckRunTitle({ baselineOnly: true })).toBe("PR dependency change – baseline scan only");
+        expect(buildPrCheckRunTitle({ baselineOnly: true })).toBe("PR dependency change - baseline scan only");
     });
 });
 describe("formatScanDashboardUrl", () => {
@@ -271,7 +271,7 @@ describe("buildPrCheckRunSummaryMarkdown", () => {
             baseline: false,
         });
         if (md.includes("Layer scores")) {
-            expect(md).toMatch(/Maintainability.*\/100 —/);
+            expect(md).toMatch(/Maintainability.*\/100 -/);
             expect(md).not.toMatch(/\| Security \| 0 \|/);
         }
     });

package/dist/presentGitHubPrComment.d.ts

@@ -0,0 +1,9 @@
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
+import type { PRDecision, PRInsight, ScanResult } from "./types.js";
+/**
+ * PR comment markdown from narrative facts (compressed dashboard story).
+ */
+export declare function presentGitHubPrComment(facts: ScanNarrativeFacts, result: ScanResult): string;
+/** Backward-compatible entry: derives facts then presents. */
+export declare function renderInsightsAsMarkdown(insights: PRInsight[], decision: PRDecision): string;
+//# sourceMappingURL=presentGitHubPrComment.d.ts.map

package/dist/presentGitHubPrComment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentGitHubPrComment.d.ts","sourceRoot":"","sources":["../src/presentGitHubPrComment.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoBpE;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,UAAU,GACjB,MAAM,CA6CR;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,EAAE,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAgBR"}

package/dist/presentGitHubPrComment.js

@@ -0,0 +1,80 @@
+import { deriveScanNarrative } from "./deriveScanNarrative.js";
+import { composeVerificationPrompt, formatChangedPackagesShort, formatUsageSummaryLine, selectReviewerGuidance, } from "./narrativePresentation.js";
+import { normalizeGeneratedText } from "./normalizeGeneratedText.js";
+import { MERGE_POSTURE_LABEL, mergePostureFromDecision, } from "./riskVocabulary.js";
+import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
+function renderGuidanceBlock(message, where, action) {
+    return [
+        normalizeGeneratedText(message),
+        "",
+        "**Where it shows up**",
+        "",
+        normalizeGeneratedText(where),
+        "",
+        "**What to do**",
+        "",
+        normalizeGeneratedText(action),
+    ].join("\n");
+}
+/**
+ * PR comment markdown from narrative facts (compressed dashboard story).
+ */
+export function presentGitHubPrComment(facts, result) {
+    const posture = facts.mergePosture ??
+        mergePostureFromDecision(result.decision?.recommendation);
+    const title = posture
+        ? `**${MERGE_POSTURE_LABEL[posture]}**`
+        : `**${scanSurfaceCopy.checkRun.mergePostureUnavailable}**`;
+    const introLines = [];
+    const changed = formatChangedPackagesShort(facts, 3);
+    if (changed)
+        introLines.push(`Changed: ${changed}`);
+    const usage = formatUsageSummaryLine(facts, 1);
+    if (usage)
+        introLines.push(usage);
+    const verify = composeVerificationPrompt(facts);
+    if (verify)
+        introLines.push(`Verify: ${verify}`);
+    const guidance = selectReviewerGuidance(facts, { scope: "changed", max: 3 });
+    if (guidance.length === 0) {
+        const fallback = selectReviewerGuidance(facts, { max: 3 });
+        guidance.push(...fallback.slice(0, 3 - guidance.length));
+    }
+    const blocks = guidance.map((g) => {
+        const where = g.context?.trim() ||
+            facts.packageUsage
+                .flatMap((u) => u.paths.slice(0, 1))
+                .filter(Boolean)[0] ||
+            "See scan detail for affected paths.";
+        const action = g.remediation?.trim() ||
+            composeVerificationPrompt(facts) ||
+            "Review before merge.";
+        return renderGuidanceBlock(g.message, where, action);
+    });
+    const parts = [title];
+    if (introLines.length > 0) {
+        parts.push("", introLines.join("\n"));
+    }
+    if (blocks.length > 0) {
+        parts.push("", ...blocks);
+    }
+    return parts.join("\n\n---\n\n").trimEnd();
+}
+/** Backward-compatible entry: derives facts then presents. */
+export function renderInsightsAsMarkdown(insights, decision) {
+    const result = {
+        totalScore: 0,
+        layerScores: {
+            security: 0,
+            maintainability: 0,
+            ecosystem: 0,
+            upgradeImpact: 0,
+        },
+        findings: [],
+        generatedAt: new Date().toISOString(),
+        insights,
+        decision,
+    };
+    const facts = deriveScanNarrative(result);
+    return presentGitHubPrComment(facts, result);
+}