@usefragments/core 1.10.2 → 2.0.0

package/src/contract/index.ts

@@ -5,15 +5,20 @@
  * projection that defines what the contract IS, the shared pin formatter, and
  * the committed reference catalog (`catalog-fixture-a`).
  */
-export { canonicalPreimage, contractHash, sha256Hex } from "./hash.js";
+export { artifactContentHash, canonicalPreimage, contractHash, sha256Hex } from "./hash.js";
 export {
+  CONTRACT_DISPLAY_ONLY_FIELDS,
   CONTRACT_DOMAINS,
+  CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractPolicyFromGovernanceConfig,
+  deriveArtifactId,
   diffContractDomains,
   projectContractPreimage,
+  projectEnforcementContract,
   verifiedContractPreimageFromPin,
 } from "./preimage.js";
 export type {
@@ -22,6 +27,7 @@ export type {
   ContractCatalogInput,
   ContractComponentInput,
   ContractDomain,
+  ContractEnforcementField,
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
@@ -44,3 +50,20 @@ export {
   catalogFixtureATokensDtcg,
   CATALOG_FIXTURE_A_FCID,
 } from "./fixture.js";
+export {
+  FRAGMENTS_MANIFEST_FILENAME,
+  FRAGMENTS_MANIFEST_SCHEMA_VERSION,
+  FRAGMENTS_MANIFEST_TOKEN_RULE,
+  fragmentsManifestFcid,
+  fragmentsManifestGrammarSchema,
+  fragmentsManifestPatternSchema,
+  fragmentsManifestPrimitiveSchema,
+  fragmentsManifestSchema,
+  parseFragmentsManifest,
+} from "./manifest.js";
+export type {
+  FragmentsManifest,
+  FragmentsManifestGrammar,
+  FragmentsManifestPattern,
+  FragmentsManifestPrimitive,
+} from "./manifest.js";

package/src/contract/manifest.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  FRAGMENTS_MANIFEST_FILENAME,
+  fragmentsManifestFcid,
+  fragmentsManifestSchema,
+  parseFragmentsManifest,
+  type FragmentsManifest,
+} from "./manifest.js";
+
+const SAMPLE: FragmentsManifest = {
+  schemaVersion: 1,
+  designSystem: { packageName: "@usefragments/ui", importPath: "@usefragments/ui" },
+  tokens: { prefix: "--fui-", rule: "no-raw-values" },
+  primitives: [
+    {
+      name: "Button",
+      members: [],
+      intents: ["action"],
+      props: ["variant", "size"],
+      do: ["one primary per view"],
+      dont: ["raw <button>"],
+      exemplar: "apps/cloud/src/page/findings/findings-page.tsx:212",
+    },
+  ],
+  patterns: [],
+  grammar: [],
+  rules: { preset: "fragments", off: [] },
+};
+
+describe("fragments.manifest schema", () => {
+  it("parses the v1 shape", () => {
+    expect(parseFragmentsManifest(SAMPLE)).toEqual(SAMPLE);
+  });
+
+  it("rejects a missing schemaVersion", () => {
+    const { schemaVersion: _schemaVersion, ...rest } = SAMPLE;
+    expect(() => parseFragmentsManifest(rest)).toThrow();
+  });
+
+  it("rejects a non-v1 schemaVersion", () => {
+    expect(() => parseFragmentsManifest({ ...SAMPLE, schemaVersion: 2 })).toThrow();
+  });
+
+  it("requires the no-raw-values token rule", () => {
+    expect(() =>
+      parseFragmentsManifest({
+        ...SAMPLE,
+        tokens: { prefix: "--fui-", rule: "prefer-tokens" },
+      })
+    ).toThrow();
+  });
+
+  it("keeps the committed filename stable", () => {
+    expect(FRAGMENTS_MANIFEST_FILENAME).toBe("fragments.manifest.json");
+  });
+});
+
+describe("fragmentsManifestFcid", () => {
+  it("returns a 64-char lowercase hex FCID", () => {
+    expect(fragmentsManifestFcid(SAMPLE)).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("is stable across object key order", () => {
+    const reordered = fragmentsManifestSchema.parse({
+      rules: SAMPLE.rules,
+      grammar: SAMPLE.grammar,
+      patterns: SAMPLE.patterns,
+      primitives: SAMPLE.primitives,
+      tokens: SAMPLE.tokens,
+      designSystem: SAMPLE.designSystem,
+      schemaVersion: 1,
+    });
+    expect(fragmentsManifestFcid(reordered)).toBe(fragmentsManifestFcid(SAMPLE));
+  });
+
+  it("changes when a primitive is added", () => {
+    const extended: FragmentsManifest = {
+      ...SAMPLE,
+      primitives: [
+        ...SAMPLE.primitives,
+        {
+          name: "Input",
+          members: [],
+          intents: [],
+          props: [],
+          do: [],
+          dont: [],
+        },
+      ],
+    };
+    expect(fragmentsManifestFcid(extended)).not.toBe(fragmentsManifestFcid(SAMPLE));
+  });
+});

package/src/contract/manifest.ts

@@ -0,0 +1,68 @@
+/**
+ * Design-system manifest v1 — the committed, human-curated vocabulary that
+ * every local agent surface reads. FCID is `contractHash(manifest)`.
+ */
+
+import { z } from "zod";
+
+import { contractHash } from "./hash.js";
+
+export const FRAGMENTS_MANIFEST_FILENAME = "fragments.manifest.json";
+export const FRAGMENTS_MANIFEST_SCHEMA_VERSION = 1;
+export const FRAGMENTS_MANIFEST_TOKEN_RULE = "no-raw-values";
+
+export const fragmentsManifestPrimitiveSchema = z.object({
+  name: z.string().min(1),
+  members: z.array(z.string()),
+  intents: z.array(z.string()),
+  props: z.array(z.string()),
+  do: z.array(z.string()),
+  dont: z.array(z.string()),
+  exemplar: z.string().min(1).optional(),
+});
+
+export const fragmentsManifestPatternSchema = z.object({
+  name: z.string().min(1),
+  intent: z.string(),
+  primitives: z.array(z.string()),
+  shape: z.string(),
+  exemplar: z.string().min(1).optional(),
+});
+
+export const fragmentsManifestGrammarSchema = z.object({
+  rule: z.string().min(1),
+  check: z.string().min(1).optional(),
+});
+
+export const fragmentsManifestSchema = z.object({
+  schemaVersion: z.literal(FRAGMENTS_MANIFEST_SCHEMA_VERSION),
+  designSystem: z.object({
+    packageName: z.string().min(1),
+    importPath: z.string().min(1),
+  }),
+  tokens: z.object({
+    prefix: z.string().min(1),
+    rule: z.literal(FRAGMENTS_MANIFEST_TOKEN_RULE),
+  }),
+  primitives: z.array(fragmentsManifestPrimitiveSchema),
+  patterns: z.array(fragmentsManifestPatternSchema),
+  grammar: z.array(fragmentsManifestGrammarSchema),
+  rules: z.object({
+    preset: z.string().min(1),
+    off: z.array(z.string()),
+  }),
+});
+
+export type FragmentsManifestPrimitive = z.infer<typeof fragmentsManifestPrimitiveSchema>;
+export type FragmentsManifestPattern = z.infer<typeof fragmentsManifestPatternSchema>;
+export type FragmentsManifestGrammar = z.infer<typeof fragmentsManifestGrammarSchema>;
+export type FragmentsManifest = z.infer<typeof fragmentsManifestSchema>;
+
+export function parseFragmentsManifest(input: unknown): FragmentsManifest {
+  return fragmentsManifestSchema.parse(input);
+}
+
+/** FCID for a parsed manifest: content-address, key-order independent. */
+export function fragmentsManifestFcid(manifest: FragmentsManifest): string {
+  return contractHash(manifest);
+}

package/src/contract/preimage.test.ts

@@ -10,14 +10,19 @@ import {
   catalogFixtureA,
   catalogFixtureAContractPayload,
 } from "./fixture.js";
-import { contractHash } from "./hash.js";
+import { artifactContentHash, contractHash } from "./hash.js";
 import {
   type ContractCatalogInput,
   type ContractComponentInput,
   type ContractTokenInput,
+  CONTRACT_DISPLAY_ONLY_FIELDS,
+  CONTRACT_ENFORCEMENT_FIELDS,
+  ContractCatalogValidationError,
   contractComponentsFromFragments,
+  deriveArtifactId,
   diffContractDomains,
   projectContractPreimage,
+  projectEnforcementContract,
   verifiedContractPreimageFromPin,
 } from "./preimage.js";
 import { formatStampPin } from "./stamp.js";
@@ -62,6 +67,70 @@ describe("§1 byte parity — one fixture, one hash, every runtime", () => {
   });
 });
 
+describe("catalog runtime validation", () => {
+  it("accepts partial legacy catalogs and ignores unknown future fields", () => {
+    const legacy = projectContractPreimage({ components: [{ name: "Button" }] });
+    const future = projectContractPreimage({
+      components: [{ name: "Button", futureHint: { mode: "v4" } }],
+      futureDomain: { enabled: true },
+    } as ContractCatalogInput);
+
+    expect(future).toEqual(legacy);
+  });
+
+  it("rejects malformed known fields with sorted, deterministic issues", () => {
+    const invalid = {
+      components: [{ name: "", props: "variant", contract: [] }],
+      tokens: [{ name: "--fui-space", value: Number.NaN }],
+      policy: { waivers: "waiver-1" },
+    } as unknown as ContractCatalogInput;
+
+    expect(() => projectContractPreimage(invalid)).toThrow(ContractCatalogValidationError);
+    try {
+      projectContractPreimage(invalid);
+    } catch (error) {
+      expect(error).toBeInstanceOf(ContractCatalogValidationError);
+      expect((error as ContractCatalogValidationError).issues).toEqual([
+        "components[0].contract: expected a plain object",
+        "components[0].name: expected a non-empty string",
+        "components[0].props: expected an array",
+        "policy.waivers: expected an array",
+        "tokens[0].value: expected a finite number or string",
+      ]);
+    }
+  });
+
+  it("rejects duplicate semantic identities instead of hashing ambiguous catalogs", () => {
+    const invalid = {
+      components: [{ name: "Button" }, { name: "Button" }],
+      tokens: [
+        { name: "--fui-space", value: "4px" },
+        { name: "--fui-space", value: "8px" },
+      ],
+      canonicalMappings: [
+        { component: "LegacyButton", canonical: "Button", status: "confirmed" },
+        { component: "LegacyButton", canonical: "LinkButton", status: "confirmed" },
+      ],
+      policy: {
+        waivers: [
+          { id: "waiver-1", target: "FUI1001", reason: "migration" },
+          { id: "waiver-1", target: "FUI1002", reason: "migration" },
+        ],
+      },
+    } satisfies ContractCatalogInput;
+
+    expect(() => projectContractPreimage(invalid)).toThrow(
+      [
+        "Invalid contract catalog:",
+        '  - canonicalMappings: duplicate confirmed identity "LegacyButton"',
+        '  - components: duplicate identity "#Button"',
+        '  - policy.waivers: duplicate identity "waiver-1"',
+        '  - tokens: duplicate identity "--fui-space"',
+      ].join("\n")
+    );
+  });
+});
+
 describe("published identity pin verification", () => {
   it("reconstructs the exact canonical preimage behind a matching FCID", () => {
     const preimage = projectContractPreimage(catalogFixtureA);
@@ -123,6 +192,16 @@ describe("§2 enforced-only — prose doesn't move the hash, enforcement does",
             ...component,
             description: "A lovingly rewritten description",
             docsUrl: "https://usefragments.com/docs/button",
+            contract: {
+              ...(typeof component.contract === "object" && component.contract
+                ? component.contract
+                : {}),
+              propsSummary: ["variant: display-only"],
+              canonicalUsage: ["<Button>Save</Button>"],
+              scenarioTags: ["marketing-copy"],
+              states: [{ name: "Primary", props: { children: "Save" } }],
+              variants: [{ prop: "variant", options: ["primary"] }],
+            },
           }) as ContractComponentInput
       ),
       tokens: (catalogFixtureA.tokens ?? []).map(
@@ -149,6 +228,145 @@ describe("§2 enforced-only — prose doesn't move the hash, enforcement does",
   });
 });
 
+describe("Brief 05 — FCID / artifact identity boundary", () => {
+  it("A05-02: governance, enforcement contract, compound, and prop-name edits move FCID", () => {
+    const base = catalogFixtureA;
+    const withGovernance: ContractCatalogInput = {
+      ...base,
+      components: (base.components ?? []).map((component, index) =>
+        index === 0
+          ? {
+              ...component,
+              governance: [
+                {
+                  kind: "a11y.requireName" as const,
+                  because: "icon-only buttons need an accessible name",
+                  severity: "error" as const,
+                },
+              ],
+            }
+          : component
+      ),
+    };
+    const withBan: ContractCatalogInput = {
+      ...base,
+      components: (base.components ?? []).map((component, index) =>
+        index === 0
+          ? {
+              ...component,
+              contract: {
+                bans: [
+                  { prop: "style", reason: "token-governed surface" },
+                  { prop: "className", reason: "prefer variants" },
+                ],
+              },
+            }
+          : component
+      ),
+    };
+    const withCompound: ContractCatalogInput = {
+      ...base,
+      components: (base.components ?? []).map((component) =>
+        component.name === "Card"
+          ? {
+              ...component,
+              compoundChildren: ["Card.Header", "Card.Body", "Card.Footer"],
+            }
+          : component
+      ),
+    };
+    const withProp: ContractCatalogInput = {
+      ...base,
+      components: (base.components ?? []).map((component, index) =>
+        index === 0 ? { ...component, props: [...(component.props ?? []), "loading"] } : component
+      ),
+    };
+
+    expect(fcidOf(withGovernance)).not.toBe(CATALOG_FIXTURE_A_FCID);
+    expect(fcidOf(withBan)).not.toBe(CATALOG_FIXTURE_A_FCID);
+    expect(fcidOf(withCompound)).not.toBe(CATALOG_FIXTURE_A_FCID);
+    expect(fcidOf(withProp)).not.toBe(CATALOG_FIXTURE_A_FCID);
+    expect(
+      diffContractDomains(projectContractPreimage(base), projectContractPreimage(withGovernance))
+    ).toEqual(["components"]);
+  });
+
+  it("A05-03: display-only fields are absent from the positive enforcement pick-list", () => {
+    for (const field of CONTRACT_DISPLAY_ONLY_FIELDS) {
+      expect(CONTRACT_ENFORCEMENT_FIELDS).not.toContain(field);
+    }
+    expect(
+      projectEnforcementContract({
+        propsSummary: ["variant: primary"],
+        canonicalUsage: ["<Button />"],
+        scenarioTags: ["hero"],
+        states: [{ name: "Primary" }],
+        variants: [{ prop: "variant", options: ["primary"] }],
+        a11yRules: ["no-empty-buttons"],
+      })
+    ).toEqual({ a11yRules: ["no-empty-buttons"] });
+  });
+
+  it("A05-01: guidance/example content moves artifactId while FCID stays fixed", () => {
+    const fcid = fcidOf(catalogFixtureA);
+    const artifactA = deriveArtifactId({
+      modules: [{ path: "Button.stories.tsx" }],
+      states: [{ name: "Primary", props: { children: "Save" } }],
+      guidance: { purpose: "Primary actions" },
+      runtime: { framework: "react" },
+    });
+    const artifactB = deriveArtifactId({
+      modules: [{ path: "Button.stories.tsx" }],
+      states: [{ name: "Primary", props: { children: "Save changes" } }],
+      guidance: { purpose: "Primary actions, revised copy" },
+      runtime: { framework: "react" },
+    });
+
+    expect(fcidOf(catalogFixtureA)).toBe(fcid);
+    expect(artifactA).toMatch(/^[0-9a-f]{64}$/);
+    expect(artifactB).toMatch(/^[0-9a-f]{64}$/);
+    expect(artifactA).not.toBe(artifactB);
+    expect(artifactA).not.toBe(fcid);
+    expect(artifactContentHash({ schema: "artifact-content:v1" })).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("A05-04: fragment adapters project resolved governance without migration ambiguity", () => {
+    const withoutGov = contractComponentsFromFragments([
+      {
+        meta: { name: "Button" },
+        props: { variant: {} },
+        contract: {
+          bans: [{ pattern: "style", message: "no" }],
+          propsSummary: ["variant"],
+        },
+      },
+    ]);
+    const withGov = contractComponentsFromFragments([
+      {
+        meta: { name: "Button" },
+        props: { variant: {} },
+        contract: {
+          bans: [{ pattern: "style", message: "no" }],
+          propsSummary: ["variant"],
+        },
+        governance: [
+          {
+            kind: "capability",
+            capability: "button",
+          },
+        ],
+      },
+    ]);
+
+    expect(withoutGov[0]?.governance).toBeUndefined();
+    expect(withGov[0]?.governance).toEqual([{ kind: "capability", capability: "button" }]);
+    expect(fcidOf({ components: withoutGov })).not.toBe(fcidOf({ components: withGov }));
+    expect(projectEnforcementContract(withoutGov[0]?.contract)).toEqual({
+      bans: [{ pattern: "style", message: "no" }],
+    });
+  });
+});
+
 describe("§3 proposed mappings are not identity", () => {
   it("adding a new proposed mapping leaves the fcid unchanged", () => {
     const withNewProposedMapping: ContractCatalogInput = {