pkg-scaffold 2.2.0 → 2.4.0

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "pkg-scaffold",
-  "version": "2.2.0",
-  "description": "Zero-config workspace initializer with advanced dependency intelligence: detects ghost dependencies (used but undeclared), orphaned packages (declared but unused), unused imports with file locations, deprecated packages, hardcoded secrets, and more.",
+  "version": "2.4.0",
+  "description": "An advanced, AST-driven dependency resolution, refactoring, and self-healing engine.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "pkg-scaffold": "./index.js"
+    "pkg-scaffold": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test:stability": "npm run test"
   },
   "keywords": [
     "scaffold",
@@ -35,8 +40,15 @@
   },
   "homepage": "https://github.com/DreamLongYT/pkg-scaffold#readme",
   "dependencies": {
-    "acorn": "^8.17.0",
-    "acorn-walk": "^8.3.5",
-    "npm-deprecated-check": "^1.4.0"
+    "ansis": "^3.0.0",
+    "commander": "^12.0.0",
+    "enhanced-resolve": "^5.16.0",
+    "execa": "^8.0.1",
+    "ramda": "^0.29.1",
+    "typescript": "^5.4.5",
+    "yocto-spinner": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
-}
+}

package/src/EngineContext.js

@@ -0,0 +1,282 @@
+/**
+ * ============================================================================
+ * 📦 pkg-scaffold v3.0.0: Enterprise In-Memory Codebase State Manifest
+ * ============================================================================
+ * Implements a high-density, centralized graph database context for tracking
+ * software engineering debt, dependencies, types, and vulnerabilities.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * High-Fidelity Graph Element Node representing a single file asset boundary.
+ */
+export class GraphNode {
+  constructor(filePath) {
+    this.filePath = path.normalize(filePath);
+    this.contentHash = '';
+    this.isLibraryEntry = false;
+    this.isFrameworkContract = false;
+    this.scriptKind = 0; // Ambient enum mapping
+
+    // Explicit and Computed Dynamic Syntax Boundaries
+    this.explicitImports = new Set();
+    this.dynamicImports = new Set();
+    this.importedSymbols = new Set(); // Format: 'specifier:symbol' or 'specifier:*'
+    
+    // Internal API Exposed Interfaces (Symbol Name -> ExportMetadata)
+    this.internalExports = new Map();
+    this.typeOnlyExports = new Set();
+    
+    // Semantic Reference Verification Registries
+    this.instantiatedIdentifiers = new Set();
+    this.rawStringReferences = new Set();
+    this.propertyAccessChains = new Set();
+    
+    // Dependency Mesh Connection Maps
+    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 = [];
+    this.calculatedDynamicImports = [];
+    this.localSuppressedRules = new Set();
+    
+    // Detailed AST Location Diagnostics (Symbol -> Structural Location Mapping)
+    this.symbolSourceLocations = new Map(); // Symbol -> { line: number, column: number, length: number }
+  }
+
+  /**
+   * Evaluates if a specific exposed symbol token is utilized by any incoming edges.
+   * Leverages precise syntax identity collections.
+   */
+  isSymbolReferencedExternally(symbolName, projectGraph) {
+    if (this.isLibraryEntry) return true;
+    
+    for (const parentPath of this.incomingEdges) {
+      const parentNode = projectGraph.get(parentPath);
+      if (!parentNode) continue;
+
+      // Direct identity reference check
+      if (parentNode.instantiatedIdentifiers.has(symbolName)) return true;
+      
+      // Property lookup reference checks (e.g., config.databaseUrl)
+      for (const accessChain of parentNode.propertyAccessChains) {
+        if (accessChain.endsWith(`.${symbolName}`) || accessChain.includes(`.${symbolName}.`)) {
+          return true;
+        }
+      }
+
+      // Safe fallback lookup inside string reference caches (e.g., obj['databaseUrl'])
+      if (parentNode.rawStringReferences.has(symbolName)) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Compiles complete localized diagnostic telemetry tracking metrics for this node instance.
+   */
+  compileNodeTelemetry() {
+    return {
+      path: this.filePath,
+      totalExplicitImportsCount: this.explicitImports.size,
+      totalExposedExportsCount: this.internalExports.size,
+      incomingDependenciesCount: this.incomingEdges.size,
+      outgoingDependenciesCount: this.outgoingEdges.size,
+      isDanglingOrphan: this.incomingEdges.size === 0 && !this.isLibraryEntry,
+      trackedThreatsCount: this.securityThreats.length
+    };
+  }
+}
+
+/**
+ * Enterprise Engine Run State Registry & Suppression Context Matrix
+ */
+export class EngineContext {
+  constructor(options = {}) {
+    this.cwd = path.normalize(options.cwd || process.cwd());
+    this.cacheDir = path.join(this.cwd, '.scaffold-cache');
+    this.ignoreFilePath = path.join(this.cwd, '.scaffold-ignore');
+    this.tsconfigFilename = options.tsconfig || 'tsconfig.json';
+    this.testCommand = options.testCommand || 'npm test';
+    
+    this.allowAutoFix = options.autoFix ?? true;
+    this.isWorkspaceEnabled = options.workspace ?? false;
+    this.verbose = options.verbose ?? false;
+
+    // Core Memory Repositories
+    this.graph = new Map(); // Absolute File Path -> GraphNode
+    this.registryHashes = new Map(); // Package Name -> Secure Lockfile Signature String
+    this.globallyIgnoredSymbols = new Set();
+    this.globallyIgnoredPaths = [];
+    this.monorepoPackageRoots = new Set();
+    
+    // Structural Heuristic Verification Metrics Tracker
+    this.metrics = {
+      startTime: 0,
+      endTime: 0,
+      totalFilesScanned: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      prunedFilesCount: 0,
+      prunedExportsCount: 0,
+      totalSymbolsAnalyzed: 0,
+      securityVulnerabilitiesMitigated: 0
+    };
+  }
+
+  /**
+   * Initializes baseline context options, directory footprints, and suppression maps.
+   */
+  async initialize() {
+    this.metrics.startTime = Date.now();
+    await fs.mkdir(this.cacheDir, { recursive: true });
+    await this.compileIgnoreConfigurations();
+  }
+
+  /**
+   * Parses .scaffold-ignore layers using precise token segment matching
+   * instead of high-risk loose regex blocks.
+   */
+  async compileIgnoreConfigurations() {
+    try {
+      const content = await fs.readFile(this.ignoreFilePath, 'utf8');
+      const lines = content.split('\n');
+
+      for (let line of lines) {
+        line = line.trim();
+        if (!line || line.startsWith('#')) continue;
+
+        if (line.startsWith('export:')) {
+          const symbolToken = line.replace('export:', '').trim();
+          this.globallyIgnoredSymbols.add(symbolToken);
+        } else if (line.startsWith('path:')) {
+          const pathToken = line.replace('path:', '').trim();
+          this.globallyIgnoredPaths.push(path.normalize(pathToken));
+        } else {
+          // Standard structural path rule fallback
+          this.globallyIgnoredPaths.push(path.normalize(line));
+        }
+      }
+    } catch {
+      // Configuration optionally omitted; proceed with default execution flags
+    }
+  }
+
+  /**
+   * Allocates or resolves a unified GraphNode reference inside our memory map index.
+   */
+  createNode(absoluteFilePath) {
+    const normalizedPath = path.normalize(absoluteFilePath);
+    if (this.graph.has(normalizedPath)) {
+      return this.graph.get(normalizedPath);
+    }
+    const node = new GraphNode(normalizedPath);
+    this.graph.set(normalizedPath, node);
+    return node;
+  }
+
+  /**
+   * Checks if an absolute file token path matches configuration ignore directives.
+   * Evaluates sub-path sequences exactly to prevent regular expression parsing drops.
+   */
+  isPathIgnored(absoluteFilePath) {
+    const relativeText = path.relative(this.cwd, absoluteFilePath);
+    
+    for (const ignoredTarget of this.globallyIgnoredPaths) {
+      if (relativeText === ignoredTarget || relativeText.startsWith(path.join(ignoredTarget, path.sep))) {
+        return true;
+      }
+      // Handle explicit wildcard terminal indicators
+      if (ignoredTarget.endsWith('*')) {
+        const baseSegment = ignoredTarget.slice(0, -1);
+        if (relativeText.startsWith(baseSegment)) return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Processes the entire active dependency map to compile structural issue indices.
+   * Evaluates orphaned components, dead exports, and supply-chain threats.
+   */
+  generateSummaryReport() {
+    this.metrics.endTime = Date.now();
+    const durationSeconds = ((this.metrics.endTime - this.metrics.startTime) / 1000).toFixed(2);
+    
+    const summary = {
+      executionDuration: `${durationSeconds}s`,
+      totalFilesProcessed: this.metrics.totalFilesScanned,
+      graphCacheOptimization: {
+        hits: this.metrics.cacheHits,
+        misses: this.metrics.cacheMisses,
+        ratio: this.metrics.totalFilesScanned > 0 
+          ? `${((this.metrics.cacheHits / this.metrics.totalFilesScanned) * 100).toFixed(1)}%`
+          : '0%'
+      },
+      structuralIssuesDetected: {
+        deadFiles: [],
+        deadExports: [],
+        securityThreats: []
+      },
+      modificationsExecuted: {
+        filesUnlinked: this.metrics.prunedFilesCount,
+        exportsStripped: this.metrics.prunedExportsCount
+      }
+    };
+
+    for (const [filePath, node] of this.graph.entries()) {
+      // Skip package control files from standard structural dead-code checks
+      if (filePath.endsWith('package.json')) continue;
+      if (this.isPathIgnored(filePath)) continue;
+
+      const relativePath = path.relative(this.cwd, filePath);
+
+      // Category A: Completely orphaned components (no references, not library/framework entries)
+      if (node.incomingEdges.size === 0 && !node.isLibraryEntry && !node.isFrameworkContract) {
+        summary.structuralIssuesDetected.deadFiles.push(relativePath);
+        continue; // An orphaned file implies all internal sub-exports are dead; skip sub-checks
+      }
+
+      // Category B: Dead Named Exports inside active files
+      for (const [exportName, meta] of node.internalExports.entries()) {
+        this.metrics.totalSymbolsAnalyzed++;
+        
+        // Skip entry configurations, global suppresses, and type-suppressed symbols
+        if (exportName === 'default' || 
+            this.globallyIgnoredSymbols.has(exportName) || 
+            node.localSuppressedRules.has(exportName)) {
+          continue;
+        }
+        
+        if (!node.isSymbolReferencedExternally(exportName, this.graph)) {
+          const diagnosticLocation = node.symbolSourceLocations.get(exportName) || { line: 1, column: 1 };
+          summary.structuralIssuesDetected.deadExports.push({
+            file: relativePath,
+            symbol: exportName,
+            type: meta.type || 'named',
+            line: diagnosticLocation.line,
+            column: diagnosticLocation.column
+          });
+        }
+      }
+
+      // Category C: High-Entropy Password / Key Hardcode 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
+          });
+        });
+      }
+    }
+
+    return summary;
+  }
+}

package/src/ast/ASTAnalyzer.js

@@ -0,0 +1,313 @@
+import ts from 'typescript';
+import fs from 'fs/promises';
+import crypto from 'crypto';
+
+/**
+ * Enterprise AST Syntax Walker & Feature Extractor
+ * Utilizes the official TypeScript Compiler infrastructure to execute deeply nested
+ * node classification without falling back to high-risk regular expression approximations.
+ */
+export class ASTAnalyzer {
+  constructor(context) {
+    this.context = context;
+    // Standard high-entropy baseline selectors for AST variable tracking
+    this.entropyThreshold = 4.3;
+  }
+
+  /**
+   * Parses target file data into an isolated AST representation and populates metadata structures.
+   * @param {string} filePath - Absolute path to on-disk component
+   * @param {Object} fileNode - In-memory structural graph reference node
+   */
+  async processFile(filePath, fileNode) {
+    try {
+      const sourceText = await fs.readFile(filePath, 'utf8');
+      
+      // Configure target extraction structures to parse TS, JSX, and modern TC39 specifications
+      const sourceFile = ts.createSourceFile(
+        filePath,
+        sourceText,
+        ts.ScriptTarget.Latest,
+        true, // Ensure parent pointers are bound to allow localized subtree walking
+        this.getScriptKind(filePath)
+      );
+
+      this.walkNode(sourceFile, sourceFile, fileNode);
+      this.extractTopLevelJSDocSuppreessions(sourceFile, fileNode);
+      
+      return true;
+    } catch (parseError) {
+      if (this.context.verbose) {
+        console.error(`[AST Open Error] Failed compilation validation mapping on element: ${filePath}. Reason: ${parseError.message}`);
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Primary node walker loop executing atomic switch classifications.
+   * Challenge #7: Resolves conditional/destructured references to prevent cascading breakages.
+   */
+  walkNode(sourceFile, node, fileNode) {
+    if (!node) return;
+
+    switch (node.kind) {
+      // Handle Explicit Named or Absolute Star Namespace Imports
+      case ts.SyntaxKind.ImportDeclaration: {
+        if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+          const specifier = node.moduleSpecifier.text;
+          fileNode.explicitImports.add(specifier);
+
+          if (node.importClause) {
+            // Trace named bounds: import { activeToken } from 'module';
+            if (node.importClause.namedBindings) {
+              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}`);
+                });
+              } else if (ts.isNamespaceImport(node.importClause.namedBindings)) {
+                // Tracking total wildcard imports: import * as layout from 'module';
+                fileNode.importedSymbols.add(`${specifier}:*`);
+              }
+            }
+            // Trace default bounds: import React from 'react';
+            if (node.importClause.name) {
+              fileNode.importedSymbols.add(`${specifier}:default`);
+            }
+          }
+        }
+        break;
+      }
+
+      // Handle Explicit Namespace Requirements: import config = require('./config');
+      case ts.SyntaxKind.ImportEqualsDeclaration: {
+        if (node.moduleReference && ts.isExternalModuleReference(node.moduleReference)) {
+          if (node.moduleReference.expression && ts.isStringLiteral(node.moduleReference.expression)) {
+            fileNode.explicitImports.add(node.moduleReference.expression.text);
+          }
+        }
+        break;
+      }
+
+      // Challenge #1: Tracking dynamic expressions e.g., import('./chunks/' + variant)
+      case ts.SyntaxKind.CallExpression: {
+        if (node.expression && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+          const firstArgument = node.arguments[0];
+          if (firstArgument) {
+            if (ts.isStringLiteral(firstArgument)) {
+              fileNode.explicitImports.add(firstArgument.text);
+              fileNode.dynamicImports.add(firstArgument.text);
+            } else {
+              // Deeply trace runtime calculated variables within the import parameters call
+              const stringPatterns = [];
+              this.traceStringExpressions(firstArgument, stringPatterns);
+              fileNode.calculatedDynamicImports.push({
+                rawText: firstArgument.getText(sourceFile),
+                heuristics: stringPatterns,
+                position: node.getStart(sourceFile)
+              });
+            }
+          }
+        }
+        break;
+      }
+
+      // Handle Variable Declaration Assignments & Challenge #11 (AST Secret Scanning)
+      case ts.SyntaxKind.VariableDeclaration: {
+        if (node.name && ts.isIdentifier(node.name)) {
+          this.auditAssignmentSafety(node.name.text, node.initializer, fileNode, sourceFile);
+        } else if (node.name && (ts.isObjectBindingPattern(node.name) || ts.isArrayBindingPattern(node.name))) {
+          // Flatten binding properties to map destructured usage accurately
+          node.name.elements.forEach(element => {
+            if (element.name && ts.isIdentifier(element.name)) {
+              this.auditAssignmentSafety(element.name.text, null, fileNode, sourceFile);
+            }
+          });
+        }
+        break;
+      }
+
+      // Handle Named Function Node Exports Matrix Configurations
+      case ts.SyntaxKind.FunctionDeclaration: {
+        if (node.name && ts.isIdentifier(node.name)) {
+          const name = node.name.text;
+          if (this.hasExportModifier(node)) {
+            fileNode.internalExports.set(name, { type: 'function', start: node.getStart(sourceFile), end: node.getEnd() });
+          }
+        }
+        break;
+      }
+
+      // Handle Structural Class Definitions and Class Export Signatures
+      case ts.SyntaxKind.ClassDeclaration: {
+        if (node.name && ts.isIdentifier(node.name)) {
+          const name = node.name.text;
+          if (this.hasExportModifier(node)) {
+            fileNode.internalExports.set(name, { type: 'class', start: node.getStart(sourceFile), end: node.getEnd() });
+          }
+        }
+        break;
+      }
+
+      // Handle Interface Definitions (Crucial for Challenge #10: Type Integrity Mapping)
+      case ts.SyntaxKind.InterfaceDeclaration: {
+        if (node.name && ts.isIdentifier(node.name)) {
+          const name = node.name.text;
+          if (this.hasExportModifier(node)) {
+            fileNode.internalExports.set(name, { type: 'interface', start: node.getStart(sourceFile), end: node.getEnd() });
+          }
+        }
+        break;
+      }
+
+      // Handle Type Invocations and Declarations Aliases
+      case ts.SyntaxKind.TypeAliasDeclaration: {
+        if (node.name && ts.isIdentifier(node.name)) {
+          const name = node.name.text;
+          if (this.hasExportModifier(node)) {
+            fileNode.internalExports.set(name, { type: 'type-alias', start: node.getStart(sourceFile), end: node.getEnd() });
+          }
+        }
+        break;
+      }
+
+      // Handle Explicit Export Assignments: export default baselineConfiguration;
+      case ts.SyntaxKind.ExportAssignment: {
+        const name = node.expression ? node.expression.getText(sourceFile) : 'default';
+        fileNode.internalExports.set('default', { 
+          type: 'default-assignment', 
+          referencedSymbol: name,
+          start: node.getStart(sourceFile), 
+          end: node.getEnd() 
+        });
+        break;
+      }
+
+      // Handle Arbitrary String References to catch deep framework routing or dynamic keys
+      case ts.SyntaxKind.StringLiteral: {
+        const text = node.text;
+        if (text.length > 2 && text.length < 120) {
+          fileNode.rawStringReferences.add(text);
+        }
+        break;
+      }
+
+      // Track general identifiers to register references to mapped import keys
+      case ts.SyntaxKind.Identifier: {
+        const idText = node.text;
+        // Avoid adding declarations to usage logs to keep verification accurate
+        if (!this.isNodeDeclarationName(node)) {
+          fileNode.instantiatedIdentifiers.add(idText);
+        }
+        break;
+      }
+    }
+
+    // Traverse recursively down the Node structural tree
+    ts.forEachChild(node, child => this.walkNode(sourceFile, child, fileNode));
+  }
+
+  /**
+   * Challenge #1: Evaluates math operations and template configurations inside dynamic imports.
+   */
+  traceStringExpressions(node, collector) {
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+      this.traceStringExpressions(node.left, collector);
+      this.traceStringExpressions(node.right, collector);
+    } else if (ts.isStringLiteral(node)) {
+      collector.push({ type: 'literal', val: node.text });
+    } else if (ts.isTemplateExpression(node)) {
+      if (node.head) collector.push({ type: 'template-slice', val: node.head.text });
+      node.templateSpans.forEach(span => {
+        collector.push({ type: 'dynamic-var', val: span.expression.getText() });
+        if (span.literal) collector.push({ type: 'template-slice', val: span.literal.text });
+      });
+    } else {
+      collector.push({ type: 'computed-variable', val: node.getText() });
+    }
+  }
+
+  /**
+   * Challenge #11: AST Secret Scanning. Evaluates entropy and patterns directly via assignments.
+   */
+  auditAssignmentSafety(variableName, initializer, fileNode, sourceFile) {
+    // Process variable mapping target indicators first
+    if (this.hasExportModifier(variableName?.parent)) {
+      fileNode.internalExports.set(variableName, { type: 'variable', start: variableName.parent.getStart(sourceFile), end: variableName.parent.getEnd() });
+    }
+
+    if (!initializer || !ts.isStringLiteral(initializer)) return;
+    const value = initializer.text;
+
+    // Challenge #11 Heuristic validation parameters matching variable patterns or contents values
+    const isSuspiciousKeyName = /api_?key|secret|token|password|auth_?token|private_?key/i.test(variableName);
+    const entropy = this.calculateShannonEntropy(value);
+
+    if ((isSuspiciousKeyName && value.length > 8) || (entropy > this.entropyThreshold && value.length > 16)) {
+      fileNode.securityThreats.push({
+        identifier: variableName,
+        entropy: parseFloat(entropy.toFixed(2)),
+        position: initializer.getStart(sourceFile),
+        riskCode: 'HIGH_RISK_SECRET_LEAK'
+      });
+    }
+  }
+
+  calculateShannonEntropy(str) {
+    const map = {};
+    for (let i = 0; i < str.length; i++) {
+      const char = str[i];
+      map[char] = (map[char] || 0) + 1;
+    }
+    let entropy = 0;
+    for (const char in map) {
+      const p = map[char] / str.length;
+      entropy -= p * Math.log2(p);
+    }
+    return entropy;
+  }
+
+  /**
+   * Challenge #18 & #8: Parse JSDoc suppression blocks right out of code statements.
+   */
+  extractTopLevelJSDocSuppreessions(sourceFile, fileNode) {
+    const fullText = sourceFile.text;
+    const commentRanges = ts.getLeadingCommentRanges(fullText, 0) || [];
+    
+    for (const range of commentRanges) {
+      const comment = fullText.slice(range.pos, range.end);
+      const matches = comment.match(/@scaffold-suppress\s+([a-zA-Z0-9_\-*:]+)/g);
+      if (matches) {
+        matches.forEach(m => {
+          const directive = m.replace('@scaffold-suppress', '').trim();
+          fileNode.localSuppressedRules.add(directive);
+        });
+      }
+    }
+  }
+
+  hasExportModifier(node) {
+    if (!node || !node.modifiers) return false;
+    return node.modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
+  }
+
+  isNodeDeclarationName(node) {
+    const parent = node.parent;
+    if (!parent) return false;
+    if (ts.isVariableDeclaration(parent) && parent.name === node) return true;
+    if (ts.isFunctionDeclaration(parent) && parent.name === node) return true;
+    if (ts.isClassDeclaration(parent) && parent.name === node) return true;
+    if (ts.isInterfaceDeclaration(parent) && parent.name === node) return true;
+    if (ts.isImportSpecifier(parent) && parent.name === node) return true;
+    return false;
+  }
+
+  getScriptKind(filePath) {
+    if (filePath.endsWith('.ts')) return ts.ScriptKind.TS;
+    if (filePath.endsWith('.tsx')) return ts.ScriptKind.TSX;
+    if (filePath.endsWith('.jsx')) return ts.ScriptKind.JSX;
+    return ts.ScriptKind.JS;
+  }
+}