mind-palace-graph 0.3.0

package/dist/rg.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Thin wrapper over ripgrep's --json output.
+ *
+ * We don't reimplement grep. rg is the fastest, most correct regex
+ * engine available, and `--json` gives us structured matches we can
+ * build context nodes from. This module is the only place that
+ * knows about rg's CLI.
+ *
+ * Defensive posture against pathological input:
+ *   - Pass `--max-columns` so rg refuses to emit megabyte-long
+ *     `lines.text` payloads (minified assets, generated blobs).
+ *     A preview marker still tells us a match existed.
+ *   - Cap the in-memory line buffer. If rg emits a single JSON line
+ *     longer than the cap, we kill the process and throw rather than
+ *     letting V8 string-concat blow up O(n^2).
+ *   - Clip per-Match `text` so a single oversized match line can't
+ *     pin many megabytes into `pendingMatches` once per submatch.
+ *   - Surface JSON parse failures via `MPG_DEBUG` instead of silently
+ *     swallowing them — otherwise a truncated tail line looks like a
+ *     clean "no matches" result.
+ */
+import type { Match, RgOptions, Source } from "./types.js";
+export declare class RgError extends Error {
+    readonly code: number | null;
+    readonly stderr: string;
+    constructor(message: string, code: number | null, stderr: string);
+}
+export declare class RgNotFoundError extends Error {
+    constructor();
+}
+/**
+ * Run ripgrep and yield structured matches as they arrive (streaming).
+ */
+export declare function runRg(pattern: string, source: Source, sourceContent: string | null, options?: RgOptions): AsyncGenerator<Match>;

package/dist/rg.js

@@ -0,0 +1,288 @@
+/**
+ * Thin wrapper over ripgrep's --json output.
+ *
+ * We don't reimplement grep. rg is the fastest, most correct regex
+ * engine available, and `--json` gives us structured matches we can
+ * build context nodes from. This module is the only place that
+ * knows about rg's CLI.
+ *
+ * Defensive posture against pathological input:
+ *   - Pass `--max-columns` so rg refuses to emit megabyte-long
+ *     `lines.text` payloads (minified assets, generated blobs).
+ *     A preview marker still tells us a match existed.
+ *   - Cap the in-memory line buffer. If rg emits a single JSON line
+ *     longer than the cap, we kill the process and throw rather than
+ *     letting V8 string-concat blow up O(n^2).
+ *   - Clip per-Match `text` so a single oversized match line can't
+ *     pin many megabytes into `pendingMatches` once per submatch.
+ *   - Surface JSON parse failures via `MPG_DEBUG` instead of silently
+ *     swallowing them — otherwise a truncated tail line looks like a
+ *     clean "no matches" result.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { resolve as resolvePath } from "node:path";
+export class RgError extends Error {
+    code;
+    stderr;
+    constructor(message, code, stderr) {
+        super(message);
+        this.code = code;
+        this.stderr = stderr;
+        this.name = "RgError";
+    }
+}
+export class RgNotFoundError extends Error {
+    constructor() {
+        super("ripgrep (rg) is not installed or not on PATH. Install it from https://github.com/BurntSushi/ripgrep");
+        this.name = "RgNotFoundError";
+    }
+}
+/** Hard cap on per-line size we will buffer before bailing out. */
+const MAX_LINE_BUFFER_BYTES = 16 * 1024 * 1024; // 16 MB
+/** Default cap on per-line columns rg will emit. */
+const DEFAULT_MAX_COLUMNS = 1_000_000;
+/** Hard cap on per-Match.text size we push downstream. */
+const MAX_MATCH_TEXT_CHARS = 16 * 1024; // 16 KB per node's match line
+function debugLog(msg) {
+    if (process.env.MPG_DEBUG) {
+        try {
+            process.stderr.write(`mpg[rg]: ${msg}\n`);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Run ripgrep and yield structured matches as they arrive (streaming).
+ */
+export async function* runRg(pattern, source, sourceContent, options = {}) {
+    const args = ["--json", "--no-heading", "--no-messages"];
+    // Always cap per-line size. rg emits the preview form (still flags
+    // the match, just doesn't ship the body) for oversized lines.
+    const maxColumns = options.max_columns ?? DEFAULT_MAX_COLUMNS;
+    args.push("--max-columns", String(maxColumns));
+    args.push("--max-columns-preview");
+    if (options.case_insensitive)
+        args.push("-i");
+    if (options.word_match)
+        args.push("-w");
+    if (options.fixed_strings)
+        args.push("-F");
+    if (options.multiline)
+        args.push("-U", "--multiline-dotall");
+    if (options.hidden)
+        args.push("--hidden");
+    if (options.no_ignore)
+        args.push("-u");
+    if (options.include_globs) {
+        for (const g of options.include_globs)
+            args.push("--glob", g);
+    }
+    if (options.exclude_globs) {
+        for (const g of options.exclude_globs)
+            args.push("--glob", `!${g}`);
+    }
+    if (options.type)
+        args.push("--type", options.type);
+    if (options.glob_case_insensitive)
+        args.push("--glob-case-insensitive");
+    // Search target. Non-file sources go to a temp file with a random
+    // suffix — pid+ms is not enough when callers spawn many rg processes
+    // in the same millisecond.
+    let searchTarget;
+    let cleanup = null;
+    if (sourceContent !== null) {
+        const tmpDir = process.env.TMPDIR || process.env.TMP || process.env.TEMP || "/tmp";
+        const safeId = source.id.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
+        const rand = randomBytes(6).toString("hex");
+        const tmpPath = resolvePath(tmpDir, `mpg-${process.pid}-${Date.now()}-${rand}-${safeId}`);
+        const { writeFileSync, unlinkSync } = await import("node:fs");
+        writeFileSync(tmpPath, sourceContent, "utf8");
+        cleanup = () => {
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+        };
+        searchTarget = tmpPath;
+    }
+    else {
+        searchTarget = source.id;
+    }
+    args.push("--", pattern, searchTarget);
+    // Spawn rg.
+    let proc;
+    try {
+        proc = spawn("rg", args, { stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (err) {
+        if (cleanup)
+            cleanup();
+        if (err.code === "ENOENT") {
+            throw new RgNotFoundError();
+        }
+        throw err;
+    }
+    // Stream-parse: accumulate chunks, split by newline, process complete
+    // lines as they arrive. We track the buffer size so a pathological
+    // single line (e.g. minified asset containing many alternation hits)
+    // can't grow V8's string-concat path into O(n^2) memory.
+    let stderr = "";
+    if (proc.stderr) {
+        proc.stderr.setEncoding("utf8");
+        proc.stderr.on("data", (chunk) => { stderr += chunk; });
+    }
+    let lineBuffer = "";
+    let bufferOverflow = false;
+    let parseErrors = 0;
+    let pendingResolve = null;
+    const pendingMatches = [];
+    let streamEnded = false;
+    let aborted = false;
+    function clipMatchText(s) {
+        if (s.length <= MAX_MATCH_TEXT_CHARS)
+            return s;
+        const head = MAX_MATCH_TEXT_CHARS - 16;
+        return s.slice(0, head) + "…[clipped]";
+    }
+    function processLine(line) {
+        if (!line)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            parseErrors++;
+            debugLog(`JSON.parse failed on line of length ${line.length}: ${err.message}`);
+            return;
+        }
+        if (parsed.type !== "match")
+            return;
+        const m = parsed;
+        // rg emits `lines.text` as a string when the line fits under
+        // --max-columns. With --max-columns-preview, oversized lines get a
+        // truncated preview but the field is still a string.
+        const rawText = m.data?.lines?.text;
+        if (typeof rawText !== "string") {
+            debugLog(`match record missing lines.text at line ${m.data?.line_number}`);
+            return;
+        }
+        const txt = clipMatchText(stripTrailingNewline(rawText));
+        let matchSource;
+        if (sourceContent !== null) {
+            matchSource = source;
+        }
+        else {
+            const filePath = resolvePath(m.data.path.text);
+            matchSource = { id: filePath, type: "file" };
+        }
+        for (const sub of m.data.submatches) {
+            pendingMatches.push({
+                source: matchSource,
+                line: m.data.line_number,
+                text: txt,
+                match_start: sub.start,
+                match_end: sub.end,
+            });
+        }
+    }
+    function abortProc(reason) {
+        if (aborted)
+            return;
+        aborted = true;
+        debugLog(`aborting rg: ${reason}`);
+        try {
+            proc.kill("SIGTERM");
+        }
+        catch { /* ignore */ }
+    }
+    proc.stdout.setEncoding("utf8");
+    proc.stdout.on("data", (chunk) => {
+        if (aborted)
+            return;
+        // Guard before any string-concat. If a single line is already
+        // bigger than our cap, kill rg and let the generator surface the
+        // error on close — we never want O(n^2) string-concat growth.
+        if (lineBuffer.length + chunk.length > MAX_LINE_BUFFER_BYTES) {
+            bufferOverflow = true;
+            abortProc(`single line exceeded ${MAX_LINE_BUFFER_BYTES} bytes`);
+            if (pendingResolve) {
+                pendingResolve();
+                pendingResolve = null;
+            }
+            return;
+        }
+        lineBuffer += chunk;
+        const lines = lineBuffer.split("\n");
+        lineBuffer = lines.pop(); // keep incomplete last line
+        for (const line of lines)
+            processLine(line);
+        if (pendingMatches.length > 0 && pendingResolve) {
+            pendingResolve();
+            pendingResolve = null;
+        }
+    });
+    proc.stdout.on("end", () => {
+        // Process any trailing partial line — if we aborted because of
+        // overflow, skip this so we don't try to parse a multi-MB
+        // mid-line buffer.
+        if (!bufferOverflow && lineBuffer.trim())
+            processLine(lineBuffer);
+        streamEnded = true;
+        if (pendingResolve) {
+            pendingResolve();
+            pendingResolve = null;
+        }
+    });
+    const closePromise = new Promise((resolve, reject) => {
+        proc.on("error", reject);
+        proc.on("close", (code) => resolve({ code }));
+    });
+    // Async generator loop: drain pending matches, wait for more, repeat.
+    try {
+        let allEmitted = false;
+        while (!allEmitted) {
+            while (pendingMatches.length > 0) {
+                yield pendingMatches.shift();
+            }
+            if (streamEnded || bufferOverflow) {
+                allEmitted = true;
+            }
+            else {
+                await new Promise((resolve) => {
+                    pendingResolve = resolve;
+                });
+            }
+        }
+    }
+    finally {
+        const { code } = await closePromise;
+        if (cleanup)
+            cleanup();
+        if (parseErrors > 0) {
+            debugLog(`${parseErrors} JSON line(s) failed to parse during this scan`);
+        }
+        if (bufferOverflow) {
+            throw new RgError(`mpg: a single match line exceeded ${MAX_LINE_BUFFER_BYTES} bytes ` +
+                `for source ${source.id}. This usually means a minified asset or ` +
+                `generated blob — exclude it with --glob '!path' or pass a more ` +
+                `restrictive pattern.`, code, stderr);
+        }
+        // rg exit codes: 0 = matches, 1 = no matches, 2+ = error.
+        // We treat SIGTERM (null code on POSIX, sometimes propagated as
+        // exit 143 / signal name) as our own abort signal and don't
+        // surface it as a separate error.
+        if (!aborted && code !== null && code > 1) {
+            throw new RgError(`ripgrep exited with code ${code}: ${stderr.trim() || "unknown error"}`, code, stderr);
+        }
+    }
+}
+function stripTrailingNewline(s) {
+    if (s.endsWith("\r\n"))
+        return s.slice(0, -2);
+    if (s.endsWith("\n"))
+        return s.slice(0, -1);
+    return s;
+}
+//# sourceMappingURL=rg.js.map

package/dist/rg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rg.js","sourceRoot":"","sources":["../src/rg.ts"],"names":[],"mappings":"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"}

package/dist/sources.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Source resolution.
+ *
+ * A "source" is a stream of text we can search. mpg supports four kinds:
+ *
+ *   - file/glob: read from disk
+ *   - command:   exec a shell command, search its stdout
+ *   - stdin:     read piped input
+ *   - url:       fetch with HTTP GET
+ *
+ * For non-file sources we capture the content into memory and feed it
+ * to rg via a temp file (see rg.ts). This keeps rg as the single
+ * search engine while supporting arbitrary content types.
+ */
+import type { Source } from "./types.js";
+/** Read stdin once and cache it. Returns cached value on subsequent calls. */
+export declare function getStdin(): Promise<string>;
+/** Reset the cached stdin (e.g. in test teardown). */
+export declare function resetStdinCache(): void;
+export interface ResolvedSource {
+    source: Source;
+    /** Inline content if we have it (stdin, command, url, or small files). */
+    content: string | null;
+}
+/** Expand globs into individual file paths using Node's built-in fs.glob. */
+export declare function expandGlobs(patterns: string[]): Promise<string[]>;
+/** Heuristic: if a path exists as a file/dir, classify it. */
+export declare function classifyPath(p: string): "file" | "glob";
+/**
+ * Resolve a list of path specs to actual file paths.
+ *
+ * If `stdinContent` is provided, it is used as the content when
+ * resolving `@-` specs instead of reading process.stdin again.
+ * This avoids double-reading stdin when both content-from-stdin and
+ * path-list-from-stdin are used in the same invocation.
+ *
+ * A spec can be:
+ *   - `@-`         read paths from stdin, one per line
+ *   - `@<file>`    read paths from a file, one per line
+ *   - `path`       a literal file or directory path
+ *   - `glob`       a glob pattern; expanded via fs.glob
+ *
+ * Directories are recursed into. Empty lines and `#` comments are
+ * ignored when reading from a file.
+ */
+export declare function resolvePathSpecs(specs: string[], stdinContent?: string | null): Promise<string[]>;
+/**
+ * Split path specs into two buckets without expanding directories:
+ *
+ *   - `files`:    literal file paths the caller asked for. Each becomes
+ *                 a separate `runRg` invocation so they can be searched
+ *                 in parallel and their per-file content cache is hot.
+ *   - `bulk`:     directories and glob patterns. These get passed to
+ *                 rg as-is — rg walks them itself in parallel, much
+ *                 faster than fan-out-per-file from Node. Each bulk
+ *                 entry becomes one `runRg` invocation that may emit
+ *                 matches from many files.
+ *
+ * `@file` / `@-` are still expanded inline (the caller asked for an
+ * explicit list, so we respect that).
+ *
+ * Returns absolute paths so deduplication is stable across cwd-relative
+ * vs absolute inputs.
+ */
+export declare function classifyPathSpecs(specs: string[], stdinContent?: string | null): Promise<{
+    files: string[];
+    bulk: string[];
+}>;
+export declare function resolveFileSource(p: string): ResolvedSource;
+export declare function resolveGlobSource(pattern: string): Promise<ResolvedSource[]>;
+export declare function resolveCommandSource(cmd: string): ResolvedSource;
+/**
+ * Capture a shell command's stdout for searching.
+ *
+ * Quoting handled correctly: the command runs through the platform
+ * shell (`bash -c` on POSIX, `cmd /c` on Windows), so `git log
+ * --grep="fix bug"` parses the way the user typed it.
+ *
+ * Output is capped at COMMAND_OUTPUT_MAX_BYTES and the command is
+ * killed after COMMAND_TIMEOUT_MS so a hanging or runaway command
+ * can't lock up the agent harness.
+ */
+export declare function captureCommand(cmd: string): Promise<string>;
+/** Deprecated: use getStdin() instead to avoid double-reads. */
+export declare function captureStdin(): Promise<string>;
+export declare function captureUrl(url: string): Promise<string>;
+export declare function resolveUrlSource(url: string): ResolvedSource;