Parser: attach comments to ClassDefinition, MethodDefinition, StateDeclaration (BT-975)

[jamesc]

Summary

Implements Phase 2, Issue 3 of ADR 0044 (Comments as First-Class AST Nodes).

• Adds collect_comment_attachment() to the parser that collects // and /* */ trivia into CommentAttachment.leading, skipping /// doc comments
• Wires comment collection at all parse sites: parse_class_definition, parse_method_definition, parse_state_declaration, parse_classvar_declaration
• Wires collect_doc_comment() for StateDeclaration (previously missing)
• Adds 5 focused parser tests covering all acceptance criteria
• Updates 20 parser snapshots to reflect populated comments fields

Linear: https://linear.app/beamtalk/issue/BT-975

🤖 Generated with Claude Code

Summary by CodeRabbit

• Refactor

  • Enhanced source code parser to properly collect and associate comments with code elements (classes, methods, and state declarations), ensuring improved documentation preservation during analysis.

• Tests

  • Added test coverage validating comment attachment and documentation handling across multiple code element types.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between afab809 and ecb4342.

⛔ Files ignored due to path filters (20)

• test-package-compiler/tests/snapshots/compiler_tests__abstract_class_spawn_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__class_definition_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__class_methods_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__empty_method_body_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__error_message_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__intrinsic_keyword_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__method_lookup_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__sealed_class_violation_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__sealed_method_override_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__stdlib_class_dictionary_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__stdlib_class_list_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__stdlib_class_set_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__stdlib_class_tuple_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__typed_class_warnings_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__typed_methods_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__typed_value_type_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__value_type_multi_expr_method_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__value_type_param_collision_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__workspace_binding_cascade_parser.snap is excluded by !**/*.snap
• test-package-compiler/tests/snapshots/compiler_tests__workspace_binding_send_parser.snap is excluded by !**/*.snap

📒 Files selected for processing (2)

• crates/beamtalk-core/src/source_analysis/parser/declarations.rs
• crates/beamtalk-core/src/source_analysis/parser/mod.rs

---

📝 Walkthrough

Walkthrough

This PR adds support for attaching regular comments to AST nodes by introducing a comments field to ClassDefinition, MethodDefinition, and StateDeclaration structs, implementing a new collect_comment_attachment() parser method to extract leading comments from token trivia, and updating parser logic to assign collected comments during parsing of these node types.

Changes

Cohort / File(s)	Summary
AST Structure Updates crates/beamtalk-core/src/ast.rs	Added public comments field to ClassDefinition, MethodDefinition, and StateDeclaration structs to store comment attachments.
Parser Method & Tests crates/beamtalk-core/src/source_analysis/parser/mod.rs	Added CommentAttachment import; introduced collect_comment_attachment() method that extracts leading line/block comments from token trivia; added five tests validating comment attachment behavior for classes, methods, and state declarations.
Parser Comment Assignment crates/beamtalk-core/src/source_analysis/parser/declarations.rs	Updated comment collection and assignment during parsing of class definitions, state declarations, class variables, and methods; removed CommentAttachment from public imports (now handled at module level); assigns collected comments and doc comments to respective AST node fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• docs: ADR 0044 - Comments as First-Class AST Nodes #1000: Implements the ADR design by adding CommentAttachment fields to AST nodes and foundational parser logic for comment collection.
• Add CommentAttachment/ExpressionStatement types and comment fields to AST (BT-973) #1008: Introduces CommentAttachment type definition and doc_comment field support that this PR builds upon for full comment attachment functionality.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main change: adding comment attachment to three AST node types (ClassDefinition, MethodDefinition, StateDeclaration), and references the associated ticket (BT-975).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch worktree-BT-975

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}