rea-agents 1.7.0 → 2.1.0

package/dist/application/JavaScriptArtifactGraphBundlers.js

@@ -0,0 +1,225 @@
+import { addAstContainsEdge, artifactLocalIdentity, chunkLookupKey, javascriptAnalysisCoverage, moduleLookupKey, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Project Webpack/Rspack chunk and factory literals recovered from AST. */
+export const addJavaScriptBundlerNodes = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file, javascript } = analyzed;
+        const asset = context.assetNodes.get(file.path);
+        if (javascript === null || asset === undefined)
+            continue;
+        const coverage = javascriptAnalysisCoverage(javascript, context.input);
+        const records = [];
+        for (const registration of javascript.bundler_registrations) {
+            const input = {
+                file,
+                registration,
+                coverage,
+                limitations: javascript.limitations,
+            };
+            const chunk = createBundlerChunkNode(context, input);
+            addAstContainsEdge(context, {
+                source: asset,
+                target: chunk,
+                file,
+                range: registration.location,
+                coverage,
+                properties: { bundler: registration.bundler },
+            });
+            for (const key of registration.chunk_keys)
+                context.chunkNodes.set(chunkLookupKey(file.path, registration.runtime, key), chunk);
+            records.push({ file, registration, chunk, coverage });
+            addBundlerModuleNodes(context, { ...input, chunk });
+        }
+        for (const record of records)
+            addBundlerRuntimeEdges(context, record);
+    }
+};
+const createBundlerChunkNode = (context, input) => {
+    const { file, registration, coverage, limitations } = input;
+    const chunkKey = `${registration.runtime}:${registration.chunk_keys.join(",")}`;
+    return context.accumulator.addNode({
+        kind: "javascript-chunk",
+        identity: artifactLocalIdentity(file.sha256, "bundler-chunk", chunkKey),
+        observations: [
+            {
+                label: chunkKey,
+                properties: {
+                    path: file.path,
+                    bundler: registration.bundler,
+                    runtime: registration.runtime,
+                    chunk_keys: registration.chunk_keys,
+                    omitted_chunk_keys: registration.omitted_chunk_keys,
+                    unknown_chunk_keys: registration.unknown_chunk_keys,
+                    runtime_require_name: registration.runtime_require_name,
+                    runtime_module_cache_status: registration.runtime_module_cache_status,
+                    entry_module_keys: registration.entry_module_keys,
+                    omitted_entry_module_keys: registration.omitted_entry_module_keys,
+                    unknown_entry_module_keys: registration.unknown_entry_module_keys,
+                    async_chunk_keys: registration.async_chunk_keys,
+                    omitted_async_chunk_keys: registration.omitted_async_chunk_keys,
+                    unknown_async_chunk_keys: registration.unknown_async_chunk_keys,
+                    module_count: registration.modules.length,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: registration.location,
+                    operation: "extract-bundler-registration",
+                    coverage,
+                    limitations,
+                }),
+            },
+        ],
+    });
+};
+const addBundlerModuleNodes = (context, input) => {
+    const { file, registration, chunk, coverage, limitations } = input;
+    for (const moduleValue of registration.modules) {
+        const module = context.accumulator.addNode({
+            kind: "javascript-module",
+            identity: artifactLocalIdentity(file.sha256, `${registration.runtime}:module`, moduleValue.module_key),
+            observations: [
+                {
+                    label: moduleValue.module_key,
+                    properties: {
+                        path: file.path,
+                        bundler: registration.bundler,
+                        runtime: registration.runtime,
+                        chunk_keys: registration.chunk_keys,
+                        module_key: moduleValue.module_key,
+                        factory_require_name: moduleValue.factory_require_name,
+                        runtime_entry: registration.entry_module_keys.includes(moduleValue.module_key),
+                        source_sha256: moduleValue.source_sha256,
+                        structural_fingerprint_sha256: moduleValue.structural_fingerprint_sha256,
+                        structural_fingerprint_algorithm: moduleValue.structural_fingerprint_algorithm,
+                        structural_fingerprint_status: moduleValue.structural_fingerprint_status,
+                        exports: moduleValue.exports,
+                        exports_truncated: moduleValue.exports_truncated,
+                    },
+                    evidence: astObservationEvidence({
+                        sha256: file.sha256,
+                        path: file.path,
+                        range: moduleValue.location,
+                        operation: "extract-bundler-module",
+                        coverage,
+                        limitations,
+                    }),
+                },
+            ],
+        });
+        context.moduleNodes.set(moduleLookupKey(file.path, moduleValue.module_key), module);
+        addAstContainsEdge(context, {
+            source: chunk,
+            target: module,
+            file,
+            range: moduleValue.location,
+            coverage,
+            properties: {
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                chunk_keys: registration.chunk_keys,
+                module_key: moduleValue.module_key,
+            },
+        });
+    }
+};
+const addBundlerRuntimeEdges = (context, record) => {
+    const { file, registration, chunk, coverage } = record;
+    for (const moduleKey of registration.entry_module_keys) {
+        const resolved = context.moduleNodes.get(moduleLookupKey(file.path, moduleKey));
+        const target = resolved ?? unresolvedBundlerModuleNode(context, record, moduleKey);
+        context.accumulator.addEdge({
+            source_node_id: chunk.node_id,
+            target_node_id: target.node_id,
+            relation: "loads",
+            properties: {
+                kind: "bundler-entry-module",
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                module_key: moduleKey,
+                resolution_status: resolved === undefined ? "not-found" : "resolved",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: file.sha256,
+                path: file.path,
+                range: registration.location,
+                operation: "resolve-bundler-entry-module",
+                coverage,
+                confidence: resolved === undefined ? "low" : "high",
+            }),
+        });
+    }
+    for (const chunkKey of registration.async_chunk_keys) {
+        const lookup = chunkLookupKey(file.path, registration.runtime, chunkKey);
+        const resolved = context.chunkNodes.get(lookup);
+        const target = resolved ?? unresolvedBundlerChunkNode(context, record, chunkKey);
+        context.accumulator.addEdge({
+            source_node_id: chunk.node_id,
+            target_node_id: target.node_id,
+            relation: "imports",
+            properties: {
+                kind: "bundler-async-chunk",
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                chunk_key: chunkKey,
+                resolution_status: resolved === undefined ? "not-found" : "resolved",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: file.sha256,
+                path: file.path,
+                range: registration.location,
+                operation: "resolve-bundler-async-chunk",
+                coverage,
+                confidence: resolved === undefined ? "low" : "high",
+            }),
+        });
+    }
+};
+const unresolvedBundlerModuleNode = (context, record, moduleKey) => context.accumulator.addNode({
+    kind: "javascript-module",
+    identity: artifactLocalIdentity(record.file.sha256, `${record.registration.runtime}:unresolved-entry-module`, moduleKey),
+    observations: [
+        {
+            label: moduleKey,
+            properties: {
+                semantic_role: "bundler-module-reference",
+                bundler: record.registration.bundler,
+                runtime: record.registration.runtime,
+                module_key: moduleKey,
+                resolution_status: "not-found",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: record.file.sha256,
+                path: record.file.path,
+                range: record.registration.location,
+                operation: "retain-unresolved-bundler-entry-module",
+                coverage: record.coverage,
+                confidence: "low",
+            }),
+        },
+    ],
+});
+const unresolvedBundlerChunkNode = (context, record, chunkKey) => context.accumulator.addNode({
+    kind: "javascript-chunk",
+    identity: artifactLocalIdentity(record.file.sha256, `${record.registration.runtime}:unresolved-async-chunk`, chunkKey),
+    observations: [
+        {
+            label: chunkKey,
+            properties: {
+                semantic_role: "bundler-chunk-reference",
+                bundler: record.registration.bundler,
+                runtime: record.registration.runtime,
+                chunk_key: chunkKey,
+                resolution_status: "not-found",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: record.file.sha256,
+                path: record.file.path,
+                range: record.registration.location,
+                operation: "retain-unresolved-bundler-async-chunk",
+                coverage: record.coverage,
+                confidence: "low",
+            }),
+        },
+    ],
+});

package/dist/application/JavaScriptArtifactGraphContext.js

@@ -1,6 +1,6 @@
-import { posix } from "node:path";
 import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
 import { artifactObservationEvidence, astObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, staticInferenceEvidence, unavailableAstEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext, } from "./JavaScriptArtifactPathResolution.js";
 /** Add a direct artifact-containment edge. */
 export const addArtifactContainsEdge = (context, input) => {
     context.accumulator.addEdge({
@@ -103,16 +103,27 @@ export const artifactLocalIdentity = (sha256, namespace, key) => ({
     namespace: namespace.slice(0, 512),
     key: key.slice(0, 4_096),
 });
+/** Select the graph node kind for one inventoried relevant file. */
+export const artifactFileNodeKind = (kind) => kind === "javascript"
+    ? "javascript-asset"
+    : kind === "source-map"
+        ? "source-map"
+        : kind === "native-addon"
+            ? "native-addon"
+            : "artifact";
 /** Create or merge an Electron role inferred from static syntax or metadata. */
 export const createElectronRoleNode = (context, input) => context.accumulator.addNode({
     kind: input.kind,
-    identity: artifactLocalIdentity(input.anchor.sha256, "electron-role", `${input.kind}:${input.resolvedPath ?? input.declaredPath}`),
+    identity: artifactLocalIdentity(input.anchor.sha256, "electron-role", `${input.kind}:${input.resolution.resolution_context}:${input.resolution.resolved_path ?? input.resolution.declared_path}`),
     observations: [
         {
-            label: input.resolvedPath ?? input.declaredPath,
+            label: input.resolution.resolved_path ?? input.resolution.declared_path,
             properties: {
-                declared_path: input.declaredPath,
-                resolved_path: input.resolvedPath,
+                declared_path: input.resolution.declared_path,
+                resolution_context: input.resolution.resolution_context,
+                resolved_path: input.resolution.resolved_path,
+                resolution_status: input.resolution.resolution_status,
+                limitations: input.resolution.limitations,
                 mechanism: input.mechanism,
             },
             evidence: staticInferenceEvidence({
@@ -120,6 +131,7 @@ export const createElectronRoleNode = (context, input) => context.accumulator.ad
                 path: input.anchor.path,
                 operation: "discover-electron-entrypoint",
                 coverage: input.coverage ?? completeReconstructionCoverage(),
+                limitations: input.resolution.limitations,
                 ...(input.range === undefined ? {} : { range: input.range }),
             }),
         },
@@ -127,59 +139,48 @@ export const createElectronRoleNode = (context, input) => context.accumulator.ad
 });
 /** Resolve an Electron role to an inventoried asset when available. */
 export const linkElectronRoleToAsset = (context, input) => {
-    if (input.path === null)
+    const path = input.resolution.resolved_path;
+    if (path === null)
         return;
-    const asset = context.assetNodes.get(input.path) ?? context.fileNodes.get(input.path);
+    const asset = context.assetNodes.get(path) ?? context.fileNodes.get(path);
     if (asset === undefined)
         return;
     context.accumulator.addEdge({
         source_node_id: input.role.node_id,
         target_node_id: asset.node_id,
         relation: "maps_to",
-        properties: { resolved_path: input.path },
+        properties: {
+            declared_path: input.resolution.declared_path,
+            resolution_context: input.resolution.resolution_context,
+            resolved_path: path,
+            resolution_status: input.resolution.resolution_status,
+        },
         evidence: staticInferenceEvidence({
             sha256: input.anchor.sha256,
             path: input.anchor.path,
             operation: "resolve-electron-entrypoint",
             coverage: input.coverage ?? completeReconstructionCoverage(),
+            limitations: input.resolution.limitations,
             ...(input.range === undefined ? {} : { range: input.range }),
         }),
     });
 };
 /** Deterministic key for one recovered module inside a bundle asset. */
 export const moduleLookupKey = (path, moduleKey) => `${path}\0${moduleKey}`;
+/** Deterministic key for one recovered bundler chunk inside a bundle asset. */
+export const chunkLookupKey = (path, runtime, chunkKey) => `${path}\0${runtime}\0${chunkKey}`;
 /** Resolve a relative static specifier without escaping the artifact root. */
-export const resolveArtifactPath = (specifier, sourcePath, files) => {
-    const clean = specifier.split("#", 1)[0]?.split("?", 1)[0] ?? "";
-    if (clean === "" || /^[A-Za-z][A-Za-z+.-]*:/u.test(clean))
-        return null;
-    if (!clean.startsWith(".") && !clean.startsWith("/"))
-        return null;
-    const candidate = posix.normalize(clean.startsWith("/")
-        ? clean.slice(1)
-        : posix.join(posix.dirname(sourcePath), clean));
-    if (candidate === ".." || candidate.startsWith("../"))
-        return null;
-    for (const path of pathCandidates(candidate))
-        if (files.has(path))
-            return path;
-    return null;
-};
+export const resolveArtifactPath = (specifier, sourcePath, files, moduleKind) => resolveArtifactPathByContext({
+    declaredPath: specifier,
+    sourcePath,
+    context: "module-specifier",
+    files,
+    ...(moduleKind === undefined ? {} : { moduleKind }),
+}).resolved_path;
 /** Locate the recovered module that owns a static finding. */
 export const sourceNodeFor = (context, path, moduleKey) => moduleKey === null
-    ? undefined
+    ? context.sourceModuleNodes.get(path)
     : context.moduleNodes.get(moduleLookupKey(path, moduleKey));
-const pathCandidates = (path) => [
-    path,
-    `${path}.js`,
-    `${path}.mjs`,
-    `${path}.cjs`,
-    `${path}.ts`,
-    `${path}.tsx`,
-    `${path}.node`,
-    posix.join(path, "index.js"),
-    posix.join(path, "index.ts"),
-];
 /** Named AST budgets committed to graph evidence coverage. */
 export const javaScriptAnalysisLimits = (input) => [
     {

package/dist/application/JavaScriptArtifactGraphDocuments.js

@@ -1,5 +1,6 @@
-import { addArtifactContainsEdge, addStaticInferenceEdge, createElectronRoleNode, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
+import { addArtifactContainsEdge, addStaticInferenceEdge, createElectronRoleNode, linkElectronRoleToAsset, } from "./JavaScriptArtifactGraphContext.js";
 import { artifactObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
 /** Project HTML renderer entrypoints and their local script assets. */
 export const addJavaScriptHtmlRoles = (context) => {
     const byHtml = new Map();
@@ -11,11 +12,17 @@ export const addJavaScriptHtmlRoles = (context) => {
         const html = context.filesByPath.get(htmlPath);
         if (html === undefined)
             continue;
+        const roleResolution = {
+            declared_path: html.path,
+            resolution_context: "html-reference",
+            resolved_path: html.path,
+            resolution_status: "resolved",
+            limitations: [],
+        };
         const role = createElectronRoleNode(context, {
             kind: "electron-renderer",
             anchor: html,
-            declaredPath: html.path,
-            resolvedPath: html.path,
+            resolution: roleResolution,
             mechanism: "html-script-entrypoint",
         });
         addArtifactContainsEdge(context, {
@@ -24,8 +31,20 @@ export const addJavaScriptHtmlRoles = (context) => {
             file: html,
             operation: "discover-html-renderer",
         });
+        linkElectronRoleToAsset(context, {
+            role,
+            anchor: html,
+            resolution: roleResolution,
+        });
         for (const script of scripts) {
-            const resolvedPath = resolveArtifactPath(script.script_path, html.path, context.filesByPath);
+            const resolution = resolveArtifactPathByContext({
+                declaredPath: script.script_path,
+                sourcePath: html.path,
+                context: "html-reference",
+                files: context.filesByPath,
+                htmlBaseHref: script.base_href,
+            });
+            const resolvedPath = resolution.resolved_path;
             if (resolvedPath === null)
                 continue;
             const resolved = context.fileNodes.get(resolvedPath);
@@ -40,7 +59,11 @@ export const addJavaScriptHtmlRoles = (context) => {
                 relation: "loads",
                 properties: {
                     script_path: script.script_path,
+                    base_href: script.base_href,
+                    resolution_context: resolution.resolution_context,
                     resolved_path: resolvedPath,
+                    resolution_status: resolution.resolution_status,
+                    limitations: resolution.limitations,
                 },
             });
         }

package/dist/application/JavaScriptArtifactGraphEvidence.js

@@ -19,20 +19,30 @@ export const artifactObservationEvidence = (input) => ({
     evidence_ids: [],
 });
 /** Exact AST syntax evidence with an actionable source range. */
-export const astObservationEvidence = (input) => ({
-    authority: "ast-static-analysis",
-    state: "observed",
-    confidence: "exact",
-    artifact: artifactReference(input.sha256),
-    location: {
-        available: true,
-        value: { kind: "source-range", source: input.path, ...input.range },
-    },
-    extractor: { ...EXTRACTOR, operation: input.operation },
-    coverage: input.coverage,
-    limitations: [...(input.limitations ?? [])],
-    evidence_ids: [],
-});
+export const astObservationEvidence = (input) => {
+    const limitations = [
+        ...(input.limitations ?? []),
+        ...(input.coverage.status === "complete"
+            ? []
+            : [
+                "AST coverage is incomplete; omitted or dynamic facts must not be interpreted as absence.",
+            ]),
+    ];
+    return {
+        authority: "ast-static-analysis",
+        state: "observed",
+        confidence: "exact",
+        artifact: artifactReference(input.sha256),
+        location: {
+            available: true,
+            value: { kind: "source-range", source: input.path, ...input.range },
+        },
+        extractor: { ...EXTRACTOR, operation: input.operation },
+        coverage: input.coverage,
+        limitations,
+        evidence_ids: [],
+    };
+};
 /** Explicit static relationship inference; never promoted to observation. */
 export const staticInferenceEvidence = (input) => ({
     authority: "static-relationship-inference",

package/dist/application/JavaScriptArtifactGraphFindings.js

@@ -1,5 +1,6 @@
-import { addStaticInferenceEdge, artifactLocalIdentity, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
+import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
 /** Project imports, workers, roles, endpoints, storage, and source-map links. */
 export const addJavaScriptStaticFindings = (context) => {
     for (const analyzed of context.analysis.files) {
@@ -25,7 +26,7 @@ const addReference = (context, input) => {
         input.asset;
     const resolved = input.value.specifier === null
         ? null
-        : resolveReference(context, input.file.path, input.value.specifier);
+        : resolveReference(context, input.file.path, input.value);
     if (input.value.kind === "worker" || input.value.kind === "service-worker") {
         const worker = context.accumulator.addNode({
             kind: input.value.kind === "worker" ? "worker" : "service-worker",
@@ -155,12 +156,16 @@ const addStorage = (context, input) => {
     });
 };
 const addDiscoveredRole = (context, input) => {
-    const resolvedPath = resolveArtifactPath(input.value.path, input.file.path, context.filesByPath);
+    const resolution = resolveArtifactPathByContext({
+        declaredPath: input.value.path,
+        sourcePath: input.file.path,
+        context: input.value.resolution_context,
+        files: context.filesByPath,
+    });
     const role = createElectronRoleNode(context, {
         kind: input.value.role === "preload" ? "electron-preload" : "electron-renderer",
         anchor: input.file,
-        declaredPath: input.value.path,
-        resolvedPath,
+        resolution,
         mechanism: input.value.mechanism,
         range: input.value.location,
         coverage: input.coverage,
@@ -179,7 +184,7 @@ const addDiscoveredRole = (context, input) => {
     linkElectronRoleToAsset(context, {
         role,
         anchor: input.file,
-        path: resolvedPath,
+        resolution,
         range: input.value.location,
         coverage: input.coverage,
     });
@@ -228,7 +233,13 @@ const addSourceMapEdge = (context, input) => {
         },
     });
 };
-const resolveReference = (context, sourcePath, specifier) => {
+const resolveReference = (context, sourcePath, reference) => {
+    const specifier = reference.specifier;
+    if (specifier === null)
+        return null;
+    const chunk = resolveBundlerChunkReference(context, sourcePath, reference);
+    if (chunk !== null)
+        return chunk;
     const module = context.moduleNodes.get(moduleLookupKey(sourcePath, specifier));
     if (module !== undefined) {
         const file = context.filesByPath.get(sourcePath);
@@ -236,13 +247,48 @@ const resolveReference = (context, sourcePath, specifier) => {
             ? null
             : { path: `${sourcePath}#module:${specifier}`, file, node: module };
     }
-    const path = resolveArtifactPath(specifier, sourcePath, context.filesByPath);
+    const path = resolveArtifactPath(specifier, sourcePath, context.filesByPath, reference.kind === "require"
+        ? "require"
+        : reference.kind === "static-import" ||
+            reference.kind === "dynamic-import"
+            ? "import"
+            : undefined);
     if (path === null)
         return null;
     const file = context.filesByPath.get(path);
     const node = context.fileNodes.get(path);
     return file === undefined || node === undefined ? null : { path, file, node };
 };
+const resolveBundlerChunkReference = (context, sourcePath, reference) => {
+    const key = reference.specifier?.startsWith("chunk:")
+        ? reference.specifier.slice("chunk:".length)
+        : null;
+    if (key === null)
+        return null;
+    const file = context.filesByPath.get(sourcePath);
+    if (file === undefined)
+        return null;
+    const registrations = context.analysis.files
+        .find(({ file: analyzedFile }) => analyzedFile.path === sourcePath)
+        ?.javascript?.bundler_registrations.filter(({ modules }) => reference.module_key === null
+        ? true
+        : modules.some(({ module_key: moduleKey }) => moduleKey === reference.module_key));
+    if (registrations === undefined)
+        return null;
+    const candidates = registrations.flatMap(({ runtime }) => {
+        const node = context.chunkNodes.get(chunkLookupKey(sourcePath, runtime, key));
+        return node === undefined ? [] : [node];
+    });
+    const unique = [
+        ...new Map(candidates.map((node) => [node.node_id, node])).values(),
+    ];
+    if (unique.length !== 1)
+        return null;
+    const node = unique[0];
+    return node === undefined
+        ? null
+        : { path: `${sourcePath}#chunk:${key}`, file, node };
+};
 const unresolvedReferenceNode = (context, file, reference, coverage) => context.accumulator.addNode({
     kind: "javascript-module",
     identity: artifactLocalIdentity(file.sha256, "unresolved-reference", `${reference.kind}:${reference.specifier ?? reference.expression ?? "[dynamic]"}`),