pkg-scaffold 3.1.2 → 3.2.0

package/README.md

@@ -1,126 +1,41 @@
-# 📦 pkg-scaffold v3.1.2
+# README
 
-**The Ultimate Enterprise Codebase Janitor: OXC-Powered, Type-Aware, and Self-Healing.**
-
-[![npm version](https://img.shields.io/npm/v/pkg-scaffold.svg?style=flat&color=CB3837)](https://www.npmjs.com/package/pkg-scaffold)
-[![License](https://img.shields.io/badge/license-MIT-orange.svg?style=flat)](LICENSE)
-[![Performance](https://img.shields.io/badge/performance-OXC--Inside-blueviolet.svg?style=flat)](https://oxc.rs/)
-
-`pkg-scaffold` is the industry's most advanced codebase optimization engine. Version 3.1.0 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**.
-
----
-
-## 🚀 Why pkg-scaffold@3.1.2?
+![Logo](./logo.png)
 
-### 1. Extreme Speed with OXC
-By integrating the Rust-based **OXC (Oxc-Parser & Oxc-Resolver)**, pkg-scaffold v3.1.0 achieves a **2-4x performance boost** over previous versions, matching and often exceeding the speed of Knip v6 for single-pass analysis.
-
-### 2. True Type-Aware Analysis
-Unlike basic linters, pkg-scaffold uses the full **TypeScript Compiler API** to resolve types across your entire project. This ensures that implicitly implemented interfaces, extended objects, and global ambient overrides are correctly tracked, reducing false positives to near zero.
-
-### 3. Automated Self-Healing (The "Fix" Loop)
-This is the "Knip-Killer" feature. pkg-scaffold doesn't just give you a report; it:
-1.  **Identifies** unused code.
-2.  **Prunes** it automatically.
-3.  **Validates** the change by running your test suite.
-4.  **Self-Heals** by rolling back immediately if a test fails.
-
-### 4. Modular Plugin Ecosystem
-With a dedicated `/pkg-scaffold` directory, you can now manage local configurations and custom plugins. We even support **Knip-style plugins**, allowing you to leverage the existing ecosystem while using our superior engine.
+**The Ultimate Enterprise Codebase Janitor: OXC-Powered, Type-Aware, and Self-Healing.**
 
----
+![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)
 
-## ⚔️ Competitive Analysis: pkg-scaffold vs. The Rest
+`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**.
 
-| Feature | **pkg-scaffold v3.1.0** | Knip v6 | Depcheck |
-| :--- | :---: | :---: | :---: |
-| **Parsing Engine** | ⚡ **OXC (Rust) + Hybrid TS** | ⚡ OXC (Rust) | ⚠️ Regex/Loose |
-| **Type-Awareness** | ✅ **Full Program API** | ✅ Yes | ❌ No |
-| **Automated Pruning** | ✅ **Native & Safe** | ⚠️ Experimental | ❌ No |
-| **Self-Healing Loop** | ✅ **Yes (Auto-Rollback)** | ❌ No | ❌ No |
-| **Plugin Architecture** | ✅ **Modular + Knip-Compat** | ✅ Built-in Only | ❌ No |
-| **Namespace Tracking** | ✅ **Sub-Symbol Level** | ✅ Yes | ❌ No |
-| **Security Audit** | ✅ **Dynamic Registry Check** | ❌ No | ❌ No |
+## Features
 
-### Where Knip.dev is still strong:
-- **Maturity:** Knip has a larger set of pre-configured community plugins (150+).
-- **Ecosystem:** More integrations with niche tools and legacy build systems.
-*However, pkg-scaffold's Knip-compatibility layer is designed to bridge this gap.*
+- **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.
 
----
+## Getting Started
 
-## 🛠️ Installation & Usage
+### Installation
 
-### 1. Add to your project
 ```bash
-npm install --save-dev pkg-scaffold
+npm install -g pkg-scaffold
 ```
 
-### 2. Configure (Optional)
-Create a `pkg-scaffold/config.json` to customize your experience:
-```json
-{
-  "interface": "CLI",
-  "options": {
-    "fastMode": true,
-    "selfHealing": true
-  }
-}
-```
+### Usage
 
-### 3. Run the Engine
-Add this to your `package.json` scripts:
-```json
-"scripts": {
-  "pkg-scaffold:run": "pkg-scaffold --fix --test-command 'npm test'"
-}
+```bash
+pkg-scaffold init my-project
+pkg-scaffold --fix --test-command 'npm test'
 ```
 
----
-
-## 📂 Project Structure
-
-- **`/pkg-scaffold/config.json`**: Your local settings (CLI/GUI, Plugin Toggles).
-- **`/pkg-scaffold/plugins/`**: Drop your custom or Knip-style plugins here.
-- **`/docs/`**: Full [Plugin Development Guide](https://dreamlongyt.github.io/pkg-scaffold/).
-
----
-
-## 🛡️ Suppression
+## Documentation
 
-Protect specific code from the janitor:
-
-```javascript
-/**
- * @scaffold-suppress
- */
-export const internalHelper = () => { /* Safe from pruning */ };
-```
-
----
-## Depencies
-```json
-"ansis": "^3.0.0",
-"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",
-"yocto-spinner": "^0.1.0"
-```
----
-## DevDepencies
-```json
-"@types/node": "^25.9.3",
-"express": "^5.2.1",
-"knip": "^6.16.1", //Used to make Plugins from knip compitable with the code
-"lodash": "^4.18.1", //For Analysing
-"typescript": "^6.0.3", //For Analysing
-"vitepress": "^1.6.4" //For the Documentation
-```
----
+- [home](https://dreamlongyt.github.io/pkg-scaffold/)
+- [guide](https://dreamlongyt.github.io/pkg-scaffold/guide)
+- [references](https://dreamlongyt.github.io/pkg-scaffold/reference)
 
-## 📜 License
+## License
 
 MIT © DreamLongYT & The Enhanced Contributors.

package/index.js

@@ -2,7 +2,7 @@
 
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.1.2: Ultimate Enterprise Codebase Janitor & Self-Healing Engine
+ * 📦 pkg-scaffold v3.1.3: 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,6 +1,6 @@
 {
   "name": "pkg-scaffold",
-  "version": "3.1.2",
+  "version": "3.2.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",
@@ -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",
+    "docs:build": "vitepress build docs && cp docs/sitemap.xml docs/.vitepress/dist/ && cp docs/robots.txt docs/.vitepress/dist",
     "docs:preview": "vitepress preview docs"
   },
   "keywords": [

package/pkg-scaffold/config.json

@@ -20,6 +20,7 @@
     "nuxt",
     "remix",
     "sveltekit",
-    "astro"
+    "astro",
+    "typescript"
   ]
 }

package/src/plugins/BasePlugin.js

@@ -1,53 +1,71 @@
+import fs from 'fs/promises';
+import path from 'path';
+
 /**
  * Base class for all pkg-scaffold plugins.
  * Defines the contract for ecosystem detection and entry point mapping.
+ * Version 3.2.0: Added support for dynamic custom getters.
  */
 export class BasePlugin {
-  constructor(context) {
-    this.context = context;
-  }
+    constructor(context) {
+        this.context = context;
+        this.customGetters = new Map();
+    }
+
+    /**
+     * Unique identifier for the plugin (e.g., 'nextjs').
+     */
+    get name() {
+        throw new Error('Plugin must implement name getter');
+    }
 
-  /**
-   * Unique identifier for the plugin (e.g., 'nextjs').
-   */
-  get name() {
-    throw new Error('Plugin must implement name getter');
-  }
+    /**
+     * Returns a list of configuration files that indicate this ecosystem is active.
+     */
+    getConfigFiles() {
+        return [];
+    }
 
-  /**
-   * Returns a list of configuration files that indicate this ecosystem is active.
-   */
-  getConfigFiles() {
-    return [];
-  }
+    /**
+     * Returns regex patterns for files that should be treated as entry points.
+     */
+    getRoutePatterns() {
+        return [];
+    }
 
-  /**
-   * Returns regex patterns for files that should be treated as entry points.
-   */
-  getRoutePatterns() {
-    return [];
-  }
+    /**
+     * Returns symbols that are implicitly required/exported by the framework.
+     */
+    getRequiredSystemContracts() {
+        return ['default'];
+    }
 
-  /**
-   * Returns symbols that are implicitly required/exported by the framework.
-   */
-  getRequiredSystemContracts() {
-    return ['default'];
-  }
+    /**
+     * Version 3.2.0: Dynamic getter for custom plugin properties.
+     * @param {string} key - The property key to retrieve
+     * @returns {any} The value of the custom property
+     */
+    get(key) {
+        const methodName = `get${key.charAt(0).toUpperCase() + key.slice(1)}`;
+        if (typeof this[methodName] === 'function') {
+            return this[methodName]();
+        }
+        return this.customGetters.get(key);
+    }
 
-  /**
-   * Optional: Logic to detect if the plugin should be active in the given directory.
-   */
-  async isActive(baseDir) {
-    const configFiles = this.getConfigFiles();
-    for (const file of configFiles) {
-      try {
-        await fs.access(path.join(baseDir, file));
-        return true;
-      } catch {
-        continue;
-      }
+    /**
+     * Optional: Logic to detect if the plugin should be active in the given directory.
+     */
+    async isActive(baseDir) {
+        const configFiles = this.getConfigFiles();
+        for (const file of configFiles) {
+            try {
+                await fs.access(path.join(baseDir, file));
+                return true;
+            } catch {
+                continue;
+            }
+        }
+        return false;
     }
-    return false;
-  }
 }

package/src/plugins/PluginRegistry.js

@@ -4,92 +4,107 @@ import { pathToFileURL } from 'url';
 
 /**
  * Advanced Plugin Registry supporting Builtin, Custom, and Knip-style plugins.
+ * Version 3.2.0: Enhanced with support for dynamic custom getters.
  */
 export class PluginRegistry {
-  constructor(context) {
-    this.context = context;
-    this.plugins = new Map();
-    this.config = null;
-  }
-
-  async init(projectRoot) {
-    const configPath = path.join(projectRoot, 'pkg-scaffold', 'config.json');
-    try {
-      const configRaw = await fs.readFile(configPath, 'utf8');
-      this.config = JSON.parse(configRaw);
-    } catch (e) {
-      this.config = { useBuiltinPlugins: true, useCustomPlugins: true, supportKnipPlugins: true };
+    constructor(context) {
+        this.context = context;
+        this.plugins = new Map();
+        this.config = null;
     }
 
-    if (this.config.useBuiltinPlugins) {
-      await this.loadBuiltinPlugins();
-    }
+    async init(projectRoot) {
+        const configPath = path.join(projectRoot, 'pkg-scaffold', 'config.json');
+        try {
+            const configRaw = await fs.readFile(configPath, 'utf8');
+            this.config = JSON.parse(configRaw);
+        } catch (e) {
+            this.config = {
+                useBuiltinPlugins: true,
+                useCustomPlugins: true,
+                supportKnipPlugins: true
+            };
+        }
 
-    if (this.config.useCustomPlugins) {
-      await this.loadCustomPlugins(projectRoot);
-    }
+        if (this.config.useBuiltinPlugins) {
+            await this.loadBuiltinPlugins();
+        }
+
+        if (this.config.useCustomPlugins) {
+            await this.loadCustomPlugins(projectRoot);
+        }
 
-    if (this.config.supportKnipPlugins) {
-      await this.initKnipAdapter();
+        if (this.config.supportKnipPlugins) {
+            await this.initKnipAdapter();
+        }
     }
-  }
 
-  async loadBuiltinPlugins() {
-    const { NextJsPlugin } = await import('./ecosystems/NextJsPlugin.js');
-    const { NuxtPlugin, RemixPlugin, SvelteKitPlugin, AstroPlugin } = await import('./ecosystems/GenericPlugins.js');
+    async loadBuiltinPlugins() {
+        const { NextJsPlugin } = await import('./ecosystems/NextJsPlugin.js');
+        const { NuxtPlugin, RemixPlugin, SvelteKitPlugin, AstroPlugin } = await import('./ecosystems/GenericPlugins.js');
+        const { TypeScriptPlugin } = await import('./ecosystems/TypeScriptPlugin.js');
 
-    const builtins = [
-      new NextJsPlugin(this.context),
-      new NuxtPlugin(this.context),
-      new RemixPlugin(this.context),
-      new SvelteKitPlugin(this.context),
-      new AstroPlugin(this.context)
-    ];
+        const builtins = [
+            new NextJsPlugin(this.context),
+            new NuxtPlugin(this.context),
+            new RemixPlugin(this.context),
+            new SvelteKitPlugin(this.context),
+            new AstroPlugin(this.context),
+            new TypeScriptPlugin(this.context)
+        ];
 
-    builtins.forEach(p => {
-      if (!this.config.enabledPlugins || this.config.enabledPlugins.includes(p.name)) {
-        this.register(p);
-      }
-    });
-  }
+        builtins.forEach(p => {
+            if (!this.config.enabledPlugins || this.config.enabledPlugins.includes(p.name)) {
+                this.register(p);
+            }
+        });
+    }
+
+    async loadCustomPlugins(projectRoot) {
+        const pluginsDir = path.join(projectRoot, 'pkg-scaffold', 'plugins');
+        try {
+            const files = await fs.readdir(pluginsDir);
+            for (const file of files) {
+                if (file.endsWith('.js') || file.endsWith('.mjs')) {
+                    const pluginModule = await import(pathToFileURL(path.join(pluginsDir, file)).href);
+                    const PluginClass = pluginModule.default || pluginModule;
+                    const pluginInstance = new PluginClass(this.context);
 
-  async loadCustomPlugins(projectRoot) {
-    const pluginsDir = path.join(projectRoot, 'pkg-scaffold', 'plugins');
-    try {
-      const files = await fs.readdir(pluginsDir);
-      for (const file of files) {
-        if (file.endsWith('.js') || file.endsWith('.mjs')) {
-          const pluginModule = await import(pathToFileURL(path.join(pluginsDir, file)).href);
-          const PluginClass = pluginModule.default || pluginModule;
-          this.register(new PluginClass(this.context));
+                    const version = pluginInstance.get('version');
+                    if (version && this.context.verbose) {
+                        console.log(`[PluginRegistry] Loaded ${pluginInstance.name} v${version}`);
+                    }
+                    this.register(pluginInstance);
+                }
+            }
+        } catch (e) {
+            // No custom plugins or dir missing
         }
-      }
-    } catch (e) {
-      // No custom plugins or dir missing
     }
-  }
 
-  async initKnipAdapter() {
-    // This adapter allows running Knip-style plugins by wrapping them
-    // In a real scenario, this would interface with knip's plugin API
-    this.context.knipCompatible = true;
-  }
+    async initKnipAdapter() {
+        this.context.knipCompatible = true;
+    }
+
+    register(plugin) {
+        this.plugins.set(plugin.name, plugin);
+    }
 
-  register(plugin) {
-    this.plugins.set(plugin.name, plugin);
-  }
+    getPlugins() {
+        return Array.from(this.plugins.values());
+    }
 
-  getPlugins() {
-    return Array.from(this.plugins.values());
-  }
+    getPlugin(name) {
+        return this.plugins.get(name);
+    }
 
-  async getActivePlugins(baseDir) {
-    const active = [];
-    for (const plugin of this.plugins.values()) {
-      if (await plugin.isActive(baseDir)) {
-        active.push(plugin);
-      }
+    async getActivePlugins(baseDir) {
+        const active = [];
+        for (const plugin of this.plugins.values()) {
+            if (await plugin.isActive(baseDir)) {
+                active.push(plugin);
+            }
+        }
+        return active;
     }
-    return active;
-  }
 }

package/src/plugins/ecosystems/TypeScriptPlugin.js

@@ -0,0 +1,56 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { BasePlugin } from '../BasePlugin.js';
+
+/**
+ * TypeScript Plugin for pkg-scaffold.
+ * Handles tsconfig.json detection and TypeScript-specific entry points.
+ */
+export class TypeScriptPlugin extends BasePlugin {
+    get name() {
+        return 'typescript';
+    }
+
+    getConfigFiles() {
+        return ['tsconfig.json', 'tsconfig.base.json', 'tsconfig.eslint.json'];
+    }
+
+    getRoutePatterns() {
+        // Common TypeScript entry points and declaration files
+        return [
+            /src\/index\.ts$/,
+            /src\/main\.ts$/,
+            /src\/lib\.ts$/,
+            /.*\.d\.ts$/
+        ];
+    }
+
+    getRequiredSystemContracts() {
+        // TypeScript specific implicit exports or requirements
+        return ['default'];
+    }
+
+    /**
+     * Custom Getter for v3.2.0: Get the compiler version from the project.
+     */
+    async getCompilerVersion() {
+        try {
+            const packageJsonPath = path.join(this.context.cwd, 'package.json');
+            const content = await fs.readFile(packageJsonPath, 'utf8');
+            const pkg = JSON.parse(content);
+            return pkg.devDependencies?.typescript || pkg.dependencies?.typescript || 'unknown';
+        } catch {
+            return 'not installed';
+        }
+    }
+
+    async isActive(baseDir) {
+        for (const file of this.getConfigFiles()) {
+            try {
+                await fs.access(path.join(baseDir, file));
+                return true;
+            } catch {}
+        }
+        return false;
+    }
+}