pkg-scaffold 2.3.0 → 3.0.0

package/src/healing/GitSandbox.js

@@ -0,0 +1,160 @@
+import { execSync } from 'child_process';
+import path from 'path';
+
+/**
+ * Ephemeral Git Sandbox & Version Control Islolation Gateway
+ * Manages atomic branch switching, working-tree stashing, and systemic rollbacks.
+ */
+export class GitSandbox {
+  constructor(context) {
+    this.context = context;
+    this.originalBranch = null;
+    this.sandboxBranch = null;
+    this.hasStashedChanges = false;
+    this.isGitRepository = false;
+  }
+
+  /**
+   * Validates the active environment and isolates the working directory.
+   */
+  async establishIsolationCheckpoint() {
+    this.verifyGitRepositoryPresence();
+    if (!this.isGitRepository) return;
+
+    try {
+      // Capture the current branch name
+      this.originalBranch = execSync('git rev-parse --abbrev-ref HEAD', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      // Check for uncommitted working directory changes
+      const statusOutput = execSync('git status --porcelain', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      if (statusOutput.length > 0) {
+        if (this.context.verbose) {
+          console.log('📦 Working tree contains uncommitted changes. Stashing before running pipeline...');
+        }
+        execSync('git stash save "pkg-scaffold: Ephemeral Checkpoint Stash"', { 
+          cwd: this.context.cwd, 
+          stdio: 'ignore' 
+        });
+        this.hasStashedChanges = true;
+      }
+
+      // Generate an isolated tracking branch name
+      this.sandboxBranch = `scaffold-heal-${Date.now()}`;
+      execSync(`git checkout -b ${this.sandboxBranch}`, { 
+        cwd: this.context.cwd, 
+        stdio: 'ignore' 
+      });
+
+      if (this.context.verbose) {
+        console.log(`🌿 Isolated sandbox branch successfully initialized: [${this.sandboxBranch}]`);
+      }
+    } catch (error) {
+      throw new Error(`Git Sandbox separation failure: ${error.message}`);
+    }
+  }
+
+  /**
+   * Commits all modifications within the sandbox branch for validation testing.
+   */
+  async stageAndCheckpointChanges(commitMessage = 'refactor(scaffold): apply structural optimizations') {
+    if (!this.isGitRepository) return;
+    this.assertActiveIsolation();
+
+    try {
+      execSync('git add .', { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      // Check if any mutations were actually staged
+      const diffIndex = execSync('git diff --cached --name-only', { 
+        cwd: this.context.cwd, 
+        encoding: 'utf8' 
+      }).trim();
+
+      if (diffIndex.length === 0) return; // No modifications to verify
+
+      execSync(`git commit -m "${commitMessage}" --no-verify`, { 
+        cwd: this.context.cwd, 
+        stdio: 'ignore' 
+      });
+    } catch (error) {
+      throw new Error(`Failed to stage changes inside the sandbox: ${error.message}`);
+    }
+  }
+
+  /**
+   * Merges modifications back into the mainline branch if all validation test suites pass.
+   */
+  async acceptAndMergeOptimizations() {
+    if (!this.isGitRepository) return;
+    this.assertActiveIsolation();
+
+    try {
+      // Return to the original project branch boundary
+      execSync(`git checkout ${this.originalBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      // Merge the verified changes without creating a fast-forward bottleneck
+      execSync(`git merge --squash ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync('git commit -m "chore(refactor): apply verified dead-code removals" --no-verify', {
+        cwd: this.context.cwd,
+        stdio: 'ignore'
+      });
+
+      // Purge the temporary branch tracking reference
+      execSync(`git branch -D ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      this.restorePreviousWorkingState();
+    } catch (error) {
+      throw new Error(`Failed to merge sandbox modifications into mainline branch: ${error.message}`);
+    }
+  }
+
+  /**
+   * Reverts all disk changes instantly if testing suites flag an error.
+   */
+  async rejectAndAbortOptimizations() {
+    if (!this.isGitRepository) return;
+    if (!this.sandboxBranch) return;
+
+    try {
+      if (this.context.verbose) {
+        console.log('🔄 Aborting transaction loop. Resetting file systems...');
+      }
+      
+      execSync('git add . && git reset --hard HEAD', { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync(`git checkout ${this.originalBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      execSync(`git branch -D ${this.sandboxBranch}`, { cwd: this.context.cwd, stdio: 'ignore' });
+      
+      this.restorePreviousWorkingState();
+    } catch (error) {
+      console.error(`🚨 Critical Recovery Error: Failed to drop sandbox branch cleanly: ${error.message}`);
+    }
+  }
+
+  restorePreviousWorkingState() {
+    if (this.hasStashedChanges) {
+      execSync('git stash pop', { cwd: this.context.cwd, stdio: 'ignore' });
+      this.hasStashedChanges = false;
+    }
+    this.sandboxBranch = null;
+  }
+
+  verifyGitRepositoryPresence() {
+    try {
+      execSync('git rev-parse --is-inside-work-tree', { cwd: this.context.cwd, stdio: 'ignore' });
+      this.isGitRepository = true;
+    } catch {
+      this.isGitRepository = false;
+    }
+  }
+
+  assertActiveIsolation() {
+    if (!this.sandboxBranch) {
+      throw new Error('Git Sandbox operation error: No active sandbox tracking context exists.');
+    }
+  }
+}

package/src/healing/SelfHealer.js

@@ -0,0 +1,150 @@
+import { spawn } from 'child_process';
+import path from 'path';
+
+/**
+ * Self-Healing Test Orchestration & Regression Scanner
+ * Runs validation suites, intercepts stack traces, and controls transaction rollbacks.
+ */
+export class SelfHealer {
+  constructor(context, transactionManager, gitSandbox) {
+    this.context = context;
+    this.transactionManager = transactionManager;
+    this.gitSandbox = gitSandbox;
+    this.executionTimeout = 45000; // 45-second execution timeout wall
+  }
+
+  /**
+   * Validates the stability of staged code changes by running your project's test suite.
+   * @param {Function} refactorTask - The function containing code changes to evaluate
+   */
+  async runSelfHealingLifecycle(refactorTask) {
+    console.log('🛡️  Initializing transaction safety sandbox...');
+    
+    // Step 1: Open the transaction boundaries
+    await this.gitSandbox.establishIsolationCheckpoint();
+    await this.transactionManager.begin();
+
+    try {
+      // Step 2: Execute the codebase pruning transformations
+      await refactorTask();
+
+      // Step 3: Stage changes inside our Git tracking context
+      await this.gitSandbox.stageAndCheckpointChanges();
+
+      console.log('🧪 Running testing suites to verify workspace integrity...');
+      const validationPassed = await this.verifyProjectHealthStatus();
+
+      if (validationPassed) {
+        console.log('✨ Build stable. Merging verified code improvements.');
+        await this.transactionManager.commit();
+        await this.gitSandbox.acceptAndMergeOptimizations();
+        return true;
+      } else {
+        console.warn('⚠️  Regression flagged during validation. Triggering self-healing rollback...');
+        await this.revertWorkspaceToSafeState();
+        return false;
+      }
+    } catch (pipelineError) {
+      console.error(`🚨 Critical Exception Intercepted: ${pipelineError.message}`);
+      await this.revertWorkspaceToSafeState();
+      return false;
+    }
+  }
+
+  /**
+   * Spawns testing processes to detect exit code alerts or compiler trace metrics.
+   * @returns {Promise<boolean>} True if the test suite runs with an exit code of 0
+   */
+  verifyProjectHealthStatus() {
+    return new Promise((resolve) => {
+      const commandTokens = this.context.testCommand.split(' ');
+      const executionBinary = commandTokens.shift();
+      
+      const processBuffer = [];
+      const testProcess = spawn(executionBinary, commandTokens, {
+        cwd: this.context.cwd,
+        shell: true
+      });
+
+      // Implement an execution timeout monitor to prevent hanging test suites from blocking the pipeline
+      const timeoutWatch = setTimeout(() => {
+        console.warn('⏱️  Test execution exceeded timeout limit. Terminating subprocess...');
+        testProcess.kill('SIGKILL');
+      }, this.executionTimeout);
+
+      testProcess.stdout.on('data', (data) => {
+        processBuffer.push(data);
+        if (this.context.verbose) {
+          process.stdout.write(data);
+        }
+      });
+
+      testProcess.stderr.on('data', (data) => {
+        processBuffer.push(data);
+        if (this.context.verbose) {
+          process.stderr.write(data);
+        }
+      });
+
+      testProcess.on('close', (exitCode) => {
+        clearTimeout(timeoutWatch);
+        
+        if (exitCode !== 0) {
+          const fullConsoleOutput = Buffer.concat(processBuffer).toString('utf8');
+          this.diagnoseErrorOutput(fullConsoleOutput);
+          resolve(false);
+        } else {
+          resolve(true);
+        }
+      });
+
+      testProcess.on('error', (err) => {
+        clearTimeout(timeoutWatch);
+        if (this.context.verbose) {
+          console.error(`Subprocess execution error: ${err.message}`);
+        }
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Traces error codes and console log outputs to identify the root cause of a broken build.
+   */
+  diagnoseErrorOutput(consoleLogOutput) {
+    console.log('\n🔍 [Diagnostics] Reviewing error output...');
+    
+    // Scan for standard TypeScript Compilation errors
+    const tsErrorPattern = /error\s+TS(\d+):\s+([\s\S]*?)$/m;
+    const tsMatches = consoleLogOutput.match(tsErrorPattern);
+    
+    if (tsMatches) {
+      console.error(`❌ Mapped Type Error Code [TS${tsMatches[1]}]: ${tsMatches[2].trim()}`);
+      return;
+    }
+
+    // Scan for missing file imports or runtime resolution exceptions
+    const missingModulePattern = /Cannot find module '([^']+)'/i;
+    const moduleMatches = consoleLogOutput.match(missingModulePattern);
+    
+    if (moduleMatches) {
+      console.error(`❌ Missing Dependency Reference Pointer: Cannot locate element [${moduleMatches[1]}]`);
+      return;
+    }
+
+    console.error('❌ Test suite execution failed. Check standard console output for details.');
+  }
+
+  /**
+   * Automatically executes a rollback event, restoring both file states and Git status.
+   */
+  async revertWorkspaceToSafeState() {
+    try {
+      await this.transactionManager.rollback();
+      await this.gitSandbox.rejectAndAbortOptimizations();
+      console.log('🔄 [Self-Healing] Rollback complete. Original project states restored.');
+    } catch (recoveryError) {
+      console.error(`🚨 Fatal Recovery Error: Failed to restore prior workspace configuration: ${recoveryError.message}`);
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,384 @@
+/**
+ * ============================================================================
+ * 📦 pkg-scaffold v3.0.0: Unified Architectural Refactoring Orchestrator
+ * ============================================================================
+ * Main execution bridge managing multi-pass compilation cycles, semantic cross-linking,
+ * supply-chain validation audits, and automated git self-healing rollbacks.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import ansis from 'ansis';
+import readline from 'readline/promises';
+
+// Import local domain architecture sub-systems
+import { EngineContext } from './EngineContext.js';
+import { ASTAnalyzer } from './ast/ASTAnalyzer.js';
+import { BarrelParser } from './ast/BarrelParser.js';
+import { MagicDetector } from './ast/MagicDetector.js';
+import { PathMapper } from './resolution/PathMapper.js';
+import { WorkspaceGraph } from './resolution/WorkSpaceGraph.js';
+import { DependencyResolver } from './resolution/DepencyResolver.js';
+import { TransactionManager } from './refractor/TransactionManager.js';
+import { ImpactAnalyzer } from './refractor/ImpactAnalyzer.js';
+import { SourceRewriter } from './refractor/SourceRewriter.js';
+import { TypeIntegrity } from './refractor/TypeIntegrity.js';
+import { GitSandbox } from './healing/GitSandbox.js';
+import { SelfHealer } from './healing/SelfHealer.js';
+import { IncrementalCacheManager } from './performance/GraphCache.js';
+import { WorkerPool } from './performance/WorkerPool.js';
+import { SupplyChainGuard } from './performance/SupplyChainGuard.js';
+
+/**
+ * Primary Refactoring Engine Core Coordination Controller
+ */
+export class RefactoringEngine {
+  constructor(options = {}) {
+    // Stage 1: Instantiate State Registers and Global Variables context
+    this.context = new EngineContext(options);
+    
+    // Stage 2: Initialize File Mappers and Multi-Package Graph Networks
+    this.pathMapper = new PathMapper(this.context);
+    this.workspaceGraph = new WorkspaceGraph(this.context);
+    this.resolver = new DependencyResolver(this.context, this.pathMapper, this.workspaceGraph);
+    
+    // Stage 3: Wire official AST Syntax parsers and framework processors
+    this.analyzer = new ASTAnalyzer(this.context);
+    this.barrelParser = new BarrelParser(this.context, this.resolver);
+    this.magicDetector = new MagicDetector(this.context);
+    
+    // Stage 4: Connect Transaction managers and surgical code generation scripts
+    this.txManager = new TransactionManager(this.context);
+    this.impactAnalyzer = new ImpactAnalyzer(this.context);
+    this.sourceRewriter = new SourceRewriter(this.context);
+    this.typeIntegrity = new TypeIntegrity(this.context);
+    
+    // Stage 5: Bind security audit utilities and performance cache rings
+    this.supplyChainGuard = new SupplyChainGuard(this.context);
+    this.cacheManager = new IncrementalCacheManager(this.context);
+    this.workerPool = new WorkerPool(this.context);
+    this.gitSandbox = new GitSandbox(this.context);
+    this.selfHealer = new SelfHealer(this.context, this.txManager, this.gitSandbox);
+  }
+
+  /**
+   * Main Operational Loop executing multi-stage analysis passes across files.
+   */
+  async run() {
+    try {
+      console.log(ansis.bold.green('🎯 Starting pkg-scaffold Operational Optimization Cycle...'));
+      
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      
+      // Pass 1: Boot environment contexts and load alias configuration maps
+      await this.context.initialize();
+      await this.pathMapper.loadMappings(this.context.tsconfigFilename);
+      
+      if (this.context.isWorkspaceEnabled) {
+        console.log(ansis.dim('🌐 Mapping local monorepo workspaces and package mesh layers...'));
+        await this.workspaceGraph.initializeWorkspaceMesh();
+      }
+
+      // Load asset fingerprints from disk cache to maximize cold-start performance
+      const cacheManifest = await this.cacheManager.loadCacheManifest();
+
+      // Pass 2: Recursively crawl directories to compile target codebase files list
+      const fileList = [];
+      await this.discoverSourceFiles(this.context.cwd, fileList);
+      this.context.metrics.totalFilesScanned = fileList.length;
+
+      // Identify meta-framework setups (Next.js, Remix, Nuxt, etc.)
+      const activeFrameworkEcosystems = await this.magicDetector.identifyActiveProjectEcosystems(this.context.cwd);
+
+      // Separate explicit configuration packages out for targeted supply chain security checks
+      const sourceCodeFilesList = [];
+      for (const file of fileList) {
+        if (file.endsWith('package.json')) {
+          await this.auditManifestSupplyChain(file);
+        } else {
+          sourceCodeFilesList.push(file);
+        }
+      }
+
+      // Pass 3: Process source file tokens using high-performance concurrent workers
+      let parallelParseCompleted = false;
+      if (sourceCodeFilesList.length > 10) {
+        parallelParseCompleted = await this.workerPool.parallelAnalyzeCodebase(sourceCodeFilesList, this);
+      }
+
+      // Synchronous fallback loop to parse remaining files or cache misses.
+      // IMPORTANT: The `parallelParseCompleted` flag only controls whether the *worker pool*
+      // already processed all files. It must NOT be set per-file inside this loop — doing so
+      // would cause all files after the first cache-hit to be silently skipped.
+      for (const filePath of sourceCodeFilesList) {
+        const node = this.context.createNode(filePath);
+        const currentHash = await this.cacheManager.computeHash(filePath);
+        node.contentHash = currentHash;
+
+        // Check if this individual file is already up-to-date in the cache
+        const isFileCached = cacheManifest[filePath] && cacheManifest[filePath].hash === currentHash;
+
+        if (isFileCached) {
+          this.context.metrics.cacheHits++;
+          this.hydrateNodeFromCache(node, cacheManifest[filePath]);
+        } else if (!parallelParseCompleted) {
+          // Only parse if the worker pool did not already handle this file
+          this.context.metrics.cacheMisses++;
+          await this.analyzer.processFile(filePath, node);
+        }
+
+        // Apply ecosystem overrides directly to our parsed memory maps
+        this.magicDetector.injectVirtualConsumerEdges(filePath, node, activeFrameworkEcosystems);
+      }
+
+      // Pass 4: Evaluate graph edges and link connections across the codebase mesh
+      console.log(ansis.dim('🔗 Linking graph edges and checking structural usage paths...'));
+      await this.linkDependencyGraph();
+
+      // Pass 5: Compile metrics summary and print diagnostics report
+      const analysisSummary = this.context.generateSummaryReport();
+      this.displayConsoleDiagnostics(analysisSummary);
+
+      // Pass 6: Run self-healing automated transformations if --fix is set
+      if (this.context.allowAutoFix) {
+        const structuralModificationsStaged = 
+          analysisSummary.structuralIssuesDetected.deadFiles.length > 0 || 
+          analysisSummary.structuralIssuesDetected.deadExports.length > 0;
+
+        if (structuralModificationsStaged) {
+          console.log(ansis.bold.yellow('\n📋 Proposed Optimization Plan:'));
+          console.log(ansis.dim('------------------------------------------------------------'));
+          
+          if (analysisSummary.structuralIssuesDetected.deadFiles.length > 0) {
+            console.log(ansis.bold(`  🗑️  Delete ${analysisSummary.structuralIssuesDetected.deadFiles.length} orphaned files:`));
+            analysisSummary.structuralIssuesDetected.deadFiles.forEach(f => console.log(ansis.dim(`    • ${f}`)));
+          }
+          
+          if (analysisSummary.structuralIssuesDetected.deadExports.length > 0) {
+            console.log(ansis.bold(`  ✂️  Prune ${analysisSummary.structuralIssuesDetected.deadExports.length} unused named exports:`));
+            analysisSummary.structuralIssuesDetected.deadExports.forEach(e => console.log(ansis.dim(`    • ${e.symbol} in ${e.file}:${e.line}`)));
+          }
+          console.log(ansis.dim('------------------------------------------------------------'));
+
+          let proceed = this.context.skipConfirm;
+          if (!proceed) {
+            const answer = await rl.question(ansis.bold.cyan('\n❓ Apply these structural modifications? (y/N): '));
+            proceed = answer.toLowerCase() === 'y';
+          }
+
+          if (proceed) {
+            await this.selfHealer.runSelfHealingLifecycle(async () => {
+              // Sub-Task A: Purge completely unreferenced dangling components
+              for (const relPath of analysisSummary.structuralIssuesDetected.deadFiles) {
+                const absPath = path.resolve(this.context.cwd, relPath);
+                console.log(ansis.red(`✂️  Removing unreferenced file: ${relPath}`));
+                await this.txManager.stageDeletion(absPath);
+              }
+
+              // Sub-Task B: Surgically remove unused named export blocks from active files
+              for (const unusedExport of analysisSummary.structuralIssuesDetected.deadExports) {
+                const absPath = path.resolve(this.context.cwd, unusedExport.file);
+                const node = this.context.graph.get(absPath);
+                
+                if (!node) continue;
+                const meta = node.internalExports.get(unusedExport.symbol);
+
+                // Perform safety analysis to ensure the token isn't called via dynamic runtime methods
+                const safetyVerdict = await this.impactAnalyzer.verifyRefactorSafety(absPath, unusedExport.symbol, this.context.graph);
+
+                if (safetyVerdict.isSafeToPrune) {
+                  console.log(ansis.yellow(`⚡ Stripping unused export [${unusedExport.symbol}] from: ${unusedExport.file}:${unusedExport.line}`));
+                  const nextText = await this.sourceRewriter.stripNamedExportSignature(absPath, unusedExport.symbol, meta);
+                  
+                  await this.txManager.stageWrite(absPath, nextText);
+                  
+                  // Align matching type declaration boundaries (.d.ts) to prevent compilation errors
+                  await this.typeIntegrity.synchronizeDeclarationFile(absPath, unusedExport.symbol);
+                } else if (this.context.verbose) {
+                  console.log(ansis.gray(`🛡️  Preserving symbol export [${unusedExport.symbol}] due to: ${safetyVerdict.blockReason}`));
+                }
+              }
+            });
+          } else {
+            console.log(ansis.bold.yellow('\n⚠️  Optimization plan aborted by user. No changes applied.'));
+          }
+        }
+      }
+
+      // Pass 7: Save optimized graph footprints back to the cache directory
+      await this.cacheManager.saveCacheManifest(this.context.graph);
+      rl.close();
+      console.log(ansis.bold.green('\n✨ Core optimization cycle completed smoothly. Codebase workspace is healthy.'));
+
+    } catch (criticalFault) {
+      console.error(ansis.bold.red(`\n🚨 Critical Operational Pipeline Failure: ${criticalFault.message}`));
+      if (criticalFault.stack) console.error(ansis.dim(criticalFault.stack));
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Links nodes and processes barrel files recursively without regular expressions.
+   */
+  async linkDependencyGraph() {
+    for (const [filePath, node] of this.context.graph.entries()) {
+      
+      // Connect standard module imports
+      for (const specifier of node.explicitImports) {
+        const resolvedPath = this.resolver.resolveModulePath(filePath, specifier);
+        if (resolvedPath && this.context.graph.has(resolvedPath)) {
+          this.context.graph.get(resolvedPath).incomingEdges.add(filePath);
+          node.outgoingEdges.add(resolvedPath);
+        }
+      }
+
+      // Unroll re-exports and unwrap barrel file links recursively
+      for (const specToken of node.importedSymbols) {
+        const delimiterIndex = specToken.indexOf(':');
+        if (delimiterIndex === -1) continue;
+
+        const specifier = specToken.slice(0, delimiterIndex);
+        const symbol = specToken.slice(delimiterIndex + 1);
+
+        const resolvedPath = this.resolver.resolveModulePath(filePath, specifier);
+        
+        if (resolvedPath && symbol !== '*') {
+          const traceResolution = await this.barrelParser.determineSymbolDeclarationOrigin(
+            resolvedPath, 
+            symbol, 
+            this.context.graph
+          );
+          
+          if (traceResolution && this.context.graph.has(traceResolution.originFile)) {
+            this.context.graph.get(traceResolution.originFile).incomingEdges.add(filePath);
+            node.outgoingEdges.add(traceResolution.originFile);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Audits package json files using token equality checks instead of fragile regex searches.
+   */
+  async auditManifestSupplyChain(packageJsonPath) {
+    try {
+      const text = await fs.readFile(packageJsonPath, 'utf8');
+      const data = JSON.parse(text);
+      
+      const prodDeps = Object.keys(data.dependencies || {});
+      const devDeps = Object.keys(data.devDependencies || {});
+      const totalDependencies = [...prodDeps, ...devDeps];
+
+      // Pass dependencies down to our Levenshtein string-distance guard to find typosquat targets
+      const supplyChainThreats = this.supplyChainGuard.detectTyposquattingAnomalies(totalDependencies);
+      
+      for (const anomaly of supplyChainThreats) {
+        console.warn(ansis.bold.red(`🚨 Supply Chain Alert: Malicious package masking candidate discovered [${anomaly.maliciousCandidate}]. Mimics trusted library [${anomaly.targetMimicked}].`));
+      }
+
+      // Verify lockfile hash configurations to catch poisoned manifests
+      await this.supplyChainGuard.verifyIntegrityLockfileHashes(packageJsonPath);
+    } catch {
+      // Manifest unreadable or locked; skip gracefully
+    }
+  }
+
+  hydrateNodeFromCache(node, cachedRecord) {
+    cachedRecord.explicitImports.forEach(i => node.explicitImports.add(i));
+    cachedRecord.dynamicImports.forEach(i => node.dynamicImports.add(i));
+    cachedRecord.importedSymbols.forEach(s => node.importedSymbols.add(s));
+    cachedRecord.rawStringReferences.forEach(r => node.rawStringReferences.add(r));
+    cachedRecord.instantiatedIdentifiers.forEach(i => node.instantiatedIdentifiers.add(i));
+    cachedRecord.propertyAccessChains.forEach(c => node.propertyAccessChains.add(c));
+    
+    if (cachedRecord.internalExports) {
+      Object.entries(cachedRecord.internalExports).forEach(([k, v]) => {
+        node.internalExports.set(k, v);
+      });
+    }
+    node.isLibraryEntry = cachedRecord.isLibraryEntry || false;
+    node.securityThreats = cachedRecord.securityThreats || [];
+    if (cachedRecord.localSuppressedRules) {
+      cachedRecord.localSuppressedRules.forEach(r => node.localSuppressedRules.add(r));
+    }
+    if (cachedRecord.symbolSourceLocations) {
+      Object.entries(cachedRecord.symbolSourceLocations).forEach(([k, v]) => {
+        node.symbolSourceLocations.set(k, v);
+      });
+    }
+  }
+
+  /**
+   * Crawls project roots using precise token extension checking instead of high-risk text matching.
+   */
+  async discoverSourceFiles(currentDirectory, fileAccumulator) {
+    try {
+      const entries = await fs.readdir(currentDirectory, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const absolutePath = path.join(currentDirectory, entry.name);
+
+        if (entry.isDirectory()) {
+          // Standard systemic exclusions filters
+          if (entry.name === 'node_modules' || 
+              entry.name === '.git' || 
+              entry.name === '.scaffold-cache' || 
+              entry.name === 'dist' || 
+              entry.name === 'build') {
+            continue;
+          }
+          await this.discoverSourceFiles(absolutePath, fileAccumulator);
+        } else if (entry.isFile()) {
+          const extension = path.extname(entry.name);
+          if (extension === '.js' || 
+              extension === '.ts' || 
+              extension === '.tsx' || 
+              extension === '.jsx' || 
+              entry.name === 'package.json') {
+            fileAccumulator.push(absolutePath);
+          }
+        }
+      }
+    } catch {
+      // Path unreadable or access locked; close loop gracefully
+    }
+  }
+
+  displayConsoleDiagnostics(report) {
+    console.log(ansis.bold.green('\n📊 Codebase Structural Diagnostics Summary'));
+    console.log(ansis.dim('============================================================'));
+    console.log(`${ansis.bold('Processing Cycle Wall Duration:')} ${ansis.cyan(report.executionDuration)}`);
+    console.log(`${ansis.bold('Total Files Indexed Globally  :')} ${ansis.white(report.totalFilesProcessed)}`);
+    console.log(`${ansis.bold('Delta Cache Optimization Ratio:')} ${ansis.green(report.graphCacheOptimization.ratio)} (Hits: ${report.graphCacheOptimization.hits} / Misses: ${report.graphCacheOptimization.misses})`);
+    console.log(ansis.dim('------------------------------------------------------------'));
+    
+    if (report.structuralIssuesDetected.deadFiles.length > 0) {
+      console.log(ansis.bold.red(`\nOrphaned Files Flagged (${report.structuralIssuesDetected.deadFiles.length}):`));
+      report.structuralIssuesDetected.deadFiles.forEach(f => console.log(ansis.dim(`  • ${f}`)));
+    } else {
+      console.log(ansis.green('\n✨ No orphaned or unreferenced component files found.'));
+    }
+
+    if (report.structuralIssuesDetected.deadExports.length > 0) {
+      console.log(ansis.bold.yellow(`\nUnused Named Symbol Exports Flagged (${report.structuralIssuesDetected.deadExports.length}):`));
+      report.structuralIssuesDetected.deadExports.forEach(e => {
+        console.log(`  • ${ansis.dim(e.file)}:${e.line}:${e.column} -> [${ansis.yellow(e.symbol)}] (Type: ${e.type})`);
+      });
+    } else {
+      console.log(ansis.green('✨ No dead or unused named symbols exported across components.'));
+    }
+
+    if (report.structuralIssuesDetected.securityThreats.length > 0) {
+      console.log(ansis.bold.red(`\n⚠️  High-Risk Variable Assignment Alerts (${report.structuralIssuesDetected.securityThreats.length}):`));
+      report.structuralIssuesDetected.securityThreats.forEach(threat => {
+        console.log(`  • ${ansis.red(threat.file)}:${threat.line} -> Variable [${ansis.bold(threat.identifier)}] contains a high-entropy secret (Shannon Score: ${threat.entropy})`);
+      });
+    }
+
+    console.log(ansis.dim('\n============================================================\n'));
+  }
+}