structured-context 0.11.0 → 0.13.0

package/dist/schema/gating.js

@@ -0,0 +1,253 @@
+import { judgeNodes } from '../judge/judge-node';
+import { buildEvalContext, evaluateRuleExpression, expressionErrorViolation, tryEvaluateExpression, } from './evaluate-rule';
+import { ruleSeverities, ruleSeverity } from './rule-severity';
+/**
+ * Whether a failure of this rule gates its subtree: explicit `gatesDescendants`, else true only for `error` severity.
+ * `severity` is that of the failure: the rule's own for an expression, the verdict's for a semantic part.
+ */
+export function ruleGatesDescendants(rule, severity = ruleSeverity(rule)) {
+    return rule.gatesDescendants ?? severity === 'error';
+}
+/** Whether any violation of this rule could gate its subtree. */
+function ruleCanGate(rule) {
+    return rule.gatesDescendants ?? ruleSeverities(rule).includes('error');
+}
+/**
+ * Compute breadth-first depth (1-based, from hierarchy roots and orphans) for every
+ * hierarchy-typed node in the graph. Non-hierarchy nodes are not included.
+ */
+export function computeHierarchyDepths(graph) {
+    const depths = new Map();
+    const queue = [];
+    for (const node of [...graph.hierarchyRoots, ...graph.orphans]) {
+        queue.push({ title: node.title, depth: 1 });
+    }
+    let i = 0;
+    while (i < queue.length) {
+        const { title, depth } = queue[i++];
+        if (depths.has(title))
+            continue;
+        depths.set(title, depth);
+        for (const child of graph.hierarchyChildren.get(title) ?? []) {
+            if (!depths.has(child.title))
+                queue.push({ title: child.title, depth: depth + 1 });
+        }
+    }
+    return depths;
+}
+/**
+ * Evaluate executable rules with cascade gating: a schema, hierarchy, or blocking-rule
+ * failure on a node suppresses rule evaluation for that node (when the failure is
+ * schema/hierarchy) and its hierarchy subtree, unless `includeGated` is set.
+ *
+ * Traversal is breadth-first from hierarchy roots and orphans. Non-hierarchy nodes
+ * (not part of the hierarchy DAG) are always evaluated — cascade gating only applies
+ * within hierarchy subtrees. Global rules always run, unaffected by gating.
+ */
+export async function evaluateRulesWithGating(nodes, rules, graph, seeds, options = {}) {
+    const includeGated = options.includeGated ?? false;
+    const nodeIndex = new Map();
+    for (const node of nodes) {
+        if (node.title)
+            nodeIndex.set(node.title, node);
+    }
+    // When a node has both a schema and hierarchy failure, report schema as the reason.
+    const seedByTitle = new Map();
+    for (const seed of seeds) {
+        if (!seedByTitle.has(seed.title) || seed.reason === 'schema') {
+            seedByTitle.set(seed.title, seed);
+        }
+    }
+    const judge = options.provider;
+    const violations = [];
+    const gateOrigins = new Map();
+    function originFor(title, seed) {
+        let origin = gateOrigins.get(title);
+        if (!origin) {
+            origin = { file: seed.file, nodeTitle: title, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] };
+            gateOrigins.set(title, origin);
+        }
+        return origin;
+    }
+    const globalRules = rules.filter((r) => r.global && r.expression !== undefined);
+    const sentinel = nodes[0];
+    if (sentinel) {
+        for (const rule of globalRules) {
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            if (!result.passed)
+                violations.push(result.violation);
+        }
+    }
+    const perNodeRules = rules.filter((r) => !r.global && (r.expression !== undefined || (r.semantic !== undefined && judge)));
+    // With a judge target, only the target and its hierarchy ancestors can need judging.
+    const targetAncestors = new Set();
+    if (options.judgeTarget !== undefined) {
+        const parentsOf = new Map();
+        for (const [parent, children] of graph.hierarchyChildren) {
+            for (const child of children)
+                parentsOf.set(child.title, [...(parentsOf.get(child.title) ?? []), parent]);
+        }
+        const target = nodes.find((n) => n.label === options.judgeTarget);
+        const pending = target ? [target.title] : [];
+        while (pending.length > 0) {
+            for (const parent of parentsOf.get(pending.pop()) ?? []) {
+                if (!targetAncestors.has(parent)) {
+                    targetAncestors.add(parent);
+                    pending.push(parent);
+                }
+            }
+        }
+    }
+    /** Rules that apply to this node: matching `type`, passing their `when` test, and (for a judge target) worth judging. */
+    async function applicableRules(node, onWhenError) {
+        const applicable = [];
+        for (const r of perNodeRules) {
+            if (r.type && r.type !== node.resolvedType)
+                continue;
+            if (judge &&
+                r.semantic !== undefined &&
+                options.judgeTarget !== undefined &&
+                node.label !== options.judgeTarget) {
+                // Ancestors only matter through the gates they could raise.
+                if (!(targetAncestors.has(node.title) && ruleCanGate(r)))
+                    continue;
+            }
+            if (r.when) {
+                const outcome = await tryEvaluateExpression(r.when, buildEvalContext(node, nodes, nodeIndex));
+                if ('error' in outcome) {
+                    onWhenError?.(r, outcome.error);
+                    continue;
+                }
+                if (outcome.value !== true)
+                    continue;
+            }
+            applicable.push(r);
+        }
+        return applicable;
+    }
+    async function prepareNode(node) {
+        const local = [];
+        const prepared = { violations: local, semantic: [], judged: () => { } };
+        const applicable = await applicableRules(node, (rule, error) => local.push(expressionErrorViolation(rule, node.label, error)));
+        function report(rule, detail = {}) {
+            const severity = detail.severity ?? ruleSeverities(rule)[0] ?? ruleSeverity(rule);
+            local.push({
+                file: node.label,
+                ruleId: rule.id,
+                category: rule.category,
+                severity,
+                description: detail.error
+                    ? `${rule.description} (Semantic evaluation error: ${detail.error})`
+                    : rule.description,
+                ...(detail.evidence !== undefined && { evidence: detail.evidence }),
+                ...(detail.verdict !== undefined && { verdict: detail.verdict }),
+                ...(detail.guidance !== undefined && { guidance: detail.guidance }),
+            });
+            // An evaluation error says nothing about the node, so it never gates.
+            if (!detail.error && ruleGatesDescendants(rule, severity) && !prepared.blockingRuleId) {
+                prepared.blockingRuleId = rule.id;
+            }
+        }
+        // Cheap expressions first; a semantic part is only evaluated when its own expression passes.
+        for (const rule of applicable) {
+            if (rule.expression !== undefined) {
+                const result = await evaluateRuleExpression(rule, node, nodes, nodeIndex);
+                if (!result.passed) {
+                    local.push(result.violation);
+                    if (result.failed && ruleGatesDescendants(rule, result.violation.severity) && !prepared.blockingRuleId) {
+                        prepared.blockingRuleId = rule.id;
+                    }
+                    continue;
+                }
+            }
+            if (rule.semantic !== undefined && judge)
+                prepared.semantic.push(rule);
+        }
+        prepared.judged = (judgements) => {
+            for (const j of judgements) {
+                if (j.failed) {
+                    report(j.rule, {
+                        severity: j.severity,
+                        verdict: j.verdict,
+                        guidance: j.guidance,
+                        evidence: j.evidence,
+                        error: j.error,
+                    });
+                }
+            }
+        };
+        return prepared;
+    }
+    /**
+     * Evaluate one set of nodes together, so their semantic rules go to the judge in one pass and a judge
+     * with `evaluateNodes` can share model calls. Gating for the set is already decided; violations are
+     * recorded in node order.
+     */
+    async function evaluateNodeSet(nodes) {
+        const prepared = [];
+        for (const node of nodes)
+            prepared.push(await prepareNode(node));
+        if (judge) {
+            const pending = nodes.map((node, i) => ({ node, rules: prepared[i].semantic }));
+            const judgements = await judgeNodes(judge, pending, graph, options.trimReport);
+            prepared.forEach((p, i) => {
+                p.judged(judgements[i] ?? []);
+            });
+        }
+        for (const p of prepared)
+            violations.push(...p.violations);
+        return prepared.map((p) => ({ blockingRuleId: p.blockingRuleId }));
+    }
+    // Non-hierarchy nodes sit outside the subtree cascade — always evaluated, never gated.
+    await evaluateNodeSet(graph.nonHierarchy);
+    const visited = new Set();
+    // Hierarchy nodes are judged one depth at a time: a node's verdicts decide whether its children are evaluated.
+    let depthNodes = [];
+    for (const node of [...graph.hierarchyRoots, ...graph.orphans]) {
+        depthNodes.push({ node, ancestorOrigin: undefined });
+    }
+    while (depthNodes.length > 0) {
+        const current = [];
+        for (const entry of depthNodes) {
+            if (visited.has(entry.node.title))
+                continue;
+            visited.add(entry.node.title);
+            current.push(entry);
+        }
+        const isGated = (e) => e.ancestorOrigin !== undefined || seedByTitle.has(e.node.title);
+        const toEvaluate = current.filter((e) => !isGated(e) || includeGated);
+        const evaluated = await evaluateNodeSet(toEvaluate.map((e) => e.node));
+        const blockingByTitle = new Map(toEvaluate.map((e, i) => [e.node.title, evaluated[i].blockingRuleId]));
+        const next = [];
+        for (const { node, ancestorOrigin } of current) {
+            const selfSeed = seedByTitle.get(node.title);
+            const isGatedByAncestor = ancestorOrigin !== undefined;
+            const isSelfBlocked = selfSeed !== undefined;
+            const blockingRuleId = blockingByTitle.get(node.title);
+            let childOrigin = ancestorOrigin;
+            if (isGatedByAncestor) {
+                gateOrigins.get(ancestorOrigin).gatedFiles.push(node.label);
+            }
+            else if (isSelfBlocked) {
+                const origin = originFor(node.title, { file: selfSeed.file, reason: selfSeed.reason });
+                origin.gatedFiles.push(node.label);
+                childOrigin = node.title;
+            }
+            else if (blockingRuleId) {
+                originFor(node.title, { file: node.label, reason: 'rule', ruleId: blockingRuleId });
+                childOrigin = node.title;
+            }
+            else {
+                childOrigin = undefined;
+            }
+            for (const child of graph.hierarchyChildren.get(node.title) ?? []) {
+                next.push({ node: child, ancestorOrigin: childOrigin });
+            }
+        }
+        depthNodes = next;
+    }
+    return {
+        violations,
+        gates: [...gateOrigins.values()].filter((g) => g.gatedFiles.length > 0),
+    };
+}

package/dist/schema/meta-schemas.d.ts

@@ -0,0 +1,13 @@
+import type { AnySchemaObject } from 'ajv';
+/** Version folders under `generatedDir` (named after the release that first shipped the dialect), oldest first. */
+export declare function listMetaVersions(generatedDir: string): string[];
+/** The newest released meta-schema and its version folder, if any. */
+export declare function readNewestMetaSchema(generatedDir: string): {
+    version: string;
+    schema: AnySchemaObject;
+} | undefined;
+/**
+ * Meta-schemas shipped in `<schemasDir>/generated/`, keyed by `$id`: every versioned folder at its own `$id`, and
+ * `latest` registered under the `latest` URL so `$schema` references to either form resolve.
+ */
+export declare function loadMetaSchemas(schemasDir: string): Map<string, AnySchemaObject>;

package/dist/schema/meta-schemas.js

@@ -0,0 +1,50 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCHEMA_META_FILE, SCHEMA_META_ID } from './metadata-contract';
+const LATEST_FOLDER = 'latest';
+const VERSION_FOLDER = /^\d+\.\d+\.\d+$/;
+function compareVersions(a, b) {
+    const [pa, pb] = [a, b].map((v) => v.split('.').map(Number));
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa?.[i] ?? 0) - (pb?.[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/** Version folders under `generatedDir` (named after the release that first shipped the dialect), oldest first. */
+export function listMetaVersions(generatedDir) {
+    if (!existsSync(generatedDir))
+        return [];
+    return readdirSync(generatedDir)
+        .filter((name) => VERSION_FOLDER.test(name))
+        .sort(compareVersions);
+}
+function readMetaSchema(generatedDir, folder) {
+    const path = join(generatedDir, folder, SCHEMA_META_FILE);
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf-8')) : undefined;
+}
+/** The newest released meta-schema and its version folder, if any. */
+export function readNewestMetaSchema(generatedDir) {
+    const version = listMetaVersions(generatedDir).at(-1);
+    const schema = version && readMetaSchema(generatedDir, version);
+    return version && schema ? { version, schema } : undefined;
+}
+/**
+ * Meta-schemas shipped in `<schemasDir>/generated/`, keyed by `$id`: every versioned folder at its own `$id`, and
+ * `latest` registered under the `latest` URL so `$schema` references to either form resolve.
+ */
+export function loadMetaSchemas(schemasDir) {
+    const generatedDir = join(schemasDir, 'generated');
+    const schemas = new Map();
+    for (const version of listMetaVersions(generatedDir)) {
+        const schema = readMetaSchema(generatedDir, version);
+        if (schema && typeof schema.$id === 'string')
+            schemas.set(schema.$id, schema);
+    }
+    // The `latest` copy carries its versioned `$id`, which a version folder may already own; register it under its own URL.
+    const latest = readMetaSchema(generatedDir, LATEST_FOLDER);
+    if (latest)
+        schemas.set(SCHEMA_META_ID, { ...latest, $id: SCHEMA_META_ID });
+    return schemas;
+}