structured-context 0.11.0 → 0.13.0

package/dist/commands/validate.js

@@ -1,18 +1,29 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
+import { judgeForRun } from '../judge/factory';
+import { resolveSpacePluginSchemas } from '../plugins/util';
+import { parseRuleFilter } from '../schema/rule-filter';
 import { bundledSchemasDir } from '../schema/schema';
-import { formatErrors, validateSpace } from '../validate';
+import { formatErrors, ruleViolationMessage, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry } = context;
-    const result = await validateSpace(context);
+    const result = await validateSpace(context, {
+        depth: options.depth,
+        includeGated: options.includeGated,
+        judge: judgeForRun(context.config, context.space, options.semantic),
+        ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
+    });
+    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,24 +41,32 @@ 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', ruleViolationMessage(v), 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,
+            coverageGates: result.coverageGates,
+            contextTrimmed: result.contextTrimmed,
+            skippedByDepth: result.skippedByDepth,
+            depthLimit: result.depthLimit,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -79,12 +98,19 @@ 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));
     const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
     console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
+    if (result.depthLimit !== undefined) {
+        console.log(fmt('  Skipped by depth limit', result.skippedByDepth.length, true, true));
+    }
+    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
+    console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
@@ -107,14 +133,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 +151,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 +167,20 @@ 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}]`);
+                if (v.evidence) {
+                    console.log(`      Evidence: ${v.evidence}`);
+                }
+                if (v.guidance) {
+                    console.log(`      Guidance: ${v.guidance}`);
+                }
             }
         }
     }
@@ -157,11 +190,28 @@ export async function validate(context, options = {}) {
             console.log(`   ${v.file}: ${v.description}`);
         }
     }
+    if (result.coverageGates.length > 0) {
+        console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`);
+        for (const gate of result.coverageGates) {
+            const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
+            console.log(`   ${gate.file} (${gate.nodeTitle}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
+            for (const file of gate.gatedFiles)
+                console.log(`      ${file}`);
+        }
+    }
+    if (result.skippedByDepth.length > 0) {
+        console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`);
+        for (const { file } of result.skippedByDepth)
+            console.log(`   ${file}`);
+    }
+    if (result.contextTrimmed.nodeCount > 0) {
+        console.log(`\nContext trimmed for ${result.contextTrimmed.nodeCount} node(s) across rules ${result.contextTrimmed.ruleIds.join(', ')}.`);
+    }
     console.log(`\n`);
     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 +227,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

@@ -1,3 +1,4 @@
+import { type JudgeConfig, type ModelProviderConfig } from './judge/types.js';
 export type SpaceConfig = {
     name: string;
     path: string;
@@ -8,6 +9,8 @@ export type SpaceConfig = {
     views?: Record<string, {
         expression: string;
     }>;
+    /** Model provider for this space's semantic rules; overrides the top-level `semantic`. */
+    semantic?: JudgeConfig;
     /**
      * Directory of the config file that defined this space, used to anchor relative plugin-config
      * paths. Set by loadConfig; absent for a hand-assembled Config, whose callers must pass an
@@ -19,6 +22,10 @@ export type Config = {
     spaces: SpaceConfig[];
     schema?: string;
     includeSpacesFrom?: string[];
+    /** Model providers by name: how to reach each model. */
+    modelProviders?: Record<string, ModelProviderConfig>;
+    /** Model provider for semantic rules (a provider name). A space's `semantic` overrides it. */
+    semantic?: JudgeConfig;
 };
 /** Override the config file path used by loadConfig/updateSpaceField. */
 export declare function setConfigPath(path: string | undefined): void;
@@ -28,7 +35,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,11 +1,31 @@
 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 { bundledSchemasDir } from './schema/schema';
+import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants.js';
+import { MODEL_PROVIDER_APIS } from './judge/types.js';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util.js';
+import { bundledSchemasDir } from './schema/schema.js';
+const MODEL_PROVIDER_SCHEMA = {
+    type: 'object',
+    properties: {
+        api: { type: 'string', enum: MODEL_PROVIDER_APIS },
+        model: { type: 'string' },
+        modelEnv: { type: 'string' },
+        endpoint: { type: 'string' },
+        endpointEnv: { type: 'string' },
+        apiKey: { type: 'string' },
+        apiKeyEnv: { type: 'string' },
+    },
+    required: ['api'],
+    additionalProperties: false,
+};
+const SEMANTIC_CONFIG_SCHEMA = {
+    type: 'object',
+    properties: { provider: { type: 'string', minLength: 1 } },
+    additionalProperties: false,
+};
 const CONFIG_SCHEMA = {
     type: 'object',
     properties: {
@@ -27,6 +47,7 @@ const CONFIG_SCHEMA = {
                             additionalProperties: false,
                         },
                     },
+                    semantic: SEMANTIC_CONFIG_SCHEMA,
                 },
                 required: ['name', 'path'],
                 additionalProperties: false,
@@ -34,6 +55,8 @@ const CONFIG_SCHEMA = {
         },
         schema: { type: 'string' },
         includeSpacesFrom: { type: 'array', items: { type: 'string' } },
+        modelProviders: { type: 'object', additionalProperties: MODEL_PROVIDER_SCHEMA },
+        semantic: SEMANTIC_CONFIG_SCHEMA,
     },
     anyOf: [{ required: ['spaces'] }, { required: ['includeSpacesFrom'] }],
     additionalProperties: false,
@@ -87,13 +110,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 +131,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 +182,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.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
-import type { SpaceContext } from './types';
+import type { SpaceContext } from './types.js';
 export declare function buildSpaceContext(spaceName: string): SpaceContext;