@fragments-sdk/cli 0.2.2

package/src/core/schema/fragment.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fragments.dev/schema/v1.json",
+  "title": "Fragment",
+  "description": "Component enrichment metadata for AI agents and developers",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "description": "Component name (must match the component export name)"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of the component's purpose"
+    },
+    "figma": {
+      "type": "object",
+      "description": "Figma design links and mappings",
+      "properties": {
+        "file": {
+          "type": "string",
+          "format": "uri",
+          "description": "Figma file URL"
+        },
+        "nodeId": {
+          "type": "string",
+          "description": "Default Figma node ID for this component"
+        },
+        "variants": {
+          "type": "object",
+          "description": "Mapping of variant names to Figma node IDs",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "usage": {
+      "type": "object",
+      "description": "Usage guidelines for AI agents and developers",
+      "properties": {
+        "when": {
+          "type": "array",
+          "description": "Scenarios when this component should be used",
+          "items": {
+            "type": "string"
+          }
+        },
+        "doNot": {
+          "type": "array",
+          "description": "Anti-patterns and what to use instead",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "text": {
+                    "type": "string",
+                    "description": "What not to do"
+                  },
+                  "instead": {
+                    "type": "string",
+                    "description": "Component name to use instead"
+                  }
+                },
+                "required": ["text"]
+              }
+            ]
+          }
+        },
+        "patterns": {
+          "type": "array",
+          "description": "Common usage patterns with code examples",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Pattern name"
+              },
+              "code": {
+                "type": "string",
+                "description": "Code example"
+              },
+              "description": {
+                "type": "string",
+                "description": "When to use this pattern"
+              }
+            },
+            "required": ["name", "code"]
+          }
+        }
+      }
+    },
+    "accessibility": {
+      "type": "object",
+      "description": "Accessibility requirements and guidelines",
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "ARIA role this component implements"
+        },
+        "requirements": {
+          "type": "array",
+          "description": "Accessibility requirements",
+          "items": {
+            "type": "string"
+          }
+        },
+        "keyboard": {
+          "type": "object",
+          "description": "Keyboard interaction patterns",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "related": {
+      "type": "object",
+      "description": "Relationships to other components",
+      "properties": {
+        "similar": {
+          "type": "array",
+          "description": "Similar components that might be alternatives",
+          "items": {
+            "type": "string"
+          }
+        },
+        "composedWith": {
+          "type": "array",
+          "description": "Components commonly used together with this one",
+          "items": {
+            "type": "string"
+          }
+        },
+        "usedIn": {
+          "type": "array",
+          "description": "Parent components or patterns where this is commonly used",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "description": "Administrative metadata",
+      "properties": {
+        "owner": {
+          "type": "string",
+          "description": "Team or person responsible for this component"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["draft", "experimental", "beta", "stable", "deprecated"],
+          "description": "Component lifecycle status"
+        },
+        "since": {
+          "type": "string",
+          "description": "Version when this component was introduced"
+        },
+        "deprecatedSince": {
+          "type": "string",
+          "description": "Version when this component was deprecated"
+        },
+        "deprecatedReason": {
+          "type": "string",
+          "description": "Why this component was deprecated and what to use instead"
+        },
+        "tags": {
+          "type": "array",
+          "description": "Tags for categorization and search",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "required": ["name"]
+}

package/src/core/schema/registry.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fragments.dev/schema/registry-v1.json",
+  "title": "Fragment Registry",
+  "description": "Auto-generated component index with resolved paths and extracted metadata",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "description": "Schema version"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this registry was generated"
+    },
+    "projectRoot": {
+      "type": "string",
+      "description": "Absolute path to the project root"
+    },
+    "components": {
+      "type": "object",
+      "description": "Component index keyed by component name",
+      "additionalProperties": {
+        "$ref": "#/$defs/ComponentEntry"
+      }
+    },
+    "categories": {
+      "type": "object",
+      "description": "Components grouped by category",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": ["version", "generatedAt", "components"],
+  "$defs": {
+    "ComponentEntry": {
+      "type": "object",
+      "description": "Component registry entry with resolved paths and metadata",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Relative path to the component source file"
+        },
+        "fragmentPath": {
+          "type": "string",
+          "description": "Relative path to the .fragment.json file"
+        },
+        "storyPath": {
+          "type": "string",
+          "description": "Relative path to the .stories.tsx file (if exists)"
+        },
+        "category": {
+          "type": "string",
+          "description": "Component category"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["draft", "experimental", "beta", "stable", "deprecated"],
+          "description": "Component lifecycle status"
+        },
+        "description": {
+          "type": "string",
+          "description": "Component description"
+        },
+        "props": {
+          "type": "object",
+          "description": "Extracted prop definitions",
+          "additionalProperties": {
+            "$ref": "#/$defs/PropEntry"
+          }
+        },
+        "exports": {
+          "type": "array",
+          "description": "Named exports from the component file",
+          "items": {
+            "type": "string"
+          }
+        },
+        "dependencies": {
+          "type": "array",
+          "description": "Component dependencies (other components used)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "fragment": {
+          "type": "object",
+          "description": "Merged fragment enrichment data",
+          "additionalProperties": true
+        }
+      },
+      "required": ["path"]
+    },
+    "PropEntry": {
+      "type": "object",
+      "description": "Extracted prop definition",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "TypeScript type (e.g., 'string', 'boolean', enum values)"
+        },
+        "typeKind": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "enum", "object", "array", "function", "node", "element", "union", "unknown"],
+          "description": "Simplified type category"
+        },
+        "options": {
+          "type": "array",
+          "description": "For enum types, the allowed values",
+          "items": {
+            "type": "string"
+          }
+        },
+        "default": {
+          "description": "Default value if specified"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this prop is required"
+        },
+        "description": {
+          "type": "string",
+          "description": "Prop description from JSDoc or TypeScript"
+        }
+      }
+    }
+  }
+}

package/src/core/schema.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for runtime validation of segment definitions
+ */
+
+// Figma property mapping schemas
+const figmaStringMappingSchema = z.object({
+  __type: z.literal('figma-string'),
+  figmaProperty: z.string().min(1),
+});
+
+const figmaBooleanMappingSchema = z.object({
+  __type: z.literal('figma-boolean'),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.object({ true: z.unknown(), false: z.unknown() }).optional(),
+});
+
+const figmaEnumMappingSchema = z.object({
+  __type: z.literal('figma-enum'),
+  figmaProperty: z.string().min(1),
+  valueMapping: z.record(z.unknown()),
+});
+
+const figmaInstanceMappingSchema = z.object({
+  __type: z.literal('figma-instance'),
+  figmaProperty: z.string().min(1),
+});
+
+const figmaChildrenMappingSchema = z.object({
+  __type: z.literal('figma-children'),
+  layers: z.array(z.string().min(1)),
+});
+
+const figmaTextContentMappingSchema = z.object({
+  __type: z.literal('figma-text-content'),
+  layer: z.string().min(1),
+});
+
+export const figmaPropMappingSchema = z.discriminatedUnion('__type', [
+  figmaStringMappingSchema,
+  figmaBooleanMappingSchema,
+  figmaEnumMappingSchema,
+  figmaInstanceMappingSchema,
+  figmaChildrenMappingSchema,
+  figmaTextContentMappingSchema,
+]);
+
+export const segmentMetaSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+  status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
+  since: z.string().optional(),
+  figma: z.string().url().optional(),
+  figmaProps: z.record(figmaPropMappingSchema).optional(),
+});
+
+export const segmentUsageSchema = z.object({
+  when: z.array(z.string()).min(1),
+  whenNot: z.array(z.string()).min(1),
+  guidelines: z.array(z.string()).optional(),
+  accessibility: z.array(z.string()).optional(),
+});
+
+export const propTypeSchema: z.ZodType<string> = z.enum([
+  'string',
+  'number',
+  'boolean',
+  'enum',
+  'function',
+  'node',
+  'element',
+  'object',
+  'array',
+  'union',
+  'custom',
+]);
+
+export const propDefinitionSchema = z.object({
+  type: propTypeSchema,
+  values: z.array(z.string()).readonly().optional(),
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  constraints: z.array(z.string()).optional(),
+  typeDetails: z.record(z.unknown()).optional(),
+});
+
+export const relationshipTypeSchema = z.enum([
+  'alternative',
+  'sibling',
+  'parent',
+  'child',
+  'composition',
+]);
+
+export const componentRelationSchema = z.object({
+  component: z.string().min(1),
+  relationship: relationshipTypeSchema,
+  note: z.string().min(1),
+});
+
+export const segmentVariantSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  render: z.function().returns(z.unknown()),
+  code: z.string().optional(),
+  figma: z.string().url().optional(),
+});
+
+/**
+ * Schema for banned patterns in codebase
+ */
+export const segmentBanSchema = z.object({
+  pattern: z.string().min(1),
+  message: z.string().min(1),
+});
+
+/**
+ * Schema for agent-optimized contract metadata
+ */
+export const segmentContractSchema = z.object({
+  propsSummary: z.array(z.string()).optional(),
+  a11yRules: z.array(z.string()).optional(),
+  bans: z.array(segmentBanSchema).optional(),
+  scenarioTags: z.array(z.string()).optional(),
+});
+
+/**
+ * Schema for provenance tracking of generated segments
+ */
+export const segmentGeneratedSchema = z.object({
+  source: z.enum(['storybook', 'manual', 'ai']),
+  sourceFile: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  timestamp: z.string().datetime().optional(),
+});
+
+/**
+ * Schema for recipe definitions
+ */
+export const recipeDefinitionSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  category: z.string().min(1),
+  components: z.array(z.string().min(1)).min(1),
+  code: z.string().min(1),
+  tags: z.array(z.string()).optional(),
+});
+
+export const segmentDefinitionSchema = z.object({
+  component: z.any(), // Allow any component type (function, class, forwardRef, etc.)
+  meta: segmentMetaSchema,
+  usage: segmentUsageSchema,
+  props: z.record(propDefinitionSchema),
+  relations: z.array(componentRelationSchema).optional(),
+  variants: z.array(segmentVariantSchema), // Allow empty variants array
+  contract: segmentContractSchema.optional(),
+  _generated: segmentGeneratedSchema.optional(),
+});
+
+/**
+ * Config schema - validates required fields, passes through optional config objects.
+ * Type definitions are in types.ts - schema just ensures basic structure.
+ */
+export const segmentsConfigSchema = z.object({
+  include: z.array(z.string()).min(1),
+  exclude: z.array(z.string()).optional(),
+  components: z.array(z.string()).optional(),
+  outFile: z.string().optional(),
+  framework: z.enum(['react', 'vue', 'svelte']).optional(),
+  figmaFile: z.string().url().optional(),
+  figmaToken: z.string().optional(),
+  screenshots: z.object({}).passthrough().optional(),
+  service: z.object({}).passthrough().optional(),
+  registry: z.object({}).passthrough().optional(),
+  tokens: z.object({
+    include: z.array(z.string()).min(1),
+  }).passthrough().optional(),
+});