structured-context 0.12.0 → 0.13.1

package/dist/plugins/markdown/read-space.js

@@ -5,12 +5,12 @@ import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
-import { applyFieldMap, coerceDates, inferTypeFromPath } from './util';
+import { applyFieldMap, inferTypeFromPath, MATTER_OPTIONS } from './util';
 export function readSpaceOnAPage(context) {
     const { space, resolvedSchemaPath, schema: { metadata }, } = context;
     const filePath = resolve(space.path);
     const raw = readFileSync(filePath, 'utf-8');
-    const { data: frontmatter, content: body } = matter(raw);
+    const { data: frontmatter, content: body } = matter(raw, MATTER_OPTIONS);
     const pageType = frontmatter.type;
     if (pageType !== undefined && !ON_A_PAGE_TYPES.includes(pageType)) {
         throw new Error(`Expected a space_on_a_page file but got type "${pageType}" in ${filePath}. ` +
@@ -60,14 +60,9 @@ export async function readSpaceDirectory(context, options) {
         const content = readFileSync(join(directory, file), 'utf-8');
         let parsed;
         try {
-            parsed = matter(content);
+            parsed = matter(content, MATTER_OPTIONS);
         }
         catch (err) {
-            // gray-matter caches parsed YAML and has a known bug where a caught exception
-            // corrupts its internal cache, causing subsequent parses to silently return {}.
-            // Clear the cache after any parse error to avoid stale state.
-            // See: https://github.com/jonschlinkert/gray-matter/issues/166
-            matter.clearCache();
             const yamlErr = err;
             const line = yamlErr.mark ? yamlErr.mark.line + 1 : undefined;
             const column = yamlErr.mark ? yamlErr.mark.column + 1 : undefined;
@@ -91,7 +86,7 @@ export async function readSpaceDirectory(context, options) {
             });
             continue;
         }
-        const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
+        const data = applyFieldMap(parsed.data, fieldMap);
         if (!data.type && typeInferenceCfg && knownTypes) {
             data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
         }

package/dist/plugins/markdown/render-directory.js

@@ -1,7 +1,7 @@
 import { posix } from 'node:path';
 import matter from 'gray-matter';
 import { getMarkdownConfig } from './index';
-import { coerceDates, invertFieldMap } from './util';
+import { invertFieldMap, MATTER_OPTIONS } from './util';
 /**
  * Sanitize a node title into a valid filesystem filename.
  * Strips Obsidian/OS forbidden characters: \ / : * ? " < > | # ^ [ ]
@@ -112,11 +112,11 @@ export function renderMarkdownDirectory(context, graph, options) {
             const typeKey = reverseFieldMap.type ?? 'type';
             frontmatterData[typeKey] = nodeType;
         }
-        const coercedData = coerceDates(sortFrontmatterKeys(frontmatterData));
+        const sortedData = sortFrontmatterKeys(frontmatterData);
         const body = (node.content ?? '').trim();
         let fileContent;
-        if (Object.keys(coercedData).length > 0) {
-            fileContent = matter.stringify(body ? `\n${body}\n` : '', coercedData);
+        if (Object.keys(sortedData).length > 0) {
+            fileContent = matter.stringify(body ? `\n${body}\n` : '', sortedData, MATTER_OPTIONS);
         }
         else {
             fileContent = body ? `${body}\n` : '';

package/dist/plugins/markdown/template-sync.js

@@ -2,9 +2,8 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import fg from 'fast-glob';
 import matter from 'gray-matter';
-import yaml from 'js-yaml';
 import { mergeVariantProperties, resolveRef } from '../../schema/schema-refs';
-import { invertFieldMap } from './util';
+import { dumpYaml, invertFieldMap, MATTER_OPTIONS } from './util';
 // Fields derived from the filesystem — present at validation time but not written to frontmatter
 const DERIVED_FIELDS = new Set(['title', 'content']);
 function enumPlaceholder(def) {
@@ -76,7 +75,7 @@ export function generateNewContent(nodeType, variant, schema, schemaRefRegistry,
     const toCanonicalKey = (k) => fieldMap[k] ?? k;
     const exampleWithPlaceholders = withEnumPlaceholders(example, properties, schema, schemaRefRegistry);
     const remappedExample = Object.fromEntries(Object.entries(exampleWithPlaceholders).map(([k, v]) => [toFileKey(k), v]));
-    let frontmatterYaml = yaml.dump(remappedExample, { lineWidth: -1 }).trim();
+    let frontmatterYaml = dumpYaml(remappedExample, { lineWidth: -1 }).trim();
     // Append property descriptions as comments
     // YAML lines use file field names; look up properties using canonical key.
     const lines = frontmatterYaml.split('\n');
@@ -206,7 +205,7 @@ export async function templateSync(context, options) {
             continue;
         }
         const body = content.slice(fmMatch[0].length);
-        const parsed = matter(content);
+        const parsed = matter(content, MATTER_OPTIONS);
         const nodeType = parsed.data.type;
         if (!nodeType) {
             continue;

package/dist/plugins/markdown/util.d.ts

@@ -1,11 +1,32 @@
+import { type DumpOptions, type Schema } from 'js-yaml';
 import type { TypeInferenceConfig } from '.';
 export declare function inferTypeFromPath(filePath: string, config: TypeInferenceConfig, knownTypes: Set<string>, typeAliases: Record<string, string> | undefined): string | undefined;
 /**
- * Coerce Date objects in frontmatter/YAML data to ISO date strings (YYYY-MM-DD).
- * gray-matter and js-yaml parse unquoted ISO dates (e.g. `date: 2026-03-31`) as
- * JavaScript Date objects, which are not valid JSON and fail string type validation.
+ * YAML schema for frontmatter and embedded YAML blocks: YAML 1.2 Core schema extended with
+ * YAML 1.1 merge keys (`<<`), collections (binary, omap, pairs, set), and custom Date scalar
+ * handling that avoids js-yaml's timestamp type. Dates and datetimes stay as the strings
+ * written (e.g. `2026-03-31`, `2026-06-20T22:53:05+10:00`) rather than becoming Date objects,
+ * which lose precision and offset and are not valid JSON.
  */
-export declare function coerceDates(data: Record<string, unknown>): Record<string, unknown>;
+export declare const YAML_SCHEMA: Schema;
+export declare function parseYaml(text: string): unknown;
+export type DumpYamlOptions = DumpOptions & {
+    replacer?: (key: string, value: unknown) => unknown;
+};
+/** Dumps with YAML_SCHEMA. Date values (e.g. from non-markdown plugins) are written as ISO 8601 strings. */
+export declare function dumpYaml(data: unknown, options?: DumpYamlOptions): string;
+/**
+ * gray-matter options using YAML_SCHEMA. Passing options also bypasses gray-matter's parse cache,
+ * which is corrupted by a caught parse error (https://github.com/jonschlinkert/gray-matter/issues/166).
+ */
+export declare const MATTER_OPTIONS: {
+    engines: {
+        yaml: {
+            parse: (text: string) => object;
+            stringify: (data: object) => string;
+        };
+    };
+};
 /**
  * Apply field remapping to a data object.
  * Renames keys according to fieldMap (file field name → canonical field name).

package/dist/plugins/markdown/util.js

@@ -1,4 +1,5 @@
 import { posix } from 'node:path';
+import { binaryTag, CORE_SCHEMA, defineScalarTag, dump, load, mergeTag, omapTag, pairsTag, setTag, visit, } from 'js-yaml';
 export function inferTypeFromPath(filePath, config, knownTypes, typeAliases) {
     if (config.mode === 'off')
         return undefined;
@@ -37,26 +38,66 @@ export function inferTypeFromPath(filePath, config, knownTypes, typeAliases) {
     }
     return undefined;
 }
+const dateTag = defineScalarTag('tag:yaml.org,2002:timestamp', {
+    identify: (data) => data instanceof Date,
+    represent: (data) => data.toISOString(),
+    resolve: (source) => source,
+});
 /**
- * Coerce Date objects in frontmatter/YAML data to ISO date strings (YYYY-MM-DD).
- * gray-matter and js-yaml parse unquoted ISO dates (e.g. `date: 2026-03-31`) as
- * JavaScript Date objects, which are not valid JSON and fail string type validation.
+ * YAML schema for frontmatter and embedded YAML blocks: YAML 1.2 Core schema extended with
+ * YAML 1.1 merge keys (`<<`), collections (binary, omap, pairs, set), and custom Date scalar
+ * handling that avoids js-yaml's timestamp type. Dates and datetimes stay as the strings
+ * written (e.g. `2026-03-31`, `2026-06-20T22:53:05+10:00`) rather than becoming Date objects,
+ * which lose precision and offset and are not valid JSON.
  */
-export function coerceDates(data) {
-    const result = {};
-    for (const [key, value] of Object.entries(data)) {
-        if (value instanceof Date) {
-            result[key] = value.toISOString().slice(0, 10);
-        }
-        else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-            result[key] = coerceDates(value);
-        }
-        else {
-            result[key] = value;
+export const YAML_SCHEMA = CORE_SCHEMA.withTags(mergeTag, binaryTag, omapTag, pairsTag, setTag, dateTag);
+export function parseYaml(text) {
+    return load(text, { schema: YAML_SCHEMA });
+}
+function applyReplacer(key, value, replacer) {
+    const replaced = replacer(key, value);
+    if (Array.isArray(replaced)) {
+        return replaced.map((item, index) => applyReplacer(String(index), item, replacer));
+    }
+    if (replaced !== null && typeof replaced === 'object' && Object.getPrototypeOf(replaced) === Object.prototype) {
+        const res = {};
+        for (const [k, v] of Object.entries(replaced)) {
+            const vReplaced = applyReplacer(k, v, replacer);
+            if (vReplaced !== undefined) {
+                res[k] = vReplaced;
+            }
         }
+        return res;
     }
-    return result;
+    return replaced;
+}
+/** Dumps with YAML_SCHEMA. Date values (e.g. from non-markdown plugins) are written as ISO 8601 strings. */
+export function dumpYaml(data, options) {
+    const input = options?.replacer ? applyReplacer('', data, options.replacer) : data;
+    const { replacer: _ignored, transform, ...dumpOpts } = options ?? {};
+    return dump(input, {
+        ...dumpOpts,
+        schema: YAML_SCHEMA,
+        transform: (docs) => {
+            visit(docs, (node) => {
+                if (node.kind === 'scalar' && (node.tag === '!!timestamp' || node.tag === 'tag:yaml.org,2002:timestamp')) {
+                    node.tagged = false;
+                    node.tag = 'tag:yaml.org,2002:str';
+                }
+            });
+            transform?.(docs);
+        },
+    });
 }
+/**
+ * gray-matter options using YAML_SCHEMA. Passing options also bypasses gray-matter's parse cache,
+ * which is corrupted by a caught parse error (https://github.com/jonschlinkert/gray-matter/issues/166).
+ */
+export const MATTER_OPTIONS = {
+    engines: {
+        yaml: { parse: (text) => parseYaml(text), stringify: (data) => dumpYaml(data) },
+    },
+};
 /**
  * Apply field remapping to a data object.
  * Renames keys according to fieldMap (file field name → canonical field name).

package/dist/render/render.js

@@ -1,7 +1,7 @@
-import { shortenPluginName } from '../plugins/util';
 import { updateSpaceField } from '../config';
 import { assembleSpaceGraph } from '../load-space-graph';
 import { loadPlugins } from '../plugins/loader';
+import { shortenPluginName } from '../plugins/util';
 import { buildFormatRegistry } from './registry';
 export async function executeRender(formatName, context, options) {
     const pluginMap = context.space?.plugins ?? {};

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

@@ -1,4 +1,4 @@
-import type { SpaceNode } from '../types';
+import type { Rule, RuleViolation, SpaceNode } from '../types';
 /** Evaluation context for JSONata expressions */
 export interface EvalContext {
     /** All nodes in the space (flattened) */
@@ -12,13 +12,26 @@ export interface EvalContext {
 }
 /**
  * Evaluate a JSONata expression against a context.
- * Returns the result of the expression (boolean for rule checks).
+ * Returns the result of the expression (boolean for rule checks). Throws {@link ExpressionError} if it fails.
  *
  * @param expr - JSONata expression string
  * @param context - Evaluation context with $, $$, parent, $lookup
  * @returns Result of expression evaluation
  */
 export declare function evaluateExpression(expr: string, context: EvalContext): Promise<boolean | string | number>;
+/** A JSONata expression could not be compiled or evaluated. */
+export declare class ExpressionError extends Error {
+    readonly expression: string;
+    constructor(expression: string, cause: unknown);
+}
+/** Result of evaluating a rule's `expression` or `when`: a value, or the error that stopped it (never thrown). */
+export type ExpressionOutcome = {
+    value: boolean | string | number;
+} | {
+    error: string;
+};
+/** Like {@link evaluateExpression} but reports a failure as data, so callers can turn it into a violation. */
+export declare function tryEvaluateExpression(expr: string, context: EvalContext): Promise<ExpressionOutcome>;
 /**
  * Build an evaluation context for a given node.
  *
@@ -28,3 +41,21 @@ export declare function evaluateExpression(expr: string, context: EvalContext):
  * @returns Evaluation context for the node
  */
 export declare function buildEvalContext(node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<string, SpaceNode>): EvalContext;
+/** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
+export declare function expressionErrorViolation(rule: Rule, file: string, error: string): RuleViolation;
+/** The outcome of a rule's `expression` on one node. */
+export type ExpressionRuleResult = {
+    passed: true;
+}
+/** `failed` is the expression returning something other than true; otherwise it could not be evaluated. */
+ | {
+    passed: false;
+    violation: RuleViolation;
+    failed: boolean;
+};
+/**
+ * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
+ * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
+ */
+export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<string, SpaceNode>, file?: string): Promise<ExpressionRuleResult>;

package/dist/schema/evaluate-rule.js

@@ -1,8 +1,9 @@
 import jsonata from 'jsonata';
+import { ruleSeverity } from './rule-severity';
 const expressionCache = new Map();
 /**
  * Evaluate a JSONata expression against a context.
- * Returns the result of the expression (boolean for rule checks).
+ * Returns the result of the expression (boolean for rule checks). Throws {@link ExpressionError} if it fails.
  *
  * @param expr - JSONata expression string
  * @param context - Evaluation context with $, $$, parent, $lookup
@@ -34,9 +35,26 @@ export async function evaluateExpression(expr, context) {
         return result;
     }
     catch (error) {
-        // Log warning and return false (fail safe)
-        console.warn(`Warning: Error evaluating expression "${expr}":`, error);
-        return false;
+        throw new ExpressionError(expr, error);
+    }
+}
+/** A JSONata expression could not be compiled or evaluated. */
+export class ExpressionError extends Error {
+    expression;
+    constructor(expression, cause) {
+        // JSONata throws plain objects ({ code, message, position }), not Error instances.
+        const reason = cause?.message ?? cause;
+        super(`Expression "${expression}" failed: ${String(reason)}`);
+        this.expression = expression;
+    }
+}
+/** Like {@link evaluateExpression} but reports a failure as data, so callers can turn it into a violation. */
+export async function tryEvaluateExpression(expr, context) {
+    try {
+        return { value: await evaluateExpression(expr, context) };
+    }
+    catch (error) {
+        return { error: error instanceof ExpressionError ? error.message : String(error) };
     }
 }
 /**
@@ -81,3 +99,39 @@ export function buildEvalContext(node, allNodes, nodeIndex) {
         parents: flattenedParents.length > 0 ? flattenedParents : undefined,
     };
 }
+/** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
+export function expressionErrorViolation(rule, file, error) {
+    return {
+        file,
+        ruleId: rule.id,
+        category: rule.category,
+        severity: 'error',
+        description: `${rule.description} (Rule error: ${error})`,
+    };
+}
+/**
+ * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
+ * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
+ */
+export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, file = node.label) {
+    const expression = rule.expression;
+    const outcome = await tryEvaluateExpression(expression, buildEvalContext(node, allNodes, nodeIndex));
+    if ('error' in outcome) {
+        return { passed: false, failed: false, violation: expressionErrorViolation(rule, file, outcome.error) };
+    }
+    if (outcome.value === true)
+        return { passed: true };
+    return {
+        passed: false,
+        failed: true,
+        violation: {
+            file,
+            ruleId: rule.id,
+            category: rule.category,
+            severity: ruleSeverity(rule),
+            description: rule.description,
+            ...(rule.semantic !== undefined && { evidence: `expression failed: ${expression}` }),
+        },
+    };
+}

package/dist/schema/gating.d.ts

@@ -0,0 +1,69 @@
+import type { TrimReport } from '../judge/trim';
+import type { SemanticJudgeProvider } from '../judge/types';
+import type { SpaceGraph } from '../space-graph';
+import type { Rule, RuleSeverity, RuleViolation, SpaceNode } from '../types';
+/**
+ * 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 declare function ruleGatesDescendants(rule: Rule, severity?: RuleSeverity): boolean;
+/**
+ * A node-level failure that seeds cascade gating: a deterministic, always-run check
+ * (schema validation or hierarchy structure) that failed on a specific node.
+ */
+export type GatingSeed = {
+    /** Label (file) of the failing node. */
+    file: string;
+    /** Title of the failing node. */
+    title: string;
+    /** Which always-run layer produced the failure. */
+    reason: 'schema' | 'hierarchy';
+};
+/**
+ * Records one cascade: a node whose failure or blocking rule violation suppressed
+ * rule evaluation for itself (if schema/hierarchy caused it) and/or its hierarchy subtree.
+ */
+export type CoverageGate = {
+    /** Label (file) of the node whose failure triggered this gate. */
+    file: string;
+    /** Title of the blocking node. */
+    nodeTitle: string;
+    /** What kind of check triggered the gate. */
+    reason: 'schema' | 'hierarchy' | 'rule';
+    /** Rule id responsible, when `reason` is `'rule'`. */
+    ruleId?: string;
+    /** Labels of nodes whose rule evaluation was suppressed as a result of this gate. */
+    gatedFiles: string[];
+};
+export type GatedRuleEvaluation = {
+    violations: RuleViolation[];
+    gates: CoverageGate[];
+};
+export interface GatingOptions {
+    trimReport?: TrimReport;
+    /** Evaluate rules on gated nodes anyway (gates are still reported). */
+    includeGated?: boolean;
+    /** Evaluates `semantic` rules. Without it, a rule's semantic part is not evaluated. */
+    provider?: SemanticJudgeProvider;
+    /**
+     * Label of the one node whose result is wanted (`validate-file`). Gating is still computed over the
+     * whole space, but the judge is only consulted for that node and for its hierarchy ancestors' gate-capable
+     * semantic rules (top-down, so a gated ancestor stops the walk). Other nodes' semantic rules are not evaluated.
+     */
+    judgeTarget?: string;
+}
+/**
+ * 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 declare function computeHierarchyDepths(graph: SpaceGraph): Map<string, number>;
+/**
+ * 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 declare function evaluateRulesWithGating(nodes: SpaceNode[], rules: Rule[], graph: SpaceGraph, seeds: GatingSeed[], options?: GatingOptions): Promise<GatedRuleEvaluation>;