entkapp 5.3.1 → 5.4.0

package/README.md

@@ -1,4 +1,4 @@
-# 🕸️ entkapp Ultimate v5.3.1
+# 🕸️ entkapp Ultimate v5.4.0
 
 > **The Ultimate Enterprise Codebase Janitor.** High-speed OXC integration, type-aware analysis, and automated structural healing. Fully standalone architectural orchestrator.
 
@@ -35,12 +35,6 @@ Starts the interactive analysis:
 npx entkapp -r
 ```
 
-### Headless Analysis Mode
-Ideal for CI/CD pipelines. Performs analysis without prompts and outputs JSON:
-```bash
-npx entkapp --analyze
-```
-
 ### Auto-Fix Mode
 Automatically resolves dependency conflicts and structural issues:
 ```bash

package/bin/cli.js

@@ -2,10 +2,10 @@
 
 /**
  * ============================================================================
- * 🏁 loui CLI Entry Point
+ * 🚀 entkapp: The High-Performance Codebase Orchestrator
  * ============================================================================
- * Handles option compilation, environment orchestration, option validation,
- * and initiates the primary operational pipeline loop.
+ * Command-line interface for executing architectural audits, structural 
+ * refactoring cycles, and autonomous codebase healing.
  */
 
 import { Command } from 'commander';
@@ -13,163 +13,104 @@ import ansis from 'ansis';
 import path from 'path';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
-import readline from 'readline/promises';
+import { ConfigLoader } from '../src/resolution/ConfigLoader.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(await fs.readFile(path.join(__dirname, '../package.json'), 'utf8'));
 
 const program = new Command();
 
-async function bootstrap() {
+async function main() {
   try {
-    const packageJsonPath = path.resolve(__dirname, '../package.json');
-    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
-
     program
       .name('entkapp')
-      .description(ansis.cyan('The Ultimate Enterprise Codebase Janitor with OXC integration, type-aware analysis, and automated structural healing.'))
-      .version(packageJsonContent.version || '5.3.1');
-
-    program
-      .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
-      .option('-d, --debug', 'Developer`s comprehensive telemetry debug diagnostics', false)
-      .option('--fix', 'Enable atomic code updates, structural file pruning, and active type sanitization', false)
+      .description('Autonomous architectural refactoring and codebase optimization engine')
+      .version(pkg.version)
+      .argument('[path]', 'Target directory for codebase analysis and refactoring', '.')
+      .option('-f, --fix', 'Automatically apply identified structural optimizations and healing', false)
       .option('--tsconfig <filename>', 'Specify path to custom layout configurations', 'tsconfig.json')
       .option('--test-command <command>', 'Integrated continuous safety test validation script execution path', 'npm test')
       .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
       .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false)
       .option('--visualize', 'Generate an interactive execution graph visualization', false)
+      .option('-ef, --entry-file <path>', 'Manually specify a primary entry file for analysis')
       .option('-r, --run', 'Execute the primary operational pipeline loop', false)
       .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false)
       .option('--timeout <ms>', 'Set execution timeout in milliseconds', '30000');
 
     program.parse(process.argv);
-    const options = program.opts();
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-    // --- Onboarding Check (Skipped in Non-Interactive Mode) ---
-    // FIX: Ensure options.cwd is always a string, never undefined
-    const targetCwd = path.resolve(options.cwd || process.cwd());
-    const pkgJsonPath = path.join(targetCwd, 'package.json');
-    const configDirPath = path.join(targetCwd, 'entkapp');
-
-    let pkgJson;
-    try {
-      pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
-    } catch (e) {}
-
-    let configInstalled = false;
-    if (!options.yes && !options.run) {
-      // 1. Ask to install script
-      if (pkgJson && !pkgJson.scripts?.['entkapp:run']) {
-        const answer = await rl.question(ansis.bold.yellow('❓ No "entkapp:run" script found in package.json. Install it? (y/n): '));
-        if (answer.toLowerCase() === 'y') {
-          pkgJson.scripts = pkgJson.scripts || {};
-          pkgJson.scripts['entkapp:run'] = 'npx entkapp --fix';
-          await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
-          console.log(ansis.green('✅ "entkapp:run" script added to package.json.'));
-        }
-      }
-
-      // 2. Ask to install config folder
-      try {
-        await fs.access(configDirPath);
-        configInstalled = true;
-      } catch (e) {
-        const answer = await rl.question(ansis.bold.yellow('❓ No "/entkapp" configuration folder found. Create it with defaults? (y/n): '));
-        if (answer.toLowerCase() === 'y') {
-          await fs.mkdir(configDirPath, { recursive: true });
-          await fs.mkdir(path.join(configDirPath, 'plugins'), { recursive: true });
-          const defaultConfig = {
-            interface: "CLI",
-            useBuiltinPlugins: true,
-            useCustomPlugins: true,
-
-            options: { verbose: false, fastMode: true, selfHealing: true },
-            enabledPlugins: ["nextjs", "nuxt", "remix", "sveltekit", "astro"]
-          };
-          await fs.writeFile(path.join(configDirPath, 'config.json'), JSON.stringify(defaultConfig, null, 2));
-          console.log(ansis.green('✅ "/entkapp" folder? and default config created.'));
-          configInstalled = true;
-        }
-      }
-
-      if (pkgJson?.scripts?.['entkapp:run'] || configInstalled) {
-        console.log(ansis.bold.cyan('\n🚀 Setup complete! To start the engine, run:'));
-        console.log(ansis.white(`   - npx entkapp -r`));
-        console.log(ansis.white(`   - npm run entkapp:run\n`));
-      }
-    }
 
-    rl.close();
-
-    // Load local config if available
-    let localConfig = {};
-    try {
-      const { ConfigLoader } = await import('../src/resolution/ConfigLoader.js');
-      const loader = new ConfigLoader(targetCwd);
-      localConfig = await loader.loadConfig();
-    } catch (e) {}
-
-    // Merge options with local config
-    const finalInterface = localConfig.interface || 'CLI';
-    if (finalInterface === 'GUI') {
-      console.log(ansis.bold.magenta('🎨 GUI Mode Detected. Starting Web Interface...'));
-      return;
-    }
-
-    // Only proceed to execution if -r/--run is provided
-    if (!options.run) {
-      return;
+    const options = program.opts();
+    const targetCwd = path.resolve(process.cwd(), program.args[0] || '.');
+
+    // Load configuration
+    const configLoader = new ConfigLoader(targetCwd);
+    const localConfig = await configLoader.loadConfig(options);
+
+    if (options.verbose) {
+      const summary = {
+        packages: localConfig.workspacePackages?.length || 0,
+        tsconfigs: localConfig.workspaceTsConfigs?.length || 0,
+        configs: localConfig.workspaceConfigFiles?.length || 0
+      };
+      console.log(ansis.dim(`[ConfigLoader] Monorepo detected – ${summary.packages} package(s), ${summary.tsconfigs} tsconfig(s), ${summary.configs} *.config file(s) loaded`));
     }
 
-    // --- Timeout Handling ---
-    const timeoutMs = parseInt(options.timeout);
     const timeoutTimer = setTimeout(() => {
-      console.error(ansis.bold.red(`\n🚨 Execution Timeout: The process exceeded the limit of ${timeoutMs}ms.`));
+      console.error(ansis.red(`\n❌ Execution Timeout: Operation exceeded ${options.timeout}ms limit.`));
       process.exit(1);
-    }, timeoutMs);
-    timeoutTimer.unref(); // Allow process to exit if work finishes
+    }, parseInt(options.timeout));
 
-    console.log(ansis.bold.green(`\n📦 entkapp v${packageJsonContent.version || '5.3.1'} Engine Activation`));
+    console.log('\n' + ansis.bold.cyan(`📦 entkapp v${pkg.version} Engine Activation`));
     console.log(ansis.dim('------------------------------------------------------------'));
-    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(targetCwd)}`);
-    console.log(`${ansis.bold('Refactoring Mode     :')} ${options.fix ? ansis.yellow('Active Fixing & Self-Healing Enabled') : ansis.gray('Dry-Run Reporting Only')}`);
-    console.log(`${ansis.bold('Validation Sandbox   :')} ${ansis.magenta(options.testCommand)}`);
+    console.log(`${ansis.bold('Target Workspace Root')} : ${targetCwd}`);
+    console.log(`${ansis.bold('Refactoring Mode')}     : ${options.fix ? ansis.yellow('Automated Healing Active') : 'Dry-Run Reporting Only'}`);
+    console.log(`${ansis.bold('Validation Sandbox')}   : ${options.testCommand}`);
     console.log(ansis.dim('------------------------------------------------------------\n'));
 
     const { RefactoringEngine } = await import('../src/index.js');
 
+    // Prepare entry points - EXTREMELY ROBUST ARRAY HANDLING
+    let entryPoints = [];
+    if (localConfig.entryPoints && typeof localConfig.entryPoints[Symbol.iterator] === 'function') {
+      entryPoints = [...localConfig.entryPoints];
+    } else if (localConfig.entryPoints) {
+      entryPoints = [localConfig.entryPoints];
+    }
+    
+    if (options.entryFile) {
+      const absEntry = path.resolve(targetCwd, options.entryFile).replace(/\\/g, '/');
+      if (!entryPoints.includes(absEntry)) {
+        entryPoints.push(absEntry);
+      }
+    }
+
     const engine = new RefactoringEngine({
       cwd: targetCwd,
       autoFix: options.fix,
       tsconfig: options.tsconfig,
       testCommand: options.testCommand,
-      workspace: options.workspace,
+      workspace: options.workspace || localConfig.workspace || false,
       verbose: options.verbose,
       skipConfirm: options.yes,
-      // Pass through local config settings
-      entryPoints: localConfig.entryPoints,
-      exclude: localConfig.exclude,
-      rules: localConfig.rules,
+      entryPoints: entryPoints,
+      exclude: localConfig.exclude || [],
+      rules: localConfig.rules || {},
       debug: options.debug,
       visualize: options.visualize,
+      workspacePackages:    localConfig.workspacePackages || [],
+      workspaceTsConfigs:   localConfig.workspaceTsConfigs || [],
+      workspaceConfigFiles: localConfig.workspaceConfigFiles || [],
     });
 
     await engine.run();
     
     clearTimeout(timeoutTimer);
-    console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
-    process.exit(0);
-
-  } catch (criticalBootError) {
-    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Boot Instability: ${criticalBootError.message}`));
-    if (criticalBootError.stack) {
-      console.error(ansis.dim(criticalBootError.stack));
-    }
+  } catch (err) {
+    console.error(ansis.red(`\n❌ Engine Failure: ${err.message}`));
+    if (program.opts().verbose) console.error(err);
     process.exit(1);
   }
 }
 
-bootstrap();
+main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "name": "entkapp",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "description": "The Ultimate Enterprise Codebase Janitor. High-speed OXC integration, type-aware analysis, and automated structural healing. Fully standalone architectural orchestrator.",
   "type": "module",
   "main": "index.js",

package/src/EngineContext.js

@@ -419,6 +419,12 @@ export class EngineContext {
     report.importedUnusedPackages = Array.from(this.importedUnusedPackages);
     report.unusedBinaries = Array.from(this.unusedBinaries);
 
+    // UPGRADE 5.4.3: Integrate enhanced results from GraphAnalyzer
+    const analyzer = new (await import('./resolution/GraphAnalyzer.js')).GraphAnalyzer(this);
+    const { unusedImports, boundaryViolations } = await analyzer.findDeadCode();
+    report.unusedImports = unusedImports;
+    report.boundaryViolations = boundaryViolations;
+
     return report;
   }
 }

package/src/ast/ASTAnalyzer.js

@@ -265,7 +265,16 @@ export class ASTAnalyzer {
                 fileNode.explicitImports.add(specifier);
                 fileNode.importedSymbols.add(`${specifier}:*`);
                 if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-                  fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+                  // UPGRADE: Apply alias/workspace filtering before adding to externalPackageUsage
+                  const pkgNameReq = this._extractPackageName(specifier);
+                  let isInternalReq = false;
+                  if (this.context.pathMapper && typeof this.context.pathMapper.isTsconfigAlias === 'function') {
+                    if (this.context.pathMapper.isTsconfigAlias(specifier) || this.context.pathMapper.isTsconfigAlias(pkgNameReq)) isInternalReq = true;
+                  }
+                  if (!isInternalReq && this.context.workspaceGraph && typeof this.context.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+                    if (this.context.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgNameReq)) isInternalReq = true;
+                  }
+                  if (!isInternalReq) fileNode.externalPackageUsage.add(pkgNameReq);
                 }
               } else if (arg && ts.isTemplateExpression(arg)) {
                 // Dynamic require with template literal
@@ -351,8 +360,40 @@ export class ASTAnalyzer {
       const specifier = node.moduleSpecifier.text;
       fileNode.explicitImports.add(specifier);
       
+      // UPGRADE 5.4.2: Distinguish between local aliases and workspace packages
       if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+        let isInternalAlias = false;
+        const pkgName = this._extractPackageName(specifier);
+
+        // UPGRADE: First check via isTsconfigAlias() — works even when the target file doesn't exist yet
+        if (this.context.pathMapper && typeof this.context.pathMapper.isTsconfigAlias === 'function') {
+          if (this.context.pathMapper.isTsconfigAlias(specifier) || this.context.pathMapper.isTsconfigAlias(pkgName)) {
+            isInternalAlias = true;
+          }
+        }
+
+        // UPGRADE: Check workspace packages (pnpm-workspace.yaml / package.json workspaces)
+        if (!isInternalAlias && this.context.workspaceGraph && typeof this.context.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+          if (this.context.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgName)) {
+            isInternalAlias = true;
+          }
+        }
+
+        // Fallback: try resolvePath() — works when the target file exists on disk
+        if (!isInternalAlias && this.context.pathMapper && typeof this.context.pathMapper.resolvePath === 'function') {
+          const resolved = this.context.pathMapper.resolvePath(specifier);
+          if (resolved !== specifier && (resolved.startsWith('/') || resolved.includes(':'))) {
+            // Only mark as internal alias if it's NOT a registered workspace package
+            const isWorkspacePkg = this.context.workspaceGraph && this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgName);
+            if (!isWorkspacePkg) {
+              isInternalAlias = true;
+            }
+          }
+        }
+        
+        if (!isInternalAlias) {
+          fileNode.externalPackageUsage.add(pkgName);
+        }
       }
 
       if (this.context.workspaceGraph && typeof this.context.workspaceGraph.auditImportSpecifier === 'function') {
@@ -373,14 +414,29 @@ export class ASTAnalyzer {
           if (ts.isNamespaceImport(node.importClause.namedBindings)) {
             fileNode.importedSymbols.add(`${specifier}:*`);
             if (targetFile) this.context.importUsageRegistry.add(`${targetFile}:*`);
+            
+            // Track local name for unused import detection
+            if (!fileNode.localImportBindings) fileNode.localImportBindings = new Map();
+            fileNode.localImportBindings.set(node.importClause.namedBindings.name.text, { specifier, originalName: '*' });
           } else if (ts.isNamedImports(node.importClause.namedBindings)) {
             node.importClause.namedBindings.elements.forEach(element => {
               const importedName = element.propertyName ? element.propertyName.text : element.name.text;
+              const localName = element.name.text;
               fileNode.importedSymbols.add(`${specifier}:${importedName}`);
               if (targetFile) this.context.importUsageRegistry.add(`${targetFile}:${importedName}`);
+              
+              // Track local name for unused import detection
+              if (!fileNode.localImportBindings) fileNode.localImportBindings = new Map();
+              fileNode.localImportBindings.set(localName, { specifier, originalName: importedName });
             });
           }
         }
+        
+        // Handle default import binding
+        if (node.importClause.name) {
+          if (!fileNode.localImportBindings) fileNode.localImportBindings = new Map();
+          fileNode.localImportBindings.set(node.importClause.name.text, { specifier, originalName: 'default' });
+        }
       } else {
         // Side-Effect Import (import '...')
         // FIX: Mark the target file as used even if no symbols are imported
@@ -423,7 +479,22 @@ export class ASTAnalyzer {
     if (specifier) {
       fileNode.explicitImports.add(specifier);
       if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+        // UPGRADE: Apply the same alias/workspace filtering as handleImportDeclaration
+        const pkgNameExport = this._extractPackageName(specifier);
+        let isInternalAliasExport = false;
+        if (this.context.pathMapper && typeof this.context.pathMapper.isTsconfigAlias === 'function') {
+          if (this.context.pathMapper.isTsconfigAlias(specifier) || this.context.pathMapper.isTsconfigAlias(pkgNameExport)) {
+            isInternalAliasExport = true;
+          }
+        }
+        if (!isInternalAliasExport && this.context.workspaceGraph && typeof this.context.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+          if (this.context.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgNameExport)) {
+            isInternalAliasExport = true;
+          }
+        }
+        if (!isInternalAliasExport) {
+          fileNode.externalPackageUsage.add(pkgNameExport);
+        }
       }
 
       if (!node.exportClause) {
@@ -587,7 +658,16 @@ export class ASTAnalyzer {
           fileNode.dynamicImports.add(specifier);
           fileNode.importedSymbols.add(`${specifier}:*`);
           if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-            fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+            // UPGRADE: Apply alias/workspace filtering before adding to externalPackageUsage
+            const pkgNameDyn = this._extractPackageName(specifier);
+            let isInternalDyn = false;
+            if (this.context.pathMapper && typeof this.context.pathMapper.isTsconfigAlias === 'function') {
+              if (this.context.pathMapper.isTsconfigAlias(specifier) || this.context.pathMapper.isTsconfigAlias(pkgNameDyn)) isInternalDyn = true;
+            }
+            if (!isInternalDyn && this.context.workspaceGraph && typeof this.context.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+              if (this.context.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgNameDyn)) isInternalDyn = true;
+            }
+            if (!isInternalDyn) fileNode.externalPackageUsage.add(pkgNameDyn);
           }
         } else {
           // Non-literal dynamic import
@@ -608,9 +688,17 @@ export class ASTAnalyzer {
         if (this.context.verbose) console.log(`[AST-DEBUG] Added import: ${specifier}`);
         fileNode.explicitImports.add(specifier);
         
-        // UPGRADE: Also track package usage for unlisted dependency detection
+        // UPGRADE: Apply alias/workspace filtering before adding to externalPackageUsage
         if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-          fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+          const pkgNameCE = this._extractPackageName(specifier);
+          let isInternalCE = false;
+          if (this.context.pathMapper && typeof this.context.pathMapper.isTsconfigAlias === 'function') {
+            if (this.context.pathMapper.isTsconfigAlias(specifier) || this.context.pathMapper.isTsconfigAlias(pkgNameCE)) isInternalCE = true;
+          }
+          if (!isInternalCE && this.context.workspaceGraph && typeof this.context.workspaceGraph.isLocalWorkspaceSpecifier === 'function') {
+            if (this.context.workspaceGraph.isLocalWorkspaceSpecifier(specifier) || this.context.workspaceGraph.isLocalWorkspaceSpecifier(pkgNameCE)) isInternalCE = true;
+          }
+          if (!isInternalCE) fileNode.externalPackageUsage.add(pkgNameCE);
         }
       }
     }

package/src/ast/MagicDetector.js

@@ -6,15 +6,7 @@ import { PluginRegistry } from '../plugins/PluginRegistry.js';
  * Ecosystem Entry Point Manifest & Dynamic Framework Router Heuristic Validator
  * Intercepts implicit conventions to handle cases where direct import statements are absent.
  * Now refactored to use a pluggable architecture.
- *
- * Improvements over v1:
- * - Extended config-file detection list (Biome, Oxlint, tsup, unbuild, etc.)
- * - Next.js App Router conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, etc.)
- * - Remix conventions (route files under app/routes/)
- * - SvelteKit conventions (+page.svelte, +layout.svelte, etc.)
- * - Astro page/layout conventions
- * - Common entry-point patterns (bin/, cli.ts, server.ts, main.ts, app.ts)
- * - Test file patterns extended to cover Vitest workspace files
+ * Version 5.4.0: Added detectEntryPointsFromPlugins() for dynamic framework entry detection.
  */
 export class MagicDetector {
   constructor(context) {
@@ -31,18 +23,26 @@ export class MagicDetector {
 
   /**
    * Audits the project context to map active micro-framework ecosystems.
-   * @param {string} baseContextDirectory - Root file workspace context execution vector path
    */
   async identifyActiveProjectEcosystems(baseContextDirectory) {
     await this.ensureInitialized(baseContextDirectory);
     const activePlugins = await this.registry.getActivePlugins(baseContextDirectory);
     const activeFrameworkFlags = activePlugins.map(p => p.name);
-    
-    // Universal infrastructure overrides (testing platforms and common bundlers)
     activeFrameworkFlags.push('universal-tooling-vectors');
     return activeFrameworkFlags;
   }
 
+  /**
+   * Version 5.4.0: Delegates entry point detection to the plugin registry.
+   * @param {string} content - The file content
+   * @param {string} filePath - The absolute path to the file
+   * @returns {Array<string>} List of detected entry points
+   */
+  async detectEntryPointsFromPlugins(content, filePath) {
+    await this.ensureInitialized();
+    return this.registry.detectEntryPointsFromContent(content, filePath);
+  }
+
   /**
    * Assesses if a file path acts as an implicit route entry point.
    */
@@ -60,7 +60,6 @@ export class MagicDetector {
       }
     }
 
-    // Apply baseline platform rules (Test suites, lint parameters, continuous integration files)
     if (this.isCoreToolingSuiteElement(normalizedSystemPath)) {
       return true;
     }
@@ -68,49 +67,46 @@ export class MagicDetector {
     return false;
   }
 
+  /**
+   * Version 5.3.0: Delegates content analysis to the plugin registry.
+   */
+  async runPluginContentAnalysis(node, absolutePath) {
+    await this.ensureInitialized();
+    await this.registry.runPluginAnalysis(node, absolutePath);
+  }
+
   isCoreToolingSuiteElement(normalizedPath) {
-    // ── Test / spec files ──────────────────────────────────────────────────────
     if (/\.(test|spec|e2e|cy)\.(js|ts|tsx|jsx)$/i.test(normalizedPath)) return true;
     if (/\.stories\.(js|ts|tsx|jsx)$/i.test(normalizedPath)) return true;
 
-    // ── Build / bundler config files ───────────────────────────────────────────
     const configFragments = [
-      // Test runners
       'jest.config.', 'vitest.config.', 'vitest.workspace.',
       'playwright.config.', 'cypress.config.',
-      // Bundlers
       'webpack.config.', 'vite.config.', 'rollup.config.',
       'esbuild.config.', 'parcel.config.',
       'tsup.config.', 'unbuild.config.', 'pkgroll.config.',
-      // CSS / styling
       'tailwind.config.', 'postcss.config.', '.postcssrc.',
-      // Linters / formatters
       '.eslintrc.', 'eslint.config.', 'prettier.config.', '.prettierrc.',
       '.stylelintrc.', 'stylelint.config.',
       'biome.json', '.oxlintrc.',
-      // Babel / transpilation
       '.babelrc.', 'babel.config.',
-      // Commit / git hooks
       '.commitlintrc.', 'commitlint.config.',
       '.lintstagedrc.', 'lint-staged.config.',
-      // Documentation
       'typedoc.config.', 'typedoc.json',
-      // Monorepo tools
       'turbo.json', 'nx.json', 'lerna.json',
-      // Misc tooling
       'knip.config.', 'knip.json',
       'syncpack.config.',
-      // Internal worker
       'WorkerTaskRunner.js'
     ];
     if (configFragments.some(f => normalizedPath.includes(f))) return true;
 
-    // ── Common application entry points ───────────────────────────────────────
     const entryPatterns = [
       // CLI binaries
       '/bin/cli.js', '/bin/cli.ts', '/bin/cli.mjs',
       '/bin/index.js', '/bin/index.ts',
-      // Server / app entry points (Reduced in v3.3.8 to avoid false positives in libraries)
+      // Standard package entry points (poly-extension support)
+      '/index.js', '/index.ts', '/index.jsx', '/index.tsx', '/index.mjs', '/index.cjs',
+      // Server / app entry points
       '/src/main.ts', '/src/main.js',
       '/src/app.ts', '/src/app.js',
       '/src/api/HeadlessAPI.js', '/src/api/PluginSDK.js',
@@ -119,50 +115,37 @@ export class MagicDetector {
     ];
     if (entryPatterns.some(p => normalizedPath.endsWith(p))) return true;
 
-    // ── Next.js App Router conventions ────────────────────────────────────────
-    // Files under app/ directory with Next.js special names
     if (/\/app\/(page|layout|loading|error|not-found|template|default|route|middleware)\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
-    // Next.js Pages Router
     if (/\/pages\/.*\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
-    // Next.js API routes
     if (/\/pages\/api\/.*\.(js|ts)$/.test(normalizedPath)) return true;
-    // Next.js middleware
     if (/\/middleware\.(js|ts)$/.test(normalizedPath)) return true;
-    // Next.js config
     if (/\/next\.config\.(js|ts|mjs|cjs)$/.test(normalizedPath)) return true;
 
-    // ── Remix conventions ─────────────────────────────────────────────────────
     if (/\/app\/routes\/.*\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
     if (/\/app\/root\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
     if (/\/app\/entry\.(client|server)\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
 
-    // ── SvelteKit conventions ─────────────────────────────────────────────────
     if (/\/\+page(\.(server|client))?\.(svelte|js|ts)$/.test(normalizedPath)) return true;
     if (/\/\+layout(\.(server|client))?\.(svelte|js|ts)$/.test(normalizedPath)) return true;
     if (/\/\+error\.(svelte|js|ts)$/.test(normalizedPath)) return true;
     if (/\/\+server\.(js|ts)$/.test(normalizedPath)) return true;
     if (/\/svelte\.config\.(js|ts|mjs)$/.test(normalizedPath)) return true;
 
-    // ── Astro conventions ─────────────────────────────────────────────────────
     if (/\/src\/pages\/.*\.astro$/.test(normalizedPath)) return true;
     if (/\/src\/layouts\/.*\.astro$/.test(normalizedPath)) return true;
     if (/\/astro\.config\.(mjs|js|ts)$/.test(normalizedPath)) return true;
 
-    // ── Nuxt conventions ──────────────────────────────────────────────────────
     if (/\/pages\/.*\.vue$/.test(normalizedPath)) return true;
     if (/\/layouts\/.*\.vue$/.test(normalizedPath)) return true;
     if (/\/server\/api\/.*\.(js|ts)$/.test(normalizedPath)) return true;
     if (/\/nuxt\.config\.(js|ts|mjs)$/.test(normalizedPath)) return true;
 
-    // ── React / Vite entry points ─────────────────────────────────────────────
     if (/\/vite\.config\.(js|ts|mjs)$/.test(normalizedPath)) return true;
 
-    // ── Angular conventions ───────────────────────────────────────────────────
     if (/\/main\.(ts|js)$/.test(normalizedPath)) return true;
     if (/\/app\.module\.(ts|js)$/.test(normalizedPath)) return true;
     if (/\/angular\.json$/.test(normalizedPath)) return true;
 
-    // ── Expo / React Native ───────────────────────────────────────────────────
     if (/\/app\/_layout\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
     if (/\/app\/index\.(js|ts|tsx|jsx)$/.test(normalizedPath)) return true;
 
@@ -176,10 +159,8 @@ export class MagicDetector {
     await this.ensureInitialized();
     if (!await this.isImplicitlyRequiredByEcosystem(filePath, activeFrameworks)) return;
 
-    // Retain entry point elements within memory to keep verification safe
     fileNode.isEntry = true;
 
-    // Apply dynamic exports coverage metrics based on active platform contracts
     const normalizedPath = filePath.replace(/\\/g, '/');
     const plugins = this.registry.getPlugins();
 
@@ -192,7 +173,6 @@ export class MagicDetector {
           const contracts = plugin.getRequiredSystemContracts();
           contracts.forEach(contractMethodToken => {
             if (fileNode.internalExports.has(contractMethodToken)) {
-              // Emulate active local reference linkages to protect the export
               fileNode.instantiatedIdentifiers.add(contractMethodToken);
             }
           });