@mergesignal/shared 0.2.3 → 0.2.5

package/README.md

@@ -0,0 +1,37 @@
+# @mergesignal/shared
+
+Published npm package containing the MergeSignal **scan contract**, presentation policy, and trusted-output validation.
+
+```bash
+npm install @mergesignal/shared
+```
+
+**Current version:** see [package.json](./package.json). Pin exact semver in downstream consumers (especially the proprietary analysis engine).
+
+## What it provides
+
+- **Types and schemas** for `ScanRequest`, `ScanResult`, upgrade simulation, and related wire formats
+- **Validation** for scan results and trusted CI output guards
+- **Presentation copy** helpers used by the web app and CI summary renderers
+
+## Usage
+
+```typescript
+import {} from /* types, validators, copy */ "@mergesignal/shared";
+```
+
+See `dist/index.d.ts` after install for the full export surface.
+
+## OSS monorepo vs npm
+
+Inside this repository, apps use the workspace package via `pnpm`. External consumers (e.g. `mergesignal-engine`) install from the **public npm registry** with an exact version pin.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE) for the monorepo; npm package license field in `package.json`.
+
+## More
+
+- [Engine stub](../engine-stub/README.md) — OSS boundary
+- [GitHub Actions integration](../../.github/actions/merge-signal-scan/README.md)
+- Maintainer release process: [docs/engineering/releasing.md](../../docs/engineering/releasing.md)

package/dist/deriveRiskScoreSummary.d.ts

@@ -0,0 +1,33 @@
+import type { ScanResult, ScoreLayer } from "./types.js";
+export declare const SCAN_DETAIL_RISK_BAND_MODERATE_MIN = 40;
+export declare const SCAN_DETAIL_RISK_BAND_HIGH_MIN = 80;
+export type ScanDetailOverallRiskBand = "low" | "moderate" | "high";
+export type ScanDetailLayerConcernLevel = "low" | "medium" | "high";
+export type ScanDetailSignalLayer = {
+    layer: ScoreLayer;
+    label: string;
+    score: number;
+    concernLevel: ScanDetailLayerConcernLevel;
+    concernLabel: string;
+};
+/** @deprecated Use ScanDetailSignalLayer */
+export type ScanDetailRiskLayer = ScanDetailSignalLayer;
+export type RiskScoreGaugeModel = {
+    fillPercent: number;
+    band: ScanDetailOverallRiskBand;
+    ariaLabel: string;
+};
+export type ScanDetailSignalSummary = {
+    score: number;
+    overallBand: ScanDetailOverallRiskBand;
+    overallLabel: string;
+    gauge: RiskScoreGaugeModel;
+    layers: ScanDetailSignalLayer[];
+};
+/** @deprecated Use ScanDetailSignalSummary */
+export type ScanDetailRiskSummary = ScanDetailSignalSummary;
+export declare function deriveOverallRiskBand(score: number | null | undefined): ScanDetailOverallRiskBand;
+export declare function overallSignalBandLabel(band: ScanDetailOverallRiskBand): string;
+export declare function deriveRiskScoreGauge(score: number, band: ScanDetailOverallRiskBand): RiskScoreGaugeModel;
+export declare function deriveSignalSummary(result: ScanResult): ScanDetailSignalSummary | null;
+//# sourceMappingURL=deriveRiskScoreSummary.d.ts.map

package/dist/deriveRiskScoreSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deriveRiskScoreSummary.d.ts","sourceRoot":"","sources":["../src/deriveRiskScoreSummary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,kCAAkC,KAAK,CAAC;AACrD,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAgBjD,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AACpE,MAAM,MAAM,2BAA2B,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpE,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,2BAA2B,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAExD,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,yBAAyB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,yBAAyB,CAAC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAO5D,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,yBAAyB,CAM3B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,yBAAyB,GAC9B,MAAM,CAKR;AAgBD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,yBAAyB,GAC9B,mBAAmB,CASrB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GACjB,uBAAuB,GAAG,IAAI,CAoChC"}

package/dist/deriveRiskScoreSummary.js

@@ -0,0 +1,90 @@
+import { layerRiskBandLabel } from "./actionsStepSummary.js";
+import { scanSurfaceCopy } from "./scanSurfaceCopy.js";
+export const SCAN_DETAIL_RISK_BAND_MODERATE_MIN = 40;
+export const SCAN_DETAIL_RISK_BAND_HIGH_MIN = 80;
+const LAYER_ORDER = [
+    "security",
+    "maintainability",
+    "ecosystem",
+    "upgradeImpact",
+];
+const LAYER_LABEL = {
+    security: "Security",
+    maintainability: "Maintainability",
+    ecosystem: "Ecosystem",
+    upgradeImpact: "Upgrade Impact",
+};
+function clampScore(score) {
+    if (!Number.isFinite(score))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+export function deriveOverallRiskBand(score) {
+    if (score == null || !Number.isFinite(score))
+        return "low";
+    const value = clampScore(score);
+    if (value >= SCAN_DETAIL_RISK_BAND_HIGH_MIN)
+        return "high";
+    if (value >= SCAN_DETAIL_RISK_BAND_MODERATE_MIN)
+        return "moderate";
+    return "low";
+}
+export function overallSignalBandLabel(band) {
+    const copy = scanSurfaceCopy.scanDetail.signalSummary.bandLabel;
+    if (band === "high")
+        return copy.high;
+    if (band === "moderate")
+        return copy.moderate;
+    return copy.low;
+}
+function layerBandToSignal(band) {
+    const copy = scanSurfaceCopy.scanDetail.signalSummary.signalLabel;
+    if (band === "High") {
+        return { level: "high", label: copy.high };
+    }
+    if (band === "Moderate") {
+        return { level: "medium", label: copy.medium };
+    }
+    return { level: "low", label: copy.low };
+}
+export function deriveRiskScoreGauge(score, band) {
+    const clamped = clampScore(score);
+    return {
+        fillPercent: clamped,
+        band,
+        ariaLabel: scanSurfaceCopy.scanDetail.signalSummary.gaugeAriaLabel
+            .replace("{score}", String(clamped))
+            .replace("{band}", overallSignalBandLabel(band)),
+    };
+}
+export function deriveSignalSummary(result) {
+    if (typeof result.totalScore !== "number" ||
+        !Number.isFinite(result.totalScore)) {
+        return null;
+    }
+    const score = clampScore(result.totalScore);
+    const overallBand = deriveOverallRiskBand(score);
+    const overallLabel = overallSignalBandLabel(overallBand);
+    const gauge = deriveRiskScoreGauge(score, overallBand);
+    const layers = LAYER_ORDER.map((layer) => {
+        const layerScore = typeof result.layerScores?.[layer] === "number"
+            ? clampScore(result.layerScores[layer])
+            : 0;
+        const band = layerRiskBandLabel(layerScore);
+        const signal = layerBandToSignal(band);
+        return {
+            layer,
+            label: LAYER_LABEL[layer],
+            score: layerScore,
+            concernLevel: signal.level,
+            concernLabel: signal.label,
+        };
+    });
+    return {
+        score,
+        overallBand,
+        overallLabel,
+        gauge,
+        layers,
+    };
+}

package/dist/deriveRiskScoreSummary.test.d.ts

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

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

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

package/dist/deriveRiskScoreSummary.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { deriveOverallRiskBand, deriveSignalSummary, SCAN_DETAIL_RISK_BAND_HIGH_MIN, SCAN_DETAIL_RISK_BAND_MODERATE_MIN, } from "./deriveRiskScoreSummary.js";
+const baseResult = {
+    totalScore: 71,
+    layerScores: {
+        security: 80,
+        maintainability: 65,
+        ecosystem: 55,
+        upgradeImpact: 70,
+    },
+    findings: [],
+    generatedAt: "2026-01-01T00:00:00.000Z",
+};
+describe("deriveOverallRiskBand", () => {
+    it("uses 40/80 thresholds", () => {
+        expect(SCAN_DETAIL_RISK_BAND_MODERATE_MIN).toBe(40);
+        expect(SCAN_DETAIL_RISK_BAND_HIGH_MIN).toBe(80);
+        expect(deriveOverallRiskBand(39)).toBe("low");
+        expect(deriveOverallRiskBand(40)).toBe("moderate");
+        expect(deriveOverallRiskBand(71)).toBe("moderate");
+        expect(deriveOverallRiskBand(79)).toBe("moderate");
+        expect(deriveOverallRiskBand(80)).toBe("high");
+    });
+});
+describe("deriveSignalSummary", () => {
+    it("returns moderate band for score 71 on safe posture", () => {
+        const summary = deriveSignalSummary({
+            ...baseResult,
+            decision: { recommendation: "safe", confidence: "high", reasoning: [] },
+        });
+        expect(summary?.score).toBe(71);
+        expect(summary?.overallBand).toBe("moderate");
+        expect(summary?.overallLabel).toBe("Moderate");
+        expect(summary?.gauge.fillPercent).toBe(71);
+    });
+    it("returns null when totalScore is missing", () => {
+        expect(deriveSignalSummary({
+            ...baseResult,
+            totalScore: Number.NaN,
+        })).toBeNull();
+    });
+    it("uses short signal labels on layer rows", () => {
+        const summary = deriveSignalSummary(baseResult);
+        expect(summary?.layers).toHaveLength(4);
+        expect(summary?.layers[0]?.concernLabel).toBe("Elevated");
+    });
+});

package/dist/deriveScanDetailRecommendations.d.ts

@@ -0,0 +1,63 @@
+import { type ObservationSignalFamily } from "./cardObservationCatalog.js";
+import { type MergePosture } from "./riskVocabulary.js";
+import type { ScanResult } from "./types.js";
+export declare const RECOMMENDATION_MAX_ITEMS = 3;
+export declare const RECOMMENDATION_MAX_TITLE_CHARS = 80;
+export declare const RECOMMENDATION_PREFER_MAX_ON_SAFE = 2;
+export declare const RECOMMENDATION_MAX_SIGNALS = 4;
+export declare const RECOMMENDATION_MAX_PACKAGES = 5;
+export type RecommendationPriority = "high" | "medium" | "low";
+/** @deprecated Use RecommendationPriority */
+export type GuidanceUrgency = RecommendationPriority;
+export type GuidanceSource = "insight" | "recommendation" | "signal" | "finding" | "posture_playbook";
+export type ScanDetailRecommendationDetail = {
+    why: string;
+    whyNow: string;
+    signals: string[];
+    affectedPackages?: {
+        names: string[];
+        overflowCount: number;
+    };
+    expectedBenefit: string;
+};
+export type ScanDetailRecommendation = {
+    id: string;
+    rank: number;
+    title: string;
+    priority: RecommendationPriority;
+    source: GuidanceSource;
+    signalFamily?: ObservationSignalFamily | null;
+    detail: ScanDetailRecommendationDetail;
+    proofRefs?: {
+        findingIds?: string[];
+    };
+};
+export type ScanDetailRecommendationCenter = {
+    heading: string;
+    defaultSelectedId: string;
+    items: ScanDetailRecommendation[];
+    posture: MergePosture | null;
+    scanContext?: string;
+};
+/** @deprecated Use ScanDetailRecommendationCenter */
+export type ScanDetailWhatToDo = {
+    items: Array<{
+        id: string;
+        label: string;
+        emphasis: "primary" | "secondary";
+        priority: RecommendationPriority;
+        source: GuidanceSource;
+    }>;
+    posture: MergePosture | null;
+};
+export declare const GUIDANCE_ACTION_FOR_FAMILY: Record<ObservationSignalFamily, string>;
+/** Derive the scan detail recommendation center — always returns 1–3 enriched items. */
+export declare function deriveScanDetailRecommendations(result: ScanResult): ScanDetailRecommendationCenter;
+export declare function recommendationTitlesForDedupe(center: ScanDetailRecommendationCenter): Set<string>;
+export declare function findingIdsCoveredByRecommendations(center: ScanDetailRecommendationCenter): Set<string>;
+export declare function verifyLabelsForDedupe(center: ScanDetailRecommendationCenter): Set<string>;
+/** @deprecated Use deriveScanDetailRecommendations */
+export declare function deriveScanDetailGuidance(result: ScanResult): ScanDetailWhatToDo;
+/** @deprecated Use recommendationTitlesForDedupe */
+export declare function guidanceLabelsForDedupe(whatToDo: ScanDetailWhatToDo): Set<string>;
+//# sourceMappingURL=deriveScanDetailRecommendations.d.ts.map

package/dist/deriveScanDetailRecommendations.d.ts.map

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