From 28265927594d6929f6c84d6c65ddd6d72a0b6ee6 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 18:38:24 +0800 Subject: [PATCH] refactor(application): build application cancellations with a required reason (#10574) * refactor(application): build application cancellations with a required reason Migrate every AnalysisCancelledError construction under src/application to cancelledBy and lower the guard baseline from 671 to 442. Shutdown refusals in BinarySession report OwnerCancellation.ownerClosed when the caller did not abort, instead of an undefined reason. ReverseEngineeringService and DesktopBuildOwnedWork close their work with the typed owner reason. SharedStartupAttempt returns the departing caller's reason with a cancelled wait. One shared isAborted predicate replaces eleven local copies and narrows a checked signal for cancelledBy. * refactor(desktop): drop an unused cancellation import from desktop capture state --- .../verify/architecture-guard-baselines.json | 79 ------- src/application/AnalysisContextQueries.ts | 40 +--- src/application/AnalysisDocument.ts | 16 +- src/application/AnalysisInput.ts | 5 +- src/application/BinaryTargetResolver.ts | 52 ++--- src/application/BrowserObservationService.ts | 38 +--- .../BrowserScenarioCaptureService.ts | 6 +- src/application/CallPathTracing.ts | 27 +-- src/application/DirectAnalysis.ts | 10 +- src/application/Doctor.ts | 22 +- src/application/EnhancedLiteralTracing.ts | 8 +- src/application/EnhancedTools.ts | 12 +- src/application/EvidenceBundleCommands.ts | 5 +- src/application/EvidenceBundleFiles.ts | 22 +- src/application/EvidenceInputResolver.ts | 12 +- src/application/JsonFiles.ts | 41 ++-- src/application/LinuxHopper.ts | 4 +- src/application/LinuxHopperPython.ts | 3 +- src/application/McpClientRegistration.ts | 12 +- src/application/McpRegistrationCatalog.ts | 14 +- src/application/McpRegistrationGit.ts | 14 +- src/application/ProviderOperationExecution.ts | 8 +- src/application/ReferenceSourceImport.ts | 3 +- .../ReferenceSourceImportPolicy.ts | 3 +- src/application/ReferenceSourceImportTypes.ts | 18 +- src/application/ReferenceSourceVcsAdapter.ts | 3 +- src/application/Setup.ts | 8 +- src/application/SetupCancellation.ts | 13 +- src/application/WebModuleTraceService.ts | 8 +- src/application/WebNetworkCaptureService.ts | 8 +- src/application/WebScriptExportService.ts | 28 +-- src/application/WebSourceLocationService.ts | 6 +- src/application/XrefsAddressResolution.ts | 8 +- .../analysisView/AnalysisViewService.ts | 14 +- .../analysisView/evidenceFileSource.ts | 8 +- .../android/AndroidAnalysisService.ts | 6 +- .../apiContract/ApiContractRead.ts | 10 +- .../apiContract/ApiContractTraversal.ts | 4 +- .../binary/AnalysisProviderEvaluation.ts | 15 +- .../binary/AnalysisProviderRegistry.ts | 74 ++----- .../binary/AnalysisSnapshotFiles.ts | 9 +- src/application/binary/BinarySession.ts | 209 ++++++------------ .../binary/BinarySessionInvestigation.test.ts | 5 +- .../binary/LazyAnalysisProvider.ts | 7 +- .../binaryDiagnostics/ByteEntropyService.ts | 38 ++-- .../decompileDirectory/decompileAll.ts | 29 +-- .../desktop/DesktopApplicationCapture.ts | 10 +- .../desktop/DesktopApplicationState.ts | 34 ++- .../desktop/DesktopBuildCapture.ts | 7 +- .../desktop/DesktopBuildCaptureFailure.ts | 7 +- .../desktop/DesktopBuildComputers.ts | 13 +- src/application/desktop/DesktopBuildExport.ts | 4 +- .../desktop/DesktopBuildOwnedWork.ts | 14 +- .../desktop/DesktopBuildSecrets.ts | 14 +- src/application/desktop/DesktopBuildSolves.ts | 15 +- src/application/desktop/DesktopBuildSteps.ts | 8 +- src/application/desktop/DesktopBuildTurns.ts | 4 +- .../desktop/DesktopBuildWitnessBundle.ts | 5 +- .../desktop/DesktopCaptureRefusals.ts | 26 +-- src/application/desktop/DesktopExportFiles.ts | 6 +- .../desktop/DesktopExportInstall.ts | 5 +- src/application/desktop/DesktopOutputTree.ts | 10 +- .../desktop/DesktopRemoteTaskReaders.ts | 11 +- src/application/desktop/DesktopTaskDraft.ts | 5 +- .../desktop/DesktopTaskReaderCleanup.ts | 6 +- .../environment/environmentBuild.ts | 12 +- .../firmware/FirmwareAnalysisService.ts | 6 +- .../frida/FridaInstrumentationService.ts | 41 ++-- src/application/gpu/GpuCodeObjectsService.ts | 11 +- .../il2cpp/Il2cppMetadataService.ts | 12 +- .../ElectronActiveObservationService.ts | 10 +- .../javascript/ElectronObservationService.ts | 14 +- .../javascript/JavaScriptArtifactAnalysis.ts | 16 +- .../JavaScriptRuntimeObservationService.ts | 14 +- .../javascript/SourceToBundleReference.ts | 27 +-- ...StaticObservedEndpointComparisonService.ts | 12 +- src/application/model/ModelArtifactService.ts | 11 +- .../native/NativeFunctionMatchingService.ts | 6 +- src/application/native/NativeValueTrace.ts | 16 +- src/application/ntfs/NtfsJournalService.ts | 9 +- src/application/pcap/PcapAnalysisService.ts | 8 +- src/application/process/ProcessCli.ts | 24 +- .../process/ProcessScenarioPreparation.ts | 30 ++- .../releaseExposure/ReleaseExposureService.ts | 17 +- .../reverse/ReverseEngineeringService.ts | 71 +++--- .../wasm/WasmInterfaceComparisonService.ts | 11 +- 86 files changed, 554 insertions(+), 1012 deletions(-) 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();