@sprig-and-prose/sprig-universe 0.4.3 → 0.4.4

package/src/universe/graph.js

@@ -920,6 +920,21 @@ function getRawText(contentSpan, sourceText) {
   return sourceText.slice(contentSpan.startOffset, contentSpan.endOffset);
 }
 
+/**
+ * @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;
+}
+
 /**
  * Pass 4: Build nodes
  * @param {BoundDecl[]} boundDecls
@@ -1078,7 +1093,7 @@ function buildNodes(boundDecls, schemas, fileData) {
       // Extract unknown blocks (non-container, non-standard blocks)
       const unknownBlocks = (decl.body || []).filter(b => {
         if (!b.kind) return false;
-        const knownKinds = ['describe', 'title', 'note', 'relationships', 'from', 'references', 'reference'];
+        const knownKinds = ['describe', 'title', 'note', 'relationships', 'from', 'references', 'reference', 'ordering'];
         return !knownKinds.includes(b.kind);
       });
       if (unknownBlocks.length > 0) {
@@ -1090,13 +1105,28 @@ function buildNodes(boundDecls, schemas, fileData) {
         }));
       }
       
-      // Extract references block
+      // Extract references block (resolved after all nodes are built)
       const referencesBlock = (decl.body || []).find(b => b.kind === 'references');
       if (referencesBlock && referencesBlock.items) {
-        node.references = referencesBlock.items.map(item => {
-          // Will be resolved in Pass 5
-          return item.ref || item.name || '';
-        });
+        node._pendingReferences = referencesBlock.items
+          .map(item => ({
+            name: item.ref || item.name || '',
+            source: item.span || referencesBlock.source,
+          }))
+          .filter(item => item.name);
+      }
+
+      // Extract ordering block (applied after all nodes are built)
+      const orderingBlocks = (decl.body || []).filter(b => b.kind === 'ordering');
+      if (orderingBlocks.length > 0) {
+        if (orderingBlocks.length > 1) {
+          diagnostics.push({
+            severity: 'warning',
+            message: `Multiple ordering blocks in ${node.kind} "${node.name}". Using the first one.`,
+            source: orderingBlocks[1].source || orderingBlocks[0].source,
+          });
+        }
+        node._pendingOrdering = orderingBlocks[0];
       }
       
       nodes.set(id, node);
@@ -1172,6 +1202,12 @@ function buildNodes(boundDecls, schemas, fileData) {
       if (pathsBlock && pathsBlock.paths) {
         ref.paths = pathsBlock.paths;
       }
+
+      // Extract kind block
+      const kindBlock = (decl.body || []).find(b => b.kind === 'kind');
+      if (kindBlock && kindBlock.value) {
+        ref.kind = kindBlock.value;
+      }
       
       // Extract title block
       const titleBlock = (decl.body || []).find(b => b.kind === 'title');
@@ -1202,6 +1238,293 @@ function buildNodes(boundDecls, schemas, fileData) {
   return { nodes, repositories, references, diagnostics };
 }
 
+/**
+ * Attach named references declared inside containers to their parent nodes.
+ * @param {BoundDecl[]} boundDecls
+ * @param {Map<DeclId, NodeModel>} nodes
+ */
+function addImplicitReferenceAttachments(boundDecls, nodes) {
+  for (const bound of boundDecls) {
+    const { info } = bound;
+    if (info.kindResolved !== 'reference') continue;
+    const parentId = info.parentDeclId;
+    if (!parentId) continue;
+    const parentNode = nodes.get(parentId);
+    if (!parentNode || parentNode.kind === 'universe') continue;
+    if (!parentNode._pendingReferences) {
+      parentNode._pendingReferences = [];
+    }
+    parentNode._pendingReferences.push({
+      name: info.name,
+      source: info.span,
+    });
+  }
+}
+
+/**
+ * Resolve reference declarations to repository URLs and repository references.
+ * @param {BoundDecl[]} boundDecls
+ * @param {Map<DeclId, ReferenceModel>} references
+ * @param {Map<DeclId, RepositoryModel>} repositories
+ * @param {DeclIndex} index
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @returns {Diagnostic[]}
+ */
+function resolveReferenceModels(boundDecls, references, repositories, index, parentMap) {
+  const diagnostics = [];
+  const unknownRepoCounts = new Map();
+
+  for (const bound of boundDecls) {
+    const { id, info } = bound;
+    if (info.kindResolved !== 'reference') continue;
+    const ref = references.get(id);
+    if (!ref) continue;
+
+    const displayName = ref.name || info.name || 'unnamed reference';
+    const hasUrl = Array.isArray(ref.urls) && ref.urls.length > 0;
+    const repositoryName = ref.repositoryName;
+    let urls = hasUrl ? [...ref.urls] : [];
+    let repositoryRef = undefined;
+
+    if (hasUrl && repositoryName) {
+      diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" cannot include both url { ... } and in <Repository>`,
+        source: info.span,
+      });
+    }
+
+    if (!hasUrl && repositoryName) {
+      const pathSegments = repositoryName.split('.');
+      if (pathSegments.length === 1) {
+        const resolved = resolveUnqualified(pathSegments[0], id, index, parentMap, info.span);
+        if (resolved.ambiguous) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous repository "${repositoryName}" - use qualified path`,
+            source: info.span,
+          });
+        } else if (resolved.declId) {
+          const repo = repositories.get(resolved.declId);
+          if (!repo) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Reference "${displayName}" uses "${repositoryName}" which is not a repository`,
+              source: info.span,
+            });
+          } else if (!repo.url) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Repository "${repo.name}" is missing url { '...' }`,
+              source: info.span,
+            });
+          } else {
+            repositoryRef = repo.id;
+            if (ref.paths && ref.paths.length > 0) {
+              urls = ref.paths.map((path) => joinRepositoryUrl(repo.url, path));
+            } else if (ref.paths && ref.paths.length === 0) {
+              diagnostics.push({
+                severity: 'error',
+                message: `Reference "${displayName}" has an empty paths block`,
+                source: info.span,
+              });
+            } else {
+              urls = [repo.url];
+            }
+          }
+        } else {
+          const entry = unknownRepoCounts.get(repositoryName) || {
+            count: 0,
+            source: info.span,
+          };
+          entry.count += 1;
+          if (!entry.source && info.span) {
+            entry.source = info.span;
+          }
+          unknownRepoCounts.set(repositoryName, entry);
+        }
+      } else {
+        const resolved = resolveQualified(pathSegments, index, info.span);
+        if (resolved.declId) {
+          const repo = repositories.get(resolved.declId);
+          if (!repo) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Reference "${displayName}" uses "${repositoryName}" which is not a repository`,
+              source: info.span,
+            });
+          } else if (!repo.url) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Repository "${repo.name}" is missing url { '...' }`,
+              source: info.span,
+            });
+          } else {
+            repositoryRef = repo.id;
+            if (ref.paths && ref.paths.length > 0) {
+              urls = ref.paths.map((path) => joinRepositoryUrl(repo.url, path));
+            } else if (ref.paths && ref.paths.length === 0) {
+              diagnostics.push({
+                severity: 'error',
+                message: `Reference "${displayName}" has an empty paths block`,
+                source: info.span,
+              });
+            } else {
+              urls = [repo.url];
+            }
+          }
+        } else {
+          const entry = unknownRepoCounts.get(repositoryName) || {
+            count: 0,
+            source: info.span,
+          };
+          entry.count += 1;
+          if (!entry.source && info.span) {
+            entry.source = info.span;
+          }
+          unknownRepoCounts.set(repositoryName, entry);
+        }
+      }
+    }
+
+    if (!hasUrl && !repositoryName) {
+      diagnostics.push({
+        severity: 'error',
+        message: `Reference "${displayName}" must have url { ... } or declared as reference ${displayName} in <Repository>`,
+        source: info.span,
+      });
+    }
+
+    if (urls.length > 0) {
+      ref.urls = urls;
+    }
+    if (repositoryRef) {
+      ref.repositoryRef = repositoryRef;
+    }
+  }
+
+  for (const [repoName, info] of unknownRepoCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    diagnostics.push({
+      severity: 'error',
+      message: `Unknown repository "${repoName}" used by references${countText}.`,
+      source: info.source,
+    });
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Resolve references blocks to reference IDs.
+ * @param {Map<DeclId, NodeModel>} nodes
+ * @param {Map<DeclId, ReferenceModel>} references
+ * @param {DeclIndex} index
+ * @param {Map<DeclId, DeclId>} parentMap
+ * @returns {Diagnostic[]}
+ */
+function resolveReferenceAttachments(nodes, references, index, parentMap) {
+  const diagnostics = [];
+  const unknownReferenceCounts = new Map();
+
+  for (const node of nodes.values()) {
+    if (!node._pendingReferences) continue;
+    const resolvedReferences = [];
+
+    for (const item of node._pendingReferences) {
+      const name = item.name;
+      if (!name) continue;
+
+      let resolvedDeclId = null;
+      const pathSegments = name.split('.');
+      if (pathSegments.length === 1) {
+        const resolved = resolveUnqualified(pathSegments[0], node.id, index, parentMap, item.source);
+        if (resolved.ambiguous) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous reference "${name}" - use qualified path`,
+            source: item.source,
+          });
+          continue;
+        }
+        resolvedDeclId = resolved.declId;
+      } else {
+        const resolved = resolveQualified(pathSegments, index, item.source);
+        resolvedDeclId = resolved.declId;
+      }
+
+      if (resolvedDeclId && references.has(resolvedDeclId)) {
+        resolvedReferences.push(resolvedDeclId);
+      } else {
+        const entry = unknownReferenceCounts.get(name) || { count: 0, source: item.source };
+        entry.count += 1;
+        if (!entry.source && item.source) {
+          entry.source = item.source;
+        }
+        unknownReferenceCounts.set(name, entry);
+      }
+    }
+
+    node.references = resolvedReferences;
+    delete node._pendingReferences;
+  }
+
+  for (const [name, info] of unknownReferenceCounts.entries()) {
+    const countText = info.count > 1 ? ` (${info.count} occurrences)` : '';
+    diagnostics.push({
+      severity: 'error',
+      message: `Unknown reference "${name}" in references list${countText}. References must use reference names, not paths.`,
+      source: info.source,
+    });
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Validate and apply ordering blocks after all nodes are created.
+ * @param {Map<DeclId, NodeModel>} nodes
+ * @returns {Diagnostic[]}
+ */
+function applyOrderingBlocks(nodes) {
+  const diagnostics = [];
+
+  for (const node of nodes.values()) {
+    if (!node._pendingOrdering) continue;
+    const orderingBlock = node._pendingOrdering;
+    const orderingIdentifiers = orderingBlock.identifiers || [];
+
+    const childNameToNodeId = new Map();
+    for (const childId of node.children || []) {
+      const childNode = nodes.get(childId);
+      if (childNode) {
+        childNameToNodeId.set(childNode.name, childId);
+      }
+    }
+
+    const validOrdering = [];
+    for (const identifier of orderingIdentifiers) {
+      if (childNameToNodeId.has(identifier)) {
+        validOrdering.push(identifier);
+      } else {
+        diagnostics.push({
+          severity: 'warning',
+          message: `Ordering block in ${node.kind} "${node.name}" references unknown child "${identifier}". This identifier will be ignored.`,
+          source: orderingBlock.source,
+        });
+      }
+    }
+
+    if (validOrdering.length > 0) {
+      node.ordering = validOrdering;
+    }
+
+    delete node._pendingOrdering;
+  }
+
+  return diagnostics;
+}
+
 /**
  * Pass 5: Build edges from relationship usage
  * @param {BoundDecl[]} boundDecls
@@ -1467,6 +1790,14 @@ export function buildGraph(fileAstOrFileAsts, options) {
   // Pass 4: Build nodes
   const fileData = normalized.map(n => ({ sourceText: n.sourceText, filePath: n.filePath }));
   const { nodes, repositories, references, diagnostics: nodeDiags } = buildNodes(boundDecls, schemas, fileData);
+
+  // Resolve reference models and attachments
+  addImplicitReferenceAttachments(boundDecls, nodes);
+  const referenceModelDiags = resolveReferenceModels(boundDecls, references, repositories, index, parentMap);
+  const referenceAttachmentDiags = resolveReferenceAttachments(nodes, references, index, parentMap);
+
+  // Apply ordering blocks after all nodes are available
+  const orderingDiags = applyOrderingBlocks(nodes);
   
   // Resolve relates endpoints
   const relatesDiags = resolveRelatesEndpoints(nodes, index, parentMap, boundDecls);
@@ -1483,6 +1814,9 @@ export function buildGraph(fileAstOrFileAsts, options) {
     ...bindDiags,
     ...schemaDiags,
     ...nodeDiags,
+    ...referenceModelDiags,
+    ...referenceAttachmentDiags,
+    ...orderingDiags,
     ...relatesDiags,
     ...edgeDiags,
   ];

package/src/universe/parser.js

@@ -342,6 +342,7 @@ const blockParselets = new Map([
   ['label', (p) => p.parseLabelBlock()],
   ['reference', (p) => p.parseReferenceBlock()],
   ['references', (p) => p.parseReferencesBlock()],
+  ['ordering', (p) => p.parseOrderingBlock()],
   ['relationships', (p) => p.parseRelationshipsBlock()],
 ]);
 
@@ -1074,6 +1075,54 @@ ParserCore.prototype.parseReferenceBlock = function () {
   };
 };
 
+/**
+ * Parses an ordering block: ordering { <identifiers> }
+ * Items are identifiers (not paths).
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseOrderingBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: orderingToken } = this.expectIdentifierOrKeyword('ordering');
+  if (!orderingToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const identifiers = [];
+
+  // Parse items until closing brace
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    // Skip optional commas
+    if (this.match('COMMA')) {
+      this.advance();
+      continue;
+    }
+
+    const itemToken = this.peek();
+    if (!itemToken) break;
+
+    const identifier = this.readIdent();
+    if (!identifier) {
+      this.reportDiagnostic('error', 'Expected identifier in ordering block', itemToken.span);
+      this.advance();
+      continue;
+    }
+
+    identifiers.push(identifier);
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'ordering',
+    identifiers,
+    source: this.createSpan(orderingToken, rbrace),
+  };
+};
+
 /**
  * Parses a references block: references { <items> }
  * Items are identifier paths (reference names)

package/src/universe/scanner.js

@@ -37,6 +37,7 @@ const KEYWORDS = new Set([
   'title',
   'reference',
   'references',
+  'ordering',
   'paths',
   'url',
 ]);

package/src/universe/universe.prose

@@ -67,14 +67,16 @@ anthology AnthologyWithRelationships in CanonicalUniverse {
         A chapter can still be nested under an aliased book.
       }
 
-      owns {
-        ExternalOtherChapter,
-        ExternalBook,
-      }
+      relationships {
+        owns {
+          ExternalOtherChapter,
+          ExternalBook,
+        }
 
-      singleton {
-        ExternalAnthology
-        ExternalSeries
+        singleton {
+          ExternalAnthology
+          ExternalSeries
+        }
       }
     }
 
@@ -104,21 +106,21 @@ anthology AnthologyWithRelationships in CanonicalUniverse {
   }
 
   reference NamedReference1 {
-    url { 'https://github.com/owner/repository/tree/main' }
+    url { 'https://github.com/owner/repository/tree/main/references/reference1.md' }
     describe {
       References can have describe blocks.
     }
   }
 
   reference NamedReference2 {
-    url { 'https://github.com/owner/repository/tree/main' }
+    url { 'https://github.com/owner/repository/tree/main/references/reference2.md' }
     describe {
       References can have describe blocks.
     }
   }
 
   reference NamedReferenceInRepository in InternalRepository {
-    url { 'https://github.com/owner/repository/tree/main' }
+    paths { 'path/to/file1.md' 'path/to/file2.md' }
   }
 
   concept ConceptWithDirectReference {
@@ -150,6 +152,11 @@ anthology ExternalAnthology in CanonicalUniverse {
 
   bookAlias BookAlias {
     chapterAlias NestedChapterAlias { }
+
+    ordering {
+      NestedChapterAlias
+      ExternalChapterAlias
+    }
   }
 
   chapterAlias ExternalChapterAlias in BookAlias { }