prodex 1.4.11 → 2.0.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Zeki
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Zeki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,234 +1,240 @@
-# 🧩 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. ❤️
+# Prodex
+
+Focused code-context extraction for large, multi-file projects.
+
+Prodex starts from real project entrypoints, follows supported dependencies, adds explicitly included files, and exports a clean Markdown trace. It helps you isolate the files that matter for a feature, review, debug session, documentation pass, handoff, or AI-assisted workflow without manually collecting every related file.
+
+Prodex is intentionally narrow: it creates readable, reproducible context bundles. It is not trying to be a full IDE indexer, static analysis platform, architecture rule engine, or graph visualizer.
+
+## Why Prodex
+
+Large projects make context gathering expensive. A feature can start in one route or component, then spread through shared utilities, types, controllers, services, bindings, and framework conventions. Copying those files by hand is slow, inconsistent, and easy to get wrong.
+
+Prodex gives that workflow a repeatable shape:
+
+1. Choose one or more entry files or globs.
+2. Trace the dependencies Prodex can resolve.
+3. Add any extra files you explicitly include.
+4. Exclude noisy paths such as generated output, vendor code, or UI primitives.
+5. Export a Markdown bundle with an index and file sections.
+
+The result is a focused project trace you can read, share, review, archive, or hand to another tool.
+
+## How It Works
+
+```bash
+prodex run --entry src/index.ts
+```
+
+Prodex resolves the requested entrypoints from your project root, follows supported dependency references, applies include and exclude rules, then writes a versioned Markdown file to `./prodex/` by default.
+
+For example:
+
+```bash
+prodex run --entry resources/js/pages/Dashboard.tsx --include "routes/**/*.php"
+```
+
+This traces the dashboard entrypoint and adds the matching route files to the exported context.
+
+## Profiles
+
+Profiles are reusable named context maps stored in `prodex.json`.
+
+They are one of Prodex's most useful workflow features: instead of rebuilding the same trace commands every time, teams can save important project areas as named profiles such as `dashboard`, `auth`, `billing`, `api`, `admin`, or `checkout`.
+
+```bash
+prodex run --profile dashboard
+prodex run --profile auth,billing
+prodex run --all
+prodex profiles
+```
+
+Use profiles when a project has recurring review surfaces or ownership areas. A profile can define its own entries, includes, excludes, and optional output name; when no output name is set, the profile key becomes the trace basename. This makes context extraction repeatable across debugging, reviews, documentation, handoffs, and release work. Run one profile, a comma-separated set of profiles, or all profiles with `--all` when you need a broader pass.
+
+Example:
+
+```json
+{
+    "version": 4,
+    "$schema": "https://raw.githubusercontent.com/emxhive/prodex/main/schema/prodex.schema.json",
+    "output": {
+        "dir": "prodex",
+        "format": "md",
+        "versioned": true
+    },
+    "entry": [],
+    "include": [],
+    "exclude": ["node_modules/**", "vendor/**", "dist/**"],
+    "resolve": {
+        "aliases": {
+            "@": "resources/js"
+        },
+        "maxDepth": 10,
+        "maxFiles": 200
+    },
+    "profiles": {
+        "dashboard": {
+            "entry": ["resources/js/pages/Dashboard.tsx"],
+            "include": ["routes/**/*.php", "resources/js/types/**/*.d.ts"],
+            "exclude": ["resources/js/components/ui/**"]
+        },
+        "api": {
+            "entry": ["routes/api.php"],
+            "include": ["app/Http/Requests/**/*.php"],
+            "exclude": ["vendor/**"]
+        }
+    }
+}
+```
+
+## Markdown Output
+
+Markdown is the primary Prodex output.
+
+Each generated trace includes:
+
+- A file index
+- A total file count marker
+- Links to each exported file section
+- Line ranges for the generated sections
+- Syntax-highlighted code fences where possible
+- The collected source content in one readable bundle
+
+Versioned filenames are enabled by default so repeated runs do not overwrite earlier traces.
+
+## Current Support
+
+Prodex's broader identity is controlled context extraction, not a single-framework tool.
+
+Include-only extraction is language-agnostic: any source or text file matched by `--include` or a profile `include` rule can be added to a trace.
+
+Dependency tracing is resolver-based. Today Prodex traces JavaScript, TypeScript, TSX, declaration files, and PHP entrypoints. Current tracing support includes JS/TS imports, dynamic imports, CommonJS `require`, re-exports, static PHP include/require statements, PHP namespace imports, PSR-4 resolution, and some Laravel binding awareness.
+
+Unsupported or dynamic relationships may need to be added with `--include` or profile `include` rules. That is expected: Prodex favors a focused, readable trace over pretending to understand every runtime edge in a project.
+
+## Installation
+
+```bash
+npm install -g prodex
+```
+
+Or run it ad hoc:
+
+```bash
+npx prodex run --entry src/index.ts
+```
+
+Create a starter config:
+
+```bash
+prodex init
+```
+
+## Common Commands
+
+```bash
+prodex run [root] --entry src/index.ts
+prodex run [root] --entry routes/web.php --include "**/*.d.ts"
+prodex run [root] --profile dashboard
+prodex run [root] --profile dashboard,api
+prodex run [root] --all
+prodex profiles [root]
+prodex migrate [root]
+```
+
+`prodex run` requires the `run` command. Root-only positional command shortcuts are intentionally not supported.
+
+## CLI Reference
+
+| Flag | Short | Type | Description |
+| --- | --- | --- | --- |
+| `--entry` | `-e` | list | Entry file or glob to trace. Repeatable and comma-aware. |
+| `--include` | `-i` | list | Extra file or glob to add without dependency tracing. Repeatable and comma-aware. |
+| `--exclude` | `-x` | list | File or glob to skip during traversal. Repeatable and comma-aware. |
+| `--profile` | `-p` | list | Named profile to run. Comma-aware and repeatable. |
+| `--all` | `-a` | boolean | Run every configured profile. `--all-profiles` remains available as an explicit alias. |
+| `--name` | `-n` | string | Output basename for this run. |
+| `--format` | `-F` | `md`/`txt` | Output format. Markdown is the default. |
+| `--max-depth` |  | number | Maximum dependency traversal depth. |
+| `--max-files` |  | number | Maximum traced file count. |
+
+Global metadata flags:
+
+```bash
+prodex --version
+prodex run --help
+prodex profiles --help
+prodex migrate --help
+```
+
+## Configuration
+
+Prodex reads `prodex.json` from the project root.
+
+```json
+{
+    "version": 4,
+    "$schema": "https://raw.githubusercontent.com/emxhive/prodex/main/schema/prodex.schema.json",
+    "output": {
+        "dir": "prodex",
+        "format": "md",
+        "versioned": true
+    },
+    "entry": ["src/index.ts"],
+    "include": [],
+    "exclude": ["node_modules/**", "vendor/**", "dist/**"],
+    "resolve": {
+        "aliases": {
+            "@": "resources/js"
+        },
+        "maxDepth": 10,
+        "maxFiles": 200
+    },
+    "profiles": {}
+}
+```
+
+Naming precedence:
+
+1. `--name`
+2. `profile.name`
+3. Profile key, when running a named profile
+4. Automatic name from entries
+5. Internal fallback: `combined`
+
+CLI flags override config values for a run. Profile arrays replace base arrays for that profile run.
+
+## Migrating Configs
+
+Prodex requires config version 4. If a project has an older `prodex.json`, `prodex run` and `prodex profiles` fail with migration instructions instead of guessing.
+
+Preview a migration:
+
+```bash
+prodex migrate
+```
+
+Check whether migration is needed:
+
+```bash
+prodex migrate --check
+```
+
+Write the migration:
+
+```bash
+prodex migrate --write
+```
+
+`--write` creates a backup before replacing `prodex.json`.
+
+## Requirements
+
+- Node.js 22+
+- A project with JS, TS, TSX, declaration-file, or PHP entrypoints for dependency tracing
+- Any file type can be added through include-only extraction
+- Optional `prodex.json` for saved defaults and profiles
+
+## License
+
+MIT

package/dist/app/execute-run.d.ts

@@ -0,0 +1,2 @@
+import type { RunPlan, RunResult } from "../types";
+export declare function executeRun(plan: RunPlan): Promise<RunResult>;

package/dist/app/execute-run.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeRun = executeRun;
+const cache_manager_1 = require("../cache/cache-manager");
+const glob_scan_1 = require("../filesystem/glob-scan");
+const trace_run_1 = require("../tracing/trace-run");
+const logger_1 = require("../diagnostics/logger");
+async function executeRun(plan) {
+    cache_manager_1.CacheManager.clear();
+    (0, logger_1.setLoggerOptions)(plan.flags);
+    const warnings = [];
+    const errors = [];
+    const entries = await resolveHeadlessEntries(plan);
+    const includes = plan.config.include ?? [];
+    const mode = getRunMode(entries.length, includes.length);
+    if (!entries.length && !includes.length) {
+        return {
+            ok: false,
+            root: plan.root,
+            mode,
+            entries,
+            includes,
+            files: [],
+            warnings,
+            errors: ["No entry files found and no include patterns were configured."],
+            profile: plan.profile,
+        };
+    }
+    const result = await (0, trace_run_1.runTrace)({
+        cfg: plan.config,
+        opts: {
+            entries,
+            outputName: plan.outputName,
+        },
+    });
+    if (!result.outputPath) {
+        return {
+            ok: false,
+            root: plan.root,
+            mode,
+            entries,
+            includes,
+            files: result.files,
+            stats: result.stats,
+            warnings,
+            errors: ["No files matched the selected entries or include patterns."],
+            profile: plan.profile,
+        };
+    }
+    return {
+        ok: true,
+        root: plan.root,
+        mode,
+        outputPath: result.outputPath,
+        outputName: plan.outputName,
+        entries,
+        includes,
+        files: result.files,
+        stats: result.stats,
+        warnings,
+        errors,
+        profile: plan.profile,
+    };
+}
+async function resolveHeadlessEntries(plan) {
+    return (await (0, glob_scan_1.globScan)(plan.config.entry, { cwd: plan.root })).files;
+}
+function getRunMode(entryCount, includePatternCount) {
+    if (entryCount && includePatternCount)
+        return "mixed";
+    if (entryCount)
+        return "trace";
+    return "include-only";
+}

package/dist/app/project-context.d.ts

@@ -0,0 +1,12 @@
+import type { ProdexConfigFile } from "../types";
+export interface ProjectContext {
+    root: string;
+    config: ProdexConfigFile;
+    configPath: string;
+    configExists: boolean;
+    warnings: string[];
+    errors: string[];
+}
+export declare function loadProjectContext(rootArg?: string, cwd?: string): ProjectContext;
+export declare function resolveRoot(rootArg?: string, cwd?: string): string;
+export declare function validateRoot(root: string, rootArg?: string): string[];