pkg-scaffold 3.2.0 → 3.3.0

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/plugins/KnipAdapter.js

@@ -0,0 +1,106 @@
+/**
+ * ============================================================================
+ * Knip Plugin Adapter for pkg-scaffold v4.0.0
+ * ============================================================================
+ * This adapter allows pkg-scaffold to use existing Knip plugins without
+ * requiring knip as a dependency. It implements the Knip plugin interface
+ * internally to ensure full compatibility.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+export class KnipAdapter {
+  constructor(context) {
+    this.context = context;
+    this.knipPlugins = new Map();
+  }
+
+  /**
+   * Discovers and loads Knip plugins from the project's node_modules
+   * or a specified directory.
+   */
+  async discoverPlugins(projectRoot) {
+    // Knip plugins are typically named 'knip-plugin-*' or are part of knip's core
+    // We look for common Knip plugin patterns in node_modules
+    const nodeModulesPath = path.join(projectRoot, 'node_modules');
+    
+    try {
+      const dirs = await fs.readdir(nodeModulesPath);
+      for (const dir of dirs) {
+        if (dir.startsWith('knip-plugin-') || dir === '@knip/plugin') {
+          await this.loadPlugin(path.join(nodeModulesPath, dir));
+        }
+      }
+    } catch (e) {
+      // node_modules not found or unreadable
+    }
+  }
+
+  /**
+   * Loads a specific Knip plugin and wraps it for pkg-scaffold
+   */
+  async loadPlugin(pluginPath) {
+    try {
+      const pluginModule = await import(pluginPath);
+      const plugin = pluginModule.default || pluginModule;
+      
+      if (plugin.name && (plugin.config || plugin.entry)) {
+        this.knipPlugins.set(plugin.name, this.wrapKnipPlugin(plugin));
+        if (this.context.verbose) {
+          console.log(`[KnipAdapter] Successfully integrated Knip plugin: ${plugin.name}`);
+        }
+      }
+    } catch (e) {
+      // Failed to load plugin
+    }
+  }
+
+  /**
+   * Wraps a Knip plugin to match the pkg-scaffold BasePlugin interface
+   */
+  wrapKnipPlugin(knipPlugin) {
+    return {
+      name: `knip-${knipPlugin.name}`,
+      isKnipWrapped: true,
+      
+      getConfigFiles: () => {
+        if (Array.isArray(knipPlugin.config)) return knipPlugin.config;
+        if (typeof knipPlugin.config === 'string') return [knipPlugin.config];
+        return [];
+      },
+      
+      getRoutePatterns: () => {
+        if (Array.isArray(knipPlugin.entry)) return knipPlugin.entry.map(e => new RegExp(e.replace('*', '.*')));
+        if (typeof knipPlugin.entry === 'string') return [new RegExp(knipPlugin.entry.replace('*', '.*'))];
+        return [];
+      },
+      
+      isActive: async (baseDir) => {
+        const configFiles = Array.isArray(knipPlugin.config) ? knipPlugin.config : [knipPlugin.config];
+        for (const file of configFiles) {
+          if (!file) continue;
+          try {
+            await fs.access(path.join(baseDir, file));
+            return true;
+          } catch {
+            continue;
+          }
+        }
+        return false;
+      },
+      
+      // Map other Knip plugin properties to pkg-scaffold
+      get: (key) => knipPlugin[key]
+    };
+  }
+
+  /**
+   * Returns all integrated Knip plugins
+   */
+  getPlugins() {
+    return Array.from(this.knipPlugins.values());
+  }
+}
+
+export default KnipAdapter;

package/src/plugins/PluginRegistry.js

@@ -1,16 +1,18 @@
 import path from 'path';
 import fs from 'fs/promises';
 import { pathToFileURL } from 'url';
+import { KnipAdapter } from './KnipAdapter.js';
 
 /**
  * Advanced Plugin Registry supporting Builtin, Custom, and Knip-style plugins.
- * Version 3.2.0: Enhanced with support for dynamic custom getters.
+ * Version 4.0.0: Enhanced with Modern Frameworks, Backend Services, and Standalone Knip Integration.
  */
 export class PluginRegistry {
     constructor(context) {
         this.context = context;
         this.plugins = new Map();
         this.config = null;
+        this.knipAdapter = new KnipAdapter(context);
     }
 
     async init(projectRoot) {
@@ -35,14 +37,21 @@ export class PluginRegistry {
         }
 
         if (this.config.supportKnipPlugins) {
-            await this.initKnipAdapter();
+            await this.initKnipAdapter(projectRoot);
         }
     }
 
     async loadBuiltinPlugins() {
+        // Core Ecosystems
         const { NextJsPlugin } = await import('./ecosystems/NextJsPlugin.js');
         const { NuxtPlugin, RemixPlugin, SvelteKitPlugin, AstroPlugin } = await import('./ecosystems/GenericPlugins.js');
         const { TypeScriptPlugin } = await import('./ecosystems/TypeScriptPlugin.js');
+        
+        // Modern Frameworks (New in v4.0)
+        const { ReactPlugin, VuePlugin, SveltePlugin, AngularPlugin } = await import('./ecosystems/ModernFrameworks.js');
+        
+        // Backend Services (New in v4.0)
+        const { GraphQLPlugin, DatabasePlugin } = await import('./ecosystems/BackendServices.js');
 
         const builtins = [
             new NextJsPlugin(this.context),
@@ -50,7 +59,13 @@ export class PluginRegistry {
             new RemixPlugin(this.context),
             new SvelteKitPlugin(this.context),
             new AstroPlugin(this.context),
-            new TypeScriptPlugin(this.context)
+            new TypeScriptPlugin(this.context),
+            new ReactPlugin(this.context),
+            new VuePlugin(this.context),
+            new SveltePlugin(this.context),
+            new AngularPlugin(this.context),
+            new GraphQLPlugin(this.context),
+            new DatabasePlugin(this.context)
         ];
 
         builtins.forEach(p => {
@@ -82,8 +97,11 @@ export class PluginRegistry {
         }
     }
 
-    async initKnipAdapter() {
+    async initKnipAdapter(projectRoot) {
         this.context.knipCompatible = true;
+        await this.knipAdapter.discoverPlugins(projectRoot);
+        const knipPlugins = this.knipAdapter.getPlugins();
+        knipPlugins.forEach(p => this.register(p));
     }
 
     register(plugin) {

package/src/plugins/ecosystems/BackendServices.js

@@ -0,0 +1,59 @@
+/**
+ * ============================================================================
+ * Backend Services Plugins for pkg-scaffold v4.0.0
+ * ============================================================================
+ * Built-in support for GraphQL, REST APIs, and Databases.
+ */
+
+import { BasePlugin } from '../BasePlugin.js';
+
+/**
+ * GraphQL Ecosystem Plugin
+ */
+export class GraphQLPlugin extends BasePlugin {
+  get name() {
+    return 'graphql';
+  }
+
+  getConfigFiles() {
+    return ['package.json', 'graphql.config.js', '.graphqlconfig'];
+  }
+
+  async isActive(baseDir) {
+    try {
+      const pkgJson = JSON.parse(await require('fs').promises.readFile(require('path').join(baseDir, 'package.json'), 'utf8'));
+      return !!(pkgJson.dependencies?.graphql || pkgJson.devDependencies?.graphql || pkgJson.dependencies?.['@apollo/client']);
+    } catch {
+      return false;
+    }
+  }
+
+  async analyze(node, filePath) {
+    // Detect GraphQL tagged templates
+    const gqlPattern = /gql\s*`([\s\S]*?)`/g;
+    const matches = node.rawCode?.match(gqlPattern) || [];
+    if (matches.length > 0) {
+      node.graphqlQueries = matches;
+    }
+  }
+}
+
+/**
+ * Database Ecosystem Plugin (Prisma, Drizzle, TypeORM)
+ */
+export class DatabasePlugin extends BasePlugin {
+  get name() {
+    return 'database';
+  }
+
+  getConfigFiles() {
+    return ['package.json', 'prisma/schema.prisma', 'drizzle.config.ts', 'ormconfig.json'];
+  }
+
+  async analyze(node, filePath) {
+    // Detect DB usage
+    if (node.explicitImports.has('@prisma/client') || node.explicitImports.has('drizzle-orm')) {
+      node.usesDatabase = true;
+    }
+  }
+}

package/src/plugins/ecosystems/ModernFrameworks.js

@@ -0,0 +1,157 @@
+/**
+ * ============================================================================
+ * Modern Frameworks Plugins for pkg-scaffold v4.0.0
+ * ============================================================================
+ * Built-in support for React, Vue, Svelte, and Angular.
+ */
+
+import { BasePlugin } from '../BasePlugin.js';
+
+/**
+ * React Ecosystem Plugin
+ */
+export class ReactPlugin extends BasePlugin {
+  get name() {
+    return 'react';
+  }
+
+  getConfigFiles() {
+    return ['package.json'];
+  }
+
+  async isActive(baseDir) {
+    try {
+      const pkgJson = JSON.parse(await require('fs').promises.readFile(require('path').join(baseDir, 'package.json'), 'utf8'));
+      return !!(pkgJson.dependencies?.react || pkgJson.devDependencies?.react);
+    } catch {
+      return false;
+    }
+  }
+
+  getRoutePatterns() {
+    return [/\.(tsx?|jsx?)$/];
+  }
+
+  getRequiredSystemContracts() {
+    return ['default', 'Component', 'PureComponent', 'Fragment', 'useEffect', 'useState', 'useContext', 'useReducer', 'useCallback', 'useMemo', 'useRef', 'useImperativeHandle', 'useLayoutEffect', 'useDebugValue'];
+  }
+
+  async analyze(node, filePath) {
+    if (node.explicitImports.has('react')) {
+      node.isReactComponent = true;
+    }
+    
+    // Detect JSX
+    if (node.rawCode && (node.rawCode.includes('</') || node.rawCode.includes('/>'))) {
+      node.hasJSX = true;
+    }
+
+    // Detect Hooks
+    const hookMatches = node.rawCode?.match(/use[A-Z]\w+/g) || [];
+    if (hookMatches.length > 0) {
+      node.reactHooks = new Set(hookMatches);
+    }
+  }
+}
+
+/**
+ * Vue Ecosystem Plugin
+ */
+export class VuePlugin extends BasePlugin {
+  get name() {
+    return 'vue';
+  }
+
+  getConfigFiles() {
+    return ['package.json', 'vue.config.js', 'vite.config.ts', 'vite.config.js'];
+  }
+
+  async isActive(baseDir) {
+    try {
+      const pkgJson = JSON.parse(await require('fs').promises.readFile(require('path').join(baseDir, 'package.json'), 'utf8'));
+      return !!(pkgJson.dependencies?.vue || pkgJson.devDependencies?.vue);
+    } catch {
+      return false;
+    }
+  }
+
+  getRoutePatterns() {
+    return [/\.vue$/, /\.(tsx?|jsx?)$/];
+  }
+
+  async analyze(node, filePath) {
+    if (filePath.endsWith('.vue')) {
+      node.isVueSFC = true;
+      // Extract template/script/style sections
+      const templateMatch = node.rawCode?.match(/<template>([\s\S]*)<\/template>/);
+      if (templateMatch) node.vueTemplate = templateMatch[1];
+      
+      const scriptMatch = node.rawCode?.match(/<script(?: setup)?(?: lang=['"]\w+['"])?>([\s\S]*)<\/script>/);
+      if (scriptMatch) node.vueScript = scriptMatch[1];
+    }
+  }
+}
+
+/**
+ * Svelte Ecosystem Plugin
+ */
+export class SveltePlugin extends BasePlugin {
+  get name() {
+    return 'svelte';
+  }
+
+  getConfigFiles() {
+    return ['package.json', 'svelte.config.js'];
+  }
+
+  async isActive(baseDir) {
+    try {
+      const pkgJson = JSON.parse(await require('fs').promises.readFile(require('path').join(baseDir, 'package.json'), 'utf8'));
+      return !!(pkgJson.dependencies?.svelte || pkgJson.devDependencies?.svelte);
+    } catch {
+      return false;
+    }
+  }
+
+  getRoutePatterns() {
+    return [/\.svelte$/, /\.(tsx?|jsx?)$/];
+  }
+
+  async analyze(node, filePath) {
+    if (filePath.endsWith('.svelte')) {
+      node.isSvelteComponent = true;
+    }
+  }
+}
+
+/**
+ * Angular Ecosystem Plugin
+ */
+export class AngularPlugin extends BasePlugin {
+  get name() {
+    return 'angular';
+  }
+
+  getConfigFiles() {
+    return ['package.json', 'angular.json'];
+  }
+
+  async isActive(baseDir) {
+    try {
+      const pkgJson = JSON.parse(await require('fs').promises.readFile(require('path').join(baseDir, 'package.json'), 'utf8'));
+      return !!(pkgJson.dependencies?.['@angular/core'] || pkgJson.devDependencies?.['@angular/core']);
+    } catch {
+      return false;
+    }
+  }
+
+  getRoutePatterns() {
+    return [/\.ts$/];
+  }
+
+  async analyze(node, filePath) {
+    if (node.rawCode?.includes('@Component') || node.rawCode?.includes('@Injectable') || node.rawCode?.includes('@NgModule')) {
+      node.isAngularEntity = true;
+    }
+  }
+}