entkapp 5.4.0 → 5.5.0

package/README.md

@@ -1,4 +1,4 @@
-# 🕸️ entkapp Ultimate v5.4.0
+# 🕸️ entkapp Ultimate v5.5.0
 
 > **The Ultimate Enterprise Codebase Janitor.** High-speed OXC integration, type-aware analysis, and automated structural healing. Fully standalone architectural orchestrator.
 
@@ -35,6 +35,12 @@ 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 @@
 
 /**
  * ============================================================================
- * 🚀 entkapp: The High-Performance Codebase Orchestrator
+ * 🏁 loui CLI Entry Point
  * ============================================================================
- * Command-line interface for executing architectural audits, structural 
- * refactoring cycles, and autonomous codebase healing.
+ * Handles option compilation, environment orchestration, option validation,
+ * and initiates the primary operational pipeline loop.
  */
 
 import { Command } from 'commander';
@@ -13,104 +13,163 @@ import ansis from 'ansis';
 import path from 'path';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
-import { ConfigLoader } from '../src/resolution/ConfigLoader.js';
+import readline from 'readline/promises';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(await fs.readFile(path.join(__dirname, '../package.json'), 'utf8'));
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const program = new Command();
 
-async function main() {
+async function bootstrap() {
   try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
     program
       .name('entkapp')
-      .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)
+      .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)
       .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 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`));
+
+    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;
+    }
+
+    // --- Timeout Handling ---
+    const timeoutMs = parseInt(options.timeout);
     const timeoutTimer = setTimeout(() => {
-      console.error(ansis.red(`\n❌ Execution Timeout: Operation exceeded ${options.timeout}ms limit.`));
+      console.error(ansis.bold.red(`\n🚨 Execution Timeout: The process exceeded the limit of ${timeoutMs}ms.`));
       process.exit(1);
-    }, parseInt(options.timeout));
+    }, timeoutMs);
+    timeoutTimer.unref(); // Allow process to exit if work finishes
 
-    console.log('\n' + ansis.bold.cyan(`📦 entkapp v${pkg.version} Engine Activation`));
+    console.log(ansis.bold.green(`\n📦 entkapp v${packageJsonContent.version || '5.3.1'} Engine Activation`));
     console.log(ansis.dim('------------------------------------------------------------'));
-    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.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.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 || localConfig.workspace || false,
+      workspace: options.workspace,
       verbose: options.verbose,
       skipConfirm: options.yes,
-      entryPoints: entryPoints,
-      exclude: localConfig.exclude || [],
-      rules: localConfig.rules || {},
+      // Pass through local config settings
+      entryPoints: localConfig.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);
-  } catch (err) {
-    console.error(ansis.red(`\n❌ Engine Failure: ${err.message}`));
-    if (program.opts().verbose) console.error(err);
+    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));
+    }
     process.exit(1);
   }
 }
 
-main();
+bootstrap();

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "name": "entkapp",
-  "version": "5.4.0",
+  "version": "5.5.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,12 +419,6 @@ 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,16 +265,7 @@ export class ASTAnalyzer {
                 fileNode.explicitImports.add(specifier);
                 fileNode.importedSymbols.add(`${specifier}:*`);
                 if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-                  // 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);
+                  fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
                 }
               } else if (arg && ts.isTemplateExpression(arg)) {
                 // Dynamic require with template literal
@@ -360,40 +351,8 @@ 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('/')) {
-        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);
-        }
+        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
       }
 
       if (this.context.workspaceGraph && typeof this.context.workspaceGraph.auditImportSpecifier === 'function') {
@@ -414,29 +373,14 @@ 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
@@ -479,22 +423,7 @@ export class ASTAnalyzer {
     if (specifier) {
       fileNode.explicitImports.add(specifier);
       if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-        // 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);
-        }
+        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
       }
 
       if (!node.exportClause) {
@@ -658,16 +587,7 @@ export class ASTAnalyzer {
           fileNode.dynamicImports.add(specifier);
           fileNode.importedSymbols.add(`${specifier}:*`);
           if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-            // 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);
+            fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
           }
         } else {
           // Non-literal dynamic import
@@ -688,17 +608,9 @@ export class ASTAnalyzer {
         if (this.context.verbose) console.log(`[AST-DEBUG] Added import: ${specifier}`);
         fileNode.explicitImports.add(specifier);
         
-        // UPGRADE: Apply alias/workspace filtering before adding to externalPackageUsage
+        // UPGRADE: Also track package usage for unlisted dependency detection
         if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
-          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);
+          fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
         }
       }
     }

package/src/ast/MagicDetector.js

@@ -6,7 +6,15 @@ 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.
- * Version 5.4.0: Added detectEntryPointsFromPlugins() for dynamic framework entry detection.
+ *
+ * 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
  */
 export class MagicDetector {
   constructor(context) {
@@ -23,26 +31,18 @@ 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,6 +60,7 @@ export class MagicDetector {
       }
     }
 
+    // Apply baseline platform rules (Test suites, lint parameters, continuous integration files)
     if (this.isCoreToolingSuiteElement(normalizedSystemPath)) {
       return true;
     }
@@ -67,46 +68,49 @@ 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',
-      // Standard package entry points (poly-extension support)
-      '/index.js', '/index.ts', '/index.jsx', '/index.tsx', '/index.mjs', '/index.cjs',
-      // Server / app entry points
+      // Server / app entry points (Reduced in v3.3.8 to avoid false positives in libraries)
       '/src/main.ts', '/src/main.js',
       '/src/app.ts', '/src/app.js',
       '/src/api/HeadlessAPI.js', '/src/api/PluginSDK.js',
@@ -115,37 +119,50 @@ 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;
 
@@ -159,8 +176,10 @@ 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();
 
@@ -173,6 +192,7 @@ 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);
             }
           });