pkg-scaffold 3.3.4 → 3.3.5

package/README.md

@@ -2,7 +2,7 @@
 
 ![Logo](./logo.png)
 
-> **The Ultimate Enterprise Codebase Janitor.** Faster than Knip with OXC integration, type-aware analysis, and self-healing capabilities. Fully standalone - solving what Knip cannot.
+> **The Ultimate Enterprise Codebase Janitor.** Faster than Knip with OXC integration, type-aware analysis, and automated structural healing. Fully standalone - solving what Knip cannot.
 
 ![Version](https://img.shields.io/npm/v/pkg-scaffold) ![License](https://img.shields.io/badge/license-Apache--2.0-green.svg) ![Performance](https://img.shields.io/badge/performance-OXC--Inside-blueviolet.svg)
 
@@ -15,8 +15,7 @@
 *   **💀 True Dead Code Detection:** Advanced graph-based reachability analysis to find truly dead files and unused exports, even deep within your codebase.
 *   **🔄 Circular Dependency Detection:** High-performance Tarjan-based algorithm to detect and report circular dependencies.
 *   **🛡️ Supply Chain Guard:** Detects typosquatting and verifies integrity lockfile hashes.
-*   **🔐 Secret Detection:** Scans for hardcoded secrets (API keys, tokens) using AST and Regex.
-*   **🛠️ Self-Healing:** Not just reporting, but automatically fixing structural issues (removing dead files, pruning unused dependencies).
+*   **🛠️ Automated Structural Healing:** Not just reporting, but automatically fixing structural issues (removing dead files, pruning unused dependencies) with git-based rollback protection.
 *   **⚙️ Flexible Configuration:** Supports `pkg-scaffold.json`, `pkg-scaffold.ts`, `scaffold.config.js`, and more.
 
 ## 📦 Installation
@@ -26,7 +25,7 @@ npm install -D pkg-scaffold
 # or
 pnpm add -D pkg-scaffold
 # or
-yarn add -D pkg-scaffold
+pnpm add -D pkg-scaffold
 ```
 
 ## 🚀 Usage

package/bin/cli.js

@@ -28,7 +28,7 @@ async function bootstrap() {
     program
       .name('pkg-scaffold')
       .description(ansis.cyan('Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine'))
-      .version(packageJsonContent.version || '3.3.2');
+      .version(packageJsonContent.version || '3.3.5');
 
     program
       .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
@@ -130,7 +130,7 @@ async function bootstrap() {
     }, timeoutMs);
     timeoutTimer.unref(); // Allow process to exit if work finishes
 
-    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.3.2'} Engine Activation`));
+    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.3.5'} 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')}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pkg-scaffold",
-  "version": "3.3.4",
-  "description": "The Ultimate Enterprise Codebase Janitor. Faster than Knip with OXC integration, type-aware analysis, and self-healing capabilities. Fully standalone - solving what Knip cannot.",
+  "version": "3.3.5",
+  "description": "The Ultimate Enterprise Codebase Janitor. Faster than Knip with OXC integration, type-aware analysis, and automated structural healing. Fully standalone - solving what Knip cannot.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -48,7 +48,8 @@
     "package.json",
     "packages",
     "scan",
-    "self-healing",
+
+    "structural-healing",
     "setup",
     "type",
     "types",

package/src/EngineContext.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.3.0: Enterprise In-Memory Codebase State Manifest
+ * 📦 pkg-scaffold v3.3.5: Enterprise In-Memory Codebase State Manifest
  * ============================================================================
  * Implements a high-density, centralized graph database context for tracking
  * software engineering debt, dependencies, types, and vulnerabilities.
@@ -8,6 +8,7 @@
 
 import path from 'path';
 import fs from 'fs/promises';
+import { DependencyProfiler } from './resolution/DependencyProfiler.js';
 
 /**
  * High-Fidelity Graph Element Node representing a single file asset boundary.
@@ -42,8 +43,7 @@ export class GraphNode {
     this.incomingEdges = new Set(); // Set of absolute filePaths depending on this component
     this.outgoingEdges = new Set(); // Set of absolute internal filePaths this component calls
     
-    // Security & Compliance Anomaly Matrices
-    this.securityThreats = [];
+    // Structural Syntax Boundaries
     this.calculatedDynamicImports = [];
     this.localSuppressedRules = new Set();
     this.externalPackageUsage = new Set(); // Tracked third-party package names
@@ -160,6 +160,9 @@ export class EngineContext {
     };
     this.usedExternalPackages = new Set(); // Global set of used npm packages
     this.manifestDependencies = new Map(); // Package.json path -> { dependencies, devDependencies, peerDependencies, optionalDependencies }
+
+    // DependencyProfiler instance for implicit invocation tracing
+    this._depProfiler = new DependencyProfiler(this);
   }
 
   /**
@@ -237,7 +240,7 @@ export class EngineContext {
    * Processes the entire active dependency map to compile structural issue indices.
    * Evaluates orphaned components, dead exports, and supply-chain threats.
    */
-  generateSummaryReport() {
+  async generateSummaryReport() {
     this.metrics.endTime = Date.now();
     const durationSeconds = ((this.metrics.endTime - this.metrics.startTime) / 1000).toFixed(2);
     
@@ -254,7 +257,6 @@ export class EngineContext {
       structuralIssuesDetected: {
         deadFiles: [],
         deadExports: [],
-        securityThreats: [],
         unusedDependencies: []
       },
       modificationsExecuted: {
@@ -266,6 +268,11 @@ export class EngineContext {
     for (const [filePath, node] of this.graph.entries()) {
       // Skip package control files from standard structural dead-code checks
       if (filePath.endsWith('package.json')) continue;
+      
+      // Fix: Always track external package usage from all files, even if they are orphaned,
+      // to prevent false-positive unused dependency reports.
+      node.externalPackageUsage.forEach(pkg => this.usedExternalPackages.add(pkg));
+
       if (this.isPathIgnored(filePath)) continue;
 
       const relativePath = path.relative(this.cwd, filePath);
@@ -299,28 +306,34 @@ export class EngineContext {
         }
       }
 
-      // Category C: Security Vulnerabilities
-      if (node.securityThreats && node.securityThreats.length > 0) {
-        node.securityThreats.forEach(threat => {
-          summary.structuralIssuesDetected.securityThreats.push({
-            file: relativePath,
-            identifier: threat.variableKey,
-            riskCode: threat.riskCode || 'HIGH_RISK_SECRET_LEAK',
-            entropy: threat.entropyValue,
-            line: threat.line || 1
-          });
-        });
-      }
     }
 
     // Category D: Unused Dependencies Audit (Enhanced Classification)
     for (const [manifestPath, manifestData] of this.manifestDependencies.entries()) {
       const relativeManifest = path.relative(this.cwd, manifestPath);
-      
+      const packageRoot = path.dirname(manifestPath);
+
+      // Collect packages that are implicitly used via scripts / config files
+      const implicitlyUsed = await this._depProfiler.traceImplicitInvocations(packageRoot);
+
+      // Resolve peer dependencies of all used packages so they are not flagged
+      const allUsedForPeerResolution = new Set([...this.usedExternalPackages, ...implicitlyUsed]);
+      const peerDepsOfUsed = await this._depProfiler.resolvePeerDependencies(allUsedForPeerResolution, packageRoot);
+
       const checkDeps = (deps, type) => {
         if (!deps) return;
         for (const dep of deps) {
-          if (!this.usedExternalPackages.has(dep)) {
+          // Skip peer and optional dependencies – they are never "unused" in the
+          // traditional sense because they are not required to be imported directly.
+          if (this._depProfiler.shouldExcludeFromUnusedCheck(dep, type)) {
+            continue;
+          }
+
+          const isUsedInCode = this.usedExternalPackages.has(dep);
+          const isUsedImplicitly = implicitlyUsed.has(dep);
+          const isRequiredAsPeer = peerDepsOfUsed.has(dep);
+
+          if (!isUsedInCode && !isUsedImplicitly && !isRequiredAsPeer) {
             summary.structuralIssuesDetected.unusedDependencies.push({
               manifest: relativeManifest,
               package: dep,
@@ -333,6 +346,7 @@ export class EngineContext {
 
       checkDeps(manifestData.dependencies, 'dependency');
       checkDeps(manifestData.devDependencies, 'devDependency');
+      // peerDependencies and optionalDependencies are excluded via shouldExcludeFromUnusedCheck
       checkDeps(manifestData.peerDependencies, 'peerDependency');
       checkDeps(manifestData.optionalDependencies, 'optionalDependency');
     }

package/src/ast/ASTAnalyzer.js

@@ -6,6 +6,16 @@ export class ASTAnalyzer {
     this.scopeStack = [];
   }
 
+  /**
+   * Returns the TypeScript ScriptKind for a given file path.
+   * Exposed as a public method so WorkerTaskRunner can call it directly.
+   */
+  getScriptKind(filePath) {
+    if (filePath.endsWith('.tsx') || filePath.endsWith('.jsx')) return ts.ScriptKind.TSX;
+    if (filePath.endsWith('.js') || filePath.endsWith('.mjs') || filePath.endsWith('.cjs')) return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+  }
+
   parseFile(filePath, content, fileNode) {
     if (this.context.verbose) {
       console.log(`[AST] Parsing: ${filePath}`);
@@ -16,7 +26,7 @@ export class ASTAnalyzer {
       content,
       ts.ScriptTarget.Latest,
       true,
-      filePath.endsWith('.tsx') || filePath.endsWith('.jsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+      this.getScriptKind(filePath)
     );
 
     this.currentScope = { symbols: new Map(), parent: null };
@@ -29,6 +39,13 @@ export class ASTAnalyzer {
     this.currentScope = null;
   }
 
+  /**
+   * Alias for walkAST used by WorkerTaskRunner (legacy API compatibility).
+   */
+  walkNode(node, sourceFile, fileNode) {
+    return this.walkAST(node, fileNode, sourceFile);
+  }
+
   pushScope() {
     const newScope = { symbols: new Map(), parent: this.currentScope };
     this.scopeStack.push(newScope);
@@ -87,6 +104,16 @@ export class ASTAnalyzer {
       case ts.SyntaxKind.ModuleDeclaration:
         this.handleNamedDeclaration(node, fileNode, sourceFile);
         break;
+      case ts.SyntaxKind.Identifier:
+        fileNode.instantiatedIdentifiers.add(node.text);
+        break;
+      case ts.SyntaxKind.StringLiteral:
+      case ts.SyntaxKind.NoSubstitutionTemplateLiteral:
+        fileNode.rawStringReferences.add(node.text);
+        break;
+      case ts.SyntaxKind.PropertyAccessExpression:
+        fileNode.propertyAccessChains.add(node.getText(sourceFile));
+        break;
       case ts.SyntaxKind.CallExpression:
         this.handleCallExpression(node, fileNode, sourceFile);
         break;
@@ -97,13 +124,6 @@ export class ASTAnalyzer {
       case ts.SyntaxKind.Decorator:
         this.handleDecorator(node, fileNode, sourceFile);
         break;
-      case ts.SyntaxKind.Identifier:
-        // Track usage of identifiers
-        const symbol = this.resolveSymbol(node.text);
-        if (symbol) {
-          // fileNode.usedSymbols.add(`${symbol.node.parent.kind}:${node.text}`); // More granular tracking needed
-        }
-        break;
     }
 
     ts.forEachChild(node, child => this.walkAST(child, fileNode, sourceFile));
@@ -117,88 +137,67 @@ export class ASTAnalyzer {
     if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
       const specifier = node.moduleSpecifier.text;
       fileNode.explicitImports.add(specifier);
+      
+      // Track external package usage for dependency analysis
+      if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
+        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+      }
 
       if (node.importClause) {
+        if (node.importClause.name) {
+          fileNode.importedSymbols.add(`${specifier}:default`);
+        }
         if (node.importClause.namedBindings) {
-          if (ts.isNamedImports(node.importClause.namedBindings)) {
+          if (ts.isNamespaceImport(node.importClause.namedBindings)) {
+            fileNode.importedSymbols.add(`${specifier}:*`);
+          } else if (ts.isNamedImports(node.importClause.namedBindings)) {
             node.importClause.namedBindings.elements.forEach(element => {
-              const importedName = element.name.text;
-              const propertyName = element.propertyName ? element.propertyName.text : importedName;
-              fileNode.importedSymbols.add(`${specifier}:${propertyName}`);
-              this.addDeclaredSymbol(element.name.text, element, sourceFile); // Add local import name to scope
+              const importedName = element.propertyName ? element.propertyName.text : element.name.text;
+              fileNode.importedSymbols.add(`${specifier}:${importedName}`);
             });
-          } else if (ts.isNamespaceImport(node.importClause.namedBindings)) {
-            fileNode.importedSymbols.add(`${specifier}:*`);
-            this.addDeclaredSymbol(node.importClause.namedBindings.name.text, node.importClause.namedBindings, sourceFile); // Add namespace import to scope
           }
         }
-        if (node.importClause.name) {
-          fileNode.importedSymbols.add(`${specifier}:default`);
-          this.addDeclaredSymbol(node.importClause.name.text, node.importClause.name, sourceFile); // Add default import to scope
-        }
       }
     }
   }
 
   handleExportDeclaration(node, fileNode, sourceFile) {
-    if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
-      const specifier = node.moduleSpecifier.text;
-      if (node.exportClause && ts.isNamedExports(node.exportClause)) {
-        node.exportClause.elements.forEach(element => {
-          const name = element.name.text;
-          const propertyName = element.propertyName ? element.propertyName.text : name;
-          fileNode.internalExports.set(name, { 
-            type: 're-export', 
-            source: specifier,
-            originalName: propertyName,
-            start: node.getStart(sourceFile), 
-            end: node.getEnd() 
-          });
-        });
-      } else if (node.exportClause && ts.isNamespaceExport(node.exportClause)) {
-        // export * as name from 'module'
+    const specifier = node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) ? node.moduleSpecifier.text : null;
+    
+    if (specifier) {
+      // Re-export from source: export * from './module' or export { x } from './module'
+      fileNode.explicitImports.add(specifier);
+      
+      // Track external package usage from re-exports
+      if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
+        fileNode.externalPackageUsage.add(this._extractPackageName(specifier));
+      }
+
+      if (!node.exportClause) {
+        // export * from './module'
+        fileNode.internalExports.set('*', { type: 're-export-all', source: specifier });
+        fileNode.importedSymbols.add(`${specifier}:*`);
+      } else if (ts.isNamespaceExport(node.exportClause)) {
+        // export * as name from './module'
         const name = node.exportClause.name.text;
         fileNode.internalExports.set(name, { type: 're-export-namespace', source: specifier, originalName: '*', start: node.getStart(sourceFile), end: node.getEnd() });
-      } else {
-        // export * from 'module'
-        fileNode.internalExports.set('*', { type: 're-export-all', source: specifier });
-      }
-    } else if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        fileNode.importedSymbols.add(`${specifier}:*`);
+      } else if (ts.isNamedExports(node.exportClause)) {
+        // export { x, y as z } from './module'
         node.exportClause.elements.forEach(element => {
-          const name = element.name.text;
-          const propertyName = element.propertyName ? element.propertyName.text : name;
-          fileNode.internalExports.set(name, { 
-            type: 'export', 
-            originalName: propertyName,
-            start: node.getStart(sourceFile), 
-            end: node.getEnd() 
-          });
+          const originalName = element.propertyName ? element.propertyName.text : element.name.text;
+          const exportedName = element.name.text;
+          fileNode.internalExports.set(exportedName, { type: 're-export', source: specifier, originalName, start: element.getStart(sourceFile), end: element.getEnd() });
+          fileNode.importedSymbols.add(`${specifier}:${originalName}`);
         });
-    } else if (node.declaration) {
-      // Direct export of a declaration (e.g., export const x = 1;)
-      if (ts.isVariableStatement(node.declaration)) {
-        node.declaration.declarationList.declarations.forEach(decl => {
-          if (decl.name && ts.isIdentifier(decl.name)) {
-            const name = decl.name.text;
-            fileNode.internalExports.set(name, { 
-              type: 'variable', 
-              start: decl.getStart(sourceFile), 
-              end: decl.getEnd() 
-            });
-            this.addDeclaredSymbol(name, decl, sourceFile);
-          }
-        });
-      } else if (ts.isFunctionDeclaration(node.declaration) || ts.isClassDeclaration(node.declaration)) {
-        const name = node.declaration.name?.text;
-        if (name) {
-          fileNode.internalExports.set(name, { 
-            type: ts.SyntaxKind[node.declaration.kind].toLowerCase().replace('declaration', ''), 
-            start: node.declaration.getStart(sourceFile), 
-            end: node.declaration.getEnd() 
-          });
-          this.addDeclaredSymbol(name, node.declaration, sourceFile);
-        }
       }
+    } else if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+      // Local named exports: export { x, y as z }
+      node.exportClause.elements.forEach(element => {
+        const localName = element.propertyName ? element.propertyName.text : element.name.text;
+        const exportedName = element.name.text;
+        fileNode.internalExports.set(exportedName, { type: 'export', originalName: localName, start: element.getStart(sourceFile), end: element.getEnd() });
+      });
     }
   }
 
@@ -325,16 +324,32 @@ export class ASTAnalyzer {
   }
 
   handleCallExpression(node, fileNode, sourceFile) {
+    // Dynamic import(): import('./module').then(...)
     if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
       const arg = node.arguments[0];
-      if (arg && ts.isStringLiteral(arg)) {
-        fileNode.explicitImports.add(arg.text);
-        fileNode.dynamicImports.add(arg.text);
+      if (arg) {
+        if (ts.isStringLiteral(arg)) {
+          fileNode.explicitImports.add(arg.text);
+          fileNode.dynamicImports.add(arg.text);
+          // Track external package usage from dynamic imports
+          if (!arg.text.startsWith('.') && !arg.text.startsWith('/')) {
+            fileNode.externalPackageUsage.add(this._extractPackageName(arg.text));
+          }
+        } else {
+          // Dynamic import with a non-literal expression (e.g., variable or template literal).
+          if (fileNode.calculatedDynamicImports) {
+            fileNode.calculatedDynamicImports.push({ kind: ts.SyntaxKind[arg.kind], start: arg.getStart(sourceFile) });
+          }
+        }
       }
     } else if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
       const arg = node.arguments[0];
       if (arg && ts.isStringLiteral(arg)) {
         fileNode.explicitImports.add(arg.text);
+        // Track external package usage from require() calls
+        if (!arg.text.startsWith('.') && !arg.text.startsWith('/')) {
+          fileNode.externalPackageUsage.add(this._extractPackageName(arg.text));
+        }
       }
     }
   }
@@ -371,7 +386,6 @@ export class ASTAnalyzer {
     if (ts.isCallExpression(node.expression)) {
       node.expression.arguments.forEach(arg => {
         // Further analysis of arguments can be done here if needed
-        // e.g., if (ts.isStringLiteral(arg)) fileNode.decoratorArgs.add(`${decoratorName}:${arg.text}`);
       });
     }
   }
@@ -391,4 +405,18 @@ export class ASTAnalyzer {
       }
     }
   }
+
+  /**
+   * Extracts the root npm package name from an import specifier.
+   * Handles scoped packages (@scope/pkg) and subpath imports (pkg/utils, @scope/pkg/utils).
+   */
+  _extractPackageName(specifier) {
+    if (specifier.startsWith('@')) {
+      // Scoped package: @scope/name or @scope/name/subpath
+      const parts = specifier.split('/');
+      return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : specifier;
+    }
+    // Regular package: name or name/subpath
+    return specifier.split('/')[0];
+  }
 }

package/src/ast/BarrelParser.js

@@ -178,19 +178,39 @@ export class BarrelParser {
     }
 
     // Rule D: Sweep through anonymous star re-exports vectors (export * from 'module')
+    //
+    // Algorithm:
+    // 1. For each `export * from './child'`, recursively resolve the symbol in the child.
+    // 2. A non-barrel child immediately returns `{ originFile: childPath }` regardless of
+    //    whether it actually declares the symbol.  We therefore must verify that the
+    //    returned origin file actually contains the symbol in its declaredLocalExports
+    //    before accepting the result.
+    // 3. If the child is itself a barrel, the recursive call already performs the full
+    //    chain walk, so we only need to verify the final origin.
     for (const relativePath of spec.wildcardExports) {
       const fullyResolvedPath = this.resolver.resolveModulePath(contextFilePath, relativePath);
       
       if (fullyResolvedPath) {
-        // Look inside the graph metadata map configuration to verify child target availability
         const continuousResolutionTrace = await this.determineSymbolDeclarationOrigin(
           fullyResolvedPath,
           targetSymbolName,
           activeProjectGraph,
-          protectionStack
+          new Set(protectionStack) // Use a copy so sibling branches don't block each other
         );
-        // If a resolution was found in a child barrel, return it
-        if (continuousResolutionTrace && continuousResolutionTrace.originFile !== fullyResolvedPath) {
+
+        if (!continuousResolutionTrace) continue;
+        if (continuousResolutionTrace.originFile === contextFilePath) continue;
+
+        // Verify that the resolved origin actually declares the symbol.
+        // This prevents a non-barrel sibling (e.g. constants.ts) from being
+        // incorrectly returned for a symbol it does not export (e.g. formatData).
+        const originSpec = await this.parseBarrelSpecification(continuousResolutionTrace.originFile);
+        if (originSpec.declaredLocalExports.has(continuousResolutionTrace.originSymbol)) {
+          return continuousResolutionTrace;
+        }
+        // The origin spec is itself a barrel (isBarrelInstance = true) and the
+        // recursive call already resolved through it – accept the result.
+        if (originSpec.isBarrelInstance) {
           return continuousResolutionTrace;
         }
       }

package/src/ast/MagicDetector.js

@@ -6,6 +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.
+ *
+ * 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) {
@@ -60,20 +69,109 @@ export class MagicDetector {
   }
 
   isCoreToolingSuiteElement(normalizedPath) {
-    // Testing and execution matrices rules configuration keys
-    if (/\.(test|spec|e2e|cy)\.(js|ts|tsx|jsx|stories\.tsx|stories\.ts)$/i.test(normalizedPath)) return true;
-    
-    // Testing tools and structural environment frameworks configuration keys
-    const testEnvironments = [
-      'jest.config.', 'vitest.config.', 'playwright.config.', 'cypress.config.',
-      'webpack.config.', 'vite.config.', 'rollup.config.', 'tailwind.config.',
-      '.eslintrc.', 'prettier.config.', '.postcssrc.', 'postcss.config.',
-      'bin/cli.js', 'index.js', 'WorkerTaskRunner.js',
-      'src/server.ts', 'src/main.ts', 'src/app.ts', 'src/index.tsx', 'src/index.ts',
-      'server.ts', 'main.ts', 'app.ts'
+    // ── 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'
     ];
-    
-    return testEnvironments.some(matchPattern => normalizedPath.includes(matchPattern));
+    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
+      '/src/server.ts', '/src/server.js',
+      '/src/main.ts', '/src/main.js',
+      '/src/app.ts', '/src/app.js',
+      '/src/index.ts', '/src/index.tsx',
+      '/src/index.js', '/src/index.jsx',
+      '/server.ts', '/server.js',
+      '/main.ts', '/main.js',
+      '/app.ts', '/app.js',
+      '/index.ts', '/index.tsx',
+      '/index.js', '/index.jsx',
+    ];
+    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;
+
+    return false;
   }
 
   /**