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

package/src/universe/graph.js

@@ -920,6 +920,90 @@ function getRawText(contentSpan, sourceText) {
   return sourceText.slice(contentSpan.startOffset, contentSpan.endOffset);
 }
 
+/**
+ * @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 {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 {{ title?: string, paths?: string[], urls?: string[] }} ref
+ * @returns {string}
+ */
+function deriveReferenceName(ref) {
+  if (ref.title) {
+    return ref.title;
+  }
+  if (ref.paths && ref.paths.length > 0) {
+    const rawPath = ref.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 (ref.urls && ref.urls.length > 0) {
+    try {
+      const parsed = new URL(ref.urls[0]);
+      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';
+}
+
+/**
+ * @param {Map<string, true>} nameMap
+ * @param {string} baseName
+ * @returns {string}
+ */
+function pickUniqueInlineReferenceName(nameMap, baseName) {
+  if (!nameMap.has(baseName)) {
+    nameMap.set(baseName, true);
+    return baseName;
+  }
+  let suffix = 2;
+  let candidate = `${baseName}-${suffix}`;
+  while (nameMap.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseName}-${suffix}`;
+  }
+  nameMap.set(candidate, true);
+  return candidate;
+}
+
 /**
  * Pass 4: Build nodes
  * @param {BoundDecl[]} boundDecls
@@ -927,11 +1011,12 @@ function getRawText(contentSpan, sourceText) {
  * @param {Array<{ sourceText: string, filePath: string }>} fileData
  * @returns {{ nodes: Map<DeclId, NodeModel>, repositories: Map<DeclId, RepositoryModel>, references: Map<DeclId, ReferenceModel>, diagnostics: Diagnostic[] }}
  */
-function buildNodes(boundDecls, schemas, fileData) {
+function buildNodes(boundDecls, schemas, fileData, universeName) {
   const nodes = new Map();
   const repositories = new Map();
   const references = new Map();
   const diagnostics = [];
+  const inlineReferenceNamesByScope = new Map();
   
   // Build file data map
   const fileDataMap = new Map();
@@ -954,6 +1039,47 @@ function buildNodes(boundDecls, schemas, fileData) {
       source: block.span,
     };
   }
+
+  /**
+   * @param {any} block
+   * @param {string} sourceText
+   * @returns {ReferenceModel}
+   */
+  function buildReferenceFromBlock(block, sourceText) {
+    const ref = {
+      id: '',
+      name: '',
+      urls: [],
+      source: block.source || block.span,
+    };
+
+    if (block.repositoryName) {
+      ref.repositoryName = block.repositoryName;
+    }
+
+    const children = block.children || [];
+    for (const child of children) {
+      if (child.kind === 'url' && child.value) {
+        ref.urls = [child.value];
+      } else if (child.kind === 'paths' && child.paths) {
+        ref.paths = child.paths;
+      } else if (child.kind === 'kind' && child.value) {
+        ref.kind = child.value;
+      } else if (child.kind === 'title') {
+        const raw = getRawText(child.contentSpan, sourceText);
+        const titleValue = normalizeTitleValue(raw);
+        if (titleValue) {
+          ref.title = titleValue;
+        }
+      } else if (child.kind === 'describe') {
+        ref.describe = buildTextBlock(child, sourceText);
+      } else if (child.kind === 'note') {
+        ref.note = buildTextBlock(child, sourceText);
+      }
+    }
+
+    return ref;
+  }
   
   for (const bound of boundDecls) {
     const { id, info, decl } = bound;
@@ -1078,7 +1204,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 +1216,49 @@ 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 inline reference blocks and attach directly
+      const inlineReferenceBlocks = (decl.body || []).filter(b => b.kind === 'reference' && b.children);
+      if (inlineReferenceBlocks.length > 0) {
+        const nameMap = inlineReferenceNamesByScope.get(id) || new Map();
+        inlineReferenceNamesByScope.set(id, nameMap);
+        for (const block of inlineReferenceBlocks) {
+          const refModel = buildReferenceFromBlock(block, sourceText);
+          const baseName = deriveReferenceName(refModel);
+          const uniqueName = pickUniqueInlineReferenceName(nameMap, baseName);
+          const refId = makeDeclId(universeName, 'reference', `${id}:${uniqueName}`);
+          refModel.id = refId;
+          refModel.name = uniqueName;
+          refModel.scopeDeclId = id;
+          references.set(refId, refModel);
+          if (!node.references) {
+            node.references = [];
+          }
+          node.references.push(refId);
+        }
+      }
+
+      // 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 +1334,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');
@@ -1194,6 +1362,8 @@ function buildNodes(boundDecls, schemas, fileData) {
       if (noteBlock) {
         ref.note = buildTextBlock(noteBlock, sourceText);
       }
+
+      ref.scopeDeclId = info.parentDeclId || id;
       
       references.set(id, ref);
     }
@@ -1202,6 +1372,292 @@ 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 ref of references.values()) {
+    const scopeDeclId = ref.scopeDeclId || ref.id;
+    const source = ref.source;
+    const displayName = ref.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,
+      });
+    }
+
+    if (!hasUrl && repositoryName) {
+      const pathSegments = repositoryName.split('.');
+      if (pathSegments.length === 1) {
+        const resolved = resolveUnqualified(pathSegments[0], scopeDeclId, index, parentMap, source);
+        if (resolved.ambiguous) {
+          diagnostics.push({
+            severity: 'error',
+            message: `Ambiguous repository "${repositoryName}" - use qualified path`,
+            source,
+          });
+        } 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,
+            });
+          } else if (!repo.url) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Repository "${repo.name}" is missing url { '...' }`,
+              source,
+            });
+          } 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,
+              });
+            } else {
+              urls = [repo.url];
+            }
+          }
+        } else {
+          const entry = unknownRepoCounts.get(repositoryName) || {
+            count: 0,
+            source,
+          };
+          entry.count += 1;
+          if (!entry.source && source) {
+            entry.source = source;
+          }
+          unknownRepoCounts.set(repositoryName, entry);
+        }
+      } else {
+        const resolved = resolveQualified(pathSegments, index, source);
+        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,
+            });
+          } else if (!repo.url) {
+            diagnostics.push({
+              severity: 'error',
+              message: `Repository "${repo.name}" is missing url { '...' }`,
+              source,
+            });
+          } 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,
+              });
+            } else {
+              urls = [repo.url];
+            }
+          }
+        } else {
+          const entry = unknownRepoCounts.get(repositoryName) || {
+            count: 0,
+            source,
+          };
+          entry.count += 1;
+          if (!entry.source && source) {
+            entry.source = source;
+          }
+          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,
+      });
+    }
+
+    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 = [];
+    const existingReferences = Array.isArray(node.references) ? node.references : [];
+
+    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);
+      }
+    }
+
+    const combined = [...existingReferences, ...resolvedReferences];
+    node.references = Array.from(new Set(combined));
+    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
@@ -1466,7 +1922,20 @@ 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);
+  const { nodes, repositories, references, diagnostics: nodeDiags } = buildNodes(
+    boundDecls,
+    schemas,
+    fileData,
+    universeName,
+  );
+
+  // 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 +1952,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',
 ]);