prodex 2.0.0 → 2.1.0

package/dist/runtime/shell-command-runner.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAttachedCommand = executeAttachedCommand;
+const child_process_1 = require("child_process");
+/**
+ * Execute a single command sequentially using child_process.spawn.
+ */
+async function executeAttachedCommand(command, cwd, timeoutSeconds) {
+    const startTime = Date.now();
+    let stdout = "";
+    let stderr = "";
+    let combinedOutput = "";
+    let timedOut = false;
+    let status = "success";
+    let errorMessage;
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(command, {
+            shell: true,
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                PAGER: "cat",
+                GIT_PAGER: "cat",
+                CI: process.env.CI ?? "1",
+            },
+            detached: process.platform !== "win32",
+        });
+        let timer;
+        if (timeoutSeconds > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                status = "timed-out";
+                if (child.pid) {
+                    if (process.platform === "win32") {
+                        (0, child_process_1.spawn)("taskkill", ["/pid", child.pid.toString(), "/t", "/f"], { stdio: "ignore" });
+                    }
+                    else {
+                        try {
+                            process.kill(-child.pid, "SIGTERM");
+                        }
+                        catch { }
+                        setTimeout(() => {
+                            try {
+                                process.kill(-child.pid, "SIGKILL");
+                            }
+                            catch { }
+                        }, 2000);
+                    }
+                }
+            }, timeoutSeconds * 1000);
+        }
+        child.stdout?.on("data", (chunk) => {
+            const str = chunk.toString();
+            stdout += str;
+            combinedOutput += str;
+        });
+        child.stderr?.on("data", (chunk) => {
+            const str = chunk.toString();
+            stderr += str;
+            combinedOutput += str;
+        });
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            status = "error";
+            errorMessage = err.message;
+            resolve({
+                command,
+                cwd,
+                status: "error",
+                exitCode: null,
+                signal: null,
+                durationMs: Date.now() - startTime,
+                timedOut: false,
+                stdout,
+                stderr,
+                combinedOutput,
+                errorMessage: err.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (timer)
+                clearTimeout(timer);
+            const durationMs = Date.now() - startTime;
+            if (status === "timed-out") {
+                resolve({
+                    command,
+                    cwd,
+                    status: "timed-out",
+                    exitCode: code,
+                    signal,
+                    durationMs,
+                    timedOut: true,
+                    stdout,
+                    stderr,
+                    combinedOutput,
+                });
+                return;
+            }
+            if (code !== 0) {
+                status = "failed";
+            }
+            resolve({
+                command,
+                cwd,
+                status,
+                exitCode: code,
+                signal,
+                durationMs,
+                timedOut: false,
+                stdout,
+                stderr,
+                combinedOutput,
+            });
+        });
+    });
+}

package/dist/tracing/collect-trace.d.ts

@@ -0,0 +1,10 @@
+import type { ProdexConfig, TraceOptions, ChainResult } from "../types";
+export interface CollectSourcesParams {
+    cfg: ProdexConfig;
+    opts: TraceOptions;
+}
+/**
+ * Pure source provider that resolves dependency chain and includes.
+ * Does not write output or have logging side-effects.
+ */
+export declare function collectTraceSources({ cfg, opts }: CollectSourcesParams): Promise<ChainResult>;

package/dist/tracing/collect-trace.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectTraceSources = collectTraceSources;
+const follow_chain_1 = require("./follow-chain");
+const file_set_1 = require("../filesystem/file-set");
+/**
+ * Pure source provider that resolves dependency chain and includes.
+ * Does not write output or have logging side-effects.
+ */
+async function collectTraceSources({ cfg, opts }) {
+    const entries = opts.entries ?? [];
+    const result = entries.length ? await (0, follow_chain_1.followChain)(entries, cfg) : undefined;
+    const files = await (0, file_set_1.buildFinalFileSet)({
+        root: cfg.root,
+        sources: result?.files ?? [],
+        include: cfg.include ?? [],
+        exclude: cfg.exclude ?? [],
+    });
+    return {
+        files,
+        stats: result?.stats ?? { expected: new Set(), resolved: new Set() },
+    };
+}

package/dist/tracing/exclude.d.ts

@@ -1,6 +1 @@
-/**
- * Centralized exclusion logic.
- * Accepts namespaces, absolute paths, or relative paths
- * and converts everything to a normalized, root-relative glob target.
- */
 export declare function isExcluded(p: string, patterns?: string[], root?: string): boolean;

package/dist/tracing/exclude.js

@@ -6,22 +6,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isExcluded = isExcluded;
 const micromatch_1 = __importDefault(require("micromatch"));
 const path_1 = __importDefault(require("path"));
-const read_file_1 = require("../filesystem/read-file");
 const path_2 = require("../filesystem/path");
-/**
- * Centralized exclusion logic.
- * Accepts namespaces, absolute paths, or relative paths
- * and converts everything to a normalized, root-relative glob target.
- */
 function isExcluded(p, patterns = [], root = process.cwd()) {
     if (!patterns?.length)
         return false;
     if (!p)
         return false;
-    let norm = (0, path_2.normalizePath)(p);
-    if (!path_1.default.isAbsolute(norm) && /^[A-Z]/.test(norm))
-        return false;
-    if (path_1.default.isAbsolute(norm))
-        norm = (0, path_2.normalizePath)((0, read_file_1.rel)(norm, root));
-    return micromatch_1.default.isMatch(norm, patterns);
+    const normAbsolute = (0, path_2.normalizePath)(path_1.default.resolve(root, p));
+    const normRelative = (0, path_2.normalizePath)(path_1.default.relative(root, normAbsolute));
+    for (const pattern of patterns) {
+        const normPattern = (0, path_2.normalizePath)(pattern);
+        if (path_1.default.isAbsolute(normPattern)) {
+            if (micromatch_1.default.isMatch(normAbsolute, normPattern)) {
+                return true;
+            }
+        }
+        else {
+            if (micromatch_1.default.isMatch(normRelative, normPattern)) {
+                return true;
+            }
+        }
+    }
+    return false;
 }

package/dist/tracing/follow-chain.js

@@ -10,8 +10,8 @@ const exclude_1 = require("./exclude");
 const trace_stats_1 = require("./trace-stats");
 const resolver_registry_1 = require("./resolver-registry");
 async function followChain(entryFiles, cfg) {
-    const limit = cfg.resolve.maxFiles;
-    const resolverDepth = cfg.resolve.maxDepth;
+    const limit = cfg.maxFiles;
+    const resolverDepth = cfg.depth;
     logger_1.logger.debug("Following dependency chain...");
     const visited = new Set();
     const all = [];

package/dist/types/app.types.d.ts

@@ -2,17 +2,44 @@ import type { MigrationCommandResult } from "../config/migration";
 import type { ProdexFlags } from "./cli.types";
 import type { ProdexConfig } from "./config.types";
 import type { ChainResult } from "./tracing.types";
+import type { ArtifactSection, FileSnapshot } from "./artifact.types";
+export type ProdexCommandKind = "pack" | "trace" | "scope" | "git" | "grep";
+export type ProdexRunMode = "trace" | "include-only" | "mixed" | "git" | "grep";
+export interface SourceCollectionResult {
+    files: string[];
+    entries: string[];
+    includes: string[];
+    mode: ProdexRunMode;
+    stats?: ChainResult["stats"];
+    warnings: string[];
+    errors: string[];
+    sections?: ArtifactSection[];
+    snapshots?: FileSnapshot[];
+}
 export type CliCommand = {
-    kind: "run";
+    kind: "pack";
     rootArg?: string;
     flags: Partial<ProdexFlags>;
 } | {
-    kind: "init";
+    kind: "trace";
     rootArg?: string;
-    force?: boolean;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "scope";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "git";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
 } | {
-    kind: "profiles";
+    kind: "grep";
     rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "init";
+    rootArg?: string;
+    force?: boolean;
 } | {
     kind: "migrate";
     rootArg?: string;
@@ -34,26 +61,29 @@ export interface RunPlan {
     config: ProdexConfig;
     flags: Partial<ProdexFlags>;
     outputName?: string;
-    profile?: string;
+    scopeKey?: string;
 }
 export interface RunResult {
     ok: boolean;
     root: string;
-    mode: "trace" | "include-only" | "mixed";
+    mode: ProdexRunMode;
     outputPath?: string;
+    outputSizeBytes?: number;
+    outputName?: string;
     entries: string[];
     includes: string[];
     files: string[];
     stats?: ChainResult["stats"];
     warnings: string[];
     errors: string[];
-    profile?: string;
+    scopeKey?: string;
+    plannedCommands?: string[];
 }
 export interface CommandResult {
     ok: boolean;
     exitCode: number;
     message?: string;
-    profiles?: string[];
+    scopes?: string[];
     migration?: MigrationCommandResult;
     warnings: string[];
     errors: string[];

package/dist/types/artifact.types.d.ts

@@ -0,0 +1,50 @@
+import type { ProdexCommandKind, ProdexRunMode } from "./app.types";
+export interface FileSnapshot {
+    path: string;
+    content: string;
+    readError?: string;
+}
+export interface ArtifactSection {
+    id: string;
+    title: string;
+    kind: "text" | "code";
+    language?: string;
+    content: string;
+}
+export interface CommandOutputResult {
+    command: string;
+    cwd: string;
+    status: "success" | "failed" | "timed-out" | "error";
+    exitCode: number | null;
+    signal: string | null;
+    durationMs: number;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    combinedOutput: string;
+    errorMessage?: string;
+}
+export interface ArtifactMetadata {
+    version: string;
+    timestamp: string;
+    commandKind: ProdexCommandKind;
+    mode: ProdexRunMode;
+    outputName?: string;
+    entries: string[];
+    includes: string[];
+    scopeKey?: string;
+    targets?: string[];
+    depth?: number;
+}
+export interface ArtifactPayload {
+    root: string;
+    sections?: ArtifactSection[];
+    files: FileSnapshot[];
+    commandOutputs?: CommandOutputResult[];
+    metadata: ArtifactMetadata;
+}
+export interface CommandAttachmentOptions {
+    commands: string[];
+    timeoutSeconds: number;
+    failOnError: boolean;
+}

package/dist/types/artifact.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/cli.types.d.ts

@@ -1,6 +1,8 @@
 export interface ProdexFlags {
     /** Entry globs or file paths. Repeatable and comma-aware. */
     entry?: string[];
+    /** Target file/module to resolve and trace from. Repeatable and comma-aware. */
+    target?: string[];
     /** Extra files or globs appended without dependency resolution. */
     include?: string[];
     /** Files or globs to skip during traversal. */
@@ -10,13 +12,59 @@ export interface ProdexFlags {
     /** Output basename override for this run. */
     name?: string | null;
     /** Maximum dependency traversal depth. */
-    maxDepth?: number | null;
+    depth?: number | null;
     /** Maximum number of files to trace. */
     maxFiles?: number | null;
     /** Enable debug logs. */
     debug?: boolean;
-    /** Named profiles to run, in user-provided order. */
-    profiles?: string[];
-    /** Run all configured profiles. */
+    /** Scopes to merge for pack command. */
+    scope?: string[];
+    /** Keys of scopes to run for scope command. */
+    key?: string[];
+    /** Run all scopes for scope command. */
+    all?: boolean;
+    /** List available scopes. */
+    list?: boolean;
+    /** Perform a dry-run execution. */
+    dryRun?: boolean;
+    /** Sequential attached shell commands to execute. */
+    cmd?: string[];
+    /** Per-command timeout in seconds. */
+    cmdTimeout?: number | null;
+    /** Enforce strict mode, exiting nonzero if any command fails. */
+    failOnCmdError?: boolean;
+    /** Git-specific: Include staged, unstaged, and untracked changes. */
+    changed?: boolean;
+    /** Git-specific: Include staged changes only. */
+    staged?: boolean;
+    /** Git-specific: Include unstaged changes only. */
+    unstaged?: boolean;
+    /** Git-specific: Include untracked files only. */
+    untracked?: boolean;
+    /** Git-specific: Include full git diff output in generic sections. */
+    includeDiff?: boolean;
+    /** Git-specific: Snapshot files changed by a single commit. */
+    commit?: string;
+    /** Git-specific: Snapshot files changed between two commits (base..head or base...head). */
+    range?: string;
+    /** Git-specific: Compare merge-base of base and HEAD against HEAD. */
+    against?: string;
+    /** Grep-specific: search query */
+    query?: string;
+    /** Grep-specific: comma-separated list of terms for OR search */
+    any?: string[];
+    /** Grep-specific: comma-separated list of terms for AND search */
+    grepAll?: string[];
+    /** Grep-specific: regex pattern for search */
+    regex?: string;
+    /** Grep-specific: negative terms list */
+    not?: string[];
+    /** Grep-specific: search only inside these paths/globs */
+    within?: string[];
+    /** Grep-specific: do not search inside these paths/globs */
+    skip?: string[];
+    /** Deprecated legacy flags */
+    profile?: string[];
     allProfiles?: boolean;
+    maxDepth?: number | null;
 }

package/dist/types/config.types.d.ts

@@ -1,34 +1,51 @@
-export interface ProdexConfig extends ProdexBase {
+export interface ProdexConfig {
     root: string;
     name?: string;
+    dryRun?: boolean;
+    output: {
+        dir: string;
+        versioned: boolean;
+        format: "md" | "txt";
+    };
+    entry: string[];
+    include: string[];
+    exclude: string[];
+    aliases: Record<string, string>;
+    depth: number;
+    maxFiles: number;
+    scopes: Record<string, ProdexScope>;
+}
+export interface ProdexConfigFileOutput {
+    dir?: string;
+    versioned?: boolean;
+    format?: "md" | "txt";
 }
-export type ProdexConfigFile = DeepPartial<ProdexBase> & {
+export type ProdexConfigFile = {
     $schema: string;
     version: number;
+    output?: ProdexConfigFileOutput;
+    exclude?: string[];
+    aliases?: Record<string, string>;
+    depth?: number;
+    maxFiles?: number;
+    scopes?: Record<string, ProdexScope>;
 };
 export type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends Array<infer Item> ? Item[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
-export type ProdexProfile = {
+export interface ProdexGrepScopeConfig {
+    query?: string;
+    any?: string[];
+    all?: string[];
+    regex?: string;
+    not?: string[];
+    within?: string[];
+    skip?: string[];
+}
+export type ProdexScope = {
     name?: string;
     entry?: string[];
     include?: string[];
     exclude?: string[];
+    grep?: ProdexGrepScopeConfig;
 };
-interface ProdexBase {
-    output: {
-        dir: string;
-        versioned: boolean;
-        format: "md" | "txt";
-    };
-    entry: string[];
-    include: string[];
-    exclude: string[];
-    resolve: {
-        aliases: Record<string, string>;
-        maxDepth: number;
-        maxFiles: number;
-    };
-    profiles: Record<string, ProdexProfile>;
-}
-export {};

package/dist/types/index.d.ts

@@ -5,3 +5,5 @@ export * from "./output.types";
 export * from "./resolver.types";
 export * from "./utils.types";
 export * from "./app.types";
+export * from "./planner.types";
+export * from "./artifact.types";

package/dist/types/index.js

@@ -21,3 +21,5 @@ __exportStar(require("./output.types"), exports);
 __exportStar(require("./resolver.types"), exports);
 __exportStar(require("./utils.types"), exports);
 __exportStar(require("./app.types"), exports);
+__exportStar(require("./planner.types"), exports);
+__exportStar(require("./artifact.types"), exports);

package/dist/types/output.types.d.ts

@@ -1,6 +1,15 @@
-import type { ProdexConfig } from "./config.types";
+import type { ArtifactPayload } from "./artifact.types";
+export type LayoutOrder = "files-first" | "sections-first";
+export interface MdTraceEntry {
+    file: string;
+    anchor: number;
+    startLine: number;
+    endLine: number;
+}
 export interface OutputParams {
-    files: string[];
     name: string;
-    cfg: ProdexConfig;
+    payload: ArtifactPayload;
+    format: "md" | "txt";
+    dir: string;
+    versioned: boolean;
 }

package/dist/types/planner.types.d.ts

@@ -0,0 +1,76 @@
+import type { ProdexFlags } from "./cli.types";
+import type { CommandAttachmentOptions } from "./artifact.types";
+import type { ProdexCommandKind } from "./app.types";
+export type CommandIntent = {
+    kind: "pack";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "trace";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "scope";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "git";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+} | {
+    kind: "grep";
+    rootArg?: string;
+    flags: Partial<ProdexFlags>;
+};
+export type GitPlanOptions = {
+    mode: "working-tree";
+    changed: boolean;
+    staged: boolean;
+    unstaged: boolean;
+    untracked: boolean;
+    includeDiff: boolean;
+} | {
+    mode: "commit";
+    rev: string;
+    includeDiff: boolean;
+} | {
+    mode: "range";
+    spec: string;
+    base: string;
+    head: string;
+    includeDiff: boolean;
+} | {
+    mode: "against";
+    base: string;
+    mergeBase?: string;
+    includeDiff: boolean;
+};
+export interface GrepPlanOptions {
+    mode: "query" | "any" | "all" | "regex";
+    terms: string[];
+    negativeTerms: string[];
+    within: string[];
+    skip: string[];
+}
+export interface ExecutionPlan {
+    root: string;
+    command: ProdexCommandKind;
+    outputName?: string;
+    entry: string[];
+    target?: string[];
+    include: string[];
+    exclude: string[];
+    depth: number;
+    maxFiles: number;
+    aliases: Record<string, string>;
+    output: {
+        dir: string;
+        versioned: boolean;
+        format: "md" | "txt";
+    };
+    dryRun: boolean;
+    scopeKey?: string;
+    attachmentOptions?: CommandAttachmentOptions;
+    gitOptions?: GitPlanOptions;
+    grepOptions?: GrepPlanOptions;
+}

package/dist/types/planner.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/resolver.types.d.ts

@@ -5,7 +5,7 @@ export interface JsResolverCtx {
 }
 export interface PhpResolverCtx {
     kind: "php";
-    psr4: Record<string, string>;
+    psr4: Record<string, string | string[]>;
     nsKeys: string[];
     bindings: Record<string, string>;
 }

package/dist/types/tracing.types.d.ts

@@ -1,4 +1,3 @@
-import type { ProdexConfig } from "./config.types";
 export interface TraceStats {
     expected: Set<string>;
     resolved: Set<string>;
@@ -11,13 +10,3 @@ export interface TraceOptions {
     entries: string[];
     outputName?: string;
 }
-export interface TraceParams {
-    cfg: ProdexConfig;
-    opts: TraceOptions;
-}
-export interface TraceResult {
-    outputPath?: string;
-    entries: string[];
-    files: string[];
-    stats?: TraceStats;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prodex",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Focused code-context extractor for large projects.",
   "type": "commonjs",
   "packageManager": "npm@11.12.1",
@@ -41,7 +41,7 @@
     "dev": "tsc --watch",
     "gen:schema": "node schema/generate.js",
     "check:architecture": "node scripts/check-architecture.js",
-    "test": "npm run check:architecture && npm run build && node --test test/cli-contract.test.js",
+    "test": "npm run check:architecture && npm run build && node --test test/cli-contract.test.js test/git-command.test.js test/cleanup.test.js test/grep-command.test.js test/resolvers-and-config.test.js",
     "prepack": "npm run build",
     "pack:check": "npm pack --dry-run"
   },