pkg-scaffold 2.3.0 → 2.4.0

package/.scaffold-ignore

@@ -0,0 +1,22 @@
+# ============================================================================
+# ⚙️ pkg-scaffold Rule Suppression & Intent Profiles
+# ============================================================================
+# Define exact symbols, file patterns, or dependency keys that must remain 
+# preserved during dead-code scanning and transactional refactoring pruning.
+
+# Framework & Meta Entrypoints (Implicitly Alive)
+pages/api/*
+app/routes/*
+src/entry-point.js
+
+# Intent Suppression: Library Code / Consumer Consumption Contracts
+export:publicApiMethod
+export:initializePlugin
+export:onConfigLoaded
+
+# Globally Ignored Module Specifiers
+@types/node
+tslib
+
+# Secret Heuristic Exemptions (Explicit False Positive Control)
+exempt_token_pattern

package/bin/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * ============================================================================
+ * 🏁 pkg-scaffold CLI Entry Point
+ * ============================================================================
+ * Handles option compilation, environment orchestration, option validation,
+ * and initiates the primary operational pipeline loop.
+ */
+
+import { Command } from 'commander';
+import ansis from 'ansis';
+import path from 'path';
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+async function bootstrap() {
+  try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
+    program
+      .name('pkg-scaffold')
+      .description(ansis.cyan('Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine'))
+      .version(packageJsonContent.version || '3.0.0');
+
+    program
+      .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
+      .option('--fix', 'Enable atomic code updates, structural file pruning, and active type sanitization', true)
+      .option('--no-fix', 'Disable direct file manipulation modifications (dry-run reporting mode)')
+      .option('--tsconfig <filename>', 'Specify path to custom layout configurations', 'tsconfig.json')
+      .option('--test-command <command>', 'Integrated continuous safety test validation script execution path', 'npm test')
+      .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
+      .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false);
+
+    program.parse(process.argv);
+    const options = program.opts();
+
+    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.0.0'} Engine Activation`));
+    console.log(ansis.dim('------------------------------------------------------------'));
+    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(path.resolve(options.cwd))}`);
+    console.log(`${ansis.bold('Refactoring Mode     :')} ${options.fix ? ansis.yellow('Active Fixing & Self-Healing Enabled') : ansis.gray('Dry-Run Reporting Only')}`);
+    console.log(`${ansis.bold('Validation Sandbox   :')} ${ansis.magenta(options.testCommand)}`);
+    console.log(ansis.dim('------------------------------------------------------------\n'));
+
+    const engineModulePath = path.resolve(__dirname, '../src/EngineContext.js');
+    
+    try {
+      await fs.access(engineModulePath);
+    } catch {
+      console.error(ansis.red(`🚨 Execution Fault: Core engine architecture files missing. Ensure src/ directory layout is fully generated.`));
+      process.exit(1);
+    }
+
+    // Lazy load execution context wrapper to align with domain initialization
+    const { RefactoringEngine } = await import('../src/index.js');
+
+    if (!RefactoringEngine) {
+      console.error(ansis.red('🚨 Architecture Boundary Error: RefactoringEngine could not be resolved from code topology channels.'));
+      process.exit(1);
+    }
+
+    const engine = new RefactoringEngine({
+      cwd: options.cwd,
+      autoFix: options.fix,
+      tsconfig: options.tsconfig,
+      testCommand: options.testCommand,
+      workspace: options.workspace,
+      verbose: options.verbose
+    });
+
+    await engine.run();
+
+    console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
+    process.exit(0);
+
+  } catch (criticalBootError) {
+    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Boot Instability: ${criticalBootError.message}`));
+    if (criticalBootError.stack) {
+      console.error(ansis.dim(criticalBootError.stack));
+    }
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "pkg-scaffold",
-  "version": "2.3.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": {
-    "enhanced-resolve": "^5.24.0",
-    "npm-deprecated-check": "^1.4.0",
-    "typescript": "^6.0.3"
+    "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;
+  }
+}