@sprig-and-prose/sprig-universe 0.1.0

package/src/parser.js

@@ -0,0 +1,1656 @@
+/**
+ * @fileoverview Recursive descent parser for Sprig universe syntax
+ */
+
+import { mergeSpans } from './util/span.js';
+
+/**
+ * @typedef {import('./ast.js').FileAST} FileAST
+ * @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('./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').DocumentationBlock} DocumentationBlock
+ * @typedef {import('./ast.js').DocumentBlock} DocumentBlock
+ * @typedef {import('./ast.js').NamedDocumentBlock} NamedDocumentBlock
+ * @typedef {import('./scanner.js').Token} Token
+ */
+
+/**
+ * Parses tokens into an AST
+ * @param {Token[]} tokens - Tokens from scanner
+ * @param {string} file - File path
+ * @param {string} sourceText - Original source text for raw content extraction
+ * @returns {FileAST}
+ */
+export function parse(tokens, file, sourceText) {
+  const parser = new Parser(tokens, file, sourceText);
+  return parser.parseFile();
+}
+
+class Parser {
+  /**
+   * @param {Token[]} tokens
+   * @param {string} file
+   * @param {string} sourceText
+   */
+  constructor(tokens, file, sourceText) {
+    this.tokens = tokens;
+    this.file = file;
+    this.sourceText = sourceText;
+    this.pos = 0;
+  }
+
+  /**
+   * @returns {Token | null}
+   */
+  peek() {
+    if (this.pos >= this.tokens.length) {
+      return null;
+    }
+    return this.tokens[this.pos];
+  }
+
+  /**
+   * @returns {Token | null}
+   */
+  advance() {
+    if (this.pos >= this.tokens.length) {
+      return null;
+    }
+    return this.tokens[this.pos++];
+  }
+
+  /**
+   * @param {string} type
+   * @returns {boolean}
+   */
+  match(type) {
+    const token = this.peek();
+    return token !== null && token.type === type;
+  }
+
+  /**
+   * @param {string} type
+   * @param {string} [value]
+   * @returns {Token}
+   * @throws {Error}
+   */
+  expect(type, value) {
+    const token = this.advance();
+    if (!token || token.type !== type) {
+      throw new Error(
+        `Expected ${type}, got ${token ? token.type : 'EOF'} at ${this.file}:${token ? token.span.start.line : '?'}`,
+      );
+    }
+    if (value !== undefined && token.value !== value) {
+      throw new Error(
+        `Expected ${type} with value "${value}", got "${token.value}" at ${this.file}:${token.span.start.line}`,
+      );
+    }
+    return token;
+  }
+
+  /**
+   * @returns {FileAST}
+   */
+  parseFile() {
+    const universes = [];
+    const scenes = [];
+    const startToken = this.peek();
+
+    while (!this.match('EOF')) {
+      if (this.match('KEYWORD') && this.peek()?.value === 'universe') {
+        universes.push(this.parseUniverse());
+      } else if (this.match('KEYWORD') && this.peek()?.value === 'scene') {
+        scenes.push(this.parseScene());
+      } 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
+        }
+      }
+    }
+
+    return {
+      file: this.file,
+      universes,
+      scenes,
+      source: startToken
+        ? {
+            file: this.file,
+            start: startToken.span.start,
+            end: this.tokens[this.tokens.length - 1]?.span.end || startToken.span.end,
+          }
+        : undefined,
+    };
+  }
+
+  /**
+   * @returns {UniverseDecl}
+   */
+  parseUniverse() {
+    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 rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'universe',
+      name: nameToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @param {string[]} allowedKeywords - Keywords allowed in this body
+   * @returns {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | DocumentationBlock | NamedReferenceBlock | NamedDocumentBlock | UnknownBlock>}
+   */
+  parseBlockBody(allowedKeywords) {
+    const body = [];
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      // Check for keywords or identifiers that might start a block
+      if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+        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;
+          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 document block
+            body.push(this.parseNamedDocument());
+            continue;
+          }
+          // Otherwise, it's an inline document (only valid inside documentation block)
+          // 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')) {
+          body.push(this.parseDescribe());
+        } else if (keyword === 'title' && allowedKeywords.includes('title')) {
+          body.push(this.parseTitle());
+        } else if (keyword === 'repository' && allowedKeywords.includes('repository')) {
+          body.push(this.parseRepository());
+        } 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') {
+          body.push(this.parseReferences());
+        } else if (keyword === 'documentation') {
+          body.push(this.parseDocumentation());
+        } else {
+          // Unknown keyword/identifier followed by brace - parse as UnknownBlock
+          // Check if next token is LBRACE
+          const nextPos = this.pos + 1;
+          if (nextPos < this.tokens.length && this.tokens[nextPos].type === 'LBRACE') {
+            body.push(this.parseUnknownBlock());
+          } else {
+            // Not a block, just skip this token (tolerant parsing)
+            this.advance();
+          }
+        }
+      } else {
+        // Unexpected token in body - skip (tolerant)
+        this.advance();
+      }
+    }
+
+    return body;
+  }
+
+  /**
+   * @returns {AnthologyDecl}
+   */
+  parseAnthology() {
+    const startToken = this.expect('KEYWORD', 'anthology');
+    const nameToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'anthology',
+      name: nameToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {SeriesDecl}
+   */
+  parseSeries() {
+    const startToken = this.expect('KEYWORD', 'series');
+    const nameToken = this.expect('IDENTIFIER');
+    
+    // Optional "in <AnthologyName>" syntax
+    let parentName = undefined;
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const parentToken = this.expect('IDENTIFIER');
+      parentName = parentToken.value;
+    }
+    
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['book', 'chapter', 'describe', 'title', 'references', 'documentation']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'series',
+      name: nameToken.value,
+      parentName,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {BookDecl}
+   */
+  parseBook() {
+    const startToken = this.expect('KEYWORD', 'book');
+    const nameToken = this.expect('IDENTIFIER');
+    this.expect('KEYWORD', 'in');
+    const parentToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['chapter', 'describe', 'title', 'references', 'documentation']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'book',
+      name: nameToken.value,
+      parentName: parentToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {ChapterDecl}
+   */
+  parseChapter() {
+    const startToken = this.expect('KEYWORD', 'chapter');
+    const nameToken = this.expect('IDENTIFIER');
+    this.expect('KEYWORD', 'in');
+    const parentToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'chapter',
+      name: nameToken.value,
+      parentName: parentToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {ConceptDecl}
+   */
+  parseConcept() {
+    const startToken = this.expect('KEYWORD', 'concept');
+    const nameToken = this.expect('IDENTIFIER');
+    
+    // Optional "in <ParentName>" syntax
+    let parentName = undefined;
+    if (this.match('KEYWORD') && this.peek()?.value === 'in') {
+      this.expect('KEYWORD', 'in');
+      const parentToken = this.expect('IDENTIFIER');
+      parentName = parentToken.value;
+    }
+    
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['describe', 'title', 'references', 'documentation']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'concept',
+      name: nameToken.value,
+      parentName,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {RelatesDecl}
+   */
+  parseRelates() {
+    const startToken = this.expect('KEYWORD', 'relates');
+    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']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'relates',
+      a: aToken.value,
+      b: bToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {FromBlock}
+   */
+  parseFrom() {
+    const startToken = this.expect('KEYWORD', 'from');
+    const endpointToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseBlockBody(['relationships', 'describe', 'title']);
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'from',
+      endpoint: endpointToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {RelationshipsBlock}
+   */
+  parseRelationships() {
+    const startToken = this.expect('KEYWORD', 'relationships');
+    const lbrace = this.expect('LBRACE');
+    const values = [];
+    let relationshipsSource = {
+      file: this.file,
+      start: lbrace.span.end,
+      end: lbrace.span.end,
+    };
+
+    // Parse string literals (commas are whitespace, so scanner skips them)
+    // We parse consecutive STRING tokens until we hit RBRACE
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('STRING')) {
+        const stringToken = this.advance();
+        if (stringToken) {
+          values.push(stringToken.value);
+          relationshipsSource.end = stringToken.span.end;
+        }
+      } else {
+        // Skip non-string tokens (whitespace/comments already skipped by scanner)
+        // This handles commas and other unexpected tokens gracefully
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+    relationshipsSource.end = rbrace.span.start;
+
+    return {
+      kind: 'relationships',
+      values,
+      source: relationshipsSource,
+    };
+  }
+
+  /**
+   * Parses a describe block, consuming raw text until matching closing brace
+   * Treats braces inside as plain text (doesn't parse nested structures)
+   * @returns {DescribeBlock}
+   */
+  parseDescribe() {
+    const startToken = this.expect('KEYWORD', 'describe');
+    const lbrace = this.expect('LBRACE');
+
+    // Find the matching closing brace by tracking depth
+    // We start at depth 1 (the opening brace we just consumed)
+    let depth = 1;
+    const startOffset = lbrace.span.end.offset;
+    let endOffset = startOffset;
+    let endToken = null;
+
+    // Consume tokens until we find the matching closing brace
+    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) {
+          // This is our closing brace
+          endToken = token;
+          endOffset = token.span.start.offset;
+          this.pos++;
+          break;
+        } else {
+          this.pos++;
+        }
+      } else {
+        this.pos++;
+      }
+    }
+
+    if (depth > 0) {
+      throw new Error(`Unclosed describe block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'describe',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a title block containing a string literal
+   * @returns {TitleBlock}
+   */
+  parseTitle() {
+    const startToken = this.expect('IDENTIFIER', 'title');
+    const lbrace = this.expect('LBRACE');
+
+    // Find the matching closing brace by tracking depth
+    // We start at depth 1 (the opening brace we just consumed)
+    let depth = 1;
+    const startOffset = lbrace.span.end.offset;
+    let endOffset = startOffset;
+    let endToken = null;
+
+    // Consume tokens until we find the matching closing brace
+    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) {
+          // This is our closing brace
+          endToken = token;
+          endOffset = token.span.start.offset;
+          this.pos++;
+          break;
+        } else {
+          this.pos++;
+        }
+      } else {
+        this.pos++;
+      }
+    }
+
+    if (depth > 0) {
+      throw new Error(`Unclosed title block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'title',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a references block containing nested reference blocks and using blocks
+   * @returns {ReferencesBlock}
+   */
+  parseReferences() {
+    const startToken = this.expect('IDENTIFIER', 'references');
+    const lbrace = this.expect('LBRACE');
+    const references = [];
+
+    // 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)
+        this.advance();
+      }
+    }
+
+    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)
+        this.advance();
+      }
+    }
+
+    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;
+
+    // Parse repository, paths, optional kind, and optional describe
+    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');
+        } 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();
+        }
+      } else {
+        // Skip unexpected tokens
+        this.advance();
+      }
+    }
+
+    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}`);
+    }
+
+    return {
+      kind: 'reference',
+      repository,
+      paths,
+      referenceKind: kind,
+      describe,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a named reference block: reference <Name> { ... }
+   * @returns {NamedReferenceBlock}
+   */
+  parseNamedReference() {
+    const startToken = this.expect('IDENTIFIER', 'reference');
+    const nameToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    let repository = null;
+    let paths = [];
+    let describe = null;
+    let kind = 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');
+        } 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();
+        }
+      } 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,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a string block (e.g., repository { 'string' } or repository { Identifier })
+   * @param {string} fieldName - Field name for error messages
+   * @returns {string}
+   */
+  parseStringBlock(fieldName) {
+    // Accept either IDENTIFIER or KEYWORD (since 'repository' is now a keyword)
+    if (!this.match('IDENTIFIER') && !this.match('KEYWORD')) {
+      throw new Error(`Expected IDENTIFIER or KEYWORD '${fieldName}' at ${this.file}:${this.peek()?.span.start.line}`);
+    }
+    const fieldToken = this.advance();
+    if (fieldToken.value !== fieldName) {
+      throw new Error(`Expected '${fieldName}', got '${fieldToken.value}' at ${this.file}:${fieldToken.span.start.line}`);
+    }
+    const lbrace = this.expect('LBRACE');
+
+    // Find string literal or identifier
+    let stringValue = null;
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('STRING')) {
+        const stringToken = this.advance();
+        if (stringValue !== null) {
+          throw new Error(`Multiple values in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+        }
+        stringValue = stringToken.value;
+      } else if (this.match('IDENTIFIER')) {
+        const identifierToken = this.advance();
+        if (stringValue !== null) {
+          throw new Error(`Multiple values in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+        }
+        stringValue = identifierToken.value;
+      } else {
+        // Skip whitespace and other tokens
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    if (stringValue === null) {
+      throw new Error(`Expected string literal or identifier in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+    }
+
+    return stringValue;
+  }
+
+  /**
+   * Parses a value block that can contain a string, identifier, or number
+   * @param {string} fieldName - Field name for error messages
+   * @returns {string | number}
+   */
+  parseValueBlock(fieldName) {
+    this.expect('IDENTIFIER', fieldName);
+    const lbrace = this.expect('LBRACE');
+
+    let value = null;
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('STRING')) {
+        const stringToken = this.advance();
+        if (value !== null) {
+          throw new Error(`Multiple values in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+        }
+        value = stringToken.value;
+      } else if (this.match('IDENTIFIER')) {
+        const identifierToken = this.advance();
+        if (value !== null) {
+          throw new Error(`Multiple values in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+        }
+        value = identifierToken.value;
+      } else if (this.match('NUMBER')) {
+        const numberToken = this.advance();
+        if (value !== null) {
+          throw new Error(`Multiple values in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+        }
+        value = numberToken.value;
+      } else {
+        // Skip whitespace and other tokens
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    if (value === null) {
+      throw new Error(`Expected value (string, identifier, or number) in ${fieldName} block at ${this.file}:${lbrace.span.start.line}`);
+    }
+
+    return value;
+  }
+
+  /**
+   * Parses an options block containing key-value pairs
+   * @returns {Record<string, string | number>}
+   */
+  parseOptionsBlock() {
+    this.expect('IDENTIFIER', 'options');
+    const lbrace = this.expect('LBRACE');
+    const options = {};
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('IDENTIFIER')) {
+        const keyToken = this.advance();
+        const key = keyToken.value;
+        
+        // Expect LBRACE for the value block
+        const valueLbrace = this.expect('LBRACE');
+        let value = null;
+
+        // Parse value (string, identifier, or number)
+        while (!this.match('RBRACE') && !this.match('EOF')) {
+          if (this.match('STRING')) {
+            const stringToken = this.advance();
+            if (value !== null) {
+              throw new Error(`Multiple values in ${key} block at ${this.file}:${valueLbrace.span.start.line}`);
+            }
+            value = stringToken.value;
+          } else if (this.match('IDENTIFIER')) {
+            const identifierToken = this.advance();
+            if (value !== null) {
+              throw new Error(`Multiple values in ${key} block at ${this.file}:${valueLbrace.span.start.line}`);
+            }
+            value = identifierToken.value;
+          } else if (this.match('NUMBER')) {
+            const numberToken = this.advance();
+            if (value !== null) {
+              throw new Error(`Multiple values in ${key} block at ${this.file}:${valueLbrace.span.start.line}`);
+            }
+            value = numberToken.value;
+          } else {
+            // Skip whitespace and other tokens
+            this.advance();
+          }
+        }
+
+        const valueRbrace = this.expect('RBRACE');
+
+        if (value === null) {
+          throw new Error(`Expected value (string, identifier, or number) in ${key} block at ${this.file}:${valueLbrace.span.start.line}`);
+        }
+
+        options[key] = value;
+      } else {
+        // Skip unexpected tokens
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+    return options;
+  }
+
+  /**
+   * Parses a repository block: repository <Identifier> { kind { ... } options { ... } }
+   * @returns {RepositoryDecl}
+   */
+  parseRepository() {
+    const startToken = this.expect('KEYWORD', 'repository');
+    const nameToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+
+    let kind = null;
+    let options = 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();
+        } 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 || {},
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a paths block (e.g., paths { 'path1', 'path2' })
+   * @returns {string[]}
+   */
+  parsePathsBlock() {
+    this.expect('IDENTIFIER', 'paths');
+    const lbrace = this.expect('LBRACE');
+    const paths = [];
+
+    // Parse string literals (commas are whitespace, so scanner skips them)
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('STRING')) {
+        const stringToken = this.advance();
+        paths.push(stringToken.value);
+      } else {
+        // Skip non-string tokens (whitespace/comments already skipped by scanner)
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    return paths;
+  }
+
+  /**
+   * Parses a documentation block containing nested document blocks
+   * @returns {DocumentationBlock}
+   */
+  parseDocumentation() {
+    const startToken = this.expect('IDENTIFIER', 'documentation');
+    const lbrace = this.expect('LBRACE');
+    const documents = [];
+
+    // Parse nested document blocks
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      // Look for 'document' identifier
+      if ((this.match('IDENTIFIER') || this.match('KEYWORD')) && this.peek()?.value === 'document') {
+        documents.push(this.parseDocument());
+      } else {
+        // Skip unexpected tokens (tolerant parsing)
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'documentation',
+      documents,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a single document block
+   * Supports both forms: `document Title { ... }` and `document { ... }`
+   * @returns {DocumentBlock}
+   */
+  parseDocument() {
+    const startToken = this.expect('IDENTIFIER', 'document');
+    let title = null;
+
+    // Check if there's an optional title identifier before the brace
+    if (this.match('IDENTIFIER')) {
+      // Peek ahead to see if next token is LBRACE (meaning this is a title)
+      const nextPos = this.pos + 1;
+      if (nextPos < this.tokens.length && this.tokens[nextPos].type === 'LBRACE') {
+        const titleToken = this.expect('IDENTIFIER');
+        title = titleToken.value;
+      }
+    }
+
+    const lbrace = this.expect('LBRACE');
+    let kind = null;
+    let path = null;
+    let describe = null;
+
+    // Parse kind, path (both required), and optional describe
+    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 === 'kind') {
+          kind = this.parseStringBlock('kind');
+        } else if (identifier === 'path') {
+          path = this.parseStringBlock('path');
+        } else if (identifier === 'describe') {
+          describe = this.parseDescribe();
+        } 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 document block at ${this.file}:${startToken.span.start.line}`);
+    }
+    if (!path) {
+      throw new Error(`Missing 'path' field in document block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    return {
+      kind: 'document',
+      title: title || undefined,
+      documentKind: kind,
+      path,
+      describe,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses a named document block: document <Name> { ... }
+   * @returns {NamedDocumentBlock}
+   */
+  parseNamedDocument() {
+    const startToken = this.expect('IDENTIFIER', 'document');
+    const nameToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    let kind = null;
+    let path = null;
+    let describe = null;
+
+    // Parse kind, path (both required), and optional describe (same as parseDocument, but no title)
+    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 === 'kind') {
+          kind = this.parseStringBlock('kind');
+        } else if (identifier === 'path') {
+          path = this.parseStringBlock('path');
+        } else if (identifier === 'describe') {
+          describe = this.parseDescribe();
+        } 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 named document block at ${this.file}:${startToken.span.start.line}`);
+    }
+    if (!path) {
+      throw new Error(`Missing 'path' field in named document block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    return {
+      kind: 'named-document',
+      name: nameToken.value,
+      documentKind: kind,
+      path,
+      describe,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {SceneDecl}
+   */
+  parseScene() {
+    const startToken = this.expect('KEYWORD', 'scene');
+    const nameToken = this.expect('IDENTIFIER');
+    this.expect('KEYWORD', 'for');
+    // Target can be a dot-separated path like "Amaranthine.Items"
+    // Parse as: IDENTIFIER (DOT IDENTIFIER)*
+    const targetParts = [];
+    targetParts.push(this.expect('IDENTIFIER').value);
+    
+    // Consume dot-separated identifiers
+    while (this.match('DOT')) {
+      this.expect('DOT'); // consume dot
+      if (this.match('IDENTIFIER')) {
+        targetParts.push(this.expect('IDENTIFIER').value);
+      } else {
+        break;
+      }
+    }
+    
+    const target = targetParts.join('.');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseSceneBody();
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'scene',
+      name: nameToken.value,
+      target,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses scene body blocks
+   * @returns {Array<UsingBlock | ActorDecl | DescribeBlock | UnknownBlock>}
+   */
+  parseSceneBody() {
+    const body = [];
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+        const keyword = this.peek()?.value;
+        if (!keyword) break;
+
+        if (keyword === 'using' && this.match('KEYWORD')) {
+          body.push(this.parseUsing());
+        } else if (keyword === 'actor' && this.match('KEYWORD')) {
+          body.push(this.parseActor());
+        } else if (keyword === 'describe' && this.match('KEYWORD')) {
+          body.push(this.parseDescribe());
+        } else {
+          // Unknown keyword/identifier followed by brace - parse as UnknownBlock
+          const nextPos = this.pos + 1;
+          if (nextPos < this.tokens.length && this.tokens[nextPos].type === 'LBRACE') {
+            body.push(this.parseUnknownBlock());
+          } else {
+            // Not a block, just skip this token (tolerant parsing)
+            this.advance();
+          }
+        }
+      } else {
+        // Unexpected token in body - skip (tolerant)
+        this.advance();
+      }
+    }
+
+    return body;
+  }
+
+  /**
+   * @returns {UsingBlock}
+   */
+  parseUsing() {
+    const startToken = this.expect('KEYWORD', 'using');
+    const lbrace = this.expect('LBRACE');
+    const identifiers = [];
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('IDENTIFIER')) {
+        identifiers.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)
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'using',
+      identifiers,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {ActorDecl}
+   */
+  parseActor() {
+    const startToken = this.expect('KEYWORD', 'actor');
+    const nameToken = this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+    const body = this.parseActorBody();
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'actor',
+      name: nameToken.value,
+      body,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses actor body blocks
+   * @returns {Array<DescribeBlock | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | UnknownBlock>}
+   */
+  parseActorBody() {
+    const body = [];
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('KEYWORD') || this.match('IDENTIFIER')) {
+        const keyword = this.peek()?.value;
+        if (!keyword) break;
+
+        if (keyword === 'describe' && this.match('KEYWORD')) {
+          body.push(this.parseDescribe());
+        } else if (keyword === 'type' && this.match('KEYWORD')) {
+          body.push(this.parseTypeBlock());
+        } else if (keyword === 'identity' && this.match('KEYWORD')) {
+          body.push(this.parseIdentityBlock());
+        } else if (keyword === 'file' && (this.match('KEYWORD') || this.match('IDENTIFIER'))) {
+          body.push(this.parseSourceBlock('file'));
+        } else if (keyword === 'sqlite' && (this.match('KEYWORD') || this.match('IDENTIFIER'))) {
+          body.push(this.parseSourceBlock('sqlite'));
+        } else if (keyword === 'mysql' && (this.match('KEYWORD') || this.match('IDENTIFIER'))) {
+          body.push(this.parseSourceBlock('mysql'));
+        } else if (keyword === 'transforms' && this.match('KEYWORD')) {
+          body.push(this.parseTransformsBlock());
+        } else {
+          // Unknown keyword/identifier followed by brace - parse as UnknownBlock
+          const nextPos = this.pos + 1;
+          if (nextPos < this.tokens.length && this.tokens[nextPos].type === 'LBRACE') {
+            body.push(this.parseUnknownBlock());
+          } else {
+            // Not a block, just skip this token (tolerant parsing)
+            this.advance();
+          }
+        }
+      } else {
+        // Unexpected token in body - skip (tolerant)
+        this.advance();
+      }
+    }
+
+    return body;
+  }
+
+  /**
+   * @returns {TypeBlock}
+   */
+  parseTypeBlock() {
+    const startToken = this.expect('KEYWORD', 'type');
+    const lbrace = this.expect('LBRACE');
+
+    // Track brace depth to find matching closing brace
+    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 type block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'type',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {IdentityBlock}
+   */
+  parseIdentityBlock() {
+    const startToken = this.expect('KEYWORD', 'identity');
+    const lbrace = this.expect('LBRACE');
+
+    // Track brace depth to find matching closing brace
+    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 identity block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'identity',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @param {string} sourceType - 'file', 'sqlite', or 'mysql'
+   * @returns {SourceBlock}
+   */
+  parseSourceBlock(sourceType) {
+    const startToken = this.match('KEYWORD') ? this.expect('KEYWORD', sourceType) : this.expect('IDENTIFIER');
+    const lbrace = this.expect('LBRACE');
+
+    // Track brace depth to find matching closing brace
+    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 ${sourceType} block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'source',
+      sourceType,
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {TransformsBlock}
+   */
+  parseTransformsBlock() {
+    const startToken = this.expect('KEYWORD', 'transforms');
+    const lbrace = this.expect('LBRACE');
+    const transforms = [];
+
+    while (!this.match('RBRACE') && !this.match('EOF')) {
+      if (this.match('KEYWORD') && this.peek()?.value === 'transform') {
+        transforms.push(this.parseTransformBlock());
+      } else {
+        // Skip non-transform blocks (tolerant parsing)
+        this.advance();
+      }
+    }
+
+    const rbrace = this.expect('RBRACE');
+
+    return {
+      kind: 'transforms',
+      transforms,
+      source: {
+        file: this.file,
+        start: startToken.span.start,
+        end: rbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * @returns {TransformBlock}
+   */
+  parseTransformBlock() {
+    const startToken = this.expect('KEYWORD', 'transform');
+    const lbrace = this.expect('LBRACE');
+
+    // Track brace depth to find matching closing brace
+    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 transform block at ${this.file}:${startToken.span.start.line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      kind: 'transform',
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+
+  /**
+   * Parses an unknown block with balanced brace scanning
+   * @returns {UnknownBlock}
+   */
+  parseUnknownBlock() {
+    // Can be either KEYWORD or IDENTIFIER
+    const token = this.peek();
+    if (!token || (token.type !== 'KEYWORD' && token.type !== 'IDENTIFIER')) {
+      throw new Error(
+        `Expected keyword or identifier for unknown block at ${this.file}:${token?.span.start.line || '?'}`,
+      );
+    }
+    const keywordToken = this.advance();
+    const lbrace = this.expect('LBRACE');
+
+    // Track brace depth to find matching closing brace
+    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) {
+      const keywordValue = keywordToken ? keywordToken.value : 'unknown';
+      const line = keywordToken ? keywordToken.span.start.line : '?';
+      throw new Error(`Unclosed block "${keywordValue}" at ${this.file}:${line}`);
+    }
+
+    // Extract raw content from source text
+    const rawContent = this.sourceText.substring(startOffset, endOffset).trim();
+
+    return {
+      keyword: keywordToken.value,
+      raw: rawContent,
+      source: {
+        file: this.file,
+        start: lbrace.span.end,
+        end: endToken ? endToken.span.start : lbrace.span.end,
+      },
+    };
+  }
+}
+