@checkstack/script-packages-backend 0.2.0 → 0.3.0

package/src/audit-delta.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import type { AuditAdvisory, AuditSeverity } from "@checkstack/script-packages-common";
+import { advisoryKey, computeAuditDelta } from "./audit-delta";
+
+function adv(
+  packageName: string,
+  advisoryId: string,
+  severity: AuditSeverity,
+): AuditAdvisory {
+  return {
+    packageName,
+    advisoryId,
+    severity,
+    title: `${packageName} ${advisoryId}`,
+    vulnerableVersions: "<1",
+    url: null,
+    cvssScore: null,
+  };
+}
+
+const THRESHOLD: AuditSeverity = "moderate";
+
+describe("computeAuditDelta", () => {
+  it("notifies newly-appeared advisories at or above the threshold", () => {
+    const result = computeAuditDelta({
+      previous: [],
+      current: [adv("lodash", "1", "high"), adv("a", "2", "low")],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify.map((a) => a.packageName)).toEqual(["lodash"]);
+    expect(result.newlyAppeared.sort()).toEqual([
+      advisoryKey({ packageName: "a", advisoryId: "2" }),
+      advisoryKey({ packageName: "lodash", advisoryId: "1" }),
+    ]);
+  });
+
+  it("does NOT notify a newly-appeared advisory below the threshold", () => {
+    const result = computeAuditDelta({
+      previous: [],
+      current: [adv("a", "1", "low")],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify).toEqual([]);
+    expect(result.newlyAppeared).toHaveLength(1);
+  });
+
+  it("suppresses re-notify on an unchanged set (the spam guard)", () => {
+    const set = [adv("lodash", "1", "high"), adv("zod", "2", "critical")];
+    const result = computeAuditDelta({
+      previous: set,
+      current: set,
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify).toEqual([]);
+    expect(result.newlyAppeared).toEqual([]);
+    expect(result.escalated).toEqual([]);
+  });
+
+  it("notifies on severity escalation across the threshold", () => {
+    const result = computeAuditDelta({
+      previous: [adv("lodash", "1", "low")],
+      current: [adv("lodash", "1", "high")],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify.map((a) => a.packageName)).toEqual(["lodash"]);
+    expect(result.escalated).toEqual([
+      advisoryKey({ packageName: "lodash", advisoryId: "1" }),
+    ]);
+  });
+
+  it("notifies on a within-threshold escalation (high -> critical)", () => {
+    const result = computeAuditDelta({
+      previous: [adv("lodash", "1", "high")],
+      current: [adv("lodash", "1", "critical")],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify).toHaveLength(1);
+    expect(result.escalated).toHaveLength(1);
+  });
+
+  it("does not notify a below-threshold escalation (low -> moderate is at threshold; low->low-ish stays quiet)", () => {
+    // escalated but still below threshold: bump low -> ... still below.
+    const result = computeAuditDelta({
+      previous: [adv("a", "1", "low")],
+      current: [adv("a", "1", "low")], // unchanged
+      threshold: "high",
+    });
+    expect(result.toNotify).toEqual([]);
+    expect(result.escalated).toEqual([]);
+  });
+
+  it("never notifies on de-escalation", () => {
+    const result = computeAuditDelta({
+      previous: [adv("lodash", "1", "critical")],
+      current: [adv("lodash", "1", "moderate")],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify).toEqual([]);
+    expect(result.escalated).toEqual([]);
+  });
+
+  it("does not notify when an advisory disappears", () => {
+    const result = computeAuditDelta({
+      previous: [adv("lodash", "1", "high")],
+      current: [],
+      threshold: THRESHOLD,
+    });
+    expect(result.toNotify).toEqual([]);
+    expect(result.newlyAppeared).toEqual([]);
+  });
+
+  it("sorts toNotify by severity (most severe first) then package name", () => {
+    const result = computeAuditDelta({
+      previous: [],
+      current: [
+        adv("b", "1", "moderate"),
+        adv("a", "2", "critical"),
+        adv("c", "3", "high"),
+        adv("a", "4", "moderate"),
+      ],
+      threshold: THRESHOLD,
+    });
+    expect(
+      result.toNotify.map((a) => `${a.severity}:${a.packageName}`),
+    ).toEqual(["critical:a", "high:c", "moderate:a", "moderate:b"]);
+  });
+});

package/src/audit-delta.ts

@@ -0,0 +1,100 @@
+import {
+  AUDIT_SEVERITY_RANK,
+  type AuditAdvisory,
+  type AuditSeverity,
+} from "@checkstack/script-packages-common";
+import { meetsThreshold } from "./audit-parse";
+
+/**
+ * Pure delta logic for the vulnerability audit: given the previously-stored
+ * advisory set and the freshly-parsed one, decide which advisories warrant a
+ * NEW notification to `script-packages.manage` holders.
+ *
+ * Notify rules (locked product decision: threshold = `moderate`):
+ * - A NEWLY-APPEARED advisory (not in the previous set) at or above the
+ *   threshold notifies.
+ * - An advisory whose severity ESCALATED across the threshold (was below,
+ *   now at/above) notifies. (A within-threshold escalation, e.g.
+ *   high -> critical, also notifies because operators want to know it got
+ *   worse; a de-escalation never notifies.)
+ * - An UNCHANGED advisory never re-notifies. This is the spam guard: a daily
+ *   run over a stable set produces zero notifications.
+ *
+ * The function is the suppression mechanism — the notification transport
+ * (`sendTransactional`) has no de-dup of its own, so "don't emit when
+ * nothing changed" lives here against the durably-stored previous set.
+ */
+
+/** Identity of one advisory: `<package> <advisoryId>`. */
+export function advisoryKey(advisory: {
+  packageName: string;
+  advisoryId: string;
+}): string {
+  return `${advisory.packageName} ${advisory.advisoryId}`;
+}
+
+export interface AuditDeltaInput {
+  /** Advisories stored from the previous run (any severity). */
+  previous: AuditAdvisory[];
+  /** Advisories parsed from the current run (any severity). */
+  current: AuditAdvisory[];
+  /** Notify on this severity and above. */
+  threshold: AuditSeverity;
+}
+
+export interface AuditDeltaResult {
+  /**
+   * Advisories to notify about this run: newly-appeared or severity-escalated
+   * across/within the threshold. Sorted by severity (most severe first) then
+   * package name for stable rendering.
+   */
+  toNotify: AuditAdvisory[];
+  /** Advisory keys that newly appeared (regardless of severity). */
+  newlyAppeared: string[];
+  /** Advisory keys whose severity increased since the previous run. */
+  escalated: string[];
+}
+
+export function computeAuditDelta({
+  previous,
+  current,
+  threshold,
+}: AuditDeltaInput): AuditDeltaResult {
+  const prevBySeverity = new Map<string, AuditSeverity>();
+  for (const a of previous) prevBySeverity.set(advisoryKey(a), a.severity);
+
+  const toNotify: AuditAdvisory[] = [];
+  const newlyAppeared: string[] = [];
+  const escalated: string[] = [];
+
+  for (const adv of current) {
+    const key = advisoryKey(adv);
+    const prevSeverity = prevBySeverity.get(key);
+    const meetsNow = meetsThreshold(adv.severity, threshold);
+
+    if (prevSeverity === undefined) {
+      newlyAppeared.push(key);
+      // A brand-new advisory notifies only if it meets the threshold.
+      if (meetsNow) toNotify.push(adv);
+      continue;
+    }
+
+    const increased =
+      AUDIT_SEVERITY_RANK[adv.severity] > AUDIT_SEVERITY_RANK[prevSeverity];
+    if (increased) {
+      escalated.push(key);
+      // An escalation notifies when the (now-higher) severity meets the
+      // threshold. (If it escalated but is still below threshold, stay quiet.)
+      if (meetsNow) toNotify.push(adv);
+    }
+    // Unchanged or de-escalated: never re-notify.
+  }
+
+  toNotify.sort((a, b) => {
+    const rank = AUDIT_SEVERITY_RANK[b.severity] - AUDIT_SEVERITY_RANK[a.severity];
+    if (rank !== 0) return rank;
+    return a.packageName.localeCompare(b.packageName);
+  });
+
+  return { toNotify, newlyAppeared, escalated };
+}

package/src/audit-parse.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "bun:test";
+import type { AuditAdvisory } from "@checkstack/script-packages-common";
+import { countBySeverity, meetsThreshold, parseBunAudit } from "./audit-parse";
+
+describe("parseBunAudit", () => {
+  it("parses the package-keyed advisory document", () => {
+    const stdout = JSON.stringify({
+      lodash: [
+        {
+          id: 1106913,
+          url: "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
+          title: "Command Injection in lodash",
+          severity: "high",
+          vulnerable_versions: "<4.17.21",
+          cvss: { score: 7.2, vectorString: "CVSS:3.1/..." },
+        },
+      ],
+    });
+    const { advisories } = parseBunAudit(stdout);
+    expect(advisories).toHaveLength(1);
+    expect(advisories[0]).toEqual({
+      packageName: "lodash",
+      advisoryId: "1106913",
+      title: "Command Injection in lodash",
+      severity: "high",
+      vulnerableVersions: "<4.17.21",
+      url: "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
+      cvssScore: 7.2,
+    });
+  });
+
+  it("treats {} (clean tree) and [] (no deps) as no advisories", () => {
+    expect(parseBunAudit("{}").advisories).toEqual([]);
+    expect(parseBunAudit("[]").advisories).toEqual([]);
+    expect(parseBunAudit("   ").advisories).toEqual([]);
+    expect(parseBunAudit("").advisories).toEqual([]);
+  });
+
+  it("sorts deterministically by package then advisory id", () => {
+    const stdout = JSON.stringify({
+      zod: [{ id: 200, severity: "low", vulnerable_versions: "<1" }],
+      lodash: [
+        { id: 30, severity: "high", vulnerable_versions: "<2" },
+        { id: 10, severity: "moderate", vulnerable_versions: "<3" },
+      ],
+    });
+    const { advisories } = parseBunAudit(stdout);
+    expect(advisories.map((a) => `${a.packageName}:${a.advisoryId}`)).toEqual([
+      "lodash:10",
+      "lodash:30",
+      "zod:200",
+    ]);
+  });
+
+  it("maps 'medium' to 'moderate' and coerces unknown severities to 'low'", () => {
+    const stdout = JSON.stringify({
+      a: [{ id: 1, severity: "medium", vulnerable_versions: "<1" }],
+      b: [{ id: 2, severity: "spooky", vulnerable_versions: "<1" }],
+    });
+    const { advisories } = parseBunAudit(stdout);
+    expect(advisories.find((x) => x.packageName === "a")?.severity).toBe(
+      "moderate",
+    );
+    expect(advisories.find((x) => x.packageName === "b")?.severity).toBe("low");
+  });
+
+  it("dedups the same (package, advisory) and skips entries with no id", () => {
+    const stdout = JSON.stringify({
+      lodash: [
+        { id: 5, severity: "high", vulnerable_versions: "<1" },
+        { id: 5, severity: "high", vulnerable_versions: "<1" },
+        { severity: "high", vulnerable_versions: "<1" },
+      ],
+    });
+    const { advisories } = parseBunAudit(stdout);
+    expect(advisories).toHaveLength(1);
+  });
+
+  it("tolerates missing optional fields and null cvss", () => {
+    const stdout = JSON.stringify({
+      pkg: [{ id: 9, severity: "critical" }],
+    });
+    const { advisories } = parseBunAudit(stdout);
+    expect(advisories[0]).toMatchObject({
+      title: "",
+      vulnerableVersions: "",
+      url: null,
+      cvssScore: null,
+    });
+  });
+
+  it("throws on non-JSON output", () => {
+    expect(() => parseBunAudit("error: registry unreachable")).toThrow();
+  });
+});
+
+describe("countBySeverity", () => {
+  it("counts each bucket and always returns all four", () => {
+    const advisories: AuditAdvisory[] = (
+      [
+        ["a", "1", "low"],
+        ["b", "2", "high"],
+        ["c", "3", "high"],
+        ["d", "4", "critical"],
+      ] as const
+    ).map(([packageName, advisoryId, severity]) => ({
+      packageName,
+      advisoryId,
+      severity,
+      title: "",
+      vulnerableVersions: "",
+      url: null,
+      cvssScore: null,
+    }));
+    const counts = countBySeverity(advisories);
+    expect(counts).toEqual({ low: 1, moderate: 0, high: 2, critical: 1 });
+  });
+});
+
+describe("meetsThreshold", () => {
+  it("compares by ordinal rank", () => {
+    expect(meetsThreshold("low", "moderate")).toBe(false);
+    expect(meetsThreshold("moderate", "moderate")).toBe(true);
+    expect(meetsThreshold("high", "moderate")).toBe(true);
+    expect(meetsThreshold("critical", "high")).toBe(true);
+    expect(meetsThreshold("moderate", "high")).toBe(false);
+  });
+});

package/src/audit-parse.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import {
+  AUDIT_SEVERITY_RANK,
+  type AuditAdvisory,
+  type AuditSeverity,
+} from "@checkstack/script-packages-common";
+
+/**
+ * Parse `bun audit --json` stdout into a normalised, deterministically-sorted
+ * advisory list.
+ *
+ * `bun audit --json` writes an object keyed by package name, each value an
+ * array of advisories:
+ * ```json
+ * { "lodash": [ { "id": 123, "url": "...", "title": "...",
+ *   "severity": "high", "vulnerable_versions": "<4.17.21",
+ *   "cvss": { "score": 7.2, "vectorString": "..." } } ] }
+ * ```
+ * A clean tree emits `{}` (or `[]` when there are no dependencies). The exit
+ * code is unreliable (Bun exits non-zero even on a clean tree in some
+ * versions), so callers MUST rely on this parse, never the exit status.
+ *
+ * Unknown severities are coerced to `low` rather than dropped, so a future
+ * registry value never silently hides a finding.
+ */
+
+const KNOWN_SEVERITIES = new Set<AuditSeverity>([
+  "low",
+  "moderate",
+  "high",
+  "critical",
+]);
+
+function normaliseSeverity(value: unknown): AuditSeverity {
+  if (typeof value === "string") {
+    const lower = value.toLowerCase();
+    // npm/GitHub sometimes use "medium" as a synonym for "moderate".
+    if (lower === "medium") return "moderate";
+    if (KNOWN_SEVERITIES.has(lower as AuditSeverity)) {
+      return lower as AuditSeverity;
+    }
+  }
+  return "low";
+}
+
+/** Raw advisory entry as Bun emits it. Lenient: tolerate missing fields. */
+const RawAdvisorySchema = z.object({
+  id: z.union([z.number(), z.string()]).optional(),
+  url: z.string().optional().nullable(),
+  title: z.string().optional().nullable(),
+  severity: z.string().optional().nullable(),
+  vulnerable_versions: z.string().optional().nullable(),
+  cvss: z
+    .object({ score: z.number().optional().nullable() })
+    .optional()
+    .nullable(),
+});
+
+/**
+ * The whole document: `{ [packageName]: RawAdvisory[] }`. An empty-deps tree
+ * yields `[]`, which we treat as "no advisories".
+ */
+const AuditDocumentSchema = z.union([
+  z.record(z.string(), z.array(RawAdvisorySchema)),
+  z.array(z.unknown()),
+]);
+
+export interface ParseAuditResult {
+  advisories: AuditAdvisory[];
+}
+
+/**
+ * Compare advisories deterministically so equal sets serialise identically:
+ * package name, then advisory id.
+ */
+function compareAdvisories(a: AuditAdvisory, b: AuditAdvisory): number {
+  if (a.packageName !== b.packageName) {
+    return a.packageName.localeCompare(b.packageName);
+  }
+  return a.advisoryId.localeCompare(b.advisoryId);
+}
+
+export function parseBunAudit(stdout: string): ParseAuditResult {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return { advisories: [] };
+
+  let json: unknown;
+  try {
+    json = JSON.parse(trimmed);
+  } catch {
+    throw new Error("bun audit produced output that is not valid JSON.");
+  }
+
+  const doc = AuditDocumentSchema.parse(json);
+  if (Array.isArray(doc)) return { advisories: [] };
+
+  const advisories: AuditAdvisory[] = [];
+  const seen = new Set<string>();
+  for (const [packageName, rawList] of Object.entries(doc)) {
+    for (const raw of rawList) {
+      const advisoryId =
+        raw.id === undefined || raw.id === null ? "" : String(raw.id);
+      if (advisoryId.length === 0) continue;
+      // Dedup on (package, advisory) so a registry returning the same
+      // advisory twice can't double-count.
+      const dedupKey = `${packageName} ${advisoryId}`;
+      if (seen.has(dedupKey)) continue;
+      seen.add(dedupKey);
+
+      advisories.push({
+        packageName,
+        advisoryId,
+        title: raw.title ?? "",
+        severity: normaliseSeverity(raw.severity),
+        vulnerableVersions: raw.vulnerable_versions ?? "",
+        url: raw.url ?? null,
+        cvssScore:
+          raw.cvss && typeof raw.cvss.score === "number"
+            ? raw.cvss.score
+            : null,
+      });
+    }
+  }
+
+  advisories.sort(compareAdvisories);
+  return { advisories };
+}
+
+/** Count advisories by severity (all four buckets always present). */
+export function countBySeverity(advisories: AuditAdvisory[]): {
+  low: number;
+  moderate: number;
+  high: number;
+  critical: number;
+} {
+  const counts = { low: 0, moderate: 0, high: 0, critical: 0 };
+  for (const a of advisories) counts[a.severity] += 1;
+  return counts;
+}
+
+/** True when `severity` is at or above `threshold`. */
+export function meetsThreshold(
+  severity: AuditSeverity,
+  threshold: AuditSeverity,
+): boolean {
+  return AUDIT_SEVERITY_RANK[severity] >= AUDIT_SEVERITY_RANK[threshold];
+}