@usefragments/core 1.10.2 → 2.0.0

package/src/contract/preimage.ts

@@ -24,9 +24,35 @@
  *
  * Runtime-portable by construction: no Node APIs, no Convex imports, no React.
  */
-import type { GovernanceConfig } from "../governance.js";
+import type { ComponentGovernanceRecord, GovernanceConfig } from "../governance.js";
+import { resolveGovernanceRecordsForIdentity } from "../governance.js";
 import { projectV1OwnedComponentId, projectV1OwnedImportIdentity } from "../package-identity.js";
-import { canonicalPreimage, contractHash } from "./hash.js";
+import { artifactContentHash, canonicalPreimage, contractHash } from "./hash.js";
+
+/**
+ * Positive pick-list of per-component `contract` fields that enter the FCID.
+ * Display/guidance fields (`propsSummary`, `canonicalUsage`, `scenarioTags`,
+ * story `states`/`variants`, descriptions) are intentionally absent — adapters
+ * may still pass them, but {@link projectEnforcementContract} never copies them.
+ */
+export const CONTRACT_ENFORCEMENT_FIELDS = [
+  "a11yRules",
+  "bans",
+  "performanceBudget",
+  "compoundChildren",
+  "composition",
+] as const;
+
+export type ContractEnforcementField = (typeof CONTRACT_ENFORCEMENT_FIELDS)[number];
+
+/** Display-only contract keys that must never enter the FCID positive pick-list. */
+export const CONTRACT_DISPLAY_ONLY_FIELDS = [
+  "propsSummary",
+  "canonicalUsage",
+  "scenarioTags",
+  "states",
+  "variants",
+] as const;
 
 // ---------------------------------------------------------------------------
 // Domains
@@ -56,11 +82,15 @@ export interface ContractComponentInput {
   /** Prop names the component accepts. */
   props?: readonly string[];
   /**
-   * The per-component enforcement contract as authored (bans, a11y rules,
-   * required compound children). Passed through whole — it is enforcement data
-   * by definition.
+   * The per-component contract as authored. Only {@link CONTRACT_ENFORCEMENT_FIELDS}
+   * are projected into the FCID — display/guidance keys are stripped structurally.
    */
   contract?: unknown;
+  /**
+   * Resolved component governance records (`govern:` / `governance`). Editing
+   * these changes what CI allows, so they are FCID identity.
+   */
+  governance?: readonly ComponentGovernanceRecord[];
   /** Required compound-children names, when the structure is declared. */
   compoundChildren?: readonly string[];
 }
@@ -143,6 +173,18 @@ export interface ContractCatalogInput {
   policy?: ContractPolicyInput | null;
 }
 
+/** Deterministic runtime refusal for malformed or ambiguous FCID inputs. */
+export class ContractCatalogValidationError extends TypeError {
+  readonly issues: readonly string[];
+
+  constructor(issues: readonly string[]) {
+    const sortedIssues = [...issues].sort();
+    super(["Invalid contract catalog:", ...sortedIssues.map((issue) => `  - ${issue}`)].join("\n"));
+    this.name = "ContractCatalogValidationError";
+    this.issues = sortedIssues;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Preimage
 // ---------------------------------------------------------------------------
@@ -226,13 +268,259 @@ function sortCanonical<T>(items: readonly T[]): T[] {
     .map(({ item }) => item);
 }
 
+function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function requireNonEmptyString(value: unknown, path: string, issues: string[]): void {
+  if (typeof value !== "string" || value.length === 0) {
+    issues.push(`${path}: expected a non-empty string`);
+  }
+}
+
+function validateStringArray(value: unknown, path: string, issues: string[]): void {
+  if (!Array.isArray(value)) {
+    issues.push(`${path}: expected an array`);
+    return;
+  }
+  const seen = new Set<string>();
+  for (const [index, entry] of value.entries()) {
+    requireNonEmptyString(entry, `${path}[${index}]`, issues);
+    if (typeof entry === "string" && entry.length > 0) {
+      if (seen.has(entry)) issues.push(`${path}: duplicate value "${entry}"`);
+      seen.add(entry);
+    }
+  }
+}
+
+function validateContractCatalog(catalog: unknown): asserts catalog is ContractCatalogInput {
+  const issues: string[] = [];
+  if (!isPlainRecord(catalog)) {
+    throw new ContractCatalogValidationError(["(root): expected a plain object"]);
+  }
+
+  const componentIdentities = new Set<string>();
+  if (catalog.components !== undefined) {
+    if (!Array.isArray(catalog.components)) {
+      issues.push("components: expected an array");
+    } else {
+      for (const [index, value] of catalog.components.entries()) {
+        const path = `components[${index}]`;
+        if (!isPlainRecord(value)) {
+          issues.push(`${path}: expected a plain object`);
+          continue;
+        }
+        requireNonEmptyString(value.name, `${path}.name`, issues);
+        if (value.parentName !== undefined) {
+          requireNonEmptyString(value.parentName, `${path}.parentName`, issues);
+        }
+        if (typeof value.name === "string" && value.name.length > 0) {
+          const identity = `${typeof value.parentName === "string" ? value.parentName : ""}#${value.name}`;
+          if (componentIdentities.has(identity)) {
+            issues.push(`components: duplicate identity "${identity}"`);
+          }
+          componentIdentities.add(identity);
+        }
+        if (value.props !== undefined) validateStringArray(value.props, `${path}.props`, issues);
+        if (value.compoundChildren !== undefined) {
+          validateStringArray(value.compoundChildren, `${path}.compoundChildren`, issues);
+        }
+        if (value.contract !== undefined && !isPlainRecord(value.contract)) {
+          issues.push(`${path}.contract: expected a plain object`);
+        }
+        if (value.governance !== undefined && !Array.isArray(value.governance)) {
+          issues.push(`${path}.governance: expected an array`);
+        }
+      }
+    }
+  }
+
+  const tokenNames = new Set<string>();
+  if (catalog.tokens !== undefined) {
+    if (!Array.isArray(catalog.tokens)) {
+      issues.push("tokens: expected an array");
+    } else {
+      for (const [index, value] of catalog.tokens.entries()) {
+        const path = `tokens[${index}]`;
+        if (!isPlainRecord(value)) {
+          issues.push(`${path}: expected a plain object`);
+          continue;
+        }
+        requireNonEmptyString(value.name, `${path}.name`, issues);
+        if (typeof value.name === "string" && value.name.length > 0) {
+          if (tokenNames.has(value.name)) issues.push(`tokens: duplicate identity "${value.name}"`);
+          tokenNames.add(value.name);
+        }
+        if (
+          (typeof value.value !== "string" && typeof value.value !== "number") ||
+          (typeof value.value === "number" && !Number.isFinite(value.value))
+        ) {
+          issues.push(`${path}.value: expected a finite number or string`);
+        }
+        if (value.type !== undefined) requireNonEmptyString(value.type, `${path}.type`, issues);
+      }
+    }
+  }
+
+  const confirmedMappings = new Set<string>();
+  if (catalog.canonicalMappings !== undefined) {
+    if (!Array.isArray(catalog.canonicalMappings)) {
+      issues.push("canonicalMappings: expected an array");
+    } else {
+      for (const [index, value] of catalog.canonicalMappings.entries()) {
+        const path = `canonicalMappings[${index}]`;
+        if (!isPlainRecord(value)) {
+          issues.push(`${path}: expected a plain object`);
+          continue;
+        }
+        requireNonEmptyString(value.component, `${path}.component`, issues);
+        requireNonEmptyString(value.canonical, `${path}.canonical`, issues);
+        if (!(["confirmed", "proposed", "unknown"] as const).includes(value.status as never)) {
+          issues.push(`${path}.status: expected confirmed, proposed, or unknown`);
+        }
+        if (value.status === "confirmed" && typeof value.component === "string") {
+          if (confirmedMappings.has(value.component)) {
+            issues.push(`canonicalMappings: duplicate confirmed identity "${value.component}"`);
+          }
+          confirmedMappings.add(value.component);
+        }
+        if (value.importPath !== undefined) {
+          requireNonEmptyString(value.importPath, `${path}.importPath`, issues);
+        }
+        if (value.propMapping !== undefined && !Array.isArray(value.propMapping)) {
+          issues.push(`${path}.propMapping: expected an array`);
+        }
+        if (value.resolves !== undefined && !Array.isArray(value.resolves)) {
+          issues.push(`${path}.resolves: expected an array`);
+        }
+        if (value.bridge !== undefined && !isPlainRecord(value.bridge)) {
+          issues.push(`${path}.bridge: expected a plain object`);
+        }
+      }
+    }
+  }
+
+  if (catalog.policy !== undefined && catalog.policy !== null) {
+    if (!isPlainRecord(catalog.policy)) {
+      issues.push("policy: expected a plain object or null");
+    } else {
+      if (catalog.policy.rules !== undefined && !isPlainRecord(catalog.policy.rules)) {
+        issues.push("policy.rules: expected a plain object");
+      }
+      if (catalog.policy.codes !== undefined && !isPlainRecord(catalog.policy.codes)) {
+        issues.push("policy.codes: expected a plain object");
+      }
+      if (
+        catalog.policy.compositionPatterns !== undefined &&
+        !Array.isArray(catalog.policy.compositionPatterns)
+      ) {
+        issues.push("policy.compositionPatterns: expected an array");
+      }
+      if (catalog.policy.waivers !== undefined) {
+        if (!Array.isArray(catalog.policy.waivers)) {
+          issues.push("policy.waivers: expected an array");
+        } else {
+          const waiverIds = new Set<string>();
+          for (const [index, value] of catalog.policy.waivers.entries()) {
+            const path = `policy.waivers[${index}]`;
+            if (!isPlainRecord(value)) {
+              issues.push(`${path}: expected a plain object`);
+              continue;
+            }
+            requireNonEmptyString(value.id, `${path}.id`, issues);
+            requireNonEmptyString(value.target, `${path}.target`, issues);
+            requireNonEmptyString(value.reason, `${path}.reason`, issues);
+            if (value.expiresOn !== undefined) {
+              requireNonEmptyString(value.expiresOn, `${path}.expiresOn`, issues);
+            }
+            if (typeof value.id === "string" && value.id.length > 0) {
+              if (waiverIds.has(value.id)) {
+                issues.push(`policy.waivers: duplicate identity "${value.id}"`);
+              }
+              waiverIds.add(value.id);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (issues.length > 0) throw new ContractCatalogValidationError(issues);
+}
+
+/**
+ * Project only enforcement fields from a per-component `contract` blob.
+ * Unknown / display keys are dropped; an all-display contract becomes `undefined`.
+ */
+export function projectEnforcementContract(contract: unknown): unknown {
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
+    return undefined;
+  }
+  const source = contract as Readonly<Record<string, unknown>>;
+  const projected: Record<string, unknown> = {};
+
+  if (Array.isArray(source.a11yRules)) {
+    projected.a11yRules = sortCanonical([...source.a11yRules]);
+  }
+  if (Array.isArray(source.bans)) {
+    projected.bans = sortCanonical([...source.bans]);
+  }
+  if (typeof source.performanceBudget === "number") {
+    projected.performanceBudget = source.performanceBudget;
+  }
+  if (Array.isArray(source.composition)) {
+    projected.composition = sortCanonical([...source.composition]);
+  }
+  const compoundChildren = projectContractCompoundChildren(source.compoundChildren);
+  if (compoundChildren !== undefined) {
+    projected.compoundChildren = compoundChildren;
+  }
+
+  return Object.keys(projected).length > 0 ? projected : undefined;
+}
+
+/**
+ * Compound-children structure is enforcement (required / accepts); prose
+ * descriptions are display-only and never enter the FCID.
+ */
+function projectContractCompoundChildren(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value as Readonly<Record<string, unknown>>)
+    .map(([name, raw]) => {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return [name, {}] as const;
+      }
+      const child = raw as Readonly<Record<string, unknown>>;
+      const projected: Record<string, unknown> = {};
+      if (typeof child.required === "boolean") projected.required = child.required;
+      if (Array.isArray(child.accepts)) {
+        projected.accepts = [...child.accepts]
+          .filter((entry): entry is string => typeof entry === "string")
+          .sort();
+      }
+      return [name, projected] as const;
+    })
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return Object.fromEntries(entries);
+}
+
+function projectGovernanceRecords(
+  records: readonly ComponentGovernanceRecord[] | undefined
+): unknown {
+  if (!records || records.length === 0) return undefined;
+  return sortCanonical([...records]);
+}
+
 function projectComponents(components: readonly ContractComponentInput[] | undefined): unknown {
   return sortCanonical(
     (components ?? []).map((component) => ({
       name: component.name,
       parentName: component.parentName,
       props: component.props ? [...component.props].sort() : undefined,
-      contract: component.contract,
+      contract: projectEnforcementContract(component.contract),
+      governance: projectGovernanceRecords(component.governance),
       compoundChildren: component.compoundChildren
         ? [...component.compoundChildren].sort()
         : undefined,
@@ -351,6 +639,7 @@ function projectPolicy(policy: ContractPolicyInput | null | undefined): unknown
  * is the fcid.
  */
 export function projectContractPreimage(catalog: ContractCatalogInput): ContractPreimage {
+  validateContractCatalog(catalog);
   return {
     schema: CONTRACT_PREIMAGE_SCHEMA,
     domains: {
@@ -418,6 +707,8 @@ export function contractComponentsFromFragments(
       meta?: { name?: unknown; parentComponentName?: unknown };
       props?: Record<string, unknown>;
       contract?: unknown;
+      governance?: unknown;
+      govern?: unknown;
       structure?: { compoundChildren?: unknown };
     } | null;
     const name = fragment?.meta?.name;
@@ -429,13 +720,42 @@ export function contractComponentsFromFragments(
           .map((child) => (child as { name?: unknown } | null)?.name)
           .filter((childName): childName is string => typeof childName === "string")
       : undefined;
+    const governance = resolveGovernanceRecordsForIdentity({
+      governance: Array.isArray(fragment?.governance)
+        ? (fragment.governance as ComponentGovernanceRecord[])
+        : undefined,
+      govern: typeof fragment?.govern === "function" ? (fragment.govern as never) : undefined,
+    });
     components.push({
       name,
       parentName: typeof parentName === "string" ? parentName : undefined,
       props: Object.keys(fragment?.props ?? {}),
       contract: fragment?.contract,
+      governance,
       compoundChildren,
     });
   }
   return components;
 }
+
+/**
+ * Derive a preview `artifactId` from modules, states, guidance/render content,
+ * and runtime config. Never an FCID — callers must not assign
+ * `derivedFromContractHash` into `artifactId` (or the reverse).
+ */
+export function deriveArtifactId(content: {
+  modules?: unknown;
+  states?: unknown;
+  guidance?: unknown;
+  render?: unknown;
+  runtime?: unknown;
+}): string {
+  return artifactContentHash({
+    schema: "artifact-content:v1",
+    modules: content.modules,
+    states: content.states,
+    guidance: content.guidance,
+    render: content.render,
+    runtime: content.runtime,
+  });
+}

package/src/contract/stamp.test.ts

@@ -75,6 +75,9 @@ Prefer canonical components over raw HTML elements.
     // 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();
+    expect(
+      parseContractStamp(`contract: fragments contract v0 · a3f9e21\ncontract-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`)

package/src/contract/stamp.ts

@@ -87,7 +87,7 @@ export function parseContractStamp(text: string): ContractStampRecord | null {
   const fcidLine = STAMP_FCID_LINE.exec(text);
   if (!header || !fcidLine) return null;
   const contractVersion = Number(header[1]);
-  if (!Number.isSafeInteger(contractVersion)) return null;
+  if (!Number.isSafeInteger(contractVersion) || contractVersion < 1) return null;
   const fcid = fcidLine[1];
   if (!fcid.startsWith(header[2])) return null;
 

package/src/contract-parser.ts

@@ -6,8 +6,8 @@
  * (MCP tools, governance, search) work unchanged.
  */
 
-import { componentContractSchema } from './component-contract.js';
-import type { ComponentContract } from './component-contract.js';
+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
@@ -20,7 +20,7 @@ export interface CompiledContractOutput {
     description: string;
     category: string;
     tags?: string[];
-    status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
+    status?: "stable" | "beta" | "deprecated" | "experimental";
     dependencies?: Array<{ name: string; version: string; reason?: string }>;
     figma?: string;
     figmaProps?: Record<string, unknown>;
@@ -31,17 +31,27 @@ export interface CompiledContractOutput {
     guidelines?: string[];
     accessibility?: string[];
   };
-  props: Record<string, {
-    type: string;
-    description: string;
-    default?: unknown;
-    required?: boolean;
-    values?: string[];
-    constraints?: 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';
+    relationship:
+      | "alternative"
+      | "parent"
+      | "child"
+      | "sibling"
+      | "composition"
+      | "complementary"
+      | "used-by";
     note: string;
   }>;
   variants: Array<{
@@ -55,19 +65,32 @@ export interface CompiledContractOutput {
     scenarioTags?: string[];
     a11yRules?: string[];
     bans?: Array<{ pattern: string; message: string }>;
-    compoundChildren?: Record<string, {
-      required?: boolean;
-      accepts?: string[];
-      description?: string;
-    }>;
+    compoundChildren?: Record<
+      string,
+      {
+        required?: boolean;
+        accepts?: string[];
+        description?: string;
+      }
+    >;
     canonicalUsage?: string[];
     performanceBudget?: number;
   };
+  /** Per-component preview configuration */
+  preview?: {
+    setupModule?: string;
+    wrapperModule?: string;
+    wrapperExport?: string;
+    css?: string[];
+    theme?: "light" | "dark";
+  };
+  /** Design-token references used by this component */
+  tokens?: string[];
   /** Framework hint from contract, used by extractor adapter selection */
   framework?: string;
   /** AI metadata for compound component generation */
   ai?: {
-    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    compositionPattern?: "compound" | "simple" | "controlled" | "wrapper";
     subComponents?: string[];
     requiredChildren?: string[];
     commonPatterns?: string[];
@@ -92,16 +115,13 @@ export interface CompiledContractOutput {
  * Check if a file path is a component contract file.
  */
 export function isContractFile(filePath: string): boolean {
-  return filePath.endsWith('.contract.json');
+  return filePath.endsWith(".contract.json");
 }
 
 /**
  * Parse a component contract JSON file into CompiledFragment-compatible output.
  */
-export function parseComponentContract(
-  content: string,
-  filePath: string,
-): CompiledContractOutput {
+export function parseComponentContract(content: string, filePath: string): CompiledContractOutput {
   const raw = JSON.parse(content);
   const validated: ComponentContract = componentContractSchema.parse(raw);
 
@@ -126,13 +146,17 @@ export function parseComponentContract(
       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,
-    },
+    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,
+        },
+    preview: validated.preview,
+    tokens: validated.tokens,
     framework: validated.framework,
     ai: validated.ai,
     propsSummary: validated.propsSummary,