pkg-scaffold 3.3.3 → 3.3.5

package/README.md

@@ -1,41 +1,81 @@
-# README
+# 📦 pkg-scaffold
 
 ![Logo](./logo.png)
 
-**The Ultimate Enterprise Codebase Janitor: OXC-Powered, Type-Aware, and Self-Healing.**
+> **The Ultimate Enterprise Codebase Janitor.** Faster than Knip with OXC integration, type-aware analysis, and automated structural healing. Fully standalone - solving what Knip cannot.
 
-![Version](https://img.shields.io/badge/version-3.1.3-blue.svg) ![License](https://img.shields.io/badge/license-MIT-green.svg) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/DreamLongYT/pkg-scaffold/npm-publish.yml?branch=main) ![Performance](https://img.shields.io/badge/performance-OXC--Inside-blueviolet.svg)
+![Version](https://img.shields.io/npm/v/pkg-scaffold) ![License](https://img.shields.io/badge/license-Apache--2.0-green.svg) ![Performance](https://img.shields.io/badge/performance-OXC--Inside-blueviolet.svg)
 
-`pkg-scaffold` is the industry's most advanced codebase optimization engine. Version 3.1.3 marks a massive leap forward, outperforming Knip v6 with a hybrid **OXC + TypeScript** architecture. It doesn't just find dead code—it safely prunes it and validates your project's integrity through a unique **Self-Healing Loop**.
+`pkg-scaffold` is a next-generation tool designed to declutter your JavaScript and TypeScript projects. It finds unused files, unused dependencies, dead code, circular dependencies, and more. It is built to be a direct and superior competitor to `knip.dev`.
 
-## Features
+## 🚀 Why pkg-scaffold over Knip?
 
-- **Extreme Speed with OXC**: By integrating the Rust-based OXC parser, `pkg-scaffold` achieves a 2-4x performance boost.
-- **True Type-Aware Analysis**: Uses the full TypeScript Compiler API to resolve types across your entire project.
-- **Automated Self-Healing**: Identifies unused code, removes it, and validates the change through tests.
-- **Modular Plugin Ecosystem**: Supports local configurations and custom plugins, including Knip compatibility.
+*   **⚡ Blazing Fast:** Powered by `oxc-parser` (Rust-based) for lightning-fast AST traversal. Fallback to TypeScript compiler API when needed.
+*   **🔌 Massive Plugin Ecosystem:** Over 20+ built-in plugins (Next.js, Nuxt, SvelteKit, Tailwind, Jest, Vitest, Playwright, GitHub Actions, Webpack, Babel, Rollup, ESLint, Prettier, Husky, and many more).
+*   **💀 True Dead Code Detection:** Advanced graph-based reachability analysis to find truly dead files and unused exports, even deep within your codebase.
+*   **🔄 Circular Dependency Detection:** High-performance Tarjan-based algorithm to detect and report circular dependencies.
+*   **🛡️ Supply Chain Guard:** Detects typosquatting and verifies integrity lockfile hashes.
+*   **🛠️ Automated Structural Healing:** Not just reporting, but automatically fixing structural issues (removing dead files, pruning unused dependencies) with git-based rollback protection.
+*   **⚙️ Flexible Configuration:** Supports `pkg-scaffold.json`, `pkg-scaffold.ts`, `scaffold.config.js`, and more.
 
-## Getting Started
-
-### Installation
+## 📦 Installation
 
 ```bash
-npm install -g pkg-scaffold
+npm install -D pkg-scaffold
+# or
+pnpm add -D pkg-scaffold
+# or
+pnpm add -D pkg-scaffold
 ```
 
-### Usage
+## 🚀 Usage
+
+Run the CLI at the root of your project:
 
 ```bash
-pkg-scaffold init my-project
-pkg-scaffold --fix --test-command 'npm test'
+npx pkg-scaffold --run
 ```
 
-## Documentation
+### CLI Options
+
+*   `-c, --cwd <path>`: Specify the execution context root directory.
+*   `--fix`: Enable atomic code updates, structural file pruning, and active type sanitization.
+*   `--no-fix`: Disable direct file manipulation (dry-run reporting mode).
+*   `--tsconfig <filename>`: Specify path to custom layout configurations.
+*   `--verbose`: Toggle expanded trace telemetry for debug operational diagnostics.
+*   `-r, --run`: Execute the primary operational pipeline loop.
+*   `-y, --yes`: Skip confirmation prompts.
+
+## ⚙️ Configuration
+
+Create a `pkg-scaffold.json` (or `.js`, `.ts`) in your project root:
+
+```json
+{
+  "entryPoints": ["src/index.ts"],
+  "exclude": ["node_modules/**", "dist/**", "**/*.test.ts"],
+  "rules": {
+    "no-unused-exports": "error",
+    "no-dead-code": "error"
+  }
+}
+```
+
+## 🔌 Supported Plugins
+
+`pkg-scaffold` automatically detects your ecosystem and enables the relevant plugins:
+
+*   **Frameworks:** Next.js, Nuxt, Remix, SvelteKit, Astro, Vue, Angular
+*   **Testing:** Jest, Vitest, Playwright, Cypress
+*   **Build Tools:** Webpack, Rollup, Babel, PostCSS, TailwindCSS
+*   **Linters/Formatters:** ESLint, Prettier, Commitlint, Lint-Staged, Husky
+*   **CI/CD:** GitHub Actions
+*   **And more!**
+
+## 🤝 Contributing
 
-- [home](https://dreamlongyt.github.io/pkg-scaffold/)
-- [guide](https://dreamlongyt.github.io/pkg-scaffold/guide)
-- [references](https://dreamlongyt.github.io/pkg-scaffold/reference)
+Contributions are welcome! Please open an issue or submit a pull request.
 
-## License
+## 📄 License
 
-MIT © DreamLongYT & The Enhanced Contributors.
+Apache-2.0 License.

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.3.2');
+      .version(packageJsonContent.version || '3.3.5');
 
     program
       .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
@@ -105,9 +105,9 @@ async function bootstrap() {
     // Load local config if available
     let localConfig = {};
     try {
-      const configPath = path.join(targetCwd, 'pkg-scaffold', 'config.json');
-      const configData = await fs.readFile(configPath, 'utf8');
-      localConfig = JSON.parse(configData);
+      const { ConfigLoader } = await import('../src/resolution/ConfigLoader.js');
+      const loader = new ConfigLoader(targetCwd);
+      localConfig = await loader.loadConfig(targetCwd);
     } catch (e) {}
 
     // Merge options with local config
@@ -130,9 +130,9 @@ async function bootstrap() {
     }, 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.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.3.5'} Engine Activation`));
     console.log(ansis.dim('------------------------------------------------------------'));
-    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(path.resolve(options.cwd))}`);
+    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(targetCwd)}`);
     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'));
@@ -140,7 +140,7 @@ async function bootstrap() {
     const { RefactoringEngine } = await import('../src/index.js');
 
     const engine = new RefactoringEngine({
-      cwd: path.resolve(options.cwd),
+      cwd: targetCwd,
       autoFix: options.fix,
       tsconfig: options.tsconfig,
       testCommand: options.testCommand,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pkg-scaffold",
-  "version": "3.3.3",
-  "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.",
+  "version": "3.3.5",
+  "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": {
@@ -13,7 +13,7 @@
     "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",
+    "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": [
@@ -48,7 +48,8 @@
     "package.json",
     "packages",
     "scan",
-    "self-healing",
+
+    "structural-healing",
     "setup",
     "type",
     "types",

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: set this to true or false

package/src/EngineContext.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.3.0: Enterprise In-Memory Codebase State Manifest
+ * 📦 pkg-scaffold v3.3.5: Enterprise In-Memory Codebase State Manifest
  * ============================================================================
  * Implements a high-density, centralized graph database context for tracking
  * software engineering debt, dependencies, types, and vulnerabilities.
@@ -8,6 +8,7 @@
 
 import path from 'path';
 import fs from 'fs/promises';
+import { DependencyProfiler } from './resolution/DependencyProfiler.js';
 
 /**
  * High-Fidelity Graph Element Node representing a single file asset boundary.
@@ -25,6 +26,9 @@ export class GraphNode {
     this.explicitImports = new Set();
     this.dynamicImports = new Set();
     this.importedSymbols = new Set(); // Format: 'specifier:symbol' or 'specifier:*'
+    this.jsxComponents = new Set();
+    this.jsxProps = new Set();
+    this.decorators = new Set();
     
     // Internal API Exposed Interfaces (Symbol Name -> ExportMetadata)
     this.internalExports = new Map();
@@ -39,8 +43,7 @@ export class GraphNode {
     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 = [];
+    // Structural Syntax Boundaries
     this.calculatedDynamicImports = [];
     this.localSuppressedRules = new Set();
     this.externalPackageUsage = new Set(); // Tracked third-party package names
@@ -87,6 +90,17 @@ export class GraphNode {
 
       // Safe fallback lookup inside string reference caches (e.g., obj['databaseUrl'])
       if (parentNode.rawStringReferences.has(symbolName)) return true;
+
+      // Check for JSX component usage
+      if (parentNode.jsxComponents.has(symbolName)) return true;
+
+      // Check for JSX prop usage (e.g., <MyComponent myProp={symbolName} />)
+      for (const jsxProp of parentNode.jsxProps) {
+        if (jsxProp.endsWith(`:${symbolName}`)) return true;
+      }
+
+      // Check for decorator usage
+      if (parentNode.decorators.has(symbolName)) return true;
     }
 
     return false;
@@ -146,6 +160,9 @@ export class EngineContext {
     };
     this.usedExternalPackages = new Set(); // Global set of used npm packages
     this.manifestDependencies = new Map(); // Package.json path -> { dependencies, devDependencies, peerDependencies, optionalDependencies }
+
+    // DependencyProfiler instance for implicit invocation tracing
+    this._depProfiler = new DependencyProfiler(this);
   }
 
   /**
@@ -223,7 +240,7 @@ export class EngineContext {
    * Processes the entire active dependency map to compile structural issue indices.
    * Evaluates orphaned components, dead exports, and supply-chain threats.
    */
-  generateSummaryReport() {
+  async generateSummaryReport() {
     this.metrics.endTime = Date.now();
     const durationSeconds = ((this.metrics.endTime - this.metrics.startTime) / 1000).toFixed(2);
     
@@ -240,7 +257,6 @@ export class EngineContext {
       structuralIssuesDetected: {
         deadFiles: [],
         deadExports: [],
-        securityThreats: [],
         unusedDependencies: []
       },
       modificationsExecuted: {
@@ -252,6 +268,11 @@ export class EngineContext {
     for (const [filePath, node] of this.graph.entries()) {
       // Skip package control files from standard structural dead-code checks
       if (filePath.endsWith('package.json')) continue;
+      
+      // Fix: Always track external package usage from all files, even if they are orphaned,
+      // to prevent false-positive unused dependency reports.
+      node.externalPackageUsage.forEach(pkg => this.usedExternalPackages.add(pkg));
+
       if (this.isPathIgnored(filePath)) continue;
 
       const relativePath = path.relative(this.cwd, filePath);
@@ -285,28 +306,34 @@ export class EngineContext {
         }
       }
 
-      // Category C: Security 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
-          });
-        });
-      }
     }
 
     // Category D: Unused Dependencies Audit (Enhanced Classification)
     for (const [manifestPath, manifestData] of this.manifestDependencies.entries()) {
       const relativeManifest = path.relative(this.cwd, manifestPath);
-      
+      const packageRoot = path.dirname(manifestPath);
+
+      // Collect packages that are implicitly used via scripts / config files
+      const implicitlyUsed = await this._depProfiler.traceImplicitInvocations(packageRoot);
+
+      // Resolve peer dependencies of all used packages so they are not flagged
+      const allUsedForPeerResolution = new Set([...this.usedExternalPackages, ...implicitlyUsed]);
+      const peerDepsOfUsed = await this._depProfiler.resolvePeerDependencies(allUsedForPeerResolution, packageRoot);
+
       const checkDeps = (deps, type) => {
         if (!deps) return;
         for (const dep of deps) {
-          if (!this.usedExternalPackages.has(dep)) {
+          // Skip peer and optional dependencies – they are never "unused" in the
+          // traditional sense because they are not required to be imported directly.
+          if (this._depProfiler.shouldExcludeFromUnusedCheck(dep, type)) {
+            continue;
+          }
+
+          const isUsedInCode = this.usedExternalPackages.has(dep);
+          const isUsedImplicitly = implicitlyUsed.has(dep);
+          const isRequiredAsPeer = peerDepsOfUsed.has(dep);
+
+          if (!isUsedInCode && !isUsedImplicitly && !isRequiredAsPeer) {
             summary.structuralIssuesDetected.unusedDependencies.push({
               manifest: relativeManifest,
               package: dep,
@@ -319,6 +346,7 @@ export class EngineContext {
 
       checkDeps(manifestData.dependencies, 'dependency');
       checkDeps(manifestData.devDependencies, 'devDependency');
+      // peerDependencies and optionalDependencies are excluded via shouldExcludeFromUnusedCheck
       checkDeps(manifestData.peerDependencies, 'peerDependency');
       checkDeps(manifestData.optionalDependencies, 'optionalDependency');
     }