feat(javascript): add bounded semantic relation graph
This commit is contained in:
@@ -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
|
||||
>;
|
||||
@@ -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
|
||||
>;
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user