reverseport 0.0.0-stage → 1.2.0

package/dist/application/javascript/JavaScriptArtifactGraphDocuments.js

@@ -0,0 +1,160 @@
+import { addArtifactContainsEdge, addStaticInferenceEdge, artifactLocalIdentity, createElectronRoleNode, linkElectronRoleToAsset, } from "./JavaScriptArtifactGraphContext.js";
+import { artifactObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { completeApplicationCoverage } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.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 roleResolution = {
+            declared_path: html.path,
+            resolution_context: "html-reference",
+            resolved_path: html.path,
+            resolution_status: "resolved",
+            limitations: [],
+        };
+        const role = createElectronRoleNode(context, {
+            kind: "electron-renderer",
+            anchor: html,
+            resolution: roleResolution,
+            mechanism: "html-script-entrypoint",
+        });
+        addArtifactContainsEdge(context, {
+            source: context.root,
+            target: role,
+            file: html,
+            operation: "discover-html-renderer",
+        });
+        linkElectronRoleToAsset(context, {
+            role,
+            anchor: html,
+            resolution: roleResolution,
+        });
+        for (const script of scripts) {
+            const resolution = resolveArtifactPathByContext({
+                declaredPath: script.script_path,
+                sourcePath: html.path,
+                context: "html-reference",
+                files: context.filesByPath,
+                htmlBaseHref: script.base_href,
+            });
+            const resolvedPath = resolution.resolved_path;
+            if (resolvedPath === null) {
+                context.accumulator.addNode({
+                    kind: role.kind,
+                    identity: role.identity,
+                    observations: [
+                        {
+                            label: script.script_path,
+                            properties: {
+                                mechanism: "html-script-reference",
+                                script_path: script.script_path,
+                                base_href: script.base_href,
+                                ...resolution,
+                            },
+                            evidence: staticInferenceEvidence({
+                                sha256: html.sha256,
+                                path: html.path,
+                                range: script.location,
+                                operation: "resolve-html-script-reference",
+                                coverage: completeApplicationCoverage(),
+                                limitations: resolution.limitations,
+                            }),
+                        },
+                    ],
+                });
+                continue;
+            }
+            const resolved = context.fileNodes.get(resolvedPath);
+            if (resolved === undefined)
+                continue;
+            addStaticInferenceEdge(context, {
+                source: role,
+                target: resolved,
+                file: html,
+                range: script.location,
+                coverage: completeApplicationCoverage(),
+                relation: "loads",
+                properties: {
+                    script_path: script.script_path,
+                    base_href: script.base_href,
+                    resolution_context: resolution.resolution_context,
+                    resolved_path: resolvedPath,
+                    resolution_status: resolution.resolution_status,
+                    limitations: resolution.limitations,
+                },
+            });
+        }
+    }
+};
+/** 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 = completeApplicationCoverage();
+        for (const original of sourceMap.sources) {
+            const reference = original.reference;
+            const node = context.accumulator.addNode({
+                kind: reference === null ? "unknown" : "source-module",
+                identity: reference === null
+                    ? artifactLocalIdentity(mapFile.sha256, "source-map-unnamed-declaration", String(original.declaration_index))
+                    : {
+                        strategy: "source-map-original",
+                        stability: "source-map-exact",
+                        source_map_sha256: mapFile.sha256,
+                        original_source: reference.source_name,
+                        source_root: reference.source_root,
+                        source_sha256: original.content_sha256,
+                    },
+                observations: [
+                    {
+                        label: reference?.source_name || null,
+                        source_map_reference: reference,
+                        properties: {
+                            source_index: original.source_index,
+                            declaration_index: original.declaration_index,
+                            source_name_available: reference !== null,
+                            content_available: original.content !== null,
+                            content_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: {
+                    source_index: original.source_index,
+                    declaration_index: original.declaration_index,
+                    original_source: reference?.source_name ?? null,
+                    source_root: reference?.source_root ?? null,
+                },
+                evidence: artifactObservationEvidence({
+                    sha256: mapFile.sha256,
+                    path: mapFile.path,
+                    operation: "parse-local-source-map",
+                    coverage,
+                    limitations: sourceMap.limitation === null ? [] : [sourceMap.limitation],
+                }),
+            });
+        }
+    }
+};

package/dist/application/javascript/JavaScriptArtifactGraphEvidence.js

@@ -0,0 +1,85 @@
+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: [],
+});
+const artifactReference = (sha256) => ({
+    available: true,
+    artifact_id: `art_${sha256}`,
+    sha256,
+});

package/dist/application/javascript/JavaScriptArtifactGraphFindings.js

@@ -0,0 +1,349 @@
+import { createHash } from "node:crypto";
+import { compactStringIdentityKey } from "../../domain/compactStringIdentity.js";
+import { addStaticInferenceEdge, artifactLocalIdentity, chunkLookupKey, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, resolveArtifactPath, selfReferenceOmissions, sourceNodeFor, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { moduleKindForJavaScriptReference, resolveArtifactPathByContext, } from "./JavaScriptArtifactPathResolution.js";
+/** Project imports, workers, roles, endpoints, storage, and source-map links. */
+export function* addJavaScriptStaticFindingsSteps(context) {
+    const omissions = { selfReferences: 0 };
+    for (const analyzed of context.analysis.files) {
+        yield;
+        const { file, javascript } = analyzed;
+        const asset = context.assetNodes.get(file.path);
+        if (javascript === null || asset === undefined)
+            continue;
+        const coverage = javascriptAnalysisCoverage(javascript);
+        for (const value of javascript.references)
+            addReference(context, { file, asset, value, coverage }, omissions);
+        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 });
+    }
+    return selfReferenceOmissions(omissions.selfReferences, ["static reference", "static references"], "the referencing module");
+}
+const addReference = (context, input, omissions) => {
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? input.asset;
+    const resolved = input.value.specifier === null
+        ? null
+        : resolveReference(context, input.file.path, input.value);
+    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),
+            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;
+    }
+    // A reference that resolves to its own source, such as a bundled module
+    // requiring its own key, cannot become an edge: the application graph
+    // forbids self-referential edges and one would fail the whole analysis.
+    if (resolved?.node.node_id === source.node_id) {
+        omissions.selfReferences += 1;
+        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.value.module_runtime) ?? input.asset;
+    const key = compactStringIdentityKey(input.value.value);
+    const label = `${input.value.kind} endpoint`;
+    const node = context.accumulator.addNode({
+        kind: "endpoint",
+        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, key),
+        observations: [
+            {
+                label: input.value.value.length <= label.length ? input.value.value : label,
+                properties: {
+                    endpoint_kind: input.value.kind,
+                    value: input.value.value,
+                    mechanism: input.value.mechanism,
+                },
+                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.value.module_runtime) ?? input.asset;
+    const node = context.accumulator.addNode({
+        kind: "storage",
+        identity: artifactLocalIdentity(input.file.sha256, input.value.kind, input.value.name ?? input.value.mechanism),
+        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 resolution = resolveArtifactPathByContext({
+        declaredPath: input.value.path,
+        sourcePath: input.file.path,
+        context: input.value.resolution_context,
+        files: context.filesByPath,
+    });
+    const role = createElectronRoleNode(context, {
+        kind: input.value.role === "preload" ? "electron-preload" : "electron-renderer",
+        anchor: input.file,
+        resolution,
+        mechanism: input.value.mechanism,
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+    const source = sourceNodeFor(context, input.file.path, input.value.module_key, input.value.module_runtime) ?? 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,
+        resolution,
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+};
+const addSourceMapEdge = (context, input) => {
+    const declaredUrlSha256 = createHash("sha256")
+        .update(input.value.declared_url)
+        .digest("hex");
+    const resolvedPath = resolveArtifactPathByContext({
+        declaredPath: input.value.declared_url,
+        sourcePath: input.file.path,
+        context: "url-reference",
+        files: context.filesByPath,
+    }).resolved_path;
+    const resolvedFile = resolvedPath === null ? undefined : context.filesByPath.get(resolvedPath);
+    const resolvedNode = resolvedPath === null ? undefined : context.fileNodes.get(resolvedPath);
+    const isAvailable = resolvedFile?.kind === "source-map" && resolvedNode !== undefined;
+    const target = context.accumulator.addNode({
+        kind: "source-map",
+        identity: isAvailable && resolvedNode !== undefined
+            ? resolvedNode.identity
+            : artifactLocalIdentity(input.file.sha256, "unresolved-source-map", declaredUrlSha256),
+        observations: [
+            {
+                label: "source map reference",
+                properties: {
+                    declared_url: input.value.declared_url,
+                    declared_url_sha256: declaredUrlSha256,
+                    resolved_path: resolvedPath,
+                    available: isAvailable,
+                },
+                evidence: staticInferenceEvidence({
+                    sha256: input.file.sha256,
+                    path: input.file.path,
+                    range: input.value.location,
+                    operation: "discover-source-map",
+                    coverage: input.coverage,
+                    confidence: "medium",
+                    limitations: isAvailable
+                        ? []
+                        : [
+                            "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_sha256: declaredUrlSha256,
+            resolved_path: resolvedPath,
+        },
+    });
+};
+const resolveReference = (context, sourcePath, reference) => {
+    const specifier = reference.specifier;
+    if (specifier === null)
+        return null;
+    const chunk = resolveBundlerChunkReference(context, sourcePath, reference);
+    if (chunk !== null)
+        return chunk;
+    const module = reference.module_runtime === undefined
+        ? undefined
+        : context.moduleNodes.get(moduleLookupKey(sourcePath, reference.module_runtime, specifier));
+    if (module !== undefined) {
+        const file = context.filesByPath.get(sourcePath);
+        return file === undefined
+            ? null
+            : { path: `${sourcePath}#module:${specifier}`, file, node: module };
+    }
+    // Worker scripts are URLs relative to the script, not module specifiers.
+    const path = reference.kind === "worker" || reference.kind === "service-worker"
+        ? resolveArtifactPathByContext({
+            declaredPath: specifier,
+            sourcePath,
+            context: "url-reference",
+            files: context.filesByPath,
+        }).resolved_path
+        : resolveArtifactPath(specifier, sourcePath, context.filesByPath, reference.kind === "require" ||
+            reference.kind === "static-import" ||
+            reference.kind === "dynamic-import"
+            ? moduleKindForJavaScriptReference(sourcePath, reference.kind)
+            : undefined);
+    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 resolveBundlerChunkReference = (context, sourcePath, reference) => {
+    const key = reference.specifier?.startsWith("chunk:")
+        ? reference.specifier.slice("chunk:".length)
+        : null;
+    if (key === null)
+        return null;
+    const file = context.filesByPath.get(sourcePath);
+    if (file === undefined)
+        return null;
+    const registrations = context.analysis.files
+        .find(({ file: analyzedFile }) => analyzedFile.path === sourcePath)
+        ?.javascript?.bundler_registrations.filter(({ runtime, modules }) => reference.module_runtime === undefined
+        ? reference.module_key === null
+        : runtime === reference.module_runtime &&
+            modules.some(({ module_key: moduleKey }) => moduleKey === reference.module_key));
+    if (registrations === undefined)
+        return null;
+    const candidates = registrations.flatMap(({ runtime }) => {
+        const node = context.chunkNodes.get(chunkLookupKey(sourcePath, runtime, key));
+        return node === undefined ? [] : [node];
+    });
+    const unique = [
+        ...new Map(candidates.map((node) => [node.node_id, node])).values(),
+    ];
+    if (unique.length !== 1)
+        return null;
+    const node = unique[0];
+    return node === undefined
+        ? null
+        : { path: `${sourcePath}#chunk:${key}`, 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}`),
+    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.",
+                ],
+            }),
+        },
+    ],
+});