rea-agents 1.6.0 → 2.0.0

package/dist/application/JavaScriptArtifactGraphStructure.js

@@ -0,0 +1,409 @@
+import { addArtifactContainsEdge, addAstContainsEdge, addUnavailableStaticParseScope, artifactLocalIdentity, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
+import { artifactObservationEvidence, astObservationEvidence, completeReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.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);
+    if (root === undefined)
+        throw new TypeError("Artifact inventory root is missing");
+    return accumulator.addNode({
+        kind: "artifact",
+        identity: {
+            strategy: "content-digest",
+            stability: "global-exact",
+            sha256: root.sha256,
+        },
+        observations: [
+            {
+                label: "artifact root",
+                properties: {
+                    format: snapshot.manifest.root_format,
+                    bytes: root.size,
+                    inventory_manifest_id: snapshot.manifest.manifest_id,
+                    inventory_graph_sha256: snapshot.manifest.graph_sha256,
+                    inventory_artifact_id: root.artifact_id,
+                },
+                evidence: artifactObservationEvidence({
+                    sha256: root.sha256,
+                    path: "artifact-root",
+                    operation: "inventory-root",
+                    coverage: completeReconstructionCoverage(),
+                    limitations: [
+                        "artifact-root is a path-independent alias; the application result retains the canonical local input path.",
+                    ],
+                }),
+            },
+        ],
+    });
+};
+/** Project nested ASAR containers inventoried inside a directory. */
+export const addJavaScriptArtifactContainers = (context) => {
+    for (const container of context.fileSet.containers) {
+        const node = context.accumulator.addNode({
+            kind: "artifact",
+            identity: {
+                strategy: "content-digest",
+                stability: "global-exact",
+                sha256: container.sha256,
+            },
+            observations: [
+                {
+                    label: container.path,
+                    properties: containerProperties(container),
+                    evidence: artifactObservationEvidence({
+                        sha256: container.sha256,
+                        path: container.path,
+                        operation: "inventory-nested-asar",
+                        coverage: completeReconstructionCoverage(),
+                    }),
+                },
+            ],
+        });
+        context.containerNodes.set(container.sha256, node);
+        context.accumulator.addEdge({
+            source_node_id: context.root.node_id,
+            target_node_id: node.node_id,
+            relation: "contains",
+            properties: { path: container.path, format: "asar" },
+            evidence: artifactObservationEvidence({
+                sha256: context.snapshot.manifest.root_sha256,
+                path: container.path,
+                operation: "inventory-nested-asar",
+                coverage: completeReconstructionCoverage(),
+            }),
+        });
+    }
+};
+/** Project relevant files, ASAR entries, and explicit unavailable parse scopes. */
+export const addJavaScriptArtifactFiles = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file } = analyzed;
+        const target = createFileTarget(context, file, analyzed.javascript);
+        context.fileNodes.set(file.path, target);
+        if (file.kind === "javascript")
+            context.assetNodes.set(file.path, target);
+        const entry = createAsarEntry(context, file);
+        const parent = context.containerNodes.get(file.container_sha256) ?? context.root;
+        if (entry === undefined)
+            addArtifactContainsEdge(context, {
+                source: parent,
+                target,
+                file,
+                operation: "inventory-file",
+            });
+        else {
+            addArtifactContainsEdge(context, {
+                source: parent,
+                target: entry,
+                file,
+                operation: "inventory-entry",
+            });
+            context.accumulator.addEdge({
+                source_node_id: entry.node_id,
+                target_node_id: target.node_id,
+                relation: "maps_to",
+                properties: { sha256: file.sha256 },
+                evidence: artifactObservationEvidence({
+                    sha256: file.container_sha256,
+                    path: file.path,
+                    operation: "map-entry-content",
+                    coverage: completeReconstructionCoverage(),
+                }),
+            });
+        }
+        if (file.kind === "javascript" &&
+            (analyzed.javascript === null ||
+                analyzed.javascript.parse_status === "failed"))
+            addUnavailableStaticParseScope(context, {
+                file,
+                asset: target,
+                operation: "parse-javascript",
+                limitation: file.text.included
+                    ? "JavaScript syntax could not be parsed."
+                    : `JavaScript text was unavailable: ${file.text.reason}.`,
+            });
+        const packageValue = context.analysis.packages.find(({ path }) => path === file.path);
+        if (packageValue?.status !== undefined &&
+            packageValue.status !== "included")
+            addUnavailableStaticParseScope(context, {
+                file,
+                asset: target,
+                operation: "parse-package-json",
+                limitation: packageValue.limitation ?? "Package metadata 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"))
+            addUnavailableStaticParseScope(context, {
+                file,
+                asset: target,
+                operation: "parse-local-source-map",
+                limitation: sourceMap.limitation ?? "Source-map content could not be parsed.",
+            });
+    }
+};
+/** Project package metadata and its declared Electron roles. */
+export const addJavaScriptPackageNodes = (context) => {
+    const roots = [];
+    for (const packageValue of context.analysis.packages) {
+        const file = context.filesByPath.get(packageValue.path);
+        if (file === undefined)
+            continue;
+        const node = context.accumulator.addNode({
+            kind: "package",
+            identity: artifactLocalIdentity(file.sha256, "package-json", file.path),
+            observations: [
+                {
+                    label: packageValue.name ?? file.path,
+                    properties: {
+                        path: file.path,
+                        name: packageValue.name,
+                        version: packageValue.version,
+                        main: packageValue.main,
+                        renderer: packageValue.renderer,
+                        parse_status: packageValue.status,
+                    },
+                    evidence: artifactObservationEvidence({
+                        sha256: file.sha256,
+                        path: file.path,
+                        operation: "parse-package-json",
+                        coverage: completeReconstructionCoverage(),
+                        limitations: packageValue.limitation === null ? [] : [packageValue.limitation],
+                    }),
+                },
+            ],
+        });
+        if (roots.length === 0) {
+            roots.push(node);
+            context.accumulator.addEdge({
+                source_node_id: node.node_id,
+                target_node_id: context.root.node_id,
+                relation: "contains",
+                properties: { basis: "package-metadata-within-artifact" },
+                evidence: staticInferenceEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    operation: "associate-package-artifact",
+                    coverage: completeReconstructionCoverage(),
+                }),
+            });
+        }
+        else
+            addArtifactContainsEdge(context, {
+                source: context.root,
+                target: node,
+                file,
+                operation: "inventory-package",
+            });
+        addPackageRole(context, {
+            packageNode: node,
+            packageFile: file,
+            kind: "electron-main",
+            declaredPath: packageValue.main,
+        });
+        addPackageRole(context, {
+            packageNode: node,
+            packageFile: file,
+            kind: "electron-renderer",
+            declaredPath: packageValue.renderer,
+        });
+    }
+    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);
+    return context.accumulator.addNode({
+        kind,
+        identity: {
+            strategy: "content-digest",
+            stability: "global-exact",
+            sha256: file.sha256,
+        },
+        observations: [
+            {
+                label: file.path,
+                properties: {
+                    path: file.path,
+                    bytes: file.bytes,
+                    inventory_artifact_id: file.inventory_artifact_id,
+                    unpacked: file.unpacked,
+                    file_kind: file.kind,
+                    text_status: file.text.included ? "included" : file.text.reason,
+                    parse_status: javascript?.parse_status ?? null,
+                    vendor_markers: javascript?.vendors ?? [],
+                },
+                evidence: artifactObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    operation: "inventory-relevant-file",
+                    coverage: completeReconstructionCoverage(),
+                }),
+            },
+        ],
+    });
+};
+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;
+    if (!isAsar)
+        return undefined;
+    return context.accumulator.addNode({
+        kind: "asar-entry",
+        identity: {
+            strategy: "canonical-path",
+            stability: "artifact-version",
+            artifact_sha256: file.container_sha256,
+            path: file.path,
+        },
+        observations: [
+            {
+                label: file.path,
+                properties: {
+                    entry_sha256: file.sha256,
+                    bytes: file.bytes,
+                    unpacked: file.unpacked,
+                    inventory_artifact_id: file.inventory_artifact_id,
+                },
+                evidence: artifactObservationEvidence({
+                    sha256: file.container_sha256,
+                    path: file.path,
+                    operation: "inventory-asar-entry",
+                    coverage: completeReconstructionCoverage(),
+                }),
+            },
+        ],
+    });
+};
+const addPackageRole = (context, input) => {
+    if (input.declaredPath === null)
+        return;
+    const resolvedPath = resolveArtifactPath(input.declaredPath, input.packageFile.path, context.filesByPath);
+    const role = createElectronRoleNode(context, {
+        kind: input.kind,
+        anchor: input.packageFile,
+        declaredPath: input.declaredPath,
+        resolvedPath,
+        mechanism: input.kind === "electron-main"
+            ? "package.json:main"
+            : "package.json:renderer",
+    });
+    context.accumulator.addEdge({
+        source_node_id: input.packageNode.node_id,
+        target_node_id: role.node_id,
+        relation: "loads",
+        properties: {
+            declared_path: input.declaredPath,
+            resolved_path: resolvedPath,
+        },
+        evidence: staticInferenceEvidence({
+            sha256: input.packageFile.sha256,
+            path: input.packageFile.path,
+            operation: "discover-package-entrypoint",
+            coverage: completeReconstructionCoverage(),
+        }),
+    });
+    linkElectronRoleToAsset(context, {
+        role,
+        anchor: input.packageFile,
+        path: resolvedPath,
+    });
+};
+const containerProperties = (container) => ({
+    path: container.path,
+    format: "asar",
+    bytes: container.bytes,
+    inventory_artifact_id: container.inventory_artifact_id,
+});

package/dist/application/JavaScriptArtifactReconstruction.js

@@ -0,0 +1,77 @@
+import { lstat, realpath } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+import { AsarArtifactReader } from "../artifacts/AsarArtifactReader.js";
+import { ArtifactReaderFailure, } from "../artifacts/ArtifactReader.js";
+import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
+import { analyzeJavaScriptArtifactFiles } from "./JavaScriptArtifactAnalysis.js";
+import { readJavaScriptArtifactFiles } from "./JavaScriptArtifactFiles.js";
+import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.js";
+import { artifactLimitsForReconstruction, javascriptArtifactReconstructionInputSchema, } from "./JavaScriptArtifactReconstructionInput.js";
+import { scanCanonicalArtifactInventory } from "./ArtifactInventory.js";
+import { summarizeElectronBoundaries } from "./ElectronBoundaryAnalysis.js";
+/** Reconstruct one local ASAR or extracted directory without executing code. */
+export const reconstructJavaScriptArtifact = async (rawInput, signal) => {
+    const input = javascriptArtifactReconstructionInputSchema.parse(rawInput);
+    abortIfNeeded(signal);
+    const path = await realpath(input.input_path);
+    const format = await resolveFormat(path, input);
+    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);
+    try {
+        const files = await readJavaScriptArtifactFiles(reader, snapshot, input, signal);
+        const analysis = analyzeJavaScriptArtifactFiles(files, input, () => performance.now());
+        abortIfNeeded(signal);
+        const graph = buildJavaScriptArtifactGraph(snapshot, files, analysis, input);
+        return {
+            input_path: path,
+            format,
+            root_artifact_sha256: snapshot.manifest.root_sha256,
+            inventory_manifest_id: snapshot.manifest.manifest_id,
+            inventory_graph_sha256: snapshot.manifest.graph_sha256,
+            graph,
+            electron_summary: summarizeElectronBoundaries(analysis),
+            statistics: {
+                relevant_files: files.files.length,
+                nested_asar_containers: files.containers.length,
+                text_files_selected: files.text_files_selected,
+                text_bytes_read: files.text_bytes_read,
+                omitted_text_files: files.omitted_text_files,
+                limit_omitted_text_files: files.limit_omitted_text_files,
+                policy_filtered_text_files: files.policy_filtered_text_files,
+                invalid_utf8_files: files.invalid_utf8_files,
+                parsed_javascript_files: analysis.files.filter(({ javascript }) => javascript !== null).length,
+                visited_ast_nodes: analysis.visited_ast_nodes,
+                findings: analysis.findings,
+                modules: analysis.modules,
+                parse_failures: analysis.parse_failures,
+                truncated_scopes: analysis.truncated_scopes,
+            },
+            limitations: analysis.limitations,
+        };
+    }
+    finally {
+        await reader.close();
+    }
+};
+const resolveFormat = async (path, input) => {
+    const metadata = await lstat(path);
+    const observed = metadata.isDirectory()
+        ? "directory"
+        : metadata.isFile() && path.toLowerCase().endsWith(".asar")
+            ? "asar"
+            : undefined;
+    if (observed === undefined)
+        throw new ArtifactReaderFailure("format", `JavaScript artifact reconstruction accepts only a directory or .asar file: ${path}`);
+    if (input.format !== "auto" && input.format !== observed)
+        throw new ArtifactReaderFailure("format", `Requested ${input.format} input but observed ${observed}: ${path}`);
+    return observed;
+};
+const createReader = (path, format) => format === "asar"
+    ? new AsarArtifactReader(path)
+    : new DirectoryArtifactReader(path);
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "JavaScript artifact reconstruction cancelled");
+};

package/dist/application/JavaScriptArtifactReconstructionInput.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS, javascriptApplicationAnalysisLimitsSchema, } from "../domain/javascriptApplicationAnalysis.js";
+/** Local ASAR/directory reconstruction request with explicit source-map authority. */
+export const javascriptArtifactReconstructionInputSchema = z.strictObject({
+    input_path: z.string().min(1).max(16_384),
+    format: z.enum(["auto", "asar", "directory"]).default("auto"),
+    source_map_read_approved: z.boolean().default(false),
+    limits: javascriptApplicationAnalysisLimitsSchema.default(JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS),
+});
+/** Project reconstruction limits into the shared artifact traversal policy. */
+export const artifactLimitsForReconstruction = (input) => ({
+    maxEntries: input.limits.max_entries,
+    maxTotalBytes: input.limits.max_total_artifact_bytes,
+    maxEntryBytes: input.limits.max_artifact_entry_bytes,
+    maxCompressionRatio: input.limits.max_compression_ratio,
+    maxDepth: input.limits.max_depth,
+    maxPathBytes: input.limits.max_path_bytes,
+});