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

package/src/parser.js

@@ -4,6 +4,19 @@
 
 import { mergeSpans } from './util/span.js';
 
+const DECLARATION_KINDS = new Set([
+  'universe',
+  'anthology',
+  'series',
+  'book',
+  'chapter',
+  'concept',
+  'relates',
+  'relationship',
+  'repository',
+  'reference',
+]);
+
 /**
  * @typedef {import('./ast.js').FileAST} FileAST
  * @typedef {import('./ast.js').UniverseDecl} UniverseDecl
@@ -13,6 +26,7 @@ import { mergeSpans } from './util/span.js';
  * @typedef {import('./ast.js').ChapterDecl} ChapterDecl
  * @typedef {import('./ast.js').ConceptDecl} ConceptDecl
  * @typedef {import('./ast.js').RelatesDecl} RelatesDecl
+ * @typedef {import('./ast.js').RelationshipDecl} RelationshipDecl
  * @typedef {import('./ast.js').DescribeBlock} DescribeBlock
  * @typedef {import('./ast.js').UnknownBlock} UnknownBlock
  * @typedef {import('./ast.js').ReferencesBlock} ReferencesBlock
@@ -48,6 +62,10 @@ class Parser {
     this.file = file;
     this.sourceText = sourceText;
     this.pos = 0;
+    this.aliasScopes = [new Map()];
+    this.aliasDeclarations = [];
+    this.relationshipScopes = [new Map()];
+    this.relationshipDeclarations = [];
   }
 
   /**
@@ -100,6 +118,205 @@ class Parser {
     return token;
   }
 
+  /**
+   * @param {string} [value]
+   * @returns {Token}
+   * @throws {Error}
+   */
+  expectIdentifierOrKeyword(value) {
+    const token = this.advance();
+    if (!token || (token.type !== 'KEYWORD' && token.type !== 'IDENTIFIER')) {
+      throw new Error(
+        `Expected identifier or keyword, got ${token ? token.type : 'EOF'} at ${this.file}:${token ? token.span.start.line : '?'}`,
+      );
+    }
+    if (value !== undefined && token.value !== value) {
+      throw new Error(
+        `Expected identifier or keyword "${value}", got "${token.value}" at ${this.file}:${token.span.start.line}`,
+      );
+    }
+    return token;
+  }
+
+  /**
+   * @param {string} value
+   * @returns {Token}
+   * @throws {Error}
+   */
+  expectKindToken(value) {
+    return this.expectIdentifierOrKeyword(value);
+  }
+
+  pushAliasScope() {
+    const parent = this.aliasScopes[this.aliasScopes.length - 1] || new Map();
+    this.aliasScopes.push(new Map(parent));
+    this.aliasDeclarations.push(new Map());
+  }
+
+  /**
+   * @returns {Map<string, string>}
+   */
+  popAliasScope() {
+    this.aliasScopes.pop();
+    return this.aliasDeclarations.pop() || new Map();
+  }
+
+  /**
+   * @returns {Map<string, string>}
+   */
+  currentAliasMap() {
+    return this.aliasScopes[this.aliasScopes.length - 1] || new Map();
+  }
+
+  pushRelationshipScope() {
+    const parent = this.relationshipScopes[this.relationshipScopes.length - 1] || new Map();
+    this.relationshipScopes.push(new Map(parent));
+    this.relationshipDeclarations.push(new Map());
+  }
+
+  /**
+   * @returns {Map<string, RelationshipDecl>}
+   */
+  popRelationshipScope() {
+    this.relationshipScopes.pop();
+    return this.relationshipDeclarations.pop() || new Map();
+  }
+
+  /**
+   * @returns {Map<string, RelationshipDecl>}
+   */
+  currentRelationshipMap() {
+    return this.relationshipScopes[this.relationshipScopes.length - 1] || new Map();
+  }
+
+  /**
+   * @param {RelationshipDecl} relationshipDecl
+   */
+  declareRelationship(relationshipDecl) {
+    const declaredMap = this.relationshipDeclarations[this.relationshipDeclarations.length - 1];
+    if (!declaredMap) {
+      throw new Error(
+        `Relationship must be declared inside a container at ${this.file}:${relationshipDecl.source.start.line}`,
+      );
+    }
+
+    // Get identifiers to check for duplicates
+    const identifiers = [];
+    if (relationshipDecl.type === 'symmetric' && relationshipDecl.id) {
+      identifiers.push(relationshipDecl.id);
+    } else if (relationshipDecl.type === 'paired') {
+      if (relationshipDecl.leftId) identifiers.push(relationshipDecl.leftId);
+      if (relationshipDecl.rightId) identifiers.push(relationshipDecl.rightId);
+    }
+
+    for (const id of identifiers) {
+      if (declaredMap.has(id)) {
+        throw new Error(
+          `Duplicate relationship identifier "${id}" in this scope at ${this.file}:${relationshipDecl.source.start.line}`,
+        );
+      }
+      const relationshipMap = this.currentRelationshipMap();
+      relationshipMap.set(id, relationshipDecl);
+      declaredMap.set(id, relationshipDecl);
+    }
+  }
+
+  /**
+   * @param {Token} nameToken
+   * @param {Token} targetToken
+   */
+  declareAlias(nameToken, targetToken) {
+    const aliasName = nameToken.value;
+    const targetKind = targetToken.value;
+    const declaredMap = this.aliasDeclarations[this.aliasDeclarations.length - 1];
+    if (!declaredMap) {
+      throw new Error(
+        `Alias "${aliasName}" must be declared inside a container at ${this.file}:${nameToken.span.start.line}`,
+      );
+    }
+    if (DECLARATION_KINDS.has(aliasName)) {
+      throw new Error(
+        `Alias "${aliasName}" conflicts with built-in kind "${aliasName}" at ${this.file}:${nameToken.span.start.line}`,
+      );
+    }
+    if (!DECLARATION_KINDS.has(targetKind)) {
+      throw new Error(
+        `Unknown alias target kind "${targetKind}" at ${this.file}:${targetToken.span.start.line}`,
+      );
+    }
+    if (declaredMap.has(aliasName)) {
+      throw new Error(
+        `Duplicate alias "${aliasName}" in this scope at ${this.file}:${nameToken.span.start.line}`,
+      );
+    }
+    const aliasMap = this.currentAliasMap();
+    aliasMap.set(aliasName, targetKind);
+    declaredMap.set(aliasName, targetKind);
+  }
+
+  parseAliasStatement() {
+    this.expectIdentifierOrKeyword('alias');
+    const nameToken = this.expectIdentifierOrKeyword();
+    this.expect('LBRACE');
+    const targetToken = this.expectIdentifierOrKeyword();
+    this.expect('RBRACE');
+    this.declareAlias(nameToken, targetToken);
+  }
+
+  parseAliasesBlock() {
+    this.expectIdentifierOrKeyword('aliases');
+    this.expect('LBRACE');
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (!this.match('IDENTIFIER') && !this.match('KEYWORD')) {
+        const token = this.peek();
+        throw new Error(
+          `Expected alias name in aliases block at ${this.file}:${token ? token.span.start.line : '?'}`,
+        );
+      }
+      const nameToken = this.expectIdentifierOrKeyword();
+      this.expect('LBRACE');
+      const targetToken = this.expectIdentifierOrKeyword();
+      this.expect('RBRACE');
+      this.declareAlias(nameToken, targetToken);
+    }
+    this.expect('RBRACE');
+  }
+
+  /**
+   * @param {string} resolvedKind
+   * @param {string} spelledKind
+   */
+  parseDeclarationByKind(resolvedKind, spelledKind) {
+    if (resolvedKind === 'anthology') {
+      return this.parseAnthology(spelledKind);
+    }
+    if (resolvedKind === 'series') {
+      return this.parseSeries(spelledKind);
+    }
+    if (resolvedKind === 'book') {
+      return this.parseBook(spelledKind);
+    }
+    if (resolvedKind === 'chapter') {
+      return this.parseChapter(spelledKind);
+    }
+    if (resolvedKind === 'concept') {
+      return this.parseConcept(spelledKind);
+    }
+    if (resolvedKind === 'relates') {
+      return this.parseRelates(spelledKind);
+    }
+    if (resolvedKind === 'repository') {
+      return this.parseRepository(spelledKind);
+    }
+    if (resolvedKind === 'reference') {
+      return this.parseReferenceDecl(spelledKind);
+    }
+    if (resolvedKind === 'relationship') {
+      return this.parseRelationship(spelledKind);
+    }
+    return null;
+  }
+
   /**
    * @returns {FileAST}
    */
@@ -174,16 +391,40 @@ class Parser {
   /**
    * @returns {UniverseDecl}
    */
-  parseUniverse() {
-    const startToken = this.expect('KEYWORD', 'universe');
+  parseUniverse(spelledKind = 'universe') {
+    const startToken = this.expectKindToken(spelledKind);
     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', 'ordering', 'documentation']);
+    this.pushAliasScope();
+    this.pushRelationshipScope();
+    const body = this.parseBlockBody(
+      [
+        'anthology',
+        'series',
+        'book',
+        'chapter',
+        'concept',
+        'relates',
+        'relationship',
+        'describe',
+        'title',
+        'repository',
+        'reference',
+        'references',
+        'ordering',
+        'documentation',
+      ],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
+    const relationships = this.popRelationshipScope();
 
     return {
       kind: 'universe',
+      spelledKind,
       name: nameToken.value,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -195,10 +436,12 @@ class Parser {
 
   /**
    * @param {string[]} allowedKeywords - Keywords allowed in this body
+   * @param {{ allowAliases?: boolean }} [options]
    * @returns {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>}
    */
-  parseBlockBody(allowedKeywords) {
+  parseBlockBody(allowedKeywords, options = {}) {
     const body = [];
+    const allowAliases = options.allowAliases === true;
 
     while (!this.match('RBRACE') && !this.match('EOF')) {
       // Check for keywords or identifiers that might start a block
@@ -206,6 +449,15 @@ class Parser {
         const keyword = this.peek()?.value;
         if (!keyword) break;
 
+        if (allowAliases && keyword === 'alias') {
+          this.parseAliasStatement();
+          continue;
+        }
+        if (allowAliases && keyword === 'aliases') {
+          this.parseAliasesBlock();
+          continue;
+        }
+
         // Check for named document: document <IDENTIFIER> { ... }
         if (keyword === 'document') {
           const nextPos = this.pos + 1;
@@ -221,19 +473,16 @@ class Parser {
           // Fall through to unknown block handling
         }
 
-        if (keyword === 'anthology' && allowedKeywords.includes('anthology')) {
-          body.push(this.parseAnthology());
-        } else if (keyword === 'series' && allowedKeywords.includes('series')) {
-          body.push(this.parseSeries());
-        } else if (keyword === 'book' && allowedKeywords.includes('book')) {
-          body.push(this.parseBook());
-        } else if (keyword === 'chapter' && allowedKeywords.includes('chapter')) {
-          body.push(this.parseChapter());
-        } else if (keyword === 'concept' && allowedKeywords.includes('concept')) {
-          body.push(this.parseConcept());
-        } else if (keyword === 'relates' && allowedKeywords.includes('relates')) {
-          body.push(this.parseRelates());
-        } else if (keyword === 'describe' && allowedKeywords.includes('describe')) {
+        const resolvedKind = this.currentAliasMap().get(keyword) || keyword;
+        if (allowedKeywords.includes(resolvedKind)) {
+          const decl = this.parseDeclarationByKind(resolvedKind, keyword);
+          if (decl) {
+            body.push(decl);
+            continue;
+          }
+        }
+
+        if (keyword === 'describe' && allowedKeywords.includes('describe')) {
           body.push(this.parseDescribe());
         } else if (keyword === 'title' && allowedKeywords.includes('title')) {
           body.push(this.parseTitle());
@@ -274,8 +523,8 @@ class Parser {
   /**
    * @returns {AnthologyDecl}
    */
-  parseAnthology() {
-    const startToken = this.expect('KEYWORD', 'anthology');
+  parseAnthology(spelledKind = 'anthology') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     let parentName = undefined;
     if (this.match('KEYWORD') && this.peek()?.value === 'in') {
@@ -284,26 +533,37 @@ class Parser {
       parentName = parentToken.value;
     }
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody([
-      'describe',
-      'title',
-      'series',
-      'book',
-      'chapter',
-      'concept',
-      'relates',
-      'references',
-      'ordering',
-      'documentation',
-      'repository',
-      'reference',
-    ]);
+    this.pushAliasScope();
+    this.pushRelationshipScope();
+    const body = this.parseBlockBody(
+      [
+        'describe',
+        'title',
+        'series',
+        'book',
+        'chapter',
+        'concept',
+        'relationship',
+        'relates',
+        'relationship',
+        'references',
+        'ordering',
+        'documentation',
+        'repository',
+        'reference',
+      ],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
+    const relationships = this.popRelationshipScope();
 
     return {
       kind: 'anthology',
+      spelledKind,
       name: nameToken.value,
       parentName,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -316,8 +576,8 @@ class Parser {
   /**
    * @returns {SeriesDecl}
    */
-  parseSeries() {
-    const startToken = this.expect('KEYWORD', 'series');
+  parseSeries(spelledKind = 'series') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     
     // Optional "in <AnthologyName>" syntax
@@ -329,13 +589,20 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
+    this.pushAliasScope();
+    const body = this.parseBlockBody(
+      ['book', 'chapter', 'concept', 'describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference'],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
 
     return {
       kind: 'series',
+      spelledKind,
       name: nameToken.value,
       parentName,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -348,8 +615,8 @@ class Parser {
   /**
    * @returns {BookDecl}
    */
-  parseBook() {
-    const startToken = this.expect('KEYWORD', 'book');
+  parseBook(spelledKind = 'book') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     
     // Optional "in <ParentName>" syntax
@@ -361,13 +628,20 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
+    this.pushAliasScope();
+    const body = this.parseBlockBody(
+      ['series', 'chapter', 'concept', 'describe', 'title', 'relationships', 'references', 'ordering', 'documentation', 'repository', 'reference'],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
 
     return {
       kind: 'book',
+      spelledKind,
       name: nameToken.value,
       parentName,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -380,8 +654,8 @@ class Parser {
   /**
    * @returns {ChapterDecl}
    */
-  parseChapter() {
-    const startToken = this.expect('KEYWORD', 'chapter');
+  parseChapter(spelledKind = 'chapter') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     
     // Chapters must belong to a book - check for "in" keyword
@@ -396,13 +670,20 @@ class Parser {
     this.expect('KEYWORD', 'in');
     const parentToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation', 'repository', 'reference']);
+    this.pushAliasScope();
+    const body = this.parseBlockBody(
+      ['concept', 'describe', 'title', 'references', 'relationships', 'documentation', 'repository', 'reference'],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
 
     return {
       kind: 'chapter',
+      spelledKind,
       name: nameToken.value,
       parentName: parentToken.value,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -415,8 +696,8 @@ class Parser {
   /**
    * @returns {ConceptDecl}
    */
-  parseConcept() {
-    const startToken = this.expect('KEYWORD', 'concept');
+  parseConcept(spelledKind = 'concept') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     
     // Optional "in <ParentName>" syntax
@@ -428,13 +709,20 @@ class Parser {
     }
     
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'references', 'ordering', 'documentation', 'repository', 'reference']);
+    this.pushAliasScope();
+    const body = this.parseBlockBody(
+      ['describe', 'title', 'references', 'relationships', 'ordering', 'documentation', 'repository', 'reference'],
+      { allowAliases: true },
+    );
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
 
     return {
       kind: 'concept',
+      spelledKind,
       name: nameToken.value,
       parentName,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -447,19 +735,23 @@ class Parser {
   /**
    * @returns {RelatesDecl}
    */
-  parseRelates() {
-    const startToken = this.expect('KEYWORD', 'relates');
+  parseRelates(spelledKind = 'relates') {
+    const startToken = this.expectKindToken(spelledKind);
     const aToken = this.expect('IDENTIFIER');
     this.expect('KEYWORD', 'and');
     const bToken = this.expect('IDENTIFIER');
     const lbrace = this.expect('LBRACE');
-    const body = this.parseBlockBody(['describe', 'title', 'from', 'relationships']);
+    this.pushAliasScope();
+    const body = this.parseBlockBody(['describe', 'title', 'from', 'relationships'], { allowAliases: true });
     const rbrace = this.expect('RBRACE');
+    const aliases = this.popAliasScope();
 
     return {
       kind: 'relates',
+      spelledKind,
       a: aToken.value,
       b: bToken.value,
+      aliases: aliases.size > 0 ? Object.fromEntries(aliases) : undefined,
       body,
       source: {
         file: this.file,
@@ -469,6 +761,191 @@ class Parser {
     };
   }
 
+  /**
+   * Parses a relationship declaration (symmetric or paired)
+   * @returns {RelationshipDecl}
+   */
+  parseRelationship(spelledKind = 'relationship') {
+    const startToken = this.expectKindToken(spelledKind);
+    const firstIdToken = this.expectIdentifierOrKeyword();
+    
+    // Check if this is paired (has "and" after first identifier)
+    if (this.match('KEYWORD') && this.peek()?.value === 'and') {
+      // Paired relationship: relationship <leftId> and <rightId> { ... }
+      return this.parseRelationshipPaired(startToken, firstIdToken, spelledKind);
+    } else {
+      // Symmetric relationship: relationship <id> { ... }
+      return this.parseRelationshipSymmetric(startToken, firstIdToken, spelledKind);
+    }
+  }
+
+  /**
+   * Parses a symmetric relationship declaration
+   * @param {Token} startToken
+   * @param {Token} idToken
+   * @param {string} spelledKind
+   * @returns {RelationshipDecl}
+   */
+  parseRelationshipSymmetric(startToken, idToken, spelledKind) {
+    const lbrace = this.expect('LBRACE');
+    let describe = null;
+    let label = null;
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+        const keyword = this.peek()?.value;
+        if (keyword === 'describe') {
+          if (describe !== null) {
+            throw new Error(
+              `Multiple describe blocks in relationship "${idToken.value}" at ${this.file}:${startToken.span.start.line}`,
+            );
+          }
+          describe = this.parseDescribe();
+        } else if (keyword === 'label') {
+          if (label !== null) {
+            throw new Error(
+              `Multiple label blocks in relationship "${idToken.value}" at ${this.file}:${startToken.span.start.line}`,
+            );
+          }
+          label = this.parseStringBlock('label');
+        } else {
+          this.advance();
+        }
+      } else {
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    const relationshipDecl = {
+      kind: 'relationship',
+      spelledKind,
+      type: 'symmetric',
+      id: idToken.value,
+      describe: describe || undefined,
+      label: label || undefined,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+
+    // Declare the relationship in current scope
+    this.declareRelationship(relationshipDecl);
+
+    return relationshipDecl;
+  }
+
+  /**
+   * Parses a paired (directional) relationship declaration
+   * @param {Token} startToken
+   * @param {Token} leftIdToken
+   * @param {string} spelledKind
+   * @returns {RelationshipDecl}
+   */
+  parseRelationshipPaired(startToken, leftIdToken, spelledKind) {
+    this.expect('KEYWORD', 'and');
+    const rightIdToken = this.expectIdentifierOrKeyword();
+    const lbrace = this.expect('LBRACE');
+
+    let pairDescribe = null;
+    const fromBlocks = {};
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+        const keyword = this.peek()?.value;
+        if (keyword === 'describe') {
+          if (pairDescribe !== null) {
+            throw new Error(
+              `Multiple describe blocks in relationship "${leftIdToken.value} and ${rightIdToken.value}" at ${this.file}:${startToken.span.start.line}`,
+            );
+          }
+          pairDescribe = this.parseDescribe();
+        } else if (keyword === 'from') {
+          const fromStartToken = this.advance();
+          const endpointToken = this.expect('IDENTIFIER');
+          
+          // Validate: from block must reference leftId or rightId
+          if (endpointToken.value !== leftIdToken.value && endpointToken.value !== rightIdToken.value) {
+            throw new Error(
+              `from block references "${endpointToken.value}" which is not declared in relationship "${leftIdToken.value} and ${rightIdToken.value}" at ${this.file}:${endpointToken.span.start.line}`,
+            );
+          }
+          
+          const fromLbrace = this.expect('LBRACE');
+          let fromLabel = null;
+          let fromDescribe = null;
+          
+          // Parse from block body (label and describe)
+          while (!this.match('RBRACE') && !this.match('EOF')) {
+            if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+              const fromKeyword = this.peek()?.value;
+              if (fromKeyword === 'label') {
+                if (fromLabel !== null) {
+                  throw new Error(
+                    `Multiple label blocks in from "${endpointToken.value}" at ${this.file}:${endpointToken.span.start.line}`,
+                  );
+                }
+                fromLabel = this.parseStringBlock('label');
+              } else if (fromKeyword === 'describe') {
+                if (fromDescribe !== null) {
+                  throw new Error(
+                    `Multiple describe blocks in from "${endpointToken.value}" at ${this.file}:${endpointToken.span.start.line}`,
+                  );
+                }
+                fromDescribe = this.parseDescribe();
+              } else {
+                this.advance();
+              }
+            } else {
+              this.advance();
+            }
+          }
+          
+          const fromRbrace = this.expect('RBRACE');
+          
+          const fromSide = {};
+          if (fromLabel !== null) {
+            fromSide.label = fromLabel;
+          }
+          if (fromDescribe !== null) {
+            fromSide.describe = fromDescribe;
+          }
+          
+          fromBlocks[endpointToken.value] = fromSide;
+        } else {
+          this.advance();
+        }
+      } else {
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    const relationshipDecl = {
+      kind: 'relationship',
+      spelledKind,
+      type: 'paired',
+      leftId: leftIdToken.value,
+      rightId: rightIdToken.value,
+      describe: pairDescribe || undefined,
+      from: Object.keys(fromBlocks).length > 0 ? fromBlocks : undefined,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+
+    // Declare the relationship in current scope (both identifiers)
+    this.declareRelationship(relationshipDecl);
+
+    return relationshipDecl;
+  }
+
   /**
    * @returns {FromBlock}
    */
@@ -492,11 +969,54 @@ class Parser {
   }
 
   /**
+   * Parses a relationships block
+   * Supports both legacy syntax (string literals for relates blocks) and new syntax (relationship IDs + targets)
    * @returns {RelationshipsBlock}
    */
   parseRelationships() {
     const startToken = this.expect('KEYWORD', 'relationships');
     const lbrace = this.expect('LBRACE');
+    const startOffset = lbrace.span.end.offset;
+    
+    // Try to detect which syntax we're using
+    // If first token after brace is a STRING, use legacy syntax
+    // Otherwise, use new syntax (relationship ID + targets)
+    
+    // Peek ahead to see what comes next
+    let peekPos = this.pos;
+    let foundString = false;
+    let foundIdentifier = false;
+    
+    while (peekPos < this.tokens.length && peekPos < this.pos + 10) {
+      const token = this.tokens[peekPos];
+      if (token.type === 'RBRACE' || token.type === 'EOF') break;
+      if (token.type === 'STRING') {
+        foundString = true;
+        break;
+      }
+      if (token.type === 'IDENTIFIER' || token.type === 'KEYWORD') {
+        foundIdentifier = true;
+        break;
+      }
+      peekPos++;
+    }
+
+    // If we found a string first, use legacy syntax (for relates blocks)
+    if (foundString && !foundIdentifier) {
+      return this.parseRelationshipsLegacy(startToken, lbrace);
+    }
+
+    // Otherwise, use new syntax (relationship ID + targets)
+    return this.parseRelationshipsNew(startToken, lbrace);
+  }
+
+  /**
+   * Parses legacy relationships block (string literals for relates blocks)
+   * @param {Token} startToken
+   * @param {Token} lbrace
+   * @returns {RelationshipsBlock}
+   */
+  parseRelationshipsLegacy(startToken, lbrace) {
     const values = [];
     let relationshipsSource = {
       file: this.file,
@@ -530,6 +1050,89 @@ class Parser {
     };
   }
 
+  /**
+   * Parses new relationships block syntax (relationship ID + target identifiers)
+   * @param {Token} startToken
+   * @param {Token} lbrace
+   * @returns {RelationshipsBlock}
+   */
+  parseRelationshipsNew(startToken, lbrace) {
+    const entries = [];
+    let relationshipsSource = {
+      file: this.file,
+      start: lbrace.span.end,
+      end: lbrace.span.end,
+    };
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      // Parse relationship ID (identifier or keyword)
+      if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+        const relationshipIdToken = this.advance();
+        const relationshipId = relationshipIdToken.value;
+        
+        // Expect opening brace for targets
+        if (!this.match('LBRACE')) {
+          throw new Error(
+            `Expected '{' after relationship identifier "${relationshipId}" at ${this.file}:${relationshipIdToken.span.start.line}`,
+          );
+        }
+        const targetLbrace = this.advance();
+        
+        const targets = [];
+        
+        // Parse targets until closing brace
+        while (!this.match('RBRACE') && !this.match('EOF')) {
+          if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+            const targetIdToken = this.advance();
+            const targetId = targetIdToken.value;
+            
+            // Check if this target has a metadata block
+            let metadata = null;
+            if (this.match('LBRACE')) {
+              // Parse metadata block (describe)
+              const metadataLbrace = this.advance();
+              const metadataBody = this.parseBlockBody(['describe'], {});
+              const metadataRbrace = this.expect('RBRACE');
+              
+              const describeBlock = metadataBody.find((b) => b.kind === 'describe');
+              if (describeBlock) {
+                metadata = describeBlock;
+              }
+            }
+            
+            targets.push({
+              id: targetId,
+              metadata: metadata || undefined,
+            });
+          } else {
+            // Skip other tokens
+            this.advance();
+          }
+        }
+        
+        const targetRbrace = this.expect('RBRACE');
+        relationshipsSource.end = targetRbrace.span.end;
+        
+        entries.push({
+          relationshipId,
+          targets,
+        });
+      } else {
+        // Skip other tokens
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+    relationshipsSource.end = rbrace.span.start;
+
+    return {
+      kind: 'relationships',
+      entries,
+      source: relationshipsSource,
+    };
+  }
+
   /**
    * Parses a describe block, consuming raw text until matching closing brace
    * Treats braces inside as plain text (doesn't parse nested structures)
@@ -775,8 +1378,8 @@ class Parser {
    * Parses a reference declaration: reference <Name> [in <RepoName>] { ... }
    * @returns {ReferenceDecl}
    */
-  parseReferenceDecl() {
-    const startToken = this.match('KEYWORD') ? this.expect('KEYWORD', 'reference') : this.expect('IDENTIFIER', 'reference');
+  parseReferenceDecl(spelledKind = 'reference') {
+    const startToken = this.expectKindToken(spelledKind);
     let nameToken = null;
     if (this.match('IDENTIFIER')) {
       nameToken = this.expect('IDENTIFIER');
@@ -1000,8 +1603,8 @@ class Parser {
    * Parses a repository block: repository <Identifier> { url { ... } ... }
    * @returns {RepositoryDecl}
    */
-  parseRepository() {
-    const startToken = this.expect('KEYWORD', 'repository');
+  parseRepository(spelledKind = 'repository') {
+    const startToken = this.expectKindToken(spelledKind);
     const nameToken = this.expect('IDENTIFIER');
     let parentName = undefined;