structured-context 0.11.0 → 0.13.0

package/README.md

@@ -28,10 +28,13 @@ Content and structure
   Schema validation errors                 0
   Broken links                             1
   Duplicate keys                           0
-  Rule violations                          2
+  Rule violations (error)                  0
+  Rule violations (warning)                1
+  Rule violations (info)                   1
   Hierarchy violations                     0
   Orphans (hierarchy nodes - no parent)    1
-  Ignored during parsing                   0
+  Unresolved content links                 0
+  Excluded during parsing                  0
 
 Orphans (hierarchy nodes - no parent):
    Solution looking for a problem.md
@@ -40,13 +43,14 @@ Broken links:
    Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found
 
 Rule violations:
-  workflow (1):
-    Build Death Star.md: Opportunities should contribute to at least one Outcome
-  
-  best-practice (1):
-    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for an active target opportunity
+  WARNING (1):
+    Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome]
+  INFO (1):
+    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity]
 ```
 
+Rule violations carry a severity (`error`, `warning` or `info`) that defaults from the rule's category. Only errors fail validation — see [docs/rules.md](docs/rules.md#rule-shape).
+
 ## Installation
 
 Requires [Bun](https://bun.sh) runtime.
@@ -81,230 +85,99 @@ npx skills add https://github.com/mindsocket/structured-context/tree/main/plugin
 
 ## Concepts
 
-See [docs/concepts.md](docs/concepts.md) for the full terminology reference, including definitions of nodes, embedded nodes, spaces, schemas, rules, and more.
+See [docs/concepts.md](docs/concepts.md) (`sctx docs concepts`) for terminology: spaces, nodes, embedded nodes, schemas, hierarchies, rules and more.
 
 ## Configuration
 
-`structured-context` looks for its config file in this order:
-
-1. `--config` command line argument
-2. `$SCTX_CONFIG` env var
-3. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
-4. `./config.json` in the current working directory
-
-See `config.example.json` for the full structure. The config maps space names to paths, with optional additional configuration options for parsing and integrations. Paths in config files are resolved relative to the config file.
-
-**Including spaces from other configs:** Use `includeSpacesFrom` to import space definitions from other config files. This is useful for aggregating spaces from multiple projects into a central config, reducing the need to specify `--config` on CLI commands. Duplicate space names are not allowed.
+The config file maps space names to paths and schemas, with optional plugin settings. It is found from `--config`, then `$SCTX_CONFIG`, then `$XDG_CONFIG_HOME/structured-context/config.json` (default `~/.config/...`), then `./config.json`. Paths resolve relative to the config file, and `includeSpacesFrom` pulls in spaces from other config files.
 
-**Plugins and markdown plugin config:** See `sctx docs config` for the full reference including `fieldMap`, `typeInference`, `templateDir`, filter views, and plugin loading rules.
+See `config.example.json` and [docs/config.md](docs/config.md) (`sctx docs config`) for the full reference, including `fieldMap`, `typeInference`, templates, filter views and plugin loading.
 
 ### Schemas
 
-Schemas define the structure and rules for the entities in a space, allowing customisation and extension to different models.
+Schemas define the entity types, fields, hierarchy and rules for a space. Set one per space with `schema` in config. Bundled schemas:
 
-Several schemas (`strict_ost`, `knowledge_wiki` and `general`) are included. The general (strategy) schema combines a basic vision/mission/goals hierarchy with a hierarchy loosely based on Opportunity Solution Trees. It is intentionally flexible to support rapid initial adoption. The strict OST schema has a narrower scope, and reflects Teresa Torres' specific recommendations for Opportunity Solution Trees more closely. The knowledge wiki schema defines a flatter set of types used for knowledge bases.
+- `strategy_general` — flexible strategy ladder (vision, mission, goals) flowing into an OST-style opportunity → solution → experiment hierarchy.
+- `strict_ost` — Teresa Torres' canonical four levels: outcome → opportunity → solution → assumption test.
+- `knowledge_wiki` — flat, LLM-maintained knowledge base of sources, concepts, entities, syntheses and notes, with provenance.
+- `okf` — [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) v0.2 bundles: any concept type, with provenance, trust, lifecycle and Attested Computation fields checked when present.
 
-structured-context schemas use a metaschema based on JSON Schema Draft-07 that adds a top-level `$metadata` block:
+Partials (`_*.json`, e.g. `_strategy_general`, `_knowledge_wiki`) are reusable building blocks for your own schemas. Plugins can contribute further schemas.
+
+Schemas are JSON Schema 2020-12 plus a top-level `$metadata` block for hierarchy, relationships, aliases, imports and executable rules, for example:
 
 ```json5
 "$metadata": {
-  "hierarchy": {
-    "levels": ["outcome", { "type": "opportunity", "selfRef": true }, "solution", "assumption_test"],
-    "allowSkipLevels": false
-  },
-  "relationships": [
-    {
-      "parent": "opportunity",
-      "type": "assumption",
-      "templateFormat": "table",
-      "matchers": ["Assumptions"]
-    }
-  ],
+  "hierarchy": { "levels": ["outcome", { "type": "opportunity", "selfRef": true }, "solution", "assumption_test"] },
   "aliases": { "experiment": "assumption_test" },
   "rules": [
     {
       "id": "active-outcome-count",
       "category": "workflow",
       "description": "Only one outcome should be active at a time",
-      "scope": "global",
-      "check": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
+      "global": true,
+      "expression": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
     }
   ]
 }
 ```
 
-Schema hierarchy levels support DAG (multi-parent) relationships via configurable edge fields. Each entry in `$metadata.hierarchy.levels` can be a plain type name string (defaults to `parent` field on child nodes) or an object:
-
-```json5
-// Example fragments for hierarchy level objects:
-{ "type": "opportunity", "selfRef": true }
-{ "type": "solution", "field": "fulfills", "multiple": true }
-{ "type": "requirement", "field": "generates", "fieldOn": "parent", "multiple": true }
-{ "type": "solution", "field": "solutions", "fieldOn": "parent", "multiple": true, "selfRefField": "parent" }
-```
-
-| Property | Default | Description |
-|---|---|---|
-| `type` | required | The node type at this hierarchy level |
-| `field` | `"parent"` | Name of the edge field |
-| `fieldOn` | `"child"` | Which side holds the field: `"child"` (child points up) or `"parent"` (parent points down) |
-| `multiple` | `false` | Whether the field is an array of wikilinks (enables multi-parent DAG) |
-| `selfRef` | `false` | Whether a node of this type may reference a same-type parent |
-| `selfRefField` | _undefined_ | Optional field for same-type parent relationships (always on child-side and singular) |
-| `templateFormat` | _undefined_ | Embedding hint (`"list"`, `"table"`, `"heading"`). When set alongside `matchers`, enables hierarchy embedding in typed pages |
-| `matchers` | _undefined_ | Heading patterns (strings or `/regex/`) to match for hierarchy embedding. Case-insensitive. |
-| `embeddedTemplateFields` | _undefined_ | Column names for table stubs when `template-sync` generates templates |
-
-The `selfRefField` property enables different fields for regular vs same-type relationships. For example, requirements can list solutions via `solutions` on the requirement node, while solutions can reference parent solutions via `parent` on the solution node.
-
-**Hierarchy embedding** — when `templateFormat` and `matchers` are set on a level, typed pages may include section headings that signal embedded content for that type without explicit `[type:: x]` annotations. Two patterns:
-
-- **Child-level**: heading matches the child level's type/matchers → list or table items create child nodes.
-- **Parent-level references**: heading matches the *parent* level's type/matchers → bare wikilink items (`- [[X]]`) populate the current node's reference field rather than creating new nodes. Useful for listing parent relationships inline.
+See [docs/schemas.md](docs/schemas.md) (`sctx docs schema`) for the dialect, composition, multiple hierarchies and `$id` namespaces; [docs/rules.md](docs/rules.md) (`sctx docs rules`) for rules; and [docs/concepts.md](docs/concepts.md) for hierarchy embedding and relationships.
 
-Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a field rather than creating a new node.
-
-**Adjacent Relationships** (`$metadata.relationships`) define connections between types outside the primary hierarchy — such as an `activity` having many `task` nodes. They drive embedded parsing (typed headings, lists, tables) and template generation.
-
-| Property | Default | Description |
-|---|---|---|
-| `parent` | required | Parent canonical type |
-| `type` | required | Child canonical type |
-| `field` | `"parent"` | Frontmatter field holding the wikilink(s). Required when `fieldOn: "parent"`. |
-| `fieldOn` | `"child"` | `"child"`: child holds a link pointing up. `"parent"`: parent holds an array of child links. |
-| `templateFormat` | `"page"` | Hint for `template-sync`: `"table"`, `"list"`, or `"heading"` |
-| `matchers` | `[]` | Heading text to match for embedded parsing (strings or `/regex/`). Case-insensitive. |
-| `multiple` | `true` | Whether multiple children are expected |
-| `embeddedTemplateFields` | `[]` | Field names to include as table columns in templates |
-
-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)
-- `aliases` are shallow-merged (later wins)
-- `rules` merge by `id`; conflicts error unless the later rule sets `override: true`
-- `$metadata.rules` supports `$ref` imports for reusable rule packs
-- `relationships` are collected from all files
-
-If no file defines `hierarchy`, hierarchy-specific checks are skipped.
-
-**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.
-- **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).
-- **Unique IDs**: To encourage clean namespacing, local partial schemas **must** have unique `$id`s that do not collide with the default schemas. If a collision is detected, validation will fail with an error.
-
-Schema resolution order: space config `schema` > global config `schema`. Schema resolution fails if none is configured.
-
-**⚠️ Security Notice: Only use schemas and configuration files from trusted sources.**
-
-The tool executes JSONata expressions defined in schema files for rule validation. A maliciously crafted schema could make JSONata access JavaScript's prototype chain and execute arbitrary code. Only use schemas you've created or reviewed personally.
+**⚠️ Only use schemas and configuration from trusted sources:** rules are JSONata expressions, and a malicious schema can execute arbitrary code. See [docs/config.md](docs/config.md#security-notice).
 
 ## Usage
 
 ### Validate nodes
 
 ```bash
-sctx validate <space> [--watch]
+sctx validate <space> [--watch] [--depth <n>] [--include-gated] [--semantic [provider]] [--rule-filter <dim=values>]
 ```
 
 Validates markdown files against the JSON schema:
 - Extracts YAML frontmatter from each `.md` file
 - Skips files without frontmatter or without a `type` field
 - Reports validation results with counts and per-file errors
+- Runs executable rules (`$metadata.rules`) with **cascade gating**: a schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for that node's hierarchy subtree. Gated rules are reported in a Coverage section so you know what wasn't evaluated and why. See [docs/rules.md](docs/rules.md#cascade-gating) for details.
+- `--depth <n>` limits evaluation to hierarchy nodes within `n` breadth-first levels from the top — useful for staged agentic fix loops (fix the top level, then request the next).
+- `--include-gated` evaluates rules even on gated nodes (still reported as gated) — for surfacing cheap bottom-up checks on request.
+- `--semantic` also evaluates the `semantic` part of rules with the configured model provider (Jev, Anthropic or OpenAI-compatible); `--semantic <provider>` uses that configured model provider instead; `--rule-filter` narrows which rules run. See [docs/semantic-rules.md](docs/semantic-rules.md) (`sctx docs semantic-rules`).
 
-### Show space tree
+### Render space
 
 ```bash
-sctx show <space> [--filter <view-or-expression>]
+sctx render <space> <format> [--out <dir-or-file>] [--force] [--filter <view>] [--hierarchy <name>] [--data key=value]
 ```
 
-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.
+Renders a space in a plugin-provided format. Use `sctx render list [space]` to list available formats.
 
-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.
+- `markdown.bullets` — Indented bullet list tree (outputs to stdout or `--out <file>`).
+- `markdown.directory` — Markdown space directory with one file per node. Writes to `--out <dir>` (refuses to overwrite existing files unless `--force` is passed). Flat directory by default, or organized into per-type subfolders with `--data folders=type` or when configured with `typeInference.folderMap`. Without `--out`, prints a summary of files to be written.
 
-**Filtering:** The `--filter` flag accepts either a named view from the space config, or an inline filter expression. Only nodes matching the expression are shown.
+### Show space tree
 
 ```bash
-# Inline expression
-sctx show <space> --filter "WHERE resolvedType='solution' and status='active'"
-
-# Named view from config
-sctx show <space> --filter active-solutions
+sctx show <space> [--filter <view-or-expression>] [--hierarchy <name>]
 ```
 
-See [Filter expressions](#filter-expressions) below for expression syntax.
-
-### Filter expressions
-
-Filter expressions are used with `--filter` and in config `views`. They use a `SELECT ... WHERE ...` pseudo-DSL:
-
-| Form | Meaning |
-|------|---------|
-| `WHERE {jsonata}` | Return nodes where the JSONata predicate is truthy |
-| `SELECT {spec} WHERE {jsonata}` | Filter by WHERE, then expand result via SELECT |
-| `SELECT {spec}` | Expand from all nodes via SELECT (no WHERE filter — returns all nodes, expanded per spec) |
-| `{jsonata}` | Bare JSONata, treated as a WHERE predicate (convenience shorthand) |
-
-The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Within the expression, each node's fields are accessible directly (e.g. `resolvedType`, `status`, any schema fields like `title`). Two built-in fields are always available regardless of schema: `label` (relative file path, e.g. `"solutions/My Solution.md"`) and `title` (node display name). Additionally, two pre-computed traversal arrays are available:
-
-- **`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'`
-  - `_selfRef` — whether the edge is a same-type (self-referential) link
-- **`descendants[]`** — same structure, for descendant nodes
-
-**SELECT spec** expands the result set by walking the graph from matched nodes. The spec is a comma-separated list of directives:
-
-| Directive | Meaning |
-|-----------|---------|
-| `ancestors` | All ancestor nodes |
-| `ancestors(type)` | Ancestors of the given resolved type |
-| `descendants` | All descendant nodes |
-| `descendants(type)` | Descendants of the given resolved type |
-| `siblings` | Nodes sharing at least one parent with matched nodes |
-| `relationships` | All nodes connected via a relationship (non-hierarchy) edge |
-| `relationships(childType)` | Relationship-connected nodes of the given child type |
-| `relationships(parentType:childType)` | As above, also filtering by parent type |
-| `relationships(parentType:field:childType)` | Fully qualified: also filtering by edge field name |
-
-Multiple directives may be combined: `SELECT ancestors(goal), siblings WHERE ...`
-
-**Examples:**
-
-```jsonata
-// All solutions
-WHERE resolvedType='solution'
-
-// Active solutions only
-WHERE resolvedType='solution' and status='active'
-
-// Solutions whose nearest opportunity ancestor is active
-WHERE resolvedType='solution' and $exists(ancestors[resolvedType='opportunity' and status='active'])
+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 <name>` selects another (see [Multiple hierarchies](docs/schemas.md#multiple-hierarchies)). `diagram` and `render` accept the same option.
 
-// Nodes that have any ancestor goal
-WHERE $exists(ancestors[resolvedType='goal'])
-
-// Bare JSONata shorthand (no WHERE keyword)
-resolvedType='solution' and status='active'
-
-// Solutions + their opportunity ancestors
-SELECT ancestors(opportunity) WHERE resolvedType='solution'
+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.
 
-// Solutions + their siblings (other solutions under same opportunity)
-SELECT siblings WHERE resolvedType='solution' and status='active'
+**Filtering:** `--filter` (on `show` and `render`) takes a named view from the space config or an inline expression: `WHERE {jsonata}`, optionally with `SELECT {spec}` to expand results along the graph.
 
-// Opportunities + their related assumptions
-SELECT relationships(assumption) WHERE resolvedType='opportunity'
+```bash
+sctx show <space> --filter "WHERE resolvedType='solution' and status='active'"
+sctx show <space> --filter "SELECT ancestors(opportunity) WHERE resolvedType='solution'"
+sctx show <space> --filter active-solutions   # named view
 ```
 
+See [Filter expressions](docs/concepts.md#filter-expressions) (`sctx docs concepts`) for the full syntax.
+
 ### Generate Mermaid diagram
 
 ```bash
-sctx diagram <space> [--output path/to/output.mmd]
+sctx diagram <space> [--output path/to/output.mmd] [--hierarchy <name>]
 ```
 
 Generates a Mermaid `graph TD` diagram from validated space nodes:
@@ -321,7 +194,7 @@ sctx schemas show <schema-file> [--mermaid-erd] [--space <name>]
 
 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:
@@ -335,28 +208,9 @@ sctx schemas show strategy_general --mermaid-erd
 sctx miro-sync <space> [--new-frame <title>] [--dry-run] [--verbose]
 ```
 
-Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `boardId` set in the `miro` plugin config for the space.
-
-- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `frameId` back to the miro plugin config
-- `--dry-run` — show what would change without touching Miro
-- `--verbose` / `-v` — detailed per-card and per-connector output
-
-Configure the miro plugin in the space's config entry:
-
-```json
-{
-  "plugins": {
-    "miro": {
-      "boardId": "your-board-id",
-      "frameId": "your-frame-id"
-    }
-  }
-}
-```
-
-On subsequent runs, the cached `frameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
+Syncs space nodes to a Miro board as colour-coded cards with parent→child connectors. Requires a `MIRO_TOKEN` env var and `plugins.miro.boardId` in the space config. `--new-frame` creates a frame and saves its `frameId` to config; `--dry-run` previews changes.
 
-Sync is one-way (OST → Miro) and scoped to a single frame. Only cards and connectors created by this tool within that frame are managed — everything else on the board is left untouched. Card content and connectors are overwritten or recreated to match the markdown source; any edits made directly in Miro to managed cards will be lost on the next sync. Existing card positions are not changed.
+Sync is one-way and scoped to one frame: only cards and connectors this tool created there are managed, and edits made in Miro to those cards are overwritten on the next sync. A local `.miro-cache/` tracks Miro IDs for incremental updates.
 
 ### Sync templates with schema
 

package/dist/api.d.ts

@@ -3,8 +3,8 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
- *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from './api.js';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from './api.js';
  *
  * Common patterns:
  *
@@ -18,16 +18,18 @@
  *   const validation = await validateSpace(ctx, { readResult });
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
-export type { Config, SpaceConfig } from './config';
-export { loadConfig, setConfigPath } from './config';
-export { PLUGIN_PREFIX } from './constants';
-export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
-export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
-export { readSpace } from './read/read-space';
-export type { SharedEmbeddingFields } from './schema/metadata-contract';
-export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
-export { createSpaceContext, SpaceNotFoundError } from './space-context';
-export type { SpaceGraph } from './space-graph';
-export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
-export type { ValidationResult } from './validate';
-export { validateFile, validateSpace } from './validate';
+export type { Config, SpaceConfig } from './config.js';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config.js';
+export { PLUGIN_PREFIX } from './constants.js';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph.js';
+export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util.js';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util.js';
+export { readSpace } from './read/read-space.js';
+export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils.js';
+export type { SharedEmbeddingFields } from './schema/metadata-contract.js';
+export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema.js';
+export { createSpaceContext, SpaceNotFoundError } from './space-context.js';
+export { buildSpaceGraph, type SpaceGraph } from './space-graph.js';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types.js';
+export type { ValidationResult } from './validate.js';
+export { validateFile, validateSpace } from './validate.js';

package/dist/api.js

@@ -3,8 +3,8 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
- *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from './api.js';
+ *   import type { StructuredContextPlugin, PluginContext, ParseResult } from './api.js';
  *
  * Common patterns:
  *
@@ -17,10 +17,13 @@
  *   const graph = await assembleSpaceGraph(ctx, { readResult });
  *   const validation = await validateSpace(ctx, { readResult });
  */
-export { loadConfig, setConfigPath } from './config';
-export { PLUGIN_PREFIX } from './constants';
-export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
-export { readSpace } from './read/read-space';
-export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
-export { createSpaceContext, SpaceNotFoundError } from './space-context';
-export { validateFile, validateSpace } from './validate';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config.js';
+export { PLUGIN_PREFIX } from './constants.js';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph.js';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util.js';
+export { readSpace } from './read/read-space.js';
+export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils.js';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema.js';
+export { createSpaceContext, SpaceNotFoundError } from './space-context.js';
+export { buildSpaceGraph } from './space-graph.js';
+export { validateFile, validateSpace } from './validate.js';

package/dist/commands/diagram.d.ts

@@ -2,4 +2,5 @@ import type { SpaceContext } from '../types';
 export declare function diagram(context: SpaceContext, options: {
     output?: string;
     filter?: string;
+    hierarchy?: string;
 }): Promise<void>;

package/dist/commands/diagram.js

@@ -1,7 +1,13 @@
 import { writeFileSync } from 'node:fs';
 import { executeRender } from '../render/render';
 export async function diagram(context, options) {
-    const result = await executeRender('mermaid.graph', context, { filter: options.filter });
+    const result = await executeRender('mermaid.graph', context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from mermaid diagram renderer');
+    }
     if (options.output) {
         writeFileSync(options.output, result);
         console.log(`Mermaid diagram written to ${options.output}`);

package/dist/commands/docs.js

@@ -5,6 +5,7 @@ const TOPICS = {
     config: 'config.md',
     schema: 'schemas.md',
     rules: 'rules.md',
+    'semantic-rules': 'semantic-rules.md',
 };
 export function docs(topic) {
     let filePath;

package/dist/commands/dump.d.ts

@@ -1,2 +1,15 @@
-import type { SpaceContext } from '../types';
-export declare function dump(context: SpaceContext): Promise<void>;
+import type { ReadSpaceResult, SpaceContext } from '../types';
+export interface DumpOptions {
+    /** Named view (resolved via space.views) or a raw filter DSL expression. */
+    filter?: string;
+    /** Hierarchy used when evaluating the filter (default: the main hierarchy). */
+    hierarchy?: string;
+}
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export declare function buildDump(context: SpaceContext, options?: DumpOptions): Promise<ReadSpaceResult>;
+export declare function dump(context: SpaceContext, options?: DumpOptions): Promise<void>;

package/dist/commands/dump.js

@@ -1,6 +1,20 @@
-import JSON5 from 'json5';
+import { assembleSpaceGraph } from '../load-space-graph';
 import { readSpace } from '../read/read-space';
-export async function dump(context) {
-    const { nodes, source, diagnostics } = await readSpace(context);
-    console.log(JSON5.stringify({ nodes, source, diagnostics }, null, 2));
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export async function buildDump(context, options = {}) {
+    const readResult = await readSpace(context);
+    if (!options.filter)
+        return readResult;
+    const graph = await assembleSpaceGraph(context, { ...options, readResult });
+    const nodes = readResult.nodes.filter((node) => graph.nodes.get(node.title) === node);
+    return { ...readResult, nodes };
+}
+export async function dump(context, options = {}) {
+    const { nodes, source, diagnostics } = await buildDump(context, options);
+    console.log(JSON.stringify({ nodes, source, diagnostics }, null, 2));
 }

package/dist/commands/providers.d.ts

@@ -0,0 +1,4 @@
+/** List bundled and configured model providers with their effective config; keys are never shown. */
+export declare function listProviders(options?: {
+    json?: boolean;
+}): void;

package/dist/commands/providers.js

@@ -0,0 +1,52 @@
+import { loadConfig } from '../config';
+import { BUNDLED_PROVIDERS, hydrateProvider } from '../judge/factory';
+function row(name, def, source) {
+    try {
+        const h = hydrateProvider(name, def);
+        const needsKey = h.api !== 'openai-completions' && h.api !== 'fake';
+        return {
+            name,
+            source,
+            api: h.api,
+            model: h.model,
+            endpoint: h.endpoint,
+            keyEnv: h.keyEnv,
+            valid: !needsKey || h.apiKey !== undefined,
+            error: needsKey && h.apiKey === undefined ? `no API key; set ${h.keyEnv}` : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            name,
+            source,
+            api: def.api,
+            model: def.model,
+            endpoint: def.endpoint,
+            keyEnv: def.apiKeyEnv,
+            valid: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** List bundled and configured model providers with their effective config; keys are never shown. */
+export function listProviders(options = {}) {
+    const config = loadConfig();
+    const configured = config.modelProviders ?? {};
+    const rows = [
+        ...Object.entries(configured).map(([name, def]) => row(name, def, 'config')),
+        ...Object.entries(BUNDLED_PROVIDERS)
+            .filter(([name]) => !(name in configured))
+            .map(([name, def]) => row(name, def, 'bundled')),
+    ];
+    if (options.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    for (const r of rows) {
+        const origin = r.source === 'bundled' ? '' : ' (config)';
+        const model = r.model ?? '(api default)';
+        const endpoint = r.endpoint ?? '(api default)';
+        const key = r.valid ? `key via ${r.keyEnv}` : (r.error ?? 'no key');
+        console.log(`${r.name}${origin}\n  api=${r.api}\n  endpoint=${endpoint}\n  model=${model}\n  ${key}`);
+    }
+}

package/dist/commands/render.d.ts

@@ -1,6 +1,10 @@
 import type { SpaceContext } from '../types';
 export declare function render(context: SpaceContext, format: string, options: {
     filter?: string;
+    hierarchy?: string;
     output?: string;
+    out?: string;
+    force?: boolean;
+    data?: Record<string, unknown>;
 }): Promise<void>;
 export declare function renderList(context?: SpaceContext): Promise<void>;