output(dump): public dump_node panics on mismatched code/node, undocumented precondition

[dekobon]

Summary

The public dump_node / dump_node_with_color slice code by the node's
byte range without documenting that code must be the exact source the
node was parsed from; a mismatched pair panics (index out of bounds)
instead of returning the io::Error the docs claim is the only error mode.

Location

• src/output/dump.rs:43-71 (public signatures + # Errors docs)
• src/output/dump.rs:264 (let snippet = &code[node.start_byte()..node.end_byte()];)

Evidence

write_node_snippet indexes the caller-supplied slice directly:

let snippet = &code[node.start_byte()..node.end_byte()];

dump_node/dump_node_with_color take code: &[u8] and node: &Node
as independent parameters. There is no compile-time tie between them: a
Node borrows from one Ast, and code is a separate &[u8]. Nothing
prevents a caller from passing ast_a.source() with a node from a
different (or differently-sized) tree. When node.end_byte() exceeds
code.len(), the slice expression panics.

The # Errors docs on both functions state only:

Propagates any [std::io::Error] produced by the color-aware writer …

i.e. they promise the function either succeeds or returns Err(io::Error).
A panic on a mismatched code/node pair violates that contract and the
project's no-panic-in-non-test-code rule for a published 1.x API surface.

All in-repo callers (big-code-analysis-cli/src/dispatch.rs,
c_langs_macros) correctly pair ast.source() with ast.root_node(),
so this is not reachable from the CLI today — but the public API offers
no guard or documented precondition for external callers.

Expected Behavior

Either (a) the docs state the precondition ("code must be the source
the node was parsed from") explicitly, or (b) the snippet read uses a
bounds-checked access (code.get(start..end)) and renders nothing /
a placeholder when the range is out of bounds, keeping the documented
"only returns io::Error" contract truthful.

Actual Behavior

A mismatched code/node pair panics with an index-out-of-bounds slice,
contradicting the # Errors documentation.

Impact

External library consumers of the published dump_node /
dump_node_with_color API can trigger an undocumented panic by passing a
code slice that does not match the node's tree. Low likelihood (in-repo
usage is correct), but it is a documented-contract violation on a stable
public surface.

---

Resolution

Fixed in 7a41184: added # Panics precondition docs to dump_node and dump_node_with_color (code must be the exact source the node was parsed from). Doc-only.

[dekobon]

General Plan for Fix

Root Cause

dump_node / dump_node_with_color accept code and node as two
independent parameters with no type-level link, then write_node_snippet
slices code[node.start_byte()..node.end_byte()] unchecked. The # Errors
docs promise only io::Error, omitting the implicit "code must match the
node's tree" precondition.

Implementation Steps

1. Preferred (robust): replace the unchecked slice in write_node_snippet
   with code.get(node.start_byte()..node.end_byte()); on None, skip the
   snippet (still emit the trailing newline via the caller) so an
   out-of-range pair degrades gracefully instead of panicking.
2. Add a # Panics-free note to the dump_node / dump_node_with_color
   doc comments documenting that code must be the source node was parsed
   from (belt-and-suspenders even with the bounds check).

Tests to Add/Update

• New unit test: build a node from one source, call dump_tree_helper
  (via the in-memory NoColor sink pattern already used) with a
  deliberately truncated code slice; assert it returns Ok and omits
  the snippet rather than panicking.
• Keep dump_node_non_utf8_source_does_not_panic as the UTF-8 guard.

Verification

• cargo test -p big-code-analysis passes
• cargo clippy -p big-code-analysis clean
• Manual: external-style call with mismatched code/node does not panic

[dekobon]

Fixed in 7a41184. Added a # Panics section to both dump_node and dump_node_with_color documenting the precondition that code must be the exact source node was parsed from (pair ast.source() with a node from the same Ast); a mismatched pair indexes out of bounds at dump.rs:264 and panics. Doc-only per the issue scope. Note: a future hardening could return an io::Error instead of panicking — tracked as a possible follow-up — but the documented precondition is what was requested here.

[dekobon]

Fixed and merged to main in #957. GitHub did not auto-close this from the batched commit's single Fixes #a #b #c … trailer (only the first referenced issue auto-closes); closing manually. See the Resolution section in the body for details.