@mergesignal/shared 0.2.6 → 0.2.8

package/dist/presentScanCardSummary.d.ts

@@ -0,0 +1,16 @@
+import { type ScanCardSummary, type ScanPipelineStatus } from "./scanCardSummary.js";
+import type { ScanNarrativeFacts } from "./scanNarrativeFacts.js";
+import { type CardExposureDisplay } from "./formatCardExposureDisplay.js";
+import { type MergePosture } from "./riskVocabulary.js";
+import type { ScanResult } from "./types.js";
+export type PresentScanCardSummaryOptions = {
+    pipelineStatus?: ScanPipelineStatus;
+    findings?: ScanResult["findings"];
+};
+/**
+ * Dashboard card presentation DTO from consumer-agnostic facts.
+ */
+export declare function presentScanCardSummary(facts: ScanNarrativeFacts, options?: PresentScanCardSummaryOptions): ScanCardSummary;
+export type { CardExposureDisplay, MergePosture };
+export declare function exposureFromFacts(facts: ScanNarrativeFacts): CardExposureDisplay | null;
+//# sourceMappingURL=presentScanCardSummary.d.ts.map

package/dist/presentScanCardSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentScanCardSummary.d.ts","sourceRoot":"","sources":["../src/presentScanCardSummary.ts"],"names":[],"mappings":"AAKA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAkBxC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,6BAA6B,GAAG;IAC1C,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CACnC,CAAC;AA2HF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,6BAAkC,GAC1C,eAAe,CA8HjB;AAED,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAElD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,GAAG,IAAI,CAE5B"}

package/dist/presentScanCardSummary.js

@@ -0,0 +1,212 @@
+import { isCatalogPhrase, phraseForFamily, } from "./cardObservationCatalog.js";
+import { aggregateFindingCounts, deriveRiskIndexBand, SCAN_CARD_SCANNING_SUMMARY, } from "./scanCardSummary.js";
+import { deriveCardExposureDisplay, } from "./formatCardExposureDisplay.js";
+import { formatCardAreaLabels } from "./formatCardAreaLabels.js";
+import { composeContextLineFromFacts, composeVerificationPrompt, formatBlastRadiusDetailLine, formatChangedPackagesShort, formatFrameworksSummary, formatUsageSummaryLine, labelBlastRadiusLevel, labelReachabilityKind, labelRuntimeSurface, } from "./narrativePresentation.js";
+import { normalizeGeneratedText, normalizeGeneratedTextNullable, } from "./normalizeGeneratedText.js";
+import { MERGE_POSTURE_LABEL } from "./riskVocabulary.js";
+import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
+function formatAffectedAreaLabels(facts) {
+    const ordered = [];
+    for (const area of facts.affectedAreas) {
+        const formatted = formatCardAreaLabels([area.label], 1);
+        if (formatted[0])
+            ordered.push(formatted[0]);
+        if (ordered.length >= 2)
+            break;
+    }
+    return ordered;
+}
+function selectPrimaryInsight(facts) {
+    const changedGuidance = facts.reviewerGuidance.find((g) => g.scope === "changed" && g.message.trim());
+    if (changedGuidance)
+        return changedGuidance.message.trim();
+    const insight = facts.reviewerGuidance.find((g) => g.kind === "insight" && g.message.trim());
+    if (insight)
+        return insight.message.trim();
+    return null;
+}
+function selectSecondaryLines(facts, exclude) {
+    const lines = [];
+    for (const g of facts.reviewerGuidance) {
+        const msg = g.message.trim();
+        if (!msg || msg === exclude)
+            continue;
+        lines.push(msg);
+        if (lines.length >= 2)
+            break;
+    }
+    return lines;
+}
+function repositoryContextPhrases(facts, max) {
+    const phrases = [];
+    const seen = new Set();
+    for (const ctx of facts.repositoryContext) {
+        const phrase = phraseForFamily(ctx.family);
+        if (seen.has(phrase))
+            continue;
+        seen.add(phrase);
+        phrases.push(phrase);
+        if (phrases.length >= max)
+            break;
+    }
+    return phrases;
+}
+function buildLegacyObservations(facts, primaryInsight, repoPhraseCap) {
+    const repoPhrases = repositoryContextPhrases(facts, repoPhraseCap);
+    const secondary = selectSecondaryLines(facts, primaryInsight);
+    if (primaryInsight) {
+        return {
+            operationalObservations: repoPhrases.slice(0, 1),
+            supportingLine: repoPhrases[0] && repoPhrases[0] !== primaryInsight
+                ? repoPhrases[0]
+                : (secondary[0] ?? null),
+        };
+    }
+    if (repoPhrases.length === 0) {
+        return { operationalObservations: [], supportingLine: null };
+    }
+    return {
+        operationalObservations: repoPhrases.slice(0, repoPhraseCap),
+        supportingLine: repoPhrases.length === 1 ? (secondary[0] ?? null) : null,
+    };
+}
+function normalizeCardSummary(summary) {
+    return {
+        ...summary,
+        headline: normalizeGeneratedText(summary.headline),
+        summaryLine: normalizeGeneratedTextNullable(summary.summaryLine),
+        supportingLine: normalizeGeneratedTextNullable(summary.supportingLine),
+        changedPackagesDisplay: normalizeGeneratedTextNullable(summary.changedPackagesDisplay),
+        runtimeSurfaceLabel: normalizeGeneratedTextNullable(summary.runtimeSurfaceLabel),
+        reachabilityLabel: normalizeGeneratedTextNullable(summary.reachabilityLabel),
+        blastRadiusLabel: normalizeGeneratedTextNullable(summary.blastRadiusLabel),
+        primaryInsight: normalizeGeneratedTextNullable(summary.primaryInsight),
+        structuralOnlyDisclaimer: normalizeGeneratedTextNullable(summary.structuralOnlyDisclaimer),
+        usageSummary: normalizeGeneratedTextNullable(summary.usageSummary),
+        verificationLine: normalizeGeneratedTextNullable(summary.verificationLine),
+        blastRadiusDetail: normalizeGeneratedTextNullable(summary.blastRadiusDetail),
+        frameworksSummary: normalizeGeneratedTextNullable(summary.frameworksSummary),
+        affectedAreas: summary.affectedAreas.map((a) => normalizeGeneratedText(a)),
+        topAffectedAreas: summary.topAffectedAreas.map((a) => normalizeGeneratedText(a)),
+        operationalObservations: summary.operationalObservations.map((p) => {
+            const normalized = normalizeGeneratedText(p);
+            return isCatalogPhrase(normalized) ? normalized : p;
+        }),
+    };
+}
+/**
+ * Dashboard card presentation DTO from consumer-agnostic facts.
+ */
+export function presentScanCardSummary(facts, options = {}) {
+    const pipelineStatus = options.pipelineStatus ?? "done";
+    const emptyPresentationFields = {
+        narrativeMode: facts.availability.mode,
+        codeIntelligenceAvailable: facts.availability.codeIntelligenceAvailable,
+        changedPackagesDisplay: null,
+        runtimeSurfaceLabel: null,
+        reachabilityLabel: null,
+        blastRadiusLabel: null,
+        affectedAreas: [],
+        primaryInsight: null,
+        structuralOnlyDisclaimer: null,
+        usageSummary: null,
+        verificationLine: null,
+        blastRadiusDetail: null,
+        frameworksSummary: null,
+    };
+    if (pipelineStatus === "queued" || pipelineStatus === "running") {
+        return normalizeCardSummary({
+            mergePosture: null,
+            riskIndex: null,
+            riskIndexBand: null,
+            headline: scanSurfaceCopy.pipeline.scanRunning,
+            summaryLine: SCAN_CARD_SCANNING_SUMMARY,
+            findingCounts: null,
+            topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
+            ...emptyPresentationFields,
+        });
+    }
+    if (pipelineStatus === "failed") {
+        return normalizeCardSummary({
+            mergePosture: null,
+            riskIndex: null,
+            riskIndexBand: null,
+            headline: scanSurfaceCopy.pipeline.analysisIncomplete,
+            summaryLine: null,
+            findingCounts: null,
+            topAffectedAreas: [],
+            operationalObservations: [],
+            supportingLine: null,
+            ...emptyPresentationFields,
+        });
+    }
+    const posture = facts.mergePosture;
+    const riskIndex = facts.riskIndex;
+    const riskIndexBand = deriveRiskIndexBand(riskIndex);
+    const headline = posture
+        ? MERGE_POSTURE_LABEL[posture]
+        : scanSurfaceCopy.checkRun.mergePostureUnavailable;
+    const findingCounts = options.findings
+        ? aggregateFindingCounts(options.findings)
+        : null;
+    const prIntelligence = facts.availability.mode === "pr_intelligence" ||
+        facts.availability.tiersPresent.tier1;
+    const changedPackagesDisplay = formatChangedPackagesShort(facts, 2);
+    const runtimeSurfaceLabel = labelRuntimeSurface(facts);
+    const reachabilityLabel = labelReachabilityKind(facts);
+    const blastRadiusLabel = labelBlastRadiusLevel(facts);
+    const affectedAreas = formatAffectedAreaLabels(facts);
+    const contextLine = composeContextLineFromFacts(facts, {
+        includePathSample: prIntelligence,
+        maxAreas: 2,
+    });
+    const structuralOnlyDisclaimer = facts.availability.mode === "graph_fallback" &&
+        !facts.availability.tiersPresent.tier1
+        ? scanSurfaceCopy.narrativeCard.structuralOnlyDisclaimer
+        : null;
+    const insightMessage = selectPrimaryInsight(facts);
+    const primaryInsight = insightMessage ??
+        (facts.availability.mode !== "graph_fallback" ? contextLine : null);
+    const usageSummary = prIntelligence ? formatUsageSummaryLine(facts, 1) : null;
+    const verificationLine = prIntelligence
+        ? composeVerificationPrompt(facts)
+        : null;
+    const blastRadiusDetail = prIntelligence
+        ? formatBlastRadiusDetailLine(facts, 1)
+        : null;
+    const frameworksSummary = prIntelligence
+        ? formatFrameworksSummary(facts, 2)
+        : null;
+    const repoPhraseCap = prIntelligence ? 0 : 3;
+    const { operationalObservations, supportingLine } = buildLegacyObservations(facts, primaryInsight, repoPhraseCap);
+    return normalizeCardSummary({
+        mergePosture: posture,
+        riskIndex,
+        riskIndexBand,
+        headline,
+        summaryLine: null,
+        findingCounts,
+        topAffectedAreas: affectedAreas,
+        operationalObservations,
+        supportingLine,
+        narrativeMode: facts.availability.mode,
+        codeIntelligenceAvailable: facts.availability.codeIntelligenceAvailable,
+        changedPackagesDisplay,
+        runtimeSurfaceLabel,
+        reachabilityLabel,
+        blastRadiusLabel,
+        affectedAreas,
+        primaryInsight,
+        structuralOnlyDisclaimer,
+        usageSummary,
+        verificationLine,
+        blastRadiusDetail,
+        frameworksSummary,
+    });
+}
+export function exposureFromFacts(facts) {
+    return deriveCardExposureDisplay(facts.riskIndex) ?? null;
+}

package/dist/productMessaging.d.ts

@@ -71,7 +71,7 @@ export declare const productMessaging: {
         readonly exposure: "Exposure indicates how broadly the upgrade touches runtime-relevant application areas.";
         readonly exposureCategoriesLead: "On each scanned card, exposure reads as one of:";
         readonly exposureCategories: readonly string[];
-        readonly cardBody: "Below the verdict, scanned cards surface up to three compact operational observations (transitive volume, blast radius, duplicate versions, and related topology signals) when the engine finds mappable structure.";
+        readonly cardBody: "Below the verdict, scanned cards lead with the changed package, runtime surface, reachability, blast radius, and affected areas when code intelligence is available; repository-wide graph signals appear only as supporting context.";
     };
 };
 /** Illustrative scan-card example for homepage proof band and getting-started. */

package/dist/productMessaging.js

@@ -86,7 +86,7 @@ export const productMessaging = {
         exposure: "Exposure indicates how broadly the upgrade touches runtime-relevant application areas.",
         exposureCategoriesLead: "On each scanned card, exposure reads as one of:",
         exposureCategories: CARD_EXPOSURE_CATEGORY_LABELS,
-        cardBody: "Below the verdict, scanned cards surface up to three compact operational observations (transitive volume, blast radius, duplicate versions, and related topology signals) when the engine finds mappable structure.",
+        cardBody: "Below the verdict, scanned cards lead with the changed package, runtime surface, reachability, blast radius, and affected areas when code intelligence is available; repository-wide graph signals appear only as supporting context.",
     },
 };
 /** Illustrative scan-card example for homepage proof band and getting-started. */

package/dist/repoIntelligenceSchema.d.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import type { BlastRadiusLevel, ReachabilityKind, RuntimeSurfaceKind } from "./scanNarrativeFacts.js";
+declare const looseSurfaceSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    unknown: "unknown";
+    runtime: "runtime";
+    build: "build";
+    test: "test";
+}>, z.ZodString, z.ZodObject<{
+    kind: z.ZodString;
+}, z.core.$loose>]>;
+declare const looseReachabilitySchema: z.ZodUnion<readonly [z.ZodEnum<{
+    unknown: "unknown";
+    on_runtime_paths: "on_runtime_paths";
+    build_only: "build_only";
+    test_only: "test_only";
+    unreachable: "unreachable";
+}>, z.ZodString, z.ZodObject<{
+    kind: z.ZodString;
+}, z.core.$loose>]>;
+export declare const repoIntelligenceSchema: z.ZodObject<{
+    packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        runtimeSurface: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            unknown: "unknown";
+            runtime: "runtime";
+            build: "build";
+            test: "test";
+        }>, z.ZodString, z.ZodObject<{
+            kind: z.ZodString;
+        }, z.core.$loose>]>>;
+        reachability: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            unknown: "unknown";
+            on_runtime_paths: "on_runtime_paths";
+            build_only: "build_only";
+            test_only: "test_only";
+            unreachable: "unreachable";
+        }>, z.ZodString, z.ZodObject<{
+            kind: z.ZodString;
+        }, z.core.$loose>]>>;
+        packageUsage: z.ZodOptional<z.ZodObject<{
+            packageName: z.ZodOptional<z.ZodString>;
+            package: z.ZodOptional<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            criticalPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>>;
+        usage: z.ZodOptional<z.ZodObject<{
+            packageName: z.ZodOptional<z.ZodString>;
+            package: z.ZodOptional<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            criticalPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>>;
+        areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        hotspots: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            packageName: z.ZodOptional<z.ZodString>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            depth: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    packageUsage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        packageName: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        criticalPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>>;
+    blastRadius: z.ZodOptional<z.ZodObject<{
+        level: z.ZodOptional<z.ZodEnum<{
+            moderate: "moderate";
+            narrow: "narrow";
+            wide: "wide";
+        }>>;
+        factors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        changedPackageCount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    runtimeSurface: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        unknown: "unknown";
+        runtime: "runtime";
+        build: "build";
+        test: "test";
+    }>, z.ZodString, z.ZodObject<{
+        kind: z.ZodString;
+    }, z.core.$loose>]>>;
+    reachability: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        unknown: "unknown";
+        on_runtime_paths: "on_runtime_paths";
+        build_only: "build_only";
+        test_only: "test_only";
+        unreachable: "unreachable";
+    }>, z.ZodString, z.ZodObject<{
+        kind: z.ZodString;
+    }, z.core.$loose>]>>;
+    applicationAreas: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$loose>>>;
+    affectedAreas: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$loose>>>;
+    hotspots: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        packageName: z.ZodString;
+        source: z.ZodOptional<z.ZodEnum<{
+            code: "code";
+            graph: "graph";
+        }>>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>>;
+    frameworks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type RepoIntelligence = z.infer<typeof repoIntelligenceSchema>;
+export declare function parseRepoIntelligence(raw: unknown): RepoIntelligence | null;
+export declare function normalizeRuntimeSurfaceKind(raw: string | undefined): RuntimeSurfaceKind;
+export declare function normalizeReachabilityKind(raw: string | undefined): ReachabilityKind;
+export declare function readSurfaceFromLoose(value: z.infer<typeof looseSurfaceSchema> | undefined): RuntimeSurfaceKind | null;
+export declare function readReachabilityFromLoose(value: z.infer<typeof looseReachabilitySchema> | undefined): ReachabilityKind | null;
+export declare function readBlastLevel(level: BlastRadiusLevel | undefined): BlastRadiusLevel | null;
+export {};
+//# sourceMappingURL=repoIntelligenceSchema.d.ts.map

package/dist/repoIntelligenceSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoIntelligenceSchema.d.ts","sourceRoot":"","sources":["../src/repoIntelligenceSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAcjC,QAAA,MAAM,kBAAkB;;;;;;;mBAItB,CAAC;AAEH,QAAA,MAAM,uBAAuB;;;;;;;;mBAI3B,CAAC;AAyCH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BnB,CAAC;AAEjB,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAc3E;AAuBD,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,kBAAkB,CAUpB;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,gBAAgB,CAgBlB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,GAAG,SAAS,GACpD,kBAAkB,GAAG,IAAI,CAO3B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,GAAG,SAAS,GACzD,gBAAgB,GAAG,IAAI,CAOzB;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,GAAG,SAAS,GAClC,gBAAgB,GAAG,IAAI,CAKzB"}

package/dist/repoIntelligenceSchema.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+const surfaceKindSchema = z.enum(["runtime", "build", "test", "unknown"]);
+const reachabilityKindSchema = z.enum([
+    "on_runtime_paths",
+    "build_only",
+    "test_only",
+    "unreachable",
+    "unknown",
+]);
+const blastLevelSchema = z.enum(["narrow", "moderate", "wide"]);
+const looseSurfaceSchema = z.union([
+    surfaceKindSchema,
+    z.string(),
+    z.object({ kind: z.string() }).passthrough(),
+]);
+const looseReachabilitySchema = z.union([
+    reachabilityKindSchema,
+    z.string(),
+    z.object({ kind: z.string() }).passthrough(),
+]);
+const packageUsageEntrySchema = z
+    .object({
+    packageName: z.string().optional(),
+    package: z.string().optional(),
+    files: z.array(z.string()).optional(),
+    paths: z.array(z.string()).optional(),
+    criticalPaths: z.array(z.string()).optional(),
+    areas: z.array(z.string()).optional(),
+})
+    .passthrough();
+const packageIntelSchema = z
+    .object({
+    runtimeSurface: looseSurfaceSchema.optional(),
+    reachability: looseReachabilitySchema.optional(),
+    packageUsage: packageUsageEntrySchema.optional(),
+    usage: packageUsageEntrySchema.optional(),
+    areas: z.array(z.string()).optional(),
+    hotspots: z
+        .array(z
+        .object({
+        packageName: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+        depth: z.number().optional(),
+    })
+        .passthrough())
+        .optional(),
+})
+    .passthrough();
+const areaSchema = z
+    .object({
+    id: z.string(),
+    label: z.string(),
+})
+    .passthrough();
+export const repoIntelligenceSchema = z
+    .object({
+    packages: z.record(z.string(), packageIntelSchema).optional(),
+    packageUsage: z.array(packageUsageEntrySchema).optional(),
+    blastRadius: z
+        .object({
+        level: blastLevelSchema.optional(),
+        factors: z.array(z.string()).optional(),
+        changedPackageCount: z.number().optional(),
+    })
+        .passthrough()
+        .optional(),
+    runtimeSurface: looseSurfaceSchema.optional(),
+    reachability: looseReachabilitySchema.optional(),
+    applicationAreas: z.array(areaSchema).optional(),
+    affectedAreas: z.array(areaSchema).optional(),
+    hotspots: z
+        .array(z
+        .object({
+        packageName: z.string(),
+        source: z.enum(["code", "graph"]).optional(),
+        depth: z.number().optional(),
+        paths: z.array(z.string()).optional(),
+    })
+        .passthrough())
+        .optional(),
+    frameworks: z.array(z.string()).optional(),
+})
+    .passthrough();
+export function parseRepoIntelligence(raw) {
+    if (raw == null || typeof raw !== "object")
+        return null;
+    const parsed = repoIntelligenceSchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    const value = parsed.data;
+    if (Object.keys(value).length === 0)
+        return null;
+    if (Object.keys(value).length === 1 &&
+        value.packages &&
+        Object.keys(value.packages).length === 0) {
+        return null;
+    }
+    return value;
+}
+const RUNTIME_SURFACE_ALIASES = [
+    [/\bruntime\b/i, "runtime"],
+    [/\bproduction\b/i, "runtime"],
+    [/\bapi\b/i, "runtime"],
+    [/\bbuild\b/i, "build"],
+    [/\bdev(?:elopment)?\b/i, "build"],
+    [/\btypescript\b/i, "build"],
+    [/\btest\b/i, "test"],
+    [/\bvitest\b/i, "test"],
+    [/\bjest\b/i, "test"],
+];
+const REACHABILITY_ALIASES = [
+    [/\bon[_\s-]?runtime/i, "on_runtime_paths"],
+    [/\bruntime[_\s-]?path/i, "on_runtime_paths"],
+    [/\bdirect\b/i, "on_runtime_paths"],
+    [/\bbuild[_\s-]?only/i, "build_only"],
+    [/\btest[_\s-]?only/i, "test_only"],
+    [/\bunreachable\b/i, "unreachable"],
+];
+export function normalizeRuntimeSurfaceKind(raw) {
+    if (!raw?.trim())
+        return "unknown";
+    const t = raw.trim().toLowerCase();
+    if (t === "runtime" || t === "build" || t === "test" || t === "unknown") {
+        return t;
+    }
+    for (const [re, kind] of RUNTIME_SURFACE_ALIASES) {
+        if (re.test(t))
+            return kind;
+    }
+    return "unknown";
+}
+export function normalizeReachabilityKind(raw) {
+    if (!raw?.trim())
+        return "unknown";
+    const t = raw.trim().toLowerCase();
+    if (t === "on_runtime_paths" ||
+        t === "build_only" ||
+        t === "test_only" ||
+        t === "unreachable" ||
+        t === "unknown") {
+        return t;
+    }
+    for (const [re, kind] of REACHABILITY_ALIASES) {
+        if (re.test(t))
+            return kind;
+    }
+    return "unknown";
+}
+export function readSurfaceFromLoose(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return normalizeRuntimeSurfaceKind(value);
+    if (typeof value === "object" && "kind" in value) {
+        return normalizeRuntimeSurfaceKind(String(value.kind));
+    }
+    return null;
+}
+export function readReachabilityFromLoose(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return normalizeReachabilityKind(value);
+    if (typeof value === "object" && "kind" in value) {
+        return normalizeReachabilityKind(String(value.kind));
+    }
+    return null;
+}
+export function readBlastLevel(level) {
+    if (level === "narrow" || level === "moderate" || level === "wide") {
+        return level;
+    }
+    return null;
+}

package/dist/riskVocabulary.js

@@ -34,7 +34,7 @@ export function mergePostureFromDecision(decision) {
     return null;
 }
 /** Returns the display label for a decision, or a fallback string. */
-export function mergePostureLabel(decision, fallback = "—") {
+export function mergePostureLabel(decision, fallback = "-") {
     const posture = mergePostureFromDecision(decision);
     return posture ? MERGE_POSTURE_LABEL[posture] : fallback;
 }

package/dist/scanCardSummary.d.ts

@@ -1,4 +1,5 @@
 import type { CatalogPhrase } from "./cardObservationCatalog.js";
+import type { NarrativeAvailabilityMode } from "./scanNarrativeFacts.js";
 import { type MergePosture } from "./riskVocabulary.js";
 import type { Finding, ScanResult } from "./types.js";
 export type ScanPipelineStatus = "queued" | "running" | "done" | "failed";
@@ -18,14 +19,31 @@ export type ScanCardSummary = {
     /** @deprecated Use operationalObservations */
     summaryLine: string | null;
     findingCounts: FindingCountSummary | null;
-    /** @deprecated Use operationalObservations */
+    /** @deprecated Use affectedAreas */
     topAffectedAreas: string[];
-    /** Catalog-mapped topology observations (0–3). */
+    /** Catalog-mapped topology observations (0–3). Tier 3 repo context — legacy wire field. */
     operationalObservations: CatalogPhrase[];
     /** Optional quiet subline when exactly one observation is shown. */
     supportingLine: string | null;
+    narrativeMode: NarrativeAvailabilityMode;
+    codeIntelligenceAvailable: boolean;
+    changedPackagesDisplay: string | null;
+    runtimeSurfaceLabel: string | null;
+    reachabilityLabel: string | null;
+    blastRadiusLabel: string | null;
+    affectedAreas: string[];
+    primaryInsight: string | null;
+    structuralOnlyDisclaimer: string | null;
+    /** One-line usage hint from packageUsage paths or areas. */
+    usageSummary: string | null;
+    /** Single verification prompt from changed-scope guidance or usage. */
+    verificationLine: string | null;
+    /** Optional blast factor subline when factors exist. */
+    blastRadiusDetail: string | null;
+    /** Short framework list (max 2 on card). */
+    frameworksSummary: string | null;
 };
-export declare const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results\u2026";
+export declare const SCAN_CARD_SCANNING_SUMMARY = "Waiting for results...";
 export type PipelineCompletionEvidence = {
     scannedAt?: string | null;
     decision?: string | null;

package/dist/scanCardSummary.d.ts.map

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