[PR #6149] [MERGED] fix(javascript): preserve source-map preparation capability errors #7164

New issue

Closed

opened 2026-11-01 21:45:50 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:45:50 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6149
Author: @diyasharma05
Created: 10/21/2026
Status: ✅ Merged
Merged: 10/21/2026
Merged by: @morluto

Base: main ← Head: fix/source-map-preparation-capability

📝 Commits (1)

653a29f fix(javascript): preserve source-map preparation capability errors

📊 Changes

3 files changed (+141 additions, -9 deletions)

View changed files

📝 src/javascript/sourceMaps/SourceMapCommand.ts (+10 -8)
➕ tests/boundary/javascript/sourceMapPreparation.test.ts (+74 -0)
📝 tests/boundary/mcp/webSourceLocationMcp.test.ts (+57 -1)

📄 Description

Summary

Fixes #6082.

When Linux cannot find a usable ps, source-map tracing reports a generic decoder failure. This preserves the existing prerequisite error so CLI and MCP callers get capability_unavailable and the advice to provide a procps-compatible ps on REA's PATH.

Problem and expected behavior

Ownership preparation already produces the right typed error. runSourceMapCommand was wrapping it in ProviderAdapterError, losing its public classification and recovery advice.

The corrected response includes:

{
  "code": "capability_unavailable",
  "category": "unsupported_provider",
  "retryable": false,
  "details": {
    "provider_id": "process-ownership",
    "operation": "prepare_owned_process"
  }
}

Change and scope

Return an existing AnalysisError unchanged from the preparation catch. Caller cancellation still takes priority; unexpected exceptions keep the existing adapter diagnostics.

Contract and boundary impact

Semantic owner and earliest changed stage: source-map ownership preparation, before runtime creation or codec launch.
Contribution scope / maintainer decision: ordinary fix within existing boundaries; advance scope decision not applicable.
CLI and MCP/tool catalog: corrected error classification through the shared projection; schemas and tool catalog unchanged.
Platform compatibility: the reported prerequisite failure is Linux-specific; typed-error preservation uses the existing shared contract.
Evidence and provenance: preserves the original error and producer details; successful Evidence is unchanged.
Authority and cleanup: existing admission remains required. No new execution authority or cleanup owner; cancellation reasons remain opaque.
Generated metadata, dependencies, package, installation: no changes.

Expected effects of the existing workflow (unchanged by this fix):

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

The checked execution/write effects are the existing trusted codec and its private runtime files. Preparation failure returns before either is acquired.

Evidence and regression coverage

Added an MCP regression using real Linux ownership preparation with an empty PATH. It checks the error, remediation, repeated calls, a working ping, and no runtime/codec acquisition.
Added two cancellation cases (null and a caller-owned cleanup error) and an unexpected-error case preserving diagnostics.
On Linux, removing just the new branch made the MCP regression fail with execution_failure instead of capability_unavailable. Restoring it passed all five tests in the two changed test files; source bytes and Git status were verified afterward.
Executed 11 real CLI/stdio MCP negative scenarios: missing, non-executable, incompatible, empty-output and malformed-output ps; invalid JSON/UTF-8, missing, directory and oversized maps; unsupported external section. All preserved CLI/MCP error parity, answered ping, and succeeded after repair on the same MCP connection. These were manual checks with generated local fixtures, not new committed tests.
Real CLI and stdio MCP success responses matched. With an empty PATH, both returned the error above and the original ENOENT reason with procps guidance.

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

Node 24.18.0 / npm 11.16.0, commit 653a29f824469ffffa84165a15c25c61eabc9973:

npm run check and npm run check:fast: passed on Windows; lint retains existing warnings.
npm run verify:test-discovery: passed, all 1940 test files discovered once.
npm run verify:windows-native:artifact: passed using the matching published 6.7.0 x64 helper.
Focused suite below: Linux (Ubuntu WSL2) 115 passed; Windows 112 passed, 3 failed. All added cases passed on both hosts.

The three Windows failures concern exit-vs-cancellation ordering, late output limits, and memory-limit precedence in SourceMapCommand.test.ts. Substituting the exact production file from base 3220e17b8bd046ad1be8fbb2e4070d8ddc37ad64 reproduced the same three failures. The committed file was restored and verified unchanged afterward.

Focused test command

npm run test:focused -- \
  src/javascript/sourceMaps/SourceMapCommand.test.ts \
  src/javascript/sourceMaps/SourceMapDecoder.test.ts \
  tests/boundary/javascript/sourceMapDecoder.test.ts \
  tests/boundary/javascript/sourceMapRuntimeAvailability.test.ts \
  tests/boundary/javascript/sourceMapPreparation.test.ts \
  tests/boundary/mcp/webSourceLocationMcp.test.ts \
  tests/acceptance/webSourceLocationCli.test.ts \
  src/application/WebSourceLocationService.test.ts \
  src/domain/analysisErrorProjection.test.ts \
  tests/boundary/filesystem/webSourceLocationArtifacts.test.ts

Compatibility, safety, and release

No breaking schema change, migration, dependency, or release metadata change.
Coverage: Linux source-map workflow and Windows tests above. macOS, live browsers, Hopper, Ghidra, and IDA were not exercised; this fix changes none of their adapters.
Source review found no new process authority, credential handling, or network access.

Author readiness

Human owner: @diyasharma05

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
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/6149 **Author:** [@diyasharma05](https://github.com/diyasharma05) **Created:** 10/21/2026 **Status:** ✅ Merged **Merged:** 10/21/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/source-map-preparation-capability` --- ### 📝 Commits (1) - [`653a29f`](https://github.com/morluto/rea/commit/653a29f824469ffffa84165a15c25c61eabc9973) fix(javascript): preserve source-map preparation capability errors ### 📊 Changes **3 files changed** (+141 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `src/javascript/sourceMaps/SourceMapCommand.ts` (+10 -8) ➕ `tests/boundary/javascript/sourceMapPreparation.test.ts` (+74 -0) 📝 `tests/boundary/mcp/webSourceLocationMcp.test.ts` (+57 -1) </details> ### 📄 Description ## Summary Fixes #6082. When Linux cannot find a usable `ps`, source-map tracing reports a generic decoder failure. This preserves the existing prerequisite error so CLI and MCP callers get `capability_unavailable` and the advice to provide a procps-compatible `ps` on REA's PATH. ## Problem and expected behavior Ownership preparation already produces the right typed error. `runSourceMapCommand` was wrapping it in `ProviderAdapterError`, losing its public classification and recovery advice. The corrected response includes: ```json { "code": "capability_unavailable", "category": "unsupported_provider", "retryable": false, "details": { "provider_id": "process-ownership", "operation": "prepare_owned_process" } } ``` ## Change and scope Return an existing `AnalysisError` unchanged from the preparation catch. Caller cancellation still takes priority; unexpected exceptions keep the existing adapter diagnostics. ## Contract and boundary impact - Semantic owner and earliest changed stage: source-map ownership preparation, before runtime creation or codec launch. - Contribution scope / maintainer decision: ordinary fix within existing boundaries; advance scope decision not applicable. - CLI and MCP/tool catalog: corrected error classification through the shared projection; schemas and tool catalog unchanged. - Platform compatibility: the reported prerequisite failure is Linux-specific; typed-error preservation uses the existing shared contract. - Evidence and provenance: preserves the original error and producer details; successful Evidence is unchanged. - Authority and cleanup: existing admission remains required. No new execution authority or cleanup owner; cancellation reasons remain opaque. - Generated metadata, dependencies, package, installation: no changes. Expected effects of the existing workflow (unchanged by this fix): - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [x] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. The checked execution/write effects are the existing trusted codec and its private runtime files. Preparation failure returns before either is acquired. ## Evidence and regression coverage - Added an MCP regression using real Linux ownership preparation with an empty PATH. It checks the error, remediation, repeated calls, a working ping, and no runtime/codec acquisition. - Added two cancellation cases (`null` and a caller-owned cleanup error) and an unexpected-error case preserving diagnostics. - On Linux, removing just the new branch made the MCP regression fail with `execution_failure` instead of `capability_unavailable`. Restoring it passed all five tests in the two changed test files; source bytes and Git status were verified afterward. - Executed 11 real CLI/stdio MCP negative scenarios: missing, non-executable, incompatible, empty-output and malformed-output `ps`; invalid JSON/UTF-8, missing, directory and oversized maps; unsupported external section. All preserved CLI/MCP error parity, answered ping, and succeeded after repair on the same MCP connection. These were manual checks with generated local fixtures, not new committed tests. - Real CLI and stdio MCP success responses matched. With an empty PATH, both returned the error above and the original ENOENT reason with procps guidance. 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 Node 24.18.0 / npm 11.16.0, commit `653a29f824469ffffa84165a15c25c61eabc9973`: - `npm run check` and `npm run check:fast`: passed on Windows; lint retains existing warnings. - `npm run verify:test-discovery`: passed, all 1940 test files discovered once. - `npm run verify:windows-native:artifact`: passed using the matching published 6.7.0 x64 helper. - Focused suite below: Linux (Ubuntu WSL2) **115 passed**; Windows **112 passed, 3 failed**. All added cases passed on both hosts. The three Windows failures concern exit-vs-cancellation ordering, late output limits, and memory-limit precedence in `SourceMapCommand.test.ts`. Substituting the exact production file from base `3220e17b8bd046ad1be8fbb2e4070d8ddc37ad64` reproduced the same three failures. The committed file was restored and verified unchanged afterward. <details> <summary>Focused test command</summary> ```sh npm run test:focused -- \ src/javascript/sourceMaps/SourceMapCommand.test.ts \ src/javascript/sourceMaps/SourceMapDecoder.test.ts \ tests/boundary/javascript/sourceMapDecoder.test.ts \ tests/boundary/javascript/sourceMapRuntimeAvailability.test.ts \ tests/boundary/javascript/sourceMapPreparation.test.ts \ tests/boundary/mcp/webSourceLocationMcp.test.ts \ tests/acceptance/webSourceLocationCli.test.ts \ src/application/WebSourceLocationService.test.ts \ src/domain/analysisErrorProjection.test.ts \ tests/boundary/filesystem/webSourceLocationArtifacts.test.ts ``` </details> ## Compatibility, safety, and release - No breaking schema change, migration, dependency, or release metadata change. - Coverage: Linux source-map workflow and Windows tests above. macOS, live browsers, Hopper, Ghidra, and IDA were not exercised; this fix changes none of their adapters. - Source review found no new process authority, credential handling, or network access. ## Author readiness Human owner: @diyasharma05 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [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. - [ ] 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-11-01 21:45:50 +00:00