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
@@ -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
>;