# Node Naming Conventions

Tree-sitter nodes describe ZuzuScript concrete syntax. They should stay useful
for editors, query files, and language-server indexing without copying any one
runtime's AST class names.

## General Rules

- Prefer language concepts over implementation terms: `class_declaration`,
  `trait_declaration`, `pair_list_literal`, and `assignment_statement`.
- Use `_expression`, `_statement`, `_declaration`, and `_literal` as hidden
  supertypes for query convenience.
- Use named nodes when editor queries need a stable target. Keep punctuation and
  most keywords anonymous unless a token needs context-sensitive highlighting,
  such as `set_close`.
- Use `field()` names for roles within a construct: `name`, `type`,
  `condition`, `body`, `value`, `left`, `operator`, and `right`.
- Avoid names that imply semantics the parser does not validate. For example,
  compact class syntax is still `class_declaration`, not predeclaration.

## ZuzuScript-Specific Choices

- `class_declaration` covers both block classes and compact class declarations:
  `class Foo;`, `class Foo with Bar;`, and `class Foo extends Bar but Baz;`.
- `trait_declaration` is the trait syntax supported by ZuzuScript. Do not add a
  separate role node unless the language gains roles as distinct syntax.
- `while_statement` has no `else` alternative. `if_statement` and
  `for_statement` may have `else` blocks.
- `pair_list_literal` uses `{{ ... }}` delimiters and contains `pair_entry`
  nodes.
- `bag_literal` uses `<<< ... >>>` delimiters.
- `set_literal` uses `<< ... >>`, `« ... »`, or `∅`. The `>>` close delimiter is
  a named `set_close` token so it can be distinguished from the shift operator.
- `template_string` contains `template_fragment` and `template_interpolation`
  children. Interpolation values are normal ZuzuScript expressions so shared
  highlight queries apply inside `${ ... }`.
- POD is represented as `pod_block`, including POD that runs to end of file.

## Query Stability

Queries should target these stable nodes and fields rather than depending on
incidental parse shape. If a new grammar rule is added, update the query files
and corpus or highlight fixtures in the same change when the node is visible to
editors.
