pkg-scaffold 3.3.0 → 3.3.2

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2026] [name of copyright owner]
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -207,5 +207,5 @@
    following attribution in a prominent location (e.g., README, about page, 
    or CLI output):
    
-   "The original code was from the lovely DreamLong"
+   "The Original Code was made by DreamLongYT"
    ============================================================================

package/NOTICE

@@ -1,7 +1,7 @@
 pkg-scaffold
 Copyright 2026 DreamLongYT
 
-The original code was from the lovely DreamLong
+The Original Code was made by DreamLongYT
 
 This product includes software developed at
 pkg-scaffold (https://github.com/DreamLongYT/pkg-scaffold).

package/bin/cli.js

@@ -28,7 +28,7 @@ async function bootstrap() {
     program
       .name('pkg-scaffold')
       .description(ansis.cyan('Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine'))
-      .version(packageJsonContent.version || '3.0.0');
+      .version(packageJsonContent.version || '3.3.2');
 
     program
       .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
@@ -39,14 +39,15 @@ async function bootstrap() {
       .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
       .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false)
       .option('-r, --run', 'Execute the primary operational pipeline loop', false)
-      .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false);
+      .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false)
+      .option('--timeout <ms>', 'Set execution timeout in milliseconds', '30000');
 
     program.parse(process.argv);
     const options = program.opts();
 
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
-    // --- Onboarding Check ---
+    // --- Onboarding Check (Skipped in Non-Interactive Mode) ---
     const targetCwd = path.resolve(options.cwd);
     const pkgJsonPath = path.join(targetCwd, 'package.json');
     const configDirPath = path.join(targetCwd, 'pkg-scaffold');
@@ -54,49 +55,49 @@ async function bootstrap() {
     let pkgJson;
     try {
       pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
-    } catch (e) {
-      // No package.json found in target
-    }
+    } catch (e) {}
 
-    // 1. Ask to install script
-    if (pkgJson && !pkgJson.scripts?.['pkg-scaffold:run']) {
-      const answer = await rl.question(ansis.bold.yellow('❓ No "pkg-scaffold:run" script found in package.json. Install it? (y/n): '));
-      if (answer.toLowerCase() === 'y') {
-        pkgJson.scripts = pkgJson.scripts || {};
-        pkgJson.scripts['pkg-scaffold:run'] = 'pkg-scaffold --fix';
-        await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
-        console.log(ansis.green('✅ "pkg-scaffold:run" script added to package.json.'));
+    let configInstalled = false;
+    if (!options.yes && !options.run) {
+      // 1. Ask to install script
+      if (pkgJson && !pkgJson.scripts?.['pkg-scaffold:run']) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "pkg-scaffold:run" script found in package.json. Install it? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          pkgJson.scripts = pkgJson.scripts || {};
+          pkgJson.scripts['pkg-scaffold:run'] = 'pkg-scaffold --fix';
+          await fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+          console.log(ansis.green('✅ "pkg-scaffold:run" script added to package.json.'));
+        }
       }
-    }
 
-    // 2. Ask to install config folder
-    let configInstalled = false;
-    try {
-      await fs.access(configDirPath);
-      configInstalled = true;
-    } catch (e) {
-      const answer = await rl.question(ansis.bold.yellow('❓ No "/pkg-scaffold" configuration folder found. Create it with defaults? (y/n): '));
-      if (answer.toLowerCase() === 'y') {
-        await fs.mkdir(configDirPath, { recursive: true });
-        await fs.mkdir(path.join(configDirPath, 'plugins'), { recursive: true });
-        const defaultConfig = {
-          interface: "CLI",
-          useBuiltinPlugins: true,
-          useCustomPlugins: true,
-          supportKnipPlugins: true,
-          options: { verbose: false, fastMode: true, selfHealing: true },
-          enabledPlugins: ["nextjs", "nuxt", "remix", "sveltekit", "astro"]
-        };
-        await fs.writeFile(path.join(configDirPath, 'config.json'), JSON.stringify(defaultConfig, null, 2));
-        console.log(ansis.green('✅ "/pkg-scaffold" folder and default config created.'));
+      // 2. Ask to install config folder
+      try {
+        await fs.access(configDirPath);
         configInstalled = true;
+      } catch (e) {
+        const answer = await rl.question(ansis.bold.yellow('❓ No "/pkg-scaffold" configuration folder found. Create it with defaults? (y/n): '));
+        if (answer.toLowerCase() === 'y') {
+          await fs.mkdir(configDirPath, { recursive: true });
+          await fs.mkdir(path.join(configDirPath, 'plugins'), { recursive: true });
+          const defaultConfig = {
+            interface: "CLI",
+            useBuiltinPlugins: true,
+            useCustomPlugins: true,
+            supportKnipPlugins: true,
+            options: { verbose: false, fastMode: true, selfHealing: true },
+            enabledPlugins: ["nextjs", "nuxt", "remix", "sveltekit", "astro"]
+          };
+          await fs.writeFile(path.join(configDirPath, 'config.json'), JSON.stringify(defaultConfig, null, 2));
+          console.log(ansis.green('✅ "/pkg-scaffold" folder and default config created.'));
+          configInstalled = true;
+        }
       }
-    }
 
-    if (pkgJson?.scripts?.['pkg-scaffold:run'] || configInstalled) {
-      console.log(ansis.bold.cyan('\n🚀 Setup complete! To start the engine, run:'));
-      console.log(ansis.white(`   - pkg-scaffold -r`));
-      console.log(ansis.white(`   - npm run pkg-scaffold:run\n`));
+      if (pkgJson?.scripts?.['pkg-scaffold:run'] || configInstalled) {
+        console.log(ansis.bold.cyan('\n🚀 Setup complete! To start the engine, run:'));
+        console.log(ansis.white(`   - pkg-scaffold -r`));
+        console.log(ansis.white(`   - npm run pkg-scaffold:run\n`));
+      }
     }
 
     rl.close();
@@ -113,7 +114,6 @@ async function bootstrap() {
     const finalInterface = localConfig.interface || 'CLI';
     if (finalInterface === 'GUI') {
       console.log(ansis.bold.magenta('🎨 GUI Mode Detected. Starting Web Interface...'));
-      // In a real scenario, we'd start a local server or Electron here
       return;
     }
 
@@ -122,31 +122,23 @@ async function bootstrap() {
       return;
     }
 
-    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.1.0'} Engine Activation`));
+    // --- Timeout Handling ---
+    const timeoutMs = parseInt(options.timeout);
+    const timeoutTimer = setTimeout(() => {
+      console.error(ansis.bold.red(`\n🚨 Execution Timeout: The process exceeded the limit of ${timeoutMs}ms.`));
+      process.exit(1);
+    }, timeoutMs);
+    timeoutTimer.unref(); // Allow process to exit if work finishes
+
+    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.3.2'} Engine Activation`));
     console.log(ansis.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);
-    }
-
-    // Ensure cwd is always an absolute path regardless of how it was passed (e.g., '--cwd .')
     const engine = new RefactoringEngine({
       cwd: path.resolve(options.cwd),
       autoFix: options.fix,
@@ -158,7 +150,8 @@ async function bootstrap() {
     });
 
     await engine.run();
-
+    
+    clearTimeout(timeoutTimer);
     console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
     process.exit(0);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkg-scaffold",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "The Ultimate Enterprise Codebase Janitor. Faster than Knip with OXC integration, type-aware analysis, and self-healing capabilities. Fully standalone - solving what Knip cannot.",
   "type": "module",
   "main": "index.js",

package/src/EngineContext.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.0.0: Enterprise In-Memory Codebase State Manifest
+ * 📦 pkg-scaffold v3.3.0: Enterprise In-Memory Codebase State Manifest
  * ============================================================================
  * Implements a high-density, centralized graph database context for tracking
  * software engineering debt, dependencies, types, and vulnerabilities.
@@ -145,7 +145,7 @@ export class EngineContext {
       unusedDependenciesCount: 0
     };
     this.usedExternalPackages = new Set(); // Global set of used npm packages
-    this.manifestDependencies = new Map(); // Package.json path -> { dependencies, devDependencies }
+    this.manifestDependencies = new Map(); // Package.json path -> { dependencies, devDependencies, peerDependencies, optionalDependencies }
   }
 
   /**
@@ -256,20 +256,17 @@ export class EngineContext {
 
       const relativePath = path.relative(this.cwd, filePath);
 
-      // Category A: Completely orphaned components (no references, not library/framework entries)
-      // A file with ANY @scaffold-suppress directive is considered intentionally retained and must
-      // never be flagged as orphaned, even if no other file imports it directly.
+      // Category A: Completely orphaned components
       const fileHasSuppressDirective = node.localSuppressedRules.size > 0;
       if (node.incomingEdges.size === 0 && !node.isLibraryEntry && !node.isFrameworkContract && !fileHasSuppressDirective) {
         summary.structuralIssuesDetected.deadFiles.push(relativePath);
-        continue; // An orphaned file implies all internal sub-exports are dead; skip sub-checks
+        continue;
       }
 
-      // Category B: Dead Named Exports inside active files
+      // Category B: Dead Named Exports
       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)) {
@@ -288,7 +285,7 @@ export class EngineContext {
         }
       }
 
-      // Category C: High-Entropy Password / Key Hardcode Vulnerabilities
+      // Category C: Security Vulnerabilities
       if (node.securityThreats && node.securityThreats.length > 0) {
         node.securityThreats.forEach(threat => {
           summary.structuralIssuesDetected.securityThreats.push({
@@ -302,21 +299,28 @@ export class EngineContext {
       }
     }
 
-    // Category D: Unused Dependencies Audit
+    // Category D: Unused Dependencies Audit (Enhanced Classification)
     for (const [manifestPath, manifestData] of this.manifestDependencies.entries()) {
       const relativeManifest = path.relative(this.cwd, manifestPath);
       
-      // We only audit 'dependencies' for now as devDependencies are harder to track (test files, tools, etc.)
-      for (const dep of manifestData.dependencies) {
-        if (!this.usedExternalPackages.has(dep)) {
-          summary.structuralIssuesDetected.unusedDependencies.push({
-            manifest: relativeManifest,
-            package: dep,
-            type: 'dependency'
-          });
-          this.metrics.unusedDependenciesCount++;
+      const checkDeps = (deps, type) => {
+        if (!deps) return;
+        for (const dep of deps) {
+          if (!this.usedExternalPackages.has(dep)) {
+            summary.structuralIssuesDetected.unusedDependencies.push({
+              manifest: relativeManifest,
+              package: dep,
+              type: type
+            });
+            this.metrics.unusedDependenciesCount++;
+          }
         }
-      }
+      };
+
+      checkDeps(manifestData.dependencies, 'dependency');
+      checkDeps(manifestData.devDependencies, 'devDependency');
+      checkDeps(manifestData.peerDependencies, 'peerDependency');
+      checkDeps(manifestData.optionalDependencies, 'optionalDependency');
     }
 
     return summary;

package/src/api/HeadlessAPI.js

@@ -105,6 +105,17 @@ export class HeadlessAPI extends EventEmitter {
         }
       }
 
+      // 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) {

package/src/ast/ASTAnalyzer.js

@@ -40,8 +40,9 @@ export class ASTAnalyzer {
    */
   async processFile(filePath, fileNode) {
     // Fast Path: Use OXC for rapid scanning if type checking is not strictly required for this file
-    if (this.context.fastMode) {
-      return await this.oxc.processFile(filePath, fileNode);
+    if (this.context.fastMode && this.oxc.isAvailable) {
+      const success = await this.oxc.processFile(filePath, fileNode);
+      if (success) return true;
     }
 
     if (!this.program) {

package/src/ast/OxcAnalyzer.js

@@ -1,21 +1,35 @@
-import { parseSync } from 'oxc-parser';
+let oxcParser;
+try {
+  oxcParser = await import('oxc-parser');
+} catch (e) {
+  // OXC is optional; will fall back to TypeScript in ASTAnalyzer
+}
+
 import fs from 'fs/promises';
 
 /**
  * High-Performance AST Analyzer using OXC (Rust-based)
  * Designed to outpace Knip v6 by utilizing the fastest parser in the JS ecosystem.
+ * Includes automatic fallback if OXC is not available in the environment.
  */
 export class OxcAnalyzer {
   constructor(context) {
     this.context = context;
+    this.isAvailable = !!oxcParser;
   }
 
   async processFile(filePath, fileNode) {
+    if (!this.isAvailable) {
+      if (this.context.verbose) {
+        console.warn(`[OXC] Library not available, skipping fast-scan for: ${filePath}`);
+      }
+      return false;
+    }
+
     try {
       const sourceText = await fs.readFile(filePath, 'utf8');
       
-      // OXC is significantly faster than TypeScript for single-pass analysis
-      const { program } = parseSync(sourceText, {
+      const { program } = oxcParser.parseSync(sourceText, {
         sourceFilename: filePath,
         sourceType: filePath.endsWith('.ts') || filePath.endsWith('.tsx') ? 'typescript' : 'script'
       });
@@ -33,8 +47,6 @@ export class OxcAnalyzer {
   walkOxcNode(node, fileNode) {
     if (!node) return;
 
-    // OXC AST structure is slightly different from TS
-    // We focus on imports, exports, and namespace members
     if (node.type === 'ImportDeclaration') {
       const specifier = node.source.value;
       fileNode.explicitImports.add(specifier);
@@ -64,7 +76,6 @@ export class OxcAnalyzer {
       fileNode.internalExports.set('default', { type: 'default-export' });
     }
 
-    // Phase 3: Namespace Member Tracking
     if (node.type === 'TSModuleDeclaration' && node.id.type === 'Identifier') {
       const namespaceName = node.id.name;
       if (node.body && node.body.type === 'TSModuleBlock') {
@@ -86,7 +97,6 @@ export class OxcAnalyzer {
       }
     }
 
-    // Recursively walk
     for (const key in node) {
       const child = node[key];
       if (child && typeof child === 'object') {