rea-agents 1.6.0 → 2.0.0

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,99 @@
+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) => {
+    const limitations = [
+        ...(input.limitations ?? []),
+        ...(input.coverage.status === "complete"
+            ? []
+            : [
+                "AST coverage is incomplete; omitted or dynamic facts must not be interpreted as absence.",
+            ]),
+    ];
+    return {
+        authority: "ast-static-analysis",
+        state: "observed",
+        confidence: "exact",
+        artifact: artifactReference(input.sha256),
+        location: {
+            available: true,
+            value: { kind: "source-range", source: input.path, ...input.range },
+        },
+        extractor: { ...EXTRACTOR, operation: input.operation },
+        coverage: input.coverage,
+        limitations,
+        evidence_ids: [],
+    };
+};
+/** Explicit static relationship inference; never promoted to observation. */
+export const staticInferenceEvidence = (input) => ({
+    authority: "static-relationship-inference",
+    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.",
+                ],
+            }),
+        },
+    ],
+});