structured-context 0.11.0 → 0.12.0

package/dist/plugins/util.js

@@ -1,3 +1,6 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { PLUGIN_PREFIX as _PLUGIN_PREFIX } from '../constants';
 export const PLUGIN_PREFIX = _PLUGIN_PREFIX;
 export const CONFIG_PLUGINS_DIR = 'plugins';
@@ -9,3 +12,139 @@ export function normalizePluginName(name) {
 export function shortenPluginName(name) {
     return name.startsWith(PLUGIN_PREFIX) ? name.slice(PLUGIN_PREFIX.length) : name;
 }
+/** Type guard for multi-file render result. */
+export function isRenderMultiFileOutput(result) {
+    return typeof result === 'object' && result !== null && Array.isArray(result.files);
+}
+/**
+ * Synchronously locate the root directory of an external plugin.
+ * Resolution order:
+ * 1. Config-adjacent: {configDir}/plugins/{name} or {configDir}/plugins/sctx-{name}
+ * 2. Node module: resolve from configDir using standard module resolution
+ */
+export function resolvePluginDir(pluginName, configDir) {
+    const normalized = normalizePluginName(pluginName);
+    const short = shortenPluginName(pluginName);
+    for (const candidate of [normalized, short]) {
+        const localDir = resolve(configDir, CONFIG_PLUGINS_DIR, candidate);
+        if (existsSync(localDir)) {
+            try {
+                if (statSync(localDir).isDirectory()) {
+                    return localDir;
+                }
+            }
+            catch { }
+        }
+    }
+    // Node module resolution from configDir
+    for (const candidate of [normalized, short]) {
+        try {
+            const req = createRequire(join(configDir, 'package.json'));
+            const pkgPath = req.resolve(`${candidate}/package.json`);
+            return dirname(pkgPath);
+        }
+        catch {
+            const nmCandidate = resolve(configDir, 'node_modules', candidate);
+            if (existsSync(nmCandidate)) {
+                try {
+                    if (statSync(nmCandidate).isDirectory()) {
+                        return nmCandidate;
+                    }
+                }
+                catch { }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Synchronously locate the schemas directory for a plugin.
+ * Convention:
+ * 1. package.json "sctx": { "schemas": "..." }
+ * 2. Convention: <pluginDir>/schemas
+ * 3. Fallback for test fixtures: {configDir}/plugins/schemas
+ */
+export function resolvePluginSchemasDir(pluginName, configDir) {
+    const dir = resolvePluginDir(pluginName, configDir);
+    if (dir) {
+        // 1. package.json sctx.schemas
+        const pkgJsonPath = join(dir, 'package.json');
+        if (existsSync(pkgJsonPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+                if (pkg.sctx?.schemas && typeof pkg.sctx.schemas === 'string') {
+                    const customSchemas = resolve(dir, pkg.sctx.schemas);
+                    if (existsSync(customSchemas) && statSync(customSchemas).isDirectory()) {
+                        return customSchemas;
+                    }
+                }
+            }
+            catch { }
+        }
+        // 2. Convention: <pluginDir>/schemas
+        const conventionDir = join(dir, 'schemas');
+        if (existsSync(conventionDir)) {
+            try {
+                if (statSync(conventionDir).isDirectory()) {
+                    return conventionDir;
+                }
+            }
+            catch { }
+        }
+    }
+    // 3. Check config-adjacent plugins/schemas as fallback (e.g. test fixtures)
+    const fallbackSchemas = resolve(configDir, CONFIG_PLUGINS_DIR, 'schemas');
+    if (existsSync(fallbackSchemas)) {
+        try {
+            if (statSync(fallbackSchemas).isDirectory()) {
+                return fallbackSchemas;
+            }
+        }
+        catch { }
+    }
+    return undefined;
+}
+/**
+ * Synchronously collect all plugin schema sources available to a space.
+ */
+export function resolveSpacePluginSchemas(space, config, configDir) {
+    const pluginSources = [];
+    const seenPlugins = new Set();
+    const maybeAddPlugin = (name) => {
+        const shortName = shortenPluginName(name);
+        if (seenPlugins.has(shortName))
+            return;
+        seenPlugins.add(shortName);
+        const schemasDir = resolvePluginSchemasDir(name, configDir);
+        if (schemasDir) {
+            pluginSources.push({
+                pluginName: shortName,
+                schemasDir,
+            });
+        }
+    };
+    // 1. Plugin referenced by space.schema prefix if any (e.g. sctx-wardley-mapping/wardley_map.json)
+    const rawSchema = space?.schema ?? config.schema;
+    if (rawSchema && !isAbsolute(rawSchema) && !rawSchema.startsWith('.')) {
+        const normalized = rawSchema.replace(/\\/g, '/');
+        const slashIdx = normalized.indexOf('/');
+        if (slashIdx !== -1) {
+            const prefix = normalized.slice(0, slashIdx);
+            maybeAddPlugin(prefix);
+        }
+    }
+    // 2. Plugins configured on space
+    if (space?.plugins) {
+        for (const name of Object.keys(space.plugins)) {
+            maybeAddPlugin(name);
+        }
+    }
+    // 3. Plugins configured globally
+    const globalPlugins = config.plugins;
+    if (globalPlugins) {
+        for (const name of Object.keys(globalPlugins)) {
+            maybeAddPlugin(name);
+        }
+    }
+    return pluginSources;
+}

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

@@ -1,7 +1,7 @@
 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.
+ * 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).
  */

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';
 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';
 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/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;
+}