structured-context 0.9.0

package/dist/plugins/util.js

@@ -0,0 +1,7 @@
+import { PLUGIN_PREFIX as _PLUGIN_PREFIX } from '../constants';
+export const PLUGIN_PREFIX = _PLUGIN_PREFIX;
+export const CONFIG_PLUGINS_DIR = 'plugins';
+/** Normalize a plugin name to its canonical prefixed form. */
+export function normalizePluginName(name) {
+    return name.startsWith(PLUGIN_PREFIX) ? name : `${PLUGIN_PREFIX}${name}`;
+}

package/dist/read/read-space.d.ts

@@ -0,0 +1,2 @@
+import type { ReadSpaceResult, SpaceContext } from '../types';
+export declare function readSpace(context: SpaceContext): Promise<ReadSpaceResult>;

package/dist/read/read-space.js

@@ -0,0 +1,22 @@
+import { loadPlugins } from '../plugins/loader';
+import { resolveGraphEdges } from './resolve-graph-edges';
+export async function readSpace(context) {
+    const pluginMap = context.space?.plugins ?? {};
+    const loaded = await loadPlugins(pluginMap, context.configDir);
+    for (const { plugin, pluginConfig } of loaded) {
+        if (!plugin.parse)
+            continue;
+        const result = await plugin.parse({ ...context, pluginConfig });
+        if (result !== null) {
+            const { nodes, unresolvedRefs } = resolveGraphEdges(result.nodes, context.schema.metadata);
+            return {
+                nodes,
+                source: plugin.name,
+                parseIgnored: result.parseIgnored,
+                diagnostics: result.diagnostics,
+                unresolvedRefs,
+            };
+        }
+    }
+    throw new Error(`No plugin handled space at: ${context.space.path}`);
+}

package/dist/read/resolve-graph-edges.d.ts

@@ -0,0 +1,11 @@
+import type { BaseNode, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types';
+/**
+ * Enrich parsed nodes into SpaceNodes by applying type alias resolution and resolving
+ * parent links using the hierarchy levels and relationships from schema metadata.
+ *
+ * Returns the enriched nodes and any unresolved refs (broken/invalid wikilinks).
+ */
+export declare function resolveGraphEdges(nodes: BaseNode[], metadata: SchemaMetadata): {
+    nodes: SpaceNode[];
+    unresolvedRefs: UnresolvedRef[];
+};

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

@@ -0,0 +1,201 @@
+import { resolveNodeType } from '../schema/schema';
+import { buildTargetIndex, wikilinkToTarget } from './wikilink-utils';
+/**
+ * Extract wikilink refs from a field value.
+ * If multiple=true: expects an array; returns string elements.
+ * If multiple=false: expects a single string; returns it in a one-element array.
+ */
+function getRefs(rawField, multiple) {
+    if (multiple) {
+        return Array.isArray(rawField) ? rawField.filter((v) => typeof v === 'string') : [];
+    }
+    return typeof rawField === 'string' ? [rawField] : [];
+}
+/**
+ * Resolves parent-child links for a specific edge definition, pushing a ResolvedParentRef
+ * onto each child's resolvedParents array. Records unresolved refs for broken/invalid links.
+ *
+ * For all edges, any existing node is accepted as the target (permissive).
+ * Type correctness is enforced by validateHierarchyStructure via resolvedParents, not here.
+ *
+ * @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 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) {
+    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 });
+        }
+    }
+    function checkShape(ownerNode, rawField) {
+        if (multiple && !Array.isArray(rawField)) {
+            unresolvedRefs.push({
+                label: ownerNode.label,
+                ref: String(rawField),
+                field,
+                reason: 'invalid_shape',
+                message: `Field "${field}" must be an array of wikilinks, got ${typeof rawField}`,
+            });
+            return false;
+        }
+        if (!multiple && typeof rawField !== 'string') {
+            unresolvedRefs.push({
+                label: ownerNode.label,
+                ref: String(rawField),
+                field,
+                reason: 'invalid_shape',
+                message: `Field "${field}" must be a wikilink string, got ${typeof rawField}`,
+            });
+            return false;
+        }
+        return true;
+    }
+    function checkAndRecordRef(ownerNode, ref) {
+        const target = wikilinkToTarget(ref);
+        const resolved = targetIndex.get(target);
+        if (resolved === undefined) {
+            unresolvedRefs.push({
+                label: ownerNode.label,
+                ref,
+                field,
+                reason: 'not_found',
+                message: `Link target "${target}" in field "${field}" not found`,
+            });
+            return null;
+        }
+        if (resolved === null) {
+            unresolvedRefs.push({
+                label: ownerNode.label,
+                ref,
+                field,
+                reason: 'ambiguous',
+                message: `Link target "${target}" in field "${field}" is ambiguous (matches multiple nodes)`,
+            });
+            return null;
+        }
+        return resolved;
+    }
+    if (fieldOn === 'parent') {
+        // Parent nodes have the field pointing to children; resolve permissively (any target type).
+        // Type correctness is enforced by validateHierarchyStructure, not the resolver.
+        for (const parentNode of nodesByType.get(parentType) ?? []) {
+            const rawField = parentNode.schemaData[field];
+            if (rawField === undefined || rawField === null)
+                continue;
+            if (!checkShape(parentNode, rawField))
+                continue;
+            const refs = getRefs(rawField, multiple);
+            for (const ref of refs) {
+                const childNode = checkAndRecordRef(parentNode, ref);
+                if (!childNode)
+                    continue;
+                const parentTitle = parentNode.schemaData.title;
+                if (typeof parentTitle !== 'string')
+                    continue;
+                pushParentRef(childNode, parentTitle);
+            }
+        }
+    }
+    else {
+        // Child nodes have the field pointing to parents; accept any resolved target
+        for (const childNode of nodesByType.get(childType) ?? []) {
+            const rawField = childNode.schemaData[field];
+            if (rawField === undefined || rawField === null)
+                continue;
+            if (!checkShape(childNode, rawField))
+                continue;
+            const refs = getRefs(rawField, multiple);
+            for (const ref of refs) {
+                const parentNode = checkAndRecordRef(childNode, ref);
+                if (!parentNode)
+                    continue;
+                const parentTitle = parentNode.schemaData.title;
+                if (typeof parentTitle !== 'string')
+                    continue;
+                pushParentRef(childNode, parentTitle);
+            }
+        }
+    }
+}
+/**
+ * Enrich parsed nodes into SpaceNodes by applying type alias resolution and resolving
+ * parent links using the hierarchy levels and 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 relationships = metadata.relationships ?? [];
+    const typeAliases = metadata.typeAliases;
+    const unresolvedRefs = [];
+    const spaceNodes = nodes.map((n) => ({
+        ...n,
+        resolvedType: resolveNodeType(n.type, typeAliases),
+        resolvedParents: [],
+    }));
+    const targetIndex = buildTargetIndex(spaceNodes);
+    // Build nodesByType map
+    const nodesByType = new Map();
+    for (const node of spaceNodes) {
+        const type = node.resolvedType;
+        if (!nodesByType.has(type)) {
+            nodesByType.set(type, []);
+        }
+        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);
+        }
+    }
+    // 2. Process additional relationships
+    for (const rel of relationships) {
+        const edge = {
+            type: rel.type,
+            parent: rel.parent,
+            field: rel.field,
+            fieldOn: rel.fieldOn,
+            multiple: rel.multiple,
+        };
+        resolveEdge(nodesByType, targetIndex, edge, 'relationship', rel.type === rel.parent, unresolvedRefs, typeAliases);
+    }
+    // Deduplicate by (label, field, ref) — the same broken link may be encountered across
+    // multiple resolveEdge calls (e.g. selfRef + regular hierarchy share the same field).
+    const seen = new Set();
+    const deduped = [];
+    for (const u of unresolvedRefs) {
+        const key = `${u.label}\0${u.field}\0${u.ref}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            deduped.push(u);
+        }
+    }
+    return { nodes: spaceNodes, unresolvedRefs: deduped };
+}

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

@@ -0,0 +1,16 @@
+import type { BaseNode } from '../types';
+/**
+ * Extract the lookup key from a wikilink string such as:
+ *   [[Personal Vision]]                → "Personal Vision"
+ *   [[Personal Vision#Our Mission]]    → "Personal Vision#Our Mission"
+ *   [[vision_page#^ourmission]]        → "vision_page#^ourmission"
+ */
+export declare function wikilinkToTarget(wikilink: string): string;
+/**
+ * Builds a fast lookup index mapping link targets to nodes.
+ * Used for both hierarchy and relationship validation.
+ *
+ * @param nodes The complete set of nodes (BaseNode, SpaceNode, or subtypes)
+ * @returns Map of target strings to nodes. If a target is ambiguous (points to multiple nodes), its value is null.
+ */
+export declare function buildTargetIndex<T extends BaseNode>(nodes: T[]): Map<string, T | null>;

package/dist/read/wikilink-utils.js

@@ -0,0 +1,38 @@
+/**
+ * Extract the lookup key from a wikilink string such as:
+ *   [[Personal Vision]]                → "Personal Vision"
+ *   [[Personal Vision#Our Mission]]    → "Personal Vision#Our Mission"
+ *   [[vision_page#^ourmission]]        → "vision_page#^ourmission"
+ */
+export function wikilinkToTarget(wikilink) {
+    const cleaned = wikilink.replace(/^"|"$/g, '').trim();
+    if (!cleaned.startsWith('[[') || !cleaned.endsWith(']]')) {
+        return cleaned;
+    }
+    return cleaned.slice(2, -2).trim();
+}
+/**
+ * Builds a fast lookup index mapping link targets to nodes.
+ * Used for both hierarchy and relationship validation.
+ *
+ * @param nodes The complete set of nodes (BaseNode, SpaceNode, or subtypes)
+ * @returns Map of target strings to nodes. If a target is ambiguous (points to multiple nodes), its value is null.
+ */
+export function buildTargetIndex(nodes) {
+    const index = new Map();
+    for (const node of nodes) {
+        for (const target of node.linkTargets) {
+            const normalized = target.trim();
+            if (!normalized)
+                continue; // Skip empty strings after trimming
+            const existing = index.get(normalized);
+            if (existing === undefined) {
+                index.set(normalized, node);
+            }
+            else if (existing !== node) {
+                index.set(normalized, null); // mark as ambiguous
+            }
+        }
+    }
+    return index;
+}

package/dist/render/registry.d.ts

@@ -0,0 +1,13 @@
+import type { LoadedPlugin } from '../plugins/loader';
+import type { RenderFormat } from '../plugins/util';
+export type ResolvedFormat = {
+    qualifiedName: string;
+    format: RenderFormat;
+    plugin: LoadedPlugin;
+};
+/**
+ * Build a registry of all render formats from loaded plugins.
+ * Formats are namespaced as `{shortPluginName}.{formatName}` where
+ * shortPluginName strips the `sctx-` prefix.
+ */
+export declare function buildFormatRegistry(loaded: LoadedPlugin[]): ResolvedFormat[];

package/dist/render/registry.js

@@ -0,0 +1,22 @@
+import { PLUGIN_PREFIX } from '../plugins/util';
+/**
+ * Build a registry of all render formats from loaded plugins.
+ * Formats are namespaced as `{shortPluginName}.{formatName}` where
+ * shortPluginName strips the `sctx-` prefix.
+ */
+export function buildFormatRegistry(loaded) {
+    const registry = [];
+    for (const lp of loaded) {
+        if (!lp.plugin.render)
+            continue;
+        const shortName = lp.plugin.name.replace(PLUGIN_PREFIX, '');
+        for (const format of lp.plugin.render.formats) {
+            registry.push({
+                qualifiedName: `${shortName}.${format.name}`,
+                format,
+                plugin: lp,
+            });
+        }
+    }
+    return registry;
+}

package/dist/render/render.d.ts

@@ -0,0 +1,4 @@
+import type { SpaceContext } from '../types';
+export declare function executeRender(formatName: string, context: SpaceContext, options: {
+    filter?: string;
+}): Promise<string>;

package/dist/render/render.js

@@ -0,0 +1,28 @@
+import { filterNodes } from '../filter/filter-nodes';
+import { loadPlugins } from '../plugins/loader';
+import { readSpace } from '../read/read-space';
+import { buildSpaceGraph } from '../space-graph';
+import { buildFormatRegistry } from './registry';
+export async function executeRender(formatName, context, options) {
+    const pluginMap = context.space?.plugins ?? {};
+    const loaded = await loadPlugins(pluginMap, context.configDir);
+    const registry = buildFormatRegistry(loaded);
+    const entry = registry.find((r) => r.qualifiedName === formatName);
+    if (!entry) {
+        const available = registry.map((r) => r.qualifiedName).join(', ');
+        throw new Error(`Unknown render format: "${formatName}".${available ? ` Available: ${available}` : ' No formats registered.'}`);
+    }
+    const { nodes: allNodes } = await readSpace(context);
+    // Validate: drop nodes that fail schema validation
+    const { schemaValidator } = context;
+    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
+    const levels = context.schema.metadata.hierarchy?.levels ?? [];
+    let graph = buildSpaceGraph(validNodes, levels);
+    // Filter: apply filter expression if provided
+    if (options.filter) {
+        const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
+        graph = await filterNodes(expression, graph);
+    }
+    const pluginContext = { ...context, pluginConfig: entry.plugin.pluginConfig };
+    return entry.plugin.plugin.render.render(pluginContext, graph, { format: entry.format.name });
+}

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

@@ -0,0 +1,30 @@
+import type { SpaceNode } from '../types';
+/** Evaluation context for JSONata expressions */
+export interface EvalContext {
+    /** All nodes in the space (flattened) */
+    nodes: Record<string, unknown>[];
+    /** Current node being evaluated (flattened) */
+    $$: Record<string, unknown>;
+    /** First resolved parent node (undefined if no parent) (flattened) — provided as a convenience */
+    parent?: Record<string, unknown>;
+    /** All resolved parent nodes (flattened) */
+    parents?: Record<string, unknown>[];
+}
+/**
+ * Evaluate a JSONata expression against a context.
+ * Returns the result of the expression (boolean for rule checks).
+ *
+ * @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>;
+/**
+ * Build an evaluation context for a given node.
+ *
+ * @param node - The node to build context for
+ * @param allNodes - All nodes in the space
+ * @param nodeIndex - Map of node titles to nodes for efficient lookup
+ * @returns Evaluation context for the node
+ */
+export declare function buildEvalContext(node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<string, SpaceNode>): EvalContext;

package/dist/schema/evaluate-rule.js

@@ -0,0 +1,82 @@
+import jsonata from 'jsonata';
+const expressionCache = new Map();
+/**
+ * Evaluate a JSONata expression against a context.
+ * Returns the result of the expression (boolean for rule checks).
+ *
+ * @param expr - JSONata expression string
+ * @param context - Evaluation context with $, $$, parent, $lookup
+ * @returns Result of expression evaluation
+ */
+export async function evaluateExpression(expr, context) {
+    // Build a structured input object for JSONata
+    // This allows expressions to access nodes, current, and parent as properties
+    const input = {
+        nodes: context.nodes,
+        current: context.$$,
+    };
+    // Only add parent if it exists (not undefined)
+    if (context.parent !== undefined) {
+        input.parent = context.parent;
+    }
+    // Add parents array if present
+    if (context.parents !== undefined) {
+        input.parents = context.parents;
+    }
+    try {
+        let expression = expressionCache.get(expr);
+        if (!expression) {
+            expression = jsonata(expr);
+            expressionCache.set(expr, expression);
+        }
+        // Pass the structured input - expressions access nodes, current, parent from it
+        const result = await expression.evaluate(input);
+        return result;
+    }
+    catch (error) {
+        // Log warning and return false (fail safe)
+        console.warn(`Warning: Error evaluating expression "${expr}":`, error);
+        return false;
+    }
+}
+/**
+ * Flatten a SpaceNode for JSONata evaluation.
+ * Creates a new object with schemaData properties at the top level.
+ *
+ * @param node - The node to flatten
+ * @returns Flattened node with properties directly accessible
+ */
+function flattenNode(node) {
+    return {
+        ...node.schemaData,
+        resolvedType: node.resolvedType,
+        resolvedParentTitle: node.resolvedParents[0]?.title, // first parent or undefined, provided for convenience
+        resolvedParentTitles: node.resolvedParents.map((r) => r.title), // full array of parent titles
+    };
+}
+/**
+ * Build an evaluation context for a given node.
+ *
+ * @param node - The node to build context for
+ * @param allNodes - All nodes in the space
+ * @param nodeIndex - Map of node titles to nodes for efficient lookup
+ * @returns Evaluation context for the node
+ */
+export function buildEvalContext(node, allNodes, nodeIndex) {
+    // Flatten all nodes for JSONata access
+    const flattenedNodes = allNodes.map(flattenNode);
+    // Build all parent objects from resolvedParents array
+    const flattenedParents = [];
+    for (const { title: parentTitle } of node.resolvedParents) {
+        const parentNode = nodeIndex.get(parentTitle);
+        if (parentNode) {
+            flattenedParents.push(flattenNode(parentNode));
+        }
+    }
+    return {
+        nodes: flattenedNodes,
+        $$: flattenNode(node),
+        parent: flattenedParents[0],
+        parents: flattenedParents.length > 0 ? flattenedParents : undefined,
+    };
+}