entkapp 5.3.1 → 5.4.0

package/src/ast/OxcAnalyzer.js

@@ -2,13 +2,18 @@ import path from 'path';
 
 /**
  * Production-Grade Native Rust AST Parser Bridge (OXC)
- * Fixed for Windows environments to prevent path-based "Unexpected token" errors.
+ * Optimized for Monorepos and Windows environments.
+ * Implements the same semantic logic as ASTAnalyzer but using the high-performance OXC parser.
  */
 export class OxcAnalyzer {
   constructor(context) {
     this.context = context;
     this.oxc = null;
     this.isAvailable = false;
+    this.scopeStack = [];
+    this.currentScope = null;
+    this.scopeCounter = 0;
+    this.pass = 1;
   }
 
   async init() {
@@ -35,7 +40,6 @@ export class OxcAnalyzer {
 
   /**
    * WINDOWS FIX: Robust path normalization for OXC.
-   * Replaces backslashes with forward slashes to prevent escape sequence errors.
    */
   normalizePath(filePath) {
     if (!filePath) return filePath;
@@ -64,13 +68,10 @@ export class OxcAnalyzer {
           lang: "typescript"
         });
       } catch (e) {
-        // Fallback with normalized path if the options object fails
         try {
           result = this.oxc.parseSync(normalizedPath, cleanContent);
         } catch (innerErr) {
-          if (this.context.verbose) {
-            console.error(`[OXC-ERROR] Native parse failed for: ${normalizedPath}`);
-          }
+          if (this.context.verbose) console.error(`[OXC-ERROR] Native parse failed for: ${normalizedPath}`);
           return false;
         }
       }
@@ -79,11 +80,8 @@ export class OxcAnalyzer {
       try {
         parsedResult = typeof result === 'string' ? JSON.parse(result) : JSON.parse(JSON.stringify(result));
       } catch (err) {
-        if (result && typeof result === 'object') {
-          parsedResult = result;
-        } else {
-          return false;
-        }
+        if (result && typeof result === 'object') parsedResult = result;
+        else return false;
       }
 
       let programRoot = null;
@@ -93,24 +91,35 @@ export class OxcAnalyzer {
         else if (parsedResult.type === 'Program' || parsedResult.body) programRoot = parsedResult;
       }
 
-      // --- VALIDATION CHECK ---
-      // If the file has content but OXC returns an empty body, it's a silent failure.
       if (cleanContent.trim().length > 0 && (!programRoot || !programRoot.body || programRoot.body.length === 0)) {
-        if (this.context.verbose) {
-          console.warn(`[OXC-WARNING] Silent failure detected for ${normalizedPath}. Body is empty despite content. Triggering Fallback...`);
-        }
-        return false; // This triggers the fallback to TypeScript in the engine
-      }
-
-      if (!programRoot || !programRoot.body) {
+        if (this.context.verbose) console.warn(`[OXC-WARNING] Silent failure detected for ${normalizedPath}. Triggering Fallback...`);
         return false;
       }
 
-      fileNode.ast = programRoot; 
-      fileNode.symbolTable = new Map(); 
+      if (!programRoot || !programRoot.body) return false;
+
+      fileNode.ast = programRoot;
+      fileNode.symbolTable = new Map();
+
+      // --- TWO-PASS ANALYSIS ---
       
-      this.walkOxcAst(programRoot, fileNode, cleanContent, 1);
-      this.walkOxcAst(programRoot, fileNode, cleanContent, 2);
+      // Pass 1: Declarations
+      this.currentScope = { symbols: new Map(), parent: null, children: [] };
+      this.scopeStack = [this.currentScope];
+      this.scopeCounter = 0;
+      this.pass = 1;
+      this.walkOxcAst(programRoot, fileNode, cleanContent);
+
+      // Pass 2: References
+      if (this.scopeStack.length > 0) {
+        this.currentScope = this.scopeStack[0];
+        this.scopeCounter = 0;
+        this.pass = 2;
+        this.walkOxcAst(programRoot, fileNode, cleanContent);
+      }
+
+      this.scopeStack = [];
+      this.currentScope = null;
       
       return true;
     } catch (e) {
@@ -118,9 +127,163 @@ export class OxcAnalyzer {
     }
   }
 
-  // ... (walkOxcAst and other methods remain the same as in original)
-  walkOxcAst(node, fileNode, content, pass) {
+  pushScope() {
+    if (this.pass === 1) {
+      const newScope = { symbols: new Map(), parent: this.currentScope, children: [] };
+      if (this.currentScope) this.currentScope.children.push(newScope);
+      this.scopeStack.push(newScope);
+      this.currentScope = newScope;
+    } else {
+      if (this.currentScope && this.currentScope.children) {
+        const nextScope = this.currentScope.children[this.scopeCounter++];
+        if (nextScope) {
+          this.scopeStack.push(nextScope);
+          this.currentScope = nextScope;
+        }
+      }
+    }
+  }
+
+  popScope() {
+    this.scopeStack.pop();
+    this.currentScope = this.scopeStack[this.scopeStack.length - 1];
+  }
+
+  walkOxcAst(node, fileNode, content) {
     if (!node) return;
-    // (Implementation omitted for brevity, should be copied from original OxcAnalyzer.js)
+
+    const isScopeNode = node.type === 'BlockStatement' || node.type === 'FunctionDeclaration' || 
+                        node.type === 'ClassDeclaration' || node.type === 'ArrowFunctionExpression';
+
+    let previousCounter = 0;
+    if (isScopeNode) {
+      if (this.pass === 2) previousCounter = this.scopeCounter;
+      this.scopeCounter = 0;
+      this.pushScope();
+    }
+
+    if (this.pass === 1) {
+      this.handleNodePass1(node, fileNode, content);
+    } else {
+      this.handleNodePass2(node, fileNode, content);
+    }
+
+    // Traverse children
+    for (const key in node) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        child.forEach(c => this.walkOxcAst(c, fileNode, content));
+      } else if (child && typeof child === 'object' && child.type) {
+        this.walkOxcAst(child, fileNode, content);
+      }
+    }
+
+    if (isScopeNode) {
+      this.popScope();
+      if (this.pass === 2) this.scopeCounter = previousCounter + 1;
+    }
+  }
+
+  handleNodePass1(node, fileNode, content) {
+    switch (node.type) {
+      case 'ImportDeclaration':
+        this.handleImport(node, fileNode);
+        break;
+      case 'ExportNamedDeclaration':
+        this.handleExportNamed(node, fileNode);
+        break;
+      case 'ExportDefaultDeclaration':
+        fileNode.internalExports.set('default', { type: 'default', start: node.start, end: node.end });
+        break;
+      case 'ExportAllDeclaration':
+        if (node.source) {
+          const specifier = node.source.value;
+          fileNode.explicitImports.add(specifier);
+          fileNode.internalExports.set('*', { type: 're-export-all', source: specifier });
+        }
+        break;
+    }
+  }
+
+  handleNodePass2(node, fileNode, content) {
+    switch (node.type) {
+      case 'Identifier':
+        if (!this.isLocalShadowing(node.name)) {
+          fileNode.instantiatedIdentifiers.add(node.name);
+        }
+        break;
+      case 'CallExpression':
+        this.handleCall(node, fileNode);
+        break;
+      case 'MemberExpression':
+        if (node.property && node.property.name) {
+          fileNode.instantiatedIdentifiers.add(node.property.name);
+        }
+        break;
+    }
+  }
+
+  handleImport(node, fileNode) {
+    if (!node.source) return;
+    const specifier = node.source.value;
+    fileNode.explicitImports.add(specifier);
+    
+    if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
+      const pkgName = this._extractPackageName(specifier);
+      let isInternal = false;
+      if (this.context.pathMapper?.isTsconfigAlias?.(specifier)) isInternal = true;
+      if (!isInternal && this.context.workspaceGraph?.isLocalWorkspaceSpecifier?.(specifier)) isInternal = true;
+      if (!isInternal) fileNode.externalPackageUsage.add(pkgName);
+    }
+  }
+
+  handleExportNamed(node, fileNode) {
+    if (node.declaration) {
+      const decl = node.declaration;
+      const name = decl.id?.name || (decl.declarations?.[0]?.id?.name);
+      if (name) {
+        fileNode.internalExports.set(name, { type: 'export', start: node.start, end: node.end });
+      }
+    } else if (node.specifiers) {
+      node.specifiers.forEach(spec => {
+        const name = spec.exported.name || spec.exported.value;
+        fileNode.internalExports.set(name, { type: 'export', start: spec.start, end: spec.end });
+      });
+    }
+  }
+
+  handleCall(node, fileNode) {
+    const callee = node.callee;
+    if (callee.type === 'Identifier' && callee.name === 'require') {
+      const arg = node.arguments[0];
+      if (arg && (arg.type === 'StringLiteral' || arg.type === 'Literal')) {
+        const specifier = arg.value;
+        fileNode.explicitImports.add(specifier);
+      }
+    } else if (callee.type === 'Import') {
+      const arg = node.arguments[0];
+      if (arg && (arg.type === 'StringLiteral' || arg.type === 'Literal')) {
+        const specifier = arg.value;
+        fileNode.explicitImports.add(specifier);
+        fileNode.dynamicImports.add(specifier);
+      }
+    }
+  }
+
+  isLocalShadowing(name) {
+    let scope = this.currentScope;
+    while (scope) {
+      if (scope.symbols.has(name)) return scope.parent !== null;
+      scope = scope.parent;
+    }
+    return false;
+  }
+
+  _extractPackageName(specifier) {
+    if (specifier.startsWith('@')) {
+      const parts = specifier.split('/');
+      return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : specifier;
+    }
+    return specifier.split('/')[0];
   }
 }

package/src/index.js

@@ -113,22 +113,81 @@ export class RefactoringEngine {
       
       // Pass 1: Boot environment contexts and load alias configuration maps
       await this.oxcAnalyzer.init();
+      // UPGRADE: Wire pathMapper onto context so ASTAnalyzer alias-filtering works in all code paths
+      this.context.pathMapper = this.pathMapper;
       await this.pathMapper.loadMappings(this.context.tsconfigFilename);
       
       // Always attempt workspace mesh initialization
       console.log(ansis.dim('🌐 Probing for monorepo workspace configuration...'));
       await this.workspaceGraph.initializeWorkspaceMesh();
+      // UPGRADE: Always expose workspaceGraph on context (not only when workspace is enabled)
+      this.context.workspaceGraph = this.workspaceGraph;
+      
+      // UPGRADE: Scan all discovered framework configs across the workspace EARLY
+      const discoveredConfigs = await this.workspaceGraph.findFrameworkConfigs();
+      if (discoveredConfigs.length > 0) {
+        console.log(ansis.dim(`⚙️  Detected ${discoveredConfigs.length} framework configurations...`));
+        const { FrameworkConfigParser } = await import('./resolution/FrameworkConfigParser.js');
+        const parser = new FrameworkConfigParser(this.context);
+        
+        for (const configPath of discoveredConfigs) {
+          try {
+            const content = await fs.readFile(configPath, 'utf8');
+            
+            // 1. Core Parsing (Aliases)
+            const { aliases } = parser.parse(content, configPath);
+            for (const [key, target] of aliases.entries()) {
+              this.pathMapper.addAlias(key, target);
+            }
+            
+            // 2. Plugin-based Entry Detection
+            const detectedEntries = await this.magicDetector.detectEntryPointsFromPlugins(content, configPath);
+            for (const entry of detectedEntries) {
+              const absEntry = path.resolve(path.dirname(configPath), entry).replace(/\\/g, '/');
+              if (!this.context.entryPoints.includes(absEntry)) {
+                this.context.entryPoints.push(absEntry);
+              }
+            }
+            
+            // 3. Register config file itself as entry
+            if (!this.context.entryPoints.includes(configPath)) {
+              this.context.entryPoints.push(configPath);
+            }
+          } catch (e) {}
+        }
+      }
+
       if (this.context.isWorkspaceEnabled) {
         console.log(ansis.dim('🌐 Monorepo workspace detected – mapping package mesh layers...'));
-        // Expose workspaceGraph on context for WorkspaceDiagnostic and other components
-        this.context.workspaceGraph = this.workspaceGraph;
+        
+        // NEW: Register all workspace package entry points
+        for (const [dir, manifest] of this.workspaceGraph.packageManifests.entries()) {
+          if (manifest.entryPoints && manifest.entryPoints.length > 0) {
+            for (const ep of manifest.entryPoints) {
+              if (!this.context.entryPoints.includes(ep)) {
+                this.context.entryPoints.push(ep);
+              }
+            }
+          }
+        }
+
         // Reload PathMapper aliases now that workspace roots are known
         await this.pathMapper.loadMappings(this.context.tsconfigFilename);
         if (this.context.verbose) {
-          console.log(`[Workspace] Found ${this.workspaceGraph.packageManifests.size} workspace packages:`);
+          const wsSummary = this.workspaceGraph.getSummary();
+          console.log(`[Workspace] Found ${wsSummary.packages} workspace packages:`);
           for (const [dir, manifest] of this.workspaceGraph.packageManifests.entries()) {
             console.log(ansis.dim(`  • ${manifest.name || dir}`));
           }
+          if (wsSummary.tsconfigsLoaded > 0) {
+            console.log(ansis.dim(`[Workspace] Loaded ${wsSummary.tsconfigsLoaded} tsconfig.json file(s) from workspace packages`));
+          }
+          if (wsSummary.configFilesLoaded > 0) {
+            console.log(ansis.dim(`[Workspace] Loaded ${wsSummary.configFilesLoaded} *.config.ts/js file(s) from workspace packages`));
+          }
+          if (wsSummary.monorepoConfigs && wsSummary.monorepoConfigs.length > 0) {
+            console.log(ansis.dim(`[Workspace] Detected global configs: ${wsSummary.monorepoConfigs.join(', ')}`));
+          }
         }
       }
 
@@ -200,6 +259,14 @@ export class RefactoringEngine {
       for (const filePath of sourceCodeFilesList) {
         const absFilePath = slashifyInternal(filePath);
         const node = this.context.getOrCreateNode(absFilePath);
+
+        // Config data is now handled early in the workspace mesh initialization phase.
+        // We still mark the rawCode for plugin analysis.
+        if (absFilePath.includes('.config.')) {
+          try {
+            node.rawCode = await fs.readFile(absFilePath, 'utf8');
+          } catch (e) {}
+        }
         const currentHash = await this.cacheManager.computeHash(absFilePath);
         node.contentHash = currentHash;
 
@@ -227,6 +294,7 @@ export class RefactoringEngine {
         } else if (!parallelParseCompleted) {
           this.context.metrics.cacheMisses++;
           const fileContent = await fs.readFile(filePath, 'utf8');
+          node.rawCode = fileContent; // UPGRADE: Store raw code for plugin analysis
           
           let success = false;
           if (this.oxcAnalyzer.isAvailable) {
@@ -248,6 +316,10 @@ export class RefactoringEngine {
           if (!success || (oxcFailedToFindDependencies && (hasImportExportKeywords || hasCommonJSKeywords))) {
             await this.analyzer.parseFile(filePath, fileContent, node);
           }
+
+          // UPGRADE 5.3.0: Run plugin-specific content analysis
+          await this.magicDetector.runPluginContentAnalysis(node, absFilePath);
+
           // Secret scan on freshly parsed content
           const secretFindings = this.secretScanner.scanFileContent(filePath, fileContent);
           if (secretFindings.length > 0) {
@@ -562,6 +634,17 @@ export class RefactoringEngine {
                   const nodeBuiltins = ['assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console', 'constants', 'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'http', 'http2', 'https', 'inspector', 'module', 'net', 'os', 'path', 'perf_hooks', 'process', 'punycode', 'querystring', 'readline', 'repl', 'stream', 'string_decoder', 'timers', 'tls', 'trace_events', 'tty', 'url', 'util', 'v8', 'vm', 'worker_threads', 'zlib'];
                   if (nodeBuiltins.includes(basePkg) || nodeBuiltins.includes(basePkg.replace('node:', ''))) return;
 
+                  // UPGRADE: Skip tsconfig path aliases (e.g. @shared/*, @idk/*, ~/*)
+                  // Check full specifier AND basePkg against alias patterns
+                  if (this.pathMapper && typeof this.pathMapper.isTsconfigAlias === 'function') {
+                    if (this.pathMapper.isTsconfigAlias(specifier) || this.pathMapper.isTsconfigAlias(basePkg)) return;
+                  }
+
+                  // UPGRADE: Skip workspace packages detected via pnpm-workspace.yaml / package.json workspaces
+                  if (this.workspaceGraph && typeof this.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+                    if (this.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.workspaceGraph.isLocalWorkspaceSpecifier(basePkg)) return;
+                  }
+
                   if (!localDeps.has(basePkg)) {
                     const alreadyFlagged = this.context.unlistedDependencies.some(u => u.package === basePkg && u.file === filePath);
                     if (!alreadyFlagged) {
@@ -574,7 +657,7 @@ export class RefactoringEngine {
                   }
                 });
               } catch (error) {
-                if (this.context.options.verbose) {
+                if (this.context.options.verbose && error.code !== 'ENOENT') {
                   console.error(ansis.red(`      ❌ Manifest Parsing Exception: ${error.message}`));
                 }
               }

package/src/performance/GraphCache.js

@@ -59,6 +59,33 @@ export class IncrementalCacheManager {
     }
   }
 
+  /**
+   * UPGRADE 5.4.3: Affected-Only Analysis
+   * Identifies which files need re-analysis based on Git changes or cache misses.
+   */
+  async getAffectedFiles(allFiles) {
+    const manifest = await this.loadCacheManifest();
+    const affected = [];
+    const unchanged = [];
+
+    for (const file of allFiles) {
+      const cached = manifest[file];
+      if (!cached) {
+        affected.push(file);
+        continue;
+      }
+
+      const currentHash = await this.computeHash(file);
+      if (currentHash !== cached.hash) {
+        affected.push(file);
+      } else {
+        unchanged.push({ path: file, data: cached });
+      }
+    }
+
+    return { affected, unchanged };
+  }
+
   /**
    * Serializes the current active dependency graph, translating Maps and Sets into JSON schemas.
    * @param {Map<string, Object>} currentGraphState - In-memory structural project state map

package/src/performance/WorkerPool.js

@@ -47,10 +47,11 @@ export class WorkerPool {
 
     try {
       const analyticalResultsSubsets = await Promise.all(threadTaskExecutionsList);
+      const flatResults = analyticalResultsSubsets.flat();
       
       // Merge thread structural subsets back into the primary context graph nodes
-      analyticalResultsSubsets.flat().forEach(result => {
-        if (!result) return;
+      for (const result of flatResults) {
+        if (!result) continue;
         // UPGRADE: Normalize filePath before merging to prevent duplicate nodes in the graph
         const normalizedPath = path.resolve(this.context.cwd, result.filePath).replace(/\\/g, '/');
         const node = masterEngineInstanceReference.context.getOrCreateNode(normalizedPath);
@@ -95,7 +96,13 @@ export class WorkerPool {
           if (!node.globImports) node.globImports = [];
           result.globImports.forEach(i => node.globImports.push(i));
         }
-      });
+
+        // UPGRADE 5.3.0: Run plugin-specific content analysis for worker-parsed files
+        if (result.rawCode) {
+          node.rawCode = result.rawCode;
+          await masterEngineInstanceReference.magicDetector.runPluginContentAnalysis(node, normalizedPath);
+        }
+      }
 
       return true;
     } catch (poolThreadFault) {
@@ -107,13 +114,24 @@ export class WorkerPool {
   }
 
   executeChunkInsideThread(fileChunkSubset) {
+    // UPGRADE: Serialize alias patterns and workspace package names so workers can filter false positives
+    const serializedAliasPatterns = (this.context.pathMapper && this.context.pathMapper._aliasPatterns)
+      ? this.context.pathMapper._aliasPatterns.map(p => p.regex.source)
+      : [];
+    const workspacePackageNames = (this.context.workspaceGraph && this.context.workspaceGraph.workspacePackages)
+      ? Array.from(this.context.workspaceGraph.workspacePackages.keys())
+      : [];
+
     return new Promise((resolve, reject) => {
       const workerInstance = new Worker(this.workerScriptPath, { type: 'module',
         workerData: { 
           files: fileChunkSubset, 
           contextOptions: { 
             verbose: this.context.verbose,
-            cwd: this.context.cwd
+            cwd: this.context.cwd,
+            // UPGRADE: Pass alias/workspace data so workers can filter false positives
+            aliasPatternSources: serializedAliasPatterns,
+            workspacePackageNames
           } 
         }
       });

package/src/performance/WorkerTaskRunner.js

@@ -12,11 +12,35 @@ async function runTask() {
   const { files, contextOptions } = workerData;
   const results = [];
 
+  // UPGRADE: Reconstruct alias/workspace filter helpers from serialized contextOptions
+  // These are passed from WorkerPool.executeChunkInsideThread so workers can skip false positives
+  const aliasRegexes = (contextOptions.aliasPatternSources || []).map(src => {
+    try { return new RegExp(src); } catch { return null; }
+  }).filter(Boolean);
+  const workspacePackageSet = new Set(contextOptions.workspacePackageNames || []);
+
+  // Lightweight helpers mirroring PathMapper.isTsconfigAlias and WorkspaceGraph.isLocalWorkspaceSpecifier
+  const isTsconfigAlias = (spec) => aliasRegexes.some(r => r.test(spec));
+  const isWorkspacePkg = (spec) => {
+    if (workspacePackageSet.has(spec)) return true;
+    for (const name of workspacePackageSet) { if (spec.startsWith(name + '/')) return true; }
+    return false;
+  };
+
   // Create a minimal context for analyzers
   const mockContext = {
     verbose: contextOptions.verbose,
     cwd: contextOptions.cwd || process.cwd(),
     projectGraph: new Map(),
+    // UPGRADE: Expose lightweight alias/workspace helpers so ASTAnalyzer can filter imports
+    pathMapper: {
+      isTsconfigAlias,
+      _aliasPatterns: aliasRegexes.map(r => ({ regex: r }))
+    },
+    workspaceGraph: {
+      isLocalWorkspaceSpecifier: isWorkspacePkg,
+      workspacePackages: workspacePackageSet
+    },
     getOrCreateNode: (path) => ({
       filePath: path,
       explicitImports: new Set(),
@@ -50,6 +74,7 @@ async function runTask() {
     try {
       const content = await fs.readFile(filePath, 'utf8');
       const node = mockContext.getOrCreateNode(filePath);
+      node.rawCode = content; // UPGRADE: Add raw code to node for plugin analysis in main thread
 
       // Defensiver Check: Sicherstellen, dass die Map/Set-Instanzen sauber existieren
       if (!(node.internalExports instanceof Map)) node.internalExports = new Map();
@@ -106,6 +131,7 @@ async function runTask() {
       // Serialize the node data for transfer back to main thread
       results.push({
         filePath: node.filePath,
+        rawCode: node.rawCode, // UPGRADE: Pass raw code back to main thread for plugin analysis
         explicitImports: Array.from(node.explicitImports || []),
         dynamicImports: Array.from(node.dynamicImports || []),
         importedSymbols: Array.from(node.importedSymbols || []),

package/src/plugins/BasePlugin.js

@@ -5,7 +5,7 @@ import path from 'path';
  * Base class for all entkapp plugins.
  * Defines the contract for ecosystem detection, entry point mapping,
  * and missing dependency / devDependency detection.
- * Version 5.0.0: Added getMissingDependencies(), getOrphanedConfigs(), runDependencyDiagnostics().
+ * Version 5.4.0: Added detectEntryPoints() for dynamic framework entry detection.
  */
 export class BasePlugin {
     constructor(context) {
@@ -34,6 +34,17 @@ export class BasePlugin {
         return [];
     }
 
+    /**
+     * Version 5.4.0: Dynamically detect entry points from a file's content.
+     * Useful for parsing vite.config.ts, webpack.config.js, etc.
+     * @param {string} content - The file content
+     * @param {string} filePath - The absolute path to the file
+     * @returns {Array<string>} List of relative or absolute entry point paths
+     */
+    detectEntryPoints(content, filePath) {
+        return [];
+    }
+
     /**
      * Returns symbols that are implicitly required/exported by the framework.
      */
@@ -43,25 +54,13 @@ export class BasePlugin {
 
     /**
      * Returns the npm package names required for this plugin to work.
-     * Each entry is either a string or an object:
-     *   { name: string, dev?: boolean, optional?: boolean }
-     *   - dev: true  => expected in devDependencies
-     *   - dev: false => expected in dependencies
-     *   - optional   => only warn, not error
-     *
-     * Override in subclasses to enable automatic dependency checking.
-     * @returns {Array<string | {name: string, dev?: boolean, optional?: boolean}>}
      */
     getRequiredPackages() {
         return [];
     }
 
     /**
-     * Version 5.0.0: Checks whether all required packages are present in package.json.
-     * Returns an array of diagnostic objects describing missing or misplaced dependencies.
-     *
-     * @param {string} baseDir - The project root directory
-     * @returns {Promise<Array>}
+     * Checks whether all required packages are present in package.json.
      */
     async getMissingDependencies(baseDir) {
         const diagnostics = [];
@@ -147,11 +146,7 @@ export class BasePlugin {
     }
 
     /**
-     * Version 5.0.0: Checks for config files that exist without the corresponding package.
-     * Detects "orphaned" configs – e.g. .prettierrc exists but prettier is not installed.
-     *
-     * @param {string} baseDir
-     * @returns {Promise<Array>}
+     * Checks for config files that exist without the corresponding package.
      */
     async getOrphanedConfigs(baseDir) {
         const diagnostics = [];
@@ -195,11 +190,7 @@ export class BasePlugin {
     }
 
     /**
-     * Version 5.0.0: Run all dependency diagnostics (missing + orphaned).
-     * Convenience method combining getMissingDependencies and getOrphanedConfigs.
-     *
-     * @param {string} baseDir
-     * @returns {Promise<Array>}
+     * Run all dependency diagnostics (missing + orphaned).
      */
     async runDependencyDiagnostics(baseDir) {
         const [missing, orphaned] = await Promise.all([
@@ -210,9 +201,7 @@ export class BasePlugin {
     }
 
     /**
-     * Version 3.2.0: Dynamic getter for custom plugin properties.
-     * @param {string} key - The property key to retrieve
-     * @returns {any} The value of the custom property
+     * Dynamic getter for custom plugin properties.
      */
     get(key) {
         const methodName = `get${key.charAt(0).toUpperCase() + key.slice(1)}`;