[PR #916] [MERGED] refactor(artifacts): isolate JavaScript file acquisition #2344

New issue

Closed

opened 2026-10-16 21:17:34 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:17:34 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/916
Author: @N0zoM1z0
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @morluto

Base: main ← Head: refactor/javascript-artifact-acquisition

📝 Commits (1)

abc5e42 refactor(artifacts): isolate JavaScript file acquisition

📊 Changes

45 files changed (+202 additions, -121 deletions)

View changed files

📝 docs/capability-migration.md (+17 -5)
📝 scripts/lib/module-boundaries.d.mts (+1 -0)
📝 scripts/lib/module-boundaries.mjs (+16 -0)
📝 src/application/ArtifactInventory.ts (+1 -1)
📝 src/application/ArtifactInventory/classify.ts (+1 -1)
📝 src/application/ArtifactInventory/scanCanonical.ts (+1 -1)
📝 src/application/ArtifactInventory/scanReader.ts (+1 -1)
📝 src/application/ArtifactInventory/types.ts (+1 -18)
📝 src/application/javascript/ElectronBoundaryAnalysis.ts (+1 -1)
📝 src/application/javascript/ElectronBoundaryGraphContext.ts (+1 -1)
📝 src/application/javascript/ElectronBoundaryGraphIpc.ts (+1 -1)
📝 src/application/javascript/ElectronBoundaryGraphNative.ts (+1 -1)
📝 src/application/javascript/ElectronBoundaryGraphWindows.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactAnalysis.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactAnalysisTypes.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactGraphBuilder.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactGraphBundlers.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactGraphContext.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactGraphFindings.ts (+1 -1)
📝 src/application/javascript/JavaScriptArtifactGraphStructure.ts (+1 -1)

...and 25 more files

📄 Description

Summary

Move JavaScript artifact byte acquisition into its format adapter while keeping analysis workflows and file facts at their correct layers. This is the traced reader-selection increment in T3/T6/T7 of #740.

Problem and expected behavior

JavaScript reconstruction previously selected concrete ASAR/directory readers and verified nested ASAR containers inside application code. Its graph and semantic-analysis consumers also imported file facts from that acquisition implementation. Format-specific reading should have one adapter owner, while application keeps admission, inventory, analysis and root-reader cleanup.

Change and scope

Move byte acquisition/root and nested ASAR handling to src/artifacts/javascript/.
Extract the exact file facts to src/domain/javascript/javascriptArtifactFiles.ts and immutable inventory snapshot to domain. Preserve the application snapshot type reexport; inventory options and integrity policy remain application-owned.
Move complete-stream hashing and bounded classification-prefix evidence into src/artifacts/ArtifactHash.ts.
Use a narrow ASAR/directory factory returning the existing ArtifactReader. Preserve the original application reconstruction body and its finally close sequence.
Guard the migrated acquisition/hash owner against outward dependencies and JavaScript workflows against concrete ASAR/directory reader imports. Keep the separately owned ZIP/native-DMG/Mach-O selection intact.

Contract and boundary impact

Semantic owner and earliest changed stage: artifact byte acquisition and pure file/snapshot ownership.
CLI and MCP/tool-catalog contract: unchanged named contracts, schemas, outputs and examples.
Provider, bridge, target-format, or platform compatibility: unchanged adapter implementations and support claims; no reader protocol expansion.
Evidence, artifact, provenance, or reconstruction contract: exact declarations, identity algorithms and failure reasons preserved.
Process execution, authorization, cleanup, or containment impact: root and nested ownership/cancellation preserved; no new authority or eager acquisition.
Generated metadata (docs/product-catalog.json), package, or installation impact: generated metadata unchanged; five new compiled owners replace two old ones, with no dependency or installer change.

Evidence and regression coverage

Tests added or updated: migrate existing reader/fact/hash imports and add representative resolved dependency acceptance/rejection cases.
Base reproduction or other evidence: unchanged baseline passes 24 filesystem cases. The new guard reproduces all three original concrete-reader dependency violations. Exact AST comparison preserves extracted declarations, acquisition/hash helpers, root reconstruction lifecycle, factory body and 34 caller bodies/bindings/resolved import owners.
User-visible CLI/MCP output: actual application/artifact CLI/MCP and installed-package workflows validate the existing results and Evidence identities.
Remaining proof gaps: a host-native macOS Interface Builder case skips on Linux; hosted native checks are required before merge. No local real Hopper/Ghidra/IDA or browser-engine execution was performed for this artifact acquisition increment.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run check -- --output-logs=errors-only — all five static gates passed.
npm run docs:check and npm run build:cached — fresh generated checks/build passed; generated outputs unchanged, all five new compiled owners present and both obsolete owners absent.
Exact focused Vitest selection — 377 cases passed in 37 files; one host-native macOS case skipped. Includes content identity, nested ASAR, cancellation, traversal, malformed/UTF-8 data, stream classification, complete inventories, graphs and actual CLI/MCP.
npm run verify:test-discovery — all 529 files discovered once.
npm run verify:package — installed CLI/MCP, configuration backups/recovery, Evidence, lifecycle and update passed; 131 tools and six prompts. Observed startup to tools/list: 2108.24 ms; sampled MCP peak RSS: 423223296 bytes. The final owned-process report contained no descendants, and the generated tarball was cleaned. These are run observations, not comparative performance claims.

Compatibility, safety, and release

Breaking changes or migration steps: internal acquisition/hash and pure data type owners moved; actual callers migrated together. The existing application inventory snapshot type export remains available.
Real Hopper/Ghidra, browser, or OS coverage: actual local Linux format/CLI/MCP workflows. No local proprietary-engine or browser-engine run for this increment; hosted native Linux/macOS x64/arm64 and Windows x64 baselines must pass before merge.
Package or release metadata impact: no dependency/version/installation change. Existing data/error schemas and generated catalogs remain unchanged.
Security, privacy, process, or containment review: exact source/import review and representative boundary rejections passed. Root/nested digest verification, path registry, UTF-8 diagnostics, cancellation and close order retain their original implementations. Heavy local lanes ran serially on two CPUs with reduced priority, one worker and one-GiB heap. No Windows writes or user-GUI mutation.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/916 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `refactor/javascript-artifact-acquisition` --- ### 📝 Commits (1) - [`abc5e42`](https://github.com/morluto/rea/commit/abc5e420e89f47e400206fccf5fd37ac970f1602) refactor(artifacts): isolate JavaScript file acquisition ### 📊 Changes **45 files changed** (+202 additions, -121 deletions) <details> <summary>View changed files</summary> 📝 `docs/capability-migration.md` (+17 -5) 📝 `scripts/lib/module-boundaries.d.mts` (+1 -0) 📝 `scripts/lib/module-boundaries.mjs` (+16 -0) 📝 `src/application/ArtifactInventory.ts` (+1 -1) 📝 `src/application/ArtifactInventory/classify.ts` (+1 -1) 📝 `src/application/ArtifactInventory/scanCanonical.ts` (+1 -1) 📝 `src/application/ArtifactInventory/scanReader.ts` (+1 -1) 📝 `src/application/ArtifactInventory/types.ts` (+1 -18) 📝 `src/application/javascript/ElectronBoundaryAnalysis.ts` (+1 -1) 📝 `src/application/javascript/ElectronBoundaryGraphContext.ts` (+1 -1) 📝 `src/application/javascript/ElectronBoundaryGraphIpc.ts` (+1 -1) 📝 `src/application/javascript/ElectronBoundaryGraphNative.ts` (+1 -1) 📝 `src/application/javascript/ElectronBoundaryGraphWindows.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactAnalysis.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactAnalysisTypes.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactGraphBuilder.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactGraphBundlers.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactGraphContext.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactGraphFindings.ts` (+1 -1) 📝 `src/application/javascript/JavaScriptArtifactGraphStructure.ts` (+1 -1) _...and 25 more files_ </details> ### 📄 Description ## Summary Move JavaScript artifact byte acquisition into its format adapter while keeping analysis workflows and file facts at their correct layers. This is the traced reader-selection increment in T3/T6/T7 of #740. ## Problem and expected behavior JavaScript reconstruction previously selected concrete ASAR/directory readers and verified nested ASAR containers inside application code. Its graph and semantic-analysis consumers also imported file facts from that acquisition implementation. Format-specific reading should have one adapter owner, while application keeps admission, inventory, analysis and root-reader cleanup. ## Change and scope - Move byte acquisition/root and nested ASAR handling to `src/artifacts/javascript/`. - Extract the exact file facts to `src/domain/javascript/javascriptArtifactFiles.ts` and immutable inventory snapshot to domain. Preserve the application snapshot type reexport; inventory options and integrity policy remain application-owned. - Move complete-stream hashing and bounded classification-prefix evidence into `src/artifacts/ArtifactHash.ts`. - Use a narrow ASAR/directory factory returning the existing `ArtifactReader`. Preserve the original application reconstruction body and its `finally` close sequence. - Guard the migrated acquisition/hash owner against outward dependencies and JavaScript workflows against concrete ASAR/directory reader imports. Keep the separately owned ZIP/native-DMG/Mach-O selection intact. ## Contract and boundary impact - Semantic owner and earliest changed stage: artifact byte acquisition and pure file/snapshot ownership. - CLI and MCP/tool-catalog contract: unchanged named contracts, schemas, outputs and examples. - Provider, bridge, target-format, or platform compatibility: unchanged adapter implementations and support claims; no reader protocol expansion. - Evidence, artifact, provenance, or reconstruction contract: exact declarations, identity algorithms and failure reasons preserved. - Process execution, authorization, cleanup, or containment impact: root and nested ownership/cancellation preserved; no new authority or eager acquisition. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: generated metadata unchanged; five new compiled owners replace two old ones, with no dependency or installer change. ## Evidence and regression coverage - Tests added or updated: migrate existing reader/fact/hash imports and add representative resolved dependency acceptance/rejection cases. - Base reproduction or other evidence: unchanged baseline passes 24 filesystem cases. The new guard reproduces all three original concrete-reader dependency violations. Exact AST comparison preserves extracted declarations, acquisition/hash helpers, root reconstruction lifecycle, factory body and 34 caller bodies/bindings/resolved import owners. - User-visible CLI/MCP output: actual application/artifact CLI/MCP and installed-package workflows validate the existing results and Evidence identities. - Remaining proof gaps: a host-native macOS Interface Builder case skips on Linux; hosted native checks are required before merge. No local real Hopper/Ghidra/IDA or browser-engine execution was performed for this artifact acquisition increment. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check -- --output-logs=errors-only` — all five static gates passed. - `npm run docs:check` and `npm run build:cached` — fresh generated checks/build passed; generated outputs unchanged, all five new compiled owners present and both obsolete owners absent. - Exact focused Vitest selection — 377 cases passed in 37 files; one host-native macOS case skipped. Includes content identity, nested ASAR, cancellation, traversal, malformed/UTF-8 data, stream classification, complete inventories, graphs and actual CLI/MCP. - `npm run verify:test-discovery` — all 529 files discovered once. - `npm run verify:package` — installed CLI/MCP, configuration backups/recovery, Evidence, lifecycle and update passed; 131 tools and six prompts. Observed startup to tools/list: 2108.24 ms; sampled MCP peak RSS: 423223296 bytes. The final owned-process report contained no descendants, and the generated tarball was cleaned. These are run observations, not comparative performance claims. ## Compatibility, safety, and release - Breaking changes or migration steps: internal acquisition/hash and pure data type owners moved; actual callers migrated together. The existing application inventory snapshot type export remains available. - Real Hopper/Ghidra, browser, or OS coverage: actual local Linux format/CLI/MCP workflows. No local proprietary-engine or browser-engine run for this increment; hosted native Linux/macOS x64/arm64 and Windows x64 baselines must pass before merge. - Package or release metadata impact: no dependency/version/installation change. Existing data/error schemas and generated catalogs remain unchanged. - Security, privacy, process, or containment review: exact source/import review and representative boundary rejections passed. Root/nested digest verification, path registry, UTF-8 diagnostics, cancellation and close order retain their original implementations. Heavy local lanes ran serially on two CPUs with reduced priority, one worker and one-GiB heap. No Windows writes or user-GUI mutation. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:17:34 +00:00