@usefragments/core 1.0.0

package/src/compiled-types/index.ts

@@ -0,0 +1,293 @@
+/**
+ * Compiled fragment types — shared between CLI and MCP packages.
+ *
+ * These are the JSON-serializable types used in fragments.json and consumed
+ * by AI agents, MCP servers, and context generators.
+ */
+
+import type { ComponentGovernanceRecord } from '../governance.js';
+
+/**
+ * Component metadata
+ */
+export interface FragmentMeta {
+  name: string;
+  description: string;
+  category: string;
+  tags?: string[];
+  status?: "stable" | "beta" | "deprecated" | "experimental";
+  since?: string;
+  dependencies?: Array<{ name: string; version: string; reason?: string }>;
+  figma?: string;
+  figmaProps?: Record<string, unknown>;
+}
+
+/**
+ * Usage guidelines for AI agents and developers
+ */
+export interface FragmentUsage {
+  when: string[];
+  whenNot: string[];
+  guidelines?: string[];
+  accessibility?: string[];
+}
+
+/**
+ * Definition for a single prop
+ */
+export interface PropDefinition {
+  type: string;
+  values?: readonly string[];
+  default?: unknown;
+  description: string;
+  required?: boolean;
+  constraints?: string[];
+  typeDetails?: Record<string, unknown>;
+  controlType?: string;
+  controlOptions?: {
+    min?: number;
+    max?: number;
+    step?: number;
+    presetColors?: string[];
+  };
+}
+
+/**
+ * Relationship to another component
+ */
+export interface ComponentRelation {
+  component: string;
+  relationship: string;
+  note: string;
+}
+
+/**
+ * Agent-optimized contract metadata
+ */
+export interface FragmentContract {
+  propsSummary?: string[];
+  a11yRules?: string[];
+  bans?: Array<{ pattern: string; message: string }>;
+  scenarioTags?: string[];
+  /** Per-component performance budget override in bytes (gzipped) */
+  performanceBudget?: number;
+  /** Sub-component slot metadata for compound components */
+  compoundChildren?: Record<string, {
+    required?: boolean;
+    accepts?: string[];
+    description?: string;
+  }>;
+  /** Canonical JSX usage examples showing how to assemble the component */
+  canonicalUsage?: string[];
+}
+
+/**
+ * Provenance tracking for generated fragments
+ */
+export interface FragmentGenerated {
+  source: "storybook" | "manual" | "ai" | "extracted" | "merged" | "migrated";
+  sourceFile?: string;
+  /** @deprecated Use provenance.verified instead */
+  confidence?: number;
+  verified?: boolean;
+  timestamp?: string;
+}
+
+/**
+ * AI-specific metadata
+ */
+export interface AIMetadata {
+  compositionPattern?: "compound" | "simple" | "controlled" | "wrapper";
+  subComponents?: string[];
+  requiredChildren?: string[];
+  commonPatterns?: string[];
+}
+
+/**
+ * Performance data for a component (from bundle size measurement)
+ */
+/**
+ * A single import contributing to bundle size
+ */
+export interface ImportEntry {
+  /** Resolved file path (relative to project root) */
+  path: string;
+  /** Bytes contributed to the bundle */
+  bytes: number;
+  /** Percentage of total bundle size */
+  percent: number;
+}
+
+export interface PerformanceData {
+  /** Gzipped bundle size in bytes */
+  bundleSize: number;
+  /** Raw (minified, not gzipped) bundle size in bytes */
+  rawSize: number;
+  /** Complexity classification */
+  complexity: 'lightweight' | 'moderate' | 'heavy';
+  /** Percentage of budget used (0-100+) */
+  budgetPercent: number;
+  /** Whether the component exceeds its budget */
+  overBudget: boolean;
+  /** ISO timestamp when measured */
+  measuredAt: string;
+  /** Top imports by size (largest first) */
+  imports?: ImportEntry[];
+}
+
+export interface ObservedUsageProp {
+  name: string;
+  kind: 'static' | 'dynamic' | 'spread' | 'jsx' | 'boolean' | 'null';
+  value?: string | number | boolean | null;
+}
+
+export interface ObservedComponentUsage {
+  /** Source file path relative to the fragments config root */
+  file: string;
+  /** 1-indexed source line */
+  line: number;
+  /** 0-indexed source column */
+  column: number;
+  props: ObservedUsageProp[];
+  parentElement?: string;
+  conditional?: boolean;
+}
+
+/**
+ * Compiled fragment data (JSON-serializable for AI consumption)
+ */
+export interface CompiledFragment {
+  filePath: string;
+  meta: FragmentMeta;
+  /** Canonical v2 guidance. `usage` is retained for compatibility. */
+  guidance?: FragmentUsage;
+  usage: FragmentUsage;
+  props: Record<string, PropDefinition>;
+  /** Normalized component governance records emitted from *.fragment.ts. */
+  governance?: ComponentGovernanceRecord[];
+  relations?: ComponentRelation[];
+  variants: Array<{
+    name: string;
+    description: string;
+    code?: string;
+    figma?: string;
+    args?: Record<string, unknown>;
+  }>;
+  contract?: FragmentContract;
+  ai?: AIMetadata;
+  /** Framework hint from contract, used by preview adapters and Cloud */
+  framework?: string;
+  /** Top-level compact prop summaries for agent first-pass */
+  propsSummary?: string[];
+  /** Source file path relative to config root (for contract-sourced fragments) */
+  sourcePath?: string;
+  /** Named export for preview adapter resolution */
+  exportName?: string;
+  /** Clean provenance tracking (V2) */
+  provenance?: {
+    source: string;
+    verified: boolean;
+    frameworkSupport?: string;
+    sourceHash?: string;
+    extractedAt?: string;
+  };
+  /** Component performance data from bundle size measurement */
+  performance?: PerformanceData;
+  /** Observed JSX call sites captured during `fragments scan` */
+  usages?: ObservedComponentUsage[];
+  _generated?: FragmentGenerated;
+}
+
+/**
+ * Compiled block data (JSON-serializable for AI consumption)
+ */
+export interface CompiledBlock {
+  filePath: string;
+  name: string;
+  description: string;
+  category: string;
+  components: string[];
+  code: string;
+  tags?: string[];
+}
+
+/**
+ * A single token entry in the compiled output
+ */
+export interface CompiledTokenEntry {
+  name: string;
+  value?: string;
+  description?: string;
+}
+
+/**
+ * Compiled token data stored in fragments.json
+ */
+export interface CompiledTokenData {
+  prefix: string;
+  total: number;
+  categories: Record<string, CompiledTokenEntry[]>;
+}
+
+/**
+ * Performance summary across all components
+ */
+export interface PerformanceSummary {
+  /** Preset name used */
+  preset: string;
+  /** Budget applied in bytes */
+  budget: number;
+  /** Total components measured */
+  total: number;
+  /** Number of components over budget */
+  overBudget: number;
+  /** Distribution by tier */
+  tiers: Record<string, number>;
+}
+
+/**
+ * The compiled fragments.json structure
+ */
+export interface CompiledFragmentsFile {
+  version: string;
+  generatedAt: string;
+  /** CLI version that produced this file, used for freshness checks */
+  generatorVersion?: string;
+  /** Relative source/config inputs used to build this file, used for freshness checks */
+  buildInputs?: string[];
+  packageName?: string;
+  fragments: Record<string, CompiledFragment>;
+  blocks?: Record<string, CompiledBlock>;
+  tokens?: CompiledTokenData;
+  /** Component relationship graph for AI structural queries */
+  graph?: import('../graph/types.js').SerializedComponentGraph;
+  /** Performance measurement summary */
+  performanceSummary?: PerformanceSummary;
+  /** @deprecated Use blocks instead */
+  recipes?: Record<string, CompiledBlock>;
+}
+
+/**
+ * Theme identifier
+ */
+export type Theme = "light" | "dark";
+
+/**
+ * Verification result
+ */
+export interface VerifyResult {
+  verdict: "pass" | "fail" | "error";
+  matches: boolean;
+  diffPercentage: number;
+  screenshot: string;
+  baseline: string;
+  diffImage?: string;
+  notes: string[];
+  error?: string;
+  timing: {
+    renderMs: number;
+    captureMs: number;
+    diffMs: number;
+    totalMs: number;
+  };
+}

package/src/component-contract.ts

@@ -0,0 +1,231 @@
+/**
+ * Framework-agnostic component contract format.
+ *
+ * Allows non-React teams to define component metadata via `.contract.json`
+ * files instead of `.fragment.tsx`. Maps trivially to CompiledFragment.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Component Contract interface
+// ---------------------------------------------------------------------------
+
+export interface ComponentContract {
+  /** JSON Schema reference for tooling — required for validation */
+  $schema: string;
+
+  /** Component name */
+  name: string;
+  description: string;
+  category: string;
+  tags?: string[];
+  status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
+
+  /** Framework hint (for extraction and documentation) */
+  framework?: 'react' | 'vue' | 'svelte' | 'web-components' | 'angular';
+
+  /** Path to the component source file, relative to fragments.config.ts root */
+  sourcePath: string;
+
+  /** Named export from the source file */
+  exportName: string;
+
+  /** Compact one-line-per-prop summaries for agent first-pass (e.g., "variant: primary|secondary (required)") */
+  propsSummary: string[];
+
+  /** Component props schema */
+  props: Record<string, {
+    type: string;
+    values?: string[];
+    default?: unknown;
+    description: string;
+    required?: boolean;
+    constraints?: string[];
+  }>;
+
+  /** Usage guidelines */
+  usage: {
+    when: string[];
+    whenNot: string[];
+    guidelines?: string[];
+    accessibility?: string[];
+  };
+
+  /** Code examples (as strings, not render functions) */
+  examples?: Array<{
+    name: string;
+    description: string;
+    code: string;
+    args?: Record<string, unknown>;
+  }>;
+
+  /** Relations to other components */
+  relations?: Array<{
+    component: string;
+    relationship: 'alternative' | 'parent' | 'child' | 'sibling' | 'composition' | 'complementary' | 'used-by';
+    note: string;
+  }>;
+
+  /** AI generation contract */
+  contract?: {
+    propsSummary?: string[];
+    scenarioTags?: string[];
+    a11yRules?: string[];
+    bans?: Array<{ pattern: string; message: string }>;
+    /** Sub-component slot metadata for compound components */
+    compoundChildren?: Record<string, {
+      required?: boolean;
+      accepts?: string[];
+      description?: string;
+    }>;
+    /** Canonical JSX usage examples */
+    canonicalUsage?: string[];
+    /** Per-component performance budget override in bytes (gzipped) */
+    performanceBudget?: number;
+  };
+
+  /** AI metadata for compound component generation */
+  ai?: {
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    subComponents?: string[];
+    requiredChildren?: string[];
+    commonPatterns?: string[];
+  };
+
+  /** Per-component preview configuration */
+  preview?: {
+    setupModule?: string;
+    wrapperModule?: string;
+    wrapperExport?: string;
+    css?: string[];
+    theme?: 'light' | 'dark';
+  };
+
+  /** Provenance tracking — required for verification */
+  provenance: {
+    source: 'manual' | 'extracted' | 'merged' | 'migrated';
+    verified: boolean;
+    frameworkSupport?: 'native' | 'manual-only';
+    sourceHash?: string;
+    extractedAt?: string;
+  };
+
+  /** Design token references used by this component */
+  tokens?: string[];
+
+  /** Figma mappings (same DSL as .fragment.tsx but in JSON form) */
+  figma?: {
+    nodeUrl?: string;
+    propMappings?: Record<string, {
+      type: 'string' | 'boolean' | 'enum' | 'instance' | 'children' | 'textContent';
+      figmaProperty: string;
+      values?: Record<string, string>;
+    }>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema for validation
+// ---------------------------------------------------------------------------
+
+const contractPropSchema = z.object({
+  type: z.string(),
+  values: z.array(z.string()).optional(),
+  default: z.unknown().optional(),
+  description: z.string(),
+  required: z.boolean().optional(),
+  constraints: z.array(z.string()).optional(),
+});
+
+const contractUsageSchema = z.object({
+  when: z.array(z.string()),
+  whenNot: z.array(z.string()),
+  guidelines: z.array(z.string()).optional(),
+  accessibility: z.array(z.string()).optional(),
+});
+
+const contractExampleSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  code: z.string(),
+  args: z.record(z.string(), z.unknown()).optional(),
+});
+
+const contractRelationSchema = z.object({
+  component: z.string(),
+  relationship: z.enum(['alternative', 'parent', 'child', 'sibling', 'composition', 'complementary', 'used-by']),
+  note: z.string(),
+});
+
+const contractContractSchema = z.object({
+  propsSummary: z.array(z.string()).optional(),
+  scenarioTags: z.array(z.string()).optional(),
+  a11yRules: z.array(z.string()).optional(),
+  bans: z.array(z.object({
+    pattern: z.string(),
+    message: z.string(),
+  })).optional(),
+  compoundChildren: z.record(z.string(), z.object({
+    required: z.boolean().optional(),
+    accepts: z.array(z.string()).optional(),
+    description: z.string().optional(),
+  })).optional(),
+  canonicalUsage: z.array(z.string()).optional(),
+  performanceBudget: z.number().optional(),
+});
+
+const contractAiSchema = z.object({
+  compositionPattern: z.enum(['compound', 'simple', 'controlled', 'wrapper']).optional(),
+  subComponents: z.array(z.string()).optional(),
+  requiredChildren: z.array(z.string()).optional(),
+  commonPatterns: z.array(z.string()).optional(),
+});
+
+const contractPreviewSchema = z.object({
+  setupModule: z.string().optional(),
+  wrapperModule: z.string().optional(),
+  wrapperExport: z.string().optional(),
+  css: z.array(z.string()).optional(),
+  theme: z.enum(['light', 'dark']).optional(),
+});
+
+const contractProvenanceSchema = z.object({
+  source: z.enum(['manual', 'extracted', 'merged', 'migrated']),
+  verified: z.boolean(),
+  frameworkSupport: z.enum(['native', 'manual-only']).optional(),
+  sourceHash: z.string().optional(),
+  extractedAt: z.string().optional(),
+});
+
+const contractFigmaSchema = z.object({
+  nodeUrl: z.string().optional(),
+  propMappings: z.record(z.string(), z.object({
+    type: z.enum(['string', 'boolean', 'enum', 'instance', 'children', 'textContent']),
+    figmaProperty: z.string(),
+    values: z.record(z.string(), z.string()).optional(),
+  })).optional(),
+});
+
+export const componentContractSchema = z.object({
+  $schema: z.string(),
+  name: z.string(),
+  description: z.string(),
+  category: z.string(),
+  tags: z.array(z.string()).optional(),
+  status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
+  framework: z.enum(['react', 'vue', 'svelte', 'web-components', 'angular']).optional(),
+  sourcePath: z.string(),
+  exportName: z.string(),
+  propsSummary: z.array(z.string()),
+  props: z.record(z.string(), contractPropSchema),
+  usage: contractUsageSchema,
+  examples: z.array(contractExampleSchema).optional(),
+  relations: z.array(contractRelationSchema).optional(),
+  contract: contractContractSchema.optional(),
+  ai: contractAiSchema.optional(),
+  preview: contractPreviewSchema.optional(),
+  provenance: contractProvenanceSchema,
+  tokens: z.array(z.string()).optional(),
+  figma: contractFigmaSchema.optional(),
+});

package/src/component-discovery.ts

@@ -0,0 +1,80 @@
+/**
+ * Component discovery utilities.
+ *
+ * Extracted from the docs app component-registry so that any consumer
+ * (govern presets, CLI tools, third-party integrations) can discover
+ * components from a module's exports without duplicating the logic.
+ */
+
+/**
+ * Check if a value is likely a React component.
+ * Functions or objects with $$typeof (forwardRef, memo) qualify.
+ */
+export function isReactComponent(value: unknown): boolean {
+  if (!value) return false;
+
+  // Function component (most common case)
+  if (typeof value === 'function') {
+    return true;
+  }
+
+  // ForwardRef, memo, etc. have $$typeof
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    if (obj.$$typeof) return true;
+  }
+
+  return false;
+}
+
+export interface DiscoverComponentsOptions {
+  /** Set of export names to skip */
+  exclude?: Set<string>;
+}
+
+/**
+ * Discover all components and sub-components from a module's exports.
+ * Returns a sorted array of component names including compound names (e.g. 'Card.Header').
+ *
+ * @param moduleExports - The exports object from a component library (e.g. `import * as UI from '@usefragments/ui'`)
+ * @param options - Optional configuration
+ */
+export function discoverComponents(
+  moduleExports: Record<string, unknown>,
+  options?: DiscoverComponentsOptions,
+): string[] {
+  const exclude = options?.exclude;
+  const names: string[] = [];
+
+  for (const [exportName, exportValue] of Object.entries(moduleExports)) {
+    // Skip excluded exports
+    if (exclude?.has(exportName)) continue;
+
+    // Skip non-components (types, constants, etc.)
+    if (!isReactComponent(exportValue)) continue;
+
+    // Skip lowercase exports (likely utilities)
+    if (exportName[0] !== exportName[0].toUpperCase()) continue;
+
+    // Add the main component
+    names.push(exportName);
+
+    // Check for sub-components by looking at ALL properties of the component
+    const componentObj = exportValue as Record<string, unknown>;
+
+    for (const key of Object.keys(componentObj)) {
+      // Skip internal properties and non-component properties
+      if (key.startsWith('_') || key.startsWith('$')) continue;
+      if (key === 'displayName' || key === 'propTypes' || key === 'defaultProps') continue;
+      // Skip 'render' which is a forwardRef internal, and 'Tabbed' which is a special variant
+      if (key === 'render' || key === 'Tabbed') continue;
+
+      const subComponent = componentObj[key];
+      if (isReactComponent(subComponent)) {
+        names.push(`${exportName}.${key}`);
+      }
+    }
+  }
+
+  return names.sort();
+}