structured-context 0.12.0 → 0.13.0

package/dist/schema/metadata-contract.js

@@ -43,20 +43,126 @@ const HIERARCHY_LEVEL_SCHEMA = {
     required: ['type'],
     additionalProperties: false,
 };
+const SEVERITY_SCHEMA = { enum: ['error', 'warning', 'info'] };
+/** The verdicts the evaluation reserves besides a rule's own; a verdict map may set a severity for them. */
+export const RESERVED_VERDICTS = ['missing-context'];
+/** Related-node kinds a semantic rule's `scope` can add: main-hierarchy edges only. `branch` is ancestors plus descendants. */
+export const SEMANTIC_SCOPES = ['parent', 'siblings', 'children', 'ancestors', 'descendants', 'branch'];
+const VERDICT_SEVERITY_SCHEMA = { enum: ['error', 'warning', 'info', 'ignore'] };
+/** The semantic part of a rule: a model evaluates the node against a rubric and returns a verdict. */
+const SEMANTIC_SCHEMA = {
+    type: 'object',
+    properties: {
+        /** What the model judges the node against. Falls back to the rule's `description`. */
+        rubric: { type: 'string', minLength: 1 },
+        /**
+         * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+         * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+         * Defaults to `pass`/`fail`.
+         */
+        verdicts: {
+            type: 'object',
+            additionalProperties: {
+                oneOf: [
+                    { type: 'string', minLength: 1 },
+                    {
+                        type: 'object',
+                        properties: { description: { type: 'string', minLength: 1 }, guidance: { type: 'string', minLength: 1 } },
+                        required: ['description'],
+                        additionalProperties: false,
+                    },
+                ],
+            },
+            minProperties: 2,
+        },
+        /**
+         * Severity per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+         * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+         * takes the rule's own `severity` instead.
+         */
+        severity: {
+            type: 'object',
+            additionalProperties: VERDICT_SEVERITY_SCHEMA,
+            minProperties: 1,
+        },
+        /**
+         * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+         * the evaluated node alone.
+         */
+        scope: {
+            type: 'array',
+            items: { enum: SEMANTIC_SCOPES },
+            uniqueItems: true,
+        },
+        /**
+         * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+         * or `true` for `fullScope`. Left out: no bodies.
+         */
+        includeContent: { enum: ['nodeOnly', 'fullScope', true] },
+    },
+    additionalProperties: false,
+};
 const RULE_SCHEMA = {
     type: 'object',
     properties: {
         id: { type: 'string', minLength: 1 },
         category: { enum: ['validation', 'coherence', 'workflow', 'best-practice'] },
-        severity: { enum: ['error', 'warning', 'info'] },
+        /**
+         * Severity of a failed `expression` and of the default `fail` verdict. Defaults from the category.
+         */
+        severity: SEVERITY_SCHEMA,
         description: { type: 'string', minLength: 1 },
-        check: { type: 'string', minLength: 1 },
+        /** JSONata test a node must pass. When the rule also has `semantic`, a failing node is reported without being evaluated by the model. */
+        expression: { type: 'string', minLength: 1 },
+        /** Optional JSONata applicability condition, evaluated per node before the rule runs. The rule applies only when it returns true. */
+        when: { type: 'string', minLength: 1 },
+        /** A model evaluates the node against a rubric. `{}` takes every default; `true` means the same. */
+        semantic: { oneOf: [{ const: true }, SEMANTIC_SCHEMA] },
         type: { type: 'string', minLength: 1 },
-        scope: { enum: ['global'] },
+        /** Run once for the whole space instead of once per node. */
+        global: { type: 'boolean' },
         override: { type: 'boolean' },
+        /** Whether a failure of this rule gates (suppresses) downstream rules on the node's hierarchy subtree. Defaults to true when the failure's severity is `error`. */
+        gatesDescendants: { type: 'boolean' },
     },
-    required: ['id', 'category', 'description', 'check'],
+    required: ['id', 'category', 'description'],
     additionalProperties: false,
+    allOf: [
+        // A rule has an expression, a semantic part, or both.
+        { anyOf: [{ required: ['expression'] }, { required: ['semantic'] }] },
+        // A global rule has no node to apply to or to evaluate.
+        {
+            if: { required: ['global'], properties: { global: { const: true } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { not: { anyOf: [{ required: ['when'] }, { required: ['type'] }, { required: ['semantic'] }] } },
+        },
+        // Custom verdicts need a severity for each failing verdict.
+        {
+            if: { required: ['semantic'], properties: { semantic: { type: 'object', required: ['verdicts'] } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { properties: { semantic: { type: 'object', required: ['severity'] } } },
+        },
+        // With the default verdicts, `fail` takes the rule's severity.
+        {
+            if: { required: ['semantic'], properties: { semantic: { type: 'object', not: { required: ['verdicts'] } } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: {
+                properties: {
+                    semantic: { type: 'object', properties: { severity: { type: 'object', not: { required: ['fail'] } } } },
+                },
+            },
+        },
+        // A rule with custom verdicts and no expression has no failure for the top-level severity to describe.
+        {
+            if: {
+                required: ['semantic'],
+                properties: { semantic: { type: 'object', required: ['verdicts'] } },
+                not: { required: ['expression'] },
+            },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { not: { required: ['severity'] } },
+        },
+    ],
 };
 const REF_SCHEMA = {
     type: 'object',

package/dist/schema/rule-filter.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from '../types';
+export declare const RULE_FILTER_DIMENSIONS: readonly ["category", "severity", "type", "id"];
+export type RuleFilterDimension = (typeof RULE_FILTER_DIMENSIONS)[number];
+/** Narrows which rules are evaluated. Dimensions combine with AND; values within a dimension with OR. */
+export type RuleFilter = Partial<Record<RuleFilterDimension, string[]>>;
+/** Parse `dimension=value[,value]` specs (e.g. from repeated `--rule-filter` flags); repeats of a dimension merge. */
+export declare function parseRuleFilter(specs: string[]): RuleFilter;
+/**
+ * Keep the rules matching every dimension of the filter. A rule with no `type` never matches a `type` filter,
+ * and a rule with a verdict map matches a `severity` filter on any severity it can report.
+ */
+export declare function filterRules(rules: Rule[], filter?: RuleFilter): Rule[];

package/dist/schema/rule-filter.js

@@ -0,0 +1,46 @@
+import { ruleSeverities } from './rule-severity';
+export const RULE_FILTER_DIMENSIONS = ['category', 'severity', 'type', 'id'];
+/** Parse `dimension=value[,value]` specs (e.g. from repeated `--rule-filter` flags); repeats of a dimension merge. */
+export function parseRuleFilter(specs) {
+    const filter = {};
+    for (const spec of specs) {
+        const eq = spec.indexOf('=');
+        const dimension = spec.slice(0, eq);
+        const values = spec
+            .slice(eq + 1)
+            .split(',')
+            .map((v) => v.trim())
+            .filter(Boolean);
+        if (eq < 0 || values.length === 0 || !RULE_FILTER_DIMENSIONS.includes(dimension)) {
+            throw new Error(`Invalid rule filter "${spec}". Use <${RULE_FILTER_DIMENSIONS.join('|')}>=<value>[,<value>...].`);
+        }
+        filter[dimension] = [...(filter[dimension] ?? []), ...values];
+    }
+    return filter;
+}
+function dimensionValues(rule, dimension) {
+    switch (dimension) {
+        case 'severity':
+            return ruleSeverities(rule);
+        case 'category':
+            return [rule.category];
+        case 'type':
+            return rule.type ? [rule.type] : [];
+        case 'id':
+            return [rule.id];
+    }
+}
+/**
+ * Keep the rules matching every dimension of the filter. A rule with no `type` never matches a `type` filter,
+ * and a rule with a verdict map matches a `severity` filter on any severity it can report.
+ */
+export function filterRules(rules, filter) {
+    if (!filter)
+        return rules;
+    return rules.filter((rule) => RULE_FILTER_DIMENSIONS.every((dim) => {
+        const wanted = filter[dim];
+        if (!wanted)
+            return true;
+        return dimensionValues(rule, dim).some((value) => wanted.includes(value));
+    }));
+}

package/dist/schema/rule-severity.d.ts

@@ -0,0 +1,13 @@
+import type { Rule, RuleCategory, RuleSeverity } from '../types';
+import type { RuleSemantic } from './metadata-contract';
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export declare const DEFAULT_SEVERITY_BY_CATEGORY: Record<RuleCategory, RuleSeverity>;
+/** The rule's semantic part as an object (`semantic: true` means `{}`), or undefined for a rule without one. */
+export declare function ruleSemantic(rule: Rule): RuleSemantic | undefined;
+/** Severity of a failed `expression` and of the default `fail` verdict: the rule's `severity`, else its category default. */
+export declare function ruleSeverity(rule: Rule): RuleSeverity;
+/**
+ * Every severity this rule can report: that of its failed `expression` (or default `fail` verdict), plus those
+ * its semantic verdict map sets. `ignore` entries report nothing. Most severe first.
+ */
+export declare function ruleSeverities(rule: Rule): RuleSeverity[];

package/dist/schema/rule-severity.js

@@ -0,0 +1,33 @@
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export const DEFAULT_SEVERITY_BY_CATEGORY = {
+    validation: 'error',
+    coherence: 'warning',
+    workflow: 'warning',
+    'best-practice': 'info',
+};
+const SEVERITY_ORDER = ['error', 'warning', 'info'];
+/** The rule's semantic part as an object (`semantic: true` means `{}`), or undefined for a rule without one. */
+export function ruleSemantic(rule) {
+    if (rule.semantic === undefined)
+        return undefined;
+    return rule.semantic === true ? {} : rule.semantic;
+}
+/** Severity of a failed `expression` and of the default `fail` verdict: the rule's `severity`, else its category default. */
+export function ruleSeverity(rule) {
+    return rule.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[rule.category];
+}
+/**
+ * Every severity this rule can report: that of its failed `expression` (or default `fail` verdict), plus those
+ * its semantic verdict map sets. `ignore` entries report nothing. Most severe first.
+ */
+export function ruleSeverities(rule) {
+    const semantic = ruleSemantic(rule);
+    const found = new Set();
+    if (rule.expression !== undefined || (semantic && !semantic.verdicts))
+        found.add(ruleSeverity(rule));
+    for (const severity of Object.values(semantic?.severity ?? {})) {
+        if (severity !== 'ignore')
+            found.add(severity);
+    }
+    return SEVERITY_ORDER.filter((s) => found.has(s));
+}

package/dist/schema/schema.js

@@ -183,10 +183,40 @@ export function buildFullRegistry(schemaPath, pluginSchemas) {
     }
     return schemaRefRegistry;
 }
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?(Z|[+-](\d{2}):(\d{2}))?$/;
+function isCalendarDate(year, month, day) {
+    const d = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+    return d.getUTCMonth() === Number(month) - 1 && d.getUTCDate() === Number(day);
+}
+/** ISO 8601 date, e.g. 2026-03-31. */
+function isDate(value) {
+    const m = DATE_PATTERN.exec(value);
+    return m !== null && isCalendarDate(m[1], m[2], m[3]);
+}
+/**
+ * ISO 8601 datetime. `strict` requires seconds and a UTC offset (e.g. 2026-03-31T09:15:00+10:00);
+ * otherwise both are optional, as in the local datetimes Obsidian writes (e.g. 2026-03-31T09:15).
+ */
+function isDateTime(value, strict) {
+    const m = DATE_TIME_PATTERN.exec(value);
+    if (!m || !isCalendarDate(m[1], m[2], m[3]))
+        return false;
+    const [, , , , hour, minute, second, , offset, offsetHour, offsetMinute] = m;
+    if (strict && (second === undefined || offset === undefined))
+        return false;
+    return (Number(hour) < 24 &&
+        Number(minute) < 60 &&
+        Number(second ?? 0) < 60 &&
+        Number(offsetHour ?? 0) < 24 &&
+        Number(offsetMinute ?? 0) < 60);
+}
 function compileValidator(targetSchema, schemaRefRegistry) {
     const ajv = new Ajv2020();
     ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
-    ajv.addFormat('date', (value) => /^\d{4}-\d{2}-\d{2}$/.test(value));
+    ajv.addFormat('date', isDate);
+    ajv.addFormat('date-time', (value) => isDateTime(value, true));
+    ajv.addFormat('date-or-date-time', (value) => isDate(value) || isDateTime(value, false));
     ajv.addFormat('wikilink', (value) => /^\[\[.+\]\]$/.test(value));
     ajv.addKeyword({
         keyword: '$metadata',

package/dist/schema/validate-rules.d.ts

@@ -1,14 +1,23 @@
-import type { Rule, RuleCategory, RuleSeverity, RuleViolation, SpaceNode } from '../types';
-/** Default severity for each rule category. A rule's own `severity` field overrides this. */
-export declare const DEFAULT_SEVERITY_BY_CATEGORY: Record<RuleCategory, RuleSeverity>;
-/** Effective severity of a rule: its explicit `severity`, else its category default. */
-export declare function ruleSeverity(rule: Rule): RuleSeverity;
+import type { TrimReport } from '../judge/trim';
+import type { SemanticJudgeProvider } from '../judge/types';
+import type { Rule, RuleViolation, SpaceNode } from '../types';
+export { DEFAULT_SEVERITY_BY_CATEGORY, ruleSeverity } from './rule-severity';
+export interface ValidateRulesOptions {
+    /** Evaluates semantic rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
+    judge?: SemanticJudgeProvider;
+    /** Label of the only node to judge (`validate-file`); other nodes' semantic rules are skipped. */
+    judgeTarget?: string;
+    /** Set of node labels that have already failed upstream structural checks. */
+    gatedNodeLabels?: Set<string>;
+    trimReport?: TrimReport;
+}
 /**
  * Validate nodes against rules metadata.
- * Returns a list of rule violations found.
+ * Evaluates expressions and (when opt-in) semantic parts.
  *
  * @param nodes - All nodes in the space
  * @param rules - Rules metadata list
- * @returns Array of rule violations
+ * @param options - Validation options, including the judge for semantic rules
+ * @returns Rule violations
  */
-export declare function validateRules(nodes: SpaceNode[], rules: Rule[]): Promise<RuleViolation[]>;
+export declare function validateRules(nodes: SpaceNode[], rules: Rule[], options?: ValidateRulesOptions): Promise<RuleViolation[]>;

package/dist/schema/validate-rules.js

@@ -1,25 +1,20 @@
-import { buildEvalContext, evaluateExpression } from './evaluate-rule';
-/** Default severity for each rule category. A rule's own `severity` field overrides this. */
-export const DEFAULT_SEVERITY_BY_CATEGORY = {
-    validation: 'error',
-    coherence: 'warning',
-    workflow: 'warning',
-    'best-practice': 'info',
-};
-/** Effective severity of a rule: its explicit `severity`, else its category default. */
-export function ruleSeverity(rule) {
-    return rule.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[rule.category];
-}
+import { judgeNodes } from '../judge/judge-node';
+import { buildSpaceGraph } from '../space-graph';
+import { buildEvalContext, evaluateRuleExpression, expressionErrorViolation, tryEvaluateExpression, } from './evaluate-rule';
+import { ruleSeverities, ruleSeverity } from './rule-severity';
+export { DEFAULT_SEVERITY_BY_CATEGORY, ruleSeverity } from './rule-severity';
 /**
  * Validate nodes against rules metadata.
- * Returns a list of rule violations found.
+ * Evaluates expressions and (when opt-in) semantic parts.
  *
  * @param nodes - All nodes in the space
  * @param rules - Rules metadata list
- * @returns Array of rule violations
+ * @param options - Validation options, including the judge for semantic rules
+ * @returns Rule violations
  */
-export async function validateRules(nodes, rules) {
+export async function validateRules(nodes, rules, options = {}) {
     const violations = [];
+    const judge = options.judge;
     // Build node index for efficient lookups
     const nodeIndex = new Map();
     for (const node of nodes) {
@@ -28,43 +23,91 @@ export async function validateRules(nodes, rules) {
             nodeIndex.set(title, node);
         }
     }
-    // Evaluate each rule against applicable nodes
-    for (const rule of rules) {
-        const severity = ruleSeverity(rule);
-        if (rule.scope === 'global') {
-            // Global rules are evaluated once against the full node set.
-            // A sentinel node provides the evaluation context (nodes array is what matters).
-            const sentinel = nodes[0];
-            if (sentinel) {
-                const context = buildEvalContext(sentinel, nodes, nodeIndex);
-                const result = await evaluateExpression(rule.check, context);
-                if (result !== true) {
-                    violations.push({
-                        file: '',
-                        ruleId: rule.id,
-                        category: rule.category,
-                        severity,
-                        description: rule.description,
-                    });
+    const sentinel = nodes[0];
+    const runnable = rules.filter((r) => r.expression !== undefined || (r.semantic !== undefined && judge));
+    // The nodes each per-node rule applies to: matching `type` and passing the applicability condition (`when`).
+    const applicable = new Map();
+    for (const rule of runnable) {
+        if (rule.global)
+            continue;
+        const matching = [];
+        for (const node of nodes) {
+            if (rule.type && rule.type !== node.resolvedType)
+                continue;
+            if (rule.when) {
+                const when = await tryEvaluateExpression(rule.when, buildEvalContext(node, nodes, nodeIndex));
+                if ('error' in when) {
+                    violations.push(expressionErrorViolation(rule, node.label, when.error));
+                    continue;
                 }
+                if (when.value !== true)
+                    continue;
             }
+            matching.push(node);
         }
-        else {
-            const targetNodes = rule.type ? nodes.filter((n) => n.resolvedType === rule.type) : nodes;
-            for (const node of targetNodes) {
-                const context = buildEvalContext(node, nodes, nodeIndex);
-                const result = await evaluateExpression(rule.check, context);
-                if (result !== true) {
-                    violations.push({
-                        file: node.label,
-                        ruleId: rule.id,
-                        category: rule.category,
-                        severity,
-                        description: rule.description,
-                    });
-                }
-            }
+        applicable.set(rule, matching);
+    }
+    // 1. Expressions, in rule order. A global rule is evaluated once against the full node set; a sentinel node
+    // provides the evaluation context (the nodes array is what matters).
+    const failedNodeLabels = new Set(options.gatedNodeLabels); // nodes that failed an expression (or upstream)
+    const notEvaluable = new Set(); // `${rule.id}\0${label}` whose own expression failed or errored
+    for (const rule of runnable) {
+        if (rule.expression === undefined)
+            continue;
+        if (rule.global) {
+            if (!sentinel)
+                continue;
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            if (!result.passed)
+                violations.push(result.violation);
+            continue;
         }
+        for (const node of applicable.get(rule) ?? []) {
+            const result = await evaluateRuleExpression(rule, node, nodes, nodeIndex);
+            if (result.passed)
+                continue;
+            violations.push(result.violation);
+            notEvaluable.add(`${rule.id}\0${node.label}`);
+            if (result.failed)
+                failedNodeLabels.add(node.label);
+        }
+    }
+    // 2. Semantic parts, for nodes that passed their own expression. A node that failed an expression or
+    // upstream is left out (safe cascading default).
+    if (judge) {
+        const perNode = []; // kept in node order
+        const pending = [];
+        for (const node of nodes) {
+            if (options.judgeTarget !== undefined && node.label !== options.judgeTarget)
+                continue;
+            const found = [];
+            perNode.push(found);
+            if (failedNodeLabels.has(node.label))
+                continue;
+            const semantic = runnable.filter((r) => r.semantic !== undefined && applicable.get(r)?.includes(node) && !notEvaluable.has(`${r.id}\0${node.label}`));
+            if (semantic.length > 0)
+                pending.push({ node, rules: semantic, found });
+        }
+        // One provider call for every node, so a provider with `evaluateNodes` can share model calls.
+        const judged = await judgeNodes(judge, pending, buildSpaceGraph(nodes, undefined), options.trimReport);
+        pending.forEach(({ node, found }, i) => {
+            for (const j of judged[i] ?? []) {
+                if (!j.failed)
+                    continue;
+                found.push({
+                    file: node.label,
+                    ruleId: j.rule.id,
+                    category: j.rule.category,
+                    severity: j.severity ?? ruleSeverities(j.rule)[0] ?? ruleSeverity(j.rule),
+                    description: j.error ? `${j.rule.description} (Semantic evaluation error: ${j.error})` : j.rule.description,
+                    evidence: j.evidence,
+                    ...(j.verdict !== undefined && { verdict: j.verdict }),
+                    ...(j.guidance !== undefined && { guidance: j.guidance }),
+                });
+            }
+        });
+        for (const found of perNode)
+            violations.push(...found);
     }
     return violations;
 }

package/dist/schemas/_knowledge_wiki.json

@@ -50,14 +50,14 @@
         "category": "coherence",
         "description": "Syntheses should reference at least one contributing source in their sources array",
         "type": "synthesis",
-        "check": "$exists(current.sources) and $count(current.sources) >= 1"
+        "expression": "$exists(current.sources) and $count(current.sources) >= 1"
       },
       {
         "id": "concept-has-summary",
         "category": "best-practice",
         "description": "Concept pages should have a short summary for index discoverability",
         "type": "concept",
-        "check": "$exists(current.summary) and $length(current.summary) > 0"
+        "expression": "$exists(current.summary) and $length(current.summary) > 0"
       }
     ]
   },
@@ -89,7 +89,7 @@
         },
         "published_date": {
           "type": "string",
-          "format": "date",
+          "format": "date-or-date-time",
           "description": "Original publication date"
         },
         "source_type": {
@@ -213,7 +213,7 @@
         "type": { "const": "note" },
         "date": {
           "type": "string",
-          "format": "date",
+          "format": "date-or-date-time",
           "description": "Date this entry was created or relates to"
         }
       },