structured-context 0.15.0 → 0.17.0

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,

package/dist/space-graph-data.d.ts

@@ -0,0 +1,237 @@
+import { type SpaceGraph } from './space-graph';
+import type { Hierarchy, SchemaMetadata, SpaceNode } from './types';
+/** Bump when the shape of SpaceGraphData changes; the generator refuses to overwrite a released version's schema. */
+export declare const SPACE_GRAPH_FORMAT_VERSION = 1;
+/** Folder under `schemas/generated/` holding the format schema: `latest.json` and one frozen file per released version. */
+export declare const SPACE_GRAPH_SCHEMA_DIR = "space-graph";
+/** Schema `$id` for a format version file, e.g. `.../generated/space-graph/1.json`. */
+export declare function spaceGraphSchemaId(file: string): string;
+/** JSON Schema for SpaceGraphData. Written to `schemas/generated/space-graph/` by `bun run generate:schema-meta`. */
+export declare const SPACE_GRAPH_DATA_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "structured-context space graph";
+    readonly type: "object";
+    readonly properties: {
+        readonly formatVersion: {
+            readonly const: 1;
+        };
+        readonly hierarchies: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly levels: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly selfRef: {
+                                    readonly type: "boolean";
+                                };
+                                readonly selfRefField: {
+                                    readonly type: "string";
+                                };
+                                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;
+                                    };
+                                };
+                                readonly field: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly fieldOn: {
+                                    readonly enum: readonly ["child", "parent"];
+                                };
+                                readonly multiple: {
+                                    readonly type: "boolean";
+                                };
+                                readonly type: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["type", "field", "fieldOn", "multiple", "selfRef"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly allowSkipLevels: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["name", "levels"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly mainHierarchy: {
+            readonly type: "string";
+        };
+        readonly nodes: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly schemaData: {
+                        readonly type: "object";
+                    };
+                    readonly linkTargets: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                    };
+                    readonly contentLinks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly linkSyntax: {
+                                    readonly enum: readonly ["wikilink", "markdown"];
+                                };
+                                readonly text: {
+                                    readonly type: "string";
+                                };
+                                readonly target: {
+                                    readonly type: "string";
+                                };
+                                readonly action: {
+                                    readonly enum: readonly ["link", "embed"];
+                                };
+                                readonly anchor: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["text", "target", "action", "linkSyntax"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly source: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly file: {
+                                readonly type: "string";
+                            };
+                            readonly line: {
+                                readonly type: "integer";
+                            };
+                            readonly column: {
+                                readonly type: "integer";
+                            };
+                        };
+                        readonly required: readonly ["file"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly resolvedType: {
+                        readonly type: "string";
+                    };
+                    readonly resolvedParents: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly field: {
+                                    readonly type: "string";
+                                };
+                                readonly kind: {
+                                    readonly enum: readonly ["hierarchy", "relationship"];
+                                };
+                                readonly hierarchy: {
+                                    readonly type: "string";
+                                };
+                                readonly selfRef: {
+                                    readonly type: "boolean";
+                                };
+                                readonly fieldOn: {
+                                    readonly enum: readonly ["child", "parent"];
+                                };
+                            };
+                            readonly required: readonly ["id", "field", "kind", "selfRef", "fieldOn"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly resolvedLinks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly location: {
+                                    readonly enum: readonly ["node", "internal", "external", "system", "protocol"];
+                                };
+                                readonly text: {
+                                    readonly type: "string";
+                                };
+                                readonly target: {
+                                    readonly type: "string";
+                                };
+                                readonly action: {
+                                    readonly enum: readonly ["link", "embed"];
+                                };
+                                readonly anchor: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["text", "target", "action", "location"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                };
+                readonly required: readonly ["id", "title", "schemaData", "linkTargets", "type", "resolvedType", "resolvedParents", "resolvedLinks"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: readonly ["formatVersion", "hierarchies", "nodes"];
+    readonly additionalProperties: false;
+};
+/**
+ * A space's nodes and hierarchies as plain JSON, for passing a graph across a process or network boundary.
+ *
+ * Edges live in each node's resolvedParents, including edges to nodes outside the set. The format names every
+ * hierarchy, so the receiver picks which one structures the graph.
+ */
+export type SpaceGraphData = {
+    formatVersion: typeof SPACE_GRAPH_FORMAT_VERSION;
+    hierarchies: Hierarchy[];
+    /** Name of the main hierarchy, if the schema has one. */
+    mainHierarchy?: string;
+    nodes: SpaceNode[];
+};
+/** Turn a set of nodes and its schema's hierarchies into SpaceGraphData. Pass `graph.nodes.values()` for a filtered graph. */
+export declare function exportSpaceGraph(nodes: Iterable<SpaceNode>, metadata: Pick<SchemaMetadata, 'hierarchy' | 'hierarchies'>): SpaceGraphData;
+/**
+ * Build a SpaceGraph from SpaceGraphData, structured by the named hierarchy (default: the main hierarchy).
+ * Throws on an unsupported format version or an unknown hierarchy name.
+ */
+export declare function spaceGraphFrom(data: SpaceGraphData, options?: {
+    hierarchy?: string;
+}): SpaceGraph;

package/dist/space-graph-data.js

@@ -0,0 +1,129 @@
+import { EDGE_PROPS, EMBEDDING_PROPS, SCHEMA_META_BASE_URL } from './schema/metadata-contract';
+import { buildSpaceGraph, selectHierarchy } from './space-graph';
+/** Bump when the shape of SpaceGraphData changes; the generator refuses to overwrite a released version's schema. */
+export const SPACE_GRAPH_FORMAT_VERSION = 1;
+/** Folder under `schemas/generated/` holding the format schema: `latest.json` and one frozen file per released version. */
+export const SPACE_GRAPH_SCHEMA_DIR = 'space-graph';
+/** Schema `$id` for a format version file, e.g. `.../generated/space-graph/1.json`. */
+export function spaceGraphSchemaId(file) {
+    return `${SCHEMA_META_BASE_URL}/${SPACE_GRAPH_SCHEMA_DIR}/${file}.json`;
+}
+const STRING = { type: 'string' };
+const SOURCE_LOCATION_SCHEMA = {
+    type: 'object',
+    properties: { file: STRING, line: { type: 'integer' }, column: { type: 'integer' } },
+    required: ['file'],
+    additionalProperties: false,
+};
+const CONTENT_LINK_PROPS = {
+    text: STRING,
+    target: STRING,
+    action: { enum: ['link', 'embed'] },
+    anchor: STRING,
+};
+const CONTENT_LINK_SCHEMA = {
+    type: 'object',
+    properties: { ...CONTENT_LINK_PROPS, linkSyntax: { enum: ['wikilink', 'markdown'] } },
+    required: ['text', 'target', 'action', 'linkSyntax'],
+    additionalProperties: false,
+};
+const RESOLVED_CONTENT_LINK_SCHEMA = {
+    type: 'object',
+    properties: { ...CONTENT_LINK_PROPS, location: { enum: ['node', 'internal', 'external', 'system', 'protocol'] } },
+    required: ['text', 'target', 'action', 'location'],
+    additionalProperties: false,
+};
+const RESOLVED_PARENT_REF_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: STRING,
+        field: STRING,
+        kind: { enum: ['hierarchy', 'relationship'] },
+        hierarchy: STRING,
+        selfRef: { type: 'boolean' },
+        fieldOn: EDGE_PROPS.fieldOn,
+    },
+    required: ['id', 'field', 'kind', 'selfRef', 'fieldOn'],
+    additionalProperties: false,
+};
+const SPACE_NODE_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: STRING,
+        title: STRING,
+        schemaData: { type: 'object' },
+        linkTargets: { type: 'array', items: STRING },
+        type: STRING,
+        content: STRING,
+        contentLinks: { type: 'array', items: CONTENT_LINK_SCHEMA },
+        source: SOURCE_LOCATION_SCHEMA,
+        resolvedType: STRING,
+        resolvedParents: { type: 'array', items: RESOLVED_PARENT_REF_SCHEMA },
+        resolvedLinks: { type: 'array', items: RESOLVED_CONTENT_LINK_SCHEMA },
+    },
+    required: ['id', 'title', 'schemaData', 'linkTargets', 'type', 'resolvedType', 'resolvedParents', 'resolvedLinks'],
+    additionalProperties: false,
+};
+/** A hierarchy level after normalisation: edge fields are always present. */
+const HIERARCHY_LEVEL_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: STRING,
+        ...EDGE_PROPS,
+        ...EMBEDDING_PROPS,
+        selfRef: { type: 'boolean' },
+        selfRefField: STRING,
+    },
+    required: ['type', 'field', 'fieldOn', 'multiple', 'selfRef'],
+    additionalProperties: false,
+};
+const HIERARCHY_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: STRING,
+        levels: { type: 'array', items: HIERARCHY_LEVEL_SCHEMA },
+        allowSkipLevels: { type: 'boolean' },
+    },
+    required: ['name', 'levels'],
+    additionalProperties: false,
+};
+/** JSON Schema for SpaceGraphData. Written to `schemas/generated/space-graph/` by `bun run generate:schema-meta`. */
+export const SPACE_GRAPH_DATA_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'structured-context space graph',
+    type: 'object',
+    properties: {
+        formatVersion: { const: SPACE_GRAPH_FORMAT_VERSION },
+        hierarchies: { type: 'array', items: HIERARCHY_SCHEMA },
+        mainHierarchy: STRING,
+        nodes: { type: 'array', items: SPACE_NODE_SCHEMA },
+    },
+    required: ['formatVersion', 'hierarchies', 'nodes'],
+    additionalProperties: false,
+};
+/** Turn a set of nodes and its schema's hierarchies into SpaceGraphData. Pass `graph.nodes.values()` for a filtered graph. */
+export function exportSpaceGraph(nodes, metadata) {
+    return {
+        formatVersion: SPACE_GRAPH_FORMAT_VERSION,
+        hierarchies: metadata.hierarchies ?? [],
+        ...(metadata.hierarchy ? { mainHierarchy: metadata.hierarchy.name } : {}),
+        nodes: [...nodes],
+    };
+}
+/**
+ * Build a SpaceGraph from SpaceGraphData, structured by the named hierarchy (default: the main hierarchy).
+ * Throws on an unsupported format version or an unknown hierarchy name.
+ */
+export function spaceGraphFrom(data, options = {}) {
+    if (data.formatVersion !== SPACE_GRAPH_FORMAT_VERSION) {
+        throw new Error(`Unsupported space graph format version ${data.formatVersion}; expected ${SPACE_GRAPH_FORMAT_VERSION}.`);
+    }
+    const metadata = {
+        hierarchy: data.hierarchies.find((h) => h.name === data.mainHierarchy),
+        hierarchies: data.hierarchies,
+    };
+    return buildSpaceGraph(data.nodes, selectHierarchy(metadata, options.hierarchy));
+}
+// Fails typecheck when SPACE_GRAPH_DATA_SCHEMA and SpaceGraphData drift apart.
+const _schemaMatchesType = true;
+void _schemaMatchesType;

package/dist/space-graph.d.ts

@@ -1,4 +1,9 @@
-import type { Hierarchy, NodeId, SpaceNode } from './types';
+import type { Hierarchy, NodeId, ResolvedParentRef, SchemaMetadata, SpaceNode } from './types';
+/** A typed edge between two nodes: a node's resolvedParents entry, with both ends named. */
+export type SpaceEdge = Omit<ResolvedParentRef, 'id'> & {
+    parent: NodeId;
+    child: NodeId;
+};
 /**
  * A navigable graph over a set of SpaceNodes.
  *
@@ -21,6 +26,10 @@ export type SpaceGraph = {
     readonly hierarchyChildren: ReadonlyMap<NodeId, readonly SpaceNode[]>;
     /** All-edges children map: parent id → direct children connected via any edge (hierarchy + relationship). */
     readonly children: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** Parent edges: child id → edges to its parents (hierarchy + relationship), in resolvedParents order. */
+    readonly parentEdges: ReadonlyMap<NodeId, readonly SpaceEdge[]>;
+    /** Child edges: parent id → edges to its children (hierarchy + relationship). */
+    readonly childEdges: ReadonlyMap<NodeId, readonly SpaceEdge[]>;
     /** Set of all node ids that are part of the hierarchy (roots + their descendants + orphans). */
     readonly hierarchyIds: ReadonlySet<NodeId>;
     /** The hierarchy used to build this graph, if the schema has one. */
@@ -28,3 +37,5 @@ export type SpaceGraph = {
 };
 /** Build a SpaceGraph from a flat list of SpaceNodes and the hierarchy to structure it by. */
 export declare function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undefined): SpaceGraph;
+/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
+export declare function selectHierarchy(metadata: Pick<SchemaMetadata, 'hierarchy' | 'hierarchies'>, name: string | undefined): Hierarchy | undefined;