reverseport 0.0.0-stage → 1.0.0

package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js

@@ -0,0 +1,193 @@
+import { ELECTRON_IDENTITY_LIMITATION } from "../../domain/javascript/javascriptElectronMemberWrites.js";
+import { createJavaScriptApplicationGraph, sealTransferredJavaScriptApplicationGraphSteps, } from "../../domain/javascript/javascriptApplicationGraph.js";
+import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
+import { selfReferenceOmissions, } from "./JavaScriptArtifactGraphContext.js";
+import { addJavaScriptHtmlRoles, addJavaScriptSourceMapOriginals, } from "./JavaScriptArtifactGraphDocuments.js";
+import { addJavaScriptStaticFindingsSteps } from "./JavaScriptArtifactGraphFindings.js";
+import { addJavaScriptModuleRelationshipsSteps, addJavaScriptSourceModules, } from "./JavaScriptModuleRelationships.js";
+import { completeApplicationCoverage, partialApplicationCoverage, } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import { semanticCoverageResourceLimits, semanticResourceLimitCoverage, } from "../../domain/javascript/javascriptSemanticCoverage.js";
+import { semanticResourceLimitReason } from "../../domain/javascript/javascriptSemanticResourceLimits.js";
+import { addJavaScriptArtifactContainers, addJavaScriptArtifactFiles, addJavaScriptPackageNodes, createJavaScriptArtifactRootNode, } from "./JavaScriptArtifactGraphStructure.js";
+import { addJavaScriptBundlerNodes } from "./JavaScriptArtifactGraphBundlers.js";
+import { addElectronBoundaries } from "./ElectronBoundaryGraph.js";
+import { classifyElectronIpcPairings, collectElectronIpcRecords, } from "./ElectronBoundaryAnalysis.js";
+/** Project artifact and AST facts into JavaScript Application Graph. */
+export const buildJavaScriptArtifactGraph = (snapshot, fileSet, analysis) => createJavaScriptApplicationGraph(completeSynchronously(buildJavaScriptArtifactGraphInputSteps(snapshot, fileSet, analysis)));
+/**
+ * Build a validated application graph with cooperative immutable ownership.
+ * Constructing the graph input also runs in steps: projecting every module
+ * relationship and finding at once held the event loop for seconds.
+ */
+export function* buildImmutableJavaScriptArtifactGraphSteps(snapshot, fileSet, analysis) {
+    const input = yield* buildJavaScriptArtifactGraphInputSteps(snapshot, fileSet, analysis);
+    // The input was built here and is not retained, so it can be transferred.
+    return yield* sealTransferredJavaScriptApplicationGraphSteps(input);
+}
+const completeSynchronously = (steps) => {
+    for (;;) {
+        const step = steps.next();
+        if (step.done === true)
+            return step.value;
+    }
+};
+function* buildJavaScriptArtifactGraphInputSteps(snapshot, fileSet, analysis) {
+    const accumulator = new JavaScriptArtifactGraphAccumulator();
+    const root = createJavaScriptArtifactRootNode(accumulator, snapshot);
+    const context = {
+        accumulator,
+        snapshot,
+        fileSet,
+        analysis,
+        root,
+        filesByPath: new Map(fileSet.files.map((file) => [file.path, file])),
+        fileNodes: new Map(),
+        assetNodes: new Map(),
+        sourceModuleNodes: new Map(),
+        chunkNodes: new Map(),
+        moduleNodes: new Map(),
+        containerNodes: new Map([[snapshot.manifest.root_sha256, root]]),
+    };
+    addJavaScriptArtifactContainers(context);
+    yield;
+    addJavaScriptArtifactFiles(context);
+    yield;
+    // Raw observations remain on the file nodes. Only admitted expansions feed
+    // the relationship builders, including their Electron and bundler callers.
+    const projectionContext = {
+        ...context,
+        analysis: {
+            ...analysis,
+            files: analysis.files.map((file) => file.application_projection_failure === undefined
+                ? file
+                : { ...file, javascript: null, semantic: null }),
+        },
+    };
+    const packageRoots = addJavaScriptPackageNodes(projectionContext);
+    yield;
+    addJavaScriptSourceModules(projectionContext);
+    yield;
+    const bundlerLimitations = addJavaScriptBundlerNodes(projectionContext);
+    const relationshipOmissions = yield* addJavaScriptModuleRelationshipsSteps(projectionContext);
+    const findingLimitations = yield* addJavaScriptStaticFindingsSteps(projectionContext);
+    addElectronBoundaries(projectionContext);
+    yield;
+    addJavaScriptHtmlRoles(projectionContext);
+    yield;
+    addJavaScriptSourceMapOriginals(projectionContext);
+    yield;
+    const coverage = graphCoverage(context);
+    return {
+        schema: "JavaScriptApplicationGraph",
+        root_node_ids: packageRoots.length === 0
+            ? [root.node_id]
+            : packageRoots.map(({ node_id: id }) => id),
+        nodes: accumulator.nodes(),
+        edges: accumulator.edges(),
+        coverage,
+        limitations: [
+            ...bundlerLimitations,
+            ...findingLimitations,
+            ...graphLimitations(context, coverage.status, relationshipOmissions),
+        ],
+    };
+}
+const graphCoverage = (context) => {
+    const resourceLimits = semanticResourceLimits(context);
+    const sourceMapPolicyGap = context.analysis.source_maps.some(({ status }) => status === "invalid");
+    const malformedStructuredData = context.analysis.packages.some(({ status }) => status !== "included") ||
+        context.analysis.json_modules.some(({ status }) => status !== "included") ||
+        context.analysis.source_maps.some(({ status }) => status === "invalid");
+    const partialJavaScript = context.analysis.files.some(({ javascript }) => javascript !== null && javascript.parse_status === "partial");
+    const unknownGap = (context.fileSet.source_selection?.unselected_files ?? 0) > 0 ||
+        context.analysis.files.some(({ analysis_failure, application_projection_failure }) => analysis_failure !== undefined ||
+            application_projection_failure !== undefined) ||
+        context.analysis.parse_failures > 0 ||
+        context.fileSet.invalid_utf8_files > 0 ||
+        sourceMapPolicyGap ||
+        malformedStructuredData ||
+        partialJavaScript;
+    const executionLimits = context.analysis.files.flatMap(({ analysis_failure, application_projection_failure }) => [analysis_failure, application_projection_failure].flatMap((failure) => failure === undefined
+        ? []
+        : javaScriptAnalysisCoverageLimits(failure.limits)));
+    if (resourceLimits.length > 0 || executionLimits.length > 0)
+        return partialApplicationCoverage([
+            ...new Map([
+                ...semanticResourceLimitCoverage(resourceLimits),
+                ...executionLimits,
+            ].map((limit) => [JSON.stringify(limit), limit])).values(),
+        ], null);
+    if (unknownGap)
+        return partialApplicationCoverage([], null);
+    if (context.snapshot.integrity_contradictions.length > 0) {
+        const nestedArchiveWasOpaque = context.snapshot.integrity_contradictions.some(({ logical_path }) => logical_path.toLowerCase().endsWith(".asar"));
+        return partialApplicationCoverage([], nestedArchiveWasOpaque ? null : 0);
+    }
+    return completeApplicationCoverage();
+};
+const semanticResourceLimits = (context) => [
+    ...new Set(context.analysis.files.flatMap(({ semantic }) => semantic === null
+        ? []
+        : semanticCoverageResourceLimits(semantic.ir.coverage))),
+].sort();
+const graphLimitations = (context, coverage, relationshipOmissions) => {
+    const ipc = collectElectronIpcRecords(context.analysis);
+    const pairings = classifyElectronIpcPairings(ipc);
+    const electronFindings = context.analysis.files.reduce((count, { javascript }) => count +
+        (javascript === null
+            ? 0
+            : javascript.electron.browser_windows.length +
+                javascript.electron.context_bridge_apis.length +
+                javascript.electron.ipc.length +
+                javascript.electron.sender_validations.length +
+                javascript.electron.utility_processes.length +
+                javascript.electron.native_addon_bindings.length), 0);
+    return [
+        ...context.analysis.limitations,
+        ...(context.fileSet.source_selection === undefined
+            ? []
+            : [
+                `Caller-selected source analysis leaves ${String(context.fileSet.source_selection.unselected_files)} inventoried files outside analysis scope. Inventory identity covers the complete artifact; relationships through unselected sources remain unknown.`,
+            ]),
+        ...context.snapshot.integrity_contradictions.map(({ logical_path: path }) => `Artifact integrity metadata contradicts observed bytes at ${path}; the observed bytes are untrusted.`),
+        ...selfReferenceOmissions(relationshipOmissions.selfImports, ["import specifier", "import specifiers"], "the importing module"),
+        "CommonJS and ESM binding relationships were recovered from inert syntax and resolved only within the inventoried artifact container.",
+        "Webpack/Rspack factories were recovered from AST literals; REA did not invoke push handlers or bundle bootstrap code.",
+        "Static imports, entrypoints, workers, endpoints, and storage relationships do not prove runtime execution.",
+        ...(context.analysis.files.some(({ javascript }) => javascript?.limitations.includes(ELECTRON_IDENTITY_LIMITATION))
+            ? [ELECTRON_IDENTITY_LIMITATION]
+            : []),
+        ...(electronFindings === 0
+            ? []
+            : [
+                "Electron relationships are derived from inert syntax; runtime registration, reachability, defaults, and enforcement remain unproven.",
+            ]),
+        ...(ipc.some(({ finding }) => finding.channel === null)
+            ? [
+                "Dynamic IPC channel expressions remain unresolved and are never paired by textual similarity.",
+            ]
+            : []),
+        ...(pairings.some(({ status }) => status === "ambiguous")
+            ? [
+                "Some literal IPC channels have multiple compatible main handlers; ambiguous calls are not paired to any handler.",
+            ]
+            : []),
+        ...(context.analysis.files.some(({ javascript }) => (javascript?.electron.sender_validations.length ?? 0) > 0)
+            ? [
+                "Sender, frame, URL, and origin checks are observations only; REA does not claim that they enforce a complete authorization policy.",
+            ]
+            : []),
+        ...semanticResourceLimits(context).map(semanticResourceLimitReason),
+        ...(context.analysis.files.some(({ javascript }) => (javascript?.electron.native_addon_bindings.length ?? 0) > 0)
+            ? [
+                "Native member names are requested by JavaScript syntax and are not verified binary exports in this workflow.",
+            ]
+            : []),
+        ...(coverage === "complete"
+            ? []
+            : [
+                "Graph coverage is incomplete; unavailable facts remain explicit and must not be read as absence.",
+            ]),
+    ];
+};
+import { javaScriptAnalysisCoverageLimits } from "../../domain/javascript/javascriptAnalysisResourceControls.js";

package/dist/application/javascript/JavaScriptArtifactGraphBundlers.js

@@ -0,0 +1,229 @@
+import { compositeKey } from "../../domain/unicodeCodePointOrder.js";
+import { addAstContainsEdge, artifactLocalIdentity, chunkLookupKey, javascriptAnalysisCoverage, moduleLookupKey, selfReferenceOmissions, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Project Webpack/Rspack AST literals and disclose unrepresentable relationships. */
+export const addJavaScriptBundlerNodes = (context) => {
+    let selfAsyncChunks = 0;
+    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);
+        const records = [];
+        for (const registration of javascript.bundler_registrations) {
+            const input = {
+                file,
+                registration,
+                coverage,
+                limitations: javascript.limitations,
+            };
+            const chunk = createBundlerChunkNode(context, input);
+            addAstContainsEdge(context, {
+                source: asset,
+                target: chunk,
+                file,
+                range: registration.location,
+                coverage,
+                properties: { bundler: registration.bundler },
+            });
+            for (const key of registration.chunk_keys)
+                context.chunkNodes.set(chunkLookupKey(file.path, registration.runtime, key), chunk);
+            records.push({ file, registration, chunk, coverage });
+            addBundlerModuleNodes(context, { ...input, chunk });
+        }
+        for (const record of records)
+            selfAsyncChunks += addBundlerRuntimeEdges(context, record);
+    }
+    return selfReferenceOmissions(selfAsyncChunks, ["bundler async-chunk reference", "bundler async-chunk references"], "the requesting chunk");
+};
+const createBundlerChunkNode = (context, input) => {
+    const { file, registration, coverage, limitations } = input;
+    const chunkKey = `${registration.runtime}:${registration.chunk_keys.join(",")}`;
+    return context.accumulator.addNode({
+        kind: "javascript-chunk",
+        identity: artifactLocalIdentity(file.sha256, "bundler-chunk", compositeKey([registration.runtime, registration.chunk_keys])),
+        observations: [
+            {
+                label: chunkKey,
+                properties: {
+                    path: file.path,
+                    bundler: registration.bundler,
+                    runtime: registration.runtime,
+                    chunk_keys: registration.chunk_keys,
+                    unknown_chunk_keys: registration.unknown_chunk_keys,
+                    runtime_require_name: registration.runtime_require_name,
+                    runtime_module_cache_status: registration.runtime_module_cache_status,
+                    entry_module_keys: registration.entry_module_keys,
+                    unknown_entry_module_keys: registration.unknown_entry_module_keys,
+                    async_chunk_keys: registration.async_chunk_keys,
+                    unknown_async_chunk_keys: registration.unknown_async_chunk_keys,
+                    module_count: registration.modules.length,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: registration.location,
+                    operation: "extract-bundler-registration",
+                    coverage,
+                    limitations,
+                }),
+            },
+        ],
+    });
+};
+const addBundlerModuleNodes = (context, input) => {
+    const { file, registration, chunk, coverage, limitations } = input;
+    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,
+                        chunk_keys: registration.chunk_keys,
+                        module_key: moduleValue.module_key,
+                        factory_require_name: moduleValue.factory_require_name,
+                        runtime_entry: registration.entry_module_keys.includes(moduleValue.module_key),
+                        source_sha256: moduleValue.source_sha256,
+                        structural_fingerprint_sha256: moduleValue.structural_fingerprint_sha256,
+                        structural_fingerprint_algorithm: moduleValue.structural_fingerprint_algorithm,
+                        exports: moduleValue.exports,
+                    },
+                    evidence: astObservationEvidence({
+                        sha256: file.sha256,
+                        path: file.path,
+                        range: moduleValue.location,
+                        operation: "extract-bundler-module",
+                        coverage,
+                        limitations,
+                    }),
+                },
+            ],
+        });
+        context.moduleNodes.set(moduleLookupKey(file.path, registration.runtime, moduleValue.module_key), module);
+        addAstContainsEdge(context, {
+            source: chunk,
+            target: module,
+            file,
+            range: moduleValue.location,
+            coverage,
+            properties: {
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                chunk_keys: registration.chunk_keys,
+                module_key: moduleValue.module_key,
+            },
+        });
+    }
+};
+const addBundlerRuntimeEdges = (context, record) => {
+    let selfAsyncChunks = 0;
+    const { file, registration, chunk, coverage } = record;
+    for (const moduleKey of registration.entry_module_keys) {
+        const resolved = context.moduleNodes.get(moduleLookupKey(file.path, registration.runtime, moduleKey));
+        const target = resolved ?? unresolvedBundlerModuleNode(context, record, moduleKey);
+        context.accumulator.addEdge({
+            source_node_id: chunk.node_id,
+            target_node_id: target.node_id,
+            relation: "loads",
+            properties: {
+                kind: "bundler-entry-module",
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                module_key: moduleKey,
+                resolution_status: resolved === undefined ? "not-found" : "resolved",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: file.sha256,
+                path: file.path,
+                range: registration.location,
+                operation: "resolve-bundler-entry-module",
+                coverage,
+                confidence: resolved === undefined ? "low" : "high",
+            }),
+        });
+    }
+    for (const chunkKey of registration.async_chunk_keys) {
+        const lookup = chunkLookupKey(file.path, registration.runtime, chunkKey);
+        const resolved = context.chunkNodes.get(lookup);
+        if (resolved?.node_id === chunk.node_id) {
+            selfAsyncChunks++;
+            continue;
+        }
+        const target = resolved ?? unresolvedBundlerChunkNode(context, record, chunkKey);
+        context.accumulator.addEdge({
+            source_node_id: chunk.node_id,
+            target_node_id: target.node_id,
+            relation: "imports",
+            properties: {
+                kind: "bundler-async-chunk",
+                bundler: registration.bundler,
+                runtime: registration.runtime,
+                chunk_key: chunkKey,
+                resolution_status: resolved === undefined ? "not-found" : "resolved",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: file.sha256,
+                path: file.path,
+                range: registration.location,
+                operation: "resolve-bundler-async-chunk",
+                coverage,
+                confidence: resolved === undefined ? "low" : "high",
+            }),
+        });
+    }
+    return selfAsyncChunks;
+};
+const unresolvedBundlerModuleNode = (context, record, moduleKey) => context.accumulator.addNode({
+    kind: "javascript-module",
+    identity: artifactLocalIdentity(record.file.sha256, `${record.registration.runtime}:unresolved-entry-module`, moduleKey),
+    observations: [
+        {
+            label: moduleKey,
+            properties: {
+                semantic_role: "bundler-module-reference",
+                bundler: record.registration.bundler,
+                runtime: record.registration.runtime,
+                module_key: moduleKey,
+                resolution_status: "not-found",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: record.file.sha256,
+                path: record.file.path,
+                range: record.registration.location,
+                operation: "retain-unresolved-bundler-entry-module",
+                coverage: record.coverage,
+                confidence: "low",
+            }),
+        },
+    ],
+});
+const unresolvedBundlerChunkNode = (context, record, chunkKey) => context.accumulator.addNode({
+    kind: "javascript-chunk",
+    identity: artifactLocalIdentity(record.file.sha256, `${record.registration.runtime}:unresolved-async-chunk`, chunkKey),
+    observations: [
+        {
+            label: chunkKey,
+            properties: {
+                semantic_role: "bundler-chunk-reference",
+                bundler: record.registration.bundler,
+                runtime: record.registration.runtime,
+                chunk_key: chunkKey,
+                resolution_status: "not-found",
+            },
+            evidence: staticInferenceEvidence({
+                sha256: record.file.sha256,
+                path: record.file.path,
+                range: record.registration.location,
+                operation: "retain-unresolved-bundler-async-chunk",
+                coverage: record.coverage,
+                confidence: "low",
+            }),
+        },
+    ],
+});

package/dist/application/javascript/JavaScriptArtifactGraphContext.js

@@ -0,0 +1,194 @@
+import { compositeKey } from "../../domain/unicodeCodePointOrder.js";
+import { completeApplicationCoverage, partialApplicationCoverage, } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
+import { artifactObservationEvidence, astObservationEvidence, staticInferenceEvidence, unavailableAstEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext, } from "./JavaScriptArtifactPathResolution.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: completeApplicationCoverage(),
+        }),
+    });
+};
+/** 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,
+                    ...(input.failure === undefined
+                        ? {}
+                        : { analysis_failure: input.failure }),
+                },
+                evidence: unavailableAstEvidence({
+                    sha256: input.file.sha256,
+                    path: input.file.path,
+                    operation: input.operation,
+                    coverage: partialApplicationCoverage(input.limits ?? [], null),
+                    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: completeApplicationCoverage(),
+        }),
+    });
+};
+/** Coverage for one bounded JavaScript AST analysis. */
+export const javascriptAnalysisCoverage = (analysis) => analysis.parse_status === "complete"
+    ? completeApplicationCoverage()
+    : partialApplicationCoverage([], null);
+/** 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,
+    key,
+});
+/** Select the graph node kind for one inventoried relevant file. */
+export const artifactFileNodeKind = (kind) => kind === "javascript"
+    ? "javascript-asset"
+    : kind === "source-map"
+        ? "source-map"
+        : kind === "native-addon"
+            ? "native-addon"
+            : "artifact";
+/** 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.resolution.resolution_context}:${input.resolution.resolved_path ?? input.resolution.declared_path}`),
+    observations: [
+        {
+            label: input.resolution.resolved_path ?? input.resolution.declared_path,
+            properties: {
+                declared_path: input.resolution.declared_path,
+                resolution_context: input.resolution.resolution_context,
+                resolved_path: input.resolution.resolved_path,
+                resolution_status: input.resolution.resolution_status,
+                limitations: input.resolution.limitations,
+                mechanism: input.mechanism,
+            },
+            evidence: staticInferenceEvidence({
+                sha256: input.anchor.sha256,
+                path: input.anchor.path,
+                operation: "discover-electron-entrypoint",
+                coverage: input.coverage ?? completeApplicationCoverage(),
+                limitations: input.resolution.limitations,
+                ...(input.range === undefined ? {} : { range: input.range }),
+            }),
+        },
+    ],
+});
+/** Resolve an Electron role to an inventoried asset when available. */
+export const linkElectronRoleToAsset = (context, input) => {
+    const path = input.resolution.resolved_path;
+    if (path === null)
+        return;
+    const asset = context.assetNodes.get(path) ?? context.fileNodes.get(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: {
+            declared_path: input.resolution.declared_path,
+            resolution_context: input.resolution.resolution_context,
+            resolved_path: path,
+            resolution_status: input.resolution.resolution_status,
+        },
+        evidence: staticInferenceEvidence({
+            sha256: input.anchor.sha256,
+            path: input.anchor.path,
+            operation: "resolve-electron-entrypoint",
+            coverage: input.coverage ?? completeApplicationCoverage(),
+            limitations: input.resolution.limitations,
+            ...(input.range === undefined ? {} : { range: input.range }),
+        }),
+    });
+};
+/**
+ * Disclose relationships omitted because they resolved to their own source;
+ * the application graph forbids self-referential edges.
+ */
+export const selfReferenceOmissions = (count, noun, owner) => count === 0
+    ? []
+    : [
+        `${String(count)} ${count === 1 ? noun[0] : noun[1]} resolved back to ${owner} itself and ${count === 1 ? "was" : "were"} omitted; application graph edges cannot be self-referential.`,
+    ];
+/** Deterministic key for one recovered module inside a bundle asset. */
+export const moduleLookupKey = (path, runtime, moduleKey) => compositeKey([path, runtime, moduleKey]);
+/** Deterministic key for one recovered bundler chunk inside a bundle asset. */
+export const chunkLookupKey = (path, runtime, chunkKey) => compositeKey([path, runtime, chunkKey]);
+/** Resolve a relative static specifier without escaping the artifact root. */
+export const resolveArtifactPath = (specifier, sourcePath, files, moduleKind) => resolveArtifactPathByContext({
+    declaredPath: specifier,
+    sourcePath,
+    context: "module-specifier",
+    files,
+    ...(moduleKind === undefined ? {} : { moduleKind }),
+}).resolved_path;
+/** Locate the recovered module that owns a static finding. */
+export const sourceNodeFor = (context, path, moduleKey, runtime) => moduleKey === null
+    ? context.sourceModuleNodes.get(path)
+    : runtime === undefined
+        ? undefined
+        : context.moduleNodes.get(moduleLookupKey(path, runtime, moduleKey));