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

package/src/graph.js

@@ -27,9 +27,7 @@ import { normalizeProseBlock } from './util/text.js';
  * @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').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
  * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
  * @typedef {import('./ast.js').NamedDocumentBlock} NamedDocumentBlock
@@ -52,20 +50,30 @@ export function buildGraph(fileASTs) {
     nodes: {},
     edges: {},
     diagnostics: [],
-    referencesByName: {},
     documentsByName: {},
+    repositories: {},
+    references: {},
   };
 
   // Track node names within each scope (container) for scoped resolution
   // Map<containerNodeId, Map<name, nodeId[]>> - allows multiple nodes with same name in different scopes
   const scopeIndex = new Map(); // containerNodeId -> Map<name, nodeId[]>
   
-  // Track named references and documents per universe for duplicate detection
-  const namedReferencesByUniverse = new Map(); // universeName -> Map<name, { source }>
+  // Track named documents per universe for duplicate detection
   const namedDocumentsByUniverse = new Map(); // universeName -> Map<name, { source }>
   
-  // Track repositories per universe
-  const repositoriesByUniverse = new Map(); // universeName -> Map<name, RepositoryDecl>
+  // Track repositories and references per universe for scoped resolution
+  const repositoriesByUniverse = new Map(); // universeName -> Map<id, RepositoryDecl>
+  const referencesByUniverse = new Map(); // universeName -> Map<id, ReferenceDecl>
+
+  // Track entity kinds for duplicate detection (references/repositories)
+  const entityKinds = new Map(); // id -> kind
+
+  // Pending resolutions
+  /** @type {Array<{ refId: string, decl: ReferenceDecl, universeName: string, scopeNodeId: string }>} */
+  const pendingReferenceDecls = [];
+  /** @type {Array<{ nodeId: string, items: Array<{ name: string, source: SourceSpan }>, universeName: string }>} */
+  const pendingReferenceAttachments = [];
 
   // First pass: collect all universe names with their file locations for validation
   const universeNameToFiles = new Map(); // universeName -> Set<file>
@@ -107,11 +115,6 @@ export function buildGraph(fileASTs) {
         };
       }
 
-      // 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] = {};
@@ -119,6 +122,9 @@ export function buildGraph(fileASTs) {
       if (!repositoriesByUniverse.has(universeName)) {
         repositoriesByUniverse.set(universeName, new Map());
       }
+      if (!referencesByUniverse.has(universeName)) {
+        referencesByUniverse.set(universeName, new Map());
+      }
 
       // Check if universe node already exists (from a previous file)
       const existingUniverseNode = graph.nodes[universeNodeId];
@@ -177,9 +183,12 @@ export function buildGraph(fileASTs) {
           scopeIndex,
           fileAST.file,
           universeNodeId,
-          namedReferencesByUniverse.get(universeName),
           namedDocumentsByUniverse.get(universeName),
           repositoriesByUniverse.get(universeName),
+          referencesByUniverse.get(universeName),
+          entityKinds,
+          pendingReferenceDecls,
+          pendingReferenceAttachments,
         );
       } else {
         // First time seeing this universe - create node and process body
@@ -203,34 +212,77 @@ export function buildGraph(fileASTs) {
           scopeIndex,
           fileAST.file,
           universeNodeId,
-          namedReferencesByUniverse.get(universeName),
           namedDocumentsByUniverse.get(universeName),
           repositoriesByUniverse.get(universeName),
+          referencesByUniverse.get(universeName),
+          entityKinds,
+          pendingReferenceDecls,
+          pendingReferenceAttachments,
         );
       }
     }
   }
 
-  // Extract repositories and convert to config format
-  // Note: There's only one universe per manifest, so we iterate over the single entry
-  graph.repositories = {};
-  for (const reposMap of repositoriesByUniverse.values()) {
-    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];
+  // Attach unscoped top-level declarations to the single universe if present
+  if (universeNameToFiles.size === 1) {
+    const [universeName] = universeNameToFiles.keys();
+    const universeModel = graph.universes[universeName];
+    const universeNodeId = universeModel?.root;
+    if (universeNodeId) {
+      for (const fileAST of fileASTs) {
+        if (!fileAST.topLevelDecls || fileAST.topLevelDecls.length === 0) {
+          continue;
+        }
+        for (const decl of fileAST.topLevelDecls) {
+          if (decl.parentName) {
+            const resolved = resolveNameInScope(
+              graph,
+              scopeIndex,
+              decl.parentName,
+              universeNodeId,
+              decl.source,
+            );
+            if (!resolved.nodeId && !resolved.ambiguous) {
+              graph.diagnostics.push({
+                severity: 'error',
+                message: `Top-level ${decl.kind} "${decl.name}" references unknown container "${decl.parentName}"`,
+                source: diagnosticSource(decl.source),
+              });
+              continue;
+            }
+          }
+          processBody(
+            graph,
+            universeName,
+            universeNodeId,
+            [decl],
+            scopeIndex,
+            fileAST.file,
+            universeNodeId,
+            namedDocumentsByUniverse.get(universeName),
+            repositoriesByUniverse.get(universeName),
+            referencesByUniverse.get(universeName),
+            entityKinds,
+            pendingReferenceDecls,
+            pendingReferenceAttachments,
+          );
+        }
       }
-      
-      graph.repositories[repoName] = {
-        kind: kindValue,
-        options: repoDecl.options,
-      };
     }
   }
 
+  // Resolve reference declarations and attach references after all names are indexed
+  resolveReferenceDecls(
+    graph,
+    pendingReferenceDecls,
+    scopeIndex,
+  );
+  resolveReferenceAttachments(
+    graph,
+    pendingReferenceAttachments,
+    scopeIndex,
+  );
+
   // Resolve edge endpoints
   resolveEdges(graph, scopeIndex);
 
@@ -384,29 +436,112 @@ function resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source) {
   return { nodeId: null, ambiguous: false, ambiguousNodes: [] };
 }
 
+/**
+ * Resolve relates endpoints with a universe-wide fallback.
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} name
+ * @param {string} startScopeNodeId
+ * @param {SourceSpan} [source]
+ * @returns {{ nodeId: string | null, ambiguous: boolean, ambiguousNodes: string[] }}
+ */
+function resolveRelatesEndpoint(graph, scopeIndex, name, startScopeNodeId, source) {
+  const resolved = resolveNameInScope(graph, scopeIndex, name, startScopeNodeId, source);
+  if (resolved.nodeId || resolved.ambiguous) {
+    return resolved;
+  }
+
+  const universeName = startScopeNodeId.split(':')[0];
+  const matches = [];
+  for (const nodeId in graph.nodes) {
+    if (!nodeId.startsWith(`${universeName}:`)) {
+      continue;
+    }
+    const node = graph.nodes[nodeId];
+    if (node && node.name === name) {
+      matches.push(nodeId);
+    }
+  }
+
+  if (matches.length === 1) {
+    return { nodeId: matches[0], ambiguous: false, ambiguousNodes: [] };
+  }
+
+  if (matches.length > 1) {
+    if (source) {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Ambiguous relates endpoint "${name}" in universe "${universeName}": found ${matches.length} matches`,
+        source,
+      });
+    }
+    return { nodeId: null, ambiguous: true, ambiguousNodes: matches };
+  }
+
+  return resolved;
+}
+
 /**
  * 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 {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body
  * @param {Map<string, Map<string, string[]>>} scopeIndex - Scope index: containerNodeId -> Map<name, nodeId[]>
  * @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)
+ * @param {Map<string, ReferenceDecl>} [refsMap] - Map for tracking reference declarations (universe scope only)
+ * @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
  */
-function processBody(graph, universeName, parentNodeId, body, scopeIndex, file, currentNodeId, namedRefsMap, namedDocsMap, reposMap) {
+function processBody(
+  graph,
+  universeName,
+  parentNodeId,
+  body,
+  scopeIndex,
+  file,
+  currentNodeId,
+  namedDocsMap,
+  reposMap,
+  refsMap,
+  entityKinds,
+  pendingReferenceDecls,
+  pendingReferenceAttachments,
+) {
   for (const decl of body) {
     if (decl.kind === 'anthology') {
       const nodeId = makeNodeId(universeName, 'anthology', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'anthology', decl.source);
-      const node = createNode(nodeId, 'anthology', decl.name, parentNodeId, decl);
+      let actualParentNodeId = parentNodeId;
+      if (decl.parentName) {
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          actualParentNodeId = resolved.nodeId;
+        }
+      }
+      const node = createNode(nodeId, 'anthology', decl.name, actualParentNodeId, decl);
       graph.nodes[nodeId] = node;
-      graph.nodes[parentNodeId].children.push(nodeId);
+      graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } else if (decl.kind === 'series') {
       const nodeId = makeNodeId(universeName, 'series', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'series', decl.source);
@@ -425,34 +560,99 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } else if (decl.kind === 'book') {
       const nodeId = makeNodeId(universeName, 'book', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'book', decl.source);
-      const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
-      const containerNodeId = resolved.nodeId && !resolved.ambiguous ? resolved.nodeId : null;
-      // Always set container for book nodes (even if undefined when parentName doesn't resolve)
+      
+      // Handle optional parent
+      let actualParentNodeId = parentNodeId;
+      let containerNodeId = undefined;
+      if (decl.parentName) {
+        const resolved = resolveNameInScope(graph, scopeIndex, decl.parentName, currentNodeId, decl.source);
+        if (resolved.nodeId && !resolved.ambiguous) {
+          actualParentNodeId = resolved.nodeId;
+          containerNodeId = resolved.nodeId;
+        }
+        // If parent not found, fall back to parentNodeId (tolerant parsing)
+      }
+      
       const node = createNode(
         nodeId,
         'book',
         decl.name,
-        containerNodeId || parentNodeId,
+        actualParentNodeId,
         decl,
-        containerNodeId, // May be undefined if parentName doesn't resolve
+        containerNodeId, // May be undefined if no parentName or if parentName doesn't resolve
       );
       graph.nodes[nodeId] = node;
-      if (containerNodeId) {
-        graph.nodes[containerNodeId].children.push(nodeId);
-      } else {
-        graph.nodes[parentNodeId].children.push(nodeId);
-      }
+      graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } 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;
+      
+      // Validate: chapter container must be a book
+      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 if (decl.parentName) {
+        // Container not found
+        graph.diagnostics.push({
+          severity: 'error',
+          message: `Chapter "${decl.name}" references unknown book "${decl.parentName}"`,
+          source: decl.source,
+        });
+      }
+      
       // Always set container for chapter nodes (even if undefined when parentName doesn't resolve)
       const node = createNode(
         nodeId,
@@ -469,7 +669,21 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
         graph.nodes[parentNodeId].children.push(nodeId);
       }
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } else if (decl.kind === 'concept') {
       const nodeId = makeNodeId(universeName, 'concept', decl.name);
       checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, nodeId, 'concept', decl.source);
@@ -488,7 +702,21 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
       graph.nodes[nodeId] = node;
       graph.nodes[actualParentNodeId].children.push(nodeId);
       addNameToScope(graph, scopeIndex, currentNodeId, decl.name, nodeId);
-      processBody(graph, universeName, nodeId, decl.body, scopeIndex, file, nodeId, namedRefsMap, namedDocsMap);
+      processBody(
+        graph,
+        universeName,
+        nodeId,
+        decl.body,
+        scopeIndex,
+        file,
+        nodeId,
+        namedDocsMap,
+        reposMap,
+        refsMap,
+        entityKinds,
+        pendingReferenceDecls,
+        pendingReferenceAttachments,
+      );
     } else if (decl.kind === 'relates') {
       // Check for duplicate relates in reverse order
       checkDuplicateRelates(graph, universeName, decl.a, decl.b, decl.source);
@@ -670,51 +898,12 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
       // 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,
-              });
-            }
-          }
-        }
+      if (pendingReferenceAttachments) {
+        pendingReferenceAttachments.push({
+          nodeId: currentNodeId,
+          items: decl.items,
+          universeName,
+        });
       }
     } else if (decl.kind === 'documentation') {
       // DocumentationBlock - attach to current node
@@ -738,35 +927,75 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
           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 if (decl.kind === 'reference') {
+      if (refsMap && entityKinds && pendingReferenceDecls) {
+        const baseName = decl.name || deriveReferenceName(decl);
+        const uniqueName = decl.name
+          ? baseName
+          : pickUniqueName(scopeIndex, currentNodeId, baseName);
+        const qualifiedName = makeQualifiedName(graph, currentNodeId, uniqueName);
+        const refId = makeEntityId(universeName, 'reference', qualifiedName);
+        if (decl.name) {
+          checkDuplicateInScope(graph, scopeIndex, currentNodeId, decl.name, refId, 'reference', decl.source, entityKinds);
+        }
+
+        if (!refsMap.has(refId)) {
+          refsMap.set(refId, decl);
+          entityKinds.set(refId, 'reference');
+          addNameToScope(graph, scopeIndex, currentNodeId, uniqueName, refId);
+          if (!graph.references[refId]) {
+            graph.references[refId] = {
+              id: refId,
+              name: uniqueName,
+              urls: [],
+              source: decl.source,
+            };
+          }
+          pendingReferenceDecls.push({
+            refId,
+            decl,
+            universeName,
+            scopeNodeId: currentNodeId,
           });
-        } 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,
+
+          if (pendingReferenceAttachments && currentNodeId !== makeNodeId(universeName, 'universe', universeName)) {
+            pendingReferenceAttachments.push({
+              nodeId: currentNodeId,
+              items: [
+                {
+                  name: uniqueName,
+                  source: decl.source,
+                },
+              ],
+              universeName,
+            });
+          }
+        }
+      }
+    } else if (decl.kind === 'repository') {
+      // RepositoryDecl - store in universe-level registry
+      if (reposMap && entityKinds) {
+        const scopeNodeId = resolveContainerScope(graph, scopeIndex, currentNodeId, decl.parentName, decl.source);
+        const qualifiedName = makeQualifiedName(graph, scopeNodeId, decl.name);
+        const repoId = makeEntityId(universeName, 'repository', qualifiedName);
+        checkDuplicateInScope(graph, scopeIndex, scopeNodeId, decl.name, repoId, 'repository', decl.source, entityKinds);
+
+        if (!reposMap.has(repoId)) {
+          reposMap.set(repoId, decl);
+          entityKinds.set(repoId, 'repository');
+          addNameToScope(graph, scopeIndex, scopeNodeId, decl.name, repoId);
+          if (!decl.url) {
+            graph.diagnostics.push({
+              severity: 'error',
+              message: `Repository "${decl.name}" is missing url { '...' }`,
+              source: decl.source,
+            });
+          }
+          graph.repositories[repoId] = {
+            id: repoId,
+            name: decl.name,
+            url: decl.url || '',
+            title: normalizeTitleValue(decl.title?.raw),
             describe: decl.describe
               ? {
                   raw: decl.describe.raw,
@@ -774,34 +1003,15 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
                   source: decl.describe.source,
                 }
               : undefined,
+            note: decl.note
+              ? {
+                  raw: decl.note.raw,
+                  normalized: normalizeProseBlock(decl.note.raw),
+                  source: decl.note.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') {
@@ -868,7 +1078,7 @@ function processBody(graph, universeName, parentNodeId, body, scopeIndex, file,
  * @param {string} name
  * @param {string | undefined} parentNodeId
  * @param {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl} decl
- * @param {string | undefined} containerNodeId
+ * @param {string | undefined} [containerNodeId]
  * @returns {NodeModel}
  */
 function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
@@ -924,15 +1134,16 @@ function createNode(nodeId, kind, name, parentNodeId, decl, containerNodeId) {
  * @param {string} nodeId
  * @param {string} kind - The kind of the current node being checked
  * @param {SourceSpan} source
+ * @param {Map<string, string>} [entityKinds]
  */
-function checkDuplicateInScope(graph, scopeIndex, scopeNodeId, name, nodeId, kind, source) {
+function checkDuplicateInScope(graph, scopeIndex, scopeNodeId, name, nodeId, kind, source, entityKinds) {
   const scopeMap = scopeIndex.get(scopeNodeId);
   if (scopeMap && scopeMap.has(name)) {
     const existingNodeIds = scopeMap.get(name);
     if (existingNodeIds.length > 0) {
       const firstNodeId = existingNodeIds[0];
       const firstNode = graph.nodes[firstNodeId];
-      const firstKind = firstNode?.kind || 'unknown';
+      const firstKind = firstNode?.kind || entityKinds?.get(firstNodeId) || 'unknown';
       const scopeNode = graph.nodes[scopeNodeId];
       const scopeName = scopeNode ? (scopeNode.name || scopeNodeId) : scopeNodeId;
       graph.diagnostics.push({
@@ -998,7 +1209,7 @@ function resolveEdges(graph, scopeIndex) {
     const hasRelatesNode = relatesNodeNames.has(edgeName) || relatesNodeNames.has(reverseEdgeName);
 
     // Resolve endpoint A - start from universe scope
-    const resolvedA = resolveNameInScope(graph, scopeIndex, edge.a.text, universeNodeId, edge.source);
+    const resolvedA = resolveRelatesEndpoint(graph, scopeIndex, edge.a.text, universeNodeId, edge.source);
     if (resolvedA.nodeId && !resolvedA.ambiguous) {
       edge.a.target = resolvedA.nodeId;
     } else if (!hasRelatesNode) {
@@ -1013,7 +1224,7 @@ function resolveEdges(graph, scopeIndex) {
     }
 
     // Resolve endpoint B - start from universe scope
-    const resolvedB = resolveNameInScope(graph, scopeIndex, edge.b.text, universeNodeId, edge.source);
+    const resolvedB = resolveRelatesEndpoint(graph, scopeIndex, edge.b.text, universeNodeId, edge.source);
     if (resolvedB.nodeId && !resolvedB.ambiguous) {
       edge.b.target = resolvedB.nodeId;
     } else if (!hasRelatesNode) {
@@ -1042,7 +1253,7 @@ function resolveEdges(graph, scopeIndex) {
       const unresolved = [];
 
       for (const endpointName of node.unresolvedEndpoints) {
-        const resolved = resolveNameInScope(graph, scopeIndex, endpointName, relatesScope, node.source);
+        const resolved = resolveRelatesEndpoint(graph, scopeIndex, endpointName, relatesScope, node.source);
         if (resolved.nodeId && !resolved.ambiguous) {
           resolvedEndpoints.push(resolved.nodeId);
         } else {
@@ -1068,7 +1279,7 @@ function resolveEdges(graph, scopeIndex) {
       if (node.from) {
         const resolvedFrom = {};
         for (const endpointName in node.from) {
-          const resolved = resolveNameInScope(graph, scopeIndex, endpointName, relatesScope, node.source);
+          const resolved = resolveRelatesEndpoint(graph, scopeIndex, endpointName, relatesScope, node.source);
           if (resolved.nodeId && !resolved.ambiguous) {
             resolvedFrom[resolved.nodeId] = node.from[endpointName];
           } else {
@@ -1082,6 +1293,320 @@ function resolveEdges(graph, scopeIndex) {
   }
 }
 
+/**
+ * @param {string | undefined} raw
+ * @returns {string | undefined}
+ */
+function normalizeTitleValue(raw) {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  const unquoted = trimmed.replace(/^['"]|['"]$/g, '');
+  return unquoted.trim() || undefined;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Array<{refId: string, decl: ReferenceDecl, universeName: string, scopeNodeId: string}>} pending
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ */
+function resolveReferenceDecls(graph, pending, scopeIndex) {
+  /** @type {Map<string, { count: number, source: SourceSpan | undefined }>} */
+  const unknownRepoCounts = new Map();
+  for (const item of pending) {
+    const { refId, decl, scopeNodeId } = item;
+    const model = graph.references[refId] || { id: refId, name: decl.name, urls: [], source: decl.source };
+    const displayName = model.name || decl.name || 'unnamed reference';
+    let urls = [];
+    let repositoryRef = undefined;
+
+    if (decl.url && decl.repositoryName) {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" cannot include both url { ... } and in <Repository>`,
+        source: diagnosticSource(decl.source),
+      });
+    }
+
+    if (decl.url) {
+      urls = [decl.url];
+    } else if (decl.repositoryName) {
+      const resolved = resolveNameInScope(graph, scopeIndex, decl.repositoryName, scopeNodeId, decl.source);
+      if (resolved.nodeId && !resolved.ambiguous) {
+        const repo = graph.repositories[resolved.nodeId];
+        if (!repo) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Reference "${displayName}" uses "${decl.repositoryName}" which is not a repository`,
+            source: diagnosticSource(decl.source),
+          });
+        } else if (!repo.url) {
+          graph.diagnostics.push({
+            severity: 'error',
+            message: `Repository "${repo.name}" is missing url { '...' }`,
+            source: decl.source,
+          });
+        } else {
+          repositoryRef = repo.id;
+          if (decl.paths && decl.paths.length > 0) {
+            urls = decl.paths.map((path) => joinRepositoryUrl(repo.url, path));
+          } else if (decl.paths && decl.paths.length === 0) {
+          graph.diagnostics.push({
+              severity: 'error',
+              message: `Reference "${displayName}" has an empty paths block`,
+            source: diagnosticSource(decl.source),
+            });
+          } else {
+            urls = [repo.url];
+          }
+        }
+      } else if (!resolved.ambiguous) {
+        const entry = unknownRepoCounts.get(decl.repositoryName) || {
+          count: 0,
+          source: decl.source,
+        };
+        entry.count += 1;
+        if (!entry.source && decl.source) {
+          entry.source = decl.source;
+        }
+        unknownRepoCounts.set(decl.repositoryName, entry);
+      }
+    } else {
+      graph.diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" must have url { ... } or in <Repository>`,
+        source: diagnosticSource(decl.source),
+      });
+    }
+
+    model.name = decl.name || model.name || displayName;
+    model.kind = decl.referenceKind || undefined;
+    model.title = normalizeTitleValue(decl.title?.raw);
+    model.describe = decl.describe
+      ? {
+          raw: decl.describe.raw,
+          normalized: normalizeProseBlock(decl.describe.raw),
+          source: decl.describe.source,
+        }
+      : undefined;
+    model.note = decl.note
+      ? {
+          raw: decl.note.raw,
+          normalized: normalizeProseBlock(decl.note.raw),
+          source: decl.note.source,
+        }
+      : undefined;
+    model.urls = urls;
+    model.repositoryRef = repositoryRef;
+    model.paths = decl.paths && decl.paths.length > 0 ? decl.paths : undefined;
+    model.source = decl.source;
+    graph.references[refId] = model;
+  }
+
+  for (const [repoName, info] of unknownRepoCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    graph.diagnostics.push({
+      severity: 'error',
+      message: `Unknown repository "${repoName}" used by references${countText}.`,
+      source: diagnosticSource(info.source),
+    });
+  }
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Array<{nodeId: string, items: Array<{ name: string, source: SourceSpan }>, universeName: string}>} pending
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ */
+function resolveReferenceAttachments(graph, pending, scopeIndex) {
+  /** @type {Map<string, { count: number, source: SourceSpan | undefined }>} */
+  const unknownReferenceCounts = new Map();
+
+  for (const item of pending) {
+    const node = graph.nodes[item.nodeId];
+    if (!node) {
+      continue;
+    }
+    if (!node.references) {
+      node.references = [];
+    }
+
+    for (const entry of item.items) {
+      const name = entry.name;
+      const resolved = resolveNameInScope(graph, scopeIndex, name, item.nodeId, entry.source);
+      if (resolved.nodeId && !resolved.ambiguous) {
+        if (graph.references[resolved.nodeId]) {
+          node.references.push(resolved.nodeId);
+        } else {
+          const existing = unknownReferenceCounts.get(name) || { count: 0, source: entry.source };
+          existing.count += 1;
+          if (!existing.source && entry.source) {
+            existing.source = entry.source;
+          }
+          unknownReferenceCounts.set(name, existing);
+        }
+      } else if (!resolved.ambiguous) {
+        const existing = unknownReferenceCounts.get(name) || { count: 0, source: entry.source };
+        existing.count += 1;
+        if (!existing.source && entry.source) {
+          existing.source = entry.source;
+        }
+        unknownReferenceCounts.set(name, existing);
+      }
+    }
+  }
+
+  for (const [name, info] of unknownReferenceCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    graph.diagnostics.push({
+      severity: 'error',
+      message: `Unknown reference "${name}" in references list${countText}. References must use reference names, not paths.`,
+      source: diagnosticSource(info.source),
+    });
+  }
+}
+
+/**
+ * @param {SourceSpan | undefined} source
+ * @returns {SourceSpan | { file: string, line?: number, col?: number, start?: any, end?: any } | undefined}
+ */
+function diagnosticSource(source) {
+  if (!source) return undefined;
+  return {
+    file: source.file,
+    line: source.start?.line,
+    col: source.start?.col,
+    start: source.start,
+    end: source.end,
+  };
+}
+
+/**
+ * @param {string} base
+ * @param {string} path
+ * @returns {string}
+ */
+function joinRepositoryUrl(base, path) {
+  if (base.endsWith('/') && path.startsWith('/')) {
+    return base + path.slice(1);
+  }
+  if (!base.endsWith('/') && !path.startsWith('/')) {
+    return `${base}/${path}`;
+  }
+  return base + path;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {string} containerNodeId
+ * @param {string} name
+ * @returns {string}
+ */
+function makeQualifiedName(graph, containerNodeId, name) {
+  const path = [];
+  let current = containerNodeId;
+  const visited = new Set();
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const node = graph.nodes[current];
+    if (!node) break;
+    if (node.kind !== 'universe') {
+      path.push(node.name);
+    }
+    current = node.parent;
+  }
+  path.reverse();
+  path.push(name);
+  return path.join('.');
+}
+
+/**
+ * @param {string} universeName
+ * @param {string} kind
+ * @param {string} qualifiedName
+ * @returns {string}
+ */
+function makeEntityId(universeName, kind, qualifiedName) {
+  return `${universeName}:${kind}:${qualifiedName}`;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} currentNodeId
+ * @param {string | undefined} parentName
+ * @param {SourceSpan} source
+ * @returns {string}
+ */
+function resolveContainerScope(graph, scopeIndex, currentNodeId, parentName, source) {
+  if (!parentName) {
+    return currentNodeId;
+  }
+  const resolved = resolveNameInScope(graph, scopeIndex, parentName, currentNodeId, source);
+  if (resolved.nodeId && !resolved.ambiguous) {
+    return resolved.nodeId;
+  }
+  return currentNodeId;
+}
+
+/**
+ * @param {Map<string, Map<string, string[]>>} scopeIndex
+ * @param {string} scopeNodeId
+ * @param {string} baseName
+ * @returns {string}
+ */
+function pickUniqueName(scopeIndex, scopeNodeId, baseName) {
+  const scopeMap = scopeIndex.get(scopeNodeId);
+  if (!scopeMap || !scopeMap.has(baseName)) {
+    return baseName;
+  }
+  let suffix = 2;
+  let candidate = `${baseName}-${suffix}`;
+  while (scopeMap.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseName}-${suffix}`;
+  }
+  return candidate;
+}
+
+/**
+ * @param {ReferenceDecl} decl
+ * @returns {string}
+ */
+function deriveReferenceName(decl) {
+  const title = normalizeTitleValue(decl.title?.raw);
+  if (title) {
+    return title;
+  }
+  if (decl.paths && decl.paths.length > 0) {
+    const rawPath = decl.paths[0];
+    const trimmed = rawPath.replace(/\/+$/, '');
+    const parts = trimmed.split('/').filter(Boolean);
+    if (parts.length > 0) {
+      const lastPart = parts[parts.length - 1];
+      const withoutExt = lastPart.replace(/\.[^/.]+$/, '');
+      return withoutExt.replace(/\./g, '-');
+    }
+  }
+  if (decl.url) {
+    try {
+      const parsed = new URL(decl.url);
+      const segments = parsed.pathname.split('/').filter(Boolean);
+      if (segments.length > 0) {
+        const lastSegment = segments[segments.length - 1];
+        const withoutExt = lastSegment.replace(/\.[^/.]+$/, '');
+        return withoutExt.replace(/\./g, '-');
+      }
+      if (parsed.hostname) {
+        return parsed.hostname.replace(/\./g, '-');
+      }
+    } catch {
+      // Ignore malformed URLs here; validation handles required fields
+    }
+  }
+  return 'reference';
+}
+
 /**
  * Creates a node ID
  * @param {string} universeName