pkg-scaffold 3.2.0 → 3.3.2

package/src/api/HeadlessAPI.js

@@ -0,0 +1,376 @@
+/**
+ * ============================================================================
+ * Headless API for pkg-scaffold v4.0.0
+ * ============================================================================
+ * Provides a programmatic interface for integrating pkg-scaffold into
+ * custom workflows, CI/CD pipelines, and third-party tools.
+ * 
+ * Features:
+ * - Full control over analysis and refactoring operations
+ * - Event-driven architecture for real-time feedback
+ * - Streaming results for large codebases
+ * - Plugin SDK integration
+ */
+
+import EventEmitter from 'events';
+import { RefactoringEngine } from '../index.js';
+
+export class HeadlessAPI extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = options;
+    this.engine = null;
+    this.analysisResults = null;
+    this.isRunning = false;
+  }
+
+  /**
+   * Initialize the API with a project context
+   * @param {string} projectRoot - Root directory of the project
+   * @param {Object} config - Configuration options
+   * @returns {Promise<void>}
+   */
+  async initialize(projectRoot, config = {}) {
+    try {
+      this.emit('initialize:start', { projectRoot });
+
+      const engineOptions = {
+        cwd: projectRoot,
+        allowAutoFix: config.autoFix !== false,
+        skipConfirm: config.skipConfirm || false,
+        verbose: config.verbose || false,
+        ...config
+      };
+
+      this.engine = new RefactoringEngine(engineOptions);
+      await this.engine.context.initialize();
+
+      this.emit('initialize:complete', {
+        projectRoot,
+        config: this.engine.context
+      });
+    } catch (error) {
+      this.emit('initialize:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Analyze the codebase without making changes
+   * @returns {Promise<Object>} Analysis results
+   */
+  async analyze() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    try {
+      this.isRunning = true;
+      this.emit('analysis:start');
+
+      // Initialize path mappings and workspace graph
+      await this.engine.pathMapper.loadMappings(this.engine.context.tsconfigFilename);
+
+      if (this.engine.context.isWorkspaceEnabled) {
+        this.emit('analysis:workspace-mapping-start');
+        await this.engine.workspaceGraph.initializeWorkspaceMesh();
+        this.emit('analysis:workspace-mapping-complete');
+      }
+
+      // Load cache manifest
+      const cacheManifest = await this.engine.cacheManager.loadCacheManifest();
+
+      // Discover source files
+      this.emit('analysis:file-discovery-start');
+      const fileList = [];
+      await this.engine.discoverSourceFiles(this.engine.context.cwd, fileList);
+      this.engine.context.metrics.totalFilesScanned = fileList.length;
+      this.emit('analysis:file-discovery-complete', { fileCount: fileList.length });
+
+      // Identify framework ecosystems
+      this.emit('analysis:framework-detection-start');
+      const activeFrameworkEcosystems = await this.engine.magicDetector.identifyActiveProjectEcosystems(
+        this.engine.context.cwd
+      );
+      this.emit('analysis:framework-detection-complete', { ecosystems: activeFrameworkEcosystems });
+
+      // Process files
+      this.emit('analysis:file-processing-start');
+      const sourceCodeFilesList = [];
+      for (const file of fileList) {
+        if (file.endsWith('package.json')) {
+          await this.engine.auditManifestSupplyChain(file);
+        } else {
+          sourceCodeFilesList.push(file);
+        }
+      }
+
+      // Initialize TypeScript program for AST analysis (required before processFile)
+      if (sourceCodeFilesList.length > 0) {
+        try {
+          this.engine.analyzer.initProgram(sourceCodeFilesList);
+        } catch (e) {
+          if (this.engine.context.verbose) {
+            console.warn('Warning: Failed to initialize TypeScript program:', e.message);
+          }
+        }
+      }
+
+      // Parallel processing
+      let parallelParseCompleted = false;
+      if (sourceCodeFilesList.length > 10) {
+        parallelParseCompleted = await this.engine.workerPool.parallelAnalyzeCodebase(
+          sourceCodeFilesList,
+          this.engine
+        );
+      }
+
+      // Sequential processing
+      for (let i = 0; i < sourceCodeFilesList.length; i++) {
+        const filePath = sourceCodeFilesList[i];
+        const node = this.engine.context.createNode(filePath);
+        const currentHash = await this.engine.cacheManager.computeHash(filePath);
+        node.contentHash = currentHash;
+
+        const isFileCached = cacheManifest[filePath] && cacheManifest[filePath].hash === currentHash;
+
+        if (isFileCached) {
+          this.engine.context.metrics.cacheHits++;
+          this.engine.hydrateNodeFromCache(node, cacheManifest[filePath]);
+        } else if (!parallelParseCompleted) {
+          this.engine.context.metrics.cacheMisses++;
+          await this.engine.analyzer.processFile(filePath, node);
+        }
+
+        this.engine.magicDetector.injectVirtualConsumerEdges(filePath, node, activeFrameworkEcosystems);
+        node.externalPackageUsage.forEach(pkg => this.engine.context.usedExternalPackages.add(pkg));
+
+        // Emit progress
+        if ((i + 1) % Math.ceil(sourceCodeFilesList.length / 10) === 0) {
+          this.emit('analysis:file-processing-progress', {
+            processed: i + 1,
+            total: sourceCodeFilesList.length,
+            percentage: Math.round(((i + 1) / sourceCodeFilesList.length) * 100)
+          });
+        }
+      }
+
+      // Link dependency graph
+      this.emit('analysis:graph-linking-start');
+      await this.engine.linkDependencyGraph();
+      this.emit('analysis:graph-linking-complete');
+
+      // Generate summary
+      this.analysisResults = this.engine.context.generateSummaryReport();
+      this.emit('analysis:complete', this.analysisResults);
+
+      this.isRunning = false;
+      return this.analysisResults;
+    } catch (error) {
+      this.isRunning = false;
+      this.emit('analysis:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Get detailed impact analysis for a specific file or export
+   * @param {string} filePath - Path to the file
+   * @param {string} symbol - Optional: specific export symbol to analyze
+   * @returns {Promise<Object>} Impact analysis results
+   */
+  async getImpactAnalysis(filePath, symbol = null) {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    try {
+      const node = this.engine.context.graph.get(filePath);
+      if (!node) {
+        throw new Error(`File not found in analysis graph: ${filePath}`);
+      }
+
+      const impact = {
+        file: filePath,
+        symbol,
+        directDependents: Array.from(node.incomingEdges),
+        dependencies: Array.from(node.outgoingEdges),
+        internalExports: symbol
+          ? [symbol]
+          : Array.from(node.internalExports.keys()),
+        externalPackages: Array.from(node.externalPackageUsage)
+      };
+
+      if (symbol) {
+        const safety = await this.engine.impactAnalyzer.verifyRefactorSafety(
+          filePath,
+          symbol,
+          this.engine.context.graph
+        );
+        impact.refactorSafety = safety;
+      }
+
+      return impact;
+    } catch (error) {
+      this.emit('impact-analysis:error', { error, filePath, symbol });
+      throw error;
+    }
+  }
+
+  /**
+   * Apply refactoring changes with automatic rollback on test failure
+   * @param {Object} changes - Changes to apply
+   * @returns {Promise<Object>} Refactoring results
+   */
+  async applyRefactoring(changes = {}) {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    if (!this.analysisResults) {
+      throw new Error('No analysis results available. Call analyze() first.');
+    }
+
+    try {
+      this.isRunning = true;
+      this.emit('refactoring:start', changes);
+
+      const refactoringResults = {
+        filesDeleted: [],
+        exportsRemoved: [],
+        dependenciesRemoved: [],
+        errors: []
+      };
+
+      await this.engine.selfHealer.runSelfHealingLifecycle(async () => {
+        // Delete dead files
+        const filesToDelete = changes.deleteDeadFiles !== false
+          ? this.analysisResults.structuralIssuesDetected.deadFiles
+          : [];
+
+        for (const relPath of filesToDelete) {
+          try {
+            const absPath = require('path').resolve(this.engine.context.cwd, relPath);
+            await this.engine.txManager.stageDeletion(absPath);
+            refactoringResults.filesDeleted.push(relPath);
+            this.emit('refactoring:file-deleted', { file: relPath });
+          } catch (error) {
+            refactoringResults.errors.push({ type: 'file-deletion', file: relPath, error: error.message });
+            this.emit('refactoring:error', { type: 'file-deletion', file: relPath, error });
+          }
+        }
+
+        // Remove unused exports
+        const exportsToRemove = changes.removeUnusedExports !== false
+          ? this.analysisResults.structuralIssuesDetected.deadExports
+          : [];
+
+        for (const unusedExport of exportsToRemove) {
+          try {
+            const absPath = require('path').resolve(this.engine.context.cwd, unusedExport.file);
+            const node = this.engine.context.graph.get(absPath);
+
+            if (node) {
+              const safety = await this.engine.impactAnalyzer.verifyRefactorSafety(
+                absPath,
+                unusedExport.symbol,
+                this.engine.context.graph
+              );
+
+              if (safety.isSafeToPrune) {
+                const nextText = await this.engine.sourceRewriter.stripNamedExportSignature(
+                  absPath,
+                  unusedExport.symbol,
+                  node.internalExports.get(unusedExport.symbol)
+                );
+
+                await this.engine.txManager.stageWrite(absPath, nextText);
+                await this.engine.typeIntegrity.synchronizeDeclarationFile(absPath, unusedExport.symbol);
+
+                refactoringResults.exportsRemoved.push(unusedExport);
+                this.emit('refactoring:export-removed', unusedExport);
+              }
+            }
+          } catch (error) {
+            refactoringResults.errors.push({
+              type: 'export-removal',
+              export: unusedExport.symbol,
+              file: unusedExport.file,
+              error: error.message
+            });
+            this.emit('refactoring:error', { type: 'export-removal', export: unusedExport, error });
+          }
+        }
+
+        // Remove unused dependencies
+        const depsToRemove = changes.removeUnusedDependencies !== false
+          ? this.analysisResults.structuralIssuesDetected.unusedDependencies
+          : [];
+
+        for (const dep of depsToRemove) {
+          try {
+            const absPath = require('path').resolve(this.engine.context.cwd, dep.manifest);
+            // TODO: Implement package.json dependency removal
+            refactoringResults.dependenciesRemoved.push(dep);
+            this.emit('refactoring:dependency-removed', dep);
+          } catch (error) {
+            refactoringResults.errors.push({
+              type: 'dependency-removal',
+              package: dep.package,
+              error: error.message
+            });
+            this.emit('refactoring:error', { type: 'dependency-removal', package: dep.package, error });
+          }
+        }
+      });
+
+      this.isRunning = false;
+      this.emit('refactoring:complete', refactoringResults);
+      return refactoringResults;
+    } catch (error) {
+      this.isRunning = false;
+      this.emit('refactoring:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Get current analysis metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+    return this.engine.context.metrics;
+  }
+
+  /**
+   * Get all registered plugins
+   * @returns {Array} Plugin instances
+   */
+  getPlugins() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+    return this.engine.context.pluginRegistry?.getPlugins() || [];
+  }
+
+  /**
+   * Get analysis results
+   * @returns {Object} Analysis results
+   */
+  getAnalysisResults() {
+    return this.analysisResults;
+  }
+
+  /**
+   * Check if API is currently running
+   * @returns {boolean}
+   */
+  isProcessing() {
+    return this.isRunning;
+  }
+}
+
+export default HeadlessAPI;

package/src/api/PluginSDK.js

@@ -0,0 +1,299 @@
+/**
+ * ============================================================================
+ * Plugin SDK for pkg-scaffold v4.0.0
+ * ============================================================================
+ * Provides utilities and helpers for developing custom plugins that extend
+ * pkg-scaffold's analysis and healing capabilities.
+ */
+
+import { BasePlugin } from '../plugins/BasePlugin.js';
+
+/**
+ * Extended plugin base class with SDK utilities
+ */
+export class PluginSDKBase extends BasePlugin {
+  constructor(context) {
+    super(context);
+    this.hooks = new Map();
+    this.transformers = [];
+    this.validators = [];
+  }
+
+  /**
+   * Register a hook for a specific lifecycle event
+   * @param {string} eventName - Event name (e.g., 'analyze:start', 'refactor:complete')
+   * @param {Function} handler - Handler function
+   */
+  registerHook(eventName, handler) {
+    if (!this.hooks.has(eventName)) {
+      this.hooks.set(eventName, []);
+    }
+    this.hooks.get(eventName).push(handler);
+  }
+
+  /**
+   * Emit a hook event
+   * @param {string} eventName - Event name
+   * @param {Object} data - Event data
+   */
+  async emitHook(eventName, data) {
+    const handlers = this.hooks.get(eventName) || [];
+    for (const handler of handlers) {
+      await handler(data);
+    }
+  }
+
+  /**
+   * Register a code transformer
+   * @param {Function} transformer - Transformer function
+   */
+  registerTransformer(transformer) {
+    this.transformers.push(transformer);
+  }
+
+  /**
+   * Register a validator
+   * @param {Function} validator - Validator function
+   */
+  registerValidator(validator) {
+    this.validators.push(validator);
+  }
+
+  /**
+   * Apply all registered transformers to a code string
+   * @param {string} code - Source code
+   * @param {string} filePath - File path
+   * @returns {Promise<string>} Transformed code
+   */
+  async applyTransformers(code, filePath) {
+    let result = code;
+    for (const transformer of this.transformers) {
+      result = await transformer(result, filePath);
+    }
+    return result;
+  }
+
+  /**
+   * Run all validators on a code string
+   * @param {string} code - Source code
+   * @param {string} filePath - File path
+   * @returns {Promise<Array>} Validation errors
+   */
+  async runValidators(code, filePath) {
+    const errors = [];
+    for (const validator of this.validators) {
+      const result = await validator(code, filePath);
+      if (result && result.length > 0) {
+        errors.push(...result);
+      }
+    }
+    return errors;
+  }
+}
+
+/**
+ * SDK utilities for plugin development
+ */
+export class PluginSDK {
+  /**
+   * Create a custom plugin class
+   * @param {Object} config - Plugin configuration
+   * @returns {Class} Plugin class
+   */
+  static createPlugin(config) {
+    return class CustomPlugin extends PluginSDKBase {
+      get name() {
+        return config.name;
+      }
+
+      getConfigFiles() {
+        return config.configFiles || [];
+      }
+
+      getRoutePatterns() {
+        return config.routePatterns || [];
+      }
+
+      getRequiredSystemContracts() {
+        return config.requiredContracts || ['default'];
+      }
+
+      async isActive(baseDir) {
+        if (config.isActive) {
+          return await config.isActive(baseDir);
+        }
+        return super.isActive(baseDir);
+      }
+
+      async initialize() {
+        if (config.initialize) {
+          await config.initialize(this.context);
+        }
+      }
+
+      async analyze(node, filePath) {
+        if (config.analyze) {
+          return await config.analyze(node, filePath, this.context);
+        }
+      }
+
+      async transform(code, filePath) {
+        if (config.transform) {
+          return await config.transform(code, filePath, this.context);
+        }
+        return code;
+      }
+
+      async validate(code, filePath) {
+        if (config.validate) {
+          return await config.validate(code, filePath, this.context);
+        }
+        return [];
+      }
+    };
+  }
+
+  /**
+   * Create a CSS-in-JS analyzer plugin
+   * @param {Object} config - Configuration for CSS-in-JS analysis
+   * @returns {Class} Plugin class
+   */
+  static createCSSInJSPlugin(config = {}) {
+    const cssLibraries = config.libraries || [
+      'styled-components',
+      'emotion',
+      '@emotion/react',
+      '@emotion/styled',
+      'linaria',
+      'vanilla-extract'
+    ];
+
+    return this.createPlugin({
+      name: config.name || 'css-in-js-analyzer',
+      configFiles: [],
+      routePatterns: [/\.(tsx?|jsx?)$/],
+      requiredContracts: [],
+
+      async analyze(node, filePath) {
+        // Track CSS-in-JS imports
+        for (const lib of cssLibraries) {
+          if (node.explicitImports.has(lib)) {
+            node.cssInJsLibraries = node.cssInJsLibraries || new Set();
+            node.cssInJsLibraries.add(lib);
+          }
+        }
+
+        // Detect styled component definitions
+        const styledPattern = /(?:styled|css|keyframes)\s*\.\w+|styled\(\w+\)/g;
+        for (const match of (node.rawCode || '').matchAll(styledPattern)) {
+          node.styledComponentUsages = node.styledComponentUsages || [];
+          node.styledComponentUsages.push(match[0]);
+        }
+      },
+
+      async validate(code, filePath) {
+        const errors = [];
+        // Check for unused CSS-in-JS definitions
+        const unusedStylesPattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:styled|css)\./g;
+        const matches = [...code.matchAll(unusedStylesPattern)];
+
+        for (const match of matches) {
+          const styleName = match[1];
+          const usagePattern = new RegExp(`\\b${styleName}\\b`);
+          if (!usagePattern.test(code.substring(match.index + match[0].length))) {
+            errors.push({
+              type: 'unused-style',
+              name: styleName,
+              line: code.substring(0, match.index).split('\n').length,
+              message: `Unused CSS-in-JS definition: ${styleName}`
+            });
+          }
+        }
+
+        return errors;
+      }
+    });
+  }
+
+  /**
+   * Create an asset tracking plugin
+   * @param {Object} config - Configuration for asset tracking
+   * @returns {Class} Plugin class
+   */
+  static createAssetTrackingPlugin(config = {}) {
+    const assetExtensions = config.extensions || [
+      '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp',
+      '.mp4', '.webm', '.mp3', '.wav',
+      '.woff', '.woff2', '.ttf', '.eot'
+    ];
+
+    return this.createPlugin({
+      name: config.name || 'asset-tracker',
+      configFiles: [],
+      routePatterns: [/\.(tsx?|jsx?)$/],
+
+      async analyze(node, filePath) {
+        node.assetReferences = node.assetReferences || new Set();
+
+        // Track asset imports
+        const assetImportPattern = /import\s+(?:\*\s+as\s+\w+|[\w\s,{}]+)\s+from\s+['"]([^'"]+(?:${assetExtensions.join('|')}))['"]/g;
+        for (const match of (node.rawCode || '').matchAll(assetImportPattern)) {
+          node.assetReferences.add(match[1]);
+        }
+
+        // Track asset requires
+        const assetRequirePattern = /require\s*\(\s*['"]([^'"]+(?:${assetExtensions.join('|')}))['"]\s*\)/g;
+        for (const match of (node.rawCode || '').matchAll(assetRequirePattern)) {
+          node.assetReferences.add(match[1]);
+        }
+
+        // Track asset URLs in strings
+        const assetUrlPattern = /['"]([^'"]*(?:${assetExtensions.join('|')}))['"]/g;
+        for (const match of (node.rawCode || '').matchAll(assetUrlPattern)) {
+          node.assetReferences.add(match[1]);
+        }
+      }
+    });
+  }
+
+  /**
+   * Create a monorepo awareness plugin
+   * @param {Object} config - Configuration for monorepo support
+   * @returns {Class} Plugin class
+   */
+  static createMonorepoPlugin(config = {}) {
+    return this.createPlugin({
+      name: config.name || 'monorepo-aware',
+      configFiles: config.configFiles || ['nx.json', 'pnpm-workspace.yaml', 'lerna.json'],
+
+      async analyze(node, filePath) {
+        // Track workspace package references
+        node.workspaceReferences = node.workspaceReferences || new Set();
+
+        // Detect workspace imports (e.g., @workspace/package-name)
+        const workspacePattern = /@[\w-]+\/[\w-]+/g;
+        for (const match of (node.rawCode || '').matchAll(workspacePattern)) {
+          node.workspaceReferences.add(match[0]);
+        }
+      }
+    });
+  }
+
+  /**
+   * Create a circular dependency detector plugin
+   * @param {Object} config - Configuration
+   * @returns {Class} Plugin class
+   */
+  static createCircularDepPlugin(config = {}) {
+    return this.createPlugin({
+      name: config.name || 'circular-dep-detector',
+
+      async analyze(node, filePath) {
+        node.potentialCycles = node.potentialCycles || [];
+        // Cycle detection will be handled by the main engine
+      }
+    });
+  }
+}
+
+export default PluginSDK;

package/src/ast/ASTAnalyzer.js

@@ -40,8 +40,9 @@ export class ASTAnalyzer {
    */
   async processFile(filePath, fileNode) {
     // Fast Path: Use OXC for rapid scanning if type checking is not strictly required for this file
-    if (this.context.fastMode) {
-      return await this.oxc.processFile(filePath, fileNode);
+    if (this.context.fastMode && this.oxc.isAvailable) {
+      const success = await this.oxc.processFile(filePath, fileNode);
+      if (success) return true;
     }
 
     if (!this.program) {