refactor(output): normalize AstNode dump key casing; name the Span tuple

[dekobon]

Decided (2026-06-05): AST keys → snake_case type/value/span/field_name/children; Span → flat {start_row,start_col,end_row,end_col} named struct (still Option). See the resolved-decisions comment.

Summary

The bca dump/AST JSON output uses PascalCase keys while every other
serialized type in the library is lowercase, and the AST span is an unnamed
4-tuple.

Evidence

• AstNode hand-serializes Type / TextValue / Span / FieldName /
  Children (src/ast.rs, the impl Serialize), and renames the value field
  to TextValue. Compare SpaceKind's #[serde(rename_all = "lowercase")]
  (src/spaces.rs) and the lowercase CodeMetrics keys.
• pub type Span = Option<(usize, usize, usize, usize)> (src/ast.rs:26) — a
  bare tuple alias as public API; the four positions (start_row, start_col,
  end_row, end_col) have no names on the wire.

Why 2.0-worthy

The #510/#511 horizon normalizes metric output keys but does not cover the AST
dump keys, so without action the AST dump stays a permanent casing inconsistency.
Renaming serialized keys and changing Span to a named struct are both breaking
→ 2.0.

Proposed change

At 2.0: bring AstNode keys into the same lowercase scheme as the rest of the
output (type/value/span/field_name/children), and promote Span to a
named struct (Span { start_row, start_col, end_row, end_col }) so the AST dump
is self-documenting.

Acceptance

• bca dump -O json keys match the rest of the serialized surface's casing.
• Span serializes as a named object; 2.0 CHANGELOG records the shape change.

Part of the pre-2.0 review (#505).

Resolution

Implemented on branch fix/issue-535 (commit ab030f87).

• AST dump keys are now snake_case: type / value / span /
  field_name / children. TextValue → value; the hand-written
  serialize_struct("Node", ...) impl was replaced with
  #[derive(Serialize)] + #[serde(rename_all = "snake_case")].
• Span is now a named struct Span { start_row, start_col, end_row, end_col }, still wrapped in Option. Field order maps 1:1 to the
  former tuple (spos_row+1, spos_column+1, epos_row+1, epos_column+1);
  values are unchanged (1-based tree-sitter rows/cols). Span derives
  Deserialize for wire round-trip parity.
• Updated call sites: src/alterator.rs::get_text_span, the web
  /ast integration tests, the book AST-traversal example test, and
  the book doc page.
• (breaking) — serialized AST shape; lands with the 2.0 schema
  cluster. CHANGELOG entry is consolidated by the orchestrator.

[dekobon]

Resolved decisions (2026-06-05)

AST dump keys → snake_case type / value / span / field_name /
children. Replaces the PascalCase Type/TextValue/Span/FieldName/
Children; TextValue→value (matches the AstNode.value field), type
keeps tree-sitter node-type terminology. Drop the hand-written PascalCase
serialize_struct("Node", …) impl in favour of the lowercase scheme so the AST
dump matches the rest of the serialized surface (and the #510 normalization).

Span → flat named struct serialized as {start_row, start_col, end_row, end_col}. Replaces pub type Span = Option<(usize,usize,usize,usize)> with a
named struct Span { start_row, start_col, end_row, end_col } (still wrapped in
Option — None for root/anonymous nodes, omitted/null as today). The four
fields preserve the current numeric values (tree-sitter start/end Point
row+column); only their names/shape change. Verify the existing tuple order at
implementation and map 1:1.

2.0-gated/breaking (serialized AST shape). Lands with the #510/#530/#532 schema
cluster; if #532's DTO layer covers the AST dump, fold the AstNode shape into it.

[dekobon]

Fixed on fix/issue-535 (commit ab030f87).

Root cause. The serialized AST shape was an artifact of a
hand-written Serialize impl that emitted PascalCase keys
(Type/TextValue/Span/FieldName/Children) and serialized
the span as a bare 4-tuple, neither of which match the rest of the
crate's snake_case JSON conventions or self-describe their fields.

Changes.

• Dropped the hand-written serialize_struct("Node", ...) impl;
  AstNode now derives Serialize with
  #[serde(rename_all = "snake_case")], yielding keys type,
  value, span, field_name, children. (r#type serializes as
  type via serde's raw-identifier handling.)
• Replaced pub type Span = Option<(usize, usize, usize, usize)>
  with a named struct Span { start_row, start_col, end_row, end_col }
  (Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize), still
  carried as Option<Span> on AstNode. Verified the construction
  site in get_text_span: the old tuple was
  (spos_row+1, spos_column+1, epos_row+1, epos_column+1), so the new
  fields map 1:1 with identical values.

Languages affected. n/a (language-agnostic AST plumbing; verified
via Rust, C, and JS fixtures).

Tests.

• src/ast.rs: added serialized_json_uses_snake_case_keys (asserts
  the five snake_case keys present, all four PascalCase keys absent),
  span_serializes_as_named_object (anchored on the exact span
  {1,1,1,9} for fn f(){}), and span_round_trips_through_serde.
  Updated the existing field_name-key regression test.
• big-code-analysis-web /ast integration tests rewritten to the
  named-span/snake_case shape (C and JS), plus the two
  content-type-variant tests' ["root"]["type"] accessors.
• tests/book_ast_traversal_examples.rs: "Type" → "type".
• Book doc page updated. No insta/submodule snapshots moved.
• cargo fmt --check, clippy -D warnings (both feature flavours),
  and cargo test --workspace --all-features all green.

(breaking) — serialized AST shape change, deferred to the 2.0
schema cluster. CHANGELOG entry handled by the batch orchestrator.