structured-context 0.11.0 → 0.12.0

package/dist/commands/spaces.js

@@ -1,13 +1,22 @@
 import { basename, resolve } from 'node:path';
-import { configPath, loadConfig } from '../config';
+import { configPath, getConfigSourceFiles, loadConfig } from '../config';
 function renderConfigValue(v) {
     if (typeof v === 'object' && v !== null)
         return JSON.stringify(v);
     return String(v);
 }
-export function listSpaces() {
+export function listSpaces(options = {}) {
     const path = resolve(configPath());
     const config = loadConfig();
+    if (options.json) {
+        const spaces = config.spaces.map((space) => ({
+            name: space.name,
+            path: space.path,
+            schema: space.schema ?? config.schema,
+        }));
+        console.log(JSON.stringify({ configFiles: [...getConfigSourceFiles()], spaces }));
+        return;
+    }
     console.log(`Config: ${path}\n`);
     for (const space of config.spaces) {
         console.log(`${space.name}`);

package/dist/commands/validate-file.js

@@ -34,8 +34,8 @@ function printHumanReadable(result) {
     }
     if (result.errorCount > 0) {
         console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`);
-        for (const { kind, message } of Object.values(result.errors)) {
-            console.log(`  [${kind}] ${message}`);
+        for (const issue of Object.values(result.errors)) {
+            console.log(`  [${issueLabel(issue)}] ${issue.message}`);
         }
     }
     else {
@@ -43,9 +43,12 @@ function printHumanReadable(result) {
     }
     if (result.warningCount > 0) {
         console.log(`\n  ${yellow}${result.warningCount} warning(s):${reset}`);
-        for (const { kind, message } of Object.values(result.warnings)) {
-            console.log(`  ${yellow}[${kind}]${reset} ${message}`);
+        for (const issue of Object.values(result.warnings)) {
+            console.log(`  ${yellow}[${issueLabel(issue)}]${reset} ${issue.message}`);
         }
     }
     console.log('');
 }
+function issueLabel({ kind, severity }) {
+    return severity ? `${kind}:${severity}` : kind;
+}

package/dist/commands/validate.js

@@ -1,18 +1,22 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
+import { resolveSpacePluginSchemas } from '../plugins/util';
 import { bundledSchemasDir } from '../schema/schema';
 import { formatErrors, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry } = context;
     const result = await validateSpace(context);
+    const ruleCounts = { error: 0, warning: 0, info: 0 };
+    for (const v of result.ruleViolations)
+        ruleCounts[v.severity]++;
     // JSON output mode
     if (options.json) {
         const errorsByFile = {};
-        const addError = (file, key, kind, message) => {
+        const addError = (file, key, kind, message, severity) => {
             if (!errorsByFile[file])
                 errorsByFile[file] = {};
-            errorsByFile[file][key] = { kind, message };
+            errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
         };
         for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) {
             const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
@@ -30,21 +34,25 @@ export async function validate(context, options = {}) {
             }
         }
         for (const v of result.ruleViolations) {
-            if (v.file) {
-                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`);
+            if (v.file && v.severity === 'error') {
+                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`, v.severity);
             }
         }
+        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length;
         for (const v of result.hierarchyViolations) {
             addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
         }
         const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
-        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + parseErrorCount;
+        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) +
+            parseErrorCount +
+            globalRuleErrorCount;
         console.log(JSON.stringify({
             space: context.space.name,
             valid: errorCount === 0,
             validCount: result.validCount,
             errorCount,
             errors: errorsByFile,
+            ruleViolations: result.ruleViolations,
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
             unresolvedContentLinks: result.unresolvedContentLinks,
@@ -79,7 +87,9 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Schema validation errors', result.nodeErrorCount, true));
     console.log(fmt('  Broken links', result.refErrors.length, true));
     console.log(fmt('  Duplicate keys', result.duplicateErrors.length, true));
-    console.log(fmt('  Rule violations', result.ruleViolations.length, true));
+    console.log(fmt('  Rule violations (error)', ruleCounts.error, true));
+    console.log(fmt('  Rule violations (warning)', ruleCounts.warning, true, true));
+    console.log(fmt('  Rule violations (info)', ruleCounts.info, true, true));
     console.log(fmt('  Hierarchy violations', result.hierarchyViolations.length, true));
     console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphans.length, true, true));
     console.log(fmt('  Unresolved content links', result.unresolvedContentLinks.length, true, true));
@@ -107,14 +117,16 @@ export async function validate(context, options = {}) {
     if (result.parseIssues.length > 0) {
         console.log(`\nExcluded during parsing:`);
         for (const issue of result.parseIssues) {
+            const loc = issue.line !== undefined ? `:${issue.line}${issue.column !== undefined ? `:${issue.column}` : ''}` : '';
             const detail = issue.message ? ` - ${issue.message}` : '';
-            console.log(`   ${issue.file}: ${issue.severity} - ${issue.type}${detail}`);
+            console.log(`   ${issue.file}${loc}: ${issue.severity} - ${issue.type}${detail}`);
         }
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ file, errors, nodeData }) => {
-            console.log(`\n   ${file}:`);
+        result.nodeErrors.forEach(({ file, line, errors, nodeData }) => {
+            const loc = line !== undefined ? `:${line}` : '';
+            console.log(`\n   ${file}${loc}:`);
             const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
             formatted.forEach(({ message }) => {
                 console.log(`      ${message}`);
@@ -123,8 +135,9 @@ export async function validate(context, options = {}) {
     }
     if (result.refErrors.length > 0) {
         console.log(`\nBroken links:`);
-        result.refErrors.forEach(({ file, parent, error }) => {
-            console.log(`   ${file}: ${parent} → ${error}`);
+        result.refErrors.forEach(({ file, line, parent, error }) => {
+            const loc = line !== undefined ? `:${line}` : '';
+            console.log(`   ${file}${loc}: ${parent} → ${error}`);
         });
     }
     if (result.duplicateErrors.length > 0) {
@@ -138,16 +151,14 @@ export async function validate(context, options = {}) {
     }
     if (result.ruleViolations.length > 0) {
         console.log(`\nRule violations:`);
-        const byCategory = new Map();
-        for (const v of result.ruleViolations) {
-            if (!byCategory.has(v.category))
-                byCategory.set(v.category, []);
-            byCategory.get(v.category).push(v);
-        }
-        for (const [category, violations] of byCategory) {
-            console.log(`  ${category.toUpperCase()} (${violations.length}):`);
+        const severityColor = { error: red, warning: yellow, info: reset };
+        for (const severity of ['error', 'warning', 'info']) {
+            const violations = result.ruleViolations.filter((v) => v.severity === severity);
+            if (violations.length === 0)
+                continue;
+            console.log(`  ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`);
             for (const v of violations) {
-                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description}`);
+                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
             }
         }
     }
@@ -161,7 +172,7 @@ export async function validate(context, options = {}) {
     if (result.nodeErrorCount > 0 ||
         result.refErrors.length > 0 ||
         result.duplicateErrors.length > 0 ||
-        result.ruleViolations.length > 0 ||
+        ruleCounts.error > 0 ||
         result.hierarchyViolations.length > 0 ||
         parseIssueErrorCount > 0) {
         return 1;
@@ -177,6 +188,12 @@ export async function watchValidate(context) {
     if (schemaDir !== bundledSchemasDir) {
         schemaDirs.push(schemaDir);
     }
+    const pluginSources = resolveSpacePluginSchemas(context.space, context.config, context.configDir);
+    for (const ps of pluginSources) {
+        if (!schemaDirs.includes(ps.schemasDir)) {
+            schemaDirs.push(ps.schemasDir);
+        }
+    }
     console.log(`👀 Watching for changes...`);
     console.log(`   Config files: ${configFiles.join(', ')}`);
     console.log(`   Schema dirs: ${schemaDirs.join(', ')}`);

package/dist/config.d.ts

@@ -28,7 +28,24 @@ export declare function configPath(): string;
 export declare function loadConfig(): Config;
 /** Get the full space config entry by name. Throws if not found. */
 export declare function getSpaceConfig(name: string, config: Config): SpaceConfig;
+/**
+ * Resolve a schema identifier or path to an absolute file path.
+ *
+ * Precedence:
+ * 1. Absolute path or URL → used directly.
+ * 2. Explicit relative path (./... or ../...) → resolved relative to configDir.
+ * 3. Plugin-qualified path (e.g. "sctx-wardley-mapping/wardley_map.json" or "wardley-mapping/wardley_map.json"):
+ *    resolved against the matching loaded plugin's schemasDir.
+ * 4. Simple filename without directory (e.g. "wardley_map.json" or "strategy_general.json"):
+ *    - configDir/filename if it exists
+ *    - plugin.schemasDir/filename for any loaded plugin with schemasDir
+ *    - bundledSchemasDir/filename if it exists
+ *    - fallback: configDir/filename
+ */
+export declare function resolveSchemaPath(rawSchema: string | undefined, configDir: string, space?: SpaceConfig, config?: Config): string;
 /** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
-export declare function resolveSchema(config: Config, space?: SpaceConfig): string;
+export declare function resolveSchema(config: Config, space?: SpaceConfig, options?: {
+    configDir?: string;
+}): string;
 /** Update a string field on a space entry and persist config. When `plugin` is given, updates that field inside `space.plugins[plugin]` instead. */
 export declare function updateSpaceField(spaceName: string, field: string, value: string, plugin?: string): void;

package/dist/config.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020';
 import JSON5 from 'json5';
 import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
-import { normalizePluginName, shortenPluginName } from './plugins/util';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util';
 import { bundledSchemasDir } from './schema/schema';
 const CONFIG_SCHEMA = {
     type: 'object',
@@ -87,13 +87,10 @@ function resolveRelativePaths(config, configDir) {
     const relSchema = (p) => {
         if (!p || isAbsolute(p) || isUrl(p))
             return p;
-        if (!p.includes('/') && !p.includes('\\')) {
-            const localPath = resolve(configDir, p);
-            if (existsSync(localPath))
-                return localPath;
-            return join(bundledSchemasDir, p);
+        if (p.startsWith('./') || p.startsWith('../')) {
+            return resolve(configDir, p);
         }
-        return resolve(configDir, p);
+        return p;
     };
     return {
         ...config,
@@ -111,7 +108,7 @@ function _loadConfig(path) {
         throw new Error(`Config file not found: ${path}`);
     }
     const config = JSON5.parse(readFileSync(path, 'utf-8'));
-    const ajv = new Ajv();
+    const ajv = new Ajv2020();
     const validate = ajv.compile(CONFIG_SCHEMA);
     if (!validate(config)) {
         throw new Error(`Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
@@ -162,12 +159,86 @@ export function getSpaceConfig(name, config) {
     }
     return space;
 }
+/**
+ * Resolve a schema identifier or path to an absolute file path.
+ *
+ * Precedence:
+ * 1. Absolute path or URL → used directly.
+ * 2. Explicit relative path (./... or ../...) → resolved relative to configDir.
+ * 3. Plugin-qualified path (e.g. "sctx-wardley-mapping/wardley_map.json" or "wardley-mapping/wardley_map.json"):
+ *    resolved against the matching loaded plugin's schemasDir.
+ * 4. Simple filename without directory (e.g. "wardley_map.json" or "strategy_general.json"):
+ *    - configDir/filename if it exists
+ *    - plugin.schemasDir/filename for any loaded plugin with schemasDir
+ *    - bundledSchemasDir/filename if it exists
+ *    - fallback: configDir/filename
+ */
+export function resolveSchemaPath(rawSchema, configDir, space, config) {
+    if (!rawSchema) {
+        throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
+    }
+    if (isAbsolute(rawSchema) || isUrl(rawSchema)) {
+        return rawSchema;
+    }
+    if (rawSchema.startsWith('./') || rawSchema.startsWith('../')) {
+        return resolve(configDir, rawSchema);
+    }
+    if (rawSchema.includes('/') || rawSchema.includes('\\')) {
+        const normalizedSlash = rawSchema.replace(/\\/g, '/');
+        const slashIdx = normalizedSlash.indexOf('/');
+        const prefix = normalizedSlash.slice(0, slashIdx);
+        const subPath = normalizedSlash.slice(slashIdx + 1);
+        const pluginSchemasDir = resolvePluginSchemasDir(prefix, configDir);
+        if (pluginSchemasDir) {
+            const candidate = resolve(pluginSchemasDir, subPath);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        // Check if relative to configDir exists
+        const localCandidate = resolve(configDir, rawSchema);
+        if (existsSync(localCandidate)) {
+            return localCandidate;
+        }
+        // If plugin schemas dir was found, return candidate under it
+        if (pluginSchemasDir) {
+            return resolve(pluginSchemasDir, subPath);
+        }
+        return localCandidate;
+    }
+    // Simple filename without directory:
+    // 1. configDir/filename
+    const localCandidate = resolve(configDir, rawSchema);
+    if (existsSync(localCandidate)) {
+        return localCandidate;
+    }
+    // 2. Plugin schemas from declared space / config plugins
+    if (space || config) {
+        const pluginSources = resolveSpacePluginSchemas(space, config ?? { spaces: [] }, configDir);
+        for (const source of pluginSources) {
+            const pluginCandidate = resolve(source.schemasDir, rawSchema);
+            if (existsSync(pluginCandidate)) {
+                return pluginCandidate;
+            }
+        }
+    }
+    // 3. Bundled schemas
+    const bundledCandidate = join(bundledSchemasDir, rawSchema);
+    if (existsSync(bundledCandidate)) {
+        return bundledCandidate;
+    }
+    return localCandidate;
+}
 /** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
-export function resolveSchema(config, space) {
+export function resolveSchema(config, space, options) {
     const schema = space?.schema ?? config.schema;
     if (!schema) {
         throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
     }
+    const configDir = options?.configDir ?? space?.sourceDir;
+    if (configDir) {
+        return resolveSchemaPath(schema, configDir, space, config);
+    }
     return schema;
 }
 /** Update a string field on a space entry and persist config. When `plugin` is given, updates that field inside `space.plugins[plugin]` instead. */

package/dist/filter/augment-nodes.d.ts

@@ -3,6 +3,8 @@ import type { SpaceNode } from '../types';
 export type EdgeMetadata = {
     _field: string;
     _source: 'hierarchy' | 'relationship';
+    /** Hierarchy name, present only for hierarchy edges. */
+    _hierarchy?: string;
     _selfRef: boolean;
 };
 /** A flat node representation augmented with ancestor and descendant traversal arrays. */
@@ -18,6 +20,6 @@ export type AugmentedFlatNode = Record<string, unknown> & {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
  */
 export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>): AugmentedFlatNode;

package/dist/filter/augment-nodes.js

@@ -1,3 +1,12 @@
+/** Edge metadata for the resolvedParents entry connecting two nodes. */
+function edgeMetadata(ref) {
+    return {
+        _field: ref.field,
+        _source: ref.source,
+        ...(ref.hierarchy !== undefined ? { _hierarchy: ref.hierarchy } : {}),
+        _selfRef: ref.selfRef,
+    };
+}
 /** Flatten a SpaceNode's data fields for use in an augmented representation. */
 function flattenData(node) {
     return {
@@ -13,7 +22,7 @@ function flattenData(node) {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
  */
 export function augmentNode(node, nodeIndex, childrenIndex) {
     const ancestors = buildAncestors(node, nodeIndex);
@@ -44,9 +53,7 @@ function buildAncestors(node, nodeIndex) {
         visited.add(title);
         result.push({
             ...flattenData(item.node),
-            _field: item.ref.field,
-            _source: item.ref.source,
-            _selfRef: item.ref.selfRef,
+            ...edgeMetadata(item.ref),
         });
         // Continue BFS upward
         for (const ref of item.node.resolvedParents) {
@@ -78,9 +85,7 @@ function buildDescendants(node, childrenIndex) {
         visited.add(title);
         result.push({
             ...flattenData(item.childNode),
-            _field: item.ref.field,
-            _source: item.ref.source,
-            _selfRef: item.ref.selfRef,
+            ...edgeMetadata(item.ref),
         });
         const grandchildren = childrenIndex.get(title) ?? [];
         for (const grandchild of grandchildren) {

package/dist/filter/filter-nodes.js

@@ -69,5 +69,5 @@ export async function filterNodes(expression, graph) {
     else {
         matchedNodes = matched;
     }
-    return buildSpaceGraph(matchedNodes, graph.levels);
+    return buildSpaceGraph(matchedNodes, graph.hierarchy);
 }

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { createRequire } from 'node:module';
+import { format } from 'node:util';
 import { Command } from 'commander';
 import { diagram } from './commands/diagram';
 import { docs } from './commands/docs';
@@ -16,6 +17,11 @@ import { validateFileCommand } from './commands/validate-file';
 import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
 import { createSpaceContext, SpaceNotFoundError } from './space-context';
+// Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
+// past 64KB when the reader is slow. process.stdout.write delivers all of it before exit.
+console.log = (...args) => {
+    process.stdout.write(`${format(...args)}\n`);
+};
 export function buildSpaceContext(spaceName) {
     try {
         return createSpaceContext(spaceName, loadConfig());
@@ -45,8 +51,7 @@ program
     .argument('<path>', 'Path to the file to validate')
     .option('--json', 'Output results as JSON (machine-readable, for hooks)')
     .action(async (filePath, options) => {
-    const exitCode = await validateFileCommand(filePath, { json: options.json });
-    process.exit(exitCode);
+    process.exitCode = await validateFileCommand(filePath, { json: options.json });
 });
 program
     .command('validate')
@@ -60,8 +65,8 @@ program
         await watchValidate(context);
     }
     else {
-        const exitCode = await validate(context, { json: options.json });
-        process.exit(exitCode);
+        // exitCode rather than process.exit(): exiting straight away can cut off large piped output
+        process.exitCode = await validate(context, { json: options.json });
     }
 });
 program
@@ -69,19 +74,23 @@ program
     .description('Generate mermaid diagram from space')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
     .option('-o, --output <path>', 'Output file path (default: stdout)')
-    .action((spaceName, options) => diagram(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => diagram(buildSpaceContext(spaceName), options));
 program
     .command('show')
     .description('Print space graph as a bullet list')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .action((spaceName, options) => show(buildSpaceContext(spaceName), options));
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .action(async (spaceName, options) => show(buildSpaceContext(spaceName), options));
 program
     .command('dump')
     .description('Dump parsed space nodes as JSON')
     .argument('<space-name>', 'Space name')
-    .action((spaceName) => dump(buildSpaceContext(spaceName)));
+    .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy used to evaluate --filter (default: the main hierarchy)')
+    .action(async (spaceName, options) => dump(buildSpaceContext(spaceName), options));
 program
     .command('miro-sync')
     .description('Sync space to a Miro board')
@@ -89,16 +98,16 @@ program
     .option('--new-frame <title>', 'Create a new frame on the board and sync into it')
     .option('--dry-run', 'Show what would change without touching Miro')
     .option('-v, --verbose', 'Detailed output')
-    .action((spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
 program
     .command('template-sync')
     .description('Sync schema examples to templates')
     .argument('<space-name>', 'Space name')
     .option('--create-missing', 'Create missing template files for schema types')
     .option('--dry-run', 'Preview changes without writing files')
-    .action((spaceName, options) => {
+    .action(async (spaceName, options) => {
     const context = buildSpaceContext(spaceName);
-    templateSync(context, options);
+    await templateSync(context, options);
 });
 program
     .command('plugins')
@@ -108,13 +117,14 @@ const spacesCmd = new Command('spaces').description('List configured spaces');
 spacesCmd
     .command('list', { isDefault: true })
     .description('List all configured spaces and their paths')
-    .action(listSpaces);
+    .option('--json', 'Output as JSON: config files, and each space with its path and schema')
+    .action((options) => listSpaces(options));
 program.addCommand(spacesCmd);
 const schemasCmd = new Command('schemas').alias('schema').description('List and inspect schemas');
 schemasCmd
     .command('list', { isDefault: true })
     .description('List available schemas')
-    .action(() => listSchemas());
+    .action(async () => await listSchemas());
 schemasCmd
     .command('show')
     .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')
@@ -122,7 +132,7 @@ schemasCmd
     .option('--space <name>', 'Resolve schema from space config')
     .option('--raw', 'Output raw JSON file content')
     .option('--mermaid-erd', 'Output Mermaid Entity Relationship Diagram')
-    .action((file, options) => showSchema(file, {
+    .action(async (file, options) => await showSchema(file, {
     space: options.space,
     raw: options.raw ?? false,
     mermaidErd: options.mermaidErd ?? false,
@@ -141,11 +151,25 @@ renderCmd
     const context = spaceName ? buildSpaceContext(spaceName) : undefined;
     await renderList(context);
 });
+function parseDataOptions(val, prev = {}) {
+    const eqIdx = val.indexOf('=');
+    if (eqIdx >= 0) {
+        prev[val.slice(0, eqIdx).trim()] = val.slice(eqIdx + 1).trim();
+    }
+    else {
+        prev[val.trim()] = 'true';
+    }
+    return prev;
+}
 renderCmd
     .argument('<space-name>', 'Space name')
-    .argument('<format>', 'Render format (e.g. markdown.bullets)')
+    .argument('<format>', 'Render format (e.g. markdown.bullets, markdown.directory)')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .option('-o, --output <path>', 'Output file path (default: stdout)')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .option('-o, --output <path>', 'Output file or directory path (default: stdout)')
+    .option('--out <path>', 'Output directory or file path')
+    .option('-f, --force', 'Overwrite existing files when writing to disk')
+    .option('-d, --data <key=value...>', 'Format-specific key=value options', parseDataOptions)
     .action(async (spaceName, format, options) => {
     await render(buildSpaceContext(spaceName), format, options);
 });

package/dist/load-space-graph.d.ts

@@ -4,13 +4,15 @@ import type { ReadSpaceResult, SpaceContext } from './types';
 export interface AssembleSpaceGraphOptions {
     /** Named view (resolved via space.views) or a raw filter DSL expression. */
     filter?: string;
+    /** Name of the hierarchy to structure the graph by. Defaults to the schema's main hierarchy. */
+    hierarchy?: string;
     /** Pre-loaded read result to assemble from, avoiding a re-read of the space. */
     readResult?: ReadSpaceResult;
 }
 /**
  * Assemble a SpaceGraph from a space context: read the space, drop nodes that
- * fail schema validation, build the hierarchy graph, and apply an optional
- * view/filter expression.
+ * fail schema validation, build the graph for the selected hierarchy (the main
+ * hierarchy by default), and apply an optional view/filter expression.
  *
  * Nodes that fail schema validation are silently excluded so the graph is
  * well-formed enough to render and traverse. This is NOT a validation pass —

package/dist/load-space-graph.js

@@ -4,8 +4,8 @@ import { createSpaceContext } from './space-context';
 import { buildSpaceGraph } from './space-graph';
 /**
  * Assemble a SpaceGraph from a space context: read the space, drop nodes that
- * fail schema validation, build the hierarchy graph, and apply an optional
- * view/filter expression.
+ * fail schema validation, build the graph for the selected hierarchy (the main
+ * hierarchy by default), and apply an optional view/filter expression.
  *
  * Nodes that fail schema validation are silently excluded so the graph is
  * well-formed enough to render and traverse. This is NOT a validation pass —
@@ -19,14 +19,25 @@ export async function assembleSpaceGraph(context, options = {}) {
     const { nodes: allNodes } = options.readResult ?? (await readSpace(context));
     const { schemaValidator } = context;
     const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
-    const levels = context.schema.metadata.hierarchy?.levels ?? [];
-    let graph = buildSpaceGraph(validNodes, levels);
+    let graph = buildSpaceGraph(validNodes, selectHierarchy(context.schema.metadata, options.hierarchy));
     if (options.filter) {
         const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
         graph = await filterNodes(expression, graph);
     }
     return graph;
 }
+/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
+function selectHierarchy(metadata, name) {
+    if (name === undefined)
+        return metadata.hierarchy;
+    const hierarchies = metadata.hierarchies ?? [];
+    const hierarchy = hierarchies.find((h) => h.name === name);
+    if (!hierarchy) {
+        const available = hierarchies.map((h) => h.name).join(', ');
+        throw new Error(`Unknown hierarchy: "${name}".${available ? ` Available: ${available}` : ' The schema defines no hierarchies.'}`);
+    }
+    return hierarchy;
+}
 /**
  * Load a named space and return its assembled, filtered SpaceGraph.
  *

package/dist/plugins/loader.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import Ajv, {} from 'ajv';
+import Ajv2020 from 'ajv/dist/2020';
 import { getConfigSourceFiles } from '../config';
 import { builtinPlugins } from '.';
 import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX, shortenPluginName, } from './util';
@@ -71,7 +71,7 @@ export async function discoverPlugins() {
  */
 export async function loadPlugins(pluginMap, configDir) {
     const builtinsByName = new Map(builtinPlugins.map((p) => [p.name, p]));
-    const ajv = new Ajv();
+    const ajv = new Ajv2020();
     ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
     const loaded = [];
     // External plugins: entries in the map that are not built-in names