@mergesignal/shared 0.4.0 → 0.4.2

package/dist/presentation/fixtures/presentationPersonaFixtures.js

@@ -0,0 +1,197 @@
+import { fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceTypescript, } from "../../fixtures/repoIntelligenceFixtures.js";
+import { analysisPreparationWithValidRepoIntel } from "../../fixtures/repoIntelligenceTestHelpers.js";
+import { scanResultFastifyRuntime, scanResultLimitedContext, scanResultTypescriptPatch, } from "./scanResultFixtures.js";
+const basePrep = analysisPreparationWithValidRepoIntel();
+const fixtureRepoIntelligenceEslint = {
+    packages: {
+        eslint: {
+            runtimeSurface: "build",
+            reachability: "build_only",
+            runtimeImpact: "none",
+            expectedImpact: "development_only",
+            evidenceStrength: "medium",
+            suppressRuntimeNarrative: true,
+            dependencyClass: "lint",
+            packageRole: "linter",
+            verificationFocus: ["ci", "lint"],
+            usage: { packageName: "eslint", files: [".eslintrc.cjs"], paths: [] },
+        },
+    },
+    blastRadius: { level: "narrow", changedPackageCount: 1 },
+    applicationAreas: [],
+};
+const fixtureRepoIntelligencePrettier = {
+    packages: {
+        prettier: {
+            runtimeSurface: "build",
+            reachability: "build_only",
+            runtimeImpact: "none",
+            expectedImpact: "development_only",
+            evidenceStrength: "medium",
+            suppressRuntimeNarrative: true,
+            dependencyClass: "format",
+            packageRole: "formatter",
+            verificationFocus: ["ci", "format"],
+            usage: { packageName: "prettier", files: [".prettierrc"], paths: [] },
+        },
+    },
+    blastRadius: { level: "narrow", changedPackageCount: 1 },
+    applicationAreas: [],
+};
+const fixtureRepoIntelligenceVitest = {
+    packages: {
+        vitest: {
+            runtimeSurface: "test",
+            reachability: "test_only",
+            runtimeImpact: "none",
+            expectedImpact: "test_time",
+            evidenceStrength: "medium",
+            suppressRuntimeNarrative: true,
+            dependencyClass: "test",
+            packageRole: "test_runner",
+            verificationFocus: ["ci", "test_suite"],
+            usage: { packageName: "vitest", files: ["vitest.config.ts"], paths: [] },
+        },
+    },
+    blastRadius: { level: "narrow", changedPackageCount: 1 },
+    applicationAreas: [],
+};
+const fixtureRepoIntelligenceNextAuth = {
+    packages: {
+        "next-auth": {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            runtimeImpact: "confirmed",
+            expectedImpact: "runtime",
+            evidenceStrength: "high",
+            suppressRuntimeNarrative: false,
+            dependencyClass: "runtime",
+            packageRole: "auth",
+            verificationFocus: ["auth_flow", "session", "routes"],
+            usage: {
+                packageName: "next-auth",
+                files: ["apps/web/src/auth.ts"],
+                paths: ["apps/web/src/auth.ts"],
+                areas: ["Auth"],
+            },
+        },
+    },
+    blastRadius: { level: "moderate", changedPackageCount: 1 },
+    applicationAreas: [{ id: "auth", label: "authentication flows" }],
+};
+const fixtureRepoIntelligenceBullmq = {
+    packages: {
+        bullmq: {
+            runtimeSurface: "runtime",
+            reachability: "on_runtime_paths",
+            runtimeImpact: "confirmed",
+            expectedImpact: "runtime",
+            evidenceStrength: "high",
+            suppressRuntimeNarrative: false,
+            dependencyClass: "runtime",
+            packageRole: "queue",
+            verificationFocus: ["workers", "queue", "serialization"],
+            usage: {
+                packageName: "bullmq",
+                files: ["apps/worker/src/queue.ts"],
+                paths: ["apps/worker/src/queue.ts"],
+                areas: ["Workers"],
+            },
+        },
+    },
+    blastRadius: { level: "moderate", changedPackageCount: 1 },
+    applicationAreas: [{ id: "workers", label: "background job processing" }],
+};
+const fixtureRepoIntelligenceUnknown = {
+    packages: {
+        "opaque-pkg": {
+            runtimeSurface: "unknown",
+            reachability: "unknown",
+            runtimeImpact: "unknown",
+            expectedImpact: "unknown",
+            evidenceStrength: "low",
+            suppressRuntimeNarrative: false,
+            dependencyClass: "unknown",
+            packageRole: "unknown",
+            verificationFocus: [],
+            usage: { packageName: "opaque-pkg", files: [], paths: [] },
+        },
+    },
+    blastRadius: { level: "narrow", changedPackageCount: 1 },
+    applicationAreas: [],
+};
+const fixtureRepoIntelligenceMixedToolingRuntime = {
+    packages: {
+        typescript: fixtureRepoIntelligenceTypescript.packages.typescript,
+        fastify: fixtureRepoIntelligenceFastify.packages.fastify,
+    },
+    blastRadius: fixtureRepoIntelligenceFastify.blastRadius,
+    applicationAreas: fixtureRepoIntelligenceFastify.applicationAreas,
+};
+function scanBase(over = {}) {
+    return {
+        totalScore: 18,
+        layerScores: {
+            security: 5,
+            maintainability: 8,
+            ecosystem: 10,
+            upgradeImpact: 5,
+        },
+        findings: [],
+        generatedAt: "2026-01-01T00:00:00.000Z",
+        decision: {
+            recommendation: "safe",
+            confidence: "high",
+            reasoning: [],
+        },
+        analysisPreparation: basePrep,
+        ...over,
+    };
+}
+export const scanResultEslint = scanBase({
+    changedPackages: ["eslint"],
+    repoIntelligence: fixtureRepoIntelligenceEslint,
+});
+export const scanResultPrettier = scanBase({
+    changedPackages: ["prettier"],
+    repoIntelligence: fixtureRepoIntelligencePrettier,
+});
+export const scanResultVitest = scanBase({
+    changedPackages: ["vitest"],
+    repoIntelligence: fixtureRepoIntelligenceVitest,
+});
+export const scanResultNextAuth = scanBase({
+    totalScore: 52,
+    changedPackages: ["next-auth"],
+    repoIntelligence: fixtureRepoIntelligenceNextAuth,
+    decision: {
+        recommendation: "needs_review",
+        confidence: "medium",
+        reasoning: [],
+    },
+});
+export const scanResultBullmq = scanBase({
+    totalScore: 48,
+    changedPackages: ["bullmq"],
+    repoIntelligence: fixtureRepoIntelligenceBullmq,
+    decision: {
+        recommendation: "needs_review",
+        confidence: "medium",
+        reasoning: [],
+    },
+});
+export const scanResultUnknownSafe = scanBase({
+    changedPackages: ["opaque-pkg"],
+    repoIntelligence: fixtureRepoIntelligenceUnknown,
+});
+export const scanResultMixedTypescriptFastify = scanBase({
+    totalScore: 55,
+    changedPackages: ["typescript", "fastify"],
+    repoIntelligence: fixtureRepoIntelligenceMixedToolingRuntime,
+    decision: {
+        recommendation: "needs_review",
+        confidence: "medium",
+        reasoning: [],
+    },
+});
+export { scanResultFastifyRuntime, scanResultLimitedContext, scanResultTypescriptPatch, };

package/dist/presentation/index.d.ts

@@ -6,6 +6,8 @@ export type { BuildScanCardPresentationInput } from "./orchestration/buildScanCa
 export { buildScanDetailsPresentation } from "./orchestration/buildScanDetailsPresentation.js";
 export type { BuildScanDetailsPresentationInput } from "./orchestration/buildScanDetailsPresentation.js";
 export type { PresentationProfile } from "./profile/presentationProfile.js";
+export type { PresentationIntent, PresentationInterpretation, } from "./intent/presentationIntent.js";
+export { derivePresentationInterpretation } from "./intent/derivePresentationInterpretation.js";
 export type { PipelineStatus, PresentationStatus, PresentationDensity, PresentationConfidence, PresentationPriority, PresentationEvidenceContext, PresentationEvidenceRow, } from "./dto/types.js";
 export type { ScanCardPresentation } from "./dto/scanCardPresentation.js";
 export type { ScanDetailsPresentation } from "./dto/scanDetailsPresentation.js";

package/dist/presentation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presentation/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACxF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,YAAY,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AACzF,YAAY,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AACnG,OAAO,EAAE,4BAA4B,EAAE,MAAM,iDAAiD,CAAC;AAC/F,YAAY,EAAE,iCAAiC,EAAE,MAAM,iDAAiD,CAAC;AAEzG,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presentation/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACxF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,YAAY,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AACzF,YAAY,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AACnG,OAAO,EAAE,4BAA4B,EAAE,MAAM,iDAAiD,CAAC;AAC/F,YAAY,EAAE,iCAAiC,EAAE,MAAM,iDAAiD,CAAC;AAEzG,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EACV,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,gCAAgC,EAAE,MAAM,8CAA8C,CAAC;AAChG,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC"}

package/dist/presentation/index.js

@@ -1,6 +1,7 @@
 export { buildScanPresentationBundle } from "./orchestration/buildScanPresentationBundle.js";
 export { buildScanCardPresentation } from "./orchestration/buildScanCardPresentation.js";
 export { buildScanDetailsPresentation } from "./orchestration/buildScanDetailsPresentation.js";
+export { derivePresentationInterpretation } from "./intent/derivePresentationInterpretation.js";
 export { presentScanCard } from "./presenters/presentScanCard.js";
 export { presentPipelineScanCard } from "./presenters/presentPipelineScanCard.js";
 export { presentScanDetails } from "./presenters/presentScanDetails.js";

package/dist/presentation/intent/applyPostureVocabularyGuard.d.ts

@@ -0,0 +1,5 @@
+import type { PresentationStatus } from "../dto/types.js";
+export declare function guardHeadlineForPosture(headline: string, status: PresentationStatus, anchorPackage: string | null): string;
+export declare function applyPostureVocabularyGuardHeadline(headline: string, status: PresentationStatus | undefined, anchorPackage: string | null): string;
+export declare function applyPostureVocabularyGuardLines(lines: string[], status: PresentationStatus | undefined): string[];
+//# sourceMappingURL=applyPostureVocabularyGuard.d.ts.map

package/dist/presentation/intent/applyPostureVocabularyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyPostureVocabularyGuard.d.ts","sourceRoot":"","sources":["../../../src/presentation/intent/applyPostureVocabularyGuard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AA2B1D,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,EAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAYR;AASD,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAGR;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,MAAM,EAAE,CAGV"}

package/dist/presentation/intent/applyPostureVocabularyGuard.js

@@ -0,0 +1,44 @@
+import { scanSurfaceCopy } from "../../scanSurfaceCopy.js";
+import { formatPackageDisplayName } from "./packageDisplayName.js";
+const SAFE_FORBIDDEN = /\b(needs\s+review|critical\s+concern|high\s+risk|significant\s+impact|urgent\s+verification|severe\s+exposure|review\s+before\s+merge|wide\s+blast\s+radius)\b/i;
+const NEEDS_REVIEW_FORBIDDEN = /\b(no\s+action\s+required|no\s+verification\s+required|safe\s+to\s+merge|no\s+concerns)\b/i;
+const RISKY_FORBIDDEN = /\b(no\s+action\s+required|minor\s+findings\s+only|low\s+risk|no\s+concerns)\b/i;
+function violatesPosture(text, status) {
+    const t = text.trim();
+    if (!t)
+        return true;
+    switch (status) {
+        case "safe":
+            return SAFE_FORBIDDEN.test(t);
+        case "needs_review":
+            return NEEDS_REVIEW_FORBIDDEN.test(t);
+        case "risky":
+            return RISKY_FORBIDDEN.test(t);
+        default:
+            return false;
+    }
+}
+export function guardHeadlineForPosture(headline, status, anchorPackage) {
+    if (!violatesPosture(headline, status))
+        return headline;
+    const pkg = anchorPackage
+        ? formatPackageDisplayName(anchorPackage)
+        : "Dependency";
+    if (status === "safe") {
+        return scanSurfaceCopy.presentation.safeNeutralHeadline.replace("{package}", pkg);
+    }
+    return headline;
+}
+function guardLinesForPosture(lines, status) {
+    return lines.filter((line) => !violatesPosture(line, status));
+}
+export function applyPostureVocabularyGuardHeadline(headline, status, anchorPackage) {
+    if (!status)
+        return headline;
+    return guardHeadlineForPosture(headline, status, anchorPackage);
+}
+export function applyPostureVocabularyGuardLines(lines, status) {
+    if (!status)
+        return lines;
+    return guardLinesForPosture(lines, status);
+}

package/dist/presentation/intent/derivePresentationInterpretation.d.ts

@@ -0,0 +1,4 @@
+import type { ScanNarrativeFacts } from "../../scanNarrativeFacts.js";
+import type { PresentationInterpretation } from "./presentationIntent.js";
+export declare function derivePresentationInterpretation(facts: ScanNarrativeFacts): PresentationInterpretation;
+//# sourceMappingURL=derivePresentationInterpretation.d.ts.map

package/dist/presentation/intent/derivePresentationInterpretation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivePresentationInterpretation.d.ts","sourceRoot":"","sources":["../../../src/presentation/intent/derivePresentationInterpretation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAMV,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,yBAAyB,CAAC;AAsJjC,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,kBAAkB,GACxB,0BAA0B,CAkG5B"}

package/dist/presentation/intent/derivePresentationInterpretation.js

@@ -0,0 +1,202 @@
+import { formatCardAreaLabels } from "../../formatCardAreaLabels.js";
+import { mergeVerificationFocusLabels } from "./verificationFocusLabels.js";
+const TOOLING_CLASSES = new Set([
+    "tooling",
+    "test",
+    "lint",
+    "format",
+    "build",
+    "ci",
+]);
+const RUNTIME_IMPACT_RANK = {
+    confirmed: 3,
+    possible: 2,
+    unknown: 1,
+    none: 0,
+};
+const EVIDENCE_RANK = {
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+function isRuntimeEligible(row) {
+    if (row.suppressRuntimeNarrative)
+        return false;
+    if (row.runtimeImpact === "confirmed" || row.runtimeImpact === "possible") {
+        return true;
+    }
+    if (row.dependencyClass === "runtime")
+        return true;
+    if (row.usagePathCount > 0)
+        return true;
+    return false;
+}
+function isToolingOriented(row) {
+    if (row.suppressRuntimeNarrative)
+        return true;
+    if (row.dependencyClass && TOOLING_CLASSES.has(row.dependencyClass)) {
+        return true;
+    }
+    return false;
+}
+function compareRuntimePackages(a, b, order) {
+    const impactA = RUNTIME_IMPACT_RANK[a.runtimeImpact ?? "none"] ?? 0;
+    const impactB = RUNTIME_IMPACT_RANK[b.runtimeImpact ?? "none"] ?? 0;
+    if (impactB !== impactA)
+        return impactB - impactA;
+    const evA = EVIDENCE_RANK[a.evidenceStrength ?? "low"] ?? 0;
+    const evB = EVIDENCE_RANK[b.evidenceStrength ?? "low"] ?? 0;
+    if (evB !== evA)
+        return evB - evA;
+    return order.indexOf(a.packageName) - order.indexOf(b.packageName);
+}
+function pickAnchorPackage(rows, changedOrder) {
+    if (rows.length === 0)
+        return null;
+    const sorted = [...rows].sort((a, b) => compareRuntimePackages(a, b, changedOrder));
+    return sorted[0]?.packageName ?? null;
+}
+function pickToolingAnchor(rows, changedOrder) {
+    if (rows.length === 0)
+        return null;
+    const sorted = [...rows].sort((a, b) => changedOrder.indexOf(a.packageName) - changedOrder.indexOf(b.packageName));
+    return sorted[0]?.packageName ?? null;
+}
+function isToolingPatchSet(rows, facts) {
+    if (rows.length === 0)
+        return false;
+    const narrow = !facts.blastRadius || facts.blastRadius.level === "narrow";
+    if (!narrow)
+        return false;
+    return rows.every((row) => row.suppressRuntimeNarrative &&
+        (row.expectedImpact === "typecheck" ||
+            row.expectedImpact === "build_time"));
+}
+function runtimeSurfaceLabelFromFacts(facts, anchorRow) {
+    const area = facts.affectedAreas[0];
+    if (area) {
+        const formatted = formatCardAreaLabels([area.label], 1);
+        return formatted[0] ?? area.label;
+    }
+    if (anchorRow?.packageRole === "http_framework") {
+        return "API request handling";
+    }
+    if (anchorRow?.packageRole === "auth") {
+        return "authentication flows";
+    }
+    if (anchorRow?.packageRole === "queue") {
+        return "background job processing";
+    }
+    return "application code";
+}
+function collectVerificationLabels(rows) {
+    return mergeVerificationFocusLabels(rows.map((r) => r.verificationFocus));
+}
+function showLimitedEvidence(rows) {
+    return rows.some((r) => r.evidenceStrength === "low");
+}
+function dominantExpectedImpact(rows) {
+    for (const row of rows) {
+        if (row.expectedImpact && row.expectedImpact !== "unknown") {
+            return row.expectedImpact;
+        }
+    }
+    return null;
+}
+function emptyInterpretation(intent) {
+    return {
+        intent,
+        anchorPackage: null,
+        suppressRuntimeNarrative: intent.startsWith("tooling"),
+        allowRuntimeNarrative: intent.includes("runtime"),
+        showLimitedEvidence: false,
+        expectedImpactKey: null,
+        verificationLabels: [],
+        runtimeSurfaceLabel: null,
+        runtimePackages: [],
+    };
+}
+export function derivePresentationInterpretation(facts) {
+    const changedOrder = facts.changedPackages.all;
+    const semantics = facts.changedPackageSemantics.length > 0
+        ? facts.changedPackageSemantics
+        : facts.packageSemantics && facts.changedPackages.primary
+            ? [
+                {
+                    packageName: facts.changedPackages.primary,
+                    dependencyClass: facts.packageSemantics.dependencyClass,
+                    packageRole: facts.packageSemantics.packageRole,
+                    runtimeImpact: facts.packageSemantics.runtimeImpact,
+                    expectedImpact: facts.packageSemantics.expectedImpact,
+                    suppressRuntimeNarrative: facts.packageSemantics.suppressRuntimeNarrative,
+                    evidenceStrength: facts.packageSemantics.evidenceStrength,
+                    verificationFocus: facts.packageSemantics.verificationFocus,
+                    usagePathCount: 0,
+                    usageAreaCount: 0,
+                },
+            ]
+            : [];
+    const tier1Ok = facts.availability.tiersPresent.tier1 &&
+        facts.availability.repoIntelligenceParse === "ok";
+    if (!tier1Ok) {
+        return emptyInterpretation("limited_context");
+    }
+    if (!facts.changedPackages.primary) {
+        return emptyInterpretation("no_changed_packages");
+    }
+    const runtimeEligible = semantics.filter(isRuntimeEligible);
+    if (runtimeEligible.length > 0) {
+        const anchorPackage = pickAnchorPackage(runtimeEligible, changedOrder);
+        const anchorRow = runtimeEligible.find((r) => r.packageName === anchorPackage);
+        const runtimeSurfaceLabel = runtimeSurfaceLabelFromFacts(facts, anchorRow);
+        const verificationLabels = collectVerificationLabels(runtimeEligible);
+        let intent = "runtime_upgrade";
+        if (runtimeEligible.length > 1) {
+            intent = "multi_runtime_upgrade";
+        }
+        else if (runtimeEligible.some((r) => r.packageRole === "auth")) {
+            intent = "auth_runtime_upgrade";
+        }
+        else if (runtimeEligible.some((r) => r.packageRole === "queue")) {
+            intent = "queue_runtime_upgrade";
+        }
+        return {
+            intent,
+            anchorPackage,
+            suppressRuntimeNarrative: false,
+            allowRuntimeNarrative: true,
+            showLimitedEvidence: showLimitedEvidence(runtimeEligible),
+            expectedImpactKey: dominantExpectedImpact(runtimeEligible),
+            verificationLabels,
+            runtimeSurfaceLabel,
+            runtimePackages: runtimeEligible.map((r) => r.packageName),
+        };
+    }
+    const toolingOnly = semantics.length > 0 && semantics.every(isToolingOriented);
+    if (toolingOnly) {
+        const anchorPackage = pickToolingAnchor(semantics, changedOrder);
+        const isPatch = isToolingPatchSet(semantics, facts);
+        const intent = isPatch
+            ? "tooling_patch"
+            : "tooling_upgrade";
+        const anchorRow = semantics.find((r) => r.packageName === anchorPackage);
+        return {
+            intent,
+            anchorPackage,
+            suppressRuntimeNarrative: true,
+            allowRuntimeNarrative: false,
+            showLimitedEvidence: showLimitedEvidence(semantics),
+            expectedImpactKey: anchorRow?.expectedImpact ?? null,
+            verificationLabels: collectVerificationLabels(semantics),
+            runtimeSurfaceLabel: null,
+            runtimePackages: [],
+        };
+    }
+    return {
+        ...emptyInterpretation("unknown_upgrade"),
+        anchorPackage: facts.changedPackages.primary,
+        verificationLabels: collectVerificationLabels(semantics),
+        showLimitedEvidence: showLimitedEvidence(semantics),
+        expectedImpactKey: dominantExpectedImpact(semantics),
+    };
+}

package/dist/presentation/intent/formatPresentationCopy.d.ts

@@ -0,0 +1,7 @@
+import type { ScanNarrativeFacts } from "../../scanNarrativeFacts.js";
+import type { PresentationStatus } from "../dto/types.js";
+import type { PresentationInterpretation } from "./presentationIntent.js";
+export declare function formatPresentationHeadline(interpretation: PresentationInterpretation, facts: ScanNarrativeFacts, status: PresentationStatus | undefined): string;
+export declare function formatPresentationKeyPoints(interpretation: PresentationInterpretation, facts: ScanNarrativeFacts, status: PresentationStatus | undefined, max: number): string[];
+export declare function formatPresentationVerification(interpretation: PresentationInterpretation, status: PresentationStatus | undefined, max: number): string[];
+//# sourceMappingURL=formatPresentationCopy.d.ts.map

package/dist/presentation/intent/formatPresentationCopy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatPresentationCopy.d.ts","sourceRoot":"","sources":["../../../src/presentation/intent/formatPresentationCopy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAM1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAa1E,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,0BAA0B,EAC1C,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,MAAM,CAmDR;AA0BD,wBAAgB,2BAA2B,CACzC,cAAc,EAAE,0BAA0B,EAC1C,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAmEV;AAuBD,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,0BAA0B,EAC1C,MAAM,EAAE,kBAAkB,GAAG,SAAS,EACtC,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAmBV"}

package/dist/presentation/intent/formatPresentationCopy.js

@@ -0,0 +1,153 @@
+import { scanSurfaceCopy } from "../../scanSurfaceCopy.js";
+import { applyPostureVocabularyGuardHeadline, applyPostureVocabularyGuardLines, } from "./applyPostureVocabularyGuard.js";
+import { formatPackageDisplayName } from "./packageDisplayName.js";
+function anchorSemantics(facts, interpretation) {
+    const name = interpretation.anchorPackage;
+    if (!name)
+        return null;
+    return (facts.changedPackageSemantics.find((r) => r.packageName === name) ?? null);
+}
+export function formatPresentationHeadline(interpretation, facts, status) {
+    const anchor = interpretation.anchorPackage ?? facts.changedPackages.primary;
+    const row = anchorSemantics(facts, interpretation);
+    const pkgDisplay = formatPackageDisplayName(anchor ?? "dependency", row?.packageRole);
+    const copy = scanSurfaceCopy.presentation;
+    let headline;
+    switch (interpretation.intent) {
+        case "limited_context":
+            headline = copy.limitedContextHeadline;
+            break;
+        case "no_changed_packages":
+            headline = copy.noChangedPackagesHeadline;
+            break;
+        case "tooling_patch":
+            headline = copy.toolingPatchHeadline.replace("{package}", pkgDisplay);
+            break;
+        case "tooling_upgrade":
+            headline = copy.toolingUpgradeHeadline.replace("{package}", pkgDisplay);
+            break;
+        case "multi_runtime_upgrade":
+            headline = copy.multiRuntimeHeadline;
+            break;
+        case "auth_runtime_upgrade":
+        case "queue_runtime_upgrade":
+        case "runtime_upgrade": {
+            const surface = interpretation.runtimeSurfaceLabel ?? "application code";
+            headline = copy.runtimeUpgradeHeadline
+                .replace("{package}", pkgDisplay)
+                .replace("{surface}", surface);
+            break;
+        }
+        case "unknown_upgrade":
+            if (status === "safe") {
+                headline = copy.safeNeutralHeadline.replace("{package}", pkgDisplay);
+            }
+            else {
+                headline = copy.defaultUpgradeHeadline.replace("{package}", pkgDisplay);
+            }
+            break;
+        default:
+            headline = copy.safeNeutralHeadline.replace("{package}", pkgDisplay);
+    }
+    return applyPostureVocabularyGuardHeadline(headline, status, interpretation.anchorPackage);
+}
+function formatExpectedImpactKeyPoint(interpretation) {
+    if (interpretation.intent !== "tooling_patch" &&
+        interpretation.intent !== "tooling_upgrade") {
+        return null;
+    }
+    const key = interpretation.expectedImpactKey;
+    let workflows = "build and typecheck workflows";
+    if (key === "test_time")
+        workflows = "test workflows";
+    else if (key === "development_only")
+        workflows = "development workflows";
+    else if (key === "build_time")
+        workflows = "build workflows";
+    return scanSurfaceCopy.presentation.expectedImpactLimitedKeyPoint.replace("{workflows}", workflows);
+}
+function formatLimitedEvidenceKeyPoint() {
+    return scanSurfaceCopy.presentation.limitedEvidenceKeyPoint;
+}
+export function formatPresentationKeyPoints(interpretation, facts, status, max) {
+    const points = [];
+    if (interpretation.intent === "limited_context") {
+        points.push(scanSurfaceCopy.presentation.limitedContextKeyPoint);
+        if (facts.changedPackages.primary) {
+            points.push(scanSurfaceCopy.presentation.changedPackageKeyPoint.replace("{package}", facts.changedPackages.primary));
+        }
+        return applyPostureVocabularyGuardLines(points, status).slice(0, max);
+    }
+    if (interpretation.showLimitedEvidence) {
+        points.push(formatLimitedEvidenceKeyPoint());
+    }
+    if (interpretation.suppressRuntimeNarrative) {
+        points.push(scanSurfaceCopy.presentation.noRuntimePathsKeyPoint);
+        const impact = formatExpectedImpactKeyPoint(interpretation);
+        if (impact)
+            points.push(impact);
+    }
+    else if (interpretation.allowRuntimeNarrative) {
+        const usage = facts.packageUsage.find((u) => u.packageName === interpretation.anchorPackage);
+        const paths = [...(usage?.paths ?? []), ...(usage?.criticalPaths ?? [])];
+        if (paths.length > 0) {
+            points.push(scanSurfaceCopy.presentation.usedInRuntimePathsKeyPoint.replace("{count}", String(paths.length)));
+        }
+        else {
+            points.push(scanSurfaceCopy.presentation.runtimeUsageKeyPoint);
+        }
+        if (facts.affectedAreas.length > 0) {
+            const labels = facts.affectedAreas
+                .slice(0, 2)
+                .map((a) => a.label)
+                .join(", ");
+            points.push(scanSurfaceCopy.presentation.affectedAreasKeyPoint.replace("{areas}", labels));
+        }
+        const blast = facts.blastRadius;
+        if (blast?.level === "wide") {
+            points.push(scanSurfaceCopy.presentation.blastRadiusWideKeyPoint);
+        }
+        else if (blast?.level === "moderate") {
+            points.push(scanSurfaceCopy.presentation.blastRadiusLevelKeyPoint.replace("{level}", "Moderate"));
+        }
+    }
+    return applyPostureVocabularyGuardLines(points, status).slice(0, max);
+}
+const AUTH_VERIFICATION = [
+    "routes",
+    "middleware/hooks",
+    "auth flow",
+    "serialization",
+    "error handling",
+];
+const QUEUE_VERIFICATION = [
+    "workers",
+    "queue",
+    "serialization",
+    "error handling",
+];
+const RUNTIME_DEFAULT_VERIFICATION = [
+    "routes",
+    "middleware/hooks",
+    "error handling",
+];
+export function formatPresentationVerification(interpretation, status, max) {
+    let actions = [];
+    if (interpretation.verificationLabels.length > 0) {
+        actions = [...interpretation.verificationLabels];
+    }
+    else if (interpretation.intent === "auth_runtime_upgrade") {
+        actions = [...AUTH_VERIFICATION];
+    }
+    else if (interpretation.intent === "queue_runtime_upgrade") {
+        actions = [...QUEUE_VERIFICATION];
+    }
+    else if (interpretation.allowRuntimeNarrative) {
+        actions = [...RUNTIME_DEFAULT_VERIFICATION];
+    }
+    else if (interpretation.intent === "tooling_patch" ||
+        interpretation.intent === "tooling_upgrade") {
+        actions = ["CI", "typecheck", "build"];
+    }
+    return applyPostureVocabularyGuardLines(actions, status).slice(0, max);
+}

package/dist/presentation/intent/packageDisplayName.d.ts

@@ -0,0 +1,4 @@
+import type { PackageRoleKind } from "../../scanNarrativeFacts.js";
+/** Display name from package role when engine classified it; else title-case package name. */
+export declare function formatPackageDisplayName(packageName: string, packageRole?: PackageRoleKind | null): string;
+//# sourceMappingURL=packageDisplayName.d.ts.map

package/dist/presentation/intent/packageDisplayName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageDisplayName.d.ts","sourceRoot":"","sources":["../../../src/presentation/intent/packageDisplayName.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AASnE,8FAA8F;AAC9F,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,GACnC,MAAM,CAOR"}