From a5316256ef5f0e2fe2712d3fb771a812effc176a Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sat, 26 Sep 2026 17:55:42 +1000 Subject: [PATCH 1/2] Multiple hierarchies via schema composition Every $ref'd schema now contributes its declared hierarchy as a separate named hierarchy instead of the last provider winning. - $metadata.hierarchy gains an optional `name` (default: declaring file stem) and may be `{ "$ref": "#/$metadata/hierarchy" }` on the root to select the main hierarchy - main hierarchy: root-declared, else the single contributed one, else the root's $ref selection; several contributed with none selected is an error, as is declaring and selecting at once - a type in two hierarchies, or two hierarchies with the same name, is an error - layering, parent-type, skip-level and orphan checks run per hierarchy - hierarchy edges in resolvedParents carry the hierarchy name - show/diagram/render take --hierarchy (default: main hierarchy) - SchemaMetadata gains `hierarchies`; SpaceGraph.levels becomes SpaceGraph.hierarchy; buildSpaceGraph takes a Hierarchy Closes #121 Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi --- README.md | 29 +++- docs/api.md | 2 +- docs/concepts.md | 12 +- docs/schema-dialect-update-proposal.md | 4 +- docs/schemas.md | 45 ++++- plugin/.claude-plugin/plugin.json | 2 +- plugin/skills/structured-context/SKILL.md | 2 +- .../structured-context/references/commands.md | 9 +- .../references/schema-authoring.md | 7 +- .../references/schema-design.md | 5 + schemas/_strategy_general.json | 4 +- .../_structured_context_schema_meta.json | 135 ++++++++------- schemas/strategy_general.json | 2 +- src/api.ts | 1 + src/commands/diagram.ts | 10 +- src/commands/render.ts | 4 +- src/commands/schemas.ts | 17 +- src/commands/show.ts | 7 +- src/filter/augment-nodes.ts | 22 ++- src/filter/filter-nodes.ts | 2 +- src/index.ts | 3 + src/load-space-graph.ts | 25 ++- src/plugins/markdown/extract-content-links.ts | 8 +- src/plugins/mermaid/render-mermaid.ts | 3 +- src/plugins/miro/sync.ts | 13 +- src/read/resolve-graph-edges.ts | 129 +++++++++------ src/render/render.ts | 4 +- src/schema/metadata-contract.ts | 41 +++-- src/schema/schema.ts | 155 +++++++++++++----- src/schema/validate-graph.ts | 57 ++++--- src/space-graph.ts | 24 +-- src/types.ts | 18 +- src/validate.ts | 6 +- tests/filter/augment-nodes.test.ts | 2 +- tests/filter/expand-include.test.ts | 2 +- tests/filter/filter-nodes.test.ts | 4 +- .../multi-hierarchy/_skills-pack.json | 47 ++++++ .../fixtures/multi-hierarchy/_work-pack.json | 42 +++++ .../multi-hierarchy/declare-and-ref-root.json | 24 +++ .../multi-hierarchy/declared-root.json | 54 ++++++ .../multi-hierarchy/selected-root.json | 23 +++ .../single-contributed-root.json | 12 ++ .../multi-hierarchy/space/Engineering.md | 3 + .../fixtures/multi-hierarchy/space/Ship v2.md | 3 + .../fixtures/multi-hierarchy/space/Testing.md | 4 + .../multi-hierarchy/space/Write docs.md | 4 + .../multi-hierarchy/unselected-root.json | 18 ++ ...parse-embedded-hierarchy-embedding.test.ts | 29 ++-- .../parse-embedded-relationships.test.ts | 24 +-- .../relationship-embedded-nodes.test.ts | 4 +- tests/read/content-links.test.ts | 3 +- tests/read/resolve-hierarchy-edges.test.ts | 34 ++-- tests/render/render-bullets.test.ts | 14 +- tests/render/render-hierarchy.test.ts | 36 ++++ tests/render/render-mermaid.test.ts | 16 +- tests/schema/schema-composition.test.ts | 72 +++++++- tests/schema/validate-graph.test.ts | 97 ++++++++--- tests/space-graph.test.ts | 43 ++--- tests/test-helpers.ts | 42 ++++- tests/validate/general.test.ts | 8 +- tests/validate/relationships.test.ts | 10 +- 61 files changed, 1080 insertions(+), 401 deletions(-) create mode 100644 tests/fixtures/multi-hierarchy/_skills-pack.json create mode 100644 tests/fixtures/multi-hierarchy/_work-pack.json create mode 100644 tests/fixtures/multi-hierarchy/declare-and-ref-root.json create mode 100644 tests/fixtures/multi-hierarchy/declared-root.json create mode 100644 tests/fixtures/multi-hierarchy/selected-root.json create mode 100644 tests/fixtures/multi-hierarchy/single-contributed-root.json create mode 100644 tests/fixtures/multi-hierarchy/space/Engineering.md create mode 100644 tests/fixtures/multi-hierarchy/space/Ship v2.md create mode 100644 tests/fixtures/multi-hierarchy/space/Testing.md create mode 100644 tests/fixtures/multi-hierarchy/space/Write docs.md create mode 100644 tests/fixtures/multi-hierarchy/unselected-root.json create mode 100644 tests/render/render-hierarchy.test.ts diff --git a/README.md b/README.md index d167fd9..dd55729 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,7 @@ Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a With `fieldOn: "parent"`, embedded child nodes (parsed from a matching heading's list or table) are appended as wikilinks to the parent's `field` array, rather than receiving a `parent` field. This matches schemas where the content model naturally lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`). Metadata is composable across `$ref` graphs: -- `hierarchy`: multiple schema files may define a hierarchy; **last one wins** (root schema overrides partials) +- `hierarchy`: each schema file declares at most one hierarchy, and every declared hierarchy is kept as a separate named hierarchy (see [Multiple hierarchies](#multiple-hierarchies)) - `aliases` are shallow-merged (later wins) - `rules` merge by `id`; conflicts error unless the later rule sets `override: true` - each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it @@ -193,6 +193,24 @@ Metadata is composable across `$ref` graphs: If no file defines `hierarchy`, hierarchy-specific checks are skipped. +#### Multiple hierarchies + +A space can have several hierarchies by composing schemas that each declare one. For example, a root schema might compose a work hierarchy (`goal → task`) and a skills hierarchy (`skill_area → skill`). + +- **Naming**: a hierarchy's `name` defaults to the declaring schema's file stem (e.g. `_skills` for `_skills.json`). Set `"name"` in `$metadata.hierarchy` to override it. +- **Main hierarchy**: if the root schema declares a hierarchy, it is the main one. If the root declares none and exactly one is composed, that one is the main hierarchy. If several are composed, the root must select one: + + ```json5 + "$metadata": { + "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" } + } + ``` + + A root may either declare a hierarchy or select one with `$ref`, not both. +- **Each type belongs to at most one hierarchy.** A type in two hierarchies is an error, so a composing schema cannot redefine a composed hierarchy's levels. +- **Validation** (layering, parent types, skip levels, orphans) runs per hierarchy. Relationships can connect types across hierarchies. +- The main hierarchy drives `space_on_a_page` parsing, hierarchy embedding, `template-sync`, and the default `show`/`diagram`/`render` output. Use `--hierarchy ` to render another one. + **Customizing Schemas:** - **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`). - **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content. @@ -224,10 +242,10 @@ Validates markdown files against the JSON schema: ### Show space tree ```bash -sctx show [--filter ] +sctx show [--filter ] [--hierarchy ] ``` -Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes. +Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes. The main hierarchy is shown by default; `--hierarchy ` selects another (see [Multiple hierarchies](#multiple-hierarchies)). `diagram` and `render` accept the same option. When a node appears under multiple parents (DAG hierarchy), it is printed in full under its first parent. Subsequent appearances with children show a `(*)` marker indicating the subtree is omitted. @@ -259,6 +277,7 @@ The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression - **`ancestors[]`** — flat array of ancestor nodes, nearest first, deduplicated. Each entry includes all schema fields of the ancestor node, plus: - `_field` — the edge field name that connects to the ancestor - `_source` — `'hierarchy'` or `'relationship'` + - `_hierarchy` — the hierarchy name, for hierarchy edges - `_selfRef` — whether the edge is a same-type (self-referential) link - **`descendants[]`** — same structure, for descendant nodes @@ -309,7 +328,7 @@ SELECT relationships(assumption) WHERE resolvedType='opportunity' ### Generate Mermaid diagram ```bash -sctx diagram [--output path/to/output.mmd] +sctx diagram [--output path/to/output.mmd] [--hierarchy ] ``` Generates a Mermaid `graph TD` diagram from validated space nodes: @@ -326,7 +345,7 @@ sctx schemas show [--mermaid-erd] [--space ] Generates a Mermaid Entity Relationship Diagram from a schema: - Shows all entity types and their properties -- Displays parent-child relationships based on hierarchy metadata +- Displays parent-child relationships based on the levels of each hierarchy - Useful for visualizing schema structure during development Example: diff --git a/docs/api.md b/docs/api.md index fcc2297..d8578e8 100644 --- a/docs/api.md +++ b/docs/api.md @@ -11,7 +11,7 @@ see [architecture.md](architecture.md#information-flow) for that flow. | `loadConfig()` | Load the resolved config (spaces, schemas) from the standard config locations. | | `createSpaceContext(spaceName, config)` | Build a `SpaceContext` for a named space. Throws `SpaceNotFoundError` on an unknown name. | | `readSpace(context)` | Read a space into a flat `ReadSpaceResult` (`nodes`, `parseIssues`, `diagnostics`, `source`). | -| `loadSpaceGraph(spaceName, config, options?)` | Read, assemble, and optionally filter a space into a navigable `SpaceGraph`. | +| `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. | | `validateSpace(context, options?)` | Run full validation (schema, references, rules, duplicates) over a space. | | `validateFile(filePath, config)` | Validate a single file within its space. | diff --git a/docs/concepts.md b/docs/concepts.md index 721849b..c87dceb 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -123,7 +123,7 @@ A **schema** defines the valid structure for nodes in a `space`: the fields, typ The schema handles structural validation. Cross-node and workflow checks are handled by executable `rules` defined in `$metadata.rules`. -Schemas are composable: structural definitions and metadata can be sourced across `$ref` graphs, then merged deterministically (root metadata applied last, single hierarchy provider, aliases merged, rules merged by `id` with explicit override semantics). +Schemas are composable: structural definitions and metadata can be sourced across `$ref` graphs, then merged deterministically (root metadata applied last, each declared hierarchy kept as a separate named hierarchy, aliases merged, rules merged by `id` with explicit override semantics). ### Rules @@ -162,6 +162,10 @@ The **hierarchy** is the ordered list of node types in a space, from root to lea The hierarchy is modelled as a layered DAG: a non-root node may have zero parents (orphaned), one parent, or multiple parents. The `show` command renders this as an indented tree, marking repeated nodes with `(*)` where the subtree is already shown elsewhere. +A space may have **several hierarchies**, one for each composed schema that declares one. Each hierarchy has a **name** (defaulting to the declaring schema's file stem), and each type belongs to at most one hierarchy. Structural validation runs per hierarchy; relationships may connect types across hierarchies. + +The **main hierarchy** is the one declared by the root schema; failing that, the only composed hierarchy; failing that, the one the root selects with `"hierarchy": { "$ref": ... }`. The main hierarchy drives `space on a page` parsing, hierarchy embedding, template sync, and default rendering. `show`, `diagram` and `render` take `--hierarchy ` to render another. See [docs/schemas.md](schemas.md#multiple-hierarchies). + Each non-root level uses the shared `field`, `fieldOn`, and `multiple` edge options (see [Graph edges](#graph-edges)). Hierarchy-specific options: | Option | Default | Meaning | @@ -252,9 +256,10 @@ Each entry is a `ResolvedParentRef` object: | `title` | `string` | The parent node's title | | `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'` | | `selfRef` | `boolean` | Whether the edge is a same-type (self-referential) parent link | -The `source` label lets downstream consumers distinguish edge types without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks (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 `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. ### Content links @@ -317,7 +322,8 @@ 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 the hierarchy or a relationship | +| `_source` | `'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 | ### SELECT spec diff --git a/docs/schema-dialect-update-proposal.md b/docs/schema-dialect-update-proposal.md index 486f07f..52aa4cb 100644 --- a/docs/schema-dialect-update-proposal.md +++ b/docs/schema-dialect-update-proposal.md @@ -167,7 +167,7 @@ Metadata merge behavior is implicit and fragile. Define deterministic merge rules in this update: - Metadata sources: traverse `$ref` graph from root schema (DFS), then apply root schema metadata last. -- `hierarchy`: exactly one provider allowed; error if multiple providers define it. +- `hierarchy`: exactly one provider allowed; error if multiple providers define it. *(Superseded: as implemented, the last provider won; since #121 each provider's hierarchy is kept as a separate named hierarchy. See [schemas.md](schemas.md#multiple-hierarchies).)* - `aliases`: shallow merge by key; later provider wins. - `rules`: concatenate, then dedupe by `id`; later provider wins on conflict. - Validation: fail fast on duplicate rule ids with incompatible payload unless override is explicit. @@ -443,7 +443,7 @@ Stage B acceptance criteria: ### Stage C - Composability and merge semantics - [x] Implement metadata collection across `$ref` graph (DFS) with root metadata applied last. -- [x] Enforce single-provider hierarchy (error on multiple providers). +- [x] ~~Enforce single-provider hierarchy (error on multiple providers).~~ Superseded by multiple named hierarchies (#121). - [x] Implement aliases merge (shallow merge, later provider wins). - [x] Implement rules merge by `id` with conflict policy: - [x] default conflict is error; diff --git a/docs/schemas.md b/docs/schemas.md index 4fe4475..3c98860 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -120,7 +120,8 @@ Top-level metadata shape: | Field | Type | Notes | |---|---|---| -| `hierarchy` | object | Optional per provider; at most one provider may define it after composition | +| `hierarchy` | object | Optional; declares this schema's hierarchy, or (root schema only) selects the main hierarchy with `{ "$ref": "#/$metadata/hierarchy" }`. See [Multiple hierarchies](#multiple-hierarchies) | +| `hierarchy.name` | `string` | Optional short name; defaults to the declaring schema's file stem | | `hierarchy.levels` | `(string \| HierarchyLevel)[]` | Ordered root→leaf types | | `hierarchy.allowSkipLevels` | `boolean` | Optional; allows parent to be any ancestor level | | `relationships` | `Relationship[]` | Optional; defines related node links outside the primary hierarchy | @@ -258,7 +259,7 @@ Metadata is composed across the `$ref` graph with deterministic behavior: 2. Apply root schema metadata last. Merge rules: -- `hierarchy`: may be defined in partials; **last one wins**. This allows partials to define a default hierarchy that composing schemas can override. +- `hierarchy`: not merged. Each declared hierarchy is kept as a separate named hierarchy (see below). - `aliases`: shallow merged; later file wins per key. - `relationships`: collected from all files; order preserved. - `rules`: merged by `id`. @@ -267,6 +268,46 @@ Merge rules: When no provider defines `hierarchy`, hierarchy-based behavior is disabled (`show` tree shape, hierarchy validation, parent-edge checks). `space_on_a_page` parsing still requires hierarchy and will error without it. +### Multiple hierarchies + +A space has several hierarchies when its schema composes several schemas that each declare one. Each schema declares at most one hierarchy. + +- **Every `$ref`'d schema contributes its hierarchy.** Each is kept as a separate named hierarchy; levels are never merged. +- **Naming.** `hierarchy.name` defaults to the declaring schema's file stem (`_ost_strict` for `_ost_strict.json`). Names must be unique. +- **Main hierarchy.** + - If the root schema declares a hierarchy, it is the main hierarchy. + - If the root declares none and exactly one hierarchy is contributed, that one is the main hierarchy (for example `strict_ost`, whose hierarchy comes from `_ost_strict`). + - If the root declares none and several are contributed, the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }`, otherwise loading the schema fails. + - A root that both declares a hierarchy and uses `$ref` is an error. +- **Each type belongs to at most one hierarchy.** A type claimed by two hierarchies is an error. A composing schema therefore cannot redefine the levels of a hierarchy it composes; it declares a hierarchy over its own types instead. +- **Selections are not contributed.** A `hierarchy: { "$ref" }` selection only applies when its schema is the root, so a composed schema stays usable standalone as another space's root. + +```json5 +{ + "$id": "sctx://team", + "oneOf": [ + { "$ref": "sctx://_work#/$defs/goal" }, + { "$ref": "sctx://_work#/$defs/task" }, + { "$ref": "sctx://_skills#/$defs/skill_area" }, + { "$ref": "sctx://_skills#/$defs/skill" } + ], + "$metadata": { + // _work.json and _skills.json each declare a hierarchy; select the main one. + "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" } + } +} +``` + +How hierarchies are used: + +| Behaviour | Hierarchies used | +|---|---| +| Layering, parent-type, skip-level and orphan checks | Each hierarchy, independently. A hierarchy edge whose parent belongs to another hierarchy is an invalid parent. | +| Relationships | Connect types across hierarchies, as before | +| `space_on_a_page` parsing, hierarchy embedding, `template-sync` | Main hierarchy | +| `show`, `diagram`, `render` | Main hierarchy by default; `--hierarchy ` selects another | +| `resolvedParents` | Hierarchy edges carry the `hierarchy` name | + ### Rule imports via `$ref` Inside `$metadata.rules`, entries can be inline rules or `$ref` imports: diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 40e36b0..016af37 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.11.2", + "version": "0.11.3", "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/SKILL.md b/plugin/skills/structured-context/SKILL.md index 32efb9d..1cb308d 100644 --- a/plugin/skills/structured-context/SKILL.md +++ b/plugin/skills/structured-context/SKILL.md @@ -108,7 +108,7 @@ When writing or editing Obsidian markdown frontmatter: **Rule violations on every node of a type** — the rule may be too strict or misconfigured. Use `dump` to verify what the rule actually sees in the `current` object, then adjust the rule in the schema. -**`show`/`diagram` show only orphans and non-hierarchy types** — the schema's `$metadata.hierarchy` may not have edge configuration for the space's relationship fields. Use `schemas show --space ` to check the hierarchy definition. Each non-root level can define a `field` entry (overriding default `parent:` field (and optionally `fieldOn: "parent"` / `multiple: true`) to wire up the correct relationship field. +**`show`/`diagram` show only orphans and non-hierarchy types** — the schema's `$metadata.hierarchy` may not have edge configuration for the space's relationship fields, or the nodes may belong to another hierarchy (pass `--hierarchy `). Use `schemas show --space ` to check the hierarchy definition. Each non-root level can define a `field` entry (overriding default `parent:` field (and optionally `fieldOn: "parent"` / `multiple: true`) to wire up the correct relationship field. ## Troubleshooting Common Errors diff --git a/plugin/skills/structured-context/references/commands.md b/plugin/skills/structured-context/references/commands.md index 22ef32d..d5e467f 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -37,7 +37,7 @@ sctx validate --watch ## show ```bash -sctx show [--filter ] +sctx show [--filter ] [--hierarchy ] ``` Prints a hierarchical tree of all nodes, indented by parent→child relationships. Useful for @@ -49,6 +49,9 @@ If those are misconfigured for your content, output will appear flatter than exp **`--filter`** accepts either a named view from the space config (`views` key) or an inline filter expression. Only matching nodes are shown in the tree. +**`--hierarchy`** names the hierarchy to render when the schema composes several (default: the main +hierarchy). `schemas show --space ` lists the hierarchy names. `diagram` and `render` accept it too. + ```bash # Inline expression sctx show --filter "WHERE resolvedType='solution' and status='active'" @@ -63,7 +66,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`, `_selfRef` edge metadata +- `ancestors[]` — ancestor nodes nearest-first, each with `_field`, `_source`, `_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: @@ -100,7 +103,7 @@ sctx dump | jq '.[] | select(.title == "My Node Title")' ## diagram ```bash -sctx diagram [--output ] +sctx diagram [--output ] [--hierarchy ] ``` Generates a Mermaid `graph TD` diagram from space nodes. Nodes are colour-coded by type; diff --git a/plugin/skills/structured-context/references/schema-authoring.md b/plugin/skills/structured-context/references/schema-authoring.md index 9e9498a..22ec3b1 100644 --- a/plugin/skills/structured-context/references/schema-authoring.md +++ b/plugin/skills/structured-context/references/schema-authoring.md @@ -70,7 +70,10 @@ Rules are a flat array. Each rule's `category` (`validation`, `coherence`, `work Across `$ref` graphs: - metadata providers are traversed DFS, root metadata applied last -- zero or one provider may define `hierarchy` +- each schema declares at most one `hierarchy`; every composed schema's hierarchy is kept as a separate named hierarchy (`hierarchy.name`, default: the declaring file's stem) +- each type belongs to at most one hierarchy — a composing schema cannot redefine a composed hierarchy's levels +- main hierarchy: the root's own; else the only composed one; else the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }` (declaring and selecting at once is an error) +- the main hierarchy drives `space_on_a_page` parsing, embedding, `template-sync` and default rendering; validation runs per hierarchy - `aliases` shallow-merge (later wins) - `rules` merge by `id` - duplicate rule IDs with different payloads error unless later rule sets `override: true` @@ -173,7 +176,7 @@ Each node also carries convenience fields for common queries: - `resolvedParentTitle` — title of the first resolved parent (or `undefined`) - `resolvedParentTitles` — array of all resolved parent titles -`resolvedParents` on the raw node is an array of `ResolvedParentRef` objects (`{ title, field, source, selfRef }`); use the convenience fields for simple title-matching. +`resolvedParents` on the raw node is an array of `ResolvedParentRef` objects (`{ title, field, source, hierarchy?, selfRef }`, where `hierarchy` names the hierarchy of a hierarchy edge); use the convenience fields for simple title-matching. ```jsonata $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) diff --git a/plugin/skills/structured-context/references/schema-design.md b/plugin/skills/structured-context/references/schema-design.md index cc5544a..1d6d631 100644 --- a/plugin/skills/structured-context/references/schema-design.md +++ b/plugin/skills/structured-context/references/schema-design.md @@ -40,6 +40,11 @@ level object in `$metadata.hierarchy.levels`. For a mixed graph (some hierarchical, some lateral entities), put the main chain in `hierarchy.levels` and include lateral types in `oneOf` without hierarchy constraints. +If the content has a second, independent tree (e.g. a skills tree alongside a work hierarchy), declare +each tree's hierarchy in its own partial and compose both. Each type may belong to only one hierarchy; +if several are composed, the root selects the main one with +`"hierarchy": { "$ref": "#/$metadata/hierarchy" }`. Relationships can link the trees. + ### 2a. Adjacent Relationships vs Primary Hierarchy Use **Primary Hierarchy** (`$metadata.hierarchy`) for the main structural backbone of your tree. These links: diff --git a/schemas/_strategy_general.json b/schemas/_strategy_general.json index a38c3d7..39ad6cd 100644 --- a/schemas/_strategy_general.json +++ b/schemas/_strategy_general.json @@ -2,8 +2,8 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx://_strategy_general", // Shared entity definitions for strategy-general schemas. - // Provides a default hierarchy, aliases, relationships, and entity type $defs. - // Composing schemas can override the hierarchy by defining their own. + // Provides a hierarchy, aliases, relationships, and entity type $defs. + // Composing schemas contribute this hierarchy alongside any others they compose. "$metadata": { "hierarchy": { "levels": [ diff --git a/schemas/generated/_structured_context_schema_meta.json b/schemas/generated/_structured_context_schema_meta.json index cdd0ddb..4327ff9 100644 --- a/schemas/generated/_structured_context_schema_meta.json +++ b/schemas/generated/_structured_context_schema_meta.json @@ -14,72 +14,91 @@ "type": "object", "properties": { "hierarchy": { - "type": "object", - "properties": { - "levels": { - "type": "array", - "minItems": 1, - "items": { - "oneOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "minLength": 1 - }, - "field": { + "oneOf": [ + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "levels": { + "type": "array", + "minItems": 1, + "items": { + "oneOf": [ + { "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 + { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1 + }, + "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", + "minLength": 1 + } }, - "minItems": 1 - }, - "embeddedTemplateFields": { - "type": "array", - "items": { - "type": "string", - "minLength": 1 - } - }, - "selfRef": { - "type": "boolean" - }, - "selfRefField": { - "type": "string", - "minLength": 1 + "required": ["type"], + "additionalProperties": false } - }, - "required": ["type"], - "additionalProperties": false + ] } - ] - } + }, + "allowSkipLevels": { + "type": "boolean" + } + }, + "required": ["levels"], + "additionalProperties": false }, - "allowSkipLevels": { - "type": "boolean" + { + "type": "object", + "properties": { + "$ref": { + "type": "string", + "minLength": 1 + } + }, + "required": ["$ref"], + "additionalProperties": false } - }, - "required": ["levels"], - "additionalProperties": false + ] }, "relationships": { "type": "array", diff --git a/schemas/strategy_general.json b/schemas/strategy_general.json index e7a9a0f..266b260 100644 --- a/schemas/strategy_general.json +++ b/schemas/strategy_general.json @@ -2,7 +2,7 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx://strategy_general", "title": "Strategy and opportunity ladder", - "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Override the hierarchy in $metadata to customize the level structure.", + "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Its hierarchy is contributed by the partial.", "allOf": [{ "$ref": "sctx://_strategy_general" }], "oneOf": [ { "$ref": "sctx://_strategy_general#/$defs/dashboard" }, diff --git a/src/api.ts b/src/api.ts index b532e8b..13b0639 100644 --- a/src/api.ts +++ b/src/api.ts @@ -46,6 +46,7 @@ export type { FileNotInSpaceResult, FileValidationIssue, FileValidationResult, + Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, diff --git a/src/commands/diagram.ts b/src/commands/diagram.ts index 5da473c..f604a2c 100644 --- a/src/commands/diagram.ts +++ b/src/commands/diagram.ts @@ -2,8 +2,14 @@ import { writeFileSync } from 'node:fs'; import { executeRender } from '../render/render'; import type { SpaceContext } from '../types'; -export async function diagram(context: SpaceContext, options: { output?: string; filter?: string }): Promise { - const result = await executeRender('mermaid.graph', context, { filter: options.filter }); +export async function diagram( + context: SpaceContext, + options: { output?: string; filter?: string; hierarchy?: string }, +): Promise { + const result = await executeRender('mermaid.graph', context, { + filter: options.filter, + hierarchy: options.hierarchy, + }); if (options.output) { writeFileSync(options.output, result); console.log(`Mermaid diagram written to ${options.output}`); diff --git a/src/commands/render.ts b/src/commands/render.ts index 06f2321..d2d66ef 100644 --- a/src/commands/render.ts +++ b/src/commands/render.ts @@ -7,9 +7,9 @@ import type { SpaceContext } from '../types'; export async function render( context: SpaceContext, format: string, - options: { filter?: string; output?: string }, + options: { filter?: string; hierarchy?: string; output?: string }, ): Promise { - const result = await executeRender(format, context, { filter: options.filter }); + const result = await executeRender(format, context, { filter: options.filter, hierarchy: options.hierarchy }); if (options.output) { writeFileSync(options.output, result); console.error(`Written to ${options.output}`); diff --git a/src/commands/schemas.ts b/src/commands/schemas.ts index 8d0ef24..5be1ce0 100644 --- a/src/commands/schemas.ts +++ b/src/commands/schemas.ts @@ -91,9 +91,14 @@ function showDefs(defs: Record): void { } function showMetadata(metadata: SchemaMetadata): void { - if (metadata.hierarchy?.levels.length) { - const parts = metadata.hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type)); - console.log(`\nhierarchy: ${parts.join(' → ')}`); + const hierarchies = metadata.hierarchies ?? []; + if (hierarchies.length > 0) { + console.log(''); + for (const hierarchy of hierarchies) { + const parts = hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type)); + const main = hierarchy === metadata.hierarchy ? ' (main)' : ''; + console.log(`hierarchy "${hierarchy.name}"${main}: ${parts.join(' → ')}`); + } } else { console.log('\nhierarchy: (none)'); } @@ -154,8 +159,6 @@ function showRegistry(schemaPath: string, schemaRefRegistry: Map 0) { + // Generate relationships based on the levels of each hierarchy + for (const { levels: hierarchyLevels } of metadata.hierarchies ?? []) { for (let i = 0; i < hierarchyLevels.length - 1; i++) { const current = hierarchyLevels[i]; const next = hierarchyLevels[i + 1]; diff --git a/src/commands/show.ts b/src/commands/show.ts index e86611f..a9f00c2 100644 --- a/src/commands/show.ts +++ b/src/commands/show.ts @@ -1,8 +1,11 @@ import { executeRender } from '../render/render'; import type { SpaceContext } from '../types'; -export async function show(context: SpaceContext, options?: { filter?: string }) { - const result = await executeRender('markdown.bullets', context, { filter: options?.filter }); +export async function show(context: SpaceContext, options?: { filter?: string; hierarchy?: string }) { + const result = await executeRender('markdown.bullets', context, { + filter: options?.filter, + hierarchy: options?.hierarchy, + }); process.stdout.write(result); if (!result.endsWith('\n')) process.stdout.write('\n'); } diff --git a/src/filter/augment-nodes.ts b/src/filter/augment-nodes.ts index 7d7037b..1659f67 100644 --- a/src/filter/augment-nodes.ts +++ b/src/filter/augment-nodes.ts @@ -4,6 +4,8 @@ import type { ResolvedParentRef, SpaceNode } from '../types'; export type EdgeMetadata = { _field: string; _source: 'hierarchy' | 'relationship'; + /** Hierarchy name, present only for hierarchy edges. */ + _hierarchy?: string; _selfRef: boolean; }; @@ -15,6 +17,16 @@ export type AugmentedFlatNode = Record & { descendants: Array & EdgeMetadata>; }; +/** Edge metadata for the resolvedParents entry connecting two nodes. */ +function edgeMetadata(ref: ResolvedParentRef): EdgeMetadata { + return { + _field: ref.field, + _source: ref.source, + ...(ref.hierarchy !== undefined ? { _hierarchy: ref.hierarchy } : {}), + _selfRef: ref.selfRef, + }; +} + /** Flatten a SpaceNode's data fields for use in an augmented representation. */ function flattenData(node: SpaceNode): Record { return { @@ -31,7 +43,7 @@ function flattenData(node: SpaceNode): Record { * * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title. * - descendants: BFS via childrenIndex, nearest first, deduplicated by title. - * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _selfRef). + * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef). */ export function augmentNode( node: SpaceNode, @@ -73,9 +85,7 @@ function buildAncestors( result.push({ ...flattenData(item.node), - _field: item.ref.field, - _source: item.ref.source, - _selfRef: item.ref.selfRef, + ...edgeMetadata(item.ref), }); // Continue BFS upward @@ -115,9 +125,7 @@ function buildDescendants( result.push({ ...flattenData(item.childNode), - _field: item.ref.field, - _source: item.ref.source, - _selfRef: item.ref.selfRef, + ...edgeMetadata(item.ref), }); const grandchildren = childrenIndex.get(title) ?? []; diff --git a/src/filter/filter-nodes.ts b/src/filter/filter-nodes.ts index feca88f..0f38c1b 100644 --- a/src/filter/filter-nodes.ts +++ b/src/filter/filter-nodes.ts @@ -76,5 +76,5 @@ export async function filterNodes(expression: string, graph: SpaceGraph): Promis matchedNodes = matched; } - return buildSpaceGraph(matchedNodes, graph.levels); + return buildSpaceGraph(matchedNodes, graph.hierarchy); } diff --git a/src/index.ts b/src/index.ts index 5a29154..ead7a56 100755 --- a/src/index.ts +++ b/src/index.ts @@ -76,6 +76,7 @@ program .description('Generate mermaid diagram from space') .argument('', 'Space name') .option('--filter ', 'Filter view name (from config) or inline filter expression') + .option('--hierarchy ', 'Hierarchy to render (default: the main hierarchy)') .option('-o, --output ', 'Output file path (default: stdout)') .action((spaceName, options) => diagram(buildSpaceContext(spaceName), options)); @@ -84,6 +85,7 @@ program .description('Print space graph as a bullet list') .argument('', 'Space name') .option('--filter ', 'Filter view name (from config) or inline filter expression') + .option('--hierarchy ', 'Hierarchy to render (default: the main hierarchy)') .action((spaceName, options) => show(buildSpaceContext(spaceName), options)); program @@ -163,6 +165,7 @@ renderCmd .argument('', 'Space name') .argument('', 'Render format (e.g. markdown.bullets)') .option('--filter ', 'Filter view name (from config) or inline filter expression') + .option('--hierarchy ', 'Hierarchy to render (default: the main hierarchy)') .option('-o, --output ', 'Output file path (default: stdout)') .action(async (spaceName: string, format: string, options) => { await render(buildSpaceContext(spaceName), format, options); diff --git a/src/load-space-graph.ts b/src/load-space-graph.ts index 8d37e7a..93d340c 100644 --- a/src/load-space-graph.ts +++ b/src/load-space-graph.ts @@ -3,19 +3,21 @@ 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 { ReadSpaceResult, SpaceContext, SpaceNode } from './types'; +import type { Hierarchy, ReadSpaceResult, SchemaMetadata, SpaceContext, SpaceNode } from './types'; export interface AssembleSpaceGraphOptions { /** Named view (resolved via space.views) or a raw filter DSL expression. */ filter?: string; + /** Name of the hierarchy to structure the graph by. Defaults to the schema's main hierarchy. */ + hierarchy?: string; /** Pre-loaded read result to assemble from, avoiding a re-read of the space. */ readResult?: ReadSpaceResult; } /** * Assemble a SpaceGraph from a space context: read the space, drop nodes that - * fail schema validation, build the hierarchy graph, and apply an optional - * view/filter expression. + * fail schema validation, build the graph for the selected hierarchy (the main + * hierarchy by default), and apply an optional view/filter expression. * * Nodes that fail schema validation are silently excluded so the graph is * well-formed enough to render and traverse. This is NOT a validation pass — @@ -34,8 +36,7 @@ export async function assembleSpaceGraph( const { schemaValidator } = context; const validNodes: SpaceNode[] = allNodes.filter((node) => schemaValidator(node.schemaData)); - const levels = context.schema.metadata.hierarchy?.levels ?? []; - let graph = buildSpaceGraph(validNodes, levels); + let graph = buildSpaceGraph(validNodes, selectHierarchy(context.schema.metadata, options.hierarchy)); if (options.filter) { const expression = context.space.views?.[options.filter]?.expression ?? options.filter; @@ -45,6 +46,20 @@ 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/extract-content-links.ts b/src/plugins/markdown/extract-content-links.ts index 38212be..b8e73ab 100644 --- a/src/plugins/markdown/extract-content-links.ts +++ b/src/plugins/markdown/extract-content-links.ts @@ -121,9 +121,11 @@ export function extractLinksFromBody(body: string): ContentLink[] { */ export function getEdgeFieldNames(metadata: SchemaMetadata): Set { const fields = new Set(); - for (const level of metadata.hierarchy?.levels ?? []) { - fields.add(level.field); - if (level.selfRefField) fields.add(level.selfRefField); + for (const hierarchy of metadata.hierarchies ?? []) { + for (const level of hierarchy.levels) { + fields.add(level.field); + if (level.selfRefField) fields.add(level.selfRefField); + } } for (const rel of metadata.relationships ?? []) { fields.add(rel.field); diff --git a/src/plugins/mermaid/render-mermaid.ts b/src/plugins/mermaid/render-mermaid.ts index 9be958a..0297048 100644 --- a/src/plugins/mermaid/render-mermaid.ts +++ b/src/plugins/mermaid/render-mermaid.ts @@ -21,7 +21,8 @@ function safeNodeId(id: string): string { } export function renderMermaid(graph: SpaceGraph): string { - const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet, levels } = graph; + const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph; + const levels = graph.hierarchy?.levels ?? []; let mmd = 'graph TD\n'; diff --git a/src/plugins/miro/sync.ts b/src/plugins/miro/sync.ts index d25c3f0..4caa245 100644 --- a/src/plugins/miro/sync.ts +++ b/src/plugins/miro/sync.ts @@ -29,6 +29,7 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option throw new Error('No frameId in miro plugin config. Pass --new-frame "Title" to create one.'); // 3. Filter to hierarchy nodes only (graph already built by caller) + const levels = graph.hierarchy?.levels ?? []; const nodes = [...graph.nodes.values()].filter((n) => graph.hierarchyTitles.has(n.title)); if (nodes.length === 0) { @@ -45,7 +46,7 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option if (options.newFrame) { // Calculate layout bounds to size the frame appropriately - const { bounds } = layoutNewCards(nodes, new Map(), graph.levels); + const { bounds } = layoutNewCards(nodes, new Map(), levels); const frameWidth = Math.max(1600, bounds.maxX - bounds.minX); const frameHeight = Math.max(1200, bounds.maxY - bounds.minY); @@ -182,7 +183,7 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option } // Compute positions for new cards - const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, graph.levels); + const { positions: newPositions } = layoutNewCards(newNodes, existingPositions, levels); // 7. Create new cards let createdCount = 0; @@ -215,7 +216,7 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option title: buildCardTitle(node), description: buildCardDescription(node), }, - style: { cardTheme: getCardColor(type, graph.levels) }, + style: { cardTheme: getCardColor(type, levels) }, position: { x: pos.x, y: pos.y, origin: 'center' }, parent: { id: frameId }, geometry: { width: CARD_WIDTH }, @@ -264,7 +265,7 @@ export async function miroSync(context: PluginContext, graph: SpaceGraph, option title: buildCardTitle(node), description: buildCardDescription(node), }, - style: { cardTheme: getCardColor(type, graph.levels) }, + style: { cardTheme: getCardColor(type, levels) }, position: { x: 0, y: 0, origin: 'center' }, parent: { id: frameId }, geometry: { width: CARD_WIDTH }, @@ -290,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 { title: parentTitle, source } of node.resolvedParents) { - if (source !== 'hierarchy') continue; + for (const { title: parentTitle, source, hierarchy } of node.resolvedParents) { + if (source !== 'hierarchy' || hierarchy !== graph.hierarchy?.name) continue; // Both endpoints must have verified cards on the board if (verifiedCardIds.has(parentTitle) && verifiedCardIds.has(childTitle)) { const key = `${parentTitle}\u2192${childTitle}`; diff --git a/src/read/resolve-graph-edges.ts b/src/read/resolve-graph-edges.ts index 4f5169e..58e17a9 100644 --- a/src/read/resolve-graph-edges.ts +++ b/src/read/resolve-graph-edges.ts @@ -33,7 +33,8 @@ 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 source Whether this edge comes from hierarchy levels or relationships + * @param hierarchy Name of the hierarchy the edge belongs to (hierarchy edges only) * @param selfRef Whether child and parent are the same node type * @param unresolvedRefs Array to push broken/invalid link entries into * @param typeAliases Optional type aliases for resolution @@ -43,6 +44,7 @@ function resolveEdge( targetIndex: Map, edge: EdgeDefinition, source: ResolvedParentRef['source'], + hierarchy: string | undefined, selfRef: boolean, unresolvedRefs: UnresolvedRef[], typeAliases?: Record, @@ -55,7 +57,14 @@ function resolveEdge( function pushParentRef(childNode: SpaceNode, parentTitle: string): void { // Deduplicate by (field, title) — same parent via different fields is intentional if (!childNode.resolvedParents.some((r) => r.field === field && r.title === parentTitle)) { - childNode.resolvedParents.push({ title: parentTitle, field, fieldOn, source, selfRef }); + childNode.resolvedParents.push({ + title: parentTitle, + field, + fieldOn, + source, + ...(hierarchy !== undefined ? { hierarchy } : {}), + selfRef, + }); } } @@ -178,7 +187,7 @@ function classifyContentLink(link: ContentLink, targetIndex: Map 0) { - const parentLevel = levels[i - 1]!; - resolveEdge( - nodesByType, - targetIndex, - { - type: level.type, - parent: parentLevel.type, - field: level.field, - fieldOn: level.fieldOn, - multiple: level.multiple, - }, - 'hierarchy', - false, - unresolvedRefs, - typeAliases, - ); - } + // Regular relationship (child type → parent type) + if (i > 0) { + const parentLevel = levels[i - 1]!; + resolveEdge( + nodesByType, + targetIndex, + { + type: level.type, + parent: parentLevel.type, + field: level.field, + fieldOn: level.fieldOn, + multiple: level.multiple, + }, + 'hierarchy', + name, + false, + unresolvedRefs, + typeAliases, + ); + } - // Same-type relationship (child type → same type) via primary field - if (level.selfRef) { - resolveEdge( - nodesByType, - targetIndex, - { type: level.type, parent: level.type, field: level.field, fieldOn: level.fieldOn, multiple: level.multiple }, - 'hierarchy', - true, - unresolvedRefs, - typeAliases, - ); - } + // Same-type relationship (child type → same type) via primary field + if (level.selfRef) { + resolveEdge( + nodesByType, + targetIndex, + { + type: level.type, + parent: level.type, + field: level.field, + fieldOn: level.fieldOn, + multiple: level.multiple, + }, + 'hierarchy', + name, + true, + unresolvedRefs, + typeAliases, + ); + } - // Same-type relationship via explicit selfRefField - if (level.selfRefField) { - resolveEdge( - nodesByType, - targetIndex, - { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, - 'hierarchy', - true, - unresolvedRefs, - typeAliases, - ); + // Same-type relationship via explicit selfRefField + if (level.selfRefField) { + resolveEdge( + nodesByType, + targetIndex, + { type: level.type, parent: level.type, field: level.selfRefField, fieldOn: 'child', multiple: false }, + 'hierarchy', + name, + true, + unresolvedRefs, + typeAliases, + ); + } } } @@ -270,7 +290,16 @@ export function resolveGraphEdges( fieldOn: rel.fieldOn, multiple: rel.multiple, }; - resolveEdge(nodesByType, targetIndex, edge, 'relationship', rel.type === rel.parent, unresolvedRefs, typeAliases); + resolveEdge( + nodesByType, + targetIndex, + edge, + 'relationship', + undefined, + rel.type === rel.parent, + unresolvedRefs, + typeAliases, + ); } // 3. Resolve content links — classify each raw ContentLink into a ResolvedContentLink. diff --git a/src/render/render.ts b/src/render/render.ts index 6e1df3d..220ed9d 100644 --- a/src/render/render.ts +++ b/src/render/render.ts @@ -8,7 +8,7 @@ import { buildFormatRegistry } from './registry'; export async function executeRender( formatName: string, context: SpaceContext, - options: { filter?: string; data?: Record }, + options: { filter?: string; hierarchy?: string; data?: Record }, ): Promise { const pluginMap: Record> = context.space?.plugins ?? {}; const loaded = await loadPlugins(pluginMap, context.configDir); @@ -22,7 +22,7 @@ export async function executeRender( ); } - const graph = await assembleSpaceGraph(context, { filter: options.filter }); + const graph = await assembleSpaceGraph(context, { filter: options.filter, hierarchy: options.hierarchy }); const shortName = shortenPluginName(entry.plugin.plugin.name); const pluginContext = { diff --git a/src/schema/metadata-contract.ts b/src/schema/metadata-contract.ts index 9a97101..aa1a4a7 100644 --- a/src/schema/metadata-contract.ts +++ b/src/schema/metadata-contract.ts @@ -59,7 +59,7 @@ const RULE_SCHEMA = { additionalProperties: false, } as const; -const RULE_REF_SCHEMA = { +const REF_SCHEMA = { type: 'object', properties: { $ref: { type: 'string', minLength: 1 }, @@ -68,6 +68,23 @@ const RULE_REF_SCHEMA = { additionalProperties: false, } as const; +const HIERARCHY_SCHEMA = { + type: 'object', + properties: { + name: { type: 'string', minLength: 1 }, + levels: { + type: 'array', + minItems: 1, + items: { + oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA], + }, + }, + allowSkipLevels: { type: 'boolean' }, + }, + required: ['levels'], + additionalProperties: false, +} as const; + const RELATIONSHIP_SCHEMA = { type: 'object', properties: { @@ -83,20 +100,9 @@ const RELATIONSHIP_SCHEMA = { export const METADATA_SCHEMA = { type: 'object', properties: { + // Either declares this schema's hierarchy, or (root schema only) selects a contributed one via $ref. hierarchy: { - type: 'object', - properties: { - levels: { - type: 'array', - minItems: 1, - items: { - oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA], - }, - }, - allowSkipLevels: { type: 'boolean' }, - }, - required: ['levels'], - additionalProperties: false, + oneOf: [HIERARCHY_SCHEMA, REF_SCHEMA], }, relationships: { type: 'array', @@ -109,7 +115,7 @@ export const METADATA_SCHEMA = { rules: { type: 'array', items: { - oneOf: [RULE_SCHEMA, RULE_REF_SCHEMA], + oneOf: [RULE_SCHEMA, REF_SCHEMA], }, }, }, @@ -129,10 +135,11 @@ export const DIALECT_META_SCHEMA = { } as const; export type MetadataContract = FromSchema; +export type MetadataContractHierarchy = FromSchema; export type MetadataContractHierarchyLevel = FromSchema; export type MetadataContractRelationship = FromSchema; export type SharedEdgeFields = FromSchema; export type SharedEmbeddingFields = FromSchema; export type Rule = FromSchema; -export type RuleRef = FromSchema; -export type RuleEntry = Rule | RuleRef; +export type MetadataRef = FromSchema; +export type RuleEntry = Rule | MetadataRef; diff --git a/src/schema/schema.ts b/src/schema/schema.ts index 46f62f5..f61bc7f 100644 --- a/src/schema/schema.ts +++ b/src/schema/schema.ts @@ -1,15 +1,24 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'; -import { basename, dirname, join, resolve } from 'node:path'; +import { basename, dirname, extname, join, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; import { isDeepStrictEqual } from 'node:util'; import Ajv, { type AnySchemaObject, type ValidateFunction } from 'ajv'; import JSON5 from 'json5'; -import type { HierarchyLevel, RuleCategory, RuleSeverity, SchemaMetadata, SchemaWithMetadata } from '../types'; +import type { + Hierarchy, + HierarchyLevel, + RuleCategory, + RuleSeverity, + SchemaMetadata, + SchemaWithMetadata, +} from '../types'; import { DIALECT_META_SCHEMA, METADATA_SCHEMA, type MetadataContract, + type MetadataContractHierarchy, type MetadataContractRelationship, + type MetadataRef, type Rule, type RuleEntry, SCHEMA_META_ID, @@ -26,8 +35,13 @@ export function setBundledSchemasDir(dir: string): void { const validateMetadataContract = new Ajv().compile(METADATA_SCHEMA); +/** File stem of each schema read from disk — the default name of the hierarchy it declares. */ +const schemaFileStems = new WeakMap(); + export function readRawSchema(schemaPath: string): AnySchemaObject { - return JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8')) as AnySchemaObject; + const schema = JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8')) as AnySchemaObject; + schemaFileStems.set(schema, basename(schemaPath, extname(schemaPath))); + return schema; } /** @@ -52,8 +66,8 @@ function buildSchemaRegistry(dir: string, targetFile?: string): Map { const absPath = resolve(schemaPath); @@ -132,8 +146,13 @@ const RULE_ALLOWED_KEYS = new Set(['id', 'category', 'severity', 'description', function readTopLevelMetadata(schema: AnySchemaObject): MetadataContract | undefined { const metadata = schema.$metadata; if (!isObject(metadata)) return undefined; + const schemaId = typeof schema.$id === 'string' ? schema.$id : '(unknown schema)'; + if (isObject(metadata.hierarchy) && '$ref' in metadata.hierarchy && Object.keys(metadata.hierarchy).length > 1) { + throw new Error( + `Invalid $metadata in schema "${schemaId}": hierarchy both declares levels and selects a hierarchy with "$ref". Use one or the other.`, + ); + } if (!validateMetadataContract(metadata)) { - const schemaId = typeof schema.$id === 'string' ? schema.$id : '(unknown schema)'; const errors = validateMetadataContract.errors?.map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ') ?? 'unknown error'; @@ -142,7 +161,7 @@ function readTopLevelMetadata(schema: AnySchemaObject): MetadataContract | undef return metadata as MetadataContract; } -function resolveRefTargetForRule( +function resolveMetadataRef( ref: string, currentRootSchema: AnySchemaObject, schemaRefRegistry: Map, @@ -231,7 +250,7 @@ function collectMetadataProviders( return providers; } -function isRuleRefEntry(value: unknown): value is { $ref: string } { +function isRefEntry(value: unknown): value is MetadataRef { if (!isObject(value)) return false; return typeof value.$ref === 'string' && value.$ref.length > 0 && Object.keys(value).length === 1; } @@ -267,11 +286,11 @@ function resolveRuleEntries( return [ruleEntry]; } - if (!isRuleRefEntry(ruleEntry)) { + if (!isRefEntry(ruleEntry)) { throw new Error(`Invalid rule entry in metadata from "${provider.schemaId}".`); } - const target = resolveRefTargetForRule(ruleEntry.$ref, provider.schema, schemaRefRegistry); + const target = resolveMetadataRef(ruleEntry.$ref, provider.schema, schemaRefRegistry); if (stack.has(target.refKey)) { throw new Error( `Cyclic rule import detected while loading metadata from "${provider.schemaId}": ${[...stack, target.refKey].join( @@ -347,16 +366,26 @@ function areRulesEquivalent(left: Rule, right: Rule): boolean { function extractMetadata(schema: AnySchemaObject, schemaRefRegistry: Map): SchemaMetadata { const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry); - let mergedHierarchy: MetadataContract['hierarchy'] | undefined; + // Each declared hierarchy is kept as a separate named hierarchy, keyed by its declaring object + // so a root `hierarchy: { $ref }` selection can be matched to it. + const hierarchies = new Map(); + let mainHierarchy: Hierarchy | undefined; + let mainSelection: MetadataRef | undefined; const mergedAliases: Record = {}; const mergedRules = new Map(); const mergedRelationships: MetadataContractRelationship[] = []; for (const provider of metadataProviders) { - if (provider.metadata.hierarchy) { - // Later providers (including root schema) override earlier ones (e.g. partials). - // This allows partials to define a default hierarchy that composing schemas can override. - mergedHierarchy = provider.metadata.hierarchy; + const declaredHierarchy = provider.metadata.hierarchy; + const isRoot = provider.schema === schema; + if (isRefEntry(declaredHierarchy)) { + // A hierarchy selection only applies when its schema is the root; composed schemas contribute + // their declared hierarchies, not their selections. + if (isRoot) mainSelection = declaredHierarchy; + } else if (declaredHierarchy) { + const hierarchy = normalizeHierarchy(declaredHierarchy, provider); + hierarchies.set(declaredHierarchy, hierarchy); + if (isRoot) mainHierarchy = hierarchy; } if (provider.metadata.aliases) { @@ -392,18 +421,56 @@ function extractMetadata(schema: AnySchemaObject, schemaRefRegistry: Map#/$metadata/hierarchy".`, + ); + } + } else if (!mainHierarchy && allHierarchies.length === 1) { + mainHierarchy = allHierarchies[0]; + } else if (!mainHierarchy && allHierarchies.length > 1) { + const rootSchemaId = typeof schema.$id === 'string' ? schema.$id : '(root schema)'; + throw new Error( + `Schema "${rootSchemaId}" composes multiple hierarchies (${allHierarchies.map((h) => `"${h.name}"`).join(', ')}) but selects none as its main hierarchy. Declare one, or select one with "hierarchy": { "$ref": "#/$metadata/hierarchy" }.`, + ); + } + // Collect valid type names from the schema's oneOf list for validation const validTypeNames = extractSchemaTypeNames(schema as SchemaWithMetadata, schemaRefRegistry); // Validate and filter metadata references against valid type names - validateMetadataReferences({ mergedHierarchy, mergedAliases, mergedRules, mergedRelationships }, validTypeNames); + validateMetadataReferences({ allHierarchies, mergedAliases, mergedRules, mergedRelationships }, validTypeNames); // Filter relationships to only include those where both parent and child types are valid const filteredRelationships = mergedRelationships.filter((rel) => { return validTypeNames.has(rel.parent) && validTypeNames.has(rel.type); }); - const levels: HierarchyLevel[] | undefined = mergedHierarchy?.levels.map((entry) => { + return { + hierarchy: mainHierarchy, + hierarchies: allHierarchies.length > 0 ? allHierarchies : undefined, + typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined, + rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined, + relationships: + filteredRelationships.length > 0 + ? filteredRelationships.map((rel) => ({ + ...rel, + field: rel.field ?? 'parent', + fieldOn: rel.fieldOn === 'parent' ? 'parent' : ('child' as const), + multiple: rel.multiple ?? false, + })) + : undefined, + }; +} + +function normalizeHierarchy(declared: MetadataContractHierarchy, provider: MetadataProvider): Hierarchy { + const levels: HierarchyLevel[] = declared.levels.map((entry) => { if (typeof entry === 'string') { return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false }; } @@ -421,31 +488,36 @@ function extractMetadata(schema: AnySchemaObject, schemaRefRegistry: Map 0 ? mergedAliases : undefined, - rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined, - relationships: - filteredRelationships.length > 0 - ? filteredRelationships.map((rel) => ({ - ...rel, - field: rel.field ?? 'parent', - fieldOn: rel.fieldOn === 'parent' ? 'parent' : ('child' as const), - multiple: rel.multiple ?? false, - })) - : undefined, + name: declared.name ?? schemaFileStems.get(provider.schema) ?? provider.schemaId, + levels, + allowSkipLevels: declared.allowSkipLevels, }; } +/** Hierarchy names must be unique, and each type may belong to at most one hierarchy. */ +function validateHierarchyComposition(hierarchies: Hierarchy[]): void { + const names = new Set(); + const typeOwners = new Map(); + for (const hierarchy of hierarchies) { + if (names.has(hierarchy.name)) { + throw new Error(`Duplicate hierarchy name "${hierarchy.name}". Set a unique "name" on one of the hierarchies.`); + } + names.add(hierarchy.name); + for (const { type } of hierarchy.levels) { + const owner = typeOwners.get(type); + if (owner !== undefined && owner !== hierarchy.name) { + throw new Error( + `Type "${type}" belongs to both hierarchy "${owner}" and hierarchy "${hierarchy.name}". Each type may belong to at most one hierarchy.`, + ); + } + typeOwners.set(type, hierarchy.name); + } + } +} + interface MetadataForValidation { - mergedHierarchy: MetadataContract['hierarchy'] | undefined; + allHierarchies: Hierarchy[]; mergedAliases: Record; mergedRules: Map; mergedRelationships: MetadataContractRelationship[]; @@ -460,11 +532,10 @@ function validateMetadataReferences(metadata: MetadataForValidation, validTypes: const errors: string[] = []; // Validate hierarchy level types - if (metadata.mergedHierarchy?.levels) { - for (const level of metadata.mergedHierarchy.levels) { - const typeName = typeof level === 'string' ? level : level.type; - if (!validTypes.has(typeName)) { - errors.push(`Hierarchy level "${typeName}" is not a valid type in the schema's oneOf list`); + for (const hierarchy of metadata.allHierarchies) { + for (const { type } of hierarchy.levels) { + if (!validTypes.has(type)) { + errors.push(`Hierarchy "${hierarchy.name}" level "${type}" is not a valid type in the schema's oneOf list`); } } } diff --git a/src/schema/validate-graph.ts b/src/schema/validate-graph.ts index 3883ab8..69b925a 100644 --- a/src/schema/validate-graph.ts +++ b/src/schema/validate-graph.ts @@ -1,5 +1,5 @@ import { resolveNodeType } from '../schema/schema'; -import type { GraphViolation, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types'; +import type { GraphViolation, Hierarchy, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types'; export interface GraphValidationResult { violations: GraphViolation[]; @@ -23,7 +23,7 @@ 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. + * 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 fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node. * @@ -31,12 +31,15 @@ export function validateGraph( */ export function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaMetadata): GraphViolation[] { const violations: GraphViolation[] = []; - const levels = metadata.hierarchy?.levels ?? []; + const hierarchies = metadata.hierarchies ?? []; const relationships = metadata.relationships ?? []; - const allowSkipLevels = metadata.hierarchy?.allowSkipLevels ?? false; const typeAliases = metadata.typeAliases; - const hierarchy = levels.map((level) => resolveNodeType(level.type, typeAliases)); + const hierarchiesByName = new Map(hierarchies.map((h) => [h.name, h])); + const levelTypesByName = new Map( + hierarchies.map((h) => [h.name, h.levels.map((level) => resolveNodeType(level.type, typeAliases))]), + ); + const allHierarchyTypes = new Set([...levelTypesByName.values()].flat()); // Build type rules: (ownerType, field) → set of valid target types. // For fieldOn:'child': owner=childType, target=parentType. @@ -52,15 +55,17 @@ export function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaM fieldMap.get(field)!.add(target); } - for (let i = 1; i < levels.length; i++) { - const level = levels[i]!; - const parentLevel = levels[i - 1]!; - if (level.fieldOn === 'parent') { - addTypeRule(parentLevel.type, level.field, level.type); - if (level.selfRef) addTypeRule(level.type, level.field, level.type); - } else { - addTypeRule(level.type, level.field, parentLevel.type); - if (level.selfRef) addTypeRule(level.type, level.field, level.type); + for (const { levels } of hierarchies) { + for (let i = 1; i < levels.length; i++) { + const level = levels[i]!; + const parentLevel = levels[i - 1]!; + if (level.fieldOn === 'parent') { + addTypeRule(parentLevel.type, level.field, level.type); + if (level.selfRef) addTypeRule(level.type, level.field, level.type); + } else { + addTypeRule(level.type, level.field, parentLevel.type); + if (level.selfRef) addTypeRule(level.type, level.field, level.type); + } } } @@ -119,17 +124,25 @@ export function validateHierarchyStructure(nodes: SpaceNode[], metadata: SchemaM }); } } else { - // Hierarchy edge (fieldOn:'child', source:'hierarchy'): validate level ordering. - const typeIndex = hierarchy.indexOf(nodeType); - const parentIndex = hierarchy.indexOf(parentType); - - if (typeIndex === -1 || parentIndex === -1) continue; - - const level = levels[typeIndex]!; + // Hierarchy edge (fieldOn:'child', source:'hierarchy'): validate level ordering within its hierarchy. + const edgeHierarchy = + parentRef.hierarchy !== undefined ? hierarchiesByName.get(parentRef.hierarchy) : undefined; + if (!edgeHierarchy) continue; + const levelTypes = levelTypesByName.get(edgeHierarchy.name)!; + const typeIndex = levelTypes.indexOf(nodeType); + const parentIndex = levelTypes.indexOf(parentType); + + // A parent from another hierarchy is invalid; a parent of a type outside every hierarchy is not checked here. + if (typeIndex === -1 || (parentIndex === -1 && !allHierarchyTypes.has(parentType))) continue; + + const level = edgeHierarchy.levels[typeIndex]!; const canSelfRef = level.selfRef || level.selfRefField !== undefined; + const allowSkipLevels = edgeHierarchy.allowSkipLevels ?? false; let isValidHierarchy = false; - if (parentIndex === typeIndex - 1) { + if (parentIndex === -1) { + isValidHierarchy = false; + } else if (parentIndex === typeIndex - 1) { isValidHierarchy = true; } else if (canSelfRef && parentIndex === typeIndex) { isValidHierarchy = true; diff --git a/src/space-graph.ts b/src/space-graph.ts index 38ec9da..4a7e8b9 100644 --- a/src/space-graph.ts +++ b/src/space-graph.ts @@ -1,9 +1,11 @@ -import type { HierarchyLevel, ResolvedParentRef, SpaceNode } from './types'; +import type { Hierarchy, ResolvedParentRef, SpaceNode } from './types'; /** * A navigable graph over a set of SpaceNodes. * - * Built once from SpaceNode[] + hierarchy levels via buildSpaceGraph(). + * Built once from SpaceNode[] + one selected hierarchy via buildSpaceGraph(). + * The hierarchy-specific views (roots, orphans, hierarchyChildren, ...) cover only that hierarchy; + * nodes of other hierarchies' types are non-hierarchy nodes in this graph. * Provides typed access to nodes, edges, traversal, and classification * so consumers don't need to build their own indexes. */ @@ -20,7 +22,7 @@ export type SpaceGraph = { /** Non-hierarchy nodes: type not in the hierarchy levels definition. */ readonly nonHierarchy: readonly SpaceNode[]; - /** Hierarchy children map: parent title → direct children connected via hierarchy edges only. */ + /** Hierarchy children map: parent title → direct children connected via this hierarchy's edges only. */ readonly hierarchyChildren: ReadonlyMap; /** All-edges children map: parent title → direct children connected via any edge (hierarchy + relationship). */ @@ -29,14 +31,16 @@ export type SpaceGraph = { /** Set of all node titles that are part of the hierarchy (roots + their descendants + orphans). */ readonly hierarchyTitles: ReadonlySet; - /** Hierarchy levels used to build this graph. */ - readonly levels: readonly HierarchyLevel[]; + /** The hierarchy used to build this graph, if the schema has one. */ + readonly hierarchy: Hierarchy | undefined; }; -/** Build a SpaceGraph from a flat list of SpaceNodes and hierarchy level definitions. */ -export function buildSpaceGraph(nodes: SpaceNode[], levels: readonly HierarchyLevel[]): SpaceGraph { +/** Build a SpaceGraph from a flat list of SpaceNodes and the hierarchy to structure it by. */ +export function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undefined): SpaceGraph { + 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 nodesMap = new Map(); const hierarchyChildrenMap = new Map(); @@ -61,7 +65,7 @@ export function buildSpaceGraph(nodes: SpaceNode[], levels: readonly HierarchyLe childrenMap.get(parentRef.title)!.push(node); // Hierarchy-only map - if (parentRef.source === 'hierarchy') { + if (isHierarchyEdge(parentRef)) { if (!hierarchyChildrenMap.has(parentRef.title)) hierarchyChildrenMap.set(parentRef.title, []); hierarchyChildrenMap.get(parentRef.title)!.push(node); } @@ -78,7 +82,7 @@ export function buildSpaceGraph(nodes: SpaceNode[], levels: readonly HierarchyLe } // Only hierarchy-sourced parents determine structural position in the DAG - const hierarchyParents = node.resolvedParents.filter((r: ResolvedParentRef) => r.source === 'hierarchy'); + const hierarchyParents = node.resolvedParents.filter(isHierarchyEdge); if (hierarchyParents.length === 0) { if (nodeType === rootType) { @@ -118,6 +122,6 @@ export function buildSpaceGraph(nodes: SpaceNode[], levels: readonly HierarchyLe hierarchyChildren: hierarchyChildrenMap, children: childrenMap, hierarchyTitles, - levels, + hierarchy, }; } diff --git a/src/types.ts b/src/types.ts index 25eecd1..82cbf0d 100644 --- a/src/types.ts +++ b/src/types.ts @@ -49,6 +49,8 @@ export type ResolvedParentRef = { 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'. */ + hierarchy?: string; /** Whether the parent and child are the same node type (self-referential edge). */ selfRef: boolean; /** Whether the edge field is on the child node (default) or on the parent node (fieldOn:'parent' edges). */ @@ -190,11 +192,19 @@ export type GraphViolation = { description: string; }; +/** A named hierarchy, normalized from a schema's `$metadata.hierarchy`. */ +export type Hierarchy = { + /** Declared short name, defaulting to the declaring schema's file stem. */ + name: string; + levels: HierarchyLevel[]; // full per-level config + allowSkipLevels?: boolean; +}; + export type SchemaMetadata = { - hierarchy?: { - levels: HierarchyLevel[]; // full per-level config - allowSkipLevels?: boolean; - }; + /** Main hierarchy: used for space_on_a_page parsing, embedding, template-sync and default rendering. */ + hierarchy?: Hierarchy; + /** Every hierarchy in the composed schema (main included), in composition order. Each type belongs to at most one. */ + hierarchies?: Hierarchy[]; typeAliases?: Record; rules?: Rule[]; relationships?: Relationship[]; diff --git a/src/validate.ts b/src/validate.ts index 4f34657..e6d787a 100644 --- a/src/validate.ts +++ b/src/validate.ts @@ -232,9 +232,9 @@ export async function validateSpace( result.refErrors.push(...hierarchyValidation.refErrors); result.hierarchyViolations = [...hierarchyValidation.violations]; - // Calculate orphan count (informational, not a validation error) - if (metadata.hierarchy) { - result.orphans = [...buildSpaceGraph(nodes, metadata.hierarchy.levels).orphans]; + // Calculate orphans across every hierarchy (informational, not a validation error) + for (const hierarchy of metadata.hierarchies ?? []) { + result.orphans.push(...buildSpaceGraph(nodes, hierarchy).orphans); } // Load and execute rules validation if schema defines rules diff --git a/tests/filter/augment-nodes.test.ts b/tests/filter/augment-nodes.test.ts index ad5ae9a..acfa1cd 100644 --- a/tests/filter/augment-nodes.test.ts +++ b/tests/filter/augment-nodes.test.ts @@ -18,7 +18,7 @@ function makeNode(title: string, type: string, parentRefs: ReturnType { diff --git a/tests/filter/expand-include.test.ts b/tests/filter/expand-include.test.ts index 157fe88..d601f1c 100644 --- a/tests/filter/expand-include.test.ts +++ b/tests/filter/expand-include.test.ts @@ -24,7 +24,7 @@ function makeNode(title: string, type: string, extra: Record = function buildContext(nodes: SpaceNode[]) { // Use an empty levels array — expand-include tests don't care about hierarchy classification - const graph = buildSpaceGraph(nodes, []); + const graph = buildSpaceGraph(nodes, undefined); const nodeIndex = graph.nodes; const childrenIndex = graph.children; const augmented = new Map(nodes.map((n) => [n.title, augmentNode(n, nodeIndex, childrenIndex)])); diff --git a/tests/filter/filter-nodes.test.ts b/tests/filter/filter-nodes.test.ts index 5f120fa..793f482 100644 --- a/tests/filter/filter-nodes.test.ts +++ b/tests/filter/filter-nodes.test.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test'; import { filterNodes } from '../../src/filter/filter-nodes'; import { buildSpaceGraph } from '../../src/space-graph'; import type { SpaceNode } from '../../src/types'; -import { makeLevel, makeParentRef } from '../test-helpers'; +import { makeHierarchy, makeLevel, makeParentRef } from '../test-helpers'; const levels = [makeLevel('goal'), makeLevel('opportunity'), makeLevel('solution')]; @@ -32,7 +32,7 @@ activeOpportunity.resolvedParents = [makeParentRef('My Goal')]; pausedOpportunity.resolvedParents = [makeParentRef('My Goal')]; const allNodes = [goal, activeOpportunity, pausedOpportunity, solution1, solution2]; -const allGraph = buildSpaceGraph(allNodes, levels); +const allGraph = buildSpaceGraph(allNodes, makeHierarchy(levels)); function nodes(graph: Awaited>): SpaceNode[] { return [...graph.nodes.values()]; diff --git a/tests/fixtures/multi-hierarchy/_skills-pack.json b/tests/fixtures/multi-hierarchy/_skills-pack.json new file mode 100644 index 0000000..916c880 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/_skills-pack.json @@ -0,0 +1,47 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/skills", + "$metadata": { + "hierarchy": { + "levels": [ + "skill_area", + { + "type": "skill", + "selfRef": true + } + ] + } + }, + "$defs": { + "skill_area": { + "type": "object", + "properties": { + "type": { + "const": "skill_area" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + }, + "skill": { + "type": "object", + "properties": { + "type": { + "const": "skill" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + } + } +} diff --git a/tests/fixtures/multi-hierarchy/_work-pack.json b/tests/fixtures/multi-hierarchy/_work-pack.json new file mode 100644 index 0000000..203e9bb --- /dev/null +++ b/tests/fixtures/multi-hierarchy/_work-pack.json @@ -0,0 +1,42 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/work", + "$metadata": { + "hierarchy": { + "name": "work", + "levels": ["goal", "task"] + } + }, + "$defs": { + "goal": { + "type": "object", + "properties": { + "type": { + "const": "goal" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + }, + "task": { + "type": "object", + "properties": { + "type": { + "const": "task" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + } + } +} diff --git a/tests/fixtures/multi-hierarchy/declare-and-ref-root.json b/tests/fixtures/multi-hierarchy/declare-and-ref-root.json new file mode 100644 index 0000000..bf932b9 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/declare-and-ref-root.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/declare-and-ref-root", + "$metadata": { + "hierarchy": { + "$ref": "sctx-test://multi-hierarchy/work#/$metadata/hierarchy", + "levels": ["goal", "task"] + } + }, + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/goal" + }, + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/task" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/declared-root.json b/tests/fixtures/multi-hierarchy/declared-root.json new file mode 100644 index 0000000..f197594 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/declared-root.json @@ -0,0 +1,54 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/declared-root", + "$metadata": { + "hierarchy": { + "name": "strategy", + "levels": ["vision", "mission"] + } + }, + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/goal" + }, + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/task" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + }, + { + "type": "object", + "properties": { + "type": { + "const": "vision" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + }, + { + "type": "object", + "properties": { + "type": { + "const": "mission" + }, + "title": { + "type": "string" + }, + "parent": { + "type": "string" + } + }, + "required": ["type", "title"] + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/selected-root.json b/tests/fixtures/multi-hierarchy/selected-root.json new file mode 100644 index 0000000..73fca73 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/selected-root.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/selected-root", + "$metadata": { + "hierarchy": { + "$ref": "sctx-test://multi-hierarchy/work#/$metadata/hierarchy" + } + }, + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/goal" + }, + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/task" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/single-contributed-root.json b/tests/fixtures/multi-hierarchy/single-contributed-root.json new file mode 100644 index 0000000..c01e549 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/single-contributed-root.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/single-contributed-root", + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/space/Engineering.md b/tests/fixtures/multi-hierarchy/space/Engineering.md new file mode 100644 index 0000000..47e8ada --- /dev/null +++ b/tests/fixtures/multi-hierarchy/space/Engineering.md @@ -0,0 +1,3 @@ +--- +type: skill_area +--- diff --git a/tests/fixtures/multi-hierarchy/space/Ship v2.md b/tests/fixtures/multi-hierarchy/space/Ship v2.md new file mode 100644 index 0000000..86878d4 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/space/Ship v2.md @@ -0,0 +1,3 @@ +--- +type: goal +--- diff --git a/tests/fixtures/multi-hierarchy/space/Testing.md b/tests/fixtures/multi-hierarchy/space/Testing.md new file mode 100644 index 0000000..ca0c945 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/space/Testing.md @@ -0,0 +1,4 @@ +--- +type: skill +parent: "[[Engineering]]" +--- diff --git a/tests/fixtures/multi-hierarchy/space/Write docs.md b/tests/fixtures/multi-hierarchy/space/Write docs.md new file mode 100644 index 0000000..1ddec68 --- /dev/null +++ b/tests/fixtures/multi-hierarchy/space/Write docs.md @@ -0,0 +1,4 @@ +--- +type: task +parent: "[[Ship v2]]" +--- diff --git a/tests/fixtures/multi-hierarchy/unselected-root.json b/tests/fixtures/multi-hierarchy/unselected-root.json new file mode 100644 index 0000000..6b7686d --- /dev/null +++ b/tests/fixtures/multi-hierarchy/unselected-root.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/unselected-root", + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/goal" + }, + { + "$ref": "sctx-test://multi-hierarchy/work#/$defs/task" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/plugins/markdown/parse-embedded-hierarchy-embedding.test.ts b/tests/plugins/markdown/parse-embedded-hierarchy-embedding.test.ts index 08e014f..01be29d 100644 --- a/tests/plugins/markdown/parse-embedded-hierarchy-embedding.test.ts +++ b/tests/plugins/markdown/parse-embedded-hierarchy-embedding.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'bun:test'; import { extractEmbeddedNodes } from '../../../src/plugins/markdown/parse-embedded'; import type { HierarchyLevel } from '../../../src/types'; -import { makeLevel, makeRelationship } from '../../test-helpers'; +import { makeLevel, makeRelationship, withHierarchy } from '../../test-helpers'; const HIERARCHY: HierarchyLevel[] = [ makeLevel('phase'), @@ -23,7 +23,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'activity', - metadata: { hierarchy: { levels: HIERARCHY } }, + metadata: { ...withHierarchy(HIERARCHY) }, }); const caps = nodes.filter((n) => n.schemaData.type === 'capability'); @@ -48,7 +48,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'goal', - metadata: { hierarchy: { levels: hierarchy } }, + metadata: { ...withHierarchy(hierarchy) }, }); const opps = nodes.filter((n) => n.schemaData.type === 'opportunity'); @@ -67,11 +67,10 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'activity', - metadata: { - hierarchy: { - levels: [makeLevel('activity'), makeLevel('tool', { field: 'tools', fieldOn: 'parent', multiple: true })], - }, - }, + metadata: withHierarchy([ + makeLevel('activity'), + makeLevel('tool', { field: 'tools', fieldOn: 'parent', multiple: true }), + ]), }); const activity = nodes.find((n) => n.schemaData.type === 'activity'); @@ -93,7 +92,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'application', - metadata: { hierarchy: { levels: HIERARCHY } }, + metadata: { ...withHierarchy(HIERARCHY) }, }); const app = nodes.find((n) => n.schemaData.type === 'application'); @@ -119,7 +118,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'application', - metadata: { hierarchy: { levels: capLevelWithMatchers } }, + metadata: { ...withHierarchy(capLevelWithMatchers) }, }); const app = nodes.find((n) => n.schemaData.type === 'application'); @@ -141,7 +140,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'activity', - metadata: { hierarchy: { levels: hierarchy } }, + metadata: { ...withHierarchy(hierarchy) }, }); const activity = nodes.find((n) => n.schemaData.type === 'activity'); @@ -173,7 +172,7 @@ describe('extractEmbeddedNodes - hierarchy embedding', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'phase', - metadata: { hierarchy: { levels: hierarchy } }, + metadata: { ...withHierarchy(hierarchy) }, }); const app = nodes.find((n) => n.schemaData.type === 'application'); @@ -203,7 +202,7 @@ Some paragraph content here. `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'goal', - metadata: { hierarchy: { levels: hierarchy } }, + metadata: { ...withHierarchy(hierarchy) }, }); // The opportunity heading is flushed as a node when paragraph content follows @@ -221,7 +220,7 @@ Some paragraph content here. `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'goal', - metadata: { hierarchy: { levels: [makeLevel('goal'), makeLevel('opportunity')] } }, + metadata: { ...withHierarchy([makeLevel('goal'), makeLevel('opportunity')]) }, }); const opps = nodes.filter((n) => n.schemaData.type === 'opportunity'); @@ -250,7 +249,7 @@ Some paragraph content here. `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'goal', - metadata: { hierarchy: { levels: hierarchy }, relationships }, + metadata: { ...withHierarchy(hierarchy), relationships }, }); const opps = nodes.filter((n) => n.schemaData.type === 'opportunity'); diff --git a/tests/plugins/markdown/parse-embedded-relationships.test.ts b/tests/plugins/markdown/parse-embedded-relationships.test.ts index 8cb6d3c..0c8b987 100644 --- a/tests/plugins/markdown/parse-embedded-relationships.test.ts +++ b/tests/plugins/markdown/parse-embedded-relationships.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'bun:test'; import { extractEmbeddedNodes } from '../../../src/plugins/markdown/parse-embedded'; import type { Relationship } from '../../../src/types'; -import { makeLevel } from '../../test-helpers'; +import { makeLevel, withHierarchy } from '../../test-helpers'; describe('extractEmbeddedNodes - relationships', () => { const hierarchy = ['vision', 'mission', 'goal', 'opportunity', 'solution', 'experiment']; @@ -33,7 +33,7 @@ describe('extractEmbeddedNodes - relationships', () => { const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const opp = nodes.find((n) => n.schemaData.type === 'opportunity'); @@ -57,7 +57,7 @@ describe('extractEmbeddedNodes - relationships', () => { `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: [...hierarchy, 'assumption'].map((t) => makeLevel(t)) }, relationships: [] }, + metadata: { ...withHierarchy([...hierarchy, 'assumption'].map((t) => makeLevel(t))), relationships: [] }, }); const assumptions = nodes.filter((n) => n.schemaData.type === 'assumption'); @@ -86,7 +86,7 @@ Our users are sad. `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const probNodes = nodes.filter((n) => n.schemaData.type === 'problem_statement'); @@ -118,7 +118,7 @@ Our users are sad. `; const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const solutions = nodes.filter((n) => n.schemaData.type === 'solution'); @@ -154,7 +154,7 @@ Our users are sad. const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const assumptions = nodes.filter((n) => n.schemaData.type === 'assumption'); @@ -188,7 +188,7 @@ Our users are sad. const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const assumptions = nodes.filter((n) => n.schemaData.type === 'assumption'); @@ -221,7 +221,7 @@ Our users are sad. expect(() => extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }), ).toThrow(/Cannot append child link to field 'solutions'.*field exists but is not an array/); }); @@ -254,7 +254,7 @@ Our users are sad. expect(() => extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }), ).toThrow(/Cannot append child link to field 'assumptions'.*field exists but is not an array/); }); @@ -283,7 +283,7 @@ Our users are sad. expect(() => extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }), ).toThrow(/Cannot append child link to field 'count'.*field exists but is not an array/); }); @@ -312,7 +312,7 @@ Our users are sad. const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const opportunity = nodes.find((n) => n.schemaData.type === 'opportunity'); @@ -350,7 +350,7 @@ Our users are sad. const { nodes } = extractEmbeddedNodes(body, { pageType: 'opportunity', - metadata: { hierarchy: { levels: hierarchy.map((t) => makeLevel(t)) }, relationships }, + metadata: { ...withHierarchy(hierarchy.map((t) => makeLevel(t))), relationships }, }); const opportunity = nodes.find((n) => n.schemaData.type === 'opportunity'); diff --git a/tests/plugins/markdown/relationship-embedded-nodes.test.ts b/tests/plugins/markdown/relationship-embedded-nodes.test.ts index 64137e6..dde193f 100644 --- a/tests/plugins/markdown/relationship-embedded-nodes.test.ts +++ b/tests/plugins/markdown/relationship-embedded-nodes.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'bun:test'; import { extractEmbeddedNodes } from '../../../src/plugins/markdown/parse-embedded'; -import { makeLevel, makeRelationship } from '../../test-helpers'; +import { makeLevel, makeRelationship, withHierarchy } from '../../test-helpers'; describe('Embedded nodes with parent-side relationships', () => { it('should create child nodes when heading anchor matches relationship type', () => { @@ -15,7 +15,7 @@ describe('Embedded nodes with parent-side relationships', () => { pageTitle: 'Test Solution', pageType: 'Solutions', metadata: { - hierarchy: { levels: ['Phases', 'Activities', 'Capabilities', 'Tools'].map((t) => makeLevel(t)) }, + ...withHierarchy(['Phases', 'Activities', 'Capabilities', 'Tools'].map((t) => makeLevel(t))), relationships: [ makeRelationship('Solutions', 'Applications', { field: 'applications', diff --git a/tests/read/content-links.test.ts b/tests/read/content-links.test.ts index b18fb75..6f09bf9 100644 --- a/tests/read/content-links.test.ts +++ b/tests/read/content-links.test.ts @@ -193,13 +193,14 @@ describe('contentLinks and resolvedLinks integration', () => { // --------------------------------------------------------------------------- import { resolveGraphEdges as resolveEdges } from '../../src/read/resolve-graph-edges'; +import { withHierarchy } from '../test-helpers'; describe('link location classification', () => { const levels = [ { type: 'goal', field: 'parent', fieldOn: 'child' as const, multiple: false, selfRef: false }, { type: 'solution', field: 'parent', fieldOn: 'child' as const, multiple: false, selfRef: false }, ]; - const metadata = { hierarchy: { levels } }; + const metadata = { ...withHierarchy(levels) }; function makeBaseNode(title: string, type: string, links: ContentLink[] = []) { return { diff --git a/tests/read/resolve-hierarchy-edges.test.ts b/tests/read/resolve-hierarchy-edges.test.ts index 3c80108..9d9ff65 100644 --- a/tests/read/resolve-hierarchy-edges.test.ts +++ b/tests/read/resolve-hierarchy-edges.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'bun:test'; import { resolveGraphEdges } from '../../src/read/resolve-graph-edges'; import type { Relationship } from '../../src/types'; -import { makeLevel, makeNode } from '../test-helpers'; +import { makeLevel, makeNode, withHierarchy } from '../test-helpers'; describe('resolveGraphEdges', () => { describe("default behavior (fieldOn: 'child', multiple: false)", () => { @@ -11,7 +11,7 @@ describe('resolveGraphEdges', () => { const phase = makeNode('Phase 1', 'Phase'); const activity = makeNode('Activity 1', 'Activity', { parent: '[[Phase 1]]' }); - const { nodes } = resolveGraphEdges([phase, activity], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([phase, activity], { ...withHierarchy(levels) }); const resolvedActivity = nodes.find((n) => n.label === 'Activity 1.md')!; const resolvedPhase = nodes.find((n) => n.label === 'Phase 1.md')!; @@ -24,7 +24,7 @@ describe('resolveGraphEdges', () => { const activity = makeNode('Activity 1', 'Activity', { parent: '[[Nonexistent Phase]]' }); - const { nodes, unresolvedRefs } = resolveGraphEdges([activity], { hierarchy: { levels } }); + const { nodes, unresolvedRefs } = resolveGraphEdges([activity], { ...withHierarchy(levels) }); const resolvedActivity = nodes.find((n) => n.label === 'Activity 1.md')!; expect(resolvedActivity.resolvedParents).toEqual([]); @@ -50,7 +50,7 @@ describe('resolveGraphEdges', () => { const reqB = makeNode('Req B', 'Requirement'); const tool = makeNode('Tool X', 'Tool', { fulfills: ['[[Req A]]', '[[Req B]]'] }); - const { nodes } = resolveGraphEdges([reqA, reqB, tool], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([reqA, reqB, tool], { ...withHierarchy(levels) }); const resolvedTool = nodes.find((n) => n.label === 'Tool X.md')!; expect(resolvedTool.resolvedParents.map((r) => r.title)).toContain('Req A'); @@ -64,7 +64,7 @@ describe('resolveGraphEdges', () => { const req = makeNode('Req A', 'Requirement'); const tool = makeNode('Tool X', 'Tool', { fulfills: ['[[Req A]]', 42, null] }); - const { nodes } = resolveGraphEdges([req, tool], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([req, tool], { ...withHierarchy(levels) }); const resolvedTool = nodes.find((n) => n.label === 'Tool X.md')!; expect(resolvedTool.resolvedParents.map((r) => r.title)).toEqual(['Req A']); @@ -75,7 +75,7 @@ describe('resolveGraphEdges', () => { const tool = makeNode('Tool X', 'Tool', { fulfills: '[[Req A]]' }); // string, not array - const { nodes, unresolvedRefs } = resolveGraphEdges([tool], { hierarchy: { levels } }); + const { nodes, unresolvedRefs } = resolveGraphEdges([tool], { ...withHierarchy(levels) }); const resolvedTool = nodes.find((n) => n.label === 'Tool X.md')!; expect(resolvedTool.resolvedParents).toEqual([]); @@ -102,7 +102,7 @@ describe('resolveGraphEdges', () => { const reqA = makeNode('Req A', 'Requirement'); const reqB = makeNode('Req B', 'Requirement'); - const { nodes } = resolveGraphEdges([activity, reqA, reqB], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([activity, reqA, reqB], { ...withHierarchy(levels) }); const resolvedReqA = nodes.find((n) => n.label === 'Req A.md')!; const resolvedReqB = nodes.find((n) => n.label === 'Req B.md')!; @@ -126,7 +126,7 @@ describe('resolveGraphEdges', () => { }); const sharedReq = makeNode('Shared Req', 'Requirement'); - const { nodes } = resolveGraphEdges([activity1, activity2, sharedReq], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([activity1, activity2, sharedReq], { ...withHierarchy(levels) }); const resolvedSharedReq = nodes.find((n) => n.label === 'Shared Req.md')!; expect(resolvedSharedReq.resolvedParents.map((r) => r.title)).toContain('Activity 1'); @@ -153,7 +153,7 @@ describe('resolveGraphEdges', () => { const reqB = makeNode('Req B', 'Requirement'); const tool = makeNode('Tool X', 'Tool', { fulfills: ['[[Req A]]'] }); - const { nodes } = resolveGraphEdges([phase, activity, reqA, reqB, tool], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([phase, activity, reqA, reqB, tool], { ...withHierarchy(levels) }); const r = (label: string) => nodes.find((n) => n.label === label)!; expect(r('Activity 1.md').resolvedParents.map((p) => p.title)).toEqual(['Phase 1']); @@ -171,7 +171,7 @@ describe('resolveGraphEdges', () => { const phase = makeNode('Phase 1', 'Phase', { parent: '[[Activity 1]]' }); const activity = makeNode('Activity 1', 'Activity', { parent: '[[Phase 1]]' }); - const { nodes } = resolveGraphEdges([phase, activity], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([phase, activity], { ...withHierarchy(levels) }); const resolvedPhase = nodes.find((n) => n.label === 'Phase 1.md')!; const resolvedActivity = nodes.find((n) => n.label === 'Activity 1.md')!; @@ -187,7 +187,7 @@ describe('resolveGraphEdges', () => { const activity = makeNode('Activity 1', 'Activity', { parent: '[[Ghost Phase]]' }); - const { nodes, unresolvedRefs } = resolveGraphEdges([activity], { hierarchy: { levels } }); + const { nodes, unresolvedRefs } = resolveGraphEdges([activity], { ...withHierarchy(levels) }); const resolvedActivity = nodes.find((n) => n.label === 'Activity 1.md')!; expect(resolvedActivity.resolvedParents).toEqual([]); @@ -218,7 +218,7 @@ describe('resolveGraphEdges', () => { const project = makeNode('Project A', 'project'); const task = makeNode('Task 1', 'task', { parent: '[[Project A]]' }); - const { nodes } = resolveGraphEdges([project, task], { hierarchy: { levels }, relationships }); + const { nodes } = resolveGraphEdges([project, task], { ...withHierarchy(levels), relationships }); const resolvedTask = nodes.find((n) => n.label === 'Task 1.md')!; const ref = resolvedTask.resolvedParents.find((r) => r.title === 'Project A'); @@ -242,7 +242,7 @@ describe('resolveGraphEdges', () => { const project = makeNode('Project A', 'project'); const resource = makeNode('Resource 1', 'resource', { parent: '[[Project A]]' }); - const { nodes } = resolveGraphEdges([project, resource], { hierarchy: { levels }, relationships }); + const { nodes } = resolveGraphEdges([project, resource], { ...withHierarchy(levels), relationships }); const resolvedResource = nodes.find((n) => n.label === 'Resource 1.md')!; const ref = resolvedResource.resolvedParents.find((r) => r.title === 'Project A'); @@ -264,7 +264,7 @@ describe('resolveGraphEdges', () => { const coreCapability = makeNode('Core Capability', 'Capability'); const subCapability = makeNode('Sub Capability', 'Capability', { parent: '[[Core Capability]]' }); - const { nodes } = resolveGraphEdges([activity, coreCapability, subCapability], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([activity, coreCapability, subCapability], { ...withHierarchy(levels) }); const resolvedCore = nodes.find((n) => n.label === 'Core Capability.md')!; const resolvedSub = nodes.find((n) => n.label === 'Sub Capability.md')!; @@ -295,7 +295,7 @@ describe('resolveGraphEdges', () => { const toolB = makeNode('Tool B', 'Tool', { partOf: '[[Tool A]]' }); const toolC = makeNode('Tool C', 'Tool', { partOf: '[[Tool B]]' }); - const { nodes } = resolveGraphEdges([activity, toolA, toolB, toolC], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([activity, toolA, toolB, toolC], { ...withHierarchy(levels) }); const rTool = (name: string) => nodes.find((n) => n.label === `${name}.md`)!; @@ -320,7 +320,7 @@ describe('resolveGraphEdges', () => { const objective1 = makeNode('Objective 1', 'Objective', { parent: '[[Goal 1]]' }); const objective2 = makeNode('Objective 2', 'Objective', { parent: '[[Objective 1]]' }); - const { nodes } = resolveGraphEdges([goal, objective1, objective2], { hierarchy: { levels } }); + const { nodes } = resolveGraphEdges([goal, objective1, objective2], { ...withHierarchy(levels) }); const rObj = (name: string) => nodes.find((n) => n.label === `${name}.md`)!; @@ -348,7 +348,7 @@ describe('resolveGraphEdges', () => { parent: '[[Nonexistent Parent]]', // selfRefField target that doesn't exist }); - const { nodes, unresolvedRefs } = resolveGraphEdges([activity, capabilityA], { hierarchy: { levels } }); + const { nodes, unresolvedRefs } = resolveGraphEdges([activity, capabilityA], { ...withHierarchy(levels) }); const resolvedCapA = nodes.find((n) => n.label === 'Capability A.md')!; diff --git a/tests/render/render-bullets.test.ts b/tests/render/render-bullets.test.ts index f5b3516..355c840 100644 --- a/tests/render/render-bullets.test.ts +++ b/tests/render/render-bullets.test.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test'; import { renderBullets } from '../../src/plugins/markdown/render-bullets'; import { buildSpaceGraph } from '../../src/space-graph'; import type { SpaceNode } from '../../src/types'; -import { makeLevel, makeParentRef } from '../test-helpers'; +import { makeHierarchy, makeLevel, makeParentRef } from '../test-helpers'; const levels = [makeLevel('goal'), makeLevel('opportunity'), makeLevel('solution')]; @@ -22,7 +22,7 @@ function makeNode(title: string, type: string): SpaceNode { describe('renderBullets', () => { it('renders a single root with no children', () => { const root = makeNode('My Goal', 'goal'); - const output = renderBullets(buildSpaceGraph([root], levels)); + const output = renderBullets(buildSpaceGraph([root], makeHierarchy(levels))); expect(output).toBe('- goal: My Goal'); }); @@ -30,20 +30,20 @@ describe('renderBullets', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal')]; - const output = renderBullets(buildSpaceGraph([goal, opp], levels)); + const output = renderBullets(buildSpaceGraph([goal, opp], makeHierarchy(levels))); expect(output).toBe('- goal: My Goal\n - opportunity: An Opportunity'); }); it('renders orphans in a separate section', () => { const orphan = makeNode('Orphaned Opp', 'opportunity'); - const output = renderBullets(buildSpaceGraph([orphan], levels)); + const output = renderBullets(buildSpaceGraph([orphan], makeHierarchy(levels))); expect(output).toContain('Orphans (missing parent):'); expect(output).toContain('- opportunity: Orphaned Opp'); }); it('renders non-hierarchy nodes in a separate section', () => { const dashboard = makeNode('My Dashboard', 'dashboard'); - const output = renderBullets(buildSpaceGraph([dashboard], levels)); + const output = renderBullets(buildSpaceGraph([dashboard], makeHierarchy(levels))); expect(output).toContain('Other (not in hierarchy):'); expect(output).toContain('- dashboard: My Dashboard'); }); @@ -56,7 +56,7 @@ describe('renderBullets', () => { // opp is referenced under both goals and has a child opp.resolvedParents = [makeParentRef('My Goal'), makeParentRef('Another Goal')]; solution.resolvedParents = [makeParentRef('Shared Opp')]; - const output = renderBullets(buildSpaceGraph([goal, goal2, opp, solution], levels)); + const output = renderBullets(buildSpaceGraph([goal, goal2, opp, solution], makeHierarchy(levels))); expect(output).toContain('- opportunity: Shared Opp\n - solution: A Solution'); expect(output).toContain('- opportunity: Shared Opp (*)'); }); @@ -66,7 +66,7 @@ describe('renderBullets', () => { const goal2 = makeNode('Another Goal', 'goal'); const opp = makeNode('Shared Opp', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal'), makeParentRef('Another Goal')]; - const output = renderBullets(buildSpaceGraph([goal, goal2, opp], levels)); + const output = renderBullets(buildSpaceGraph([goal, goal2, opp], makeHierarchy(levels))); expect(output).toContain('- opportunity: Shared Opp'); expect(output).not.toContain('(*)'); }); diff --git a/tests/render/render-hierarchy.test.ts b/tests/render/render-hierarchy.test.ts new file mode 100644 index 0000000..39ee3b3 --- /dev/null +++ b/tests/render/render-hierarchy.test.ts @@ -0,0 +1,36 @@ +import { describe, expect, it } from 'bun:test'; +import { join } from 'node:path'; +import { executeRender } from '../../src/render/render'; +import { makeSpaceContext } from '../helpers/context'; + +const MULTI_DIR = join(import.meta.dir, '..', 'fixtures/multi-hierarchy'); +const context = makeSpaceContext(join(MULTI_DIR, 'space'), join(MULTI_DIR, 'selected-root.json')); + +describe('rendering a selected hierarchy', () => { + it('renders the main hierarchy by default', async () => { + const [tree, other] = (await executeRender('markdown.bullets', context, {})).split('\n\n'); + expect(tree).toBe(['- goal: Ship v2', ' - task: Write docs'].join('\n')); + expect(other?.split('\n').sort()).toEqual([ + ' - skill: Testing', + ' - skill_area: Engineering', + 'Other (not in hierarchy):', + ]); + }); + + it('renders the hierarchy named by the hierarchy option', async () => { + const output = await executeRender('markdown.bullets', context, { hierarchy: '_skills-pack' }); + const [tree, other] = output.split('\n\n'); + expect(tree).toBe(['- skill_area: Engineering', ' - skill: Testing'].join('\n')); + expect(other?.split('\n').sort()).toEqual([ + ' - goal: Ship v2', + ' - task: Write docs', + 'Other (not in hierarchy):', + ]); + }); + + it('fails for an unknown hierarchy name', async () => { + await expect(executeRender('markdown.bullets', context, { hierarchy: 'missing' })).rejects.toThrow( + 'Unknown hierarchy: "missing". Available: work, _skills-pack', + ); + }); +}); diff --git a/tests/render/render-mermaid.test.ts b/tests/render/render-mermaid.test.ts index 4932b02..4f3c34a 100644 --- a/tests/render/render-mermaid.test.ts +++ b/tests/render/render-mermaid.test.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test'; import { renderMermaid } from '../../src/plugins/mermaid/render-mermaid'; import { buildSpaceGraph } from '../../src/space-graph'; import type { SpaceNode } from '../../src/types'; -import { makeLevel, makeParentRef } from '../test-helpers'; +import { makeHierarchy, makeLevel, makeParentRef } from '../test-helpers'; const levels = [ makeLevel('vision'), @@ -27,13 +27,13 @@ function makeNode(title: string, type: string, status = 'active'): SpaceNode { describe('renderMermaid', () => { it('starts with graph TD', () => { - const output = renderMermaid(buildSpaceGraph([], levels)); + const output = renderMermaid(buildSpaceGraph([], makeHierarchy(levels))); expect(output.startsWith('graph TD\n')).toBe(true); }); it('emits classDefs derived from hierarchy levels', () => { const customLevels = [makeLevel('theme'), makeLevel('initiative')]; - const output = renderMermaid(buildSpaceGraph([], customLevels)); + const output = renderMermaid(buildSpaceGraph([], makeHierarchy(customLevels))); expect(output).toContain('classDef theme '); expect(output).toContain('classDef initiative '); expect(output).not.toContain('classDef vision'); @@ -42,7 +42,7 @@ describe('renderMermaid', () => { it('renders a root node with the hierarchy type as its class', () => { const goal = makeNode('My Goal', 'goal'); - const output = renderMermaid(buildSpaceGraph([goal], levels)); + const output = renderMermaid(buildSpaceGraph([goal], makeHierarchy(levels))); expect(output).toContain('My_Goal["My Goal"]:::goal'); }); @@ -50,26 +50,26 @@ describe('renderMermaid', () => { const goal = makeNode('My Goal', 'goal', 'active'); const opp = makeNode('An Opportunity', 'opportunity', 'active'); opp.resolvedParents = [makeParentRef('My Goal')]; - const output = renderMermaid(buildSpaceGraph([goal, opp], levels)); + const output = renderMermaid(buildSpaceGraph([goal, opp], makeHierarchy(levels))); expect(output).toContain('My_Goal --> An_Opportunity'); }); it('wraps orphans in a subgraph', () => { const orphan = makeNode('Orphaned Opp', 'opportunity'); - const output = renderMermaid(buildSpaceGraph([orphan], levels)); + const output = renderMermaid(buildSpaceGraph([orphan], makeHierarchy(levels))); expect(output).toContain('subgraph Orphans'); expect(output).toContain('Orphaned_Opp["Orphaned Opp"]:::opportunity'); }); it('escapes double quotes in node labels', () => { const node = makeNode('Say "Hello"', 'goal', 'active'); - const output = renderMermaid(buildSpaceGraph([node], levels)); + const output = renderMermaid(buildSpaceGraph([node], makeHierarchy(levels))); expect(output).toContain('"Hello"'); }); it('does not render non-hierarchy nodes', () => { const dashboard = makeNode('My Dashboard', 'dashboard', 'active'); - const output = renderMermaid(buildSpaceGraph([dashboard], levels)); + const output = renderMermaid(buildSpaceGraph([dashboard], makeHierarchy(levels))); expect(output).not.toContain('My_Dashboard'); }); }); diff --git a/tests/schema/schema-composition.test.ts b/tests/schema/schema-composition.test.ts index 453d617..c050ed2 100644 --- a/tests/schema/schema-composition.test.ts +++ b/tests/schema/schema-composition.test.ts @@ -1,8 +1,9 @@ import { describe, expect, it } from 'bun:test'; import { join } from 'node:path'; -import { createValidator, loadMetadata } from '../../src/schema/schema'; +import { bundledSchemasDir, createValidator, loadMetadata } from '../../src/schema/schema'; const FIXTURES_DIR = join(import.meta.dir, '..', 'fixtures/schema-composition'); +const MULTI_DIR = join(import.meta.dir, '..', 'fixtures/multi-hierarchy'); describe('schema composition metadata', () => { it('merges metadata across $ref graph in DFS order and applies root metadata last', () => { @@ -17,11 +18,11 @@ describe('schema composition metadata', () => { expect(metadata.rules?.map((rule) => rule.id)).toEqual(['leaf-rule', 'pack-a-rule', 'root-rule']); }); - it('uses root schema hierarchy when multiple providers define one', () => { - const metadata = loadMetadata(join(FIXTURES_DIR, 'hierarchy-conflict-root.json')); - // Root schema defines hierarchy with only ["goal"]; partial defines ["vision", "goal"]. - // Root wins — it is processed last and overrides the partial. - expect(metadata.hierarchy?.levels.map((l) => l.type)).toEqual(['goal']); + it('fails when a type belongs to two hierarchies', () => { + // Root declares ["goal"]; the partial it composes declares ["vision", "goal"]. + expect(() => loadMetadata(join(FIXTURES_DIR, 'hierarchy-conflict-root.json'))).toThrow( + 'Type "goal" belongs to both hierarchy "_hierarchy-conflict-pack" and hierarchy "hierarchy-conflict-root"', + ); }); it('fails conflicting rule IDs without explicit override', () => { @@ -61,3 +62,62 @@ describe('schema composition metadata', () => { expect(() => createValidator(join(FIXTURES_DIR, 'merge-root.json'))).not.toThrow(); }); }); + +describe('schema composition hierarchies', () => { + const summarize = (metadata: ReturnType) => ({ + main: metadata.hierarchy?.name, + hierarchies: metadata.hierarchies?.map((h) => [h.name, h.levels.map((l) => l.type)]), + }); + + it('keeps each composed hierarchy separate and uses the root-declared one as main', () => { + const metadata = loadMetadata(join(MULTI_DIR, 'declared-root.json')); + expect(summarize(metadata)).toEqual({ + main: 'strategy', + hierarchies: [ + ['work', ['goal', 'task']], + ['_skills-pack', ['skill_area', 'skill']], + ['strategy', ['vision', 'mission']], + ], + }); + }); + + it('uses a single contributed hierarchy as the implicit main hierarchy', () => { + const metadata = loadMetadata(join(MULTI_DIR, 'single-contributed-root.json')); + expect(summarize(metadata)).toEqual({ + main: '_skills-pack', + hierarchies: [['_skills-pack', ['skill_area', 'skill']]], + }); + }); + + it('names a hierarchy after its declaring schema file stem by default', () => { + const metadata = loadMetadata(join(bundledSchemasDir, 'strict_ost.json')); + expect(metadata.hierarchy?.name).toBe('_ost_strict'); + }); + + it('selects the main hierarchy with hierarchy: { $ref }', () => { + const metadata = loadMetadata(join(MULTI_DIR, 'selected-root.json')); + expect(summarize(metadata)).toEqual({ + main: 'work', + hierarchies: [ + ['work', ['goal', 'task']], + ['_skills-pack', ['skill_area', 'skill']], + ], + }); + }); + + it('fails when several hierarchies are contributed and none is selected', () => { + expect(() => loadMetadata(join(MULTI_DIR, 'unselected-root.json'))).toThrow( + 'composes multiple hierarchies ("work", "_skills-pack") but selects none as its main hierarchy', + ); + }); + + it('fails when a root both declares a hierarchy and selects one with $ref', () => { + expect(() => loadMetadata(join(MULTI_DIR, 'declare-and-ref-root.json'))).toThrow( + 'hierarchy both declares levels and selects a hierarchy with "$ref"', + ); + }); + + it('compiles a schema that selects its main hierarchy with $ref', () => { + expect(() => createValidator(join(MULTI_DIR, 'selected-root.json'))).not.toThrow(); + }); +}); diff --git a/tests/schema/validate-graph.test.ts b/tests/schema/validate-graph.test.ts index b2e56e2..6014b2a 100644 --- a/tests/schema/validate-graph.test.ts +++ b/tests/schema/validate-graph.test.ts @@ -3,15 +3,15 @@ import { resolveGraphEdges } from '../../src/read/resolve-graph-edges'; import { resolveNodeType } from '../../src/schema/schema'; import { validateGraph, validateHierarchyStructure } from '../../src/schema/validate-graph'; import type { BaseNode, SchemaMetadata, SpaceNode } from '../../src/types'; -import { makeLevel, makeNode, makeParentRef } from '../test-helpers'; +import { makeHierarchy, makeLevel, makeNode, makeParentRef, withHierarchy } from '../test-helpers'; describe('validateGraph - selfRef field reference validation', () => { describe('fieldOn: child (default)', () => { const metaSelfRef: SchemaMetadata = { - hierarchy: { levels: [makeLevel('mission'), makeLevel('goal', { selfRef: true })], allowSkipLevels: false }, + ...withHierarchy([makeLevel('mission'), makeLevel('goal', { selfRef: true })], { allowSkipLevels: false }), }; const metaNoSelfRef: SchemaMetadata = { - hierarchy: { levels: [makeLevel('mission'), makeLevel('goal')], allowSkipLevels: false }, + ...withHierarchy([makeLevel('mission'), makeLevel('goal')], { allowSkipLevels: false }), }; it('allows goal.parent pointing to a goal when selfRef is true', () => { @@ -41,13 +41,13 @@ describe('validateGraph - selfRef field reference validation', () => { describe('fieldOn: parent', () => { const meta: SchemaMetadata = { - hierarchy: { - levels: [ + ...withHierarchy( + [ makeLevel('mission'), makeLevel('goal', { selfRef: true, fieldOn: 'parent', field: 'subgoals', multiple: true }), ], - allowSkipLevels: false, - }, + { allowSkipLevels: false }, + ), }; it('allows goal.subgoals pointing to goals (self-ref)', () => { @@ -93,10 +93,10 @@ describe('validate-graph', () => { describe('hierarchy with selfRef', () => { const hierarchy = ['vision', 'mission', 'goal', 'opportunity', 'solution', 'experiment']; const metadata: SchemaMetadata = { - hierarchy: { - levels: hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), - allowSkipLevels: false, - }, + ...withHierarchy( + hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), + { allowSkipLevels: false }, + ), typeAliases, }; @@ -159,10 +159,10 @@ describe('validate-graph', () => { describe('hierarchy with allowSkipLevels', () => { const hierarchy = ['vision', 'mission', 'goal', 'opportunity', 'solution', 'experiment']; const metadata: SchemaMetadata = { - hierarchy: { - levels: hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), - allowSkipLevels: true, - }, + ...withHierarchy( + hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), + { allowSkipLevels: true }, + ), typeAliases: {}, }; @@ -192,10 +192,10 @@ describe('validate-graph', () => { describe('edge cases', () => { const hierarchy = ['vision', 'mission', 'goal', 'opportunity', 'solution', 'experiment']; const metadata: SchemaMetadata = { - hierarchy: { - levels: hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), - allowSkipLevels: false, - }, + ...withHierarchy( + hierarchy.map((t) => makeLevel(t, { selfRef: ['goal', 'opportunity', 'solution'].includes(t) })), + { allowSkipLevels: false }, + ), typeAliases: {}, }; @@ -232,10 +232,10 @@ describe('validate-graph', () => { describe('violation format', () => { const hierarchy = ['vision', 'mission', 'goal']; const metadata: SchemaMetadata = { - hierarchy: { - levels: hierarchy.map((t) => makeLevel(t)), - allowSkipLevels: false, - }, + ...withHierarchy( + hierarchy.map((t) => makeLevel(t)), + { allowSkipLevels: false }, + ), typeAliases: {}, }; @@ -255,3 +255,54 @@ describe('validate-graph', () => { }); }); }); + +describe('validateHierarchyStructure - multiple hierarchies', () => { + // "work" forbids skipping levels; "skills" allows it. + const work = makeHierarchy([makeLevel('goal'), makeLevel('project'), makeLevel('task')], { name: 'work' }); + const skills = makeHierarchy([makeLevel('area'), makeLevel('skill'), makeLevel('technique')], { + name: 'skills', + allowSkipLevels: true, + }); + const metadata: SchemaMetadata = { hierarchy: work, hierarchies: [work, skills] }; + + const validate = (baseNodes: BaseNode[]) => { + const { nodes } = resolveGraphEdges(baseNodes, metadata); + return { nodes, violations: validateHierarchyStructure(nodes, metadata) }; + }; + + it('tags each hierarchy edge with its hierarchy name', () => { + const { nodes } = validate([ + makeNode('Ship', 'goal'), + makeNode('Launch', 'project', { parent: '[[Ship]]' }), + makeNode('Engineering', 'area'), + makeNode('Testing', 'skill', { parent: '[[Engineering]]' }), + ]); + const edges = nodes.flatMap((n) => n.resolvedParents.map((r) => [n.title, r.hierarchy])); + expect(edges).toEqual([ + ['Launch', 'work'], + ['Testing', 'skills'], + ]); + }); + + it("checks skip levels against each hierarchy's own setting", () => { + const { violations } = validate([ + makeNode('Ship', 'goal'), + makeNode('Write docs', 'task', { parent: '[[Ship]]' }), + makeNode('Engineering', 'area'), + makeNode('Mocking', 'technique', { parent: '[[Engineering]]' }), + ]); + expect(violations.map((v) => v.description)).toEqual([ + 'Invalid parent: task "Write docs" cannot have goal "Ship" as parent', + ]); + }); + + it('rejects a parent from another hierarchy', () => { + const { violations } = validate([ + makeNode('Engineering', 'area'), + makeNode('Launch', 'project', { parent: '[[Engineering]]' }), + ]); + expect(violations.map((v) => v.description)).toEqual([ + 'Invalid parent: project "Launch" cannot have area "Engineering" as parent', + ]); + }); +}); diff --git a/tests/space-graph.test.ts b/tests/space-graph.test.ts index 81bb7c4..9460035 100644 --- a/tests/space-graph.test.ts +++ b/tests/space-graph.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'bun:test'; import { buildSpaceGraph } from '../src/space-graph'; import type { SpaceNode } from '../src/types'; -import { makeLevel, makeParentRef } from './test-helpers'; +import { makeHierarchy, makeLevel, makeParentRef } from './test-helpers'; const levels = [makeLevel('goal'), makeLevel('opportunity'), makeLevel('solution')]; @@ -22,7 +22,7 @@ describe('buildSpaceGraph', () => { describe('nodes map', () => { it('builds a map of all nodes keyed by title', () => { const goal = makeNode('My Goal', 'goal'); - const graph = buildSpaceGraph([goal], levels); + const graph = buildSpaceGraph([goal], makeHierarchy(levels)); expect(graph.nodes.get('My Goal')).toBe(goal); expect(graph.nodes.size).toBe(1); }); @@ -30,7 +30,7 @@ describe('buildSpaceGraph', () => { it('preserves insertion order', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); - const graph = buildSpaceGraph([goal, opp], levels); + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect([...graph.nodes.keys()]).toEqual(['My Goal', 'An Opportunity']); }); }); @@ -38,13 +38,13 @@ describe('buildSpaceGraph', () => { describe('classification', () => { it('classifies root-type nodes with no parents as hierarchyRoot', () => { const goal = makeNode('My Goal', 'goal'); - const graph = buildSpaceGraph([goal], levels); + const graph = buildSpaceGraph([goal], makeHierarchy(levels)); expect(graph.hierarchyRoots).toContain(goal); }); it('classifies non-root hierarchy nodes with no parents as orphan', () => { const opp = makeNode('Orphaned Opp', 'opportunity'); - const graph = buildSpaceGraph([opp], levels); + const graph = buildSpaceGraph([opp], makeHierarchy(levels)); expect(graph.orphans).toContain(opp); }); @@ -52,25 +52,25 @@ describe('buildSpaceGraph', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal')]; - const graph = buildSpaceGraph([goal, opp], levels); + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('My Goal')).toContain(opp); }); it('classifies nodes with dangling hierarchy parents as orphan', () => { const opp = makeNode('Orphaned Opp', 'opportunity'); opp.resolvedParents = [makeParentRef('Missing Goal')]; - const graph = buildSpaceGraph([opp], levels); + const graph = buildSpaceGraph([opp], makeHierarchy(levels)); expect(graph.orphans).toContain(opp); }); it('classifies nodes not in hierarchy levels as nonHierarchy', () => { const dashboard = makeNode('My Dashboard', 'dashboard'); - const graph = buildSpaceGraph([dashboard], levels); + const graph = buildSpaceGraph([dashboard], makeHierarchy(levels)); expect(graph.nonHierarchy).toContain(dashboard); }); it('handles empty node list', () => { - const graph = buildSpaceGraph([], levels); + const graph = buildSpaceGraph([], makeHierarchy(levels)); expect(graph.hierarchyRoots).toHaveLength(0); expect(graph.orphans).toHaveLength(0); expect(graph.nonHierarchy).toHaveLength(0); @@ -83,7 +83,7 @@ describe('buildSpaceGraph', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal', { source: 'hierarchy' })]; - const graph = buildSpaceGraph([goal, opp], levels); + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('My Goal')).toContain(opp); }); @@ -91,13 +91,13 @@ describe('buildSpaceGraph', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal', { source: 'relationship' })]; - const graph = buildSpaceGraph([goal, opp], levels); + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('My Goal')).toHaveLength(0); }); it('initialises empty array for leaf nodes', () => { const leaf = makeNode('Leaf', 'solution'); - const graph = buildSpaceGraph([leaf], levels); + const graph = buildSpaceGraph([leaf], makeHierarchy(levels)); expect(graph.hierarchyChildren.get('Leaf')).toEqual([]); }); }); @@ -109,7 +109,7 @@ describe('buildSpaceGraph', () => { const assumption = makeNode('An Assumption', 'assumption'); opp.resolvedParents = [makeParentRef('My Goal', { source: 'hierarchy' })]; assumption.resolvedParents = [makeParentRef('My Goal', { source: 'relationship', field: 'assumptions' })]; - const graph = buildSpaceGraph([goal, opp, assumption], levels); + const graph = buildSpaceGraph([goal, opp, assumption], makeHierarchy(levels)); const children = graph.children.get('My Goal') ?? []; expect(children).toContain(opp); expect(children).toContain(assumption); @@ -118,7 +118,7 @@ describe('buildSpaceGraph', () => { it('populates children map for parents not in the node set', () => { const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('Missing Goal')]; - const graph = buildSpaceGraph([opp], levels); + const graph = buildSpaceGraph([opp], makeHierarchy(levels)); expect(graph.children.get('Missing Goal')).toContain(opp); }); }); @@ -128,28 +128,29 @@ describe('buildSpaceGraph', () => { const goal = makeNode('My Goal', 'goal'); const opp = makeNode('An Opportunity', 'opportunity'); opp.resolvedParents = [makeParentRef('My Goal')]; - const graph = buildSpaceGraph([goal, opp], levels); + const graph = buildSpaceGraph([goal, opp], makeHierarchy(levels)); expect(graph.hierarchyTitles.has('My Goal')).toBe(true); expect(graph.hierarchyTitles.has('An Opportunity')).toBe(true); }); it('includes orphans', () => { const opp = makeNode('Orphaned Opp', 'opportunity'); - const graph = buildSpaceGraph([opp], levels); + const graph = buildSpaceGraph([opp], makeHierarchy(levels)); expect(graph.hierarchyTitles.has('Orphaned Opp')).toBe(true); }); it('excludes non-hierarchy nodes', () => { const dashboard = makeNode('My Dashboard', 'dashboard'); - const graph = buildSpaceGraph([dashboard], levels); + const graph = buildSpaceGraph([dashboard], makeHierarchy(levels)); expect(graph.hierarchyTitles.has('My Dashboard')).toBe(false); }); }); - describe('levels', () => { - it('stores the hierarchy levels used to build the graph', () => { - const graph = buildSpaceGraph([], levels); - expect(graph.levels).toBe(levels); + describe('hierarchy', () => { + it('stores the hierarchy used to build the graph', () => { + const hierarchy = makeHierarchy(levels); + const graph = buildSpaceGraph([], hierarchy); + expect(graph.hierarchy).toBe(hierarchy); }); }); }); diff --git a/tests/test-helpers.ts b/tests/test-helpers.ts index ed2a18c..f10b7d8 100644 --- a/tests/test-helpers.ts +++ b/tests/test-helpers.ts @@ -1,17 +1,21 @@ -import type { BaseNode, HierarchyLevel, Relationship, ResolvedParentRef } from '../src/types'; +import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentRef } from '../src/types'; /** * Creates a ResolvedParentRef with sensible defaults for use in tests. * Override any field to represent specific edge contexts. */ -export const makeParentRef = (title: string, overrides: Partial = {}): ResolvedParentRef => ({ - title, - field: 'parent', - source: 'hierarchy', - selfRef: false, - fieldOn: 'child', - ...overrides, -}); +export const makeParentRef = (title: string, overrides: Partial = {}): ResolvedParentRef => { + const source = overrides.source ?? 'hierarchy'; + return { + title, + field: 'parent', + source, + ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}), + selfRef: false, + fieldOn: 'child', + ...overrides, + }; +}; /** * Creates a HierarchyLevel with defaults matching schema.loadMetadata normalization. @@ -25,6 +29,26 @@ export const makeLevel = (type: string, overrides: Partial = {}) ...overrides, }); +/** + * Creates a named Hierarchy (default name 'main') from normalized levels. + */ +export const makeHierarchy = (levels: HierarchyLevel[], overrides: Partial = {}): Hierarchy => ({ + name: 'main', + levels, + ...overrides, +}); + +/** + * SchemaMetadata fields for a schema whose only hierarchy is its main hierarchy. + */ +export const withHierarchy = ( + levels: HierarchyLevel[], + overrides: Partial = {}, +): { hierarchy: Hierarchy; hierarchies: Hierarchy[] } => { + const hierarchy = makeHierarchy(levels, overrides); + return { hierarchy, hierarchies: [hierarchy] }; +}; + /** * Creates a Relationship with defaults matching schema.loadMetadata normalization. */ diff --git a/tests/validate/general.test.ts b/tests/validate/general.test.ts index 1ba8b44..7751e2d 100644 --- a/tests/validate/general.test.ts +++ b/tests/validate/general.test.ts @@ -6,7 +6,7 @@ import { bundledSchemasDir, createValidator, loadMetadata } from '../../src/sche import { validateGraph } from '../../src/schema/validate-graph'; import type { BaseNode, SpaceNode, UnresolvedRef } from '../../src/types'; import { makePluginContext } from '../helpers/context'; -import { makeLevel } from '../test-helpers'; +import { makeLevel, withHierarchy } from '../test-helpers'; const DEFAULT_SCHEMA_PATH = join(bundledSchemasDir, 'strategy_general.json'); const VALID_DIR = join(import.meta.dir, '../fixtures/general/valid-ost'); @@ -136,7 +136,7 @@ describe('Schema validation', () => { ]; const { nodes: nodes1, unresolvedRefs: refs1 } = resolveGraphEdges(baseNodes, { - hierarchy: { levels: [makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')] }, + ...withHierarchy([makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')]), }); expect(nodes1.find((n) => n.label === 'Another Goal')?.schemaData.parent).toBe('[[anchor_vision#^mission]]'); @@ -172,7 +172,7 @@ describe('Schema validation', () => { ]; const { nodes: nodes2, unresolvedRefs: refs2 } = resolveGraphEdges(baseNodes, { - hierarchy: { levels: [makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')] }, + ...withHierarchy([makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')]), }); const { refErrors } = validateGraph(nodes2, metadata, refs2); @@ -216,7 +216,7 @@ describe('Schema validation', () => { ]; const { nodes: nodes3, unresolvedRefs: refs3 } = resolveGraphEdges(baseNodes, { - hierarchy: { levels: [makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')] }, + ...withHierarchy([makeLevel('vision'), makeLevel('mission'), makeLevel('goal'), makeLevel('solution')]), }); expect(nodes3.find((n) => n.label === 'solution_page.md')?.resolvedParents).toHaveLength(0); diff --git a/tests/validate/relationships.test.ts b/tests/validate/relationships.test.ts index 4b75c9a..05f1b92 100644 --- a/tests/validate/relationships.test.ts +++ b/tests/validate/relationships.test.ts @@ -2,11 +2,11 @@ import { describe, expect, it } from 'bun:test'; import { resolveGraphEdges } from '../../src/read/resolve-graph-edges'; import { validateGraph } from '../../src/schema/validate-graph'; import type { SchemaMetadata } from '../../src/types'; -import { makeLevel, makeNode, makeRelationship } from '../test-helpers'; +import { makeLevel, makeNode, makeRelationship, withHierarchy } from '../test-helpers'; describe('validateGraph - Relationships', () => { const metadata: SchemaMetadata = { - hierarchy: { levels: [makeLevel('opportunity')] }, + ...withHierarchy([makeLevel('opportunity')]), relationships: [makeRelationship('opportunity', 'assumption', { templateFormat: 'table' })], }; @@ -58,7 +58,7 @@ describe('validateGraph - Relationships', () => { it('uses custom field name when fieldOn is child', () => { const metaWithCustomField: SchemaMetadata = { - hierarchy: { levels: [makeLevel('opportunity')] }, + ...withHierarchy([makeLevel('opportunity')]), relationships: [makeRelationship('opportunity', 'assumption', { field: 'linked_opportunity' })], }; @@ -74,7 +74,7 @@ describe('validateGraph - Relationships', () => { it('reports error for custom field pointing to wrong type', () => { const metaWithCustomField: SchemaMetadata = { - hierarchy: { levels: [makeLevel('opportunity')] }, + ...withHierarchy([makeLevel('opportunity')]), relationships: [makeRelationship('opportunity', 'assumption', { field: 'linked_opportunity' })], }; @@ -92,7 +92,7 @@ describe('validateGraph - Relationships', () => { describe('validateGraph — fieldOn: parent', () => { const metadata: SchemaMetadata = { - hierarchy: { levels: [makeLevel('activity')] }, + ...withHierarchy([makeLevel('activity')]), relationships: [makeRelationship('activity', 'task', { field: 'tasks', fieldOn: 'parent', multiple: true })], }; From 0c7deeee44b6e61e30f8a496bab170330f8df121 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sat, 26 Sep 2026 19:25:53 +1000 Subject: [PATCH 2/2] Explicit metadata imports; $ref becomes validation-only - $metadata.imports (schema $ids) is the only way metadata travels; imports are whole-schema and transitive, merged depth-first in order, own metadata last - external $ref / $defs no longer make the referenced schema a metadata provider - one merge rule for rules (id), relationships (parent+type+field), aliases (name) and hierarchies (name): duplicate is an error unless the later entry sets override: true (aliases: { "type": ..., "override": true }) - remove $ref rule imports inside $metadata.rules - bundled strategy_general, strict_ost and knowledge_wiki gain imports Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi --- README.md | 27 +- docs/concepts.md | 6 +- docs/rules.md | 21 +- docs/schema-dialect-update-proposal.md | 4 +- docs/schemas.md | 78 ++--- plugin/.claude-plugin/plugin.json | 2 +- .../structured-context/references/commands.md | 2 +- .../references/schema-authoring.md | 33 +- .../references/schema-design.md | 4 +- schemas/_strategy_general.json | 2 +- .../_structured_context_schema_meta.json | 98 +++--- schemas/knowledge_wiki.json | 1 + schemas/strategy_general.json | 3 +- schemas/strict_ost.json | 1 + src/schema/metadata-contract.ts | 35 +- src/schema/schema.ts | 314 ++++++------------ .../multi-hierarchy/declare-and-ref-root.json | 1 + .../multi-hierarchy/declared-root.json | 1 + .../hierarchy-override-root.json | 20 ++ .../multi-hierarchy/ref-only-root.json | 12 + .../multi-hierarchy/selected-root.json | 1 + .../single-contributed-root.json | 3 + .../multi-hierarchy/unselected-root.json | 3 + .../schema-composition/_duplicate-pack.json | 17 + .../schema-composition/_merge-pack-a.json | 2 +- .../schema-composition/_rule-import-pack.json | 31 -- .../compile/_rule-import-pack.json | 14 - .../compile/rule-import-root.json | 11 - .../schema-composition/conflict-root.json | 7 +- .../duplicate-alias-root.json | 11 + .../duplicate-relationship-root.json | 16 + .../hierarchy-conflict-root.json | 2 +- .../schema-composition/merge-root.json | 10 +- .../schema-composition/override-root.json | 7 +- .../relationship-override-root.json | 35 ++ .../schema-composition/rule-import-root.json | 34 -- tests/schema/schema-composition.test.ts | 70 ++-- 37 files changed, 447 insertions(+), 492 deletions(-) create mode 100644 tests/fixtures/multi-hierarchy/hierarchy-override-root.json create mode 100644 tests/fixtures/multi-hierarchy/ref-only-root.json create mode 100644 tests/fixtures/schema-composition/_duplicate-pack.json delete mode 100644 tests/fixtures/schema-composition/_rule-import-pack.json delete mode 100644 tests/fixtures/schema-composition/compile/_rule-import-pack.json delete mode 100644 tests/fixtures/schema-composition/compile/rule-import-root.json create mode 100644 tests/fixtures/schema-composition/duplicate-alias-root.json create mode 100644 tests/fixtures/schema-composition/duplicate-relationship-root.json create mode 100644 tests/fixtures/schema-composition/relationship-override-root.json delete mode 100644 tests/fixtures/schema-composition/rule-import-root.json diff --git a/README.md b/README.md index dd55729..a89ab5a 100644 --- a/README.md +++ b/README.md @@ -183,38 +183,43 @@ Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a With `fieldOn: "parent"`, embedded child nodes (parsed from a matching heading's list or table) are appended as wikilinks to the parent's `field` array, rather than receiving a `parent` field. This matches schemas where the content model naturally lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`). -Metadata is composable across `$ref` graphs: -- `hierarchy`: each schema file declares at most one hierarchy, and every declared hierarchy is kept as a separate named hierarchy (see [Multiple hierarchies](#multiple-hierarchies)) -- `aliases` are shallow-merged (later wins) -- `rules` merge by `id`; conflicts error unless the later rule sets `override: true` -- each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it -- `$metadata.rules` supports `$ref` imports for reusable rule packs -- `relationships` are collected from all files +`$ref` reuses JSON Schema definitions for validation only; it brings no metadata. Metadata is composed only through explicit imports: + +```json5 +"$metadata": { "imports": ["sctx://_strategy_general"] } +``` + +- An import brings the whole schema's `$metadata`, and is transitive (the imported schema's own imports come too). +- Merge order: imports in order, depth-first, then the schema's own metadata last. +- One rule for every key: a duplicate rule `id`, alias, relationship (same `parent`/`type`/`field`) or hierarchy `name` is an error unless the later entry sets `override: true` (for an alias, write the value as `{ "type": "goal", "override": true }`). +- `hierarchy`: each schema file declares at most one hierarchy, and every imported hierarchy is kept as a separate named hierarchy (see [Multiple hierarchies](#multiple-hierarchies)) +- Each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it. If no file defines `hierarchy`, hierarchy-specific checks are skipped. #### Multiple hierarchies -A space can have several hierarchies by composing schemas that each declare one. For example, a root schema might compose a work hierarchy (`goal → task`) and a skills hierarchy (`skill_area → skill`). +A space can have several hierarchies by importing schemas that each declare one. For example, a root schema might import a work hierarchy (`goal → task`) and a skills hierarchy (`skill_area → skill`). - **Naming**: a hierarchy's `name` defaults to the declaring schema's file stem (e.g. `_skills` for `_skills.json`). Set `"name"` in `$metadata.hierarchy` to override it. -- **Main hierarchy**: if the root schema declares a hierarchy, it is the main one. If the root declares none and exactly one is composed, that one is the main hierarchy. If several are composed, the root must select one: +- **Main hierarchy**: if the root schema declares a hierarchy, it is the main one. If the root declares none and exactly one is imported, that one is the main hierarchy. If several are imported, the root must select one: ```json5 "$metadata": { + "imports": ["sctx://_work", "sctx://_skills"], "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" } } ``` A root may either declare a hierarchy or select one with `$ref`, not both. -- **Each type belongs to at most one hierarchy.** A type in two hierarchies is an error, so a composing schema cannot redefine a composed hierarchy's levels. +- **Each type belongs to at most one hierarchy.** A type in two hierarchies is an error. To change an imported hierarchy's levels, declare a hierarchy with the same `name` and `"override": true`. - **Validation** (layering, parent types, skip levels, orphans) runs per hierarchy. Relationships can connect types across hierarchies. - The main hierarchy drives `space_on_a_page` parsing, hierarchy embedding, `template-sync`, and the default `show`/`diagram`/`render` output. Use `--hierarchy ` to render another one. **Customizing Schemas:** - **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`). - **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content. -- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata. +- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets that metadata only by listing the partial in `$metadata.imports`. - **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "http://json-schema.org/draft-07/schema#"` so it validates standalone as plain JSON Schema. - **Loading priority**: Partial schemas are loaded from both the default schema directory and the directory of your specified target schema. - **Transitive resolution**: `$ref` chains are resolved recursively across files/schemas (including nested `allOf` usage in partials). diff --git a/docs/concepts.md b/docs/concepts.md index c87dceb..82e1c97 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -123,7 +123,7 @@ A **schema** defines the valid structure for nodes in a `space`: the fields, typ The schema handles structural validation. Cross-node and workflow checks are handled by executable `rules` defined in `$metadata.rules`. -Schemas are composable: structural definitions and metadata can be sourced across `$ref` graphs, then merged deterministically (root metadata applied last, each declared hierarchy kept as a separate named hierarchy, aliases merged, rules merged by `id` with explicit override semantics). +Schemas are composable. Structural definitions are reused with `$ref` (validation only). Metadata is reused only by listing schema `$id`s in `$metadata.imports`: imports merge transitively, in order, with the schema's own metadata last. Hierarchies, relationships, aliases and rules all follow one rule — a duplicate is an error unless the later entry sets `override: true` — and each declared hierarchy is kept as a separate named hierarchy. ### Rules @@ -162,9 +162,9 @@ The **hierarchy** is the ordered list of node types in a space, from root to lea The hierarchy is modelled as a layered DAG: a non-root node may have zero parents (orphaned), one parent, or multiple parents. The `show` command renders this as an indented tree, marking repeated nodes with `(*)` where the subtree is already shown elsewhere. -A space may have **several hierarchies**, one for each composed schema that declares one. Each hierarchy has a **name** (defaulting to the declaring schema's file stem), and each type belongs to at most one hierarchy. Structural validation runs per hierarchy; relationships may connect types across hierarchies. +A space may have **several hierarchies**, one for each imported schema that declares one. Each hierarchy has a **name** (defaulting to the declaring schema's file stem), and each type belongs to at most one hierarchy. Structural validation runs per hierarchy; relationships may connect types across hierarchies. -The **main hierarchy** is the one declared by the root schema; failing that, the only composed hierarchy; failing that, the one the root selects with `"hierarchy": { "$ref": ... }`. The main hierarchy drives `space on a page` parsing, hierarchy embedding, template sync, and default rendering. `show`, `diagram` and `render` take `--hierarchy ` to render another. See [docs/schemas.md](schemas.md#multiple-hierarchies). +The **main hierarchy** is the one declared by the root schema; failing that, the only imported hierarchy; failing that, the one the root selects with `"hierarchy": { "$ref": ... }`. The main hierarchy drives `space on a page` parsing, hierarchy embedding, template sync, and default rendering. `show`, `diagram` and `render` take `--hierarchy ` to render another. See [docs/schemas.md](schemas.md#multiple-hierarchies). Each non-root level uses the shared `field`, `fieldOn`, and `multiple` edge options (see [Graph edges](#graph-edges)). Hierarchy-specific options: diff --git a/docs/rules.md b/docs/rules.md index 4019e07..303b37d 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -107,28 +107,21 @@ Inside `nodes[...]`, bare names refer to each candidate node. Use `$$` to refere $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) ``` -## Rule imports (`$ref`) +## Reusing rules -`$metadata.rules` can include `$ref` entries that import: -- one rule -- a rule-set object with `rules: []` - -Example: +To share rules, put them in a schema's `$metadata.rules` and list that schema's `$id` in `$metadata.imports`. An import brings the whole schema's metadata, including its own imports: ```json5 -"rules": [ - { "$ref": "sctx://rule-pack#/$defs/workflowRule" }, - { "$ref": "sctx://rule-pack#/$defs/coreRuleSet" } -] +"$metadata": { + "imports": ["sctx://_rule-pack"] +} ``` -Imported entries are normalized into the same flat runtime list. - ## Merge and conflict behavior -When metadata is composed across `$ref`: +When metadata is merged from imports (imports in order, then the schema's own metadata): - Rules are merged by `id`. -- Different payloads for the same `id` are an error by default. +- A duplicate `id` is an error. - A later rule may replace an earlier one only with `override: true`. Example override: diff --git a/docs/schema-dialect-update-proposal.md b/docs/schema-dialect-update-proposal.md index 52aa4cb..40fa05d 100644 --- a/docs/schema-dialect-update-proposal.md +++ b/docs/schema-dialect-update-proposal.md @@ -26,9 +26,9 @@ Issue #28 opened the door to reorganize schema metadata, rules, and composition - Top-level `"$metadata"` is the shipped keyword. - Hierarchy shape is `"$metadata.hierarchy.levels"` with optional `allowSkipLevels`. - Rules are a flat `"$metadata.rules"` array with per-rule `category`. -- Metadata is composed across `$ref` graph (DFS, root last) with deterministic merge semantics. +- Metadata is composed across `$ref` graph (DFS, root last) with deterministic merge semantics. *(Superseded by #121: metadata is composed only through explicit `$metadata.imports`; `$ref` is validation-only. See [schemas.md](schemas.md#composition-and-merge-semantics).)* - Rule conflict policy is error by default; explicit `override: true` enables replacement. -- `$metadata.rules` supports `$ref` imports for specific rules and rule sets. +- `$metadata.rules` supports `$ref` imports for specific rules and rule sets. *(Removed by #121: import a rules-only schema via `$metadata.imports` instead.)* - Metadata contract source is `src/metadata-contract.ts` (`json-schema-to-ts` types), with generated metaschema artifact in `schemas/generated/_ost_tools_schema_meta.json`. ## Decision Areas and Recommendations diff --git a/docs/schemas.md b/docs/schemas.md index 3c98860..8084f71 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -46,7 +46,7 @@ Main types: - `solution` - `assumption_test` -This schema composes shared structural defs and strict metadata/rules from partials. +This schema reuses shared structural defs from partials via `$ref` and imports its hierarchy and rules from `_ost_strict` via `$metadata.imports`. ## Custom format annotations @@ -120,12 +120,14 @@ Top-level metadata shape: | Field | Type | Notes | |---|---|---| +| `imports` | `string[]` | Optional; `$id`s of schemas whose metadata is merged into this one. See [Composition and merge semantics](#composition-and-merge-semantics) | | `hierarchy` | object | Optional; declares this schema's hierarchy, or (root schema only) selects the main hierarchy with `{ "$ref": "#/$metadata/hierarchy" }`. See [Multiple hierarchies](#multiple-hierarchies) | | `hierarchy.name` | `string` | Optional short name; defaults to the declaring schema's file stem | +| `hierarchy.override` | `boolean` | Optional; replaces an imported hierarchy with the same name | | `hierarchy.levels` | `(string \| HierarchyLevel)[]` | Ordered root→leaf types | | `hierarchy.allowSkipLevels` | `boolean` | Optional; allows parent to be any ancestor level | -| `relationships` | `Relationship[]` | Optional; defines related node links outside the primary hierarchy | -| `aliases` | `Record` | Optional type alias map | +| `relationships` | `Relationship[]` | Optional; defines related node links outside the primary hierarchy. A relationship may set `override: true` | +| `aliases` | `Record` | Optional type alias map. Use `{ "type": "goal", "override": true }` to replace an imported alias | | `rules` | `Rule[]` | Optional flat rule array | ### Relationships @@ -253,34 +255,48 @@ With this config, an application page may include `### capability` with wikilink ## Composition and merge semantics -Metadata is composed across the `$ref` graph with deterministic behavior: +`$ref` and `$defs` are for **validation only**: a `$ref` to another schema (or to one of its `$defs`) reuses its JSON Schema definitions but brings none of its `$metadata`. -1. Traverse external `$ref` graph in DFS order. -2. Apply root schema metadata last. +Metadata travels only through **`$metadata.imports`**, a list of schema `$id`s: -Merge rules: -- `hierarchy`: not merged. Each declared hierarchy is kept as a separate named hierarchy (see below). -- `aliases`: shallow merged; later file wins per key. -- `relationships`: collected from all files; order preserved. -- `rules`: merged by `id`. -- Duplicate rule `id` with different payload errors by default. -- A later rule may replace an earlier one only with `"override": true`. +```json5 +"$metadata": { + "imports": ["sctx://_strategy_general"], + "rules": [ /* this schema's own rules */ ] +} +``` + +- An import brings the imported schema's whole `$metadata` (hierarchy, relationships, aliases, rules). +- Imports are transitive: an imported schema's own imports come too. +- Merge order: imports in the order listed, depth-first, then the schema's own metadata last. Each schema is merged at most once. +- An unresolvable import `$id` is an error. + +One merge rule applies to every key. **A duplicate is an error unless the later entry sets `"override": true`**, in which case it replaces the earlier entry. + +| Key | Identity | How to mark `override` | +|---|---|---| +| `rules` | `id` | `"override": true` on the rule | +| `relationships` | `parent` + `type` + `field` (default `"parent"`) | `"override": true` on the relationship | +| `aliases` | alias name | `{ "type": "", "override": true }` as the alias value | +| `hierarchy` | `name` | `"override": true` on the hierarchy declaration | + +Overriding a hierarchy by name is how a schema replaces the levels of an imported hierarchy (declare it with the same `name` and `"override": true`). When no provider defines `hierarchy`, hierarchy-based behavior is disabled (`show` tree shape, hierarchy validation, parent-edge checks). `space_on_a_page` parsing still requires hierarchy and will error without it. ### Multiple hierarchies -A space has several hierarchies when its schema composes several schemas that each declare one. Each schema declares at most one hierarchy. +A space has several hierarchies when its schema imports several schemas that each declare one. Each schema declares at most one hierarchy. -- **Every `$ref`'d schema contributes its hierarchy.** Each is kept as a separate named hierarchy; levels are never merged. -- **Naming.** `hierarchy.name` defaults to the declaring schema's file stem (`_ost_strict` for `_ost_strict.json`). Names must be unique. +- **Every imported schema contributes its hierarchy.** Each is kept as a separate named hierarchy; levels are never merged. +- **Naming.** `hierarchy.name` defaults to the declaring schema's file stem (`_ost_strict` for `_ost_strict.json`). A duplicate name is an error unless the later hierarchy sets `"override": true`. - **Main hierarchy.** - If the root schema declares a hierarchy, it is the main hierarchy. - - If the root declares none and exactly one hierarchy is contributed, that one is the main hierarchy (for example `strict_ost`, whose hierarchy comes from `_ost_strict`). - - If the root declares none and several are contributed, the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }`, otherwise loading the schema fails. + - If the root declares none and exactly one hierarchy is imported, that one is the main hierarchy (for example `strict_ost`, which imports `_ost_strict`). + - If the root declares none and several are imported, the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }`, otherwise loading the schema fails. - A root that both declares a hierarchy and uses `$ref` is an error. -- **Each type belongs to at most one hierarchy.** A type claimed by two hierarchies is an error. A composing schema therefore cannot redefine the levels of a hierarchy it composes; it declares a hierarchy over its own types instead. -- **Selections are not contributed.** A `hierarchy: { "$ref" }` selection only applies when its schema is the root, so a composed schema stays usable standalone as another space's root. +- **Each type belongs to at most one hierarchy.** A type claimed by two hierarchies is an error. To change an imported hierarchy's levels, override it by name. +- **Selections are not imported.** A `hierarchy: { "$ref" }` selection only applies when its schema is the root, so an imported schema stays usable standalone as another space's root. ```json5 { @@ -293,6 +309,7 @@ A space has several hierarchies when its schema composes several schemas that ea ], "$metadata": { // _work.json and _skills.json each declare a hierarchy; select the main one. + "imports": ["sctx://_work", "sctx://_skills"], "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" } } } @@ -308,23 +325,6 @@ How hierarchies are used: | `show`, `diagram`, `render` | Main hierarchy by default; `--hierarchy ` selects another | | `resolvedParents` | Hierarchy edges carry the `hierarchy` name | -### Rule imports via `$ref` - -Inside `$metadata.rules`, entries can be inline rules or `$ref` imports: - -```json5 -"rules": [ - { "$ref": "sctx://my-pack#/$defs/workflowRule" }, - { "$ref": "sctx://my-pack#/$defs/ruleSet" } -] -``` - -Import targets may be: -- a single rule object -- an object containing `rules: []` - -Imported rules are normalized into one executable flat list before validation. - ### Override example ```json5 @@ -351,8 +351,8 @@ Imported rules are normalized into one executable flat list before validation. - Local partial `$id` values must not collide with bundled IDs. - `$ref` resolution is transitive across files. - Partials with no `$metadata` should prefer `$schema: "http://json-schema.org/draft-07/schema#"` so they validate standalone as plain JSON Schema fragments. -- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference these via `$ref` rather than redefining common entity types. -- **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata. +- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference their entity types via `$ref` rather than redefining them. +- **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets it only by listing the partial in `$metadata.imports`; `$ref` alone brings none. ## Editor expectations diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 016af37..c8e1cba 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.11.3", + "version": "0.11.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 d5e467f..06f4a21 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -49,7 +49,7 @@ If those are misconfigured for your content, output will appear flatter than exp **`--filter`** accepts either a named view from the space config (`views` key) or an inline filter expression. Only matching nodes are shown in the tree. -**`--hierarchy`** names the hierarchy to render when the schema composes several (default: the main +**`--hierarchy`** names the hierarchy to render when the schema imports several (default: the main hierarchy). `schemas show --space ` lists the hierarchy names. `diagram` and `render` accept it too. ```bash diff --git a/plugin/skills/structured-context/references/schema-authoring.md b/plugin/skills/structured-context/references/schema-authoring.md index 22ec3b1..e1a2dfe 100644 --- a/plugin/skills/structured-context/references/schema-authoring.md +++ b/plugin/skills/structured-context/references/schema-authoring.md @@ -68,30 +68,23 @@ Rules are a flat array. Each rule's `category` (`validation`, `coherence`, `work ## Metadata composition semantics -Across `$ref` graphs: -- metadata providers are traversed DFS, root metadata applied last -- each schema declares at most one `hierarchy`; every composed schema's hierarchy is kept as a separate named hierarchy (`hierarchy.name`, default: the declaring file's stem) -- each type belongs to at most one hierarchy — a composing schema cannot redefine a composed hierarchy's levels -- main hierarchy: the root's own; else the only composed one; else the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }` (declaring and selecting at once is an error) -- the main hierarchy drives `space_on_a_page` parsing, embedding, `template-sync` and default rendering; validation runs per hierarchy -- `aliases` shallow-merge (later wins) -- `rules` merge by `id` -- duplicate rule IDs with different payloads error unless later rule sets `override: true` - -## Rule imports in `$metadata.rules` - -Rule entries may be inline or `$ref` imports: +`$ref`/`$defs` are validation-only: a `$ref` brings no metadata. Metadata travels only via `$metadata.imports` (schema `$id`s): ```json5 -"rules": [ - { "$ref": "sctx://my-rule-pack#/$defs/workflowRule" }, - { "$ref": "sctx://my-rule-pack#/$defs/ruleSet" } -] +"$metadata": { "imports": ["sctx://_strategy_general"] } ``` -Import targets can be: -- single rule object -- object with `rules: []` +- an import brings the whole schema's metadata and is transitive; merge order is imports in order (depth-first), then the schema's own metadata +- one merge rule for every key: a duplicate is an error unless the later entry sets `override: true` + - rules by `id` (`"override": true` on the rule) + - relationships by `parent` + `type` + `field` (`"override": true` on the relationship) + - aliases by name (value `{ "type": "goal", "override": true }`) + - hierarchies by `name` (`"override": true` on the hierarchy — how you change an imported hierarchy's levels) +- each schema declares at most one `hierarchy`; every imported hierarchy is kept as a separate named hierarchy (`hierarchy.name`, default: the declaring file's stem) +- each type belongs to at most one hierarchy +- main hierarchy: the root's own; else the only imported one; else the root must select one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }` (declaring and selecting at once is an error) +- the main hierarchy drives `space_on_a_page` parsing, embedding, `template-sync` and default rendering; validation runs per hierarchy +- to share rules, put them in a schema and import it (there are no `$ref` entries in `$metadata.rules`) ## `fieldMap` in config diff --git a/plugin/skills/structured-context/references/schema-design.md b/plugin/skills/structured-context/references/schema-design.md index 1d6d631..4503ad8 100644 --- a/plugin/skills/structured-context/references/schema-design.md +++ b/plugin/skills/structured-context/references/schema-design.md @@ -41,8 +41,8 @@ For a mixed graph (some hierarchical, some lateral entities), put the main chain and include lateral types in `oneOf` without hierarchy constraints. If the content has a second, independent tree (e.g. a skills tree alongside a work hierarchy), declare -each tree's hierarchy in its own partial and compose both. Each type may belong to only one hierarchy; -if several are composed, the root selects the main one with +each tree's hierarchy in its own partial and list both in `$metadata.imports`. Each type may belong to only one hierarchy; +if several are imported, the root selects the main one with `"hierarchy": { "$ref": "#/$metadata/hierarchy" }`. Relationships can link the trees. ### 2a. Adjacent Relationships vs Primary Hierarchy diff --git a/schemas/_strategy_general.json b/schemas/_strategy_general.json index 39ad6cd..bf5eefa 100644 --- a/schemas/_strategy_general.json +++ b/schemas/_strategy_general.json @@ -3,7 +3,7 @@ "$id": "sctx://_strategy_general", // Shared entity definitions for strategy-general schemas. // Provides a hierarchy, aliases, relationships, and entity type $defs. - // Composing schemas contribute this hierarchy alongside any others they compose. + // Schemas that import this partial get its metadata; a $ref to its $defs alone brings none. "$metadata": { "hierarchy": { "levels": [ diff --git a/schemas/generated/_structured_context_schema_meta.json b/schemas/generated/_structured_context_schema_meta.json index 4327ff9..4989e5e 100644 --- a/schemas/generated/_structured_context_schema_meta.json +++ b/schemas/generated/_structured_context_schema_meta.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "title": "structured-context schema dialect", - "description": "Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.", + "description": "Extends JSON Schema Draft-07 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.", "type": "object", "allOf": [ { @@ -13,6 +13,13 @@ "$metadata": { "type": "object", "properties": { + "imports": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, "hierarchy": { "oneOf": [ { @@ -22,6 +29,9 @@ "type": "string", "minLength": 1 }, + "override": { + "type": "boolean" + }, "levels": { "type": "array", "minItems": 1, @@ -140,6 +150,9 @@ "type": "string", "minLength": 1 } + }, + "override": { + "type": "boolean" } }, "required": ["parent", "type"], @@ -149,62 +162,65 @@ "aliases": { "type": "object", "additionalProperties": { - "type": "string", - "minLength": 1 - } - }, - "rules": { - "type": "array", - "items": { "oneOf": [ + { + "type": "string", + "minLength": 1 + }, { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "category": { - "enum": ["validation", "coherence", "workflow", "best-practice"] - }, - "severity": { - "enum": ["error", "warning", "info"] - }, - "description": { - "type": "string", - "minLength": 1 - }, - "check": { - "type": "string", - "minLength": 1 - }, "type": { "type": "string", "minLength": 1 }, - "scope": { - "enum": ["global"] - }, "override": { "type": "boolean" } }, - "required": ["id", "category", "description", "check"], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "$ref": { - "type": "string", - "minLength": 1 - } - }, - "required": ["$ref"], + "required": ["type"], "additionalProperties": false } ] } + }, + "rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "category": { + "enum": ["validation", "coherence", "workflow", "best-practice"] + }, + "severity": { + "enum": ["error", "warning", "info"] + }, + "description": { + "type": "string", + "minLength": 1 + }, + "check": { + "type": "string", + "minLength": 1 + }, + "type": { + "type": "string", + "minLength": 1 + }, + "scope": { + "enum": ["global"] + }, + "override": { + "type": "boolean" + } + }, + "required": ["id", "category", "description", "check"], + "additionalProperties": false + } } }, "additionalProperties": false diff --git a/schemas/knowledge_wiki.json b/schemas/knowledge_wiki.json index 1708aaa..69f0b23 100644 --- a/schemas/knowledge_wiki.json +++ b/schemas/knowledge_wiki.json @@ -3,6 +3,7 @@ "$id": "sctx://knowledge_wiki", "title": "Knowledge Wiki", "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source pages, concept pages, syntheses, and notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).", + "$metadata": { "imports": ["sctx://_knowledge_wiki"] }, "allOf": [{ "$ref": "sctx://_knowledge_wiki" }], "oneOf": [ { "$ref": "sctx://_knowledge_wiki#/$defs/source" }, diff --git a/schemas/strategy_general.json b/schemas/strategy_general.json index 266b260..d445575 100644 --- a/schemas/strategy_general.json +++ b/schemas/strategy_general.json @@ -2,7 +2,8 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx://strategy_general", "title": "Strategy and opportunity ladder", - "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Its hierarchy is contributed by the partial.", + "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Imports the partial's hierarchy, aliases, relationships and rules.", + "$metadata": { "imports": ["sctx://_strategy_general"] }, "allOf": [{ "$ref": "sctx://_strategy_general" }], "oneOf": [ { "$ref": "sctx://_strategy_general#/$defs/dashboard" }, diff --git a/schemas/strict_ost.json b/schemas/strict_ost.json index be9adc7..a50a95a 100644 --- a/schemas/strict_ost.json +++ b/schemas/strict_ost.json @@ -6,6 +6,7 @@ // and at producttalk.org. // Structure: outcome → opportunity → solution → assumption test "description": "Validates frontmatter for space node files following the canonical 4-level OST structure: outcome → opportunity → solution → assumption test", + "$metadata": { "imports": ["sctx://_ost_strict"] }, "oneOf": [ { "type": "object", diff --git a/src/schema/metadata-contract.ts b/src/schema/metadata-contract.ts index aa1a4a7..11ff72d 100644 --- a/src/schema/metadata-contract.ts +++ b/src/schema/metadata-contract.ts @@ -72,6 +72,7 @@ const HIERARCHY_SCHEMA = { type: 'object', properties: { name: { type: 'string', minLength: 1 }, + override: { type: 'boolean' }, levels: { type: 'array', minItems: 1, @@ -92,15 +93,37 @@ const RELATIONSHIP_SCHEMA = { type: { type: 'string', minLength: 1 }, ...EDGE_PROPS, ...EMBEDDING_PROPS, + override: { type: 'boolean' }, }, required: ['parent', 'type'], additionalProperties: false, } as const; +/** An alias target: a type name, or `{ type, override: true }` to replace an imported alias. */ +const ALIAS_SCHEMA = { + oneOf: [ + { type: 'string', minLength: 1 }, + { + type: 'object', + properties: { + type: { type: 'string', minLength: 1 }, + override: { type: 'boolean' }, + }, + required: ['type'], + additionalProperties: false, + }, + ], +} as const; + export const METADATA_SCHEMA = { type: 'object', properties: { - // Either declares this schema's hierarchy, or (root schema only) selects a contributed one via $ref. + // $ids of schemas whose metadata (and their imports' metadata) is merged into this schema's. + imports: { + type: 'array', + items: { type: 'string', minLength: 1 }, + }, + // Either declares this schema's hierarchy, or (root schema only) selects an imported one via $ref. hierarchy: { oneOf: [HIERARCHY_SCHEMA, REF_SCHEMA], }, @@ -110,13 +133,11 @@ export const METADATA_SCHEMA = { }, aliases: { type: 'object', - additionalProperties: { type: 'string', minLength: 1 }, + additionalProperties: ALIAS_SCHEMA, }, rules: { type: 'array', - items: { - oneOf: [RULE_SCHEMA, REF_SCHEMA], - }, + items: RULE_SCHEMA, }, }, additionalProperties: false, @@ -126,7 +147,8 @@ export const DIALECT_META_SCHEMA = { $schema: 'http://json-schema.org/draft-07/schema#', $id: SCHEMA_META_ID, title: 'structured-context schema dialect', - description: 'Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.', + description: + 'Extends JSON Schema Draft-07 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.', type: 'object', allOf: [{ $ref: 'http://json-schema.org/draft-07/schema#' }], properties: { @@ -142,4 +164,3 @@ export type SharedEdgeFields = FromSchema; export type SharedEmbeddingFields = FromSchema; export type Rule = FromSchema; export type MetadataRef = FromSchema; -export type RuleEntry = Rule | MetadataRef; diff --git a/src/schema/schema.ts b/src/schema/schema.ts index f61bc7f..b897950 100644 --- a/src/schema/schema.ts +++ b/src/schema/schema.ts @@ -1,17 +1,9 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'; import { basename, dirname, extname, join, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; -import { isDeepStrictEqual } from 'node:util'; import Ajv, { type AnySchemaObject, type ValidateFunction } from 'ajv'; import JSON5 from 'json5'; -import type { - Hierarchy, - HierarchyLevel, - RuleCategory, - RuleSeverity, - SchemaMetadata, - SchemaWithMetadata, -} from '../types'; +import type { Hierarchy, HierarchyLevel, SchemaMetadata, SchemaWithMetadata } from '../types'; import { DIALECT_META_SCHEMA, METADATA_SCHEMA, @@ -20,7 +12,6 @@ import { type MetadataContractRelationship, type MetadataRef, type Rule, - type RuleEntry, SCHEMA_META_ID, } from './metadata-contract'; import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs'; @@ -139,10 +130,6 @@ interface MetadataProvider { metadata: MetadataContract; } -const RULE_CATEGORIES = new Set(['validation', 'coherence', 'workflow', 'best-practice']); -const RULE_SEVERITIES = new Set(['error', 'warning', 'info']); -const RULE_ALLOWED_KEYS = new Set(['id', 'category', 'severity', 'description', 'check', 'type', 'scope', 'override']); - function readTopLevelMetadata(schema: AnySchemaObject): MetadataContract | undefined { const metadata = schema.$metadata; if (!isObject(metadata)) return undefined; @@ -191,62 +178,35 @@ function resolveMetadataRef( }; } -function collectExternalRefIdsInOrder(schema: unknown): string[] { - const refs: string[] = []; - const seen = new Set(); - - const walk = (value: unknown): void => { - if (!isObject(value)) return; - for (const [key, child] of Object.entries(value)) { - if (key === '$ref' && typeof child === 'string' && !child.startsWith('#')) { - const schemaId = child.split('#', 1)[0] ?? child; - if (!seen.has(schemaId)) { - seen.add(schemaId); - refs.push(schemaId); - } - continue; - } - walk(child); - } - }; - - walk(schema); - return refs; -} - +/** + * Collect metadata providers in merge order: each schema's `$metadata.imports` depth-first, in + * order, then the schema's own metadata. Each schema contributes at most once. `$ref` does not + * import metadata. + */ function collectMetadataProviders( rootSchema: AnySchemaObject, schemaRefRegistry: Map, ): MetadataProvider[] { const providers: MetadataProvider[] = []; - const visitedSchemaIds = new Set(); - - const walk = (schema: AnySchemaObject): void => { - const refs = collectExternalRefIdsInOrder(schema); - for (const schemaId of refs) { - if (visitedSchemaIds.has(schemaId)) continue; - visitedSchemaIds.add(schemaId); - - const referencedSchema = schemaRefRegistry.get(schemaId); - if (!referencedSchema) continue; - - walk(referencedSchema); - - const metadata = readTopLevelMetadata(referencedSchema); - if (metadata) { - providers.push({ schemaId, schema: referencedSchema, metadata }); + const rootSchemaId = typeof rootSchema.$id === 'string' ? rootSchema.$id : '(root schema)'; + const visitedSchemaIds = new Set([rootSchemaId]); + + const walk = (schema: AnySchemaObject, schemaId: string): void => { + const metadata = readTopLevelMetadata(schema); + if (!metadata) return; + for (const importId of metadata.imports ?? []) { + if (visitedSchemaIds.has(importId)) continue; + visitedSchemaIds.add(importId); + const importedSchema = schemaRefRegistry.get(importId); + if (!importedSchema) { + throw new Error(`Cannot resolve import "${importId}" in schema "${schemaId}".`); } + walk(importedSchema, importId); } + providers.push({ schemaId, schema, metadata }); }; - walk(rootSchema); - - const rootMetadata = readTopLevelMetadata(rootSchema); - if (rootMetadata) { - const rootSchemaId = typeof rootSchema.$id === 'string' ? rootSchema.$id : '(root schema)'; - providers.push({ schemaId: rootSchemaId, schema: rootSchema, metadata: rootMetadata }); - } - + walk(rootSchema, rootSchemaId); return providers; } @@ -255,181 +215,95 @@ function isRefEntry(value: unknown): value is MetadataRef { return typeof value.$ref === 'string' && value.$ref.length > 0 && Object.keys(value).length === 1; } -function isMetadataRule(value: unknown): value is Rule { - if (!isObject(value)) return false; - const record = value as Record; - - if (typeof record.id !== 'string' || record.id.length === 0) return false; - if (typeof record.category !== 'string' || !RULE_CATEGORIES.has(record.category as RuleCategory)) return false; - if (typeof record.description !== 'string' || record.description.length === 0) return false; - if (typeof record.check !== 'string' || record.check.length === 0) return false; - - if ('type' in record && (typeof record.type !== 'string' || record.type.length === 0)) return false; - if ('severity' in record && !RULE_SEVERITIES.has(record.severity as RuleSeverity)) return false; - if ('scope' in record && record.scope !== 'global') return false; - if ('override' in record && typeof record.override !== 'boolean') return false; - - for (const key of Object.keys(record)) { - if (!RULE_ALLOWED_KEYS.has(key)) return false; - } - - return true; -} - -function resolveRuleEntries( - ruleEntry: RuleEntry, - provider: MetadataProvider, - schemaRefRegistry: Map, - stack: Set, -): Rule[] { - if (isMetadataRule(ruleEntry)) { - return [ruleEntry]; - } - - if (!isRefEntry(ruleEntry)) { - throw new Error(`Invalid rule entry in metadata from "${provider.schemaId}".`); - } - - const target = resolveMetadataRef(ruleEntry.$ref, provider.schema, schemaRefRegistry); - if (stack.has(target.refKey)) { - throw new Error( - `Cyclic rule import detected while loading metadata from "${provider.schemaId}": ${[...stack, target.refKey].join( - ' -> ', - )}`, - ); - } - - stack.add(target.refKey); - try { - const value = target.value; - - const resolveArray = (arr: unknown[]): Rule[] => { - const resolvedRules: Rule[] = []; - for (const child of arr) { - if (!isObject(child)) { - throw new Error( - `Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". Rule sets must contain objects.`, - ); - } - resolvedRules.push( - ...resolveRuleEntries( - child as RuleEntry, - { ...provider, schema: target.rootSchema }, - schemaRefRegistry, - stack, - ), - ); - } - return resolvedRules; - }; - - if (Array.isArray(value)) { - return resolveArray(value); - } - - if (isObject(value) && 'rules' in value) { - const nestedRules = value.rules; - if (!Array.isArray(nestedRules)) { - throw new Error( - `Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". "rules" must be an array.`, - ); - } - return resolveArray(nestedRules); - } - - if (isObject(value)) { - return resolveRuleEntries( - value as RuleEntry, - { ...provider, schema: target.rootSchema }, - schemaRefRegistry, - stack, - ); - } +type Merged = Map; +/** + * The single metadata merge rule: a duplicate key is an error unless the later entry sets + * `override: true`, in which case it replaces the earlier one (keeping its position). + */ +function mergeEntry( + merged: Merged, + key: string, + label: string, + value: T, + override: boolean | undefined, + providerId: string, +): void { + const existing = merged.get(key); + if (existing && override !== true) { throw new Error( - `Invalid rule import target for "${ruleEntry.$ref}" from "${provider.schemaId}". Expected a rule object or rule set.`, + `Duplicate ${label} found in "${existing.providerId}" and "${providerId}". Set "override": true on the later one to replace it.`, ); - } finally { - stack.delete(target.refKey); } + merged.set(key, { providerId, value }); } -function normalizeRule(rule: Rule): Rule { - const { override, ...normalized } = rule; - return normalized; -} - -function areRulesEquivalent(left: Rule, right: Rule): boolean { - return isDeepStrictEqual(normalizeRule(left), normalizeRule(right)); +function values(merged: Merged): T[] { + return [...merged.values()].map(({ value }) => value); } function extractMetadata(schema: AnySchemaObject, schemaRefRegistry: Map): SchemaMetadata { const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry); - // Each declared hierarchy is kept as a separate named hierarchy, keyed by its declaring object - // so a root `hierarchy: { $ref }` selection can be matched to it. - const hierarchies = new Map(); - let mainHierarchy: Hierarchy | undefined; + // Hierarchies are merged by name; the declaring object is kept so a root `hierarchy: { $ref }` + // selection can be matched to it. + const mergedHierarchies: Merged<{ declared: MetadataContractHierarchy; hierarchy: Hierarchy }> = new Map(); + let rootHierarchy: MetadataContractHierarchy | undefined; let mainSelection: MetadataRef | undefined; - const mergedAliases: Record = {}; - const mergedRules = new Map(); - const mergedRelationships: MetadataContractRelationship[] = []; + const mergedAliases: Merged = new Map(); + const mergedRules: Merged = new Map(); + const mergedRelationships: Merged = new Map(); for (const provider of metadataProviders) { - const declaredHierarchy = provider.metadata.hierarchy; + const { schemaId, metadata } = provider; + const declaredHierarchy = metadata.hierarchy; const isRoot = provider.schema === schema; if (isRefEntry(declaredHierarchy)) { - // A hierarchy selection only applies when its schema is the root; composed schemas contribute + // A hierarchy selection only applies when its schema is the root; imported schemas contribute // their declared hierarchies, not their selections. if (isRoot) mainSelection = declaredHierarchy; } else if (declaredHierarchy) { const hierarchy = normalizeHierarchy(declaredHierarchy, provider); - hierarchies.set(declaredHierarchy, hierarchy); - if (isRoot) mainHierarchy = hierarchy; + const label = `hierarchy "${hierarchy.name}"`; + mergeEntry( + mergedHierarchies, + hierarchy.name, + label, + { declared: declaredHierarchy, hierarchy }, + declaredHierarchy.override, + schemaId, + ); + if (isRoot) rootHierarchy = declaredHierarchy; } - if (provider.metadata.aliases) { - Object.assign(mergedAliases, provider.metadata.aliases); + for (const [alias, target] of Object.entries(metadata.aliases ?? {})) { + const [type, override] = typeof target === 'string' ? [target, false] : [target.type, target.override]; + mergeEntry(mergedAliases, alias, `alias "${alias}"`, type, override, schemaId); } - if (provider.metadata.relationships) { - mergedRelationships.push(...provider.metadata.relationships); + for (const rel of metadata.relationships ?? []) { + const field = rel.field ?? 'parent'; + const label = `relationship "${rel.parent} → ${rel.type}" (field "${field}")`; + mergeEntry(mergedRelationships, `${rel.parent}\0${rel.type}\0${field}`, label, rel, rel.override, schemaId); } - if (provider.metadata.rules) { - for (const entry of provider.metadata.rules) { - const resolvedRules = resolveRuleEntries(entry, provider, schemaRefRegistry, new Set()); - for (const incomingRule of resolvedRules) { - const existingRule = mergedRules.get(incomingRule.id); - if (!existingRule) { - mergedRules.set(incomingRule.id, { providerId: provider.schemaId, rule: incomingRule }); - continue; - } - - if (incomingRule.override === true) { - mergedRules.set(incomingRule.id, { providerId: provider.schemaId, rule: incomingRule }); - continue; - } - - if (!areRulesEquivalent(existingRule.rule, incomingRule)) { - throw new Error( - `Conflicting rule "${incomingRule.id}" found in "${existingRule.providerId}" and "${provider.schemaId}". Set "override": true on the later rule to replace it.`, - ); - } - } - } + for (const rule of metadata.rules ?? []) { + mergeEntry(mergedRules, rule.id, `rule "${rule.id}"`, rule, rule.override, schemaId); } } - const allHierarchies = [...hierarchies.values()]; - validateHierarchyComposition(allHierarchies); + const merged = values(mergedHierarchies); + const allHierarchies = merged.map(({ hierarchy }) => hierarchy); + validateHierarchyTypes(allHierarchies); + const findDeclared = (declared: unknown) => merged.find((entry) => entry.declared === declared)?.hierarchy; + let mainHierarchy = rootHierarchy ? findDeclared(rootHierarchy) : undefined; if (mainSelection) { const target = resolveMetadataRef(mainSelection.$ref, schema, schemaRefRegistry); - mainHierarchy = hierarchies.get(target.value as MetadataContractHierarchy); + mainHierarchy = findDeclared(target.value); if (!mainHierarchy) { throw new Error( - `Hierarchy $ref "${mainSelection.$ref}" does not point to a hierarchy declared by a composed schema. Expected a ref like "#/$metadata/hierarchy".`, + `Hierarchy $ref "${mainSelection.$ref}" does not point to a hierarchy declared by an imported schema. Expected a ref like "#/$metadata/hierarchy".`, ); } } else if (!mainHierarchy && allHierarchies.length === 1) { @@ -437,29 +311,33 @@ function extractMetadata(schema: AnySchemaObject, schemaRefRegistry: Map 1) { const rootSchemaId = typeof schema.$id === 'string' ? schema.$id : '(root schema)'; throw new Error( - `Schema "${rootSchemaId}" composes multiple hierarchies (${allHierarchies.map((h) => `"${h.name}"`).join(', ')}) but selects none as its main hierarchy. Declare one, or select one with "hierarchy": { "$ref": "#/$metadata/hierarchy" }.`, + `Schema "${rootSchemaId}" imports multiple hierarchies (${allHierarchies.map((h) => `"${h.name}"`).join(', ')}) but selects none as its main hierarchy. Declare one, or select one with "hierarchy": { "$ref": "#/$metadata/hierarchy" }.`, ); } + const typeAliases = Object.fromEntries([...mergedAliases].map(([alias, { value }]) => [alias, value])); + const rules = values(mergedRules).map(({ override, ...rule }) => rule); + const relationships = values(mergedRelationships); + // Collect valid type names from the schema's oneOf list for validation const validTypeNames = extractSchemaTypeNames(schema as SchemaWithMetadata, schemaRefRegistry); - // Validate and filter metadata references against valid type names - validateMetadataReferences({ allHierarchies, mergedAliases, mergedRules, mergedRelationships }, validTypeNames); + // Validate metadata references against valid type names + validateMetadataReferences({ allHierarchies, typeAliases, rules }, validTypeNames); // Filter relationships to only include those where both parent and child types are valid - const filteredRelationships = mergedRelationships.filter((rel) => { + const filteredRelationships = relationships.filter((rel) => { return validTypeNames.has(rel.parent) && validTypeNames.has(rel.type); }); return { hierarchy: mainHierarchy, hierarchies: allHierarchies.length > 0 ? allHierarchies : undefined, - typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined, - rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined, + typeAliases: Object.keys(typeAliases).length > 0 ? typeAliases : undefined, + rules: rules.length > 0 ? rules : undefined, relationships: filteredRelationships.length > 0 - ? filteredRelationships.map((rel) => ({ + ? filteredRelationships.map(({ override, ...rel }) => ({ ...rel, field: rel.field ?? 'parent', fieldOn: rel.fieldOn === 'parent' ? 'parent' : ('child' as const), @@ -495,15 +373,10 @@ function normalizeHierarchy(declared: MetadataContractHierarchy, provider: Metad }; } -/** Hierarchy names must be unique, and each type may belong to at most one hierarchy. */ -function validateHierarchyComposition(hierarchies: Hierarchy[]): void { - const names = new Set(); +/** Each type may belong to at most one hierarchy. */ +function validateHierarchyTypes(hierarchies: Hierarchy[]): void { const typeOwners = new Map(); for (const hierarchy of hierarchies) { - if (names.has(hierarchy.name)) { - throw new Error(`Duplicate hierarchy name "${hierarchy.name}". Set a unique "name" on one of the hierarchies.`); - } - names.add(hierarchy.name); for (const { type } of hierarchy.levels) { const owner = typeOwners.get(type); if (owner !== undefined && owner !== hierarchy.name) { @@ -518,9 +391,8 @@ function validateHierarchyComposition(hierarchies: Hierarchy[]): void { interface MetadataForValidation { allHierarchies: Hierarchy[]; - mergedAliases: Record; - mergedRules: Map; - mergedRelationships: MetadataContractRelationship[]; + typeAliases: Record; + rules: Rule[]; } function validateMetadataReferences(metadata: MetadataForValidation, validTypes: Set): void { @@ -541,7 +413,7 @@ function validateMetadataReferences(metadata: MetadataForValidation, validTypes: } // Validate alias targets (the values) - for (const [alias, target] of Object.entries(metadata.mergedAliases)) { + for (const [alias, target] of Object.entries(metadata.typeAliases)) { if (!validTypes.has(target)) { errors.push(`Alias "${alias}" → "${target}" references type "${target}" which is not in the schema's oneOf list`); } @@ -550,7 +422,7 @@ function validateMetadataReferences(metadata: MetadataForValidation, validTypes: // Note: relationships are filtered (not validated) - see extractMetadata // Validate rule types - for (const { rule } of metadata.mergedRules.values()) { + for (const rule of metadata.rules) { if (rule.type && !validTypes.has(rule.type)) { errors.push(`Rule "${rule.id}" has type "${rule.type}" which is not in the schema's oneOf list`); } diff --git a/tests/fixtures/multi-hierarchy/declare-and-ref-root.json b/tests/fixtures/multi-hierarchy/declare-and-ref-root.json index bf932b9..f603a0b 100644 --- a/tests/fixtures/multi-hierarchy/declare-and-ref-root.json +++ b/tests/fixtures/multi-hierarchy/declare-and-ref-root.json @@ -2,6 +2,7 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://multi-hierarchy/declare-and-ref-root", "$metadata": { + "imports": ["sctx-test://multi-hierarchy/work", "sctx-test://multi-hierarchy/skills"], "hierarchy": { "$ref": "sctx-test://multi-hierarchy/work#/$metadata/hierarchy", "levels": ["goal", "task"] diff --git a/tests/fixtures/multi-hierarchy/declared-root.json b/tests/fixtures/multi-hierarchy/declared-root.json index f197594..7df1438 100644 --- a/tests/fixtures/multi-hierarchy/declared-root.json +++ b/tests/fixtures/multi-hierarchy/declared-root.json @@ -2,6 +2,7 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://multi-hierarchy/declared-root", "$metadata": { + "imports": ["sctx-test://multi-hierarchy/work", "sctx-test://multi-hierarchy/skills"], "hierarchy": { "name": "strategy", "levels": ["vision", "mission"] diff --git a/tests/fixtures/multi-hierarchy/hierarchy-override-root.json b/tests/fixtures/multi-hierarchy/hierarchy-override-root.json new file mode 100644 index 0000000..1d3690a --- /dev/null +++ b/tests/fixtures/multi-hierarchy/hierarchy-override-root.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/hierarchy-override-root", + "$metadata": { + "imports": ["sctx-test://multi-hierarchy/skills"], + "hierarchy": { + "name": "_skills-pack", + "override": true, + "levels": ["skill_area", "skill"] + } + }, + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/ref-only-root.json b/tests/fixtures/multi-hierarchy/ref-only-root.json new file mode 100644 index 0000000..f0f40ec --- /dev/null +++ b/tests/fixtures/multi-hierarchy/ref-only-root.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://multi-hierarchy/ref-only-root", + "oneOf": [ + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" + }, + { + "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill" + } + ] +} diff --git a/tests/fixtures/multi-hierarchy/selected-root.json b/tests/fixtures/multi-hierarchy/selected-root.json index 73fca73..bf6835e 100644 --- a/tests/fixtures/multi-hierarchy/selected-root.json +++ b/tests/fixtures/multi-hierarchy/selected-root.json @@ -2,6 +2,7 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://multi-hierarchy/selected-root", "$metadata": { + "imports": ["sctx-test://multi-hierarchy/work", "sctx-test://multi-hierarchy/skills"], "hierarchy": { "$ref": "sctx-test://multi-hierarchy/work#/$metadata/hierarchy" } diff --git a/tests/fixtures/multi-hierarchy/single-contributed-root.json b/tests/fixtures/multi-hierarchy/single-contributed-root.json index c01e549..fae0a9c 100644 --- a/tests/fixtures/multi-hierarchy/single-contributed-root.json +++ b/tests/fixtures/multi-hierarchy/single-contributed-root.json @@ -1,6 +1,9 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://multi-hierarchy/single-contributed-root", + "$metadata": { + "imports": ["sctx-test://multi-hierarchy/skills"] + }, "oneOf": [ { "$ref": "sctx-test://multi-hierarchy/skills#/$defs/skill_area" diff --git a/tests/fixtures/multi-hierarchy/unselected-root.json b/tests/fixtures/multi-hierarchy/unselected-root.json index 6b7686d..cea0dc9 100644 --- a/tests/fixtures/multi-hierarchy/unselected-root.json +++ b/tests/fixtures/multi-hierarchy/unselected-root.json @@ -1,6 +1,9 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://multi-hierarchy/unselected-root", + "$metadata": { + "imports": ["sctx-test://multi-hierarchy/work", "sctx-test://multi-hierarchy/skills"] + }, "oneOf": [ { "$ref": "sctx-test://multi-hierarchy/work#/$defs/goal" diff --git a/tests/fixtures/schema-composition/_duplicate-pack.json b/tests/fixtures/schema-composition/_duplicate-pack.json new file mode 100644 index 0000000..57d79d4 --- /dev/null +++ b/tests/fixtures/schema-composition/_duplicate-pack.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://schema-composition/duplicate/pack", + "$metadata": { + "aliases": { + "outcome": "goal" + }, + "relationships": [ + { + "parent": "goal", + "type": "task", + "matchers": ["Tasks"] + } + ] + }, + "type": "object" +} diff --git a/tests/fixtures/schema-composition/_merge-pack-a.json b/tests/fixtures/schema-composition/_merge-pack-a.json index 6b1a442..63a1157 100644 --- a/tests/fixtures/schema-composition/_merge-pack-a.json +++ b/tests/fixtures/schema-composition/_merge-pack-a.json @@ -1,8 +1,8 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://schema-composition/merge/pack-a", - "allOf": [{ "$ref": "sctx-test://schema-composition/merge/leaf" }], "$metadata": { + "imports": ["sctx-test://schema-composition/merge/leaf"], "aliases": { "outcome": "goal" }, diff --git a/tests/fixtures/schema-composition/_rule-import-pack.json b/tests/fixtures/schema-composition/_rule-import-pack.json deleted file mode 100644 index 074ee19..0000000 --- a/tests/fixtures/schema-composition/_rule-import-pack.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "sctx-test://schema-composition/imports/pack", - "$defs": { - "workflowRule": { - "id": "workflow-rule", - "category": "workflow", - "description": "Imported workflow rule", - "scope": "global", - "check": "true" - }, - "coherenceRule": { - "id": "coherence-rule", - "category": "coherence", - "description": "Imported coherence rule", - "check": "true" - }, - "ruleSet": { - "rules": [ - { "$ref": "#/$defs/coherenceRule" }, - { - "id": "validation-rule", - "category": "validation", - "description": "Imported validation rule", - "check": "true" - } - ] - } - }, - "type": "object" -} diff --git a/tests/fixtures/schema-composition/compile/_rule-import-pack.json b/tests/fixtures/schema-composition/compile/_rule-import-pack.json deleted file mode 100644 index 33ce2dd..0000000 --- a/tests/fixtures/schema-composition/compile/_rule-import-pack.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "sctx-test://schema-composition/imports/compile/pack", - "$defs": { - "workflowRule": { - "id": "workflow-rule", - "category": "workflow", - "description": "Imported workflow rule", - "scope": "global", - "check": "true" - } - }, - "type": "object" -} diff --git a/tests/fixtures/schema-composition/compile/rule-import-root.json b/tests/fixtures/schema-composition/compile/rule-import-root.json deleted file mode 100644 index cd9957f..0000000 --- a/tests/fixtures/schema-composition/compile/rule-import-root.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", - "$id": "sctx-test://schema-composition/imports/compile/root", - "$metadata": { - "hierarchy": { - "levels": ["goal"] - }, - "rules": [{ "$ref": "sctx-test://schema-composition/imports/compile/pack#/$defs/workflowRule" }] - }, - "type": "object" -} diff --git a/tests/fixtures/schema-composition/conflict-root.json b/tests/fixtures/schema-composition/conflict-root.json index db6ad28..813d2d1 100644 --- a/tests/fixtures/schema-composition/conflict-root.json +++ b/tests/fixtures/schema-composition/conflict-root.json @@ -1,9 +1,8 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://schema-composition/conflict/root", - "allOf": [ - { "$ref": "sctx-test://schema-composition/conflict/pack-a" }, - { "$ref": "sctx-test://schema-composition/conflict/pack-b" } - ], + "$metadata": { + "imports": ["sctx-test://schema-composition/conflict/pack-a", "sctx-test://schema-composition/conflict/pack-b"] + }, "type": "object" } diff --git a/tests/fixtures/schema-composition/duplicate-alias-root.json b/tests/fixtures/schema-composition/duplicate-alias-root.json new file mode 100644 index 0000000..d8a6268 --- /dev/null +++ b/tests/fixtures/schema-composition/duplicate-alias-root.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://schema-composition/duplicate-alias/root", + "$metadata": { + "imports": ["sctx-test://schema-composition/duplicate/pack"], + "aliases": { + "outcome": "objective" + } + }, + "type": "object" +} diff --git a/tests/fixtures/schema-composition/duplicate-relationship-root.json b/tests/fixtures/schema-composition/duplicate-relationship-root.json new file mode 100644 index 0000000..339b5b5 --- /dev/null +++ b/tests/fixtures/schema-composition/duplicate-relationship-root.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://schema-composition/duplicate-relationship/root", + "$metadata": { + "imports": ["sctx-test://schema-composition/duplicate/pack"], + "relationships": [ + { + "parent": "goal", + "type": "task", + "field": "parent", + "matchers": ["Work"] + } + ] + }, + "type": "object" +} diff --git a/tests/fixtures/schema-composition/hierarchy-conflict-root.json b/tests/fixtures/schema-composition/hierarchy-conflict-root.json index 59c6ec7..c14174a 100644 --- a/tests/fixtures/schema-composition/hierarchy-conflict-root.json +++ b/tests/fixtures/schema-composition/hierarchy-conflict-root.json @@ -1,8 +1,8 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://schema-composition/hierarchy-conflict/root", - "allOf": [{ "$ref": "sctx-test://schema-composition/hierarchy-conflict/pack" }], "$metadata": { + "imports": ["sctx-test://schema-composition/hierarchy-conflict/pack"], "hierarchy": { "levels": ["goal"] } diff --git a/tests/fixtures/schema-composition/merge-root.json b/tests/fixtures/schema-composition/merge-root.json index aade2b3..00fb797 100644 --- a/tests/fixtures/schema-composition/merge-root.json +++ b/tests/fixtures/schema-composition/merge-root.json @@ -1,13 +1,13 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://schema-composition/merge/root", - "allOf": [ - { "$ref": "sctx-test://schema-composition/merge/pack-a" }, - { "$ref": "sctx-test://schema-composition/merge/pack-b" } - ], "$metadata": { + "imports": ["sctx-test://schema-composition/merge/pack-a", "sctx-test://schema-composition/merge/pack-b"], "aliases": { - "goal": "objective" + "goal": { + "type": "objective", + "override": true + } }, "rules": [ { diff --git a/tests/fixtures/schema-composition/override-root.json b/tests/fixtures/schema-composition/override-root.json index f928032..430f1e8 100644 --- a/tests/fixtures/schema-composition/override-root.json +++ b/tests/fixtures/schema-composition/override-root.json @@ -1,9 +1,8 @@ { "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", "$id": "sctx-test://schema-composition/override/root", - "allOf": [ - { "$ref": "sctx-test://schema-composition/override/pack-a" }, - { "$ref": "sctx-test://schema-composition/override/pack-b" } - ], + "$metadata": { + "imports": ["sctx-test://schema-composition/override/pack-a", "sctx-test://schema-composition/override/pack-b"] + }, "type": "object" } diff --git a/tests/fixtures/schema-composition/relationship-override-root.json b/tests/fixtures/schema-composition/relationship-override-root.json new file mode 100644 index 0000000..9895708 --- /dev/null +++ b/tests/fixtures/schema-composition/relationship-override-root.json @@ -0,0 +1,35 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://schema-composition/relationship-override/root", + "$metadata": { + "imports": ["sctx-test://schema-composition/duplicate/pack"], + "relationships": [ + { + "parent": "goal", + "type": "task", + "matchers": ["Work"], + "override": true + } + ] + }, + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "goal" + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "const": "task" + } + }, + "required": ["type"] + } + ] +} diff --git a/tests/fixtures/schema-composition/rule-import-root.json b/tests/fixtures/schema-composition/rule-import-root.json deleted file mode 100644 index b9143c7..0000000 --- a/tests/fixtures/schema-composition/rule-import-root.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", - "$id": "sctx-test://schema-composition/imports/root", - "$metadata": { - "hierarchy": { - "levels": ["goal"] - }, - "rules": [ - { "$ref": "sctx-test://schema-composition/imports/pack#/$defs/workflowRule" }, - { "$ref": "sctx-test://schema-composition/imports/pack#/$defs/ruleSet" }, - { "$ref": "#/$defs/localRule" }, - { "$ref": "#/$defs/localRuleSet" } - ] - }, - "$defs": { - "localRule": { - "id": "local-rule", - "category": "validation", - "description": "Local single rule", - "check": "true" - }, - "localRuleSet": { - "rules": [ - { - "id": "local-set-rule", - "category": "best-practice", - "description": "Local rule-set rule", - "check": "true" - } - ] - } - }, - "type": "object" -} diff --git a/tests/schema/schema-composition.test.ts b/tests/schema/schema-composition.test.ts index c050ed2..abc7401 100644 --- a/tests/schema/schema-composition.test.ts +++ b/tests/schema/schema-composition.test.ts @@ -6,7 +6,8 @@ const FIXTURES_DIR = join(import.meta.dir, '..', 'fixtures/schema-composition'); const MULTI_DIR = join(import.meta.dir, '..', 'fixtures/multi-hierarchy'); describe('schema composition metadata', () => { - it('merges metadata across $ref graph in DFS order and applies root metadata last', () => { + it('merges transitive imports depth-first in order and applies root metadata last', () => { + // root imports pack-a (which imports leaf) then pack-b; root overrides pack-b's "goal" alias. const metadata = loadMetadata(join(FIXTURES_DIR, 'merge-root.json')); expect(metadata.hierarchy?.levels.map((level) => level.type)).toEqual(['vision', 'goal']); @@ -27,10 +28,40 @@ describe('schema composition metadata', () => { it('fails conflicting rule IDs without explicit override', () => { expect(() => loadMetadata(join(FIXTURES_DIR, 'conflict-root.json'))).toThrow( - 'Conflicting rule "active-outcome-count"', + 'Duplicate rule "active-outcome-count" found in "sctx-test://schema-composition/conflict/pack-a" and "sctx-test://schema-composition/conflict/pack-b"', ); }); + it('brings no metadata through $ref without an import', () => { + const metadata = loadMetadata(join(MULTI_DIR, 'ref-only-root.json')); + expect(metadata).toEqual({ + hierarchy: undefined, + hierarchies: undefined, + typeAliases: undefined, + rules: undefined, + relationships: undefined, + }); + }); + + it('fails on a duplicate alias without override', () => { + expect(() => loadMetadata(join(FIXTURES_DIR, 'duplicate-alias-root.json'))).toThrow( + 'Duplicate alias "outcome" found in "sctx-test://schema-composition/duplicate/pack"', + ); + }); + + it('fails on a duplicate relationship (same parent, type and field) without override', () => { + expect(() => loadMetadata(join(FIXTURES_DIR, 'duplicate-relationship-root.json'))).toThrow( + 'Duplicate relationship "goal → task" (field "parent") found in "sctx-test://schema-composition/duplicate/pack"', + ); + }); + + it('replaces an imported relationship marked override', () => { + const metadata = loadMetadata(join(FIXTURES_DIR, 'relationship-override-root.json')); + expect(metadata.relationships).toEqual([ + { parent: 'goal', type: 'task', matchers: ['Work'], field: 'parent', fieldOn: 'child', multiple: false }, + ]); + }); + it('allows later rule override when override=true', () => { const metadata = loadMetadata(join(FIXTURES_DIR, 'override-root.json')); @@ -42,23 +73,7 @@ describe('schema composition metadata', () => { expect((metadata.rules?.[0] as Record).override).toBeUndefined(); }); - it('imports specific rules and rule sets via $ref targets', () => { - const metadata = loadMetadata(join(FIXTURES_DIR, 'rule-import-root.json')); - - expect(metadata.rules?.map((rule) => rule.id)).toEqual([ - 'workflow-rule', - 'coherence-rule', - 'validation-rule', - 'local-rule', - 'local-set-rule', - ]); - }); - - it('compiles schemas that use rule import refs in $metadata.rules', () => { - expect(() => createValidator(join(FIXTURES_DIR, 'compile/rule-import-root.json'))).not.toThrow(); - }); - - it('compiles schemas where only one metadata provider defines hierarchy', () => { + it('compiles schemas that import metadata', () => { expect(() => createValidator(join(FIXTURES_DIR, 'merge-root.json'))).not.toThrow(); }); }); @@ -69,7 +84,7 @@ describe('schema composition hierarchies', () => { hierarchies: metadata.hierarchies?.map((h) => [h.name, h.levels.map((l) => l.type)]), }); - it('keeps each composed hierarchy separate and uses the root-declared one as main', () => { + it('keeps each imported hierarchy separate and uses the root-declared one as main', () => { const metadata = loadMetadata(join(MULTI_DIR, 'declared-root.json')); expect(summarize(metadata)).toEqual({ main: 'strategy', @@ -81,7 +96,7 @@ describe('schema composition hierarchies', () => { }); }); - it('uses a single contributed hierarchy as the implicit main hierarchy', () => { + it('uses a single imported hierarchy as the implicit main hierarchy', () => { const metadata = loadMetadata(join(MULTI_DIR, 'single-contributed-root.json')); expect(summarize(metadata)).toEqual({ main: '_skills-pack', @@ -89,6 +104,15 @@ describe('schema composition hierarchies', () => { }); }); + it('lets a root replace an imported hierarchy of the same name with override', () => { + const metadata = loadMetadata(join(MULTI_DIR, 'hierarchy-override-root.json')); + expect(summarize(metadata)).toEqual({ + main: '_skills-pack', + hierarchies: [['_skills-pack', ['skill_area', 'skill']]], + }); + expect(metadata.hierarchy?.levels[1]?.selfRef).toBe(false); + }); + it('names a hierarchy after its declaring schema file stem by default', () => { const metadata = loadMetadata(join(bundledSchemasDir, 'strict_ost.json')); expect(metadata.hierarchy?.name).toBe('_ost_strict'); @@ -105,9 +129,9 @@ describe('schema composition hierarchies', () => { }); }); - it('fails when several hierarchies are contributed and none is selected', () => { + it('fails when several hierarchies are imported and none is selected', () => { expect(() => loadMetadata(join(MULTI_DIR, 'unselected-root.json'))).toThrow( - 'composes multiple hierarchies ("work", "_skills-pack") but selects none as its main hierarchy', + 'imports multiple hierarchies ("work", "_skills-pack") but selects none as its main hierarchy', ); });