@sprig-and-prose/sprig-universe 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/sprig-universe",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "description": "Minimal universe parser for sprig",
   "main": "src/index.js",
@@ -27,4 +27,3 @@
     "typescript": "^5.7.2"
   }
 }
-

package/src/ast.js

@@ -43,6 +43,13 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} OrderingBlock
+ * @property {string} kind - Always 'ordering'
+ * @property {string[]} identifiers - Array of identifier names
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} DocumentBlock
  * @property {string} kind - Always 'document'
@@ -107,7 +114,7 @@
  * @typedef {Object} UniverseDecl
  * @property {string} kind - Always 'universe'
  * @property {string} name - Universe name
- * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -116,7 +123,7 @@
  * @property {string} kind - Always 'anthology'
  * @property {string} name - Anthology name
  * @property {string} [parentName] - Optional parent universe name (from "in UniverseName")
- * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -125,7 +132,7 @@
  * @property {string} kind - Always 'series'
  * @property {string} name - Series name
  * @property {string} [parentName] - Optional parent anthology name (from "in AnthologyName")
- * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -134,7 +141,7 @@
  * @property {string} kind - Always 'book'
  * @property {string} name - Book name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
- * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -143,7 +150,7 @@
  * @property {string} kind - Always 'chapter'
  * @property {string} name - Chapter name
  * @property {string} parentName - Parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -152,7 +159,7 @@
  * @property {string} kind - Always 'concept'
  * @property {string} name - Concept name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 

package/src/graph.js

@@ -27,6 +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').OrderingBlock} OrderingBlock
  * @typedef {import('./ast.js').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
  * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
@@ -294,6 +295,9 @@ export function buildGraph(fileASTs) {
   // Resolve container references (books/chapters) that may have forward references
   resolveContainers(graph, scopeIndex, pendingContainerResolutions);
 
+  // Validate and apply ordering blocks after all nodes and relationships are established
+  validateOrderingBlocks(graph);
+
   return graph;
 }
 
@@ -522,6 +526,9 @@ function processBody(
   pendingReferenceAttachments,
   pendingContainerResolutions,
 ) {
+  // Collect ordering blocks to process after all children are added
+  const orderingBlocks = [];
+  
   for (const decl of body) {
     if (decl.kind === 'anthology') {
       const nodeId = makeNodeId(universeName, 'anthology', decl.name);
@@ -952,6 +959,9 @@ function processBody(
           universeName,
         });
       }
+    } else if (decl.kind === 'ordering') {
+      // Collect ordering blocks to process after all children are added
+      orderingBlocks.push(decl);
     } else if (decl.kind === 'documentation') {
       // DocumentationBlock - attach to current node
       const currentNode = graph.nodes[currentNodeId];
@@ -1116,6 +1126,30 @@ function processBody(
       });
     }
   }
+
+  // Store ordering blocks for later validation (after all nodes are created)
+  // We'll validate them in a separate pass after the entire graph is built
+  // This is necessary because children may be defined outside their parent's body
+  // (e.g., "book X in Y" defined at anthology level, not inside series Y's body)
+  if (orderingBlocks.length > 0) {
+    const currentNode = graph.nodes[currentNodeId];
+    if (!currentNode) {
+      return;
+    }
+
+    // Validate: only one ordering block per container
+    if (orderingBlocks.length > 1) {
+      graph.diagnostics.push({
+        severity: 'warning',
+        message: `Multiple ordering blocks in ${currentNode.kind} "${currentNode.name}". Using the first one.`,
+        source: orderingBlocks[1].source,
+      });
+    }
+
+    // Store ordering block temporarily on the node for later validation
+    // We'll process this in validateOrderingBlocks() after all nodes are created
+    currentNode._pendingOrdering = orderingBlocks[0];
+  }
 }
 
 /**
@@ -1746,6 +1780,56 @@ function makeRelatesNodeId(universeName, a, b, index = 0) {
   return `${universeName}:relates:${a}:${b}:${index}`;
 }
 
+/**
+ * Validates and applies ordering blocks after all nodes and relationships are established
+ * This must run after all nodes are created because children may be defined outside their parent's body
+ * (e.g., "book X in Y" defined at anthology level, not inside series Y's body)
+ * @param {UniverseGraph} graph
+ */
+function validateOrderingBlocks(graph) {
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    if (!node._pendingOrdering) {
+      continue;
+    }
+
+    const orderingBlock = node._pendingOrdering;
+    const orderingIdentifiers = orderingBlock.identifiers;
+
+    // Build a map of child names to node IDs for validation
+    const childNameToNodeId = new Map();
+    for (const childId of node.children) {
+      const childNode = graph.nodes[childId];
+      if (childNode) {
+        childNameToNodeId.set(childNode.name, childId);
+      }
+    }
+
+    // Validate ordering identifiers against actual children
+    const validOrdering = [];
+    for (const identifier of orderingIdentifiers) {
+      if (childNameToNodeId.has(identifier)) {
+        validOrdering.push(identifier);
+      } else {
+        // Unknown identifier - emit gentle warning
+        graph.diagnostics.push({
+          severity: 'warning',
+          message: `Ordering block in ${node.kind} "${node.name}" references unknown child "${identifier}". This identifier will be ignored.`,
+          source: orderingBlock.source,
+        });
+      }
+    }
+
+    // Store ordering if there are any valid identifiers
+    if (validOrdering.length > 0) {
+      node.ordering = validOrdering;
+    }
+
+    // Clean up temporary field
+    delete node._pendingOrdering;
+  }
+}
+
 /**
  * Creates an edge ID
  * @param {string} universeName

package/src/ir.js

@@ -61,6 +61,7 @@
  * @property {NodeId} [parent] - Tree parent node ID
  * @property {NodeId[]} children - Child node IDs
  * @property {NodeId} [container] - Container node ID (for book/chapter "in" relationship; always set for book/chapter nodes when resolved)
+ * @property {string[]} [ordering] - Optional ordering of direct children by identifier name
  * @property {TextBlock} [describe] - Describe block if present
  * @property {UnknownBlock[]} [unknownBlocks] - Unknown blocks if any
  * @property {string[]} [references] - Reference IDs attached to this node

package/src/parser.js

@@ -16,6 +16,7 @@ import { mergeSpans } from './util/span.js';
  * @typedef {import('./ast.js').DescribeBlock} DescribeBlock
  * @typedef {import('./ast.js').UnknownBlock} UnknownBlock
  * @typedef {import('./ast.js').ReferencesBlock} ReferencesBlock
+ * @typedef {import('./ast.js').OrderingBlock} OrderingBlock
  * @typedef {import('./ast.js').RepositoryDecl} RepositoryDecl
  * @typedef {import('./ast.js').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
@@ -177,7 +178,7 @@ class Parser {
     const startToken = this.expect('KEYWORD', 'universe');
     const nameToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['anthology', 'series', 'book', 'chapter', 'concept', 'relates', 'describe', 'title', 'repository', 'reference', 'references', 'documentation']);
+    const body = this.parseBlockBody(['anthology', 'series', 'book', 'chapter', 'concept', 'relates', 'describe', 'title', 'repository', 'reference', 'references', 'ordering', 'documentation']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -246,6 +247,8 @@ class Parser {
           body.push(this.parseRelationships());
         } else if (keyword === 'references' && allowedKeywords.includes('references')) {
           body.push(this.parseReferences());
+        } else if (keyword === 'ordering' && allowedKeywords.includes('ordering')) {
+          body.push(this.parseOrdering());
         } else if (keyword === 'documentation' && allowedKeywords.includes('documentation')) {
           body.push(this.parseDocumentation());
         } else {
@@ -290,6 +293,7 @@ class Parser {
       'concept',
       'relates',
       'references',
+      'ordering',
       'documentation',
       'repository',
       'reference',
@@ -325,7 +329,7 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'documentation', 'repository', 'reference']);
+    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -357,7 +361,7 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'documentation', 'repository', 'reference']);
+    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -424,7 +428,7 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation', 'repository', 'reference']);
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -641,6 +645,62 @@ class Parser {
     };
   }
 
+  /**
+   * Parses an ordering block containing a list of identifiers
+   * @returns {OrderingBlock}
+   */
+  parseOrdering() {
+    const startToken = this.match('KEYWORD') ? this.expect('KEYWORD', 'ordering') : this.expect('IDENTIFIER', 'ordering');
+    const lbrace = this.expect('LBRACE');
+    const identifiers = [];
+    let depth = 1;
+
+    while (this.pos < this.tokens.length && !this.match('EOF')) {
+      if (this.match('LBRACE')) {
+        throw new Error(`Unexpected '{' in ordering block at ${this.file}:${this.peek()?.span.start.line}. Use identifiers only.`);
+      }
+
+      if (this.match('RBRACE')) {
+        depth -= 1;
+        this.advance();
+        if (depth === 0) {
+          break;
+        }
+        continue;
+      }
+
+      if (depth !== 1) {
+        this.advance();
+        continue;
+      }
+
+      if (this.match('COMMA')) {
+        this.advance();
+        continue;
+      }
+
+      if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+        const identifierToken = this.advance();
+        if (identifierToken) {
+          identifiers.push(identifierToken.value);
+        }
+        continue;
+      }
+
+      this.advance();
+    }
+
+    return {
+      kind: 'ordering',
+      identifiers,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: this.tokens[this.pos - 1]?.span.end || lbrace.span.end,
+      },
+    };
+  }
+
   /**
    * Parses a references block containing a list of identifier paths
    * @returns {ReferencesBlock}