rea-agents 6.3.0 → 6.5.0

package/dist/application/javascript/JavaScriptArtifactGraphFindings.js

@@ -1,11 +1,14 @@
 import { createHash } from "node:crypto";
-import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, selfReferenceOmissions, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
+import { compactStringIdentityKey } from "../../domain/compactStringIdentity.js";
+import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, selfReferenceOmissions, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
 import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
-import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+import { artifactPathResolutionProperties, resolveArtifactPathByContext, } from "./JavaScriptArtifactPathResolution.js";
+import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js";
 /** Project imports, workers, roles, endpoints, storage, and source-map links. */
-export const addJavaScriptStaticFindings = (context) => {
+export function* addJavaScriptStaticFindingsSteps(context) {
     const omissions = { selfReferences: 0 };
     for (const analyzed of context.analysis.files) {
+        yield;
         const { file, javascript } = analyzed;
         const asset = context.assetNodes.get(file.path);
         if (javascript === null || asset === undefined)
@@ -23,13 +26,12 @@ export const addJavaScriptStaticFindings = (context) => {
             addSourceMapEdge(context, { file, asset, value, coverage });
     }
     return selfReferenceOmissions(omissions.selfReferences, ["static reference", "static references"], "the referencing module");
-};
+}
 const addReference = (context, input, omissions) => {
-    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
-        input.asset;
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? input.asset;
     const resolved = input.value.specifier === null
         ? null
-        : resolveReference(context, input.file.path, input.value);
+        : resolveReference(context, input.file.path, input.value, input.coverage);
     if (input.value.kind === "worker" || input.value.kind === "service-worker") {
         const worker = context.accumulator.addNode({
             kind: input.value.kind === "worker" ? "worker" : "service-worker",
@@ -41,6 +43,8 @@ const addReference = (context, input, omissions) => {
                         declared_specifier: input.value.specifier,
                         expression: input.value.expression,
                         resolved_path: resolved?.path ?? null,
+                        resolution_status: resolved?.resolutionStatus ?? null,
+                        ...artifactPathResolutionProperties(resolved?.resolution),
                     },
                     evidence: staticInferenceEvidence({
                         sha256: input.file.sha256,
@@ -48,6 +52,7 @@ const addReference = (context, input, omissions) => {
                         range: input.value.location,
                         operation: "discover-worker",
                         coverage: input.coverage,
+                        limitations: resolved?.limitations ?? [],
                     }),
                 },
             ],
@@ -59,9 +64,14 @@ const addReference = (context, input, omissions) => {
             range: input.value.location,
             coverage: input.coverage,
             relation: "loads",
-            properties: { kind: input.value.kind },
+            properties: {
+                kind: input.value.kind,
+                resolution_status: resolved?.resolutionStatus ?? null,
+                ...artifactPathResolutionProperties(resolved?.resolution),
+            },
+            limitations: resolved?.limitations ?? [],
         });
-        if (resolved !== null)
+        if (resolved !== null && resolved.path !== null && resolved.node !== null)
             addStaticInferenceEdge(context, {
                 source: worker,
                 target: resolved.node,
@@ -70,13 +80,14 @@ const addReference = (context, input, omissions) => {
                 coverage: input.coverage,
                 relation: "maps_to",
                 properties: { resolved_path: resolved.path },
+                limitations: resolved.limitations,
             });
         return;
     }
     // A reference that resolves to its own source, such as a bundled module
     // requiring its own key, cannot become an edge: the application graph
     // forbids self-referential edges and one would fail the whole analysis.
-    if (resolved?.node.node_id === source.node_id) {
+    if (resolved?.node?.node_id === source.node_id) {
         omissions.selfReferences += 1;
         return;
     }
@@ -88,36 +99,58 @@ const addReference = (context, input, omissions) => {
         file: input.file,
         range: input.value.location,
         coverage: input.coverage,
-        relation: resolved?.file.kind === "native-addon" ? "loads" : "imports",
+        relation: resolved?.file?.kind === "native-addon" ? "loads" : "imports",
         properties: {
             kind: input.value.kind,
             specifier: input.value.specifier,
             expression: input.value.expression,
+            resolution_mode: input.value.kind === "static-import" ||
+                input.value.kind === "dynamic-import" ||
+                input.value.kind === "require"
+                ? moduleResolutionModeForJavaScriptReference(input.file.path, input.value.kind)
+                : null,
             resolved_path: resolved?.path ?? null,
+            resolution_status: resolved?.resolutionStatus ?? null,
+            ...artifactPathResolutionProperties(resolved?.resolution),
         },
+        ...(resolved === null ? {} : { limitations: resolved.limitations }),
     });
 };
 const addEndpoint = (context, input) => {
-    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
-        input.asset;
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? input.asset;
+    const key = compactStringIdentityKey(input.value.value);
+    const candidate = input.value.interpretation === "candidate";
+    const candidateLimitation = "The unbound method-like argument is only a candidate; its receiver does not establish a network call.";
+    const label = `${input.value.kind} ${candidate ? "endpoint candidate" : "endpoint"}`;
     const node = context.accumulator.addNode({
         kind: "endpoint",
-        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.value),
+        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, JSON.stringify([input.value.interpretation ?? "literal", key])),
         observations: [
             {
-                label: input.value.value,
+                label: input.value.value.length <= label.length ? input.value.value : label,
                 properties: {
                     endpoint_kind: input.value.kind,
                     value: input.value.value,
                     mechanism: input.value.mechanism,
+                    ...(candidate ? { interpretation: input.value.interpretation } : {}),
                 },
-                evidence: astObservationEvidence({
-                    sha256: input.file.sha256,
-                    path: input.file.path,
-                    range: input.value.location,
-                    operation: "discover-static-endpoint",
-                    coverage: input.coverage,
-                }),
+                evidence: candidate
+                    ? staticInferenceEvidence({
+                        sha256: input.file.sha256,
+                        path: input.file.path,
+                        range: input.value.location,
+                        operation: "classify-static-endpoint-candidate",
+                        coverage: input.coverage,
+                        confidence: "low",
+                        limitations: [candidateLimitation],
+                    })
+                    : astObservationEvidence({
+                        sha256: input.file.sha256,
+                        path: input.file.path,
+                        range: input.value.location,
+                        operation: "discover-static-endpoint",
+                        coverage: input.coverage,
+                    }),
             },
         ],
     });
@@ -128,12 +161,20 @@ const addEndpoint = (context, input) => {
         range: input.value.location,
         coverage: input.coverage,
         relation: input.value.kind === "route" ? "exposes" : "calls",
-        properties: { mechanism: input.value.mechanism },
+        properties: {
+            mechanism: input.value.mechanism,
+            ...(candidate ? { interpretation: input.value.interpretation } : {}),
+        },
+        ...(candidate
+            ? {
+                confidence: "low",
+                limitations: [candidateLimitation],
+            }
+            : {}),
     });
 };
 const addStorage = (context, input) => {
-    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
-        input.asset;
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? input.asset;
     const node = context.accumulator.addNode({
         kind: "storage",
         identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.name ?? input.value.mechanism),
@@ -171,6 +212,16 @@ const addDiscoveredRole = (context, input) => {
         sourcePath: input.file.path,
         context: input.value.resolution_context,
         files: context.filesByPath,
+        directoryPaths: context.directoryPaths,
+        unanalyzedFiles: context.unanalyzedFiles,
+        ...(input.value.role === "preload" ||
+            (input.value.role === "renderer" &&
+                input.value.resolution_context === "filesystem-expression")
+            ? { runtimePathKind: "exact-file" }
+            : input.value.role === "renderer" &&
+                input.value.resolution_context === "module-specifier"
+                ? { runtimePathKind: "url-resource" }
+                : {}),
     });
     const role = createElectronRoleNode(context, {
         kind: input.value.role === "preload" ? "electron-preload" : "electron-renderer",
@@ -180,8 +231,7 @@ const addDiscoveredRole = (context, input) => {
         range: input.value.location,
         coverage: input.coverage,
     });
-    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
-        input.asset;
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? input.asset;
     addStaticInferenceEdge(context, {
         source,
         target: role,
@@ -203,15 +253,23 @@ const addSourceMapEdge = (context, input) => {
     const declaredUrlSha256 = createHash("sha256")
         .update(input.value.declared_url)
         .digest("hex");
-    const resolvedPath = resolveArtifactPathByContext({
+    const resolution = resolveArtifactPathByContext({
         declaredPath: input.value.declared_url,
         sourcePath: input.file.path,
         context: "url-reference",
         files: context.filesByPath,
-    }).resolved_path;
+        directoryPaths: context.directoryPaths,
+        unanalyzedFiles: context.unanalyzedFiles,
+    });
+    const resolvedPath = resolution.resolved_path;
     const resolvedFile = resolvedPath === null ? undefined : context.filesByPath.get(resolvedPath);
     const resolvedNode = resolvedPath === null ? undefined : context.fileNodes.get(resolvedPath);
     const isAvailable = resolvedFile?.kind === "source-map" && resolvedNode !== undefined;
+    const limitations = isAvailable || resolution.limitations.length > 0
+        ? resolution.limitations
+        : [
+            "The declared reference does not identify an available source-map projection.",
+        ];
     const target = context.accumulator.addNode({
         kind: "source-map",
         identity: isAvailable && resolvedNode !== undefined
@@ -224,6 +282,8 @@ const addSourceMapEdge = (context, input) => {
                     declared_url: input.value.declared_url,
                     declared_url_sha256: declaredUrlSha256,
                     resolved_path: resolvedPath,
+                    resolution_status: resolution.resolution_status,
+                    ...artifactPathResolutionProperties(resolution),
                     available: isAvailable,
                 },
                 evidence: staticInferenceEvidence({
@@ -233,11 +293,7 @@ const addSourceMapEdge = (context, input) => {
                     operation: "discover-source-map",
                     coverage: input.coverage,
                     confidence: "medium",
-                    limitations: isAvailable
-                        ? []
-                        : [
-                            "The declared source map was not present in the inventoried artifact.",
-                        ],
+                    limitations,
                 }),
             },
         ],
@@ -249,45 +305,92 @@ const addSourceMapEdge = (context, input) => {
         range: input.value.location,
         coverage: input.coverage,
         relation: "maps_to",
+        limitations,
         properties: {
             declared_url_sha256: declaredUrlSha256,
             resolved_path: resolvedPath,
+            resolution_status: resolution.resolution_status,
+            ...artifactPathResolutionProperties(resolution),
         },
     });
 };
-const resolveReference = (context, sourcePath, reference) => {
+const resolveReference = (context, sourcePath, reference, coverage) => {
     const specifier = reference.specifier;
     if (specifier === null)
         return null;
-    const chunk = resolveBundlerChunkReference(context, sourcePath, reference);
+    const isWorker = reference.kind === "worker" || reference.kind === "service-worker";
+    const chunk = isWorker
+        ? null
+        : resolveBundlerChunkReference(context, sourcePath, reference);
     if (chunk !== null)
         return chunk;
-    const module = context.moduleNodes.get(moduleLookupKey(sourcePath, specifier));
+    const module = isWorker || reference.module_runtime === undefined
+        ? undefined
+        : context.moduleNodes.get(moduleLookupKey(sourcePath, reference.module_runtime, specifier));
     if (module !== undefined) {
         const file = context.filesByPath.get(sourcePath);
         return file === undefined
             ? null
-            : { path: `${sourcePath}#module:${specifier}`, file, node: module };
+            : {
+                path: `${sourcePath}#module:${specifier}`,
+                file,
+                node: module,
+                limitations: [],
+            };
     }
     // Worker scripts are URLs relative to the script, not module specifiers.
-    const path = reference.kind === "worker" || reference.kind === "service-worker"
+    const resolution = isWorker
         ? resolveArtifactPathByContext({
             declaredPath: specifier,
             sourcePath,
             context: "url-reference",
             files: context.filesByPath,
-        }).resolved_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;
+            directoryPaths: context.directoryPaths,
+            unanalyzedFiles: context.unanalyzedFiles,
+        })
+        : resolveArtifactPathByContext({
+            declaredPath: specifier,
+            sourcePath,
+            context: "module-specifier",
+            files: context.filesByPath,
+            directoryPaths: context.directoryPaths,
+            unanalyzedFiles: context.unanalyzedFiles,
+            ...("require" === reference.kind ||
+                "static-import" === reference.kind ||
+                "dynamic-import" === reference.kind
+                ? {
+                    moduleKind: moduleResolutionModeForJavaScriptReference(sourcePath, reference.kind),
+                }
+                : {}),
+        });
+    const path = resolution.resolved_path;
+    if (path === null) {
+        const source = context.filesByPath.get(sourcePath);
+        return source === undefined
+            ? null
+            : {
+                path: null,
+                file: null,
+                node: isWorker
+                    ? null
+                    : unresolvedReferenceNode(context, source, reference, coverage, resolution),
+                limitations: resolution.limitations,
+                resolutionStatus: resolution.resolution_status,
+                resolution,
+            };
+    }
     const file = context.filesByPath.get(path);
     const node = context.fileNodes.get(path);
-    return file === undefined || node === undefined ? null : { path, file, node };
+    return file === undefined || node === undefined
+        ? null
+        : {
+            path,
+            file,
+            node,
+            limitations: resolution.limitations,
+            resolutionStatus: resolution.resolution_status,
+            resolution,
+        };
 };
 const resolveBundlerChunkReference = (context, sourcePath, reference) => {
     const key = reference.specifier?.startsWith("chunk:")
@@ -300,9 +403,10 @@ const resolveBundlerChunkReference = (context, sourcePath, reference) => {
         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));
+        ?.javascript?.bundler_registrations.filter(({ runtime, modules }) => reference.module_runtime === undefined
+        ? reference.module_key === null
+        : runtime === reference.module_runtime &&
+            modules.some(({ module_key: moduleKey }) => moduleKey === reference.module_key));
     if (registrations === undefined)
         return null;
     const candidates = registrations.flatMap(({ runtime }) => {
@@ -317,9 +421,9 @@ const resolveBundlerChunkReference = (context, sourcePath, reference) => {
     const node = unique[0];
     return node === undefined
         ? null
-        : { path: `${sourcePath}#chunk:${key}`, file, node };
+        : { path: `${sourcePath}#chunk:${key}`, file, node, limitations: [] };
 };
-const unresolvedReferenceNode = (context, file, reference, coverage) => context.accumulator.addNode({
+const unresolvedReferenceNode = (context, file, reference, coverage, resolution) => context.accumulator.addNode({
     kind: "javascript-module",
     identity: artifactLocalIdentity(file.sha256, "unresolved-reference", `${reference.kind}:${reference.specifier ?? reference.expression}`),
     observations: [
@@ -330,6 +434,10 @@ const unresolvedReferenceNode = (context, file, reference, coverage) => context.
                 specifier: reference.specifier,
                 expression: reference.expression,
                 resolution: "unresolved",
+                ...(resolution === undefined
+                    ? {}
+                    : { resolution_status: resolution.resolution_status }),
+                ...artifactPathResolutionProperties(resolution),
             },
             evidence: staticInferenceEvidence({
                 sha256: file.sha256,
@@ -340,6 +448,7 @@ const unresolvedReferenceNode = (context, file, reference, coverage) => context.
                 confidence: "low",
                 limitations: [
                     "The static reference could not be resolved within the inventoried artifact.",
+                    ...(resolution?.limitations ?? []),
                 ],
             }),
         },