fix(reference)!: retain source and metadata cleanup owners

Require a caller-owned artifact resource scope for source traversal and Git metadata reads. Preserve cancellation, filesystem reasons, partial entries and bytes, and cleanup observations through import and the CLI. Transfer exact failed file owners at regular-file admission and close boundaries, including multiple failures encountered by Git reference resolution.

Validation: 169 focused tests passed across 26 files; two Windows-only cases skipped. Build, typecheck, lint, formatting, knip, architecture guards, discovery and docs checks passed.

BREAKING CHANGE: Reference source readers and imports require an ArtifactResourceScope. VCS metadata reads return Result, and CLI import failures include observed details and partial evidence.
This commit is contained in:
morluto
2026-10-11 06:10:10 +08:00
parent 215001a1ce
commit 53e7fadbd0
30 changed files with 1450 additions and 222 deletions
+166 -20
View File
@@ -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"));
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) {
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 };
} 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;