@sprig-and-prose/sprig-universe 0.4.1 → 0.4.2

package/src/universe/parser.js

@@ -0,0 +1,1751 @@
+/**
+ * @fileoverview Declarative parselet-based parser for Sprig universe syntax
+ * Syntax-only parsing with no semantic validation
+ */
+
+/**
+ * @typedef {import('../ast.js').UniverseDecl} UniverseDecl
+ * @typedef {import('../ast.js').AnthologyDecl} AnthologyDecl
+ * @typedef {import('../ast.js').SeriesDecl} SeriesDecl
+ * @typedef {import('../ast.js').BookDecl} BookDecl
+ * @typedef {import('../ast.js').ChapterDecl} ChapterDecl
+ * @typedef {import('../ast.js').ConceptDecl} ConceptDecl
+ * @typedef {import('../ast.js').RelatesDecl} RelatesDecl
+ * @typedef {import('./scanner.js').Token} Token
+ * @typedef {import('../ir.js').Diagnostic} Diagnostic
+ * @typedef {import('../ast.js').SourceSpan} SourceSpan
+ */
+
+/**
+ * @typedef {Object} FileAST
+ * @property {string} kind - Always 'file'
+ * @property {any[]} decls - Top-level declarations
+ * @property {SourceSpan} [source] - File-level source span
+ */
+
+/**
+ * @typedef {Object} DescribeBlock
+ * @property {string} kind - Always 'describe'
+ * @property {{ startOffset: number, endOffset: number }} contentSpan - Content span (inside braces)
+ * @property {SourceSpan} span - Full span including braces
+ */
+
+/**
+ * @typedef {Object} TitleBlock
+ * @property {string} kind - Always 'title'
+ * @property {{ startOffset: number, endOffset: number }} contentSpan - Content span (inside braces)
+ * @property {SourceSpan} span - Full span including braces
+ */
+
+/**
+ * @typedef {Object} NoteBlock
+ * @property {string} kind - Always 'note'
+ * @property {{ startOffset: number, endOffset: number }} contentSpan - Content span (inside braces)
+ * @property {SourceSpan} span - Full span including braces
+ */
+
+/**
+ * @typedef {Object} RelUseBlock
+ * @property {string} kind - Always 'relUse'
+ * @property {string} name - Relationship identifier
+ * @property {RelItem[]} items - List of relationship items
+ * @property {SourceSpan} span - Source span
+ */
+
+/**
+ * @typedef {Object} RelItem
+ * @property {string} kind - 'ref' or 'string'
+ * @property {string} [ref] - Reference path (dot-separated identifiers) for 'ref' items
+ * @property {string} [value] - String value for 'string' items
+ * @property {any[]} [body] - Optional inline body (for 'ref' items)
+ * @property {SourceSpan} span - Source span
+ */
+
+/**
+ * @typedef {Object} RelationshipDecl
+ * @property {string} kind - Always 'relationshipDecl'
+ * @property {string[]} ids - Relationship identifier(s) [id1, id2?]
+ * @property {any[]} body - Body declarations
+ * @property {SourceSpan} span - Source span
+ */
+
+/**
+ * Core parser class with low-level token navigation utilities
+ */
+class ParserCore {
+  /**
+   * @param {Token[]} tokens
+   * @param {string} filePath
+   * @param {string} sourceText
+   */
+  constructor(tokens, filePath, sourceText) {
+    this.tokens = tokens;
+    this.filePath = filePath;
+    this.sourceText = sourceText;
+    this.index = 0;
+    this.diagnostics = [];
+  }
+
+  /**
+   * @returns {Token | null}
+   */
+  peek() {
+    if (this.index >= this.tokens.length) {
+      return null;
+    }
+    return this.tokens[this.index];
+  }
+
+  /**
+   * @returns {Token | null}
+   */
+  previous() {
+    if (this.index === 0) {
+      return null;
+    }
+    return this.tokens[this.index - 1];
+  }
+
+  /**
+   * @returns {Token | null}
+   */
+  advance() {
+    if (this.index >= this.tokens.length) {
+      return null;
+    }
+    return this.tokens[this.index++];
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  isAtEnd() {
+    const token = this.peek();
+    return token === null || token.type === 'EOF';
+  }
+
+  /**
+   * @param {string} type
+   * @param {string} [value]
+   * @returns {boolean}
+   */
+  match(type, value) {
+    const token = this.peek();
+    if (!token || token.type !== type) {
+      return false;
+    }
+    if (value !== undefined && token.value !== value) {
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * @param {string} type
+   * @param {string} [value]
+   * @returns {{ token: Token | null, diagnostic: Diagnostic | null }}
+   */
+  expect(type, value) {
+    const token = this.peek();
+    if (!token || token.type !== type) {
+      const diagnostic = {
+        severity: 'error',
+        message: `Expected ${type}${value !== undefined ? ` with value "${value}"` : ''}, got ${token ? token.type : 'EOF'}`,
+        source: token ? token.span : undefined,
+      };
+      this.diagnostics.push(diagnostic);
+      return { token: null, diagnostic };
+    }
+    if (value !== undefined && token.value !== value) {
+      const diagnostic = {
+        severity: 'error',
+        message: `Expected ${type} with value "${value}", got "${token.value}"`,
+        source: token.span,
+      };
+      this.diagnostics.push(diagnostic);
+      return { token: null, diagnostic };
+    }
+    // Success: advance and return token
+    this.advance();
+    return { token, diagnostic: null };
+  }
+
+  /**
+   * @param {string} [value]
+   * @returns {{ token: Token | null, diagnostic: Diagnostic | null }}
+   */
+  expectIdentifierOrKeyword(value) {
+    const token = this.peek();
+    if (!token || (token.type !== 'KEYWORD' && token.type !== 'IDENTIFIER')) {
+      const diagnostic = {
+        severity: 'error',
+        message: `Expected identifier or keyword${value !== undefined ? ` "${value}"` : ''}, got ${token ? token.type : 'EOF'}`,
+        source: token ? token.span : undefined,
+      };
+      this.diagnostics.push(diagnostic);
+      return { token: null, diagnostic };
+    }
+    if (value !== undefined && token.value !== value) {
+      const diagnostic = {
+        severity: 'error',
+        message: `Expected identifier or keyword "${value}", got "${token.value}"`,
+        source: token.span,
+      };
+      this.diagnostics.push(diagnostic);
+      return { token: null, diagnostic };
+    }
+    // Success: advance and return token
+    this.advance();
+    return { token, diagnostic: null };
+  }
+
+  /**
+   * @param {string} value
+   * @returns {{ token: Token | null, diagnostic: Diagnostic | null }}
+   */
+  expectKindToken(value) {
+    return this.expectIdentifierOrKeyword(value);
+  }
+
+  /**
+   * Reads an identifier name (IDENTIFIER or KEYWORD)
+   * @returns {string | null}
+   */
+  readIdent() {
+    const token = this.peek();
+    if (!token || (token.type !== 'IDENTIFIER' && token.type !== 'KEYWORD')) {
+      return null;
+    }
+    this.advance();
+    return token.value;
+  }
+
+  /**
+   * Consumes an identifier, reporting diagnostic if missing
+   * @returns {string | null}
+   */
+  consumeIdentifier() {
+    const { token, diagnostic } = this.expectIdentifierOrKeyword();
+    return token ? token.value : null;
+  }
+
+  /**
+   * Parses an identifier path (IDENTIFIER (DOT IDENTIFIER)*)
+   * @returns {string | null}
+   */
+  parseIdentifierPath() {
+    if (!this.match('IDENTIFIER') && !this.match('KEYWORD')) {
+      return null;
+    }
+
+    const parts = [];
+    const firstToken = this.advance();
+    if (firstToken) {
+      parts.push(firstToken.value);
+    }
+
+    while (this.match('DOT')) {
+      this.advance(); // consume DOT
+      if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+        const partToken = this.advance();
+        if (partToken) {
+          parts.push(partToken.value);
+        }
+      } else {
+        break;
+      }
+    }
+
+    return parts.join('.');
+  }
+
+  /**
+   * Reports a diagnostic
+   * @param {'error' | 'warning'} severity
+   * @param {string} message
+   * @param {SourceSpan} [span]
+   */
+  reportDiagnostic(severity, message, span) {
+    this.diagnostics.push({
+      severity,
+      message,
+      source: span,
+    });
+  }
+
+  /**
+   * Creates a span from start and end tokens
+   * @param {Token} startToken
+   * @param {Token} endToken
+   * @returns {SourceSpan}
+   */
+  createSpan(startToken, endToken) {
+    return {
+      file: this.filePath,
+      start: startToken.span.start,
+      end: endToken.span.end,
+    };
+  }
+
+  /**
+   * Creates a span from a single token
+   * @param {Token} token
+   * @returns {SourceSpan}
+   */
+  spanFromToken(token) {
+    return token.span;
+  }
+}
+
+/**
+ * Parses tokens into an AST with diagnostics
+ * @param {{ tokens: Token[], sourceText: string, filePath: string }} options
+ * @returns {{ ast: FileAST, diags: Diagnostic[] }}
+ */
+export function parseUniverse({ tokens, sourceText, filePath }) {
+  const parser = new ParserCore(tokens, filePath, sourceText);
+  const ast = parser.parseFile();
+  return {
+    ast,
+    diags: parser.diagnostics,
+  };
+}
+
+/**
+ * Declaration parselets: keyword → parse function
+ * @type {Map<string, (p: ParserCore) => any>}
+ */
+const declParselets = new Map([
+  ['universe', (p) => p.parseUniverseDecl()],
+  ['anthology', (p) => p.parseContainerDecl('anthology')],
+  ['series', (p) => p.parseContainerDecl('series')],
+  ['book', (p) => p.parseContainerDecl('book')],
+  ['chapter', (p) => p.parseContainerDecl('chapter')],
+  ['concept', (p) => p.parseContainerDecl('concept')],
+  ['relates', (p) => p.parseRelatesDecl()],
+  ['relationship', (p) => p.parseRelationshipDecl()],
+  ['alias', (p) => p.parseAliasDecl()],
+  ['aliases', (p) => p.parseAliasesBlock()],
+  ['repository', (p) => p.parseRepositoryDecl()],
+  ['reference', (p) => p.parseNamedReferenceDecl()],
+]);
+
+/**
+ * Block parselets: keyword → parse function
+ * @type {Map<string, (p: ParserCore) => any>}
+ */
+const blockParselets = new Map([
+  ['describe', (p) => p.parseDescribeBlock()],
+  ['title', (p) => p.parseTitleBlock()],
+  ['note', (p) => p.parseNoteBlock()],
+  ['from', (p) => p.parseFromBlock()],
+  ['label', (p) => p.parseLabelBlock()],
+  ['reference', (p) => p.parseReferenceBlock()],
+  ['references', (p) => p.parseReferencesBlock()],
+  ['relationships', (p) => p.parseRelationshipsBlock()],
+]);
+
+/**
+ * Parses a file (top-level declarations)
+ * @returns {FileAST}
+ */
+ParserCore.prototype.parseFile = function () {
+  const decls = [];
+  const startToken = this.peek();
+
+  while (!this.isAtEnd()) {
+    const token = this.peek();
+    if (!token) break;
+
+    if (token.type === 'KEYWORD') {
+      const keyword = token.value;
+      const parselet = declParselets.get(keyword);
+      if (parselet) {
+        const decl = parselet(this);
+        if (decl) {
+          decls.push(decl);
+        }
+      } else {
+        // Try aliased container declaration before reporting error
+        const aliasedDecl = this.parseAliasedContainerDeclIfPresent();
+        if (aliasedDecl) {
+          decls.push(aliasedDecl);
+        } else {
+          // Unknown keyword - report diagnostic and skip
+          this.reportDiagnostic('error', `Unexpected keyword "${keyword}" at top level`, token.span);
+          this.advance();
+        }
+      }
+    } else if (token.type === 'IDENTIFIER') {
+      // Handle 'repository' and 'reference' even if they're IDENTIFIER tokens (not keywords)
+      const identifierValue = token.value;
+      if (identifierValue === 'repository') {
+        const parselet = declParselets.get('repository');
+        if (parselet) {
+          const decl = parselet(this);
+          if (decl) {
+            decls.push(decl);
+          }
+        }
+        continue;
+      }
+      if (identifierValue === 'reference') {
+        const parselet = declParselets.get('reference');
+        if (parselet) {
+          const decl = parselet(this);
+          if (decl) {
+            decls.push(decl);
+          }
+        }
+        continue;
+      }
+      // Try aliased container declaration before reporting error
+      const aliasedDecl = this.parseAliasedContainerDeclIfPresent();
+      if (aliasedDecl) {
+        decls.push(aliasedDecl);
+      } else {
+        // IDENTIFIER at top level - report and skip
+        this.reportDiagnostic('error', `Unexpected identifier "${token.value}" at top level`, token.span);
+        this.advance();
+      }
+    } else if (token.type === 'EOF') {
+      break;
+    } else {
+      // Unexpected token - skip (ensure we advance to avoid infinite loops)
+      this.advance();
+    }
+  }
+
+  const endToken = this.previous() || startToken;
+  return {
+    kind: 'file',
+    decls,
+    source: startToken && endToken ? this.createSpan(startToken, endToken) : undefined,
+  };
+};
+
+/**
+ * Parses a body until closing brace
+ * @returns {any[]}
+ */
+ParserCore.prototype.parseBodyUntilRBrace = function () {
+  const body = [];
+
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    const token = this.peek();
+    if (!token) break;
+
+    if (token.type === 'KEYWORD') {
+      const keyword = token.value;
+      // Special handling for 'reference' in body context
+      // Check if it's a named reference decl (reference <Name> {) or a block (reference [in X] {)
+      if (keyword === 'reference') {
+        // Peek ahead to see if next token is a named decl, including optional "in <Repo>"
+        const nextToken = this.tokens[this.index + 1];
+        const tokenAfterNext = this.tokens[this.index + 2];
+        const tokenAfterIn = this.tokens[this.index + 3];
+        const tokenAfterInLbrace = this.tokens[this.index + 4];
+        const hasNameToken = nextToken && (nextToken.type === 'IDENTIFIER' || nextToken.type === 'KEYWORD');
+        const isNamedDeclDirect = hasNameToken && tokenAfterNext && tokenAfterNext.type === 'LBRACE';
+        const isNamedDeclWithRepo = hasNameToken &&
+          tokenAfterNext && tokenAfterNext.type === 'KEYWORD' && tokenAfterNext.value === 'in' &&
+          tokenAfterIn && (tokenAfterIn.type === 'IDENTIFIER' || tokenAfterIn.type === 'KEYWORD') &&
+          tokenAfterInLbrace && tokenAfterInLbrace.type === 'LBRACE';
+        // If next is IDENTIFIER/KEYWORD and then LBRACE (or "in" + Repo + LBRACE), it's a named decl
+        if (isNamedDeclDirect || isNamedDeclWithRepo) {
+          // Parse as named reference declaration
+          const declParselet = declParselets.get('reference');
+          if (declParselet) {
+            const decl = declParselet(this);
+            if (decl) {
+              body.push(decl);
+            }
+            continue;
+          }
+        }
+        // Otherwise parse as reference block
+        const blockParselet = blockParselets.get('reference');
+        if (blockParselet) {
+          const block = blockParselet(this);
+          if (block) {
+            body.push(block);
+          }
+          continue;
+        }
+        // If both failed, report error and skip
+        this.reportDiagnostic('error', `Unexpected reference keyword in body`, token.span);
+        this.advance();
+        continue;
+      }
+      // Check declaration parselets first (for nested decls)
+      const declParselet = declParselets.get(keyword);
+      if (declParselet) {
+        const decl = declParselet(this);
+        if (decl) {
+          body.push(decl);
+        }
+        continue;
+      }
+      // Check block parselets
+      const blockParselet = blockParselets.get(keyword);
+      if (blockParselet) {
+        const block = blockParselet(this);
+        if (block) {
+          body.push(block);
+        }
+        continue;
+      }
+      // Try aliased container declaration
+      const aliasedDecl = this.parseAliasedContainerDeclIfPresent();
+      if (aliasedDecl) {
+        body.push(aliasedDecl);
+        continue;
+      }
+      // No implicit relationship usage blocks; require explicit relationships { ... }
+      // Unknown keyword - report and skip
+      this.reportDiagnostic('error', `Unexpected keyword "${keyword}" in body`, token.span);
+      this.advance();
+    } else if (token.type === 'IDENTIFIER') {
+      // Handle 'repository' and 'reference' even if they're IDENTIFIER tokens
+      const identifierValue = token.value;
+      if (identifierValue === 'repository') {
+        const parselet = declParselets.get('repository');
+        if (parselet) {
+          const decl = parselet(this);
+          if (decl) {
+            body.push(decl);
+          }
+        }
+        continue;
+      }
+      if (identifierValue === 'reference') {
+        // In body context, 'reference' should be a block, not a named decl
+        const blockParselet = blockParselets.get('reference');
+        if (blockParselet) {
+          const block = blockParselet(this);
+          if (block) {
+            body.push(block);
+          }
+        }
+        continue;
+      }
+      // Try aliased container declaration first
+      const aliasedDecl = this.parseAliasedContainerDeclIfPresent();
+      if (aliasedDecl) {
+        body.push(aliasedDecl);
+        continue;
+      }
+      // No implicit relationship usage blocks; require explicit relationships { ... }
+      // Avoid stalling on bare identifiers.
+      this.reportDiagnostic('error', `Unexpected identifier "${identifierValue}" in body`, token.span);
+      this.advance();
+    } else if (token.type === 'RBRACE') {
+      break;
+    } else {
+      // Unexpected token - report and skip (ensure we advance to avoid infinite loops)
+      this.reportDiagnostic('error', `Unexpected token ${token.type} in body`, token.span);
+      this.advance();
+    }
+  }
+
+  return body;
+};
+
+/**
+ * Parses raw content block by brace matching (returns spans only, no raw string)
+ * @param {string} kind - Block kind ('describe', 'title', 'note')
+ * @param {Token} keywordToken - The keyword token
+ * @returns {{ kind: string, contentSpan: { startOffset: number, endOffset: number }, span: SourceSpan } | null}
+ */
+ParserCore.prototype.parseRawContentBlock = function (kind, keywordToken) {
+  const { token: lbrace, diagnostic } = this.expect('LBRACE');
+  if (!lbrace) {
+    return null;
+  }
+
+  // Find matching closing brace by tracking depth
+  let depth = 1;
+  const startOffset = lbrace.span.end.offset;
+  let endOffset = startOffset;
+  let endToken = null;
+
+  while (depth > 0 && this.index < this.tokens.length) {
+    const token = this.tokens[this.index];
+    if (token.type === 'EOF') break;
+
+    if (token.type === 'LBRACE') {
+      depth++;
+      this.index++;
+    } else if (token.type === 'RBRACE') {
+      depth--;
+      if (depth === 0) {
+        endToken = token;
+        endOffset = token.span.start.offset;
+        this.index++;
+        break;
+      } else {
+        this.index++;
+      }
+    } else {
+      this.index++;
+    }
+  }
+
+  if (depth > 0) {
+    this.reportDiagnostic('error', `Unclosed ${kind} block`, keywordToken.span);
+    return null;
+  }
+
+  return {
+    kind,
+    contentSpan: {
+      startOffset,
+      endOffset,
+    },
+    span: this.createSpan(keywordToken, endToken || lbrace),
+  };
+};
+
+// ============================================================================
+// Parselet Implementations
+// ============================================================================
+
+/**
+ * Parses a universe declaration
+ * @returns {UniverseDecl | null}
+ */
+ParserCore.prototype.parseUniverseDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken('universe');
+  if (!kindToken) return null;
+
+  const name = this.consumeIdentifier();
+  if (!name) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseBodyUntilRBrace();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'universe',
+    spelledKind: kindToken.value,
+    name,
+    body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses container declarations (anthology, series, book, chapter, concept)
+ * @param {string} kind
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseContainerDecl = function (kind) {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken(kind);
+  if (!kindToken) return null;
+
+  const name = this.consumeIdentifier();
+  if (!name) return null;
+
+  // Parse optional "in ParentName" clause
+  let parentName = undefined;
+  if (this.match('KEYWORD', 'in')) {
+    this.advance(); // consume 'in'
+    const parentToken = this.peek();
+    if (parentToken && (parentToken.type === 'IDENTIFIER' || parentToken.type === 'KEYWORD')) {
+      parentName = this.parseIdentifierPath();
+    }
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseBodyUntilRBrace();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind,
+    spelledKind: kindToken.value,
+    name,
+    parentName,
+    body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses relates declarations: relates A and B { ... }
+ * @returns {RelatesDecl | null}
+ */
+ParserCore.prototype.parseRelatesDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken('relates');
+  if (!kindToken) return null;
+
+  const a = this.consumeIdentifier();
+  if (!a) return null;
+
+  const { token: andToken } = this.expect('KEYWORD', 'and');
+  if (!andToken) return null;
+
+  const b = this.consumeIdentifier();
+  if (!b) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseBodyUntilRBrace();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'relates',
+    spelledKind: kindToken.value,
+    a,
+    b,
+    body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses relationship declarations: relationship <id> [and <id2>] { ... }
+ * @returns {RelationshipDecl | null}
+ */
+ParserCore.prototype.parseRelationshipDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken('relationship');
+  if (!kindToken) return null;
+
+  const firstIdToken = this.peek();
+  if (!firstIdToken || (firstIdToken.type !== 'IDENTIFIER' && firstIdToken.type !== 'KEYWORD')) {
+    this.reportDiagnostic('error', 'Expected identifier for relationship', startToken.span);
+    return null;
+  }
+  this.advance();
+  const ids = [firstIdToken.value];
+
+  // Optional "and <id2>" for paired relationships
+  if (this.match('KEYWORD', 'and')) {
+    this.advance(); // consume 'and'
+    const secondIdToken = this.peek();
+    if (secondIdToken && (secondIdToken.type === 'IDENTIFIER' || secondIdToken.type === 'KEYWORD')) {
+      this.advance();
+      ids.push(secondIdToken.value);
+    } else {
+      this.reportDiagnostic('error', 'Expected identifier after "and"', secondIdToken?.span || startToken.span);
+    }
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseBodyUntilRBrace();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'relationshipDecl',
+    ids,
+    body,
+    span: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses alias declaration: alias Name { TargetKind }
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseAliasDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: aliasToken } = this.expectIdentifierOrKeyword('alias');
+  if (!aliasToken) return null;
+
+  const name = this.consumeIdentifier();
+  if (!name) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const targetKind = this.consumeIdentifier();
+  if (!targetKind) return null;
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'alias',
+    name,
+    targetKind,
+    source: this.createSpan(aliasToken, rbrace),
+  };
+};
+
+/**
+ * Parses aliases block: aliases { Name { TargetKind } ... }
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseAliasesBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: aliasesToken } = this.expectIdentifierOrKeyword('aliases');
+  if (!aliasesToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const aliases = [];
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    const name = this.consumeIdentifier();
+    if (!name) break;
+
+    const { token: innerLbrace } = this.expect('LBRACE');
+    if (!innerLbrace) break;
+
+    const targetKind = this.consumeIdentifier();
+    if (!targetKind) break;
+
+    const { token: innerRbrace } = this.expect('RBRACE');
+    if (!innerRbrace) break;
+
+    aliases.push({ name, targetKind });
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'aliases',
+    aliases,
+    source: this.createSpan(aliasesToken, rbrace),
+  };
+};
+
+/**
+ * Parses a describe block (spans only, no raw string)
+ * @returns {DescribeBlock | null}
+ */
+ParserCore.prototype.parseDescribeBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: keywordToken } = this.expect('KEYWORD', 'describe');
+  if (!keywordToken) return null;
+
+  const block = this.parseRawContentBlock('describe', keywordToken);
+  if (!block) return null;
+
+  return {
+    kind: 'describe',
+    contentSpan: block.contentSpan,
+    span: block.span,
+  };
+};
+
+/**
+ * Parses a title block (spans only, no raw string)
+ * @returns {TitleBlock | null}
+ */
+ParserCore.prototype.parseTitleBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: keywordToken } = this.expect('KEYWORD', 'title');
+  if (!keywordToken) return null;
+
+  const block = this.parseRawContentBlock('title', keywordToken);
+  if (!block) return null;
+
+  return {
+    kind: 'title',
+    contentSpan: block.contentSpan,
+    span: block.span,
+  };
+};
+
+/**
+ * Parses a note block (spans only, no raw string)
+ * @returns {NoteBlock | null}
+ */
+ParserCore.prototype.parseNoteBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: keywordToken } = this.expect('KEYWORD', 'note');
+  if (!keywordToken) return null;
+
+  const block = this.parseRawContentBlock('note', keywordToken);
+  if (!block) return null;
+
+  return {
+    kind: 'note',
+    contentSpan: block.contentSpan,
+    span: block.span,
+  };
+};
+
+/**
+ * Parses from block: from Endpoint { ... }
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseFromBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: fromToken } = this.expect('KEYWORD', 'from');
+  if (!fromToken) return null;
+
+  const endpoint = this.consumeIdentifier();
+  if (!endpoint) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseBodyUntilRBrace();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'from',
+    endpoint,
+    body,
+    source: this.createSpan(fromToken, rbrace),
+  };
+};
+
+/**
+ * Parses a label block (placeholder - similar to raw content blocks)
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseLabelBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: labelToken } = this.expectIdentifierOrKeyword('label');
+  if (!labelToken) return null;
+
+  // Parse as raw content block (it will handle LBRACE)
+  const block = this.parseRawContentBlock('label', labelToken);
+  if (!block) return null;
+
+  return {
+    kind: 'label',
+    contentSpan: block.contentSpan,
+    span: block.span,
+  };
+};
+
+/**
+ * Parses a repository declaration: repository <Name> [in <Parent>] { ... }
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseRepositoryDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken('repository');
+  if (!kindToken) return null;
+
+  const name = this.consumeIdentifier();
+  if (!name) return null;
+
+  // Parse optional "in ParentName" clause
+  let parentName = undefined;
+  if (this.match('KEYWORD', 'in')) {
+    this.advance(); // consume 'in'
+    const parentToken = this.peek();
+    if (parentToken && (parentToken.type === 'IDENTIFIER' || parentToken.type === 'KEYWORD')) {
+      parentName = this.parseIdentifierPath();
+    }
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseRepositoryBody();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'repository',
+    spelledKind: kindToken.value,
+    name,
+    parentName,
+    children: body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses a named reference declaration: reference <Name> { ... }
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseNamedReferenceDecl = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: kindToken } = this.expectKindToken('reference');
+  if (!kindToken) return null;
+
+  const name = this.consumeIdentifier();
+  if (!name) return null;
+
+  // Optional "in <RepositoryName>" clause
+  let repositoryName = undefined;
+  if (this.match('KEYWORD', 'in')) {
+    this.advance();
+    repositoryName = this.parseIdentifierPath();
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseReferenceBody();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'referenceDecl',
+    name,
+    repositoryName,
+    children: body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses a reference block: reference [in <RepositoryName>] { ... }
+ * Used inside container bodies (unnamed reference)
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseReferenceBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: refToken } = this.expect('KEYWORD', 'reference');
+  if (!refToken) return null;
+
+  // Parse optional "in RepositoryName" clause
+  let repositoryName = undefined;
+  if (this.match('KEYWORD', 'in')) {
+    this.advance(); // consume 'in'
+    const repoToken = this.peek();
+    if (repoToken && (repoToken.type === 'IDENTIFIER' || repoToken.type === 'KEYWORD')) {
+      repositoryName = this.parseIdentifierPath();
+    }
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const body = this.parseReferenceBody();
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'reference',
+    repositoryName,
+    children: body,
+    source: this.createSpan(refToken, rbrace),
+  };
+};
+
+/**
+ * Parses a references block: references { <items> }
+ * Items are identifier paths (reference names)
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseReferencesBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: refsToken } = this.expect('KEYWORD', 'references');
+  if (!refsToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const items = [];
+
+  // Parse items until closing brace
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    // Skip optional commas
+    if (this.match('COMMA')) {
+      this.advance();
+      continue;
+    }
+
+    const itemStartToken = this.peek();
+    if (!itemStartToken) break;
+
+    // Parse reference name as identifier path
+    const refPath = this.parseIdentifierPath();
+    if (!refPath) {
+      // Not a valid item - report and try to recover
+      const token = this.peek();
+      if (token) {
+        this.reportDiagnostic('error', `Expected identifier path in references block`, token.span);
+        this.advance(); // Advance to avoid infinite loop
+      } else {
+        break;
+      }
+      continue;
+    }
+
+    // After parseIdentifierPath, previous() gives us the last token of the path
+    let refEndToken = this.previous();
+    if (!refEndToken) refEndToken = itemStartToken;
+
+    // Create item span
+    const itemSpan = itemStartToken && refEndToken
+      ? this.createSpan(itemStartToken, refEndToken)
+      : (itemStartToken ? this.spanFromToken(itemStartToken) : undefined);
+
+    items.push({
+      kind: 'ref',
+      ref: refPath,
+      span: itemSpan,
+    });
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'references',
+    items,
+    source: this.createSpan(refsToken, rbrace),
+  };
+};
+
+/**
+ * Parses repository declaration body.
+ * @returns {any[]}
+ */
+ParserCore.prototype.parseRepositoryBody = function () {
+  const body = [];
+
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    const token = this.peek();
+    if (!token) break;
+
+    if (token.type === 'KEYWORD' || token.type === 'IDENTIFIER') {
+      const keyword = token.value;
+      if (keyword === 'url') {
+        const block = this.parseStringValueBlock('url');
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'title') {
+        const block = this.parseTitleBlock();
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'describe') {
+        const block = this.parseDescribeBlock();
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'note') {
+        const block = this.parseNoteBlock();
+        if (block) body.push(block);
+        continue;
+      }
+    }
+
+    this.reportDiagnostic('error', `Unexpected token ${token.type} in repository body`, token.span);
+    this.advance();
+  }
+
+  return body;
+};
+
+/**
+ * Parses reference declaration body.
+ * @returns {any[]}
+ */
+ParserCore.prototype.parseReferenceBody = function () {
+  const body = [];
+
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    const token = this.peek();
+    if (!token) break;
+
+    if (token.type === 'KEYWORD' || token.type === 'IDENTIFIER') {
+      const keyword = token.value;
+      if (keyword === 'url') {
+        const block = this.parseStringValueBlock('url');
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'paths') {
+        const block = this.parsePathsBlock();
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'kind') {
+        const block = this.parseStringValueBlock('kind');
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'title') {
+        const block = this.parseTitleBlock();
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'describe') {
+        const block = this.parseDescribeBlock();
+        if (block) body.push(block);
+        continue;
+      }
+      if (keyword === 'note') {
+        const block = this.parseNoteBlock();
+        if (block) body.push(block);
+        continue;
+      }
+    }
+
+    this.reportDiagnostic('error', `Unexpected token ${token.type} in reference body`, token.span);
+    this.advance();
+  }
+
+  return body;
+};
+
+/**
+ * Parses a string value block like url { '...' } or kind { '...' }.
+ * @param {string} kind
+ * @returns {{ kind: string, value: string, span: SourceSpan } | null}
+ */
+ParserCore.prototype.parseStringValueBlock = function (kind) {
+  const startToken = this.peek();
+  if (!startToken) return null;
+  const { token: kindToken } = this.expectIdentifierOrKeyword(kind);
+  if (!kindToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  let valueToken = null;
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    if (this.match('STRING') || this.match('IDENTIFIER') || this.match('KEYWORD')) {
+      valueToken = this.advance();
+      break;
+    }
+    this.advance();
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+  if (!valueToken) {
+    this.reportDiagnostic('error', `Expected value in ${kind} block`, kindToken.span);
+    return null;
+  }
+
+  return {
+    kind,
+    value: valueToken.value,
+    span: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses a paths block: paths { 'a' 'b' }
+ * @returns {{ kind: string, paths: string[], span: SourceSpan } | null}
+ */
+ParserCore.prototype.parsePathsBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+  const { token: kindToken } = this.expectIdentifierOrKeyword('paths');
+  if (!kindToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const paths = [];
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    if (this.match('COMMA')) {
+      this.advance();
+      continue;
+    }
+    if (this.match('STRING')) {
+      const valueToken = this.advance();
+      if (valueToken) {
+        paths.push(valueToken.value);
+      }
+      continue;
+    }
+    this.advance();
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'paths',
+    paths,
+    span: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses a relationships block
+ * Supports legacy string syntax and new relationship/targets syntax
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseRelationshipsBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  const { token: relationshipsToken } = this.expect('KEYWORD', 'relationships');
+  if (!relationshipsToken) return null;
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const source = {
+    file: this.filePath,
+    start: lbrace.span.end,
+    end: lbrace.span.end,
+  };
+
+  // Probe for legacy syntax (string literals only)
+  let foundString = false;
+  let foundIdentifier = false;
+  let probeIndex = this.index;
+  while (probeIndex < this.tokens.length) {
+    const token = this.tokens[probeIndex];
+    if (!token || token.type === 'EOF' || token.type === 'RBRACE') break;
+    if (token.type === 'STRING') foundString = true;
+    if (token.type === 'IDENTIFIER' || token.type === 'KEYWORD') foundIdentifier = true;
+    if (foundString && foundIdentifier) break;
+    probeIndex++;
+  }
+
+  if (foundString && !foundIdentifier) {
+    const values = [];
+    while (!this.isAtEnd() && !this.match('RBRACE')) {
+      if (this.match('COMMA')) {
+        this.advance();
+        continue;
+      }
+      if (this.match('STRING')) {
+        const stringToken = this.advance();
+        if (stringToken) {
+          values.push(stringToken.value);
+          source.end = stringToken.span.end;
+        }
+      } else {
+        this.advance();
+      }
+    }
+
+    const { token: rbrace } = this.expect('RBRACE');
+    if (!rbrace) return null;
+    source.end = rbrace.span.start;
+
+    return {
+      kind: 'relationships',
+      values,
+      source,
+    };
+  }
+
+  const entries = [];
+
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    if (this.match('COMMA')) {
+      this.advance();
+      continue;
+    }
+
+    if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+      const relationshipToken = this.advance();
+      if (!relationshipToken) {
+        break;
+      }
+      const relationshipId = relationshipToken.value;
+
+      if (!this.match('LBRACE')) {
+        this.reportDiagnostic(
+          'error',
+          `Expected '{' after relationship identifier "${relationshipId}"`,
+          relationshipToken.span,
+        );
+        continue;
+      }
+
+      const { token: targetLbrace } = this.expect('LBRACE');
+      if (!targetLbrace) return null;
+
+      const targets = [];
+      while (!this.isAtEnd() && !this.match('RBRACE')) {
+        if (this.match('COMMA')) {
+          this.advance();
+          continue;
+        }
+
+        if (this.match('IDENTIFIER') || this.match('KEYWORD')) {
+          const targetToken = this.advance();
+          if (!targetToken) {
+            break;
+          }
+          const targetId = targetToken.value;
+          let metadata = undefined;
+
+          if (this.match('LBRACE')) {
+            const { token: metadataLbrace } = this.expect('LBRACE');
+            if (!metadataLbrace) return null;
+            const metadataBody = this.parseBodyUntilRBrace();
+            const { token: metadataRbrace } = this.expect('RBRACE');
+            if (!metadataRbrace) return null;
+
+            const describeBlock = metadataBody.find((b) => b.kind === 'describe');
+            if (describeBlock) {
+              metadata = describeBlock;
+            }
+          }
+
+          targets.push({
+            id: targetId,
+            metadata,
+          });
+        } else {
+          this.advance();
+        }
+      }
+
+      const { token: targetRbrace } = this.expect('RBRACE');
+      if (!targetRbrace) return null;
+      source.end = targetRbrace.span.end;
+
+      entries.push({
+        relationshipId,
+        targets,
+      });
+      continue;
+    }
+
+    this.advance();
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+  source.end = rbrace.span.start;
+
+  return {
+    kind: 'relationships',
+    entries,
+    source,
+  };
+};
+
+/**
+ * Parses aliased container kind declaration if present
+ * Pattern: (IDENTIFIER|KEYWORD) (IDENTIFIER|KEYWORD) [KEYWORD 'in' + identifierPath] LBRACE
+ * Only triggers when first token is NOT a known decl keyword parselet
+ * @returns {any | null}
+ */
+ParserCore.prototype.parseAliasedContainerDeclIfPresent = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  // Must be IDENTIFIER or KEYWORD
+  if (startToken.type !== 'IDENTIFIER' && startToken.type !== 'KEYWORD') {
+    return null;
+  }
+
+  const kindName = startToken.value;
+  
+  // Don't steal known declaration keywords
+  if (declParselets.has(kindName)) {
+    return null;
+  }
+
+  // Check if pattern matches: kindName name [in parent] {
+  // Need to peek ahead to see if we have: kindName name [in ...] LBRACE
+  const savedIndex = this.index;
+  
+  // Consume kindName
+  this.advance();
+  
+  // Next must be IDENTIFIER or KEYWORD (the name)
+  const nameToken = this.peek();
+  if (!nameToken || (nameToken.type !== 'IDENTIFIER' && nameToken.type !== 'KEYWORD')) {
+    // Restore position
+    this.index = savedIndex;
+    return null;
+  }
+  
+  // Consume name
+  const name = nameToken.value;
+  this.advance();
+  
+  // Check for optional "in ParentName"
+  let parentName = undefined;
+  if (this.match('KEYWORD', 'in')) {
+    this.advance(); // consume 'in'
+    const parentToken = this.peek();
+    if (parentToken && (parentToken.type === 'IDENTIFIER' || parentToken.type === 'KEYWORD')) {
+      parentName = this.parseIdentifierPath();
+    }
+  }
+  
+  // Must be followed by LBRACE
+  if (!this.match('LBRACE')) {
+    // Restore position
+    this.index = savedIndex;
+    return null;
+  }
+  
+  // Pattern matches - parse the declaration
+  const kindToken = startToken;
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) {
+    this.index = savedIndex;
+    return null;
+  }
+  
+  const body = this.parseBodyUntilRBrace();
+  
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) {
+    this.index = savedIndex;
+    return null;
+  }
+  
+  return {
+    kind: 'container',
+    spelledKind: kindName,
+    name,
+    parentName,
+    body,
+    source: this.createSpan(kindToken, rbrace),
+  };
+};
+
+/**
+ * Parses relationship usage block: <identifier|keyword> { <items> }
+ * Grammar: RefPath = (IDENTIFIER|KEYWORD) (DOT (IDENTIFIER|KEYWORD))*
+ *          RelItem = STRING | (RefPath [LBRACE body RBRACE])
+ *          Items repeat until closing RBRACE, commas optional
+ * @returns {RelUseBlock | null}
+ */
+ParserCore.prototype.parseRelUseBlock = function () {
+  const startToken = this.peek();
+  if (!startToken) return null;
+
+  // Name can be IDENTIFIER or KEYWORD
+  const nameToken = this.peek();
+  if (!nameToken || (nameToken.type !== 'IDENTIFIER' && nameToken.type !== 'KEYWORD')) {
+    return null;
+  }
+  const name = nameToken.value;
+  this.advance();
+
+  // Check if followed by brace
+  if (!this.match('LBRACE')) {
+    // Not a block, just an identifier/keyword - report and return null
+    this.reportDiagnostic('error', `Unexpected ${nameToken.type.toLowerCase()} "${name}"`, startToken.span);
+    return null;
+  }
+
+  const { token: lbrace } = this.expect('LBRACE');
+  if (!lbrace) return null;
+
+  const items = [];
+
+  // Parse items until closing brace
+  while (!this.isAtEnd() && !this.match('RBRACE')) {
+    // Skip optional commas
+    if (this.match('COMMA')) {
+      this.advance();
+      continue;
+    }
+
+    const itemStartToken = this.peek();
+    if (!itemStartToken) break;
+
+    // Check if it's a STRING item
+    if (itemStartToken.type === 'STRING') {
+      const stringToken = this.advance();
+      if (stringToken) {
+        items.push({
+          kind: 'string',
+          value: stringToken.value,
+          span: this.spanFromToken(stringToken),
+        });
+      }
+      continue;
+    }
+
+    // Otherwise parse as reference path
+    const refPath = this.parseIdentifierPath();
+    if (!refPath) {
+      // Not a valid item - report and try to recover
+      const token = this.peek();
+      if (token) {
+        this.reportDiagnostic('error', `Expected string or identifier path in relationship usage block`, token.span);
+        this.advance(); // Advance to avoid infinite loop
+      } else {
+        break;
+      }
+      continue;
+    }
+
+    // After parseIdentifierPath, previous() gives us the last token of the path
+    let refEndToken = this.previous();
+    if (!refEndToken) refEndToken = itemStartToken;
+
+    // Check if followed by inline body
+    let body = undefined;
+    if (this.match('LBRACE')) {
+      const bodyLbrace = this.advance();
+      if (bodyLbrace) {
+        // Parse body using existing parseBodyUntilRBrace
+        body = this.parseBodyUntilRBrace();
+        const { token: bodyRbrace } = this.expect('RBRACE');
+        if (bodyRbrace) {
+          refEndToken = bodyRbrace;
+        }
+      }
+    }
+
+    // Create item span from ref path start to end (or body end if present)
+    const itemSpan = itemStartToken && refEndToken
+      ? this.createSpan(itemStartToken, refEndToken)
+      : (itemStartToken ? this.spanFromToken(itemStartToken) : undefined);
+
+    items.push({
+      kind: 'ref',
+      ref: refPath,
+      body,
+      span: itemSpan,
+    });
+  }
+
+  const { token: rbrace } = this.expect('RBRACE');
+  if (!rbrace) return null;
+
+  return {
+    kind: 'relUse',
+    name,
+    items,
+    span: this.createSpan(startToken, rbrace),
+  };
+};
+
+/**
+ * Debug helper: prints AST in stable tree format
+ * @param {any} ast - AST node or FileAST
+ */
+export function debugAst(ast) {
+  /**
+   * @param {any} node
+   * @param {number} indent
+   */
+  function printNode(node, indent = 0) {
+    const prefix = '  '.repeat(indent);
+    if (!node || typeof node !== 'object') {
+      console.log(`${prefix}${node}`);
+      return;
+    }
+
+    if (node.kind) {
+      // AST node
+      const kind = node.kind;
+      const fields = [];
+      if (node.name !== undefined) fields.push(`name=${node.name}`);
+      if (node.spelledKind !== undefined) fields.push(`spelledKind=${node.spelledKind}`);
+      if (node.a !== undefined) fields.push(`a=${node.a}`);
+      if (node.b !== undefined) fields.push(`b=${node.b}`);
+      if (node.endpoint !== undefined) fields.push(`endpoint=${node.endpoint}`);
+      if (node.ids !== undefined) fields.push(`ids=[${node.ids.join(',')}]`);
+      if (node.ref !== undefined) fields.push(`ref=${node.ref}`);
+      if (node.keyword !== undefined) fields.push(`keyword=${node.keyword}`);
+      if (node.parentName !== undefined) fields.push(`parentName=${node.parentName}`);
+      if (node.repositoryName !== undefined) fields.push(`repositoryName=${node.repositoryName}`);
+      if (node.contentSpan !== undefined) fields.push(`contentSpan=[${node.contentSpan.startOffset}..${node.contentSpan.endOffset}]`);
+
+      const childCount = Array.isArray(node.body) ? node.body.length
+        : Array.isArray(node.children) ? node.children.length
+        : Array.isArray(node.items) ? node.items.length
+        : Array.isArray(node.decls) ? node.decls.length
+        : 0;
+      if (childCount > 0) fields.push(`children=${childCount}`);
+
+      const fieldStr = fields.length > 0 ? ` (${fields.join(', ')})` : '';
+      console.log(`${prefix}${kind}${fieldStr}`);
+
+      if (Array.isArray(node.body)) {
+        node.body.forEach(/** @param {any} child */ (child) => printNode(child, indent + 1));
+      } else if (Array.isArray(node.children)) {
+        node.children.forEach(/** @param {any} child */ (child) => printNode(child, indent + 1));
+      } else if (Array.isArray(node.items)) {
+        // Special handling for references block vs relUse block
+        if (node.kind === 'references') {
+          node.items.forEach(/** @param {any} item */ (item) => {
+            if (item && typeof item === 'object' && item.kind === 'ref') {
+              console.log(`${prefix}  item ref=${item.ref}`);
+            } else {
+              printNode(item, indent + 1);
+            }
+          });
+        } else {
+          // relUse block items
+          node.items.forEach(/** @param {any} item */ (item) => {
+            if (item && typeof item === 'object' && item.kind) {
+              if (item.kind === 'string') {
+                console.log(`${prefix}  item string='${item.value}'`);
+              } else if (item.kind === 'ref') {
+                const refFields = [`ref=${item.ref}`];
+                if (item.body && Array.isArray(item.body) && item.body.length > 0) {
+                  refFields.push(`body=${item.body.length}`);
+                }
+                console.log(`${prefix}  item ref (${refFields.join(', ')})`);
+                if (item.body && Array.isArray(item.body)) {
+                  item.body.forEach(/** @param {any} child */ (child) => printNode(child, indent + 2));
+                }
+              } else {
+                printNode(item, indent + 1);
+              }
+            } else {
+              printNode(item, indent + 1);
+            }
+          });
+        }
+      } else if (Array.isArray(node.decls)) {
+        node.decls.forEach(/** @param {any} child */ (child) => printNode(child, indent + 1));
+      }
+    } else {
+      // Unknown object
+      console.log(`${prefix}[object]`);
+    }
+  }
+
+  printNode(ast);
+}