refactor(javascript): group domain semantics and contracts (#907)
This commit is contained in:
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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
Reference in New Issue
Block a user