structured-context 0.16.0 → 0.17.0

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.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
-import { loadConfig, resolveConfigPath, resolveSchemaPath } from '../config';
+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';
@@ -32,7 +32,7 @@ function jsonFiles(dir) {
  * 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 ?? loadConfig({ startDir: options.startDir });
+    const config = options.config ?? loadConfigOrEmpty({ startDir: options.startDir });
     const listings = [];
     const byPath = new Map();
     const add = (listing, location) => {

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
+}

package/dist/schemas/generated/space-graph/latest.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
+}

package/dist/space-context.js

@@ -1,4 +1,5 @@
 import { resolveSchema } from './config';
+import { SctxError } from './errors';
 import { resolveSpacePluginSchemas } from './plugins/util';
 import { loadSchema } from './schema/schema';
 /** Thrown by createSpaceContext when no space matches the given name. */
@@ -33,7 +34,16 @@ export function createSpaceContext(spaceName, config, options = {}) {
     }
     const resolvedSchemaPath = resolveSchema(config, space, { configDir });
     const pluginSchemas = resolveSpacePluginSchemas(space, config, configDir);
-    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath, pluginSchemas);
+    let loaded;
+    try {
+        loaded = loadSchema(resolvedSchemaPath, pluginSchemas);
+    }
+    catch (err) {
+        if (err instanceof SctxError)
+            throw err;
+        throw new SctxError('E_SCHEMA_INVALID', `Space "${spaceName}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const { schema, schemaRefRegistry, schemaValidator } = loaded;
     return {
         space,
         config,