reverseport 0.0.0-stage → 1.2.0

package/dist/application/ReferenceSourceImportTypes.js

@@ -0,0 +1,47 @@
+const IMPORT_FAILURE_GUIDANCE = {
+    cancelled: {
+        category: "cancelled",
+        message: "Reference source import was cancelled. Start it again when ready.",
+    },
+    "invalid-root": {
+        category: "invalid_input",
+        message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
+    },
+    unsupported: {
+        category: "unsupported_host",
+        message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
+    },
+    io: {
+        category: "execution_failure",
+        message: "Reference source files could not be read. Check directory permissions and try again.",
+    },
+    parse: {
+        category: "execution_failure",
+        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+    },
+};
+/** Safe CLI projection for a historical-source import failure. */
+export const projectReferenceSourceImportError = (error) => {
+    const primary = IMPORT_FAILURE_GUIDANCE[error.code];
+    const cleanupMessage = error.cleanup === undefined
+        ? ""
+        : ` Cleanup failed during import for ${error.cleanup.resources.join(", ")}: ${error.cleanup.reason}.`;
+    return {
+        category: primary.category,
+        message: `${error.message} ${primary.message}${cleanupMessage}`,
+        ...(error.cleanup === undefined ? {} : { cleanup: error.cleanup }),
+        ...(error.partial === undefined ? {} : { partial: error.partial }),
+    };
+};
+export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
+    ".git/",
+    ".git/hooks/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    "coverage/",
+    "htmlcov/",
+    ".coverage",
+    "*.log",
+];
+export const PARSEABLE_REFERENCE_SOURCE_LANGUAGES = new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);

package/dist/application/ReferenceSourceVcsAdapter.js

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import { lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { readRegularFile, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
+/**
+ * Read Git metadata for a directory using isomorphic-git.
+ *
+ * No git subprocess or network is used; only the local `.git` object store is read.
+ */
+export const readReferenceSourceVcs = async (root, resources, signal) => {
+    try {
+        return await resources.run(async () => {
+            if (isAborted(signal))
+                return ok(unknownVcs());
+            try {
+                await lstat(join(root, ".git"));
+            }
+            catch (cause) {
+                return ok(errorCode(cause) === "ENOENT"
+                    ? { kind: "none", head: null, dirty: null }
+                    : unknownVcs());
+            }
+            try {
+                const head = await resolveSourceHead(root, resources, signal);
+                if (isAborted(signal))
+                    return ok(unknownVcs());
+                return ok({ kind: "git", head, dirty: null });
+            }
+            catch (cause) {
+                if (cause instanceof ArtifactReaderFailure)
+                    throw cause;
+                return ok(unknownVcs());
+            }
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            tag: "reference-source-reader",
+            code: cause.reason === "cancelled" ? "cancelled" : "io",
+            message: cause.message,
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
+    }
+};
+const unknownVcs = () => ({
+    kind: "unknown",
+    head: null,
+    dirty: null,
+});
+const resolveSourceHead = async (root, resources, signal) => {
+    // isomorphic-git is loaded on first use so CLI and MCP startup skip it.
+    const { resolveRef } = await import("isomorphic-git");
+    let failedRead;
+    const cleanupFailures = [];
+    const readMetadataBytes = async (path) => {
+        try {
+            return await readRegularFile(path, { signal });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileCleanupFailure))
+                throw cause;
+            const retry = await retryRegularFileCleanup(cause, resources);
+            if (retry.outcome.kind === "failed" &&
+                errorCode(retry.outcome.cause) !== "ENOENT")
+                failedRead ??= { cause: retry.outcome.cause };
+            if (retry.cleanup === undefined &&
+                retry.outcome.kind === "failed" &&
+                !isAborted(signal))
+                throw retry.outcome.cause;
+            const primary = retry.outcome.kind === "failed"
+                ? retry.outcome.cause
+                : cause.cleanupCause;
+            throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+                cause: primary,
+                ...(retry.cleanup === undefined ? {} : { cleanup: retry.cleanup }),
+            });
+        }
+    };
+    const readMetadataText = async (path) => (await readMetadataBytes(path)).toString("utf8");
+    const throwCleanupFailures = (primary) => {
+        const observations = cleanupFailures.flatMap((failure) => failure.cleanup === undefined ? [] : [failure.cleanup]);
+        throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+            cause: new AggregateError([primary, ...cleanupFailures], "Git metadata reads and cleanup failed", { cause: primary }),
+            ...(observations.length === 0
+                ? {}
+                : {
+                    cleanup: {
+                        reason: observations.map(({ reason }) => reason).join("; "),
+                        resources: [
+                            ...new Set(observations.flatMap(({ resources }) => resources)),
+                        ],
+                    },
+                }),
+        });
+    };
+    const referenceFs = {
+        ...fs,
+        promises: {
+            ...fs.promises,
+            // Let isomorphic-git continue from a failed loose ref to packed-refs,
+            // then report the original read failure after resolution. This preserves
+            // both observations when packed metadata also fails cleanup.
+            readFile: async (path, options = null) => {
+                // The library probes readFile() without a path to detect promise APIs.
+                // Reject that invocation without attributing it to a source read.
+                if (path === undefined)
+                    throw new TypeError("Git filesystem read requires a path");
+                try {
+                    const bytes = await readMetadataBytes(path);
+                    const encoding = typeof options === "string" ? options : options?.encoding;
+                    return encoding === undefined || encoding === null
+                        ? bytes
+                        : bytes.toString(encoding);
+                }
+                catch (cause) {
+                    if (cause instanceof ArtifactReaderFailure) {
+                        cleanupFailures.push(cause);
+                    }
+                    else if (errorCode(cause) !== "ENOENT")
+                        failedRead ??= { cause };
+                    throw cause;
+                }
+            },
+        },
+    };
+    const readRef = async (options) => {
+        let head;
+        try {
+            head = await resolveRef({ fs: referenceFs, dir: root, ...options });
+        }
+        catch (cause) {
+            if (cleanupFailures.length > 0)
+                throwCleanupFailures(failedRead?.cause ?? cause);
+            if (failedRead !== undefined)
+                throw failedRead.cause;
+            throw cause;
+        }
+        if (cleanupFailures.length > 0)
+            throwCleanupFailures(failedRead?.cause ?? cleanupFailures[0]?.cause);
+        signal?.throwIfAborted();
+        if (failedRead !== undefined)
+            throw failedRead.cause;
+        return head;
+    };
+    const dotgit = join(root, ".git");
+    if (!(await lstat(dotgit)).isFile())
+        return readRef({ ref: "HEAD" });
+    const pointer = (await readMetadataText(dotgit)).replace(/\r?\n$/u, "");
+    if (!pointer.startsWith("gitdir: ") || pointer.length === 8)
+        throw new Error("Invalid Git directory pointer");
+    const gitdir = resolve(root, pointer.slice(8));
+    let commonDirectory;
+    try {
+        commonDirectory = resolve(gitdir, (await readMetadataText(join(gitdir, "commondir"))).replace(/\r?\n$/u, ""));
+    }
+    catch (cause) {
+        if (errorCode(cause) !== "ENOENT")
+            throw cause;
+        return readRef({ gitdir, ref: "HEAD" });
+    }
+    const head = (await readMetadataText(join(gitdir, "HEAD"))).trim();
+    if (!head.startsWith("ref: "))
+        return readRef({ gitdir, ref: "HEAD" });
+    const ref = head.slice(5);
+    const privateRef = ["refs/bisect/", "refs/rewritten/", "refs/worktree/"].some((prefix) => ref.startsWith(prefix));
+    return readRef({
+        gitdir: privateRef ? gitdir : commonDirectory,
+        ref,
+    });
+};
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? String(cause.code)
+    : undefined;
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const isAborted = (signal) => signal?.aborted === true;

package/dist/application/RegularFileRead.js

@@ -0,0 +1,120 @@
+import { lstat, stat } from "node:fs/promises";
+import { RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, RegularFileChangedError, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+/** A close failed after reading; this error transfers the exact handle owner. */
+export class RegularFileCleanupFailure extends Error {
+    path;
+    owner;
+    outcome;
+    cleanupCause;
+    constructor(path, owner, outcome, cleanupCause) {
+        super(`Regular file cleanup failed: ${path}`, {
+            cause: outcome.kind === "failed" ? outcome.cause : cleanupCause,
+        });
+        this.path = path;
+        this.owner = owner;
+        this.outcome = outcome;
+        this.cleanupCause = cleanupCause;
+        this.name = "RegularFileCleanupFailure";
+    }
+}
+/** Retry a failed close through its retained owner and report any remaining cleanup. */
+export const retryRegularFileCleanup = async (failure, resources) => {
+    const released = await resources.release({
+        kind: "file-handle",
+        handle: failure.owner,
+        resource: failure.path,
+    });
+    if (released.kind === "released")
+        return { outcome: failure.outcome };
+    return {
+        outcome: failure.outcome,
+        cleanup: {
+            reason: `${failureMessage(failure.cleanupCause)}; retry: ${failureMessage(released.cause)}`,
+            resources: [failure.path],
+        },
+    };
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Admit one regular-file handle, retain it through the consumer, and always close it. */
+export const withRegularFile = async (path, read, options = {}) => options.resources === undefined
+    ? withRegularFileOwned(path, read, options)
+    : options.resources.run(() => withRegularFileOwned(path, read, options));
+const withRegularFileOwned = async (path, read, options) => {
+    const { signal } = options;
+    let handle;
+    try {
+        handle = await openRegularFile(path, {
+            symlinks: options.symlinks ?? "follow",
+            signal,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegularFileAdmissionFailure))
+            throw cause;
+        const failure = new RegularFileCleanupFailure(path, cause.owner, { kind: "failed", cause: cause.cause }, cause.cleanupCause);
+        if (options.resources === undefined)
+            throw failure;
+        const retry = await retryRegularFileCleanup(failure, options.resources);
+        if (retry.cleanup !== undefined)
+            throw failure;
+        throw cause.cause;
+    }
+    const owner = new OwnedFileHandle(handle);
+    let outcome;
+    try {
+        const stats = await handle.stat();
+        signal?.throwIfAborted();
+        const value = await read(handle, stats);
+        signal?.throwIfAborted();
+        const [opened, currentPath] = await Promise.all([
+            handle.stat(),
+            options.symlinks === "reject" ? lstat(path) : stat(path),
+        ]);
+        if (!sameRegularFileState(stats, opened) ||
+            !sameRegularFileState(stats, currentPath))
+            throw new RegularFileChangedError(path);
+        outcome = { kind: "completed", value };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
+    }
+    try {
+        await owner.close();
+    }
+    catch (cleanupCause) {
+        const failure = new RegularFileCleanupFailure(path, owner, outcome, cleanupCause);
+        if (options.resources === undefined)
+            throw failure;
+        const retry = await retryRegularFileCleanup(failure, options.resources);
+        if (retry.cleanup !== undefined)
+            throw failure;
+        if (retry.outcome.kind === "failed")
+            throw retry.outcome.cause;
+        return retry.outcome.value;
+    }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
+};
+/** Admit a regular file without waiting for a pipe, then read its verified handle. */
+export const readRegularFile = (path, options = {}) => withRegularFile(path, async (handle, stats) => {
+    const bytes = await readBoundedFileBytes(handle, stats.size, options.signal);
+    if (bytes === undefined || bytes.length !== stats.size)
+        throw new RegularFileChangedError(path);
+    return bytes;
+}, options);
+/** Read one admitted regular file as UTF-8 without waiting on a pipe. */
+export const readRegularFileText = async (path, options = {}) => {
+    try {
+        return (await readRegularFile(path, options)).toString("utf8");
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure &&
+            cause.outcome.kind === "completed" &&
+            Buffer.isBuffer(cause.outcome.value))
+            throw new RegularFileCleanupFailure(cause.path, cause.owner, { kind: "completed", value: cause.outcome.value.toString("utf8") }, cause.cleanupCause);
+        throw cause;
+    }
+};