[PR #3545] [CLOSED] fix(javascript): explain parent budget exhaustion after a static checkpoint #5815

New issue

Closed

opened 2026-10-31 01:09:38 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:09:38 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3545
Author: @Rinkia
Created: 10/14/2026
Status: ❌ Closed

Base: main ← Head: fix/js-parent-budget-static-remediation

📝 Commits (1)

b2aa24d fix(javascript): explain parent budget exhaustion after a static checkpoint

📊 Changes

2 files changed (+56 additions, -0 deletions)

View changed files

📝 src/javascript/analysis/JavaScriptAnalysisWorker.ts (+4 -0)
➕ tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts (+52 -0)

📄 Description

Summary

When analyze_javascript_application exhausts the parent result budget while retaining a static checkpoint, the error told users to "Retry with sufficient memory", which can't help. This path now gives the same parent-budget remediation as its sibling paths. Fixes #3538.

Problem and expected behavior

Smallest trigger: one large source followed by one tiny source, analysed with a 256 MiB CLI heap. The large file's static checkpoint uses up the parent result budget, and the next checkpoint (z-tiny.mjs) stops the analysis:

code: resource_constraint
message: The parent's result capacity was exhausted after retaining static facts for z-tiny.mjs; remaining sources were not analyzed
remediation (before): Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.

JavaScriptAnalysisWorker.ts raised this AnalysisResourceConstraintError without a remediationAction, so analysisErrorPresentation.ts fell back to the generic memory advice. The three sibling parent-budget paths (module facts, semantic graph, expanded application relationships) already explain that the limit belongs to the parent result budget and that a larger worker heap doesn't raise it.

The same path occurs on a real target: Joplin desktop 3.7.21 (app.asar, 5,427 sources) stops at source 3,880 with this error (details in #3538).

Expected and new behavior:

remediation (after): Use the retained static facts or analyze fewer source files. This limit belongs to the parent result budget; increasing the worker heap alone does not increase it.

Change and scope

src/javascript/analysis/JavaScriptAnalysisWorker.ts: pass { remediationAction } to the static-checkpoint parent-budget error, reusing the static-facts sibling's text verbatim (4 added lines).
tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts: a CLI acceptance test that reaches this path and asserts the parent-budget remediation, modelled on javascriptCheckpointReserveCli.test.ts.

Intentionally not included: changes to budget sizing, ordering of app-owned sources before node_modules, partial-success behavior, or the size of the error payload (all mentioned in #3538 as context only).

Follow the contribution scope.
Scope decision: not applicable (ordinary fix of user-facing remediation within existing boundaries).

Contract and boundary impact

Semantic owner and earliest changed stage: JavaScriptAnalysisWorker error construction (remediation text only).
Contribution scope fit and linked maintainer decision: not applicable; bug fix for #3538.
CLI and MCP/tool-catalog contract: unchanged shape; only remediation.action text changes for this one error path.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: none. Error code, category, message, reported_limits and partial observation are unchanged.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

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.

Evidence and regression coverage

Tests added or updated: tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts. It runs analyze-javascript-application with NODE_OPTIONS=--max-old-space-size=256 --max-semi-space-size=8 on a generated 3.1 MB module plus a tiny module, then asserts exit 1, resource_constraint, parent_result_budget_exhausted: true, the message naming z-tiny.mjs, a remediation mentioning the parent result budget and that the worker heap doesn't raise it, and no V8 fatal heap error.
Base reproduction: on the base revision the new test fails only on the remediation assertion (expected 'Review the reported worker memory lim…' to contain 'parent result budget'); every earlier assertion passes, so the test reaches exactly this path.
Heap window, measured with the 6.5.0 CLI in a Linux container on the same fixture: 224, 256, 288 and 320 MiB all reach this path with no fatal OOM; 384 MiB and above complete successfully; 192 MiB exits 0. The test uses 256 MiB, mid-window.
User-visible CLI/MCP output: remediation text shown above.
Remaining proof gaps: verified on Linux x64 only. The test is skipped on Bun, like its sibling. The 256 MiB window depends on parent heap ergonomics, so a much larger baseline heapUsed on some runner could move it; it was stable across 4 runs here.

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

Linux x64 container (node:24-bookworm, Node 24.21.0), branch based on main @ 1438422df:

npx vitest run --project acceptance tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts before the fix: 1 failed (remediation assertion only).
Same, after the fix: 1 passed. Repeated 3 more times: 1 passed each.
npx vitest run --project acceptance tests/acceptance/applications/javascriptCheckpointReserveCli.test.ts: 3 passed (sibling parent-budget behavior unchanged).
npx vitest run tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts: 10 passed.
npm run verify:test-discovery: "Discovered all 1285 test files exactly once."
npm run typecheck: exit 0.
npm run lint: exit 0 (module boundaries checked in 1,885 source files).
npm run build: exit 0.
Pre-commit (lint-staged: oxfmt, oxlint) and pre-push (typecheck, lint) hooks: passed.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: not applicable; JavaScript analysis only, Linux x64.
Package or release metadata impact: none.
Security, privacy, process, or containment review: none. Text-only change to one error's remediation; no new process, file, or network behavior. The test writes only to a test temp directory.

Author readiness

Human owner: @Rinkia

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.

🤖 Generated with Claude Code

_{🔄 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/3545 **Author:** [@Rinkia](https://github.com/Rinkia) **Created:** 10/14/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/js-parent-budget-static-remediation` --- ### 📝 Commits (1) - [`b2aa24d`](https://github.com/morluto/rea/commit/b2aa24d630dc736fc54d83a72a1a912757b66d7a) fix(javascript): explain parent budget exhaustion after a static checkpoint ### 📊 Changes **2 files changed** (+56 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `src/javascript/analysis/JavaScriptAnalysisWorker.ts` (+4 -0) ➕ `tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts` (+52 -0) </details> ### 📄 Description ## Summary When `analyze_javascript_application` exhausts the parent result budget while retaining a static checkpoint, the error told users to "Retry with sufficient memory", which can't help. This path now gives the same parent-budget remediation as its sibling paths. Fixes #3538. ## Problem and expected behavior Smallest trigger: one large source followed by one tiny source, analysed with a 256 MiB CLI heap. The large file's static checkpoint uses up the parent result budget, and the next checkpoint (`z-tiny.mjs`) stops the analysis: ```text code: resource_constraint message: The parent's result capacity was exhausted after retaining static facts for z-tiny.mjs; remaining sources were not analyzed remediation (before): Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits. ``` `JavaScriptAnalysisWorker.ts` raised this `AnalysisResourceConstraintError` without a `remediationAction`, so `analysisErrorPresentation.ts` fell back to the generic memory advice. The three sibling parent-budget paths (module facts, semantic graph, expanded application relationships) already explain that the limit belongs to the parent result budget and that a larger worker heap doesn't raise it. The same path occurs on a real target: Joplin desktop 3.7.21 (`app.asar`, 5,427 sources) stops at source 3,880 with this error (details in #3538). Expected and new behavior: ```text remediation (after): Use the retained static facts or analyze fewer source files. This limit belongs to the parent result budget; increasing the worker heap alone does not increase it. ``` ## Change and scope - `src/javascript/analysis/JavaScriptAnalysisWorker.ts`: pass `{ remediationAction }` to the static-checkpoint parent-budget error, reusing the static-facts sibling's text verbatim (4 added lines). - `tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts`: a CLI acceptance test that reaches this path and asserts the parent-budget remediation, modelled on `javascriptCheckpointReserveCli.test.ts`. Intentionally not included: changes to budget sizing, ordering of app-owned sources before `node_modules`, partial-success behavior, or the size of the error payload (all mentioned in #3538 as context only). Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Scope decision: not applicable (ordinary fix of user-facing remediation within existing boundaries). ## Contract and boundary impact - Semantic owner and earliest changed stage: `JavaScriptAnalysisWorker` error construction (remediation text only). - Contribution scope fit and linked maintainer decision: not applicable; bug fix for #3538. - CLI and MCP/tool-catalog contract: unchanged shape; only `remediation.action` text changes for this one error path. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. Error code, category, message, `reported_limits` and partial observation are unchanged. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] 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. ## Evidence and regression coverage - Tests added or updated: `tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts`. It runs `analyze-javascript-application` with `NODE_OPTIONS=--max-old-space-size=256 --max-semi-space-size=8` on a generated 3.1 MB module plus a tiny module, then asserts exit 1, `resource_constraint`, `parent_result_budget_exhausted: true`, the message naming `z-tiny.mjs`, a remediation mentioning the parent result budget and that the worker heap doesn't raise it, and no V8 fatal heap error. - Base reproduction: on the base revision the new test fails only on the remediation assertion (`expected 'Review the reported worker memory lim…' to contain 'parent result budget'`); every earlier assertion passes, so the test reaches exactly this path. - Heap window, measured with the 6.5.0 CLI in a Linux container on the same fixture: 224, 256, 288 and 320 MiB all reach this path with no fatal OOM; 384 MiB and above complete successfully; 192 MiB exits 0. The test uses 256 MiB, mid-window. - User-visible CLI/MCP output: remediation text shown above. - Remaining proof gaps: verified on Linux x64 only. The test is skipped on Bun, like its sibling. The 256 MiB window depends on parent heap ergonomics, so a much larger baseline `heapUsed` on some runner could move it; it was stable across 4 runs here. 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 Linux x64 container (`node:24-bookworm`, Node 24.21.0), branch based on `main` @ `1438422df`: - `npx vitest run --project acceptance tests/acceptance/applications/javascriptStaticCheckpointBudgetCli.test.ts` before the fix: 1 failed (remediation assertion only). - Same, after the fix: 1 passed. Repeated 3 more times: 1 passed each. - `npx vitest run --project acceptance tests/acceptance/applications/javascriptCheckpointReserveCli.test.ts`: 3 passed (sibling parent-budget behavior unchanged). - `npx vitest run tests/boundary/javascript/javascriptSourceAnalysisWorker.test.ts`: 10 passed. - `npm run verify:test-discovery`: "Discovered all 1285 test files exactly once." - `npm run typecheck`: exit 0. - `npm run lint`: exit 0 (module boundaries checked in 1,885 source files). - `npm run build`: exit 0. - Pre-commit (lint-staged: oxfmt, oxlint) and pre-push (typecheck, lint) hooks: passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable; JavaScript analysis only, Linux x64. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none. Text-only change to one error's remediation; no new process, file, or network behavior. The test writes only to a test temp directory. ## Author readiness Human owner: @Rinkia - [ ] 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 - [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. - [ ] 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. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:09:38 +00:00