structured-context 0.9.0

package/dist/schema/validate-graph.js

@@ -0,0 +1,141 @@
+import { resolveNodeType } from '../schema/schema';
+/**
+ * Validate graph structure using pre-collected unresolved refs from resolveGraphEdges.
+ * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
+ */
+export function validateGraph(nodes, metadata, unresolvedRefs = []) {
+    const refErrors = unresolvedRefs.map((u) => ({ file: u.label, parent: u.ref, error: u.message }));
+    const violations = validateHierarchyStructure(nodes, metadata);
+    return { violations, refErrors };
+}
+/**
+ * Validate that resolved parents follow hierarchy level rules and relationship type constraints.
+ *
+ * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering.
+ * For relationship edges (fieldOn:'child', source:'relationship'): validates parent type.
+ * For fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node.
+ *
+ * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
+ */
+export function validateHierarchyStructure(nodes, metadata) {
+    const violations = [];
+    const levels = metadata.hierarchy?.levels ?? [];
+    const relationships = metadata.relationships ?? [];
+    const allowSkipLevels = metadata.hierarchy?.allowSkipLevels ?? false;
+    const typeAliases = metadata.typeAliases;
+    const hierarchy = levels.map((level) => resolveNodeType(level.type, typeAliases));
+    // Build type rules: (ownerType, field) → set of valid target types.
+    // For fieldOn:'child': owner=childType, target=parentType.
+    // For fieldOn:'parent': owner=parentType (field owner), target=childType.
+    const typeRules = new Map();
+    function addTypeRule(ownerType, field, targetType) {
+        const owner = resolveNodeType(ownerType, typeAliases);
+        const target = resolveNodeType(targetType, typeAliases);
+        if (!typeRules.has(owner))
+            typeRules.set(owner, new Map());
+        const fieldMap = typeRules.get(owner);
+        if (!fieldMap.has(field))
+            fieldMap.set(field, new Set());
+        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 rel of relationships) {
+        if (rel.fieldOn === 'parent') {
+            addTypeRule(rel.parent, rel.field, rel.type);
+        }
+        else {
+            addTypeRule(rel.type, rel.field, rel.parent);
+        }
+    }
+    const nodeIndex = new Map();
+    for (const node of nodes) {
+        const title = node.title;
+        if (title)
+            nodeIndex.set(title, node);
+    }
+    for (const node of nodes) {
+        const nodeType = node.resolvedType;
+        const nodeTitle = node.title;
+        for (const parentRef of node.resolvedParents) {
+            const parentNode = nodeIndex.get(parentRef.title);
+            if (!parentNode)
+                continue;
+            const parentType = parentNode.resolvedType;
+            const parentTitle = parentRef.title;
+            if (parentRef.fieldOn === 'parent') {
+                // Field is on the parent node; validate that this node's type matches the expected child type.
+                // Violation is attributed to the field-owner (parent) node.
+                const allowedChildTypes = typeRules.get(parentType)?.get(parentRef.field);
+                if (allowedChildTypes && !allowedChildTypes.has(nodeType)) {
+                    const expected = [...allowedChildTypes].join(' or ');
+                    violations.push({
+                        file: parentNode.label,
+                        nodeType: parentType,
+                        nodeTitle: parentTitle,
+                        parentType: nodeType,
+                        parentTitle: nodeTitle,
+                        description: `Invalid relationship: ${parentType} "${parentTitle}" has "${nodeTitle}" in field "${parentRef.field}" which is of type ${nodeType}, expected ${expected}`,
+                    });
+                }
+            }
+            else if (parentRef.source === 'relationship') {
+                // Relationship edge (fieldOn:'child'): validate parent type matches relationship definition.
+                const allowedTypes = typeRules.get(nodeType)?.get(parentRef.field);
+                if (allowedTypes && !allowedTypes.has(parentType)) {
+                    const expected = [...allowedTypes].join(' or ');
+                    violations.push({
+                        file: node.label,
+                        nodeType,
+                        nodeTitle,
+                        parentType,
+                        parentTitle,
+                        description: `Invalid relationship: ${nodeType} "${nodeTitle}" has "${parentTitle}" in field "${parentRef.field}" which is of type ${parentType}, expected ${expected}`,
+                    });
+                }
+            }
+            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];
+                const canSelfRef = level.selfRef || level.selfRefField !== undefined;
+                let isValidHierarchy = false;
+                if (parentIndex === typeIndex - 1) {
+                    isValidHierarchy = true;
+                }
+                else if (canSelfRef && parentIndex === typeIndex) {
+                    isValidHierarchy = true;
+                }
+                else if (allowSkipLevels && parentIndex < typeIndex) {
+                    isValidHierarchy = true;
+                }
+                if (!isValidHierarchy) {
+                    violations.push({
+                        file: node.label,
+                        nodeType,
+                        nodeTitle,
+                        parentType,
+                        parentTitle,
+                        description: `Invalid parent: ${nodeType} "${nodeTitle}" cannot have ${parentType} "${parentTitle}" as parent`,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}

package/dist/schema/validate-rules.d.ts

@@ -0,0 +1,10 @@
+import type { Rule, RuleViolation, SpaceNode } from '../types';
+/**
+ * Validate nodes against rules metadata.
+ * Returns a list of rule violations found.
+ *
+ * @param nodes - All nodes in the space
+ * @param rules - Rules metadata list
+ * @returns Array of rule violations
+ */
+export declare function validateRules(nodes: SpaceNode[], rules: Rule[]): Promise<RuleViolation[]>;

package/dist/schema/validate-rules.js

@@ -0,0 +1,51 @@
+import { buildEvalContext, evaluateExpression } from './evaluate-rule';
+/**
+ * Validate nodes against rules metadata.
+ * Returns a list of rule violations found.
+ *
+ * @param nodes - All nodes in the space
+ * @param rules - Rules metadata list
+ * @returns Array of rule violations
+ */
+export async function validateRules(nodes, rules) {
+    const violations = [];
+    // Build node index for efficient lookups
+    const nodeIndex = new Map();
+    for (const node of nodes) {
+        const title = node.title;
+        if (title) {
+            nodeIndex.set(title, node);
+        }
+    }
+    // Evaluate each rule against applicable nodes
+    for (const rule of rules) {
+        if (rule.scope === 'global') {
+            // Global rules are evaluated once against the full node set.
+            // A sentinel node provides the evaluation context (nodes array is what matters).
+            const sentinel = nodes[0];
+            if (sentinel) {
+                const context = buildEvalContext(sentinel, nodes, nodeIndex);
+                const result = await evaluateExpression(rule.check, context);
+                if (result !== true) {
+                    violations.push({ file: '', ruleId: rule.id, category: rule.category, description: rule.description });
+                }
+            }
+        }
+        else {
+            const targetNodes = rule.type ? nodes.filter((n) => n.resolvedType === rule.type) : nodes;
+            for (const node of targetNodes) {
+                const context = buildEvalContext(node, nodes, nodeIndex);
+                const result = await evaluateExpression(rule.check, context);
+                if (result !== true) {
+                    violations.push({
+                        file: node.label,
+                        ruleId: rule.id,
+                        category: rule.category,
+                        description: rule.description,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}

package/dist/schemas/_ost_strict.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://_ost_strict",
+  // Shared definitions for the strict OST (Opportunity Solution Tree) schema.
+  // This schema follows Teresa Torres' canonical 4-level structure as described in
+  // "Continuous Discovery Habits" (2021) and at producttalk.org.
+  "$metadata": {
+    "hierarchy": {
+      "levels": ["outcome", { "type": "opportunity", "selfRef": true }, "solution", "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"
+      },
+      {
+        "id": "active-opportunity-count",
+        "category": "workflow",
+        "description": "Only one target opportunity should be active at a time",
+        "scope": "global",
+        "check": "$count(nodes[resolvedType='opportunity' and status='active']) <= 1"
+      },
+      {
+        "id": "active-node-parent-active",
+        "category": "workflow",
+        "description": "An active node's parent should also be active",
+        "check": "current.status != 'active' or $exists(parent) = false or parent.status = 'active'"
+      },
+      {
+        "id": "solution-quantity",
+        "category": "best-practice",
+        "description": "Explore multiple candidate solutions (aim for at least three) for the target opportunity",
+        "type": "opportunity",
+        "check": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) >= 3"
+      }
+    ]
+  },
+  "$defs": {
+    "outcomeProps": {
+      "type": "object",
+      "description": "Properties for an Outcome node (product metric, not vision/mission)",
+      "properties": {
+        "metric": {
+          "type": "string",
+          "description": "The specific product metric to move (e.g., 'Increase % of first-time users who reach the aha moment')"
+        }
+      },
+      "required": ["metric"]
+    },
+    "opportunityProps": {
+      "type": "object",
+      "description": "Properties for an Opportunity, emphasizing research grounding",
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "Customer research source that grounded this opportunity (e.g., 'Interview with Jane, 2024-03-15')"
+        }
+      },
+      "required": ["source"]
+    },
+    "assumptionTestProps": {
+      "type": "object",
+      "description": "Properties for an Assumption Test (the fourth level of the OST)",
+      "properties": {
+        "assumption": {
+          "type": "string",
+          "description": "The specific belief being tested"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["desirability", "viability", "feasibility", "usability", "ethical"],
+          "description": "Assumption type categories"
+        }
+      },
+      "required": ["assumption"]
+    }
+  }
+}

package/dist/schemas/_sctx_base.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "sctx://_sctx_base",
+  "description": "Shared definitions for structured-context schemas",
+  "$defs": {
+    "title": {
+      "type": "string",
+      "description": "Title of the node"
+    },
+    "content": {
+      "type": "string",
+      "description": "Body content"
+    },
+    "summary": {
+      "type": "string",
+      "description": "Short summary"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["identified", "wondering", "exploring", "active", "paused", "completed", "archived"]
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["p1", "p2", "p3", "p4"]
+    },
+    "assessment": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "description": "Assessment score from 1-5"
+    },
+    "wikilink": {
+      "type": "string",
+      "pattern": "^\\[\\[.+\\]\\]$",
+      "description": "An Obsidian wikilink, e.g. [[Parent Node]]"
+    },
+    "baseNodeProps": {
+      "type": "object",
+      "properties": {
+        "title": { "$ref": "#/$defs/title" },
+        "content": { "$ref": "#/$defs/content" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Categorization tags"
+        }
+      },
+      "required": ["title"]
+    },
+    "ostEntityProps": {
+      "type": "object",
+      "properties": {
+        "status": { "$ref": "#/$defs/status" },
+        "summary": { "$ref": "#/$defs/summary" },
+        "status_tweet": {
+          "type": "string",
+          "description": "Succinct free-text status summary"
+        }
+      },
+      "required": ["status"]
+    },
+    "parentNodeProps": {
+      "type": "object",
+      "properties": {
+        "parent": {
+          "$ref": "#/$defs/wikilink",
+          "description": "Parent node"
+        }
+      }
+    }
+  }
+}

package/dist/schemas/general.json

@@ -0,0 +1,261 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://general",
+  "title": "Strategy and opportunity ladder",
+  "description": "Validates frontmatter for space node files",
+  "$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
+      }
+    ]
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "dashboard" }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    {
+      "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]]"
+        }
+      ]
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    {
+      "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]]"
+        }
+      ]
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    {
+      "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"
+        }
+      ]
+    }
+  ]
+}