From 7826e9688d9846c8fa1d93356ea5afe4d0b0b099 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:06:13 +0800 Subject: [PATCH] refactor(reverse): fake objdump and Rizin commands only through the owned supervisor (#11076) * refactor(reverse): fake objdump and Rizin commands only through the owned supervisor * test(reverse): fake launch refusals and failed exits as the owned supervisor reports them * refactor(reverse): name objdump and Rizin command repairs through the command port (#11080) --- .../reverse/ReverseEngineeringCommandPort.ts | 12 + .../reverse/ReverseEngineeringService.ts | 98 +++----- src/composition/reverseEngineering.ts | 13 +- src/objdump/ObjdumpProviderIdentity.ts | 8 + src/rizin/RizinProviderIdentity.ts | 8 + .../cli/commandEvidenceDelivery.test.ts | 10 +- .../mcp/commandObservationViews.test.ts | 10 +- .../mcp/reverseEngineeringPartialMcp.test.ts | 48 ++-- .../objdumpSelectedDisassembly.test.ts | 36 +-- tests/composition/reverseEngineering.test.ts | 222 +++++++++--------- .../reverseEngineeringAdmission.test.ts | 69 +++--- .../reverseEngineeringCancellation.test.ts | 20 -- .../reverseEngineeringCommandPort.test.ts | 101 +++++--- .../reverseEngineeringEdgeCases.test.ts | 95 ++++---- .../reverseEngineeringUnknownFailures.test.ts | 7 +- .../reverseEngineeringCompositionEdgeCases.ts | 170 +++----------- .../reverseEngineeringCompositionFixtures.ts | 50 ++++ 17 files changed, 479 insertions(+), 498 deletions(-) diff --git a/src/application/reverse/ReverseEngineeringCommandPort.ts b/src/application/reverse/ReverseEngineeringCommandPort.ts index 2d32b5000b..917bf978b0 100644 --- a/src/application/reverse/ReverseEngineeringCommandPort.ts +++ b/src/application/reverse/ReverseEngineeringCommandPort.ts @@ -5,11 +5,22 @@ import type { RizinInput, } from "../../domain/reverseEngineering.js"; +/** How a caller repairs a configured provider command; named by the provider. */ +export interface ReverseEngineeringCommandRepair { + /** The provider's name in reports, such as "objdump". */ + readonly provider: string; + /** The environment setting that selects the command. */ + readonly setting: string; + /** What to change when the command cannot be found or launched. */ + readonly remediationAction: string; +} + /** Provider-neutral command profile consumed by the shared application workflow. */ export interface ReverseEngineeringProviderCommand { readonly executable: string; readonly arguments: readonly string[]; readonly identity: EvidenceProvider; + readonly repair: ReverseEngineeringCommandRepair; /** What the provider cannot attest about the arguments it built. */ readonly limitations?: readonly string[]; /** @@ -27,6 +38,7 @@ export interface ReverseEngineeringProviderCommand { */ export interface ReverseEngineeringCommandUnavailable { readonly identity: EvidenceProvider; + readonly repair: ReverseEngineeringCommandRepair; /** The command as configured. */ readonly command: string; readonly reason: diff --git a/src/application/reverse/ReverseEngineeringService.ts b/src/application/reverse/ReverseEngineeringService.ts index 2914b524e0..b1e22a61ef 100644 --- a/src/application/reverse/ReverseEngineeringService.ts +++ b/src/application/reverse/ReverseEngineeringService.ts @@ -52,12 +52,12 @@ import { } from "../../domain/reverseEngineering.js"; import type { ReverseEngineeringCommandPort, + ReverseEngineeringCommandRepair, ReverseEngineeringCommandSelection, ReverseEngineeringCommandUnavailable, ReverseEngineeringProviderCommand, } from "./ReverseEngineeringCommandPort.js"; import { - execFileOutput, execFileOutputFailure, HOST_SPAWN_CAPACITY_CODES, } from "../../process/ExecFileOutput.js"; @@ -122,7 +122,6 @@ const MAX_ACTIVE_CAPTURE_BYTES = export interface ReverseEngineeringServiceOptions { readonly environment?: Readonly; readonly commands: ReverseEngineeringCommandPort; - readonly run?: ReverseEngineeringCommandRunner; readonly runOwned?: typeof runOwnedCommand; readonly digest?: typeof digestFile; readonly stat?: (path: string) => Promise; @@ -132,7 +131,12 @@ interface ReverseEngineeringCommandRunner { ( command: string, arguments_: readonly string[], - options?: Parameters[2], + options: { + readonly env: NodeJS.ProcessEnv; + readonly signal: AbortSignal | undefined; + readonly timeout: number; + readonly maxBuffer: number; + }, ): Promise<{ readonly stdout: string; readonly stderr: string; @@ -177,24 +181,13 @@ interface ReverseCommandObservation { readonly outputBudgetBytes: number; } -/** The provider a reverse command runs and how a caller repairs its command. */ -const reverseCommandRepair = ( - operation: ReverseEngineeringOperation, -): { readonly provider: string; readonly remediationAction: string } => { - const objdump = operation === "inspect_with_objdump"; - return { - provider: objdump ? "objdump" : "rizin", - remediationAction: `Set ${objdump ? "REA_OBJDUMP_COMMAND" : "REA_RIZIN_COMMAND"} to an installed executable ${objdump ? "GNU objdump" : "Rizin"} command, or make that command available on PATH. Check execute permission on the command and search permission on its parent directories before retrying.`, - }; -}; - /** A configured command the host search did not find; nothing was launched. */ const reverseCommandUnavailable = ( operation: ReverseEngineeringOperation, unavailable: ReverseEngineeringCommandUnavailable, ): AnalysisCapabilityUnavailableError => { - const { provider, remediationAction } = reverseCommandRepair(operation); - const { command, reason } = unavailable; + const { command, reason, repair } = unavailable; + const { provider, remediationAction } = repair; return new AnalysisCapabilityUnavailableError( unavailable.identity.id, operation, @@ -255,18 +248,16 @@ export class ReverseEngineeringService { constructor(options: ReverseEngineeringServiceOptions) { this.#environment = { ...(options.environment ?? process.env) }; this.#commands = options.commands; - this.#run = - options.run ?? - runOwnedCommandOutput( - options.runOwned ?? runOwnedCommand, - (owner, cleanup) => - this.#pendingCleanup.set(owner, { - observation: cleanup, - release: - this.#pendingCleanup.get(owner)?.release ?? - new AnalysisCleanupRelease(), - }), - ); + this.#run = runOwnedCommandOutput( + options.runOwned ?? runOwnedCommand, + (owner, cleanup) => + this.#pendingCleanup.set(owner, { + observation: cleanup, + release: + this.#pendingCleanup.get(owner)?.release ?? + new AnalysisCleanupRelease(), + }), + ); this.#digest = options.digest ?? digestFile; this.#stat = options.stat ?? statPath; } @@ -348,6 +339,7 @@ export class ReverseEngineeringService { operation: ReverseEngineeringOperation, dispatch: number, failure: AnalysisCapabilityUnavailableError, + repair: ReverseEngineeringCommandRepair, ): void { const outcome = this.#outcome(operation); if ( @@ -357,9 +349,7 @@ export class ReverseEngineeringService { outcome.failure = { dispatch, reason: failure.userMessage ?? failure.message, - remediation: - failure.remediationAction ?? - reverseCommandRepair(operation).remediationAction, + remediation: failure.remediationAction ?? repair.remediationAction, }; } @@ -512,7 +502,12 @@ export class ReverseEngineeringService { // discovery reports it like a launch failure until a later success. if (!selection.ok) { const refusal = reverseCommandUnavailable(operation, selection.error); - this.#recordUnavailable(operation, ++this.#dispatched, refusal); + this.#recordUnavailable( + operation, + ++this.#dispatched, + refusal, + selection.error.repair, + ); return Promise.resolve(err(refusal)); } if ( @@ -590,6 +585,7 @@ export class ReverseEngineeringService { outputBudgetBytes, } = request; const { executable: command, arguments: args } = profile; + const { provider, setting } = profile.repair; if (signal?.aborted) return err(cancelledBy(operation, signal)); const cleanup = await this.retryCleanup(operation); if (!cleanup.ok) return cleanup; @@ -696,7 +692,6 @@ export class ReverseEngineeringService { }, signal, timeout: timeoutMs, - stopSignal: "SIGTERM", maxBuffer: outputBudgetBytes, }); stdout = output.stdout; @@ -793,12 +788,6 @@ export class ReverseEngineeringService { typeof code === "string" && HOST_SPAWN_CAPACITY_CODES.has(code) ) { - const provider = - operation === "inspect_with_objdump" ? "objdump" : "rizin"; - const setting = - operation === "inspect_with_objdump" - ? "REA_OBJDUMP_COMMAND" - : "REA_RIZIN_COMMAND"; earlyFailure = new AnalysisResourceConstraintError( operation, "capacity", @@ -831,12 +820,6 @@ export class ReverseEngineeringService { ? cause.cause : undefined; if (earlyFailure === undefined && admissionFailure !== undefined) { - const provider = - operation === "inspect_with_objdump" ? "objdump" : "rizin"; - const setting = - operation === "inspect_with_objdump" - ? "REA_OBJDUMP_COMMAND" - : "REA_RIZIN_COMMAND"; const rawSystemCode = admissionFailure.detail?.system_code ?? (typeof admissionFailure.cause === "object" && @@ -886,10 +869,6 @@ export class ReverseEngineeringService { carriedReason(darwinFailure.cancellation?.reason), ); } else { - const setting = - operation === "inspect_with_objdump" - ? "REA_OBJDUMP_COMMAND" - : "REA_RIZIN_COMMAND"; earlyFailure = new AnalysisCapabilityUnavailableError( "process-ownership", "prepare_owned_process", @@ -930,10 +909,6 @@ export class ReverseEngineeringService { code !== "ETIMEDOUT" && !commandCancelled(signal, cause, code) ) { - const setting = - operation === "inspect_with_objdump" - ? "REA_OBJDUMP_COMMAND" - : "REA_RIZIN_COMMAND"; const remediation = controlFailure.remediationAction === undefined ? `${setting} does not need to change.` @@ -985,8 +960,7 @@ export class ReverseEngineeringService { ...reverseCommandTimeoutGuidance(timeoutMs), }); else { - const { provider, remediationAction } = - reverseCommandRepair(operation); + const { provider, remediationAction } = profile.repair; earlyFailure = new AnalysisCapabilityUnavailableError( profile.identity.id, operation, @@ -1097,7 +1071,12 @@ export class ReverseEngineeringService { earlyFailure.diagnostics?.boundary === "provider-launch" && earlyFailure.providerId === profile.identity.id ) { - this.#recordUnavailable(operation, dispatch, earlyFailure); + this.#recordUnavailable( + operation, + dispatch, + earlyFailure, + profile.repair, + ); } return err(this.#registerCleanupFailure(earlyFailure, cleanupOwner)); } @@ -1366,7 +1345,7 @@ const runOwnedCommandOutput = cleanup: AnalysisCleanupObservation, ) => void, ): ReverseEngineeringCommandRunner => - async (command, args, options = {}) => { + async (command, args, options) => { const spawnEnv = { ...options.env }; try { const snapshot = await runOwned( @@ -1380,9 +1359,8 @@ const runOwnedCommandOutput = sweepTokenOwnedProcesses: true, }, { - timeoutMs: options.timeout ?? DEFAULT_REVERSE_COMMAND_TIMEOUT_MS, - diagnosticBytes: - options.maxBuffer ?? DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES, + timeoutMs: options.timeout, + diagnosticBytes: options.maxBuffer, acceptNonZeroExit: true, }, { signal: options.signal }, diff --git a/src/composition/reverseEngineering.ts b/src/composition/reverseEngineering.ts index fafef9f338..8f5831f8a7 100644 --- a/src/composition/reverseEngineering.ts +++ b/src/composition/reverseEngineering.ts @@ -7,13 +7,19 @@ import type { import { err, ok } from "../domain/result.js"; import { ReverseEngineeringService } from "../application/reverse/ReverseEngineeringService.js"; import { objdumpCommand } from "../objdump/ObjdumpCommand.js"; -import { OBJDUMP_PROVIDER_IDENTITY } from "../objdump/ObjdumpProviderIdentity.js"; +import { + OBJDUMP_COMMAND_REPAIR, + OBJDUMP_PROVIDER_IDENTITY, +} from "../objdump/ObjdumpProviderIdentity.js"; import { rizinCommand, rizinCommandLimitations, rizinCommandRejection, } from "../rizin/RizinCommand.js"; -import { RIZIN_PROVIDER_IDENTITY } from "../rizin/RizinProviderIdentity.js"; +import { + RIZIN_COMMAND_REPAIR, + RIZIN_PROVIDER_IDENTITY, +} from "../rizin/RizinProviderIdentity.js"; import { resolveWindowsProviderExecutable } from "./resolveWindowsProviderExecutable.js"; export const createReverseEngineeringCommandPort = ( @@ -28,6 +34,7 @@ export const createReverseEngineeringCommandPort = ( { arguments: objdumpCommand(input), identity: OBJDUMP_PROVIDER_IDENTITY, + repair: OBJDUMP_COMMAND_REPAIR, environmentOverrides: { DEBUGINFOD_URLS: "" }, }, ), @@ -41,6 +48,7 @@ export const createReverseEngineeringCommandPort = ( limitations: rizinCommandLimitations(input), rejection: rizinCommandRejection, identity: RIZIN_PROVIDER_IDENTITY, + repair: RIZIN_COMMAND_REPAIR, }, ), }); @@ -57,6 +65,7 @@ const selectCommand = ( if (resolved.ok) return ok({ ...profile, executable: resolved.value }); return err({ identity: profile.identity, + repair: profile.repair, command, reason: resolved.error.kind === "not_found" diff --git a/src/objdump/ObjdumpProviderIdentity.ts b/src/objdump/ObjdumpProviderIdentity.ts index a039305b08..9f1926e7fd 100644 --- a/src/objdump/ObjdumpProviderIdentity.ts +++ b/src/objdump/ObjdumpProviderIdentity.ts @@ -4,3 +4,11 @@ export const OBJDUMP_PROVIDER_IDENTITY = { name: "objdump command", version: null, } as const; + +/** How a caller repairs the configured objdump command. */ +export const OBJDUMP_COMMAND_REPAIR = { + provider: "objdump", + setting: "REA_OBJDUMP_COMMAND", + remediationAction: + "Set REA_OBJDUMP_COMMAND to an installed executable GNU objdump command, or make that command available on PATH. Check execute permission on the command and search permission on its parent directories before retrying.", +} as const; diff --git a/src/rizin/RizinProviderIdentity.ts b/src/rizin/RizinProviderIdentity.ts index 003c3ebe40..9f251e9c0d 100644 --- a/src/rizin/RizinProviderIdentity.ts +++ b/src/rizin/RizinProviderIdentity.ts @@ -4,3 +4,11 @@ export const RIZIN_PROVIDER_IDENTITY = { name: "Rizin", version: null, } as const; + +/** How a caller repairs the configured Rizin command. */ +export const RIZIN_COMMAND_REPAIR = { + provider: "rizin", + setting: "REA_RIZIN_COMMAND", + remediationAction: + "Set REA_RIZIN_COMMAND to an installed executable Rizin command, or make that command available on PATH. Check execute permission on the command and search permission on its parent directories before retrying.", +} as const; diff --git a/tests/boundary/cli/commandEvidenceDelivery.test.ts b/tests/boundary/cli/commandEvidenceDelivery.test.ts index bd886e925d..f334d0e00a 100644 --- a/tests/boundary/cli/commandEvidenceDelivery.test.ts +++ b/tests/boundary/cli/commandEvidenceDelivery.test.ts @@ -17,6 +17,7 @@ import { ok } from "../../../src/domain/result.js"; import { OwnedStagedOutput } from "../../../src/filesystem/OwnedStagedOutput.js"; import { GdbSessionManager } from "../../../src/gdb/GdbSessionManager.js"; import { TestReverseEngineeringService } from "../../support/reverseEngineeringService.js"; +import { ownedOutput } from "../../support/reverseEngineeringCompositionFixtures.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const kinds = ["objdump", "architectures", "gdb"] as const; @@ -24,13 +25,12 @@ const fixture = async (kind: (typeof kinds)[number]) => { const directory = await createTestTempDirectory("rea-command-delivery-"); const path = join(directory, "input.bin"); await writeFile(path, "local CLI publication fixture"); - const runProvider = vi.fn(async () => ({ - stdout: "opaque provider output\n", - stderr: "provider diagnostic\n", - })); + const runProvider = vi.fn(async () => + ownedOutput("opaque provider output\n", "provider diagnostic\n"), + ); const service = new TestReverseEngineeringService({ environment: {}, - run: runProvider, + runOwned: runProvider, }); const closeService = vi.spyOn(service, "close"); const manager = new GdbSessionManager({ platform: "linux", environment: {} }); diff --git a/tests/boundary/mcp/commandObservationViews.test.ts b/tests/boundary/mcp/commandObservationViews.test.ts index 03949aaf13..c715fa36f1 100644 --- a/tests/boundary/mcp/commandObservationViews.test.ts +++ b/tests/boundary/mcp/commandObservationViews.test.ts @@ -17,6 +17,7 @@ import { import { ok } from "../../../src/domain/result.js"; import { inspectAnalysisView } from "../../../src/application/analysisView/AnalysisViewService.js"; import { TestReverseEngineeringService } from "../../support/reverseEngineeringService.js"; +import { ownedOutput } from "../../support/reverseEngineeringCompositionFixtures.js"; import { advertisedMcpToolSchemas } from "../../fixtures/advertisedMcpTool.js"; const sessionId = "00000000-0000-4000-8000-000000000001"; @@ -79,11 +80,10 @@ const connect = async (retain = true) => { close: async () => ok({ target_state: "none_observed" as const }), retryCleanupFailures: async () => ok(null), }; - const run = vi.fn(async () => ({ - stdout: "BFD advertised targets\n", - stderr: "diagnostic\n", - })); - const service = new TestReverseEngineeringService({ run }); + const run = vi.fn(async () => + ownedOutput("BFD advertised targets\n", "diagnostic\n"), + ); + const service = new TestReverseEngineeringService({ runOwned: run }); const logger = pino({ enabled: false }); registerGdbTools( server, diff --git a/tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts b/tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts index e32801c019..31a5157749 100644 --- a/tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts +++ b/tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts @@ -6,6 +6,10 @@ import { dirname, join } from "node:path"; import { expect, it, vi } from "vitest"; import { TestReverseEngineeringService as ReverseEngineeringService } from "../../support/reverseEngineeringService.js"; +import { + ownedFailure, + ownedOutput, +} from "../../support/reverseEngineeringCompositionFixtures.js"; import { AnalysisCancelledError, AnalysisInputError, @@ -30,14 +34,11 @@ import { const createTimedOutRizinService = (): ReverseEngineeringService => new ReverseEngineeringService({ - run: async () => { - throw Object.assign(new Error("timed out"), { - stdout: "partial provider output", - stderr: "", - code: "ETIMEDOUT", - signal: null, - killed: true, - }); + runOwned: async () => { + throw ownedFailure( + "timeout", + ownedOutput("partial provider output", "", { exitCode: null }), + ); }, }); @@ -124,9 +125,9 @@ it("admits Rizin mutation after invalidating before dispatch", async () => { const { server, handler } = createReverseEngineeringMcpHarness(); const events: string[] = []; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { events.push("dispatch"); - return { stdout: "rizin output", stderr: "" }; + return ownedOutput("rizin output"); }, }); registerReverseEngineeringTools( @@ -156,7 +157,7 @@ it("invalidates the snapshot in the legacy Rizin admission path", async () => { const { server, handler } = createReverseEngineeringMcpHarness(); const invalidateSnapshot = vi.fn(); const service = new ReverseEngineeringService({ - run: async () => ({ stdout: "rizin output", stderr: "" }), + runOwned: async () => ownedOutput("rizin output"), }); registerReverseEngineeringTools( server, @@ -215,7 +216,7 @@ it("skips snapshot invalidation for malformed Rizin input", async () => { it("delivers failed Rizin execution after external admission", async () => { const { server, handler } = createReverseEngineeringMcpHarness(); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { throw new Error("Rizin command failed"); }, }); @@ -305,17 +306,16 @@ it.each(["success", "timeout"])( const { server, handler } = createReverseEngineeringMcpHarness(); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { await writeFile(alias, "changed by Rizin"); if (outcome === "timeout") - throw Object.assign(new Error("timed out"), { - stdout: "partial analysis output", - stderr: "timeout diagnostics", - code: "ETIMEDOUT", - signal: null, - killed: true, - }); - return { stdout: "partial analysis output", stderr: "" }; + throw ownedFailure( + "timeout", + ownedOutput("partial analysis output", "timeout diagnostics", { + exitCode: null, + }), + ); + return ownedOutput("partial analysis output"); }, }); const recordEvidence = vi.fn(() => ok("added" as const)); @@ -420,7 +420,7 @@ it("preserves a partial MCP error without claiming failed Evidence retention", a it("delivers pathless objdump capability Evidence and input errors through its named tool", async () => { const { server, handler } = createReverseEngineeringMcpHarness(); const service = new ReverseEngineeringService({ - run: async () => ({ stdout: "objdump output", stderr: "" }), + runOwned: async () => ownedOutput("objdump output"), }); const delivery = createToolResultDelivery(2 * 1024 * 1024); registerReverseEngineeringTools( @@ -505,9 +505,9 @@ it("keeps provider execution and Evidence recording inside analysis admission", const { server, handler } = createReverseEngineeringMcpHarness(); const events: string[] = []; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { events.push("provider"); - return { stdout: "objdump output", stderr: "" }; + return ownedOutput("objdump output"); }, }); const recordEvidence = vi.fn(() => { diff --git a/tests/composition/objdumpSelectedDisassembly.test.ts b/tests/composition/objdumpSelectedDisassembly.test.ts index 1a4742cf8a..cb89a4d4c1 100644 --- a/tests/composition/objdumpSelectedDisassembly.test.ts +++ b/tests/composition/objdumpSelectedDisassembly.test.ts @@ -1,17 +1,20 @@ import { rm } from "node:fs/promises"; import { expect, it, vi } from "vitest"; -import { createArtifact } from "../support/reverseEngineeringCompositionFixtures.js"; +import { + createArtifact, + ownedOutput, +} from "../support/reverseEngineeringCompositionFixtures.js"; +import type { runOwnedCommand } from "../../src/process/OwnedCommand.js"; import { TestReverseEngineeringService } from "../support/reverseEngineeringService.js"; import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js"; it("keeps omitted and undefined selection out of default command Evidence", async () => { const { directory, path } = await createArtifact(); - const run = vi.fn(async (_command: string, _args: readonly string[]) => ({ - stdout: "complete disassembly\n", - stderr: "", - })); - const service = new TestReverseEngineeringService({ run }); + const run = vi.fn(async () => + ownedOutput("complete disassembly\n"), + ); + const service = new TestReverseEngineeringService({ runOwned: run }); try { for (const selector of [{}, { symbol: undefined }]) { const result = await service.inspectWithObjdump({ @@ -39,11 +42,10 @@ it.each([ "preserves native symbol %j as one argument and scoped Evidence", async (symbol) => { const { directory, path } = await createArtifact(); - const run = vi.fn(async (_command: string, _args: readonly string[]) => ({ - stdout: "selected disassembly\n", - stderr: "", - })); - const service = new TestReverseEngineeringService({ run }); + const run = vi.fn(async () => + ownedOutput("selected disassembly\n"), + ); + const service = new TestReverseEngineeringService({ runOwned: run }); try { const result = await service.inspectWithObjdump({ path, @@ -51,7 +53,10 @@ it.each([ symbol, }); if (!result.ok) throw result.error; - expect(run.mock.calls[0]?.[1]).toEqual([`--disassemble=${symbol}`, path]); + expect(run.mock.calls[0]?.[0].arguments).toEqual([ + `--disassemble=${symbol}`, + path, + ]); expect(result.value.parameters).toMatchObject({ operation: "disassemble", symbol, @@ -88,7 +93,10 @@ it.each([ async (operation) => { const digest = vi.fn(); const run = vi.fn(); - const service = new TestReverseEngineeringService({ digest, run }); + const service = new TestReverseEngineeringService({ + digest, + runOwned: run, + }); const result = await service.inspectWithObjdump({ ...(operation === "architectures" ? {} : { path: "/unread-artifact" }), operation, @@ -126,7 +134,7 @@ it.each([ ])("rejects invalid symbol %j before artifact admission", async (symbol) => { const digest = vi.fn(); const run = vi.fn(); - const service = new TestReverseEngineeringService({ digest, run }); + const service = new TestReverseEngineeringService({ digest, runOwned: run }); const result = await service.inspectWithObjdump({ path: "/unread-artifact", operation: "disassemble", diff --git a/tests/composition/reverseEngineering.test.ts b/tests/composition/reverseEngineering.test.ts index a905a198a3..c1da746c04 100644 --- a/tests/composition/reverseEngineering.test.ts +++ b/tests/composition/reverseEngineering.test.ts @@ -10,7 +10,13 @@ import { describe, expect, it } from "vitest"; import { digestFile } from "../../src/application/reverse/ReverseEngineeringService.js"; import { ok } from "../../src/domain/result.js"; import { TestReverseEngineeringService as ReverseEngineeringService } from "../support/reverseEngineeringService.js"; -import { providerSnapshot } from "../support/reverseEngineeringCompositionFixtures.js"; +import { + fixtureCommandRepair, + ownedFailure, + ownedLaunchRefusal, + ownedOutput, + providerSnapshot, +} from "../support/reverseEngineeringCompositionFixtures.js"; import { createReverseEngineeringService } from "../../src/composition/reverseEngineering.js"; import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js"; import { AnalysisCancelledError } from "../../src/domain/analysisErrorCore.js"; @@ -27,6 +33,7 @@ it.each(["objdump", "rizin"] as const)( const profile = { executable: process.execPath, arguments: ["-e", "process.stdout.write('complete-output')"], + repair: fixtureCommandRepair, identity: { id: "fixture-command", name: "Fixture command", @@ -95,9 +102,13 @@ describe("reverse engineering command services", () => { REA_OBJDUMP_COMMAND: "/tools/objdump", DEBUGINFOD_URLS: "https://debug.example.invalid", }, - run: async (command, args, options) => { - calls.push({ command, args, env: options?.env }); - return { stdout: "DWARF output\n", stderr: "diagnostic\n" }; + runOwned: async (spawn) => { + calls.push({ + command: spawn.command, + args: spawn.arguments, + env: spawn.env, + }); + return ownedOutput("DWARF output\n", "diagnostic\n"); }, }); @@ -136,9 +147,9 @@ describe("reverse engineering command services", () => { ); let invoked = false; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { invoked = true; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); @@ -171,15 +182,8 @@ describe("reverse engineering command services", () => { const path = join(directory, "fixture.bin"); await writeFile(path, "fixture"); const service = new ReverseEngineeringService({ - run: async () => { - const failure = Object.assign(new Error("not found"), { - stdout: "", - stderr: "", - code: "ENOENT", - signal: null, - killed: false, - }); - throw failure; + runOwned: async (spawn) => { + throw ownedLaunchRefusal("ENOENT", spawn.command); }, }); @@ -204,14 +208,15 @@ describe("reverse engineering command services", () => { const path = join(directory, "fixture.bin"); await writeFile(path, "fixture"); const service = new ReverseEngineeringService({ - run: async () => { - throw Object.assign(new Error("max buffer exceeded"), { - stdout: "captured partial output", - stderr: "", - code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", - signal: "SIGTERM", - killed: true, - }); + runOwned: async () => { + throw ownedFailure( + "output-limit", + ownedOutput("captured partial output", "", { + exitCode: null, + signal: "SIGTERM", + diagnosticTruncated: true, + }), + ); }, }); @@ -263,9 +268,9 @@ it.each([ const calls: (readonly string[])[] = []; const service = new ReverseEngineeringService({ environment: { REA_OBJDUMP_COMMAND: "/tools/objdump" }, - run: async (_command, args) => { - calls.push(args); - return { stdout: "captured stdout", stderr: "captured stderr" }; + runOwned: async (spawn) => { + calls.push(spawn.arguments); + return ownedOutput("captured stdout", "captured stderr"); }, }); @@ -315,9 +320,9 @@ it("uses one selected environment snapshot for provider selection and execution" }; const calls: { command: string; env: NodeJS.ProcessEnv | undefined }[] = []; const service = createReverseEngineeringService(selectedEnvironment, { - run: async (command, _args, options) => { - calls.push({ command, env: options?.env }); - return { stdout: "headers", stderr: "" }; + runOwned: async (spawn) => { + calls.push({ command: spawn.command, env: spawn.env }); + return ownedOutput("headers"); }, }); selectedEnvironment.REA_RIZIN_COMMAND = "/changed/rizin"; @@ -350,22 +355,18 @@ it("marks signal-terminated provider commands as unknown completion", async () = await writeFile(path, "fixture"); let invocation = 0; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { invocation += 1; if (invocation === 1) - throw Object.assign(new Error("provider killed by signal"), { - stdout: "partial output", - stderr: "", - code: null, - signal: "SIGKILL", - killed: true, - }); - throw Object.assign(new Error("provider exited with status 2"), { - stdout: "ordinary partial output", - stderr: "ordinary diagnostic", - code: 2, - signal: null, - killed: false, + throw ownedFailure( + "process", + ownedOutput("partial output", "", { + exitCode: null, + signal: "SIGKILL", + }), + ); + return ownedOutput("ordinary partial output", "ordinary diagnostic", { + exitCode: 2, }); }, }); @@ -425,23 +426,13 @@ describe("Rizin command service", () => { const calls: { command: string; args: readonly string[] }[] = []; const service = new ReverseEngineeringService({ environment: { REA_RIZIN_COMMAND: "/tools/rizin" }, - run: async (command, args) => { - calls.push({ command, args }); - const failure = new Error("command exited with status 2") as Error & { - stdout: string; - stderr: string; - code: number; - signal: null; - killed: boolean; - }; - Object.assign(failure, { - stdout: "\u001b[31mpartial data\u001b[0m\n", - stderr: "command error", - code: 2, - signal: null, - killed: false, - }); - throw failure; + runOwned: async (spawn) => { + calls.push({ command: spawn.command, args: spawn.arguments }); + return ownedOutput( + "\u001b[31mpartial data\u001b[0m\n", + "command error", + { exitCode: 2 }, + ); }, }); @@ -506,9 +497,9 @@ describe("Rizin command service", () => { await writeFile(path, "fixture"); let invoked = false; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { invoked = true; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); @@ -536,9 +527,9 @@ describe("Rizin command service", () => { const path = join(directory, "fixture.bin"); await writeFile(path, "before"); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { await writeFile(path, "after"); - return { stdout: "changed", stderr: "" }; + return ownedOutput("changed"); }, }); @@ -576,9 +567,9 @@ it("passes decoder and map inputs to Rizin before the path and records them", as const calls: (readonly string[])[] = []; const service = new ReverseEngineeringService({ environment: { REA_RIZIN_COMMAND: "/tools/rizin" }, - run: async (_command, args) => { - calls.push(args); - return { stdout: "bx lr\n", stderr: "" }; + runOwned: async (spawn) => { + calls.push(spawn.arguments); + return ownedOutput("bx lr\n"); }, }); const input = { @@ -640,9 +631,9 @@ it("checks only the spelling and range of decoder and map inputs", async () => { await writeFile(path, "image"); const calls: (readonly string[])[] = []; const service = new ReverseEngineeringService({ - run: async (_command, args) => { - calls.push(args); - return { stdout: "", stderr: "" }; + runOwned: async (spawn) => { + calls.push(spawn.arguments); + return ownedOutput(); }, }); @@ -721,15 +712,14 @@ it("retains partial Evidence when a provider command times out", async () => { const path = join(directory, "fixture.bin"); await writeFile(path, "before"); const service = new ReverseEngineeringService({ - run: async () => { - const failure = Object.assign(new Error("timeout"), { - stdout: "captured before timeout", - stderr: "still running", - code: "ETIMEDOUT", - signal: "SIGTERM", - killed: true, - }); - throw failure; + runOwned: async () => { + throw ownedFailure( + "timeout", + ownedOutput("captured before timeout", "still running", { + exitCode: null, + signal: "SIGTERM", + }), + ); }, }); @@ -769,7 +759,7 @@ it("retains partial Evidence when a provider command times out", async () => { it("keeps a selected architecture deadline on Evidence", async () => { const service = new ReverseEngineeringService({ - run: async () => ({ stdout: "elf64-x86-64\n", stderr: "" }), + runOwned: async () => ownedOutput("elf64-x86-64\n"), }); const selected = await service.inspectWithObjdump({ operation: "architectures", @@ -881,15 +871,12 @@ it("applies a caller-selected one-shot deadline on the next call", async () => { await writeFile(path, "before"); const timeouts: number[] = []; const service = new ReverseEngineeringService({ - run: async (_command, _args, options) => { - timeouts.push(options?.timeout ?? -1); - throw Object.assign(new Error("timeout"), { - stdout: "", - stderr: "", - code: "ETIMEDOUT", - signal: "SIGTERM", - killed: true, - }); + runOwned: async (_spawn, limits) => { + timeouts.push(limits.timeoutMs ?? -1); + throw ownedFailure( + "timeout", + ownedOutput("", "", { exitCode: null, signal: "SIGTERM" }), + ); }, }); @@ -929,19 +916,17 @@ it("preserves raw byte counts when cancellation rejects invalid UTF-8 output", a const path = join(directory, "fixture.bin"); await writeFile(path, "fixture"); const controller = new AbortController(); - const failure = Object.assign(new Error("The operation was aborted"), { - stdout: "�", - stderr: "€", - stdoutBytes: 1, - stderrBytes: 3, - code: "ABORT_ERR", - signal: null, - killed: true, - }); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { controller.abort(); - throw failure; + throw ownedFailure( + "cancelled", + ownedOutput("�", "€", { + stdout: { text: "�", bytes: 1, observedBytes: 1 }, + exitCode: null, + }), + { cancellation: { reason: controller.signal.reason } }, + ); }, }); @@ -971,16 +956,22 @@ it("preserves provider facts when cancellation interrupts the post-run digest", await writeFile(path, "fixture"); const controller = new AbortController(); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { controller.abort(); - return { - stdout: "�", - stderr: "�", - stdoutInvalidUtf8: true, - stderrInvalidUtf8: true, - stdoutBytes: 1, - stderrBytes: 1, - }; + return ownedOutput("", "", { + stdout: { + text: "�", + bytes: 1, + observedBytes: 1, + invalidUtf8: true, + }, + stderr: { + text: "�", + bytes: 1, + observedBytes: 1, + invalidUtf8: true, + }, + }); }, }); @@ -1022,14 +1013,11 @@ it("marks signal-terminated provider output incomplete", async () => { const path = join(directory, "fixture.bin"); await writeFile(path, "fixture"); const service = new ReverseEngineeringService({ - run: async () => { - throw Object.assign(new Error("terminated"), { - stdout: "partial", - stderr: "", - code: null, - signal: "SIGSEGV", - killed: false, - }); + runOwned: async () => { + throw ownedFailure( + "process", + ownedOutput("partial", "", { exitCode: null, signal: "SIGSEGV" }), + ); }, }); diff --git a/tests/composition/reverseEngineeringAdmission.test.ts b/tests/composition/reverseEngineeringAdmission.test.ts index a6ea37fe6a..456212b365 100644 --- a/tests/composition/reverseEngineeringAdmission.test.ts +++ b/tests/composition/reverseEngineeringAdmission.test.ts @@ -5,6 +5,11 @@ import { join } from "node:path"; import { expect, it } from "vitest"; import { TestReverseEngineeringService } from "../support/reverseEngineeringService.js"; +import { + ownedFailure, + ownedLaunchRefusal, + ownedOutput, +} from "../support/reverseEngineeringCompositionFixtures.js"; it.each([ { budget: undefined, capacity: 8 }, @@ -27,16 +32,13 @@ it.each([ let calls = 0; let mode: "success" | "failure" | "timeout" = "success"; const service = new TestReverseEngineeringService({ - run: async () => { + runOwned: async (spawn) => { calls += 1; if (mode === "failure") - throw Object.assign(new Error("provider failed"), { code: "ENOENT" }); - if (mode === "timeout") - throw Object.assign(new Error("provider timed out"), { - code: "ETIMEDOUT", - }); + throw ownedLaunchRefusal("ENOENT", spawn.command); + if (mode === "timeout") throw ownedFailure("timeout", null); await gate; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); @@ -115,9 +117,9 @@ it("preserves the exact caller reason when objdump admission is already aborted" controller.abort(reason); let runs = 0; const service = new TestReverseEngineeringService({ - run: async () => { + runOwned: async () => { runs += 1; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); try { @@ -143,9 +145,9 @@ it("preserves the caller reason when cancellation arrives after provider output" const reason = Object.freeze({ requested: "stop-after-output" }); const controller = new AbortController(); const service = new TestReverseEngineeringService({ - run: async () => { + runOwned: async () => { controller.abort(reason); - return { stdout: "symbols", stderr: "" }; + return ownedOutput("symbols"); }, }); try { @@ -181,9 +183,9 @@ it("keeps a physical digest denial primary when the caller aborts during that fa controller.abort(reason); throw denied; }, - run: async () => { + runOwned: async () => { runs += 1; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); try { @@ -235,33 +237,28 @@ it("keeps an unrelated digest ABORT_ERR as an adapter failure", async () => { it.each([ { - captured: true, + captured: false, code: "EACCES", tag: "AnalysisCapabilityUnavailableError", }, { captured: true, - code: "ETIMEDOUT", + code: "timeout", tag: "AnalysisTimeoutError", }, { captured: true, - code: "ABORT_ERR", + code: "cancelled", tag: "AnalysisCancelledError", }, { captured: false, - code: "EACCES", - tag: "AnalysisCapabilityUnavailableError", - }, - { - captured: false, - code: "ETIMEDOUT", + code: "timeout", tag: "AnalysisTimeoutError", }, { captured: false, - code: "ABORT_ERR", + code: "cancelled", tag: "AnalysisCancelledError", }, ] as const)( @@ -274,14 +271,20 @@ it.each([ await writeFile(path, "fixture"); const reason = Object.freeze({ requested: `stop-${code}` }); const controller = new AbortController(); - const failure = Object.assign(new Error("provider failure"), { - code, - ...(captured - ? { stdout: "partial stdout", stderr: "partial stderr" } - : {}), - }); + const failure = + code === "EACCES" + ? ownedLaunchRefusal(code, "objdump") + : ownedFailure( + code, + captured + ? ownedOutput("partial stdout", "partial stderr", { + exitCode: null, + }) + : null, + code === "cancelled" ? { cancellation: { reason } } : undefined, + ); const service = new TestReverseEngineeringService({ - run: async () => { + runOwned: async () => { controller.abort(reason); throw failure; }, @@ -293,7 +296,9 @@ it.each([ ); expect(result).toMatchObject({ ok: false, error: { _tag: tag } }); if (result.ok) return; - expect(result.error.cause).toBe(code === "ABORT_ERR" ? reason : failure); + if (code === "cancelled") expect(result.error.cause).toBe(reason); + else if (code === "EACCES") expect(result.error.cause).toBe(failure); + else expect(result.error.cause).toMatchObject({ cause: failure }); if (code === "EACCES") { expect(result.error).toMatchObject({ providerId: "objdump.command", @@ -304,7 +309,7 @@ it.each([ }, }); } - if (captured && code === "ABORT_ERR") { + if (captured && code === "cancelled") { expect(result.error.capturedOutput).toMatchObject({ stdout: "partial stdout", stderr: "partial stderr", diff --git a/tests/composition/reverseEngineeringCancellation.test.ts b/tests/composition/reverseEngineeringCancellation.test.ts index 9270646108..14116315b4 100644 --- a/tests/composition/reverseEngineeringCancellation.test.ts +++ b/tests/composition/reverseEngineeringCancellation.test.ts @@ -193,26 +193,6 @@ const cleanupCancellationScenario = async (options: { } }; -it("uses stoppable process mode for caller-selected provider commands", async () => { - const directory = await mkdtemp(join(tmpdir(), "rea-rizin-stoppable-")); - const path = join(directory, "fixture.bin"); - await writeFile(path, "fixture"); - let received: Record | undefined; - const service = new ReverseEngineeringService({ - run: async (_command, _args, options) => { - received = options as Record; - return { stdout: "", stderr: "" }; - }, - }); - - try { - await service.executeRizinCommand({ path, command: "iI" }); - expect(received?.stopSignal).toBe("SIGTERM"); - } finally { - await rm(directory, { recursive: true, force: true }); - } -}); - it.skipIf(process.platform === "win32")( "waits for a cancelled Rizin process to exit before returning", async () => { diff --git a/tests/composition/reverseEngineeringCommandPort.test.ts b/tests/composition/reverseEngineeringCommandPort.test.ts index 1b8f400885..d98a310985 100644 --- a/tests/composition/reverseEngineeringCommandPort.test.ts +++ b/tests/composition/reverseEngineeringCommandPort.test.ts @@ -9,20 +9,19 @@ import { analysisErrorProjectionSchema } from "../../src/contracts/errorSchemas. import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js"; import { ok } from "../../src/domain/result.js"; import { createReverseEngineeringCommandPort } from "../../src/composition/reverseEngineering.js"; -import { execFileOutput } from "../../src/process/ExecFileOutput.js"; - -type ExecFileOutputOptions = NonNullable[2]>; +import type { runOwnedCommand } from "../../src/process/OwnedCommand.js"; +import { + fixtureCommandRepair, + ownedLaunchRefusal, + ownedOutput, +} from "../support/reverseEngineeringCompositionFixtures.js"; it("uses provider profiles supplied through the application port", async () => { const directory = await mkdtemp(join(tmpdir(), "rea-reverse-port-")); const path = join(directory, "fixture.bin"); await writeFile(path, Buffer.from([0x7f, 0x45, 0x4c, 0x46])); - const run = vi.fn( - async ( - _command: string, - _args: readonly string[], - _options?: ExecFileOutputOptions, - ) => ({ stdout: "injected", stderr: "" }), + const run = vi.fn(async () => + ownedOutput("injected"), ); const service = new ReverseEngineeringService({ environment: { REA_OBJDUMP_COMMAND: "ambient-objdump" }, @@ -31,6 +30,7 @@ it("uses provider profiles supplied through the application port", async () => { ok({ executable: "injected-objdump", arguments: ["--injected", path], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Injected objdump", @@ -42,10 +42,11 @@ it("uses provider profiles supplied through the application port", async () => { ok({ executable: "injected-rizin", arguments: ["--injected", path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Injected Rizin", version: null }, }), }, - run, + runOwned: run, }); try { @@ -54,10 +55,10 @@ it("uses provider profiles supplied through the application port", async () => { operation: "file_headers", }); expect(result.ok).toBe(true); - const call = run.mock.calls[0]; - expect(call?.[0]).toBe("injected-objdump"); - expect(call?.[1]).toEqual(["--injected", path]); - expect(call?.[2]?.env?.INJECTED_PROFILE).toBe("yes"); + const spawn = run.mock.calls[0]?.[0]; + expect(spawn?.command).toBe("injected-objdump"); + expect(spawn?.arguments).toEqual(["--injected", path]); + expect(spawn?.env?.INJECTED_PROFILE).toBe("yes"); if (result.ok) expect(result.value.provider.id).toBe("test.objdump"); } finally { await rm(directory, { recursive: true, force: true }); @@ -71,12 +72,8 @@ it("does not reintroduce ambient variables absent from the captured provider env const previous = process.env[variable]; await writeFile(path, Buffer.from([0x7f, 0x45, 0x4c, 0x46])); process.env[variable] = "late-ambient-value"; - const run = vi.fn( - async ( - _command: string, - _args: readonly string[], - _options?: ExecFileOutputOptions, - ) => ({ stdout: "captured", stderr: "" }), + const run = vi.fn(async () => + ownedOutput("captured"), ); const service = new ReverseEngineeringService({ environment: { REA_OBJDUMP_COMMAND: "captured-objdump" }, @@ -85,6 +82,7 @@ it("does not reintroduce ambient variables absent from the captured provider env ok({ executable: "captured-objdump", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Captured objdump", @@ -96,15 +94,16 @@ it("does not reintroduce ambient variables absent from the captured provider env ok({ executable: "captured-rizin", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Captured Rizin", version: null }, }), }, - run, + runOwned: run, }); try { await service.inspectWithObjdump({ path, operation: "file_headers" }); - expect(run.mock.calls[0]?.[2]?.env).toEqual({ + expect(run.mock.calls[0]?.[0].env).toEqual({ REA_OBJDUMP_COMMAND: "captured-objdump", PROFILE_VALUE: "explicit", }); @@ -120,13 +119,14 @@ it("projects missing and non-file objdump targets with actionable path reasons", join(tmpdir(), "rea-reverse-invalid-target-"), ); const missing = join(directory, "missing.bin"); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); + const run = vi.fn(async () => ownedOutput()); const service = new ReverseEngineeringService({ commands: { objdump: () => ok({ executable: "unused-objdump", arguments: [missing], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Test objdump", @@ -137,10 +137,11 @@ it("projects missing and non-file objdump targets with actionable path reasons", ok({ executable: "unused-rizin", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Test Rizin", version: null }, }), }, - run, + runOwned: run, }); try { @@ -195,7 +196,7 @@ it("keeps target preflight I/O failures out of invalid-input classification", as const stat = vi.fn(async () => { throw ioFailure; }); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); + const run = vi.fn(async () => ownedOutput()); const service = new ReverseEngineeringService({ stat, commands: { @@ -203,6 +204,7 @@ it("keeps target preflight I/O failures out of invalid-input classification", as ok({ executable: "unused-objdump", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Test objdump", @@ -213,10 +215,11 @@ it("keeps target preflight I/O failures out of invalid-input classification", as ok({ executable: "unused-rizin", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Test Rizin", version: null }, }), }, - run, + runOwned: run, }); try { @@ -263,7 +266,7 @@ it.each([ const stat = vi.fn(async () => { throw pathFailure; }); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); + const run = vi.fn(async () => ownedOutput()); const service = new ReverseEngineeringService({ stat, commands: { @@ -271,6 +274,7 @@ it.each([ ok({ executable: "unused-objdump", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Test objdump", @@ -281,10 +285,11 @@ it.each([ ok({ executable: "unused-rizin", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Test Rizin", version: null }, }), }, - run, + runOwned: run, }); try { @@ -347,11 +352,11 @@ it.each([ ])( "refuses $operation on Windows when the bare command is not found on PATH, launching nothing", async ({ operation, environment, run: execute, command, reason }) => { - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); + const run = vi.fn(async () => ownedOutput()); const service = new ReverseEngineeringService({ environment, commands: createReverseEngineeringCommandPort(environment, "win32"), - run, + runOwned: run, }); const result = await execute(service); if (result.ok) throw new Error("Expected a lookup refusal"); @@ -386,3 +391,39 @@ it.each([ expect(run).not.toHaveBeenCalled(); }, ); + +it("reports a launch refusal with the repair the command port names", async () => { + const profile = { + executable: "fixture-command", + arguments: [], + repair: fixtureCommandRepair, + identity: { id: "test.fixture", name: "Fixture", version: null }, + }; + const service = new ReverseEngineeringService({ + commands: { objdump: () => ok(profile), rizin: () => ok(profile) }, + runOwned: async (spawn) => { + throw ownedLaunchRefusal("ENOENT", spawn.command); + }, + }); + try { + const result = await service.inspectWithObjdump({ + operation: "architectures", + }); + if (result.ok) throw new Error("Expected a launch refusal"); + const projection = projectAnalysisError(result.error); + expect(projection.message).toContain( + 'selected fixture executable "fixture-command"', + ); + expect(projection.remediation.action).toBe( + fixtureCommandRepair.remediationAction, + ); + expect(service.observedLaunchFailures()).toEqual({ + inspect_with_objdump: { + reason: projection.message, + remediation: fixtureCommandRepair.remediationAction, + }, + }); + } finally { + await service.close(); + } +}); diff --git a/tests/composition/reverseEngineeringEdgeCases.test.ts b/tests/composition/reverseEngineeringEdgeCases.test.ts index 0313c0fea7..a92a22123d 100644 --- a/tests/composition/reverseEngineeringEdgeCases.test.ts +++ b/tests/composition/reverseEngineeringEdgeCases.test.ts @@ -6,6 +6,8 @@ import { registerSharedReverseEngineeringEdgeCaseTests } from "../support/revers import { registerOwnedRizinCommandEvidenceTests } from "../support/ownedRizinCommandEvidenceTests.js"; import { createArtifact, + ownedFailure, + ownedOutput, providerSnapshot, } from "../support/reverseEngineeringCompositionFixtures.js"; @@ -93,7 +95,7 @@ it("records pathless objdump architecture support as provider capability evidenc const service = new CoreReverseEngineeringService({ commands: createReverseEngineeringCommandPort(process.env), digest, - run: async () => ({ stdout: "elf64-x86-64", stderr: "" }), + runOwned: async () => ownedOutput("elf64-x86-64"), }); try { const result = await service.inspectWithObjdump({ @@ -136,9 +138,9 @@ it("uses the host environment when the service environment is omitted", async () let observedEnvironment: NodeJS.ProcessEnv | undefined; const service = new CoreReverseEngineeringService({ commands: createReverseEngineeringCommandPort(process.env), - run: async (_command, _args, options) => { - observedEnvironment = options?.env; - return { stdout: "ok", stderr: "" }; + runOwned: async (spawn) => { + observedEnvironment = spawn.env; + return ownedOutput("ok"); }, }); @@ -173,7 +175,7 @@ it.each(["cancellation", "deadline"] as const)( rejectStat = reject; }); }, - run: async () => ({ stdout: "", stderr: "" }), + runOwned: async () => ownedOutput(), }); const resultPromise = service.inspectWithObjdump( @@ -231,8 +233,8 @@ it("handles cancellation that races with stat listener registration", async () = throwIfAborted: () => {}, } as AbortSignal; const stat = vi.fn(async () => ({ isFile: () => true }) as unknown as Stats); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ stat, run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ stat, runOwned }); try { const result = await service.inspectWithObjdump( @@ -245,7 +247,7 @@ it("handles cancellation that races with stat listener registration", async () = error: { _tag: "AnalysisCancelledError" }, }); expect(stat).not.toHaveBeenCalled(); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } @@ -258,10 +260,10 @@ it("handles a synchronous stat provider throw as an artifact input failure", asy code: "ENOENT", }); }); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); + const runOwned = vi.fn(async () => ownedOutput()); const service = new ReverseEngineeringService({ stat: stat as unknown as (path: string) => Promise, - run, + runOwned, }); try { @@ -275,7 +277,7 @@ it("handles a synchronous stat provider throw as an artifact input failure", asy error: { _tag: "AnalysisInputError" }, }); expect(stat).toHaveBeenCalledTimes(1); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } @@ -307,8 +309,8 @@ it("cancels an artifact stream when cancellation races with its listener registr throwIfAborted: () => {}, } as AbortSignal; const stat = vi.fn(async () => ({ isFile: () => true }) as unknown as Stats); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ stat, run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ stat, runOwned }); try { const result = await service.inspectWithObjdump( @@ -322,7 +324,7 @@ it("cancels an artifact stream when cancellation races with its listener registr }); expect(registrations).toBe(2); expect(stat).toHaveBeenCalledTimes(1); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } @@ -344,8 +346,8 @@ it("cancels before stream listeners when the signal changes after stat", async ( throwIfAborted: () => {}, } as AbortSignal; const stat = vi.fn(async () => ({ isFile: () => true }) as unknown as Stats); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ stat, run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ stat, runOwned }); try { const result = await service.inspectWithObjdump( @@ -360,15 +362,15 @@ it("cancels before stream listeners when the signal changes after stat", async ( // Cancellation checks may be repeated by the digest cleanup path. expect(abortedReads).toBeGreaterThanOrEqual(5); expect(stat).toHaveBeenCalledTimes(1); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } }); it("rejects malformed Rizin requests before touching the provider", async () => { - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ runOwned }); const result = await service.executeRizinCommand({ path: "sample.bin" }); @@ -382,13 +384,13 @@ it("rejects malformed Rizin requests before touching the provider", async () => ], }, }); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); }); it("rejects new operations after service shutdown begins", async () => { const { directory, path } = await createArtifact(); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ runOwned }); try { await service.close(); @@ -401,7 +403,7 @@ it("rejects new operations after service shutdown begins", async () => { "Reverse-engineering service is closed.", ); } - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } @@ -415,10 +417,10 @@ it("rejects work after reaching the concurrent provider-operation limit", async }); let providerCalls = 0; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { providerCalls += 1; await providerGate; - return { stdout: "ok", stderr: "" }; + return ownedOutput("ok"); }, }); @@ -472,8 +474,8 @@ it("cancels when an AbortSignal becomes aborted during listener registration", a return typeof value === "function" ? value.bind(target) : value; }, }); - const run = vi.fn(async () => ({ stdout: "", stderr: "" })); - const service = new ReverseEngineeringService({ run }); + const runOwned = vi.fn(async () => ownedOutput()); + const service = new ReverseEngineeringService({ runOwned }); try { const result = await service.inspectWithObjdump( @@ -486,7 +488,7 @@ it("cancels when an AbortSignal becomes aborted during listener registration", a error: { _tag: "AnalysisCancelledError" }, }); expect(abortedReads).toBe(2); - expect(run).not.toHaveBeenCalled(); + expect(runOwned).not.toHaveBeenCalled(); } finally { await rm(directory, { recursive: true, force: true }); } @@ -504,11 +506,11 @@ it("drains an active provider operation before service shutdown resolves", async runStarted = resolve; }); const service = new ReverseEngineeringService({ - run: async (_command, _args, options) => { + runOwned: async (_spawn, _limits, options) => { signal = options?.signal; runStarted?.(); await runGate; - return { stdout: "finished", stderr: "" }; + return ownedOutput("finished"); }, }); @@ -557,11 +559,11 @@ it("relays caller cancellation to the admitted provider signal", async () => { let providerSignal: AbortSignal | undefined; const service = new CoreReverseEngineeringService({ commands: createReverseEngineeringCommandPort(process.env), - run: async (_command, _args, options) => { + runOwned: async (_spawn, _limits, options) => { providerSignal = options?.signal; announceStarted?.(); await runGate; - return { stdout: "captured", stderr: "" }; + return ownedOutput("captured"); }, }); const operation = service.inspectWithObjdump( @@ -608,14 +610,16 @@ it("passes an AbortSignal-like caller value through without relaying it", async expect(receivedSignal).toBe(signal); return "a".repeat(64); }); - const run = vi.fn(async (_command, _args, options) => { - expect(options?.signal).toBe(signal); - return { stdout: "ok", stderr: "" }; - }); + const runOwned = vi.fn( + async (_spawn, _limits, options) => { + expect(options?.signal).toBe(signal); + return ownedOutput("ok"); + }, + ); const service = new CoreReverseEngineeringService({ commands: createReverseEngineeringCommandPort(process.env), digest, - run, + runOwned, }); try { @@ -628,7 +632,7 @@ it("passes an AbortSignal-like caller value through without relaying it", async expect(signal.addEventListener).not.toHaveBeenCalled(); expect(signal.removeEventListener).toHaveBeenCalledTimes(1); expect(digest).toHaveBeenCalledTimes(2); - expect(run).toHaveBeenCalledTimes(1); + expect(runOwned).toHaveBeenCalledTimes(1); } finally { await rm(directory, { recursive: true, force: true }); } @@ -898,14 +902,13 @@ it("preserves a provider timeout when cancellation arrives during the final dige if (digests === 2) controller.abort(); return "a".repeat(64); }, - run: async () => { - throw Object.assign(new Error("provider timed out"), { - stdout: "partial timeout output", - stderr: "timeout diagnostic", - code: "ETIMEDOUT", - signal: null, - killed: true, - }); + runOwned: async () => { + throw ownedFailure( + "timeout", + ownedOutput("partial timeout output", "timeout diagnostic", { + exitCode: null, + }), + ); }, }); diff --git a/tests/composition/reverseEngineeringUnknownFailures.test.ts b/tests/composition/reverseEngineeringUnknownFailures.test.ts index 6ecac90f09..eec605dc2a 100644 --- a/tests/composition/reverseEngineeringUnknownFailures.test.ts +++ b/tests/composition/reverseEngineeringUnknownFailures.test.ts @@ -9,6 +9,7 @@ import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.j import { ok } from "../../src/domain/result.js"; import { OwnedCommandFailure } from "../../src/process/OwnedCommand.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { fixtureCommandRepair } from "../support/reverseEngineeringCompositionFixtures.js"; it.each([false, true])( "keeps owned output collection failure primary after late cancellation=%s", @@ -33,6 +34,7 @@ it.each([false, true])( const profile = { executable: "unused", arguments: [], + repair: fixtureCommandRepair, identity: { id: "fixture", name: "fixture", version: null }, }; const service = new ReverseEngineeringService({ @@ -68,6 +70,7 @@ it("keeps the owned producer cancellation reason authoritative", async () => { const profile = { executable: "unused", arguments: [], + repair: fixtureCommandRepair, identity: { id: "fixture", name: "fixture", version: null }, }; const service = new ReverseEngineeringService({ @@ -109,12 +112,13 @@ it.each([ throw cause; } : stat, - run, + runOwned: run, commands: { objdump: () => ok({ executable: "unused-objdump", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.objdump", name: "Test objdump", @@ -125,6 +129,7 @@ it.each([ ok({ executable: "unused-rizin", arguments: [path], + repair: fixtureCommandRepair, identity: { id: "test.rizin", name: "Test Rizin", version: null }, }), }, diff --git a/tests/support/reverseEngineeringCompositionEdgeCases.ts b/tests/support/reverseEngineeringCompositionEdgeCases.ts index ed4f98cae5..760b92a5a5 100644 --- a/tests/support/reverseEngineeringCompositionEdgeCases.ts +++ b/tests/support/reverseEngineeringCompositionEdgeCases.ts @@ -5,6 +5,8 @@ import { expect, it, vi } from "vitest"; import { TestReverseEngineeringService as ReverseEngineeringService } from "./reverseEngineeringService.js"; import { createArtifact, + ownedFailure, + ownedOutput, providerSnapshot, } from "./reverseEngineeringCompositionFixtures.js"; import { objdumpCommand } from "../../src/objdump/ObjdumpCommand.js"; @@ -29,9 +31,9 @@ const registerSharedReverseEngineeringEdgeCasesPart1 = (): void => { const { directory, path } = await createArtifact(); const calls: string[][] = []; const service = new ReverseEngineeringService({ - run: async (_command, args) => { - calls.push([...args]); - return { stdout: "DWARF output", stderr: "" }; + runOwned: async (spawn) => { + calls.push([...spawn.arguments]); + return ownedOutput("DWARF output"); }, }); @@ -52,7 +54,7 @@ const registerSharedReverseEngineeringEdgeCasesPart1 = (): void => { it("marks opted-in external DWARF debug files as unbound Evidence sources", async () => { const { directory, path } = await createArtifact(); const service = new ReverseEngineeringService({ - run: async () => ({ stdout: "DWARF output", stderr: "" }), + runOwned: async () => ownedOutput("DWARF output"), }); try { @@ -74,9 +76,9 @@ const registerSharedReverseEngineeringEdgeCasesPart1 = (): void => { it("rejects malformed objdump requests before touching the provider", async () => { let invoked = false; const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { invoked = true; - return { stdout: "", stderr: "" }; + return ownedOutput(); }, }); @@ -297,19 +299,19 @@ const registerSharedReverseEngineeringEdgeCasesPart3 = (): void => { }); it.each([ - ["ETIMEDOUT", "AnalysisTimeoutError"], - ["EACCES", "AnalysisCapabilityUnavailableError"], - ["EPERM", "AnalysisCapabilityUnavailableError"], - ["ABORT_ERR", "AnalysisCancelledError"], + ["timeout", "AnalysisTimeoutError"], + ["cancelled", "AnalysisCancelledError"], ["unknown", "AnalysisCapabilityUnavailableError"], - ])( + ] as const)( "maps provider failure %s to its tagged analysis error", async (code, tag) => { const { directory, path } = await createArtifact(); const service = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { if (code === "unknown") throw new Error("provider failure"); - throw Object.assign(new Error("provider failure"), { code }); + throw ownedFailure(code, null, { + cause: new Error("provider failure"), + }); }, }); @@ -323,20 +325,10 @@ const registerSharedReverseEngineeringEdgeCasesPart3 = (): void => { error: { _tag: tag, operation: "inspect_with_objdump", - cause: { message: "provider failure" }, - ...(code === "ETIMEDOUT" ? { timeoutMs: 120_000 } : {}), - ...(code === "EACCES" || code === "EPERM" - ? { - providerId: "objdump.command", - diagnostics: { - boundary: "provider-launch", - command: "objdump", - system_code: code, - }, - } - : {}), + ...(code === "timeout" ? { timeoutMs: 120_000 } : {}), ...(code === "unknown" ? { + cause: { message: "provider failure" }, providerId: "objdump.command", reason: "Unable to run configured command (unknown error)", } @@ -354,15 +346,15 @@ const registerSharedReverseEngineeringEdgeCasesPart4 = (): void => { it("records a changed artifact and unknown post-run digest separately", async () => { const { directory, path } = await createArtifact(); const changed = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { await writeFile(path, "changed during provider execution"); - return { stdout: "observed", stderr: "" }; + return ownedOutput("observed"); }, }); const removed = new ReverseEngineeringService({ - run: async () => { + runOwned: async () => { await rm(path); - return { stdout: "observed", stderr: "" }; + return ownedOutput("observed"); }, }); @@ -399,54 +391,10 @@ const registerSharedReverseEngineeringEdgeCasesPart4 = (): void => { await rm(directory, { recursive: true, force: true }); } }); - - it.each(["EACCES", "EPERM"] as const)( - "retains raw failure output on a permission-denied provider launch (%s)", - async (code) => { - const { directory, path } = await createArtifact(); - const service = new ReverseEngineeringService({ - run: async () => { - throw Object.assign(new Error("provider permission denied"), { - stdout: "partial provider output", - stderr: "permission diagnostic", - code, - signal: null, - killed: false, - }); - }, - }); - - try { - const result = await service.inspectWithObjdump({ - path, - operation: "file_headers", - }); - expect(result).toMatchObject({ - ok: false, - error: { - _tag: "AnalysisCapabilityUnavailableError", - providerId: "objdump.command", - diagnostics: { - boundary: "provider-launch", - command: "objdump", - system_code: code, - }, - cause: { - code, - stdout: "partial provider output", - stderr: "permission diagnostic", - }, - }, - }); - } finally { - await rm(directory, { recursive: true, force: true }); - } - }, - ); }; const registerSharedReverseEngineeringEdgeCasesPart5 = (): void => { - it("cancels after captured output when a provider reports a non-numeric status", async () => { + it("cancels after captured output when the provider exit status is unknown", async () => { const { directory, path } = await createArtifact(); const controller = new AbortController(); let digests = 0; @@ -456,14 +404,11 @@ const registerSharedReverseEngineeringEdgeCasesPart5 = (): void => { if (digests === 2) controller.abort(); return digests === 1 ? "a".repeat(64) : "b".repeat(64); }, - run: async () => { - throw Object.assign(new Error("provider status unavailable"), { - stdout: "captured output", - stderr: "", - code: "provider-status-unknown", - signal: null, - killed: false, - }); + runOwned: async () => { + throw ownedFailure( + "process", + ownedOutput("captured output", "", { exitCode: null }), + ); }, }); @@ -485,65 +430,6 @@ const registerSharedReverseEngineeringEdgeCasesPart5 = (): void => { await rm(directory, { recursive: true, force: true }); } }); - - it("maps an unavailable Rizin command to the Rizin capability error", async () => { - const { directory, path } = await createArtifact(); - const service = new ReverseEngineeringService({ - run: async () => { - throw Object.assign(new Error("not found"), { code: "ENOENT" }); - }, - }); - - try { - const result = await service.executeRizinCommand({ path, command: "iI" }); - expect(result).toMatchObject({ - ok: false, - error: { - _tag: "AnalysisCapabilityUnavailableError", - providerId: "rizin", - operation: "execute_rizin_command", - reason: "Unable to run configured command (ENOENT)", - cause: { message: "not found" }, - }, - }); - } finally { - await rm(directory, { recursive: true, force: true }); - } - }); - - it("classifies a captured ENOENT as provider unavailability", async () => { - const { directory, path } = await createArtifact(); - const cause = Object.assign(new Error("launch failed"), { - stdout: "", - stderr: "", - code: "ENOENT", - signal: null, - killed: false, - }); - const service = new ReverseEngineeringService({ - run: async () => { - throw cause; - }, - }); - - try { - const result = await service.inspectWithObjdump({ - path, - operation: "file_headers", - }); - expect(result).toMatchObject({ - ok: false, - error: { - _tag: "AnalysisCapabilityUnavailableError", - providerId: "objdump.command", - reason: "Unable to run configured command (ENOENT)", - cause: { message: "launch failed" }, - }, - }); - } finally { - await rm(directory, { recursive: true, force: true }); - } - }); }; const registerSharedReverseEngineeringEdgeCasesPart6 = (): void => { @@ -698,7 +584,7 @@ const registerSharedReverseEngineeringEdgeCasesPart8 = (): void => { const { directory, path } = await createArtifact(); const controller = new AbortController(); const service = new ReverseEngineeringService({ - run: async () => ({ stdout: "completed output", stderr: "" }), + runOwned: async () => ownedOutput("completed output"), }); try { diff --git a/tests/support/reverseEngineeringCompositionFixtures.ts b/tests/support/reverseEngineeringCompositionFixtures.ts index b96233dcb4..0abf81710d 100644 --- a/tests/support/reverseEngineeringCompositionFixtures.ts +++ b/tests/support/reverseEngineeringCompositionFixtures.ts @@ -1,5 +1,6 @@ import { mkdtemp, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; +import { OwnedCommandFailure } from "../../src/process/OwnedCommand.js"; import type { ProviderProcessSnapshot } from "../../src/process/ProviderProcess.js"; import { join } from "node:path"; @@ -22,3 +23,52 @@ export const providerSnapshot = ( signal: null, ...overrides, }); + +/** What the owned supervisor returns for a provider process that ended. */ +export const ownedOutput = ( + stdout = "", + stderr = "", + overrides: Partial = {}, +): ProviderProcessSnapshot => { + const stdoutBytes = Buffer.byteLength(stdout); + const stderrBytes = Buffer.byteLength(stderr); + return { + stdout: { text: stdout, bytes: stdoutBytes, observedBytes: stdoutBytes }, + stderr: { text: stderr, bytes: stderrBytes, observedBytes: stderrBytes }, + exitCode: 0, + signal: null, + ...overrides, + }; +}; + +/** What the owned supervisor throws when a command does not finish normally. */ +export const ownedFailure = ( + reason: OwnedCommandFailure["reason"], + snapshot: ProviderProcessSnapshot | null, + options?: ConstructorParameters[4], +): OwnedCommandFailure => + new OwnedCommandFailure( + reason, + `owned command ${reason}`, + snapshot, + null, + options, + ); + +/** + * A launcher's refusal to start the command. The owned supervisor rethrows + * the launcher's spawn error unchanged. + */ +export const ownedLaunchRefusal = (code: string, command = "provider"): Error => + Object.assign(new Error(`spawn ${command} ${code}`), { + code, + syscall: `spawn ${command}`, + path: command, + }); + +/** Repair guidance for a test-built command profile. */ +export const fixtureCommandRepair = { + provider: "fixture", + setting: "REA_FIXTURE_COMMAND", + remediationAction: "Configure the fixture command.", +} as const;