perf(javascript): reuse validated immutable graphs (#1112)

* perf(javascript): reuse validated immutable graphs

* fix(ci): follow the moved process CLI boundary test
This commit is contained in:
Ysopwnable
2026-10-09 02:40:21 +08:00
committed by GitHub
parent 1f5be750bc
commit ec6db0f063
11 changed files with 582 additions and 117 deletions
@@ -1,7 +1,15 @@
import { z } from "zod";
import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
import { javaScriptSemanticGraphSchema } from "./javascriptSemanticGraph.js";
import {
javascriptApplicationGraphSchema,
isValidatedImmutableJavaScriptApplicationGraph,
type JavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
javaScriptSemanticGraphSchema,
isValidatedImmutableJavaScriptSemanticGraph,
type JavaScriptSemanticGraph,
} from "./javascriptSemanticGraph.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
@@ -51,43 +59,62 @@ const reconstructionStatisticsSchema = z.strictObject({
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())
const applicationAnalysisResultShape = 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,
});
type BindingIssue = {
readonly code: "custom";
readonly path: PropertyKey[];
readonly message: string;
};
function* checkApplicationBindingsSteps(
result: z.infer<typeof applicationAnalysisResultShape>,
context: { readonly addIssue: (issue: BindingIssue) => void },
): Generator<void> {
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<string>();
let examined = 0;
try {
for (const node of result.graph.nodes) {
applicationNodeIds.add(node.node_id);
if (++examined === 4096) {
examined = 0;
yield;
}
}
for (const [nodeIndex, node] of result.semantic_graph.nodes.entries()) {
if (++examined === 4096) {
examined = 0;
yield;
}
for (const [
identifierIndex,
identifier,
] of node.application_node_ids.entries())
] of node.application_node_ids.entries()) {
if (!applicationNodeIds.has(identifier))
context.addIssue({
code: "custom",
@@ -100,8 +127,52 @@ export const javascriptApplicationAnalysisResultSchema = z
],
message: "Semantic node references an absent application node",
});
if (++examined === 4096) {
examined = 0;
yield;
}
}
}
} finally {
applicationNodeIds.clear();
}
}
/** JavaScript application analysis with an authenticated semantic companion. */
export const javascriptApplicationAnalysisResultSchema =
applicationAnalysisResultShape.superRefine((result, context) => {
const steps = checkApplicationBindingsSteps(result, context);
while (!steps.next().done) {
// Public/imported results still receive complete synchronous validation.
}
});
const ownedAnalysisResultShape = applicationAnalysisResultShape.extend({
graph: z.custom<JavaScriptApplicationGraph>(
isValidatedImmutableJavaScriptApplicationGraph,
),
semantic_graph: z.custom<JavaScriptSemanticGraph>(
isValidatedImmutableJavaScriptSemanticGraph,
),
});
/** Reuse exact owned graphs while validating metadata and cross-graph bindings. */
export function* parseOwnedJavaScriptApplicationAnalysisSteps(
input: unknown,
): Generator<void, JavaScriptApplicationAnalysisResult> {
const prepared = ownedAnalysisResultShape.safeParse(input);
if (!prepared.success)
return javascriptApplicationAnalysisResultSchema.parse(input);
const issues: BindingIssue[] = [];
yield* checkApplicationBindingsSteps(prepared.data, {
addIssue: (issue) => {
issues.push(issue);
},
});
if (issues.length > 0) throw new z.ZodError(issues);
return prepared.data;
}
/** Parsed public JavaScript application analysis request. */
export type AnalyzeJavaScriptApplicationInput = z.infer<
typeof analyzeJavaScriptApplicationInputSchema
@@ -0,0 +1,267 @@
import { describe, expect, it } from "vitest";
import { z } from "zod";
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";
import { freezeJsonSnapshot } from "../immutableJson.js";
import {
javascriptApplicationAnalysisResultSchema,
parseOwnedJavaScriptApplicationAnalysisSteps,
} from "./javascriptApplicationAnalysis.js";
import {
createJavaScriptApplicationGraph,
createImmutableJavaScriptApplicationGraphSteps,
isValidatedImmutableJavaScriptApplicationGraph,
} from "./javascriptApplicationGraph.js";
import {
createJavaScriptSemanticGraph,
createImmutableJavaScriptSemanticGraphSteps,
isValidatedImmutableJavaScriptSemanticGraph,
} from "./javascriptSemanticGraph.js";
const complete = <Value>(steps: Iterator<void, Value>): Value => {
let next = steps.next();
while (!next.done) next = steps.next();
return next.value;
};
const example = () =>
javascriptApplicationAnalysisResultSchema.parse(
JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.normalized_result,
);
const ownedExample = () => {
const result = example();
const { graph_id: _applicationId, ...application } = result.graph;
const { graph_id: _semanticId, ...semantic } = result.semantic_graph;
return {
...result,
graph: complete(
createImmutableJavaScriptApplicationGraphSteps(application),
),
semantic_graph: complete(
createImmutableJavaScriptSemanticGraphSteps(semantic),
),
};
};
const issuesFrom = (action: () => unknown) => {
try {
action();
} catch (error: unknown) {
if (error instanceof z.ZodError) return error.issues;
throw error;
}
throw new Error("Expected complete result validation to reject the input");
};
describe("owned JavaScript graph validation", () => {
it("reuses exact sealed graphs and preserves all public result fields", () => {
const input = ownedExample();
const result = complete(
parseOwnedJavaScriptApplicationAnalysisSteps(input),
);
expect(result).toEqual(
javascriptApplicationAnalysisResultSchema.parse(input),
);
expect(result.graph).toBe(input.graph);
expect(result.semantic_graph).toBe(input.semantic_graph);
expect(result.summary).not.toBe(input.summary);
expect(result.statistics).not.toBe(input.statistics);
expect(Object.isFrozen(result.graph.nodes[0]?.observations)).toBe(true);
expect(Object.isFrozen(result.semantic_graph.nodes[0]?.properties)).toBe(
true,
);
expect(isValidatedImmutableJavaScriptApplicationGraph(result.graph)).toBe(
true,
);
expect(
isValidatedImmutableJavaScriptSemanticGraph(result.semantic_graph),
).toBe(true);
expect(
isValidatedImmutableJavaScriptApplicationGraph(result.graph.nodes),
).toBe(false);
});
it("keeps ordinary constructors mutable and clones inputs before sealing", () => {
const input = example();
const { graph_id: _applicationId, ...application } = input.graph;
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
const ordinaryApplication = createJavaScriptApplicationGraph(application);
const ordinarySemantic = createJavaScriptSemanticGraph(semantic);
expect(Object.isFrozen(ordinaryApplication)).toBe(false);
expect(Object.isFrozen(ordinarySemantic)).toBe(false);
const applicationSteps =
createImmutableJavaScriptApplicationGraphSteps(application);
const semanticSteps = createImmutableJavaScriptSemanticGraphSteps(semantic);
application.limitations.push("Changed after factory input was cloned.");
semantic.limitations.push("Changed after factory input was cloned.");
expect(complete(applicationSteps)).toEqual(ordinaryApplication);
expect(complete(semanticSteps)).toEqual(ordinarySemantic);
expect(
isValidatedImmutableJavaScriptApplicationGraph(ordinaryApplication),
).toBe(false);
expect(isValidatedImmutableJavaScriptSemanticGraph(ordinarySemantic)).toBe(
false,
);
});
it.each(["mutable", "shallow-frozen", "json-sealed"])(
"fully validates %s imported graphs instead of trusting their IDs",
(representation) => {
const input = example();
input.graph.graph_id = `jag_${"f".repeat(64)}`;
if (representation === "shallow-frozen") Object.freeze(input.graph);
if (representation === "json-sealed") freezeJsonSnapshot(input.graph);
expect(isValidatedImmutableJavaScriptApplicationGraph(input.graph)).toBe(
false,
);
const issues = issuesFrom(() =>
complete(parseOwnedJavaScriptApplicationAnalysisSteps(input)),
);
expect(issues).toEqual(
issuesFrom(() =>
javascriptApplicationAnalysisResultSchema.parse(input),
),
);
expect(
issues.some(({ path }) => path.join("/") === "graph/graph_id"),
).toBe(true);
},
);
it("fully parses valid imported graphs without conferring an owned proof", () => {
const input = example();
const parsed = complete(
parseOwnedJavaScriptApplicationAnalysisSteps(input),
);
expect(parsed).toEqual(input);
expect(parsed.graph).not.toBe(input.graph);
expect(parsed.semantic_graph).not.toBe(input.semantic_graph);
expect(
isValidatedImmutableJavaScriptSemanticGraph(parsed.semantic_graph),
).toBe(false);
});
it("rejects a forged semantic graph paired with an authenticated application graph", () => {
const input = ownedExample();
input.semantic_graph = freezeJsonSnapshot({
...input.semantic_graph,
graph_id: `jsrg_${"f".repeat(64)}`,
});
expect(
isValidatedImmutableJavaScriptSemanticGraph(input.semantic_graph),
).toBe(false);
expect(
issuesFrom(() =>
complete(parseOwnedJavaScriptApplicationAnalysisSteps(input)),
),
).toEqual(
issuesFrom(() => javascriptApplicationAnalysisResultSchema.parse(input)),
);
});
it("does not authenticate an abandoned sealing operation", () => {
const input = example();
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
const originalNode = semantic.nodes[0];
if (originalNode === undefined) throw new Error("Expected a semantic node");
semantic.nodes[0] = {
...originalNode,
properties: {
rows: Array.from({ length: 10_000 }, (_, value) => ({ value })),
},
};
const mutable = createJavaScriptSemanticGraph(semantic);
const { graph_id: _mutableId, ...mutableInput } = mutable;
const steps = createImmutableJavaScriptSemanticGraphSteps(mutableInput);
expect(steps.next().done).toBe(false);
steps.return(mutable);
expect(isValidatedImmutableJavaScriptSemanticGraph(mutable)).toBe(false);
const sealed = complete(
createImmutableJavaScriptSemanticGraphSteps(mutableInput),
);
expect(sealed).toEqual(mutable);
expect(isValidatedImmutableJavaScriptSemanticGraph(sealed)).toBe(true);
});
});
describe("owned JavaScript result bindings", () => {
it.each(["application", "root", "node"])(
"retains the %s binding check for individually authenticated graphs",
(binding) => {
const input = ownedExample();
if (binding === "root") input.root_artifact_sha256 = "e".repeat(64);
else {
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
if (binding === "application")
semantic.application_graph_id = `jag_${"e".repeat(64)}`;
else {
const node = semantic.nodes[0];
if (node === undefined) throw new Error("Expected a semantic node");
semantic.nodes = [
{ ...node, application_node_ids: [`jag_node_${"e".repeat(64)}`] },
...semantic.nodes.slice(1),
];
}
input.semantic_graph = complete(
createImmutableJavaScriptSemanticGraphSteps(semantic),
);
}
expect(
issuesFrom(() =>
complete(parseOwnedJavaScriptApplicationAnalysisSteps(input)),
),
).toEqual(
issuesFrom(() =>
javascriptApplicationAnalysisResultSchema.parse(input),
),
);
},
);
it("yields while checking a wide binding set and closes an abandoned iteration", () => {
const input = ownedExample();
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
const node = semantic.nodes[0];
if (node === undefined) throw new Error("Expected a semantic node");
semantic.nodes = [
{
...node,
application_node_ids: Array.from(
{ length: 10_000 },
(_, index) => `jag_node_${index.toString(16).padStart(64, "0")}`,
),
},
...semantic.nodes.slice(1),
];
input.semantic_graph = complete(
createImmutableJavaScriptSemanticGraphSteps(semantic),
);
const steps = parseOwnedJavaScriptApplicationAnalysisSteps(input);
expect(steps.next().done).toBe(false);
steps.return(input);
expect(steps.next().done).toBe(true);
expect(
issuesFrom(() =>
complete(parseOwnedJavaScriptApplicationAnalysisSteps(input)),
),
).toEqual(
issuesFrom(() => javascriptApplicationAnalysisResultSchema.parse(input)),
);
});
it("retains strict metadata validation alongside authenticated graphs", () => {
const input = {
...ownedExample(),
statistics: { ...example().statistics, findings: -1 },
extra: true,
};
expect(
issuesFrom(() =>
complete(parseOwnedJavaScriptApplicationAnalysisSteps(input)),
),
).toEqual(
issuesFrom(() => javascriptApplicationAnalysisResultSchema.parse(input)),
);
});
});
@@ -1,6 +1,7 @@
import { z } from "zod";
import { canonicalDigest, canonicalJson } from "../comparisonSemantics.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import { freezeOwnedJsonSnapshotSteps } from "../immutableJson.js";
import type {
ApplicationGraphEvidence,
@@ -450,6 +451,30 @@ export const createJavaScriptApplicationGraph = (
});
};
const validatedImmutableApplicationGraphs = new WeakSet<object>();
/** Clone and validate synchronously, then return steps to seal the owned graph. */
export const createImmutableJavaScriptApplicationGraphSteps = (
input: unknown,
): Generator<void, JavaScriptApplicationGraph> =>
sealValidatedApplicationGraphSteps(createJavaScriptApplicationGraph(input));
function* sealValidatedApplicationGraphSteps(
graph: JavaScriptApplicationGraph,
): Generator<void, JavaScriptApplicationGraph> {
yield* freezeOwnedJsonSnapshotSteps(graph);
validatedImmutableApplicationGraphs.add(graph);
return graph;
}
/** Recognize the exact completely sealed graph produced by the owned factory. */
export const isValidatedImmutableJavaScriptApplicationGraph = (
value: unknown,
): value is JavaScriptApplicationGraph =>
typeof value === "object" &&
value !== null &&
validatedImmutableApplicationGraphs.has(value);
/** Parse a stored graph and reject stale IDs. */
export const parseJavaScriptApplicationGraph = (
input: unknown,
@@ -2,6 +2,7 @@ import { z } from "zod";
import { canonicalDigest, canonicalJson } from "../comparisonSemantics.js";
import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
import { freezeOwnedJsonSnapshotSteps } from "../immutableJson.js";
import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
import {
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
@@ -561,4 +562,28 @@ export const createJavaScriptSemanticGraph = (
return record;
};
const validatedImmutableSemanticGraphs = new WeakSet<object>();
/** Clone and validate synchronously, then return steps to seal the owned graph. */
export const createImmutableJavaScriptSemanticGraphSteps = (
input: unknown,
): Generator<void, JavaScriptSemanticGraph> =>
sealValidatedSemanticGraphSteps(createJavaScriptSemanticGraph(input));
function* sealValidatedSemanticGraphSteps(
graph: JavaScriptSemanticGraph,
): Generator<void, JavaScriptSemanticGraph> {
yield* freezeOwnedJsonSnapshotSteps(graph);
validatedImmutableSemanticGraphs.add(graph);
return graph;
}
/** Recognize the exact completely sealed graph produced by the owned factory. */
export const isValidatedImmutableJavaScriptSemanticGraph = (
value: unknown,
): value is JavaScriptSemanticGraph =>
typeof value === "object" &&
value !== null &&
validatedImmutableSemanticGraphs.has(value);
export type { JavaScriptSemanticGraphNode, JavaScriptSemanticGraphRelation };