@fragments-sdk/cli 0.14.3 → 0.15.1

package/src/build.ts

@@ -1,612 +0,0 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { resolve, join } from "node:path";
-import { existsSync } from "node:fs";
-import type {
-  FragmentsConfig,
-  CompiledFragmentsFile,
-  CompiledFragment,
-  CompiledBlock,
-  CompiledTokenData,
-} from "./core/index.js";
-import { BRAND, compileBlock, parseTokenFile } from "./core/index.js";
-import { resolveTokensWithSass } from "./core/token-resolver.js";
-import type { BlockDefinition } from "./core/index.js";
-import {
-  discoverFragmentFiles,
-  discoverBlockFiles,
-  discoverTokenFiles,
-  parseFragmentFile,
-  loadFragmentFile,
-  generateRegistry,
-  generateContextMd,
-} from "./core/node.js";
-import {
-  resolveComponentSourcePath,
-} from "./core/auto-props.js";
-import {
-  createComponentExtractor,
-  type PropMeta,
-  type ComponentMeta,
-} from "./core/component-extractor.js";
-import { buildComponentGraph } from "./core/graph-extractor.js";
-import { serializeGraph } from "@fragments-sdk/context/graph";
-import { resolvePerformanceConfig } from "./core/index.js";
-import { measureBundleSizes, toPerformanceData } from "./core/bundle-measurer.js";
-import type { PerformanceSummary } from "@fragments-sdk/context/types";
-
-type CompiledProp = CompiledFragment["props"][string];
-
-function normalizeParsedProps(
-  parsedProps: Record<string, Partial<CompiledProp>>
-): Record<string, CompiledProp> {
-  return Object.fromEntries(
-    Object.entries(parsedProps).map(([name, prop]) => [
-      name,
-      {
-        type: prop.type ?? "custom",
-        description: prop.description ?? "",
-        default: prop.default,
-        required: prop.required,
-        values: prop.values,
-        constraints: prop.constraints,
-      },
-    ])
-  );
-}
-
-function mergeDocumentedAndAutoProps(
-  documentedProps: Record<string, CompiledProp>,
-  autoProps: Record<string, PropMeta>
-): Record<string, CompiledProp> {
-  return Object.fromEntries(
-    Object.keys(autoProps)
-      // Strip inherited HTML/React props — they're identical across all components
-      // and bloat fragments.json. MCP consumers know these exist implicitly.
-      .filter((name) => autoProps[name].source === 'local' || name in documentedProps)
-      .map((name) => {
-      const documented = documentedProps[name];
-      const auto = autoProps[name];
-
-      return [
-        name,
-        {
-          type: auto.typeKind,
-          description: documented?.description ?? auto.description ?? "",
-          default: auto.default !== undefined ? auto.default : documented?.default,
-          required: auto.required,
-          values: auto.values ?? documented?.values,
-          constraints: documented?.constraints,
-        },
-      ];
-    })
-  );
-}
-
-/**
- * Auto-compile a propsSummary for the contract from extracted props.
- * Format: "variant: primary|secondary|ghost (required)"
- */
-function compilePropsSummary(props: Record<string, PropMeta>): string[] {
-  return Object.entries(props)
-    .filter(([_, p]) => p.source === 'local')
-    .map(([name, prop]) => {
-      let summary = name + ': ';
-      if (prop.values && prop.values.length > 0) {
-        summary += prop.values.join('|');
-      } else {
-        summary += prop.typeKind;
-      }
-      if (prop.default !== undefined) {
-        summary += ` (default: ${prop.default})`;
-      }
-      if (prop.required) {
-        summary += ' (required)';
-      }
-      return summary;
-    });
-}
-
-export interface BuildResult {
-  success: boolean;
-  outputPath: string;
-  fragmentCount: 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.
- */
-export async function buildFragments(
-  config: FragmentsConfig,
-  configDir: string
-): Promise<BuildResult> {
-  const files = await discoverFragmentFiles(config, configDir);
-  const errors: Array<{ file: string; error: string }> = [];
-  const warnings: Array<{ file: string; warning: string }> = [];
-  const fragments: CompiledFragmentsFile["fragments"] = {};
-
-  // Create a persistent extractor — shared LanguageService across all fragments
-  // Try to find a tsconfig.json in the config directory
-  const tsconfigCandidates = [
-    resolve(configDir, 'tsconfig.json'),
-    resolve(configDir, '..', 'tsconfig.json'),
-  ];
-  const tsconfigPath = tsconfigCandidates.find((p) => existsSync(p));
-  const extractor = createComponentExtractor(tsconfigPath);
-
-  for (const file of files) {
-    try {
-      // Read file content as text
-      const content = await readFile(file.absolutePath, "utf-8");
-
-      // Skip files that don't contain defineFragment() — e.g., story files
-      // that were accidentally included in the config
-      if (!content.includes("defineFragment")) {
-        warnings.push({
-          file: file.relativePath,
-          warning: "No defineFragment() call found",
-        });
-        continue;
-      }
-
-      // Parse using AST (no execution)
-      const parsed = parseFragmentFile(content, file.relativePath);
-
-      // Collect warnings
-      for (const warning of parsed.warnings) {
-        warnings.push({ file: file.relativePath, warning });
-      }
-
-      // Check for required fields
-      if (!parsed.meta.name) {
-        warnings.push({
-          file: file.relativePath,
-          warning: "Missing meta.name in fragment definition — skipped",
-        });
-        continue;
-      }
-
-      const documentedProps = normalizeParsedProps(parsed.props);
-      let mergedProps = documentedProps;
-
-      const componentExportName = parsed.componentName ?? parsed.meta.name;
-      const componentSourcePath = resolveComponentSourcePath(
-        file.absolutePath,
-        parsed.componentImport
-      );
-
-      // Extract full component metadata using persistent LanguageService
-      let extractedMeta: ComponentMeta | null = null;
-      if (componentExportName && componentSourcePath) {
-        try {
-          extractedMeta = extractor.extract(componentSourcePath, componentExportName);
-        } catch {
-          // Extraction failure is non-fatal — fall back to documented props
-        }
-
-        if (extractedMeta) {
-          const autoProps = extractedMeta.props;
-          const hasAutoProps = Object.keys(autoProps).length > 0;
-
-          if (hasAutoProps) {
-            const removedDocumentedProps = Object.keys(documentedProps).filter(
-              (propName) => !(propName in autoProps)
-            );
-
-            if (removedDocumentedProps.length > 0) {
-              warnings.push({
-                file: file.relativePath,
-                warning: `Removed ${removedDocumentedProps.length} documented props not present in source API: ${removedDocumentedProps.join(", ")}`,
-              });
-            }
-
-            mergedProps = mergeDocumentedAndAutoProps(documentedProps, autoProps);
-          } else if (Object.keys(documentedProps).length > 0) {
-            warnings.push({
-              file: file.relativePath,
-              warning: "Auto-props extraction returned no props; falling back to documented props",
-            });
-          }
-        }
-      } else if (!componentExportName) {
-        warnings.push({
-          file: file.relativePath,
-          warning: "Unable to resolve component export name for auto-props extraction",
-        });
-      } else if (!componentSourcePath) {
-        warnings.push({
-          file: file.relativePath,
-          warning: `Unable to resolve component source path from import: ${parsed.componentImport ?? "unknown"}`,
-        });
-      }
-
-      // Auto-compile contract if not manually authored
-      let contract = parsed.contract;
-      if (!contract?.propsSummary && extractedMeta) {
-        const summary = compilePropsSummary(extractedMeta.props);
-        if (summary.length > 0) {
-          contract = { ...contract, propsSummary: summary };
-        }
-      }
-
-      // Auto-enrich AI metadata from extractor's composition data
-      let ai = parsed.ai;
-      if (extractedMeta?.composition) {
-        const comp = extractedMeta.composition;
-        ai = {
-          compositionPattern: comp.pattern,
-          subComponents: comp.parts.map((p) => p.name),
-          ...ai, // Manually authored ai fields take precedence
-        };
-      }
-
-      // Build compiled fragment from parsed metadata
-      const compiled: CompiledFragment = {
-        filePath: file.relativePath,
-        meta: {
-          name: parsed.meta.name,
-          description: parsed.meta.description ?? "",
-          category: parsed.meta.category ?? "Uncategorized",
-          status: parsed.meta.status,
-          tags: parsed.meta.tags,
-          since: parsed.meta.since,
-          ...(parsed.meta.dependencies && { dependencies: parsed.meta.dependencies }),
-          figma: parsed.meta.figma,
-        },
-        usage: {
-          when: parsed.usage.when ?? [],
-          whenNot: parsed.usage.whenNot ?? [],
-          guidelines: parsed.usage.guidelines,
-          accessibility: parsed.usage.accessibility,
-        },
-        props: mergedProps,
-        relations: parsed.relations.map((rel) => ({
-          component: rel.component,
-          relationship: rel.relationship as
-            | "alternative"
-            | "sibling"
-            | "parent"
-            | "child"
-            | "composition",
-          note: rel.note,
-        })),
-        variants: parsed.variants.map((v) => ({
-          name: v.name,
-          description: v.description,
-          ...(v.code && { code: v.code }),
-          ...(v.figma && { figma: v.figma }),
-          ...(v.args && { args: v.args }),
-        })),
-        // Include AI metadata (auto-enriched or manual)
-        ...(ai && { ai }),
-        // Include contract metadata (auto-compiled or manual)
-        ...(contract && { contract }),
-      };
-
-      fragments[parsed.meta.name] = compiled;
-    } catch (error) {
-      errors.push({
-        file: file.relativePath,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  extractor.dispose();
-
-  // Discover and compile block files
-  const blocks: Record<string, CompiledBlock> = {};
-  try {
-    const blockFiles = await discoverBlockFiles(configDir, config.exclude);
-    for (const file of blockFiles) {
-      try {
-        // loadFragmentFile uses esbuild to bundle+evaluate, returns default export
-        // CJS/ESM interop may double-wrap the default export
-        let raw = await loadFragmentFile(file.absolutePath) as unknown as Record<string, unknown> | null;
-        // Unwrap double-default from CJS interop
-        if (raw && 'default' in raw && typeof raw.default === 'object') {
-          raw = raw.default as Record<string, unknown>;
-        }
-        const def = raw;
-        if (def && typeof def === 'object' && 'name' in def && 'code' in def && 'components' in def) {
-          const compiled = compileBlock(def as unknown as BlockDefinition, file.relativePath);
-          blocks[compiled.name] = compiled;
-        }
-      } catch (error) {
-        warnings.push({
-          file: file.relativePath,
-          warning: `Failed to load block: ${error instanceof Error ? error.message : String(error)}`,
-        });
-      }
-    }
-  } catch {
-    // Block discovery failure is non-fatal
-  }
-
-  // Discover and extract design tokens from SCSS/CSS files
-  let tokens: CompiledTokenData | undefined;
-  try {
-    const tokenPatterns = config.tokens?.include;
-    const tokenFiles = await discoverTokenFiles(configDir, tokenPatterns, config.exclude);
-    if (tokenFiles.length > 0) {
-      // Merge tokens from all discovered files
-      const mergedCategories: Record<string, Array<{ name: string; value?: string; description?: string }>> = {};
-      let prefix = '--';
-      let total = 0;
-
-      // Read all file contents first for cross-file SCSS variable resolution
-      const fileContents: Array<{ content: string; path: string }> = [];
-      for (const file of tokenFiles) {
-        const content = await readFile(file.absolutePath, 'utf-8');
-        fileContents.push({ content, path: file.relativePath });
-      }
-
-      // Concatenate all contents so parseTokenFile can resolve SCSS vars across files
-      const allContent = fileContents.map((f) => f.content).join('\n');
-
-      for (const { content, path } of fileContents) {
-        // Parse with the combined content to enable cross-file SCSS var resolution
-        const parsed = parseTokenFile(allContent, path);
-        // But only use tokens from THIS file's content to avoid duplicates
-        const fileParsed = parseTokenFile(content, path);
-        prefix = fileParsed.prefix;
-        total += fileParsed.total;
-        for (const [cat, catTokens] of Object.entries(fileParsed.categories)) {
-          if (!mergedCategories[cat]) {
-            mergedCategories[cat] = [];
-          }
-          for (const t of catTokens) {
-            // Deduplicate by name
-            if (!mergedCategories[cat].some((e) => e.name === t.name)) {
-              // Use resolved value from the combined parse if available
-              const combinedToken = Object.values(parsed.categories)
-                .flat()
-                .find((ct) => ct.name === t.name);
-              const resolvedValue = combinedToken?.resolvedValue ?? t.resolvedValue;
-
-              mergedCategories[cat].push({
-                name: t.name,
-                ...(resolvedValue
-                  ? { value: resolvedValue }
-                  : t.value ? { value: t.value } : {}),
-                description: t.description,
-              });
-            }
-          }
-        }
-      }
-
-      // Sass compilation fallback: resolve tokens the regex parser couldn't handle
-      if (total > 0) {
-        const allTokens = Object.values(mergedCategories).flat();
-        const unresolved = allTokens.filter(
-          t => t.value && (t.value.includes('#{') || t.value.includes('$'))
-        );
-
-        if (unresolved.length > 0 && tokenFiles.length > 0) {
-          // Determine the tokens directory from the first discovered file
-          const tokensDir = resolve(configDir, tokenFiles[0].relativePath, '..');
-          const sassResolved = await resolveTokensWithSass(
-            unresolved as Array<{ name: string; value: string }>,
-            tokensDir,
-          );
-
-          // Merge sass-resolved values back into the categories
-          if (sassResolved.size > 0) {
-            for (const catTokens of Object.values(mergedCategories)) {
-              for (const token of catTokens) {
-                const resolved = sassResolved.get(token.name);
-                if (resolved && token.value && (token.value.includes('#{') || token.value.includes('$'))) {
-                  token.value = resolved;
-                }
-              }
-            }
-          }
-        }
-
-        tokens = { prefix, total, categories: mergedCategories };
-      }
-    }
-  } catch {
-    // Token extraction failure is non-fatal
-  }
-
-  // Read package name for import statements
-  let packageName: string | undefined;
-  const pkgJsonPath = resolve(configDir, "package.json");
-  if (existsSync(pkgJsonPath)) {
-    try {
-      const pkg = JSON.parse(await readFile(pkgJsonPath, "utf-8"));
-      if (pkg.name) packageName = pkg.name;
-    } catch {
-      // Non-fatal
-    }
-  }
-
-  // Build component graph for AI structural queries
-  // Derive component directory from configDir (typically src/components/)
-  const componentDir = resolve(configDir, "src", "components");
-  let graphData: ReturnType<typeof serializeGraph> | undefined;
-  try {
-    const graphResult = await buildComponentGraph(fragments, blocks, componentDir);
-
-    // Auto-enrich fragments with detected metadata
-    for (const [name, fragment] of Object.entries(fragments)) {
-      const detected = graphResult.autoDetected.get(name);
-      if (!detected) continue;
-
-      if (!fragment.ai) fragment.ai = {};
-      if (!fragment.ai.subComponents && detected.subComponents) {
-        fragment.ai.subComponents = detected.subComponents;
-      }
-      if (!fragment.ai.compositionPattern && detected.compositionPattern) {
-        fragment.ai.compositionPattern = detected.compositionPattern;
-      }
-      if (!fragment.ai.commonPatterns && detected.commonPatterns) {
-        fragment.ai.commonPatterns = detected.commonPatterns;
-      }
-      if (!fragment.ai.requiredChildren && detected.requiredChildren) {
-        fragment.ai.requiredChildren = detected.requiredChildren;
-      }
-    }
-
-    // Report drift warnings
-    for (const w of graphResult.warnings) {
-      warnings.push({ file: "graph", warning: w });
-    }
-
-    graphData = serializeGraph(graphResult.graph);
-  } catch (error) {
-    warnings.push({
-      file: "graph",
-      warning: `Graph extraction failed: ${error instanceof Error ? error.message : String(error)}`,
-    });
-  }
-
-  // Measure performance budgets if configured
-  let performanceSummary: PerformanceSummary | undefined;
-  if (config.performance) {
-    try {
-      const perfConfig = resolvePerformanceConfig(config.performance);
-      const perfResult = await measureBundleSizes(fragments, configDir, {
-        perfConfig,
-      });
-
-      const tiers: Record<string, number> = { lightweight: 0, moderate: 0, heavy: 0 };
-      let overBudgetCount = 0;
-
-      for (const [name, measurement] of perfResult.measurements) {
-        const fragment = fragments[name];
-        const contractBudget = fragment?.contract?.performanceBudget as number | undefined;
-        const perfData = toPerformanceData(measurement, perfConfig, contractBudget);
-        fragment.performance = perfData;
-        tiers[perfData.complexity]++;
-        if (perfData.overBudget) overBudgetCount++;
-      }
-
-      performanceSummary = {
-        preset: perfConfig.preset,
-        budget: perfConfig.budgets.bundleSize,
-        total: perfResult.measurements.size,
-        overBudget: overBudgetCount,
-        tiers,
-      };
-
-      for (const err of perfResult.errors) {
-        warnings.push({
-          file: 'performance',
-          warning: `Could not measure ${err.name}: ${err.error}`,
-        });
-      }
-    } catch (error) {
-      warnings.push({
-        file: 'performance',
-        warning: `Performance measurement failed: ${error instanceof Error ? error.message : String(error)}`,
-      });
-    }
-  }
-
-  const output: CompiledFragmentsFile = {
-    version: "1.0.0",
-    generatedAt: new Date().toISOString(),
-    ...(packageName && { packageName }),
-    fragments,
-    ...(Object.keys(blocks).length > 0 && { blocks }),
-    ...(tokens && { tokens }),
-    ...(graphData && { graph: graphData }),
-    ...(performanceSummary && { performanceSummary }),
-  };
-
-  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
-  await writeFile(outputPath, JSON.stringify(output));
-
-  return {
-    success: errors.length === 0,
-    outputPath,
-    fragmentCount: Object.keys(fragments).length,
-    errors,
-    warnings,
-  };
-}
-
-/**
- * Result of building the .fragments directory
- */
-export interface FragmentsBuildResult {
-  success: boolean;
-  indexPath: string;
-  registryPath: string;
-  contextPath: string;
-  componentCount: number;
-  errors: Array<{ file: string; error: string }>;
-  warnings: Array<{ file: string; warning: string }>;
-}
-
-/**
- * Build the .fragments/ directory with index.json, registry.json, and context.md
- *
- * This generates:
- * - .fragments/index.json - Minimal name → path mapping (tiny, for quick lookups)
- * - .fragments/registry.json - Component index with paths and enrichment references
- * - .fragments/context.md - AI-ready consolidated context file
- */
-export async function buildFragmentsDir(
-  config: FragmentsConfig,
-  configDir: string
-): Promise<FragmentsBuildResult> {
-  const fragmentsDir = join(configDir, BRAND.dataDir);
-  const componentsDir = join(fragmentsDir, BRAND.componentsDir);
-
-  // Create directories
-  await mkdir(fragmentsDir, { recursive: true });
-  await mkdir(componentsDir, { recursive: true });
-
-  // Generate registry with config options
-  const registryResult = await generateRegistry({
-    projectRoot: configDir,
-    componentPatterns: config.components || ["src/**/*.tsx", "src/**/*.ts"],
-    storyPatterns: config.include || ["src/**/*.stories.tsx"],
-    fragmentsDir,
-    registryOptions: config.registry || {},
-  });
-
-  const errors = [...registryResult.errors];
-  const warnings = [...registryResult.warnings];
-
-  // Write index.json (minimal name → path)
-  const indexPath = join(fragmentsDir, "index.json");
-  await writeFile(indexPath, JSON.stringify(registryResult.index, null, 2));
-
-  // Write registry.json (full metadata)
-  const registryPath = join(fragmentsDir, BRAND.registryFile);
-  await writeFile(registryPath, JSON.stringify(registryResult.registry, null, 2));
-
-  // Generate context.md - focus on semantic knowledge, skip props (AI can read source)
-  const contextResult = generateContextMd(registryResult.registry, {
-    format: "markdown",
-    compact: false,
-    include: {
-      props: false, // AI can read TypeScript directly
-      relations: true,
-      code: false,
-    },
-  });
-
-  // Write context.md
-  const contextPath = join(fragmentsDir, BRAND.contextFile);
-  await writeFile(contextPath, contextResult.content);
-
-  return {
-    success: errors.length === 0,
-    indexPath,
-    registryPath,
-    contextPath,
-    componentCount: registryResult.registry.componentCount,
-    errors,
-    warnings,
-  };
-}