@usefragments/core 1.0.0

package/src/schemas/schemas.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  findingSchema,
+  governanceVerdictSchema,
+  normalizeSeverity,
+  normalizeViolation,
+  suppressionDirectiveSchema,
+  validatorResultSchema,
+} from "./index.js";
+import { makeFinding } from "../rules/finding.js";
+
+describe("canonical TypeStyle schemas", () => {
+  it("validates a canonical finding with derived level", () => {
+    const finding = findingSchema.parse({
+      ruleId: "tokens/require-design-tokens",
+      ruleVersion: "1.0.0",
+      severity: "moderate",
+      level: "warn",
+      code: "FUI2001",
+      helpUrl: "https://usefragments.com/errors/FUI2001",
+      message: "Use a design token.",
+      fingerprint: "abc123",
+      location: { file: "src/button.tsx", line: 4, column: 12 },
+      evidence: [
+        {
+          factId: "fact:1",
+          fact: {
+            kind: "style_declaration",
+            location: { file: "src/button.tsx", line: 4, column: 12 },
+          },
+        },
+      ],
+    });
+
+    expect(finding.severity).toBe("moderate");
+    expect(finding.level).toBe("warn");
+  });
+
+  it("normalizes legacy severity levels at compatibility boundaries", () => {
+    expect(normalizeSeverity("error")).toBe("serious");
+    expect(normalizeSeverity("warning")).toBe("moderate");
+    expect(normalizeSeverity("info")).toBe("minor");
+    expect(
+      normalizeViolation({
+        nodeId: "node-1",
+        nodeType: "Button",
+        rule: "components/allow",
+        severity: "serious",
+        message: "Use an allowed component.",
+      }).level
+    ).toBe("error");
+  });
+
+  it("validates verdict and suppression contracts", () => {
+    expect(() =>
+      governanceVerdictSchema.parse({
+        passed: true,
+        score: 100,
+        results: [],
+        metadata: {
+          runner: "cli",
+          duration: 10,
+          nodeCount: 1,
+          componentTypes: ["Button"],
+        },
+      })
+    ).not.toThrow();
+
+    expect(() =>
+      suppressionDirectiveSchema.parse({
+        ruleId: "tokens/require-design-tokens",
+        reason: "Legacy file scheduled for removal.",
+        expiresAt: "2026-08-01T00:00:00.000Z",
+        scope: "line",
+        code: "FUI2001",
+      })
+    ).not.toThrow();
+  });
+
+  it("allows validator results to bridge legacy violations and canonical findings", () => {
+    const finding = makeFinding({
+      ruleId: "safety/block-event-handlers",
+      ruleVersion: "1.0.0",
+      severity: "serious",
+      message: "Event handlers are blocked.",
+      location: { file: "<ui-spec>", line: 0, column: 0 },
+      evidence: [
+        {
+          factId: "ui-spec:safety:block-event-handlers:button-1:onClick",
+          fact: {
+            kind: "ui_spec_violation",
+            location: { file: "<ui-spec>", line: 0, column: 0 },
+          },
+        },
+      ],
+      fingerprintIdentity: {
+        nodeId: "button-1",
+        prop: "onClick",
+      },
+    });
+
+    expect(finding.code).toBe("FUI8001");
+    expect(finding.helpUrl).toBe("https://usefragments.com/errors/FUI8001");
+    expect(() =>
+      validatorResultSchema.parse({
+        validator: "safety",
+        severity: "serious",
+        passed: false,
+        violations: [
+          {
+            nodeId: "button-1",
+            nodeType: "Button",
+            rule: "safety/block-event-handlers",
+            severity: "serious",
+            code: "FUI8001",
+            message: "Event handlers are blocked.",
+          },
+        ],
+        findings: [finding],
+      })
+    ).not.toThrow();
+  });
+});

package/src/severity.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+export const severitySchema = z.enum(["critical", "serious", "moderate", "minor"]);
+export type Severity = z.infer<typeof severitySchema>;
+
+export const severityLevelSchema = z.enum(["error", "warn"]);
+export type SeverityLevel = z.infer<typeof severityLevelSchema>;
+
+export const legacySeverityLevelSchema = z.enum(["error", "warn", "info", "warning"]);
+export type LegacySeverityLevel = z.infer<typeof legacySeverityLevelSchema>;
+
+export const SEVERITIES = severitySchema.options;
+
+export const SEVERITY_WEIGHTS: Record<Severity, number> = {
+  critical: 10,
+  serious: 5,
+  moderate: 2,
+  minor: 1,
+};
+
+export const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 4,
+  serious: 3,
+  moderate: 2,
+  minor: 1,
+};
+
+export function severityLevel(severity: Severity): SeverityLevel {
+  return severity === "critical" || severity === "serious" ? "error" : "warn";
+}
+
+export function severityFromLevel(level: LegacySeverityLevel): Severity {
+  switch (level) {
+    case "error":
+      return "serious";
+    case "warn":
+    case "warning":
+      return "moderate";
+    case "info":
+      return "minor";
+  }
+}
+
+export function compareSeverity(a: Severity, b: Severity): number {
+  return SEVERITY_RANK[b] - SEVERITY_RANK[a];
+}
+
+export function maxSeverity(a: Severity, b: Severity): Severity {
+  return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+
+export function sortBySeverity<T>(items: readonly T[], getSeverity: (item: T) => Severity): T[] {
+  return items.slice().sort((a, b) => compareSeverity(getSeverity(a), getSeverity(b)));
+}