From eaa961658578522cecfbba7c7be1acf1c64da65a Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 15:19:18 +0800 Subject: [PATCH 1/7] fix(javascript): preserve cancellation through recovery publication cleanup --- src/javascript/recovery/WakaruProvider.ts | 12 +- .../wakaruPublicationCancellation.test.ts | 128 ++++++++++++++++++ 2 files changed, 138 insertions(+), 2 deletions(-) create mode 100644 tests/boundary/javascript-recovery/wakaruPublicationCancellation.test.ts diff --git a/src/javascript/recovery/WakaruProvider.ts b/src/javascript/recovery/WakaruProvider.ts index 88a51a74b..e25812663 100644 --- a/src/javascript/recovery/WakaruProvider.ts +++ b/src/javascript/recovery/WakaruProvider.ts @@ -9,7 +9,11 @@ import type { import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js"; import { SafeOutputTreeCreationFailure } from "../../artifacts/SafeOutputTreeCreationFailure.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisOutputError } from "../../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + AnalysisOutputError, +} from "../../domain/analysisErrorCore.js"; +import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; import { javascriptRecoveryResultSchema, type JavaScriptRecoveryInput, @@ -144,7 +148,11 @@ export class WakaruProvider implements JavaScriptRecoveryPort { failed = { cause }; } if (failed !== undefined) { - const failure = failed.cause; + const failure = + failed.cause instanceof ArtifactReaderFailure && + failed.cause.reason === "cancelled" + ? new AnalysisCancelledError(OPERATION, { cause: failed.cause }) + : failed.cause; const residuals: string[] = []; const cleanupFailures: { resource: string; reason: string }[] = []; const cleanupOwner = diff --git a/tests/boundary/javascript-recovery/wakaruPublicationCancellation.test.ts b/tests/boundary/javascript-recovery/wakaruPublicationCancellation.test.ts new file mode 100644 index 000000000..250e75623 --- /dev/null +++ b/tests/boundary/javascript-recovery/wakaruPublicationCancellation.test.ts @@ -0,0 +1,128 @@ +import { createHash } from "node:crypto"; +import { access, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { Readable } from "node:stream"; +import { expect, it, vi } from "vitest"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +const publicationCancellation = vi.hoisted(() => ({ + controller: undefined as AbortController | undefined, + directorySyncs: 0, +})); + +vi.mock("node:fs/promises", async (importOriginal) => { + const filesystem = await importOriginal(); + return { + ...filesystem, + open: async (...args: Parameters) => { + const handle = await filesystem.open(...args); + if (publicationCancellation.controller !== undefined) { + const stats = await handle.stat(); + if (stats.isDirectory()) { + const sync = handle.sync.bind(handle); + handle.sync = async () => { + await sync(); + publicationCancellation.directorySyncs += 1; + if (publicationCancellation.directorySyncs === 2) + publicationCancellation.controller?.abort(); + }; + } + } + return handle; + }, + }; +}); + +vi.mock( + "../../../src/javascript/recovery/WakaruCommand.js", + async (importOriginal) => { + const actual = + await importOriginal< + typeof import("../../../src/javascript/recovery/WakaruCommand.js") + >(); + return { + ...actual, + resolveWakaruCommand: async () => ({ + command: "/unused/wakaru", + limiter: "/unused/prlimit", + sha256: "a".repeat(64), + bytes: 1, + }), + }; + }, +); + +vi.mock( + "../../../src/javascript/recovery/WakaruExecution.js", + async (importOriginal) => { + const actual = + await importOriginal< + typeof import("../../../src/javascript/recovery/WakaruExecution.js") + >(); + const { createAnalysisExecution } = + await import("../../../src/application/AnalysisProvider.js"); + return { + ...actual, + prepareWakaruExecution: async ( + context: Parameters[0], + ) => { + const source = context.sources[0]; + if (source === undefined) throw new Error("Missing recovery source"); + const bytes = Buffer.from("module.exports = 42;"); + await context.tree.write("module.js", Readable.from([bytes]), { + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.byteLength, + }); + return createAnalysisExecution( + { status: "complete" }, + { id: "wakaru", name: "Wakaru", version: "1.14.0" }, + { + subject: { + path: source.path, + sha256: source.sha256, + format: "javascript", + }, + }, + ); + }, + }; + }, +); + +import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; +import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; +import { WakaruProvider } from "../../../src/javascript/recovery/WakaruProvider.js"; + +it.skipIf(process.platform === "win32")( + "keeps mid-commit output-tree cancellation typed through the provider", + async () => { + const root = await createTestTempDirectory("rea-wakaru-cancel-"); + const sourcePath = join(root, "source.js"); + const output = join(root, "output"); + await writeFile(sourcePath, "module.exports = 42;"); + const controller = new AbortController(); + publicationCancellation.controller = controller; + publicationCancellation.directorySyncs = 0; + const provider = new WakaruProvider({}); + try { + const result = await provider.recover( + { + path: sourcePath, + output_directory: output, + extraction_mode: "structural", + rewrite_level: "standard", + }, + { signal: controller.signal }, + ); + if (result.ok) throw new Error("Expected publication cancellation"); + expect(result.error).toBeInstanceOf(AnalysisCancelledError); + expect(projectAnalysisError(result.error).code).toBe("cancelled"); + expect(publicationCancellation.directorySyncs).toBe(2); + await expect(access(output)).rejects.toMatchObject({ code: "ENOENT" }); + } finally { + publicationCancellation.controller = undefined; + publicationCancellation.directorySyncs = 0; + await provider.close(); + } + }, +); From ed881c6d2ef6a8adba0c2a241ebc9ab4603b7868 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 15:23:56 +0800 Subject: [PATCH 2/7] fix(progress): measure delivery intervals with a monotonic clock --- src/application/ProgressReporter.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/application/ProgressReporter.ts b/src/application/ProgressReporter.ts index cf5ed7b7f..bb5a98f0d 100644 --- a/src/application/ProgressReporter.ts +++ b/src/application/ProgressReporter.ts @@ -23,7 +23,7 @@ export const createProgressReporter = ( } = {}, ): ProgressReporter => { const minimumIntervalMs = options.minimumIntervalMs ?? 100; - const now = options.now ?? Date.now; + const now = options.now ?? (() => performance.now()); let lastCompleted = -1; let lastSentAt = Number.NEGATIVE_INFINITY; let sequence = 0; From c923fb0dc9462e302b84a15770131ff899f89455 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 15:58:25 +0800 Subject: [PATCH 3/7] fix(javascript): retain compiler-dependent module resolution facts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Compare import and require outcomes for static TypeScript references when compiler options are unknown. Preserve branch facts through worker IR and both graph projections; retain declaration fallbacks as candidates without changing explicitly selected paths. Validation: 210 focused resolver and semantic tests; 21 production-boundary and source-extension tests. A bounded 2,000-reference probe adds about 16–17 ms wall time for dual resolution; full task token costs and real compiled application behavior remain unmeasured. --- docs/javascript-application-graph.md | 9 + .../ReferenceSourceImportEntries.ts | 6 +- .../TypeScriptEmittedSourceCandidates.ts | 12 +- .../javascript/JavaScriptArtifactAnalysis.ts | 7 +- .../JavaScriptArtifactGraphContext.ts | 6 +- .../JavaScriptArtifactGraphFindings.ts | 108 +++++++-- .../JavaScriptArtifactPathResolution.test.ts | 23 +- .../JavaScriptArtifactPathResolution.ts | 209 ++++++++++++++---- .../JavaScriptModuleRelationships.ts | 29 ++- .../javascriptAnalysisWorkerProcess.ts | 4 +- .../javascriptModuleResolutionMode.ts | 23 ++ .../javascript/javascriptSemanticAnalysis.ts | 14 +- src/domain/javascript/javascriptSemanticIr.ts | 5 +- .../javascriptSemanticProjection.ts | 15 +- .../javascript/javascriptSemanticReturns.ts | 4 +- .../javascript/javascriptSemanticState.ts | 3 +- .../JavaScriptAnalysisWorkerSchemas.ts | 8 +- .../javascriptModuleRelationships.test.ts | 118 +++++++++- 18 files changed, 503 insertions(+), 100 deletions(-) create mode 100644 src/domain/javascript/javascriptModuleResolutionMode.ts diff --git a/docs/javascript-application-graph.md b/docs/javascript-application-graph.md index 2290491a5..48e17bf44 100644 --- a/docs/javascript-application-graph.md +++ b/docs/javascript-application-graph.md @@ -104,6 +104,15 @@ static inferences. Dynamic or ambiguous IPC is retained without a pairing edge. Runtime entities retain passive-CDP authority, while a successful static/runtime correspondence is a separately identified cross-layer inference. +Source module links retain their resolution mode. Static imports in `.ts` and +`.tsx` are `compiler-dependent` when compiler options have not been retained. +REA compares Node import and require resolution: a shared outcome remains +available with a limitation; divergent outcomes remain unavailable with both +conditional branches and their limitations. This models source relationships, +not verified emitted code or execution. A declaration file found only through +an emitted-extension fallback is retained as a candidate, not a runtime target; +an explicitly selected path keeps its original identity. + ## Evidence and authority Every observation and edge carries all of the following: diff --git a/src/application/ReferenceSourceImportEntries.ts b/src/application/ReferenceSourceImportEntries.ts index a6e962118..36dae9949 100644 --- a/src/application/ReferenceSourceImportEntries.ts +++ b/src/application/ReferenceSourceImportEntries.ts @@ -104,7 +104,11 @@ const resolveInternalSpecifier = ( ]); // Retain present runtime files first; substitute only a missing counterpart. // Counterparts cover explicit filenames, not directory/index resolution. - candidates.push(...typescriptEmittedSourceCandidates(fromPath, normalized)); + candidates.push( + ...typescriptEmittedSourceCandidates(fromPath, normalized).map( + ({ path }) => path, + ), + ); const match = lookupPath.resolveCandidates(candidates); return match === undefined ? { to: normalized, resolution: "unresolved" } diff --git a/src/application/TypeScriptEmittedSourceCandidates.ts b/src/application/TypeScriptEmittedSourceCandidates.ts index 663c7dada..0e7adf41c 100644 --- a/src/application/TypeScriptEmittedSourceCandidates.ts +++ b/src/application/TypeScriptEmittedSourceCandidates.ts @@ -8,6 +8,11 @@ const EMITTED_SUFFIXES: ReadonlyArray< [".jsx", [".tsx", ".d.ts"]], ]; +export interface TypeScriptEmittedSourceCandidate { + readonly path: string; + readonly kind: "implementation" | "declaration"; +} + /** * Return TypeScript source counterparts for an explicit emitted filename. * Callers retain exact runtime-file precedence and must not use these for @@ -16,7 +21,7 @@ const EMITTED_SUFFIXES: ReadonlyArray< export const typescriptEmittedSourceCandidates = ( sourcePath: string, candidate: string, -): readonly string[] => { +): readonly TypeScriptEmittedSourceCandidate[] => { if (!/\.(?:ts|tsx|mts|cts)$/u.test(sourcePath)) return []; const emitted = EMITTED_SUFFIXES.find(([suffix]) => candidate.endsWith(suffix), @@ -25,5 +30,8 @@ export const typescriptEmittedSourceCandidates = ( // Strip the matched suffix by length. posix.extname would miss dotfile // names such as ".js", whose whole basename is the emitted suffix itself. const stem = candidate.slice(0, candidate.length - emitted[0].length); - return emitted[1].map((suffix) => `${stem}${suffix}`); + return emitted[1].map((suffix) => ({ + path: `${stem}${suffix}`, + kind: suffix.startsWith(".d.") ? "declaration" : "implementation", + })); }; diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.ts b/src/application/javascript/JavaScriptArtifactAnalysis.ts index dd1a50488..e61d3ae94 100644 --- a/src/application/javascript/JavaScriptArtifactAnalysis.ts +++ b/src/application/javascript/JavaScriptArtifactAnalysis.ts @@ -1,6 +1,6 @@ import { createHash } from "node:crypto"; -import { moduleKindForJavaScriptReference } from "./JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; import { setImmediate } from "node:timers/promises"; import { resolveJavaScriptSourceMapReferences } from "../../domain/javascript/javascriptSourceMapPaths.js"; @@ -384,7 +384,10 @@ function* analyzeArtifactFileSteps< analysis.parse_status === "complete" || analysis.parse_status === "partial" ? yield* analyzeParsedJavaScriptSemanticsSteps( parsed, - moduleKindForJavaScriptReference(file.path, "static-import"), + moduleResolutionModeForJavaScriptReference( + file.path, + "static-import", + ), ) : null; const projected = diff --git a/src/application/javascript/JavaScriptArtifactGraphContext.ts b/src/application/javascript/JavaScriptArtifactGraphContext.ts index 8b0fed5f1..1779bdaae 100644 --- a/src/application/javascript/JavaScriptArtifactGraphContext.ts +++ b/src/application/javascript/JavaScriptArtifactGraphContext.ts @@ -66,6 +66,7 @@ export interface AstEdgeInput { /** Inferred static relationship edge values. */ export interface InferenceEdgeInput extends AstEdgeInput { + readonly limitations?: readonly string[]; readonly relation: | "imports" | "loads" @@ -162,6 +163,9 @@ export const addStaticInferenceEdge = ( range: input.range, operation: "map-static-relationship", coverage: input.coverage, + ...(input.limitations === undefined + ? {} + : { limitations: input.limitations }), }), }); }; @@ -347,7 +351,7 @@ export const resolveArtifactPath = ( specifier: string, sourcePath: string, files: ReadonlyMap, - moduleKind?: "import" | "require", + moduleKind?: "import" | "require" | "compiler-dependent", ): string | null => resolveArtifactPathByContext({ declaredPath: specifier, diff --git a/src/application/javascript/JavaScriptArtifactGraphFindings.ts b/src/application/javascript/JavaScriptArtifactGraphFindings.ts index 3e92ff1a4..0020ef577 100644 --- a/src/application/javascript/JavaScriptArtifactGraphFindings.ts +++ b/src/application/javascript/JavaScriptArtifactGraphFindings.ts @@ -12,7 +12,6 @@ import { javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, - resolveArtifactPath, selfReferenceOmissions, sourceNodeFor, type JavaScriptArtifactGraphContext, @@ -23,9 +22,11 @@ import { staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js"; import { - moduleKindForJavaScriptReference, + artifactPathResolutionProperties, resolveArtifactPathByContext, + type ArtifactPathResolution, } from "./JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; type StaticReference = JavaScriptStaticAnalysis["references"][number]; type StaticEndpoint = JavaScriptStaticAnalysis["endpoints"][number]; @@ -41,9 +42,12 @@ interface FindingInput { } interface ResolvedReference { - readonly path: string; - readonly file: JavaScriptArtifactFile; + readonly path: string | null; + readonly file: JavaScriptArtifactFile | null; readonly node: ApplicationNode; + readonly limitations: readonly string[]; + readonly resolutionStatus?: string; + readonly resolution?: ArtifactPathResolution; } /** Project imports, workers, roles, endpoints, storage, and source-map links. */ @@ -90,7 +94,7 @@ const addReference = ( const resolved = input.value.specifier === null ? null - : resolveReference(context, input.file.path, input.value); + : resolveReference(context, input.file.path, input.value, input.coverage); if (input.value.kind === "worker" || input.value.kind === "service-worker") { const worker = context.accumulator.addNode({ kind: input.value.kind === "worker" ? "worker" : "service-worker", @@ -126,7 +130,7 @@ const addReference = ( relation: "loads", properties: { kind: input.value.kind }, }); - if (resolved !== null) + if (resolved !== null && resolved.path !== null) addStaticInferenceEdge(context, { source: worker, target: resolved.node, @@ -135,6 +139,7 @@ const addReference = ( coverage: input.coverage, relation: "maps_to", properties: { resolved_path: resolved.path }, + limitations: resolved.limitations, }); return; } @@ -154,13 +159,25 @@ const addReference = ( file: input.file, range: input.value.location, coverage: input.coverage, - relation: resolved?.file.kind === "native-addon" ? "loads" : "imports", + relation: resolved?.file?.kind === "native-addon" ? "loads" : "imports", properties: { kind: input.value.kind, specifier: input.value.specifier, expression: input.value.expression, + resolution_mode: + input.value.kind === "static-import" || + input.value.kind === "dynamic-import" || + input.value.kind === "require" + ? moduleResolutionModeForJavaScriptReference( + input.file.path, + input.value.kind, + ) + : null, resolved_path: resolved?.path ?? null, + resolution_status: resolved?.resolutionStatus ?? null, + ...artifactPathResolutionProperties(resolved?.resolution), }, + ...(resolved === null ? {} : { limitations: resolved.limitations }), }); }; @@ -373,6 +390,7 @@ const resolveReference = ( context: JavaScriptArtifactGraphContext, sourcePath: string, reference: StaticReference, + coverage: JavaScriptArtifactGraphCoverage, ): ResolvedReference | null => { const specifier = reference.specifier; if (specifier === null) return null; @@ -392,30 +410,70 @@ const resolveReference = ( const file = context.filesByPath.get(sourcePath); return file === undefined ? null - : { path: `${sourcePath}#module:${specifier}`, file, node: module }; + : { + path: `${sourcePath}#module:${specifier}`, + file, + node: module, + limitations: [], + }; } // Worker scripts are URLs relative to the script, not module specifiers. - const path = isWorker + const resolution = isWorker ? resolveArtifactPathByContext({ declaredPath: specifier, sourcePath, context: "url-reference", files: context.filesByPath, - }).resolved_path - : resolveArtifactPath( - specifier, + }) + : resolveArtifactPathByContext({ + declaredPath: specifier, sourcePath, - context.filesByPath, - reference.kind === "require" || - reference.kind === "static-import" || - reference.kind === "dynamic-import" - ? moduleKindForJavaScriptReference(sourcePath, reference.kind) - : undefined, - ); - if (path === null) return null; + context: "module-specifier", + files: context.filesByPath, + ...("require" === reference.kind || + "static-import" === reference.kind || + "dynamic-import" === reference.kind + ? { + moduleKind: moduleResolutionModeForJavaScriptReference( + sourcePath, + reference.kind, + ), + } + : {}), + }); + const path = resolution.resolved_path; + if (path === null) { + if (isWorker) return null; + const source = context.filesByPath.get(sourcePath); + return source === undefined + ? null + : { + path: null, + file: null, + node: unresolvedReferenceNode( + context, + source, + reference, + coverage, + resolution, + ), + limitations: resolution.limitations, + resolutionStatus: resolution.resolution_status, + resolution, + }; + } const file = context.filesByPath.get(path); const node = context.fileNodes.get(path); - return file === undefined || node === undefined ? null : { path, file, node }; + return file === undefined || node === undefined + ? null + : { + path, + file, + node, + limitations: resolution.limitations, + resolutionStatus: resolution.resolution_status, + resolution, + }; }; const resolveBundlerChunkReference = ( @@ -453,7 +511,7 @@ const resolveBundlerChunkReference = ( const node = unique[0]; return node === undefined ? null - : { path: `${sourcePath}#chunk:${key}`, file, node }; + : { path: `${sourcePath}#chunk:${key}`, file, node, limitations: [] }; }; const unresolvedReferenceNode = ( @@ -461,6 +519,7 @@ const unresolvedReferenceNode = ( file: JavaScriptArtifactFile, reference: StaticReference, coverage: JavaScriptArtifactGraphCoverage, + resolution?: ArtifactPathResolution, ): ApplicationNode => context.accumulator.addNode({ kind: "javascript-module", @@ -477,6 +536,10 @@ const unresolvedReferenceNode = ( specifier: reference.specifier, expression: reference.expression, resolution: "unresolved", + ...(resolution === undefined + ? {} + : { resolution_status: resolution.resolution_status }), + ...artifactPathResolutionProperties(resolution), }, evidence: staticInferenceEvidence({ sha256: file.sha256, @@ -487,6 +550,7 @@ const unresolvedReferenceNode = ( confidence: "low", limitations: [ "The static reference could not be resolved within the inventoried artifact.", + ...(resolution?.limitations ?? []), ], }), }, diff --git a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts b/src/application/javascript/JavaScriptArtifactPathResolution.test.ts index 1a8713929..b746d7e97 100644 --- a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts +++ b/src/application/javascript/JavaScriptArtifactPathResolution.test.ts @@ -1890,21 +1890,40 @@ describe("TypeScript NodeNext emitted-extension resolution", () => { ).toMatchObject({ resolution_status: "resolved", resolved_path: target }); }, ); +}); + +describe("TypeScript declaration fallback ownership", () => { + const container = "container"; it.each([ ["./dep.js", "src/dep.d.ts"], ["./cfg.mjs", "src/cfg.d.mts"], ["./legacy.cjs", "src/legacy.d.cts"], ] as const)( - "resolves %s to a declaration counterpart", + "retains %s as compile-time evidence without inventing a runtime target", (specifier, target) => { const files = fileMap([ file("src/main.ts", container), file(target, container, "export const value = 1;"), ]); + for (const moduleKind of ["import", "require"] as const) { + expect( + resolve({ + declaredPath: specifier, + sourcePath: "src/main.ts", + context: "module-specifier", + moduleKind, + files, + }), + ).toMatchObject({ + resolution_status: "unavailable", + resolved_path: null, + candidate_path: target, + }); + } expect( resolve({ - declaredPath: specifier, + declaredPath: "./" + target.slice(4), sourcePath: "src/main.ts", context: "module-specifier", moduleKind: "import", diff --git a/src/application/javascript/JavaScriptArtifactPathResolution.ts b/src/application/javascript/JavaScriptArtifactPathResolution.ts index 3ea23ab11..cb29ab2a9 100644 --- a/src/application/javascript/JavaScriptArtifactPathResolution.ts +++ b/src/application/javascript/JavaScriptArtifactPathResolution.ts @@ -19,8 +19,13 @@ import { classifyPackageImportTargetString, lookupExactPackageImport, } from "../../domain/javascript/javascriptPackageImportAliases.js"; -import { typescriptEmittedSourceCandidates } from "../TypeScriptEmittedSourceCandidates.js"; +import { + typescriptEmittedSourceCandidates, + type TypeScriptEmittedSourceCandidate, +} from "../TypeScriptEmittedSourceCandidates.js"; import { isRelativeJavaScriptModuleSpecifier } from "../../domain/javascript/javascriptModuleSpecifier.js"; +import type { JavaScriptModuleResolutionMode } from "../../domain/javascript/javascriptModuleResolutionMode.js"; +import type { JsonValue } from "../../domain/jsonValue.js"; type ArtifactPathResolutionContext = | "package-entrypoint" @@ -39,6 +44,16 @@ interface ArtifactPathResolutionBase { readonly declared_path: string; readonly resolution_context: ArtifactPathResolutionContext; readonly limitations: readonly string[]; + readonly conditional_resolutions?: readonly ConditionalModuleResolution[]; + readonly candidate_path?: string; +} + +export interface ConditionalModuleResolution { + readonly mode: "import" | "require"; + readonly resolution_status: UnresolvedArtifactPathStatus | "resolved"; + readonly resolved_path: string | null; + readonly candidate_path?: string; + readonly limitations: readonly string[]; } /** Explicit outcome of artifact-confined path resolution. */ @@ -62,26 +77,13 @@ export interface ResolveArtifactPathInput { readonly files: ReadonlyMap; readonly htmlBaseHref?: string | null; /** Import/require semantics; runtime resource paths omit this provenance. */ - readonly moduleKind?: "import" | "require"; + readonly moduleKind?: JavaScriptModuleResolutionMode; } -/** Loader selected by a source-level JavaScript module reference. */ -export const moduleKindForJavaScriptReference = ( - sourcePath: string, - referenceKind: "static-import" | "dynamic-import" | "require", - resolutionMode?: "import" | "require", -): "import" | "require" => - resolutionMode ?? - (referenceKind === "require" || - (referenceKind === "static-import" && - posix.extname(sourcePath).toLowerCase() === ".cts") - ? "require" - : "import"); - /** Preserve an explicitly retained loader mode on graph relationships. */ export const moduleResolutionModeProperties = ( - mode: "import" | "require" | undefined, -): Readonly> => + mode: JavaScriptModuleResolutionMode | undefined, +): Readonly> => mode === undefined ? {} : { resolution_mode: mode }; const EXTENSIONS = [ @@ -110,43 +112,116 @@ interface PackageFileTarget { readonly url: URL; } -type CandidateResolution = - | { - readonly resolvedPath: string; - readonly status: "resolved"; - readonly limitations: readonly string[]; - } +type CandidateResolution = { + readonly limitations: readonly string[]; + readonly candidatePath?: string; + readonly conditionalResolutions?: readonly ConditionalModuleResolution[]; +} & ( + | { readonly resolvedPath: string; readonly status: "resolved" } | { readonly resolvedPath: null; readonly status: UnresolvedArtifactPathStatus; - readonly limitations: readonly string[]; /** A truthy package main failed, so Node must not try ancestor packages. */ readonly stopsAncestorLookup?: true; - }; + } +); /** Resolve one declaration while preserving its original input identity. */ export const resolveArtifactPathByContext = ( input: ResolveArtifactPathInput, ): ArtifactPathResolution => { const resolution = resolvePath(input); + const facts = { + declared_path: input.declaredPath, + resolution_context: input.context, + limitations: resolution.limitations, + ...(resolution.candidatePath === undefined + ? {} + : { candidate_path: resolution.candidatePath }), + ...(resolution.conditionalResolutions === undefined + ? {} + : { conditional_resolutions: resolution.conditionalResolutions }), + }; return resolution.status === "resolved" ? { - declared_path: input.declaredPath, - resolution_context: input.context, + ...facts, resolved_path: resolution.resolvedPath, resolution_status: resolution.status, - limitations: resolution.limitations, } - : { - declared_path: input.declaredPath, - resolution_context: input.context, - resolved_path: null, - resolution_status: resolution.status, - limitations: resolution.limitations, - }; + : { ...facts, resolved_path: null, resolution_status: resolution.status }; }; +/** Project retained conditional identities without flattening them into display text. */ +export const artifactPathResolutionProperties = ( + resolution: ArtifactPathResolution | undefined, +): Readonly> => ({ + ...(resolution?.candidate_path === undefined + ? {} + : { candidate_path: resolution.candidate_path }), + ...(resolution?.conditional_resolutions === undefined + ? {} + : { + conditional_resolutions: resolution.conditional_resolutions.map( + (branch) => ({ + mode: branch.mode, + resolution_status: branch.resolution_status, + resolved_path: branch.resolved_path, + limitations: [...branch.limitations], + ...(branch.candidate_path === undefined + ? {} + : { candidate_path: branch.candidate_path }), + }), + ), + }), +}); + +const conditionalResolution = ( + mode: "import" | "require", + result: CandidateResolution, +): ConditionalModuleResolution => ({ + mode, + resolution_status: result.status, + resolved_path: result.resolvedPath, + limitations: result.limitations, + ...(result.candidatePath === undefined + ? {} + : { candidate_path: result.candidatePath }), +}); + const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => { + if (input.moduleKind === "compiler-dependent") { + const imported = resolvePath({ ...input, moduleKind: "import" }); + const required = resolvePath({ ...input, moduleKind: "require" }); + const sameOutcome = + imported.status === required.status && + imported.resolvedPath === required.resolvedPath && + imported.candidatePath === required.candidatePath; + const limitation = + "Static TypeScript loader mode is compiler-dependent without retained compiler options. " + + (sameOutcome + ? "Node import and require resolution agree on this outcome." + : "Node import and require resolution disagree; neither branch is an established target."); + return sameOutcome + ? { + ...imported, + limitations: [ + ...new Set([ + ...imported.limitations, + ...required.limitations, + limitation, + ]), + ], + } + : { + resolvedPath: null, + status: "unavailable", + limitations: [limitation], + conditionalResolutions: [ + conditionalResolution("import", imported), + conditionalResolution("require", required), + ], + }; + } // Package import keys are literal lookup identities, not artifact paths. // The selected target is admitted separately by resolveExportTarget. if ( @@ -176,12 +251,47 @@ const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => { : []; if (isModuleUrlPath && input.moduleKind === "import") return ( - resolveFileCandidates(input, [confined, ...emittedSourceCandidates]) ?? - notFoundCandidate() + resolveRuntimeSourceCandidates( + input, + confined, + emittedSourceCandidates, + ) ?? notFoundCandidate() ); return resolveCandidate(input, confined, new Set(), emittedSourceCandidates); }; +const resolveRuntimeSourceCandidates = ( + input: ResolveArtifactPathInput, + exactPath: string, + sourceCandidates: readonly TypeScriptEmittedSourceCandidate[], +): CandidateResolution | null => { + const source = input.files.get(input.sourcePath); + const exactCandidate: TypeScriptEmittedSourceCandidate = { + path: exactPath, + kind: "implementation", + }; + for (const candidate of [exactCandidate, ...sourceCandidates]) { + const target = input.files.get(candidate.path); + if ( + target === undefined || + (source !== undefined && + target.container_sha256 !== source.container_sha256) + ) + continue; + return candidate.kind === "declaration" + ? { + resolvedPath: null, + status: "unavailable", + candidatePath: candidate.path, + limitations: [ + "Only a TypeScript declaration fallback was found; it does not establish the requested runtime module.", + ], + } + : { resolvedPath: candidate.path, status: "resolved", limitations: [] }; + } + return null; +}; + const rejectDeclaration = (declared: string): CandidateResolution | null => { if (declared.length === 0) return unresolvedCandidate("rejected", ["The declared path is empty."]); @@ -849,12 +959,10 @@ const resolveCandidate = ( input: ResolveArtifactPathInput, candidate: string, packageChain: ReadonlySet, - emittedSourceCandidates: readonly string[] = [], + emittedSourceCandidates: readonly TypeScriptEmittedSourceCandidate[] = [], ): CandidateResolution => - resolveFileCandidates(input, [ - ...fileCandidates(candidate, input.moduleKind), - ...emittedSourceCandidates, - ]) ?? + resolveFileCandidates(input, fileCandidates(candidate, input.moduleKind)) ?? + resolveRuntimeSourceCandidates(input, candidate, emittedSourceCandidates) ?? resolveDirectory( input, candidate, @@ -940,11 +1048,26 @@ const resolveFileCandidates = ( (source === undefined || target.container_sha256 === source.container_sha256) ) - return { resolvedPath: path, status: "resolved", limitations: [] }; + return isRuntimeDeclarationPath(input, path) + ? { + resolvedPath: null, + status: "unavailable", + candidatePath: path, + limitations: [ + `The TypeScript declaration ${path} is compile-time evidence and cannot identify a runtime module implementation.`, + ], + } + : { resolvedPath: path, status: "resolved", limitations: [] }; } return null; }; +const isRuntimeDeclarationPath = ( + input: ResolveArtifactPathInput, + path: string, +): boolean => + input.moduleKind !== undefined && /\.d\.(?:ts|mts|cts)$/iu.test(path); + const NODE_MODULE_EXTENSIONS = [".js", ".json", ".node"] as const; const fileCandidates = ( diff --git a/src/application/javascript/JavaScriptModuleRelationships.ts b/src/application/javascript/JavaScriptModuleRelationships.ts index 514a9bb7c..3b46e95ae 100644 --- a/src/application/javascript/JavaScriptModuleRelationships.ts +++ b/src/application/javascript/JavaScriptModuleRelationships.ts @@ -18,6 +18,7 @@ import type { JavaScriptModuleOrigin, JavaScriptSemanticModuleLink, } from "../../domain/javascript/javascriptSemanticIr.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js"; import { addAstContainsEdge, @@ -30,7 +31,7 @@ import { staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js"; import { - moduleKindForJavaScriptReference, + artifactPathResolutionProperties, moduleResolutionModeProperties, resolveArtifactPathByContext, type ArtifactPathResolution, @@ -54,6 +55,7 @@ interface RelationshipInput { type ResolvedModuleTarget = { readonly node: ApplicationNode; readonly limitations: readonly string[]; + readonly resolution?: ArtifactPathResolution; } & ( | { readonly path: string; @@ -287,7 +289,7 @@ const resolveModuleTarget = ( sourcePath: input.file.path, context: "module-specifier", files: input.context.filesByPath, - moduleKind: moduleKindForJavaScriptReference( + moduleKind: moduleResolutionModeForJavaScriptReference( input.file.path, input.link.kind === "require" || input.link.kind === "commonjs-export" ? "require" @@ -297,15 +299,12 @@ const resolveModuleTarget = ( }); if (resolution.resolution_status !== "resolved") return { - node: unresolvedModuleNode( - input, - specifier, - resolution.resolution_status, - ), + node: unresolvedModuleNode(input, specifier, resolution), path: null, file: null, status: resolution.resolution_status, limitations: resolution.limitations, + resolution, }; const path = resolution.resolved_path; const file = input.context.filesByPath.get(path); @@ -322,20 +321,24 @@ const resolveModuleTarget = ( file, status: "resolved", limitations: resolution.limitations, + resolution, }; }; const unresolvedModuleNode = ( input: RelationshipInput, specifier: string, - status: Exclude, + resolution: Extract< + ArtifactPathResolution, + { resolution_status: Exclude } + >, ): ApplicationNode => input.context.accumulator.addNode({ kind: "javascript-module", identity: artifactLocalIdentity( input.file.sha256, "unresolved-semantic-module", - `${status}:${specifier}`, + `${resolution.resolution_status}:${specifier}`, ), observations: [ { @@ -343,7 +346,8 @@ const unresolvedModuleNode = ( properties: { semantic_role: "module-reference", declared_specifier: specifier, - resolution_status: status, + resolution_status: resolution.resolution_status, + ...artifactPathResolutionProperties(resolution), }, evidence: staticInferenceEvidence({ sha256: input.file.sha256, @@ -364,6 +368,9 @@ const moduleOriginForExport = ( ): JavaScriptModuleOrigin | null => { if (link.specifier !== null) return { + ...(link.resolutionMode === undefined + ? {} + : { resolutionMode: link.resolutionMode }), specifier: link.specifier, importedPath: link.importedName === null ? [] : [link.importedName], }; @@ -393,6 +400,7 @@ const relationshipProperties = ( exported_name: link.exportedName, resolved_path: target?.path ?? null, resolution_status: target?.status ?? null, + ...artifactPathResolutionProperties(target?.resolution), target_file_kind: target?.file?.kind ?? null, target_json_status: target?.file?.kind === "json" || target?.file?.kind === "package-json" @@ -441,6 +449,7 @@ const moduleFormat = ( const extension = posix.extname(path).toLowerCase(); if (extension === ".mjs" || extension === ".mts") return "esm"; if (extension === ".cjs" || extension === ".cts") return "commonjs"; + if (extension === ".ts" || extension === ".tsx") return "unknown"; const esm = ir.moduleLinks.some(({ kind }) => ["import", "export", "re-export"].includes(kind), ); diff --git a/src/composition/javascriptAnalysisWorkerProcess.ts b/src/composition/javascriptAnalysisWorkerProcess.ts index 09a9c9bc3..d1c3c134e 100644 --- a/src/composition/javascriptAnalysisWorkerProcess.ts +++ b/src/composition/javascriptAnalysisWorkerProcess.ts @@ -1,4 +1,4 @@ -import { moduleKindForJavaScriptReference } from "../application/javascript/JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../domain/javascript/javascriptModuleResolutionMode.js"; import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js"; import { analyzeParsedJavaScriptStaticSourceSteps } from "../domain/javascript/javascriptStaticAnalysis.js"; import { @@ -56,7 +56,7 @@ const analyze: JavaScriptSourceWorkerAnalyzer = async ( const ir = await completeJavaScriptAnalysisSteps( analyzeParsedJavaScriptSemanticsSteps( parsed, - moduleKindForJavaScriptReference(file.path, "static-import"), + moduleResolutionModeForJavaScriptReference(file.path, "static-import"), ), ); parsed = null; diff --git a/src/domain/javascript/javascriptModuleResolutionMode.ts b/src/domain/javascript/javascriptModuleResolutionMode.ts new file mode 100644 index 000000000..d14b91bd9 --- /dev/null +++ b/src/domain/javascript/javascriptModuleResolutionMode.ts @@ -0,0 +1,23 @@ +import { posix } from "node:path"; + +/** Loader evidence retained for a source-level module reference. */ +export type JavaScriptModuleResolutionMode = + | "import" + | "require" + | "compiler-dependent"; + +/** Derive source mode only when syntax or an explicit source format owns it. */ +export const moduleResolutionModeForJavaScriptReference = ( + sourcePath: string, + referenceKind: "static-import" | "dynamic-import" | "require", + explicitMode?: JavaScriptModuleResolutionMode, +): JavaScriptModuleResolutionMode => { + if (explicitMode !== undefined) return explicitMode; + if (referenceKind === "require") return "require"; + if (referenceKind === "dynamic-import") return "import"; + const extension = posix.extname(sourcePath).toLowerCase(); + if (extension === ".cts") return "require"; + if (extension === ".mts") return "import"; + if (extension === ".ts" || extension === ".tsx") return "compiler-dependent"; + return "import"; +}; diff --git a/src/domain/javascript/javascriptSemanticAnalysis.ts b/src/domain/javascript/javascriptSemanticAnalysis.ts index 35a8b7dc9..f6c6db25d 100644 --- a/src/domain/javascript/javascriptSemanticAnalysis.ts +++ b/src/domain/javascript/javascriptSemanticAnalysis.ts @@ -68,6 +68,7 @@ import { import { isJavaScriptRpcClientFactory } from "./javascriptRpcEndpoints.js"; import { createSemanticModuleInterop } from "./javascriptModuleInterop.js"; import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; interface BindPatternInput { readonly pattern: t.Node; @@ -138,7 +139,7 @@ export function* indexJavaScriptBindingsSteps( /** Recover semantics from an already parsed JavaScript artifact. */ export const analyzeParsedJavaScriptSemantics = ( file: ParsedJavaScriptSource, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): JavaScriptSemanticIr => completeSemanticSteps( analyzeParsedJavaScriptSemanticsSteps(file, staticImportResolutionMode), @@ -152,7 +153,7 @@ export const analyzeParsedJavaScriptSemantics = ( */ export function* analyzeParsedJavaScriptSemanticsSteps( file: ParsedJavaScriptSource, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): Generator { const state = createState(file.program, staticImportResolutionMode); yield* collectDefinitionsSteps(file.program, state); @@ -539,7 +540,7 @@ const bindingOrigin = ( const createState = ( program: t.Program, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): JavaScriptSemanticAnalysisState => { const root: JavaScriptSemanticScopeState = { scopeId: semanticScopeId("program", program), @@ -1216,8 +1217,11 @@ const addBinding = (input: AddBindingInput): void => { if (directOrigin !== undefined) binding.directOrigins.push( directOrigin.resolutionMode === undefined && - state.staticImportResolutionMode === "require" - ? { ...directOrigin, resolutionMode: "require" } + state.staticImportResolutionMode !== "import" + ? { + ...directOrigin, + resolutionMode: state.staticImportResolutionMode, + } : directOrigin, ); binding.runtimeImport ||= runtimeImport === true; diff --git a/src/domain/javascript/javascriptSemanticIr.ts b/src/domain/javascript/javascriptSemanticIr.ts index 18f1eb485..005471775 100644 --- a/src/domain/javascript/javascriptSemanticIr.ts +++ b/src/domain/javascript/javascriptSemanticIr.ts @@ -4,10 +4,11 @@ import type { JavaScriptSemanticCoverage, JavaScriptSemanticReturnCoverage, } from "./javascriptSemanticCoverage.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; /** One exact module origin followed through imports, requires, or aliases. */ export interface JavaScriptModuleOrigin { - readonly resolutionMode?: "import" | "require"; + readonly resolutionMode?: JavaScriptModuleResolutionMode; readonly specifier: string; readonly importedPath: readonly string[]; } @@ -393,7 +394,7 @@ export interface JavaScriptSemanticFrontier { /** Static import/export relationship retained for cross-file composition. */ export interface JavaScriptSemanticModuleLink { - readonly resolutionMode?: "import" | "require"; + readonly resolutionMode?: JavaScriptModuleResolutionMode; readonly kind: | "import" | "type-import" diff --git a/src/domain/javascript/javascriptSemanticProjection.ts b/src/domain/javascript/javascriptSemanticProjection.ts index 9d252a0d8..b477bb5af 100644 --- a/src/domain/javascript/javascriptSemanticProjection.ts +++ b/src/domain/javascript/javascriptSemanticProjection.ts @@ -533,7 +533,20 @@ const addModuleLink = ( }, referenceNode: t.Node, ): void => { - const collected = { ...link, callableId: link.callableId ?? null }; + const resolutionMode = + link.resolutionMode ?? + (link.kind === "import" || + link.kind === "re-export" || + link.kind === "type-import" + ? state.staticImportResolutionMode + : link.kind === "require" + ? "require" + : undefined); + const collected = { + ...link, + ...(resolutionMode === undefined ? {} : { resolutionMode }), + callableId: link.callableId ?? null, + }; state.moduleLinks.push(collected); if (link.localName !== null) { const binding = resolveSemanticBindingState( diff --git a/src/domain/javascript/javascriptSemanticReturns.ts b/src/domain/javascript/javascriptSemanticReturns.ts index a3ca92ead..27bb030d0 100644 --- a/src/domain/javascript/javascriptSemanticReturns.ts +++ b/src/domain/javascript/javascriptSemanticReturns.ts @@ -123,9 +123,7 @@ export const resolveSemanticModuleCallables = ( : undefined; return { ...link, - ...(resolutionMode === "import" || resolutionMode === "require" - ? { resolutionMode } - : {}), + ...(resolutionMode !== undefined ? { resolutionMode } : {}), callableId: resolved.length === 1 ? (resolved[0] ?? null) : null, }; }); diff --git a/src/domain/javascript/javascriptSemanticState.ts b/src/domain/javascript/javascriptSemanticState.ts index b82abc62d..d01a4be52 100644 --- a/src/domain/javascript/javascriptSemanticState.ts +++ b/src/domain/javascript/javascriptSemanticState.ts @@ -12,6 +12,7 @@ import type { JavaScriptSemanticCallable, JavaScriptSemanticScope, } from "./javascriptSemanticIr.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; /** Internal initializer plus a destructuring/member projection. */ interface JavaScriptSemanticInitializer { @@ -63,7 +64,7 @@ export interface JavaScriptSemanticScopeState { /** Shared state for semantic collection and evaluation. */ export interface JavaScriptSemanticAnalysisState { /** Effective loader for static imports in this source artifact. */ - readonly staticImportResolutionMode: "import" | "require"; + readonly staticImportResolutionMode: JavaScriptModuleResolutionMode; readonly parentsByNode: WeakMap; readonly scopes: JavaScriptSemanticScopeState[]; readonly scopesById: Map; diff --git a/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts b/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts index b666cfa9b..84a63d79b 100644 --- a/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts +++ b/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts @@ -475,7 +475,9 @@ const origin = z .strictObject({ specifier: z.string(), importedPath: strings, - resolutionMode: z.enum(["import", "require"]).optional(), + resolutionMode: z + .enum(["import", "require", "compiler-dependent"]) + .optional(), }) .transform(({ resolutionMode, ...rest }) => ({ ...rest, @@ -530,7 +532,9 @@ const coverage = z }); const moduleLink = z .strictObject({ - resolutionMode: z.enum(["import", "require"]).optional(), + resolutionMode: z + .enum(["import", "require", "compiler-dependent"]) + .optional(), kind: z.enum([ "import", "type-import", diff --git a/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts b/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts index 9b4df9992..cdd95bc97 100644 --- a/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts +++ b/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts @@ -152,7 +152,7 @@ describe("TypeScript source module loader semantics", () => { }); }); -describe("CommonJS and ESM module relationships", () => { +describe("JavaScript module relationships", () => { it("composes bindings, re-exports, dynamic imports, and JSON modules", async () => { const root = await moduleFixture(); const first = await reconstructJavaScriptFixture(root); @@ -288,6 +288,122 @@ describe("CommonJS and ESM module relationships", () => { }); }); +describe("Compiler-dependent TypeScript resolution", () => { + it("retains only compiler-independent targets for .ts static imports", async () => { + const root = await createTestTempDirectory("rea-ts-conditional-loader-"); + await writeFixtureFiles(root, { + "package.json": '{"type":"commonjs"}', + "main.ts": `import { value as different } from "different"; +import { value as same } from "same"; +void different; void same;`, + "node_modules/different/package.json": JSON.stringify({ + exports: { + ".": { + import: "./import.mjs", + require: "./require.cjs", + }, + }, + }), + "node_modules/different/import.mjs": "export const value = 'import';", + "node_modules/different/require.cjs": "exports.value = 'require';", + "node_modules/same/package.json": JSON.stringify({ + exports: { ".": { import: "./shared.js", require: "./shared.js" } }, + }), + "node_modules/same/shared.js": "export const value = 'shared';", + }); + + const { graph } = await reconstructJavaScriptFixture(root); + const different = findRelationshipEdge(graph, { + kind: "import", + specifier: "different", + localName: "different", + }); + const same = findRelationshipEdge(graph, { + kind: "import", + specifier: "same", + localName: "same", + resolvedPath: "node_modules/same/shared.js", + }); + const staticFinding = (specifier: string) => + graph.edges.find( + ({ relation, properties }) => + relation === "imports" && + properties.kind === "static-import" && + properties.specifier === specifier, + ); + + expect( + findSourceModule(graph, "main.ts")?.observations[0]?.properties, + ).toMatchObject({ module_format: "unknown" }); + expect(different).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolution_status: "unavailable", + resolved_path: null, + conditional_resolutions: [ + { + mode: "import", + resolution_status: "resolved", + resolved_path: "node_modules/different/import.mjs", + }, + { + mode: "require", + resolution_status: "resolved", + resolved_path: "node_modules/different/require.cjs", + }, + ], + }, + }); + expect(same).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolved_path: "node_modules/same/shared.js", + resolution_status: "resolved", + }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + expect(staticFinding("different")).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolution_status: "unavailable", + conditional_resolutions: [ + { + mode: "import", + resolved_path: "node_modules/different/import.mjs", + }, + { + mode: "require", + resolved_path: "node_modules/different/require.cjs", + }, + ], + }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + expect(staticFinding("same")).toMatchObject({ + properties: { resolved_path: "node_modules/same/shared.js" }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + }); +}); + it("does not assign one module origin to an export with colliding path encodings", async () => { const root = await createTestTempDirectory("rea-ambiguous-module-origin-"); await writeFixtureFiles(root, { From 9cf49c7a784ace9b79e4b4c1022c9fbf2b3f77e1 Mon Sep 17 00:00:00 2001 From: jiangjiang248 Date: Tue, 13 Oct 2026 16:04:44 +0800 Subject: [PATCH 4/7] fix(snapshot): classify non-object roots as invalid content (#2685) Co-authored-by: jiangjiang248 <237556902+jiangjiang248@users.noreply.github.com> --- src/application/JsonInputFile.ts | 8 +- .../filesystem/analysisSnapshotInput.test.ts | 88 +++++++++++++++++++ 2 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 tests/boundary/filesystem/analysisSnapshotInput.test.ts diff --git a/src/application/JsonInputFile.ts b/src/application/JsonInputFile.ts index a226cb0cc..25e5fcec0 100644 --- a/src/application/JsonInputFile.ts +++ b/src/application/JsonInputFile.ts @@ -78,7 +78,9 @@ export const readJsonObjectFile = ( value === null || Array.isArray(value) ) - throw new TypeError("JSON document root must be an object"); + return err( + invalidJson(operation, "JSON document root must be an object"), + ); for (const members of scans) for (const [key, member] of members) { if (!Object.hasOwn(value, key)) continue; @@ -177,7 +179,9 @@ export const readJsonObjectFile = ( signal === undefined ? {} : { signal }, ); if (!rootObject) - throw new TypeError("JSON document root must be an object"); + return err( + invalidJson(operation, "JSON document root must be an object"), + ); const digest = hash.digest("hex"); if (previousDigest !== undefined && digest !== previousDigest) throw new RegularFileChangedError(path); diff --git a/tests/boundary/filesystem/analysisSnapshotInput.test.ts b/tests/boundary/filesystem/analysisSnapshotInput.test.ts new file mode 100644 index 000000000..85bd7b7d1 --- /dev/null +++ b/tests/boundary/filesystem/analysisSnapshotInput.test.ts @@ -0,0 +1,88 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { readAnalysisSnapshot } from "../../../src/application/binary/AnalysisSnapshotFiles.js"; +import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; +import { + snapshotBinding, + snapshotTarget, +} from "../../../src/domain/analysisSnapshot.js"; +import { + ANALYSIS_SNAPSHOT_PROFILE, + ANALYSIS_SNAPSHOT_TARGET, +} from "../../../src/domain/analysisSnapshot.fixture.js"; +import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +describe.each([ + { mode: "native", paddingBytes: 0 }, + { mode: "streamed", paddingBytes: 9 * 1024 * 1024 }, +])("analysis snapshot input ($mode)", ({ paddingBytes }) => { + it.each(["[]", "null", "5", '"x"', "true"])( + "classifies a readable %s root as invalid content, not an I/O failure", + async (document) => { + const root = await createTestTempDirectory("rea-snapshot-root-"); + const path = join(root, "snapshot.json"); + const encoded = `${" ".repeat(paddingBytes)}${document}`; + await writeFile(path, encoded); + + const loaded = await readAnalysisSnapshot(path); + if (loaded.ok) throw new Error("Expected a non-object root rejection"); + const projected = projectAnalysisError(loaded.error); + expect(projected).toMatchObject({ + code: "evidence_integrity_mismatch", + details: { reason: "invalid-json" }, + }); + expect(projected.message).toContain("Repair or recreate"); + expect(loaded.error.cause).toMatchObject({ + message: "JSON document root must be an object", + }); + expect(await readFile(path, "utf8")).toBe(encoded); + }, + ); + + it("retains syntax and snapshot-member validation and loads valid objects", async () => { + const root = await createTestTempDirectory("rea-snapshot-validation-"); + const path = join(root, "snapshot.json"); + const prefix = " ".repeat(paddingBytes); + await writeFile(path, `${prefix}[`); + expect(await readAnalysisSnapshot(path)).toMatchObject({ + ok: false, + error: { _tag: "EvidenceFileError", reason: "invalid-json" }, + }); + await writeFile(path, `${prefix}{}`); + expect(await readAnalysisSnapshot(path)).toMatchObject({ + ok: false, + error: { _tag: "EvidenceIntegrityError" }, + }); + const snapshot = { + target: snapshotTarget(ANALYSIS_SNAPSHOT_TARGET), + binding: snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE), + entries: [], + workflow_entries: [], + evidence_bundle: createEvidenceBundle([]), + }; + await writeFile(path, `${prefix}${JSON.stringify(snapshot)}`); + expect(await readAnalysisSnapshot(path)).toEqual({ + ok: true, + value: snapshot, + }); + }); +}); + +it("keeps file-selection failures distinct from invalid snapshot contents", async () => { + const root = await createTestTempDirectory("rea-snapshot-selection-"); + for (const [path, reason] of [ + [join(root, "missing.json"), "missing"], + [root, "not-file"], + ] as const) { + const loaded = await readAnalysisSnapshot(path); + if (loaded.ok) throw new Error("Expected a file-selection failure"); + expect(projectAnalysisError(loaded.error)).toMatchObject({ + code: "invalid_request", + details: { reason }, + }); + } +}); From b955b825fc002a4bb408f2910b78768c566c2cd1 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 16:08:41 +0800 Subject: [PATCH 5/7] fix(artifacts): retain read cleanup ownership through CLI and MCP shutdown Keep failed stable-read handles and WABT runtime roots under retryable resource scopes. Preserve cancellation causes and primary errors, close the same service instances bound to MCP tools, and consolidate CLI operation/cleanup projection. Validation: fast typecheck and lint, cached runtime build, docs checks, SDK schema validation, focused service and real-file cleanup tests, CLI cleanup regressions, and MCP lifecycle/shutdown workflows. Provider process fixtures simulate engine output; real WABT and Linux EVM execution are not established by this pass. --- src/application/WebModulePorts.ts | 1 + src/application/WebModuleTraceService.ts | 23 +- src/application/WebNetworkCapturePort.ts | 2 + src/application/WebNetworkCaptureService.ts | 5 + src/application/WebScriptArtifactPort.ts | 1 + src/application/WebSourceLocationPorts.ts | 1 + src/application/WebSourceLocationService.ts | 23 +- .../binaryDiagnostics/PeResourcesPort.ts | 1 + .../binaryDiagnostics/PeResourcesService.ts | 4 + src/application/go/GoBinaryPort.ts | 1 + src/application/go/GoBinaryService.ts | 4 + src/artifacts/ArtifactResourceScope.ts | 4 + src/artifacts/readStableArtifact.ts | 12 +- src/browser/assets/LocalWebScriptArtifacts.ts | 32 ++- src/browser/assets/WebArtifactReads.ts | 36 ++- .../assets/WebSourceLocationArtifacts.ts | 61 ++++- .../history/HistoricalCaptureDecoder.ts | 94 ++++++- src/browser/modules/WebModuleArtifacts.ts | 60 ++++- src/cli/binaryDiagnosticsCommands.ts | 39 +-- src/cli/captureCommands.ts | 65 ++--- src/cli/finishAnalysisCommand.ts | 69 +++++ src/cli/goCommands.ts | 26 +- src/cli/signalCommands.ts | 65 ++--- src/cli/webNetworkCaptureCommands.ts | 32 ++- src/evm/EvmoleFailures.ts | 57 +++-- src/evm/EvmoleInterfaceProvider.ts | 116 +++++++-- src/go/GoBinaryProvider.ts | 53 +++- src/native/pe/PeResourcesProvider.ts | 61 ++++- src/native/pwndbg/PwndbgCoreContext.ts | 32 ++- src/native/pwntools/PwntoolsDecoder.ts | 125 +++++++-- .../pwntools/PwntoolsRecordedCrashProvider.ts | 2 + src/native/pwntools/PwntoolsResourceLimits.ts | 8 + src/server/createServer.ts | 23 +- src/wasm/WabtArtifactProvider.test.ts | 241 ++++++++++++++---- src/wasm/WabtArtifactProvider.ts | 94 +++++-- src/wasm/WabtFailures.ts | 27 +- .../browser/historicalCaptureDecoder.test.ts | 63 ++++- tests/boundary/cli/captureCleanup.test.ts | 106 ++++++++ .../filesystem/stableArtifact.test.ts | 9 +- .../webArtifactReadOwnership.test.ts | 96 +++++++ tests/boundary/mcp/serverLifecycleMcp.test.ts | 65 +++++ .../boundary/native/PwndbgCoreContext.test.ts | 2 + .../native/pwntoolsArtifactCleanup.test.ts | 147 +++++++++++ .../artifactReadCleanupRetry.test.ts | 100 ++++++++ 44 files changed, 1758 insertions(+), 330 deletions(-) create mode 100644 src/cli/finishAnalysisCommand.ts create mode 100644 tests/boundary/filesystem/webArtifactReadOwnership.test.ts create mode 100644 tests/boundary/native/pwntoolsArtifactCleanup.test.ts create mode 100644 tests/boundary/providers/artifactReadCleanupRetry.test.ts diff --git a/src/application/WebModulePorts.ts b/src/application/WebModulePorts.ts index 81c94a161..2f03efce0 100644 --- a/src/application/WebModulePorts.ts +++ b/src/application/WebModulePorts.ts @@ -22,6 +22,7 @@ export interface WebModuleArtifacts extends SelectedWebScriptArtifacts { /** Read selected local artifacts without refetching website assets. */ export interface WebModuleArtifactPort { + close?(): Promise; load( input: WebModuleTraceInput, options?: ExecutionOptions, diff --git a/src/application/WebModuleTraceService.ts b/src/application/WebModuleTraceService.ts index f8aa0f8b9..7913158f6 100644 --- a/src/application/WebModuleTraceService.ts +++ b/src/application/WebModuleTraceService.ts @@ -70,7 +70,13 @@ export class WebModuleTraceService { ) {} close(): Promise { - return this.resolver.close?.() ?? Promise.resolve(); + return closeOwnedWebResources( + [ + this.artifacts.close?.bind(this.artifacts), + this.resolver.close?.bind(this.resolver), + ], + "Web module trace cleanup failed", + ); } async trace( @@ -265,6 +271,21 @@ export class WebModuleTraceService { } } +const closeOwnedWebResources = async ( + close: readonly ((() => Promise) | undefined)[], + message: string, +): Promise => { + const results = await Promise.allSettled( + close.flatMap((owner) => + owner === undefined ? [] : [Promise.resolve().then(owner)], + ), + ); + const failures = results.flatMap((result) => + result.status === "rejected" ? [result.reason] : [], + ); + if (failures.length > 0) throw new AggregateError(failures, message); +}; + const admitContext = ( value: string, path: readonly string[], diff --git a/src/application/WebNetworkCapturePort.ts b/src/application/WebNetworkCapturePort.ts index 5f9cd5545..2bd0f1968 100644 --- a/src/application/WebNetworkCapturePort.ts +++ b/src/application/WebNetworkCapturePort.ts @@ -12,4 +12,6 @@ export interface WebNetworkCapturePort { input: InspectWebNetworkCaptureInput, options?: ExecutionOptions, ): Promise>; + /** Retry retained reader/runtime cleanup when the owning service shuts down. */ + close?(): Promise; } diff --git a/src/application/WebNetworkCaptureService.ts b/src/application/WebNetworkCaptureService.ts index 8e29ebb10..5a3d5cfea 100644 --- a/src/application/WebNetworkCaptureService.ts +++ b/src/application/WebNetworkCaptureService.ts @@ -27,6 +27,11 @@ const OPERATION = "inspect_web_network_capture"; export class WebNetworkCaptureService { constructor(readonly port: WebNetworkCapturePort) {} + /** Release resources retained by the selected capture adapter. */ + close(): Promise { + return this.port.close?.() ?? Promise.resolve(); + } + /** Return selected complete records inline, without inventing live browser attribution. */ async inspect( rawInput: unknown, diff --git a/src/application/WebScriptArtifactPort.ts b/src/application/WebScriptArtifactPort.ts index 02214d006..77dcd9cfc 100644 --- a/src/application/WebScriptArtifactPort.ts +++ b/src/application/WebScriptArtifactPort.ts @@ -8,6 +8,7 @@ import type { ExecutionOptions } from "./AnalysisProvider.js"; /** Read the caller-selected capture export and verify the selected source identity. */ export interface WebScriptArtifactPort { + close?(): Promise; load( input: SelectedWebScriptInput, options?: ExecutionOptions, diff --git a/src/application/WebSourceLocationPorts.ts b/src/application/WebSourceLocationPorts.ts index 04fe1742c..1d21783cc 100644 --- a/src/application/WebSourceLocationPorts.ts +++ b/src/application/WebSourceLocationPorts.ts @@ -20,6 +20,7 @@ export interface WebSourceLocationArtifacts extends SelectedWebScriptArtifacts { /** Replaceable artifact acquisition boundary for a caller-selected pairing. */ export interface WebSourceLocationArtifactPort { + close?(): Promise; load( input: WebSourceLocationInput, options?: ExecutionOptions, diff --git a/src/application/WebSourceLocationService.ts b/src/application/WebSourceLocationService.ts index 7be901311..79b7d45fc 100644 --- a/src/application/WebSourceLocationService.ts +++ b/src/application/WebSourceLocationService.ts @@ -71,7 +71,13 @@ export class WebSourceLocationService { ) {} close(): Promise { - return this.decoder.close?.() ?? Promise.resolve(); + return closeOwnedWebResources( + [ + this.artifacts.close?.bind(this.artifacts), + this.decoder.close?.bind(this.decoder), + ], + "Web source-location cleanup failed", + ); } /** Shared CLI/MCP workflow preserves raw declarations and every equal-position match. */ @@ -174,6 +180,21 @@ export class WebSourceLocationService { ); } } + +const closeOwnedWebResources = async ( + close: readonly ((() => Promise) | undefined)[], + message: string, +): Promise => { + const results = await Promise.allSettled( + close.flatMap((owner) => + owner === undefined ? [] : [Promise.resolve().then(owner)], + ), + ); + const failures = results.flatMap((result) => + result.status === "rejected" ? [result.reason] : [], + ); + if (failures.length > 0) throw new AggregateError(failures, message); +}; const invalidOutput = (message: string): Result => err(new AnalysisOutputError(OPERATION, message)); const invalid = ( diff --git a/src/application/binaryDiagnostics/PeResourcesPort.ts b/src/application/binaryDiagnostics/PeResourcesPort.ts index b1a7b53de..ee36d34f3 100644 --- a/src/application/binaryDiagnostics/PeResourcesPort.ts +++ b/src/application/binaryDiagnostics/PeResourcesPort.ts @@ -12,6 +12,7 @@ import type { Result } from "../../domain/result.js"; /** Stable read and PE decoding boundary, independent of an active disassembler session. */ export interface PeResourcesPort { readonly identity: ProviderIdentity; + close?(): Promise; inspect( input: InspectPeResourcesInput, options?: ExecutionOptions, diff --git a/src/application/binaryDiagnostics/PeResourcesService.ts b/src/application/binaryDiagnostics/PeResourcesService.ts index 3c8a53704..87de771a4 100644 --- a/src/application/binaryDiagnostics/PeResourcesService.ts +++ b/src/application/binaryDiagnostics/PeResourcesService.ts @@ -21,6 +21,10 @@ import { err, ok, type Result } from "../../domain/result.js"; export class PeResourcesService { constructor(readonly provider: PeResourcesPort) {} + close(): Promise { + return this.provider.close?.() ?? Promise.resolve(); + } + async inspect( rawInput: unknown, options?: ExecutionOptions, diff --git a/src/application/go/GoBinaryPort.ts b/src/application/go/GoBinaryPort.ts index 2094e9109..cef925921 100644 --- a/src/application/go/GoBinaryPort.ts +++ b/src/application/go/GoBinaryPort.ts @@ -12,6 +12,7 @@ import type { Result } from "../../domain/result.js"; /** Replaceable offline build-information reader with no target-execution authority. */ export interface GoBinaryPort { readonly identity: ProviderIdentity; + close?(): Promise; inspect( input: InspectGoBinaryInput, options?: ExecutionOptions, diff --git a/src/application/go/GoBinaryService.ts b/src/application/go/GoBinaryService.ts index f5642c96c..2b9928f82 100644 --- a/src/application/go/GoBinaryService.ts +++ b/src/application/go/GoBinaryService.ts @@ -34,6 +34,10 @@ const architectureForSubject = (architecture: string) => { export class GoBinaryService { constructor(readonly provider: GoBinaryPort) {} + close(): Promise { + return this.provider.close?.() ?? Promise.resolve(); + } + /** Inspect one explicitly selected file without acquiring a binary session. */ async inspect( rawInput: unknown, diff --git a/src/artifacts/ArtifactResourceScope.ts b/src/artifacts/ArtifactResourceScope.ts index 7c0bcf2c2..872899631 100644 --- a/src/artifacts/ArtifactResourceScope.ts +++ b/src/artifacts/ArtifactResourceScope.ts @@ -57,6 +57,10 @@ export class ArtifactResourceScope { #draining: Promise | undefined; #closed = false; + get hasPending(): boolean { + return this.#pending.size > 0; + } + /** Admit a resource operation while the scope remains open. */ async run(operation: () => Promise): Promise { while (true) { diff --git a/src/artifacts/readStableArtifact.ts b/src/artifacts/readStableArtifact.ts index e35a20783..808133d89 100644 --- a/src/artifacts/readStableArtifact.ts +++ b/src/artifacts/readStableArtifact.ts @@ -38,6 +38,13 @@ const afterValidation = async ( } }; +const assertReadActive = (signal: AbortSignal | undefined): void => { + if (signal?.aborted) + throw new ArtifactReaderFailure("cancelled", "Artifact read cancelled", { + cause: signal.reason, + }); +}; + /** Read one bounded regular file and reject replacement or in-place changes. */ export const readStableArtifact = async ( path: string, @@ -46,7 +53,7 @@ export const readStableArtifact = async ( fileSystem: StableArtifactFileSystem = FILE_SYSTEM, resourceScope?: ArtifactResourceScope, ): Promise<{ readonly bytes: Buffer; readonly sha256: string }> => { - signal?.throwIfAborted(); + assertReadActive(signal); const before = await fileSystem.lstat(path); if (!before.isFile() || before.isSymbolicLink()) throw new ArtifactReaderFailure( @@ -84,7 +91,7 @@ export const readStableArtifact = async ( autoClose: false, highWaterMark: 65536, })) { - signal?.throwIfAborted(); + assertReadActive(signal); const value: unknown = chunk; if (!Buffer.isBuffer(value)) throw new ArtifactReaderFailure( @@ -120,6 +127,7 @@ export const readStableArtifact = async ( "integrity", `Artifact changed during read: ${path}`, ); + assertReadActive(signal); const bytes = Buffer.concat(chunks, count); return { bytes, sha256: createHash("sha256").update(bytes).digest("hex") }; } catch (cause: unknown) { diff --git a/src/browser/assets/LocalWebScriptArtifacts.ts b/src/browser/assets/LocalWebScriptArtifacts.ts index c5d6ea8ed..51fc14c45 100644 --- a/src/browser/assets/LocalWebScriptArtifacts.ts +++ b/src/browser/assets/LocalWebScriptArtifacts.ts @@ -1,6 +1,7 @@ import { lstat, realpath } from "node:fs/promises"; import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; import { normalizeArtifactPath } from "../../artifacts/ArtifactPaths.js"; import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js"; @@ -19,10 +20,36 @@ import { /** Read one digest-verified captured source under the manifest's current location. */ export class LocalWebScriptArtifacts implements WebScriptArtifactPort { - constructor(readonly operation: WebArtifactReadContext["operation"]) {} + constructor( + readonly operation: WebArtifactReadContext["operation"], + readonly resources = new ArtifactResourceScope(), + ) {} + + close(): Promise { + return this.resources.close(); + } /** Read the selected source; relocated exports retain their reported original root. */ async load(input: SelectedWebScriptInput, options?: ExecutionOptions) { + try { + return await this.resources.run(() => this.#load(input, options)); + } catch (cause: unknown) { + return err( + webArtifactReadError( + cause, + { + operation: this.operation, + field: ["manifest_path"], + targetPath: input.manifest_path, + callerSelected: true, + }, + options?.signal, + ), + ); + } + } + + async #load(input: SelectedWebScriptInput, options?: ExecutionOptions) { let field: readonly (string | number)[] = ["manifest_path"]; let targetPath = input.manifest_path; let callerSelected = true; @@ -31,6 +58,7 @@ export class LocalWebScriptArtifacts implements WebScriptArtifactPort { input.manifest_path, 32 * 1024 * 1024, options?.signal, + this.resources, ); const manifest = webScriptExportManifestSchema.parse(manifestBytes.value); field = ["script_index"]; @@ -65,6 +93,8 @@ export class LocalWebScriptArtifacts implements WebScriptArtifactPort { sourcePath, 16 * 1024 * 1024, options?.signal, + undefined, + this.resources, ); await assertContained(root, sourcePath); if ( diff --git a/src/browser/assets/WebArtifactReads.ts b/src/browser/assets/WebArtifactReads.ts index cd142f62f..e045e1575 100644 --- a/src/browser/assets/WebArtifactReads.ts +++ b/src/browser/assets/WebArtifactReads.ts @@ -1,5 +1,6 @@ import { z } from "zod"; import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; +import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { @@ -9,6 +10,8 @@ import { } from "../../domain/analysisErrorCore.js"; import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; +import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; +import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import { safeParseJson } from "../../domain/safeJson.js"; /** The selected artifact and input field owning a reader failure. */ @@ -42,8 +45,15 @@ export const readWebArtifactJson = async ( path: string, maximumBytes: number, signal?: AbortSignal, + resourceScope?: ArtifactResourceScope, ) => { - const data = await readStableArtifact(path, maximumBytes, signal); + const data = await readStableArtifact( + path, + maximumBytes, + signal, + undefined, + resourceScope, + ); const value = safeParseJson(decodeWebArtifact(data.bytes)); if (!value.ok) throw new WebArtifactFormatFailure(value.error); return { ...data, value: value.value }; @@ -55,8 +65,30 @@ export const webArtifactReadError = ( context: WebArtifactReadContext, signal?: AbortSignal, ): AnalysisError => { + if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) { + const primary = + signal?.aborted === true + ? new AnalysisCancelledError(context.operation, { cause }) + : new ArtifactOperationError( + context.operation, + cause.reason, + cause.details, + cause.message, + { cause }, + ); + return analysisErrorWithCleanupFailure( + primary, + new ProviderCleanupError( + "captured-web-artifacts", + cause.cleanup.resources, + { reason: cause.cleanup.reason }, + { cause, operation: context.operation }, + ), + context.operation, + ); + } if (signal?.aborted === true) - return new AnalysisCancelledError(context.operation); + return new AnalysisCancelledError(context.operation, { cause }); const selection = context.callerSelected ? selectedFileError(cause, context) : undefined; diff --git a/src/browser/assets/WebSourceLocationArtifacts.ts b/src/browser/assets/WebSourceLocationArtifacts.ts index 21c483bd8..733069469 100644 --- a/src/browser/assets/WebSourceLocationArtifacts.ts +++ b/src/browser/assets/WebSourceLocationArtifacts.ts @@ -1,6 +1,7 @@ import type { WebSourceLocationArtifactPort } from "../../application/WebSourceLocationPorts.js"; import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js"; import type { ExecutionOptions } from "../../application/AnalysisProvider.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; import { WEB_SOURCE_MAP_LIMITS, @@ -12,14 +13,64 @@ import { decodeWebArtifact, webArtifactReadError } from "./WebArtifactReads.js"; /** Read one verified capture source and the caller-selected map, without fetching. */ export class LocalWebSourceLocationArtifacts implements WebSourceLocationArtifactPort { + readonly scripts: WebScriptArtifactPort; + readonly #resources: ArtifactResourceScope; + constructor( - readonly scripts: WebScriptArtifactPort = new LocalWebScriptArtifacts( - "trace_web_source_location", - ), - ) {} + scripts?: WebScriptArtifactPort, + resources = scripts instanceof LocalWebScriptArtifacts + ? scripts.resources + : new ArtifactResourceScope(), + ) { + this.#resources = resources; + this.scripts = + scripts ?? + new LocalWebScriptArtifacts("trace_web_source_location", resources); + } + + async close(): Promise { + const closeScript = + this.scripts instanceof LocalWebScriptArtifacts && + this.scripts.resources === this.#resources + ? undefined + : this.scripts.close?.bind(this.scripts); + const results = await Promise.allSettled([ + Promise.resolve().then(() => this.#resources.close()), + ...(closeScript === undefined + ? [] + : [Promise.resolve().then(closeScript)]), + ]); + const failures = results.flatMap((result) => + result.status === "rejected" ? [result.reason] : [], + ); + if (failures.length > 0) + throw new AggregateError( + failures, + "Web source-location artifact cleanup failed", + ); + } /** Preserve actual map identity separately from the selected deployment URL. */ async load(input: WebSourceLocationInput, options?: ExecutionOptions) { + try { + return await this.#resources.run(() => this.#load(input, options)); + } catch (cause: unknown) { + return err( + webArtifactReadError( + cause, + { + operation: "trace_web_source_location", + field: ["source_map", "path"], + targetPath: input.source_map.path, + callerSelected: true, + }, + options?.signal, + ), + ); + } + } + + async #load(input: WebSourceLocationInput, options?: ExecutionOptions) { const loaded = await this.scripts.load(input, options); if (!loaded.ok) return loaded; try { @@ -27,6 +78,8 @@ export class LocalWebSourceLocationArtifacts implements WebSourceLocationArtifac input.source_map.path, WEB_SOURCE_MAP_LIMITS.mapBytes, options?.signal, + undefined, + this.#resources, ); return ok({ ...loaded.value, diff --git a/src/browser/history/HistoricalCaptureDecoder.ts b/src/browser/history/HistoricalCaptureDecoder.ts index 7f6e7b83a..85a91ef76 100644 --- a/src/browser/history/HistoricalCaptureDecoder.ts +++ b/src/browser/history/HistoricalCaptureDecoder.ts @@ -17,6 +17,7 @@ import { z } from "zod"; import type { ExecutionOptions } from "../../application/AnalysisProvider.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisCapabilityUnavailableError, @@ -26,6 +27,7 @@ import { } from "../../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; +import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import { err, ok, type Result } from "../../domain/result.js"; import { WEB_NETWORK_CAPTURE_LIMITS, @@ -60,18 +62,52 @@ const replySchema = z.discriminatedUnion("ok", [ /** One owned snapshot/process/root lifecycle for replaceable historical format decoders. */ export class HistoricalCaptureDecoder { + readonly #resources: ArtifactResourceScope; + constructor( readonly adapters: readonly HistoricalCaptureFormatAdapter[], readonly environment: Readonly, readonly createRuntime: () => Promise< Pick > = () => PrivateRuntimeRoot.create({ prefix: "rea-web-capture-" }), - ) {} + resources = new ArtifactResourceScope(), + ) { + this.#resources = resources; + } + + /** Retry retained readers and private roots at service shutdown. */ + close(): Promise { + return this.#resources.close(); + } /** Snapshot the selected artifact, decode it offline, and release private credentials and processes. */ async inspect( input: InspectWebNetworkCaptureInput, options?: ExecutionOptions, + ): Promise> { + try { + return await this.#resources.run(() => + this.inspectAdmitted(input, options), + ); + } catch (cause: unknown) { + const error = historicalCaptureFailure( + input, + cause, + "capture-read", + options, + ); + return err( + redactExplicitFailure( + this.withReaderCleanup(error, cause), + input.sensitive_values, + ), + ); + } + } + + private async inspectAdmitted( + input: InspectWebNetworkCaptureInput, + options?: ExecutionOptions, ): Promise> { let runtime: Pick | undefined; let result: Result; @@ -90,6 +126,8 @@ export class HistoricalCaptureDecoder { input.capture_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); phase = "decoder"; runtime = await this.createRuntime(); @@ -139,9 +177,16 @@ export class HistoricalCaptureDecoder { replyPath, WEB_NETWORK_CAPTURE_LIMITS.outputBytes, options?.signal, + undefined, + this.#resources, ); reply = replySchema.parse(JSON.parse(replyFile.bytes.toString("utf8"))); } catch (cause: unknown) { + if ( + cause instanceof ArtifactReaderFailure && + cause.cleanup !== undefined + ) + throw cause; if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION); throw new AnalysisOutputError( @@ -230,17 +275,21 @@ export class HistoricalCaptureDecoder { result = ok({ ...reply.value, ...common, format: input.format }); } } catch (cause: unknown) { + const error = historicalCaptureFailure(input, cause, phase, options); result = err( redactExplicitFailure( - historicalCaptureFailure(input, cause, phase, options), + this.withReaderCleanup(error, cause), input.sensitive_values, ), ); } if (runtime !== undefined) { - try { - await runtime.close(); - } catch (cause: unknown) { + const cleanup = await this.#resources.release({ + kind: "private-runtime-root", + resource: runtime.path, + root: runtime, + }); + if (cleanup.kind === "failed") { return err( redactExplicitFailure( new ProviderCleanupError( @@ -251,9 +300,12 @@ export class HistoricalCaptureDecoder { previous_error: result.ok ? null : projectAnalysisError(result.error), - reason: cause instanceof Error ? cause.message : String(cause), + reason: + cleanup.cause instanceof Error + ? cleanup.cause.message + : String(cleanup.cause), }, - { operation: OPERATION }, + { operation: OPERATION, cause: cleanup.cause }, ), input.sensitive_values, ), @@ -264,6 +316,34 @@ export class HistoricalCaptureDecoder { ? err(new AnalysisCancelledError(OPERATION)) : result; } + + private withReaderCleanup( + primary: AnalysisError, + cause: unknown, + ): AnalysisError { + if ( + !(cause instanceof ArtifactReaderFailure) || + cause.cleanup === undefined + ) + return primary; + if (cause.reason === "unavailable") + return new ProviderCleanupError( + "web-network-capture", + cause.cleanup.resources, + { reason: cause.cleanup.reason }, + { operation: OPERATION, cause }, + ); + const cleanup = new ProviderCleanupError( + "web-network-capture", + cause.cleanup.resources, + { + reason: cause.cleanup.reason, + previous_error: projectAnalysisError(primary), + }, + { operation: OPERATION, cause }, + ); + return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION); + } } /** The Node capture decoder runs on this executable; only Node.js enforces its V8 heap flags. */ diff --git a/src/browser/modules/WebModuleArtifacts.ts b/src/browser/modules/WebModuleArtifacts.ts index 287e6e8de..928025f09 100644 --- a/src/browser/modules/WebModuleArtifacts.ts +++ b/src/browser/modules/WebModuleArtifacts.ts @@ -4,6 +4,7 @@ import type { } from "../../application/WebModulePorts.js"; import type { WebScriptArtifactPort } from "../../application/WebScriptArtifactPort.js"; import type { ExecutionOptions } from "../../application/AnalysisProvider.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { jsonObjectSchema } from "../../domain/jsonValue.js"; import { err, ok } from "../../domain/result.js"; import type { WebModuleTraceInput } from "../../domain/webModuleTrace.js"; @@ -15,14 +16,64 @@ import { /** Add an explicitly selected import map to a verified captured-script source. */ export class LocalWebModuleArtifacts implements WebModuleArtifactPort { + readonly scripts: WebScriptArtifactPort; + readonly #resources: ArtifactResourceScope; + constructor( - readonly scripts: WebScriptArtifactPort = new LocalWebScriptArtifacts( - "trace_web_module_imports", - ), - ) {} + scripts?: WebScriptArtifactPort, + resources = scripts instanceof LocalWebScriptArtifacts + ? scripts.resources + : new ArtifactResourceScope(), + ) { + this.#resources = resources; + this.scripts = + scripts ?? + new LocalWebScriptArtifacts("trace_web_module_imports", resources); + } + + async close(): Promise { + const closeScript = + this.scripts instanceof LocalWebScriptArtifacts && + this.scripts.resources === this.#resources + ? undefined + : this.scripts.close?.bind(this.scripts); + const results = await Promise.allSettled([ + Promise.resolve().then(() => this.#resources.close()), + ...(closeScript === undefined + ? [] + : [Promise.resolve().then(closeScript)]), + ]); + const failures = results.flatMap((result) => + result.status === "rejected" ? [result.reason] : [], + ); + if (failures.length > 0) + throw new AggregateError(failures, "Web module artifact cleanup failed"); + } /** Read selected source and optional map without website requests. */ async load(input: WebModuleTraceInput, options?: ExecutionOptions) { + try { + return await this.#resources.run(() => this.#load(input, options)); + } catch (cause: unknown) { + return err( + webArtifactReadError( + cause, + { + operation: "trace_web_module_imports", + field: + input.import_map === undefined + ? ["manifest_path"] + : ["import_map", "path"], + targetPath: input.import_map?.path ?? input.manifest_path, + callerSelected: input.import_map !== undefined, + }, + options?.signal, + ), + ); + } + } + + async #load(input: WebModuleTraceInput, options?: ExecutionOptions) { const loaded = await this.scripts.load(input, options); if (!loaded.ok) return loaded; if (input.import_map === undefined) @@ -33,6 +84,7 @@ export class LocalWebModuleArtifacts implements WebModuleArtifactPort { selected.path, 4 * 1024 * 1024, options?.signal, + this.#resources, ); const importMap: WebModuleArtifacts["importMap"] = { file: { diff --git a/src/cli/binaryDiagnosticsCommands.ts b/src/cli/binaryDiagnosticsCommands.ts index bddd16bed..5cb9577bd 100644 --- a/src/cli/binaryDiagnosticsCommands.ts +++ b/src/cli/binaryDiagnosticsCommands.ts @@ -7,11 +7,12 @@ import { } from "../composition/binaryDiagnostics.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; import { logCliCommand } from "../cliLogging.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { withCommandCancellation } from "./commandCancellation.js"; import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { finishAnalysisCommand } from "./finishAnalysisCommand.js"; /** Inspect operator-selected files through the same shared workflow as MCP. */ export const registerBinaryDiagnosticsCommands = ( @@ -19,7 +20,6 @@ export const registerBinaryDiagnosticsCommands = ( logger: Logger, environment: Readonly, ): void => { - const pe = createPeResourcesService(); cli.command(CLI_COMMANDS.inspectPeResources, { description: "Inspect PE resource identities, payload ranges, hashes and icon-group relationships", @@ -29,19 +29,28 @@ export const registerBinaryDiagnosticsCommands = ( maxEntries: inspectPeResourcesInputSchema.shape.max_entries, }), run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, CLI_COMMANDS.inspectPeResources, async () => { - const result = await pe.inspect( - { - path: resolve(args.path), - max_file_bytes: options.maxFileBytes, - max_entries: options.maxEntries, - }, - { signal }, - ); - return result.ok ? result.value : projectAnalysisError(result.error); - }), - ), + withCommandCancellation(async (signal) => { + const pe = createPeResourcesService(); + return await logCliCommand( + logger, + CLI_COMMANDS.inspectPeResources, + async () => + finishAnalysisCommand( + () => + pe.inspect( + { + path: resolve(args.path), + max_file_bytes: options.maxFileBytes, + max_entries: options.maxEntries, + }, + { signal }, + ), + pe, + "rea-pe-resources", + "inspect_pe_resources", + ), + ); + }), }); const service = createBinaryLayoutService(environment); cli.command(CLI_COMMANDS.inspectBinaryLayout, { diff --git a/src/cli/captureCommands.ts b/src/cli/captureCommands.ts index 2a3566703..542361e90 100644 --- a/src/cli/captureCommands.ts +++ b/src/cli/captureCommands.ts @@ -1,9 +1,6 @@ import { inspectPacketFieldsInputSchema } from "../domain/captures/packetFields.js"; import { z } from "incur"; import type { PacketCaptureService } from "../application/captures/PacketCaptureService.js"; -import { AnalysisError } from "../domain/analysisErrorBase.js"; -import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; -import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { resolve } from "node:path"; import { createPacketCaptureService } from "../composition/captures.js"; import { @@ -13,10 +10,10 @@ import { } from "../domain/captures/packetCapture.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; import { logCliCommand } from "../cliLogging.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { withCommandCancellation } from "./commandCancellation.js"; +import { finishAnalysisCommand } from "./finishAnalysisCommand.js"; export const registerCaptureCommands = ( cli: CliInstance, logger: Logger, @@ -26,32 +23,6 @@ export const registerCaptureCommands = ( "inspect" | "inspectFields" | "close" > = createPacketCaptureService(environment), ): void => { - const finish = async ( - result: Awaited>, - operation: string, - ) => { - // A one-shot command must retry retained cleanup before discarding its owner. - try { - await service.close(); - } catch (cause) { - const cleanup = - cause instanceof AnalysisError - ? cause - : new ProviderCleanupError( - "tshark-capture", - [], - { reason: String(cause) }, - { cause, operation: operation }, - ); - if (result.ok) cleanup.retainPartialObservation(result.value); - return projectAnalysisError( - result.ok - ? cleanup - : analysisErrorWithCleanupFailure(result.error, cleanup, operation), - ); - } - return result.ok ? result.value : projectAnalysisError(result.error); - }; cli.command(CLI_COMMANDS.inspectPacketFields, { description: "Search installed TShark protocol and field definitions", options: z @@ -80,11 +51,14 @@ export const registerCaptureCommands = ( run: ({ options: { all, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectPacketFields, async () => - finish( - await service.inspectFields( - { ...options, ...(all ? { limit: null } : {}) }, - { signal }, - ), + finishAnalysisCommand( + () => + service.inspectFields( + { ...options, ...(all ? { limit: null } : {}) }, + { signal }, + ), + service, + "tshark-capture", "inspect_packet_fields", ), ), @@ -125,15 +99,20 @@ export const registerCaptureCommands = ( run: ({ args, options: { all_matches, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectPacketCapture, async () => { - const result = await service.inspect( - { - ...options, - ...(all_matches ? { match_limit: null } : {}), - path: resolve(args.path), - }, - { signal }, + return finishAnalysisCommand( + () => + service.inspect( + { + ...options, + ...(all_matches ? { match_limit: null } : {}), + path: resolve(args.path), + }, + { signal }, + ), + service, + "tshark-capture", + "inspect_packet_capture", ); - return finish(result, "inspect_packet_capture"); }), ), }); diff --git a/src/cli/finishAnalysisCommand.ts b/src/cli/finishAnalysisCommand.ts new file mode 100644 index 000000000..9394ba828 --- /dev/null +++ b/src/cli/finishAnalysisCommand.ts @@ -0,0 +1,69 @@ +import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; +import { + AnalysisError, + type AnalysisPartialObservation, +} from "../domain/analysisErrorBase.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; +import type { Result } from "../domain/result.js"; + +/** Finish a one-shot CLI operation without discarding its primary result on close failure. */ +export const finishAnalysisCommand = async < + Value extends AnalysisPartialObservation, +>( + run: () => Promise>, + service: { close(): Promise }, + providerId: string, + canonicalOperation: string, + fallbackResource?: string, +): Promise> => { + let result: Result; + try { + result = await run(); + } catch (cause) { + result = { + ok: false, + error: + cause instanceof AnalysisError + ? cause + : new ProviderAdapterError(providerId, canonicalOperation, { cause }), + }; + } + try { + await service.close(); + } catch (cause) { + let cleanup: AnalysisError; + if (cause instanceof AnalysisError) cleanup = cause; + else { + const observation = + cause instanceof ArtifactReaderFailure + ? ArtifactReaderFailure.cleanupObservation( + cause, + fallbackResource ?? `${canonicalOperation} resources`, + ) + : { + reason: cause instanceof Error ? cause.message : String(cause), + resources: [], + }; + cleanup = new ProviderCleanupError( + providerId, + observation.resources, + { reason: observation.reason }, + { cause, operation: canonicalOperation }, + ); + } + if (result.ok) cleanup.retainPartialObservation(result.value); + return projectAnalysisError( + result.ok + ? cleanup + : analysisErrorWithCleanupFailure( + result.error, + cleanup, + canonicalOperation, + ), + ); + } + return result.ok ? result.value : projectAnalysisError(result.error); +}; diff --git a/src/cli/goCommands.ts b/src/cli/goCommands.ts index d67a344e0..12b2b992a 100644 --- a/src/cli/goCommands.ts +++ b/src/cli/goCommands.ts @@ -3,14 +3,13 @@ import { resolve } from "node:path"; import { createGoBinaryService } from "../composition/go.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; import { logCliCommand } from "../cliLogging.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { withCommandCancellation } from "./commandCancellation.js"; +import { finishAnalysisCommand } from "./finishAnalysisCommand.js"; /** Resolve caller paths and inspect static build metadata through the shared workflow. */ export const registerGoCommands = (cli: CliInstance, logger: Logger): void => { - const service = createGoBinaryService(); cli.command(CLI_COMMANDS.inspectGoBinary, { description: "Inspect embedded Go compiler, modules and build settings without target execution", @@ -18,14 +17,19 @@ export const registerGoCommands = (cli: CliInstance, logger: Logger): void => { path: z.string().describe("Local ELF, PE or thin Mach-O image"), }), run: ({ args }) => - withCommandCancellation((signal) => - logCliCommand(logger, CLI_COMMANDS.inspectGoBinary, async () => { - const result = await service.inspect( - { path: resolve(args.path) }, - { signal }, - ); - return result.ok ? result.value : projectAnalysisError(result.error); - }), - ), + withCommandCancellation(async (signal) => { + const service = createGoBinaryService(); + return await logCliCommand( + logger, + CLI_COMMANDS.inspectGoBinary, + async () => + finishAnalysisCommand( + () => service.inspect({ path: resolve(args.path) }, { signal }), + service, + "go-build-info", + "inspect_go_binary", + ), + ); + }), }); }; diff --git a/src/cli/signalCommands.ts b/src/cli/signalCommands.ts index e7d254507..63b7d9edf 100644 --- a/src/cli/signalCommands.ts +++ b/src/cli/signalCommands.ts @@ -1,9 +1,6 @@ import { inspectSignalDecodersInputSchema } from "../domain/signals/signalDecoders.js"; import { z } from "incur"; import type { SignalRecordingService } from "../application/signals/SignalRecordingService.js"; -import { AnalysisError } from "../domain/analysisErrorBase.js"; -import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; -import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { resolve } from "node:path"; import { createSignalRecordingService } from "../composition/signals.js"; import { @@ -13,10 +10,10 @@ import { } from "../domain/signals/signalRecording.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; import { logCliCommand } from "../cliLogging.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { withCommandCancellation } from "./commandCancellation.js"; +import { finishAnalysisCommand } from "./finishAnalysisCommand.js"; export const registerSignalCommands = ( cli: CliInstance, logger: Logger, @@ -26,32 +23,6 @@ export const registerSignalCommands = ( "decode" | "inspectDecoders" | "close" > = createSignalRecordingService(environment), ): void => { - const finish = async ( - result: Awaited>, - operation: string, - ) => { - // A one-shot command must retry retained cleanup before discarding its owner. - try { - await service.close(); - } catch (cause) { - const cleanup = - cause instanceof AnalysisError - ? cause - : new ProviderCleanupError( - "sigrok-recording", - [], - { reason: String(cause) }, - { cause, operation: operation }, - ); - if (result.ok) cleanup.retainPartialObservation(result.value); - return projectAnalysisError( - result.ok - ? cleanup - : analysisErrorWithCleanupFailure(result.error, cleanup, operation), - ); - } - return result.ok ? result.value : projectAnalysisError(result.error); - }; cli.command(CLI_COMMANDS.inspectSignalDecoders, { description: "Search installed sigrok decoders or selected decoder help", options: z @@ -82,11 +53,14 @@ export const registerSignalCommands = ( run: ({ options: { all, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectSignalDecoders, async () => - finish( - await service.inspectDecoders( - { ...options, ...(all ? { limit: null } : {}) }, - { signal }, - ), + finishAnalysisCommand( + () => + service.inspectDecoders( + { ...options, ...(all ? { limit: null } : {}) }, + { signal }, + ), + service, + "sigrok-recording", "inspect_signal_decoders", ), ), @@ -127,15 +101,20 @@ export const registerSignalCommands = ( run: ({ args, options: { all_lines, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.decodeSignalRecording, async () => { - const result = await service.decode( - { - ...options, - ...(all_lines ? { line_limit: null } : {}), - path: resolve(args.path), - }, - { signal }, + return finishAnalysisCommand( + () => + service.decode( + { + ...options, + ...(all_lines ? { line_limit: null } : {}), + path: resolve(args.path), + }, + { signal }, + ), + service, + "sigrok-recording", + "decode_signal_recording", ); - return finish(result, "decode_signal_recording"); }), ), }); diff --git a/src/cli/webNetworkCaptureCommands.ts b/src/cli/webNetworkCaptureCommands.ts index 655d34bc1..d49e39b0e 100644 --- a/src/cli/webNetworkCaptureCommands.ts +++ b/src/cli/webNetworkCaptureCommands.ts @@ -3,10 +3,10 @@ import { WEB_NETWORK_CAPTURE_FORMATS } from "../domain/webNetworkCapture.js"; import { createWebNetworkCaptureService } from "../composition/webNetworkCaptures.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; import { logCliCommand } from "../cliLogging.js"; -import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { withCommandCancellation } from "./commandCancellation.js"; +import { finishAnalysisCommand } from "./finishAnalysisCommand.js"; /** Expose offline historical capture inspection with the same selection contract as MCP. */ export const registerWebNetworkCaptureCommands = ( @@ -42,20 +42,24 @@ export const registerWebNetworkCaptureCommands = ( logger, CLI_COMMANDS.inspectWebNetworkCapture, async () => { - const result = await service.inspect( - { - capture_path: args.capturePath, - format: args.format, - sensitive_values: options.sensitiveValue, - ...(options.record === undefined - ? {} - : { record_ordinals: options.record }), - }, - { signal }, + return finishAnalysisCommand( + () => + service.inspect( + { + capture_path: args.capturePath, + format: args.format, + sensitive_values: options.sensitiveValue, + ...(options.record === undefined + ? {} + : { record_ordinals: options.record }), + }, + { signal }, + ), + service, + "web-network-capture", + "inspect_web_network_capture", + "Web network capture resources", ); - return result.ok - ? result.value - : projectAnalysisError(result.error); }, ), ), diff --git a/src/evm/EvmoleFailures.ts b/src/evm/EvmoleFailures.ts index 2677a3e71..63c6578aa 100644 --- a/src/evm/EvmoleFailures.ts +++ b/src/evm/EvmoleFailures.ts @@ -39,6 +39,9 @@ export const evmInterfaceFailure = ( limiter = "/usr/bin/prlimit", fileFailure?: EvmFileSizeFailureEvidence, ): AnalysisError => { + const cleanup = + cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; + const cleanupOptions = cleanup === undefined ? {} : { cleanup }; if (cause instanceof AnalysisError) return cause; if (cause instanceof OwnedCommandFailure) { const outputOptions = @@ -64,12 +67,15 @@ export const evmInterfaceFailure = ( { operation: "inspect_evm_interface", cause }, ); if (cause.reason === "cancelled") - return new AnalysisCancelledError("inspect_evm_interface", outputOptions); + return new AnalysisCancelledError("inspect_evm_interface", { + ...outputOptions, + ...cleanupOptions, + }); if (cause.reason === "timeout") return new AnalysisTimeoutError( "inspect_evm_interface", EVM_INTERFACE_LIMITS.timeoutMs, - outputOptions, + { ...outputOptions, ...cleanupOptions }, ); if (cause.reason === "output-limit") return new AnalysisOutputError( @@ -122,25 +128,33 @@ export const evmInterfaceFailure = ( } if (cause instanceof ArtifactReaderFailure) { if (cause.reason === "cancelled") - return new AnalysisCancelledError("inspect_evm_interface"); + return new AnalysisCancelledError("inspect_evm_interface", { + cause, + ...cleanupOptions, + }); if (cause.reason === "integrity") return new AnalysisArtifactChangedError( "inspect_evm_interface", path, cause.message, - { cause }, + { cause, ...cleanupOptions }, ); if ( phase === "artifact-read" && ["limit", "path", "format"].includes(cause.reason) ) - return new AnalysisInputError("inspect_evm_interface", { cause }, [ - { - path: ["path"], - reason: cause.reason === "limit" ? "out_of_range" : "invalid_format", - message: cause.message, - }, - ]); + return new AnalysisInputError( + "inspect_evm_interface", + { cause, ...cleanupOptions }, + [ + { + path: ["path"], + reason: + cause.reason === "limit" ? "out_of_range" : "invalid_format", + message: cause.message, + }, + ], + ); } if (phase === "artifact-read" && cause instanceof Error && "code" in cause) { if (cause.code === "EACCES" || cause.code === "EPERM") @@ -148,22 +162,27 @@ export const evmInterfaceFailure = ( "inspect_evm_interface", path, cause.code, - { cause }, + { cause, ...cleanupOptions }, ); if (cause.code === "ENOENT" || cause.code === "ENOTDIR") - return new AnalysisInputError("inspect_evm_interface", { cause }, [ - { - path: ["path"], - reason: "invalid_value", - message: `Selected bytecode carrier could not be read (${String(cause.code)}): ${path}.`, - }, - ]); + return new AnalysisInputError( + "inspect_evm_interface", + { cause, ...cleanupOptions }, + [ + { + path: ["path"], + reason: "invalid_value", + message: `Selected bytecode carrier could not be read (${String(cause.code)}): ${path}.`, + }, + ], + ); } return new ProviderAdapterError( EVMOLE_PROVIDER_IDENTITY.id, "inspect_evm_interface", { cause, + ...cleanupOptions, diagnostics: { phase, path, diff --git a/src/evm/EvmoleInterfaceProvider.ts b/src/evm/EvmoleInterfaceProvider.ts index 7437edc23..c59427e6a 100644 --- a/src/evm/EvmoleInterfaceProvider.ts +++ b/src/evm/EvmoleInterfaceProvider.ts @@ -13,6 +13,8 @@ import type { EvmInterfacePort, } from "../application/evm/EvmInterfacePort.js"; import { readStableArtifact } from "../artifacts/readStableArtifact.js"; +import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; +import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { OwnedCommandFailure } from "../process/OwnedCommand.js"; import type { AnalysisError, @@ -78,6 +80,7 @@ type Launcher = NonNullable[2]>["launcher"]; /** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */ export class EvmoleInterfaceProvider implements EvmInterfacePort { + readonly #resources = new ArtifactResourceScope(); #tail: Promise = Promise.resolve(); #closing = false; #closePromise: Promise | undefined; @@ -102,9 +105,14 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { options?: ExecutionOptions, ): Promise> { if (this.#closing) return Promise.resolve(err(this.#closedError())); - const operation = this.#tail.then(() => - this.#closing ? err(this.#closedError()) : this.#inspect(input, options), - ); + const operation = this.#tail.then(async () => { + if (this.#closing) return err(this.#closedError()); + try { + return await this.#resources.run(() => this.#inspect(input, options)); + } catch (cause: unknown) { + return err(evmInterfaceFailure(cause, "artifact-read", input.path)); + } + }); this.#tail = operation.then( () => undefined, () => undefined, @@ -180,6 +188,8 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { input.path, EVM_INTERFACE_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); phase = "worker"; root = await this.createRuntime(); @@ -243,15 +253,27 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal, + undefined, + this.#resources, ); reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8"))); } catch (cause: unknown) { + const cleanup = + cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; if (options?.signal?.aborted) - throw new AnalysisCancelledError(OPERATION, { capturedOutput }); + throw new AnalysisCancelledError(OPERATION, { + cause, + capturedOutput, + ...(cleanup === undefined ? {} : { cleanup }), + }); throw new AnalysisOutputError( OPERATION, `Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`, - { cause, capturedOutput }, + { + cause, + capturedOutput, + ...(cleanup === undefined ? {} : { cleanup }), + }, ); } if (!reply.ok) { @@ -355,6 +377,7 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { if (cause instanceof OwnedCommandFailure) processOwner = cause.cleanupOwner; let fileFailure: EvmFileSizeFailureEvidence | undefined; + let markerCleanupFailure: ArtifactReaderFailure | undefined; if ( cause instanceof OwnedCommandFailure && cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT && @@ -365,6 +388,9 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { const marker = await readStableArtifact( join(root.path, "resource.failure"), 1, + undefined, + undefined, + this.#resources, ); if (!marker.bytes.equals(Buffer.from("F"))) throw new Error( @@ -372,6 +398,14 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { ); fileFailure = { verified: true, failure: null }; } catch (markerFailure: unknown) { + if ( + markerFailure instanceof ArtifactReaderFailure && + markerFailure.cleanup !== undefined + ) + markerCleanupFailure = ArtifactReaderFailure.withCleanup( + cause, + markerFailure.cleanup, + ); fileFailure = { verified: false, failure: @@ -382,23 +416,36 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { } } result = err( - options?.signal?.aborted && - (cause === options.signal.reason || - (cause instanceof Error && cause.name === "AbortError")) - ? new AnalysisCancelledError( - OPERATION, - retainedOutput === undefined - ? undefined - : { capturedOutput: retainedOutput }, - ) - : evmInterfaceFailure( - cause, - phase, + markerCleanupFailure !== undefined + ? evmInterfaceFailure( + markerCleanupFailure, + "artifact-read", input.path, workerLimits, limiter, fileFailure, - ), + ) + : options?.signal?.aborted && + (cause === options.signal.reason || + (cause instanceof Error && cause.name === "AbortError")) + ? new AnalysisCancelledError(OPERATION, { + cause, + ...(retainedOutput === undefined + ? {} + : { capturedOutput: retainedOutput }), + ...(cause instanceof ArtifactReaderFailure && + cause.cleanup !== undefined + ? { cleanup: cause.cleanup } + : {}), + }) + : evmInterfaceFailure( + cause, + phase, + input.path, + workerLimits, + limiter, + fileFailure, + ), ); } if (processOwner !== undefined) { @@ -447,8 +494,37 @@ export class EvmoleInterfaceProvider implements EvmInterfacePort { this.#closing = true; this.#closePromise ??= this.#tail .then(async () => { - const failure = await this.#retire(); - if (failure !== undefined) throw failure; + const outcomes = await Promise.allSettled([ + this.#retire(), + this.#resources.close(), + ]); + const failures = outcomes.flatMap((outcome) => + outcome.status === "rejected" + ? [outcome.reason] + : outcome.value === undefined + ? [] + : [outcome.value], + ); + if (failures.length > 0) { + const resources = failures.flatMap((failure) => + failure instanceof ProviderCleanupError + ? failure.cleanupResources + : failure instanceof ArtifactReaderFailure && + failure.cleanup !== undefined + ? failure.cleanup.resources + : ["artifact-resources"], + ); + throw new ProviderCleanupError( + EVMOLE_PROVIDER_IDENTITY.id, + [...new Set(resources)], + { + failures: failures.map((failure) => + failure instanceof Error ? failure.message : String(failure), + ), + }, + { operation: OPERATION, cause: new AggregateError(failures) }, + ); + } }) .catch((cause: unknown) => { this.#closePromise = undefined; diff --git a/src/go/GoBinaryProvider.ts b/src/go/GoBinaryProvider.ts index a1c0cc6a3..466136f3f 100644 --- a/src/go/GoBinaryProvider.ts +++ b/src/go/GoBinaryProvider.ts @@ -1,5 +1,7 @@ import { readStableArtifact } from "../artifacts/readStableArtifact.js"; +import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import type { ExecutionOptions } from "../application/AnalysisProvider.js"; import type { GoBinaryPort } from "../application/go/GoBinaryPort.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; @@ -18,6 +20,7 @@ import { type InspectGoBinaryInput, } from "../domain/go/goBinary.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { err, ok, type Result } from "../domain/result.js"; import { readGoBinaryImage, @@ -36,13 +39,19 @@ const OPERATION = "inspect_go_binary"; const INPUT_BYTES = 256 * 1024 * 1024; const OUTPUT_BYTES = 8 * 1024 * 1024; -const failureFor = ( +const failureForPrimary = ( cause: unknown, path: string, signal?: AbortSignal, ): AnalysisError => { if (cause instanceof AnalysisError) return cause; - if (signal?.aborted) return new AnalysisCancelledError(OPERATION); + if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity") + return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { + cause, + }); + if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") + return new AnalysisCancelledError(OPERATION, { cause }); + if (signal?.aborted) return new AnalysisCancelledError(OPERATION, { cause }); if (cause instanceof GoBinaryResourceFailure) return new AnalysisResourceConstraintError( OPERATION, @@ -64,12 +73,6 @@ const failureFor = ( }, ]); if (cause instanceof ArtifactReaderFailure) { - if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { - cause, - }); - if (cause.reason === "cancelled") - return new AnalysisCancelledError(OPERATION); if (cause.reason === "limit") return new AnalysisResourceConstraintError( OPERATION, @@ -110,6 +113,23 @@ const failureFor = ( }); }; +const failureFor = ( + cause: unknown, + path: string, + signal?: AbortSignal, +): AnalysisError => { + const primary = failureForPrimary(cause, path, signal); + if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined) + return primary; + const cleanup = new ProviderCleanupError( + GO_BINARY_PROVIDER_IDENTITY.id, + cause.cleanup.resources, + { reason: cause.cleanup.reason }, + { operation: OPERATION, cause }, + ); + return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION); +}; + const outputLimit = (path: string) => new AnalysisResourceConstraintError( OPERATION, @@ -121,6 +141,11 @@ const outputLimit = (path: string) => /** Stable in-process metadata inspection without subprocesses, temporary files or Go installation. */ export class GoBinaryProvider implements GoBinaryPort { readonly identity = GO_BINARY_PROVIDER_IDENTITY; + readonly #resources = new ArtifactResourceScope(); + + close(): Promise { + return this.#resources.close(); + } /** Read complete compiler/module metadata while preserving original byte identity and source ranges. */ async inspect( @@ -128,10 +153,14 @@ export class GoBinaryProvider implements GoBinaryPort { options?: ExecutionOptions, ): Promise> { try { - const snapshot = await readStableArtifact( - input.path, - INPUT_BYTES, - options?.signal, + const snapshot = await this.#resources.run(() => + readStableArtifact( + input.path, + INPUT_BYTES, + options?.signal, + undefined, + this.#resources, + ), ); options?.signal?.throwIfAborted(); const image = readGoBinaryImage(snapshot.bytes); diff --git a/src/native/pe/PeResourcesProvider.ts b/src/native/pe/PeResourcesProvider.ts index 4326cb3b7..4f31256d9 100644 --- a/src/native/pe/PeResourcesProvider.ts +++ b/src/native/pe/PeResourcesProvider.ts @@ -1,5 +1,7 @@ import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; +import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import type { PeResourcesPort } from "../../application/binaryDiagnostics/PeResourcesPort.js"; import type { ExecutionOptions } from "../../application/AnalysisProvider.js"; import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; @@ -12,19 +14,29 @@ import { } from "../../domain/analysisErrorCore.js"; import type { InspectPeResourcesInput } from "../../domain/native/peResources.js"; import { err, ok } from "../../domain/result.js"; +import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; import { PE_RESOURCES_PROVIDER } from "../../application/InvestigationProviders.js"; import { parsePeResources } from "./PeResourceParser.js"; /** Portable parser over one bounded, identity-checked regular file. */ export class PeResourcesProvider implements PeResourcesPort { readonly identity = PE_RESOURCES_PROVIDER; + readonly #resources = new ArtifactResourceScope(); + + close(): Promise { + return this.#resources.close(); + } async inspect(input: InspectPeResourcesInput, options?: ExecutionOptions) { try { - const snapshot = await readStableArtifact( - input.path, - input.max_file_bytes, - options?.signal, + const snapshot = await this.#resources.run(() => + readStableArtifact( + input.path, + input.max_file_bytes, + options?.signal, + undefined, + this.#resources, + ), ); return ok( await parsePeResources( @@ -44,12 +56,21 @@ export class PeResourcesProvider implements PeResourcesPort { } } -const peResourcesFailure = ( +const peResourcesFailurePrimary = ( cause: unknown, input: InspectPeResourcesInput, signal: AbortSignal | undefined, ) => { const operation = "inspect_pe_resources"; + if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity") + return new AnalysisArtifactChangedError( + operation, + input.path, + cause.message, + { cause }, + ); + if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") + return new AnalysisCancelledError(operation, { cause }); if (signal?.aborted) return new AnalysisCancelledError(operation, { cause }); if (cause instanceof ArtifactReaderFailure) { @@ -64,13 +85,6 @@ const peResourcesFailure = ( }, { cause }, ); - if (cause.reason === "integrity") - return new AnalysisArtifactChangedError( - operation, - input.path, - cause.message, - { cause }, - ); if (cause.reason === "path" || cause.reason === "format") return new AnalysisInputError(operation, { cause }, [ { @@ -79,8 +93,6 @@ const peResourcesFailure = ( message: cause.message, }, ]); - if (cause.reason === "cancelled") - return new AnalysisCancelledError(operation, { cause }); } if (cause instanceof Error && "code" in cause) { @@ -106,3 +118,24 @@ const peResourcesFailure = ( { cause }, ); }; + +const peResourcesFailure = ( + cause: unknown, + input: InspectPeResourcesInput, + signal: AbortSignal | undefined, +) => { + const primary = peResourcesFailurePrimary(cause, input, signal); + if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined) + return primary; + const cleanup = new ProviderCleanupError( + PE_RESOURCES_PROVIDER.id, + cause.cleanup.resources, + { reason: cause.cleanup.reason }, + { operation: "inspect_pe_resources", cause }, + ); + return analysisErrorWithCleanupFailure( + primary, + cleanup, + "inspect_pe_resources", + ); +}; diff --git a/src/native/pwndbg/PwndbgCoreContext.ts b/src/native/pwndbg/PwndbgCoreContext.ts index 0ef29cd9b..db8386d26 100644 --- a/src/native/pwndbg/PwndbgCoreContext.ts +++ b/src/native/pwndbg/PwndbgCoreContext.ts @@ -17,6 +17,7 @@ import { type RecordedCrash, } from "../../domain/native/recordedCrash.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; +import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { capturedPwntoolsOutput, @@ -46,6 +47,7 @@ const replySchema = z.discriminatedUnion("ok", [ export const inspectPwndbgCore = async ({ environment, rootPath, + resources, diagnostics, options, runCommand, @@ -53,6 +55,7 @@ export const inspectPwndbgCore = async ({ }: { readonly environment: Readonly; readonly rootPath: string; + readonly resources: ArtifactResourceScope; readonly diagnostics: AnalysisCapturedOutput; readonly options: ExecutionOptions | undefined; readonly runCommand: PwntoolsCommand; @@ -178,11 +181,14 @@ export const inspectPwndbgCore = async ({ replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal, + undefined, + resources, ); reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8"))); } catch (cause: unknown) { if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION, { + cause, capturedOutput: recordedCrashStageOutput(diagnostics, output), }); throw new AnalysisOutputError( @@ -226,22 +232,22 @@ export const inspectPwndbgCore = async ({ return { ...reply.value, diagnostics: output }; } catch (cause: unknown) { if (cause instanceof AnalysisError && cause.cleanupIncomplete) throw cause; - if ( + const primary = options?.signal?.aborted && (cause === options.signal.reason || (cause instanceof Error && cause.name === "AbortError")) - ) - throw new AnalysisCancelledError(OPERATION, { - capturedOutput: recordedCrashStageOutput(diagnostics, output), - }); - throw pwntoolsDecoderFailure( - cause, - "debugger", - gdb, - environment.REA_PWNTOOLS_PYTHON ?? "", - await readPwntoolsFailureEvidence(cause, stage), - failureContext, - ); + ? new AnalysisCancelledError(OPERATION, { + capturedOutput: recordedCrashStageOutput(diagnostics, output), + }) + : pwntoolsDecoderFailure( + cause, + "debugger", + gdb, + environment.REA_PWNTOOLS_PYTHON ?? "", + await readPwntoolsFailureEvidence(cause, stage, resources), + failureContext, + ); + throw primary; } }; diff --git a/src/native/pwntools/PwntoolsDecoder.ts b/src/native/pwntools/PwntoolsDecoder.ts index d8cad3d2e..169f25601 100644 --- a/src/native/pwntools/PwntoolsDecoder.ts +++ b/src/native/pwntools/PwntoolsDecoder.ts @@ -16,6 +16,8 @@ import type { AnalysisPartialObservation, } from "../../domain/analysisErrorBase.js"; import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; +import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; +import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisCancelledError, @@ -78,6 +80,7 @@ export interface PwntoolsDecoderProfile< readonly payload: Payload; readonly snapshot: { readonly bytes: Buffer; readonly sha256: string }; readonly rootPath: string; + readonly resources: ArtifactResourceScope; readonly diagnostics: AnalysisCapturedOutput; readonly options: ExecutionOptions | undefined; readonly runCommand: PwntoolsCommand; @@ -96,6 +99,7 @@ export class PwntoolsDecoder< symbol, "admitted" | "cancelled" >(); + readonly #resources = new ArtifactResourceScope(); #closing = false; #closePromise: Promise | undefined; #pendingCleanup: @@ -244,6 +248,8 @@ export class PwntoolsDecoder< input.path, PWNTOOLS_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); phase = "decoder"; root = await this.createRuntime(); @@ -298,11 +304,16 @@ export class PwntoolsDecoder< replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal, + undefined, + this.#resources, ); reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8"))); } catch (cause: unknown) { if (options?.signal?.aborted) - throw new AnalysisCancelledError(OPERATION, { capturedOutput }); + throw new AnalysisCancelledError(OPERATION, { + cause, + capturedOutput, + }); throw new AnalysisOutputError( OPERATION, `Owned pwntools decoder reply failed for ${input.path}: ${cause instanceof z.ZodError ? cause.issues[0]?.message + " at " + (cause.issues[0]?.path.map(String).join(".") ?? "root") : cause instanceof Error ? cause.message : String(cause)}`, @@ -369,6 +380,7 @@ export class PwntoolsDecoder< payload: reply.value, snapshot, rootPath: root.path, + resources: this.#resources, diagnostics: capturedOutput, options, runCommand: (spawn, classifyFailure) => @@ -385,12 +397,18 @@ export class PwntoolsDecoder< } return err(cause); } - const evidence = await readPwntoolsFailureEvidence(cause, root?.path); - result = err( + const evidence = await readPwntoolsFailureEvidence( + cause, + root?.path, + this.#resources, + ); + const primary = options?.signal?.aborted && - (cause === options.signal.reason || - (cause instanceof Error && cause.name === "AbortError")) - ? new AnalysisCancelledError(OPERATION) + (cause === options.signal.reason || + (cause instanceof Error && cause.name === "AbortError") || + (cause instanceof ArtifactReaderFailure && + cause.cleanup !== undefined)) + ? new AnalysisCancelledError(OPERATION, { cause }) : pwntoolsDecoderFailure( cause, phase, @@ -398,8 +416,8 @@ export class PwntoolsDecoder< executablePath, evidence, context, - ), - ); + ); + result = err(primary); } if (this.#pendingCleanup !== undefined) { this.#pendingCleanup.failure = result.ok ? undefined : result.error; @@ -483,7 +501,39 @@ export class PwntoolsDecoder< this.#closing = true; this.#closePromise ??= this.#tail .then(async () => { - const failure = await this.#retire(); + let failure: AnalysisError | undefined; + try { + failure = await this.#retire(); + } catch (cause: unknown) { + failure = new ProviderCleanupError( + this.identity.id, + [this.#pendingCleanup?.root?.path ?? "pwntools decoder"], + { reason: cause instanceof Error ? cause.message : String(cause) }, + { operation: this.profile.operation, cause }, + ); + } + try { + await this.#resources.close(); + } catch (cause: unknown) { + const observation = ArtifactReaderFailure.cleanupObservation( + cause, + "pwntools artifact read", + ); + const resourceFailure = new ProviderCleanupError( + this.identity.id, + observation.resources, + { reason: observation.reason }, + { operation: this.profile.operation, cause }, + ); + failure = + failure === undefined + ? resourceFailure + : analysisErrorWithCleanupFailure( + failure, + resourceFailure, + this.profile.operation, + ); + } if (failure !== undefined) throw failure; }) .catch((cause: unknown) => { @@ -502,8 +552,8 @@ export class PwntoolsDecoder< } async #completeCleanup( - retire: () => Promise, - ): Promise { + retire: () => Promise, + ): Promise { const failure = await retire(); return failure !== undefined && this.#closing ? retire() : failure; } @@ -548,18 +598,46 @@ export class PwntoolsDecoder< return undefined; } - async #retire(): Promise { - const failure = await this.#retireProcess(); - if (failure !== undefined) return failure; + async #retire(): Promise { + let failure: AnalysisError | undefined; + try { + await this.#resources.retryCleanup(); + } catch (cause: unknown) { + const observation = ArtifactReaderFailure.cleanupObservation( + cause, + "pwntools artifact read", + ); + failure = new ProviderCleanupError( + this.identity.id, + observation.resources, + { reason: observation.reason }, + { + operation: this.profile.operation, + cause, + ...(this.#pendingCleanup?.observation === undefined + ? {} + : { partialObservation: this.#pendingCleanup.observation }), + }, + ); + } + const processFailure = await this.#retireProcess(); + if (processFailure !== undefined) { + return failure === undefined + ? processFailure + : analysisErrorWithCleanupFailure( + failure, + processFailure, + this.profile.operation, + ); + } const pending = this.#pendingCleanup; - if (pending === undefined) return undefined; - if (pending.root !== undefined) { + if (pending?.root !== undefined) { const root = pending.root; try { await root.close(); pending.root = undefined; } catch (cause: unknown) { - return new ProviderCleanupError( + const rootFailure = new ProviderCleanupError( this.identity.id, [root.path], { @@ -580,9 +658,18 @@ export class PwntoolsDecoder< : { partialObservation: pending.observation }), }, ); + failure = + failure === undefined + ? rootFailure + : analysisErrorWithCleanupFailure( + failure, + rootFailure, + this.profile.operation, + ); } } - this.#pendingCleanup = undefined; - return undefined; + if (!this.#resources.hasPending && pending?.root === undefined) + this.#pendingCleanup = undefined; + return failure; } } diff --git a/src/native/pwntools/PwntoolsRecordedCrashProvider.ts b/src/native/pwntools/PwntoolsRecordedCrashProvider.ts index ffc10d13b..24cee7314 100644 --- a/src/native/pwntools/PwntoolsRecordedCrashProvider.ts +++ b/src/native/pwntools/PwntoolsRecordedCrashProvider.ts @@ -48,6 +48,7 @@ export class PwntoolsRecordedCrashProvider payload, snapshot, rootPath, + resources, diagnostics, options, runCommand, @@ -120,6 +121,7 @@ export class PwntoolsRecordedCrashProvider const context = await inspectPwndbgCore({ environment, rootPath, + resources, diagnostics, options, runCommand, diff --git a/src/native/pwntools/PwntoolsResourceLimits.ts b/src/native/pwntools/PwntoolsResourceLimits.ts index dcbe91d5a..3b379779f 100644 --- a/src/native/pwntools/PwntoolsResourceLimits.ts +++ b/src/native/pwntools/PwntoolsResourceLimits.ts @@ -7,6 +7,7 @@ import { } from "./PwntoolsRelease.js"; import { z } from "zod"; import { PWNTOOLS_LIMITS } from "./PwntoolsRelease.js"; +import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; /** Actual limits reported by the owned bridge after lowering inherited soft limits. */ export const pwntoolsResourceLimitsSchema = z.strictObject({ @@ -42,6 +43,7 @@ export interface PwntoolsFailureEvidence { export const readPwntoolsFailureEvidence = async ( cause: unknown, rootPath?: string, + resources?: ArtifactResourceScope, ): Promise => { let limitReport: PwntoolsLimitReport | undefined; let marker: PwntoolsFailureEvidence["marker"]; @@ -56,6 +58,9 @@ export const readPwntoolsFailureEvidence = async ( const reported = await readStableArtifact( join(rootPath, "resource.failure"), 1, + undefined, + undefined, + resources, ); const expected = cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT ? "M" : "F"; @@ -90,6 +95,9 @@ export const readPwntoolsFailureEvidence = async ( const reported = await readStableArtifact( join(rootPath, "limits.json"), 4096, + undefined, + undefined, + resources, ); limitReport = { limits: pwntoolsResourceLimitsSchema.parse( diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 777028cf8..c73071bea 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -9,6 +9,7 @@ import { wasmArtifactModule } from "../composition/wasm.js"; import { registerWasmTools } from "./registerWasmTools.js"; import { snapshotEnvironment } from "../process/snapshotEnvironment.js"; import { createPeResourcesService } from "../composition/binaryDiagnostics.js"; +import type { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js"; import { registerPeResourcesTool } from "./registerPeResourcesTool.js"; import type { EvmInterfaceService } from "../application/evm/EvmInterfaceService.js"; import { evmInterfaceModule } from "../composition/evm.js"; @@ -280,6 +281,10 @@ export const createServer = ( options.webSourceLocation ?? createWebSourceLocationService(environment); const webModuleTrace = options.webModuleTrace ?? createWebModuleTraceService(environment); + const goBinary = options.goBinary ?? createGoBinaryService(); + const peResources = createPeResourcesService(); + const webNetworkCapture = + options.webNetworkCapture ?? createWebNetworkCaptureService(environment); const javascriptRecovery = options.javascriptRecovery ?? createJavaScriptRecoveryProvider(environment); const artifactResources = new ArtifactResourceScope(); @@ -345,6 +350,9 @@ export const createServer = ( recordedCrash.close(), webSourceLocation.close(), webModuleTrace.close(), + goBinary.close(), + peResources.close(), + webNetworkCapture.close(), javascriptRecovery.close?.() ?? Promise.resolve(), artifactResources.close(), firmwareAnalysis.close(), @@ -388,6 +396,9 @@ export const createServer = ( recordEvidenceWithUnknown, withAdmittedAnalysis: analysisAdmission, artifactResources, + goBinary, + peResources, + webNetworkCapture, }; registerBinaryAnalysisTools(toolContext); registerFridaTools( @@ -517,6 +528,9 @@ const registerConfiguredAnalysisTools = ( evidenceById, recordEvidence, withAdmittedAnalysis, + goBinary, + peResources, + webNetworkCapture, }: ServerToolContext, android: AndroidAnalysisPort, wasmArtifact: Pick, @@ -556,14 +570,14 @@ const registerConfiguredAnalysisTools = ( ); registerPeResourcesTool( server, - createPeResourcesService(), + peResources, toolLogger, recordEvidence, withAdmittedAnalysis, ); registerGoTools( server, - options.goBinary ?? createGoBinaryService(), + goBinary, toolLogger, recordEvidence, withAdmittedAnalysis, @@ -628,7 +642,7 @@ const registerConfiguredAnalysisTools = ( ); registerWebNetworkCaptureTool( server, - options.webNetworkCapture ?? createWebNetworkCaptureService(environment), + webNetworkCapture, toolLogger, recordEvidence, withAdmittedAnalysis, @@ -673,6 +687,9 @@ const createSessionRecorders = ( }); interface ServerToolContext extends ReturnType { + readonly goBinary: GoBinaryService; + readonly peResources: PeResourcesService; + readonly webNetworkCapture: WebNetworkCaptureService; readonly artifactResources: ArtifactResourceScope; readonly server: EvidenceMcpServer; readonly session: BinarySessionPort | undefined; diff --git a/src/wasm/WabtArtifactProvider.test.ts b/src/wasm/WabtArtifactProvider.test.ts index 94c4e0c95..428cf8cbd 100644 --- a/src/wasm/WabtArtifactProvider.test.ts +++ b/src/wasm/WabtArtifactProvider.test.ts @@ -1,6 +1,6 @@ import { access, chmod, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; -import { expect, it } from "vitest"; +import { expect, it, vi } from "vitest"; import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; import { WabtArtifactProvider } from "./WabtArtifactProvider.js"; import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; @@ -9,6 +9,33 @@ import { spawnOwnedProviderProcess } from "../process/ProviderProcess.js"; import { OwnedCommandFailure } from "../process/OwnedCommand.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +const fileCloseFailure = vi.hoisted(() => ({ + selectedPath: "", + attempts: 0, + failFirst: false, +})); + +vi.mock("node:fs/promises", async (importOriginal) => { + const fs = await importOriginal(); + return { + ...fs, + open: async (...args: Parameters) => { + const handle = await fs.open(...args); + if (String(args[0]) !== fileCloseFailure.selectedPath) return handle; + const close = handle.close.bind(handle); + handle.close = async () => { + fileCloseFailure.attempts += 1; + if (fileCloseFailure.failFirst) { + fileCloseFailure.failFirst = false; + throw new Error("injected WABT input close failure"); + } + return close(); + }; + return handle; + }, + }; +}); + const failureTags: Readonly> = { invalid: "AnalysisInputError", timeout: "AnalysisTimeoutError", @@ -20,6 +47,82 @@ const failureTags: Readonly> = { "wat-warning": "AnalysisOutputError", }; +const assertCleanupRecovery = async (options: { + readonly provider: WabtArtifactProvider; + readonly result: Awaited>; + readonly path: string; + readonly runtimePath: string; + readonly cleanupAttempts: () => number; + readonly runtimeCreations: () => number; +}): Promise => { + expect(options.result).toMatchObject({ + error: { + cleanupIncomplete: true, + cleanupResources: [options.runtimePath], + partialObservation: { normalized_result: { validation: "valid" } }, + }, + }); + await expect(access(options.runtimePath)).resolves.toBeUndefined(); + const blocked = await options.provider.inspect({ + path: options.path, + glue_paths: [], + candidate_paths: [], + }); + expect(blocked).toMatchObject({ + ok: false, + error: { + cleanupIncomplete: true, + cleanupResources: [options.runtimePath], + }, + }); + expect(options.cleanupAttempts()).toBe(2); + expect(options.runtimeCreations()).toBe(1); + await options.provider.close(); + expect(options.cleanupAttempts()).toBe(3); + await expect(access(options.runtimePath)).rejects.toMatchObject({ + code: "ENOENT", + }); +}; + +const assertModeOutcome = ( + mode: string, + result: Awaited>, + path: string, +): void => { + if (mode === "success") + expect(result).toMatchObject({ + ok: true, + value: { + result: { + artifact: { path, bytes: 76 }, + validation: "valid", + runtime_execution: "not-performed", + }, + }, + }); + else + expect(result).toMatchObject({ + ok: false, + error: { _tag: failureTags[mode] }, + }); + if (mode === "invalid") + expect(result).toMatchObject({ + error: { capturedOutput: { stderr: "module.wasm: invalid bytes\n" } }, + }); + if (mode === "malformed-wat" || mode === "wat-warning") + expect(result).toMatchObject({ + error: { + capturedOutput: { + stdout: + mode === "malformed-wat" + ? "unexpected decoder output\n" + : '(module (@custom "test" "payload"))\n', + stderr: mode === "wat-warning" ? "decoder warning\n" : "", + }, + }, + }); +}; + it("returns actionable unavailable without creating a workspace when tools are absent", async () => { const provider = new WabtArtifactProvider({}, undefined, () => { throw new Error("Must not allocate"); @@ -39,6 +142,88 @@ it("returns actionable unavailable without creating a workspace when tools are a }); }); +it("retries a retained input descriptor before admitting the next WABT operation", async () => { + const root = await createTestTempDirectory("rea-wabt-read-cleanup-"); + const path = join(root, "selected.wasm"); + await writeFile(path, Buffer.alloc(76, 1)); + for (const tool of ["wasm-validate", "wasm-objdump", "wasm2wat"]) + await writeFile(join(root, tool), "source-owned executable seam", { + mode: 0o700, + }); + const dump = await readFile( + new URL("../../tests/fixtures/wasm/objdump.txt", import.meta.url), + "utf8", + ); + const provider = new WabtArtifactProvider( + { REA_WABT_BIN_DIRECTORY: root }, + async (input) => { + const version = input.arguments[0] === "--version"; + const stdout = version + ? "1.0.42\n" + : input.command.includes("wasm-objdump") + ? dump + : input.command.includes("wasm2wat") + ? '(module (@custom "test" "payload"))\n' + : ""; + const launched = await spawnOwnedProviderProcess({ + ...input, + command: process.execPath, + arguments: [ + "-e", + `process.stdout.write(${JSON.stringify(stdout)}); process.exit(0);`, + ], + expectedCommand: null, + }); + return launched; + }, + ); + fileCloseFailure.selectedPath = path; + fileCloseFailure.attempts = 0; + fileCloseFailure.failFirst = true; + try { + const first = await provider.inspect({ + path, + candidate_paths: [], + glue_paths: [], + }); + expect(first).toMatchObject({ + ok: false, + error: { + cleanupIncomplete: true, + cleanupResources: [path], + cause: { message: "injected WABT input close failure" }, + }, + }); + expect(fileCloseFailure.attempts).toBe(1); + + const retried = await provider.inspect({ + path, + candidate_paths: [], + glue_paths: [], + }); + expect(retried.ok).toBe(true); + expect(fileCloseFailure.attempts).toBeGreaterThan(1); + + fileCloseFailure.failFirst = true; + const closeRetry = await provider.inspect({ + path, + candidate_paths: [], + glue_paths: [], + }); + expect(closeRetry).toMatchObject({ + ok: false, + error: { cleanupIncomplete: true, cleanupResources: [path] }, + }); + const beforeClose = fileCloseFailure.attempts; + await provider.close(); + expect(fileCloseFailure.attempts).toBeGreaterThan(beforeClose); + } finally { + fileCloseFailure.selectedPath = ""; + fileCloseFailure.failFirst = false; + await provider.close(); + } +}); + it.each([false, true])( "reports an unavailable private runtime root with retryable=%s without a misleading WABT remediation", async (retryable) => { @@ -110,6 +295,7 @@ it.each([ "utf8", ); let runtimePath = ""; + let runtimeCreations = 0; let acquiredPid: number | undefined; let cleanupAttempts = 0; const controller = new AbortController(); @@ -168,6 +354,7 @@ it.each([ return launched; }, async () => { + runtimeCreations += 1; const root = await PrivateRuntimeRoot.create({ prefix: "rea-wabt-owned-test-", }); @@ -186,53 +373,17 @@ it.each([ { path, glue_paths: [], candidate_paths: [] }, { signal: controller.signal }, ); - if (mode === "success") - expect(result).toMatchObject({ - ok: true, - value: { - result: { - artifact: { path, bytes: 76 }, - validation: "valid", - runtime_execution: "not-performed", - }, - }, - }); - else - expect(result).toMatchObject({ - ok: false, - error: { _tag: failureTags[mode] }, - }); - if (mode === "invalid") - expect(result).toMatchObject({ - error: { capturedOutput: { stderr: "module.wasm: invalid bytes\n" } }, - }); + assertModeOutcome(mode, result, path); if (mode === "cleanup") { - expect(result).toMatchObject({ - error: { - cleanupIncomplete: true, - cleanupResources: [runtimePath], - partialObservation: { normalized_result: { validation: "valid" } }, - }, + await assertCleanupRecovery({ + provider, + result, + path, + runtimePath, + cleanupAttempts: () => cleanupAttempts, + runtimeCreations: () => runtimeCreations, }); - await expect(access(runtimePath)).resolves.toBeUndefined(); - await expect(provider.close()).rejects.toMatchObject({ - cleanupIncomplete: true, - }); - await expect(access(runtimePath)).resolves.toBeUndefined(); - await provider.close(); } - if (mode === "malformed-wat" || mode === "wat-warning") - expect(result).toMatchObject({ - error: { - capturedOutput: { - stdout: - mode === "malformed-wat" - ? "unexpected decoder output\n" - : '(module (@custom "test" "payload"))\n', - stderr: mode === "wat-warning" ? "decoder warning\n" : "", - }, - }, - }); await expect(access(runtimePath)).rejects.toMatchObject({ code: "ENOENT" }); expect(await readFile(path)).toEqual(bytes); if (acquiredPid !== undefined) { diff --git a/src/wasm/WabtArtifactProvider.ts b/src/wasm/WabtArtifactProvider.ts index fe79914ca..c5f0aef53 100644 --- a/src/wasm/WabtArtifactProvider.ts +++ b/src/wasm/WabtArtifactProvider.ts @@ -9,6 +9,8 @@ import type { WasmArtifactPort, } from "../application/wasm/WasmArtifactPort.js"; import { readStableArtifact } from "../artifacts/readStableArtifact.js"; +import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; +import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import type { AnalysisError, AnalysisCapturedOutput, @@ -16,6 +18,7 @@ import type { import { AnalysisCancelledError, AnalysisArtifactChangedError, + AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js"; @@ -41,9 +44,7 @@ const digest = (text: string) => createHash("sha256").update(text).digest("hex"); /** Run caller-supplied WABT against private copies of exactly selected bytes. */ export class WabtArtifactProvider implements WasmArtifactPort { - readonly #pendingRoots = new Set< - Pick - >(); + readonly #resources = new ArtifactResourceScope(); constructor( readonly environment: Readonly = process.env, readonly launcher?: Launcher, @@ -53,29 +54,51 @@ export class WabtArtifactProvider implements WasmArtifactPort { ) {} /** Retry retained cleanup without discarding roots that still cannot be removed. */ async close(): Promise { - const failures: { path: string; reason: string }[] = []; - for (const root of this.#pendingRoots) { - try { - await root.close(); - this.#pendingRoots.delete(root); - } catch (cause: unknown) { - failures.push({ - path: root.path, - reason: cause instanceof Error ? cause.message : String(cause), - }); - } - } - if (failures.length > 0) + try { + await this.#resources.close(); + } catch (cause: unknown) { + const cleanup = + cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; throw new ProviderCleanupError( WABT_PROVIDER_IDENTITY.id, - failures.map(({ path }) => path), - { failures }, - { operation: OPERATION }, + cleanup?.resources ?? ["artifact-resources"], + { + reason: + cleanup?.reason ?? + (cause instanceof Error ? cause.message : String(cause)), + }, + { operation: OPERATION, cause }, ); + } } async inspect( input: InspectWasmArtifactInput, options?: ExecutionOptions, + ): Promise> { + try { + return await this.#resources.run(() => this.#inspect(input, options)); + } catch (cause: unknown) { + if ( + cause instanceof ArtifactReaderFailure && + cause.reason === "unavailable" && + cause.cleanup === undefined + ) + return err(this.#closedError()); + return err(wabtFailure(cause, "artifact", input.path)); + } + } + + #closedError(): AnalysisCapabilityUnavailableError { + return new AnalysisCapabilityUnavailableError( + WABT_PROVIDER_IDENTITY.id, + OPERATION, + "Provider is closing", + ); + } + + async #inspect( + input: InspectWasmArtifactInput, + options?: ExecutionOptions, ): Promise> { let root: Pick | undefined; let phase: "configuration" | "artifact" | "producer" = "configuration"; @@ -83,7 +106,6 @@ export class WabtArtifactProvider implements WasmArtifactPort { let capturedOutput: AnalysisCapturedOutput | undefined; try { if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION); - await this.close(); const directory = this.environment.REA_WABT_BIN_DIRECTORY ?? ""; if (!isAbsolute(directory)) throw new Error( @@ -108,6 +130,8 @@ export class WabtArtifactProvider implements WasmArtifactPort { path, WABT_LIMITS.toolBytes, options?.signal, + undefined, + this.#resources, ); commands.push({ tool, @@ -130,17 +154,24 @@ export class WabtArtifactProvider implements WasmArtifactPort { snapshotPath, WABT_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); if (bytes.sha256 !== snapshotHash) throw new Error("Private WASM snapshot bytes changed."); } catch (cause: unknown) { + const cleanup = + cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; if (options?.signal?.aborted) - throw new AnalysisCancelledError(OPERATION); + throw new AnalysisCancelledError(OPERATION, { + cause, + ...(cleanup === undefined ? {} : { cleanup }), + }); throw new AnalysisArtifactChangedError( OPERATION, input.path, "Private WASM snapshot no longer matches selected byte identity.", - { cause }, + { cause, ...(cleanup === undefined ? {} : { cleanup }) }, ); } }; @@ -175,6 +206,8 @@ export class WabtArtifactProvider implements WasmArtifactPort { command.path, WABT_LIMITS.toolBytes, options?.signal, + undefined, + this.#resources, ); if (current.sha256 !== command.sha256) throw new AnalysisOutputError( @@ -200,6 +233,8 @@ export class WabtArtifactProvider implements WasmArtifactPort { input.path, WABT_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); const artifact = { path: input.path, @@ -215,6 +250,8 @@ export class WabtArtifactProvider implements WasmArtifactPort { path, WABT_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); candidates.push({ path, @@ -228,6 +265,8 @@ export class WabtArtifactProvider implements WasmArtifactPort { path, WABT_LIMITS.inputBytes, options?.signal, + undefined, + this.#resources, ); const source = new TextDecoder("utf-8", { fatal: true }).decode( bytes.bytes, @@ -395,10 +434,13 @@ export class WabtArtifactProvider implements WasmArtifactPort { ); } if (root !== undefined) { - try { - await root.close(); - } catch (cause: unknown) { - this.#pendingRoots.add(root); + const cleanup = await this.#resources.release({ + kind: "private-runtime-root", + resource: root.path, + root, + }); + if (cleanup.kind === "failed") { + const cause = cleanup.cause; const partialObservation = result.ok ? createEvidence( result.value.subject ?? undefined, diff --git a/src/wasm/WabtFailures.ts b/src/wasm/WabtFailures.ts index 4f386998f..7b6875203 100644 --- a/src/wasm/WabtFailures.ts +++ b/src/wasm/WabtFailures.ts @@ -20,12 +20,19 @@ export const wabtFailure = ( path: string, ): AnalysisError => { if (cause instanceof AnalysisError) return cause; + const artifactCleanup = + cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined; + const cleanupOptions = + artifactCleanup === undefined ? {} : { cleanup: artifactCleanup }; const reason = cause instanceof Error ? cause.message : String(cause); if ( (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") || (cause instanceof Error && cause.name === "AbortError") ) - return new AnalysisCancelledError("inspect_wasm_artifact", { cause }); + return new AnalysisCancelledError("inspect_wasm_artifact", { + cause, + ...cleanupOptions, + }); if (cause instanceof OwnedCommandFailure) { const capturedOutput = cause.snapshot === null @@ -85,6 +92,7 @@ export const wabtFailure = ( reason, { cause, + ...cleanupOptions, userMessage: `${reason} Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY; REA does not install tools.`, }, ); @@ -97,7 +105,7 @@ export const wabtFailure = ( "inspect_wasm_artifact", path, reason, - { cause }, + { cause, ...cleanupOptions }, ); if ( phase === "artifact" && @@ -109,11 +117,16 @@ export const wabtFailure = ( "inspect_wasm_artifact", path, cause.code, - { cause }, + { cause, ...cleanupOptions }, ); if (phase === "artifact") - return new AnalysisInputError("inspect_wasm_artifact", { cause }, [ - { path: ["path"], reason: "invalid_value", message: reason }, - ]); - return new AnalysisOutputError("inspect_wasm_artifact", reason, { cause }); + return new AnalysisInputError( + "inspect_wasm_artifact", + { cause, ...cleanupOptions }, + [{ path: ["path"], reason: "invalid_value", message: reason }], + ); + return new AnalysisOutputError("inspect_wasm_artifact", reason, { + cause, + ...cleanupOptions, + }); }; diff --git a/tests/boundary/browser/historicalCaptureDecoder.test.ts b/tests/boundary/browser/historicalCaptureDecoder.test.ts index 92b26d5df..e02524f8d 100644 --- a/tests/boundary/browser/historicalCaptureDecoder.test.ts +++ b/tests/boundary/browser/historicalCaptureDecoder.test.ts @@ -11,7 +11,7 @@ import { } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { expect, it, onTestFinished } from "vitest"; +import { expect, it, onTestFinished, vi } from "vitest"; import { HistoricalCaptureDecoder } from "../../../src/browser/history/HistoricalCaptureDecoder.js"; import { MitmproxyCaptureAdapter } from "../../../src/browser/history/MitmproxyCaptureAdapter.js"; import { HAR_CAPTURE_PROVIDER_IDENTITY } from "../../../src/browser/history/CaptureRelease.js"; @@ -22,6 +22,7 @@ import { import { historicalHar } from "../../fixtures/historicalHar.js"; import { decodeHarCapture } from "../../../src/browser/history/HarCapture.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; +import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; const linux = it.skipIf(process.platform !== "linux"); @@ -138,6 +139,66 @@ it("classifies an oversized selected capture before creating an owned decoder", }); }); +it("retains a failed capture reader and retries it before a fresh load", async () => { + const root = await mkdtemp(join(tmpdir(), "rea-capture-reader-close-")); + onTestFinished(() => rm(root, { recursive: true, force: true })); + const path = join(root, "input.har"); + await writeFile(path, JSON.stringify(historicalHar())); + const originalClose = OwnedFileHandle.prototype.close; + const close = vi.spyOn(OwnedFileHandle.prototype, "close"); + let allowClose = false; + let closeAttempts = 0; + close.mockImplementation(async function (this: OwnedFileHandle) { + closeAttempts += 1; + if (!allowClose) throw new Error("injected capture reader close failure"); + await originalClose.call(this); + }); + let decoderCalls = 0; + const decoder = new HistoricalCaptureDecoder( + [ + { + format: "har", + identity: HAR_CAPTURE_PROVIDER_IDENTITY, + command: async () => { + decoderCalls += 1; + return { + command: process.execPath, + arguments: ["-e", "process.exit(0)"], + }; + }, + }, + ], + process.env, + ); + const input = inspectWebNetworkCaptureInputSchema.parse({ + capture_path: path, + format: "har", + }); + try { + const first = await decoder.inspect(input); + expect(first.ok).toBe(false); + if (first.ok) throw new Error("Reader close failure must fail inspection"); + expect(first.error.cleanupResources).toContain(path); + expect(decoderCalls).toBe(0); + + const refused = await decoder.inspect(input); + expect(refused.ok).toBe(false); + if (refused.ok) throw new Error("Fresh read must wait for owner cleanup"); + expect(refused.error.cleanupIncomplete).toBe(true); + expect(refused.error.cleanupResources).toContain(path); + expect(decoderCalls).toBe(0); + expect(closeAttempts).toBe(2); + + allowClose = true; + await decoder.close(); + expect(closeAttempts).toBe(3); + } finally { + allowClose = true; + await decoder.close().catch(() => undefined); + close.mockRestore(); + } +}); + it("does not misclassify decoder filesystem failures as missing selected input", async () => { const root = await mkdtemp(join(tmpdir(), "rea-historical-command-")); onTestFinished(() => rm(root, { recursive: true, force: true })); diff --git a/tests/boundary/cli/captureCleanup.test.ts b/tests/boundary/cli/captureCleanup.test.ts index 8f34b6839..6e5882cd4 100644 --- a/tests/boundary/cli/captureCleanup.test.ts +++ b/tests/boundary/cli/captureCleanup.test.ts @@ -5,6 +5,7 @@ import { silentLogger } from "../../../src/logger.js"; import { createEvidence } from "../../../src/domain/evidence.js"; import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js"; import { err } from "../../../src/domain/result.js"; +import { AnalysisInputError } from "../../../src/domain/analysisErrorCore.js"; it.each([false, true])( "awaits cleanup retry and preserves completed output when retry failure is %s", @@ -82,6 +83,111 @@ it.each([false, true])( }, ); +it("keeps the primary CLI failure when close throws an untyped error", async () => { + const cli = Cli.create("capture-cleanup-primary-test", { sync: false }); + registerCaptureCommands( + cli, + silentLogger, + {}, + { + inspectFields: async () => { + throw new Error("Unexpected field discovery call"); + }, + inspect: async () => + err( + new AnalysisInputError("inspect_packet_capture", { + userMessage: "The selected capture input was rejected.", + }), + ), + close: async () => { + throw new Error("raw close failure"); + }, + }, + ); + let stdout = ""; + await cli.serve( + [ + "inspect-packet-capture", + "recording.pcap", + "--fields", + "ip.addr", + "--format", + "json", + ], + { + stdout: (text) => { + stdout += text; + }, + exit: () => {}, + }, + ); + expect(JSON.parse(stdout)).toMatchObject({ + code: "cleanup_incomplete", + message: "The selected capture input was rejected.", + details: { + diagnostics: { + primary_error: { code: "invalid_request" }, + }, + resources: [], + }, + }); +}); + +it("closes the service and retains an unexpected producer rejection", async () => { + const cli = Cli.create("capture-producer-rejection-test", { sync: false }); + let closed = false; + registerCaptureCommands( + cli, + silentLogger, + {}, + { + inspectFields: async () => { + throw new Error("Unexpected field discovery call"); + }, + inspect: async () => { + throw new Error("raw producer failure"); + }, + close: async () => { + closed = true; + throw new Error("raw close failure"); + }, + }, + ); + let stdout = ""; + await cli.serve( + [ + "inspect-packet-capture", + "recording.pcap", + "--fields", + "ip.addr", + "--format", + "json", + ], + { + stdout: (text) => { + stdout += text; + }, + exit: () => {}, + }, + ); + expect(closed).toBe(true); + expect(JSON.parse(stdout)).toMatchObject({ + code: "cleanup_incomplete", + details: { + diagnostics: { + primary_error: { + code: "execution_failure", + details: { + operation: "inspect_packet_capture", + provider_id: "tshark-capture", + }, + }, + cleanup_error: { code: "cleanup_incomplete" }, + }, + }, + }); +}); + it("rejects an oversized selector budget before the CLI invokes its service", async () => { const cli = Cli.create("capture-selector-test", { sync: false }); let called = false; diff --git a/tests/boundary/filesystem/stableArtifact.test.ts b/tests/boundary/filesystem/stableArtifact.test.ts index 454d9064b..3bd587ad0 100644 --- a/tests/boundary/filesystem/stableArtifact.test.ts +++ b/tests/boundary/filesystem/stableArtifact.test.ts @@ -31,9 +31,12 @@ it("reads exact binary and empty bytes and rejects symlink/size/cancellation bou }); const controller = new AbortController(); controller.abort(); - await expect(readStableArtifact(real, 3, controller.signal)).rejects.toBe( - controller.signal.reason, - ); + await expect( + readStableArtifact(real, 3, controller.signal), + ).rejects.toMatchObject({ + reason: "cancelled", + cause: controller.signal.reason, + }); }); const checkChange = async ( diff --git a/tests/boundary/filesystem/webArtifactReadOwnership.test.ts b/tests/boundary/filesystem/webArtifactReadOwnership.test.ts new file mode 100644 index 000000000..0a8791366 --- /dev/null +++ b/tests/boundary/filesystem/webArtifactReadOwnership.test.ts @@ -0,0 +1,96 @@ +import { mkdir, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect, it, onTestFinished, vi } from "vitest"; + +const injected = vi.hoisted(() => ({ + sourcePath: undefined as string | undefined, + abortController: undefined as AbortController | undefined, + failClose: false, + closeAttempts: 0, +})); + +vi.mock("node:fs/promises", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + open: async (...args: Parameters) => { + const handle = await actual.open(...args); + if (args[0] !== injected.sourcePath) return handle; + const createReadStream = handle.createReadStream.bind(handle); + handle.createReadStream = (options) => { + injected.abortController?.abort(); + return createReadStream(options); + }; + const close = handle.close.bind(handle); + handle.close = async () => { + injected.closeAttempts += 1; + if (injected.failClose) throw new Error("fixture close refusal"); + await close(); + }; + return handle; + }, + }; +}); + +import { WebModuleTraceService } from "../../../src/application/WebModuleTraceService.js"; +import { LocalWebModuleArtifacts } from "../../../src/browser/modules/WebModuleArtifacts.js"; +import { webModuleArtifactsFixture } from "../../fixtures/webModuleTrace.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +it("retains cancelled source read ownership until service close retries it", async () => { + const root = await createTestTempDirectory("rea-web-artifact-read-owner-"); + onTestFinished(async () => { + injected.sourcePath = undefined; + injected.abortController = undefined; + injected.failClose = false; + injected.closeAttempts = 0; + await rm(root, { recursive: true, force: true }); + }); + const source = 'import "./dep.js";'; + const fixture = webModuleArtifactsFixture(source); + const manifestPath = join(root, "manifest.json"); + const sourcePath = join(root, "files", "modules", "main.js"); + await mkdir(join(root, "files", "modules"), { recursive: true }); + await writeFile(sourcePath, source); + await writeFile(manifestPath, JSON.stringify(fixture.manifest)); + + injected.sourcePath = sourcePath; + injected.failClose = true; + const controller = new AbortController(); + injected.abortController = controller; + const resolver = { + resolve: vi.fn(), + close: vi.fn(async () => undefined), + }; + const service = new WebModuleTraceService( + new LocalWebModuleArtifacts(), + resolver, + ); + const input = { manifest_path: manifestPath, script_index: 0 }; + + const cancelled = await service.trace(input, { signal: controller.signal }); + expect(cancelled.ok).toBe(false); + if (cancelled.ok) throw new Error("Expected cancelled source read"); + expect(cancelled.error.cleanupIncomplete).toBe(true); + expect(cancelled.error.cleanupResources).toContain(sourcePath); + expect(resolver.resolve).not.toHaveBeenCalled(); + + injected.abortController = undefined; + const blocked = await service.trace(input); + expect(blocked.ok).toBe(false); + if (blocked.ok) throw new Error("Expected retained cleanup to block load"); + expect(blocked.error.cleanupIncomplete).toBe(true); + expect(injected.closeAttempts).toBe(2); + + await expect(service.close()).rejects.toThrow( + "Web module trace cleanup failed", + ); + expect(resolver.close).toHaveBeenCalledTimes(1); + expect(injected.closeAttempts).toBe(3); + + injected.failClose = false; + const attemptsBeforeRetry = injected.closeAttempts; + await service.close(); + expect(injected.closeAttempts).toBeGreaterThan(attemptsBeforeRetry); + expect(resolver.close).toHaveBeenCalledTimes(2); +}); diff --git a/tests/boundary/mcp/serverLifecycleMcp.test.ts b/tests/boundary/mcp/serverLifecycleMcp.test.ts index c841e08ed..cdec09a3e 100644 --- a/tests/boundary/mcp/serverLifecycleMcp.test.ts +++ b/tests/boundary/mcp/serverLifecycleMcp.test.ts @@ -34,6 +34,9 @@ import { } from "../../support/workspace/workspaceFixture.js"; import { z } from "zod"; import { createDeferred } from "../../fixtures/binarySession.js"; +import { GoBinaryService } from "../../../src/application/go/GoBinaryService.js"; +import { WebNetworkCaptureService } from "../../../src/application/WebNetworkCaptureService.js"; +import { AnalysisUnsupportedTargetError } from "../../../src/domain/analysisErrorCore.js"; const resources: Array<{ close(): Promise }> = []; @@ -334,6 +337,68 @@ it("awaits SQLite cleanup and retries its retained owner after failed server shu expect(attempts).toBe(2); }); +it("closes the bound Go and web-capture services and retries failed shutdown", async () => { + let goCalls = 0; + let goCloseAttempts = 0; + let captureCloseAttempts = 0; + let cleanupAllowed = false; + const goBinary = new GoBinaryService({ + identity: { id: "go-fixture", name: "Go fixture", version: "1" }, + inspect: async ({ path }) => { + goCalls += 1; + return err( + new AnalysisUnsupportedTargetError( + "inspect_go_binary", + path, + "fixture rejection", + ), + ); + }, + close: async () => { + goCloseAttempts += 1; + if (!cleanupAllowed) throw new Error("Go cleanup refused"); + }, + }); + const webNetworkCapture = new WebNetworkCaptureService({ + inspect: async () => { + throw new Error("No capture inspection requested"); + }, + close: async () => { + captureCloseAttempts += 1; + if (!cleanupAllowed) throw new Error("Capture cleanup refused"); + }, + }); + const server = createServer( + { kind: "fixed", analysis: { execute: async () => ok(null) } }, + { goBinary, webNetworkCapture }, + ); + const client = new Client({ name: "bound-service-lifecycle", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + resources.push(client, server); + try { + await server.connect(serverTransport); + await client.connect(clientTransport); + const result = await client.callTool({ + name: "inspect_go_binary", + arguments: { path: "/tmp/go-fixture" }, + }); + expect(result.isError).toBe(true); + expect(goCalls).toBe(1); + + await expect(server.close()).rejects.toBeInstanceOf(AggregateError); + expect(goCloseAttempts).toBe(1); + expect(captureCloseAttempts).toBe(1); + + cleanupAllowed = true; + await server.close(); + expect(goCloseAttempts).toBe(2); + expect(captureCloseAttempts).toBe(2); + } finally { + cleanupAllowed = true; + } +}); + afterEach(async () => { await Promise.all( resources.splice(0).map(async (resource) => resource.close()), diff --git a/tests/boundary/native/PwndbgCoreContext.test.ts b/tests/boundary/native/PwndbgCoreContext.test.ts index e8f007a9b..d38b01ac3 100644 --- a/tests/boundary/native/PwndbgCoreContext.test.ts +++ b/tests/boundary/native/PwndbgCoreContext.test.ts @@ -2,6 +2,7 @@ import { access } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, onTestFinished } from "vitest"; import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js"; +import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js"; import { createTestWorkspace, removeTestWorkspace, @@ -40,6 +41,7 @@ it.each(["pre-aborted", "aborted-during-probe"] as const)( REA_PWNDBG_VENV_PATH: join(workspace.root, "missing-venv"), }, rootPath: workspace.root, + resources: new ArtifactResourceScope(), diagnostics, options: { signal: controller.signal }, probePath, diff --git a/tests/boundary/native/pwntoolsArtifactCleanup.test.ts b/tests/boundary/native/pwntoolsArtifactCleanup.test.ts new file mode 100644 index 000000000..82760cfd2 --- /dev/null +++ b/tests/boundary/native/pwntoolsArtifactCleanup.test.ts @@ -0,0 +1,147 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it, vi } from "vitest"; +import { z } from "zod"; + +const closeState = vi.hoisted(() => ({ + fail: false, + failOnce: false, + opened: 0, + closes: 0, +})); + +vi.mock("node:fs/promises", async (importOriginal) => { + const fs = await importOriginal(); + return { + ...fs, + open: async (...args: Parameters) => { + const handle = await fs.open(...args); + closeState.opened++; + const close = handle.close.bind(handle); + handle.close = async () => { + closeState.closes++; + if (closeState.fail || closeState.failOnce) { + closeState.failOnce = false; + throw new Error("injected stable artifact close failure"); + } + return close(); + }; + return handle; + }, + }; +}); + +import { PwntoolsDecoder } from "../../../src/native/pwntools/PwntoolsDecoder.js"; +import { PWNTOOLS_PROVIDER_IDENTITY } from "../../../src/native/pwntools/PwntoolsRelease.js"; +import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; + +const makeDecoder = () => + new PwntoolsDecoder( + { + identity: PWNTOOLS_PROVIDER_IDENTITY, + operation: "test_pwntools_artifact_read", + bridge: new URL("file:///unused-bridge.py"), + payloadSchema: z.string(), + project: () => { + throw new Error("input read should fail before decoder launch"); + }, + }, + { REA_PWNTOOLS_PYTHON: process.execPath }, + undefined, + async () => { + throw new Error("runtime should not be created for failed input read"); + }, + ); + +const emulateSupportedHost = async ( + run: () => Promise, +): Promise => { + const platform = Object.getOwnPropertyDescriptor(process, "platform"); + const arch = Object.getOwnPropertyDescriptor(process, "arch"); + Object.defineProperty(process, "platform", { ...platform, value: "linux" }); + Object.defineProperty(process, "arch", { ...arch, value: "x64" }); + try { + await run(); + } finally { + if (platform !== undefined) + Object.defineProperty(process, "platform", platform); + if (arch !== undefined) Object.defineProperty(process, "arch", arch); + } +}; + +it("reports the read failure without stale incomplete-cleanup state when close retry succeeds", async () => + emulateSupportedHost(async () => { + const root = await mkdtemp(join(tmpdir(), "rea-pwntools-close-retry-")); + const path = join(root, "selected.bin"); + await writeFile(path, "selected evidence"); + closeState.fail = false; + closeState.failOnce = true; + closeState.opened = 0; + closeState.closes = 0; + const decoder = makeDecoder(); + try { + const result = await decoder.inspect({ path }); + expect(result.ok).toBe(false); + if (result.ok) throw new Error("Injected close failure was not returned"); + expect(result.error.cleanupIncomplete).toBe(false); + expect(projectAnalysisError(result.error).code).not.toBe( + "cleanup_incomplete", + ); + expect(result.error.cause).toMatchObject({ + cleanup: { + resources: [path], + reason: expect.stringContaining( + "injected stable artifact close failure", + ), + }, + }); + expect(closeState.closes).toBeGreaterThanOrEqual(2); + } finally { + closeState.fail = false; + closeState.failOnce = false; + await decoder.close(); + await rm(root, { recursive: true, force: true }); + } + })); + +it("retains a persistent failed input descriptor and refuses the next acquisition", async () => + emulateSupportedHost(async () => { + const root = await mkdtemp(join(tmpdir(), "rea-pwntools-held-close-")); + const path = join(root, "selected.bin"); + await writeFile(path, "selected evidence"); + closeState.fail = true; + closeState.failOnce = false; + closeState.opened = 0; + closeState.closes = 0; + const decoder = makeDecoder(); + try { + const first = await decoder.inspect({ path }); + expect(first.ok).toBe(false); + if (first.ok) + throw new Error("Persistent close failure was not returned"); + expect(projectAnalysisError(first.error).code).toBe("cleanup_incomplete"); + const openedAfterFailure = closeState.opened; + + const retry = await decoder.inspect({ path }); + expect(retry.ok).toBe(false); + if (retry.ok) throw new Error("Retained descriptor was not retried"); + expect(projectAnalysisError(retry.error).code).toBe("cleanup_incomplete"); + expect(closeState.opened).toBe(openedAfterFailure); + + await expect(decoder.close()).rejects.toMatchObject({ + cleanupIncomplete: true, + }); + closeState.fail = false; + await decoder.close(); + } finally { + closeState.fail = false; + closeState.failOnce = false; + try { + await decoder.close(); + } catch { + // The test already asserts persistent cleanup failure before releasing it. + } + await rm(root, { recursive: true, force: true }); + } + })); diff --git a/tests/boundary/providers/artifactReadCleanupRetry.test.ts b/tests/boundary/providers/artifactReadCleanupRetry.test.ts new file mode 100644 index 000000000..ebaba673a --- /dev/null +++ b/tests/boundary/providers/artifactReadCleanupRetry.test.ts @@ -0,0 +1,100 @@ +import type { FileHandle } from "node:fs/promises"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { expect, it, vi } from "vitest"; + +const cleanupState = vi.hoisted(() => ({ + failFirstClose: false, + abortController: undefined as AbortController | undefined, + firstHandle: undefined as FileHandle | undefined, + firstHandleCloseAttempts: 0, +})); + +vi.mock("node:fs/promises", async (importOriginal) => { + const fs = await importOriginal(); + return { + ...fs, + open: async (...args: Parameters) => { + const handle = await fs.open(...args); + const close = handle.close.bind(handle); + if (cleanupState.abortController !== undefined) + setImmediate(() => { + cleanupState.abortController?.abort(); + cleanupState.abortController = undefined; + }); + handle.close = async () => { + if (handle === cleanupState.firstHandle) + cleanupState.firstHandleCloseAttempts += 1; + else if (cleanupState.firstHandle === undefined) + cleanupState.firstHandle = handle; + if ( + cleanupState.failFirstClose && + handle === cleanupState.firstHandle + ) { + cleanupState.failFirstClose = false; + throw new Error("injected descriptor close failure"); + } + return close(); + }; + return handle; + }, + }; +}); + +import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; +import { GoBinaryProvider } from "../../../src/go/GoBinaryProvider.js"; +import { PeResourcesProvider } from "../../../src/native/pe/PeResourcesProvider.js"; +import { createGoBinaryFixture } from "../../fixtures/go/image.js"; +import { peResourceFixture } from "../../../src/native/pe/PeResources.fixture.js"; + +it.each(["go", "pe"] as const)( + "%s provider retains a failed descriptor close and retries that owner before the next read", + async (kind) => { + const root = await mkdtemp(join(tmpdir(), "rea-read-cleanup-")); + const path = join(root, kind === "go" ? "program.elf" : "program.exe"); + const bytes = + kind === "go" ? createGoBinaryFixture().bytes : peResourceFixture().bytes; + await writeFile(path, bytes); + const provider = + kind === "go" ? new GoBinaryProvider() : new PeResourcesProvider(); + cleanupState.failFirstClose = true; + const controller = new AbortController(); + cleanupState.abortController = controller; + cleanupState.firstHandle = undefined; + cleanupState.firstHandleCloseAttempts = 0; + try { + const input = { + path, + max_file_bytes: 8 * 1024 * 1024, + max_entries: 4096, + }; + const first = await provider.inspect(input, { + signal: controller.signal, + }); + expect(first.ok).toBe(false); + if (first.ok) throw new Error("Injected close failure was not returned"); + expect(projectAnalysisError(first.error)).toMatchObject({ + code: "cleanup_incomplete", + details: { diagnostics: { primary_error: { code: "cancelled" } } }, + }); + expect(first.error.cause).toBeInstanceOf(AggregateError); + if (!(first.error.cause instanceof AggregateError)) + throw first.error.cause; + expect(first.error.cause.errors[1]).toMatchObject({ + cleanupResources: [path], + }); + + const retry = await provider.inspect(input); + expect(retry.ok).toBe(true); + expect(cleanupState.firstHandleCloseAttempts).toBe(2); + } finally { + await provider.close(); + cleanupState.failFirstClose = false; + cleanupState.abortController = undefined; + cleanupState.firstHandle = undefined; + cleanupState.firstHandleCloseAttempts = 0; + await rm(root, { recursive: true, force: true }); + } + }, +); From c7a890d12987d9b2d496119c1fbf1a88c0fc298e Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 16:08:41 +0800 Subject: [PATCH 6/7] fix(javascript): preserve unknown module-alias provenance Replace the implicit local-provenance fallback with explicit locally constructed values. Keep opaque results, parameters and caught values unknown; follow assignment and sequence results while retaining exact module aliases. Clarify that alias provenance does not represent transitive data taint. Validation: 26 focused provenance/module-link tests, 135 semantic and graph-builder tests, six application module-relationship boundary tests, and the fast typecheck/lint gate. --- src/domain/javascript/javascriptSemanticIr.ts | 5 +- .../javascriptSemanticProvenance.test.ts | 94 +++++++++++++++++++ .../javascript/javascriptSemanticValues.ts | 33 ++++++- 3 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 src/domain/javascript/javascriptSemanticProvenance.test.ts diff --git a/src/domain/javascript/javascriptSemanticIr.ts b/src/domain/javascript/javascriptSemanticIr.ts index 005471775..d8349e895 100644 --- a/src/domain/javascript/javascriptSemanticIr.ts +++ b/src/domain/javascript/javascriptSemanticIr.ts @@ -13,7 +13,10 @@ export interface JavaScriptModuleOrigin { readonly importedPath: readonly string[]; } -/** Fail-closed provenance classification for one binding. */ +/** + * Fail-closed module-alias provenance for one binding, not transitive data flow. + * Locally constructed values may contain or derive from imported values. + */ export type JavaScriptBindingProvenance = | { readonly status: "module"; diff --git a/src/domain/javascript/javascriptSemanticProvenance.test.ts b/src/domain/javascript/javascriptSemanticProvenance.test.ts new file mode 100644 index 000000000..82a77a449 --- /dev/null +++ b/src/domain/javascript/javascriptSemanticProvenance.test.ts @@ -0,0 +1,94 @@ +import { describe, expect, it } from "vitest"; + +import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js"; +import { + onlyBinding, + topLevelBinding, +} from "./javascriptSemanticAnalysis.fixture.js"; + +describe("JavaScript semantic binding provenance", () => { + it("keeps opaque expression results unknown instead of declaring them local", () => { + const ir = analyzeJavaScriptSemantics(` + const called = loadFeature(); + const constructed = new Feature(); + const tagged = tag\`feature\`; + const dynamicRequired = require(specifier); + const sequence = (0, loadFeature()); + const assignment = (slot = loadFeature()); + async function readLater(parameter = require("fallback")) { + const awaited = await loadFeature(); + return awaited; + } + try { loadFeature(); } catch (caught) { void caught; } + function* yieldLater() { + const yielded = yield loadFeature(); + return yielded; + } + `); + + for (const name of [ + "called", + "constructed", + "tagged", + "dynamicRequired", + "sequence", + "assignment", + "awaited", + "yielded", + "parameter", + "caught", + ]) { + expect(onlyBinding(ir, name).provenance).toMatchObject({ + status: "unknown", + origins: [], + }); + } + }); + + it("recognizes explicit local values and preserves exact module aliases", () => { + const ir = analyzeJavaScriptSemantics(` + const object = { value: 1 }; + const array = [1, 2]; + const template = \`feature\`; + const primitive = -1 + 2; + const derived = loadFeature() + 1; + const derivedText = \`value: \${loadFeature()}\`; + let uninitialized; + const callable = () => 1; + const Constructed = class {}; + const imported = require("feature"); + const alias = imported; + const sequence = (0, require("sequence-feature")); + const assignment = (slot = require("assignment-feature")); + `); + + for (const name of [ + "object", + "array", + "template", + "primitive", + "derived", + "derivedText", + "uninitialized", + "callable", + "Constructed", + ]) + expect(topLevelBinding(ir, name).provenance).toMatchObject({ + status: "local", + origins: [], + }); + + expect(topLevelBinding(ir, "alias").provenance).toMatchObject({ + status: "module", + origins: [{ specifier: "feature" }], + }); + expect(topLevelBinding(ir, "sequence").provenance).toMatchObject({ + status: "module", + origins: [{ specifier: "sequence-feature" }], + }); + expect(topLevelBinding(ir, "assignment").provenance).toMatchObject({ + status: "module", + origins: [{ specifier: "assignment-feature" }], + }); + }); +}); diff --git a/src/domain/javascript/javascriptSemanticValues.ts b/src/domain/javascript/javascriptSemanticValues.ts index cf31e0575..d15c5edfc 100644 --- a/src/domain/javascript/javascriptSemanticValues.ts +++ b/src/domain/javascript/javascriptSemanticValues.ts @@ -817,6 +817,13 @@ const provenanceForBindingValue = ( binding: JavaScriptSemanticBindingState, context: EvaluationContext, ): JavaScriptBindingProvenance => { + if (binding.kind === "parameter" || binding.kind === "catch") + return semanticUnresolvedProvenance( + "unknown", + binding.kind === "parameter" + ? "Parameter provenance depends on caller arguments." + : "Catch binding provenance depends on the thrown value.", + ); if (binding.directOrigins.length > 0) return semanticOriginsProvenance(binding.directOrigins); if (binding.initializers.length === 0) return semanticLocalProvenance(); @@ -890,6 +897,14 @@ const provenanceForExpression = ( const required = semanticRequireOrigin(node, context.state); if (required !== undefined) return semanticOriginsProvenance([required.origin]); + if (t.isSequenceExpression(node)) { + const finalExpression = node.expressions.at(-1); + return finalExpression === undefined + ? semanticUnresolvedProvenance("unknown", "Empty sequence expression.") + : provenanceForExpression(finalExpression, nestedContext(context)); + } + if (t.isAssignmentExpression(node) && node.operator === "=") + return provenanceForExpression(node.right, nestedContext(context)); if (t.isIdentifier(node)) { const binding = resolveSemanticBindingState(context.state, node, node.name); return binding === undefined @@ -961,9 +976,25 @@ const provenanceForExpression = ( "Conditional provenance is unresolved.", ); } - return semanticLocalProvenance(); + if (isLocallyCreatedValue(node)) return semanticLocalProvenance(); + return semanticUnresolvedProvenance( + "unknown", + `Unsupported ${node.type} provenance.`, + ); }; +const isLocallyCreatedValue = (node: t.Node): boolean => + readExactJavaScriptLiteral(node).found || + t.isObjectExpression(node) || + t.isArrayExpression(node) || + t.isFunctionExpression(node) || + t.isArrowFunctionExpression(node) || + t.isClassExpression(node) || + t.isTemplateLiteral(node) || + t.isUnaryExpression(node) || + t.isBinaryExpression(node) || + t.isUpdateExpression(node); + const mergeValues = ( values: readonly JavaScriptSemanticValue[], ): JavaScriptSemanticValue => { From a0317cf732b3addefad5ac3b234db1e044e3351d Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 13 Oct 2026 16:16:31 +0800 Subject: [PATCH 7/7] fix(ci): align FAT fixtures and consolidate duplicated workflow helpers Declare the synthetic 4 KiB Mach-O slice alignment accurately while preserving the IDA thinning scenario. Share web cleanup aggregation and process-trace fixture facts instead of duplicating them across consumers and tests; keep the 3% duplication threshold unchanged. Validation: npm run check:ci, test discovery, and 42 focused IDA, process-trace, web workflow and cleanup boundary tests. Duplication falls from 3.01% to 2.99%. --- src/application/WebModuleTraceService.ts | 16 +---- src/application/WebSourceLocationService.ts | 15 +--- src/application/closeOwnedWebResources.ts | 15 ++++ src/domain/process/processCapture.fixture.ts | 54 +++++++++++++++ .../process/processTraceAdapters.test.ts | 69 ++----------------- src/ida/IdaWorkspaceThinning.test.ts | 12 +++- .../mcp/processTraceAdaptersParity.test.ts | 64 +---------------- 7 files changed, 87 insertions(+), 158 deletions(-) create mode 100644 src/application/closeOwnedWebResources.ts diff --git a/src/application/WebModuleTraceService.ts b/src/application/WebModuleTraceService.ts index 7913158f6..be0936e1c 100644 --- a/src/application/WebModuleTraceService.ts +++ b/src/application/WebModuleTraceService.ts @@ -1,3 +1,4 @@ +import { closeOwnedWebResources } from "./closeOwnedWebResources.js"; import { isAbsolute } from "node:path"; import { z } from "zod"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; @@ -271,21 +272,6 @@ export class WebModuleTraceService { } } -const closeOwnedWebResources = async ( - close: readonly ((() => Promise) | undefined)[], - message: string, -): Promise => { - const results = await Promise.allSettled( - close.flatMap((owner) => - owner === undefined ? [] : [Promise.resolve().then(owner)], - ), - ); - const failures = results.flatMap((result) => - result.status === "rejected" ? [result.reason] : [], - ); - if (failures.length > 0) throw new AggregateError(failures, message); -}; - const admitContext = ( value: string, path: readonly string[], diff --git a/src/application/WebSourceLocationService.ts b/src/application/WebSourceLocationService.ts index 79b7d45fc..d084bff5a 100644 --- a/src/application/WebSourceLocationService.ts +++ b/src/application/WebSourceLocationService.ts @@ -1,3 +1,4 @@ +import { closeOwnedWebResources } from "./closeOwnedWebResources.js"; import { createHash } from "node:crypto"; import { isAbsolute } from "node:path"; import { z } from "zod"; @@ -181,20 +182,6 @@ export class WebSourceLocationService { } } -const closeOwnedWebResources = async ( - close: readonly ((() => Promise) | undefined)[], - message: string, -): Promise => { - const results = await Promise.allSettled( - close.flatMap((owner) => - owner === undefined ? [] : [Promise.resolve().then(owner)], - ), - ); - const failures = results.flatMap((result) => - result.status === "rejected" ? [result.reason] : [], - ); - if (failures.length > 0) throw new AggregateError(failures, message); -}; const invalidOutput = (message: string): Result => err(new AnalysisOutputError(OPERATION, message)); const invalid = ( diff --git a/src/application/closeOwnedWebResources.ts b/src/application/closeOwnedWebResources.ts new file mode 100644 index 000000000..51b3e6f69 --- /dev/null +++ b/src/application/closeOwnedWebResources.ts @@ -0,0 +1,15 @@ +/** Attempt every web workflow cleanup owner and report all failures. */ +export const closeOwnedWebResources = async ( + close: readonly ((() => Promise) | undefined)[], + message: string, +): Promise => { + const results = await Promise.allSettled( + close.flatMap((owner) => + owner === undefined ? [] : [Promise.resolve().then(owner)], + ), + ); + const failures = results.flatMap((result) => + result.status === "rejected" ? [result.reason] : [], + ); + if (failures.length > 0) throw new AggregateError(failures, message); +}; diff --git a/src/domain/process/processCapture.fixture.ts b/src/domain/process/processCapture.fixture.ts index 701e76e2a..a8f2e669f 100644 --- a/src/domain/process/processCapture.fixture.ts +++ b/src/domain/process/processCapture.fixture.ts @@ -1,3 +1,4 @@ +import type { ProcessTraceSpecification } from "./processTraceSpecification.js"; import { compareProcessCaptures } from "./processComparison.js"; import { parseProcessCapture } from "./processCaptureParsing.js"; import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js"; @@ -112,3 +113,56 @@ export const compareUnverifiedProcessCaptures = ( parseProcessCapture(right), options, ); + +/** One journal and its matching declared trace, shared by domain and adapter checks. */ +export const processTraceCaptureFixture = () => { + const capture = { + ...EMPTY_PROCESS_CAPTURE_EXAMPLE, + event_journal: [ + { capture_order: 0, collection: "filesystem_checkpoints", index: 0 }, + { capture_order: 1, collection: "lifecycle", index: 0 }, + { capture_order: 2, collection: "lifecycle", index: 1 }, + { capture_order: 3, collection: "filesystem_checkpoints", index: 1 }, + ], + } as const; + const [before, after] = capture.filesystem_checkpoints; + if (before === undefined || after === undefined) + throw new Error( + "Trace fixture requires before and after filesystem checkpoints", + ); + const traceSpecification: ProcessTraceSpecification = { + events: [ + { + id: "before", + source: "filesystem", + exact: before, + cardinality: { kind: "required" }, + }, + { + id: "exit", + source: "lifecycle", + exact: { event: "exit", ...capture.exit }, + cardinality: { kind: "required" }, + }, + { + id: "settlement", + source: "lifecycle", + exact: { event: "settlement", ...capture.settlement }, + cardinality: { kind: "required" }, + }, + { + id: "after", + source: "filesystem", + exact: after, + cardinality: { kind: "required" }, + }, + ], + language: { + kind: "finite_traces", + variants: [ + { id: "normal", trace: ["before", "exit", "settlement", "after"] }, + ], + }, + }; + return { capture, traceSpecification }; +}; diff --git a/src/domain/process/processTraceAdapters.test.ts b/src/domain/process/processTraceAdapters.test.ts index 18cdea5c6..959ca76c8 100644 --- a/src/domain/process/processTraceAdapters.test.ts +++ b/src/domain/process/processTraceAdapters.test.ts @@ -1,72 +1,13 @@ import { describe, expect, it } from "vitest"; -import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js"; -import { accountFullyObservedProcessCapture } from "./processCapture.fixture.js"; +import { + processTraceCaptureFixture, + accountFullyObservedProcessCapture, +} from "./processCapture.fixture.js"; import { compareProcessCaptures } from "./processComparison.js"; import { parseProcessCapture } from "./processCaptureParsing.js"; import type { ProcessTraceSpecification } from "./processTraceSpecification.js"; -const beforeCheckpoint = { - name: "before", - at_ms: 0, - files: [], - effects: [], - truncated: false, -}; -const afterCheckpoint = { - name: "after_settlement", - at_ms: 50, - files: [], - effects: [], - truncated: false, -}; - -const capture = { - ...EMPTY_PROCESS_CAPTURE_EXAMPLE, - event_journal: [ - { capture_order: 0, collection: "filesystem_checkpoints", index: 0 }, - { capture_order: 1, collection: "lifecycle", index: 0 }, - { capture_order: 2, collection: "lifecycle", index: 1 }, - { capture_order: 3, collection: "filesystem_checkpoints", index: 1 }, - ], -} as const; - -const traceSpecification: ProcessTraceSpecification = { - events: [ - { - id: "before", - source: "filesystem", - exact: beforeCheckpoint, - cardinality: { kind: "required" }, - }, - { - id: "exit", - source: "lifecycle", - exact: { event: "exit", ...capture.exit }, - cardinality: { kind: "required" }, - }, - { - id: "settlement", - source: "lifecycle", - exact: { event: "settlement", ...capture.settlement }, - cardinality: { kind: "required" }, - }, - { - id: "after", - source: "filesystem", - exact: afterCheckpoint, - cardinality: { kind: "required" }, - }, - ], - language: { - kind: "finite_traces", - variants: [ - { - id: "normal", - trace: ["before", "exit", "settlement", "after"], - }, - ], - }, -}; +const { capture, traceSpecification } = processTraceCaptureFixture(); describe("declared trace comparison nonconformance", () => { it("does not call identical captures changed when both violate the language", () => { diff --git a/src/ida/IdaWorkspaceThinning.test.ts b/src/ida/IdaWorkspaceThinning.test.ts index 7d83f089b..baba6e145 100644 --- a/src/ida/IdaWorkspaceThinning.test.ts +++ b/src/ida/IdaWorkspaceThinning.test.ts @@ -40,6 +40,7 @@ interface Layout { readonly cpu: number; readonly offset: number; readonly size: number; + readonly alignmentExponent?: number; } /** @@ -57,12 +58,12 @@ const largeUniversalTarget = async ( const bytes = Buffer.alloc(total); bytes.writeUInt32BE(0xcafebabe, 0); bytes.writeUInt32BE(layout.length, 4); - layout.forEach(({ cpu, offset, size }, index) => { + layout.forEach(({ cpu, offset, size, alignmentExponent = 14 }, index) => { const entry = 8 + index * 20; bytes.writeUInt32BE(cpu, entry); bytes.writeUInt32BE(offset, entry + 8); bytes.writeUInt32BE(size, entry + 12); - bytes.writeUInt32BE(14, entry + 16); + bytes.writeUInt32BE(alignmentExponent, entry + 16); bytes.fill(0x11 * (index + 1), offset, offset + size); thinMach(0xfeedfacf, cpu).copy(bytes, offset); }); @@ -122,7 +123,12 @@ describe("IDA workspace input thinning", () => { async () => { const { bytes, target } = await largeUniversalTarget( [ - { cpu: 0x01000007, offset: 4096, size: 8480 }, + { + cpu: 0x01000007, + offset: 4096, + size: 8480, + alignmentExponent: 12, + }, { cpu: 0x0100000c, offset: 16384, size: 33464 }, { cpu: 0x00000007, offset: 65536, size: 33464 }, ], diff --git a/tests/boundary/mcp/processTraceAdaptersParity.test.ts b/tests/boundary/mcp/processTraceAdaptersParity.test.ts index cb7c1439c..d8c9b6173 100644 --- a/tests/boundary/mcp/processTraceAdaptersParity.test.ts +++ b/tests/boundary/mcp/processTraceAdaptersParity.test.ts @@ -9,76 +9,16 @@ import { createTestBinarySession } from "../../fixtures/binarySession.js"; import type { AnalysisClient } from "../../../src/application/AnalysisProvider.js"; import { compareProcessEvidenceFiles } from "../../../src/application/process/ProcessCli.js"; import { PROCESS_PROVIDER } from "../../../src/domain/process/processEvidenceProvider.js"; -import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js"; +import { processTraceCaptureFixture } from "../../../src/domain/process/processCapture.fixture.js"; import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js"; import { jsonValueSchema } from "../../../src/domain/jsonValue.js"; -import type { ProcessTraceSpecification } from "../../../src/domain/process/processTraceSpecification.js"; import { createServer } from "../../../src/server/createServer.js"; import { observed as ok } from "../../fixtures/analysisExecution.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const resources: Array<{ close(): Promise }> = []; const temporaryRoots: string[] = []; -const beforeCheckpoint = { - name: "before", - at_ms: 0, - files: [], - effects: [], - truncated: false, -}; -const afterCheckpoint = { - name: "after_settlement", - at_ms: 50, - files: [], - effects: [], - truncated: false, -}; -const capture = { - ...EMPTY_PROCESS_CAPTURE_EXAMPLE, - event_journal: [ - { capture_order: 0, collection: "filesystem_checkpoints", index: 0 }, - { capture_order: 1, collection: "lifecycle", index: 0 }, - { capture_order: 2, collection: "lifecycle", index: 1 }, - { capture_order: 3, collection: "filesystem_checkpoints", index: 1 }, - ], -} as const; -const traceSpecification: ProcessTraceSpecification = { - events: [ - { - id: "before", - source: "filesystem", - exact: beforeCheckpoint, - cardinality: { kind: "required" }, - }, - { - id: "exit", - source: "lifecycle", - exact: { event: "exit", ...capture.exit }, - cardinality: { kind: "required" }, - }, - { - id: "settlement", - source: "lifecycle", - exact: { event: "settlement", ...capture.settlement }, - cardinality: { kind: "required" }, - }, - { - id: "after", - source: "filesystem", - exact: afterCheckpoint, - cardinality: { kind: "required" }, - }, - ], - language: { - kind: "finite_traces", - variants: [ - { - id: "normal", - trace: ["before", "exit", "settlement", "after"], - }, - ], - }, -}; +const { capture, traceSpecification } = processTraceCaptureFixture(); const captureEvidence = (side: "left" | "right") => createEvidence(undefined, PROCESS_PROVIDER, {