import { describe, expect, it } from "vitest"; import { compileFragment, defineConfig, defineFragment, g } from "./index.js"; type ButtonProps = { variant?: "primary" | "secondary" | "ghost" | "link"; size?: "sm" | "md" | "lg"; disabled?: boolean; }; function Button(_props: ButtonProps) { return null; } describe("governance DSL", () => { it("defineConfig accepts global governance records", () => { const config = defineConfig({ include: ["src/**/*.fragment.ts"], tokens: { include: ["src/styles/tokens.scss"], }, govern: { presets: ["fragments/recommended"], scales: { space: g.scale.px([0, 4, 8, 12, 16]), typeSize: g.scale.px([12, 14, 16]), }, styles: [ g.styles.rawColors().forbid({ except: ["transparent", "currentColor"], prefer: "token", severity: "error", }), g.styles.rawSpacing().mustMatchScale("space", { appliesTo: ["gap", "padding"], severity: "error", }), g.styles.fontSize().mustMatchScale("typeSize", { severity: "warn", }), g.styles.cssVars().mustBeDefined({ severity: "error", }), ], jsx: [ g.jsx.unknownProps().forbid({ severity: "error" }), g.jsx.inlineStyle().forbidRaw(["color", "backgroundColor"]), ], agent: { repairOrder: ["apply-deterministic-fixes"], }, }, }); expect(config.govern?.scales?.space).toEqual({ kind: "scale", name: "space", unit: "px", values: [0, 4, 8, 12, 16], }); expect(config.govern?.styles?.[0]).toMatchObject({ kind: "style.rawColors.forbid", severity: "error", }); }); it("throws when a governance severity is malformed", () => { expect(() => defineConfig({ include: ["src/**/*.fragment.ts"], govern: { styles: [ g.styles.rawColors().forbid({ severity: "loud" as never, }), ], }, }) ).toThrow("Invalid fragments config"); }); it("throws when scale values are not numbers", () => { expect(() => defineConfig({ include: ["src/**/*.fragment.ts"], govern: { scales: { space: g.scale.px([0, "4" as never]), }, }, }) ).toThrow("Invalid fragments config"); }); it("accepts registry canonical sources for install receipt governance", () => { const config = defineConfig({ include: ["src/**/*.fragment.ts"], govern: { canonicalSources: [ { kind: "registry", registryId: "fragments-ui", registryHash: "a".repeat(64), receiptPath: ".fragments/registry-lock.json", installPath: "src/fragments/ui", importPath: "@/fragments/ui", severity: "error", }, ], }, }); expect(config.govern?.canonicalSources?.[0]).toMatchObject({ kind: "registry", registryId: "fragments-ui", installPath: "src/fragments/ui", }); }); it("accepts canonical source include lists", () => { const config = defineConfig({ include: ["src/**/*.fragment.ts"], govern: { canonicalSources: [ { kind: "npm", specifier: "@acme/ui", implementationPath: "src/ui", include: ["Button", "Tabs"], }, ], }, }); expect(config.govern?.canonicalSources?.[0]).toMatchObject({ kind: "npm", specifier: "@acme/ui", implementationPath: "src/ui", include: ["Button", "Tabs"], }); }); it("rejects unsafe registry canonical source paths", () => { expect(() => defineConfig({ include: ["src/**/*.fragment.ts"], govern: { canonicalSources: [ { kind: "registry", registryId: "fragments-ui", installPath: "../ui", }, ], }, }) ).toThrow("Invalid fragments config"); }); it("accepts component-specific governance overrides in config", () => { const config = defineConfig({ include: ["src/**/*.fragment.ts"], govern: { rules: { "components/usage": { enabled: true, severity: "warn" }, }, overrides: [ { match: { path: "src/components/ui/button.tsx", export: "Button", }, rules: [ g.component.prop("variant").forbid("link", { because: "Use Link for navigation.", severity: "error", }), g.component.accessibility().requireName({ because: "Buttons must announce their action.", }), ], }, ], }, }); expect(config.govern?.overrides?.[0]).toMatchObject({ match: { path: "src/components/ui/button.tsx", export: "Button", }, rules: [ { kind: "prop.value.forbid", prop: "variant", value: "link", severity: "error", }, { kind: "a11y.requireName", severity: "error", }, ], }); }); it("normalizes component governance records from defineFragment", () => { const fragment = defineFragment({ component: Button, meta: { name: "Button", description: "Interactive element for user-triggered actions.", category: "forms", }, guidance: { when: ["Submitting forms"], whenNot: ["Simple navigation without side effects"], }, govern: (govern) => [ govern.capability("dom.button"), govern.prop("variant").avoid("link", { because: "Use Link for ordinary navigation.", severity: "warn", }), govern.prop("variant").forbid("secondary", { when: { path: "apps/checkout/**" }, because: "Checkout CTAs should stay visually dominant.", fix: { replaceWith: "primary" }, severity: "error", }), govern.accessibility().requireName({ because: "Buttons must announce their action.", severity: "error", }), ], }); expect(fragment.governance).toEqual([ { kind: "capability", capability: "dom.button" }, { kind: "prop.value.avoid", prop: "variant", value: "link", because: "Use Link for ordinary navigation.", severity: "warn", }, { kind: "prop.value.forbid", prop: "variant", value: "secondary", when: { path: "apps/checkout/**" }, because: "Checkout CTAs should stay visually dominant.", fix: { replaceWith: "primary" }, severity: "error", }, { kind: "a11y.requireName", because: "Buttons must announce their action.", severity: "error", }, ]); }); it("compiles governed fragments with guidance and governance records", () => { const fragment = defineFragment({ component: Button, meta: { name: "Button", description: "Interactive element for user-triggered actions.", category: "forms", }, guidance: { when: ["Submitting forms"], whenNot: ["Simple navigation without side effects"], }, govern: (govern) => [ govern.capability("dom.button"), govern.prop("variant").forbid("secondary", { because: "Checkout CTAs should stay visually dominant.", severity: "error", }), ], }); const compiled = compileFragment(fragment, "src/components/Button.fragment.ts"); expect(compiled.meta.name).toBe("Button"); expect(compiled.guidance?.when).toEqual(["Submitting forms"]); expect(compiled.usage.when).toEqual(["Submitting forms"]); expect(compiled.governance).toEqual([ { kind: "capability", capability: "dom.button" }, { kind: "prop.value.forbid", prop: "variant", value: "secondary", because: "Checkout CTAs should stay visually dominant.", severity: "error", }, ]); }); });