structured-context 0.15.0 → 0.17.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { dump } from './commands/dump';
 import { miroSyncCommand } from './commands/miro-sync';
 import { listPlugins } from './commands/plugins';
 import { render, renderList } from './commands/render';
-import { listSchemas, showSchema } from './commands/schemas';
+import { printSchemas, showSchema } from './commands/schemas';
 import { show } from './commands/show';
 import { addSpaceCommand, listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
@@ -16,6 +16,7 @@ import { validate, watchValidate } from './commands/validate';
 import { validateFileCommand } from './commands/validate-file';
 import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
+import { SctxError } from './errors';
 import { JudgeConfigError } from './judge/factory';
 import { createSpaceContext, SpaceNotFoundError } from './space-context';
 // Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
@@ -121,6 +122,7 @@ program
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
     .option('--hierarchy <name>', 'Hierarchy used to evaluate --filter (default: the main hierarchy)')
+    .option('--graph', 'Output the space graph format: nodes plus every hierarchy')
     .action(async (spaceName, options) => dump(buildSpaceContext(spaceName), options));
 program
     .command('miro-sync')
@@ -176,7 +178,8 @@ const schemasCmd = new Command('schemas').alias('schema').description('List and
 schemasCmd
     .command('list', { isDefault: true })
     .description('List available schemas')
-    .action(async () => await listSchemas());
+    .option('--json', 'Output as JSON')
+    .action(async (options) => await printSchemas({ json: options.json ?? false }));
 schemasCmd
     .command('show')
     .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')
@@ -226,4 +229,10 @@ renderCmd
     await render(buildSpaceContext(spaceName), format, options);
 });
 program.addCommand(renderCmd);
-program.parse();
+// Expected errors print as one line; anything else keeps its stack trace
+program.parseAsync().catch((err) => {
+    if (!(err instanceof SctxError))
+        throw err;
+    console.error(`${err.code}: ${err.message}`);
+    process.exitCode = 1;
+});

package/dist/judge/context.js

@@ -49,7 +49,7 @@ export function relatedNodes(graph, node, context) {
     const parentsOf = (n) => graph.hierarchy === undefined
         ? []
         : n.resolvedParents
-            .filter((p) => p.source === 'hierarchy' && p.hierarchy === hierarchyName)
+            .filter((p) => p.kind === 'hierarchy' && p.hierarchy === hierarchyName)
             .map((p) => graph.nodes.get(p.id))
             .filter((p) => p !== undefined);
     const childrenOf = (n) => graph.hierarchyChildren.get(n.id) ?? [];

package/dist/load-space-graph.js

@@ -1,7 +1,7 @@
 import { filterNodes } from './filter/filter-nodes';
 import { readSpace } from './read/read-space';
 import { createSpaceContext } from './space-context';
-import { buildSpaceGraph } from './space-graph';
+import { buildSpaceGraph, selectHierarchy } from './space-graph';
 /**
  * Assemble a SpaceGraph from a space context: read the space, drop nodes that
  * fail schema validation, build the graph for the selected hierarchy (the main
@@ -26,18 +26,6 @@ export async function assembleSpaceGraph(context, options = {}) {
     }
     return graph;
 }
-/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
-function selectHierarchy(metadata, name) {
-    if (name === undefined)
-        return metadata.hierarchy;
-    const hierarchies = metadata.hierarchies ?? [];
-    const hierarchy = hierarchies.find((h) => h.name === name);
-    if (!hierarchy) {
-        const available = hierarchies.map((h) => h.name).join(', ');
-        throw new Error(`Unknown hierarchy: "${name}".${available ? ` Available: ${available}` : ' The schema defines no hierarchies.'}`);
-    }
-    return hierarchy;
-}
 /**
  * Load a named space and return its assembled, filtered SpaceGraph.
  *

package/dist/plugins/markdown/parse-embedded.js

@@ -364,7 +364,7 @@ export function extractEmbeddedNodes(body, options) {
             fieldOn: rel.fieldOn,
             multiple: rel.multiple,
             templateFormat: rel.templateFormat ?? 'heading',
-            source: 'relationship',
+            kind: 'relationship',
             matchers: rel.matchers,
             embeddedTemplateFields: rel.embeddedTemplateFields,
         };
@@ -378,7 +378,7 @@ export function extractEmbeddedNodes(body, options) {
             fieldOn: level.fieldOn,
             multiple: level.multiple,
             templateFormat: level.templateFormat ?? 'heading',
-            source: 'hierarchy',
+            kind: 'hierarchy',
             matchers: level.matchers,
             embeddedTemplateFields: level.embeddedTemplateFields,
         };
@@ -435,7 +435,7 @@ export function extractEmbeddedNodes(body, options) {
                     fieldOn: currentLevel.fieldOn,
                     multiple: currentLevel.multiple,
                     templateFormat: currentLevel.templateFormat ?? 'list',
-                    source: 'hierarchy',
+                    kind: 'hierarchy',
                     matchers: immediateParentLevel.matchers,
                 };
             }
@@ -651,7 +651,7 @@ export function extractEmbeddedNodes(body, options) {
                 // e.g. definition.type='capabilities', definition.parent='application' → capabilities is above application.
                 const typeIdx = hierarchy.indexOf(definition.type);
                 const parentIdx = hierarchy.indexOf(definition.parent);
-                const isParentLevelMatch = definition.source === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx;
+                const isParentLevelMatch = definition.kind === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx;
                 const activeNodeFieldAppendArg = isParentLevelMatch && semanticParent.node
                     ? { node: semanticParent.node, field: definition.field }
                     : undefined;

package/dist/plugins/miro/cache.js

@@ -30,7 +30,7 @@ export function computeNodeHash(node) {
         status: node.schemaData.status,
         summary: node.schemaData.summary,
         priority: node.schemaData.priority,
-        parents: node.resolvedParents.filter((r) => r.source === 'hierarchy').map((r) => r.id),
+        parents: node.resolvedParents.filter((r) => r.kind === 'hierarchy').map((r) => r.id),
     };
     return createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
 }

package/dist/plugins/miro/sync.js

@@ -257,8 +257,8 @@ export async function miroSync(context, graph, options) {
     const desiredEdges = new Map();
     for (const node of nodes) {
         const childTitle = node.title;
-        for (const { id: parentId, source, hierarchy } of node.resolvedParents) {
-            if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
+        for (const { id: parentId, kind, hierarchy } of node.resolvedParents) {
+            if (kind !== 'hierarchy' || hierarchy !== graph.hierarchy?.name)
                 continue;
             const parentTitle = graph.nodes.get(parentId)?.title ?? parentId;
             // Both endpoints must have verified cards on the board

package/dist/read/resolve-graph-edges.js

@@ -21,13 +21,13 @@ function getRefs(rawField, multiple) {
  * @param nodesByType Map of node type to nodes
  * @param targetIndex Map of link targets to nodes
  * @param edge The edge definition (child type, parent type, field, fieldOn, multiple)
- * @param source Whether this edge comes from hierarchy levels or relationships
+ * @param kind Whether this edge comes from hierarchy levels or relationships
  * @param hierarchy Name of the hierarchy the edge belongs to (hierarchy edges only)
  * @param selfRef Whether child and parent are the same node type
  * @param unresolvedRefs Array to push broken/invalid link entries into
  * @param typeAliases Optional type aliases for resolution
  */
-function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef, unresolvedRefs, typeAliases) {
+function resolveEdge(nodesByType, targetIndex, edge, kind, hierarchy, selfRef, unresolvedRefs, typeAliases) {
     const { type: rawChildType, parent: rawParentType, field, fieldOn, multiple } = edge;
     const childType = resolveNodeType(rawChildType, typeAliases);
     const parentType = resolveNodeType(rawParentType, typeAliases);
@@ -38,7 +38,7 @@ function resolveEdge(nodesByType, targetIndex, edge, source, hierarchy, selfRef,
                 id: parentId,
                 field,
                 fieldOn,
-                source,
+                kind,
                 ...(hierarchy !== undefined ? { hierarchy } : {}),
                 selfRef,
             });

package/dist/schema/list-schemas.d.ts

@@ -0,0 +1,27 @@
+import { type Config } from '../config';
+type SchemaListing = {
+    /** The value for a config's `schema` field. */
+    schema: string;
+    /** Absolute location or URL. Omitted for bundled schemas. */
+    path?: string;
+    /** `core`, a plugin's short name, or `configured`. */
+    source: string;
+    /** Names of the spaces that use it, and `global` when the top-level `schema` does. */
+    usedBy: string[];
+    partial: boolean;
+    id?: string;
+    title?: string;
+    description?: string;
+    /** Why the schema could not be read. */
+    error?: string;
+};
+/**
+ * List the schemas available to the config: bundled schemas, schemas contributed by plugins, and any other
+ * schema file the config points at. Each schema appears once, under the place its file lives.
+ */
+export declare function listSchemas(options?: {
+    /** Loaded by discovery from `startDir` when omitted. */
+    config?: Config;
+    startDir?: string;
+}): Promise<SchemaListing[]>;
+export {};

package/dist/schema/list-schemas.js

@@ -0,0 +1,108 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { loadConfigOrEmpty, resolveConfigPath, resolveSchemaPath } from '../config';
+import { PLUGIN_PREFIX } from '../constants';
+import { CONFIG_PLUGINS_DIR, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { bundledSchemasDir, readRawSchema } from './schema';
+function isRemote(ref) {
+    return /^https?:\/\//.test(ref);
+}
+function describeSchema(path) {
+    try {
+        const schema = readRawSchema(path);
+        return {
+            ...(typeof schema.$id === 'string' && { id: schema.$id }),
+            ...(typeof schema.title === 'string' && { title: schema.title }),
+            ...(typeof schema.description === 'string' && { description: schema.description }),
+        };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function jsonFiles(dir) {
+    if (!dir || !existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .sort();
+}
+/**
+ * List the schemas available to the config: bundled schemas, schemas contributed by plugins, and any other
+ * schema file the config points at. Each schema appears once, under the place its file lives.
+ */
+export async function listSchemas(options = {}) {
+    const config = options.config ?? loadConfigOrEmpty({ startDir: options.startDir });
+    const listings = [];
+    const byPath = new Map();
+    const add = (listing, location) => {
+        listings.push(listing);
+        byPath.set(resolve(location), listing);
+    };
+    for (const file of jsonFiles(bundledSchemasDir)) {
+        const location = join(bundledSchemasDir, file);
+        add({ schema: file, source: 'core', usedBy: [], partial: file.startsWith('_'), ...describeSchema(location) }, location);
+    }
+    // Relative schema references are anchored at the folder of the config that holds them
+    const fallbackDir = dirname(resolveConfigPath(options.startDir).path);
+    const configDirs = [...new Set([fallbackDir, ...config.spaces.map((s) => s.sourceDir ?? fallbackDir)])];
+    // Plugins are found the way schema references resolve them, without loading their code: those declared by a
+    // space or the config, and any installed beside a config file
+    const pluginSchemaDirs = new Map();
+    for (const space of [undefined, ...config.spaces]) {
+        for (const { pluginName, schemasDir } of resolveSpacePluginSchemas(space, config, space?.sourceDir ?? fallbackDir)) {
+            pluginSchemaDirs.set(pluginName, schemasDir);
+        }
+    }
+    for (const dir of configDirs) {
+        const pluginsDir = join(dir, CONFIG_PLUGINS_DIR);
+        if (!existsSync(pluginsDir))
+            continue;
+        for (const entry of readdirSync(pluginsDir).filter((e) => e.startsWith(PLUGIN_PREFIX))) {
+            const schemasDir = resolvePluginSchemasDir(entry, dir);
+            if (schemasDir && !pluginSchemaDirs.has(shortenPluginName(entry))) {
+                pluginSchemaDirs.set(shortenPluginName(entry), schemasDir);
+            }
+        }
+    }
+    for (const [source, schemasDir] of pluginSchemaDirs) {
+        for (const file of jsonFiles(schemasDir)) {
+            const location = join(schemasDir, file);
+            add({
+                schema: `${source}/${file}`,
+                path: location,
+                source,
+                usedBy: [],
+                partial: file.startsWith('_'),
+                ...describeSchema(location),
+            }, location);
+        }
+    }
+    const references = [
+        ...(config.schema ? [{ user: 'global', raw: config.schema, dir: fallbackDir }] : []),
+        ...config.spaces.flatMap((s) => s.schema ? [{ user: s.name, raw: s.schema, dir: s.sourceDir ?? fallbackDir }] : []),
+    ];
+    for (const { user, raw, dir } of references) {
+        const location = isRemote(raw) ? raw : resolveSchemaPath(raw, dir);
+        const key = isRemote(raw) ? raw : resolve(location);
+        let listing = byPath.get(key);
+        if (!listing) {
+            listing = {
+                schema: raw,
+                path: isRemote(raw) || isAbsolute(location) ? location : resolve(location),
+                source: 'configured',
+                usedBy: [],
+                partial: basename(raw).startsWith('_'),
+                ...(isRemote(raw)
+                    ? { error: 'Remote schemas are not read' }
+                    : existsSync(location)
+                        ? describeSchema(location)
+                        : { error: `Schema file not found: ${location}` }),
+            };
+            add(listing, key);
+        }
+        if (!listing.usedBy.includes(user))
+            listing.usedBy.push(user);
+    }
+    return listings;
+}

package/dist/schema/metadata-contract.d.ts

@@ -7,6 +7,40 @@ export declare const SCHEMA_META_FILE = "_structured_context_schema_meta.json";
 export declare function schemaMetaId(folder: string): string;
 /** The URL schemas set as `$schema` to follow the newest dialect. Resolves to the newest versioned meta-schema. */
 export declare const SCHEMA_META_ID: string;
+/** Graph edge routing fields shared by hierarchy levels and relationships. */
+export declare const EDGE_PROPS: {
+    readonly field: {
+        readonly type: "string";
+        readonly minLength: 1;
+    };
+    readonly fieldOn: {
+        readonly enum: readonly ["child", "parent"];
+    };
+    readonly multiple: {
+        readonly type: "boolean";
+    };
+};
+/** Embedding/template hint fields shared by hierarchy levels and relationships. */
+export declare const EMBEDDING_PROPS: {
+    readonly templateFormat: {
+        readonly enum: readonly ["heading", "list", "table", "page"];
+    };
+    readonly matchers: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly minItems: 1;
+    };
+    readonly embeddedTemplateFields: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+};
 /** Schema objects wrapping each prop group for type derivation via FromSchema. */
 declare const EDGE_SCHEMA: {
     readonly type: "object";

package/dist/schema/metadata-contract.js

@@ -9,13 +9,13 @@ export function schemaMetaId(folder) {
 /** The URL schemas set as `$schema` to follow the newest dialect. Resolves to the newest versioned meta-schema. */
 export const SCHEMA_META_ID = schemaMetaId('latest');
 /** Graph edge routing fields shared by hierarchy levels and relationships. */
-const EDGE_PROPS = {
+export const EDGE_PROPS = {
     field: { type: 'string', minLength: 1 },
     fieldOn: { enum: ['child', 'parent'] },
     multiple: { type: 'boolean' },
 };
 /** Embedding/template hint fields shared by hierarchy levels and relationships. */
-const EMBEDDING_PROPS = {
+export const EMBEDDING_PROPS = {
     templateFormat: { enum: ['heading', 'list', 'table', 'page'] },
     matchers: { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1 },
     embeddedTemplateFields: { type: 'array', items: { type: 'string', minLength: 1 } },

package/dist/schema/validate-graph.d.ts

@@ -16,8 +16,8 @@ export declare function validateGraph(nodes: SpaceNode[], metadata: SchemaMetada
 /**
  * Validate that resolved parents follow hierarchy level rules and relationship type constraints.
  *
- * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering within the edge's hierarchy.
- * For relationship edges (fieldOn:'child', source:'relationship'): validates parent type.
+ * For hierarchy edges (fieldOn:'child', kind:'hierarchy'): validates level ordering within the edge's hierarchy.
+ * For relationship edges (fieldOn:'child', kind:'relationship'): validates parent type.
  * For fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node.
  *
  * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.

package/dist/schema/validate-graph.js

@@ -16,8 +16,8 @@ export function validateGraph(nodes, metadata, unresolvedRefs = []) {
 /**
  * Validate that resolved parents follow hierarchy level rules and relationship type constraints.
  *
- * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering within the edge's hierarchy.
- * For relationship edges (fieldOn:'child', source:'relationship'): validates parent type.
+ * For hierarchy edges (fieldOn:'child', kind:'hierarchy'): validates level ordering within the edge's hierarchy.
+ * For relationship edges (fieldOn:'child', kind:'relationship'): validates parent type.
  * For fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node.
  *
  * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
@@ -96,7 +96,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                     });
                 }
             }
-            else if (parentRef.source === 'relationship') {
+            else if (parentRef.kind === 'relationship') {
                 // Relationship edge (fieldOn:'child'): validate parent type matches relationship definition.
                 const allowedTypes = typeRules.get(nodeType)?.get(parentRef.field);
                 if (allowedTypes && !allowedTypes.has(parentType)) {
@@ -112,7 +112,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 }
             }
             else {
-                // Hierarchy edge (fieldOn:'child', source:'hierarchy'): validate level ordering within its hierarchy.
+                // Hierarchy edge (fieldOn:'child', kind:'hierarchy'): validate level ordering within its hierarchy.
                 const edgeHierarchy = parentRef.hierarchy !== undefined ? hierarchiesByName.get(parentRef.hierarchy) : undefined;
                 if (!edgeHierarchy)
                     continue;

package/dist/schemas/generated/space-graph/1.json

@@ -0,0 +1,216 @@
+{
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/space-graph/1.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "structured-context space graph",
+  "type": "object",
+  "properties": {
+    "formatVersion": {
+      "const": 1
+    },
+    "hierarchies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "levels": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                },
+                "multiple": {
+                  "type": "boolean"
+                },
+                "templateFormat": {
+                  "enum": ["heading", "list", "table", "page"]
+                },
+                "matchers": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "minItems": 1
+                },
+                "embeddedTemplateFields": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "selfRefField": {
+                  "type": "string"
+                }
+              },
+              "required": ["type", "field", "fieldOn", "multiple", "selfRef"],
+              "additionalProperties": false
+            }
+          },
+          "allowSkipLevels": {
+            "type": "boolean"
+          }
+        },
+        "required": ["name", "levels"],
+        "additionalProperties": false
+      }
+    },
+    "mainHierarchy": {
+      "type": "string"
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "schemaData": {
+            "type": "object"
+          },
+          "linkTargets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "type": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "linkSyntax": {
+                  "enum": ["wikilink", "markdown"]
+                }
+              },
+              "required": ["text", "target", "action", "linkSyntax"],
+              "additionalProperties": false
+            }
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer"
+              },
+              "column": {
+                "type": "integer"
+              }
+            },
+            "required": ["file"],
+            "additionalProperties": false
+          },
+          "resolvedType": {
+            "type": "string"
+          },
+          "resolvedParents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": ["hierarchy", "relationship"]
+                },
+                "hierarchy": {
+                  "type": "string"
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                }
+              },
+              "required": ["id", "field", "kind", "selfRef", "fieldOn"],
+              "additionalProperties": false
+            }
+          },
+          "resolvedLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "location": {
+                  "enum": ["node", "internal", "external", "system", "protocol"]
+                }
+              },
+              "required": ["text", "target", "action", "location"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "schemaData",
+          "linkTargets",
+          "type",
+          "resolvedType",
+          "resolvedParents",
+          "resolvedLinks"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["formatVersion", "hierarchies", "nodes"],
+  "additionalProperties": false
+}