refactor(javascript): group domain semantics and contracts (#907)

This commit is contained in:
ysopwnable
2026-10-07 17:16:58 +08:00
committed by GitHub
parent d5f28fb29c
commit f6a58f1062
253 changed files with 432 additions and 410 deletions
@@ -0,0 +1,56 @@
import { electronActiveObservationResultSchema } from "./electronActiveObservation.js";
/** Create an active-capture result for MCP contract tests. */
export const createElectronActiveObservationFixtureResult = (
applicationPath: string,
) =>
electronActiveObservationResultSchema.parse({
application: {
executable_path: process.execPath,
application_path: applicationPath,
electron_version: "test-electron",
process_ownership: "provider-owned",
cleanup: "terminated-owned-process",
},
actions: [
{
step_id: "submit",
kind: "click",
window_index: 0,
target: "window:1",
status: "completed",
elapsed_ms: 3,
error: null,
},
],
windows: [
{
window_id: "window:1",
web_contents_id: "webContents:1",
url: "file:///tmp/app.html",
title: "Fixture",
visible: true,
destroyed: false,
},
],
processes: {
items: [{ pid: 1234, type: "Browser", name: null, service_name: null }],
},
ipc: {
events: [
{
sequence: 1,
kind: "main-handler-invocation",
channel: "readiness:echo",
argument_shapes: ["string"],
result_shape: "object",
process_type: "main",
error: false,
},
],
observed: 1,
},
limitations: [
"IPC payloads are represented by value shapes; payload values are never retained.",
],
});
@@ -0,0 +1,270 @@
import { z } from "zod";
const pathInputSchema = z.string().trim().min(1);
const absolutePathSchema = z
.string()
.min(1)
.refine(
(value) =>
value.startsWith("/") ||
/^[A-Za-z]:[\\/]/u.test(value) ||
value.startsWith("\\\\"),
"provider path must be absolute",
);
const windowIndexSchema = z.number().int().min(0);
const deepLinkUrlSchema = z
.string()
.min(1)
.refine((value) => {
try {
return new URL(value).protocol.length > 0;
} catch (cause: unknown) {
// Invalid input fails the refinement.
void cause;
return false;
}
}, "deep-link url must be an absolute URL");
const actionSchema = z.discriminatedUnion("kind", [
z.strictObject({
step_id: z.string().min(1),
kind: z.literal("click"),
selector: z.string().min(1),
window_index: windowIndexSchema.default(0),
}),
z.strictObject({
step_id: z.string().min(1),
kind: z.literal("wait"),
duration_ms: z.number().int().min(0),
window_index: windowIndexSchema.optional(),
}),
z.strictObject({
step_id: z.string().min(1),
kind: z.literal("renderer-reload"),
window_index: windowIndexSchema.default(0),
}),
z.strictObject({
step_id: z.string().min(1),
kind: z.literal("renderer-crash"),
window_index: windowIndexSchema.default(0),
}),
z.strictObject({
step_id: z.string().min(1),
kind: z.literal("deep-link"),
delivery: z.enum(["open-url", "second-instance"]),
url: deepLinkUrlSchema,
}),
]);
/** Input for one explicit, provider-owned Electron runtime experiment. */
export const electronActiveObservationInputSchema = z.strictObject({
executable_path: pathInputSchema,
application_path: pathInputSchema,
application_root: pathInputSchema.optional(),
args: z.array(z.string()).default([]),
actions: z.array(actionSchema).default([]),
});
export type ElectronActiveObservationInput = z.infer<
typeof electronActiveObservationInputSchema
>;
const ipcEventSchema = z.strictObject({
sequence: z.number().int().min(1),
correlation_id: z.string().nullable().default(null),
kind: z.enum([
"main-handler-invocation",
"main-event-invocation",
"utility-process-fork",
"utility-process-message",
"ipc-main-to-renderer",
"ipc-utility-to-main",
"ipc-renderer-send",
"ipc-renderer-invoke",
"ipc-renderer-post-message",
]),
event: z.string().nullable().optional(),
phase: z
.enum(["attempted", "completed", "blocked", "failed", "observed"])
.nullable()
.optional(),
channel: z.string().nullable(),
direction: z
.enum([
"renderer-to-main",
"main-to-renderer",
"main-to-utility",
"utility-to-main",
])
.nullable()
.optional(),
sender: z.string().nullable().optional(),
receiver: z.string().nullable().optional(),
frame: z.string().nullable().default(null),
target: z.string().nullable().optional(),
argument_shapes: z.array(z.string()),
result_shape: z.string().nullable(),
process_type: z.string().nullable(),
source: z.string().default("electron-active-hook"),
capture_method: z
.enum(["api-wrapper", "event-emitter", "process-hook"])
.default("api-wrapper"),
artifact_path: z.string().nullable().default(null),
artifact_sha256: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.nullable()
.default(null),
error: z.boolean(),
});
const timelineEventSchema = z.strictObject({
sequence: z.number().int().min(1),
correlation_id: z.string().nullable().default(null),
kind: z.enum([
"main-handler-invocation",
"main-event-invocation",
"utility-process-fork",
"utility-process-message",
"ipc-main-to-renderer",
"ipc-utility-to-main",
"ipc-renderer-send",
"ipc-renderer-invoke",
"ipc-renderer-post-message",
"app-lifecycle",
"window-lifecycle",
"web-contents-lifecycle",
"navigation",
"shell-attempt",
"process-lifecycle",
"permission",
"popup-attempt",
"download",
"protocol",
"preload",
"native-addon",
"updater",
"error",
]),
event: z.string().nullable(),
phase: z.enum(["attempted", "completed", "blocked", "failed", "observed"]),
channel: z.string().nullable(),
direction: z
.enum([
"renderer-to-main",
"main-to-renderer",
"main-to-utility",
"utility-to-main",
])
.nullable(),
sender: z.string().nullable(),
receiver: z.string().nullable(),
frame: z.string().nullable(),
target: z.string().nullable(),
argument_shapes: z.array(z.string()),
result_shape: z.string().nullable(),
process_type: z.string().nullable(),
source: z.string(),
capture_method: z.enum(["api-wrapper", "event-emitter", "process-hook"]),
artifact_path: z.string().nullable(),
artifact_sha256: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.nullable(),
error: z.boolean(),
});
const processMetricSchema = z.strictObject({
pid: z.number().int().min(1),
type: z.string().min(1),
name: z.string().nullable(),
service_name: z.string().nullable(),
});
const windowResultSchema = z.strictObject({
window_id: z.string(),
web_contents_id: z.string(),
url: z.string(),
title: z.string(),
visible: z.boolean().nullable(),
destroyed: z.boolean(),
});
const coverageSchema = z.strictObject({
status: z.enum([
"complete",
"partial_attach",
"hook_conflict",
"target_exited",
"cleanup_failed",
]),
observed_event_families: z.array(z.string()),
unavailable_event_families: z.array(z.string()),
observed_roles: z.array(z.string()),
pre_capture_activity: z.literal("unavailable"),
});
const actionResultContextShape = {
step_id: z.string().min(1),
kind: z.enum([
"click",
"wait",
"renderer-reload",
"renderer-crash",
"deep-link",
]),
window_index: windowIndexSchema.nullable(),
target: z.string().nullable(),
elapsed_ms: z.number().int().min(0),
};
const actionResultSchema = z.discriminatedUnion("status", [
z.strictObject({
...actionResultContextShape,
status: z.literal("completed"),
error: z.null(),
}),
z.strictObject({
...actionResultContextShape,
status: z.enum(["failed", "cancelled"]),
error: z.string(),
}),
]);
/** Result of a provider-owned Electron runtime experiment. */
export const electronActiveObservationResultSchema = z.strictObject({
application: z.strictObject({
executable_path: absolutePathSchema,
application_path: absolutePathSchema,
electron_version: z.string().min(1),
process_ownership: z.literal("provider-owned"),
cleanup: z.literal("terminated-owned-process"),
}),
actions: z.array(actionResultSchema),
windows: z.array(windowResultSchema),
processes: z.strictObject({
items: z.array(processMetricSchema),
}),
ipc: z.strictObject({
events: z.array(ipcEventSchema),
observed: z.number().int().min(0),
}),
timeline: z
.strictObject({
events: z.array(timelineEventSchema),
observed: z.number().int().min(0),
})
.default({ events: [], observed: 0 }),
coverage: coverageSchema.default({
status: "partial_attach",
observed_event_families: [],
unavailable_event_families: [],
observed_roles: [],
pre_capture_activity: "unavailable",
}),
limitations: z.array(z.string()),
});
export type ElectronActiveObservationResult = z.infer<
typeof electronActiveObservationResultSchema
>;
@@ -0,0 +1,51 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptStaticSource } from "./javascriptStaticAnalysis.js";
describe("native addon loader provenance", () => {
it("distinguishes CommonJS and ESM re-exports", () => {
const analysis = analyzeJavaScriptStaticSource(`
const required = require("./addon.node#literal.node");
module.exports = require("./addon.node#literal.node");
import imported from "./addon.node#literal.node";
export { default } from "./addon.node#literal.node";
`);
expect(analysis.electron.native_addon_bindings).toHaveLength(4);
expect(analysis.electron.native_addon_bindings).toEqual(
expect.arrayContaining([
expect.objectContaining({
binding_kind: "require",
module_kind: "require",
}),
expect.objectContaining({
binding_kind: "import",
module_kind: "import",
}),
expect.objectContaining({
binding_kind: "re-export",
module_kind: "require",
}),
expect.objectContaining({
binding_kind: "re-export",
module_kind: "import",
}),
]),
);
});
it.each(["#", "?"])(
"classifies require filenames literally for %s",
(punctuation) => {
const analysis = analyzeJavaScriptStaticSource(`
const script = require("./addon.node${punctuation}helper.js");
import native from "./addon.node${punctuation}helper.js";
`);
expect(analysis.electron.native_addon_bindings).toEqual([
expect.objectContaining({
binding_kind: "import",
module_kind: "import",
}),
]);
},
);
});
@@ -0,0 +1,136 @@
import { z } from "zod";
import { browserCompletenessSchema } from "../browserCompleteness.js";
import { browserEndpointSchema } from "../browserObservation.js";
import { browserVersionSchema } from "../browserObservationSchemas.js";
import { webTextArtifactSchema } from "../webContentArtifact.js";
import { prefixedDigestSchema } from "../digests.js";
const approvedElectronInput = {
cdp_endpoint: browserEndpointSchema,
};
/** Input for listing local file:// page targets from an explicit Electron CDP endpoint. */
export const listElectronTargetsInputSchema = z.strictObject({
...approvedElectronInput,
});
export type ListElectronTargetsInput = z.infer<
typeof listElectronTargetsInputSchema
>;
/** Input for passive structural inspection of one Electron file page. */
const inspectElectronPageFacts = {
...approvedElectronInput,
target_id: z.string().trim().min(1),
observation_ms: z.number().int().min(0).default(100),
} as const;
export const inspectElectronPageInputSchema = z.union([
z.strictObject({
...inspectElectronPageFacts,
include_script_sources: z.literal(false).default(false),
}),
z.strictObject({
...inspectElectronPageFacts,
include_script_sources: z.literal(true),
}),
]);
export type InspectElectronPageInput = z.infer<
typeof inspectElectronPageInputSchema
>;
const electronTargetSchema = z.object({
target_id: z.string(),
type: z.string(),
title: z.string(),
file_path: z.string(),
attached: z.boolean(),
});
/** Complete local file target inventory from one Electron CDP endpoint. */
export const electronTargetListSchema = z.object({
browser: browserVersionSchema,
targets: z.array(electronTargetSchema),
excluded: z.object({
unsupported_url: z.number().int().min(0),
non_page: z.number().int().min(0),
}),
limitations: z.array(z.string()),
});
export type ElectronTargetList = z.infer<typeof electronTargetListSchema>;
const electronSourceSchema = z.discriminatedUnion("included", [
z.object({ included: z.literal(false), reason: z.string() }),
z.object({ included: z.literal(true), artifact: webTextArtifactSchema }),
]);
/** Provider-neutral passive Electron file-page structure and script inventory. */
export const electronPageInspectionSchema = z.object({
browser: browserVersionSchema,
target: electronTargetSchema,
capture_window: z.object({
started_at: z.iso.datetime(),
ended_at: z.iso.datetime(),
observation_ms: z.number().int().min(0),
}),
completeness: browserCompletenessSchema,
frames: z.array(
z.object({
frame_id: z.string(),
parent_frame_id: z.string().nullable(),
file_path: z.string(),
}),
),
dom: z.object({
total_nodes: z.number().int().min(0),
nodes: z.array(
z.object({
index: z.number().int().min(0),
parent_index: z.number().int().min(-1),
node_type: z.number().int().min(0),
node_name: z.string(),
node_value_length: z.number().int().min(0),
attribute_names: z.array(z.string()),
}),
),
}),
scripts: z.object({
total: z.number().int().min(0),
items: z.array(
z.object({
script_key: prefixedDigestSchema("electron_script"),
frame_id: z.string().nullable().default(null),
file_path: z.string(),
cdp_hash: z.string(),
length: z.number().int().min(0),
is_module: z.boolean(),
language: z.string().nullable(),
source: electronSourceSchema,
}),
),
}),
resources: z.array(
z.object({
resource_key: prefixedDigestSchema("electron_resource"),
file_path: z.string(),
type: z.string(),
mime_type: z.string(),
content_size: z.number().min(0).nullable(),
}),
),
workers: z
.array(
z.object({
target_id: z.string().min(1),
type: z.string().min(1),
file_path: z.string(),
attached: z.boolean(),
opener_target_id: z.string().min(1).nullable(),
parent_frame_id: z.string().min(1).nullable(),
}),
)
.default([]),
limitations: z.array(z.string()),
});
export type ElectronPageInspection = z.infer<
typeof electronPageInspectionSchema
>;
@@ -0,0 +1,16 @@
import type * as t from "@babel/types";
import { inspectElectronBrowserNode } from "./electronStaticAnalysisBrowser.js";
import { inspectElectronIpcNode } from "./electronStaticAnalysisIpc.js";
import { inspectElectronNativeNode } from "./electronStaticAnalysisNative.js";
import type { JavaScriptFindingContext } from "./javascriptStaticAnalysisState.js";
/** Collect Electron-specific syntax during the shared inert AST traversal. */
export const inspectElectronStaticNode = (
node: t.Node,
context: JavaScriptFindingContext,
): void => {
inspectElectronBrowserNode(node, context);
inspectElectronIpcNode(node, context);
inspectElectronNativeNode(node, context);
};
@@ -0,0 +1,248 @@
import * as t from "@babel/types";
import type {
ElectronBrowserWindowFinding,
ElectronBrowserWindowPreload,
ElectronContextBridgeApiKey,
ElectronContextBridgeFinding,
ElectronStaticValue,
ElectronUtilityProcessFinding,
ElectronWebPreference,
} from "./electronStaticAnalysisTypes.js";
import {
boundedExpression,
collectContextBridgeMembers,
electronStaticValue,
objectProperty,
} from "./electronStaticAnalysisValues.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
import {
argumentNode,
calleeName,
range,
staticPath,
staticPathResolutionContext,
} from "./javascriptStaticAnalysisHelpers.js";
import { semanticStaticPropertyName } from "./javascriptAstValues.js";
import type { JavaScriptFindingContext } from "./javascriptStaticAnalysisState.js";
/** Inspect BrowserWindow, contextBridge, and utility-process syntax. */
export const inspectElectronBrowserNode = (
node: t.Node,
context: JavaScriptFindingContext,
): void => {
if (t.isNewExpression(node)) inspectBrowserWindow(node, context);
if (!t.isCallExpression(node)) return;
inspectContextBridge(node, context);
inspectUtilityProcess(node, context);
};
const inspectBrowserWindow = (
node: t.NewExpression,
context: JavaScriptFindingContext,
): void => {
const name = calleeName(node.callee);
if (name !== "BrowserWindow" && !name.endsWith(".BrowserWindow")) return;
const options = argumentNode(node.arguments[0]);
const collected = collectWindowOptions(context.source, options);
context.accumulator.unknownFindings += collected.unknown;
const finding: ElectronBrowserWindowFinding = {
options_status:
options === undefined
? "missing"
: t.isObjectExpression(options)
? "object-literal"
: "dynamic",
web_preferences_status: collected.status,
web_preferences: collected.preferences,
...collected.preload,
module_key: null,
location: range(node),
};
addLocatedFinding(context, {
collection: context.accumulator.browserWindows,
key: `electron-window\0${name}`,
node,
value: finding,
});
};
const collectWindowOptions = (
source: string,
options: t.Node | undefined,
): {
readonly status: ElectronBrowserWindowFinding["web_preferences_status"];
readonly preferences: readonly ElectronWebPreference[];
readonly preload: ElectronBrowserWindowPreload;
readonly unknown: number;
} => {
const lookup = objectProperty(options, "webPreferences");
if (
lookup.status !== "explicit" ||
!t.isObjectExpression(lookup.property.value)
)
return {
status: lookup.status === "missing" ? "missing" : "dynamic",
preferences: [],
preload: { preload_path: null, preload_resolution_context: null },
unknown: lookup.status === "missing" ? 0 : 1,
};
return collectWebPreferences(source, lookup.property.value);
};
const collectWebPreferences = (
source: string,
object: t.ObjectExpression,
): {
readonly status: "object-literal";
readonly preferences: readonly ElectronWebPreference[];
readonly preload: ElectronBrowserWindowPreload;
readonly unknown: number;
} => {
const preferences: ElectronWebPreference[] = [];
let unknown = 0;
let preload: ElectronBrowserWindowPreload = {
preload_path: null,
preload_resolution_context: null,
};
for (const property of object.properties) {
if (t.isSpreadElement(property)) {
unknown += 1;
preferences.push({
name: `[spread@${String(property.start ?? -1)}]`,
value: electronStaticValue(source, property.argument),
});
continue;
}
const name = semanticStaticPropertyName(property.key, property.computed);
if (name === "" || property.computed) {
unknown += 1;
preferences.push({
name: `[dynamic@${String(property.start ?? -1)}]`,
value: electronStaticValue(source, property),
});
continue;
}
if (t.isObjectMethod(property)) {
unknown += 1;
preferences.push({
name,
value: electronStaticValue(source, property),
});
continue;
}
const path = name === "preload" ? staticPath(property.value) : undefined;
if (path !== undefined)
preload = {
preload_path: path,
preload_resolution_context: staticPathResolutionContext(property.value),
};
const value: ElectronStaticValue =
path === undefined
? electronStaticValue(source, property.value)
: { status: "literal", value: path, expression: null };
if (value.status === "dynamic") unknown += 1;
preferences.push({ name, value });
}
preferences.sort((left, right) => compareCodePoints(left.name, right.name));
return {
status: "object-literal",
preferences,
preload,
unknown,
};
};
const inspectContextBridge = (
node: t.CallExpression,
context: JavaScriptFindingContext,
): void => {
const name = calleeName(node.callee);
const main =
name === "contextBridge.exposeInMainWorld" ||
name.endsWith(".contextBridge.exposeInMainWorld");
const isolated =
name === "contextBridge.exposeInIsolatedWorld" ||
name.endsWith(".contextBridge.exposeInIsolatedWorld");
if (!main && !isolated) return;
const keyNode = argumentNode(node.arguments[isolated ? 1 : 0]);
const apiNode = argumentNode(node.arguments[isolated ? 2 : 1]);
const key = electronStaticValue(context.source, keyNode);
const api = collectContextBridgeMembers(apiNode);
const worldId = isolated
? electronStaticValue(context.source, argumentNode(node.arguments[0]))
: null;
const unknown =
(key.status === "dynamic" ? 1 : 0) +
(worldId?.status === "dynamic" ? 1 : 0) +
api.unknown;
context.accumulator.unknownFindings += unknown;
const apiKey: ElectronContextBridgeApiKey =
key.status === "dynamic"
? { api_key: null, api_key_expression: key.expression }
: typeof key.value === "string"
? { api_key: key.value, api_key_expression: null }
: { api_key: null, api_key_expression: null };
const finding: ElectronContextBridgeFinding = {
...apiKey,
world: isolated ? "isolated" : "main",
world_id: worldId,
api_status: api.status,
members: api.members,
unknown_members: api.unknown,
module_key: null,
location: range(node),
};
addLocatedFinding(context, {
collection: context.accumulator.contextBridgeApis,
key: `context-bridge\0${isolated ? "isolated" : "main"}\0${finding.api_key ?? finding.api_key_expression ?? "[missing]"}`,
node,
value: finding,
});
};
const inspectUtilityProcess = (
node: t.CallExpression,
context: JavaScriptFindingContext,
): void => {
const name = calleeName(node.callee);
if (name !== "utilityProcess.fork" && !name.endsWith(".utilityProcess.fork"))
return;
const moduleNode = argumentNode(node.arguments[0]);
const modulePath =
moduleNode === undefined ? undefined : staticPath(moduleNode);
const options = argumentNode(node.arguments[2]);
const serviceNameProperty = objectProperty(options, "serviceName");
const serviceName =
serviceNameProperty.status === "explicit"
? staticPath(serviceNameProperty.property.value)
: undefined;
if (serviceNameProperty.status !== "missing" && serviceName === undefined)
context.accumulator.unknownFindings += 1;
if (modulePath === undefined) context.accumulator.unknownFindings += 1;
const moduleReference =
modulePath === undefined || moduleNode === undefined
? {
module_path: null,
module_resolution_context: null,
module_expression: boundedExpression(context.source, moduleNode),
}
: {
module_path: modulePath,
module_resolution_context: staticPathResolutionContext(moduleNode),
module_expression: null,
};
const finding: ElectronUtilityProcessFinding = {
...moduleReference,
service_name: serviceName ?? null,
module_key: null,
location: range(node),
};
addLocatedFinding(context, {
collection: context.accumulator.utilityProcesses,
key: `electron-utility\0${finding.module_path ?? finding.module_expression}`,
node,
value: finding,
});
};
@@ -0,0 +1,240 @@
import * as t from "@babel/types";
import type {
ElectronIpcDescriptor,
ElectronIpcFinding,
ElectronSenderValidationFinding,
} from "./electronStaticAnalysisTypes.js";
import {
boundedExpression,
electronStaticValue,
handlerKind,
} from "./electronStaticAnalysisValues.js";
import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
import {
argumentNode,
calleeName,
range,
semanticStaticPropertyName,
} from "./javascriptStaticAnalysisHelpers.js";
import type { JavaScriptFindingContext } from "./javascriptStaticAnalysisState.js";
/** Inspect Electron IPC operations and validation candidates. */
export const inspectElectronIpcNode = (
node: t.Node,
context: JavaScriptFindingContext,
): void => {
if (t.isCallExpression(node)) {
inspectIpcCall(node, context);
inspectValidationCall(node, context);
}
if (t.isBinaryExpression(node)) inspectValidationComparison(node, context);
};
const inspectIpcCall = (
node: t.CallExpression,
context: JavaScriptFindingContext,
): void => {
const name = calleeName(node.callee);
const descriptor = ipcDescriptor(name);
if (descriptor === undefined) return;
const channelNode = argumentNode(node.arguments[0]);
const channelValue = electronStaticValue(context.source, channelNode);
const channel =
channelValue.status === "literal" && typeof channelValue.value === "string"
? channelValue.value
: null;
const channelReference =
channel === null
? {
channel: null,
channel_expression:
channelValue.status === "dynamic"
? channelValue.expression
: boundedExpression(context.source, channelNode),
}
: { channel, channel_expression: null };
const handlerNode =
descriptor.mode === "listen" || descriptor.mode === "handle"
? argumentNode(node.arguments[1])
: undefined;
const findingState =
descriptor.mode === "send"
? {
...descriptor,
handler_kind: null,
handler_location: null,
}
: descriptor.mode === "invoke"
? {
...descriptor,
handler_kind: null,
handler_location: null,
}
: handlerNode === undefined
? {
...descriptor,
handler_kind: "missing" as const,
handler_location: null,
}
: {
...descriptor,
handler_kind: handlerKind(handlerNode),
handler_location: range(handlerNode),
};
if (channel === null) context.accumulator.unknownFindings += 1;
if (findingState.handler_kind === "missing")
context.accumulator.unknownFindings += 1;
const finding: ElectronIpcFinding = {
...findingState,
...channelReference,
module_key: null,
location: range(node),
};
addLocatedFinding(context, {
collection: context.accumulator.ipc,
key: `electron-ipc\0${descriptor.side}\0${descriptor.operation}\0${channelReference.channel ?? channelReference.channel_expression}`,
node,
value: finding,
});
};
const inspectValidationComparison = (
node: t.BinaryExpression,
context: JavaScriptFindingContext,
): void => {
if (!["==", "===", "!=", "!==", "in"].includes(node.operator)) return;
const left = senderSubject(node.left);
const right = senderSubject(node.right);
if (left === undefined && right === undefined) return;
const expected = left === undefined ? node.left : node.right;
addValidation(context, node, {
subject: left ?? right ?? "sender-frame",
mechanism: `comparison:${node.operator}`,
expected: electronStaticValue(context.source, expected),
});
};
const inspectValidationCall = (
node: t.CallExpression,
context: JavaScriptFindingContext,
): void => {
if (
!t.isMemberExpression(node.callee) &&
!t.isOptionalMemberExpression(node.callee)
)
return;
const method = semanticStaticPropertyName(
node.callee.property,
node.callee.computed,
);
if (!["startsWith", "endsWith", "includes"].includes(method)) return;
const subject = t.isNode(node.callee.object)
? senderSubject(node.callee.object)
: undefined;
if (subject === undefined) return;
addValidation(context, node, {
subject,
mechanism: `call:${method}`,
expected: electronStaticValue(
context.source,
argumentNode(node.arguments[0]),
),
});
};
const addValidation = (
context: JavaScriptFindingContext,
node: t.Node,
input: Pick<
ElectronSenderValidationFinding,
"subject" | "mechanism" | "expected"
>,
): void => {
if (input.expected.status === "dynamic")
context.accumulator.unknownFindings += 1;
const finding: ElectronSenderValidationFinding = {
...input,
enforcement: "unknown",
module_key: null,
location: range(node),
};
addLocatedFinding(context, {
collection: context.accumulator.senderValidations,
key: `electron-validation\0${input.subject}\0${input.mechanism}\0${input.expected.status === "literal" ? String(input.expected.value) : input.expected.expression}`,
node,
value: finding,
});
};
const ipcDescriptor = (name: string): ElectronIpcDescriptor | undefined => {
const renderer = suffixOperation(name, "ipcRenderer");
if (renderer !== undefined) {
switch (renderer) {
case "send":
return { side: "renderer", operation: "send", mode: "send" };
case "sendSync":
return { side: "renderer", operation: "send-sync", mode: "send" };
case "invoke":
return { side: "renderer", operation: "invoke", mode: "invoke" };
case "postMessage":
return {
side: "renderer",
operation: "post-message",
mode: "send",
};
case "sendToHost":
return {
side: "renderer",
operation: "send-to-host",
mode: "send",
};
case "on":
return { side: "renderer", operation: "on", mode: "listen" };
case "once":
return { side: "renderer", operation: "once", mode: "listen" };
}
}
const main = suffixOperation(name, "ipcMain");
switch (main) {
case "on":
return { side: "main", operation: "on", mode: "listen" };
case "once":
return { side: "main", operation: "once", mode: "listen" };
case "handle":
return { side: "main", operation: "handle", mode: "handle" };
case "handleOnce":
return { side: "main", operation: "handle-once", mode: "handle" };
default:
return undefined;
}
};
const suffixOperation = (
name: string,
object: "ipcRenderer" | "ipcMain",
): string | undefined => {
const marker = `${object}.`;
const index = name.lastIndexOf(marker);
if (index < 0) return undefined;
const prefix = name.slice(0, index);
if (prefix !== "" && !prefix.endsWith(".")) return undefined;
const operation = name.slice(index + marker.length);
return operation.includes(".") ? undefined : operation;
};
const senderSubject = (
node: t.Node,
): ElectronSenderValidationFinding["subject"] | undefined => {
const name = t.isCallExpression(node)
? calleeName(node.callee)
: calleeName(node);
if (/(?:^|\.)sender\.getURL$/u.test(name)) return "sender-url";
if (/(?:^|\.)senderFrame\.origin$/u.test(name)) return "sender-origin";
if (/(?:^|\.)senderFrame\.url$/u.test(name)) return "sender-url";
if (/(?:^|\.)senderFrame$/u.test(name)) return "sender-frame";
if (/(?:^|\.)sender\.id$/u.test(name)) return "sender-id";
if (/(?:^|\.)frameId$/u.test(name)) return "frame-id";
if (/(?:^|\.)processId$/u.test(name)) return "process-id";
return undefined;
};
@@ -0,0 +1,215 @@
import * as t from "@babel/types";
import { compareCodePoints } from "../canonicalOrdering.js";
import { stripQueryAndFragment } from "../artifactPathSyntax.js";
import type { ElectronNativeAddonBindingFinding } from "./electronStaticAnalysisTypes.js";
import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
import {
argumentNode,
calleeName,
propertyName,
range,
semanticStaticPropertyName,
stringValue,
} from "./javascriptStaticAnalysisHelpers.js";
import type { JavaScriptFindingContext } from "./javascriptStaticAnalysisState.js";
interface NativeBindingInput {
readonly context: JavaScriptFindingContext;
readonly node: t.Node;
readonly specifier: string;
readonly kind: ElectronNativeAddonBindingFinding["binding_kind"];
readonly moduleKind: ElectronNativeAddonBindingFinding["module_kind"];
readonly members: readonly string[];
}
/** Inspect JavaScript-side imports and re-exports of native .node addons. */
export const inspectElectronNativeNode = (
node: t.Node,
context: JavaScriptFindingContext,
): void => {
if (t.isImportDeclaration(node)) inspectImport(node, context);
else if (t.isExportNamedDeclaration(node)) inspectNamedExport(node, context);
else if (t.isExportAllDeclaration(node)) inspectExportAll(node, context);
else if (t.isVariableDeclarator(node)) inspectRequireBinding(node, context);
else if (t.isAssignmentExpression(node)) inspectReExport(node, context);
};
const inspectImport = (
node: t.ImportDeclaration,
context: JavaScriptFindingContext,
): void => {
if (!isNativeSpecifier(node.source.value, "import")) return;
const members = node.specifiers.map((specifier) => {
if (t.isImportDefaultSpecifier(specifier)) return "default";
if (t.isImportNamespaceSpecifier(specifier)) return "*";
return propertyName(specifier.imported) || "[dynamic-import]";
});
addBinding({
context,
node,
specifier: node.source.value,
kind: "import",
moduleKind: "import",
members,
});
};
const inspectNamedExport = (
node: t.ExportNamedDeclaration,
context: JavaScriptFindingContext,
): void => {
if (
node.source === null ||
node.source === undefined ||
!isNativeSpecifier(node.source.value, "import")
)
return;
const members = node.specifiers.map((specifier) => {
if (t.isExportSpecifier(specifier)) return propertyName(specifier.local);
return "*";
});
addBinding({
context,
node,
specifier: node.source.value,
kind: "re-export",
moduleKind: "import",
members,
});
};
const inspectExportAll = (
node: t.ExportAllDeclaration,
context: JavaScriptFindingContext,
): void => {
if (
node.source === undefined ||
!isNativeSpecifier(node.source.value, "import")
)
return;
addBinding({
context,
node,
specifier: node.source.value,
kind: "re-export",
moduleKind: "import",
members: ["*"],
});
};
const inspectRequireBinding = (
node: t.VariableDeclarator,
context: JavaScriptFindingContext,
): void => {
const required = nativeRequire(node.init);
if (required === undefined) return;
addBinding({
context,
node,
specifier: required.specifier,
kind: "require",
moduleKind: "require",
members:
required.member === null ? bindingMembers(node.id) : [required.member],
});
};
const inspectReExport = (
node: t.AssignmentExpression,
context: JavaScriptFindingContext,
): void => {
const required = nativeRequire(node.right);
if (required === undefined || !isModuleExport(node.left)) return;
addBinding({
context,
node,
specifier: required.specifier,
kind: "re-export",
moduleKind: "require",
members: [required.member ?? exportedMember(node.left) ?? "*"],
});
};
const addBinding = (input: NativeBindingInput): void => {
const { context, node, specifier, kind } = input;
const unique = [
...new Set(input.members.filter((member) => member !== "")),
].sort(compareCodePoints);
const members = unique.length === 0 ? ["*"] : unique;
addLocatedFinding(context, {
collection: context.accumulator.nativeAddonBindings,
key: `native-addon-binding\0${kind}\0${specifier}\0${members.join("\0")}`,
node,
value: {
specifier,
binding_kind: kind,
module_kind: input.moduleKind,
members,
module_key: null,
location: range(node),
},
});
};
const nativeRequire = (
node: t.Node | null | undefined,
):
| { readonly specifier: string; readonly member: string | null }
| undefined => {
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
const nested = t.isNode(node.object)
? nativeRequire(node.object)
: undefined;
if (nested === undefined) return undefined;
const member = semanticStaticPropertyName(node.property, node.computed);
return { ...nested, member: member === "" ? nested.member : member };
}
if (!t.isCallExpression(node)) return undefined;
const name = calleeName(node.callee);
if (
name !== "require" &&
!name.endsWith(".require") &&
!name.includes("__webpack_require__")
)
return undefined;
const specifier = stringValue(argumentNode(node.arguments[0]));
return specifier !== undefined && isNativeSpecifier(specifier, "require")
? { specifier, member: null }
: undefined;
};
const bindingMembers = (pattern: t.Node): string[] => {
if (t.isIdentifier(pattern)) return ["*"];
if (!t.isObjectPattern(pattern)) return ["*"];
return pattern.properties.map((property) => {
if (t.isRestElement(property)) return "*";
return propertyName(property.key) || "[dynamic-import]";
});
};
const isModuleExport = (node: t.Node): boolean => {
const name = calleeName(node);
return (
name === "module.exports" ||
name.startsWith("module.exports.") ||
name.startsWith("exports.")
);
};
const exportedMember = (node: t.Node): string | undefined => {
const name = calleeName(node);
if (name.startsWith("module.exports."))
return name.slice("module.exports.".length);
if (name.startsWith("exports.")) return name.slice("exports.".length);
return undefined;
};
const isNativeSpecifier = (
specifier: string,
moduleKind: ElectronNativeAddonBindingFinding["module_kind"],
): boolean => {
const path =
moduleKind === "require" ? specifier : stripQueryAndFragment(specifier);
return path.toLowerCase().endsWith(".node");
};
@@ -0,0 +1,157 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptStaticSource } from "./javascriptStaticAnalysis.js";
describe.each(["webPreferences", "serviceName"] as const)(
"Electron %s option lookup",
(name) => {
const value =
name === "webPreferences"
? '{ preload: "./kept.js", sandbox: true }'
: '"kept"';
const explicit = `${name}: ${value}`;
const method = `${name}() { return ${value}; }`;
const getter = `get ${name}() { return ${value}; }`;
const setter = `set ${name}(value) {}`;
const explicitCases = [
["plain key", explicit],
["quoted key", `"${name}": ${value}`],
["computed string key", `["${name}"]: ${value}`],
["duplicate key", `${name}: null, ${explicit}`],
["computed duplicate key", `${name}: null, ["${name}"]: ${value}`],
["earlier spread", `...options, ${explicit}`],
["earlier computed identifier", `[key]: null, ${explicit}`],
["earlier computed expression", `[getKey()]: null, ${explicit}`],
["earlier getter", `${getter}, ${explicit}`],
["earlier method", `${method}, ${explicit}`],
["unrelated later key", `${explicit}, title: "title"`],
["unrelated computed literal", `${explicit}, ["title"]: null`],
["unrelated numeric key", `${explicit}, [1]: null`],
["unrelated empty key", `${explicit}, [""]: null`],
["unrelated getter", `${explicit}, get title() { return "title"; }`],
];
it.each(explicitCases)(
"retains the explicit value with %s",
(_, members) => {
const analysis = analyzeOption(name, `{ ${members} }`);
expect(analysis.parse_status).toBe("complete");
if (name === "webPreferences") {
expect(analysis.electron.browser_windows).toEqual([
expect.objectContaining({
options_status: "object-literal",
web_preferences_status: "object-literal",
preload_path: "./kept.js",
preload_resolution_context: "module-specifier",
web_preferences: [
{ name: "preload", value: literal("./kept.js") },
{ name: "sandbox", value: literal(true) },
],
}),
]);
} else {
expect(analysis.electron.utility_processes).toEqual([
expect.objectContaining({ service_name: "kept" }),
]);
}
},
);
const dynamicCases = [
["same-spelled computed binding", `[${name}]: ${value}`],
["different computed binding", `[key]: ${value}`],
["computed expression", `[getKey()]: ${value}`],
["unevaluated template key", `[\`${name}\`]: ${value}`],
["spread only", "...options"],
["later spread", `${explicit}, ...options`],
["later computed binding", `${explicit}, [key]: null`],
["later computed expression", `${explicit}, [getKey()]: null`],
["exact getter", getter],
["exact setter", setter],
["exact method", method],
["computed string method", `["${name}"]() { return ${value}; }`],
["overriding getter", `${explicit}, ${getter}`],
["overriding setter", `${explicit}, ${setter}`],
["overriding method", `${explicit}, ${method}`],
["dynamic explicit value", `${name}: dynamicValue`],
["null explicit value", `${name}: null`],
["duplicate null value", `${explicit}, ${name}: null`],
];
it.each(dynamicCases)("preserves uncertainty for %s", (_, members) => {
expectUnknownOption(name, `{ ${members} }`, "object-literal");
});
it.each(["null", "options"])(
"preserves nonliteral options %s",
(options) => {
expectUnknownOption(name, options, "dynamic");
},
);
it.each(["", "{}", '{ title: "title", ["other"]: null }'])(
"reports an omitted option in %s without inventing a default",
(options) => {
const analysis = analyzeOption(name, options);
expect(analysis.parse_status).toBe("complete");
if (name === "webPreferences")
expect(analysis.electron.browser_windows[0]).toMatchObject({
options_status: options === "" ? "missing" : "object-literal",
web_preferences_status: "missing",
web_preferences: [],
preload_path: null,
preload_resolution_context: null,
});
else
expect(
analysis.electron.utility_processes[0]?.service_name,
).toBeNull();
},
);
},
);
type OptionName = "webPreferences" | "serviceName";
const analyzeOption = (name: OptionName, options: string) =>
analyzeJavaScriptStaticSource(`
const webPreferences = "title";
const serviceName = "env";
${
name === "webPreferences"
? `new BrowserWindow(${options});`
: `utilityProcess.fork("./worker.js", []${options === "" ? "" : `, ${options}`});`
}
`);
const literal = (value: string | boolean) => ({
status: "literal",
value,
expression: null,
});
const expectUnknownOption = (
name: OptionName,
options: string,
optionsStatus: "object-literal" | "dynamic",
): void => {
const analysis = analyzeOption(name, options);
expect(analysis.parse_status).toBe("partial");
expect(analysis.parse_error_count).toBe(0);
expect(analysis.limitations.join(" ")).toContain("remain unknown");
if (name === "webPreferences")
expect(analysis.electron.browser_windows[0]).toMatchObject({
options_status: optionsStatus,
web_preferences_status: "dynamic",
web_preferences: [],
preload_path: null,
preload_resolution_context: null,
});
else
expect(analysis.electron.utility_processes[0]).toMatchObject({
module_path: "./worker.js",
module_expression: null,
service_name: null,
});
};
@@ -0,0 +1,179 @@
import type {
JavaScriptSourceRange,
JavaScriptStaticPathContext,
} from "./javascriptStaticAnalysisTypes.js";
/** One inert literal or unresolved expression observed in Electron syntax. */
export type ElectronStaticValue =
| {
readonly status: "literal";
readonly value: string | number | boolean | null;
readonly expression: null;
}
| {
readonly status: "dynamic";
readonly value: null;
readonly expression: string;
};
/** One explicitly present BrowserWindow webPreference. */
export interface ElectronWebPreference {
readonly name: string;
readonly value: ElectronStaticValue;
}
/** A statically resolved BrowserWindow preload declaration, or its absence. */
export type ElectronBrowserWindowPreload =
| {
readonly preload_path: string;
readonly preload_resolution_context: JavaScriptStaticPathContext;
}
| {
readonly preload_path: null;
readonly preload_resolution_context: null;
};
/** Statically visible BrowserWindow construction and preference surface. */
export type ElectronBrowserWindowFinding = ElectronBrowserWindowPreload & {
readonly options_status: "object-literal" | "dynamic" | "missing";
readonly web_preferences_status: "object-literal" | "dynamic" | "missing";
readonly web_preferences: readonly ElectronWebPreference[];
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
};
/** Literal, dynamic, or unsupported contextBridge API key syntax. */
export type ElectronContextBridgeApiKey =
| { readonly api_key: string; readonly api_key_expression: null }
| { readonly api_key: null; readonly api_key_expression: string }
| { readonly api_key: null; readonly api_key_expression: null };
/** One contextBridge API declaration without executing its API object. */
export type ElectronContextBridgeFinding = ElectronContextBridgeApiKey & {
readonly world: "main" | "isolated";
readonly world_id: ElectronStaticValue | null;
readonly api_status: "object-literal" | "dynamic" | "missing";
readonly members: readonly string[];
readonly unknown_members: number;
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
};
/** Electron IPC operation identity and its semantic communication mode. */
export type ElectronIpcDescriptor =
| {
readonly side: "renderer";
readonly operation:
| "send"
| "send-sync"
| "post-message"
| "send-to-host";
readonly mode: "send";
}
| {
readonly side: "renderer";
readonly operation: "invoke";
readonly mode: "invoke";
}
| {
readonly side: "renderer" | "main";
readonly operation: "on" | "once";
readonly mode: "listen";
}
| {
readonly side: "main";
readonly operation: "handle" | "handle-once";
readonly mode: "handle";
};
type ElectronIpcHandler =
| {
readonly mode: "send" | "invoke";
readonly handler_kind: null;
readonly handler_location: null;
}
| {
readonly mode: "listen" | "handle";
readonly handler_kind: "missing";
readonly handler_location: null;
}
| {
readonly mode: "listen" | "handle";
readonly handler_kind:
| "inline-function"
| "identifier"
| "member-expression"
| "dynamic-expression";
readonly handler_location: JavaScriptSourceRange;
};
interface ElectronIpcFindingContext {
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
}
/** One statically visible Electron IPC send, invocation, listener, or handler. */
export type ElectronIpcFinding = ElectronIpcDescriptor &
ElectronIpcHandler &
ElectronIpcFindingContext &
(
| { readonly channel: string; readonly channel_expression: null }
| { readonly channel: null; readonly channel_expression: string }
);
/** Static check involving an IPC sender, frame, process, URL, or origin. */
export interface ElectronSenderValidationFinding {
readonly subject:
| "sender-url"
| "sender-origin"
| "sender-frame"
| "sender-id"
| "frame-id"
| "process-id";
readonly mechanism: string;
readonly expected: ElectronStaticValue;
readonly enforcement: "unknown";
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
}
interface ElectronUtilityProcessFindingState {
readonly service_name: string | null;
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
}
/** One utilityProcess.fork declaration and its statically visible entrypoint. */
export type ElectronUtilityProcessFinding = ElectronUtilityProcessFindingState &
(
| {
readonly module_path: string;
readonly module_resolution_context: JavaScriptStaticPathContext;
readonly module_expression: null;
}
| {
readonly module_path: null;
readonly module_resolution_context: null;
readonly module_expression: string;
}
);
/** JavaScript-side binding or re-export requested from one native .node addon. */
export interface ElectronNativeAddonBindingFinding {
readonly specifier: string;
readonly binding_kind: "import" | "require" | "re-export";
readonly module_kind: "import" | "require";
readonly members: readonly string[];
readonly module_key: string | null;
readonly location: JavaScriptSourceRange;
}
/** All Electron-specific facts collected during one shared AST traversal. */
export interface ElectronStaticFindings {
readonly browser_windows: readonly ElectronBrowserWindowFinding[];
readonly context_bridge_apis: readonly ElectronContextBridgeFinding[];
readonly ipc: readonly ElectronIpcFinding[];
readonly sender_validations: readonly ElectronSenderValidationFinding[];
readonly utility_processes: readonly ElectronUtilityProcessFinding[];
readonly native_addon_bindings: readonly ElectronNativeAddonBindingFinding[];
}
@@ -0,0 +1,160 @@
import * as t from "@babel/types";
import { compareCodePoints } from "../canonicalOrdering.js";
import type { ElectronStaticValue } from "./electronStaticAnalysisTypes.js";
import { semanticStaticPropertyName } from "./javascriptAstValues.js";
import { sourceSlice } from "./javascriptStaticAnalysisHelpers.js";
/** Preserve one literal value or the exact inert expression. */
export const electronStaticValue = (
source: string,
node: t.Node | null | undefined,
): ElectronStaticValue => {
const literal = literalValue(node);
return literal.found
? { status: "literal", value: literal.value, expression: null }
: {
status: "dynamic",
value: null,
expression: boundedExpression(source, node),
};
};
/** Return an actionable expression without evaluating it. */
export const boundedExpression = (
source: string,
node: t.Node | null | undefined,
): string => {
if (node === null || node === undefined) return "[missing-expression]";
const expression = sourceSlice(source, node).trim();
return expression === "" ? `[${node.type}]` : expression;
};
/** Find the effective explicit property, preserving unresolved overrides. */
export const objectProperty = (
object: t.Node | undefined,
name: string,
):
| { readonly status: "missing" | "dynamic" }
| { readonly status: "explicit"; readonly property: t.ObjectProperty } => {
if (object === undefined) return { status: "missing" };
if (!t.isObjectExpression(object)) return { status: "dynamic" };
for (const property of object.properties.toReversed()) {
if (t.isSpreadElement(property)) return { status: "dynamic" };
const key = semanticStaticPropertyName(property.key, property.computed);
if (key === "" && !t.isStringLiteral(property.key))
return { status: "dynamic" };
if (key !== name) continue;
return t.isObjectProperty(property)
? { status: "explicit", property }
: { status: "dynamic" };
}
return { status: "missing" };
};
type PresentHandlerKind =
| "inline-function"
| "identifier"
| "member-expression"
| "dynamic-expression";
/** Classify a handler argument while retaining its exact source range. */
export function handlerKind(node: t.Node): PresentHandlerKind;
export function handlerKind(node: null | undefined): "missing";
export function handlerKind(
node: t.Node | null | undefined,
): PresentHandlerKind | "missing" {
if (node === null || node === undefined) return "missing";
if (
t.isArrowFunctionExpression(node) ||
t.isFunctionExpression(node) ||
t.isFunctionDeclaration(node)
)
return "inline-function";
if (t.isIdentifier(node)) return "identifier";
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
return "member-expression";
return "dynamic-expression";
}
/** Collect statically visible dotted keys from one literal contextBridge API object. */
export const collectContextBridgeMembers = (
node: t.Node | null | undefined,
): {
readonly status: "object-literal" | "dynamic" | "missing";
readonly members: readonly string[];
readonly unknown: number;
} => {
if (node === null || node === undefined)
return {
status: "missing",
members: [],
unknown: 0,
};
if (!t.isObjectExpression(node))
return {
status: "dynamic",
members: [],
unknown: 1,
};
const state: { members: string[]; unknown: number } = {
members: [],
unknown: 0,
};
collectMembersAt(node, "", 0, state);
const members = [...new Set(state.members)].sort(compareCodePoints);
return {
status: "object-literal",
members,
unknown: state.unknown,
};
};
const collectMembersAt = (
object: t.ObjectExpression,
prefix: string,
depth: number,
state: { members: string[]; unknown: number },
): void => {
if (depth >= 8) {
state.unknown += 1;
return;
}
for (const property of object.properties) {
if (t.isSpreadElement(property)) {
state.unknown += 1;
continue;
}
const name = semanticStaticPropertyName(property.key, property.computed);
if (name === "" || property.computed) {
state.unknown += 1;
continue;
}
const path = prefix === "" ? name : `${prefix}.${name}`;
state.members.push(path);
if (t.isObjectProperty(property) && t.isObjectExpression(property.value))
collectMembersAt(property.value, path, depth + 1, state);
}
};
const literalValue = (
node: t.Node | null | undefined,
):
| { readonly found: true; readonly value: string | number | boolean | null }
| { readonly found: false } => {
if (t.isStringLiteral(node) || t.isNumericLiteral(node))
return { found: true, value: node.value };
if (t.isBooleanLiteral(node)) return { found: true, value: node.value };
if (t.isNullLiteral(node)) return { found: true, value: null };
if (t.isTemplateLiteral(node) && node.expressions.length === 0)
return {
found: true,
value: node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? "",
};
if (
t.isUnaryExpression(node, { operator: "-" }) &&
t.isNumericLiteral(node.argument)
)
return { found: true, value: -node.argument.value };
return { found: false };
};
@@ -0,0 +1,118 @@
import { z } from "zod";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { javaScriptSemanticGraphSchema } from "./javascriptSemanticGraph.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const countSchema = z.number().int().min(0);
/** Public target-free request for static JavaScript application analysis. */
export const analyzeJavaScriptApplicationInputSchema = z.strictObject({
input_path: z.string().min(1),
format: z.enum(["auto", "asar", "directory"]).default("auto"),
});
/** Compact counts for the high-level Electron architecture/security surface. */
const electronBoundarySummarySchema = z.strictObject({
browser_windows: countSchema,
explicit_web_preferences: countSchema,
preload_entrypoints: countSchema,
context_bridge_apis: countSchema,
exposed_api_members: countSchema,
ipc: z.strictObject({
operations: countSchema,
literal_channels: countSchema,
dynamic_channel_operations: countSchema,
renderer_transmissions: countSchema,
renderer_listeners: countSchema,
main_handlers: countSchema,
paired_renderer_transmissions: countSchema,
ambiguous_renderer_transmissions: countSchema,
unpaired_literal_renderer_transmissions: countSchema,
}),
sender_validation_observations: countSchema,
utility_processes: countSchema,
resolved_utility_entrypoints: countSchema,
native_addon_bindings: countSchema,
resolved_native_addon_bindings: countSchema,
});
const reconstructionStatisticsSchema = z.strictObject({
relevant_files: countSchema,
nested_asar_containers: countSchema,
text_bytes_read: countSchema,
invalid_utf8_files: countSchema,
parsed_javascript_files: countSchema,
visited_ast_nodes: countSchema,
findings: countSchema,
modules: countSchema,
parse_failures: countSchema,
truncated_scopes: countSchema,
});
/** JavaScript application analysis with an authenticated semantic companion. */
export const javascriptApplicationAnalysisResultSchema = z
.strictObject({
input_path: z.string().min(1),
format: z.enum(["asar", "directory"]),
root_artifact_sha256: digestSchema,
inventory_manifest_id: prefixedDigestSchema("agm"),
inventory_graph_sha256: digestSchema,
graph: javascriptApplicationGraphSchema,
summary: electronBoundarySummarySchema,
statistics: reconstructionStatisticsSchema,
limitations: z.array(z.string().min(1)),
semantic_graph: javaScriptSemanticGraphSchema,
})
.superRefine((result, context) => {
if (result.semantic_graph.application_graph_id !== result.graph.graph_id)
context.addIssue({
code: "custom",
path: ["semantic_graph", "application_graph_id"],
message: "Semantic graph must commit the containing application graph",
});
if (
result.semantic_graph.root_artifact_sha256 !== result.root_artifact_sha256
)
context.addIssue({
code: "custom",
path: ["semantic_graph", "root_artifact_sha256"],
message: "Semantic graph must commit the containing root artifact",
});
const applicationNodeIds = new Set(
result.graph.nodes.map(({ node_id }) => node_id),
);
for (const [nodeIndex, node] of result.semantic_graph.nodes.entries())
for (const [
identifierIndex,
identifier,
] of node.application_node_ids.entries())
if (!applicationNodeIds.has(identifier))
context.addIssue({
code: "custom",
path: [
"semantic_graph",
"nodes",
nodeIndex,
"application_node_ids",
identifierIndex,
],
message: "Semantic node references an absent application node",
});
});
/** Parsed public JavaScript application analysis request. */
export type AnalyzeJavaScriptApplicationInput = z.infer<
typeof analyzeJavaScriptApplicationInputSchema
>;
/** Validated high-level JavaScript application analysis result. */
export type JavaScriptApplicationAnalysisResult = z.infer<
typeof javascriptApplicationAnalysisResultSchema
>;
/** Validated high-level Electron boundary counts. */
export type ElectronBoundarySummary = z.infer<
typeof electronBoundarySummarySchema
>;
@@ -0,0 +1,258 @@
import {
createJavaScriptApplicationEdge,
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
type ApplicationEdge,
type ApplicationGraphEvidence,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { ApplicationVersionComparisonItem } from "./javascriptApplicationVersionComparisonSchemas.js";
interface ChangeGraphInput {
readonly left: JavaScriptApplicationGraph;
readonly right: JavaScriptApplicationGraph;
readonly leftEvidenceId: string;
readonly rightEvidenceId: string;
readonly items: readonly ApplicationVersionComparisonItem[];
}
/** Complete cross-version graph projection. */
export interface ApplicationChangeGraphProjection {
readonly graph: JavaScriptApplicationGraph;
}
/** Merge compared nodes and add inferred right-to-left changed_from edges. */
export const buildJavaScriptApplicationChangeGraph = (
input: ChangeGraphInput,
): ApplicationChangeGraphProjection => {
const allNodes = nodeCandidates(input);
const preferredRoots = uniqueSorted([
...input.right.root_node_ids,
...input.left.root_node_ids,
]).filter((nodeId) => allNodes.has(nodeId));
const orderedNodeIds = uniqueSorted([
...preferredRoots,
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
...(right === null ? [] : [right]),
...(left === null ? [] : [left]),
]),
]);
const retained = new Set(orderedNodeIds);
const mergedNodes = mergeNodes(
orderedNodeIds.flatMap((nodeId) => allNodes.get(nodeId) ?? []),
);
const sourceEdges = uniqueEdges([
...input.left.edges,
...input.right.edges,
]).filter(
({ source_node_id: source, target_node_id: target }) =>
retained.has(source) && retained.has(target),
);
const comparisonEdges = input.items.flatMap((item) =>
changedFromEdge(item, input, retained),
);
const candidateEdges = uniqueEdges([...sourceEdges, ...comparisonEdges]);
const rootNodeIds = preferredRoots.filter((nodeId) => retained.has(nodeId));
const fallbackRoot = mergedNodes[0]?.node_id;
const graph = createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids:
rootNodeIds.length > 0
? rootNodeIds
: fallbackRoot === undefined
? []
: [fallbackRoot],
nodes: mergedNodes,
edges: candidateEdges,
coverage: changeGraphCoverage(input),
limitations: uniqueSorted([
...input.left.limitations.map((value) => `Left: ${value}`),
...input.right.limitations.map((value) => `Right: ${value}`),
"changed_from edges are cross-version inferences and never promote structural or semantic matches to exact identity.",
"The change graph contains compared entities and their retained relationships; it is not an executable application.",
]),
});
return { graph };
};
const nodeCandidates = (
input: ChangeGraphInput,
): Map<string, ApplicationNode[]> => {
const required = new Set([
...input.left.root_node_ids,
...input.right.root_node_ids,
...input.items.flatMap(({ left_node_id: left, right_node_id: right }) => [
...(left === null ? [] : [left]),
...(right === null ? [] : [right]),
]),
]);
const output = new Map<string, ApplicationNode[]>();
for (const node of [...input.left.nodes, ...input.right.nodes])
if (required.has(node.node_id))
output.set(node.node_id, [...(output.get(node.node_id) ?? []), node]);
return output;
};
const changedFromEdge = (
item: ApplicationVersionComparisonItem,
input: ChangeGraphInput,
retained: ReadonlySet<string>,
): ApplicationEdge[] => {
const left = item.left_node_id;
const right = item.right_node_id;
if (
item.match.status !== "matched" ||
item.status === "unchanged" ||
left === null ||
right === null ||
left === right ||
!retained.has(left) ||
!retained.has(right)
)
return [];
const evidence = comparisonEvidence(item, input);
return [
createJavaScriptApplicationEdge({
source_node_id: right,
target_node_id: left,
relation: "changed_from",
properties: {
comparison_item_id: item.item_id,
status: item.status,
match_basis: item.match.basis,
match_confidence: item.match.confidence,
dimensions: item.dimensions,
},
evidence,
}),
];
};
const comparisonEvidence = (
item: ApplicationVersionComparisonItem,
input: ChangeGraphInput,
): ApplicationGraphEvidence => {
const right = input.right.nodes.find(
({ node_id: id }) => id === item.right_node_id,
);
const left = input.left.nodes.find(
({ node_id: id }) => id === item.left_node_id,
);
const source =
right?.observations[0]?.evidence ?? left?.observations[0]?.evidence;
const complete =
input.left.coverage.status === "complete" &&
input.right.coverage.status === "complete";
return {
authority: "cross-version-comparison",
state: "inferred",
confidence: item.match.confidence === "medium" ? "medium" : "high",
artifact: source?.artifact ?? {
available: false,
reason: "unresolved",
detail: "Compared node has no artifact-backed observation.",
},
location: source?.location ?? {
available: false,
reason: "unresolved",
detail: "Compared node has no actionable source location.",
},
extractor: {
name: "rea-application-version-comparison",
version: "1",
operation: "compare_application_versions",
executable_sha256: null,
},
coverage: complete
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: {
status: "partial",
truncated:
input.left.coverage.truncated || input.right.coverage.truncated,
omitted_count: combineOmittedCounts(
input.left.coverage.omitted_count,
input.right.coverage.omitted_count,
),
limits: sourceCoverageLimits(input),
},
limitations: [
"Cross-version pairing is inferred from the stated match basis; changed_from does not prove runtime reachability.",
...item.limitations,
],
evidence_ids: [input.leftEvidenceId, input.rightEvidenceId],
};
};
const changeGraphCoverage = (
input: ChangeGraphInput,
): JavaScriptApplicationGraph["coverage"] => {
if (
input.left.coverage.status === "complete" &&
input.right.coverage.status === "complete"
)
return {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
};
return {
status: "partial",
truncated: input.left.coverage.truncated || input.right.coverage.truncated,
omitted_count: combineOmittedCounts(
input.left.coverage.omitted_count,
input.right.coverage.omitted_count,
),
limits: sourceCoverageLimits(input),
};
};
const sourceCoverageLimits = (input: ChangeGraphInput) =>
[
...new Map(
[...input.left.coverage.limits, ...input.right.coverage.limits].map(
(limit) => [`${limit.name}\0${limit.value}\0${limit.unit}`, limit],
),
).values(),
].sort((left, right) => compareCodePoints(left.name, right.name));
const combineOmittedCounts = (left: number | null, right: number | null) =>
left === null || right === null ? null : left + right;
const mergeNodes = (nodes: readonly ApplicationNode[]): ApplicationNode[] => {
const groups = new Map<string, ApplicationNode[]>();
for (const node of nodes)
groups.set(node.node_id, [...(groups.get(node.node_id) ?? []), node]);
const merged = [...groups.values()].map((group) => {
const first = group[0];
if (first === undefined)
throw new TypeError("Empty change-graph node group");
const observations = [
...new Map(
group
.flatMap(({ observations: values }) => values)
.map((observation) => [observation.observation_id, observation]),
).values(),
].sort((left, right) =>
compareCodePoints(left.observation_id, right.observation_id),
);
return createJavaScriptApplicationNode({
kind: first.kind,
identity: first.identity,
observations: observations.map(
({ observation_id: _id, identifier_strategy: _strategy, ...value }) =>
value,
),
});
});
return merged.sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
);
};
const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] =>
[...new Map(edges.map((edge) => [edge.edge_id, edge])).values()].sort(
(left, right) => compareCodePoints(left.edge_id, right.edge_id),
);
@@ -0,0 +1,480 @@
import { z } from "zod";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const boundedTextSchema = z.string().min(1);
const boundedKeySchema = z.string().min(1);
const unsafePathSegments = new Set(["", ".", ".."]);
const isSafeRelativePath = (path: string): boolean => {
if (path.startsWith("/") || path.includes("\\")) return false;
return path.split("/").every((part) => !unsafePathSegments.has(part));
};
const relativePathSchema = z
.string()
.min(1)
.refine(
isSafeRelativePath,
"Expected a normalized relative POSIX path without traversal",
);
/** Authority that produced one node observation or relationship. */
const applicationEvidenceAuthoritySchema = z.enum([
"artifact-bytes",
"ast-static-analysis",
"static-relationship-inference",
"passive-cdp-runtime",
"cross-layer-reconciliation",
"cross-version-comparison",
"controlled-replay",
"native-analysis-provider",
"managed-static-analysis",
"historical-reference",
"user-assertion",
"unknown",
]);
/** Epistemic state kept separate from the evidence source. */
const applicationFactStateSchema = z.enum([
"observed",
"inferred",
"unknown",
"unavailable",
]);
/** Confidence assigned without promoting inference into observation. */
const applicationConfidenceSchema = z.enum([
"exact",
"high",
"medium",
"low",
"unknown",
]);
/** Why an artifact or source location was not available to an extractor. */
const applicationUnavailableReasonSchema = z.enum([
"not-applicable",
"not-observed",
"truncated",
"provider-unavailable",
"unresolved",
"unknown",
]);
const unavailableFactSchema = z.strictObject({
available: z.literal(false),
reason: applicationUnavailableReasonSchema,
detail: boundedTextSchema,
});
const availableArtifactSchema = z
.strictObject({
available: z.literal(true),
artifact_id: prefixedDigestSchema("art"),
sha256: digestSchema,
})
.superRefine((artifact, context) => {
if (artifact.artifact_id !== `art_${artifact.sha256}`)
context.addIssue({
code: "custom",
path: ["artifact_id"],
message: "Artifact identifier must commit the same SHA-256 digest",
});
});
/** Explicit content-addressed artifact availability for one graph fact. */
const applicationArtifactReferenceSchema = z.discriminatedUnion("available", [
availableArtifactSchema,
unavailableFactSchema,
]);
const sourceRangeSchema = z
.strictObject({
kind: z.literal("source-range"),
source: boundedTextSchema,
start: z.strictObject({
line: z.number().int().min(1),
column: z.number().int().min(0),
}),
end: z.strictObject({
line: z.number().int().min(1),
column: z.number().int().min(0),
}),
})
.superRefine((location, context) => {
if (
location.end.line < location.start.line ||
(location.end.line === location.start.line &&
location.end.column < location.start.column)
)
context.addIssue({
code: "custom",
path: ["end"],
message: "Source range end must not precede its start",
});
});
const fileOffsetRangeSchema = z
.strictObject({
kind: z.literal("file-offset-range"),
start: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
end: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
})
.superRefine((location, context) => {
if (location.end < location.start)
context.addIssue({
code: "custom",
path: ["end"],
message: "File offset range end must not precede its start",
});
});
/** A deterministic artifact, source, runtime, package, or native location. */
const applicationLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
kind: z.literal("artifact-path"),
path: relativePathSchema,
}),
sourceRangeSchema,
fileOffsetRangeSchema,
z.strictObject({
kind: z.literal("url"),
url: z.string().min(1),
}),
z.strictObject({
kind: z.literal("runtime"),
capture_sha256: digestSchema,
target_key: boundedKeySchema,
frame_key: boundedKeySchema.nullable(),
script_key: boundedKeySchema.nullable(),
}),
z.strictObject({
kind: z.literal("native-address"),
address: boundedKeySchema,
symbol: boundedTextSchema.nullable(),
}),
z.strictObject({
kind: z.literal("package-export"),
package_name: boundedKeySchema,
export_path: boundedTextSchema,
}),
]);
/** Explicit source-location availability for one graph fact. */
const applicationLocationReferenceSchema = z.discriminatedUnion("available", [
z.strictObject({
available: z.literal(true),
value: applicationLocationSchema,
}),
unavailableFactSchema,
]);
/** Versioned extractor coordinates attached to every graph fact. */
const applicationExtractorSchema = z.strictObject({
name: z.string().min(1),
version: z.string().min(1),
operation: z.string().min(1),
executable_sha256: digestSchema.nullable(),
});
const applicationLimitSchema = z.strictObject({
name: z.string().min(1),
value: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
unit: z.enum([
"items",
"bytes",
"milliseconds",
"depth",
"characters",
"instructions",
"other",
]),
});
/** Bounded collection coverage without treating omission as absence. */
const coverageLimitsSchema = z.array(applicationLimitSchema);
const omittedCountSchema = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
export const applicationCoverageSchema = z.union([
z.strictObject({
status: z.literal("complete"),
truncated: z.literal(false),
omitted_count: z.literal(0),
limits: coverageLimitsSchema,
}),
z.strictObject({
status: z.literal("partial"),
truncated: z.literal(false),
omitted_count: omittedCountSchema.nullable(),
limits: coverageLimitsSchema,
}),
z.strictObject({
status: z.literal("partial"),
truncated: z.literal(true),
omitted_count: z.union([omittedCountSchema.positive(), z.null()]),
limits: z.array(applicationLimitSchema).min(1),
}),
z.strictObject({
status: z.enum(["unknown", "unavailable"]),
truncated: z.literal(false),
omitted_count: z.null(),
limits: coverageLimitsSchema,
}),
]);
export type ApplicationCoverage = z.infer<typeof applicationCoverageSchema>;
/** Construct complete bounded coverage under the stated configured limits. */
export const completeApplicationCoverage = (
limits: ApplicationCoverage["limits"] = [],
): ApplicationCoverage =>
applicationCoverageSchema.parse({
status: "complete",
truncated: false,
omitted_count: 0,
limits,
});
/** Construct partial non-truncated coverage without inventing omissions. */
export const partialApplicationCoverage = (
limits: ApplicationCoverage["limits"],
omittedCount: number | null,
): ApplicationCoverage =>
applicationCoverageSchema.parse({
status: "partial",
truncated: false,
omitted_count: omittedCount,
limits,
});
/** Construct limit-truncated coverage with a named bound. */
export const truncatedApplicationCoverage = (
limits: ApplicationCoverage["limits"],
omittedCount: number | null,
): ApplicationCoverage =>
applicationCoverageSchema.parse({
status: "partial",
truncated: true,
omitted_count: omittedCount,
limits,
});
const applicationGraphEvidenceBaseSchema = z.strictObject({
authority: applicationEvidenceAuthoritySchema,
state: applicationFactStateSchema,
confidence: applicationConfidenceSchema,
artifact: applicationArtifactReferenceSchema,
location: applicationLocationReferenceSchema,
extractor: applicationExtractorSchema,
coverage: applicationCoverageSchema,
limitations: z.array(boundedTextSchema),
evidence_ids: z.array(prefixedDigestSchema("ev")),
});
type EvidenceValue = z.infer<typeof applicationGraphEvidenceBaseSchema>;
const checkAuthorityState = (
evidence: EvidenceValue,
context: z.RefinementCtx,
): void => {
if (
evidence.authority === "static-relationship-inference" &&
evidence.state !== "inferred"
)
context.addIssue({
code: "custom",
path: ["state"],
message: "Static relationship authority must remain inferred",
});
if (
evidence.authority === "cross-layer-reconciliation" &&
evidence.state !== "inferred"
)
context.addIssue({
code: "custom",
path: ["state"],
message: "Cross-layer reconciliation authority must remain inferred",
});
if (
evidence.authority === "cross-version-comparison" &&
evidence.state !== "inferred"
)
context.addIssue({
code: "custom",
path: ["state"],
message: "Cross-version comparison authority must remain inferred",
});
if (
evidence.authority === "unknown" &&
!["unknown", "unavailable"].includes(evidence.state)
)
context.addIssue({
code: "custom",
path: ["state"],
message: "Unknown authority cannot claim an observed fact",
});
};
const checkStateConfidence = (
evidence: EvidenceValue,
context: z.RefinementCtx,
): void => {
if (
["unknown", "unavailable"].includes(evidence.state) &&
(evidence.confidence !== "unknown" || evidence.limitations.length === 0)
)
context.addIssue({
code: "custom",
message:
"Unknown and unavailable facts require unknown confidence and an explicit limitation",
});
if (evidence.state === "observed" && evidence.confidence === "unknown")
context.addIssue({
code: "custom",
path: ["confidence"],
message: "Observed facts require a bounded non-unknown confidence",
});
if (
evidence.state === "inferred" &&
!["high", "medium", "low"].includes(evidence.confidence)
)
context.addIssue({
code: "custom",
path: ["confidence"],
message: "Inferred facts require high, medium, or low confidence",
});
if (evidence.confidence === "exact" && evidence.state !== "observed")
context.addIssue({
code: "custom",
path: ["confidence"],
message: "Exact confidence is reserved for observed facts",
});
};
const checkTraceability = (
evidence: EvidenceValue,
context: z.RefinementCtx,
): void => {
if (evidence.state === "observed" && !evidence.location.available)
context.addIssue({
code: "custom",
path: ["location"],
message: "Observed facts require an actionable location",
});
if (evidence.state === "inferred" && evidence.limitations.length === 0)
context.addIssue({
code: "custom",
path: ["limitations"],
message: "Inferred facts require an explicit limitation",
});
if (
evidence.coverage.status !== "complete" &&
evidence.limitations.length === 0
)
context.addIssue({
code: "custom",
path: ["limitations"],
message: "Non-complete coverage requires an explicit limitation",
});
};
const checkArtifactBacking = (
evidence: EvidenceValue,
context: z.RefinementCtx,
): void => {
const artifactBacked = [
"artifact-bytes",
"ast-static-analysis",
"controlled-replay",
"native-analysis-provider",
"managed-static-analysis",
].includes(evidence.authority);
if (
artifactBacked &&
evidence.state !== "unavailable" &&
!evidence.artifact.available
)
context.addIssue({
code: "custom",
path: ["artifact"],
message: "Artifact-backed facts require a content digest",
});
};
/** Provenance, authority, uncertainty, and bounds for one graph fact. */
export const applicationGraphEvidenceSchema =
applicationGraphEvidenceBaseSchema.superRefine((evidence, context) => {
checkAuthorityState(evidence, context);
checkStateConfidence(evidence, context);
checkTraceability(evidence, context);
checkArtifactBacking(evidence, context);
});
/** Stable node identifier strategies and their explicit scope. */
export const applicationNodeIdentitySchema = z.discriminatedUnion("strategy", [
z.strictObject({
strategy: z.literal("content-digest"),
stability: z.literal("global-exact"),
sha256: digestSchema,
}),
z.strictObject({
strategy: z.literal("source-map-original"),
stability: z.literal("source-map-exact"),
source_map_sha256: digestSchema,
// The exact `sources` entry; `""` is a legal relative reference.
original_source: z.string(),
source_sha256: digestSchema.nullable(),
}),
z.strictObject({
strategy: z.literal("canonical-path"),
stability: z.literal("artifact-version"),
artifact_sha256: digestSchema,
path: relativePathSchema,
}),
z.strictObject({
strategy: z.literal("structural-fingerprint"),
stability: z.literal("cross-version-inference"),
algorithm: z.string().min(1),
fingerprint_sha256: digestSchema,
basis: z
.array(
z.enum([
"syntax-tree",
"control-flow",
"imports",
"exports",
"literals",
"api-usage",
]),
)
.min(1),
}),
z.strictObject({
strategy: z.literal("artifact-local-key"),
stability: z.literal("artifact-version"),
artifact_sha256: digestSchema,
namespace: boundedKeySchema,
// The exact artifact-local value, such as `""` from `fetch("")`.
key: z.string(),
}),
z.strictObject({
strategy: z.literal("runtime-instance"),
stability: z.literal("capture-only"),
capture_sha256: digestSchema,
runtime_key: boundedTextSchema,
}),
z.strictObject({
strategy: z.literal("observation-fingerprint"),
stability: z.literal("observation-only"),
observation_sha256: digestSchema,
scope: boundedTextSchema,
}),
]);
/** Evidence coordinates attached to one graph observation or edge. */
export type ApplicationGraphEvidence = z.infer<
typeof applicationGraphEvidenceSchema
>;
/** Explicit stable identity strategy for one application entity. */
export type ApplicationNodeIdentity = z.infer<
typeof applicationNodeIdentitySchema
>;
@@ -0,0 +1,486 @@
import {
createJavaScriptApplicationEdge,
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
type ApplicationGraphEvidence,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
export const APPLICATION_GRAPH_DIGESTS = {
package: "1".repeat(64),
asar: "2".repeat(64),
nativeAddon: "3".repeat(64),
capture: "4".repeat(64),
} as const;
/** Coverage block asserting nothing was truncated or omitted. */
export const completeCoverage = {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
} satisfies ApplicationGraphEvidence["coverage"];
const extractor = (operation: string) => ({
name: "rea-test-fixture",
version: "1.0.0",
operation,
executable_sha256: null,
});
export const artifactEvidence = (
sha256: string,
path: string,
authority:
| "artifact-bytes"
| "ast-static-analysis"
| "native-analysis-provider" = "artifact-bytes",
): ApplicationGraphEvidence => ({
authority,
state: "observed",
confidence: "exact",
artifact: {
available: true,
artifact_id: `art_${sha256}`,
sha256,
},
location: { available: true, value: { kind: "artifact-path", path } },
extractor: extractor(`observe-${authority}`),
coverage: completeCoverage,
limitations: [],
evidence_ids: [],
});
export const inferredArtifactEvidence = (
sha256: string,
path: string,
): ApplicationGraphEvidence => ({
authority: "static-relationship-inference",
state: "inferred",
confidence: "high",
artifact: {
available: true,
artifact_id: `art_${sha256}`,
sha256,
},
location: { available: true, value: { kind: "artifact-path", path } },
extractor: extractor("infer-static-relationship"),
coverage: completeCoverage,
limitations: ["Relationship is inferred from static syntax."],
evidence_ids: [],
});
export const runtimeEvidence = (
runtimeKey: string,
): ApplicationGraphEvidence => ({
authority: "passive-cdp-runtime",
state: "observed",
confidence: "exact",
artifact: {
available: false,
reason: "not-observed",
detail: "Passive CDP metadata did not expose backing artifact bytes.",
},
location: {
available: true,
value: {
kind: "runtime",
capture_sha256: APPLICATION_GRAPH_DIGESTS.capture,
target_key: "target-main",
frame_key: "frame-main",
script_key: runtimeKey,
},
},
extractor: extractor("observe-passive-cdp"),
coverage: completeCoverage,
limitations: ["Only passive CDP metadata was observed."],
evidence_ids: [],
});
type FixtureNode = ReturnType<typeof createJavaScriptApplicationNode>;
type NodeProperties = FixtureNode["observations"][number]["properties"];
type FixtureNodeArguments = [
kind: FixtureNode["kind"],
identity: FixtureNode["identity"],
label: string,
properties: NodeProperties,
evidence: ApplicationGraphEvidence,
];
const fixtureNode = (
...[kind, identity, label, properties, evidence]: FixtureNodeArguments
): FixtureNode =>
createJavaScriptApplicationNode({
kind,
identity,
observations: [{ label, properties, evidence }],
});
const buildArtifactNodes = (): FixtureNode[] => [
fixtureNode(
"package",
{
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.package,
},
"Synthetic desktop package",
{ format: "directory" },
artifactEvidence(APPLICATION_GRAPH_DIGESTS.package, "package.json"),
),
fixtureNode(
"artifact",
{
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.asar,
},
"resources/app.asar",
{ format: "asar" },
artifactEvidence(APPLICATION_GRAPH_DIGESTS.asar, "resources/app.asar"),
),
fixtureNode(
"electron-preload",
{
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
path: "dist/preload.js",
},
"desktop preload",
{ sandboxed: true },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
"ast-static-analysis",
),
),
];
const buildInteractionNodes = (): FixtureNode[] => [
fixtureNode(
"context-bridge-api",
{
strategy: "artifact-local-key",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
namespace: "contextBridge",
key: "desktopApi",
},
"desktopApi",
{ methods: ["openProject"] },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
"ast-static-analysis",
),
),
fixtureNode(
"ipc-channel",
{
strategy: "artifact-local-key",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
namespace: "electron-ipc",
key: "project:open",
},
"project:open",
{ mode: "invoke" },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
"ast-static-analysis",
),
),
fixtureNode(
"ipc-handler",
{
strategy: "artifact-local-key",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
namespace: "ipcMain.handle",
key: "project:open",
},
"project open handler",
{ process: "main" },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/main.js",
"ast-static-analysis",
),
),
];
const buildNativeRuntimeNodes = (): FixtureNode[] => [
fixtureNode(
"native-addon",
{
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
},
"synthetic.node",
{ abi: "napi" },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.nativeAddon,
"native/synthetic.node",
"native-analysis-provider",
),
),
fixtureNode(
"native-export",
{
strategy: "artifact-local-key",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
namespace: "napi-export",
key: "openProject",
},
"openProject",
{ calling_convention: "napi" },
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.nativeAddon,
"native/synthetic.node",
"native-analysis-provider",
),
),
fixtureNode(
"runtime-script-instance",
{
strategy: "runtime-instance",
stability: "capture-only",
capture_sha256: APPLICATION_GRAPH_DIGESTS.capture,
runtime_key: "script-preload",
},
"preload runtime script",
{ url: "file:///synthetic/dist/preload.js" },
runtimeEvidence("script-preload"),
),
];
const observedEdge = (
sourceNodeId: string,
targetNodeId: string,
relation: "contains" | "exposes" | "handles",
evidence: ApplicationGraphEvidence,
) =>
createJavaScriptApplicationEdge({
source_node_id: sourceNodeId,
target_node_id: targetNodeId,
relation,
properties: {},
evidence,
});
const inferredEdge = (
sourceNodeId: string,
targetNodeId: string,
relation: "invokes" | "calls" | "loads",
path: string,
) =>
createJavaScriptApplicationEdge({
source_node_id: sourceNodeId,
target_node_id: targetNodeId,
relation,
properties: {},
evidence: inferredArtifactEvidence(APPLICATION_GRAPH_DIGESTS.asar, path),
});
const buildEdges = (nodes: FixtureNode[]) => {
const [packageNode, asarNode, preloadNode, bridgeNode, channelNode] = nodes;
const [handlerNode, addonNode, exportNode, runtimeNode] = nodes.slice(5);
if (
packageNode === undefined ||
asarNode === undefined ||
preloadNode === undefined ||
bridgeNode === undefined ||
channelNode === undefined ||
handlerNode === undefined ||
addonNode === undefined ||
exportNode === undefined ||
runtimeNode === undefined
) {
throw new Error(
"Synthetic application graph fixture nodes are incomplete.",
);
}
return [
observedEdge(
packageNode.node_id,
asarNode.node_id,
"contains",
artifactEvidence(APPLICATION_GRAPH_DIGESTS.package, "resources/app.asar"),
),
observedEdge(
asarNode.node_id,
preloadNode.node_id,
"contains",
artifactEvidence(APPLICATION_GRAPH_DIGESTS.asar, "dist/preload.js"),
),
observedEdge(
preloadNode.node_id,
bridgeNode.node_id,
"exposes",
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
"ast-static-analysis",
),
),
inferredEdge(
bridgeNode.node_id,
channelNode.node_id,
"invokes",
"dist/preload.js",
),
observedEdge(
channelNode.node_id,
handlerNode.node_id,
"handles",
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/main.js",
"ast-static-analysis",
),
),
inferredEdge(
handlerNode.node_id,
addonNode.node_id,
"loads",
"dist/main.js",
),
inferredEdge(
handlerNode.node_id,
exportNode.node_id,
"calls",
"dist/main.js",
),
observedEdge(
addonNode.node_id,
exportNode.node_id,
"contains",
artifactEvidence(
APPLICATION_GRAPH_DIGESTS.nativeAddon,
"native/synthetic.node",
"native-analysis-provider",
),
),
createJavaScriptApplicationEdge({
source_node_id: preloadNode.node_id,
target_node_id: runtimeNode.node_id,
relation: "observed_as",
properties: {},
evidence: runtimeEvidence("script-preload"),
}),
];
};
/** Build a synthetic cross-layer Electron graph without proprietary artifacts. */
export const buildSyntheticJavaScriptApplicationGraph =
(): JavaScriptApplicationGraph => {
const nodes = [
...buildArtifactNodes(),
...buildInteractionNodes(),
...buildNativeRuntimeNodes(),
];
const packageNode = nodes[0];
if (packageNode === undefined) {
throw new Error("Synthetic application graph fixture has no root node.");
}
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [packageNode.node_id],
nodes,
edges: buildEdges(nodes),
coverage: completeCoverage,
limitations: [
"Synthetic fixture demonstrates identity and authority boundaries only.",
],
});
};
/** Find the fixture node carrying an observation with the given label. */
export const nodeByLabel = (
graph: JavaScriptApplicationGraph,
label: string,
): ApplicationNode => {
const node = graph.nodes.find(({ observations }) =>
observations.some((observation) => observation.label === label),
);
if (node === undefined) throw new TypeError(`Missing fixture node: ${label}`);
return node;
};
/** Return the first value, failing loudly when a fixture is empty. */
export const firstOf = <Value>(
values: readonly Value[],
label: string,
): Value => {
const value = values[0];
if (value === undefined) throw new TypeError(`Missing fixture ${label}`);
return value;
};
/** Shared fixture helper. */
export const graphForNode = (
node: ApplicationNode,
): JavaScriptApplicationGraph =>
createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [node.node_id],
nodes: [node],
edges: [],
coverage: completeCoverage,
limitations: [],
});
/** Shared fixture helper. */
export const unknownEvidence = (
limitations: string[] = ["The extractor could not classify this fact."],
): ApplicationGraphEvidence => ({
authority: "unknown",
state: "unknown",
confidence: "unknown",
artifact: {
available: false,
reason: "unknown",
detail: "Artifact provenance is unknown.",
},
location: {
available: false,
reason: "unknown",
detail: "Source location is unknown.",
},
extractor: {
name: "test",
version: "1",
operation: "unknown",
executable_sha256: null,
},
coverage: {
status: "unknown",
truncated: false,
omitted_count: null,
limits: [],
},
limitations,
evidence_ids: [],
});
/** Shared fixture helper. */
export const contentNode = (
evidence: ApplicationGraphEvidence,
properties: Record<string, unknown> = {},
): ApplicationNode =>
createJavaScriptApplicationNode({
kind: "javascript-module",
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.asar,
},
observations: [{ label: "module", properties, evidence }],
});
@@ -0,0 +1,871 @@
import { describe, expect, it } from "vitest";
import {
computeJavaScriptApplicationGraphSha256,
createJavaScriptApplicationEdge,
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
javascriptApplicationGraphSchema,
parseJavaScriptApplicationGraph,
serializeJavaScriptApplicationGraph,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
JAVASCRIPT_APPLICATION_NODE_KINDS,
JAVASCRIPT_APPLICATION_RELATIONS,
} from "./javascriptApplicationGraphSchemas.js";
import {
APPLICATION_GRAPH_DIGESTS,
artifactEvidence,
buildSyntheticJavaScriptApplicationGraph,
completeCoverage,
contentNode,
firstOf,
graphForNode,
inferredArtifactEvidence,
nodeByLabel,
runtimeEvidence,
unknownEvidence,
} from "./javascriptApplicationGraph.fixture.js";
const createLargeNativeExportGraph = (): JavaScriptApplicationGraph => {
const properties = Object.fromEntries(
Array.from({ length: 1_001 }, (_, index) => [
`${"export-property-"}${"k".repeat(120)}-${index}`,
"v".repeat(4_097),
]),
);
const nodes = Array.from({ length: 1_001 }, (_, index) => {
const path = `native/exports/${index}.symbol`;
return createJavaScriptApplicationNode({
kind: "native-export",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
path,
},
observations: [
{
label: index === 0 ? "large export graph label ".repeat(300) : path,
properties: index === 0 ? properties : {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.nativeAddon,
path,
"native-analysis-provider",
),
},
],
});
});
const first = nodes[0];
if (first === undefined) throw new TypeError("Missing native export");
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [first.node_id],
nodes,
edges: [],
coverage: {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
},
limitations: [],
});
};
it("accepts deeply nested canonical application properties", () => {
let nested: unknown = "leaf";
for (let index = 0; index < 12; index += 1)
nested = { [`level-${String(index)}`]: nested };
const node = createJavaScriptApplicationNode({
kind: "native-export",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.nativeAddon,
path: "native/deep-export",
},
observations: [
{
label: "deep export",
properties: { nested },
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.nativeAddon,
"native/deep-export",
"native-analysis-provider",
),
},
],
});
const graph = createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [node.node_id],
nodes: [node],
edges: [],
coverage: {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
},
limitations: [],
});
expect(graph.nodes[0]?.observations[0]?.properties).toEqual({ nested });
expect(
parseJavaScriptApplicationGraph(
JSON.parse(serializeJavaScriptApplicationGraph(graph)),
),
).toEqual(graph);
});
describe("JavaScript Application Graph: vocabulary", () => {
it("defines the complete provider-neutral node and relation vocabulary", () => {
expect(JAVASCRIPT_APPLICATION_NODE_KINDS).toEqual([
"package",
"installer",
"artifact",
"asar-entry",
"electron-main",
"electron-preload",
"electron-renderer",
"electron-utility",
"javascript-asset",
"javascript-chunk",
"javascript-module",
"source-map",
"source-module",
"browser-window",
"frame",
"target",
"context-bridge-api",
"ipc-channel",
"ipc-handler",
"worker",
"service-worker",
"endpoint",
"storage",
"native-addon",
"native-export",
"managed-assembly",
"managed-module",
"managed-type",
"managed-method",
"managed-field",
"managed-pinvoke-import",
"managed-native-implementation",
"runtime-script-instance",
"unknown",
]);
expect(JAVASCRIPT_APPLICATION_RELATIONS).toEqual([
"contains",
"loads",
"imports",
"maps_to",
"exposes",
"sends",
"invokes",
"handles",
"calls",
"persists_to",
"observed_as",
"changed_from",
]);
});
it("round-trips one canonical, byte-stable graph", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
const serialized = serializeJavaScriptApplicationGraph(graph);
const decoded: unknown = JSON.parse(serialized);
expect(parseJavaScriptApplicationGraph(decoded)).toEqual(graph);
expect(javascriptApplicationGraphSchema.parse(decoded)).toEqual(graph);
expect(serializeJavaScriptApplicationGraph(decoded)).toBe(serialized);
expect(computeJavaScriptApplicationGraphSha256(decoded)).toMatch(
/^[a-f0-9]{64}$/u,
);
const { graph_id: _graphId, ...semantic } = graph;
expect(
createJavaScriptApplicationGraph({
...semantic,
nodes: semantic.nodes.toReversed(),
edges: semantic.edges.toReversed(),
}),
).toEqual(graph);
});
it("keeps large native-export graphs and their complete properties", () => {
const graph = createLargeNativeExportGraph();
const largeExport = graph.nodes.find(({ observations }) =>
observations.some(({ label }) =>
label?.startsWith("large export graph label "),
),
);
expect(graph.nodes).toHaveLength(1_001);
expect(
Object.keys(largeExport?.observations[0]?.properties ?? {}),
).toHaveLength(1_001);
});
it("represents the synthetic ASAR to preload to IPC to native chain", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
const labels = [
"resources/app.asar",
"desktop preload",
"desktopApi",
"project:open",
"project open handler",
"synthetic.node",
"openProject",
];
const chain = labels.map((label) => nodeByLabel(graph, label));
const expectedRelations = [
"contains",
"exposes",
"invokes",
"handles",
"loads",
"contains",
];
for (let index = 0; index < expectedRelations.length; index += 1)
expect(graph.edges).toContainEqual(
expect.objectContaining({
source_node_id: chain[index]?.node_id,
target_node_id: chain[index + 1]?.node_id,
relation: expectedRelations[index],
}),
);
expect(chain.at(-2)?.kind).toBe("native-addon");
expect(chain.at(-1)?.kind).toBe("native-export");
});
});
describe("JavaScript Application Graph: evidence authority", () => {
it("keeps static observations, static inferences, runtime facts, and native facts distinct", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
const preload = nodeByLabel(graph, "desktop preload");
const runtime = nodeByLabel(graph, "preload runtime script");
const nativeExport = nodeByLabel(graph, "openProject");
const invoke = graph.edges.find(({ relation }) => relation === "invokes");
const observedAs = graph.edges.find(
({ relation }) => relation === "observed_as",
);
expect(preload.observations[0]?.evidence).toMatchObject({
authority: "ast-static-analysis",
state: "observed",
});
expect(invoke?.evidence).toMatchObject({
authority: "static-relationship-inference",
state: "inferred",
});
expect(runtime.observations[0]?.evidence).toMatchObject({
authority: "passive-cdp-runtime",
state: "observed",
});
expect(observedAs?.evidence.authority).toBe("passive-cdp-runtime");
expect(observedAs?.identifier_strategy).toEqual({
strategy: "semantic-content-sha256",
stability: "relationship-exact",
});
expect(runtime.observations[0]?.identifier_strategy).toEqual({
strategy: "semantic-content-sha256",
stability: "observation-exact",
});
expect(nativeExport.observations[0]?.evidence.authority).toBe(
"native-analysis-provider",
);
expect(preload.node_id).not.toBe(runtime.node_id);
});
it("retains explicit unknown observations without using them as identity proof", () => {
const node = createJavaScriptApplicationNode({
kind: "javascript-module",
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.asar,
},
observations: [
{
label: "observed module",
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
),
},
{
label: null,
properties: { question: "runtime correspondence" },
evidence: unknownEvidence(),
},
],
});
const graph = graphForNode(node);
expect(
graph.nodes[0]?.observations.find(
({ evidence }) => evidence.state === "unknown",
)?.evidence,
).toMatchObject({ authority: "unknown", confidence: "unknown" });
});
it("separates stable entity identity from changing observations", () => {
const identity = {
strategy: "canonical-path" as const,
stability: "artifact-version" as const,
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
path: "dist/chunk.js",
};
const first = createJavaScriptApplicationNode({
kind: "javascript-chunk",
identity,
observations: [
{
label: "first label",
properties: { modules: 10 },
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/chunk.js",
"ast-static-analysis",
),
},
],
});
const second = createJavaScriptApplicationNode({
kind: "javascript-chunk",
identity,
observations: [
{
label: "renamed chunk",
properties: { modules: 11 },
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/chunk.js",
"ast-static-analysis",
),
},
],
});
expect(first.node_id).toBe(second.node_id);
expect(first.observations[0]?.observation_id).not.toBe(
second.observations[0]?.observation_id,
);
});
});
describe("JavaScript Application Graph: identity and evidence", () => {
it("normalizes structural identity and evidence set ordering", () => {
const evidence = inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
evidence.limitations = ["z limitation", "a limitation", "a limitation"];
evidence.evidence_ids = [
`ev_${"b".repeat(64)}`,
`ev_${"a".repeat(64)}`,
`ev_${"a".repeat(64)}`,
];
evidence.coverage.limits = [
{ name: "modules", value: 100, unit: "items" },
{ name: "modules", value: 100, unit: "items" },
];
const node = createJavaScriptApplicationNode({
kind: "javascript-module",
identity: {
strategy: "structural-fingerprint",
stability: "cross-version-inference",
algorithm: "synthetic-v1",
fingerprint_sha256: "5".repeat(64),
basis: ["syntax-tree", "imports", "syntax-tree"],
},
observations: [{ label: "module", properties: {}, evidence }],
});
expect(node.identity).toMatchObject({ basis: ["imports", "syntax-tree"] });
expect(node.observations[0]?.evidence.limitations).toEqual([
"a limitation",
"z limitation",
]);
expect(node.observations[0]?.evidence.evidence_ids).toEqual([
`ev_${"a".repeat(64)}`,
`ev_${"b".repeat(64)}`,
]);
expect(node.observations[0]?.evidence.coverage.limits).toEqual([
{ name: "modules", value: 100, unit: "items" },
]);
expect(graphForNode(node).nodes).toEqual([node]);
});
it("scopes runtime identities to a capture and artifact paths to a version", () => {
const runtime = nodeByLabel(
buildSyntheticJavaScriptApplicationGraph(),
"preload runtime script",
);
const differentCapture = createJavaScriptApplicationNode({
kind: "runtime-script-instance",
identity: {
strategy: "runtime-instance",
stability: "capture-only",
capture_sha256: "6".repeat(64),
runtime_key: "script-preload",
},
observations: [
{
label: "other capture",
properties: {},
evidence: {
...runtimeEvidence("script-preload"),
location: {
available: true,
value: {
kind: "runtime",
capture_sha256: "6".repeat(64),
target_key: "target-main",
frame_key: "frame-main",
script_key: "script-preload",
},
},
},
},
],
});
expect(differentCapture.node_id).not.toBe(runtime.node_id);
const firstArtifact = createJavaScriptApplicationNode({
kind: "javascript-asset",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
path: "dist/app.js",
},
observations: [
{
label: null,
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/app.js",
),
},
],
});
const secondArtifact = createJavaScriptApplicationNode({
kind: "javascript-asset",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: "7".repeat(64),
path: "dist/app.js",
},
observations: [
{
label: null,
properties: {},
evidence: artifactEvidence("7".repeat(64), "dist/app.js"),
},
],
});
expect(firstArtifact.node_id).not.toBe(secondArtifact.node_id);
});
});
describe("JavaScript Application Graph: source maps and observations", () => {
it("admits source-map and observation-scoped identities only with supporting observations", () => {
const sourceModule = createJavaScriptApplicationNode({
kind: "source-module",
identity: {
strategy: "source-map-original",
stability: "source-map-exact",
source_map_sha256: APPLICATION_GRAPH_DIGESTS.asar,
original_source: "webpack:///src/editor.ts",
source_sha256: null,
},
observations: [
{
label: "src/editor.ts",
properties: { recovered_from: "source-map" },
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/app.js.map",
"ast-static-analysis",
),
},
],
});
const observationScoped = createJavaScriptApplicationNode({
kind: "unknown",
identity: {
strategy: "observation-fingerprint",
stability: "observation-only",
observation_sha256: "8".repeat(64),
scope: "synthetic static inventory",
},
observations: [
{
label: "unclassified entity",
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/app.js",
),
},
],
});
expect(graphForNode(sourceModule).nodes).toEqual([sourceModule]);
expect(graphForNode(observationScoped).nodes).toEqual([observationScoped]);
});
it("rejects unknown fields and stale commitments", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
expect(() =>
parseJavaScriptApplicationGraph({ ...graph, surprise: true }),
).toThrow();
const staleGraph = structuredClone(graph);
staleGraph.graph_id = `jag_${"f".repeat(64)}`;
expect(() => parseJavaScriptApplicationGraph(staleGraph)).toThrow(
/Graph identifier/u,
);
const staleNode = structuredClone(graph);
firstOf(staleNode.nodes, "node").node_id = `jag_node_${"f".repeat(64)}`;
expect(() => parseJavaScriptApplicationGraph(staleNode)).toThrow(
/Node identifier/u,
);
const staleObservation = structuredClone(graph);
firstOf(
firstOf(staleObservation.nodes, "node").observations,
"observation",
).observation_id = `jag_observation_${"f".repeat(64)}`;
expect(() => parseJavaScriptApplicationGraph(staleObservation)).toThrow(
/Observation identifier/u,
);
const staleEdge = structuredClone(graph);
firstOf(staleEdge.edges, "edge").edge_id = `jag_edge_${"f".repeat(64)}`;
expect(() => parseJavaScriptApplicationGraph(staleEdge)).toThrow(
/Edge identifier/u,
);
});
});
describe("JavaScript Application Graph: duplicate and orphan rejection", () => {
it("rejects duplicate nodes, missing roots, dangling edges, and self edges", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
const { graph_id: _graphId, ...semantic } = graph;
const source = firstOf(semantic.nodes, "node");
expect(() =>
createJavaScriptApplicationGraph({
...semantic,
nodes: [...semantic.nodes, source],
}),
).toThrow(/Nodes must be sorted and unique/u);
expect(() =>
createJavaScriptApplicationGraph({
...semantic,
root_node_ids: [`jag_node_${"9".repeat(64)}`],
}),
).toThrow(/Root identifier/u);
const missingId = `jag_node_${"9".repeat(64)}`;
const dangling = createJavaScriptApplicationEdge({
source_node_id: source.node_id,
target_node_id: missingId,
relation: "loads",
properties: {},
evidence: inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/main.js",
),
});
expect(() =>
createJavaScriptApplicationGraph({
...semantic,
edges: [...semantic.edges, dangling],
}),
).toThrow(/endpoints must name graph nodes/u);
const selfEdge = createJavaScriptApplicationEdge({
source_node_id: source.node_id,
target_node_id: source.node_id,
relation: "imports",
properties: {},
evidence: inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/main.js",
),
});
expect(() =>
createJavaScriptApplicationGraph({
...semantic,
edges: [...semantic.edges, selfEdge],
}),
).toThrow(/self-referential/u);
});
it("allows changed_from only between entities of the same kind", () => {
const graph = buildSyntheticJavaScriptApplicationGraph();
const preload = nodeByLabel(graph, "desktop preload");
const runtime = nodeByLabel(graph, "preload runtime script");
const earlierPreload = createJavaScriptApplicationNode({
kind: "electron-preload",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: "7".repeat(64),
path: "dist/preload.js",
},
observations: [
{
label: "earlier preload",
properties: {},
evidence: artifactEvidence("7".repeat(64), "dist/preload.js"),
},
],
});
const changedFrom = createJavaScriptApplicationEdge({
source_node_id: preload.node_id,
target_node_id: earlierPreload.node_id,
relation: "changed_from",
properties: {},
evidence: inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
),
});
expect(
createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [preload.node_id],
nodes: [preload, earlierPreload],
edges: [changedFrom],
coverage: completeCoverage,
limitations: [],
}).edges,
).toEqual([changedFrom]);
const invalid = createJavaScriptApplicationEdge({
source_node_id: preload.node_id,
target_node_id: runtime.node_id,
relation: "changed_from",
properties: {},
evidence: inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
),
});
expect(() =>
createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [preload.node_id],
nodes: [preload, runtime],
edges: [invalid],
coverage: completeCoverage,
limitations: [],
}),
).toThrow(/changed_from endpoints must have the same node kind/u);
});
});
describe("JavaScript Application Graph: identity strategy requirements", () => {
it("requires every identity strategy to have compatible supporting evidence", () => {
const mismatchedPath = createJavaScriptApplicationNode({
kind: "javascript-asset",
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: APPLICATION_GRAPH_DIGESTS.asar,
path: "dist/expected.js",
},
observations: [
{
label: null,
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/other.js",
),
},
],
});
expect(() => graphForNode(mismatchedPath)).toThrow(
/identity is not supported/u,
);
const runtimeWithStaticEvidence = createJavaScriptApplicationNode({
kind: "runtime-script-instance",
identity: {
strategy: "runtime-instance",
stability: "capture-only",
capture_sha256: APPLICATION_GRAPH_DIGESTS.capture,
runtime_key: "script-preload",
},
observations: [
{
label: null,
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/preload.js",
"ast-static-analysis",
),
},
],
});
expect(() => graphForNode(runtimeWithStaticEvidence)).toThrow(
/identity is not supported/u,
);
const mismatchedDigest = contentNode(
artifactEvidence("7".repeat(64), "dist/module.js"),
);
expect(() => graphForNode(mismatchedDigest)).toThrow(
/identity is not supported/u,
);
});
it("prevents static authorities from claiming runtime locations", () => {
const evidence = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
"ast-static-analysis",
);
evidence.location = runtimeEvidence("script-module").location;
expect(() => graphForNode(contentNode(evidence))).toThrow(
/cannot claim a runtime location/u,
);
});
it("enforces epistemic truthfulness and content-addressed artifacts", () => {
const inferredAsObserved = inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
inferredAsObserved.state = "observed";
inferredAsObserved.confidence = "exact";
expect(() => contentNode(inferredAsObserved)).toThrow(
/must remain inferred/u,
);
const inferenceWithoutLimit = inferredArtifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
inferenceWithoutLimit.limitations = [];
expect(() => contentNode(inferenceWithoutLimit)).toThrow(
/Inferred facts require an explicit limitation/u,
);
const unknownWithoutLimit = unknownEvidence([]);
expect(() => contentNode(unknownWithoutLimit)).toThrow(
/require unknown confidence and an explicit limitation/u,
);
const missingArtifact = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
missingArtifact.artifact = {
available: false,
reason: "not-observed",
detail: "Bytes were not observed.",
};
expect(() => contentNode(missingArtifact)).toThrow(
/require a content digest/u,
);
const mismatchedArtifact = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
if (mismatchedArtifact.artifact.available)
mismatchedArtifact.artifact.artifact_id = `art_${"8".repeat(64)}`;
expect(() => contentNode(mismatchedArtifact)).toThrow(
/same SHA-256 digest/u,
);
const unlocatedObservation = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
unlocatedObservation.location = {
available: false,
reason: "not-observed",
detail: "The exact location was not recorded.",
};
expect(() => contentNode(unlocatedObservation)).toThrow(
/Observed facts require an actionable location/u,
);
});
});
describe("JavaScript Application Graph: truncation claims", () => {
it("rejects false truncation claims and accepts large properties", () => {
const truncated = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
truncated.coverage = {
status: "partial",
truncated: true,
omitted_count: 0,
limits: [],
};
expect(() => contentNode(truncated)).toThrow(/omitted_count[\s\S]*limits/u);
const nonComplete = artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"dist/module.js",
);
nonComplete.coverage = {
status: "partial",
truncated: false,
omitted_count: null,
limits: [],
};
expect(() => contentNode(nonComplete)).toThrow(
/Non-complete coverage requires an explicit limitation/u,
);
const validNode = contentNode(
artifactEvidence(APPLICATION_GRAPH_DIGESTS.asar, "dist/module.js"),
);
expect(() =>
createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [validNode.node_id],
nodes: [validNode],
edges: [],
coverage: {
status: "partial",
truncated: false,
omitted_count: null,
limits: [],
},
limitations: [],
}),
).toThrow(/Non-complete graph coverage requires an explicit limitation/u);
const properties = Object.fromEntries(
Array.from({ length: 65 }, (_, index) => [`key-${String(index)}`, index]),
);
expect(
contentNode(
artifactEvidence(APPLICATION_GRAPH_DIGESTS.asar, "dist/module.js"),
properties,
).observations[0]?.properties,
).toEqual(properties);
});
});
@@ -0,0 +1,474 @@
import { z } from "zod";
import { canonicalDigest, canonicalJson } from "../comparisonSemantics.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type {
ApplicationGraphEvidence,
ApplicationNodeIdentity,
} from "./javascriptApplicationEvidenceSchemas.js";
import {
applicationEdgeInputSchema,
applicationEdgeSchema,
applicationNodeInputSchema,
applicationNodeObservationSchema,
applicationNodeSchema,
javascriptApplicationGraphInputSchema,
javascriptApplicationGraphRecordSchema,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraphInput,
} from "./javascriptApplicationGraphSchemas.js";
const OBSERVATION_IDENTIFIER_STRATEGY = {
strategy: "semantic-content-sha256" as const,
stability: "observation-exact" as const,
};
const EDGE_IDENTIFIER_STRATEGY = {
strategy: "semantic-content-sha256" as const,
stability: "relationship-exact" as const,
};
const limitKey = (
limit: ApplicationGraphEvidence["coverage"]["limits"][number],
) => canonicalJson(limit, "JavaScript Application Graph");
const normalizeLimits = (
limits: ApplicationGraphEvidence["coverage"]["limits"],
): ApplicationGraphEvidence["coverage"]["limits"] =>
[...new Map(limits.map((limit) => [limitKey(limit), limit])).values()].sort(
(left, right) => compareCodePoints(limitKey(left), limitKey(right)),
);
const normalizeEvidence = (
evidence: ApplicationGraphEvidence,
): ApplicationGraphEvidence => ({
...evidence,
coverage: {
...evidence.coverage,
limits: normalizeLimits(evidence.coverage.limits),
},
limitations: uniqueSorted(evidence.limitations),
evidence_ids: uniqueSorted(evidence.evidence_ids),
});
const normalizeIdentity = (
identity: ApplicationNodeIdentity,
): ApplicationNodeIdentity =>
identity.strategy === "structural-fingerprint"
? { ...identity, basis: uniqueSorted(identity.basis) }
: identity;
const nodeSemantic = (node: Pick<ApplicationNode, "kind" | "identity">) => ({
kind: node.kind,
identity: node.identity,
});
const nodeId = (node: Pick<ApplicationNode, "kind" | "identity">): string =>
`jag_node_${canonicalDigest(nodeSemantic(node), "JavaScript Application Graph")}`;
const observationSemantic = (
nodeIdentifier: string,
observation: Omit<
z.infer<typeof applicationNodeObservationSchema>,
"observation_id"
>,
) => ({ node_id: nodeIdentifier, ...observation });
const observationId = (
nodeIdentifier: string,
observation: Omit<
z.infer<typeof applicationNodeObservationSchema>,
"observation_id"
>,
): string =>
`jag_observation_${canonicalDigest(
observationSemantic(nodeIdentifier, observation),
)}`;
type EdgeSemantic = Omit<ApplicationEdge, "edge_id">;
const edgeId = (edge: EdgeSemantic): string =>
`jag_edge_${canonicalDigest(edge, "JavaScript Application Graph")}`;
const sortedUniqueIssue = (
values: readonly string[],
path: PropertyKey[],
label: string,
context: z.RefinementCtx,
): void => {
for (let index = 1; index < values.length; index += 1) {
if (compareCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
continue;
context.addIssue({
code: "custom",
message: `${label} must be sorted and unique by Unicode code point`,
path: [...path, index],
});
return;
}
};
const checkEvidenceNormalization = (
evidence: ApplicationGraphEvidence,
path: PropertyKey[],
context: z.RefinementCtx,
): void => {
sortedUniqueIssue(
evidence.limitations,
[...path, "limitations"],
"Evidence limitations",
context,
);
sortedUniqueIssue(
evidence.evidence_ids,
[...path, "evidence_ids"],
"Evidence identifiers",
context,
);
sortedUniqueIssue(
evidence.coverage.limits.map(limitKey),
[...path, "coverage", "limits"],
"Evidence limits",
context,
);
const runtimeLocation =
evidence.location.available && evidence.location.value.kind === "runtime";
const staticAuthority = [
"artifact-bytes",
"ast-static-analysis",
"static-relationship-inference",
"native-analysis-provider",
].includes(evidence.authority);
if (runtimeLocation && staticAuthority)
context.addIssue({
code: "custom",
message: "Static and native authorities cannot claim a runtime location",
path: [...path, "location"],
});
};
const observationMatchesIdentity = (
node: ApplicationNode,
observation: ApplicationNode["observations"][number],
): boolean => {
const { identity } = node;
const { evidence } = observation;
if (identity.strategy === "content-digest")
return (
evidence.state === "observed" &&
evidence.artifact.available &&
evidence.artifact.sha256 === identity.sha256
);
if (identity.strategy === "source-map-original")
return (
evidence.state === "observed" &&
evidence.artifact.available &&
evidence.artifact.sha256 === identity.source_map_sha256
);
if (identity.strategy === "canonical-path")
return (
evidence.artifact.available &&
evidence.artifact.sha256 === identity.artifact_sha256 &&
evidence.location.available &&
evidence.location.value.kind === "artifact-path" &&
evidence.location.value.path === identity.path
);
if (identity.strategy === "artifact-local-key")
return (
evidence.artifact.available &&
evidence.artifact.sha256 === identity.artifact_sha256
);
if (identity.strategy === "runtime-instance") {
if (
!["passive-cdp-runtime", "controlled-replay"].includes(
evidence.authority,
) ||
!evidence.location.available ||
evidence.location.value.kind !== "runtime"
)
return false;
const location = evidence.location.value;
return (
location.capture_sha256 === identity.capture_sha256 &&
[location.target_key, location.frame_key, location.script_key].includes(
identity.runtime_key,
)
);
}
if (identity.strategy === "structural-fingerprint")
return evidence.state === "inferred";
return evidence.state === "observed";
};
const checkNode = (
node: ApplicationNode,
index: number,
context: z.RefinementCtx,
): void => {
if (node.node_id !== nodeId(node))
context.addIssue({
code: "custom",
message: "Node identifier does not match its kind and identity",
path: ["nodes", index, "node_id"],
});
if (
node.identity.strategy === "structural-fingerprint" &&
canonicalJson(node.identity.basis, "JavaScript Application Graph") !==
canonicalJson(
uniqueSorted(node.identity.basis),
"JavaScript Application Graph",
)
)
context.addIssue({
code: "custom",
message: "Structural fingerprint basis must be sorted and unique",
path: ["nodes", index, "identity", "basis"],
});
sortedUniqueIssue(
node.observations.map(({ observation_id: id }) => id),
["nodes", index, "observations"],
"Node observations",
context,
);
for (const [observationIndex, observation] of node.observations.entries()) {
const { observation_id: identifier, ...semantic } = observation;
if (identifier !== observationId(node.node_id, semantic))
context.addIssue({
code: "custom",
message: "Observation identifier does not match its semantic content",
path: [
"nodes",
index,
"observations",
observationIndex,
"observation_id",
],
});
checkEvidenceNormalization(
observation.evidence,
["nodes", index, "observations", observationIndex, "evidence"],
context,
);
}
if (
!node.observations.some((observation) =>
observationMatchesIdentity(node, observation),
)
)
context.addIssue({
code: "custom",
message: "Node identity is not supported by a compatible observation",
path: ["nodes", index, "identity"],
});
};
type GraphRecord = z.infer<typeof javascriptApplicationGraphRecordSchema>;
const checkGraphInvariants = (
graph: GraphRecord,
context: z.RefinementCtx,
): void => {
sortedUniqueIssue(
graph.root_node_ids,
["root_node_ids"],
"Root nodes",
context,
);
sortedUniqueIssue(
graph.nodes.map(({ node_id: id }) => id),
["nodes"],
"Nodes",
context,
);
sortedUniqueIssue(
graph.edges.map(({ edge_id: id }) => id),
["edges"],
"Edges",
context,
);
sortedUniqueIssue(
graph.limitations,
["limitations"],
"Graph limitations",
context,
);
sortedUniqueIssue(
graph.coverage.limits.map(limitKey),
["coverage", "limits"],
"Graph limits",
context,
);
if (graph.coverage.status !== "complete" && graph.limitations.length === 0)
context.addIssue({
code: "custom",
message: "Non-complete graph coverage requires an explicit limitation",
path: ["limitations"],
});
const nodesById = new Map(graph.nodes.map((node) => [node.node_id, node]));
for (const root of graph.root_node_ids)
if (!nodesById.has(root))
context.addIssue({
code: "custom",
message: "Root identifier must name a graph node",
path: ["root_node_ids"],
});
for (const [index, node] of graph.nodes.entries())
checkNode(node, index, context);
for (const [index, edge] of graph.edges.entries()) {
const { edge_id: identifier, ...semantic } = edge;
if (identifier !== edgeId(semantic))
context.addIssue({
code: "custom",
message: "Edge identifier does not match its semantic content",
path: ["edges", index, "edge_id"],
});
if (
!nodesById.has(edge.source_node_id) ||
!nodesById.has(edge.target_node_id)
)
context.addIssue({
code: "custom",
message: "Edge endpoints must name graph nodes",
path: ["edges", index],
});
if (edge.source_node_id === edge.target_node_id)
context.addIssue({
code: "custom",
message: "Application graph edges cannot be self-referential",
path: ["edges", index],
});
if (
edge.relation === "changed_from" &&
nodesById.get(edge.source_node_id)?.kind !==
nodesById.get(edge.target_node_id)?.kind
)
context.addIssue({
code: "custom",
message: "changed_from endpoints must have the same node kind",
path: ["edges", index, "relation"],
});
checkEvidenceNormalization(
edge.evidence,
["edges", index, "evidence"],
context,
);
}
const { graph_id: identifier, ...semantic } = graph;
if (
identifier !==
`jag_${canonicalDigest(semantic, "JavaScript Application Graph")}`
)
context.addIssue({
code: "custom",
message: "Graph identifier does not match its semantic content",
path: ["graph_id"],
});
};
/** Strict JavaScript Application Graph with verified commitments. */
export const javascriptApplicationGraphSchema =
javascriptApplicationGraphRecordSchema.superRefine(checkGraphInvariants);
/** Fully validated JavaScript Application Graph. */
export type JavaScriptApplicationGraph = z.infer<
typeof javascriptApplicationGraphSchema
>;
/** Build one normalized application entity and derive all semantic IDs. */
export const createJavaScriptApplicationNode = (
input: unknown,
): ApplicationNode => {
const parsed = applicationNodeInputSchema.parse(input);
const identity = normalizeIdentity(parsed.identity);
const identifier = nodeId({ kind: parsed.kind, identity });
const observations = parsed.observations
.map((observation) => {
const semantic = {
...observation,
evidence: normalizeEvidence(observation.evidence),
identifier_strategy: OBSERVATION_IDENTIFIER_STRATEGY,
};
return applicationNodeObservationSchema.parse({
...semantic,
observation_id: observationId(identifier, semantic),
});
})
.sort((left, right) =>
compareCodePoints(left.observation_id, right.observation_id),
);
return applicationNodeSchema.parse({
node_id: identifier,
kind: parsed.kind,
identity,
observations,
});
};
/** Build one normalized directed relationship and derive its semantic ID. */
export const createJavaScriptApplicationEdge = (
input: unknown,
): ApplicationEdge => {
const parsed = applicationEdgeInputSchema.parse(input);
const semantic = {
...parsed,
evidence: normalizeEvidence(parsed.evidence),
identifier_strategy: EDGE_IDENTIFIER_STRATEGY,
};
return applicationEdgeSchema.parse({
...semantic,
edge_id: edgeId(semantic),
});
};
/** Normalize a complete graph and derive its top-level semantic ID. */
export const createJavaScriptApplicationGraph = (
input: unknown,
): JavaScriptApplicationGraph => {
const parsed = javascriptApplicationGraphInputSchema.parse(input);
const semantic: JavaScriptApplicationGraphInput = {
...parsed,
root_node_ids: uniqueSorted(parsed.root_node_ids),
nodes: [...parsed.nodes].sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
),
edges: [...parsed.edges].sort((left, right) =>
compareCodePoints(left.edge_id, right.edge_id),
),
coverage: {
...parsed.coverage,
limits: normalizeLimits(parsed.coverage.limits),
},
limitations: uniqueSorted(parsed.limitations),
};
return javascriptApplicationGraphSchema.parse({
...semantic,
graph_id: `jag_${canonicalDigest(semantic, "JavaScript Application Graph")}`,
});
};
/** Parse a stored graph and reject stale IDs. */
export const parseJavaScriptApplicationGraph = (
input: unknown,
): JavaScriptApplicationGraph => javascriptApplicationGraphSchema.parse(input);
/** Compute the byte-stable SHA-256 commitment of a verified graph. */
export const computeJavaScriptApplicationGraphSha256 = (
input: unknown,
): string =>
canonicalDigest(
parseJavaScriptApplicationGraph(input),
"JavaScript Application Graph",
);
/** Serialize a verified graph as RFC 8785 canonical JSON. */
export const serializeJavaScriptApplicationGraph = (input: unknown): string =>
canonicalJson(
parseJavaScriptApplicationGraph(input),
"JavaScript Application Graph",
);
export type { ApplicationEdge, ApplicationGraphEvidence, ApplicationNode };
@@ -0,0 +1,151 @@
import { z } from "zod";
import {
applicationCoverageSchema,
applicationGraphEvidenceSchema,
applicationNodeIdentitySchema,
} from "./javascriptApplicationEvidenceSchemas.js";
import { jsonValueSchema } from "../jsonValue.js";
import { prefixedDigestSchema } from "../digests.js";
const boundedTextSchema = z.string().min(1);
/** Node kinds admitted by JavaScript Application Graph. */
export const JAVASCRIPT_APPLICATION_NODE_KINDS = [
"package",
"installer",
"artifact",
"asar-entry",
"electron-main",
"electron-preload",
"electron-renderer",
"electron-utility",
"javascript-asset",
"javascript-chunk",
"javascript-module",
"source-map",
"source-module",
"browser-window",
"frame",
"target",
"context-bridge-api",
"ipc-channel",
"ipc-handler",
"worker",
"service-worker",
"endpoint",
"storage",
"native-addon",
"native-export",
"managed-assembly",
"managed-module",
"managed-type",
"managed-method",
"managed-field",
"managed-pinvoke-import",
"managed-native-implementation",
"runtime-script-instance",
"unknown",
] as const;
/** Provider-neutral application entity categories. */
const applicationNodeKindSchema = z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS);
/** Directed relations admitted by JavaScript Application Graph. */
export const JAVASCRIPT_APPLICATION_RELATIONS = [
"contains",
"loads",
"imports",
"maps_to",
"exposes",
"sends",
"invokes",
"handles",
"calls",
"persists_to",
"observed_as",
"changed_from",
] as const;
/** Provider-neutral relation categories. */
const applicationRelationSchema = z.enum(JAVASCRIPT_APPLICATION_RELATIONS);
const applicationPropertiesSchema = z.record(
z.string().min(1),
jsonValueSchema,
);
/** One node observation before its semantic identifier is derived. */
const applicationNodeObservationInputSchema = z.strictObject({
label: z.string().min(1).nullable(),
properties: applicationPropertiesSchema,
evidence: applicationGraphEvidenceSchema,
});
/** One immutable, evidence-bearing observation attached to an entity. */
export const applicationNodeObservationSchema =
applicationNodeObservationInputSchema.extend({
observation_id: prefixedDigestSchema("jag_observation"),
identifier_strategy: z.strictObject({
strategy: z.literal("semantic-content-sha256"),
stability: z.literal("observation-exact"),
}),
});
/** One application entity before its stable identifier is derived. */
export const applicationNodeInputSchema = z.strictObject({
kind: applicationNodeKindSchema,
identity: applicationNodeIdentitySchema,
observations: z.array(applicationNodeObservationInputSchema).min(1),
});
/** One stable application entity with one or more bounded observations. */
export const applicationNodeSchema = z.strictObject({
node_id: prefixedDigestSchema("jag_node"),
kind: applicationNodeKindSchema,
identity: applicationNodeIdentitySchema,
observations: z.array(applicationNodeObservationSchema).min(1),
});
/** One directed relationship before its semantic identifier is derived. */
export const applicationEdgeInputSchema = z.strictObject({
source_node_id: prefixedDigestSchema("jag_node"),
target_node_id: prefixedDigestSchema("jag_node"),
relation: applicationRelationSchema,
properties: applicationPropertiesSchema,
evidence: applicationGraphEvidenceSchema,
});
/** One directed, evidence-bearing application relationship. */
export const applicationEdgeSchema = applicationEdgeInputSchema.extend({
edge_id: prefixedDigestSchema("jag_edge"),
identifier_strategy: z.strictObject({
strategy: z.literal("semantic-content-sha256"),
stability: z.literal("relationship-exact"),
}),
});
/** Graph content before its top-level semantic identifier is derived. */
export const javascriptApplicationGraphInputSchema = z.strictObject({
schema: z.literal("JavaScriptApplicationGraph"),
root_node_ids: z.array(prefixedDigestSchema("jag_node")).min(1),
nodes: z.array(applicationNodeSchema).min(1),
edges: z.array(applicationEdgeSchema),
coverage: applicationCoverageSchema,
limitations: z.array(boundedTextSchema),
});
/** Strict stored shape for a JavaScript Application Graph. */
export const javascriptApplicationGraphRecordSchema =
javascriptApplicationGraphInputSchema.extend({
graph_id: prefixedDigestSchema("jag"),
});
/** Immutable entity in a JavaScript Application Graph. */
export type ApplicationNode = z.infer<typeof applicationNodeSchema>;
/** Immutable relationship in a JavaScript Application Graph. */
export type ApplicationEdge = z.infer<typeof applicationEdgeSchema>;
/** Complete graph content before its graph identifier is derived. */
export type JavaScriptApplicationGraphInput = z.infer<
typeof javascriptApplicationGraphInputSchema
>;
@@ -0,0 +1,163 @@
import { canonicalDigest } from "../comparisonSemantics.js";
import { uniqueSorted } from "../canonicalOrdering.js";
import type { Evidence } from "../evidence.js";
import { buildJavaScriptApplicationChangeGraph } from "./javascriptApplicationChangeGraph.js";
import {
applicationVersionComparisonResultSchema,
type ApplicationVersionComparisonResult,
} from "./javascriptApplicationVersionComparisonSchemas.js";
import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
import { classifyJavaScriptApplicationVersions } from "./javascriptApplicationVersionItems.js";
import { matchJavaScriptApplicationVersions } from "./javascriptApplicationVersionKeys.js";
/** Pure inputs after application-layer Evidence authentication. */
export interface ApplicationVersionComparisonProjectionInput {
readonly left: {
readonly evidenceId: string;
readonly rootArtifactSha256: string;
readonly graph: JavaScriptApplicationGraph;
};
readonly right: {
readonly evidenceId: string;
readonly rootArtifactSha256: string;
readonly graph: JavaScriptApplicationGraph;
};
readonly leftNativeEvidence: readonly Evidence[];
readonly rightNativeEvidence: readonly Evidence[];
}
/** Compare application entities with ordered unique-only identity tiers. */
export const compareJavaScriptApplicationVersions = (
input: ApplicationVersionComparisonProjectionInput,
): ApplicationVersionComparisonResult => {
const matching = matchJavaScriptApplicationVersions(
input.left.graph.nodes,
input.right.graph.nodes,
);
const projection = classifyJavaScriptApplicationVersions(matching, {
leftGraph: input.left.graph,
rightGraph: input.right.graph,
leftEvidenceId: input.left.evidenceId,
rightEvidenceId: input.right.evidenceId,
leftNativeEvidence: input.leftNativeEvidence,
rightNativeEvidence: input.rightNativeEvidence,
});
const changeGraph = buildJavaScriptApplicationChangeGraph({
left: input.left.graph,
right: input.right.graph,
leftEvidenceId: input.left.evidenceId,
rightEvidenceId: input.right.evidenceId,
items: projection.items,
});
const evidenceLinks = uniqueSorted(
projection.items.flatMap(({ evidence_links: links }) => links),
);
const omissions = {
left_graph_omitted_count: input.left.graph.coverage.omitted_count,
right_graph_omitted_count: input.right.graph.coverage.omitted_count,
};
const coverage = comparisonCoverage(input, omissions);
const semantic = {
left: {
evidence_id: input.left.evidenceId,
graph_id: input.left.graph.graph_id,
root_artifact_sha256: input.left.rootArtifactSha256,
},
right: {
evidence_id: input.right.evidenceId,
graph_id: input.right.graph.graph_id,
root_artifact_sha256: input.right.rootArtifactSha256,
},
summary: summary(projection.items),
matching: matchingSummary(projection.items),
items: projection.items,
graph: changeGraph.graph,
coverage,
evidence_links: evidenceLinks,
limitations: comparisonLimitations(input),
};
return applicationVersionComparisonResultSchema.parse({
...semantic,
comparison_id: `javc_${canonicalDigest(semantic, "Application version comparison")}`,
});
};
const summary = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
): ApplicationVersionComparisonResult["summary"] => ({
unchanged: countStatus(items, "unchanged"),
added: countStatus(items, "added"),
removed: countStatus(items, "removed"),
changed: countStatus(items, "changed"),
unknown: countStatus(items, "unknown"),
});
const countStatus = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
status: ApplicationVersionComparisonResult["items"][number]["status"],
): number => items.filter((item) => item.status === status).length;
const matchingSummary = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
): ApplicationVersionComparisonResult["matching"] => ({
exact_node_identity: countBasis(items, "exact-node-identity"),
exact_content_digest: countBasis(items, "exact-content-digest"),
exact_module_source_digest: countBasis(items, "exact-module-source-digest"),
source_map_identity: countBasis(items, "source-map-identity"),
structural_fingerprint: countBasis(items, "structural-fingerprint"),
semantic_key: countBasis(items, "semantic-key"),
ambiguous: items.filter(({ match }) => match.status === "ambiguous").length,
unmatched: items.filter(({ match }) => match.status === "unmatched").length,
});
const countBasis = (
items: readonly ApplicationVersionComparisonResult["items"][number][],
basis: ApplicationVersionComparisonResult["items"][number]["match"]["basis"],
): number => items.filter(({ match }) => match.basis === basis).length;
type ComparisonOmissions = ApplicationVersionComparisonResult["coverage"];
type ComparisonOmissionCounts = Pick<
ComparisonOmissions,
"left_graph_omitted_count" | "right_graph_omitted_count"
>;
const comparisonCoverage = (
input: ApplicationVersionComparisonProjectionInput,
omissions: ComparisonOmissionCounts,
): ApplicationVersionComparisonResult["coverage"] => {
const context = {
left_graph_status: input.left.graph.coverage.status,
right_graph_status: input.right.graph.coverage.status,
};
const sourceGraphsComplete =
input.left.graph.coverage.status === "complete" &&
input.right.graph.coverage.status === "complete";
const sourceGraphsTruncated =
input.left.graph.coverage.truncated || input.right.graph.coverage.truncated;
return {
...context,
...omissions,
status: sourceGraphsComplete
? "complete-within-inputs"
: sourceGraphsTruncated
? "truncated"
: "partial",
};
};
const comparisonLimitations = (
input: ApplicationVersionComparisonProjectionInput,
): string[] =>
uniqueSorted([
"Application comparison never uses bundler module ordinals as persistent identity and performs no fuzzy pairing.",
"Exact digest equality proves byte identity only; source-map, structural-fingerprint, and semantic-key matches retain inferred confidence.",
"Minified names and chunk locations are not assumed stable across versions.",
"The comparison reads retained graphs and Evidence only; it does not execute either application.",
"Native Evidence is linked only by exact subject digest; provider snapshot reuse remains target/provider/profile exact.",
...(input.left.graph.coverage.status === "complete" &&
input.right.graph.coverage.status === "complete"
? []
: [
"At least one source graph is incomplete; unmatched entities on the opposite side remain unknown rather than added or removed.",
]),
]);
@@ -0,0 +1,216 @@
import { z } from "zod";
import { emptyArraySchema } from "../emptyArraySchema.js";
import { evidenceSchema } from "../evidence.js";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
import { prefixedDigestSchema } from "../digests.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const nodeIdSchema = prefixedDigestSchema("jag_node");
const textSchema = z.string().min(1);
/** Two authenticated application versions and their native observations. */
export const compareApplicationVersionsInputSchema = z
.strictObject({
left: evidenceSchema,
right: evidenceSchema,
left_native_observations: z.array(evidenceSchema).default([]),
right_native_observations: z.array(evidenceSchema).default([]),
})
.superRefine((input, context) => {
if (input.left.evidence_id === input.right.evidence_id)
context.addIssue({
code: "custom",
path: ["right"],
message: "Application version Evidence must be distinct",
});
for (const side of [
"left_native_observations",
"right_native_observations",
] as const) {
const ids = input[side].map(({ evidence_id: id }) => id);
if (new Set(ids).size !== ids.length)
context.addIssue({
code: "custom",
path: [side],
message: "Native observations must be unique on each side",
});
}
});
const emptyCandidateNodesSchema = emptyArraySchema;
const candidateNodesSchema = z.tuple([nodeIdSchema]).rest(nodeIdSchema);
const exactMatchSchema = z.strictObject({
status: z.literal("matched"),
basis: z.enum([
"exact-node-identity",
"exact-content-digest",
"exact-module-source-digest",
]),
confidence: z.literal("exact"),
candidate_left_node_ids: emptyCandidateNodesSchema,
candidate_right_node_ids: emptyCandidateNodesSchema,
});
const sourceMapMatchSchema = z.strictObject({
status: z.literal("matched"),
basis: z.literal("source-map-identity"),
confidence: z.literal("high"),
candidate_left_node_ids: emptyCandidateNodesSchema,
candidate_right_node_ids: emptyCandidateNodesSchema,
});
const inferredMatchSchema = z.strictObject({
status: z.literal("matched"),
basis: z.enum(["structural-fingerprint", "semantic-key"]),
confidence: z.literal("medium"),
candidate_left_node_ids: emptyCandidateNodesSchema,
candidate_right_node_ids: emptyCandidateNodesSchema,
});
const matchedItemMatchSchema = z.union([
exactMatchSchema,
sourceMapMatchSchema,
inferredMatchSchema,
]);
const unmatchedItemMatchSchema = z.strictObject({
status: z.literal("unmatched"),
basis: z.literal("none"),
confidence: z.literal("unknown"),
candidate_left_node_ids: emptyCandidateNodesSchema,
candidate_right_node_ids: emptyCandidateNodesSchema,
});
const leftAmbiguousMatchSchema = z.strictObject({
status: z.literal("ambiguous"),
basis: z.literal("none"),
confidence: z.literal("unknown"),
candidate_left_node_ids: emptyCandidateNodesSchema,
candidate_right_node_ids: candidateNodesSchema,
});
const rightAmbiguousMatchSchema = z.strictObject({
status: z.literal("ambiguous"),
basis: z.literal("none"),
confidence: z.literal("unknown"),
candidate_left_node_ids: candidateNodesSchema,
candidate_right_node_ids: emptyCandidateNodesSchema,
});
const comparisonItemContextShape = {
item_id: prefixedDigestSchema("javc_item"),
node_kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
dimensions: z.array(
z.enum([
"content",
"location",
"properties",
"relationships",
"availability",
"coverage",
]),
),
evidence_links: z.array(evidenceIdSchema).min(2),
limitations: z.array(textSchema),
};
const comparisonItemSchema = z.union([
z.strictObject({
...comparisonItemContextShape,
status: z.enum(["unchanged", "changed", "unknown"]),
left_node_id: nodeIdSchema,
right_node_id: nodeIdSchema,
match: matchedItemMatchSchema,
}),
z.strictObject({
...comparisonItemContextShape,
status: z.enum(["removed", "unknown"]),
left_node_id: nodeIdSchema,
right_node_id: z.null(),
match: unmatchedItemMatchSchema,
}),
z.strictObject({
...comparisonItemContextShape,
status: z.enum(["added", "unknown"]),
left_node_id: z.null(),
right_node_id: nodeIdSchema,
match: unmatchedItemMatchSchema,
}),
z.strictObject({
...comparisonItemContextShape,
status: z.literal("unknown"),
left_node_id: nodeIdSchema,
right_node_id: z.null(),
match: leftAmbiguousMatchSchema,
}),
z.strictObject({
...comparisonItemContextShape,
status: z.literal("unknown"),
left_node_id: z.null(),
right_node_id: nodeIdSchema,
match: rightAmbiguousMatchSchema,
}),
]);
const comparisonCoverageSchema = z.strictObject({
left_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]),
right_graph_status: z.enum(["complete", "partial", "unknown", "unavailable"]),
left_graph_omitted_count: z.number().int().min(0).nullable(),
right_graph_omitted_count: z.number().int().min(0).nullable(),
status: z.enum(["complete-within-inputs", "partial", "truncated"]),
});
/** Tiered module/entity matching plus its complete cross-version change graph. */
export const applicationVersionComparisonResultSchema = z
.strictObject({
comparison_id: prefixedDigestSchema("javc"),
left: z.strictObject({
evidence_id: evidenceIdSchema,
graph_id: prefixedDigestSchema("jag"),
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
}),
right: z.strictObject({
evidence_id: evidenceIdSchema,
graph_id: prefixedDigestSchema("jag"),
root_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
}),
summary: z.strictObject({
unchanged: z.number().int().min(0),
added: z.number().int().min(0),
removed: z.number().int().min(0),
changed: z.number().int().min(0),
unknown: z.number().int().min(0),
}),
matching: z.strictObject({
exact_node_identity: z.number().int().min(0),
exact_content_digest: z.number().int().min(0),
exact_module_source_digest: z.number().int().min(0),
source_map_identity: z.number().int().min(0),
structural_fingerprint: z.number().int().min(0),
semantic_key: z.number().int().min(0),
ambiguous: z.number().int().min(0),
unmatched: z.number().int().min(0),
}),
items: z.array(comparisonItemSchema),
graph: javascriptApplicationGraphSchema,
coverage: comparisonCoverageSchema,
evidence_links: z.array(evidenceIdSchema).min(2),
limitations: z.array(textSchema),
})
.superRefine((result, context) => {
const sourceGraphsComplete =
result.coverage.left_graph_status === "complete" &&
result.coverage.right_graph_status === "complete";
if (
(result.coverage.status === "complete-within-inputs") !==
sourceGraphsComplete
)
context.addIssue({
code: "custom",
path: ["coverage", "status"],
message: "Comparison coverage must match source graph completeness",
});
});
export type ApplicationVersionComparisonItem = z.infer<
typeof comparisonItemSchema
>;
export type ApplicationVersionComparisonResult = z.infer<
typeof applicationVersionComparisonResultSchema
>;
@@ -0,0 +1,460 @@
import {
absenceClaimable,
canonicalDigest,
canonicalJson,
} from "../comparisonSemantics.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import type { Evidence } from "../evidence.js";
import {
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import type { ApplicationVersionComparisonItem } from "./javascriptApplicationVersionComparisonSchemas.js";
import type {
ApplicationVersionMatchingProjection,
ApplicationVersionNodePair,
} from "./javascriptApplicationVersionKeys.js";
/** All classified entities and their complete ambiguity candidate sets. */
export interface ApplicationVersionItemProjection {
readonly items: ApplicationVersionComparisonItem[];
}
interface ItemContext {
readonly leftGraph: JavaScriptApplicationGraph;
readonly rightGraph: JavaScriptApplicationGraph;
readonly leftEvidenceId: string;
readonly rightEvidenceId: string;
readonly leftNativeEvidence: readonly Evidence[];
readonly rightNativeEvidence: readonly Evidence[];
readonly pairByLeft: ReadonlyMap<string, string>;
readonly pairByRight: ReadonlyMap<string, string>;
}
type OneSidedNode =
| {
readonly left: ApplicationNode;
readonly right?: never;
readonly candidateRightNodeIds: readonly string[];
readonly candidateLeftNodeIds?: never;
}
| {
readonly left?: never;
readonly right: ApplicationNode;
readonly candidateRightNodeIds?: never;
readonly candidateLeftNodeIds: readonly string[];
};
type ComparisonItemSemantic<
Item extends ApplicationVersionComparisonItem =
ApplicationVersionComparisonItem,
> = Item extends ApplicationVersionComparisonItem
? Omit<Item, "item_id">
: never;
/** Classify matched, unmatched, and ambiguous nodes without inventing absence. */
export const classifyJavaScriptApplicationVersions = (
matching: ApplicationVersionMatchingProjection,
context: Omit<ItemContext, "pairByLeft" | "pairByRight">,
): ApplicationVersionItemProjection => {
const pairByLeft = new Map(
matching.pairs.map(({ left, right }) => [
left.node_id,
`pair:${left.node_id}:${right.node_id}`,
]),
);
const pairByRight = new Map(
matching.pairs.map(({ left, right }) => [
right.node_id,
`pair:${left.node_id}:${right.node_id}`,
]),
);
const fullContext: ItemContext = { ...context, pairByLeft, pairByRight };
const leftItems = matching.unmatchedLeft.map((node) => {
const candidates = matching.candidatesForLeft.get(node.node_id) ?? [];
return unmatchedItem(
{
left: node,
candidateRightNodeIds: candidates,
},
fullContext,
);
});
const rightItems = matching.unmatchedRight.map((node) => {
const candidates = matching.candidatesForRight.get(node.node_id) ?? [];
return unmatchedItem(
{
right: node,
candidateLeftNodeIds: candidates,
},
fullContext,
);
});
return {
items: [
...matching.pairs.map((pair) => matchedItem(pair, fullContext)),
...leftItems,
...rightItems,
].sort((left, right) => compareCodePoints(left.item_id, right.item_id)),
};
};
const matchedItem = (
pair: ApplicationVersionNodePair,
context: ItemContext,
): ApplicationVersionComparisonItem => {
const dimensions = changedDimensions(pair, context);
const complete = graphsComplete(context);
const observedChange = dimensions.some((dimension) =>
["content", "location", "properties"].includes(dimension),
);
const status: ApplicationVersionComparisonItem["status"] =
observedChange || (complete && dimensions.length > 0)
? "changed"
: complete
? "unchanged"
: "unknown";
const finalDimensions =
status === "unknown" && !dimensions.includes("coverage")
? [...dimensions, "coverage" as const]
: dimensions;
const semantic: ComparisonItemSemantic = {
status,
node_kind: pair.left.kind,
left_node_id: pair.left.node_id,
right_node_id: pair.right.node_id,
match: matchedMatch(pair),
dimensions: finalDimensions,
evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
limitations: pairLimitations(pair, status),
};
return itemWithId(semantic);
};
const unmatchedItem = (
member: OneSidedNode,
context: ItemContext,
): ApplicationVersionComparisonItem =>
member.left === undefined
? rightOnlyItem(member.right, member.candidateLeftNodeIds, context)
: leftOnlyItem(member.left, member.candidateRightNodeIds, context);
const leftOnlyItem = (
node: ApplicationNode,
candidateNodeIds: readonly string[],
context: ItemContext,
): ApplicationVersionComparisonItem => {
const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
const common = {
node_kind: node.kind,
evidence_links: itemEvidenceLinks(node, undefined, context),
};
if (firstCandidate !== undefined)
return itemWithId({
...common,
status: "unknown",
left_node_id: node.node_id,
right_node_id: null,
match: {
status: "ambiguous",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [],
candidate_right_node_ids: [firstCandidate, ...remainingCandidates],
},
dimensions: ["availability"],
limitations: [AMBIGUOUS_MATCH_LIMITATION],
});
const absenceObserved = absenceClaimable(context.rightGraph.coverage);
return itemWithId({
...common,
status: absenceObserved ? "removed" : "unknown",
left_node_id: node.node_id,
right_node_id: null,
match: unmatchedMatch(),
dimensions: absenceObserved
? ["availability"]
: ["availability", "coverage"],
limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
});
};
const rightOnlyItem = (
node: ApplicationNode,
candidateNodeIds: readonly string[],
context: ItemContext,
): ApplicationVersionComparisonItem => {
const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
const common = {
node_kind: node.kind,
evidence_links: itemEvidenceLinks(undefined, node, context),
};
if (firstCandidate !== undefined)
return itemWithId({
...common,
status: "unknown",
left_node_id: null,
right_node_id: node.node_id,
match: {
status: "ambiguous",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [firstCandidate, ...remainingCandidates],
candidate_right_node_ids: [],
},
dimensions: ["availability"],
limitations: [AMBIGUOUS_MATCH_LIMITATION],
});
const absenceObserved = absenceClaimable(context.leftGraph.coverage);
return itemWithId({
...common,
status: absenceObserved ? "added" : "unknown",
left_node_id: null,
right_node_id: node.node_id,
match: unmatchedMatch(),
dimensions: absenceObserved
? ["availability"]
: ["availability", "coverage"],
limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
});
};
const matchedMatch = (
pair: ApplicationVersionNodePair,
): Extract<
ApplicationVersionComparisonItem["match"],
{ readonly status: "matched" }
> => {
const candidates: {
readonly candidate_left_node_ids: [];
readonly candidate_right_node_ids: [];
} = {
candidate_left_node_ids: [],
candidate_right_node_ids: [],
};
switch (pair.basis) {
case "exact-node-identity":
case "exact-content-digest":
case "exact-module-source-digest":
return {
status: "matched",
basis: pair.basis,
confidence: "exact",
...candidates,
};
case "source-map-identity":
return {
status: "matched",
basis: pair.basis,
confidence: "high",
...candidates,
};
case "structural-fingerprint":
case "semantic-key":
return {
status: "matched",
basis: pair.basis,
confidence: "medium",
...candidates,
};
}
};
const unmatchedMatch = (): Extract<
ApplicationVersionComparisonItem["match"],
{ readonly status: "unmatched" }
> => ({
status: "unmatched",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [],
candidate_right_node_ids: [],
});
const AMBIGUOUS_MATCH_LIMITATION =
"Multiple nodes share the same permitted match key; no cross-version pair was selected.";
const INCOMPLETE_GRAPH_LIMITATION =
"The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.";
const changedDimensions = (
pair: ApplicationVersionNodePair,
context: ItemContext,
): ApplicationVersionComparisonItem["dimensions"] => {
const dimensions: ApplicationVersionComparisonItem["dimensions"] = [];
const leftContent = contentIdentity(pair.left);
const rightContent = contentIdentity(pair.right);
if (
leftContent !== null &&
rightContent !== null &&
leftContent !== rightContent
)
dimensions.push("content");
if (
canonicalJson(locations(pair.left)) !== canonicalJson(locations(pair.right))
)
dimensions.push("location");
if (
canonicalJson(properties(pair.left)) !==
canonicalJson(properties(pair.right))
)
dimensions.push("properties");
if (
relationshipSignature(pair.left, "left", context) !==
relationshipSignature(pair.right, "right", context)
)
dimensions.push("relationships");
return dimensions;
};
const contentIdentity = (node: ApplicationNode): string | null => {
if (node.identity.strategy === "content-digest")
return `content:${node.identity.sha256}`;
if (node.kind === "javascript-module")
return stringProperty(node, "source_sha256");
if (
node.kind === "source-module" &&
node.identity.strategy === "source-map-original"
)
return node.identity.source_sha256;
return null;
};
const locations = (node: ApplicationNode) =>
node.observations
.map(({ evidence }) =>
evidence.location.available ? evidence.location.value : evidence.location,
)
.sort((left, right) =>
compareCodePoints(canonicalJson(left), canonicalJson(right)),
);
const properties = (node: ApplicationNode) =>
node.observations
.map(({ label, properties: values }) => ({ label, properties: values }))
.sort((left, right) =>
compareCodePoints(canonicalJson(left), canonicalJson(right)),
);
const relationshipSignature = (
node: ApplicationNode,
side: "left" | "right",
context: ItemContext,
): string => {
const graph = side === "left" ? context.leftGraph : context.rightGraph;
const paired = side === "left" ? context.pairByLeft : context.pairByRight;
const nodeById = new Map(graph.nodes.map((value) => [value.node_id, value]));
const signatures = graph.edges.flatMap((edge) => {
if (edge.source_node_id === node.node_id)
return [
edgeSignature({
direction: "out",
relation: edge.relation,
neighborId: edge.target_node_id,
paired,
nodeById,
}),
];
if (edge.target_node_id === node.node_id)
return [
edgeSignature({
direction: "in",
relation: edge.relation,
neighborId: edge.source_node_id,
paired,
nodeById,
}),
];
return [];
});
return canonicalJson(signatures.sort(compareCodePoints));
};
interface EdgeSignatureContext {
readonly direction: "in" | "out";
readonly relation: ApplicationEdge["relation"];
readonly neighborId: string;
readonly paired: ReadonlyMap<string, string>;
readonly nodeById: ReadonlyMap<string, ApplicationNode>;
}
const edgeSignature = (context: EdgeSignatureContext): string => {
const mapped = context.paired.get(context.neighborId);
const neighbor = context.nodeById.get(context.neighborId);
return `${context.direction}\0${context.relation}\0${mapped ?? `unmatched:${neighbor?.kind ?? "unknown"}`}`;
};
const itemEvidenceLinks = (
left: ApplicationNode | undefined,
right: ApplicationNode | undefined,
context: ItemContext,
): string[] =>
[
...new Set([
context.leftEvidenceId,
context.rightEvidenceId,
...nativeLinks(left, context.leftNativeEvidence),
...nativeLinks(right, context.rightNativeEvidence),
]),
].sort(compareCodePoints);
const nativeLinks = (
node: ApplicationNode | undefined,
evidence: readonly Evidence[],
): string[] => {
const digest =
node === undefined
? null
: contentIdentity(node)?.replace(/^content:/u, "");
return digest === null
? []
: evidence
.filter(({ subject }) => subject?.digest.sha256 === digest)
.map(({ evidence_id: id }) => id);
};
const pairLimitations = (
pair: ApplicationVersionNodePair,
status: ApplicationVersionComparisonItem["status"],
): string[] => [
...(pair.basis === "structural-fingerprint"
? [
"Structural fingerprint equality is rename-resistant inference; it is not byte identity or proof of semantic equivalence.",
]
: []),
...(pair.basis === "source-map-identity"
? [
"Source-map original names identify a candidate source lineage; changed or unavailable source content remains explicit.",
]
: []),
...(pair.basis === "semantic-key"
? [
"Semantic-key pairing is a deterministic inference and is never promoted to exact identity.",
]
: []),
...(status === "unknown"
? ["Incomplete graph coverage prevents a complete node-level conclusion."]
: []),
];
const itemWithId = <Semantic extends ComparisonItemSemantic>(
semantic: Semantic,
): Semantic & { readonly item_id: string } => ({
...semantic,
item_id: `javc_item_${canonicalDigest(semantic, "Application version item")}`,
});
const stringProperty = (node: ApplicationNode, key: string): string | null => {
const values = [
...new Set(
node.observations
.map(({ properties: values }) => values[key])
.filter((value): value is string => typeof value === "string"),
),
];
return values.length === 1 ? (values[0] ?? null) : null;
};
const graphsComplete = (context: ItemContext): boolean =>
absenceClaimable(context.leftGraph.coverage) &&
absenceClaimable(context.rightGraph.coverage);
@@ -0,0 +1,317 @@
import { compareCodePoints } from "../canonicalOrdering.js";
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
import type { JsonValue } from "../jsonValue.js";
/** One deterministic one-to-one match between two graph versions. */
type ApplicationVersionPairMatch =
| {
readonly basis:
| "exact-node-identity"
| "exact-content-digest"
| "exact-module-source-digest";
readonly confidence: "exact";
}
| {
readonly basis: "source-map-identity";
readonly confidence: "high";
}
| {
readonly basis: "structural-fingerprint" | "semantic-key";
readonly confidence: "medium";
};
export type ApplicationVersionNodePair = {
readonly left: ApplicationNode;
readonly right: ApplicationNode;
} & ApplicationVersionPairMatch;
/** Matched nodes plus ambiguity candidates that were never forced into pairs. */
export interface ApplicationVersionMatchingProjection {
readonly pairs: ApplicationVersionNodePair[];
readonly unmatchedLeft: ApplicationNode[];
readonly unmatchedRight: ApplicationNode[];
readonly candidatesForLeft: ReadonlyMap<string, readonly string[]>;
readonly candidatesForRight: ReadonlyMap<string, readonly string[]>;
}
interface MatchTier {
readonly match: ApplicationVersionPairMatch;
readonly key: (node: ApplicationNode) => string | null;
}
const matchTiers = (): readonly MatchTier[] => [
{
match: { basis: "exact-content-digest", confidence: "exact" },
key: contentDigestKey,
},
{
match: { basis: "exact-module-source-digest", confidence: "exact" },
key: moduleSourceDigestKey,
},
{
match: { basis: "exact-node-identity", confidence: "exact" },
key: nodeIdentityKey,
},
{
match: { basis: "source-map-identity", confidence: "high" },
key: sourceMapKey,
},
{
match: { basis: "structural-fingerprint", confidence: "medium" },
key: structuralFingerprintKey,
},
{
match: { basis: "semantic-key", confidence: "medium" },
key: semanticKey,
},
];
/** Apply ordered, unique-only matching tiers without fuzzy pairing. */
export const matchJavaScriptApplicationVersions = (
leftNodes: readonly ApplicationNode[],
rightNodes: readonly ApplicationNode[],
): ApplicationVersionMatchingProjection => {
const left = new Map(leftNodes.map((node) => [node.node_id, node]));
const right = new Map(rightNodes.map((node) => [node.node_id, node]));
const leftCandidates = new Map<string, Set<string>>();
const rightCandidates = new Map<string, Set<string>>();
const pairs: ApplicationVersionNodePair[] = [];
for (const tier of matchTiers())
applyTier({ left, right, pairs, leftCandidates, rightCandidates, tier });
const remainingLeft = sortedNodes(left.values());
const remainingRight = sortedNodes(right.values());
const leftIds = new Set(remainingLeft.map(({ node_id: id }) => id));
const rightIds = new Set(remainingRight.map(({ node_id: id }) => id));
return {
pairs: pairs.sort((a, b) =>
compareCodePoints(
`${a.left.node_id}\0${a.right.node_id}`,
`${b.left.node_id}\0${b.right.node_id}`,
),
),
unmatchedLeft: remainingLeft,
unmatchedRight: remainingRight,
candidatesForLeft: filteredCandidates(leftCandidates, rightIds),
candidatesForRight: filteredCandidates(rightCandidates, leftIds),
};
};
interface TierContext {
readonly left: Map<string, ApplicationNode>;
readonly right: Map<string, ApplicationNode>;
readonly pairs: ApplicationVersionNodePair[];
readonly leftCandidates: Map<string, Set<string>>;
readonly rightCandidates: Map<string, Set<string>>;
readonly tier: MatchTier;
}
const applyTier = (context: TierContext): void => {
const leftByKey = nodesByKey(context.left.values(), context.tier.key);
const rightByKey = nodesByKey(context.right.values(), context.tier.key);
for (const key of [...leftByKey.keys()].sort(compareCodePoints)) {
const leftGroup = leftByKey.get(key) ?? [];
const rightGroup = rightByKey.get(key) ?? [];
if (rightGroup.length === 0) continue;
recordCandidates(
leftGroup,
rightGroup,
context.leftCandidates,
context.rightCandidates,
);
if (leftGroup.length !== 1 || rightGroup.length !== 1) continue;
const leftNode = leftGroup[0];
const rightNode = rightGroup[0];
if (leftNode === undefined || rightNode === undefined) continue;
context.pairs.push({
left: leftNode,
right: rightNode,
...context.tier.match,
});
context.left.delete(leftNode.node_id);
context.right.delete(rightNode.node_id);
}
};
const nodesByKey = (
nodes: Iterable<ApplicationNode>,
keyFor: (node: ApplicationNode) => string | null,
): Map<string, ApplicationNode[]> => {
const output = new Map<string, ApplicationNode[]>();
for (const node of nodes) {
const key = keyFor(node);
if (key === null) continue;
output.set(key, [...(output.get(key) ?? []), node]);
}
return output;
};
const recordCandidates = (
left: readonly ApplicationNode[],
right: readonly ApplicationNode[],
leftCandidates: Map<string, Set<string>>,
rightCandidates: Map<string, Set<string>>,
): void => {
for (const leftNode of left) {
const candidates =
leftCandidates.get(leftNode.node_id) ?? new Set<string>();
for (const rightNode of right) candidates.add(rightNode.node_id);
leftCandidates.set(leftNode.node_id, candidates);
}
for (const rightNode of right) {
const candidates =
rightCandidates.get(rightNode.node_id) ?? new Set<string>();
for (const leftNode of left) candidates.add(leftNode.node_id);
rightCandidates.set(rightNode.node_id, candidates);
}
};
const filteredCandidates = (
candidates: ReadonlyMap<string, ReadonlySet<string>>,
retained: ReadonlySet<string>,
): ReadonlyMap<string, readonly string[]> =>
new Map(
[...candidates.entries()].flatMap(([nodeId, values]) => {
const filtered = [...values]
.filter((value) => retained.has(value))
.sort(compareCodePoints);
return filtered.length === 0 ? [] : [[nodeId, filtered] as const];
}),
);
const nodeIdentityKey = (node: ApplicationNode): string =>
`node\0${node.kind}\0${node.node_id}`;
const contentDigestKey = (node: ApplicationNode): string | null =>
node.identity.strategy === "content-digest"
? `content\0${node.kind}\0${node.identity.sha256}`
: null;
const moduleSourceDigestKey = (node: ApplicationNode): string | null => {
if (node.kind !== "javascript-module") return null;
const value = uniqueStringProperty(node, "source_sha256");
return value === null ? null : `module-source\0${node.kind}\0${value}`;
};
const sourceMapKey = (node: ApplicationNode): string | null =>
node.kind === "source-module" &&
node.identity.strategy === "source-map-original"
? `source-map\0${node.identity.original_source}`
: null;
const structuralFingerprintKey = (node: ApplicationNode): string | null => {
if (node.kind !== "javascript-module") return null;
const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
const algorithm = uniqueStringProperty(
node,
"structural_fingerprint_algorithm",
);
return digest === null || algorithm === null
? null
: `structural\0${node.kind}\0${algorithm}\0${digest}`;
};
const semanticKey = (node: ApplicationNode): string | null => {
if (
[
"javascript-module",
"javascript-chunk",
"runtime-script-instance",
"unknown",
].includes(node.kind)
)
return null;
const properties = firstProperties(node);
const value = semanticValue(node, properties);
return value === null ? null : `semantic\0${node.kind}\0${value}`;
};
const semanticValue = (
node: ApplicationNode,
properties: Readonly<Record<string, JsonValue>>,
): string | null => {
if (node.kind === "endpoint") {
const kind = nonEmptyString(properties.endpoint_kind);
const value = exactString(properties.value);
return kind === null || value === null ? null : `${kind}\0${value}`;
}
if (node.kind === "storage")
return joined(
properties.storage_kind,
properties.name ?? properties.mechanism,
);
if (node.kind === "ipc-channel")
return properties.resolution === "dynamic"
? null
: (exactString(properties.channel) ?? firstLabel(node));
if (node.kind === "context-bridge-api")
return (
firstLabel(node) ??
exactString(properties.api_key) ??
nonEmptyString(properties.api_name)
);
if (node.kind === "native-export")
return (
joined(
properties.specifier,
stringList(properties.requested_members).join(","),
) ?? firstLabel(node)
);
if (
[
"electron-main",
"electron-preload",
"electron-renderer",
"electron-utility",
].includes(node.kind)
)
return joined(properties.declared_path, properties.resolved_path);
if (node.kind === "package") return nonEmptyString(properties.name);
return canonicalPath(node) ?? nonEmptyString(properties.path);
};
const canonicalPath = (node: ApplicationNode): string | null =>
node.identity.strategy === "canonical-path" ? node.identity.path : null;
const firstProperties = (node: ApplicationNode) =>
node.observations[0]?.properties ?? {};
const firstLabel = (node: ApplicationNode): string | null =>
node.observations.find(({ label }) => label !== null)?.label ?? null;
const uniqueStringProperty = (
node: ApplicationNode,
name: string,
): string | null => {
const values = [
...new Set(
node.observations
.map(({ properties }) => properties[name])
.filter((value): value is string => typeof value === "string"),
),
];
return values.length === 1 ? (values[0] ?? null) : null;
};
const joined = (...values: readonly unknown[]): string | null => {
const strings = values.map(nonEmptyString);
return strings.some((value) => value === null) ? null : strings.join("\0");
};
const nonEmptyString = (value: unknown): string | null =>
typeof value === "string" && value !== "" ? value : null;
/** A literal value such as `ipcMain.handle("")` keeps its exact empty text. */
const exactString = (value: unknown): string | null =>
typeof value === "string" ? value : null;
const stringList = (value: unknown): string[] =>
Array.isArray(value)
? value
.filter((item): item is string => typeof item === "string")
.sort(compareCodePoints)
: [];
const sortedNodes = (nodes: Iterable<ApplicationNode>): ApplicationNode[] =>
[...nodes].sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
);
@@ -0,0 +1,16 @@
import { parse } from "@babel/parser";
import { describe, expect, it } from "vitest";
import { fingerprintJavaScriptAst } from "./javascriptAstFingerprint.js";
describe("JavaScript AST fingerprints", () => {
it("includes complete literal values in the fingerprint", () => {
const prefix = "x".repeat(1_024);
const left = parse(`const value = ${JSON.stringify(`${prefix}left`)};`);
const right = parse(`const value = ${JSON.stringify(`${prefix}right`)};`);
expect(fingerprintJavaScriptAst(left)).not.toBe(
fingerprintJavaScriptAst(right),
);
});
});
@@ -0,0 +1,126 @@
import { createHash } from "node:crypto";
import * as t from "@babel/types";
import { compareCodePoints } from "../canonicalOrdering.js";
import { propertyName } from "./javascriptAstValues.js";
import { stringValue } from "./javascriptStaticAnalysisHelpers.js";
/** Static CommonJS export names. */
export interface StaticExports {
readonly values: readonly string[];
}
/** Derive a rename-resistant syntax fingerprint without code execution. */
export const fingerprintJavaScriptAst = (node: t.Node): string => {
const tokens: string[] = [];
t.traverseFast(node, (current) => {
tokens.push(...semanticTokens(current));
return undefined;
});
return createHash("sha256").update(JSON.stringify(tokens)).digest("hex");
};
/** Collect statically declared CommonJS/bundler export names from one factory. */
export const collectJavaScriptExports = (node: t.Node): StaticExports => {
const exports = new Set<string>();
t.traverseFast(node, (current) => {
if (t.isAssignmentExpression(current))
collectAssignmentExports(current.left, current.right, exports);
if (t.isCallExpression(current)) collectCallExports(current, exports);
return undefined;
});
return {
values: [...exports].sort(compareCodePoints),
};
};
const semanticTokens = (node: t.Node): string[] => {
const tokens = [`node:${node.type}`];
if (t.isStringLiteral(node)) tokens.push(`string:${node.value}`);
else if (t.isNumericLiteral(node))
tokens.push(`number:${String(node.value)}`);
else if (t.isBooleanLiteral(node))
tokens.push(`boolean:${String(node.value)}`);
else if (t.isRegExpLiteral(node))
tokens.push(`regexp:${node.pattern}/${node.flags}`);
else if (t.isBinaryExpression(node) || t.isLogicalExpression(node))
tokens.push(`operator:${node.operator}`);
else if (t.isUnaryExpression(node) || t.isUpdateExpression(node))
tokens.push(`operator:${node.operator}`);
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
const property = propertyName(node.property);
if (property !== "") tokens.push(`property:${property}`);
}
if ((t.isObjectProperty(node) || t.isObjectMethod(node)) && !node.computed) {
const key = propertyName(node.key);
if (key !== "") tokens.push(`key:${key}`);
}
return tokens;
};
const collectAssignmentExports = (
left: t.LVal | t.OptionalMemberExpression,
right: t.Expression,
output: Set<string>,
): void => {
const path = memberPath(left);
if (path === "exports" || path === "module.exports") {
if (t.isObjectExpression(right)) collectObjectKeys(right, output);
else addExport(output, "default");
return;
}
if (path.startsWith("exports."))
addExport(output, path.slice("exports.".length));
if (path.startsWith("module.exports."))
addExport(output, path.slice("module.exports.".length));
};
const collectCallExports = (
call: t.CallExpression,
output: Set<string>,
): void => {
const callee = memberPath(call.callee);
if (callee === "Object.defineProperty") {
const target = memberPath(call.arguments[0]);
const name = stringValue(call.arguments[1]);
if ((target === "exports" || target === "module.exports") && name)
addExport(output, name);
}
if (!callee.endsWith(".d")) return;
const target = memberPath(call.arguments[0]);
const declarations = call.arguments[1];
if (
(target === "exports" || target === "module.exports") &&
t.isObjectExpression(declarations)
)
collectObjectKeys(declarations, output);
};
const collectObjectKeys = (
object: t.ObjectExpression,
output: Set<string>,
): void => {
for (const property of object.properties) {
if (!t.isObjectProperty(property) && !t.isObjectMethod(property)) continue;
const name = propertyName(property.key);
if (name !== "") addExport(output, name);
}
};
const addExport = (output: Set<string>, name: string): void => {
output.add(name);
};
const memberPath = (node: t.Node | null | undefined): string => {
if (node === undefined || node === null) return "";
if (t.isIdentifier(node) || t.isPrivateName(node))
return t.isIdentifier(node) ? node.name : "";
if (t.isThisExpression(node)) return "this";
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
const object = t.isNode(node.object) ? memberPath(node.object) : "";
const property = propertyName(node.property);
return object === "" ? property : `${object}.${property}`;
}
return "";
};
@@ -0,0 +1,33 @@
import * as t from "@babel/types";
/** Read an identifier or literal property name without evaluating syntax. */
export const propertyName = (node: t.Node): string => {
if (t.isIdentifier(node)) return node.name;
if (t.isStringLiteral(node) || t.isNumericLiteral(node))
return String(node.value);
return "";
};
/** Read a property name only when its syntax commits to one exact key. */
export const semanticStaticPropertyName = (
property: t.Node,
computed: boolean,
): string => semanticStaticPropertyKey(property, computed) ?? "";
/** Read an exact property key, preserving the legal empty-string key. */
export const semanticStaticPropertyKey = (
property: t.Node,
computed: boolean,
): string | null => {
if (t.isStringLiteral(property) || t.isNumericLiteral(property))
return String(property.value);
return !computed && t.isIdentifier(property) ? property.name : null;
};
/**
* Display an exact JavaScript string as nonempty label text. Graph labels and
* artifact-local keys are nonempty, so the legal empty value is shown as `""`;
* producers keep the exact value in their properties.
*/
export const javascriptDisplayText = (value: string): string =>
value === "" ? '""' : value;
@@ -0,0 +1,211 @@
import { uniqueSorted } from "../canonicalOrdering.js";
import { digestExportShapeValue } from "./javascriptExportShapeComparisonIdentity.js";
import {
javaScriptExportShapeComparisonResultSchema,
type JavaScriptExportShapeComparisonChange,
type JavaScriptExportShapeComparisonResult,
} from "./javascriptExportShapeComparisonSchemas.js";
import {
retainJavaScriptExportShapes,
selectJavaScriptExport,
type JavaScriptExportShapeSideInput,
type RetainedJavaScriptExportShapes,
type SelectedJavaScriptExport,
} from "./javascriptExportShapeSelection.js";
import {
buildJavaScriptExportShapeChanges,
compareJavaScriptExportShapeChanges,
hasPartialJavaScriptExportPropertyCoverage,
pairJavaScriptExportShapeVariants,
type JavaScriptExportShapePairing,
} from "./javascriptExportShapeVariants.js";
/** Pure comparison input after application-layer Evidence authentication. */
export interface JavaScriptExportShapeComparisonProjectionInput {
readonly left: JavaScriptExportShapeSideInput;
readonly right: JavaScriptExportShapeSideInput;
}
/** Compare exact selected export return shapes without executing JavaScript. */
export const compareJavaScriptExportShapes = (
input: JavaScriptExportShapeComparisonProjectionInput,
): JavaScriptExportShapeComparisonResult => {
const left = selectJavaScriptExport(input.left);
const right = selectJavaScriptExport(input.right);
const leftRetained = retainJavaScriptExportShapes(left);
const rightRetained = retainJavaScriptExportShapes(right);
const pairing = pairJavaScriptExportShapeVariants(
leftRetained.shapes,
rightRetained.shapes,
);
const evidenceLinks = evidencePair(
input.left.evidenceId,
input.right.evidenceId,
);
const allChanges = buildJavaScriptExportShapeChanges({
leftSelection: left,
rightSelection: right,
pairing,
leftShapes: leftRetained.shapes,
rightShapes: rightRetained.shapes,
evidenceLinks,
}).sort(compareJavaScriptExportShapeChanges);
const changes = allChanges;
const omittedChanges = 0;
const coverage = comparisonCoverage({
input,
left,
right,
leftRetained,
rightRetained,
pairing,
allChanges,
omittedChanges,
});
const limitations = comparisonLimitations(left, right, coverage.status);
const semantic = {
left: left.selection,
right: right.selection,
summary: summarize(allChanges),
changes,
coverage,
evidence_links: evidenceLinks,
limitations,
};
return javaScriptExportShapeComparisonResultSchema.parse({
...semantic,
comparison_id: `jesc_${digestExportShapeValue(semantic)}`,
});
};
interface CoverageInput {
readonly input: JavaScriptExportShapeComparisonProjectionInput;
readonly left: SelectedJavaScriptExport;
readonly right: SelectedJavaScriptExport;
readonly leftRetained: RetainedJavaScriptExportShapes;
readonly rightRetained: RetainedJavaScriptExportShapes;
readonly pairing: JavaScriptExportShapePairing;
readonly allChanges: readonly JavaScriptExportShapeComparisonChange[];
readonly omittedChanges: number;
}
const comparisonCoverage = (context: CoverageInput) => {
const leftSource = context.left.projection?.return_shape_coverage;
const rightSource = context.right.projection?.return_shape_coverage;
const omittedCandidates =
context.left.selection.omitted_candidates +
context.right.selection.omitted_candidates;
const truncated = comparisonTruncated(context, omittedCandidates);
const partial = comparisonPartial(context);
return {
status: truncated
? ("truncated" as const)
: partial
? ("partial" as const)
: ("complete-within-inputs" as const),
left_graph_status: context.input.left.graph.coverage.status,
right_graph_status: context.input.right.graph.coverage.status,
paired_variants: context.pairing.pairs.length,
unpaired_left_variants: context.pairing.unpairedLeft.length,
unpaired_right_variants: context.pairing.unpairedRight.length,
omitted_left_variants: context.leftRetained.omitted,
omitted_right_variants: context.rightRetained.omitted,
left_source_omitted_variants: leftSource?.omitted_return_sites ?? null,
right_source_omitted_variants: rightSource?.omitted_return_sites ?? null,
left_omitted_fields: leftSource?.omitted_fields ?? 0,
right_omitted_fields: rightSource?.omitted_fields ?? 0,
left_omitted_property_coverage: leftSource?.omitted_property_coverage ?? 0,
right_omitted_property_coverage:
rightSource?.omitted_property_coverage ?? 0,
omitted_candidates: omittedCandidates,
omitted_changes: context.omittedChanges,
};
};
const comparisonTruncated = (
context: CoverageInput,
omittedCandidates: number,
): boolean =>
context.leftRetained.omitted > 0 ||
context.rightRetained.omitted > 0 ||
omittedCandidates > 0 ||
context.omittedChanges > 0 ||
sourceProjectionTruncated(context.left) ||
sourceProjectionTruncated(context.right);
const sourceProjectionTruncated = (
selection: SelectedJavaScriptExport,
): boolean => {
const coverage = selection.projection?.return_shape_coverage;
if (coverage === undefined) return false;
return (
coverage.status === "truncated" ||
coverage.omitted_fields > 0 ||
coverage.omitted_property_coverage > 0 ||
coverage.projection_complete === false
);
};
const comparisonPartial = (context: CoverageInput): boolean =>
selectionPartial(context.left) ||
selectionPartial(context.right) ||
context.input.left.graph.coverage.status !== "complete" ||
context.input.right.graph.coverage.status !== "complete" ||
hasPartialJavaScriptExportPropertyCoverage(context.leftRetained.shapes) ||
hasPartialJavaScriptExportPropertyCoverage(context.rightRetained.shapes) ||
context.pairing.unpairedLeft.length > 0 ||
context.pairing.unpairedRight.length > 0 ||
context.allChanges.some(({ status }) => status === "unknown");
const selectionPartial = (selection: SelectedJavaScriptExport): boolean => {
const coverage = selection.projection?.return_shape_coverage;
return (
selection.selection.status !== "selected" ||
!selection.observationComplete ||
coverage?.status !== "complete" ||
coverage.projection_complete !== true
);
};
const comparisonLimitations = (
left: SelectedJavaScriptExport,
right: SelectedJavaScriptExport,
status: "complete-within-inputs" | "partial" | "truncated",
): string[] =>
uniqueSorted([
"Return shapes are inferred from inert syntax and do not prove runtime behavior.",
"Return variants are paired only by unique exact literal discriminants, never by source order.",
"Dynamic values, incomplete object coverage, and ambiguous variants remain unknown.",
"This static comparison cannot establish runtime semantics; run behavioral probes directly against the relevant application versions when that evidence is required.",
...left.limitations,
...right.limitations,
...(status === "truncated"
? [
"Comparison output or source return-shape recovery reached an explicit limit.",
]
: []),
...(status === "partial"
? [
"At least one selector, graph, return shape, or property boundary is incomplete.",
]
: []),
]);
const summarize = (
changes: readonly JavaScriptExportShapeComparisonChange[],
): JavaScriptExportShapeComparisonResult["summary"] => ({
added: countStatus(changes, "added"),
removed: countStatus(changes, "removed"),
changed: countStatus(changes, "changed"),
unknown: countStatus(changes, "unknown"),
});
const countStatus = (
changes: readonly JavaScriptExportShapeComparisonChange[],
status: JavaScriptExportShapeComparisonChange["status"],
): number => changes.filter((change) => change.status === status).length;
const evidencePair = (left: string, right: string): [string, string] => [
left,
right,
];
@@ -0,0 +1,17 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
/** Canonically encode one export-shape comparison value. */
export const canonicalExportShapeValue = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError(
"JavaScript export shape comparison could not canonicalize data",
);
return encoded;
};
/** Derive one deterministic SHA-256 comparison identifier component. */
export const digestExportShapeValue = (value: unknown): string =>
createHash("sha256").update(canonicalExportShapeValue(value)).digest("hex");
@@ -0,0 +1,157 @@
import { expect, it } from "vitest";
import {
javaScriptExportShapeComparisonResultSchema,
projectedExportReturnShapesSchema,
} from "./javascriptExportShapeComparisonSchemas.js";
const projectionWithField = (field: unknown) => ({
semantic_role: "export-return-shapes",
module_path: "index.js",
exported_name: "render",
callable_id: "callable:render",
callable_kind: "function",
static_return_shapes: [
{
source_range: {
start: { line: 1, column: 0 },
end: { line: 1, column: 10 },
},
value_status: "unknown",
fields: [field],
property_coverage: [],
},
],
return_shape_coverage: {
status: "partial",
retained_return_sites: 1,
omitted_return_sites: null,
omitted_fields: 0,
omitted_property_coverage: 0,
projection_complete: true,
},
});
it("parses projected fields into literal, union, or unknown values", () => {
expect(
projectedExportReturnShapesSchema.safeParse(
projectionWithField({
path: "/kind",
state: "unknown",
value: "invented",
reason: "Dynamic property",
}),
).success,
).toBe(false);
expect(
projectedExportReturnShapesSchema.safeParse(
projectionWithField({
path: "/kind",
state: "union",
value: ["success", "failure"],
reason: null,
}),
).success,
).toBe(true);
});
it("accepts every projected return site and field without presentation caps", () => {
const fields = Array.from({ length: 65 }, (_, index) => ({
path: `/field-${String(index)}`,
state: "literal",
value: index,
reason: null,
}));
const propertyCoverage = fields.map(({ path }) => ({
path,
status: "complete",
omitted: 0,
}));
const shapes = Array.from({ length: 33 }, () => ({
source_range: {
start: { line: 1, column: 0 },
end: { line: 1, column: 10 },
},
value_status: "object",
fields,
property_coverage: propertyCoverage,
}));
expect(
projectedExportReturnShapesSchema.parse({
...projectionWithField(fields[0]),
static_return_shapes: shapes,
return_shape_coverage: {
status: "complete",
retained_return_sites: shapes.length,
omitted_return_sites: 0,
omitted_fields: 0,
omitted_property_coverage: 0,
projection_complete: true,
},
}).static_return_shapes,
).toHaveLength(33);
});
it("accepts complete candidate and change inventories without page ceilings", () => {
const evidenceId = `ev_${"a".repeat(64)}`;
const graphId = `jag_${"b".repeat(64)}`;
const selector = {
evidence_id: evidenceId,
graph_id: graphId,
requested_module_path: "index.js",
requested_export_name: "render",
candidates: Array.from({ length: 1_001 }, (_, index) => ({
node_id: `jag_node_${index.toString(16).padStart(64, "0")}`,
module_path: "index.js",
export_name: "render",
matches_requested_module: true,
matches_requested_export: true,
})),
omitted_candidates: 0,
status: "missing",
selected_node_id: null,
};
const changes = Array.from({ length: 10_001 }, (_, index) => ({
change_id: `jesc_change_${index.toString(16).padStart(64, "0")}`,
status: "unknown",
path: `/field-${String(index)}`,
discriminant: null,
left: { availability: "absent" },
right: { availability: "absent" },
left_source_range: null,
right_source_range: null,
evidence_links: [evidenceId, `ev_${"c".repeat(64)}`],
limitations: [],
}));
expect(
javaScriptExportShapeComparisonResultSchema.parse({
comparison_id: `jesc_${"d".repeat(64)}`,
left: selector,
right: { ...selector, graph_id: `jag_${"e".repeat(64)}` },
summary: { added: 0, removed: 0, changed: 0, unknown: changes.length },
changes,
coverage: {
status: "complete-within-inputs",
left_graph_status: "complete",
right_graph_status: "complete",
paired_variants: 0,
unpaired_left_variants: 0,
unpaired_right_variants: 0,
omitted_left_variants: 0,
omitted_right_variants: 0,
left_source_omitted_variants: 0,
right_source_omitted_variants: 0,
left_omitted_fields: 0,
right_omitted_fields: 0,
left_omitted_property_coverage: 0,
right_omitted_property_coverage: 0,
omitted_candidates: 0,
omitted_changes: 0,
},
evidence_links: [evidenceId, `ev_${"c".repeat(64)}`],
limitations: [],
}).changes,
).toHaveLength(10_001);
});
@@ -0,0 +1,297 @@
import { z } from "zod";
import { evidenceSchema } from "../evidence.js";
import { prefixedDigestSchema } from "../digests.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const graphIdSchema = prefixedDigestSchema("jag");
const nodeIdSchema = prefixedDigestSchema("jag_node");
const textSchema = z.string().min(1);
const selectorTextSchema = textSchema;
const semanticPrimitiveSchema = z.union([
z.string(),
z.number().finite(),
z.boolean(),
z.null(),
]);
function isJsonPointer(value: string): boolean {
if (value === "") return true;
if (!value.startsWith("/")) return false;
for (let index = 0; index < value.length; index += 1) {
if (value[index] !== "~") continue;
const escaped = value[index + 1];
if (escaped !== "0" && escaped !== "1") return false;
index += 1;
}
return true;
}
const jsonPointerSchema = z
.string()
.refine(isJsonPointer, "Expected an RFC 6901 JSON Pointer");
const sourcePointSchema = z.strictObject({
line: z.number().int().min(1),
column: z.number().int().min(0),
});
const sourceRangeSchema = z
.strictObject({
start: sourcePointSchema,
end: sourcePointSchema,
})
.superRefine((range, context) => {
if (
range.end.line < range.start.line ||
(range.end.line === range.start.line &&
range.end.column < range.start.column)
)
context.addIssue({
code: "custom",
path: ["end"],
message: "Source range end must not precede its start",
});
});
/** Two authenticated application graphs and exact export selectors. */
export const compareJavaScriptExportShapesInputSchema = z
.strictObject({
left: evidenceSchema,
right: evidenceSchema,
left_module_path: selectorTextSchema,
left_export_name: selectorTextSchema,
right_module_path: selectorTextSchema,
right_export_name: selectorTextSchema,
})
.superRefine((input, context) => {
if (input.left.evidence_id === input.right.evidence_id)
context.addIssue({
code: "custom",
path: ["right"],
message: "JavaScript export shape Evidence must be distinct",
});
});
const projectedReturnFieldShape = { path: jsonPointerSchema };
const projectedReturnFieldSchema = z.discriminatedUnion("state", [
z.strictObject({
...projectedReturnFieldShape,
state: z.literal("literal"),
value: semanticPrimitiveSchema,
reason: z.null(),
}),
z.strictObject({
...projectedReturnFieldShape,
state: z.literal("union"),
value: z.array(semanticPrimitiveSchema).min(1),
reason: z.null(),
}),
z.strictObject({
...projectedReturnFieldShape,
state: z.literal("unknown"),
value: z.null(),
reason: textSchema,
}),
]);
export type ProjectedReturnField = z.infer<typeof projectedReturnFieldSchema>;
const projectedPropertyCoverageSchema = z.discriminatedUnion("status", [
z.strictObject({
path: jsonPointerSchema,
status: z.literal("complete"),
omitted: z.literal(0),
}),
z.strictObject({
path: jsonPointerSchema,
status: z.literal("partial"),
omitted: z.union([z.number().int().positive(), z.null()]),
}),
]);
export type ProjectedPropertyCoverage = z.infer<
typeof projectedPropertyCoverageSchema
>;
const projectedReturnShapeSchema = z
.strictObject({
source_range: sourceRangeSchema,
value_status: z.enum([
"literal",
"union",
"object",
"array",
"unknown",
"ambiguous",
"cycle",
]),
fields: z.array(projectedReturnFieldSchema),
property_coverage: z.array(projectedPropertyCoverageSchema),
})
.superRefine((shape, context) => {
const fieldPaths = shape.fields.map(({ path }) => path);
if (new Set(fieldPaths).size !== fieldPaths.length)
context.addIssue({
code: "custom",
path: ["fields"],
message: "Projected return field paths must be unique",
});
const coveragePaths = shape.property_coverage.map(({ path }) => path);
if (new Set(coveragePaths).size !== coveragePaths.length)
context.addIssue({
code: "custom",
path: ["property_coverage"],
message: "Projected property coverage paths must be unique",
});
});
/** Strict graph-observation payload produced by static return-shape recovery. */
export const projectedExportReturnShapesSchema = z
.strictObject({
semantic_role: z.literal("export-return-shapes"),
module_path: selectorTextSchema,
exported_name: selectorTextSchema,
callable_id: textSchema,
callable_kind: z.enum(["function", "class", "method"]),
static_return_shapes: z.array(projectedReturnShapeSchema),
return_shape_coverage: z.strictObject({
status: z.enum(["complete", "partial", "truncated"]),
retained_return_sites: z.number().int().min(0),
omitted_return_sites: z.number().int().min(0).nullable(),
omitted_fields: z.number().int().min(0),
omitted_property_coverage: z.number().int().min(0),
projection_complete: z.boolean(),
}),
})
.superRefine((projection, context) => {
if (
projection.return_shape_coverage.retained_return_sites !==
projection.static_return_shapes.length
)
context.addIssue({
code: "custom",
path: ["return_shape_coverage", "retained_return_sites"],
message: "Retained return-site count must match projected shapes",
});
});
const exportCandidateSchema = z.strictObject({
node_id: nodeIdSchema,
module_path: selectorTextSchema,
export_name: selectorTextSchema,
matches_requested_module: z.boolean(),
matches_requested_export: z.boolean(),
});
const selectorResultShape = {
evidence_id: evidenceIdSchema,
graph_id: graphIdSchema,
requested_module_path: selectorTextSchema,
requested_export_name: selectorTextSchema,
candidates: z.array(exportCandidateSchema),
omitted_candidates: z.number().int().min(0),
};
const selectorResultSchema = z.union([
z.strictObject({
...selectorResultShape,
status: z.literal("selected"),
selected_node_id: nodeIdSchema,
}),
z.strictObject({
...selectorResultShape,
status: z.enum(["missing", "ambiguous"]),
selected_node_id: z.null(),
}),
z.strictObject({
...selectorResultShape,
status: z.literal("unavailable"),
selected_node_id: nodeIdSchema.nullable(),
}),
]);
const valueAvailabilitySchema = z.discriminatedUnion("availability", [
z.strictObject({ availability: z.literal("absent") }),
z.strictObject({
availability: z.literal("literal"),
value: semanticPrimitiveSchema,
}),
z.strictObject({
availability: z.literal("union"),
values: z.array(semanticPrimitiveSchema).min(1),
}),
z.strictObject({
availability: z.literal("unknown"),
reason: textSchema,
}),
]);
const discriminantSchema = z.strictObject({
path: jsonPointerSchema,
value: semanticPrimitiveSchema,
});
const comparisonChangeSchema = z.strictObject({
change_id: prefixedDigestSchema("jesc_change"),
status: z.enum(["added", "removed", "changed", "unknown"]),
path: jsonPointerSchema,
discriminant: discriminantSchema.nullable(),
left: valueAvailabilitySchema,
right: valueAvailabilitySchema,
left_source_range: sourceRangeSchema.nullable(),
right_source_range: sourceRangeSchema.nullable(),
evidence_links: z.array(evidenceIdSchema).length(2),
limitations: z.array(textSchema),
});
/** Static export-return comparison with explicit unknown semantics. */
export const javaScriptExportShapeComparisonResultSchema = z.strictObject({
comparison_id: prefixedDigestSchema("jesc"),
left: selectorResultSchema,
right: selectorResultSchema,
summary: z.strictObject({
added: z.number().int().min(0),
removed: z.number().int().min(0),
changed: z.number().int().min(0),
unknown: z.number().int().min(0),
}),
changes: z.array(comparisonChangeSchema),
coverage: z.strictObject({
status: z.enum(["complete-within-inputs", "partial", "truncated"]),
left_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
right_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
paired_variants: z.number().int().min(0),
unpaired_left_variants: z.number().int().min(0),
unpaired_right_variants: z.number().int().min(0),
omitted_left_variants: z.number().int().min(0),
omitted_right_variants: z.number().int().min(0),
left_source_omitted_variants: z.number().int().min(0).nullable(),
right_source_omitted_variants: z.number().int().min(0).nullable(),
left_omitted_fields: z.number().int().min(0),
right_omitted_fields: z.number().int().min(0),
left_omitted_property_coverage: z.number().int().min(0),
right_omitted_property_coverage: z.number().int().min(0),
omitted_candidates: z.number().int().min(0),
omitted_changes: z.number().int().min(0),
}),
evidence_links: z.array(evidenceIdSchema).length(2),
limitations: z.array(textSchema),
});
export type ProjectedExportReturnShapes = z.output<
typeof projectedExportReturnShapesSchema
>;
export type JavaScriptExportShapeComparisonResult = z.output<
typeof javaScriptExportShapeComparisonResultSchema
>;
export type JavaScriptExportShapeComparisonChange = z.output<
typeof comparisonChangeSchema
>;
@@ -0,0 +1,263 @@
import type {
ApplicationNode,
JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
projectedExportReturnShapesSchema,
type JavaScriptExportShapeComparisonResult,
type ProjectedExportReturnShapes,
} from "./javascriptExportShapeComparisonSchemas.js";
import { compareCodePoints } from "../canonicalOrdering.js";
type Shape = ProjectedExportReturnShapes["static_return_shapes"][number];
type SelectorResult = JavaScriptExportShapeComparisonResult["left"];
type SelectorBase = Omit<SelectorResult, "status" | "selected_node_id">;
type ReturnShapeSelection =
| {
readonly projection: ProjectedExportReturnShapes;
readonly observationComplete: boolean;
}
| {
readonly projection: null;
readonly observationComplete: false;
readonly reason: string;
};
/** One authenticated graph and exact export selector. */
export interface JavaScriptExportShapeSideInput {
readonly evidenceId: string;
readonly graph: JavaScriptApplicationGraph;
readonly modulePath: string;
readonly exportName: string;
}
interface ExportCandidate {
readonly node: ApplicationNode;
readonly modulePath: string;
readonly exportName: string;
readonly trusted: boolean;
}
/** Exact selector result plus any admitted static return-shape projection. */
export type SelectedJavaScriptExport =
| {
readonly selection: Extract<SelectorResult, { status: "selected" }>;
readonly projection: ProjectedExportReturnShapes;
readonly observationComplete: boolean;
readonly limitations: readonly [];
}
| {
readonly selection: Exclude<SelectorResult, { status: "selected" }>;
readonly projection: null;
readonly observationComplete: false;
readonly limitations: readonly string[];
};
/** Complete return-shape inventory retained from an authenticated projection. */
export interface RetainedJavaScriptExportShapes {
readonly shapes: readonly Shape[];
readonly omitted: number;
}
/** Select one exact trusted export and its exact static return-shape observation. */
export const selectJavaScriptExport = (
side: JavaScriptExportShapeSideInput,
): SelectedJavaScriptExport => {
const candidates = exportCandidates(side.graph);
const exact = candidates.filter(
({ modulePath, exportName }) =>
modulePath === side.modulePath && exportName === side.exportName,
);
const matchingOneSelector = candidates.filter(
({ modulePath, exportName }) =>
modulePath === side.modulePath || exportName === side.exportName,
);
const diagnosticPool =
exact.length > 0
? exact
: matchingOneSelector.length > 0
? matchingOneSelector
: candidates;
const base = selectorBase(side, diagnosticPool);
if (exact.length === 0)
return unresolvedSelection(
base,
{ status: "missing", selected_node_id: null },
[
`No exact export binding matched ${side.modulePath}:${side.exportName}.`,
],
);
if (exact.length > 1)
return unresolvedSelection(
base,
{ status: "ambiguous", selected_node_id: null },
[
`Multiple exact export bindings matched ${side.modulePath}:${side.exportName}; none was selected.`,
],
);
const selected = exact[0];
if (selected === undefined || !selected.trusted)
return unresolvedSelection(
base,
{
status: "unavailable",
selected_node_id: selected?.node.node_id ?? null,
},
[
"The exact export binding lacks the expected static-analysis authority.",
],
);
const returnShape = returnShapeFor(selected.node, side);
if (returnShape.projection === null)
return unresolvedSelection(
base,
{ status: "unavailable", selected_node_id: selected.node.node_id },
[returnShape.reason],
);
return {
selection: {
...base,
status: "selected",
selected_node_id: selected.node.node_id,
},
projection: returnShape.projection,
observationComplete: returnShape.observationComplete,
limitations: [],
};
};
/** Retain every projected return variant. */
export const retainJavaScriptExportShapes = (
selection: SelectedJavaScriptExport,
): RetainedJavaScriptExportShapes => {
const shapes = selection.projection?.static_return_shapes ?? [];
return { shapes, omitted: 0 };
};
const selectorBase = (
side: JavaScriptExportShapeSideInput,
candidates: readonly ExportCandidate[],
): SelectorBase => ({
evidence_id: side.evidenceId,
graph_id: side.graph.graph_id,
requested_module_path: side.modulePath,
requested_export_name: side.exportName,
candidates: candidates.map((candidate) => ({
node_id: candidate.node.node_id,
module_path: candidate.modulePath,
export_name: candidate.exportName,
matches_requested_module: candidate.modulePath === side.modulePath,
matches_requested_export: candidate.exportName === side.exportName,
})),
omitted_candidates: 0,
});
const unresolvedSelection = (
base: SelectorBase,
resolution:
| {
readonly status: "missing" | "ambiguous";
readonly selected_node_id: null;
}
| {
readonly status: "unavailable";
readonly selected_node_id: string | null;
},
limitations: readonly string[],
): SelectedJavaScriptExport => ({
selection: { ...base, ...resolution },
projection: null,
observationComplete: false,
limitations,
});
const exportCandidates = (
graph: JavaScriptApplicationGraph,
): ExportCandidate[] => {
const candidates = new Map<string, ExportCandidate>();
for (const node of graph.nodes) {
for (const observation of node.observations) {
const properties = observation.properties;
if (properties.semantic_role !== "export-binding") continue;
const modulePath = properties.module_path;
const exportName = properties.exported_name;
if (typeof modulePath !== "string" || typeof exportName !== "string")
continue;
const key = `${node.node_id}\0${modulePath}\0${exportName}`;
const trusted =
observation.evidence.authority === "ast-static-analysis" &&
observation.evidence.state === "observed" &&
observation.evidence.extractor.operation === "recover-module-export";
const existing = candidates.get(key);
candidates.set(key, {
node,
modulePath,
exportName,
trusted: trusted || existing?.trusted === true,
});
}
}
return [...candidates.values()].sort((left, right) =>
compareCodePoints(candidateKey(left), candidateKey(right)),
);
};
const candidateKey = (candidate: ExportCandidate): string =>
`${candidate.modulePath}\0${candidate.exportName}\0${candidate.node.node_id}`;
const returnShapeFor = (
node: ApplicationNode,
side: JavaScriptExportShapeSideInput,
): ReturnShapeSelection => {
const roleObservations = node.observations.filter(
({ properties }) => properties.semantic_role === "export-return-shapes",
);
const parsed = roleObservations.map((observation) => ({
observation,
result: projectedExportReturnShapesSchema.safeParse(observation.properties),
}));
if (parsed.some(({ result }) => !result.success))
return unavailableReturnShape(
"The export return-shape observation is malformed.",
);
const matching = parsed.filter(
({ result }) =>
result.success &&
result.data.module_path === side.modulePath &&
result.data.exported_name === side.exportName,
);
if (matching.length !== 1)
return unavailableReturnShape(
matching.length === 0
? "No exact static return-shape observation is available for the selected export."
: "Multiple static return-shape observations matched the selected export.",
);
const selected = matching[0];
if (selected === undefined || !selected.result.success)
return unavailableReturnShape(
"The selected return-shape observation could not be parsed.",
);
const { observation } = selected;
const trusted =
observation.evidence.authority === "static-relationship-inference" &&
observation.evidence.state === "inferred" &&
observation.evidence.extractor.operation === "recover-export-return-shapes";
if (!trusted)
return unavailableReturnShape(
"The return-shape observation lacks the expected static-inference authority.",
);
return {
projection: selected.result.data,
observationComplete:
observation.evidence.coverage.status === "complete" &&
!observation.evidence.coverage.truncated,
};
};
const unavailableReturnShape = (
reason: string,
): Extract<ReturnShapeSelection, { readonly projection: null }> => ({
projection: null,
observationComplete: false,
reason,
});
@@ -0,0 +1,460 @@
import {
canonicalExportShapeValue,
digestExportShapeValue,
} from "./javascriptExportShapeComparisonIdentity.js";
import type {
JavaScriptExportShapeComparisonChange,
JavaScriptExportShapeComparisonResult,
ProjectedExportReturnShapes,
} from "./javascriptExportShapeComparisonSchemas.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { SelectedJavaScriptExport } from "./javascriptExportShapeSelection.js";
type Primitive = string | number | boolean | null;
type Shape = ProjectedExportReturnShapes["static_return_shapes"][number];
type Field = Shape["fields"][number];
type SelectorResult = JavaScriptExportShapeComparisonResult["left"];
type ValueAvailability = JavaScriptExportShapeComparisonChange["left"];
type Discriminant = NonNullable<
JavaScriptExportShapeComparisonChange["discriminant"]
>;
interface VariantPair {
readonly leftIndex: number;
readonly rightIndex: number;
readonly discriminant: Discriminant;
}
/** Unique-only return-variant pairings plus every unpaired retained variant. */
export interface JavaScriptExportShapePairing {
readonly pairs: readonly VariantPair[];
readonly unpairedLeft: readonly number[];
readonly unpairedRight: readonly number[];
}
/** Pair variants only through reciprocal unique exact literal discriminants. */
export const pairJavaScriptExportShapeVariants = (
left: readonly Shape[],
right: readonly Shape[],
): JavaScriptExportShapePairing => {
const leftKeys = discriminantOccurrences(left);
const rightKeys = discriminantOccurrences(right);
const edges = new Map<string, Discriminant[]>();
const leftTargets = new Map<number, Set<number>>();
const rightTargets = new Map<number, Set<number>>();
for (const [key, leftOccurrence] of leftKeys) {
const rightOccurrence = rightKeys.get(key);
if (
leftOccurrence.indexes.length !== 1 ||
rightOccurrence?.indexes.length !== 1
)
continue;
const leftIndex = leftOccurrence.indexes[0];
const rightIndex = rightOccurrence.indexes[0];
if (leftIndex === undefined || rightIndex === undefined) continue;
const edgeKey = `${String(leftIndex)}:${String(rightIndex)}`;
edges.set(edgeKey, [
...(edges.get(edgeKey) ?? []),
leftOccurrence.discriminant,
]);
addTarget(leftTargets, leftIndex, rightIndex);
addTarget(rightTargets, rightIndex, leftIndex);
}
const pairs = reciprocalPairs(leftTargets, rightTargets, edges);
const pairedLeft = new Set(pairs.map(({ leftIndex }) => leftIndex));
const pairedRight = new Set(pairs.map(({ rightIndex }) => rightIndex));
return {
pairs,
unpairedLeft: indexesNotIn(left, pairedLeft),
unpairedRight: indexesNotIn(right, pairedRight),
};
};
interface ChangeBuildInput {
readonly leftSelection: SelectedJavaScriptExport;
readonly rightSelection: SelectedJavaScriptExport;
readonly pairing: JavaScriptExportShapePairing;
readonly leftShapes: readonly Shape[];
readonly rightShapes: readonly Shape[];
readonly evidenceLinks: [string, string];
}
/** Build bounded-ready field and unpaired-variant changes before caller slicing. */
export const buildJavaScriptExportShapeChanges = (
input: ChangeBuildInput,
): JavaScriptExportShapeComparisonChange[] => {
if (
input.leftSelection.selection.status !== "selected" ||
input.rightSelection.selection.status !== "selected"
)
return [selectionUnknownChange(input)];
if (input.leftShapes.length === 0 || input.rightShapes.length === 0)
return [emptyShapeUnknownChange(input)];
const paired = input.pairing.pairs.flatMap((pair) => {
const left = input.leftShapes[pair.leftIndex];
const right = input.rightShapes[pair.rightIndex];
return left === undefined || right === undefined
? []
: diffPair(left, right, pair.discriminant, input.evidenceLinks);
});
const unpairedLeft = input.pairing.unpairedLeft.flatMap((index) => {
const shape = input.leftShapes[index];
return shape === undefined
? []
: [unpairedChange("left", shape, input.evidenceLinks)];
});
const unpairedRight = input.pairing.unpairedRight.flatMap((index) => {
const shape = input.rightShapes[index];
return shape === undefined
? []
: [unpairedChange("right", shape, input.evidenceLinks)];
});
return [...paired, ...unpairedLeft, ...unpairedRight];
};
/** Sort changes by semantic content rather than traversal order. */
export const compareJavaScriptExportShapeChanges = (
left: JavaScriptExportShapeComparisonChange,
right: JavaScriptExportShapeComparisonChange,
): number =>
compareCodePoints(
canonicalExportShapeValue(changeSortKey(left)),
canonicalExportShapeValue(changeSortKey(right)),
);
/** Report whether any retained shape lacks complete property coverage. */
export const hasPartialJavaScriptExportPropertyCoverage = (
shapes: readonly Shape[],
): boolean =>
shapes.some((shape) =>
shape.property_coverage.some(({ status }) => status === "partial"),
);
interface DiscriminantOccurrence {
readonly discriminant: Discriminant;
readonly indexes: number[];
}
const discriminantOccurrences = (
shapes: readonly Shape[],
): Map<string, DiscriminantOccurrence> => {
const output = new Map<string, DiscriminantOccurrence>();
shapes.forEach((shape, index) => {
for (const field of shape.fields) {
const value = literalValue(field);
if (!value.found) continue;
const discriminant = { path: field.path, value: value.value };
const key = canonicalExportShapeValue(discriminant);
const current = output.get(key);
output.set(key, {
discriminant,
indexes: [...(current?.indexes ?? []), index],
});
}
});
return output;
};
const reciprocalPairs = (
leftTargets: ReadonlyMap<number, ReadonlySet<number>>,
rightTargets: ReadonlyMap<number, ReadonlySet<number>>,
edges: ReadonlyMap<string, readonly Discriminant[]>,
): VariantPair[] => {
const pairs: VariantPair[] = [];
for (const [leftIndex, targets] of leftTargets) {
if (targets.size !== 1) continue;
const rightIndex = [...targets][0];
if (
rightIndex === undefined ||
rightTargets.get(rightIndex)?.size !== 1 ||
!rightTargets.get(rightIndex)?.has(leftIndex)
)
continue;
const discriminants = edges
.get(`${String(leftIndex)}:${String(rightIndex)}`)
?.toSorted(compareDiscriminants);
const discriminant = discriminants?.[0];
if (discriminant !== undefined)
pairs.push({ leftIndex, rightIndex, discriminant });
}
return pairs.sort((first, second) =>
compareDiscriminants(first.discriminant, second.discriminant),
);
};
const addTarget = (
map: Map<number, Set<number>>,
source: number,
target: number,
): void => {
const values = map.get(source) ?? new Set<number>();
values.add(target);
map.set(source, values);
};
const indexesNotIn = (
shapes: readonly Shape[],
paired: ReadonlySet<number>,
): number[] =>
shapes.map((_, index) => index).filter((index) => !paired.has(index));
const compareDiscriminants = (
left: Discriminant,
right: Discriminant,
): number =>
compareCodePoints(
canonicalExportShapeValue(left),
canonicalExportShapeValue(right),
);
const selectionUnknownChange = (
input: ChangeBuildInput,
): JavaScriptExportShapeComparisonChange =>
changeWithId({
status: "unknown",
path: "",
discriminant: null,
left: selectionAvailability(input.leftSelection.selection, "left"),
right: selectionAvailability(input.rightSelection.selection, "right"),
left_source_range: null,
right_source_range: null,
evidence_links: input.evidenceLinks,
limitations: [
"Both selectors must resolve one exact export with trusted static return shapes before comparison.",
],
});
const emptyShapeUnknownChange = (
input: ChangeBuildInput,
): JavaScriptExportShapeComparisonChange =>
changeWithId({
status: "unknown",
path: "",
discriminant: null,
left: emptyShapeAvailability(input.leftShapes, "left"),
right: emptyShapeAvailability(input.rightShapes, "right"),
left_source_range: null,
right_source_range: null,
evidence_links: input.evidenceLinks,
limitations: [
"At least one selected export has no retained direct return shape.",
],
});
const diffPair = (
left: Shape,
right: Shape,
discriminant: Discriminant,
evidenceLinks: [string, string],
): JavaScriptExportShapeComparisonChange[] => {
const leftFields = new Map(left.fields.map((field) => [field.path, field]));
const rightFields = new Map(right.fields.map((field) => [field.path, field]));
const paths = uniqueSorted([
...leftFields.keys(),
...rightFields.keys(),
...left.property_coverage.map(({ path }) => path),
...right.property_coverage.map(({ path }) => path),
]);
return paths.flatMap((path) => {
const leftField = fieldAtPath(left, leftFields, path);
const rightField = fieldAtPath(right, rightFields, path);
const status = fieldChangeStatus({
leftShape: left,
rightShape: right,
path,
leftField,
rightField,
});
if (status === null) return [];
return [
changeWithId({
status,
path,
discriminant,
left: fieldAvailability(leftField),
right: fieldAvailability(rightField),
left_source_range: left.source_range,
right_source_range: right.source_range,
evidence_links: evidenceLinks,
limitations:
status === "unknown"
? [
"The static value or relevant parent-property coverage is incomplete.",
]
: [],
}),
];
});
};
const fieldAtPath = (
shape: Shape,
fields: ReadonlyMap<string, Field>,
path: string,
): Field | undefined => {
const field = fields.get(path);
if (field !== undefined) return field;
if (!shape.property_coverage.some((coverage) => coverage.path === path))
return undefined;
return {
path,
state: "unknown",
value: null,
reason:
"A static container is retained at this path, but no primitive field value is projected.",
};
};
interface FieldChangeInput {
readonly leftShape: Shape;
readonly rightShape: Shape;
readonly path: string;
readonly leftField: Field | undefined;
readonly rightField: Field | undefined;
}
const fieldChangeStatus = ({
leftShape,
rightShape,
path,
leftField,
rightField,
}: FieldChangeInput):
| JavaScriptExportShapeComparisonChange["status"]
| null => {
if (leftField !== undefined && rightField !== undefined) {
if (
canonicalExportShapeValue(leftField) ===
canonicalExportShapeValue(rightField)
)
return null;
return leftField.state === "unknown" || rightField.state === "unknown"
? "unknown"
: "changed";
}
const present = leftField ?? rightField;
if (present === undefined) return null;
const parent = parentPointer(path);
const parentsComplete =
propertyCoverageComplete(leftShape, parent) &&
propertyCoverageComplete(rightShape, parent);
if (present.state === "unknown" || !parentsComplete) return "unknown";
return leftField === undefined ? "added" : "removed";
};
const propertyCoverageComplete = (shape: Shape, path: string | null): boolean =>
path !== null &&
shape.property_coverage.some(
(coverage) => coverage.path === path && coverage.status === "complete",
);
const parentPointer = (path: string): string | null => {
if (path === "") return null;
const separator = path.lastIndexOf("/");
return separator < 0 ? null : path.slice(0, separator);
};
const fieldAvailability = (field: Field | undefined): ValueAvailability => {
if (field === undefined) return { availability: "absent" };
if (field.state === "unknown")
return {
availability: "unknown",
reason: field.reason ?? "Static field value is unknown.",
};
if (field.state === "union")
return { availability: "union", values: primitiveArray(field.value) };
const literal = literalValue(field);
return literal.found
? { availability: "literal", value: literal.value }
: {
availability: "unknown",
reason: "Static literal field failed its projection boundary.",
};
};
const selectionAvailability = (
selection: SelectorResult,
side: "left" | "right",
): ValueAvailability => ({
availability: "unknown",
reason: `${capitalize(side)} export selection is ${selection.status}.`,
});
const emptyShapeAvailability = (
shapes: readonly Shape[],
side: "left" | "right",
): ValueAvailability => ({
availability: "unknown",
reason:
shapes.length === 0
? `${capitalize(side)} export has no retained direct return shape.`
: `${capitalize(side)} export return shape cannot be paired without an opposite variant.`,
});
const unpairedChange = (
side: "left" | "right",
shape: Shape,
evidenceLinks: [string, string],
): JavaScriptExportShapeComparisonChange =>
changeWithId({
status: "unknown",
path: "",
discriminant: null,
left: {
availability: "unknown",
reason:
side === "left"
? "Left return variant has no unique exact cross-version pairing."
: "No left return variant was uniquely paired with this right variant.",
},
right: {
availability: "unknown",
reason:
side === "right"
? "Right return variant has no unique exact cross-version pairing."
: "No right return variant was uniquely paired with this left variant.",
},
left_source_range: side === "left" ? shape.source_range : null,
right_source_range: side === "right" ? shape.source_range : null,
evidence_links: evidenceLinks,
limitations: [
"The return variant was not paired because no reciprocal unique literal discriminant exists.",
],
});
const changeWithId = (
semantic: Omit<JavaScriptExportShapeComparisonChange, "change_id">,
): JavaScriptExportShapeComparisonChange => ({
...semantic,
change_id: `jesc_change_${digestExportShapeValue(semantic)}`,
});
const changeSortKey = (change: JavaScriptExportShapeComparisonChange) => ({
discriminant: change.discriminant,
path: change.path,
status: change.status,
left_source_range: change.left_source_range,
right_source_range: change.right_source_range,
change_id: change.change_id,
});
const literalValue = (
field: Field,
):
| { readonly found: true; readonly value: Primitive }
| { readonly found: false } =>
field.state === "literal" && isPrimitive(field.value)
? { found: true, value: field.value }
: { found: false };
const primitiveArray = (value: unknown): Primitive[] =>
Array.isArray(value) ? value.filter(isPrimitive) : [];
const isPrimitive = (value: unknown): value is Primitive =>
value === null ||
typeof value === "string" ||
typeof value === "number" ||
typeof value === "boolean";
const capitalize = (value: string): string =>
`${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
@@ -0,0 +1,432 @@
import { describe, expect, it } from "vitest";
import {
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
type ApplicationNode,
} from "./javascriptApplicationGraph.js";
import {
artifactEvidence,
completeCoverage,
} from "./javascriptApplicationGraph.fixture.js";
import { findApplicationFeatureSeeds } from "./javascriptFeatureSeed.js";
import { traceApplicationFeature } from "./javascriptFeatureTrace.js";
import type { ApplicationFeatureSeed } from "./javascriptFeatureTraceSchemas.js";
import { analyzeJavaScriptStaticSource } from "./javascriptStaticAnalysis.js";
import type { JsonValue } from "../jsonValue.js";
const memberFields = [
{ kind: "api", nodeKind: "context-bridge-api", field: "members" },
{ kind: "api", nodeKind: "context-bridge-api", field: "methods" },
{ kind: "module", nodeKind: "javascript-asset", field: "exports" },
{ kind: "module", nodeKind: "javascript-module", field: "exports" },
{ kind: "module", nodeKind: "source-module", field: "exports" },
{
kind: "native-export",
nodeKind: "native-export",
field: "requested_members",
},
{ kind: "native-export", nodeKind: "native-export", field: "members" },
] as const;
const matchingModes = [
{ value: "openProject", match: null, case_sensitive: true },
{ value: "openProject", match: "exact", case_sensitive: true },
{ value: "openProj", match: "contains", case_sensitive: true },
{ value: "OPENPROJECT", match: "exact", case_sensitive: false },
{ value: "OPENPROJ", match: "contains", case_sensitive: false },
] as const;
describe.each(memberFields)(
"$kind seeds for $nodeKind / $field",
({ kind, nodeKind, field }) => {
it.each(matchingModes)(
"matches scalar and array values with $match / $value / case-sensitive $case_sensitive",
(mode) => {
const values: readonly [JsonValue, string][] = [
["openProject", ""],
[["closeProject", "openProject"], "[1]"],
];
for (const [value, suffix] of values) {
const node = memberNode(nodeKind, { [field]: value });
expect(
findApplicationFeatureSeeds([node], { kind, ...mode }),
).toEqual([propertyMatch(node, `${field}${suffix}`)]);
}
},
);
it("keeps exact, case-sensitive, and non-string exclusions", () => {
const node = memberNode(nodeKind, {
[field]: [null, 42, true, "openProject"],
});
for (const value of ["Project", "OPENPROJECT", "42", "true", "null"])
expect(findApplicationFeatureSeeds([node], seed(kind, value))).toEqual(
[],
);
expect(
findApplicationFeatureSeeds([node], {
...seed(kind, "Project"),
match: null,
}),
).toEqual([]);
});
it("retains actual indexes through nested arrays and object properties", () => {
const properties = {
nested: [{ [field]: [null, 42, false, [["openProject"]]] }],
};
const node = memberNode(nodeKind, properties);
const before = structuredClone(node);
expect(findApplicationFeatureSeeds([node], seed(kind))).toEqual([
propertyMatch(node, `nested[0].${field}[3][0][0]`),
]);
expect(node).toEqual(before);
expect(properties.nested[0]?.[field]).toEqual([
null,
42,
false,
[["openProject"]],
]);
});
it("preserves literal dotted-field suffixes for scalars and arrays", () => {
const values: readonly [JsonValue, string][] = [
["openProject", ""],
[["openProject"], "[0]"],
];
for (const [value, suffix] of values) {
const node = memberNode(nodeKind, { [`nested.${field}`]: value });
expect(findApplicationFeatureSeeds([node], seed(kind))).toEqual([
propertyMatch(node, `nested.${field}${suffix}`),
]);
}
});
it("does not select near-fields, literal bracket keys, or object descendants", () => {
const cases = [
{
properties: { [`other_${field}`]: "openProject" },
path: `other_${field}`,
},
{ properties: { [`${field}[0]`]: "openProject" }, path: `${field}[0]` },
{
properties: { [`nested.${field}[0]`]: ["openProject"] },
path: `nested.${field}[0][0]`,
},
{
properties: { [field]: { name: "openProject" } },
path: `${field}.name`,
},
{
properties: { [field]: [{ name: "openProject" }] },
path: `${field}[0].name`,
},
];
for (const { properties, path } of cases) {
const node = memberNode(nodeKind, properties);
expect(findApplicationFeatureSeeds([node], seed(kind))).toEqual([]);
expect(findApplicationFeatureSeeds([node], seed("string"))).toEqual([
propertyMatch(node, path),
]);
}
});
},
);
describe("feature seed selection controls", () => {
it.each([
{ kind: "api", nodeKind: "context-bridge-api", field: "label" },
{ kind: "api", nodeKind: "context-bridge-api", field: "api_name" },
{ kind: "api", nodeKind: "context-bridge-api", field: "key" },
{ kind: "module", nodeKind: "javascript-module", field: "label" },
{ kind: "module", nodeKind: "javascript-module", field: "module_key" },
{ kind: "module", nodeKind: "javascript-module", field: "path" },
{ kind: "module", nodeKind: "javascript-module", field: "source" },
{ kind: "module", nodeKind: "javascript-module", field: "original_source" },
{ kind: "native-export", nodeKind: "native-export", field: "label" },
{ kind: "native-export", nodeKind: "native-export", field: "key" },
{ kind: "route", nodeKind: "endpoint", field: "label" },
{ kind: "route", nodeKind: "endpoint", field: "value" },
{ kind: "route", nodeKind: "endpoint", field: "path" },
{ kind: "channel", nodeKind: "ipc-channel", field: "label" },
{ kind: "channel", nodeKind: "ipc-channel", field: "channel" },
{ kind: "channel", nodeKind: "ipc-channel", field: "key" },
] as const)(
"keeps $kind / $field scalar-only selection unchanged",
({ kind, nodeKind, field }) => {
const scalar = memberNode(nodeKind, {
endpoint_kind: "route",
[field]: "openProject",
});
const array = memberNode(nodeKind, {
endpoint_kind: "route",
[field]: ["openProject"],
});
expect(findApplicationFeatureSeeds([scalar], seed(kind))).toEqual([
propertyMatch(scalar, field),
]);
expect(findApplicationFeatureSeeds([array], seed(kind))).toEqual([]);
expect(findApplicationFeatureSeeds([array], seed("string"))).toEqual([
propertyMatch(array, `${field}[0]`),
]);
},
);
it("keeps generic matching and scalar label and identity selection", () => {
const node = memberNode("context-bridge-api", { members: ["openProject"] });
expect(findApplicationFeatureSeeds([node], seed("string"))).toEqual([
propertyMatch(node, "members[0]"),
]);
expect(
findApplicationFeatureSeeds([node], seed("api", "desktopApi")),
).toEqual([
{
node_id: node.node_id,
kind: node.kind,
basis: "label",
field: "observations[0].label",
},
]);
expect(
findApplicationFeatureSeeds([node], seed("node-id", node.node_id)),
).toEqual([
{
node_id: node.node_id,
kind: node.kind,
basis: "node-id",
field: "node_id",
},
]);
const module = memberNode("javascript-module", {});
expect(
findApplicationFeatureSeeds([module], seed("module", "preload.js")),
).toEqual([
{
node_id: module.node_id,
kind: module.kind,
basis: "identity",
field: "identity.path",
},
]);
});
it.each([
{
kind: "route",
nodeKind: "endpoint",
properties: { endpoint_kind: "route", path: "/projects" },
value: "/projects",
field: "path",
},
{
kind: "channel",
nodeKind: "ipc-channel",
properties: { channel: "project:open" },
value: "project:open",
field: "channel",
},
] as const)(
"preserves $kind scalar matching and node-kind restrictions",
({ kind, nodeKind, properties, value, field }) => {
const node = memberNode(nodeKind, properties);
expect(findApplicationFeatureSeeds([node], seed(kind, value))).toEqual([
propertyMatch(node, field),
]);
expect(
findApplicationFeatureSeeds(
[memberNode("context-bridge-api", properties)],
seed(kind, value),
),
).toEqual([]);
},
);
it.each(memberFields)(
"rejects $kind members on an unrelated node kind",
({ kind, field }) => {
const node = memberNode("unknown", { [field]: ["openProject"] });
expect(findApplicationFeatureSeeds([node], seed(kind))).toEqual([]);
},
);
});
describe("public feature trace from contextBridge source members", () => {
it.each(matchingModes)(
"traces $match / $value / case-sensitive $case_sensitive",
(mode) => {
const graph = contextBridgeGraph();
const before = structuredClone(graph);
const input = {
sourceEvidenceId,
graph,
nativeEvidence: [],
direction: "both" as const,
};
const generic = traceApplicationFeature({
...input,
seed: { kind: "string", ...mode },
});
const typed = traceApplicationFeature({
...input,
seed: { kind: "api", ...mode },
});
expect(typed.coverage).toEqual({
status: "complete-within-source",
source_graph_status: "complete",
total_seed_matches: 1,
});
expect(typed.seed_matches).toEqual(generic.seed_matches);
expect(typed.seed_matches).toEqual([
{
node_id: graph.nodes[0]?.node_id,
kind: "context-bridge-api",
basis: "property",
field: "observations[0].properties.members[1]",
},
]);
expect(typed.graph?.nodes).toEqual(graph.nodes);
expect(typed.graph?.edges).toEqual([]);
expect(typed.evidence_links).toEqual([sourceEvidenceId]);
expect(typed.summary).toMatchObject({
matched_seeds: 1,
traced_nodes: 1,
traced_edges: 0,
observed_facts: 1,
inferred_facts: 0,
unknown_facts: 0,
unavailable_facts: 0,
});
expect(typed.native_handoffs).toEqual([]);
expect(graph).toEqual(before);
},
);
it("keeps a missing member explicit without changing source coverage", () => {
const graph = contextBridgeGraph();
const result = traceApplicationFeature({
sourceEvidenceId,
graph,
nativeEvidence: [],
direction: "both",
seed: seed("api", "missingProject"),
});
expect(result.graph).toBeNull();
expect(result.seed_matches).toEqual([]);
expect(result.coverage).toEqual({
status: "no-match",
source_graph_status: "complete",
total_seed_matches: 0,
});
expect(result.evidence_links).toEqual([sourceEvidenceId]);
expect(result.limitations).toContain(
"No graph entity matched the literal seed; this is not evidence that the feature is absent.",
);
});
it("retains incomplete source coverage when an array member matches", () => {
const graph = contextBridgeGraph();
const { graph_id: _graphId, ...content } = graph;
const partialGraph = createJavaScriptApplicationGraph({
...content,
limitations: ["Only one source file was analyzed."],
coverage: {
status: "partial",
truncated: false,
omitted_count: null,
limits: [],
},
});
const result = traceApplicationFeature({
sourceEvidenceId,
graph: partialGraph,
nativeEvidence: [],
direction: "both",
seed: seed("api"),
});
expect(result.coverage).toEqual({
status: "partial",
source_graph_status: "partial",
total_seed_matches: 1,
});
expect(result.graph?.coverage).toEqual(partialGraph.coverage);
expect(result.graph?.nodes).toEqual(partialGraph.nodes);
expect(result.limitations).toContain(
"The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
);
});
});
const sourceEvidenceId = `ev_${"b".repeat(64)}`;
const seed = (
kind: ApplicationFeatureSeed["kind"],
value = "openProject",
): ApplicationFeatureSeed => ({
kind,
value,
match: "exact",
case_sensitive: true,
});
const memberNode = (
kind: ApplicationNode["kind"],
properties: Readonly<Record<string, JsonValue>>,
): ApplicationNode =>
createJavaScriptApplicationNode({
kind,
identity: {
strategy: "canonical-path",
stability: "artifact-version",
artifact_sha256: "a".repeat(64),
path: "preload.js",
},
observations: [
{
label: "desktopApi",
properties,
evidence: {
...artifactEvidence(
"a".repeat(64),
"preload.js",
"ast-static-analysis",
),
evidence_ids: [sourceEvidenceId],
},
},
],
});
const propertyMatch = (node: ApplicationNode, field: string) => ({
node_id: node.node_id,
kind: node.kind,
basis: "property",
field: `observations[0].properties.${field}`,
});
const contextBridgeGraph = () => {
const analysis = analyzeJavaScriptStaticSource(
"contextBridge.exposeInMainWorld('desktopApi', { openProject() {}, closeProject() {} });",
);
expect(analysis.parse_status).toBe("complete");
const finding = analysis.electron.context_bridge_apis[0];
if (finding === undefined) throw new Error("Expected contextBridge finding");
expect(finding.api_key).toBe("desktopApi");
expect(finding.members).toEqual(["closeProject", "openProject"]);
expect(finding.unknown_members).toBe(0);
const node = memberNode("context-bridge-api", {
api_name: finding.api_key,
members: [...finding.members],
unknown_members: finding.unknown_members,
});
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [node.node_id],
nodes: [node],
edges: [],
coverage: completeCoverage,
limitations: [],
});
};
@@ -0,0 +1,67 @@
import { describe, expect, it } from "vitest";
import { buildSyntheticJavaScriptApplicationGraph } from "./javascriptApplicationGraph.fixture.js";
import type { JsonValue } from "../jsonValue.js";
import { findApplicationFeatureSeeds } from "./javascriptFeatureSeed.js";
describe("application feature seed property matching", () => {
it("finds strings after the former property count ceiling", () => {
const node = graphNodeWithProperties({
values: Array.from({ length: 513 }, (_, index) => `value-${index}`),
});
expect(
findApplicationFeatureSeeds([node], {
kind: "string",
value: "value-512",
match: "exact",
case_sensitive: true,
}),
).toEqual([
{
node_id: node.node_id,
kind: node.kind,
basis: "property",
field: "observations[0].properties.values[512]",
},
]);
});
it("finds strings deeper than the former traversal cutoff", () => {
const node = graphNodeWithProperties({
one: {
two: { three: { four: { five: { six: { seven: "deep-value" } } } } },
},
});
expect(
findApplicationFeatureSeeds([node], {
kind: "string",
value: "deep-value",
match: "exact",
case_sensitive: true,
}),
).toEqual([
{
node_id: node.node_id,
kind: node.kind,
basis: "property",
field: "observations[0].properties.one.two.three.four.five.six.seven",
},
]);
});
});
const graphNodeWithProperties = (
properties: Readonly<Record<string, JsonValue>>,
) => {
const template = buildSyntheticJavaScriptApplicationGraph().nodes[0];
if (template === undefined) throw new Error("Expected fixture graph node");
return {
...template,
observations: template.observations.map((observation) => ({
...observation,
properties,
})),
};
};
@@ -0,0 +1,229 @@
import { compareCodePoints } from "../canonicalOrdering.js";
import type { ApplicationNode } from "./javascriptApplicationGraph.js";
import {
featureSeedMatchMode,
type ApplicationFeatureSeed,
} from "./javascriptFeatureTraceSchemas.js";
import type { JsonValue } from "../jsonValue.js";
/** One explicit field that matched a feature seed. */
export interface ApplicationFeatureSeedMatch {
readonly node_id: string;
readonly kind: ApplicationNode["kind"];
readonly basis: "node-id" | "label" | "identity" | "property";
readonly field: string;
}
interface CandidateField {
readonly basis: ApplicationFeatureSeedMatch["basis"];
readonly field: string;
/** Structural field path, retaining literal keys but omitting array indexes. */
readonly selectionPath?: string;
readonly value: string;
}
/** Locate every graph node matching a typed literal seed without regex execution. */
export const findApplicationFeatureSeeds = (
nodes: readonly ApplicationNode[],
seed: ApplicationFeatureSeed,
): ApplicationFeatureSeedMatch[] =>
nodes
.flatMap((node) => seedMatch(node, seed))
.sort((left, right) =>
compareCodePoints(
`${left.node_id}\0${left.basis}\0${left.field}`,
`${right.node_id}\0${right.basis}\0${right.field}`,
),
);
const seedMatch = (
node: ApplicationNode,
seed: ApplicationFeatureSeed,
): ApplicationFeatureSeedMatch[] => {
if (seed.kind === "node-id")
return node.node_id === seed.value
? [
{
node_id: node.node_id,
kind: node.kind,
basis: "node-id",
field: "node_id",
},
]
: [];
if (!kindMatches(node, seed.kind)) return [];
const mode = featureSeedMatchMode(seed);
const query = normalized(seed.value, seed.case_sensitive);
const match = candidateFields(node, seed.kind).find((candidate) => {
const value = normalized(candidate.value, seed.case_sensitive);
return mode === "exact" ? value === query : value.includes(query);
});
return match === undefined
? []
: [
{
node_id: node.node_id,
kind: node.kind,
basis: match.basis,
field: match.field,
},
];
};
const kindMatches = (
node: ApplicationNode,
kind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
): boolean => {
if (kind === "string") return true;
if (kind === "route")
return (
node.kind === "endpoint" &&
node.observations.some(
({ properties }) => properties.endpoint_kind === "route",
)
);
if (kind === "api") return node.kind === "context-bridge-api";
if (kind === "channel") return node.kind === "ipc-channel";
if (kind === "module")
return ["javascript-asset", "javascript-module", "source-module"].includes(
node.kind,
);
return node.kind === "native-export";
};
const candidateFields = (
node: ApplicationNode,
seedKind: Exclude<ApplicationFeatureSeed["kind"], "node-id">,
): CandidateField[] => {
const fields: CandidateField[] = [
...identityFields(node),
...node.observations.flatMap((observation, index) => [
...(observation.label === null
? []
: [
{
basis: "label" as const,
field: `observations[${String(index)}].label`,
value: observation.label,
},
]),
...propertyFields(
observation.properties,
`observations[${String(index)}].properties`,
),
]),
];
if (seedKind === "string") return fields;
const names = relevantFields[seedKind];
return fields.filter(({ field, selectionPath = field }) =>
names.some((name) => {
const path = memberFieldSuffixes.has(name) ? selectionPath : field;
return path === "identity" || path.endsWith(name);
}),
);
};
const memberFieldSuffixes = new Set([
".members",
".methods",
".exports",
".requested_members",
]);
const relevantFields = {
route: [".label", ".value", ".path"],
api: [".label", ".api_name", ".api_key", ".key", ".methods", ".members"],
channel: [".label", ".channel", ".key"],
module: [
".label",
".module_key",
".path",
".source",
".original_source",
".exports",
],
"native-export": [".label", ".key", ".requested_members", ".members"],
} as const;
const identityFields = (node: ApplicationNode): CandidateField[] => {
const identity = node.identity;
if (identity.strategy === "content-digest")
return [{ basis: "identity", field: "identity", value: identity.sha256 }];
if (identity.strategy === "source-map-original")
return [
{
basis: "identity",
field: "identity.original_source",
value: identity.original_source,
},
];
if (identity.strategy === "canonical-path")
return [
{ basis: "identity", field: "identity.path", value: identity.path },
];
if (identity.strategy === "artifact-local-key")
return [{ basis: "identity", field: "identity.key", value: identity.key }];
if (identity.strategy === "runtime-instance")
return [
{
basis: "identity",
field: "identity.runtime_key",
value: identity.runtime_key,
},
];
return [];
};
const propertyFields = (
value: Readonly<Record<string, JsonValue>>,
prefix: string,
): CandidateField[] => {
const output: CandidateField[] = [];
const pending: {
readonly current: JsonValue;
readonly path: string;
readonly selectionPath: string;
}[] = [{ current: value, path: prefix, selectionPath: prefix }];
while (pending.length > 0) {
const next = pending.pop();
if (next === undefined) continue;
const { current, path, selectionPath } = next;
if (typeof current === "string") {
output.push({
basis: "property",
field: path,
selectionPath,
value: current,
});
continue;
}
if (Array.isArray(current)) {
for (let index = current.length - 1; index >= 0; index -= 1) {
const item = current[index];
if (item !== undefined)
pending.push({
current: item,
path: `${path}[${String(index)}]`,
selectionPath,
});
}
continue;
}
if (current !== null && typeof current === "object") {
for (const key of Object.keys(current).sort(compareCodePoints).reverse())
pending.push({
current: current[key] ?? null,
path: `${path}.${key}`,
selectionPath: `${selectionPath}.${key}`,
});
}
}
return output;
};
const normalized = (value: string, caseSensitive: boolean): string => {
const normalizedValue = value.normalize("NFKC");
return caseSensitive
? normalizedValue
: normalizedValue.toLocaleLowerCase("en-US");
};
@@ -0,0 +1,255 @@
import { canonicalDigest } from "../comparisonSemantics.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { Evidence } from "../evidence.js";
import {
createJavaScriptApplicationGraph,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
applicationFeatureTraceResultSchema,
type ApplicationFeatureTraceResult,
type TraceApplicationFeatureInput,
} from "./javascriptFeatureTraceSchemas.js";
import {
findApplicationFeatureSeeds,
type ApplicationFeatureSeedMatch,
} from "./javascriptFeatureSeed.js";
import {
traverseApplicationFeature,
type ApplicationFeatureTraversal,
} from "./javascriptFeatureTraversal.js";
import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
/** Pure, authenticated inputs projected by the application service. */
export interface ApplicationFeatureTraceProjectionInput {
readonly sourceEvidenceId: string;
readonly graph: JavaScriptApplicationGraph;
readonly nativeEvidence: readonly Evidence[];
readonly seed: TraceApplicationFeatureInput["seed"];
readonly direction: TraceApplicationFeatureInput["direction"];
}
/** Trace a literal feature through its complete reachable, authority-preserving JAG. */
export const traceApplicationFeature = (
input: ApplicationFeatureTraceProjectionInput,
): ApplicationFeatureTraceResult => {
const allSeedMatches = findApplicationFeatureSeeds(
input.graph.nodes,
input.seed,
);
const seedMatches = allSeedMatches;
if (seedMatches.length === 0) return noMatchResult(input);
const traversal = traverseApplicationFeature(
input.graph,
seedMatches.map(({ node_id: id }) => id),
input.direction,
);
const graph = traceGraph(input, seedMatches, traversal);
const paths = terminalPaths(traversal, seedMatches);
const nativeHandoffs = buildJavaScriptNativeHandoffs(
traversal.nodes,
traversal.edges,
input.nativeEvidence,
);
const evidenceLinks = uniqueSorted([
input.sourceEvidenceId,
...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
]);
const semantic = {
source_evidence_id: input.sourceEvidenceId,
source_graph_id: input.graph.graph_id,
seed: input.seed,
direction: input.direction,
seed_matches: seedMatches,
graph,
paths,
native_handoffs: nativeHandoffs,
summary: {
matched_seeds: seedMatches.length,
traced_nodes: traversal.nodes.length,
traced_edges: traversal.edges.length,
terminal_paths: paths.length,
native_handoffs: nativeHandoffs.length,
...factSummary(traversal.nodes, traversal.edges),
},
coverage: {
status: traceCoverageStatus(input.graph),
source_graph_status: input.graph.coverage.status,
total_seed_matches: allSeedMatches.length,
},
evidence_links: evidenceLinks,
limitations: traceLimitations(input.graph),
};
return applicationFeatureTraceResultSchema.parse({
...semantic,
trace_id: `jatr_${canonicalDigest(semantic, "Feature trace")}`,
});
};
const noMatchResult = (
input: ApplicationFeatureTraceProjectionInput,
): ApplicationFeatureTraceResult => {
const semantic = {
source_evidence_id: input.sourceEvidenceId,
source_graph_id: input.graph.graph_id,
seed: input.seed,
direction: input.direction,
seed_matches: [],
graph: null,
paths: [],
native_handoffs: [],
summary: {
matched_seeds: 0,
traced_nodes: 0,
traced_edges: 0,
terminal_paths: 0,
native_handoffs: 0,
observed_facts: 0,
inferred_facts: 0,
unknown_facts: 0,
unavailable_facts: 0,
},
coverage: {
status: "no-match" as const,
source_graph_status: input.graph.coverage.status,
total_seed_matches: 0,
},
evidence_links: [input.sourceEvidenceId],
limitations: uniqueSorted([
"No graph entity matched the literal seed; this is not evidence that the feature is absent.",
...sourceCoverageLimitations(input.graph),
]),
};
return applicationFeatureTraceResultSchema.parse({
...semantic,
trace_id: `jatr_${canonicalDigest(semantic, "Feature trace")}`,
});
};
const traceGraph = (
input: ApplicationFeatureTraceProjectionInput,
seedMatches: readonly ApplicationFeatureSeedMatch[],
traversal: ApplicationFeatureTraversal,
): JavaScriptApplicationGraph => {
return createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
nodes: traversal.nodes,
edges: traversal.edges,
coverage: traceGraphCoverage(input.graph),
limitations: uniqueSorted([
...input.graph.limitations,
"Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
]),
});
};
const traceGraphCoverage = (
source: JavaScriptApplicationGraph,
): JavaScriptApplicationGraph["coverage"] => {
return source.coverage.status === "complete"
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: source.coverage;
};
const terminalPaths = (
traversal: ApplicationFeatureTraversal,
seeds: readonly ApplicationFeatureSeedMatch[],
): ApplicationFeatureTraceResult["paths"] => {
const seedIds = new Set(seeds.map(({ node_id: id }) => id));
const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
return traversal.nodes
.filter(
(node) =>
isTerminal(node) &&
(!seedIds.has(node.node_id) || traversal.nodes.length === 1),
)
.map((node) => pathTo(node, traversal.predecessors, edgeById))
.filter((path): path is NonNullable<typeof path> => path !== null)
.sort((left, right) => compareCodePoints(left.path_id, right.path_id));
};
const pathTo = (
node: ApplicationNode,
predecessors: ApplicationFeatureTraversal["predecessors"],
edgeById: ReadonlyMap<string, ApplicationEdge>,
): ApplicationFeatureTraceResult["paths"][number] | null => {
const nodeIds = [node.node_id];
const edgeIds: string[] = [];
let current = node.node_id;
while (predecessors.has(current)) {
const predecessor = predecessors.get(current);
if (predecessor === undefined) break;
nodeIds.push(predecessor.previousNodeId);
edgeIds.push(predecessor.edgeId);
current = predecessor.previousNodeId;
}
nodeIds.reverse();
edgeIds.reverse();
const edges = edgeIds
.map((edgeId) => edgeById.get(edgeId))
.filter((edge): edge is ApplicationEdge => edge !== undefined);
if (edges.length !== edgeIds.length) return null;
const semantic = {
start_node_id: nodeIds[0] ?? node.node_id,
end_node_id: node.node_id,
end_kind: node.kind,
node_ids: nodeIds,
edge_ids: edgeIds,
authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
contains_inference: edges.some(
({ evidence }) => evidence.state === "inferred",
),
};
return {
...semantic,
path_id: `jatp_${canonicalDigest(semantic, "Feature trace")}`,
};
};
const isTerminal = (node: ApplicationNode): boolean =>
["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(
node.kind,
);
const factSummary = (
nodes: readonly ApplicationNode[],
edges: readonly ApplicationEdge[],
) => {
const states = [
...nodes.flatMap(({ observations }) =>
observations.map(({ evidence }) => evidence.state),
),
...edges.map(({ evidence }) => evidence.state),
];
return {
observed_facts: states.filter((state) => state === "observed").length,
inferred_facts: states.filter((state) => state === "inferred").length,
unknown_facts: states.filter((state) => state === "unknown").length,
unavailable_facts: states.filter((state) => state === "unavailable").length,
};
};
const traceCoverageStatus = (
graph: JavaScriptApplicationGraph,
): ApplicationFeatureTraceResult["coverage"]["status"] =>
graph.coverage.status === "complete" ? "complete-within-source" : "partial";
const traceLimitations = (graph: JavaScriptApplicationGraph): string[] =>
uniqueSorted([
"A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
"Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
"Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
...sourceCoverageLimitations(graph),
]);
const sourceCoverageLimitations = (
graph: JavaScriptApplicationGraph,
): string[] =>
graph.coverage.status === "complete"
? []
: [
"The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
];
@@ -0,0 +1,149 @@
import { z } from "zod";
import { evidenceSchema, providerSchema } from "../evidence.js";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const nodeIdSchema = prefixedDigestSchema("jag_node");
const edgeIdSchema = prefixedDigestSchema("jag_edge");
const boundedTextSchema = z.string().min(1);
/** Matching mode for a literal seed: string seeds default to containment. */
export const featureSeedMatchMode = (seed: {
readonly kind: string;
readonly match: "exact" | "contains" | null;
}): "exact" | "contains" =>
seed.match ?? (seed.kind === "string" ? "contains" : "exact");
const literalSeedKinds = [
"route",
"string",
"api",
"channel",
"module",
"native-export",
] as const;
/**
* Literal starting point for one application feature trace. An empty value,
* such as the channel in `ipcMain.handle("")`, must be an explicit exact
* literal seed: empty containment would select every node.
*/
const applicationFeatureSeedSchema = z.union([
z.strictObject({
kind: z.enum(["node-id", ...literalSeedKinds]),
value: boundedTextSchema,
match: z.enum(["exact", "contains"]).nullable().default(null),
case_sensitive: z.boolean().default(false),
}),
z.strictObject({
kind: z.enum(literalSeedKinds),
value: z.literal(""),
match: z.literal("exact"),
case_sensitive: z.boolean().default(false),
}),
]);
/** Evidence-backed application graph and feature seed. */
export const traceApplicationFeatureInputSchema = z
.strictObject({
application: evidenceSchema,
native_observations: z.array(evidenceSchema).default([]),
seed: applicationFeatureSeedSchema,
direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
})
.superRefine((input, context) => {
const ids = input.native_observations.map(({ evidence_id: id }) => id);
if (new Set(ids).size !== ids.length)
context.addIssue({
code: "custom",
path: ["native_observations"],
message: "Native observations must be unique",
});
});
const seedMatchSchema = z.strictObject({
node_id: nodeIdSchema,
kind: z.string().min(1),
basis: z.enum(["node-id", "label", "identity", "property"]),
field: z.string().min(1),
});
const tracePathSchema = z.strictObject({
path_id: prefixedDigestSchema("jatp"),
start_node_id: nodeIdSchema,
end_node_id: nodeIdSchema,
end_kind: z.string().min(1),
node_ids: z.array(nodeIdSchema).min(1),
edge_ids: z.array(edgeIdSchema),
authorities: z.array(z.string().min(1)),
contains_inference: z.boolean(),
});
const nativeHandoffSchema = z.strictObject({
native_node_id: nodeIdSchema,
artifact_sha256: digestSchema,
artifact_path: z.string().min(1).nullable(),
export_node_ids: z.array(nodeIdSchema),
requested_exports: z.array(boundedTextSchema),
status: z.enum(["evidence-linked", "requires-provider-analysis"]),
providers: z.array(providerSchema),
evidence_ids: z.array(evidenceIdSchema),
recommended_tools: z.array(
z.enum([
"open_binary",
"binary_overview",
"search_procedures",
"analyze_function",
"xrefs",
]),
),
});
/** Evidence-preserving complete reachable subgraph and native-analysis handoffs. */
export const applicationFeatureTraceResultSchema = z.strictObject({
trace_id: prefixedDigestSchema("jatr"),
source_evidence_id: evidenceIdSchema,
source_graph_id: prefixedDigestSchema("jag"),
seed: applicationFeatureSeedSchema,
direction: z.enum(["outgoing", "incoming", "both"]),
seed_matches: z.array(seedMatchSchema),
graph: javascriptApplicationGraphSchema.nullable(),
paths: z.array(tracePathSchema),
native_handoffs: z.array(nativeHandoffSchema),
summary: z.strictObject({
matched_seeds: z.number().int().min(0),
traced_nodes: z.number().int().min(0),
traced_edges: z.number().int().min(0),
terminal_paths: z.number().int().min(0),
native_handoffs: z.number().int().min(0),
observed_facts: z.number().int().min(0),
inferred_facts: z.number().int().min(0),
unknown_facts: z.number().int().min(0),
unavailable_facts: z.number().int().min(0),
}),
coverage: z.strictObject({
status: z.enum(["complete-within-source", "partial", "no-match"]),
source_graph_status: z.enum([
"complete",
"partial",
"unknown",
"unavailable",
]),
total_seed_matches: z.number().int().min(0),
}),
evidence_links: z.array(evidenceIdSchema).min(1),
limitations: z.array(boundedTextSchema),
});
export type TraceApplicationFeatureInput = z.infer<
typeof traceApplicationFeatureInputSchema
>;
export type ApplicationFeatureSeed = z.infer<
typeof applicationFeatureSeedSchema
>;
export type ApplicationFeatureTraceResult = z.infer<
typeof applicationFeatureTraceResultSchema
>;
@@ -0,0 +1,99 @@
import {
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import { compareCodePoints } from "../canonicalOrdering.js";
interface AdjacencyEntry {
readonly edge: ApplicationEdge;
readonly nextNodeId: string;
}
interface Predecessor {
readonly previousNodeId: string;
readonly edgeId: string;
}
/** Complete reachable graph projection plus the first deterministic path to each node. */
export interface ApplicationFeatureTraversal {
readonly nodes: ApplicationNode[];
readonly edges: ApplicationEdge[];
readonly predecessors: ReadonlyMap<string, Predecessor>;
}
/** Traverse a JAG without treating edge inference as observed reachability. */
export const traverseApplicationFeature = (
graph: JavaScriptApplicationGraph,
seedNodeIds: readonly string[],
direction: "outgoing" | "incoming" | "both",
): ApplicationFeatureTraversal => {
const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
const adjacency = buildAdjacency(graph.edges, direction);
const visited = new Set(seedNodeIds);
const retainedEdges = new Map<string, ApplicationEdge>();
const predecessors = new Map<string, Predecessor>();
const queue = [...seedNodeIds];
for (let offset = 0; offset < queue.length; offset += 1) {
const current = queue[offset];
if (current === undefined) continue;
for (const entry of adjacency.get(current) ?? []) {
retainedEdges.set(entry.edge.edge_id, entry.edge);
if (visited.has(entry.nextNodeId)) continue;
if (!nodeById.has(entry.nextNodeId)) continue;
visited.add(entry.nextNodeId);
predecessors.set(entry.nextNodeId, {
previousNodeId: current,
edgeId: entry.edge.edge_id,
});
queue.push(entry.nextNodeId);
}
}
return {
nodes: [...visited]
.map((nodeId) => nodeById.get(nodeId))
.filter((node): node is ApplicationNode => node !== undefined)
.sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
edges: [...retainedEdges.values()].sort((left, right) =>
compareCodePoints(left.edge_id, right.edge_id),
),
predecessors,
};
};
const buildAdjacency = (
edges: readonly ApplicationEdge[],
direction: "outgoing" | "incoming" | "both",
): ReadonlyMap<string, AdjacencyEntry[]> => {
const adjacency = new Map<string, AdjacencyEntry[]>();
for (const edge of edges) {
if (direction !== "incoming")
addAdjacency(adjacency, edge.source_node_id, {
edge,
nextNodeId: edge.target_node_id,
});
if (direction !== "outgoing")
addAdjacency(adjacency, edge.target_node_id, {
edge,
nextNodeId: edge.source_node_id,
});
}
for (const entries of adjacency.values())
entries.sort((left, right) =>
compareCodePoints(
`${left.edge.edge_id}\0${left.nextNodeId}`,
`${right.edge.edge_id}\0${right.nextNodeId}`,
),
);
return adjacency;
};
const addAdjacency = (
adjacency: Map<string, AdjacencyEntry[]>,
nodeId: string,
entry: AdjacencyEntry,
): void => {
const entries = adjacency.get(nodeId);
if (entries === undefined) adjacency.set(nodeId, [entry]);
else entries.push(entry);
};
@@ -0,0 +1,132 @@
import { compareCodePoints } from "../canonicalOrdering.js";
import type { Evidence } from "../evidence.js";
import {
type ApplicationEdge,
type ApplicationNode,
} from "./javascriptApplicationGraph.js";
import type { ApplicationFeatureTraceResult } from "./javascriptFeatureTraceSchemas.js";
type NativeHandoff = ApplicationFeatureTraceResult["native_handoffs"][number];
/** Build provider-neutral addon targets and link exact-subject native Evidence. */
export const buildJavaScriptNativeHandoffs = (
nodes: readonly ApplicationNode[],
edges: readonly ApplicationEdge[],
nativeEvidence: readonly Evidence[],
): NativeHandoff[] => {
const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
return nodes
.filter(({ kind }) => kind === "native-addon")
.flatMap((node) => {
const digest = artifactDigest(node);
if (digest === null) return [];
const linked = nativeEvidence.filter(
({ subject }) => subject?.digest.sha256 === digest,
);
const exportNodes = nativeExportNodes(node, edges, nodeById);
return [
{
native_node_id: node.node_id,
artifact_sha256: digest,
artifact_path: artifactPath(node),
export_node_ids: exportNodes.map(({ node_id: id }) => id),
requested_exports: requestedExports(exportNodes),
status:
linked.length === 0
? ("requires-provider-analysis" as const)
: ("evidence-linked" as const),
providers: uniqueProviders(linked),
evidence_ids: linked
.map(({ evidence_id: id }) => id)
.sort(compareCodePoints),
recommended_tools: [
"open_binary" as const,
"binary_overview" as const,
"search_procedures" as const,
"analyze_function" as const,
"xrefs" as const,
],
},
];
})
.sort((left, right) =>
compareCodePoints(left.native_node_id, right.native_node_id),
);
};
const artifactDigest = (node: ApplicationNode): string | null => {
if (node.identity.strategy === "content-digest") return node.identity.sha256;
const observation = node.observations.find(
({ evidence }) => evidence.artifact.available,
);
return observation?.evidence.artifact.available === true
? observation.evidence.artifact.sha256
: null;
};
const artifactPath = (node: ApplicationNode): string | null => {
for (const { evidence } of node.observations)
if (
evidence.location.available &&
evidence.location.value.kind === "artifact-path"
)
return evidence.location.value.path;
return null;
};
const nativeExportNodes = (
addon: ApplicationNode,
edges: readonly ApplicationEdge[],
nodeById: ReadonlyMap<string, ApplicationNode>,
): ApplicationNode[] => {
const ids = edges.flatMap((edge) => {
if (
edge.source_node_id === addon.node_id &&
["contains", "exposes"].includes(edge.relation)
)
return [edge.target_node_id];
if (
edge.target_node_id === addon.node_id &&
["imports", "loads"].includes(edge.relation)
)
return [edge.source_node_id];
return [];
});
return [...new Set(ids)]
.map((id) => nodeById.get(id))
.filter((node): node is ApplicationNode => node?.kind === "native-export")
.sort((left, right) => compareCodePoints(left.node_id, right.node_id));
};
const requestedExports = (nodes: readonly ApplicationNode[]): string[] => {
const values = nodes.flatMap((node) =>
node.observations.flatMap((observation) => [
...(observation.label === null ? [] : [observation.label]),
...stringArray(observation.properties.requested_members),
...stringArray(observation.properties.members),
]),
);
return [...new Set(values)].sort(compareCodePoints);
};
const stringArray = (value: unknown): string[] =>
Array.isArray(value)
? value.filter((item): item is string => typeof item === "string")
: [];
const uniqueProviders = (
evidence: readonly Evidence[],
): NativeHandoff["providers"] =>
[
...new Map(
evidence.map(({ provider }) => [
`${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
provider,
]),
).values(),
].sort((left, right) =>
compareCodePoints(
`${left.id}\0${left.name}\0${left.version ?? ""}`,
`${right.id}\0${right.name}\0${right.version ?? ""}`,
),
);
@@ -0,0 +1,34 @@
import { describe, expect, it } from "vitest";
import { javascriptRecoveryInputSchema } from "./javascriptRecovery.js";
describe("JavaScript recovery requests", () => {
it("defaults omitted transform metadata without requiring engine confirmations", () => {
expect(
javascriptRecoveryInputSchema.parse({
path: "/tmp/bundle.js",
output_directory: "/tmp/recovered",
}),
).toEqual({
path: "/tmp/bundle.js",
output_directory: "/tmp/recovered",
extraction_mode: "structural",
rewrite_level: "standard",
});
});
it.each([
{ path: "", output_directory: "/tmp/recovered" },
{ path: "/tmp/bundle.js" },
{
path: "/tmp/bundle.js",
output_directory: "/tmp/recovered",
approve: true,
},
{
path: "/tmp/bundle.js",
output_directory: "/tmp/recovered",
extraction_mode: "invented",
},
])("rejects malformed input %j", (input) => {
expect(javascriptRecoveryInputSchema.safeParse(input).success).toBe(false);
});
});
+109
View File
@@ -0,0 +1,109 @@
import { z } from "zod";
import { digestSchema } from "../digests.js";
import { analyzeJavaScriptApplicationInputSchema } from "./javascriptApplicationAnalysis.js";
/** Recover derived readable modules from one explicitly selected local script. */
export const javascriptRecoveryInputSchema = z.strictObject({
path: z
.string()
.min(1)
.describe("Absolute path to a UTF-8 JavaScript file; never executed"),
output_directory: z
.string()
.min(1)
.describe("Absolute absent output directory; parent must exist"),
extraction_mode: z
.enum(["structural", "heuristic", "inspection"])
.default("structural")
.describe(
"Structural module boundaries, heuristic fallback, or finer inspection-only regions",
),
rewrite_level: z
.enum(["minimal", "standard", "aggressive"])
.default("standard")
.describe(
"Upstream syntax recovery level; runtime equivalence remains unverified",
),
});
const fileSchema = z.strictObject({
path: z.string().min(1),
sha256: digestSchema,
bytes: z.number().int().nonnegative(),
});
const rangeSchema = z.strictObject({
start: z.number().int().nonnegative(),
end: z.number().int().nonnegative(),
});
/** Complete published artifacts and exact producer provenance for source recovery. */
export const javascriptRecoveryResultSchema = z.strictObject({
source: fileSchema.extend({
snapshot_path: z.string().min(1),
published_copy: fileSchema,
}),
engine: z.strictObject({
id: z.string().min(1),
version: z.string().min(1),
executable: fileSchema,
audited_source_revision: z.string().min(1),
executed_source_revision: z.string().nullable(),
}),
options: z.strictObject({
extraction_mode:
javascriptRecoveryInputSchema.shape.extraction_mode.removeDefault(),
rewrite_level:
javascriptRecoveryInputSchema.shape.rewrite_level.removeDefault(),
}),
status: z.enum(["complete", "partial"]),
detected_formats: z.array(z.string()),
reported_safety: z.string(),
reported_strategy: z.string(),
reported_format: z.string(),
total: z.number().int().nonnegative(),
failed: z.number().int().nonnegative(),
modules: z.array(
z.strictObject({
reported_filename: z.string().min(1),
reported_status: z.string().min(1),
artifact: fileSchema,
source_map: fileSchema.nullable(),
provenance: z.strictObject({
reported_input: z.string(),
original_path: z.string(),
original_sha256: digestSchema,
extraction: z.string(),
byte_ranges: z.array(rangeSchema),
context_byte_ranges: z.array(rangeSchema),
range_semantics: z.literal("half-open-utf8-bytes"),
}),
}),
),
warnings: z.array(
z.strictObject({
filename: z.string(),
kind: z.string(),
is_error: z.boolean(),
message: z.string(),
}),
),
report: fileSchema,
provenance: fileSchema,
manifest: fileSchema,
analysis_input: z
.strictObject({
input_path: analyzeJavaScriptApplicationInputSchema.shape.input_path,
format: z.literal("directory"),
})
.nullable(),
runtime_equivalence: z.literal("unknown"),
limitations: z.array(z.string()),
});
export type JavaScriptRecoveryInput = z.output<
typeof javascriptRecoveryInputSchema
>;
export type JavaScriptRecoveryResult = z.output<
typeof javascriptRecoveryResultSchema
>;
@@ -0,0 +1,173 @@
import { type ApplicationNode } from "./javascriptApplicationGraph.js";
import { uniqueSorted } from "../canonicalOrdering.js";
import type { ParsedStaticLayer } from "./javascriptRuntimeReconciliationParsing.js";
import type {
JavaScriptRuntimeReconciliationItem,
JavaScriptStaticLoadState,
} from "./javascriptRuntimeReconciliationSchemas.js";
import type { RuntimeReconciliationEntity } from "./javascriptRuntimeReconciliationRuntime.js";
import {
createStaticRuntimeScope,
mappedRuntimePaths,
staticNodeWithinRuntimeScope,
} from "./javascriptRuntimeStaticCandidates.js";
export interface StaticLoadStateProjection {
readonly states: readonly JavaScriptStaticLoadState[];
readonly omittedStates: number;
}
/** Classify static code presence without claiming bundled module execution. */
export const classifyStaticLoadStates = (
layers: readonly ParsedStaticLayer[],
runtimeEntities: readonly RuntimeReconciliationEntity[],
matches: readonly JavaScriptRuntimeReconciliationItem[],
options: {
readonly reconciliationComplete: boolean;
},
): StaticLoadStateProjection => {
const states: JavaScriptStaticLoadState[] = [];
for (const layer of layers) {
const projection = classifyLayer(layer, runtimeEntities, matches, {
reconciliationComplete: options.reconciliationComplete,
});
states.push(...projection.states);
}
return { states, omittedStates: 0 };
};
const classifyLayer = (
layer: ParsedStaticLayer,
runtimeEntities: readonly RuntimeReconciliationEntity[],
matches: readonly JavaScriptRuntimeReconciliationItem[],
options: {
readonly reconciliationComplete: boolean;
},
): { readonly states: JavaScriptStaticLoadState[] } => {
const nodes = layer.graph.nodes.filter(isLoadStateNode);
const direct = new Map<string, string[]>();
for (const match of matches)
if (
match.status === "matched" &&
match.static_layer_id === layer.layerId &&
match.static_node_id !== null
)
append(direct, match.static_node_id, match.runtime_node_id);
const resident = residentNodes(layer, new Set(direct.keys()));
const runtimeScope = createStaticRuntimeScope(layer, runtimeEntities);
const scopedEntities = runtimeEntities.filter(
(entity) => mappedRuntimePaths(layer, entity).length > 0,
);
const layerComplete =
options.reconciliationComplete &&
layer.graph.coverage.status === "complete" &&
scopedEntities.length > 0 &&
scopedEntities.every(({ capture }) =>
captureScriptsComplete(capture.evidence.evidence_id, runtimeEntities),
);
const states = nodes.map((node) => {
const runtimeNodeIds = uniqueSorted(direct.get(node.node_id) ?? []);
if (runtimeNodeIds.length > 0)
return state(layer, node, {
status: "loaded",
runtimeNodeIds,
reason: "runtime-script-correspondence",
});
if (resident.has(node.node_id))
return state(layer, node, {
status: "resident-in-loaded-asset",
runtimeNodeIds: [],
reason: "containing-asset-was-loaded",
});
const nodeWithinScope = staticNodeWithinRuntimeScope(node, runtimeScope);
if (layerComplete && nodeWithinScope)
return state(layer, node, {
status: "not-observed-in-capture",
runtimeNodeIds: [],
reason: "not-observed-in-bounded-capture",
});
return state(layer, node, {
status: "unknown",
runtimeNodeIds: [],
reason: !nodeWithinScope
? "layer-outside-runtime-scope"
: "static-or-runtime-coverage-incomplete",
});
});
return { states };
};
const residentNodes = (
layer: ParsedStaticLayer,
directlyLoaded: ReadonlySet<string>,
): ReadonlySet<string> => {
const nodeKinds = new Map(
layer.graph.nodes.map(({ node_id: id, kind }) => [id, kind]),
);
const children = new Map<string, string[]>();
for (const edge of layer.graph.edges)
if (edge.relation === "contains")
append(children, edge.source_node_id, edge.target_node_id);
const pending = [...directlyLoaded].filter(
(nodeId) => nodeKinds.get(nodeId) === "javascript-asset",
);
const resident = new Set<string>();
for (let index = 0; index < pending.length; index += 1) {
const current = pending[index];
if (current === undefined) break;
for (const child of children.get(current) ?? []) {
if (resident.has(child)) continue;
resident.add(child);
pending.push(child);
}
}
return resident;
};
const append = (
values: Map<string, string[]>,
key: string,
value: string,
): void => {
const current = values.get(key);
if (current === undefined) values.set(key, [value]);
else current.push(value);
};
const captureScriptsComplete = (
evidenceId: string,
entities: readonly RuntimeReconciliationEntity[],
): boolean =>
entities.find(({ capture }) => capture.evidence.evidence_id === evidenceId)
?.capture.scriptsCompleteWithinScope === true;
const isLoadStateNode = (
node: ApplicationNode,
): node is ApplicationNode & {
readonly kind: "javascript-asset" | "javascript-chunk" | "javascript-module";
} =>
node.kind === "javascript-asset" ||
node.kind === "javascript-chunk" ||
node.kind === "javascript-module";
const state = (
layer: ParsedStaticLayer,
node: ApplicationNode & {
readonly kind:
| "javascript-asset"
| "javascript-chunk"
| "javascript-module";
},
input: {
readonly status: JavaScriptStaticLoadState["status"];
readonly runtimeNodeIds: readonly string[];
readonly reason: JavaScriptStaticLoadState["reason"];
},
): JavaScriptStaticLoadState => ({
static_layer_id: layer.layerId,
static_node_id: node.node_id,
kind: node.kind,
status: input.status,
runtime_node_ids: [...input.runtimeNodeIds],
reason: input.reason,
});
@@ -0,0 +1,157 @@
import { z } from "zod";
import { browserEndpointSchema } from "../browserObservation.js";
import { prefixedDigestSchema } from "../digests.js";
const observationTextSchema = z.string().min(1);
const runtimeEndpoint = {
inspector_endpoint: browserEndpointSchema,
};
/** Input for listing targets exposed by an explicit Node/Electron Inspector endpoint. */
export const listJavaScriptRuntimeTargetsInputSchema = z.strictObject({
...runtimeEndpoint,
});
export type ListJavaScriptRuntimeTargetsInput = z.infer<
typeof listJavaScriptRuntimeTargetsInputSchema
>;
export const javascriptRuntimeKindSchema = z.enum([
"node",
"electron-main",
"electron-preload",
"electron-renderer",
]);
const observedJavaScriptRuntimeKindSchema = javascriptRuntimeKindSchema.or(
z.literal("unknown"),
);
/** Input for one bounded, attach-only V8 Inspector observation. */
/** Input for one passive attach-only V8 Inspector observation. */
export const observeJavaScriptRuntimeInputSchema = z.strictObject({
...runtimeEndpoint,
target_id: z.string().trim().min(1),
runtime_kind: javascriptRuntimeKindSchema.optional(),
observation_ms: z.number().int().min(0).default(100),
});
export type ObserveJavaScriptRuntimeInput = z.infer<
typeof observeJavaScriptRuntimeInputSchema
>;
export const javascriptRuntimeVersionSchema = z.strictObject({
product: z.string().min(1),
protocol_version: z.string().min(1),
v8_version: z.string().nullable(),
});
export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
kind: z.literal("file"),
file_path: z.string().min(1),
authority: z.literal("scope-fallback").optional(),
}),
z.strictObject({
kind: z.literal("url"),
origin: z.string().min(1),
sanitized_url: z.string().min(1),
}),
z.strictObject({
kind: z.literal("builtin"),
specifier: z.string().min(1),
}),
]);
export type JavaScriptRuntimeLocation = z.infer<
typeof javascriptRuntimeLocationSchema
>;
/** Discovery metadata can identify an endpoint target without verifying its file location. */
export const javascriptRuntimeUnresolvedLocationSchema = z.strictObject({
kind: z.literal("unresolved"),
reported_url: z.string().min(1),
reason: z.literal("unverifiable-file-location"),
});
/** Verified locations and explicitly unresolved discovery metadata. */
export const javascriptRuntimeTargetLocationSchema = z.union([
javascriptRuntimeLocationSchema,
javascriptRuntimeUnresolvedLocationSchema,
]);
export type JavaScriptRuntimeTargetLocation = z.infer<
typeof javascriptRuntimeTargetLocationSchema
>;
const javascriptRuntimeTargetSchema = z.strictObject({
target_id: z.string().min(1),
protocol_type: z.string().min(1),
attached: z.boolean(),
location: javascriptRuntimeTargetLocationSchema,
});
/** Complete V8 Inspector target inventory exposed by the selected endpoint. */
export const javascriptRuntimeTargetListSchema = z.strictObject({
runtime: javascriptRuntimeVersionSchema,
targets: z.array(javascriptRuntimeTargetSchema),
excluded: z.strictObject({
unsupported_location: z.number().int().min(0),
unconnectable: z.number().int().min(0),
}),
limitations: z.array(observationTextSchema),
});
export type JavaScriptRuntimeTargetList = z.infer<
typeof javascriptRuntimeTargetListSchema
>;
const javascriptRuntimeScriptSchema = z.strictObject({
script_key: prefixedDigestSchema("v8_script"),
location: javascriptRuntimeLocationSchema,
execution_context_key: z.string().nullable(),
cdp_hash: z.string().nullable(),
length: z.number().int().min(0),
is_module: z.boolean(),
status: z.literal("observed-loaded"),
});
const javascriptRuntimeContextSchema = z.strictObject({
context_key: z.string().min(1),
state: z.enum(["created", "destroyed", "cleared"]),
name: z.string().nullable(),
origin: z.string().nullable(),
});
/** Deterministic passive script/context snapshot from one bounded window. */
export const javascriptRuntimeObservationSchema = z.strictObject({
runtime: javascriptRuntimeVersionSchema,
target: javascriptRuntimeTargetSchema.extend({
runtime_kind: observedJavaScriptRuntimeKindSchema,
runtime_kind_authority: z.enum([
"caller-declared-unverified",
"not-declared",
]),
}),
capture: z.strictObject({
observation_ms: z.number().int().min(0),
events_observed: z.number().int().min(0),
events_retained: z.number().int().min(0),
events_dropped: z.number().int().min(0),
metadata_bytes_retained: z.number().int().min(0),
truncated: z.boolean(),
truncation_reasons: z.array(observationTextSchema),
}),
scripts: z.strictObject({
items: z.array(javascriptRuntimeScriptSchema),
observed_total: z.number().int().min(0),
excluded: z.strictObject({
unsupported_location: z.number().int().min(0),
invalid_protocol_value: z.number().int().min(0),
}),
}),
execution_contexts: z.array(javascriptRuntimeContextSchema),
directly_observed: z.array(observationTextSchema),
unavailable_without_instrumentation: z.array(observationTextSchema),
unknowns: z.array(observationTextSchema),
limitations: z.array(observationTextSchema),
});
export type JavaScriptRuntimeObservation = z.infer<
typeof javascriptRuntimeObservationSchema
>;
@@ -0,0 +1,53 @@
import { classifyStaticLoadStates } from "./javascriptRuntimeLoadState.js";
import { buildReconciledApplicationGraph } from "./javascriptRuntimeReconciliationGraph.js";
import { reconcileRuntimeEntities } from "./javascriptRuntimeReconciliationMatching.js";
import {
parseRuntimeCaptures,
parseStaticLayers,
} from "./javascriptRuntimeReconciliationParsing.js";
import { createJavaScriptRuntimeReconciliationResult } from "./javascriptRuntimeReconciliationResult.js";
import type { JavaScriptRuntimeReconciliationResult } from "./javascriptRuntimeReconciliationSchemas.js";
import { reconcileJavaScriptRuntimeInputSchema } from "./javascriptRuntimeReconciliationSchemas.js";
import { projectRuntimeCaptures } from "./javascriptRuntimeReconciliationRuntime.js";
import { collectStaticRuntimeCandidates } from "./javascriptRuntimeStaticCandidates.js";
/** Reconcile static JAG layers with authorized passive CDP Evidence. */
export const reconcileJavaScriptRuntime = (
input: unknown,
): JavaScriptRuntimeReconciliationResult => {
const parsed = reconcileJavaScriptRuntimeInputSchema.parse(input);
const layers = parseStaticLayers(parsed.static_layers);
const captures = parseRuntimeCaptures(parsed.runtime_observations);
const runtime = projectRuntimeCaptures(captures);
const candidates = collectStaticRuntimeCandidates(layers);
const matching = reconcileRuntimeEntities({
entities: runtime.entities,
candidates,
layers,
});
const loadStates = classifyStaticLoadStates(
layers,
runtime.entities,
matching.items,
{
reconciliationComplete:
runtime.omittedEntities === 0 && matching.omittedItems === 0,
},
);
const graph = buildReconciledApplicationGraph({
layers,
captures,
runtime,
reconciliationEdges: matching.edges,
omittedReconciliationItems: matching.omittedItems,
});
return createJavaScriptRuntimeReconciliationResult({
layers,
captures,
runtime,
matching,
loadStates,
graph: graph.graph,
omittedGraphItems: graph.omittedGraphItems,
});
};
@@ -0,0 +1,116 @@
import { isAbsolute } from "node:path";
import { canonicalDigest } from "../comparisonSemantics.js";
import { isPathWithinRoot } from "../localPath.js";
import { z } from "zod";
import {
classifyBrowserCompleteness,
type BrowserCompleteness,
} from "../browserCompleteness.js";
import {
electronActiveObservationResultSchema,
type ElectronActiveObservationResult,
} from "./electronActiveObservation.js";
import type { Evidence } from "../evidence.js";
import type { ParsedRuntimeCapture } from "./javascriptRuntimeReconciliationParsing.js";
/** Parse active Electron Evidence as a bounded, target-only runtime capture. */
export const parseActiveElectronCapture = (
evidence: Evidence,
): ParsedRuntimeCapture => {
assertIdentity(evidence);
const result = electronActiveObservationResultSchema.parse(
evidence.normalized_result,
);
const parameters = z
.object({
application_path: absolutePathSchema,
application_root: absolutePathSchema,
})
.passthrough()
.parse(evidence.parameters);
if (
result.application.application_path !== parameters.application_path ||
!isPathWithinRoot(
parameters.application_root,
result.application.application_path,
)
)
throw new TypeError(
"Active Electron Evidence application path disagrees with its configured root",
);
return {
kind: "electron-active",
evidence,
inspection: normalizeInspection(result),
captureSha256: canonicalDigest(result, "Runtime reconciliation"),
scriptsCompleteWithinScope: false,
};
};
const absolutePathSchema = z.string().min(1).refine(isAbsolute);
const assertIdentity = (evidence: Evidence): void => {
if (
evidence.operation !== "capture_electron_scenario" ||
evidence.predicate_type !== "rea.electron-active-scenario" ||
evidence.provider.id !== "rea-playwright-electron-active" ||
evidence.provider.name !==
"REA Playwright active Electron observation provider" ||
evidence.provider.version !== "1" ||
evidence.authority !== "controlled-replay" ||
evidence.confidence !== "observed"
)
throw new TypeError(
"Evidence does not match the supported capture_electron_scenario contract",
);
};
const normalizeInspection = (
result: ElectronActiveObservationResult,
): {
readonly target: {
readonly target_id: string;
readonly type: string;
readonly title: string;
readonly attached: boolean;
readonly file_path: string;
};
readonly frames: readonly [];
readonly scripts: { readonly items: readonly [] };
readonly workers: readonly [];
readonly completeness: BrowserCompleteness;
} => ({
target: {
target_id: `electron-active:${canonicalDigest(result.application.application_path, "Runtime reconciliation").slice(0, 32)}`,
type: "electron-application",
title: result.application.application_path,
attached: true,
file_path: result.application.application_path,
},
frames: [],
scripts: { items: [] },
workers: [],
completeness: classifyBrowserCompleteness({
policyFilteredSections: new Set(),
attachLimitedSections: new Set(),
truncatedSections: new Set(),
unavailableSections: new Set([
"frames",
"scripts",
"script_sources",
"workers",
]),
excluded: [],
droppedEvents: {
scripts: 0,
network_requests: 0,
console_events: 0,
websocket_connections: 0,
websocket_frames: 0,
webmcp_tools: 0,
timeline_events: 0,
},
}),
});
@@ -0,0 +1,248 @@
import {
createJavaScriptApplicationGraph,
createJavaScriptApplicationNode,
type ApplicationEdge,
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import type {
ParsedRuntimeCapture,
ParsedStaticLayer,
} from "./javascriptRuntimeReconciliationParsing.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { RuntimeProjection } from "./javascriptRuntimeReconciliationRuntime.js";
interface ReconciledGraphInput {
readonly layers: readonly ParsedStaticLayer[];
readonly captures: readonly ParsedRuntimeCapture[];
readonly runtime: RuntimeProjection;
readonly reconciliationEdges: readonly ApplicationEdge[];
readonly omittedReconciliationItems: number;
}
interface GraphCoverageFacts {
readonly projectionOmissions: number;
readonly knownOmissions: number;
readonly omissionsKnown: boolean;
readonly inputStatus: "complete" | "partial" | "truncated";
readonly outputTruncated: boolean;
}
/** Combined graph plus omissions introduced while merging its observations. */
export interface ReconciledApplicationGraphProjection {
readonly graph: JavaScriptApplicationGraph;
readonly omittedGraphItems: number;
}
/** Merge source graphs, runtime nodes, and inferred mappings into one valid JAG. */
export const buildReconciledApplicationGraph = (
input: ReconciledGraphInput,
): ReconciledApplicationGraphProjection => {
const merged = mergeNodes([
...input.layers.flatMap(({ graph }) => graph.nodes),
...input.runtime.nodes,
]);
const allEdges = uniqueEdges([
...input.layers.flatMap(({ graph }) => graph.edges),
...input.runtime.edges,
...input.reconciliationEdges,
]);
const bounded = boundGraphContent(input, merged, allEdges);
const facts = graphCoverageFacts(input, bounded.omittedItems);
const graph = createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: bounded.rootNodeIds,
nodes: bounded.nodes,
edges: bounded.edges,
coverage: graphCoverage(input, facts, bounded.nodes.length),
limitations: uniqueSorted([
...input.layers.flatMap(({ graph }) => graph.limitations),
"Runtime presence is bounded to passive capture windows and does not prove feature execution.",
"Cross-layer observed_as edges are inferences; digest equality proves byte identity only.",
"Source-map relationships retain their original static authority and are not promoted into runtime matches.",
...(facts.inputStatus === "truncated"
? [
"One or more source graphs or passive captures were incomplete or truncated.",
]
: []),
...(facts.outputTruncated
? [
"The reconciled graph omitted entities or classifications during projection.",
]
: []),
]),
});
return {
graph,
omittedGraphItems: bounded.omittedItems,
};
};
const boundGraphContent = (
input: ReconciledGraphInput,
nodes: readonly ApplicationNode[],
edges: readonly ApplicationEdge[],
): {
readonly rootNodeIds: string[];
readonly nodes: ApplicationNode[];
readonly edges: ApplicationEdge[];
readonly omittedItems: number;
} => {
const allRoots = preferredRootIds(input);
const rootNodeIds = allRoots;
const sortedNodes = [...nodes].sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
);
const retainedNodes = sortedNodes;
const retainedIds = new Set(retainedNodes.map(({ node_id: id }) => id));
const retainedEdges = [...edges]
.sort((left, right) => compareCodePoints(left.edge_id, right.edge_id))
.filter(
({ source_node_id: source, target_node_id: target }) =>
retainedIds.has(source) && retainedIds.has(target),
);
return {
rootNodeIds,
nodes: retainedNodes,
edges: retainedEdges,
omittedItems: 0,
};
};
const preferredRootIds = (input: ReconciledGraphInput): string[] => {
const runtime = [...input.runtime.targetNodeByEvidenceId.values()].map(
({ node_id: id }) => id,
);
const application = input.layers
.filter(({ role }) => role === "application")
.flatMap(({ graph }) => graph.root_node_ids);
const supplemental = input.layers
.filter(({ role }) => role !== "application")
.flatMap(({ graph }) => graph.root_node_ids);
return [...new Set([...runtime, ...application, ...supplemental])];
};
const graphCoverageFacts = (
input: ReconciledGraphInput,
omittedNodeObservations: number,
): GraphCoverageFacts => {
const projectionOmissions =
input.runtime.omittedEntities +
input.omittedReconciliationItems +
omittedNodeObservations;
const captureTruncated = input.captures.some(({ inspection }) =>
inspection.completeness.conditions.includes("truncated"),
);
const captureHasUnknownOmissions = input.captures.some(
({ inspection }) => inspection.completeness.unavailable_sections.length > 0,
);
const inputTruncated =
input.layers.some(({ graph }) => graph.coverage.truncated) ||
captureTruncated;
const inputComplete =
input.layers.every(({ graph }) => graph.coverage.status === "complete") &&
input.captures.every(
({ inspection }) =>
inspection.completeness.status === "complete_within_window",
);
const outputTruncated = projectionOmissions > 0;
const sourceOmissions = input.layers.reduce(
(total, { graph }) => total + (graph.coverage.omitted_count ?? 0),
0,
);
const omissionsKnown =
!captureTruncated &&
!captureHasUnknownOmissions &&
input.layers.every(({ graph }) => graph.coverage.omitted_count !== null);
return {
projectionOmissions,
knownOmissions: projectionOmissions + sourceOmissions,
omissionsKnown,
inputStatus: inputTruncated
? "truncated"
: inputComplete
? "complete"
: "partial",
outputTruncated,
};
};
const graphCoverage = (
input: ReconciledGraphInput,
facts: GraphCoverageFacts,
nodeCount: number,
): JavaScriptApplicationGraph["coverage"] =>
facts.inputStatus === "complete" && !facts.outputTruncated
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: facts.inputStatus === "truncated" || facts.outputTruncated
? {
status: "partial",
truncated: true,
omitted_count: facts.omissionsKnown ? facts.knownOmissions : null,
limits: [
...(facts.inputStatus === "truncated"
? [
{
name: "runtime-reconciliation-input-coverage",
value: input.layers.length + input.captures.length,
unit: "items" as const,
},
]
: []),
...(facts.outputTruncated
? [
{
name: "runtime-reconciliation-output-limits",
value: nodeCount,
unit: "items" as const,
},
]
: []),
],
}
: {
status: "partial",
truncated: false,
omitted_count: facts.omissionsKnown ? facts.knownOmissions : null,
limits: [],
};
const mergeNodes = (nodes: readonly ApplicationNode[]): ApplicationNode[] => {
const grouped = new Map<string, ApplicationNode[]>();
for (const node of nodes)
grouped.set(node.node_id, [...(grouped.get(node.node_id) ?? []), node]);
const merged = [...grouped.values()].map((group) => {
const first = group[0];
if (first === undefined) throw new TypeError("Empty JAG node group");
if (
group.some(
({ kind, identity }) =>
kind !== first.kind ||
JSON.stringify(identity) !== JSON.stringify(first.identity),
)
)
throw new TypeError("Colliding JAG node identifiers disagree");
const observations = [
...new Map(
group
.flatMap(({ observations: values }) => values)
.map((observation) => [observation.observation_id, observation]),
).values(),
].sort((left, right) =>
compareCodePoints(left.observation_id, right.observation_id),
);
return createJavaScriptApplicationNode({
kind: first.kind,
identity: first.identity,
observations: observations.map(
({ observation_id: _id, identifier_strategy: _strategy, ...value }) =>
value,
),
});
});
return merged;
};
const uniqueEdges = (edges: readonly ApplicationEdge[]): ApplicationEdge[] => [
...new Map(edges.map((edge) => [edge.edge_id, edge])).values(),
];
@@ -0,0 +1,431 @@
import {
createJavaScriptApplicationEdge,
type ApplicationEdge,
type ApplicationGraphEvidence,
} from "./javascriptApplicationGraph.js";
import { canonicalDigest } from "../comparisonSemantics.js";
import type { ParsedStaticLayer } from "./javascriptRuntimeReconciliationParsing.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import type { JavaScriptRuntimeReconciliationItem } from "./javascriptRuntimeReconciliationSchemas.js";
import type { RuntimeReconciliationEntity } from "./javascriptRuntimeReconciliationRuntime.js";
import {
mappedRuntimePaths,
type MappedRuntimePath,
type StaticRuntimeCandidate,
} from "./javascriptRuntimeStaticCandidates.js";
export interface RuntimeMatchingProjection {
readonly items: readonly JavaScriptRuntimeReconciliationItem[];
readonly edges: readonly ApplicationEdge[];
readonly omittedItems: number;
}
/** Match runtime entities conservatively and emit only inferred observed_as edges. */
export const reconcileRuntimeEntities = (input: {
readonly entities: readonly RuntimeReconciliationEntity[];
readonly candidates: readonly StaticRuntimeCandidate[];
readonly layers: readonly ParsedStaticLayer[];
}): RuntimeMatchingProjection => {
const index = indexCandidates(input.candidates);
const evaluated = input.entities.map((entity) =>
reconcileEntity(entity, index, input.layers),
);
const retained = evaluated.sort((left, right) =>
compareCodePoints(
left.item.reconciliation_id,
right.item.reconciliation_id,
),
);
return {
items: retained.map(({ item }) => item),
edges: retained.flatMap(({ edge }) => (edge === null ? [] : [edge])),
omittedItems: 0,
};
};
interface EvaluatedMatch {
readonly item: JavaScriptRuntimeReconciliationItem;
readonly edge: ApplicationEdge | null;
}
interface CandidateIndex {
readonly byCategoryDigest: ReadonlyMap<
string,
readonly StaticRuntimeCandidate[]
>;
readonly byLayerCategoryPath: ReadonlyMap<
string,
readonly StaticRuntimeCandidate[]
>;
}
const reconcileEntity = (
entity: RuntimeReconciliationEntity,
index: CandidateIndex,
layers: readonly ParsedStaticLayer[],
): EvaluatedMatch => {
if (entity.location.kind === "unresolved")
return unresolved(entity, {
status: "unknown",
basis: "none",
confidence: "unknown",
reason: "runtime-location-unresolved",
candidates: [],
});
const locations = candidatesWithLocation(entity, index, layers);
if (entity.sourceSha256 !== null) {
const content =
index.byCategoryDigest.get(
categoryDigestKey(entity.staticKind, entity.sourceSha256),
) ?? [];
const locatedKeys = new Set(
locations.map(({ candidate }) => candidateKey(candidate)),
);
const combined = content.filter((candidate) =>
locatedKeys.has(candidateKey(candidate)),
);
const combinedCandidate = combined.at(0);
if (combined.length === 1 && combinedCandidate !== undefined)
return matched(entity, combinedCandidate, {
basis: "content-and-location",
confidence: "high",
reason: "content-and-location-match",
});
const contentCandidate = content.at(0);
if (content.length === 1 && contentCandidate !== undefined) {
const candidate = contentCandidate;
const digestBasis = candidate.digests.find(
({ sha256 }) => sha256 === entity.sourceSha256,
)?.basis;
return matched(entity, candidate, {
basis: digestBasis ?? "content-sha256",
confidence: "high",
reason: "unique-content-match",
});
}
if (content.length > 1)
return unresolved(entity, {
status: "ambiguous",
basis: "none",
confidence: "unknown",
reason: "ambiguous-static-candidates",
candidates: content,
});
if (locations.length > 0)
return unresolved(entity, {
status: "unmatched",
basis: strongestLocationBasis(locations),
confidence: "high",
reason: "captured-content-disagrees-with-static-location",
candidates: locations.map(({ candidate }) => candidate),
});
return unresolved(entity, {
status: "unmatched",
basis: "none",
confidence: "high",
reason: "no-static-content-match",
candidates: [],
});
}
const location = locations.at(0);
if (locations.length === 1 && location !== undefined) {
const located = location;
return matched(entity, located.candidate, {
basis: located.mapping.basis,
confidence: "medium",
reason: "unique-location-match",
});
}
if (locations.length > 1)
return unresolved(entity, {
status: "ambiguous",
basis: strongestLocationBasis(locations),
confidence: "unknown",
reason: "ambiguous-static-candidates",
candidates: locations.map(({ candidate }) => candidate),
});
const mapped = layers.some(
(layer) => mappedRuntimePaths(layer, entity).length > 0,
);
return unresolved(entity, {
status: mapped ? "unmatched" : "unknown",
basis: "none",
confidence: "unknown",
reason: mapped
? "no-static-content-match"
: "no-authorized-location-mapping",
candidates: [],
});
};
interface LocatedCandidate {
readonly candidate: StaticRuntimeCandidate;
readonly mapping: MappedRuntimePath;
}
const candidatesWithLocation = (
entity: RuntimeReconciliationEntity,
index: CandidateIndex,
layers: readonly ParsedStaticLayer[],
): LocatedCandidate[] => {
const located = new Map<string, LocatedCandidate>();
for (const layer of layers)
for (const mapping of mappedRuntimePaths(layer, entity))
for (const candidate of index.byLayerCategoryPath.get(
layerCategoryPathKey(layer.layerId, entity.staticKind, mapping.path),
) ?? []) {
const key = candidateKey(candidate);
if (!located.has(key)) located.set(key, { candidate, mapping });
}
return [...located.values()].sort((left, right) =>
compareCodePoints(
candidateKey(left.candidate),
candidateKey(right.candidate),
),
);
};
const indexCandidates = (
candidates: readonly StaticRuntimeCandidate[],
): CandidateIndex => {
const byCategoryDigest = new Map<string, StaticRuntimeCandidate[]>();
const byLayerCategoryPath = new Map<string, StaticRuntimeCandidate[]>();
for (const candidate of candidates) {
for (const { sha256 } of candidate.digests)
appendIndex(
byCategoryDigest,
categoryDigestKey(candidate.category, sha256),
candidate,
);
for (const path of candidate.paths)
appendIndex(
byLayerCategoryPath,
layerCategoryPathKey(candidate.layer.layerId, candidate.category, path),
candidate,
);
}
return { byCategoryDigest, byLayerCategoryPath };
};
const appendIndex = (
index: Map<string, StaticRuntimeCandidate[]>,
key: string,
candidate: StaticRuntimeCandidate,
): void => {
const values = index.get(key);
if (values === undefined) index.set(key, [candidate]);
else values.push(candidate);
};
const categoryDigestKey = (category: string, digest: string): string =>
`${category}\0${digest}`;
const layerCategoryPathKey = (
layerId: string,
category: string,
path: string,
): string => `${layerId}\0${category}\0${path}`;
const matched = (
entity: RuntimeReconciliationEntity,
candidate: StaticRuntimeCandidate,
input: Pick<ItemInput, "basis" | "confidence" | "reason">,
): EvaluatedMatch => {
const item = createItem(entity, {
layer: candidate.layer,
staticNodeId: candidate.node.node_id,
status: "matched",
basis: input.basis,
confidence: input.confidence,
reason: input.reason,
candidates: [candidate],
});
return {
item,
edge: createJavaScriptApplicationEdge({
source_node_id: candidate.node.node_id,
target_node_id: entity.node.node_id,
relation: "observed_as",
properties: {
reconciliation_id: item.reconciliation_id,
basis: input.basis,
static_layer_id: candidate.layer.layerId,
},
evidence: reconciliationEvidence(
entity,
candidate.layer,
input.basis,
input.confidence,
),
}),
};
};
const unresolved = (
entity: RuntimeReconciliationEntity,
input: Pick<ItemInput, "basis" | "confidence" | "reason" | "candidates"> & {
readonly status: Exclude<
JavaScriptRuntimeReconciliationItem["status"],
"matched"
>;
},
): EvaluatedMatch => ({
item: createItem(entity, {
layer: null,
staticNodeId: null,
status: input.status,
basis: input.basis,
confidence: input.confidence,
reason: input.reason,
candidates: input.candidates,
}),
edge: null,
});
type ItemInput = {
readonly basis: JavaScriptRuntimeReconciliationItem["basis"];
readonly confidence: JavaScriptRuntimeReconciliationItem["confidence"];
readonly reason: JavaScriptRuntimeReconciliationItem["reason"];
readonly candidates: readonly StaticRuntimeCandidate[];
} & (
| {
readonly layer: ParsedStaticLayer;
readonly staticNodeId: string;
readonly status: "matched";
}
| {
readonly layer: null;
readonly staticNodeId: null;
readonly status: Exclude<
JavaScriptRuntimeReconciliationItem["status"],
"matched"
>;
}
);
const createItem = (
entity: RuntimeReconciliationEntity,
input: ItemInput,
): JavaScriptRuntimeReconciliationItem => {
const candidateReferences = uniqueCandidateReferences(input.candidates);
const staticMatch =
input.status === "matched"
? {
static_layer_id: input.layer.layerId,
static_node_id: input.staticNodeId,
status: input.status,
}
: {
static_layer_id: null,
static_node_id: null,
status: input.status,
};
const semantic = {
entity_kind: entity.kind,
runtime_evidence_id: entity.capture.evidence.evidence_id,
runtime_node_id: entity.node.node_id,
...staticMatch,
basis: input.basis,
confidence: input.confidence,
reason: input.reason,
candidate_static_count: candidateReferences.count,
candidate_static_nodes: candidateReferences.items,
} satisfies Omit<JavaScriptRuntimeReconciliationItem, "reconciliation_id">;
return {
reconciliation_id: `jrr_item_${canonicalDigest(semantic, "Runtime reconciliation")}`,
...semantic,
};
};
const reconciliationEvidence = (
entity: RuntimeReconciliationEntity,
layer: ParsedStaticLayer,
basis: JavaScriptRuntimeReconciliationItem["basis"],
confidence: JavaScriptRuntimeReconciliationItem["confidence"],
): ApplicationGraphEvidence => {
const observation = entity.node.observations.at(0);
if (observation === undefined)
throw new TypeError("Runtime reconciliation entity has no observation");
return {
authority: "cross-layer-reconciliation",
state: "inferred",
confidence: confidence === "medium" ? "medium" : "high",
artifact:
entity.sourceSha256 === null
? {
available: false,
reason: "not-observed",
detail: "Runtime source bytes were not captured for this mapping.",
}
: {
available: true,
artifact_id: `art_${entity.sourceSha256}`,
sha256: entity.sourceSha256,
},
location: observation.evidence.location,
extractor: {
name: "rea-javascript-runtime-reconciliation",
version: "1",
operation: "reconcile_javascript_runtime",
executable_sha256: null,
},
coverage:
layer.graph.coverage.status === "complete" &&
entity.capture.scriptsCompleteWithinScope
? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
: {
status: "partial",
truncated: false,
omitted_count: null,
limits: [],
},
limitations: [
basis === "content-sha256" ||
basis === "module-source-sha256" ||
basis === "content-and-location"
? "Equal content digests establish byte identity, not execution causality."
: "Location correspondence is inferred from an artifact root or caller-declared mapping.",
"Passive script parsing or target presence does not prove feature execution.",
],
evidence_ids: [
layer.evidence.evidence_id,
entity.capture.evidence.evidence_id,
].sort(),
};
};
const strongestLocationBasis = (
values: readonly LocatedCandidate[],
): JavaScriptRuntimeReconciliationItem["basis"] => {
const bases = new Set(values.map(({ mapping }) => mapping.basis));
if (bases.has("artifact-path")) return "artifact-path";
if (bases.has("operator-file-mapping")) return "operator-file-mapping";
return "operator-url-mapping";
};
const candidateKey = (candidate: StaticRuntimeCandidate): string =>
`${candidate.layer.layerId}:${candidate.node.node_id}`;
const uniqueCandidateReferences = (
candidates: readonly StaticRuntimeCandidate[],
): {
readonly count: number;
readonly items: JavaScriptRuntimeReconciliationItem["candidate_static_nodes"];
} => {
const seen = new Set<string>();
let count = 0;
const items: JavaScriptRuntimeReconciliationItem["candidate_static_nodes"] =
[];
for (const { layer, node } of candidates) {
const key = `${layer.layerId}:${node.node_id}`;
if (seen.has(key)) continue;
seen.add(key);
count += 1;
items.push({
static_layer_id: layer.layerId,
static_node_id: node.node_id,
});
}
return { count, items };
};
@@ -0,0 +1,464 @@
import { z } from "zod";
import {
browserAllowedOriginsSchema,
browserEndpointSchema,
webPageInspectionSchema,
type WebPageInspection,
} from "../browserObservation.js";
import {
classifyBrowserCompleteness,
type BrowserCompleteness,
} from "../browserCompleteness.js";
import {
electronPageInspectionSchema,
type ElectronPageInspection,
} from "./electronObservation.js";
import {
javascriptRuntimeObservationSchema,
javascriptRuntimeKindSchema,
type JavaScriptRuntimeObservation,
type JavaScriptRuntimeLocation,
} from "./javascriptRuntimeObservation.js";
import { canonicalDigest } from "../comparisonSemantics.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { parseEvidence, type Evidence } from "../evidence.js";
import {
javascriptApplicationAnalysisResultSchema,
type JavaScriptApplicationAnalysisResult,
} from "./javascriptApplicationAnalysis.js";
import { type JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
import { parseActiveElectronCapture } from "./javascriptRuntimeReconciliationActive.js";
import type { ReconcileJavaScriptRuntimeInput } from "./javascriptRuntimeReconciliationSchemas.js";
type StaticLayerInput =
ReconcileJavaScriptRuntimeInput["static_layers"][number];
type RuntimeMapping = StaticLayerInput["runtime_mappings"][number];
export interface ParsedStaticLayer {
readonly layerId: string;
readonly role: StaticLayerInput["role"];
readonly evidence: Evidence;
readonly result: JavaScriptApplicationAnalysisResult;
readonly graph: JavaScriptApplicationGraph;
readonly runtimeMappings: readonly RuntimeMapping[];
}
interface RuntimeCaptureBase {
readonly evidence: Evidence;
readonly captureSha256: string;
readonly scriptsCompleteWithinScope: boolean;
}
interface NormalizedV8Inspection {
readonly target:
| {
readonly target_id: string;
readonly type: string;
readonly title: string;
readonly attached: boolean;
readonly file_path: string;
}
| {
readonly target_id: string;
readonly type: string;
readonly title: string;
readonly attached: boolean;
readonly url: string;
}
| {
readonly target_id: string;
readonly type: string;
readonly title: string;
readonly attached: boolean;
readonly unresolved_location: Extract<
JavaScriptRuntimeObservation["target"]["location"],
{ kind: "unresolved" }
>;
};
readonly frames: readonly [];
readonly scripts: {
readonly items: readonly (Readonly<{
script_key: string;
frame_id: string | null;
cdp_hash: string;
length: number;
is_module: boolean;
language: null;
source: { readonly included: false; readonly reason: string };
}> &
({ readonly file_path: string } | { readonly url: string }))[];
};
readonly workers: readonly [];
readonly completeness: BrowserCompleteness;
}
export type ParsedRuntimeCapture =
| (RuntimeCaptureBase & {
readonly kind: "browser";
readonly inspection: WebPageInspection;
})
| (RuntimeCaptureBase & {
readonly kind: "electron";
readonly inspection: ElectronPageInspection;
})
| (RuntimeCaptureBase & {
readonly kind: "v8-inspector";
readonly inspection: NormalizedV8Inspection;
})
| (RuntimeCaptureBase & {
readonly kind: "electron-active";
readonly inspection: {
readonly target: {
readonly target_id: string;
readonly type: string;
readonly title: string;
readonly attached: boolean;
readonly file_path: string;
};
readonly frames: readonly [];
readonly scripts: { readonly items: readonly [] };
readonly workers: readonly [];
readonly completeness: BrowserCompleteness;
};
});
/** Parse and semantically bind every static analysis Evidence layer. */
export const parseStaticLayers = (
layers: readonly StaticLayerInput[],
): ParsedStaticLayer[] =>
layers
.map((layer) => parseStaticLayer(layer))
.sort((left, right) => compareCodePoints(left.layerId, right.layerId));
/** Parse only supported passive web/Electron inspection Evidence. */
export const parseRuntimeCaptures = (
observations: readonly Evidence[],
): ParsedRuntimeCapture[] =>
observations
.map((observation) => parseRuntimeCapture(observation))
.sort((left, right) =>
compareCodePoints(left.evidence.evidence_id, right.evidence.evidence_id),
);
const parseStaticLayer = (layer: StaticLayerInput): ParsedStaticLayer => {
const evidence = parseEvidence(layer.analysis);
const result = javascriptApplicationAnalysisResultSchema.parse(
evidence.normalized_result,
);
assertEvidenceIdentity(evidence, {
operation: "analyze_javascript_application",
predicate: "rea.javascript-application-analysis",
providerId: "rea-javascript-application",
providerName: "REA JavaScript application analyzer",
providerVersion: "1",
authority: "shipped-artifact",
confidence: "derived",
});
if (
evidence.subject === null ||
evidence.subject.digest.sha256 !== result.root_artifact_sha256 ||
evidence.subject.format !== result.format ||
evidence.subject.local_path !== result.input_path
)
throw new TypeError(
"JavaScript application Evidence subject disagrees with its result",
);
return {
layerId: `jrl_${canonicalDigest(
{
role: layer.role,
evidence_id: evidence.evidence_id,
runtime_mappings: layer.runtime_mappings,
},
"Runtime reconciliation",
)}`,
role: layer.role,
evidence,
result,
graph: result.graph,
runtimeMappings: layer.runtime_mappings,
};
};
const parseRuntimeCapture = (input: Evidence): ParsedRuntimeCapture => {
const evidence = parseEvidence(input);
if (evidence.operation === "inspect_web_page") {
assertEvidenceIdentity(evidence, {
operation: "inspect_web_page",
predicate: "rea.web-page-inspection",
providerId: "rea-cdp-browser",
providerName: "REA Chrome DevTools Protocol observation provider",
providerVersion: "2",
authority: "external-service",
confidence: "observed",
});
const inspection = webPageInspectionSchema.parse(
evidence.normalized_result,
);
assertRuntimeParameters(evidence, {
kind: "browser",
targetId: inspection.target.target_id,
targetOrigin: inspection.target.origin,
sourceIncluded: inspection.scripts.items.some(
({ source }) => source.included,
),
});
return {
kind: "browser",
evidence,
inspection,
captureSha256: canonicalDigest(inspection, "Runtime reconciliation"),
scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
};
}
if (evidence.operation === "inspect_electron_page") {
assertEvidenceIdentity(evidence, {
operation: "inspect_electron_page",
predicate: "rea.electron-page-inspection",
providerId: "rea-cdp-electron",
providerName: "REA Electron file-page CDP observation provider",
providerVersion: "1",
authority: "external-service",
confidence: "observed",
});
const inspection = electronPageInspectionSchema.parse(
evidence.normalized_result,
);
assertRuntimeParameters(evidence, {
kind: "electron",
targetId: inspection.target.target_id,
sourceIncluded: inspection.scripts.items.some(
({ source }) => source.included,
),
});
return {
kind: "electron",
evidence,
inspection,
captureSha256: canonicalDigest(inspection, "Runtime reconciliation"),
scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
};
}
if (evidence.operation === "observe_javascript_runtime") {
assertEvidenceIdentity(evidence, {
operation: "observe_javascript_runtime",
predicate: "rea.javascript-runtime-observation",
providerId: "rea-v8-inspector",
providerName: "REA passive Node/Electron V8 Inspector provider",
providerVersion: "1",
authority: "external-service",
confidence: "observed",
});
const result = javascriptRuntimeObservationSchema.parse(
evidence.normalized_result,
);
assertV8RuntimeParameters(evidence, result);
const inspection = normalizeV8Inspection(result);
return {
kind: "v8-inspector",
evidence,
inspection,
captureSha256: canonicalDigest(result, "Runtime reconciliation"),
scriptsCompleteWithinScope: false,
};
}
if (evidence.operation === "capture_electron_scenario") {
return parseActiveElectronCapture(evidence);
}
throw new TypeError(
"Runtime reconciliation requires inspect_web_page, inspect_electron_page, observe_javascript_runtime, or capture_electron_scenario Evidence",
);
};
const assertV8RuntimeParameters = (
evidence: Evidence,
result: JavaScriptRuntimeObservation,
): void => {
const parameters = z
.object({
inspector_endpoint: browserEndpointSchema,
target_id: z.string().trim().min(1),
runtime_kind: javascriptRuntimeKindSchema.optional(),
})
.passthrough()
.parse(evidence.parameters);
if (
parameters.target_id !== result.target.target_id ||
(parameters.runtime_kind !== undefined &&
parameters.runtime_kind !== result.target.runtime_kind)
)
throw new TypeError(
"Runtime Evidence target or declared role disagrees with its result",
);
for (const location of [
result.target.location,
...result.scripts.items.map(({ location }) => location),
])
if (location.kind === "builtin" && !location.specifier.startsWith("node:"))
throw new TypeError(
"Runtime Evidence contains an invalid builtin location",
);
};
const normalizeV8Inspection = (
result: JavaScriptRuntimeObservation,
): NormalizedV8Inspection => ({
target: {
target_id: result.target.target_id,
type: result.target.protocol_type,
title: result.target.runtime_kind,
attached: result.target.attached,
...(result.target.location.kind === "unresolved"
? { unresolved_location: result.target.location }
: runtimeLocation(result.target.location)),
},
frames: [],
scripts: {
items: result.scripts.items.map((script) => ({
script_key: script.script_key,
frame_id: script.execution_context_key,
...runtimeLocation(script.location),
cdp_hash: script.cdp_hash ?? "",
length: script.length,
is_module: script.is_module,
language: null,
source: {
included: false,
reason: "V8 Inspector source capture is outside passive authority.",
},
})),
},
workers: [],
completeness: classifyBrowserCompleteness({
policyFilteredSections: new Set(
excludedV8Scripts(result) > 0 ? ["scripts"] : [],
),
attachLimitedSections: new Set([
"frames",
"scripts",
"script_sources",
"workers",
]),
truncatedSections: new Set(result.capture.truncated ? ["scripts"] : []),
unavailableSections: new Set(["frames", "script_sources", "workers"]),
excluded:
excludedV8Scripts(result) === 0
? []
: [
{
section: "scripts",
reason: "out_of_target_scope",
count: excludedV8Scripts(result),
},
],
droppedEvents: {
scripts: result.capture.events_dropped,
network_requests: 0,
console_events: 0,
websocket_connections: 0,
websocket_frames: 0,
webmcp_tools: 0,
timeline_events: 0,
},
}),
});
const runtimeLocation = (
location: JavaScriptRuntimeLocation,
): { readonly file_path: string } | { readonly url: string } => {
if (location.kind === "file") return { file_path: location.file_path };
if (location.kind === "url") return { url: location.sanitized_url };
return { url: location.specifier };
};
const excludedV8Scripts = (result: JavaScriptRuntimeObservation): number =>
Object.values(result.scripts.excluded).reduce(
(total, count) => total + count,
0,
);
const assertRuntimeParameters = (
evidence: Evidence,
expected:
| {
readonly kind: "browser";
readonly targetId: string;
readonly targetOrigin: string;
readonly sourceIncluded: boolean;
}
| {
readonly kind: "electron";
readonly targetId: string;
readonly sourceIncluded: boolean;
},
): void => {
const common = {
target_id: z.string().trim().min(1),
cdp_endpoint: browserEndpointSchema,
include_script_sources: z.boolean(),
};
if (expected.kind === "browser") {
const parameters = z
.object({ ...common, allowed_origins: browserAllowedOriginsSchema })
.passthrough()
.parse(evidence.parameters);
if (parameters.target_id !== expected.targetId)
throw new TypeError(
"Runtime Evidence target disagrees with its captured result",
);
if (!parameters.allowed_origins.includes(expected.targetOrigin))
throw new TypeError(
"Browser Evidence target is outside its recorded origin scope",
);
if (expected.sourceIncluded && !parameters.include_script_sources)
throw new TypeError(
"Runtime Evidence contains source without source-capture selection",
);
return;
}
const parameters = z.object(common).passthrough().parse(evidence.parameters);
if (parameters.target_id !== expected.targetId)
throw new TypeError(
"Runtime Evidence target disagrees with its captured result",
);
if (expected.sourceIncluded && !parameters.include_script_sources)
throw new TypeError(
"Runtime Evidence contains source without source-capture selection",
);
};
const scriptsComplete = (completeness: {
readonly truncated_sections: readonly string[];
readonly unavailable_sections: readonly string[];
readonly dropped_events: { readonly scripts: number };
}): boolean =>
!completeness.truncated_sections.includes("scripts") &&
!completeness.unavailable_sections.includes("scripts") &&
completeness.dropped_events.scripts === 0;
const assertEvidenceIdentity = (
evidence: Evidence,
expected: {
readonly operation: string;
readonly predicate: string;
readonly providerId: string;
readonly providerName: string;
readonly providerVersion: string;
readonly authority: Evidence["authority"];
readonly confidence: Evidence["confidence"];
},
): void => {
if (
evidence.operation !== expected.operation ||
evidence.predicate_type !== expected.predicate ||
evidence.provider.id !== expected.providerId ||
evidence.provider.name !== expected.providerName ||
evidence.provider.version !== expected.providerVersion ||
evidence.authority !== expected.authority ||
evidence.confidence !== expected.confidence
)
throw new TypeError(
`Evidence does not match the supported ${expected.operation} contract`,
);
};
@@ -0,0 +1,210 @@
import { type JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
import { canonicalDigest } from "../comparisonSemantics.js";
import { uniqueSorted } from "../canonicalOrdering.js";
import type { StaticLoadStateProjection } from "./javascriptRuntimeLoadState.js";
import type { RuntimeMatchingProjection } from "./javascriptRuntimeReconciliationMatching.js";
import type {
ParsedRuntimeCapture,
ParsedStaticLayer,
} from "./javascriptRuntimeReconciliationParsing.js";
import {
javascriptRuntimeReconciliationResultSchema,
type JavaScriptRuntimeReconciliationResult,
} from "./javascriptRuntimeReconciliationSchemas.js";
import type { RuntimeProjection } from "./javascriptRuntimeReconciliationRuntime.js";
interface ReconciliationProjection {
readonly layers: readonly ParsedStaticLayer[];
readonly captures: readonly ParsedRuntimeCapture[];
readonly runtime: RuntimeProjection;
readonly matching: RuntimeMatchingProjection;
readonly loadStates: StaticLoadStateProjection;
readonly graph: JavaScriptApplicationGraph;
readonly omittedGraphItems: number;
}
interface CompletionFlags {
readonly outputTruncated: boolean;
readonly inputStatus: "complete" | "partial" | "truncated";
}
/** Build and verify the deterministic caller-visible reconciliation result. */
export const createJavaScriptRuntimeReconciliationResult = (
input: ReconciliationProjection,
): JavaScriptRuntimeReconciliationResult => {
const completion = completionFlags(input);
const semantic = {
static_layers: staticLayerSummaries(input.layers),
runtime_captures: captureSummaries(input.captures, input.runtime),
graph: input.graph,
summary: reconciliationSummary(input),
reconciliations: input.matching.items,
static_load_states: input.loadStates.states,
source_map_authority: sourceMapAuthority(input),
coverage: reconciliationCoverage(input, completion),
evidence_links: uniqueSorted([
...input.layers.map(({ evidence }) => evidence.evidence_id),
...input.captures.map(({ evidence }) => evidence.evidence_id),
]),
limitations: reconciliationLimitations(completion),
};
return javascriptRuntimeReconciliationResultSchema.parse({
reconciliation_id: `jrr_${canonicalDigest(semantic, "Runtime reconciliation")}`,
...semantic,
});
};
const staticLayerSummaries = (
layers: readonly ParsedStaticLayer[],
): JavaScriptRuntimeReconciliationResult["static_layers"] =>
layers.map((layer) => ({
layer_id: layer.layerId,
role: layer.role,
evidence_id: layer.evidence.evidence_id,
graph_id: layer.graph.graph_id,
root_artifact_sha256: layer.result.root_artifact_sha256,
input_path: layer.result.input_path,
format: layer.result.format,
runtime_mappings: [...layer.runtimeMappings],
}));
const captureSummaries = (
captures: readonly ParsedRuntimeCapture[],
runtime: RuntimeProjection,
): JavaScriptRuntimeReconciliationResult["runtime_captures"] =>
captures.map((capture) => {
const targetNode = runtime.targetNodeByEvidenceId.get(
capture.evidence.evidence_id,
);
if (targetNode === undefined)
throw new TypeError("Runtime projection omitted a required target node");
return {
evidence_id: capture.evidence.evidence_id,
capture_sha256: capture.captureSha256,
kind: capture.kind,
target_node_id: targetNode.node_id,
target_key: capture.inspection.target.target_id,
target_location:
"unresolved_location" in capture.inspection.target
? capture.inspection.target.unresolved_location
: "url" in capture.inspection.target
? capture.inspection.target.url
: capture.inspection.target.file_path,
frames: capture.inspection.frames.length,
scripts: capture.inspection.scripts.items.length,
workers: capture.inspection.workers.length,
scripts_complete_within_scope: capture.scriptsCompleteWithinScope,
};
});
const reconciliationSummary = (
input: ReconciliationProjection,
): JavaScriptRuntimeReconciliationResult["summary"] => ({
runtime_targets: countBy(input.runtime.entities, "kind", "target"),
runtime_frames: countBy(input.runtime.entities, "kind", "frame"),
runtime_scripts: countBy(input.runtime.entities, "kind", "script"),
runtime_workers: countBy(input.runtime.entities, "kind", "worker"),
matched: countBy(input.matching.items, "status", "matched"),
ambiguous: countBy(input.matching.items, "status", "ambiguous"),
unmatched: countBy(input.matching.items, "status", "unmatched"),
unknown: countBy(input.matching.items, "status", "unknown"),
static_loaded: countBy(input.loadStates.states, "status", "loaded"),
static_resident: countBy(
input.loadStates.states,
"status",
"resident-in-loaded-asset",
),
static_not_observed: countBy(
input.loadStates.states,
"status",
"not-observed-in-capture",
),
static_unknown: countBy(input.loadStates.states, "status", "unknown"),
});
const sourceMapAuthority = (
input: ReconciliationProjection,
): JavaScriptRuntimeReconciliationResult["source_map_authority"] => ({
used_for_primary_matching: false,
static_layer_count: input.layers.length,
runtime_script_declarations: input.captures.reduce(
(total, capture) =>
total +
(capture.kind === "browser"
? capture.inspection.scripts.items.filter(
({ source_map_url: url }) => url !== null,
).length
: 0),
0,
),
limitation:
"Source-map declarations and original-source content retain separate static authority and are not used as primary runtime byte matches.",
});
const reconciliationCoverage = (
input: ReconciliationProjection,
completion: CompletionFlags,
): JavaScriptRuntimeReconciliationResult["coverage"] => ({
status:
completion.outputTruncated || completion.inputStatus === "truncated"
? "truncated"
: completion.inputStatus === "partial"
? "partial"
: "complete-within-inputs",
truncated:
completion.outputTruncated || completion.inputStatus === "truncated",
omitted_runtime_entities: input.runtime.omittedEntities,
omitted_reconciliation_items: input.matching.omittedItems,
omitted_static_load_states: input.loadStates.omittedStates,
omitted_graph_items: input.omittedGraphItems,
});
const completionFlags = (input: ReconciliationProjection): CompletionFlags => {
const inputTruncated =
input.layers.some(({ graph }) => graph.coverage.truncated) ||
input.captures.some(({ inspection }) =>
inspection.completeness.conditions.includes("truncated"),
);
const inputPartial =
input.layers.some(({ graph }) => graph.coverage.status !== "complete") ||
input.captures.some(
({ inspection }) =>
inspection.completeness.status !== "complete_within_window",
);
return {
outputTruncated:
input.runtime.omittedEntities > 0 ||
input.matching.omittedItems > 0 ||
input.loadStates.omittedStates > 0 ||
input.omittedGraphItems > 0,
inputStatus: inputTruncated
? "truncated"
: inputPartial
? "partial"
: "complete",
};
};
const reconciliationLimitations = (completion: CompletionFlags): string[] =>
uniqueSorted([
"Only caller-supplied, semantically verified Evidence records were reconciled.",
"Digest equality establishes byte identity but not code reachability, module initialization, or feature execution.",
"A static module resident in an observed bundle is not reported as executed.",
"Not-observed means absent from the bounded captures in scope, never globally unloaded.",
"Caller-declared file and URL mappings are inference inputs and do not expand CDP origin or filesystem-root authority.",
"Source-map authority remains separate from passive runtime authority.",
...(completion.inputStatus !== "complete"
? ["One or more static graphs or passive captures were incomplete."]
: []),
...(completion.outputTruncated
? [
"Runtime reconciliation omitted entities or classifications during projection.",
]
: []),
]);
const countBy = <Item extends Record<Key, string>, Key extends keyof Item>(
items: readonly Item[],
key: Key,
value: Item[Key],
): number => items.filter((item) => item[key] === value).length;
@@ -0,0 +1,438 @@
import type { JsonValue } from "../jsonValue.js";
import {
createJavaScriptApplicationEdge,
createJavaScriptApplicationNode,
type ApplicationEdge,
type ApplicationGraphEvidence,
type ApplicationNode,
} from "./javascriptApplicationGraph.js";
import type { ParsedRuntimeCapture } from "./javascriptRuntimeReconciliationParsing.js";
export interface RuntimeReconciliationEntity {
readonly kind: "target" | "frame" | "script" | "worker";
readonly section: "target" | "frames" | "scripts" | "workers";
readonly node: ApplicationNode;
readonly capture: ParsedRuntimeCapture;
readonly runtimeKey: string;
readonly location: {
readonly kind: "file" | "url" | "unresolved";
readonly value: string;
};
readonly frameKey: string | null;
readonly sourceSha256: string | null;
readonly staticKind: "renderer" | "javascript" | "worker" | "service-worker";
}
export interface RuntimeProjection {
readonly entities: readonly RuntimeReconciliationEntity[];
readonly nodes: readonly ApplicationNode[];
readonly edges: readonly ApplicationEdge[];
readonly targetNodeByEvidenceId: ReadonlyMap<string, ApplicationNode>;
readonly omittedEntities: number;
}
/** Project authorized passive capture metadata into capture-scoped JAG nodes. */
export const projectRuntimeCaptures = (
captures: readonly ParsedRuntimeCapture[],
): RuntimeProjection => {
const all = captures.flatMap(projectCapture);
const retained = all;
const retainedIds = new Set(retained.map(({ node }) => node.node_id));
const nodes = retained.map(({ node }) => node);
const edges = captures
.flatMap((capture) => runtimeEdges(capture, all))
.filter(
({ source_node_id: source, target_node_id: target }) =>
retainedIds.has(source) && retainedIds.has(target),
);
const targetNodeByEvidenceId = new Map(
retained
.filter(({ kind }) => kind === "target")
.map(({ capture, node }) => [capture.evidence.evidence_id, node]),
);
return {
entities: retained,
nodes,
edges,
targetNodeByEvidenceId,
omittedEntities: 0,
};
};
const projectCapture = (
capture: ParsedRuntimeCapture,
): RuntimeReconciliationEntity[] => {
const target = targetEntity(capture);
return [
target,
...frameEntities(capture),
...scriptEntities(capture),
...workerEntities(capture),
];
};
const targetEntity = (
capture: ParsedRuntimeCapture,
): RuntimeReconciliationEntity => {
const target = capture.inspection.target;
const location =
"unresolved_location" in target
? ({
kind: "unresolved",
value: target.unresolved_location.reported_url,
} as const)
: "url" in target
? ({ kind: "url", value: target.url } as const)
: ({ kind: "file", value: target.file_path } as const);
return runtimeEntity(capture, {
kind: "target",
nodeKind: "target",
runtimeKey: target.target_id,
targetKey: target.target_id,
frameKey: null,
scriptKey: null,
location,
staticKind: "renderer",
sourceSha256: null,
label: target.title,
properties: {
runtime_type: target.type,
...(location.kind === "unresolved"
? {
reported_url: location.value,
location_kind: "unresolved",
location_reason: "unverifiable-file-location",
}
: { location: location.value }),
attached: target.attached,
},
section: "target",
});
};
const frameEntities = (
capture: ParsedRuntimeCapture,
): RuntimeReconciliationEntity[] =>
capture.inspection.frames.map((frame) => {
const location =
"url" in frame
? ({ kind: "url", value: frame.url } as const)
: ({ kind: "file", value: frame.file_path } as const);
return runtimeEntity(capture, {
kind: "frame",
nodeKind: "frame",
runtimeKey: frame.frame_id,
targetKey: capture.inspection.target.target_id,
frameKey: frame.frame_id,
scriptKey: null,
location,
staticKind: "renderer",
sourceSha256: null,
label: location.value,
properties: {
parent_frame_id: frame.parent_frame_id,
location: location.value,
},
section: "frames",
});
});
const scriptEntities = (
capture: ParsedRuntimeCapture,
): RuntimeReconciliationEntity[] =>
capture.inspection.scripts.items.map((script) => {
const location =
"url" in script
? ({ kind: "url", value: script.url } as const)
: ({ kind: "file", value: script.file_path } as const);
return runtimeEntity(capture, {
kind: "script",
nodeKind: "runtime-script-instance",
runtimeKey: script.script_key,
targetKey: capture.inspection.target.target_id,
frameKey: script.frame_id,
scriptKey: script.script_key,
location,
staticKind: "javascript",
sourceSha256: script.source.included
? script.source.artifact.sha256
: null,
label: location.value,
properties: {
location: location.value,
cdp_hash: script.cdp_hash,
length: script.length,
is_module: script.is_module,
language: script.language,
source_sha256: script.source.included
? script.source.artifact.sha256
: null,
...("source_map_url" in script
? { source_map_url: script.source_map_url }
: {}),
},
section: "scripts",
...(script.source.included
? { artifactSha256: script.source.artifact.sha256 }
: {}),
});
});
const workerEntities = (
capture: ParsedRuntimeCapture,
): RuntimeReconciliationEntity[] =>
capture.inspection.workers.map((worker) => {
const location =
"url" in worker
? ({ kind: "url", value: worker.url } as const)
: ({ kind: "file", value: worker.file_path } as const);
const serviceWorker = worker.type.includes("service");
return runtimeEntity(capture, {
kind: "worker",
nodeKind: serviceWorker ? "service-worker" : "worker",
runtimeKey: worker.target_id,
targetKey: worker.target_id,
frameKey: worker.parent_frame_id,
scriptKey: null,
location,
staticKind: serviceWorker ? "service-worker" : "worker",
sourceSha256: null,
label: location.value,
properties: {
runtime_type: worker.type,
location: location.value,
attached: worker.attached,
opener_target_id: worker.opener_target_id,
parent_frame_id: worker.parent_frame_id,
},
section: "workers",
});
});
interface RuntimeEntityInput {
readonly kind: RuntimeReconciliationEntity["kind"];
readonly nodeKind: ApplicationNode["kind"];
readonly runtimeKey: string;
readonly targetKey: string;
readonly frameKey: string | null;
readonly scriptKey: string | null;
readonly location: RuntimeReconciliationEntity["location"];
readonly staticKind: RuntimeReconciliationEntity["staticKind"];
readonly sourceSha256: string | null;
readonly label: string;
readonly properties: Readonly<Record<string, JsonValue>>;
readonly section: "target" | "frames" | "scripts" | "workers";
readonly artifactSha256?: string;
}
const runtimeEntity = (
capture: ParsedRuntimeCapture,
input: RuntimeEntityInput,
): RuntimeReconciliationEntity => ({
kind: input.kind,
section: input.section,
capture,
runtimeKey: input.runtimeKey,
location: input.location,
frameKey: input.frameKey,
sourceSha256: input.sourceSha256,
staticKind: input.staticKind,
node: createJavaScriptApplicationNode({
kind: input.nodeKind,
identity: {
strategy: "runtime-instance",
stability: "capture-only",
capture_sha256: capture.captureSha256,
runtime_key: input.runtimeKey,
},
observations: [
{
label: input.label || null,
properties: input.properties,
evidence: runtimeEvidence(capture, input),
},
],
}),
});
const runtimeEvidence = (
capture: ParsedRuntimeCapture,
input: RuntimeEntityInput,
): ApplicationGraphEvidence => ({
authority: "passive-cdp-runtime",
state: "observed",
confidence: "exact",
artifact:
input.artifactSha256 === undefined
? {
available: false,
reason:
input.section === "scripts" ? "not-observed" : "not-applicable",
detail:
input.section === "scripts"
? "Script source bytes were not included in this passive capture."
: "This runtime entity has no standalone artifact bytes.",
}
: {
available: true,
artifact_id: `art_${input.artifactSha256}`,
sha256: input.artifactSha256,
},
location: {
available: true,
value: {
kind: "runtime",
capture_sha256: capture.captureSha256,
target_key: input.targetKey,
frame_key: input.frameKey,
script_key: input.scriptKey,
},
},
extractor: {
name: capture.evidence.provider.id,
version:
capture.evidence.provider.version ??
(capture.kind === "browser" ? "2" : "1"),
operation: capture.evidence.operation,
executable_sha256: null,
},
coverage: runtimeSectionCoverage(capture, input.section),
limitations: [
"The entity was observed only within one bounded passive CDP capture.",
...(runtimeSectionComplete(capture, input.section)
? []
: [
`The runtime ${input.section} inventory was incomplete within this capture.`,
]),
],
evidence_ids: [capture.evidence.evidence_id],
});
const runtimeEdges = (
capture: ParsedRuntimeCapture,
entities: readonly RuntimeReconciliationEntity[],
): ApplicationEdge[] => {
const local = entities.filter(
({ capture: candidate }) =>
candidate.evidence.evidence_id === capture.evidence.evidence_id,
);
const target = local.find(({ kind }) => kind === "target");
if (target === undefined) return [];
const frames = new Map(
local
.filter(({ kind }) => kind === "frame")
.map((entity) => [entity.runtimeKey, entity]),
);
return local.flatMap((entity) => {
if (entity === target) return [];
const parent =
(entity.kind === "script" || entity.kind === "worker") &&
entity.frameKey !== null
? (frames.get(entity.frameKey) ?? target)
: target;
return [
createJavaScriptApplicationEdge({
source_node_id: parent.node.node_id,
target_node_id: entity.node.node_id,
relation: entity.kind === "script" ? "loads" : "contains",
properties: { basis: "passive-cdp-observation" },
evidence: runtimeRelationshipEvidence(capture, entity),
}),
];
});
};
const runtimeRelationshipEvidence = (
capture: ParsedRuntimeCapture,
entity: RuntimeReconciliationEntity,
): ApplicationGraphEvidence => ({
authority: "passive-cdp-runtime",
state: "observed",
confidence: "exact",
artifact: {
available: false,
reason: "not-applicable",
detail: "The relationship is runtime metadata, not standalone bytes.",
},
location: {
available: true,
value: {
kind: "runtime",
capture_sha256: capture.captureSha256,
target_key: capture.inspection.target.target_id,
frame_key: entity.frameKey,
script_key: entity.kind === "script" ? entity.runtimeKey : null,
},
},
extractor: {
name: capture.evidence.provider.id,
version:
capture.evidence.provider.version ??
(capture.kind === "browser" ? "2" : "1"),
operation: capture.evidence.operation,
executable_sha256: null,
},
coverage: runtimeSectionCoverage(capture, entity.section),
limitations: [
"The relationship was observed only within one bounded passive CDP capture.",
],
evidence_ids: [capture.evidence.evidence_id],
});
const runtimeSectionComplete = (
capture: ParsedRuntimeCapture,
section: RuntimeEntityInput["section"],
): boolean => {
if (section === "target") return true;
if (section === "scripts") return capture.scriptsCompleteWithinScope;
return (
!capture.inspection.completeness.truncated_sections.includes(section) &&
!capture.inspection.completeness.unavailable_sections.includes(section)
);
};
const runtimeSectionCoverage = (
capture: ParsedRuntimeCapture,
section: RuntimeEntityInput["section"],
): ApplicationGraphEvidence["coverage"] => {
if (runtimeSectionComplete(capture, section))
return {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
};
const truncated =
section !== "target" &&
capture.inspection.completeness.truncated_sections.includes(section);
return {
status: "partial",
truncated,
omitted_count: null,
limits: truncated
? [
{
name: `passive-cdp-${section}-limit`,
value: runtimeSectionCount(capture, section),
unit: "items",
},
]
: [],
};
};
const runtimeSectionCount = (
capture: ParsedRuntimeCapture,
section: RuntimeEntityInput["section"],
): number => {
switch (section) {
case "target":
return 1;
case "frames":
return capture.inspection.frames.length;
case "scripts":
return capture.inspection.scripts.items.length;
case "workers":
return capture.inspection.workers.length;
}
};
@@ -0,0 +1,283 @@
import { z } from "zod";
import { compareCodePoints } from "../canonicalOrdering.js";
import { evidenceSchema } from "../evidence.js";
import { javascriptRuntimeUnresolvedLocationSchema } from "./javascriptRuntimeObservation.js";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
const nodeIdSchema = prefixedDigestSchema("jag_node");
const boundedTextSchema = z.string().min(1);
const safePrefixSchema = z
.string()
.refine(
(value) =>
value === "" ||
(!value.startsWith("/") &&
!value.includes("\\") &&
value.split("/").every((part) => !["", ".", ".."].includes(part))),
"Artifact prefix must be empty or a safe relative POSIX path",
);
const runtimeFileMappingSchema = z.strictObject({
kind: z.literal("file-root"),
root: z.string().min(1),
artifact_prefix: safePrefixSchema.default(""),
});
const runtimeUrlMappingSchema = z.strictObject({
kind: z.literal("url-prefix"),
prefix: z
.string()
.min(1)
.refine(
(value) => normalizeRuntimeUrlPrefix(value) !== null,
"Runtime URL prefix must be HTTP(S) without credentials, query, or fragment",
)
.overwrite((value) => normalizeRuntimeUrlPrefix(value) ?? value),
artifact_prefix: safePrefixSchema.default(""),
});
const normalizeRuntimeUrlPrefix = (value: string): string | null => {
let url: URL;
try {
url = new URL(value);
} catch (cause: unknown) {
// Invalid input is represented by the null return.
void cause;
return null;
}
if (
!["http:", "https:"].includes(url.protocol) ||
url.username !== "" ||
url.password !== "" ||
url.search !== "" ||
url.hash !== ""
)
return null;
if (!url.pathname.endsWith("/")) url.pathname += "/";
return url.href;
};
/** Caller-declared translation from an authorized runtime location to a layer. */
const runtimeLocationMappingSchema = z.discriminatedUnion("kind", [
runtimeFileMappingSchema,
runtimeUrlMappingSchema,
]);
type RuntimeLocationMapping = z.infer<typeof runtimeLocationMappingSchema>;
const staticLayerSchema = z.strictObject({
role: z.enum(["application", "cache", "assets"]).default("application"),
analysis: evidenceSchema,
runtime_mappings: z
.array(runtimeLocationMappingSchema)
.overwrite(normalizeRuntimeMappings)
.default([]),
});
function normalizeRuntimeMappings(
mappings: RuntimeLocationMapping[],
): RuntimeLocationMapping[] {
return [
...new Map(
mappings.map((mapping) => [runtimeMappingKey(mapping), mapping]),
).values(),
].sort((left, right) =>
compareCodePoints(runtimeMappingKey(left), runtimeMappingKey(right)),
);
}
function runtimeMappingKey(mapping: RuntimeLocationMapping): string {
return mapping.kind === "file-root"
? `file-root\0${mapping.root}\0${mapping.artifact_prefix}`
: `url-prefix\0${mapping.prefix}\0${mapping.artifact_prefix}`;
}
/** Evidence-backed static layers and passive captures to reconcile. */
export const reconcileJavaScriptRuntimeInputSchema = z
.strictObject({
static_layers: z.array(staticLayerSchema).min(1),
runtime_observations: z.array(evidenceSchema).min(1),
})
.superRefine((input, context) => {
if (
input.static_layers.filter(({ role }) => role === "application")
.length !== 1
)
context.addIssue({
code: "custom",
path: ["static_layers"],
message: "Exactly one application static layer is required",
});
const staticIds = input.static_layers.map(
({ analysis }) => analysis.evidence_id,
);
if (new Set(staticIds).size !== staticIds.length)
context.addIssue({
code: "custom",
path: ["static_layers"],
message: "Static layer Evidence must be unique",
});
const runtimeIds = input.runtime_observations.map(
({ evidence_id: id }) => id,
);
if (new Set(runtimeIds).size !== runtimeIds.length)
context.addIssue({
code: "custom",
path: ["runtime_observations"],
message: "Runtime observation Evidence must be unique",
});
});
const layerSummarySchema = z.strictObject({
layer_id: prefixedDigestSchema("jrl"),
role: z.enum(["application", "cache", "assets"]),
evidence_id: evidenceIdSchema,
graph_id: prefixedDigestSchema("jag"),
root_artifact_sha256: digestSchema,
input_path: z.string().min(1),
format: z.enum(["asar", "directory"]),
runtime_mappings: z.array(runtimeLocationMappingSchema),
});
const captureSummarySchema = z.strictObject({
evidence_id: evidenceIdSchema,
capture_sha256: digestSchema,
kind: z.enum(["browser", "electron", "v8-inspector", "electron-active"]),
target_node_id: nodeIdSchema,
target_key: boundedTextSchema,
target_location: z
.string()
.min(1)
.or(javascriptRuntimeUnresolvedLocationSchema),
frames: z.number().int().min(0),
scripts: z.number().int().min(0),
workers: z.number().int().min(0),
scripts_complete_within_scope: z.boolean(),
});
const reconciliationReasonSchema = z.enum([
"content-and-location-match",
"unique-content-match",
"unique-location-match",
"ambiguous-static-candidates",
"captured-content-disagrees-with-static-location",
"no-static-content-match",
"no-authorized-location-mapping",
"runtime-location-unresolved",
"runtime-frame-unattributed",
"static-or-runtime-coverage-incomplete",
"reconciliation-limit-reached",
]);
const reconciliationItemShape = {
reconciliation_id: prefixedDigestSchema("jrr_item"),
entity_kind: z.enum(["target", "frame", "script", "worker"]),
runtime_evidence_id: evidenceIdSchema,
runtime_node_id: nodeIdSchema,
basis: z.enum([
"content-and-location",
"content-sha256",
"module-source-sha256",
"artifact-path",
"operator-file-mapping",
"operator-url-mapping",
"none",
]),
confidence: z.enum(["exact", "high", "medium", "low", "unknown"]),
reason: reconciliationReasonSchema,
candidate_static_count: z.number().int().min(0),
candidate_static_nodes: z.array(
z.strictObject({
static_layer_id: prefixedDigestSchema("jrl"),
static_node_id: nodeIdSchema,
}),
),
};
const reconciliationItemSchema = z.union([
z.strictObject({
...reconciliationItemShape,
static_layer_id: prefixedDigestSchema("jrl"),
static_node_id: nodeIdSchema,
status: z.literal("matched"),
}),
z.strictObject({
...reconciliationItemShape,
static_layer_id: z.null(),
static_node_id: z.null(),
status: z.enum(["ambiguous", "unmatched", "unknown"]),
}),
]);
const staticLoadStateSchema = z.strictObject({
static_layer_id: prefixedDigestSchema("jrl"),
static_node_id: nodeIdSchema,
kind: z.enum(["javascript-asset", "javascript-chunk", "javascript-module"]),
status: z.enum([
"loaded",
"resident-in-loaded-asset",
"not-observed-in-capture",
"unknown",
]),
runtime_node_ids: z.array(nodeIdSchema),
reason: z.enum([
"runtime-script-correspondence",
"containing-asset-was-loaded",
"not-observed-in-bounded-capture",
"layer-outside-runtime-scope",
"static-or-runtime-coverage-incomplete",
]),
});
/** Deterministic static/passive-runtime reconciliation with a combined JAG. */
export const javascriptRuntimeReconciliationResultSchema = z.strictObject({
reconciliation_id: prefixedDigestSchema("jrr"),
static_layers: z.array(layerSummarySchema).min(1),
runtime_captures: z.array(captureSummarySchema).min(1),
graph: javascriptApplicationGraphSchema,
summary: z.strictObject({
runtime_targets: z.number().int().min(0),
runtime_frames: z.number().int().min(0),
runtime_scripts: z.number().int().min(0),
runtime_workers: z.number().int().min(0),
matched: z.number().int().min(0),
ambiguous: z.number().int().min(0),
unmatched: z.number().int().min(0),
unknown: z.number().int().min(0),
static_loaded: z.number().int().min(0),
static_resident: z.number().int().min(0),
static_not_observed: z.number().int().min(0),
static_unknown: z.number().int().min(0),
}),
reconciliations: z.array(reconciliationItemSchema),
static_load_states: z.array(staticLoadStateSchema),
source_map_authority: z.strictObject({
used_for_primary_matching: z.literal(false),
static_layer_count: z.number().int().min(0),
runtime_script_declarations: z.number().int().min(0),
limitation: boundedTextSchema,
}),
coverage: z.strictObject({
status: z.enum(["complete-within-inputs", "partial", "truncated"]),
truncated: z.boolean(),
omitted_runtime_entities: z.number().int().min(0),
omitted_reconciliation_items: z.number().int().min(0),
omitted_static_load_states: z.number().int().min(0),
omitted_graph_items: z.number().int().min(0),
}),
evidence_links: z.array(evidenceIdSchema).min(2),
limitations: z.array(boundedTextSchema),
});
export type ReconcileJavaScriptRuntimeInput = z.infer<
typeof reconcileJavaScriptRuntimeInputSchema
>;
export type JavaScriptRuntimeReconciliationResult = z.infer<
typeof javascriptRuntimeReconciliationResultSchema
>;
export type JavaScriptRuntimeReconciliationItem = z.infer<
typeof reconciliationItemSchema
>;
export type JavaScriptStaticLoadState = z.infer<typeof staticLoadStateSchema>;
@@ -0,0 +1,322 @@
import { posix, relative, win32 } from "node:path";
import {
type ApplicationNode,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { ParsedStaticLayer } from "./javascriptRuntimeReconciliationParsing.js";
import type { RuntimeReconciliationEntity } from "./javascriptRuntimeReconciliationRuntime.js";
export interface StaticRuntimeCandidate {
readonly layer: ParsedStaticLayer;
readonly node: ApplicationNode;
readonly category: "renderer" | "javascript" | "worker" | "service-worker";
readonly paths: readonly string[];
readonly digests: readonly {
readonly sha256: string;
readonly basis: "content-sha256" | "module-source-sha256";
}[];
}
export interface MappedRuntimePath {
readonly path: string;
readonly basis:
| "artifact-path"
| "operator-file-mapping"
| "operator-url-mapping";
}
/** Precomputed mapping scope and graph paths for static load-state decisions. */
export interface StaticRuntimeScope {
readonly artifactPrefixes: readonly string[];
readonly pathsByNodeId: ReadonlyMap<string, readonly string[]>;
}
/** Index statically reconstructed entities that can receive runtime matches. */
export const collectStaticRuntimeCandidates = (
layers: readonly ParsedStaticLayer[],
): StaticRuntimeCandidate[] =>
layers
.flatMap((layer) => candidatesForLayer(layer))
.sort(
(left, right) =>
compareCodePoints(left.layer.layerId, right.layer.layerId) ||
compareCodePoints(left.node.node_id, right.node.node_id),
);
/** Translate one already-authorized runtime location into artifact paths. */
export const mappedRuntimePaths = (
layer: ParsedStaticLayer,
entity: RuntimeReconciliationEntity,
): MappedRuntimePath[] => {
const paths: MappedRuntimePath[] = [];
if (entity.location.kind === "file" && layer.result.format === "directory") {
const path = pathBelowRoot(layer.result.input_path, entity.location.value);
if (path !== null) paths.push({ path, basis: "artifact-path" });
}
for (const mapping of layer.runtimeMappings) {
const suffix =
mapping.kind === "file-root" && entity.location.kind === "file"
? pathBelowRoot(mapping.root, entity.location.value)
: mapping.kind === "url-prefix" && entity.location.kind === "url"
? pathBelowUrlPrefix(mapping.prefix, entity.location.value)
: null;
if (suffix === null) continue;
const path = safeArtifactPath(mapping.artifact_prefix, suffix);
if (path === null) continue;
paths.push({
path,
basis:
mapping.kind === "file-root"
? "operator-file-mapping"
: "operator-url-mapping",
});
}
return uniqueMappedPaths(paths);
};
/** Precompute the artifact prefixes exercised by a bounded runtime set. */
export const createStaticRuntimeScope = (
layer: ParsedStaticLayer,
entities: readonly RuntimeReconciliationEntity[],
): StaticRuntimeScope => ({
artifactPrefixes: activeArtifactPrefixes(layer, entities),
pathsByNodeId: indexStaticPaths(layer.graph),
});
/** Whether one static node falls under a mapping exercised by this runtime set. */
export const staticNodeWithinRuntimeScope = (
node: ApplicationNode,
scope: StaticRuntimeScope,
): boolean =>
(scope.pathsByNodeId.get(node.node_id) ?? []).some((path) =>
scope.artifactPrefixes.some((prefix) => pathWithinPrefix(path, prefix)),
);
const candidatesForLayer = (
layer: ParsedStaticLayer,
): StaticRuntimeCandidate[] => {
const graph = layer.graph;
const pathsByNodeId = indexStaticPaths(graph);
return graph.nodes.flatMap((node) => {
const category = candidateCategory(node);
if (category === null) return [];
return [
{
layer,
node,
category,
paths: pathsByNodeId.get(node.node_id) ?? [],
digests: candidateDigests(node),
},
];
});
};
const candidateCategory = (
node: ApplicationNode,
): StaticRuntimeCandidate["category"] | null => {
if (node.kind === "electron-renderer") return "renderer";
if (
node.kind === "javascript-asset" ||
(node.kind === "javascript-module" && !isStaticSourceModule(node))
)
return "javascript";
if (node.kind === "worker") return "worker";
if (node.kind === "service-worker") return "service-worker";
return null;
};
const isStaticSourceModule = (node: ApplicationNode): boolean =>
node.observations.some(
({ properties }) => properties.semantic_role === "source-module",
);
const indexStaticPaths = (
graph: JavaScriptApplicationGraph,
): ReadonlyMap<string, readonly string[]> => {
const nodes = new Map(
graph.nodes.map((candidate) => [candidate.node_id, candidate]),
);
const relatedBySource = new Map<string, ApplicationNode[]>();
for (const edge of graph.edges) {
if (edge.relation !== "maps_to") continue;
const target = nodes.get(edge.target_node_id);
if (target === undefined) continue;
const related = relatedBySource.get(edge.source_node_id);
if (related === undefined)
relatedBySource.set(edge.source_node_id, [target]);
else related.push(target);
}
return new Map(
graph.nodes.map((node) => [
node.node_id,
uniqueSorted([
...nodePaths(node),
...(relatedBySource.get(node.node_id) ?? []).flatMap(nodePaths),
]),
]),
);
};
const nodePaths = (node: ApplicationNode): string[] => {
const paths: string[] = [];
if (node.identity.strategy === "canonical-path")
paths.push(node.identity.path);
for (const observation of node.observations) {
for (const property of ["path", "resolved_path", "declared_path"])
if (typeof observation.properties[property] === "string")
paths.push(observation.properties[property]);
if (
observation.evidence.location.available &&
observation.evidence.location.value.kind === "artifact-path"
)
paths.push(observation.evidence.location.value.path);
}
return paths
.map(normalizeArtifactPath)
.filter(
(path): path is string => path !== null && path !== "artifact-root",
);
};
const candidateDigests = (
node: ApplicationNode,
): StaticRuntimeCandidate["digests"] => {
const values: StaticRuntimeCandidate["digests"][number][] = [];
if (
node.kind === "javascript-asset" &&
node.identity.strategy === "content-digest"
)
values.push({
sha256: node.identity.sha256,
basis: "content-sha256",
});
if (node.kind === "javascript-module")
for (const observation of node.observations) {
const digest = observation.properties.source_sha256;
if (typeof digest === "string" && /^[a-f0-9]{64}$/u.test(digest))
values.push({ sha256: digest, basis: "module-source-sha256" });
}
return [
...new Map(
values.map((value) => [`${value.basis}:${value.sha256}`, value]),
).values(),
];
};
const pathBelowRoot = (root: string, value: string): string | null => {
const rootStyle = absoluteFilePathStyle(root);
if (rootStyle === null || rootStyle !== absoluteFilePathStyle(value))
return null;
const remainder =
rootStyle === "windows"
? win32.relative(root, value)
: relative(root, value);
const portableRemainder = remainder.replaceAll("\\", "/");
if (
remainder === "" ||
(rootStyle === "windows" && win32.isAbsolute(remainder)) ||
portableRemainder === ".." ||
portableRemainder.startsWith("../")
)
return null;
return normalizeArtifactPath(portableRemainder);
};
const absoluteFilePathStyle = (path: string): "posix" | "windows" | null => {
if (
/^[a-z]:[\\/]/iu.test(path) ||
/^(?:\\\\|\/\/)[^\\/]+[\\/][^\\/]+(?:[\\/]|$)/u.test(path)
)
return "windows";
return path.startsWith("/") ? "posix" : null;
};
const pathBelowUrlPrefix = (prefix: string, value: string): string | null => {
let base: URL;
let candidate: URL;
try {
base = new URL(prefix);
candidate = new URL(value);
} catch (cause: unknown) {
// Invalid input is represented by the null return.
void cause;
return null;
}
if (
base.origin !== candidate.origin ||
!candidate.pathname.startsWith(base.pathname)
)
return null;
try {
return normalizeArtifactPath(
decodeURIComponent(candidate.pathname.slice(base.pathname.length)),
);
} catch (cause: unknown) {
// Undecodable path segments are represented by the null return.
void cause;
return null;
}
};
const activeArtifactPrefixes = (
layer: ParsedStaticLayer,
entities: readonly RuntimeReconciliationEntity[],
): string[] => {
const prefixes = new Set<string>();
if (
layer.result.format === "directory" &&
entities.some(
({ location }) =>
location.kind === "file" &&
pathBelowRoot(layer.result.input_path, location.value) !== null,
)
)
prefixes.add("");
for (const mapping of layer.runtimeMappings)
if (
entities.some(({ location }) =>
mapping.kind === "file-root" && location.kind === "file"
? pathBelowRoot(mapping.root, location.value) !== null
: mapping.kind === "url-prefix" && location.kind === "url"
? pathBelowUrlPrefix(mapping.prefix, location.value) !== null
: false,
)
)
prefixes.add(mapping.artifact_prefix);
return [...prefixes].sort(compareCodePoints);
};
const pathWithinPrefix = (path: string, prefix: string): boolean =>
prefix === "" || path === prefix || path.startsWith(`${prefix}/`);
const safeArtifactPath = (prefix: string, suffix: string): string | null =>
normalizeArtifactPath(prefix === "" ? suffix : posix.join(prefix, suffix));
const normalizeArtifactPath = (value: string): string | null => {
const normalized = posix
.normalize(value.replaceAll("\\", "/"))
.replace(/^\.\//u, "");
return normalized !== "" &&
normalized !== "." &&
normalized !== ".." &&
!normalized.startsWith("/") &&
!normalized.startsWith("../")
? normalized
: null;
};
const uniqueMappedPaths = (
values: readonly MappedRuntimePath[],
): MappedRuntimePath[] =>
[
...new Map(
values.map((value) => [`${value.basis}:${value.path}`, value]),
).values(),
].sort(
(left, right) =>
compareCodePoints(left.path, right.path) ||
compareCodePoints(left.basis, right.basis),
);
@@ -0,0 +1,39 @@
import { expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
it.each(["namespace", "default", "named-default"])(
"retains Node built-in effects from %s imports",
(mode) => {
const imports = ["fs", "child_process", "timers", "http"]
.map((name, index) => {
const declaration =
mode === "namespace"
? `* as m${String(index)}`
: mode === "default"
? `m${String(index)}`
: `{default as m${String(index)}}`;
return `import ${declaration} from 'node:${name}';`;
})
.join("\n");
const ir = analyzeJavaScriptSemantics(`${imports}
const text = m0.readFileSync('config.json','utf8');
const stream = m0.createReadStream('config.json'); stream.destroy();
const child = m1.spawn('/usr/bin/tool', ['--version']);
const timer = m2.setTimeout(work,1000); m2.clearTimeout(timer);
const request = m3.get('http://localhost/');
`);
expect(ir.configurationOperations).toHaveLength(1);
expect(ir.resourceOperations).toHaveLength(2);
expect(ir.childProcessSpawns).toHaveLength(1);
expect(ir.timerOperations).toHaveLength(2);
expect(ir.requestOperations).toHaveLength(1);
},
);
it.each([
"import fs from './fs.js'; fs.createReadStream('config.json');",
"import {constants as fs} from 'node:fs'; fs.createReadStream('config.json');",
"function run(fs) { fs.createReadStream('config.json'); }",
])("does not invent a built-in namespace for %s", (source) => {
expect(analyzeJavaScriptSemantics(source).resourceOperations).toEqual([]);
});
@@ -0,0 +1,285 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import { semanticBinding } from "./javascriptSemanticIr.js";
import {
onlyCallable,
topLevelBinding,
} from "./javascriptSemanticAnalysis.fixture.js";
describe("JavaScript semantic analysis: calls 1", () => {
it("links exact local calls to parameters, returns, and closure captures", () => {
const ir = analyzeJavaScriptSemantics(`
const prefix = "rea";
function render(value, { mode }) {
return prefix + value + mode;
}
const alias = render;
const result = alias(input, { mode: "fast" });
`);
expect(ir.schema).toBe("JavaScriptSemanticIR");
const render = onlyCallable(ir, "render");
const call = ir.callSites.find(
({ calleeCallableIds }) => calleeCallableIds[0] === render.callableId,
);
expect(call).toMatchObject({
kind: "call",
callerCallableId: null,
resolution: "exact",
calleeCallableIds: [render.callableId],
arguments: [
{ index: 0, spread: false },
{ index: 1, spread: false },
],
});
if (call === undefined) throw new Error("Missing render call");
expect(
ir.argumentFlows
.filter(({ callSiteId }) => callSiteId === call.callSiteId)
.map(({ argumentIndex, parameterBindingId }) => ({
argumentIndex,
parameter: semanticBinding(ir, parameterBindingId)?.name,
})),
).toEqual([
{ argumentIndex: 0, parameter: "value" },
{ argumentIndex: 1, parameter: "mode" },
]);
expect(ir.callReturnFlows).toEqual([
expect.objectContaining({
callSiteId: call.callSiteId,
callableId: render.callableId,
returnSiteId: render.returnSites[0]?.returnSiteId,
}),
]);
expect(ir.closureCaptures).toEqual([
expect.objectContaining({
callableId: render.callableId,
bindingId: topLevelBinding(ir, "prefix").bindingId,
}),
]);
expect(ir.frontiers).toEqual([]);
});
it("recovers explicit Promise ownership, chains, aggregation, and awaits", () => {
const ir = analyzeJavaScriptSemantics(`
async function run(value) {
const base = Promise.resolve(value);
const chained = base.then(work).finally(cleanup);
await chained;
Promise.resolve(value).then(work);
return Promise.all([base, Promise.resolve(value)]);
}
const settled = Promise.allSettled([Promise.resolve(1)]);
`);
expect(
ir.promiseOperations.map(
({ kind, method, ownership, sourceResolution }) => ({
kind,
method,
ownership,
sourceResolution,
}),
),
).toEqual(
expect.arrayContaining([
{
kind: "static",
method: "resolve",
ownership: "assigned",
sourceResolution: "complete",
},
{
kind: "chain",
method: "then",
ownership: "chained",
sourceResolution: "complete",
},
{
kind: "chain",
method: "finally",
ownership: "assigned",
sourceResolution: "complete",
},
{
kind: "awaited-expression",
method: "await",
ownership: "awaited",
sourceResolution: "complete",
},
{
kind: "chain",
method: "then",
ownership: "detached",
sourceResolution: "complete",
},
{
kind: "aggregate",
method: "all",
ownership: "returned",
sourceResolution: "complete",
},
{
kind: "aggregate",
method: "allSettled",
ownership: "assigned",
sourceResolution: "complete",
},
]),
);
const aggregate = ir.promiseOperations.find(
({ method }) => method === "all",
);
expect(aggregate?.sourcePromiseIds).toHaveLength(2);
expect(aggregate?.returnSiteId).toBeTypeOf("string");
});
});
describe("JavaScript semantic analysis: calls 2", () => {
it("does not treat a shadowed Promise binding as the intrinsic", () => {
const ir = analyzeJavaScriptSemantics(`
function run(Promise) {
return Promise.resolve(1).then(work);
}
`);
expect(ir.promiseOperations).toEqual([
expect.objectContaining({
kind: "chain",
method: "then",
ownership: "returned",
sourcePromiseIds: [],
sourceResolution: "unresolved",
}),
]);
});
it("retains every promise operation found in the finite source", () => {
const ir = analyzeJavaScriptSemantics(
`
Promise.resolve(1);
Promise.resolve(2);
Promise.resolve(3);
`,
);
expect(ir.promiseOperations).toHaveLength(3);
expect(ir.coverage.status).toBe("complete");
});
it("fingerprints formatting and local-name changes identically", () => {
const left = analyzeJavaScriptSemantics(`
function calculate(value) {
const result = value + 1;
return result;
}
`);
const right = analyzeJavaScriptSemantics(
"function renamed(input){const output=input+1;return output}",
);
const changed = analyzeJavaScriptSemantics(
"function renamed(input){const output=input+2;return output}",
);
expect(left.functionFingerprints).toHaveLength(1);
expect(right.functionFingerprints).toHaveLength(1);
expect(left.functionFingerprints[0]?.components).toEqual(
right.functionFingerprints[0]?.components,
);
expect(
changed.functionFingerprints[0]?.components.literalSetSha256,
).not.toBe(left.functionFingerprints[0]?.components.literalSetSha256);
});
it("retains ambiguous local callees and explicit dynamic frontiers", () => {
const ir = analyzeJavaScriptSemantics(`
function left(value) { return value; }
function right(value) { return value; }
const selected = chooseLeft ? left : right;
selected(input);
receiver[key](input);
external(input);
`);
const selected = ir.callSites.find(
({ resolution }) => resolution === "ambiguous",
);
expect(selected?.calleeCallableIds).toEqual(
[
onlyCallable(ir, "left").callableId,
onlyCallable(ir, "right").callableId,
].sort(),
);
expect(
ir.argumentFlows.filter(
({ callSiteId }) => callSiteId === selected?.callSiteId,
),
).toHaveLength(2);
expect(ir.frontiers).toEqual(
expect.arrayContaining([
expect.objectContaining({
kind: "dynamic-call",
reason: expect.stringMatching(/ambiguous/iu),
}),
expect.objectContaining({
kind: "dynamic-property",
reason: expect.stringMatching(/computed member/iu),
}),
expect.objectContaining({
kind: "dynamic-call",
reason: "Unresolved call target external.",
}),
]),
);
});
});
describe("JavaScript semantic rest parameter flow", () => {
it.each([
{
parameters: "first, ...rest",
arguments: "1, 2, 3",
expected: [
[0, "first"],
[1, "rest"],
[2, "rest"],
],
},
{
parameters: "...rest",
arguments: "1, 2, 3",
expected: [
[0, "rest"],
[1, "rest"],
[2, "rest"],
],
},
{
parameters: "first, second",
arguments: "1, 2, 3",
expected: [
[0, "first"],
[1, "second"],
],
},
{
parameters: "first, ...rest",
arguments: "1, ...values, 3",
expected: [[0, "first"]],
},
])(
"links exact positions for ($parameters) called with ($arguments)",
({ parameters, arguments: arguments_, expected }) => {
const ir = analyzeJavaScriptSemantics(
`function collect(${parameters}) { return 1; } collect(${arguments_});`,
);
expect(
ir.argumentFlows.map(({ argumentIndex, parameterBindingId }) => [
argumentIndex,
semanticBinding(ir, parameterBindingId)?.name,
]),
).toEqual(expected);
},
);
});
@@ -0,0 +1,475 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import {
onlyCallable,
topLevelBinding,
} from "./javascriptSemanticAnalysis.fixture.js";
describe("JavaScript semantic analysis: dataflow 1", () => {
it("recovers static object reads, writes, spreads, and destructuring", () => {
const ir = analyzeJavaScriptSemantics(`
const source = { token: "TOKEN", count: 1 };
const { token } = source;
const copy = { ...source };
source.count = 2;
const read = source.token;
`);
expect(
ir.objectOperations.map(({ kind, propertyName, resolution }) => ({
kind,
propertyName,
resolution,
})),
).toEqual(
expect.arrayContaining([
{
kind: "destructure",
propertyName: "token",
resolution: "complete",
},
{ kind: "spread", propertyName: null, resolution: "complete" },
{ kind: "write", propertyName: "count", resolution: "complete" },
{ kind: "read", propertyName: "token", resolution: "complete" },
]),
);
});
it("does not invent property names for dynamic destructuring keys", () => {
const ir = analyzeJavaScriptSemantics(`
const source = { token: "TOKEN" };
const key = getKey();
const { [key]: dynamic } = source;
const { ["token"]: literal } = source;
const { token: renamed } = source;
const { token } = source;
const { [1]: numeric } = source;
`);
const destructures = ir.objectOperations.filter(
({ kind }) => kind === "destructure",
);
expect(destructures.map(({ propertyName }) => propertyName)).toEqual([
"token",
"token",
"token",
"1",
]);
expect(
destructures.every(({ resolution }) => resolution === "complete"),
).toBe(true);
expect(topLevelBinding(ir, "dynamic").value.status).toBe("unknown");
});
it("does not project positional argument flow after a spread", () => {
const ir = analyzeJavaScriptSemantics(`
function target(first, second, third) { return third; }
target(one, ...rest, three);
`);
expect(ir.argumentFlows.map(({ argumentIndex }) => argumentIndex)).toEqual([
0,
]);
});
it("retains all statically recovered call, flow, capture, and frontier facts", () => {
const ir = analyzeJavaScriptSemantics(
`
const captured = 1;
function target(value, other) { return value + other + captured; }
target(1, 2);
target(3, 4);
object[first];
object[second];
`,
);
expect(ir.callSites).toHaveLength(2);
expect(ir.callSites.map(({ arguments: args }) => args)).toEqual([
[
expect.objectContaining({ index: 0, spread: false }),
expect.objectContaining({ index: 1, spread: false }),
],
[
expect.objectContaining({ index: 0, spread: false }),
expect.objectContaining({ index: 1, spread: false }),
],
]);
expect(ir.argumentFlows).toHaveLength(4);
expect(ir.callReturnFlows).toHaveLength(2);
expect(ir.closureCaptures).toHaveLength(1);
expect(ir.frontiers).toHaveLength(2);
expect(ir.coverage.status).toBe("complete");
});
it("recovers only direct return sites with literal and unknown object fields", () => {
const ir = analyzeJavaScriptSemantics(`
export default function parseMarkdown(value) {
if (value.startsWith("# "))
return { type: "heading", depth: 1, text: value.slice(2) };
function nested() { return { type: "nested" }; }
const arrow = () => ({ type: "arrow" });
void nested; void arrow;
return { type: "paragraph", text: value.replaceAll("x", "y") };
}
`);
const parse = onlyCallable(ir, "parseMarkdown");
expect(parse.returnCoverage).toEqual({
status: "complete",
retainedCount: 2,
omittedCount: 0,
});
expect(parse.returnSites).toHaveLength(2);
expect(parse.returnSites[0]?.value).toMatchObject({
status: "object",
unknownProperties: false,
omittedProperties: 0,
properties: expect.arrayContaining([
{ name: "depth", value: { status: "literal", value: 1 } },
{ name: "type", value: { status: "literal", value: "heading" } },
{
name: "text",
value: {
status: "unknown",
reason: "Unsupported CallExpression value.",
},
},
]),
});
expect(onlyCallable(ir, "nested").returnSites).toHaveLength(1);
expect(onlyCallable(ir, "arrow").returnSites).toHaveLength(1);
expect(ir.moduleLinks).toContainEqual(
expect.objectContaining({
exportedName: "default",
callableId: parse.callableId,
}),
);
});
});
describe("JavaScript semantic analysis: read-modify-write", () => {
it.each(["+= 1", "++", "--", "||= 1", "&&= 1", "??= 1"])(
"retains the property read in a read-modify-write operation: %s",
(operator) => {
const ir = analyzeJavaScriptSemantics(`
const source = { count: 1 };
source.count ${operator};
`);
expect(ir.objectOperations.map(({ kind }) => kind)).toEqual([
"read",
"write",
]);
},
);
it("keeps plain member assignment write-only and member access read-only", () => {
const ir = analyzeJavaScriptSemantics(`
const source = { count: 1 };
source.count = 2;
const value = source.count;
`);
expect(ir.objectOperations.map(({ kind }) => kind)).toEqual([
"write",
"read",
]);
});
});
describe("JavaScript semantic analysis: dataflow 2", () => {
it("retains partial property coverage and empty returns", () => {
const partial = analyzeJavaScriptSemantics(`
const spread = () => ({ type: "spread", ...dynamic });
const computed = () => ({ type: "computed", [key]: 1 });
function noReturn() { throw new Error("stop"); }
function emptyReturn() { return; }
`);
expect(onlyCallable(partial, "spread").returnSites[0]?.value).toMatchObject(
{
status: "object",
unknownProperties: true,
omittedProperties: null,
},
);
expect(
onlyCallable(partial, "computed").returnSites[0]?.value,
).toMatchObject({
status: "object",
unknownProperties: true,
omittedProperties: 1,
});
expect(onlyCallable(partial, "noReturn").returnSites).toEqual([]);
expect(onlyCallable(partial, "emptyReturn").returnSites[0]?.value).toEqual({
status: "unknown",
reason: "Return has no value.",
});
});
it("fails closed on assignment ambiguity and alias cycles", () => {
const ambiguous = analyzeJavaScriptSemantics(`
let current = "first";
current = "second";
const left = right;
const right = left;
`);
expect(topLevelBinding(ambiguous, "current").value).toMatchObject({
status: "ambiguous",
});
expect(topLevelBinding(ambiguous, "left").value).toMatchObject({
status: "cycle",
});
expect(topLevelBinding(ambiguous, "right").provenance).toMatchObject({
status: "cycle",
});
});
it("does not invent exact module paths for dynamic property access", () => {
const ir = analyzeJavaScriptSemantics(`
const key = getKey();
const dynamicMember = require("electron")[key];
const { [key]: dynamicBinding } = require("electron");
`);
expect(topLevelBinding(ir, "dynamicMember").provenance).toMatchObject({
status: "unknown",
origins: [],
});
expect(topLevelBinding(ir, "dynamicBinding").provenance).toMatchObject({
status: "unknown",
origins: [],
});
expect(
ir.moduleLinks.filter(({ localName }) =>
["dynamicMember", "dynamicBinding"].includes(localName ?? ""),
),
).toEqual([]);
});
it("retains all scopes, bindings, and references without truncation", () => {
const ir = analyzeJavaScriptSemantics(
`
const retained = "yes";
const omitted = "no";
retained;
function nested(value) { return retained + value; }
`,
);
expect(ir.bindings.map(({ name }) => name)).toEqual(
expect.arrayContaining(["retained", "omitted", "value"]),
);
expect(ir.callables.map(({ name }) => name)).toContain("nested");
expect(ir.coverage.status).toBe("complete");
expect(ir.references.filter(({ name }) => name === "retained")).toEqual([
expect.objectContaining({
resolution: "resolved",
bindingId: topLevelBinding(ir, "retained").bindingId,
}),
expect.objectContaining({
resolution: "resolved",
bindingId: topLevelBinding(ir, "retained").bindingId,
}),
]);
});
});
describe("primitive addition values", () => {
it.each([
["true + 1", 2],
["null + 2", 2],
["false + true", 1],
['"x" + false', "xfalse"],
['null + "x"', "nullx"],
["3 + 4", 7],
])("recovers %s using primitive coercion", (expression, expected) => {
const ir = analyzeJavaScriptSemantics(`const answer = ${expression};`);
expect(topLevelBinding(ir, "answer").value).toEqual({
status: "literal",
value: expected,
});
});
});
describe("array positional value recovery", () => {
it("keeps holes at their actual destructuring indices", () => {
const ir = analyzeJavaScriptSemantics(`
const list = ["zero", , "two"];
const [first, second, third] = list;
`);
expect(topLevelBinding(ir, "first").value).toEqual({
status: "literal",
value: "zero",
});
expect(topLevelBinding(ir, "second").value.status).toBe("unknown");
expect(topLevelBinding(ir, "third").value).toEqual({
status: "literal",
value: "two",
});
});
it("projects canonical array indices without treating arbitrary strings as indices", () => {
const ir = analyzeJavaScriptSemantics(`
const list = ["zero", "one"];
const numeric = list[1];
const quoted = list["1"];
const leadingZero = list["01"];
const negative = list[-1];
`);
for (const name of ["numeric", "quoted"])
expect(topLevelBinding(ir, name).value).toEqual({
status: "literal",
value: "one",
});
for (const name of ["leadingZero", "negative"])
expect(topLevelBinding(ir, name).value.status).toBe("unknown");
});
it("does not shift trailing values across an unknown spread", () => {
const ir = analyzeJavaScriptSemantics(`
const values = ["first", ...unknownValues, "last"];
const [first, second] = values;
`);
expect(topLevelBinding(ir, "first").value).toEqual({
status: "literal",
value: "first",
});
expect(topLevelBinding(ir, "second").value.status).toBe("unknown");
});
});
describe("object value overwrite boundaries", () => {
it("uses the last named property and keeps later exact overwrites", () => {
const ir = analyzeJavaScriptSemantics(`
const duplicate = { key: "old", key: "new" };
const selected = duplicate.key;
const later = { key: "old", ...unknownObject, key: "final" };
const final = later.key;
`);
expect(topLevelBinding(ir, "selected").value).toEqual({
status: "literal",
value: "new",
});
expect(topLevelBinding(ir, "final").value).toEqual({
status: "literal",
value: "final",
});
});
it("does not retain an exact earlier value after an unknown overwrite", () => {
const ir = analyzeJavaScriptSemantics(`
const spread = { key: "old", ...unknownObject };
const dynamic = { key: "old", [unknownKey]: "new" };
const method = { key: "old", key() { return "new"; } };
const spreadValue = spread.key;
const dynamicValue = dynamic.key;
const methodValue = method.key;
`);
for (const name of ["spreadValue", "dynamicValue", "methodValue"])
expect(topLevelBinding(ir, name).value.status).toBe("unknown");
});
it("admits literal computed keys while excluding prototype setters", () => {
const ir = analyzeJavaScriptSemantics(`
const object = { ["key"]: "value", __proto__: { prototype: true } };
const selected = object.key;
const prototype = object.__proto__;
`);
expect(topLevelBinding(ir, "selected").value).toEqual({
status: "literal",
value: "value",
});
expect(topLevelBinding(ir, "prototype").value.status).toBe("unknown");
});
});
it("retains shorthand __proto__ as an own data property", () => {
const ir = analyzeJavaScriptSemantics(`
const __proto__ = "own";
const object = { __proto__ };
const selected = object.__proto__;
`);
expect(topLevelBinding(ir, "selected").value).toEqual({
status: "literal",
value: "own",
});
});
describe("nonfinite static values", () => {
it.each(['+"not-a-number"', '-"not-a-number"', "1e308 + 1e308", "1e309"])(
"keeps %s unknown instead of publishing a non-JSON number",
(expression) => {
const ir = analyzeJavaScriptSemantics(`const answer = ${expression};`);
expect(topLevelBinding(ir, "answer").value.status).toBe("unknown");
},
);
it("does not collapse an uncertain nonfinite branch to its finite alternative", () => {
const ir = analyzeJavaScriptSemantics(
'const answer = condition ? 1 : +"invalid";',
);
expect(topLevelBinding(ir, "answer").value.status).toBe("ambiguous");
});
});
describe("binding write invalidation", () => {
it.each([
"let value = 1; value++; const observed = value;",
"let value = 1; --value; const observed = value;",
'let value = "old"; [value] = ["new"]; const observed = value;',
'let value = "old"; ({key: value} = {key: "new"}); const observed = value;',
'let value = "old"; for (value of ["new"]) {} const observed = value;',
'let value = "old"; for (value in {new: true}) {} const observed = value;',
])("does not retain an exact initializer across %s", (source) => {
const ir = analyzeJavaScriptSemantics(source);
expect(topLevelBinding(ir, "observed").value.status).toBe("ambiguous");
expect(
topLevelBinding(ir, "value").definitions.some(
({ kind }) => kind === "assignment",
),
).toBe(true);
});
it("does not treat destructuring keys or member owners as assigned bindings", () => {
const ir = analyzeJavaScriptSemantics(`
const key = "stable";
const owner = "stable";
let target = "old";
({key: target} = {key: "new"});
({owner: object.slot} = {owner: "new"});
const preservedKey = key;
const preservedOwner = owner;
`);
for (const name of ["preservedKey", "preservedOwner"])
expect(topLevelBinding(ir, name).value).toEqual({
status: "literal",
value: "stable",
});
});
});
describe("JavaScript semantic analysis: unknown default inputs", () => {
it.each([
'function launch(mode = "safe") { return mode; }',
'function launch({ mode } = { mode: "safe" }) { return mode; }',
'function launch([mode] = ["safe"]) { return mode; }',
])("does not assume an optional argument is omitted: %s", (source) => {
const ir = analyzeJavaScriptSemantics(source);
expect(onlyCallable(ir, "launch").returnSites[0]?.value.status).toBe(
"unknown",
);
});
it("preserves known declaration inputs and unknown catch bindings", () => {
const ir = analyzeJavaScriptSemantics(`
const { mode: retained = "fallback" } = { mode: "actual" };
function caught() {
try { risky(); } catch ({ message = "fallback" }) { return message; }
}
`);
expect(topLevelBinding(ir, "retained").value).toMatchObject({
status: "literal",
value: "actual",
});
expect(onlyCallable(ir, "caught").returnSites[0]?.value.status).toBe(
"unknown",
);
});
});
@@ -0,0 +1,105 @@
import { expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
it.each([
"const routes = {'': 'HOME'}; const root = routes[''];",
"const routes = {['']: 'HOME'}; const root = routes[''];",
"const routes = {'': 'HOME'}; const {'': root} = routes;",
"const routes = {'': 'HOME'}; const {['']: root} = routes;",
"const routes = {home: 'HOME'}; const root = routes.home;",
])("preserves exact string keys in %s", (source) => {
const ir = analyzeJavaScriptSemantics(source);
expect(ir.bindings.find(({ name }) => name === "root")?.value).toEqual({
status: "literal",
value: "HOME",
});
expect(
ir.frontiers.filter(({ kind }) => kind === "dynamic-property"),
).toEqual([]);
});
it("keeps a computed identifier key unresolved", () => {
const ir = analyzeJavaScriptSemantics(
"const routes = {'': 'HOME'}; const root = routes[key];",
);
expect(ir.bindings.find(({ name }) => name === "root")?.value.status).toBe(
"unknown",
);
expect(ir.frontiers).toEqual(
expect.arrayContaining([
expect.objectContaining({ kind: "dynamic-property" }),
]),
);
});
it("retains exact empty method names and environment keys", () => {
const ir = analyzeJavaScriptSemantics(`
const target = { ['']() { return 42; } };
class Holder { ""() { return 2; } }
const empty = process.env[''];
const dynamic = process.env[key];
`);
expect(
ir.callables
.filter(({ kind }) => kind === "method")
.map(({ name }) => name),
).toEqual(["", ""]);
expect(
ir.configurationOperations.map(({ kind, key, resolution }) => ({
kind,
key,
resolution,
})),
).toEqual([
{ kind: "environment", key: "", resolution: "complete" },
{ kind: "environment", key: null, resolution: "partial" },
]);
});
it("retains exact empty require paths without dynamic-key links", () => {
const ir = analyzeJavaScriptSemantics(`
const { '': fromPattern } = require("./table.js");
const fromMember = require("./table.js")[''];
const { [key]: dynamicPattern } = require("./table.js");
const dynamicMember = require("./table.js")[key];
module.exports.root = require("./table.js")[''];
`);
expect(
ir.moduleLinks.map(({ kind, importedName, localName, exportedName }) => ({
kind,
importedName,
localName,
exportedName,
})),
).toEqual([
{
kind: "require",
importedName: "",
localName: "fromPattern",
exportedName: null,
},
{
kind: "require",
importedName: "",
localName: "fromMember",
exportedName: null,
},
{
kind: "commonjs-export",
importedName: "",
localName: null,
exportedName: "root",
},
]);
});
it("retains exact empty request field names without dynamic fields", () => {
const ir = analyzeJavaScriptSemantics(`
fetch("https://example.test", { '': value, [key]: 1, body: "x" });
`);
expect(
ir.requestOperations.flatMap(({ fields }) =>
fields.map(({ name }) => name),
),
).toEqual(["", "body"]);
});
@@ -0,0 +1,61 @@
import { expect } from "vitest";
import type {
JavaScriptSemanticBinding,
JavaScriptSemanticIr,
} from "./javascriptSemanticIr.js";
export const programScope = (ir: JavaScriptSemanticIr) => {
const scope = ir.scopes.find(({ kind }) => kind === "program");
if (scope === undefined) throw new Error("Missing program scope");
return scope;
};
export const bindingsNamed = (
ir: JavaScriptSemanticIr,
name: string,
): JavaScriptSemanticBinding[] =>
ir.bindings.filter(({ name: candidate }) => candidate === name);
export const onlyBinding = (
ir: JavaScriptSemanticIr,
name: string,
): JavaScriptSemanticBinding => {
const bindings = bindingsNamed(ir, name);
expect(bindings).toHaveLength(1);
const binding = bindings[0];
if (binding === undefined) throw new Error(`Missing binding ${name}`);
return binding;
};
export const onlyCallable = (ir: JavaScriptSemanticIr, name: string) => {
const callables = ir.callables.filter(
({ name: candidate }) => candidate === name,
);
if (callables.length !== 1 || callables[0] === undefined)
throw new Error(`Expected one callable named ${name}`);
return callables[0];
};
export const topLevelBinding = (
ir: JavaScriptSemanticIr,
name: string,
): JavaScriptSemanticBinding => {
const scopeId = programScope(ir).scopeId;
const binding = ir.bindings.find(
({ name: candidate, scopeId: candidateScope }) =>
candidate === name && candidateScope === scopeId,
);
if (binding === undefined)
throw new Error(`Missing top-level binding ${name}`);
return binding;
};
export const origin = (binding: JavaScriptSemanticBinding) => {
expect(binding.provenance.status).toBe("module");
expect(binding.provenance.origins).toHaveLength(1);
const value = binding.provenance.origins[0];
if (value === undefined)
throw new Error(`Missing origin for ${binding.name}`);
return value;
};
@@ -0,0 +1,54 @@
import { expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
it.each(["execute", "{execute}", "...execute", "execute = () => 'DEFAULT'"])(
"lets %s parameters shadow a named function expression",
(parameter) => {
const ir = analyzeJavaScriptSemantics(
`const task = function execute(${parameter}) { return execute(); };`,
);
const call = ir.callSites[0];
expect(call?.calleeCallableIds).toEqual([]);
expect(call?.resolution).toBe("unresolved");
const bindings = ir.bindings.filter(({ name }) => name === "execute");
expect(bindings).toHaveLength(2);
expect(bindings.map(({ kind }) => kind).sort()).toEqual([
"function",
"parameter",
]);
},
);
it.each(["var", "let", "const"])(
"lets body %s declarations shadow a named function expression",
(kind) => {
const ir = analyzeJavaScriptSemantics(`const task = function execute() {
${kind} execute = () => 'LOCAL';
return execute();
};`);
const local = ir.callables.find(
({ location }) => location.start.line === 2,
);
expect(ir.callSites[0]?.calleeCallableIds).toEqual([local?.callableId]);
expect(ir.callSites[0]?.resolution).toBe("exact");
},
);
it("preserves recursive function-name resolution without leaking the name", () => {
const ir = analyzeJavaScriptSemantics(`const task = function execute(depth) {
return depth === 0 ? 'DONE' : execute(depth - 1);
};
execute();`);
const own = ir.callables.find(({ name }) => name === "execute");
expect(ir.callSites[0]?.calleeCallableIds).toEqual([own?.callableId]);
expect(ir.callSites[1]?.calleeCallableIds).toEqual([]);
});
it("retains an unshadowed function name in parameter defaults", () => {
const ir = analyzeJavaScriptSemantics(
`const task = function execute(value = execute()) { return value; };`,
);
const own = ir.callables.find(({ name }) => name === "execute");
expect(ir.callSites[0]?.calleeCallableIds).toEqual([own?.callableId]);
});
@@ -0,0 +1,139 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import { onlyCallable } from "./javascriptSemanticAnalysis.fixture.js";
const resultValue = (body: string) =>
onlyCallable(
analyzeJavaScriptSemantics(`export function result() { ${body} }`),
"result",
).returnSites[0]?.value;
const mutations = [
'const shared = { mode: "initial" }; const options = { [key]: shared }; options.foo.mode = "updated"; return shared.mode;',
'const shared = { mode: "initial" }; const original = [shared]; const copy = [...original]; copy[0].mode = "updated"; return shared.mode;',
'const original = { nested: { mode: "initial" } }; const copy = { ...original }; copy.nested.mode = "updated"; return original.nested.mode;',
'const shared = { mode: "initial" }; const options = flag ? shared : { mode: "other" }; options.mode = "updated"; return shared.mode;',
'const child = { mode: "initial" }; const options = { layer: { child } }; options.layer.child.mode = "updated"; return child.mode;',
'const options = { mode: "initial" }; options.mode = "updated"; return options.mode;',
"const options = { count: 1 }; options.count += 1; return options.count;",
"const options = { count: 1 }; options.count++; return options.count;",
'const options = { mode: "initial" }; delete options.mode; return options.mode;',
'const options = ["initial"]; options[0] = "updated"; return options[0];',
'const options = { nested: { mode: "initial" } }; options.nested.mode = "updated"; return options.nested.mode;',
'const options = { mode: "initial" }; const alias = options; alias.mode = "updated"; return options.mode;',
'const options = { nested: { mode: "initial" } }; const { nested } = options; nested.mode = "updated"; return options.nested.mode;',
'const nested = { mode: "initial" }; const options = { nested }; options.nested.mode = "updated"; return nested.mode;',
'const options = { mode: "initial" }; [options.mode] = ["updated"]; return options.mode;',
'const options = { mode: "initial" }; for (options.mode of ["updated"]) {} return options.mode;',
'const options = { mode: "initial" }; const key = getKey(); options[key] = "updated"; return options.mode;',
];
describe("JavaScript semantic values after explicit property mutations", () => {
it.each(mutations)("keeps the mutated value unknown: %s", (body) => {
expect(resultValue(body)?.status).toBe("unknown");
});
it("keeps an unrelated shadowed object literal known", () => {
expect(
resultValue(`
const options = { mode: "initial" };
{ const options = { mode: "inner" }; options.mode = "updated"; }
return options.mode;
`),
).toEqual({ status: "literal", value: "initial" });
});
it("keeps scalar slots in a spread source known after a copy slot write", () => {
expect(
resultValue(`
const original = { mode: "initial" };
const copy = { ...original };
copy.mode = "updated";
return original.mode;
`),
).toEqual({ status: "literal", value: "initial" });
});
it("keeps conditional object branches unknown after a property write", () => {
expect(
resultValue(`
const options = flag ? { mode: "initial" } : { mode: "other" };
options.mode = "updated";
return options.mode;
`)?.status,
).toBe("unknown");
});
it("keeps a copied primitive initializer known", () => {
expect(
resultValue(`
const mode = "initial";
const options = { mode };
options.mode = "updated";
return mode;
`),
).toEqual({ status: "literal", value: "initial" });
});
it("retains ordinary immutable object and array projection", () => {
expect(
resultValue(
'const options = { mode: ["initial"] }; return options.mode[0];',
),
).toEqual({ status: "literal", value: "initial" });
});
});
const unchangedProperties = [
'const source = { token: "TOKEN", count: 1 }; source.count = 2; return source.token;',
'const source = { token: "TOKEN", count: 1 }; const alias = source; alias.count++; return source.token;',
'const source = { token: "TOKEN", count: 1 }; delete source.count; return source.token;',
'const source = { nested: { token: "TOKEN", count: 1 } }; source.nested.count = 2; return source.nested.token;',
'const source = { nested: { token: "TOKEN", count: 1 } }; const { nested } = source; nested.count = 2; return source.nested.token;',
'const child = { token: "TOKEN", count: 1 }; const source = { child }; source.child.count = 2; return child.token;',
'const source = ["TOKEN", 1]; source[1] = 2; return source[0];',
'const child = { token: "TOKEN", count: 1 }; const source = [child]; source[0].count = 2; return child.token;',
'const source = { token: "TOKEN" }; source.added = 2; return source.token;',
'const source = { token: "TOKEN", count: 1, other: 1 }; source.count = 2; source.other = 2; return source.token;',
'const left = { token: "TOKEN", count: 1 }; const right = { count: 1 }; const source = { left, right }; source.right.count = 2; return left.count + ":" + left.token;',
];
describe("JavaScript semantic values for properties unaffected by a mutation", () => {
it.each(unchangedProperties)("retains an unaffected property: %s", (body) => {
expect(resultValue(body)).toEqual({
status: "literal",
value: body.includes("left.count") ? "1:TOKEN" : "TOKEN",
});
});
it("keeps the changed slot unknown alongside an unchanged literal slot", () => {
expect(
resultValue(
'const source = { token: "TOKEN", count: 1 }; source.count = 2; return source.count;',
)?.status,
).toBe("unknown");
});
});
describe("property mutations through TypeScript satisfies aliases", () => {
it.each([
'const shared = { mode: "initial" }; const alias = shared satisfies { mode: string }; alias.mode = "updated"; return shared.mode;',
'const shared = { nested: { mode: "initial" } }; const alias = shared satisfies { nested: { mode: string } }; alias.nested.mode = "updated"; return shared.nested.mode;',
'const shared = { mode: "initial" }; const alias = (shared satisfies { mode: string }) as { mode: string }; delete alias.mode; return shared.mode;',
"const shared = [1]; const alias = shared satisfies number[]; alias[0]++; return shared[0];",
])("keeps the mutated value unknown: %s", (body) => {
expect(resultValue(body)?.status).toBe("unknown");
});
it("retains the untouched property through a satisfies alias", () => {
expect(
resultValue(`
const shared = { mode: "initial", token: "TOKEN" };
const alias = shared satisfies { mode: string; token: string };
alias.mode = "updated";
return shared.token;
`),
).toEqual({ status: "literal", value: "TOKEN" });
});
});
@@ -0,0 +1,172 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
describe("JavaScript semantic analysis: native bindings 1", () => {
it("recovers child-process argv, env, stdio, listeners, and signals", () => {
const ir = analyzeJavaScriptSemantics(`
import { spawn as launch } from "node:child_process";
function run() {
const child = launch(
"/bin/tool",
["--mode", "fast"],
{ env: { MODE: "test" }, stdio: ["ignore", "pipe", "pipe"] },
);
child.on("exit", onExit);
child.once("error", onError);
child.kill("SIGINT");
}
`);
expect(ir.childProcessSpawns).toEqual([
expect.objectContaining({
method: "spawn",
command: "/bin/tool",
argvCount: 2,
environmentSupplied: true,
stdioMode: "array",
resolution: "complete",
}),
]);
expect(
ir.childProcessInteractions.map(
({ kind, eventName, signalName, resolution }) => ({
kind,
eventName,
signalName,
resolution,
}),
),
).toEqual([
{
kind: "listener",
eventName: "exit",
signalName: null,
resolution: "complete",
},
{
kind: "listener",
eventName: "error",
signalName: null,
resolution: "complete",
},
{
kind: "signal",
eventName: null,
signalName: "SIGINT",
resolution: "complete",
},
]);
expect(ir.functionFingerprints[0]?.components.effects).toContain(
"child-process",
);
});
it("recovers configuration, requests, response consumers, and boundaries", () => {
const ir = analyzeJavaScriptSemantics(`
import { readFileSync } from "node:fs";
import * as http from "node:http";
async function run(schema) {
const endpoint = process.env.API_URL ?? "https://fallback.test";
const mode = process.argv[2];
const raw = readFileSync("./config.json", "utf8");
const parsed = JSON.parse(raw);
const port = Number(process.env.PORT);
const validated = schema.parse(parsed);
const response = await fetch(endpoint, {
method: "POST",
body: validated,
});
const body = await response.json();
http.request("https://audit.test", { body });
return { mode, port, body };
}
`);
expect(
ir.configurationOperations.map(({ kind, key }) => ({ kind, key })),
).toEqual(
expect.arrayContaining([
{ kind: "environment", key: "API_URL" },
{ kind: "default", key: "API_URL" },
{ kind: "argv", key: "2" },
{ kind: "file", key: "./config.json" },
{ kind: "environment", key: "PORT" },
]),
);
expect(
ir.requestOperations.map(({ kind, method, endpoint, resolution }) => ({
kind,
method,
endpoint,
resolution,
})),
).toEqual(
expect.arrayContaining([
{
kind: "request",
method: "fetch",
endpoint: null,
resolution: "partial",
},
{
kind: "response-consumer",
method: "json",
endpoint: null,
resolution: "complete",
},
{
kind: "request",
method: "request",
endpoint: "https://audit.test",
resolution: "complete",
},
]),
);
expect(
ir.boundaryOperations.map(({ kind, method, resolution }) => ({
kind,
method,
resolution,
})),
).toEqual(
expect.arrayContaining([
{ kind: "parse", method: "JSON.parse", resolution: "complete" },
{ kind: "coerce", method: "Number", resolution: "complete" },
{ kind: "parse", method: "parse", resolution: "partial" },
]),
);
expect(ir.functionFingerprints[0]?.components.effects).toContain("network");
});
});
describe("JavaScript semantic analysis: native bindings 2", () => {
it("recovers built-in resource acquisition and exact local release", () => {
const ir = analyzeJavaScriptSemantics(`
import { open } from "node:fs/promises";
import { connect as dial } from "node:net";
async function run(path) {
const file = await open(path);
const socket = dial({ port: 9000 });
await file.close();
socket.destroy();
}
`);
expect(
ir.resourceOperations.map(({ kind, method, resolution }) => ({
kind,
method,
resolution,
})),
).toEqual([
{ kind: "acquire", method: "open", resolution: "complete" },
{ kind: "acquire", method: "connect", resolution: "complete" },
{ kind: "release", method: "close", resolution: "complete" },
{ kind: "release", method: "destroy", resolution: "complete" },
]);
expect(ir.functionFingerprints[0]?.components.effects).toContain(
"resource",
);
});
});
@@ -0,0 +1,149 @@
import { expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
it.each([
{
source: "const value = (Promise.resolve(1) as Promise<number>);",
ownership: "assigned",
},
{
source: "const run = () => (Promise.resolve(1) as Promise<number>);",
ownership: "returned",
},
{
source: "const value = consume(Promise.resolve(1)).then(work);",
ownership: "unknown",
},
{
source: "const value = consume(Promise.resolve(1));",
ownership: "unknown",
},
{
source: "async function run() { await consume(Promise.resolve(1)); }",
ownership: "unknown",
},
{
source: "function run() { return consume(Promise.resolve(1)); }",
ownership: "unknown",
},
{ source: "const value = [Promise.resolve(1)];", ownership: "unknown" },
{
source: "const value = Promise.all([{promise: Promise.resolve(1)}]);",
ownership: "unknown",
},
{ source: "const value = Promise.resolve(1);", ownership: "assigned" },
{
source: "async function run() { await Promise.resolve(1); }",
ownership: "awaited",
},
{
source: "function run() { return Promise.resolve(1); }",
ownership: "returned",
},
{
source: "const value = Promise.resolve(1).then(work);",
ownership: "chained",
},
{
source: "const value = Promise.all([Promise.resolve(1)]);",
ownership: "aggregated",
},
{ source: "Promise.resolve(1);", ownership: "detached" },
])("retains direct Promise ownership in $source", ({ source, ownership }) => {
const ir = analyzeJavaScriptSemantics(source);
const promise = ir.promiseOperations.find(
({ method }) => method === "resolve",
);
expect(promise).toMatchObject({ ownership });
if (ownership === "unknown")
expect(promise).toMatchObject({ ownerBindingId: null, returnSiteId: null });
});
it.each([
["Promise.resolve(1)", "resolve"],
["((Promise.resolve(1)))", "resolve"],
["(Promise.resolve(1) as Promise<number>)", "resolve"],
["(Promise.resolve(1) satisfies Promise<number>)", "resolve"],
["Promise.resolve(1)!", "resolve"],
["((Promise.resolve(1) as Promise<number>)!)", "resolve"],
["(new Promise(resolve => resolve(1)) as Promise<number>)", "new"],
["(Promise.all([Promise.resolve(1)]) as Promise<number[]>)", "all"],
["(Promise.resolve(1).then(value => value) as Promise<number>)", "then"],
])("links the exact arrow return site for %s", (expression, method) => {
const ir = analyzeJavaScriptSemantics(`const run = () => ${expression};`);
const callable = ir.callables.find(({ name }) => name === "run");
expect(callable?.returnSites).toHaveLength(1);
const site = callable?.returnSites[0];
if (site === undefined) throw new Error("Expected the arrow return site");
const promise = ir.promiseOperations.find(
(operation) => operation.method === method,
);
expect(promise).toMatchObject({
ownership: "returned",
ownerCallableId: callable?.callableId,
returnSiteId: site.returnSiteId,
});
});
it.each([
"const outer = () => () => (Promise.resolve(1) as Promise<number>);",
"const outer = () => { const inner = () => Promise.resolve(1)!; return inner; };",
])("keeps a wrapped return owned by its nested arrow: %s", (source) => {
const ir = analyzeJavaScriptSemantics(source);
const promise = ir.promiseOperations.find(
({ method }) => method === "resolve",
);
const owner = ir.callables.find(
({ callableId }) => callableId === promise?.ownerCallableId,
);
const outer = ir.callables.find(({ name }) => name === "outer");
const site = owner?.returnSites[0];
if (site === undefined)
throw new Error("Expected the nested arrow return site");
expect(owner?.callableId).not.toBe(outer?.callableId);
expect(promise).toMatchObject({
ownership: "returned",
returnSiteId: site.returnSiteId,
});
expect(
outer?.returnSites.map(({ returnSiteId }) => returnSiteId),
).not.toContain(promise?.returnSiteId);
});
it.each([
["consume((Promise.resolve(1) as Promise<number>))", "unknown"],
["[(Promise.resolve(1) as Promise<number>)]", "unknown"],
["({ task: Promise.resolve(1)! })", "unknown"],
["(condition ? Promise.resolve(1)! : other)", "unknown"],
["((0, Promise.resolve(1)) as Promise<number>)", "unknown"],
["await (Promise.resolve(1) as Promise<number>)", "awaited"],
])("does not invent a return link through %s", (expression, ownership) => {
const ir = analyzeJavaScriptSemantics(
`const run = async () => ${expression};`,
);
expect(
ir.promiseOperations.find(({ method }) => method === "resolve"),
).toMatchObject({
ownership,
returnSiteId: null,
});
});
it("keeps an explicit return statement's full range and the producer's location", () => {
const source =
"const run = () => { return (Promise.resolve(1) as Promise<number>); };";
const ir = analyzeJavaScriptSemantics(source);
const site = ir.callables.find(({ name }) => name === "run")?.returnSites[0];
if (site === undefined) throw new Error("Expected a return statement");
const start = source.indexOf("Promise.resolve(1)");
expect(ir.promiseOperations[0]).toMatchObject({
ownership: "returned",
returnSiteId: site.returnSiteId,
location: {
start: { line: 1, column: start },
end: { line: 1, column: start + "Promise.resolve(1)".length },
},
});
expect(site.location.start.column).toBe(source.indexOf("return"));
});
@@ -0,0 +1,123 @@
import { fc, it } from "@fast-check/vitest";
import { describe, expect } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import type { JavaScriptSemanticValue } from "./javascriptSemanticIr.js";
import {
onlyCallable,
topLevelBinding,
} from "./javascriptSemanticAnalysis.fixture.js";
describe("JavaScript semantic analysis: rejection 1", () => {
it("retains complete finite facts and deeply nested static values", () => {
const names = Array.from(
{ length: 280 },
(_, index) => `key${String(index)}`,
);
const object = analyzeJavaScriptSemantics(
`const first = require("first"); const second = require("second"); first; second; const object = { ${names.map((name, index) => `${name}: ${String(index)}`).join(", ")} };`,
);
expect(object.moduleLinks).toHaveLength(2);
expect(object.references).toHaveLength(4);
expect(topLevelBinding(object, "object").value).toMatchObject({
status: "object",
unknownProperties: false,
properties: expect.arrayContaining([
expect.objectContaining({ name: "key279" }),
]),
});
const nesting = 40;
const nestedValue =
Array.from({ length: nesting }, () => "{ next: ").join("") +
'"value"' +
" }".repeat(nesting);
const deep = analyzeJavaScriptSemantics(`const nested = ${nestedValue};`);
let value: JavaScriptSemanticValue = topLevelBinding(deep, "nested").value;
for (let depth = 0; depth < nesting; depth += 1) {
expect(value.status).toBe("object");
if (value.status !== "object")
throw new TypeError("Expected a recovered nested object");
const next = value.properties.find(({ name }) => name === "next");
if (next === undefined) throw new TypeError("Missing nested property");
value = next.value;
}
expect(value).toEqual({ status: "literal", value: "value" });
});
it("is deterministic and returns failed coverage for an unparseable source", () => {
const source = 'const { value: renamed } = require("fixture");';
expect(analyzeJavaScriptSemantics(source)).toEqual(
analyzeJavaScriptSemantics(source),
);
expect(analyzeJavaScriptSemantics("function {")).toMatchObject({
scopes: [],
bindings: [],
callables: [],
references: [],
coverage: { status: "failed", omittedCount: null },
});
});
it("does not mark parser-recovered duplicate bindings complete", () => {
const ir = analyzeJavaScriptSemantics(
"const duplicate = 'first'; const duplicate = 'second';",
);
expect(ir.coverage).toMatchObject({
status: "partial",
omittedCount: 0,
});
expect(topLevelBinding(ir, "duplicate").value).toMatchObject({
status: "ambiguous",
});
expect(ir.limitations.join(" ")).toMatch(/parser recovered/iu);
});
it("keeps parser-recovered return shapes partial", () => {
const ir = analyzeJavaScriptSemantics(
`
export default function recovered(value) {
const duplicate = 1;
const duplicate = 2;
return { type: "item", text: render(value) };
}
`,
);
const recovered = onlyCallable(ir, "recovered");
expect(ir.coverage.status).toBe("partial");
expect(recovered.returnCoverage).toMatchObject({
status: "partial",
retainedCount: 1,
omittedCount: 0,
});
expect(recovered.returnSites[0]?.value).toMatchObject({
status: "object",
properties: expect.arrayContaining([
{ name: "type", value: { status: "literal", value: "item" } },
expect.objectContaining({
name: "text",
value: expect.objectContaining({ status: "unknown" }),
}),
]),
});
});
it.prop([fc.string({ maxLength: 512 })])(
"fails closed for arbitrary source text",
(source) => {
const ir = analyzeJavaScriptSemantics(source);
expect(ir.schema).toBe("JavaScriptSemanticIR");
expect(["complete", "partial", "truncated", "failed"]).toContain(
ir.coverage.status,
);
if (ir.coverage.status === "failed") {
expect(ir.scopes).toEqual([]);
expect(ir.bindings).toEqual([]);
expect(ir.callables).toEqual([]);
}
},
);
});
@@ -0,0 +1,132 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
describe("JavaScript semantic analysis: runtime boundaries 1", () => {
it("recovers EventEmitter candidates and imported timer handle cancellation", () => {
const ir = analyzeJavaScriptSemantics(`
import {
setTimeout as later,
clearTimeout as cancel,
} from "node:timers";
function run(bus, dynamicName) {
const handle = later(work, 25);
bus.on("ready", handler);
bus.once(dynamicName, handler);
bus.emit("ready");
bus.off("ready", handler);
cancel(handle);
}
`);
expect(
ir.eventOperations.map(({ kind, method, eventName, resolution }) => ({
kind,
method,
eventName,
resolution,
})),
).toEqual([
{
kind: "register",
method: "on",
eventName: "ready",
resolution: "complete",
},
{
kind: "register",
method: "once",
eventName: null,
resolution: "unresolved",
},
{
kind: "dispatch",
method: "emit",
eventName: "ready",
resolution: "complete",
},
{
kind: "remove",
method: "off",
eventName: "ready",
resolution: "complete",
},
]);
expect(ir.timerOperations).toEqual([
expect.objectContaining({
kind: "schedule",
method: "setTimeout",
delayMilliseconds: 25,
resolution: "complete",
}),
expect.objectContaining({
kind: "cancel",
method: "clearTimeout",
delayMilliseconds: null,
resolution: "complete",
linkedTimerId: ir.timerOperations[0]?.timerId,
}),
]);
expect(ir.functionFingerprints[0]?.components.effects).toEqual([
"event",
"timer",
]);
});
it("does not treat shadowed timer globals as Node timers", () => {
const ir = analyzeJavaScriptSemantics(`
function run(setTimeout, clearTimeout) {
const handle = setTimeout(work, 1);
clearTimeout(handle);
}
`);
expect(ir.timerOperations).toEqual([]);
});
it("does not invent request fields or option keys from dynamic properties", () => {
const ir = analyzeJavaScriptSemantics(`
const key = resolveKey();
fetch("https://example.test", { [key]: 1, body: "x" });
spawn("/bin/tool", { [key]: vars });
`);
expect(
ir.requestOperations.flatMap(({ fields }) =>
fields.map(({ name }) => name),
),
).toEqual(["body"]);
expect(
ir.childProcessSpawns.some(
({ environmentSupplied }) => environmentSupplied,
),
).toBe(false);
});
it("retains every added semantic effect family", () => {
const ir = analyzeJavaScriptSemantics(
`
import { spawn } from "node:child_process";
import { open } from "node:fs/promises";
Promise.resolve(1);
bus.on("ready", handler);
setTimeout(work, 1);
spawn("/bin/tool");
const endpoint = process.env.API_URL;
fetch("https://example.test");
JSON.parse(raw);
open(path);
`,
);
expect(ir.coverage.status).toBe("complete");
expect(ir.promiseOperations).toHaveLength(1);
expect(ir.eventOperations).toHaveLength(1);
expect(ir.timerOperations).toHaveLength(1);
expect(ir.childProcessSpawns).toHaveLength(1);
expect(ir.configurationOperations).toHaveLength(1);
expect(ir.requestOperations).toHaveLength(1);
expect(ir.boundaryOperations).toHaveLength(1);
expect(ir.resourceOperations).toHaveLength(1);
expect(ir.objectOperations.length).toBeGreaterThan(0);
});
});
@@ -0,0 +1,468 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import {
semanticBinding,
semanticReferenceAt,
} from "./javascriptSemanticIr.js";
import {
programScope,
bindingsNamed,
onlyBinding,
topLevelBinding,
origin,
} from "./javascriptSemanticAnalysis.fixture.js";
describe("JavaScript semantic analysis: structure 1", () => {
it("resolves imports, require destructuring, aliases, assignments, and shadowing", () => {
const ir = analyzeJavaScriptSemantics(`
import { ipcRenderer as ir } from "electron";
const { ipcMain: bus } = require("electron");
const forwarded = bus;
let assigned;
assigned = ir;
ir.invoke("outside");
bus.handle("main", handler);
function local(ipcRenderer) {
const bus = require("./local-bus.js");
ipcRenderer.send("shadowed");
return bus;
}
`);
expect(ir.coverage).toEqual({
status: "complete",
omittedCount: 0,
});
expect(origin(topLevelBinding(ir, "ir"))).toEqual({
specifier: "electron",
importedPath: ["ipcRenderer"],
});
expect(origin(topLevelBinding(ir, "bus"))).toEqual({
specifier: "electron",
importedPath: ["ipcMain"],
});
expect(origin(topLevelBinding(ir, "forwarded"))).toEqual({
specifier: "electron",
importedPath: ["ipcMain"],
});
expect(origin(topLevelBinding(ir, "assigned"))).toEqual({
specifier: "electron",
importedPath: ["ipcRenderer"],
});
expect(ir.moduleLinks).toEqual(
expect.arrayContaining([
expect.objectContaining({
kind: "require",
specifier: "electron",
importedName: "ipcMain",
localName: "bus",
}),
]),
);
const innerBus = bindingsNamed(ir, "bus").find(
({ scopeId }) => scopeId !== programScope(ir).scopeId,
);
expect(innerBus).toBeDefined();
if (innerBus === undefined) return;
expect(origin(innerBus)).toEqual({
specifier: "./local-bus.js",
importedPath: [],
});
const shadow = onlyBinding(ir, "ipcRenderer");
expect(shadow.provenance).toEqual({
status: "local",
origins: [],
reason: null,
});
const shadowReference = ir.references.find(
({ name, bindingId, role }) =>
name === "ipcRenderer" &&
bindingId === shadow.bindingId &&
role === "read",
);
expect(shadowReference?.resolution).toBe("resolved");
expect(shadowReference?.bindingId).not.toBe(
topLevelBinding(ir, "ir").bindingId,
);
if (shadowReference === undefined || shadowReference.bindingId === null)
throw new Error("Missing shadow reference");
expect(semanticBinding(ir, shadowReference.bindingId)).toEqual(shadow);
expect(
semanticReferenceAt(
ir,
shadowReference.location.start.line,
shadowReference.location.start.column,
),
).toEqual(shadowReference);
});
it.each([
`function run(require) { const bus = require("electron").ipcMain; return bus; }`,
`function run() { const { ipcMain: bus } = require("electron"); function require() {} return bus; }`,
`{ const bus = require("electron").ipcMain; const require = localLoader; }`,
`import require from "./loader.js"; const bus = require("electron").ipcMain;`,
])(
"does not assign CommonJS origins to lexically shadowed require",
(source) => {
const ir = analyzeJavaScriptSemantics(source);
const bus = onlyBinding(ir, "bus");
expect(bus.provenance.origins).toEqual([]);
expect(ir.moduleLinks.filter(({ kind }) => kind === "require")).toEqual(
[],
);
},
);
it("preserves unshadowed require origins through aliases and assignments", () => {
const ir = analyzeJavaScriptSemantics(`
const { ipcMain: bus } = require("electron");
const forwarded = bus;
let assigned;
assigned = require("electron").ipcMain;
{ const require = localLoader; require("./local.js"); }
`);
for (const name of ["bus", "forwarded", "assigned"])
expect(origin(topLevelBinding(ir, name))).toEqual({
specifier: "electron",
importedPath: ["ipcMain"],
});
expect(
ir.moduleLinks.filter(({ kind }) => kind === "require"),
).toHaveLength(1);
});
it("propagates literal, template, object, conditional, and destructured values", () => {
const ir = analyzeJavaScriptSemantics(`
const prefix = "rea";
const suffix = "open";
const channel = \`${"${prefix}"}:${"${suffix}"}\`;
const options = {
channel,
mode: enabled ? "read" : "write",
};
const selected = options.channel;
const { mode } = options;
const [first] = ["zero", "one"];
`);
expect(topLevelBinding(ir, "channel").value).toEqual({
status: "literal",
value: "rea:open",
});
expect(topLevelBinding(ir, "selected").value).toEqual({
status: "literal",
value: "rea:open",
});
expect(topLevelBinding(ir, "mode").value).toEqual({
status: "union",
values: ["read", "write"],
});
expect(topLevelBinding(ir, "first").value).toEqual({
status: "literal",
value: "zero",
});
});
});
describe("JavaScript semantic analysis: loop lexical names", () => {
it.each([
`for (let value = "inside"; ready; step()) { consume(value); }`,
`for (const value of entries) { consume(value); }`,
`for (const value in entries) { consume(value); }`,
])("does not leak lexical loop bindings into the enclosing scope", (loop) => {
const ir = analyzeJavaScriptSemantics(`
const value = "outside";
${loop}
consume(value);
`);
expect(topLevelBinding(ir, "value").value).toEqual({
status: "literal",
value: "outside",
});
expect(bindingsNamed(ir, "value")).toHaveLength(2);
const reads = ir.references.filter(
({ name, role }) => name === "value" && role === "read",
);
expect(reads).toHaveLength(2);
expect(reads[0]?.bindingId).not.toBe(reads[1]?.bindingId);
expect(reads[1]?.bindingId).toBe(topLevelBinding(ir, "value").bindingId);
});
it("resolves closures inside a loop against the loop binding", () => {
const ir = analyzeJavaScriptSemantics(`
const value = "outside";
for (const value of entries) { callbacks.push(() => value); }
consume(value);
`);
const reads = ir.references.filter(
({ name, role }) => name === "value" && role === "read",
);
expect(reads).toHaveLength(2);
expect(reads[0]?.bindingId).not.toBe(
topLevelBinding(ir, "value").bindingId,
);
expect(reads[1]?.bindingId).toBe(topLevelBinding(ir, "value").bindingId);
expect(ir.closureCaptures).toContainEqual(
expect.objectContaining({
bindingId: reads[0]?.bindingId,
}),
);
});
it("keeps var loop declarations in the enclosing function", () => {
const ir = analyzeJavaScriptSemantics(`
function run() { for (var value of entries) { consume(value); } return value; }
`);
const binding = onlyBinding(ir, "value");
const callable = ir.callables.find(({ name }) => name === "run");
expect(binding.scopeId).toBe(callable?.bodyScopeId);
expect(
ir.references
.filter(({ name, role }) => name === "value" && role === "read")
.every(({ bindingId }) => bindingId === binding.bindingId),
).toBe(true);
});
});
describe("JavaScript semantic analysis: class expression lexical names", () => {
it("resolves named class expressions inside the class without changing the outer binding", () => {
const ir = analyzeJavaScriptSemantics(`
const Service = "outside";
const Wrapper = class Service {
create() { return new Service(); }
};
consume(Service);
`);
expect(bindingsNamed(ir, "Service")).toHaveLength(2);
expect(topLevelBinding(ir, "Service").value).toEqual({
status: "literal",
value: "outside",
});
const references = ir.references.filter(
({ name, role }) => name === "Service" && role === "read",
);
expect(references).toHaveLength(2);
expect(references[0]?.bindingId).not.toBe(references[1]?.bindingId);
expect(references[0]?.resolution).toBe("resolved");
const classScope = ir.scopes.find(({ kind }) => kind === "class");
expect(
bindingsNamed(ir, "Service").some(
({ scopeId }) => scopeId === classScope?.scopeId,
),
).toBe(true);
});
it("does not expose a named class expression outside its class", () => {
const ir = analyzeJavaScriptSemantics(`
const Wrapper = class Internal { create() { return new Internal(); } };
consume(Internal);
`);
const references = ir.references.filter(
({ name, role }) => name === "Internal" && role === "read",
);
expect(references.map(({ resolution }) => resolution)).toEqual([
"resolved",
"unbound",
]);
expect(topLevelBinding(ir, "Wrapper").provenance.status).toBe("local");
});
});
describe("JavaScript semantic analysis: structure 2", () => {
it("retains ESM, re-export, require, and CommonJS export relationships", () => {
const ir = analyzeJavaScriptSemantics(`
export { ipcRenderer as bridge } from "electron";
export * from "./wrapper.js";
export const localValue = 1;
const addon = require("./native.node");
module.exports.addon = addon;
export default function namedDefault() {}
`);
expect(ir.moduleLinks).toEqual(
expect.arrayContaining([
expect.objectContaining({
kind: "re-export",
specifier: "electron",
importedName: "ipcRenderer",
exportedName: "bridge",
}),
expect.objectContaining({
kind: "re-export",
specifier: "./wrapper.js",
importedName: "*",
exportedName: "*",
}),
expect.objectContaining({
kind: "export",
localName: "localValue",
exportedName: "localValue",
}),
expect.objectContaining({
kind: "require",
specifier: "./native.node",
localName: "addon",
}),
expect.objectContaining({
kind: "commonjs-export",
localName: "addon",
exportedName: "addon",
}),
expect.objectContaining({
kind: "export",
localName: "namedDefault",
exportedName: "default",
}),
]),
);
});
it("does not invent export or method names from dynamic keys", () => {
const ir = analyzeJavaScriptSemantics(`
const key = resolveKey();
exports[key] = addon;
module.exports[key] = addon;
const target = { [key]() { return 1; } };
class Holder { [key]() { return 2; } }
`);
// The assignment is real, but its name is not knowable, so the only
// honest exported_name is the wildcard.
expect(
ir.moduleLinks
.filter(({ kind }) => kind === "commonjs-export")
.map(({ exportedName }) => exportedName),
).toEqual(["*", "*"]);
const names = ir.callables.map(({ name }) => name);
expect(names).not.toContain("key");
expect(names.filter((name) => name?.startsWith("[computed@")).length).toBe(
2,
);
});
it("classifies destructuring and loop targets as writes, not reads", () => {
const ir = analyzeJavaScriptSemantics(`
let a, b, c;
({ a } = source);
[b] = list;
({ nested: { c } } = source);
for (a of list) {}
let d;
try { risky(); } catch ({ message }) { report(message); }
`);
const roles = (name: string): string[] =>
ir.references
.filter((reference) => reference.name === name)
.map(({ role }) => role);
expect(roles("a")).toEqual(["write", "write"]);
expect(roles("b")).toEqual(["write"]);
expect(roles("c")).toEqual(["write"]);
// A catch binding is a declaration, so its only later use is a read.
expect(roles("message")).toEqual(["read"]);
});
it("retains the read a compound assignment or update performs", () => {
const ir = analyzeJavaScriptSemantics(`
let total = 0;
total += 1;
total++;
total = 2;
const observed = total;
`);
const roles = ir.references
.filter(({ name }) => name === "total")
.map(({ role }) => role);
expect(roles).toEqual([
"read",
"write", // total += 1
"read",
"write", // total++
"write", // total = 2
"read", // const observed = total
]);
});
});
describe("JavaScript semantic analysis: dynamic and case scopes", () => {
it("marks with and eval as unresolved dynamic scope instead of staying silent", () => {
const ir = analyzeJavaScriptSemantics(`
function load(source) {
with (host) { consume(target); }
eval("var injected = 1;");
}
`);
const reasons = ir.frontiers
.filter(({ kind }) => kind === "dynamic-scope")
.map(({ reason }) => reason);
expect(reasons).toHaveLength(2);
expect(reasons.join("\n")).toContain("`with`");
expect(reasons.join("\n")).toContain("`eval`");
});
it("does not assign CommonJS exports to lexically shadowed module or exports", () => {
const ir = analyzeJavaScriptSemantics(`
function shadowed(module, exports) {
module.exports.value = 1;
exports.other = 2;
exports[key] = 3;
module.exports[key] = 4;
unrelated[key] = 5;
}
`);
expect(
ir.moduleLinks.filter(({ kind }) => kind === "commonjs-export"),
).toEqual([]);
});
it("shares one lexical scope across switch cases and isolates static blocks", () => {
const switchIr = analyzeJavaScriptSemantics(`
const kind = select();
switch (kind) {
case "a": let shared = 1; break;
case "b": shared = 2; break;
}
`);
// One declaration, one binding — and it belongs to a scope of its own, so
// it cannot leak past the switch statement.
const shared = switchIr.bindings.filter(({ name }) => name === "shared");
expect(shared).toHaveLength(1);
expect(shared[0]?.scopeId).not.toBe(
topLevelBinding(switchIr, "kind").scopeId,
);
const classIr = analyzeJavaScriptSemantics(`
class Holder {
static { let isolated = 1; }
static { let isolated = 2; }
}
`);
expect(
classIr.bindings.filter(({ name }) => name === "isolated"),
).toHaveLength(2);
});
it("keeps function, class, and method identities separate from bindings", () => {
const ir = analyzeJavaScriptSemantics(`
class Service {
run() {}
get value() { return 1; }
#privateMethod() {}
}
const arrow = () => 1;
const object = { method() {} };
`);
expect(ir.callables).toEqual(
expect.arrayContaining([
expect.objectContaining({ kind: "class", name: "Service" }),
expect.objectContaining({ kind: "method", name: "run" }),
expect.objectContaining({ kind: "method", name: "value" }),
expect.objectContaining({ kind: "method", name: "#privateMethod" }),
expect.objectContaining({ kind: "function", name: "arrow" }),
expect.objectContaining({ kind: "method", name: "method" }),
]),
);
expect(bindingsNamed(ir, "run")).toEqual([]);
expect(bindingsNamed(ir, "method")).toEqual([]);
});
});
@@ -0,0 +1,563 @@
import * as t from "@babel/types";
import {
failedJavaScriptSemanticIr,
type JavaScriptModuleOrigin,
type JavaScriptSemanticDefinition,
type JavaScriptSemanticIr,
} from "./javascriptSemanticIr.js";
import {
collectSemanticModuleLink,
collectSemanticCallable,
collectSemanticReferences,
immutableSemanticBindings,
immutableSemanticScopes,
semanticStaticPropertyKey,
} from "./javascriptSemanticProjection.js";
import type {
JavaScriptSemanticAnalysisState,
JavaScriptSemanticBindingState,
JavaScriptSemanticScopeState,
} from "./javascriptSemanticState.js";
import {
currentSemanticScope,
resolveSemanticBindingFromScope,
semanticScopeId,
semanticVariableScope,
} from "./javascriptSemanticState.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { collectSemanticMemberMutations } from "./javascriptSemanticMemberMutations.js";
import {
collectSemanticReturns,
resolveSemanticModuleCallables,
} from "./javascriptSemanticReturns.js";
import { collectJavaScriptDerivedSemantics } from "./javascriptSemanticDerivedAnalysis.js";
import { propertyName, range } from "./javascriptStaticAnalysisHelpers.js";
import { semanticCoverage } from "./javascriptSemanticCoverage.js";
import {
parseJavaScriptSource,
type ParsedJavaScriptSource,
} from "./javascriptSourceParser.js";
interface BindPatternInput {
readonly pattern: t.Node;
readonly initializer: t.Node | null;
readonly scope: JavaScriptSemanticScopeState;
readonly state: JavaScriptSemanticAnalysisState;
readonly mutable: boolean;
readonly kind?: JavaScriptSemanticDefinition["kind"];
readonly projection?: readonly (string | number | null)[];
}
interface AddBindingInput {
readonly state: JavaScriptSemanticAnalysisState;
readonly scope: JavaScriptSemanticScopeState;
readonly name: string;
readonly kind: JavaScriptSemanticDefinition["kind"];
readonly mutable: boolean;
readonly definitionNode: t.Node;
readonly initializer: t.Node | null;
readonly directOrigin?: JavaScriptModuleOrigin;
readonly projection?: readonly (string | number | null)[];
}
/** Recover lexical bindings, aliases, constants, and module links. */
export const analyzeJavaScriptSemantics = (
source: string,
): JavaScriptSemanticIr => {
const file = parseJavaScriptSource(source);
return file === null
? failedJavaScriptSemanticIr()
: analyzeParsedJavaScriptSemantics(file);
};
/** Recover semantics from an already parsed JavaScript artifact. */
export const analyzeParsedJavaScriptSemantics = (
file: ParsedJavaScriptSource,
): JavaScriptSemanticIr => {
const state = createState(file.program);
collectDefinitions(file.program, state);
collectSemanticMemberMutations(file.program, state);
traverseJavaScriptAst(file.program, {
enter: (node) => collectSemanticModuleLink(node, state),
});
const references = collectSemanticReferences(file.program, state);
const parserPartial = file.errors.length > 0;
const bindings = immutableSemanticBindings(state);
const callables = collectSemanticReturns(file.program, state, parserPartial);
const moduleLinks = resolveSemanticModuleCallables(state, callables);
const derived = collectJavaScriptDerivedSemantics(
file.program,
state,
callables,
parserPartial,
);
return {
schema: "JavaScriptSemanticIR",
scopes: immutableSemanticScopes(state),
bindings,
callables,
references,
moduleLinks,
...derived,
coverage: semanticCoverage(parserPartial),
limitations: [
...(parserPartial
? [
"The parser recovered from syntax errors; affected bindings are partial.",
]
: []),
"Values and aliases were recovered from inert syntax only; no JavaScript was executed.",
"Return sites include only direct callable returns; nested callable returns remain separate.",
"Local call, argument, return, and closure relations are static candidates and do not prove runtime invocation.",
"Promise ownership covers explicit unshadowed Promise construction, static factories, aggregation, chaining, and await syntax only.",
"Cross-function mutation and dynamic property resolution remain unknown.",
],
};
};
const createState = (program: t.Program): JavaScriptSemanticAnalysisState => {
const root: JavaScriptSemanticScopeState = {
scopeId: semanticScopeId("program", program),
parentScopeId: null,
kind: "program",
location: range(program),
bindingsComplete: true,
bindings: new Map(),
};
return {
scopes: [root],
scopesById: new Map([[root.scopeId, root]]),
scopeByNode: new WeakMap([[program, root]]),
bindingsById: new Map(),
callables: [],
callableNodesById: new Map(),
moduleLinks: [],
};
};
const collectDefinitions = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
): void => {
const stack: JavaScriptSemanticScopeState[] = [
currentSemanticScope(state.scopes),
];
const openedScopes = new WeakMap<t.Node, number>();
traverseJavaScriptAst(program, {
enter: (node, parent) => {
let parentScope = currentSemanticScope(stack);
if (
parent !== null &&
t.isWithStatement(parent) &&
parent.body === node
) {
const dynamicScope: JavaScriptSemanticScopeState = {
scopeId: `${semanticScopeId("block", parent)}:with`,
parentScopeId: parentScope.scopeId,
kind: "block",
location: range(parent),
bindingsComplete: false,
bindings: new Map(),
};
state.scopes.push(dynamicScope);
state.scopesById.set(dynamicScope.scopeId, dynamicScope);
stack.push(dynamicScope);
openedScopes.set(node, 1);
parentScope = dynamicScope;
}
bindOuterDeclaration(node, parentScope, state);
const nested = nestedScope(node, parent, parentScope, state);
if (nested !== undefined) {
stack.push(nested);
openedScopes.set(node, (openedScopes.get(node) ?? 0) + 1);
}
const scope = currentSemanticScope(stack);
state.scopeByNode.set(node, scope);
collectSemanticCallable({
node,
parent,
containerScope: parentScope,
bodyScope: nested,
state,
});
bindInnerDeclaration(node, parent, scope, state);
},
exit: (node) => {
for (let count = openedScopes.get(node) ?? 0; count > 0; count--)
stack.pop();
},
});
};
const bindOuterDeclaration = (
node: t.Node,
scope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): void => {
if (t.isFunctionDeclaration(node) && t.isIdentifier(node.id))
addBinding({
state,
scope,
name: node.id.name,
kind: "function",
mutable: false,
definitionNode: node.id,
initializer: node,
});
else if (t.isClassDeclaration(node) && t.isIdentifier(node.id))
addBinding({
state,
scope,
name: node.id.name,
kind: "class",
mutable: false,
definitionNode: node.id,
initializer: node,
});
};
const bindInnerDeclaration = (
node: t.Node,
parent: t.Node | null,
scope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): void => {
if (t.isImportDeclaration(node)) bindImports(node, scope, state);
else if (t.isVariableDeclarator(node))
bindPattern({
pattern: node.id,
initializer: node.init ?? null,
scope: semanticVariableScope(scope, parent, state),
state,
mutable:
parent !== null && t.isVariableDeclaration(parent)
? parent.kind !== "const"
: true,
});
else if (t.isClassExpression(node) && t.isIdentifier(node.id))
addBinding({
state,
scope,
name: node.id.name,
kind: "class",
mutable: false,
definitionNode: node.id,
initializer: node,
});
else if (t.isFunction(node)) bindFunctionLocals(node, scope, state);
else if (t.isCatchClause(node) && node.param != null)
bindPattern({
pattern: node.param,
initializer: null,
scope,
state,
mutable: true,
kind: "catch",
});
else if (t.isAssignmentExpression(node)) {
if (t.isIdentifier(node.left))
addAssignment(node.left, node.right, scope, state);
else
for (const identifier of assignedPatternIdentifiers(node.left))
addAssignment(identifier, node, scope, state);
} else if (t.isUpdateExpression(node) && t.isIdentifier(node.argument))
addAssignment(node.argument, node, scope, state);
else if (t.isForOfStatement(node) || t.isForInStatement(node))
for (const identifier of assignedPatternIdentifiers(node.left))
addAssignment(identifier, node, scope, state);
};
const assignedPatternIdentifiers = (
pattern: t.Node,
): readonly t.Identifier[] => {
const identifiers: t.Identifier[] = [];
const pending = [pattern];
while (pending.length > 0) {
const node = pending.pop();
if (node === undefined) continue;
if (t.isIdentifier(node)) identifiers.push(node);
else if (t.isRestElement(node)) pending.push(node.argument);
else if (t.isAssignmentPattern(node)) pending.push(node.left);
else if (t.isArrayPattern(node)) {
for (const element of node.elements)
if (element !== null) pending.push(element);
} else if (t.isObjectPattern(node)) {
for (const property of node.properties)
pending.push(
t.isRestElement(property) ? property.argument : property.value,
);
}
}
return identifiers;
};
const nestedScope = (
node: t.Node,
parent: t.Node | null,
parentScope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticScopeState | undefined => {
const switchOwner =
t.isSwitchCase(node) && parent !== null && t.isSwitchStatement(parent)
? parent
: undefined;
if (switchOwner !== undefined) {
const existing = state.scopesById.get(
semanticScopeId("block", switchOwner),
);
if (existing !== undefined) return existing;
}
const kind = scopeKind(node, parent);
if (kind === undefined) return undefined;
const scope: JavaScriptSemanticScopeState = {
scopeId: semanticScopeId(kind, switchOwner ?? node),
parentScopeId:
functionNameScope(node, parentScope, state)?.scopeId ??
parentScope.scopeId,
kind,
location: range(switchOwner ?? node),
bindingsComplete: true,
bindings: new Map(),
};
state.scopes.push(scope);
state.scopesById.set(scope.scopeId, scope);
return scope;
};
const functionNameScope = (
node: t.Node,
parentScope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticScopeState | undefined => {
if (!t.isFunctionExpression(node) || !t.isIdentifier(node.id))
return undefined;
// A named expression has a private name environment outside its parameters
// and body. Parameters and local declarations may shadow that name.
const scope: JavaScriptSemanticScopeState = {
scopeId: `${semanticScopeId("block", node)}:function-name`,
parentScopeId: parentScope.scopeId,
kind: "block",
location: range(node),
bindingsComplete: true,
bindings: new Map(),
};
state.scopes.push(scope);
state.scopesById.set(scope.scopeId, scope);
addBinding({
state,
scope,
name: node.id.name,
kind: "function",
mutable: false,
definitionNode: node.id,
initializer: node,
});
return scope;
};
const scopeKind = (
node: t.Node,
parent: t.Node | null,
): JavaScriptSemanticScopeState["kind"] | undefined => {
if (t.isFunction(node)) return "function";
if (t.isClass(node)) return "class";
if (t.isCatchClause(node)) return "catch";
if (
t.isForStatement(node) ||
t.isForOfStatement(node) ||
t.isForInStatement(node)
)
return "block";
// A switch body is one lexical scope shared by all its cases, so `let` in
// two cases must resolve to one binding rather than collide or leak.
if (t.isSwitchCase(node)) return "block";
// Each `static {}` block is its own lexical scope; otherwise a `let` in two
// static blocks would collide in the enclosing class scope.
if (t.isStaticBlock(node)) return "static-block";
if (
t.isBlockStatement(node) &&
!(parent !== null && t.isFunction(parent) && parent.body === node)
)
return "block";
return undefined;
};
const bindImports = (
node: t.ImportDeclaration,
scope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): void => {
for (const specifier of node.specifiers) {
const importedPath = t.isImportDefaultSpecifier(specifier)
? ["default"]
: t.isImportNamespaceSpecifier(specifier)
? []
: [propertyName(specifier.imported) || "[dynamic]"];
addBinding({
state,
scope,
name: specifier.local.name,
kind: "import",
mutable: false,
definitionNode: specifier.local,
initializer: null,
directOrigin: { specifier: node.source.value, importedPath },
});
}
};
const bindFunctionLocals = (
node: t.Function,
scope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): void => {
for (const parameter of node.params)
bindPattern({
pattern: t.isTSParameterProperty(parameter)
? parameter.parameter
: parameter,
initializer: null,
scope,
state,
mutable: true,
kind: "parameter",
});
};
const bindPattern = (input: BindPatternInput): void => {
const {
pattern,
initializer,
scope,
state,
mutable,
kind = "variable",
projection = [],
} = input;
if (t.isTSParameterProperty(pattern)) {
bindPattern({ ...input, pattern: pattern.parameter });
return;
}
if (t.isIdentifier(pattern)) {
addBinding({
state,
scope,
name: pattern.name,
kind,
mutable,
definitionNode: pattern,
initializer,
projection,
});
return;
}
if (t.isAssignmentPattern(pattern)) {
bindPattern({
...input,
pattern: pattern.left,
initializer:
kind === "parameter" || kind === "catch"
? initializer
: (initializer ?? pattern.right),
});
return;
}
if (t.isRestElement(pattern)) {
bindPattern({
...input,
pattern: pattern.argument,
initializer: null,
mutable: true,
});
return;
}
if (t.isObjectPattern(pattern))
for (const property of pattern.properties) {
if (t.isRestElement(property))
bindPattern({
...input,
pattern: property.argument,
initializer: null,
mutable: true,
projection: [],
});
else {
const name = semanticStaticPropertyKey(property.key, property.computed);
bindPattern({
...input,
pattern: property.value,
projection: [...projection, name],
});
}
}
else if (t.isArrayPattern(pattern))
pattern.elements.forEach((element, index) => {
if (element !== null)
bindPattern({
...input,
pattern: element,
projection: [...projection, index],
});
});
};
const addBinding = (input: AddBindingInput): void => {
const {
state,
scope,
name,
kind,
mutable,
definitionNode,
initializer,
directOrigin,
projection = [],
} = input;
let binding = scope.bindings.get(name);
if (binding === undefined) {
if (!scope.bindingsComplete) return;
binding = createBinding(scope, name, kind, mutable);
scope.bindings.set(name, binding);
state.bindingsById.set(binding.bindingId, binding);
}
binding.mutable ||= mutable;
binding.definitions.push({ kind, location: range(definitionNode) });
if (initializer !== null)
binding.initializers.push({ node: initializer, projection });
if (directOrigin !== undefined) binding.directOrigins.push(directOrigin);
};
const createBinding = (
scope: JavaScriptSemanticScopeState,
name: string,
kind: JavaScriptSemanticDefinition["kind"],
mutable: boolean,
): JavaScriptSemanticBindingState => ({
bindingId: `${scope.scopeId}:binding:${encodeURIComponent(name)}`,
scopeId: scope.scopeId,
name,
kind,
mutable,
mutatedPaths: [],
definitions: [],
initializers: [],
directOrigins: [],
});
const addAssignment = (
identifier: t.Identifier,
initializer: t.Node,
scope: JavaScriptSemanticScopeState,
state: JavaScriptSemanticAnalysisState,
): void => {
const binding = resolveSemanticBindingFromScope(
scope,
identifier.name,
state,
);
if (binding === undefined) return;
binding.mutable = true;
binding.definitions.push({ kind: "assignment", location: range(identifier) });
binding.initializers.push({ node: initializer, projection: [] });
};
@@ -0,0 +1,156 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
import { topLevelBinding } from "./javascriptSemanticAnalysis.fixture.js";
const conditionalCandidates = [
'"one"',
'(choice ? "one" : "two")',
'(choice ? "one" : other ? "two" : "three")',
];
const incompatibleValue = {
status: "ambiguous",
reason: "Branches have incompatible values.",
};
const valueOf = (expression: string) =>
topLevelBinding(
analyzeJavaScriptSemantics(`const answer = ${expression};`),
"answer",
).value;
describe("conditional primitive unions", () => {
const cases = conditionalCandidates.flatMap((known) =>
[
"missing",
"unsupported()",
'({ key: "value" })',
'["value"]',
'+"invalid"',
"1e309",
"1e308 + 1e308",
].flatMap((other) => [
`condition ? ${known} : ${other}`,
`condition ? ${other} : ${known}`,
]),
);
it.each(cases)("preserves incompatible alternatives in %s", (expression) => {
expect(valueOf(expression)).toEqual(incompatibleValue);
});
it.each([
[
'condition ? (choice ? "two" : "one") : "three"',
{ status: "union", values: ["one", "three", "two"] },
],
[
'condition ? "three" : (choice ? "two" : "one")',
{ status: "union", values: ["one", "three", "two"] },
],
[
'condition ? (choice ? "two" : "one") : (other ? "one" : "three")',
{ status: "union", values: ["one", "three", "two"] },
],
[
'condition ? (choice ? "two" : "one") : (other ? "one" : "two")',
{ status: "union", values: ["one", "two"] },
],
[
'condition ? (choice ? "one" : "one") : "one"',
{ status: "literal", value: "one" },
],
[
'condition ? (choice ? "one" : "two") : null',
{ status: "union", values: [null, "one", "two"] },
],
[
'condition ? null : (choice ? "one" : "two")',
{ status: "union", values: [null, "one", "two"] },
],
["condition ? null : null", { status: "literal", value: null }],
])("retains exact primitive candidates in %s", (expression, expected) => {
expect(valueOf(expression)).toEqual(expected);
});
it("propagates an incompatible nested branch through an outer union", () => {
expect(
valueOf(
'condition ? (choice ? "one" : "two") : (other ? "three" : missing)',
),
).toEqual(incompatibleValue);
});
});
describe("logical primitive unions", () => {
// Each left-hand set can select the unresolved right-hand operand at runtime.
const operators = [
{
operator: "||",
alternatives: [
'""',
'(choice ? "" : "one")',
'(choice ? "" : other ? "one" : "two")',
],
},
{
operator: "&&",
alternatives: [
'"one"',
'(choice ? 0 : "one")',
'(choice ? 0 : other ? "one" : "two")',
],
},
{
operator: "??",
alternatives: [
"null",
'(choice ? null : "one")',
'(choice ? null : other ? "one" : "two")',
],
},
];
const cases = operators.flatMap(({ operator, alternatives }) =>
alternatives.flatMap((known) =>
["missing", "unsupported()"].flatMap((other) => [
`${known} ${operator} ${other}`,
`${other} ${operator} ${known}`,
]),
),
);
it.each(cases)("preserves unresolved alternatives in %s", (expression) => {
expect(valueOf(expression)).toEqual(incompatibleValue);
});
it.each([
[
'(choice ? "" : "one") || "two"',
{ status: "union", values: ["", "one", "two"] },
],
[
'(choice ? 0 : "one") && "two"',
{ status: "union", values: [0, "one", "two"] },
],
[
'(choice ? null : "one") ?? "two"',
{ status: "union", values: [null, "one", "two"] },
],
['"one" || "one"', { status: "literal", value: "one" }],
["null ?? null", { status: "literal", value: null }],
])(
"retains the conservative primitive union in %s",
(expression, expected) => {
expect(valueOf(expression)).toEqual(expected);
},
);
it.each([
'true ? "one" : missing',
'"one" || missing',
"false && missing",
'"one" ?? missing',
])("does not introduce short-circuit evaluation for %s", (expression) => {
expect(valueOf(expression)).toEqual(incompatibleValue);
});
});
@@ -0,0 +1,370 @@
import * as t from "@babel/types";
import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticEventOperation,
JavaScriptSemanticTimerOperation,
} from "./javascriptSemanticIr.js";
import {
semanticCallableIdForNode,
semanticStaticPropertyName,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
import {
dataEffectLiteralString,
dataEffectMemberCallee,
assignedSemanticResultBindings,
scalarAssignedResultBinding,
semanticProjectedBindingFacts,
} from "./javascriptSemanticDataEffectHelpers.js";
const EVENT_REGISTER_METHODS = [
"on",
"once",
"addListener",
"prependListener",
"prependOnceListener",
] as const;
const EVENT_REMOVE_METHODS = [
"off",
"removeListener",
"removeAllListeners",
] as const;
const EVENT_METHODS = [
...EVENT_REGISTER_METHODS,
...EVENT_REMOVE_METHODS,
"emit",
] as const;
const TIMER_SCHEDULE_METHODS = [
"setTimeout",
"setInterval",
"setImmediate",
] as const;
const TIMER_CANCEL_METHODS = [
"clearTimeout",
"clearInterval",
"clearImmediate",
] as const;
interface AsyncEffectAnalysis {
readonly eventOperations: readonly JavaScriptSemanticEventOperation[];
readonly timerOperations: readonly JavaScriptSemanticTimerOperation[];
}
interface TimerCandidate {
readonly node: t.CallExpression | t.OptionalCallExpression;
readonly method: JavaScriptSemanticTimerOperation["method"];
readonly kind: JavaScriptSemanticTimerOperation["kind"];
readonly ownerCallableId: string | null;
readonly handleBindingId: string | null;
readonly projectedResultBindings: readonly {
readonly bindingId: string;
readonly projectionPath: readonly (string | number | null)[];
readonly resolution: "complete" | "partial";
}[];
}
interface TimerCollectionInput {
readonly node: t.CallExpression | t.OptionalCallExpression;
readonly ownerCallableId: string | null;
readonly state: JavaScriptSemanticAnalysisState;
readonly output: TimerCandidate[];
readonly ancestors: readonly t.Node[];
}
/** Recover explicit EventEmitter and Node timer candidates from inert syntax. */
export const collectJavaScriptSemanticAsyncEffects = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): AsyncEffectAnalysis => {
const events: JavaScriptSemanticEventOperation[] = [];
const timers: TimerCandidate[] = [];
const callableIds = new Set(callables.map(({ callableId }) => callableId));
const callableStack: string[] = [];
const ancestors: t.Node[] = [];
traverseJavaScriptAst(program, {
enter: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableIds.has(callableId))
callableStack.push(callableId);
if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
const ownerCallableId = callableStack.at(-1) ?? null;
collectEvent(node, ownerCallableId, state, events);
collectTimer({
node,
ownerCallableId,
state,
output: timers,
ancestors,
});
}
ancestors.push(node);
},
exit: (node) => {
const callableId = semanticCallableIdForNode(node);
ancestors.pop();
if (callableId !== null && callableStack.at(-1) === callableId)
callableStack.pop();
},
});
return {
eventOperations: events,
timerOperations: resolveTimers(timers),
};
};
const collectEvent = (
node: t.CallExpression | t.OptionalCallExpression,
ownerCallableId: string | null,
state: JavaScriptSemanticAnalysisState,
output: JavaScriptSemanticEventOperation[],
): void => {
const member = dataEffectMemberCallee(node);
if (member === null) return;
const method = EVENT_METHODS.find(
(candidate) =>
candidate ===
semanticStaticPropertyName(member.property, member.computed),
);
if (method === undefined) return;
const kind = eventKind(method);
const eventArgument = node.arguments[0];
const listenerArgument = node.arguments[1];
const emitter = emitterIdentity(member.object, state);
const eventName = dataEffectLiteralString(eventArgument);
output.push({
eventId: `event:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind,
method,
location: range(node),
ownerCallableId,
emitterKey: emitter.key,
emitterBindingId: emitter.bindingId,
eventName,
listenerBindingId: bindingId(listenerArgument, state),
listenerLocation: t.isNode(listenerArgument)
? range(listenerArgument)
: null,
resolution:
eventName === null
? "unresolved"
: emitter.complete
? "complete"
: "partial",
});
};
const eventKind = (
method: JavaScriptSemanticEventOperation["method"],
): JavaScriptSemanticEventOperation["kind"] => {
if (EVENT_REGISTER_METHODS.some((candidate) => candidate === method))
return "register";
if (EVENT_REMOVE_METHODS.some((candidate) => candidate === method))
return "remove";
return "dispatch";
};
const emitterIdentity = (
node: t.Expression | t.Super,
state: JavaScriptSemanticAnalysisState,
): {
readonly key: string;
readonly bindingId: string | null;
readonly complete: boolean;
} => {
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(state, node, node.name);
if (binding !== undefined)
return {
key: `binding:${binding.bindingId}`,
bindingId: binding.bindingId,
complete: true,
};
return {
key: `global:${node.name}`,
bindingId: null,
complete: !semanticResolutionBlocked(state, node, node.name),
};
}
if (t.isThisExpression(node))
return { key: "this", bindingId: null, complete: true };
return {
key: `expression:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
bindingId: null,
complete: false,
};
};
const collectTimer = (input: TimerCollectionInput): void => {
const { node, ownerCallableId, state, output, ancestors } = input;
const method = timerMethod(node.callee, state);
if (method === null) return;
const kind = TIMER_SCHEDULE_METHODS.some((candidate) => candidate === method)
? "schedule"
: "cancel";
const projectedResultBindings = assignedSemanticResultBindings(
node,
ancestors,
state,
);
output.push({
node,
method,
kind,
ownerCallableId,
handleBindingId:
kind === "schedule"
? scalarAssignedResultBinding(projectedResultBindings)
: bindingId(node.arguments[0], state),
projectedResultBindings:
kind === "schedule"
? semanticProjectedBindingFacts(
projectedResultBindings.filter(
({ projectionPath }) => projectionPath.length > 0,
),
)
: [],
});
};
const resolveTimers = (
candidates: readonly TimerCandidate[],
): JavaScriptSemanticTimerOperation[] => {
const schedulesByBinding = new Map<string, TimerCandidate[]>();
for (const candidate of candidates) {
if (candidate.kind !== "schedule") continue;
const ids = [
...(candidate.handleBindingId === null
? []
: [candidate.handleBindingId]),
...candidate.projectedResultBindings.map(({ bindingId }) => bindingId),
];
for (const id of ids) {
const existing = schedulesByBinding.get(id) ?? [];
existing.push(candidate);
schedulesByBinding.set(id, existing);
}
}
return candidates.map((candidate) => {
const linked =
candidate.kind === "cancel" && candidate.handleBindingId !== null
? (schedulesByBinding.get(candidate.handleBindingId) ?? [])
: [];
return {
timerId: timerId(candidate),
kind: candidate.kind,
method: candidate.method,
location: range(candidate.node),
ownerCallableId: candidate.ownerCallableId,
handleBindingId: candidate.handleBindingId,
projectedResultBindings: candidate.projectedResultBindings,
linkedTimerId:
linked.length === 1 && linked[0] !== undefined
? timerId(linked[0])
: null,
delayMilliseconds: timerDelay(candidate),
resolution:
candidate.kind === "schedule"
? "complete"
: linked.length === 1 &&
!linked[0]?.projectedResultBindings.some(
({ bindingId }) => bindingId === candidate.handleBindingId,
)
? "complete"
: linked.length > 1
? "partial"
: "unresolved",
};
});
};
const timerMethod = (
callee: t.Node,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticTimerOperation["method"] | null => {
if (t.isIdentifier(callee)) {
const binding = resolveSemanticBindingState(state, callee, callee.name);
if (binding === undefined) {
const method = admittedTimerMethod(callee.name);
if (method === null) return null;
return semanticResolutionBlocked(state, callee, callee.name)
? null
: method;
}
return timerMethodFromBinding(binding);
}
if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
return null;
const method = admittedTimerMethod(
semanticStaticPropertyName(callee.property, callee.computed),
);
return method !== null &&
t.isIdentifier(callee.object) &&
timerNamespaceBinding(
resolveSemanticBindingState(state, callee.object, callee.object.name),
)
? method
: null;
};
const admittedTimerMethod = (
value: string,
): JavaScriptSemanticTimerOperation["method"] | null =>
[...TIMER_SCHEDULE_METHODS, ...TIMER_CANCEL_METHODS].find(
(candidate) => candidate === value,
) ?? null;
const timerMethodFromBinding = (
binding: JavaScriptSemanticBindingState,
): JavaScriptSemanticTimerOperation["method"] | null => {
for (const { specifier, importedPath } of binding.directOrigins) {
if (!timerModule(specifier)) continue;
const method = admittedTimerMethod(importedPath.at(-1) ?? "");
if (method !== null) return method;
}
return null;
};
const timerNamespaceBinding = (
binding: JavaScriptSemanticBindingState | undefined,
): boolean =>
binding?.directOrigins.some(
({ specifier, importedPath }) =>
timerModule(specifier) && semanticBuiltinNamespacePath(importedPath),
) ?? false;
const timerModule = (specifier: string): boolean =>
specifier === "timers" || specifier === "node:timers";
const bindingId = (
node:
| t.Expression
| t.SpreadElement
| t.JSXNamespacedName
| t.ArgumentPlaceholder
| undefined,
state: JavaScriptSemanticAnalysisState,
): string | null =>
t.isIdentifier(node)
? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
: null;
const timerDelay = (candidate: TimerCandidate): number | null => {
if (candidate.kind !== "schedule" || candidate.method === "setImmediate")
return null;
const delay = candidate.node.arguments[1];
return t.isNumericLiteral(delay) ? delay.value : null;
};
const timerId = (candidate: TimerCandidate): string =>
`timer:${candidate.kind}:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
@@ -0,0 +1,219 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticArgumentFlow,
JavaScriptSemanticCallable,
} from "./javascriptSemanticIr.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
/** Resolution of one call target within the currently analyzed source. */
export interface LocalCallableResolution {
readonly callableIds: readonly string[];
readonly complete: boolean;
readonly reason: string;
}
interface CallResolutionContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;
readonly seenBindings: ReadonlySet<string>;
readonly bindingCache: Map<string, LocalCallableResolution>;
}
/** Inputs needed to resolve one local call target. */
export interface ResolveLocalCallablesInput {
readonly node: t.Node;
readonly state: JavaScriptSemanticAnalysisState;
readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;
readonly seenBindings: ReadonlySet<string>;
readonly bindingCache: Map<string, LocalCallableResolution>;
}
/** Resolve local callable candidates without following dynamic properties. */
export const resolveLocalCallables = (
input: ResolveLocalCallablesInput,
): LocalCallableResolution =>
resolveCallables(input.node, {
state: input.state,
callableById: input.callableById,
seenBindings: input.seenBindings,
bindingCache: input.bindingCache,
});
const resolveCallables = (
node: t.Node,
context: CallResolutionContext,
): LocalCallableResolution => {
const direct = semanticCallableIdForNode(node);
if (direct !== null && context.callableById.has(direct))
return {
callableIds: [direct],
complete: true,
reason: "Direct local callable.",
};
if (t.isIdentifier(node)) return resolveIdentifier(node, context);
if (
t.isTSAsExpression(node) ||
t.isTSTypeAssertion(node) ||
t.isTSNonNullExpression(node)
)
return resolveCallables(node.expression, context);
if (t.isConditionalExpression(node) || t.isLogicalExpression(node))
return resolveAlternatives(
t.isConditionalExpression(node) ? node.consequent : node.left,
t.isConditionalExpression(node) ? node.alternate : node.right,
context,
);
return {
callableIds: [],
complete: false,
reason: `Unsupported ${node.type} call target.`,
};
};
const resolveIdentifier = (
node: t.Identifier,
context: CallResolutionContext,
): LocalCallableResolution => {
const binding = resolveSemanticBindingState(context.state, node, node.name);
return binding === undefined
? {
callableIds: [],
complete: false,
reason: `Unresolved call target ${node.name}.`,
}
: resolveBindingCallables(binding, context);
};
const resolveAlternatives = (
left: t.Node,
right: t.Node,
context: CallResolutionContext,
): LocalCallableResolution => {
const candidates = [left, right].map((candidate) =>
resolveCallables(candidate, context),
);
return {
callableIds: uniqueCallableIds(
candidates.flatMap(({ callableIds }) => callableIds),
),
complete: candidates.every(({ complete }) => complete),
reason: "Conditional or logical call target has multiple candidates.",
};
};
const resolveBindingCallables = (
binding: JavaScriptSemanticBindingState,
context: CallResolutionContext,
): LocalCallableResolution => {
const cached = context.bindingCache.get(binding.bindingId);
if (cached !== undefined) return cached;
if (context.seenBindings.has(binding.bindingId))
return {
callableIds: [],
complete: false,
reason: `Call target alias cycle at ${binding.name}.`,
};
if (binding.initializers.length === 0)
return missingBindingInitializer(binding);
const candidateContext = {
...context,
seenBindings: new Set([...context.seenBindings, binding.bindingId]),
};
const candidates = binding.initializers.map(({ node, projection }) =>
projection.length === 0
? resolveCallables(node, candidateContext)
: {
callableIds: [],
complete: false,
reason: `Projected call target ${binding.name} is unresolved.`,
},
);
const callableIds = uniqueCallableIds(
candidates.flatMap((candidate) => candidate.callableIds),
);
const resolution = {
callableIds,
complete: candidates.every(({ complete }) => complete),
reason:
callableIds.length === 1 && candidates.every(({ complete }) => complete)
? "Unique local callable target."
: `Call target ${binding.name} has ambiguous or unsupported assignments.`,
};
if (resolution.complete)
context.bindingCache.set(binding.bindingId, resolution);
return resolution;
};
const missingBindingInitializer = (
binding: JavaScriptSemanticBindingState,
): LocalCallableResolution => ({
callableIds: [],
complete: false,
reason:
binding.kind === "import"
? `Call target ${binding.name} is imported from outside this source.`
: `Call target ${binding.name} has no local initializer.`,
});
/** Find all bindings introduced by one positional parameter pattern. */
export const parameterBindings = (
callable: JavaScriptSemanticCallable,
index: number,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBindingState[] => {
if (callable.bodyScopeId === null) return [];
const scope = state.scopesById.get(callable.bodyScopeId);
if (scope === undefined) return [];
return [...scope.bindings.values()]
.filter(
(binding) =>
binding.kind === "parameter" &&
binding.definitions.some(
({ kind, location }) =>
kind === "parameter" &&
parameterAcceptsArgument(callable, location, index, state),
),
)
.sort((left, right) => compareCodePoints(left.bindingId, right.bindingId));
};
const parameterAcceptsArgument = (
callable: JavaScriptSemanticCallable,
location: JavaScriptSemanticArgumentFlow["parameterLocation"],
argumentIndex: number,
state: JavaScriptSemanticAnalysisState,
): boolean => {
const node = state.callableNodesById.get(callable.callableId);
if (!t.isFunction(node)) return false;
const parameterIndex = node.params.findIndex((parameter) =>
rangeContains(range(parameter), location),
);
if (parameterIndex === argumentIndex) return true;
return (
parameterIndex >= 0 &&
parameterIndex < argumentIndex &&
t.isRestElement(node.params[parameterIndex])
);
};
const rangeContains = (
outer: JavaScriptSemanticArgumentFlow["parameterLocation"],
inner: JavaScriptSemanticArgumentFlow["parameterLocation"],
): boolean =>
(outer.start.line < inner.start.line ||
(outer.start.line === inner.start.line &&
outer.start.column <= inner.start.column)) &&
(outer.end.line > inner.end.line ||
(outer.end.line === inner.end.line &&
outer.end.column >= inner.end.column));
const uniqueCallableIds = (values: readonly string[]): string[] =>
[...new Set(values)].sort(compareCodePoints);
@@ -0,0 +1,430 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticArgumentFlow,
JavaScriptSemanticCallable,
JavaScriptSemanticCallResultFlow,
JavaScriptSemanticCallReturnFlow,
JavaScriptSemanticCallSite,
JavaScriptSemanticClosureCapture,
JavaScriptSemanticFrontier,
} from "./javascriptSemanticIr.js";
import {
semanticCallableIdForNode,
semanticReferenceRole,
semanticStaticPropertyKey,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
isUnshadowedGlobal,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import {
type LocalCallableResolution,
parameterBindings,
resolveLocalCallables,
} from "./javascriptSemanticCallResolution.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
import { assignedSemanticResultBindings } from "./javascriptSemanticDataEffectHelpers.js";
/** Local call, flow, capture, and unsupported-frontier facts. */
export interface JavaScriptSemanticCallAnalysis {
readonly callSites: readonly JavaScriptSemanticCallSite[];
readonly argumentFlows: readonly JavaScriptSemanticArgumentFlow[];
readonly callReturnFlows: readonly JavaScriptSemanticCallReturnFlow[];
readonly callResultFlows: readonly JavaScriptSemanticCallResultFlow[];
readonly closureCaptures: readonly JavaScriptSemanticClosureCapture[];
readonly frontiers: readonly JavaScriptSemanticFrontier[];
}
interface MutableCallAnalysis {
readonly callSites: JavaScriptSemanticCallSite[];
readonly argumentFlows: JavaScriptSemanticArgumentFlow[];
readonly callReturnFlows: JavaScriptSemanticCallReturnFlow[];
readonly callResultFlows: JavaScriptSemanticCallResultFlow[];
readonly closureCaptures: JavaScriptSemanticClosureCapture[];
readonly frontiers: JavaScriptSemanticFrontier[];
}
interface CallCollectionContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;
readonly output: MutableCallAnalysis;
readonly bindingResolutionCache: Map<string, LocalCallableResolution>;
readonly parameterBindingCache: Map<
string,
readonly JavaScriptSemanticBindingState[]
>;
readonly ancestors: t.Node[];
}
/** Recover direct-call and lexical-capture candidates from inert syntax. */
export const collectJavaScriptSemanticCalls = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticCallAnalysis => {
const output: MutableCallAnalysis = {
callSites: [],
argumentFlows: [],
callReturnFlows: [],
callResultFlows: [],
closureCaptures: [],
frontiers: [],
};
const callableById = new Map(
callables.map((callable) => [callable.callableId, callable]),
);
const context: CallCollectionContext = {
state,
callableById,
output,
bindingResolutionCache: new Map(),
parameterBindingCache: new Map(),
ancestors: [],
};
const callableStack: JavaScriptSemanticCallable[] = [];
traverseJavaScriptAst(program, {
enter: (node, parent) => {
const callableId = semanticCallableIdForNode(node);
const callable =
callableId === null ? undefined : callableById.get(callableId);
if (callable !== undefined) callableStack.push(callable);
const owner = enclosingFunction(callableStack);
collectCapture(node, parent, owner, context);
collectDynamicProperty(node, owner, state, output);
collectDynamicScope(node, owner, state, output);
if (
t.isCallExpression(node) ||
t.isOptionalCallExpression(node) ||
t.isNewExpression(node)
)
collectCallSite(node, parent, owner, context);
context.ancestors.push(node);
},
exit: (node) => {
context.ancestors.pop();
const callableId = semanticCallableIdForNode(node);
if (
callableId !== null &&
callableStack.at(-1)?.callableId === callableId
)
callableStack.pop();
},
});
return {
callSites: output.callSites,
argumentFlows: output.argumentFlows,
callReturnFlows: output.callReturnFlows,
callResultFlows: output.callResultFlows,
closureCaptures: output.closureCaptures,
frontiers: output.frontiers,
};
};
const collectCallSite = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
parent: t.Node | null,
owner: JavaScriptSemanticCallable | undefined,
context: CallCollectionContext,
): void => {
const { state, callableById, output } = context;
const resolution = resolveLocalCallables({
node: node.callee,
state,
callableById,
seenBindings: new Set(),
bindingCache: context.bindingResolutionCache,
});
const callSiteId = semanticCallSiteId(node);
const argumentsValue = retainedArguments(node.arguments);
const site: JavaScriptSemanticCallSite = {
callSiteId,
kind: t.isNewExpression(node) ? "construct" : "call",
callerCallableId: owner?.callableId ?? null,
location: range(node),
calleeLocation: range(node.callee),
resolution:
resolution.callableIds.length === 1 && resolution.complete
? "exact"
: resolution.callableIds.length > 0
? "ambiguous"
: "unresolved",
calleeCallableIds: resolution.callableIds,
arguments: argumentsValue,
};
output.callSites.push(site);
collectCallResultFlow(site, node, context);
if (site.resolution !== "exact")
addFrontier(
{
kind: "dynamic-call",
callableId: owner?.callableId ?? null,
location: range(node.callee),
reason: resolution.reason,
},
state,
output,
);
collectArgumentFlows(site, node, context);
if (site.kind === "call")
collectReturnFlows(site, callableById, state, output);
};
const collectCallResultFlow = (
site: JavaScriptSemanticCallSite,
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
context: CallCollectionContext,
): void => {
for (const assigned of assignedSemanticResultBindings(
node,
context.ancestors,
context.state,
).filter(({ projectionPath }) => projectionPath.length === 0)) {
const binding = [...context.state.bindingsById.values()].find(
({ bindingId }) => bindingId === assigned.bindingId,
);
if (binding === undefined) continue;
const identifierRange = range(assigned.identifier);
const definition = binding.definitions.find(
({ location }) =>
location.start.line === identifierRange.start.line &&
location.start.column === identifierRange.start.column &&
location.end.line === identifierRange.end.line &&
location.end.column === identifierRange.end.column,
);
if (definition === undefined) continue;
context.output.callResultFlows.push({
callSiteId: site.callSiteId,
bindingId: binding.bindingId,
definitionLocation: definition.location,
});
}
};
const retainedArguments = (
nodes: readonly (
| t.Expression
| t.SpreadElement
| t.JSXNamespacedName
| t.ArgumentPlaceholder
)[],
): JavaScriptSemanticCallSite["arguments"] => {
const retained: JavaScriptSemanticCallSite["arguments"][number][] = [];
for (const [index, node] of nodes.entries()) {
retained.push({
index,
location: range(node),
spread: t.isSpreadElement(node),
});
}
return retained;
};
const collectArgumentFlows = (
site: JavaScriptSemanticCallSite,
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
context: CallCollectionContext,
): void => {
const { callableById, output } = context;
const retainedIndexes = new Set(site.arguments.map(({ index }) => index));
let positionIsExact = true;
for (const [index, argument] of node.arguments.entries()) {
if (t.isSpreadElement(argument)) {
positionIsExact = false;
continue;
}
if (
!positionIsExact ||
!retainedIndexes.has(index) ||
!t.isExpression(argument)
)
continue;
for (const callableId of site.calleeCallableIds) {
const callable = callableById.get(callableId);
if (callable === undefined) continue;
for (const parameter of cachedParameterBindings(
callable,
index,
context,
)) {
const definition = parameter.definitions.find(
({ kind }) => kind === "parameter",
);
if (definition === undefined) continue;
output.argumentFlows.push({
callSiteId: site.callSiteId,
argumentIndex: index,
argumentLocation: range(argument),
callableId,
parameterBindingId: parameter.bindingId,
parameterLocation: definition.location,
});
}
}
}
};
const cachedParameterBindings = (
callable: JavaScriptSemanticCallable,
index: number,
context: CallCollectionContext,
): readonly JavaScriptSemanticBindingState[] => {
const key = `${callable.callableId}:${String(index)}`;
const cached = context.parameterBindingCache.get(key);
if (cached !== undefined) return cached;
const bindings = parameterBindings(callable, index, context.state);
context.parameterBindingCache.set(key, bindings);
return bindings;
};
const collectReturnFlows = (
site: JavaScriptSemanticCallSite,
callableById: ReadonlyMap<string, JavaScriptSemanticCallable>,
state: JavaScriptSemanticAnalysisState,
output: MutableCallAnalysis,
): void => {
for (const callableId of site.calleeCallableIds) {
const callable = callableById.get(callableId);
if (callable === undefined) continue;
for (const returnSite of callable.returnSites) {
output.callReturnFlows.push({
callSiteId: site.callSiteId,
callableId,
returnSiteId: returnSite.returnSiteId,
returnLocation: returnSite.location,
});
}
}
};
const collectCapture = (
node: t.Node,
parent: t.Node | null,
owner: JavaScriptSemanticCallable | undefined,
context: CallCollectionContext,
): void => {
const { state, output } = context;
if (
!t.isIdentifier(node) ||
parent === null ||
owner === undefined ||
owner.bodyScopeId === null
)
return;
if (semanticReferenceRole(node, parent) === null) return;
const binding = resolveSemanticBindingState(state, node, node.name);
if (
binding === undefined ||
bindingIsWithinCallable(binding, owner.bodyScopeId, state)
)
return;
output.closureCaptures.push({
callableId: owner.callableId,
bindingId: binding.bindingId,
referenceLocation: range(node),
});
};
const collectDynamicProperty = (
node: t.Node,
owner: JavaScriptSemanticCallable | undefined,
state: JavaScriptSemanticAnalysisState,
output: MutableCallAnalysis,
): void => {
if (
(t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) &&
semanticStaticPropertyKey(node.property, node.computed) === null
)
addFrontier(
{
kind: "dynamic-property",
callableId: owner?.callableId ?? null,
location: range(node.property),
reason: "Computed member property is not a static string or number.",
},
state,
output,
);
else if (
(t.isObjectProperty(node) || t.isObjectMethod(node)) &&
node.computed &&
semanticStaticPropertyKey(node.key, true) === null
)
addFrontier(
{
kind: "dynamic-property",
callableId: owner?.callableId ?? null,
location: range(node.key),
reason: "Computed object property is not a static string or number.",
},
state,
output,
);
};
/**
* `with (o) { … }` and `eval("…")` decide at runtime which bindings exist, so
* every name inside them is unresolvable statically. Recording the frontier
* is what keeps the analyzer from presenting an empty or partial resolution as
* an observed fact — silence here would read as "nothing to resolve".
*/
const collectDynamicScope = (
node: t.Node,
owner: JavaScriptSemanticCallable | undefined,
state: JavaScriptSemanticAnalysisState,
output: MutableCallAnalysis,
): void => {
const reason = t.isWithStatement(node)
? "`with` introduces a runtime binding environment; names inside are not statically resolvable."
: t.isCallExpression(node) && isUnshadowedGlobal(node.callee, state, "eval")
? "`eval` can declare bindings at runtime; names inside the evaluated source are not statically resolvable."
: null;
if (reason === null) return;
addFrontier(
{
kind: "dynamic-scope",
callableId: owner?.callableId ?? null,
location: range(node),
reason,
},
state,
output,
);
};
const addFrontier = (
frontier: JavaScriptSemanticFrontier,
state: JavaScriptSemanticAnalysisState,
output: MutableCallAnalysis,
): void => {
output.frontiers.push(frontier);
};
const bindingIsWithinCallable = (
binding: JavaScriptSemanticBindingState,
bodyScopeId: string,
state: JavaScriptSemanticAnalysisState,
): boolean => {
let scope = state.scopesById.get(binding.scopeId);
while (scope !== undefined) {
if (scope.scopeId === bodyScopeId) return true;
scope =
scope.parentScopeId === null
? undefined
: state.scopesById.get(scope.parentScopeId);
}
return false;
};
const enclosingFunction = (
stack: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticCallable | undefined =>
stack.findLast(({ kind }) => kind !== "class");
const semanticCallSiteId = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
): string =>
`call:${t.isNewExpression(node) ? "construct" : "call"}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
@@ -0,0 +1,381 @@
import * as t from "@babel/types";
import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticChildProcessInteraction,
JavaScriptSemanticChildProcessSpawn,
} from "./javascriptSemanticIr.js";
import {
semanticCallableIdForNode,
semanticStaticPropertyName,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
import {
dataEffectLiteralString,
dataEffectMemberCallee,
assignedSemanticResultBindings,
scalarAssignedResultBinding,
semanticProjectedBindingFacts,
} from "./javascriptSemanticDataEffectHelpers.js";
const CHILD_PROCESS_METHODS = ["spawn", "exec", "execFile", "fork"] as const;
const CHILD_LISTENER_METHODS = ["on", "once", "addListener"] as const;
interface ChildProcessAnalysis {
readonly childProcessSpawns: readonly JavaScriptSemanticChildProcessSpawn[];
readonly childProcessInteractions: readonly JavaScriptSemanticChildProcessInteraction[];
}
interface SpawnCandidate {
readonly node: t.CallExpression | t.OptionalCallExpression;
readonly method: JavaScriptSemanticChildProcessSpawn["method"];
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
readonly projectedResultBindings: readonly {
readonly bindingId: string;
readonly projectionPath: readonly (string | number | null)[];
readonly resolution: "complete" | "partial";
}[];
}
interface ChildInteractionContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly spawnByNode: WeakMap<t.Node, SpawnCandidate>;
readonly spawnsByBinding: ReadonlyMap<string, readonly SpawnCandidate[]>;
}
/** Recover explicit asynchronous node:child_process ownership candidates. */
export const collectJavaScriptSemanticChildProcesses = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): ChildProcessAnalysis => {
const candidates = collectSpawns(program, state, callables);
const childProcessSpawns = candidates.map((candidate) =>
immutableSpawn(candidate),
);
return {
childProcessSpawns,
childProcessInteractions: collectInteractions(
program,
state,
callables,
candidates,
),
};
};
const collectSpawns = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): SpawnCandidate[] => {
const output: SpawnCandidate[] = [];
const admittedCallables = new Set(
callables.map(({ callableId }) => callableId),
);
const callableStack: string[] = [];
const ancestors: t.Node[] = [];
traverseJavaScriptAst(program, {
enter: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && admittedCallables.has(callableId))
callableStack.push(callableId);
if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
const method = childProcessMethod(node.callee, state);
if (method !== null) {
const projectedResultBindings = assignedSemanticResultBindings(
node,
ancestors,
state,
);
output.push({
node,
method,
ownerCallableId: callableStack.at(-1) ?? null,
resultBindingId: scalarAssignedResultBinding(
projectedResultBindings,
),
projectedResultBindings: semanticProjectedBindingFacts(
projectedResultBindings.filter(
({ projectionPath }) => projectionPath.length > 0,
),
),
});
}
}
ancestors.push(node);
},
exit: (node) => {
ancestors.pop();
popCallable(node, callableStack);
},
});
return output;
};
const immutableSpawn = (
candidate: SpawnCandidate,
): JavaScriptSemanticChildProcessSpawn => {
const options = spawnOptions(candidate);
const command = dataEffectLiteralString(candidate.node.arguments[0]);
return {
processId: spawnId(candidate),
method: candidate.method,
location: range(candidate.node),
ownerCallableId: candidate.ownerCallableId,
resultBindingId: candidate.resultBindingId,
projectedResultBindings: candidate.projectedResultBindings,
command,
argvCount: spawnArgvCount(candidate),
environmentSupplied: objectHasProperty(options, "env"),
stdioMode: stdioMode(options),
resolution: command === null ? "partial" : "complete",
};
};
const collectInteractions = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
spawns: readonly SpawnCandidate[],
): JavaScriptSemanticChildProcessInteraction[] => {
const output: JavaScriptSemanticChildProcessInteraction[] = [];
const callableIds = new Set(callables.map(({ callableId }) => callableId));
const callableStack: string[] = [];
const spawnByNode = new WeakMap<t.Node, SpawnCandidate>();
const spawnsByBinding = new Map<string, SpawnCandidate[]>();
for (const spawn of spawns) {
spawnByNode.set(spawn.node, spawn);
const ids = [
...(spawn.resultBindingId === null ? [] : [spawn.resultBindingId]),
...spawn.projectedResultBindings.map(({ bindingId }) => bindingId),
];
for (const id of ids) {
const existing = spawnsByBinding.get(id) ?? [];
existing.push(spawn);
spawnsByBinding.set(id, existing);
}
}
const context: ChildInteractionContext = {
state,
spawnByNode,
spawnsByBinding,
};
traverseJavaScriptAst(program, {
enter: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableIds.has(callableId))
callableStack.push(callableId);
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
return;
const interaction = childInteraction(
node,
callableStack.at(-1) ?? null,
context,
);
if (interaction === null) return;
output.push(interaction);
},
exit: (node) => popCallable(node, callableStack),
});
return output;
};
const childInteraction = (
node: t.CallExpression | t.OptionalCallExpression,
ownerCallableId: string | null,
context: ChildInteractionContext,
): JavaScriptSemanticChildProcessInteraction | null => {
const { state, spawnByNode, spawnsByBinding } = context;
const member = dataEffectMemberCallee(node);
if (member === null) return null;
const method = semanticStaticPropertyName(member.property, member.computed);
const binding = objectBinding(member.object, state);
const linked = resolveChildCandidates(
member.object,
binding,
spawnByNode,
spawnsByBinding,
);
if (linked.length === 0) return null;
const classification = classifyInteraction(method, node.arguments[0]);
if (classification === null) return null;
const { kind, interactionMethod, eventName } = classification;
const listener = node.arguments[1];
return {
interactionId: `child:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind,
method: interactionMethod,
location: range(node),
ownerCallableId,
processBindingId: binding?.bindingId ?? null,
linkedProcessIds: linked
.map((candidate) => spawnId(candidate))
.sort(compareCodePoints),
eventName: kind === "listener" ? eventName : null,
signalName:
kind === "signal"
? (dataEffectLiteralString(node.arguments[0]) ?? "SIGTERM")
: null,
listenerLocation:
kind === "listener" && t.isNode(listener) ? range(listener) : null,
resolution:
linked.length === 1 &&
!linked[0]?.projectedResultBindings.some(
({ bindingId }) => bindingId === binding?.bindingId,
)
? "complete"
: "partial",
};
};
const classifyInteraction = (
method: string,
argument:
| t.Expression
| t.SpreadElement
| t.JSXNamespacedName
| t.ArgumentPlaceholder
| undefined,
): {
readonly kind: JavaScriptSemanticChildProcessInteraction["kind"];
readonly interactionMethod: JavaScriptSemanticChildProcessInteraction["method"];
readonly eventName: "exit" | "error" | null;
} | null => {
if (method === "kill")
return { kind: "signal", interactionMethod: "kill", eventName: null };
const listenerMethod = CHILD_LISTENER_METHODS.find(
(candidate) => candidate === method,
);
const eventName = dataEffectLiteralString(argument);
return listenerMethod !== undefined &&
(eventName === "exit" || eventName === "error")
? { kind: "listener", interactionMethod: listenerMethod, eventName }
: null;
};
const childProcessMethod = (
callee: t.Node,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticChildProcessSpawn["method"] | null => {
if (t.isIdentifier(callee)) {
const binding = resolveSemanticBindingState(state, callee, callee.name);
return binding === undefined ? null : methodFromBinding(binding);
}
if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
return null;
const method = admittedChildMethod(
semanticStaticPropertyName(callee.property, callee.computed),
);
if (method === null || !t.isIdentifier(callee.object)) return null;
const binding = resolveSemanticBindingState(
state,
callee.object,
callee.object.name,
);
return childProcessNamespace(binding) ? method : null;
};
const methodFromBinding = (
binding: JavaScriptSemanticBindingState,
): JavaScriptSemanticChildProcessSpawn["method"] | null => {
for (const { specifier, importedPath } of binding.directOrigins) {
if (!childProcessModule(specifier)) continue;
const method = admittedChildMethod(importedPath.at(-1) ?? "");
if (method !== null) return method;
}
return null;
};
const admittedChildMethod = (
value: string,
): JavaScriptSemanticChildProcessSpawn["method"] | null =>
CHILD_PROCESS_METHODS.find((candidate) => candidate === value) ?? null;
const childProcessNamespace = (
binding: JavaScriptSemanticBindingState | undefined,
): boolean =>
binding?.directOrigins.some(
({ specifier, importedPath }) =>
childProcessModule(specifier) &&
semanticBuiltinNamespacePath(importedPath),
) ?? false;
const childProcessModule = (specifier: string): boolean =>
specifier === "child_process" || specifier === "node:child_process";
const resolveChildCandidates = (
node: t.Node,
binding: JavaScriptSemanticBindingState | undefined,
spawnByNode: WeakMap<t.Node, SpawnCandidate>,
spawnsByBinding: ReadonlyMap<string, readonly SpawnCandidate[]>,
): readonly SpawnCandidate[] => {
const direct = spawnByNode.get(node);
if (direct !== undefined) return [direct];
return binding === undefined
? []
: (spawnsByBinding.get(binding.bindingId) ?? []);
};
const spawnOptions = (candidate: SpawnCandidate): t.ObjectExpression | null => {
const index = candidate.method === "exec" ? 1 : 2;
const value = candidate.node.arguments[index];
return t.isObjectExpression(value) ? value : null;
};
const spawnArgvCount = (candidate: SpawnCandidate): number | null => {
if (candidate.method === "exec") return null;
const args = candidate.node.arguments[1];
return t.isArrayExpression(args) ? args.elements.length : null;
};
const objectHasProperty = (
object: t.ObjectExpression | null,
name: string,
): boolean => objectProperty(object, name) !== null;
const stdioMode = (options: t.ObjectExpression | null): string => {
const property = objectProperty(options, "stdio");
if (property === null || !t.isObjectProperty(property)) return "default";
if (t.isStringLiteral(property.value)) return property.value.value;
if (t.isArrayExpression(property.value)) return "array";
return "dynamic";
};
const objectProperty = (
object: t.ObjectExpression | null,
name: string,
): t.ObjectMethod | t.ObjectProperty | null =>
object?.properties.find(
(property): property is t.ObjectMethod | t.ObjectProperty =>
(t.isObjectMethod(property) || t.isObjectProperty(property)) &&
// `{[env]: vars}` has a dynamic key; treating it as `env` would claim
// the caller supplied an environment when the real key is unknown.
semanticStaticPropertyName(property.key, property.computed) === name,
) ?? null;
const objectBinding = (
node: t.Expression | t.Super,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBindingState | undefined =>
t.isIdentifier(node)
? resolveSemanticBindingState(state, node, node.name)
: undefined;
const popCallable = (node: t.Node, stack: string[]): void => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && stack.at(-1) === callableId) stack.pop();
};
const spawnId = (candidate: SpawnCandidate): string =>
`child:spawn:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
@@ -0,0 +1,36 @@
/** Exact retention state for one callable's direct returns. */
export type JavaScriptSemanticReturnCoverage = {
readonly retainedCount: number;
} & {
readonly status: "complete" | "partial";
readonly omittedCount: 0 | null;
};
/** Coverage state for one semantic recovery pass. */
export type JavaScriptSemanticCoverage =
| {
readonly status: "complete" | "partial";
readonly omittedCount: 0;
}
| {
readonly status: "failed";
readonly omittedCount: null;
};
/** Classify whole-file semantic coverage from parser recovery. */
export const semanticCoverage = (
parserPartial: boolean,
): JavaScriptSemanticCoverage => ({
status: parserPartial ? "partial" : "complete",
omittedCount: 0,
});
/** Classify one callable's direct-return coverage. */
export const semanticReturnCoverage = (
retainedCount: number,
parserPartial: boolean,
): JavaScriptSemanticReturnCoverage => ({
status: parserPartial ? "partial" : "complete",
retainedCount,
omittedCount: 0,
});
@@ -0,0 +1,299 @@
import * as t from "@babel/types";
import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import {
semanticStaticPropertyKey,
semanticStaticPropertyName,
} from "./javascriptAstValues.js";
export interface SemanticProjectedBinding {
readonly bindingId: string;
readonly identifier: t.Identifier;
readonly projectionPath: readonly (string | number | null)[];
readonly resolution: "complete" | "partial";
}
/** Resolve bindings written by the nearest variable or assignment owner. */
export const assignedSemanticResultBindings = (
node: t.Node,
ancestors: readonly t.Node[],
state: JavaScriptSemanticAnalysisState,
): SemanticProjectedBinding[] => {
for (let index = ancestors.length - 1; index >= 0; index -= 1) {
const owner = ancestors[index];
if (owner === undefined) continue;
let pattern: t.Node | undefined;
let source: t.Node | null = null;
if (t.isVariableDeclarator(owner)) {
pattern = owner.id;
source = owner.init ?? null;
} else if (t.isAssignmentExpression(owner)) {
pattern = owner.left;
source = owner.right;
}
if (
pattern !== undefined &&
source !== null &&
assignedSourceIs(node, source)
)
return projectedPatternBindings(pattern, state);
if (semanticCallableIdForNode(owner) !== null) return [];
}
return [];
};
const assignedSourceIs = (node: t.Node, source: t.Node): boolean => {
let value = source;
while (true) {
if (t.isAwaitExpression(value)) value = value.argument;
else if (
t.isParenthesizedExpression(value) ||
t.isTSAsExpression(value) ||
t.isTSTypeAssertion(value) ||
t.isTypeCastExpression(value) ||
t.isTSSatisfiesExpression(value)
)
value = value.expression;
else break;
}
return value === node;
};
const projectedPatternBindings = (
pattern: t.Node,
state: JavaScriptSemanticAnalysisState,
): SemanticProjectedBinding[] => {
const output: SemanticProjectedBinding[] = [];
const visit = (
current: t.Node,
path: readonly (string | number | null)[],
partial: boolean,
): void => {
if (t.isIdentifier(current)) {
const binding = resolveSemanticBindingState(state, current, current.name);
if (binding !== undefined)
output.push({
bindingId: binding.bindingId,
identifier: current,
projectionPath: path,
resolution: partial ? "partial" : "complete",
});
return;
}
if (t.isAssignmentPattern(current)) return visit(current.left, path, true);
if (t.isRestElement(current))
return visit(current.argument, [...path, null], true);
if (t.isObjectPattern(current)) {
for (const property of current.properties) {
if (t.isRestElement(property))
visit(property.argument, [...path, null], true);
else
visit(
property.value,
[
...path,
semanticStaticPropertyKey(property.key, property.computed),
],
partial ||
semanticStaticPropertyKey(property.key, property.computed) ===
null,
);
}
} else if (t.isArrayPattern(current)) {
current.elements.forEach((element, index) => {
if (element !== null) visit(element, [...path, index], partial);
});
}
};
visit(pattern, [], false);
return output;
};
export const semanticProjectedBindingFacts = (
bindings: readonly SemanticProjectedBinding[],
): Omit<SemanticProjectedBinding, "identifier">[] =>
bindings.map(({ identifier: _identifier, ...fact }) => fact);
/** Return a scalar owner only for an unprojected identifier result. */
export const scalarAssignedResultBinding = (
bindings: readonly SemanticProjectedBinding[],
): string | null =>
bindings.length === 1 && bindings[0]?.projectionPath.length === 0
? (bindings[0]?.bindingId ?? null)
: null;
/** Shared mutable stacks reset before each deterministic data-effect pass. */
export interface DataEffectTraversalContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly callableIds: ReadonlySet<string>;
readonly callableStack: string[];
readonly ancestors: t.Node[];
}
/** Resolve a direct or namespace-imported built-in method. */
export const builtinDataEffectMethod = (
callee: t.Node,
state: JavaScriptSemanticAnalysisState,
specifiers: readonly string[],
): string | null => {
if (t.isIdentifier(callee)) {
const binding = resolveSemanticBindingState(state, callee, callee.name);
return moduleMethod(binding, specifiers);
}
if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
return null;
if (!t.isIdentifier(callee.object)) return null;
const binding = resolveSemanticBindingState(
state,
callee.object,
callee.object.name,
);
const namespace = binding?.directOrigins.some(
({ specifier, importedPath }) =>
specifiers.includes(specifier) &&
semanticBuiltinNamespacePath(importedPath),
);
return namespace
? semanticStaticPropertyName(callee.property, callee.computed)
: null;
};
const moduleMethod = (
binding: JavaScriptSemanticBindingState | undefined,
specifiers: readonly string[],
): string | null => {
for (const { specifier, importedPath } of binding?.directOrigins ?? []) {
if (!specifiers.includes(specifier)) continue;
return importedPath.at(-1) ?? null;
}
return null;
};
/** Recognize global or node:process aliases without accepting shadowing. */
export const isSemanticProcessObject = (
node: t.Expression | t.Super,
state: JavaScriptSemanticAnalysisState,
): boolean => {
if (!t.isIdentifier(node)) return false;
const binding = resolveSemanticBindingState(state, node, node.name);
if (binding === undefined)
return (
node.name === "process" &&
!semanticResolutionBlocked(state, node, node.name)
);
return binding.directOrigins.some(
({ specifier }) => specifier === "process" || specifier === "node:process",
);
};
/** Resolve the nearest direct variable/assignment owner before a callable. */
export const outerDataEffectBinding = (
node: t.Node,
context: DataEffectTraversalContext,
): string | null => {
return scalarAssignedResultBinding(
assignedSemanticResultBindings(node, context.ancestors, context.state),
);
};
/** Traverse with exact callable and ancestor stacks. */
export const traverseDataEffects = (
program: t.Program,
context: DataEffectTraversalContext,
visit: (node: t.Node, parent: t.Node | null) => void,
): void => {
context.callableStack.length = 0;
context.ancestors.length = 0;
traverseJavaScriptAst(program, {
enter: (node, parent) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && context.callableIds.has(callableId))
context.callableStack.push(callableId);
visit(node, parent);
context.ancestors.push(node);
},
exit: (node) => {
context.ancestors.pop();
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && context.callableStack.at(-1) === callableId)
context.callableStack.pop();
},
});
};
/** Resolve one direct identifier argument to a lexical binding. */
export const dataEffectArgumentBindingId = (
node:
| t.Expression
| t.SpreadElement
| t.JSXNamespacedName
| t.ArgumentPlaceholder
| undefined,
state: JavaScriptSemanticAnalysisState,
): string | null =>
t.isIdentifier(node)
? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
: null;
/** Read one JSON primitive default without evaluating code. */
export const dataEffectPrimitive = (
node: t.Node,
): string | number | boolean | null => {
if (t.isStringLiteral(node) || t.isNumericLiteral(node)) return node.value;
if (t.isBooleanLiteral(node)) return node.value;
return null;
};
/** Read one static string or expression-free template. */
export const dataEffectLiteralString = (
node:
| t.Expression
| t.SpreadElement
| t.JSXNamespacedName
| t.ArgumentPlaceholder
| undefined,
): string | null => {
if (t.isStringLiteral(node)) return node.value;
if (t.isTemplateLiteral(node) && node.expressions.length === 0)
return node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? null;
return null;
};
/** Read a member callee from call or construction syntax. */
export const dataEffectMemberCallee = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
): t.MemberExpression | t.OptionalMemberExpression | null =>
t.isMemberExpression(node.callee) || t.isOptionalMemberExpression(node.callee)
? node.callee
: null;
/** Read a parent member's object when present. */
export const dataEffectMemberObject = (
node: t.Node | null,
): t.Expression | t.Super | null =>
node !== null &&
(t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
? node.object
: null;
/** Compare Babel source offsets for exact containment. */
export const containsSemanticNode = (outer: t.Node, inner: t.Node): boolean =>
outer.start !== null &&
outer.start !== undefined &&
outer.end !== null &&
outer.end !== undefined &&
inner.start !== null &&
inner.start !== undefined &&
inner.end !== null &&
inner.end !== undefined &&
outer.start <= inner.start &&
outer.end >= inner.end;
@@ -0,0 +1,430 @@
import * as t from "@babel/types";
import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
import type {
JavaScriptSemanticBoundaryOperation,
JavaScriptSemanticCallable,
JavaScriptSemanticConfigurationOperation,
JavaScriptSemanticRequestOperation,
} from "./javascriptSemanticIr.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import {
semanticStaticPropertyKey,
semanticStaticPropertyName,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
} from "./javascriptSemanticState.js";
import {
builtinDataEffectMethod as builtinMethod,
containsSemanticNode as containsNode,
dataEffectArgumentBindingId as argumentBindingId,
dataEffectLiteralString as literalString,
dataEffectMemberCallee as memberCallee,
dataEffectMemberObject as memberObject,
dataEffectPrimitive as primitiveValue,
isSemanticProcessObject as isProcessObject,
outerDataEffectBinding as outerAssignedBinding,
assignedSemanticResultBindings,
semanticProjectedBindingFacts,
traverseDataEffects as traverseWithContext,
type DataEffectTraversalContext as TraversalContext,
} from "./javascriptSemanticDataEffectHelpers.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
interface DataEffectAnalysis {
readonly configurationOperations: readonly JavaScriptSemanticConfigurationOperation[];
readonly requestOperations: readonly JavaScriptSemanticRequestOperation[];
readonly boundaryOperations: readonly JavaScriptSemanticBoundaryOperation[];
}
interface ConfigurationCandidate {
readonly node: t.Node;
readonly operation: JavaScriptSemanticConfigurationOperation;
}
interface RequestCandidate {
readonly node: t.CallExpression | t.OptionalCallExpression | t.NewExpression;
readonly operation: JavaScriptSemanticRequestOperation;
}
/** Recover configuration, request, and boundary candidates from inert syntax. */
export const collectJavaScriptSemanticDataEffects = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): DataEffectAnalysis => {
const context: TraversalContext = {
state,
callableIds: new Set(callables.map(({ callableId }) => callableId)),
callableStack: [],
ancestors: [],
};
const configuration = collectConfigurations(program, context);
const requests = collectRequests(program, context);
return {
configurationOperations: [
...configuration.map(({ operation }) => operation),
...collectDefaults(program, context, configuration),
],
requestOperations: [
...requests.map(({ operation }) => operation),
...collectResponseConsumers(program, context, requests),
],
boundaryOperations: collectBoundaries(program, context),
};
};
const collectConfigurations = (
program: t.Program,
context: TraversalContext,
): ConfigurationCandidate[] => {
const output: ConfigurationCandidate[] = [];
traverseWithContext(program, context, (node, parent) => {
const details = configurationDetails(node, parent, context);
if (details === null) return;
const operation: JavaScriptSemanticConfigurationOperation = {
configId: `config:${details.kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: details.kind,
location: range(node),
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: outerAssignedBinding(node, context),
key: details.key,
sourceConfigId: null,
value: null,
resolution: details.resolution,
};
output.push({ node, operation });
});
return output;
};
const configurationDetails = (
node: t.Node,
parent: t.Node | null,
context: TraversalContext,
): {
readonly kind: "environment" | "argv" | "file";
readonly key: string | null;
readonly resolution: "complete" | "partial";
} | null => {
if (
(t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) &&
!(memberObject(parent) === node)
) {
const processMember = processConfigurationMember(node, context.state);
if (processMember !== null) return processMember;
}
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
return null;
const fileMethod = builtinMethod(node.callee, context.state, [
"fs",
"node:fs",
]);
return fileMethod === "readFile" || fileMethod === "readFileSync"
? {
kind: "file",
key: literalString(node.arguments[0]),
resolution:
literalString(node.arguments[0]) === null ? "partial" : "complete",
}
: null;
};
const processConfigurationMember = (
node: t.MemberExpression | t.OptionalMemberExpression,
state: JavaScriptSemanticAnalysisState,
): {
readonly kind: "environment" | "argv";
readonly key: string | null;
readonly resolution: "complete" | "partial";
} | null => {
const object = node.object;
if (!t.isMemberExpression(object) && !t.isOptionalMemberExpression(object))
return null;
if (!isProcessObject(object.object, state)) return null;
const family = semanticStaticPropertyName(object.property, object.computed);
if (family !== "env" && family !== "argv") return null;
// `process.env[""]` names an exact (empty) key; only a dynamic key is unknown.
const key = semanticStaticPropertyKey(node.property, node.computed);
return {
kind: family === "env" ? "environment" : "argv",
key,
resolution: key === null ? "partial" : "complete",
};
};
const collectDefaults = (
program: t.Program,
context: TraversalContext,
configurations: readonly ConfigurationCandidate[],
): JavaScriptSemanticConfigurationOperation[] => {
const output: JavaScriptSemanticConfigurationOperation[] = [];
traverseWithContext(program, context, (node) => {
if (
!t.isLogicalExpression(node) ||
(node.operator !== "??" && node.operator !== "||")
)
return;
const sources = configurations.filter(({ node: source }) =>
containsNode(node.left, source),
);
if (sources.length !== 1 || sources[0] === undefined) return;
output.push({
configId: `config:default:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: "default",
location: range(node.right),
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: outerAssignedBinding(node, context),
key: sources[0].operation.key,
sourceConfigId: sources[0].operation.configId,
value: primitiveValue(node.right),
resolution: primitiveValue(node.right) === null ? "partial" : "complete",
});
});
return output;
};
const collectRequests = (
program: t.Program,
context: TraversalContext,
): RequestCandidate[] => {
const output: RequestCandidate[] = [];
traverseWithContext(program, context, (node) => {
if (
!t.isCallExpression(node) &&
!t.isOptionalCallExpression(node) &&
!t.isNewExpression(node)
)
return;
const method = requestMethod(node, context.state);
if (method === null) return;
const endpoint = requestEndpoint(node);
output.push({
node,
operation: {
requestId: `request:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: "request",
method,
location: range(node),
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: outerAssignedBinding(node, context),
projectedResultBindings: semanticProjectedBindingFacts(
assignedSemanticResultBindings(
node,
context.ancestors,
context.state,
).filter(({ projectionPath }) => projectionPath.length > 0),
),
linkedRequestIds: [],
endpoint,
fields: requestFields(node, method, context.state),
resolution: endpoint === null ? "partial" : "complete",
},
});
});
return output;
};
const collectResponseConsumers = (
program: t.Program,
context: TraversalContext,
requests: readonly RequestCandidate[],
): JavaScriptSemanticRequestOperation[] => {
const requestsByBinding = new Map<string, RequestCandidate[]>();
for (const request of requests) {
const bindingIds = [
...(request.operation.resultBindingId === null
? []
: [request.operation.resultBindingId]),
...request.operation.projectedResultBindings.map(
({ bindingId }) => bindingId,
),
];
for (const bindingId of bindingIds) {
const existing = requestsByBinding.get(bindingId) ?? [];
existing.push(request);
requestsByBinding.set(bindingId, existing);
}
}
const output: JavaScriptSemanticRequestOperation[] = [];
traverseWithContext(program, context, (node) => {
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node)) return;
const member = memberCallee(node);
if (member === null || !t.isIdentifier(member.object)) return;
const method = semanticStaticPropertyName(member.property, member.computed);
if (method !== "json" && method !== "text" && method !== "arrayBuffer")
return;
const binding = resolveSemanticBindingState(
context.state,
member.object,
member.object.name,
);
const linked =
binding === undefined
? []
: (requestsByBinding.get(binding.bindingId) ?? []);
if (linked.length === 0) return;
output.push({
requestId: `response:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: "response-consumer",
method,
location: range(node),
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: outerAssignedBinding(node, context),
projectedResultBindings: semanticProjectedBindingFacts(
assignedSemanticResultBindings(
node,
context.ancestors,
context.state,
).filter(({ projectionPath }) => projectionPath.length > 0),
),
linkedRequestIds: linked
.map(({ operation }) => operation.requestId)
.sort(compareCodePoints),
endpoint: null,
fields: [],
resolution:
linked.length === 1 &&
!linked[0]?.operation.projectedResultBindings.some(
({ bindingId }) => bindingId === binding?.bindingId,
)
? "complete"
: "partial",
});
});
return output;
};
const collectBoundaries = (
program: t.Program,
context: TraversalContext,
): JavaScriptSemanticBoundaryOperation[] => {
const output: JavaScriptSemanticBoundaryOperation[] = [];
traverseWithContext(program, context, (node) => {
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node)) return;
const details = boundaryDetails(node, context.state);
if (details === null) return;
output.push({
boundaryId: `boundary:${details.kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: details.kind,
method: details.method,
location: range(node),
ownerCallableId: context.callableStack.at(-1) ?? null,
sourceBindingId: argumentBindingId(node.arguments[0], context.state),
resultBindingId: outerAssignedBinding(node, context),
resolution: details.resolution,
});
});
return output;
};
const boundaryDetails = (
node: t.CallExpression | t.OptionalCallExpression,
state: JavaScriptSemanticAnalysisState,
): {
readonly kind: JavaScriptSemanticBoundaryOperation["kind"];
readonly method: string;
readonly resolution: "complete" | "partial";
} | null => {
if (t.isIdentifier(node.callee)) {
const name = node.callee.name;
const unbound =
resolveSemanticBindingState(state, node.callee, name) === undefined &&
!semanticResolutionBlocked(state, node.callee, name);
if (
unbound &&
["String", "Number", "Boolean", "parseInt", "parseFloat"].includes(name)
)
return { kind: "coerce", method: name, resolution: "complete" };
}
const member = memberCallee(node);
if (member === null) return null;
const method = semanticStaticPropertyName(member.property, member.computed);
if (
method === "parse" &&
t.isIdentifier(member.object, { name: "JSON" }) &&
resolveSemanticBindingState(state, member.object, "JSON") === undefined &&
!semanticResolutionBlocked(state, member.object, "JSON")
)
return { kind: "parse", method: "JSON.parse", resolution: "complete" };
if (method === "parse" || method === "safeParse")
return { kind: "parse", method, resolution: "partial" };
if (method === "validate" || method === "assert" || method === "is")
return { kind: "validate", method, resolution: "partial" };
return null;
};
const requestMethod = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticRequestOperation["method"] | null => {
if (t.isIdentifier(node.callee)) {
const name = node.callee.name;
const unbound =
resolveSemanticBindingState(state, node.callee, name) === undefined &&
!semanticResolutionBlocked(state, node.callee, name);
if (!t.isNewExpression(node) && unbound && name === "fetch") return "fetch";
if (t.isNewExpression(node) && unbound && name === "WebSocket")
return "WebSocket";
}
const member = memberCallee(node);
if (member === null || !t.isIdentifier(member.object)) return null;
const method = semanticStaticPropertyName(member.property, member.computed);
if (method !== "request" && method !== "get") return null;
const binding = resolveSemanticBindingState(
state,
member.object,
member.object.name,
);
return binding?.directOrigins.some(
({ specifier, importedPath }) =>
["http", "https", "node:http", "node:https"].includes(specifier) &&
semanticBuiltinNamespacePath(importedPath),
)
? method
: null;
};
const requestFields = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
method: JavaScriptSemanticRequestOperation["method"],
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticRequestOperation["fields"] => {
const candidate =
method === "fetch" || method === "WebSocket"
? node.arguments[1]
: t.isObjectExpression(node.arguments[0])
? node.arguments[0]
: node.arguments[1];
if (!t.isObjectExpression(candidate)) return [];
return candidate.properties.flatMap((property) => {
if (!t.isObjectProperty(property)) return [];
// `{[key]: 1}` sends no knowable field name; reporting `key` would invent
// a request field that may not exist.
const name = semanticStaticPropertyKey(property.key, property.computed);
if (name === null) return [];
return [
{
name,
sourceBindingId: t.isIdentifier(property.value)
? (resolveSemanticBindingState(
state,
property.value,
property.value.name,
)?.bindingId ?? null)
: null,
},
];
});
};
const requestEndpoint = (
node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,
): string | null =>
t.isObjectExpression(node.arguments[0])
? null
: literalString(node.arguments[0]);
@@ -0,0 +1,99 @@
import type * as t from "@babel/types";
import { collectJavaScriptSemanticAsyncEffects } from "./javascriptSemanticAsyncEffects.js";
import { collectJavaScriptSemanticCalls } from "./javascriptSemanticCalls.js";
import { collectJavaScriptSemanticChildProcesses } from "./javascriptSemanticChildProcesses.js";
import { collectJavaScriptSemanticFingerprints } from "./javascriptSemanticFingerprints.js";
import { collectJavaScriptSemanticDataEffects } from "./javascriptSemanticDataEffects.js";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticIr,
} from "./javascriptSemanticIr.js";
import { collectJavaScriptSemanticPromises } from "./javascriptSemanticPromises.js";
import { collectJavaScriptSemanticObjects } from "./javascriptSemanticObjects.js";
import { collectJavaScriptSemanticResources } from "./javascriptSemanticResources.js";
import type { JavaScriptSemanticAnalysisState } from "./javascriptSemanticState.js";
type DerivedSemanticAnalysis = Pick<
JavaScriptSemanticIr,
| "argumentFlows"
| "callResultFlows"
| "callReturnFlows"
| "callSites"
| "boundaryOperations"
| "childProcessInteractions"
| "childProcessSpawns"
| "closureCaptures"
| "configurationOperations"
| "eventOperations"
| "frontiers"
| "functionFingerprints"
| "objectOperations"
| "promiseOperations"
| "requestOperations"
| "resourceOperations"
| "timerOperations"
>;
/** Compose bounded semantic passes after lexical definitions are available. */
export const collectJavaScriptDerivedSemantics = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
parserPartial: boolean,
): DerivedSemanticAnalysis => {
const calls = collectJavaScriptSemanticCalls(program, state, callables);
const promiseOperations = collectJavaScriptSemanticPromises(
program,
state,
callables,
);
const asyncEffects = collectJavaScriptSemanticAsyncEffects(
program,
state,
callables,
);
const childProcesses = collectJavaScriptSemanticChildProcesses(
program,
state,
callables,
);
const dataEffects = collectJavaScriptSemanticDataEffects(
program,
state,
callables,
);
const resourceOperations = collectJavaScriptSemanticResources(
program,
state,
callables,
);
const objectOperations = collectJavaScriptSemanticObjects(
program,
state,
callables,
);
const functionFingerprints = collectJavaScriptSemanticFingerprints({
state,
callables,
calls,
promises: promiseOperations,
events: asyncEffects.eventOperations,
timers: asyncEffects.timerOperations,
childProcessSpawns: childProcesses.childProcessSpawns,
childProcessInteractions: childProcesses.childProcessInteractions,
requestOperations: dataEffects.requestOperations,
resourceOperations,
parserPartial,
});
return {
...calls,
promiseOperations,
...asyncEffects,
...childProcesses,
...dataEffects,
resourceOperations,
objectOperations,
functionFingerprints,
};
};
@@ -0,0 +1,260 @@
import { createHash } from "node:crypto";
import * as t from "@babel/types";
import { compareCodePoints } from "../canonicalOrdering.js";
import type { JavaScriptSemanticCallAnalysis } from "./javascriptSemanticCalls.js";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticChildProcessInteraction,
JavaScriptSemanticChildProcessSpawn,
JavaScriptSemanticEventOperation,
JavaScriptSemanticFunctionFingerprint,
JavaScriptSemanticPromiseOperation,
JavaScriptSemanticRequestOperation,
JavaScriptSemanticResourceOperation,
JavaScriptSemanticTimerOperation,
} from "./javascriptSemanticIr.js";
import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
import type { JavaScriptSemanticAnalysisState } from "./javascriptSemanticState.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
interface SemanticFingerprintCollectionInput {
readonly state: JavaScriptSemanticAnalysisState;
readonly callables: readonly JavaScriptSemanticCallable[];
readonly calls: JavaScriptSemanticCallAnalysis;
readonly promises: readonly JavaScriptSemanticPromiseOperation[];
readonly events: readonly JavaScriptSemanticEventOperation[];
readonly timers: readonly JavaScriptSemanticTimerOperation[];
readonly childProcessSpawns: readonly JavaScriptSemanticChildProcessSpawn[];
readonly childProcessInteractions: readonly JavaScriptSemanticChildProcessInteraction[];
readonly requestOperations: readonly JavaScriptSemanticRequestOperation[];
readonly resourceOperations: readonly JavaScriptSemanticResourceOperation[];
readonly parserPartial: boolean;
}
/** Build bounded rename- and formatting-resistant components per callable. */
export const collectJavaScriptSemanticFingerprints = (
input: SemanticFingerprintCollectionInput,
): JavaScriptSemanticFunctionFingerprint[] => {
const {
state,
callables,
calls,
promises,
events,
timers,
childProcessSpawns,
childProcessInteractions,
requestOperations,
resourceOperations,
parserPartial,
} = input;
return callables.flatMap((callable) => {
if (callable.kind === "class") return [];
const node = state.callableNodesById.get(callable.callableId);
if (node === undefined) return [];
const syntax = fingerprintSyntax(node, callable.callableId);
const promiseEffects = promises.filter(
({ ownerCallableId }) => ownerCallableId === callable.callableId,
);
const eventEffects = events.filter(
({ ownerCallableId }) => ownerCallableId === callable.callableId,
);
const timerEffects = timers.filter(
({ ownerCallableId }) => ownerCallableId === callable.callableId,
);
const childProcessEffects = [
...childProcessSpawns,
...childProcessInteractions,
].filter(({ ownerCallableId }) => ownerCallableId === callable.callableId);
const networkEffects = requestOperations.filter(
({ ownerCallableId }) => ownerCallableId === callable.callableId,
);
const resourceEffects = resourceOperations.filter(
({ ownerCallableId }) => ownerCallableId === callable.callableId,
);
return [
{
callableId: callable.callableId,
status:
parserPartial || callable.returnCoverage.status !== "complete"
? "partial"
: "complete",
components: {
parameterArity: callableParameterArity(node),
normalizedAstSha256: digest(syntax.normalizedTokens),
controlFlowSha256: digest(syntax.controlFlowTokens),
relationShapeSha256: digest(
relationShape(callable, calls, promiseEffects),
),
literalSetSha256: digest(
[...new Set(syntax.literals)].sort(compareCodePoints),
),
effects: [
...(isAsyncCallable(node) ? (["async"] as const) : []),
...(childProcessEffects.length > 0
? (["child-process"] as const)
: []),
...(eventEffects.length > 0 ? (["event"] as const) : []),
...(networkEffects.length > 0 ? (["network"] as const) : []),
...(promiseEffects.length > 0 ? (["promise"] as const) : []),
...(resourceEffects.length > 0 ? (["resource"] as const) : []),
...(timerEffects.length > 0 ? (["timer"] as const) : []),
],
},
limitations: [
"The fingerprint is a static candidate and does not prove behavioral equivalence.",
...(parserPartial
? ["Incomplete semantic recovery makes this fingerprint partial."]
: []),
],
},
];
});
};
interface FingerprintSyntax {
readonly normalizedTokens: readonly string[];
readonly controlFlowTokens: readonly string[];
readonly literals: readonly string[];
}
const fingerprintSyntax = (
root: t.Node,
targetCallableId: string,
): FingerprintSyntax => {
const normalizedTokens: string[] = [];
const controlFlowTokens: string[] = [];
const literals: string[] = [];
const callableStack: string[] = [];
traverseJavaScriptAst(root, {
enter: (node, parent) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null) callableStack.push(callableId);
if (callableStack.at(-1) !== targetCallableId) return;
normalizedTokens.push(normalizedNodeToken(node, parent));
const control = controlFlowToken(node);
if (control !== null) controlFlowTokens.push(control);
const literal = semanticLiteral(node);
if (literal !== null) literals.push(literal);
},
exit: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableStack.at(-1) === callableId)
callableStack.pop();
},
});
return { normalizedTokens, controlFlowTokens, literals };
};
const normalizedNodeToken = (node: t.Node, parent: t.Node | null): string => {
if (t.isIdentifier(node))
return propertyIdentity(node, parent)
? `property:${node.name}`
: "identifier";
if (t.isStringLiteral(node))
return propertyIdentity(node, parent)
? `property:${node.value}`
: "string-literal";
const attributes = [
primitiveAttribute(node, "operator"),
primitiveAttribute(node, "kind"),
primitiveAttribute(node, "computed"),
primitiveAttribute(node, "optional"),
primitiveAttribute(node, "async"),
primitiveAttribute(node, "generator"),
].filter((value): value is string => value !== null);
return [node.type, ...attributes].join(":");
};
const primitiveAttribute = (node: t.Node, key: string): string | null => {
const value: unknown = Reflect.get(node, key);
return typeof value === "string" ||
typeof value === "number" ||
typeof value === "boolean"
? `${key}=${String(value)}`
: null;
};
const propertyIdentity = (node: t.Node, parent: t.Node | null): boolean => {
if (parent === null) return false;
if (
(t.isMemberExpression(parent) || t.isOptionalMemberExpression(parent)) &&
parent.property === node
)
return !parent.computed || t.isStringLiteral(node);
if (
(t.isObjectProperty(parent) ||
t.isObjectMethod(parent) ||
t.isClassMethod(parent) ||
t.isClassProperty(parent)) &&
parent.key === node
)
return !parent.computed || t.isStringLiteral(node);
return false;
};
const controlFlowToken = (node: t.Node): string | null => {
if (
!t.isIfStatement(node) &&
!t.isConditionalExpression(node) &&
!t.isSwitchStatement(node) &&
!t.isSwitchCase(node) &&
!t.isLoop(node) &&
!t.isTryStatement(node) &&
!t.isCatchClause(node) &&
!t.isReturnStatement(node) &&
!t.isThrowStatement(node) &&
!t.isAwaitExpression(node) &&
!t.isYieldExpression(node) &&
!t.isLogicalExpression(node)
)
return null;
const operator = primitiveAttribute(node, "operator");
return operator === null ? node.type : `${node.type}:${operator}`;
};
const semanticLiteral = (node: t.Node): string | null => {
if (t.isStringLiteral(node)) return `string:${node.value}`;
if (t.isNumericLiteral(node)) return `number:${String(node.value)}`;
if (t.isBooleanLiteral(node)) return `boolean:${String(node.value)}`;
if (t.isNullLiteral(node)) return "null";
if (t.isBigIntLiteral(node)) return `bigint:${node.value}`;
if (t.isRegExpLiteral(node)) return `regexp:${node.pattern}/${node.flags}`;
if (t.isTemplateElement(node))
return `template:${node.value.cooked ?? node.value.raw}`;
return null;
};
const relationShape = (
callable: JavaScriptSemanticCallable,
calls: JavaScriptSemanticCallAnalysis,
promises: readonly JavaScriptSemanticPromiseOperation[],
): string[] => [
`returns:${String(callable.returnSites.length)}:${callable.returnCoverage.status}`,
...calls.callSites
.filter(({ callerCallableId }) => callerCallableId === callable.callableId)
.map(
({ kind, resolution, arguments: args, calleeCallableIds }) =>
`call:${kind}:${resolution}:${String(args.length)}:${String(calleeCallableIds.length)}`,
),
`captures:${String(
calls.closureCaptures.filter(
({ callableId }) => callableId === callable.callableId,
).length,
)}`,
...promises.map(
({ kind, method, ownership, sourceResolution }) =>
`promise:${kind}:${method}:${ownership}:${sourceResolution}`,
),
];
const callableParameterArity = (node: t.Node): number =>
t.isFunction(node) ? node.params.length : 0;
const isAsyncCallable = (node: t.Node): boolean =>
t.isFunction(node) && node.async;
const digest = (value: readonly string[]): string =>
createHash("sha256").update(JSON.stringify(value)).digest("hex");
@@ -0,0 +1,532 @@
import { z } from "zod";
import { canonicalDigest, canonicalJson } from "../comparisonSemantics.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
import {
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
javaScriptSemanticFingerprintInputSchema,
javaScriptSemanticFingerprintSchema,
javaScriptSemanticGraphInputSchema,
javaScriptSemanticGraphRecordSchema,
javaScriptSemanticNodeInputSchema,
javaScriptSemanticNodeSchema,
javaScriptSemanticRelationInputSchema,
javaScriptSemanticRelationSchema,
javaScriptSemanticUnknownInputSchema,
javaScriptSemanticUnknownSchema,
type JavaScriptSemanticGraphInput,
type JavaScriptSemanticGraphNode,
type JavaScriptSemanticGraphRelation,
} from "./javascriptSemanticGraphSchemas.js";
const normalizeEvidence = (
evidence: ApplicationGraphEvidence,
): ApplicationGraphEvidence => ({
...evidence,
coverage: {
...evidence.coverage,
limits: [...evidence.coverage.limits].sort((left, right) =>
compareCodePoints(
canonicalJson(left, "JavaScript semantic graph"),
canonicalJson(right, "JavaScript semantic graph"),
),
),
},
limitations: uniqueSorted(evidence.limitations),
evidence_ids: uniqueSorted(evidence.evidence_ids),
});
const nodeId = (
node: Pick<JavaScriptSemanticGraphNode, "kind" | "identity">,
): string =>
`jsrg_node_${canonicalDigest({ kind: node.kind, identity: node.identity }, "JavaScript semantic graph")}`;
/** Normalize one semantic entity and derive its artifact-version identifier. */
export const createJavaScriptSemanticGraphNode = (
input: unknown,
): JavaScriptSemanticGraphNode => {
const parsed = javaScriptSemanticNodeInputSchema.parse(input);
const semantic = {
...parsed,
application_node_ids: uniqueSorted(parsed.application_node_ids),
evidence: normalizeEvidence(parsed.evidence),
identifier_strategy: {
strategy: "semantic-content-sha256" as const,
stability: "artifact-version" as const,
},
};
return javaScriptSemanticNodeSchema.parse({
...semantic,
node_id: nodeId(semantic),
});
};
/** Normalize one semantic relationship and derive its exact identifier. */
export const createJavaScriptSemanticGraphRelation = (
input: unknown,
): JavaScriptSemanticGraphRelation => {
const parsed = javaScriptSemanticRelationInputSchema.parse(input);
const semantic = {
...parsed,
evidence: normalizeEvidence(parsed.evidence),
identifier_strategy: {
strategy: "semantic-content-sha256" as const,
stability: "relationship-exact" as const,
},
};
return javaScriptSemanticRelationSchema.parse({
...semantic,
relation_id: `jsrg_relation_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
});
};
/** Normalize one unresolved semantic frontier and derive its identifier. */
export const createJavaScriptSemanticGraphUnknown = (input: unknown) => {
const parsed = javaScriptSemanticUnknownInputSchema.parse(input);
const semantic = {
...parsed,
relation_kinds: uniqueSorted(parsed.relation_kinds),
candidate_node_ids: uniqueSorted(parsed.candidate_node_ids),
evidence: normalizeEvidence(parsed.evidence),
};
return javaScriptSemanticUnknownSchema.parse({
...semantic,
unknown_id: `jsrg_unknown_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
});
};
/** Normalize one function fingerprint and derive its component commitment. */
export const createJavaScriptSemanticFingerprint = (input: unknown) => {
const parsed = javaScriptSemanticFingerprintInputSchema.parse(input);
const semantic = {
...parsed,
components: {
...parsed.components,
effects: uniqueSorted(parsed.components.effects),
},
limitations: uniqueSorted(parsed.limitations),
evidence: normalizeEvidence(parsed.evidence),
};
const fingerprintSha256 = canonicalDigest(
semantic.components,
"JavaScript semantic graph",
);
return javaScriptSemanticFingerprintSchema.parse({
...semantic,
fingerprint_sha256: fingerprintSha256,
fingerprint_id: `jsrg_fingerprint_${canonicalDigest(
{
function_node_id: semantic.function_node_id,
algorithm: semantic.algorithm,
fingerprint_sha256: fingerprintSha256,
},
"JavaScript semantic graph",
)}`,
});
};
type GraphRecord = z.infer<typeof javaScriptSemanticGraphRecordSchema>;
const sortedUniqueIssue = (
values: readonly string[],
path: PropertyKey[],
label: string,
context: z.RefinementCtx,
): void => {
for (let index = 1; index < values.length; index += 1) {
if (compareCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
continue;
context.addIssue({
code: "custom",
path: [...path, index],
message: `${label} must be sorted and unique`,
});
return;
}
};
const checkCoverage = (graph: GraphRecord, context: z.RefinementCtx): void => {
const families = graph.coverage.families.map(({ family }) => family);
if (
canonicalJson(families, "JavaScript semantic graph") !==
canonicalJson(
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
"JavaScript semantic graph",
)
)
context.addIssue({
code: "custom",
path: ["coverage", "families"],
message:
"Coverage must name every semantic relation family once in canonical order",
});
if (
graph.coverage.status === "complete" &&
(graph.coverage.truncated ||
graph.coverage.omitted_nodes !== 0 ||
graph.coverage.omitted_relations !== 0 ||
graph.coverage.families.some(({ status }) => status !== "complete"))
)
context.addIssue({
code: "custom",
path: ["coverage"],
message: "Complete graph coverage cannot omit or truncate semantic facts",
});
if (graph.coverage.truncated && graph.coverage.limits.length === 0)
context.addIssue({
code: "custom",
path: ["coverage", "limits"],
message: "Truncated graph coverage must identify an effective limit",
});
const relationsByFamily = new Map(
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => [family, 0]),
);
for (const relation of graph.relations) {
const family = JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation];
relationsByFamily.set(family, (relationsByFamily.get(family) ?? 0) + 1);
}
const unknownsById = new Map(
graph.unknowns.map((unknown) => [unknown.unknown_id, unknown]),
);
for (const [index, family] of graph.coverage.families.entries()) {
if (family.retained_relations !== relationsByFamily.get(family.family))
context.addIssue({
code: "custom",
path: ["coverage", "families", index, "retained_relations"],
message: "Family retained relation count does not match graph content",
});
if (
family.unknown_ids.some(
(identifier) => unknownsById.get(identifier)?.family !== family.family,
)
)
context.addIssue({
code: "custom",
path: ["coverage", "families", index, "unknown_ids"],
message: "Family coverage references an unknown from another family",
});
if (
family.status === "complete" &&
(family.omitted_relations !== 0 || family.unknown_ids.length > 0)
)
context.addIssue({
code: "custom",
path: ["coverage", "families", index],
message: "Complete family coverage cannot omit or retain unknown facts",
});
}
};
const checkCanonicalOrder = (
graph: GraphRecord,
context: z.RefinementCtx,
): void => {
sortedUniqueIssue(
graph.root_node_ids,
["root_node_ids"],
"Root nodes",
context,
);
sortedUniqueIssue(
graph.nodes.map(({ node_id }) => node_id),
["nodes"],
"Nodes",
context,
);
sortedUniqueIssue(
graph.relations.map(({ relation_id }) => relation_id),
["relations"],
"Relations",
context,
);
sortedUniqueIssue(
graph.fingerprints.map(({ fingerprint_id }) => fingerprint_id),
["fingerprints"],
"Fingerprints",
context,
);
sortedUniqueIssue(
graph.unknowns.map(({ unknown_id }) => unknown_id),
["unknowns"],
"Unknown frontiers",
context,
);
sortedUniqueIssue(graph.limitations, ["limitations"], "Limitations", context);
};
const checkNodes = (
graph: GraphRecord,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
context: z.RefinementCtx,
): void => {
for (const [index, node] of graph.nodes.entries()) {
if (node.node_id !== nodeId(node))
context.addIssue({
code: "custom",
path: ["nodes", index, "node_id"],
message: "Node identifier is stale",
});
if (
node.function_node_id !== null &&
nodes.get(node.function_node_id)?.kind !== "function"
)
context.addIssue({
code: "custom",
path: ["nodes", index, "function_node_id"],
message: "Function owner must name a function node",
});
}
};
const checkRoots = (
graph: GraphRecord,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
context: z.RefinementCtx,
): void => {
for (const root of graph.root_node_ids)
if (!nodes.has(root))
context.addIssue({
code: "custom",
path: ["root_node_ids"],
message: "Root identifier must name a semantic node",
});
};
const checkRelations = (
graph: GraphRecord,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
context: z.RefinementCtx,
): void => {
for (const [index, relation] of graph.relations.entries()) {
const { relation_id: identifier, ...semantic } = relation;
if (
identifier !==
"jsrg_relation_" + canonicalDigest(semantic, "JavaScript semantic graph")
)
context.addIssue({
code: "custom",
path: ["relations", index, "relation_id"],
message: "Relation identifier is stale",
});
if (
!nodes.has(relation.source_node_id) ||
!nodes.has(relation.target_node_id)
)
context.addIssue({
code: "custom",
path: ["relations", index],
message: "Relation endpoints must name semantic nodes",
});
if (relation.source_node_id === relation.target_node_id)
context.addIssue({
code: "custom",
path: ["relations", index],
message: "Semantic relations cannot be self-referential",
});
if (
relation.resolution === "candidate" &&
relation.evidence.state === "observed"
)
context.addIssue({
code: "custom",
path: ["relations", index, "evidence", "state"],
message: "Candidate relations cannot claim observed resolution",
});
}
};
const checkUnknowns = (
graph: GraphRecord,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
context: z.RefinementCtx,
): void => {
for (const [index, unknown] of graph.unknowns.entries()) {
const { unknown_id: identifier, ...semantic } = unknown;
if (
identifier !==
"jsrg_unknown_" + canonicalDigest(semantic, "JavaScript semantic graph")
)
context.addIssue({
code: "custom",
path: ["unknowns", index, "unknown_id"],
message: "Unknown frontier identifier is stale",
});
if (unknown.node_id !== null && !nodes.has(unknown.node_id))
context.addIssue({
code: "custom",
path: ["unknowns", index, "node_id"],
message: "Unknown frontier node is absent",
});
if (unknown.candidate_node_ids.some((nodeId) => !nodes.has(nodeId)))
context.addIssue({
code: "custom",
path: ["unknowns", index, "candidate_node_ids"],
message: "Unknown frontier candidate node is absent",
});
if (
unknown.relation_kinds.some(
(kind) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[kind] !== unknown.family,
)
)
context.addIssue({
code: "custom",
path: ["unknowns", index, "relation_kinds"],
message: "Unknown relation kinds must belong to their declared family",
});
if (!["unknown", "unavailable"].includes(unknown.evidence.state))
context.addIssue({
code: "custom",
path: ["unknowns", index, "evidence", "state"],
message: "Unknown frontiers require unknown or unavailable evidence",
});
}
};
const checkUnknownReferences = (
graph: GraphRecord,
context: z.RefinementCtx,
): void => {
const unknownIds = new Set(
graph.unknowns.map(({ unknown_id }) => unknown_id),
);
for (const [index, family] of graph.coverage.families.entries())
if (family.unknown_ids.some((identifier) => !unknownIds.has(identifier)))
context.addIssue({
code: "custom",
path: ["coverage", "families", index, "unknown_ids"],
message: "Family coverage references an absent unknown frontier",
});
};
const checkFingerprints = (
graph: GraphRecord,
nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
context: z.RefinementCtx,
): void => {
for (const [index, fingerprint] of graph.fingerprints.entries()) {
if (nodes.get(fingerprint.function_node_id)?.kind !== "function")
context.addIssue({
code: "custom",
path: ["fingerprints", index, "function_node_id"],
message: "Fingerprint must name a function node",
});
if (
fingerprint.fingerprint_sha256 !==
canonicalDigest(fingerprint.components, "JavaScript semantic graph")
)
context.addIssue({
code: "custom",
path: ["fingerprints", index, "fingerprint_sha256"],
message: "Fingerprint component commitment is stale",
});
const expectedIdentifier =
"jsrg_fingerprint_" +
canonicalDigest(
{
function_node_id: fingerprint.function_node_id,
algorithm: fingerprint.algorithm,
fingerprint_sha256: fingerprint.fingerprint_sha256,
},
"JavaScript semantic graph",
);
if (fingerprint.fingerprint_id !== expectedIdentifier)
context.addIssue({
code: "custom",
path: ["fingerprints", index, "fingerprint_id"],
message: "Fingerprint identifier is stale",
});
if (
fingerprint.status !== "complete" &&
fingerprint.limitations.length === 0
)
context.addIssue({
code: "custom",
path: ["fingerprints", index, "limitations"],
message: "Incomplete fingerprints require a limitation",
});
}
};
const checkGraph = (graph: GraphRecord, context: z.RefinementCtx): void => {
checkCanonicalOrder(graph, context);
const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
checkNodes(graph, nodes, context);
checkRoots(graph, nodes, context);
checkRelations(graph, nodes, context);
checkUnknowns(graph, nodes, context);
checkUnknownReferences(graph, context);
checkFingerprints(graph, nodes, context);
checkCoverage(graph, context);
if (graph.coverage.status !== "complete" && graph.limitations.length === 0)
context.addIssue({
code: "custom",
path: ["limitations"],
message: "Non-complete graph coverage requires a limitation",
});
const { graph_id: identifier, ...semantic } = graph;
if (
identifier !==
"jsrg_" + canonicalDigest(semantic, "JavaScript semantic graph")
)
context.addIssue({
code: "custom",
path: ["graph_id"],
message: "Graph identifier is stale",
});
};
/** Strict semantic graph schema with verified canonical commitments. */
export const javaScriptSemanticGraphSchema =
javaScriptSemanticGraphRecordSchema.superRefine(checkGraph);
/** Fully validated JavaScript Semantic Relation Graph. */
export type JavaScriptSemanticGraph = z.infer<
typeof javaScriptSemanticGraphSchema
>;
/** Normalize a complete companion graph and derive its graph ID. */
export const createJavaScriptSemanticGraph = (
input: unknown,
): JavaScriptSemanticGraph => {
const parsed = javaScriptSemanticGraphInputSchema.parse(input);
const semantic: JavaScriptSemanticGraphInput = {
...parsed,
root_node_ids: uniqueSorted(parsed.root_node_ids),
nodes: [...parsed.nodes].sort((left, right) =>
compareCodePoints(left.node_id, right.node_id),
),
relations: [...parsed.relations].sort((left, right) =>
compareCodePoints(left.relation_id, right.relation_id),
),
fingerprints: [...parsed.fingerprints].sort((left, right) =>
compareCodePoints(left.fingerprint_id, right.fingerprint_id),
),
unknowns: [...parsed.unknowns].sort((left, right) =>
compareCodePoints(left.unknown_id, right.unknown_id),
),
coverage: {
...parsed.coverage,
limits: [...parsed.coverage.limits].sort((left, right) =>
compareCodePoints(
canonicalJson(left, "JavaScript semantic graph"),
canonicalJson(right, "JavaScript semantic graph"),
),
),
families: [...parsed.coverage.families]
.map((family) => ({
...family,
unknown_ids: uniqueSorted(family.unknown_ids),
}))
.sort((left, right) => compareCodePoints(left.family, right.family)),
},
limitations: uniqueSorted(parsed.limitations),
};
return javaScriptSemanticGraphSchema.parse({
...semantic,
graph_id: `jsrg_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
});
};
export type { JavaScriptSemanticGraphNode, JavaScriptSemanticGraphRelation };
@@ -0,0 +1,287 @@
import { expect, it } from "vitest";
import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
import {
JAVASCRIPT_SEMANTIC_NODE_KINDS,
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
JAVASCRIPT_SEMANTIC_RELATIONS,
} from "./javascriptSemanticGraphSchemas.js";
import {
createJavaScriptSemanticFingerprint,
createJavaScriptSemanticGraph,
createJavaScriptSemanticGraphNode,
createJavaScriptSemanticGraphRelation,
createJavaScriptSemanticGraphUnknown,
type JavaScriptSemanticGraph,
type JavaScriptSemanticGraphNode,
} from "./javascriptSemanticGraph.js";
import {
parseJavaScriptSemanticGraph,
serializeJavaScriptSemanticGraph,
} from "./javascriptSemanticGraphSerialization.js";
const SHA = "a".repeat(64);
const JAG_ID = `jag_${"b".repeat(64)}`;
const completeCoverage = {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
} satisfies ApplicationGraphEvidence["coverage"];
const evidence = (
state: "observed" | "inferred" = "observed",
): ApplicationGraphEvidence => ({
authority:
state === "observed"
? "ast-static-analysis"
: "static-relationship-inference",
state,
confidence: state === "observed" ? "exact" : "high",
artifact: { available: true, artifact_id: `art_${SHA}`, sha256: SHA },
location: {
available: true,
value: {
kind: "source-range",
source: "bundle.js",
start: { line: 1, column: 0 },
end: { line: 1, column: 10 },
},
},
extractor: {
name: "test",
version: "1",
operation: "recover-semantic-relation",
executable_sha256: null,
},
coverage: completeCoverage,
limitations:
state === "observed"
? []
: ["Static reachability does not prove runtime execution."],
evidence_ids: [],
});
const unknownEvidence = (): ApplicationGraphEvidence => ({
authority: "unknown",
state: "unknown",
confidence: "unknown",
artifact: {
available: false,
reason: "unknown",
detail: "Unknown artifact.",
},
location: {
available: false,
reason: "unresolved",
detail: "Dynamic call target.",
},
extractor: {
name: "test",
version: "1",
operation: "retain-dynamic-call",
executable_sha256: null,
},
coverage: {
status: "unknown",
truncated: false,
omitted_count: null,
limits: [],
},
limitations: ["Dynamic call target remains unknown."],
evidence_ids: [],
});
const node = (
kind: (typeof JAVASCRIPT_SEMANTIC_NODE_KINDS)[number],
role: string,
properties: Record<string, string | number | boolean | null> = {},
options: {
readonly functionNodeId?: string | null;
readonly modulePath?: string;
} = {},
): JavaScriptSemanticGraphNode =>
createJavaScriptSemanticGraphNode({
kind,
identity: {
artifact_sha256: SHA,
module_path: options.modulePath ?? "bundle.js",
source_range: {
start: { line: 1, column: role.length },
end: { line: 1, column: role.length + 1 },
},
role_key: role,
},
function_node_id: options.functionNodeId ?? null,
application_node_ids: [],
label: role,
properties,
evidence: evidence(),
});
it("accepts semantic module paths longer than the former schema ceiling", () => {
const modulePath = `${"segment/".repeat(600)}entry.js`;
expect(
node("module", "long-path", {}, { modulePath }).identity.module_path,
).toBe(modulePath);
});
const fixtureGraph = (withUnknown = false): JavaScriptSemanticGraph => {
const module = node("module", "module");
const literal = node("literal", "literal", { value: "TOKEN" });
const binding = node("binding", "binding");
const callable = node("function", "function");
const request = node("request", "request", {
endpoint: "https://example.invalid/v1",
});
const relations = [
createJavaScriptSemanticGraphRelation({
source_node_id: literal.node_id,
target_node_id: binding.node_id,
relation: "defines",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
createJavaScriptSemanticGraphRelation({
source_node_id: binding.node_id,
target_node_id: callable.node_id,
relation: "captures",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
createJavaScriptSemanticGraphRelation({
source_node_id: callable.node_id,
target_node_id: request.node_id,
relation: "constructs-request",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
];
const dynamic = createJavaScriptSemanticGraphUnknown({
node_id: callable.node_id,
family: "call-flow",
relation_kinds: ["calls"],
reason: "dynamic-call",
detail: "Computed callee is unresolved.",
candidate_node_ids: [],
evidence: unknownEvidence(),
});
const unknowns = withUnknown ? [dynamic] : [];
const coverageFamilies = JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map(
(family) => ({
family,
status:
withUnknown && family === "call-flow"
? ("unknown" as const)
: ("complete" as const),
retained_relations: relations.filter(({ relation }) =>
relation === "defines"
? family === "data-flow"
: relation === "captures"
? family === "closure"
: family === "request",
).length,
omitted_relations: withUnknown && family === "call-flow" ? null : 0,
unknown_ids:
withUnknown && family === "call-flow" ? [dynamic.unknown_id] : [],
}),
);
const fingerprint = createJavaScriptSemanticFingerprint({
function_node_id: callable.node_id,
algorithm: "rea.javascript-semantic-function",
status: "complete",
components: {
parameter_arity: 0,
normalized_ast_sha256: "1".repeat(64),
control_flow_sha256: "2".repeat(64),
relation_shape_sha256: "3".repeat(64),
literal_set_sha256: "4".repeat(64),
effects: ["network"],
},
limitations: [],
evidence: evidence("inferred"),
});
return createJavaScriptSemanticGraph({
schema: "JavaScriptSemanticRelationGraph",
root_artifact_sha256: SHA,
application_graph_id: JAG_ID,
root_node_ids: [module.node_id],
nodes: [request, callable, binding, literal, module],
relations,
fingerprints: [fingerprint],
unknowns,
coverage: {
status: withUnknown ? "partial" : "complete",
truncated: false,
omitted_nodes: withUnknown ? null : 0,
omitted_relations: withUnknown ? null : 0,
limits: [],
families: coverageFamilies,
},
limitations: withUnknown ? ["Dynamic call target remains unknown."] : [],
});
};
it("defines every required relation family and canonicalizes records", () => {
expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("argument-to-parameter");
expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("detaches-task");
expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("forwards-signal");
expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("validates");
const graph = fixtureGraph();
expect(
parseJavaScriptSemanticGraph(
JSON.parse(serializeJavaScriptSemanticGraph(graph)),
),
).toEqual(graph);
expect(graph.nodes.map(({ node_id }) => node_id)).toEqual(
graph.nodes.map(({ node_id }) => node_id).toSorted(),
);
});
it("rejects stale identities, dangling endpoints, and incomplete coverage claims", () => {
const graph = fixtureGraph();
const { graph_id: _graphId, ...graphInput } = graph;
expect(() =>
parseJavaScriptSemanticGraph({
...graph,
graph_id: `jsrg_${"0".repeat(64)}`,
}),
).toThrow();
expect(() =>
createJavaScriptSemanticGraph({
...graphInput,
relations: [
{
...graph.relations[0],
target_node_id: `jsrg_node_${"f".repeat(64)}`,
},
],
}),
).toThrow();
expect(() =>
createJavaScriptSemanticGraph({
...graphInput,
coverage: { ...graph.coverage, omitted_nodes: 1 },
}),
).toThrow(/Complete graph coverage/u);
const graphWithUnknown = fixtureGraph(true);
const { graph_id: _unknownGraphId, ...unknownGraphInput } = graphWithUnknown;
const originalUnknown = graphWithUnknown.unknowns[0];
if (originalUnknown === undefined)
throw new Error("Expected unknown frontier");
const { unknown_id: _unknownId, ...unknownInput } = originalUnknown;
expect(() =>
createJavaScriptSemanticGraph({
...unknownGraphInput,
unknowns: [
createJavaScriptSemanticGraphUnknown({
...unknownInput,
candidate_node_ids: [`jsrg_node_${"f".repeat(64)}`],
}),
],
}),
).toThrow(/candidate node is absent/u);
});
@@ -0,0 +1,367 @@
import { z } from "zod";
import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
import { jsonValueSchema } from "../jsonValue.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const boundedTextSchema = z.string().min(1);
const semanticNodeIdSchema = prefixedDigestSchema("jsrg_node");
const semanticRelationIdSchema = z
.string()
.regex(/^jsrg_relation_[a-f0-9]{64}$/u);
const semanticUnknownIdSchema = z
.string()
.regex(/^jsrg_unknown_[a-f0-9]{64}$/u);
/** Semantic entity kinds admitted by JavaScript Semantic Relation Graph. */
export const JAVASCRIPT_SEMANTIC_NODE_KINDS = [
"module",
"function",
"parameter",
"binding",
"expression",
"literal",
"property-slot",
"call-site",
"return-site",
"closure-capture",
"promise",
"task",
"event",
"listener",
"timer",
"child-process",
"stdio",
"signal",
"config-source",
"request",
"response",
"boundary",
"resource",
"unknown-frontier",
] as const;
/** Required semantic-analysis coverage families. */
export const JAVASCRIPT_SEMANTIC_RELATION_FAMILIES = [
"boundary",
"call-flow",
"child-process",
"closure",
"configuration",
"data-flow",
"event",
"object-flow",
"promise-ownership",
"request",
"resource-lifecycle",
"timer",
] as const;
/** Directed semantic relations admitted by the graph. */
export const JAVASCRIPT_SEMANTIC_RELATIONS = [
"acquires",
"aggregates",
"aliases",
"argument-to-parameter",
"awaits",
"calls",
"cancels-timer",
"captures",
"chains",
"coerces",
"connects-stdio",
"consumed-by",
"constructs-request",
"creates-promise",
"defaults",
"defines",
"destructures",
"detaches-task",
"dispatches-candidate",
"forwards-signal",
"listens-error",
"listens-exit",
"owns",
"overrides",
"parses",
"reads",
"reads-argv",
"reads-config",
"reads-environment",
"reads-property",
"registers-listener",
"releases",
"removes-listener",
"returns-task",
"returns-to-call",
"schedules-timer",
"spawns",
"spreads",
"supplies-argv",
"supplies-env",
"supplies-request-field",
"validates",
"writes",
"writes-property",
] as const;
/** Map each semantic relation to its coverage family. */
export const JAVASCRIPT_SEMANTIC_RELATION_FAMILY = {
acquires: "resource-lifecycle",
aggregates: "promise-ownership",
aliases: "data-flow",
"argument-to-parameter": "call-flow",
awaits: "promise-ownership",
calls: "call-flow",
"cancels-timer": "timer",
captures: "closure",
chains: "promise-ownership",
coerces: "boundary",
"connects-stdio": "child-process",
"consumed-by": "request",
"constructs-request": "request",
"creates-promise": "promise-ownership",
defaults: "configuration",
defines: "data-flow",
destructures: "object-flow",
"detaches-task": "promise-ownership",
"dispatches-candidate": "event",
"forwards-signal": "child-process",
"listens-error": "child-process",
"listens-exit": "child-process",
owns: "promise-ownership",
overrides: "configuration",
parses: "boundary",
reads: "data-flow",
"reads-argv": "configuration",
"reads-config": "configuration",
"reads-environment": "configuration",
"reads-property": "object-flow",
"registers-listener": "event",
releases: "resource-lifecycle",
"removes-listener": "event",
"returns-task": "promise-ownership",
"returns-to-call": "call-flow",
"schedules-timer": "timer",
spawns: "child-process",
spreads: "object-flow",
"supplies-argv": "child-process",
"supplies-env": "child-process",
"supplies-request-field": "request",
validates: "boundary",
writes: "data-flow",
"writes-property": "object-flow",
} as const satisfies Readonly<
Record<
(typeof JAVASCRIPT_SEMANTIC_RELATIONS)[number],
(typeof JAVASCRIPT_SEMANTIC_RELATION_FAMILIES)[number]
>
>;
const relativePathSchema = z
.string()
.min(1)
.refine(
(path) =>
!path.startsWith("/") &&
!path.includes("\\") &&
path.split("/").every((part) => !["", ".", ".."].includes(part)),
"Expected a normalized relative POSIX path without traversal",
);
const sourcePointSchema = z.strictObject({
line: z.number().int().min(1),
column: z.number().int().min(0),
});
const sourceRangeSchema = z
.strictObject({ start: sourcePointSchema, end: sourcePointSchema })
.superRefine((range, context) => {
if (
range.end.line < range.start.line ||
(range.end.line === range.start.line &&
range.end.column < range.start.column)
)
context.addIssue({
code: "custom",
path: ["end"],
message: "Source range end must not precede its start",
});
});
const semanticPropertiesSchema = z.record(z.string().min(1), jsonValueSchema);
const semanticNodeIdentitySchema = z.strictObject({
artifact_sha256: digestSchema,
module_path: relativePathSchema,
source_range: sourceRangeSchema.nullable(),
role_key: z.string().min(1),
});
/** One semantic entity before its canonical identifier is derived. */
export const javaScriptSemanticNodeInputSchema = z.strictObject({
kind: z.enum(JAVASCRIPT_SEMANTIC_NODE_KINDS),
identity: semanticNodeIdentitySchema,
function_node_id: semanticNodeIdSchema.nullable(),
application_node_ids: z.array(prefixedDigestSchema("jag_node")),
label: z.string().min(1).nullable(),
properties: semanticPropertiesSchema,
evidence: applicationGraphEvidenceSchema,
});
/** One exact, artifact-version semantic entity. */
export const javaScriptSemanticNodeSchema =
javaScriptSemanticNodeInputSchema.extend({
node_id: semanticNodeIdSchema,
identifier_strategy: z.strictObject({
strategy: z.literal("semantic-content-sha256"),
stability: z.literal("artifact-version"),
}),
});
/** One directed semantic relationship before its ID is derived. */
export const javaScriptSemanticRelationInputSchema = z.strictObject({
source_node_id: semanticNodeIdSchema,
target_node_id: semanticNodeIdSchema,
relation: z.enum(JAVASCRIPT_SEMANTIC_RELATIONS),
resolution: z.enum(["resolved", "candidate"]),
properties: semanticPropertiesSchema,
evidence: applicationGraphEvidenceSchema,
});
/** One canonical directed semantic relationship. */
export const javaScriptSemanticRelationSchema =
javaScriptSemanticRelationInputSchema.extend({
relation_id: semanticRelationIdSchema,
identifier_strategy: z.strictObject({
strategy: z.literal("semantic-content-sha256"),
stability: z.literal("relationship-exact"),
}),
});
/** Reasons semantic analysis can leave an explicit frontier. */
export const JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS = [
"ambiguous-target",
"bound-reached",
"dynamic-call",
"dynamic-property",
"dynamic-scope",
"eval-or-generated-code",
"incomplete-module",
"missing-source",
"unsupported-syntax",
] as const;
/** One unresolved semantic frontier before its ID is derived. */
export const javaScriptSemanticUnknownInputSchema = z.strictObject({
node_id: semanticNodeIdSchema.nullable(),
family: z.enum(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES),
relation_kinds: z.array(z.enum(JAVASCRIPT_SEMANTIC_RELATIONS)).min(1),
reason: z.enum(JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS),
detail: boundedTextSchema,
candidate_node_ids: z.array(semanticNodeIdSchema),
evidence: applicationGraphEvidenceSchema,
});
/** One canonical unresolved semantic frontier. */
export const javaScriptSemanticUnknownSchema =
javaScriptSemanticUnknownInputSchema.extend({
unknown_id: semanticUnknownIdSchema,
});
const fingerprintComponentsSchema = z.strictObject({
parameter_arity: z.number().int().min(0),
normalized_ast_sha256: digestSchema,
control_flow_sha256: digestSchema,
relation_shape_sha256: digestSchema,
literal_set_sha256: digestSchema,
effects: z.array(
z.enum([
"async",
"child-process",
"event",
"network",
"promise",
"resource",
"timer",
]),
),
});
/** One bounded rename-resistant function fingerprint. */
export const javaScriptSemanticFingerprintInputSchema = z.strictObject({
function_node_id: semanticNodeIdSchema,
algorithm: z.literal("rea.javascript-semantic-function"),
status: z.enum(["complete", "partial", "unavailable"]),
components: fingerprintComponentsSchema,
limitations: z.array(boundedTextSchema),
evidence: applicationGraphEvidenceSchema,
});
/** One canonical function fingerprint record. */
export const javaScriptSemanticFingerprintSchema =
javaScriptSemanticFingerprintInputSchema.extend({
fingerprint_id: prefixedDigestSchema("jsrg_fingerprint"),
fingerprint_sha256: digestSchema,
});
const familyCoverageSchema = z.strictObject({
family: z.enum(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES),
status: z.enum(["complete", "partial", "unknown", "unsupported"]),
retained_relations: z.number().int().min(0),
omitted_relations: z.number().int().min(0).nullable(),
unknown_ids: z.array(semanticUnknownIdSchema),
});
const graphCoverageSchema = z.strictObject({
status: z.enum(["complete", "partial", "unknown", "unavailable"]),
truncated: z.boolean(),
omitted_nodes: z.number().int().min(0).nullable(),
omitted_relations: z.number().int().min(0).nullable(),
limits: z.array(
z.strictObject({
name: z.string().min(1),
value: z.number().int().min(0),
unit: z.enum(["items", "bytes", "milliseconds", "depth", "other"]),
}),
),
families: z.array(familyCoverageSchema).length(12),
});
/** Graph content before its top-level commitment is derived. */
export const javaScriptSemanticGraphInputSchema = z.strictObject({
schema: z.literal("JavaScriptSemanticRelationGraph"),
root_artifact_sha256: digestSchema,
application_graph_id: prefixedDigestSchema("jag"),
root_node_ids: z.array(semanticNodeIdSchema).min(1),
nodes: z.array(javaScriptSemanticNodeSchema).min(1),
relations: z.array(javaScriptSemanticRelationSchema),
fingerprints: z.array(javaScriptSemanticFingerprintSchema),
unknowns: z.array(javaScriptSemanticUnknownSchema),
coverage: graphCoverageSchema,
limitations: z.array(boundedTextSchema),
});
/** Stored JavaScript Semantic Relation Graph. */
export const javaScriptSemanticGraphRecordSchema =
javaScriptSemanticGraphInputSchema.extend({
graph_id: prefixedDigestSchema("jsrg"),
});
/** Canonical semantic node. */
export type JavaScriptSemanticGraphNode = z.infer<
typeof javaScriptSemanticNodeSchema
>;
/** Canonical semantic relation. */
export type JavaScriptSemanticGraphRelation = z.infer<
typeof javaScriptSemanticRelationSchema
>;
/** Canonical unresolved semantic frontier. */
export type JavaScriptSemanticGraphUnknown = z.infer<
typeof javaScriptSemanticUnknownSchema
>;
/** Canonical graph content before graph ID derivation. */
export type JavaScriptSemanticGraphInput = z.infer<
typeof javaScriptSemanticGraphInputSchema
>;
@@ -0,0 +1,23 @@
import canonicalize from "canonicalize";
import {
javaScriptSemanticGraphSchema,
type JavaScriptSemanticGraph,
} from "./javascriptSemanticGraph.js";
const canonicalJson = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError(
"JavaScript semantic graph could not canonicalize data",
);
return encoded;
};
/** Parse a stored semantic graph and reject stale IDs. */
export const parseJavaScriptSemanticGraph = (
input: unknown,
): JavaScriptSemanticGraph => javaScriptSemanticGraphSchema.parse(input);
/** Serialize a verified semantic graph as canonical JSON. */
export const serializeJavaScriptSemanticGraph = (input: unknown): string =>
canonicalJson(parseJavaScriptSemanticGraph(input));
@@ -0,0 +1,594 @@
import { expect, it } from "vitest";
import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
import {
JAVASCRIPT_SEMANTIC_NODE_KINDS,
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
} from "./javascriptSemanticGraphSchemas.js";
import {
createJavaScriptSemanticFingerprint,
createJavaScriptSemanticGraph,
createJavaScriptSemanticGraphNode,
createJavaScriptSemanticGraphRelation,
createJavaScriptSemanticGraphUnknown,
type JavaScriptSemanticGraph,
type JavaScriptSemanticGraphNode,
type JavaScriptSemanticGraphRelation,
} from "./javascriptSemanticGraph.js";
import { queryJavaScriptSemanticGraph } from "./javascriptSemanticQuery.js";
import type { JsonValue } from "../jsonValue.js";
const SHA = "a".repeat(64);
const JAG_ID = `jag_${"b".repeat(64)}`;
const completeCoverage = {
status: "complete",
truncated: false,
omitted_count: 0,
limits: [],
} satisfies ApplicationGraphEvidence["coverage"];
const evidence = (
state: "observed" | "inferred" = "observed",
): ApplicationGraphEvidence => ({
authority:
state === "observed"
? "ast-static-analysis"
: "static-relationship-inference",
state,
confidence: state === "observed" ? "exact" : "high",
artifact: { available: true, artifact_id: `art_${SHA}`, sha256: SHA },
location: {
available: true,
value: {
kind: "source-range",
source: "bundle.js",
start: { line: 1, column: 0 },
end: { line: 1, column: 10 },
},
},
extractor: {
name: "test",
version: "1",
operation: "recover-semantic-relation",
executable_sha256: null,
},
coverage: completeCoverage,
limitations:
state === "observed"
? []
: ["Static reachability does not prove runtime execution."],
evidence_ids: [],
});
const unknownEvidence = (): ApplicationGraphEvidence => ({
authority: "unknown",
state: "unknown",
confidence: "unknown",
artifact: {
available: false,
reason: "unknown",
detail: "Unknown artifact.",
},
location: {
available: false,
reason: "unresolved",
detail: "Dynamic call target.",
},
extractor: {
name: "test",
version: "1",
operation: "retain-dynamic-call",
executable_sha256: null,
},
coverage: {
status: "unknown",
truncated: false,
omitted_count: null,
limits: [],
},
limitations: ["Dynamic call target remains unknown."],
evidence_ids: [],
});
const node = (
kind: (typeof JAVASCRIPT_SEMANTIC_NODE_KINDS)[number],
role: string,
properties: Record<string, JsonValue> = {},
functionNodeId: string | null = null,
): JavaScriptSemanticGraphNode =>
createJavaScriptSemanticGraphNode({
kind,
identity: {
artifact_sha256: SHA,
module_path: "bundle.js",
source_range: {
start: { line: 1, column: role.length },
end: { line: 1, column: role.length + 1 },
},
role_key: role,
},
function_node_id: functionNodeId,
application_node_ids: [],
label: role,
properties,
evidence: evidence(),
});
const fixtureGraph = (withUnknown = false): JavaScriptSemanticGraph => {
const module = node("module", "module");
const literal = node("literal", "literal", { value: "TOKEN" });
const binding = node("binding", "binding");
const callable = node("function", "function");
const request = node("request", "request", {
endpoint: "https://example.invalid/v1",
});
const relations = [
createJavaScriptSemanticGraphRelation({
source_node_id: literal.node_id,
target_node_id: binding.node_id,
relation: "defines",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
createJavaScriptSemanticGraphRelation({
source_node_id: binding.node_id,
target_node_id: callable.node_id,
relation: "captures",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
createJavaScriptSemanticGraphRelation({
source_node_id: callable.node_id,
target_node_id: request.node_id,
relation: "constructs-request",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
];
const dynamic = createJavaScriptSemanticGraphUnknown({
node_id: callable.node_id,
family: "call-flow",
relation_kinds: ["calls"],
reason: "dynamic-call",
detail: "Computed callee is unresolved.",
candidate_node_ids: [],
evidence: unknownEvidence(),
});
const unknowns = withUnknown ? [dynamic] : [];
const coverageFamilies = JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map(
(family) => ({
family,
status:
withUnknown && family === "call-flow"
? ("unknown" as const)
: ("complete" as const),
retained_relations: relations.filter(({ relation }) =>
relation === "defines"
? family === "data-flow"
: relation === "captures"
? family === "closure"
: family === "request",
).length,
omitted_relations: withUnknown && family === "call-flow" ? null : 0,
unknown_ids:
withUnknown && family === "call-flow" ? [dynamic.unknown_id] : [],
}),
);
const fingerprint = createJavaScriptSemanticFingerprint({
function_node_id: callable.node_id,
algorithm: "rea.javascript-semantic-function",
status: "complete",
components: {
parameter_arity: 0,
normalized_ast_sha256: "1".repeat(64),
control_flow_sha256: "2".repeat(64),
relation_shape_sha256: "3".repeat(64),
literal_set_sha256: "4".repeat(64),
effects: ["network"],
},
limitations: [],
evidence: evidence("inferred"),
});
return createJavaScriptSemanticGraph({
schema: "JavaScriptSemanticRelationGraph",
root_artifact_sha256: SHA,
application_graph_id: JAG_ID,
root_node_ids: [module.node_id],
nodes: [request, callable, binding, literal, module],
relations,
fingerprints: [fingerprint],
unknowns,
coverage: {
status: withUnknown ? "partial" : "complete",
truncated: false,
omitted_nodes: withUnknown ? null : 0,
omitted_relations: withUnknown ? null : 0,
limits: [],
families: coverageFamilies,
},
limitations: withUnknown ? ["Dynamic call target remains unknown."] : [],
});
};
const graphWithCandidateEdge = (): JavaScriptSemanticGraph => {
const graph = fixtureGraph();
const literal = graph.nodes.find(({ kind }) => kind === "literal");
const request = graph.nodes.find(({ kind }) => kind === "request");
if (literal === undefined || request === undefined)
throw new TypeError("Semantic fixture nodes are missing");
const candidate = createJavaScriptSemanticGraphRelation({
source_node_id: literal.node_id,
target_node_id: request.node_id,
relation: "supplies-request-field",
resolution: "candidate",
properties: { field: "authorization" },
evidence: evidence("inferred"),
});
const { graph_id: _graphId, ...input } = graph;
return createJavaScriptSemanticGraph({
...input,
relations: [...graph.relations, candidate],
coverage: {
...graph.coverage,
families: graph.coverage.families.map((family) =>
family.family === "request"
? {
...family,
retained_relations: family.retained_relations + 1,
}
: family,
),
},
});
};
it("returns every relevant unknown inline", () => {
const graph = fixtureGraph(true);
const callable = graph.nodes.find(({ kind }) => kind === "function");
if (callable === undefined) throw new Error("Expected callable node");
const result = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "semantic-node", node_id: callable.node_id },
direction: "forward-influence",
});
expect(result).toMatchObject({
summary: { relevant_unknowns: 1 },
});
expect(result.unknowns).toHaveLength(1);
});
it("returns the complete deterministic forward influence result inline", () => {
const graph = fixtureGraph();
const input = {
seed: { kind: "literal" as const, value: "TOKEN" },
direction: "forward-influence" as const,
expected: { role: "sink" as const, classes: ["request" as const] },
};
const first = queryJavaScriptSemanticGraph(graph, input);
expect(first).toMatchObject({
status: "found",
summary: { traversed_nodes: 4, traversed_relations: 3 },
relations: expect.any(Array),
});
expect(first.expected_match_node_ids).toHaveLength(1);
expect(first.relations).toHaveLength(3);
});
it("traverses paths beyond the former fixed depth ceiling", () => {
const original = fixtureGraph();
const request = original.nodes.find(({ kind }) => kind === "request");
if (request === undefined) throw new TypeError("Missing request node");
const chain = Array.from({ length: 70 }, (_, index) =>
node("binding", `long-chain-${index}`),
);
const chainRelations = chain.map((target, index) =>
createJavaScriptSemanticGraphRelation({
source_node_id: chain[index - 1]?.node_id ?? request.node_id,
target_node_id: target.node_id,
relation: "reads",
resolution: "resolved",
properties: {},
evidence: evidence("inferred"),
}),
);
const { graph_id: _graphId, ...input } = original;
const graph = createJavaScriptSemanticGraph({
...input,
nodes: [...original.nodes, ...chain],
relations: [...original.relations, ...chainRelations],
coverage: {
...original.coverage,
families: original.coverage.families.map((family) =>
family.family === "data-flow"
? {
...family,
retained_relations:
family.retained_relations + chainRelations.length,
}
: family,
),
},
});
const result = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
});
expect(result.summary.traversed_nodes).toBe(74);
expect(result.nodes).toHaveLength(74);
});
it("accepts deeply nested semantic properties", () => {
let nested: JsonValue = "leaf";
for (let index = 0; index < 12; index += 1)
nested = { [`level-${String(index)}`]: nested };
const result = node("binding", "deep-properties", { nested });
expect(result.properties).toEqual({ nested });
});
it("keeps relevant dynamic frontiers unknown", () => {
const result = queryJavaScriptSemanticGraph(fixtureGraph(true), {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
});
expect(result.status).toBe("found");
expect(result.coverage.status).toBe("partial");
expect(result.unknowns).toMatchObject([
{ reason: "dynamic-call", relation_kinds: ["calls"] },
]);
});
it("excludes candidate edges unless the caller explicitly opts in", () => {
const graph = graphWithCandidateEdge();
const input = {
seed: { kind: "literal" as const, value: "TOKEN" },
direction: "forward-influence" as const,
allowed_relations: ["supplies-request-field" as const],
};
const conservative = queryJavaScriptSemanticGraph(graph, input);
const optedIn = queryJavaScriptSemanticGraph(graph, {
...input,
include_ambiguous_dynamic_edges: true,
});
expect(conservative.summary.traversed_relations).toBe(0);
expect(optedIn.summary.traversed_relations).toBe(1);
expect(conservative.status).toBe("ambiguous");
expect(conservative.coverage.status).toBe("partial");
expect(optedIn.status).toBe("ambiguous");
expect(optedIn.relations).toMatchObject([
{ relation: "supplies-request-field", resolution: "candidate" },
]);
});
it("retains every structural application node linked to one semantic node", () => {
const original = node("module", "module");
const linked = createJavaScriptSemanticGraphNode({
kind: original.kind,
identity: original.identity,
function_node_id: original.function_node_id,
application_node_ids: Array.from(
{ length: 65 },
(_, index) => `jag_node_${index.toString(16).padStart(64, "0")}`,
),
label: original.label,
properties: original.properties,
evidence: original.evidence,
});
expect(linked.application_node_ids).toHaveLength(65);
});
it("retains all explicit unresolved candidate node identifiers", () => {
const unknown = createJavaScriptSemanticGraphUnknown({
node_id: null,
family: "call-flow",
relation_kinds: ["calls"],
reason: "ambiguous-target",
detail: "All candidate targets are retained.",
candidate_node_ids: Array.from(
{ length: 1_001 },
(_, index) => `jsrg_node_${index.toString(16).padStart(64, "0")}`,
),
evidence: unknownEvidence(),
});
expect(unknown.candidate_node_ids).toHaveLength(1_001);
});
const directionalGraph = (
nodes: readonly JavaScriptSemanticGraphNode[],
relations: readonly JavaScriptSemanticGraphRelation[],
partial = false,
): JavaScriptSemanticGraph =>
createJavaScriptSemanticGraph({
schema: "JavaScriptSemanticRelationGraph",
root_artifact_sha256: SHA,
application_graph_id: JAG_ID,
root_node_ids: nodes.slice(0, 1).map(({ node_id }) => node_id),
nodes: [...nodes],
relations: [...relations],
fingerprints: [],
unknowns: [],
coverage: {
status: partial ? "partial" : "complete",
truncated: false,
omitted_nodes: partial ? 1 : 0,
omitted_relations: 0,
limits: [],
families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
family,
status: "complete",
retained_relations: relations.filter(
({ relation }) =>
JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation] === family,
).length,
omitted_relations: 0,
unknown_ids: [],
})),
},
limitations: partial ? ["One source graph node was omitted."] : [],
});
const relationBetween = (
source: JavaScriptSemanticGraphNode,
target: JavaScriptSemanticGraphNode,
relation: JavaScriptSemanticGraphRelation["relation"],
resolution: JavaScriptSemanticGraphRelation["resolution"] = "resolved",
) =>
createJavaScriptSemanticGraphRelation({
source_node_id: source.node_id,
target_node_id: target.node_id,
relation,
resolution,
properties: {},
evidence: evidence("inferred"),
});
it.each([
{
direction: "forward-influence",
relation: "calls",
incoming: true,
relevant: false,
},
{
direction: "forward-influence",
relation: "calls",
incoming: false,
relevant: true,
},
{
direction: "backward-provenance",
relation: "calls",
incoming: false,
relevant: false,
},
{
direction: "backward-provenance",
relation: "calls",
incoming: true,
relevant: true,
},
{ direction: "callers", relation: "reads", incoming: true, relevant: false },
{ direction: "callers", relation: "calls", incoming: false, relevant: false },
{ direction: "callers", relation: "calls", incoming: true, relevant: true },
{
direction: "ownership",
relation: "reads",
incoming: false,
relevant: false,
},
{ direction: "ownership", relation: "owns", incoming: false, relevant: true },
{ direction: "ownership", relation: "owns", incoming: true, relevant: true },
] as const)(
"limits $direction ambiguity to traversable $relation candidates (incoming=$incoming)",
({ direction, relation, incoming, relevant }) => {
const seed = node("function", "directional-seed");
const reached = node("function", "directional-reached");
const other = node("function", "directional-other");
const reverse =
direction === "callers" || direction === "backward-provenance";
const resolved = relationBetween(
reverse ? reached : seed,
reverse ? seed : reached,
direction === "ownership" ? "owns" : "calls",
);
const candidate = relationBetween(
incoming ? other : reached,
incoming ? reached : other,
relation,
"candidate",
);
const nodes = [seed, reached, other];
const control = queryJavaScriptSemanticGraph(
directionalGraph(nodes, [resolved]),
{
seed: { kind: "semantic-node", node_id: seed.node_id },
direction,
},
);
expect(control).toMatchObject({
status: "found",
coverage: { status: "complete" },
});
for (const include of [false, true]) {
const result = queryJavaScriptSemanticGraph(
directionalGraph(nodes, [resolved, candidate]),
{
seed: { kind: "semantic-node", node_id: seed.node_id },
direction,
include_ambiguous_dynamic_edges: include,
},
);
expect(result).toMatchObject({
status: relevant ? "ambiguous" : "found",
coverage: { status: relevant ? "partial" : "complete" },
});
if (!relevant || !include) {
expect(result.nodes).toEqual(control.nodes);
expect(result.relations).toEqual(control.relations);
} else {
expect(result.nodes).toHaveLength(3);
expect(result.relations).toContainEqual(candidate);
}
}
},
);
it("excludes explicitly filtered candidates without hiding partial graph coverage", () => {
const seed = node("function", "filtered-seed");
const other = node("function", "filtered-other");
const candidate = relationBetween(seed, other, "reads", "candidate");
for (const partial of [false, true]) {
const result = queryJavaScriptSemanticGraph(
directionalGraph([seed, other], [candidate], partial),
{
seed: { kind: "semantic-node", node_id: seed.node_id },
direction: "forward-influence",
allowed_relations: ["calls"],
},
);
expect(result).toMatchObject({
status: "found",
coverage: { status: partial ? "partial" : "complete" },
relations: [],
});
}
});
it("keeps candidate uncertainty at the end of a long reachable path", () => {
const chain = Array.from({ length: 72 }, (_, index) =>
node("binding", `candidate-chain-${index}`),
);
const relations = chain.slice(1).map((target, index) => {
const source = chain[index];
if (source === undefined) throw new TypeError("Missing chain source");
return relationBetween(
source,
target,
"reads",
index === 70 ? "candidate" : "resolved",
);
});
const seed = chain[0];
if (seed === undefined) throw new TypeError("Missing chain seed");
for (const include of [false, true]) {
const result = queryJavaScriptSemanticGraph(
directionalGraph(chain, relations),
{
seed: { kind: "semantic-node", node_id: seed.node_id },
direction: "forward-influence",
include_ambiguous_dynamic_edges: include,
},
);
expect(result).toMatchObject({
status: "ambiguous",
coverage: { status: "partial" },
});
expect(result.nodes).toHaveLength(include ? 72 : 71);
}
});
@@ -0,0 +1,492 @@
import type { JavaScriptSourceRange } from "./javascriptStaticAnalysisTypes.js";
import type { JavaScriptSemanticValue } from "./javascriptSemanticValueTypes.js";
import type {
JavaScriptSemanticCoverage,
JavaScriptSemanticReturnCoverage,
} from "./javascriptSemanticCoverage.js";
export type {
JavaScriptSemanticPrimitive,
JavaScriptSemanticProperty,
JavaScriptSemanticValue,
} from "./javascriptSemanticValueTypes.js";
/** One exact module origin followed through imports, requires, or aliases. */
export interface JavaScriptModuleOrigin {
readonly specifier: string;
readonly importedPath: readonly string[];
}
/** Fail-closed provenance classification for one binding. */
export type JavaScriptBindingProvenance =
| {
readonly status: "module";
readonly origins: readonly [JavaScriptModuleOrigin];
readonly reason: null;
}
| {
readonly status: "local";
readonly origins: readonly [];
readonly reason: null;
}
| {
readonly status: "ambiguous";
readonly origins: readonly JavaScriptModuleOrigin[];
readonly reason: string;
}
| {
readonly status: "unknown" | "cycle";
readonly origins: readonly [];
readonly reason: string;
};
/** One lexical scope recovered without executing source. */
export interface JavaScriptSemanticScope {
readonly scopeId: string;
readonly parentScopeId: string | null;
readonly kind:
| "program"
| "function"
| "block"
| "static-block"
| "class"
| "catch";
readonly location: JavaScriptSourceRange;
readonly bindingsComplete: boolean;
readonly bindingIds: readonly string[];
}
/** One declaration or assignment contributing to a binding. */
export interface JavaScriptSemanticDefinition {
readonly kind:
| "import"
| "variable"
| "parameter"
| "function"
| "class"
| "catch"
| "assignment";
readonly location: JavaScriptSourceRange;
}
/** One resolved lexical binding plus static value and provenance. */
export interface JavaScriptSemanticBinding {
readonly bindingId: string;
readonly scopeId: string;
readonly name: string;
readonly kind: JavaScriptSemanticDefinition["kind"];
readonly mutable: boolean;
readonly definitions: readonly JavaScriptSemanticDefinition[];
readonly value: JavaScriptSemanticValue;
readonly provenance: JavaScriptBindingProvenance;
}
/** One identifier use and its fail-closed lexical resolution. */
export interface JavaScriptSemanticReference {
readonly name: string;
readonly role: "read" | "write" | "export";
readonly location: JavaScriptSourceRange;
readonly bindingId: string | null;
readonly resolution: "resolved" | "unbound" | "ambiguous" | "unknown";
}
/** Function, class, or method identity without pretending it is a binding. */
export interface JavaScriptSemanticCallable {
readonly callableId: string;
readonly kind: "function" | "class" | "method";
readonly name: string | null;
readonly containerScopeId: string;
readonly bodyScopeId: string | null;
readonly location: JavaScriptSourceRange;
readonly returnSites: readonly JavaScriptSemanticReturnSite[];
readonly returnCoverage: JavaScriptSemanticReturnCoverage;
}
/** One direct return expression belonging to exactly one callable. */
export interface JavaScriptSemanticReturnSite {
readonly returnSiteId: string;
readonly location: JavaScriptSourceRange;
readonly identityReferenceLocation: JavaScriptSourceRange | null;
readonly value: JavaScriptSemanticValue;
}
/** One statically visible call or construction expression. */
export interface JavaScriptSemanticCallSite {
readonly callSiteId: string;
readonly kind: "call" | "construct";
readonly callerCallableId: string | null;
readonly location: JavaScriptSourceRange;
readonly calleeLocation: JavaScriptSourceRange;
readonly resolution: "exact" | "ambiguous" | "unresolved";
readonly calleeCallableIds: readonly string[];
readonly arguments: readonly JavaScriptSemanticCallArgument[];
}
/** One argument occurrence retained without evaluating application code. */
export interface JavaScriptSemanticCallArgument {
readonly index: number;
readonly location: JavaScriptSourceRange;
readonly spread: boolean;
}
/** One positional argument that may initialize one local parameter binding. */
export interface JavaScriptSemanticArgumentFlow {
readonly callSiteId: string;
readonly argumentIndex: number;
readonly argumentLocation: JavaScriptSourceRange;
readonly callableId: string;
readonly parameterBindingId: string;
readonly parameterLocation: JavaScriptSourceRange;
}
/** One direct local return that may supply a call expression's value. */
export interface JavaScriptSemanticCallReturnFlow {
readonly callSiteId: string;
readonly callableId: string;
readonly returnSiteId: string;
readonly returnLocation: JavaScriptSourceRange;
}
/** One local binding initialized or assigned from a retained call expression. */
export interface JavaScriptSemanticCallResultFlow {
readonly callSiteId: string;
readonly bindingId: string;
readonly definitionLocation: JavaScriptSourceRange;
}
/** One resolved outer lexical binding referenced by a nested callable. */
export interface JavaScriptSemanticClosureCapture {
readonly callableId: string;
readonly bindingId: string;
readonly referenceLocation: JavaScriptSourceRange;
}
/** One promise/task operation recovered from explicit syntax. */
export interface JavaScriptSemanticPromiseOperation {
readonly promiseId: string;
readonly kind:
| "constructor"
| "static"
| "chain"
| "aggregate"
| "awaited-expression";
readonly method:
| "new"
| "resolve"
| "reject"
| "then"
| "catch"
| "finally"
| "all"
| "allSettled"
| "await";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly ownership:
| "awaited"
| "returned"
| "detached"
| "assigned"
| "chained"
| "aggregated"
| "unknown";
readonly ownerBindingId: string | null;
readonly returnSiteId: string | null;
readonly sourcePromiseIds: readonly string[];
readonly sourceResolution: "complete" | "partial" | "unresolved";
}
/** Rename-resistant bounded component commitment for one callable. */
export interface JavaScriptSemanticFunctionFingerprint {
readonly callableId: string;
readonly status: "complete" | "partial" | "unavailable";
readonly components: {
readonly parameterArity: number;
readonly normalizedAstSha256: string;
readonly controlFlowSha256: string;
readonly relationShapeSha256: string;
readonly literalSetSha256: string;
readonly effects: readonly (
| "async"
| "child-process"
| "event"
| "network"
| "promise"
| "resource"
| "timer"
)[];
};
readonly limitations: readonly string[];
}
/** One EventEmitter-style registration, removal, or dispatch candidate. */
export interface JavaScriptSemanticEventOperation {
readonly eventId: string;
readonly kind: "register" | "remove" | "dispatch";
readonly method:
| "on"
| "once"
| "addListener"
| "prependListener"
| "prependOnceListener"
| "off"
| "removeListener"
| "removeAllListeners"
| "emit";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly emitterKey: string;
readonly emitterBindingId: string | null;
readonly eventName: string | null;
readonly listenerBindingId: string | null;
readonly listenerLocation: JavaScriptSourceRange | null;
readonly resolution: "complete" | "partial" | "unresolved";
}
/** One timer scheduling or cancellation candidate. */
export interface JavaScriptSemanticTimerOperation {
readonly timerId: string;
readonly kind: "schedule" | "cancel";
readonly method:
| "setTimeout"
| "setInterval"
| "setImmediate"
| "clearTimeout"
| "clearInterval"
| "clearImmediate";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly handleBindingId: string | null;
readonly projectedResultBindings: readonly JavaScriptSemanticProjectedResultBinding[];
readonly linkedTimerId: string | null;
readonly delayMilliseconds: number | null;
readonly resolution: "complete" | "partial" | "unresolved";
}
/** One explicit asynchronous node:child_process creation candidate. */
export interface JavaScriptSemanticChildProcessSpawn {
readonly processId: string;
readonly method: "spawn" | "exec" | "execFile" | "fork";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
readonly projectedResultBindings: readonly JavaScriptSemanticProjectedResultBinding[];
readonly command: string | null;
readonly argvCount: number | null;
readonly environmentSupplied: boolean;
readonly stdioMode: string;
readonly resolution: "complete" | "partial";
}
/** One exit/error listener or signal operation linked to child candidates. */
export interface JavaScriptSemanticChildProcessInteraction {
readonly interactionId: string;
readonly kind: "listener" | "signal";
readonly method: "on" | "once" | "addListener" | "kill";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly processBindingId: string | null;
readonly linkedProcessIds: readonly string[];
readonly eventName: "exit" | "error" | null;
readonly signalName: string | null;
readonly listenerLocation: JavaScriptSourceRange | null;
readonly resolution: "complete" | "partial";
}
/** One environment, argv, file, or default configuration source. */
export interface JavaScriptSemanticConfigurationOperation {
readonly configId: string;
readonly kind: "environment" | "argv" | "file" | "default";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
readonly key: string | null;
readonly sourceConfigId: string | null;
readonly value: string | number | boolean | null;
readonly resolution: "complete" | "partial";
}
/** One request construction or response-consumer candidate. */
export interface JavaScriptSemanticRequestOperation {
readonly requestId: string;
readonly kind: "request" | "response-consumer";
readonly method:
| "fetch"
| "WebSocket"
| "request"
| "get"
| "json"
| "text"
| "arrayBuffer";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
readonly projectedResultBindings: readonly JavaScriptSemanticProjectedResultBinding[];
readonly linkedRequestIds: readonly string[];
readonly endpoint: string | null;
readonly fields: readonly {
readonly name: string;
readonly sourceBindingId: string | null;
}[];
readonly resolution: "complete" | "partial" | "unresolved";
}
/** A destructured result binding with its known projection path. */
export interface JavaScriptSemanticProjectedResultBinding {
readonly bindingId: string;
readonly projectionPath: readonly (string | number | null)[];
readonly resolution: "complete" | "partial";
}
/** One parse, coercion, or validation boundary candidate. */
export interface JavaScriptSemanticBoundaryOperation {
readonly boundaryId: string;
readonly kind: "parse" | "coerce" | "validate";
readonly method: string;
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly sourceBindingId: string | null;
readonly resultBindingId: string | null;
readonly resolution: "complete" | "partial";
}
/** One explicit built-in resource acquisition or release candidate. */
export interface JavaScriptSemanticResourceOperation {
readonly resourceId: string;
readonly kind: "acquire" | "release";
readonly method:
| "open"
| "openSync"
| "createReadStream"
| "createWriteStream"
| "connect"
| "createConnection"
| "close"
| "destroy"
| "end";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
readonly linkedResourceIds: readonly string[];
readonly resolution: "complete" | "partial";
}
/** One static property read/write, spread, or destructuring candidate. */
export interface JavaScriptSemanticObjectOperation {
readonly objectOperationId: string;
readonly kind: "read" | "write" | "spread" | "destructure";
readonly location: JavaScriptSourceRange;
readonly ownerCallableId: string | null;
readonly objectBindingId: string | null;
readonly targetBindingId: string | null;
readonly propertyName: string | null;
readonly resolution: "complete" | "partial";
}
/** One syntax location where exact local semantic continuation is unavailable. */
export interface JavaScriptSemanticFrontier {
/**
* `dynamic-call`/`dynamic-property` mark a callee or key the analyzer could
* not resolve. `dynamic-scope` marks `with`/`eval`, where the binding
* environment itself is not statically knowable.
*/
readonly kind: "dynamic-call" | "dynamic-property" | "dynamic-scope";
readonly callableId: string | null;
readonly location: JavaScriptSourceRange;
readonly reason: string;
}
/** Static import/export relationship retained for cross-file composition. */
export interface JavaScriptSemanticModuleLink {
readonly kind:
| "import"
| "require"
| "export"
| "re-export"
| "commonjs-export";
readonly specifier: string | null;
readonly importedName: string | null;
readonly localName: string | null;
readonly exportedName: string | null;
readonly callableId: string | null;
readonly location: JavaScriptSourceRange;
}
/** Provider-neutral JavaScript semantic IR. */
export interface JavaScriptSemanticIr {
readonly schema: "JavaScriptSemanticIR";
readonly scopes: readonly JavaScriptSemanticScope[];
readonly bindings: readonly JavaScriptSemanticBinding[];
readonly callables: readonly JavaScriptSemanticCallable[];
readonly references: readonly JavaScriptSemanticReference[];
readonly moduleLinks: readonly JavaScriptSemanticModuleLink[];
readonly callSites: readonly JavaScriptSemanticCallSite[];
readonly argumentFlows: readonly JavaScriptSemanticArgumentFlow[];
readonly callReturnFlows: readonly JavaScriptSemanticCallReturnFlow[];
readonly callResultFlows: readonly JavaScriptSemanticCallResultFlow[];
readonly closureCaptures: readonly JavaScriptSemanticClosureCapture[];
readonly promiseOperations: readonly JavaScriptSemanticPromiseOperation[];
readonly eventOperations: readonly JavaScriptSemanticEventOperation[];
readonly timerOperations: readonly JavaScriptSemanticTimerOperation[];
readonly childProcessSpawns: readonly JavaScriptSemanticChildProcessSpawn[];
readonly childProcessInteractions: readonly JavaScriptSemanticChildProcessInteraction[];
readonly configurationOperations: readonly JavaScriptSemanticConfigurationOperation[];
readonly requestOperations: readonly JavaScriptSemanticRequestOperation[];
readonly boundaryOperations: readonly JavaScriptSemanticBoundaryOperation[];
readonly resourceOperations: readonly JavaScriptSemanticResourceOperation[];
readonly objectOperations: readonly JavaScriptSemanticObjectOperation[];
readonly functionFingerprints: readonly JavaScriptSemanticFunctionFingerprint[];
readonly frontiers: readonly JavaScriptSemanticFrontier[];
readonly coverage: JavaScriptSemanticCoverage;
readonly limitations: readonly string[];
}
/** Find the innermost resolved reference at one source coordinate. */
export const semanticReferenceAt = (
ir: JavaScriptSemanticIr,
line: number,
column: number,
): JavaScriptSemanticReference | undefined =>
ir.references.find(
({ location }) =>
location.start.line === line && location.start.column === column,
);
/** Read one binding by its deterministic semantic identifier. */
export const semanticBinding = (
ir: JavaScriptSemanticIr,
bindingId: string,
): JavaScriptSemanticBinding | undefined =>
ir.bindings.find(({ bindingId: candidate }) => candidate === bindingId);
/** Fail-closed result when Babel cannot produce an inert syntax tree. */
export const failedJavaScriptSemanticIr = (): JavaScriptSemanticIr => ({
schema: "JavaScriptSemanticIR",
scopes: [],
bindings: [],
callables: [],
references: [],
moduleLinks: [],
callSites: [],
argumentFlows: [],
callReturnFlows: [],
callResultFlows: [],
closureCaptures: [],
promiseOperations: [],
eventOperations: [],
timerOperations: [],
childProcessSpawns: [],
childProcessInteractions: [],
configurationOperations: [],
requestOperations: [],
boundaryOperations: [],
resourceOperations: [],
objectOperations: [],
functionFingerprints: [],
frontiers: [],
coverage: { status: "failed", omittedCount: null },
limitations: [
"JavaScript parsing failed; no semantic absence claim is available.",
"No JavaScript was executed.",
],
});
@@ -0,0 +1,143 @@
import * as t from "@babel/types";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
} from "./javascriptSemanticState.js";
import { evaluateSemanticBinding } from "./javascriptSemanticValues.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import {
semanticStaticPropertyKey,
semanticStaticPropertyName,
} from "./javascriptAstValues.js";
type PropertyPath = readonly (string | number | null)[];
/** Keep explicit property mutations outside the initializer-only value lattice. */
export const collectSemanticMemberMutations = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
): void => {
const markValue = (
node: t.Node,
path: PropertyPath,
bindings: ReadonlySet<string>,
): void => {
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(state, node, node.name);
if (binding === undefined || bindings.has(binding.bindingId)) return;
const value = evaluateSemanticBinding(binding, state);
if (value.status === "literal" || value.status === "union") return;
binding.mutatedPaths.push(path);
const nested = new Set([...bindings, binding.bindingId]);
for (const initializer of binding.initializers)
markValue(
initializer.node,
[...initializer.projection, ...path],
nested,
);
return;
}
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
markValue(
node.object,
[semanticStaticPropertyKey(node.property, node.computed), ...path],
bindings,
);
return;
}
for (const value of referencedValues(node, path))
markValue(value.node, value.path, bindings);
};
const markTarget = (node: t.Node): void => {
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
markValue(
node.object,
[semanticStaticPropertyKey(node.property, node.computed)],
new Set(),
);
else if (t.isRestElement(node)) markTarget(node.argument);
else if (t.isAssignmentPattern(node)) markTarget(node.left);
else if (t.isArrayPattern(node)) {
for (const element of node.elements)
if (element !== null) markTarget(element);
} else if (t.isObjectPattern(node)) {
for (const property of node.properties)
markTarget(
t.isRestElement(property) ? property.argument : property.value,
);
}
};
traverseJavaScriptAst(program, {
enter: (node) => {
if (t.isAssignmentExpression(node)) markTarget(node.left);
else if (t.isUpdateExpression(node)) markTarget(node.argument);
else if (t.isUnaryExpression(node, { operator: "delete" }))
markTarget(node.argument);
else if (t.isForOfStatement(node) || t.isForInStatement(node))
markTarget(node.left);
},
});
};
interface ReferencedValue {
readonly node: t.Node;
readonly path: PropertyPath;
}
const referencedValues = (
node: t.Node,
path: PropertyPath,
): readonly ReferencedValue[] => {
const [key, ...remaining] = path;
// An initializer owns its slots; only deeper writes can affect shared children.
if (t.isObjectExpression(node))
return path.length < 2
? []
: node.properties.flatMap<ReferencedValue>((property) => {
if (t.isSpreadElement(property))
return [{ node: property.argument, path }];
if (!t.isObjectProperty(property)) return [];
const name = semanticStaticPropertyName(
property.key,
property.computed,
);
return key === null ||
(name === "" && !t.isStringLiteral(property.key, { value: "" })) ||
String(key) === name
? [{ node: property.value, path: remaining }]
: [];
});
if (t.isArrayExpression(node)) {
if (path.length < 2) return [];
let uncertainIndex = false;
return node.elements.flatMap<ReferencedValue>((element, index) => {
if (element === null) return [];
if (t.isSpreadElement(element)) {
uncertainIndex = true;
return [{ node: element.argument, path: [null, ...remaining] }];
}
return uncertainIndex || key === null || String(key) === String(index)
? [{ node: element, path: remaining }]
: [];
});
}
if (
t.isTSAsExpression(node) ||
t.isTSTypeAssertion(node) ||
t.isTSSatisfiesExpression(node) ||
t.isTSNonNullExpression(node)
)
return [{ node: node.expression, path }];
if (t.isConditionalExpression(node))
return [
{ node: node.consequent, path },
{ node: node.alternate, path },
];
if (t.isLogicalExpression(node))
return [
{ node: node.left, path },
{ node: node.right, path },
];
return [];
};
@@ -0,0 +1,65 @@
import type { JavaScriptSemanticValue } from "./javascriptSemanticIr.js";
/** Invalidate only slots that an explicit mutation can affect. */
export const invalidateSemanticMutationPath = (
value: JavaScriptSemanticValue,
path: readonly (string | number | null)[],
): JavaScriptSemanticValue => {
const [key, ...remaining] = path;
const unknown: JavaScriptSemanticValue = {
status: "unknown",
reason: "This property may have been mutated.",
};
if (key === undefined || key === null) return unknown;
if (value.status === "object") {
const name = String(key);
const observed = value.properties.some(
(property) => property.name === name,
);
const properties = value.properties.map((property) =>
property.name === name
? {
...property,
value: invalidateSemanticMutationPath(property.value, remaining),
}
: property,
);
return value.unknownProperties || !observed
? {
status: "object",
properties,
unknownProperties: true,
omittedProperties: observed ? value.omittedProperties : null,
}
: {
status: "object",
properties,
unknownProperties: false,
omittedProperties: 0,
};
}
if (value.status === "array") {
const index = typeof key === "number" ? key : Number(key);
if (
!Number.isSafeInteger(index) ||
index < 0 ||
String(index) !== String(key)
)
return unknown;
const observed = value.items[index] !== undefined;
const items = value.items.map((item, position) =>
position === index
? invalidateSemanticMutationPath(item, remaining)
: item,
);
return value.unknownItems || !observed
? {
status: "array",
items,
unknownItems: true,
omittedItems: observed ? value.omittedItems : null,
}
: { status: "array", items, unknownItems: false, omittedItems: 0 };
}
return unknown;
};
@@ -0,0 +1,191 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticObjectOperation,
} from "./javascriptSemanticIr.js";
import {
semanticCallableIdForNode,
semanticReadsBeforeWrite,
semanticStaticPropertyKey,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
} from "./javascriptSemanticState.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
/** Recover bounded static property reads, writes, spreads, and destructuring. */
export const collectJavaScriptSemanticObjects = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticObjectOperation[] => {
const output: JavaScriptSemanticObjectOperation[] = [];
const callableIds = new Set(callables.map(({ callableId }) => callableId));
const callableStack: string[] = [];
const context: ObjectCollectionContext = { state, output };
traverseJavaScriptAst(program, {
enter: (node, parent) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableIds.has(callableId))
callableStack.push(callableId);
const ownerCallableId = callableStack.at(-1) ?? null;
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
collectMember(node, parent, ownerCallableId, context);
else if (
t.isSpreadElement(node) &&
parent !== null &&
t.isObjectExpression(parent)
)
addObjectOperation(
{
node,
kind: "spread",
ownerCallableId,
objectBindingId: expressionBindingId(node.argument, state),
targetBindingId: null,
propertyName: null,
},
state,
output,
);
else if (t.isVariableDeclarator(node) && t.isObjectPattern(node.id))
collectDestructuring(node, ownerCallableId, state, output);
},
exit: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableStack.at(-1) === callableId)
callableStack.pop();
},
});
return output;
};
interface ObjectCollectionContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly output: JavaScriptSemanticObjectOperation[];
}
const collectMember = (
node: t.MemberExpression | t.OptionalMemberExpression,
parent: t.Node | null,
ownerCallableId: string | null,
context: ObjectCollectionContext,
): void => {
const { state, output } = context;
const name = semanticStaticPropertyKey(node.property, node.computed);
if (name === null) return;
const write =
(t.isAssignmentExpression(parent) && parent.left === node) ||
(t.isUpdateExpression(parent) && parent.argument === node);
const readsBeforeWrite = write && semanticReadsBeforeWrite(node, parent);
if (readsBeforeWrite)
addObjectOperation(
{
node,
kind: "read",
ownerCallableId,
objectBindingId: expressionBindingId(node.object, state),
targetBindingId: null,
propertyName: name,
},
state,
output,
);
addObjectOperation(
{
node,
kind: write ? "write" : "read",
ownerCallableId,
objectBindingId: expressionBindingId(node.object, state),
targetBindingId: null,
propertyName: name,
},
state,
output,
);
};
const collectDestructuring = (
node: t.VariableDeclarator,
ownerCallableId: string | null,
state: JavaScriptSemanticAnalysisState,
output: JavaScriptSemanticObjectOperation[],
): void => {
if (!t.isObjectPattern(node.id)) return;
const objectBindingId = expressionBindingId(node.init, state);
for (const property of node.id.properties) {
if (!t.isObjectProperty(property)) continue;
const name = semanticStaticPropertyKey(property.key, property.computed);
if (name === null) continue;
const target = bindingIdentifier(property.value);
addObjectOperation(
{
node: property,
kind: "destructure",
ownerCallableId,
objectBindingId,
targetBindingId:
target === null
? null
: (resolveSemanticBindingState(state, target, target.name)
?.bindingId ?? null),
propertyName: name,
},
state,
output,
);
}
};
interface AddObjectOperationInput {
readonly node: t.Node;
readonly kind: JavaScriptSemanticObjectOperation["kind"];
readonly ownerCallableId: string | null;
readonly objectBindingId: string | null;
readonly targetBindingId: string | null;
readonly propertyName: string | null;
}
const addObjectOperation = (
input: AddObjectOperationInput,
state: JavaScriptSemanticAnalysisState,
output: JavaScriptSemanticObjectOperation[],
): void => {
output.push({
objectOperationId: `object:${input.kind}:${String(input.node.start ?? -1)}:${String(input.node.end ?? -1)}`,
kind: input.kind,
location: range(input.node),
ownerCallableId: input.ownerCallableId,
objectBindingId: input.objectBindingId,
targetBindingId: input.targetBindingId,
propertyName: input.propertyName,
resolution:
input.kind === "spread"
? input.objectBindingId === null
? "partial"
: "complete"
: input.objectBindingId === null ||
input.propertyName === null ||
(input.kind === "destructure" && input.targetBindingId === null)
? "partial"
: "complete",
});
};
const expressionBindingId = (
node: t.Node | null | undefined,
state: JavaScriptSemanticAnalysisState,
): string | null =>
t.isIdentifier(node)
? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
: null;
const bindingIdentifier = (node: t.Node): t.Identifier | null => {
if (t.isIdentifier(node)) return node;
if (t.isAssignmentPattern(node) && t.isIdentifier(node.left))
return node.left;
return null;
};
@@ -0,0 +1,56 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticPrimitive,
JavaScriptSemanticValue,
} from "./javascriptSemanticIr.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { semanticPrimitiveKey } from "./javascriptSemanticProvenance.js";
/** Normalize one bounded collection of possible primitive values. */
export const semanticPrimitiveSet = (
values: readonly JavaScriptSemanticPrimitive[],
): JavaScriptSemanticValue => {
if (
values.some((value) => typeof value === "number" && !Number.isFinite(value))
)
return {
status: "unknown",
reason: "Nonfinite numbers are outside the JSON primitive lattice.",
};
const unique = [
...new Map(
values.map((value) => [semanticPrimitiveKey(value), value]),
).values(),
].sort((left, right) =>
compareCodePoints(semanticPrimitiveKey(left), semanticPrimitiveKey(right)),
);
const only = unique[0];
return unique.length === 1 && only !== undefined
? { status: "literal", value: only }
: { status: "union", values: unique };
};
/** Read the primitive candidates retained in one lattice value. */
export const semanticPrimitiveCandidates = (
value: JavaScriptSemanticValue,
): readonly JavaScriptSemanticPrimitive[] | null =>
value.status === "literal"
? [value.value]
: value.status === "union"
? value.values
: null;
/** Parse one Babel primitive literal without evaluating code. */
export const semanticPrimitiveValue = (
node: t.Node,
):
| { readonly found: true; readonly value: JavaScriptSemanticPrimitive }
| { readonly found: false } => {
if (t.isStringLiteral(node)) return { found: true, value: node.value };
if (t.isNumericLiteral(node) && Number.isFinite(node.value))
return { found: true, value: node.value };
if (t.isBooleanLiteral(node)) return { found: true, value: node.value };
if (t.isNullLiteral(node)) return { found: true, value: null };
return { found: false };
};
@@ -0,0 +1,638 @@
import * as t from "@babel/types";
import type {
JavaScriptModuleOrigin,
JavaScriptSemanticBinding,
JavaScriptSemanticModuleLink,
JavaScriptSemanticReference,
JavaScriptSemanticScope,
} from "./javascriptSemanticIr.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
isUnshadowedGlobal,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticScopeState,
} from "./javascriptSemanticState.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import {
evaluateSemanticBinding,
evaluateSemanticProvenance,
} from "./javascriptSemanticValues.js";
import {
propertyName,
range,
stringValue,
} from "./javascriptStaticAnalysisHelpers.js";
import { semanticStaticPropertyKey } from "./javascriptAstValues.js";
interface CollectCallableInput {
readonly node: t.Node;
readonly parent: t.Node | null;
readonly containerScope: JavaScriptSemanticScopeState;
readonly bodyScope: JavaScriptSemanticScopeState | undefined;
readonly state: JavaScriptSemanticAnalysisState;
}
/** Retain callable identity without polluting lexical bindings. */
export const collectSemanticCallable = (input: CollectCallableInput): void => {
const { node, parent, containerScope, bodyScope, state } = input;
const kind = callableKind(node);
if (kind === undefined) return;
const callableId =
semanticCallableIdForNode(node) ?? "callable:unknown:-1:-1";
state.callables.push({
callableId,
kind,
name: callableName(node, parent),
containerScopeId: containerScope.scopeId,
bodyScopeId:
bodyScope === undefined || !bodyScope.bindingsComplete
? null
: bodyScope.scopeId,
location: range(node),
returnSites: [],
returnCoverage: {
status: "partial",
retainedCount: 0,
omittedCount: null,
},
});
state.callableNodesById.set(callableId, node);
};
/** Collect one static import/export relationship for later composition. */
export const collectSemanticModuleLink = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): void => {
if (t.isImportDeclaration(node)) collectImports(node, state);
else if (t.isExportAllDeclaration(node))
addModuleLink(state, {
kind: "re-export",
specifier: node.source.value,
importedName: "*",
localName: null,
exportedName: "*",
location: range(node),
});
else if (t.isExportNamedDeclaration(node)) collectNamedExports(node, state);
else if (t.isExportDefaultDeclaration(node))
addModuleLink(state, {
kind: "export",
specifier: null,
importedName: null,
localName: defaultDeclarationName(node.declaration),
exportedName: "default",
callableId: semanticCallableIdForNode(node.declaration),
location: range(node),
});
else if (t.isVariableDeclarator(node)) collectRequireLink(node, state);
else if (t.isAssignmentExpression(node)) collectCommonJsExport(node, state);
};
/** Collect bounded lexical identifier references after definitions exist. */
export const collectSemanticReferences = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticReference[] => {
const output: JavaScriptSemanticReference[] = [];
const seen = new Set<string>();
traverseJavaScriptAst(program, {
enter: (node, parent, ancestors) => {
if (!t.isIdentifier(node) || parent === null) return;
const role = semanticIdentifierRole(node, parent, ancestors);
if (role === null) return;
// A compound assignment or update reads before it writes; emit both so
// reference consumers see the read they actually execute.
const roles =
role === "write" && semanticReadsBeforeWrite(node, parent)
? (["read", "write"] as const)
: ([role] as const);
for (const resolvedRole of roles) {
const key = `${String(node.start)}:${resolvedRole}:${node.name}`;
if (seen.has(key)) continue;
seen.add(key);
const binding = resolveSemanticBindingState(state, node, node.name);
const blocked =
binding === undefined &&
semanticResolutionBlocked(state, node, node.name);
output.push({
name: node.name,
role: resolvedRole,
location: range(node),
bindingId: binding?.bindingId ?? null,
resolution:
binding !== undefined
? "resolved"
: blocked
? "unknown"
: "unbound",
});
}
},
});
return output;
};
/** Freeze collected scopes into deterministic IR order. */
export const immutableSemanticScopes = (
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticScope[] =>
state.scopes.map((scope) => ({
scopeId: scope.scopeId,
parentScopeId: scope.parentScopeId,
kind: scope.kind,
location: scope.location,
bindingsComplete: scope.bindingsComplete,
bindingIds: [...scope.bindings.values()]
.map(({ bindingId }) => bindingId)
.sort(compareCodePoints),
}));
/** Evaluate and freeze bindings into deterministic IR order. */
export const immutableSemanticBindings = (
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBinding[] =>
[...state.bindingsById.values()]
.map((binding) => ({
bindingId: binding.bindingId,
scopeId: binding.scopeId,
name: binding.name,
kind: binding.kind,
mutable: binding.mutable,
definitions: binding.definitions,
value: evaluateSemanticBinding(binding, state),
provenance: evaluateSemanticProvenance(binding, state),
}))
.sort((left, right) => compareCodePoints(left.bindingId, right.bindingId));
/** Recover a literal require origin plus an optional member chain. */
const semanticModuleOrigin = (
node: t.Node | null | undefined,
projection: readonly (string | number | null)[],
state: JavaScriptSemanticAnalysisState,
): JavaScriptModuleOrigin | undefined => {
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
const nested = t.isNode(node.object)
? semanticModuleOrigin(node.object, projection, state)
: undefined;
const member = semanticStaticPropertyKey(node.property, node.computed);
return nested === undefined || member === null
? undefined
: { ...nested, importedPath: [...nested.importedPath, member] };
}
if (
!t.isCallExpression(node) ||
!t.isIdentifier(node.callee, { name: "require" })
)
return undefined;
if (
resolveSemanticBindingState(state, node.callee, "require") !== undefined ||
semanticResolutionBlocked(state, node.callee, "require")
)
return undefined;
const specifier = stringValue(node.arguments[0]);
return specifier === undefined || projection.includes(null)
? undefined
: {
specifier,
importedPath: projection.map((segment) => String(segment)),
};
};
export {
semanticStaticPropertyKey,
semanticStaticPropertyName,
} from "./javascriptAstValues.js";
const callableKind = (
node: t.Node,
): "function" | "class" | "method" | undefined => {
if (
t.isClassMethod(node) ||
t.isClassPrivateMethod(node) ||
t.isObjectMethod(node)
)
return "method";
if (t.isFunction(node)) return "function";
if (t.isClass(node)) return "class";
return undefined;
};
const callableName = (node: t.Node, parent: t.Node | null): string | null => {
if (
(t.isFunctionDeclaration(node) ||
t.isFunctionExpression(node) ||
t.isClassDeclaration(node) ||
t.isClassExpression(node)) &&
t.isIdentifier(node.id)
)
return node.id.name;
if (
t.isClassMethod(node) ||
t.isClassPrivateMethod(node) ||
t.isObjectMethod(node)
) {
if (t.isPrivateName(node.key)) return `#${node.key.id.name}`;
// `{[key]() {}}` names nothing statically; reading `key` off the key node
// would report the variable name as the method name. `{[""]() {}}` names
// the exact empty key, which is retained rather than replaced.
return (
semanticStaticPropertyKey(node.key, node.computed) ??
`[computed@${String(node.start ?? -1)}]`
);
}
if (
parent !== null &&
t.isVariableDeclarator(parent) &&
t.isIdentifier(parent.id)
)
return parent.id.name;
return null;
};
const collectImports = (
node: t.ImportDeclaration,
state: JavaScriptSemanticAnalysisState,
): void => {
if (node.specifiers.length === 0)
addModuleLink(state, {
kind: "import",
specifier: node.source.value,
importedName: null,
localName: null,
exportedName: null,
location: range(node),
});
for (const specifier of node.specifiers)
addModuleLink(state, {
kind: "import",
specifier: node.source.value,
importedName: t.isImportDefaultSpecifier(specifier)
? "default"
: t.isImportNamespaceSpecifier(specifier)
? "*"
: propertyName(specifier.imported),
localName: specifier.local.name,
exportedName: null,
location: range(specifier),
});
};
const collectNamedExports = (
node: t.ExportNamedDeclaration,
state: JavaScriptSemanticAnalysisState,
): void => {
if (node.declaration !== null && node.declaration !== undefined)
for (const localName of declarationNames(node.declaration))
addModuleLink(state, {
kind: "export",
specifier: null,
importedName: null,
localName,
exportedName: localName,
callableId: declarationCallableId(node.declaration, localName),
location: range(node.declaration),
});
for (const specifier of node.specifiers)
if (t.isExportSpecifier(specifier))
addModuleLink(state, {
kind: node.source == null ? "export" : "re-export",
specifier: node.source?.value ?? null,
importedName: propertyName(specifier.local),
localName: node.source == null ? propertyName(specifier.local) : null,
exportedName: propertyName(specifier.exported),
location: range(specifier),
});
};
const collectRequireLink = (
node: t.VariableDeclarator,
state: JavaScriptSemanticAnalysisState,
): void => {
const origin = semanticModuleOrigin(node.init, [], state);
if (origin === undefined) return;
for (const binding of requirePatternBindings(node.id, origin.importedPath))
addModuleLink(state, {
kind: "require",
specifier: origin.specifier,
importedName: binding.importedName,
localName: binding.localName,
exportedName: null,
location: range(node),
});
};
const requirePatternBindings = (
pattern: t.Node,
path: readonly string[],
): { readonly importedName: string; readonly localName: string }[] => {
if (t.isTSParameterProperty(pattern))
return requirePatternBindings(pattern.parameter, path);
if (t.isIdentifier(pattern))
return [{ importedName: path.at(-1) ?? "*", localName: pattern.name }];
if (t.isAssignmentPattern(pattern))
return requirePatternBindings(pattern.left, path);
if (t.isObjectPattern(pattern))
return pattern.properties.flatMap((property) => {
if (t.isRestElement(property)) return [];
const name = semanticStaticPropertyKey(property.key, property.computed);
return name === null
? []
: requirePatternBindings(property.value, [...path, name]);
});
if (t.isArrayPattern(pattern))
return pattern.elements.flatMap((element, index) =>
element === null
? []
: requirePatternBindings(element, [...path, String(index)]),
);
return [];
};
const collectCommonJsExport = (
node: t.AssignmentExpression,
state: JavaScriptSemanticAnalysisState,
): void => {
const exportedName = commonJsExportName(node.left, state);
if (exportedName === undefined) return;
const origin = semanticModuleOrigin(node.right, [], state);
addModuleLink(state, {
kind: "commonjs-export",
specifier: origin?.specifier ?? null,
importedName: origin?.importedPath.at(-1) ?? null,
localName: t.isIdentifier(node.right) ? node.right.name : null,
exportedName,
callableId: semanticCallableIdForNode(node.right),
location: range(node),
});
};
const addModuleLink = (
state: JavaScriptSemanticAnalysisState,
link: Omit<JavaScriptSemanticModuleLink, "callableId"> & {
readonly callableId?: string | null;
},
): void => {
state.moduleLinks.push({ ...link, callableId: link.callableId ?? null });
};
/** Deterministic callable identity shared by collection and return recovery. */
export const semanticCallableIdForNode = (node: t.Node): string | null => {
const kind = callableKind(node);
return kind === undefined
? null
: `callable:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
};
const declarationCallableId = (
declaration: t.Declaration,
localName: string,
): string | null => {
if (
(t.isFunctionDeclaration(declaration) ||
t.isClassDeclaration(declaration)) &&
declaration.id?.name === localName
)
return semanticCallableIdForNode(declaration);
if (!t.isVariableDeclaration(declaration)) return null;
const declarator = declaration.declarations.find(({ id }) =>
t.isIdentifier(id, { name: localName }),
);
return declarator?.init === null || declarator?.init === undefined
? null
: semanticCallableIdForNode(declarator.init);
};
/**
* True when writing `node` also reads it first: a compound assignment
* (`+=`, `||=`, …) or an update (`++`/`--`). A plain `=` writes only.
*
* One predicate serves both member operations and identifier references so the
* two can never disagree about what counts as a read-modify-write.
*/
export const semanticReadsBeforeWrite = (
node: t.Node,
parent: t.Node,
): boolean =>
(t.isAssignmentExpression(parent) &&
parent.left === node &&
parent.operator !== "=") ||
(t.isUpdateExpression(parent) && parent.argument === node);
/**
* Role of one identifier occurrence, given the node's ancestry.
*
* A binding inside a destructuring pattern has an ObjectProperty/ArrayPattern
* as its direct parent, so the immediate parent cannot tell a declaration
* (`const {a} = o`, `catch ({message})`) from an assignment target
* (`({a} = o)`, `for (a of list)`). Walking the ancestry to the nearest
* pattern-owning construct is what makes the distinction possible.
*/
export const semanticIdentifierRole = (
node: t.Identifier,
parent: t.Node,
ancestors: readonly t.Node[],
): JavaScriptSemanticReference["role"] | null => {
const patternAncestor = enclosingPatternAncestor(node, parent, ancestors);
if (patternAncestor !== null) {
if (isPatternOwnerDeclaration(patternAncestor)) return null;
return "write";
}
return semanticReferenceRole(node, parent);
};
/**
* The nearest ancestor that owns this identifier as a *bound* pattern slot, or
* null when the identifier is not being bound. A binding inside a pattern has
* an ObjectProperty/ArrayPattern parent, so the immediate parent cannot say
* whether the identifier declares a binding or is assigned to.
*
* Only the bound side counts: `{a = compute()}` binds `a` but merely *reads*
* `compute`, so the default-value side must not be mistaken for a binding.
*/
const enclosingPatternAncestor = (
node: t.Identifier,
parent: t.Node,
ancestors: readonly t.Node[],
): t.Node | null => {
const chain = [...ancestors, parent];
for (let index = chain.length - 1; index >= 0; index -= 1) {
const ancestor = chain[index];
if (ancestor === undefined || !isPatternNode(ancestor)) continue;
if (!bindsIdentifier(ancestor, parent, node)) continue;
// Found the binding slot; now find what owns the pattern.
for (let owner = index - 1; owner >= 0; owner -= 1) {
const candidate = chain[owner];
if (candidate === undefined) continue;
if (
t.isAssignmentExpression(candidate) ||
t.isForInStatement(candidate) ||
t.isForOfStatement(candidate)
)
return candidate;
if (isPatternOwnerDeclaration(candidate)) return candidate;
}
return null;
}
return null;
};
/** True when `parent` places `node` in the bound slot of `pattern`. */
const bindsIdentifier = (
pattern: t.Node,
parent: t.Node,
node: t.Identifier,
): boolean => {
// The identifier sits directly in the pattern: `[b]`, `({b})`, `{b = 1}`.
if (parent === pattern) return patternContains(pattern, node);
if (t.isObjectPattern(pattern))
return (
t.isObjectProperty(parent) &&
(parent.value === node || (parent.shorthand && parent.key === node))
);
if (t.isArrayPattern(pattern))
return pattern.elements.some((element) => element === parent);
if (t.isAssignmentPattern(pattern)) return pattern.left === parent;
return t.isRestElement(pattern) && pattern.argument === parent;
};
const isPatternNode = (node: t.Node): boolean =>
t.isObjectPattern(node) ||
t.isArrayPattern(node) ||
t.isAssignmentPattern(node) ||
t.isRestElement(node);
const isPatternOwnerDeclaration = (node: t.Node): boolean =>
(t.isVariableDeclarator(node) && t.isPattern(node.id)) ||
(t.isFunction(node) &&
node.params.some((value): value is t.Pattern => t.isPattern(value))) ||
(t.isCatchClause(node) && node.param !== null && t.isPattern(node.param));
/** Classify one identifier occurrence consistently with semantic references. */
export const semanticReferenceRole = (
node: t.Identifier,
parent: t.Node,
): JavaScriptSemanticReference["role"] | null => {
if (isDeclarationIdentifier(node, parent) || isNonReferenceKey(node, parent))
return null;
if (
(t.isAssignmentExpression(parent) && parent.left === node) ||
t.isUpdateExpression(parent) ||
((t.isForInStatement(parent) || t.isForOfStatement(parent)) &&
parent.left === node)
)
return "write";
if (t.isExportSpecifier(parent) && parent.local === node) return "export";
return "read";
};
const isDeclarationIdentifier = (node: t.Identifier, parent: t.Node): boolean =>
(t.isVariableDeclarator(parent) && patternContains(parent.id, node)) ||
((t.isFunctionDeclaration(parent) || t.isFunctionExpression(parent)) &&
parent.id === node) ||
(t.isFunction(parent) &&
parent.params.some((value) => patternContains(value, node))) ||
((t.isClassDeclaration(parent) || t.isClassExpression(parent)) &&
parent.id === node) ||
(t.isImportSpecifier(parent) &&
(parent.local === node || parent.imported === node)) ||
(t.isImportDefaultSpecifier(parent) && parent.local === node) ||
(t.isImportNamespaceSpecifier(parent) && parent.local === node) ||
(t.isCatchClause(parent) && parent.param === node);
const isNonReferenceKey = (node: t.Identifier, parent: t.Node): boolean =>
((t.isMemberExpression(parent) || t.isOptionalMemberExpression(parent)) &&
parent.property === node &&
!parent.computed) ||
((t.isObjectProperty(parent) || t.isObjectMethod(parent)) &&
parent.key === node &&
!parent.computed &&
!(t.isObjectProperty(parent) && parent.shorthand)) ||
(t.isExportSpecifier(parent) && parent.exported === node) ||
t.isLabeledStatement(parent) ||
t.isBreakStatement(parent) ||
t.isContinueStatement(parent);
const patternNames = (pattern: t.Node): string[] => {
if (t.isTSParameterProperty(pattern)) return patternNames(pattern.parameter);
if (t.isIdentifier(pattern)) return [pattern.name];
if (t.isAssignmentPattern(pattern)) return patternNames(pattern.left);
if (t.isRestElement(pattern)) return patternNames(pattern.argument);
if (t.isObjectPattern(pattern))
return pattern.properties.flatMap((property) =>
t.isRestElement(property)
? patternNames(property.argument)
: patternNames(property.value),
);
if (t.isArrayPattern(pattern))
return pattern.elements.flatMap((element) =>
element === null ? [] : patternNames(element),
);
return [];
};
const patternContains = (pattern: t.Node, target: t.Identifier): boolean =>
pattern === target ||
(t.isAssignmentPattern(pattern) && patternContains(pattern.left, target)) ||
(t.isRestElement(pattern) && patternContains(pattern.argument, target)) ||
(t.isObjectPattern(pattern) &&
pattern.properties.some((property) =>
t.isRestElement(property)
? patternContains(property.argument, target)
: patternContains(property.value, target),
)) ||
(t.isArrayPattern(pattern) &&
pattern.elements.some(
(element) => element !== null && patternContains(element, target),
));
const declarationNames = (declaration: t.Declaration): string[] => {
if (t.isVariableDeclaration(declaration))
return declaration.declarations.flatMap(({ id }) => patternNames(id));
if (
(t.isFunctionDeclaration(declaration) ||
t.isClassDeclaration(declaration)) &&
t.isIdentifier(declaration.id)
)
return [declaration.id.name];
return [];
};
const defaultDeclarationName = (
declaration: t.ExportDefaultDeclaration["declaration"],
): string | null =>
(t.isFunctionDeclaration(declaration) || t.isClassDeclaration(declaration)) &&
t.isIdentifier(declaration.id)
? declaration.id.name
: null;
const commonJsExportName = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): string | undefined => {
if (isUnshadowedGlobal(node, state, "exports")) return "default";
if (!t.isMemberExpression(node) && !t.isOptionalMemberExpression(node))
return undefined;
const key = semanticStaticPropertyKey(node.property, node.computed);
// `exports[key]`/`module.exports[key]` assign an export whose name is not
// knowable. Report the wildcard rather than the variable name, and never
// collapse it into `default`, which would claim a real default export.
if (isUnshadowedGlobal(node.object, state, "exports"))
return key === null ? "*" : key || "*";
if (
t.isMemberExpression(node.object) &&
isUnshadowedGlobal(node.object.object, state, "module") &&
semanticStaticPropertyKey(node.object.property, node.object.computed) ===
"exports"
)
return key === null ? "*" : key || "default";
if (
isUnshadowedGlobal(node.object, state, "module") &&
semanticStaticPropertyKey(node.property, node.computed) === "exports"
)
return "default";
return undefined;
};
@@ -0,0 +1,476 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticPromiseOperation,
} from "./javascriptSemanticIr.js";
import {
semanticCallableIdForNode,
semanticStaticPropertyName,
} from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
} from "./javascriptSemanticState.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
import { range, sourceRangesEqual } from "./javascriptStaticAnalysisHelpers.js";
import {
assignedSemanticResultBindings,
dataEffectMemberCallee,
scalarAssignedResultBinding,
} from "./javascriptSemanticDataEffectHelpers.js";
type PromiseMethod = JavaScriptSemanticPromiseOperation["method"];
type PromiseKind = JavaScriptSemanticPromiseOperation["kind"];
interface PromiseCandidate {
readonly node: t.Node;
readonly kind: PromiseKind;
readonly method: PromiseMethod;
readonly promiseId: string;
readonly ownerCallableId: string | null;
readonly ancestors: readonly t.Node[];
}
interface PromiseResolution {
readonly promiseIds: readonly string[];
readonly status: JavaScriptSemanticPromiseOperation["sourceResolution"];
}
interface PromiseOwnership {
readonly ownership: JavaScriptSemanticPromiseOperation["ownership"];
readonly ownerBindingId: string | null;
readonly returnSiteId: string | null;
}
interface PromiseExpressionResolutionContext {
readonly current: PromiseCandidate;
readonly candidateByNode: WeakMap<t.Node, PromiseCandidate>;
readonly state: JavaScriptSemanticAnalysisState;
readonly seenBindings: ReadonlySet<string>;
}
interface PromiseOwnershipContext {
readonly candidate: PromiseCandidate;
readonly candidateByNode: WeakMap<t.Node, PromiseCandidate>;
readonly state: JavaScriptSemanticAnalysisState;
readonly callables: readonly JavaScriptSemanticCallable[];
}
/** Recover explicit Promise construction, chaining, aggregation, and ownership. */
export const collectJavaScriptSemanticPromises = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticPromiseOperation[] => {
const candidates = collectCandidates(program, state, callables);
const candidateByNode = new WeakMap<t.Node, PromiseCandidate>();
for (const candidate of candidates)
candidateByNode.set(candidate.node, candidate);
return candidates.map((candidate) => {
const ownership = promiseOwnership(
candidate,
candidateByNode,
state,
callables,
);
const sources = promiseSources(candidate, candidateByNode, state);
return {
promiseId: candidate.promiseId,
kind: candidate.kind,
method: candidate.method,
location: range(candidate.node),
ownerCallableId: candidate.ownerCallableId,
...ownership,
sourcePromiseIds: [...new Set(sources.promiseIds)].sort(
compareCodePoints,
),
sourceResolution: sources.status,
};
});
};
const collectCandidates = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): PromiseCandidate[] => {
const output: PromiseCandidate[] = [];
const admittedCallables = new Set(
callables.map(({ callableId }) => callableId),
);
const callableStack: string[] = [];
const ancestors: t.Node[] = [];
traverseJavaScriptAst(program, {
enter: (node) => {
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && admittedCallables.has(callableId))
callableStack.push(callableId);
const details = promiseCandidateDetails(node, state);
if (details !== null) {
output.push({
node,
...details,
promiseId: semanticPromiseId(details.kind, node),
ownerCallableId: callableStack.at(-1) ?? null,
ancestors: [...ancestors],
});
}
ancestors.push(node);
},
exit: (node) => {
ancestors.pop();
const callableId = semanticCallableIdForNode(node);
if (callableId !== null && callableStack.at(-1) === callableId)
callableStack.pop();
},
});
return output;
};
const promiseCandidateDetails = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): Pick<PromiseCandidate, "kind" | "method"> | null => {
if (
t.isNewExpression(node) &&
t.isIdentifier(node.callee, { name: "Promise" }) &&
isUnshadowedGlobalPromise(node.callee, state)
)
return { kind: "constructor", method: "new" };
if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
const member = dataEffectMemberCallee(node);
if (member === null) return null;
const method = semanticStaticPropertyName(member.property, member.computed);
if (
t.isIdentifier(member.object, { name: "Promise" }) &&
isUnshadowedGlobalPromise(member.object, state)
) {
if (method === "all" || method === "allSettled")
return { kind: "aggregate", method };
if (method === "resolve" || method === "reject")
return { kind: "static", method };
}
if (method === "then" || method === "catch" || method === "finally")
return { kind: "chain", method };
}
if (t.isAwaitExpression(node) && !isPromiseProducer(node.argument, state))
return { kind: "awaited-expression", method: "await" };
return null;
};
const isUnshadowedGlobalPromise = (
node: t.Identifier,
state: JavaScriptSemanticAnalysisState,
): boolean =>
resolveSemanticBindingState(state, node, "Promise") === undefined &&
!semanticResolutionBlocked(state, node, "Promise");
const isPromiseProducer = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): boolean => promiseCandidateDetails(unwrapExpression(node), state) !== null;
const semanticPromiseId = (kind: PromiseKind, node: t.Node): string =>
`promise:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
const promiseOwnership = (
candidate: PromiseCandidate,
candidateByNode: WeakMap<t.Node, PromiseCandidate>,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): PromiseOwnership => {
if (candidate.kind === "awaited-expression") return emptyOwnership("awaited");
const context: PromiseOwnershipContext = {
candidate,
candidateByNode,
state,
callables,
};
for (let index = candidate.ancestors.length - 1; index >= 0; index -= 1) {
const ancestor = candidate.ancestors[index];
if (ancestor === undefined) continue;
const ownership = ownershipAtAncestor(ancestor, context);
if (ownership === "boundary") break;
if (ownership !== null) return ownership;
}
return emptyOwnership("unknown");
};
const ownershipAtAncestor = (
ancestor: t.Node,
context: PromiseOwnershipContext,
): PromiseOwnership | "boundary" | null => {
const { candidate, candidateByNode, state, callables } = context;
if (t.isAwaitExpression(ancestor))
return unwrapExpression(ancestor.argument) === candidate.node
? emptyOwnership("awaited")
: "boundary";
const outer = candidateByNode.get(ancestor);
if (
outer !== undefined &&
outer.ownerCallableId === candidate.ownerCallableId &&
outerConsumesCandidate(outer, candidate)
)
return outer.kind === "chain"
? emptyOwnership("chained")
: emptyOwnership("aggregated");
if (isUnmodeledCall(ancestor, outer)) return "boundary";
const assigned = assignedPromiseBinding(ancestor, candidate.node, state);
if (assigned !== undefined)
return {
ownership: "assigned",
ownerBindingId: assigned,
returnSiteId: null,
};
if (t.isReturnStatement(ancestor)) {
if (
ancestor.argument == null ||
unwrapExpression(ancestor.argument) !== candidate.node
)
return "boundary";
return returnedPromiseOwnership(
candidate.ownerCallableId,
range(ancestor),
callables,
);
}
if (t.isExpressionStatement(ancestor))
return unwrapExpression(ancestor.expression) === candidate.node
? emptyOwnership("detached")
: "boundary";
const callableId = semanticCallableIdForNode(ancestor);
if (callableId === null || callableId !== candidate.ownerCallableId)
return null;
return t.isArrowFunctionExpression(ancestor) &&
unwrapExpression(ancestor.body) === candidate.node
? returnedPromiseOwnership(
candidate.ownerCallableId,
range(ancestor.body),
callables,
)
: "boundary";
};
const isUnmodeledCall = (
node: t.Node,
candidate: PromiseCandidate | undefined,
): boolean =>
candidate === undefined &&
(t.isCallExpression(node) ||
t.isOptionalCallExpression(node) ||
t.isNewExpression(node));
const assignedPromiseBinding = (
ancestor: t.Node,
candidate: t.Node,
state: JavaScriptSemanticAnalysisState,
): string | null | undefined => {
if (!t.isVariableDeclarator(ancestor) && !t.isAssignmentExpression(ancestor))
return undefined;
const source = t.isVariableDeclarator(ancestor)
? ancestor.init
: ancestor.right;
if (source == null) return undefined;
if (unwrapExpression(source) !== candidate) return undefined;
return scalarAssignedResultBinding(
assignedSemanticResultBindings(source, [ancestor], state),
);
};
const returnedPromiseOwnership = (
callableId: string | null,
location: JavaScriptSemanticPromiseOperation["location"],
callables: readonly JavaScriptSemanticCallable[],
): PromiseOwnership => ({
ownership: "returned",
ownerBindingId: null,
returnSiteId: matchingReturnSite(callableId, location, callables),
});
const outerConsumesCandidate = (
outer: PromiseCandidate,
candidate: PromiseCandidate,
): boolean => {
if (
outer.kind === "chain" &&
(t.isCallExpression(outer.node) || t.isOptionalCallExpression(outer.node))
) {
const member = dataEffectMemberCallee(outer.node);
return (
member !== null && unwrapExpression(member.object) === candidate.node
);
}
if (
outer.kind === "aggregate" &&
(t.isCallExpression(outer.node) || t.isOptionalCallExpression(outer.node))
) {
const input = outer.node.arguments[0];
return (
t.isArrayExpression(input) &&
input.elements.some(
(element) =>
element !== null &&
!t.isSpreadElement(element) &&
unwrapExpression(element) === candidate.node,
)
);
}
return false;
};
const emptyOwnership = (
ownership: JavaScriptSemanticPromiseOperation["ownership"],
): PromiseOwnership => ({
ownership,
ownerBindingId: null,
returnSiteId: null,
});
const matchingReturnSite = (
callableId: string | null,
location: JavaScriptSemanticPromiseOperation["location"],
callables: readonly JavaScriptSemanticCallable[],
): string | null =>
callables
.find(({ callableId: candidate }) => candidate === callableId)
?.returnSites.find(({ location: candidate }) =>
sourceRangesEqual(candidate, location),
)?.returnSiteId ?? null;
const promiseSources = (
candidate: PromiseCandidate,
candidateByNode: WeakMap<t.Node, PromiseCandidate>,
state: JavaScriptSemanticAnalysisState,
): PromiseResolution => {
if (candidate.kind === "chain") {
const member =
t.isCallExpression(candidate.node) ||
t.isOptionalCallExpression(candidate.node)
? dataEffectMemberCallee(candidate.node)
: null;
return member === null
? unresolvedPromise()
: resolvePromiseExpression(
member.object,
promiseResolutionContext(candidate, candidateByNode, state),
);
}
if (candidate.kind === "aggregate")
return aggregateSources(candidate, candidateByNode, state);
if (candidate.kind === "awaited-expression")
return t.isAwaitExpression(candidate.node)
? resolvePromiseExpression(
candidate.node.argument,
promiseResolutionContext(candidate, candidateByNode, state),
)
: unresolvedPromise();
return { promiseIds: [], status: "complete" };
};
const aggregateSources = (
candidate: PromiseCandidate,
candidateByNode: WeakMap<t.Node, PromiseCandidate>,
state: JavaScriptSemanticAnalysisState,
): PromiseResolution => {
if (
!t.isCallExpression(candidate.node) &&
!t.isOptionalCallExpression(candidate.node)
)
return unresolvedPromise();
const input = candidate.node.arguments[0];
if (!t.isArrayExpression(input)) return unresolvedPromise();
const resolutions = input.elements.map((element) => {
if (element === null) return completePromise();
if (t.isSpreadElement(element)) return unresolvedPromise();
if (isObviouslyNonPromise(element)) return completePromise();
return resolvePromiseExpression(
element,
promiseResolutionContext(candidate, candidateByNode, state),
);
});
return combinePromiseResolutions(resolutions);
};
const resolvePromiseExpression = (
rawNode: t.Node,
context: PromiseExpressionResolutionContext,
): PromiseResolution => {
const { current, candidateByNode, state, seenBindings } = context;
const node = unwrapExpression(rawNode);
const direct = candidateByNode.get(node);
if (direct !== undefined && direct.promiseId !== current.promiseId)
return { promiseIds: [direct.promiseId], status: "complete" };
if (!t.isIdentifier(node)) return unresolvedPromise();
const binding = resolveSemanticBindingState(state, node, node.name);
if (
binding === undefined ||
binding.mutable ||
binding.initializers.length !== 1 ||
seenBindings.has(binding.bindingId)
)
return unresolvedPromise();
const initializer = binding.initializers[0];
if (initializer === undefined || initializer.projection.length > 0)
return unresolvedPromise();
const nestedSeen = new Set(seenBindings);
nestedSeen.add(binding.bindingId);
return resolvePromiseExpression(initializer.node, {
...context,
seenBindings: nestedSeen,
});
};
const promiseResolutionContext = (
current: PromiseCandidate,
candidateByNode: WeakMap<t.Node, PromiseCandidate>,
state: JavaScriptSemanticAnalysisState,
): PromiseExpressionResolutionContext => ({
current,
candidateByNode,
state,
seenBindings: new Set(),
});
const unwrapExpression = (node: t.Node): t.Node => {
if (
t.isParenthesizedExpression(node) ||
t.isTSAsExpression(node) ||
t.isTSSatisfiesExpression(node) ||
t.isTSNonNullExpression(node) ||
t.isTypeCastExpression(node)
)
return unwrapExpression(node.expression);
return node;
};
const combinePromiseResolutions = (
resolutions: readonly PromiseResolution[],
): PromiseResolution => ({
promiseIds: resolutions.flatMap(({ promiseIds }) => promiseIds),
status: resolutions.some(({ status }) => status === "unresolved")
? resolutions.some(({ status }) => status === "complete")
? "partial"
: "unresolved"
: resolutions.some(({ status }) => status === "partial")
? "partial"
: "complete",
});
const completePromise = (): PromiseResolution => ({
promiseIds: [],
status: "complete",
});
const unresolvedPromise = (): PromiseResolution => ({
promiseIds: [],
status: "unresolved",
});
const isObviouslyNonPromise = (node: t.Node): boolean =>
t.isLiteral(node) ||
t.isObjectExpression(node) ||
t.isFunction(node) ||
t.isClassExpression(node);
@@ -0,0 +1,64 @@
import type {
JavaScriptBindingProvenance,
JavaScriptModuleOrigin,
JavaScriptSemanticPrimitive,
} from "./javascriptSemanticIr.js";
import { compareCodePoints } from "../canonicalOrdering.js";
/** Construct exact local provenance without inventing module origins. */
export const semanticLocalProvenance = (): JavaScriptBindingProvenance => ({
status: "local",
origins: [],
reason: null,
});
/** Construct an unresolved provenance outcome with an actionable reason. */
export const semanticUnresolvedProvenance = (
status: "unknown" | "cycle",
reason: string,
): JavaScriptBindingProvenance => ({ status, origins: [], reason });
/** Construct ambiguous provenance while retaining every origin. */
export const semanticAmbiguousProvenance = (
origins: readonly JavaScriptModuleOrigin[],
reason: string,
): JavaScriptBindingProvenance => ({ status: "ambiguous", origins, reason });
/** Normalize exact module origins into one provenance classification. */
export const semanticOriginsProvenance = (
origins: readonly JavaScriptModuleOrigin[],
): JavaScriptBindingProvenance => {
const unique = uniqueSemanticOrigins(origins);
const origin = unique[0];
return unique.length === 1 && origin !== undefined
? { status: "module", origins: [origin], reason: null }
: semanticAmbiguousProvenance(unique, "Multiple module origins.");
};
/** Deduplicate and canonically order module origins. */
export const uniqueSemanticOrigins = (
origins: readonly JavaScriptModuleOrigin[],
): JavaScriptModuleOrigin[] =>
[
...new Map(
origins.map((origin) => [semanticOriginKey(origin), origin]),
).values(),
].sort((left, right) =>
compareCodePoints(semanticOriginKey(left), semanticOriginKey(right)),
);
const semanticOriginKey = (origin: JavaScriptModuleOrigin): string =>
`${origin.specifier}\0${origin.importedPath.join("\0")}`;
/** Canonically distinguish primitive values across type boundaries. */
export const semanticPrimitiveKey = (
value: JavaScriptSemanticPrimitive,
): string =>
`${value === null ? "null" : typeof value}:${JSON.stringify(value)}`;
/** Match namespace paths only after the caller has identified a Node built-in. */
export const semanticBuiltinNamespacePath = (
importedPath: readonly string[],
): boolean =>
importedPath.length === 0 ||
(importedPath.length === 1 && importedPath[0] === "default");
@@ -0,0 +1,312 @@
import type {
JavaScriptSemanticGraph,
JavaScriptSemanticGraphNode,
JavaScriptSemanticGraphRelation,
} from "./javascriptSemanticGraph.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import type { JavaScriptSemanticGraphUnknown } from "./javascriptSemanticGraphSchemas.js";
import { isJavaScriptSemanticOwnershipRelation as ownershipRelation } from "./javascriptSemanticQueryRelations.js";
import {
javaScriptSemanticQueryInputSchema,
javaScriptSemanticQueryResultSchema,
type JavaScriptSemanticQueryInput,
type JavaScriptSemanticQueryResult,
} from "./javascriptSemanticQuerySchemas.js";
import { assessJavaScriptSemanticQuery } from "./javascriptSemanticQueryAssessment.js";
import {
javaScriptSemanticQueryIdentifier as queryIdentifier,
resolveJavaScriptSemanticQuerySeeds as resolveSeeds,
} from "./javascriptSemanticQueryIdentity.js";
interface TraversalEntry {
readonly relation: JavaScriptSemanticGraphRelation;
readonly nextNodeId: string;
}
interface Traversal {
readonly nodeIds: Set<string>;
readonly relationIds: Set<string>;
readonly functionIds: Set<string>;
readonly modules: Set<string>;
}
interface SeedAdmission {
readonly nodeIds: string[];
}
interface QueryResult {
readonly retainedNodes: JavaScriptSemanticGraphNode[];
readonly retainedRelations: JavaScriptSemanticGraphRelation[];
}
/** Run one deterministic traversal over a verified semantic graph. */
export const queryJavaScriptSemanticGraph = (
graph: JavaScriptSemanticGraph,
rawInput: unknown,
): JavaScriptSemanticQueryResult => {
const input = javaScriptSemanticQueryInputSchema.parse(rawInput);
const queryId = queryIdentifier(graph, input);
const seeds = resolveSeeds(graph, input);
const admission = admitSeeds(graph, seeds);
const retainedSeeds = admission.nodeIds;
const adjacency = buildAdjacency(graph.relations, input);
const traversal = traverse(graph, retainedSeeds, adjacency);
const result = createQueryResult(graph, traversal);
const allRelevantUnknowns = relevantUnknownFrontiers(
graph,
traversal.nodeIds,
input,
);
const relevantUnknowns = allRelevantUnknowns;
const candidateRelations = relevantCandidateRelationCount(
graph,
traversal.nodeIds,
input,
);
const expectedMatches = expectedMatchesFor(
result.retainedNodes,
result.retainedRelations,
input,
);
const assessment = assessJavaScriptSemanticQuery({
graph,
totalSeeds: seeds.length,
expectedMatches: expectedMatches.length,
hasExpectation: input.expected !== null,
unknowns: relevantUnknowns,
candidateRelations,
});
return javaScriptSemanticQueryResultSchema.parse({
query_id: queryId,
source_graph_id: graph.graph_id,
seed: input.seed,
direction: input.direction,
status: assessment.status,
seed_node_ids: retainedSeeds,
nodes: result.retainedNodes,
relations: result.retainedRelations,
unknowns: relevantUnknowns,
expected_match_node_ids: expectedMatches.map(({ node_id }) => node_id),
summary: {
total_seed_matches: seeds.length,
traversed_nodes: traversal.nodeIds.size,
traversed_relations: traversal.relationIds.size,
traversed_functions: traversal.functionIds.size,
traversed_modules: traversal.modules.size,
relevant_unknowns: allRelevantUnknowns.length,
},
coverage: assessment.coverage,
limitations: assessment.limitations,
});
};
const createQueryResult = (
graph: JavaScriptSemanticGraph,
traversal: Traversal,
): QueryResult => {
const retainedNodes = graph.nodes.filter(({ node_id }) =>
traversal.nodeIds.has(node_id),
);
const retainedRelations = graph.relations.filter(({ relation_id }) =>
traversal.relationIds.has(relation_id),
);
return { retainedNodes, retainedRelations };
};
const admitSeeds = (
graph: JavaScriptSemanticGraph,
seeds: readonly string[],
): SeedAdmission => {
const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
const retained: string[] = [];
for (const nodeId of seeds) {
const node = nodes.get(nodeId);
if (node === undefined) continue;
retained.push(nodeId);
}
return { nodeIds: retained };
};
const buildAdjacency = (
relations: readonly JavaScriptSemanticGraphRelation[],
input: JavaScriptSemanticQueryInput,
): ReadonlyMap<string, TraversalEntry[]> => {
const adjacency = new Map<string, TraversalEntry[]>();
const allowed =
input.allowed_relations === undefined
? null
: new Set(input.allowed_relations);
for (const relation of relations) {
if (allowed !== null && !allowed.has(relation.relation)) continue;
if (
relation.resolution === "candidate" &&
!input.include_ambiguous_dynamic_edges
)
continue;
addDirectedEntries(adjacency, relation, input.direction);
}
for (const entries of adjacency.values())
entries.sort((left, right) =>
compareCodePoints(
`${left.relation.relation_id}\0${left.nextNodeId}`,
`${right.relation.relation_id}\0${right.nextNodeId}`,
),
);
return adjacency;
};
const addDirectedEntries = (
adjacency: Map<string, TraversalEntry[]>,
relation: JavaScriptSemanticGraphRelation,
direction: JavaScriptSemanticQueryInput["direction"],
): void => {
if (direction === "callers") {
if (relation.relation === "calls")
addEntry(
adjacency,
relation.target_node_id,
relation.source_node_id,
relation,
);
return;
}
if (direction === "ownership") {
if (!ownershipRelation(relation.relation)) return;
addEntry(
adjacency,
relation.source_node_id,
relation.target_node_id,
relation,
);
addEntry(
adjacency,
relation.target_node_id,
relation.source_node_id,
relation,
);
return;
}
if (direction === "backward-provenance")
addEntry(
adjacency,
relation.target_node_id,
relation.source_node_id,
relation,
);
else
addEntry(
adjacency,
relation.source_node_id,
relation.target_node_id,
relation,
);
};
const addEntry = (
adjacency: Map<string, TraversalEntry[]>,
from: string,
nextNodeId: string,
relation: JavaScriptSemanticGraphRelation,
): void => {
const entries = adjacency.get(from) ?? [];
entries.push({ relation, nextNodeId });
adjacency.set(from, entries);
};
const traverse = (
graph: JavaScriptSemanticGraph,
seeds: readonly string[],
adjacency: ReadonlyMap<string, TraversalEntry[]>,
): Traversal => {
const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
const nodeIds = new Set(seeds);
const relationIds = new Set<string>();
const functionIds = new Set<string>();
const modules = new Set<string>();
const queue = [...nodeIds];
for (const nodeId of nodeIds)
retainOwners(nodes.get(nodeId), functionIds, modules);
for (let offset = 0; offset < queue.length; offset += 1) {
const current = queue[offset];
if (current === undefined) continue;
for (const entry of adjacency.get(current) ?? []) {
relationIds.add(entry.relation.relation_id);
if (nodeIds.has(entry.nextNodeId)) continue;
const node = nodes.get(entry.nextNodeId);
if (node === undefined) continue;
nodeIds.add(entry.nextNodeId);
retainOwners(node, functionIds, modules);
queue.push(entry.nextNodeId);
}
}
return {
nodeIds,
relationIds,
functionIds,
modules,
};
};
const retainOwners = (
node: JavaScriptSemanticGraphNode | undefined,
functions: Set<string>,
modules: Set<string>,
): void => {
if (node === undefined) return;
const functionId =
node.kind === "function" ? node.node_id : node.function_node_id;
if (functionId !== null) functions.add(functionId);
modules.add(node.identity.module_path);
};
const relevantUnknownFrontiers = (
graph: JavaScriptSemanticGraph,
nodeIds: ReadonlySet<string>,
input: JavaScriptSemanticQueryInput,
): JavaScriptSemanticGraphUnknown[] => {
const allowed =
input.allowed_relations === undefined
? null
: new Set(input.allowed_relations);
return graph.unknowns.filter(
(unknown) =>
(unknown.node_id === null || nodeIds.has(unknown.node_id)) &&
(allowed === null ||
unknown.relation_kinds.some((relation) => allowed.has(relation))),
);
};
const relevantCandidateRelationCount = (
graph: JavaScriptSemanticGraph,
nodeIds: ReadonlySet<string>,
input: JavaScriptSemanticQueryInput,
): number => {
const adjacency = buildAdjacency(
graph.relations.filter(({ resolution }) => resolution === "candidate"),
{ ...input, include_ambiguous_dynamic_edges: true },
);
const relevant = new Set<string>();
for (const nodeId of nodeIds)
for (const { relation } of adjacency.get(nodeId) ?? [])
relevant.add(relation.relation_id);
return relevant.size;
};
const expectedMatchesFor = (
nodes: readonly JavaScriptSemanticGraphNode[],
relations: readonly JavaScriptSemanticGraphRelation[],
input: JavaScriptSemanticQueryInput,
): JavaScriptSemanticGraphNode[] => {
if (input.expected === null) return [];
const classes = new Set(input.expected.classes);
const connected = new Set(
relations.map((relation) =>
input.expected?.role === "source"
? relation.target_node_id
: relation.source_node_id,
),
);
return nodes.filter(
({ kind, node_id }) => classes.has(kind) && !connected.has(node_id),
);
};
@@ -0,0 +1,79 @@
import { uniqueSorted } from "../canonicalOrdering.js";
import type { JavaScriptSemanticGraph } from "./javascriptSemanticGraph.js";
import type { JavaScriptSemanticGraphUnknown } from "./javascriptSemanticGraphSchemas.js";
import type { JavaScriptSemanticQueryResult } from "./javascriptSemanticQuerySchemas.js";
/** Inputs needed to classify one completed semantic traversal. */
export interface JavaScriptSemanticQueryAssessmentInput {
readonly graph: JavaScriptSemanticGraph;
readonly totalSeeds: number;
readonly expectedMatches: number;
readonly hasExpectation: boolean;
readonly unknowns: readonly JavaScriptSemanticGraphUnknown[];
readonly candidateRelations: number;
}
/** Status, coverage, and limitations derived from one traversal. */
export interface JavaScriptSemanticQueryAssessment {
readonly status: JavaScriptSemanticQueryResult["status"];
readonly coverage: JavaScriptSemanticQueryResult["coverage"];
readonly limitations: string[];
}
/** Classify a complete semantic traversal without promoting unknowns to absence. */
export const assessJavaScriptSemanticQuery = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryAssessment => ({
status: queryStatus(input),
coverage: queryCoverage(input),
limitations: queryLimitations(input),
});
const queryCoverage = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryResult["coverage"] => ({
status:
input.graph.coverage.status === "unavailable"
? "unavailable"
: input.unknowns.length > 0 ||
input.candidateRelations > 0 ||
input.graph.coverage.status !== "complete" ||
input.graph.coverage.truncated
? "partial"
: "complete",
});
const queryStatus = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryResult["status"] => {
if (input.graph.coverage.status === "unavailable") return "unsupported";
if (input.candidateRelations > 0) return "ambiguous";
if (
input.totalSeeds === 0 ||
(input.hasExpectation && input.expectedMatches === 0)
)
return input.unknowns.length > 0 ||
input.graph.coverage.status !== "complete" ||
input.graph.coverage.truncated
? "partial"
: "no-match";
return input.totalSeeds > 1 ? "ambiguous" : "found";
};
const queryLimitations = (
input: JavaScriptSemanticQueryAssessmentInput,
): string[] =>
uniqueSorted([
"Semantic graph reachability is a static inference and does not prove runtime execution.",
...input.graph.limitations,
...(input.unknowns.length === 0
? []
: [
"Relevant dynamic, unsupported, incomplete, or ambiguous semantics remain unknown.",
]),
...(input.candidateRelations === 0
? []
: [
"Candidate relations remain ambiguous and do not establish a resolved semantic path.",
]),
]);
@@ -0,0 +1,100 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import type {
JavaScriptSemanticGraph,
JavaScriptSemanticGraphNode,
} from "./javascriptSemanticGraph.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import type { JavaScriptSemanticQueryInput } from "./javascriptSemanticQuerySchemas.js";
/** Canonical JSON used by semantic query commitments and ordering. */
export const canonicalJavaScriptSemanticQueryJson = (
value: unknown,
): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError(
"JavaScript semantic query could not canonicalize data",
);
return encoded;
};
const digest = (value: unknown): string =>
createHash("sha256")
.update(canonicalJavaScriptSemanticQueryJson(value))
.digest("hex");
/** Derive the stable identity for one graph-bound query. */
export const javaScriptSemanticQueryIdentifier = (
graph: JavaScriptSemanticGraph,
input: JavaScriptSemanticQueryInput,
): string => {
const semantic = input;
return `jsrq_${digest({
source_graph_id: graph.graph_id,
...semantic,
allowed_relations:
semantic.allowed_relations === undefined
? undefined
: uniqueSorted(semantic.allowed_relations),
expected:
semantic.expected === null
? null
: {
...semantic.expected,
classes: uniqueSorted(semantic.expected.classes),
},
})}`;
};
/** Resolve deterministic seed candidates without applying traversal limits. */
export const resolveJavaScriptSemanticQuerySeeds = (
graph: JavaScriptSemanticGraph,
input: JavaScriptSemanticQueryInput,
): string[] => {
const fingerprintFunctions = new Set(
input.seed.kind === "function"
? graph.fingerprints
.filter(
({ fingerprint_sha256 }) =>
input.seed.kind === "function" &&
fingerprint_sha256 === input.seed.fingerprint_sha256,
)
.map(({ function_node_id }) => function_node_id)
: [],
);
return graph.nodes
.filter((node) => seedMatches(node, input, fingerprintFunctions))
.map(({ node_id }) => node_id)
.sort(compareCodePoints);
};
const seedMatches = (
node: JavaScriptSemanticGraphNode,
input: JavaScriptSemanticQueryInput,
fingerprintFunctions: ReadonlySet<string>,
): boolean => {
const seed = input.seed;
if (seed.kind === "semantic-node") return node.node_id === seed.node_id;
if (seed.kind === "application-node")
return node.application_node_ids.includes(seed.node_id);
if (seed.kind === "function") return fingerprintFunctions.has(node.node_id);
if (seed.kind === "literal")
return (
node.kind === "literal" &&
canonicalJavaScriptSemanticQueryJson(node.properties.value) ===
canonicalJavaScriptSemanticQueryJson(seed.value)
);
if (seed.kind === "property")
return node.kind === "property-slot" && node.properties.name === seed.name;
if (seed.kind === "endpoint")
return node.kind === "request" && node.properties.endpoint === seed.value;
if (seed.kind === "event")
return (
["event", "listener"].includes(node.kind) &&
node.properties.event_name === seed.name
);
return node.kind === "boundary" && node.properties.field === seed.field;
};
@@ -0,0 +1,22 @@
import type { JavaScriptSemanticGraphRelation } from "./javascriptSemanticGraph.js";
const OWNERSHIP_RELATIONS = new Set<
JavaScriptSemanticGraphRelation["relation"]
>([
"acquires",
"aggregates",
"awaits",
"chains",
"connects-stdio",
"creates-promise",
"detaches-task",
"owns",
"releases",
"returns-task",
"spawns",
]);
/** Whether one relation participates in bidirectional ownership traversal. */
export const isJavaScriptSemanticOwnershipRelation = (
relation: JavaScriptSemanticGraphRelation["relation"],
): boolean => OWNERSHIP_RELATIONS.has(relation);
@@ -0,0 +1,66 @@
import { expect, it } from "vitest";
import {
javaScriptSemanticQueryInputSchema,
javaScriptSemanticQueryResultSchema,
} from "./javascriptSemanticQuerySchemas.js";
it("accepts long selectors and complete relation and class selections", () => {
const longText = "x".repeat(16_385);
const result = javaScriptSemanticQueryInputSchema.parse({
seed: { kind: "endpoint", value: longText },
direction: "forward-influence",
allowed_relations: Array(2).fill("calls"),
expected: {
role: "sink",
classes: Array(25).fill("module"),
},
});
expect(result.seed).toEqual({ kind: "endpoint", value: longText });
expect(result.allowed_relations).toHaveLength(2);
expect(result.expected?.classes).toHaveLength(25);
});
it("rejects the inert source-map authority setting", () => {
expect(
javaScriptSemanticQueryInputSchema.safeParse({
seed: { kind: "endpoint", value: "/api" },
direction: "forward-influence",
source_map_authority: { authority: "none" },
}).success,
).toBe(false);
});
it("accepts every reported limitation without a count ceiling", () => {
const limitations = Array.from(
{ length: 1_001 },
(_, index) => `gap-${index}`,
);
const id = "a".repeat(64);
const result = javaScriptSemanticQueryResultSchema.parse({
query_id: `jsrq_${id}`,
source_graph_id: `jsrg_${id}`,
seed: { kind: "literal", value: null },
direction: "forward-influence",
status: "no-match",
seed_node_ids: [],
nodes: [],
relations: [],
unknowns: [],
expected_match_node_ids: [],
summary: {
total_seed_matches: 0,
traversed_nodes: 0,
traversed_relations: 0,
traversed_functions: 0,
traversed_modules: 0,
relevant_unknowns: 0,
},
coverage: { status: "complete" },
limitations,
});
expect(result.limitations).toHaveLength(1_001);
});
@@ -0,0 +1,116 @@
import { z } from "zod";
import {
JAVASCRIPT_SEMANTIC_NODE_KINDS,
JAVASCRIPT_SEMANTIC_RELATIONS,
javaScriptSemanticNodeSchema,
javaScriptSemanticRelationSchema,
javaScriptSemanticUnknownSchema,
} from "./javascriptSemanticGraphSchemas.js";
import { jsonValueSchema } from "../jsonValue.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
const semanticNodeIdSchema = prefixedDigestSchema("jsrg_node");
const literalSeedSchema = z.strictObject({
kind: z.literal("literal"),
value: jsonValueSchema.refine(
(value) =>
value === null ||
typeof value === "string" ||
typeof value === "number" ||
typeof value === "boolean",
"Literal seeds accept only JSON primitive values",
),
});
/** Authenticated starting points accepted by semantic tracing. */
export const javaScriptSemanticQuerySeedSchema = z.discriminatedUnion("kind", [
z.strictObject({
kind: z.literal("semantic-node"),
node_id: semanticNodeIdSchema,
}),
z.strictObject({
kind: z.literal("application-node"),
node_id: prefixedDigestSchema("jag_node"),
}),
literalSeedSchema,
z.strictObject({
kind: z.literal("function"),
fingerprint_sha256: digestSchema,
}),
z.strictObject({
kind: z.literal("property"),
name: z.string().min(1),
}),
z.strictObject({
kind: z.literal("endpoint"),
value: z.string().min(1),
}),
z.strictObject({
kind: z.literal("event"),
name: z.string().min(1),
}),
z.strictObject({
kind: z.literal("boundary-field"),
field: z.string().min(1),
}),
]);
/** Parsed pure-domain query over one authenticated companion graph. */
export const javaScriptSemanticQueryInputSchema = z.strictObject({
seed: javaScriptSemanticQuerySeedSchema,
direction: z.enum([
"backward-provenance",
"forward-influence",
"callers",
"ownership",
]),
allowed_relations: z
.array(z.enum(JAVASCRIPT_SEMANTIC_RELATIONS))
.min(1)
.optional(),
include_ambiguous_dynamic_edges: z.boolean().default(false),
expected: z
.strictObject({
role: z.enum(["source", "sink"]),
classes: z.array(z.enum(JAVASCRIPT_SEMANTIC_NODE_KINDS)).min(1),
})
.nullable()
.default(null),
});
/** Deterministic semantic trace result. */
export const javaScriptSemanticQueryResultSchema = z.strictObject({
query_id: prefixedDigestSchema("jsrq"),
source_graph_id: prefixedDigestSchema("jsrg"),
seed: javaScriptSemanticQuerySeedSchema,
direction: javaScriptSemanticQueryInputSchema.shape.direction,
status: z.enum(["found", "no-match", "ambiguous", "partial", "unsupported"]),
seed_node_ids: z.array(semanticNodeIdSchema),
nodes: z.array(javaScriptSemanticNodeSchema),
relations: z.array(javaScriptSemanticRelationSchema),
unknowns: z.array(javaScriptSemanticUnknownSchema),
expected_match_node_ids: z.array(semanticNodeIdSchema),
summary: z.strictObject({
total_seed_matches: z.number().int().min(0),
traversed_nodes: z.number().int().min(0),
traversed_relations: z.number().int().min(0),
traversed_functions: z.number().int().min(0),
traversed_modules: z.number().int().min(0),
relevant_unknowns: z.number().int().min(0),
}),
coverage: z.strictObject({
status: z.enum(["complete", "partial", "unavailable"]),
}),
limitations: z.array(z.string().min(1)),
});
/** Validated semantic query input. */
export type JavaScriptSemanticQueryInput = z.infer<
typeof javaScriptSemanticQueryInputSchema
>;
/** Validated semantic query result. */
export type JavaScriptSemanticQueryResult = z.infer<
typeof javaScriptSemanticQueryResultSchema
>;
@@ -0,0 +1,194 @@
import * as t from "@babel/types";
import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticResourceOperation,
} from "./javascriptSemanticIr.js";
import { semanticStaticPropertyName } from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import {
dataEffectMemberCallee,
outerDataEffectBinding,
traverseDataEffects,
type DataEffectTraversalContext,
} from "./javascriptSemanticDataEffectHelpers.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
const ACQUIRE_METHODS = [
"open",
"openSync",
"createReadStream",
"createWriteStream",
"connect",
"createConnection",
] as const;
const RELEASE_METHODS = ["close", "destroy", "end"] as const;
interface ResourceCandidate {
readonly node: t.CallExpression | t.OptionalCallExpression;
readonly method: JavaScriptSemanticResourceOperation["method"];
readonly ownerCallableId: string | null;
readonly resultBindingId: string | null;
}
/** Recover built-in filesystem/network acquisition and local release handles. */
export const collectJavaScriptSemanticResources = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticResourceOperation[] => {
const context: DataEffectTraversalContext = {
state,
callableIds: new Set(callables.map(({ callableId }) => callableId)),
callableStack: [],
ancestors: [],
};
const acquisitions = collectAcquisitions(program, context);
return [
...acquisitions.map(immutableAcquisition),
...collectReleases(program, context, acquisitions),
];
};
const collectAcquisitions = (
program: t.Program,
context: DataEffectTraversalContext,
): ResourceCandidate[] => {
const output: ResourceCandidate[] = [];
traverseDataEffects(program, context, (node) => {
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node)) return;
const method = acquisitionMethod(node.callee, context.state);
if (method === null) return;
output.push({
node,
method,
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: outerDataEffectBinding(node, context),
});
});
return output;
};
const collectReleases = (
program: t.Program,
context: DataEffectTraversalContext,
acquisitions: readonly ResourceCandidate[],
): JavaScriptSemanticResourceOperation[] => {
const byBinding = new Map<string, ResourceCandidate[]>();
for (const acquisition of acquisitions) {
if (acquisition.resultBindingId === null) continue;
const existing = byBinding.get(acquisition.resultBindingId) ?? [];
existing.push(acquisition);
byBinding.set(acquisition.resultBindingId, existing);
}
const output: JavaScriptSemanticResourceOperation[] = [];
traverseDataEffects(program, context, (node) => {
if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node)) return;
const member = dataEffectMemberCallee(node);
if (member === null || !t.isIdentifier(member.object)) return;
const method = RELEASE_METHODS.find(
(candidate) =>
candidate ===
semanticStaticPropertyName(member.property, member.computed),
);
if (method === undefined) return;
const binding = resolveSemanticBindingState(
context.state,
member.object,
member.object.name,
);
const linked =
binding === undefined ? [] : (byBinding.get(binding.bindingId) ?? []);
if (linked.length === 0) return;
output.push({
resourceId: `resource:release:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
kind: "release",
method,
location: range(node),
ownerCallableId: context.callableStack.at(-1) ?? null,
resultBindingId: binding?.bindingId ?? null,
linkedResourceIds: linked.map(resourceCandidateId).sort(),
resolution: linked.length === 1 ? "complete" : "partial",
});
});
return output;
};
const immutableAcquisition = (
candidate: ResourceCandidate,
): JavaScriptSemanticResourceOperation => ({
resourceId: resourceCandidateId(candidate),
kind: "acquire",
method: candidate.method,
location: range(candidate.node),
ownerCallableId: candidate.ownerCallableId,
resultBindingId: candidate.resultBindingId,
linkedResourceIds: [],
resolution: "complete",
});
const acquisitionMethod = (
callee: t.Node,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticResourceOperation["method"] | null => {
if (t.isIdentifier(callee)) {
const binding = resolveSemanticBindingState(state, callee, callee.name);
return methodFromBinding(binding);
}
if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
return null;
const method = ACQUIRE_METHODS.find(
(candidate) =>
candidate ===
semanticStaticPropertyName(callee.property, callee.computed),
);
if (method === undefined || !t.isIdentifier(callee.object)) return null;
const binding = resolveSemanticBindingState(
state,
callee.object,
callee.object.name,
);
return resourceNamespace(binding) ? method : null;
};
const methodFromBinding = (
binding: JavaScriptSemanticBindingState | undefined,
): JavaScriptSemanticResourceOperation["method"] | null => {
for (const { specifier, importedPath } of binding?.directOrigins ?? []) {
if (!resourceModule(specifier)) continue;
const method = ACQUIRE_METHODS.find(
(candidate) => candidate === importedPath.at(-1),
);
if (method !== undefined) return method;
}
return null;
};
const resourceNamespace = (
binding: JavaScriptSemanticBindingState | undefined,
): boolean =>
binding?.directOrigins.some(
({ specifier, importedPath }) =>
resourceModule(specifier) && semanticBuiltinNamespacePath(importedPath),
) ?? false;
const resourceModule = (specifier: string): boolean =>
[
"fs",
"fs/promises",
"net",
"node:fs",
"node:fs/promises",
"node:net",
"node:tls",
"tls",
].includes(specifier);
const resourceCandidateId = (candidate: ResourceCandidate): string =>
`resource:acquire:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
@@ -0,0 +1,258 @@
import * as t from "@babel/types";
import type {
JavaScriptSemanticCallable,
JavaScriptSemanticModuleLink,
JavaScriptSemanticReturnSite,
JavaScriptSemanticValue,
} from "./javascriptSemanticIr.js";
import type {
ProjectedPropertyCoverage,
ProjectedReturnField,
} from "./javascriptExportShapeComparisonSchemas.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
import {
resolveSemanticBindingState,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { evaluateSemanticExpression } from "./javascriptSemanticValues.js";
import { range } from "./javascriptStaticAnalysisHelpers.js";
import { semanticReturnCoverage } from "./javascriptSemanticCoverage.js";
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
interface ReturnExpression {
readonly node: t.Node | null;
readonly location: JavaScriptSemanticReturnSite["location"];
}
/** Evaluate direct returns while excluding every nested callable. */
export const collectSemanticReturns = (
program: t.Program,
state: JavaScriptSemanticAnalysisState,
parserPartial: boolean,
): JavaScriptSemanticCallable[] => {
const nodes = callableNodes(program);
return state.callables.map((callable) => {
const node = nodes.get(callable.callableId);
if (node === undefined)
return {
...callable,
returnCoverage: {
status: "partial" as const,
retainedCount: 0,
omittedCount: null,
},
};
const expressions = directReturnExpressions(node);
const sites: JavaScriptSemanticReturnSite[] = [];
for (const expression of expressions) {
sites.push({
returnSiteId: semanticReturnSiteId(
callable.callableId,
expression.location,
),
location: expression.location,
identityReferenceLocation:
expression.node !== null && t.isIdentifier(expression.node)
? range(expression.node)
: null,
value:
expression.node === null
? { status: "unknown", reason: "Return has no value." }
: evaluateSemanticExpression(expression.node, state),
});
}
return {
...callable,
returnSites: sites,
returnCoverage: semanticReturnCoverage(sites.length, parserPartial),
};
});
};
const semanticReturnSiteId = (
callableId: string,
location: JavaScriptSemanticReturnSite["location"],
): string =>
`${callableId}:return:${String(location.start.line)}:${String(location.start.column)}:${String(location.end.line)}:${String(location.end.column)}`;
/** Link exports to callables only when lexical resolution is unique and exact. */
export const resolveSemanticModuleCallables = (
state: JavaScriptSemanticAnalysisState,
callables: readonly JavaScriptSemanticCallable[],
): JavaScriptSemanticModuleLink[] => {
const callableIds = new Set(callables.map(({ callableId }) => callableId));
const root = state.scopes.find(({ kind }) => kind === "program");
return state.moduleLinks.map((link) => {
if (link.callableId !== null && callableIds.has(link.callableId))
return link;
if (link.localName === null || root === undefined)
return { ...link, callableId: null };
const named = callables.filter(
({ name, containerScopeId }) =>
name === link.localName && containerScopeId === root.scopeId,
);
if (named.length === 1)
return { ...link, callableId: named[0]?.callableId ?? null };
const binding = root.bindings.get(link.localName);
const resolved =
binding === undefined
? []
: callableIdsForBinding(binding, state, callableIds, new Set());
return {
...link,
callableId: resolved.length === 1 ? (resolved[0] ?? null) : null,
};
});
};
const callableNodes = (program: t.Program): Map<string, t.Node> => {
const output = new Map<string, t.Node>();
traverseJavaScriptAst(program, {
enter: (node) => {
const id = semanticCallableIdForNode(node);
if (id !== null) output.set(id, node);
},
});
return output;
};
const directReturnExpressions = (callable: t.Node): ReturnExpression[] => {
if (
t.isArrowFunctionExpression(callable) &&
!t.isBlockStatement(callable.body)
)
return [{ node: callable.body, location: range(callable.body) }];
if (!t.isFunction(callable)) return [];
const output: ReturnExpression[] = [];
const visit = (node: t.Node): void => {
if (t.isFunction(node) || t.isClass(node)) return;
if (t.isReturnStatement(node)) {
output.push({ node: node.argument ?? null, location: range(node) });
return;
}
for (const child of childNodes(node)) visit(child);
};
for (const child of childNodes(callable.body)) visit(child);
return output;
};
const childNodes = (node: t.Node): t.Node[] =>
(t.VISITOR_KEYS[node.type] ?? []).flatMap((key) => {
const value: unknown = Reflect.get(node, key);
if (t.isNode(value)) return [value];
return Array.isArray(value)
? value.filter((item): item is t.Node => t.isNode(item))
: [];
});
const callableIdsForBinding = (
binding: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
admitted: ReadonlySet<string>,
seen: ReadonlySet<string>,
): string[] => {
if (seen.has(binding.bindingId) || binding.initializers.length !== 1)
return [];
const initializer = binding.initializers[0];
if (initializer === undefined || initializer.projection.length > 0) return [];
return callableIdsForNode(
initializer.node,
state,
admitted,
new Set([...seen, binding.bindingId]),
);
};
const callableIdsForNode = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
admitted: ReadonlySet<string>,
seen: ReadonlySet<string>,
): string[] => {
const direct = semanticCallableIdForNode(node);
if (direct !== null && admitted.has(direct)) return [direct];
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(state, node, node.name);
return binding === undefined
? []
: callableIdsForBinding(binding, state, admitted, seen);
}
if (
t.isTSAsExpression(node) ||
t.isTSTypeAssertion(node) ||
t.isTSNonNullExpression(node)
)
return callableIdsForNode(node.expression, state, admitted, seen);
return [];
};
/** Flatten a semantic value to bounded JSON-pointer leaves for graph projection. */
export const flattenSemanticReturnValue = (
value: JavaScriptSemanticValue,
): {
readonly fields: readonly ProjectedReturnField[];
readonly propertyCoverage: readonly ProjectedPropertyCoverage[];
} => {
const fields: ProjectedReturnField[] = [];
const propertyCoverage: ProjectedPropertyCoverage[] = [];
flattenValue(value, "", fields, propertyCoverage);
fields.sort((left, right) => compareCodePoints(left.path, right.path));
propertyCoverage.sort((left, right) =>
compareCodePoints(left.path, right.path),
);
return { fields, propertyCoverage };
};
const flattenValue = (
value: JavaScriptSemanticValue,
path: string,
fields: ProjectedReturnField[],
coverage: ProjectedPropertyCoverage[],
): void => {
if (value.status === "literal") {
fields.push({ path, state: "literal", value: value.value, reason: null });
return;
}
if (value.status === "union") {
fields.push({
path,
state: "union",
value: [...value.values],
reason: null,
});
return;
}
if (value.status === "object") {
coverage.push(
value.unknownProperties
? { path, status: "partial", omitted: value.omittedProperties }
: { path, status: "complete", omitted: 0 },
);
for (const property of value.properties)
flattenValue(
property.value,
`${path}/${escapePointer(property.name)}`,
fields,
coverage,
);
return;
}
if (value.status === "array") {
coverage.push(
value.unknownItems
? { path, status: "partial", omitted: value.omittedItems }
: { path, status: "complete", omitted: 0 },
);
value.items.forEach((item, index) =>
flattenValue(item, `${path}/${String(index)}`, fields, coverage),
);
return;
}
fields.push({ path, state: "unknown", value: null, reason: value.reason });
};
const escapePointer = (value: string): string =>
value.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -0,0 +1,151 @@
import * as t from "@babel/types";
import type {
JavaScriptModuleOrigin,
JavaScriptSemanticDefinition,
JavaScriptSemanticModuleLink,
JavaScriptSemanticCallable,
JavaScriptSemanticScope,
} from "./javascriptSemanticIr.js";
/** Internal initializer plus a destructuring/member projection. */
interface JavaScriptSemanticInitializer {
readonly node: t.Node;
readonly projection: readonly (string | number | null)[];
}
/** Mutable binding state used only while constructing the immutable IR. */
export interface JavaScriptSemanticBindingState {
readonly bindingId: string;
readonly scopeId: string;
readonly name: string;
kind: JavaScriptSemanticDefinition["kind"];
mutable: boolean;
readonly mutatedPaths: (readonly (string | number | null)[])[];
readonly definitions: JavaScriptSemanticDefinition[];
readonly initializers: JavaScriptSemanticInitializer[];
readonly directOrigins: JavaScriptModuleOrigin[];
}
/** Mutable lexical-scope state used only during AST recovery. */
export interface JavaScriptSemanticScopeState {
readonly scopeId: string;
readonly parentScopeId: string | null;
readonly kind: JavaScriptSemanticScope["kind"];
readonly location: JavaScriptSemanticScope["location"];
bindingsComplete: boolean;
readonly bindings: Map<string, JavaScriptSemanticBindingState>;
}
/** Shared state for semantic collection and evaluation. */
export interface JavaScriptSemanticAnalysisState {
readonly scopes: JavaScriptSemanticScopeState[];
readonly scopesById: Map<string, JavaScriptSemanticScopeState>;
readonly scopeByNode: WeakMap<t.Node, JavaScriptSemanticScopeState>;
readonly bindingsById: Map<string, JavaScriptSemanticBindingState>;
readonly callables: JavaScriptSemanticCallable[];
readonly callableNodesById: Map<string, t.Node>;
readonly moduleLinks: JavaScriptSemanticModuleLink[];
}
/** Return the active scope from a non-empty construction stack. */
export const currentSemanticScope = (
stack: readonly JavaScriptSemanticScopeState[],
): JavaScriptSemanticScopeState => {
const scope = stack.at(-1);
if (scope === undefined) throw new TypeError("Missing semantic scope");
return scope;
};
/** Create a stable source-position identity for one lexical scope. */
export const semanticScopeId = (
kind: JavaScriptSemanticScope["kind"],
node: t.Node,
): string =>
`scope:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
/** Resolve one lexical name from the scope containing a node. */
export const resolveSemanticBindingState = (
state: JavaScriptSemanticAnalysisState,
node: t.Node,
name: string,
): JavaScriptSemanticBindingState | undefined => {
let scope = state.scopeByNode.get(node);
while (scope !== undefined) {
const binding = scope.bindings.get(name);
if (binding !== undefined) return binding;
if (!scope.bindingsComplete) return undefined;
scope =
scope.parentScopeId === null
? undefined
: state.scopesById.get(scope.parentScopeId);
}
return undefined;
};
/** Report whether an omitted binding scope blocks a trustworthy miss. */
export const semanticResolutionBlocked = (
state: JavaScriptSemanticAnalysisState,
node: t.Node,
name: string,
): boolean => {
let scope = state.scopeByNode.get(node);
while (scope !== undefined) {
if (scope.bindings.has(name)) return false;
if (!scope.bindingsComplete) return true;
scope =
scope.parentScopeId === null
? undefined
: state.scopesById.get(scope.parentScopeId);
}
return false;
};
/** Resolve one name starting from an explicitly selected lexical scope. */
export const resolveSemanticBindingFromScope = (
scope: JavaScriptSemanticScopeState,
name: string,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBindingState | undefined => {
let candidate: JavaScriptSemanticScopeState | undefined = scope;
while (candidate !== undefined) {
const binding = candidate.bindings.get(name);
if (binding !== undefined) return binding;
if (!candidate.bindingsComplete) return undefined;
candidate =
candidate.parentScopeId === null
? undefined
: state.scopesById.get(candidate.parentScopeId);
}
return undefined;
};
/** Select the function/program owner for a var declaration. */
export const semanticVariableScope = (
scope: JavaScriptSemanticScopeState,
parent: t.Node | null,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticScopeState => {
if (!(parent !== null && t.isVariableDeclaration(parent, { kind: "var" })))
return scope;
let candidate = scope;
while (candidate.kind === "block" || candidate.kind === "catch") {
const outer =
candidate.parentScopeId === null
? undefined
: state.scopesById.get(candidate.parentScopeId);
if (outer === undefined) break;
candidate = outer;
}
return candidate;
};
/** Identify a global name only when no lexical or dynamic environment shadows it. */
export const isUnshadowedGlobal = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
name: string,
): boolean =>
t.isIdentifier(node, { name }) &&
resolveSemanticBindingState(state, node, name) === undefined &&
!semanticResolutionBlocked(state, node, name);
@@ -0,0 +1,28 @@
import { z } from "zod";
import { evidenceSchema } from "../evidence.js";
import {
javaScriptSemanticQueryInputSchema,
javaScriptSemanticQueryResultSchema,
} from "./javascriptSemanticQuerySchemas.js";
import { prefixedDigestSchema } from "../digests.js";
const evidenceIdSchema = prefixedDigestSchema("ev");
/** Authenticated application Evidence plus one bounded semantic query. */
export const traceJavaScriptSemanticsInputSchema = z.strictObject({
application: evidenceSchema,
query: javaScriptSemanticQueryInputSchema,
});
/** Evidence-linked semantic query result shared by CLI and MCP. */
export const javaScriptSemanticTraceResultSchema =
javaScriptSemanticQueryResultSchema.extend({
source_evidence_id: evidenceIdSchema,
evidence_links: z.array(evidenceIdSchema).length(1),
});
/** Validated Evidence-linked semantic trace result. */
export type JavaScriptSemanticTraceResult = z.infer<
typeof javaScriptSemanticTraceResultSchema
>;
@@ -0,0 +1,44 @@
import * as t from "@babel/types";
/**
* Visit every Babel AST node in deterministic source-tree order.
*
* `ancestors` runs outermost-first and ends with the direct parent. Callers
* need it whenever meaning depends on where a node sits, not just what its
* immediate parent is — a binding inside `catch ({message})` or `({a} = o)`
* has an ObjectProperty parent, so the parent alone cannot say whether the
* identifier declares a binding or is assigned to.
*/
export const traverseJavaScriptAst = (
root: t.Node,
visitor: {
readonly enter: (
node: t.Node,
parent: t.Node | null,
ancestors: readonly t.Node[],
) => void;
readonly exit?: (node: t.Node, parent: t.Node | null) => void;
},
): void => {
const visit = (
node: t.Node,
parent: t.Node | null,
ancestors: readonly t.Node[],
): void => {
visitor.enter(node, parent, ancestors);
for (const child of childNodes(node))
visit(child, node, [...ancestors, node]);
visitor.exit?.(node, parent);
};
visit(root, null, []);
};
const childNodes = (node: t.Node): t.Node[] => {
const keys: readonly string[] = t.VISITOR_KEYS[node.type] ?? [];
return keys.flatMap((key) => {
const value: unknown = Reflect.get(node, key);
if (t.isNode(value)) return [value];
if (!Array.isArray(value)) return [];
return value.filter((item): item is t.Node => t.isNode(item));
});
};
@@ -0,0 +1,53 @@
/** Primitive values admitted into the constant lattice. */
export type JavaScriptSemanticPrimitive = string | number | boolean | null;
type JavaScriptSemanticObjectValue = {
readonly status: "object";
readonly properties: readonly JavaScriptSemanticProperty[];
} & (
| {
readonly unknownProperties: false;
readonly omittedProperties: 0;
}
| {
readonly unknownProperties: true;
readonly omittedProperties: number | null;
}
);
type JavaScriptSemanticArrayValue = {
readonly status: "array";
readonly items: readonly JavaScriptSemanticValue[];
} & (
| {
readonly unknownItems: false;
readonly omittedItems: 0;
}
| {
readonly unknownItems: true;
readonly omittedItems: number | null;
}
);
/** Execution-free value lattice for JavaScript expressions. */
export type JavaScriptSemanticValue =
| {
readonly status: "literal";
readonly value: JavaScriptSemanticPrimitive;
}
| {
readonly status: "union";
readonly values: readonly JavaScriptSemanticPrimitive[];
}
| JavaScriptSemanticObjectValue
| JavaScriptSemanticArrayValue
| {
readonly status: "unknown" | "ambiguous" | "cycle";
readonly reason: string;
};
/** One statically named object-literal property. */
export interface JavaScriptSemanticProperty {
readonly name: string;
readonly value: JavaScriptSemanticValue;
}
@@ -0,0 +1,506 @@
import * as t from "@babel/types";
import { invalidateSemanticMutationPath } from "./javascriptSemanticMutationValues.js";
import type {
JavaScriptBindingProvenance,
JavaScriptModuleOrigin,
JavaScriptSemanticProperty,
JavaScriptSemanticValue,
} from "./javascriptSemanticIr.js";
import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { stringValue } from "./javascriptStaticAnalysisHelpers.js";
import { compareCodePoints } from "../canonicalOrdering.js";
import { semanticStaticPropertyKey } from "./javascriptAstValues.js";
import {
semanticAmbiguousProvenance,
semanticLocalProvenance,
semanticOriginsProvenance,
semanticUnresolvedProvenance,
uniqueSemanticOrigins,
} from "./javascriptSemanticProvenance.js";
import {
semanticPrimitiveCandidates as primitiveCandidates,
semanticPrimitiveSet as primitiveSet,
semanticPrimitiveValue as primitiveValue,
} from "./javascriptSemanticPrimitives.js";
interface EvaluationContext {
readonly state: JavaScriptSemanticAnalysisState;
readonly bindings: ReadonlySet<string>;
}
/** Evaluate one binding in the bounded constant-value lattice. */
export const evaluateSemanticBinding = (
binding: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticValue =>
evaluateBinding(binding, { state, bindings: new Set() });
/** Evaluate one arbitrary inert expression in the established lexical state. */
export const evaluateSemanticExpression = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticValue =>
evaluateExpression(node, { state, bindings: new Set() });
/** Follow module provenance through destructuring, members, and aliases. */
export const evaluateSemanticProvenance = (
binding: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
): JavaScriptBindingProvenance =>
provenanceForBinding(binding, { state, bindings: new Set() });
const evaluateBinding = (
binding: JavaScriptSemanticBindingState,
context: EvaluationContext,
): JavaScriptSemanticValue => {
if (context.bindings.has(binding.bindingId))
return { status: "cycle", reason: `Alias cycle at ${binding.name}.` };
if (binding.initializers.length === 0)
return {
status: "unknown",
reason: `Binding ${binding.name} has no constant initializer.`,
};
if (binding.initializers.length > 1)
return {
status: "ambiguous",
reason: `Binding ${binding.name} has multiple possible assignments.`,
};
const initializer = binding.initializers[0];
if (initializer === undefined)
return { status: "unknown", reason: "Missing binding initializer." };
const nested = nestedContext(context, binding.bindingId);
const value = projectValue(
evaluateExpression(initializer.node, nested),
initializer.projection,
);
return binding.mutatedPaths.reduce(invalidateSemanticMutationPath, value);
};
const evaluateExpression = (
node: t.Node,
context: EvaluationContext,
): JavaScriptSemanticValue => {
const literal = primitiveValue(node);
if (literal.found) return { status: "literal", value: literal.value };
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(context.state, node, node.name);
return binding === undefined
? { status: "unknown", reason: `Unbound identifier ${node.name}.` }
: evaluateBinding(binding, nestedContext(context));
}
if (t.isTemplateLiteral(node)) return evaluateTemplate(node, context);
if (t.isConditionalExpression(node))
return mergeValues([
evaluateExpression(node.consequent, nestedContext(context)),
evaluateExpression(node.alternate, nestedContext(context)),
]);
if (t.isLogicalExpression(node))
return mergeValues([
evaluateExpression(node.left, nestedContext(context)),
evaluateExpression(node.right, nestedContext(context)),
]);
if (t.isObjectExpression(node)) return evaluateObject(node, context);
if (t.isArrayExpression(node)) return evaluateArray(node, context);
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
return evaluateMember(node, context);
if (t.isBinaryExpression(node, { operator: "+" }))
return evaluateAddition(node, context);
if (t.isUnaryExpression(node)) return evaluateUnary(node, context);
if (
(t.isTSAsExpression(node) ||
t.isTSTypeAssertion(node) ||
t.isTSNonNullExpression(node)) &&
t.isExpression(node.expression)
)
return evaluateExpression(node.expression, nestedContext(context));
return { status: "unknown", reason: `Unsupported ${node.type} value.` };
};
const evaluateTemplate = (
node: t.TemplateLiteral,
context: EvaluationContext,
): JavaScriptSemanticValue => {
let candidates = [""];
for (let index = 0; index < node.quasis.length; index += 1) {
const quasi = node.quasis[index];
const text = quasi?.value.cooked ?? quasi?.value.raw ?? "";
candidates = candidates.map((prefix) => `${prefix}${text}`);
const expression = node.expressions[index];
if (expression === undefined) continue;
const values = primitiveCandidates(
evaluateExpression(expression, nestedContext(context)),
);
if (values === null)
return {
status: "unknown",
reason: "Template expression is not a bounded primitive.",
};
candidates = candidates.flatMap((prefix) =>
values.map((value) => `${prefix}${String(value)}`),
);
}
return primitiveSet(candidates);
};
const evaluateObject = (
node: t.ObjectExpression,
context: EvaluationContext,
): JavaScriptSemanticValue => {
const propertiesByName = new Map<string, JavaScriptSemanticProperty>();
let unknownProperties = false;
let omittedProperties: number | null = 0;
const invalidateEarlierProperties = (): void => {
for (const [name] of propertiesByName)
propertiesByName.set(name, {
name,
value: {
status: "unknown",
reason: "A later property may overwrite this value.",
},
});
};
for (const property of node.properties) {
if (t.isSpreadElement(property)) {
unknownProperties = true;
omittedProperties = null;
invalidateEarlierProperties();
continue;
}
const name = semanticStaticPropertyKey(property.key, property.computed);
if (name === null) {
unknownProperties = true;
if (omittedProperties !== null) omittedProperties += 1;
invalidateEarlierProperties();
continue;
}
// This spelling changes the prototype instead of defining an own slot.
if (
t.isObjectProperty(property) &&
!property.computed &&
!property.shorthand &&
name === "__proto__"
) {
unknownProperties = true;
if (omittedProperties !== null) omittedProperties += 1;
continue;
}
propertiesByName.set(name, {
name,
value: t.isObjectProperty(property)
? evaluateExpression(property.value, nestedContext(context))
: {
status: "unknown",
reason: "Object method or accessor value is not a primitive.",
},
});
}
const properties = [...propertiesByName.values()].sort((left, right) =>
compareCodePoints(left.name, right.name),
);
return unknownProperties
? {
status: "object",
properties,
unknownProperties: true,
omittedProperties,
}
: {
status: "object",
properties,
unknownProperties: false,
omittedProperties: 0,
};
};
const evaluateArray = (
node: t.ArrayExpression,
context: EvaluationContext,
): JavaScriptSemanticValue => {
const items: JavaScriptSemanticValue[] = [];
let unknownItems = false;
let omittedItems: number | null = 0;
for (const element of node.elements) {
if (t.isSpreadElement(element)) {
unknownItems = true;
omittedItems = null;
// Subsequent elements have no fixed index after an unknown-length spread.
break;
}
if (element === null) {
unknownItems = true;
if (omittedItems !== null) omittedItems += 1;
items.push({
status: "unknown",
reason: "Array hole has no primitive value.",
});
continue;
}
items.push(evaluateExpression(element, nestedContext(context)));
}
return unknownItems
? { status: "array", items, unknownItems: true, omittedItems }
: { status: "array", items, unknownItems: false, omittedItems: 0 };
};
const evaluateMember = (
node: t.MemberExpression | t.OptionalMemberExpression,
context: EvaluationContext,
): JavaScriptSemanticValue => {
if (!t.isNode(node.object))
return { status: "unknown", reason: "Unsupported member base." };
const key =
semanticStaticPropertyKey(node.property, node.computed) ?? undefined;
if (key === undefined)
return { status: "unknown", reason: "Dynamic member key." };
return projectValue(evaluateExpression(node.object, nestedContext(context)), [
key,
]);
};
const evaluateAddition = (
node: t.BinaryExpression,
context: EvaluationContext,
): JavaScriptSemanticValue => {
const left = primitiveCandidates(
evaluateExpression(node.left, nestedContext(context)),
);
const right = primitiveCandidates(
evaluateExpression(node.right, nestedContext(context)),
);
if (left === null || right === null)
return { status: "unknown", reason: "Non-primitive addition." };
const values = left.flatMap((leftValue) =>
right.map((rightValue) =>
typeof leftValue === "string" || typeof rightValue === "string"
? `${String(leftValue)}${String(rightValue)}`
: Number(leftValue) + Number(rightValue),
),
);
return primitiveSet(values);
};
const evaluateUnary = (
node: t.UnaryExpression,
context: EvaluationContext,
): JavaScriptSemanticValue => {
const argument = primitiveCandidates(
evaluateExpression(node.argument, nestedContext(context)),
);
if (argument === null)
return { status: "unknown", reason: "Non-primitive unary operand." };
if (node.operator === "!")
return primitiveSet(argument.map((value) => !value));
if (node.operator === "+")
return primitiveSet(argument.map((value) => Number(value)));
if (node.operator === "-")
return primitiveSet(argument.map((value) => -Number(value)));
return { status: "unknown", reason: `Unsupported unary ${node.operator}.` };
};
const projectValue = (
value: JavaScriptSemanticValue,
projection: readonly (string | number | null)[],
): JavaScriptSemanticValue => {
let current = value;
for (const key of projection) {
if (key === null)
return {
status: "unknown",
reason: "Cannot project a dynamic property.",
};
if (current.status === "object" && typeof key === "string") {
const property = current.properties.find(({ name }) => name === key);
if (property === undefined)
return {
status: current.unknownProperties ? "unknown" : "unknown",
reason: `Object property ${key} was not observed.`,
};
current = property.value;
} else if (current.status === "array") {
const index = typeof key === "number" ? key : Number(key);
if (
!Number.isSafeInteger(index) ||
index < 0 ||
String(index) !== String(key)
)
return {
status: "unknown",
reason: `Array property ${String(key)} is not a canonical index.`,
};
const item = current.items[index];
if (item === undefined)
return {
status: "unknown",
reason: `Array item ${String(key)} missing.`,
};
current = item;
} else
return {
status: "unknown",
reason: `Cannot project ${String(key)} from ${current.status}.`,
};
}
return current;
};
const provenanceForBinding = (
binding: JavaScriptSemanticBindingState,
context: EvaluationContext,
): JavaScriptBindingProvenance => {
if (context.bindings.has(binding.bindingId))
return semanticUnresolvedProvenance(
"cycle",
`Alias cycle at ${binding.name}.`,
);
if (binding.directOrigins.length > 0)
return semanticOriginsProvenance(binding.directOrigins);
if (binding.initializers.length === 0) return semanticLocalProvenance();
if (binding.initializers.length > 1)
return semanticAmbiguousProvenance(
[],
`Binding ${binding.name} has multiple possible assignments.`,
);
const initializer = binding.initializers[0];
if (initializer === undefined)
return semanticUnresolvedProvenance(
"unknown",
"Missing binding initializer.",
);
if (initializer.projection.includes(null))
return semanticUnresolvedProvenance(
"unknown",
"Dynamic provenance projection.",
);
const resolved = provenanceForExpression(
initializer.node,
nestedContext(context, binding.bindingId),
);
if (resolved.status !== "module" || initializer.projection.length === 0)
return resolved;
return semanticOriginsProvenance(
resolved.origins.map((origin) => ({
...origin,
importedPath: [
...origin.importedPath,
...initializer.projection.map((segment) => String(segment)),
],
})),
);
};
const provenanceForExpression = (
node: t.Node,
context: EvaluationContext,
): JavaScriptBindingProvenance => {
const required = requireOrigin(node, context.state);
if (required !== undefined) return semanticOriginsProvenance([required]);
if (t.isIdentifier(node)) {
const binding = resolveSemanticBindingState(context.state, node, node.name);
return binding === undefined
? semanticUnresolvedProvenance(
"unknown",
`Unbound identifier ${node.name}.`,
)
: provenanceForBinding(binding, nestedContext(context));
}
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
if (!t.isNode(node.object))
return semanticUnresolvedProvenance(
"unknown",
"Unsupported member base.",
);
const member =
semanticStaticPropertyKey(node.property, node.computed) ?? undefined;
if (typeof member !== "string")
return semanticUnresolvedProvenance(
"unknown",
"Dynamic provenance member.",
);
const base = provenanceForExpression(node.object, nestedContext(context));
return base.status !== "module"
? base
: semanticOriginsProvenance(
base.origins.map((origin) => ({
...origin,
importedPath: [...origin.importedPath, member],
})),
);
}
if (t.isConditionalExpression(node) || t.isLogicalExpression(node)) {
const left = t.isConditionalExpression(node) ? node.consequent : node.left;
const right = t.isConditionalExpression(node) ? node.alternate : node.right;
const candidates = [
provenanceForExpression(left, nestedContext(context)),
provenanceForExpression(right, nestedContext(context)),
];
const origins = candidates.flatMap((candidate) => candidate.origins);
return origins.length > 0
? semanticAmbiguousProvenance(
uniqueSemanticOrigins(origins),
"Multiple module origins.",
)
: semanticUnresolvedProvenance(
"unknown",
"Conditional provenance is unresolved.",
);
}
return semanticLocalProvenance();
};
const requireOrigin = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): JavaScriptModuleOrigin | undefined => {
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
if (!t.isNode(node.object)) return undefined;
const nested = requireOrigin(node.object, state);
const member =
semanticStaticPropertyKey(node.property, node.computed) ?? undefined;
return nested === undefined || typeof member !== "string"
? undefined
: { ...nested, importedPath: [...nested.importedPath, member] };
}
if (
!t.isCallExpression(node) ||
!t.isIdentifier(node.callee, { name: "require" })
)
return undefined;
if (
resolveSemanticBindingState(state, node.callee, "require") !== undefined ||
semanticResolutionBlocked(state, node.callee, "require")
)
return undefined;
const specifier = stringValue(node.arguments[0]);
return specifier === undefined ? undefined : { specifier, importedPath: [] };
};
const mergeValues = (
values: readonly JavaScriptSemanticValue[],
): JavaScriptSemanticValue => {
const primitives = values.flatMap(
(value) => primitiveCandidates(value) ?? [],
);
return values.every(
(value) => value.status === "union" || value.status === "literal",
)
? primitiveSet(primitives)
: { status: "ambiguous", reason: "Branches have incompatible values." };
};
const nestedContext = (
context: EvaluationContext,
bindingId?: string,
): EvaluationContext => ({
state: context.state,
bindings:
bindingId === undefined
? context.bindings
: new Set([...context.bindings, bindingId]),
});

Some files were not shown because too many files have changed in this diff Show More