entkapp 4.1.0

package/package.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "name": "entkapp",
+  "version": "4.1.0",
+  "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": {
+    "entkapp": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "entkapp:run": "npx entkapp --fix",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test:stability": "npm run test",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs && cp docs/sitemap.xml docs/.vitepress/dist/ && cp docs/robots.txt docs/.vitepress/dist && cp logo.png docs/.vitepress/dist",
+    "docs:preview": "vitepress preview docs"
+  },
+  "keywords": [
+    "analysis",
+    "analyze",
+    "ast",
+    "automation",
+    "cli",
+    "gui",
+    "class",
+    "dead-code",
+    "dependencies",
+    "dependency-analysis",
+    "dependency-audit",
+    "detect",
+    "devDependencies",
+    "duplicate",
+    "entropy",
+    "enum",
+    "export",
+    "files",
+    "find",
+    "ghost-dependencies",
+    "javascript",
+    "maintenance",
+    "members",
+    "missing",
+    "missing-imports",
+    "monorepo",
+    "namespace",
+    "oxc",
+    "package.json",
+    "packages",
+    "scan",
+    "security",
+    "secret-scanner",
+    "secrets",
+    "hardcoded-secrets",
+    "credentials",
+    "audit",
+    "structural-healing",
+    "setup",
+    "type",
+    "types",
+    "typescript",
+    "unreferenced",
+    "unresolved",
+    "unused",
+    "unused-packages",
+    "workspace"
+  ],
+  "author": "DreamLongYT",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DreamLongYT/entkapp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DreamLongYT/entkapp/issues"
+  },
+  "homepage": "https://dreamlongyt.github.io/entkapp/",
+  "dependencies": {
+    "ansis": "^3.0.0",
+    "commander": "^12.0.0",
+    "enhanced-resolve": "^5.16.0",
+    "execa": "^8.0.1",
+    "oxc-parser": "^0.135.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "knip": "^6.17.1",
+    "vitepress": "^1.6.4",
+    "vue": ">=3.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/EngineContext.js

@@ -0,0 +1,185 @@
+import path from 'path';
+
+/**
+ * Core In-Memory Graph Node Representation.
+ * Tracks structural metadata, dependencies, and usage metrics for a single file.
+ */
+export class GraphNode {
+  constructor(filePath) {
+    this.filePath = filePath;
+    this.incomingEdges = new Set(); // Files that import THIS file
+    this.outgoingEdges = new Set(); // Files that THIS file imports
+    
+    this.explicitImports = new Set(); // Raw import strings
+    this.importedSymbols = new Set(); // "file:symbol" or "file:*"
+    this.internalExports = new Map(); // symbol -> { type, start, end, ... }
+    
+    this.externalPackageUsage = new Set();
+    this.instantiatedIdentifiers = new Set();
+    this.propertyAccessChains = new Set();
+    this.rawStringReferences = new Set();
+    this.jsxComponents = new Set();
+    this.jsxProps = new Set();
+    this.decorators = new Set();
+    this.dynamicImports = new Set();
+    this.calculatedDynamicImports = [];
+    
+    this.isEntry = false;
+    this.isLibraryEntry = false;
+    this.isFrameworkComponent = false;
+    this.symbolSourceLocations = new Map(); // symbol -> { line, column }
+    this.localSuppressedRules = new Set();
+  }
+
+  isSymbolReferencedExternally(symbolName, projectGraph) {
+    if (this.isLibraryEntry) return true;
+
+    // --- NEW: Self-reference check (Fix for SecretSeverity bug) ---
+    // If the symbol is used within the same file, it is NOT dead.
+    if (this.instantiatedIdentifiers.has(symbolName)) return true;
+    
+    // Check property access in the same file
+    for (const accessChain of this.propertyAccessChains) {
+      if (accessChain.endsWith(`.${symbolName}`) || accessChain.includes(`.${symbolName}.`)) {
+        return true;
+      }
+    }
+    // --------------------------------------------------------------
+    
+    for (const parentPath of this.incomingEdges) {
+      const parentNode = projectGraph.get(parentPath);
+      if (!parentNode) continue;
+
+      // Strategy 1: Check absolute path based tokens
+      const absoluteImportKey = `${this.filePath}:${symbolName}`;
+      const absoluteStarKey = `${this.filePath}:*`;
+      
+      if (parentNode.importedSymbols.has(absoluteImportKey) || parentNode.importedSymbols.has(absoluteStarKey)) {
+        return true;
+      }
+
+      // Strategy 2: Check relative path based tokens
+      const relativePath = path.relative(path.dirname(parentPath), this.filePath).replace(/\\/g, '/');
+      const relativePathNoExt = relativePath.replace(/\.(js|ts|tsx|jsx)$/, '');
+      
+      const importKey = `${relativePath}:${symbolName}`;
+      const importKeyAlt = `${relativePathNoExt}:${symbolName}`;
+      const starKey = `${relativePath}:*`;
+      const starKeyAlt = `${relativePathNoExt}:*`;
+      
+      if (parentNode.importedSymbols.has(importKey) || parentNode.importedSymbols.has(importKeyAlt) ||
+          parentNode.importedSymbols.has(starKey) || parentNode.importedSymbols.has(starKeyAlt)) {
+        return true;
+      }
+
+      if (parentNode.instantiatedIdentifiers.has(symbolName)) return true;
+      
+      for (const accessChain of parentNode.propertyAccessChains) {
+        if (accessChain.endsWith(`.${symbolName}`) || accessChain.includes(`.${symbolName}.`)) {
+          return true;
+        }
+      }
+
+      if (parentNode.rawStringReferences.has(symbolName)) return true;
+      if (parentNode.jsxComponents.has(symbolName)) return true;
+
+      for (const jsxProp of parentNode.jsxProps) {
+        if (jsxProp.endsWith(`:${symbolName}`)) return true;
+      }
+
+      if (parentNode.decorators.has(symbolName)) return true;
+    }
+
+    return false;
+  }
+}
+
+export class EngineContext {
+  constructor(cwd) {
+    // FIX: Ensure cwd is always defined, fallback to process.cwd()
+    this.cwd = cwd || process.cwd();
+    this.projectGraph = new Map(); // Path -> GraphNode
+    this.usedExternalPackages = new Set();
+    this.unimportedUsedPackages = new Set(); // NEW: For "Unimported but used"
+    this.importedUnusedPackages = new Set(); // NEW: For "Imported but unused"
+    this.unusedBinaries = new Set();         // NEW: For "Unused Binaries"
+    this.manifestDependencies = new Map();   // NEW: Store dependencies from package.json
+    
+    this.isWorkspaceEnabled = false;
+    this.monorepoPackageRoots = new Set();
+    this.verbose = false;
+    this.metrics = { totalFilesScanned: 0, cacheHits: 0, cacheMisses: 0 };
+    this.allSecretFindings = [];
+  }
+
+  getOrCreateNode(filePath) {
+    if (!this.projectGraph.has(filePath)) {
+      this.projectGraph.set(filePath, new GraphNode(filePath));
+    }
+    return this.projectGraph.get(filePath);
+  }
+
+  generateSummaryReport() {
+    const report = {
+      orphanedFiles: [],
+      deadExports: [],
+      unusedDependencies: [],
+      unimportedUsedPackages: [], // NEW
+      importedUnusedPackages: [], // NEW
+      unusedBinaries: []          // NEW
+    };
+
+    // 1. Files & Exports
+    for (const [filePath, node] of this.projectGraph.entries()) {
+      const isSuppressed = node.localSuppressedRules.has('*') || node.localSuppressedRules.has('unused-file');
+      
+      if (node.incomingEdges.size === 0 && !node.isEntry && !node.isLibraryEntry && !node.isFrameworkComponent && !isSuppressed) {
+        report.orphanedFiles.push(path.relative(this.cwd, filePath));
+      }
+
+      for (const [symbol, meta] of node.internalExports.entries()) {
+        if (symbol === '*' || symbol === 'default' || node.localSuppressedRules.has('unused-export') || node.localSuppressedRules.has(`unused-export:${symbol}`)) {
+          continue;
+        }
+
+        if (!node.isSymbolReferencedExternally(symbol, this.projectGraph)) {
+          const loc = node.symbolSourceLocations.get(symbol) || { line: 0, column: 0 };
+          report.deadExports.push({
+            symbol,
+            file: path.relative(this.cwd, filePath),
+            line: loc.line
+          });
+        }
+      }
+    }
+
+    // 2. Dependency Analysis (Extended)
+    // Compare manifest dependencies with actually used packages
+    for (const [manifestPath, deps] of this.manifestDependencies.entries()) {
+      const allDeps = [...(deps.dependencies || []), ...(deps.devDependencies || [])];
+      
+      for (const dep of allDeps) {
+        // Skip @types packages and known safe packages
+        if (dep.startsWith('@types/') || dep === 'entkapp') {
+          continue;
+        }
+        
+        // Check if the dependency is actually used in the code
+        if (!this.usedExternalPackages.has(dep)) {
+          report.unusedDependencies.push({
+            package: dep,
+            type: deps.dependencies.includes(dep) ? 'dependency' : 'devDependency',
+            manifest: path.relative(this.cwd, manifestPath)
+          });
+          this.importedUnusedPackages.add(dep);
+        }
+      }
+    }
+    
+    report.unimportedUsedPackages = Array.from(this.unimportedUsedPackages);
+    report.importedUnusedPackages = Array.from(this.importedUnusedPackages);
+    report.unusedBinaries = Array.from(this.unusedBinaries);
+
+    return report;
+  }
+}

package/src/api/HeadlessAPI.js

@@ -0,0 +1,376 @@
+/**
+ * ============================================================================
+ * Headless API for entkapp v4.1.0
+ * ============================================================================
+ * Provides a programmatic interface for integrating entkapp into
+ * custom workflows, CI/CD pipelines, and third-party tools.
+ * 
+ * Features:
+ * - Full control over analysis and refactoring operations
+ * - Event-driven architecture for real-time feedback
+ * - Streaming results for large codebases
+ * - Plugin SDK integration
+ */
+
+import EventEmitter from 'events';
+import path from 'path';
+import { RefactoringEngine } from '../index.js';
+
+export class HeadlessAPI extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = options;
+    this.engine = null;
+    this.analysisResults = null;
+    this.isRunning = false;
+  }
+
+  /**
+   * Initialize the API with a project context
+   * @param {string} projectRoot - Root directory of the project
+   * @param {Object} config - Configuration options
+   * @returns {Promise<void>}
+   */
+  async initialize(projectRoot, config = {}) {
+    try {
+      this.emit('initialize:start', { projectRoot });
+
+      const engineOptions = {
+        cwd: projectRoot,
+        autoFix: config.autoFix !== false,
+        skipConfirm: config.skipConfirm || false,
+        verbose: config.verbose || false,
+        ...config
+      };
+
+      this.engine = new RefactoringEngine(engineOptions);
+
+      this.emit('initialize:complete', {
+        projectRoot,
+        config: this.engine.context
+      });
+    } catch (error) {
+      this.emit('initialize:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Analyze the codebase without making changes
+   * @returns {Promise<Object>} Analysis results
+   */
+  async analyze() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    try {
+      this.isRunning = true;
+      this.emit('analysis:start');
+
+      // Initialize path mappings and workspace graph
+      await this.engine.pathMapper.loadMappings(this.engine.context.tsconfigFilename);
+
+      if (this.engine.context.isWorkspaceEnabled) {
+        this.emit('analysis:workspace-mapping-start');
+        await this.engine.workspaceGraph.initializeWorkspaceMesh();
+        this.emit('analysis:workspace-mapping-complete');
+      }
+
+      // Load cache manifest
+      const cacheManifest = await this.engine.cacheManager.loadCacheManifest();
+
+      // Discover source files
+      this.emit('analysis:file-discovery-start');
+      const fileList = [];
+      await this.engine.discoverSourceFiles(this.engine.context.cwd, fileList);
+      this.engine.context.metrics.totalFilesScanned = fileList.length;
+      this.emit('analysis:file-discovery-complete', { fileCount: fileList.length });
+
+      // Identify framework ecosystems
+      this.emit('analysis:framework-detection-start');
+      const activeFrameworkEcosystems = await this.engine.magicDetector.identifyActiveProjectEcosystems(
+        this.engine.context.cwd
+      );
+      this.emit('analysis:framework-detection-complete', { ecosystems: activeFrameworkEcosystems });
+
+      // Process files
+      this.emit('analysis:file-processing-start');
+      const sourceCodeFilesList = [];
+      for (const file of fileList) {
+        if (file.endsWith('package.json')) {
+          await this.engine.auditManifestSupplyChain(file);
+        } else {
+          sourceCodeFilesList.push(file);
+        }
+      }
+
+      // Initialize TypeScript program for AST analysis (required before processFile)
+      if (sourceCodeFilesList.length > 0) {
+        try {
+          this.engine.analyzer.initProgram(sourceCodeFilesList);
+        } catch (e) {
+          if (this.engine.context.verbose) {
+            console.warn('Warning: Failed to initialize TypeScript program:', e.message);
+          }
+        }
+      }
+
+      // Parallel processing
+      let parallelParseCompleted = false;
+      if (sourceCodeFilesList.length > 10) {
+        parallelParseCompleted = await this.engine.workerPool.parallelAnalyzeCodebase(
+          sourceCodeFilesList,
+          this.engine
+        );
+      }
+
+      // Sequential processing
+      for (let i = 0; i < sourceCodeFilesList.length; i++) {
+        const filePath = sourceCodeFilesList[i];
+        const node = this.engine.context.getOrCreateNode(filePath);
+        const currentHash = await this.engine.cacheManager.computeHash(filePath);
+        node.contentHash = currentHash;
+
+        const isFileCached = cacheManifest[filePath] && cacheManifest[filePath].hash === currentHash;
+
+        if (isFileCached) {
+          this.engine.context.metrics.cacheHits++;
+          this.engine.hydrateNodeFromCache(node, cacheManifest[filePath]);
+        } else if (!parallelParseCompleted) {
+          this.engine.context.metrics.cacheMisses++;
+          await this.engine.analyzer.parseFile(filePath, "", node);
+        }
+
+        this.engine.magicDetector.injectVirtualConsumerEdges(filePath, node, activeFrameworkEcosystems);
+        node.externalPackageUsage.forEach(pkg => this.engine.context.usedExternalPackages.add(pkg));
+
+        // Emit progress
+        if ((i + 1) % Math.ceil(sourceCodeFilesList.length / 10) === 0) {
+          this.emit('analysis:file-processing-progress', {
+            processed: i + 1,
+            total: sourceCodeFilesList.length,
+            percentage: Math.round(((i + 1) / sourceCodeFilesList.length) * 100)
+          });
+        }
+      }
+
+      // Link dependency graph
+      this.emit('analysis:graph-linking-start');
+      await this.engine.linkDependencyGraph();
+      this.emit('analysis:graph-linking-complete');
+
+      // Generate summary
+      this.analysisResults = this.engine.context.generateSummaryReport();
+      this.emit('analysis:complete', this.analysisResults);
+
+      this.isRunning = false;
+      return this.analysisResults;
+    } catch (error) {
+      this.isRunning = false;
+      this.emit('analysis:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Get detailed impact analysis for a specific file or export
+   * @param {string} filePath - Path to the file
+   * @param {string} symbol - Optional: specific export symbol to analyze
+   * @returns {Promise<Object>} Impact analysis results
+   */
+  async getImpactAnalysis(filePath, symbol = null) {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    try {
+      const node = this.engine.context.projectGraph.get(filePath);
+      if (!node) {
+        throw new Error(`File not found in analysis graph: ${filePath}`);
+      }
+
+      const impact = {
+        file: filePath,
+        symbol,
+        directDependents: Array.from(node.incomingEdges),
+        dependencies: Array.from(node.outgoingEdges),
+        internalExports: symbol
+          ? [symbol]
+          : Array.from(node.internalExports.keys()),
+        externalPackages: Array.from(node.externalPackageUsage)
+      };
+
+      if (symbol) {
+        const safety = await this.engine.impactAnalyzer.verifyRefactorSafety(
+          filePath,
+          symbol,
+          this.engine.context.projectGraph
+        );
+        impact.refactorSafety = safety;
+      }
+
+      return impact;
+    } catch (error) {
+      this.emit('impact-analysis:error', { error, filePath, symbol });
+      throw error;
+    }
+  }
+
+  /**
+   * Apply refactoring changes with automatic rollback on test failure
+   * @param {Object} changes - Changes to apply
+   * @returns {Promise<Object>} Refactoring results
+   */
+  async applyRefactoring(changes = {}) {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+
+    if (!this.analysisResults) {
+      throw new Error('No analysis results available. Call analyze() first.');
+    }
+
+    try {
+      this.isRunning = true;
+      this.emit('refactoring:start', changes);
+
+      const refactoringResults = {
+        filesDeleted: [],
+        exportsRemoved: [],
+        dependenciesRemoved: [],
+        errors: []
+      };
+
+      await this.engine.selfHealer.runSelfHealingLifecycle(async () => {
+        // Delete dead files
+        const filesToDelete = changes.deleteDeadFiles !== false
+          ? this.analysisResults.orphanedFiles
+          : [];
+
+        for (const relPath of filesToDelete) {
+          try {
+            const absPath = path.resolve(this.engine.context.cwd, relPath);
+            await this.engine.txManager.stageDeletion(absPath);
+            refactoringResults.filesDeleted.push(relPath);
+            this.emit('refactoring:file-deleted', { file: relPath });
+          } catch (error) {
+            refactoringResults.errors.push({ type: 'file-deletion', file: relPath, error: error.message });
+            this.emit('refactoring:error', { type: 'file-deletion', file: relPath, error });
+          }
+        }
+
+        // Remove unused exports
+        const exportsToRemove = changes.removeUnusedExports !== false
+          ? this.analysisResults.deadExports
+          : [];
+
+        for (const unusedExport of exportsToRemove) {
+          try {
+            const absPath = path.resolve(this.engine.context.cwd, unusedExport.file);
+            const node = this.engine.context.projectGraph.get(absPath);
+
+            if (node) {
+              const safety = await this.engine.impactAnalyzer.verifyRefactorSafety(
+                absPath,
+                unusedExport.symbol,
+                this.engine.context.projectGraph
+              );
+
+              if (safety.isSafeToPrune) {
+                const nextText = await this.engine.sourceRewriter.stripNamedExportSignature(
+                  absPath,
+                  unusedExport.symbol,
+                  node.internalExports.get(unusedExport.symbol)
+                );
+
+                await this.engine.txManager.stageWrite(absPath, nextText);
+                await this.engine.typeIntegrity.synchronizeDeclarationFile(absPath, unusedExport.symbol);
+
+                refactoringResults.exportsRemoved.push(unusedExport);
+                this.emit('refactoring:export-removed', unusedExport);
+              }
+            }
+          } catch (error) {
+            refactoringResults.errors.push({
+              type: 'export-removal',
+              export: unusedExport.symbol,
+              file: unusedExport.file,
+              error: error.message
+            });
+            this.emit('refactoring:error', { type: 'export-removal', export: unusedExport, error });
+          }
+        }
+
+        // Remove unused dependencies
+        const depsToRemove = changes.removeUnusedDependencies !== false
+          ? this.analysisResults.unusedDependencies
+          : [];
+
+        for (const dep of depsToRemove) {
+          try {
+            const absPath = path.resolve(this.engine.context.cwd, dep.manifest);
+            // TODO: Implement package.json dependency removal
+            refactoringResults.dependenciesRemoved.push(dep);
+            this.emit('refactoring:dependency-removed', dep);
+          } catch (error) {
+            refactoringResults.errors.push({
+              type: 'dependency-removal',
+              package: dep.package,
+              error: error.message
+            });
+            this.emit('refactoring:error', { type: 'dependency-removal', package: dep.package, error });
+          }
+        }
+      });
+
+      this.isRunning = false;
+      this.emit('refactoring:complete', refactoringResults);
+      return refactoringResults;
+    } catch (error) {
+      this.isRunning = false;
+      this.emit('refactoring:error', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Get current analysis metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+    return this.engine.context.metrics;
+  }
+
+  /**
+   * Get all registered plugins
+   * @returns {Array} Plugin instances
+   */
+  getPlugins() {
+    if (!this.engine) {
+      throw new Error('API not initialized. Call initialize() first.');
+    }
+    return this.engine.context.pluginRegistry?.getPlugins() || [];
+  }
+
+  /**
+   * Get analysis results
+   * @returns {Object} Analysis results
+   */
+  getAnalysisResults() {
+    return this.analysisResults;
+  }
+
+  /**
+   * Check if API is currently running
+   * @returns {boolean}
+   */
+  isProcessing() {
+    return this.isRunning;
+  }
+}
+
+export default HeadlessAPI;