From e4f140417ec7005e6d23d803caaad2126f1e536a Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 06:10:25 +0800 Subject: [PATCH] refactor(resources): move the ASAR header reader into src/resources and its node schema into domain (#11526) --- scripts/lib/module-layers.baseline.json | 2 +- scripts/verify/architecture-guards.mjs | 4 ++++ scripts/verify/baselines/budget-arithmetic.json | 4 ++-- scripts/verify/baselines/parser-json-parse.json | 2 +- scripts/verify/baselines/raw-buffer-read.json | 2 +- src/artifacts/ArtifactClassificationProbe.ts | 8 ++++---- src/artifacts/AsarArtifactReader.ts | 6 ++---- src/artifacts/AsarListing.ts | 2 +- src/artifacts/ReleaseExposureReader.ts | 6 ++---- src/artifacts/extraction/ArtifactExtraction.ts | 2 +- .../inventory/ArtifactGraphConstruction.test.ts | 2 +- src/artifacts/inventory/ArtifactGraphConstruction.ts | 6 ++++-- src/browser/ElectronFileScope.ts | 8 +++----- src/{artifacts/AsarNode.ts => domain/asarNode.ts} | 0 src/{artifacts => resources}/AsarHeader.test.ts | 2 +- src/{artifacts => resources}/AsarHeader.ts | 6 ++---- src/resources/index.ts | 12 ++++++++++++ .../boundary/filesystem/asarHeaderAdmission.test.ts | 8 ++++---- .../boundary/filesystem/asarListingAdmission.test.ts | 2 +- tests/fixtures/artifactClassification.ts | 2 +- 20 files changed, 48 insertions(+), 38 deletions(-) rename src/{artifacts/AsarNode.ts => domain/asarNode.ts} (100%) rename src/{artifacts => resources}/AsarHeader.test.ts (100%) rename src/{artifacts => resources}/AsarHeader.ts (99%) diff --git a/scripts/lib/module-layers.baseline.json b/scripts/lib/module-layers.baseline.json index c58df70edf..67f20e9dec 100644 --- a/scripts/lib/module-layers.baseline.json +++ b/scripts/lib/module-layers.baseline.json @@ -16,7 +16,7 @@ "apktool -> artifacts": 2, "artifacts -> dotnet": 3, "artifacts -> native": 1, - "browser -> artifacts": 4, + "browser -> artifacts": 2, "captures -> pcap": 2, "desktop -> browser": 1, "desktop -> electron": 1, diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 5d401b8e88..4e105e4dc2 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -554,6 +554,8 @@ const PARSER_FOLDERS = [ "src/model/", "src/native/", "src/python/", + // Shared artifact readers (ZIP, directory, ASAR header) live in resources. + "src/resources/", "src/rust/", "src/v8/", "src/wasm/", @@ -572,11 +574,13 @@ const PARSER_FOLDERS = [ "managed", "model", "native", + "pcap", "python", "rust", "v8", "wasm", "windows", + "zip", ].map((folder) => `src/domain/${folder}/`), ]; const parserFiles = files.filter((file) => diff --git a/scripts/verify/baselines/budget-arithmetic.json b/scripts/verify/baselines/budget-arithmetic.json index 9729d605f2..85fd864a38 100644 --- a/scripts/verify/baselines/budget-arithmetic.json +++ b/scripts/verify/baselines/budget-arithmetic.json @@ -1,6 +1,6 @@ { - "src/artifacts/AsarHeader.ts": 1, "src/kuna/KunaJsonStream.ts": 1, "src/process/BoundedOutputExcerpt.ts": 1, - "src/process/ProviderProcess.ts": 1 + "src/process/ProviderProcess.ts": 1, + "src/resources/AsarHeader.ts": 1 } diff --git a/scripts/verify/baselines/parser-json-parse.json b/scripts/verify/baselines/parser-json-parse.json index 605fb05ac7..4bee57a0c0 100644 --- a/scripts/verify/baselines/parser-json-parse.json +++ b/scripts/verify/baselines/parser-json-parse.json @@ -1,7 +1,6 @@ { "src/android/JadxProtocol.ts": 2, "src/android/JadxWorkspaceRoot.ts": 1, - "src/artifacts/AsarHeader.ts": 1, "src/artifacts/ReleaseExposureReader.ts": 1, "src/artifacts/apple/AppleAssetCatalogAnalysis.ts": 1, "src/artifacts/deno/DenoSectionLayout.ts": 1, @@ -13,5 +12,6 @@ "src/native/LldbRetainedObservations.ts": 1, "src/native/apple/losslessJson.ts": 1, "src/native/parsers/plist.ts": 1, + "src/resources/AsarHeader.ts": 1, "src/rust/RustAuditableReader.ts": 1 } diff --git a/scripts/verify/baselines/raw-buffer-read.json b/scripts/verify/baselines/raw-buffer-read.json index 0e327c10b1..31da08ce3f 100644 --- a/scripts/verify/baselines/raw-buffer-read.json +++ b/scripts/verify/baselines/raw-buffer-read.json @@ -2,7 +2,6 @@ "src/application/BinaryTargetResolver.ts": 1, "src/application/MipsElfMetadata.ts": 10, "src/application/MipsGnuAttributes.ts": 2, - "src/artifacts/AsarHeader.ts": 4, "src/artifacts/DesktopFileInspection.ts": 4, "src/artifacts/FitArtifactReader.ts": 1, "src/artifacts/GodotPckArtifactReader.ts": 6, @@ -131,5 +130,6 @@ "src/native/pwntools/RecordedCrashSourceBindings.ts": 6, "src/native/windows/WindowsShortcutParser.ts": 49, "src/pcap/PcapDnsWire.ts": 5, + "src/resources/AsarHeader.ts": 4, "src/v8/V8CodeCacheParser.ts": 1 } diff --git a/src/artifacts/ArtifactClassificationProbe.ts b/src/artifacts/ArtifactClassificationProbe.ts index 582e221315..a9896b8180 100644 --- a/src/artifacts/ArtifactClassificationProbe.ts +++ b/src/artifacts/ArtifactClassificationProbe.ts @@ -1,8 +1,4 @@ import type { AsarHeaderAdmission } from "../config/asarHeaderAdmission.js"; -import { - createAsarHeaderSignatureProbe, - type FinalAsarHeaderProbeObservation, -} from "./AsarHeader.js"; import { createXmlPlistSignatureProbe, MAX_XML_PLIST_PROBE_BYTES, @@ -20,6 +16,10 @@ import { type MzWindowsHeaderSignatureEvidence, } from "../domain/dosMz.js"; import { DFUSE_SUFFIX_BYTES } from "../domain/firmware/dfuse.js"; +import { + createAsarHeaderSignatureProbe, + type FinalAsarHeaderProbeObservation, +} from "../resources/index.js"; /** Initial bytes required by the other bounded format classifiers. */ export const ARTIFACT_CLASSIFICATION_PREFIX_BYTES = 8_192; diff --git a/src/artifacts/AsarArtifactReader.ts b/src/artifacts/AsarArtifactReader.ts index 725855d7e5..6675832d34 100644 --- a/src/artifacts/AsarArtifactReader.ts +++ b/src/artifacts/AsarArtifactReader.ts @@ -26,13 +26,11 @@ import { type ArtifactReader, type ArtifactTraversalOptions, readArtifactFileChunks, -} from "../resources/index.js"; -import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js"; -import { admitAsarHeader, readAsarHeader, type AsarHeaderExtents, -} from "./AsarHeader.js"; +} from "../resources/index.js"; +import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js"; import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; import type { FileHandleChunkStream } from "../filesystem/readFileHandleChunks.js"; import { diff --git a/src/artifacts/AsarListing.ts b/src/artifacts/AsarListing.ts index 2399c77321..7b971f4f9f 100644 --- a/src/artifacts/AsarListing.ts +++ b/src/artifacts/AsarListing.ts @@ -2,7 +2,7 @@ import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { setImmediate } from "node:timers/promises"; import { z } from "zod"; -import { asarDeclaredSizeSchema, asarNodeSchema } from "./AsarNode.js"; +import { asarDeclaredSizeSchema, asarNodeSchema } from "../domain/asarNode.js"; import { ArtifactReaderFailure, type ArtifactEntry, diff --git a/src/artifacts/ReleaseExposureReader.ts b/src/artifacts/ReleaseExposureReader.ts index 6160045466..5c3ca5a567 100644 --- a/src/artifacts/ReleaseExposureReader.ts +++ b/src/artifacts/ReleaseExposureReader.ts @@ -35,6 +35,8 @@ import { hashStableRootArtifactHandle, openRootArtifact, releaseRootArtifact, + asarHeaderAdmissionRecovery, + createAsarHeaderSignatureProbe, } from "../resources/index.js"; import { decodeBinaryPlistText } from "../domain/apple/binaryPlistMaterializer.js"; import { @@ -42,10 +44,6 @@ import { invariantViolation, } from "../domain/internalInvariant.js"; import { ArtifactEmbeddedFormatProbes } from "./ArtifactEmbeddedFormatProbes.js"; -import { - asarHeaderAdmissionRecovery, - createAsarHeaderSignatureProbe, -} from "./AsarHeader.js"; import { DEFAULT_ASAR_HEADER_ADMISSION, type AsarHeaderAdmission, diff --git a/src/artifacts/extraction/ArtifactExtraction.ts b/src/artifacts/extraction/ArtifactExtraction.ts index 25c1a171ad..31ad22371e 100644 --- a/src/artifacts/extraction/ArtifactExtraction.ts +++ b/src/artifacts/extraction/ArtifactExtraction.ts @@ -24,13 +24,13 @@ import { SafeOutputTree, SafeOutputTreeCreationFailure, assertArtifactFileSelectedSource, + resolveAsarHeaderAdmission, } from "../../resources/index.js"; import { absoluteCallerPath } from "../../filesystem/callerPath.js"; import type { AsarHeaderAdmission } from "../../config/asarHeaderAdmission.js"; import type { EspFlashSelection } from "../../domain/firmware/espFlashLocation.js"; import { artifactFormatDescriptor } from "../artifactFormats.js"; import { createArtifactReader } from "../createArtifactReader.js"; -import { resolveAsarHeaderAdmission } from "../AsarHeader.js"; import { ArtifactEmbeddedFormatProbes, type ArtifactEmbeddedFormatProbeFacts, diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts index aa74d97267..7f6879ead4 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts @@ -14,7 +14,6 @@ import { resolveOccurrenceParents, } from "./ArtifactGraphConstruction.js"; import { createArtifactClassificationProbe } from "../ArtifactClassificationProbe.js"; -import { createAsarHeaderSignatureProbe } from "../AsarHeader.js"; import { ArtifactReaderFailure } from "../../resources/ArtifactReader.js"; import { translateArtifactFailure } from "../ArtifactOperationFailure.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; @@ -43,6 +42,7 @@ import { } from "../../../tests/fixtures/espImage.js"; import { devicetreeFixture } from "../../domain/firmware/devicetree.fixture.js"; import { fitFixture } from "../fit/FitImage.fixture.js"; +import { createAsarHeaderSignatureProbe } from "../../resources/index.js"; it("joins only observed PE signature bytes across stream chunks", () => { const bytes = pe(0x8664, 8190); diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.ts index 7424527c15..52d6072faf 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.ts @@ -1,8 +1,10 @@ import { artifactFormatDescriptor } from "../artifactFormats.js"; import { recognizeArtifactFormat } from "../../domain/artifactFormatRecognition.js"; import type { ArtifactClassificationEvidence } from "../ArtifactClassificationProbe.js"; -import { asarHeaderAdmissionFailure } from "../AsarHeader.js"; -import { hasDestinationPath } from "../../resources/index.js"; +import { + hasDestinationPath, + asarHeaderAdmissionFailure, +} from "../../resources/index.js"; import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js"; import { isJavaScriptSourcePath } from "../../domain/javascript/javascriptArtifactFiles.js"; import { digestCanonicalValue } from "../../domain/canonicalDigest.js"; diff --git a/src/browser/ElectronFileScope.ts b/src/browser/ElectronFileScope.ts index 9b51c86061..89820e6171 100644 --- a/src/browser/ElectronFileScope.ts +++ b/src/browser/ElectronFileScope.ts @@ -15,18 +15,16 @@ import { withArtifactFileHandle, ArtifactReaderFailure, ArtifactResourceScope, + admitAsarHeader, + asarHeaderAdmissionFailure, } from "../resources/index.js"; -import { asarNodeSchema } from "../artifacts/AsarNode.js"; +import { asarNodeSchema } from "../domain/asarNode.js"; import { regularFileState, sameRegularFileState, type RegularFileState, } from "../filesystem/RegularFile.js"; -import { - admitAsarHeader, - asarHeaderAdmissionFailure, -} from "../artifacts/AsarHeader.js"; import { DEFAULT_ASAR_HEADER_ADMISSION, type AsarHeaderAdmission, diff --git a/src/artifacts/AsarNode.ts b/src/domain/asarNode.ts similarity index 100% rename from src/artifacts/AsarNode.ts rename to src/domain/asarNode.ts diff --git a/src/artifacts/AsarHeader.test.ts b/src/resources/AsarHeader.test.ts similarity index 100% rename from src/artifacts/AsarHeader.test.ts rename to src/resources/AsarHeader.test.ts index 673ca50efa..1059e82c9d 100644 --- a/src/artifacts/AsarHeader.test.ts +++ b/src/resources/AsarHeader.test.ts @@ -2,12 +2,12 @@ import type { FileHandle } from "node:fs/promises"; import type { Stats } from "node:fs"; import { expect, it, vi } from "vitest"; +import { asarHeaderBytes } from "../../tests/fixtures/asarHeader.js"; import { admitAsarHeader, readAsarHeader, createAsarHeaderSignatureProbe, } from "./AsarHeader.js"; -import { asarHeaderBytes } from "../../tests/fixtures/asarHeader.js"; const makeArchive = (): Buffer => asarHeaderBytes(' \t\r\n{"files":{}} '); diff --git a/src/artifacts/AsarHeader.ts b/src/resources/AsarHeader.ts similarity index 99% rename from src/artifacts/AsarHeader.ts rename to src/resources/AsarHeader.ts index 4f259b4809..421e3ac7ef 100644 --- a/src/artifacts/AsarHeader.ts +++ b/src/resources/AsarHeader.ts @@ -3,10 +3,8 @@ import type { FileHandle } from "node:fs/promises"; import { readFileHandleRange } from "../filesystem/readFileHandleRange.js"; import { findDuplicateJsonMember } from "../domain/jsonDuplicateMember.js"; -import { - assertArtifactReadActive, - ArtifactReaderFailure, -} from "../resources/index.js"; +import { assertArtifactReadActive } from "./ArtifactFileOperation.js"; +import { ArtifactReaderFailure } from "./ArtifactReader.js"; import { err, ok, type Result } from "../domain/result.js"; import { ASAR_HEADER_ADMISSION_SETTING, diff --git a/src/resources/index.ts b/src/resources/index.ts index 7a7e736f5d..77fc43532c 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -4,6 +4,18 @@ * counts any other import as an import past the entry file. Export a name * here when a new outside use needs it. */ +export { + admitAsarHeader, + asarHeaderAdmissionFailure, + asarHeaderAdmissionRecovery, + createAsarHeaderSignatureProbe, + readAsarHeader, + resolveAsarHeaderAdmission, +} from "./AsarHeader.js"; +export type { + AsarHeaderExtents, + FinalAsarHeaderProbeObservation, +} from "./AsarHeader.js"; export { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, diff --git a/tests/boundary/filesystem/asarHeaderAdmission.test.ts b/tests/boundary/filesystem/asarHeaderAdmission.test.ts index f4137e1726..0f599051e1 100644 --- a/tests/boundary/filesystem/asarHeaderAdmission.test.ts +++ b/tests/boundary/filesystem/asarHeaderAdmission.test.ts @@ -6,10 +6,6 @@ import { afterEach, expect, it, vi } from "vitest"; import { translateArtifactFailure } from "../../../src/artifacts/ArtifactOperationFailure.js"; import { ArtifactReaderFailure } from "../../../src/resources/ArtifactReader.js"; -import { - admitAsarHeader, - asarHeaderAdmissionRecovery, -} from "../../../src/artifacts/AsarHeader.js"; import { parseEnvironment } from "../../../src/config/environment.js"; import { createDirectAnalysis } from "../../../src/composition/directAnalysis.js"; import { @@ -26,6 +22,10 @@ import { projectAnalysisError } from "../../../src/domain/analysisErrorProjectio import { inventoryArtifact } from "../../fixtures/artifactInventory.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { analyzeJavaScriptApplication } from "../../support/javascriptApplicationScope.js"; +import { + admitAsarHeader, + asarHeaderAdmissionRecovery, +} from "../../../src/resources/index.js"; const createFixture = async () => { const root = await createTestTempDirectory("rea-asar-header-admission-"); diff --git a/tests/boundary/filesystem/asarListingAdmission.test.ts b/tests/boundary/filesystem/asarListingAdmission.test.ts index f1d350d589..1848b8e16f 100644 --- a/tests/boundary/filesystem/asarListingAdmission.test.ts +++ b/tests/boundary/filesystem/asarListingAdmission.test.ts @@ -10,7 +10,6 @@ import { BLOCK_INTEGRITY_LIMITATION, readAsarListing, } from "../../../src/artifacts/AsarListing.js"; -import { resolveAsarHeaderAdmission } from "../../../src/artifacts/AsarHeader.js"; import { asarHeaderBytes, nestedAsarHeader, @@ -19,6 +18,7 @@ import { inventoryArtifact } from "../../fixtures/artifactInventory.js"; import { ArtifactResourceScope } from "../../../src/resources/ArtifactResourceScope.js"; import { extractArtifact } from "../../../src/artifacts/extraction/ArtifactExtraction.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { resolveAsarHeaderAdmission } from "../../../src/resources/index.js"; const archiveWith = async (bytes: Buffer) => { const root = await createTestTempDirectory("rea-asar-listing-"); diff --git a/tests/fixtures/artifactClassification.ts b/tests/fixtures/artifactClassification.ts index abeea2d7ff..5cbd6082ad 100644 --- a/tests/fixtures/artifactClassification.ts +++ b/tests/fixtures/artifactClassification.ts @@ -1,5 +1,5 @@ -import { createAsarHeaderSignatureProbe } from "../../src/artifacts/AsarHeader.js"; import { classifyArtifactContent } from "../../src/artifacts/inventory/ArtifactGraphConstruction.js"; +import { createAsarHeaderSignatureProbe } from "../../src/resources/index.js"; /** Observe a supplied byte prefix before assigning an inventory path role. */ export const classifyArtifactBytesAtPath = (