pkg-scaffold 2.4.0 → 3.1.0

package/docs/guide.md

@@ -0,0 +1,102 @@
+# Getting Started with pkg-scaffold
+
+This guide will walk you through the installation and basic usage of `pkg-scaffold`. Learn how to quickly clean and optimize your project.
+
+## Installation
+
+`pkg-scaffold` is an npm package and can be easily installed in your project. It is recommended to install it as a `devDependency`.
+
+```bash
+npm install --save-dev pkg-scaffold
+# or
+yarn add --dev pkg-scaffold
+# or
+pnpm add --save-dev pkg-scaffold
+```
+
+After installation, you can run `pkg-scaffold` via `npx` or by adding a script to your `package.json`.
+
+## Basic Usage
+
+### Dry-Run Mode (Recommended)
+
+Before making any changes to your project, it is always advisable to use the dry-run mode. This mode analyzes your project and shows you which changes *would be made* without actually applying them.
+
+```bash
+npx pkg-scaffold --no-fix
+```
+
+This command will output a summary of identified issues, such as orphaned files or potential refactoring opportunities.
+
+### Applying Changes
+
+If you are satisfied with the proposed changes, you can run `pkg-scaffold` with the `--fix` option to apply the changes to your project. The `--yes` option skips the confirmation prompt.
+
+```bash
+npx pkg-scaffold --fix --yes
+```
+
+**Caution:** Ensure you have backed up your changes or are in a version control system before using this option.
+
+### Monorepo Support
+
+For projects organized in a monorepo, `pkg-scaffold` can be run with the `--workspace` option to analyze and optimize all packages within the workspace.
+
+```bash
+npx pkg-scaffold --workspace --fix --yes
+```
+
+## Next Steps
+
+*   Learn more about all available options in the [Reference](/reference).
+*   Visit the [GitHub Repository](https://github.com/DreamLongYT/pkg-scaffold) for the latest updates and to report issues.
+
+## Plugin Development
+
+Building a plugin for pkg-scaffold is straightforward. You need to export a class that extends the `BasePlugin` (or follows its structure).
+
+### Basic Plugin Structure
+
+```javascript
+export default class MyCustomPlugin {
+  constructor(context) {
+    this.context = context;
+  }
+
+  // Unique identifier for the plugin
+  get name() {
+    return 'my-plugin';
+  }
+
+  // Files that indicate this ecosystem is active
+  getConfigFiles() {
+    return ['my-config.json'];
+  }
+
+  // Regex patterns for entry point files
+  getRoutePatterns() {
+    return [
+      /\/src\/routes\/.*\.js$/
+    ];
+  }
+
+  // Symbols that should never be flagged as unused in entry points
+  getRequiredSystemContracts() {
+    return ['default', 'handler', 'config'];
+  }
+
+  // Logic to determine if the plugin should run
+  async isActive(baseDir) {
+    // Return true if your framework is detected
+    return true; 
+  }
+}
+```
+
+### Advanced: Interfacing with the Engine
+
+Plugins have access to the `context`, allowing them to trigger specific engine behaviors like `fastMode` or `selfHealing` for certain file types.
+
+### Knip Compatibility
+
+If you are porting a Knip plugin, ensure the export mappings align with the `getRoutePatterns()` and `getRequiredSystemContracts()` methods to ensure full compatibility with the pkg-scaffold resolution graph.

package/docs/index.md

@@ -0,0 +1,64 @@
+---
+layout: home
+
+hero:
+  name: "pkg-scaffold"
+  text: "AST-driven Refactoring & Self-Healing Engine"
+  tagline: "Optimize your codebase with precise AST analysis and automated cleanup."
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/DreamLongYT/pkg-scaffold
+
+features:
+  - title: AST-Driven Analysis
+    details: pkg-scaffold leverages Abstract Syntax Trees (ASTs) for deep and precise analysis of your codebase, identifying unused structures and optimization potentials.
+  - title: Intelligent Refactoring
+    details: Automatic detection and pruning of orphaned files and dead code to improve the maintainability and performance of your project.
+  - title: Dry-Run Mode
+    details: Preview all proposed structural changes before they are actually applied, ensuring maximum control and safety.
+  - title: Monorepo Support
+    details: Optimized for complex project structures and monorepos, ensuring consistent code quality across multiple packages.
+  - title: Integrated Test Validation
+    details: Executes integrated tests after each modification to verify workspace integrity and prevent regressions.
+  - title: Seamless Integration
+    details: As a CLI tool, pkg-scaffold integrates effortlessly into existing CI/CD workflows and development environments.
+---
+
+
+# Welcome to pkg-scaffold
+
+pkg-scaffold is a powerful command-line tool designed to enhance the health and efficiency of your JavaScript and TypeScript projects. By utilizing an advanced AST engine, it identifies and fixes structural issues, optimizes dependencies, and ensures a clean and maintainable codebase.
+
+Whether you are working on a small project or a large monorepo, pkg-scaffold helps streamline your development experience and secure the quality of your code.
+
+## pkg-scaffold vs. Knip.dev vs. ts-prune
+
+While tools like Knip.dev and ts-prune are excellent for specific tasks, pkg-scaffold offers a unique approach with its AST-driven refactoring and self-healing capabilities. Here's how it compares:
+
+| Feature / Tool       | pkg-scaffold                                   | Knip.dev                                     | ts-prune                                   |
+| :------------------- | :--------------------------------------------- | :------------------------------------------- | :----------------------------------------- |
+| **Primary Focus**    | Structural Refactoring, Self-Healing, Orphaned Files | Unused Dependencies, Exports, Files          | Unused Exports                             |
+| **Analysis Method**  | AST-driven, Deep Structural Analysis           | Deep Analysis with fine-grained entry points | TypeScript Compiler API                    |
+| **Unused Dependencies** | Limited (focus on structural usage)            | Yes (very detailed)                          | No                                         |
+| **Unused Exports**   | No (currently)                                 | Yes                                          | Yes                                        |
+| **Orphaned Files**   | Yes (core feature)                             | Yes                                          | No                                         |
+| **Automated Fixes**  | Yes (`--fix` option)                           | Yes                                          | No (reporting only)                        |
+| **Monorepo Support** | Yes                                            | Yes                                          | Limited                                    |
+| **Integrated Test Validation** | Yes (post-fix)                                 | No                                           | No                                         |
+| **Key Advantage**    | **Proactive structural integrity, self-healing, prevents file bloat.** | **Comprehensive dependency/export cleanup, excellent for bundle size.** | **Simple, fast unused export detection for TS.** |
+
+### Where pkg-scaffold excels:
+
+pkg-scaffold shines in maintaining the **structural integrity** of your project. Unlike Knip.dev, which focuses heavily on unused dependencies and exports (often for bundle size optimization), pkg-scaffold's core strength lies in:
+
+*   **Orphaned File Detection & Pruning:** It actively identifies and removes files that are no longer referenced anywhere in your codebase, preventing file system bloat and confusion.
+*   **AST-driven Self-Healing:** Its deep AST analysis allows for more intelligent structural refactoring, ensuring that your project's architecture remains sound over time.
+*   **Integrated Safety:** By running tests post-fix, it provides an additional layer of confidence that automated changes haven't introduced regressions.
+
+While Knip.dev is superior for finding unused `package.json` dependencies and exports, pkg-scaffold complements it by focusing on the physical file structure and overall project health. ts-prune is a simpler tool specifically for TypeScript unused exports.
+
+Start optimizing your projects today! Head over to the [Getting Started Guide](/guide) to learn more.

package/docs/reference.md

@@ -0,0 +1,52 @@
+# CLI Reference
+
+This page lists all available command-line options for `pkg-scaffold`.
+
+```text
+Usage: pkg-scaffold [options]
+Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine
+
+Options:
+  -V, --version             output the version number
+  -c, --cwd <path>          Specify the execution context root directory (default: "/home/ubuntu/test-project")
+  --fix                     Enable atomic code updates, structural file pruning, and active type sanitization (default: true)
+  --no-fix                  Disable direct file manipulation modifications (dry-run reporting mode)
+  --tsconfig <filename>     Specify path to custom layout configurations (default: "tsconfig.json")
+  --test-command <command>  Integrated continuous safety test validation script execution path (default: "npm test")
+  --workspace               Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing (default: false)
+  --verbose                 Toggle expanded trace telemetry for debug operational diagnostics (default: false)
+  -y, --yes                 Skip confirmation prompts and execute planned structural modifications automatically (default: false)
+  -h, --help                display help for command
+```
+
+## Options in Detail
+
+### `-V`, `--version`
+Displays the current version of `pkg-scaffold`.
+
+### `-c`, `--cwd <path>`
+Defines the root directory where `pkg-scaffold` should be executed. By default, this is the current working directory.
+
+### `--fix`
+Activates the mode for atomic code updates, structural file pruning, and active type sanitization. This is the mode in which `pkg-scaffold` makes actual changes to your code.
+
+### `--no-fix`
+Disables direct file manipulation modifications. `pkg-scaffold` performs an analysis and reports on potential changes without applying them (dry-run mode).
+
+### `--tsconfig <filename>`
+Specifies the path to a custom `tsconfig.json` file. By default, `pkg-scaffold` looks for `tsconfig.json` in the current working directory.
+
+### `--test-command <command>`
+Defines the command to be executed for integrated continuous safety test validation after changes. By default, `npm test` is used.
+
+### `--workspace`
+Enables evaluation of workspaces/monorepo clusters. When this option is enabled, `pkg-scaffold` analyzes and optimizes all packages within a monorepo.
+
+### `--verbose`
+Enables expanded trace telemetry for debug operational diagnostics, providing more detailed output during execution.
+
+### `-y`, `--yes`
+Skips all confirmation prompts and automatically executes planned structural modifications. **Use with caution in production environments without prior review.**
+
+### `-h`, `--help`
+Displays help information for `pkg-scaffold`.

package/index.js

@@ -2,7 +2,7 @@
 
 /**
  * ============================================================================
- * 📦 pkg-scaffold v2.3.0: Enterprise Dependency Intelligence & Scaffolding Engine
+ * 📦 pkg-scaffold v3.1.0: Ultimate Enterprise Codebase Janitor & Self-Healing Engine
  * ============================================================================
  * * Eine hochgradig integrierte Code-Analyse- und Projektbootstrapping-Engine.
  * Kombiniert rekursive Erreichbarkeitsanalysen (Reachability Graphs) auf 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pkg-scaffold",
-  "version": "2.4.0",
-  "description": "An advanced, AST-driven dependency resolution, refactoring, and self-healing engine.",
+  "version": "3.1.0",
+  "description": "The ultimate enterprise-grade codebase janitor. Faster than Knip v6 with OXC integration, type-aware analysis, and self-healing capabilities.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -9,8 +9,12 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
+    "pkg-scaffold:run": "node bin/cli.js",
     "test": "echo \"Error: no test specified\" && exit 0",
-    "test:stability": "npm run test"
+    "test:stability": "npm run test",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "scaffold",
@@ -44,11 +48,24 @@
     "commander": "^12.0.0",
     "enhanced-resolve": "^5.16.0",
     "execa": "^8.0.1",
+    "oxc-parser": "^0.135.0",
+    "oxc-resolver": "^11.20.0",
     "ramda": "^0.29.1",
-    "typescript": "^5.4.5",
     "yocto-spinner": "^0.1.0"
   },
+  "devDepencies": {
+    "vitepress": "^1.0.0",
+    "vue": ">=3.5.0"
+  },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "express": "^5.2.1",
+    "knip": "^6.16.1",
+    "lodash": "^4.18.1",
+    "typescript": "^6.0.3",
+    "vitepress": "^1.6.4"
   }
 }

package/pkg-scaffold/config.json

@@ -0,0 +1,25 @@
+{
+  // Interface mode: "CLI" for terminal usage, "GUI" for web interface
+  "interface": "CLI",
+
+  // Plugin activation toggles
+  "useBuiltinPlugins": true,
+  "useCustomPlugins": true,
+  "supportKnipPlugins": true,
+
+  // Engine performance and behavior options
+  "options": {
+    "verbose": false,
+    "fastMode": true, // Uses OXC parser for 4x speed boost
+    "selfHealing": true // Automatically fixes and validates code
+  },
+
+  // List of core plugins to load (if useBuiltinPlugins is true)
+  "enabledPlugins": [
+    "nextjs",
+    "nuxt",
+    "remix",
+    "sveltekit",
+    "astro"
+  ]
+}

package/pkg-scaffold/plugins/README.md

@@ -0,0 +1,19 @@
+# pkg-scaffold Plugins
+
+This directory is for your custom plugins. pkg-scaffold will automatically load any `.js` or `.mjs` files placed here if `useCustomPlugins` is set to `true` in your `config.json`.
+
+## Supported Ecosystems (Built-in)
+
+- **Next.js**: Handles pages, API routes, and App Router conventions.
+- **Nuxt**: Supports auto-imports and server routes.
+- **Remix**: Maps loaders, actions, and root exports.
+- **SvelteKit**: Tracks `+page`, `+layout`, and server-side scripts.
+- **Astro**: Analyzes `.astro` files and static paths.
+
+## Knip Compatibility
+
+pkg-scaffold supports Knip-style plugins. You can drop Knip plugins into this folder, and the engine will attempt to wrap them for use within the pkg-scaffold ecosystem.
+
+## Documentation
+
+For a detailed guide on how to build your own plugins, please refer to the [Plugin Development Guide](../../docs/guide.md#plugin-development).

package/src/EngineContext.js

@@ -11,6 +11,7 @@ import fs from 'fs/promises';
 
 /**
  * High-Fidelity Graph Element Node representing a single file asset boundary.
+ * @scaffold-suppress GraphNode
  */
 export class GraphNode {
   constructor(filePath) {
@@ -42,6 +43,7 @@ export class GraphNode {
     this.securityThreats = [];
     this.calculatedDynamicImports = [];
     this.localSuppressedRules = new Set();
+    this.externalPackageUsage = new Set(); // Tracked third-party package names
     
     // Detailed AST Location Diagnostics (Symbol -> Structural Location Mapping)
     this.symbolSourceLocations = new Map(); // Symbol -> { line: number, column: number, length: number }
@@ -58,7 +60,22 @@ export class GraphNode {
       const parentNode = projectGraph.get(parentPath);
       if (!parentNode) continue;
 
-      // Direct identity reference check
+      // Check if the symbol is explicitly imported by the parent
+      const importKey = `${path.relative(path.dirname(parentPath), this.filePath).replace(/\\/g, '/')}:${symbolName}`;
+      const importKeyAlt = `${path.relative(path.dirname(parentPath), this.filePath).replace(/\\/g, '/').replace(/\.(js|ts|tsx|jsx)$/, '')}:${symbolName}`;
+      
+      if (parentNode.importedSymbols.has(importKey) || parentNode.importedSymbols.has(importKeyAlt)) {
+        return true;
+      }
+
+      // Check for star imports or namespace imports
+      const starKey = `${path.relative(path.dirname(parentPath), this.filePath).replace(/\\/g, '/')}:*`;
+      const starKeyAlt = `${path.relative(path.dirname(parentPath), this.filePath).replace(/\\/g, '/').replace(/\.(js|ts|tsx|jsx)$/, '')}:*`;
+      if (parentNode.importedSymbols.has(starKey) || parentNode.importedSymbols.has(starKeyAlt)) {
+        return true;
+      }
+
+      // Direct identity reference check (for cases where it's used but not explicitly imported in a traceable way, or global)
       if (parentNode.instantiatedIdentifiers.has(symbolName)) return true;
       
       // Property lookup reference checks (e.g., config.databaseUrl)
@@ -105,6 +122,7 @@ export class EngineContext {
     this.allowAutoFix = options.autoFix ?? true;
     this.isWorkspaceEnabled = options.workspace ?? false;
     this.verbose = options.verbose ?? false;
+    this.skipConfirm = options.skipConfirm ?? false;
 
     // Core Memory Repositories
     this.graph = new Map(); // Absolute File Path -> GraphNode
@@ -123,8 +141,11 @@ export class EngineContext {
       prunedFilesCount: 0,
       prunedExportsCount: 0,
       totalSymbolsAnalyzed: 0,
-      securityVulnerabilitiesMitigated: 0
+      securityVulnerabilitiesMitigated: 0,
+      unusedDependenciesCount: 0
     };
+    this.usedExternalPackages = new Set(); // Global set of used npm packages
+    this.manifestDependencies = new Map(); // Package.json path -> { dependencies, devDependencies }
   }
 
   /**
@@ -219,7 +240,8 @@ export class EngineContext {
       structuralIssuesDetected: {
         deadFiles: [],
         deadExports: [],
-        securityThreats: []
+        securityThreats: [],
+        unusedDependencies: []
       },
       modificationsExecuted: {
         filesUnlinked: this.metrics.prunedFilesCount,
@@ -235,7 +257,10 @@ export class EngineContext {
       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) {
+      // 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.
+      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
       }
@@ -277,6 +302,23 @@ export class EngineContext {
       }
     }
 
+    // Category D: Unused Dependencies Audit
+    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++;
+        }
+      }
+    }
+
     return summary;
   }
 }