rea-agents 4.1.0 → 5.0.0

package/dist/domain/propertyListKeys.js

@@ -0,0 +1,69 @@
+import { parse } from "plist";
+/** The dictionary key REA results cannot carry: validation strips it. */
+const PROTOTYPE_KEY = "__proto__";
+/** Limitation for results whose source plist held `__proto__` entries. */
+export const omittedPrototypeKeysLimitation = (count) => `${String(count)} dictionary ${count === 1 ? "entry" : "entries"} keyed __proto__ ${count === 1 ? "was" : "were"} omitted because REA results cannot represent that key.`;
+const withoutKey = (value, key) => {
+    let omitted = 0;
+    const strip = (item) => {
+        if (Array.isArray(item))
+            return item.map(strip);
+        if (item === null ||
+            typeof item !== "object" ||
+            item instanceof Date ||
+            item instanceof Uint8Array)
+            return item;
+        return Object.fromEntries(Object.entries(item).flatMap(([name, entry]) => {
+            if (name !== key)
+                return [[name, strip(entry)]];
+            omitted += 1;
+            return [];
+        }));
+    };
+    const stripped = strip(value);
+    return { value: stripped, omittedPrototypeKeys: omitted };
+};
+/** Remove own `__proto__` entries, such as JSON.parse creates, and count them. */
+export const omitPrototypeKeys = (value) => withoutKey(value, PROTOTYPE_KEY);
+// Comments and CDATA text are consumed whole so only element keys match.
+const KEY_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<key>([^<]*)<\/key>|<key><!\[CDATA\[([\s\S]*?)\]\]><\/key>/gu;
+const XML_ENTITIES = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    quot: '"',
+};
+/**
+ * Expand XML character and predefined entity references. A reference beyond
+ * Unicode stays as written: comments and CDATA may hold such text literally,
+ * and the XML decoder rejects it anywhere else.
+ */
+const decodeXmlText = (text) => text.replace(/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/giu, (entity, hex, decimal, name) => {
+    const codePoint = hex !== undefined
+        ? parseInt(hex, 16)
+        : decimal !== undefined
+            ? parseInt(decimal, 10)
+            : undefined;
+    if (codePoint !== undefined)
+        return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : entity;
+    return (name === undefined ? undefined : XML_ENTITIES[name]) ?? entity;
+});
+/**
+ * Decode an XML plist whose dictionaries may use the legal key `__proto__`,
+ * which the `plist` decoder rejects outright. Those entries are omitted and
+ * counted so callers can report them instead of failing the whole document.
+ */
+export const parseXmlPropertyList = (text) => {
+    // The decoded text holds every key the decoder can produce, including
+    // entity-encoded spellings of the placeholder, so no source key aliases it.
+    // Decoding comment or CDATA text too can only lengthen the placeholder.
+    const decoded = decodeXmlText(text);
+    let placeholder = "__rea_prototype_key__";
+    while (decoded.includes(placeholder))
+        placeholder = `_${placeholder}`;
+    const substituted = text.replace(KEY_TOKEN, (token, plain, cdata) => (plain === undefined ? cdata : decodeXmlText(plain)) === PROTOTYPE_KEY
+        ? `<key>${placeholder}</key>`
+        : token);
+    return withoutKey(parse(substituted), placeholder);
+};

package/dist/domain/providerCleanupError.js

@@ -4,8 +4,11 @@ export class ProviderCleanupError extends ProviderAdapterError {
     cleanupIncomplete = true;
     cleanupResources;
     userMessage = "Provider cleanup could not be fully confirmed. Review the reported local resources before opening another target.";
-    constructor(providerId, resources, diagnostics, options) {
-        super(providerId, "close_binary", { ...options, diagnostics });
+    constructor(providerId, resources, diagnostics, 
+    /** Identify the operation owning these resources; binary callers retain their default. */
+    options) {
+        const { operation = "close_binary", ...errorOptions } = options ?? {};
+        super(providerId, operation, { ...errorOptions, diagnostics });
         this.cleanupResources = [...resources];
     }
 }

package/dist/domain/reconstructionCoverageEvaluation.js

@@ -87,13 +87,14 @@ const evaluateOwner = (context, surfaceId) => {
 };
 export const evaluateReconstructionClaims = (context) => {
     const claims = indexUnique(context.coverage.claims, "claim_id");
+    const indexes = createVerifierIndexes(context.coverage);
     for (const claimId of context.boundary.required_claim_ids) {
         const claim = claims.get(claimId);
         if (claim === undefined) {
             addReason(context, "claim-missing", claimId, "Required finite claim is absent.");
             continue;
         }
-        const contracts = context.coverage.verifier_contracts.filter(({ claim_ids: ids }) => ids.includes(claimId));
+        const contracts = indexes.contractsByClaim.get(claimId) ?? [];
         if (contracts.length === 0) {
             addReason(context, "verifier-missing", claimId, "No verifier contract covers this claim.");
             continue;
@@ -104,20 +105,49 @@ export const evaluateReconstructionClaims = (context) => {
         }
         const contract = contracts[0];
         if (contract !== undefined)
-            evaluateVerifierResult(context, claim, contract);
+            evaluateVerifierResult(context, claim, contract, indexes);
     }
 };
-const evaluateVerifierResult = (context, claim, contract) => {
-    const results = context.coverage.verifier_results
-        .filter(({ verifier_id: id }) => id === contract.verifier_id)
-        .sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at));
-    const result = results[0];
+const createVerifierIndexes = (coverage) => {
+    const contractsByClaim = new Map();
+    for (const contract of coverage.verifier_contracts)
+        for (const claimId of new Set(contract.claim_ids)) {
+            const contracts = contractsByClaim.get(claimId) ?? [];
+            contracts.push(contract);
+            contractsByClaim.set(claimId, contracts);
+        }
+    const latestResultsByVerifier = new Map();
+    for (const result of coverage.verifier_results) {
+        const latest = latestResultsByVerifier.get(result.verifier_id);
+        // Stable descending sort used to choose the first input record on ties.
+        if (latest === undefined ||
+            Date.parse(result.observed_at) > Date.parse(latest.observed_at))
+            latestResultsByVerifier.set(result.verifier_id, result);
+    }
+    const ownersBySurface = new Map();
+    for (const owner of coverage.owners) {
+        const owners = ownersBySurface.get(owner.surface_id) ?? [];
+        owners.push(owner);
+        ownersBySurface.set(owner.surface_id, owners);
+    }
+    return {
+        contractsByClaim,
+        latestResultsByVerifier,
+        artifactDigests: new Set(coverage.artifacts.map(({ artifact_sha256: value }) => value)),
+        ownerDigests: new Set(coverage.owners.flatMap(({ ownership }) => ownership.disposition === "implemented" ? [ownership.owner_sha256] : [])),
+        surfaces: indexUnique(coverage.surfaces, "surface_id"),
+        artifacts: indexUnique(coverage.artifacts, "artifact_id"),
+        ownersBySurface,
+    };
+};
+const evaluateVerifierResult = (context, claim, contract, indexes) => {
+    const result = indexes.latestResultsByVerifier.get(contract.verifier_id);
     if (result === undefined) {
         addReason(context, "verifier-result-missing", claim.claim_id, "Verifier has no recorded result.");
         return;
     }
     addEvidence(context, result.evidence_ids);
-    if (!verifierResultIsCompatible(context, claim, contract, result)) {
+    if (!verifierResultIsCompatible(claim, contract, result, indexes)) {
         addReason(context, "verifier-result-incompatible", claim.claim_id, "Latest verifier result does not match current artifacts, owners, dimensions, authority, normalization, repeats, or contract.");
         return;
     }
@@ -132,23 +162,15 @@ const evaluateVerifierResult = (context, claim, contract) => {
     else if (result.status !== "pass")
         addReason(context, "verifier-unknown", claim.claim_id, `Latest compatible verifier result is ${result.status}.`);
 };
-const verifierResultIsCompatible = (context, claim, contract, result) => {
-    const artifactDigests = new Set(context.coverage.artifacts.map(({ artifact_sha256: value }) => value));
-    const ownerDigests = new Set(context.coverage.owners.flatMap(({ ownership }) => ownership.disposition === "implemented" ? [ownership.owner_sha256] : []));
-    const surfaces = new Map(context.coverage.surfaces.map((surface) => [surface.surface_id, surface]));
-    const artifacts = new Map(context.coverage.artifacts.map((artifact) => [
-        artifact.artifact_id,
-        artifact,
-    ]));
+const verifierResultIsCompatible = (claim, contract, result, indexes) => {
     const expectedArtifactDigests = claim.surface_ids.flatMap((surfaceId) => {
-        const surface = surfaces.get(surfaceId);
-        const artifact = surface === undefined ? undefined : artifacts.get(surface.artifact_id);
+        const surface = indexes.surfaces.get(surfaceId);
+        const artifact = surface === undefined
+            ? undefined
+            : indexes.artifacts.get(surface.artifact_id);
         return artifact === undefined ? [] : [artifact.artifact_sha256];
     });
-    const expectedOwnerDigests = context.coverage.owners.flatMap(({ surface_id: surfaceId, ownership }) => claim.surface_ids.includes(surfaceId) &&
-        ownership.disposition === "implemented"
-        ? [ownership.owner_sha256]
-        : []);
+    const expectedOwnerDigests = claim.surface_ids.flatMap((surfaceId) => (indexes.ownersBySurface.get(surfaceId) ?? []).flatMap(({ ownership }) => ownership.disposition === "implemented" ? [ownership.owner_sha256] : []));
     return (result.contract_sha256 === contract.contract_sha256 &&
         result.normalization_sha256 === contract.normalization_sha256 &&
         result.covered_claim_ids.includes(claim.claim_id) &&
@@ -156,9 +178,9 @@ const verifierResultIsCompatible = (context, claim, contract, result) => {
         claim.required_dimensions.every((item) => contract.dimensions.includes(item)) &&
         claim.required_dimensions.every((item) => result.covered_dimensions.includes(item)) &&
         result.covered_dimensions.every((item) => contract.dimensions.includes(item)) &&
-        result.artifact_sha256s.every((item) => artifactDigests.has(item)) &&
+        result.artifact_sha256s.every((item) => indexes.artifactDigests.has(item)) &&
         expectedArtifactDigests.every((item) => result.artifact_sha256s.includes(item)) &&
-        result.owner_sha256s.every((item) => ownerDigests.has(item)) &&
+        result.owner_sha256s.every((item) => indexes.ownerDigests.has(item)) &&
         expectedOwnerDigests.every((item) => result.owner_sha256s.includes(item)) &&
         result.repeats >= contract.minimum_repeats &&
         claim.required_authority === contract.authority);

package/dist/domain/reconstructionCoverageInput.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { reconstructionCoverageDataSchema } from "./reconstructionCoverage.js";
+/** Named-boundary input for inline reconstruction coverage evaluation. */
+export const reconstructionCoverageEvaluationInputSchema = z.strictObject({
+    coverage: reconstructionCoverageDataSchema,
+    boundary_id: z.string().min(1),
+});

package/dist/domain/runtimeVersion.js

@@ -1,5 +1,7 @@
 import { satisfies } from "semver";
 /** Supported runtime range, kept in sync with the published package engines. */
 export const SUPPORTED_NODE_VERSION_RANGE = "^22.19.0 || ^24.11.0 || >=26.0.0";
+/** Human-readable form of {@link SUPPORTED_NODE_VERSION_RANGE} for remediation. */
+export const SUPPORTED_NODE_VERSION_PROSE = "Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+";
 /** Return whether a Node.js version satisfies REA's tested runtime families. */
 export const supportsNodeVersion = (version) => satisfies(version, SUPPORTED_NODE_VERSION_RANGE);

package/dist/domain/sourceMapEnvelope.js

@@ -0,0 +1,38 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a parsed value has the version-3 map shape. */
+export const isVersion3Map = (value) => isRecord(value) && value.version === 3;
+const isValidOffset = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+/**
+ * Collect leaf maps from an indexed source-map envelope, or undefined when
+ * the envelope is not a version-3 map. A map carrying neither `mappings`
+ * nor `sections` yields itself as the single leaf; callers decide whether
+ * that leaf is valid content.
+ */
+export const flattenSourceMapLeaves = (root, options) => {
+    if (!isVersion3Map(root))
+        return undefined;
+    const leaves = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const map = pending.pop();
+        if (!isVersion3Map(map))
+            return undefined;
+        if (Array.isArray(map.sections)) {
+            for (const section of map.sections) {
+                if (!isRecord(section) || !isRecord(section.map))
+                    return undefined;
+                if (options?.validateOffsets === true) {
+                    if (!isRecord(section.offset))
+                        return undefined;
+                    if (!isValidOffset(section.offset.line) ||
+                        !isValidOffset(section.offset.column))
+                        return undefined;
+                }
+                pending.push(section.map);
+            }
+        }
+        else
+            leaves.push(map);
+    }
+    return leaves;
+};

package/dist/domain/unicodeCodePointOrder.js

@@ -1,12 +1,17 @@
 /** Compare strings lexicographically by Unicode code point, independent of locale. */
 export const compareUnicodeCodePoints = (left, right) => {
-    const leftPoints = [...left].map((value) => value.codePointAt(0) ?? 0);
-    const rightPoints = [...right].map((value) => value.codePointAt(0) ?? 0);
-    const length = Math.min(leftPoints.length, rightPoints.length);
-    for (let index = 0; index < length; index += 1) {
-        const difference = (leftPoints[index] ?? 0) - (rightPoints[index] ?? 0);
+    let leftIndex = 0;
+    let rightIndex = 0;
+    while (leftIndex < left.length && rightIndex < right.length) {
+        const leftPoint = left.codePointAt(leftIndex) ?? 0;
+        const rightPoint = right.codePointAt(rightIndex) ?? 0;
+        const difference = leftPoint - rightPoint;
         if (difference !== 0)
             return difference;
+        leftIndex += leftPoint > 0xffff ? 2 : 1;
+        rightIndex += rightPoint > 0xffff ? 2 : 1;
     }
-    return leftPoints.length - rightPoints.length;
+    if (leftIndex === left.length && rightIndex === right.length)
+        return 0;
+    return leftIndex === left.length ? -1 : 1;
 };

package/dist/domain/webBundleAnalyzerAst.js

@@ -1,29 +1,7 @@
 import * as t from "@babel/types";
 import { sanitizeBrowserUrl } from "./browserObservation.js";
-import { semanticStaticPropertyName } from "./javascriptAstValues.js";
-/** Name of a call/new callee from its AST node. */
-export const calleeName = (callee) => {
-    if (t.isIdentifier(callee))
-        return callee.name;
-    if (t.isImport(callee))
-        return "import";
-    if (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) {
-        const object = t.isExpression(callee.object)
-            ? calleeName(callee.object)
-            : "";
-        const property = propertyName(callee.property);
-        return object === "" ? property : `${object}.${property}`;
-    }
-    return "";
-};
-export const stringArgument = (value) => (t.isStringLiteral(value) ? value.value : undefined);
-export const propertyName = (value) => {
-    if (t.isIdentifier(value))
-        return value.name;
-    if (t.isStringLiteral(value))
-        return value.value;
-    return "";
-};
+import { semanticStaticPropertyName } from "./javascript/javascriptAstValues.js";
+/** Pick the endpoint argument for common network-call patterns. */
 export const objectValue = (object, name) => {
     let value;
     for (const property of object.properties) {
@@ -69,13 +47,3 @@ export const locationFields = (node) => ({
     line: node.loc?.start.line ?? null,
     column: node.loc?.start.column ?? null,
 });
-/** Pick the endpoint argument for common network-call patterns. */
-export const endpointArgument = (name, args) => {
-    if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
-        return stringArgument(args[0]);
-    if (name.endsWith(".open") && stringArgument(args[1]) !== undefined)
-        return stringArgument(args[1]);
-    if (["get", "post", "put", "patch", "delete", "request"].some((method) => name === method || name.endsWith(`.${method}`)))
-        return stringArgument(args[0]);
-    return undefined;
-};

package/dist/domain/webBundleAnalyzerInspection.js

@@ -1,8 +1,10 @@
 import { parse } from "@babel/parser";
 import * as t from "@babel/types";
 import { sanitizeEndpointCandidate } from "./browserObservation.js";
-import { semanticStaticPropertyName } from "./javascriptAstValues.js";
-import { calleeName, endpointArgument, location, locationFields, objectString, objectValue, resolveSpecifier, isUrlLikeModuleSpecifier, stringArgument, } from "./webBundleAnalyzerAst.js";
+import { traverseJavaScriptAst } from "./javascript/javascriptSemanticTraversal.js";
+import { semanticStaticPropertyName } from "./javascript/javascriptAstValues.js";
+import { calleeName, endpointArgument, stringValue, } from "./javascript/javascriptStaticAnalysisHelpers.js";
+import { location, locationFields, objectString, objectValue, resolveSpecifier, isUrlLikeModuleSpecifier, } from "./webBundleAnalyzerAst.js";
 export const analyzeScript = (script, accumulator) => {
     let file;
     try {
@@ -20,10 +22,11 @@ export const analyzeScript = (script, accumulator) => {
     }
     accumulator.parsedScripts += 1;
     detectVendorFingerprints(script, accumulator);
-    t.traverseFast(file, (node) => {
-        accumulator.visitedNodes += 1;
-        inspectNode(script, node, accumulator);
-        return undefined;
+    traverseJavaScriptAst(file, {
+        enter: (node) => {
+            accumulator.visitedNodes += 1;
+            inspectNode(script, node, accumulator);
+        },
     });
 };
 const inspectNode = (script, node, accumulator) => {
@@ -59,7 +62,7 @@ const inspectNode = (script, node, accumulator) => {
 };
 const inspectCall = (script, node, accumulator) => {
     const name = calleeName(node.callee);
-    const first = stringArgument(node.arguments[0]);
+    const first = stringValue(node.arguments[0]);
     if ((name === "require" || name.endsWith(".require")) && first !== undefined)
         addEdge({
             script,
@@ -70,7 +73,7 @@ const inspectCall = (script, node, accumulator) => {
         });
     if (name === "importScripts" || name.endsWith(".importScripts"))
         for (const argument of node.arguments) {
-            const specifier = stringArgument(argument);
+            const specifier = stringValue(argument);
             if (specifier === undefined)
                 continue;
             addEdge({ script, specifier, kind: "worker_import", node, accumulator });
@@ -92,7 +95,7 @@ const inspectCall = (script, node, accumulator) => {
             accumulator,
         });
     }
-    const endpoint = endpointArgument(name, node.arguments);
+    const endpoint = endpointArgument(name, node.arguments, node.callee);
     if (endpoint !== undefined)
         addFinding({
             collection: accumulator.endpoints,

package/dist/domain/webEventListeners.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { webRuntimeBrowserSchema, webRuntimeLocationSchema, webRuntimeScopeSchema, webRuntimeSourceSchema, webRuntimeTargetSchema, } from "./webRuntime.js";
+/** Inspect listeners registered directly on the first main-document CSS match. */
+export const inspectWebEventListenersInputSchema = webRuntimeScopeSchema.extend({
+    selector: z.string().min(1),
+});
+/** A listener declaration and its source location do not establish that it ran. */
+export const webEventListenersSchema = z.object({
+    browser: webRuntimeBrowserSchema,
+    target: webRuntimeTargetSchema,
+    inspected_at: z.iso.datetime(),
+    selected_node: z.object({
+        selector: z.string(),
+        match: z.enum(["found", "not_found"]),
+        backend_node_id: z.number().int().min(1).nullable(),
+    }),
+    listeners: z.array(z.object({
+        type: z.string(),
+        use_capture: z.boolean(),
+        passive: z.boolean(),
+        once: z.boolean(),
+        location: webRuntimeLocationSchema,
+        execution: z.literal("unknown"),
+    })),
+    sources: z.array(webRuntimeSourceSchema),
+    cleanup: z.literal("confirmed"),
+    limitations: z.array(z.string()),
+});

package/dist/domain/webExecution.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { jsonObjectSchema } from "./jsonValue.js";
+import { webRuntimeBrowserSchema, webRuntimeLocationSchema, webRuntimeScopeSchema, webRuntimeSourceSchema, webRuntimeTargetSchema, } from "./webRuntime.js";
+/** Explicit instrumentation request for one finite, externally driven execution window. */
+export const observeWebExecutionInputSchema = webRuntimeScopeSchema.extend({
+    observation_ms: z.number().int().min(1).max(2_147_483_647).default(10_000),
+});
+const rangeSchema = z.object({
+    start_offset: z.number().int().min(0),
+    end_offset: z.number().int().min(0),
+    count: z.number().int().min(0),
+    source_bounds: z.enum(["verified", "unknown"]),
+});
+const functionSchema = z.object({
+    name: z.string(),
+    is_block_coverage: z.boolean(),
+    ranges: z.array(rangeSchema),
+});
+/** Precise V8 ranges retain their nested structure and counts without summing them. */
+export const webExecutionSchema = z.object({
+    browser: webRuntimeBrowserSchema,
+    target: webRuntimeTargetSchema,
+    window: z.object({
+        armed_at: z.iso.datetime(),
+        ended_at: z.iso.datetime(),
+        requested_ms: z.number().int().min(1),
+        end_reason: z.enum([
+            "window_elapsed",
+            "document_changed",
+            "target_terminated",
+        ]),
+        producer_started_seconds: z.number().min(0),
+        producer_sampled_seconds: z.number().min(0).nullable(),
+    }),
+    coverage: z.object({
+        state: z.enum(["captured", "unavailable"]),
+        reason: z.string().nullable(),
+        offset_units: z.literal("utf16-code-units"),
+        end_offset: z.literal("exclusive"),
+        scripts: z.array(z.object({
+            script_id: z.string().min(1),
+            reported_url: z.string(),
+            functions: z.array(functionSchema),
+        })),
+        excluded_scripts: z.number().int().min(0),
+    }),
+    requests: z.array(z.object({
+        request_id: z.string().min(1),
+        url: z.string(),
+        method: z.string(),
+        timestamp_seconds: z.number().min(0),
+        initiator_type: z.string(),
+        reported_initiator: jsonObjectSchema,
+        callsites: z.array(webRuntimeLocationSchema),
+        async_parent_ids: z.array(z.object({ id: z.string(), debugger_id: z.string().nullable() })),
+        causal_attribution: z.literal("unknown"),
+    })),
+    excluded_requests: z.number().int().min(0),
+    script_inventory: z.object({
+        main_document_scripts: z.number().int().min(0),
+        not_reported_script_ids: z.array(z.string().min(1)),
+        coverage_absence: z.literal("unknown"),
+    }),
+    sources: z.array(webRuntimeSourceSchema),
+    instrumentation: z.object({
+        resets_execution_counters: z.literal(true),
+        disables_optimized_execution: z.literal(true),
+        takes_one_resetting_sample: z.boolean(),
+        executes_selected_code: z.literal(false),
+        cleanup: z.literal("confirmed"),
+        page_ownership: z.literal("external"),
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/webMcpDiscovery.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { browserCompletenessSchema } from "./browserCompleteness.js";
 import { browserAllowedOriginsSchema, browserEndpointSchema, } from "./browserObservation.js";
+import { browserVersionSchema } from "./browserObservationSchemas.js";
 import { jsonShapeSchema } from "./jsonShape.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
 /** Input for passive discovery of page-registered WebMCP tools. */
@@ -10,13 +11,6 @@ export const discoverWebMcpToolsInputSchema = z.strictObject({
     target_id: z.string().trim().min(1),
     observation_ms: z.number().int().min(0).default(100),
 });
-const browserVersionSchema = z.object({
-    product: z.string(),
-    protocol_version: z.string(),
-    revision: z.string(),
-    user_agent: z.string(),
-    js_version: z.string(),
-});
 const webMcpToolSchema = z.object({
     tool_key: prefixedDigestSchema("webmcp"),
     name: z.string(),

package/dist/domain/webModuleImports.js

@@ -0,0 +1,104 @@
+import { isStringLiteral, isTemplateLiteral } from "@babel/types";
+import { traverseJavaScriptAst } from "./javascript/javascriptSemanticTraversal.js";
+import { parseJavaScriptSource } from "./javascript/javascriptSourceParser.js";
+/** Collect native import syntax, excluding erased type-only references. */
+export const collectWebModuleImports = (source) => {
+    const ast = parseJavaScriptSource(source);
+    if (ast === null)
+        return {
+            imports: [],
+            state: "unparseable",
+            diagnostics: ["Source could not be parsed; imports are unknown."],
+        };
+    const imports = [];
+    const add = (kind, expression) => {
+        if (expression.start === null ||
+            expression.start === undefined ||
+            expression.end === null ||
+            expression.end === undefined ||
+            expression.loc === null ||
+            expression.loc === undefined)
+            return;
+        const specifier = isStringLiteral(expression)
+            ? expression.value
+            : isTemplateLiteral(expression) && expression.expressions.length === 0
+                ? (expression.quasis[0]?.value.cooked ?? null)
+                : null;
+        imports.push({
+            kind,
+            specifier,
+            expression: source.slice(expression.start, expression.end),
+            start: {
+                offset: expression.start,
+                line: expression.loc.start.line,
+                column: expression.loc.start.column,
+            },
+            end: {
+                offset: expression.end,
+                line: expression.loc.end.line,
+                column: expression.loc.end.column,
+            },
+        });
+    };
+    traverseJavaScriptAst(ast, {
+        enter: (node) => {
+            if (node.type === "ImportDeclaration") {
+                if (node.importKind === "type" || node.importKind === "typeof")
+                    return;
+                if (node.specifiers.length > 0 &&
+                    node.specifiers.every((s) => s.type === "ImportSpecifier" &&
+                        (s.importKind === "type" || s.importKind === "typeof")))
+                    return;
+                add("static-import", node.source);
+            }
+            else if (node.type === "ExportAllDeclaration" ||
+                node.type === "ExportNamedDeclaration") {
+                if (node.exportKind === "type" ||
+                    node.source === null ||
+                    node.source === undefined)
+                    return;
+                if (node.type === "ExportNamedDeclaration" &&
+                    node.specifiers.length > 0 &&
+                    node.specifiers.every((s) => s.type === "ExportSpecifier" && s.exportKind === "type"))
+                    return;
+                add("re-export", node.source);
+            }
+            else if (node.type === "ImportExpression")
+                add("dynamic-import", node.source);
+            else if (node.type === "CallExpression" &&
+                node.callee.type === "Import" &&
+                node.arguments[0] !== undefined)
+                add("dynamic-import", node.arguments[0]);
+        },
+    });
+    imports.sort((a, b) => a.start.offset - b.start.offset);
+    return {
+        imports,
+        state: "parsed",
+        diagnostics: ast.errors?.map((error) => error.message) ?? [],
+    };
+};
+/** Match reported URLs without collapsing query or module fragment identity. */
+export const matchCapturedModules = (url, scripts) => {
+    const candidates = [];
+    scripts.forEach((script, script_index) => {
+        if (script.url === url)
+            candidates.push({ script_index, match: "exact-reported-url", script });
+        else if (script.source.kind === "scenario-response") {
+            try {
+                const transport = new URL(url);
+                transport.hash = "";
+                if (transport.href === script.url)
+                    candidates.push({
+                        script_index,
+                        match: "response-url-without-fragment",
+                        script,
+                    });
+            }
+            catch (cause) {
+                void cause;
+            }
+        }
+    });
+    return candidates;
+};