@sprig-and-prose/sprig-universe 0.1.1 → 0.3.0

package/src/ir.js

@@ -63,7 +63,7 @@
  * @property {NodeId} [container] - Container node ID (for book/chapter "in" relationship; always set for book/chapter nodes when resolved)
  * @property {TextBlock} [describe] - Describe block if present
  * @property {UnknownBlock[]} [unknownBlocks] - Unknown blocks if any
- * @property {Array<{repository: string, paths: string[], kind?: string, describe?: TextBlock, source: SourceSpan}>} [references] - References if any
+ * @property {string[]} [references] - Reference IDs attached to this node
  * @property {Array<{title?: string, kind: string, path: string, describe?: TextBlock, source: SourceSpan}>} [documentation] - Documentation if any
  * @property {SourceSpan} source - Source span
  * @property {NodeId[]} [endpoints] - Endpoint node IDs (for relates nodes)
@@ -88,12 +88,27 @@
  */
 
 /**
- * @typedef {Object} NamedReferenceModel
+ * @typedef {Object} RepositoryModel
+ * @property {string} id - Repository ID (qualified)
+ * @property {string} name - Repository name
+ * @property {string} url - Base URL
+ * @property {TextBlock} [describe] - Optional describe block
+ * @property {TextBlock} [note] - Optional note block
+ * @property {string} [title] - Optional title
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} ReferenceModel
+ * @property {string} id - Reference ID (qualified)
  * @property {string} name - Reference name
- * @property {string} repository - Repository name
- * @property {string[]} paths - Array of path strings
  * @property {string} [kind] - Optional reference kind
+ * @property {string} [title] - Optional title
  * @property {TextBlock} [describe] - Optional describe block
+ * @property {TextBlock} [note] - Optional note block
+ * @property {string[]} urls - Computed URLs
+ * @property {string} [repositoryRef] - Repository ID if reference uses a repository
+ * @property {string[]} [paths] - Raw paths (if provided)
  * @property {SourceSpan} source - Source span
  */
 
@@ -113,9 +128,9 @@
  * @property {Record<NodeId, NodeModel>} nodes - Nodes keyed by ID
  * @property {Record<EdgeId, EdgeModel>} edges - Edges keyed by ID
  * @property {Diagnostic[]} diagnostics - Diagnostics
- * @property {Record<string, any>} [repositories] - Repository configurations (from config)
+ * @property {Record<string, RepositoryModel>} [repositories] - Repositories by ID
+ * @property {Record<string, ReferenceModel>} [references] - References by ID
  * @property {string} [generatedAt] - ISO timestamp when manifest was generated
- * @property {Record<string, Record<string, NamedReferenceModel>>} [referencesByName] - Named references by universe name, then by reference name
  * @property {Record<string, Record<string, NamedDocumentModel>>} [documentsByName] - Named documents by universe name, then by document name
  */
 

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,6 +105,7 @@ class Parser {
   parseFile() {
     const universes = [];
     const scenes = [];
+    const topLevelDeclsUnscoped = [];
     const startToken = this.peek();
 
     while (!this.match('EOF')) {
@@ -113,6 +113,34 @@ class Parser {
         universes.push(this.parseUniverse());
       } else if (this.match('KEYWORD') && this.peek()?.value === 'scene') {
         scenes.push(this.parseScene());
+      } else if (this.match('KEYWORD')) {
+        const keyword = this.peek()?.value;
+        let decl = null;
+        if (keyword === 'series') {
+          decl = this.parseSeries();
+        } else if (keyword === 'book') {
+          decl = this.parseBook();
+        } else if (keyword === 'chapter') {
+          decl = this.parseChapter();
+        } else if (keyword === 'concept') {
+          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) {
+          topLevelDeclsUnscoped.push(decl);
+        } else {
+          // Skip unknown top-level content (tolerant parsing)
+          const token = this.advance();
+          if (token && token.type !== 'EOF') {
+            // Could emit warning here, but for now just skip
+          }
+        }
       } else {
         // Skip unknown top-level content (tolerant parsing)
         const token = this.advance();
@@ -122,10 +150,16 @@ class Parser {
       }
     }
 
+    // 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,
@@ -143,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 {
@@ -160,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 = [];
@@ -171,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;
@@ -219,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
@@ -253,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,
@@ -285,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 {
@@ -310,7 +350,7 @@ class Parser {
     this.expect('KEYWORD', 'in');
     const parentToken = this.expect('IDENTIFIER');
     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 {
@@ -335,7 +375,7 @@ class Parser {
     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 {
@@ -367,7 +407,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 {
@@ -585,193 +625,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,
@@ -932,45 +920,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,
@@ -979,6 +980,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[]}