structured-context 0.9.3 → 0.10.0

package/dist/api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public API for structured-context.
+ *
+ * Import from this module to use structured-context as a library:
+ *
+ *   import { validateFile } from 'structured-context/api';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ */
+export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
+export type { Config, SpaceConfig } from './config';
+export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export type { SharedEmbeddingFields } from './schema/metadata-contract';
+export type { SpaceGraph } from './space-graph';
+export type { BaseNode, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export { validateFile } from './validate';

package/dist/api.js

@@ -0,0 +1,9 @@
+/**
+ * Public API for structured-context.
+ *
+ * Import from this module to use structured-context as a library:
+ *
+ *   import { validateFile } from 'structured-context/api';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ */
+export { validateFile } from './validate';

package/dist/commands/dump.js

@@ -1,4 +1,4 @@
-import { JSON5 } from 'bun';
+import JSON5 from 'json5';
 import { readSpace } from '../read/read-space';
 export async function dump(context) {
     const { nodes, source, diagnostics } = await readSpace(context);

package/dist/commands/validate-file.d.ts

@@ -1,28 +1,9 @@
-export interface FileValidationResult {
-    file: string;
-    label: string;
-    space: string;
-    /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
-    errors: Record<string, {
-        kind: string;
-        message: string;
-    }>;
-    errorCount: number;
-    inSpace: true;
-}
-export interface FileNotInSpaceResult {
-    file: string;
-    inSpace: false;
-    message: string;
-}
-export type ValidateFileOutput = FileValidationResult | FileNotInSpaceResult;
+export { validateFile } from '../validate';
 /**
- * Validate a single file within its space.
- *
- * Reads the full space (required for graph correctness) but filters all reported
- * errors to only those attributable to the target file. Exits 0 if the file is
- * not in any configured space (not an error — hooks call this on all file writes).
+ * CLI command: validate a file and print results to stdout.
+ * Loads config automatically from the environment, outputs human-readable or JSON,
+ * and returns an exit code (0 = valid, 1 = errors found).
  */
-export declare function validateFile(filePath: string, options?: {
+export declare function validateFileCommand(filePath: string, options?: {
     json?: boolean;
 }): Promise<number>;

package/dist/commands/validate-file.js

@@ -1,121 +1,27 @@
-import { isAbsolute, relative, resolve } from 'node:path';
-import { getSpaceConfigDir, loadConfig, resolveSchema } from '../config';
-import { readSpace } from '../read/read-space';
-import { loadSchema } from '../schema/schema';
-import { validateGraph } from '../schema/validate-graph';
-import { validateRules } from '../schema/validate-rules';
-import { formatErrors } from './validate';
-/** Find which space a file belongs to by checking directory containment. */
-function resolveFileSpace(filePath, config) {
-    const absFile = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
-    for (const space of config.spaces) {
-        const absSpace = isAbsolute(space.path) ? space.path : resolve(process.cwd(), space.path);
-        // Trailing slash prevents prefix-match false positives (e.g. /foo matching /foobar/)
-        const spaceDir = absSpace.endsWith('/') ? absSpace : `${absSpace}/`;
-        if (absFile.startsWith(spaceDir) || absFile === absSpace) {
-            return { space, label: relative(absSpace, absFile) };
-        }
-    }
-    return null;
-}
-function buildContextForSpace(space, config) {
-    const resolvedSchemaPath = resolveSchema(config, space);
-    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
-    const configDir = getSpaceConfigDir(space.name);
-    return { space, config, resolvedSchemaPath, schema, schemaRefRegistry, schemaValidator, configDir };
-}
+import { loadConfig } from '../config';
+import { validateFile } from '../validate';
+export { validateFile } from '../validate';
 /**
- * Validate a single file within its space.
- *
- * Reads the full space (required for graph correctness) but filters all reported
- * errors to only those attributable to the target file. Exits 0 if the file is
- * not in any configured space (not an error — hooks call this on all file writes).
+ * CLI command: validate a file and print results to stdout.
+ * Loads config automatically from the environment, outputs human-readable or JSON,
+ * and returns an exit code (0 = valid, 1 = errors found).
  */
-export async function validateFile(filePath, options = {}) {
+export async function validateFileCommand(filePath, options = {}) {
     const config = loadConfig();
-    const resolved = resolveFileSpace(filePath, config);
-    if (!resolved) {
-        const result = {
-            file: filePath,
-            inSpace: false,
-            message: 'File does not belong to any configured space.',
-        };
+    const result = await validateFile(filePath, config);
+    if (!result.inSpace) {
         if (options.json) {
             console.log(JSON.stringify(result, null, 2));
         }
         return 0;
     }
-    const { space, label } = resolved;
-    const context = buildContextForSpace(space, config);
-    const { schema, schemaRefRegistry, schemaValidator } = context;
-    const metadata = schema.metadata;
-    const readResult = await readSpace(context);
-    const { nodes } = readResult;
-    const errors = {};
-    // Schema validation errors for this node
-    for (const node of nodes) {
-        if (node.label !== label)
-            continue;
-        const valid = schemaValidator(node.schemaData);
-        if (!valid) {
-            const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
-            for (const { message, dedupeKey } of formatted) {
-                errors[`schema:${dedupeKey}`] = { kind: 'schema', message };
-            }
-        }
-    }
-    // Duplicate key errors — include if this file is one of the duplicates
-    const titleToFiles = new Map();
-    for (const node of nodes) {
-        if (!titleToFiles.has(node.title))
-            titleToFiles.set(node.title, []);
-        titleToFiles.get(node.title).push(node.label);
-    }
-    for (const [title, files] of titleToFiles) {
-        if (files.length > 1 && files.includes(label)) {
-            const others = files.filter((f) => f !== label);
-            errors[`duplicate:${title}`] = {
-                kind: 'duplicate',
-                message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
-            };
-        }
-    }
-    // Broken links and hierarchy violations from this file
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
-    for (const { file, parent, error } of hierarchyValidation.refErrors) {
-        if (file === label) {
-            errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
-        }
-    }
-    for (const v of hierarchyValidation.violations) {
-        if (v.file === label) {
-            errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
-        }
-    }
-    // Rule violations for this node
-    if (metadata.rules) {
-        const ruleViolations = await validateRules(nodes, metadata.rules);
-        for (const v of ruleViolations) {
-            if (v.file === label) {
-                errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` };
-            }
-        }
-    }
-    const result = {
-        file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
-        label,
-        space: space.name,
-        errors,
-        errorCount: Object.keys(errors).length,
-        inSpace: true,
-    };
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
     }
     else {
         printHumanReadable(result);
     }
-    return Object.keys(errors).length > 0 ? 1 : 0;
+    return Object.keys(result.errors).length > 0 ? 1 : 0;
 }
 function printHumanReadable(result) {
     const reset = '\x1b[0m';

package/dist/commands/validate.d.ts

@@ -1,15 +1,4 @@
-import type { ErrorObject } from 'ajv';
-import { extractEntityInfo } from '../schema/schema';
-import type { SchemaWithMetadata, SpaceContext } from '../types';
-export interface FormattedError {
-    message: string;
-    dedupeKey: string;
-}
-/**
- * Format AJV errors for better readability.
- * Groups related errors and extracts helpful context like allowed values.
- */
-export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
+import type { SpaceContext } from '../types';
 export declare function validate(context: SpaceContext, options?: {
     json?: boolean;
 }): Promise<number>;

package/dist/commands/validate.js

@@ -1,154 +1,11 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
-import { readSpace } from '../read/read-space';
-import { bundledSchemasDir, extractEntityInfo } from '../schema/schema';
-import { validateGraph } from '../schema/validate-graph';
-import { validateRules } from '../schema/validate-rules';
-import { buildSpaceGraph } from '../space-graph';
-/**
- * Format AJV errors for better readability.
- * Groups related errors and extracts helpful context like allowed values.
- */
-export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
-    const formatted = [];
-    const seen = new Set();
-    // Group errors by instancePath
-    const byPath = new Map();
-    for (const err of errors) {
-        const path = err.instancePath || 'root';
-        if (!byPath.has(path)) {
-            byPath.set(path, []);
-        }
-        byPath.get(path).push(err);
-    }
-    for (const [path, pathErrors] of byPath) {
-        // Check if this is a oneOf failure at root - extract valid types from schema
-        const isRootOneOf = path === 'root' || path === '/type';
-        let hasOneOfContext = false;
-        if (isRootOneOf && pathErrors.length > 1) {
-            hasOneOfContext = Array.isArray(schema.oneOf);
-            if (hasOneOfContext) {
-                const entities = extractEntityInfo(schema, schemaRefRegistry);
-                const validTypes = entities.map((e) => e.type).sort();
-                if (validTypes.length > 0) {
-                    const actualValue = nodeData.type;
-                    // Only show type error if the actual type is NOT in the valid types list
-                    if (actualValue !== undefined && !validTypes.includes(String(actualValue))) {
-                        const message = `Invalid type "${actualValue}". Valid types are: ${validTypes.join(', ')}`;
-                        const key = `type:${validTypes.join(',')}`;
-                        if (!seen.has(key)) {
-                            seen.add(key);
-                            formatted.push({ message, dedupeKey: key });
-                        }
-                    }
-                }
-            }
-        }
-        // Handle individual errors
-        for (const err of pathErrors) {
-            // Skip individual type const/enum errors when in oneOf context (we handle it above)
-            if (hasOneOfContext &&
-                (err.keyword === 'const' || err.keyword === 'enum') &&
-                (err.instancePath === '' || err.instancePath === '/type')) {
-                continue;
-            }
-            const parts = err.instancePath.split('/').filter(Boolean);
-            const fieldName = parts.length > 0 ? parts[parts.length - 1] : 'root';
-            let message = err.message;
-            let key = `${err.instancePath}:${err.keyword}`;
-            // Enhance const errors
-            if (err.keyword === 'const' && err.params?.allowedValue !== undefined) {
-                const actual = err.data !== undefined ? `"${err.data}"` : 'missing value';
-                const expected = `"${err.params.allowedValue}"`;
-                message = `${fieldName}: expected ${expected}, got ${actual}`;
-                key = `${err.instancePath}:const:${err.params.allowedValue}`;
-            }
-            // Enhance enum errors
-            else if (err.keyword === 'enum' && err.params?.allowedValues && Array.isArray(err.params.allowedValues)) {
-                let actual = err.data !== undefined ? `"${err.data}"` : null;
-                // If err.data is undefined, try to get the value from nodeData using the field name
-                if (actual === null && fieldName !== 'root') {
-                    const actualValue = nodeData[fieldName];
-                    if (actualValue !== undefined) {
-                        actual = `"${actualValue}"`;
-                    }
-                }
-                if (actual === null) {
-                    actual = 'missing value';
-                }
-                const allowed = err.params.allowedValues.map((v) => `"${v}"`).join(', ');
-                message = `${fieldName}: ${actual} is not valid. Allowed: ${allowed}`;
-                key = `${err.instancePath}:enum:${err.params.allowedValues.join(',')}`;
-            }
-            // Generic message with path
-            else {
-                message = `${fieldName}: ${err.message}`;
-            }
-            if (!seen.has(key)) {
-                seen.add(key);
-                formatted.push({ message, dedupeKey: key });
-            }
-        }
-    }
-    return formatted;
-}
+import { bundledSchemasDir } from '../schema/schema';
+import { formatErrors, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
-    const { schema, schemaRefRegistry, schemaValidator } = context;
-    const metadata = schema.metadata;
-    const readResult = await readSpace(context);
-    const { nodes, parseIssues } = readResult;
-    const result = {
-        validCount: 0,
-        nodeErrorCount: 0,
-        nodeErrors: [],
-        refErrors: [],
-        duplicateErrors: [],
-        ruleViolations: [],
-        hierarchyViolations: [],
-        orphans: [],
-        parseIssues,
-    };
-    for (const node of nodes) {
-        const valid = schemaValidator(node.schemaData);
-        if (valid) {
-            result.validCount++;
-        }
-        else {
-            result.nodeErrorCount++;
-            result.nodeErrors.push({
-                file: node.label,
-                errors: schemaValidator.errors || [],
-                nodeData: node.schemaData,
-            });
-        }
-    }
-    // Detect duplicate node keys (titles)
-    const titleToFiles = new Map();
-    for (const node of nodes) {
-        const title = node.title;
-        if (!titleToFiles.has(title)) {
-            titleToFiles.set(title, []);
-        }
-        titleToFiles.get(title).push(node.label);
-    }
-    for (const [title, files] of titleToFiles) {
-        if (files.length > 1) {
-            result.duplicateErrors.push({ title, files });
-        }
-    }
-    // Validate all hierarchy constraints (field references and structure)
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
-    result.refErrors.push(...hierarchyValidation.refErrors);
-    result.hierarchyViolations = [...hierarchyValidation.violations];
-    // Calculate orphan count (informational, not a validation error)
-    if (metadata.hierarchy) {
-        result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans];
-    }
-    // Load and execute rules validation if schema defines rules
-    if (metadata.rules) {
-        result.ruleViolations = await validateRules(nodes, metadata.rules);
-    }
+    const { schema, schemaRefRegistry } = context;
+    const result = await validateSpace(context);
     // JSON output mode
     if (options.json) {
         const errorsByFile = {};
@@ -193,7 +50,7 @@ export async function validate(context, options = {}) {
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
-    // Report
+    // Human-readable output
     const reset = '\x1b[0m';
     const green = '\x1b[32m';
     const red = '\x1b[31m';
@@ -209,7 +66,6 @@ export async function validate(context, options = {}) {
             color = colorFor(count, isWarning);
         }
         else {
-            // For non-error items (like "Valid"), green if count > 0, red if 0
             color = count > 0 ? green : red;
         }
         const countStr = String(count).padStart(3);
@@ -266,15 +122,12 @@ export async function validate(context, options = {}) {
     }
     if (result.ruleViolations.length > 0) {
         console.log(`\nRule violations:`);
-        // Group by category
         const byCategory = new Map();
         for (const v of result.ruleViolations) {
-            if (!byCategory.has(v.category)) {
+            if (!byCategory.has(v.category))
                 byCategory.set(v.category, []);
-            }
             byCategory.get(v.category).push(v);
         }
-        // Report each category
         for (const [category, violations] of byCategory) {
             console.log(`  ${category.toUpperCase()} (${violations.length}):`);
             for (const v of violations) {
@@ -289,7 +142,6 @@ export async function validate(context, options = {}) {
         }
     }
     console.log(`\n`);
-    // Return exit code (0 for success, 1 for validation failures)
     if (result.nodeErrorCount > 0 ||
         result.refErrors.length > 0 ||
         result.duplicateErrors.length > 0 ||
@@ -314,7 +166,6 @@ export async function watchValidate(context) {
     console.log(`   Schema dirs: ${schemaDirs.join(', ')}`);
     console.log(`   Space:  ${spacePath}`);
     console.log(`   Press Ctrl+C to stop\n`);
-    // Save cursor position after header (for clearing later)
     process.stdout.write('\x1b[s');
     let exitCode = 0;
     const innerValidate = async () => {
@@ -336,7 +187,6 @@ export async function watchValidate(context) {
         },
     });
     const handleFileChange = async (filePath, action) => {
-        // Restore cursor to header position and clear everything below
         process.stdout.write('\x1b[u\x1b[0J');
         console.log(`🔄 ${filePath} ${action}, re-validating...\n`);
         await innerValidate();
@@ -347,7 +197,6 @@ export async function watchValidate(context) {
     watcher.on('error', (error) => {
         console.error(`Watcher error: ${error}`);
     });
-    // Keep process alive
     return new Promise((_, reject) => {
         process.on('SIGINT', () => {
             console.log('\n\n👋 Stopping watch mode...');

package/dist/config.js

@@ -2,7 +2,7 @@ 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 { JSON5 } from 'bun';
+import JSON5 from 'json5';
 import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
 import { normalizePluginName } from './plugins/util';
 import { bundledSchemasDir } from './schema/schema';

package/dist/index.js

@@ -11,7 +11,7 @@ import { show } from './commands/show';
 import { listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
 import { validate, watchValidate } from './commands/validate';
-import { validateFile } from './commands/validate-file';
+import { validateFileCommand } from './commands/validate-file';
 import { getSpaceConfigDir, loadConfig, resolveSchema, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
 import { miroSync } from './integrations/miro/sync';
@@ -53,7 +53,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 validateFile(filePath, { json: options.json });
+    const exitCode = await validateFileCommand(filePath, { json: options.json });
     process.exit(exitCode);
 });
 program

package/dist/plugins/markdown/index.d.ts

@@ -1,48 +1,58 @@
+import type { FromSchema } from 'json-schema-to-ts';
 import type { StructuredContextPlugin } from '../util';
-export type TypeInferenceConfig = {
-    mode?: 'folder-name' | 'off';
-    folderMap?: Record<string, string>;
-};
-export type MarkdownPluginConfig = {
-    templateDir?: string;
-    fieldMap?: Record<string, string>;
-    templatePrefix?: string;
-    typeInference?: TypeInferenceConfig;
+declare const TYPE_INFERENCE_CONFIG_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly mode: {
+            readonly type: "string";
+            readonly enum: readonly ["folder-name", "off"];
+        };
+        readonly folderMap: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly additionalProperties: false;
 };
 export declare const MARKDOWN_CONFIG_SCHEMA: {
-    type: string;
-    properties: {
-        templateDir: {
-            type: string;
-            format: string;
+    readonly type: "object";
+    readonly properties: {
+        readonly templateDir: {
+            readonly type: "string";
+            readonly format: "path";
         };
-        fieldMap: {
-            type: string;
-            additionalProperties: {
-                type: string;
+        readonly fieldMap: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "string";
             };
         };
-        templatePrefix: {
-            type: string;
+        readonly templatePrefix: {
+            readonly type: "string";
         };
-        typeInference: {
-            type: string;
-            properties: {
-                mode: {
-                    type: string;
-                    enum: string[];
+        readonly typeInference: {
+            readonly type: "object";
+            readonly properties: {
+                readonly mode: {
+                    readonly type: "string";
+                    readonly enum: readonly ["folder-name", "off"];
                 };
-                folderMap: {
-                    type: string;
-                    additionalProperties: {
-                        type: string;
+                readonly folderMap: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "string";
                     };
                 };
             };
-            additionalProperties: boolean;
+            readonly additionalProperties: false;
         };
     };
-    additionalProperties: boolean;
+    readonly additionalProperties: false;
 };
+export type MarkdownPluginConfig = FromSchema<typeof MARKDOWN_CONFIG_SCHEMA>;
+export type TypeInferenceConfig = FromSchema<typeof TYPE_INFERENCE_CONFIG_SCHEMA>;
 export declare function getMarkdownConfig(plugins?: Record<string, Record<string, unknown>>): MarkdownPluginConfig;
 export declare const markdownPlugin: StructuredContextPlugin;
+export {};

package/dist/plugins/markdown/index.js

@@ -4,20 +4,21 @@ import { readSpaceDirectory, readSpaceOnAPage } from './read-space';
 import { renderBullets } from './render-bullets';
 import { renderMermaid } from './render-mermaid';
 import { templateSync } from './template-sync';
+const TYPE_INFERENCE_CONFIG_SCHEMA = {
+    type: 'object',
+    properties: {
+        mode: { type: 'string', enum: ['folder-name', 'off'] },
+        folderMap: { type: 'object', additionalProperties: { type: 'string' } },
+    },
+    additionalProperties: false,
+};
 export const MARKDOWN_CONFIG_SCHEMA = {
     type: 'object',
     properties: {
         templateDir: { type: 'string', format: 'path' }, // format is hint to config loader to resolve relative directories
         fieldMap: { type: 'object', additionalProperties: { type: 'string' } },
         templatePrefix: { type: 'string' },
-        typeInference: {
-            type: 'object',
-            properties: {
-                mode: { type: 'string', enum: ['folder-name', 'off'] },
-                folderMap: { type: 'object', additionalProperties: { type: 'string' } },
-            },
-            additionalProperties: false,
-        },
+        typeInference: TYPE_INFERENCE_CONFIG_SCHEMA,
     },
     additionalProperties: false,
 };

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -1,4 +1,4 @@
-import type { BaseNode, Relationship, SchemaMetadata } from '../../plugin-api';
+import type { BaseNode, Relationship, SchemaMetadata } from '../../api';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export declare const ON_A_PAGE_TYPES: string[];
 type StackEntry = {

package/dist/plugins/markdown/read-space.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { Glob } from 'bun';
+import fg from 'fast-glob';
 import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
@@ -42,7 +42,7 @@ export async function readSpaceDirectory(context, options) {
     const absoluteTemplateDir = templateDir ? resolve(templateDir) : undefined;
     const typeInferenceCfg = mdCfg.typeInference;
     const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
-    const files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
+    const files = await fg('**/*.md', { cwd: directory, followSymbolicLinks: true });
     const nodes = [];
     const parseIssues = [];
     for (const file of files) {
@@ -70,7 +70,7 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            parseIssues.push({ file, severity: 'warning', type: 'empty' });
+            parseIssues.push({ file, severity: 'warning', type: 'no-type', message: 'No front-matter or type specified' });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));

package/dist/plugins/markdown/template-sync.d.ts

@@ -1,5 +1,5 @@
 import type { AnySchemaObject } from 'ajv';
-import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../plugin-api';
+import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../api';
 import type { PluginContext, TemplateSyncOptions } from '../util';
 export interface TypeVariant {
     required: string[];

package/dist/plugins/markdown/template-sync.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Glob } from 'bun';
+import fg from 'fast-glob';
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { mergeVariantProperties, resolveRef } from '../../schema/schema-refs';
@@ -190,7 +190,7 @@ export async function templateSync(context, options) {
     const { schema, schemaRefRegistry } = context;
     const typeVariants = getTypeVariants(schema, schemaRefRegistry);
     const matchedTypes = new Set();
-    const files = await Array.fromAsync(new Glob('*.md').scan({ cwd: templateDir, absolute: true }));
+    const files = await fg('*.md', { cwd: templateDir, absolute: true });
     const dryRun = options.dryRun ?? false;
     let filesModified = 0;
     let filesCreated = 0;

package/dist/schema/schema.js

@@ -3,7 +3,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import Ajv, {} from 'ajv';
-import { JSON5 } from 'bun';
+import JSON5 from 'json5';
 import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
 import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
 const packageDir = dirname(fileURLToPath(import.meta.url));

package/dist/types.d.ts

@@ -91,10 +91,10 @@ export type ParseIssue = {
     file: string;
     /** error: prevented the file from producing nodes; warning: file was silently excluded. */
     severity: 'error' | 'warning';
-    /** empty: no content; no-type: no type field;
+    /** no-type: no type field;
      *  parse: parse failure (syntax issue or unexpected content);
      *  plugins may choose to provide additional types. */
-    type: 'empty' | 'no-type' | 'parse' | string;
+    type: 'no-type' | 'parse' | string;
     /** Human-readable detail. */
     message?: string;
 };
@@ -155,3 +155,21 @@ export type SpaceContext = {
     /** Directory of the config file that defines this space. Used for resolving relative paths in plugin configs. */
     configDir: string;
 };
+export interface FileValidationResult {
+    file: string;
+    label: string;
+    space: string;
+    /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
+    errors: Record<string, {
+        kind: string;
+        message: string;
+    }>;
+    errorCount: number;
+    inSpace: true;
+}
+export interface FileNotInSpaceResult {
+    file: string;
+    inSpace: false;
+    message: string;
+}
+export type ValidateFileOutput = FileValidationResult | FileNotInSpaceResult;

package/dist/validate.d.ts

@@ -0,0 +1,50 @@
+import type { ErrorObject } from 'ajv';
+import type { Config } from './config';
+import { extractEntityInfo } from './schema/schema';
+import type { GraphViolation, ParseIssue, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+export interface FormattedError {
+    message: string;
+    dedupeKey: string;
+}
+export interface ValidationResult {
+    validCount: number;
+    nodeErrorCount: number;
+    nodeErrors: Array<{
+        file: string;
+        errors: ErrorObject[];
+        nodeData: Record<string, unknown>;
+    }>;
+    refErrors: Array<{
+        file: string;
+        parent: string;
+        error: string;
+    }>;
+    duplicateErrors: Array<{
+        title: string;
+        files: string[];
+    }>;
+    ruleViolations: RuleViolation[];
+    hierarchyViolations: GraphViolation[];
+    orphans: SpaceNode[];
+    parseIssues: ParseIssue[];
+}
+/**
+ * Format AJV errors for better readability.
+ * Groups related errors and extracts helpful context like allowed values.
+ */
+export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
+/**
+ * Run full validation on a space and return a structured result.
+ * Does not output to console or call process.exit.
+ */
+export declare function validateSpace(context: SpaceContext): Promise<ValidationResult>;
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file.
+ *
+ * Returns a result object — does not output to console or call process.exit.
+ * If the file is not in any configured space, returns a result with `inSpace: false`.
+ */
+export declare function validateFile(filePath: string, config: Config): Promise<ValidateFileOutput>;

package/dist/validate.js

@@ -0,0 +1,291 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { getSpaceConfigDir, resolveSchema } from './config';
+import { readSpace } from './read/read-space';
+import { extractEntityInfo, loadSchema } from './schema/schema';
+import { validateGraph } from './schema/validate-graph';
+import { validateRules } from './schema/validate-rules';
+import { buildSpaceGraph } from './space-graph';
+/**
+ * Format AJV errors for better readability.
+ * Groups related errors and extracts helpful context like allowed values.
+ */
+export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
+    const formatted = [];
+    const seen = new Set();
+    // Group errors by instancePath
+    const byPath = new Map();
+    for (const err of errors) {
+        const path = err.instancePath || 'root';
+        if (!byPath.has(path)) {
+            byPath.set(path, []);
+        }
+        byPath.get(path).push(err);
+    }
+    for (const [path, pathErrors] of byPath) {
+        // Check if this is a oneOf failure at root - extract valid types from schema
+        const isRootOneOf = path === 'root' || path === '/type';
+        let hasOneOfContext = false;
+        if (isRootOneOf && pathErrors.length > 1) {
+            hasOneOfContext = Array.isArray(schema.oneOf);
+            if (hasOneOfContext) {
+                const entities = extractEntityInfo(schema, schemaRefRegistry);
+                const validTypes = entities.map((e) => e.type).sort();
+                if (validTypes.length > 0) {
+                    const actualValue = nodeData.type;
+                    // Only show type error if the actual type is NOT in the valid types list
+                    if (actualValue !== undefined && !validTypes.includes(String(actualValue))) {
+                        const message = `Invalid type "${actualValue}". Valid types are: ${validTypes.join(', ')}`;
+                        const key = `type:${validTypes.join(',')}`;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            formatted.push({ message, dedupeKey: key });
+                        }
+                    }
+                }
+            }
+        }
+        // Handle individual errors
+        for (const err of pathErrors) {
+            // Skip individual type const/enum errors when in oneOf context (we handle it above)
+            if (hasOneOfContext &&
+                (err.keyword === 'const' || err.keyword === 'enum') &&
+                (err.instancePath === '' || err.instancePath === '/type')) {
+                continue;
+            }
+            const parts = err.instancePath.split('/').filter(Boolean);
+            const fieldName = parts.length > 0 ? parts[parts.length - 1] : 'root';
+            let message = err.message;
+            let key = `${err.instancePath}:${err.keyword}`;
+            // Enhance const errors
+            if (err.keyword === 'const' && err.params?.allowedValue !== undefined) {
+                const actual = err.data !== undefined ? `"${err.data}"` : 'missing value';
+                const expected = `"${err.params.allowedValue}"`;
+                message = `${fieldName}: expected ${expected}, got ${actual}`;
+                key = `${err.instancePath}:const:${err.params.allowedValue}`;
+            }
+            // Enhance enum errors
+            else if (err.keyword === 'enum' && err.params?.allowedValues && Array.isArray(err.params.allowedValues)) {
+                let actual = err.data !== undefined ? `"${err.data}"` : null;
+                // If err.data is undefined, try to get the value from nodeData using the field name
+                if (actual === null && fieldName !== 'root') {
+                    const actualValue = nodeData[fieldName];
+                    if (actualValue !== undefined) {
+                        actual = `"${actualValue}"`;
+                    }
+                }
+                if (actual === null) {
+                    actual = 'missing value';
+                }
+                const allowed = err.params.allowedValues.map((v) => `"${v}"`).join(', ');
+                message = `${fieldName}: ${actual} is not valid. Allowed: ${allowed}`;
+                key = `${err.instancePath}:enum:${err.params.allowedValues.join(',')}`;
+            }
+            // Generic message with path
+            else {
+                message = `${fieldName}: ${err.message}`;
+            }
+            if (!seen.has(key)) {
+                seen.add(key);
+                formatted.push({ message, dedupeKey: key });
+            }
+        }
+    }
+    return formatted;
+}
+/**
+ * Run full validation on a space and return a structured result.
+ * Does not output to console or call process.exit.
+ */
+export async function validateSpace(context) {
+    const { schema, schemaRefRegistry, schemaValidator } = context;
+    const metadata = schema.metadata;
+    const readResult = await readSpace(context);
+    const { nodes, parseIssues } = readResult;
+    // Pre-extract valid types for early type validation
+    const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
+    const result = {
+        validCount: 0,
+        nodeErrorCount: 0,
+        nodeErrors: [],
+        refErrors: [],
+        duplicateErrors: [],
+        ruleViolations: [],
+        hierarchyViolations: [],
+        orphans: [],
+        parseIssues,
+    };
+    for (const node of nodes) {
+        // Early type validation - check before full AJV validation to prevent cascading errors
+        const nodeType = node.schemaData.type;
+        if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
+            result.nodeErrorCount++;
+            result.nodeErrors.push({
+                file: node.label,
+                errors: [
+                    {
+                        instancePath: '/type',
+                        keyword: 'enum',
+                        message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
+                        params: { allowedValues: validTypes },
+                        schemaPath: '#/oneOf',
+                        data: nodeType,
+                    },
+                ],
+                nodeData: node.schemaData,
+            });
+            continue;
+        }
+        const valid = schemaValidator(node.schemaData);
+        if (valid) {
+            result.validCount++;
+        }
+        else {
+            result.nodeErrorCount++;
+            result.nodeErrors.push({
+                file: node.label,
+                errors: schemaValidator.errors || [],
+                nodeData: node.schemaData,
+            });
+        }
+    }
+    // Detect duplicate node keys (titles)
+    const titleToFiles = new Map();
+    for (const node of nodes) {
+        const title = node.title;
+        if (!titleToFiles.has(title)) {
+            titleToFiles.set(title, []);
+        }
+        titleToFiles.get(title).push(node.label);
+    }
+    for (const [title, files] of titleToFiles) {
+        if (files.length > 1) {
+            result.duplicateErrors.push({ title, files });
+        }
+    }
+    // Validate all hierarchy constraints (field references and structure)
+    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
+    result.refErrors.push(...hierarchyValidation.refErrors);
+    result.hierarchyViolations = [...hierarchyValidation.violations];
+    // Calculate orphan count (informational, not a validation error)
+    if (metadata.hierarchy) {
+        result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans];
+    }
+    // Load and execute rules validation if schema defines rules
+    if (metadata.rules) {
+        result.ruleViolations = await validateRules(nodes, metadata.rules);
+    }
+    return result;
+}
+/** Find which space a file belongs to by checking directory containment. */
+function resolveFileSpace(filePath, config) {
+    const absFile = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+    for (const space of config.spaces) {
+        const absSpace = isAbsolute(space.path) ? space.path : resolve(process.cwd(), space.path);
+        // Trailing slash prevents prefix-match false positives (e.g. /foo matching /foobar/)
+        const spaceDir = absSpace.endsWith('/') ? absSpace : `${absSpace}/`;
+        if (absFile.startsWith(spaceDir) || absFile === absSpace) {
+            return { space, label: relative(absSpace, absFile) };
+        }
+    }
+    return null;
+}
+function buildContextForSpace(space, config) {
+    const resolvedSchemaPath = resolveSchema(config, space);
+    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
+    const configDir = getSpaceConfigDir(space.name);
+    return { space, config, resolvedSchemaPath, schema, schemaRefRegistry, schemaValidator, configDir };
+}
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file.
+ *
+ * Returns a result object — does not output to console or call process.exit.
+ * If the file is not in any configured space, returns a result with `inSpace: false`.
+ */
+export async function validateFile(filePath, config) {
+    const resolved = resolveFileSpace(filePath, config);
+    if (!resolved) {
+        return {
+            file: filePath,
+            inSpace: false,
+            message: 'File does not belong to any configured space.',
+        };
+    }
+    const { space, label } = resolved;
+    const context = buildContextForSpace(space, config);
+    const { schema, schemaRefRegistry, schemaValidator } = context;
+    const metadata = schema.metadata;
+    const readResult = await readSpace(context);
+    const { nodes } = readResult;
+    // Pre-extract valid types for early type validation
+    const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
+    const errors = {};
+    // Schema validation errors for this node
+    for (const node of nodes) {
+        if (node.label !== label)
+            continue;
+        // Early type validation - check before full AJV validation to prevent cascading errors
+        const nodeType = node.schemaData.type;
+        if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
+            errors[`schema:type:${validTypes.join(',')}`] = {
+                kind: 'schema',
+                message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
+            };
+            continue;
+        }
+        const valid = schemaValidator(node.schemaData);
+        if (!valid) {
+            const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
+            for (const { message, dedupeKey } of formatted) {
+                errors[`schema:${dedupeKey}`] = { kind: 'schema', message };
+            }
+        }
+    }
+    // Duplicate key errors — include if this file is one of the duplicates
+    const titleToFiles = new Map();
+    for (const node of nodes) {
+        if (!titleToFiles.has(node.title))
+            titleToFiles.set(node.title, []);
+        titleToFiles.get(node.title).push(node.label);
+    }
+    for (const [title, files] of titleToFiles) {
+        if (files.length > 1 && files.includes(label)) {
+            const others = files.filter((f) => f !== label);
+            errors[`duplicate:${title}`] = {
+                kind: 'duplicate',
+                message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
+            };
+        }
+    }
+    // Broken links and hierarchy violations from this file
+    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
+    for (const { file, parent, error } of hierarchyValidation.refErrors) {
+        if (file === label) {
+            errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
+        }
+    }
+    for (const v of hierarchyValidation.violations) {
+        if (v.file === label) {
+            errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
+        }
+    }
+    // Rule violations for this node
+    if (metadata.rules) {
+        const ruleViolations = await validateRules(nodes, metadata.rules);
+        for (const v of ruleViolations) {
+            if (v.file === label) {
+                errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` };
+            }
+        }
+    }
+    return {
+        file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
+        label,
+        space: space.name,
+        errors,
+        errorCount: Object.keys(errors).length,
+        inSpace: true,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "structured-context",
-  "version": "0.9.3",
-  "description": "Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks",
+  "version": "0.10.0",
+  "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
   "license": "MIT",
@@ -18,9 +18,13 @@
   ],
   "exports": {
     ".": "./dist/index.js",
-    "./plugin-api": {
-      "types": "./dist/plugin-api.d.ts",
-      "default": "./dist/plugin-api.js"
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
     }
   },
   "scripts": {
@@ -57,8 +61,10 @@
     "ajv": "^8.18.0",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
+    "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.1",
+    "json5": "^2.2.3",
     "jsonata": "^2.1.0",
     "mdast-util-to-string": "^4.0.0",
     "remark-gfm": "^4.0.1",

package/dist/plugin-api.d.ts

@@ -1,12 +0,0 @@
-/**
- * Public API for external structured-context plugins.
- *
- * Import from this module to get the types needed to implement a StructuredContextPlugin:
- *
- *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/plugin-api';
- */
-export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
-export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
-export type { SharedEmbeddingFields } from './schema/metadata-contract';
-export type { SpaceGraph } from './space-graph';
-export type { BaseNode, EdgeDefinition, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, } from './types';

package/dist/plugin-api.js

@@ -1,7 +0,0 @@
-/**
- * Public API for external structured-context plugins.
- *
- * Import from this module to get the types needed to implement a StructuredContextPlugin:
- *
- *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/plugin-api';
- */