@3fn/core 14.0.0 → 15.0.0

package/src/build/workflow/README.md

@@ -1,327 +0,0 @@
-# Build Workflow Module
-
-The workflow module provides development workflow integration for the Cross-Platform Build System, including source map generation, build modes, CI/CD integration, and configuration helpers.
-
-## Source Map Generation
-
-Source maps enable debugging of generated platform-specific code back to original token definitions.
-
-### Features
-
-- **iOS Source Maps**: DWARF debug information for Swift Package builds
-- **Android Source Maps**: Kotlin source maps for debugging
-- **Web Source Maps**: Standard JavaScript Source Map v3 format
-- **Inline/External**: Support for both inline and external source map formats
-- **Source Content**: Optional embedding of source content in maps
-
-### Usage
-
-```typescript
-import { SourceMapGenerator } from '@3fn/core/build/workflow';
-
-const generator = new SourceMapGenerator();
-
-// Generate source map for Web build
-const config = {
-  platform: 'web',
-  options: {
-    enabled: true,
-    includeContent: true,
-    format: 'external',
-  },
-  outputPath: '/output/web',
-  sourcePaths: ['src/tokens/SpacingTokens.ts', 'src/tokens/ColorTokens.ts'],
-};
-
-const result = generator.generateWebSourceMap(config);
-
-if (result.success) {
-  console.log(`Source map generated: ${result.sourceMapPath}`);
-}
-```
-
-### Platform-Specific Generation
-
-#### iOS (Swift)
-
-```typescript
-const iosConfig = {
-  platform: 'ios',
-  options: {
-    enabled: true,
-    includeContent: true,
-    format: 'external', // Generates .dSYM bundle
-  },
-  outputPath: '/output/ios',
-  sourcePaths: ['src/tokens/SpacingTokens.ts'],
-};
-
-const result = generator.generateiOSSourceMap(iosConfig);
-// Result: /output/ios/DesignTokens.dSYM
-```
-
-#### Android (Kotlin)
-
-```typescript
-const androidConfig = {
-  platform: 'android',
-  options: {
-    enabled: true,
-    includeContent: true,
-    format: 'external', // Generates .map file
-  },
-  outputPath: '/output/android',
-  sourcePaths: ['src/tokens/SpacingTokens.ts'],
-};
-
-const result = generator.generateAndroidSourceMap(androidConfig);
-// Result: /output/android/DesignTokens.map
-```
-
-#### Web (TypeScript/JavaScript)
-
-```typescript
-const webConfig = {
-  platform: 'web',
-  options: {
-    enabled: true,
-    includeContent: true,
-    format: 'inline', // Inline base64 source map
-  },
-  outputPath: '/output/web',
-  sourcePaths: ['src/tokens/SpacingTokens.ts'],
-};
-
-const result = generator.generateWebSourceMap(webConfig);
-// Result: Inline source map in generated code
-```
-
-### Multi-Platform Generation
-
-```typescript
-const configs = [
-  {
-    platform: 'ios',
-    options: { enabled: true, includeContent: true, format: 'external' },
-    outputPath: '/output/ios',
-    sourcePaths: ['src/tokens/SpacingTokens.ts'],
-  },
-  {
-    platform: 'android',
-    options: { enabled: true, includeContent: true, format: 'external' },
-    outputPath: '/output/android',
-    sourcePaths: ['src/tokens/SpacingTokens.ts'],
-  },
-  {
-    platform: 'web',
-    options: { enabled: true, includeContent: true, format: 'external' },
-    outputPath: '/output/web',
-    sourcePaths: ['src/tokens/SpacingTokens.ts'],
-  },
-];
-
-const results = generator.generateSourceMaps(configs);
-// Generates source maps for all platforms
-```
-
-### Default Options
-
-Get platform-appropriate defaults based on build mode:
-
-```typescript
-// Development mode: full source maps with content
-const devOptions = generator.getDefaultOptions('web', 'development');
-// { enabled: true, includeContent: true, format: 'external' }
-
-// Production mode: minimal source maps
-const prodOptions = generator.getDefaultOptions('web', 'production');
-// { enabled: true, includeContent: false, format: 'external' }
-```
-
-## Source Map Options
-
-### SourceMapOptions
-
-```typescript
-interface SourceMapOptions {
-  /** Enable source map generation */
-  enabled: boolean;
-  
-  /** Include source content in source map */
-  includeContent: boolean;
-  
-  /** Source map output format */
-  format: 'inline' | 'external';
-  
-  /** Source root path for source map */
-  sourceRoot?: string;
-}
-```
-
-### PlatformSourceMapConfig
-
-```typescript
-interface PlatformSourceMapConfig {
-  /** Target platform */
-  platform: Platform;
-  
-  /** Source map options */
-  options: SourceMapOptions;
-  
-  /** Output path for source maps */
-  outputPath: string;
-  
-  /** Source file paths to include */
-  sourcePaths: string[];
-}
-```
-
-### SourceMapResult
-
-```typescript
-interface SourceMapResult {
-  /** Platform for which source map was generated */
-  platform: Platform;
-  
-  /** Path to generated source map file (external format) */
-  sourceMapPath?: string;
-  
-  /** Inline source map content (inline format) */
-  inlineSourceMap?: string;
-  
-  /** Source files included in map */
-  sourceFiles: string[];
-  
-  /** Generation success status */
-  success: boolean;
-  
-  /** Error message if generation failed */
-  error?: string;
-}
-```
-
-## Integration with Build System
-
-Source maps integrate seamlessly with the build orchestrator:
-
-```typescript
-import { BuildOrchestrator, SourceMapGenerator } from '@3fn/core/build';
-
-const orchestrator = new BuildOrchestrator();
-const sourceMapGenerator = new SourceMapGenerator();
-
-// Configure build with source maps
-const buildConfig = {
-  platforms: ['ios', 'android', 'web'],
-  mode: 'development',
-  sourceMaps: true, // Enable source maps
-  outputDir: '/output',
-};
-
-// Build generates source maps automatically
-const results = await orchestrator.build(buildConfig);
-```
-
-## Best Practices
-
-### Development Mode
-
-- Enable source maps with full content
-- Use external format for better debugging
-- Include all source files
-
-```typescript
-const devConfig = {
-  enabled: true,
-  includeContent: true,
-  format: 'external',
-};
-```
-
-### Production Mode
-
-- Enable source maps but exclude content
-- Use external format for security
-- Consider hosting source maps separately
-
-```typescript
-const prodConfig = {
-  enabled: true,
-  includeContent: false,
-  format: 'external',
-};
-```
-
-### CI/CD Integration
-
-```typescript
-// Generate source maps during CI build
-const ciConfig = {
-  platform: 'web',
-  options: {
-    enabled: process.env.CI === 'true',
-    includeContent: false,
-    format: 'external',
-  },
-  outputPath: process.env.OUTPUT_DIR,
-  sourcePaths: getSourceFiles(),
-};
-```
-
-## Platform-Specific Considerations
-
-### iOS (Swift)
-
-- Uses DWARF debug information format
-- Generates `.dSYM` bundle for debugging
-- Compatible with Xcode debugger
-- Source maps enable breakpoint debugging in original TypeScript
-
-### Android (Kotlin)
-
-- Uses Kotlin source map format
-- Generates `.map` file alongside compiled code
-- Compatible with Android Studio debugger
-- Enables stack trace mapping to original sources
-
-### Web (JavaScript/TypeScript)
-
-- Uses Source Map v3 standard format
-- Inline format embeds map in generated code
-- External format creates separate `.js.map` file
-- Compatible with browser DevTools and error tracking services
-
-## Error Handling
-
-Source map generation handles errors gracefully:
-
-```typescript
-const result = generator.generateWebSourceMap(config);
-
-if (!result.success) {
-  console.error(`Source map generation failed: ${result.error}`);
-  // Continue with build even if source maps fail
-}
-```
-
-## Future Enhancements
-
-- **Build Mode Support**: Automatic configuration based on development/production mode
-- **CI/CD Integration**: Automated source map generation in CI pipelines
-- **Config Helpers**: Utilities for common source map configurations
-- **Source Map Validation**: Verify source map correctness and completeness
-
-## Related Modules
-
-- **BuildOrchestrator**: Main build coordination
-- **Platform Builders**: iOS, Android, Web builders
-- **Token Integration**: Token system integration
-- **Validation**: Cross-platform validation
-
-## Requirements
-
-Implements requirements from F2 specification:
-
-- **Requirement 8.5**: Source map generation for debugging support
-- **Cross-Platform Consistency**: Consistent source map generation across platforms
-- **Development Workflow**: Integration with development and production workflows

package/src/build/workflow/SourceMapGenerator.ts

@@ -1,362 +0,0 @@
-/**
- * Source Map Generator
- * 
- * Generates source maps for platform-specific builds to enable debugging
- * of generated code back to original token definitions.
- * 
- * @module build/workflow/SourceMapGenerator
- */
-
-import { Platform } from '../types/Platform';
-
-/**
- * Source map configuration options
- */
-export interface SourceMapOptions {
-  /** Enable source map generation */
-  enabled: boolean;
-  /** Include source content in source map */
-  includeContent: boolean;
-  /** Source map output format */
-  format: 'inline' | 'external';
-  /** Source root path for source map */
-  sourceRoot?: string;
-}
-
-/**
- * Platform-specific source map configuration
- */
-export interface PlatformSourceMapConfig {
-  platform: Platform;
-  options: SourceMapOptions;
-  /** Output path for source maps */
-  outputPath: string;
-  /** Source file paths to include */
-  sourcePaths: string[];
-}
-
-/**
- * Generated source map result
- */
-export interface SourceMapResult {
-  platform: Platform;
-  /** Path to generated source map file */
-  sourceMapPath?: string;
-  /** Inline source map content (if format is 'inline') */
-  inlineSourceMap?: string;
-  /** Source files included in map */
-  sourceFiles: string[];
-  success: boolean;
-  error?: string;
-}
-
-/**
- * Source map mapping entry
- */
-interface SourceMapping {
-  generatedLine: number;
-  generatedColumn: number;
-  sourceLine: number;
-  sourceColumn: number;
-  sourceFile: string;
-  name?: string;
-}
-
-/**
- * SourceMapGenerator generates source maps for platform-specific builds
- * to enable debugging of generated code back to original sources.
- */
-export class SourceMapGenerator {
-  /**
-   * Generate source map for iOS Swift build
-   */
-  generateiOSSourceMap(config: PlatformSourceMapConfig): SourceMapResult {
-    if (!config.options.enabled) {
-      return {
-        platform: 'ios',
-        sourceFiles: [],
-        success: true,
-      };
-    }
-
-    try {
-      // Swift source maps use DWARF debug information
-      // Generate debug symbol mapping for Swift Package
-      const mappings = this.generateSwiftDebugMappings(config.sourcePaths);
-      
-      if (config.options.format === 'inline') {
-        return {
-          platform: 'ios',
-          inlineSourceMap: this.encodeSwiftDebugInfo(mappings),
-          sourceFiles: config.sourcePaths,
-          success: true,
-        };
-      }
-
-      // External source map for Swift (dSYM bundle)
-      const sourceMapPath = `${config.outputPath}/DesignTokens.dSYM`;
-      
-      return {
-        platform: 'ios',
-        sourceMapPath,
-        sourceFiles: config.sourcePaths,
-        success: true,
-      };
-    } catch (error) {
-      return {
-        platform: 'ios',
-        sourceFiles: [],
-        success: false,
-        error: error instanceof Error ? error.message : 'Unknown error generating iOS source map',
-      };
-    }
-  }
-
-  /**
-   * Generate source map for Android Kotlin build
-   */
-  generateAndroidSourceMap(config: PlatformSourceMapConfig): SourceMapResult {
-    if (!config.options.enabled) {
-      return {
-        platform: 'android',
-        sourceFiles: [],
-        success: true,
-      };
-    }
-
-    try {
-      // Kotlin source maps for debugging
-      const mappings = this.generateKotlinSourceMappings(config.sourcePaths);
-      
-      if (config.options.format === 'inline') {
-        return {
-          platform: 'android',
-          inlineSourceMap: this.encodeKotlinSourceMap(mappings),
-          sourceFiles: config.sourcePaths,
-          success: true,
-        };
-      }
-
-      // External source map for Kotlin
-      const sourceMapPath = `${config.outputPath}/DesignTokens.map`;
-      
-      return {
-        platform: 'android',
-        sourceMapPath,
-        sourceFiles: config.sourcePaths,
-        success: true,
-      };
-    } catch (error) {
-      return {
-        platform: 'android',
-        sourceFiles: [],
-        success: false,
-        error: error instanceof Error ? error.message : 'Unknown error generating Android source map',
-      };
-    }
-  }
-
-  /**
-   * Generate source map for Web TypeScript build
-   */
-  generateWebSourceMap(config: PlatformSourceMapConfig): SourceMapResult {
-    if (!config.options.enabled) {
-      return {
-        platform: 'web',
-        sourceFiles: [],
-        success: true,
-      };
-    }
-
-    try {
-      // Standard JavaScript source map (v3 format)
-      const mappings = this.generateJavaScriptSourceMappings(config.sourcePaths);
-      
-      if (config.options.format === 'inline') {
-        const sourceMap = this.generateSourceMapV3(mappings, config);
-        return {
-          platform: 'web',
-          inlineSourceMap: this.encodeInlineSourceMap(sourceMap),
-          sourceFiles: config.sourcePaths,
-          success: true,
-        };
-      }
-
-      // External source map for Web
-      const sourceMapPath = `${config.outputPath}/tokens.js.map`;
-      
-      return {
-        platform: 'web',
-        sourceMapPath,
-        sourceFiles: config.sourcePaths,
-        success: true,
-      };
-    } catch (error) {
-      return {
-        platform: 'web',
-        sourceFiles: [],
-        success: false,
-        error: error instanceof Error ? error.message : 'Unknown error generating Web source map',
-      };
-    }
-  }
-
-  /**
-   * Generate source map for specified platform
-   */
-  generateSourceMap(config: PlatformSourceMapConfig): SourceMapResult {
-    switch (config.platform) {
-      case 'ios':
-        return this.generateiOSSourceMap(config);
-      case 'android':
-        return this.generateAndroidSourceMap(config);
-      case 'web':
-        return this.generateWebSourceMap(config);
-      default:
-        return {
-          platform: config.platform,
-          sourceFiles: [],
-          success: false,
-          error: `Unsupported platform: ${config.platform}`,
-        };
-    }
-  }
-
-  /**
-   * Generate source maps for multiple platforms
-   */
-  generateSourceMaps(configs: PlatformSourceMapConfig[]): SourceMapResult[] {
-    return configs.map(config => this.generateSourceMap(config));
-  }
-
-  /**
-   * Get default source map options for platform
-   */
-  getDefaultOptions(platform: Platform, mode: 'development' | 'production'): SourceMapOptions {
-    if (mode === 'development') {
-      return {
-        enabled: true,
-        includeContent: true,
-        format: 'external',
-      };
-    }
-
-    // Production: minimal source maps
-    return {
-      enabled: true,
-      includeContent: false,
-      format: 'external',
-    };
-  }
-
-  // Private helper methods
-
-  private generateSwiftDebugMappings(sourcePaths: string[]): SourceMapping[] {
-    // Generate debug symbol mappings for Swift
-    // Maps generated Swift constants back to token definitions
-    return sourcePaths.flatMap((sourcePath, fileIndex) => {
-      return this.createMappingsForFile(sourcePath, fileIndex);
-    });
-  }
-
-  private generateKotlinSourceMappings(sourcePaths: string[]): SourceMapping[] {
-    // Generate source mappings for Kotlin
-    // Maps generated Kotlin constants back to token definitions
-    return sourcePaths.flatMap((sourcePath, fileIndex) => {
-      return this.createMappingsForFile(sourcePath, fileIndex);
-    });
-  }
-
-  private generateJavaScriptSourceMappings(sourcePaths: string[]): SourceMapping[] {
-    // Generate source mappings for JavaScript/TypeScript
-    // Maps generated JS/TS code back to token definitions
-    return sourcePaths.flatMap((sourcePath, fileIndex) => {
-      return this.createMappingsForFile(sourcePath, fileIndex);
-    });
-  }
-
-  private createMappingsForFile(sourcePath: string, fileIndex: number): SourceMapping[] {
-    // Create mappings for a single source file
-    // In a real implementation, this would parse the source file
-    // and create mappings for each token definition
-    return [
-      {
-        generatedLine: 1,
-        generatedColumn: 0,
-        sourceLine: 1,
-        sourceColumn: 0,
-        sourceFile: sourcePath,
-      },
-    ];
-  }
-
-  private generateSourceMapV3(
-    mappings: SourceMapping[],
-    config: PlatformSourceMapConfig
-  ): SourceMapV3 {
-    // Generate Source Map v3 format (standard for JavaScript)
-    return {
-      version: 3,
-      file: 'tokens.js',
-      sourceRoot: config.options.sourceRoot || '',
-      sources: config.sourcePaths,
-      sourcesContent: config.options.includeContent ? this.getSourceContents(config.sourcePaths) : undefined,
-      names: this.extractNames(mappings),
-      mappings: this.encodeMappings(mappings),
-    };
-  }
-
-  private encodeSwiftDebugInfo(mappings: SourceMapping[]): string {
-    // Encode Swift debug information
-    // In practice, this would generate DWARF debug info
-    return JSON.stringify({ format: 'swift-debug', mappings });
-  }
-
-  private encodeKotlinSourceMap(mappings: SourceMapping[]): string {
-    // Encode Kotlin source map
-    return JSON.stringify({ format: 'kotlin-sourcemap', mappings });
-  }
-
-  private encodeInlineSourceMap(sourceMap: SourceMapV3): string {
-    // Encode source map as inline base64 data URI
-    const json = JSON.stringify(sourceMap);
-    const base64 = Buffer.from(json).toString('base64');
-    return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64}`;
-  }
-
-  private getSourceContents(sourcePaths: string[]): string[] {
-    // Get source file contents for embedding in source map
-    // In practice, this would read the actual files
-    return sourcePaths.map(() => '// Source content placeholder');
-  }
-
-  private extractNames(mappings: SourceMapping[]): string[] {
-    // Extract unique names from mappings
-    const names = new Set<string>();
-    mappings.forEach(mapping => {
-      if (mapping.name) {
-        names.add(mapping.name);
-      }
-    });
-    return Array.from(names);
-  }
-
-  private encodeMappings(mappings: SourceMapping[]): string {
-    // Encode mappings using VLQ (Variable Length Quantity) format
-    // This is a simplified version - real implementation would use proper VLQ encoding
-    return mappings.map(m => `${m.generatedLine},${m.generatedColumn},${m.sourceLine},${m.sourceColumn}`).join(';');
-  }
-}
-
-/**
- * Source Map v3 format (standard for JavaScript)
- */
-interface SourceMapV3 {
-  version: 3;
-  file: string;
-  sourceRoot: string;
-  sources: string[];
-  sourcesContent?: string[];
-  names: string[];
-  mappings: string;
-}