feat(javascript): add bounded semantic relation graph

This commit is contained in:
morluto
2026-07-22 23:22:55 +00:00
parent a26a1c73df
commit b3939ea9ff
6 changed files with 2321 additions and 0 deletions
+546
View File
@@ -0,0 +1,546 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import { z } from "zod";
import { compareCodePoints } from "./javascriptApplicationGraph.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 canonicalJson = (value: unknown): string => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError(
"JavaScript semantic graph could not canonicalize data",
);
return encoded;
};
const digestCanonical = (value: unknown): string =>
createHash("sha256").update(canonicalJson(value)).digest("hex");
const uniqueSorted = <Value extends string>(
values: readonly Value[],
): Value[] => [...new Set(values)].sort(compareCodePoints);
const normalizeEvidence = (
evidence: ApplicationGraphEvidence,
): ApplicationGraphEvidence => ({
...evidence,
coverage: {
...evidence.coverage,
limits: [...evidence.coverage.limits].sort((left, right) =>
compareCodePoints(canonicalJson(left), canonicalJson(right)),
),
},
limitations: uniqueSorted(evidence.limitations),
evidence_ids: uniqueSorted(evidence.evidence_ids),
});
const nodeIdentity = (
node: Pick<JavaScriptSemanticGraphNode, "kind" | "identity">,
) => ({ kind: node.kind, identity: node.identity });
const nodeId = (
node: Pick<JavaScriptSemanticGraphNode, "kind" | "identity">,
): string => `jsrg_node_${digestCanonical(nodeIdentity(node))}`;
/** 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_${digestCanonical(semantic)}`,
});
};
/** 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_${digestCanonical(semantic)}`,
});
};
/** 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 = digestCanonical(semantic.components);
return javaScriptSemanticFingerprintSchema.parse({
...semantic,
fingerprint_sha256: fingerprintSha256,
fingerprint_id: `jsrg_fingerprint_${digestCanonical({
function_node_id: semantic.function_node_id,
algorithm: semantic.algorithm,
fingerprint_sha256: fingerprintSha256,
})}`,
});
};
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) !==
canonicalJson(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES)
)
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_" + digestCanonical(semantic))
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_" + digestCanonical(semantic))
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.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 !== digestCanonical(fingerprint.components)
)
context.addIssue({
code: "custom",
path: ["fingerprints", index, "fingerprint_sha256"],
message: "Fingerprint component commitment is stale",
});
const expectedIdentifier =
"jsrg_fingerprint_" +
digestCanonical({
function_node_id: fingerprint.function_node_id,
algorithm: fingerprint.algorithm,
fingerprint_sha256: fingerprint.fingerprint_sha256,
});
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_" + digestCanonical(semantic))
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 v1. */
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), canonicalJson(right)),
),
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_${digestCanonical(semantic)}`,
});
};
/** Parse a stored semantic graph and reject unsupported versions or stale IDs. */
export const parseJavaScriptSemanticGraph = (
input: unknown,
): JavaScriptSemanticGraph => {
const envelope = z
.object({ schema: z.string(), schema_version: z.number() })
.passthrough()
.safeParse(input);
if (
envelope.success &&
envelope.data.schema === "JavaScriptSemanticRelationGraph" &&
envelope.data.schema_version !== 1
)
throw new TypeError(
`Unsupported JavaScript Semantic Relation Graph schema version: ${String(envelope.data.schema_version)}`,
);
return javaScriptSemanticGraphSchema.parse(input);
};
/** Serialize a verified semantic graph as canonical JSON. */
export const serializeJavaScriptSemanticGraph = (input: unknown): string =>
canonicalJson(parseJavaScriptSemanticGraph(input));
/** Compute the canonical SHA-256 commitment of a verified semantic graph. */
export const computeJavaScriptSemanticGraphSha256 = (input: unknown): string =>
digestCanonical(parseJavaScriptSemanticGraph(input));
export type { JavaScriptSemanticGraphNode, JavaScriptSemanticGraphRelation };
@@ -0,0 +1,393 @@
import { z } from "zod";
import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
import { isJsonWithinLimits } from "./jsonLimits.js";
import { jsonValueSchema } from "./jsonValue.js";
const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
const boundedTextSchema = z.string().min(1).max(4_096);
const semanticNodeIdSchema = z.string().regex(/^jsrg_node_[a-f0-9]{64}$/u);
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 v1. */
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 graph v1. */
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)
.max(4_096)
.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).max(128), jsonValueSchema)
.superRefine((properties, context) => {
if (Object.keys(properties).length > 64)
context.addIssue({
code: "custom",
message: "Semantic properties exceed 64 keys",
});
if (
!isJsonWithinLimits(properties, {
maxDepth: 6,
maxNodes: 512,
maxStringLength: 4_096,
})
)
context.addIssue({
code: "custom",
message: "Semantic properties exceed structural limits",
});
});
const semanticNodeIdentitySchema = z.strictObject({
artifact_sha256: digestSchema,
module_path: relativePathSchema,
source_range: sourceRangeSchema.nullable(),
role_key: z.string().min(1).max(1_024),
});
/** 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(z.string().regex(/^jag_node_[a-f0-9]{64}$/u))
.max(64),
label: z.string().min(1).max(1_024).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",
"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).max(45),
reason: z.enum(JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS),
detail: boundedTextSchema,
candidate_node_ids: z.array(semanticNodeIdSchema).max(1_000),
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).max(10_000),
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",
]),
)
.max(7),
});
/** One bounded rename-resistant function fingerprint. */
export const javaScriptSemanticFingerprintInputSchema = z.strictObject({
function_node_id: semanticNodeIdSchema,
algorithm: z.literal("rea.javascript-semantic-function/v1"),
status: z.enum(["complete", "partial", "unavailable"]),
components: fingerprintComponentsSchema,
limitations: z.array(boundedTextSchema).max(100),
evidence: applicationGraphEvidenceSchema,
});
/** One canonical function fingerprint record. */
export const javaScriptSemanticFingerprintSchema =
javaScriptSemanticFingerprintInputSchema.extend({
fingerprint_id: z.string().regex(/^jsrg_fingerprint_[a-f0-9]{64}$/u),
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).max(100_000),
});
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).max(128),
value: z.number().int().min(0),
unit: z.enum(["items", "bytes", "milliseconds", "depth", "other"]),
}),
)
.max(32),
families: z.array(familyCoverageSchema).length(12),
});
/** Graph content before its top-level commitment is derived. */
export const javaScriptSemanticGraphInputSchema = z.strictObject({
schema: z.literal("JavaScriptSemanticRelationGraph"),
schema_version: z.literal(1),
root_artifact_sha256: digestSchema,
application_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
root_node_ids: z.array(semanticNodeIdSchema).min(1).max(10_000),
nodes: z.array(javaScriptSemanticNodeSchema).min(1).max(100_000),
relations: z.array(javaScriptSemanticRelationSchema).max(200_000),
fingerprints: z.array(javaScriptSemanticFingerprintSchema).max(20_000),
unknowns: z.array(javaScriptSemanticUnknownSchema).max(100_000),
coverage: graphCoverageSchema,
limitations: z.array(boundedTextSchema).max(1_000),
});
/** Stored JavaScript Semantic Relation Graph v1. */
export const javaScriptSemanticGraphRecordSchema =
javaScriptSemanticGraphInputSchema.extend({
graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
});
/** 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
>;
+568
View File
@@ -0,0 +1,568 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import { compareCodePoints } from "./javascriptApplicationGraph.js";
import type {
JavaScriptSemanticGraph,
JavaScriptSemanticGraphNode,
JavaScriptSemanticGraphRelation,
} from "./javascriptSemanticGraph.js";
import {
JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
type JavaScriptSemanticGraphUnknown,
} from "./javascriptSemanticGraphSchemas.js";
import {
javaScriptSemanticQueryInputSchema,
javaScriptSemanticQueryResultSchema,
type JavaScriptSemanticQueryInput,
type JavaScriptSemanticQueryResult,
} from "./javascriptSemanticQuerySchemas.js";
import {
assessJavaScriptSemanticQuery,
type JavaScriptSemanticQueryFrontier,
} from "./javascriptSemanticQueryAssessment.js";
interface TraversalEntry {
readonly relation: JavaScriptSemanticGraphRelation;
readonly nextNodeId: string;
}
type QueryFrontier = JavaScriptSemanticQueryFrontier;
interface Traversal {
readonly nodeIds: Set<string>;
readonly relationIds: Set<string>;
readonly functionIds: Set<string>;
readonly modules: Set<string>;
readonly frontier: QueryFrontier[];
}
interface SeedAdmission {
readonly nodeIds: string[];
readonly frontier: QueryFrontier[];
}
const canonicalJson = (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(canonicalJson(value)).digest("hex");
const uniqueSorted = (values: readonly string[]): string[] =>
[...new Set(values)].sort(compareCodePoints);
/** Run one deterministic bounded 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 offset = parseCursor(input.cursor, queryId);
const seeds = resolveSeeds(graph, input);
const admission = admitSeeds(graph, seeds, input);
const retainedSeeds = admission.nodeIds;
const adjacency = buildAdjacency(graph.relations, input);
const traversal = traverse(graph, retainedSeeds, adjacency, input);
const frontier = uniqueFrontier([
...traversal.frontier,
...admission.frontier,
]);
const retainedNodes = graph.nodes.filter(({ node_id }) =>
traversal.nodeIds.has(node_id),
);
const retainedRelations = graph.relations.filter(({ relation_id }) =>
traversal.relationIds.has(relation_id),
);
if (offset > retainedRelations.length)
throw new TypeError("Semantic query cursor is beyond the retained result");
const pageRelations = retainedRelations.slice(
offset,
offset + input.limits.page_size,
);
const pageNodeIds = new Set([
...retainedSeeds,
...pageRelations.flatMap(({ source_node_id, target_node_id }) => [
source_node_id,
target_node_id,
]),
]);
const pageNodes = graph.nodes.filter(({ node_id }) =>
pageNodeIds.has(node_id),
);
const relevantUnknowns = relevantUnknownFrontiers(
graph,
traversal.nodeIds,
input,
);
const expectedMatches = expectedMatchesFor(
retainedNodes,
retainedRelations,
input,
);
const assessment = assessJavaScriptSemanticQuery({
graph,
totalSeeds: seeds.length,
retainedSeeds: retainedSeeds.length,
expectedMatches: expectedMatches.length,
hasExpectation: input.expected !== null,
frontier,
unknowns: relevantUnknowns,
});
const nextOffset = offset + pageRelations.length;
const nextCursor =
nextOffset < retainedRelations.length
? createCursor(queryId, nextOffset)
: null;
return javaScriptSemanticQueryResultSchema.parse({
schema_version: 1,
query_id: queryId,
source_graph_id: graph.graph_id,
seed: input.seed,
direction: input.direction,
status: assessment.status,
seed_node_ids: retainedSeeds,
nodes: pageNodes,
relations: pageRelations,
unknowns: relevantUnknowns,
expected_match_node_ids: expectedMatches.map(({ node_id }) => node_id),
summary: {
total_seed_matches: seeds.length,
retained_seed_matches: retainedSeeds.length,
traversed_nodes: traversal.nodeIds.size,
traversed_relations: traversal.relationIds.size,
traversed_functions: traversal.functionIds.size,
traversed_modules: traversal.modules.size,
relevant_unknowns: relevantUnknowns.length,
},
coverage: assessment.coverage,
page: {
offset,
size: pageRelations.length,
next_cursor: nextCursor,
},
applied_limits: input.limits,
accepted_limit_ranges: assessment.acceptedLimitRanges,
limitations: assessment.limitations,
});
};
const queryIdentifier = (
graph: JavaScriptSemanticGraph,
input: JavaScriptSemanticQueryInput,
): string => {
const { cursor: _cursor, ...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),
},
})}`;
};
const createCursor = (queryId: string, offset: number): string =>
`jsrqc_${String(offset)}_${digest({ query_id: queryId, offset })}`;
const parseCursor = (cursor: string | null, queryId: string): number => {
if (cursor === null) return 0;
const match = /^jsrqc_([0-9]+)_([a-f0-9]{64})$/u.exec(cursor);
const offsetText = match?.[1];
const commitment = match?.[2];
if (offsetText === undefined || commitment === undefined)
throw new TypeError("Semantic query cursor is malformed");
const offset = Number(offsetText);
if (
!Number.isSafeInteger(offset) ||
offset < 0 ||
commitment !== digest({ query_id: queryId, offset })
)
throw new TypeError("Semantic query cursor does not match this query");
return offset;
};
const resolveSeeds = (
graph: JavaScriptSemanticGraph,
input: JavaScriptSemanticQueryInput,
): string[] => {
const fingerprintFunctions = new Set(
input.seed.kind === "function"
? graph.fingerprints
.filter(({ fingerprint_sha256 }) => {
const seed = input.seed;
return (
seed.kind === "function" &&
fingerprint_sha256 === 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" &&
canonicalJson(node.properties.value) === canonicalJson(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;
};
const admitSeeds = (
graph: JavaScriptSemanticGraph,
seeds: readonly string[],
input: JavaScriptSemanticQueryInput,
): SeedAdmission => {
const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
const retained: string[] = [];
const functions = new Set<string>();
const modules = new Set<string>();
const frontier: QueryFrontier[] = [];
for (const nodeId of seeds) {
const node = nodes.get(nodeId);
if (node === undefined) continue;
const reason = seedBlockedReason(node, {
retained,
functions,
modules,
input,
});
if (reason !== null) {
frontier.push({ node_id: nodeId, depth: 0, reason });
continue;
}
retained.push(nodeId);
retainOwners(node, functions, modules);
}
return { nodeIds: retained, frontier: uniqueFrontier(frontier) };
};
interface SeedBounds {
readonly retained: readonly string[];
readonly functions: ReadonlySet<string>;
readonly modules: ReadonlySet<string>;
readonly input: JavaScriptSemanticQueryInput;
}
interface TraversalBounds {
readonly nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>;
readonly nodeIds: ReadonlySet<string>;
readonly relationIds: ReadonlySet<string>;
readonly functionIds: ReadonlySet<string>;
readonly modules: ReadonlySet<string>;
readonly input: JavaScriptSemanticQueryInput;
}
const seedBlockedReason = (
node: JavaScriptSemanticGraphNode,
bounds: SeedBounds,
): QueryFrontier["reason"] | null => {
if (bounds.retained.length >= bounds.input.limits.max_seed_matches)
return "max-seed-matches";
if (bounds.retained.length >= bounds.input.limits.max_nodes)
return "max-nodes";
const functionId = functionOwner(node);
if (
functionId !== null &&
!bounds.functions.has(functionId) &&
bounds.functions.size >= bounds.input.limits.max_functions
)
return "max-functions";
if (
!bounds.modules.has(node.identity.module_path) &&
bounds.modules.size >= bounds.input.limits.max_modules
)
return "max-modules";
return null;
};
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 ownershipRelation = (
relation: JavaScriptSemanticGraphRelation["relation"],
): boolean =>
[
"acquires",
"aggregates",
"awaits",
"chains",
"connects-stdio",
"creates-promise",
"detaches-task",
"owns",
"releases",
"returns-task",
"spawns",
].includes(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[]>,
input: JavaScriptSemanticQueryInput,
): 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 frontier: QueryFrontier[] = [];
for (const nodeId of nodeIds)
retainOwners(nodes.get(nodeId), functionIds, modules);
const depths = new Map([...nodeIds].map((nodeId) => [nodeId, 0]));
const queue = [...nodeIds];
const bounds: TraversalBounds = {
nodes,
nodeIds,
relationIds,
functionIds,
modules,
input,
};
for (let offset = 0; offset < queue.length; offset += 1) {
const current = queue[offset];
if (current === undefined) continue;
const depth = depths.get(current) ?? 0;
for (const entry of adjacency.get(current) ?? []) {
const reason = blockedReason(entry, depth, bounds);
if (reason !== null) {
frontier.push({ node_id: current, depth, reason });
continue;
}
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);
depths.set(entry.nextNodeId, depth + 1);
queue.push(entry.nextNodeId);
}
}
return {
nodeIds,
relationIds,
functionIds,
modules,
frontier: uniqueFrontier(frontier),
};
};
const blockedReason = (
entry: TraversalEntry,
depth: number,
bounds: TraversalBounds,
): QueryFrontier["reason"] | null => {
if (depth >= bounds.input.limits.max_depth) return "max-depth";
if (
!bounds.relationIds.has(entry.relation.relation_id) &&
bounds.relationIds.size >= bounds.input.limits.max_edges
)
return "max-edges";
if (bounds.nodeIds.has(entry.nextNodeId)) return null;
if (bounds.nodeIds.size >= bounds.input.limits.max_nodes) return "max-nodes";
const node = bounds.nodes.get(entry.nextNodeId);
if (node === undefined) return null;
const functionId = functionOwner(node);
if (
functionId !== null &&
!bounds.functionIds.has(functionId) &&
bounds.functionIds.size >= bounds.input.limits.max_functions
)
return "max-functions";
if (
!bounds.modules.has(node.identity.module_path) &&
bounds.modules.size >= bounds.input.limits.max_modules
)
return "max-modules";
return null;
};
const retainOwners = (
node: JavaScriptSemanticGraphNode | undefined,
functions: Set<string>,
modules: Set<string>,
): void => {
if (node === undefined) return;
const functionId = functionOwner(node);
if (functionId !== null) functions.add(functionId);
modules.add(node.identity.module_path);
};
const functionOwner = (node: JavaScriptSemanticGraphNode): string | null =>
node.kind === "function" ? node.node_id : node.function_node_id;
const uniqueFrontier = (frontier: readonly QueryFrontier[]): QueryFrontier[] =>
[
...new Map(
frontier.map((item) => [
`${item.node_id}\0${String(item.depth)}\0${item.reason}`,
item,
]),
).values(),
].sort((left, right) =>
compareCodePoints(canonicalJson(left), canonicalJson(right)),
);
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 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),
);
};
/** Return a relation's declared semantic coverage family. */
export const javaScriptSemanticRelationFamily = (
relation: JavaScriptSemanticGraphRelation["relation"],
) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation];
@@ -0,0 +1,110 @@
import { compareCodePoints } from "./javascriptApplicationGraph.js";
import type { JavaScriptSemanticGraph } from "./javascriptSemanticGraph.js";
import type { JavaScriptSemanticGraphUnknown } from "./javascriptSemanticGraphSchemas.js";
import type { JavaScriptSemanticQueryResult } from "./javascriptSemanticQuerySchemas.js";
/** One caller-limit frontier retained by deterministic query traversal. */
export interface JavaScriptSemanticQueryFrontier {
readonly node_id: string;
readonly depth: number;
readonly reason:
| "max-depth"
| "max-edges"
| "max-functions"
| "max-modules"
| "max-nodes"
| "max-seed-matches";
}
/** Inputs needed to classify one completed semantic traversal. */
export interface JavaScriptSemanticQueryAssessmentInput {
readonly graph: JavaScriptSemanticGraph;
readonly totalSeeds: number;
readonly retainedSeeds: number;
readonly expectedMatches: number;
readonly hasExpectation: boolean;
readonly frontier: readonly JavaScriptSemanticQueryFrontier[];
readonly unknowns: readonly JavaScriptSemanticGraphUnknown[];
}
/** Status, coverage, limits, and limitations derived from one traversal. */
export interface JavaScriptSemanticQueryAssessment {
readonly status: JavaScriptSemanticQueryResult["status"];
readonly coverage: JavaScriptSemanticQueryResult["coverage"];
readonly limitations: string[];
readonly acceptedLimitRanges: JavaScriptSemanticQueryResult["accepted_limit_ranges"];
}
/** Classify a bounded semantic traversal without promoting unknowns to absence. */
export const assessJavaScriptSemanticQuery = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryAssessment => ({
status: queryStatus(input),
coverage: queryCoverage(input),
limitations: queryLimitations(input),
acceptedLimitRanges: {
max_seed_matches: { minimum: 1, maximum: 1_000 },
max_nodes: { minimum: 1, maximum: 50_000 },
max_edges: { minimum: 1, maximum: 100_000 },
max_depth: { minimum: 0, maximum: 64 },
max_functions: { minimum: 1, maximum: 10_000 },
max_modules: { minimum: 1, maximum: 10_000 },
page_size: { minimum: 1, maximum: 1_000 },
},
});
const queryCoverage = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryResult["coverage"] => ({
status:
input.graph.coverage.status === "unavailable"
? "unavailable"
: input.frontier.length > 0
? "truncated"
: input.unknowns.length > 0 ||
input.graph.coverage.status !== "complete"
? "partial"
: "complete",
frontier: [...input.frontier],
});
const queryStatus = (
input: JavaScriptSemanticQueryAssessmentInput,
): JavaScriptSemanticQueryResult["status"] => {
if (input.graph.coverage.status === "unavailable") return "unsupported";
if (input.frontier.length > 0) return "truncated";
if (input.unknowns.length > 0 || input.graph.coverage.status !== "complete")
return "partial";
if (
input.totalSeeds === 0 ||
(input.hasExpectation && input.expectedMatches === 0)
)
return "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.totalSeeds === input.retainedSeeds
? []
: [
"Seed matches exceeded caller bounds; omitted starts remain unexplored.",
]),
...(input.frontier.length === 0
? []
: [
"Traversal stopped at explicit caller limits; frontier facts remain unknown.",
]),
...(input.unknowns.length === 0
? []
: [
"Relevant dynamic, unsupported, incomplete, or ambiguous semantics remain unknown.",
]),
]);
const uniqueSorted = (values: readonly string[]): string[] =>
[...new Set(values)].sort(compareCodePoints);
@@ -0,0 +1,227 @@
import { z } from "zod";
import {
JAVASCRIPT_SEMANTIC_NODE_KINDS,
JAVASCRIPT_SEMANTIC_RELATIONS,
javaScriptSemanticNodeSchema,
javaScriptSemanticRelationSchema,
javaScriptSemanticUnknownSchema,
} from "./javascriptSemanticGraphSchemas.js";
import { jsonValueSchema } from "./jsonValue.js";
const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
const semanticNodeIdSchema = z.string().regex(/^jsrg_node_[a-f0-9]{64}$/u);
const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
/** Exact accepted ranges and defaults for one semantic traversal. */
export const JAVASCRIPT_SEMANTIC_QUERY_LIMIT_RANGES = {
max_seed_matches: { minimum: 1, maximum: 1_000, default: 25 },
max_nodes: { minimum: 1, maximum: 50_000, default: 2_000 },
max_edges: { minimum: 1, maximum: 100_000, default: 4_000 },
max_depth: { minimum: 0, maximum: 64, default: 12 },
max_functions: { minimum: 1, maximum: 10_000, default: 500 },
max_modules: { minimum: 1, maximum: 10_000, default: 500 },
page_size: { minimum: 1, maximum: 1_000, default: 200 },
} as const;
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: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
}),
literalSeedSchema,
z.strictObject({
kind: z.literal("function"),
fingerprint_sha256: digestSchema,
}),
z.strictObject({
kind: z.literal("property"),
name: z.string().min(1).max(4_096),
}),
z.strictObject({
kind: z.literal("endpoint"),
value: z.string().min(1).max(16_384),
}),
z.strictObject({
kind: z.literal("event"),
name: z.string().min(1).max(4_096),
}),
z.strictObject({
kind: z.literal("boundary-field"),
field: z.string().min(1).max(4_096),
}),
]);
/** Strict caller limits for deterministic bounded traversal. */
export const javaScriptSemanticQueryLimitsSchema = z.strictObject({
max_seed_matches: z.number().int().min(1).max(1_000).default(25),
max_nodes: z.number().int().min(1).max(50_000).default(2_000),
max_edges: z.number().int().min(1).max(100_000).default(4_000),
max_depth: z.number().int().min(0).max(64).default(12),
max_functions: z.number().int().min(1).max(10_000).default(500),
max_modules: z.number().int().min(1).max(10_000).default(500),
page_size: z.number().int().min(1).max(1_000).default(200),
});
const sourceMapAuthoritySchema = z.discriminatedUnion("authority", [
z.strictObject({ authority: z.literal("none") }),
z.strictObject({
authority: z.literal("authenticated"),
evidence_id: evidenceIdSchema,
source_map_sha256: digestSchema,
}),
]);
/** Parsed pure-domain query over one authenticated companion graph. */
export const javaScriptSemanticQueryInputSchema = z.strictObject({
seed: javaScriptSemanticQuerySeedSchema,
direction: z.enum([
"backward-provenance",
"forward-influence",
"callers",
"consumers",
"ownership",
]),
allowed_relations: z
.array(z.enum(JAVASCRIPT_SEMANTIC_RELATIONS))
.min(1)
.max(JAVASCRIPT_SEMANTIC_RELATIONS.length)
.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).max(24),
})
.nullable()
.default(null),
source_map_authority: sourceMapAuthoritySchema.default({ authority: "none" }),
limits: javaScriptSemanticQueryLimitsSchema.default({
max_seed_matches: 25,
max_nodes: 2_000,
max_edges: 4_000,
max_depth: 12,
max_functions: 500,
max_modules: 500,
page_size: 200,
}),
cursor: z
.string()
.regex(/^jsrqc_[0-9]+_[a-f0-9]{64}$/u)
.nullable()
.default(null),
});
const queryFrontierSchema = z.strictObject({
node_id: semanticNodeIdSchema,
depth: z.number().int().min(0).max(65),
reason: z.enum([
"max-depth",
"max-edges",
"max-functions",
"max-modules",
"max-nodes",
"max-seed-matches",
]),
});
/** Deterministic, pageable semantic trace result. */
export const javaScriptSemanticQueryResultSchema = z.strictObject({
schema_version: z.literal(1),
query_id: z.string().regex(/^jsrq_[a-f0-9]{64}$/u),
source_graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
seed: javaScriptSemanticQuerySeedSchema,
direction: javaScriptSemanticQueryInputSchema.shape.direction,
status: z.enum([
"found",
"no-match",
"ambiguous",
"partial",
"truncated",
"unsupported",
]),
seed_node_ids: z.array(semanticNodeIdSchema).max(1_000),
nodes: z.array(javaScriptSemanticNodeSchema).max(3_000),
relations: z.array(javaScriptSemanticRelationSchema).max(1_000),
unknowns: z.array(javaScriptSemanticUnknownSchema).max(100_000),
expected_match_node_ids: z.array(semanticNodeIdSchema).max(50_000),
summary: z.strictObject({
total_seed_matches: z.number().int().min(0),
retained_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", "truncated", "unavailable"]),
frontier: z.array(queryFrontierSchema).max(100_000),
}),
page: z.strictObject({
offset: z.number().int().min(0),
size: z.number().int().min(0).max(1_000),
next_cursor: z
.string()
.regex(/^jsrqc_[0-9]+_[a-f0-9]{64}$/u)
.nullable(),
}),
applied_limits: javaScriptSemanticQueryLimitsSchema,
accepted_limit_ranges: z.strictObject({
max_seed_matches: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(1_000),
}),
max_nodes: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(50_000),
}),
max_edges: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(100_000),
}),
max_depth: z.strictObject({
minimum: z.literal(0),
maximum: z.literal(64),
}),
max_functions: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(10_000),
}),
max_modules: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(10_000),
}),
page_size: z.strictObject({
minimum: z.literal(1),
maximum: z.literal(1_000),
}),
}),
limitations: z.array(z.string().min(1).max(4_096)).max(1_000),
});
/** Validated semantic query input. */
export type JavaScriptSemanticQueryInput = z.infer<
typeof javaScriptSemanticQueryInputSchema
>;
/** Validated semantic query result. */
export type JavaScriptSemanticQueryResult = z.infer<
typeof javaScriptSemanticQueryResultSchema
>;
+477
View File
@@ -0,0 +1,477 @@
import { describe, expect, it } from "vitest";
import type { ApplicationGraphEvidence } from "../src/domain/javascriptApplicationEvidenceSchemas.js";
import {
JAVASCRIPT_SEMANTIC_NODE_KINDS,
JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
JAVASCRIPT_SEMANTIC_RELATIONS,
} from "../src/domain/javascriptSemanticGraphSchemas.js";
import {
createJavaScriptSemanticFingerprint,
createJavaScriptSemanticGraph,
createJavaScriptSemanticGraphNode,
createJavaScriptSemanticGraphRelation,
createJavaScriptSemanticGraphUnknown,
parseJavaScriptSemanticGraph,
serializeJavaScriptSemanticGraph,
type JavaScriptSemanticGraph,
type JavaScriptSemanticGraphNode,
} from "../src/domain/javascriptSemanticGraph.js";
import { queryJavaScriptSemanticGraph } from "../src/domain/javascriptSemanticQuery.js";
import { javaScriptSemanticQueryInputSchema } from "../src/domain/javascriptSemanticQuerySchemas.js";
const SHA = "a".repeat(64);
const JAG_ID = `jag_${"b".repeat(64)}`;
const completeCoverage = {
status: "complete" as const,
truncated: false,
omitted_count: 0,
limits: [],
};
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> = {},
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/v1",
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",
schema_version: 1,
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,
),
},
});
};
const graphWithDuplicateLiteral = (): JavaScriptSemanticGraph => {
const graph = fixtureGraph();
const duplicate = node("literal", "literal-copy", { value: "TOKEN" });
const { graph_id: _graphId, ...input } = graph;
return createJavaScriptSemanticGraph({
...input,
nodes: [...graph.nodes, duplicate],
});
};
describe("JavaScript semantic relation graph", () => {
it("defines every required v1 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);
});
});
describe("JavaScript semantic query", () => {
it("traces deterministic forward influence and pages without changing identity", () => {
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] },
limits: {
max_seed_matches: 25,
max_nodes: 20,
max_edges: 20,
max_depth: 12,
max_functions: 10,
max_modules: 10,
page_size: 2,
},
};
const first = queryJavaScriptSemanticGraph(graph, input);
expect(first).toMatchObject({
status: "found",
summary: { traversed_nodes: 4, traversed_relations: 3 },
page: { offset: 0, size: 2 },
});
expect(first.expected_match_node_ids).toHaveLength(1);
expect(first.page.next_cursor).not.toBeNull();
const second = queryJavaScriptSemanticGraph(graph, {
...input,
cursor: first.page.next_cursor,
});
expect(second.query_id).toBe(first.query_id);
expect(second.page).toMatchObject({
offset: 2,
size: 1,
next_cursor: null,
});
expect(second.relations[0]?.relation_id).not.toBe(
first.relations[0]?.relation_id,
);
});
it("keeps relevant dynamic frontiers unknown", () => {
const result = queryJavaScriptSemanticGraph(fixtureGraph(true), {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
});
expect(result.status).toBe("partial");
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(optedIn.relations).toMatchObject([
{ relation: "supplies-request-field", resolution: "candidate" },
]);
});
it("bounds seed ambiguity before traversal", () => {
const result = queryJavaScriptSemanticGraph(graphWithDuplicateLiteral(), {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
limits: {
max_seed_matches: 1,
max_nodes: 20,
max_edges: 20,
max_depth: 12,
max_functions: 10,
max_modules: 10,
page_size: 10,
},
});
expect(result.summary).toMatchObject({
total_seed_matches: 2,
retained_seed_matches: 1,
});
expect(result.status).toBe("truncated");
expect(result.coverage.frontier).toContainEqual(
expect.objectContaining({ reason: "max-seed-matches", depth: 0 }),
);
});
it("reports exact caller limits and a deterministic truncation frontier", () => {
const result = queryJavaScriptSemanticGraph(fixtureGraph(), {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
limits: {
max_seed_matches: 1,
max_nodes: 2,
max_edges: 10,
max_depth: 12,
max_functions: 10,
max_modules: 10,
page_size: 10,
},
});
expect(result.status).toBe("truncated");
expect(result.coverage.frontier).toMatchObject([{ reason: "max-nodes" }]);
expect(result.applied_limits.max_nodes).toBe(2);
expect(result.accepted_limit_ranges.max_nodes).toEqual({
minimum: 1,
maximum: 50_000,
});
});
it.each([
{
limit: { max_edges: 1 },
reason: "max-edges",
},
{
limit: { max_depth: 0 },
reason: "max-depth",
},
])("reports the $reason frontier", ({ limit, reason }) => {
const result = queryJavaScriptSemanticGraph(fixtureGraph(), {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
limits: {
max_seed_matches: 10,
max_nodes: 20,
max_edges: limit.max_edges ?? 20,
max_depth: limit.max_depth ?? 12,
max_functions: 10,
max_modules: 10,
page_size: 10,
},
});
expect(result.status).toBe("truncated");
expect(result.coverage.frontier).toContainEqual(
expect.objectContaining({ reason }),
);
});
it("rejects out-of-range limits and cursors from another query", () => {
expect(() =>
javaScriptSemanticQueryInputSchema.parse({
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
limits: { max_nodes: 50_001 },
}),
).toThrow();
const graph = fixtureGraph();
const first = queryJavaScriptSemanticGraph(graph, {
seed: { kind: "literal", value: "TOKEN" },
direction: "forward-influence",
limits: { page_size: 1 },
});
expect(() =>
queryJavaScriptSemanticGraph(graph, {
seed: { kind: "endpoint", value: "https://example.invalid/v1" },
direction: "backward-provenance",
limits: { page_size: 1 },
cursor: first.page.next_cursor,
}),
).toThrow(/cursor does not match/u);
});
});