@sprig-and-prose/sprig-universe 0.4.0 → 0.4.1

package/package.json

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

package/src/graph.js

@@ -50,7 +50,7 @@ export function buildGraph(fileASTs) {
     version: 1,
     universes: {},
     nodes: {},
-    edges: {},
+    edges: [],
     diagnostics: [],
     documentsByName: {},
     repositories: {},
@@ -318,9 +318,6 @@ export function buildGraph(fileASTs) {
   // Extract asserted edges from both relationships blocks and relates nodes
   graph.edgesAsserted = extractAssertedEdges(graph, scopeIndex);
 
-  // Preserve existing edges object format for relates (for code that still uses it)
-  graph.edgesByRelates = graph.edges;
-
   // Normalize edges (add inverse edges for paired/symmetric relationships)
   const universeNames = Array.from(universeNameToFiles.keys());
   if (universeNames.length > 0) {
@@ -382,6 +379,46 @@ function addNameToScope(graph, scopeIndex, scopeNodeId, name, nodeId) {
   }
 }
 
+/**
+ * Finds the series containing a given node by walking up the parent chain
+ * @param {UniverseGraph} graph - The graph
+ * @param {string} nodeId - Node ID to find series for
+ * @returns {string | null} - Series node ID, or null if not found
+ */
+function findSeriesForNode(graph, nodeId) {
+  const node = graph.nodes[nodeId];
+  if (!node) return null;
+  
+  let checkNode = node;
+  while (checkNode && checkNode.parent) {
+    checkNode = graph.nodes[checkNode.parent];
+    if (checkNode && checkNode.kind === 'series') {
+      return checkNode.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Prefers a candidate from the same series as the starting node when multiple candidates exist
+ * @param {UniverseGraph} graph - The graph
+ * @param {string} startScopeNodeId - Starting node ID
+ * @param {string[]} candidates - Array of candidate node IDs
+ * @returns {string | null} - Preferred candidate node ID, or null if none found
+ */
+function preferSameSeriesCandidate(graph, startScopeNodeId, candidates) {
+  const seriesNodeId = findSeriesForNode(graph, startScopeNodeId);
+  if (!seriesNodeId) return null;
+  
+  for (const candidateId of candidates) {
+    const candidateSeriesNodeId = findSeriesForNode(graph, candidateId);
+    if (candidateSeriesNodeId === seriesNodeId) {
+      return candidateId;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolves a name by walking the scope chain (current container -> parent -> ... -> universe)
  * Returns the first matching node ID found, or null if not found
@@ -445,7 +482,14 @@ function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
       } else if (candidates.length === 1) {
         return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
       } else {
-        // Ambiguity at this scope level
+        // Ambiguity at this scope level - try to disambiguate by preferring same series
+        const preferredCandidate = preferSameSeriesCandidate(graph, startScopeNodeId, candidates);
+        
+        if (preferredCandidate) {
+          return { nodeId: preferredCandidate, ambiguous: false, ambiguousNodes: [] };
+        }
+        
+        // No preferred candidate found - report ambiguity
         if (source) {
           const scopeNode = graph.nodes[currentScope];
           const scopeName = scopeNode ? (scopeNode.name || currentScope) : currentScope;
@@ -475,6 +519,14 @@ function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
           if (candidates.length === 1) {
             return { nodeId: candidates[0], ambiguous: false, ambiguousNodes: [] };
           } else if (candidates.length > 1) {
+            // Multiple matches at universe scope - try to disambiguate by preferring same series
+            const preferredCandidate = preferSameSeriesCandidate(graph, startScopeNodeId, candidates);
+            
+            if (preferredCandidate) {
+              return { nodeId: preferredCandidate, ambiguous: false, ambiguousNodes: [] };
+            }
+            
+            // No preferred candidate found - report ambiguity
             if (source) {
               graph.diagnostics.push({
                 severity: 'error',
@@ -773,36 +825,82 @@ function processBody(
         pendingContainerResolutions,
       );
     } else if (decl.kind === 'chapter') {
-      const nodeId = makeNodeId(universeName, 'chapter', decl.name);
-      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'chapter', decl.source);
-      
-      // Validate: chapter must have an "in" block
-      if (!decl.parentName) {
-        graph.diagnostics.push({
-          severity: 'error',
-          message: `Chapter "${decl.name}" must belong to a book. Use "chapter ${decl.name} in <BookName> { ... }"`,
-          source: decl.source,
-        });
-        // Continue processing but mark as invalid
-      }
-      
-      const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
-      const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
+      let containerNodeId = undefined;
       
-      // 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') {
+      if (decl.parentName) {
+        // Explicit "in" clause - resolve the parent name
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : undefined;
+        
+        // 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') {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Chapter "${decl.name}" must belong to a book, but "${decl.parentName}" is a ${containerNode.kind}`,
+              source: decl.source,
+            });
+          }
+        }
+      } else {
+        // Nested chapter - parentName is undefined, check if parentNodeId is a book
+        if (parentNodeId) {
+          const parentNode = graph.nodes[parentNodeId];
+          if (parentNode && parentNode.kind !== 'book') {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Chapter "${decl.name}" must belong to a book, but it's nested inside a ${parentNode.kind}`,
+              source: decl.source,
+            });
+          } else if (parentNode && parentNode.kind === 'book') {
+            // Valid nested chapter - use parentNodeId as container
+            containerNodeId = parentNodeId;
+          }
+        } else {
+          // No parent at all - error
           graph.diagnostics.push({
             severity: 'error',
-            message: `Chapter "${decl.name}" must belong to a book, but "${decl.parentName}" is a ${containerNode.kind}`,
+            message: `Chapter "${decl.name}" must belong to a book. Use "chapter ${decl.name} in <BookName> { ... }"`,
             source: decl.source,
           });
         }
-      } else if (decl.parentName && pendingContainerResolutions) {
+      }
+      
+      // Build unique node ID including container path
+      let containerPath = null;
+      if (containerNodeId) {
+        // Container is resolved - build path from container node
+        containerPath = buildContainerPath(graph, containerNodeId);
+      } else if (parentNodeId) {
+        // Nested chapter - use parent (book) to build path
+        containerPath = buildContainerPath(graph, parentNodeId);
+      } else if (decl.parentName) {
+        // Forward reference - build path from current scope to include series
+        // Walk up from currentNodeId to find series, then use book name
+        // This ensures uniqueness even when the container isn't resolved yet
+        const pathParts = [];
+        const seriesNodeId = findSeriesForNode(graph, currentNodeId);
+        if (seriesNodeId) {
+          const seriesNode = graph.nodes[seriesNodeId];
+          if (seriesNode) {
+            pathParts.push('series', seriesNode.name);
+          }
+        }
+        // Always include book name - if series wasn't found, we'll still have book name
+        // which should be unique within the current processing context
+        pathParts.push('book', decl.parentName);
+        containerPath = pathParts.length > 0 ? pathParts.join(':') : null;
+      }
+      
+      const nodeId = makeNodeId(universeName, 'chapter', decl.name, containerPath);
+      checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'chapter', decl.source);
+      
+      if (decl.parentName && !containerNodeId && pendingContainerResolutions) {
         // Container not found yet - may be a forward reference, track for later resolution
+        // Note: nodeId already includes the parent name, so it's unique even if container isn't resolved yet
         pendingContainerResolutions.push({
           nodeId,
           parentName: decl.parentName,
@@ -1087,26 +1185,6 @@ function processBody(
 
       graph.nodes[finalRelatesNodeId] = relatesNode;
       graph.nodes[parentNodeId].children.push(finalRelatesNodeId);
-
-      // Also create edge for backward compatibility
-      const edgeId = makeEdgeId(universeName, decl.a, decl.b, index);
-      const edge = {
-        id: edgeId,
-        kind: 'relates',
-        a: { text: decl.a },
-        b: { text: decl.b },
-        source: decl.source,
-      };
-
-      if (describeBlocks.length > 0) {
-        edge.describe = {
-          raw: describeBlocks[0].raw,
-          normalized: normalizeProseBlock(describeBlocks[0].raw),
-          source: describeBlocks[0].source,
-        };
-      }
-
-      graph.edges[edgeId] = edge;
     } else if (decl.kind === 'describe') {
       // Describe blocks are attached to their parent node
       // This is handled in createNode
@@ -1471,60 +1549,7 @@ function checkDuplicateRelates(graph, universeName, a, b, source) {
  * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index
  */
 function resolveEdges(graph, scopeIndex) {
-  // Build a set of relates node names to avoid duplicate warnings
-  // (edges are created for backward compatibility alongside relates nodes)
-  const relatesNodeNames = new Set();
-  for (const nodeId in graph.nodes) {
-    const node = graph.nodes[nodeId];
-    if (node.kind === 'relates') {
-      relatesNodeNames.add(node.name);
-    }
-  }
-
-  // Resolve edges (relates edges in object format)
-  for (const edgeId in graph.edges) {
-    const edge = graph.edges[edgeId];
-    const universeName = edgeId.split(':')[0];
-    const universeNodeId = `${universeName}:universe:${universeName}`;
-
-    // Check if this edge corresponds to a relates node
-    // If so, skip warnings here (they'll be generated during relates node resolution)
-    const edgeName = `${edge.a.text} and ${edge.b.text}`;
-    const reverseEdgeName = `${edge.b.text} and ${edge.a.text}`;
-    const hasRelatesNode = relatesNodeNames.has(edgeName) || relatesNodeNames.has(reverseEdgeName);
-
-    // Resolve endpoint A - start from universe scope
-    const resolvedA = resolveRelatesEndpoint(graph, scopeIndex, edge.a.text, universeNodeId, edge.source);
-    if (resolvedA.nodeId && !resolvedA.ambiguous) {
-      edge.a.target = resolvedA.nodeId;
-    } else if (!hasRelatesNode) {
-      // Only warn if there's no corresponding relates node (legacy edge-only format)
-      if (!resolvedA.ambiguous) {
-        graph.diagnostics.push({
-          severity: 'warning',
-          message: `Unresolved relates endpoint "${edge.a.text}" in universe "${universeName}"`,
-          source: edge.source,
-        });
-      }
-    }
-
-    // Resolve endpoint B - start from universe scope
-    const resolvedB = resolveRelatesEndpoint(graph, scopeIndex, edge.b.text, universeNodeId, edge.source);
-    if (resolvedB.nodeId && !resolvedB.ambiguous) {
-      edge.b.target = resolvedB.nodeId;
-    } else if (!hasRelatesNode) {
-      // Only warn if there's no corresponding relates node (legacy edge-only format)
-      if (!resolvedB.ambiguous) {
-        graph.diagnostics.push({
-          severity: 'warning',
-          message: `Unresolved relates endpoint "${edge.b.text}" in universe "${universeName}"`,
-          source: edge.source,
-        });
-      }
-    }
-  }
-
-  // Resolve relates nodes
+  // Resolve relates node endpoints
   for (const nodeId in graph.nodes) {
     const node = graph.nodes[nodeId];
     if (node.kind === 'relates' && node.unresolvedEndpoints) {
@@ -1678,32 +1703,31 @@ function extractAssertedEdges(graph, scopeIndex) {
   }
 
   // Extract from relates nodes (bidirectional relationships)
+  // Note: Relates are bidirectional, but we create only ONE edge entry
+  // The UI should traverse edges bidirectionally to show the relationship from both perspectives
+  //
+  // Metadata behavior: edge.meta contains metadata from endpointA's perspective (from block at endpointA).
+  // When viewing endpointB, the UI should look up endpointB-specific metadata from the relates node's
+  // from[endpointB] block. This allows different descriptions for the same relationship from each endpoint's view.
   for (const nodeId in graph.nodes) {
     const node = graph.nodes[nodeId];
     if (node.kind !== 'relates' || !node.endpoints || node.endpoints.length !== 2) continue;
 
     const [endpointA, endpointB] = node.endpoints;
 
-    // Relates are bidirectional - extract both directions as asserted edges
     // Use the relationship label from the relates node if available
     const viaLabel = node.relationships?.values?.[0] || 'related to';
 
-    // Create edge A -> B
+    // Create a single bidirectional edge (A -> B)
+    // The UI should show this relationship when viewing either endpoint
+    // Metadata is from endpointA's perspective; UI will look up endpointB-specific metadata when needed
     assertedEdges.push({
       from: endpointA,
       via: viaLabel, // Note: relates don't use relationship declarations, they use string labels
       to: endpointB,
-      meta: node.from?.[endpointA]?.describe,
-      source: node.source,
-    });
-
-    // Create edge B -> A (relates are bidirectional)
-    assertedEdges.push({
-      from: endpointB,
-      via: viaLabel,
-      to: endpointA,
-      meta: node.from?.[endpointB]?.describe,
+      meta: node.from?.[endpointA]?.describe, // Metadata from endpointA's perspective
       source: node.source,
+      bidirectional: true, // Mark as bidirectional so UI can traverse both directions
     });
   }
 
@@ -1743,6 +1767,7 @@ function normalizeEdges(assertedEdges, relationshipDecls, universeName) {
       asserted: true,
       sourceRefs: [asserted.source],
       meta: asserted.meta,
+      bidirectional: asserted.bidirectional || false, // Preserve bidirectional flag for relates edges
     });
 
     // Add inverse edge if applicable (only for declared relationships, not relates)
@@ -1786,7 +1811,8 @@ function normalizeEdges(assertedEdges, relationshipDecls, universeName) {
       }
     }
     // Note: If no relDecl found, it's likely a relates edge (string label, not declared relationship)
-    // Relates edges are already bidirectional in assertedEdges, so no inverse needed
+    // Relates edges are bidirectional - the UI should traverse them bidirectionally
+    // by checking both from/to fields, so we only create one edge entry
   }
 
   return normalizedEdges;
@@ -2120,10 +2146,47 @@ function deriveReferenceName(decl) {
  * @param {string} name
  * @returns {string}
  */
-function makeNodeId(universeName, kind, name) {
+function makeNodeId(universeName, kind, name, containerPath = null) {
+  if (containerPath) {
+    return `${universeName}:${kind}:${containerPath}:${name}`;
+  }
   return `${universeName}:${kind}:${name}`;
 }
 
+/**
+ * Builds a container path string from a node's parent chain
+ * @param {UniverseGraph} graph
+ * @param {string} containerNodeId - The container node ID
+ * @returns {string | null} - Container path like "series:Alchemy:book:Materials" or null if no container
+ */
+function buildContainerPath(graph, containerNodeId) {
+  if (!containerNodeId) return null;
+  
+  const containerNode = graph.nodes[containerNodeId];
+  // If container node doesn't exist yet (e.g., forward reference), return null
+  // The caller should handle this case appropriately
+  if (!containerNode) return null;
+  
+  const pathParts = [];
+  let current = containerNode;
+  
+  // Walk up the parent chain, collecting series and book names
+  while (current) {
+    if (current.kind === 'series' || current.kind === 'book') {
+      pathParts.unshift(current.kind, current.name);
+    }
+    if (current.parent) {
+      current = graph.nodes[current.parent];
+      // Safety check: if parent node doesn't exist, stop walking
+      if (!current) break;
+    } else {
+      break;
+    }
+  }
+  
+  return pathParts.length > 0 ? pathParts.join(':') : null;
+}
+
 /**
  * Creates a relates node ID (deterministic, endpoints in source order)
  * @param {string} universeName

package/src/ir.js

@@ -92,6 +92,7 @@
  * @property {string} to - Target node ID
  * @property {TextBlock} [meta] - Per-edge metadata (from target describe block)
  * @property {SourceSpan} source - Source location
+ * @property {boolean} [bidirectional] - Whether this edge is bidirectional (for relates blocks)
  */
 
 /**
@@ -102,6 +103,7 @@
  * @property {boolean} asserted - Whether this edge was explicitly authored
  * @property {SourceSpan[]} sourceRefs - Array of source locations (for inferred edges, points to asserted edge)
  * @property {TextBlock} [meta] - Per-edge metadata
+ * @property {boolean} [bidirectional] - Whether this edge is bidirectional (for relates blocks)
  */
 
 /**

package/src/parser.js

@@ -658,17 +658,23 @@ class Parser {
     const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     
-    // Chapters must belong to a book - check for "in" keyword
-    if (!this.match('KEYWORD') || this.peek()?.value !== 'in') {
+    // Chapters must belong to a book - check for "in" keyword or nested structure
+    let parentName = undefined;
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      // Explicit "in" clause
+      this.expect('KEYWORD', 'in');
+      const parentToken = this.expect('IDENTIFIER');
+      parentName = parentToken.value;
+    } else if (!this.match('LBRACE')) {
+      // Neither "in" nor nested - error
       const nextToken = this.peek();
       const line = nextToken ? nextToken.span.start.line : startToken.span.start.line;
       throw new Error(
         `Chapter "${nameToken.value}" must belong to a book. Use "chapter ${nameToken.value} in <BookName> { ... }" at ${this.file}:${line}`,
       );
     }
+    // If next token is LBRACE, it's nested - parentName stays undefined
     
-    this.expect('KEYWORD', 'in');
-    const parentToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
     this.pushAliasScope();
     const body = this.parseBlockBody(
@@ -682,7 +688,7 @@ class Parser {
       kind: 'chapter',
       spelledKind,
       name: nameToken.value,
-      parentName: parentToken.value,
+      parentName,
       aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {