@fragments-sdk/cli 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,775 @@
+/**
+ * Metadata about the component
+ */
+interface SegmentMeta {
+    /** Component display name */
+    name: string;
+    /** Brief description of the component's purpose */
+    description: string;
+    /** Category for organizing components (e.g., "actions", "forms", "layout") */
+    category: string;
+    /** Optional tags for additional categorization */
+    tags?: string[];
+    /** Component status */
+    status?: "stable" | "beta" | "deprecated" | "experimental";
+    /** Version when component was introduced */
+    since?: string;
+    /** Figma frame URL for design verification */
+    figma?: string;
+    /** Figma property mappings (how Figma props map to code props) */
+    figmaProps?: Record<string, FigmaPropMapping>;
+}
+/**
+ * Figma property mapping types - describes how a Figma property maps to code
+ */
+type FigmaPropMapping = FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping;
+/** Maps a Figma text property to a string prop */
+interface FigmaStringMapping {
+    __type: 'figma-string';
+    figmaProperty: string;
+}
+/** Maps a Figma boolean property to a boolean prop (with optional value mapping) */
+interface FigmaBooleanMapping {
+    __type: 'figma-boolean';
+    figmaProperty: string;
+    valueMapping?: {
+        true: unknown;
+        false: unknown;
+    };
+}
+/** Maps a Figma variant property to an enum prop */
+interface FigmaEnumMapping {
+    __type: 'figma-enum';
+    figmaProperty: string;
+    valueMapping: Record<string, unknown>;
+}
+/** References a nested Figma component instance */
+interface FigmaInstanceMapping {
+    __type: 'figma-instance';
+    figmaProperty: string;
+}
+/** Renders children from Figma layer names */
+interface FigmaChildrenMapping {
+    __type: 'figma-children';
+    layers: string[];
+}
+/** Extracts text content from a Figma text layer */
+interface FigmaTextContentMapping {
+    __type: 'figma-text-content';
+    layer: string;
+}
+/**
+ * Usage guidelines for AI agents and developers
+ */
+interface SegmentUsage {
+    /** When to use this component */
+    when: string[];
+    /** When NOT to use this component (with alternatives) */
+    whenNot: string[];
+    /** Additional usage guidelines and best practices */
+    guidelines?: string[];
+    /** Accessibility considerations */
+    accessibility?: string[];
+}
+/**
+ * Prop type definitions
+ */
+type PropType = {
+    type: "string";
+    pattern?: string;
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "enum";
+    values: readonly string[];
+} | {
+    type: "function";
+    signature?: string;
+} | {
+    type: "node";
+} | {
+    type: "element";
+} | {
+    type: "object";
+    shape?: Record<string, PropDefinition>;
+} | {
+    type: "array";
+    items?: PropType;
+} | {
+    type: "union";
+    types: PropType[];
+} | {
+    type: "custom";
+    typescript: string;
+};
+/**
+ * Storybook control types for UI rendering
+ */
+type ControlType = "text" | "number" | "range" | "boolean" | "select" | "multi-select" | "radio" | "inline-radio" | "check" | "inline-check" | "object" | "file" | "color" | "date";
+/**
+ * Definition for a single prop
+ */
+interface PropDefinition {
+    /** The prop type */
+    type: PropType["type"];
+    /** For enum types, the allowed values */
+    values?: readonly string[];
+    /** Default value if not provided */
+    default?: unknown;
+    /** Description of what this prop does */
+    description: string;
+    /** Whether this prop is required */
+    required?: boolean;
+    /** Usage constraints for AI agents */
+    constraints?: string[];
+    /** Additional type details for complex types */
+    typeDetails?: Omit<PropType, "type">;
+    /** Original Storybook control type for UI rendering (e.g., "color", "date", "range") */
+    controlType?: ControlType;
+    /** Control options (e.g., min/max for range, presetColors for color) */
+    controlOptions?: {
+        min?: number;
+        max?: number;
+        step?: number;
+        presetColors?: string[];
+    };
+}
+/**
+ * Relationship types between components
+ */
+type RelationshipType = "alternative" | "sibling" | "parent" | "child" | "composition";
+/**
+ * Relationship to another component
+ */
+interface ComponentRelation {
+    /** Name of the related component */
+    component: string;
+    /** Type of relationship */
+    relationship: RelationshipType;
+    /** Explanation of the relationship */
+    note: string;
+}
+/**
+ * Agent-optimized contract metadata
+ * Provides compact, structured data for AI code generation
+ */
+interface SegmentContract {
+    /** Short prop descriptions for agents (e.g., "variant: primary|secondary (required)") */
+    propsSummary?: string[];
+    /** Accessibility rule IDs for lookup in glossary (e.g., "A11Y_BTN_LABEL") */
+    a11yRules?: string[];
+    /** Banned patterns in codebase - triggers warnings during code review */
+    bans?: Array<{
+        /** Pattern to match (regex string or literal) */
+        pattern: string;
+        /** Message explaining why this pattern is banned and what to use instead */
+        message: string;
+    }>;
+    /** Scenario tags for use-case matching (e.g., "form.submit", "navigation.primary") */
+    scenarioTags?: string[];
+}
+/**
+ * Provenance tracking for generated segments
+ * Helps distinguish human-authored from machine-generated content
+ */
+interface SegmentGenerated {
+    /** Source of this segment definition */
+    source: "storybook" | "manual" | "ai";
+    /** Original source file (e.g., "Button.stories.tsx") */
+    sourceFile?: string;
+    /** Confidence score from 0-1 (how reliable the extraction was) */
+    confidence?: number;
+    /** ISO timestamp when this was generated */
+    timestamp?: string;
+}
+/**
+ * Registry generation options
+ */
+interface RegistryOptions {
+    /** Only include components that have a corresponding .stories.tsx file */
+    requireStory?: boolean;
+    /** Only include components that are exported (public API) */
+    publicOnly?: boolean;
+    /** Maximum depth for category inference from directory structure (default: 1) */
+    categoryDepth?: number;
+    /** Include props in registry (default: false - AI can read TypeScript directly) */
+    includeProps?: boolean;
+    /** Include full fragment data in registry (default: false - reference fragmentPath instead) */
+    embedFragments?: boolean;
+}
+/**
+ * Design token configuration
+ */
+interface TokenConfig {
+    /**
+     * Glob patterns for files to scan for tokens
+     * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
+     */
+    include: string[];
+    /**
+     * Glob patterns to exclude
+     * @example ["node_modules"]
+     */
+    exclude?: string[];
+    /**
+     * Map CSS selectors to theme names
+     * @example { ":root": "default", "[data-theme='dark']": "dark" }
+     */
+    themeSelectors?: Record<string, string>;
+    /** Enable token comparison in style diffs (default: true) */
+    enabled?: boolean;
+}
+/**
+ * CI configuration for automated compliance checks
+ */
+interface CIConfig {
+    /** Minimum compliance percentage to pass (default: 80) */
+    minCompliance?: number;
+    /** Whether to fail on any visual regression */
+    failOnDiff?: boolean;
+    /** Whether to output JSON format */
+    jsonOutput?: boolean;
+}
+/**
+ * Config file structure
+ */
+interface FragmentsConfig {
+    /** Glob patterns for finding segment/fragment files */
+    include: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Glob patterns for finding component files (for coverage validation) */
+    components?: string[];
+    /** Output path for compiled output */
+    outFile?: string;
+    /** Framework adapter to use */
+    framework?: "react" | "vue" | "svelte";
+    /** Figma file URL for the design system (used by `fragments link`) */
+    figmaFile?: string;
+    /** Figma access token (alternative to FIGMA_ACCESS_TOKEN env var) */
+    figmaToken?: string;
+    /** Screenshot configuration */
+    screenshots?: ScreenshotConfig;
+    /** Service configuration */
+    service?: ServiceConfig;
+    /** Registry generation options */
+    registry?: RegistryOptions;
+    /** Design token discovery and mapping configuration */
+    tokens?: TokenConfig;
+    /** CI pipeline configuration */
+    ci?: CIConfig;
+}
+/**
+ * @deprecated Use FragmentsConfig instead
+ */
+type SegmentsConfig = FragmentsConfig;
+/**
+ * Screenshot capture configuration
+ */
+interface ScreenshotConfig {
+    /** Default viewport for captures */
+    viewport?: Viewport;
+    /** Diff threshold percentage (0-100) */
+    threshold?: number;
+    /** Additional delay after render before capture (ms) */
+    delay?: number;
+    /** Output directory for baselines (relative to project root) */
+    outputDir?: string;
+    /** Themes to capture */
+    themes?: Theme[];
+}
+/**
+ * Service configuration
+ */
+interface ServiceConfig {
+    /** Browser pool size */
+    poolSize?: number;
+    /** Idle timeout before shutdown (ms) */
+    idleTimeout?: number;
+}
+/**
+ * Viewport dimensions
+ */
+interface Viewport {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+/**
+ * Theme identifier
+ */
+type Theme = "light" | "dark";
+/**
+ * Result of comparing two screenshots
+ */
+interface DiffResult {
+    /** Whether images are considered matching (below threshold) */
+    matches: boolean;
+    /** Percentage of pixels that differ (0-100) */
+    diffPercentage: number;
+    /** Number of differing pixels */
+    diffPixelCount: number;
+    /** Total pixels compared */
+    totalPixels: number;
+    /** PNG image highlighting differences */
+    diffImage?: Buffer;
+    /** Bounding boxes of changed regions */
+    changedRegions: BoundingBox[];
+    /** Time taken to compute diff (ms) */
+    diffTimeMs: number;
+}
+/**
+ * Bounding box for changed region
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Compiled segment data (JSON-serializable for AI consumption)
+ */
+interface CompiledSegment {
+    /** File path relative to project root */
+    filePath: string;
+    /** Component metadata */
+    meta: SegmentMeta;
+    /** Usage guidelines */
+    usage: SegmentUsage;
+    /** Props documentation (without render functions) */
+    props: Record<string, PropDefinition>;
+    /** Component relationships */
+    relations?: ComponentRelation[];
+    /** Variant names and descriptions (without render functions) */
+    variants: Array<{
+        name: string;
+        description: string;
+        code?: string;
+        figma?: string;
+        /** Args/props used to render this variant (for code generation) */
+        args?: Record<string, unknown>;
+    }>;
+    /** Agent-optimized contract metadata */
+    contract?: SegmentContract;
+    /** Provenance tracking (for generated segments) */
+    _generated?: SegmentGenerated;
+}
+/**
+ * Compiled recipe data (JSON-serializable for AI consumption)
+ */
+interface CompiledRecipe {
+    filePath: string;
+    name: string;
+    description: string;
+    category: string;
+    components: string[];
+    code: string;
+    tags?: string[];
+}
+/**
+ * The compiled segments.json structure
+ */
+interface CompiledSegmentsFile {
+    /** Version of the schema */
+    version: string;
+    /** When this file was generated */
+    generatedAt: string;
+    /** All compiled segments indexed by component name */
+    segments: Record<string, CompiledSegment>;
+    /** All compiled recipes indexed by recipe name */
+    recipes?: Record<string, CompiledRecipe>;
+}
+
+/**
+ * Find the config file in the current directory or parent directories.
+ * Checks for both the current config file name and the legacy name.
+ */
+declare function findConfigFile(startDir?: string): string | null;
+/**
+ * Load and validate the config file
+ */
+declare function loadConfig(configPath?: string): Promise<{
+    config: SegmentsConfig;
+    configDir: string;
+}>;
+
+interface DiscoveredFile {
+    /** Absolute path to the file */
+    absolutePath: string;
+    /** Path relative to config directory */
+    relativePath: string;
+}
+/**
+ * Discover segment files matching the config patterns
+ */
+declare function discoverSegmentFiles(config: SegmentsConfig, configDir: string): Promise<DiscoveredFile[]>;
+/**
+ * Discover component files for coverage validation
+ */
+declare function discoverComponentFiles(config: SegmentsConfig, configDir: string): Promise<DiscoveredFile[]>;
+/**
+ * Extract component name from file path
+ */
+declare function extractComponentName(filePath: string): string;
+
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    file: string;
+    message: string;
+    details?: string;
+}
+interface ValidationWarning {
+    file: string;
+    message: string;
+}
+/**
+ * Validate segment file schema
+ */
+declare function validateSchema(config: SegmentsConfig, configDir: string): Promise<ValidationResult>;
+/**
+ * Validate coverage - ensure all components have segments
+ */
+declare function validateCoverage(config: SegmentsConfig, configDir: string): Promise<ValidationResult>;
+/**
+ * Run all validations
+ */
+declare function validateAll(config: SegmentsConfig, configDir: string): Promise<ValidationResult>;
+
+interface BuildResult {
+    success: boolean;
+    outputPath: string;
+    segmentCount: number;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+    warnings: Array<{
+        file: string;
+        warning: string;
+    }>;
+}
+/**
+ * Build compiled fragments.json file for AI consumption.
+ *
+ * Uses AST parsing to extract metadata WITHOUT executing fragment files.
+ * This means the build works without any project dependencies installed.
+ */
+declare function buildSegments(config: SegmentsConfig, configDir: string): Promise<BuildResult>;
+
+/**
+ * Options for the screenshot command
+ */
+interface ScreenshotCommandOptions {
+    /** Specific component to capture */
+    component?: string;
+    /** Specific variant to capture */
+    variant?: string;
+    /** Theme to capture */
+    theme?: Theme;
+    /** Update existing baselines */
+    update?: boolean;
+    /** CI mode - no interactive prompts */
+    ci?: boolean;
+    /** Viewport width */
+    width?: number;
+    /** Viewport height */
+    height?: number;
+}
+/**
+ * Result of the screenshot command
+ */
+interface ScreenshotResult {
+    success: boolean;
+    captured: number;
+    skipped: number;
+    errors: Array<{
+        component: string;
+        variant: string;
+        error: string;
+    }>;
+    totalTimeMs: number;
+}
+/**
+ * Execute the screenshot command
+ */
+declare function runScreenshotCommand(config: SegmentsConfig, configDir: string, options?: ScreenshotCommandOptions): Promise<ScreenshotResult>;
+
+/**
+ * Analytics engine for design system insights.
+ *
+ * Analyzes compiled segments to provide:
+ * - Component inventory stats
+ * - Documentation coverage
+ * - Usage pattern insights
+ * - Quality scores
+ */
+
+/**
+ * Overall design system analytics
+ */
+interface DesignSystemAnalytics {
+    /** When the analysis was performed */
+    analyzedAt: Date;
+    /** Summary metrics */
+    summary: {
+        totalComponents: number;
+        totalVariants: number;
+        totalProps: number;
+        categories: string[];
+        overallScore: number;
+    };
+    /** Component inventory */
+    inventory: ComponentInventory;
+    /** Documentation coverage */
+    coverage: CoverageAnalytics;
+    /** Quality insights */
+    quality: QualityAnalytics;
+    /** Distribution charts data */
+    distribution: DistributionAnalytics;
+    /** Recommendations for improvement */
+    recommendations: Recommendation[];
+}
+/**
+ * Component inventory breakdown
+ */
+interface ComponentInventory {
+    /** Components by category */
+    byCategory: Record<string, ComponentSummary[]>;
+    /** Components by status */
+    byStatus: Record<string, ComponentSummary[]>;
+    /** Components sorted by variant count (most to least) */
+    byVariantCount: ComponentSummary[];
+    /** Components sorted by prop count */
+    byPropCount: ComponentSummary[];
+}
+/**
+ * Summary info for a single component
+ */
+interface ComponentSummary {
+    name: string;
+    category: string;
+    status: string;
+    variantCount: number;
+    propCount: number;
+    hasUsageWhen: boolean;
+    hasUsageWhenNot: boolean;
+    hasGuidelines: boolean;
+    hasRelations: boolean;
+    documentationScore: number;
+}
+/**
+ * Documentation coverage analytics
+ */
+interface CoverageAnalytics {
+    /** Overall coverage percentage */
+    overall: number;
+    /** Coverage by field */
+    fields: {
+        description: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        usageWhen: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        usageWhenNot: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        guidelines: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        accessibility: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        relations: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        propDescriptions: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+        propConstraints: {
+            covered: number;
+            total: number;
+            percentage: number;
+        };
+    };
+    /** Components with incomplete documentation */
+    incomplete: Array<{
+        component: string;
+        missing: string[];
+    }>;
+}
+/**
+ * Quality insights
+ */
+interface QualityAnalytics {
+    /** Components with no whenNot guidance (anti-patterns) */
+    missingWhenNot: string[];
+    /** Components with no relations defined */
+    isolated: string[];
+    /** Deprecated components still in use */
+    deprecated: string[];
+    /** Components with very few variants (might need more examples) */
+    fewVariants: string[];
+    /** Props without descriptions */
+    undocumentedProps: Array<{
+        component: string;
+        prop: string;
+    }>;
+    /** Props without constraints (might need validation rules) */
+    unconstrainedProps: Array<{
+        component: string;
+        prop: string;
+    }>;
+}
+/**
+ * Distribution data for charts
+ */
+interface DistributionAnalytics {
+    /** Variants per component distribution */
+    variantsPerComponent: Array<{
+        name: string;
+        count: number;
+    }>;
+    /** Props per component distribution */
+    propsPerComponent: Array<{
+        name: string;
+        count: number;
+    }>;
+    /** Components per category */
+    componentsPerCategory: Array<{
+        category: string;
+        count: number;
+    }>;
+    /** Status distribution */
+    statusDistribution: Array<{
+        status: string;
+        count: number;
+    }>;
+    /** Tag frequency */
+    tagFrequency: Array<{
+        tag: string;
+        count: number;
+    }>;
+}
+/**
+ * Actionable recommendation
+ */
+interface Recommendation {
+    priority: "high" | "medium" | "low";
+    category: "documentation" | "coverage" | "quality" | "organization";
+    title: string;
+    description: string;
+    components?: string[];
+    impact: string;
+}
+
+/**
+ * Options for the diff command
+ */
+interface DiffCommandOptions {
+    /** Specific component to diff */
+    component?: string;
+    /** Specific variant to diff */
+    variant?: string;
+    /** Theme to compare */
+    theme?: Theme;
+    /** CI mode - exit 1 on differences */
+    ci?: boolean;
+    /** Diff threshold percentage */
+    threshold?: number;
+    /** Open diff images */
+    open?: boolean;
+}
+/**
+ * Single diff result with metadata
+ */
+interface VariantDiffResult {
+    component: string;
+    variant: string;
+    theme: Theme;
+    result: DiffResult;
+    diffImagePath?: string;
+}
+/**
+ * Result of the diff command
+ */
+interface DiffCommandResult {
+    success: boolean;
+    total: number;
+    passed: number;
+    failed: number;
+    missing: number;
+    results: VariantDiffResult[];
+    totalTimeMs: number;
+}
+/**
+ * Execute the diff command
+ */
+declare function runDiffCommand(config: SegmentsConfig, configDir: string, options?: DiffCommandOptions): Promise<DiffCommandResult>;
+
+/**
+ * CLI command: segments analyze
+ *
+ * Analyzes the design system and generates an HTML report with:
+ * - Component inventory
+ * - Documentation coverage
+ * - Quality insights
+ * - Actionable recommendations
+ */
+
+interface AnalyzeOptions {
+    /** Output format */
+    format?: "html" | "json" | "console";
+    /** Output file path (default: segments-report.html) */
+    output?: string;
+    /** Open report in browser after generation */
+    open?: boolean;
+    /** CI mode - exit with appropriate code */
+    ci?: boolean;
+    /** Minimum score to pass in CI mode */
+    minScore?: number;
+}
+interface AnalyzeResult {
+    success: boolean;
+    analytics: DesignSystemAnalytics;
+    outputPath?: string;
+}
+/**
+ * Run the analyze command
+ */
+declare function runAnalyzeCommand(config: SegmentsConfig, configDir: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+
+/**
+ * Generate a static HTML viewer for the segments.json file.
+ * This viewer shows component documentation without needing to render actual components.
+ */
+declare function generateStaticViewer(data: CompiledSegmentsFile): string;
+/**
+ * Load segments.json and generate static viewer
+ */
+declare function generateViewerFromJson(jsonPath: string): Promise<string>;
+
+export { type AnalyzeOptions, type AnalyzeResult, type BuildResult, type DiffCommandOptions, type DiffCommandResult, type DiscoveredFile, type ScreenshotCommandOptions, type ScreenshotResult, type ValidationError, type ValidationResult, type ValidationWarning, type VariantDiffResult, buildSegments, discoverComponentFiles, discoverSegmentFiles, extractComponentName, findConfigFile, generateStaticViewer, generateViewerFromJson, loadConfig, runAnalyzeCommand, runDiffCommand, runScreenshotCommand, validateAll, validateCoverage, validateSchema };