@usefragments/core 1.0.0

package/src/facts/facts.test.ts

@@ -0,0 +1,494 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  asComponentId,
+  componentId as makeComponentId,
+  defineConfig,
+  defineFragment,
+  factId,
+  FactIndex,
+  compileComponentFacts,
+  compileGlobalGovernanceFacts,
+  g,
+  makeUsageNodeFact,
+} from "../index.js";
+import type { ComponentId, FactId, PropValueForbiddenFact } from "../index.js";
+
+type ButtonProps = {
+  variant?: "primary" | "secondary" | "ghost" | "link";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+};
+
+function Button(_props: ButtonProps) {
+  return null;
+}
+
+function buildSampleFragment() {
+  return 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"],
+    },
+    props: {
+      variant: {
+        type: "enum",
+        values: ["primary", "secondary", "ghost", "link"],
+        description: "Visual style",
+        required: false,
+      },
+      size: {
+        type: "enum",
+        values: ["sm", "md", "lg"],
+        description: "Size of the button",
+        required: false,
+      },
+      disabled: {
+        type: "boolean",
+        description: "Disables the button",
+        required: false,
+      },
+    },
+    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",
+      }),
+    ],
+  });
+}
+
+const buttonId = makeComponentId("@usefragments/ui", "Button");
+
+describe("fact IR — content-addressed IDs", () => {
+  it("authors owned component package ids with the active package epoch", () => {
+    expect(makeComponentId("@usefragments/ui", "Button")).toBe("@usefragments/ui#Button");
+    expect(makeComponentId("@acme/ui", "Button")).toBe("@acme/ui#Button");
+  });
+
+  it("emits the same fact IDs across runs for the same input", () => {
+    const a = compileComponentFacts(buttonId, buildSampleFragment());
+    const b = compileComponentFacts(buttonId, buildSampleFragment());
+
+    expect(a.map((f) => f.id)).toEqual(b.map((f) => f.id));
+  });
+
+  it("does not change component or policy fact IDs when source location moves", () => {
+    const baseline = compileComponentFacts(buttonId, buildSampleFragment());
+
+    // Different filePath simulates a moved component file. Identity inputs for
+    // component/policy facts are componentId/prop/value/path-pattern only —
+    // never the source location of the .fragment.ts file.
+    const movedFragment = buildSampleFragment();
+    movedFragment._provenance = {
+      source: "manual",
+      verified: true,
+      sourceFile: "src/components/Button.fragment.ts",
+    } as never;
+    const moved = compileComponentFacts(buttonId, movedFragment);
+
+    expect(moved.map((f) => f.id)).toEqual(baseline.map((f) => f.id));
+  });
+
+  it("usage_node fact IDs include stable node identity inputs, not raw line/col", () => {
+    const a = makeUsageNodeFact({
+      file: "apps/checkout/page.tsx",
+      nodePath: "0/2/1",
+      element: "Button",
+      location: { file: "apps/checkout/page.tsx", line: 42, column: 8 },
+    });
+    const b = makeUsageNodeFact({
+      file: "apps/checkout/page.tsx",
+      nodePath: "0/2/1",
+      element: "Button",
+      // Same identity inputs, different location — moved several lines down.
+      location: { file: "apps/checkout/page.tsx", line: 87, column: 12 },
+    });
+
+    expect(a.id).toBe(b.id);
+
+    // Identity changes when any of file / nodePath / element changes.
+    const moved = makeUsageNodeFact({
+      file: "apps/checkout/page.tsx",
+      nodePath: "0/2/2",
+      element: "Button",
+      location: { file: "apps/checkout/page.tsx", line: 42, column: 8 },
+    });
+    expect(moved.id).not.toBe(a.id);
+  });
+
+  it("factId() canonicalizes attribute order", () => {
+    const a = factId("prop_value_forbidden", {
+      componentId: buttonId,
+      prop: "variant",
+      value: "secondary",
+      pathPattern: "apps/checkout/**",
+    });
+    const b = factId("prop_value_forbidden", {
+      pathPattern: "apps/checkout/**",
+      value: "secondary",
+      prop: "variant",
+      componentId: buttonId,
+    });
+
+    expect(a).toBe(b);
+  });
+
+  it("keeps v1 IDs stable across owned package spellings only in typed identity fields", () => {
+    const legacyComponentId = asComponentId("@fragments-sdk/ui#Button");
+    const currentComponentId = asComponentId("@usefragments/ui#Button");
+
+    expect(factId("component", { componentId: legacyComponentId })).toBe(
+      factId("component", { componentId: currentComponentId })
+    );
+    expect(
+      factId("jsx_import_path_preferred", {
+        from: "@fragments-sdk/ui/legacy",
+        to: "@fragments-sdk/ui",
+      })
+    ).toBe(
+      factId("jsx_import_path_preferred", {
+        from: "@usefragments/ui/legacy",
+        to: "@usefragments/ui",
+      })
+    );
+    expect(
+      factId("jsx_component_preferred", {
+        from: legacyComponentId,
+        to: asComponentId("@fragments-sdk/ui#Link"),
+      })
+    ).toBe(
+      factId("jsx_component_preferred", {
+        from: currentComponentId,
+        to: asComponentId("@usefragments/ui#Link"),
+      })
+    );
+    expect(
+      factId("usage_import", {
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@fragments-sdk/ui",
+      })
+    ).toBe(
+      factId("usage_import", {
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@usefragments/ui",
+      })
+    );
+
+    expect(factId("component", { componentId: "@acme/ui#Button" })).not.toBe(
+      factId("component", { componentId: "@other/ui#Button" })
+    );
+    expect(factId("marker", { generated_by: "@fragments-sdk/ui" })).not.toBe(
+      factId("marker", { generated_by: "@usefragments/ui" })
+    );
+  });
+});
+
+describe("FactIndex — query layer", () => {
+  function buildIndex(): FactIndex {
+    const ix = new FactIndex();
+    ix.addMany(compileComponentFacts(buttonId, buildSampleFragment()));
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        scales: {
+          space: g.scale.px([0, 4, 8, 12, 16]),
+        },
+        styles: [
+          g.styles.rawColors().forbid({
+            except: ["transparent"],
+            prefer: "token",
+            severity: "error",
+          }),
+          g.styles.rawSpacing().mustMatchScale("space", {
+            appliesTo: ["padding", "gap"],
+            severity: "error",
+          }),
+        ],
+        jsx: [g.jsx.unknownProps().forbid({ severity: "error" })],
+      })
+    );
+    return ix;
+  }
+
+  it("resolves components.byId() to the component metadata fact", () => {
+    const ix = buildIndex();
+    const component = ix.components.byId(buttonId);
+
+    expect(component?.kind).toBe("component");
+    expect(component?.componentId).toBe(buttonId);
+    expect(component?.name).toBe("Button");
+    expect(component?.category).toBe("forms");
+  });
+
+  it("queries legacy/current component ids as one logical identity without duplicate facts", () => {
+    const legacyId = asComponentId("@usefragments/ui#Button");
+    const currentId = asComponentId("@usefragments/ui#Button");
+    const ix = new FactIndex();
+    ix.addMany(compileComponentFacts(legacyId, buildSampleFragment()));
+    ix.addMany(compileComponentFacts(currentId, buildSampleFragment()));
+
+    expect(ix.components.byId(currentId)?.componentId).toBe(legacyId);
+    expect(ix.components.list()).toHaveLength(1);
+    expect(
+      ix.components
+        .propsOf(currentId)
+        .map((fact) => fact.prop)
+        .sort()
+    ).toEqual(["disabled", "size", "variant"]);
+    expect(ix.policy.forbiddenPropValues(currentId)).toHaveLength(1);
+  });
+
+  it("resolves prop metadata for a component", () => {
+    const ix = buildIndex();
+
+    const props = ix.components.propsOf(buttonId);
+    expect(props.map((p) => p.prop).sort()).toEqual(["disabled", "size", "variant"]);
+
+    const variant = ix.components.propOf(buttonId, "variant");
+    expect(variant?.type).toBe("enum");
+    expect(variant?.values).toEqual(["primary", "secondary", "ghost", "link"]);
+    expect(variant?.required).toBe(false);
+
+    const disabled = ix.components.propOf(buttonId, "disabled");
+    expect(disabled?.type).toBe("boolean");
+  });
+
+  it("resolves component capabilities", () => {
+    const ix = buildIndex();
+
+    const capabilities = ix.components.capabilitiesOf(buttonId);
+    expect(capabilities.map((c) => c.capability)).toEqual(["dom.button"]);
+  });
+
+  it("resolves policy records by component, property, and path", () => {
+    const ix = buildIndex();
+
+    const allForbidden = ix.policy.forbiddenPropValues(buttonId);
+    expect(allForbidden).toHaveLength(1);
+
+    const forVariant = ix.policy.forbiddenPropValues(buttonId, { prop: "variant" });
+    expect(forVariant).toHaveLength(1);
+    expect(forVariant[0].value).toBe("secondary");
+    expect(forVariant[0].pathPattern).toBe("apps/checkout/**");
+
+    const inCheckout = ix.policy.forbiddenPropValues(buttonId, {
+      prop: "variant",
+      path: "apps/checkout/cart/page.tsx",
+    });
+    expect(inCheckout).toHaveLength(1);
+
+    const inMarketing = ix.policy.forbiddenPropValues(buttonId, {
+      prop: "variant",
+      path: "apps/marketing/home.tsx",
+    });
+    expect(inMarketing).toHaveLength(0);
+
+    const avoided = ix.policy.avoidedPropValues(buttonId, { prop: "variant" });
+    expect(avoided).toHaveLength(1);
+    expect(avoided[0].value).toBe("link");
+
+    const a11y = ix.policy.a11yNameRequired(buttonId);
+    expect(a11y?.severity).toBe("error");
+  });
+
+  it("resolves global policy facts", () => {
+    const ix = buildIndex();
+
+    expect(
+      ix.policy
+        .scales()
+        .map((s) => s.name)
+        .sort()
+    ).toEqual(["space"]);
+    expect(
+      ix.policy
+        .scaleValues("space")
+        .map((v) => v.value)
+        .sort((a, b) => a - b)
+    ).toEqual([0, 4, 8, 12, 16]);
+
+    const rawColors = ix.policy.rawColorPolicy();
+    expect(rawColors?.except).toEqual(["transparent"]);
+
+    const padding = ix.policy.propertyScale("padding");
+    expect(padding?.scale).toBe("space");
+    const gap = ix.policy.propertyScale("gap");
+    expect(gap?.scale).toBe("space");
+
+    const unknownProps = ix.policy.jsxUnknownPropsForbidden();
+    expect(unknownProps?.severity).toBe("error");
+  });
+
+  it("activates prefer-library from top-level canonical sources", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+      })
+    );
+
+    expect(ix.policy.ruleConfig("components/prefer-library")).toMatchObject({
+      enabled: true,
+      severity: "warn",
+      options: {
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+      },
+    });
+  });
+
+  it("resolves preferred import and component policy facts", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        jsx: [
+          g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui", {
+            imported: "Button",
+            severity: "warn",
+          }),
+          g.jsx.component().prefer("@legacy/ui#LegacyButton", "@usefragments/ui#Button", {
+            severity: "error",
+          }),
+        ],
+      })
+    );
+
+    expect(ix.policy.jsxImportPathPreferred({ from: "@legacy/ui" })).toMatchObject([
+      {
+        kind: "jsx_import_path_preferred",
+        from: "@legacy/ui",
+        to: "@usefragments/ui",
+        imported: "Button",
+        severity: "warn",
+      },
+    ]);
+    expect(ix.policy.jsxComponentPreferred()).toMatchObject([
+      {
+        kind: "jsx_component_preferred",
+        from: "@legacy/ui#LegacyButton",
+        to: "@usefragments/ui#Button",
+        severity: "error",
+      },
+    ]);
+  });
+
+  it("evidence([]) rejects missing fact IDs", () => {
+    const ix = buildIndex();
+    const componentFact = ix.components.byId(buttonId)!;
+    const propFact = ix.components.propOf(buttonId, "variant")!;
+    const ghost = "prop_value_forbidden:ghosts0123456789" as FactId;
+
+    const ok = ix.evidence([componentFact.id, propFact.id]);
+    expect(ok.map((e) => e.factId)).toEqual([componentFact.id, propFact.id]);
+
+    expect(() => ix.evidence([componentFact.id, ghost])).toThrow(/missing/i);
+  });
+
+  it("warns and keeps the first fact when a conflicting fact reuses an id", () => {
+    const ix = new FactIndex();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const id = factId("prop_value_forbidden", {
+      componentId: buttonId,
+      prop: "variant",
+      value: "secondary",
+    });
+    const a: PropValueForbiddenFact = {
+      id,
+      kind: "prop_value_forbidden",
+      componentId: buttonId,
+      prop: "variant",
+      value: "secondary",
+      because: "first",
+      severity: "error",
+    };
+    const b: PropValueForbiddenFact = {
+      ...a,
+      because: "second",
+    };
+    ix.add(a);
+    expect(() => ix.add(b)).not.toThrow();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"));
+    expect(ix.get(id)).toEqual(a);
+    warn.mockRestore();
+  });
+
+  it("treats old and current owned component spellings as the same indexed facts", () => {
+    const legacyId = asComponentId("@fragments-sdk/ui#Button");
+    const currentId = asComponentId("@usefragments/ui#Button");
+    const legacy = compileComponentFacts(legacyId, buildSampleFragment());
+    const current = compileComponentFacts(currentId, buildSampleFragment());
+    const ix = new FactIndex();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    ix.addMany(legacy);
+    ix.addMany(current);
+
+    expect(warn).not.toHaveBeenCalled();
+    expect(ix.size()).toBe(legacy.length);
+    expect(ix.components.byId(legacyId)?.name).toBe("Button");
+    expect(ix.components.byId(currentId)?.name).toBe("Button");
+    warn.mockRestore();
+  });
+});
+
+describe("fact IR — deterministic snapshot", () => {
+  it("compiles the sample fragment to a stable, sorted snapshot", () => {
+    const config = defineConfig({
+      include: ["src/**/*.fragment.ts"],
+      govern: {
+        scales: {
+          space: g.scale.px([0, 4, 8]),
+        },
+        styles: [
+          g.styles.rawColors().forbid({
+            except: ["transparent"],
+            prefer: "token",
+            severity: "error",
+          }),
+        ],
+      },
+    });
+
+    const facts = [
+      ...compileGlobalGovernanceFacts(config.govern),
+      ...compileComponentFacts(buttonId, buildSampleFragment()),
+    ].sort((a, b) => a.id.localeCompare(b.id));
+
+    expect(facts).toMatchSnapshot();
+  });
+});
+
+// Convenience type assertion to keep TS happy if FactId is unused above.
+const _typeWitness: ComponentId = buttonId;
+void _typeWitness;

package/src/facts/ids.ts

@@ -0,0 +1,125 @@
+/**
+ * Content-addressed fact IDs.
+ *
+ * A fact ID is a deterministic function of (kind, identity). Two runs over the
+ * same inputs produce identical IDs; identity attribute order is irrelevant
+ * because the payload is canonicalized before hashing.
+ *
+ * The hash is a 64-bit FNV-1a (computed as two 32-bit halves with different
+ * seeds). It is not a cryptographic hash — fact IDs are integrity references
+ * inside one build, not security tokens.
+ */
+
+import {
+  authorOwnedImport,
+  projectV1OwnedComponentId,
+  projectV1OwnedImportIdentity,
+} from "../package-identity.js";
+import type { ComponentId, FactId } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON
+// ---------------------------------------------------------------------------
+
+export function canonicalJson(value: unknown): string {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+
+// ---------------------------------------------------------------------------
+// 64-bit FNV-1a (two 32-bit halves with different seeds)
+// ---------------------------------------------------------------------------
+
+const FNV_PRIME = 0x01000193;
+const FNV_SEED_A = 0x811c9dc5;
+const FNV_SEED_B = 0x9e3779b1;
+
+function fnv1a32(input: string, seed: number): number {
+  let hash = seed >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    hash ^= code & 0xff;
+    hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    if (code > 0xff) {
+      hash ^= (code >>> 8) & 0xff;
+      hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+  }
+  return hash >>> 0;
+}
+
+export function hash64Hex(input: string): string {
+  const a = fnv1a32(input, FNV_SEED_A);
+  const b = fnv1a32(input, FNV_SEED_B);
+  return a.toString(16).padStart(8, "0") + b.toString(16).padStart(8, "0");
+}
+
+// ---------------------------------------------------------------------------
+// IDs
+// ---------------------------------------------------------------------------
+
+export function componentId(packageName: string, name: string): ComponentId {
+  if (!packageName.length || !name.length) {
+    throw new Error("componentId requires a non-empty packageName and name");
+  }
+  return `${authorOwnedImport(packageName)}#${name}` as ComponentId;
+}
+
+export function asComponentId(value: string): ComponentId {
+  if (!value.includes("#")) {
+    throw new Error(`componentId must look like "package#Name", got "${value}"`);
+  }
+  return value as ComponentId;
+}
+
+/**
+ * Compute a content-addressed fact ID. Identity is canonicalized so attribute
+ * order is irrelevant.
+ */
+export function factId(kind: string, identity: Record<string, unknown>): FactId {
+  const payload = canonicalJson({ k: kind, i: projectFactIdentityV1(kind, identity) });
+  return `${kind}:${hash64Hex(payload)}` as FactId;
+}
+
+/**
+ * Preserve the immutable v1 fact-id domain across the public package rename.
+ * Projection is deliberately kind/key aware: arbitrary strings must not be
+ * rewritten merely because they resemble one of our package names.
+ */
+function projectFactIdentityV1(
+  kind: string,
+  identity: Record<string, unknown>
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(identity).map(([key, value]) => {
+      if (key === "componentId" && typeof value === "string") {
+        return [key, projectV1OwnedComponentId(value)];
+      }
+      if (
+        kind === "jsx_component_preferred" &&
+        (key === "from" || key === "to") &&
+        typeof value === "string"
+      ) {
+        return [key, projectV1OwnedComponentId(value)];
+      }
+      if (
+        kind === "jsx_import_path_preferred" &&
+        (key === "from" || key === "to") &&
+        typeof value === "string"
+      ) {
+        return [key, projectV1OwnedImportIdentity(value)];
+      }
+      if (kind === "usage_import" && key === "source" && typeof value === "string") {
+        return [key, projectV1OwnedImportIdentity(value)];
+      }
+      return [key, value];
+    })
+  );
+}