docs(parser): numeric -t/--type filter silently matches by grammar-unstable kind_id

[dekobon]

Summary

Parser::filters silently reinterprets any -t/--type value that parses
as a u16 as a raw tree-sitter kind_id, but this behaviour is neither
explained at the call site nor documented for CLI users.

Location

• src/parser.rs:190-201

Evidence

_ => {
    if let Ok(n) = f.parse::<u16>() {
        res.push(Box::new(move |node: &Node| -> bool { node.kind_id() == n }));
    } else {
        // Exact match on `node.kind()` — the CLI documents
        // `find <NODE>` / `count <NODE_TYPE>` as searching
        // for a specific node type, not a substring (see
        // big-code-analysis-book/src/commands/nodes.md and
        // issue #293).
        let f = f.to_owned();
        res.push(Box::new(move |node: &Node| -> bool { node.kind() == f }));
    }
}

The inline comment documents only the string (exact-kind()) branch and
its #293 history. The numeric branch — which matches by integer kind_id
instead of by node-type name — has no rationale comment, and the user-facing
docs (big-code-analysis-book/src/commands/nodes.md) describe -t/--type
solely as "the node type to match", with no mention that a numeric argument
is interpreted as a kind_id.

Consequences:

• A user who passes a numeric -t value gets kind_id matching with no
  indication this differs from name matching. kind_id values are not
  stable across grammar versions, so a value that matched one node type
  today may match a different one after a grammar bump — a silent
  behaviour change for any script that relied on a numeric filter.
• -t 0 matches the tree-sitter end/error sentinel rather than producing
  an empty result, which is surprising and undocumented.

Expected Behavior

The numeric kind_id matching path should carry an inline rationale comment
(mirroring the documented string branch), and the nodes.md docs should
state that a numeric -t/--type value is treated as a raw kind_id (and
warn that kind_id values are grammar-version-specific).

Actual Behavior

The numeric kind_id path is undocumented both in-source and in user docs;
the only documented filter semantics are the keyword set and exact kind()
name matching.

Impact

CLI users of find/count with numeric type arguments; maintainers reading
filters who must reverse-engineer why numeric input is special-cased.
Low severity — no incorrect computation, but a documentation/contract gap
around grammar-version-unstable kind_id values.

---

Resolution

Fixed in 7a41184: numeric -t/--type kind_id behavior documented in parser.rs and nodes.md as grammar-version-unstable.

[dekobon]

General Plan for Fix

Root Cause

Parser::filters was extended with a numeric kind_id fast-path as a
power-user convenience, but the rationale was never recorded inline and the
user-facing nodes.md docs were not updated to describe it. kind_id
values are assigned by tree-sitter at grammar-build time and are not stable
across grammar version bumps, so the implicit contract ("numeric means
kind_id") is both undocumented and version-fragile.

Implementation Steps

1. Add an inline rationale comment above the if let Ok(n) = f.parse::<u16>()
   branch in src/parser.rs, mirroring the existing string-branch comment:
   explain that a numeric filter is matched against node.kind_id() and that
   kind_id values are grammar-version-specific (so name filters are
   preferred for stability).
2. Update big-code-analysis-book/src/commands/nodes.md -t/--type
   description to note that a numeric argument is interpreted as a raw
   tree-sitter kind_id rather than a node-type name, with a one-line
   caution that kind_id values can change on a grammar bump.

Tests to Add/Update

• Add a parser.rs unit test (alongside the existing fix(parser): make count/find node filters exact matches #293 tests) asserting
  that a numeric filter matches by kind_id for a known Python node kind,
  pinning the documented behaviour so a future refactor cannot silently drop
  the numeric branch.

Verification

• cargo test -p big-code-analysis passes
• cargo clippy -p big-code-analysis clean
• make rumdl / markdown lint clean for nodes.md
• Manual verification: bca count -t <known_kind_id> file.py matches the
  same nodes as the corresponding -t <kind_name> invocation

[dekobon]

Fixed in 7a41184. (a) Added a rationale comment at the numeric branch in Parser::filters (parser.rs) explaining that a numeric -t/--type value matches by raw tree-sitter kind_id, that kind_id is grammar-version-unstable (an index into the symbol table; -t 0 is the end/ERROR sentinel), and that it is an inspection escape hatch. (b) Updated big-code-analysis-book/src/commands/nodes.md to document numeric vs string -t/--type semantics in the existing prose style. Markdown lint clean.

[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.