@usefragments/core 1.0.0

package/src/contract/stamp.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Contract-identity ACCEPTANCE §5 (core half) — the shared stamp record:
+ * header form, frontmatter-safe serialization, and the tolerant parser that
+ * gates read the stamp back with.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { ContractDomain } from "./preimage.js";
+import {
+  type ContractStampRecord,
+  formatStampHeader,
+  parseContractStamp,
+  serializeContractStamp,
+} from "./stamp.js";
+
+const FCID = "a3f9e21b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785";
+const DOMAINS: Record<ContractDomain, string> = {
+  components: "1".repeat(64),
+  tokens: "2".repeat(64),
+  canonicalMap: "3".repeat(64),
+  policy: "4".repeat(64),
+};
+const RECORD: ContractStampRecord = { contractVersion: 12, fcid: FCID, domains: DOMAINS };
+
+describe("formatStampHeader", () => {
+  it("prefixes the shared pin formatter's output — never a second pin format", () => {
+    expect(formatStampHeader(RECORD)).toBe("fragments contract v12 · a3f9e21");
+  });
+});
+
+describe("serializeContractStamp", () => {
+  it("renders plain header lines with the literal header form on the first line", () => {
+    expect(serializeContractStamp(RECORD)).toBe(
+      [
+        "contract: fragments contract v12 · a3f9e21",
+        `contract-fcid: ${FCID}`,
+        `contract-domains: components=${DOMAINS.components} tokens=${DOMAINS.tokens} canonicalMap=${DOMAINS.canonicalMap} policy=${DOMAINS.policy}`,
+      ].join("\n")
+    );
+  });
+
+  it("omits the domains line when sub-hashes are unknown", () => {
+    const serialized = serializeContractStamp({ contractVersion: 12, fcid: FCID });
+    expect(serialized).not.toContain("contract-domains:");
+    expect(serialized.split("\n")).toHaveLength(2);
+  });
+});
+
+describe("parseContractStamp", () => {
+  it("round-trips serialize → parse, with and without domains", () => {
+    expect(parseContractStamp(serializeContractStamp(RECORD))).toEqual(RECORD);
+    expect(parseContractStamp(serializeContractStamp({ contractVersion: 12, fcid: FCID }))).toEqual(
+      { contractVersion: 12, fcid: FCID }
+    );
+  });
+
+  it("finds the stamp inside a rendered agent-context-shaped file", () => {
+    const rendered = `---
+generated_by: fragments-sdk@0.0.0
+preset: universal
+last_init: 2026-06-09T00:00:00.000Z
+${serializeContractStamp(RECORD)}
+---
+
+# Agent context for this project
+
+Prefer canonical components over raw HTML elements.
+`;
+    expect(parseContractStamp(rendered)).toEqual(RECORD);
+  });
+
+  it("returns null when the stamp is absent or malformed — never throws", () => {
+    expect(parseContractStamp("")).toBeNull();
+    expect(parseContractStamp("# Just markdown\n\ncontract talk, no stamp\n")).toBeNull();
+    // Header without the fcid line (and vice versa) is not a stamp.
+    expect(parseContractStamp("contract: fragments contract v12 · a3f9e21\n")).toBeNull();
+    expect(parseContractStamp(`contract-fcid: ${FCID}\n`)).toBeNull();
+    // Short fcid in the header must prefix the full fcid.
+    expect(
+      parseContractStamp(`contract: fragments contract v12 · 0000000\ncontract-fcid: ${FCID}\n`)
+    ).toBeNull();
+    // Truncated full fcid.
+    expect(
+      parseContractStamp(
+        `contract: fragments contract v12 · a3f9e21\ncontract-fcid: ${FCID.slice(0, 40)}\n`
+      )
+    ).toBeNull();
+    // Malformed domains line poisons the whole stamp.
+    expect(
+      parseContractStamp(
+        `${serializeContractStamp({ contractVersion: 12, fcid: FCID })}\ncontract-domains: components=zzz\n`
+      )
+    ).toBeNull();
+    expect(
+      parseContractStamp(
+        `${serializeContractStamp({ contractVersion: 12, fcid: FCID })}\ncontract-domains: components=${DOMAINS.components}\n`
+      )
+    ).toBeNull();
+  });
+});

package/src/contract/stamp.ts

@@ -0,0 +1,105 @@
+/**
+ * The shared contract pin formatter. Every surface that shows a human the
+ * contract identity — MCP metadata, agent context files, hook output, CI check
+ * text, PR comments — interpolates the string this
+ * function returns; no surface reformats it. One formatter is what makes
+ * "compare the hashes yourself" a falsifiable claim instead of three surfaces
+ * rendering the pin three ways.
+ *
+ * Display convention (spine "Identifiers"): never a bare hash without the
+ * version, never a version without the hash.
+ */
+
+import { CONTRACT_DOMAINS, type ContractDomain } from "./preimage.js";
+
+/** The committed agent context file every gate reads for local contract stamps. */
+export const AGENT_CONTEXT_RELATIVE_PATH = ".fragments/agent-context.md";
+
+/** Length of the abbreviated fcid in the display form. */
+const SHORT_FCID_LENGTH = 7;
+
+export interface ContractStampPin {
+  /** Monotonic, human-facing version from the ledger. */
+  contractVersion: number;
+  /** The 64-hex FCID; abbreviated for display. */
+  fcid: string;
+}
+
+export interface ContractStampRecord extends ContractStampPin {
+  /** Full 64-hex domain sub-hashes, when known. */
+  domains?: Record<ContractDomain, string>;
+}
+
+/**
+ * The bare `v12 · a3f9e21` form, for surfaces where "contract" is already said
+ * by the surrounding copy (e.g. the hook staleness line's `local v11 · 9c01b22`).
+ * {@link formatStampPin} delegates here so the two forms can never drift.
+ */
+export function formatStampVersionHash(pin: ContractStampPin): string {
+  return `v${pin.contractVersion} · ${pin.fcid.slice(0, SHORT_FCID_LENGTH)}`;
+}
+
+/**
+ * Render the canonical pin: `contract v12 · a3f9e21`.
+ */
+export function formatStampPin(pin: ContractStampPin): string {
+  return `contract ${formatStampVersionHash(pin)}`;
+}
+
+/** The context-file header form: `fragments contract v12 · a3f9e21`. */
+export function formatStampHeader(pin: ContractStampPin): string {
+  return `fragments ${formatStampPin(pin)}`;
+}
+
+/**
+ * Serialize pin + full fcid (+ domain hashes when known) as plain header lines —
+ * no markdown syntax, so the block is safe inside YAML-ish frontmatter and
+ * inside HTML-comment blocks. The first line carries the literal
+ * {@link formatStampHeader} output; surfaces grep for that substring, so the
+ * header form and the serialized form may never diverge.
+ */
+export function serializeContractStamp(record: ContractStampRecord): string {
+  const lines = [`contract: ${formatStampHeader(record)}`, `contract-fcid: ${record.fcid}`];
+  if (record.domains) {
+    const domains = record.domains;
+    lines.push(
+      `contract-domains: ${CONTRACT_DOMAINS.map((domain) => `${domain}=${domains[domain]}`).join(" ")}`
+    );
+  }
+  return lines.join("\n");
+}
+
+// Line-anchored so the stamp is found anywhere in a file — frontmatter, an
+// HTML-comment block, or a marker-merged region — without parsing the host
+// format.
+const STAMP_HEADER_LINE = /^contract:\s*fragments contract v(\d+) · ([0-9a-f]+)\s*$/mu;
+const STAMP_FCID_LINE = /^contract-fcid:\s*([0-9a-f]{64})\s*$/mu;
+const STAMP_DOMAINS_LINE = /^contract-domains:\s*(\S.*?)\s*$/mu;
+
+/**
+ * Parse a stamp record back out of arbitrary file text. Requires the
+ * `contract:` + `contract-fcid:` lines and an abbreviated fcid that prefixes
+ * the full one; `contract-domains` is optional. Returns null when absent or
+ * malformed — never throws.
+ */
+export function parseContractStamp(text: string): ContractStampRecord | null {
+  const header = STAMP_HEADER_LINE.exec(text);
+  const fcidLine = STAMP_FCID_LINE.exec(text);
+  if (!header || !fcidLine) return null;
+  const contractVersion = Number(header[1]);
+  if (!Number.isSafeInteger(contractVersion)) return null;
+  const fcid = fcidLine[1];
+  if (!fcid.startsWith(header[2])) return null;
+
+  const domainsLine = STAMP_DOMAINS_LINE.exec(text);
+  if (!domainsLine) return { contractVersion, fcid };
+
+  const domains = {} as Record<ContractDomain, string>;
+  for (const pair of domainsLine[1].split(/\s+/u)) {
+    const match = /^([a-zA-Z]+)=([0-9a-f]{64})$/u.exec(pair);
+    if (!match || !(CONTRACT_DOMAINS as readonly string[]).includes(match[1])) return null;
+    domains[match[1] as ContractDomain] = match[2];
+  }
+  if (CONTRACT_DOMAINS.some((domain) => !domains[domain])) return null;
+  return { contractVersion, fcid, domains };
+}

package/src/contract-parser.ts

@@ -0,0 +1,141 @@
+/**
+ * Component Contract Parser — converts .contract.json files to CompiledFragment.
+ *
+ * Maps the framework-agnostic ComponentContract format to the same
+ * CompiledFragment type used by .fragment.tsx, so all downstream consumers
+ * (MCP tools, governance, search) work unchanged.
+ */
+
+import { componentContractSchema } from './component-contract.js';
+import type { ComponentContract } from './component-contract.js';
+
+// Use the context package's CompiledFragment type via re-export from types.ts
+// Since core can't depend on context, we define the minimal output shape here
+// that matches CompiledFragment structurally.
+
+export interface CompiledContractOutput {
+  filePath: string;
+  meta: {
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[];
+    status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
+    figma?: string;
+    figmaProps?: Record<string, unknown>;
+  };
+  usage: {
+    when: string[];
+    whenNot: string[];
+    guidelines?: string[];
+    accessibility?: string[];
+  };
+  props: Record<string, {
+    type: string;
+    description: string;
+    default?: unknown;
+    required?: boolean;
+    values?: string[];
+    constraints?: string[];
+  }>;
+  relations?: Array<{
+    component: string;
+    relationship: 'alternative' | 'parent' | 'child' | 'sibling' | 'composition' | 'complementary' | 'used-by';
+    note: string;
+  }>;
+  variants: Array<{
+    name: string;
+    description: string;
+    code?: string;
+    args?: Record<string, unknown>;
+  }>;
+  contract?: {
+    propsSummary?: string[];
+    scenarioTags?: string[];
+    a11yRules?: string[];
+    bans?: Array<{ pattern: string; message: string }>;
+    compoundChildren?: Record<string, {
+      required?: boolean;
+      accepts?: string[];
+      description?: string;
+    }>;
+    canonicalUsage?: string[];
+    performanceBudget?: number;
+  };
+  /** Framework hint from contract, used by extractor adapter selection */
+  framework?: string;
+  /** AI metadata for compound component generation */
+  ai?: {
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    subComponents?: string[];
+    requiredChildren?: string[];
+    commonPatterns?: string[];
+  };
+  /** Top-level compact prop summaries for agent first-pass */
+  propsSummary?: string[];
+  /** Provenance tracking */
+  provenance?: {
+    source: string;
+    verified: boolean;
+    frameworkSupport?: string;
+    sourceHash?: string;
+    extractedAt?: string;
+  };
+  /** Source file path relative to config root */
+  sourcePath?: string;
+  /** Named export from source file */
+  exportName?: string;
+}
+
+/**
+ * Check if a file path is a component contract file.
+ */
+export function isContractFile(filePath: string): boolean {
+  return filePath.endsWith('.contract.json');
+}
+
+/**
+ * Parse a component contract JSON file into CompiledFragment-compatible output.
+ */
+export function parseComponentContract(
+  content: string,
+  filePath: string,
+): CompiledContractOutput {
+  const raw = JSON.parse(content);
+  const validated: ComponentContract = componentContractSchema.parse(raw);
+
+  return {
+    filePath,
+    meta: {
+      name: validated.name,
+      description: validated.description,
+      category: validated.category,
+      tags: validated.tags,
+      status: validated.status,
+      figma: validated.figma?.nodeUrl,
+      figmaProps: validated.figma?.propMappings as Record<string, unknown> | undefined,
+    },
+    usage: validated.usage,
+    props: validated.props,
+    relations: validated.relations ?? [],
+    variants: (validated.examples ?? []).map((ex) => ({
+      name: ex.name,
+      description: ex.description,
+      code: ex.code,
+      args: ex.args,
+    })),
+    contract: validated.contract ? {
+      ...validated.contract,
+      // Merge top-level propsSummary into contract.propsSummary if not already set
+      propsSummary: validated.contract.propsSummary ?? validated.propsSummary,
+    } : {
+      propsSummary: validated.propsSummary,
+    },
+    framework: validated.framework,
+    ai: validated.ai,
+    propsSummary: validated.propsSummary,
+    provenance: validated.provenance,
+    sourcePath: validated.sourcePath,
+    exportName: validated.exportName,
+  };
+}

package/src/defineFragment.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect } from 'vitest';
+import { defineFragment, compileFragment, normalizeToV1 } from './defineFragment.js';
+import type {
+  FragmentDefinition,
+  FragmentDefinitionV2,
+  FragmentVariant,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers — minimal component stubs
+// ---------------------------------------------------------------------------
+
+function StubComponent(_props: { children?: string }) {
+  return null;
+}
+
+const renderStub = () => null;
+
+function makeV1(): FragmentDefinition<{ children?: string }> {
+  return {
+    component: StubComponent,
+    meta: { name: 'Stub', description: 'A stub', category: 'test', status: 'stable' },
+    usage: {
+      when: ['Testing v1'],
+      whenNot: ['Production'],
+    },
+    props: {
+      children: { type: 'node', description: 'Content', required: false },
+    },
+    variants: [
+      { name: 'Default', description: 'Default variant', render: renderStub },
+    ],
+    ai: {
+      compositionPattern: 'simple',
+    },
+    contract: {
+      propsSummary: ['children: node'],
+    },
+    _generated: {
+      source: 'manual',
+      confidence: 1,
+    },
+  };
+}
+
+function makeV2(): FragmentDefinitionV2<{ children?: string }> {
+  return {
+    component: StubComponent,
+    meta: { name: 'Stub', description: 'A stub', category: 'test', status: 'stable' },
+    guidance: {
+      when: ['Testing v2'],
+      whenNot: ['Production'],
+    },
+    props: {
+      children: { type: 'node', description: 'Content', required: false },
+    },
+    examples: [
+      { name: 'Default', description: 'Default example', render: renderStub },
+    ],
+    composition: {
+      pattern: 'compound',
+      subComponents: ['Header', 'Body'],
+      requiredChildren: ['Body'],
+      commonPatterns: ['<Stub><Stub.Header /><Stub.Body /></Stub>'],
+    },
+    contract: {
+      propsSummary: ['children: node'],
+    },
+    _provenance: {
+      source: 'scan',
+      confidence: 0.85,
+      autoFields: ['props', 'composition'],
+      humanFields: ['guidance', 'examples'],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// defineFragment — v1 shape
+// ---------------------------------------------------------------------------
+
+describe('defineFragment — v1 shape', () => {
+  it('accepts and returns v1 definition unchanged', () => {
+    const v1 = makeV1();
+    const result = defineFragment(v1);
+    expect(result).toBe(v1);
+    expect(result.usage.when).toEqual(['Testing v1']);
+    expect(result.variants[0].name).toBe('Default');
+    expect(result.ai?.compositionPattern).toBe('simple');
+  });
+
+  it('throws on invalid v1 definition', () => {
+    const invalid = {
+      component: StubComponent,
+      meta: { name: '', description: 'bad', category: 'test' }, // empty name
+      usage: { when: [], whenNot: [] },
+      props: {},
+      variants: [],
+    } as unknown as FragmentDefinition;
+
+    expect(() => defineFragment(invalid)).toThrow('Invalid fragment definition');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defineFragment — v2 shape
+// ---------------------------------------------------------------------------
+
+describe('defineFragment — v2 shape', () => {
+  it('accepts and returns v2 definition unchanged', () => {
+    const v2 = makeV2();
+    const result = defineFragment(v2);
+    expect(result).toBe(v2);
+    expect((result as FragmentDefinitionV2).guidance.when).toEqual(['Testing v2']);
+    expect((result as FragmentDefinitionV2).examples[0].name).toBe('Default');
+    expect((result as FragmentDefinitionV2).composition?.pattern).toBe('compound');
+  });
+
+  it('validates v2 field names correctly', () => {
+    const v2 = makeV2();
+    // Should not throw
+    expect(() => defineFragment(v2)).not.toThrow();
+  });
+
+  it('throws on invalid v2 definition', () => {
+    const invalid = {
+      component: StubComponent,
+      meta: { name: 'Test', description: 'test', category: 'test' },
+      guidance: { when: 'not-an-array', whenNot: [] }, // wrong type
+      props: {},
+      examples: [],
+    } as unknown as FragmentDefinitionV2;
+
+    expect(() => defineFragment(invalid)).toThrow('Invalid fragment definition');
+  });
+
+  it('accepts wrapper composition pattern', () => {
+    const v2 = makeV2();
+    v2.composition = { pattern: 'wrapper' };
+    expect(() => defineFragment(v2)).not.toThrow();
+  });
+
+  it('accepts scan provenance source', () => {
+    const v2 = makeV2();
+    v2._provenance = { source: 'scan', confidence: 0.9 };
+    expect(() => defineFragment(v2)).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeToV1
+// ---------------------------------------------------------------------------
+
+describe('normalizeToV1', () => {
+  it('maps guidance → usage', () => {
+    const v2 = makeV2();
+    const v1 = normalizeToV1(v2);
+    expect(v1.usage).toBe(v2.guidance);
+    expect(v1.usage.when).toEqual(['Testing v2']);
+  });
+
+  it('maps examples → variants', () => {
+    const v2 = makeV2();
+    const v1 = normalizeToV1(v2);
+    expect(v1.variants).toBe(v2.examples);
+    expect(v1.variants[0].name).toBe('Default');
+  });
+
+  it('maps composition → ai', () => {
+    const v2 = makeV2();
+    const v1 = normalizeToV1(v2);
+    expect(v1.ai).toEqual({
+      compositionPattern: 'compound',
+      subComponents: ['Header', 'Body'],
+      requiredChildren: ['Body'],
+      commonPatterns: ['<Stub><Stub.Header /><Stub.Body /></Stub>'],
+    });
+  });
+
+  it('maps _provenance → _generated (narrows scan → ai)', () => {
+    const v2 = makeV2();
+    const v1 = normalizeToV1(v2);
+    expect(v1._generated).toEqual({
+      source: 'ai', // scan → ai (v1 doesn't have scan)
+      sourceFile: undefined,
+      confidence: 0.85,
+      timestamp: undefined,
+    });
+  });
+
+  it('preserves storybook source as-is', () => {
+    const v2 = makeV2();
+    v2._provenance = { source: 'storybook', sourceFile: 'Button.stories.tsx' };
+    const v1 = normalizeToV1(v2);
+    expect(v1._generated!.source).toBe('storybook');
+    expect(v1._generated!.sourceFile).toBe('Button.stories.tsx');
+  });
+
+  it('handles undefined composition gracefully', () => {
+    const v2 = makeV2();
+    v2.composition = undefined;
+    const v1 = normalizeToV1(v2);
+    expect(v1.ai).toBeUndefined();
+  });
+
+  it('handles undefined _provenance gracefully', () => {
+    const v2 = makeV2();
+    v2._provenance = undefined;
+    const v1 = normalizeToV1(v2);
+    expect(v1._generated).toBeUndefined();
+  });
+
+  it('preserves contract and relations', () => {
+    const v2 = makeV2();
+    v2.relations = [{ component: 'Other', relationship: 'sibling', note: 'test' }];
+    const v1 = normalizeToV1(v2);
+    expect(v1.contract).toBe(v2.contract);
+    expect(v1.relations).toBe(v2.relations);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// compileFragment — v2 support
+// ---------------------------------------------------------------------------
+
+describe('compileFragment — v2 support', () => {
+  it('compiles v1 definition', () => {
+    const v1 = makeV1();
+    const compiled = compileFragment(v1, 'test/Stub.fragment.tsx');
+    expect(compiled.meta.name).toBe('Stub');
+    expect(compiled.usage.when).toEqual(['Testing v1']);
+    expect(compiled.variants[0].name).toBe('Default');
+    expect(compiled.ai?.compositionPattern).toBe('simple');
+  });
+
+  it('compiles v2 definition (normalizes to v1 output)', () => {
+    const v2 = makeV2();
+    const compiled = compileFragment(v2, 'test/Stub.fragment.tsx');
+    expect(compiled.meta.name).toBe('Stub');
+    expect(compiled.usage.when).toEqual(['Testing v2']);
+    expect(compiled.variants[0].name).toBe('Default');
+    expect(compiled.ai?.compositionPattern).toBe('compound');
+    expect(compiled.ai?.subComponents).toEqual(['Header', 'Body']);
+    expect(compiled._generated?.source).toBe('ai'); // scan normalized to ai
+  });
+
+  it('compiles v2 without optional fields', () => {
+    const v2 = makeV2();
+    v2.composition = undefined;
+    v2._provenance = undefined;
+    v2.contract = undefined;
+    const compiled = compileFragment(v2, 'test/Stub.fragment.tsx');
+    expect(compiled.ai).toBeUndefined();
+    expect(compiled._generated).toBeUndefined();
+    expect(compiled.contract).toBeUndefined();
+  });
+});