fix(browser): report semantic limits reached by captured scripts (#11755)

fix(browser): retain captured-script semantic budget limits

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
This commit is contained in:
ShuaixinHuangandShuaixinHuang authored and GitHub committed 2026-11-16 12:53:04 -05:00
1 parent 3676ec632b
commit 1aad5c449d
8 files changed
+392 -7

No files matched your search

@@ -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,
@@ -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;
+6 -3
View File
@@ -27,9 +27,9 @@ export const analyzeCapturedWebScript = (
memberMutationAllowance?: JavaScriptMemberMutationAllowance,
): WebBundleScriptAnalysis => {
const accumulator = createWebBundleAnalysisAccumulator();
let routeFacts: ReturnType<typeof analyzeScript>;
let analysis: ReturnType<typeof analyzeScript>;
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,
+29 -3
View File
@@ -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 = (
+15
View File
@@ -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
? []
: [
+13 -1
View File
@@ -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<typeof semanticLimitSchema>;
/** 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 ||
+145
View File
@@ -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);
});
@@ -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);
},
);