@mergesignal/shared 0.4.2 → 0.5.0

package/dist/assessmentSchema.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Assessment Contract — mirrored from mergesignal-engine/packages/analysis-engine/src/assessment/types.ts
+ * Bump {@link ASSESSMENT_ABI} when this schema changes incompatibly.
+ */
+import { z } from "zod";
+export declare const ASSESSMENT_ABI: "1";
+export declare const ASSESSMENT_POSTURES: readonly ["safe", "needs_review", "risky"];
+export type AssessmentPosture = (typeof ASSESSMENT_POSTURES)[number];
+export declare const ASSESSMENT_CONFIDENCES: readonly ["low", "medium", "high"];
+export type AssessmentConfidence = (typeof ASSESSMENT_CONFIDENCES)[number];
+export declare const CHANGE_CLASSES: readonly ["tooling_maintenance", "test_infra", "runtime_patch", "runtime_upgrade", "security_advisory", "breaking_change", "ecosystem_unknown", "bulk_mixed", "removal"];
+export type ChangeClass = (typeof CHANGE_CLASSES)[number];
+export declare const MERGE_CONCERN_KINDS: readonly ["confirmed_runtime_usage", "security_finding", "breaking_or_major", "behavioral_change", "ecosystem_risk", "insufficient_evidence", "graph_baseline_only"];
+export type MergeConcernKind = (typeof MERGE_CONCERN_KINDS)[number];
+export declare const NARRATIVE_INTENSITIES: readonly ["minimal", "standard", "elevated"];
+export type NarrativeIntensity = (typeof NARRATIVE_INTENSITIES)[number];
+export declare const REACH_VISIBILITIES: readonly ["hidden", "contextual", "prominent"];
+export type ReachVisibility = (typeof REACH_VISIBILITIES)[number];
+export declare const VERIFICATION_INTENSITIES: readonly ["none", "advisory", "required"];
+export type VerificationIntensity = (typeof VERIFICATION_INTENSITIES)[number];
+export declare const INSIGHT_EMISSION_FLOORS: readonly ["none", "explain_only", "full"];
+export type InsightEmissionFloor = (typeof INSIGHT_EMISSION_FLOORS)[number];
+export declare const ASSESSMENT_REPORT_MODES: readonly ["lightweight_pr_graph_baseline", "high_signal_pr"];
+export type AssessmentReportMode = (typeof ASSESSMENT_REPORT_MODES)[number];
+declare const assessmentConcernSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        confirmed_runtime_usage: "confirmed_runtime_usage";
+        security_finding: "security_finding";
+        breaking_or_major: "breaking_or_major";
+        behavioral_change: "behavioral_change";
+        ecosystem_risk: "ecosystem_risk";
+        insufficient_evidence: "insufficient_evidence";
+        graph_baseline_only: "graph_baseline_only";
+    }>;
+    rank: z.ZodNumber;
+    packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    evidenceRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const assessmentPresentationWireSchema: z.ZodObject<{
+    narrativeIntensity: z.ZodEnum<{
+        minimal: "minimal";
+        standard: "standard";
+        elevated: "elevated";
+    }>;
+    reachVisibility: z.ZodEnum<{
+        hidden: "hidden";
+        contextual: "contextual";
+        prominent: "prominent";
+    }>;
+    verificationIntensity: z.ZodEnum<{
+        none: "none";
+        advisory: "advisory";
+        required: "required";
+    }>;
+    insightEmissionFloor: z.ZodEnum<{
+        none: "none";
+        explain_only: "explain_only";
+        full: "full";
+    }>;
+    reportMode: z.ZodEnum<{
+        lightweight_pr_graph_baseline: "lightweight_pr_graph_baseline";
+        high_signal_pr: "high_signal_pr";
+    }>;
+}, z.core.$strip>;
+export declare const assessmentSchema: z.ZodObject<{
+    posture: z.ZodEnum<{
+        safe: "safe";
+        needs_review: "needs_review";
+        risky: "risky";
+    }>;
+    confidence: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    primaryConcern: z.ZodNullable<z.ZodEnum<{
+        confirmed_runtime_usage: "confirmed_runtime_usage";
+        security_finding: "security_finding";
+        breaking_or_major: "breaking_or_major";
+        behavioral_change: "behavioral_change";
+        ecosystem_risk: "ecosystem_risk";
+        insufficient_evidence: "insufficient_evidence";
+        graph_baseline_only: "graph_baseline_only";
+    }>>;
+    concerns: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            confirmed_runtime_usage: "confirmed_runtime_usage";
+            security_finding: "security_finding";
+            breaking_or_major: "breaking_or_major";
+            behavioral_change: "behavioral_change";
+            ecosystem_risk: "ecosystem_risk";
+            insufficient_evidence: "insufficient_evidence";
+            graph_baseline_only: "graph_baseline_only";
+        }>;
+        rank: z.ZodNumber;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        evidenceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    factors: z.ZodArray<z.ZodString>;
+    changeClasses: z.ZodArray<z.ZodEnum<{
+        tooling_maintenance: "tooling_maintenance";
+        test_infra: "test_infra";
+        runtime_patch: "runtime_patch";
+        runtime_upgrade: "runtime_upgrade";
+        security_advisory: "security_advisory";
+        breaking_change: "breaking_change";
+        ecosystem_unknown: "ecosystem_unknown";
+        bulk_mixed: "bulk_mixed";
+        removal: "removal";
+    }>>;
+    presentation: z.ZodObject<{
+        narrativeIntensity: z.ZodEnum<{
+            minimal: "minimal";
+            standard: "standard";
+            elevated: "elevated";
+        }>;
+        reachVisibility: z.ZodEnum<{
+            hidden: "hidden";
+            contextual: "contextual";
+            prominent: "prominent";
+        }>;
+        verificationIntensity: z.ZodEnum<{
+            none: "none";
+            advisory: "advisory";
+            required: "required";
+        }>;
+        insightEmissionFloor: z.ZodEnum<{
+            none: "none";
+            explain_only: "explain_only";
+            full: "full";
+        }>;
+        reportMode: z.ZodEnum<{
+            lightweight_pr_graph_baseline: "lightweight_pr_graph_baseline";
+            high_signal_pr: "high_signal_pr";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AssessmentConcern = z.infer<typeof assessmentConcernSchema>;
+export type AssessmentPresentationWire = z.infer<typeof assessmentPresentationWireSchema>;
+/** Public presentation subset — excludes engine policy fields. */
+export type AssessmentPresentationPublic = Pick<AssessmentPresentationWire, "narrativeIntensity" | "reachVisibility" | "verificationIntensity" | "reportMode">;
+export type Assessment = z.infer<typeof assessmentSchema>;
+export declare function toPublicPresentation(wire: AssessmentPresentationWire): AssessmentPresentationPublic;
+export declare function parseAssessmentOrThrow(data: unknown): Assessment;
+export declare function safeParseAssessment(data: unknown): {
+    ok: true;
+    value: Assessment;
+} | {
+    ok: false;
+    issues: string[];
+};
+/** Map engine narrative intensity to presentation density (formatting only). */
+export declare function narrativeIntensityToDensity(intensity: NarrativeIntensity): "minimal" | "standard" | "rich";
+export {};
+//# sourceMappingURL=assessmentSchema.d.ts.map

package/dist/assessmentSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessmentSchema.d.ts","sourceRoot":"","sources":["../src/assessmentSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,EAAG,GAAY,CAAC;AAE3C,eAAO,MAAM,mBAAmB,4CAA6C,CAAC;AAC9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,eAAO,MAAM,sBAAsB,oCAAqC,CAAC;AACzE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,eAAO,MAAM,cAAc,0KAUjB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB,sKAQtB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,eAAO,MAAM,qBAAqB,8CAIxB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,eAAO,MAAM,kBAAkB,gDAIrB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB,2CAI3B,CAAC;AACX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,eAAO,MAAM,uBAAuB,2CAI1B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,uBAAuB,8DAG1B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,QAAA,MAAM,uBAAuB;;;;;;;;;;;;;iBAK3B,CAAC;AAEH,QAAA,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;iBAMpC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ3B,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAC7C,0BAA0B,EACxB,oBAAoB,GACpB,iBAAiB,GACjB,uBAAuB,GACvB,YAAY,CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,0BAA0B,GAC/B,4BAA4B,CAO9B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAShE;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnE;AAED,gFAAgF;AAChF,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,kBAAkB,GAC5B,SAAS,GAAG,UAAU,GAAG,MAAM,CAIjC"}

package/dist/assessmentSchema.js

@@ -0,0 +1,110 @@
+/**
+ * Assessment Contract — mirrored from mergesignal-engine/packages/analysis-engine/src/assessment/types.ts
+ * Bump {@link ASSESSMENT_ABI} when this schema changes incompatibly.
+ */
+import { z } from "zod";
+export const ASSESSMENT_ABI = "1";
+export const ASSESSMENT_POSTURES = ["safe", "needs_review", "risky"];
+export const ASSESSMENT_CONFIDENCES = ["low", "medium", "high"];
+export const CHANGE_CLASSES = [
+    "tooling_maintenance",
+    "test_infra",
+    "runtime_patch",
+    "runtime_upgrade",
+    "security_advisory",
+    "breaking_change",
+    "ecosystem_unknown",
+    "bulk_mixed",
+    "removal",
+];
+export const MERGE_CONCERN_KINDS = [
+    "confirmed_runtime_usage",
+    "security_finding",
+    "breaking_or_major",
+    "behavioral_change",
+    "ecosystem_risk",
+    "insufficient_evidence",
+    "graph_baseline_only",
+];
+export const NARRATIVE_INTENSITIES = [
+    "minimal",
+    "standard",
+    "elevated",
+];
+export const REACH_VISIBILITIES = [
+    "hidden",
+    "contextual",
+    "prominent",
+];
+export const VERIFICATION_INTENSITIES = [
+    "none",
+    "advisory",
+    "required",
+];
+export const INSIGHT_EMISSION_FLOORS = [
+    "none",
+    "explain_only",
+    "full",
+];
+export const ASSESSMENT_REPORT_MODES = [
+    "lightweight_pr_graph_baseline",
+    "high_signal_pr",
+];
+const assessmentConcernSchema = z.object({
+    kind: z.enum(MERGE_CONCERN_KINDS),
+    rank: z.number().int().nonnegative(),
+    packages: z.array(z.string()).optional(),
+    evidenceRefs: z.array(z.string()),
+});
+const assessmentPresentationWireSchema = z.object({
+    narrativeIntensity: z.enum(NARRATIVE_INTENSITIES),
+    reachVisibility: z.enum(REACH_VISIBILITIES),
+    verificationIntensity: z.enum(VERIFICATION_INTENSITIES),
+    insightEmissionFloor: z.enum(INSIGHT_EMISSION_FLOORS),
+    reportMode: z.enum(ASSESSMENT_REPORT_MODES),
+});
+export const assessmentSchema = z.object({
+    posture: z.enum(ASSESSMENT_POSTURES),
+    confidence: z.enum(ASSESSMENT_CONFIDENCES),
+    primaryConcern: z.enum(MERGE_CONCERN_KINDS).nullable(),
+    concerns: z.array(assessmentConcernSchema),
+    factors: z.array(z.string()),
+    changeClasses: z.array(z.enum(CHANGE_CLASSES)),
+    presentation: assessmentPresentationWireSchema,
+});
+export function toPublicPresentation(wire) {
+    return {
+        narrativeIntensity: wire.narrativeIntensity,
+        reachVisibility: wire.reachVisibility,
+        verificationIntensity: wire.verificationIntensity,
+        reportMode: wire.reportMode,
+    };
+}
+export function parseAssessmentOrThrow(data) {
+    const parsed = assessmentSchema.safeParse(data);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        throw new Error(`assessment validation: ${issues}`);
+    }
+    return parsed.data;
+}
+export function safeParseAssessment(data) {
+    const parsed = assessmentSchema.safeParse(data);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            issues: parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`),
+        };
+    }
+    return { ok: true, value: parsed.data };
+}
+/** Map engine narrative intensity to presentation density (formatting only). */
+export function narrativeIntensityToDensity(intensity) {
+    if (intensity === "minimal")
+        return "minimal";
+    if (intensity === "elevated")
+        return "rich";
+    return "standard";
+}

package/dist/cardObservationCatalog.d.ts

@@ -9,6 +9,8 @@ import type { DependencyGraphInsights, ExplainReason, Finding, Recommendation, S
  * If any answer is no → do not add.
  */
 export declare const CARD_OBSERVATION_MAX_LENGTH = 48;
+/** Presentation-only rewrite of known engine metric tokens. */
+export declare function humanizeEngineSurfaceText(raw: string): string;
 export declare const CARD_OBSERVATION_CATALOG: readonly ["Large upgrade blast radius", "High transitive dependency volume", "Broad package surface area", "Duplicate dependency versions detected", "Vulnerable transitive packages detected", "Stale ecosystem dependencies detected", "Transitive dependency hotspots detected", "Deep indirect dependency chains", "Overlapping dependency paths detected"];
 export type CatalogPhrase = (typeof CARD_OBSERVATION_CATALOG)[number];
 /** Signal family keys — one catalog phrase per family on a card. */

package/dist/cardObservationCatalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cardObservationCatalog.d.ts","sourceRoot":"","sources":["../src/cardObservationCatalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EACb,OAAO,EACP,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AAEH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,eAAO,MAAM,wBAAwB,iWAU3B,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,eAAO,MAAM,gCAAgC,EAAE,MAAM,CACnD,uBAAuB,EACvB,aAAa,CAWd,CAAC;AAoIF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIxE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,SAA8B,GAChC,OAAO,CAET;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,uBAAuB,GAC9B,aAAa,CAEf;AAYD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,IAAI,CAOhC;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAMnE;AAED,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,cAAc,GAClB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAGnE;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,aAAa,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAGnE;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GACf;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAuBnE;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,MAAM,GACT;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAEnE;AAED,wBAAgB,gCAAgC,CAC9C,EAAE,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC7C,KAAK,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC,CAgCnE;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,GAChB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAUnE;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,IAAI,IAAI,CAe/C"}
+{"version":3,"file":"cardObservationCatalog.d.ts","sourceRoot":"","sources":["../src/cardObservationCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EACb,OAAO,EACP,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AAEH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6C7D;AAED,eAAO,MAAM,wBAAwB,iWAU3B,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,eAAO,MAAM,gCAAgC,EAAE,MAAM,CACnD,uBAAuB,EACvB,aAAa,CAWd,CAAC;AAoIF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIxE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,SAA8B,GAChC,OAAO,CAET;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,uBAAuB,GAC9B,aAAa,CAEf;AAYD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,IAAI,CAOhC;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAMnE;AAED,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,cAAc,GAClB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAGnE;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,aAAa,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAGnE;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GACf;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAuBnE;AAED,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,MAAM,GACT;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAEnE;AAED,wBAAgB,gCAAgC,CAC9C,EAAE,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC7C,KAAK,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC,CAgCnE;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,GAChB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAUnE;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,IAAI,IAAI,CAe/C"}

package/dist/cardObservationCatalog.js

@@ -1,4 +1,3 @@
-import { humanizeEngineSurfaceText } from "./actionsStepSummary.js";
 /**
  * CATALOG_EXPANSION_CHECKLIST (G1):
  * - Names a specific structural/topological concept (chains, paths, versions,
@@ -9,6 +8,53 @@ import { humanizeEngineSurfaceText } from "./actionsStepSummary.js";
  * If any answer is no → do not add.
  */
 export const CARD_OBSERVATION_MAX_LENGTH = 48;
+/** Presentation-only rewrite of known engine metric tokens. */
+export function humanizeEngineSurfaceText(raw) {
+    const input = raw.trim();
+    if (!input)
+        return input;
+    let t = input.replace(/_/g, " ");
+    t = t.replace(/^(security|maintainability|ecosystem|upgradeimpact|upgrade\s+impact)[.:]\s*/i, "");
+    const subs = [
+        [
+            /ecosystem\.package\s*surface|ecosystem\s+package\s*surface|package\s+surface\b/gi,
+            "broad declared package footprint",
+        ],
+        [
+            /graph\.duplicates?\b|graph\s+duplicates?\b/gi,
+            "overlapping dependency paths to the same packages",
+        ],
+        [
+            /graph\.fan\s*in\s*max|graph\s+fan\s+in\s+max/gi,
+            "many import paths converge on a few widely shared packages",
+        ],
+        [
+            /graph\.fan\s*in|graph\s+fan\s+in/gi,
+            "shared packages see many inbound dependency paths",
+        ],
+        [
+            /graph\.transitive(?:\s+volume)?|graph\s+transitive(?:\s+volume)?/gi,
+            "transitive dependency volume",
+        ],
+        [/graph\.depth|graph\s+depth/gi, "indirect dependency depth"],
+        [/graph\.hotspot|graph\s+hotspot/gi, "dependency hotspots"],
+        [/graph\.hidden|graph\s+hidden/gi, "hidden transitive paths"],
+        [
+            /graph\.vulnerable|graph\s+vulnerable/gi,
+            "known vulnerable packages on the graph",
+        ],
+        [/graph\.fan|graph\s+fan/gi, "fan-in"],
+    ];
+    for (const [re, rep] of subs)
+        t = t.replace(re, rep);
+    t = t
+        .replace(/\bdependency\s+chain\s+depth\b/gi, "indirect dependency depth")
+        .replace(/^dependency\s+depth$/gi, "indirect dependency depth");
+    t = t.replace(/\s+/g, " ").trim();
+    if (!t)
+        return input;
+    return t.charAt(0).toUpperCase() + t.slice(1);
+}
 export const CARD_OBSERVATION_CATALOG = [
     "Large upgrade blast radius",
     "High transitive dependency volume",

package/dist/engineWireRegression.test.js

@@ -1,8 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { deriveScanCardSummary } from "./scanCardSummary.js";
 import { deriveScanNarrative } from "./deriveScanNarrative.js";
 import { fixtureRepoIntelligenceFastify, fixtureRepoIntelligenceMultiPackage, } from "./fixtures/repoIntelligenceFixtures.js";
+import { assessmentFastifyRuntime } from "./fixtures/assessmentFixtures.js";
 import { validateRepoIntelligenceWire } from "./repoIntelligenceSchema.js";
+import { buildScanPresentationBundle } from "./presentation/orchestration/buildScanPresentationBundle.js";
+import { presentDashboardCard } from "./presentation/presenters/presentDashboardCard.js";
 const baseScan = {
     totalScore: 55,
     layerScores: {
@@ -30,15 +32,27 @@ describe("engine wire regression (canonical fixtures)", () => {
             ...baseScan,
             changedPackages: ["fastify"],
             repoIntelligence: fixtureRepoIntelligenceFastify,
+            assessment: assessmentFastifyRuntime,
+            decision: {
+                recommendation: "needs_review",
+                confidence: "medium",
+                reasoning: [
+                    "Changed package has confirmed usage on runtime application paths in this repository.",
+                ],
+            },
         };
         const facts = deriveScanNarrative(result);
         expect(facts.availability.tiersPresent.tier1).toBe(true);
         expect(facts.availability.mode).toBe("pr_intelligence");
         expect(facts.availability.repoIntelligenceParse).toBe("ok");
         expect(facts.packageUsage[0]?.packageName).toBe("fastify");
-        const card = deriveScanCardSummary(result, "done");
-        expect(card.keyPoints.length).toBeGreaterThan(0);
-        expect(card.verificationActions.length).toBeGreaterThan(0);
+        const bundle = buildScanPresentationBundle({
+            result,
+            pipelineStatus: "done",
+        });
+        const card = presentDashboardCard(bundle);
+        expect(card.insights.length).toBeGreaterThan(0);
+        expect(card.verification.length).toBeGreaterThan(0);
     });
     it("multi-package fixture: both packages in packageUsage", () => {
         validateRepoIntelligenceWire(fixtureRepoIntelligenceMultiPackage);
@@ -46,6 +60,12 @@ describe("engine wire regression (canonical fixtures)", () => {
             ...baseScan,
             changedPackages: ["lodash", "axios"],
             repoIntelligence: fixtureRepoIntelligenceMultiPackage,
+            assessment: assessmentFastifyRuntime,
+            decision: {
+                recommendation: "needs_review",
+                confidence: "medium",
+                reasoning: [],
+            },
         };
         const facts = deriveScanNarrative(result);
         expect(facts.availability.mode).toBe("pr_intelligence");

package/dist/fixtures/assessmentFixtures.d.ts

@@ -0,0 +1,13 @@
+import type { Assessment } from "../assessmentSchema.js";
+export declare const assessmentTypescriptPatch: Assessment;
+export declare const assessmentPrettier: Assessment;
+export declare const assessmentEslint: Assessment;
+export declare const assessmentVitest: Assessment;
+export declare const assessmentFastifyRuntime: Assessment;
+export declare const assessmentBullmq: Assessment;
+export declare const assessmentNextAuth: Assessment;
+export declare const assessmentMixedTypescriptFastify: Assessment;
+export declare const assessmentLimitedContext: Assessment;
+export declare const assessmentStub: Assessment;
+export declare const assessmentUnknownSafe: Assessment;
+//# sourceMappingURL=assessmentFixtures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assessmentFixtures.d.ts","sourceRoot":"","sources":["../../src/fixtures/assessmentFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAkBzD,eAAO,MAAM,yBAAyB,EAAE,UAQvC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,UAGhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAE9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAQ9B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,UAetC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAmB9B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,UAehC,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,UAe9C,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,UAoBtC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UAoB5B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,UAcnC,CAAC"}

package/dist/fixtures/assessmentFixtures.js

@@ -0,0 +1,164 @@
+const safeToolingPresentation = {
+    narrativeIntensity: "minimal",
+    reachVisibility: "hidden",
+    verificationIntensity: "advisory",
+    insightEmissionFloor: "none",
+    reportMode: "high_signal_pr",
+};
+const runtimeReviewPresentation = {
+    narrativeIntensity: "elevated",
+    reachVisibility: "prominent",
+    verificationIntensity: "required",
+    insightEmissionFloor: "full",
+    reportMode: "high_signal_pr",
+};
+export const assessmentTypescriptPatch = {
+    posture: "safe",
+    confidence: "high",
+    primaryConcern: null,
+    concerns: [],
+    factors: ["tooling_maintenance"],
+    changeClasses: ["tooling_maintenance"],
+    presentation: safeToolingPresentation,
+};
+export const assessmentPrettier = {
+    ...assessmentTypescriptPatch,
+    factors: ["tooling_maintenance"],
+};
+export const assessmentEslint = {
+    ...assessmentTypescriptPatch,
+};
+export const assessmentVitest = {
+    posture: "safe",
+    confidence: "high",
+    primaryConcern: null,
+    concerns: [],
+    factors: ["test_infra_change"],
+    changeClasses: ["test_infra"],
+    presentation: safeToolingPresentation,
+};
+export const assessmentFastifyRuntime = {
+    posture: "needs_review",
+    confidence: "medium",
+    primaryConcern: "confirmed_runtime_usage",
+    concerns: [
+        {
+            kind: "confirmed_runtime_usage",
+            rank: 1,
+            packages: ["fastify"],
+            evidenceRefs: ["fixture:fastify"],
+        },
+    ],
+    factors: ["confirmed_runtime_usage", "http_framework_infrastructure"],
+    changeClasses: ["runtime_upgrade"],
+    presentation: runtimeReviewPresentation,
+};
+export const assessmentBullmq = {
+    posture: "needs_review",
+    confidence: "medium",
+    primaryConcern: "confirmed_runtime_usage",
+    concerns: [
+        {
+            kind: "confirmed_runtime_usage",
+            rank: 1,
+            packages: ["bullmq"],
+            evidenceRefs: ["fixture:bullmq"],
+        },
+    ],
+    factors: [
+        "confirmed_runtime_usage",
+        "queue_infrastructure",
+        "verification_required",
+    ],
+    changeClasses: ["runtime_upgrade"],
+    presentation: runtimeReviewPresentation,
+};
+export const assessmentNextAuth = {
+    posture: "needs_review",
+    confidence: "medium",
+    primaryConcern: "confirmed_runtime_usage",
+    concerns: [
+        {
+            kind: "confirmed_runtime_usage",
+            rank: 1,
+            packages: ["next-auth"],
+            evidenceRefs: ["fixture:nextauth"],
+        },
+    ],
+    factors: ["confirmed_runtime_usage", "auth_infrastructure"],
+    changeClasses: ["runtime_upgrade"],
+    presentation: runtimeReviewPresentation,
+};
+export const assessmentMixedTypescriptFastify = {
+    posture: "needs_review",
+    confidence: "medium",
+    primaryConcern: "confirmed_runtime_usage",
+    concerns: [
+        {
+            kind: "confirmed_runtime_usage",
+            rank: 1,
+            packages: ["fastify"],
+            evidenceRefs: ["fixture:fastify"],
+        },
+    ],
+    factors: ["confirmed_runtime_usage", "http_framework_infrastructure"],
+    changeClasses: ["runtime_upgrade", "tooling_maintenance"],
+    presentation: runtimeReviewPresentation,
+};
+export const assessmentLimitedContext = {
+    posture: "needs_review",
+    confidence: "low",
+    primaryConcern: "insufficient_evidence",
+    concerns: [
+        {
+            kind: "insufficient_evidence",
+            rank: 1,
+            evidenceRefs: ["fixture:limited"],
+        },
+    ],
+    factors: ["insufficient_collection_evidence"],
+    changeClasses: ["ecosystem_unknown"],
+    presentation: {
+        narrativeIntensity: "minimal",
+        reachVisibility: "hidden",
+        verificationIntensity: "none",
+        insightEmissionFloor: "none",
+        reportMode: "high_signal_pr",
+    },
+};
+export const assessmentStub = {
+    posture: "needs_review",
+    confidence: "low",
+    primaryConcern: "insufficient_evidence",
+    concerns: [
+        {
+            kind: "insufficient_evidence",
+            rank: 1,
+            evidenceRefs: ["stub:engine"],
+        },
+    ],
+    factors: ["insufficient_collection_evidence"],
+    changeClasses: ["ecosystem_unknown"],
+    presentation: {
+        narrativeIntensity: "minimal",
+        reachVisibility: "hidden",
+        verificationIntensity: "none",
+        insightEmissionFloor: "none",
+        reportMode: "high_signal_pr",
+    },
+};
+export const assessmentUnknownSafe = {
+    posture: "safe",
+    confidence: "medium",
+    primaryConcern: null,
+    concerns: [],
+    factors: ["ecosystem_unknown_package"],
+    changeClasses: ["ecosystem_unknown"],
+    presentation: {
+        narrativeIntensity: "standard",
+        reachVisibility: "contextual",
+        verificationIntensity: "advisory",
+        insightEmissionFloor: "explain_only",
+        reportMode: "high_signal_pr",
+    },
+};

package/dist/formatCardExposureDisplay.d.ts

@@ -17,8 +17,4 @@ export declare function deriveCardExposureDisplay(score: number | null | undefin
 export declare function formatCardExposureLine(score: number | null | undefined): string | null;
 /** Fragment for composite aria labels on PR cards. */
 export declare function exposureAriaFragment(score: number | null | undefined): string | null;
-/** Detail-page reach chip labels (not "exposure" jargon). */
-export declare const DETAIL_REACH_CHIP_LABEL: Record<CardExposureCategory, string>;
-/** Reach chip for scan detail page — maps score band to reviewer-facing scope label. */
-export declare function deriveDetailReachChip(score: number | null | undefined): string | null;
 //# sourceMappingURL=formatCardExposureDisplay.d.ts.map

package/dist/formatCardExposureDisplay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatCardExposureDisplay.d.ts","sourceRoot":"","sources":["../src/formatCardExposureDisplay.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,SAAS,GACT,UAAU,GACV,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAUF,qEAAqE;AACrE,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAM1D,CAAC;AAkBF,0EAA0E;AAC1E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,mBAAmB,GAAG,IAAI,CAM5B;AAED,uDAAuD;AACvD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAIf;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAIf;AAED,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAMxE,CAAC;AAEF,wFAAwF;AACxF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAIf"}
+{"version":3,"file":"formatCardExposureDisplay.d.ts","sourceRoot":"","sources":["../src/formatCardExposureDisplay.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,SAAS,GACT,UAAU,GACV,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAUF,qEAAqE;AACrE,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAM1D,CAAC;AAkBF,0EAA0E;AAC1E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,mBAAmB,GAAG,IAAI,CAM5B;AAED,uDAAuD;AACvD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAIf;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAIf"}

package/dist/formatCardExposureDisplay.js

@@ -54,18 +54,3 @@ export function exposureAriaFragment(score) {
         return null;
     return display.label;
 }
-/** Detail-page reach chip labels (not "exposure" jargon). */
-export const DETAIL_REACH_CHIP_LABEL = {
-    minimal: "Focused reach",
-    limited: "Limited reach",
-    moderate: "Moderate reach",
-    elevated: "Wide reach",
-    broad: "Wide reach",
-};
-/** Reach chip for scan detail page — maps score band to reviewer-facing scope label. */
-export function deriveDetailReachChip(score) {
-    const display = deriveCardExposureDisplay(score);
-    if (!display)
-        return null;
-    return DETAIL_REACH_CHIP_LABEL[display.category];
-}

package/dist/formatInsight.d.ts

@@ -1,4 +1,4 @@
-import type { PRInsight, PRDecisionRecommendation } from "./types.js";
+import type { PRInsight, PRDecision, PRDecisionRecommendation } from "./types.js";
 export type FormattedInsight = {
     message: string;
     where: string;
@@ -6,5 +6,6 @@ export type FormattedInsight = {
 };
 export declare function decisionTitle(recommendation: PRDecisionRecommendation): string;
 export declare function formatInsight(insight: PRInsight): FormattedInsight;
-export { renderInsightsAsMarkdown } from "./presentGitHubPrComment.js";
+/** Legacy markdown renderer for raw PR insights (format-only; no bundle inference). */
+export declare function renderInsightsAsMarkdown(insights: PRInsight[], decision: PRDecision): string;
 //# sourceMappingURL=formatInsight.d.ts.map

package/dist/formatInsight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatInsight.d.ts","sourceRoot":"","sources":["../src/formatInsight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AASF,wBAAgB,aAAa,CAC3B,cAAc,EAAE,wBAAwB,GACvC,MAAM,CAER;AAgBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAMlE;AAiBD,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"formatInsight.d.ts","sourceRoot":"","sources":["../src/formatInsight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AASF,wBAAgB,aAAa,CAC3B,cAAc,EAAE,wBAAwB,GACvC,MAAM,CAER;AAgBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAMlE;AA+BD,uFAAuF;AACvF,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,EAAE,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAUR"}