@fragments-sdk/cli 0.2.2

package/src/core/generators/registry.ts

@@ -0,0 +1,364 @@
+/**
+ * Registry Generator
+ * Generates .fragments/registry.json and .fragments/index.json
+ *
+ * Philosophy: Generate only what AI agents and humans can't easily get from source.
+ * - Props: AI can read TypeScript directly (skip by default)
+ * - Paths: Essential for file navigation (always include)
+ * - Enrichment: Human knowledge that doesn't exist elsewhere (include references)
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { relative, dirname, basename, join } from "node:path";
+import fg from "fast-glob";
+import type {
+  Fragment,
+  FragmentRegistry,
+  FragmentIndex,
+  RegistryComponentEntry,
+} from "../fragment-types.js";
+import { extractPropsFromFile } from "./typescript-extractor.js";
+import { BRAND } from "../constants.js";
+import type { RegistryOptions } from "../types.js";
+
+/**
+ * Options for registry generation
+ */
+export interface RegistryGeneratorOptions {
+  /** Project root directory */
+  projectRoot: string;
+  /** Glob patterns for component files */
+  componentPatterns?: string[];
+  /** Glob patterns for story files */
+  storyPatterns?: string[];
+  /** Path to .fragments directory */
+  fragmentsDir?: string;
+  /** Registry options from config */
+  registryOptions?: RegistryOptions;
+}
+
+/**
+ * Result of registry generation
+ */
+export interface RegistryGeneratorResult {
+  /** Generated registry (full metadata) */
+  registry: FragmentRegistry;
+  /** Generated index (minimal name -> path) */
+  index: FragmentIndex;
+  /** Errors encountered during generation */
+  errors: Array<{ file: string; error: string }>;
+  /** Warnings */
+  warnings: Array<{ file: string; warning: string }>;
+}
+
+/**
+ * Generate a fragment registry and index by scanning the project
+ */
+export async function generateRegistry(
+  options: RegistryGeneratorOptions
+): Promise<RegistryGeneratorResult> {
+  const {
+    projectRoot,
+    componentPatterns = ["src/**/*.tsx", "src/**/*.ts"],
+    storyPatterns = ["src/**/*.stories.tsx", "src/**/*.stories.ts"],
+    fragmentsDir = join(projectRoot, BRAND.dataDir),
+    registryOptions = {},
+  } = options;
+
+  const {
+    requireStory = false,
+    publicOnly = false,
+    categoryDepth = 1,
+    includeProps = false,
+    embedFragments = false,
+  } = registryOptions;
+
+  const errors: Array<{ file: string; error: string }> = [];
+  const warnings: Array<{ file: string; warning: string }> = [];
+
+  // Find all story files first (for requireStory filtering)
+  const storyFiles = await fg(storyPatterns, {
+    cwd: projectRoot,
+    ignore: ["**/node_modules/**"],
+    absolute: true,
+  });
+
+  // Build a map of story files by component directory and base name
+  const storyMap = new Map<string, string>();
+  for (const storyPath of storyFiles) {
+    const storyDir = dirname(storyPath);
+    const storyBase = basename(storyPath).replace(/\.stories\.(tsx?|jsx?)$/, "");
+    storyMap.set(`${storyDir}/${storyBase}`, storyPath);
+  }
+
+  // Find all component files
+  const componentFiles = await fg(componentPatterns, {
+    cwd: projectRoot,
+    ignore: [
+      "**/node_modules/**",
+      "**/*.stories.*",
+      "**/*.test.*",
+      "**/*.spec.*",
+      "**/*.d.ts",
+    ],
+    absolute: true,
+  });
+
+  // Find all fragment files
+  const fragmentPattern = join(
+    BRAND.dataDir,
+    BRAND.componentsDir,
+    `*${BRAND.fileExtension}`
+  );
+  const fragmentFiles = await fg(fragmentPattern, {
+    cwd: projectRoot,
+    absolute: true,
+  });
+
+  // Build fragment lookup map
+  const fragmentMap = new Map<string, { path: string; fragment: Fragment }>();
+  for (const fragmentPath of fragmentFiles) {
+    const fragmentName = basename(fragmentPath).replace(BRAND.fileExtension, "");
+    try {
+      const content = readFileSync(fragmentPath, "utf-8");
+      const fragment = JSON.parse(content) as Fragment;
+      fragmentMap.set(fragmentName, {
+        path: relative(projectRoot, fragmentPath),
+        fragment,
+      });
+    } catch (e) {
+      errors.push({
+        file: fragmentPath,
+        error: `Failed to parse fragment: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  // Build component index
+  const components: Record<string, RegistryComponentEntry> = {};
+  const indexComponents: Record<string, string> = {};
+  const categories: Record<string, string[]> = {};
+
+  // Process component files
+  for (const filePath of componentFiles) {
+    try {
+      const extracted = extractPropsFromFile(filePath);
+      if (!extracted || !extracted.componentName) {
+        continue;
+      }
+
+      const componentName = extracted.componentName;
+      const relativePath = relative(projectRoot, filePath);
+
+      // Check if component is exported (for publicOnly filter)
+      if (publicOnly && !extracted.exports.includes(componentName)) {
+        continue;
+      }
+
+      // Find matching story file
+      const componentDir = dirname(filePath);
+      const baseNameWithoutExt = basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
+      const storyPath = storyMap.get(`${componentDir}/${baseNameWithoutExt}`);
+
+      // Apply requireStory filter
+      if (requireStory && !storyPath) {
+        continue;
+      }
+
+      // Get fragment data if exists
+      const fragmentData = fragmentMap.get(componentName);
+
+      // Determine category from directory structure
+      const category = fragmentData?.fragment?.meta?.status
+        ? undefined // Don't use status as category
+        : getCategoryFromPath(relativePath, categoryDepth);
+
+      // Check if fragment has meaningful enrichment (not just a skeleton)
+      const hasEnrichment = fragmentData
+        ? hasRealEnrichment(fragmentData.fragment)
+        : false;
+
+      // Build minimal component entry
+      const entry: RegistryComponentEntry = {
+        path: relativePath,
+      };
+
+      // Add optional fields only if present
+      if (storyPath) {
+        entry.storyPath = relative(projectRoot, storyPath);
+      }
+
+      if (fragmentData) {
+        entry.fragmentPath = fragmentData.path;
+        if (hasEnrichment) {
+          entry.hasEnrichment = true;
+        }
+        if (fragmentData.fragment.description) {
+          entry.description = fragmentData.fragment.description;
+        }
+        if (fragmentData.fragment.meta?.status) {
+          entry.status = fragmentData.fragment.meta.status;
+        }
+        // Only embed full fragment if explicitly requested
+        if (embedFragments) {
+          entry.fragment = fragmentData.fragment;
+        }
+      }
+
+      if (category) {
+        entry.category = category;
+        // Add to categories index
+        if (!categories[category]) {
+          categories[category] = [];
+        }
+        categories[category].push(componentName);
+      }
+
+      // Only include props if explicitly requested
+      if (includeProps && extracted.props) {
+        entry.props = extracted.props;
+      }
+
+      // Only include exports if multiple exports
+      if (extracted.exports.length > 1) {
+        entry.exports = extracted.exports;
+      }
+
+      components[componentName] = entry;
+      indexComponents[componentName] = relativePath;
+    } catch (e) {
+      errors.push({
+        file: filePath,
+        error: `Failed to extract component: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  const componentCount = Object.keys(components).length;
+
+  // Build registry
+  const registry: FragmentRegistry = {
+    $schema: "https://fragments.dev/schema/registry-v1.json",
+    version: "1.0",
+    generatedAt: new Date().toISOString(),
+    componentCount,
+    components,
+    categories,
+  };
+
+  // Build minimal index
+  const index: FragmentIndex = {
+    version: "1.0",
+    generatedAt: registry.generatedAt,
+    components: indexComponents,
+    categories,
+  };
+
+  return { registry, index, errors, warnings };
+}
+
+/**
+ * Get category from file path based on directory structure
+ *
+ * Examples:
+ * - src/components/buttons/Button.tsx -> "buttons"
+ * - src/components/forms/inputs/TextInput.tsx -> "forms" (depth 1) or "forms/inputs" (depth 2)
+ * - src/components/Button/Button.tsx -> "Button" (component folder)
+ */
+function getCategoryFromPath(relativePath: string, depth: number = 1): string | undefined {
+  const parts = relativePath.split("/");
+  const componentsIndex = parts.findIndex((p) => p === "components");
+
+  if (componentsIndex === -1) {
+    return undefined;
+  }
+
+  // Get the parts after "components/"
+  const afterComponents = parts.slice(componentsIndex + 1);
+
+  // If it's just components/Button.tsx, no category
+  if (afterComponents.length <= 1) {
+    return undefined;
+  }
+
+  // If it's components/Button/Button.tsx (component folder pattern), no category
+  const folderName = afterComponents[0];
+  const fileName = afterComponents[afterComponents.length - 1].replace(/\.(tsx?|jsx?)$/, "");
+  if (afterComponents.length === 2 && folderName === fileName) {
+    return undefined;
+  }
+
+  // Get category parts based on depth
+  const categoryParts = afterComponents.slice(0, Math.min(depth, afterComponents.length - 1));
+
+  // Filter out component folders (where folder name matches file name)
+  const lastCategoryPart = categoryParts[categoryParts.length - 1];
+  if (lastCategoryPart === fileName) {
+    categoryParts.pop();
+  }
+
+  if (categoryParts.length === 0) {
+    return undefined;
+  }
+
+  return categoryParts.join("/");
+}
+
+/**
+ * Check if a fragment has meaningful enrichment beyond a skeleton
+ */
+function hasRealEnrichment(fragment: Fragment): boolean {
+  // Has description beyond just the name
+  if (fragment.description && fragment.description.length > 20) {
+    return true;
+  }
+
+  // Has usage guidelines
+  if (fragment.usage?.when && fragment.usage.when.length > 0) {
+    return true;
+  }
+  if (fragment.usage?.doNot && fragment.usage.doNot.length > 0) {
+    return true;
+  }
+  if (fragment.usage?.patterns && fragment.usage.patterns.length > 0) {
+    return true;
+  }
+
+  // Has accessibility info
+  if (fragment.accessibility?.requirements && fragment.accessibility.requirements.length > 0) {
+    return true;
+  }
+
+  // Has figma links
+  if (fragment.figma?.nodeId || fragment.figma?.variants) {
+    return true;
+  }
+
+  // Has related components
+  if (fragment.related?.similar && fragment.related.similar.length > 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Resolve component name to path using registry
+ */
+export function resolveComponentPath(
+  componentName: string,
+  registry: FragmentRegistry
+): string | undefined {
+  const entry = registry.components[componentName];
+  return entry?.path;
+}
+
+/**
+ * Get all components by category
+ */
+export function getComponentsByCategory(
+  category: string,
+  registry: FragmentRegistry
+): string[] {
+  return registry.categories?.[category] || [];
+}