diff --git a/AGENTS.md b/AGENTS.md index aea7fbb..0e07966 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`): 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 - `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/LICENSE b/LICENSE new file mode 100644 index 0000000..c5bc8e5 --- /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. diff --git a/README.md b/README.md index e7a5636..68574e3 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 2774401..333fd96 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 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. | @@ -28,6 +30,37 @@ 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 in both +directions. + +## Space graph format + +`exportSpaceGraph` returns 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` 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 +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. The JSON Schema for each released +`formatVersion` ships in `schemas/generated/space-graph/`, named by version, and `latest.json` is the newest. + ## 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 6d27b34..7a6af54 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -319,11 +319,15 @@ 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. + +### 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 @@ -386,7 +390,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/package.json b/package.json index 3c1375b..31027ba 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 666285a..c0054df 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.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 298b64d..3a7f55b 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: @@ -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 0000000..65d55d8 --- /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 77cdce9..11ee539 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 ae9a7e7..cefb250 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 75d1525..f1b632c 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,7 +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 SpaceGraph } from './space-graph'; +export { buildSpaceGraph } from './space-graph'; +export { exportSpaceGraph } from './space-graph-data'; export type { BaseNode, ContentLink, @@ -78,7 +80,6 @@ export type { SchemaWithMetadata, SourceLocation, SpaceContext, - SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types'; diff --git a/src/browser.ts b/src/browser.ts new file mode 100644 index 0000000..15a7114 --- /dev/null +++ b/src/browser.ts @@ -0,0 +1,16 @@ +// 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: + * + * import { spaceGraphFrom } from 'structured-context/browser'; + * const graph = spaceGraphFrom(await (await fetch('/graph.json')).json()); + * + * 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 type { SpaceGraph } from './space-graph'; +export { spaceGraphFrom } from './space-graph-data'; +export type { SpaceNode } from './types'; diff --git a/src/commands/dump.ts b/src/commands/dump.ts index d18658a..722a633 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/filter/augment-nodes.ts b/src/filter/augment-nodes.ts index ced9434..20fb4dc 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 27d6aec..c6aec94 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/index.ts b/src/index.ts index bf789f2..3c9adbe 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/judge/context.ts b/src/judge/context.ts index 35c5cf1..0e7df80 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/load-space-graph.ts b/src/load-space-graph.ts index 93d340c..cd671d2 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/plugins/markdown/parse-embedded.ts b/src/plugins/markdown/parse-embedded.ts index 9a475c0..f8b2c58 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 6feb606..f542613 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 5796eee..d288bb7 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 9b50ed7..d97b22a 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/metadata-contract.ts b/src/schema/metadata-contract.ts index b4fee0d..5e577b4 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/schema/validate-graph.ts b/src/schema/validate-graph.ts index 9838c11..c4195f9 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-data.ts b/src/space-graph-data.ts new file mode 100644 index 0000000..79dc31a --- /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 7de0860..f1b823d 100644 --- a/src/space-graph.ts +++ b/src/space-graph.ts @@ -1,4 +1,10 @@ -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 & { + 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; @@ -40,11 +52,13 @@ 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(); 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,7 +143,26 @@ export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undef nonHierarchy, hierarchyChildren: hierarchyChildrenMap, children: childrenMap, + parentEdges: parentEdgesMap, + childEdges: childEdgesMap, hierarchyIds, 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/src/testing.ts b/src/testing.ts index f496092..e4e0e7e 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 d7c7c30..9501968 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 1ee34ff..3417ae3 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 4e53d60..ba2b2b1 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 cf740b1..c753064 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 09b2a99..14a99cc 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-data.test.ts b/tests/space-graph-data.test.ts new file mode 100644 index 0000000..0739d23 --- /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'); + }); +}); diff --git a/tests/space-graph.test.ts b/tests/space-graph.test.ts index f303652..14ffbd2 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); @@ -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');