pkg-scaffold 3.1.0 → 3.1.2

package/README.md

@@ -1,4 +1,4 @@
-# 📦 pkg-scaffold v3.1.0
+# 📦 pkg-scaffold v3.1.2
 
 **The Ultimate Enterprise Codebase Janitor: OXC-Powered, Type-Aware, and Self-Healing.**
 
@@ -10,7 +10,7 @@
 
 ---
 
-## 🚀 Why pkg-scaffold v3.1.0?
+## 🚀 Why pkg-scaffold@3.1.2?
 
 ### 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.
@@ -82,7 +82,7 @@ Add this to your `package.json` scripts:
 
 - **`/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](./docs/guide.md#plugin-development).
+- **`/docs/`**: Full [Plugin Development Guide](https://dreamlongyt.github.io/pkg-scaffold/).
 
 ---
 
@@ -97,6 +97,28 @@ Protect specific code from the janitor:
 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
+```
 ---
 
 ## 📜 License

package/index.js

@@ -2,7 +2,7 @@
 
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.1.0: Ultimate Enterprise Codebase Janitor & Self-Healing Engine
+ * 📦 pkg-scaffold v3.1.2: 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.0",
+  "version": "3.1.2",
   "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",
@@ -42,7 +42,7 @@
   "bugs": {
     "url": "https://github.com/DreamLongYT/pkg-scaffold/issues"
   },
-  "homepage": "https://github.com/DreamLongYT/pkg-scaffold#readme",
+  "homepage": "https://dreamlongyt.github.io/pkg-scaffold/",
   "dependencies": {
     "ansis": "^3.0.0",
     "commander": "^12.0.0",

package/src/index.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================================
- * 📦 pkg-scaffold v3.0.0: Unified Architectural Refactoring Orchestrator
+ * 📦 pkg-scaffold v3.1.1: Unified Architectural Refactoring Orchestrator
  * ============================================================================
  * Main execution bridge managing multi-pass compilation cycles, semantic cross-linking,
  * supply-chain validation audits, and automated git self-healing rollbacks.

package/.github/workflows/deploy.yml

@@ -1,55 +0,0 @@
-name: Deploy VitePress site to Pages
-
-on:
-  push:
-    branches: [main] 
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build with VitePress
-        run: npm run docs:build
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/.vitepress/dist
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    needs: build
-    runs-on: ubuntu-latest
-    name: Deploy
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

package/.github/workflows/npm-publish.yml

@@ -1,20 +0,0 @@
-name: Publish to npm
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 'latest'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm install
-      - run: npm ci
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/docs/.vitepress/config.mts

@@ -1,40 +0,0 @@
-import { defineConfig } from 'vitepress'
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-  title: "pkg-scaffold Docs",
-  base: '/pkg-scaffold/',
-  description: "An advanced, AST-driven dependency resolution, refactoring, and self-healing engine.",
-  themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide' },
-      { text: 'Reference', link: '/reference' }
-    ],
-
-    sidebar: [
-      {
-        text: 'Guide',
-        items: [
-          { text: 'Getting Started', link: '/guide' }
-        ]
-      },
-      {
-        text: 'CLI',
-        items: [
-          { text: 'Reference', link: '/reference' }
-        ]
-      }
-    ],
-
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/DreamLongYT/pkg-scaffold' }
-    ],
-
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2026 DreamLongYT'
-    }
-  }
-})

package/docs/.vitepress/theme/index.ts

@@ -1,17 +0,0 @@
-// https://vitepress.dev/guide/custom-theme
-import { h } from 'vue'
-import type { Theme } from 'vitepress'
-import DefaultTheme from 'vitepress/theme'
-import './style.css'
-
-export default {
-  extends: DefaultTheme,
-  Layout: () => {
-    return h(DefaultTheme.Layout, null, {
-      // https://vitepress.dev/guide/extending-default-theme#layout-slots
-    })
-  },
-  enhanceApp({ app, router, siteData }) {
-    // ...
-  }
-} satisfies Theme

package/docs/.vitepress/theme/style.css

@@ -1,139 +0,0 @@
-/**
- * Customize default theme styling by overriding CSS variables:
- * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
- */
-
-/**
- * Colors
- *
- * Each colors have exact same color scale system with 3 levels of solid
- * colors with different brightness, and 1 soft color.
- *
- * - `XXX-1`: The most solid color used mainly for colored text. It must
- *   satisfy the contrast ratio against when used on top of `XXX-soft`.
- *
- * - `XXX-2`: The color used mainly for hover state of the button.
- *
- * - `XXX-3`: The color for solid background, such as bg color of the button.
- *   It must satisfy the contrast ratio with pure white (#ffffff) text on
- *   top of it.
- *
- * - `XXX-soft`: The color used for subtle background such as custom container
- *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
- *   on top of it.
- *
- *   The soft color must be semi transparent alpha channel. This is crucial
- *   because it allows adding multiple "soft" colors on top of each other
- *   to create a accent, such as when having inline code block inside
- *   custom containers.
- *
- * - `default`: The color used purely for subtle indication without any
- *   special meanings attached to it such as bg color for menu hover state.
- *
- * - `brand`: Used for primary brand colors, such as link text, button with
- *   brand theme, etc.
- *
- * - `tip`: Used to indicate useful information. The default theme uses the
- *   brand color for this by default.
- *
- * - `warning`: Used to indicate warning to the users. Used in custom
- *   container, badges, etc.
- *
- * - `danger`: Used to show error, or dangerous message to the users. Used
- *   in custom container, badges, etc.
- * -------------------------------------------------------------------------- */
-
-:root {
-  --vp-c-default-1: var(--vp-c-gray-1);
-  --vp-c-default-2: var(--vp-c-gray-2);
-  --vp-c-default-3: var(--vp-c-gray-3);
-  --vp-c-default-soft: var(--vp-c-gray-soft);
-
-  --vp-c-brand-1: var(--vp-c-indigo-1);
-  --vp-c-brand-2: var(--vp-c-indigo-2);
-  --vp-c-brand-3: var(--vp-c-indigo-3);
-  --vp-c-brand-soft: var(--vp-c-indigo-soft);
-
-  --vp-c-tip-1: var(--vp-c-brand-1);
-  --vp-c-tip-2: var(--vp-c-brand-2);
-  --vp-c-tip-3: var(--vp-c-brand-3);
-  --vp-c-tip-soft: var(--vp-c-brand-soft);
-
-  --vp-c-warning-1: var(--vp-c-yellow-1);
-  --vp-c-warning-2: var(--vp-c-yellow-2);
-  --vp-c-warning-3: var(--vp-c-yellow-3);
-  --vp-c-warning-soft: var(--vp-c-yellow-soft);
-
-  --vp-c-danger-1: var(--vp-c-red-1);
-  --vp-c-danger-2: var(--vp-c-red-2);
-  --vp-c-danger-3: var(--vp-c-red-3);
-  --vp-c-danger-soft: var(--vp-c-red-soft);
-}
-
-/**
- * Component: Button
- * -------------------------------------------------------------------------- */
-
-:root {
-  --vp-button-brand-border: transparent;
-  --vp-button-brand-text: var(--vp-c-white);
-  --vp-button-brand-bg: var(--vp-c-brand-3);
-  --vp-button-brand-hover-border: transparent;
-  --vp-button-brand-hover-text: var(--vp-c-white);
-  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
-  --vp-button-brand-active-border: transparent;
-  --vp-button-brand-active-text: var(--vp-c-white);
-  --vp-button-brand-active-bg: var(--vp-c-brand-1);
-}
-
-/**
- * Component: Home
- * -------------------------------------------------------------------------- */
-
-:root {
-  --vp-home-hero-name-color: transparent;
-  --vp-home-hero-name-background: -webkit-linear-gradient(
-    120deg,
-    #bd34fe 30%,
-    #41d1ff
-  );
-
-  --vp-home-hero-image-background-image: linear-gradient(
-    -45deg,
-    #bd34fe 50%,
-    #47caff 50%
-  );
-  --vp-home-hero-image-filter: blur(44px);
-}
-
-@media (min-width: 640px) {
-  :root {
-    --vp-home-hero-image-filter: blur(56px);
-  }
-}
-
-@media (min-width: 960px) {
-  :root {
-    --vp-home-hero-image-filter: blur(68px);
-  }
-}
-
-/**
- * Component: Custom Block
- * -------------------------------------------------------------------------- */
-
-:root {
-  --vp-custom-block-tip-border: transparent;
-  --vp-custom-block-tip-text: var(--vp-c-text-1);
-  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
-  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
-}
-
-/**
- * Component: Algolia
- * -------------------------------------------------------------------------- */
-
-.DocSearch {
-  --docsearch-primary-color: var(--vp-c-brand-1) !important;
-}
-

package/docs/guide.md

@@ -1,102 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
----
-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

@@ -1,52 +0,0 @@
-# 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`.