structured-context 0.9.0

package/dist/commands/validate.js

@@ -0,0 +1,349 @@
+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;
+}
+export async function validate(context, options = {}) {
+    const { schema, schemaRefRegistry, schemaValidator } = context;
+    const metadata = schema.metadata;
+    const readResult = await readSpace(context);
+    const { nodes, parseIgnored } = readResult;
+    const result = {
+        validCount: 0,
+        nodeErrorCount: 0,
+        nodeErrors: [],
+        refErrors: [],
+        duplicateErrors: [],
+        ruleViolations: [],
+        hierarchyViolations: [],
+        orphanCount: 0,
+        parseIgnored: parseIgnored || [],
+    };
+    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.orphanCount = buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans.length;
+    }
+    // Load and execute rules validation if schema defines rules
+    if (metadata.rules) {
+        result.ruleViolations = await validateRules(nodes, metadata.rules);
+    }
+    // JSON output mode
+    if (options.json) {
+        const errorsByFile = {};
+        const addError = (file, key, kind, message) => {
+            if (!errorsByFile[file])
+                errorsByFile[file] = {};
+            errorsByFile[file][key] = { kind, message };
+        };
+        for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) {
+            const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
+            for (const { message, dedupeKey } of formatted) {
+                addError(file, `schema:${dedupeKey}`, 'schema', message);
+            }
+        }
+        for (const { file, parent, error } of result.refErrors) {
+            addError(file, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
+        }
+        for (const { title, files } of result.duplicateErrors) {
+            for (const file of files) {
+                const others = files.filter((f) => f !== file);
+                addError(file, `duplicate:${title}`, 'duplicate', `Duplicate title "${title}" also exists in: ${others.join(', ')}`);
+            }
+        }
+        for (const v of result.ruleViolations) {
+            if (v.file) {
+                addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`);
+            }
+        }
+        for (const v of result.hierarchyViolations) {
+            addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
+        }
+        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0);
+        console.log(JSON.stringify({
+            space: context.space.name,
+            valid: errorCount === 0,
+            validCount: result.validCount,
+            errorCount,
+            errors: errorsByFile,
+            orphanCount: result.orphanCount,
+            parseIgnored: result.parseIgnored,
+        }, null, 2));
+        return errorCount > 0 ? 1 : 0;
+    }
+    // Report
+    const reset = '\x1b[0m';
+    const green = '\x1b[32m';
+    const red = '\x1b[31m';
+    const yellow = '\x1b[33m';
+    const colorFor = (count, isWarning) => {
+        if (count === 0)
+            return green;
+        return isWarning ? yellow : red;
+    };
+    const fmt = (label, count, isError = false, isWarning = false) => {
+        let color;
+        if (isError) {
+            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);
+        return `${label.padEnd(40)} ${color}${countStr}${reset}`;
+    };
+    console.log(`\nSpace Validation Results`);
+    console.log(`━`.repeat(45));
+    console.log('Content and structure');
+    console.log(fmt('  Valid', result.validCount));
+    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('  Hierarchy violations', result.hierarchyViolations.length, true));
+    console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphanCount, true, true));
+    console.log(fmt('  Ignored during parsing', result.parseIgnored.length, true, true));
+    if (result.parseIgnored.length > 0) {
+        console.log(`\nIgnored during parsing:`);
+        for (const f of result.parseIgnored)
+            console.log(`   ${f}`);
+    }
+    if (result.nodeErrors.length > 0) {
+        console.log(`\nSchema validation errors:`);
+        result.nodeErrors.forEach(({ file, errors, nodeData }) => {
+            console.log(`\n   ${file}:`);
+            const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
+            formatted.forEach(({ message }) => {
+                console.log(`      ${message}`);
+            });
+        });
+    }
+    if (result.refErrors.length > 0) {
+        console.log(`\nBroken links:`);
+        result.refErrors.forEach(({ file, parent, error }) => {
+            console.log(`   ${file}: ${parent} → ${error}`);
+        });
+    }
+    if (result.duplicateErrors.length > 0) {
+        console.log(`\nDuplicate keys (same title in multiple files):`);
+        result.duplicateErrors.forEach(({ title, files }) => {
+            console.log(`   "${title}":`);
+            for (const f of files) {
+                console.log(`      ${f}`);
+            }
+        });
+    }
+    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)) {
+                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) {
+                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description}`);
+            }
+        }
+    }
+    if (result.hierarchyViolations.length > 0) {
+        console.log(`\nHierarchy violations:`);
+        for (const v of result.hierarchyViolations) {
+            console.log(`   ${v.file}: ${v.description}`);
+        }
+    }
+    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 ||
+        result.ruleViolations.length > 0 ||
+        result.hierarchyViolations.length > 0) {
+        return 1;
+    }
+    return 0;
+}
+export async function watchValidate(context) {
+    const spacePath = context.space.path;
+    const schemaPath = context.resolvedSchemaPath;
+    const configFiles = Array.from(getConfigSourceFiles());
+    const schemaDir = dirname(schemaPath);
+    const schemaDirs = [bundledSchemasDir];
+    if (schemaDir !== bundledSchemasDir) {
+        schemaDirs.push(schemaDir);
+    }
+    console.log(`👀 Watching for changes...`);
+    console.log(`   Config files: ${configFiles.join(', ')}`);
+    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 () => {
+        try {
+            exitCode = await validate(context);
+        }
+        catch (error) {
+            console.error(`❌ Error during validation: ${error instanceof Error ? error.message : String(error)}`);
+            exitCode = 2;
+        }
+    };
+    await innerValidate();
+    const watchPaths = [...configFiles, ...schemaDirs, spacePath];
+    const watcher = chokidar.watch(watchPaths, {
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50,
+        },
+    });
+    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();
+    };
+    watcher.on('add', (path) => handleFileChange(path, 'added'));
+    watcher.on('change', (path) => handleFileChange(path, 'changed'));
+    watcher.on('unlink', (path) => handleFileChange(path, 'removed'));
+    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...');
+            watcher.close();
+            process.exit(exitCode);
+        });
+        process.on('uncaughtException', reject);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+export type SpaceConfig = {
+    name: string;
+    path: string;
+    schema?: string;
+    miroBoardId?: string;
+    miroFrameId?: string;
+    /** Plugin name → plugin config map. Overrides top-level plugins when set. */
+    plugins?: Record<string, Record<string, unknown>>;
+    /** Named filter views for this space. Keys are view names; values contain the filter expression. */
+    views?: Record<string, {
+        expression: string;
+    }>;
+};
+export type Config = {
+    spaces: SpaceConfig[];
+    schema?: string;
+    includeSpacesFrom?: string[];
+};
+/** Override the config file path used by loadConfig/updateSpaceField. */
+export declare function setConfigPath(path: string | undefined): void;
+/** Get all config file paths that were loaded (main config + included configs). */
+export declare function getConfigSourceFiles(): Set<string>;
+/**
+ * Get the directory of the config file that defines a given space.
+ */
+export declare function getSpaceConfigDir(spaceName: string): string;
+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 schema path: CLI arg > space-level config > global config > hardcoded default. */
+export declare function resolveSchema(config: Config, space?: SpaceConfig): string;
+type StringFields<T> = {
+    [K in keyof T]: T[K] extends string | undefined ? K : never;
+}[keyof T];
+/** Update a string field on a space entry and persist config. */
+export declare function updateSpaceField(spaceName: string, field: StringFields<SpaceConfig>, value: string): void;
+export {};

package/dist/config.js

@@ -0,0 +1,179 @@
+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 { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
+import { normalizePluginName } from './plugins/util';
+import { bundledSchemasDir } from './schema/schema';
+const CONFIG_SCHEMA = {
+    type: 'object',
+    properties: {
+        spaces: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', pattern: '^[a-z0-9_-]+$' },
+                    path: { type: 'string' },
+                    schema: { type: 'string' },
+                    miroBoardId: { type: 'string' },
+                    miroFrameId: { type: 'string' },
+                    plugins: { type: 'object', additionalProperties: { type: 'object' } },
+                    views: {
+                        type: 'object',
+                        additionalProperties: {
+                            type: 'object',
+                            properties: { expression: { type: 'string', minLength: 1 } },
+                            required: ['expression'],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ['name', 'path'],
+                additionalProperties: false,
+            },
+        },
+        schema: { type: 'string' },
+        includeSpacesFrom: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['spaces'],
+    additionalProperties: false,
+};
+let _configPathOverride;
+const _spaceSourceFiles = new Map();
+/** Override the config file path used by loadConfig/updateSpaceField. */
+export function setConfigPath(path) {
+    _configPathOverride = path;
+    _spaceSourceFiles.clear(); // Clear cache when config path changes
+}
+/** Get all config file paths that were loaded (main config + included configs). */
+export function getConfigSourceFiles() {
+    if (_spaceSourceFiles.size === 0) {
+        loadConfig();
+    }
+    return new Set(_spaceSourceFiles.values());
+}
+/**
+ * Get the directory of the config file that defines a given space.
+ */
+export function getSpaceConfigDir(spaceName) {
+    if (_spaceSourceFiles.size === 0) {
+        loadConfig();
+    }
+    const spaceConfigPath = _spaceSourceFiles.get(spaceName);
+    if (!spaceConfigPath)
+        throw new Error('Space config path not found');
+    return dirname(spaceConfigPath);
+}
+export function configPath() {
+    if (_configPathOverride) {
+        return _configPathOverride;
+    }
+    if (process.env[ENV_CONFIG_VAR]) {
+        return process.env[ENV_CONFIG_VAR];
+    }
+    const xdgBase = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+    const xdgPath = join(xdgBase, XDG_CONFIG_DIR, 'config.json');
+    if (existsSync(xdgPath)) {
+        return xdgPath;
+    }
+    const cwdPath = join(process.cwd(), 'config.json');
+    if (existsSync(cwdPath)) {
+        return cwdPath;
+    }
+    return xdgPath;
+}
+function normalizePlugins(plugins) {
+    if (!plugins)
+        return undefined;
+    return Object.fromEntries(Object.entries(plugins).map(([name, cfg]) => [normalizePluginName(name), cfg]));
+}
+function isUrl(p) {
+    return /^https?:\/\//i.test(p);
+}
+function resolveRelativePaths(config, configDir) {
+    const rel = (p) => {
+        if (!p || isAbsolute(p) || isUrl(p))
+            return p;
+        return resolve(configDir, p);
+    };
+    return {
+        ...config,
+        schema: rel(config.schema),
+        spaces: config.spaces.map((s) => ({
+            ...s,
+            path: rel(s.path),
+            schema: rel(s.schema),
+            plugins: normalizePlugins(s.plugins),
+        })),
+    };
+}
+function _loadConfig(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Config file not found: ${path}`);
+    }
+    const config = JSON5.parse(readFileSync(path, 'utf-8'));
+    const ajv = new Ajv();
+    const validate = ajv.compile(CONFIG_SCHEMA);
+    if (!validate(config)) {
+        throw new Error(`Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
+    }
+    return config;
+}
+export function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path)) {
+        console.warn(`Config file not found: ${path}`);
+        return { spaces: [] };
+    }
+    const config = _loadConfig(path);
+    _spaceSourceFiles.clear();
+    // Track which spaces come from the main config file
+    for (const space of config.spaces) {
+        _spaceSourceFiles.set(space.name, path);
+    }
+    // Load includeSpacesFrom configs and merge their spaces in, with later entries taking precedence over earlier ones
+    if (config.includeSpacesFrom) {
+        for (const includePath of config.includeSpacesFrom) {
+            // Resolve relative to the main config file
+            const resolvedIncludePath = isAbsolute(includePath) ? includePath : resolve(dirname(path), includePath);
+            const includedConfig = resolveRelativePaths(_loadConfig(resolvedIncludePath), dirname(resolvedIncludePath));
+            if (includedConfig.spaces.some((s) => config.spaces.some((existing) => existing.name === s.name))) {
+                throw new Error(`Included config contains spaces with duplicate names: ${resolvedIncludePath}`);
+            }
+            // Track which spaces come from this included config file
+            for (const space of includedConfig.spaces) {
+                _spaceSourceFiles.set(space.name, resolvedIncludePath);
+            }
+            config.spaces.push(...includedConfig.spaces);
+        }
+    }
+    return resolveRelativePaths(config, dirname(resolve(path)));
+}
+/** Get the full space config entry by name. Throws if not found. */
+export function getSpaceConfig(name, config) {
+    const space = config.spaces.find((s) => s.name === name);
+    if (!space) {
+        throw new Error(`Unknown space: "${name}". Check config.`);
+    }
+    return space;
+}
+/** Resolve schema path: CLI arg > space-level config > global config > hardcoded default. */
+export function resolveSchema(config, space) {
+    return space?.schema ?? config.schema ?? join(bundledSchemasDir, 'general.json');
+}
+/** Update a string field on a space entry and persist config. */
+export function updateSpaceField(spaceName, field, value) {
+    const sourcePath = _spaceSourceFiles.get(spaceName);
+    if (!sourcePath) {
+        throw new Error(`Space "${spaceName}" not found in any config file`);
+    }
+    const config = _loadConfig(sourcePath);
+    const space = config.spaces?.find((s) => s.name === spaceName);
+    if (!space) {
+        throw new Error(`Unknown space config: "${spaceName}". Check config.`);
+    }
+    space[field] = value;
+    writeFileSync(sourcePath, `${JSON5.stringify(config, null, 2)}\n`);
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const PACKAGE_NAME = "structured-context";
+export declare const XDG_CONFIG_DIR = "structured-context";
+export declare const CLI_NAME = "sctx";
+export declare const PLUGIN_PREFIX = "sctx-";
+export declare const ENV_CONFIG_VAR = "SCTX_CONFIG";
+export declare const SCHEMA_URI_SCHEME = "sctx";

package/dist/constants.js

@@ -0,0 +1,6 @@
+export const PACKAGE_NAME = 'structured-context';
+export const XDG_CONFIG_DIR = PACKAGE_NAME;
+export const CLI_NAME = 'sctx';
+export const PLUGIN_PREFIX = `${CLI_NAME}-`;
+export const ENV_CONFIG_VAR = 'SCTX_CONFIG';
+export const SCHEMA_URI_SCHEME = CLI_NAME;

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

@@ -0,0 +1,23 @@
+import type { SpaceNode } from '../types';
+/** Edge metadata merged into each ancestor/descendant entry. */
+export type EdgeMetadata = {
+    _field: string;
+    _source: 'hierarchy' | 'relationship';
+    _selfRef: boolean;
+};
+/** A flat node representation augmented with ancestor and descendant traversal arrays. */
+export type AugmentedFlatNode = Record<string, unknown> & {
+    resolvedType: string;
+    resolvedParentTitles: string[];
+    ancestors: Array<Record<string, unknown> & EdgeMetadata>;
+    descendants: Array<Record<string, unknown> & EdgeMetadata>;
+};
+/**
+ * Build the augmented flat representation of a node, including pre-computed
+ * ancestors[] and descendants[] arrays with edge metadata.
+ *
+ * - 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).
+ */
+export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>): AugmentedFlatNode;