feat(artifact): reconstruct JavaScript application structure

This commit is contained in:
N0zoM1z0
2026-07-16 06:43:30 +09:00
committed by N0zoM1z0
parent da4817abd1
commit aa46abfe1b
174 changed files with 11773 additions and 74 deletions
@@ -0,0 +1,449 @@
import { createHash } from "node:crypto";
import { analyzeJavaScriptStaticSource } from "../domain/javascriptStaticAnalysis.js";
import type {
JavaScriptSourceRange,
JavaScriptSourcePoint,
JavaScriptStaticAnalysis,
} from "../domain/javascriptStaticAnalysisTypes.js";
import type {
JavaScriptArtifactFile,
JavaScriptArtifactFileSet,
} from "./JavaScriptArtifactFiles.js";
import type {
AnalyzedJavaScriptArtifactFile,
JavaScriptArtifactAnalysis,
JavaScriptHtmlScriptObservation,
JavaScriptPackageObservation,
JavaScriptSourceMapObservation,
JavaScriptSourceMapOriginal,
} from "./JavaScriptArtifactAnalysisTypes.js";
import type { JavaScriptArtifactReconstructionInput } from "./JavaScriptArtifactReconstructionInput.js";
interface MutableArtifactAnalysis {
readonly files: AnalyzedJavaScriptArtifactFile[];
readonly packages: JavaScriptPackageObservation[];
readonly htmlScripts: JavaScriptHtmlScriptObservation[];
readonly sourceMaps: JavaScriptSourceMapObservation[];
visitedNodes: number;
findings: number;
modules: number;
parseFailures: number;
truncatedScopes: number;
sourceMapSources: number;
}
interface ArtifactAnalysisContext {
readonly state: MutableArtifactAnalysis;
readonly input: JavaScriptArtifactReconstructionInput;
readonly deadline: number;
readonly now: () => number;
}
/** Analyze selected text files under one shared AST, finding, module, and time budget. */
export const analyzeJavaScriptArtifactFiles = (
fileSet: JavaScriptArtifactFileSet,
input: JavaScriptArtifactReconstructionInput,
now: () => number,
): JavaScriptArtifactAnalysis => {
const state = emptyArtifactAnalysis();
const context = {
state,
input,
deadline: now() + input.limits.max_parse_milliseconds,
now,
};
for (const file of fileSet.files) analyzeArtifactFile(file, context);
return finalizeArtifactAnalysis(state, input);
};
const finalizeArtifactAnalysis = (
state: MutableArtifactAnalysis,
input: JavaScriptArtifactReconstructionInput,
): JavaScriptArtifactAnalysis => {
const omittedHtmlFindings = Math.max(
0,
state.htmlScripts.length + state.findings - input.limits.max_findings,
);
const findings = Math.min(
input.limits.max_findings,
state.findings + state.htmlScripts.length,
);
const sourceMapTruncations = state.sourceMaps.filter(
({ status }) => status === "truncated",
).length;
const truncatedScopes =
state.truncatedScopes +
sourceMapTruncations +
(omittedHtmlFindings > 0 ? 1 : 0);
return {
files: state.files,
packages: state.packages,
html_scripts: state.htmlScripts.slice(0, input.limits.max_findings),
source_maps: state.sourceMaps,
visited_ast_nodes: state.visitedNodes,
findings,
modules: state.modules,
parse_failures: state.parseFailures,
truncated_scopes: truncatedScopes,
limitations: [
"JavaScript and HTML were parsed as inert text; bundle bootstrap code was never executed.",
"Static paths and relationships may remain unresolved when expressions are dynamic or obfuscated.",
...(input.source_map_read_approved
? []
: [
"Source maps were inventoried but their contents were not read without separate approval.",
]),
...(truncatedScopes === 0
? []
: ["One or more static-analysis scopes reached an approved bound."]),
],
};
};
const analyzeArtifactFile = (
file: JavaScriptArtifactFile,
context: ArtifactAnalysisContext,
): void => {
const { state, input } = context;
if (file.kind === "package-json") state.packages.push(parsePackage(file));
if (file.kind === "html" && file.text.included)
state.htmlScripts.push(
...parseHtmlScripts(
file.path,
file.text.value,
Math.max(0, input.limits.max_findings - state.findings),
),
);
if (file.kind === "source-map") addSourceMap(file, context);
if (file.kind !== "javascript" || !file.text.included) {
state.files.push({ file, javascript: null });
return;
}
const remainingNodes = input.limits.max_ast_nodes - state.visitedNodes;
const remainingFindings = input.limits.max_findings - state.findings;
const remainingModules = input.limits.max_modules - state.modules;
if (
remainingNodes <= 0 ||
remainingFindings <= 0 ||
remainingModules <= 0 ||
context.now() > context.deadline
) {
state.files.push({ file, javascript: null });
state.truncatedScopes += 1;
return;
}
const analysis = analyzeJavaScriptStaticSource(file.text.value, {
maxAstNodes: remainingNodes,
maxFindings: remainingFindings,
maxModules: remainingModules,
deadline: context.deadline,
now: context.now,
});
state.files.push({ file, javascript: analysis });
state.visitedNodes += analysis.visited_ast_nodes;
state.findings += findingCount(analysis);
state.modules += analysis.bundler_registrations.reduce(
(count, registration) => count + registration.modules.length,
0,
);
if (analysis.parse_status === "failed") state.parseFailures += 1;
if (analysis.parse_status === "truncated") state.truncatedScopes += 1;
};
const addSourceMap = (
file: JavaScriptArtifactFile,
context: ArtifactAnalysisContext,
): void => {
const sourceMap = parseSourceMap(file, {
deadline: context.deadline,
now: context.now,
maximumSources: Math.max(
0,
context.input.limits.max_source_map_sources -
context.state.sourceMapSources,
),
});
context.state.sourceMaps.push(sourceMap);
context.state.sourceMapSources += sourceMap.sources.length;
};
const emptyArtifactAnalysis = (): MutableArtifactAnalysis => ({
files: [],
packages: [],
htmlScripts: [],
sourceMaps: [],
visitedNodes: 0,
findings: 0,
modules: 0,
parseFailures: 0,
truncatedScopes: 0,
sourceMapSources: 0,
});
const parsePackage = (
file: JavaScriptArtifactFile,
): JavaScriptPackageObservation => {
if (!file.text.included)
return unavailablePackage(file, "Package metadata text was unavailable.");
let value: unknown;
try {
value = JSON.parse(file.text.value);
} catch {
return invalidPackage(file, "package.json is not valid JSON.");
}
if (!isRecord(value))
return invalidPackage(file, "package.json root is not an object.");
return {
path: file.path,
sha256: file.sha256,
status: "included",
name: boundedString(value.name),
version: boundedString(value.version),
main: boundedString(value.main),
renderer:
boundedString(value.renderer) ??
boundedString(value.browser) ??
boundedString(value.module),
limitation: null,
};
};
const invalidPackage = (
file: JavaScriptArtifactFile,
limitation: string,
): JavaScriptPackageObservation => ({
...unavailablePackage(file, limitation),
status: "invalid",
});
const unavailablePackage = (
file: JavaScriptArtifactFile,
limitation: string,
): JavaScriptPackageObservation => ({
path: file.path,
sha256: file.sha256,
status: "unavailable",
name: null,
version: null,
main: null,
renderer: null,
limitation,
});
const parseHtmlScripts = (
path: string,
text: string,
maximum: number,
): JavaScriptHtmlScriptObservation[] => {
const scripts: JavaScriptHtmlScriptObservation[] = [];
const pattern = /<script\b[^>]*\bsrc\s*=\s*(["'])([^"']+)\1[^>]*>/giu;
for (const match of text.matchAll(pattern)) {
const script = match[2]?.slice(0, 4_096);
if (script === undefined || scripts.length >= maximum) break;
const start = match.index;
scripts.push({
html_path: path,
script_path: script,
location: rangeForOffsets(text, start, start + match[0].length),
});
}
return scripts;
};
const parseSourceMap = (
file: JavaScriptArtifactFile,
context: {
readonly deadline: number;
readonly now: () => number;
readonly maximumSources: number;
},
): JavaScriptSourceMapObservation => {
if (!file.text.included) return unavailableSourceMap(file);
if (context.now() > context.deadline)
return truncatedSourceMap(
file,
null,
"Parse deadline reached before source-map decoding.",
);
let value: unknown;
try {
value = JSON.parse(file.text.value);
} catch {
return invalidSourceMap(file, "Source map is not valid JSON.");
}
if (context.now() > context.deadline)
return truncatedSourceMap(
file,
null,
"Parse deadline elapsed during source-map decoding.",
);
const maps = flattenSourceMaps(value, 10_000);
if (maps === undefined)
return invalidSourceMap(file, "Source map is not a bounded version 3 map.");
return collectSourceMapOriginals(file, maps, context);
};
const collectSourceMapOriginals = (
file: JavaScriptArtifactFile,
maps: readonly Readonly<Record<string, unknown>>[],
context: {
readonly deadline: number;
readonly now: () => number;
readonly maximumSources: number;
},
): JavaScriptSourceMapObservation => {
const sources: JavaScriptSourceMapOriginal[] = [];
let total = 0;
for (const map of maps) {
const names = map.sources;
if (!Array.isArray(names))
return invalidSourceMap(file, "Source map has no sources array.");
const contents = Array.isArray(map.sourcesContent)
? map.sourcesContent
: [];
const root = typeof map.sourceRoot === "string" ? map.sourceRoot : "";
for (const [index, raw] of names.entries()) {
if (total % 1_024 === 0 && context.now() > context.deadline)
return {
path: file.path,
sha256: file.sha256,
status: "truncated",
sources,
omitted_sources: null,
limitation: "Parse deadline elapsed during source-map traversal.",
};
if (typeof raw !== "string")
return invalidSourceMap(
file,
"Source map contains a non-string source name.",
);
total += 1;
if (sources.length >= context.maximumSources) continue;
const content =
typeof contents[index] === "string" ? contents[index] : null;
sources.push({
source: resolveSourceName(root, raw),
content,
content_sha256: content === null ? null : sha256(content),
});
}
}
const omitted = total - sources.length;
return {
path: file.path,
sha256: file.sha256,
status: omitted === 0 ? "included" : "truncated",
sources,
omitted_sources: omitted,
limitation:
omitted === 0
? null
: "Original-source inventory reached the approved source-map limit.",
};
};
const unavailableSourceMap = (
file: JavaScriptArtifactFile,
): JavaScriptSourceMapObservation => {
if (file.text.included)
throw new TypeError("Expected unavailable source-map text");
const notApproved = file.text.reason === "not-approved";
return {
path: file.path,
sha256: file.sha256,
status: notApproved ? "not-approved" : "invalid",
sources: [],
omitted_sources: 0,
limitation: notApproved
? "Source-map content requires separate approval."
: "Source-map text was unavailable within approved limits.",
};
};
const flattenSourceMaps = (
root: unknown,
maximum: number,
): Readonly<Record<string, unknown>>[] | undefined => {
if (!isRecord(root) || root.version !== 3) return undefined;
const maps: Readonly<Record<string, unknown>>[] = [];
const pending = [root];
while (pending.length > 0) {
const map = pending.pop();
if (map === undefined || map.version !== 3) return undefined;
if (Array.isArray(map.sections)) {
if (pending.length + maps.length + map.sections.length > maximum)
return undefined;
for (const section of map.sections) {
if (!isRecord(section) || !isRecord(section.map)) return undefined;
pending.push(section.map);
}
} else maps.push(map);
}
return maps;
};
const truncatedSourceMap = (
file: JavaScriptArtifactFile,
omitted: number | null,
limitation: string,
): JavaScriptSourceMapObservation => ({
path: file.path,
sha256: file.sha256,
status: "truncated",
sources: [],
omitted_sources: omitted,
limitation,
});
const invalidSourceMap = (
file: JavaScriptArtifactFile,
limitation: string,
): JavaScriptSourceMapObservation => ({
path: file.path,
sha256: file.sha256,
status: "invalid",
sources: [],
omitted_sources: 0,
limitation,
});
const findingCount = (analysis: JavaScriptStaticAnalysis): number =>
analysis.references.length +
analysis.endpoints.length +
analysis.storage.length +
analysis.role_paths.length +
analysis.source_map_urls.length +
analysis.bundler_registrations.length;
const rangeForOffsets = (
text: string,
start: number,
end: number,
): JavaScriptSourceRange => ({
start: pointForOffset(text, start),
end: pointForOffset(text, end),
});
const pointForOffset = (
text: string,
offset: number,
): JavaScriptSourcePoint => {
const lines = text.slice(0, offset).split("\n");
return { line: lines.length, column: lines.at(-1)?.length ?? 0 };
};
const resolveSourceName = (root: string, source: string): string =>
`${root}${root !== "" && !root.endsWith("/") ? "/" : ""}${source}`.slice(
0,
4_096,
);
const boundedString = (value: unknown): string | null =>
typeof value === "string" && value.length > 0 ? value.slice(0, 4_096) : null;
const sha256 = (value: string): string =>
createHash("sha256").update(value).digest("hex");
const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);
@@ -0,0 +1,61 @@
import type {
JavaScriptSourceRange,
JavaScriptStaticAnalysis,
} from "../domain/javascriptStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
/** Parsed package metadata used only for static entrypoint discovery. */
export interface JavaScriptPackageObservation {
readonly path: string;
readonly sha256: string;
readonly status: "included" | "invalid" | "unavailable";
readonly name: string | null;
readonly version: string | null;
readonly main: string | null;
readonly renderer: string | null;
readonly limitation: string | null;
}
/** One HTML script source observed without building or executing a DOM. */
export interface JavaScriptHtmlScriptObservation {
readonly html_path: string;
readonly script_path: string;
readonly location: JavaScriptSourceRange;
}
/** One original source declared by an approved local source map. */
export interface JavaScriptSourceMapOriginal {
readonly source: string;
readonly content: string | null;
readonly content_sha256: string | null;
}
/** Bounded local source-map parse result. */
export interface JavaScriptSourceMapObservation {
readonly path: string;
readonly sha256: string;
readonly status: "included" | "truncated" | "invalid" | "not-approved";
readonly sources: readonly JavaScriptSourceMapOriginal[];
readonly omitted_sources: number | null;
readonly limitation: string | null;
}
/** One relevant file plus optional AST-only JavaScript facts. */
export interface AnalyzedJavaScriptArtifactFile {
readonly file: JavaScriptArtifactFile;
readonly javascript: JavaScriptStaticAnalysis | null;
}
/** Complete bounded static-analysis projection before graph construction. */
export interface JavaScriptArtifactAnalysis {
readonly files: readonly AnalyzedJavaScriptArtifactFile[];
readonly packages: readonly JavaScriptPackageObservation[];
readonly html_scripts: readonly JavaScriptHtmlScriptObservation[];
readonly source_maps: readonly JavaScriptSourceMapObservation[];
readonly visited_ast_nodes: number;
readonly findings: number;
readonly modules: number;
readonly parse_failures: number;
readonly truncated_scopes: number;
readonly limitations: readonly string[];
}
+406
View File
@@ -0,0 +1,406 @@
import { createHash } from "node:crypto";
import { isAbsolute } from "node:path";
import type { Readable } from "node:stream";
import { AsarArtifactReader } from "../artifacts/AsarArtifactReader.js";
import {
ArtifactPathRegistry,
normalizeArtifactPath,
} from "../artifacts/ArtifactPaths.js";
import {
ArtifactReaderFailure,
type ArtifactEntry,
type ArtifactReader,
} from "../artifacts/ArtifactReader.js";
import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
import type { JavaScriptArtifactReconstructionInput } from "./JavaScriptArtifactReconstructionInput.js";
/** Relevant file categories projected from the complete artifact inventory. */
export type JavaScriptArtifactFileKind =
| "package-json"
| "javascript"
| "html"
| "source-map"
| "native-addon";
/** One content-addressed local artifact file and its bounded text availability. */
export interface JavaScriptArtifactFile {
readonly path: string;
readonly container_sha256: string;
readonly sha256: string;
readonly bytes: number;
readonly inventory_artifact_id: string;
readonly kind: JavaScriptArtifactFileKind;
readonly unpacked: boolean;
readonly text:
| { readonly included: true; readonly value: string }
| {
readonly included: false;
readonly reason:
| "not-applicable"
| "not-approved"
| "file-limit"
| "byte-limit"
| "invalid-utf8";
};
}
/** One filesystem-backed ASAR nested beneath a directory input. */
export interface JavaScriptArtifactContainer {
readonly path: string;
readonly sha256: string;
readonly bytes: number;
readonly inventory_artifact_id: string;
}
/** Deterministic relevant-file projection plus explicit omissions. */
export interface JavaScriptArtifactFileSet {
readonly files: readonly JavaScriptArtifactFile[];
readonly containers: readonly JavaScriptArtifactContainer[];
readonly text_files_selected: number;
readonly text_bytes_read: number;
readonly omitted_text_files: number;
readonly limit_omitted_text_files: number;
readonly policy_filtered_text_files: number;
readonly invalid_utf8_files: number;
}
interface ExpectedFile {
readonly path: string;
readonly sha256: string;
readonly bytes: number;
readonly inventoryArtifactId: string;
readonly kind: JavaScriptArtifactFileKind;
}
interface Selection {
readonly selected: boolean;
readonly reason: "file-limit" | "byte-limit" | "not-approved" | null;
}
interface ReadContext {
readonly input: JavaScriptArtifactReconstructionInput;
readonly expected: ReadonlyMap<string, ExpectedFile>;
readonly expectedContainers: ReadonlyMap<string, JavaScriptArtifactContainer>;
readonly selections: ReadonlyMap<string, Selection>;
readonly registry: ArtifactPathRegistry;
readonly files: JavaScriptArtifactFile[];
readonly containers: JavaScriptArtifactContainer[];
readonly signal: AbortSignal | undefined;
textBytes: number;
invalidUtf8: number;
}
interface ReadTextInput {
readonly reader: ArtifactReader;
readonly entry: ArtifactEntry;
readonly expected: ExpectedFile;
readonly selection: Selection | undefined;
}
/** Read only selected textual entries through an already-inventoried reader. */
export const readJavaScriptArtifactFiles = async (
reader: ArtifactReader,
snapshot: ArtifactInventorySnapshot,
input: JavaScriptArtifactReconstructionInput,
signal?: AbortSignal,
): Promise<JavaScriptArtifactFileSet> => {
const inventory = expectedInventory(snapshot);
const expected = inventory.files;
const selections = selectTextFiles(expected, input);
const context: ReadContext = {
input,
expected,
expectedContainers: inventory.containers,
selections,
registry: new ArtifactPathRegistry(),
files: [],
containers: [],
signal,
textBytes: 0,
invalidUtf8: 0,
};
await visitReader(reader, "", snapshot.manifest.root_sha256, context);
const files = context.files.sort((left, right) =>
compareCodePoints(left.path, right.path),
);
assertExpectedFilesWereVisited(expected, files);
const selected = [...selections.values()].filter(
({ selected: isSelected }) => isSelected,
).length;
return {
files,
containers: context.containers.sort((left, right) =>
compareCodePoints(left.path, right.path),
),
text_files_selected: selected,
text_bytes_read: context.textBytes,
omitted_text_files: [...selections.values()].filter(
({ selected: isSelected }) => !isSelected,
).length,
limit_omitted_text_files: [...selections.values()].filter(
({ reason }) => reason === "file-limit" || reason === "byte-limit",
).length,
policy_filtered_text_files: [...selections.values()].filter(
({ reason }) => reason === "not-approved",
).length,
invalid_utf8_files: context.invalidUtf8,
};
};
const visitReader = async (
reader: ArtifactReader,
prefix: string,
containerSha256: string,
context: ReadContext,
): Promise<void> => {
for await (const entry of reader.entries(context.signal)) {
abortIfNeeded(context.signal);
const path = normalizeArtifactPath(
prefix === "" ? entry.path : `${prefix}/${entry.path}`,
{
maxDepth: context.input.limits.max_depth,
maxPathBytes: context.input.limits.max_path_bytes,
},
);
const nestedAsar = isFilesystemAsar(entry, path);
context.registry.add(path, nestedAsar ? "directory" : entry.kind);
if (nestedAsar) {
await visitNestedAsar(entry, path, context);
continue;
}
const expected = context.expected.get(path);
if (expected === undefined) continue;
const selection = context.selections.get(path);
const text = await readTextIfSelected(context, {
reader,
entry,
expected,
selection,
});
context.files.push({
path,
container_sha256: containerSha256,
sha256: expected.sha256,
bytes: expected.bytes,
inventory_artifact_id: expected.inventoryArtifactId,
kind: expected.kind,
unpacked: entry.unpacked,
text,
});
}
};
const visitNestedAsar = async (
entry: ArtifactEntry,
path: string,
context: ReadContext,
): Promise<void> => {
const inventory = expectedContainer(path, context);
context.containers.push(inventory);
const nested = new AsarArtifactReader(entry.adapterKey);
try {
await visitReader(nested, path, inventory.sha256, context);
} finally {
await nested.close();
}
};
const expectedContainer = (
path: string,
context: ReadContext,
): JavaScriptArtifactContainer => {
const container = context.expectedContainers.get(path);
if (container === undefined)
throw new ArtifactReaderFailure(
"integrity",
`Nested ASAR disappeared from inventory: ${path}`,
);
return container;
};
const readTextIfSelected = async (
context: ReadContext,
input: ReadTextInput,
): Promise<JavaScriptArtifactFile["text"]> => {
if (input.expected.kind === "native-addon")
return { included: false, reason: "not-applicable" };
if (input.selection?.selected !== true)
return {
included: false,
reason: input.selection?.reason ?? "file-limit",
};
const bytes = await readBounded(
await input.reader.open(input.entry, context.signal),
context.input.limits.max_text_file_bytes,
context.signal,
);
const digest = createHash("sha256").update(bytes).digest("hex");
if (digest !== input.expected.sha256 || bytes.length !== input.expected.bytes)
throw new ArtifactReaderFailure(
"integrity",
`Artifact entry changed after inventory: ${input.expected.path}`,
);
context.textBytes += bytes.length;
try {
return {
included: true,
value: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
};
} catch {
context.invalidUtf8 += 1;
return { included: false, reason: "invalid-utf8" };
}
};
const expectedInventory = (
snapshot: ArtifactInventorySnapshot,
): {
readonly files: ReadonlyMap<string, ExpectedFile>;
readonly containers: ReadonlyMap<string, JavaScriptArtifactContainer>;
} => {
const nodes = new Map(snapshot.nodes.map((node) => [node.artifact_id, node]));
const files = new Map<string, ExpectedFile>();
const containers = new Map<string, JavaScriptArtifactContainer>();
for (const occurrence of snapshot.occurrences) {
if (occurrence.artifact_id === null || occurrence.logical_path === ".")
continue;
const node = nodes.get(occurrence.artifact_id);
if (node === undefined)
throw new ArtifactReaderFailure(
"integrity",
`Artifact inventory node is missing: ${occurrence.logical_path}`,
);
if (occurrence.logical_path.toLowerCase().endsWith(".asar"))
containers.set(occurrence.logical_path, {
path: occurrence.logical_path,
sha256: node.sha256,
bytes: node.size,
inventory_artifact_id: node.artifact_id,
});
const kind = relevantKind(occurrence.logical_path);
if (kind === undefined) continue;
files.set(occurrence.logical_path, {
path: occurrence.logical_path,
sha256: node.sha256,
bytes: node.size,
inventoryArtifactId: node.artifact_id,
kind,
});
}
return { files, containers };
};
const selectTextFiles = (
files: ReadonlyMap<string, ExpectedFile>,
input: JavaScriptArtifactReconstructionInput,
): ReadonlyMap<string, Selection> => {
const selected = new Map<string, Selection>();
let fileCount = 0;
let bytes = 0;
const ordered = [...files.values()].sort((left, right) => {
const priority = filePriority(left.kind) - filePriority(right.kind);
return priority === 0 ? compareCodePoints(left.path, right.path) : priority;
});
for (const file of ordered) {
if (file.kind === "native-addon") continue;
if (file.kind === "source-map" && !input.source_map_read_approved) {
selected.set(file.path, { selected: false, reason: "not-approved" });
continue;
}
if (
fileCount >= input.limits.max_text_files ||
file.bytes > input.limits.max_text_file_bytes
) {
selected.set(file.path, { selected: false, reason: "file-limit" });
continue;
}
if (bytes + file.bytes > input.limits.max_total_text_bytes) {
selected.set(file.path, { selected: false, reason: "byte-limit" });
continue;
}
selected.set(file.path, { selected: true, reason: null });
fileCount += 1;
bytes += file.bytes;
}
return selected;
};
const readBounded = async (
stream: Readable,
maximum: number,
signal?: AbortSignal,
): Promise<Buffer> => {
const chunks: Buffer[] = [];
let bytes = 0;
for await (const raw of stream) {
abortIfNeeded(signal);
const chunk = streamChunkToBuffer(raw);
bytes += chunk.length;
if (bytes > maximum) {
stream.destroy();
throw new ArtifactReaderFailure(
"limit",
"Selected JavaScript artifact text exceeded its byte limit",
);
}
chunks.push(chunk);
}
return Buffer.concat(chunks, bytes);
};
const assertExpectedFilesWereVisited = (
expected: ReadonlyMap<string, ExpectedFile>,
actual: readonly JavaScriptArtifactFile[],
): void => {
const observed = new Set(actual.map(({ path }) => path));
for (const path of expected.keys())
if (!observed.has(path))
throw new ArtifactReaderFailure(
"integrity",
`Relevant artifact entry disappeared after inventory: ${path}`,
);
};
const relevantKind = (path: string): JavaScriptArtifactFileKind | undefined => {
const lower = path.toLowerCase();
if (lower === "package.json" || lower.endsWith("/package.json"))
return "package-json";
if (/\.(?:cjs|mjs|js|jsx|ts|tsx)$/u.test(lower)) return "javascript";
if (/\.html?$/u.test(lower)) return "html";
if (lower.endsWith(".map")) return "source-map";
if (lower.endsWith(".node")) return "native-addon";
return undefined;
};
const filePriority = (kind: JavaScriptArtifactFileKind): number => {
switch (kind) {
case "package-json":
return 0;
case "html":
return 1;
case "javascript":
return 2;
case "source-map":
return 3;
case "native-addon":
return 4;
}
};
const isFilesystemAsar = (entry: ArtifactEntry, path: string): boolean =>
entry.kind === "file" &&
path.toLowerCase().endsWith(".asar") &&
isAbsolute(entry.adapterKey);
const abortIfNeeded = (signal?: AbortSignal): void => {
if (signal?.aborted === true)
throw new ArtifactReaderFailure(
"cancelled",
"JavaScript artifact reconstruction cancelled",
);
};
const compareCodePoints = (left: string, right: string): number =>
left < right ? -1 : left > right ? 1 : 0;
@@ -0,0 +1,74 @@
import {
createJavaScriptApplicationEdge,
createJavaScriptApplicationNode,
type ApplicationEdge,
type ApplicationNode,
} from "../domain/javascriptApplicationGraph.js";
/** Deduplicate graph entities while retaining distinct evidence observations. */
export class JavaScriptArtifactGraphAccumulator {
readonly #nodes = new Map<string, ApplicationNode>();
readonly #edges = new Map<string, ApplicationEdge>();
#omittedObservations = 0;
/** Create or merge one canonical node. */
addNode(input: unknown): ApplicationNode {
const created = createJavaScriptApplicationNode(input);
const existing = this.#nodes.get(created.node_id);
if (existing === undefined) {
this.#nodes.set(created.node_id, created);
return created;
}
const bySemanticId = new Map(
[...existing.observations, ...created.observations].map((observation) => [
observation.observation_id,
observationInput(observation),
]),
);
const observations = [...bySemanticId.entries()]
.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
.slice(0, 64)
.map(([, observation]) => observation);
this.#omittedObservations += Math.max(0, bySemanticId.size - 64);
const merged = createJavaScriptApplicationNode({
kind: existing.kind,
identity: existing.identity,
observations,
});
this.#nodes.set(merged.node_id, merged);
return merged;
}
/** Create or replace one canonical edge by semantic identifier. */
addEdge(input: unknown): ApplicationEdge {
const edge = createJavaScriptApplicationEdge(input);
this.#edges.set(edge.edge_id, edge);
return edge;
}
/** Return all accumulated canonical nodes. */
nodes(): readonly ApplicationNode[] {
return [...this.#nodes.values()];
}
/** Return all accumulated canonical edges. */
edges(): readonly ApplicationEdge[] {
return [...this.#edges.values()];
}
/** Count distinct node observations omitted by the graph contract bound. */
omittedObservations(): number {
return this.#omittedObservations;
}
}
const observationInput = (
observation: ApplicationNode["observations"][number],
) => {
const {
observation_id: _observationId,
identifier_strategy: _strategy,
...input
} = observation;
return input;
};
@@ -0,0 +1,153 @@
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
import {
createJavaScriptApplicationGraph,
type JavaScriptApplicationGraph,
} from "../domain/javascriptApplicationGraph.js";
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
import type { JavaScriptArtifactFileSet } from "./JavaScriptArtifactFiles.js";
import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
import {
javaScriptAnalysisLimits,
type JavaScriptArtifactGraphContext,
} from "./JavaScriptArtifactGraphContext.js";
import {
addJavaScriptHtmlRoles,
addJavaScriptSourceMapOriginals,
} from "./JavaScriptArtifactGraphDocuments.js";
import { addJavaScriptStaticFindings } from "./JavaScriptArtifactGraphFindings.js";
import {
completeReconstructionCoverage,
partialReconstructionCoverage,
} from "./JavaScriptArtifactGraphEvidence.js";
import {
addJavaScriptArtifactContainers,
addJavaScriptArtifactFiles,
addJavaScriptBundlerNodes,
addJavaScriptPackageNodes,
createJavaScriptArtifactRootNode,
} from "./JavaScriptArtifactGraphStructure.js";
import type { JavaScriptArtifactReconstructionInput } from "./JavaScriptArtifactReconstructionInput.js";
/** Project bounded artifact and AST facts into JavaScript Application Graph v1. */
export const buildJavaScriptArtifactGraph = (
snapshot: ArtifactInventorySnapshot,
fileSet: JavaScriptArtifactFileSet,
analysis: JavaScriptArtifactAnalysis,
input: JavaScriptArtifactReconstructionInput,
): JavaScriptApplicationGraph => {
const accumulator = new JavaScriptArtifactGraphAccumulator();
const root = createJavaScriptArtifactRootNode(accumulator, snapshot);
const context: JavaScriptArtifactGraphContext = {
accumulator,
snapshot,
fileSet,
analysis,
input,
root,
filesByPath: new Map(fileSet.files.map((file) => [file.path, file])),
fileNodes: new Map(),
assetNodes: new Map(),
moduleNodes: new Map(),
containerNodes: new Map([[snapshot.manifest.root_sha256, root]]),
};
addJavaScriptArtifactContainers(context);
addJavaScriptArtifactFiles(context);
const packageRoots = addJavaScriptPackageNodes(context);
addJavaScriptBundlerNodes(context);
addJavaScriptStaticFindings(context);
addJavaScriptHtmlRoles(context);
addJavaScriptSourceMapOriginals(context);
const coverage = graphCoverage(context);
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
schema_version: 1,
root_node_ids:
packageRoots.length === 0
? [root.node_id]
: packageRoots.map(({ node_id: id }) => id),
nodes: accumulator.nodes(),
edges: accumulator.edges(),
coverage,
limitations: graphLimitations(context, coverage.status),
});
};
const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
const exactLimitOmissions =
context.fileSet.limit_omitted_text_files +
context.accumulator.omittedObservations();
const sourceMapPolicyGap = context.analysis.source_maps.some(
({ status }) => status === "not-approved",
);
const malformedStructuredData =
context.analysis.packages.some(({ status }) => status !== "included") ||
context.analysis.source_maps.some(({ status }) => status === "invalid");
const unknownGap =
context.analysis.parse_failures > 0 ||
context.fileSet.invalid_utf8_files > 0 ||
sourceMapPolicyGap ||
malformedStructuredData;
if (context.analysis.truncated_scopes > 0)
return partialReconstructionCoverage(
reconstructionLimits(context.input),
null,
true,
);
if (exactLimitOmissions > 0)
return partialReconstructionCoverage(
reconstructionLimits(context.input),
exactLimitOmissions,
true,
);
if (unknownGap)
return partialReconstructionCoverage(
reconstructionLimits(context.input),
null,
false,
);
return completeReconstructionCoverage(reconstructionLimits(context.input));
};
const graphLimitations = (
context: JavaScriptArtifactGraphContext,
coverage: "complete" | "partial" | "unknown" | "unavailable",
): string[] => [
...context.analysis.limitations,
"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.accumulator.omittedObservations() === 0
? []
: [
"Repeated content identities exceeded the per-node observation bound; containment edges still preserve inventoried paths.",
]),
...(coverage === "complete"
? []
: [
"Graph coverage is incomplete; unavailable facts remain explicit and must not be read as absence.",
]),
];
const reconstructionLimits = (input: JavaScriptArtifactReconstructionInput) => [
{
name: "max-entries",
value: input.limits.max_entries,
unit: "items" as const,
},
{
name: "max-total-artifact-bytes",
value: input.limits.max_total_artifact_bytes,
unit: "bytes" as const,
},
{
name: "max-text-files",
value: input.limits.max_text_files,
unit: "items" as const,
},
{
name: "max-total-text-bytes",
value: input.limits.max_total_text_bytes,
unit: "bytes" as const,
},
...javaScriptAnalysisLimits(input),
{ name: "max-observations-per-node", value: 64, unit: "items" as const },
];
@@ -0,0 +1,359 @@
import { posix } from "node:path";
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
import type { ApplicationGraphEvidence } from "../domain/javascriptApplicationEvidenceSchemas.js";
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import type { JavaScriptSourceRange } from "../domain/javascriptStaticAnalysisTypes.js";
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
import type {
JavaScriptArtifactFile,
JavaScriptArtifactFileSet,
} from "./JavaScriptArtifactFiles.js";
import { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
import {
artifactObservationEvidence,
astObservationEvidence,
completeReconstructionCoverage,
partialReconstructionCoverage,
staticInferenceEvidence,
unavailableAstEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
import type { JavaScriptArtifactReconstructionInput } from "./JavaScriptArtifactReconstructionInput.js";
/** Mutable graph-construction state scoped to one reconstruction. */
export interface JavaScriptArtifactGraphContext {
readonly accumulator: JavaScriptArtifactGraphAccumulator;
readonly snapshot: ArtifactInventorySnapshot;
readonly fileSet: JavaScriptArtifactFileSet;
readonly analysis: JavaScriptArtifactAnalysis;
readonly input: JavaScriptArtifactReconstructionInput;
readonly root: ApplicationNode;
readonly filesByPath: ReadonlyMap<string, JavaScriptArtifactFile>;
readonly fileNodes: Map<string, ApplicationNode>;
readonly assetNodes: Map<string, ApplicationNode>;
readonly moduleNodes: Map<string, ApplicationNode>;
readonly containerNodes: Map<string, ApplicationNode>;
}
/** Evidence coverage shape shared by reconstruction graph helpers. */
export type JavaScriptArtifactGraphCoverage =
ApplicationGraphEvidence["coverage"];
/** Direct artifact-containment edge values. */
export interface ContainsEdgeInput {
readonly source: ApplicationNode;
readonly target: ApplicationNode;
readonly file: JavaScriptArtifactFile;
readonly operation: string;
}
/** Exact AST containment edge values. */
export interface AstEdgeInput {
readonly source: ApplicationNode;
readonly target: ApplicationNode;
readonly file: JavaScriptArtifactFile;
readonly range: JavaScriptSourceRange;
readonly coverage: JavaScriptArtifactGraphCoverage;
readonly properties: Readonly<Record<string, unknown>>;
}
/** Inferred static relationship edge values. */
export interface InferenceEdgeInput extends AstEdgeInput {
readonly relation:
| "imports"
| "loads"
| "maps_to"
| "exposes"
| "calls"
| "persists_to";
}
/** Electron role identity and static discovery evidence. */
export interface RoleNodeInput {
readonly kind: "electron-main" | "electron-preload" | "electron-renderer";
readonly anchor: JavaScriptArtifactFile;
readonly declaredPath: string;
readonly resolvedPath: string | null;
readonly mechanism: string;
readonly range?: JavaScriptSourceRange;
readonly coverage?: JavaScriptArtifactGraphCoverage;
}
/** Resolution from an inferred Electron role to an artifact asset. */
export interface RoleAssetLinkInput {
readonly role: ApplicationNode;
readonly anchor: JavaScriptArtifactFile;
readonly path: string | null;
readonly range?: JavaScriptSourceRange;
readonly coverage?: JavaScriptArtifactGraphCoverage;
}
/** Explicit package, JavaScript, or source-map parse gap. */
export interface UnavailableParseInput {
readonly file: JavaScriptArtifactFile;
readonly asset: ApplicationNode;
readonly operation: string;
readonly limitation: string;
}
/** Add a direct artifact-containment edge. */
export const addArtifactContainsEdge = (
context: JavaScriptArtifactGraphContext,
input: ContainsEdgeInput,
): void => {
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: JavaScriptArtifactGraphContext,
input: AstEdgeInput,
): void => {
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: JavaScriptArtifactGraphContext,
input: InferenceEdgeInput,
): void => {
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: JavaScriptArtifactGraphContext,
input: UnavailableParseInput,
): void => {
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: NonNullable<
JavaScriptArtifactAnalysis["files"][number]["javascript"]
>,
input: JavaScriptArtifactReconstructionInput,
): JavaScriptArtifactGraphCoverage =>
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: string,
namespace: string,
key: string,
) => ({
strategy: "artifact-local-key" as const,
stability: "artifact-version" as const,
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: JavaScriptArtifactGraphContext,
input: RoleNodeInput,
): ApplicationNode =>
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: JavaScriptArtifactGraphContext,
input: RoleAssetLinkInput,
): void => {
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: string, moduleKey: string): string =>
`${path}\0${moduleKey}`;
/** Resolve a relative static specifier without escaping the artifact root. */
export const resolveArtifactPath = (
specifier: string,
sourcePath: string,
files: ReadonlyMap<string, JavaScriptArtifactFile>,
): string | null => {
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: JavaScriptArtifactGraphContext,
path: string,
moduleKey: string | null,
): ApplicationNode | undefined =>
moduleKey === null
? undefined
: context.moduleNodes.get(moduleLookupKey(path, moduleKey));
const pathCandidates = (path: string): readonly string[] => [
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: JavaScriptArtifactReconstructionInput,
) => [
{
name: "max-ast-nodes",
value: input.limits.max_ast_nodes,
unit: "items" as const,
},
{
name: "max-findings",
value: input.limits.max_findings,
unit: "items" as const,
},
{
name: "max-modules",
value: input.limits.max_modules,
unit: "items" as const,
},
{
name: "max-parse-milliseconds",
value: input.limits.max_parse_milliseconds,
unit: "milliseconds" as const,
},
];
@@ -0,0 +1,134 @@
import {
addArtifactContainsEdge,
addStaticInferenceEdge,
createElectronRoleNode,
resolveArtifactPath,
type JavaScriptArtifactGraphContext,
} from "./JavaScriptArtifactGraphContext.js";
import {
artifactObservationEvidence,
completeReconstructionCoverage,
partialReconstructionCoverage,
} from "./JavaScriptArtifactGraphEvidence.js";
/** Project HTML renderer entrypoints and their local script assets. */
export const addJavaScriptHtmlRoles = (
context: JavaScriptArtifactGraphContext,
): void => {
const byHtml = new Map<string, typeof context.analysis.html_scripts>();
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: JavaScriptArtifactGraphContext,
): void => {
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],
}),
});
}
}
};
@@ -0,0 +1,130 @@
import type { ApplicationGraphEvidence } from "../domain/javascriptApplicationEvidenceSchemas.js";
import type { JavaScriptSourceRange } from "../domain/javascriptStaticAnalysisTypes.js";
const EXTRACTOR = {
name: "rea-javascript-artifact-reconstruction",
version: "1",
executable_sha256: null,
} as const;
/** Coverage shape accepted by reconstruction evidence helpers. */
export type ReconstructionEvidenceCoverage =
ApplicationGraphEvidence["coverage"];
/** Shared exact artifact location and bounded coverage for static evidence. */
export interface EvidenceInput {
readonly sha256: string;
readonly path: string;
readonly operation: string;
readonly coverage: ReconstructionEvidenceCoverage;
readonly limitations?: readonly string[];
readonly range?: JavaScriptSourceRange;
}
/** Exact artifact-byte evidence for one safely inventoried local file. */
export const artifactObservationEvidence = (
input: EvidenceInput,
): ApplicationGraphEvidence => ({
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: EvidenceInput & { readonly range: JavaScriptSourceRange },
): ApplicationGraphEvidence => ({
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: EvidenceInput & {
readonly confidence?: "high" | "medium" | "low";
},
): ApplicationGraphEvidence => ({
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: EvidenceInput & { readonly limitation: string },
): ApplicationGraphEvidence => ({
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: ReconstructionEvidenceCoverage["limits"] = [],
): ReconstructionEvidenceCoverage => ({
status: "complete",
truncated: false,
omitted_count: 0,
limits: [...limits],
});
/** Partial reconstruction coverage with either exact truncation or a policy gap. */
export const partialReconstructionCoverage = (
limits: ReconstructionEvidenceCoverage["limits"],
omitted: number | null,
truncated: boolean,
): ReconstructionEvidenceCoverage => ({
status: "partial",
truncated,
omitted_count: omitted,
limits: [...limits],
});
const artifactReference = (sha256: string) => ({
available: true as const,
artifact_id: `art_${sha256}`,
sha256,
});
@@ -0,0 +1,380 @@
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import type { JavaScriptStaticAnalysis } from "../domain/javascriptStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import {
addStaticInferenceEdge,
artifactLocalIdentity,
createElectronRoleNode,
javascriptAnalysisCoverage,
linkElectronRoleToAsset,
moduleLookupKey,
resolveArtifactPath,
sourceNodeFor,
type JavaScriptArtifactGraphContext,
type JavaScriptArtifactGraphCoverage,
} from "./JavaScriptArtifactGraphContext.js";
import {
astObservationEvidence,
staticInferenceEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
type StaticReference = JavaScriptStaticAnalysis["references"][number];
type StaticEndpoint = JavaScriptStaticAnalysis["endpoints"][number];
type StaticStorage = JavaScriptStaticAnalysis["storage"][number];
type StaticRolePath = JavaScriptStaticAnalysis["role_paths"][number];
type StaticSourceMap = JavaScriptStaticAnalysis["source_map_urls"][number];
interface FindingInput<Value> {
readonly file: JavaScriptArtifactFile;
readonly asset: ApplicationNode;
readonly value: Value;
readonly coverage: JavaScriptArtifactGraphCoverage;
}
interface ResolvedReference {
readonly path: string;
readonly file: JavaScriptArtifactFile;
readonly node: ApplicationNode;
}
/** Project imports, workers, roles, endpoints, storage, and source-map links. */
export const addJavaScriptStaticFindings = (
context: JavaScriptArtifactGraphContext,
): void => {
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: JavaScriptArtifactGraphContext,
input: FindingInput<StaticReference>,
): void => {
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: JavaScriptArtifactGraphContext,
input: FindingInput<StaticEndpoint>,
): void => {
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: JavaScriptArtifactGraphContext,
input: FindingInput<StaticStorage>,
): void => {
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: JavaScriptArtifactGraphContext,
input: FindingInput<StaticRolePath>,
): void => {
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: JavaScriptArtifactGraphContext,
input: FindingInput<StaticSourceMap>,
): void => {
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: JavaScriptArtifactGraphContext,
sourcePath: string,
specifier: string,
): ResolvedReference | null => {
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: JavaScriptArtifactGraphContext,
file: JavaScriptArtifactFile,
reference: StaticReference,
coverage: JavaScriptArtifactGraphCoverage,
): ApplicationNode =>
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.",
],
}),
},
],
});
@@ -0,0 +1,501 @@
import type { ArtifactInventorySnapshot } from "./ArtifactInventory.js";
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
import type {
JavaScriptArtifactContainer,
JavaScriptArtifactFile,
JavaScriptArtifactFileKind,
} from "./JavaScriptArtifactFiles.js";
import type { JavaScriptArtifactGraphAccumulator } from "./JavaScriptArtifactGraphAccumulator.js";
import {
addArtifactContainsEdge,
addAstContainsEdge,
addUnavailableStaticParseScope,
artifactLocalIdentity,
createElectronRoleNode,
javascriptAnalysisCoverage,
linkElectronRoleToAsset,
moduleLookupKey,
resolveArtifactPath,
type JavaScriptArtifactGraphContext,
} from "./JavaScriptArtifactGraphContext.js";
import {
artifactObservationEvidence,
astObservationEvidence,
completeReconstructionCoverage,
staticInferenceEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
interface PackageRoleInput {
readonly packageNode: ApplicationNode;
readonly packageFile: JavaScriptArtifactFile;
readonly kind: "electron-main" | "electron-renderer";
readonly declaredPath: string | null;
}
/** Create the exact root artifact node from the inventory manifest. */
export const createJavaScriptArtifactRootNode = (
accumulator: JavaScriptArtifactGraphAccumulator,
snapshot: ArtifactInventorySnapshot,
): ApplicationNode => {
const root = snapshot.nodes.find(
({ artifact_id: id }) => id === snapshot.manifest.root_artifact_id,
);
if (root === undefined)
throw new TypeError("Artifact inventory root is missing");
return accumulator.addNode({
kind: "artifact",
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: root.sha256,
},
observations: [
{
label: "artifact root",
properties: {
format: snapshot.manifest.root_format,
bytes: root.size,
inventory_manifest_id: snapshot.manifest.manifest_id,
inventory_graph_sha256: snapshot.manifest.graph_sha256,
inventory_artifact_id: root.artifact_id,
},
evidence: artifactObservationEvidence({
sha256: root.sha256,
path: "artifact-root",
operation: "inventory-root",
coverage: completeReconstructionCoverage(),
limitations: [
"artifact-root is a path-independent alias; the application result retains the canonical local input path.",
],
}),
},
],
});
};
/** Project nested ASAR containers inventoried inside a directory. */
export const addJavaScriptArtifactContainers = (
context: JavaScriptArtifactGraphContext,
): void => {
for (const container of context.fileSet.containers) {
const node = context.accumulator.addNode({
kind: "artifact",
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: container.sha256,
},
observations: [
{
label: container.path,
properties: containerProperties(container),
evidence: artifactObservationEvidence({
sha256: container.sha256,
path: container.path,
operation: "inventory-nested-asar",
coverage: completeReconstructionCoverage(),
}),
},
],
});
context.containerNodes.set(container.sha256, node);
context.accumulator.addEdge({
source_node_id: context.root.node_id,
target_node_id: node.node_id,
relation: "contains",
properties: { path: container.path, format: "asar" },
evidence: artifactObservationEvidence({
sha256: context.snapshot.manifest.root_sha256,
path: container.path,
operation: "inventory-nested-asar",
coverage: completeReconstructionCoverage(),
}),
});
}
};
/** Project relevant files, ASAR entries, and explicit unavailable parse scopes. */
export const addJavaScriptArtifactFiles = (
context: JavaScriptArtifactGraphContext,
): void => {
for (const analyzed of context.analysis.files) {
const { file } = analyzed;
const target = createFileTarget(context, file, analyzed.javascript);
context.fileNodes.set(file.path, target);
if (file.kind === "javascript") context.assetNodes.set(file.path, target);
const entry = createAsarEntry(context, file);
const parent =
context.containerNodes.get(file.container_sha256) ?? context.root;
if (entry === undefined)
addArtifactContainsEdge(context, {
source: parent,
target,
file,
operation: "inventory-file",
});
else {
addArtifactContainsEdge(context, {
source: parent,
target: entry,
file,
operation: "inventory-entry",
});
context.accumulator.addEdge({
source_node_id: entry.node_id,
target_node_id: target.node_id,
relation: "maps_to",
properties: { sha256: file.sha256 },
evidence: artifactObservationEvidence({
sha256: file.container_sha256,
path: file.path,
operation: "map-entry-content",
coverage: completeReconstructionCoverage(),
}),
});
}
if (
file.kind === "javascript" &&
(analyzed.javascript === null ||
analyzed.javascript.parse_status === "failed")
)
addUnavailableStaticParseScope(context, {
file,
asset: target,
operation: "parse-javascript",
limitation: file.text.included
? "JavaScript syntax could not be parsed."
: `JavaScript text was unavailable: ${file.text.reason}.`,
});
const packageValue = context.analysis.packages.find(
({ path }) => path === file.path,
);
if (
packageValue?.status !== undefined &&
packageValue.status !== "included"
)
addUnavailableStaticParseScope(context, {
file,
asset: target,
operation: "parse-package-json",
limitation:
packageValue.limitation ?? "Package metadata could not be parsed.",
});
const sourceMap = context.analysis.source_maps.find(
({ path }) => path === file.path,
);
if (
sourceMap !== undefined &&
(sourceMap.status === "invalid" || sourceMap.status === "not-approved")
)
addUnavailableStaticParseScope(context, {
file,
asset: target,
operation: "parse-local-source-map",
limitation:
sourceMap.limitation ?? "Source-map content could not be parsed.",
});
}
};
/** Project package metadata and its declared Electron roles. */
export const addJavaScriptPackageNodes = (
context: JavaScriptArtifactGraphContext,
): ApplicationNode[] => {
const roots: ApplicationNode[] = [];
for (const packageValue of context.analysis.packages) {
const file = context.filesByPath.get(packageValue.path);
if (file === undefined) continue;
const node = context.accumulator.addNode({
kind: "package",
identity: artifactLocalIdentity(file.sha256, "package-json", file.path),
observations: [
{
label: packageValue.name ?? file.path,
properties: {
path: file.path,
name: packageValue.name,
version: packageValue.version,
main: packageValue.main,
renderer: packageValue.renderer,
parse_status: packageValue.status,
},
evidence: artifactObservationEvidence({
sha256: file.sha256,
path: file.path,
operation: "parse-package-json",
coverage: completeReconstructionCoverage(),
limitations:
packageValue.limitation === null ? [] : [packageValue.limitation],
}),
},
],
});
if (roots.length === 0) {
roots.push(node);
context.accumulator.addEdge({
source_node_id: node.node_id,
target_node_id: context.root.node_id,
relation: "contains",
properties: { basis: "package-metadata-within-artifact" },
evidence: staticInferenceEvidence({
sha256: file.sha256,
path: file.path,
operation: "associate-package-artifact",
coverage: completeReconstructionCoverage(),
}),
});
} else
addArtifactContainsEdge(context, {
source: context.root,
target: node,
file,
operation: "inventory-package",
});
addPackageRole(context, {
packageNode: node,
packageFile: file,
kind: "electron-main",
declaredPath: packageValue.main,
});
addPackageRole(context, {
packageNode: node,
packageFile: file,
kind: "electron-renderer",
declaredPath: packageValue.renderer,
});
}
return roots;
};
/** Project Webpack/Rspack chunk and factory literals recovered from AST. */
export const addJavaScriptBundlerNodes = (
context: JavaScriptArtifactGraphContext,
): void => {
for (const analyzed of context.analysis.files) {
const { file, javascript } = analyzed;
const asset = context.assetNodes.get(file.path);
if (javascript === null || asset === undefined) continue;
const coverage = javascriptAnalysisCoverage(javascript, context.input);
for (const registration of javascript.bundler_registrations) {
const chunkKey = `${registration.runtime}:${registration.chunk_keys.join(",")}`;
const chunk = context.accumulator.addNode({
kind: "javascript-chunk",
identity: artifactLocalIdentity(file.sha256, "bundler-chunk", chunkKey),
observations: [
{
label: chunkKey,
properties: {
path: file.path,
bundler: registration.bundler,
runtime: registration.runtime,
chunk_keys: registration.chunk_keys,
omitted_chunk_keys: registration.omitted_chunk_keys,
unknown_chunk_keys: registration.unknown_chunk_keys,
module_count: registration.modules.length,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: registration.location,
operation: "extract-bundler-registration",
coverage,
limitations: javascript.limitations,
}),
},
],
});
addAstContainsEdge(context, {
source: asset,
target: chunk,
file,
range: registration.location,
coverage,
properties: { bundler: registration.bundler },
});
for (const moduleValue of registration.modules) {
const module = context.accumulator.addNode({
kind: "javascript-module",
identity: artifactLocalIdentity(
file.sha256,
`${registration.runtime}:module`,
moduleValue.module_key,
),
observations: [
{
label: moduleValue.module_key,
properties: {
path: file.path,
bundler: registration.bundler,
runtime: registration.runtime,
module_key: moduleValue.module_key,
source_sha256: moduleValue.source_sha256,
structural_fingerprint_sha256:
moduleValue.structural_fingerprint_sha256,
structural_fingerprint_algorithm:
moduleValue.structural_fingerprint_algorithm,
structural_fingerprint_status:
moduleValue.structural_fingerprint_status,
exports: moduleValue.exports,
exports_truncated: moduleValue.exports_truncated,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: moduleValue.location,
operation: "extract-bundler-module",
coverage,
limitations: javascript.limitations,
}),
},
],
});
context.moduleNodes.set(
moduleLookupKey(file.path, moduleValue.module_key),
module,
);
addAstContainsEdge(context, {
source: chunk,
target: module,
file,
range: moduleValue.location,
coverage,
properties: { module_key: moduleValue.module_key },
});
}
}
}
};
const createFileTarget = (
context: JavaScriptArtifactGraphContext,
file: JavaScriptArtifactFile,
javascript: JavaScriptArtifactAnalysis["files"][number]["javascript"],
): ApplicationNode => {
const kind = artifactFileNodeKind(file.kind);
return context.accumulator.addNode({
kind,
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: file.sha256,
},
observations: [
{
label: file.path,
properties: {
path: file.path,
bytes: file.bytes,
inventory_artifact_id: file.inventory_artifact_id,
unpacked: file.unpacked,
file_kind: file.kind,
text_status: file.text.included ? "included" : file.text.reason,
parse_status: javascript?.parse_status ?? null,
vendor_markers: javascript?.vendors ?? [],
},
evidence: artifactObservationEvidence({
sha256: file.sha256,
path: file.path,
operation: "inventory-relevant-file",
coverage: completeReconstructionCoverage(),
}),
},
],
});
};
const artifactFileNodeKind = (
kind: JavaScriptArtifactFileKind,
): ApplicationNode["kind"] =>
kind === "javascript"
? "javascript-asset"
: kind === "source-map"
? "source-map"
: kind === "native-addon"
? "native-addon"
: "artifact";
const createAsarEntry = (
context: JavaScriptArtifactGraphContext,
file: JavaScriptArtifactFile,
): ApplicationNode | undefined => {
const isAsar =
context.snapshot.manifest.root_format === "asar" ||
file.container_sha256 !== context.snapshot.manifest.root_sha256;
if (!isAsar) return undefined;
return context.accumulator.addNode({
kind: "asar-entry",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: file.container_sha256,
path: file.path,
},
observations: [
{
label: file.path,
properties: {
entry_sha256: file.sha256,
bytes: file.bytes,
unpacked: file.unpacked,
inventory_artifact_id: file.inventory_artifact_id,
},
evidence: artifactObservationEvidence({
sha256: file.container_sha256,
path: file.path,
operation: "inventory-asar-entry",
coverage: completeReconstructionCoverage(),
}),
},
],
});
};
const addPackageRole = (
context: JavaScriptArtifactGraphContext,
input: PackageRoleInput,
): void => {
if (input.declaredPath === null) return;
const resolvedPath = resolveArtifactPath(
input.declaredPath,
input.packageFile.path,
context.filesByPath,
);
const role = createElectronRoleNode(context, {
kind: input.kind,
anchor: input.packageFile,
declaredPath: input.declaredPath,
resolvedPath,
mechanism:
input.kind === "electron-main"
? "package.json:main"
: "package.json:renderer",
});
context.accumulator.addEdge({
source_node_id: input.packageNode.node_id,
target_node_id: role.node_id,
relation: "loads",
properties: {
declared_path: input.declaredPath,
resolved_path: resolvedPath,
},
evidence: staticInferenceEvidence({
sha256: input.packageFile.sha256,
path: input.packageFile.path,
operation: "discover-package-entrypoint",
coverage: completeReconstructionCoverage(),
}),
});
linkElectronRoleToAsset(context, {
role,
anchor: input.packageFile,
path: resolvedPath,
});
};
const containerProperties = (container: JavaScriptArtifactContainer) => ({
path: container.path,
format: "asar",
bytes: container.bytes,
inventory_artifact_id: container.inventory_artifact_id,
});
@@ -0,0 +1,152 @@
import { lstat, realpath } from "node:fs/promises";
import { performance } from "node:perf_hooks";
import { AsarArtifactReader } from "../artifacts/AsarArtifactReader.js";
import {
ArtifactReaderFailure,
type ArtifactReader,
} from "../artifacts/ArtifactReader.js";
import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
import type { JavaScriptApplicationGraph } from "../domain/javascriptApplicationGraph.js";
import { analyzeJavaScriptArtifactFiles } from "./JavaScriptArtifactAnalysis.js";
import { readJavaScriptArtifactFiles } from "./JavaScriptArtifactFiles.js";
import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.js";
import {
artifactLimitsForReconstruction,
javascriptArtifactReconstructionInputSchema,
type JavaScriptArtifactReconstructionInput,
} from "./JavaScriptArtifactReconstructionInput.js";
import { scanCanonicalArtifactInventory } from "./ArtifactInventory.js";
/** Application-layer result retaining local diagnostics outside the canonical graph. */
export interface JavaScriptArtifactReconstructionResult {
readonly input_path: string;
readonly format: "asar" | "directory";
readonly inventory_manifest_id: string;
readonly inventory_graph_sha256: string;
readonly graph: JavaScriptApplicationGraph;
readonly statistics: {
readonly relevant_files: number;
readonly nested_asar_containers: number;
readonly text_files_selected: number;
readonly text_bytes_read: number;
readonly omitted_text_files: number;
readonly limit_omitted_text_files: number;
readonly policy_filtered_text_files: number;
readonly invalid_utf8_files: number;
readonly parsed_javascript_files: number;
readonly visited_ast_nodes: number;
readonly findings: number;
readonly modules: number;
readonly parse_failures: number;
readonly truncated_scopes: number;
};
readonly limitations: readonly string[];
}
/** Reconstruct one local ASAR or extracted directory without executing code. */
export const reconstructJavaScriptArtifact = async (
rawInput: unknown,
signal?: AbortSignal,
): Promise<JavaScriptArtifactReconstructionResult> => {
const input = javascriptArtifactReconstructionInputSchema.parse(rawInput);
abortIfNeeded(signal);
const path = await realpath(input.input_path);
const format = await resolveFormat(path, input);
const snapshot = await scanCanonicalArtifactInventory(
path,
artifactLimitsForReconstruction(input),
signal,
);
if (snapshot.manifest.root_format !== format)
throw new ArtifactReaderFailure(
"format",
`Artifact inventory classified ${path} as ${snapshot.manifest.root_format}, not ${format}`,
);
const reader = createReader(path, format);
try {
const files = await readJavaScriptArtifactFiles(
reader,
snapshot,
input,
signal,
);
const analysis = analyzeJavaScriptArtifactFiles(files, input, () =>
performance.now(),
);
abortIfNeeded(signal);
const graph = buildJavaScriptArtifactGraph(
snapshot,
files,
analysis,
input,
);
return {
input_path: path,
format,
inventory_manifest_id: snapshot.manifest.manifest_id,
inventory_graph_sha256: snapshot.manifest.graph_sha256,
graph,
statistics: {
relevant_files: files.files.length,
nested_asar_containers: files.containers.length,
text_files_selected: files.text_files_selected,
text_bytes_read: files.text_bytes_read,
omitted_text_files: files.omitted_text_files,
limit_omitted_text_files: files.limit_omitted_text_files,
policy_filtered_text_files: files.policy_filtered_text_files,
invalid_utf8_files: files.invalid_utf8_files,
parsed_javascript_files: analysis.files.filter(
({ javascript }) => javascript !== null,
).length,
visited_ast_nodes: analysis.visited_ast_nodes,
findings: analysis.findings,
modules: analysis.modules,
parse_failures: analysis.parse_failures,
truncated_scopes: analysis.truncated_scopes,
},
limitations: analysis.limitations,
};
} finally {
await reader.close();
}
};
const resolveFormat = async (
path: string,
input: JavaScriptArtifactReconstructionInput,
): Promise<"asar" | "directory"> => {
const metadata = await lstat(path);
const observed = metadata.isDirectory()
? "directory"
: metadata.isFile() && path.toLowerCase().endsWith(".asar")
? "asar"
: undefined;
if (observed === undefined)
throw new ArtifactReaderFailure(
"format",
`JavaScript artifact reconstruction accepts only a directory or .asar file: ${path}`,
);
if (input.format !== "auto" && input.format !== observed)
throw new ArtifactReaderFailure(
"format",
`Requested ${input.format} input but observed ${observed}: ${path}`,
);
return observed;
};
const createReader = (
path: string,
format: "asar" | "directory",
): ArtifactReader =>
format === "asar"
? new AsarArtifactReader(path)
: new DirectoryArtifactReader(path);
const abortIfNeeded = (signal?: AbortSignal): void => {
if (signal?.aborted === true)
throw new ArtifactReaderFailure(
"cancelled",
"JavaScript artifact reconstruction cancelled",
);
};
@@ -0,0 +1,116 @@
import { z } from "zod";
import type { ArtifactLimits } from "../artifacts/ArtifactReader.js";
const MAX_GRAPH_NODES = 100_000;
const MAX_GRAPH_EDGES = 200_000;
const reconstructionLimitsSchema = z
.strictObject({
max_entries: z.number().int().min(1).max(1_000_000).default(8_000),
max_total_artifact_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(512 * 1_024 * 1_024),
max_artifact_entry_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(128 * 1_024 * 1_024),
max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
max_depth: z.number().int().min(1).max(100).default(64),
max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
max_text_files: z.number().int().min(1).max(100_000).default(5_000),
max_total_text_bytes: z
.number()
.int()
.min(1)
.max(512 * 1_024 * 1_024)
.default(128 * 1_024 * 1_024),
max_text_file_bytes: z
.number()
.int()
.min(1)
.max(64 * 1_024 * 1_024)
.default(8 * 1_024 * 1_024),
max_ast_nodes: z.number().int().min(1).max(20_000_000).default(2_000_000),
max_findings: z.number().int().min(1).max(200_000).default(10_000),
max_modules: z.number().int().min(1).max(100_000).default(20_000),
max_source_map_sources: z.number().int().min(1).max(100_000).default(5_000),
max_parse_milliseconds: z
.number()
.int()
.min(1)
.max(300_000)
.default(30_000),
})
.superRefine((limits, context) => {
const projectedNodes =
7 * limits.max_entries +
limits.max_findings +
limits.max_modules +
limits.max_source_map_sources +
1;
if (projectedNodes > MAX_GRAPH_NODES)
context.addIssue({
code: "custom",
path: ["max_entries"],
message:
"Combined reconstruction limits can exceed the 100000-node graph contract",
});
const projectedEdges =
9 * limits.max_entries +
5 * limits.max_findings +
limits.max_modules +
limits.max_source_map_sources;
if (projectedEdges > MAX_GRAPH_EDGES)
context.addIssue({
code: "custom",
path: ["max_entries"],
message:
"Combined reconstruction limits can exceed the 200000-edge graph contract",
});
});
/** Local ASAR/directory reconstruction request with explicit source-map authority. */
export const javascriptArtifactReconstructionInputSchema = z.strictObject({
input_path: z.string().min(1).max(16_384),
format: z.enum(["auto", "asar", "directory"]).default("auto"),
source_map_read_approved: z.boolean().default(false),
limits: reconstructionLimitsSchema.default({
max_entries: 8_000,
max_total_artifact_bytes: 512 * 1_024 * 1_024,
max_artifact_entry_bytes: 128 * 1_024 * 1_024,
max_compression_ratio: 1_000,
max_depth: 64,
max_path_bytes: 4_096,
max_text_files: 5_000,
max_total_text_bytes: 128 * 1_024 * 1_024,
max_text_file_bytes: 8 * 1_024 * 1_024,
max_ast_nodes: 2_000_000,
max_findings: 10_000,
max_modules: 20_000,
max_source_map_sources: 5_000,
max_parse_milliseconds: 30_000,
}),
});
/** Parsed bounded reconstruction request. */
export type JavaScriptArtifactReconstructionInput = z.infer<
typeof javascriptArtifactReconstructionInputSchema
>;
/** Project reconstruction limits into the shared artifact traversal policy. */
export const artifactLimitsForReconstruction = (
input: JavaScriptArtifactReconstructionInput,
): ArtifactLimits => ({
maxEntries: input.limits.max_entries,
maxTotalBytes: input.limits.max_total_artifact_bytes,
maxEntryBytes: input.limits.max_artifact_entry_bytes,
maxCompressionRatio: input.limits.max_compression_ratio,
maxDepth: input.limits.max_depth,
maxPathBytes: input.limits.max_path_bytes,
});