structured-context 0.11.0 → 0.13.0

package/dist/commands/render.js

@@ -1,17 +1,72 @@
-import { writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { discoverPlugins, loadPlugins } from '../plugins/loader';
+import { isRenderMultiFileOutput } from '../plugins/util';
 import { buildFormatRegistry } from '../render/registry';
 import { executeRender } from '../render/render';
 export async function render(context, format, options) {
-    const result = await executeRender(format, context, { filter: options.filter });
-    if (options.output) {
-        writeFileSync(options.output, result);
-        console.error(`Written to ${options.output}`);
+    const result = await executeRender(format, context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+        data: options.data,
+    });
+    const targetPath = options.out ?? options.output;
+    const force = Boolean(options.force);
+    if (typeof result === 'string') {
+        if (targetPath) {
+            const resolved = resolve(targetPath);
+            if (existsSync(resolved)) {
+                if (statSync(resolved).isDirectory()) {
+                    throw new Error(`Output path "${targetPath}" is a directory. Please specify a file path.`);
+                }
+                if (!force) {
+                    throw new Error(`File "${targetPath}" already exists. Use --force to overwrite.`);
+                }
+            }
+            mkdirSync(dirname(resolved), { recursive: true });
+            writeFileSync(resolved, result, 'utf8');
+            console.error(`Written to ${targetPath}`);
+        }
+        else {
+            process.stdout.write(result);
+            if (!result.endsWith('\n'))
+                process.stdout.write('\n');
+        }
+        return;
     }
-    else {
-        process.stdout.write(result);
-        if (!result.endsWith('\n'))
-            process.stdout.write('\n');
+    if (isRenderMultiFileOutput(result)) {
+        if (targetPath) {
+            const targetDir = resolve(targetPath);
+            const conflicts = [];
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                if (existsSync(fullPath)) {
+                    conflicts.push(file.path);
+                }
+            }
+            if (conflicts.length > 0 && !force) {
+                const preview = conflicts
+                    .slice(0, 5)
+                    .map((f) => `  ${f}`)
+                    .join('\n');
+                const extra = conflicts.length > 5 ? `\n  ... and ${conflicts.length - 5} more` : '';
+                throw new Error(`Refusing to overwrite ${conflicts.length} existing file(s) in "${targetPath}" without --force:\n${preview}${extra}`);
+            }
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                mkdirSync(dirname(fullPath), { recursive: true });
+                writeFileSync(fullPath, file.content, 'utf8');
+            }
+            console.error(`Written ${result.files.length} file(s) to ${targetPath}`);
+        }
+        else {
+            console.log(`Rendered ${result.files.length} file(s):`);
+            for (const file of result.files) {
+                const bytes = Buffer.byteLength(file.content, 'utf8');
+                console.log(`  ${file.path} (${bytes} bytes)`);
+            }
+            console.log('\nSpecify --out <dir> to write files to disk.');
+        }
     }
 }
 export async function renderList(context) {

package/dist/commands/schemas.d.ts

@@ -1,6 +1,6 @@
-export declare function listSchemas(): void;
+export declare function listSchemas(): Promise<void>;
 export declare function showSchema(file: string | undefined, options: {
     space?: string;
     raw: boolean;
     mermaidErd?: boolean;
-}): void;
+}): Promise<void>;

package/dist/commands/schemas.js

@@ -1,8 +1,13 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { loadConfig, resolveSchema } from '../config';
-import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema } from '../schema/schema';
+import { dirname, join, resolve } from 'node:path';
+import { loadConfig } from '../config';
+import { discoverPlugins } from '../plugins/loader';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { ruleSemantic } from '../schema/rule-severity';
+import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema, } from '../schema/schema';
 import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
+import { DEFAULT_SEVERITY_BY_CATEGORY } from '../schema/validate-rules';
+import { createSpaceContext } from '../space-context';
 function isBundledPath(schemaPath) {
     return dirname(schemaPath) === bundledSchemasDir;
 }
@@ -73,9 +78,14 @@ function showDefs(defs) {
     }
 }
 function showMetadata(metadata) {
-    if (metadata.hierarchy?.levels.length) {
-        const parts = metadata.hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
-        console.log(`\nhierarchy: ${parts.join(' → ')}`);
+    const hierarchies = metadata.hierarchies ?? [];
+    if (hierarchies.length > 0) {
+        console.log('');
+        for (const hierarchy of hierarchies) {
+            const parts = hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
+            const main = hierarchy === metadata.hierarchy ? ' (main)' : '';
+            console.log(`hierarchy "${hierarchy.name}"${main}: ${parts.join(' → ')}`);
+        }
     }
     else {
         console.log('\nhierarchy: (none)');
@@ -88,15 +98,15 @@ function showMetadata(metadata) {
         const groups = new Map();
         for (const rule of metadata.rules) {
             const rules = groups.get(rule.category) ?? [];
-            rules.push({ id: rule.id, description: rule.description });
+            rules.push(rule);
             groups.set(rule.category, rules);
         }
         if (groups.size > 0) {
             console.log('\nRules:');
-            for (const [group, items] of groups) {
-                console.log(`  ${group}:`);
-                for (const item of items) {
-                    console.log(`    ${item.id}: ${item.description}`);
+            for (const [category, rules] of groups) {
+                console.log(`  ${category} (default severity: ${DEFAULT_SEVERITY_BY_CATEGORY[category]}):`);
+                for (const rule of rules) {
+                    console.log(`    ${rule.id}: ${rule.description}${ruleAnnotations(rule)}`);
                 }
             }
         }
@@ -110,7 +120,7 @@ function showMetadata(metadata) {
         }
     }
 }
-function showRegistry(schemaPath, schemaRefRegistry) {
+function showRegistry(schemaPath, schemaRefRegistry, pluginSchemas) {
     const bundledIds = new Set();
     if (existsSync(bundledSchemasDir)) {
         for (const file of readdirSync(bundledSchemasDir).filter((f) => f.endsWith('.json'))) {
@@ -119,9 +129,22 @@ function showRegistry(schemaPath, schemaRefRegistry) {
                 bundledIds.add(s.$id);
         }
     }
+    const pluginIds = new Set();
+    if (pluginSchemas) {
+        for (const { schemasDir } of pluginSchemas) {
+            if (!existsSync(schemasDir))
+                continue;
+            for (const file of readdirSync(schemasDir).filter((f) => f.endsWith('.json'))) {
+                const s = readRawSchema(join(schemasDir, file));
+                if (typeof s.$id === 'string')
+                    pluginIds.add(s.$id);
+            }
+        }
+    }
     console.log(`\nRegistry (${schemaPath}):`);
     for (const [id] of schemaRefRegistry) {
-        console.log(`  [${bundledIds.has(id) ? 'bundled' : 'local'}]  ${id}`);
+        const origin = bundledIds.has(id) ? 'bundled' : pluginIds.has(id) ? 'plugin' : 'local';
+        console.log(`  [${origin}]  ${id}`);
     }
 }
 /**
@@ -130,7 +153,6 @@ function showRegistry(schemaPath, schemaRefRegistry) {
  */
 function generateMermaidErd(metadata, entities) {
     let mmd = 'erDiagram\n';
-    const hierarchyLevels = metadata.hierarchy?.levels ?? [];
     // Generate entity definitions with properties
     for (const entity of entities) {
         const safeName = entity.type.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -145,8 +167,8 @@ function generateMermaidErd(metadata, entities) {
         }
         mmd += '  }\n';
     }
-    // Generate relationships based on hierarchy metadata
-    if (hierarchyLevels.length > 0) {
+    // Generate relationships based on the levels of each hierarchy
+    for (const { levels: hierarchyLevels } of metadata.hierarchies ?? []) {
         for (let i = 0; i < hierarchyLevels.length - 1; i++) {
             const current = hierarchyLevels[i];
             const next = hierarchyLevels[i + 1];
@@ -166,7 +188,26 @@ function generateMermaidErd(metadata, entities) {
     }
     return mmd;
 }
-export function listSchemas() {
+/** Bracketed notes on a rule: semantic, severity (and verdict severities) and `when`. Empty for a plain rule. */
+function ruleAnnotations(rule) {
+    const notes = [];
+    const semantic = ruleSemantic(rule);
+    if (rule.global)
+        notes.push('global');
+    if (semantic)
+        notes.push('semantic');
+    if (rule.severity)
+        notes.push(`severity: ${rule.severity}`);
+    if (semantic?.severity) {
+        notes.push(`verdict severity: ${Object.entries(semantic.severity)
+            .map(([verdict, sev]) => `${verdict}=${sev}`)
+            .join(', ')}`);
+    }
+    if (rule.when)
+        notes.push(`when: ${rule.when}`);
+    return notes.length > 0 ? ` [${notes.join('] [')}]` : '';
+}
+export async function listSchemas() {
     const config = loadConfig();
     // List all schemas known to config
     if (existsSync(bundledSchemasDir)) {
@@ -182,6 +223,23 @@ export function listSchemas() {
             }
         }
     }
+    // List schemas provided by discovered plugins
+    const plugins = await discoverPlugins();
+    for (const p of plugins) {
+        if (p.schemasDir && existsSync(p.schemasDir)) {
+            const files = readdirSync(p.schemasDir)
+                .filter((f) => f.endsWith('.json'))
+                .sort();
+            if (files.length > 0) {
+                console.log(`\nPlugin schemas (${p.name}):`);
+                for (const file of files) {
+                    const schema = readRawSchema(join(p.schemasDir, file));
+                    const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
+                    console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
+                }
+            }
+        }
+    }
     const configured = [];
     const seen = new Set();
     if (config.schema && !isBundledPath(config.schema)) {
@@ -201,16 +259,23 @@ export function listSchemas() {
         }
     }
 }
-export function showSchema(file, options) {
+export async function showSchema(file, options) {
     const config = loadConfig();
     let schemaPath;
+    let schema;
+    let schemaRefRegistry;
+    let pluginSchemas;
     if (options.space) {
         const space = config.spaces.find((s) => s.name === options.space);
         if (!space) {
             console.error(`Error: Unknown space "${options.space}"`);
             process.exit(1);
         }
-        schemaPath = resolveSchema(config, space);
+        const context = createSpaceContext(options.space, config);
+        schemaPath = context.resolvedSchemaPath;
+        schema = context.schema;
+        schemaRefRegistry = context.schemaRefRegistry;
+        pluginSchemas = resolveSpacePluginSchemas(context.space, config, context.configDir);
     }
     else if (!file) {
         console.error('Error: specify a file argument or use --space');
@@ -220,7 +285,49 @@ export function showSchema(file, options) {
         schemaPath = file;
     }
     else {
-        schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        // Check discovered plugins
+        const discovered = await discoverPlugins();
+        pluginSchemas = discovered
+            .filter((p) => p.schemasDir)
+            .map((p) => ({ pluginName: shortenPluginName(p.name), schemasDir: p.schemasDir }));
+        let candidatePath;
+        if (file.includes('/')) {
+            const slashIdx = file.indexOf('/');
+            const prefix = file.slice(0, slashIdx);
+            const subPath = file.slice(slashIdx + 1);
+            const norm = normalizePluginName(prefix);
+            const short = shortenPluginName(prefix);
+            const pluginDir = resolvePluginSchemasDir(prefix, process.cwd());
+            if (pluginDir) {
+                candidatePath = resolve(pluginDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                if (!pluginSchemas.some((ps) => ps.pluginName === short)) {
+                    pluginSchemas.push({ pluginName: short, schemasDir: pluginDir });
+                }
+            }
+            else {
+                const match = discovered.find((p) => (p.name === norm || p.name === short) && p.schemasDir);
+                if (match?.schemasDir) {
+                    candidatePath = resolve(match.schemasDir, subPath.endsWith('.json') ? subPath : `${subPath}.json`);
+                }
+            }
+        }
+        else {
+            for (const p of discovered) {
+                if (p.schemasDir) {
+                    const c = resolve(p.schemasDir, file.endsWith('.json') ? file : `${file}.json`);
+                    if (existsSync(c)) {
+                        candidatePath = c;
+                        break;
+                    }
+                }
+            }
+        }
+        if (candidatePath && existsSync(candidatePath)) {
+            schemaPath = candidatePath;
+        }
+        else {
+            schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+        }
     }
     if (!existsSync(schemaPath)) {
         console.error(`Schema not found: ${schemaPath}`);
@@ -237,7 +344,11 @@ export function showSchema(file, options) {
         process.stdout.write(content);
         return;
     }
-    const { schema, schemaRefRegistry } = loadSchema(schemaPath);
+    if (!schema || !schemaRefRegistry) {
+        const loaded = loadSchema(schemaPath, pluginSchemas);
+        schema = loaded.schema;
+        schemaRefRegistry = loaded.schemaRefRegistry;
+    }
     // Handle --mermaid-erd: generate ERD and exit
     if (options.mermaidErd) {
         const entityInfo = extractEntityInfo(schema, schemaRefRegistry);
@@ -265,5 +376,5 @@ export function showSchema(file, options) {
             console.log(`  ${ref}`);
         }
     }
-    showRegistry(schemaPath, schemaRefRegistry);
+    showRegistry(schemaPath, schemaRefRegistry, pluginSchemas);
 }

package/dist/commands/show.d.ts

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

package/dist/commands/show.js

@@ -1,6 +1,12 @@
 import { executeRender } from '../render/render';
 export async function show(context, options) {
-    const result = await executeRender('markdown.bullets', context, { filter: options?.filter });
+    const result = await executeRender('markdown.bullets', context, {
+        filter: options?.filter,
+        hierarchy: options?.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from markdown.bullets renderer');
+    }
     process.stdout.write(result);
     if (!result.endsWith('\n'))
         process.stdout.write('\n');

package/dist/commands/spaces.d.ts

@@ -1 +1,3 @@
-export declare function listSpaces(): void;
+export declare function listSpaces(options?: {
+    json?: boolean;
+}): void;

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.d.ts

@@ -6,4 +6,7 @@ export { validateFile } from '../validate';
  */
 export declare function validateFileCommand(filePath: string, options?: {
     json?: boolean;
+    includeGated?: boolean;
+    semantic?: boolean | string;
+    ruleFilter?: string[];
 }): Promise<number>;

package/dist/commands/validate-file.js

@@ -1,5 +1,8 @@
 import { loadConfig } from '../config';
-import { validateFile } from '../validate';
+import { judgeForRun } from '../judge/factory';
+import { parseRuleFilter } from '../schema/rule-filter';
+import { createSpaceContext } from '../space-context';
+import { fileNotInSpace, resolveFileSpace, validateResolvedFile } from '../validate';
 export { validateFile } from '../validate';
 /**
  * CLI command: validate a file and print results to stdout.
@@ -8,7 +11,19 @@ export { validateFile } from '../validate';
  */
 export async function validateFileCommand(filePath, options = {}) {
     const config = loadConfig();
-    const result = await validateFile(filePath, config);
+    const resolved = resolveFileSpace(filePath, config);
+    let result;
+    if (resolved) {
+        const judge = judgeForRun(config, resolved.space, options.semantic);
+        result = await validateResolvedFile(filePath, resolved.label, createSpaceContext(resolved.space.name, config), {
+            includeGated: options.includeGated,
+            judge,
+            ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
+        });
+    }
+    else {
+        result = fileNotInSpace(filePath);
+    }
     if (!result.inSpace) {
         if (options.json) {
             console.log(JSON.stringify(result, null, 2));
@@ -34,8 +49,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 +58,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.d.ts

@@ -1,5 +1,9 @@
 import type { SpaceContext } from '../types';
 export declare function validate(context: SpaceContext, options?: {
     json?: boolean;
+    depth?: number;
+    includeGated?: boolean;
+    semantic?: boolean | string;
+    ruleFilter?: string[];
 }): Promise<number>;
 export declare function watchValidate(context: SpaceContext): Promise<never>;