@sprig-and-prose/sprig-universe 0.1.0

package/src/graph.js

@@ -0,0 +1,950 @@
+/**
+ * @fileoverview AST to UniverseGraph transformation
+ */
+
+import { normalizeProseBlock } from './util/text.js';
+
+/**
+ * @typedef {import('./ir.js').UniverseGraph} UniverseGraph
+ * @typedef {import('./ir.js').NodeModel} NodeModel
+ * @typedef {import('./ir.js').EdgeModel} EdgeModel
+ * @typedef {import('./ir.js').UniverseModel} UniverseModel
+ * @typedef {import('./ir.js').NodeRef} NodeRef
+ * @typedef {import('./ir.js').TextBlock} TextBlock
+ * @typedef {import('./ir.js').UnknownBlock} UnknownBlock
+ * @typedef {import('./ir.js').Diagnostic} Diagnostic
+ * @typedef {import('./ir.js').FromView} FromView
+ * @typedef {import('./ast.js').FileAST} FileAST
+ * @typedef {import('./ast.js').UniverseDecl} UniverseDecl
+ * @typedef {import('./ast.js').AnthologyDecl} AnthologyDecl
+ * @typedef {import('./ast.js').SeriesDecl} SeriesDecl
+ * @typedef {import('./ast.js').BookDecl} BookDecl
+ * @typedef {import('./ast.js').ChapterDecl} ChapterDecl
+ * @typedef {import('./ast.js').ConceptDecl} ConceptDecl
+ * @typedef {import('./ast.js').RelatesDecl} RelatesDecl
+ * @typedef {import('./ast.js').DescribeBlock} DescribeBlock
+ * @typedef {import('./ast.js').TitleBlock} TitleBlock
+ * @typedef {import('./ast.js').FromBlock} FromBlock
+ * @typedef {import('./ast.js').RelationshipsBlock} RelationshipsBlock
+ * @typedef {import('./ast.js').ReferencesBlock} ReferencesBlock
+ * @typedef {import('./ast.js').ReferenceBlock} ReferenceBlock
+ * @typedef {import('./ast.js').NamedReferenceBlock} NamedReferenceBlock
+ * @typedef {import('./ast.js').UsingInReferencesBlock} UsingInReferencesBlock
+ * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
+ * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
+ * @typedef {import('./ast.js').NamedDocumentBlock} NamedDocumentBlock
+ * @typedef {import('./ast.js').RepositoryDecl} RepositoryDecl
+ */
+
+/**
+ * Builds a UniverseGraph from parsed AST files
+ * @param {FileAST[]} fileASTs - Array of parsed file ASTs
+ * @returns {UniverseGraph}
+ */
+export function buildGraph(fileASTs) {
+  const graph = {
+    version: 1,
+    universes: {},
+    nodes: {},
+    edges: {},
+    diagnostics: [],
+    referencesByName: {},
+    documentsByName: {},
+  };
+
+  // Track node names within each universe for duplicate detection
+  const nameToNodeId = new Map(); // universeName -> Map<name, firstNodeId>
+  
+  // Track named references and documents per universe for duplicate detection
+  const namedReferencesByUniverse = new Map(); // universeName -> Map<name, { source }>
+  const namedDocumentsByUniverse = new Map(); // universeName -> Map<name, { source }>
+  
+  // Track repositories per universe
+  const repositoriesByUniverse = new Map(); // universeName -> Map<name, RepositoryDecl>
+
+  // First pass: collect all universe names with their file locations for validation
+  const universeNameToFiles = new Map(); // universeName -> Set<file>
+  for (const fileAST of fileASTs) {
+    for (const universeDecl of fileAST.universes) {
+      const universeName = universeDecl.name;
+      if (!universeNameToFiles.has(universeName)) {
+        universeNameToFiles.set(universeName, new Set());
+      }
+      universeNameToFiles.get(universeName).add(fileAST.file);
+    }
+  }
+
+  // Validate: all files must declare the same universe name
+  if (universeNameToFiles.size > 1) {
+    const universeGroups = Array.from(universeNameToFiles.entries()).map(([name, files]) => {
+      const fileList = Array.from(files).sort().join(', ');
+      return `'${name}' (files: ${fileList})`;
+    });
+    graph.diagnostics.push({
+      severity: 'error',
+      message: `Multiple distinct universes found across files: ${universeGroups.join('; ')}. All files must declare the same universe name.`,
+      source: undefined, // No specific source for this aggregate error
+    });
+    // Continue processing but validation will fail later
+  }
+
+  // Process each file
+  for (const fileAST of fileASTs) {
+    for (const universeDecl of fileAST.universes) {
+      const universeName = universeDecl.name;
+      const universeNodeId = makeNodeId(universeName, 'universe', universeName);
+
+      // Initialize universe model (only once per universe)
+      if (!graph.universes[universeName]) {
+        graph.universes[universeName] = {
+          name: universeName,
+          root: universeNodeId,
+        };
+      }
+
+      // Initialize name map for this universe (only once per universe)
+      if (!nameToNodeId.has(universeName)) {
+        nameToNodeId.set(universeName, new Map());
+      }
+      const nameMap = nameToNodeId.get(universeName);
+      
+      // Initialize tracking maps for named references and documents (only once per universe)
+      if (!namedReferencesByUniverse.has(universeName)) {
+        namedReferencesByUniverse.set(universeName, new Map());
+        graph.referencesByName[universeName] = {};
+      }
+      if (!namedDocumentsByUniverse.has(universeName)) {
+        namedDocumentsByUniverse.set(universeName, new Map());
+        graph.documentsByName[universeName] = {};
+      }
+      if (!repositoriesByUniverse.has(universeName)) {
+        repositoriesByUniverse.set(universeName, new Map());
+      }
+
+      // Check if universe node already exists (from a previous file)
+      const existingUniverseNode = graph.nodes[universeNodeId];
+      
+      if (existingUniverseNode) {
+        // Universe already exists - merge bodies instead of overwriting
+        
+        // Check for conflicting describe blocks
+        const existingDescribe = existingUniverseNode.describe;
+        const newDescribeBlock = universeDecl.body?.find((b) => b.kind === 'describe');
+        if (existingDescribe && newDescribeBlock) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Universe "${universeName}" has multiple describe blocks. Move all describe content into one file.`,
+            source: newDescribeBlock.source,
+          });
+          // Also add a diagnostic pointing to the first occurrence
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `First describe block for universe "${universeName}" was declared here.`,
+            source: existingDescribe.source,
+          });
+        }
+
+        // Check for conflicting title blocks
+        const existingTitle = existingUniverseNode.title;
+        const newTitleBlock = universeDecl.body?.find((b) => b.kind === 'title');
+        if (existingTitle && newTitleBlock) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Universe "${universeName}" has multiple title blocks. Move all title content into one file.`,
+            source: newTitleBlock.source,
+          });
+          // Also add a diagnostic pointing to the first occurrence
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `First title block for universe "${universeName}" was declared here.`,
+            source: existingUniverseNode.source, // Use universe node source for first title
+          });
+        }
+
+        // If no conflicts, merge the body (references, documentation, unknownBlocks, children)
+        // processBody will append to existing arrays and add children
+        processBody(
+          graph,
+          universeName,
+          universeNodeId,
+          universeDecl.body,
+          nameMap,
+          fileAST.file,
+          universeNodeId,
+          namedReferencesByUniverse.get(universeName),
+          namedDocumentsByUniverse.get(universeName),
+          repositoriesByUniverse.get(universeName),
+        );
+      } else {
+        // First time seeing this universe - create node and process body
+        const universeNode = createNode(
+          universeNodeId,
+          'universe',
+          universeName,
+          undefined,
+          universeDecl,
+        );
+        graph.nodes[universeNodeId] = universeNode;
+        nameMap.set(universeName, universeNodeId);
+
+        // Process universe body (universeNodeId is both parent and current node for UnknownBlocks)
+        processBody(
+          graph,
+          universeName,
+          universeNodeId,
+          universeDecl.body,
+          nameMap,
+          fileAST.file,
+          universeNodeId,
+          namedReferencesByUniverse.get(universeName),
+          namedDocumentsByUniverse.get(universeName),
+          repositoriesByUniverse.get(universeName),
+        );
+      }
+    }
+  }
+
+  // Extract repositories from all universes and convert to config format
+  graph.repositories = {};
+  for (const [universeName, reposMap] of repositoriesByUniverse.entries()) {
+    for (const [repoName, repoDecl] of reposMap.entries()) {
+      // Convert repository kind from package name to directory name
+      // '@sprig-and-prose/sprig-repository-github' -> 'sprig-repository-github'
+      let kindValue = String(repoDecl.repositoryKind);
+      if (kindValue.startsWith('@') && kindValue.includes('/')) {
+        const parts = kindValue.split('/');
+        kindValue = parts[parts.length - 1];
+      }
+      
+      graph.repositories[repoName] = {
+        kind: kindValue,
+        options: repoDecl.options,
+      };
+    }
+  }
+
+  // Resolve edge endpoints
+  resolveEdges(graph, nameToNodeId);
+
+  return graph;
+}
+
+/**
+ * Processes a body of declarations, creating nodes and edges
+ * @param {UniverseGraph} graph
+ * @param {string} universeName
+ * @param {string} parentNodeId - Parent node ID (for tree relationships)
+   * @param {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | ReferencesBlock | DocumentationBlock | NamedReferenceBlock | NamedDocumentBlock | UnknownBlock>} body
+ * @param {Map<string, string>} nameMap
+ * @param {string} file
+ * @param {string} currentNodeId - Current node ID (for attaching UnknownBlocks)
+ * @param {Map<string, { source: SourceSpan }>} [namedRefsMap] - Map for tracking named references (universe scope only)
+ * @param {Map<string, { source: SourceSpan }>} [namedDocsMap] - Map for tracking named documents (universe scope only)
+ * @param {Map<string, RepositoryDecl>} [reposMap] - Map for tracking repository declarations (universe scope only)
+ */
+function processBody(graph, universeName, parentNodeId, body, nameMap, file, currentNodeId, namedRefsMap, namedDocsMap, reposMap) {
+  for (const decl of body) {
+    if (decl.kind === 'anthology') {
+      const nodeId = makeNodeId(universeName, 'anthology', decl.name);
+      checkDuplicateName(graph, universeName, decl.name, nodeId, 'anthology', nameMap, decl.source);
+      const node = createNode(nodeId, 'anthology', decl.name, parentNodeId, decl);
+      graph.nodes[nodeId] = node;
+      graph.nodes[parentNodeId].children.push(nodeId);
+      nameMap.set(decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+    } else if (decl.kind === 'series') {
+      const nodeId = makeNodeId(universeName, 'series', decl.name);
+      checkDuplicateName(graph, universeName, decl.name, nodeId, 'series', nameMap, decl.source);
+      
+      // Handle optional anthology parent
+      let actualParentNodeId = parentNodeId;
+      if (decl.parentName) {
+        const anthologyNodeId = nameMap.get(decl.parentName);
+        if (anthologyNodeId) {
+          actualParentNodeId = anthologyNodeId;
+        }
+        // If anthology not found, fall back to parentNodeId (tolerant parsing)
+      }
+      
+      const node = createNode(nodeId, 'series', decl.name, actualParentNodeId, decl);
+      graph.nodes[nodeId] = node;
+      graph.nodes[actualParentNodeId].children.push(nodeId);
+      nameMap.set(decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+    } else if (decl.kind === 'book') {
+      const nodeId = makeNodeId(universeName, 'book', decl.name);
+      checkDuplicateName(graph, universeName, decl.name, nodeId, 'book', nameMap, decl.source);
+      const containerNodeId = nameMap.get(decl.parentName);
+      // Always set container for book nodes (even if undefined when parentName doesn't resolve)
+      const node = createNode(
+        nodeId,
+        'book',
+        decl.name,
+        containerNodeId || parentNodeId,
+        decl,
+        containerNodeId, // May be undefined if parentName doesn't resolve
+      );
+      graph.nodes[nodeId] = node;
+      if (containerNodeId) {
+        graph.nodes[containerNodeId].children.push(nodeId);
+      } else {
+        graph.nodes[parentNodeId].children.push(nodeId);
+      }
+      nameMap.set(decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+    } else if (decl.kind === 'chapter') {
+      const nodeId = makeNodeId(universeName, 'chapter', decl.name);
+      checkDuplicateName(graph, universeName, decl.name, nodeId, 'chapter', nameMap, decl.source);
+      const containerNodeId = nameMap.get(decl.parentName);
+      // Always set container for chapter nodes (even if undefined when parentName doesn't resolve)
+      const node = createNode(
+        nodeId,
+        'chapter',
+        decl.name,
+        containerNodeId || parentNodeId,
+        decl,
+        containerNodeId, // May be undefined if parentName doesn't resolve
+      );
+      graph.nodes[nodeId] = node;
+      if (containerNodeId) {
+        graph.nodes[containerNodeId].children.push(nodeId);
+      } else {
+        graph.nodes[parentNodeId].children.push(nodeId);
+      }
+      nameMap.set(decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+    } else if (decl.kind === 'concept') {
+      const nodeId = makeNodeId(universeName, 'concept', decl.name);
+      checkDuplicateName(graph, universeName, decl.name, nodeId, 'concept', nameMap, decl.source);
+      
+      // Handle optional parent
+      let actualParentNodeId = parentNodeId;
+      if (decl.parentName) {
+        const parentNodeIdFromName = nameMap.get(decl.parentName);
+        if (parentNodeIdFromName) {
+          actualParentNodeId = parentNodeIdFromName;
+        }
+        // If parent not found, fall back to parentNodeId (tolerant parsing)
+      }
+      
+      const node = createNode(nodeId, 'concept', decl.name, actualParentNodeId, decl);
+      graph.nodes[nodeId] = node;
+      graph.nodes[actualParentNodeId].children.push(nodeId);
+      nameMap.set(decl.name, nodeId);
+      processBody(graph, universeName, nodeId, decl.body, nameMap, file, nodeId, namedRefsMap, namedDocsMap);
+    } else if (decl.kind === 'relates') {
+      // Check for duplicate relates in reverse order
+      checkDuplicateRelates(graph, universeName, decl.a, decl.b, decl.source);
+
+      // Create relates node - resolution happens later
+      const relatesNodeId = makeRelatesNodeId(universeName, decl.a, decl.b);
+      // Check for duplicate relates and increment index if needed
+      let index = 0;
+      let finalRelatesNodeId = relatesNodeId;
+      while (graph.nodes[finalRelatesNodeId]) {
+        index++;
+        finalRelatesNodeId = makeRelatesNodeId(universeName, decl.a, decl.b, index);
+      }
+
+      // Process relates body: extract describe, from blocks, and unknown blocks
+      const describeBlocks = decl.body.filter((b) => b.kind === 'describe');
+      const fromBlocks = decl.body.filter((b) => b.kind === 'from');
+      const unknownBlocks = decl.body.filter((b) => b.kind !== 'describe' && b.kind !== 'from');
+
+      // Validate: only one top-level describe
+      if (describeBlocks.length > 1) {
+        graph.diagnostics.push({
+          severity: 'error',
+          message: `Multiple describe blocks in relates "${decl.a} and ${decl.b}"`,
+          source: describeBlocks[1].source,
+        });
+      }
+
+      // Validate: from blocks must reference endpoints
+      const endpointSet = new Set([decl.a, decl.b]);
+      const fromByEndpoint = new Map();
+      for (const fromBlock of fromBlocks) {
+        if (!endpointSet.has(fromBlock.endpoint)) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `from block references "${fromBlock.endpoint}" which is not an endpoint of relates "${decl.a} and ${decl.b}"`,
+            source: fromBlock.source,
+          });
+        } else {
+          // Check for duplicate from blocks for same endpoint
+          if (fromByEndpoint.has(fromBlock.endpoint)) {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Duplicate from block for endpoint "${fromBlock.endpoint}" in relates "${decl.a} and ${decl.b}"`,
+              source: fromBlock.source,
+            });
+          } else {
+            fromByEndpoint.set(fromBlock.endpoint, fromBlock);
+          }
+        }
+      }
+
+      // Build relates node
+      const relatesNode = {
+        id: finalRelatesNodeId,
+        kind: 'relates',
+        name: `${decl.a} and ${decl.b}`,
+        parent: parentNodeId,
+        children: [],
+        source: decl.source,
+        endpoints: [], // Will be populated during resolution
+        unresolvedEndpoints: [decl.a, decl.b], // Will be cleared during resolution
+      };
+
+      // Add top-level describe if present
+      if (describeBlocks.length > 0) {
+        relatesNode.describe = {
+          raw: describeBlocks[0].raw,
+          normalized: normalizeProseBlock(describeBlocks[0].raw),
+          source: describeBlocks[0].source,
+        };
+      }
+
+      // Process from blocks (will be resolved later)
+      relatesNode.from = {};
+      for (const fromBlock of fromBlocks) {
+        if (endpointSet.has(fromBlock.endpoint)) {
+          // Process from body
+          const relationshipsBlocks = fromBlock.body.filter((b) => b.kind === 'relationships');
+          const fromDescribeBlocks = fromBlock.body.filter((b) => b.kind === 'describe');
+          const fromUnknownBlocks = fromBlock.body.filter(
+            (b) => b.kind !== 'relationships' && b.kind !== 'describe',
+          );
+
+          // Validate: only one relationships and one describe per from
+          if (relationshipsBlocks.length > 1) {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Multiple relationships blocks in from "${fromBlock.endpoint}"`,
+              source: relationshipsBlocks[1].source,
+            });
+          }
+          if (fromDescribeBlocks.length > 1) {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Multiple describe blocks in from "${fromBlock.endpoint}"`,
+              source: fromDescribeBlocks[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 from "${fromBlock.endpoint}"`,
+              source: relationshipsBlocks[0].source,
+            });
+          }
+
+          const fromView = {
+            source: fromBlock.source,
+          };
+
+          if (relationshipsBlocks.length > 0) {
+            fromView.relationships = {
+              values: relationshipsBlocks[0].values,
+              source: relationshipsBlocks[0].source,
+            };
+          }
+
+          if (fromDescribeBlocks.length > 0) {
+            fromView.describe = {
+              raw: fromDescribeBlocks[0].raw,
+              normalized: normalizeProseBlock(fromDescribeBlocks[0].raw),
+              source: fromDescribeBlocks[0].source,
+            };
+          }
+
+          if (fromUnknownBlocks.length > 0) {
+            fromView.unknownBlocks = fromUnknownBlocks.map((ub) => ({
+              keyword: ub.keyword,
+              raw: ub.raw,
+              normalized: normalizeProseBlock(ub.raw),
+              source: ub.source,
+            }));
+          }
+
+          // Store by endpoint name for now, will be resolved to node ID later
+          relatesNode.from[fromBlock.endpoint] = fromView;
+        }
+      }
+
+      // Process unknown blocks at relates level
+      if (unknownBlocks.length > 0) {
+        relatesNode.unknownBlocks = unknownBlocks.map((ub) => ({
+          keyword: ub.keyword,
+          raw: ub.raw,
+          normalized: normalizeProseBlock(ub.raw),
+          source: ub.source,
+        }));
+      }
+
+      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
+    } else if (decl.kind === 'title') {
+      // Title blocks are attached to their parent node
+      // This is handled in createNode
+    } else if (decl.kind === 'references') {
+      // ReferencesBlock - attach to current node
+      const currentNode = graph.nodes[currentNodeId];
+      if (!currentNode.references) {
+        currentNode.references = [];
+      }
+      // Serialize references block - handle both inline references and using blocks
+      for (const item of decl.references) {
+        if (item.kind === 'reference') {
+          // Inline reference block - convert as before
+          currentNode.references.push({
+            repository: item.repository,
+            paths: item.paths,
+            kind: item.referenceKind,
+            describe: item.describe
+              ? {
+                  raw: item.describe.raw,
+                  normalized: normalizeProseBlock(item.describe.raw),
+                  source: item.describe.source,
+                }
+              : undefined,
+            source: item.source,
+          });
+        } else if (item.kind === 'using-in-references') {
+          // Using block - resolve each name against named references registry
+          for (const name of item.names) {
+            const namedRef = graph.referencesByName[universeName]?.[name];
+            if (namedRef) {
+              // Resolved: expand to reference object
+              currentNode.references.push({
+                repository: namedRef.repository,
+                paths: namedRef.paths,
+                kind: namedRef.kind,
+                describe: namedRef.describe,
+                source: namedRef.source, // Use the named reference's source, not the using block's
+              });
+            } else {
+              // Not resolved: emit error diagnostic
+              graph.diagnostics.push({
+                severity: 'error',
+                message: `Unknown reference '${name}' used in references block`,
+                source: item.source,
+              });
+            }
+          }
+        }
+      }
+    } else if (decl.kind === 'documentation') {
+      // DocumentationBlock - attach to current node
+      const currentNode = graph.nodes[currentNodeId];
+      if (!currentNode.documentation) {
+        currentNode.documentation = [];
+      }
+      // Serialize documentation block - each document block becomes an entry
+      for (const doc of decl.documents) {
+        currentNode.documentation.push({
+          title: doc.title,
+          kind: doc.documentKind,
+          path: doc.path,
+          describe: doc.describe
+            ? {
+                raw: doc.describe.raw,
+                normalized: normalizeProseBlock(doc.describe.raw),
+                source: doc.describe.source,
+              }
+            : undefined,
+          source: doc.source,
+        });
+      }
+    } else if (decl.kind === 'named-reference') {
+      // NamedReferenceBlock - store in universe-level registry
+      // Only process at universe scope (when namedRefsMap is provided)
+      if (namedRefsMap && parentNodeId === currentNodeId) {
+        const refName = decl.name;
+        
+        // Check for duplicate name
+        if (namedRefsMap.has(refName)) {
+          const firstOccurrence = namedRefsMap.get(refName);
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Duplicate named reference "${refName}" in universe "${universeName}". First declared at ${firstOccurrence.source.file}:${firstOccurrence.source.start.line}:${firstOccurrence.source.start.col}`,
+            source: decl.source,
+          });
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `First declaration of named reference "${refName}" was here.`,
+            source: firstOccurrence.source,
+          });
+        } else {
+          // Store first occurrence
+          namedRefsMap.set(refName, { source: decl.source });
+          
+          // Convert to model and store in registry
+          const refModel = {
+            name: refName,
+            repository: decl.repository,
+            paths: decl.paths,
+            kind: decl.referenceKind,
+            describe: decl.describe
+              ? {
+                  raw: decl.describe.raw,
+                  normalized: normalizeProseBlock(decl.describe.raw),
+                  source: decl.describe.source,
+                }
+              : undefined,
+            source: decl.source,
+          };
+          
+          graph.referencesByName[universeName][refName] = refModel;
+        }
+      }
+    } else if (decl.kind === 'repository') {
+      // RepositoryDecl - store in universe-level registry
+      // Only process at universe scope (when reposMap is provided)
+      if (reposMap && parentNodeId === currentNodeId) {
+        const repoName = decl.name;
+        
+        // Check for duplicate name
+        if (reposMap.has(repoName)) {
+          const firstOccurrence = reposMap.get(repoName);
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Duplicate repository "${repoName}" in universe "${universeName}". First declared at ${firstOccurrence.source.file}:${firstOccurrence.source.start.line}:${firstOccurrence.source.start.col}`,
+            source: decl.source,
+          });
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `First declaration of repository "${repoName}" was here.`,
+            source: firstOccurrence.source,
+          });
+        } else {
+          // Store repository declaration
+          reposMap.set(repoName, decl);
+        }
+      }
+    } else if (decl.kind === 'named-document') {
+      // NamedDocumentBlock - store in universe-level registry
+      // Only process at universe scope (when namedDocsMap is provided)
+      if (namedDocsMap && parentNodeId === currentNodeId) {
+        const docName = decl.name;
+        
+        // Check for duplicate name
+        if (namedDocsMap.has(docName)) {
+          const firstOccurrence = namedDocsMap.get(docName);
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Duplicate named document "${docName}" in universe "${universeName}". First declared at ${firstOccurrence.source.file}:${firstOccurrence.source.start.line}:${firstOccurrence.source.start.col}`,
+            source: decl.source,
+          });
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `First declaration of named document "${docName}" was here.`,
+            source: firstOccurrence.source,
+          });
+        } else {
+          // Store first occurrence
+          namedDocsMap.set(docName, { source: decl.source });
+          
+          // Convert to model and store in registry
+          const docModel = {
+            name: docName,
+            kind: decl.documentKind,
+            path: decl.path,
+            describe: decl.describe
+              ? {
+                  raw: decl.describe.raw,
+                  normalized: normalizeProseBlock(decl.describe.raw),
+                  source: decl.describe.source,
+                }
+              : undefined,
+            source: decl.source,
+          };
+          
+          graph.documentsByName[universeName][docName] = docModel;
+        }
+      }
+    } else {
+      // UnknownBlock - attach to current node (the node whose body contains this block)
+      const currentNode = graph.nodes[currentNodeId];
+      if (!currentNode.unknownBlocks) {
+        currentNode.unknownBlocks = [];
+      }
+      currentNode.unknownBlocks.push({
+        keyword: decl.keyword,
+        raw: decl.raw,
+        normalized: normalizeProseBlock(decl.raw),
+        source: decl.source,
+      });
+    }
+  }
+}
+
+/**
+ * Creates a node model from a declaration
+ * @param {string} nodeId
+ * @param {'universe' | 'anthology' | 'series' | 'book' | 'chapter'} kind
+ * @param {string} name
+ * @param {string | undefined} parentNodeId
+ * @param {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl} decl
+ * @param {string | undefined} containerNodeId
+ * @returns {NodeModel}
+ */
+function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
+  const node = {
+    id: nodeId,
+    kind,
+    name,
+    parent: parentNodeId,
+    children: [],
+    source: decl.source,
+  };
+
+  // Always set container for book/chapter nodes (may be undefined if not resolved)
+  if (kind === 'book' || kind === 'chapter') {
+    node.container = containerNodeId; // May be undefined
+  } else if (containerNodeId) {
+    // For other node types, only set if provided
+    node.container = containerNodeId;
+  }
+
+  // Extract describe block if present
+  const describeBlock = decl.body?.find((b) => b.kind === 'describe');
+  if (describeBlock) {
+    node.describe = {
+      raw: describeBlock.raw,
+      normalized: normalizeProseBlock(describeBlock.raw),
+      source: describeBlock.source,
+    };
+  }
+
+  // Extract title block if present
+  const titleBlock = decl.body?.find((b) => b.kind === 'title');
+  if (titleBlock) {
+    // Title is a simple string, so we normalize it (trim whitespace)
+    const titleValue = titleBlock.raw.trim();
+    if (titleValue.length > 0) {
+      node.title = titleValue;
+    }
+  }
+
+  // Note: UnknownBlocks are handled in processBody and attached to the parent node
+  // They are not extracted here to avoid duplication
+
+  return node;
+}
+
+/**
+ * Checks for duplicate node names and emits warning if found
+ * @param {UniverseGraph} graph
+ * @param {string} universeName
+ * @param {string} name
+ * @param {string} nodeId
+ * @param {string} kind - The kind of the current node being checked
+ * @param {Map<string, string>} nameMap
+ * @param {SourceSpan} source
+ */
+function checkDuplicateName(graph, universeName, name, nodeId, kind, nameMap, source) {
+  if (nameMap.has(name)) {
+    const firstNodeId = nameMap.get(name);
+    const firstNode = graph.nodes[firstNodeId];
+    const firstKind = firstNode?.kind || 'unknown';
+    graph.diagnostics.push({
+      severity: 'warning',
+      message: `Duplicate concept name "${name}" in universe "${universeName}": already defined as ${firstKind} (${firstNodeId}), now also defined as ${kind}`,
+      source: source, // Current duplicate's source span
+    });
+    // Note: Resolution will choose the first encountered (already in nameMap)
+  }
+}
+
+/**
+ * Checks for duplicate relates blocks in reverse order
+ * @param {UniverseGraph} graph
+ * @param {string} universeName
+ * @param {string} a
+ * @param {string} b
+ * @param {SourceSpan} source
+ */
+function checkDuplicateRelates(graph, universeName, a, b, source) {
+  // Check if a relates node exists with the reverse order
+  const reverseRelatesNodeId = makeRelatesNodeId(universeName, b, a);
+  if (graph.nodes[reverseRelatesNodeId]) {
+    graph.diagnostics.push({
+      severity: 'warning',
+      message: `Duplicate relates block: "${a} and ${b}" already exists as "${b} and ${a}"`,
+      source,
+    });
+  }
+}
+
+/**
+ * Resolves edge endpoint references and relates node endpoints
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string>>} nameToNodeId
+ */
+function resolveEdges(graph, nameToNodeId) {
+  // 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 (for backward compatibility)
+  for (const edgeId in graph.edges) {
+    const edge = graph.edges[edgeId];
+    const universeName = edgeId.split(':')[0];
+    const nameMap = nameToNodeId.get(universeName);
+
+    if (nameMap) {
+      // 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
+      const targetA = nameMap.get(edge.a.text);
+      if (targetA) {
+        edge.a.target = targetA;
+      } else if (!hasRelatesNode) {
+        // Only warn if there's no corresponding relates node (legacy edge-only format)
+        graph.diagnostics.push({
+          severity: 'warning',
+          message: `Unresolved relates endpoint "${edge.a.text}" in universe "${universeName}"`,
+          source: edge.source,
+        });
+      }
+
+      // Resolve endpoint B
+      const targetB = nameMap.get(edge.b.text);
+      if (targetB) {
+        edge.b.target = targetB;
+      } else if (!hasRelatesNode) {
+        // Only warn if there's no corresponding relates node (legacy edge-only format)
+        graph.diagnostics.push({
+          severity: 'warning',
+          message: `Unresolved relates endpoint "${edge.b.text}" in universe "${universeName}"`,
+          source: edge.source,
+        });
+      }
+    }
+  }
+
+  // Resolve relates nodes
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (node.kind === 'relates' && node.unresolvedEndpoints) {
+      const universeName = nodeId.split(':')[0];
+      const nameMap = nameToNodeId.get(universeName);
+
+      if (nameMap) {
+        const resolvedEndpoints = [];
+        const unresolved = [];
+
+        for (const endpointName of node.unresolvedEndpoints) {
+          const targetId = nameMap.get(endpointName);
+          if (targetId) {
+            resolvedEndpoints.push(targetId);
+          } else {
+            unresolved.push(endpointName);
+            graph.diagnostics.push({
+              severity: 'warning',
+              message: `Unresolved relates endpoint "${endpointName}" in universe "${universeName}"`,
+              source: node.source,
+            });
+          }
+        }
+
+        node.endpoints = resolvedEndpoints;
+        if (unresolved.length > 0) {
+          node.unresolvedEndpoints = unresolved;
+        } else {
+          delete node.unresolvedEndpoints;
+        }
+
+        // Resolve from blocks: convert from endpoint names to node IDs
+        if (node.from) {
+          const resolvedFrom = {};
+          for (const endpointName in node.from) {
+            const targetId = nameMap.get(endpointName);
+            if (targetId) {
+              resolvedFrom[targetId] = node.from[endpointName];
+            } else {
+              // Keep unresolved from blocks keyed by name
+              resolvedFrom[endpointName] = node.from[endpointName];
+            }
+          }
+          node.from = resolvedFrom;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Creates a node ID
+ * @param {string} universeName
+ * @param {string} kind
+ * @param {string} name
+ * @returns {string}
+ */
+function makeNodeId(universeName, kind, name) {
+  return `${universeName}:${kind}:${name}`;
+}
+
+/**
+ * Creates a relates node ID (deterministic, endpoints in source order)
+ * @param {string} universeName
+ * @param {string} a
+ * @param {string} b
+ * @param {number} [index=0]
+ * @returns {string}
+ */
+function makeRelatesNodeId(universeName, a, b, index = 0) {
+  if (index === 0) {
+    return `${universeName}:relates:${a}:${b}`;
+  }
+  return `${universeName}:relates:${a}:${b}:${index}`;
+}
+
+/**
+ * Creates an edge ID
+ * @param {string} universeName
+ * @param {string} a
+ * @param {string} b
+ * @param {number} index
+ * @returns {string}
+ */
+function makeEdgeId(universeName, a, b, index) {
+  return `${universeName}:relates:${a}--${b}:${index}`;
+}
+