structured-context 0.11.0 → 0.13.0

package/dist/read/resolve-graph-edges.js

@@ -21,19 +21,27 @@ function getRefs(rawField, multiple) {
  * @param nodesByType Map of node type to nodes
  * @param targetIndex Map of link targets to nodes
  * @param edge The edge definition (child type, parent type, field, fieldOn, multiple)
- * @param source Whether this edge comes from hierarchy.levels or relationships
+ * @param source Whether this edge comes from hierarchy levels or relationships
+ * @param hierarchy Name of the hierarchy the edge belongs to (hierarchy edges only)
  * @param selfRef Whether child and parent are the same node type
  * @param unresolvedRefs Array to push broken/invalid link entries into
  * @param typeAliases Optional type aliases for resolution
  */
-function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolvedRefs, typeAliases) {
+function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef, unresolvedRefs, typeAliases) {
     const { type: rawChildType, parent: rawParentType, field, fieldOn, multiple } = edge;
     const childType = resolveNodeType(rawChildType, typeAliases);
     const parentType = resolveNodeType(rawParentType, typeAliases);
     function pushParentRef(childNode, parentTitle) {
         // Deduplicate by (field, title) — same parent via different fields is intentional
         if (!childNode.resolvedParents.some((r) => r.field === field && r.title === parentTitle)) {
-            childNode.resolvedParents.push({ title: parentTitle, field, fieldOn, source, selfRef });
+            childNode.resolvedParents.push({
+                title: parentTitle,
+                field,
+                fieldOn,
+                source,
+                ...(hierarchy !== undefined ? { hierarchy } : {}),
+                selfRef,
+            });
         }
     }
     function checkShape(ownerNode, rawField) {
@@ -54,6 +62,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'invalid_shape',
                 message: `Field "${field}" must be a wikilink string, got ${typeof rawField}`,
+                source: ownerNode.source,
             });
             return false;
         }
@@ -69,6 +78,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'not_found',
                 message: `Link target "${target}" in field "${field}" not found`,
+                source: ownerNode.source,
             });
             return null;
         }
@@ -79,6 +89,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, selfRef, unresolved
                 field,
                 reason: 'ambiguous',
                 message: `Link target "${target}" in field "${field}" is ambiguous (matches multiple nodes)`,
+                source: ownerNode.source,
             });
             return null;
         }
@@ -155,12 +166,12 @@ function classifyContentLink(link, targetIndex) {
 }
 /**
  * Enrich parsed nodes into SpaceNodes by applying type alias resolution and resolving
- * parent links using the hierarchy levels and relationships from schema metadata.
+ * parent links using the levels of every hierarchy and the relationships from schema metadata.
  *
  * Returns the enriched nodes and any unresolved refs (broken/invalid wikilinks).
  */
 export function resolveGraphEdges(nodes, metadata) {
-    const levels = metadata.hierarchy?.levels ?? [];
+    const hierarchies = metadata.hierarchies ?? [];
     const relationships = metadata.relationships ?? [];
     const typeAliases = metadata.typeAliases;
     const unresolvedRefs = [];
@@ -180,27 +191,35 @@ export function resolveGraphEdges(nodes, metadata) {
         }
         nodesByType.get(type).push(node);
     }
-    // 1. Process hierarchy levels
-    for (let i = 0; i < levels.length; i++) {
-        const level = levels[i];
-        // Regular relationship (child type → parent type)
-        if (i > 0) {
-            const parentLevel = levels[i - 1];
-            resolveEdge(nodesByType, targetIndex, {
-                type: level.type,
-                parent: parentLevel.type,
-                field: level.field,
-                fieldOn: level.fieldOn,
-                multiple: level.multiple,
-            }, 'hierarchy', false, unresolvedRefs, typeAliases);
-        }
-        // Same-type relationship (child type → same type) via primary field
-        if (level.selfRef) {
-            resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.field, fieldOn: level.fieldOn, multiple: level.multiple }, 'hierarchy', true, unresolvedRefs, typeAliases);
-        }
-        // Same-type relationship via explicit selfRefField
-        if (level.selfRefField) {
-            resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, 'hierarchy', true, unresolvedRefs, typeAliases);
+    // 1. Process the levels of each hierarchy
+    for (const { name, levels } of hierarchies) {
+        for (let i = 0; i < levels.length; i++) {
+            const level = levels[i];
+            // Regular relationship (child type → parent type)
+            if (i > 0) {
+                const parentLevel = levels[i - 1];
+                resolveEdge(nodesByType, targetIndex, {
+                    type: level.type,
+                    parent: parentLevel.type,
+                    field: level.field,
+                    fieldOn: level.fieldOn,
+                    multiple: level.multiple,
+                }, 'hierarchy', name, false, unresolvedRefs, typeAliases);
+            }
+            // Same-type relationship (child type → same type) via primary field
+            if (level.selfRef) {
+                resolveEdge(nodesByType, targetIndex, {
+                    type: level.type,
+                    parent: level.type,
+                    field: level.field,
+                    fieldOn: level.fieldOn,
+                    multiple: level.multiple,
+                }, 'hierarchy', name, true, unresolvedRefs, typeAliases);
+            }
+            // Same-type relationship via explicit selfRefField
+            if (level.selfRefField) {
+                resolveEdge(nodesByType, targetIndex, { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, 'hierarchy', name, true, unresolvedRefs, typeAliases);
+            }
         }
     }
     // 2. Process additional relationships
@@ -212,7 +231,7 @@ export function resolveGraphEdges(nodes, metadata) {
             fieldOn: rel.fieldOn,
             multiple: rel.multiple,
         };
-        resolveEdge(nodesByType, targetIndex, edge, 'relationship', rel.type === rel.parent, unresolvedRefs, typeAliases);
+        resolveEdge(nodesByType, targetIndex, edge, 'relationship', undefined, rel.type === rel.parent, unresolvedRefs, typeAliases);
     }
     // 3. Resolve content links — classify each raw ContentLink into a ResolvedContentLink.
     for (const node of spaceNodes) {

package/dist/read/wikilink-utils.d.ts

@@ -1,4 +1,21 @@
 import type { BaseNode } from '../types';
+export interface ParsedWikilink {
+    target: string;
+    anchor?: string;
+    displayText?: string;
+}
+/**
+ * Format a wikilink string.
+ * formatWikilink('My Goal') -> '[[My Goal]]'
+ * formatWikilink('My Goal', 'Custom Display') -> '[[My Goal|Custom Display]]'
+ */
+export declare function formatWikilink(target: string, alias?: string): string;
+/**
+ * Parse a wikilink or link inner string into target, anchor, and displayText.
+ * Handles: [[target]], [[target#anchor]], [[target|alias]], [[target#anchor|alias]]
+ * Also handles bare forms without enclosing brackets.
+ */
+export declare function parseWikilink(wikilink: string): ParsedWikilink;
 /**
  * Extract the lookup key from a wikilink string such as:
  *   [[Personal Vision]]                → "Personal Vision"

package/dist/read/wikilink-utils.js

@@ -1,3 +1,43 @@
+/**
+ * Format a wikilink string.
+ * formatWikilink('My Goal') -> '[[My Goal]]'
+ * formatWikilink('My Goal', 'Custom Display') -> '[[My Goal|Custom Display]]'
+ */
+export function formatWikilink(target, alias) {
+    const trimmedTarget = target.trim();
+    const trimmedAlias = alias?.trim();
+    if (trimmedAlias && trimmedAlias !== trimmedTarget) {
+        return `[[${trimmedTarget}|${trimmedAlias}]]`;
+    }
+    return `[[${trimmedTarget}]]`;
+}
+/**
+ * Parse a wikilink or link inner string into target, anchor, and displayText.
+ * Handles: [[target]], [[target#anchor]], [[target|alias]], [[target#anchor|alias]]
+ * Also handles bare forms without enclosing brackets.
+ */
+export function parseWikilink(wikilink) {
+    const cleaned = wikilink.replace(/^"|"$/g, '').trim();
+    const inner = cleaned.startsWith('[[') && cleaned.endsWith(']]') ? cleaned.slice(2, -2).trim() : cleaned;
+    // Alias: [[target|alias]] or [[target#anchor|alias]]
+    const pipeIdx = inner.indexOf('|');
+    let core = inner;
+    let displayText;
+    if (pipeIdx >= 0) {
+        core = inner.slice(0, pipeIdx);
+        const alias = inner.slice(pipeIdx + 1).trim();
+        if (alias)
+            displayText = alias;
+    }
+    // Anchor: [[target#anchor]] or [[target#^block]]
+    const hashIdx = core.indexOf('#');
+    if (hashIdx >= 0) {
+        const target = core.slice(0, hashIdx).trim();
+        const anchor = core.slice(hashIdx + 1).trim() || undefined;
+        return { target, anchor, displayText };
+    }
+    return { target: core.trim(), displayText };
+}
 /**
  * Extract the lookup key from a wikilink string such as:
  *   [[Personal Vision]]                → "Personal Vision"

package/dist/render/render.d.ts

@@ -1,5 +1,7 @@
+import { type RenderResult } from '../plugins/util.js';
 import type { SpaceContext } from '../types';
 export declare function executeRender(formatName: string, context: SpaceContext, options: {
     filter?: string;
+    hierarchy?: string;
     data?: Record<string, unknown>;
-}): Promise<string>;
+}): Promise<RenderResult>;

package/dist/render/render.js

@@ -1,4 +1,4 @@
-import { shortenPluginName } from '@/plugins/util';
+import { shortenPluginName } from '../plugins/util.js';
 import { updateSpaceField } from '../config';
 import { assembleSpaceGraph } from '../load-space-graph';
 import { loadPlugins } from '../plugins/loader';
@@ -12,7 +12,7 @@ export async function executeRender(formatName, context, options) {
         const available = registry.map((r) => r.qualifiedName).join(', ');
         throw new Error(`Unknown render format: "${formatName}".${available ? ` Available: ${available}` : ' No formats registered.'}`);
     }
-    const graph = await assembleSpaceGraph(context, { filter: options.filter });
+    const graph = await assembleSpaceGraph(context, { filter: options.filter, hierarchy: options.hierarchy });
     const shortName = shortenPluginName(entry.plugin.plugin.name);
     const pluginContext = {
         ...context,

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