From 8c9cceceb4bd3c67874b67426421aed468d45265 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:24:16 +0800 Subject: [PATCH] refactor(javascript): name heap and deadline flags from the bound limit, not remediation text (#11448) * refactor(javascript): bind max_heap_mb and analysis_timeout_ms flags from the limit, not remediation text The CLI projection now also names the flag of a registered setting limit that carries a request parameter (javascript.max_heap_mb, javascript.analysis_timeout_ms). The JavaScript worker heap and timeout remediation and the web bundle heap remediation no longer name CLI flags; a web bundle heap exhaustion that a larger max_heap_mb raises now binds max_heap_mb as its per-call control. * test(javascript): assert the adapter-neutral heap remediation in the worker order audit * refactor(managed): bind max_snapshot_bytes as the per-call control of a managed snapshot refusal (#11453) --- .../cli-option-text-outside-cli.json | 4 +--- src/browser/WebBundleAnalysisWorker.test.ts | 9 ++++++++ src/browser/WebBundleAnalysisWorker.ts | 2 ++ src/cli/projectCliAnalysisResult.ts | 12 ++++++---- ...javascriptAnalysisResourceControls.test.ts | 4 ++-- .../javascriptAnalysisResourceControls.ts | 2 +- src/domain/webBundleAnalysis.ts | 23 ++++++++++++++++++- src/domain/webDeadlineControls.test.ts | 10 ++++++++ src/dotnet/ManagedSnapshot.ts | 12 +++++++++- .../analysis/JavaScriptAnalysisWorker.ts | 2 +- .../javascriptAnalysisLimits.test.ts | 16 ++++++++++--- tests/acceptance/managedCliOutput.test.ts | 14 ++++++++++- tests/boundary/cli/cliControlFlag.test.ts | 15 ++++++++++++ .../javascript/workerOrderAudit.test.ts | 5 +++- 14 files changed, 111 insertions(+), 19 deletions(-) diff --git a/scripts/verify/baselines/cli-option-text-outside-cli.json b/scripts/verify/baselines/cli-option-text-outside-cli.json index d4bd3d3f6e..a01e0800a6 100644 --- a/scripts/verify/baselines/cli-option-text-outside-cli.json +++ b/scripts/verify/baselines/cli-option-text-outside-cli.json @@ -4,12 +4,10 @@ "src/application/decompileDirectory/decompileAll.ts": 1, "src/application/reverse/ReverseEngineeringService.ts": 1, "src/domain/analysisErrorPresentation.ts": 2, - "src/domain/javascript/javascriptAnalysisResourceControls.ts": 5, + "src/domain/javascript/javascriptAnalysisResourceControls.ts": 4, "src/domain/javascript/javascriptSemanticResourceLimits.ts": 1, - "src/domain/webBundleAnalysis.ts": 1, "src/dotnet/ManagedDecodeBudget.ts": 1, "src/dotnet/ManagedMemberRecovery.ts": 1, - "src/dotnet/ManagedSnapshot.ts": 1, "src/ghidra/GhidraFileOffsetFailure.ts": 1, "src/ghidra/GhidraProviderClient.ts": 2, "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 1, diff --git a/src/browser/WebBundleAnalysisWorker.test.ts b/src/browser/WebBundleAnalysisWorker.test.ts index 517c86def0..58d6f52e57 100644 --- a/src/browser/WebBundleAnalysisWorker.test.ts +++ b/src/browser/WebBundleAnalysisWorker.test.ts @@ -995,6 +995,15 @@ it("projects a heap-marker exit with the runtime's exhausted resource", async () expect(error.message).toContain(webBundleHeapExhaustedReason(exhaustion)); expect(error).toMatchObject({ remediationAction: webBundleHeapExhaustedRemediation(exhaustion), + ...(exhaustion.kind === "bun-allocation" + ? {} + : { + limit: { + control_kind: "parameter", + parameter: "max_heap_mb", + effective_value: heapMb, + }, + }), reportedLimits: { max_heap_mb: heapMb, worker_process_memory_limit_bytes: diff --git a/src/browser/WebBundleAnalysisWorker.ts b/src/browser/WebBundleAnalysisWorker.ts index 530aed4bf6..b7fc44f39d 100644 --- a/src/browser/WebBundleAnalysisWorker.ts +++ b/src/browser/WebBundleAnalysisWorker.ts @@ -80,6 +80,7 @@ import { MIN_WEB_BUNDLE_HEAP_MB, webBundleFixedByteBudget, webBundleHeapExhaustedReason, + webBundleHeapLimit, webBundleHeapExhaustedRemediation, webBundleMemoryExhaustion, webBundleResultAdmissionFailure, @@ -900,6 +901,7 @@ export class WebBundleAnalysisWorker { }, { capturedOutput, + limit: webBundleHeapLimit(exhaustion), remediationAction: webBundleHeapExhaustedRemediation(exhaustion), }, ); diff --git a/src/cli/projectCliAnalysisResult.ts b/src/cli/projectCliAnalysisResult.ts index 10ecfcab4e..cd24b7a074 100644 --- a/src/cli/projectCliAnalysisResult.ts +++ b/src/cli/projectCliAnalysisResult.ts @@ -79,9 +79,11 @@ const renamedIssues = ( /** * The reported per-call control with the flag that sets it, or undefined - * when the command takes no flag for it. The longest bound prefix of the - * parameter path names the flag: a flattened member option, else the option - * of the whole field (such as `--producer-limits` JSON). + * when the command takes no flag for it. A parameter control names it, and so + * does a registered setting a request argument can also select. The longest + * bound prefix of the parameter path names the flag: a flattened member + * option, else the option of the whole field (such as `--producer-limits` + * JSON). */ const flaggedLimit = ( limit: JsonValue | undefined, @@ -89,8 +91,8 @@ const flaggedLimit = ( ): Record | undefined => { if ( !isObject(limit) || - limit.control_kind !== "parameter" || - typeof limit.parameter !== "string" + typeof limit.parameter !== "string" || + (limit.control_kind !== "parameter" && typeof limit.setting !== "string") ) return undefined; const segments = limit.parameter.split("."); diff --git a/src/domain/javascript/javascriptAnalysisResourceControls.test.ts b/src/domain/javascript/javascriptAnalysisResourceControls.test.ts index 20584bf3d1..f7d5230f21 100644 --- a/src/domain/javascript/javascriptAnalysisResourceControls.test.ts +++ b/src/domain/javascript/javascriptAnalysisResourceControls.test.ts @@ -62,7 +62,7 @@ it("names max_heap_mb, its range, and the budgets it does not raise", () => { expect(projected.remediation.action).toContain( String(JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM), ); - expect(projected.remediation.action).toContain("--max-heap-mb"); + expect(projected.remediation.action).not.toContain("--"); expect(projected.remediation.action).toContain("next analysis"); expect(projected.remediation.action).toContain("new worker"); expect(projected.remediation.action).toContain("parent result budget"); @@ -127,7 +127,7 @@ it("attributes V8 heap exhaustion to max_heap_mb only when that flag is enforced "exhausted its 1024 MiB V8 old-space heap (max_heap_mb)", ); expect(node.remediationAction).toContain("max_heap_mb"); - expect(node.remediationAction).toContain("--max-heap-mb"); + expect(node.remediationAction).not.toContain("--"); const bun = javaScriptWorkerHeapExhaustionRecovery({ heapFlagsEnforced: false, heapMb: 1024, diff --git a/src/domain/javascript/javascriptAnalysisResourceControls.ts b/src/domain/javascript/javascriptAnalysisResourceControls.ts index 7816aceb9e..1d6d5ee4b8 100644 --- a/src/domain/javascript/javascriptAnalysisResourceControls.ts +++ b/src/domain/javascript/javascriptAnalysisResourceControls.ts @@ -42,7 +42,7 @@ export const javaScriptWorkerHeapRemediation = (heapMb: number): string => { const adjustment = heapMb >= JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM ? `max_heap_mb is already ${String(heapMb)} MiB, the maximum ${String(JAVASCRIPT_WORKER_HEAP_MIB_MAXIMUM)}. Do not increase it further.` - : `Increase max_heap_mb (CLI: rea analyze-javascript-application --max-heap-mb ), ${bounds}.`; + : `Increase max_heap_mb, ${bounds}.`; return `${adjustment} The effective worker heap for this analysis is ${String(heapMb)} MiB. A changed max_heap_mb applies on the next analysis, which starts a new worker. It does not change a worker that is already running, and it does not require restarting the REA server. ${HEAP_DOES_NOT_RAISE} On Bun, V8 heap flags are ignored: Windows limits the analyzer's committed memory to max_heap_mb plus a 512 MiB reserve, and other Bun hosts enforce no analyzer heap limit.`; }; diff --git a/src/domain/webBundleAnalysis.ts b/src/domain/webBundleAnalysis.ts index 7d1502fbf3..fdc648f80f 100644 --- a/src/domain/webBundleAnalysis.ts +++ b/src/domain/webBundleAnalysis.ts @@ -1,4 +1,5 @@ import { MAX_NODE_TIMER_DELAY_MS } from "./analysisResourceLimits.js"; +import type { AnalysisControlLimit } from "./analysisSettings.js"; import { analysisSettingLimitSchema } from "./analysisSettingDefinitions.js"; import { javaScriptSemanticPrecisionSchema } from "./javascript/javascriptSemanticPrecision.js"; import { javaScriptRefusedPhaseSchema } from "./javascript/javascriptSemanticWorkAllowance.js"; @@ -158,7 +159,7 @@ const webBundleHeapRange = (): string => const webBundleHeapIncrease = (heapMb: number): string => heapMb < MAX_WEB_BUNDLE_HEAP_MB - ? `Increase max_heap_mb above ${String(heapMb)} (integer MiB from ${String(MIN_WEB_BUNDLE_HEAP_MB)} to ${String(MAX_WEB_BUNDLE_HEAP_MB)}; omitted means ${String(DEFAULT_WEB_BUNDLE_HEAP_MB)}), or use --max-heap-mb on the CLI.` + ? `Increase max_heap_mb above ${String(heapMb)} (integer MiB from ${String(MIN_WEB_BUNDLE_HEAP_MB)} to ${String(MAX_WEB_BUNDLE_HEAP_MB)}; omitted means ${String(DEFAULT_WEB_BUNDLE_HEAP_MB)}).` : `max_heap_mb is already at the maximum ${String(MAX_WEB_BUNDLE_HEAP_MB)} MiB; do not increase it further.`; const webBundleHeapDoesNotRaise = @@ -181,6 +182,26 @@ export const webBundleHeapExhaustedReason = ( } }; +/** + * The per-call control of an exhaustion that a larger `max_heap_mb` raises, + * or undefined when that allowance did not stop the analyzer. + */ +export const webBundleHeapLimit = ( + exhaustion: WebBundleMemoryExhaustion, +): AnalysisControlLimit | undefined => + exhaustion.kind === "bun-allocation" + ? undefined + : { + control_kind: "parameter", + parameter: "max_heap_mb", + effective_value: exhaustion.heapMb, + unit: "MiB", + minimum: MIN_WEB_BUNDLE_HEAP_MB, + maximum: MAX_WEB_BUNDLE_HEAP_MB, + default_value: DEFAULT_WEB_BUNDLE_HEAP_MB, + applies_at: "next_call", + }; + export const webBundleHeapExhaustedRemediation = ( exhaustion: WebBundleMemoryExhaustion, ): string => { diff --git a/src/domain/webDeadlineControls.test.ts b/src/domain/webDeadlineControls.test.ts index 38465a1460..9b473949fd 100644 --- a/src/domain/webDeadlineControls.test.ts +++ b/src/domain/webDeadlineControls.test.ts @@ -10,6 +10,7 @@ import { analyzeWebBundleInputSchema, webBundleHeapExhaustedReason, webBundleHeapExhaustedRemediation, + webBundleHeapLimit, webBundleMemoryExhaustion, webBundleResultAdmissionFailure, webBundleScriptTimeoutRecovery, @@ -177,6 +178,13 @@ it("names web-bundle exhaustion by the runtime that enforced it", () => { expect(webBundleHeapExhaustedRemediation(node)).toContain( "Increase max_heap_mb above 1024", ); + expect(webBundleHeapExhaustedRemediation(node)).not.toContain("--"); + expect(webBundleHeapLimit(node)).toMatchObject({ + control_kind: "parameter", + parameter: "max_heap_mb", + effective_value: 1024, + unit: "MiB", + }); const commitBytes = 1024 * 1024 * 1024 + 512 * 1024 * 1024; const windows = webBundleMemoryExhaustion({ @@ -216,6 +224,8 @@ it("names web-bundle exhaustion by the runtime that enforced it", () => { expect(webBundleHeapExhaustedRemediation(bun)).not.toContain( "Increase max_heap_mb", ); + // Raising max_heap_mb does not change a Bun allocation exit. + expect(webBundleHeapLimit(bun)).toBeUndefined(); expect(webBundleHeapExhaustedRemediation(bun)).toContain( "does not change this exit", ); diff --git a/src/dotnet/ManagedSnapshot.ts b/src/dotnet/ManagedSnapshot.ts index 8ec924d70a..0256d4f535 100644 --- a/src/dotnet/ManagedSnapshot.ts +++ b/src/dotnet/ManagedSnapshot.ts @@ -78,7 +78,17 @@ const managedSnapshotCapacityError = ( { max_snapshot_bytes: maxBytes }, { retryable: false, - remediationAction: `Increase max_snapshot_bytes above ${String(maxBytes)} bytes on the next inspection (CLI --max-snapshot-bytes) to admit the complete selected file. No REA restart is required. Metadata representation, transport and host memory limits remain independent; repeating the unchanged request cannot raise this budget.`, + remediationAction: `Increase max_snapshot_bytes above ${String(maxBytes)} bytes on the next inspection to admit the complete selected file. No REA restart is required. Metadata representation, transport and host memory limits remain independent; repeating the unchanged request cannot raise this budget.`, + limit: { + control_kind: "parameter", + parameter: "max_snapshot_bytes", + effective_value: maxBytes, + unit: "bytes", + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: DEFAULT_MANAGED_SNAPSHOT_BYTES, + applies_at: "next_call", + }, }, ); diff --git a/src/javascript/analysis/JavaScriptAnalysisWorker.ts b/src/javascript/analysis/JavaScriptAnalysisWorker.ts index bb6f2902ac..3b5a8cef35 100644 --- a/src/javascript/analysis/JavaScriptAnalysisWorker.ts +++ b/src/javascript/analysis/JavaScriptAnalysisWorker.ts @@ -1240,7 +1240,7 @@ export class JavaScriptAnalysisWorker { ...(withCapturedOutput ? { capturedOutput: this.#captured() } : {}), userMessage: `JavaScript source analysis reached its ${String(this.limits.timeoutMs)}ms per-source server/provider deadline (analysis_timeout_ms), not the MCP client deadline.`, remediationAction: - "Reuse accessible partial_observation Evidence to avoid recomputation; reading it is not a prerequisite for a corrected retry. Increase analysis_timeout_ms through MCP, or use rea analyze-javascript-application --analysis-timeout-ms on the CLI. Alternatively, reduce semantic limits or select exact inventoried source_paths (CLI: --source-path on that command). Omit source_paths to analyze all sources; an empty array is invalid. detail: summary reduces response size, not analysis work. Allow execution, cleanup and delivery headroom in the MCP client tool deadline; increasing that client deadline alone does not change this server budget. Resolve any reported incomplete cleanup before retrying.", + "Reuse accessible partial_observation Evidence to avoid recomputation; reading it is not a prerequisite for a corrected retry. Increase analysis_timeout_ms on the next call. Alternatively, reduce semantic limits or select exact inventoried source_paths (CLI: --source-path on that command). Omit source_paths to analyze all sources; an empty array is invalid. detail: summary reduces response size, not analysis work. Allow execution, cleanup and delivery headroom in the MCP client tool deadline; increasing that client deadline alone does not change this server budget. Resolve any reported incomplete cleanup before retrying.", }); } #workerExitFailure( diff --git a/tests/acceptance/applications/javascriptAnalysisLimits.test.ts b/tests/acceptance/applications/javascriptAnalysisLimits.test.ts index 08334108ae..1a62f372be 100644 --- a/tests/acceptance/applications/javascriptAnalysisLimits.test.ts +++ b/tests/acceptance/applications/javascriptAnalysisLimits.test.ts @@ -63,12 +63,22 @@ cliTest( code: "provider_timeout", message: expect.stringContaining("analysis_timeout_ms"), remediation: { - action: expect.stringContaining( - "rea analyze-javascript-application --analysis-timeout-ms", - ), + action: expect.stringContaining("Increase analysis_timeout_ms"), }, recovery: { kind: "inspect_timeout_state", timeout_ms: 1 }, + // The worker names the setting's request parameter; the CLI adds the + // option that sets it. + details: { + limit: { + setting: "javascript.analysis_timeout_ms", + parameter: "analysis_timeout_ms", + cli_flag: "--analysis-timeout-ms", + }, + }, }); + expect( + JSON.stringify((response.json as { remediation: unknown }).remediation), + ).not.toContain("--analysis-timeout-ms"); }, ); diff --git a/tests/acceptance/managedCliOutput.test.ts b/tests/acceptance/managedCliOutput.test.ts index fc86bdbaac..e9193ddcde 100644 --- a/tests/acceptance/managedCliOutput.test.ts +++ b/tests/acceptance/managedCliOutput.test.ts @@ -58,8 +58,20 @@ cliTest( expect(refused.exitCode).toBe(1); expect(refused.json).toMatchObject({ code: "resource_constraint", - details: { reported_limits: { max_snapshot_bytes: bytes.length - 1 } }, + details: { + reported_limits: { max_snapshot_bytes: bytes.length - 1 }, + // The provider names the field; the CLI adds the flag that sets it. + limit: { + control_kind: "parameter", + parameter: "max_snapshot_bytes", + effective_value: bytes.length - 1, + cli_flag: "--max-snapshot-bytes", + }, + }, }); + expect( + JSON.stringify((refused.json as { remediation: unknown }).remediation), + ).not.toContain("--"); const admitted = ["--max-snapshot-bytes", String(bytes.length)]; const partial = await cli.run({ arguments: [ diff --git a/tests/boundary/cli/cliControlFlag.test.ts b/tests/boundary/cli/cliControlFlag.test.ts index a282a2bc44..37258037fd 100644 --- a/tests/boundary/cli/cliControlFlag.test.ts +++ b/tests/boundary/cli/cliControlFlag.test.ts @@ -102,6 +102,21 @@ it("names a member control by its member flag, else by its field's flag", () => expect(projectCliInputFields(unbound, binding)).toBe(unbound); const success = { details: { limit: { parameter: "producer_limits" } } }; expect(projectCliInputFields(success, binding)).toBe(success); + // A registered setting that a request argument also selects names it. + expect( + projectCliInputFields( + { + code: "provider_timeout", + details: { + limit: { + setting: "fixture.timeout_ms", + parameter: "producer_limits.timeout_ms", + }, + }, + }, + binding, + ), + ).toMatchObject({ details: { limit: { cli_flag: "--producer-limits" } } }); }); it("binds a nested flattened member to its own flag", () => { diff --git a/tests/boundary/javascript/workerOrderAudit.test.ts b/tests/boundary/javascript/workerOrderAudit.test.ts index 5f8fb73214..467411d1c1 100644 --- a/tests/boundary/javascript/workerOrderAudit.test.ts +++ b/tests/boundary/javascript/workerOrderAudit.test.ts @@ -779,7 +779,10 @@ it("retains the owned worker's V8 heap exhaustion classification", async () => { expect(projected.message).toContain( "128 MiB V8 old-space heap (max_heap_mb)", ); - expect(projected.remediation.action).toContain("--max-heap-mb"); + // The adapter-neutral remediation names the request field; only the + // CLI renders its option. + expect(projected.remediation.action).toContain("Increase max_heap_mb"); + expect(projected.remediation.action).not.toContain("--max-heap-mb"); } else { expect(projected.message).toContain( "Bun ignores the V8 old-space flag",