rea-agents 1.5.0 → 1.7.0

package/dist/application/JavaScriptArtifactGraphContext.js

@@ -0,0 +1,205 @@
+import { posix } from "node:path";
+import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
+import { artifactObservationEvidence, astObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, staticInferenceEvidence, unavailableAstEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Add a direct artifact-containment edge. */
+export const addArtifactContainsEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: "contains",
+        properties: { path: input.file.path },
+        evidence: artifactObservationEvidence({
+            sha256: input.operation === "inventory-entry"
+                ? input.file.container_sha256
+                : input.file.sha256,
+            path: input.file.path,
+            operation: input.operation,
+            coverage: completeReconstructionCoverage(),
+        }),
+    });
+};
+/** Add an exact AST containment edge. */
+export const addAstContainsEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: "contains",
+        properties: input.properties,
+        evidence: astObservationEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: "map-bundler-structure",
+            coverage: input.coverage,
+        }),
+    });
+};
+/** Add an explicitly inferred static relationship edge. */
+export const addStaticInferenceEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: staticInferenceEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: "map-static-relationship",
+            coverage: input.coverage,
+        }),
+    });
+};
+/** Preserve a static parse or approval gap as an explicit unknown scope. */
+export const addUnavailableStaticParseScope = (context, input) => {
+    const node = context.accumulator.addNode({
+        kind: "unknown",
+        identity: artifactLocalIdentity(input.file.sha256, "static-parse-scope", `${input.operation}:${input.file.path}`),
+        observations: [
+            {
+                label: `${input.file.path} parse scope`,
+                properties: {
+                    path: input.file.path,
+                    operation: input.operation,
+                    limitation: input.limitation,
+                },
+                evidence: unavailableAstEvidence({
+                    sha256: input.file.sha256,
+                    path: input.file.path,
+                    operation: input.operation,
+                    coverage: partialReconstructionCoverage([], null, false),
+                    limitation: input.limitation,
+                }),
+            },
+        ],
+    });
+    context.accumulator.addEdge({
+        source_node_id: input.asset.node_id,
+        target_node_id: node.node_id,
+        relation: "contains",
+        properties: { scope: "unavailable-static-analysis" },
+        evidence: artifactObservationEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            operation: "associate-unavailable-parse-scope",
+            coverage: completeReconstructionCoverage(),
+        }),
+    });
+};
+/** Coverage for one bounded JavaScript AST analysis. */
+export const javascriptAnalysisCoverage = (analysis, input) => analysis.parse_status === "complete"
+    ? completeReconstructionCoverage(javaScriptAnalysisLimits(input))
+    : {
+        status: "partial",
+        truncated: analysis.parse_status === "truncated",
+        omitted_count: null,
+        limits: javaScriptAnalysisLimits(input),
+    };
+/** Stable identity for a fact scoped to one exact artifact. */
+export const artifactLocalIdentity = (sha256, namespace, key) => ({
+    strategy: "artifact-local-key",
+    stability: "artifact-version",
+    artifact_sha256: sha256,
+    namespace: namespace.slice(0, 512),
+    key: key.slice(0, 4_096),
+});
+/** 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}`),
+    observations: [
+        {
+            label: input.resolvedPath ?? input.declaredPath,
+            properties: {
+                declared_path: input.declaredPath,
+                resolved_path: input.resolvedPath,
+                mechanism: input.mechanism,
+            },
+            evidence: staticInferenceEvidence({
+                sha256: input.anchor.sha256,
+                path: input.anchor.path,
+                operation: "discover-electron-entrypoint",
+                coverage: input.coverage ?? completeReconstructionCoverage(),
+                ...(input.range === undefined ? {} : { range: input.range }),
+            }),
+        },
+    ],
+});
+/** Resolve an Electron role to an inventoried asset when available. */
+export const linkElectronRoleToAsset = (context, input) => {
+    if (input.path === null)
+        return;
+    const asset = context.assetNodes.get(input.path) ?? context.fileNodes.get(input.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 },
+        evidence: staticInferenceEvidence({
+            sha256: input.anchor.sha256,
+            path: input.anchor.path,
+            operation: "resolve-electron-entrypoint",
+            coverage: input.coverage ?? completeReconstructionCoverage(),
+            ...(input.range === undefined ? {} : { range: input.range }),
+        }),
+    });
+};
+/** Deterministic key for one recovered module inside a bundle asset. */
+export const moduleLookupKey = (path, moduleKey) => `${path}\0${moduleKey}`;
+/** 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;
+};
+/** Locate the recovered module that owns a static finding. */
+export const sourceNodeFor = (context, path, moduleKey) => moduleKey === null
+    ? undefined
+    : 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) => [
+    {
+        name: "max-ast-nodes",
+        value: input.limits.max_ast_nodes,
+        unit: "items",
+    },
+    {
+        name: "max-findings",
+        value: input.limits.max_findings,
+        unit: "items",
+    },
+    {
+        name: "max-modules",
+        value: input.limits.max_modules,
+        unit: "items",
+    },
+    {
+        name: "max-parse-milliseconds",
+        value: input.limits.max_parse_milliseconds,
+        unit: "milliseconds",
+    },
+];

package/dist/application/JavaScriptArtifactGraphDocuments.js

@@ -0,0 +1,108 @@
+import { addArtifactContainsEdge, addStaticInferenceEdge, createElectronRoleNode, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
+import { artifactObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Project HTML renderer entrypoints and their local script assets. */
+export const addJavaScriptHtmlRoles = (context) => {
+    const byHtml = new Map();
+    for (const script of context.analysis.html_scripts) {
+        const existing = byHtml.get(script.html_path);
+        byHtml.set(script.html_path, existing === undefined ? [script] : [...existing, script]);
+    }
+    for (const [htmlPath, scripts] of byHtml) {
+        const html = context.filesByPath.get(htmlPath);
+        if (html === undefined)
+            continue;
+        const role = createElectronRoleNode(context, {
+            kind: "electron-renderer",
+            anchor: html,
+            declaredPath: html.path,
+            resolvedPath: html.path,
+            mechanism: "html-script-entrypoint",
+        });
+        addArtifactContainsEdge(context, {
+            source: context.root,
+            target: role,
+            file: html,
+            operation: "discover-html-renderer",
+        });
+        for (const script of scripts) {
+            const resolvedPath = resolveArtifactPath(script.script_path, html.path, context.filesByPath);
+            if (resolvedPath === null)
+                continue;
+            const resolved = context.fileNodes.get(resolvedPath);
+            if (resolved === undefined)
+                continue;
+            addStaticInferenceEdge(context, {
+                source: role,
+                target: resolved,
+                file: html,
+                range: script.location,
+                coverage: completeReconstructionCoverage(),
+                relation: "loads",
+                properties: {
+                    script_path: script.script_path,
+                    resolved_path: resolvedPath,
+                },
+            });
+        }
+    }
+};
+/** Project original source names and optional content digests from approved maps. */
+export const addJavaScriptSourceMapOriginals = (context) => {
+    for (const sourceMap of context.analysis.source_maps) {
+        const mapFile = context.filesByPath.get(sourceMap.path);
+        const mapNode = context.fileNodes.get(sourceMap.path);
+        if (mapFile === undefined || mapNode === undefined)
+            continue;
+        const coverage = sourceMap.status === "truncated"
+            ? partialReconstructionCoverage([
+                {
+                    name: "max-source-map-sources",
+                    value: context.input.limits.max_source_map_sources,
+                    unit: "items",
+                },
+            ], sourceMap.omitted_sources, true)
+            : completeReconstructionCoverage();
+        for (const original of sourceMap.sources) {
+            const node = context.accumulator.addNode({
+                kind: "source-module",
+                identity: {
+                    strategy: "source-map-original",
+                    stability: "source-map-exact",
+                    source_map_sha256: mapFile.sha256,
+                    original_source: original.source,
+                    source_sha256: original.content_sha256,
+                },
+                observations: [
+                    {
+                        label: original.source,
+                        properties: {
+                            source: original.source,
+                            content_available: original.content !== null,
+                            source_sha256: original.content_sha256,
+                        },
+                        evidence: artifactObservationEvidence({
+                            sha256: mapFile.sha256,
+                            path: mapFile.path,
+                            operation: "parse-local-source-map",
+                            coverage,
+                            limitations: sourceMap.limitation === null ? [] : [sourceMap.limitation],
+                        }),
+                    },
+                ],
+            });
+            context.accumulator.addEdge({
+                source_node_id: mapNode.node_id,
+                target_node_id: node.node_id,
+                relation: "contains",
+                properties: { original_source: original.source },
+                evidence: artifactObservationEvidence({
+                    sha256: mapFile.sha256,
+                    path: mapFile.path,
+                    operation: "parse-local-source-map",
+                    coverage,
+                    limitations: sourceMap.limitation === null ? [] : [sourceMap.limitation],
+                }),
+            });
+        }
+    }
+};

package/dist/application/JavaScriptArtifactGraphEvidence.js

@@ -0,0 +1,89 @@
+const EXTRACTOR = {
+    name: "rea-javascript-artifact-reconstruction",
+    version: "1",
+    executable_sha256: null,
+};
+/** Exact artifact-byte evidence for one safely inventoried local file. */
+export const artifactObservationEvidence = (input) => ({
+    authority: "artifact-bytes",
+    state: "observed",
+    confidence: "exact",
+    artifact: artifactReference(input.sha256),
+    location: {
+        available: true,
+        value: { kind: "artifact-path", path: input.path },
+    },
+    extractor: { ...EXTRACTOR, operation: input.operation },
+    coverage: input.coverage,
+    limitations: [...(input.limitations ?? [])],
+    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: [],
+});
+/** Explicit static relationship inference; never promoted to observation. */
+export const staticInferenceEvidence = (input) => ({
+    authority: "static-relationship-inference",
+    state: "inferred",
+    confidence: input.confidence ?? "high",
+    artifact: artifactReference(input.sha256),
+    location: input.range === undefined
+        ? { available: true, value: { kind: "artifact-path", path: input.path } }
+        : {
+            available: true,
+            value: { kind: "source-range", source: input.path, ...input.range },
+        },
+    extractor: { ...EXTRACTOR, operation: input.operation },
+    coverage: input.coverage,
+    limitations: [
+        "Static syntax does not prove that this relationship executes at runtime.",
+        ...(input.limitations ?? []),
+    ],
+    evidence_ids: [],
+});
+/** Unavailable AST fact that preserves a parse, approval, or limit gap. */
+export const unavailableAstEvidence = (input) => ({
+    authority: "ast-static-analysis",
+    state: "unavailable",
+    confidence: "unknown",
+    artifact: artifactReference(input.sha256),
+    location: {
+        available: true,
+        value: { kind: "artifact-path", path: input.path },
+    },
+    extractor: { ...EXTRACTOR, operation: input.operation },
+    coverage: input.coverage,
+    limitations: [input.limitation, ...(input.limitations ?? [])],
+    evidence_ids: [],
+});
+/** Complete local projection coverage under named hard limits. */
+export const completeReconstructionCoverage = (limits = []) => ({
+    status: "complete",
+    truncated: false,
+    omitted_count: 0,
+    limits: [...limits],
+});
+/** Partial reconstruction coverage with either exact truncation or a policy gap. */
+export const partialReconstructionCoverage = (limits, omitted, truncated) => ({
+    status: "partial",
+    truncated,
+    omitted_count: omitted,
+    limits: [...limits],
+});
+const artifactReference = (sha256) => ({
+    available: true,
+    artifact_id: `art_${sha256}`,
+    sha256,
+});

package/dist/application/JavaScriptArtifactGraphFindings.js

@@ -0,0 +1,271 @@
+import { addStaticInferenceEdge, artifactLocalIdentity, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Project imports, workers, roles, endpoints, storage, and source-map links. */
+export const addJavaScriptStaticFindings = (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 value of javascript.references)
+            addReference(context, { file, asset, value, coverage });
+        for (const value of javascript.endpoints)
+            addEndpoint(context, { file, asset, value, coverage });
+        for (const value of javascript.storage)
+            addStorage(context, { file, asset, value, coverage });
+        for (const value of javascript.role_paths)
+            addDiscoveredRole(context, { file, asset, value, coverage });
+        for (const value of javascript.source_map_urls)
+            addSourceMapEdge(context, { file, asset, value, coverage });
+    }
+};
+const addReference = (context, input) => {
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
+        input.asset;
+    const resolved = input.value.specifier === null
+        ? null
+        : resolveReference(context, input.file.path, input.value.specifier);
+    if (input.value.kind === "worker" || input.value.kind === "service-worker") {
+        const worker = context.accumulator.addNode({
+            kind: input.value.kind === "worker" ? "worker" : "service-worker",
+            identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.specifier ?? input.value.expression ?? "[dynamic]"),
+            observations: [
+                {
+                    label: input.value.specifier,
+                    properties: {
+                        declared_specifier: input.value.specifier,
+                        expression: input.value.expression,
+                        resolved_path: resolved?.path ?? null,
+                    },
+                    evidence: staticInferenceEvidence({
+                        sha256: input.file.sha256,
+                        path: input.file.path,
+                        range: input.value.location,
+                        operation: "discover-worker",
+                        coverage: input.coverage,
+                    }),
+                },
+            ],
+        });
+        addStaticInferenceEdge(context, {
+            source,
+            target: worker,
+            file: input.file,
+            range: input.value.location,
+            coverage: input.coverage,
+            relation: "loads",
+            properties: { kind: input.value.kind },
+        });
+        if (resolved !== null)
+            addStaticInferenceEdge(context, {
+                source: worker,
+                target: resolved.node,
+                file: input.file,
+                range: input.value.location,
+                coverage: input.coverage,
+                relation: "maps_to",
+                properties: { resolved_path: resolved.path },
+            });
+        return;
+    }
+    const target = resolved?.node ??
+        unresolvedReferenceNode(context, input.file, input.value, input.coverage);
+    addStaticInferenceEdge(context, {
+        source,
+        target,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: resolved?.file.kind === "native-addon" ? "loads" : "imports",
+        properties: {
+            kind: input.value.kind,
+            specifier: input.value.specifier,
+            expression: input.value.expression,
+            resolved_path: resolved?.path ?? null,
+        },
+    });
+};
+const addEndpoint = (context, input) => {
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
+        input.asset;
+    const node = context.accumulator.addNode({
+        kind: "endpoint",
+        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.value),
+        observations: [
+            {
+                label: input.value.value,
+                properties: {
+                    endpoint_kind: input.value.kind,
+                    value: input.value.value,
+                    mechanism: input.value.mechanism,
+                },
+                evidence: astObservationEvidence({
+                    sha256: input.file.sha256,
+                    path: input.file.path,
+                    range: input.value.location,
+                    operation: "discover-static-endpoint",
+                    coverage: input.coverage,
+                }),
+            },
+        ],
+    });
+    addStaticInferenceEdge(context, {
+        source,
+        target: node,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: input.value.kind === "route" ? "exposes" : "calls",
+        properties: { mechanism: input.value.mechanism },
+    });
+};
+const addStorage = (context, input) => {
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
+        input.asset;
+    const node = context.accumulator.addNode({
+        kind: "storage",
+        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.name ?? input.value.mechanism),
+        observations: [
+            {
+                label: input.value.name ?? input.value.kind,
+                properties: {
+                    storage_kind: input.value.kind,
+                    name: input.value.name,
+                    mechanism: input.value.mechanism,
+                },
+                evidence: astObservationEvidence({
+                    sha256: input.file.sha256,
+                    path: input.file.path,
+                    range: input.value.location,
+                    operation: "discover-static-storage",
+                    coverage: input.coverage,
+                }),
+            },
+        ],
+    });
+    addStaticInferenceEdge(context, {
+        source,
+        target: node,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: "persists_to",
+        properties: { mechanism: input.value.mechanism },
+    });
+};
+const addDiscoveredRole = (context, input) => {
+    const resolvedPath = resolveArtifactPath(input.value.path, input.file.path, context.filesByPath);
+    const role = createElectronRoleNode(context, {
+        kind: input.value.role === "preload" ? "electron-preload" : "electron-renderer",
+        anchor: input.file,
+        declaredPath: input.value.path,
+        resolvedPath,
+        mechanism: input.value.mechanism,
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key) ??
+        input.asset;
+    addStaticInferenceEdge(context, {
+        source,
+        target: role,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: "loads",
+        properties: { mechanism: input.value.mechanism },
+    });
+    linkElectronRoleToAsset(context, {
+        role,
+        anchor: input.file,
+        path: resolvedPath,
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+};
+const addSourceMapEdge = (context, input) => {
+    const resolvedPath = resolveArtifactPath(input.value.declared_url, input.file.path, context.filesByPath);
+    const resolvedFile = resolvedPath === null ? undefined : context.filesByPath.get(resolvedPath);
+    const resolvedNode = resolvedPath === null ? undefined : context.fileNodes.get(resolvedPath);
+    const target = resolvedFile?.kind === "source-map" && resolvedNode !== undefined
+        ? resolvedNode
+        : context.accumulator.addNode({
+            kind: "source-map",
+            identity: artifactLocalIdentity(input.file.sha256, "unresolved-source-map", input.value.declared_url),
+            observations: [
+                {
+                    label: input.value.declared_url,
+                    properties: {
+                        declared_url: input.value.declared_url,
+                        resolved_path: resolvedPath,
+                        available: false,
+                    },
+                    evidence: staticInferenceEvidence({
+                        sha256: input.file.sha256,
+                        path: input.file.path,
+                        range: input.value.location,
+                        operation: "discover-source-map",
+                        coverage: input.coverage,
+                        confidence: "medium",
+                        limitations: [
+                            "The declared source map was not present in the inventoried artifact.",
+                        ],
+                    }),
+                },
+            ],
+        });
+    addStaticInferenceEdge(context, {
+        source: input.asset,
+        target,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: "maps_to",
+        properties: {
+            declared_url: input.value.declared_url,
+            resolved_path: resolvedPath,
+        },
+    });
+};
+const resolveReference = (context, sourcePath, specifier) => {
+    const module = context.moduleNodes.get(moduleLookupKey(sourcePath, specifier));
+    if (module !== undefined) {
+        const file = context.filesByPath.get(sourcePath);
+        return file === undefined
+            ? null
+            : { path: `${sourcePath}#module:${specifier}`, file, node: module };
+    }
+    const path = resolveArtifactPath(specifier, sourcePath, context.filesByPath);
+    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 unresolvedReferenceNode = (context, file, reference, coverage) => context.accumulator.addNode({
+    kind: "javascript-module",
+    identity: artifactLocalIdentity(file.sha256, "unresolved-reference", `${reference.kind}:${reference.specifier ?? reference.expression ?? "[dynamic]"}`),
+    observations: [
+        {
+            label: reference.specifier,
+            properties: {
+                reference_kind: reference.kind,
+                specifier: reference.specifier,
+                expression: reference.expression,
+                resolution: "unresolved",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: file.sha256,
+                path: file.path,
+                range: reference.location,
+                operation: "resolve-static-reference",
+                coverage,
+                confidence: "low",
+                limitations: [
+                    "The static reference could not be resolved within the inventoried artifact.",
+                ],
+            }),
+        },
+    ],
+});