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

package/src/parser.js

@@ -16,9 +16,8 @@ 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').ReferenceBlock} ReferenceBlock
- * @typedef {import('./ast.js').NamedReferenceBlock} NamedReferenceBlock
- * @typedef {import('./ast.js').UsingInReferencesBlock} UsingInReferencesBlock
+ * @typedef {import('./ast.js').RepositoryDecl} RepositoryDecl
+ * @typedef {import('./ast.js').ReferenceDecl} ReferenceDecl
  * @typedef {import('./ast.js').DocumentationBlock} DocumentationBlock
  * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
  * @typedef {import('./ast.js').NamedDocumentBlock} NamedDocumentBlock
@@ -106,7 +105,6 @@ class Parser {
   parseFile() {
     const universes = [];
     const scenes = [];
-    const topLevelDeclsByUniverse = new Map();
     const topLevelDeclsUnscoped = [];
     const startToken = this.peek();
 
@@ -128,18 +126,14 @@ class Parser {
           decl = this.parseConcept();
         } else if (keyword === 'anthology') {
           decl = this.parseAnthology();
+        } else if (keyword === 'repository') {
+          decl = this.parseRepository();
+        } else if (keyword === 'reference') {
+          decl = this.parseReferenceDecl();
         }
 
         if (decl) {
-          if (decl.parentName) {
-            const universeName = decl.parentName;
-            if (!topLevelDeclsByUniverse.has(universeName)) {
-              topLevelDeclsByUniverse.set(universeName, []);
-            }
-            topLevelDeclsByUniverse.get(universeName).push(decl);
-          } else {
-            topLevelDeclsUnscoped.push(decl);
-          }
+          topLevelDeclsUnscoped.push(decl);
         } else {
           // Skip unknown top-level content (tolerant parsing)
           const token = this.advance();
@@ -156,43 +150,16 @@ class Parser {
       }
     }
 
-    // Merge top-level declarations into their target universes
-    if (topLevelDeclsByUniverse.size > 0 || topLevelDeclsUnscoped.length > 0) {
-      const universesByName = new Map();
-      for (const universe of universes) {
-        universesByName.set(universe.name, universe);
-      }
-
-      for (const [universeName, decls] of topLevelDeclsByUniverse.entries()) {
-        const universe = universesByName.get(universeName);
-        if (universe) {
-          universe.body.push(...decls);
-        } else {
-          const firstDecl = decls[0];
-          const lastDecl = decls[decls.length - 1];
-          universes.push({
-            kind: 'universe',
-            name: universeName,
-            body: decls,
-            source: {
-              file: this.file,
-              start: firstDecl.source.start,
-              end: lastDecl.source.end,
-            },
-          });
-          universesByName.set(universeName, universes[universes.length - 1]);
-        }
-      }
-
-      if (topLevelDeclsUnscoped.length > 0 && universes.length === 1) {
-        universes[0].body.push(...topLevelDeclsUnscoped);
-      }
+    // Merge top-level declarations into their target universe
+    if (topLevelDeclsUnscoped.length > 0 && universes.length === 1) {
+      universes[0].body.push(...topLevelDeclsUnscoped);
     }
 
     return {
       file: this.file,
       universes,
       scenes,
+      topLevelDecls: topLevelDeclsUnscoped.length > 0 ? topLevelDeclsUnscoped : undefined,
       source: startToken
         ? {
             file: this.file,
@@ -210,7 +177,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']);
+    const body = this.parseBlockBody(['anthology', 'series', 'book', 'chapter', 'concept', 'relates', 'describe', 'title', 'repository', 'reference', 'references', 'documentation']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -227,7 +194,7 @@ class Parser {
 
   /**
    * @param {string[]} allowedKeywords - Keywords allowed in this body
-   * @returns {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | DocumentationBlock | NamedReferenceBlock | NamedDocumentBlock | UnknownBlock>}
+   * @returns {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>}
    */
   parseBlockBody(allowedKeywords) {
     const body = [];
@@ -238,21 +205,6 @@ class Parser {
         const keyword = this.peek()?.value;
         if (!keyword) break;
 
-        // Check for named reference: reference <IDENTIFIER> { ... }
-        if (keyword === 'reference') {
-          const nextPos = this.pos + 1;
-          if (nextPos < this.tokens.length && 
-              this.tokens[nextPos].type === 'IDENTIFIER' &&
-              nextPos + 1 < this.tokens.length &&
-              this.tokens[nextPos + 1].type === 'LBRACE') {
-            // This is a named reference block
-            body.push(this.parseNamedReference());
-            continue;
-          }
-          // Otherwise, it's an inline reference (only valid inside references block)
-          // Fall through to unknown block handling
-        }
-
         // Check for named document: document <IDENTIFIER> { ... }
         if (keyword === 'document') {
           const nextPos = this.pos + 1;
@@ -286,13 +238,15 @@ class Parser {
           body.push(this.parseTitle());
         } else if (keyword === 'repository' && allowedKeywords.includes('repository')) {
           body.push(this.parseRepository());
+        } else if (keyword === 'reference' && allowedKeywords.includes('reference')) {
+          body.push(this.parseReferenceDecl());
         } else if (keyword === 'from' && allowedKeywords.includes('from')) {
           body.push(this.parseFrom());
         } else if (keyword === 'relationships' && allowedKeywords.includes('relationships')) {
           body.push(this.parseRelationships());
-        } else if (keyword === 'references') {
+        } else if (keyword === 'references' && allowedKeywords.includes('references')) {
           body.push(this.parseReferences());
-        } else if (keyword === 'documentation') {
+        } else if (keyword === 'documentation' && allowedKeywords.includes('documentation')) {
           body.push(this.parseDocumentation());
         } else {
           // Unknown keyword/identifier followed by brace - parse as UnknownBlock
@@ -320,13 +274,32 @@ class Parser {
   parseAnthology() {
     const startToken = this.expect('KEYWORD', 'anthology');
     const nameToken = this.expect('IDENTIFIER');
+    let parentName = undefined;
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const parentToken = this.expect('IDENTIFIER');
+      parentName = parentToken.value;
+    }
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const body = this.parseBlockBody([
+      'describe',
+      'title',
+      'series',
+      'book',
+      'chapter',
+      'concept',
+      'relates',
+      'references',
+      'documentation',
+      'repository',
+      'reference',
+    ]);
     const rbrace = this.expect('RBRACE');
 
     return {
       kind: 'anthology',
       name: nameToken.value,
+      parentName,
       body,
       source: {
         file: this.file,
@@ -352,7 +325,7 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'documentation']);
+    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -374,16 +347,23 @@ class Parser {
   parseBook() {
     const startToken = this.expect('KEYWORD', 'book');
     const nameToken = this.expect('IDENTIFIER');
-    this.expect('KEYWORD', 'in');
-    const parentToken = this.expect('IDENTIFIER');
+    
+    // Optional "in <ParentName>" syntax
+    let parentName = undefined;
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const parentToken = this.expect('IDENTIFIER');
+      parentName = parentToken.value;
+    }
+    
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'documentation']);
+    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
       kind: 'book',
       name: nameToken.value,
-      parentName: parentToken.value,
+      parentName,
       body,
       source: {
         file: this.file,
@@ -399,10 +379,20 @@ class Parser {
   parseChapter() {
     const startToken = this.expect('KEYWORD', 'chapter');
     const nameToken = this.expect('IDENTIFIER');
+    
+    // Chapters must belong to a book - check for "in" keyword
+    if (!this.match('KEYWORD') || this.peek()?.value !== 'in') {
+      const nextToken = this.peek();
+      const line = nextToken ? nextToken.span.start.line : startToken.span.start.line;
+      throw new Error(
+        `Chapter "${nameToken.value}" must belong to a book. Use "chapter ${nameToken.value} in <BookName> { ... }" at ${this.file}:${line}`,
+      );
+    }
+    
     this.expect('KEYWORD', 'in');
     const parentToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -434,7 +424,7 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation', 'repository', 'reference']);
     const rbrace = this.expect('RBRACE');
 
     return {
@@ -652,193 +642,141 @@ class Parser {
   }
 
   /**
-   * Parses a references block containing nested reference blocks and using blocks
+   * Parses a references block containing a list of identifier paths
    * @returns {ReferencesBlock}
    */
   parseReferences() {
     const startToken = this.expect('IDENTIFIER', 'references');
     const lbrace = this.expect('LBRACE');
-    const references = [];
+    const items = [];
+    let depth = 1;
 
-    // Parse nested reference blocks and using blocks
-    while (!this.match('RBRACE') && !this.match('EOF')) {
-      // Check for 'using' keyword first (consistent with Scene layer)
-      if (this.match('KEYWORD') && this.peek()?.value === 'using') {
-        references.push(this.parseUsingInReferences());
-      } else if ((this.match('IDENTIFIER') || this.match('KEYWORD')) && this.peek()?.value === 'reference') {
-        // Look for 'reference' identifier
-        references.push(this.parseReference());
-      } else {
-        // Skip unexpected tokens (tolerant parsing)
+    while (this.pos < this.tokens.length && !this.match('EOF')) {
+      if (this.match('LBRACE')) {
+        throw new Error(`Unexpected '{' in references block at ${this.file}:${this.peek()?.span.start.line}. Use identifiers only.`);
+      }
+      if (this.match('LBRACE')) {
+        depth += 1;
         this.advance();
+        continue;
       }
-    }
-
-    const rbrace = this.expect('RBRACE');
-
-    return {
-      kind: 'references',
-      references,
-      source: {
-        file: this.file,
-        start: startToken.span.start,
-        end: rbrace.span.end,
-      },
-    };
-  }
 
-  /**
-   * Parses a using block inside a references block: using { IdentifierList }
-   * @returns {UsingInReferencesBlock}
-   */
-  parseUsingInReferences() {
-    const startToken = this.expect('KEYWORD', 'using');
-    const lbrace = this.expect('LBRACE');
-    const names = [];
-
-    while (!this.match('RBRACE') && !this.match('EOF')) {
-      if (this.match('IDENTIFIER')) {
-        names.push(this.expect('IDENTIFIER').value);
-        // Skip optional comma
-        if (this.match('COMMA')) {
-          this.expect('COMMA');
-        }
-      } else if (this.match('COMMA')) {
-        // Skip stray commas
-        this.expect('COMMA');
-      } else {
-        // Skip non-identifiers (tolerant parsing)
+      if (this.match('RBRACE')) {
+        depth -= 1;
         this.advance();
+        if (depth === 0) {
+          break;
+        }
+        continue;
       }
-    }
-
-    const rbrace = this.expect('RBRACE');
-
-    return {
-      kind: 'using-in-references',
-      names,
-      source: {
-        file: this.file,
-        start: startToken.span.start,
-        end: rbrace.span.end,
-      },
-    };
-  }
 
-  /**
-   * Parses a single reference block
-   * @returns {ReferenceBlock}
-   */
-  parseReference() {
-    const startToken = this.expect('IDENTIFIER', 'reference');
-    const lbrace = this.expect('LBRACE');
-    let repository = null;
-    let paths = [];
-    let describe = null;
-    let kind = null;
+      if (depth !== 1) {
+        this.advance();
+        continue;
+      }
 
-    // Parse repository, paths, optional kind, and optional describe
-    while (!this.match('RBRACE') && !this.match('EOF')) {
-      if (this.match('RBRACE')) break;
+      if (this.match('COMMA')) {
+        this.advance();
+        continue;
+      }
 
-      // Check for identifier or keyword (describe is a keyword)
       if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
-        const identifier = this.peek()?.value;
-        if (identifier === 'repository') {
-          repository = this.parseStringBlock('repository');
-        } else if (identifier === 'paths') {
-          paths = this.parsePathsBlock();
-        } else if (identifier === 'kind') {
-          kind = this.parseStringBlock('kind');
-        } else if (identifier === 'describe') {
-          describe = this.parseDescribe();
-        } else {
-          // Skip unknown identifier/keyword
-          this.advance();
+        const startToken = this.peek();
+        const name = this.parseIdentifierPath();
+        if (name && startToken) {
+          const lastToken = this.tokens[this.pos - 1] || startToken;
+          items.push({
+            name,
+            source: {
+              file: this.file,
+              start: startToken.span.start,
+              end: lastToken.span.end,
+            },
+          });
         }
-      } else {
-        // Skip unexpected tokens
-        this.advance();
+        continue;
       }
-    }
 
-    const rbrace = this.expect('RBRACE');
-
-    if (!repository) {
-      throw new Error(`Missing 'repository' field in reference block at ${this.file}:${startToken.span.start.line}`);
-    }
-    if (paths.length === 0) {
-      throw new Error(`Missing or empty 'paths' field in reference block at ${this.file}:${startToken.span.start.line}`);
+      this.advance();
     }
 
     return {
-      kind: 'reference',
-      repository,
-      paths,
-      referenceKind: kind,
-      describe,
+      kind: 'references',
+      items,
       source: {
         file: this.file,
         start: startToken.span.start,
-        end: rbrace.span.end,
+        end: this.tokens[this.pos - 1]?.span.end || lbrace.span.end,
       },
     };
   }
 
   /**
-   * Parses a named reference block: reference <Name> { ... }
-   * @returns {NamedReferenceBlock}
+   * Parses a reference declaration: reference <Name> [in <RepoName>] { ... }
+   * @returns {ReferenceDecl}
    */
-  parseNamedReference() {
-    const startToken = this.expect('IDENTIFIER', 'reference');
-    const nameToken = this.expect('IDENTIFIER');
+  parseReferenceDecl() {
+    const startToken = this.match('KEYWORD') ? this.expect('KEYWORD', 'reference') : this.expect('IDENTIFIER', 'reference');
+    let nameToken = null;
+    if (this.match('IDENTIFIER')) {
+      nameToken = this.expect('IDENTIFIER');
+    }
+    let repositoryName = null;
+
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const repoName = this.parseIdentifierPath();
+      if (!repoName) {
+        throw new Error(`Expected repository name after "in" at ${this.file}:${this.peek()?.span.start.line || '?'}`);
+      }
+      repositoryName = repoName;
+    }
+
     const lbrace = this.expect('LBRACE');
-    let repository = null;
-    let paths = [];
-    let describe = null;
+    let url = null;
+    let paths = null;
     let kind = null;
+    let describe = null;
+    let note = null;
+    let title = null;
 
-    // Parse repository, paths, optional kind, and optional describe (same as parseReference)
     while (!this.match('RBRACE') && !this.match('EOF')) {
       if (this.match('RBRACE')) break;
 
-      // Check for identifier or keyword (describe is a keyword)
       if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
         const identifier = this.peek()?.value;
-        if (identifier === 'repository') {
-          repository = this.parseStringBlock('repository');
+        if (identifier === 'url') {
+          url = this.parseStringBlock('url');
         } else if (identifier === 'paths') {
           paths = this.parsePathsBlock();
         } else if (identifier === 'kind') {
           kind = this.parseStringBlock('kind');
         } else if (identifier === 'describe') {
           describe = this.parseDescribe();
+        } else if (identifier === 'note') {
+          note = this.parseNote();
+        } else if (identifier === 'title') {
+          title = this.parseTitle();
         } else {
-          // Skip unknown identifier/keyword
           this.advance();
         }
       } else {
-        // Skip unexpected tokens
         this.advance();
       }
     }
 
     const rbrace = this.expect('RBRACE');
 
-    if (!repository) {
-      throw new Error(`Missing 'repository' field in named reference block at ${this.file}:${startToken.span.start.line}`);
-    }
-    if (paths.length === 0) {
-      throw new Error(`Missing or empty 'paths' field in named reference block at ${this.file}:${startToken.span.start.line}`);
-    }
-
     return {
-      kind: 'named-reference',
-      name: nameToken.value,
-      repository,
-      paths,
-      referenceKind: kind,
-      describe,
+      kind: 'reference',
+      name: nameToken ? nameToken.value : undefined,
+      repositoryName: repositoryName || undefined,
+      url: url || undefined,
+      paths: paths || undefined,
+      referenceKind: kind || undefined,
+      describe: describe || undefined,
+      note: note || undefined,
+      title: title || undefined,
       source: {
         file: this.file,
         start: startToken.span.start,
@@ -999,45 +937,58 @@ class Parser {
   }
 
   /**
-   * Parses a repository block: repository <Identifier> { kind { ... } options { ... } }
+   * Parses a repository block: repository <Identifier> { url { ... } ... }
    * @returns {RepositoryDecl}
    */
   parseRepository() {
     const startToken = this.expect('KEYWORD', 'repository');
     const nameToken = this.expect('IDENTIFIER');
+    let parentName = undefined;
+
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const containerName = this.parseIdentifierPath();
+      if (!containerName) {
+        throw new Error(`Expected container name after "in" at ${this.file}:${this.peek()?.span.start.line || '?'}`);
+      }
+      parentName = containerName;
+    }
     const lbrace = this.expect('LBRACE');
 
-    let kind = null;
-    let options = null;
+    let url = null;
+    let describe = null;
+    let note = null;
+    let title = null;
 
     while (!this.match('RBRACE') && !this.match('EOF')) {
       if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
         const identifier = this.peek()?.value;
-        if (identifier === 'kind') {
-          kind = this.parseValueBlock('kind');
-        } else if (identifier === 'options') {
-          options = this.parseOptionsBlock();
+        if (identifier === 'url') {
+          url = this.parseStringBlock('url');
+        } else if (identifier === 'describe') {
+          describe = this.parseDescribe();
+        } else if (identifier === 'note') {
+          note = this.parseNote();
+        } else if (identifier === 'title') {
+          title = this.parseTitle();
         } else {
-          // Skip unknown identifier/keyword
           this.advance();
         }
       } else {
-        // Skip unexpected tokens
         this.advance();
       }
     }
 
     const rbrace = this.expect('RBRACE');
 
-    if (!kind) {
-      throw new Error(`Missing 'kind' field in repository block at ${this.file}:${startToken.span.start.line}`);
-    }
-
     return {
       kind: 'repository',
       name: nameToken.value,
-      repositoryKind: kind,
-      options: options || {},
+      parentName,
+      url: url || undefined,
+      describe: describe || undefined,
+      note: note || undefined,
+      title: title || undefined,
       source: {
         file: this.file,
         start: startToken.span.start,
@@ -1046,6 +997,82 @@ class Parser {
     };
   }
 
+  /**
+   * Parses an identifier path (IDENTIFIER (DOT IDENTIFIER)*)
+   * @returns {string | null}
+   */
+  parseIdentifierPath() {
+    if (!this.match('IDENTIFIER') && !this.match('KEYWORD')) {
+      return null;
+    }
+
+    const parts = [];
+    parts.push(this.advance().value);
+
+    while (this.match('DOT')) {
+      this.expect('DOT');
+      if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+        parts.push(this.advance().value);
+      } else {
+        break;
+      }
+    }
+
+    return parts.join('.');
+  }
+
+  /**
+   * Parses a note block, same format as describe
+   * @returns {DescribeBlock}
+   */
+  parseNote() {
+    const startToken = this.expect('IDENTIFIER', 'note');
+    const lbrace = this.expect('LBRACE');
+
+    let depth = 1;
+    const startOffset = lbrace.span.end.offset;
+    let endOffset = startOffset;
+    let endToken = null;
+
+    while (depth > 0 && this.pos < this.tokens.length) {
+      const token = this.tokens[this.pos];
+      if (token.type === 'EOF') break;
+
+      if (token.type === 'LBRACE') {
+        depth++;
+        this.pos++;
+      } else if (token.type === 'RBRACE') {
+        depth--;
+        if (depth === 0) {
+          endToken = token;
+          endOffset = token.span.start.offset;
+          this.pos++;
+          break;
+        } else {
+          this.pos++;
+        }
+      } else {
+        this.pos++;
+      }
+    }
+
+    if (depth > 0) {
+      throw new Error(`Unclosed note block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'note',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
   /**
    * Parses a paths block (e.g., paths { 'path1', 'path2' })
    * @returns {string[]}