rea-agents 2.0.0 → 2.2.0

package/dist/application/JavaScriptArtifactGraphStructure.js

@@ -1,5 +1,7 @@
-import { addArtifactContainsEdge, addAstContainsEdge, addUnavailableStaticParseScope, artifactLocalIdentity, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
-import { artifactObservationEvidence, astObservationEvidence, completeReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { addArtifactContainsEdge, addUnavailableStaticParseScope, artifactFileNodeKind, artifactLocalIdentity, createElectronRoleNode, linkElectronRoleToAsset, } from "./JavaScriptArtifactGraphContext.js";
+import { artifactObservationEvidence, completeReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+export { addJavaScriptBundlerNodes } from "./JavaScriptArtifactGraphBundlers.js";
 /** Create the exact root artifact node from the inventory manifest. */
 export const createJavaScriptArtifactRootNode = (accumulator, snapshot) => {
     const root = snapshot.nodes.find(({ artifact_id: id }) => id === snapshot.manifest.root_artifact_id);
@@ -130,6 +132,14 @@ export const addJavaScriptArtifactFiles = (context) => {
                 operation: "parse-package-json",
                 limitation: packageValue.limitation ?? "Package metadata could not be parsed.",
             });
+        const jsonValue = context.analysis.json_modules.find(({ path }) => path === file.path);
+        if (jsonValue !== undefined && jsonValue.status !== "included")
+            addUnavailableStaticParseScope(context, {
+                file,
+                asset: target,
+                operation: "parse-json-module",
+                limitation: jsonValue.limitation ?? "JSON module content could not be parsed.",
+            });
         const sourceMap = context.analysis.source_maps.find(({ path }) => path === file.path);
         if (sourceMap !== undefined &&
             (sourceMap.status === "invalid" || sourceMap.status === "not-approved"))
@@ -209,95 +219,9 @@ export const addJavaScriptPackageNodes = (context) => {
     }
     return roots;
 };
-/** 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);
-        for (const registration of javascript.bundler_registrations) {
-            const chunkKey = `${registration.runtime}:${registration.chunk_keys.join(",")}`;
-            const chunk = 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,
-                            module_count: registration.modules.length,
-                        },
-                        evidence: astObservationEvidence({
-                            sha256: file.sha256,
-                            path: file.path,
-                            range: registration.location,
-                            operation: "extract-bundler-registration",
-                            coverage,
-                            limitations: javascript.limitations,
-                        }),
-                    },
-                ],
-            });
-            addAstContainsEdge(context, {
-                source: asset,
-                target: chunk,
-                file,
-                range: registration.location,
-                coverage,
-                properties: { bundler: registration.bundler },
-            });
-            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,
-                                module_key: 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: javascript.limitations,
-                            }),
-                        },
-                    ],
-                });
-                context.moduleNodes.set(moduleLookupKey(file.path, moduleValue.module_key), module);
-                addAstContainsEdge(context, {
-                    source: chunk,
-                    target: module,
-                    file,
-                    range: moduleValue.location,
-                    coverage,
-                    properties: { module_key: moduleValue.module_key },
-                });
-            }
-        }
-    }
-};
 const createFileTarget = (context, file, javascript) => {
     const kind = artifactFileNodeKind(file.kind);
+    const json = context.analysis.json_modules.find(({ path }) => path === file.path);
     return context.accumulator.addNode({
         kind,
         identity: {
@@ -316,6 +240,9 @@ const createFileTarget = (context, file, javascript) => {
                     file_kind: file.kind,
                     text_status: file.text.included ? "included" : file.text.reason,
                     parse_status: javascript?.parse_status ?? null,
+                    json_parse_status: json?.status ?? null,
+                    json_top_level_keys: json?.top_level_keys ?? [],
+                    omitted_json_top_level_keys: json?.omitted_top_level_keys ?? 0,
                     vendor_markers: javascript?.vendors ?? [],
                 },
                 evidence: artifactObservationEvidence({
@@ -328,13 +255,6 @@ const createFileTarget = (context, file, javascript) => {
         ],
     });
 };
-const artifactFileNodeKind = (kind) => kind === "javascript"
-    ? "javascript-asset"
-    : kind === "source-map"
-        ? "source-map"
-        : kind === "native-addon"
-            ? "native-addon"
-            : "artifact";
 const createAsarEntry = (context, file) => {
     const isAsar = context.snapshot.manifest.root_format === "asar" ||
         file.container_sha256 !== context.snapshot.manifest.root_sha256;
@@ -370,12 +290,16 @@ const createAsarEntry = (context, file) => {
 const addPackageRole = (context, input) => {
     if (input.declaredPath === null)
         return;
-    const resolvedPath = resolveArtifactPath(input.declaredPath, input.packageFile.path, context.filesByPath);
+    const resolution = resolveArtifactPathByContext({
+        declaredPath: input.declaredPath,
+        sourcePath: input.packageFile.path,
+        context: "package-entrypoint",
+        files: context.filesByPath,
+    });
     const role = createElectronRoleNode(context, {
         kind: input.kind,
         anchor: input.packageFile,
-        declaredPath: input.declaredPath,
-        resolvedPath,
+        resolution,
         mechanism: input.kind === "electron-main"
             ? "package.json:main"
             : "package.json:renderer",
@@ -386,19 +310,23 @@ const addPackageRole = (context, input) => {
         relation: "loads",
         properties: {
             declared_path: input.declaredPath,
-            resolved_path: resolvedPath,
+            resolution_context: resolution.resolution_context,
+            resolved_path: resolution.resolved_path,
+            resolution_status: resolution.resolution_status,
+            limitations: resolution.limitations,
         },
         evidence: staticInferenceEvidence({
             sha256: input.packageFile.sha256,
             path: input.packageFile.path,
             operation: "discover-package-entrypoint",
             coverage: completeReconstructionCoverage(),
+            limitations: resolution.limitations,
         }),
     });
     linkElectronRoleToAsset(context, {
         role,
         anchor: input.packageFile,
-        path: resolvedPath,
+        resolution,
     });
 };
 const containerProperties = (container) => ({

package/dist/application/JavaScriptArtifactPathResolution.js

@@ -0,0 +1,269 @@
+import { builtinModules } from "node:module";
+import { posix } from "node:path";
+const EXTENSIONS = [
+    ".js",
+    ".cjs",
+    ".mjs",
+    ".ts",
+    ".tsx",
+    ".json",
+    ".html",
+    ".node",
+];
+const MAX_PACKAGE_DEPTH = 4;
+const NODE_BUILTINS = new Set(builtinModules.map((name) => name.replace(/^node:/u, "")));
+/** Resolve one declaration under its exact syntax/metadata context. */
+export const resolveArtifactPathByContext = (input) => resolveAtDepth(input, 0);
+const resolveAtDepth = (input, packageDepth) => {
+    const rejected = rejectDeclaration(input);
+    if (rejected !== null)
+        return rejected;
+    const candidate = contextualCandidate(input);
+    if (typeof candidate !== "string")
+        return candidate;
+    const confined = confineCandidate(input, candidate);
+    if (typeof confined !== "string")
+        return confined;
+    const resolved = resolveCandidate(input, confined, packageDepth);
+    return outcome(input, resolved.status, resolved.resolvedPath, resolved.limitations);
+};
+const rejectDeclaration = (input) => {
+    const declared = input.declaredPath;
+    if (declared.length === 0)
+        return outcome(input, "rejected", null, ["The declared path is empty."]);
+    if (declared.length > 4_096)
+        return outcome(input, "rejected", null, [
+            "The declared path exceeds the 4096-character resolution bound.",
+        ]);
+    if (declared.includes("\0") || declared.includes("\\"))
+        return outcome(input, "rejected", null, [
+            "NUL and backslash path syntax are not admitted for canonical artifact paths.",
+        ]);
+    if (/%(?:2e|2f|5c)/iu.test(declared))
+        return outcome(input, "rejected", null, [
+            "Encoded dot or separator bytes are rejected before artifact path resolution.",
+        ]);
+    return null;
+};
+const contextualCandidate = (input) => {
+    const { context } = input;
+    const declared = context === "module-specifier" || context === "html-reference"
+        ? stripQueryAndFragment(input.declaredPath)
+        : input.declaredPath;
+    if (context === "html-reference")
+        return htmlCandidate(input);
+    if (context === "module-specifier") {
+        const fileUrl = fileUrlPath(declared);
+        if (fileUrl !== undefined)
+            return fileUrl;
+        if (hasScheme(declared))
+            return outcome(input, "external", null, [
+                "URL and Node builtin schemes are outside static artifact module resolution.",
+            ]);
+        if (!declared.startsWith(".") && !declared.startsWith("/"))
+            return bareModuleCandidate(input, declared);
+    }
+    else if (hasScheme(declared))
+        return outcome(input, "external", null, [
+            "URL schemes are outside this local artifact path context.",
+        ]);
+    const relative = declared.startsWith("/") ? declared.slice(1) : declared;
+    return declared.startsWith("/")
+        ? relative
+        : posix.join(posix.dirname(input.sourcePath), relative);
+};
+const bareModuleCandidate = (input, declared) => {
+    const packageName = barePackageName(declared);
+    if (packageName === null ||
+        NODE_BUILTINS.has(packageName) ||
+        declared.startsWith("#"))
+        return outcome(input, "external", null, [
+            "The bare specifier is a Node builtin, package import map, or invalid package name.",
+        ]);
+    if (declared !== packageName)
+        return outcome(input, "external", null, [
+            "Bare package subpaths remain unresolved unless an exact package-exports subpath model is available.",
+        ]);
+    const source = input.files.get(input.sourcePath);
+    let directory = posix.dirname(input.sourcePath);
+    while (true) {
+        const candidate = posix.join(directory, "node_modules", declared);
+        if (hasContainerCandidate(input.files, candidate, source?.container_sha256))
+            return candidate;
+        if (directory === "." || directory === "")
+            break;
+        directory = posix.dirname(directory);
+    }
+    return outcome(input, "external", null, [
+        "No matching bare package was inventoried in an enclosing node_modules directory.",
+    ]);
+};
+const barePackageName = (specifier) => {
+    const segments = specifier.split("/");
+    if (specifier.startsWith("@"))
+        return segments.length >= 2 && segments[0] !== "" && segments[1] !== ""
+            ? `${segments[0]}/${segments[1]}`
+            : null;
+    return segments[0] === "" ? null : (segments[0] ?? null);
+};
+const hasContainerCandidate = (files, candidate, containerSha256) => [...directCandidates(candidate), posix.join(candidate, "package.json")].some((path) => {
+    const file = files.get(path);
+    return (file !== undefined &&
+        (containerSha256 === undefined ||
+            file.container_sha256 === containerSha256));
+});
+const htmlCandidate = (input) => {
+    const declared = stripQueryAndFragment(input.declaredPath);
+    if (hasScheme(declared))
+        return outcome(input, "external", null, [
+            "External HTML references are not mapped to local artifact assets.",
+        ]);
+    if (declared.startsWith("/"))
+        return declared.slice(1);
+    const base = input.htmlBaseHref;
+    if (base === undefined || base === null || base === "")
+        return posix.join(posix.dirname(input.sourcePath), declared);
+    if (hasScheme(base))
+        return outcome(input, "external", null, [
+            "The document base href is external, so its script reference is not a local artifact path.",
+        ]);
+    const basePath = base.startsWith("/")
+        ? base.slice(1)
+        : posix.join(posix.dirname(input.sourcePath), base);
+    const baseDirectory = base.endsWith("/") ? basePath : posix.dirname(basePath);
+    return posix.join(baseDirectory, declared);
+};
+const confineCandidate = (input, candidate) => {
+    const normalized = posix.normalize(candidate);
+    if (normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.startsWith("/"))
+        return outcome(input, "rejected", null, [
+            "The resolved candidate escapes the canonical artifact root.",
+        ]);
+    return normalized === "." ? "" : normalized;
+};
+const resolveCandidate = (input, candidate, packageDepth) => {
+    const source = input.files.get(input.sourcePath);
+    for (const path of directCandidates(candidate)) {
+        const target = input.files.get(path);
+        if (target !== undefined &&
+            (source === undefined ||
+                target.container_sha256 === source.container_sha256))
+            return { resolvedPath: path, status: "resolved", limitations: [] };
+    }
+    if (packageDepth >= MAX_PACKAGE_DEPTH)
+        return {
+            resolvedPath: null,
+            status: "unavailable",
+            limitations: [
+                `Directory package resolution exceeded its ${String(MAX_PACKAGE_DEPTH)}-package recursion bound.`,
+            ],
+        };
+    const packagePath = posix.join(candidate, "package.json");
+    const packageFile = input.files.get(packagePath);
+    if (packageFile === undefined ||
+        (source !== undefined &&
+            packageFile.container_sha256 !== source.container_sha256))
+        return notFoundCandidate();
+    if (!packageFile.text.included)
+        return {
+            resolvedPath: null,
+            status: "unavailable",
+            limitations: [
+                `Directory package metadata ${packagePath} was inventoried but its text is unavailable: ${packageFile.text.reason}.`,
+            ],
+        };
+    const main = packageEntry(packageFile.text.value, input.moduleKind);
+    if (main.status === "invalid")
+        return {
+            resolvedPath: null,
+            status: "unavailable",
+            limitations: [
+                `Directory package metadata ${packagePath} is not valid bounded package JSON.`,
+            ],
+        };
+    if (main.status === "missing")
+        return notFoundCandidate();
+    const nested = resolveAtDepth({
+        declaredPath: main.value,
+        sourcePath: packagePath,
+        context: "package-entrypoint",
+        files: input.files,
+    }, packageDepth + 1);
+    return {
+        resolvedPath: nested.resolved_path,
+        status: nested.resolution_status,
+        limitations: nested.limitations,
+    };
+};
+const directCandidates = (candidate) => [
+    candidate,
+    ...EXTENSIONS.map((extension) => `${candidate}${extension}`),
+    ...EXTENSIONS.map((extension) => posix.join(candidate, `index${extension}`)),
+];
+const packageEntry = (text, moduleKind) => {
+    try {
+        const value = JSON.parse(text);
+        if (typeof value !== "object" || value === null)
+            return { status: "invalid" };
+        const rawExports = Reflect.get(value, "exports");
+        if (rawExports !== undefined)
+            return packageExport(rawExports, moduleKind);
+        const preferred = moduleKind === "import"
+            ? [Reflect.get(value, "module"), Reflect.get(value, "main")]
+            : [Reflect.get(value, "main"), Reflect.get(value, "module")];
+        const entry = preferred.find((candidate) => candidate !== undefined);
+        if (entry === undefined)
+            return { status: "missing" };
+        return boundedPackagePath(entry);
+    }
+    catch {
+        return { status: "invalid" };
+    }
+};
+const packageExport = (value, moduleKind) => {
+    if (typeof value === "string")
+        return boundedPackagePath(value);
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return { status: "invalid" };
+    const root = Reflect.get(value, ".") ?? value;
+    if (typeof root === "string")
+        return boundedPackagePath(root);
+    if (typeof root !== "object" || root === null || Array.isArray(root))
+        return { status: "invalid" };
+    const condition = Reflect.get(root, moduleKind ?? "default") ?? Reflect.get(root, "default");
+    return boundedPackagePath(condition);
+};
+const boundedPackagePath = (value) => typeof value === "string" && value.length > 0 && value.length <= 4_096
+    ? { status: "value", value }
+    : { status: "invalid" };
+const notFoundCandidate = () => ({
+    resolvedPath: null,
+    status: "not-found",
+    limitations: [
+        "No bounded extension, directory package, or index candidate exists in the inventoried artifact container.",
+    ],
+});
+const hasScheme = (value) => /^[A-Za-z][A-Za-z+.-]*:/u.test(value);
+const fileUrlPath = (value) => {
+    if (!value.startsWith("file://"))
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "file:" || url.hostname !== "")
+            return undefined;
+        return decodeURIComponent(url.pathname).replace(/^\/+/, "");
+    }
+    catch {
+        return undefined;
+    }
+};
+const stripQueryAndFragment = (value) => value.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+const outcome = (input, status, resolvedPath, limitations) => ({
+    declared_path: input.declaredPath,
+    resolution_context: input.context,
+    resolved_path: resolvedPath,
+    resolution_status: status,
+    limitations,
+});

package/dist/application/JavaScriptArtifactReconstruction.js

@@ -15,7 +15,7 @@ export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
     abortIfNeeded(signal);
     const path = await realpath(input.input_path);
     const format = await resolveFormat(path, input);
-    const snapshot = await scanCanonicalArtifactInventory(path, artifactLimitsForReconstruction(input), signal);
+    const snapshot = await scanCanonicalArtifactInventory(path, artifactLimitsForReconstruction(input), { signal });
     if (snapshot.manifest.root_format !== format)
         throw new ArtifactReaderFailure("format", `Artifact inventory classified ${path} as ${snapshot.manifest.root_format}, not ${format}`);
     const reader = createReader(path, format);

package/dist/application/JavaScriptJsonModules.js

@@ -0,0 +1,39 @@
+/** Parse one approved JSON module without evaluating JavaScript or resolving imports. */
+export const analyzeJavaScriptJsonModule = (file) => {
+    if (!file.text.included)
+        return {
+            path: file.path,
+            sha256: file.sha256,
+            status: "unavailable",
+            top_level_keys: [],
+            omitted_top_level_keys: null,
+            limitation: `JSON module text was unavailable: ${file.text.reason}.`,
+        };
+    let value;
+    try {
+        value = JSON.parse(file.text.value);
+    }
+    catch {
+        return {
+            path: file.path,
+            sha256: file.sha256,
+            status: "invalid",
+            top_level_keys: [],
+            omitted_top_level_keys: 0,
+            limitation: "JSON module is not valid JSON.",
+        };
+    }
+    const keys = typeof value === "object" && value !== null && !Array.isArray(value)
+        ? Object.keys(value).sort(compareCodePoints)
+        : [];
+    const retained = keys.slice(0, 128);
+    return {
+        path: file.path,
+        sha256: file.sha256,
+        status: "included",
+        top_level_keys: retained,
+        omitted_top_level_keys: keys.length - retained.length,
+        limitation: null,
+    };
+};
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;