prodex 1.1.0 → 1.3.0

package/README.md

@@ -1,140 +1,234 @@
-# 🧩 Prodex — Unified Project Indexer & Dependency Extractor
-
-> **Prodex** *(short for “Project Index”)* — a cross-language dependency combiner for modern full-stack applications.  
-> Traverses **Laravel + React + TypeScript** projects to generate a single, organized view of your project’s true dependency scope.
-
----
-
-## 🧠 Recent Fixes & Updates — v1.0.8
-- ⭐ **Priority Files Support**  — priority files will now appear **first** on the entry selection list.
-
-- 🪟 **Windows path resolution fixed** — now uses proper `file://` URLs for full ESM compatibility.  
-- 🧾 **Improved output naming** — automatic, context-aware filenames (e.g. `prodex-[entries]-combined.txt`).  
-- ⚙️ **“Yes to all” confirmation added** — skip repetitive prompts during CLI runs.
-
----
-
----
-
-## 📦 Installation
-
-### Global install (recommended)
-```bash
-npm install -g prodex
-```
-
-
-## 🚀 Features
-
-| Feature | Description |
-|----------|-------------|
-| ⚙️ **Cross-language resolver** | Parses JS/TS (`import`, `export`) and PHP (`use`, `require`, `include`) dependency trees. |
-| 🧭 **Alias detection** | Reads `tsconfig.json` and `vite.config.*` for alias paths (`@/components/...`). |
-| 🧩 **Laravel-aware** | Maps PSR-4 namespaces and detects providers under `app/Providers`. |
-| 🔄 **Recursive chain following** | Resolves dependency graphs up to a configurable depth and file limit. |
-| 🪶 **Clean unified output** | Merges all resolved files into a single `.txt` file with region markers for readability. |
-| 🧠 **Static & safe** | Fully static parsing — no runtime execution or file modification. |
-| 💬 **Interactive CLI** | Select files, confirm settings, or use “Yes to all” for streamlined automation. |
-
----
-
-## ⚙️ Configuration
-
-Optional `.prodex.json` (in project root):
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/emxhive/prodex/main/schema/prodex.schema.json",
-  "output": "prodex",
-  "scanDepth": 2,
-  "limit": 200,
-  "baseDirs": ["app", "routes", "resources/js"],
-  "aliasOverrides": {
-    "@hooks": "resources/js/hooks",
-    "@data": "resources/js/data"
-  },
-  "entryExcludes": [
-    "resources/js/components/ui/",
-    "app/DTOs/"
-  ],
-  "importExcludes": [
-    "node_modules",
-    "@shadcn/"
-  ], 
-  "priorityFiles": [
-  "routes/web.php",
-  "routes/api.php",
-  "index.",
-  "main.",
-  "app."
-]
-}
-```
-
-```
-
-
-
-```
-
-
-
-Files are matched using `.includes()` (case-insensitive), so `"index."` will match `src/index.js`, `app/index.tsx`, etc.  
-Popular entries appear at the top of the picker.
-
-
-
-
-
----
-
-## 🧱 Example: Laravel + React
-
-```bash
-prodex
-```
-
-```
-🧩 Following dependency chain...
-✅ prodex-app-routes-combined.txt written (24 file(s)).
-```
-
-Included files:
-```
-resources/js/pages/accounts.tsx
-app/Http/Controllers/Shots/AccountsController.php
-app/Repositories/Shots/FireflyApiRepository.php
-app/Enums/Shots/Granularity.php
-app/Support/Shots/CacheKeys.php
-...
-```
-
----
-
-## 🧠 Ideal Use Cases
-
-- 📦 Generate single-file **project snapshots**  
-- 🤖 Provide structured context for **AI assistants**  
-- 🧩 Perform **dependency audits** or code reviews  
-- 📄 Simplify documentation and onboarding  
-
----
-
-## 🔮 Upcoming Features
-
-- 📝 **Markdown export** (`.md`) with automatic code fences  
-- 📦 **Configurable output formats** (txt / md)  
-- ⚡ **Alias auto-discovery for Laravel Mix and Next.js**  
-
----
-
-## 🧾 License
-
-**MIT © 2025 [emxhive](https://github.com/emxhive)**  
-Issues and contributions welcome:  
-👉 [github.com/emxhive/prodex/issues](https://github.com/emxhive/prodex/issues)
-
----
-
-**Prodex** — *Codebase, decoded*
-
+# 🧩 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/bin/prodex.js

@@ -1,18 +1,2 @@
 #!/usr/bin/env node
-import fs from "fs";
-import path from "path";
-import { pathToFileURL, fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const devPath = path.resolve(__dirname, "../src/index.js");
-const distPath = path.resolve(__dirname, "../dist/src/index.js");
-
-// prefer dist in published package
-const entry = fs.existsSync(distPath) ? distPath : devPath;
-
-// convert to file:// URL for cross-platform ESM loading
-const entryUrl = pathToFileURL(entry).href;
-
-import(entryUrl).then(({ default: startProdex }) => startProdex());
+require("../dist/index.js").default();

package/dist/cli/cli-input.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliInput = parseCliInput;
+const sade_1 = __importDefault(require("sade"));
+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 }.
+ */
+function parseCliInput(argv = process.argv) {
+    if (argv.includes("-v") || argv.includes("--version")) {
+        logger_1.logger.log(`prodex v${package_json_1.default.version}`);
+        process.exit(0);
+    }
+    const program = (0, sade_1.default)("prodex [root]");
+    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 },
+        };
+    });
+    program.parse(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 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;
+        switch (meta.type) {
+            case "number": {
+                const num = Number(raw);
+                if (Number.isNaN(num))
+                    errors.push(`Flag --${key} expected a number but got "${raw}"`);
+                else
+                    flags[key] = num;
+                break;
+            }
+            case "list": {
+                const arr = String(raw)
+                    .split(",")
+                    .map((v) => v.trim())
+                    .filter(Boolean);
+                flags[key] = arr;
+                break;
+            }
+        }
+    }
+    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);
+    }
+}

package/dist/cli/flags.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_USAGE = exports.FLAG_SHORT_MAP = exports.PRODEX_FLAGS = exports.FlagKey = void 0;
+var FlagKey;
+(function (FlagKey) {
+    FlagKey["Txt"] = "txt";
+    FlagKey["Ci"] = "ci";
+    FlagKey["Debug"] = "debug";
+    FlagKey["Name"] = "name";
+    FlagKey["Limit"] = "limit";
+    FlagKey["Inc"] = "include";
+    FlagKey["Exc"] = "exclude";
+    FlagKey["Help"] = "help";
+    FlagKey["Files"] = "files";
+})(FlagKey || (exports.FlagKey = FlagKey = {}));
+exports.PRODEX_FLAGS = {
+    [FlagKey.Files]: { short: "f", type: "list", description: "Comma-separated entry files." },
+    [FlagKey.Txt]: { short: "t", type: "boolean", description: "Output as .txt instead of .md." },
+    [FlagKey.Ci]: { short: "c", type: "boolean", description: "Headless/no-UI mode." },
+    [FlagKey.Debug]: { short: "d", type: "boolean", description: "Enable debug logs." },
+    [FlagKey.Name]: { short: "n", type: "string", description: "Custom output filename." },
+    [FlagKey.Limit]: { short: "l", type: "number", description: "Override traversal limit." },
+    [FlagKey.Inc]: { type: "list", short: "i", description: "Comma-separated include globs." },
+    [FlagKey.Exc]: { type: "list", short: "x", description: "Comma-separated exclude globs." },
+    [FlagKey.Help]: { short: "h", type: "boolean", description: "Show CLI help and exit." },
+};
+/** Reverse lookup for short aliases. */
+exports.FLAG_SHORT_MAP = Object.entries(exports.PRODEX_FLAGS).reduce((acc, [key, meta]) => {
+    if (meta.short)
+        acc[meta.short] = key;
+    return acc;
+}, {});
+exports.CLI_USAGE = `
+Usage: prodex [-fcdv]
+       [--files=<globs>|-f=<globs>]
+       [--include=<globs>|-i=<globs>]
+       [--exclude=<globs>|-x=<globs>]
+       [--txt|-t] [--ci|-c] [--debug|-d] [--version|-v]
+       [--name=<string>|-n=<string>]
+       [--limit=<int>|-l=<int>]
+       [--help|-h]
+`;

package/dist/cli/init.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initProdex = initProdex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const default_config_1 = require("../constants/default-config");
+const logger_1 = require("../lib/logger");
+async function initProdex() {
+    logger_1.logger.log("🪄 Prodex Init — Configuration Wizard (v2)");
+    const dest = path_1.default.join(process.cwd(), "prodex.json");
+    if (fs_1.default.existsSync(dest)) {
+        logger_1.logger.error("prodex.json already exists. Delete or modify it manually.\n");
+        return;
+    }
+    fs_1.default.writeFileSync(dest, JSON.stringify(default_config_1.DEFAULT_PRODEX_CONFIG, null, 2) + "\n", "utf8");
+    logger_1.logger.log(`✅ Created ${dest}`);
+    logger_1.logger.log("💡 Globs supported everywhere (include, exclude, priority).");
+}

package/dist/cli/picker.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickEntries = pickEntries;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const helpers_1 = require("../core/helpers");
+const file_utils_1 = require("../core/file-utils");
+const utils_1 = require("../lib/utils");
+const logger_1 = require("../lib/logger");
+const prompt_1 = require("../lib/prompt");
+const questions_1 = require("../lib/questions");
+/**
+ * Interactive entry picker for Prodex.
+ * Handles depth-based scanning, caching, and priority ordering.
+ */
+async function pickEntries(cfg) {
+    const { root, entry: { files, ui: { roots = [], priority = [], scanDepth }, }, } = cfg;
+    let depth = scanDepth;
+    const entryPatterns = files || [];
+    const priorities = [...entryPatterns, ...priority];
+    // 1️⃣ Resolve pre-defined entry patterns
+    const resolvedEntries = (await (0, file_utils_1.globScan)(entryPatterns, { cwd: root })).files;
+    let selected = [...resolvedEntries];
+    // cache: depth → files[]
+    const scanCache = new Map();
+    for (;;) {
+        const files = await getFilesAtDepth(depth, cfg, scanCache);
+        // Merge resolved entries with current scan results
+        const combined = (0, utils_1.unique)([...resolvedEntries, ...files]);
+        const sorted = (0, helpers_1.orderByPriority)(combined, priorities);
+        // Build UI selection list
+        const choices = sorted.map((f) => ({
+            name: (0, helpers_1.rel)(f, root),
+            value: f,
+            checked: selected.includes(f),
+        }));
+        if (depth < scanDepth + 5) {
+            choices.push(new inquirer_1.default.Separator());
+            choices.push({ name: "🔽 Load more (go deeper)", value: "__loadmore" });
+        }
+        // 🧠 Use unified prompt wrapper
+        const answers = await (0, prompt_1.prompt)((0, questions_1.PICK_ENTRIES_QUESTION)(choices, depth), { picks: [] });
+        if (!answers)
+            return (0, utils_1.unique)(selected);
+        const { picks } = answers;
+        if (picks.includes("__loadmore")) {
+            depth++;
+            selected = picks.filter((p) => p !== "__loadmore");
+            continue;
+        }
+        selected = picks.filter((p) => p !== "__loadmore");
+        break;
+    }
+    return (0, utils_1.unique)(selected);
+}
+/**
+ * Depth-based directory scanner with caching.
+ */
+async function getFilesAtDepth(depth, cfg, scanCache) {
+    const baseDirs = cfg.entry.ui.roots || [];
+    if (scanCache.has(depth)) {
+        logger_1.logger.debug(`[picker] cache hit → depth=${depth}`);
+        return scanCache.get(depth);
+    }
+    logger_1.logger.debug(`[picker] scanning → depth=${depth}`);
+    const files = [];
+    const effectiveCfg = { ...cfg, scanDepth: depth };
+    for (const base of baseDirs) {
+        const full = path_1.default.join(cfg.root, base);
+        if (!fs_1.default.existsSync(full))
+            continue;
+        for (const f of (0, helpers_1.walk)(full, effectiveCfg, 0))
+            files.push(f.norm());
+    }
+    scanCache.set(depth, files);
+    logger_1.logger.debug(`[picker] depth=${depth} found=${files.length}`);
+    return files;
+}