structured-context 0.9.2 → 0.10.0

package/dist/plugins/markdown/read-space.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { Glob } from 'bun';
+import fg from 'fast-glob';
 import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
@@ -42,7 +42,7 @@ export async function readSpaceDirectory(context, options) {
     const absoluteTemplateDir = templateDir ? resolve(templateDir) : undefined;
     const typeInferenceCfg = mdCfg.typeInference;
     const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
-    const files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
+    const files = await fg('**/*.md', { cwd: directory, followSymbolicLinks: true });
     const nodes = [];
     const parseIssues = [];
     for (const file of files) {
@@ -70,7 +70,7 @@ export async function readSpaceDirectory(context, options) {
             continue;
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            parseIssues.push({ file, severity: 'warning', type: 'empty' });
+            parseIssues.push({ file, severity: 'warning', type: 'no-type', message: 'No front-matter or type specified' });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));

package/dist/plugins/markdown/template-sync.d.ts

@@ -1,5 +1,5 @@
 import type { AnySchemaObject } from 'ajv';
-import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../plugin-api';
+import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../api';
 import type { PluginContext, TemplateSyncOptions } from '../util';
 export interface TypeVariant {
     required: string[];

package/dist/plugins/markdown/template-sync.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Glob } from 'bun';
+import fg from 'fast-glob';
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { mergeVariantProperties, resolveRef } from '../../schema/schema-refs';
@@ -190,7 +190,7 @@ export async function templateSync(context, options) {
     const { schema, schemaRefRegistry } = context;
     const typeVariants = getTypeVariants(schema, schemaRefRegistry);
     const matchedTypes = new Set();
-    const files = await Array.fromAsync(new Glob('*.md').scan({ cwd: templateDir, absolute: true }));
+    const files = await fg('*.md', { cwd: templateDir, absolute: true });
     const dryRun = options.dryRun ?? false;
     let filesModified = 0;
     let filesCreated = 0;

package/dist/schema/schema.js

@@ -3,7 +3,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import Ajv, {} from 'ajv';
-import { JSON5 } from 'bun';
+import JSON5 from 'json5';
 import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
 import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
 const packageDir = dirname(fileURLToPath(import.meta.url));
@@ -255,17 +255,14 @@ function areRulesEquivalent(left, right) {
 }
 function extractMetadata(schema, schemaRefRegistry) {
     const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry);
-    let hierarchyProvider;
     let mergedHierarchy;
     const mergedAliases = {};
     const mergedRules = new Map();
     const mergedRelationships = [];
     for (const provider of metadataProviders) {
         if (provider.metadata.hierarchy) {
-            if (mergedHierarchy) {
-                throw new Error(`Multiple metadata providers define "$metadata.hierarchy": "${hierarchyProvider}" and "${provider.schemaId}". Exactly one provider is allowed.`);
-            }
-            hierarchyProvider = provider.schemaId;
+            // 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;
         }
         if (provider.metadata.aliases) {
@@ -294,6 +291,14 @@ function extractMetadata(schema, schemaRefRegistry) {
             }
         }
     }
+    // Collect valid type names from the schema's oneOf list for validation
+    const validTypeNames = extractSchemaTypeNames(schema, schemaRefRegistry);
+    // Validate and filter metadata references against valid type names
+    validateMetadataReferences({ mergedHierarchy, 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 = mergedHierarchy?.levels.map((entry) => {
         if (typeof entry === 'string') {
             return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false };
@@ -321,8 +326,8 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
         typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined,
         rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined,
-        relationships: mergedRelationships.length > 0
-            ? mergedRelationships.map((rel) => ({
+        relationships: filteredRelationships.length > 0
+            ? filteredRelationships.map((rel) => ({
                 ...rel,
                 field: rel.field ?? 'parent',
                 fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
@@ -331,6 +336,38 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
     };
 }
+function validateMetadataReferences(metadata, validTypes) {
+    // Skip validation if no types are defined (e.g., schemas without oneOf or placeholder schemas)
+    if (validTypes.size === 0) {
+        return;
+    }
+    const errors = [];
+    // 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`);
+            }
+        }
+    }
+    // Validate alias targets (the values)
+    for (const [alias, target] of Object.entries(metadata.mergedAliases)) {
+        if (!validTypes.has(target)) {
+            errors.push(`Alias "${alias}" → "${target}" references type "${target}" which is not in the schema's oneOf list`);
+        }
+    }
+    // Note: relationships are filtered (not validated) - see extractMetadata
+    // Validate rule types
+    for (const { rule } of metadata.mergedRules.values()) {
+        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`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Schema metadata validation failed:\n  - ${errors.join('\n  - ')}`);
+    }
+}
 export function extractEntityInfo(schema, schemaRefRegistry) {
     if (!Array.isArray(schema.oneOf))
         return [];

package/dist/schemas/_knowledge_wiki.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://_knowledge_wiki",
+  // Shared entity definitions for knowledge wiki schemas.
+  // Provides aliases, relationships, rules, and entity type $defs.
+  // This partial has no hierarchy — wiki entities are flat with no required parent links.
+  "$metadata": {
+    "aliases": {
+      "source_summary": "source",
+      "study": "source",
+      "article": "source",
+      "paper": "source",
+      "research": "source",
+      "comparison": "synthesis",
+      "query": "synthesis"
+    },
+    "relationships": [
+      {
+        "parent": "source",
+        "type": "source",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "synthesis",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "entity",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "concept",
+        "type": "synthesis",
+        "field": "concepts",
+        "fieldOn": "child",
+        "multiple": true
+      }
+    ],
+    "rules": [
+      {
+        "id": "synthesis-references-sources",
+        "category": "coherence",
+        "description": "Syntheses should reference at least one contributing source in their sources array",
+        "type": "synthesis",
+        "check": "$exists(current.sources) and $count(current.sources) >= 1"
+      },
+      {
+        "id": "concept-has-summary",
+        "category": "best-practice",
+        "description": "Concept pages should have a short summary for index discoverability",
+        "type": "concept",
+        "check": "$exists(current.summary) and $length(current.summary) > 0"
+      }
+    ]
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "description": "A processed summary of a raw source (article, paper, book, video, thread, podcast, etc.). Captures key information from the source in structured form with provenance.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "source" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "url": {
+          "type": "string",
+          "description": "URL of the original source"
+        },
+        "local_copy": {
+          "$ref": "sctx://_sctx_base#/$defs/wikilink",
+          "description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)"
+        },
+        "author": {
+          "type": "string",
+          "description": "Author or creator of the source"
+        },
+        "book": {
+          "type": "string",
+          "description": "Book title and author if the source is a book"
+        },
+        "published_date": {
+          "type": "string",
+          "format": "date",
+          "description": "Original publication date"
+        },
+        "source_type": {
+          "type": "string",
+          "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website. Not enum-constrained to allow evolving vocabulary."
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to other source pages that this one references or extends"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "source",
+          "author": "Joe Bloggs",
+          "url": "https://example.com/design-of-yesterday-things",
+          "source_type": "book",
+          "tags": ["design", "ux", "psychology"]
+        }
+      ]
+    },
+    "concept": {
+      "type": "object",
+      "description": "A concept page — defines and frames a specific idea, mechanism, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "concept" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages that contributed to this concept"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related concept or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "concept",
+          "summary": "A property of an object that signals how it can be used, first described by Gibson and popularised in design by Norman",
+          "tags": ["design", "ux"]
+        }
+      ]
+    },
+    "entity": {
+      "type": "object",
+      "description": "A concrete entity — a person, organisation, product, model, or other named thing. The building blocks of the wiki's knowledge graph alongside concepts. Entities are distinct from concepts: a concept frames an idea or mechanism; an entity is a specific, identifiable thing in the world.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "entity" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages that contributed to this entity page"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related entity, concept, or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "entity",
+          "summary": "AI safety research lab founded by Dario Amodei and Daniela Amodei",
+          "tags": ["company", "ai", "safety"]
+        }
+      ]
+    },
+    "synthesis": {
+      "type": "object",
+      "description": "A synthesis page — connects multiple concepts and sources into a coherent model, framework, or thesis. The highest-value pages in a knowledge wiki. Must reference contributing sources.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "synthesis" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages this synthesis draws from"
+        },
+        "concepts": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to concept pages this synthesis connects"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "synthesis",
+          "summary": "How Norman's affordance model and feedback principles combine to explain intuitive vs confusing interfaces",
+          "sources": ["[[The Design of Everyday Things - Don Norman]]"],
+          "concepts": ["[[Affordance]]", "[[Feedback loop]]"]
+        }
+      ]
+    },
+    "note": {
+      "type": "object",
+      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "note" },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "Date this entry was created or relates to"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "note",
+          "date": "2024-03-15",
+          "tags": ["reading-log"]
+        }
+      ]
+    },
+    "index": {
+      "type": "object",
+      "description": "The wiki index — a catalog of all pages with links, summaries, and metadata. Updated by the agent on ingest. Used as the primary navigation entry point.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "index" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "index"
+        }
+      ]
+    }
+  }
+}

package/dist/schemas/_strategy_general.json

@@ -0,0 +1,262 @@
+{
+  "$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.
+  "$metadata": {
+    "hierarchy": {
+      "levels": [
+        "vision",
+        "mission",
+        { "type": "goal", "selfRef": true, "matchers": ["Goals"] },
+        { "type": "opportunity", "selfRef": true, "matchers": ["Opportunities"] },
+        {
+          "type": "solution",
+          "selfRef": true,
+          "matchers": ["Solutions", "Potential solutions", "Solutions considered", "Possible solutions"]
+        },
+        "experiment"
+      ]
+    },
+    "aliases": {
+      "outcome": "goal",
+      "assumption_test": "experiment",
+      "test": "experiment"
+    },
+    "relationships": [
+      {
+        "parent": "opportunity",
+        "type": "problem_statement",
+        "templateFormat": "heading",
+        "matchers": ["Problem statement", "What problem are we solving?"],
+        "multiple": false
+      },
+      {
+        "parent": "opportunity",
+        "type": "assumption",
+        "templateFormat": "table",
+        "matchers": ["Assumptions", "^Assumptions?$"],
+        "embeddedTemplateFields": ["assumption", "status", "confidence"],
+        "multiple": true
+      }
+    ]
+  },
+  "$defs": {
+    "dashboard": {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "dashboard" }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    "ost_on_a_page": {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    "vision": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "vision" }
+      },
+      "required": ["type"],
+      "not": { "required": ["parent"] },
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "vision",
+          "status": "active"
+        }
+      ]
+    },
+    "mission": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "mission" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "mission",
+          "status": "active",
+          "parent": "[[Personal Vision]]"
+        }
+      ]
+    },
+    "goal": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "enum": ["goal", "outcome"] },
+        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "goal",
+          "status": "active",
+          "parent": "[[My Mission (2026)]]",
+          "priority": "p2"
+        }
+      ]
+    },
+    "opportunity": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "opportunity" },
+        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "timeline": {
+          "type": "string",
+          "description": "Timeline estimate (e.g., S-M, M-L)"
+        },
+        "next_steps": {
+          "type": "string",
+          "description": "Next steps for this opportunity"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "opportunity",
+          "status": "identified",
+          "parent": "[[Career Growth]]",
+          "priority": "p2"
+        }
+      ]
+    },
+    "solution": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "solution" },
+        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "timeline": {
+          "type": "string",
+          "description": "Timeline estimate (e.g., S-M, M-L)"
+        },
+        "next_steps": {
+          "type": "string",
+          "description": "Next steps for this solution"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "solution",
+          "status": "identified",
+          "parent": "[[Some Opportunity]]",
+          "priority": "p3"
+        }
+      ]
+    },
+    "experiment": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "enum": ["experiment", "assumption_test", "test"] }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "experiment",
+          "status": "exploring",
+          "parent": "[[Build a Side Project]]"
+        },
+        {
+          "type": "test",
+          "status": "active",
+          "parent": "[[Mobile App Solution]]"
+        }
+      ]
+    },
+    "assumption": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "assumption" },
+        "confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Confidence level in this assumption"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "assumption",
+          "status": "identified",
+          "parent": "[[Some Opportunity]]",
+          "confidence": "medium"
+        }
+      ]
+    },
+    "problem_statement": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "problem_statement" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "problem_statement",
+          "status": "identified"
+        }
+      ]
+    }
+  }
+}