From 271e3759242be66770fbcaf5f02c74125a5724f8 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 22:03:14 +0800 Subject: [PATCH] refactor(application): read the host from HostPlatform in the remaining application modules (#11124) Scenario planning and plan Evidence take a required platform. Host file operations (target resolution, output trees, Windows spelling lookup, executable checks, native snapshot admission), the Linux distribution read and the process CLI adapter read HOST_PLATFORM explicitly. ByteEntropyService takes an optional platform seam, so its Windows casing test injects win32 instead of stubbing process.platform. src/application no longer reads process.platform or process.arch. --- .../verify/architecture-guard-baselines.json | 15 --------------- src/application/BinaryTargetResolver.ts | 7 +++++-- src/application/LinuxHopper.ts | 4 +++- .../binary/AnalysisSnapshotCache.ts | 3 ++- .../ByteEntropyService.test.ts | 18 +++++++++--------- .../binaryDiagnostics/ByteEntropyService.ts | 5 ++++- .../desktop/DesktopBuildComputers.ts | 3 ++- src/application/desktop/DesktopBuildSolves.ts | 3 ++- src/application/desktop/DesktopOutputTree.ts | 11 ++++++++--- .../environment/environmentBundleWrite.ts | 13 +++++++++---- .../ElectronActiveObservationService.ts | 3 ++- src/application/process/ProcessCli.ts | 7 ++++--- src/application/process/ProcessEvidence.ts | 2 +- .../process/ProcessScenarioPreparation.ts | 4 ++-- .../reverse/ReverseEngineeringService.ts | 3 ++- 15 files changed, 55 insertions(+), 46 deletions(-) diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index ac8a63863a..e2721683dd 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -286,18 +286,6 @@ "src/adb/AdbProvider.ts": 1, "src/apktool/ApktoolConfiguration.ts": 4, "src/apktool/ApktoolProvider.ts": 2, - "src/application/BinaryTargetResolver.ts": 1, - "src/application/binary/AnalysisSnapshotCache.ts": 1, - "src/application/binaryDiagnostics/ByteEntropyService.ts": 1, - "src/application/desktop/DesktopBuildComputers.ts": 1, - "src/application/desktop/DesktopBuildSolves.ts": 1, - "src/application/desktop/DesktopOutputTree.ts": 1, - "src/application/environment/environmentBundleWrite.ts": 1, - "src/application/javascript/ElectronActiveObservationService.ts": 1, - "src/application/process/ProcessCli.ts": 3, - "src/application/process/ProcessEvidence.ts": 1, - "src/application/process/ProcessScenarioPreparation.ts": 1, - "src/application/reverse/ReverseEngineeringService.ts": 1, "src/browser/ChromiumSandbox.ts": 1, "src/browser/ElectronCaptureCleanup.ts": 1, "src/browser/ElectronProcessCleanup.ts": 1, @@ -348,8 +336,6 @@ "src/wasm/WabtArtifactProvider.ts": 1 }, "ambient-host-architecture": { - "src/application/BinaryTargetResolver.ts": 1, - "src/application/LinuxHopper.ts": 1, "src/browser/PlaywrightElectronActiveFuses.ts": 2, "src/evm/EvmoleInterfaceProvider.ts": 2, "src/javascript/recovery/WakaruCommand.ts": 1, @@ -418,7 +404,6 @@ "src/native/pwntools/PwntoolsDecoder.ts": 1 }, "test-host-platform-stub": { - "src/application/binaryDiagnostics/ByteEntropyService.test.ts": 1, "src/browser/ElectronCaptureCleanup.test.ts": 2, "src/browser/PlaywrightElectronActiveProvider.test.ts": 2, "src/browser/PlaywrightScenarioBrowser.test.ts": 3, diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index acae80bbd3..79a0f9cb3e 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { artifactNameForClassification, namedArtifactFormat, @@ -180,7 +181,8 @@ export const parseBinaryTarget = async ( const canonical = await realpath(candidate); stage = "read"; // Windows native admission must inspect the caller-selected reparse components. - const sourcePath = process.platform === "win32" ? candidate : canonical; + const sourcePath = + HOST_PLATFORM.platform === "win32" ? candidate : canonical; throwIfTargetResolutionCancelled(signal); const resolved = await resolveAppBundle(canonical); throwIfTargetResolutionCancelled(signal); @@ -302,7 +304,8 @@ const readOpenedBinaryTarget = async ( ...bundle, sha256: await sha256Handle(source, path, signal), }); - const hostArchitecture = options.hostArchitecture ?? process.arch; + const hostArchitecture = + options.hostArchitecture ?? HOST_PLATFORM.architecture; const { targetKind, formatHint, signal, architecture, entryPoint } = options; throwIfTargetResolutionCancelled(signal); // Flash inputs pair with one format; check before any hint branch. diff --git a/src/application/LinuxHopper.ts b/src/application/LinuxHopper.ts index 7392b28903..0eb5604590 100644 --- a/src/application/LinuxHopper.ts +++ b/src/application/LinuxHopper.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { isAborted } from "../domain/analysisErrorCore.js"; import { appendCallerPath } from "../filesystem/callerPath.js"; import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js"; @@ -608,7 +609,8 @@ export const systemLinuxHopperPublisher = ( environment, // Only the package family is read here; it does not depend on the // architecture that gates automated setup. - async () => (await readLinuxDistribution(process.arch))?.packageFamily, + async () => + (await readLinuxDistribution(HOST_PLATFORM.architecture))?.packageFamily, ); /** Read-only authentication; persistent package retention belongs to approved setup. */ diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts index 88156bffc1..c46efd47f6 100644 --- a/src/application/binary/AnalysisSnapshotCache.ts +++ b/src/application/binary/AnalysisSnapshotCache.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js"; import type { JsonValue } from "../../domain/jsonValue.js"; @@ -170,7 +171,7 @@ export const isSnapshotCacheable = ( /** Windows Ghidra must admit the selected source through its native snapshot owner. */ export const requiresNativeSourceAdmissionBeforeReplay = ( providerId: string | undefined, -): boolean => process.platform === "win32" && providerId === "ghidra"; +): boolean => HOST_PLATFORM.platform === "win32" && providerId === "ghidra"; /** Limitation that marks every observation replayed from a snapshot. */ const SNAPSHOT_REPLAY_LIMITATION = diff --git a/src/application/binaryDiagnostics/ByteEntropyService.test.ts b/src/application/binaryDiagnostics/ByteEntropyService.test.ts index 0d0ed6d371..e9187ef579 100644 --- a/src/application/binaryDiagnostics/ByteEntropyService.test.ts +++ b/src/application/binaryDiagnostics/ByteEntropyService.test.ts @@ -628,14 +628,15 @@ it("reads an admitted file even when Windows casing lookup is unavailable", asyn // The injected descriptor represents a readable share while the optional // host spelling lookup has no path on this filesystem. const selected = join(root, "share-selection.bin"); - const platform = vi - .spyOn(process, "platform", "get") - .mockReturnValue("win32"); - const service = new ByteEntropyService({ - stat: ((...args: Parameters) => - stat(path, args[1])) as typeof stat, - open: async () => open(path, "r"), - }); + const service = new ByteEntropyService( + { + stat: ((...args: Parameters) => + stat(path, args[1])) as typeof stat, + open: async () => open(path, "r"), + }, + undefined, + "win32", + ); try { const result = await service.inspect({ path: selected }); if (!result.ok) throw result.error; @@ -645,6 +646,5 @@ it("reads an admitted file even when Windows casing lookup is unavailable", asyn expect(result.value.caller_input_path).toBe(selected); } finally { await service.close(); - platform.mockRestore(); } }); diff --git a/src/application/binaryDiagnostics/ByteEntropyService.ts b/src/application/binaryDiagnostics/ByteEntropyService.ts index 359f1daf31..79106bcd0f 100644 --- a/src/application/binaryDiagnostics/ByteEntropyService.ts +++ b/src/application/binaryDiagnostics/ByteEntropyService.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { absoluteCallerPath } from "../../filesystem/callerPath.js"; import { createHash } from "node:crypto"; import { constants } from "node:fs"; @@ -67,6 +68,8 @@ export class ByteEntropyService { "open" | "stat" > = { open, stat }, resources: ArtifactResourceScope = new ArtifactResourceScope(), + // The selected path is read on this host unless a caller selects one. + private readonly platform: NodeJS.Platform = HOST_PLATFORM.platform, ) { this.#resources = resources; } @@ -189,7 +192,7 @@ export class ByteEntropyService { admitted = true; // Only an admitted selected file may consult filesystem spelling. Do not // replace symlink/junction/8.3 aliases or touch source-derived paths. - if (process.platform === "win32") { + if (this.platform === "win32") { const canonical = await realpath(input.path).catch(() => undefined); assertArtifactReadActive(options?.signal); if (canonical?.toLowerCase() === input.path.toLowerCase()) diff --git a/src/application/desktop/DesktopBuildComputers.ts b/src/application/desktop/DesktopBuildComputers.ts index 579592c463..bf0ae6152f 100644 --- a/src/application/desktop/DesktopBuildComputers.ts +++ b/src/application/desktop/DesktopBuildComputers.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { randomUUID } from "node:crypto"; import { @@ -705,7 +706,7 @@ export class DesktopBuildComputers { if (!settings.ok) return settings; const environment = await resolveBuildComputerEnvironment( this.environment, - process.platform, + HOST_PLATFORM.platform, this.defaults, ); return ok({ ...environment, ...settings.value }); diff --git a/src/application/desktop/DesktopBuildSolves.ts b/src/application/desktop/DesktopBuildSolves.ts index a2083b4db3..4f8521bae6 100644 --- a/src/application/desktop/DesktopBuildSolves.ts +++ b/src/application/desktop/DesktopBuildSolves.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { parsePortableBundleName, PORTABLE_BUNDLE_NAME_CONSTRAINT, @@ -440,7 +441,7 @@ export const measureInFreshComputers = async ( if (!taskName.ok) return taskName; const environment = await resolveBuildComputerEnvironment( host.environment, - process.platform, + HOST_PLATFORM.platform, host.defaults, ); return measureBuildTask( diff --git a/src/application/desktop/DesktopOutputTree.ts b/src/application/desktop/DesktopOutputTree.ts index d17cf09e3e..ead9ed8ab6 100644 --- a/src/application/desktop/DesktopOutputTree.ts +++ b/src/application/desktop/DesktopOutputTree.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { lstat, mkdir, readdir } from "node:fs/promises"; import { basename, dirname, isAbsolute } from "node:path"; @@ -122,9 +123,13 @@ export const writeOutputTree = async ( | { readonly kind: "failed"; readonly cause: unknown }; try { try { - tree = await SafeOutputTree.create(plan.physical, process.platform, { - acceptExistingEmpty: true, - }); + tree = await SafeOutputTree.create( + plan.physical, + HOST_PLATFORM.platform, + { + acceptExistingEmpty: true, + }, + ); } catch (cause: unknown) { if (cause instanceof SafeOutputTreeCreationFailure) tree = cause.tree; throw cause; diff --git a/src/application/environment/environmentBundleWrite.ts b/src/application/environment/environmentBundleWrite.ts index e9d640ab38..3d580d41a5 100644 --- a/src/application/environment/environmentBundleWrite.ts +++ b/src/application/environment/environmentBundleWrite.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { createHash } from "node:crypto"; import type { FileHandle } from "node:fs/promises"; import { join } from "node:path"; @@ -169,10 +170,14 @@ const writeBundleFiles = async ( | { readonly kind: "failed"; readonly cause: unknown }; try { try { - tree = await SafeOutputTree.create(input.directory, process.platform, { - acceptExistingEmpty: input.exclusiveDestination !== true, - createParents: input.exclusiveDestination !== true, - }); + tree = await SafeOutputTree.create( + input.directory, + HOST_PLATFORM.platform, + { + acceptExistingEmpty: input.exclusiveDestination !== true, + createParents: input.exclusiveDestination !== true, + }, + ); } catch (cause: unknown) { if (cause instanceof SafeOutputTreeCreationFailure) tree = cause.tree; throw cause; diff --git a/src/application/javascript/ElectronActiveObservationService.ts b/src/application/javascript/ElectronActiveObservationService.ts index 6d0d6fedfa..9bf43f4620 100644 --- a/src/application/javascript/ElectronActiveObservationService.ts +++ b/src/application/javascript/ElectronActiveObservationService.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { dirname } from "node:path"; import { constants, type Stats } from "node:fs"; import { access, realpath, stat } from "node:fs/promises"; @@ -118,7 +119,7 @@ const resolveExecutablePath = async ( } if (!metadata.isFile()) return err(notExecutable(selected, new Error("not a regular file"))); - if (process.platform !== "win32") + if (HOST_PLATFORM.platform !== "win32") try { await access(resolved.value, constants.X_OK); } catch (cause: unknown) { diff --git a/src/application/process/ProcessCli.ts b/src/application/process/ProcessCli.ts index 3faa78f3bd..b500c69161 100644 --- a/src/application/process/ProcessCli.ts +++ b/src/application/process/ProcessCli.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../../domain/result.js"; import { analysisErrorWithCleanupDependencies } from "../../domain/analysisErrorCleanup.js"; @@ -119,13 +120,13 @@ export const captureProcessScenarioFile = async ( const prepared = await prepareProcessScenarioPlan( parsed.data, environment, - process.platform, + HOST_PLATFORM.platform, signal, ); if (!prepared.ok) throw prepared.error; return createProcessScenarioPlanEvidence( prepared.value, - process.platform, + HOST_PLATFORM.platform, ); } const progress = createProgressReporter( @@ -140,7 +141,7 @@ export const captureProcessScenarioFile = async ( const captured = await captureProcessScenario( parsed.data, signal, - process.platform, + HOST_PLATFORM.platform, environment, undefined, undefined, diff --git a/src/application/process/ProcessEvidence.ts b/src/application/process/ProcessEvidence.ts index ec3361872c..d0b00656ac 100644 --- a/src/application/process/ProcessEvidence.ts +++ b/src/application/process/ProcessEvidence.ts @@ -129,7 +129,7 @@ export const createProcessCaptureEvidence = ( /** Create one canonical planned-scenario Evidence record without observing a process. */ export const createProcessScenarioPlanEvidence = ( scenario: Omit, - platform: ProcessCapture["manifest"]["platform"] = process.platform, + platform: ProcessCapture["manifest"]["platform"], ) => { const plan = processScenarioPlanSchema.parse({ status: "planned", diff --git a/src/application/process/ProcessScenarioPreparation.ts b/src/application/process/ProcessScenarioPreparation.ts index fd4786d435..7a9e592e60 100644 --- a/src/application/process/ProcessScenarioPreparation.ts +++ b/src/application/process/ProcessScenarioPreparation.ts @@ -22,8 +22,8 @@ export type ResolvedProcessScenario = Omit; */ export const prepareProcessScenarioPlan = async ( scenario: ProcessScenario, - environment: Readonly> = process.env, - platform: NodeJS.Platform = process.platform, + environment: Readonly>, + platform: NodeJS.Platform, signal?: AbortSignal, ): Promise> => { if (signal?.aborted === true) diff --git a/src/application/reverse/ReverseEngineeringService.ts b/src/application/reverse/ReverseEngineeringService.ts index b9a73e4d3f..6abbb9f81f 100644 --- a/src/application/reverse/ReverseEngineeringService.ts +++ b/src/application/reverse/ReverseEngineeringService.ts @@ -1,3 +1,4 @@ +import { HOST_PLATFORM } from "../../platform/HostPlatform.js"; import { MAX_NODE_TIMER_DELAY_MS } from "../../domain/analysisResourceLimits.js"; import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; import { bindArtifactFileCleanup } from "../../artifacts/ArtifactFileOperation.js"; @@ -831,7 +832,7 @@ export class ReverseEngineeringService { typeof rawSystemCode === "string" ? rawSystemCode : undefined; const recovery = processOwnershipAdmissionRecovery( admissionFailure.code, - systemProcessOwnershipHost.platform ?? process.platform, + systemProcessOwnershipHost.platform ?? HOST_PLATFORM.platform, admissionSystemCode, ); earlyFailure = new AnalysisCapabilityUnavailableError(