structured-context 0.9.3 → 0.11.0

package/README.md

@@ -335,13 +335,26 @@ sctx schemas show strategy_general --mermaid-erd
 sctx miro-sync <space> [--new-frame <title>] [--dry-run] [--verbose]
 ```
 
-Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `miroBoardId` set in the space's config entry.
+Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `boardId` set in the `miro` plugin config for the space.
 
-- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `miroFrameId` back to the config file
+- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `frameId` back to the miro plugin config
 - `--dry-run` — show what would change without touching Miro
 - `--verbose` / `-v` — detailed per-card and per-connector output
 
-On subsequent runs, the cached `miroFrameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
+Configure the miro plugin in the space's config entry:
+
+```json
+{
+  "plugins": {
+    "miro": {
+      "boardId": "your-board-id",
+      "frameId": "your-frame-id"
+    }
+  }
+}
+```
+
+On subsequent runs, the cached `frameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
 
 Sync is one-way (OST → Miro) and scoped to a single frame. Only cards and connectors created by this tool within that frame are managed — everything else on the board is left untouched. Card content and connectors are overwritten or recreated to match the markdown source; any edits made directly in Miro to managed cards will be lost on the next sync. Existing card positions are not changed.
 
@@ -357,6 +370,12 @@ Keeps Obsidian template files in sync with schema examples:
 - `templatePrefix` in `plugins.markdown` config (default blank) sets a naming convention for templates (`{templatePrefix}{type}.md`). This will be used to check existing filenames, and create new templates with `--create-missing`.
 - `--dry-run` previews changes without writing files
 
+## Programmatic API
+
+The package exposes a library entry point at `structured-context/api` for embedding the tooling
+in other applications. See
+[docs/api.md](docs/api.md) for the full reference and usage examples.
+
 ## Development
 
 ```bash

package/dist/api.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Public API for structured-context.
+ *
+ * Import from this module to use structured-context as a library:
+ *
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
+ */
+export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
+export type { Config, SpaceConfig } from './config';
+export { loadConfig, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export { readSpace } from './read/read-space';
+export type { SharedEmbeddingFields } from './schema/metadata-contract';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export type { SpaceGraph } from './space-graph';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export type { ValidationResult } from './validate';
+export { validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -0,0 +1,26 @@
+/**
+ * Public API for structured-context.
+ *
+ * Import from this module to use structured-context as a library:
+ *
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
+ */
+export { loadConfig, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export { readSpace } from './read/read-space';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { validateFile, validateSpace } from './validate';

package/dist/commands/diagram.js

@@ -1,7 +1,7 @@
 import { writeFileSync } from 'node:fs';
 import { executeRender } from '../render/render';
 export async function diagram(context, options) {
-    const result = await executeRender('markdown.mermaid', context, { filter: options.filter });
+    const result = await executeRender('mermaid.graph', context, { filter: options.filter });
     if (options.output) {
         writeFileSync(options.output, result);
         console.log(`Mermaid diagram written to ${options.output}`);

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/miro-sync.d.ts

@@ -0,0 +1,3 @@
+import type { SyncOptions } from '../plugins/miro/sync';
+import type { SpaceContext } from '../types';
+export declare function miroSyncCommand(context: SpaceContext, options: SyncOptions): Promise<void>;

package/dist/commands/miro-sync.js

@@ -0,0 +1,8 @@
+import { executeRender } from '../render/render';
+export async function miroSyncCommand(context, options) {
+    const summary = await executeRender('sctx-miro:board', context, {
+        filter: undefined,
+        data: options,
+    });
+    console.log(summary);
+}

package/dist/commands/schemas.js

@@ -2,7 +2,7 @@ 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 { mergeVariantProperties } from '../schema/schema-refs';
+import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
 function isBundledPath(schemaPath) {
     return dirname(schemaPath) === bundledSchemasDir;
 }
@@ -21,6 +21,7 @@ function extractRefs(obj, refs) {
 function extractEntities(oneOf, schemaRefRegistry, schema) {
     return oneOf.map((entry) => {
         const entryObj = entry;
+        const resolvedObj = resolveRef(entryObj, schema, schemaRefRegistry) ?? entryObj;
         const { properties, required } = mergeVariantProperties(entryObj, schema, schemaRefRegistry);
         const typeDef = properties.type;
         let types = [];
@@ -30,7 +31,7 @@ function extractEntities(oneOf, schemaRefRegistry, schema) {
             types = typeDef.enum.map(String);
         return {
             types,
-            description: typeof entryObj.description === 'string' ? entryObj.description : undefined,
+            description: typeof resolvedObj.description === 'string' ? resolvedObj.description : undefined,
             properties: Object.keys(properties).filter((k) => k !== 'type'),
             required: required.filter((r) => r !== 'type'),
         };

package/dist/commands/spaces.js

@@ -14,8 +14,6 @@ export function listSpaces() {
         console.log(`  path:    ${space.path}`);
         const schema = space.schema ?? config.schema;
         console.log(`  schema:  ${schema ? basename(schema) : '(none)'}`);
-        if (space.miroBoardId)
-            console.log(`  miro:    configured`);
         const plugins = space.plugins ?? {};
         if (Object.keys(plugins).length > 0) {
             console.log('  plugins:');

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,133 +1,51 @@
-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 result.errorCount > 0 ? 1 : 0;
 }
 function printHumanReadable(result) {
     const reset = '\x1b[0m';
     const green = '\x1b[32m';
     const red = '\x1b[31m';
-    if (result.errorCount === 0) {
+    const yellow = '\x1b[33m';
+    if (result.errorCount === 0 && result.warningCount === 0) {
         console.log(`${green}✓${reset} ${result.label} (space: ${result.space})`);
         return;
     }
-    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}`);
+    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}`);
+        }
+    }
+    else {
+        console.log(`\n${green}✓${reset} ${result.label} (space: ${result.space})`);
+    }
+    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}`);
+        }
     }
     console.log('');
 }

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 = {};
@@ -190,10 +47,11 @@ export async function validate(context, options = {}) {
             errors: errorsByFile,
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
+            unresolvedContentLinks: result.unresolvedContentLinks,
         }, 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 +67,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);
@@ -225,6 +82,7 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Rule violations', result.ruleViolations.length, 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.orphans.length > 0) {
@@ -232,6 +90,20 @@ export async function validate(context, options = {}) {
         for (const node of result.orphans)
             console.log(`   ${node.label}`);
     }
+    if (result.unresolvedContentLinks.length > 0) {
+        console.log(`\nUnresolved content links (may be outside-space or broken):`);
+        const byFile = new Map();
+        for (const { file, target } of result.unresolvedContentLinks) {
+            if (!byFile.has(file))
+                byFile.set(file, []);
+            byFile.get(file).push(target);
+        }
+        for (const [file, targets] of byFile) {
+            console.log(`   ${file}:`);
+            for (const target of targets)
+                console.log(`      ${target}`);
+        }
+    }
     if (result.parseIssues.length > 0) {
         console.log(`\nExcluded during parsing:`);
         for (const issue of result.parseIssues) {
@@ -266,15 +138,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 +158,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 +182,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 +203,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 +213,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...');