@fragments-sdk/cli 0.2.2

package/src/core/index.ts

@@ -0,0 +1,149 @@
+/**
+ * Browser-safe exports for @fragments/core
+ * For Node.js-only APIs (config, discovery, loader), use '@fragments/core/node'
+ */
+
+// Brand and default constants
+export { BRAND, DEFAULTS } from "./constants.js";
+export type { Brand, Defaults } from "./constants.js";
+
+// Types
+export type {
+  SegmentComponent,
+  SegmentMeta,
+  SegmentUsage,
+  PropType,
+  PropDefinition,
+  ControlType,
+  RelationshipType,
+  ComponentRelation,
+  VariantLoader,
+  PlayFunction,
+  PlayFunctionContext,
+  SegmentVariant,
+  SegmentDefinition,
+  FragmentsConfig,
+  SegmentsConfig, // @deprecated - use FragmentsConfig
+  RegistryOptions,
+  CompiledSegment,
+  CompiledSegmentsFile,
+  RecipeDefinition,
+  CompiledRecipe,
+  // Contract and provenance types
+  SegmentContract,
+  SegmentGenerated,
+  // Screenshot types
+  ScreenshotConfig,
+  ServiceConfig,
+  Viewport,
+  Theme,
+  Screenshot,
+  ScreenshotMetadata,
+  DiffResult,
+  BoundingBox,
+  BaselineInfo,
+  Manifest,
+  VerifyRequest,
+  VerifyResult,
+  // Figma property mapping types
+  FigmaPropMapping,
+  FigmaStringMapping,
+  FigmaBooleanMapping,
+  FigmaEnumMapping,
+  FigmaInstanceMapping,
+  FigmaChildrenMapping,
+  FigmaTextContentMapping,
+  // Token configuration
+  TokenConfig,
+} from "./types.js";
+
+// Token types
+export type {
+  TokenCategory,
+  DesignToken,
+  TokenRegistry,
+  TokenRegistryMeta,
+  EnhancedStyleDiffItem,
+  TokenFix,
+  TokenParseResult,
+  TokenParseError,
+  TokenMatchRequest,
+  TokenMatchResult,
+  TokenUsageSummary,
+} from "./token-types.js";
+
+// Schema validation (Zod is browser-safe)
+export {
+  segmentMetaSchema,
+  segmentUsageSchema,
+  propDefinitionSchema,
+  componentRelationSchema,
+  segmentVariantSchema,
+  segmentDefinitionSchema,
+  segmentsConfigSchema,
+  figmaPropMappingSchema,
+  // Contract and provenance schemas
+  segmentContractSchema,
+  segmentGeneratedSchema,
+  segmentBanSchema,
+  recipeDefinitionSchema,
+} from "./schema.js";
+
+// Main API
+export { defineSegment, defineFragment, compileSegment, defineRecipe, compileRecipe } from "./defineSegment.js";
+export type { InferProps } from "./defineSegment.js";
+
+// Story adapter (runtime conversion of Storybook modules)
+export {
+  storyModuleToSegment,
+  setPreviewConfig,
+  getPreviewConfig,
+  // Re-export @storybook/csf utilities
+  toId,
+  storyNameFromExport,
+  isExportStory,
+} from "./storyAdapter.js";
+export type {
+  StoryModule,
+  StoryMeta,
+  Story,
+  StoryArgType,
+  StoryContext,
+  Decorator,
+  Loader,
+  PreviewConfig,
+  CSF2Story,
+} from "./storyAdapter.js";
+
+// Context generation for AI agents
+export { generateContext } from "./context.js";
+export type { ContextOptions, ContextResult } from "./context.js";
+
+// Figma property mapping DSL
+export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
+
+// Fragment JSON types (for .fragment.json files)
+export type {
+  Fragment,
+  FragmentFigma,
+  FragmentUsage,
+  FragmentDoNotItem,
+  FragmentPattern,
+  FragmentAccessibility,
+  FragmentRelated,
+  FragmentMeta,
+  FragmentIndex,
+  FragmentRegistry,
+  RegistryComponentEntry,
+  RegistryPropEntry,
+  FragmentContextOptions,
+} from "./fragment-types.js";
+
+// Composition analysis
+export { analyzeComposition } from "./composition.js";
+export type {
+  CompositionAnalysis,
+  CompositionWarning,
+  CompositionSuggestion,
+  CompositionGuideline,
+} from "./composition.js";

package/src/core/loader.ts

@@ -0,0 +1,155 @@
+import { writeFile, unlink } from 'node:fs/promises';
+import { dirname, basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build, type Plugin } from 'esbuild';
+import type { SegmentDefinition } from './types.js';
+import { BRAND } from './constants.js';
+
+// Inline implementation of defineSegment that will be injected into bundled files
+// This allows segment files to work without @fragments/core being installed
+const DEFINE_SEGMENT_SHIM = `
+export function defineSegment(def) {
+  return def;
+}
+export function defineFragment(def) {
+  return def;
+}
+export function defineRecipe(def) {
+  return def;
+}
+`;
+
+/**
+ * Creates an esbuild plugin that replaces @fragments/core imports with an inline shim.
+ * This allows segment files to be loaded without @fragments/core being installed in the target project.
+ */
+function createSegmentsCoreShimPlugin(): Plugin {
+  return {
+    name: BRAND.vitePluginNamespace,
+    setup(build) {
+      // Intercept @fragments/core imports
+      build.onResolve({ filter: /^@fragments\/core$/ }, (args) => {
+        return {
+          path: args.path,
+          namespace: BRAND.vitePluginNamespace,
+        };
+      });
+
+      // Return the shim content
+      build.onLoad({ filter: /.*/, namespace: BRAND.vitePluginNamespace }, () => {
+        return {
+          contents: DEFINE_SEGMENT_SHIM,
+          loader: 'js',
+        };
+      });
+    },
+  };
+}
+
+/**
+ * Load a segment file, handling TSX/TS transformation automatically.
+ * Uses esbuild to bundle and transform TypeScript/JSX before importing.
+ */
+export async function loadSegmentFile(
+  absolutePath: string
+): Promise<SegmentDefinition | null> {
+  const ext = absolutePath.split('.').pop()?.toLowerCase();
+  const needsTransform = ext === 'tsx' || ext === 'ts' || ext === 'jsx';
+
+  if (!needsTransform) {
+    // Plain JS file, import directly
+    const fileUrl = pathToFileURL(absolutePath).href;
+    const module = await import(fileUrl);
+    return module.default ?? null;
+  }
+
+  // Bundle the file with all its local dependencies
+  const sourceDir = dirname(absolutePath);
+  const baseName = basename(absolutePath, `.${ext}`);
+  // Use .cjs extension to ensure CommonJS evaluation
+  const tempFile = join(sourceDir, `.${baseName}.segments-temp-${Date.now()}.cjs`);
+
+  try {
+    // Use esbuild to bundle the segment file
+    // We inject a shim for @fragments/core so it doesn't need to be installed
+    // Using CommonJS format to avoid ESM/CJS interop issues with node_modules
+    await build({
+      entryPoints: [absolutePath],
+      outfile: tempFile,
+      bundle: true,
+      format: 'cjs', // Use CommonJS to avoid ESM issues with lodash, etc.
+      target: 'es2022',
+      jsx: 'automatic',
+      platform: 'node',
+      plugins: [createSegmentsCoreShimPlugin()],
+      // Externalize all node_modules - we only need segment metadata, not component code
+      packages: 'external',
+      // Also explicitly list patterns for nested imports
+      external: [
+        // React and its subpaths
+        'react',
+        'react-dom',
+        'react/*',
+        'react-dom/*',
+      ],
+      // Don't emit sourcemaps for temp files
+      sourcemap: false,
+      // Suppress warnings
+      logLevel: 'silent',
+      // Use loader to ignore style imports
+      loader: {
+        '.scss': 'empty',
+        '.css': 'empty',
+        '.svg': 'empty',
+        '.png': 'empty',
+        '.jpg': 'empty',
+        '.jpeg': 'empty',
+        '.gif': 'empty',
+        '.woff': 'empty',
+        '.woff2': 'empty',
+        '.ttf': 'empty',
+        '.eot': 'empty',
+      },
+    });
+
+    const fileUrl = pathToFileURL(tempFile).href;
+    const module = await import(fileUrl);
+    return module.default ?? null;
+  } finally {
+    // Clean up temp file
+    try {
+      await unlink(tempFile);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Load multiple segment files in parallel with error handling.
+ */
+export async function loadSegmentFiles(
+  absolutePaths: string[]
+): Promise<Map<string, SegmentDefinition | Error>> {
+  const results = new Map<string, SegmentDefinition | Error>();
+
+  await Promise.all(
+    absolutePaths.map(async (path) => {
+      try {
+        const segment = await loadSegmentFile(path);
+        if (segment) {
+          results.set(path, segment);
+        } else {
+          results.set(path, new Error('No default export found'));
+        }
+      } catch (error) {
+        results.set(
+          path,
+          error instanceof Error ? error : new Error(String(error))
+        );
+      }
+    })
+  );
+
+  return results;
+}

package/src/core/node.ts

@@ -0,0 +1,63 @@
+/**
+ * Node.js-only exports for @fragments/core
+ * These use Node.js APIs and cannot be used in the browser.
+ */
+
+// Config
+export { loadConfig, findConfigFile } from './config.js';
+
+// Discovery
+export {
+  discoverSegmentFiles,
+  discoverRecipeFiles,
+  discoverComponentFiles,
+  extractComponentName,
+  // New: Component discovery from source files (no segment files needed)
+  discoverComponentsFromSource,
+  discoverComponentsFromBarrel,
+  discoverAllComponents,
+} from './discovery.js';
+export type { DiscoveredFile, DiscoveredComponent } from './discovery.js';
+
+// Loader (TSX/TS support)
+export { loadSegmentFile, loadSegmentFiles } from './loader.js';
+
+// AST Parser (no execution, static analysis only)
+export { parseSegmentFile } from './parser.js';
+export type { ParsedSegmentMetadata } from './parser.js';
+
+// Preview loader (Storybook .storybook/preview.tsx support)
+export {
+  findPreviewConfigPath,
+  findStorybookDir,
+  loadPreviewConfig,
+  autoLoadPreviewConfig,
+  generatePreviewModule,
+} from './previewLoader.js';
+
+// Generators (registry, context)
+export {
+  extractPropsFromFile,
+  extractPropsFromSource,
+  generateRegistry,
+  resolveComponentPath,
+  getComponentsByCategory,
+  generateContextMd,
+} from './generators/index.js';
+export type {
+  ExtractedProps,
+  RegistryGeneratorOptions,
+  RegistryGeneratorResult,
+  ContextGeneratorResult,
+} from './generators/index.js';
+
+// Import analyzer (AST-based component relationship detection)
+export {
+  analyzeFileImports,
+  buildImportGraph,
+  getImportedBy,
+} from './importAnalyzer.js';
+export type {
+  ComponentImport,
+  ImportAnalysisResult,
+} from './importAnalyzer.js';