Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(reference)!: retain source and metadata cleanup owners
morluto53e7fadbd078
diff --git a/src/application/ReferenceSourceImport.ts b/src/application/ReferenceSourceImport.tsindex ddd85f4bb..3b8ace1e7 100644--- a/src/application/ReferenceSourceImport.ts+++ b/src/application/ReferenceSourceImport.ts@@ -8,8 +8,14 @@ import {type HistoricalSourceGraphInput,} from "../domain/referenceSourceGraph.js";import { err, ok, type Result } from "../domain/result.js";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";import { readReferenceSource } from "../reference/ReferenceSourceReader.js";-import type { ReferenceSourceEntryKind } from "../reference/ReferenceSourceReaderTypes.js";+import type {+ ReferenceSourceEntryKind,+ ReferenceSourceRead,+ ReferenceSourceReaderError,+} from "../reference/ReferenceSourceReaderTypes.js";import { parseReferenceSourceEntries } from "./ReferenceSourceImportEntries.js";import { readReferenceSourceVcs } from "./ReferenceSourceVcsAdapter.js";import {@@ -30,8 +36,12 @@ const failure = (message,});-const cancelled = (): ReferenceSourceImportError =>- failure("cancelled", "Reference source import cancelled");+const cancelled = (+ partial?: ReferenceSourceRead,+): ReferenceSourceImportError => ({+ ...failure("cancelled", "Reference source import cancelled"),+ ...(partial === undefined ? {} : { partial }),+});const isAborted = (signal?: AbortSignal): boolean => signal?.aborted === true;@@ -170,9 +180,10 @@ const createShouldExclude =*/export const importReferenceSource = async (options: ReferenceSourceImportOptions,+ resources: ArtifactResourceScope,): Promise<Result<HistoricalSourceGraph, ReferenceSourceImportError>> => {if (isAborted(options.signal)) return err(cancelled());- const prepared = await prepareReferenceSourceImport(options);+ const prepared = await prepareReferenceSourceImport(options, resources);if (!prepared.ok) return prepared;const { ignored, root, secrets } = prepared.value;if (isAborted(options.signal)) return err(cancelled());@@ -180,23 +191,30 @@ export const importReferenceSource = async (const exclusions: HistoricalSourceGraphInput["exclusions"] = [];const shouldExclude = createShouldExclude(exclusions, secrets, ignored);- const [readResult, vcs] = await Promise.all([- readReferenceSource(root, {+ const [readResult, vcsResult] = await Promise.all([+ readReferenceSource(root, resources, {...(options.signal === undefined ? {} : { signal: options.signal }),shouldExclude,}),- readReferenceSourceVcs(root, options.signal),+ readReferenceSourceVcs(root, resources, options.signal),]);- if (!readResult.ok) {- const error = readResult.error;- if (error.code === "cancelled") return err(cancelled());- if (error.code === "unsupported")- return err(failure("unsupported", error.message));- return err(failure("io", error.message));- }+ if (!readResult.ok)+ return err(+ combineReadFailures(+ readResult.error,+ vcsResult.ok ? undefined : vcsResult.error,+ readResult.error.partial,+ ),+ );+ if (!vcsResult.ok)+ return err(+ combineReadFailures(vcsResult.error, undefined, readResult.value),+ );- if (isAborted(options.signal)) return err(cancelled());+ const vcs = vcsResult.value;++ if (isAborted(options.signal)) return err(cancelled(readResult.value));const read = readResult.value;const filePaths = new Set(@@ -208,7 +226,7 @@ export const importReferenceSource = async (const { entries, relationships, parseFailures, limitations } =parseReferenceSourceEntries(read, filePaths, options.signal);- if (isAborted(options.signal)) return err(cancelled());+ if (isAborted(options.signal)) return err(cancelled(read));const uniqueRelationships = deduplicateRelationships(relationships);const uniqueFailures = normalizeHistoricalSourceParseFailures(parseFailures);@@ -254,3 +272,45 @@ export const importReferenceSource = async ();}};++const combineReadFailures = (+ primary: ReferenceSourceReaderError,+ other: ReferenceSourceReaderError | undefined,+ partial: ReferenceSourceRead | undefined,+): ReferenceSourceImportError => {+ const code =+ primary.code === "cancelled" || other?.code === "cancelled"+ ? "cancelled"+ : primary.code;+ const cleanup = mergeCleanup(primary.cleanup, other?.cleanup);+ const message =+ other === undefined+ ? primary.message+ : `${primary.message}; additional reference metadata failure: ${other.message}`;+ const cause =+ other === undefined+ ? primary.cause+ : new AggregateError(+ [primary, other],+ "Reference source inventory and metadata both failed",+ { cause: primary },+ );+ return {+ ...failure(code, message),+ ...(cleanup === undefined ? {} : { cleanup }),+ ...(partial === undefined ? {} : { partial }),+ ...(cause === undefined ? {} : { cause }),+ };+};++const mergeCleanup = (+ first: AnalysisCleanupObservation | undefined,+ second: AnalysisCleanupObservation | undefined,+): AnalysisCleanupObservation | undefined => {+ if (first === undefined) return second;+ if (second === undefined) return first;+ return {+ reason: `${first.reason}; ${second.reason}`,+ resources: [...new Set([...first.resources, ...second.resources])],+ };+};diff --git a/src/application/ReferenceSourceImportPolicy.ts b/src/application/ReferenceSourceImportPolicy.tsindex b67773f7a..547e57cd3 100644--- a/src/application/ReferenceSourceImportPolicy.ts+++ b/src/application/ReferenceSourceImportPolicy.ts@@ -2,9 +2,15 @@ import { lstat, realpath, stat } from "node:fs/promises";import { join, resolve } from "node:path";import ignore from "ignore";-import { readRegularFileText } from "./RegularFileRead.js";+import {+ readRegularFileText,+ RegularFileCleanupFailure,+ retryRegularFileCleanup,+} from "./RegularFileRead.js";import { err, ok, type Result } from "../domain/result.js";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";import {DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS,type ReferenceSourceImportError,@@ -52,7 +58,10 @@ const resolveRoot = async (return err(failure("cancelled", "Reference source import cancelled"));if (!metadata.isDirectory())return err(- failure("invalid-root", "Reference source root is not a directory"),+ failure(+ "invalid-root",+ `Reference source root is not a directory: ${requestedRoot}`,+ ),);const canonicalRoot = await realpath(resolve(requestedRoot));if (isAborted(signal))@@ -66,19 +75,16 @@ const resolveRoot = async ("Reference source root could not be resolved",);if (rootFailure === undefined) throw cause;- const message =- rootFailure.code === "invalid-root"- ? "Reference source root could not be resolved"- : rootFailure.message;- return err(failure(rootFailure.code, message));+ return err({ ...failure(rootFailure.code, rootFailure.message), cause });}};const buildIgnored = async (root: string,excludePaths: readonly string[],+ resources: ArtifactResourceScope,signal?: AbortSignal,-): Promise<ReturnType<typeof ignore>> => {+): Promise<Result<ReturnType<typeof ignore>, ReferenceSourceImportError>> => {const ignored = ignore();const policyPath = join(root, ".gitignore");let present = true;@@ -98,7 +104,29 @@ const buildIgnored = async (}signal?.throwIfAborted();if (present) {- const text = await readRegularFileText(policyPath, { signal });+ let text: string;+ try {+ text = await readRegularFileText(policyPath, { signal });+ } catch (cause: unknown) {+ if (!(cause instanceof RegularFileCleanupFailure)) throw cause;+ const retry = await retryRegularFileCleanup(cause, resources);+ if (retry.cleanup !== undefined) {+ const primary =+ cause.outcome.kind === "failed"+ ? cause.outcome.cause+ : cause.cleanupCause;+ return err({+ ...failure(+ signal?.aborted === true ? "cancelled" : "io",+ `Reference source ignore policy could not be read at ${policyPath}: ${errorMessage(primary)}`,+ ),+ cleanup: retry.cleanup,+ cause: primary,+ });+ }+ if (retry.outcome.kind === "failed") throw retry.outcome.cause;+ text = retry.outcome.value;+ }addMarkedPatterns(ignored, [text], "project-ignored");}addMarkedPatterns(@@ -109,33 +137,55 @@ const buildIgnored = async (for (const path of excludePaths) {addMarkedPatterns(ignored, [path, `${path}/`], "caller-excluded");}- return ignored;+ return ok(ignored);};/** Resolve the caller-selected directory and build path filters. */export const prepareReferenceSourceImport = async (options: ReferenceSourceImportOptions,+ resources: ArtifactResourceScope,): Promise<Result<PreparedReferenceSourceImport, ReferenceSourceImportError>> => {- const root = await resolveRoot(options.root, options.signal);- if (!root.ok) return root;try {- return ok({- root: root.value,- ignored: await buildIgnored(- root.value,- options.excludePaths ?? [],- options.signal,- ),- secrets: ignore().add([...options.policy.secretPatterns]),+ return await resources.run(async () => {+ const root = await resolveRoot(options.root, options.signal);+ if (!root.ok) return root;+ try {+ const ignored = await buildIgnored(+ root.value,+ options.excludePaths ?? [],+ resources,+ options.signal,+ );+ if (!ignored.ok) return ignored;+ return ok({+ root: root.value,+ ignored: ignored.value,+ secrets: ignore().add([...options.policy.secretPatterns]),+ });+ } catch (cause: unknown) {+ return err({+ ...failure(+ options.signal?.aborted === true ? "cancelled" : "io",+ `Reference source ignore policy could not be read at ${join(root.value, ".gitignore")}: ${errorMessage(cause)}`,+ ),+ cause,+ });+ }});} catch (cause: unknown) {- return err(- failure(- options.signal?.aborted === true ? "cancelled" : "io",- `Reference source ignore policy could not be read at ${join(root.value, ".gitignore")}: ${cause instanceof Error ? cause.message : String(cause)}`,+ if (!(cause instanceof ArtifactReaderFailure)) throw cause;+ return err({+ ...failure(+ cause.reason === "cancelled" ? "cancelled" : "io",+ cause.message,),- );+ ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),+ cause,+ });}};++const errorMessage = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);diff --git a/src/application/ReferenceSourceImportTypes.test.ts b/src/application/ReferenceSourceImportTypes.test.tsnew file mode 100644index 000000000..1bc4b25dd--- /dev/null+++ b/src/application/ReferenceSourceImportTypes.test.ts@@ -0,0 +1,80 @@+import { describe, expect, it } from "vitest";++import {+ projectReferenceSourceImportError,+ type ReferenceSourceImportError,+} from "./ReferenceSourceImportTypes.js";+import type { ReferenceSourceRead } from "../reference/ReferenceSourceReaderTypes.js";++describe("reference-source import error projection", () => {+ it("preserves primary evidence with category-specific recovery guidance", () => {+ const expectedCategories = {+ cancelled: "cancelled",+ "invalid-root": "invalid_input",+ unsupported: "unsupported_host",+ io: "execution_failure",+ parse: "execution_failure",+ } as const;+ for (const [code, category] of Object.entries(expectedCategories)) {+ const projected = projectReferenceSourceImportError({+ tag: "reference-source-import",+ code: code as ReferenceSourceImportError["code"],+ message: "EIO while reading /selected/source/src/main.ts",+ });+ expect(projected.category).toBe(category);+ expect(projected.message).toContain(+ "EIO while reading /selected/source/src/main.ts",+ );+ expect(projected.message).toMatch(+ /try again|when ready|Check that|REA on Linux/u,+ );+ }+ });++ it("preserves cancellation, partial facts, and cleanup diagnostics", () => {+ const bytes = Buffer.from("export const observed = true;\n");+ const partial: ReferenceSourceRead = {+ root: "/selected/source",+ entries: [+ {+ status: "read",+ kind: "file",+ path: "src/main.ts",+ bytes,+ size: bytes.length,+ },+ ],+ bytesRead: bytes.length,+ limitations: [],+ };+ const projected = projectReferenceSourceImportError({+ tag: "reference-source-import",+ code: "cancelled",+ message: "Traversal cancelled after reading src/main.ts",+ cleanup: {+ reason: "directory close rejected",+ resources: ["/selected/source"],+ },+ partial,+ });++ expect(projected).toMatchObject({+ category: "cancelled",+ message: expect.stringContaining(+ "Traversal cancelled after reading src/main.ts",+ ),+ cleanup: {+ reason: "directory close rejected",+ resources: ["/selected/source"],+ },+ partial: {+ root: "/selected/source",+ entries: [{ path: "src/main.ts", bytes }],+ },+ });+ expect(projected.message).toContain("Cleanup failed during import");+ expect(projected.message).toContain("directory close rejected");+ expect(projected.message).toContain("/selected/source");+ expect(projected.message).not.toContain("remains unconfirmed");+ });+});diff --git a/src/application/ReferenceSourceImportTypes.ts b/src/application/ReferenceSourceImportTypes.tsindex 81f79eaaa..9395dc5c0 100644--- a/src/application/ReferenceSourceImportTypes.ts+++ b/src/application/ReferenceSourceImportTypes.ts@@ -1,44 +1,67 @@import type { ReferenceSourcePolicy } from "../domain/referenceSourcePolicy.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";+import type { ReferenceSourceRead } from "../reference/ReferenceSourceReaderTypes.js";/** Typed expected failure returned by historical-source imports. */export interface ReferenceSourceImportError {readonly tag: "reference-source-import";readonly code: "cancelled" | "invalid-root" | "unsupported" | "io" | "parse";readonly message: string;+ readonly cleanup?: AnalysisCleanupObservation;+ readonly partial?: ReferenceSourceRead;+ readonly cause?: unknown;}+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.",+ },+} satisfies Record<+ ReferenceSourceImportError["code"],+ { readonly category: string; readonly message: string }+>;+/** Safe CLI projection for a historical-source import failure. */export const projectReferenceSourceImportError = (error: ReferenceSourceImportError,-): Readonly<{ category: string; message: string }> => {- if (error.code === "cancelled")- return {- category: "cancelled",- message:- "Reference source import was cancelled. Start it again when ready.",- };- if (error.code === "invalid-root")- return {- category: "invalid_input",- message:- "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",- };- if (error.code === "unsupported")- return {- 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.",- };- if (error.code === "io")- return {- category: "execution_failure",- message:- "Reference source files could not be read. Check directory permissions and try again.",- };+): Readonly<{+ category: string;+ message: string;+ cleanup?: AnalysisCleanupObservation;+ partial?: ReferenceSourceRead;+}> => {+ 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: "execution_failure",- message:- "Reference source could not be indexed. Check that the source tree is readable, then try again.",+ category: primary.category,+ message: `${error.message} ${primary.message}${cleanupMessage}`,+ ...(error.cleanup === undefined ? {} : { cleanup: error.cleanup }),+ ...(error.partial === undefined ? {} : { partial: error.partial }),};};diff --git a/src/application/ReferenceSourceVcsAdapter.ts b/src/application/ReferenceSourceVcsAdapter.tsindex f70ace901..5bb6d0e35 100644--- a/src/application/ReferenceSourceVcsAdapter.ts+++ b/src/application/ReferenceSourceVcsAdapter.ts@@ -1,7 +1,17 @@import fs from "node:fs";import { lstat } from "node:fs/promises";import { join, resolve } from "node:path";-import { readRegularFile, readRegularFileText } from "./RegularFileRead.js";+import { err, ok, type Result } from "../domain/result.js";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";+import {+ readRegularFile,+ readRegularFileText,+ RegularFileCleanupFailure,+ retryRegularFileCleanup,+} from "./RegularFileRead.js";+import type { ReferenceSourceReaderError } from "../reference/ReferenceSourceReaderTypes.js";export type ReferenceSourceVcsInfo =| {@@ -19,40 +29,122 @@ export type ReferenceSourceVcsInfo =*/export const readReferenceSourceVcs = async (root: string,+ resources: ArtifactResourceScope,signal?: AbortSignal,-): Promise<ReferenceSourceVcsInfo> => {- if (isAborted(signal)) return { kind: "unknown", head: null, dirty: null };+): Promise<Result<ReferenceSourceVcsInfo, ReferenceSourceReaderError>> => {try {- await lstat(join(root, ".git"));- } catch (cause: unknown) {- return errorCode(cause) === "ENOENT"- ? { kind: "none", head: null, dirty: null }- : { kind: "unknown", head: null, dirty: null };- }- try {- const head = await resolveSourceHead(root, signal);- if (isAborted(signal)) return { kind: "unknown", head: null, dirty: null };- return { kind: "git", head, dirty: null };+ return await resources.run(async () => {+ if (isAborted(signal)) return ok(unknownVcs());+ try {+ await lstat(join(root, ".git"));+ } catch (cause: unknown) {+ 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: unknown) {+ if (cause instanceof ArtifactReaderFailure) throw cause;+ if (cause instanceof RegularFileCleanupFailure) {+ const retry = await retryRegularFileCleanup(cause, resources);+ if (retry.cleanup !== undefined) {+ const primary =+ cause.outcome.kind === "failed"+ ? cause.outcome.cause+ : cause.cleanupCause;+ const code = isAborted(signal) ? "cancelled" : "io";+ return err({+ tag: "reference-source-reader",+ code,+ message: `Git metadata could not be read safely: ${errorMessage(primary)}`,+ cleanup: retry.cleanup,+ cause: primary,+ });+ }+ if (retry.outcome.kind === "completed")+ return err({+ tag: "reference-source-reader",+ code: isAborted(signal) ? "cancelled" : "io",+ message: isAborted(signal)+ ? "Git metadata read cancelled"+ : `Git metadata close failed: ${errorMessage(cause.cleanupCause)}`,+ cause: cause.cleanupCause,+ });+ if (retry.outcome.kind === "failed") {+ return isAborted(signal)+ ? err({+ tag: "reference-source-reader",+ code: "cancelled",+ message: "Git metadata read cancelled",+ cause: retry.outcome.cause,+ })+ : ok(unknownVcs());+ }+ }+ return ok(unknownVcs());+ }+ });} catch (cause: unknown) {- // Unresolvable refs mean VCS state is unknown, not absent.- void cause;- return { kind: "unknown", head: null, dirty: null };+ 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 = (): ReferenceSourceVcsInfo => ({+ kind: "unknown",+ head: null,+ dirty: null,+});+const resolveSourceHead = async (root: string,+ resources: ArtifactResourceScope,signal?: AbortSignal,): Promise<string> => {// isomorphic-git is loaded on first use so CLI and MCP startup skip it.const { resolveRef } = await import("isomorphic-git");let failedRead: { readonly cause: unknown } | undefined;+ const cleanupFailures: {+ readonly failure: RegularFileCleanupFailure;+ readonly cleanup?: NonNullable<ArtifactReaderFailure["cleanup"]>;+ }[] = [];+ const throwCleanupFailures = (primary: unknown): never => {+ const cleanup = mergeCleanup(+ 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.map((item) => item.failure)],+ "Git metadata reads and cleanup failed",+ { cause: primary },+ ),+ ...(cleanup === undefined ? {} : { cleanup }),+ },+ );+ };const referenceFs = {...fs,promises: {...fs.promises,- // isomorphic-git treats every read failure as absence. Preserve real- // failures so a readable packed ref cannot hide an unreadable loose ref.+ // 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: string | undefined,options:@@ -72,7 +164,20 @@ const resolveSourceHead = async (? bytes: bytes.toString(encoding);} catch (cause: unknown) {- if (errorCode(cause) !== "ENOENT") failedRead ??= { cause };+ if (cause instanceof RegularFileCleanupFailure) {+ const retry = await retryRegularFileCleanup(cause, resources);+ cleanupFailures.push({+ failure: cause,+ ...(retry.cleanup === undefined+ ? {}+ : { cleanup: retry.cleanup }),+ });+ if (+ retry.outcome.kind === "failed" &&+ errorCode(retry.outcome.cause) !== "ENOENT"+ )+ failedRead ??= { cause: retry.outcome.cause };+ } else if (errorCode(cause) !== "ENOENT") failedRead ??= { cause };throw cause;}},@@ -82,7 +187,19 @@ const resolveSourceHead = async (readonly gitdir?: string;readonly ref: string;}) => {- const head = await resolveRef({ fs: referenceFs, dir: root, ...options });+ let head: string;+ try {+ head = await resolveRef({ fs: referenceFs, dir: root, ...options });+ } catch (cause: unknown) {+ if (cleanupFailures.length > 0)+ throwCleanupFailures(failedRead?.cause ?? cause);+ if (failedRead !== undefined) throw failedRead.cause;+ throw cause;+ }+ if (cleanupFailures.length > 0)+ throwCleanupFailures(+ failedRead?.cause ?? cleanupFailurePrimary(cleanupFailures[0]),+ );signal?.throwIfAborted();if (failedRead !== undefined) throw failedRead.cause;return head;@@ -122,9 +239,38 @@ const resolveSourceHead = async (});};+const cleanupFailurePrimary = (+ failure:+ | {+ readonly failure: RegularFileCleanupFailure;+ }+ | undefined,+): unknown =>+ failure?.failure.outcome.kind === "failed"+ ? failure.failure.outcome.cause+ : failure?.failure.cleanupCause;++const mergeCleanup = (+ observations: readonly AnalysisCleanupObservation[],+): AnalysisCleanupObservation | undefined => {+ if (observations.length === 0) return undefined;+ const first = observations[0];+ if (first === undefined) return undefined;+ return observations.slice(1).reduce<AnalysisCleanupObservation>(+ (merged, next) => ({+ reason: `${merged.reason}; ${next.reason}`,+ resources: [...new Set([...merged.resources, ...next.resources])],+ }),+ first,+ );+};+const errorCode = (cause: unknown): string | undefined =>typeof cause === "object" && cause !== null && "code" in cause? String(cause.code): undefined;+const errorMessage = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);+const isAborted = (signal?: AbortSignal): boolean => signal?.aborted === true;diff --git a/src/application/RegularFileRead.ts b/src/application/RegularFileRead.tsindex f584f1f6e..1c3852326 100644--- a/src/application/RegularFileRead.ts+++ b/src/application/RegularFileRead.ts@@ -2,11 +2,15 @@ import type { Stats } from "node:fs";import { lstat, stat, type FileHandle } 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";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";/** Filesystem admission policy for one selected regular input. */export interface RegularFileReadOptions {@@ -14,6 +18,51 @@ export interface RegularFileReadOptions {readonly symlinks?: "follow" | "reject";}+export type RegularFileReadOutcome<Value> =+ | { readonly kind: "completed"; readonly value: Value }+ | { readonly kind: "failed"; readonly cause: unknown };++/** A close failed after reading; this error transfers the exact handle owner. */+export class RegularFileCleanupFailure<Value = unknown> extends Error {+ constructor(+ readonly path: string,+ readonly owner: OwnedFileHandle,+ readonly outcome: RegularFileReadOutcome<Value>,+ readonly cleanupCause: unknown,+ ) {+ super(`Regular file cleanup failed: ${path}`, {+ cause: outcome.kind === "failed" ? outcome.cause : cleanupCause,+ });+ this.name = "RegularFileCleanupFailure";+ }+}++/** Retry a failed close through its retained owner and report any remaining cleanup. */+export const retryRegularFileCleanup = async <Value>(+ failure: RegularFileCleanupFailure<Value>,+ resources: ArtifactResourceScope,+): Promise<{+ readonly outcome: RegularFileReadOutcome<Value>;+ readonly cleanup?: AnalysisCleanupObservation;+}> => {+ 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: unknown): string =>+ 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 <Value>(path: string,@@ -21,10 +70,23 @@ export const withRegularFile = async <Value>(options: RegularFileReadOptions = {},): Promise<Value> => {const { signal } = options;- const handle = await openRegularFile(path, {- symlinks: options.symlinks ?? "follow",- signal,- });+ let handle: FileHandle;+ try {+ handle = await openRegularFile(path, {+ symlinks: options.symlinks ?? "follow",+ signal,+ });+ } catch (cause: unknown) {+ if (!(cause instanceof RegularFileAdmissionFailure)) throw cause;+ throw new RegularFileCleanupFailure(+ path,+ cause.owner,+ { kind: "failed", cause: cause.cause },+ cause.cleanupCause,+ );+ }+ const owner = new OwnedFileHandle(handle);+ let outcome: RegularFileReadOutcome<Value>;try {const stats = await handle.stat();signal?.throwIfAborted();@@ -39,10 +101,17 @@ export const withRegularFile = async <Value>(!sameRegularFileState(stats, currentPath))throw new RegularFileChangedError(path);- return value;- } finally {- await handle.close();+ outcome = { kind: "completed", value };+ } catch (cause: unknown) {+ outcome = { kind: "failed", cause };}+ try {+ await owner.close();+ } catch (cleanupCause: unknown) {+ throw new RegularFileCleanupFailure(path, owner, outcome, cleanupCause);+ }+ if (outcome.kind === "failed") throw outcome.cause;+ return outcome.value;};/** Admit a regular file without waiting for a pipe, then read its verified handle. */@@ -69,4 +138,21 @@ export const readRegularFile = (export const readRegularFileText = async (path: string,options: RegularFileReadOptions = {},-): Promise<string> => (await readRegularFile(path, options)).toString("utf8");+): Promise<string> => {+ try {+ return (await readRegularFile(path, options)).toString("utf8");+ } catch (cause: unknown) {+ 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;+ }+};diff --git a/src/cli/referenceSourceImportStatus.ts b/src/cli/referenceSourceImportStatus.tsindex 2cfe3246d..c9f8e7087 100644--- a/src/cli/referenceSourceImportStatus.ts+++ b/src/cli/referenceSourceImportStatus.ts@@ -11,6 +11,13 @@ const referenceSourceImportFailureSchema = z.strictObject({"execution_failure",]),message: z.string().min(1),+ cleanup: z+ .strictObject({+ reason: z.string().min(1),+ resources: z.array(z.string().min(1)),+ })+ .optional(),+ partial: z.unknown().optional(),});/** Identify the historical-source import command's failed operation outputs. */diff --git a/src/cli/utilityCommands.ts b/src/cli/utilityCommands.tsindex 0c4f79c5a..47cb9e5bc 100644--- a/src/cli/utilityCommands.ts+++ b/src/cli/utilityCommands.ts@@ -1,8 +1,12 @@import { z } from "incur";import type { DirectAnalysis } from "../composition/directAnalysis.js";+import type { ReferenceSourcePolicy } from "../domain/referenceSourcePolicy.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import { importReferenceSource } from "../application/ReferenceSourceImport.js";import { projectReferenceSourceImportError } from "../application/ReferenceSourceImportTypes.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";import { parseConfig } from "../config/parseConfig.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import { AnalysisInputError } from "../domain/analysisErrorCore.js";@@ -221,21 +225,110 @@ const registerReferenceSourceCommand = (error: "Import failed",...projectAnalysisError(config.error),};- const imported = await importReferenceSource({- root: args.root,- caller: "rea-cli",- policy: config.value.referenceSourcePolicy,- importer: PRODUCT_IDENTITY.packageName,- importerVersion: null,- });- return imported.ok- ? imported.value- : {- error: "Import failed",- ...projectReferenceSourceImportError(imported.error),- };+ return runReferenceSourceImport(+ args.root,+ config.value.referenceSourcePolicy,+ );},isReferenceSourceImportCliFailure,),});};++const runReferenceSourceImport = async (+ root: string,+ policy: ReferenceSourcePolicy,+): Promise<unknown> => {+ const resources = new ArtifactResourceScope();+ let outcome:+ | {+ readonly kind: "result";+ readonly imported: Awaited<ReturnType<typeof importReferenceSource>>;+ }+ | { readonly kind: "thrown"; readonly cause: unknown };+ try {+ outcome = {+ kind: "result",+ imported: await importReferenceSource(+ {+ root,+ caller: "rea-cli",+ policy,+ importer: PRODUCT_IDENTITY.packageName,+ importerVersion: null,+ },+ resources,+ ),+ };+ } catch (cause: unknown) {+ outcome = { kind: "thrown", cause };+ }++ let closeOutcome:+ | { readonly kind: "closed" }+ | { readonly kind: "failed"; readonly cause: unknown };+ try {+ await resources.close();+ closeOutcome = { kind: "closed" };+ } catch (cause: unknown) {+ closeOutcome = { kind: "failed", cause };+ }++ if (outcome.kind === "thrown") {+ if (closeOutcome.kind === "failed")+ throw new AggregateError(+ [outcome.cause, closeOutcome.cause],+ "Reference source import and cleanup both failed",+ { cause: outcome.cause },+ );+ throw outcome.cause;+ }++ const imported = outcome.imported;+ if (!imported.ok) {+ const cleanup =+ closeOutcome.kind === "closed"+ ? imported.error.cleanup+ : mergeReferenceSourceCleanup(+ imported.error.cleanup,+ ArtifactReaderFailure.cleanupObservation(+ closeOutcome.cause,+ "reference source",+ ),+ );+ return {+ error: "Import failed",+ ...projectReferenceSourceImportError({+ ...imported.error,+ ...(cleanup === undefined ? {} : { cleanup }),+ }),+ };+ }++ if (closeOutcome.kind === "failed")+ return {+ error: "Import failed",+ ...projectReferenceSourceImportError({+ tag: "reference-source-import",+ code: "io",+ message: "Reference source cleanup failed after import",+ cleanup: ArtifactReaderFailure.cleanupObservation(+ closeOutcome.cause,+ "reference source",+ ),+ cause: closeOutcome.cause,+ }),+ };+ return imported.value;+};++const mergeReferenceSourceCleanup = (+ first: AnalysisCleanupObservation | undefined,+ second: AnalysisCleanupObservation,+): AnalysisCleanupObservation =>+ first === undefined+ ? second+ : {+ reason: `${first.reason}; ${second.reason}`,+ resources: [...new Set([...first.resources, ...second.resources])],+ };diff --git a/src/reference/ReferenceSourceReader.ts b/src/reference/ReferenceSourceReader.tsindex 2821dd3d4..aa1e3b1d4 100644--- a/src/reference/ReferenceSourceReader.ts+++ b/src/reference/ReferenceSourceReader.ts@@ -1,5 +1,7 @@import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";import { err, ok } from "../domain/result.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";import {type ReferenceSourceReaderOptions,@@ -19,7 +21,27 @@ const PATH_RACE_LIMITATION =/** Read a source tree without intentionally following symbolic links. */export const readReferenceSource = async (root: string,+ resources: ArtifactResourceScope,options: ReferenceSourceReaderOptions = {},+): Promise<ReferenceSourceResult<ReferenceSourceRead>> => {+ try {+ return await resources.run(() => readSource(root, resources, options));+ } catch (cause: unknown) {+ 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 readSource = async (+ root: string,+ resources: ArtifactResourceScope,+ options: ReferenceSourceReaderOptions,): Promise<ReferenceSourceResult<ReferenceSourceRead>> => {if (!noFollowOpenSupported())return err({@@ -31,6 +53,7 @@ export const readReferenceSource = async (if (!prepared.ok) return prepared;const { canonicalRoot, rootIdentity } = prepared.value;const state: TraversalState = {+ resources,root: canonicalRoot,rootIdentity,...(options.signal === undefined ? {} : { signal: options.signal }),@@ -42,16 +65,16 @@ export const readReferenceSource = async (bytesRead: 0,};const traversal = await traverse(state);- if (!traversal.ok) return traversal;state.entries.sort((left, right) =>compareUnicodeCodePoints(left.path, right.path),);- return ok({+ const read: ReferenceSourceRead = {root: canonicalRoot,entries: state.entries,bytesRead: state.bytesRead,limitations: [PATH_RACE_LIMITATION],- });+ };+ return traversal.ok ? ok(read) : err({ ...traversal.error, partial: read });};const traverse = async (diff --git a/src/reference/ReferenceSourceReaderEntries.ts b/src/reference/ReferenceSourceReaderEntries.tsindex 162c96811..cad5b7864 100644--- a/src/reference/ReferenceSourceReaderEntries.ts+++ b/src/reference/ReferenceSourceReaderEntries.ts@@ -1,10 +1,15 @@import type { BigIntStats, Dir, Dirent } from "node:fs";import { opendir, readlink, realpath } from "node:fs/promises";import { dirname, join, resolve } from "node:path";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import type { ArtifactCleanupAttempt } from "../artifacts/ArtifactResourceScope.js";+import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";+import { err, ok } from "../domain/result.js";import {cancelled,entryFailure,+ failure,filesystemFailureDetail,safeSize,} from "./ReferenceSourceReaderErrors.js";@@ -56,28 +61,68 @@ export const traverseDirectory = async (readFailure = directoryReadFailure(cause);}if (handle !== undefined) {- const iterator = handle[Symbol.asyncIterator]();+ const owner = new OwnedDirectoryHandle(handle);+ let result: ReferenceSourceResult<undefined> = ok(undefined);+ let cleanup: ArtifactCleanupAttempt;try {for (;;) {- let child: IteratorResult<Dirent>;+ let child: Dirent | null;try {- child = await iterator.next();+ child = await handle.read();} catch (cause: unknown) {readFailure = directoryReadFailure(cause);break;}- if (child.done) break;- const result = await processEntry(- state,- current,- child.value.name,- directories,- );- if (!result.ok) return result;+ if (child === null) break;+ result = await processEntry(state, current, child.name, directories);+ if (!result.ok) break;}} finally {- await handle.close().catch(() => undefined);+ cleanup = await state.resources.release({+ kind: "directory-handle",+ handle: owner,+ resource: current.path,+ });+ }+ if (cleanup.kind === "failed") {+ if (result.ok && !isAborted(state.signal) && readFailure !== undefined)+ state.entries.push(+ entryFailure(+ pathFromRoot(state.root, current.path),+ "directory",+ "io",+ readFailure,+ ),+ );+ const observation = ArtifactReaderFailure.cleanupObservation(+ cleanup.cause,+ current.path,+ );+ const previous = result.ok ? undefined : result.error.cleanup;+ const primary = result.ok+ ? isAborted(state.signal)+ ? cancelled()+ : failure(+ "io",+ readFailure ??+ `Reference directory cleanup failed: ${current.path}`,+ )+ : result.error;+ return err({+ ...primary,+ cleanup:+ previous === undefined+ ? observation+ : {+ reason: `${previous.reason}; ${observation.reason}`,+ resources: [+ ...new Set([...previous.resources, ...observation.resources]),+ ],+ },+ cause: primary.cause ?? cleanup.cause,+ });}+ if (!result.ok) return result;}if (isAborted(state.signal)) return { ok: false, error: cancelled() };if (readFailure !== undefined) {@@ -194,7 +239,7 @@ const processEntry = async (safeSize(metadata.value.size),),);- else await processFileEntry(state, absolute, path, metadata.value);+ else return processFileEntry(state, absolute, path, metadata.value);return { ok: true, value: undefined };};@@ -203,8 +248,9 @@ const processFileEntry = async (absolute: string,path: string,metadata: BigIntStats,-): Promise<void> => {+): Promise<ReferenceSourceResult<undefined>> => {const result = await readStableFile({+ resources: state.resources,root: state.root,rootIdentity: state.rootIdentity,absolute,@@ -212,9 +258,24 @@ const processFileEntry = async (expected: metadata,...(state.signal === undefined ? {} : { signal: state.signal }),});- if (result.status === "read" && result.kind === "file")- state.bytesRead += result.bytes.byteLength;- state.entries.push(result);+ const { entry } = result;+ if (entry.status === "read" && entry.kind === "file")+ state.bytesRead += entry.bytes.byteLength;+ state.entries.push(entry);+ if (result.cleanup !== undefined)+ return err({+ tag: "reference-source-reader",+ code:+ entry.status === "failed" && entry.code === "cancelled"+ ? "cancelled"+ : "io",+ message:+ entry.status === "failed"+ ? entry.message+ : `Reference file cleanup failed: ${path}`,+ cleanup: result.cleanup,+ });+ return ok(undefined);};const describeSymlink = async (diff --git a/src/reference/ReferenceSourceReaderFile.ts b/src/reference/ReferenceSourceReaderFile.tsindex 6f61c0253..27b5c37ef 100644--- a/src/reference/ReferenceSourceReaderFile.ts+++ b/src/reference/ReferenceSourceReaderFile.ts@@ -4,8 +4,12 @@ import { dirname } from "node:path";import {NonRegularFileReadError,+ RegularFileAdmissionFailure,openRegularFile,} from "../filesystem/RegularFile.js";+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";import {entryFailure,@@ -195,9 +199,39 @@ const finalizeFileRead = async (export const readStableFile = async (request: StableFileRequest,+): Promise<{+ readonly entry: ReferenceSourceEntry;+ readonly cleanup?: AnalysisCleanupObservation;+}> => {+ let owner: OwnedFileHandle | undefined;+ let cleanup: AnalysisCleanupObservation | undefined;+ let entry: ReferenceSourceEntry;+ try {+ entry = await readStableFileEntry(request, (admitted) => {+ owner = admitted;+ });+ } finally {+ if (owner !== undefined) {+ const result = await request.resources.release({+ kind: "file-handle",+ handle: owner,+ resource: request.absolute,+ });+ if (result.kind === "failed")+ cleanup = ArtifactReaderFailure.cleanupObservation(+ result.cause,+ request.absolute,+ );+ }+ }+ return { entry, ...(cleanup === undefined ? {} : { cleanup }) };+};++const readStableFileEntry = async (+ request: StableFileRequest,+ retain: (owner: OwnedFileHandle) => void,): Promise<ReferenceSourceEntry> => {const { root, rootIdentity, absolute, path, expected, signal } = request;- let handle: FileHandle | undefined;try {const parentBefore = await validateDirectory(root,@@ -213,7 +247,11 @@ export const readStableFile = async (parentBefore.message,safeSize(expected.size),);- handle = await openRegularFile(absolute, { symlinks: "reject", signal });+ const handle = await openRegularFile(absolute, {+ symlinks: "reject",+ signal,+ });+ retain(new OwnedFileHandle(handle));const prepared = await prepareFileRead(request, handle);if (prepared.status === "failed") return prepared.entry;const contents = await readFileContents({@@ -236,6 +274,10 @@ export const readStableFile = async (...(signal === undefined ? {} : { signal }),});} catch (cause: unknown) {+ if (cause instanceof RegularFileAdmissionFailure) {+ retain(cause.owner);+ cause = cause.cause;+ }if (isAborted(signal))return entryFailure(path,@@ -258,8 +300,5 @@ export const readStableFile = async ();if (message === undefined) throw cause;return entryFailure(path, "file", "io", message, safeSize(expected.size));- } finally {- // best-effort cleanup: file-handle close must not mask the read result.- await handle?.close().catch(() => undefined);}};diff --git a/src/reference/ReferenceSourceReaderTypes.ts b/src/reference/ReferenceSourceReaderTypes.tsindex 08ed9d78b..76096ef71 100644--- a/src/reference/ReferenceSourceReaderTypes.ts+++ b/src/reference/ReferenceSourceReaderTypes.ts@@ -1,6 +1,8 @@import { type BigIntStats } from "node:fs";import { type Result } from "../domain/result.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";export type ReferenceSourceEntryKind =| "file"@@ -65,6 +67,10 @@ export interface ReferenceSourceReaderError {readonly tag: "reference-source-reader";readonly code: "cancelled" | "invalid-root" | "io" | "unsupported";readonly message: string;+ readonly cleanup?: AnalysisCleanupObservation;+ /** Captured entries before failure; this does not establish complete tree coverage. */+ readonly partial?: ReferenceSourceRead;+ readonly cause?: unknown;}export type PendingDirectory = {@@ -72,6 +78,7 @@ export type PendingDirectory = {};export type TraversalState = {+ readonly resources: ArtifactResourceScope;readonly root: string;readonly rootIdentity: BigIntStats;readonly signal?: AbortSignal;@@ -85,6 +92,7 @@ export type TraversalState = {};export type StableFileRequest = {+ readonly resources: ArtifactResourceScope;readonly root: string;readonly rootIdentity: BigIntStats;readonly absolute: string;diff --git a/tests/boundary/cli/cliStartupImports.test.ts b/tests/boundary/cli/cliStartupImports.test.tsindex c084b6212..9181bf7e3 100644--- a/tests/boundary/cli/cliStartupImports.test.ts+++ b/tests/boundary/cli/cliStartupImports.test.ts@@ -62,7 +62,7 @@ describe("CLI startup imports", () => {await expect(resolvedPackages(evaluate(- `const { readReferenceSourceVcs } = await import("./dist/application/ReferenceSourceVcsAdapter.js"); await readReferenceSourceVcs(${JSON.stringify(source)});`,+ `const { readReferenceSourceVcs } = await import("./dist/application/ReferenceSourceVcsAdapter.js"); const { ArtifactResourceScope } = await import("./dist/artifacts/ArtifactResourceScope.js"); const resources = new ArtifactResourceScope(); try { await readReferenceSourceVcs(${JSON.stringify(source)}, resources); } finally { await resources.close(); }`,),),).resolves.toContain("isomorphic-git");diff --git a/tests/boundary/cli/referenceSourceImportStatus.test.ts b/tests/boundary/cli/referenceSourceImportStatus.test.tsindex c15a1fe63..4c971899c 100644--- a/tests/boundary/cli/referenceSourceImportStatus.test.ts+++ b/tests/boundary/cli/referenceSourceImportStatus.test.ts@@ -6,18 +6,12 @@ import { describe, expect } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { cliTest } from "../../support/cli/cliFixture.js";-const invalidRootOutput = {- error: "Import failed",- category: "invalid_input",- message:- "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",-};-const unsupportedHostOutput = {error: "Import failed",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.",+ message: expect.stringContaining(+ "Safe no-follow file opens are unavailable on this host.",+ ),};const permissionChecksUnavailable =@@ -105,6 +99,15 @@ describe("compiled reference-source import preflight failures", () => {...(scenario.logging ? { REA_LOG_LEVEL: "info" } : {}),},});+ const rootReason =+ scenario.rootKind === "missing"+ ? "Reference source root could not be resolved"+ : "Reference source root is not a directory";+ const invalidRootOutput = {+ error: "Import failed",+ category: "invalid_input",+ message: expect.stringContaining(rootReason),+ };if (scenario.fullOutput) {// Incur's legacy wrapper remains unchanged; operation status is// conveyed by the exit code and command log, not this `ok` field.@@ -113,8 +116,12 @@ describe("compiled reference-source import preflight failures", () => {data: invalidRootOutput,});} else {- expect(result.json).toEqual(invalidRootOutput);+ expect(result.json).toMatchObject(invalidRootOutput);}+ expect(JSON.stringify(result.json)).toContain(+ "Check that the path exists, is readable, and points to a directory.",+ );+ expect(JSON.stringify(result.json)).toContain(root);expect.soft(result.exitCode).toBe(1);if (scenario.logging) {const records: unknown[] = result.stderr@@ -157,12 +164,15 @@ describe("compiled reference-source import preflight failures", () => {XDG_CACHE_HOME: directory,},});- expect(result.json).toEqual({+ expect(result.json).toMatchObject({error: "Import failed",category: "execution_failure",- message:- "Reference source files could not be read. Check directory permissions and try again.",+ message: expect.stringContaining("EACCES: permission denied"),});+ expect(JSON.stringify(result.json)).toContain(root);+ expect(JSON.stringify(result.json)).toContain(+ "Check directory permissions and try again.",+ );expect(result.exitCode).toBe(1);} finally {await chmod(parent, 0o700);diff --git a/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts b/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.tsnew file mode 100644index 000000000..815402ad5--- /dev/null+++ b/tests/boundary/filesystem/referenceSourceCleanupOwnership.test.ts@@ -0,0 +1,304 @@+import {+ mkdir,+ open as fsOpen,+ opendir as fsOpendir,+ writeFile,+} from "node:fs/promises";+import { join } from "node:path";++import { afterEach, beforeEach, expect, it, onTestFinished, vi } from "vitest";++import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";+import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";+import { readReferenceSource } from "../../../src/reference/ReferenceSourceReader.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ open: vi.fn(actual.open),+ opendir: vi.fn(actual.opendir),+ };+});++const openMock = vi.mocked(fsOpen);+const opendirMock = vi.mocked(fsOpendir);+let actual: typeof import("node:fs/promises");++beforeEach(async () => {+ actual =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ openMock.mockImplementation((...args) => actual.open(...args));+ opendirMock.mockImplementation((...args) => actual.opendir(...args));+});++afterEach(() => {+ openMock.mockReset();+ opendirMock.mockReset();+});++it("preserves admission EIO and retains an invalidated failed-close owner", async () => {+ const root = await createTestTempDirectory("rea-reference-admission-owner-");+ const file = join(root, "source.ts");+ await writeFile(file, "export const answer = 42;\n");+ const resources = new ArtifactResourceScope();+ onTestFinished(() => resources.close().catch(() => undefined));+ const statFailure = Object.assign(new Error("injected admission EIO"), {+ code: "EIO",+ });+ const closeFailure = new Error("native close rejected after invalidation");+ let closeCalls = 0;++ openMock.mockImplementation(async (...args) => {+ const handle = await actual.open(...args);+ vi.spyOn(handle, "stat").mockRejectedValueOnce(statFailure);+ const close = handle.close.bind(handle);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ closeCalls += 1;+ await close();+ throw closeFailure;+ });+ return handle;+ });++ const result = await readReferenceSource(root, resources);+ expect(result).toMatchObject({+ ok: false,+ error: {+ tag: "reference-source-reader",+ code: "io",+ message: expect.stringContaining("EIO"),+ cleanup: {+ resources: [file],+ reason: expect.stringContaining(closeFailure.message),+ },+ partial: {+ entries: [+ {+ status: "failed",+ kind: "file",+ path: "source.ts",+ code: "io",+ message: expect.stringContaining("EIO"),+ },+ ],+ },+ },+ });+ expect(closeCalls).toBe(1);++ await expect(resources.close()).rejects.toMatchObject({+ cleanup: {+ resources: [file],+ reason: expect.stringContaining(closeFailure.message),+ },+ });+ expect(closeCalls).toBe(1);+});++it("retains partial file bytes and retries the same live owner before new work", async () => {+ const root = await createTestTempDirectory("rea-reference-file-owner-");+ const file = join(root, "source.ts");+ const bytes = "export const answer = 'retained';\n";+ await writeFile(file, bytes);+ const resources = new ArtifactResourceScope();+ const closeFailure = new Error("injected close before native close");+ let allowClose = false;+ onTestFinished(async () => {+ allowClose = true;+ await resources.close().catch(() => undefined);+ });+ let closeCalls = 0;+ let openCalls = 0;++ openMock.mockImplementation(async (...args) => {+ openCalls += 1;+ const handle = await actual.open(...args);+ const close = handle.close.bind(handle);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ closeCalls += 1;+ if (!allowClose) throw closeFailure;+ await close();+ });+ return handle;+ });++ const first = await importReferenceSource(+ {+ root,+ caller: "reference-source-cleanup-owner-test",+ policy: { secretPatterns: [] },+ },+ resources,+ );+ expect(first).toMatchObject({+ ok: false,+ error: {+ code: "io",+ cleanup: {+ resources: [file],+ reason: expect.stringContaining(closeFailure.message),+ },+ partial: {+ entries: [+ {+ status: "read",+ kind: "file",+ path: "source.ts",+ bytes: Buffer.from(bytes),+ },+ ],+ bytesRead: Buffer.byteLength(bytes),+ },+ },+ });+ expect(openCalls).toBe(1);+ expect(closeCalls).toBe(1);++ const blocked = await readReferenceSource(root, resources);+ expect(blocked).toMatchObject({+ ok: false,+ error: {+ code: "io",+ cleanup: { resources: [file] },+ },+ });+ expect(openCalls).toBe(1);+ expect(closeCalls).toBe(2);++ allowClose = true;+ await resources.close();+ expect(openCalls).toBe(1);+ expect(closeCalls).toBe(3);+});++it("preserves a directory read failure when closing that directory also fails", async () => {+ const root = await createTestTempDirectory(+ "rea-reference-directory-read-owner-",+ );+ const file = join(root, "source.ts");+ const bytes = "observed before directory EIO\n";+ await writeFile(file, bytes);+ const resources = new ArtifactResourceScope();+ onTestFinished(() => resources.close().catch(() => undefined));+ const readFailure = Object.assign(new Error("injected directory EIO"), {+ code: "EIO",+ });+ const closeFailure = new Error("directory close rejected after invalidation");+ let readCalls = 0;+ let closeCalls = 0;++ opendirMock.mockImplementation(async (...args) => {+ const directory = await actual.opendir(...args);+ const read = directory.read.bind(directory);+ vi.spyOn(directory, "read").mockImplementation(async () => {+ if (readCalls++ > 0) throw readFailure;+ return read();+ });+ const close = directory.close.bind(directory);+ vi.spyOn(directory, "close").mockImplementation(async () => {+ closeCalls += 1;+ await close();+ throw closeFailure;+ });+ return directory;+ });++ const result = await readReferenceSource(root, resources);+ if (result.ok) throw new Error("Directory and cleanup failures were ignored");+ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "io",+ message: expect.stringContaining(readFailure.message),+ cleanup: {+ resources: [root],+ reason: expect.stringContaining(closeFailure.message),+ },+ partial: {+ bytesRead: Buffer.byteLength(bytes),+ },+ },+ });+ expect(result.error.partial?.entries).toContainEqual(+ expect.objectContaining({+ status: "read",+ kind: "file",+ path: "source.ts",+ bytes: Buffer.from(bytes),+ }),+ );+ expect(result.error.partial?.entries).toContainEqual({+ status: "failed",+ kind: "directory",+ path: ".",+ code: "io",+ message: expect.stringContaining(readFailure.message),+ });+ expect(closeCalls).toBe(1);++ await expect(resources.close()).rejects.toMatchObject({+ cleanup: {+ resources: [root],+ reason: expect.stringContaining(closeFailure.message),+ },+ });+ expect(closeCalls).toBe(1);+});++it("keeps cancelled traversal typed when native directory close rejects after invalidation", async () => {+ const root = await createTestTempDirectory("rea-reference-directory-owner-");+ await mkdir(join(root, "child"));+ const resources = new ArtifactResourceScope();+ onTestFinished(() => resources.close().catch(() => undefined));+ const controller = new AbortController();+ const closeFailure = new Error("native directory close rejected");+ let closeCalls = 0;+ let openedPath: string | undefined;++ opendirMock.mockImplementation(async (...args) => {+ const directory = await actual.opendir(...args);+ openedPath = String(args[0]);+ const read = directory.read.bind(directory);+ vi.spyOn(directory, "read").mockImplementation(async () => {+ const child = await read();+ if (child !== null) controller.abort();+ return child;+ });+ const close = directory.close.bind(directory);+ vi.spyOn(directory, "close").mockImplementation(async () => {+ closeCalls += 1;+ await close();+ throw closeFailure;+ });+ return directory;+ });++ const result = await readReferenceSource(root, resources, {+ signal: controller.signal,+ });+ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "cancelled",+ cleanup: {+ resources: [root],+ reason: expect.stringContaining(closeFailure.message),+ },+ partial: { entries: [] },+ },+ });+ expect(openedPath).toBe(root);+ expect(closeCalls).toBe(1);++ await expect(resources.close()).rejects.toMatchObject({+ cleanup: {+ resources: [root],+ reason: expect.stringContaining(closeFailure.message),+ },+ });+ expect(closeCalls).toBe(1);+});diff --git a/tests/boundary/filesystem/referenceSourceComputedRequire.test.ts b/tests/boundary/filesystem/referenceSourceComputedRequire.test.tsindex c478e6391..ff95c1951 100644--- a/tests/boundary/filesystem/referenceSourceComputedRequire.test.ts+++ b/tests/boundary/filesystem/referenceSourceComputedRequire.test.ts@@ -6,8 +6,8 @@ import { promisify } from "node:util";import { expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it("distinguishes computed require member values from literal members in source evidence", async () => {const root = await createTestTempDirectory("rea-reference-require-members-");diff --git a/tests/boundary/filesystem/referenceSourceDockerfileLanguage.test.ts b/tests/boundary/filesystem/referenceSourceDockerfileLanguage.test.tsindex 56fe1ff86..ea8d1ac59 100644--- a/tests/boundary/filesystem/referenceSourceDockerfileLanguage.test.ts+++ b/tests/boundary/filesystem/referenceSourceDockerfileLanguage.test.ts@@ -4,8 +4,8 @@ import { join } from "node:path";import { expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it("imports Dockerfile-prefixed TypeScript with ordinary source evidence and uncertainty", async () => {const root = await createTestTempDirectory("rea-dockerfile-language-");diff --git a/tests/boundary/filesystem/referenceSourceDynamicImports.test.ts b/tests/boundary/filesystem/referenceSourceDynamicImports.test.tsindex 432b7bf30..91eab7ec6 100644--- a/tests/boundary/filesystem/referenceSourceDynamicImports.test.ts+++ b/tests/boundary/filesystem/referenceSourceDynamicImports.test.ts@@ -3,8 +3,8 @@ import { join } from "node:path";import { expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it("resolves dynamic source imports while retaining computed targets as unknown", async () => {const root = await createTestTempDirectory("rea-reference-dynamic-import-");diff --git a/tests/boundary/filesystem/referenceSourceFailureDetails.test.ts b/tests/boundary/filesystem/referenceSourceFailureDetails.test.tsindex a17525e9e..dd87ea92a 100644--- a/tests/boundary/filesystem/referenceSourceFailureDetails.test.ts+++ b/tests/boundary/filesystem/referenceSourceFailureDetails.test.ts@@ -5,9 +5,11 @@ import { promisify } from "node:util";import { describe, expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";-import { readReferenceSource } from "../../../src/reference/ReferenceSourceReader.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import {+ importReferenceSource,+ readReferenceSource,+} from "../../support/referenceSourceResourceScope.js";const importTree = (root: string) =>importReferenceSource({diff --git a/tests/boundary/filesystem/referenceSourceImport.test.ts b/tests/boundary/filesystem/referenceSourceImport.test.tsindex 3cebcf5b9..75eab7acb 100644--- a/tests/boundary/filesystem/referenceSourceImport.test.ts+++ b/tests/boundary/filesystem/referenceSourceImport.test.ts@@ -7,19 +7,13 @@ import { describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";-import {- importReferenceSource,- normalizeHistoricalSourceParseFailures,-} from "../../../src/application/ReferenceSourceImport.js";+import { normalizeHistoricalSourceParseFailures } from "../../../src/application/ReferenceSourceImport.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";import {parseReferenceSourceEntries,projectReferenceSourceEntryFailure,} from "../../../src/application/ReferenceSourceImportEntries.js";import type { ReferenceSourceRead } from "../../../src/reference/ReferenceSourceReaderTypes.js";-import {- projectReferenceSourceImportError,- type ReferenceSourceImportError,-} from "../../../src/application/ReferenceSourceImportTypes.js";import { createHistoricalSourceManifest } from "../../../src/domain/referenceSourceGraph.js";const fixture = async (parent: string, name: string): Promise<string> => {@@ -49,7 +43,7 @@ const importTree = (...(signal === undefined ? {} : { signal }),});-describe("reference source import error projection", () => {+describe("reference source import projections", () => {it("deduplicates exact parse failures without collapsing distinct reasons", () => {const malformed = {path: "src/main.ts",@@ -92,29 +86,6 @@ describe("reference source import error projection", () => {expect(message).toMatch(/Check|try again|when ready|Exclude/u);}});-- it("projects every import failure without raw parser or policy text", () => {- const expectedCategories = {- cancelled: "cancelled",- "invalid-root": "invalid_input",- unsupported: "unsupported_host",- io: "execution_failure",- parse: "execution_failure",- } as const;- for (const [code, category] of Object.entries(expectedCategories)) {- const projected = projectReferenceSourceImportError({- tag: "reference-source-import",- code: code as ReferenceSourceImportError["code"],- message: "SECRET parser stack and /private/path",- });- expect(projected.category).toBe(category);- expect(projected.message).not.toContain("SECRET");- expect(projected.message).not.toContain("/private/path");- expect(projected.message).toMatch(- /try again|when ready|Check that|REA on Linux/u,- );- }- });});describe("reference source symlink import", () => {diff --git a/tests/boundary/filesystem/referenceSourceMetadataCleanup.test.ts b/tests/boundary/filesystem/referenceSourceMetadataCleanup.test.tsnew file mode 100644index 000000000..615dbf617--- /dev/null+++ b/tests/boundary/filesystem/referenceSourceMetadataCleanup.test.ts@@ -0,0 +1,226 @@+import { mkdir, open as fsOpen, writeFile } from "node:fs/promises";+import { join, resolve } from "node:path";++import { afterEach, beforeEach, expect, it, onTestFinished, vi } from "vitest";++import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";+import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";+import { readReferenceSourceVcs } from "../../../src/application/ReferenceSourceVcsAdapter.js";+import { execFileOutput } from "../../../src/process/ExecFileOutput.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return { ...actual, open: vi.fn(actual.open) };+});++const openMock = vi.mocked(fsOpen);+let actual: typeof import("node:fs/promises");++beforeEach(async () => {+ actual =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ openMock.mockImplementation((...args) => actual.open(...args));+});++afterEach(() => openMock.mockReset());++const failCloseUntilAllowed = (+ target: string,+): { readonly allow: () => void; readonly calls: () => number } => {+ const closeFailure = new Error("injected metadata close failure");+ let allowClose = false;+ let closeCalls = 0;+ openMock.mockImplementation(async (...args) => {+ const handle = await actual.open(...args);+ if (resolve(String(args[0])) !== resolve(target)) return handle;+ const close = handle.close.bind(handle);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ closeCalls += 1;+ if (!allowClose) throw closeFailure;+ await close();+ });+ return handle;+ });+ return {+ allow: () => {+ allowClose = true;+ },+ calls: () => closeCalls,+ };+};++it("retains failed .gitignore cleanup under the caller's scope", async () => {+ const root = await createTestTempDirectory("rea-reference-ignore-owner-");+ const path = join(root, ".gitignore");+ await writeFile(path, "generated/\n");+ const resources = new ArtifactResourceScope();+ const close = failCloseUntilAllowed(path);+ onTestFinished(async () => {+ close.allow();+ await resources.close().catch(() => undefined);+ });++ const result = await importReferenceSource(+ {+ root,+ caller: "reference-source-metadata-cleanup-test",+ policy: { secretPatterns: [] },+ },+ resources,+ );+ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "io",+ cleanup: {+ resources: [path],+ reason: expect.stringContaining("injected metadata close failure"),+ },+ },+ });+ expect(close.calls()).toBe(2);++ close.allow();+ await resources.close();+ expect(close.calls()).toBe(3);+});++it("preserves Git metadata cleanup failure and the completed source read", async () => {+ const root = await createTestTempDirectory("rea-reference-head-owner-");+ const repository = join(root, "repository");+ const sourceRoot = join(root, "source");+ await Promise.all([mkdir(repository), mkdir(sourceRoot)]);+ await execFileOutput("git", ["init", "--initial-branch=main"], {+ cwd: repository,+ });+ const source = join(sourceRoot, "main.ts");+ const bytes = "export const value = 1;\n";+ await writeFile(source, bytes);+ await writeFile(join(sourceRoot, ".git"), "gitdir: ../repository/.git\n");+ const head = join(sourceRoot, ".git");+ const resources = new ArtifactResourceScope();+ const close = failCloseUntilAllowed(head);+ onTestFinished(async () => {+ close.allow();+ await resources.close().catch(() => undefined);+ });++ const result = await importReferenceSource(+ {+ root: sourceRoot,+ excludePaths: [".git"],+ caller: "reference-source-metadata-cleanup-test",+ policy: { secretPatterns: [] },+ },+ resources,+ );+ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "io",+ cleanup: {+ resources: [head],+ reason: expect.stringContaining("injected metadata close failure"),+ },+ partial: {+ entries: [+ {+ kind: "file",+ path: "main.ts",+ bytes: Buffer.from(bytes),+ },+ ],+ },+ },+ });+ expect(close.calls()).toBe(2);++ close.allow();+ await resources.close();+ expect(close.calls()).toBe(3);+});++it("retains later packed-ref cleanup after an earlier loose-ref read failure", async () => {+ const root = await createTestTempDirectory("rea-reference-packed-owner-");+ await execFileOutput("git", ["init", "--initial-branch=main"], { cwd: root });+ await writeFile(join(root, "main.ts"), "export const value = 1;\n");+ await execFileOutput(+ "git",+ [+ "-c",+ "user.name=REA fixture",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "commit",+ "--allow-empty",+ "-m",+ "fixture",+ ],+ { cwd: root },+ );+ const head = (+ await execFileOutput("git", ["rev-parse", "HEAD"], { cwd: root })+ ).stdout.trim();+ await execFileOutput("git", ["pack-refs", "--all", "--prune"], { cwd: root });+ const looseRef = join(root, ".git", "refs", "heads", "main");+ const packedRefs = join(root, ".git", "packed-refs");+ await actual.mkdir(join(root, ".git", "refs", "heads"), { recursive: true });+ await writeFile(looseRef, `${head}\n`);++ const resources = new ArtifactResourceScope();+ let allowClose = false;+ let looseReadFailed = false;+ const packedCloseCalls = new Map<object, number>();+ openMock.mockImplementation(async (...args) => {+ const handle = await actual.open(...args);+ const path = resolve(String(args[0]));+ if (path === resolve(looseRef)) {+ vi.spyOn(handle, "read").mockImplementation(async () => {+ looseReadFailed = true;+ throw Object.assign(new Error("injected loose ref EIO"), {+ code: "EIO",+ });+ });+ }+ if (path === resolve(packedRefs)) {+ const close = handle.close.bind(handle);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ packedCloseCalls.set(handle, (packedCloseCalls.get(handle) ?? 0) + 1);+ if (!allowClose) throw new Error("injected packed-refs close failure");+ await close();+ });+ }+ return handle;+ });+ onTestFinished(async () => {+ allowClose = true;+ await resources.close().catch(() => undefined);+ });++ const result = await readReferenceSourceVcs(root, resources);+ expect(looseReadFailed).toBe(true);+ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "io",+ cleanup: {+ resources: [packedRefs],+ reason: expect.stringContaining("injected packed-refs close failure"),+ },+ },+ });+ expect([...packedCloseCalls.values()]).toEqual(+ Array.from({ length: packedCloseCalls.size }, () => 2),+ );++ allowClose = true;+ await resources.close();+ expect([...packedCloseCalls.values()]).toEqual(+ Array.from({ length: packedCloseCalls.size }, () => 3),+ );+});diff --git a/tests/boundary/filesystem/referenceSourceReader.test.ts b/tests/boundary/filesystem/referenceSourceReader.test.tsindex 59be7f8f0..606d2fef9 100644--- a/tests/boundary/filesystem/referenceSourceReader.test.ts+++ b/tests/boundary/filesystem/referenceSourceReader.test.ts@@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";-import { readReferenceSource } from "../../../src/reference/ReferenceSourceReader.js";+import { readReferenceSource } from "../../support/referenceSourceResourceScope.js";describe("readReferenceSource entries", () => {it("returns explicit entries in canonical code-point path order", async () => {@@ -158,12 +158,17 @@ describe("readReferenceSource failures and exclusions", () => {},});- expect(result).toEqual({+ expect(result).toMatchObject({ok: false,error: {tag: "reference-source-reader",code: "io",message: "Reference source exclusion check failed",+ partial: {+ root,+ entries: [],+ bytesRead: 0,+ },},});});diff --git a/tests/boundary/filesystem/referenceSourceRecovery.test.ts b/tests/boundary/filesystem/referenceSourceRecovery.test.tsindex 5b9f6ad45..3eea3ecaa 100644--- a/tests/boundary/filesystem/referenceSourceRecovery.test.ts+++ b/tests/boundary/filesystem/referenceSourceRecovery.test.ts@@ -4,12 +4,10 @@ import { join } from "node:path";import { expect, it } from "vitest";-import {- importReferenceSource,- normalizeHistoricalSourceParseFailures,-} from "../../../src/application/ReferenceSourceImport.js";+import { normalizeHistoricalSourceParseFailures } from "../../../src/application/ReferenceSourceImport.js";import { historicalSourceGraphSchema } from "../../../src/domain/referenceSourceGraph.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";const sources = {"fatal.js": 'import "./valid";\nconst = ;',diff --git a/tests/boundary/filesystem/referenceSourceTestFilenames.test.ts b/tests/boundary/filesystem/referenceSourceTestFilenames.test.tsindex 9bc174d9c..54a4955e3 100644--- a/tests/boundary/filesystem/referenceSourceTestFilenames.test.ts+++ b/tests/boundary/filesystem/referenceSourceTestFilenames.test.ts@@ -4,8 +4,8 @@ import { join } from "node:path";import { expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it("imports test-suffixed filenames with unchanged paths, hashes, and languages", async () => {const root = await createTestTempDirectory("rea-reference-test-filenames-");diff --git a/tests/boundary/filesystem/referenceSourceTypeScriptExtensions.test.ts b/tests/boundary/filesystem/referenceSourceTypeScriptExtensions.test.tsindex c6ca51b16..d537a1dca 100644--- a/tests/boundary/filesystem/referenceSourceTypeScriptExtensions.test.ts+++ b/tests/boundary/filesystem/referenceSourceTypeScriptExtensions.test.ts@@ -3,8 +3,8 @@ import { join } from "node:path";import { expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it.each([["main.ts", "dep.js", "dep.ts"],diff --git a/tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts b/tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.tsindex 545025f57..ec868052b 100644--- a/tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts+++ b/tests/boundary/filesystem/referenceSourceUnreadableDirectories.test.ts@@ -3,9 +3,11 @@ import { join } from "node:path";import { describe, expect, it } from "vitest";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";-import { readReferenceSource } from "../../../src/reference/ReferenceSourceReader.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import {+ importReferenceSource,+ readReferenceSource,+} from "../../support/referenceSourceResourceScope.js";const importTree = (root: string) =>importReferenceSource({diff --git a/tests/boundary/filesystem/referenceSourceVcs.test.ts b/tests/boundary/filesystem/referenceSourceVcs.test.tsindex 3ce919f8e..dbfa9ff2b 100644--- a/tests/boundary/filesystem/referenceSourceVcs.test.ts+++ b/tests/boundary/filesystem/referenceSourceVcs.test.ts@@ -2,9 +2,17 @@ import { mkdir, writeFile } from "node:fs/promises";import { join } from "node:path";import { expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { withArtifactResourceScope } from "../../fixtures/artifactInventory.js";import { execFileOutput } from "../../../src/process/ExecFileOutput.js";import { readReferenceSourceVcs } from "../../../src/application/ReferenceSourceVcsAdapter.js";+const readVcs = (root: string, signal?: AbortSignal) =>+ withArtifactResourceScope(async (resources) => {+ const result = await readReferenceSourceVcs(root, resources, signal);+ if (!result.ok) throw result.error;+ return result.value;+ });+it("reads a linked worktree's own branch and detached HEAD through shared Git refs", async () => {const root = await createTestTempDirectory("rea-reference-worktree-");const repository = join(root, "repository");@@ -49,18 +57,18 @@ it("reads a linked worktree's own branch and detached HEAD through shared Git reawait execFileOutput("git", ["rev-parse", "HEAD"], { cwd: linked })).stdout.trim();expect(linkedHead).not.toBe(mainHead);- expect(await readReferenceSourceVcs(repository)).toEqual({+ expect(await readVcs(repository)).toEqual({kind: "git",head: mainHead,dirty: null,});- expect(await readReferenceSourceVcs(linked)).toEqual({+ expect(await readVcs(linked)).toEqual({kind: "git",head: linkedHead,dirty: null,});await git("pack-refs", "--all", "--prune");- expect(await readReferenceSourceVcs(linked)).toEqual({+ expect(await readVcs(linked)).toEqual({kind: "git",head: linkedHead,dirty: null,@@ -68,7 +76,7 @@ it("reads a linked worktree's own branch and detached HEAD through shared Git reawait execFileOutput("git", ["checkout", "--detach", mainHead], {cwd: linked,});- expect(await readReferenceSourceVcs(linked)).toEqual({+ expect(await readVcs(linked)).toEqual({kind: "git",head: mainHead,dirty: null,@@ -79,7 +87,7 @@ it("reads a linked worktree's own branch and detached HEAD through shared Git rejoin(relativePointer, ".git"),"gitdir: ../repository/.git\r\n",);- expect(await readReferenceSourceVcs(relativePointer)).toEqual({+ expect(await readVcs(relativePointer)).toEqual({kind: "git",head: mainHead,dirty: null,@@ -87,14 +95,14 @@ it("reads a linked worktree's own branch and detached HEAD through shared Git re// A non-regular loose ref must remain unknown even when packed-refs has// a readable value. The library's promise-API probe is not a source failure.await mkdir(join(repository, ".git", "refs", "heads", "main"));- expect(await readReferenceSourceVcs(repository)).toEqual({+ expect(await readVcs(repository)).toEqual({kind: "unknown",head: null,dirty: null,});const controller = new AbortController();controller.abort();- expect(await readReferenceSourceVcs(linked, controller.signal)).toEqual({+ expect(await readVcs(linked, controller.signal)).toEqual({kind: "unknown",head: null,dirty: null,diff --git a/tests/boundary/filesystem/sourceToBundlePaths.test.ts b/tests/boundary/filesystem/sourceToBundlePaths.test.tsindex 50e39000e..19aa07a1a 100644--- a/tests/boundary/filesystem/sourceToBundlePaths.test.ts+++ b/tests/boundary/filesystem/sourceToBundlePaths.test.ts@@ -4,11 +4,11 @@ import { expect, it } from "vitest";import { analyzeJavaScriptApplication } from "../../support/javascriptApplicationScope.js";import { parseApplicationGraphEvidence } from "../../../src/application/javascript/JavaScriptApplicationEvidenceGraph.js";-import { importReferenceSource } from "../../../src/application/ReferenceSourceImport.js";import { findApplicationFeatureSeeds } from "../../../src/domain/javascript/javascriptFeatureSeed.js";import { compareSourceToBundle } from "../../../src/domain/javascript/sourceToBundleComparison.js";import { resolveSourceMapSource } from "../../../src/javascript/sourceMaps/DecodedSourceMap.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { importReferenceSource } from "../../support/referenceSourceResourceScope.js";it("keeps literal hash characters in historical/current filesystem paths", async () => {const root = await createTestTempDirectory("rea-source-path-");diff --git a/tests/fixtures/referenceReaderFifoProbe.mjs b/tests/fixtures/referenceReaderFifoProbe.mjsindex a8f785648..026661bb7 100644--- a/tests/fixtures/referenceReaderFifoProbe.mjs+++ b/tests/fixtures/referenceReaderFifoProbe.mjs@@ -9,23 +9,33 @@ if (modulePath === undefined || root === undefined)throw new Error("Reference reader FIFO probe requires module and root paths");const { readStableFile } = await import(pathToFileURL(modulePath));-const absolute = join(root, "source.txt");-await writeFile(absolute, "observed regular file\n");-const expected = await lstat(absolute, { bigint: true });-await unlink(absolute);-execFileSync("mkfifo", [absolute]);+const { ArtifactResourceScope } = await import(+ new URL("../artifacts/ArtifactResourceScope.js", pathToFileURL(modulePath))+);+const resources = new ArtifactResourceScope();+try {+ const absolute = join(root, "source.txt");+ await writeFile(absolute, "observed regular file\n");+ const expected = await lstat(absolute, { bigint: true });+ await unlink(absolute);+ execFileSync("mkfifo", [absolute]);-// Capture the directory after replacement to reach the file-open boundary.-// The owning test bounds this child if an O_RDONLY FIFO open blocks again.-const rootIdentity = await lstat(root, { bigint: true });-const result = await readStableFile({- root,- rootIdentity,- absolute,- path: "source.txt",- expected,-});-assert.equal(result.status, "failed");-assert.equal(result.kind, "file");-assert.equal(result.code, "changed");+ // Capture the directory after replacement to reach the file-open boundary.+ // The owning test bounds this child if an O_RDONLY FIFO open blocks again.+ const rootIdentity = await lstat(root, { bigint: true });+ const result = await readStableFile({+ resources,+ root,+ rootIdentity,+ absolute,+ path: "source.txt",+ expected,+ });+ assert.equal(result.cleanup, undefined);+ assert.equal(result.entry.status, "failed");+ assert.equal(result.entry.kind, "file");+ assert.equal(result.entry.code, "changed");+} finally {+ await resources.close();+}process.stdout.write("changed\n");diff --git a/tests/support/referenceSourceResourceScope.ts b/tests/support/referenceSourceResourceScope.tsnew file mode 100644index 000000000..83557b647--- /dev/null+++ b/tests/support/referenceSourceResourceScope.ts@@ -0,0 +1,16 @@+import { importReferenceSource as importOwned } from "../../src/application/ReferenceSourceImport.js";+import type { ReferenceSourceImportOptions } from "../../src/application/ReferenceSourceImportTypes.js";+import { readReferenceSource as readOwned } from "../../src/reference/ReferenceSourceReader.js";+import type { ReferenceSourceReaderOptions } from "../../src/reference/ReferenceSourceReaderTypes.js";+import { withArtifactResourceScope } from "../fixtures/artifactInventory.js";++/** Run one reference-source test operation with an awaited resource owner. */+export const importReferenceSource = (options: ReferenceSourceImportOptions) =>+ withArtifactResourceScope((resources) => importOwned(options, resources));++/** Read one reference-source test tree with an awaited resource owner. */+export const readReferenceSource = (+ root: string,+ options: ReferenceSourceReaderOptions = {},+) =>+ withArtifactResourceScope((resources) => readOwned(root, resources, options));