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
+26 -3
View File
@@ -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 (