mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
* refactor(native): bind producer_limits and max_input_bytes as the per-call controls of pwntools and Apple dispatch refusals producerLimitControl in src/domain/producerResourceLimits.ts names one producer budget as producer_limits.<field>; the shared provider outcome classifier now carries a resource signal's limit. Pwntools file-size, CPU and output refusals and the Apple dispatch input refusal bind their control, and their remediation no longer names CLI flags. * fix(native): report the selected output allowance as the omitted file_bytes default * fix(native): bind producer_limits.diagnostic_bytes as the pwntools command output-limit control * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals (#11458) * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals * test(rust): cover the complete-report refusal's producer_limits control * refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags (#11466) * refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals * test(rust): cover the complete-report refusal's producer_limits control * refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags deadlineParameterLimit in src/domain/analysisResourceLimits.ts owns the millisecond deadline control that nativeDeadlineRecovery and the browser recoveries share. CDP command and discovery, web bundle per-script and total, network capture and source-map decode deadlines now carry it; browserDeadlineIncrease no longer takes CLI flag text. * fix(browser): record a per-script deadline's parameter control in partial web bundle results * refactor(providers): bind Wabt, SQLite, EVMole, Apktool and Go controls instead of naming CLI commands (#11472) * refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control. * refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags * fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails * ci(guards): count template-built CLI option and command text outside the CLI layer (#11478) * refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control. * refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags * fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails * ci(guards): count template-built CLI option and command text outside the CLI layer The cli-option-text-outside-cli pattern now also matches "(CLI ...", "on the CLI", "or use rea ..." and backticked `rea <command>` references, so remediation built from a template such as --${name} or rea inspect-... <path> is counted. Doctor.ts is exempt: setup and doctor run only through the CLI. The baseline records the newly counted pre-existing sites (22 -> 45 across 21 files). * ci(guards): extract the CLI text matcher, exempt host-only commands with written reasons, and test each spelling * ci(guards): exempt a host-only command and its own arguments in any matched CLI phrase * fix(native): bind producer_limits.output_bytes for oversized pwndbg debugger replies through one owner * fix(cli): name an Evidence target source failure's control by the source option that sets it * feat(cli): render the flags of result-recorded controls in the full-output envelope (#11507) * feat(cli): render the flags of result-recorded controls in the full-output envelope * fix(cli): collect result controls only for a full-output envelope, in its requested format, past undefined values * ci(guards): end a host-only command's arguments before the next CLI command * refactor(reverse): record the output budget that stopped a one-shot command as a parameter control (#11528) * fix(cli): read result controls only at positions the output schema declares as recorded controls * refactor(providers): record the controls that bounded Rust compiler paths and kernel module text instead of naming CLI options (#11532) * refactor(rust): record the control that bounded compiler-path coverage instead of naming CLI options * refactor(native): record the controls that omitted kernel module .modinfo text instead of naming CLI options (#11534) * fix(rust): describe compiler coverage from the retained result after report trimming * refactor(providers): record managed representation and JavaScript semantic ceiling controls instead of naming CLI options (#11537) * refactor(managed): record the representation budget on a resource-limit issue instead of naming its CLI option * refactor(javascript): record the semantic retention ceilings that stopped a graph instead of naming CLI options (#11540) * fix(cli): name a composed command's source options for the controls its result records * fix(cli): read result controls from the delivered Evidence when a summary wraps it * fix(rust): keep the report-byte control recorded when trimming omits every compiler path When the complete-report allowance left room for no compiler path, rustc_commit became null and its coverage.limit was lost, so --full-output could not name the option that raises the allowance. The report now records rustc_commit_omission { reason, limit } outside the dropped record, and the summary view carries it. * refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option (#11541) * refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option * test(flutter): assert the complete set of recorded string-pool budgets * feat(cli): name the options of controls a failure's partial Evidence records (#11557) meta.cli_controls was collected only from a successful result. A failure whose partial observation is Evidence of the command's own operation is now read the same way, at the positions the output schema declares as recorded controls; Evidence of another operation or a retained reference is not read. When --evidence_output publishes the partial, the delivery records it before replacing it. * refactor(javascript): record the evaluator budgets that limited sources instead of naming the CLI option (#11564) Per-value unknown reasons and the Electron wrapper limitation named --semantic-precision. The static examination now records the semantic_precision controls that limited a source (examination.controls), and analyze_javascript_application's semantic_graph.coverage.controls records every evaluator budget that limited any source (examination and semantic IR coverage), beside the retention ceilings. The CLI renders --semantic-precision from those records in meta.cli_controls; the reason texts name only the contract field.
580 lines
25 KiB
TypeScript
580 lines
25 KiB
TypeScript
import {
|
|
MAX_NODE_TIMER_DELAY_MS,
|
|
deadlineParameterLimit,
|
|
} from "./analysisResourceLimits.js";
|
|
import type { AnalysisControlLimit } from "./analysisSettings.js";
|
|
import { analysisResultLimitSchema } from "./analysisSettingDefinitions.js";
|
|
import { javaScriptSemanticPrecisionSchema } from "./javascript/javascriptSemanticPrecision.js";
|
|
import { javaScriptRefusedPhaseSchema } from "./javascript/javascriptSemanticWorkAllowance.js";
|
|
import { fetchedSourceMapLimitsSchema } from "./sourceMapLimits.js";
|
|
import { z } from "zod";
|
|
import { knownCoverageStatusSchema, coverageStatusSchema } from "./coverage.js";
|
|
import { browserExclusionSchema } from "./browserCompleteness.js";
|
|
import { webPageInspectionSchema } from "./browserObservationSchemas.js";
|
|
import { javaScriptRouteInventorySchema } from "./javascript/javascriptRouteInventory.js";
|
|
|
|
import {
|
|
browserDeadlineIncrease,
|
|
type BrowserDeadlineRecovery,
|
|
browserDeadlineRetry,
|
|
noRuntimeOverrideSentence,
|
|
optionalBrowserDeadlineMs,
|
|
} from "./browserDeadline.js";
|
|
import { emptyArraySchema } from "./emptyArraySchema.js";
|
|
import {
|
|
inspectWebPageWithSourceInputSchema,
|
|
recordedBrowserOriginSchema,
|
|
} from "./browserObservation.js";
|
|
import {
|
|
webTextArtifactMetadataSchema,
|
|
webTextArtifactSchema,
|
|
} from "./webContentArtifact.js";
|
|
|
|
/** Isolated analyzer heap used when max_heap_mb is omitted. */
|
|
export const DEFAULT_WEB_BUNDLE_HEAP_MB = 1024;
|
|
export const MIN_WEB_BUNDLE_HEAP_MB = 128;
|
|
export const MAX_WEB_BUNDLE_HEAP_MB = 16_384;
|
|
/** Per-script deadline used when analysis_timeout_ms is omitted. */
|
|
export const DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS = 30_000;
|
|
/** Total analysis deadline used when total_analysis_timeout_ms is omitted. */
|
|
export const DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS = 300_000;
|
|
/** Source-map fetch deadline used when source_map_fetch_timeout_ms is omitted. */
|
|
export const DEFAULT_SOURCE_MAP_FETCH_TIMEOUT_MS = 30_000;
|
|
|
|
const webBundleHeapDescription = `Heap phase: maximum V8 old-space for the isolated inert-script analyzer, in MiB (default ${String(DEFAULT_WEB_BUNDLE_HEAP_MB)}, range ${String(MIN_WEB_BUNDLE_HEAP_MB)}..${String(MAX_WEB_BUNDLE_HEAP_MB)}). Omitted means ${String(DEFAULT_WEB_BUNDLE_HEAP_MB)} and applies on the next call. This is not a total process RSS limit, not analysis_timeout_ms, and not total_analysis_timeout_ms. Bun ignores V8 flags; Windows Bun uses an owned process commit limit plus a 512 MiB runtime reserve, while other Bun hosts have no enforced memory limit. Raising max_heap_mb does not raise the fixed worker protocol or result byte budgets.`;
|
|
|
|
const webBundleScriptTimeoutDescription = `Per-script deadline phase: maximum startup, analysis and result transfer time for one captured script, in milliseconds (default ${String(DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS)}, range 1..${String(MAX_NODE_TIMER_DELAY_MS)}). Omitted means ${String(DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS)}. deadlineExpired for one script is not total_analysis_timeout_ms. A per-script value above the effective total is rejected. Timed-out scripts are explicit unknowns and other scripts may still be analyzed. Applies on the next call.`;
|
|
|
|
const webBundleTotalTimeoutDescription = `Total analysis deadline phase: maximum time for all captured-script analysis, in milliseconds (default ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}, range 1..${String(MAX_NODE_TIMER_DELAY_MS)}). Omitted means ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}. This is not the per-script analysis_timeout_ms, not capture, and not source-map fetch. A per-script timeout above this total is rejected. Unstarted scripts remain explicit unknowns. Applies on the next call.`;
|
|
|
|
/** Capture-and-analyze input with optional source-map fetching. */
|
|
export const analyzeWebBundleInputSchema = inspectWebPageWithSourceInputSchema
|
|
.safeExtend({
|
|
fetch_source_maps: z.boolean().default(false),
|
|
semantic_precision: javaScriptSemanticPrecisionSchema
|
|
.exactOptional()
|
|
.describe(
|
|
"Per-script semantic evaluator budgets; omitted fields preserve defaults. Independent of worker memory, deadlines and reply budgets.",
|
|
),
|
|
source_map_limits: fetchedSourceMapLimitsSchema
|
|
.exactOptional()
|
|
.describe(
|
|
"Source-map fetch/representation and decoder admission for this call. Omitted fields keep existing defaults; no restart required.",
|
|
),
|
|
max_heap_mb: z
|
|
.number()
|
|
.int()
|
|
.min(MIN_WEB_BUNDLE_HEAP_MB)
|
|
.max(MAX_WEB_BUNDLE_HEAP_MB)
|
|
.optional()
|
|
.describe(webBundleHeapDescription),
|
|
analysis_timeout_ms: optionalBrowserDeadlineMs(
|
|
webBundleScriptTimeoutDescription,
|
|
),
|
|
total_analysis_timeout_ms: optionalBrowserDeadlineMs(
|
|
webBundleTotalTimeoutDescription,
|
|
),
|
|
source_map_fetch_timeout_ms: optionalBrowserDeadlineMs(
|
|
`Source-map fetch deadline in milliseconds (default ${String(DEFAULT_SOURCE_MAP_FETCH_TIMEOUT_MS)}). Omitted means ${String(DEFAULT_SOURCE_MAP_FETCH_TIMEOUT_MS)} and applies on the next fetch. After response cleanup completes, a fetch overrun is an item limitation (fetch_failed), not a thrown analysis timeout. Pending or failed response cleanup is reported as an error with its retained owner. Response/representation and decoder budgets are independent source_map_limits fields.`,
|
|
),
|
|
})
|
|
.superRefine((input, context) => {
|
|
if (input.source_map_limits !== undefined && !input.fetch_source_maps)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["source_map_limits"],
|
|
message:
|
|
"source_map_limits requires fetch_source_maps: true; inspection does not fetch maps unless explicitly selected.",
|
|
});
|
|
const perScript =
|
|
input.analysis_timeout_ms ?? DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS;
|
|
const total =
|
|
input.total_analysis_timeout_ms ?? DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS;
|
|
if (perScript <= total) return;
|
|
context.addIssue({
|
|
code: "custom",
|
|
path:
|
|
input.analysis_timeout_ms === undefined
|
|
? ["total_analysis_timeout_ms"]
|
|
: ["analysis_timeout_ms"],
|
|
message: `analysis_timeout_ms ${String(perScript)} ms is the per-script deadline and must be less than or equal to total_analysis_timeout_ms ${String(total)} ms. A per-script timeout above the total is rejected. Omitted analysis_timeout_ms means ${String(DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS)}; omitted total_analysis_timeout_ms means ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}.`,
|
|
});
|
|
});
|
|
export type AnalyzeWebBundleInput = z.infer<typeof analyzeWebBundleInputSchema>;
|
|
|
|
/** Per-script deadlineExpired text. It is not the total analysis deadline. */
|
|
export const webBundleScriptTimeoutRecovery = (
|
|
timeoutMs: number,
|
|
): BrowserDeadlineRecovery => ({
|
|
userMessage: `analyze_web_bundle reached its ${String(timeoutMs)} ms per-script deadline (deadlineExpired) for analysis_timeout_ms. This is not total_analysis_timeout_ms and not the MCP client deadline.`,
|
|
limit: deadlineParameterLimit(
|
|
"analysis_timeout_ms",
|
|
timeoutMs,
|
|
DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS,
|
|
),
|
|
remediationAction: `${browserDeadlineIncrease("analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_SCRIPT_TIMEOUT_MS)} Keep it less than or equal to total_analysis_timeout_ms (omitted means ${String(DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)}); a per-script timeout above the total is rejected. ${browserDeadlineRetry} analysis_timeout_ms does not raise max_heap_mb, total_analysis_timeout_ms, or the fixed worker protocol and result byte budgets.`,
|
|
});
|
|
|
|
/** Total captured-script deadlineExpired text. */
|
|
export const webBundleTotalTimeoutRecovery = (
|
|
timeoutMs: number,
|
|
): BrowserDeadlineRecovery => ({
|
|
userMessage: `analyze_web_bundle reached its ${String(timeoutMs)} ms total captured-script analysis deadline (deadlineExpired) for total_analysis_timeout_ms. This is not the per-script analysis_timeout_ms, not capture, and not source-map fetch.`,
|
|
limit: deadlineParameterLimit(
|
|
"total_analysis_timeout_ms",
|
|
timeoutMs,
|
|
DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS,
|
|
),
|
|
remediationAction: `${browserDeadlineIncrease("total_analysis_timeout_ms", timeoutMs, DEFAULT_WEB_BUNDLE_TOTAL_TIMEOUT_MS)} A per-script analysis_timeout_ms above the total is rejected. ${browserDeadlineRetry} total_analysis_timeout_ms does not raise analysis_timeout_ms, max_heap_mb, source_map_fetch_timeout_ms, or the fixed worker byte budgets.`,
|
|
});
|
|
|
|
/**
|
|
* Which resource the analyzer actually exhausted.
|
|
* Node enforces the V8 old-space flag. Windows Bun enforces a process commit
|
|
* limit of that heap plus a 512 MiB reserve. Other Bun hosts enforce neither.
|
|
*/
|
|
export type WebBundleMemoryExhaustion =
|
|
| { readonly kind: "v8-heap"; readonly heapMb: number }
|
|
| {
|
|
readonly kind: "process-commit";
|
|
readonly heapMb: number;
|
|
readonly limitBytes: number;
|
|
}
|
|
| {
|
|
readonly kind: "bun-allocation";
|
|
readonly heapMb: number;
|
|
readonly processMemoryLimitBytes: number | null;
|
|
};
|
|
|
|
/** Map host facts onto the exhausted resource. The worker supplies those facts. */
|
|
export const webBundleMemoryExhaustion = (input: {
|
|
readonly runtime: "node" | "bun";
|
|
readonly heapMb: number;
|
|
readonly memoryLimitReached: boolean;
|
|
readonly processMemoryLimitBytes: number | null;
|
|
}): WebBundleMemoryExhaustion => {
|
|
if (input.runtime === "node")
|
|
return { kind: "v8-heap", heapMb: input.heapMb };
|
|
if (input.memoryLimitReached && input.processMemoryLimitBytes !== null)
|
|
return {
|
|
kind: "process-commit",
|
|
heapMb: input.heapMb,
|
|
limitBytes: input.processMemoryLimitBytes,
|
|
};
|
|
return {
|
|
kind: "bun-allocation",
|
|
heapMb: input.heapMb,
|
|
processMemoryLimitBytes: input.processMemoryLimitBytes,
|
|
};
|
|
};
|
|
|
|
const webBundleHeapRange = (): string =>
|
|
`range ${String(MIN_WEB_BUNDLE_HEAP_MB)}..${String(MAX_WEB_BUNDLE_HEAP_MB)}; omitted means ${String(DEFAULT_WEB_BUNDLE_HEAP_MB)}`;
|
|
|
|
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)}).`
|
|
: `max_heap_mb is already at the maximum ${String(MAX_WEB_BUNDLE_HEAP_MB)} MiB; do not increase it further.`;
|
|
|
|
const webBundleHeapDoesNotRaise =
|
|
"Applies on the next call. Raising max_heap_mb does not raise analysis_timeout_ms, total_analysis_timeout_ms, or the fixed worker protocol and result byte budgets. Those byte budgets have no runtime override.";
|
|
|
|
/** Heap exhaustion names the resource this runtime actually exhausted. */
|
|
export const webBundleHeapExhaustedReason = (
|
|
exhaustion: WebBundleMemoryExhaustion,
|
|
): string => {
|
|
const range = webBundleHeapRange();
|
|
switch (exhaustion.kind) {
|
|
case "v8-heap":
|
|
return `Owned web analyzer exhausted its max_heap_mb V8 old-space heap of ${String(exhaustion.heapMb)} MiB (${range}). This is the isolated analyzer heap, not a process RSS limit.`;
|
|
case "process-commit":
|
|
return `Owned web analyzer reached its ${String(exhaustion.limitBytes)}-byte process commit limit. That limit is max_heap_mb ${String(exhaustion.heapMb)} MiB plus a 512 MiB Bun runtime reserve (${range}). Bun ignores the V8 old-space flag, so this is not V8 old-space exhaustion.`;
|
|
case "bun-allocation":
|
|
return exhaustion.processMemoryLimitBytes === null
|
|
? `Owned web analyzer ran out of memory. Bun ignores the V8 old-space flag, so this exit is not the configured max_heap_mb of ${String(exhaustion.heapMb)} MiB (${range}). This host enforces no analyzer process commit limit.`
|
|
: `Owned web analyzer ran out of memory before its ${String(exhaustion.processMemoryLimitBytes)}-byte process commit limit was reported as reached. That configured limit is max_heap_mb ${String(exhaustion.heapMb)} MiB plus a 512 MiB Bun runtime reserve (${range}). Bun ignores the V8 old-space flag, so this exit is not V8 old-space exhaustion.`;
|
|
}
|
|
};
|
|
|
|
/**
|
|
* 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 => {
|
|
switch (exhaustion.kind) {
|
|
case "v8-heap":
|
|
return `${webBundleHeapIncrease(exhaustion.heapMb)} ${webBundleHeapDoesNotRaise}`;
|
|
case "process-commit":
|
|
return `${webBundleHeapIncrease(exhaustion.heapMb)} That raises the Windows process commit limit (max_heap_mb plus the fixed 512 MiB Bun runtime reserve), not a V8 old-space heap. ${webBundleHeapDoesNotRaise}`;
|
|
case "bun-allocation":
|
|
return exhaustion.processMemoryLimitBytes === null
|
|
? `Bun ignores V8 heap flags, so raising max_heap_mb does not change this exit. A reached Windows process commit limit is reported separately. Other Bun hosts enforce no analyzer heap limit. Reduce the analysis instead of increasing max_heap_mb. ${webBundleHeapDoesNotRaise}`
|
|
: `The configured ${String(exhaustion.processMemoryLimitBytes)}-byte process commit limit was not reported as reached, so raising max_heap_mb does not change this exit. A reached Windows process commit limit is reported separately. Reduce the analysis instead of increasing max_heap_mb. ${webBundleHeapDoesNotRaise}`;
|
|
}
|
|
};
|
|
|
|
export const webBundleFixedByteBudget = (
|
|
budgetBytes: number,
|
|
label: string,
|
|
): string =>
|
|
noRuntimeOverrideSentence(
|
|
`The ${String(budgetBytes)}-byte web-bundle ${label} has no further room.`,
|
|
"max_heap_mb",
|
|
);
|
|
|
|
/**
|
|
* Result admission failed because `min(fixedRemaining, hostCapacity)` is not
|
|
* positive. The fixed allowance wins when it has no room left. Host pressure
|
|
* is named only while that allowance still has room.
|
|
*/
|
|
export const webBundleResultAdmissionFailure = (input: {
|
|
readonly fixedBudgetBytes: number;
|
|
readonly fixedRemainingBytes: number;
|
|
readonly hostCapacityBytes: number;
|
|
}):
|
|
| {
|
|
readonly kind: "fixed-budget";
|
|
readonly reason: string;
|
|
readonly reportedLimits: { readonly result_bytes: number };
|
|
}
|
|
| {
|
|
readonly kind: "host-capacity";
|
|
readonly reason: string;
|
|
readonly remediationAction: string;
|
|
readonly reportedLimits: {
|
|
readonly result_bytes: number;
|
|
readonly result_budget_remaining_bytes: number;
|
|
readonly host_result_capacity_bytes: number;
|
|
};
|
|
} => {
|
|
if (input.fixedRemainingBytes <= 0)
|
|
return {
|
|
kind: "fixed-budget",
|
|
reason: webBundleFixedByteBudget(input.fixedBudgetBytes, "result budget"),
|
|
reportedLimits: { result_bytes: input.fixedBudgetBytes },
|
|
};
|
|
return {
|
|
kind: "host-capacity",
|
|
reason: `The CLI/MCP host heap has no remaining reserved capacity for another web-bundle result (host result capacity ${String(input.hostCapacityBytes)} bytes). The fixed ${String(input.fixedBudgetBytes)}-byte result budget still has ${String(input.fixedRemainingBytes)} bytes available. This is host memory pressure, not exhaustion of that fixed allowance.`,
|
|
remediationAction:
|
|
"Retry when the CLI/MCP process has more heap headroom. On Node, set NODE_OPTIONS (for example --max-old-space-size=<MiB>) in the environment that starts the CLI or MCP server, then restart that process, to raise this host heap. Raising max_heap_mb changes the isolated analyzer, not this host admission. The fixed result budget is separate and was not exhausted.",
|
|
reportedLimits: {
|
|
result_bytes: input.fixedBudgetBytes,
|
|
result_budget_remaining_bytes: input.fixedRemainingBytes,
|
|
host_result_capacity_bytes: input.hostCapacityBytes,
|
|
},
|
|
};
|
|
};
|
|
|
|
const sourceLocationSchema = z.object({
|
|
script_key: z.string(),
|
|
line: z.int().min(1).nullable(),
|
|
column: z.int().min(0).nullable(),
|
|
});
|
|
|
|
const basisSchema = z.object({
|
|
script_key: z.string(),
|
|
artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
|
line: z.int().min(1).nullable(),
|
|
column: z.int().min(0).nullable(),
|
|
detector: z.string(),
|
|
});
|
|
|
|
const findingSchema = z.object({
|
|
value: z.string(),
|
|
mechanism: z.string(),
|
|
location: sourceLocationSchema,
|
|
});
|
|
|
|
const originalSourceSchema = z.object({
|
|
source_index: z.int().min(0),
|
|
declaration_index: z.int().min(0),
|
|
source: z.string().nullable(),
|
|
artifact: webTextArtifactSchema.nullable(),
|
|
});
|
|
const originalModuleEdgeSchema = z.object({
|
|
/** The original_sources declaration this edge was read from. */
|
|
declaration_index: z.int().min(0),
|
|
from_source: z.string(),
|
|
kind: z.enum(["static_import", "dynamic_import", "require"]),
|
|
specifier: z.string(),
|
|
resolved_source: z.string().nullable(),
|
|
});
|
|
const sourceMapMappingSchema = z.object({
|
|
source_index: z.int().min(0),
|
|
declaration_index: z.int().min(0),
|
|
generated_line: z.int().min(1),
|
|
generated_column: z.int().min(0),
|
|
source: z.string().nullable(),
|
|
original_line: z.int().min(1),
|
|
original_column: z.int().min(0),
|
|
name: z.string().nullable(),
|
|
});
|
|
const sourceMapContextShape = {
|
|
script_key: z.string(),
|
|
declared_url: z.string(),
|
|
// Null when no response was observed within the approved origins.
|
|
effective_url: z.string().nullable(),
|
|
};
|
|
const parsedSourceMapShape = {
|
|
artifact: webTextArtifactSchema,
|
|
original_sources: z.array(originalSourceSchema),
|
|
original_module_edges: z.array(originalModuleEdgeSchema),
|
|
mappings: z.array(sourceMapMappingSchema),
|
|
};
|
|
const responseIdentitySchema = z.object({
|
|
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
|
bytes: z.int().min(0),
|
|
representation: z.literal("fetch-response-body-bytes"),
|
|
});
|
|
|
|
const sourceMapSchema = z.union([
|
|
z.object({
|
|
...sourceMapContextShape,
|
|
...parsedSourceMapShape,
|
|
status: z.literal("included"),
|
|
limitation: z.null(),
|
|
}),
|
|
z.object({
|
|
...sourceMapContextShape,
|
|
...parsedSourceMapShape,
|
|
status: z.literal("partial"),
|
|
limitation: z.string(),
|
|
}),
|
|
z.object({
|
|
...sourceMapContextShape,
|
|
...parsedSourceMapShape,
|
|
status: z.literal("fetch_failed"),
|
|
artifact: z.null(),
|
|
/** Present only when the complete response body was read. */
|
|
response_identity: responseIdentitySchema.exactOptional(),
|
|
original_sources: emptyArraySchema,
|
|
original_module_edges: emptyArraySchema,
|
|
mappings: emptyArraySchema,
|
|
limitation: z.string(),
|
|
}),
|
|
z.object({
|
|
...sourceMapContextShape,
|
|
...parsedSourceMapShape,
|
|
// A map is judged invalid only after its complete body was read.
|
|
status: z.literal("invalid"),
|
|
artifact: z.null(),
|
|
response_identity: responseIdentitySchema,
|
|
original_sources: emptyArraySchema,
|
|
original_module_edges: emptyArraySchema,
|
|
mappings: emptyArraySchema,
|
|
limitation: z.string(),
|
|
}),
|
|
z.object({
|
|
...sourceMapContextShape,
|
|
status: z.literal("policy_filtered"),
|
|
artifact: z.null(),
|
|
original_sources: emptyArraySchema,
|
|
original_module_edges: emptyArraySchema,
|
|
mappings: emptyArraySchema,
|
|
limitation: z.string(),
|
|
}),
|
|
]);
|
|
|
|
const webTextArtifactSummarySchema = webTextArtifactMetadataSchema.extend({
|
|
text_available: z.literal(true),
|
|
});
|
|
|
|
export const webSourceMapsSchema = z
|
|
.object({
|
|
status: z.enum(["not_requested", "included", "partial", "unavailable"]),
|
|
requested: z.int().min(0),
|
|
processed: z.int().min(0),
|
|
items: z.array(sourceMapSchema),
|
|
/** Capture exclusions retain counts/reasons without disallowed URL details. */
|
|
excluded: z
|
|
.array(
|
|
browserExclusionSchema.extend({ section: z.literal("source_maps") }),
|
|
)
|
|
.optional(),
|
|
limitation: z.string().min(1).optional(),
|
|
})
|
|
.superRefine((sourceMaps, context) => {
|
|
if (
|
|
sourceMaps.processed > sourceMaps.requested ||
|
|
sourceMaps.processed !== sourceMaps.items.length
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: "Source-map coverage counts are inconsistent",
|
|
});
|
|
if (
|
|
sourceMaps.processed < sourceMaps.requested &&
|
|
sourceMaps.limitation === undefined
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message:
|
|
"Unprocessed source maps require an explicit coverage limitation",
|
|
path: ["limitation"],
|
|
});
|
|
const statuses = sourceMaps.items.map(({ status }) => status);
|
|
const retained = statuses.filter(
|
|
(status) => status === "included" || status === "partial",
|
|
).length;
|
|
const allowedStatuses =
|
|
sourceMaps.processed < sourceMaps.requested ||
|
|
sourceMaps.excluded?.some(({ count }) => count === null || count > 0) ===
|
|
true
|
|
? retained === 0
|
|
? ["unavailable"]
|
|
: ["partial"]
|
|
: sourceMaps.items.length === 0
|
|
? ["not_requested", "unavailable"]
|
|
: retained === 0
|
|
? ["unavailable"]
|
|
: retained === sourceMaps.items.length &&
|
|
!statuses.includes("partial")
|
|
? ["included"]
|
|
: ["partial"];
|
|
if (!allowedStatuses.includes(sourceMaps.status))
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: "Source-map status contradicts retained coverage",
|
|
path: ["status"],
|
|
});
|
|
});
|
|
|
|
export type WebSourceMapItem = z.infer<typeof sourceMapSchema>;
|
|
export type WebSourceMaps = z.infer<typeof webSourceMapsSchema>;
|
|
|
|
/** Completed fetch facts retained when source-map acquisition stops early. */
|
|
export const webSourceMapFetchPartialObservationSchema = z.object({
|
|
kind: z.literal("web-source-map-fetch"),
|
|
source_maps: webSourceMapsSchema,
|
|
});
|
|
export type WebSourceMapFetchPartialObservation = z.infer<
|
|
typeof webSourceMapFetchPartialObservationSchema
|
|
>;
|
|
|
|
/** Captured page and completed maps before bundle analysis has begun. */
|
|
export const webBundleAcquisitionPartialObservationSchema = z.object({
|
|
kind: z.literal("web-bundle-acquisition"),
|
|
inspection: webPageInspectionSchema,
|
|
source_maps: webSourceMapsSchema,
|
|
analysis_status: z.literal("not_performed"),
|
|
});
|
|
export type WebBundleAcquisitionPartialObservation = z.infer<
|
|
typeof webBundleAcquisitionPartialObservationSchema
|
|
>;
|
|
|
|
/** Provider-neutral result of JavaScript bundle reverse engineering. */
|
|
export const webBundleAnalysisSchema = z.object({
|
|
route_inventory: javaScriptRouteInventorySchema.exactOptional(),
|
|
capture: z.object({
|
|
target_url: z.string(),
|
|
// The validated HTTP(S) target origin, or null when no browser origin exists.
|
|
target_origin: recordedBrowserOriginSchema.nullable(),
|
|
scripts_observed: z.int().min(0),
|
|
scripts_analyzed: z.int().min(0),
|
|
source_artifacts: z.array(webTextArtifactSummarySchema),
|
|
}),
|
|
observations: z.object({
|
|
chunks: z.object({
|
|
nodes: z.array(
|
|
z.object({
|
|
script_key: z.string(),
|
|
url: z.string(),
|
|
artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
|
bytes: z.int().min(0),
|
|
}),
|
|
),
|
|
edges: z.array(
|
|
z.object({
|
|
from_script_key: z.string(),
|
|
kind: z.enum([
|
|
"static_import",
|
|
"dynamic_import",
|
|
"require",
|
|
"worker_import",
|
|
]),
|
|
specifier: z.string(),
|
|
resolved_url: z.string().nullable(),
|
|
location: sourceLocationSchema,
|
|
}),
|
|
),
|
|
}),
|
|
routes: z.array(findingSchema),
|
|
endpoints: z.array(findingSchema),
|
|
webmcp_declarations: z.array(
|
|
z.object({
|
|
name: z.string().nullable(),
|
|
description: z.string().nullable(),
|
|
schema_property_names: z
|
|
.array(z.string())
|
|
.describe(
|
|
"Statically known own property names from the declared schema projection; a partial list may omit unresolved members.",
|
|
),
|
|
schema_property_names_coverage: z
|
|
.enum([...coverageStatusSchema.options, "not_present"])
|
|
.describe(
|
|
"Coverage of the schema property-name projection. Not a schema-validity result.",
|
|
),
|
|
trust: z.literal("page-declared-untrusted"),
|
|
location: sourceLocationSchema,
|
|
}),
|
|
),
|
|
source_maps: webSourceMapsSchema,
|
|
}),
|
|
inferences: z.array(
|
|
z.object({
|
|
kind: z.enum([
|
|
"vendor_fingerprint",
|
|
"route_framework",
|
|
"bundle_runtime",
|
|
"endpoint_candidate",
|
|
]),
|
|
value: z.string(),
|
|
confidence: z.enum(["low", "medium", "high"]),
|
|
basis: z.array(basisSchema).min(1),
|
|
}),
|
|
),
|
|
unknowns: z.array(
|
|
z.object({
|
|
dimension: z.string(),
|
|
reason: z.string(),
|
|
affected_script_keys: z.array(z.string()),
|
|
/** The setting or request parameter that bounded these scripts, and how to change it. */
|
|
limit: analysisResultLimitSchema.exactOptional(),
|
|
remediation: z.string().exactOptional(),
|
|
/**
|
|
* The phase a work allowance refused for these scripts. Their parse
|
|
* status and text inferences remain; findings that read the phase's
|
|
* facts were not examined.
|
|
*/
|
|
refused_phase: javaScriptRefusedPhaseSchema.exactOptional(),
|
|
}),
|
|
),
|
|
completeness: z.object({
|
|
status: knownCoverageStatusSchema,
|
|
parsed_scripts: z.int().min(0),
|
|
parse_failures: z.int().min(0),
|
|
visited_ast_nodes: z.int().min(0),
|
|
}),
|
|
limitations: z.array(z.string()),
|
|
});
|
|
export type WebBundleAnalysis = z.infer<typeof webBundleAnalysisSchema>;
|