@sprig-and-prose/sprig-universe 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/sprig-universe",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Minimal universe parser for sprig",
   "main": "src/index.js",

package/src/ast.js

@@ -176,7 +176,7 @@
  * @property {string} kind - Always 'relates'
  * @property {string} a - First endpoint text
  * @property {string} b - Second endpoint text
- * @property {Array<DescribeBlock | TitleBlock | FromBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 

package/src/graph.js

@@ -74,6 +74,8 @@ export function buildGraph(fileASTs) {
   const pendingReferenceDecls = [];
   /** @type {Array<{ nodeId: string, items: Array<{ name: string, source: SourceSpan }>, universeName: string }>} */
   const pendingReferenceAttachments = [];
+  /** @type {Array<{ nodeId: string, parentName: string, scopeNodeId: string, source: SourceSpan, nodeKind: 'chapter' | 'book' }>} */
+  const pendingContainerResolutions = [];
 
   // First pass: collect all universe names with their file locations for validation
   const universeNameToFiles = new Map(); // universeName -> Set<file>
@@ -189,6 +191,7 @@ export function buildGraph(fileASTs) {
           entityKinds,
           pendingReferenceDecls,
           pendingReferenceAttachments,
+          pendingContainerResolutions,
         );
       } else {
         // First time seeing this universe - create node and process body
@@ -218,6 +221,7 @@ export function buildGraph(fileASTs) {
           entityKinds,
           pendingReferenceDecls,
           pendingReferenceAttachments,
+          pendingContainerResolutions,
         );
       }
     }
@@ -265,6 +269,7 @@ export function buildGraph(fileASTs) {
             entityKinds,
             pendingReferenceDecls,
             pendingReferenceAttachments,
+            pendingContainerResolutions,
           );
         }
       }
@@ -286,6 +291,9 @@ export function buildGraph(fileASTs) {
   // Resolve edge endpoints
   resolveEdges(graph, scopeIndex);
 
+  // Resolve container references (books/chapters) that may have forward references
+  resolveContainers(graph, scopeIndex, pendingContainerResolutions);
+
   return graph;
 }
 
@@ -496,6 +504,7 @@ function resolveRelatesEndpoint(graph, scopeIndex, name, startScopeNodeId, sourc
  * @param {Map<string, string>} [entityKinds] - Map for tracking non-node entity kinds by ID
  * @param {Array} [pendingReferenceDecls] - Reference declarations to resolve after indexing
  * @param {Array} [pendingReferenceAttachments] - Reference attachments to resolve after indexing
+ * @param {Array} [pendingContainerResolutions] - Container resolutions to resolve after all nodes are created
  */
 function processBody(
   graph,
@@ -511,6 +520,7 @@ function processBody(
   entityKinds,
   pendingReferenceDecls,
   pendingReferenceAttachments,
+  pendingContainerResolutions,
 ) {
   for (const decl of body) {
     if (decl.kind === 'anthology') {
@@ -541,6 +551,7 @@ function processBody(
         entityKinds,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'series') {
       const nodeId = makeNodeId(universeName, 'series', decl.name);
@@ -574,6 +585,7 @@ function processBody(
         entityKinds,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'book') {
       const nodeId = makeNodeId(universeName, 'book', decl.name);
@@ -616,6 +628,7 @@ function processBody(
         entityKinds,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'chapter') {
       const nodeId = makeNodeId(universeName, 'chapter', decl.name);
@@ -634,7 +647,9 @@ function processBody(
       const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
       const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
       
-      // Validate: chapter container must be a book
+      // Validate: chapter container must be a book (if found)
+      // Note: We defer "not found" validation until after all nodes are created
+      // to allow forward references (book defined after chapter)
       if (containerNodeId) {
         const containerNode = graph.nodes[containerNodeId];
         if (containerNode && containerNode.kind !== 'book') {
@@ -644,12 +659,14 @@ function processBody(
             source: decl.source,
           });
         }
-      } else if (decl.parentName) {
-        // Container not found
-        graph.diagnostics.push({
-          severity: 'error',
-          message: `Chapter "${decl.name}" references unknown book "${decl.parentName}"`,
+      } else if (decl.parentName && pendingContainerResolutions) {
+        // Container not found yet - may be a forward reference, track for later resolution
+        pendingContainerResolutions.push({
+          nodeId,
+          parentName: decl.parentName,
+          scopeNodeId: currentNodeId,
           source: decl.source,
+          nodeKind: 'chapter',
         });
       }
       
@@ -683,6 +700,7 @@ function processBody(
         entityKinds,
         pendingReferenceDecls,
         pendingReferenceAttachments,
+        pendingContainerResolutions,
       );
     } else if (decl.kind === 'concept') {
       const nodeId = makeNodeId(universeName, 'concept', decl.name);
@@ -731,10 +749,13 @@ function processBody(
         finalRelatesNodeId = makeRelatesNodeId(universeName, decl.a, decl.b, index);
       }
 
-      // Process relates body: extract describe, from blocks, and unknown blocks
+      // Process relates body: extract describe, relationships, from blocks, and unknown blocks
       const describeBlocks = decl.body.filter((b) => b.kind === 'describe');
+      const relationshipsBlocks = decl.body.filter((b) => b.kind === 'relationships');
       const fromBlocks = decl.body.filter((b) => b.kind === 'from');
-      const unknownBlocks = decl.body.filter((b) => b.kind !== 'describe' && b.kind !== 'from');
+      const unknownBlocks = decl.body.filter(
+        (b) => b.kind !== 'describe' && b.kind !== 'from' && b.kind !== 'relationships',
+      );
 
       // Validate: only one top-level describe
       if (describeBlocks.length > 1) {
@@ -745,6 +766,24 @@ function processBody(
         });
       }
 
+      // Validate: only one top-level relationships block
+      if (relationshipsBlocks.length > 1) {
+        graph.diagnostics.push({
+          severity: 'error',
+          message: `Multiple relationships blocks in relates "${decl.a} and ${decl.b}"`,
+          source: relationshipsBlocks[1].source,
+        });
+      }
+
+      // Validate: relationships must have at least one value
+      if (relationshipsBlocks.length > 0 && relationshipsBlocks[0].values.length === 0) {
+        graph.diagnostics.push({
+          severity: 'error',
+          message: `Empty relationships block in relates "${decl.a} and ${decl.b}"`,
+          source: relationshipsBlocks[0].source,
+        });
+      }
+
       // Validate: from blocks must reference endpoints
       const endpointSet = new Set([decl.a, decl.b]);
       const fromByEndpoint = new Map();
@@ -790,6 +829,14 @@ function processBody(
         };
       }
 
+      // Add top-level relationships if present
+      if (relationshipsBlocks.length > 0) {
+        relatesNode.relationships = {
+          values: relationshipsBlocks[0].values,
+          source: relationshipsBlocks[0].source,
+        };
+      }
+
       // Process from blocks (will be resolved later)
       relatesNode.from = {};
       for (const fromBlock of fromBlocks) {
@@ -1293,6 +1340,65 @@ function resolveEdges(graph, scopeIndex) {
   }
 }
 
+/**
+ * Resolves container references for chapters and books that may have forward references
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {Array<{ nodeId: string, parentName: string, scopeNodeId: string, source: SourceSpan, nodeKind: 'chapter' | 'book' }>} pending
+ */
+function resolveContainers(graph, scopeIndex, pending) {
+  for (const item of pending) {
+    const { nodeId, parentName, scopeNodeId, source, nodeKind } = item;
+    const node = graph.nodes[nodeId];
+    if (!node) continue;
+    
+    // Try to resolve the container now that all nodes are created
+    const resolved = resolveNameInScope(graph, scopeIndex, parentName, scopeNodeId, source);
+    const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
+    
+    if (containerNodeId) {
+      const containerNode = graph.nodes[containerNodeId];
+      
+      // Validate container kind
+      if (nodeKind === 'chapter' && containerNode.kind !== 'book') {
+        graph.diagnostics.push({
+          severity: 'error',
+          message: `Chapter "${node.name}" must belong to a book, but "${parentName}" is a ${containerNode.kind}`,
+          source,
+        });
+        continue;
+      }
+      
+      // Update the node's container
+      node.container = containerNodeId;
+      
+      // Move the node from its temporary parent to the correct container
+      const oldParent = node.parent;
+      if (oldParent && graph.nodes[oldParent]) {
+        const oldParentChildren = graph.nodes[oldParent].children;
+        const idx = oldParentChildren.indexOf(nodeId);
+        if (idx !== -1) {
+          oldParentChildren.splice(idx, 1);
+        }
+      }
+      
+      // Add to correct container
+      node.parent = containerNodeId;
+      if (!containerNode.children.includes(nodeId)) {
+        containerNode.children.push(nodeId);
+      }
+    } else {
+      // Still not found - report error
+      const kindLabel = nodeKind === 'chapter' ? 'book' : 'container';
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Chapter "${node.name}" references unknown ${kindLabel} "${parentName}"`,
+        source,
+      });
+    }
+  }
+}
+
 /**
  * @param {string | undefined} raw
  * @returns {string | undefined}
@@ -1372,9 +1478,16 @@ function resolveReferenceDecls(graph, pending, scopeIndex) {
         unknownRepoCounts.set(decl.repositoryName, entry);
       }
     } else {
+      // Build error message based on whether reference has a name
+      let message;
+      if (decl.name && displayName !== 'unnamed reference') {
+        message = `Reference "${displayName}" must have url { ... } or declared as reference ${displayName} in <Repository>`;
+      } else {
+        message = `Reference must have url { ... } or reference in <Repository>`;
+      }
       graph.diagnostics.push({
         severity: 'error',
-        message: `Reference "${displayName}" must have url { ... } or in <Repository>`,
+        message,
         source: diagnosticSource(decl.source),
       });
     }

package/src/ir.js

@@ -69,6 +69,7 @@
  * @property {NodeId[]} [endpoints] - Endpoint node IDs (for relates nodes)
  * @property {string[]} [unresolvedEndpoints] - Unresolved endpoint names (for relates nodes)
  * @property {Record<string, FromView>} [from] - From blocks keyed by endpoint node ID (for relates nodes)
+ * @property {{ values: string[], source: SourceSpan }} [relationships] - Top-level relationships block (for relates nodes)
  */
 
 /**

package/src/parser.js

@@ -449,7 +449,7 @@ class Parser {
     this.expect('KEYWORD', 'and');
     const bToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'from']);
+    const body = this.parseBlockBody(['describe', 'title', 'from', 'relationships']);
     const rbrace = this.expect('RBRACE');
 
     return {