From a4e3f884c0ac86b1ce2f53e5c7e70e09462db6bc Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 22:24:17 +1100 Subject: [PATCH 1/6] refactor: rename edge `source` to `kind` ResolvedParentRef.source becomes kind, and the filter metadata _source becomes _kind. The edge `source` clashed with a node's source location and with the source/target endpoint convention of graph formats. Refs #138 --- docs/concepts.md | 8 ++++---- plugin/.claude-plugin/plugin.json | 2 +- .../skills/structured-context/references/commands.md | 2 +- src/filter/augment-nodes.ts | 6 +++--- src/filter/expand-include.ts | 4 ++-- src/judge/context.ts | 2 +- src/plugins/markdown/parse-embedded.ts | 10 +++++----- src/plugins/miro/cache.ts | 2 +- src/plugins/miro/sync.ts | 4 ++-- src/read/resolve-graph-edges.ts | 6 +++--- src/schema/validate-graph.ts | 8 ++++---- src/space-graph.ts | 2 +- src/testing.ts | 6 +++--- src/types.ts | 4 ++-- tests/filter/augment-nodes.test.ts | 8 ++++---- tests/filter/expand-include.test.ts | 2 +- tests/judge/context.test.ts | 2 +- tests/judge/helpers.ts | 2 +- tests/read/resolve-hierarchy-edges.test.ts | 8 ++++---- tests/space-graph.test.ts | 8 ++++---- 20 files changed, 48 insertions(+), 48 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 6d27b349..cbc91db6 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -319,11 +319,11 @@ Each entry is a `ResolvedParentRef` object: |---|---|---| | `id` | `NodeId` | The parent node's `id` | | `field` | `string` | The frontmatter field that held the wikilink | -| `source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship | -| `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `source` is `'hierarchy'` | +| `kind` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship | +| `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `kind` is `'hierarchy'` | | `selfRef` | `boolean` | Whether the edge is a same-type (self-referential) parent link | -The `source` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set. +The `kind` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set. ### Content links @@ -386,7 +386,7 @@ Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the | Metadata field | Type | Description | |----------------|------|-------------| | `_field` | `string` | The edge field name that connects to this ancestor/descendant | -| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship | +| `_kind` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship | | `_hierarchy` | `string` | Hierarchy name; present only for hierarchy edges | | `_selfRef` | `boolean` | Whether the edge is a same-type (self-referential) link | diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 666285a3..833cead5 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.16.2", + "version": "0.16.4", "description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", diff --git a/plugin/skills/structured-context/references/commands.md b/plugin/skills/structured-context/references/commands.md index 298b64de..6ea8f688 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -92,7 +92,7 @@ sctx show --filter my-view-name **Filter expression syntax:** `WHERE {jsonata}` | `SELECT {spec} WHERE {jsonata}` | `SELECT {spec}` | bare JSONata. Within the WHERE predicate, node fields (e.g. `resolvedType`, `status`) are directly accessible. Two traversal arrays are also available per node: -- `ancestors[]` — ancestor nodes nearest-first, each with `_field`, `_source`, `_hierarchy` (hierarchy edges only), `_selfRef` edge metadata +- `ancestors[]` — ancestor nodes nearest-first, each with `_field`, `_kind`, `_hierarchy` (hierarchy edges only), `_selfRef` edge metadata - `descendants[]` — descendant nodes, same structure The SELECT spec is a comma-separated list of directives that expand the result set: diff --git a/src/filter/augment-nodes.ts b/src/filter/augment-nodes.ts index ced9434c..20fb4dc2 100644 --- a/src/filter/augment-nodes.ts +++ b/src/filter/augment-nodes.ts @@ -3,7 +3,7 @@ import type { NodeId, ResolvedParentRef, SpaceNode } from '../types'; /** Edge metadata merged into each ancestor/descendant entry. */ export type EdgeMetadata = { _field: string; - _source: 'hierarchy' | 'relationship'; + _kind: 'hierarchy' | 'relationship'; /** Hierarchy name, present only for hierarchy edges. */ _hierarchy?: string; _selfRef: boolean; @@ -22,7 +22,7 @@ export type AugmentedFlatNode = Record & { function edgeMetadata(ref: ResolvedParentRef): EdgeMetadata { return { _field: ref.field, - _source: ref.source, + _kind: ref.kind, ...(ref.hierarchy !== undefined ? { _hierarchy: ref.hierarchy } : {}), _selfRef: ref.selfRef, }; @@ -44,7 +44,7 @@ function flattenData(node: SpaceNode): Record { * * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by id. * - descendants: BFS via childrenIndex, nearest first, deduplicated by id. - * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef). + * - Each entry merges the parent/child node's fields with edge metadata (_field, _kind, _hierarchy, _selfRef). */ export function augmentNode( node: SpaceNode, diff --git a/src/filter/expand-include.ts b/src/filter/expand-include.ts index 27d6aec7..c6aec946 100644 --- a/src/filter/expand-include.ts +++ b/src/filter/expand-include.ts @@ -195,13 +195,13 @@ function applyDirective( case 'relationships': { // Relationship-sourced ancestors (matched node is the child side) for (const a of aug.ancestors) { - if (a._source === 'relationship' && matchesRelSpec(node, a, directive, true)) { + if (a._kind === 'relationship' && matchesRelSpec(node, a, directive, true)) { addById(a.id as NodeId); } } // Relationship-sourced descendants (matched node is the parent side) for (const d of aug.descendants) { - if (d._source === 'relationship' && matchesRelSpec(node, d, directive, false)) { + if (d._kind === 'relationship' && matchesRelSpec(node, d, directive, false)) { addById(d.id as NodeId); } } diff --git a/src/judge/context.ts b/src/judge/context.ts index 35c5cf12..0e7df800 100644 --- a/src/judge/context.ts +++ b/src/judge/context.ts @@ -65,7 +65,7 @@ export function relatedNodes(graph: SpaceGraph, node: SpaceNode, context: RuleCo 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 is SpaceNode => p !== undefined); const childrenOf = (n: SpaceNode) => graph.hierarchyChildren.get(n.id) ?? []; diff --git a/src/plugins/markdown/parse-embedded.ts b/src/plugins/markdown/parse-embedded.ts index 9a475c0a..f8b2c58f 100644 --- a/src/plugins/markdown/parse-embedded.ts +++ b/src/plugins/markdown/parse-embedded.ts @@ -39,7 +39,7 @@ type StackEntry = { */ interface EmbeddingDefinition extends EdgeDefinition, SharedEmbeddingFields { templateFormat: NonNullable; - source: 'hierarchy' | 'relationship'; + kind: 'hierarchy' | 'relationship'; } /** Active grouping context — replaces ad-hoc pendingMatch. */ @@ -527,7 +527,7 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio fieldOn: rel.fieldOn, multiple: rel.multiple, templateFormat: (rel.templateFormat as EmbeddingDefinition['templateFormat']) ?? 'heading', - source: 'relationship', + kind: 'relationship', matchers: rel.matchers, embeddedTemplateFields: rel.embeddedTemplateFields, }; @@ -542,7 +542,7 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio fieldOn: level.fieldOn, multiple: level.multiple, templateFormat: level.templateFormat ?? 'heading', - source: 'hierarchy', + kind: 'hierarchy', matchers: level.matchers, embeddedTemplateFields: level.embeddedTemplateFields, }; @@ -603,7 +603,7 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio fieldOn: currentLevel.fieldOn, multiple: currentLevel.multiple, templateFormat: currentLevel.templateFormat ?? 'list', - source: 'hierarchy', + kind: 'hierarchy', matchers: immediateParentLevel.matchers, }; } @@ -839,7 +839,7 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio const typeIdx = hierarchy.indexOf(definition.type); const parentIdx = hierarchy.indexOf(definition.parent); const isParentLevelMatch = - definition.source === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx; + definition.kind === 'hierarchy' && typeIdx !== -1 && parentIdx !== -1 && typeIdx < parentIdx; const activeNodeFieldAppendArg = isParentLevelMatch && semanticParent.node diff --git a/src/plugins/miro/cache.ts b/src/plugins/miro/cache.ts index 6feb6062..f5426139 100644 --- a/src/plugins/miro/cache.ts +++ b/src/plugins/miro/cache.ts @@ -54,7 +54,7 @@ export function computeNodeHash(node: SpaceNode): string { 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); } diff --git a/src/plugins/miro/sync.ts b/src/plugins/miro/sync.ts index 5796eee1..d288bb78 100644 --- a/src/plugins/miro/sync.ts +++ b/src/plugins/miro/sync.ts @@ -291,8 +291,8 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option 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) continue; + 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 if (verifiedCardIds.has(parentTitle) && verifiedCardIds.has(childTitle)) { diff --git a/src/read/resolve-graph-edges.ts b/src/read/resolve-graph-edges.ts index 9b50ed7d..d97b22a9 100644 --- a/src/read/resolve-graph-edges.ts +++ b/src/read/resolve-graph-edges.ts @@ -34,7 +34,7 @@ function getRefs(rawField: unknown, multiple: boolean): string[] { * @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 @@ -44,7 +44,7 @@ function resolveEdge( nodesByType: Map, targetIndex: Map, edge: EdgeDefinition, - source: ResolvedParentRef['source'], + kind: ResolvedParentRef['kind'], hierarchy: string | undefined, selfRef: boolean, unresolvedRefs: UnresolvedRef[], @@ -62,7 +62,7 @@ function resolveEdge( id: parentId, field, fieldOn, - source, + kind, ...(hierarchy !== undefined ? { hierarchy } : {}), selfRef, }); diff --git a/src/schema/validate-graph.ts b/src/schema/validate-graph.ts index 9838c11b..c4195f95 100644 --- a/src/schema/validate-graph.ts +++ b/src/schema/validate-graph.ts @@ -28,8 +28,8 @@ export function validateGraph( /** * 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. @@ -111,7 +111,7 @@ export function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaM description: `Invalid relationship: ${parentType} "${parentTitle}" has "${nodeTitle}" in field "${parentRef.field}" which is of type ${nodeType}, expected ${expected}`, }); } - } 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)) { @@ -126,7 +126,7 @@ export function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaM }); } } 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; diff --git a/src/space-graph.ts b/src/space-graph.ts index 7de08603..12774d4b 100644 --- a/src/space-graph.ts +++ b/src/space-graph.ts @@ -40,7 +40,7 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef const levels = hierarchy?.levels ?? []; const hierarchyTypes = new Set(levels.map((l) => l.type)); const rootType = levels[0]?.type; - const isHierarchyEdge = (r: ResolvedParentRef) => r.source === 'hierarchy' && r.hierarchy === hierarchy?.name; + const isHierarchyEdge = (r: ResolvedParentRef) => r.kind === 'hierarchy' && r.hierarchy === hierarchy?.name; const nodesMap = new Map(); const hierarchyChildrenMap = new Map(); diff --git a/src/testing.ts b/src/testing.ts index f496092b..e4e0e7ed 100644 --- a/src/testing.ts +++ b/src/testing.ts @@ -5,12 +5,12 @@ import type { BaseNode, Hierarchy, HierarchyLevel, NodeId, Relationship, Resolve * Override any field to represent specific edge contexts. */ export const makeParentRef = (id: string, overrides: Partial = {}): ResolvedParentRef => { - const source = overrides.source ?? 'hierarchy'; + const kind = overrides.kind ?? 'hierarchy'; return { id: id as NodeId, field: 'parent', - source, - ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}), + kind, + ...(kind === 'hierarchy' ? { hierarchy: 'main' } : {}), selfRef: false, fieldOn: 'child', ...overrides, diff --git a/src/types.ts b/src/types.ts index d7c7c302..95019685 100644 --- a/src/types.ts +++ b/src/types.ts @@ -51,8 +51,8 @@ export type ResolvedParentRef = { /** The field name that contained the wikilink (e.g. 'parent', 'key_activities', 'produces_data'). */ field: string; /** Whether this edge originates from a hierarchy level or a relationship definition. */ - source: 'hierarchy' | 'relationship'; - /** Name of the hierarchy the edge belongs to. Set only when source is 'hierarchy'. */ + kind: 'hierarchy' | 'relationship'; + /** Name of the hierarchy the edge belongs to. Set only when kind is 'hierarchy'. */ hierarchy?: string; /** Whether the parent and child are the same node type (self-referential edge). */ selfRef: boolean; diff --git a/tests/filter/augment-nodes.test.ts b/tests/filter/augment-nodes.test.ts index 1ee34ff1..3417ae3d 100644 --- a/tests/filter/augment-nodes.test.ts +++ b/tests/filter/augment-nodes.test.ts @@ -44,7 +44,7 @@ describe('augmentNode', () => { title: 'Root', resolvedType: 'goal', _field: 'parent', - _source: 'hierarchy', + _kind: 'hierarchy', _selfRef: false, }); }); @@ -99,7 +99,7 @@ describe('augmentNode', () => { it('preserves edge metadata from relationship edges', () => { const parent = makeNode('Opportunity', 'opportunity'); const child = makeNode('Assumption', 'assumption', [ - makeParentRef('Opportunity', { source: 'relationship', field: 'assumptions', selfRef: false }), + makeParentRef('Opportunity', { kind: 'relationship', field: 'assumptions', selfRef: false }), ]); const nodes = [parent, child]; const nodeIndex = new Map(nodes.map((n) => [n.id, n])); @@ -108,7 +108,7 @@ describe('augmentNode', () => { expect(result.ancestors[0]).toMatchObject({ _field: 'assumptions', - _source: 'relationship', + _kind: 'relationship', _selfRef: false, }); }); @@ -135,7 +135,7 @@ describe('augmentNode', () => { title: 'Child', resolvedType: 'opportunity', _field: 'parent', - _source: 'hierarchy', + _kind: 'hierarchy', }); }); diff --git a/tests/filter/expand-include.test.ts b/tests/filter/expand-include.test.ts index 4e53d60a..ba2b2b19 100644 --- a/tests/filter/expand-include.test.ts +++ b/tests/filter/expand-include.test.ts @@ -135,7 +135,7 @@ sol1.resolvedParents = [makeParentRef('Opportunity A')]; sol2.resolvedParents = [makeParentRef('Opportunity A')]; sol3.resolvedParents = [makeParentRef('Opportunity B')]; // assumption linked to opportunity A via relationship -assumption.resolvedParents = [makeParentRef('Opportunity A', { source: 'relationship', field: 'assumptions' })]; +assumption.resolvedParents = [makeParentRef('Opportunity A', { kind: 'relationship', field: 'assumptions' })]; const allNodes = [goal, oppA, oppB, sol1, sol2, sol3, assumption]; const ctx = buildContext(allNodes); diff --git a/tests/judge/context.test.ts b/tests/judge/context.test.ts index cf740b18..c753064b 100644 --- a/tests/judge/context.test.ts +++ b/tests/judge/context.test.ts @@ -20,7 +20,7 @@ const sol2 = child('Sol2', 'solution', 'Opp'); const subSol = child('SubSol', 'solution', 'Sol'); // Related to Opp by a non-hierarchy relationship: never in scope. const assumption = makeSpaceNode('Assume', 'assumption', {}, undefined, [ - makeParentRef('Opp', { source: 'relationship', hierarchy: undefined }), + makeParentRef('Opp', { kind: 'relationship', hierarchy: undefined }), ]); const nodes: SpaceNode[] = [goal, opp, sibling, sol, sol2, subSol, assumption]; const graph = buildSpaceGraph(nodes, hierarchy); diff --git a/tests/judge/helpers.ts b/tests/judge/helpers.ts index 09b2a99e..14a99cc4 100644 --- a/tests/judge/helpers.ts +++ b/tests/judge/helpers.ts @@ -12,7 +12,7 @@ export const node: SemanticJudgeInput['node'] & Pick { }); describe('relationship edges', () => { - it('assigns source: hierarchy when type appears in both hierarchy and a relationship', () => { + it('assigns kind: hierarchy when type appears in both hierarchy and a relationship', () => { const levels = [makeLevel('project'), makeLevel('task')]; const relationships: Relationship[] = [ { @@ -223,10 +223,10 @@ describe('resolveGraphEdges', () => { const resolvedTask = nodes.find((n) => n.id === 'Task 1')!; const ref = resolvedTask.resolvedParents.find((r) => r.id === 'Project A'); expect(ref).toBeDefined(); - expect(ref?.source).toBe('hierarchy'); + expect(ref?.kind).toBe('hierarchy'); }); - it('assigns source: relationship when type appears only in relationships', () => { + it('assigns kind: relationship when type appears only in relationships', () => { const levels = [makeLevel('project')]; const relationships: Relationship[] = [ { @@ -247,7 +247,7 @@ describe('resolveGraphEdges', () => { const resolvedResource = nodes.find((n) => n.id === 'Resource 1')!; const ref = resolvedResource.resolvedParents.find((r) => r.id === 'Project A'); expect(ref).toBeDefined(); - expect(ref?.source).toBe('relationship'); + expect(ref?.kind).toBe('relationship'); }); }); diff --git a/tests/space-graph.test.ts b/tests/space-graph.test.ts index f303652d..0254c454 100644 --- a/tests/space-graph.test.ts +++ b/tests/space-graph.test.ts @@ -82,7 +82,7 @@ describe('buildSpaceGraph', () => { it('maps parent to hierarchy children only', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); - opp.resolvedParents = [makeParentRef('My Goal', { source: 'hierarchy' })]; + opp.resolvedParents = [makeParentRef('My Goal', { kind: 'hierarchy' })]; const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('My Goal' as NodeId)).toContain(opp); }); @@ -90,7 +90,7 @@ describe('buildSpaceGraph', () => { it('excludes relationship edges from hierarchyChildren', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); - opp.resolvedParents = [makeParentRef('My Goal', { source: 'relationship' })]; + opp.resolvedParents = [makeParentRef('My Goal', { kind: 'relationship' })]; const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('My Goal' as NodeId)).toHaveLength(0); }); @@ -107,8 +107,8 @@ describe('buildSpaceGraph', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); const assumption = makeNode('An Assumption', 'assumption'); - opp.resolvedParents = [makeParentRef('My Goal', { source: 'hierarchy' })]; - assumption.resolvedParents = [makeParentRef('My Goal', { source: 'relationship', field: 'assumptions' })]; + opp.resolvedParents = [makeParentRef('My Goal', { kind: 'hierarchy' })]; + assumption.resolvedParents = [makeParentRef('My Goal', { kind: 'relationship', field: 'assumptions' })]; const graph = buildSpaceGraph([goal, opp, assumption], makeHierarchy(levels)); const children = graph.children.get('My Goal' as NodeId) ?? []; expect(children).toContain(opp); From b5bc7caf5c43e0f6a8de8d45ec5b2aaaade24fb0 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 22:25:25 +1100 Subject: [PATCH 2/6] feat(graph): typed parentEdges and childEdges maps on SpaceGraph Each resolvedParents entry becomes a SpaceEdge naming both ends, indexed by child and by parent, so consumers can look up edges by relationship in either direction without building their own index. Refs #138 --- src/space-graph.ts | 24 +++++++++++++++++++++ tests/space-graph.test.ts | 44 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/src/space-graph.ts b/src/space-graph.ts index 12774d4b..f34b7716 100644 --- a/src/space-graph.ts +++ b/src/space-graph.ts @@ -1,5 +1,11 @@ import type { Hierarchy, NodeId, ResolvedParentRef, SpaceNode } from './types'; +/** A typed edge between two nodes: a node's resolvedParents entry, with both ends named. */ +export type SpaceEdge = Omit & { + parent: NodeId; + child: NodeId; +}; + /** * A navigable graph over a set of SpaceNodes. * @@ -28,6 +34,12 @@ export type SpaceGraph = { /** All-edges children map: parent id → direct children connected via any edge (hierarchy + relationship). */ readonly children: ReadonlyMap; + /** Parent edges: child id → edges to its parents (hierarchy + relationship), in resolvedParents order. */ + readonly parentEdges: ReadonlyMap; + + /** Child edges: parent id → edges to its children (hierarchy + relationship). */ + readonly childEdges: ReadonlyMap; + /** Set of all node ids that are part of the hierarchy (roots + their descendants + orphans). */ readonly hierarchyIds: ReadonlySet; @@ -45,6 +57,8 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef const nodesMap = new Map(); const hierarchyChildrenMap = new Map(); const childrenMap = new Map(); + const parentEdgesMap = new Map(); + const childEdgesMap = new Map(); const hierarchyRoots: SpaceNode[] = []; const orphans: SpaceNode[] = []; @@ -55,11 +69,19 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef nodesMap.set(node.id, node); hierarchyChildrenMap.set(node.id, []); childrenMap.set(node.id, []); + parentEdgesMap.set(node.id, []); + childEdgesMap.set(node.id, []); } // Second pass: build children maps (inverted from resolvedParents) for (const node of nodes) { for (const parentRef of node.resolvedParents) { + const { id: parentId, ...edgeFields } = parentRef; + const edge: SpaceEdge = { parent: parentId, child: node.id, ...edgeFields }; + parentEdgesMap.get(node.id)!.push(edge); + if (!childEdgesMap.has(parentId)) childEdgesMap.set(parentId, []); + childEdgesMap.get(parentId)!.push(edge); + // All-edges map if (!childrenMap.has(parentRef.id)) childrenMap.set(parentRef.id, []); childrenMap.get(parentRef.id)!.push(node); @@ -121,6 +143,8 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef nonHierarchy, hierarchyChildren: hierarchyChildrenMap, children: childrenMap, + parentEdges: parentEdgesMap, + childEdges: childEdgesMap, hierarchyIds, hierarchy, }; diff --git a/tests/space-graph.test.ts b/tests/space-graph.test.ts index 0254c454..14ffbd2c 100644 --- a/tests/space-graph.test.ts +++ b/tests/space-graph.test.ts @@ -123,6 +123,50 @@ describe('buildSpaceGraph', () => { }); }); + describe('parentEdges and childEdges', () => { + it('indexes each resolvedParents entry as a typed edge in both directions', () => { + const goal = makeNode('My Goal', 'goal'); + const opp = makeNode('An Opportunity', 'opportunity'); + opp.resolvedParents = [ + makeParentRef('My Goal'), + makeParentRef('My Goal', { kind: 'relationship', field: 'related' }), + ]; + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); + + const edges = graph.parentEdges.get('An Opportunity' as NodeId); + expect(edges as unknown).toEqual([ + { + parent: 'My Goal', + child: 'An Opportunity', + field: 'parent', + kind: 'hierarchy', + hierarchy: 'main', + selfRef: false, + fieldOn: 'child', + }, + { + parent: 'My Goal', + child: 'An Opportunity', + field: 'related', + kind: 'relationship', + selfRef: false, + fieldOn: 'child', + }, + ]); + expect(graph.childEdges.get('My Goal' as NodeId)).toEqual(edges!); + expect(graph.parentEdges.get('My Goal' as NodeId)).toEqual([]); + expect(graph.childEdges.get('An Opportunity' as NodeId)).toEqual([]); + }); + + it('keeps edges to parents not in the node set', () => { + const opp = makeNode('An Opportunity', 'opportunity'); + opp.resolvedParents = [makeParentRef('Missing Goal')]; + const graph = buildSpaceGraph([opp], makeHierarchy(levels)); + expect(graph.parentEdges.get('An Opportunity' as NodeId)?.[0]?.parent).toBe('Missing Goal' as NodeId); + expect(graph.childEdges.get('Missing Goal' as NodeId)?.[0]?.child).toBe('An Opportunity' as NodeId); + }); + }); + describe('hierarchyIds', () => { it('includes hierarchy roots and their descendants', () => { const goal = makeNode('My Goal', 'goal'); From 38e0982f663d48da6e4e2dbef20f1852de1f3d79 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 22:32:53 +1100 Subject: [PATCH 3/6] feat(graph): space graph format with exportSpaceGraph and spaceGraphFrom SpaceGraphData carries a space's nodes and every hierarchy as plain JSON, so a graph can cross a process or network boundary. Edges stay in each node's resolvedParents, including edges to nodes outside an exported subset; the receiver picks the hierarchy when it builds the SpaceGraph. - exportSpaceGraph(nodes, metadata) and spaceGraphFrom(data, { hierarchy }) - structured-context/browser: browser-safe entry point for the graph functions and node types; /api re-exports them - sctx dump --graph prints SpaceGraphData - JSON Schema generated to schemas/generated/space-graph/, frozen per released formatVersion; a typecheck fails if schema and type drift Closes #138 --- AGENTS.md | 4 +- README.md | 2 +- docs/api.md | 32 +++ docs/concepts.md | 4 + package.json | 4 + plugin/.claude-plugin/plugin.json | 2 +- .../structured-context/references/commands.md | 7 +- schemas/generated/space-graph/latest.json | 216 ++++++++++++++++++ scripts/generate-schema-meta.ts | 33 ++- scripts/test-package.sh | 8 + src/api.ts | 5 +- src/browser.ts | 25 ++ src/commands/dump.ts | 6 +- src/index.ts | 1 + src/load-space-graph.ts | 18 +- src/schema/metadata-contract.ts | 4 +- src/space-graph-data.ts | 180 +++++++++++++++ src/space-graph.ts | 19 +- tests/space-graph-data.test.ts | 130 +++++++++++ 19 files changed, 673 insertions(+), 27 deletions(-) create mode 100644 schemas/generated/space-graph/latest.json create mode 100644 src/browser.ts create mode 100644 src/space-graph-data.ts create mode 100644 tests/space-graph-data.test.ts diff --git a/AGENTS.md b/AGENTS.md index aea7fbbf..62aae03c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,7 @@ There are several places that need reviewing and updating with any new feature o - **Simplicity first:** Strive for the simplest design that completely solves the problem. Prefer conventions and established filesystem patterns over adding new configuration, programmatic APIs, or abstractions. - **Explicitly state alternatives:** When planning or making architectural decisions, do not anchor to the first familiar mechanism. Formulate and state at least one alternative approach, weighing trade-offs, complexity, and ergonomic impact. - **Minimise blast radius:** Protect established boundaries and interfaces. Treat unnecessary ripple effects (such as making synchronous APIs asynchronous or adding dual APIs) as a design smell indicating the approach should be re-evaluated. -- **Public API surface:** Do not add exports to `src/api.ts`, `src/types.ts` or `src/testing.ts` (the `structured-context/api`, `/types` and `/testing` entry points), or add types or hooks to the plugin interface, without the maintainer's explicit agreement on that specific surface. Exporting something to make docs complete, to tidy up, or because a feature has a public-looking class is not a reason. Agreement on a function covers that function only: its option and result types are separate exports, so derive them in the consumer (`Parameters`, `ReturnType`) instead. If a change seems to need a new export, stop and propose it, with the consumer that needs it. Internal modules can change freely. +- **Public API surface:** Do not add exports to `src/api.ts`, `src/browser.ts`, `src/types.ts` or `src/testing.ts` (the `structured-context/api`, `/browser`, `/types` and `/testing` entry points), or add types or hooks to the plugin interface, without the maintainer's explicit agreement on that specific surface. Exporting something to make docs complete, to tidy up, or because a feature has a public-looking class is not a reason. Agreement on a function covers that function only: its option and result types are separate exports, so derive them in the consumer (`Parameters`, `ReturnType`) instead. If a change seems to need a new export, stop and propose it, with the consumer that needs it. Internal modules can change freely. - **Where a setting lives:** Config says *what* to use, CLI flags override it for one run, and the environment holds secrets and the config location only (`apiKeyEnv` names a secret; `SCTX_CONFIG` locates the config). Do not add env vars that set config values, and never infer a choice (such as a judge provider) from a variable that happens to be set: a key present for another tool must not be spent silently. Config also never switches on costly or outward-facing behaviour (such as semantic judging): each run asks for it, through a flag or an API option. - **Reuse types:** Derive a type from the real one (`Pick`, `Partial`) instead of restating its shape. Keep CLI wording (flags, commands) out of library errors and the public API; the CLI adds its own hint. Once a feature has many files, give it a directory. Comments explain why, never restate the code. - **Failures are visible:** A rule or expression that cannot be evaluated is reported as a violation, never skipped or treated as a pass. Likewise a misconfiguration fails before any work or spend. @@ -71,6 +71,8 @@ There are several places that need reviewing and updating with any new feature o ## Key Files - `src/api.ts` — Public library entry point (`structured-context/api`). Re-exports the supported programmatic surface. Keep CLI-only concerns out of it. Do not extend it without agreement (see **Public API surface** above). +- `src/browser.ts` — Browser-safe entry point (`structured-context/browser`): graph building and the space graph format. Nothing it imports may use Node built-ins; `/api` re-exports all of it. +- `src/space-graph-data.ts` — The space graph format: `SPACE_GRAPH_DATA_SCHEMA`, `SpaceGraphData` (a typecheck fails if the two drift), `exportSpaceGraph`, `spaceGraphFrom`. Bump `SPACE_GRAPH_FORMAT_VERSION` when the shape changes. It is generated to `schemas/generated/space-graph/` (`latest.json`, plus a frozen `.json` per release); generation fails if a released version's schema no longer matches. - `schemas/` — Bundled default schema files (JSON5) using the structured-context schema dialect and top-level `$metadata`. Files starting with `_` are "partials" (fragments for `$ref`). - `src/schema/metadata-contract.ts` — Single source of truth for the `$metadata` contract - `schemas/generated/latest/_structured_context_schema_meta.json` — Generated metaschema for the newest dialect (generated on build or with `bun run generate:schema-meta`). `schemas/generated//` folders are frozen copies, created by the `version` script (`generate:schema-meta --release`) only when a release changes the dialect; never edit them. `src/schema/meta-schemas.ts` loads them at runtime. diff --git a/README.md b/README.md index e7a5636d..68574e3b 100644 --- a/README.md +++ b/README.md @@ -237,7 +237,7 @@ Keeps Obsidian template files in sync with schema examples: ## Programmatic API The package exposes a library entry point at `structured-context/api` for embedding the tooling -in other applications. See +in other applications, and `structured-context/browser` for loading an exported space graph in a browser. See [docs/api.md](docs/api.md) for the full reference and usage examples. ## Development diff --git a/docs/api.md b/docs/api.md index 2774401f..bbcd54f2 100644 --- a/docs/api.md +++ b/docs/api.md @@ -18,6 +18,8 @@ see [architecture.md](architecture.md#information-flow) for that flow. | `loadSpaceGraph(spaceName, config, options?)` | Read, assemble, and optionally filter a space into a navigable `SpaceGraph`. `options.hierarchy` names the hierarchy that structures the graph (default: the main hierarchy). | | `assembleSpaceGraph(context, options?)` | Assemble (and optionally filter) a graph from a context you already hold — reuses the context instead of rebuilding it. | | `buildSpaceGraph(nodes, hierarchy?)` | Build a navigable `SpaceGraph` directly from an array of `SpaceNode`s and a `Hierarchy` definition. | +| `exportSpaceGraph(nodes, metadata)` | Turn nodes and the schema's hierarchies into `SpaceGraphData`, plain JSON for another process. See [Space graph format](#space-graph-format). | +| `spaceGraphFrom(data, options?)` | Build a `SpaceGraph` from `SpaceGraphData`. `options.hierarchy` names the hierarchy that structures it (default: the main hierarchy). | | `validateSpace(context, options?)` | Run full validation (schema, references, rules, duplicates) over a space. | | `validateFile(filePath, config)` | Validate a single file within its space. | | `listSchemas(options?)` | List the schemas available to a config: bundled, plugin-contributed and configured. | @@ -28,6 +30,36 @@ see [architecture.md](architecture.md#information-flow) for that flow. `ValidationResult.ruleViolations` carries each violation's effective `severity` (`error`, `warning` or `info`). Only `error` severity violations should be treated as failures; `validateFile` reports `warning` and `info` rule violations under `warnings` rather than `errors`. +A `SpaceGraph` classifies nodes against one hierarchy, and indexes child nodes and typed edges (`SpaceEdge`) in +both directions. + +## Space graph format + +`SpaceGraphData` is the [space graph format](concepts.md#space-graph-format): + +```jsonc +{ "formatVersion": 1, "hierarchies": [/* Hierarchy */], "mainHierarchy": "…", "nodes": [/* SpaceNode */] } +``` + +Edges are each node's `resolvedParents`. An exported subset keeps its edges to nodes outside the subset. The +receiver picks the hierarchy when it builds the graph. + +`structured-context/browser` exports the graph functions and node types, and imports no Node built-ins. +Everything in it is also exported from `structured-context/api`. + +```ts +// Server +const { nodes } = await readSpace(context); +const data = exportSpaceGraph(nodes, context.schema.metadata); // or graph.nodes.values() for a filtered graph + +// Browser +import { spaceGraphFrom } from 'structured-context/browser'; +const graph = spaceGraphFrom(data, { hierarchy: 'work' }); +``` + +`sctx dump --graph` prints the same data. A JSON Schema for the format ships at +`schemas/generated/space-graph/latest.json`, with a frozen copy per released `formatVersion`. + ## Testing utilities Test fixture builders are available via `structured-context/testing` for plugin and integration tests: diff --git a/docs/concepts.md b/docs/concepts.md index cbc91db6..ac29145a 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -325,6 +325,10 @@ Each entry is a `ResolvedParentRef` object: The `kind` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set. +### Space graph format + +The **space graph format** (`SpaceGraphData`) is a space's nodes and hierarchies as plain JSON. A program exports it on one side of a process or network boundary and builds a `SpaceGraph` from it on the other. See [api.md](api.md#space-graph-format). + ### Content links **Content links** (`resolvedLinks` on `SpaceNode`) are all links extracted from a node's content at parse time — both from frontmatter non-edge fields and from the body text. They are distinct from graph edges: they are never used to infer structure, but are available to consumers for rendering, auditing, or navigation. diff --git a/package.json b/package.json index 3c1375b7..31027baf 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,10 @@ "types": "./dist/api.d.ts", "default": "./dist/api.js" }, + "./browser": { + "types": "./dist/browser.d.ts", + "default": "./dist/browser.js" + }, "./types": { "types": "./dist/types.d.ts", "default": "./dist/types.js" diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 833cead5..c0054dfe 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.16.4", + "version": "0.16.5", "description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", diff --git a/plugin/skills/structured-context/references/commands.md b/plugin/skills/structured-context/references/commands.md index 6ea8f688..3a7f55b3 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -111,17 +111,20 @@ The SELECT spec is a comma-separated list of directives that expand the result s ## dump ```bash -sctx dump [--filter ] [--hierarchy ] +sctx dump [--filter ] [--hierarchy ] [--graph] ``` Outputs `{ nodes, source, diagnostics }` as strict JSON. Each node includes resolved fields: - `id` — unique node key; for a page it is the path `validate --json` uses for its `errors` map - `title`, `resolvedType` — display title and type after alias resolution -- `resolvedParents` — parent refs after link resolution, with the edge field and source +- `resolvedParents` — parent refs after link resolution, with the edge field and kind Unfiltered output includes schema-invalid nodes. `--filter` works the same as in `show`/`render` (named view or inline expression, evaluated over the schema-valid graph). +`--graph` outputs the space graph format instead: the nodes plus every hierarchy, for a program to load +(see "Space graph format" in `sctx docs concepts`). + Use this to debug rule violations ("why is this rule firing?"), verify `fieldMap` remapping is working, or inspect what JSONata expressions see at evaluation time. diff --git a/schemas/generated/space-graph/latest.json b/schemas/generated/space-graph/latest.json new file mode 100644 index 00000000..65d55d87 --- /dev/null +++ b/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 +} diff --git a/scripts/generate-schema-meta.ts b/scripts/generate-schema-meta.ts index 77cdce9f..11ee539f 100644 --- a/scripts/generate-schema-meta.ts +++ b/scripts/generate-schema-meta.ts @@ -1,9 +1,15 @@ import { execSync } from 'node:child_process'; -import { existsSync } from 'node:fs'; +import { existsSync, readFileSync } from 'node:fs'; import { mkdir, writeFile } from 'node:fs/promises'; import pkg from '../package.json'; import { readNewestMetaSchema } from '../src/schema/meta-schemas'; import { buildDialectMetaSchema, SCHEMA_META_FILE, schemaMetaId } from '../src/schema/metadata-contract'; +import { + SPACE_GRAPH_DATA_SCHEMA, + SPACE_GRAPH_FORMAT_VERSION, + SPACE_GRAPH_SCHEMA_DIR, + spaceGraphSchemaId, +} from '../src/space-graph-data'; const GENERATED_DIR = new URL('../schemas/generated/', import.meta.url); @@ -32,12 +38,37 @@ export async function writeMetaSchemas(generatedDir: URL, version: string, relea return folders; } +/** + * Write the space graph format schema to `space-graph/latest.json`. With `release`, also freeze it as + * `space-graph/.json`. Throws when the schema differs from an already frozen file for the same version. + */ +export async function writeSpaceGraphSchema(generatedDir: URL, release: boolean): Promise { + const dir = new URL(`${SPACE_GRAPH_SCHEMA_DIR}/`, generatedDir); + const version = String(SPACE_GRAPH_FORMAT_VERSION); + const schema = { $id: spaceGraphSchemaId(version), ...SPACE_GRAPH_DATA_SCHEMA }; + const frozen = new URL(`${version}.json`, dir); + if (existsSync(frozen) && JSON.stringify(JSON.parse(readFileSync(frozen, 'utf-8'))) !== JSON.stringify(schema)) { + throw new Error( + `The space graph format changed after version ${version} was released. Bump SPACE_GRAPH_FORMAT_VERSION.`, + ); + } + + const files = ['latest', ...(release && !existsSync(frozen) ? [version] : [])]; + await mkdir(dir, { recursive: true }); + for (const file of files) { + await writeFile(new URL(`${file}.json`, dir), `${JSON.stringify(schema, null, 2)}\n`); + } + return files; +} + if (import.meta.main) { const release = process.argv.includes('--release'); const folders = await writeMetaSchemas(GENERATED_DIR, pkg.version, release); + const graphFiles = await writeSpaceGraphSchema(GENERATED_DIR, release); execSync(`bunx biome check --config-path=. --write ${GENERATED_DIR.pathname}`, { cwd: new URL('..', import.meta.url).pathname, stdio: 'inherit', }); console.log(`Generated schema metadata: ${folders.join(', ')}`); + console.log(`Generated space graph schema: ${graphFiles.join(', ')}`); } diff --git a/scripts/test-package.sh b/scripts/test-package.sh index ae9a7e71..cefb250e 100755 --- a/scripts/test-package.sh +++ b/scripts/test-package.sh @@ -25,4 +25,12 @@ sctx=node_modules/.bin/sctx "$sctx" plugins >/dev/null "$sctx" docs concepts >/dev/null "$sctx" validate smoke >/dev/null +"$sctx" dump smoke --graph >graph.json +cat >browser.mjs <<'EOF2' +import { readFileSync } from 'node:fs'; +import { spaceGraphFrom } from 'structured-context/browser'; +const graph = spaceGraphFrom(JSON.parse(readFileSync('graph.json', 'utf-8'))); +if (graph.nodes.size === 0) throw new Error('empty graph from structured-context/browser'); +EOF2 +bun browser.mjs echo "package ok" diff --git a/src/api.ts b/src/api.ts index 75d15254..d1244c31 100644 --- a/src/api.ts +++ b/src/api.ts @@ -57,7 +57,8 @@ export { listSchemas } from './schema/list-schemas'; export type { SharedEmbeddingFields } from './schema/metadata-contract'; export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema'; export { createSpaceContext, SpaceNotFoundError } from './space-context'; -export { buildSpaceGraph, type SpaceGraph } from './space-graph'; +export { buildSpaceGraph, type SpaceEdge, type SpaceGraph } from './space-graph'; +export { exportSpaceGraph, type SpaceGraphData, spaceGraphFrom } from './space-graph-data'; export type { BaseNode, ContentLink, @@ -67,10 +68,12 @@ export type { FileValidationResult, Hierarchy, HierarchyLevel, + NodeId, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, + ResolvedParentRef, RuleCategory, RuleSeverity, RuleViolation, diff --git a/src/browser.ts b/src/browser.ts new file mode 100644 index 00000000..80195335 --- /dev/null +++ b/src/browser.ts @@ -0,0 +1,25 @@ +// Public entry point: do not add exports without the maintainer's agreement (AGENTS.md, "Public API surface"). +/** + * Browser-safe API for structured-context: nothing here imports Node built-ins. + * + * Rebuild a graph that a server exported with exportSpaceGraph (or `sctx dump --graph`): + * + * import { spaceGraphFrom } from 'structured-context/browser'; + * const graph = spaceGraphFrom(await (await fetch('/graph.json')).json()); + * + * Everything here is also exported from `structured-context/api`. + */ + +export { buildSpaceGraph, type SpaceEdge, type SpaceGraph } from './space-graph'; +export { exportSpaceGraph, type SpaceGraphData, spaceGraphFrom } from './space-graph-data'; +export type { + BaseNode, + ContentLink, + Hierarchy, + HierarchyLevel, + NodeId, + ResolvedContentLink, + ResolvedParentRef, + SourceLocation, + SpaceNode, +} from './types'; diff --git a/src/commands/dump.ts b/src/commands/dump.ts index d18658a3..722a6334 100644 --- a/src/commands/dump.ts +++ b/src/commands/dump.ts @@ -1,5 +1,6 @@ import { assembleSpaceGraph } from '../load-space-graph'; import { readSpace } from '../read/read-space'; +import { exportSpaceGraph } from '../space-graph-data'; import type { ReadSpaceResult, SpaceContext } from '../types'; export interface DumpOptions { @@ -7,6 +8,8 @@ export interface DumpOptions { filter?: string; /** Hierarchy used when evaluating the filter (default: the main hierarchy). */ hierarchy?: string; + /** Emit SpaceGraphData (nodes plus every hierarchy) instead of nodes, source and diagnostics. */ + graph?: boolean; } /** @@ -26,5 +29,6 @@ export async function buildDump(context: SpaceContext, options: DumpOptions = {} export async function dump(context: SpaceContext, options: DumpOptions = {}) { const { nodes, source, diagnostics } = await buildDump(context, options); - console.log(JSON.stringify({ nodes, source, diagnostics }, null, 2)); + const output = options.graph ? exportSpaceGraph(nodes, context.schema.metadata) : { nodes, source, diagnostics }; + console.log(JSON.stringify(output, null, 2)); } diff --git a/src/index.ts b/src/index.ts index bf789f2c..3c9adbea 100755 --- a/src/index.ts +++ b/src/index.ts @@ -153,6 +153,7 @@ program .argument('', 'Space name') .option('--filter ', 'Filter view name (from config) or inline filter expression') .option('--hierarchy ', '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 diff --git a/src/load-space-graph.ts b/src/load-space-graph.ts index 93d340cc..cd671d24 100644 --- a/src/load-space-graph.ts +++ b/src/load-space-graph.ts @@ -2,8 +2,8 @@ import type { Config } from './config'; import { filterNodes } from './filter/filter-nodes'; import { readSpace } from './read/read-space'; import { createSpaceContext } from './space-context'; -import { buildSpaceGraph, type SpaceGraph } from './space-graph'; -import type { Hierarchy, ReadSpaceResult, SchemaMetadata, SpaceContext, SpaceNode } from './types'; +import { buildSpaceGraph, type SpaceGraph, selectHierarchy } from './space-graph'; +import type { ReadSpaceResult, SpaceContext, SpaceNode } from './types'; export interface AssembleSpaceGraphOptions { /** Named view (resolved via space.views) or a raw filter DSL expression. */ @@ -46,20 +46,6 @@ export async function assembleSpaceGraph( return graph; } -/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */ -function selectHierarchy(metadata: SchemaMetadata, name: string | undefined): Hierarchy | undefined { - 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; -} - export interface LoadSpaceGraphOptions extends AssembleSpaceGraphOptions { /** * Directory to anchor relative plugin paths against. Required when config is diff --git a/src/schema/metadata-contract.ts b/src/schema/metadata-contract.ts index b4fee0dc..5e577b44 100644 --- a/src/schema/metadata-contract.ts +++ b/src/schema/metadata-contract.ts @@ -16,14 +16,14 @@ export function schemaMetaId(folder: string): string { 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' }, } as const; /** 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 } }, diff --git a/src/space-graph-data.ts b/src/space-graph-data.ts new file mode 100644 index 00000000..79dc31aa --- /dev/null +++ b/src/space-graph-data.ts @@ -0,0 +1,180 @@ +import type { FromSchema } from 'json-schema-to-ts'; +import { EDGE_PROPS, EMBEDDING_PROPS, SCHEMA_META_BASE_URL } from './schema/metadata-contract'; +import { buildSpaceGraph, type SpaceGraph, selectHierarchy } from './space-graph'; +import type { Hierarchy, NodeId, SchemaMetadata, SpaceNode } from './types'; + +/** 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: string): string { + return `${SCHEMA_META_BASE_URL}/${SPACE_GRAPH_SCHEMA_DIR}/${file}.json`; +} + +const STRING = { type: 'string' } as const; + +const SOURCE_LOCATION_SCHEMA = { + type: 'object', + properties: { file: STRING, line: { type: 'integer' }, column: { type: 'integer' } }, + required: ['file'], + additionalProperties: false, +} as const; + +const CONTENT_LINK_PROPS = { + text: STRING, + target: STRING, + action: { enum: ['link', 'embed'] }, + anchor: STRING, +} as const; + +const CONTENT_LINK_SCHEMA = { + type: 'object', + properties: { ...CONTENT_LINK_PROPS, linkSyntax: { enum: ['wikilink', 'markdown'] } }, + required: ['text', 'target', 'action', 'linkSyntax'], + additionalProperties: false, +} as const; + +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, +} as const; + +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, +} as const; + +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, +} as const; + +/** 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, +} as const; + +const HIERARCHY_SCHEMA = { + type: 'object', + properties: { + name: STRING, + levels: { type: 'array', items: HIERARCHY_LEVEL_SCHEMA }, + allowSkipLevels: { type: 'boolean' }, + }, + required: ['name', 'levels'], + additionalProperties: false, +} as const; + +/** 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, +} as const; + +/** + * 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 function exportSpaceGraph( + nodes: Iterable, + metadata: Pick, +): SpaceGraphData { + 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: SpaceGraphData, options: { hierarchy?: string } = {}): SpaceGraph { + 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)); +} + +/** Replaces branded ids with plain strings, the shape JSON Schema can describe. */ +type Unbranded = T extends NodeId + ? string + : T extends readonly (infer U)[] + ? Unbranded[] + : T extends object + ? { [K in keyof T]: Unbranded } + : T; + +type SchemaShape = FromSchema; + +/** Exact type equality: optional properties and modifiers must match too, not just assignability. */ +type Equals = (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false; + +// Fails typecheck when SPACE_GRAPH_DATA_SCHEMA and SpaceGraphData drift apart. +const _schemaMatchesType: Equals> = true; +void _schemaMatchesType; diff --git a/src/space-graph.ts b/src/space-graph.ts index f34b7716..f1b823d5 100644 --- a/src/space-graph.ts +++ b/src/space-graph.ts @@ -1,4 +1,4 @@ -import type { Hierarchy, NodeId, ResolvedParentRef, 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 & { @@ -149,3 +149,20 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef hierarchy, }; } + +/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */ +export function selectHierarchy( + metadata: Pick, + name: string | undefined, +): Hierarchy | undefined { + 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; +} diff --git a/tests/space-graph-data.test.ts b/tests/space-graph-data.test.ts new file mode 100644 index 00000000..0739d230 --- /dev/null +++ b/tests/space-graph-data.test.ts @@ -0,0 +1,130 @@ +import { afterEach, beforeEach, describe, expect, it } from 'bun:test'; +import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { pathToFileURL } from 'node:url'; +import Ajv2020 from 'ajv/dist/2020'; +import { writeSpaceGraphSchema } from '../scripts/generate-schema-meta'; +import { buildDump } from '../src/commands/dump'; +import { readSpace } from '../src/read/read-space'; +import { bundledSchemasDir } from '../src/schema/schema'; +import { buildSpaceGraph, selectHierarchy } from '../src/space-graph'; +import { + exportSpaceGraph, + SPACE_GRAPH_FORMAT_VERSION, + type SpaceGraphData, + spaceGraphFrom, + spaceGraphSchemaId, +} from '../src/space-graph-data'; +import type { SpaceContext } from '../src/types'; +import { makeSpaceContext } from './helpers/context'; + +const MULTI_DIR = join(import.meta.dir, 'fixtures/multi-hierarchy'); +const multiContext = makeSpaceContext(join(MULTI_DIR, 'space'), join(MULTI_DIR, 'selected-root.json')); +const ostContext = makeSpaceContext( + join(import.meta.dir, 'fixtures/general/valid-ost'), + join(bundledSchemasDir, 'strategy_general.json'), +); + +/** Export through JSON text, as a server would send it. */ +const overTheWire = (data: SpaceGraphData): SpaceGraphData => JSON.parse(JSON.stringify(data)); + +async function exported(context: SpaceContext): Promise { + const { nodes } = await readSpace(context); + return overTheWire(exportSpaceGraph(nodes, context.schema.metadata)); +} + +describe('exportSpaceGraph and spaceGraphFrom', () => { + it('round-trips to the graph buildSpaceGraph builds, for every hierarchy', async () => { + for (const context of [ostContext, multiContext]) { + const { nodes } = await readSpace(context); + const data = await exported(context); + const { metadata } = context.schema; + for (const name of [undefined, ...(metadata.hierarchies ?? []).map((h) => h.name)]) { + expect(spaceGraphFrom(data, { hierarchy: name })).toEqual( + buildSpaceGraph(nodes, selectHierarchy(metadata, name)), + ); + } + } + }); + + it('carries every hierarchy and names the main one', async () => { + const data = await exported(multiContext); + expect(data.formatVersion).toBe(SPACE_GRAPH_FORMAT_VERSION); + expect(data.hierarchies.map((h) => h.name).sort()).toEqual(['_skills-pack', 'work']); + expect(data.mainHierarchy).toBe(multiContext.schema.metadata.hierarchy?.name); + }); + + it('keeps edges to nodes outside an exported subset', async () => { + const { nodes } = await readSpace(multiContext); + const subset = nodes.filter((n) => n.resolvedType === 'task'); + const data = overTheWire(exportSpaceGraph(subset, multiContext.schema.metadata)); + expect(spaceGraphFrom(data)).toEqual(buildSpaceGraph(subset, multiContext.schema.metadata.hierarchy)); + const graph = spaceGraphFrom(data); + expect([...graph.childEdges.keys()].some((id) => !graph.nodes.has(id))).toBe(true); + }); + + it('throws on an unknown hierarchy or format version', async () => { + const data = await exported(multiContext); + expect(() => spaceGraphFrom(data, { hierarchy: 'nope' })).toThrow('Unknown hierarchy: "nope"'); + expect(() => spaceGraphFrom({ ...data, formatVersion: 2 } as unknown as SpaceGraphData)).toThrow( + 'Unsupported space graph format version 2', + ); + }); + + it('produces data the generated schema accepts', async () => { + const schema = JSON.parse(readFileSync(join(bundledSchemasDir, 'generated/space-graph/latest.json'), 'utf-8')); + const validate = new Ajv2020({ strict: false }).compile(schema); + for (const context of [ostContext, multiContext]) { + const data = await exported(context); + expect(validate(data), JSON.stringify(validate.errors)).toBe(true); + } + }); +}); + +describe('sctx dump --graph', () => { + it('emits the exported nodes of a filtered dump', async () => { + const { nodes } = await buildDump(multiContext, { filter: "resolvedType='task'" }); + const data = exportSpaceGraph(nodes, multiContext.schema.metadata); + expect(data.nodes.map((n) => n.resolvedType)).toEqual(['task']); + }); +}); + +describe('browser entry point', () => { + it('bundles for the browser without Node built-ins', async () => { + const result = await Bun.build({ entrypoints: [join(import.meta.dir, '../src/browser.ts')], target: 'browser' }); + expect(result.success).toBe(true); + const code = await result.outputs[0]!.text(); + expect(code).not.toMatch(/from ["']node:|require\(["']node:/); + }); +}); + +describe('writeSpaceGraphSchema', () => { + let dir: string; + beforeEach(() => { + dir = mkdtempSync(join(tmpdir(), 'sctx-graph-schema-')); + }); + afterEach(() => { + rmSync(dir, { recursive: true, force: true }); + }); + const generatedUrl = () => pathToFileURL(`${dir}/`); + const version = String(SPACE_GRAPH_FORMAT_VERSION); + const graphDir = () => join(dir, 'space-graph'); + + it('writes only latest outside a release', async () => { + expect(await writeSpaceGraphSchema(generatedUrl(), false)).toEqual(['latest']); + expect(readdirSync(graphDir())).toEqual(['latest.json']); + expect(JSON.parse(readFileSync(join(graphDir(), 'latest.json'), 'utf-8')).$id).toBe(spaceGraphSchemaId(version)); + }); + + it('freezes the current format version on release, once', async () => { + expect(await writeSpaceGraphSchema(generatedUrl(), true)).toEqual(['latest', version]); + expect(await writeSpaceGraphSchema(generatedUrl(), true)).toEqual(['latest']); + }); + + it('refuses to proceed when a released version no longer matches', async () => { + await writeSpaceGraphSchema(generatedUrl(), true); + writeFileSync(join(graphDir(), `${version}.json`), '{"changed": true}'); + expect(writeSpaceGraphSchema(generatedUrl(), false)).rejects.toThrow('Bump SPACE_GRAPH_FORMAT_VERSION'); + }); +}); From 37f316f165079aac4f9436189f87d6adc7d5e68d Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 22:37:17 +1100 Subject: [PATCH 4/6] Add MIT license --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..c5bc8e5f --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Roger Barnes + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From 058cb44ff7f5e943435d70a1137faebda070bdd0 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 22:42:10 +1100 Subject: [PATCH 5/6] refactor(api): trim graph exports to what consumers need /browser exports spaceGraphFrom with the SpaceGraph and SpaceNode types; /api re-exports them from /browser and adds exportSpaceGraph. Other types are derived from these. Refs #138 --- AGENTS.md | 2 +- docs/api.md | 15 ++++++++------- docs/concepts.md | 2 +- src/api.ts | 8 +++----- src/browser.ts | 19 +++++-------------- 5 files changed, 18 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 62aae03c..0e079662 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,7 +71,7 @@ There are several places that need reviewing and updating with any new feature o ## Key Files - `src/api.ts` — Public library entry point (`structured-context/api`). Re-exports the supported programmatic surface. Keep CLI-only concerns out of it. Do not extend it without agreement (see **Public API surface** above). -- `src/browser.ts` — Browser-safe entry point (`structured-context/browser`): graph building and the space graph format. Nothing it imports may use Node built-ins; `/api` re-exports all of it. +- `src/browser.ts` — Browser-safe entry point (`structured-context/browser`): rebuilding a graph from the space graph format. Nothing it imports may use Node built-ins; `/api` re-exports all of it. - `src/space-graph-data.ts` — The space graph format: `SPACE_GRAPH_DATA_SCHEMA`, `SpaceGraphData` (a typecheck fails if the two drift), `exportSpaceGraph`, `spaceGraphFrom`. Bump `SPACE_GRAPH_FORMAT_VERSION` when the shape changes. It is generated to `schemas/generated/space-graph/` (`latest.json`, plus a frozen `.json` per release); generation fails if a released version's schema no longer matches. - `schemas/` — Bundled default schema files (JSON5) using the structured-context schema dialect and top-level `$metadata`. Files starting with `_` are "partials" (fragments for `$ref`). - `src/schema/metadata-contract.ts` — Single source of truth for the `$metadata` contract diff --git a/docs/api.md b/docs/api.md index bbcd54f2..245c16fe 100644 --- a/docs/api.md +++ b/docs/api.md @@ -18,8 +18,8 @@ see [architecture.md](architecture.md#information-flow) for that flow. | `loadSpaceGraph(spaceName, config, options?)` | Read, assemble, and optionally filter a space into a navigable `SpaceGraph`. `options.hierarchy` names the hierarchy that structures the graph (default: the main hierarchy). | | `assembleSpaceGraph(context, options?)` | Assemble (and optionally filter) a graph from a context you already hold — reuses the context instead of rebuilding it. | | `buildSpaceGraph(nodes, hierarchy?)` | Build a navigable `SpaceGraph` directly from an array of `SpaceNode`s and a `Hierarchy` definition. | -| `exportSpaceGraph(nodes, metadata)` | Turn nodes and the schema's hierarchies into `SpaceGraphData`, plain JSON for another process. See [Space graph format](#space-graph-format). | -| `spaceGraphFrom(data, options?)` | Build a `SpaceGraph` from `SpaceGraphData`. `options.hierarchy` names the hierarchy that structures it (default: the main hierarchy). | +| `exportSpaceGraph(nodes, metadata)` | Turn nodes and the schema's hierarchies into plain JSON for another process. See [Space graph format](#space-graph-format). | +| `spaceGraphFrom(data, options?)` | Build a `SpaceGraph` from that JSON. `options.hierarchy` names the hierarchy that structures it (default: the main hierarchy). | | `validateSpace(context, options?)` | Run full validation (schema, references, rules, duplicates) over a space. | | `validateFile(filePath, config)` | Validate a single file within its space. | | `listSchemas(options?)` | List the schemas available to a config: bundled, plugin-contributed and configured. | @@ -30,12 +30,12 @@ see [architecture.md](architecture.md#information-flow) for that flow. `ValidationResult.ruleViolations` carries each violation's effective `severity` (`error`, `warning` or `info`). Only `error` severity violations should be treated as failures; `validateFile` reports `warning` and `info` rule violations under `warnings` rather than `errors`. -A `SpaceGraph` classifies nodes against one hierarchy, and indexes child nodes and typed edges (`SpaceEdge`) in -both directions. +A `SpaceGraph` classifies nodes against one hierarchy, and indexes child nodes and typed edges in both +directions. ## Space graph format -`SpaceGraphData` is the [space graph format](concepts.md#space-graph-format): +`exportSpaceGraph` returns the [space graph format](concepts.md#space-graph-format): ```jsonc { "formatVersion": 1, "hierarchies": [/* Hierarchy */], "mainHierarchy": "…", "nodes": [/* SpaceNode */] } @@ -44,8 +44,9 @@ both directions. Edges are each node's `resolvedParents`. An exported subset keeps its edges to nodes outside the subset. The receiver picks the hierarchy when it builds the graph. -`structured-context/browser` exports the graph functions and node types, and imports no Node built-ins. -Everything in it is also exported from `structured-context/api`. +`structured-context/browser` exports `spaceGraphFrom` with the `SpaceGraph` and `SpaceNode` types, and imports no +Node built-ins. Everything in it is also exported from `structured-context/api`. Derive other types from these, +such as `Parameters[0]` for the data. ```ts // Server diff --git a/docs/concepts.md b/docs/concepts.md index ac29145a..7a6af543 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -327,7 +327,7 @@ The `kind` and `hierarchy` labels let downstream consumers distinguish edge type ### Space graph format -The **space graph format** (`SpaceGraphData`) is a space's nodes and hierarchies as plain JSON. A program exports it on one side of a process or network boundary and builds a `SpaceGraph` from it on the other. See [api.md](api.md#space-graph-format). +The **space graph format** is a space's nodes and hierarchies as plain JSON. A program exports it on one side of a process or network boundary and builds a `SpaceGraph` from it on the other. See [api.md](api.md#space-graph-format). ### Content links diff --git a/src/api.ts b/src/api.ts index d1244c31..f1b632c1 100644 --- a/src/api.ts +++ b/src/api.ts @@ -20,6 +20,7 @@ */ export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv'; +export { type SpaceGraph, type SpaceNode, spaceGraphFrom } from './browser'; export type { Config, SpaceConfig } from './config'; export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config'; export { addSpace } from './config/write'; @@ -57,8 +58,8 @@ export { listSchemas } from './schema/list-schemas'; export type { SharedEmbeddingFields } from './schema/metadata-contract'; export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema'; export { createSpaceContext, SpaceNotFoundError } from './space-context'; -export { buildSpaceGraph, type SpaceEdge, type SpaceGraph } from './space-graph'; -export { exportSpaceGraph, type SpaceGraphData, spaceGraphFrom } from './space-graph-data'; +export { buildSpaceGraph } from './space-graph'; +export { exportSpaceGraph } from './space-graph-data'; export type { BaseNode, ContentLink, @@ -68,12 +69,10 @@ export type { FileValidationResult, Hierarchy, HierarchyLevel, - NodeId, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, - ResolvedParentRef, RuleCategory, RuleSeverity, RuleViolation, @@ -81,7 +80,6 @@ export type { SchemaWithMetadata, SourceLocation, SpaceContext, - SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types'; diff --git a/src/browser.ts b/src/browser.ts index 80195335..be68efb7 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -7,19 +7,10 @@ * import { spaceGraphFrom } from 'structured-context/browser'; * const graph = spaceGraphFrom(await (await fetch('/graph.json')).json()); * - * Everything here is also exported from `structured-context/api`. + * Everything here is also exported from `structured-context/api`. Derive other types from these, e.g. + * `Parameters[0]` for the exported data or `SpaceNode['id']` for a node id. */ -export { buildSpaceGraph, type SpaceEdge, type SpaceGraph } from './space-graph'; -export { exportSpaceGraph, type SpaceGraphData, spaceGraphFrom } from './space-graph-data'; -export type { - BaseNode, - ContentLink, - Hierarchy, - HierarchyLevel, - NodeId, - ResolvedContentLink, - ResolvedParentRef, - SourceLocation, - SpaceNode, -} from './types'; +export type { SpaceGraph } from './space-graph'; +export { spaceGraphFrom } from './space-graph-data'; +export type { SpaceNode } from './types'; From 154788d04e4b9a58dcc8abb62bc7a0355cfc76cc Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 27 Oct 2026 23:05:59 +1100 Subject: [PATCH 6/6] docs: tighten space graph format wording after doc review --- docs/api.md | 10 +++++----- src/browser.ts | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api.md b/docs/api.md index 245c16fe..333fd96f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -44,9 +44,9 @@ directions. Edges are each node's `resolvedParents`. An exported subset keeps its edges to nodes outside the subset. The receiver picks the hierarchy when it builds the graph. -`structured-context/browser` exports `spaceGraphFrom` with the `SpaceGraph` and `SpaceNode` types, and imports no -Node built-ins. Everything in it is also exported from `structured-context/api`. Derive other types from these, -such as `Parameters[0]` for the data. +`structured-context/browser` holds what a browser needs to load the data, and imports no Node built-ins. +Everything in it is also exported from `structured-context/api`. Derive other types from its exports, such as +`Parameters[0]` for the data. ```ts // Server @@ -58,8 +58,8 @@ import { spaceGraphFrom } from 'structured-context/browser'; const graph = spaceGraphFrom(data, { hierarchy: 'work' }); ``` -`sctx dump --graph` prints the same data. A JSON Schema for the format ships at -`schemas/generated/space-graph/latest.json`, with a frozen copy per released `formatVersion`. +`sctx dump --graph` prints the same data. The JSON Schema for each released +`formatVersion` ships in `schemas/generated/space-graph/`, named by version, and `latest.json` is the newest. ## Testing utilities diff --git a/src/browser.ts b/src/browser.ts index be68efb7..15a7114a 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -2,7 +2,7 @@ /** * Browser-safe API for structured-context: nothing here imports Node built-ins. * - * Rebuild a graph that a server exported with exportSpaceGraph (or `sctx dump --graph`): + * Rebuild a graph that a server exported with exportSpaceGraph: * * import { spaceGraphFrom } from 'structured-context/browser'; * const graph = spaceGraphFrom(await (await fetch('/graph.json')).json());