diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index e8b1723b1a..7c9c0c6a5d 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -1,84 +1,5 @@ { "analysis-cancelled-constructor": { - "src/application/AnalysisContextQueries.ts": 6, - "src/application/AnalysisDocument.ts": 3, - "src/application/AnalysisInput.ts": 1, - "src/application/BinaryTargetResolver.ts": 8, - "src/application/BrowserObservationService.ts": 6, - "src/application/BrowserScenarioCaptureService.ts": 1, - "src/application/CallPathTracing.ts": 4, - "src/application/DirectAnalysis.ts": 2, - "src/application/Doctor.ts": 4, - "src/application/EnhancedLiteralTracing.ts": 1, - "src/application/EnhancedTools.ts": 2, - "src/application/EvidenceBundleCommands.ts": 1, - "src/application/EvidenceBundleFiles.ts": 3, - "src/application/EvidenceInputResolver.ts": 2, - "src/application/JsonFiles.ts": 8, - "src/application/McpClientRegistration.ts": 2, - "src/application/McpRegistrationCatalog.ts": 2, - "src/application/McpRegistrationGit.ts": 2, - "src/application/ProviderOperationExecution.ts": 2, - "src/application/ReferenceSourceImportTypes.ts": 2, - "src/application/Setup.ts": 1, - "src/application/SetupCancellation.ts": 1, - "src/application/WebModuleTraceService.ts": 1, - "src/application/WebNetworkCaptureService.ts": 1, - "src/application/WebScriptExportService.ts": 6, - "src/application/WebSourceLocationService.ts": 1, - "src/application/XrefsAddressResolution.ts": 2, - "src/application/analysisView/AnalysisViewService.ts": 1, - "src/application/analysisView/evidenceFileSource.ts": 2, - "src/application/android/AndroidAnalysisService.ts": 1, - "src/application/apiContract/ApiContractRead.ts": 1, - "src/application/apiContract/ApiContractTraversal.ts": 1, - "src/application/binary/AnalysisProviderEvaluation.ts": 2, - "src/application/binary/AnalysisProviderRegistry.ts": 12, - "src/application/binary/AnalysisSnapshotFiles.ts": 1, - "src/application/binary/BinarySession.ts": 36, - "src/application/binary/LazyAnalysisProvider.ts": 1, - "src/application/binaryDiagnostics/ByteEntropyService.ts": 3, - "src/application/decompileDirectory/decompileAll.ts": 1, - "src/application/desktop/DesktopApplicationCapture.ts": 2, - "src/application/desktop/DesktopApplicationState.ts": 6, - "src/application/desktop/DesktopBuildCapture.ts": 2, - "src/application/desktop/DesktopBuildCaptureFailure.ts": 1, - "src/application/desktop/DesktopBuildComputers.ts": 2, - "src/application/desktop/DesktopBuildExport.ts": 1, - "src/application/desktop/DesktopBuildOwnedWork.ts": 1, - "src/application/desktop/DesktopBuildSecrets.ts": 3, - "src/application/desktop/DesktopBuildSolves.ts": 2, - "src/application/desktop/DesktopBuildSteps.ts": 1, - "src/application/desktop/DesktopBuildTurns.ts": 1, - "src/application/desktop/DesktopBuildWitnessBundle.ts": 1, - "src/application/desktop/DesktopCaptureRefusals.ts": 4, - "src/application/desktop/DesktopExportFiles.ts": 1, - "src/application/desktop/DesktopExportInstall.ts": 1, - "src/application/desktop/DesktopOutputTree.ts": 1, - "src/application/desktop/DesktopRemoteTaskReaders.ts": 1, - "src/application/desktop/DesktopTaskDraft.ts": 1, - "src/application/desktop/DesktopTaskReaderCleanup.ts": 1, - "src/application/environment/environmentBuild.ts": 1, - "src/application/firmware/FirmwareAnalysisService.ts": 1, - "src/application/frida/FridaInstrumentationService.ts": 7, - "src/application/gpu/GpuCodeObjectsService.ts": 2, - "src/application/il2cpp/Il2cppMetadataService.ts": 1, - "src/application/javascript/ElectronActiveObservationService.ts": 2, - "src/application/javascript/ElectronObservationService.ts": 2, - "src/application/javascript/JavaScriptArtifactAnalysis.ts": 3, - "src/application/javascript/JavaScriptRuntimeObservationService.ts": 2, - "src/application/javascript/SourceToBundleReference.ts": 3, - "src/application/javascript/StaticObservedEndpointComparisonService.ts": 2, - "src/application/model/ModelArtifactService.ts": 2, - "src/application/native/NativeFunctionMatchingService.ts": 1, - "src/application/native/NativeValueTrace.ts": 2, - "src/application/ntfs/NtfsJournalService.ts": 1, - "src/application/pcap/PcapAnalysisService.ts": 1, - "src/application/process/ProcessCli.ts": 5, - "src/application/process/ProcessScenarioPreparation.ts": 2, - "src/application/releaseExposure/ReleaseExposureService.ts": 3, - "src/application/reverse/ReverseEngineeringService.ts": 12, - "src/application/wasm/WasmInterfaceComparisonService.ts": 2, "src/gdb/GdbSessionManager.ts": 1, "src/process/ownedDebuggerSession.ts": 1 }, diff --git a/src/application/AnalysisContextQueries.ts b/src/application/AnalysisContextQueries.ts index 81fc863dc6..db07c2311b 100644 --- a/src/application/AnalysisContextQueries.ts +++ b/src/application/AnalysisContextQueries.ts @@ -10,6 +10,8 @@ import { AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, } from "../domain/analysisErrorCore.js"; import { omitUnretainedEvidenceFromError, @@ -76,11 +78,7 @@ export const getNavigationContext = async ( signal?: AbortSignal, ): Promise> => { if (signal?.aborted) - return err( - new AnalysisCancelledError("get_navigation_context", { - cause: signal.reason, - }), - ); + return err(cancelledBy("get_navigation_context", signal)); const document = input.document ?? (await analysis.execute("current_document", {}, executionOptions(signal))); @@ -95,11 +93,7 @@ export const getNavigationContext = async ( ), ); if (signal?.aborted) - return err( - new AnalysisCancelledError("get_navigation_context", { - cause: signal.reason, - }), - ); + return err(cancelledBy("get_navigation_context", signal)); const documentArgs = parameters(documentName); const address = await analysis.execute( "current_address", @@ -112,11 +106,7 @@ export const getNavigationContext = async ( new AnalysisOutputError("current_address", "expected an address string"), ); if (signal?.aborted) - return err( - new AnalysisCancelledError("get_navigation_context", { - cause: signal.reason, - }), - ); + return err(cancelledBy("get_navigation_context", signal)); const procedure = await analysis.execute( "resolve_containing_procedure", parameters(documentName, address.value.result), @@ -126,11 +116,7 @@ export const getNavigationContext = async ( const resolution = parseContainingProcedureResolution(procedure.value.result); if (!resolution.ok) return resolution; if (signal?.aborted) - return err( - new AnalysisCancelledError("get_navigation_context", { - cause: signal.reason, - }), - ); + return err(cancelledBy("get_navigation_context", signal)); return ok({ document: documentName, address: address.value.result, @@ -204,16 +190,14 @@ export const inspectAddressContext = async ( const operations = ADDRESS_CONTEXT_FACET_OPERATIONS; const completed: Result[] = []; if (signal?.aborted === true) - return err( - new AnalysisCancelledError("inspect_address_context", { - cause: signal.reason, - }), - ); + return err(cancelledBy("inspect_address_context", signal)); let signalCancellation: AnalysisCancelledError | undefined; const cancelled = () => { - signalCancellation = new AnalysisCancelledError("inspect_address_context", { - cause: signal?.reason, - }); + // Registered only on the caller's signal, so this runs after it aborted. + signalCancellation = cancelledBy( + "inspect_address_context", + carriedReason(signal?.reason), + ); completed.push(err(signalCancellation)); }; signal?.addEventListener("abort", cancelled, { once: true }); diff --git a/src/application/AnalysisDocument.ts b/src/application/AnalysisDocument.ts index 393d35a9b7..993d29d470 100644 --- a/src/application/AnalysisDocument.ts +++ b/src/application/AnalysisDocument.ts @@ -5,8 +5,8 @@ import type { } from "./AnalysisProvider.js"; import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js"; import { - AnalysisCancelledError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { parseDocuments } from "../domain/native/nativeDocument.js"; @@ -23,9 +23,7 @@ export const resolveAnalysisDocument = async ( ): Promise> => { if (document !== undefined) return ok(document); if (signal?.aborted === true) - return err( - new AnalysisCancelledError("current_document", { cause: signal.reason }), - ); + return err(cancelledBy("current_document", signal)); const current = await analysis.execute( "current_document", {}, @@ -33,12 +31,7 @@ export const resolveAnalysisDocument = async ( ); if (!current.ok) { if (!permitsCapabilityFallback(current.error)) return current; - if (signal?.aborted) - return err( - new AnalysisCancelledError("current_document", { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy("current_document", signal)); const listed = await analysis.execute( "list_documents", {}, @@ -101,8 +94,7 @@ const completeSelection = ( ): Result => { if (signal?.aborted) return err( - new AnalysisCancelledError(operation, { - cause: signal.reason, + cancelledBy(operation, signal, { partialObservation: createAnalysisExecutionEvidence( operation, {}, diff --git a/src/application/AnalysisInput.ts b/src/application/AnalysisInput.ts index 556dc99564..e386a19671 100644 --- a/src/application/AnalysisInput.ts +++ b/src/application/AnalysisInput.ts @@ -1,6 +1,6 @@ import type { z } from "zod"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { cancelledBy } from "../domain/analysisErrorCore.js"; import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -11,8 +11,7 @@ export const parseAnalysisInput = ( schema: z.ZodType, signal?: AbortSignal, ): Result => { - if (signal?.aborted) - return err(new AnalysisCancelledError(operation, { cause: signal.reason })); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const input = schema.safeParse(rawInput); if (!input.success) return err( diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index 6e9a702034..acae80bbd3 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -31,7 +31,11 @@ import { type StableRegularFileDescriptor, } from "../filesystem/RegularFile.js"; import { hashStableRegularFileDescriptor } from "../filesystem/StableFileHash.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, + carriedReason, +} from "../domain/analysisErrorCore.js"; import type { BinaryTarget, BinaryArchitecture, @@ -155,11 +159,7 @@ export const parseBinaryTarget = async ( const admitted = localPathStringSchema.safeParse(input); if (!admitted.success) { if (signal?.aborted === true) - return err( - new AnalysisCancelledError("resolve_binary_target", { - cause: signal.reason, - }), - ); + return err(cancelledBy("resolve_binary_target", signal)); return err( new BinaryTargetError( input, @@ -224,9 +224,7 @@ export const parseBinaryTarget = async ( } catch (cause: unknown) { // A caller-selected abort value never transfers file ownership. if (signal?.aborted === true && cause === signal.reason) - return err( - new AnalysisCancelledError("resolve_binary_target", { cause }), - ); + return err(cancelledBy("resolve_binary_target", carriedReason(cause))); if (cause instanceof RegularFileCleanupFailure) { const fileFailure = cause as RegularFileCleanupFailure; if (options.resources === undefined) @@ -549,8 +547,7 @@ const finalizedTargetResolution = ( ): TargetResolution => { if (!result.ok || signal?.aborted !== true) return result; return err( - new AnalysisCancelledError("resolve_binary_target", { - cause: signal.reason, + cancelledBy("resolve_binary_target", signal, { diagnostics: { completed_target: jsonValueSchema.parse(result.value) }, }), ); @@ -575,9 +572,10 @@ const targetFileCleanupError = ( physical instanceof AnalysisCancelledError ? physical : cancellation !== undefined - ? new AnalysisCancelledError("resolve_binary_target", { - cause: cancellation.reason, - }) + ? cancelledBy( + "resolve_binary_target", + carriedReason(cancellation.reason), + ) : (classifyTargetFilesystemFailure(candidate, physical, stage) ?? new BinaryTargetError( failure.path, @@ -586,12 +584,13 @@ const targetFileCleanupError = ( )); } else if (completed?.ok === false) primary = completed.error; else if (cancellation !== undefined) - primary = new AnalysisCancelledError("resolve_binary_target", { - cause: cancellation.reason, - ...(completedTarget === undefined + primary = cancelledBy( + "resolve_binary_target", + carriedReason(cancellation.reason), + completedTarget === undefined ? {} - : { diagnostics: { completed_target: completedTarget } }), - }); + : { diagnostics: { completed_target: completedTarget } }, + ); const error = new BinaryTargetError( failure.path, "The target file handle could not be closed", @@ -637,15 +636,14 @@ const targetResolutionFailure = ( const cancellation = regularFileCancellation(cause); if (cancellation !== undefined) return err( - new AnalysisCancelledError("resolve_binary_target", { - cause: cancellation.reason, - }), + cancelledBy( + "resolve_binary_target", + carriedReason(cancellation.reason), + ), ); } if (signal?.aborted === true && physical === signal.reason) - return err( - new AnalysisCancelledError("resolve_binary_target", { cause: physical }), - ); + return err(cancelledBy("resolve_binary_target", carriedReason(physical))); const failure = classifyTargetFilesystemFailure(candidate, physical, stage); if (failure === undefined) throw physical; return err(failure); @@ -715,9 +713,7 @@ const targetFailureReason = ( const throwIfTargetResolutionCancelled = (signal?: AbortSignal): void => { if (signal?.aborted === true) - throw new AnalysisCancelledError("resolve_binary_target", { - cause: signal.reason, - }); + throw cancelledBy("resolve_binary_target", signal); }; const detectArtifactFormat = async ( diff --git a/src/application/BrowserObservationService.ts b/src/application/BrowserObservationService.ts index 6dffb5abf0..c157a3fcdb 100644 --- a/src/application/BrowserObservationService.ts +++ b/src/application/BrowserObservationService.ts @@ -27,9 +27,9 @@ import { type CompareWebScreenshotsInput, } from "../domain/webScreenshot.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -67,11 +67,7 @@ export const listBrowserTargets = async ( const ready = requireBrowser(browser, "list_browser_targets"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("list_browser_targets", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("list_browser_targets", options.signal)); const result = await ready.value.listTargets(input, options); return result.ok ? browserEvidence( @@ -93,11 +89,7 @@ export const inspectWebPage = async ( const ready = requireBrowser(browser, "inspect_web_page"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("inspect_web_page", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("inspect_web_page", options.signal)); const result = await ready.value.inspectPage(input, options); if (!result.ok) return retainBrowserObservation( @@ -126,11 +118,7 @@ export const analyzeWebBundle = async ( const ready = requireBrowser(browser, "analyze_web_bundle"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("analyze_web_bundle", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("analyze_web_bundle", options.signal)); const analyzed = await ready.value.analyzeBundle(input, options); if (!analyzed.ok) return retainBrowserObservation( @@ -157,11 +145,7 @@ export const observeWebSession = async ( const ready = requireBrowser(browser, "observe_web_session"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("observe_web_session", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("observe_web_session", options.signal)); const observed = await ready.value.observeSession(input, options); return observed.ok ? browserEvidence( @@ -183,11 +167,7 @@ export const discoverWebMcpTools = async ( const ready = requireBrowser(browser, "discover_webmcp_tools"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("discover_webmcp_tools", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("discover_webmcp_tools", options.signal)); const discovered = await ready.value.discoverWebMcpTools(input, options); return discovered.ok ? browserEvidence( @@ -228,11 +208,7 @@ export const captureWebScreenshot = async ( const ready = requireBrowser(browser, "capture_web_screenshot"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("capture_web_screenshot", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("capture_web_screenshot", options.signal)); const captured = await ready.value.captureScreenshot(input, options); return captured.ok ? browserEvidence( diff --git a/src/application/BrowserScenarioCaptureService.ts b/src/application/BrowserScenarioCaptureService.ts index fbb38708ee..f16b97f7af 100644 --- a/src/application/BrowserScenarioCaptureService.ts +++ b/src/application/BrowserScenarioCaptureService.ts @@ -2,9 +2,9 @@ import type { ExecutionOptions } from "./AnalysisProvider.js"; import type { BrowserScenarioCapturePort } from "./BrowserScenarioCapturePort.js"; import { createBrowserScenarioEvidence } from "./BrowserScenarioEvidence.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { Evidence } from "../domain/evidence.js"; @@ -36,9 +36,7 @@ export const captureBrowserScenario = async ( ), ); if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); const captured = await provider.captureScenario(scenario, options); if (!captured.ok) { keepIncompleteObservation( diff --git a/src/application/CallPathTracing.ts b/src/application/CallPathTracing.ts index 574692bafb..46a50da1ee 100644 --- a/src/application/CallPathTracing.ts +++ b/src/application/CallPathTracing.ts @@ -10,7 +10,7 @@ import type { ExecutionOptions, } from "./AnalysisProvider.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { isAborted, cancelledBy } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -101,21 +101,13 @@ export const traceCallPath = async ( ...(goal === undefined ? {} : { goal }), direction: input.direction, }; - if (isAborted(signal)) - return err( - new AnalysisCancelledError("trace_call_path", { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("trace_call_path", signal)); const state = createTraceState(resolvedInput); while ( state.queueIndex < state.queue.length && state.traversalPath.length === 0 ) { - if (isAborted(signal)) - return err( - new AnalysisCancelledError("trace_call_path", { - cause: signal?.reason, - }), - ); + if (isAborted(signal)) return err(cancelledBy("trace_call_path", signal)); const address = state.queue[state.queueIndex++]; if (address === undefined) break; const current = state.visited.get(address); @@ -139,10 +131,7 @@ export const traceCallPath = async ( } if (expanded.value) break; } - if (isAborted(signal)) - return err( - new AnalysisCancelledError("trace_call_path", { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("trace_call_path", signal)); return ok(projectTrace(resolvedInput, state)); }; @@ -186,10 +175,7 @@ const expandAddress = async ( (read.status === "unavailable" && isAborted(signal)) ) return err(read.error); - if (isAborted(signal)) - return err( - new AnalysisCancelledError("trace_call_path", { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("trace_call_path", signal)); if (read.status !== "observed") { state.failures.push({ address, @@ -334,6 +320,3 @@ const compareAddress = (left: string, right: string): number => const sortedUniqueAddresses = (addresses: readonly string[]): string[] => [...new Set(addresses)].sort(compareAddress); - -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts index b80a6a2cd1..3e04ae60f3 100644 --- a/src/application/DirectAnalysis.ts +++ b/src/application/DirectAnalysis.ts @@ -82,8 +82,8 @@ import { import type { AnalysisProviderSelector } from "../domain/providerSelection.js"; import { resolveXrefsAddress } from "./XrefsAddressResolution.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, CallerAbort, } from "../domain/analysisErrorCore.js"; import { deliverAnalysisEvidence } from "./EvidenceBundleCommands.js"; @@ -279,8 +279,7 @@ export const runProviderAnalysis = async ( if (operationSignal.aborted) return err( cliError( - new AnalysisCancelledError(tool, { - cause: operationSignal.reason, + cancelledBy(tool, operationSignal, { partialObservation: evidence, }), ), @@ -702,10 +701,7 @@ const retainFinalCancellation = ( signal: AbortSignal, ): AnalysisError => signal.aborted - ? analysisErrorWithCancellation( - failure, - new AnalysisCancelledError(tool, { cause: signal.reason }), - ) + ? analysisErrorWithCancellation(failure, cancelledBy(tool, signal)) : failure; const executeAnalysisTool = async (input: { diff --git a/src/application/Doctor.ts b/src/application/Doctor.ts index ae9ee5bfc0..e77dbc5ea3 100644 --- a/src/application/Doctor.ts +++ b/src/application/Doctor.ts @@ -2,6 +2,8 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisCancelledError, + cancelledBy, + carriedReason, OwnerCancellation, } from "../domain/analysisErrorCore.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; @@ -280,8 +282,7 @@ export const runDoctorOwned = async ( } const cleanup = await closeDoctorHost(host); if (cleanup === undefined && report.healthy && host.signal?.aborted) - throw new AnalysisCancelledError("doctor", { - cause: host.signal.reason, + throw cancelledBy("doctor", host.signal, { diagnostics: { doctor_report: jsonValueSchema.parse(report) }, }); return cleanup === undefined @@ -294,8 +295,7 @@ const inspectDoctor = async ( host: DoctorHost, requestedScope?: DoctorScope, ): Promise => { - if (host.signal?.aborted) - throw new AnalysisCancelledError("doctor", { cause: host.signal.reason }); + if (host.signal?.aborted) throw cancelledBy("doctor", host.signal); const scope = normalizeDoctorScope(requestedScope, target); const { checks: diagnosticChecks, @@ -724,8 +724,7 @@ export const systemDoctorHost = ( signal: inspectionSignal, }); if (inspectionSignal.aborted) - throw new AnalysisCancelledError("doctor", { - cause: inspectionSignal.reason, + throw cancelledBy("doctor", inspectionSignal, { capturedOutput: { stdout: output.stdout, stderr: output.stderr, @@ -740,12 +739,13 @@ export const systemDoctorHost = ( } catch (cause: unknown) { if (cause instanceof ExecFileOutputCancelledError) { const output = execFileOutputFailure(cause); - throw new AnalysisCancelledError("doctor", { - cause: cause.cause, - ...(output === undefined + throw cancelledBy( + "doctor", + carriedReason(cause.cause), + output === undefined ? {} - : { capturedOutput: execFileFailureCapturedOutput(output) }), - }); + : { capturedOutput: execFileFailureCapturedOutput(output) }, + ); } throw cause; } diff --git a/src/application/EnhancedLiteralTracing.ts b/src/application/EnhancedLiteralTracing.ts index 5fd6806691..c03ab33c60 100644 --- a/src/application/EnhancedLiteralTracing.ts +++ b/src/application/EnhancedLiteralTracing.ts @@ -10,9 +10,9 @@ import type { AnalysisOperationPort, } from "./AnalysisProvider.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { JsonValue } from "../domain/jsonValue.js"; @@ -209,11 +209,7 @@ const traceReferences = async ( ) return resolved; if (request.signal?.aborted === true) - return err( - new AnalysisCancelledError("trace_feature", { - cause: request.signal.reason, - }), - ); + return err(cancelledBy("trace_feature", request.signal)); containingProcedure = { query_address: source, status: "unavailable", diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts index 91fdf12fe9..70f31506ba 100644 --- a/src/application/EnhancedTools.ts +++ b/src/application/EnhancedTools.ts @@ -25,8 +25,9 @@ import { type EnhancedToolName, } from "../contracts/enhancedInputs.js"; import { - AnalysisCancelledError, AnalysisOutputError, + isAborted, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; @@ -824,15 +825,13 @@ export class EnhancedTools { signal?: AbortSignal, selectorOrigin?: ExecutionOptions["selectorOrigin"], ): Promise> { - if (isAborted(signal)) - return err(new AnalysisCancelledError(name, { cause: signal?.reason })); + if (isAborted(signal)) return err(cancelledBy(name, signal)); const execution = await this.analysis.execute(name, arguments_, { ...(signal === undefined ? {} : { signal }), ...(selectorOrigin === undefined ? {} : { selectorOrigin }), }); if (!execution.ok) return execution; - if (isAborted(signal)) - return err(new AnalysisCancelledError(name, { cause: signal?.reason })); + if (isAborted(signal)) return err(cancelledBy(name, signal)); return execution; } } @@ -849,6 +848,3 @@ const addressedNames = ( name, ...(objc_class_label === undefined ? {} : { objc_class_label }), })); - -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; diff --git a/src/application/EvidenceBundleCommands.ts b/src/application/EvidenceBundleCommands.ts index d2a060f89e..c058938f47 100644 --- a/src/application/EvidenceBundleCommands.ts +++ b/src/application/EvidenceBundleCommands.ts @@ -10,8 +10,8 @@ import { } from "../domain/evidenceErrors.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { withEvidenceCallerInputPath, @@ -230,8 +230,7 @@ export const publishEvidenceDelivery = async (input: { } if (signal?.aborted) return err( - new AnalysisCancelledError(operation, { - cause: signal.reason, + cancelledBy(operation, signal, { partialObservation: input.delivered, diagnostics: { evidence_bundle: { ...written.value } }, }), diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts index 7e79634bbd..d091d3f95a 100644 --- a/src/application/EvidenceBundleFiles.ts +++ b/src/application/EvidenceBundleFiles.ts @@ -22,6 +22,7 @@ import { err, ok, type Result } from "../domain/result.js"; import { AnalysisCancelledError, type AnalysisResourceConstraintError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { safeParseProcessCapture } from "../domain/process/processCaptureParsing.js"; import { @@ -105,20 +106,10 @@ const readBundle = async ( resources?: ArtifactResourceScope, operation = "import_evidence_bundle", ): Promise> => { - if (signal?.aborted) - return err( - new AnalysisCancelledError(operation, { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const loaded = await readJsonFile(path, signal, resources, operation); if (!loaded.ok) return loaded; - if (signal?.aborted) - return err( - new AnalysisCancelledError(operation, { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy(operation, signal)); return authenticateEvidenceBundleValue(loaded.value, path, { operation, immutable, @@ -225,12 +216,7 @@ export const writeEvidenceBundle = async ( EvidenceBundleFileFailure > > => { - if (signal?.aborted === true) - return err( - new AnalysisCancelledError(operation, { - cause: signal.reason, - }), - ); + if (signal?.aborted === true) return err(cancelledBy(operation, signal)); if (!isImmutableEvidenceBundle(bundle)) { const issue = jsonValueValidationIssue(bundle); if (issue !== undefined) diff --git a/src/application/EvidenceInputResolver.ts b/src/application/EvidenceInputResolver.ts index 327463a04f..fa4f824002 100644 --- a/src/application/EvidenceInputResolver.ts +++ b/src/application/EvidenceInputResolver.ts @@ -12,7 +12,7 @@ import { } from "../domain/evidenceInputContract.js"; import { retainedEvidenceReferenceSchema } from "../domain/evidenceReference.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { cancelledBy } from "../domain/analysisErrorCore.js"; import { EvidenceReferenceError } from "../domain/evidenceErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; @@ -92,11 +92,7 @@ export function resolveEvidenceRequest( parsed.value, (input, path) => { if (options.signal?.aborted) - return err( - new AnalysisCancelledError(operation, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(operation, options.signal)); let selected = input; if (typeof input === "object" && input !== null && "kind" in input) { const reference = retainedEvidenceReferenceSchema.safeParse(input); @@ -147,9 +143,7 @@ export function resolveEvidenceRequest( }, ); if (result.ok && options.signal?.aborted) - return err( - new AnalysisCancelledError(operation, { cause: options.signal.reason }), - ); + return err(cancelledBy(operation, options.signal)); return result.ok ? ok({ input: result.value, diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.ts index 2cea42d3c2..f5143f99e8 100644 --- a/src/application/JsonFiles.ts +++ b/src/application/JsonFiles.ts @@ -18,6 +18,9 @@ import { AnalysisCancelledError, type AnalysisInputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, + type AbortedSignal, } from "../domain/analysisErrorCore.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { childFailureDiagnostics } from "../domain/analysisErrorProjection.js"; @@ -161,7 +164,7 @@ const readJsonFileInput = async ( } catch (cause: unknown) { // Caller reasons are opaque, including instances of lifecycle failure types. if (signal?.aborted === true && cause === signal.reason) - return err(new AnalysisCancelledError(operation, { cause })); + return err(cancelledBy(operation, carriedReason(cause))); if (cause instanceof RegularFileCleanupFailure) return err( jsonFileCleanupError( @@ -174,13 +177,15 @@ const readJsonFileInput = async ( if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) { const primary = cause.reason === "cancelled" - ? new AnalysisCancelledError(operation, { - cause: + ? cancelledBy( + operation, + carriedReason( cause.cancellation === undefined ? cause.cause : cause.cancellation.reason, - partialObservation: cause.partialObservation, - }) + ), + { partialObservation: cause.partialObservation }, + ) : undefined; const error = new EvidenceFileError("read", "io", { cause, @@ -232,14 +237,14 @@ const jsonFileReadFailure = ( ): JsonFileReadFailure => { if (cause instanceof AnalysisResourceConstraintError) return cause; if (cause instanceof JsonInputCancellationFailure) - return new AnalysisCancelledError(operation, { cause: cause.reason }); + return cancelledBy(operation, carriedReason(cause.reason)); if (cause instanceof JsonInputPhysicalReadFailure) return new EvidenceFileError("read", "io", { cause: cause.physicalCause, path, }); if (isJsonReadCancellation(cause, signal)) - return new AnalysisCancelledError(operation, { cause: signal?.reason }); + return cancelledBy(operation, signal); return new EvidenceFileError( "read", cause instanceof NonRegularFileReadError @@ -275,14 +280,12 @@ const jsonFileCleanupError = ( primary = cancellation === undefined ? jsonFileReadFailure(failure.outcome.cause, path, operation, signal) - : new AnalysisCancelledError(operation, { cause: cancellation.reason }); + : cancelledBy(operation, carriedReason(cancellation.reason)); } else { const decoded = decodedJsonFileResult(failure.outcome.value, path); if (!decoded.ok) primary = decoded.error; else if (cancellation !== undefined) - primary = new AnalysisCancelledError(operation, { - cause: cancellation.reason, - }); + primary = cancelledBy(operation, carriedReason(cancellation.reason)); } if (primary === undefined) return cleanup; const combined = new EvidenceFileError("read", "io", { @@ -303,7 +306,7 @@ const jsonFileCleanupError = ( const isJsonReadCancellation = ( cause: unknown, signal?: AbortSignal, -): boolean => { +): signal is AbortedSignal => { if (signal?.aborted !== true) return false; if (cause === signal.reason) return true; return ( @@ -430,11 +433,11 @@ const writeTextPartsOwned = async ( ); if (cause.outcome.error instanceof AnalysisCancelledError) return stagedCleanupFailure( - new AnalysisCancelledError(cause.outcome.error.operation, { - cause: cause.outcome.error.cause, - cleanupPrimary: cause.outcome.error, - cleanup, - }), + cancelledBy( + cause.outcome.error.operation, + carriedReason(cause.outcome.error.cause), + { cleanupPrimary: cause.outcome.error, cleanup }, + ), cause.lease, ); const failure = classifyWriteFailure(cause.outcome.error); @@ -683,9 +686,7 @@ const writeStagedParts = async ( const assertWriteActive = (cancellation?: TextWriteCancellation): void => { if (cancellation?.signal.aborted === true) - throw new AnalysisCancelledError(cancellation.operation, { - cause: cancellation.signal.reason, - }); + throw cancelledBy(cancellation.operation, cancellation.signal); }; const fileErrorCode = (cause: unknown): unknown => diff --git a/src/application/LinuxHopper.ts b/src/application/LinuxHopper.ts index 3aa683c58e..7392b28903 100644 --- a/src/application/LinuxHopper.ts +++ b/src/application/LinuxHopper.ts @@ -1,3 +1,4 @@ +import { isAborted } from "../domain/analysisErrorCore.js"; import { appendCallerPath } from "../filesystem/callerPath.js"; import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js"; import type { HopperInstallFailureReason } from "./SetupInstallFailure.js"; @@ -725,9 +726,6 @@ const installSystemPackage = async ( return { status: "installed" }; }; -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; - /** Retain the publisher's error and any vendor request facts it observed. */ const publisherFailure = ( error: HopperReleaseError, diff --git a/src/application/LinuxHopperPython.ts b/src/application/LinuxHopperPython.ts index f61019ae32..ae41bfc2b0 100644 --- a/src/application/LinuxHopperPython.ts +++ b/src/application/LinuxHopperPython.ts @@ -1,3 +1,4 @@ +import { isAborted } from "../domain/analysisErrorCore.js"; import { posix } from "node:path"; import { z } from "zod"; @@ -70,8 +71,6 @@ const runtimeCommand = { } as const; // AbortSignal changes while an awaited process runs, despite its readonly type. -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; /** Fresh, bounded inspection; package or interpreter changes must be observable. */ export const inspectLinuxHopperPythonRuntime = async ( diff --git a/src/application/McpClientRegistration.ts b/src/application/McpClientRegistration.ts index bb51bb6be6..4b5d962c62 100644 --- a/src/application/McpClientRegistration.ts +++ b/src/application/McpClientRegistration.ts @@ -7,7 +7,10 @@ import { AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js"; import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../domain/analysisErrorCore.js"; import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; import { ConfigurationError } from "../domain/configurationErrors.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -129,8 +132,7 @@ export const registerMcpClient = async ( let configured = false; const checkCancellation = (): void => { if (signal?.aborted === true) - throw new AnalysisCancelledError("MCP registration", { - cause: signal.reason, + throw cancelledBy("MCP registration", signal, { diagnostics: { client: client.id, settings_path: settingsPath, @@ -224,9 +226,7 @@ export const registerMcpClient = async ( if (signal?.aborted === true) analysisErrorWithCancellation( failure, - new AnalysisCancelledError("MCP registration", { - cause: signal.reason, - }), + cancelledBy("MCP registration", signal), ); return err(failure); } diff --git a/src/application/McpRegistrationCatalog.ts b/src/application/McpRegistrationCatalog.ts index 49e1e61a75..40b11fbfff 100644 --- a/src/application/McpRegistrationCatalog.ts +++ b/src/application/McpRegistrationCatalog.ts @@ -2,7 +2,10 @@ import { kiloLocation, kiloProjectLocation, } from "./McpRegistrationKiloLocations.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../domain/analysisErrorCore.js"; import { dirname, join, win32 } from "node:path"; import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; @@ -260,10 +263,7 @@ export interface McpRegistrationSelection { type CatalogFailure = ConfigurationError | AnalysisCancelledError; const checkCancellation = (signal: AbortSignal | undefined): void => { - if (signal?.aborted) - throw new AnalysisCancelledError("MCP registration selection", { - cause: signal.reason, - }); + if (signal?.aborted) throw cancelledBy("MCP registration selection", signal); }; const selectedIds = (agents: readonly string[]): McpRegistrationClientId[] => { @@ -509,9 +509,7 @@ export const resolveMcpRegistrationClients = async ( if (selection.signal?.aborted === true) analysisErrorWithCancellation( failure, - new AnalysisCancelledError("MCP registration selection", { - cause: selection.signal.reason, - }), + cancelledBy("MCP registration selection", selection.signal), ); return err(failure); } diff --git a/src/application/McpRegistrationGit.ts b/src/application/McpRegistrationGit.ts index 25cb87157f..1f42dfacb6 100644 --- a/src/application/McpRegistrationGit.ts +++ b/src/application/McpRegistrationGit.ts @@ -1,7 +1,11 @@ import { lstat, realpath } from "node:fs/promises"; import { dirname, isAbsolute, relative, sep } from "node:path"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, + carriedReason, +} from "../domain/analysisErrorCore.js"; import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; import { ConfigurationError } from "../domain/configurationErrors.js"; import { absoluteCallerPath } from "../filesystem/callerPath.js"; @@ -30,9 +34,7 @@ const gitFailure = ( cause: unknown, ): ConfigurationError | AnalysisCancelledError => cause instanceof ExecFileOutputCancelledError - ? new AnalysisCancelledError("Kilo project root discovery", { - cause: cause.cause, - }) + ? cancelledBy("Kilo project root discovery", carriedReason(cause.cause)) : new ConfigurationError( "Kilo project root could not be established by read-only Git metadata. Repair Git or repository access, or register globally; no client settings were written.", { cause }, @@ -199,9 +201,7 @@ export const resolveKiloRegistrationWorktree = async ( if (context.signal?.aborted === true) analysisErrorWithCancellation( failure, - new AnalysisCancelledError("Kilo project root discovery", { - cause: context.signal.reason, - }), + cancelledBy("Kilo project root discovery", context.signal), ); throw failure; } diff --git a/src/application/ProviderOperationExecution.ts b/src/application/ProviderOperationExecution.ts index ce441b57a9..1ecce6f073 100644 --- a/src/application/ProviderOperationExecution.ts +++ b/src/application/ProviderOperationExecution.ts @@ -7,6 +7,7 @@ import type { import { AnalysisCancelledError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import type { Evidence } from "../domain/evidence.js"; import { @@ -54,9 +55,7 @@ export const executeProviderOperation = async < confidence: "observed" | "derived", ): Promise> => { if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(operation, { cause: options.signal.reason }), - ); + return err(cancelledBy(operation, options.signal)); const request = schema.safeParse({ operation, input }); if (!request.success) return err( @@ -86,8 +85,7 @@ export const completeProviderEvidence = ( ): Result => { if (signal?.aborted) return err( - new AnalysisCancelledError(evidence.operation, { - cause: signal.reason, + cancelledBy(evidence.operation, signal, { partialObservation: evidence, ...(capturedOutput === undefined ? {} : { capturedOutput }), }), diff --git a/src/application/ReferenceSourceImport.ts b/src/application/ReferenceSourceImport.ts index 4229125b03..7d901eb928 100644 --- a/src/application/ReferenceSourceImport.ts +++ b/src/application/ReferenceSourceImport.ts @@ -1,3 +1,4 @@ +import { isAborted } from "../domain/analysisErrorCore.js"; import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js"; import { createHistoricalSourceGraph, @@ -47,8 +48,6 @@ const cancelled = ( ...(partial === undefined ? {} : { partial }), }); -const isAborted = (signal?: AbortSignal): boolean => signal?.aborted === true; - const deduplicateRelationships = ( relationships: HistoricalSourceGraphInput["relationships"], ): HistoricalSourceGraphInput["relationships"] => { diff --git a/src/application/ReferenceSourceImportPolicy.ts b/src/application/ReferenceSourceImportPolicy.ts index f13cf1f75f..e0a495854f 100644 --- a/src/application/ReferenceSourceImportPolicy.ts +++ b/src/application/ReferenceSourceImportPolicy.ts @@ -1,3 +1,4 @@ +import { isAborted } from "../domain/analysisErrorCore.js"; import { lstat, realpath, stat } from "node:fs/promises"; import fs from "node:fs"; import { join } from "node:path"; @@ -66,8 +67,6 @@ const ignorePolicyCause = (cause: unknown): unknown => ? cause.operationCause : cause; -const isAborted = (signal?: AbortSignal): boolean => signal?.aborted === true; - const addMarkedPatterns = ( matcher: ReturnType, patterns: readonly string[], diff --git a/src/application/ReferenceSourceImportTypes.ts b/src/application/ReferenceSourceImportTypes.ts index 91b6d0c7ef..06a74e8b1b 100644 --- a/src/application/ReferenceSourceImportTypes.ts +++ b/src/application/ReferenceSourceImportTypes.ts @@ -1,8 +1,9 @@ import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, + cancelledBy, + carriedReason, } from "../domain/analysisErrorCore.js"; import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js"; import type { @@ -71,12 +72,14 @@ export const referenceSourceImportAnalysisError = ( }; let primary: AnalysisError; switch (error.code) { - case "cancelled": - primary = new AnalysisCancelledError("import_reference_source", { - ...options, + case "cancelled": { + const { cause: reason, ...rest } = options; + primary = cancelledBy("import_reference_source", carriedReason(reason), { + ...rest, userMessage: message, }); break; + } case "invalid-root": primary = new AnalysisInputError( "import_reference_source", @@ -115,9 +118,10 @@ export const referenceSourceImportAnalysisError = ( ? primary : analysisErrorWithCancellation( primary, - new AnalysisCancelledError("import_reference_source", { - cause: error.secondaryCancellation.cause, - }), + cancelledBy( + "import_reference_source", + carriedReason(error.secondaryCancellation.cause), + ), ); }; diff --git a/src/application/ReferenceSourceVcsAdapter.ts b/src/application/ReferenceSourceVcsAdapter.ts index fd39d79221..2620519686 100644 --- a/src/application/ReferenceSourceVcsAdapter.ts +++ b/src/application/ReferenceSourceVcsAdapter.ts @@ -1,3 +1,4 @@ +import { isAborted } from "../domain/analysisErrorCore.js"; import fs from "node:fs"; import { join } from "node:path"; import { @@ -282,5 +283,3 @@ const errorCode = (cause: unknown): string | undefined => const errorMessage = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause); - -const isAborted = (signal?: AbortSignal): boolean => signal?.aborted === true; diff --git a/src/application/Setup.ts b/src/application/Setup.ts index 7e918af3f9..830d7a5ff5 100644 --- a/src/application/Setup.ts +++ b/src/application/Setup.ts @@ -33,7 +33,10 @@ import { } from "../domain/analysisErrorBase.js"; import { setupCleanupError, setupCleanupReason } from "./SetupCleanupOwner.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../domain/analysisErrorCore.js"; import { jsonValueSchema } from "../domain/jsonValue.js"; import { assertSetupActive } from "./SetupCancellation.js"; import type { @@ -159,8 +162,7 @@ export const runSetup = async ( } // Cancellation observed only during the final doctor or cleanup is not success. if (options.signal?.aborted === true) { - const cancelled = new AnalysisCancelledError("setup", { - cause: options.signal.reason, + const cancelled = cancelledBy("setup", options.signal, { diagnostics: { setup_result: jsonValueSchema.parse(result) }, }); if (cleanup !== undefined) diff --git a/src/application/SetupCancellation.ts b/src/application/SetupCancellation.ts index 1d26a20c70..acf037592f 100644 --- a/src/application/SetupCancellation.ts +++ b/src/application/SetupCancellation.ts @@ -1,4 +1,4 @@ -import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; +import { cancelledBy } from "../domain/analysisErrorCore.js"; /** Preserve the caller's exact reason while setup unwinds its resource owners. */ export const assertSetupActive = ( @@ -6,10 +6,9 @@ export const assertSetupActive = ( failure?: string, ): void => { if (signal?.aborted) - throw new AnalysisCancelledError("setup", { - cause: signal.reason, - ...(failure === undefined - ? {} - : { diagnostics: { setup_failure: failure } }), - }); + throw cancelledBy( + "setup", + signal, + failure === undefined ? {} : { diagnostics: { setup_failure: failure } }, + ); }; diff --git a/src/application/WebModuleTraceService.ts b/src/application/WebModuleTraceService.ts index 090ec95b30..42f4da6674 100644 --- a/src/application/WebModuleTraceService.ts +++ b/src/application/WebModuleTraceService.ts @@ -7,10 +7,10 @@ import { type AnalysisError, } from "../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { createEvidence, type Evidence } from "../domain/evidence.js"; import { jsonObjectSchema } from "../domain/jsonValue.js"; @@ -157,11 +157,7 @@ export class WebModuleTraceService { let resolutionFailure: AnalysisError | undefined; if (literals.length > 0) { if (options?.signal?.aborted) - return incomplete( - new AnalysisCancelledError(OPERATION, { - cause: options.signal.reason, - }), - ); + return incomplete(cancelledBy(OPERATION, options.signal)); const request = { importerUrl, importMap: diff --git a/src/application/WebNetworkCaptureService.ts b/src/application/WebNetworkCaptureService.ts index 3d5d68b50c..1b4745d7ce 100644 --- a/src/application/WebNetworkCaptureService.ts +++ b/src/application/WebNetworkCaptureService.ts @@ -5,9 +5,9 @@ import type { ExecutionOptions } from "./AnalysisProvider.js"; import type { WebNetworkCapturePort } from "./WebNetworkCapturePort.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { createAnalysisProfile } from "../domain/analysisProfile.js"; import { @@ -46,11 +46,7 @@ export class WebNetworkCaptureService { callerPaths?: { readonly capture: string; readonly descriptor?: string }, ): Promise> { if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(OPERATION, options.signal)); const failure = (error: AnalysisError): Result => err(redactExplicitFailure(error, captureSensitiveValues(rawInput))); const parsed = inspectWebNetworkCaptureInputSchema.safeParse(rawInput); diff --git a/src/application/WebScriptExportService.ts b/src/application/WebScriptExportService.ts index e8d8b37e60..8300c12f1d 100644 --- a/src/application/WebScriptExportService.ts +++ b/src/application/WebScriptExportService.ts @@ -12,9 +12,10 @@ import { publishWebScripts } from "../browser/assets/PublishWebScripts.js"; import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js"; import { AnalysisAccessDeniedError, - AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, + cancelledBy, + carriedReason, } from "../domain/analysisErrorCore.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { ConfigurationError } from "../domain/configurationErrors.js"; @@ -87,9 +88,7 @@ export const exportWebScriptsValidated = async ( ): Promise> => { try { if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); const prepared = await prepareCapture( input.capture_path, resources, @@ -98,9 +97,7 @@ export const exportWebScriptsValidated = async ( if (!prepared.ok) return prepared; const { bytes, loaded } = prepared.value; if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); const sha256 = createHash("sha256").update(bytes).digest("hex"); const result = await publishWebScripts(input, loaded, sha256, { resources, @@ -108,8 +105,7 @@ export const exportWebScriptsValidated = async ( }); if (options.signal?.aborted === true) return err( - new AnalysisCancelledError(OPERATION, { - cause: options.signal.reason, + cancelledBy(OPERATION, options.signal, { partialObservation: { kind: "web-script-export", result }, }), ); @@ -190,8 +186,7 @@ const mapExportFailure = ( cause.message, { cause, partialObservation: cause.partialObservation }, ) - : new AnalysisCancelledError(OPERATION, { - cause: cause.cancellation.reason, + : cancelledBy(OPERATION, carriedReason(cause.cancellation.reason), { partialObservation: cause.partialObservation, }); if (cause.cleanup === undefined) return primary; @@ -271,9 +266,10 @@ const readCapture = async ( ? { reason: signal.reason } : regularFileCancellation(cause); if (cancellation !== undefined) { - const primary = new AnalysisCancelledError(OPERATION, { - cause: cancellation.reason, - }); + const primary = cancelledBy( + OPERATION, + carriedReason(cancellation.reason), + ); return err( retry.cleanup === undefined ? primary @@ -304,9 +300,7 @@ const captureReadFailure = ( ): AnalysisError => { const cancellation = regularFileCancellation(failure); if (cancellation !== undefined) - return new AnalysisCancelledError(OPERATION, { - cause: cancellation.reason, - }); + return cancelledBy(OPERATION, carriedReason(cancellation.reason)); const primary = failure instanceof RegularFileCleanupFailure && failure.outcome.kind === "failed" diff --git a/src/application/WebSourceLocationService.ts b/src/application/WebSourceLocationService.ts index 0c20b4cec9..1a751c48c4 100644 --- a/src/application/WebSourceLocationService.ts +++ b/src/application/WebSourceLocationService.ts @@ -11,9 +11,9 @@ import { type AnalysisError, } from "../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { createEvidence, type Evidence } from "../domain/evidence.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -153,9 +153,7 @@ export class WebSourceLocationService { if (!generated.ok) return incomplete(generated.error); const generatedOffset = generated.value; if (options?.signal?.aborted) - return incomplete( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return incomplete(cancelledBy(OPERATION, options.signal)); const traced = await this.decoder.trace( { text: map.text, diff --git a/src/application/XrefsAddressResolution.ts b/src/application/XrefsAddressResolution.ts index ffc3b1aab2..e4ff0c4c1b 100644 --- a/src/application/XrefsAddressResolution.ts +++ b/src/application/XrefsAddressResolution.ts @@ -3,9 +3,9 @@ import { listNamesFact } from "../domain/native/nativeOperationFacts.js"; import { executeFact } from "./AnalysisOperationFacts.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, + cancelledBy, } from "../domain/analysisErrorCore.js"; import { err, ok, type Result } from "../domain/result.js"; import type { AnalysisOperationPort } from "./AnalysisProvider.js"; @@ -47,8 +47,7 @@ export const resolveXrefsName = async ( signal?: AbortSignal, operation: "xrefs" | "find_xrefs_to_name" = "xrefs", ): Promise> => { - if (signal?.aborted) - return err(new AnalysisCancelledError(operation, { cause: signal.reason })); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const inventory = await executeFact( analysis, listNamesFact, @@ -75,8 +74,7 @@ export const resolveXrefsName = async ( ); return inventory; } - if (signal?.aborted) - return err(new AnalysisCancelledError(operation, { cause: signal.reason })); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const addresses = new Set(); for (const [index, row] of inventory.value.fact.entries()) { // An empty address cannot be passed back to xrefs. diff --git a/src/application/analysisView/AnalysisViewService.ts b/src/application/analysisView/AnalysisViewService.ts index acdb51d639..6016797a6e 100644 --- a/src/application/analysisView/AnalysisViewService.ts +++ b/src/application/analysisView/AnalysisViewService.ts @@ -12,9 +12,9 @@ import { resolveEvidenceInput } from "../EvidenceInputResolver.js"; import type { EvidenceWriter } from "../investigation/InvestigationRecordPort.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisCapabilityUnavailableError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import { validateAnalysisViewSubject } from "../../domain/analysisView/analysisViewParent.js"; @@ -173,14 +173,12 @@ const cancelledFileViewResult = ( completedEvidence?: Evidence, ): Result => { if (!signal?.aborted) return result; - const cancellation = new AnalysisCancelledError( + const cancellation = cancelledBy( INSPECT_ANALYSIS_VIEW_OPERATION, - { - cause: signal.reason, - ...(completedEvidence !== undefined - ? { partialObservation: completedEvidence } - : {}), - }, + signal, + completedEvidence !== undefined + ? { partialObservation: completedEvidence } + : {}, ); if (!result.ok) cancellation.retainSecondaryFailure(result.error, { diff --git a/src/application/analysisView/evidenceFileSource.ts b/src/application/analysisView/evidenceFileSource.ts index d4186af946..641fa7b045 100644 --- a/src/application/analysisView/evidenceFileSource.ts +++ b/src/application/analysisView/evidenceFileSource.ts @@ -4,9 +4,9 @@ import { authenticateEvidenceBundleValue } from "../EvidenceBundleFiles.js"; import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, type AnalysisInputIssue, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../../domain/analysisView/analysisViewErrors.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -158,12 +158,10 @@ export const readEvidenceFileSource = async ( const { operation } = site; const resolveSelected = site.resolveSelected ?? ((selected: Evidence) => ok(selected)); - if (signal?.aborted) - return err(new AnalysisCancelledError(operation, { cause: signal.reason })); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const loaded = await readJsonFile(path, signal, resources, operation); if (!loaded.ok) return loaded; - if (signal?.aborted) - return err(new AnalysisCancelledError(operation, { cause: signal.reason })); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const value = loaded.value; if ( typeof value === "object" && diff --git a/src/application/android/AndroidAnalysisService.ts b/src/application/android/AndroidAnalysisService.ts index 64beb3a187..be16a79eab 100644 --- a/src/application/android/AndroidAnalysisService.ts +++ b/src/application/android/AndroidAnalysisService.ts @@ -8,7 +8,7 @@ import { androidRequestSchema, type AndroidOperation, } from "../../domain/android/androidAnalysis.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { Evidence } from "../../domain/evidence.js"; import { createAnalysisExecutionEvidence } from "../../domain/analysisObservation.js"; @@ -29,9 +29,7 @@ export class AndroidAnalysisService { options?: ExecutionOptions, ): Promise> { if (options?.signal?.aborted === true) - return err( - new AnalysisCancelledError(operation, { cause: options.signal.reason }), - ); + return err(cancelledBy(operation, options.signal)); const request = androidRequestSchema.safeParse({ operation, input }); if (!request.success) return err( diff --git a/src/application/apiContract/ApiContractRead.ts b/src/application/apiContract/ApiContractRead.ts index d44cf43193..dc90e4b7a5 100644 --- a/src/application/apiContract/ApiContractRead.ts +++ b/src/application/apiContract/ApiContractRead.ts @@ -13,9 +13,10 @@ import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, - AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; import { @@ -63,9 +64,10 @@ const readFailure = ( cause instanceof ArtifactReaderFailure ) { if (cause.reason === "cancelled") - return new AnalysisCancelledError(operation, { - cause: artifactFileCancellationCause(cause), - }); + return cancelledBy( + operation, + carriedReason(artifactFileCancellationCause(cause)), + ); if (cause.reason === "integrity") return new AnalysisArtifactChangedError( operation, diff --git a/src/application/apiContract/ApiContractTraversal.ts b/src/application/apiContract/ApiContractTraversal.ts index fe984b6ff1..d1bf3c8fcd 100644 --- a/src/application/apiContract/ApiContractTraversal.ts +++ b/src/application/apiContract/ApiContractTraversal.ts @@ -1,6 +1,6 @@ import { setImmediate } from "node:timers/promises"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy, carriedReason } from "../../domain/analysisErrorCore.js"; import { err, type Result } from "../../domain/result.js"; import { API_CONTRACT_OPERATION as operation } from "../../domain/apiContract/apiContract.js"; @@ -9,7 +9,7 @@ const cancelSteps = ( steps: Generator>, reason: unknown, ): Result => { - const cancellation = new AnalysisCancelledError(operation, { cause: reason }); + const cancellation = cancelledBy(operation, carriedReason(reason)); try { const stopped = steps.throw(cancellation); if (stopped.done && !stopped.value.ok) return stopped.value; diff --git a/src/application/binary/AnalysisProviderEvaluation.ts b/src/application/binary/AnalysisProviderEvaluation.ts index ec150e5e59..b6c0e789a5 100644 --- a/src/application/binary/AnalysisProviderEvaluation.ts +++ b/src/application/binary/AnalysisProviderEvaluation.ts @@ -6,6 +6,8 @@ import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; import { AnalysisCancelledError, AnalysisUnsupportedTargetError, + isAborted, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { jsonObjectSchema, type JsonValue } from "../../domain/jsonValue.js"; @@ -47,10 +49,7 @@ export const evaluateAnalysisProviderCandidate = async ( Result > => { const { signal } = options; - if (signalIsAborted(signal)) - return err( - new AnalysisCancelledError("open_binary", { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("open_binary", signal)); let resolved: Awaited>; try { resolved = await candidate.resolveAnalysisProfile(target, options); @@ -97,10 +96,7 @@ export const evaluateAnalysisProviderCandidate = async ( ); return ok({ ...rejection, profileError: error }); } - if (signalIsAborted(signal)) - return err( - new AnalysisCancelledError("open_binary", { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("open_binary", signal)); try { if (resolved.value.profile === null) return ok( @@ -164,9 +160,6 @@ export const evaluateAnalysisProviderCandidate = async ( } }; -const signalIsAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; - /** Name doctor only for a provider whose installation it can check. */ const profileRemediation = (candidate: AnalysisProviderCandidate): string => { const providerId = candidate.identity().id; diff --git a/src/application/binary/AnalysisProviderRegistry.ts b/src/application/binary/AnalysisProviderRegistry.ts index 6c980d6642..dccb4f16df 100644 --- a/src/application/binary/AnalysisProviderRegistry.ts +++ b/src/application/binary/AnalysisProviderRegistry.ts @@ -18,6 +18,9 @@ import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; import { AnalysisCancelledError, AnalysisUnsupportedTargetError, + isAborted, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { @@ -325,9 +328,7 @@ export class AnalysisProviderRegistry { options: { readonly signal?: AbortSignal } = {}, ): Promise { if (options.signal?.aborted) - throw new AnalysisCancelledError("binary_session", { - cause: options.signal.reason, - }); + throw cancelledBy("binary_session", options.signal); if (this.#closing !== undefined) return this.#providers.map((provider) => ({ provider: structuredClone(provider.identity()), @@ -380,8 +381,7 @@ export class AnalysisProviderRegistry { const result = await discovery.promise; if (!result.ok) throw result.error; if (discovery.signal.aborted) - throw new AnalysisCancelledError("binary_session", { - cause: discovery.signal.reason, + throw cancelledBy("binary_session", discovery.signal, { diagnostics: { readiness_candidates: jsonValueSchema.parse(result.value), }, @@ -405,10 +405,7 @@ export class AnalysisProviderRegistry { Result > { const { signal, operation } = context; - if (signal.aborted) - return err( - new AnalysisCancelledError(operation, { cause: signal.reason }), - ); + if (signal.aborted) return err(cancelledBy(operation, signal)); const results = await Promise.allSettled( this.#providers.map((provider) => candidateStatus(provider, target, context), @@ -453,12 +450,8 @@ export class AnalysisProviderRegistry { requestedSelector?: AnalysisProviderSelector, options: { readonly signal?: AbortSignal } = {}, ): Promise { - if (signalIsAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + if (isAborted(options.signal)) + return err(cancelledBy("open_binary", options.signal)); if (this.#closing !== undefined) { const closed = await this.#closing; if (!closed.ok) return closed; @@ -479,12 +472,8 @@ export class AnalysisProviderRegistry { const closed = await this.closeOwnedResources(); if (!closed.ok) return closed; } - if (signalIsAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + if (isAborted(options.signal)) + return err(cancelledBy("open_binary", options.signal)); const selection = new SharedStartupAttempt( (signal) => Promise.resolve().then(() => @@ -507,17 +496,9 @@ export class AnalysisProviderRegistry { if (waited.status !== "cancelled") { if (!waited.value.ok) return waited.value; if (!selection.signal.aborted) return waited.value; - return err( - new AnalysisCancelledError("open_binary", { - cause: selection.signal.reason, - }), - ); + return err(cancelledBy("open_binary", selection.signal)); } - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", carriedReason(waited.reason))); } async #selectTarget( @@ -527,10 +508,7 @@ export class AnalysisProviderRegistry { ): Promise { const scope = new ProviderInspectionScope(); try { - if (signalIsAborted(signal)) - return err( - new AnalysisCancelledError("open_binary", { cause: signal.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("open_binary", signal)); const discovery = await this.#discoverCandidates(target, { signal, scope, @@ -555,10 +533,7 @@ export class AnalysisProviderRegistry { ); const request = parsedRequest?.data; const selector = request ?? this.#defaultSelector; - if (signalIsAborted(signal)) - return err( - new AnalysisCancelledError("open_binary", { cause: signal.reason }), - ); + if (isAborted(signal)) return err(cancelledBy("open_binary", signal)); if (selector === "auto" && this.canInspectWithoutDeepProvider?.(target)) return ok({ requestedProviderId: selector, @@ -737,7 +712,7 @@ export class AnalysisProviderRegistry { if ( results.some((result) => !result.ok) || failures.some(({ error }) => error.cleanupIncomplete) || - signalIsAborted(signal) + isAborted(signal) ) return err( providerInspectionFailure( @@ -791,8 +766,7 @@ const candidateStatus = async ( }, ): Promise => { const { signal, scope, resourceScope, operation } = context; - if (signal.aborted) - throw new AnalysisCancelledError(operation, { cause: signal.reason }); + if (signal.aborted) throw cancelledBy(operation, signal); let readiness: AnalysisProviderReadinessSnapshot; try { readiness = @@ -861,9 +835,6 @@ const projectCandidateStatus = async ( }); }; -const signalIsAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; - const selectedResult = ( requestedProviderId: string, source: AnalysisProviderSelectionSource, @@ -983,12 +954,13 @@ const providerInspectionFailure = ( const primary = failures.find(({ error }) => !(error instanceof AnalysisCancelledError)) ?? failures[0]; + // No child failed, so only the caller's abort ended inspection. if (primary === undefined) - return new AnalysisCancelledError( + return cancelledBy( context.operation === "resolve_analysis_profile" ? "open_binary" : context.operation, - { cause: signal?.reason }, + carriedReason(signal?.reason), ); if ( failures.length === 1 && @@ -1033,14 +1005,12 @@ const providerInspectionFailure = ( }; const failure = primary.error instanceof AnalysisCancelledError - ? new AnalysisCancelledError( + ? cancelledBy( context.operation === "resolve_analysis_profile" ? "open_binary" : context.operation, - { - ...options, - cause: primary.error.cause, - }, + carriedReason(primary.error.cause), + { ...options }, ) : new ProviderAdapterError("rea", context.operation, { ...options, diff --git a/src/application/binary/AnalysisSnapshotFiles.ts b/src/application/binary/AnalysisSnapshotFiles.ts index 4beb0b4685..72d674630e 100644 --- a/src/application/binary/AnalysisSnapshotFiles.ts +++ b/src/application/binary/AnalysisSnapshotFiles.ts @@ -15,7 +15,10 @@ import { import { err, ok, type Result } from "../../domain/result.js"; import { describeValidationFailure } from "../../domain/validationFailure.js"; import type { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../../domain/analysisErrorCore.js"; import { readJsonObjectMembersFile, writeTextFile } from "../JsonFiles.js"; import type { JsonObjectMemberReader } from "../JsonInputFile.js"; import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; @@ -81,9 +84,7 @@ export const readAnalysisSnapshot = async ( return ok(snapshot); } catch (cause: unknown) { if (signal?.aborted === true) - return err( - new AnalysisCancelledError(READ_OPERATION, { cause: signal.reason }), - ); + return err(cancelledBy(READ_OPERATION, signal)); return err( new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }), ); diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts index 8d8c951cc2..f04a9d0913 100644 --- a/src/application/binary/BinarySession.ts +++ b/src/application/binary/BinarySession.ts @@ -21,6 +21,8 @@ import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + isAborted, + cancelledBy, OwnerCancellation, } from "../../domain/analysisErrorCore.js"; import { @@ -150,10 +152,7 @@ const trackCleanupFailures = ( return; observed.add(failure); if (cleanupFailure === undefined) { - if (isAborted(signal)) - cancellation = new AnalysisCancelledError(operation, { - cause: signal?.reason, - }); + if (isAborted(signal)) cancellation = cancelledBy(operation, signal); cleanupFailure = failure; } else { // Both operands are cleanup observations here. An earlier rejection @@ -238,11 +237,7 @@ export class BinarySession if (refused !== undefined) return refused; await this.#drainCalls(admittedThrough); if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_bundle_resources", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_bundle_resources", options.signal)); if (this.#externalMutationCleanupFailure?.cleanupIncomplete === true) return err(this.#externalMutationCleanupFailure); if (this.#bundleResourceFactory === undefined) @@ -256,22 +251,14 @@ export class BinarySession const resolved = await resolveAppBundleResourceRoot(path); if (!resolved.ok) return resolved; if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_bundle_resources", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_bundle_resources", options.signal)); const pendingClosed = await this.#retryPendingCleanup(); if (!pendingClosed.ok) return pendingClosed; const pendingResourcesClosed = await this.#retryPendingBundleResourceCleanup(); if (!pendingResourcesClosed.ok) return pendingResourcesClosed; if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_bundle_resources", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_bundle_resources", options.signal)); const runId = randomUUID(); let bundleClient: Awaited< ReturnType @@ -312,9 +299,7 @@ export class BinarySession ); } if (isAborted(options.signal)) { - const cancelled = new AnalysisCancelledError("open_bundle_resources", { - cause: options.signal?.reason, - }); + const cancelled = cancelledBy("open_bundle_resources", options.signal); this.#pendingBundleResourceCleanup.push(candidate); const closed = await this.#retryPendingBundleResourceCleanup(); return err( @@ -351,9 +336,7 @@ export class BinarySession ); } if (isAborted(options.signal)) { - const cancelled = new AnalysisCancelledError("open_bundle_resources", { - cause: options.signal?.reason, - }); + const cancelled = cancelledBy("open_bundle_resources", options.signal); this.#pendingBundleResourceCleanup.push(candidate); const candidateClosed = await this.#retryPendingBundleResourceCleanup( undefined, @@ -391,11 +374,7 @@ export class BinarySession ): Promise | undefined> { const live = await this.#retainedClientLive(retained.client, options); if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); if (!live) return undefined; if (options.snapshot !== undefined) { const imported = this.importAnalysisSnapshot(options.snapshot); @@ -462,13 +441,7 @@ export class BinarySession options: BinarySessionOpenOptions = {}, ): Promise> { if (isAborted(options.signal)) - return Promise.resolve( - err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ), - ); + return Promise.resolve(err(cancelledBy("open_binary", options.signal))); return resolveSessionTarget({ router: this.#providerRouter, current: this.#active, @@ -478,11 +451,7 @@ export class BinarySession this.snapshotMismatch(target, profile), }).then((resolved) => resolved.ok && isAborted(options.signal) - ? err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ) + ? err(cancelledBy("open_binary", options.signal)) : resolved, ); } @@ -590,11 +559,7 @@ export class BinarySession ): Promise> { if (options.loadSnapshot === undefined) return ok(options); if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); const loaded = await options.loadSnapshot(); if (!loaded.ok) return loaded; const { loadSnapshot: _loaded, ...rest } = options; @@ -609,22 +574,14 @@ export class BinarySession if (this.#externalMutationCleanupFailure?.cleanupIncomplete === true) return err(this.#externalMutationCleanupFailure); if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); const resolved = await resolve(); if (!resolved.ok) return resolved; const { target, sameTarget } = resolved.value; let { route } = resolved.value; let { profile } = route; if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); const activeProfile = this.#active?.profile; const sameProfile = activeProfile === null || activeProfile === undefined @@ -632,22 +589,14 @@ export class BinarySession : profile !== null && analysisProfilesEqual(activeProfile, profile); await this.#drainCalls(admittedThrough); if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); const pendingClosed = await this.#retryPendingCleanup(); if (!pendingClosed.ok) return pendingClosed; const pendingResourcesClosed = await this.#retryPendingBundleResourceCleanup(); if (!pendingResourcesClosed.ok) return pendingResourcesClosed; if (isAborted(options.signal)) - return err( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), - ); + return err(cancelledBy("open_binary", options.signal)); const retained = sameTarget && sameProfile ? this.#active : undefined; if (retained !== undefined) { const fastPath = await this.#tryRetainedFastPath( @@ -669,9 +618,7 @@ export class BinarySession if (isAborted(options.signal)) return err( analysisErrorWithCleanupFailure( - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), + cancelledBy("open_binary", options.signal), closed.error, "open_binary", ).bindCleanupDependencies([closed.error]), @@ -683,9 +630,7 @@ export class BinarySession return err( await this.#restoreAfterFailedOpen( previous, - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), + cancelledBy("open_binary", options.signal), ), ); if (previous !== undefined) { @@ -741,9 +686,7 @@ export class BinarySession await this.#failedOpen( run, previous, - new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }), + cancelledBy("open_binary", options.signal), ), ); } @@ -767,9 +710,7 @@ export class BinarySession } } if (isAborted(options.signal)) { - const cancelled = new AnalysisCancelledError("open_binary", { - cause: options.signal?.reason, - }); + const cancelled = cancelledBy("open_binary", options.signal); const failed = await this.#failedOpen( run, previous, @@ -822,7 +763,10 @@ export class BinarySession if (this.#shutdownStarted) return Promise.resolve( err( - new AnalysisCancelledError(operationName, { cause: signal?.reason }), + cancelledBy( + operationName, + isAborted(signal) ? signal : OwnerCancellation.ownerClosed, + ), ), ); return this.#serialize(async (admittedThrough) => { @@ -834,15 +778,9 @@ export class BinarySession "External mutation requires an active executable analysis target.", ), ); - if (isAborted(signal)) - return err( - new AnalysisCancelledError(operationName, { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy(operationName, signal)); await this.#drainCalls(admittedThrough); - if (isAborted(signal)) - return err( - new AnalysisCancelledError(operationName, { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy(operationName, signal)); if (this.#externalMutationCleanupFailure?.cleanupIncomplete === true) { if (cleanupRecovery === undefined) @@ -855,9 +793,7 @@ export class BinarySession isAborted(signal) ? analysisErrorWithCancellation( recovered.error, - new AnalysisCancelledError(operationName, { - cause: signal?.reason, - }), + cancelledBy(operationName, signal), ) : recovered.error, ); @@ -866,9 +802,7 @@ export class BinarySession isAborted(signal) ? analysisErrorWithCancellation( this.#externalMutationCleanupFailure, - new AnalysisCancelledError(operationName, { - cause: signal?.reason, - }), + cancelledBy(operationName, signal), ) : this.#externalMutationCleanupFailure, ); @@ -881,16 +815,11 @@ export class BinarySession isAborted(signal) ? analysisErrorWithCancellation( pendingCleanup.error, - new AnalysisCancelledError(operationName, { - cause: signal?.reason, - }), + cancelledBy(operationName, signal), ) : pendingCleanup.error, ); - if (isAborted(signal)) - return err( - new AnalysisCancelledError(operationName, { cause: signal?.reason }), - ); + if (isAborted(signal)) return err(cancelledBy(operationName, signal)); const activeAtDispatch = this.#active; if (activeAtDispatch?.route.binding?.identity.id === "ghidra") @@ -924,9 +853,7 @@ export class BinarySession isAborted(signal) ? analysisErrorWithCancellation( failure, - new AnalysisCancelledError(operationName, { - cause: signal?.reason, - }), + cancelledBy(operationName, signal), ) : failure, ); @@ -934,12 +861,7 @@ export class BinarySession } if (isAborted(signal)) return err( - completionFailure( - value, - new AnalysisCancelledError(operationName, { - cause: signal?.reason, - }), - ), + completionFailure(value, cancelledBy(operationName, signal)), ); return ok(value); }); @@ -960,7 +882,10 @@ export class BinarySession ): Result | undefined { if (!this.#shutdownStarted) return undefined; return err( - new AnalysisCancelledError(operation, { cause: signal?.reason }), + cancelledBy( + operation, + isAborted(signal) ? signal : OwnerCancellation.ownerClosed, + ), ); } @@ -1043,18 +968,18 @@ export class BinarySession if (this.#shutdownStarted) return Promise.resolve( err( - new AnalysisCancelledError("reset_investigation", { - cause: options.signal?.reason, - }), + cancelledBy( + "reset_investigation", + isAborted(options.signal) + ? options.signal + : OwnerCancellation.ownerClosed, + ), ), ); return this.#serialize(async (admittedThrough) => { await this.#drainCalls(admittedThrough); - const cancelled = () => - new AnalysisCancelledError("reset_investigation", { - cause: options.signal?.reason, - }); - if (isAborted(options.signal)) return err(cancelled()); + if (isAborted(options.signal)) + return err(cancelledBy("reset_investigation", options.signal)); const adapterResources = await options.retryCleanup?.(); if (adapterResources !== undefined && !adapterResources.ok) return adapterResources; @@ -1070,7 +995,8 @@ export class BinarySession const candidates = await this.#providerRouter.closeOwnedResources(); if (!candidates.ok) return candidates; } - if (isAborted(options.signal)) return err(cancelled()); + if (isAborted(options.signal)) + return err(cancelledBy("reset_investigation", options.signal)); const statistics = this.investigationStatistics(); let saved: ResetInvestigationReceipt["saved_bundle"]; if (options.savePath !== undefined) { @@ -1090,12 +1016,11 @@ export class BinarySession // the investigation if cancellation arrived during publication/cleanup. if (isAborted(options.signal)) return err( - new AnalysisCancelledError("reset_investigation", { - cause: options.signal?.reason, - ...(saved === undefined - ? {} - : { diagnostics: { saved_bundle: saved } }), - }), + cancelledBy( + "reset_investigation", + options.signal, + saved === undefined ? {} : { diagnostics: { saved_bundle: saved } }, + ), ); this.clearInvestigationRecords(); return ok({ @@ -1450,7 +1375,12 @@ export class BinarySession if (this.#shutdownStarted) return Promise.resolve( err( - new AnalysisCancelledError(name, { cause: options?.signal?.reason }), + cancelledBy( + name, + isAborted(options?.signal) + ? options.signal + : OwnerCancellation.ownerClosed, + ), ), ); const generation = this.#transitionGeneration; @@ -1507,7 +1437,10 @@ export class BinarySession if (this.#shutdownStarted) return Promise.resolve( err( - new AnalysisCancelledError(operationName, { cause: signal?.reason }), + cancelledBy( + operationName, + isAborted(signal) ? signal : OwnerCancellation.ownerClosed, + ), ), ); const generation = this.#transitionGeneration; @@ -1846,37 +1779,23 @@ export class BinarySession signal: AbortSignal | undefined, transition: Promise, ): Promise> { - if (signal?.aborted === true) - return err( - new AnalysisCancelledError(operation, { cause: signal.reason }), - ); + if (signal?.aborted === true) return err(cancelledBy(operation, signal)); if (signal === undefined) { await transition; return ok(undefined); } return new Promise((resolve) => { const onAbort = (): void => { - resolve( - err(new AnalysisCancelledError(operation, { cause: signal.reason })), - ); + resolve(err(cancelledBy(operation, signal))); }; signal.addEventListener("abort", onAbort, { once: true }); const finish = (): void => { signal.removeEventListener("abort", onAbort); resolve( - signal.aborted - ? err( - new AnalysisCancelledError(operation, { - cause: signal.reason, - }), - ) - : ok(undefined), + signal.aborted ? err(cancelledBy(operation, signal)) : ok(undefined), ); }; transition.then(finish, finish); }); } } - -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; diff --git a/src/application/binary/BinarySessionInvestigation.test.ts b/src/application/binary/BinarySessionInvestigation.test.ts index 7c81592fe8..a3a2916651 100644 --- a/src/application/binary/BinarySessionInvestigation.test.ts +++ b/src/application/binary/BinarySessionInvestigation.test.ts @@ -2,6 +2,7 @@ import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { expect, it, vi } from "vitest"; +import { OwnerCancellation } from "../../domain/analysisErrorCore.js"; import { createEvidence } from "../../domain/evidence.js"; import { createEvidenceBundle, @@ -644,7 +645,9 @@ it.each( const result = await late; if (result.ok) throw new Error("Expected shutdown admission refusal"); expect(result.error._tag).toBe("AnalysisCancelledError"); - expect(result.error.cause).toBe(aborted ? reason : undefined); + expect(result.error.cause).toBe( + aborted ? reason : OwnerCancellation.ownerClosed, + ); expect(mutation).not.toHaveBeenCalled(); expect(await earlier).toMatchObject({ ok: true, value: { ok: true } }); expect(calls.filter((name) => name === "address_name")).toHaveLength(1); diff --git a/src/application/binary/LazyAnalysisProvider.ts b/src/application/binary/LazyAnalysisProvider.ts index 25165bf813..bdc9527eda 100644 --- a/src/application/binary/LazyAnalysisProvider.ts +++ b/src/application/binary/LazyAnalysisProvider.ts @@ -1,6 +1,6 @@ import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js"; import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { DeferredAnalysisClient } from "../../providers/DeferredAnalysisClient.js"; import type { AnalysisClient, @@ -50,10 +50,7 @@ export class LazyAnalysisProvider implements AnalysisProvider { ): AnalysisClient { return new DeferredAnalysisClient(async (signal) => { const provider = await this.#load(); - if (signal.aborted) - throw new AnalysisCancelledError("create_analysis_client", { - cause: signal.reason, - }); + if (signal.aborted) throw cancelledBy("create_analysis_client", signal); return provider.createClient(target, profile, context); }, this.#providerIdentity.id); } diff --git a/src/application/binaryDiagnostics/ByteEntropyService.ts b/src/application/binaryDiagnostics/ByteEntropyService.ts index 55e0fe1c99..4db145c6c8 100644 --- a/src/application/binaryDiagnostics/ByteEntropyService.ts +++ b/src/application/binaryDiagnostics/ByteEntropyService.ts @@ -9,9 +9,10 @@ import { AnalysisOutputError, AnalysisAccessDeniedError, AnalysisArtifactChangedError, - AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { createEvidence, @@ -349,20 +350,24 @@ export class ByteEntropyService { outcome.cause instanceof ArtifactReaderFailure && outcome.cause.reason === "cancelled" ) { - const cancelled = new AnalysisCancelledError(OPERATION, { - cause: artifactFileCancellationCause(outcome.cause), - cleanup: cause.cleanup, - }).retainSecondaryFailure(cleanup); + const cancelled = cancelledBy( + OPERATION, + carriedReason(artifactFileCancellationCause(outcome.cause)), + { cleanup: cause.cleanup }, + ).retainSecondaryFailure(cleanup); bindArtifactFileCleanup(cause, cancelled); return err(cancelled); } const cancellation = completion?.cancellation; if (cancellation !== undefined) { - const cancelled = new AnalysisCancelledError(OPERATION, { - cause: cancellation.reason, - partialObservation: cleanup.partialObservation, - cleanup: cause.cleanup, - }).retainSecondaryFailure(cleanup); + const cancelled = cancelledBy( + OPERATION, + carriedReason(cancellation.reason), + { + partialObservation: cleanup.partialObservation, + cleanup: cause.cleanup, + }, + ).retainSecondaryFailure(cleanup); bindArtifactFileCleanup(cause, cancelled); return err(cancelled); } @@ -380,12 +385,15 @@ export class ByteEntropyService { } if (cause instanceof ArtifactReaderFailure) { if (cause.reason === "cancelled") { - const cancelled = new AnalysisCancelledError(OPERATION, { - cause: artifactFileCancellationCause(cause), - ...(completion === undefined + const cancelled = cancelledBy( + OPERATION, + carriedReason(artifactFileCancellationCause(cause)), + completion === undefined ? {} - : { partialObservation: completedObservation(completion.value) }), - }); + : { + partialObservation: completedObservation(completion.value), + }, + ); bindArtifactFileCleanup(cause, cancelled); return err(cancelled); } diff --git a/src/application/decompileDirectory/decompileAll.ts b/src/application/decompileDirectory/decompileAll.ts index 1d789f3f55..cd83fe3df5 100644 --- a/src/application/decompileDirectory/decompileAll.ts +++ b/src/application/decompileDirectory/decompileAll.ts @@ -25,6 +25,8 @@ import { AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, + isAborted, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; @@ -120,10 +122,10 @@ export const decompileAll = async ( input.resume, ); if (!placement.ok) return placement; - if (isAborted(signal)) return err(cancelled(signal)); + if (isAborted(signal)) return err(cancelledBy("decompile_all", signal)); const loaded = await loadProcedures(analysis, input.layout, signal); if (!loaded.ok) return loaded; - if (isAborted(signal)) return err(cancelled(signal)); + if (isAborted(signal)) return err(cancelledBy("decompile_all", signal)); const selection = selectProcedures( loaded.value.procedures, input, @@ -226,7 +228,7 @@ export const decompileAll = async ( primary.cause === signal?.reason ) ) - primary.retainSecondaryFailure(cancelled(signal)); + primary.retainSecondaryFailure(cancelledBy("decompile_all", signal)); for (const failure of failures.slice(1)) primary.retainSecondaryFailure(failure); if ( @@ -248,7 +250,7 @@ export const decompileAll = async ( // resume, but a caller abort that stopped the loop or arrived meanwhile is // not a success. Report it with the caller's own reason. if (isAborted(signal)) { - const failure = cancelled(signal); + const failure = cancelledBy("decompile_all", signal); if (publishedOutput !== undefined) failure.retainPrimaryDiagnostics({ published_output: publishedOutput }); return err(failure); @@ -393,14 +395,16 @@ const publishSelected = async ( ): Promise> => { let bodySupport: "unknown" | "unavailable" = "unknown"; for (const procedure of input.procedures) { - if (isAborted(input.signal)) return err(cancelled(input.signal)); + if (isAborted(input.signal)) + return err(cancelledBy("decompile_all", input.signal)); const existing = await existingFile( input.session, procedure.address, input.signal, ); if (typeof existing === "object") return err(existing.error); - if (isAborted(input.signal)) return err(cancelled(input.signal)); + if (isAborted(input.signal)) + return err(cancelledBy("decompile_all", input.signal)); if (existing === "skip") { input.state.skipped += 1; // A file that reads back and verifies shows the directory works. @@ -573,7 +577,7 @@ const publishOne = async (input: { if (!recorded.ok) return { result: recorded, bodySupport: body.support }; if (isAborted(input.signal)) return { - result: err(cancelled(input.signal)), + result: err(cancelledBy("decompile_all", input.signal)), bodySupport: body.support, }; attemptedIndependent = true; @@ -666,7 +670,10 @@ const publishOne = async (input: { // Classify and journal settled failures before a later caller abort. A valid // result still needs an active caller before publishing a new function file. if (isAborted(input.signal)) - return { result: err(cancelled(input.signal)), bodySupport: body.support }; + return { + result: err(cancelledBy("decompile_all", input.signal)), + bodySupport: body.support, + }; const relativePath = input.session.pathFor(input.procedure.address); const bytes = Buffer.from( functionFileText({ @@ -1162,12 +1169,6 @@ const executionOptions = (signal: AbortSignal | undefined) => ({ selectorOrigin: "provider" as const, }); -const cancelled = (signal: AbortSignal | undefined): AnalysisCancelledError => - new AnalysisCancelledError("decompile_all", { cause: signal?.reason }); - -const isAborted = (signal: AbortSignal | undefined): boolean => - signal?.aborted === true; - const nodeAbsent = (cause: unknown): boolean => typeof cause === "object" && cause !== null && diff --git a/src/application/desktop/DesktopApplicationCapture.ts b/src/application/desktop/DesktopApplicationCapture.ts index 2d80e6bc8d..069e797a67 100644 --- a/src/application/desktop/DesktopApplicationCapture.ts +++ b/src/application/desktop/DesktopApplicationCapture.ts @@ -3,7 +3,7 @@ import { samplingInspectionFailures } from "../../process/capture/ProcessSamplin import type { DesktopLibraryPolicyInput } from "../../domain/desktop/libraryPolicy.js"; import { arch, hostname, userInfo } from "node:os"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { bindProcessInspectionCancellations, retainProcessInspectionCleanup, @@ -230,10 +230,7 @@ const admit = async ( request.desktopEntry === undefined ? "executable" : "desktop_entry", running.windows, ); - if (signal?.aborted === true) - throw new AnalysisCancelledError(DESKTOP_OPERATION, { - cause: signal.reason, - }); + if (signal?.aborted === true) throw cancelledBy(DESKTOP_OPERATION, signal); const prepared = await prepareOutputDirectory(request.output); if ("refusal" in prepared) throw outputRefusal(request.output, prepared.refusal); @@ -423,8 +420,7 @@ const runCapture = async ( if (cleanup !== undefined) throw cleanup; // A cancellation that arrives during publication must not read as success. if (signal?.aborted === true && session.end_reason !== "cancelled") - throw new AnalysisCancelledError(DESKTOP_OPERATION, { - cause: signal.reason, + throw cancelledBy(DESKTOP_OPERATION, signal, { partialObservation: evidence, }); return evidence; diff --git a/src/application/desktop/DesktopApplicationState.ts b/src/application/desktop/DesktopApplicationState.ts index 2c514d5c1e..fa7c00abb0 100644 --- a/src/application/desktop/DesktopApplicationState.ts +++ b/src/application/desktop/DesktopApplicationState.ts @@ -10,8 +10,10 @@ import { join } from "node:path"; import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, + carriedReason, + isAborted, } from "../../domain/analysisErrorCore.js"; import { analysisErrorWithCancellation } from "../../domain/analysisErrorCancellation.js"; import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; @@ -146,12 +148,14 @@ export const readDesktopCapture = async ( OPERATION, "Desktop capture input", ); - if (outcome.ok && !signal?.aborted) + if (outcome.ok && !isAborted(signal)) throw cleanup.retainPartialObservation(outcome.value.evidence); const primary = outcome.ok - ? new AnalysisCancelledError(OPERATION, { - cause: signal?.reason, - }).retainPartialObservation(outcome.value.evidence) + ? cancelledBy( + OPERATION, + // A completed outcome reaches here only after the caller aborted. + carriedReason(signal?.reason), + ).retainPartialObservation(outcome.value.evidence) : desktopOperationFailure( outcome.error, undefined, @@ -159,10 +163,7 @@ export const readDesktopCapture = async ( "Desktop capture input", ); if (!outcome.ok && signal?.aborted) - analysisErrorWithCancellation( - primary, - new AnalysisCancelledError(OPERATION, { cause: signal.reason }), - ); + analysisErrorWithCancellation(primary, cancelledBy(OPERATION, signal)); throw analysisErrorWithCleanupFailure( primary, cleanup, @@ -178,13 +179,13 @@ export const readDesktopCapture = async ( OPERATION, "Desktop capture input", ), - new AnalysisCancelledError(OPERATION, { cause: signal.reason }), + cancelledBy(OPERATION, signal), ); } if (signal?.aborted) - throw new AnalysisCancelledError(OPERATION, { - cause: signal.reason, - }).retainPartialObservation(outcome.value.evidence); + throw cancelledBy(OPERATION, signal).retainPartialObservation( + outcome.value.evidence, + ); return outcome.value; }; @@ -402,9 +403,7 @@ const readVersion = async ( context: ViewContext, ): Promise => { if (context.signal?.aborted === true) - throw new AnalysisCancelledError(OPERATION, { - cause: context.signal.reason, - }); + throw cancelledBy(OPERATION, context.signal); if (!version.present) return; if (version.sha256 === null) { version.view_error = "content not retained"; @@ -555,8 +554,7 @@ const inspectState = async ( paths, limitations, }; - if (signal?.aborted === true) - throw new AnalysisCancelledError(OPERATION, { cause: signal.reason }); + if (signal?.aborted === true) throw cancelledBy(OPERATION, signal); return createEvidence(undefined, DESKTOP_PROVIDER, { predicateType: "rea.desktop-application-state", operation: OPERATION, diff --git a/src/application/desktop/DesktopBuildCapture.ts b/src/application/desktop/DesktopBuildCapture.ts index 668511c6ad..e3faec2309 100644 --- a/src/application/desktop/DesktopBuildCapture.ts +++ b/src/application/desktop/DesktopBuildCapture.ts @@ -2,7 +2,7 @@ import type { DownloadInstall } from "../../domain/desktop/appDownloadInstall.js import { z } from "zod"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import type { BuildRequest } from "../../domain/desktop/appBuild.js"; import { SIGN_IN_END, @@ -214,8 +214,7 @@ const checkExportRuntime = async ( ); return ok(undefined); } catch (cause: unknown) { - if (signal.aborted) - return err(new AnalysisCancelledError(START, { cause: signal.reason })); + if (signal.aborted) return err(cancelledBy(START, signal)); const message = errorText(cause); const redacted = computer.redacted(message); return err( @@ -679,7 +678,7 @@ export class DesktopBuildCapture { cause instanceof AnalysisError ? cause : signal.aborted - ? new AnalysisCancelledError(EXPORT, { cause: signal.reason }) + ? cancelledBy(EXPORT, signal) : adapterError(EXPORT, errorText(cause), cause), ); } diff --git a/src/application/desktop/DesktopBuildCaptureFailure.ts b/src/application/desktop/DesktopBuildCaptureFailure.ts index e9fe9f0d10..640200d620 100644 --- a/src/application/desktop/DesktopBuildCaptureFailure.ts +++ b/src/application/desktop/DesktopBuildCaptureFailure.ts @@ -1,5 +1,5 @@ import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { desktopApplicationCaptureSchema, desktopCaptureProgressSchema, @@ -178,10 +178,7 @@ export const endedCapture = async ( ); } catch (cause: unknown) { if (cause instanceof AnalysisError) return cause; - if (signal.aborted) - return new AnalysisCancelledError(step.operation, { - cause: signal.reason, - }); + if (signal.aborted) return cancelledBy(step.operation, signal); return notAnswered(step.operation, answer, redact); } }; diff --git a/src/application/desktop/DesktopBuildComputers.ts b/src/application/desktop/DesktopBuildComputers.ts index 019ef6322c..4fa33da7a6 100644 --- a/src/application/desktop/DesktopBuildComputers.ts +++ b/src/application/desktop/DesktopBuildComputers.ts @@ -17,8 +17,8 @@ import { type AnalysisCapturedOutput, } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; @@ -146,8 +146,7 @@ const failure = ( signal: AbortSignal, ): AnalysisError => { if (cause instanceof AnalysisError) return cause; - if (signal.aborted) - return new AnalysisCancelledError(operation, { cause: signal.reason }); + if (signal.aborted) return cancelledBy(operation, signal); return new ProviderAdapterError(AGENTENV_PROVIDER, operation, { userMessage: cause instanceof Error ? cause.message : String(cause), cause, @@ -369,7 +368,6 @@ const startFailure = ( ): AnalysisError => { if (cause instanceof AnalysisError && kept.release.verified) return cause; const options = { - cause, ...(output === undefined ? {} : { capturedOutput: output }), ...(kept.release.verified ? {} @@ -382,11 +380,7 @@ const startFailure = ( remediationAction: `REA keeps this computer's teardown as ${kept.id}; once the reported problem is fixed, call close_build_computer with that computer_id.`, }), }; - if (signal.aborted) - return new AnalysisCancelledError(START, { - ...options, - cause: signal.reason, - }); + if (signal.aborted) return cancelledBy(START, signal, options); return new ProviderAdapterError(AGENTENV_PROVIDER, START, { ...(cause instanceof ComputerStartFailure && cause.remediation !== undefined && @@ -395,6 +389,7 @@ const startFailure = ( : {}), userMessage: cause instanceof Error ? cause.message : String(cause), ...options, + cause, }); }; diff --git a/src/application/desktop/DesktopBuildExport.ts b/src/application/desktop/DesktopBuildExport.ts index 78f025a10c..99f28cfe3b 100644 --- a/src/application/desktop/DesktopBuildExport.ts +++ b/src/application/desktop/DesktopBuildExport.ts @@ -9,7 +9,7 @@ import { } from "../../domain/desktop/appTaskReaders.js"; import { BuildComputerLongRuns } from "../../desktop/BuildComputerLongRuns.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy, carriedReason } from "../../domain/analysisErrorCore.js"; import type { desktopTaskSchema } from "../../domain/desktop/appTask.js"; import { counted } from "../../domain/desktop/appExportUnowned.js"; import { END_CHECKPOINT } from "../../domain/desktop/buildCapture.js"; @@ -475,7 +475,7 @@ export const exportBuild = async ( cause instanceof AnalysisError ? cause : signal.aborted && cause === signal.reason - ? new AnalysisCancelledError(EXPORT, { cause }) + ? cancelledBy(EXPORT, carriedReason(cause)) : adapterError( EXPORT, redactSecrets(errorText(cause), capture.secrets), diff --git a/src/application/desktop/DesktopBuildOwnedWork.ts b/src/application/desktop/DesktopBuildOwnedWork.ts index f3cffe51df..edb1b74d05 100644 --- a/src/application/desktop/DesktopBuildOwnedWork.ts +++ b/src/application/desktop/DesktopBuildOwnedWork.ts @@ -1,6 +1,9 @@ import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { + cancelledBy, + OwnerCancellation, +} from "../../domain/analysisErrorCore.js"; import { err, type Result } from "../../domain/result.js"; import type { ProviderProcessSupervisor } from "../../process/ProviderProcess.js"; @@ -27,11 +30,7 @@ export class DesktopBuildOwnedWork { work: (stopping: AbortSignal) => Promise>, ): Promise> { if (this.#closed) - return err( - new AnalysisCancelledError(operation, { - cause: new Error("REA is closing its build computers"), - }), - ); + return err(cancelledBy(operation, OwnerCancellation.ownerClosed)); const stop = new AbortController(); const settled = work(AbortSignal.any([signal, stop.signal])); const pending = { settled, stop }; @@ -52,8 +51,7 @@ export class DesktopBuildOwnedWork { async close(): Promise { this.#closed = true; const pending = [...this.#pending]; - for (const work of pending) - work.stop.abort(new Error("REA is closing its build computers")); + for (const work of pending) work.stop.abort(OwnerCancellation.ownerClosed); await Promise.allSettled(pending.map((work) => work.settled)); const failures: Error[] = []; try { diff --git a/src/application/desktop/DesktopBuildSecrets.ts b/src/application/desktop/DesktopBuildSecrets.ts index ee9a409042..7218345fd6 100644 --- a/src/application/desktop/DesktopBuildSecrets.ts +++ b/src/application/desktop/DesktopBuildSecrets.ts @@ -6,8 +6,8 @@ import { import { bindArtifactFileCleanup } from "../../artifacts/ArtifactFileOperation.js"; import type { BuildSource } from "../../domain/desktop/appBuild.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { buildSecretHandleSchema, @@ -169,10 +169,7 @@ export class DesktopBuildSecrets { /** Every secret no bundle may hold: each value typed or kept here, then each the folder holds now, readable by others or not. */ async all(signal?: AbortSignal): Promise { - if (signal?.aborted) - throw new AnalysisCancelledError("export_build_environment", { - cause: signal.reason, - }); + if (signal?.aborted) throw cancelledBy("export_build_environment", signal); let handles: string[]; try { handles = await listBuildSecretHandles(this.directory); @@ -199,10 +196,7 @@ export class DesktopBuildSecrets { }), ), }); - if (signal?.aborted) - throw new AnalysisCancelledError("export_build_environment", { - cause: signal.reason, - }); + if (signal?.aborted) throw cancelledBy("export_build_environment", signal); const refused = read.find(({ file }) => !file.ok); if (refused !== undefined && !refused.file.ok) throw new AnalysisInputError("export_build_environment", { @@ -230,7 +224,7 @@ export class DesktopBuildSecrets { /** Why a secret was not typed, in REA's words and without its cause: the computer's own could quote the secret. */ const notTyped = (handle: string, signal: AbortSignal): AnalysisError => signal.aborted - ? new AnalysisCancelledError(ACT, { cause: signal.reason }) + ? cancelledBy(ACT, signal) : new ProviderAdapterError(AGENTENV_PROVIDER, ACT, { userMessage: `The computer did not type the secret ${handle}; REA does not show its answer, which could quote the secret.`, remediationAction: diff --git a/src/application/desktop/DesktopBuildSolves.ts b/src/application/desktop/DesktopBuildSolves.ts index 4c4672f455..a2083b4db3 100644 --- a/src/application/desktop/DesktopBuildSolves.ts +++ b/src/application/desktop/DesktopBuildSolves.ts @@ -20,9 +20,10 @@ import { z } from "zod"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { difficultyRecord, @@ -391,13 +392,15 @@ export const measureBuildTask = async ( (signal.aborted && cause.fileCleanupFailure.outcome.kind === "completed"); const failure = cancelled - ? new AnalysisCancelledError(MEASURE, { - cause: + ? cancelledBy( + MEASURE, + carriedReason( cause.cancellation === undefined ? signal.reason : cause.cancellation.reason, - cleanup, - }) + ), + { cleanup }, + ) : new ProviderAdapterError(AGENTENV_PROVIDER, MEASURE, { userMessage: `Measuring ${task} could not close an input file.`, cause, @@ -410,7 +413,7 @@ export const measureBuildTask = async ( cause instanceof AnalysisError ? cause : signal.aborted - ? new AnalysisCancelledError(MEASURE, { cause: signal.reason }) + ? cancelledBy(MEASURE, signal) : new ProviderAdapterError(AGENTENV_PROVIDER, MEASURE, { userMessage: `Measuring ${task} failed after ${String(solves.length)} solve(s): ${errorText(cause)}`, remediationAction: diff --git a/src/application/desktop/DesktopBuildSteps.ts b/src/application/desktop/DesktopBuildSteps.ts index 31e8adcf55..b44aa99afa 100644 --- a/src/application/desktop/DesktopBuildSteps.ts +++ b/src/application/desktop/DesktopBuildSteps.ts @@ -1,7 +1,7 @@ import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -71,11 +71,7 @@ export class DesktopBuildSteps { .catch(() => undefined); if (turn.aborted) { steps.capture.abandon(); - return err( - new AnalysisCancelledError("start_build_capture", { - cause: turn.reason, - }), - ); + return err(cancelledBy("start_build_capture", turn)); } return ok({ value: { diff --git a/src/application/desktop/DesktopBuildTurns.ts b/src/application/desktop/DesktopBuildTurns.ts index 4f3002a3bc..0066fa3c2b 100644 --- a/src/application/desktop/DesktopBuildTurns.ts +++ b/src/application/desktop/DesktopBuildTurns.ts @@ -1,5 +1,5 @@ import type { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { err, type Result } from "../../domain/result.js"; import { AbortedWait, @@ -34,7 +34,7 @@ export class DesktopBuildTurns { ) { // A call that never ran keeps its place until the one before it ends, so the next still waits for that one. void previous.then(release); - return err(new AnalysisCancelledError(operation, { cause: turn.reason })); + return err(cancelledBy(operation, turn)); } try { return await work(turn); diff --git a/src/application/desktop/DesktopBuildWitnessBundle.ts b/src/application/desktop/DesktopBuildWitnessBundle.ts index e9b37c6be4..bb33607771 100644 --- a/src/application/desktop/DesktopBuildWitnessBundle.ts +++ b/src/application/desktop/DesktopBuildWitnessBundle.ts @@ -6,8 +6,9 @@ import { z } from "zod"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import type { DesktopTask } from "../../domain/desktop/appTask.js"; import type { TaskCheckOutcome } from "../../domain/desktop/appTaskChecks.js"; @@ -77,7 +78,7 @@ export const bundleTaskDifference = async ( bundleFileBytes(), signal, false, - (reason) => new AnalysisCancelledError(CHECK, { cause: reason }), + (reason) => cancelledBy(CHECK, carriedReason(reason)), ), ), ); diff --git a/src/application/desktop/DesktopCaptureRefusals.ts b/src/application/desktop/DesktopCaptureRefusals.ts index 224666c0ab..6a222b0c35 100644 --- a/src/application/desktop/DesktopCaptureRefusals.ts +++ b/src/application/desktop/DesktopCaptureRefusals.ts @@ -9,9 +9,10 @@ import { import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { analysisErrorWithCancellation } from "../../domain/analysisErrorCancellation.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import { describeValidationFailure } from "../../domain/validationFailure.js"; @@ -229,9 +230,7 @@ export const desktopOperationFailure = ( ? cause.outcome.cause : cancellation === undefined ? undefined - : new AnalysisCancelledError(operation, { - cause: cancellation.reason, - }); + : cancelledBy(operation, carriedReason(cancellation.reason)); const error = new ProviderAdapterError(DESKTOP_PROVIDER.id, operation, { cause, ...(primary === undefined ? {} : { cleanupPrimary: primary }), @@ -251,9 +250,10 @@ export const desktopOperationFailure = ( ) { const primary = cause.reason === "cancelled" - ? new AnalysisCancelledError(operation, { - cause: artifactFileCancellationCause(cause), - }) + ? cancelledBy( + operation, + carriedReason(artifactFileCancellationCause(cause)), + ) : undefined; const error = new ProviderAdapterError(DESKTOP_PROVIDER.id, operation, { cause, @@ -268,9 +268,10 @@ export const desktopOperationFailure = ( cause instanceof ArtifactReaderFailure && cause.reason === "cancelled" ) { - failure = new AnalysisCancelledError(operation, { - cause: artifactFileCancellationCause(cause), - }); + failure = cancelledBy( + operation, + carriedReason(artifactFileCancellationCause(cause)), + ); } else failure = new ProviderAdapterError(DESKTOP_PROVIDER.id, operation, { cause, @@ -278,9 +279,6 @@ export const desktopOperationFailure = ( userMessage: `${label} could not complete: ${describeValidationFailure(cause)}`, }); return signal?.aborted === true - ? analysisErrorWithCancellation( - failure, - new AnalysisCancelledError(operation, { cause: signal.reason }), - ) + ? analysisErrorWithCancellation(failure, cancelledBy(operation, signal)) : failure; }; diff --git a/src/application/desktop/DesktopExportFiles.ts b/src/application/desktop/DesktopExportFiles.ts index 43e473303c..cc5724ffa7 100644 --- a/src/application/desktop/DesktopExportFiles.ts +++ b/src/application/desktop/DesktopExportFiles.ts @@ -1,4 +1,4 @@ -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { DESKTOP_VIEW_DEFAULTS, desktopViewFileLimitMessage, @@ -91,9 +91,7 @@ const retainedBytes = async ( signal: AbortSignal | undefined, ): Promise => { if (signal?.aborted === true) - throw new AnalysisCancelledError("export_desktop_application", { - cause: signal.reason, - }); + throw cancelledBy("export_desktop_application", signal); const bytes = await content.read(copy.digest, signal); if (!bytes.ok) throw refuse( diff --git a/src/application/desktop/DesktopExportInstall.ts b/src/application/desktop/DesktopExportInstall.ts index d03df7145b..eeb87329ca 100644 --- a/src/application/desktop/DesktopExportInstall.ts +++ b/src/application/desktop/DesktopExportInstall.ts @@ -1,7 +1,8 @@ import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { RegularFileCleanupFailure } from "../../filesystem/OwnedRegularFile.js"; import { @@ -85,7 +86,7 @@ export const readDownloadInstall = async ( text = await readRegularFileText(path, { signal, cancellationFailure: (reason) => - new AnalysisCancelledError(OPERATION, { cause: reason }), + cancelledBy(OPERATION, carriedReason(reason)), admit: (state) => { if (state.size > MAX_DOWNLOAD_INSTALL_BYTES) throw unreadable(); }, diff --git a/src/application/desktop/DesktopOutputTree.ts b/src/application/desktop/DesktopOutputTree.ts index 9ea9800333..d17cf09e3e 100644 --- a/src/application/desktop/DesktopOutputTree.ts +++ b/src/application/desktop/DesktopOutputTree.ts @@ -14,7 +14,10 @@ import { SafeOutputTreeCreationFailure } from "../../artifacts/SafeOutputTreeCre import { canonicalCallerPath } from "../../filesystem/canonicalCallerPath.js"; import { absoluteCallerPath } from "../../filesystem/callerPath.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../../domain/analysisErrorCore.js"; import { analysisErrorWithCancellation } from "../../domain/analysisErrorCancellation.js"; import type { Evidence } from "../../domain/evidence.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; @@ -95,10 +98,7 @@ export const planOutputTree = async ( const outputCancellation = ( operation: string, signal: AbortSignal | undefined, -) => - signal?.aborted === true - ? new AnalysisCancelledError(operation, { cause: signal.reason }) - : undefined; +) => (signal?.aborted === true ? cancelledBy(operation, signal) : undefined); /** * Write a new or empty folder through the safe output tree, rolling an diff --git a/src/application/desktop/DesktopRemoteTaskReaders.ts b/src/application/desktop/DesktopRemoteTaskReaders.ts index 3133faaada..7c1e63dc0d 100644 --- a/src/application/desktop/DesktopRemoteTaskReaders.ts +++ b/src/application/desktop/DesktopRemoteTaskReaders.ts @@ -1,6 +1,9 @@ import { randomUUID } from "node:crypto"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + cancelledBy, +} from "../../domain/analysisErrorCore.js"; import type { JsonValue } from "../../domain/jsonValue.js"; import type { DesktopTaskReader } from "../../domain/desktop/appTask.js"; import type { TaskFileView } from "../../domain/desktop/appTaskChecks.js"; @@ -272,9 +275,9 @@ export class DesktopRemoteTaskReaders { views: ReadonlyMap, absent: readonly string[], ) { - return new AnalysisCancelledError("check_build_task", { - cause: signal.reason, - }).retainDiagnostics(this.#facts(views, absent)); + return cancelledBy("check_build_task", signal).retainDiagnostics( + this.#facts(views, absent), + ); } #failure( diff --git a/src/application/desktop/DesktopTaskDraft.ts b/src/application/desktop/DesktopTaskDraft.ts index 91f75b4c4a..c731cdf51a 100644 --- a/src/application/desktop/DesktopTaskDraft.ts +++ b/src/application/desktop/DesktopTaskDraft.ts @@ -7,8 +7,8 @@ import { type WithholdSelection, } from "../../domain/desktop/appWithheld.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { draftTaskFiles } from "../../domain/desktop/appTaskDraft.js"; import { draftNotes } from "../../domain/desktop/appTaskDraftNotes.js"; @@ -159,8 +159,7 @@ const draft = async ( .filter((home) => isWithinAny(home, paths) && held(home)) .sort(), } as unknown as JsonValue; - if (signal?.aborted === true) - throw new AnalysisCancelledError(OPERATION, { cause: signal.reason }); + if (signal?.aborted === true) throw cancelledBy(OPERATION, signal); return createEvidence(undefined, DESKTOP_PROVIDER, { predicateType: "rea.desktop-application-task-draft", operation: OPERATION, diff --git a/src/application/desktop/DesktopTaskReaderCleanup.ts b/src/application/desktop/DesktopTaskReaderCleanup.ts index 7dfa522eb7..7ad58c9d85 100644 --- a/src/application/desktop/DesktopTaskReaderCleanup.ts +++ b/src/application/desktop/DesktopTaskReaderCleanup.ts @@ -1,4 +1,4 @@ -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy, carriedReason } from "../../domain/analysisErrorCore.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; @@ -22,9 +22,7 @@ const primaryFailure = (cause: unknown): AnalysisError | undefined => { if (cause instanceof AnalysisError) return cause; if (cause === undefined) return undefined; return cause instanceof OwnedCommandFailure && cause.reason === "cancelled" - ? new AnalysisCancelledError(OPERATION, { - cause: cause.cancellation?.reason, - }) + ? cancelledBy(OPERATION, carriedReason(cause.cancellation?.reason)) : new ProviderAdapterError(DESKTOP_PROVIDER.id, OPERATION, { cause, userMessage: `The task reader could not complete: ${cause instanceof Error ? cause.message : String(cause)}`, diff --git a/src/application/environment/environmentBuild.ts b/src/application/environment/environmentBuild.ts index 2bf05f09ad..3b980b99b2 100644 --- a/src/application/environment/environmentBuild.ts +++ b/src/application/environment/environmentBuild.ts @@ -8,6 +8,7 @@ import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { summarizeEnvironmentCoverage } from "../../domain/analysisView/environmentCoverageView.js"; import { @@ -158,15 +159,16 @@ const cancelled = async ( // The stages are synchronous; yield so a pending interrupt is dispatched before checking. if (signal !== undefined) await setImmediate(); return signal?.aborted === true - ? new AnalysisCancelledError(ENVIRONMENT_BUILD_OPERATION, { - cause: signal.reason, - ...(written === undefined + ? cancelledBy( + ENVIRONMENT_BUILD_OPERATION, + signal, + written === undefined ? {} : { userMessage: `The build was cancelled after it wrote the bundle at ${written}.`, diagnostics: { output_directory: written, bundle_written: true }, - }), - }) + }, + ) : undefined; }; diff --git a/src/application/firmware/FirmwareAnalysisService.ts b/src/application/firmware/FirmwareAnalysisService.ts index af74216d8d..390a1c6560 100644 --- a/src/application/firmware/FirmwareAnalysisService.ts +++ b/src/application/firmware/FirmwareAnalysisService.ts @@ -8,8 +8,8 @@ import { type FirmwareOperation, } from "../../domain/firmware/firmwareAnalysis.js"; import { - AnalysisCancelledError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { Evidence } from "../../domain/evidence.js"; @@ -32,9 +32,7 @@ export class FirmwareAnalysisService { options?: ExecutionOptions, ): Promise> { if (options?.signal?.aborted === true) - return err( - new AnalysisCancelledError(operation, { cause: options.signal.reason }), - ); + return err(cancelledBy(operation, options.signal)); const parsed = firmwareRequestSchema.safeParse({ operation, input }); if (!parsed.success) return err( diff --git a/src/application/frida/FridaInstrumentationService.ts b/src/application/frida/FridaInstrumentationService.ts index e360064310..24ac972d3b 100644 --- a/src/application/frida/FridaInstrumentationService.ts +++ b/src/application/frida/FridaInstrumentationService.ts @@ -13,6 +13,9 @@ import { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisInputError, + cancelledBy, + carriedReason, + isAborted, } from "../../domain/analysisErrorCore.js"; import { err, ok, type Result } from "../../domain/result.js"; import { fridaSessionStatusInputSchema } from "../../domain/fridaSessionStatus.js"; @@ -102,14 +105,11 @@ const rejectBeforeStart = async ( source: FridaScriptSource, signal: AbortSignal | undefined, ): Promise => { - const cancelled = () => - new AnalysisCancelledError( - "instrument_with_frida", - signal?.reason === undefined ? {} : { cause: signal.reason }, - ); - if (signal?.aborted) return cancelled(); + if (isAborted(signal)) return cancelledBy("instrument_with_frida", signal); const unreadable = await unreadableScriptFile(source); - return signal?.aborted ? cancelled() : unreadable; + return isAborted(signal) + ? cancelledBy("instrument_with_frida", signal) + : unreadable; }; /** Shared CLI/MCP workflows for Frida's device and instrumentation operations. */ @@ -158,19 +158,13 @@ export class FridaInstrumentationService { signal: AbortSignal | undefined, operation: string, ) { - if (signal?.aborted) - return err( - new AnalysisCancelledError( - operation, - signal.reason === undefined ? {} : { cause: signal.reason }, - ), - ); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const started = await this.#provider.startSession(input); if (!started.ok && signal?.aborted) return err( analysisErrorWithCancellation( started.error, - new AnalysisCancelledError(operation, { cause: signal.reason }), + cancelledBy(operation, signal), ), ); if (!started.ok || !signal?.aborted) return started; @@ -217,12 +211,7 @@ export class FridaInstrumentationService { source: FridaScriptSource, signal?: AbortSignal, ): Promise> { - if (signal?.aborted) - return err( - new AnalysisCancelledError("load_frida_script", { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy("load_frida_script", signal)); const loaded = await this.#provider.loadScript(sessionId, source, signal); if (!loaded.ok && loaded.error instanceof FridaScriptLoadCancelledError) return err(cancelledScriptEvidence(sessionId, loaded.error)); @@ -443,9 +432,7 @@ export class FridaInstrumentationService { signal?.aborted ? analysisErrorWithCancellation( failure, - new AnalysisCancelledError("instrument_with_frida", { - cause: signal.reason, - }), + cancelledBy("instrument_with_frida", signal), ) : failure, ); @@ -512,8 +499,7 @@ const cancelledFridaSession = ({ script, }: FridaSessionCancellation): AnalysisCancelledError => { const cleanupError = closed.ok ? null : closed.error.message; - const failure = new AnalysisCancelledError(operation, { - ...(cause === undefined ? {} : { cause }), + const failure = cancelledBy(operation, carriedReason(cause), { diagnostics, partialObservation: fridaEvidence( operation, @@ -616,8 +602,7 @@ const cancelledScriptEvidence = ( sessionId: string, error: FridaScriptLoadCancelledError, ): AnalysisCancelledError => - new AnalysisCancelledError(error.operation, { - cause: error.cause, + cancelledBy(error.operation, carriedReason(error.cause), { diagnostics: error.diagnostics, cleanup: error.cleanup, partialObservation: fridaEvidence( diff --git a/src/application/gpu/GpuCodeObjectsService.ts b/src/application/gpu/GpuCodeObjectsService.ts index 99002fb85b..d8984a4bc0 100644 --- a/src/application/gpu/GpuCodeObjectsService.ts +++ b/src/application/gpu/GpuCodeObjectsService.ts @@ -7,8 +7,8 @@ import type { ExecutionOptions } from "../AnalysisProvider.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { Evidence } from "../../domain/evidence.js"; import { createGpuCodeObjectsEvidence } from "../../domain/gpu/gpuCodeObjectsEvidence.js"; @@ -44,11 +44,7 @@ export class GpuCodeObjectsService { ), ); if (options?.signal?.aborted) - return err( - new AnalysisCancelledError("inspect_gpu_code_objects", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("inspect_gpu_code_objects", options.signal)); const { detail, view, ...parameters } = input.data; if (detail === "summary") { const ready = requireAnalysisViewRetention( @@ -81,8 +77,7 @@ export class GpuCodeObjectsService { ); if (options?.signal?.aborted) return err( - new AnalysisCancelledError("inspect_gpu_code_objects", { - cause: options.signal.reason, + cancelledBy("inspect_gpu_code_objects", options.signal, { partialObservation: evidence, }), ); diff --git a/src/application/il2cpp/Il2cppMetadataService.ts b/src/application/il2cpp/Il2cppMetadataService.ts index c77bb2410c..d1683cad9e 100644 --- a/src/application/il2cpp/Il2cppMetadataService.ts +++ b/src/application/il2cpp/Il2cppMetadataService.ts @@ -15,9 +15,10 @@ import { import type { Il2cppMetadataPort } from "./Il2cppMetadataPort.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, + cancelledBy, + isAborted, } from "../../domain/analysisErrorCore.js"; import { createEvidence, type Evidence } from "../../domain/evidence.js"; import { @@ -153,17 +154,16 @@ export class Il2cppMetadataService { const value = report.data; const evidence = this.#evidence(value, providerInput, output); let seedReceipt: Il2cppSeedReceipt | undefined; - const cancelled = () => + const cancelled = (signal: AbortSignal) => err( - new AnalysisCancelledError(OPERATION, { - cause: options?.signal?.reason, + cancelledBy(OPERATION, signal, { partialObservation: evidence, ...(seedReceipt === undefined ? {} : { diagnostics: { published_seed_output: { ...seedReceipt } } }), }), ); - if (options?.signal?.aborted) return cancelled(); + if (isAborted(options?.signal)) return cancelled(options.signal); if (output !== undefined && this.seeds !== undefined) { const written = await this.seeds.write(value, output, options); if (!written.ok) { @@ -172,7 +172,7 @@ export class Il2cppMetadataService { } seedReceipt = written.value; } - if (options?.signal?.aborted) return cancelled(); + if (isAborted(options?.signal)) return cancelled(options.signal); return detail === "summary" ? summarizeRetainedAnalysis(evidence, retention) : ok(evidence); diff --git a/src/application/javascript/ElectronActiveObservationService.ts b/src/application/javascript/ElectronActiveObservationService.ts index aef16811ed..6d0d6fedfa 100644 --- a/src/application/javascript/ElectronActiveObservationService.ts +++ b/src/application/javascript/ElectronActiveObservationService.ts @@ -9,11 +9,11 @@ import type { } from "./ElectronActiveObservationPort.js"; import { AnalysisAccessDeniedError, - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, type AnalysisInputIssue, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { Evidence } from "../../domain/evidence.js"; @@ -194,15 +194,11 @@ export const captureElectronScenario = async ( options: ExecutionOptions = {}, ): Promise> => { if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); const canonical = await canonicalizeInput(input); if (!canonical.ok) return canonical; if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); if (provider === undefined) return err( new AnalysisCapabilityUnavailableError( diff --git a/src/application/javascript/ElectronObservationService.ts b/src/application/javascript/ElectronObservationService.ts index c3b4ca68ac..a6b1cbbd57 100644 --- a/src/application/javascript/ElectronObservationService.ts +++ b/src/application/javascript/ElectronObservationService.ts @@ -7,9 +7,9 @@ import type { ListElectronTargetsInput, } from "../../domain/javascript/electronObservation.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -33,11 +33,7 @@ export const listElectronTargets = async ( const ready = requireProvider(provider, "list_electron_targets"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("list_electron_targets", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("list_electron_targets", options.signal)); const result = await ready.value.listTargets(input, options); if (!result.ok) return result; const json = jsonValueSchema.safeParse(result.value); @@ -78,11 +74,7 @@ export const inspectElectronPage = async ( const ready = requireProvider(provider, "inspect_electron_page"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("inspect_electron_page", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("inspect_electron_page", options.signal)); const result = await ready.value.inspectPage(input, options); if (!result.ok) { const partial = jsonObjectSchema.safeParse(result.error.partialObservation); diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.ts b/src/application/javascript/JavaScriptArtifactAnalysis.ts index 142587a98a..a01a30bac8 100644 --- a/src/application/javascript/JavaScriptArtifactAnalysis.ts +++ b/src/application/javascript/JavaScriptArtifactAnalysis.ts @@ -49,9 +49,10 @@ import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; import { translateArtifactFailure } from "../../artifacts/ArtifactOperationFailure.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { - AnalysisCancelledError, AnalysisResourceConstraintError, AnalysisTimeoutError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; interface MutableArtifactAnalysis { @@ -105,18 +106,13 @@ export const analyzeAndAdoptJavaScriptArtifactFiles = async ( await setImmediate(); if (classifyUnavailableSource(file, state, projection)) { if (signal?.aborted === true) { - interruption = new AnalysisCancelledError( - "analyze_javascript_application", - { cause: signal.reason }, - ); + interruption = cancelledBy("analyze_javascript_application", signal); break; } continue; } if (signal?.aborted === true) - throw new AnalysisCancelledError("analyze_javascript_application", { - cause: signal.reason, - }); + throw cancelledBy("analyze_javascript_application", signal); await beforeFile(file, selectedFileIndex++, selectedFileCount); analysisStarted = true; if (file.kind !== "javascript" || !file.text.included) { @@ -235,9 +231,9 @@ export const analyzeAndAdoptJavaScriptArtifactFiles = async ( cause, ); else if (signal?.aborted === true && cause === signal.reason) - interruption = new AnalysisCancelledError( + interruption = cancelledBy( "analyze_javascript_application", - { cause }, + carriedReason(cause), ); else throw cause; const scope = javascriptArtifactAnalysisScopes[file.kind]; diff --git a/src/application/javascript/JavaScriptRuntimeObservationService.ts b/src/application/javascript/JavaScriptRuntimeObservationService.ts index 54b86d39c8..75e50c0545 100644 --- a/src/application/javascript/JavaScriptRuntimeObservationService.ts +++ b/src/application/javascript/JavaScriptRuntimeObservationService.ts @@ -3,9 +3,9 @@ import type { JavaScriptRuntimeObservationPort } from "./JavaScriptRuntimeObserv import { createJavaScriptRuntimeObservationEvidence } from "./JavaScriptRuntimeObservationEvidence.js"; import type { Evidence } from "../../domain/evidence.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { @@ -32,11 +32,7 @@ export const listJavaScriptRuntimeTargets = async ( const ready = requireProvider(provider, "list_javascript_runtime_targets"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("list_javascript_runtime_targets", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("list_javascript_runtime_targets", options.signal)); const result = await ready.value.listTargets(input, options); if (!result.ok) return result; const report = javascriptRuntimeTargetListSchema.safeParse(result.value); @@ -66,11 +62,7 @@ export const observeJavaScriptRuntime = async ( const ready = requireProvider(provider, "observe_javascript_runtime"); if (!ready.ok) return ready; if (options.signal?.aborted) - return err( - new AnalysisCancelledError("observe_javascript_runtime", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("observe_javascript_runtime", options.signal)); const result = await ready.value.observe(input, options); if (!result.ok) { const partial = result.error.partialObservation; diff --git a/src/application/javascript/SourceToBundleReference.ts b/src/application/javascript/SourceToBundleReference.ts index 203320e252..e62b8bba0d 100644 --- a/src/application/javascript/SourceToBundleReference.ts +++ b/src/application/javascript/SourceToBundleReference.ts @@ -7,7 +7,7 @@ import { type HistoricalSourceGraph, } from "../../domain/referenceSourceGraph.js"; import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy, isAborted } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -29,13 +29,8 @@ export const resolveSourceToBundleReference = async ( signal?: AbortSignal, resources?: ArtifactResourceScope, ): Promise> => { - const cancelled = () => signal?.aborted === true; - if (cancelled()) - return err( - new AnalysisCancelledError("compare_source_to_bundle", { - cause: signal?.reason, - }), - ); + if (isAborted(signal)) + return err(cancelledBy("compare_source_to_bundle", signal)); if (!("kind" in reference)) return ok({ reference }); const read = await readJsonFileWithSource( reference.path, @@ -45,12 +40,8 @@ export const resolveSourceToBundleReference = async ( ); if (!read.ok) return read; await setImmediate(); - if (cancelled()) - return err( - new AnalysisCancelledError("compare_source_to_bundle", { - cause: signal?.reason, - }), - ); + if (isAborted(signal)) + return err(cancelledBy("compare_source_to_bundle", signal)); const headroom = requireAuthenticationHeadroom(read.value.data, { operation: "compare_source_to_bundle", path: read.value.path, @@ -61,12 +52,8 @@ export const resolveSourceToBundleReference = async ( const parsed = historicalSourceGraphSchema.safeParse(read.value.data); // Dispatch aborts queued while synchronous validation and commitment hashing ran. await setImmediate(); - if (cancelled()) - return err( - new AnalysisCancelledError("compare_source_to_bundle", { - cause: signal?.reason, - }), - ); + if (isAborted(signal)) + return err(cancelledBy("compare_source_to_bundle", signal)); if (!parsed.success) return err( analysisInputErrorFromIssues( diff --git a/src/application/javascript/StaticObservedEndpointComparisonService.ts b/src/application/javascript/StaticObservedEndpointComparisonService.ts index a91d85d96b..4d2ae36bd5 100644 --- a/src/application/javascript/StaticObservedEndpointComparisonService.ts +++ b/src/application/javascript/StaticObservedEndpointComparisonService.ts @@ -6,8 +6,8 @@ import { readImmutableEvidence } from "../../domain/evidenceValidation.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { EvidenceWorkflowExecution } from "../investigation/EvidenceWorkflowExecution.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { digestCanonicalValue } from "../../domain/canonicalDigest.js"; import { err, ok, type Result } from "../../domain/result.js"; @@ -217,11 +217,7 @@ export const compareStaticAndObservedEndpointsEvidence = async ( if (index % 256 === 0) { await setImmediate(); if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(OPERATION, options.signal)); } const added = accumulator.add(record); if (!added.ok) return added; @@ -237,8 +233,6 @@ export const compareStaticAndObservedEndpointsEvidence = async ( if (!compared.ok) return compared; await setImmediate(); if (options.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); return createComparison(sources, compared.value, accumulator); }; diff --git a/src/application/model/ModelArtifactService.ts b/src/application/model/ModelArtifactService.ts index a9e9ff23ed..44ca9dacd8 100644 --- a/src/application/model/ModelArtifactService.ts +++ b/src/application/model/ModelArtifactService.ts @@ -5,8 +5,8 @@ import { modelArtifactSchema } from "../../domain/model/modelArtifact.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import type { Evidence } from "../../domain/evidence.js"; import { createModelArtifactEvidence } from "../../domain/model/modelArtifactEvidence.js"; @@ -42,11 +42,7 @@ export class ModelArtifactService { ), ); if (options?.signal?.aborted) - return err( - new AnalysisCancelledError("inspect_model_artifact", { - cause: options.signal.reason, - }), - ); + return err(cancelledBy("inspect_model_artifact", options.signal)); const { detail, view, ...parameters } = input.data; if (detail === "summary") { const ready = requireAnalysisViewRetention( @@ -81,8 +77,7 @@ export class ModelArtifactService { ); if (options?.signal?.aborted) return err( - new AnalysisCancelledError("inspect_model_artifact", { - cause: options.signal.reason, + cancelledBy("inspect_model_artifact", options.signal, { partialObservation: evidence, }), ); diff --git a/src/application/native/NativeFunctionMatchingService.ts b/src/application/native/NativeFunctionMatchingService.ts index a131f5bf0b..52ea86c22e 100644 --- a/src/application/native/NativeFunctionMatchingService.ts +++ b/src/application/native/NativeFunctionMatchingService.ts @@ -16,7 +16,7 @@ import { NATIVE_FUNCTION_MATCHING_PREDICATE, } from "../../domain/native/functionMatching.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js"; import { err, ok, type Result } from "../../domain/result.js"; import type { EvidenceLookup } from "../EvidenceInputResolver.js"; @@ -208,9 +208,7 @@ const matchingFailure = ( ): Result => { if (cause instanceof RegularFileCleanupFailure) throw cause; if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); if (cause instanceof AnalysisError) return err(cause); throw cause; }; diff --git a/src/application/native/NativeValueTrace.ts b/src/application/native/NativeValueTrace.ts index 2650cdd191..a93de0c038 100644 --- a/src/application/native/NativeValueTrace.ts +++ b/src/application/native/NativeValueTrace.ts @@ -6,9 +6,9 @@ import { } from "../../domain/native/nativeValueTrace.js"; import { createAnalysisExecutionEvidence } from "../../domain/analysisObservation.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { err, ok } from "../../domain/result.js"; import type { AnalysisOperationPort } from "../AnalysisProvider.js"; @@ -119,12 +119,7 @@ export const traceNativeValues = async ( return true; }; while (pending.length > 0) { - if (signal?.aborted) - return err( - new AnalysisCancelledError("trace_native_values", { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy("trace_native_values", signal)); const next = pending.shift(); if ( next === undefined || @@ -536,11 +531,6 @@ export const traceNativeValues = async ( "Graph output exceeds 33554432 bytes (32 MiB). This release has no runtime override. Lower max_nodes, max_edges, or the page limit.", ), ); - if (signal?.aborted) - return err( - new AnalysisCancelledError("trace_native_values", { - cause: signal.reason, - }), - ); + if (signal?.aborted) return err(cancelledBy("trace_native_values", signal)); return ok(result); }; diff --git a/src/application/ntfs/NtfsJournalService.ts b/src/application/ntfs/NtfsJournalService.ts index 379e7b5ad8..ef06cb87a6 100644 --- a/src/application/ntfs/NtfsJournalService.ts +++ b/src/application/ntfs/NtfsJournalService.ts @@ -29,6 +29,8 @@ import { AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { ArtifactOperationError } from "../../domain/artifactOperationError.js"; import { isSelectedRegularFileError } from "../../filesystem/RegularFile.js"; @@ -76,9 +78,10 @@ const readFailure = ( const { cause } = artifactFilePrimaryFacts(failure); if (cause instanceof ArtifactReaderFailure) { if (cause.reason === "cancelled") - return new AnalysisCancelledError(operation, { - cause: artifactFileCancellationCause(cause), - }); + return cancelledBy( + operation, + carriedReason(artifactFileCancellationCause(cause)), + ); if (cause.reason === "integrity") return new AnalysisArtifactChangedError(operation, path, cause.message, { cause, diff --git a/src/application/pcap/PcapAnalysisService.ts b/src/application/pcap/PcapAnalysisService.ts index 0a69d14ae7..bcbabd93d7 100644 --- a/src/application/pcap/PcapAnalysisService.ts +++ b/src/application/pcap/PcapAnalysisService.ts @@ -5,7 +5,7 @@ import { pcapRequestSchema, type PcapOperation, } from "../../domain/pcap/pcapAnalysis.js"; -import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; +import { cancelledBy } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { Evidence } from "../../domain/evidence.js"; import { createPcapEvidence } from "../../domain/pcap/pcapEvidence.js"; @@ -23,11 +23,7 @@ export class PcapAnalysisService { options?: ExecutionOptions, ): Promise> { if (options?.signal?.aborted === true) - return err( - new AnalysisCancelledError(operation, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(operation, options.signal)); const request = pcapRequestSchema.safeParse({ operation, input }); if (!request.success) return err( diff --git a/src/application/process/ProcessCli.ts b/src/application/process/ProcessCli.ts index 02722f1859..ad0a9f3a20 100644 --- a/src/application/process/ProcessCli.ts +++ b/src/application/process/ProcessCli.ts @@ -6,6 +6,8 @@ import { AnalysisCancelledError, AnalysisInputError, type AnalysisInputIssue, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import type { AnalysisErrorProjection } from "../../domain/analysisErrorProjection.js"; @@ -323,14 +325,12 @@ const readJson = async ( signal: AbortSignal | undefined, resources: ArtifactResourceScope, ): Promise => { - if (signal?.aborted) - throw new AnalysisCancelledError(operation, { cause: signal.reason }); + if (signal?.aborted) throw cancelledBy(operation, signal); const loaded = await readJsonFile(path, signal, resources, operation); if (!loaded.ok && loaded.error instanceof AnalysisCancelledError) - throw new AnalysisCancelledError(operation, { cause: loaded.error.cause }); + throw cancelledBy(operation, carriedReason(loaded.error.cause)); if (loaded.ok) { - if (signal?.aborted) - throw new AnalysisCancelledError(operation, { cause: signal.reason }); + if (signal?.aborted) throw cancelledBy(operation, signal); return loaded.value; } if (loaded.error._tag !== "EvidenceFileError") throw loaded.error; @@ -408,10 +408,7 @@ const projectProcessCliError = ( }); return cliAnalysisError( signal?.aborted - ? analysisErrorWithCancellation( - failure, - new AnalysisCancelledError(operation, { cause: signal.reason }), - ) + ? analysisErrorWithCancellation(failure, cancelledBy(operation, signal)) : failure, ); }; @@ -459,10 +456,11 @@ const withProcessInputResources = async ( resources.cleanupResources, ); const cancellation = signal?.aborted - ? new AnalysisCancelledError(operation, { - cause: signal.reason, - ...(outcome.ok ? { partialObservation: outcome.value } : {}), - }) + ? cancelledBy( + operation, + signal, + outcome.ok ? { partialObservation: outcome.value } : {}, + ) : undefined; const primary = outcome.ok ? cancellation === undefined diff --git a/src/application/process/ProcessScenarioPreparation.ts b/src/application/process/ProcessScenarioPreparation.ts index 4010896982..fd4786d435 100644 --- a/src/application/process/ProcessScenarioPreparation.ts +++ b/src/application/process/ProcessScenarioPreparation.ts @@ -1,8 +1,9 @@ import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, + cancelledBy, + isAborted, } from "../../domain/analysisErrorCore.js"; import type { ProcessScenario } from "../../domain/process/processScenario.js"; import { admitFilesystemObservationRoots } from "../../process/capture/FilesystemSnapshot.js"; @@ -26,11 +27,7 @@ export const prepareProcessScenarioPlan = async ( signal?: AbortSignal, ): Promise> => { if (signal?.aborted === true) - return err( - new AnalysisCancelledError("capture_process_scenario", { - cause: signal.reason, - }), - ); + return err(cancelledBy("capture_process_scenario", signal)); const ownershipReason = processCaptureOwnershipUnavailableReason(platform); if (ownershipReason !== undefined) return err( @@ -41,25 +38,24 @@ export const prepareProcessScenarioPlan = async ( { userMessage: ownershipReason }, ), ); - const cancelled = () => - err( - new AnalysisCancelledError("capture_process_scenario", { - cause: signal?.reason, - }), - ); - const aborted = () => signal?.aborted === true; try { const { dry_run: _dryRun, ...resolved } = await resolveProcessScenarioRuntimePaths(scenario, environment, platform); - if (aborted()) return cancelled(); + if (isAborted(signal)) + return err(cancelledBy("capture_process_scenario", signal)); const privacy = createProcessSensitiveOutput(scenario); if (!privacy.ok) return privacy; const admitted = await admitFilesystemObservationRoots(resolved, signal); - if (!admitted.ok) return aborted() ? cancelled() : admitted; - if (aborted()) return cancelled(); + if (!admitted.ok) + return isAborted(signal) + ? err(cancelledBy("capture_process_scenario", signal)) + : admitted; + if (isAborted(signal)) + return err(cancelledBy("capture_process_scenario", signal)); return ok(resolved); } catch (cause: unknown) { - if (aborted()) return cancelled(); + if (isAborted(signal)) + return err(cancelledBy("capture_process_scenario", signal)); return err( cause instanceof AnalysisError ? cause diff --git a/src/application/releaseExposure/ReleaseExposureService.ts b/src/application/releaseExposure/ReleaseExposureService.ts index 4051895248..2effb076da 100644 --- a/src/application/releaseExposure/ReleaseExposureService.ts +++ b/src/application/releaseExposure/ReleaseExposureService.ts @@ -14,6 +14,8 @@ import { AnalysisCancelledError, AnalysisOutputError, AnalysisUnsupportedTargetError, + cancelledBy, + carriedReason, } from "../../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { desktopApplicationSchema } from "../../domain/desktopApplication.js"; @@ -98,11 +100,7 @@ export class ReleaseExposureService { ); if (!input.ok) return input; if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(RELEASE_EXPOSURE_OPERATION, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(RELEASE_EXPOSURE_OPERATION, options.signal)); const markerHits: CredentialMarkerHit[] = []; let omittedMarkerHits = 0; const interrupted: { scan?: ReleaseExposureScan } = {}; @@ -417,11 +415,7 @@ export class ReleaseExposureService { present: (value: Evidence) => MetadataImageFact, ): Promise> { if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(RELEASE_EXPOSURE_OPERATION, { - cause: options.signal.reason, - }), - ); + return err(cancelledBy(RELEASE_EXPOSURE_OPERATION, options.signal)); try { const result = await run(); if (!result.ok) { @@ -557,8 +551,7 @@ const withAuditPartial = ( report: Evidence, ): AnalysisError => { if (error.partialObservation !== undefined && !error.cleanupIncomplete) - return new AnalysisCancelledError(RELEASE_EXPOSURE_OPERATION, { - cause: error.cause, + return cancelledBy(RELEASE_EXPOSURE_OPERATION, carriedReason(error.cause), { partialObservation: report, }); error.partialObservation = report; diff --git a/src/application/reverse/ReverseEngineeringService.ts b/src/application/reverse/ReverseEngineeringService.ts index 0c3c54afe7..257dcaa243 100644 --- a/src/application/reverse/ReverseEngineeringService.ts +++ b/src/application/reverse/ReverseEngineeringService.ts @@ -28,6 +28,8 @@ import { AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisOutputError, + cancelledBy, + carriedReason, OwnerCancellation, } from "../../domain/analysisErrorCore.js"; import { @@ -491,9 +493,7 @@ export class ReverseEngineeringService { }): Promise> { const { operation, signal, outputBudgetBytes } = request; if (signal?.aborted) - return Promise.resolve( - err(new AnalysisCancelledError(operation, { cause: signal.reason })), - ); + return Promise.resolve(err(cancelledBy(operation, signal))); if (this.#closing) return Promise.resolve( err( @@ -558,9 +558,7 @@ export class ReverseEngineeringService { ? err( analysisErrorWithCancellation( result.error, - new AnalysisCancelledError(operation, { - cause: operationSignal.reason, - }), + cancelledBy(operation, operationSignal), ), ) : result, @@ -587,10 +585,7 @@ export class ReverseEngineeringService { outputBudgetBytes, } = request; const { executable: command, arguments: args } = profile; - if (signal?.aborted) - return err( - new AnalysisCancelledError(operation, { cause: signal.reason }), - ); + if (signal?.aborted) return err(cancelledBy(operation, signal)); const cleanup = await this.retryCleanup(operation); if (!cleanup.ok) return cleanup; const absolutePath = @@ -608,9 +603,10 @@ export class ReverseEngineeringService { const code = commandFailureCode(cause); if (preflightCancelled(signal, cause, code)) return err( - new AnalysisCancelledError(operation, { - cause: callerCancellationCause(signal, cause), - }), + cancelledBy( + operation, + carriedReason(callerCancellationCause(signal, cause)), + ), ); if (code === "EACCES" || code === "EPERM") { const deniedPath = absolutePath === undefined ? command : absolutePath; @@ -880,9 +876,10 @@ export class ReverseEngineeringService { ...reverseCommandTimeoutGuidance(timeoutMs), }); } else if (darwinFailure.cancellation !== undefined) { - earlyFailure = new AnalysisCancelledError(operation, { - cause: darwinFailure.cancellation?.reason, - }); + earlyFailure = cancelledBy( + operation, + carriedReason(darwinFailure.cancellation?.reason), + ); } else { const setting = operation === "inspect_with_objdump" @@ -971,10 +968,11 @@ export class ReverseEngineeringService { code === "ERR_PROVIDER_LAUNCH") ) { if (commandCancelled(signal, cause, code)) - earlyFailure = new AnalysisCancelledError(operation, { - cause: callerCancellationCause(signal, cause), - ...ownedCleanupOptions(cause), - }); + earlyFailure = cancelledBy( + operation, + carriedReason(callerCancellationCause(signal, cause)), + { ...ownedCleanupOptions(cause) }, + ); else if (code === "ETIMEDOUT") earlyFailure = new AnalysisTimeoutError(operation, timeoutMs, { cause, @@ -1027,11 +1025,11 @@ export class ReverseEngineeringService { signal: capture.signal, }; if (commandCancelled(signal, cause, code)) - failure = new AnalysisCancelledError(operation, { - cause: callerCancellationCause(signal, cause), - capturedOutput, - ...ownedCleanupOptions(cause), - }); + failure = cancelledBy( + operation, + carriedReason(callerCancellationCause(signal, cause)), + { capturedOutput, ...ownedCleanupOptions(cause) }, + ); else if (code === "ETIMEDOUT") failure = new AnalysisTimeoutError(operation, timeoutMs, { cause, @@ -1118,8 +1116,7 @@ export class ReverseEngineeringService { } } if (signal?.aborted && failure === undefined) { - failure = new AnalysisCancelledError(operation, { - cause: signal.reason, + failure = cancelledBy(operation, signal, { capturedOutput: { stdout, stderr, @@ -1541,9 +1538,7 @@ export const digestFile = async ( ); const abort = (): void => { stream.destroy( - new AnalysisCancelledError("artifact_digest", { - cause: signal?.reason, - }), + cancelledBy("artifact_digest", carriedReason(signal?.reason)), ); }; const cleanup = (): void => { @@ -1553,11 +1548,7 @@ export const digestFile = async ( if (signal?.aborted) { cleanup(); stream.destroy(); - rejectDigest( - new AnalysisCancelledError("artifact_digest", { - cause: signal.reason, - }), - ); + rejectDigest(cancelledBy("artifact_digest", signal)); return; } signal?.addEventListener("abort", abort, { once: true }); @@ -1637,9 +1628,7 @@ const statWithDeadline = ( timeoutMs: number, ): Promise => { if (signal?.aborted) - return Promise.reject( - new AnalysisCancelledError("artifact_digest", { cause: signal.reason }), - ); + return Promise.reject(cancelledBy("artifact_digest", signal)); return new Promise((resolveStat, rejectStat) => { let settled = false; const finish = (outcome: Result): void => { @@ -1652,11 +1641,7 @@ const statWithDeadline = ( }; const abort = (): void => finish( - err( - new AnalysisCancelledError("artifact_digest", { - cause: signal?.reason, - }), - ), + err(cancelledBy("artifact_digest", carriedReason(signal?.reason))), ); const timer = setTimeout( () => diff --git a/src/application/wasm/WasmInterfaceComparisonService.ts b/src/application/wasm/WasmInterfaceComparisonService.ts index d0e2b49f17..53721e149e 100644 --- a/src/application/wasm/WasmInterfaceComparisonService.ts +++ b/src/application/wasm/WasmInterfaceComparisonService.ts @@ -19,8 +19,8 @@ import { } from "../../domain/wasm/wasmArtifact.js"; import type { WasmInterfaceEntry } from "../../domain/wasm/wasmInterface.js"; import { - AnalysisCancelledError, AnalysisInputError, + cancelledBy, } from "../../domain/analysisErrorCore.js"; import { WasmInterfaceBudget } from "../../domain/wasm/wasmInterfaceBudget.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; @@ -95,9 +95,7 @@ export const compareWasmInterfaces = async ( lookup?: EvidenceLookup, ): Promise> => { if (options?.signal?.aborted) - return err( - new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }), - ); + return err(cancelledBy(OPERATION, options.signal)); const resolved = resolveEvidenceRequest( OPERATION, rawInput, @@ -107,10 +105,7 @@ export const compareWasmInterfaces = async ( ); if (!resolved.ok) return resolved; const assertActive = () => { - if (options?.signal?.aborted) - throw new AnalysisCancelledError(OPERATION, { - cause: options.signal.reason, - }); + if (options?.signal?.aborted) throw cancelledBy(OPERATION, options.signal); }; try { await setImmediate();