prodex 1.2.0 → 1.3.0

package/README.md

@@ -1,228 +1,234 @@
-
-# 🧩 Prodex v1.2.0
-
-> **Because every project deserves a clear map, not a maze.**
-
----
-
-## 🧠 What’s New — v1.2.0
-
-- 🆕 **Full CLI support with integrated [Sade](https://github.com/lukeed/sade).**  
-  Prodex now runs entirely from the terminal — no `prodex.json` required.  
-  Supports short flags and native glob patterns for flexible targeting.  
-  ```bash
-  prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**"
-  prodex --files **/web.php **/app.tsx --include **/*.interface.ts --exclude @shadcn/**
-  ```
-
-- 🧾 **Markdown mode added and now default.**  
-  Output is fully fenced and linkable — jump between the index and any code block.  
-  Text mode remains available using `--txt` or `-t`.  
-
-- 🗂 **Output naming improved.**  
-  Output files are now versioned by default.  
-  Custom names are supported using `--name` or `-n`.  
-  Naming conventions have been updated for cleaner, consistent results.  
-
----
-
-## ⚙️ Usage
-
-Prodex v1.2.0 runs entirely from the command line.  
-Interactive mode is currently unstable — use CLI flags instead.
-
-### Installation
-
-```bash
-npm install -g prodex
-```
-
-Or run without installing:
-
-```bash
-npx prodex
-```
-
----
-
-### Basic Run
-
-```bash
-prodex -f "**/web.php,**/app.tsx"
-```
-
-### With Includes, exclude, and Custom Name
-
-```bash
-prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**" -n "combined-output"
-```
-
-### Flag Reference
-
-| Flag | Short | Description |
-|------|--------|-------------|
-| `--files` | `-f` | Entry files — starting points for dependency resolution. Accepts multiple names or globs. |
-| `--include` | `-i` | Adds extra files or patterns to include (e.g. `.d.ts`, interface, or type files). These files are **not dependency-resolved** — they’re appended as-is. |
-| `--exclude` | `-x` | Patterns or folders to skip during the scan. |
-| `--name` | `-n` | Custom output filename (without extension). Versioning still applies automatically. |
-
-> Globs are powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob).  
-> Use **comma-separated values** for multiple entries.  
-> Wrap globs in quotes when they include special characters like `|` or `&`.  
-
----
-
-## 🧭 Plans
-
-- **Alias Resolution Improvements**  
-  Planned overhaul of alias handling to support deeper nested paths, wildcard matching, and auto-mapped imports across mixed stacks.
-
-- **Language Support**  
-  Currently supports **JavaScript**, **React**, and **Laravel + React** stacks.  
-  May work with other frameworks but remains untested.  
-  Broader multi-language support is planned for future versions.
-
-- **Combined Output**  
-  All code from multiple entries is merged into a single output file.  
-  There’s currently **no limit** on output size, but it’s advised to avoid combining *too many large entries* in a single run.  
-  Future versions will include **smart naming** and **automatic splitting** for oversized outputs.
-
-- **Performance Optimizations**  
-  Planned improvements to resolver speed and dependency traversal for faster processing on large projects.  
-
----
-
-## 🧩 Features
-
-| Status | Feature | Description |
-|:--:|----------|--------------|
-| ✅ | **Cross-language indexing** | Resolves imports across JS, TS, React, and PHP (Laravel) projects. |
-| ✅ | **Markdown output** | Generates clean `.md` files with anchors, back-to-top links, and fenced code blocks. |
-| ✅ | **Text output** | Optional `.txt` mode using `--txt` or `-t`. |
-| ✅ | **Glob support** | Works with flexible glob patterns powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob). |
-| ✅ | **Custom output names** | Define your own output prefix using `--name` or `-n`. |
-| ⚠️ | **Interactive picker (UI)** | Still unstable — not recommended for production use. |
-| ⚠️ | **Alias resolution** | Basic alias mapping supported; advanced cases in progress. |
-| 🚧 | **Smart file splitting** | Planned for large combined outputs. |
-| 🚧 | **PSR-4 deep scan** | Planned to improve PHP dependency resolution. |
-| 🚧 | **Speed optimization** | Further resolver and I/O improvements under development. |
-
----
-
-## 🧱 Use Cases
-
-Prodex can technically combine your entire codebase into one file —  
-but it’s **best used in parts**, focusing on specific sections or features.  
-Each run produces a clean, self-contained map showing all related files and dependencies.
-
-### 🧩 Common Scenarios
-
-- **🤖 Project Awareness for AI Assistants**  
-  Generate compact `.md` summaries of key parts of your project.  
-  These can be shared with AI tools (like ChatGPT, Claude, or Copilot) to give them structured context about your codebase — without exposing unnecessary files.
-
-- **📦 Feature or Module Mapping**  
-  Combine everything connected to a specific feature (e.g., `Checkout`, `Dashboard`, or `Payments`).  
-  Prodex gathers all linked imports, helpers, and files into one readable document.
-
-- **🔍 Dependency Insight**  
-  Trace how a particular entry file connects through your stack — whether it’s `app.tsx` on the frontend or `routes/web.php` on the backend.  
-  Great for debugging, refactoring, or understanding cross-stack dependencies.
-
-- **📖 Documentation Bundles**  
-  Create readable Markdown maps per module or domain instead of one large export.  
-  Each output acts as a focused, navigable view of your code relationships.
-
-- **🧠 Team Handoffs**  
-  Share isolated code scopes (like `Auth`, `Payments`, or `User Management`) with full dependency context.  
-  Makes onboarding and code reviews significantly faster.
-
----
-
-## 🧩 Recommended Workflow
-
-Prodex works best when used to **map and export projects in logical parts** rather than all at once.  
-Each run focuses on one or more entry points, and Prodex automatically **loads all imports recursively** for those files —  
-then appends any files matched by the `--include` flag.
-
-### 🧠 Suggested Pattern
-
-1. **Pick a meaningful entry file**  
-   Example:  
-   - Frontend: `resources/js/**/dashboard.tsx`  
-   - Backend: `routes/**/(web|api).php`  
-   - Shared logic: `app/Services/**/PaymentService.php`
-
-2. **Run Prodex with includes for type or interface files**  
-   ```bash
-   prodex -f "**/dashboard.tsx" -i "**/*.d.ts,**/*.interface.ts"
-   ```
-
-3. **Export separate maps for each major area**  
-   ```bash
-   prodex -f "**/dashboard.tsx" -n "dashboard-map"
-   prodex -f "**/web|api.php" -n "backend-map"
-   ```
-
-4. **Use them together**  
-   Store each output in `/prodex/` or `/docs/maps/`.  
-   These maps can be shared with teammates or loaded into AI tools for structured, code-aware assistance.
-
-> ⚡ Each run recursively resolves every import, applies includes, and outputs one complete dependency map for that section.
-
----
-
-## ⚙️ Optional — `prodex.json`
-
-`prodex.json` is **fully optional** in v1.2.0.  
-You can run Prodex entirely from the command line, but the config file can be useful for saved defaults.
-
-### 🪄 Quick Setup
-
-You can generate a ready-to-use config file with:
-
-```bash
-prodex init
-```
-
-This creates a `prodex.json` file in your project root with sensible defaults — including base directories, globs, and priority files.
-
-### 🧩 Running with a Config File
-
-If you’ve defined your entry files in the config under `entry.files`,  
-you can run Prodex directly without specifying `--files`:
-
-```bash
-prodex -c
-```
-
-The `-c` (or `--ci`) flag skips interactive mode and uses the config values automatically.  
-Specifying `-f` ( or `--files`) from the CLI also disables the picker by default.  
-
-You can permanently disable the picker in the config by setting:
-
-```json
-"entry": {
-  "ui": {
-    "enablePicker": false
-  }
-}
-```
-
----
-
-## 📜 License
-
-**MIT License**  
-© 2025 [emxhive](https://github.com/emxhive)
-
----
-
-## ⚠️ Note from the Author
-
-Prodex is still a **work in progress**.  
-Some parts of the experience may be rough, especially around interactive mode and advanced resolvers.  
-Updates are released **multiple times per week — sometimes daily** — to keep improving stability and support.  
-
-Please stay up to date for the best experience.  
-Thank you for testing Prodex early. ❤️  
+# 🧩 Prodex v1.2.0
+
+> **Build the maze, I'll write a map.**
+
+---
+
+## 🧠 What’s New — v1.2.0
+
+- 🆕 **Full CLI support with integrated [Sade](https://github.com/lukeed/sade).**  
+  Prodex now runs entirely from the terminal — no `prodex.json` required.  
+  Supports short flags and native glob patterns for flexible targeting.
+
+     ```bash
+     prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**"
+     ```
+
+     ```bash
+     prodex --files "**/web.php,**/app.tsx" --include **/*types.ts --exclude "@shadcn/**"
+     ```
+
+- 🧾 **Markdown mode added and now default.**  
+  Output is fully fenced and linkable — jump between the index and any code block.  
+  Text mode remains available using `--txt` or `-t`.
+
+- 🗂 **Output naming improved.**  
+  Output files are now versioned by default.  
+  Custom names are supported using `--name` or `-n`.  
+  Naming conventions have been updated for cleaner, consistent results.
+
+---
+
+## ⚙️ Usage
+
+Prodex v1.2.0 runs entirely from the command line.  
+Interactive mode is currently unstable — use CLI flags instead.
+
+### Installation
+
+```bash
+npm install -g prodex
+```
+
+Or run without installing:
+
+```bash
+npx prodex
+```
+
+---
+
+### Basic Run
+
+```bash
+prodex -f "**/web.php,**/app.tsx"
+```
+
+### With Includes, exclude, and Custom Name
+
+```bash
+prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**" -n "combined-output"
+```
+
+### Flag Reference
+
+| Flag        | Short | Description                                                                                                                                             |
+| ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--files`   | `-f`  | Entry files — starting points for dependency resolution. Accepts multiple names or globs.                                                               |
+| `--include` | `-i`  | Adds extra files or patterns to include (e.g. `.d.ts`, interface, or type files). These files are **not dependency-resolved** — they’re appended as-is. |
+| `--exclude` | `-x`  | Patterns or folders to skip during the scan.                                                                                                            |
+| `--name`    | `-n`  | Custom output filename (without extension). Versioning still applies automatically.                                                                     |
+
+> Globs are powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob).  
+> Use **comma-separated values** for multiple entries.  
+> Wrap globs in quotes when they include special characters like `|` or `&`.
+
+---
+
+## 🧭 Plans
+
+- **Alias Resolution Improvements**  
+  Planned overhaul of alias handling to support deeper nested paths, wildcard matching, and auto-mapped imports across mixed stacks.
+
+- **Language Support**  
+  Currently supports **JavaScript**, **React**, and **Laravel + React** stacks.  
+  May work with other frameworks but remains untested.  
+  Broader multi-language support is planned for future versions.
+
+- **Combined Output**  
+  All code from multiple entries is merged into a single output file.  
+  There’s currently **no limit** on output size, but it’s advised to avoid combining _too many large entries_ in a single run.  
+  Future versions will include **smart naming** and **automatic splitting** for oversized outputs.
+
+- **Performance Optimizations**  
+  Planned improvements to resolver speed and dependency traversal for faster processing on large projects.
+
+---
+
+## 🧩 Features
+
+| Status | Feature                     | Description                                                                                    |
+| :----: | --------------------------- | ---------------------------------------------------------------------------------------------- |
+|   ✅   | **Cross-language indexing** | Resolves imports across JS, TS, React, and PHP (Laravel) projects.                             |
+|   ✅   | **Markdown output**         | Generates clean `.md` files with anchors, back-to-top links, and fenced code blocks.           |
+|   ✅   | **Text output**             | Optional `.txt` mode using `--txt` or `-t`.                                                    |
+|   ✅   | **Glob support**            | Works with flexible glob patterns powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob). |
+|   ✅   | **Custom output names**     | Define your own output prefix using `--name` or `-n`.                                          |
+|   ⚠️   | **Interactive picker (UI)** | Still unstable — not recommended for production use.                                           |
+|   ⚠️   | **Alias resolution**        | Basic alias mapping supported; advanced cases in progress.                                     |
+|   🚧   | **Smart file splitting**    | Planned for large combined outputs.                                                            |
+|   🚧   | **PSR-4 deep scan**         | Planned to improve PHP dependency resolution.                                                  |
+|   🚧   | **Speed optimization**      | Further resolver and I/O improvements under development.                                       |
+
+---
+
+## 🧱 Use Cases
+
+Prodex can technically combine your entire codebase into one file —  
+but it’s **best used in parts**, focusing on specific sections or features.  
+Each run produces a clean, self-contained map showing all related files and dependencies.
+
+### 🧩 Common Scenarios
+
+- **🤖 Project Awareness for AI Assistants**  
+  Generate compact `.md` summaries of key parts of your project.  
+  These can be shared with AI tools (like ChatGPT, Claude, or Copilot) to give them structured context about your codebase — without exposing unnecessary files.
+
+- **📦 Feature or Module Mapping**  
+  Combine everything connected to a specific feature (e.g., `Checkout`, `Dashboard`, or `Payments`).  
+  Prodex gathers all linked imports, helpers, and files into one readable document.
+
+- **🔍 Dependency Insight**  
+  Trace how a particular entry file connects through your stack — whether it’s `app.tsx` on the frontend or `routes/web.php` on the backend.  
+  Great for debugging, refactoring, or understanding cross-stack dependencies.
+
+- **📖 Documentation Bundles**  
+  Create readable Markdown maps per module or domain instead of one large export.  
+  Each output acts as a focused, navigable view of your code relationships.
+
+- **🧠 Team Handoffs**  
+  Share isolated code scopes (like `Auth`, `Payments`, or `User Management`) with full dependency context.  
+  Makes onboarding and code reviews significantly faster.
+
+---
+
+## 🧩 Recommended Workflow
+
+Prodex works best when used to **map and export projects in logical parts** rather than all at once.  
+Each run focuses on one or more entry points, and Prodex automatically **loads all imports recursively** for those files —  
+then appends any files matched by the `--include` flag.
+
+### 🧠 Suggested Pattern
+
+1. **Pick a meaningful entry file**  
+   Example:
+
+      - Frontend: `resources/js/**/dashboard.tsx`
+      - Backend: `routes/**/(web|api).php`
+      - Shared logic: `app/Services/**/PaymentService.php`
+
+2. **Run Prodex with includes for type or interface files**
+
+      ```bash
+      prodex -f "**/dashboard.tsx" -i "**/*.d.ts,**/*.interface.ts"
+      ```
+
+3. **Export separate maps for each major area**
+
+      ```bash
+      prodex -f "**/dashboard.tsx" -n "dashboard-map"
+      prodex -f "**/(web|api).php" -n "backend-map"
+      ```
+
+4. **Use them together**  
+   Store each output in `/prodex/`
+   These maps can be shared with teammates or loaded into AI tools for structured, code-aware assistance.
+
+> ⚡ Each run recursively resolves every import, applies includes, and outputs one complete dependency map for that section.
+
+---
+
+## ⚙️ Optional — `prodex.json`
+
+`prodex.json` is **fully optional** in v1.2.0.  
+You can run Prodex entirely from the command line, but the config file can be useful for saved defaults.
+
+### 🪄 Quick Setup
+
+You can generate a ready-to-use config file with:
+
+```bash
+prodex init
+```
+
+This creates a `prodex.json` file in your project root with sensible defaults — including base directories, globs, and priority files.
+
+### 🧩 Running with a Config File
+
+If you’ve defined your entry files in the config under `entry.files`,  
+you can run Prodex directly without specifying `--files`:
+
+```bash
+prodex -c
+```
+
+The `-c` (or `--ci`) flag skips interactive mode and uses the config values automatically.  
+Specifying `-f` ( or `--files`) from the CLI also disables the picker by default.
+
+You can permanently disable the picker in the config by setting:
+
+```json
+"entry": {
+  "ui": {
+    "enablePicker": false
+  }
+}
+```
+
+---
+
+## 📜 License
+
+**MIT License**  
+© 2025 [emxhive](https://github.com/emxhive)
+
+---
+
+## ⚠️ Note from the Author
+
+Prodex is still a **work in progress**.  
+Some parts of the experience may be rough, especially around interactive mode and advanced resolvers.  
+Updates are released **multiple times per week — sometimes daily** — to keep improving stability and support.
+
+Please stay up to date for the best experience.  
+Thank you for testing Prodex early. ❤️

package/dist/cli/cli-input.js

@@ -9,6 +9,7 @@ const flags_1 = require("./flags");
 const logger_1 = require("../lib/logger");
 const path_1 = __importDefault(require("path"));
 const package_json_1 = __importDefault(require("../../package.json"));
+const fs_1 = __importDefault(require("fs"));
 /**
  * Unified CLI parser powered by Sade.
  * Returns { root, entries (from --files), flags, warnings, errors }.
@@ -19,31 +20,13 @@ function parseCliInput(argv = process.argv) {
         process.exit(0);
     }
     const program = (0, sade_1.default)("prodex [root]");
-    // Register flags dynamically
-    for (const [key, meta] of Object.entries(flags_1.PRODEX_FLAGS)) {
-        const short = meta.short ? `-${meta.short}, ` : "";
-        const long = `--${key}`;
-        const desc = meta.description;
-        let defaultVal;
-        switch (meta.type) {
-            case "boolean":
-                defaultVal = false;
-                break;
-            default:
-                defaultVal = undefined; // defer strings/numbers/lists
-        }
-        if (defaultVal !== undefined) {
-            program.option(`${short}${long}`, desc, defaultVal);
-        }
-        else {
-            program.option(`${short}${long}`, desc);
-        }
-    }
-    let parsed = { root: undefined, flags: {} };
-    // Define default command (root optional)
+    registerFlags(program);
+    let parsed = { rootArg: "", root: undefined, flags: {} };
+    // Define action
     program.action((root, opts) => {
         const cwd = process.cwd();
         parsed = {
+            rootArg: root,
             root: root ? path_1.default.resolve(cwd, root) : cwd,
             flags: { ...opts },
         };
@@ -52,20 +35,40 @@ function parseCliInput(argv = process.argv) {
     const warnings = [];
     const errors = [];
     // Post-parse casting + normalization
+    parsed.flags = normalizeFlags(parsed.flags, warnings, errors);
+    validateArgs(parsed, warnings, errors);
+    return {
+        ...parsed,
+        warnings,
+        errors,
+    };
+}
+function registerFlags(program) {
     for (const [key, meta] of Object.entries(flags_1.PRODEX_FLAGS)) {
-        const raw = parsed.flags[key];
+        const short = meta.short ? `-${meta.short}, ` : "";
+        const long = `--${key}`;
+        const desc = meta.description;
+        let defaultVal;
+        if (meta.type === "boolean")
+            defaultVal = false;
+        if (defaultVal !== undefined)
+            program.option(`${short}${long}`, desc, defaultVal);
+        else
+            program.option(`${short}${long}`, desc);
+    }
+}
+function normalizeFlags(flags, warnings, errors) {
+    for (const [key, meta] of Object.entries(flags_1.PRODEX_FLAGS)) {
+        const raw = flags[key];
         if (raw === undefined)
             continue;
-        const obj = {};
         switch (meta.type) {
             case "number": {
                 const num = Number(raw);
-                if (Number.isNaN(num)) {
+                if (Number.isNaN(num))
                     errors.push(`Flag --${key} expected a number but got "${raw}"`);
-                }
-                else {
-                    parsed.flags[key] = num;
-                }
+                else
+                    flags[key] = num;
                 break;
             }
             case "list": {
@@ -73,14 +76,31 @@ function parseCliInput(argv = process.argv) {
                     .split(",")
                     .map((v) => v.trim())
                     .filter(Boolean);
-                parsed.flags[key] = arr;
+                flags[key] = arr;
                 break;
             }
         }
     }
-    return {
-        ...parsed,
-        warnings,
-        errors,
-    };
+    return flags;
+}
+function validateArgs(parsed, warnings, errors) {
+    const { rootArg, flags: { _: unknown }, } = parsed;
+    if (rootArg) {
+        if (!fs_1.default.existsSync(parsed.root)) {
+            errors.push(`Invalid path argument: "${rootArg}" does not exist.`);
+        }
+        else if (!fs_1.default.statSync(parsed.root).isDirectory()) {
+            errors.push(`Path argument "${rootArg}" is not a directory.`);
+        }
+    }
+    if (unknown.length) {
+        warnings.push(`Unrecognized arguments detected [${unknown.join(", ")}]- They were ignored.`);
+    }
+    if (warnings.length)
+        logger_1.logger.warn("Warnings:", warnings);
+    if (errors.length) {
+        for (const err of errors)
+            logger_1.logger.error(err);
+        process.exit(1);
+    }
 }