@fragments-sdk/cli 0.2.2

package/src/commands/scan.ts

@@ -0,0 +1,537 @@
+/**
+ * fragments scan - Zero-config segments.json generation from source code
+ *
+ * Automatically extracts component documentation by:
+ * 1. Discovering components from source files and barrel exports
+ * 2. Extracting props from TypeScript interfaces
+ * 3. Scanning codebase for usage patterns
+ * 4. Parsing Storybook stories for examples
+ * 5. Inferring component relationships from usage data
+ * 6. Generating complete segments.json without manual documentation
+ */
+
+import { writeFile, mkdir } from "node:fs/promises";
+import { resolve, join, dirname, relative } from "node:path";
+import pc from "picocolors";
+import {
+  BRAND,
+  type CompiledSegmentsFile,
+  type CompiledSegment,
+  type PropDefinition,
+} from "../core/index.js";
+import {
+  loadConfig,
+  discoverAllComponents,
+  type DiscoveredComponent,
+} from "../core/node.js";
+import {
+  scanCodebase,
+  extractPropsFromFile,
+  parseAllStories,
+  inferAllRelations,
+  generateComponentContext,
+  generateEnhancementSuggestions,
+  filterBoilerplate,
+  convertToSegmentProps,
+  type UsageAnalysis,
+  type ComponentRelation,
+  type PropsExtractionResult,
+  type ParsedStoryFile,
+} from "../service/index.js";
+
+export interface ScanOptions {
+  /** Path to config file */
+  config?: string;
+  /** Output file path (default: segments.json) */
+  output?: string;
+  /** Component patterns to scan */
+  componentPatterns?: string[];
+  /** Barrel export files to parse */
+  barrelFiles?: string[];
+  /** Directory to scan for usage patterns */
+  usageDir?: string;
+  /** Skip usage analysis */
+  skipUsage?: boolean;
+  /** Skip Storybook parsing */
+  skipStorybook?: boolean;
+  /** Verbose output */
+  verbose?: boolean;
+}
+
+export interface ScanResult {
+  success: boolean;
+  outputPath: string;
+  componentCount: number;
+  propsExtracted: number;
+  usagesFound: number;
+  relationsInferred: number;
+  storiesParsed: number;
+  errors: Array<{ component: string; error: string }>;
+  warnings: Array<{ component: string; warning: string }>;
+}
+
+/**
+ * Scan codebase and generate segments.json directly from source
+ */
+export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
+  const startTime = Date.now();
+  const errors: Array<{ component: string; error: string }> = [];
+  const warnings: Array<{ component: string; warning: string }> = [];
+
+  // Load config or use defaults
+  let configDir: string;
+  let outputFile: string;
+  let componentPatterns: string[] | undefined;
+
+  try {
+    const loaded = await loadConfig(options.config);
+    configDir = loaded.configDir;
+    outputFile = options.output || loaded.config.outFile || "segments.json";
+    componentPatterns = options.componentPatterns || loaded.config.components;
+  } catch {
+    // No config file, use defaults
+    configDir = process.cwd();
+    outputFile = options.output || "segments.json";
+    componentPatterns = options.componentPatterns;
+  }
+
+  console.log(pc.cyan(`\n${BRAND.name} Scan\n`));
+  console.log(pc.dim("Zero-config segments.json generation from source code\n"));
+
+  // Phase 1: Discover components
+  console.log(pc.dim("Phase 1: Discovering components..."));
+  const components = await discoverAllComponents(configDir, {
+    patterns: componentPatterns,
+    exclude: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"],
+    barrelFiles: options.barrelFiles,
+  });
+
+  if (components.length === 0) {
+    console.log(pc.yellow("No components found. Check your patterns or config."));
+    return {
+      success: false,
+      outputPath: resolve(configDir, outputFile),
+      componentCount: 0,
+      propsExtracted: 0,
+      usagesFound: 0,
+      relationsInferred: 0,
+      storiesParsed: 0,
+      errors: [{ component: "*", error: "No components found" }],
+      warnings: [],
+    };
+  }
+
+  console.log(pc.green(`  Found ${components.length} components`));
+  if (options.verbose) {
+    for (const comp of components.slice(0, 10)) {
+      console.log(pc.dim(`    - ${comp.name}: ${comp.relativePath}`));
+    }
+    if (components.length > 10) {
+      console.log(pc.dim(`    ... and ${components.length - 10} more`));
+    }
+  }
+
+  // Phase 2: Extract props from TypeScript
+  console.log(pc.dim("\nPhase 2: Extracting props from TypeScript..."));
+  const propsMap = new Map<string, ReturnType<typeof convertToSegmentProps>>();
+  const propsResults = new Map<string, PropsExtractionResult>();
+  let propsExtracted = 0;
+
+  for (const comp of components) {
+    try {
+      const extraction = await extractPropsFromFile(comp.sourcePath, {
+        propsTypeName: `${comp.name}Props`,
+      });
+
+      propsResults.set(comp.name, extraction);
+
+      if (extraction.success && extraction.props.length > 0) {
+        propsMap.set(comp.name, convertToSegmentProps(extraction.props));
+        propsExtracted++;
+      }
+    } catch (e) {
+      if (options.verbose) {
+        warnings.push({
+          component: comp.name,
+          warning: `Props extraction failed: ${e instanceof Error ? e.message : String(e)}`,
+        });
+      }
+    }
+  }
+
+  console.log(pc.green(`  Extracted props for ${propsExtracted} components`));
+
+  // Phase 3: Scan for usage patterns
+  let usageAnalysis: UsageAnalysis | undefined;
+  let usagesFound = 0;
+  let allRelations = new Map<string, ComponentRelation[]>();
+
+  if (!options.skipUsage) {
+    console.log(pc.dim("\nPhase 3: Scanning for usage patterns..."));
+    const usageDir = options.usageDir || configDir;
+
+    try {
+      // Get component names for filtering
+      const componentNames = components.map((c) => c.name);
+
+      usageAnalysis = await scanCodebase({
+        rootDir: usageDir,
+        include: ["**/*.tsx", "**/*.ts", "**/*.jsx", "**/*.js"],
+        exclude: [
+          "**/node_modules/**",
+          "**/dist/**",
+          "**/*.stories.*",
+          "**/*.test.*",
+          "**/*.spec.*",
+        ],
+        componentNames,
+        useCache: true,
+      });
+
+      // Count total usages across all components
+      usagesFound = Object.values(usageAnalysis.components).reduce(
+        (sum, comp) => sum + comp.totalUsages,
+        0
+      );
+
+      // Infer relations
+      allRelations = inferAllRelations(usageAnalysis);
+      console.log(pc.green(`  Found ${usagesFound} usages across ${usageAnalysis.totalFiles} files`));
+      console.log(pc.green(`  Inferred relations for ${allRelations.size} components`));
+    } catch (e) {
+      warnings.push({
+        component: "*",
+        warning: `Usage scanning failed: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      console.log(pc.yellow(`  Usage scanning failed: ${e instanceof Error ? e.message : "unknown error"}`));
+    }
+  } else {
+    console.log(pc.dim("\nPhase 3: Skipping usage analysis"));
+  }
+
+  // Phase 4: Parse Storybook stories
+  const storiesMap = new Map<string, ParsedStoryFile>();
+  let storiesParsed = 0;
+
+  if (!options.skipStorybook) {
+    console.log(pc.dim("\nPhase 4: Parsing Storybook stories..."));
+
+    try {
+      const allStories = await parseAllStories(configDir);
+
+      for (const [name, stories] of Object.entries(allStories)) {
+        if (stories && stories.stories.length > 0) {
+          storiesMap.set(name, stories);
+          storiesParsed++;
+        }
+      }
+
+      console.log(pc.green(`  Parsed stories for ${storiesParsed} components`));
+    } catch (e) {
+      warnings.push({
+        component: "*",
+        warning: `Storybook parsing failed: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      console.log(pc.yellow(`  Storybook parsing failed: ${e instanceof Error ? e.message : "unknown error"}`));
+    }
+  } else {
+    console.log(pc.dim("\nPhase 4: Skipping Storybook parsing"));
+  }
+
+  // Phase 5: Generate segments
+  console.log(pc.dim("\nPhase 5: Generating segments..."));
+  const segments: Record<string, CompiledSegment> = {};
+
+  for (const comp of components) {
+    try {
+      const segment = generateSegmentFromData(
+        comp,
+        configDir,
+        propsMap.get(comp.name),
+        usageAnalysis?.components[comp.name],
+        allRelations.get(comp.name),
+        storiesMap.get(comp.name)
+      );
+
+      segments[comp.name] = segment;
+    } catch (e) {
+      errors.push({
+        component: comp.name,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+
+  // Write output
+  const outputPath = resolve(configDir, outputFile);
+  await mkdir(dirname(outputPath), { recursive: true });
+
+  const output: CompiledSegmentsFile = {
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    segments,
+  };
+
+  await writeFile(outputPath, JSON.stringify(output, null, 2));
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  // Summary
+  console.log(pc.dim("\n────────────────────────────────────────"));
+  console.log(pc.green(`\n✓ Generated segments.json in ${elapsed}s`));
+  console.log(pc.dim(`  Output: ${relative(process.cwd(), outputPath)}`));
+  console.log(pc.dim(`  Components: ${Object.keys(segments).length}`));
+  console.log(pc.dim(`  Props extracted: ${propsExtracted}`));
+  console.log(pc.dim(`  Usages found: ${usagesFound}`));
+  console.log(pc.dim(`  Relations inferred: ${allRelations.size}`));
+  console.log(pc.dim(`  Stories parsed: ${storiesParsed}`));
+
+  if (warnings.length > 0) {
+    console.log(pc.yellow(`\n  ${warnings.length} warning(s)`));
+    if (options.verbose) {
+      for (const w of warnings) {
+        console.log(pc.dim(`    ${w.component}: ${w.warning}`));
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    console.log(pc.red(`\n  ${errors.length} error(s)`));
+    for (const e of errors) {
+      console.log(pc.dim(`    ${e.component}: ${e.error}`));
+    }
+  }
+
+  console.log();
+
+  return {
+    success: errors.length === 0,
+    outputPath,
+    componentCount: Object.keys(segments).length,
+    propsExtracted,
+    usagesFound,
+    relationsInferred: allRelations.size,
+    storiesParsed,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Generate a CompiledSegment from extracted data
+ */
+function generateSegmentFromData(
+  comp: DiscoveredComponent,
+  configDir: string,
+  props: Record<string, PropDefinition> | undefined,
+  usageAnalysis: UsageAnalysis["components"][string] | undefined,
+  relations: ComponentRelation[] | undefined,
+  storyFile: ParsedStoryFile | undefined
+): CompiledSegment {
+  // Generate context for AI suggestions
+  const context = generateComponentContext(
+    comp.name,
+    usageAnalysis,
+    undefined, // No extracted docs yet
+    storyFile,
+    undefined, // No props extraction result (we have the converted props already)
+    relations
+  );
+
+  // Generate enhancement suggestions from context
+  const suggestions = generateEnhancementSuggestions(context);
+
+  // Filter boilerplate from suggestions
+  const when = filterBoilerplate(suggestions.suggestions.when);
+  const whenNot = filterBoilerplate(suggestions.suggestions.whenNot);
+
+  // Infer category from path
+  const category = inferCategory(comp.relativePath);
+
+  // Infer status from path
+  const status = inferStatus(comp.relativePath);
+
+  // Build variants from stories
+  const variants: CompiledSegment["variants"] = [];
+  if (storyFile?.stories) {
+    for (const story of storyFile.stories) {
+      variants.push({
+        name: story.name,
+        description: story.description || `${story.displayName} variant`,
+        code: story.code,
+      });
+    }
+  }
+
+  // Build relations
+  const compiledRelations: CompiledSegment["relations"] = [];
+  if (relations && relations.length > 0) {
+    for (const rel of relations.slice(0, 10)) {
+      compiledRelations.push({
+        component: rel.component,
+        relationship: rel.relationship,
+        note: `Appears together ${rel.frequency} times`,
+      });
+    }
+  }
+
+  // Generate description
+  const description = generateDescription(comp.name, props, usageAnalysis);
+
+  return {
+    filePath: comp.relativePath,
+    meta: {
+      name: comp.name,
+      description,
+      category,
+      status,
+    },
+    usage: {
+      when: when.length > 0 ? when : [`Use ${comp.name} for its intended purpose`],
+      whenNot: whenNot,
+    },
+    props: props || {},
+    relations: compiledRelations.length > 0 ? compiledRelations : undefined,
+    variants,
+    _generated: {
+      source: "ai",
+      sourceFile: comp.relativePath,
+      confidence: calculateConfidence(props, usageAnalysis, storyFile),
+      timestamp: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Infer category from file path
+ */
+function inferCategory(relativePath: string): string {
+  const parts = relativePath.toLowerCase().split("/");
+
+  // Common category patterns
+  const categoryPatterns: Record<string, string[]> = {
+    "Actions": ["button", "action", "cta"],
+    "Forms": ["form", "input", "select", "checkbox", "radio", "textarea", "field"],
+    "Layout": ["layout", "container", "grid", "flex", "stack", "box", "divider", "spacer"],
+    "Navigation": ["nav", "menu", "breadcrumb", "tab", "link", "pagination"],
+    "Feedback": ["alert", "toast", "notification", "message", "badge", "indicator", "progress", "spinner", "loading"],
+    "Data Display": ["table", "list", "card", "avatar", "stat", "timeline", "tree"],
+    "Overlays": ["modal", "dialog", "drawer", "popover", "tooltip", "dropdown"],
+    "Typography": ["text", "heading", "title", "label", "paragraph"],
+    "Media": ["image", "video", "icon", "avatar"],
+  };
+
+  for (const [category, patterns] of Object.entries(categoryPatterns)) {
+    for (const pattern of patterns) {
+      if (parts.some((part) => part.includes(pattern))) {
+        return category;
+      }
+    }
+  }
+
+  // Check path structure for category
+  const componentIdx = parts.findIndex((p) => p === "components");
+  if (componentIdx !== -1 && parts.length > componentIdx + 1) {
+    const categoryPart = parts[componentIdx + 1];
+    return categoryPart.charAt(0).toUpperCase() + categoryPart.slice(1);
+  }
+
+  return "Components";
+}
+
+/**
+ * Infer status from file path
+ */
+function inferStatus(
+  relativePath: string
+): "stable" | "beta" | "experimental" | "deprecated" {
+  const lowerPath = relativePath.toLowerCase();
+
+  if (lowerPath.includes("/experimental/") || lowerPath.includes("/labs/")) {
+    return "experimental";
+  }
+  if (lowerPath.includes("/beta/")) {
+    return "beta";
+  }
+  if (lowerPath.includes("/deprecated/") || lowerPath.includes("/legacy/")) {
+    return "deprecated";
+  }
+
+  return "stable";
+}
+
+/**
+ * Generate component description
+ */
+function generateDescription(
+  name: string,
+  props: Record<string, PropDefinition> | undefined,
+  usageAnalysis: UsageAnalysis["components"][string] | undefined
+): string {
+  // Convert name to readable form
+  const words = name
+    .replace(/([A-Z])/g, " $1")
+    .trim()
+    .toLowerCase();
+
+  // Check props for hints
+  const hasOnClick = props && ("onClick" in props || "onPress" in props);
+  const hasValue = props && ("value" in props || "defaultValue" in props);
+  const hasChildren = props && "children" in props;
+  const hasHref = props && "href" in props;
+
+  // Check usage contexts
+  const topContext = usageAnalysis?.contexts[0]?.type;
+
+  if (hasHref) {
+    return `Navigational ${words} for linking to other pages or resources`;
+  }
+
+  if (hasOnClick && !hasValue) {
+    return `Interactive ${words} for triggering actions`;
+  }
+
+  if (hasValue) {
+    return `Form ${words} for user input`;
+  }
+
+  if (topContext && topContext !== "unknown") {
+    return `${words.charAt(0).toUpperCase() + words.slice(1)} commonly used in ${topContext} contexts`;
+  }
+
+  if (hasChildren) {
+    return `Container ${words} for composing UI`;
+  }
+
+  return `${words.charAt(0).toUpperCase() + words.slice(1)} component`;
+}
+
+/**
+ * Calculate confidence score based on available data
+ */
+function calculateConfidence(
+  props: Record<string, PropDefinition> | undefined,
+  usageAnalysis: UsageAnalysis["components"][string] | undefined,
+  storyFile: ParsedStoryFile | undefined
+): number {
+  let confidence = 0;
+
+  // Props give +30 confidence
+  if (props && Object.keys(props).length > 0) {
+    confidence += 30;
+  }
+
+  // Usage data gives up to +40 confidence
+  if (usageAnalysis) {
+    if (usageAnalysis.totalUsages > 10) confidence += 40;
+    else if (usageAnalysis.totalUsages > 5) confidence += 30;
+    else if (usageAnalysis.totalUsages > 0) confidence += 20;
+  }
+
+  // Stories give +30 confidence
+  if (storyFile && storyFile.stories.length > 0) {
+    confidence += 30;
+  }
+
+  return Math.min(confidence, 100);
+}