diff --git a/docs/guides/javascript/javascript-artifact-reconstruction.md b/docs/guides/javascript/javascript-artifact-reconstruction.md index 91eb76c4ba..baf90aa6df 100644 --- a/docs/guides/javascript/javascript-artifact-reconstruction.md +++ b/docs/guides/javascript/javascript-artifact-reconstruction.md @@ -822,6 +822,12 @@ representation bounds remain independently enforced. Omission keeps the defaults invalid values fail validation. For example, retry a finite candidate-limit observation with `semantic_precision: {"primitive_candidates": 512}`. The CLI accepts `--semantic-precision '{"primitive_candidates":512}'` or a JSON file. +For `analyze_web_bundle`, evaluator budgets actually reached by a captured script +are recorded in `unknowns[]` with that script's key, the effective parameter +limit and next-call recovery guidance. These results are partial and retain +the findings already established. With `--full-output`, the CLI also names +`--semantic-precision` in `meta.cli_controls`; selecting a low budget that was +not reached does not add a limitation. An override applies to that next analysis without restarting REA, remains in Evidence parameters and effective coverage, and cannot change already retained facts. Increasing these budgets does not raise graph retention, worker heap, diff --git a/src/browser/WebBundleAnalysisWorkerServer.test.ts b/src/browser/WebBundleAnalysisWorkerServer.test.ts index fe159e5751..b96de558d5 100644 --- a/src/browser/WebBundleAnalysisWorkerServer.test.ts +++ b/src/browser/WebBundleAnalysisWorkerServer.test.ts @@ -16,6 +16,7 @@ import { WEB_BUNDLE_WORKER_LIMITS, } from "./WebBundleAnalysisWorkerProtocol.js"; import { JAVASCRIPT_MEMBER_MUTATION_WORK_LIMIT } from "../domain/javascript/javascriptSemanticWorkAllowance.js"; +import { webBundleScriptAnalysisSchema } from "../domain/webBundleScriptAnalysis.js"; const makeScript = (text: string): IncludedScript => ({ script_key: `scr_${createHash("sha256").update(text).digest("hex")}`, @@ -148,6 +149,59 @@ const closeServer = async ( } }; +it("transfers reached semantic budgets and does not retain them for the next job", async () => { + const root = await mkdtemp(join(tmpdir(), "rea-web-worker-precision-")); + let worker: ChildProcessWithoutNullStreams | undefined; + try { + const server = await startServer(root); + worker = server.process; + expect(await server.next()).toMatchObject({ kind: "ready" }); + const script = makeScript( + "const routes = {get path(){return '/a';}}; createBrowserRouter([{path:routes.path}]);", + ); + const input = sourceDescriptor(script); + for (const getterExpansions of [1, 512]) { + const id = randomUUID(); + await writeSource(root, id, input.bytes); + await send(worker, { + kind: "analyze", + id, + member_mutation_allowance: DEFAULT_ALLOWANCE, + semantic_precision: { getter_expansions: getterExpansions }, + source: input.descriptor, + result_budget_bytes: WEB_BUNDLE_WORKER_LIMITS.resultBytes, + }); + expect(await server.next()).toMatchObject({ kind: "phase", id }); + const completed = await server.next(); + expect(completed).toMatchObject({ kind: "complete", id }); + if (completed.kind !== "complete") throw new Error("Expected result"); + const bytes = await readFile(join(root, `${id}.result`)); + expect(completed.result).toEqual({ + bytes: bytes.length, + sha256: createHash("sha256").update(bytes).digest("hex"), + }); + const result = webBundleScriptAnalysisSchema.parse( + JSON.parse(bytes.toString("utf8")), + ); + if (getterExpansions === 1) + expect(result).toMatchObject({ + semantic_limits: [ + { + limit: { + parameter: "semantic_precision.getter_expansions", + effective_value: 1, + }, + }, + ], + }); + else expect(result).not.toHaveProperty("semantic_limits"); + } + } finally { + if (worker !== undefined) await closeServer(worker); + await rm(root, { recursive: true, force: true }); + } +}); + it("refuses with the allowance the parent sent and reports its limit", async () => { const root = await mkdtemp(join(tmpdir(), "rea-web-worker-work-")); let worker: ChildProcessWithoutNullStreams | undefined; diff --git a/src/domain/webBundleAnalyzer.ts b/src/domain/webBundleAnalyzer.ts index 77d05f3a20..227e248a01 100644 --- a/src/domain/webBundleAnalyzer.ts +++ b/src/domain/webBundleAnalyzer.ts @@ -27,9 +27,9 @@ export const analyzeCapturedWebScript = ( memberMutationAllowance?: JavaScriptMemberMutationAllowance, ): WebBundleScriptAnalysis => { const accumulator = createWebBundleAnalysisAccumulator(); - let routeFacts: ReturnType; + let analysis: ReturnType; try { - routeFacts = analyzeScript( + analysis = analyzeScript( script, accumulator, precision, @@ -59,7 +59,10 @@ export const analyzeCapturedWebScript = ( parse_status: failed ? "failed" : recovered ? "recovered" : "parsed", visited_ast_nodes: accumulator.visitedNodes, widened_return_references: accumulator.widenedScripts.length > 0, - route_facts: routeFacts, + route_facts: analysis.routeFacts, + ...(analysis.semanticLimits.length === 0 + ? {} + : { semantic_limits: analysis.semanticLimits }), observations: { edges: accumulator.edges, routes: accumulator.routes, diff --git a/src/domain/webBundleAnalyzerInspection.ts b/src/domain/webBundleAnalyzerInspection.ts index 66ebcbaf2d..e17dae6823 100644 --- a/src/domain/webBundleAnalyzerInspection.ts +++ b/src/domain/webBundleAnalyzerInspection.ts @@ -47,6 +47,12 @@ import { import { createJavaScriptRpcScan } from "./javascript/javascriptRpcEndpoints.js"; import { semanticStaticModuleSource } from "./javascript/javascriptModuleDeclaration.js"; import { parseJavaScriptSource } from "./javascript/javascriptSourceParser.js"; +import { + semanticPrecisionControl, + semanticResourceLimitFacts, + semanticResourceLimitReason, +} from "./javascript/javascriptSemanticResourceLimits.js"; +import type { WebBundleSemanticLimit } from "./webBundleScriptAnalysis.js"; type BundleObservations = WebBundleAnalysis["observations"]; type ChunkEdge = BundleObservations["chunks"]["edges"][number]; @@ -58,11 +64,14 @@ export const analyzeScript = ( accumulator: AnalysisAccumulator, precision?: JavaScriptSemanticPrecisionInput, memberMutationAllowance?: JavaScriptMemberMutationAllowance, -): JavaScriptRouteSourceFacts | null => { +): { + readonly routeFacts: JavaScriptRouteSourceFacts | null; + readonly semanticLimits: readonly WebBundleSemanticLimit[]; +} => { const file = parseJavaScriptSource(script.source.artifact.text); if (file === null) { accumulator.failedScripts.push(script.script_key); - return null; + return { routeFacts: null, semanticLimits: [] }; } accumulator.parsedScripts += 1; if ((file.errors?.length ?? 0) > 0) @@ -146,7 +155,24 @@ export const analyzeScript = ( }); if (index.bindings.returnedReferenceWidenings.size > 0) accumulator.widenedScripts.push(script.script_key); - return completeSemanticSteps(routeScan.finishSteps()); + // Finishing route recovery can itself exhaust a getter or alias budget. + // Snapshot the evaluator's facts only after every consumer has finished. + const routeFacts = completeSemanticSteps(routeScan.finishSteps()); + const { bindings } = index; + const reached = new Set([ + ...bindings.valueResourceLimits, + ...bindings.getterResourceLimits, + ]); + return { + routeFacts, + semanticLimits: [...reached].sort().map((resource) => ({ + reason: semanticResourceLimitReason(resource, bindings.precision), + limit: semanticPrecisionControl( + semanticResourceLimitFacts(resource, bindings.precision).control, + bindings.precision, + ), + })), + }; }; const inspectNode = ( diff --git a/src/domain/webBundleAnalyzerResult.ts b/src/domain/webBundleAnalyzerResult.ts index 304f0e27b3..b7633e85d2 100644 --- a/src/domain/webBundleAnalyzerResult.ts +++ b/src/domain/webBundleAnalyzerResult.ts @@ -61,6 +61,17 @@ export const buildCapturedWebBundleAnalysis = ( > => result.status === "unavailable", ); const accumulator = mergeScriptResults(orderedResults); + const semanticUnknowns = orderedResults.flatMap((result) => + result.status !== "analyzed" || result.semantic_limits === undefined + ? [] + : result.semantic_limits.map(({ reason, limit }) => ({ + dimension: "javascript_analysis", + reason, + limit, + remediation: `Increase ${limit.parameter} on the next analysis call.`, + affected_script_keys: [result.script_key], + })), + ); const attemptedScripts = orderedResults.filter( (result) => !(result.status === "unavailable" && result.reason === "not_started"), @@ -87,6 +98,7 @@ export const buildCapturedWebBundleAnalysis = ( const sourceMapIncomplete = sourceMaps.status === "partial" || sourceMaps.status === "unavailable"; const partial = + semanticUnknowns.length > 0 || accumulator.failedScripts.length > 0 || accumulator.recoveredScripts.length > 0 || accumulator.widenedScripts.length > 0 || @@ -173,6 +185,7 @@ export const buildCapturedWebBundleAnalysis = ( }, inferences: accumulator.inferences, unknowns: buildUnknowns({ + semanticUnknowns, unavailable, unavailableSourceReasons, failedScripts: accumulator.failedScripts, @@ -267,6 +280,7 @@ const chunkNode = (script: IncludedScript) => { }; interface UnknownsInput { + readonly semanticUnknowns: WebBundleAnalysis["unknowns"]; readonly unavailable: string[]; readonly unavailableSourceReasons: readonly string[]; readonly failedScripts: readonly string[]; @@ -284,6 +298,7 @@ interface UnknownsInput { } const buildUnknowns = (input: UnknownsInput): WebBundleAnalysis["unknowns"] => [ + ...input.semanticUnknowns, ...(input.omittedScripts === undefined ? [] : [ diff --git a/src/domain/webBundleScriptAnalysis.ts b/src/domain/webBundleScriptAnalysis.ts index 15145b63aa..65e5b936b9 100644 --- a/src/domain/webBundleScriptAnalysis.ts +++ b/src/domain/webBundleScriptAnalysis.ts @@ -4,7 +4,10 @@ import { webBundleAnalysisSchema, webBundleCallSiteSchema, } from "./webBundleAnalysis.js"; -import { analysisResultLimitSchema } from "./analysisSettingDefinitions.js"; +import { + analysisParameterLimitSchema, + analysisResultLimitSchema, +} from "./analysisSettingDefinitions.js"; import { javaScriptRouteSourceFactsSchema } from "./javascript/javascriptRouteFacts.js"; import { javaScriptRefusedPhaseSchema } from "./javascript/javascriptSemanticWorkAllowance.js"; import type { AnalysisError } from "./analysisErrorBase.js"; @@ -31,6 +34,12 @@ const refusedScriptFactsSchema = z.strictObject({ inferences: webBundleAnalysisSchema.shape.inferences, }); +const semanticLimitSchema = z.strictObject({ + reason: z.string(), + limit: analysisParameterLimitSchema, +}); +export type WebBundleSemanticLimit = z.infer; + /** Serializable result for one captured script, suitable for worker transport. */ export const webBundleScriptAnalysisSchema = z .discriminatedUnion("status", [ @@ -40,6 +49,7 @@ export const webBundleScriptAnalysisSchema = z parse_status: z.enum(["parsed", "recovered", "failed"]), visited_ast_nodes: z.number().int().min(0), widened_return_references: z.boolean(), + semantic_limits: z.array(semanticLimitSchema).exactOptional(), route_facts: javaScriptRouteSourceFactsSchema.nullable().optional(), observations: observationsSchema, inferences: webBundleAnalysisSchema.shape.inferences, @@ -144,6 +154,8 @@ export const webBundleScriptAnalysisSchema = z if (result.parse_status === "failed") { const hasFindings = + (result.semantic_limits !== undefined && + result.semantic_limits.length > 0) || result.observations.edges.length > 0 || result.observations.routes.length > 0 || result.observations.endpoints.length > 0 || diff --git a/src/domain/webBundleSemanticLimits.test.ts b/src/domain/webBundleSemanticLimits.test.ts new file mode 100644 index 0000000000..b424c60ea7 --- /dev/null +++ b/src/domain/webBundleSemanticLimits.test.ts @@ -0,0 +1,145 @@ +import { expect, it } from "vitest"; +import { createWebPageInspection } from "../../tests/support/browser/webPageInspection.js"; +import type { JavaScriptSemanticPrecisionInput } from "./javascript/javascriptSemanticPrecision.js"; +import { analyzeCapturedWebScript } from "./webBundleAnalyzer.js"; +import { buildCapturedWebBundleAnalysis } from "./webBundleAnalyzerResult.js"; +import { isIncludedScript } from "./webBundleAnalyzerState.js"; +import { webBundleScriptAnalysisSchema } from "./webBundleScriptAnalysis.js"; + +const source = + "const routes = {get path(){ return '/a'; }}; createBrowserRouter([{path:routes.path}, {path:routes.path}]); fetch('/health');"; + +const analyze = ( + texts: readonly string[], + precision: JavaScriptSemanticPrecisionInput, +) => { + const inspection = createWebPageInspection( + texts.map((text, index) => ({ + source: text, + scriptKey: `scr_${String(index + 1).repeat(64)}`, + url: `https://app.example.test/${String(index)}.js`, + origin: "https://app.example.test", + cdpHash: "hash", + })), + ); + const results = inspection.scripts.items + .filter(isIncludedScript) + .map((script) => analyzeCapturedWebScript(script, precision)); + // Exercise the same strict serializable result boundary the worker uses. + const transferred = results.map((result) => + webBundleScriptAnalysisSchema.parse(JSON.parse(JSON.stringify(result))), + ); + const report = buildCapturedWebBundleAnalysis( + inspection, + { + status: "not_requested", + requested: 0, + processed: 0, + items: [], + }, + transferred, + ); + return { results: transferred, report }; +}; + +it.each(["getter_expansions", "alias_selections"] as const)( + "retains reached %s facts and actionable recovery without dropping findings", + (field) => { + const { results, report } = analyze([source], { [field]: 1 }); + expect(report.completeness).toMatchObject({ + status: "partial", + parsed_scripts: 1, + parse_failures: 0, + }); + expect(report.observations.endpoints.map((entry) => entry.value)).toEqual([ + "/health", + ]); + expect(report.unknowns).toEqual([ + { + dimension: "javascript_analysis", + reason: expect.stringContaining(`semantic_precision.${field}=1`), + affected_script_keys: [results[0]!.script_key], + limit: { + control_kind: "parameter", + parameter: `semantic_precision.${field}`, + effective_value: 1, + minimum: 1, + maximum: Number.MAX_SAFE_INTEGER, + default_value: 512, + unit: "count", + applies_at: "next_call", + }, + remediation: `Increase semantic_precision.${field} on the next analysis call.`, + }, + ]); + }, +); + +it("records only reached controls, rather than echoing every selected low budget", () => { + const { report } = analyze([source], { + getter_expansions: 1, + expression_depth: 1, + }); + expect( + report.unknowns.map((entry) => + entry.limit !== undefined && "parameter" in entry.limit + ? entry.limit.parameter + : null, + ), + ).toEqual(["semantic_precision.getter_expansions"]); +}); + +it("clears the limitation when the next analysis has sufficient precision", () => { + const low = analyze([source], { getter_expansions: 1 }); + const raised = analyze([source], { getter_expansions: 512 }); + expect(low.report.unknowns).toHaveLength(1); + expect(raised.report.unknowns).toEqual([]); + expect(raised.report.completeness.status).toBe("complete"); + expect(raised.results[0]).not.toHaveProperty("semantic_limits"); +}); + +it("attributes each reached budget to its own script and preserves unaffected scripts", () => { + const { results, report } = analyze( + [source, source, "fetch('/unaffected');"], + { getter_expansions: 1 }, + ); + expect(report.unknowns.map((entry) => entry.affected_script_keys)).toEqual([ + [results[0]!.script_key], + [results[1]!.script_key], + ]); + expect(report.observations.endpoints.map((entry) => entry.value)).toEqual([ + "/health", + "/health", + "/unaffected", + ]); + expect(report.completeness).toMatchObject({ + status: "partial", + parsed_scripts: 3, + parse_failures: 0, + }); + expect(results[2]).not.toHaveProperty("semantic_limits"); +}); + +it("refuses worker results that claim evaluator facts after a failed parse", () => { + const { results } = analyze([source], { getter_expansions: 1 }); + const result = results[0]; + if (result?.status !== "analyzed") + throw new Error("Expected script analysis"); + expect( + webBundleScriptAnalysisSchema.safeParse({ + ...result, + parse_status: "failed", + visited_ast_nodes: 0, + widened_return_references: false, + route_facts: null, + observations: { + edges: [], + routes: [], + endpoints: [], + webmcp_declarations: [], + unresolved_endpoints: [], + }, + inferences: [], + }).success, + ).toBe(false); +}); diff --git a/tests/boundary/browser/webBundleSemanticLimits.test.ts b/tests/boundary/browser/webBundleSemanticLimits.test.ts new file mode 100644 index 0000000000..e7fd0a429c --- /dev/null +++ b/tests/boundary/browser/webBundleSemanticLimits.test.ts @@ -0,0 +1,124 @@ +import { expect, onTestFinished } from "vitest"; +import { z } from "zod"; +import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js"; +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { webBundleAnalysisSchema } from "../../../src/domain/webBundleAnalysis.js"; +import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; +import { startFakeCdpBrowser } from "../../fixtures/fakeCdpBrowser.js"; +import { createMcpSchemaValidation } from "../../fixtures/mcpSchemaValidation.js"; +import { cliTest } from "../../support/cli/cliFixture.js"; + +cliTest( + "retains semantic limits through capture, real workers, MCP and CLI recovery controls", + async ({ cli }) => { + const source = + "const routes={get path(){return '/a';}};createBrowserRouter([{path:routes.path}]);fetch('/kept');"; + const browser = await startFakeCdpBrowser({ + commandResult: ({ method }) => + method === "Debugger.getScriptSource" + ? { scriptSource: source } + : undefined, + }); + onTestFinished(() => browser.close()); + const { client } = await createApplicationMcpHarness({ + serverOptions: { browserObservation: new CdpBrowserProvider() }, + schemaValidator: createMcpSchemaValidation(), + }); + const parameters = { + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + observation_ms: 0, + }; + const low = await client.callTool({ + name: "analyze_web_bundle", + arguments: { + ...parameters, + semantic_precision: { getter_expansions: 1 }, + }, + }); + expect(low.isError, JSON.stringify(low.content)).not.toBe(true); + const evidence = parseEvidence(low.structuredContent); + const report = webBundleAnalysisSchema.parse(evidence.normalized_result); + expect(report.completeness).toMatchObject({ + status: "partial", + parse_failures: 0, + }); + expect(report.observations.endpoints).toContainEqual( + expect.objectContaining({ value: "/kept" }), + ); + expect(report.unknowns).toContainEqual( + expect.objectContaining({ + dimension: "javascript_analysis", + affected_script_keys: [expect.any(String)], + limit: expect.objectContaining({ + parameter: "semantic_precision.getter_expansions", + effective_value: 1, + }), + }), + ); + expect(evidence.parameters).toMatchObject({ + semantic_precision: { getter_expansions: 1 }, + }); + expect(JSON.stringify(report.unknowns)).not.toContain( + "--semantic-precision", + ); + + const raised = await client.callTool({ + name: "analyze_web_bundle", + arguments: parameters, + }); + expect(raised.isError, JSON.stringify(raised.content)).not.toBe(true); + const recovered = webBundleAnalysisSchema.parse( + parseEvidence(raised.structuredContent).normalized_result, + ); + // The fake also advertises sources excluded by capture policy. Raising + // evaluator precision must clear this budget, not unrelated capture gaps. + expect( + recovered.unknowns.filter( + (entry) => + entry.limit !== undefined && + "parameter" in entry.limit && + entry.limit.parameter === "semantic_precision.getter_expansions", + ), + ).toEqual([]); + + const output = await cli.run({ + arguments: [ + "analyze-web-bundle", + browser.endpoint, + "allowed-page", + "--observation-ms", + "0", + "--semantic-precision", + '{"getter_expansions":1}', + "--format", + "json", + "--full-output", + ], + }); + expect(output.exitCode, output.stderr).toBe(0); + const envelope = z + .object({ + data: z.unknown(), + meta: z.object({ cli_controls: z.record(z.string(), z.string()) }), + }) + .parse(output.json); + const cliReport = webBundleAnalysisSchema.parse( + parseEvidence(envelope.data).normalized_result, + ); + expect(cliReport.completeness.status).toBe("partial"); + expect(envelope.meta.cli_controls).toMatchObject({ + "semantic_precision.getter_expansions": "--semantic-precision", + }); + expect(cliReport.unknowns).toContainEqual( + expect.objectContaining({ + limit: expect.objectContaining({ + parameter: "semantic_precision.getter_expansions", + effective_value: 1, + }), + }), + ); + expect(browser.activeConnectionCount()).toBe(0); + }, +);