Skip to main content

big_code_analysis_ast/
checker.rs

1// Per-language metric and AST modules deliberately consume the macro-
2// generated tree-sitter token enums via `use crate::*` and `use Foo::*`
3// inside match expressions — explicit imports would list dozens of
4// variants per arm and obscure the per-language token sets that are the
5// point of these files. Allowed at the module level rather than per
6// function so the per-language impl blocks stay readable.
7#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]
8
9//! The [`Checker`] classification predicates and their per-language impls.
10
11use std::sync::OnceLock;
12
13use aho_corasick::AhoCorasick;
14use regex::bytes::Regex;
15
16use crate::cfg_predicate::attribute_marks_test as rust_attribute_marks_test;
17use crate::lang_helpers::{DocBinding, KeptDocs};
18use crate::*;
19
20static AHO_CORASICK: OnceLock<AhoCorasick> = OnceLock::new();
21static RE: OnceLock<Regex> = OnceLock::new();
22
23// The JS-family function / closure split — the binding-site walk that
24// tells `const f = function () {}` from `run(function () {})`, and the
25// one clause in which the arrow form must differ (#1188), plus the
26// generator reading (#1186) — lives on the rows since #1696:
27// `roles/js_family.rs`'s `js_family_binding_gates!` emits the walk per
28// dialect, and each dialect's `FuncOpener` / `Closure` rows read it.
29
30// The `Comment` and `DocComment` rows of a language whose tool reads a
31// doc comment inside a function body as documentation (#1597, #1699):
32// `is_comment` from the two rows' kind tables, `is_doc_comment` from the
33// `DocComment` row under its gate, and the body flag. Why the tool reads
34// one there — Doxygen's in-body description, JSDoc's inner symbols,
35// perldoc's POD anywhere — is the one line above each invocation.
36macro_rules! impl_doc_comment_rows_in_bodies {
37    ($roles:ident) => {
38        const DOC_COMMENTS_IN_FUNCTION_BODIES: bool = true;
39
40        impl_comment_from_rows!($roles);
41        impl_doc_comment_from_row!($roles);
42    };
43}
44
45// The `Call` and `StringLit` rows of a language's role table, read as
46// the four `Checker` call / string predicates (#1698): one invocation
47// per row, naming the row module and the two predicates it answers,
48// since the bypass gate reads a row-forwarding macro as binding one
49// kind and handing it to one row. The `_with_code` spellings read the
50// rows under their gates — Perl's bareword call, the Tcl family's
51// braced script body — and are what `find` / `count` and the dump ask.
52// The byte-less spellings are each row's kind table, gates aside
53// (`lists_kind`): a Tcl script body is a string to `is_string` and not
54// to `is_string_with_code`, as before the rows, and
55// `tcl_script_body_is_a_string_only_to_the_byteless_spelling` pins that
56// the two disagree — a known-empty chain would not do here, since the
57// Tcl gate reads "no parent" as a script body. Per-row rationale —
58// which alias is hidden, which keyword alias is excluded — sits on the
59// rows (`docs/development/formatting.md`).
60macro_rules! impl_row_predicates {
61    ($roles:ident, $row:ident, $byteless:ident, $with_code:ident) => {
62        fn $byteless(node: &Node) -> bool {
63            let kind = node.kind_id();
64            $crate::roles::$roles::$row::lists_kind(kind)
65        }
66
67        fn $with_code<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
68            $crate::roles::$roles::$row::owns(node, code, ancestors)
69        }
70    };
71}
72
73// Emits a `Checker::is_comment` that reads the language's `Comment` and
74// `DocComment` rows as one kind table (#1699). The predicate takes no
75// bytes and no chain, so it reads `lists_kind` — each row's owners,
76// gates aside — rather than `owns`: a comment the documentation gate
77// rejects (an empty `/**/`, a POD `=begin comment` region) is still a
78// comment, and a kind that is documentation *by kind* (Groovy's
79// `groovydoc_comment`, Perl's `pod_statement`) sits only on the
80// `DocComment` row, so the union is what makes `is_doc_comment ⇒
81// is_comment` structural. Per-language rationale — which kinds are
82// comments and why a documentation row is absent — sits on the rows.
83macro_rules! impl_comment_from_rows {
84    ($roles:ident) => {
85        fn is_comment(node: &Node) -> bool {
86            let kind = node.kind_id();
87            $crate::roles::$roles::comment::lists_kind(kind)
88                || $crate::roles::$roles::doc_comment::lists_kind(kind)
89        }
90    };
91}
92
93// Emits a byte-only `Checker` predicate — `is_doc_comment` from the
94// `DocComment` row, `is_doc_run_directive` from `DocRunDirective` —
95// that reads the row under its gate (#1699). The predicate carries the
96// bytes a `text_gated_by` marker test reads and no chain, so the row is
97// asked with a *known-empty* chain: exact while every gate of the row
98// takes no chain, which the build asserts through the row's
99// `CHAIN_GATED` (#1793) — a gate of these rows is declared `no_chain`
100// and has no chain parameter — and which `roles/doc_tests/mod.rs` pins
101// behaviourally by reading each predicate beside its row asked with
102// the real chain, on a nested fixture per language.
103// `Ancestors::unknown()` would instead climb `Node::parent` at
104// `O(depth)` and mask a future chain-reading gate by answering it.
105// Per-language rationale — which marker the tool reads, which kinds
106// can carry one — sits on the row.
107macro_rules! impl_byte_gated_row_predicate {
108    ($roles:ident, $row:ident, $method:ident) => {
109        fn $method(node: &Node, code: &[u8]) -> bool {
110            const _: () = assert!(
111                !$crate::roles::$roles::$row::CHAIN_GATED,
112                "the row reads the chain; the byte-only predicate cannot forward a known-empty one"
113            );
114            $crate::roles::$roles::$row::owns(node, code, Ancestors::known(&[]))
115        }
116    };
117}
118
119// The byte-less `is_func_space` of a language whose space tree is its
120// `FuncOpener` and `Container` rows (#1696): forwards with no bytes and
121// a known-empty chain, which is exact only while neither row reads
122// either — the build asserts both flags of both rows (#1793). The
123// `opener_gated` form is for a language whose opener row reads the
124// chain or the bytes by design, so that only the `Container` row is
125// asserted — and that the opener *is* gated, so the form cannot be
126// taken by a language whose rows the plain form would check: the
127// gated opener answers its rootless verdict under the known-empty
128// chain, a disagreement the language pins at runtime by value —
129// `false` for a Java or Groovy record's header (#1842), `true` for a
130// Ruby lambda's body block (`ruby_byte_less_spellings_stay_the_kind_table`).
131// C#'s opener is chain-gated too and keeps a hand-written forward with
132// a stricter pin since #1828
133// (`csharp_byte_less_spellings_omit_the_primary_constructor`); Elixir
134// hand-writes the byte-less one as its kind table. The trait gives the
135// spelling no default, so no language takes the forward without one of
136// these (#1863). Per-language rationale — which rows, what the gated
137// one reads — sits above the invocation.
138macro_rules! impl_byte_less_func_space {
139    ($roles:ident) => {
140        fn is_func_space(node: &Node) -> bool {
141            const _: () = assert!(
142                !$crate::roles::$roles::func_opener::TEXT_GATED
143                    && !$crate::roles::$roles::func_opener::CHAIN_GATED
144                    && !$crate::roles::$roles::container::TEXT_GATED
145                    && !$crate::roles::$roles::container::CHAIN_GATED,
146                "a space-opening row reads bytes or the chain; the byte-less spelling cannot forward with none"
147            );
148            Self::is_func_space_with_code(node, &[], Ancestors::known(&[]))
149        }
150    };
151    ($roles:ident, opener_gated) => {
152        fn is_func_space(node: &Node) -> bool {
153            const _: () = assert!(
154                $crate::roles::$roles::func_opener::TEXT_GATED
155                    || $crate::roles::$roles::func_opener::CHAIN_GATED,
156                "an ungated opener row takes the plain arm"
157            );
158            const _: () = assert!(
159                !$crate::roles::$roles::container::TEXT_GATED
160                    && !$crate::roles::$roles::container::CHAIN_GATED,
161                "the `Container` row reads bytes or the chain; the byte-less spelling cannot forward with none"
162            );
163            Self::is_func_space_with_code(node, &[], Ancestors::known(&[]))
164        }
165    };
166}
167
168// The two predicates `impl_byte_gated_row_predicate!` emits, by name.
169macro_rules! impl_doc_comment_from_row {
170    ($roles:ident) => {
171        impl_byte_gated_row_predicate!($roles, doc_comment, is_doc_comment);
172    };
173}
174macro_rules! impl_doc_run_directive_from_row {
175    ($roles:ident) => {
176        impl_byte_gated_row_predicate!($roles, doc_run_directive, is_doc_run_directive);
177    };
178}
179
180// The `DocBodyResidual` row of a language, read inside its hand-written
181// `holds_doc_comment_in_body` for the kinds it names beyond the
182// callables and closures (#1699): asked with the bytes and `ancestors`,
183// the chain the trait hands in (the ancestor's own), as the callable
184// test beside it is (#1863). An expression rather than an emitted
185// method, so the per-language branch order and the body-child test stay
186// visible in `checker/<lang>.rs`.
187macro_rules! doc_body_residual_kind {
188    ($roles:ident, $ancestor:expr, $code:expr, $ancestors:expr) => {
189        $crate::roles::$roles::doc_body_residual::owns($ancestor, $code, $ancestors)
190    };
191}
192
193// Emits a `Checker::is_doc_target` that reads the language's `DocTarget`
194// row with the node's own chain (#1699) — for the languages whose
195// targets are the row alone. Where context the row cannot see composes
196// with it (a wrapper's parent, a scope fold, a sentinel), the Checker
197// writes `is_doc_target` by hand beside a named context fn.
198macro_rules! impl_doc_target_from_row {
199    ($roles:ident) => {
200        fn is_doc_target<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
201            $crate::roles::$roles::doc_target::owns(node, code, ancestors)
202        }
203    };
204}
205
206// Emits a `Checker::is_else_if` that forwards to the language's `ElseIf`
207// row (#1697): `roles::<lang>::else_if::owns` under a known-empty code
208// slice, which is exact because no `ElseIf` gate reads bytes — the
209// parent-clause, previous-sibling and dedicated-clause strategies all
210// read the caller's chain (`roles/control_flow.rs`). Python does not use
211// it: its row also owns the `elif_clause`, and the Checker answers
212// `Branch ∧ ElseIf` so that clause stays `false` as every caller has had
213// it. Per-language rationale — which strategy the row spells and why —
214// sits above each invocation (`docs/development/formatting.md`).
215macro_rules! impl_else_if_from_row {
216    ($roles:ident) => {
217        #[inline]
218        fn is_else_if<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
219            // The empty slice is exact only while no gate reads bytes;
220            // a `text_gated_by` owner on this row would make the
221            // forward silently wrong, so the build says so.
222            const _: () = assert!(
223                !$crate::roles::$roles::else_if::TEXT_GATED,
224                "the `ElseIf` row reads bytes; `is_else_if` cannot forward with `&[]`"
225            );
226            $crate::roles::$roles::else_if::owns(node, &[], ancestors)
227        }
228    };
229}
230
231#[inline]
232fn get_aho_corasick_match(code: &[u8]) -> bool {
233    AHO_CORASICK
234        .get_or_init(|| {
235            AhoCorasick::new(vec![b"<div rustbindgen"])
236                .expect("constant single-needle AhoCorasick automaton always compiles")
237        })
238        .is_match(code)
239}
240
241/// A [`Checker::should_skip_subtree`] verdict, plus the following
242/// nodes it also answers for.
243///
244/// Most verdicts are about one node and carry no reach. The exception
245/// is a verdict a classifier can only reach by reading a *run* of
246/// siblings: Rust's `#[…]` rows all decorate the same item, so they all
247/// get the same answer, and re-deriving it per row is `O(run)` work
248/// done `run` times. A run of `3 * depth` attributes on one deep parent
249/// made that quadratic — 5.2 s at depth 2 000, against 0.05 s with
250/// `exclude_tests` off (#1446). Reporting the reach lets the walker ask
251/// the classifier once per run.
252///
253/// # Soundness
254///
255/// The reach is a byte offset, and the walk visits nodes in
256/// non-decreasing `start_byte` order, so "starts before it" is a state
257/// the walker can test in `O(1)` and can never re-enter. A claim is
258/// sound when every node the walk *visits* inside the reach genuinely
259/// has the reported verdict.
260///
261/// "Visits" is the load-bearing word, and it cuts the obligation in
262/// two. A `SKIP` reach need only hold for the nodes it skips, since a
263/// skipped node's descendants are never pushed. A `RETAIN` reach
264/// carries the heavier claim: the members' descendants *are* walked, so
265/// it must be right for them too.
266///
267/// A verdict can also answer for one node named by identity, where the
268/// reach stops ([`Self::covering_through_node`]). That claim is about
269/// the node alone: its descendants are not inside the reach, so a
270/// `RETAIN` walk still asks about each of them. It cannot be re-entered
271/// either, since an id is unique within one tree and a pre-order walk
272/// visits each node once.
273#[derive(Clone, Copy, PartialEq, Eq, Debug)]
274pub struct SubtreeSkip {
275    skipped: bool,
276    covers_through_byte: Option<usize>,
277    covers_node: Option<usize>,
278}
279
280impl SubtreeSkip {
281    /// Keep this node. Answers for nothing else.
282    pub const RETAIN: Self = Self {
283        skipped: false,
284        covers_through_byte: None,
285        covers_node: None,
286    };
287
288    /// Elide this node and its descendants. Answers for nothing else.
289    pub const SKIP: Self = Self {
290        skipped: true,
291        covers_through_byte: None,
292        covers_node: None,
293    };
294
295    /// [`Self::SKIP`] or [`Self::RETAIN`], from a predicate's answer.
296    #[inline]
297    #[must_use]
298    pub const fn of(skipped: bool) -> Self {
299        if skipped { Self::SKIP } else { Self::RETAIN }
300    }
301
302    /// Extend this verdict to every node that starts before `byte`.
303    ///
304    /// The caller is asserting that it read far enough to answer for
305    /// all of them — see the soundness note on the type.
306    #[inline]
307    #[must_use]
308    pub const fn covering_through(self, byte: usize) -> Self {
309        Self {
310            covers_through_byte: Some(byte),
311            ..self
312        }
313    }
314
315    /// Whether this node and its descendants are elided.
316    #[inline]
317    #[must_use]
318    pub const fn is_skipped(self) -> bool {
319        self.skipped
320    }
321
322    /// [`Self::covering_through`] `node`'s start, plus `node` itself.
323    ///
324    /// The caller is asserting that this verdict is also `node`'s own.
325    /// Naming `node` by identity, rather than moving the reach past its
326    /// start, leaves its descendants out: its first child starts at the
327    /// same byte.
328    #[inline]
329    #[must_use]
330    pub fn covering_through_node(self, node: &Node) -> Self {
331        Self {
332            covers_node: Some(node.id()),
333            ..self.covering_through(node.start_byte())
334        }
335    }
336
337    /// Whether this verdict already answers for `node`, so the
338    /// classifier need not be asked again.
339    #[inline]
340    #[must_use]
341    pub fn answers_for(self, node: &Node) -> bool {
342        self.covers_node == Some(node.id())
343            || self
344                .covers_through_byte
345                .is_some_and(|through| node.start_byte() < through)
346    }
347}
348
349/// Per-language AST classification predicates the metric walkers use to
350/// recognize comments, function spaces, calls, strings, branches, and so
351/// on by node kind.
352///
353/// Most predicates default to `false` — "this node is never of that
354/// category." A language implements only the predicates its grammar
355/// actually expresses; categories it lacks fall through to the default,
356/// so adding a language no longer requires copy-pasting `-> false` stubs.
357/// The flip side is that the compiler cannot flag a forgotten override, so
358/// each language's per-metric tests are the safety net for completeness.
359/// The predicates a walk asks with the bytes and the chain in hand are
360/// the exception: [`is_func_space_with_code`](Self::is_func_space_with_code),
361/// [`is_func_with_code`](Self::is_func_with_code),
362/// [`is_call_with_code`](Self::is_call_with_code) and
363/// [`is_string_with_code`](Self::is_string_with_code) are required, so
364/// a language cannot answer one by inheriting a forward to a spelling
365/// that drops the bytes or the chain; and so is the byte-less
366/// [`is_func_space`](Self::is_func_space), whose forward the other way
367/// carries a build-time pin a default could not (#1863).
368///
369/// `#[doc(hidden)]` for the reason the crate root gives: this is
370/// plumbing, and the surface the README points a reader at is `LANG` /
371/// `Node` / `SpaceKind`, not a 200-method classifier trait.
372#[doc(hidden)]
373pub trait Checker {
374    /// Whether `node` is a comment.
375    #[inline]
376    #[must_use]
377    fn is_comment(_: &Node) -> bool {
378        false
379    }
380    /// Whether this comment must survive `strip_comments`.
381    ///
382    /// `ancestors` is the chain the comment-removal walk descended
383    /// through. Rust's impl reads the parent to keep a comment that is
384    /// a macro token; reaching it with [`Node::parent`] costs
385    /// `O(depth)` per comment (#1096).
386    ///
387    /// That walk records no siblings, so an impl must not ask
388    /// `ancestors` for one: under a wide parent that trips the walk
389    /// assertion in a debug build (#1601).
390    #[inline]
391    #[must_use]
392    fn is_useful_comment<'a>(_: &Node<'a>, _: &[u8], _: Ancestors<'a, '_>) -> bool {
393        false
394    }
395    /// Whether this comment node is documentation: a doc comment the
396    /// grammar marks (Rust's doc marker child, Groovy's
397    /// `groovydoc_comment`, Perl's `pod_statement`) or one its
398    /// language's own tool recognises by the opening marker in `code`
399    /// (Doxygen, Javadoc, KDoc, JSDoc, PHPDoc, C# XML docs; see
400    /// `lang_helpers::doc_comment`). Implies [`is_comment`]; the LOC
401    /// walk bills such a row as `dloc` as well as `cloc`, unless it sits
402    /// in a function body the language's tool does not read
403    /// ([`DOC_COMMENTS_IN_FUNCTION_BODIES`]) (#1597).
404    ///
405    /// [`is_comment`]: Self::is_comment
406    /// [`DOC_COMMENTS_IN_FUNCTION_BODIES`]: Self::DOC_COMMENTS_IN_FUNCTION_BODIES
407    #[inline]
408    #[must_use]
409    fn is_doc_comment(_: &Node, _code: &[u8]) -> bool {
410        false
411    }
412    /// Whether a doc comment inside a function or closure body is still
413    /// documentation. `false` where it is better read as a working note,
414    /// so a note spelled `/// …` stays a charged comment: rustc lints one
415    /// on a statement as unused (`unused_doc_comments`), Roslyn raises
416    /// CS1587, javadoc and Dokka document declarations only, and an
417    /// in-body PHPDoc `/** @var */` is a type hint. `true` where the tool
418    /// publishes what a body holds: Doxygen's in-body description (C, C++,
419    /// Objective-C — `HIDE_IN_BODY_DOCS` defaults to NO), JSDoc's inner
420    /// symbols, and Perl POD, which perldoc extracts wherever it sits
421    /// (#1597). Which part of a function counts as its body is
422    /// [`holds_doc_comment_in_body`](Self::holds_doc_comment_in_body).
423    const DOC_COMMENTS_IN_FUNCTION_BODIES: bool = false;
424    /// Whether `ancestor`, one of a doc comment's ancestors, holds it in a
425    /// function or closure body, where
426    /// [`DOC_COMMENTS_IN_FUNCTION_BODIES`](Self::DOC_COMMENTS_IN_FUNCTION_BODIES)
427    /// decides whether it is documentation. `ancestors` is `ancestor`'s
428    /// own chain, and `below` is the node directly under `ancestor` on the
429    /// path to the comment, which is what a "does the body hold it" test
430    /// reads. The answer is memoised per ancestor for the whole walk, so
431    /// it must not depend on which comment asked; a comment-specific
432    /// exception is
433    /// [`doc_comment_opens_body`](Self::doc_comment_opens_body) (#1597).
434    /// By default the whole function or closure node counts:
435    /// javac binds a doc comment only before a declaration's first token,
436    /// and the C# specification wants one before a member's attributes,
437    /// so a doc comment after an annotation or on a parameter documents
438    /// nothing there. A language whose tool reads doc comments in the
439    /// signature narrows this to the body proper (#1597). `code` is
440    /// the source, for the callable test and the residual row: a
441    /// callable told by its chain or its bytes (C#'s primary
442    /// constructor, a bound arrow) is asked as the walk asks it (#1863).
443    #[inline]
444    #[must_use]
445    fn holds_doc_comment_in_body<'a>(
446        ancestor: &Node<'a>,
447        code: &[u8],
448        ancestors: Ancestors<'a, '_>,
449        _below: &Node<'a>,
450    ) -> bool {
451        Self::is_func_with_code(ancestor, code, ancestors) || Self::is_closure(ancestor, ancestors)
452    }
453    /// Whether `comment`, held in a body by `ancestor` (one of its two
454    /// nearest ancestors, with `below` the node between them), is that
455    /// body's own documentation rather than a note in it, so `ancestor`
456    /// does not count as holding it. `false` by default; Rust's inner doc
457    /// comment opening a function body is its `#![doc]` (#1597, #1615).
458    #[inline]
459    #[must_use]
460    fn doc_comment_opens_body(
461        _comment: &Node,
462        _ancestor: &Node,
463        _below: &Node,
464        _code: &[u8],
465    ) -> bool {
466        false
467    }
468    /// Whether a comment run before `node` documents it, so the LOC walk
469    /// bills that run as `dloc`. A positional language asks it of the
470    /// node on the row directly below the run — go/doc's lead comment,
471    /// YARD's convention; see `lang_helpers::doc_comment::leading_doc_run`
472    /// (#1597). A language with a [`DOC_BINDING`](Self::DOC_BINDING) asks
473    /// it of the first sibling after the run's comments and the nodes its
474    /// [`DocBinding::skips`] names, and answers for the declarations its
475    /// tool attaches a doc comment to; see
476    /// `lang_helpers::doc_comment::bound_doc_run` (#1613). `ancestors`
477    /// is `node`'s chain, for a rule that depends on where it sits.
478    #[inline]
479    #[must_use]
480    fn is_doc_target<'a>(_: &Node<'a>, _code: &[u8], _: Ancestors<'a, '_>) -> bool {
481        false
482    }
483    /// How a doc comment attaches to the declaration after it (#1613).
484    /// `None` by default: a doc comment documents wherever it sits outside
485    /// a function body, attached to anything or not, which is every
486    /// language not yet bound. A bound language's forward doc comments
487    /// ([`DocBinding::forward`]) document only when their stretch ends at
488    /// an [`is_doc_target`](Self::is_doc_target), and only the ones the
489    /// binding keeps; see `lang_helpers::doc_comment::bound_doc_run`.
490    const DOC_BINDING: Option<DocBinding> = None;
491    /// The row a doc target begins on, which a comment run must end
492    /// directly above. Normally `node`'s own start row; Ruby's `then`
493    /// wrapper starts on the row of the comment the grammar parks ahead of
494    /// it, so its first statement's row stands in for it (#1597).
495    #[inline]
496    #[must_use]
497    fn doc_target_start_row(node: &Node) -> usize {
498        node.start_row()
499    }
500    /// Whether the comment run that `first` opens is documentation by its
501    /// own content rather than by a [`is_doc_target`](Self::is_doc_target)
502    /// below it: an LDoc block, opened by `---` and continued over the `--`
503    /// rows below it, read under LDoc's rule for what follows it; or
504    /// RDoc's `##` and YARD's `@!` directive blocks, which document
505    /// metaprogrammed methods with no `def` to sit above. `next` is the
506    /// sibling on the row directly after the run, if any, and `ancestors`
507    /// is the run's chain, for a rule that depends on where the run sits
508    /// (#1597).
509    #[inline]
510    #[must_use]
511    fn is_doc_run_opener<'a>(
512        _first: &Node<'a>,
513        _next: Option<&Node<'a>>,
514        _code: &[u8],
515        _: Ancestors<'a, '_>,
516    ) -> bool {
517        false
518    }
519    /// Whether a comment run cannot continue past `node` onto the next
520    /// row: LDoc ends a block at a long comment (`--[[ … ]]`), because
521    /// the comment's closing newline is not part of it (#1597). A
522    /// comment later on the same row still joins.
523    #[inline]
524    #[must_use]
525    fn ends_doc_run(_: &Node, _code: &[u8]) -> bool {
526        false
527    }
528    /// A member of a documentation run that is not documentation text
529    /// and is not billed as `dloc`: a go/doc directive such as
530    /// `//go:generate`, a Ruby shebang or magic comment (#1597).
531    #[inline]
532    #[must_use]
533    fn is_doc_run_directive(_: &Node, _code: &[u8]) -> bool {
534        false
535    }
536    /// Whether `node` opens a space by its kind alone: a function,
537    /// closure, or one of the containers (class, struct, trait, impl,
538    /// namespace, interface).
539    ///
540    /// The byte-less spelling of
541    /// [`is_func_space_with_code`](Self::is_func_space_with_code): that
542    /// predicate asked with no bytes and a known-empty chain, the node
543    /// read as if it were the root. It agrees with the walk wherever no
544    /// space-opening gate reads either, and answers the gate's
545    /// rootless, byte-less verdict where one does (Elixir's `def` and
546    /// `defmodule` calls, Ruby's lambda body, C#'s primary constructor,
547    /// a Java or Groovy record's header). The walk calls the
548    /// `_with_code` one.
549    ///
550    /// Required, with no default (#1863): a language emits it through
551    /// `impl_byte_less_func_space!`, which pins at build time that the
552    /// rows it forwards to read neither, or writes it by hand beside
553    /// the reason it cannot. A provided forward would hand a new
554    /// language the spelling without the pin.
555    #[must_use]
556    fn is_func_space(node: &Node) -> bool;
557    /// Whether `node` is an anonymous function — the complement of
558    /// [`is_func_with_code`](Self::is_func_with_code) on the grammars
559    /// that express both. `ancestors` is the chain the caller descended
560    /// through: the JS family tells a bound arrow from a positional one
561    /// by what encloses it, and Ruby's `{ … }` block is a closure only
562    /// when its parent is not the `Lambda` that already counted it.
563    #[inline]
564    #[must_use]
565    fn is_closure<'a>(_: &Node<'a>, _ancestors: Ancestors<'a, '_>) -> bool {
566        false
567    }
568    /// Whether `node` is a *call site* — a function, method or command
569    /// invocation a reader would navigate to.
570    ///
571    /// This is the predicate behind the `call` filter that
572    /// [`ParserTrait::filters`](crate::traits::ParserTrait::filters)
573    /// builds, so it decides what `bca find --type call` and
574    /// `bca count --type call` report.
575    ///
576    /// It is deliberately narrower than the ABC `branches` axis, which
577    /// applies Fitzpatrick's *"function invocation or object creation"*
578    /// rule. Object construction (`new T(…)`) and constructor
579    /// delegation — C#'s `: base(x)` / `: this(a)` and a C# 12 primary
580    /// constructor's `: Base(x)`, Java's `super(…)` / `this(…)`,
581    /// Kotlin's `constructor_invocation` — are ABC branches and are
582    /// **not** call sites here: a constructor is not a function the
583    /// `find` result should point a reader at. The languages whose
584    /// `branches` axis consequently exceeds their `is_call` set are C#,
585    /// Java, Groovy, Kotlin, C++, Mozcpp, JavaScript, MozJS,
586    /// TypeScript, TSX, PHP, Ruby (`super` / `yield` count as branches)
587    /// and Rust (`?` does).
588    ///
589    /// The relation is not a plain superset everywhere. Three languages
590    /// depart from it, each in its own direction:
591    ///
592    /// * Tcl and iRules bill a mutator command (`incr`, `append`,
593    ///   `lappend`) as an ABC *assignment* rather than a branch while
594    ///   `is_call` still counts it. `set` is not one of those: it has a
595    ///   grammar production of its own (`Tcl::Set` / `Irules::Set`)
596    ///   rather than being a `command`, so it is an ABC assignment that
597    ///   `is_call` never matches either.
598    /// * Elixir excludes its definition and directive `Call`s (`def`,
599    ///   `defmodule`, `alias`, `import`, …) from `branches` while
600    ///   counting each `|>` pipeline step.
601    ///
602    /// The two sets coincide in C, Objective-C, Go, Python, Lua and
603    /// Bash, which have neither a separate construction syntax nor a
604    /// gated branch arm, and in Perl, whose one gated arm ABC shares
605    /// with [`is_call_with_code`](Self::is_call_with_code): a bareword
606    /// is no call of its own as a wrapper's callee (`print` in
607    /// `print shift;`) or as an auto-quoted key (`(name => 1)`). That
608    /// gate needs the ancestor chain, so for Perl this byte-less form is
609    /// only the kind table the override narrows.
610    // `is_call` and each language's ABC branch arm classify the same
611    // nodes through parallel `matches!()` tables, so they drift
612    // silently; the divergence is pinned by
613    // `groovy_is_call_excludes_constructors` (#430) and
614    // `csharp_is_call_excludes_constructors` in this file's tests.
615    #[inline]
616    #[must_use]
617    fn is_call(_: &Node) -> bool {
618        false
619    }
620    /// [`is_call`](Self::is_call), given the source bytes and the
621    /// chain the caller descended through, which the `call` filter
622    /// hands it: the language's `Call` row under its gates. Required
623    /// (#1863): a default forwarding to the byte-less [`is_call`](Self::is_call)
624    /// answered a gated row from its kind table without a word.
625    ///
626    /// Perl's row is gated: the grammar nests a call's name inside the
627    /// call as a bareword call of its own, and parses an auto-quoted
628    /// hash key as one, so only the position says which words are
629    /// calls (#1580). As with [`is_string_with_code`](Self::is_string_with_code),
630    /// a call site reaching for the byte-less spelling reads as correct
631    /// against every language with an ungated row;
632    /// `perl_bareword_is_a_call_only_to_the_byteless_spelling` pins that
633    /// the two really do disagree.
634    #[must_use]
635    fn is_call_with_code<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool;
636    /// Whether `node`, met among a parameter list's children, is
637    /// punctuation or a keyword rather than a parameter (`nargs` skips it).
638    #[inline]
639    #[must_use]
640    fn is_non_arg(_: &Node) -> bool {
641        false
642    }
643    /// Whether `param` is a language's way of spelling *"this function
644    /// takes nothing"* inside an otherwise ordinary parameter list.
645    ///
646    /// C's `int f(void)` declares zero parameters, but the grammar
647    /// emits a real `parameter_declaration` for the `void`, so the
648    /// negative filters in `big_code_analysis::nargs` counted it as one — `f` and
649    /// `int f(int)` both reported 1 despite one of them taking no
650    /// argument at all.
651    ///
652    /// It takes `code` because the question is not structural: a
653    /// `parameter_declaration` holding a bare `primitive_type` and no
654    /// declarator is *also* how an unnamed parameter is spelled, and
655    /// `void f(int)` really does take one. Only the bytes tell them
656    /// apart — `docs/development/grammar_dispatch.md` §10.
657    #[inline]
658    #[must_use]
659    fn is_empty_param_marker(_param: &Node, _code: &[u8]) -> bool {
660        false
661    }
662    /// Whether `node` — the value of a function's `parameters` field —
663    /// is itself a *single formal parameter* rather than a parameter
664    /// *list*.
665    ///
666    /// `compute_args` walks the field node's children, which is right
667    /// for a list and yields zero for a lone parameter that has none.
668    /// Java's `lambda_expression` spells its `parameters` field three
669    /// ways — `formal_parameters` and `inferred_parameters` are lists,
670    /// but the un-parenthesised `x -> …` form puts a bare, childless
671    /// `identifier` there — and C#'s puts a childless
672    /// `implicit_parameter`. Both reported `nargs = 0` for a lambda
673    /// that plainly has one argument (#1185).
674    ///
675    /// Gated per language rather than inferred from `child_count() == 0`
676    /// so a MISSING or zero-width ERROR node under `parameters` on a
677    /// broken parse cannot silently conjure an argument.
678    #[inline]
679    #[must_use]
680    fn is_bare_param(_: &Node) -> bool {
681        false
682    }
683    /// Whether `node` is a string literal, under every aliased kind the
684    /// grammar emits for one.
685    ///
686    /// This is the *kind table* half of the answer. Where a grammar
687    /// spells a string literal and something else with one kind, the
688    /// table cannot separate them and the walk must ask
689    /// [`is_string_with_code`](Self::is_string_with_code) instead.
690    #[inline]
691    #[must_use]
692    fn is_string(_: &Node) -> bool {
693        false
694    }
695    /// Source-aware variant of [`is_string`](Self::is_string), and the
696    /// spelling every walk calls: the language's `StringLit` row under
697    /// its gates. Required (#1863): a default forwarding to the
698    /// byte-less predicate answered a gated row from its kind table
699    /// without a word.
700    ///
701    /// The Tcl family's row is gated: `braced_word` is both the literal
702    /// of `lappend x {a b}` and the *script* of a `proc` body or an
703    /// iRules `when` handler, and only the enclosing command's leading
704    /// word tells the two apart (#1318, #1381). Read by kind,
705    /// `bca find --type string` reported every script body in the file
706    /// as a string literal.
707    ///
708    /// **A call site reaching for the byte-less spelling reads as
709    /// correct against every language with an ungated row, and is wrong
710    /// only on the one whose row is gated** —
711    /// `docs/development/grammar_dispatch.md` §7. There is one call site,
712    /// the `"string"` arm of [`ParserTrait::filters`], and it takes this
713    /// spelling; `tcl_script_body_is_a_string_only_to_the_byteless_spelling`
714    /// pins that the two really do disagree, so a future call site that
715    /// picks the wrong one is not silently right.
716    ///
717    /// [`ParserTrait::filters`]: crate::traits::ParserTrait::filters
718    #[must_use]
719    fn is_string_with_code<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool;
720    /// Whether `node` is the `if` that continues an `else if` chain,
721    /// rather than a freshly nested branch.
722    ///
723    /// `ancestors` is the chain the caller descended through; the
724    /// grammars that model `else if` as nesting need the parent (or the
725    /// preceding `else` token) to tell the two apart, and resolving
726    /// either from the node alone costs `O(depth)` (#1084). Languages
727    /// with a dedicated `elsif` clause node ignore it.
728    #[inline]
729    #[must_use]
730    fn is_else_if(_: &Node, _: Ancestors<'_, '_>) -> bool {
731        false
732    }
733    /// Whether `node` is a primitive type name (`int`, `double`, …):
734    /// what the `Primitive` row of the language's role table declares,
735    /// by kind or — Groovy, whose primitives are `identifier`s spelled
736    /// `int` — by text, which this byte-less spelling cannot read. The
737    /// text-gated languages answer this from the row through
738    /// [`keys_operator_by_text`](Self::keys_operator_by_text); the
739    /// kind-only ones by kind.
740    #[inline]
741    #[must_use]
742    fn is_primitive(_node: &Node) -> bool {
743        false
744    }
745
746    /// Whether an operator `node` is keyed by its text rather than its
747    /// kind in the Halstead vocabulary, so that the spellings one kind
748    /// covers — `int` and `double` under one `primitive_type`, `reified`
749    /// under a modifier kind, Objective-C's property-attribute words
750    /// under `identifier` — each count once (#286, #1558, #1579).
751    ///
752    /// Consulted only for a node
753    /// [`Getter::get_op_type_with_code`] has already classified as
754    /// [`TokenRole::Operator`]. The default is
755    /// [`is_primitive`](Self::is_primitive), which is the whole answer
756    /// for a language whose text-keyed operators are its primitive kinds;
757    /// a language that keys a non-primitive by text, or whose primitives
758    /// are told by text (#1599), overrides this with the bytes and the
759    /// chain in hand and leaves `is_primitive` to answer its own question.
760    #[inline]
761    #[must_use]
762    fn keys_operator_by_text<'a>(
763        node: &Node<'a>,
764        _code: &[u8],
765        _ancestors: Ancestors<'a, '_>,
766    ) -> bool {
767        Self::is_primitive(node)
768    }
769
770    /// Whether `node` is, or contains, a tree-sitter `ERROR` node.
771    #[must_use]
772    fn is_error(node: &Node) -> bool {
773        node.has_error()
774    }
775
776    /// Answer [`SubtreeSkip::SKIP`] to elide this node and all its
777    /// descendants from every metric. Used by language modules to
778    /// filter test-only / generated / preprocessor-disabled subtrees.
779    ///
780    /// The default retains every node, preserving the pre-#182
781    /// behavior. Language overrides drive opt-in skips (currently:
782    /// `RustCode` filters `#[cfg(test)]` items, gated by the runtime
783    /// `MetricsOptions::exclude_tests` flag).
784    ///
785    /// `ancestors` is the chain the caller descended through, lending
786    /// the walk's [`SiblingCache`](crate::node::SiblingCache). Rust's
787    /// override reads the run of `#[…]` siblings around an item through
788    /// it: resolving siblings from the node alone costs `O(depth)` per
789    /// step (#1100), and without the cache a flat `ERROR` parent is
790    /// sought `O(index)` per ask (#1584).
791    ///
792    /// A verdict that took a *sibling-run* to reach should say so with
793    /// [`SubtreeSkip::covering_through`], so the walker asks once per
794    /// run rather than once per member, or with
795    /// [`SubtreeSkip::covering_through_node`] when it is also the verdict
796    /// of the node the run ends at. See the type for what makes such a
797    /// claim sound.
798    #[inline]
799    #[must_use]
800    fn should_skip_subtree<'a>(
801        _node: &Node<'a>,
802        _code: &[u8],
803        _ancestors: Ancestors<'a, '_>,
804    ) -> SubtreeSkip {
805        SubtreeSkip::RETAIN
806    }
807
808    /// Whether `node` opens a space, as the walk asks it: with the
809    /// source bytes and the chain it descended through. Required: every
810    /// language answers from its role table's `opens_space` fold, and
811    /// the byte-less [`is_func_space`](Self::is_func_space) derives
812    /// from this, never the reverse — a default forwarding the other
813    /// way handed a text-gated row no bytes without a word (#1863).
814    ///
815    /// Elixir's `def` / `defmodule` are `Call`s told apart by their
816    /// target text (#275), and a `def` inside a `quote` template by the
817    /// chain, read here rather than through `Node::parent`'s `O(depth)`
818    /// per step (#1084).
819    #[must_use]
820    fn is_func_space_with_code<'a>(
821        node: &Node<'a>,
822        code: &[u8],
823        ancestors: Ancestors<'a, '_>,
824    ) -> bool;
825
826    /// Whether `node` is a *named* function definition: the `callable`
827    /// owners of the language's `FuncOpener` row under their gates.
828    /// Required, and the only spelling (#1863): a callable can be told
829    /// by its bytes (Elixir's `def`, #275), by its chain (the JS
830    /// family's bound arrow, #1088; C#'s primary constructor, #1828) or
831    /// by both (a Java or Groovy record's header, #1842), so a
832    /// byte-less form answered three different questions across the
833    /// languages and was right for none of the walks.
834    ///
835    /// The suppression scan asks this through a chain that records no
836    /// siblings, so an impl must not ask `ancestors` for one: under a
837    /// wide parent that trips the walk assertion in a debug build
838    /// (#1601).
839    #[must_use]
840    fn is_func_with_code<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool;
841
842    /// Combined predicate the walker uses to decide whether to promote
843    /// `node` to a new function-space frame. Default forwards to
844    /// `is_func_with_code || is_func_space_with_code` so most
845    /// languages need no override — each keeps the freedom to expose
846    /// the two as disjoint sets (Rust includes closures among its
847    /// spaces, Java keeps lambdas out, …) and
848    /// this method preserves that flexibility while letting Elixir
849    /// halve its per-`Call` source-text lookups: a single
850    /// `elixir_call_keyword` call answers both halves at once
851    /// (#310 follow-on perf).
852    #[inline]
853    #[must_use]
854    fn promotes_to_func_space_with_code<'a>(
855        node: &Node<'a>,
856        code: &[u8],
857        ancestors: Ancestors<'a, '_>,
858    ) -> bool {
859        Self::is_func_with_code(node, code, ancestors)
860            || Self::is_func_space_with_code(node, code, ancestors)
861    }
862
863    /// Whether the function space `node` opens belongs to something
864    /// other than the container that syntactically encloses it.
865    ///
866    /// The space tree is built by a single-pass stack walk, so a space
867    /// is a child of whichever space was open when the walk reached it
868    /// — syntactic containment, never membership. The two normally
869    /// coincide. C++ `friend` is the case where they do not: a friend
870    /// with an inline body is written inside the class braces but is a
871    /// free function the class merely grants access to, so `npm` does
872    /// not count it as a method while `wmc` weighted it anyway (#1301).
873    /// Objective-C has the same shape in a different spelling: a plain
874    /// C `function_definition` inside `@implementation` / `@interface`
875    /// / `@protocol` is a file-static helper, never a method (#1356).
876    ///
877    /// `wmc` is the sole consumer: WMC is defined as the sum over a
878    /// class's *methods*, so a `true` here keeps the space out of the
879    /// enclosing class's WMC while leaving it a `Function` space like
880    /// any other — its own metrics, its `nom` contribution, and the
881    /// file-level cyclomatic roll-up are all unaffected.
882    ///
883    /// A `true` for a function no container encloses is inert rather
884    /// than wrong, since `merge` credits a `Function` child only to a
885    /// `Class` or `Interface` parent. So a language whose grammar makes
886    /// the answer unconditional — Objective-C, where a method is always
887    /// a `method_definition` — may answer on node kind alone, which is
888    /// total where a parent-kind list is not.
889    ///
890    /// Deliberately one method rather than a byte-less / `_with_code`
891    /// pair: the pair forwards by default, so a call site reaching for
892    /// the wrong spelling reads as correct against every language
893    /// without an override (`docs/development/grammar_dispatch.md` §7).
894    /// One spelling has nothing to disagree with.
895    #[inline]
896    #[must_use]
897    fn is_non_member_function<'a>(
898        _node: &Node<'a>,
899        _code: &[u8],
900        _ancestors: Ancestors<'a, '_>,
901    ) -> bool {
902        false
903    }
904}
905
906// The doc-comment binding macros of the C and JS families (#1613),
907// declared before the language modules that invoke them.
908#[macro_use]
909mod doxygen_doc_binding;
910#[macro_use]
911mod js_doc_binding;
912mod bash;
913mod c;
914mod ccomment;
915mod cpp;
916mod csharp;
917mod elixir;
918mod go;
919mod groovy;
920mod irules;
921mod java;
922mod javascript;
923mod kotlin;
924mod lua;
925mod mozcpp;
926mod mozjs;
927mod objc;
928mod perl;
929mod php;
930mod preproc;
931mod python;
932mod ruby;
933mod rust;
934mod tcl;
935mod tsx;
936mod typescript;
937
938/// Returns the `class_body` child of a Java `object_creation_expression`
939/// when the node is an anonymous class (`new Runnable() { ... }`), or
940/// `None` for a plain constructor call (`new Foo()`). Shared by
941/// `JavaCode::is_func_space` and `JavaCode::get_space_kind` so both agree
942/// on exactly which `object_creation_expression` nodes open a Class space
943/// (#463); a lambda is a distinct `lambda_expression` node and never
944/// reaches this path.
945#[must_use]
946pub(crate) fn java_anonymous_class_body<'a>(node: &Node<'a>) -> Option<Node<'a>> {
947    node.first_child(|id| id == Java::ClassBody as u16)
948}
949
950/// Counts the `accessor_declaration` children (`get` / `set` / `init`) of a C#
951/// `property_declaration` / `indexer_declaration` by walking its
952/// `accessor_list`. Returns `0` for the expression-bodied form
953/// (`this[int i] => _d[i];` / `int W => _w;`), which has no accessor list.
954///
955/// Used by the npm reference `csharp_count_member`, which keeps its own
956/// `.max(1)` fallback so an accessor-less expression-bodied member still
957/// counts as one method (#464). `csharp_member_has_accessors` asks only
958/// whether one exists and stops at the first (#1612).
959#[must_use]
960pub fn csharp_accessor_count(node: &Node) -> usize {
961    csharp_accessors(node).count()
962}
963
964// Each accessor search a C# member's gate runs. The search is the cost
965// the doc-comment body test avoids by reading the `DocBodyResidual` row
966// *before* the callable test (#1612): no verdict can see the order, so
967// the count is what pins it (`csharp_body_test_reads_the_row_before_the_accessor_search`).
968crate::observation::counter!(csharp_accessor_searches);
969
970/// The `accessor_declaration`s in a C# member's `accessor_list`.
971// role-bypass: allow(FuncOpener) — which children are a member's accessors
972// (the gate the row reads), not whether an accessor opens a space
973fn csharp_accessors<'a>(node: &Node<'a>) -> impl Iterator<Item = Node<'a>> + use<'a> {
974    csharp_accessor_searches::record();
975    node.children()
976        .filter(|c| c.kind_id() == Csharp::AccessorList as u16)
977        .flat_map(|list| list.children())
978        .filter(|c| c.kind_id() == Csharp::AccessorDeclaration as u16)
979}
980
981/// Returns `true` when a C# `indexer_declaration` / `property_declaration`
982/// carries bodied accessors — an `accessor_list` containing at least one
983/// `accessor_declaration` (`get` / `set` / `init`). Returns `false` for the
984/// expression-bodied form (`this[int i] => _d[i];` / `int W => _w;`), which
985/// has no accessor list and defines a single implicit getter.
986///
987/// Shared by `CsharpCode`'s callable and space tests and
988/// `CsharpCode::get_space_kind` so all three agree on when an indexer or
989/// property opens its own Function space versus deferring to its accessor
990/// children. This mirrors the npm reference (`csharp_count_member`): the
991/// member counts as its accessor count, falling back to 1 for the
992/// accessor-less expression-bodied form (#464 indexer, #472 property).
993#[must_use]
994pub(crate) fn csharp_member_has_accessors(node: &Node) -> bool {
995    csharp_accessors(node).next().is_some()
996}
997
998/// Returns `true` when a C++ `struct_specifier` / `class_specifier`
999/// defines a type body (`struct S { … }`) rather than only naming one.
1000/// A forward declaration (`struct S;`) and an elaborated type specifier
1001/// (`struct S *p;`, the parameter type in `void f(struct S *q)`) carry no
1002/// `body` field.
1003///
1004/// Shared by the C++ and Mozcpp `is_func_space` and `get_space_kind`, so
1005/// a bodiless specifier neither opens a space nor is labelled one (#1555).
1006#[must_use]
1007pub(crate) fn cpp_specifier_has_body(node: &Node) -> bool {
1008    node.child_by_field_name("body").is_some()
1009}
1010
1011/// Whether `node` is a bare keyword token the C# grammar *aliased* to
1012/// `modifier`, rather than the `modifier` rule itself.
1013///
1014/// The rule is `choice('public', 'static', 'async', 'readonly', …)`, so
1015/// a real `modifier` wraps one keyword leaf that the getter already
1016/// classifies on its own. Two other rules alias a bare token onto the
1017/// same named kind, and those nodes are **childless**:
1018///
1019/// - `_parameter_type_with_modifiers` — `this`, `scoped`, `ref`, `out`,
1020///   `in`, `readonly` in parameter position, the six #1418 bills.
1021/// - `_lambda_expression_init` and `anonymous_method_expression` —
1022///   `static` and `async` on a lambda or `delegate { … }`, billed as
1023///   operators like their declaration spelling (#1482).
1024///
1025/// Child-presence is therefore what separates an alias from the rule,
1026/// and it is the grammar's shape rather than an inference about a broken
1027/// parse — contrast [`Checker::is_bare_param`], which refuses the same
1028/// test precisely because there it would be a guess.
1029///
1030/// Shared by [`CsharpCode::get_op_type_with_code`], which decides the
1031/// keyword's Halstead role from its text, and
1032/// [`CsharpCode::is_primitive`], which routes the operator half through
1033/// the lexeme-keyed map so the alias and the bare token are one
1034/// operator (#1418).
1035///
1036/// [`CsharpCode::get_op_type_with_code`]: crate::Getter::get_op_type_with_code
1037/// [`CsharpCode::is_primitive`]: Checker::is_primitive
1038#[must_use]
1039pub(crate) fn csharp_is_aliased_modifier(node: &Node) -> bool {
1040    // role-bypass: allow(Modifier) — the shape test the row's own text gate is built on
1041    node.kind_id() == Csharp::Modifier as u16 && node.child_count() == 0
1042}
1043
1044/// Whether `param` is C's `(void)` marker — the spelling for an empty
1045/// parameter list — rather than a parameter.
1046///
1047/// Shared by C, C++, Mozcpp and Objective-C, which all inherit the
1048/// idiom and all emit a real `parameter_declaration` for it.
1049///
1050/// The declarator check is what separates the marker from `void *p`,
1051/// which is an ordinary parameter of type `void *`, and the byte
1052/// comparison is what separates it from an unnamed parameter of any
1053/// other type: `f(int)` and `f(void)` are the same shape and different
1054/// arities.
1055#[must_use]
1056pub fn c_family_void_parameter(param: &Node, code: &[u8]) -> bool {
1057    param.child_by_field_name("declarator").is_none()
1058        && param
1059            .child_by_field_name("type")
1060            .and_then(|ty| code.get(ty.start_byte()..ty.end_byte()))
1061            == Some(b"void".as_slice())
1062}
1063
1064/// Strip the `#` / `#!` marker plus the `[...]` brackets from a
1065/// Rust `AttributeItem` / `InnerAttributeItem` token's raw text,
1066/// returning the inner body. Returns `None` if the input shape is
1067/// unexpected — callers skip silently rather than feed the matcher
1068/// the literal `#[...]` form.
1069fn rust_attribute_body<'a>(text: &'a str, marker: &str) -> Option<&'a str> {
1070    text.trim()
1071        .strip_prefix(marker)
1072        .and_then(|t| t.trim_start().strip_prefix('['))
1073        .and_then(|t| t.trim().strip_suffix(']'))
1074}
1075
1076/// Classifies one attribute node's body, given the `#` / `#!` marker
1077/// its kind carries. Returns `false` for a node whose text is not
1078/// valid UTF-8 or does not have the `marker[...]` shape.
1079fn rust_attribute_node_marks_test(node: &Node, code: &[u8], marker: &str) -> bool {
1080    node.utf8_text(code)
1081        .and_then(|text| rust_attribute_body(text, marker))
1082        .is_some_and(rust_attribute_marks_test)
1083}
1084
1085fn rust_item_is_test_only<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
1086    rust_outer_attr_marks_test(node, code, ancestors) || rust_inner_attr_marks_test(node, code)
1087}
1088
1089/// Whether a sibling of kind `kind` belongs to the outer-attribute run
1090/// around it rather than ending it: an `#[…]` row, or a comment of
1091/// either kind (#1647).
1092///
1093/// rustc reads a `//` or `/* */` comment as no token at all, so an
1094/// attribute above one still decorates the item below it, and it reads
1095/// an outer doc comment as a `#[doc]` attribute, so that is a row of the
1096/// run outright. Either way the item compiles only under the `cfg` the
1097/// run carries, and the comment is part of what the prune removes with
1098/// it. The comment kinds are the `Comment` and `DocComment` rows of
1099/// `roles/rust.rs`, read gates aside: an inner doc comment (`//!`) in
1100/// this position is rustc's error E0753, and a comment is a comment to
1101/// the run whichever marker it carries.
1102fn rust_attribute_run_member(kind: u16) -> bool {
1103    kind == Rust::AttributeItem as u16
1104        || crate::roles::rust::comment::lists_kind(kind)
1105        || crate::roles::rust::doc_comment::lists_kind(kind)
1106}
1107
1108/// Whether `node` is a row a run is *opened* from, so that the hook
1109/// reads the run when it stands on it: an `#[…]` row, or an outer doc
1110/// comment (`///`, `/** */`), which is a `#[doc]` attribute to rustc and
1111/// decorates the item below it like any other (#1647).
1112///
1113/// A plain comment is a member of a run it sits inside
1114/// ([`rust_attribute_run_member`]) but opens none: `// note` above
1115/// `#[cfg(test)]` is not an attribute of the item, and stays. Nor does
1116/// an inner doc comment, which documents the item *around* it — a
1117/// crate's `//!` header above its first `#[cfg(test)]` item is not that
1118/// item's. So the hook answers `RETAIN` for either in `O(1)`, and a
1119/// plain comment inside a run is answered by the reach of the row that
1120/// opened it, which the walk always visits first. Reading the run
1121/// backward from every plain comment instead would make a long stretch
1122/// of `//` rows — each its own `line_comment` sibling — quadratic in
1123/// itself.
1124fn rust_attribute_run_start(node: &Node, code: &[u8]) -> bool {
1125    node.kind_id() == Rust::AttributeItem
1126        || (<RustCode as Checker>::is_doc_comment(node, code)
1127            && !rust::rust_inner_doc(crate::lang_helpers::doc_comment::node_bytes(node, code)))
1128}
1129
1130/// The item kinds the `exclude_tests` prune removes, given a test-only
1131/// verdict.
1132///
1133/// `RustCode::should_skip_subtree` consults this for an item, and
1134/// [`rust_attribute_run_verdict`] takes a run's verdict from that hook's
1135/// answer for the item it decorates, so the two can never disagree
1136/// about whether that item is prunable: `#[cfg(test)] use foo;` keeps
1137/// both rows, because a `use_declaration` is not on this list (#1431).
1138fn rust_prunable_item(node: &Node) -> bool {
1139    // role-bypass: allow(FuncOpener, Container, Member, DocTarget) — which
1140    // items a `#[cfg(test)]` prunes, not membership
1141    matches!(
1142        node.kind_id().into(),
1143        Rust::ModItem
1144            | Rust::FunctionItem
1145            | Rust::ImplItem
1146            | Rust::TraitItem
1147            | Rust::ConstItem
1148            | Rust::StaticItem
1149    )
1150}
1151
1152/// Whether the outer-attribute run `node` belongs to decorates an item
1153/// the prune removes — which makes `node`'s own row test code too.
1154///
1155/// The whole run is asked about the *item*, not about itself, so every
1156/// row of a stacked `#[cfg(test)]\n#[allow(dead_code)]\nmod t` goes:
1157/// the second attribute says nothing about tests, and
1158/// [`rust_item_is_test_only`] reads the run from the item end either
1159/// way (#1431).
1160///
1161/// That is also why the answer is reported as covering the rest of the
1162/// run, and the item it ends at (#1783). Every attribute from `node` up
1163/// to the item resolves the same item and therefore the same verdict,
1164/// so a walker that re-asks per row pays the run twice over per row:
1165/// once in [`rust_attributed_item`]'s lookahead and once in the
1166/// backward reading [`rust_item_is_test_only`] takes. Both are `O(run)`
1167/// (see [`rust_outer_attr_marks_test`]), so re-asking per row is
1168/// `O(run²)` — the diagonal #1446 measured at 5.2 s / depth 2 000. One
1169/// ask per run makes it one pass, not `run` passes.
1170fn rust_attribute_run_verdict<'a>(
1171    node: &Node<'a>,
1172    code: &[u8],
1173    ancestors: Ancestors<'a, '_>,
1174) -> SubtreeSkip {
1175    let Some(item) = rust_attributed_item(node, ancestors) else {
1176        // Attributes all the way to the end of the parent: nothing is
1177        // decorated, so nothing is pruned — and no later member of this
1178        // run will find an item either, so say so once. Without a
1179        // parent to bound the claim there is nothing to say, which
1180        // costs only a re-ask.
1181        return match ancestors.parent(node) {
1182            Some(parent) => SubtreeSkip::RETAIN.covering_through(parent.end_byte()),
1183            None => SubtreeSkip::RETAIN,
1184        };
1185    };
1186    // `item` is `node`'s sibling, so the chain that describes one
1187    // describes the other — parent and depth alike. Its verdict is
1188    // asked of the hook itself, which cannot recurse here because `item`
1189    // is never a run member — neither an `AttributeItem` nor a comment,
1190    // so never a run start — and the run's verdict is the item's own by
1191    // construction rather than by a second spelling of it.
1192    let skipped = RustCode::should_skip_subtree(&item, code, ancestors).is_skipped();
1193    // Everything strictly between `node` and `item` is a run member — an
1194    // `AttributeItem` or a comment, which `rust_attributed_item` searched
1195    // past — so the reach holds for the run's remaining members: they all
1196    // decorate `item`, and go or stay with it (#1647). It holds for *their*
1197    // descendants, which a retained run's walk visits, because an
1198    // attribute's `#`, `[`, `]`, path, token-tree argument and literal or
1199    // macro-call value nest no run member and no `rust_prunable_item`, and
1200    // neither do a comment's delimiter, marker and `doc_comment` tokens. A
1201    // `value` that nests an item, such as a block, is the exception: a
1202    // `#[cfg(test)]` item inside it is kept. rustc rejects such a value
1203    // (Reference `attributes.meta.literal-expr`), so it compiles only in
1204    // code a false `cfg` strips or where an attribute macro consumes the
1205    // attribute, never as a derive helper; neither occurs in this
1206    // repository or serde (#1786). The reach holds for `item` too, since
1207    // `skipped` is its own verdict, so the walk does not ask again (#1783).
1208    SubtreeSkip::of(skipped).covering_through_node(&item)
1209}
1210
1211/// The item an outer-attribute run decorates: the first sibling after
1212/// `node` that is not itself a run member — an `AttributeItem` or a
1213/// comment ([`rust_attribute_run_member`]).
1214///
1215/// Read through [`Ancestors::siblings_after`], at the cost
1216/// [`rust_outer_attr_marks_test`] describes for the run itself.
1217///
1218/// A chain that does not describe `node` finds no siblings after it and
1219/// answers `None`, i.e. "nothing is pruned" — the conservative reading,
1220/// and a caller error either way (a walk constructor's check, #1122).
1221///
1222/// Reusing [`rust_item_is_test_only`] for the verdict rather than
1223/// fusing this lookahead and the run reading into one pass is
1224/// deliberate. A fused scan would be a third reading of the same run,
1225/// free to drift from the other two — the failure mode
1226/// `docs/development/grammar_dispatch.md` §7 is about. What was quadratic
1227/// in #1446 was asking `run` times, which
1228/// [`rust_attribute_run_verdict`]'s reach removes without adding a
1229/// reading.
1230fn rust_attributed_item<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> Option<Node<'a>> {
1231    ancestors
1232        .siblings_after(node)
1233        .find(|sibling| !rust_attribute_run_member(sibling.kind_id()))
1234}
1235
1236// The tree-sitter Rust grammar exposes outer attributes (`#[...]`) as
1237// `AttributeItem` siblings *before* the decorated item, so what marks
1238// `node` test-only is the run of attributes immediately preceding it —
1239// a sibling that is neither an attribute nor a comment (another item)
1240// ends the run, and a comment of either kind is read past (#1647). This
1241// scan covers every item kind, including `mod_item`, so
1242// `#[cfg(test)] mod tests` (an outer attribute on the module) is caught
1243// here while `mod tests { #![cfg(test)] }` is caught by the inner scan.
1244// A comment member is asked like an attribute: its text never has the
1245// `#[…]` shape `rust_attribute_body` requires, so it marks nothing.
1246//
1247// The run is read backward from `node` through `ancestors`, which locates
1248// `node` by a search rather than a pass from the parent's first child,
1249// the pass that made `3 * depth` one-attribute items on one deep parent
1250// `O(depth²)` until #1447 (`docs/development/benchmarking.md`). Under the
1251// walk's chain and `SiblingCache` an ask costs `O(log width + run)` for a
1252// parent wider than `WIDE_PARENT`, a binary search in the recorded
1253// children. Under a narrower one it is a seek bounded by `WIDE_PARENT`:
1254// `Node::children_before` fetches each yielded sibling with
1255// `Node::child(i)`, `O(index)` on a flat list, so at most
1256// `WIDE_PARENT²` steps. Neither depends on depth. A chainless caller
1257// (`Ancestors::unknown()`) pays `Node::parent`'s `O(depth)` on top, and
1258// a chain that lends no cache seeks a flat `ERROR` `O(index)` per ask
1259// (#1584).
1260fn rust_outer_attr_marks_test<'a>(
1261    node: &Node<'a>,
1262    code: &[u8],
1263    ancestors: Ancestors<'a, '_>,
1264) -> bool {
1265    ancestors
1266        .siblings_before(node)
1267        .take_while(|sibling| rust_attribute_run_member(sibling.kind_id()))
1268        .any(|member| rust_attribute_node_marks_test(&member, code, "#"))
1269}
1270
1271/// Reads the same run backward from `node` with the raw sibling
1272/// accessor, which resolves the parent from the root per step. The
1273/// oracle the tests compare [`rust_outer_attr_marks_test`] against: it
1274/// shares no lookup with it, so a wrong seek or a wrong cache index
1275/// cannot make the two agree.
1276#[cfg(all(test, feature = "rust"))]
1277fn rust_attribute_run_before(node: &Node, code: &[u8]) -> bool {
1278    std::iter::successors(node.previous_sibling(), Node::previous_sibling)
1279        .take_while(|sibling| rust_attribute_run_member(sibling.kind_id()))
1280        .any(|member| rust_attribute_node_marks_test(&member, code, "#"))
1281}
1282
1283/// [`rust_attributed_item`]'s oracle, for the same reason: the raw
1284/// forward accessor, one root descent per step.
1285#[cfg(all(test, feature = "rust"))]
1286fn rust_attributed_item_raw<'a>(node: &Node<'a>) -> Option<Node<'a>> {
1287    std::iter::successors(node.next_sibling(), Node::next_sibling)
1288        .find(|sibling| !rust_attribute_run_member(sibling.kind_id()))
1289}
1290
1291// `mod_item` additionally accepts inner attributes (`#![cfg(test)]`).
1292// The grammar nests these inside the module's `declaration_list` body,
1293// not as direct `mod_item` children, so descend one level via the
1294// `body` field before scanning. Non-module items have no inner-attribute
1295// test form, so this returns `false` for them immediately.
1296fn rust_inner_attr_marks_test(node: &Node, code: &[u8]) -> bool {
1297    // role-bypass: allow(DocTarget) — which item kind takes an inner
1298    // attribute, not whether it is a doc target
1299    node.kind_id() == Rust::ModItem
1300        && node.child_by_field_name("body").is_some_and(|body| {
1301            body.children()
1302                .filter(|child| child.kind_id() == Rust::InnerAttributeItem)
1303                .any(|attribute| rust_attribute_node_marks_test(&attribute, code, "#!"))
1304        })
1305}
1306
1307#[cfg(test)]
1308#[allow(
1309    clippy::float_cmp,
1310    clippy::cast_precision_loss,
1311    clippy::cast_possible_truncation,
1312    clippy::cast_sign_loss,
1313    clippy::similar_names,
1314    clippy::doc_markdown,
1315    clippy::needless_raw_string_hashes,
1316    clippy::too_many_lines
1317)]
1318mod tests {
1319    use super::*;
1320    use crate::count::count;
1321    use crate::langs::{
1322        BashParser, JavascriptCode, JavascriptParser, MozjsParser, PhpParser, TsxParser,
1323        TypescriptParser,
1324    };
1325    use crate::test_support::{
1326        ast_has_kind_id, for_each_node_with_chain, for_each_node_with_sibling_cache,
1327    };
1328    use std::fmt::Write as _;
1329    use std::path::PathBuf;
1330
1331    #[cfg(feature = "bash")]
1332    fn parse(source: &str) -> BashParser {
1333        BashParser::new(source.as_bytes().to_vec(), &PathBuf::from("test.sh"), None)
1334    }
1335
1336    #[cfg(feature = "bash")]
1337    fn count_strings(source: &str) -> usize {
1338        count(&parse(source), &["string".to_string()]).0
1339    }
1340
1341    // `count`'s filter parser accepts a numeric string as a `kind_id` match
1342    // (parser.rs `filters`), so `has_kind` reuses the same primitive.
1343    #[cfg(feature = "bash")]
1344    fn has_kind(source: &str, kind_id: u16) -> bool {
1345        count(&parse(source), &[kind_id.to_string()]).0 > 0
1346    }
1347
1348    #[cfg(feature = "bash")]
1349    #[test]
1350    fn bash_is_string_excludes_word_tokens() {
1351        // `echo hello world` produces three Word nodes — none of them are
1352        // string literals. Regression for #44 (Word must not match
1353        // is_string).
1354        assert_eq!(count_strings("echo hello world\n"), 0);
1355        assert_eq!(
1356            count_strings("if [ -f file.txt ]; then cat file.txt; fi\n"),
1357            0
1358        );
1359    }
1360
1361    #[cfg(feature = "bash")]
1362    #[test]
1363    fn bash_is_string_matches_quoted_literals() {
1364        // Regular double-quoted string -> `string` (Bash::String).
1365        assert_eq!(count_strings("echo \"double\"\n"), 1);
1366        // Single-quoted string -> `raw_string` (Bash::RawString).
1367        assert_eq!(count_strings("echo 'single'\n"), 1);
1368        // ANSI-C quoting -> `ansi_c_string` (Bash::AnsiCString).
1369        assert_eq!(count_strings("echo $'ansi-c'\n"), 1);
1370    }
1371
1372    #[cfg(feature = "bash")]
1373    #[test]
1374    fn bash_is_string_matches_translated_string() {
1375        // tree-sitter-bash only emits a visible `translated_string` node
1376        // in assignment-style contexts; in command arguments the `$"..."`
1377        // tokenizes as `$` plus a regular `string`. Use an assignment so
1378        // the wrapper actually appears in the AST.
1379        let src = "x=$\"translated\"\n";
1380        assert!(
1381            has_kind(src, Bash::TranslatedString as u16),
1382            "expected a translated_string node in {src:?}"
1383        );
1384        // The wrapper plus its inner `string` child both match is_string,
1385        // so count is 2.
1386        assert_eq!(count_strings(src), 2);
1387    }
1388
1389    #[cfg(feature = "bash")]
1390    #[test]
1391    fn bash_is_string_matches_heredoc_bodies() {
1392        // Plain heredoc body.
1393        assert_eq!(
1394            count_strings("cat <<EOF\nhello world\nEOF\n"),
1395            1,
1396            "heredoc body should be counted as a string literal"
1397        );
1398        // Quoted-tag heredoc disables expansions but is still a string.
1399        assert_eq!(
1400            count_strings("cat <<'EOF'\nliteral $not_expanded\nEOF\n"),
1401            1
1402        );
1403        // Heredoc with an embedded expansion still yields exactly one
1404        // body node (parallel to a JS template string with `${x}`).
1405        assert_eq!(count_strings("cat <<EOF\nhi $name\nEOF\n"), 1);
1406    }
1407
1408    // ===== PHP `is_string` regression tests (issue #288) =====
1409
1410    #[cfg(feature = "php")]
1411    fn parse_php(source: &str) -> PhpParser {
1412        PhpParser::new(source.as_bytes().to_vec(), &PathBuf::from("test.php"), None)
1413    }
1414
1415    #[cfg(feature = "php")]
1416    fn count_php_strings(source: &str) -> usize {
1417        count(&parse_php(source), &["string".to_string()]).0
1418    }
1419
1420    #[cfg(feature = "php")]
1421    #[test]
1422    fn php_is_string_matches_single_quoted_literal() {
1423        // `Php::String` is the named single-quoted literal. Inert
1424        // single-quoted strings have always been matched; this anchors
1425        // the baseline before exercising the alias kinds.
1426        assert_eq!(count_php_strings("<?php $x = 'single';"), 1);
1427    }
1428
1429    #[cfg(feature = "php")]
1430    #[test]
1431    fn php_is_string_matches_encapsed_heredoc_nowdoc_shell() {
1432        // `EncapsedString` (double-quoted), `Heredoc`, `Nowdoc`, and
1433        // `ShellCommandExpression` (backticks) must all match
1434        // `is_string`. Pre-#288 the alterator/checker arms were almost
1435        // aligned for these named literals — this test locks in the
1436        // shape.
1437        assert_eq!(count_php_strings("<?php $x = \"double\";"), 1);
1438        assert_eq!(
1439            count_php_strings("<?php $x = <<<EOT\nbody\nEOT;\n"),
1440            1,
1441            "heredoc should match is_string"
1442        );
1443        assert_eq!(
1444            count_php_strings("<?php $x = <<<'EOT'\nbody\nEOT;\n"),
1445            1,
1446            "nowdoc should match is_string"
1447        );
1448        assert_eq!(
1449            count_php_strings("<?php $x = `ls`;"),
1450            1,
1451            "shell command (backtick) should match is_string"
1452        );
1453    }
1454
1455    #[cfg(feature = "php")]
1456    #[test]
1457    fn php_is_string_excludes_type_keyword_alias_1474() {
1458        // `Php::String2` (kind_id 25) is the `string` *type* keyword,
1459        // not a literal: `bca dump` finds it only as the sole child of
1460        // a `primitive_type` wrapper. #288 listed it in `is_string` for
1461        // kind-name identity and for parity with `get_op_type` and the
1462        // `Alterator`; #1293 moved it into `get_op_type`'s
1463        // `primitive_type`-suppression arm, so #1474 withdrew it here
1464        // too — the same reversal #1261 made for TS's `String2` and
1465        // TSX's `String3`. On the repo's PHP corpus this took
1466        // `find -t string` from 24 hits to 12 on `strings.php` and from
1467        // 27 to 8 on `classes.php`.
1468        //
1469        // The fixture carries every position the keyword appears in —
1470        // property type, plain parameter, `?string`, a `string|int`
1471        // union and the return type. Today's predicate is a `kind_id`
1472        // `matches!`, so it cannot tell those five apart; they are here
1473        // against a future ancestor-sensitive `is_string_with_code`
1474        // override of the kind Tcl already carries (#1381), which could
1475        // suppress one position and not another. The literals anchor
1476        // the other direction: without them this test would also pass
1477        // if `is_string` were emptied out entirely.
1478        let src = concat!(
1479            "<?php\n",
1480            "class C {\n",
1481            "    private string $prop = 'p';\n",
1482            "    public function f(string $a, ?string $b, string|int $c): string {\n",
1483            "        $d = \"y\";\n",
1484            "        $e = <<<EOT\n",
1485            "        body\n",
1486            "        EOT;\n",
1487            "        $g = <<<'EOT'\n",
1488            "        lit\n",
1489            "        EOT;\n",
1490            "        return (string) $a;\n",
1491            "    }\n",
1492            "}\n",
1493        );
1494        let parser = parse_php(src);
1495        // Pin the keyword spellings by *count*, not with a boolean
1496        // `ast_has_kind_id`. The zero below holds for one spelling
1497        // exactly as for five, so a fixture trimmed to a single
1498        // `string` keyword would keep every assertion here green while
1499        // the paragraph above claimed full coverage — measured, by
1500        // stripping four of the five. The count also subsumes the
1501        // "is the keyword in the parse at all" guard the boolean gave.
1502        let keyword_nodes = parser
1503            .root()
1504            .preorder()
1505            .filter(|n| n.kind_id() == Php::String2 as u16)
1506            .count();
1507        assert_eq!(
1508            keyword_nodes, 5,
1509            "fixture must keep all five `string` type-keyword positions: property, \
1510             parameter, `?string`, `string|int` union, return type",
1511        );
1512        assert_eq!(
1513            count_string_matches_for_kind(&parser, Php::String2 as u16, PhpCode::is_string),
1514            0,
1515            "Php::String2 (type keyword) must not match is_string",
1516        );
1517        // The `(string)` cast is the negative control: a childless
1518        // `cast_type`, a different kind_id, so the four below would be
1519        // five if anything ever classified a cast as a literal. Pinned
1520        // so the control cannot be trimmed out of the fixture silently.
1521        assert_eq!(
1522            parser
1523                .root()
1524                .preorder()
1525                .filter(|n| n.kind_id() == Php::CastType as u16)
1526                .count(),
1527            1,
1528            "fixture must keep the `(string)` cast negative control",
1529        );
1530        assert!(
1531            count_string_matches_for_kind(&parser, Php::String as u16, PhpCode::is_string) > 0,
1532            "the `'p'` literal must still match is_string",
1533        );
1534        // End-to-end through the filter chain `bca find` / `bca count`
1535        // actually use (`is_string_with_code`, `parser.rs`), not just
1536        // the predicate: `'p'`, `"y"`, the heredoc and the nowdoc — the
1537        // four literals, and none of the five keywords.
1538        assert_eq!(count_php_strings(src), 4);
1539    }
1540
1541    // ===== JS-family `is_string` regression tests (issue #283) =====
1542
1543    // Count nodes whose kind_id is exactly `target` *and* match
1544    // `is_string`. It answers both directions: a non-zero count proves
1545    // the alias reaches the predicate (the #283/#288 positive checks),
1546    // and a zero paired with an `ast_has_kind_id` presence check proves
1547    // a kind present in the parse is rejected (Go runes, C-family char
1548    // literals, PHP's `string` type keyword in #1474).
1549    #[cfg(any(
1550        feature = "bash",
1551        feature = "c",
1552        feature = "c-family-helpers",
1553        feature = "cpp",
1554        feature = "csharp",
1555        feature = "elixir",
1556        feature = "go",
1557        feature = "groovy",
1558        feature = "irules",
1559        feature = "java",
1560        feature = "javascript",
1561        feature = "kotlin",
1562        feature = "lua",
1563        feature = "mozcpp",
1564        feature = "mozjs",
1565        feature = "objc",
1566        feature = "perl",
1567        feature = "php",
1568        feature = "python",
1569        feature = "ruby",
1570        feature = "rust",
1571        feature = "tcl",
1572        feature = "typescript",
1573    ))]
1574    fn count_string_matches_for_kind<P: ParserTrait, F: Fn(&Node) -> bool>(
1575        parser: &P,
1576        target: u16,
1577        is_string: F,
1578    ) -> usize {
1579        parser
1580            .root()
1581            .preorder()
1582            .filter(|node| node.kind_id() == target && is_string(node))
1583            .count()
1584    }
1585
1586    #[cfg(feature = "javascript")]
1587    #[test]
1588    fn javascript_is_string_matches_string2_alias() {
1589        // `Javascript::String2` (kind_id 221) aliases to `"string"`
1590        // (see `language_javascript.rs`). The alterator already
1591        // flattens it (#119); the generic `string` filter must agree
1592        // (#283). Use a source mix that exercises both the primary
1593        // `String` and the anonymous `String2` productions.
1594        let src = "const a = 'single';\nconst b = \"double\";\nimport \"m\";\n";
1595        let parser = JavascriptParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.js"), None);
1596        // First confirm String2 actually surfaces in this parse —
1597        // otherwise the assertion below would be vacuously true.
1598        assert!(
1599            ast_has_kind_id(&parser, Javascript::String2 as u16),
1600            "expected Javascript::String2 to appear in the parse",
1601        );
1602        // Then assert every String2 node matches is_string.
1603        assert!(
1604            count_string_matches_for_kind(
1605                &parser,
1606                Javascript::String2 as u16,
1607                JavascriptCode::is_string,
1608            ) > 0,
1609            "Javascript::String2 nodes must match is_string",
1610        );
1611    }
1612
1613    #[cfg(feature = "mozjs")]
1614    #[test]
1615    fn mozjs_is_string_matches_string2_alias() {
1616        // Parallel coverage for the MozJS dialect; same `String2`
1617        // alias as upstream JavaScript (kind_id 220 here).
1618        let src = "const a = 'single';\nconst b = \"double\";\nimport \"m\";\n";
1619        let parser = MozjsParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.js"), None);
1620        assert!(
1621            ast_has_kind_id(&parser, Mozjs::String2 as u16),
1622            "expected Mozjs::String2 to appear in the parse",
1623        );
1624        assert!(
1625            count_string_matches_for_kind(&parser, Mozjs::String2 as u16, MozjsCode::is_string) > 0,
1626            "Mozjs::String2 nodes must match is_string",
1627        );
1628    }
1629
1630    #[cfg(feature = "typescript")]
1631    #[test]
1632    fn typescript_is_string_excludes_type_keyword_alias_1261() {
1633        // TypeScript's only anonymous `"string"` alias, `String2`
1634        // (kind_id 135), is the `: string` type-annotation keyword —
1635        // not a literal. #313 made it match `is_string` for parity
1636        // with the operand classification; #1261 dropped it from both,
1637        // so `find string` / `count string` report literals only.
1638        // The `String` literal kinds must keep matching (the fixture's
1639        // `'x'` / `'y'`), otherwise this test would pass by
1640        // over-narrowing.
1641        let src = "const a: string = 'x';\nfunction f(): string { return 'y'; }\n";
1642        let parser = TypescriptParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.ts"), None);
1643        assert!(
1644            ast_has_kind_id(&parser, Typescript::String2 as u16),
1645            "expected Typescript::String2 to appear in the parse",
1646        );
1647        assert_eq!(
1648            count_string_matches_for_kind(
1649                &parser,
1650                Typescript::String2 as u16,
1651                TypescriptCode::is_string,
1652            ),
1653            0,
1654            "Typescript::String2 (type keyword) must not match is_string",
1655        );
1656        assert!(
1657            count_string_matches_for_kind(
1658                &parser,
1659                Typescript::String as u16,
1660                TypescriptCode::is_string,
1661            ) > 0,
1662            "Typescript::String literals must still match is_string",
1663        );
1664    }
1665
1666    #[cfg(feature = "typescript")]
1667    #[test]
1668    fn tsx_is_string_matches_literal_alias_not_type_keyword_1261() {
1669        // TSX uniquely carries two anonymous `"string"` aliases:
1670        // `String3` (kind_id 141, the type-annotation keyword) and
1671        // `String2` (kind_id 261, the string-literal alias). Both must
1672        // appear in this fixture: the `: string` annotation produces
1673        // `String3`, and the `'x'` / `"y"` / `"m"` / `"c"` literals
1674        // produce `String2`. Asserting presence of both *before*
1675        // checking `is_string` ensures a future grammar bump that
1676        // stops emitting either alias fails loudly here rather than
1677        // silently dropping coverage. The literal alias matches
1678        // (#283); the type keyword must not (#1261).
1679        let src = "const a: string = 'x';\n\
1680                   const b = \"y\";\n\
1681                   import \"m\";\n\
1682                   const el = <div className=\"c\">{\"t\"}</div>;\n";
1683        let parser = TsxParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.tsx"), None);
1684        assert!(
1685            ast_has_kind_id(&parser, Tsx::String3 as u16),
1686            "expected Tsx::String3 (type-keyword `string`) in the parse",
1687        );
1688        assert!(
1689            ast_has_kind_id(&parser, Tsx::String2 as u16),
1690            "expected Tsx::String2 (string-literal alias) in the parse",
1691        );
1692        assert_eq!(
1693            count_string_matches_for_kind(&parser, Tsx::String3 as u16, TsxCode::is_string),
1694            0,
1695            "Tsx::String3 (type keyword) must not match is_string",
1696        );
1697        assert!(
1698            count_string_matches_for_kind(&parser, Tsx::String2 as u16, TsxCode::is_string) > 0,
1699            "Tsx::String2 (string-literal alias) nodes must match is_string",
1700        );
1701    }
1702
1703    // The first node, in document order, whose `kind_id` equals `target`.
1704    #[cfg(any(
1705        feature = "c",
1706        feature = "cpp",
1707        feature = "csharp",
1708        feature = "groovy",
1709        feature = "mozcpp",
1710        feature = "python",
1711        feature = "rust",
1712    ))]
1713    fn find_first_kind<P: ParserTrait>(parser: &P, target: u16) -> Option<Node<'_>> {
1714        parser
1715            .root()
1716            .preorder()
1717            .find(|node| node.kind_id() == target)
1718    }
1719
1720    /// `#[cfg(test)] mod tests { … }` carries the test marker as an
1721    /// *outer* attribute sibling before the `mod_item`. The outer scan
1722    /// must run for `mod_item` nodes too, so this case is caught by
1723    /// `rust_outer_attr_marks_test` — not the inner scan. Pins the key
1724    /// invariant of the helper split: a `mod_item`'s outer attributes are
1725    /// never skipped in favour of only its inner attributes.
1726    #[cfg(feature = "rust")]
1727    #[test]
1728    fn rust_outer_attr_on_mod_is_test_only() {
1729        let src = "#[cfg(test)]\nmod tests {\n    fn t() {}\n}\n";
1730        let parser = RustParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.rs"), None);
1731        let code = parser.code();
1732        let node = find_first_kind(&parser, Rust::ModItem as u16).expect("mod_item");
1733
1734        assert!(rust_item_is_test_only(&node, code, Ancestors::unknown()));
1735        // The marker lives on the outer scan; the inner scan sees no
1736        // `#![cfg(test)]` and must report false.
1737        assert!(rust_outer_attr_marks_test(
1738            &node,
1739            code,
1740            Ancestors::unknown()
1741        ));
1742        assert!(!rust_inner_attr_marks_test(&node, code));
1743    }
1744
1745    /// `mod tests { #![cfg(test)] … }` carries the marker as an *inner*
1746    /// attribute nested in the module body. The outer sibling scan finds
1747    /// nothing; `rust_inner_attr_marks_test` descends via the `body`
1748    /// field and catches it.
1749    #[cfg(feature = "rust")]
1750    #[test]
1751    fn rust_inner_attr_in_mod_is_test_only() {
1752        let src = "mod tests {\n    #![cfg(test)]\n    fn t() {}\n}\n";
1753        let parser = RustParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.rs"), None);
1754        let code = parser.code();
1755        let node = find_first_kind(&parser, Rust::ModItem as u16).expect("mod_item");
1756
1757        assert!(rust_item_is_test_only(&node, code, Ancestors::unknown()));
1758        assert!(!rust_outer_attr_marks_test(
1759            &node,
1760            code,
1761            Ancestors::unknown()
1762        ));
1763        assert!(rust_inner_attr_marks_test(&node, code));
1764    }
1765
1766    /// A plain, unattributed item is not test-only — neither scan matches.
1767    #[cfg(feature = "rust")]
1768    #[test]
1769    fn rust_plain_item_is_not_test_only() {
1770        let src = "fn foo() {}\n";
1771        let parser = RustParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.rs"), None);
1772        let code = parser.code();
1773        let node = find_first_kind(&parser, Rust::FunctionItem as u16).expect("function_item");
1774
1775        assert!(!rust_item_is_test_only(&node, code, Ancestors::unknown()));
1776        assert!(!rust_outer_attr_marks_test(
1777            &node,
1778            code,
1779            Ancestors::unknown()
1780        ));
1781        assert!(!rust_inner_attr_marks_test(&node, code));
1782    }
1783
1784    /// The attribute run and the item it decorates, read through
1785    /// `Ancestors`, must answer exactly what the raw sibling accessors
1786    /// answer, on every node of every attribute shape — under a parent
1787    /// the walk caches and under one it does not. Clean parses only:
1788    /// `Node::next_sibling` steps over a zero-width recovery token at the
1789    /// attribute's end that a cursor yields, a difference that moves no
1790    /// prune verdict.
1791    ///
1792    /// `Ancestors::siblings_before` / `siblings_after` take one of two
1793    /// lookups: a binary search in the children the walk recorded for a
1794    /// parent wider than `WIDE_PARENT`, or a seek on a narrower one.
1795    /// A wrong index in the first, or a wrong seat in the second, moves
1796    /// which subtrees `exclude_tests` prunes and so published metric
1797    /// values. The oracle resolves every sibling from the node itself
1798    /// and shares neither lookup, and each node is also asked with no
1799    /// chain at all, the path the unit tests above take.
1800    ///
1801    /// The answers are counted by lookup and by verdict, and every
1802    /// cell must be filled: two readings that both answered `false`
1803    /// everywhere would agree perfectly, and the wide fixtures without a
1804    /// test marker would leave the cached arm agreeing by default.
1805    #[cfg(feature = "rust")]
1806    #[test]
1807    fn rust_outer_attr_scans_agree() {
1808        use crate::node::WIDE_PARENT;
1809        use crate::test_support::rust_root_of_width;
1810
1811        // One attribute run longer than the file's actual code, so the
1812        // run length cannot be confused with the child count.
1813        let long_run = format!("{}fn f() {{}}\n", "#[allow(dead_code)]\n".repeat(64));
1814        // A parent with hundreds of children: the shallow-but-wide
1815        // shape a per-step sibling scan would have been worst on.
1816        let mut wide = String::new();
1817        for i in 0..200 {
1818            let _ = writeln!(wide, "#[inline] fn f{i}() {{}}");
1819        }
1820        // The cache boundary: `WIDE_PARENT` children exactly (sought,
1821        // not cached), then one more (cached). Sized from the constant,
1822        // and checked below, so raising it cannot quietly leave both
1823        // fixtures on one side.
1824        let at_boundary = rust_root_of_width(WIDE_PARENT);
1825        let past_boundary = rust_root_of_width(WIDE_PARENT + 1);
1826        // #1447's shape, small: nested bodies whose innermost one holds
1827        // many one-attribute items, so the cached arm runs below the
1828        // root as well as at it.
1829        let nesting = 4;
1830        let nested_items = format!(
1831            "{}{}{}",
1832            "fn f() {\n".repeat(nesting),
1833            "#[cfg(test)]\nfn t() {}\n#[inline]\nfn u() {}\n".repeat(WIDE_PARENT / 2),
1834            "}\n".repeat(nesting),
1835        );
1836        let sources = [
1837            // Attribute run opening the file, so the marked item is
1838            // its parent's first non-attribute child.
1839            "#[cfg(test)]\nfn a() {}\n",
1840            // Every recognised marker form, plus the `not(test)` form
1841            // that must *not* mark (#278).
1842            "#[test]\nfn a() {}\n#[tokio::test]\nfn b() {}\n\
1843             #[cfg(all(test, feature = \"x\"))]\nfn c() {}\n\
1844             #[cfg(not(test))]\nfn d() {}\n",
1845            // A run whose marker is not the attribute adjacent to the
1846            // item, the same run reversed, and one an intervening
1847            // comment of each kind is read past (#1647). Both orders
1848            // matter: only the second distinguishes a scan that stops
1849            // at the node it was asked about from one that reads the
1850            // whole run, since the query node here is itself an
1851            // attribute.
1852            "#[cfg(test)]\n#[allow(dead_code)]\nfn a() {}\n\
1853             #[allow(dead_code)]\n#[cfg(test)]\nfn b() {}\n\
1854             #[cfg(test)]\n// plain\nfn c() {}\n\
1855             #[cfg(test)]\n/* block */\nfn d() {}\n\
1856             #[cfg(test)]\n/// doc\nfn e() {}\n\
1857             /// doc\n#[cfg(test)]\nfn g() {}\n\
1858             #[allow(dead_code)]\n// plain\n#[cfg(test)]\nmod h {}\n\
1859             // plain\n#[cfg(not(test))]\n// plain\nfn i() {}\n",
1860            // Nested modules, inner attributes, and an attributed item
1861            // inside a function body — parents other than the root.
1862            "mod outer {\n#![cfg(test)]\nmod inner {\n#[test]\nfn a() {}\n}\n}\n\
1863             fn b() {\n#[cfg(test)]\nfn c() {}\nlet x = 1;\n}\n",
1864            // A bare item: no parent for the root, no preceding
1865            // sibling for the item.
1866            "fn a() {}\n",
1867            // A run that decorates nothing: the lookahead runs off the
1868            // end of the parent.
1869            "fn a() {}\n#[inline]\n#[allow(dead_code)]\n",
1870            &long_run,
1871            &wide,
1872            &at_boundary,
1873            &past_boundary,
1874            &nested_items,
1875        ];
1876
1877        // Indexed `[cached][marked]`: the parent is wider than
1878        // `WIDE_PARENT`, and the oracle found a test marker.
1879        let mut answers = [[0_usize; 2]; 2];
1880        let mut either_side_of_the_cut = [false; 2];
1881        for source in sources {
1882            let code = source.as_bytes();
1883            let visited = for_each_node_with_sibling_cache::<RustCode>(code, |node, ancestors| {
1884                // Built eagerly and shared, so each assertion below names
1885                // the node in one place.
1886                let at = format!("{} at row {}", node.kind(), node.start_row());
1887                let backward = rust_attribute_run_before(node, code);
1888                let reads = crate::node::sibling_cache_reads::observed();
1889                let cached = rust_outer_attr_marks_test(node, code, ancestors);
1890                let read_the_cache = crate::node::sibling_cache_reads::observed() > reads;
1891                assert_eq!(cached, backward, "the cached run reading disagrees on {at}");
1892                assert_eq!(
1893                    rust_outer_attr_marks_test(node, code, Ancestors::unknown()),
1894                    backward,
1895                    "the chainless run reading disagrees on {at}",
1896                );
1897                if node.kind_id() == Rust::AttributeItem {
1898                    assert_eq!(
1899                        rust_attributed_item(node, ancestors).map(|item| item.id()),
1900                        rust_attributed_item_raw(node).map(|item| item.id()),
1901                        "the lookahead found a different item from {at}",
1902                    );
1903                }
1904                if let Some(parent) = ancestors.parent(node) {
1905                    let width = parent.child_count();
1906                    // Sorted by what the lookup did, not only by width:
1907                    // a helper that stopped lending the cache would
1908                    // otherwise turn the cached cells into seeks.
1909                    assert_eq!(
1910                        read_the_cache,
1911                        width > WIDE_PARENT,
1912                        "a {width}-child parent's lookup on {at} did not match the cut",
1913                    );
1914                    answers[usize::from(width > WIDE_PARENT)][usize::from(backward)] += 1;
1915                    either_side_of_the_cut[0] |= width == WIDE_PARENT;
1916                    either_side_of_the_cut[1] |= width == WIDE_PARENT + 1;
1917                }
1918            });
1919            assert!(visited > 0, "fixture must have nodes to compare");
1920        }
1921        assert!(
1922            answers.iter().flatten().all(|&count| count > 0),
1923            "a lookup saw only one answer ([sought, cached] x [unmarked, marked] = \
1924             {answers:?}), so agreeing there proves nothing"
1925        );
1926        assert_eq!(
1927            either_side_of_the_cut,
1928            [true, true],
1929            "no parent sat exactly on, or one past, `WIDE_PARENT`"
1930        );
1931    }
1932
1933    /// The same equivalence one level up, on the hook the walker calls.
1934    ///
1935    /// `rust_item_is_test_only` folds the inner-attribute scan in, and
1936    /// `should_skip_subtree` adds the item-kind filter and the #1431
1937    /// attribute arm, so pinning it here is what carries the
1938    /// predicate-level agreement above through to the set of subtrees
1939    /// `exclude_tests` actually prunes.
1940    ///
1941    /// The oracle reads every run backward and every lookahead forward
1942    /// with the raw sibling accessors, sharing no lookup with
1943    /// production's `Ancestors` readings, so it disagrees the moment
1944    /// either one answers differently. Which lookup those readings take
1945    /// is [`rust_outer_attr_scans_agree`]'s concern; this one pins what
1946    /// the hook does with the answer.
1947    ///
1948    /// It also pins the [`SubtreeSkip`] reach, by replaying exactly what
1949    /// the walker does with it: carry the last covering verdict, and on
1950    /// every node it claims to answer for, check the claim against what
1951    /// the classifier says when asked directly. An over-broad reach —
1952    /// one byte past the item, say, or a run start taken as the run end
1953    /// — is a *silently wrong prune* in production, because the walker
1954    /// never asks again (#1446).
1955    #[cfg(feature = "rust")]
1956    #[test]
1957    fn rust_should_skip_subtree_matches_the_backward_reading() {
1958        let source = "#[cfg(test)]\nmod tests {\nfn a() {}\n}\n\
1959                      #[allow(dead_code)]\nstatic S: i32 = 1;\n\
1960                      mod inner {\n#![cfg(test)]\nconst C: i32 = 1;\n}\n\
1961                      #[rstest]\nfn b() {}\nfn c() {}\n\
1962                      #[cfg(test)]\nuse std::fmt;\n\
1963                      #[cfg(test)]\n#[allow(dead_code)]\nfn d() {}\n\
1964                      #[inline]\n#[allow(dead_code)]\n#[must_use]\n\
1965                      fn f() -> i32 {\n#[cfg(test)]\nfn inner() {}\n1\n}\n\
1966                      mod m {\n#[cfg(test)]\nfn e() {}\n}\n\
1967                      // kept\n#[cfg(test)]\n// pruned\n/* pruned */\nfn g() {}\n\
1968                      /// pruned\n// pruned\n#[cfg(test)]\n/// pruned\nfn h() {}\n\
1969                      // kept\n/// kept\nfn i() {}\n\
1970                      //! kept\n#[cfg(test)]\nfn j() {}\n\
1971                      #[cfg(test)]\n// kept\nuse std::io;\n\
1972                      #[inline]\n#[allow(dead_code)]\n// kept\n";
1973        let code = source.as_bytes();
1974        // Spelled out rather than reused from the production predicates:
1975        // the point is to pin which kinds the prune considers, and
1976        // which rows it reads as one run, so borrowing
1977        // `rust_prunable_item` or `rust_attribute_run_member` would
1978        // assert nothing.
1979        let is_item = |node: &Node| {
1980            matches!(
1981                node.kind_id().into(),
1982                Rust::ModItem
1983                    | Rust::FunctionItem
1984                    | Rust::ImplItem
1985                    | Rust::TraitItem
1986                    | Rust::ConstItem
1987                    | Rust::StaticItem
1988            )
1989        };
1990        let is_member = |node: &Node| {
1991            matches!(
1992                node.kind_id().into(),
1993                Rust::AttributeItem | Rust::LineComment | Rust::BlockComment
1994            )
1995        };
1996        // What opens a run: an attribute, or a comment carrying the
1997        // grammar's `doc_comment` child whose text is not the inner
1998        // `//!` / `/*!` form (#1647).
1999        let opens_run = |node: &Node| {
2000            node.kind_id() == Rust::AttributeItem
2001                || (is_member(node)
2002                    && node.is_child(Rust::DocComment as u16)
2003                    && !code[node.start_byte()..].starts_with(b"//!")
2004                    && !code[node.start_byte()..].starts_with(b"/*!"))
2005        };
2006        // A member is the run's when it opens one, or some member of the
2007        // unbroken stretch before it does.
2008        let in_run = |node: &Node| {
2009            is_member(node)
2010                && (opens_run(node)
2011                    || std::iter::successors(node.previous_sibling(), Node::previous_sibling)
2012                        .take_while(is_member)
2013                        .any(|member| opens_run(&member)))
2014        };
2015        let is_test_only = |node: &Node| {
2016            rust_attribute_run_before(node, code) || rust_inner_attr_marks_test(node, code)
2017        };
2018        let mut pruned = 0_usize;
2019        // The walker's own state, replayed: the last verdict that
2020        // claimed to answer for the nodes after it, and the end of the
2021        // deepest subtree pruned so far. The second is what makes the
2022        // replay a replay — the walker never pushes a skipped node's
2023        // children, so a reach owes them nothing and asserting over
2024        // them would fail on correct code.
2025        let mut reach = SubtreeSkip::RETAIN;
2026        let (mut pruned_through, mut members, mut decorated) = (0_usize, 0_usize, 0_usize);
2027        let visited = for_each_node_with_chain::<RustCode>(code, |node, chain| {
2028            let reference = if in_run(node) {
2029                rust_attributed_item_raw(node)
2030                    .is_some_and(|item| is_item(&item) && is_test_only(&item))
2031            } else {
2032                is_item(node) && is_test_only(node)
2033            };
2034            let verdict = RustCode::should_skip_subtree(node, code, Ancestors::known(chain));
2035            let skipped = verdict.is_skipped();
2036            // A plain comment inside a run is the one member the hook
2037            // never answers for directly: it is `RETAIN` in `O(1)`, and
2038            // the row that opened the run has answered for it through
2039            // the reach, which the replay checks below (#1647).
2040            let answered_by_the_reach = in_run(node) && !opens_run(node);
2041            assert_eq!(
2042                skipped,
2043                reference && !answered_by_the_reach,
2044                "prune decision moved on {} at row {}",
2045                node.kind(),
2046                node.start_row(),
2047            );
2048            if node.start_byte() >= pruned_through {
2049                assert!(
2050                    reach.answers_for(node) || !answered_by_the_reach,
2051                    "no reach answered for the {} at row {}, which the hook leaves to one",
2052                    node.kind(),
2053                    node.start_row(),
2054                );
2055                // What the walker prunes on: the reach where it answers,
2056                // the hook's own verdict otherwise.
2057                let effective = if reach.answers_for(node) {
2058                    // Either the item a run decorates, or a run member or
2059                    // one of its descendants.
2060                    let ends_a_run =
2061                        !is_member(node) && node.previous_sibling().is_some_and(|s| is_member(&s));
2062                    if ends_a_run {
2063                        decorated += 1;
2064                    } else {
2065                        members += 1;
2066                    }
2067                    assert_eq!(
2068                        reach.is_skipped(),
2069                        reference,
2070                        "a reach answered {} for {} at row {}",
2071                        reach.is_skipped(),
2072                        node.kind(),
2073                        node.start_row(),
2074                    );
2075                    reach.is_skipped()
2076                } else {
2077                    reach = verdict;
2078                    skipped
2079                };
2080                if effective {
2081                    pruned_through = pruned_through.max(node.end_byte());
2082                    pruned += 1;
2083                }
2084            }
2085        });
2086        assert!(visited > 0, "fixture must have nodes to compare");
2087        // Every run that decorates an item answers for that item by
2088        // identity (#1783), so the replay checks each such claim against
2089        // the item's own verdict. Thirteen runs end at an item: `mod
2090        // tests`, `static S`, `fn b`, the `use std::fmt`, `fn d`,
2091        // `fn f`, the nested `fn inner` and `fn e`, and the five runs
2092        // with a comment in them — `fn g`, `fn h`, `fn i` (whose `///`
2093        // opens a run with no attribute in it), `fn j` and the
2094        // `use std::io` (#1647). A reach that stopped at the item's start
2095        // byte, as before #1783, reads 0 here.
2096        assert_eq!(decorated, 13, "a run's verdict did not answer for its item");
2097        // Both halves of the reach have to fire, or the assertion above
2098        // is decoration: a run whose members are pruned (`fn d`'s two
2099        // rows) and one whose members are kept (`fn f`'s three, plus
2100        // the trailing pair that decorates nothing at all), the latter
2101        // also carrying each attribute's `#` / `[` / `]` / `attribute`
2102        // children through the same reach.
2103        //
2104        // `fn f`'s body is what makes an over-broad reach fail rather
2105        // than agree by luck. A reach is *always* right about the item
2106        // it stops at — the run's verdict is that item's verdict, by
2107        // construction — so a reach extended one node too far reads as
2108        // correct. Extended over the item's *body*, it swallows the
2109        // nested `#[cfg(test)] fn inner`, and the two answers part
2110        // company (verified by perturbation: `node.start_byte()` to
2111        // `node.end_byte()` in `SubtreeSkip::covering_through_node`
2112        // fails the reach assertion in the replay above, and without
2113        // `fn f`'s body it fails nothing).
2114        //
2115        // The floor below counts run members and their descendants; the
2116        // items, counted apart above, would clear it on their own.
2117        assert!(
2118            members > 4,
2119            "only {members} run members were answered by a reach; the fixture \
2120             must carry runs long enough for the walker to reuse one"
2121        );
2122        // Nine test-only items — `mod tests`, `mod inner`, `fn b`,
2123        // `fn d`, `fn inner`, `fn e`, `fn g`, `fn h` and `fn j` — plus
2124        // the nine `#[…]` rows that mark eight of them (`fn d` carries
2125        // two, `mod inner` an inner attribute that its own subtree
2126        // covers), plus the five comment rows inside those runs: the
2127        // two under `fn g`'s attribute and the three around `fn h`'s
2128        // (#1647). The `fn a` inside `mod tests` is test code too, but
2129        // nothing marks it, so its own verdict keeps it and only its
2130        // pruned parent removes it. Neither `#[allow(dead_code)]` on the
2131        // production `static`, nor `#[cfg(test)]` on either `use` and the
2132        // comment under the second, nor the plain `// kept` rows above
2133        // `fn g` and `fn i`, nor the `//! kept` above `fn j` — an inner
2134        // doc comment documents the file, not the item below it — nor
2135        // the trailing run that decorates nothing, is the prune's to
2136        // take. A hook that pruned everything would satisfy the equality
2137        // above only if the oracle agreed; this pins the count the
2138        // fixture was written for.
2139        assert_eq!(
2140            pruned, 23,
2141            "expected the test-only items, the attributes marking them and the \
2142             comments among those"
2143        );
2144    }
2145
2146    /// A run that decorates nothing still answers for the rest of
2147    /// itself.
2148    ///
2149    /// `#[inline]` with no item after it parses cleanly — no ERROR node,
2150    /// just a `source_file` whose last children are attributes — so the
2151    /// lookahead runs off the end and there is no item to take the reach
2152    /// from. Answering per row there is *correct*, which is exactly why
2153    /// [`rust_should_skip_subtree_matches_the_backward_reading`] cannot
2154    /// see it: dropping this reach costs only time, and a trailing run
2155    /// is unbounded in length like any other.
2156    #[cfg(feature = "rust")]
2157    #[test]
2158    fn a_trailing_attribute_run_answers_for_its_whole_run() {
2159        let source = "fn a() {}\n#[inline]\n#[allow(dead_code)]\n";
2160        let code = source.as_bytes();
2161        let mut attributes: Vec<SubtreeSkip> = Vec::new();
2162        let mut first_answers_second = None;
2163        for_each_node_with_chain::<RustCode>(code, |node, chain| {
2164            if node.kind_id() == Rust::AttributeItem {
2165                if let [first] = attributes[..] {
2166                    first_answers_second = Some(first.answers_for(node));
2167                }
2168                attributes.push(RustCode::should_skip_subtree(
2169                    node,
2170                    code,
2171                    Ancestors::known(chain),
2172                ));
2173            }
2174        });
2175        let [first, second] = attributes[..] else {
2176            panic!("fixture must hold exactly two attributes, got {attributes:?}");
2177        };
2178        assert!(
2179            !first.is_skipped() && !second.is_skipped(),
2180            "a run decorating nothing prunes nothing"
2181        );
2182        assert_eq!(
2183            first_answers_second,
2184            Some(true),
2185            "the first row's verdict must answer for the rest of the run"
2186        );
2187    }
2188
2189    /// A run's verdict answers for the run and for the item it
2190    /// decorates, and stops there: the item's first child starts at the
2191    /// byte the reach ends on, and is asked about on its own (#1783).
2192    ///
2193    /// A direct test of the reach, because no walk over a clean parse
2194    /// shows where it ends: the only other nodes starting on that byte
2195    /// are the item's own leading descendants, which the hook retains
2196    /// whether it is asked or not, and a pruned item's are never
2197    /// visited. Only a recovery tree puts a prunable node there.
2198    #[cfg(feature = "rust")]
2199    #[test]
2200    fn a_run_verdict_answers_for_its_item_and_not_for_the_items_first_child() {
2201        let code = b"#[inline]\nfn f() {}\n";
2202        let mut verdict: Option<SubtreeSkip> = None;
2203        let mut after_the_attribute = Vec::new();
2204        for_each_node_with_chain::<RustCode>(code, |node, chain| {
2205            if let Some(verdict) = verdict {
2206                after_the_attribute.push((
2207                    node.kind(),
2208                    node.start_byte(),
2209                    verdict.answers_for(node),
2210                ));
2211            } else if node.kind_id() == Rust::AttributeItem {
2212                verdict = Some(RustCode::should_skip_subtree(
2213                    node,
2214                    code,
2215                    Ancestors::known(chain),
2216                ));
2217            }
2218        });
2219        // expected: `#[inline]` is bytes 0..9 and `fn f() {}` starts at
2220        // byte 10. The verdict answers for the attribute's five
2221        // descendants, which start before byte 10, and for the
2222        // `function_item`, which it names. The `fn` keyword starts at
2223        // byte 10 as well and is not the named node, so it is not
2224        // answered for, and nothing after it is.
2225        assert_eq!(
2226            after_the_attribute,
2227            [
2228                ("#", 0, true),
2229                ("[", 1, true),
2230                ("attribute", 2, true),
2231                ("identifier", 2, true),
2232                ("]", 8, true),
2233                ("function_item", 10, true),
2234                ("fn", 10, false),
2235                ("identifier", 13, false),
2236                ("parameters", 14, false),
2237                ("(", 14, false),
2238                (")", 15, false),
2239                ("block", 17, false),
2240                ("{", 17, false),
2241                ("}", 18, false),
2242            ]
2243        );
2244    }
2245
2246    #[cfg(feature = "groovy")]
2247    #[test]
2248    fn groovy_is_else_if_recognises_else_followed_by_if() {
2249        // Direct assertion that `GroovyCode::is_else_if` returns true
2250        // for an `if_statement` whose previous sibling is the `else`
2251        // token. Defends the sibling-token strategy against accidental
2252        // regression to a `false` stub (lesson 10, #115 / #239).
2253        let src = "if (x) { } else if (y) { } else { }";
2254        let parser =
2255            GroovyParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.groovy"), None);
2256        let outer =
2257            find_first_kind(&parser, Groovy::IfStatement as u16).expect("outer if_statement");
2258        // Locate the inner if_statement (in the `alternative` slot of
2259        // the outer if, after the `else` token).
2260        let mut inner: Option<Node> = None;
2261        for i in 0..outer.child_count() {
2262            if let Some(c) = outer.child(i)
2263                && c.kind_id() == Groovy::IfStatement as u16
2264            {
2265                inner = Some(c);
2266                break;
2267            }
2268        }
2269        let inner = inner.expect("expected an inner if_statement");
2270        assert!(
2271            GroovyCode::is_else_if(&inner, Ancestors::unknown()),
2272            "inner if_statement after `else` must be recognised as else-if"
2273        );
2274        assert!(
2275            !GroovyCode::is_else_if(&outer, Ancestors::unknown()),
2276            "outer if_statement must not be recognised as else-if"
2277        );
2278    }
2279
2280    #[cfg(feature = "groovy")]
2281    #[test]
2282    fn groovy_is_else_if_false_for_standalone_if() {
2283        // A bare `if` (no `else` preceding it) must NOT register as
2284        // an else-if.
2285        let src = "if (x) { println(x) }";
2286        let parser =
2287            GroovyParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.groovy"), None);
2288        let node = find_first_kind(&parser, Groovy::IfStatement as u16).expect("if_statement");
2289        assert!(!GroovyCode::is_else_if(&node, Ancestors::unknown()));
2290    }
2291
2292    #[cfg(feature = "groovy")]
2293    #[test]
2294    fn groovy_is_call_excludes_constructors() {
2295        // Regression for #430. `GroovyCode::is_call` previously matched
2296        // `ObjectCreationExpression`, so `new Foo()` was counted as a
2297        // call in Groovy but not in Java/C# (whose `is_call` is method
2298        // invocation only). The Java-family convention is that `is_call`
2299        // (the `--ops`/`call` filter) counts method/function call sites
2300        // only; constructors are an ABC concern. This test mixes all
2301        // three Groovy call-shaped forms and pins the count at 2:
2302        //   * `new Foo()`        -> object_creation_expression (NOT a call)
2303        //   * `a.bar()`          -> method_invocation           (a call)
2304        //   * `println "hi"`     -> command_chain               (a call)
2305        // Pre-fix this count was 3 (the constructor was miscounted).
2306        let src = "def m() {\n  def a = new Foo()\n  a.bar()\n  println \"hi\"\n}\n";
2307        let parser =
2308            GroovyParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.groovy"), None);
2309        assert_eq!(
2310            count(&parser, &["call".to_string()]).0,
2311            2,
2312            "is_call must count method_invocation + command_chain only, not the constructor"
2313        );
2314
2315        // Direct predicate assertions: the constructor node must be
2316        // rejected while both genuine call forms are accepted.
2317        let ctor = find_first_kind(&parser, Groovy::ObjectCreationExpression as u16)
2318            .expect("object_creation_expression");
2319        assert!(
2320            !GroovyCode::is_call(&ctor),
2321            "object_creation_expression must not be a call"
2322        );
2323        let method =
2324            find_first_kind(&parser, Groovy::MethodInvocation as u16).expect("method_invocation");
2325        assert!(
2326            GroovyCode::is_call(&method),
2327            "method_invocation must be a call"
2328        );
2329        let chain = find_first_kind(&parser, Groovy::CommandChain as u16).expect("command_chain");
2330        assert!(GroovyCode::is_call(&chain), "command_chain must be a call");
2331    }
2332
2333    #[cfg(feature = "csharp")]
2334    #[test]
2335    fn csharp_is_call_excludes_constructors() {
2336        // The C# half of the `is_call` contract documented on the
2337        // `Checker::is_call` trait method (#1456), mirroring the #430 test
2338        // above. C# spells four call-shaped constructs that ABC counts
2339        // as branches and this filter must not count as call sites:
2340        //
2341        //   * `new Foo()`                  -> object_creation_expression
2342        //   * `: this(a)`                  -> constructor_initializer
2343        //   * `class Sub(int x) : Base(x)` -> base_list > argument_list
2344        //   * `record R(int x) : Base(x)`  -> base_list >
2345        //                                     primary_constructor_base_type
2346        //
2347        // paired with one genuine call, `Helper(f)`. The fixture scores
2348        // `abc.branches` 5 and `call` 1, so widening `is_call` to any of
2349        // the four moves the count asserted here.
2350        let src = "class Sub(int x) : Base(x) {
2351                       public Sub(int a, int b) : this(a) { }
2352                       void M() { var f = new Foo(); Helper(f); }
2353                   }
2354                   record R(int x) : Base(x);";
2355        let parser = CsharpParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.cs"), None);
2356        assert_eq!(
2357            count(&parser, &["call".to_string()]).0,
2358            1,
2359            "is_call must count `Helper(f)` only, not the four constructions"
2360        );
2361
2362        let call = find_first_kind(&parser, Csharp::InvocationExpression3 as u16)
2363            .expect("invocation_expression");
2364        assert!(
2365            CsharpCode::is_call(&call),
2366            "an invocation_expression is a call"
2367        );
2368        // §2 drift markers for the other two ids the `Call` row of
2369        // `roles/csharp.rs` owns. All three render to
2370        // `"invocation_expression"`, and at the 0.23.5 pin every
2371        // spelling probed with `bca dump` — plain, `this.`-qualified,
2372        // `base.`-qualified, inside a query clause, a lambda body, an
2373        // attribute argument, an interpolation, a `when` guard and a
2374        // constant pattern — emits only the aliased id. The claim these
2375        // pin is therefore about *this* fixture; a grammar bump that
2376        // starts spelling an ordinary call with either id fails the
2377        // count above as well, since neither is `find_first_kind`'s
2378        // target here.
2379        for (id, name) in [
2380            (Csharp::InvocationExpression, "InvocationExpression"),
2381            (Csharp::InvocationExpression2, "InvocationExpression2"),
2382        ] {
2383            assert!(
2384                !ast_has_kind_id(&parser, id as u16),
2385                "{name} is unobserved at this grammar pin; its arm is defensive"
2386            );
2387        }
2388
2389        for (id, what) in [
2390            (Csharp::ObjectCreationExpression as u16, "`new Foo()`"),
2391            (Csharp::ConstructorInitializer as u16, "`: this(a)`"),
2392            (
2393                Csharp::PrimaryConstructorBaseType as u16,
2394                "a record's `: Base(x)`",
2395            ),
2396        ] {
2397            let node = find_first_kind(&parser, id)
2398                .unwrap_or_else(|| panic!("fixture must contain {what}"));
2399            assert!(
2400                !CsharpCode::is_call(&node),
2401                "{what} is an ABC branch, not a call site"
2402            );
2403        }
2404
2405        // The `class` spelling of the primary-constructor base call is a
2406        // bare `argument_list` under the `base_list`, and preorder reaches
2407        // `Sub`'s before the four that belong to `: this(a)`, `new Foo()`,
2408        // `Helper(f)` and the record's `: Base(x)` — the parent assertion
2409        // is what keeps this pointing at the construction rather than at
2410        // one of those.
2411        let base_args =
2412            find_first_kind(&parser, Csharp::ArgumentList as u16).expect("argument_list");
2413        assert_eq!(
2414            base_args.parent().map(|p| p.kind_id()),
2415            Some(Csharp::BaseList2 as u16),
2416            "the first argument_list must be `class Sub(int x) : Base(x)`'s"
2417        );
2418        assert!(
2419            !CsharpCode::is_call(&base_args),
2420            "a class's primary-constructor base call is an ABC branch, not a call site"
2421        );
2422    }
2423
2424    // ===== C-family `is_call` regression tests (issue #1254) =====
2425
2426    // Every C-family grammar here references `preproc_call_expression`
2427    // only under an `alias(…, $.call_expression)` — zero bare references
2428    // in `grammar.json`, and no entry in `node-types.json` — so the
2429    // unsuffixed `CallExpression` never reaches `kind_id()` while the
2430    // aliased `CallExpression2` carries every real call.
2431    //
2432    // The two halves do different jobs. The first keeps the fixture an
2433    // honest witness: a grammar bump that stops emitting the alias must
2434    // fail here rather than silently weaken the counts below. The second
2435    // cannot fail against the current parse tables — `ts_symbol_map`
2436    // rewrites the unsuffixed symbol onto the aliased one for *every*
2437    // input — so it is a drift marker, not a live guard: it fires only if
2438    // a bump renumbers the enum or stops aliasing the rule, which is
2439    // exactly what justifies keeping the unsuffixed arm defensively
2440    // (the grammar-dispatch §2 technique, applied to an alias-mapped
2441    // rule rather than a hidden one).
2442    #[cfg(any(feature = "c", feature = "cpp", feature = "mozcpp"))]
2443    #[track_caller]
2444    fn assert_call_kinds_are_aliased<P: ParserTrait>(
2445        parser: &P,
2446        lang: &str,
2447        aliased: u16,
2448        unsuffixed: u16,
2449    ) {
2450        assert!(
2451            ast_has_kind_id(parser, aliased),
2452            "{lang}: fixture must emit the aliased call_expression kind"
2453        );
2454        assert!(
2455            !ast_has_kind_id(parser, unsuffixed),
2456            "{lang}: the unsuffixed CallExpression is the aliased-away \
2457             preproc_call_expression and must not surface"
2458        );
2459    }
2460
2461    // Six calls — statement position, initializer, `if` condition, both
2462    // binary operands, and the `return` operand. The other parenthesised
2463    // shapes are deliberate negatives: the `int f(int);` prototype's
2464    // `function_declarator`, the `sizeof(int)` operand, and the `(int)x`
2465    // cast. Six differs from the C++ fixture's five, so a test that
2466    // reaches for the wrong parser cannot pass on the right number.
2467    #[cfg(feature = "c")]
2468    const C_CALL_SHAPES: &str = "int f(int);\n\
2469                                 int main(void) {\n\
2470                                 f(1);\n\
2471                                 int x = g(2);\n\
2472                                 if (h(3)) { }\n\
2473                                 int y = a(4) + b(5);\n\
2474                                 int z = sizeof(int) + (int)x + y;\n\
2475                                 return c(z);\n\
2476                                 }\n";
2477
2478    // Five calls — member (`t.m()`), arrow member (`p->m()`), qualified
2479    // (`ns::f()`), and both function-pointer spellings (`fp(2)`,
2480    // `(*fp)(3)`). `T t(1)` and `new T(4)` are the negatives that matter:
2481    // object creation is an ABC concern, not a call site, matching Groovy /
2482    // Java / C# (#430). Functional-style `T(4)` is deliberately absent
2483    // from the fixture — the grammar emits it as a plain `call_expression`,
2484    // so it *is* counted, and including it here would blur what the five
2485    // is pinning.
2486    #[cfg(any(feature = "cpp", feature = "mozcpp"))]
2487    const CPP_CALL_SHAPES: &str = "struct T { T(int); int m(); };\n\
2488                                   namespace ns { int f(); }\n\
2489                                   int main() {\n\
2490                                   T t(1);\n\
2491                                   t.m();\n\
2492                                   T *p = &t;\n\
2493                                   p->m();\n\
2494                                   ns::f();\n\
2495                                   int (*fp)(int) = nullptr;\n\
2496                                   fp(2);\n\
2497                                   (*fp)(3);\n\
2498                                   T *q = new T(4);\n\
2499                                   delete q;\n\
2500                                   return sizeof(T);\n\
2501                                   }\n";
2502
2503    /// Every `call_expression` the pinned C grammar emits carries the
2504    /// *aliased* `CallExpression2` kind_id. The unsuffixed variant is the
2505    /// grammar's `preproc_call_expression`, referenced only under an
2506    /// `alias(…, $.call_expression)` — it is absent from `node-types.json`
2507    /// and never reaches `kind_id()`. Matching it alone left `is_call`
2508    /// dead: `bca count -t call` reported 0 on ordinary C (#1254).
2509    #[cfg(feature = "c")]
2510    #[test]
2511    fn c_is_call_matches_the_aliased_call_expression() {
2512        let parser = CParser::new(
2513            C_CALL_SHAPES.as_bytes().to_vec(),
2514            &PathBuf::from("test.c"),
2515            None,
2516        );
2517
2518        assert_call_kinds_are_aliased(
2519            &parser,
2520            "C",
2521            C::CallExpression2 as u16,
2522            C::CallExpression as u16,
2523        );
2524
2525        assert_eq!(
2526            count(&parser, &["call".to_string()]).0,
2527            6,
2528            "is_call must match every call_expression the C grammar emits"
2529        );
2530
2531        // Parenthesised non-call shapes stay out. The exact count above is
2532        // the sharper guard — these rows document the intended boundary
2533        // and catch a future edit that widens the match to them.
2534        for (kind, label) in [
2535            (C::SizeofExpression as u16, "sizeof_expression"),
2536            (C::CastExpression as u16, "cast_expression"),
2537            (C::FunctionDeclarator as u16, "function_declarator"),
2538        ] {
2539            let node = find_first_kind(&parser, kind).expect(label);
2540            assert!(!CCode::is_call(&node), "{label} must not be a call");
2541        }
2542    }
2543
2544    /// C++ counterpart of [`c_is_call_matches_the_aliased_call_expression`].
2545    /// Member, qualified and function-pointer calls all arrive as the same
2546    /// aliased `CallExpression2`; object construction does not (#1254).
2547    #[cfg(feature = "cpp")]
2548    #[test]
2549    fn cpp_is_call_matches_the_aliased_call_expression() {
2550        let parser = CppParser::new(
2551            CPP_CALL_SHAPES.as_bytes().to_vec(),
2552            &PathBuf::from("test.cpp"),
2553            None,
2554        );
2555
2556        assert_call_kinds_are_aliased(
2557            &parser,
2558            "Cpp",
2559            Cpp::CallExpression2 as u16,
2560            Cpp::CallExpression as u16,
2561        );
2562
2563        assert_eq!(
2564            count(&parser, &["call".to_string()]).0,
2565            5,
2566            "is_call must match member, qualified and function-pointer \
2567             calls, and only those"
2568        );
2569
2570        // `new T(4)` and `sizeof(T)` are call-shaped but not call sites.
2571        for (kind, label) in [
2572            (Cpp::NewExpression as u16, "new_expression"),
2573            (Cpp::SizeofExpression as u16, "sizeof_expression"),
2574            (Cpp::InitDeclarator as u16, "init_declarator"),
2575        ] {
2576            let node = find_first_kind(&parser, kind).expect(label);
2577            assert!(!CppCode::is_call(&node), "{label} must not be a call");
2578        }
2579    }
2580
2581    /// `Mozcpp` owns no file extension, so nothing routes to it and it
2582    /// gets no integration-snapshot coverage. Pin it against its
2583    /// extension-owning sibling instead: the Mozilla fork inherits
2584    /// upstream C++'s aliasing, so the same source must yield the same
2585    /// calls (grammar-dispatch, "sweep the rest").
2586    #[cfg(all(feature = "cpp", feature = "mozcpp"))]
2587    #[test]
2588    fn mozcpp_is_call_agrees_with_cpp() {
2589        let source = CPP_CALL_SHAPES.as_bytes().to_vec();
2590        let mozcpp = MozcppParser::new(source.clone(), &PathBuf::from("test.cpp"), None);
2591        let cpp = CppParser::new(source, &PathBuf::from("test.cpp"), None);
2592
2593        assert_call_kinds_are_aliased(
2594            &mozcpp,
2595            "Mozcpp",
2596            Mozcpp::CallExpression2 as u16,
2597            Mozcpp::CallExpression as u16,
2598        );
2599
2600        let mozcpp_calls = count(&mozcpp, &["call".to_string()]).0;
2601        assert_eq!(
2602            mozcpp_calls, 5,
2603            "Mozcpp must count the same five calls as C++"
2604        );
2605        assert_eq!(
2606            mozcpp_calls,
2607            count(&cpp, &["call".to_string()]).0,
2608            "Mozcpp is the Mozilla C++ fork; is_call must not diverge \
2609             from CppCode on shared source"
2610        );
2611
2612        let new_expr =
2613            find_first_kind(&mozcpp, Mozcpp::NewExpression as u16).expect("new_expression");
2614        assert!(
2615            !MozcppCode::is_call(&new_expr),
2616            "new_expression must not be a call"
2617        );
2618    }
2619
2620    #[cfg(feature = "python")]
2621    fn parse_python(src: &str) -> PythonParser {
2622        PythonParser::new(src.as_bytes().to_vec(), &PathBuf::from("test.py"), None)
2623    }
2624
2625    // Walk the AST and return every node whose `kind_id` equals `target`,
2626    // in DFS pre-order. Used by the Python `is_else_if` tests below to
2627    // distinguish the outer if from the inner one in an `else: if` chain.
2628    #[cfg(feature = "python")]
2629    fn find_all_kinds<P: ParserTrait>(parser: &P, target: u16) -> Vec<Node<'_>> {
2630        let mut out = Vec::new();
2631        let mut stack = vec![parser.root()];
2632        while let Some(node) = stack.pop() {
2633            if node.kind_id() == target {
2634                out.push(node);
2635            }
2636            for i in (0..node.child_count()).rev() {
2637                if let Some(c) = node.child(i) {
2638                    stack.push(c);
2639                }
2640            }
2641        }
2642        out
2643    }
2644
2645    #[cfg(feature = "python")]
2646    #[test]
2647    fn python_is_else_if_recognises_if_inside_else_clause() {
2648        // `else: if b:` chains parse as `else_clause → block → if_statement`
2649        // (the `block` wrapper is Python-specific). `is_else_if` must
2650        // walk through that wrapper. Regression for #276 (the stub
2651        // returned `false` unconditionally).
2652        let src = "if a:\n    pass\nelse:\n    if b:\n        pass\n";
2653        let parser = parse_python(src);
2654        let outer =
2655            find_first_kind(&parser, Python::IfStatement as u16).expect("outer if_statement");
2656        let inner =
2657            find_python_if_inside_else_block(&parser).expect("inner if_statement under else");
2658        assert!(
2659            PythonCode::is_else_if(&inner, Ancestors::unknown()),
2660            "if_statement inside else_clause's block must be recognised as else-if"
2661        );
2662        assert!(
2663            !PythonCode::is_else_if(&outer, Ancestors::unknown()),
2664            "outer if_statement must not be recognised as else-if"
2665        );
2666    }
2667
2668    #[cfg(feature = "python")]
2669    #[test]
2670    fn python_is_else_if_false_for_standalone_if() {
2671        // A bare `if` whose parent is the module / function body must
2672        // NOT register as an else-if.
2673        let src = "if a:\n    pass\n";
2674        let parser = parse_python(src);
2675        let node = find_first_kind(&parser, Python::IfStatement as u16).expect("if_statement");
2676        assert!(!PythonCode::is_else_if(&node, Ancestors::unknown()));
2677    }
2678
2679    #[cfg(feature = "python")]
2680    #[test]
2681    fn python_is_else_if_false_for_outer_if_with_elif_alternative() {
2682        // `elif` parses as an `ElifClause`, not an `IfStatement`, so the
2683        // only `IfStatement` in `if … elif …` is the outer one. Its
2684        // parent is the module / function body, not an `else_clause`.
2685        // Pins that the presence of `elif` in the AST does not trip
2686        // `is_else_if` for the outer `if`.
2687        let src = "if a:\n    pass\nelif b:\n    pass\n";
2688        let parser = parse_python(src);
2689        let outer = find_first_kind(&parser, Python::IfStatement as u16).expect("if_statement");
2690        assert!(!PythonCode::is_else_if(&outer, Ancestors::unknown()));
2691    }
2692
2693    // Return the inner `if_statement` that sits directly inside an
2694    // `else_clause`'s `block` wrapper, or `None` if no such node exists.
2695    // Used by tests below instead of relying on `find_all_kinds`'s DFS
2696    // pre-order to land at `ifs[1]`.
2697    #[cfg(feature = "python")]
2698    fn find_python_if_inside_else_block(parser: &PythonParser) -> Option<Node<'_>> {
2699        find_all_kinds(parser, Python::IfStatement as u16)
2700            .into_iter()
2701            .find(|n| {
2702                n.parent().is_some_and(|p| {
2703                    matches!(p.kind_id().into(), Python::Block | Python::Block2)
2704                        && p.parent()
2705                            .is_some_and(|gp| gp.kind_id() == Python::ElseClause)
2706                })
2707            })
2708    }
2709
2710    #[cfg(feature = "python")]
2711    #[test]
2712    fn python_is_else_if_false_when_else_body_has_siblings() {
2713        // `else: if b:` followed by another statement at the same indent
2714        // is a real nested-if, not a chain. The block has 2 named
2715        // children, so `is_else_if` must return false.
2716        let src = "if a:\n    pass\nelse:\n    if b:\n        pass\n    pass\n";
2717        let parser = parse_python(src);
2718        let inner =
2719            find_python_if_inside_else_block(&parser).expect("inner if_statement under else");
2720        assert!(
2721            !PythonCode::is_else_if(&inner, Ancestors::unknown()),
2722            "inner if must NOT be recognised as else-if when its block has siblings"
2723        );
2724    }
2725
2726    // Drift guard for #419: tree-sitter-python lists hidden aliases for
2727    // both `block` and `lambda` that are NOT emitted today —
2728    // `Block` (135, the hidden `_block` supertype; only `Block2` 160 is
2729    // emitted) and `Lambda2` (197, an unseen lambda alias; only
2730    // `Lambda` 196 and the `lambda` keyword token `Lambda3` 73 appear).
2731    // Several metric sites (`is_closure` — which now routes through
2732    // `cognitive::python_is_lambda`, the three cognitive lambda-scope
2733    // sites it feeds (#422), `is_else_if`, `python_is_block` in npa,
2734    // npm's class-body lookup, loc's no-op arm) already enumerate these
2735    // aliases defensively so a future grammar bump that promotes either
2736    // supertype to a concrete node cannot silently undercount.
2737    // This test pins their current absence across representative Python
2738    // (function, class, if/for bodies, lambda); if a bump ever emits one,
2739    // the guard flips red and forces a positive assertion to be added —
2740    // mirroring the `Php::String3` hidden-supertype guard above.
2741    #[cfg(feature = "python")]
2742    #[test]
2743    fn python_hidden_block_and_lambda_aliases_stay_unseen() {
2744        let src = "def f(a, b):\n    if a:\n        return b\n    for x in b:\n        print(x)\n\nclass C:\n    def m(self):\n        pass\n\ng = lambda x: x + 1\n";
2745        let parser = parse_python(src);
2746
2747        // Confirm the LIVE aliases actually surface, so this fixture is
2748        // a meaningful witness (a guard that never parses a block or a
2749        // lambda would pass vacuously).
2750        assert!(
2751            ast_has_kind_id(&parser, Python::Block2 as u16),
2752            "expected Python::Block2 (160, the emitted `block`) in the parse",
2753        );
2754        assert!(
2755            ast_has_kind_id(&parser, Python::Lambda as u16),
2756            "expected Python::Lambda (196, the emitted `lambda`) in the parse",
2757        );
2758
2759        // The hidden supertypes must NOT surface. If either now appears,
2760        // add a positive assertion routing it through the relevant
2761        // predicate (see #419).
2762        assert!(
2763            !ast_has_kind_id(&parser, Python::Block as u16),
2764            "Python::Block (135) is the hidden `_block` supertype; if it now appears, route it through python_is_block and assert positively (#419)",
2765        );
2766        assert!(
2767            !ast_has_kind_id(&parser, Python::Lambda2 as u16),
2768            "Python::Lambda2 (197) is an unseen lambda alias; if it now appears, cognitive::python_is_lambda (reused by is_closure and the three cognitive lambda-scope sites) must detect it and a positive closure assertion is required (#419/#422)",
2769        );
2770    }
2771
2772    // #422: the cognitive lambda-alias chokepoint and `is_closure` must
2773    // recognise the *same* live `lambda` node. Before #422, cognitive's
2774    // three lambda sites compared against `Lambda` (196) only while
2775    // `is_closure` accepted `Lambda | Lambda2`; both now route through
2776    // `cognitive::python_is_lambda`, so this pins that they agree on the
2777    // emitted `Lambda` and that the predicate is not vacuously true (it
2778    // rejects the enclosing `FunctionDefinition`). The unseen `Lambda2`
2779    // half of the set is covered by the drift guard above.
2780    #[cfg(feature = "python")]
2781    #[test]
2782    fn python_is_lambda_matches_live_lambda_and_agrees_with_is_closure() {
2783        use crate::lang_helpers::python::python_is_lambda;
2784
2785        let parser = parse_python("def f():\n    return lambda x: x and x\n");
2786        let lambda = find_first_kind(&parser, Python::Lambda as u16)
2787            .expect("the lambda expression must parse as Python::Lambda (196)");
2788
2789        assert!(
2790            python_is_lambda(&lambda),
2791            "python_is_lambda must accept the emitted Lambda node",
2792        );
2793        assert!(
2794            PythonCode::is_closure(&lambda, Ancestors::unknown()),
2795            "is_closure must agree with python_is_lambda on the same lambda node",
2796        );
2797
2798        // Not vacuously true: a non-lambda node (the enclosing function)
2799        // must be rejected, so the predicate is discriminating.
2800        let func = find_first_kind(&parser, Python::FunctionDefinition as u16)
2801            .expect("the def must parse as Python::FunctionDefinition");
2802        assert!(
2803            !python_is_lambda(&func),
2804            "python_is_lambda must reject a non-lambda node",
2805        );
2806    }
2807
2808    /// The two `is_else_if` implementations that answer a flat `false`
2809    /// are a behavioural claim, not a placeholder: the language has no
2810    /// `else if` *chain* to collapse, so every `if` it contains is a
2811    /// freshly nested branch and pays cognitive nesting.
2812    ///
2813    /// Neither is reachable from a metric walk — `Preproc` and
2814    /// `Ccomment` (which inherit the `Checker` default) have no `if`
2815    /// construct at all, and Elixir's branching is `cond do` or nested
2816    /// `if/else` — so nothing else in the suite executes them. #1084
2817    /// changed both signatures to take `Ancestors`, which is exactly the
2818    /// kind of edit that can quietly invert a one-line predicate, so pin
2819    /// the contract directly.
2820    #[cfg(all(feature = "c-family-helpers", feature = "elixir"))]
2821    #[test]
2822    fn languages_without_else_if_chains_answer_false() {
2823        // The `Checker` default, via the two grammars that do not
2824        // override it.
2825        let preproc = PreprocParser::new(b"#define A 1\n".to_vec(), &PathBuf::from("a.h"), None);
2826        let ccomment = CcommentParser::new(b"/* c */\n".to_vec(), &PathBuf::from("a.c"), None);
2827        assert!(
2828            !PreprocCode::is_else_if(&preproc.root(), Ancestors::unknown()),
2829            "the Checker default must answer false"
2830        );
2831        assert!(
2832            !CcommentCode::is_else_if(&ccomment.root(), Ancestors::unknown()),
2833            "the Checker default must answer false"
2834        );
2835
2836        // Elixir's explicit override, asserted on a real `if` node so the
2837        // test would catch an impl that started consulting the ancestor
2838        // chain and got the answer wrong.
2839        let parser = ElixirParser::new(
2840            b"defmodule M do\n  def f(a) do\n    if a do\n      if a do\n        :ok\n      end\n    end\n  end\nend\n".to_vec(),
2841            std::path::Path::new("m.ex"),
2842            None,
2843        );
2844        let ifs: Vec<_> = parser
2845            .root()
2846            .preorder()
2847            .filter(|n| {
2848                n.kind() == "call"
2849                    && n.utf8_text(parser.code())
2850                        .is_some_and(|t| t.starts_with("if"))
2851            })
2852            .collect();
2853        assert!(
2854            ifs.len() >= 2,
2855            "fixture must contain a nested if, else the assertion below is vacuous"
2856        );
2857        for node in &ifs {
2858            assert!(
2859                !ElixirCode::is_else_if(node, Ancestors::unknown()),
2860                "Elixir has no else-if chain; every if is a fresh branch"
2861            );
2862        }
2863    }
2864
2865    // Regression for #301: every language's `StringLit` row must still
2866    // recognise its canonical string literal via the `"string"` filter
2867    // (which routes through `Checker::is_string_with_code`, the row's
2868    // `owns`). The positive test now drills down to
2869    // every individual variant of every multi-variant language so a
2870    // future macro invocation that drops a variant (e.g. forgetting
2871    // `Cpp::ConcatenatedString` after a grammar bump) fails loudly.
2872    //
2873    // The JS-family languages (Mozjs/Javascript/Typescript/Tsx) read
2874    // the shared `js_family_strings!` fragment and have their own
2875    // alias-aware tests above; they are intentionally not duplicated
2876    // here.
2877    #[cfg(any(
2878        feature = "bash",
2879        feature = "c-family-helpers",
2880        feature = "cpp",
2881        feature = "csharp",
2882        feature = "elixir",
2883        feature = "go",
2884        feature = "groovy",
2885        feature = "irules",
2886        feature = "java",
2887        feature = "kotlin",
2888        feature = "lua",
2889        feature = "perl",
2890        feature = "php",
2891        feature = "python",
2892        feature = "ruby",
2893        feature = "rust",
2894        feature = "tcl",
2895    ))]
2896    fn count_with_parser<P: ParserTrait>(parser: &P) -> usize {
2897        count(parser, &["string".to_string()]).0
2898    }
2899
2900    // Assert that `target` kind_id appears in the parse and every
2901    // such node matches `is_string`. The two-step check makes test
2902    // failures unambiguous: a presence failure means the fixture no
2903    // longer produces the variant (likely grammar drift); a match
2904    // failure means a macro invocation dropped the variant.
2905    #[cfg(any(
2906        feature = "bash",
2907        feature = "c-family-helpers",
2908        feature = "cpp",
2909        feature = "csharp",
2910        feature = "elixir",
2911        feature = "go",
2912        feature = "groovy",
2913        feature = "irules",
2914        feature = "java",
2915        feature = "kotlin",
2916        feature = "lua",
2917        feature = "perl",
2918        feature = "php",
2919        feature = "python",
2920        feature = "ruby",
2921        feature = "rust",
2922        feature = "tcl",
2923    ))]
2924    fn assert_variant_is_string<P: ParserTrait, F: Fn(&Node) -> bool>(
2925        parser: &P,
2926        target: u16,
2927        is_string: F,
2928        lang: &str,
2929        variant: &str,
2930    ) {
2931        assert!(
2932            ast_has_kind_id(parser, target),
2933            "{lang}::{variant} (kind_id {target}) did not appear in the parse — fixture broken",
2934        );
2935        assert!(
2936            count_string_matches_for_kind(parser, target, is_string) > 0,
2937            "{lang}::{variant} must route through is_string",
2938        );
2939    }
2940
2941    // Collapses the 6-line-per-variant `assert_variant_is_string`
2942    // call into a single token per variant. `$lang` is the language
2943    // enum (e.g. `Cpp`); `$code` is the `Checker`-implementing type
2944    // (e.g. `CppCode`); the trailing list names the enum variants to
2945    // exercise. The macro feeds `stringify!` for both the language
2946    // and variant labels so test failures keep the same "Lang::Variant"
2947    // wording the helper already emits.
2948    #[cfg(all(
2949        feature = "bash",
2950        feature = "c-family-helpers",
2951        feature = "cpp",
2952        feature = "csharp",
2953        feature = "elixir",
2954        feature = "go",
2955        feature = "groovy",
2956        feature = "irules",
2957        feature = "java",
2958        feature = "kotlin",
2959        feature = "lua",
2960        feature = "perl",
2961        feature = "php",
2962        feature = "python",
2963        feature = "ruby",
2964        feature = "rust",
2965        feature = "tcl",
2966    ))]
2967    macro_rules! assert_variants_is_string {
2968        ($parser:expr, $lang:ident, $code:ident, [$($variant:ident),+ $(,)?]) => {
2969            $(
2970                assert_variant_is_string(
2971                    $parser,
2972                    $lang::$variant as u16,
2973                    $code::is_string,
2974                    stringify!($lang),
2975                    stringify!($variant),
2976                );
2977            )+
2978        };
2979    }
2980
2981    // Parse `$src` with `$parser_ty` and assert the generic `"string"`
2982    // filter yields zero matches. Used by the negative test, which
2983    // walks every language's `StringLit` row with identical per-language
2984    // shape (parse → count → assert_eq! 0).
2985    #[cfg(all(
2986        feature = "bash",
2987        feature = "c-family-helpers",
2988        feature = "cpp",
2989        feature = "csharp",
2990        feature = "elixir",
2991        feature = "go",
2992        feature = "groovy",
2993        feature = "irules",
2994        feature = "java",
2995        feature = "kotlin",
2996        feature = "lua",
2997        feature = "perl",
2998        feature = "php",
2999        feature = "python",
3000        feature = "ruby",
3001        feature = "rust",
3002        feature = "tcl",
3003    ))]
3004    macro_rules! assert_no_string_matches {
3005        ($parser_ty:ident, $path:expr, $src:expr, $lang:literal $(,)?) => {{
3006            let parser = $parser_ty::new($src.to_vec(), $path, None);
3007            assert_eq!(count_with_parser(&parser), 0, $lang);
3008        }};
3009    }
3010
3011    #[cfg(all(
3012        feature = "bash",
3013        feature = "c-family-helpers",
3014        feature = "cpp",
3015        feature = "csharp",
3016        feature = "elixir",
3017        feature = "go",
3018        feature = "groovy",
3019        feature = "irules",
3020        feature = "java",
3021        feature = "kotlin",
3022        feature = "lua",
3023        feature = "perl",
3024        feature = "php",
3025        feature = "python",
3026        feature = "ruby",
3027        feature = "rust",
3028        feature = "tcl",
3029    ))]
3030    #[test]
3031    fn simple_is_string_macro_recognises_each_language() {
3032        use crate::langs::{
3033            CcommentParser, CppParser, CsharpParser, ElixirParser, GoParser, GroovyParser,
3034            IrulesParser, JavaParser, KotlinParser, LuaParser, PerlParser, PreprocParser,
3035            PythonParser, RubyParser, RustParser, TclParser,
3036        };
3037
3038        let path = PathBuf::from("test");
3039
3040        // ---- Preproc (2 variants): StringLiteral, RawStringLiteral ----
3041        let src = b"#include \"foo.h\"\nR\"(raw)\"\n".to_vec();
3042        let parser = PreprocParser::new(src, &path, None);
3043        assert_variants_is_string!(
3044            &parser,
3045            Preproc,
3046            PreprocCode,
3047            [StringLiteral, RawStringLiteral]
3048        );
3049
3050        // ---- Ccomment (2 variants): StringLiteral, RawStringLiteral ----
3051        // The Ccomment grammar is a stub that only emits Comment /
3052        // StringLiteral / RawStringLiteral; feed it both forms.
3053        let src = b"\"hello\"\nR\"(raw)\"\n".to_vec();
3054        let parser = CcommentParser::new(src, &path, None);
3055        assert_variants_is_string!(
3056            &parser,
3057            Ccomment,
3058            CcommentCode,
3059            [StringLiteral, RawStringLiteral]
3060        );
3061
3062        // ---- Cpp (3 variants): StringLiteral, ConcatenatedString, RawStringLiteral ----
3063        // C++ string concatenation (`"a" "b"`) produces a
3064        // `concatenated_string` node wrapping the literals.
3065        let src =
3066            b"const char* a = \"hi\";\nconst char* b = \"a\" \"b\";\nconst char* c = R\"(raw)\";\n"
3067                .to_vec();
3068        let parser = CppParser::new(src, &path, None);
3069        assert_variants_is_string!(
3070            &parser,
3071            Cpp,
3072            CppCode,
3073            [StringLiteral, ConcatenatedString, RawStringLiteral]
3074        );
3075
3076        // ---- Python (2 variants): String, ConcatenatedString ----
3077        // Python concatenates adjacent string literals into a
3078        // `concatenated_string` node.
3079        let src = b"a = \"hi\"\nb = \"a\" \"b\"\n".to_vec();
3080        let parser = PythonParser::new(src, &path, None);
3081        assert_variants_is_string!(&parser, Python, PythonCode, [String, ConcatenatedString]);
3082
3083        // ---- Java (2 variants): StringLiteral, MultilineStringLiteral ----
3084        // `Java::MultilineStringLiteral` maps to `_multiline_string_literal`
3085        // (leading-underscore hidden supertype) and does NOT surface as a
3086        // concrete kind_id in observed parses. Triple-quoted text blocks
3087        // instead produce regular `StringLiteral` nodes. The variant is
3088        // intentionally listed in the macro so a future grammar revision
3089        // that promotes it can't bypass `is_string`; presence is asserted
3090        // below to flag drift.
3091        let src = b"class C { String a = \"hi\"; String b = \"\"\"\nmulti\n\"\"\"; }\n".to_vec();
3092        let parser = JavaParser::new(src, &path, None);
3093        assert_variants_is_string!(&parser, Java, JavaCode, [StringLiteral]);
3094        assert!(
3095            !ast_has_kind_id(&parser, Java::MultilineStringLiteral as u16),
3096            "Java::MultilineStringLiteral is documented as the hidden _multiline_string_literal supertype; if it now appears in parses, replace this with a positive variant assertion",
3097        );
3098
3099        // ---- Csharp (4 variants): StringLiteral, VerbatimStringLiteral,
3100        // RawStringLiteral, InterpolatedStringExpression ----
3101        // Verbatim: `@"..."`; raw: triple-double-quote; interpolated: `$"..."`.
3102        let src = b"class C { string a = \"hi\"; string b = @\"verb\"; string c = \"\"\"raw\"\"\"; string d = $\"int{1}\"; }\n".to_vec();
3103        let parser = CsharpParser::new(src, &path, None);
3104        assert_variants_is_string!(
3105            &parser,
3106            Csharp,
3107            CsharpCode,
3108            [
3109                StringLiteral,
3110                VerbatimStringLiteral,
3111                RawStringLiteral,
3112                InterpolatedStringExpression,
3113            ]
3114        );
3115
3116        // ---- Rust (2 variants): StringLiteral, RawStringLiteral ----
3117        let src = b"fn main() { let a = \"hi\"; let b = r\"raw\"; }\n".to_vec();
3118        let parser = RustParser::new(src, &path, None);
3119        assert_variants_is_string!(&parser, Rust, RustCode, [StringLiteral, RawStringLiteral]);
3120
3121        // ---- Go (2 variants): InterpretedStringLiteral, RawStringLiteral ----
3122        // Backtick-delimited string is the raw form.
3123        let src = b"package main\nfunc main() { _ = \"hi\"; _ = `raw` }\n".to_vec();
3124        let parser = GoParser::new(src, &path, None);
3125        assert_variants_is_string!(
3126            &parser,
3127            Go,
3128            GoCode,
3129            [InterpretedStringLiteral, RawStringLiteral]
3130        );
3131
3132        // ---- Kotlin (2 variants): StringLiteral, MultilineStringLiteral ----
3133        let src = b"fun main() { val a = \"hi\"; val b = \"\"\"multi\"\"\" }\n".to_vec();
3134        let parser = KotlinParser::new(src, &path, None);
3135        assert_variants_is_string!(
3136            &parser,
3137            Kotlin,
3138            KotlinCode,
3139            [StringLiteral, MultilineStringLiteral]
3140        );
3141
3142        // ---- Lua (1 variant): String ----
3143        let src = b"local a = \"hi\"\nlocal b = [[long]]\n".to_vec();
3144        let parser = LuaParser::new(src, &path, None);
3145        assert_variants_is_string!(&parser, Lua, LuaCode, [String]);
3146
3147        // ---- Perl (7 variants): StringSingleQuoted, StringDoubleQuoted,
3148        // StringQQuoted, StringQqQuoted, BacktickQuoted, CommandQxQuoted,
3149        // HeredocBodyStatement ----
3150        let src = b"my $a = 'single';\nmy $b = \"double\";\nmy $c = q(qquoted);\nmy $d = qq(qqquoted);\nmy $e = `cmd`;\nmy $f = qx(qxcmd);\nmy $g = <<EOT;\nbody\nEOT\n".to_vec();
3151        let parser = PerlParser::new(src, &path, None);
3152        assert_variants_is_string!(
3153            &parser,
3154            Perl,
3155            PerlCode,
3156            [
3157                StringSingleQuoted,
3158                StringDoubleQuoted,
3159                StringQQuoted,
3160                StringQqQuoted,
3161                BacktickQuoted,
3162                CommandQxQuoted,
3163                HeredocBodyStatement,
3164            ]
3165        );
3166
3167        // ---- Bash (5 variants): String, RawString, AnsiCString,
3168        // TranslatedString, HeredocBody2 ----
3169        // TranslatedString surfaces as a wrapper node only in
3170        // assignment-style contexts (see `bash_is_string_matches_translated_string`).
3171        let src = b"a=\"d\"\nb='r'\nc=$'ansi'\nd=$\"t\"\ncat <<EOF\nbody\nEOF\n".to_vec();
3172        let parser = crate::langs::BashParser::new(src, &path, None);
3173        assert_variants_is_string!(
3174            &parser,
3175            Bash,
3176            BashCode,
3177            [
3178                String,
3179                RawString,
3180                AnsiCString,
3181                TranslatedString,
3182                HeredocBody2
3183            ]
3184        );
3185
3186        // ---- Tcl (3 variants): QuotedWord, BracedWord, BracedWordSimple ----
3187        // Tcl uses two `braced_word` rules: the named rule `braced_word`
3188        // (an argument-position braced expression that admits commands
3189        // and substitutions, e.g. `proc ... { body }`'s `body` arg) and
3190        // `braced_word_simple` (a plain inert braced word like
3191        // `{braced}` in `set v {braced}`). The fixture below mixes a
3192        // `proc ... {body}` (BracedWord), a simple `set` assignment
3193        // (BracedWordSimple), and a `set` to a quoted literal
3194        // (QuotedWord).
3195        let src = b"set a \"quoted\"\nset b {braced}\nproc p {x y} { return $x }\n".to_vec();
3196        let parser = TclParser::new(src, &path, None);
3197        assert_variants_is_string!(
3198            &parser,
3199            Tcl,
3200            TclCode,
3201            [QuotedWord, BracedWordSimple, BracedWord]
3202        );
3203
3204        // ---- iRules (3 variants): QuotedWord, BracedWord, BracedWordSimple ----
3205        // Same Tcl-family braced-word split as Tcl above: the `proc`
3206        // body is a named `braced_word` (BracedWord), the simple `set`
3207        // assignment is a `braced_word_simple` (BracedWordSimple), and
3208        // the quoted literal is a `QuotedWord`.
3209        let src = b"set a \"quoted\"\nset b {braced}\nproc p {x y} { return $x }\n".to_vec();
3210        let parser = IrulesParser::new(src, &path, None);
3211        assert_variants_is_string!(
3212            &parser,
3213            Irules,
3214            IrulesCode,
3215            [QuotedWord, BracedWordSimple, BracedWord]
3216        );
3217
3218        // ---- Php (6 variants): String, String3, EncapsedString,
3219        // Heredoc, Nowdoc, ShellCommandExpression ----
3220        // The `: string` return type in the fixture produces a
3221        // `String2` — the `string` *type* keyword, which is NOT a
3222        // variant here: #1474 withdrew it, and
3223        // `php_is_string_excludes_type_keyword_alias_1474` pins its
3224        // absence. String3 is the hidden `_string` supertype (kind_id
3225        // => "_string" — name starts with `_`), which tree-sitter does
3226        // NOT emit as a concrete node — see its empirical absence
3227        // asserted below.
3228        let src = b"<?php function f(): string { $a = 'single'; $b = \"double\"; $c = <<<EOT\nbody\nEOT;\n$d = <<<'EOT'\nnow\nEOT;\n$e = `ls`; return $a; }\n".to_vec();
3229        let parser = PhpParser::new(src, &path, None);
3230        assert_variants_is_string!(&parser, Php, PhpCode, [String]);
3231        // `Php::String3` is the hidden `_string` supertype — never
3232        // surfaces as a concrete kind_id in observed parses; the
3233        // checker still lists it so future grammar revisions that
3234        // promote it cannot silently bypass `is_string`. Verified
3235        // unreachable empirically (assertion below proves the
3236        // fixture does not produce it; the variant is intentionally
3237        // unverifiable through a positive test until then).
3238        assert!(
3239            !ast_has_kind_id(&parser, Php::String3 as u16),
3240            "Php::String3 is documented as the hidden _string supertype; if it now appears in parses, add a positive variant assertion",
3241        );
3242        assert_variants_is_string!(
3243            &parser,
3244            Php,
3245            PhpCode,
3246            [EncapsedString, Heredoc, Nowdoc, ShellCommandExpression]
3247        );
3248
3249        // ---- Elixir (3 variants): String, Charlist, Sigil ----
3250        // Charlists use single quotes; sigils use `~s(...)` etc.
3251        let src = b"a = \"hi\"\nb = 'charlist'\nc = ~s(sigil)\n".to_vec();
3252        let parser = ElixirParser::new(src, &path, None);
3253        assert_variants_is_string!(&parser, Elixir, ElixirCode, [String, Charlist, Sigil]);
3254
3255        // ---- Ruby (11 variants): String, ChainedString, BareString,
3256        // Subshell, Regex, HeredocBody, DelimitedSymbol, SimpleSymbol,
3257        // StringArray, SymbolArray, Character ----
3258        // ChainedString: two adjacent string literals (`"a" "b"`).
3259        // BareString: an unquoted element inside `%w[...]` / inside
3260        // a string array context. `%w[bare1 bare2]` emits a
3261        // StringArray whose children are BareString nodes — both
3262        // surface in the parse. Use a script that produces every
3263        // form so the per-variant assertion can hit each.
3264        let src = b"a = \"hi\"\nb = \"x\" \"y\"\nc = `cmd`\nd = /re/\ne = <<EOT\nbody\nEOT\nf = :sym\ng = :\"dsym\"\nh = %w[bare1 bare2]\ni = %i[s1 s2]\nj = ?A\n".to_vec();
3265        let parser = RubyParser::new(src, &path, None);
3266        assert_variants_is_string!(
3267            &parser,
3268            Ruby,
3269            RubyCode,
3270            [
3271                String,
3272                ChainedString,
3273                BareString,
3274                Subshell,
3275                Regex,
3276                HeredocBody,
3277                DelimitedSymbol,
3278                SimpleSymbol,
3279                StringArray,
3280                SymbolArray,
3281                Character,
3282            ]
3283        );
3284
3285        // ---- Groovy (1 variant): StringLiteral ----
3286        // The dekobon Groovy grammar consolidates every string shape
3287        // (single / double / triple-quoted, slashy `/.../`, dollar-
3288        // slashy `$/.../$`, GString-interpolated) under one
3289        // `string_literal` rule, so a single variant suffices —
3290        // unlike Java, character literals are not a separate node.
3291        let src =
3292            b"def m() { def a = \"hi\"; def b = \"\"\"multi\"\"\"; def c = /pat/ }\n".to_vec();
3293        let parser = GroovyParser::new(src, &path, None);
3294        assert_variants_is_string!(&parser, Groovy, GroovyCode, [StringLiteral]);
3295    }
3296
3297    #[cfg(all(
3298        feature = "bash",
3299        feature = "c-family-helpers",
3300        feature = "cpp",
3301        feature = "csharp",
3302        feature = "elixir",
3303        feature = "go",
3304        feature = "groovy",
3305        feature = "irules",
3306        feature = "java",
3307        feature = "kotlin",
3308        feature = "lua",
3309        feature = "perl",
3310        feature = "php",
3311        feature = "python",
3312        feature = "ruby",
3313        feature = "rust",
3314        feature = "tcl",
3315    ))]
3316    #[test]
3317    fn simple_is_string_macro_rejects_non_string_nodes() {
3318        // Pure-identifier source must produce zero string matches.
3319        // Catches a regression where a row accidentally lists a
3320        // too-broad kind (e.g. `Identifier`). Covers every language's
3321        // `StringLit` row.
3322        use crate::langs::{
3323            BashParser, CcommentParser, CppParser, CsharpParser, ElixirParser, GoParser,
3324            GroovyParser, IrulesParser, JavaParser, KotlinParser, LuaParser, PerlParser,
3325            PreprocParser, PythonParser, RubyParser, RustParser, TclParser,
3326        };
3327
3328        let path = PathBuf::from("test");
3329
3330        // Each fixture is the most minimal identifier-only input that
3331        // still parses for the target language. Per-language comments
3332        // below flag the few cases where the input choice is load-
3333        // bearing (Bash `s=$y` to avoid `string`-kind expansion nodes,
3334        // Tcl `set x $y` to keep the bareword as `Word`, etc.).
3335        assert_no_string_matches!(PreprocParser, &path, b"#define FOO 1\n", "Preproc");
3336        // Ccomment: input that lexes as a single line comment only.
3337        assert_no_string_matches!(CcommentParser, &path, b"// just a comment\n", "Ccomment");
3338        assert_no_string_matches!(CppParser, &path, b"int main() { return x; }\n", "Cpp");
3339        assert_no_string_matches!(PythonParser, &path, b"x = y\n", "Python");
3340        assert_no_string_matches!(JavaParser, &path, b"class C { int x = y; }\n", "Java");
3341        // Csharp: identifier-only field initializer.
3342        assert_no_string_matches!(CsharpParser, &path, b"class C { int x = y; }\n", "Csharp");
3343        assert_no_string_matches!(RustParser, &path, b"fn main() { let x = y; }\n", "Rust");
3344        assert_no_string_matches!(
3345            GoParser,
3346            &path,
3347            b"package main\nfunc main() { _ = x }\n",
3348            "Go"
3349        );
3350        assert_no_string_matches!(KotlinParser, &path, b"fun main() { val x = y }\n", "Kotlin");
3351        // Perl: identifier-only assignment with no quoted forms.
3352        assert_no_string_matches!(PerlParser, &path, b"my $x = $y;\n", "Perl");
3353        assert_no_string_matches!(LuaParser, &path, b"local x = y\n", "Lua");
3354        // Bash: assignment of one variable to another, no literals.
3355        // `s=$y` produces only Variable/SimpleExpansion nodes; no
3356        // string-kind node should appear.
3357        assert_no_string_matches!(BashParser, &path, b"s=$y\n", "Bash");
3358        // Tcl: `set` of an unquoted identifier word. The unquoted
3359        // bareword surfaces as `Word`, not any of the three string
3360        // kinds.
3361        assert_no_string_matches!(TclParser, &path, b"set x $y\n", "Tcl");
3362        // iRules: same Tcl-family `set` of an unquoted identifier word —
3363        // the bareword surfaces as `Word`, not any string kind.
3364        assert_no_string_matches!(IrulesParser, &path, b"set x $y\n", "Irules");
3365        // Php: identifier-only assignment.
3366        assert_no_string_matches!(PhpParser, &path, b"<?php $x = $y;\n", "Php");
3367        // Elixir: integer assignment, no string/charlist/sigil.
3368        assert_no_string_matches!(ElixirParser, &path, b"x = 1\n", "Elixir");
3369        assert_no_string_matches!(RubyParser, &path, b"x = y\n", "Ruby");
3370        // Groovy: identifier-only method body.
3371        assert_no_string_matches!(GroovyParser, &path, b"def m() { def x = y }\n", "Groovy");
3372    }
3373
3374    #[cfg(feature = "mozjs")]
3375    #[test]
3376    fn mozjs_parses_using_declaration() {
3377        // Drift marker for the JS-base-grammar bump 0.23.1 -> 0.25.0
3378        // (#407): the `using` / `await using` explicit-resource-
3379        // management declaration is a 0.25.0 grammar feature. The
3380        // bundled mozjs parser was previously stale at 0.23.1 while
3381        // its marker claimed 0.25.0 (the #400 baseline lie), so this
3382        // node could not appear. Asserting it surfaces pins the regen
3383        // against reversion — it fails against the pre-#407 parser.
3384        let src = "function f() {\n  using r = acquire();\n  return r;\n}\n";
3385        let parser = MozjsParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.js"), None);
3386        assert!(
3387            ast_has_kind_id(&parser, Mozjs::UsingDeclaration as u16),
3388            "expected Mozjs::UsingDeclaration to appear in the parse",
3389        );
3390    }
3391
3392    #[cfg(feature = "go")]
3393    #[test]
3394    fn go_rune_literal_is_not_a_string() {
3395        // #699 verdict: Go `RuneLiteral` is an operand in `get_op_type`
3396        // and is flattened by the alterator, but it is deliberately
3397        // excluded from `is_string` — a rune is a character (`int32`),
3398        // not a string, exactly as Rust/Cpp `CharLiteral` are operand +
3399        // flattened yet absent from their `is_string`. This pins the
3400        // exclusion: the fixture must produce a `rune_literal` (proving
3401        // the surrounding grammar still emits it) while `GoCode::is_string`
3402        // returns false for it. The flattening half lives in
3403        // `alterator.rs::go_rune_literal_flattened_but_not_a_string_kind`.
3404        use crate::langs::GoParser;
3405        let path = PathBuf::from("test.go");
3406        let src = b"package main\nfunc main() { r := 'x'; _ = r }\n".to_vec();
3407        let parser = GoParser::new(src, &path, None);
3408        let rune_id = Go::RuneLiteral as u16;
3409        assert!(
3410            ast_has_kind_id(&parser, rune_id),
3411            "fixture should produce a rune_literal node",
3412        );
3413        assert_eq!(
3414            count_string_matches_for_kind(&parser, rune_id, GoCode::is_string),
3415            0,
3416            "Go rune_literal must not match is_string (a rune is a char, not a string)",
3417        );
3418    }
3419
3420    #[cfg(all(feature = "c", feature = "cpp", feature = "mozcpp", feature = "objc"))]
3421    #[test]
3422    fn c_family_char_literal_is_not_a_string() {
3423        // The C-family half of the #699 verdict `go_rune_literal_is_not_a_string`
3424        // cites: a `char_literal` is flattened by the alterator and — since
3425        // #1316 — is a Halstead operand, yet it is deliberately absent from
3426        // `is_string`, because a character is not a string.
3427        //
3428        // #1316 made that citation true rather than aspirational (the operand
3429        // half had never been implemented), so the exclusion is now a live
3430        // decision and wants a pin of its own.
3431        //
3432        // Each row is two-sided. The `char_literal` count must be zero, and
3433        // the `string_literal` in the same fixture must be one — otherwise a
3434        // predicate that had stopped matching anything at all would read as a
3435        // correctly-rejected character. The `ast_has_kind_id` guard covers the
3436        // third way to get a zero: a fixture that no longer parses to a
3437        // `char_literal` at all.
3438        use crate::langs::{CParser, CppParser, MozcppParser, ObjcParser};
3439
3440        #[cfg(any(feature = "c", feature = "cpp", feature = "mozcpp", feature = "objc"))]
3441        fn check<P: ParserTrait, F: Fn(&Node) -> bool + Copy>(
3442            source: &[u8],
3443            file: &str,
3444            (char_literal, string_literal): (u16, u16),
3445            is_string: F,
3446            label: &str,
3447        ) {
3448            let parser = P::new(source.to_vec(), &PathBuf::from(file), None);
3449            assert!(
3450                ast_has_kind_id(&parser, char_literal),
3451                "{label}: fixture should produce a char_literal node",
3452            );
3453            assert_eq!(
3454                count_string_matches_for_kind(&parser, char_literal, is_string),
3455                0,
3456                "{label}: char_literal must not match is_string (a char is not a string)",
3457            );
3458            assert_eq!(
3459                count_string_matches_for_kind(&parser, string_literal, is_string),
3460                1,
3461                "{label}: is_string must still match the fixture's string_literal, or the \
3462                 zero above is a dead predicate rather than a rejected character",
3463            );
3464        }
3465
3466        let src = b"char a = 'x';\nconst char *b = \"s\";\n";
3467        check::<CParser, _>(
3468            src,
3469            "t.c",
3470            (C::CharLiteral as u16, C::StringLiteral as u16),
3471            CCode::is_string,
3472            "c",
3473        );
3474        check::<CppParser, _>(
3475            src,
3476            "t.cpp",
3477            (Cpp::CharLiteral as u16, Cpp::StringLiteral as u16),
3478            CppCode::is_string,
3479            "cpp",
3480        );
3481        check::<MozcppParser, _>(
3482            src,
3483            "t.cpp",
3484            (Mozcpp::CharLiteral as u16, Mozcpp::StringLiteral as u16),
3485            MozcppCode::is_string,
3486            "mozcpp",
3487        );
3488        check::<ObjcParser, _>(
3489            src,
3490            "t.m",
3491            (Objc::CharLiteral as u16, Objc::StringLiteral as u16),
3492            ObjcCode::is_string,
3493            "objc",
3494        );
3495    }
3496
3497    /// Asserts `is_func_with_code` / `is_closure` answer the same off a known
3498    /// chain as off a `Node::parent` climb, for every node of `code`.
3499    /// Returns the `(functions, closures)` the chain path counted, so a
3500    /// caller can additionally pin what the predicates actually decided.
3501    ///
3502    /// Both predicates fold their ancestor lookups into one boolean, so
3503    /// a wrong ancestor does not fail — it silently moves a function
3504    /// into the closure column. The counters keep a fixture honest: both
3505    /// answers have to occur, for both predicates, or the parity holds
3506    /// only over nodes the predicates never classify.
3507    #[cfg(any(
3508        feature = "javascript",
3509        feature = "mozjs",
3510        feature = "ruby",
3511        feature = "typescript"
3512    ))]
3513    fn assert_func_parity<L: crate::traits::LanguageInfo + Checker>(
3514        label: &str,
3515        code: &[u8],
3516    ) -> (usize, usize) {
3517        let mut funcs = 0;
3518        let mut closures = 0;
3519        let visited = for_each_node_with_chain::<L>(code, |node, chain| {
3520            let known = Ancestors::known(chain);
3521            let climbing = Ancestors::unknown();
3522            assert_eq!(
3523                L::is_func_with_code(node, code, known),
3524                L::is_func_with_code(node, code, climbing),
3525                "{label}: is_func_with_code disagrees on {} at row {}",
3526                node.kind(),
3527                node.start_row()
3528            );
3529            assert_eq!(
3530                L::is_closure(node, known),
3531                L::is_closure(node, climbing),
3532                "{label}: is_closure disagrees on {} at row {}",
3533                node.kind(),
3534                node.start_row()
3535            );
3536            funcs += usize::from(L::is_func_with_code(node, code, known));
3537            closures += usize::from(L::is_closure(node, known));
3538        });
3539        assert!(visited > 20, "{label}: fixture is too small to prove much");
3540        assert!(
3541            funcs > 0 && closures > 0,
3542            "{label}: fixture must contain both a named function and a closure, \
3543             else parity holds over nodes the walk never classifies: \
3544             {funcs} functions, {closures} closures"
3545        );
3546        (funcs, closures)
3547    }
3548
3549    /// The JS-family `is_func_with_code` / `is_closure` must classify a
3550    /// node the same whether they read the walker's ancestor chain or
3551    /// climb with `Node::parent` (#1088).
3552    ///
3553    /// These are the predicates with the longest ancestor lookup: an
3554    /// upward walk, its `is_else_if` filter, and a `has_sibling`
3555    /// adjacency check.
3556    #[cfg(all(feature = "javascript", feature = "mozjs", feature = "typescript"))]
3557    #[test]
3558    fn js_func_and_closure_agree_between_known_and_climbing() {
3559        // One of each shape the walk distinguishes: an arrow bound to a
3560        // name, an arrow passed positionally, a `function` expression
3561        // named by an object `pair`, and a nested arrow whose only
3562        // enclosing frame is a `statement_block`.
3563        //
3564        // The returned object literal is load-bearing. It is the one
3565        // shape here where the trailing `has_sibling` adjacency check
3566        // decides the answer: the upward walk stops at the `return`
3567        // having counted no binding, so whether the arrow is a *named*
3568        // function rests entirely on the `property_identifier` beside
3569        // it. Everywhere else a binding is found first and the adjacency
3570        // check is never reached, which would leave a wrong parent
3571        // lookup invisible.
3572        let code = concat!(
3573            "const f = a => { g(() => 1); a => 2; };\n",
3574            "const o = { m: function () { return 1; } };\n",
3575            "function h() { return { k: (a) => a + 1 }; }\n",
3576            "function i() { return function () { return 2; }; }\n",
3577        )
3578        .as_bytes();
3579        // `js_family_binding_gates!` and the `FuncOpener` / `Closure`
3580        // rows expand separately against each grammar's own `kind_id`
3581        // enum, so the four impls are four distinct variant lists rather
3582        // than one shared body. Checking only JavaScript would leave a
3583        // drifted id in any of the other three uncovered.
3584        assert_func_parity::<crate::langs::JavascriptCode>("javascript", code);
3585        assert_func_parity::<crate::langs::MozjsCode>("mozjs", code);
3586        assert_func_parity::<crate::langs::TypescriptCode>("typescript", code);
3587        assert_func_parity::<crate::langs::TsxCode>("tsx", code);
3588    }
3589
3590    /// Ruby's `is_closure` is the one non-JS predicate that needs an
3591    /// ancestor: a `{ … }` block is a closure unless its parent is the
3592    /// `Lambda` that already counted it (#465), so it reads the chain
3593    /// for the same reason the JS family does (#1088).
3594    ///
3595    /// The stabby lambda is the discriminating shape. Its body block is
3596    /// the only node here whose answer depends on the parent lookup —
3597    /// every other block's parent is a `Call`, which the arm accepts
3598    /// whether the lookup is right or wrong.
3599    #[cfg(feature = "ruby")]
3600    #[test]
3601    fn ruby_block_closure_agrees_between_known_and_climbing() {
3602        let code = concat!(
3603            "def m\n",
3604            "  f = ->(z) { z + 1 }\n",
3605            "  [1].each { |x| x }\n",
3606            "  lambda { 2 }\n",
3607            "end\n",
3608        )
3609        .as_bytes();
3610        let (funcs, closures) = assert_func_parity::<crate::langs::RubyCode>("ruby", code);
3611        assert_eq!(funcs, 1, "only `def m` is a named function");
3612        assert_eq!(
3613            closures, 3,
3614            "the stabby lambda, the `each` block and the `lambda` block \
3615             are three closures — the stabby lambda's own body block must \
3616             not add a fourth, which is the answer the parent lookup decides"
3617        );
3618    }
3619
3620    /// The verdicts the byte-less and the source-aware `is_string` give
3621    /// the `braced_word`-kind nodes of `code`, as their source texts,
3622    /// plus how many string-kind nodes of *any other* kind were seen.
3623    ///
3624    /// Returns `(kept_literal, withdrawn, other_strings)`. Texts rather
3625    /// than counts because a count is polarity-blind: `(1, 1)` holds
3626    /// just as well when the predicate calls the `proc` body a literal
3627    /// and `{a b}` a script, which is the claim inverted. `other_strings`
3628    /// anchors the control the third fixture line supplies — without it
3629    /// the every-other-kind assertion below can be deleted from the
3630    /// fixture and the kind-gate perturbation stops failing anything.
3631    ///
3632    /// Also asserts the two spellings agree off a known chain and off a
3633    /// `Node::parent` climb: the walk now threads a chain, and the
3634    /// answer must not depend on which it gets.
3635    #[cfg(any(feature = "irules", feature = "tcl"))]
3636    fn braced_word_string_verdicts<L: crate::traits::LanguageInfo + Checker>(
3637        label: &str,
3638        code: &[u8],
3639        script_kind: u16,
3640    ) -> (Vec<String>, Vec<String>, usize) {
3641        let (mut kept, mut withdrawn, mut other) = (Vec::new(), Vec::new(), 0);
3642        for_each_node_with_chain::<L>(code, |node, chain| {
3643            let known = L::is_string_with_code(node, code, Ancestors::known(chain));
3644            assert_eq!(
3645                known,
3646                L::is_string_with_code(node, code, Ancestors::unknown()),
3647                "{label}: is_string_with_code disagrees between a known chain and a \
3648                 parent climb on {} at row {}",
3649                node.kind(),
3650                node.start_row()
3651            );
3652            if node.kind_id() != script_kind {
3653                // Every other kind must answer identically, or the
3654                // override has widened past the one ambiguous kind.
3655                assert_eq!(
3656                    known,
3657                    L::is_string(node),
3658                    "{label}: the override moved a {} node at row {}",
3659                    node.kind(),
3660                    node.start_row()
3661                );
3662                other += usize::from(known);
3663                return;
3664            }
3665            assert!(
3666                L::is_string(node),
3667                "{label}: the kind table must still list the script kind, or this \
3668                 test is measuring its absence rather than the override"
3669            );
3670            let text = String::from_utf8_lossy(&code[node.start_byte()..node.end_byte()]);
3671            if known {
3672                kept.push(text.into_owned());
3673            } else {
3674                withdrawn.push(text.into_owned());
3675            }
3676        });
3677        (kept, withdrawn, other)
3678    }
3679
3680    /// A Tcl-family script body is a string literal to
3681    /// [`Checker::is_string`] and not to
3682    /// [`Checker::is_string_with_code`] (#1381).
3683    ///
3684    /// This is the test the end-to-end `bca find` ones cannot be: they
3685    /// observe the *result*, which is equally consistent with the
3686    /// override never firing and the byte-less default happening to be
3687    /// right. Asserting the disagreement directly is what makes a future
3688    /// call site that reaches for the byte-less spelling a wrong answer
3689    /// rather than an indistinguishable one
3690    /// (`docs/development/grammar_dispatch.md` §7).
3691    ///
3692    /// Each fixture holds a braced value, a script body reached through
3693    /// a *modelled* construct, a script body reached through the
3694    /// **command-name** list (`eval`), and a non-braced string literal —
3695    /// four rows that no constant and no inverted polarity satisfies.
3696    /// The two script routes are structurally independent
3697    /// (grammar-dispatch §11): `is_value_braced_word` answers "script"
3698    /// either because the word fills a modelled slot or because the
3699    /// enclosing command is in `SCRIPT_TAKING_COMMANDS`, and a fixture
3700    /// exercising only the first leaves the second dead.
3701    #[test]
3702    #[cfg(any(feature = "tcl", feature = "irules"))]
3703    fn tcl_script_body_is_a_string_only_to_the_byteless_spelling() {
3704        let mut ran = 0;
3705        #[cfg(feature = "tcl")]
3706        {
3707            ran += 1;
3708            // `{x}` is the parameter list, which the grammar spells
3709            // `arguments` rather than a braced word, so it is neither.
3710            // `set s "q"` is the control for the kind gate: a
3711            // `quoted_word` under a *modelled* command is a node the
3712            // role predicate answers "not a value" for, so an override
3713            // that dropped its `kind_id` test would unstring it — which
3714            // the `other` count below is what notices.
3715            let (kept, withdrawn, other) = braced_word_string_verdicts::<crate::langs::TclCode>(
3716                "tcl",
3717                b"proc p {x} { puts $x }\nlappend l {a b}\neval {puts hi}\nset s \"q\"\n",
3718                Tcl::BracedWord as u16,
3719            );
3720            assert_eq!(kept, ["{a b}"], "tcl: only the braced value is a literal");
3721            assert_eq!(
3722                withdrawn,
3723                ["{ puts $x }", "{puts hi}"],
3724                "tcl: the proc body (a modelled slot) and the `eval` argument \
3725                 (a named script-taking command) are both scripts"
3726            );
3727            assert_eq!(other, 1, "tcl: the `set` quoted word stays a string");
3728        }
3729        #[cfg(feature = "irules")]
3730        {
3731            ran += 1;
3732            // The `"hi"` inside the handler body is this dialect's
3733            // `other` row, so the control sits inside the construct
3734            // under test rather than beside it.
3735            let (kept, withdrawn, other) = braced_word_string_verdicts::<crate::langs::IrulesCode>(
3736                "irules",
3737                b"when HTTP_REQUEST { log local0. \"hi\" }\nlappend l {x y}\neval {puts hi}\n",
3738                Irules::BracedWord as u16,
3739            );
3740            assert_eq!(
3741                kept,
3742                ["{x y}"],
3743                "irules: only the braced value is a literal"
3744            );
3745            assert_eq!(
3746                withdrawn,
3747                ["{ log local0. \"hi\" }", "{puts hi}"],
3748                "irules: the `when` handler body and the `eval` argument are scripts"
3749            );
3750            assert_eq!(other, 1, "irules: the quoted word stays a string");
3751        }
3752        assert!(
3753            ran > 0,
3754            "neither tcl nor irules is enabled; this test asserted nothing"
3755        );
3756    }
3757
3758    /// A Perl bareword is a call to [`Checker::is_call`] and, as a
3759    /// wrapper's callee or an auto-quoted key, not to
3760    /// [`Checker::is_call_with_code`] (#1580). The end-to-end
3761    /// `find --type call` tests observe the result, which is equally
3762    /// consistent with the override never firing; this asserts the
3763    /// disagreement, so a call site reaching for the byte-less spelling
3764    /// is wrong rather than indistinguishable (grammar-dispatch §7).
3765    ///
3766    /// Three structurally independent routes withdraw a bareword — key
3767    /// position, the spaced wrapper's callee, the bracketed wrapper's
3768    /// callee — and two keep one: a bareword argument and a lone
3769    /// bareword (grammar-dispatch §11). The two wrappers are the control
3770    /// for the kind gate: both spellings must still call them.
3771    #[test]
3772    #[cfg(feature = "perl")]
3773    fn perl_bareword_is_a_call_only_to_the_byteless_spelling() {
3774        let code = b"my %h = (name => 1);\nprint shift;\nfoo(1);\nfoo;\n";
3775        let (mut kept, mut withdrawn, mut other) = (Vec::new(), Vec::new(), 0);
3776        for_each_node_with_chain::<crate::langs::PerlCode>(code, |node, chain| {
3777            let known = PerlCode::is_call_with_code(node, code, Ancestors::known(chain));
3778            assert_eq!(
3779                known,
3780                PerlCode::is_call_with_code(node, code, Ancestors::unknown()),
3781                "known chain and parent climb disagree on {} at row {}",
3782                node.kind(),
3783                node.start_row()
3784            );
3785            if node.kind_id() != Perl::CallExpressionWithBareword as u16 {
3786                assert_eq!(
3787                    known,
3788                    PerlCode::is_call(node),
3789                    "the override moved a {} node at row {}",
3790                    node.kind(),
3791                    node.start_row()
3792                );
3793                other += usize::from(known);
3794                return;
3795            }
3796            assert!(
3797                PerlCode::is_call(node),
3798                "the kind table must still list the bareword kind, or this test is \
3799                 measuring its absence rather than the override"
3800            );
3801            let text =
3802                String::from_utf8_lossy(&code[node.start_byte()..node.end_byte()]).into_owned();
3803            if known {
3804                kept.push(text);
3805            } else {
3806                withdrawn.push(text);
3807            }
3808        });
3809        assert_eq!(
3810            kept,
3811            ["shift", "foo"],
3812            "a bareword argument and a lone bareword are calls"
3813        );
3814        assert_eq!(
3815            withdrawn,
3816            ["name", "print", "foo"],
3817            "an auto-quoted key and the callee inside either wrapper are not"
3818        );
3819        assert_eq!(other, 2, "the two wrappers stay calls to both spellings");
3820    }
3821
3822    /// The value slots of the three constructs whose argument lists hold
3823    /// both roles stay string literals, though `is_value_braced_word`
3824    /// classifies each construct whole as script-taking
3825    /// (`Getter::is_braced_literal_slot`).
3826    ///
3827    /// Every fixture line carries a literal *and* a script in the same
3828    /// construct, so each rule is pinned from both sides: a rule that
3829    /// withdrew the whole construct fails on the literal, and one that
3830    /// rescued it whole fails on the script. The two switch lines are the
3831    /// guards' own rows — an arm whose *pattern* is spelled `proc`, `on`
3832    /// or `trap` parses as that construct around arm bodies, which must
3833    /// stay scripts. They need a line each: `proc {…} on {…}` parses as
3834    /// one `procedure`, so only the second line puts an `on` *command*
3835    /// in front of the owner guard.
3836    ///
3837    /// The Tcl `trap` line stands alone because the walk helper refuses a
3838    /// tree with a parse error, and `try {…} trap …` on one line reaches
3839    /// the same generic `trap` command only through error recovery (a
3840    /// missing terminator the grammar inserts after the `try` body).
3841    #[test]
3842    #[cfg(any(feature = "tcl", feature = "irules"))]
3843    fn tcl_family_value_slots_of_script_takers_stay_strings() {
3844        let mut ran = 0;
3845        #[cfg(feature = "tcl")]
3846        {
3847            ran += 1;
3848            let (kept, withdrawn, _) = braced_word_string_verdicts::<crate::langs::TclCode>(
3849                "tcl",
3850                b"proc {my proc} {x} { puts $x }\n\
3851                  namespace export {a b}\n\
3852                  namespace eval ns { puts hi }\n\
3853                  namespace ensemble create -map {add ::a}\n\
3854                  trap {POSIX ENOENT} {msg} { puts $msg }\n\
3855                  switch $k { proc {puts p} on {puts o} }\n\
3856                  switch $k { on {puts o} trap {puts t} }\n",
3857                Tcl::BracedWord as u16,
3858            );
3859            assert_eq!(
3860                kept,
3861                ["{my proc}", "{a b}", "{add ::a}", "{POSIX ENOENT}", "{msg}"],
3862                "tcl: a proc name, a non-`eval` namespace argument, and a \
3863                 `trap` pattern and variable list are literals"
3864            );
3865            assert_eq!(
3866                withdrawn,
3867                [
3868                    "{ puts $x }",
3869                    "{ puts hi }",
3870                    "{ puts $msg }",
3871                    "{ proc {puts p} on {puts o} }",
3872                    "{puts p}",
3873                    "{puts o}",
3874                    "{ on {puts o} trap {puts t} }",
3875                    "{puts o}",
3876                    "{puts t}",
3877                ],
3878                "tcl: the proc body, the `namespace eval` body, the `trap` \
3879                 script, and the switch arm list and its bodies are scripts"
3880            );
3881        }
3882        #[cfg(feature = "irules")]
3883        {
3884            ran += 1;
3885            let (kept, withdrawn, other) = braced_word_string_verdicts::<crate::langs::IrulesCode>(
3886                "irules",
3887                b"proc {my proc} {x} { log local0. $x }\n\
3888                  namespace export {a b}\n\
3889                  when HTTP_REQUEST { log local0. \"hi\" }\n\
3890                  on error {m2} {drop}\n",
3891                Irules::BracedWord as u16,
3892            );
3893            assert_eq!(
3894                kept,
3895                ["{my proc}", "{a b}", "{m2}"],
3896                "irules: a proc name, a `namespace` value and an `on` variable \
3897                 list are literals"
3898            );
3899            assert_eq!(
3900                withdrawn,
3901                ["{ log local0. $x }", "{ log local0. \"hi\" }", "{drop}"],
3902                "irules: the proc and `when` bodies and the `on` handler are scripts"
3903            );
3904            assert_eq!(other, 1, "irules: the quoted word stays a string");
3905        }
3906        assert!(
3907            ran > 0,
3908            "neither tcl nor irules is enabled; this test asserted nothing"
3909        );
3910    }
3911
3912    /// A command whose signature mixes the two roles keeps its *value*
3913    /// arguments string literals, one rule per row of
3914    /// `lang_helpers::tcl_family::SCRIPT_TAKING_COMMANDS` (#1381 review).
3915    ///
3916    /// `is_value_braced_word` answers by command name alone, so before
3917    /// the slot table every braced argument of a script-taking command
3918    /// was a script: `time {set x 1} {5}` lost the count, `after {100}`
3919    /// the delay, `switch {foo} {…}` the subject, and
3920    /// `namespace eval {foo bar} {…}` the namespace name.
3921    ///
3922    /// Every line carries a value *and* a script, so each rule is pinned
3923    /// from both sides: a rule that withdrew the whole construct fails on
3924    /// the value, and one that rescued it whole fails on the script.
3925    /// Flipping which index a rule calls the value moves a row from one
3926    /// list to the other, so neither list can be satisfied by a constant
3927    /// or by an inverted polarity.
3928    ///
3929    /// The two `uplevel` lines are the level gate's own pair, the last
3930    /// Tcl line is the `is_switch_arm` guard's — an arm whose *pattern*
3931    /// is spelled `after` builds an `after` command around what are
3932    /// really arm bodies, whose first would otherwise become the delay —
3933    /// and the `-matchvar` line pins the subject scan's option arity and
3934    /// its `--` terminator. iRules has no `switch` rows because its
3935    /// grammar models the construct and rejects a braced subject
3936    /// outright (the word lands under an `ERROR`, where the walk helper
3937    /// refuses to go).
3938    #[test]
3939    #[cfg(any(feature = "tcl", feature = "irules"))]
3940    fn tcl_family_mixed_signature_value_arguments_stay_strings() {
3941        let mut ran = 0;
3942        #[cfg(feature = "tcl")]
3943        {
3944            ran += 1;
3945            let (kept, withdrawn, _) = braced_word_string_verdicts::<crate::langs::TclCode>(
3946                "tcl",
3947                b"after {100} {puts a}\n\
3948                  time {puts b} {5}\n\
3949                  uplevel {1} {puts c}\n\
3950                  uplevel {puts d}\n\
3951                  switch {sub} {p {puts e}}\n\
3952                  switch -exact -- {sub2} {q {puts f}}\n\
3953                  switch -- {sub4} {t} {puts m}\n\
3954                  switch -nocase -matchvar {mv} -regexp {sub3} {r {puts g}}\n\
3955                  switch $v {^s} {puts h}\n\
3956                  namespace eval {my ns} {puts i}\n\
3957                  namespace inscope {my ns2} {puts j}\n\
3958                  namespace code {puts k}\n\
3959                  switch $w { after {puts x} time {puts y} }\n",
3960                Tcl::BracedWord as u16,
3961            );
3962            assert_eq!(
3963                kept,
3964                [
3965                    "{100}", "{5}", "{1}", "{sub}", "{sub2}", "{sub4}", "{t}", "{mv}", "{sub3}",
3966                    "{^s}", "{my ns}", "{my ns2}",
3967                ],
3968                "tcl: an `after` delay, a `time` count, an `uplevel` level, a \
3969                 `switch` subject reached past three option spellings, a \
3970                 `-matchvar` operand, two flat-form patterns and the two \
3971                 `namespace` names are literals"
3972            );
3973            assert_eq!(
3974                withdrawn,
3975                [
3976                    "{puts a}",
3977                    "{puts b}",
3978                    "{puts c}",
3979                    "{puts d}",
3980                    "{p {puts e}}",
3981                    "{puts e}",
3982                    "{q {puts f}}",
3983                    "{puts f}",
3984                    "{puts m}",
3985                    "{r {puts g}}",
3986                    "{puts g}",
3987                    "{puts h}",
3988                    "{puts i}",
3989                    "{puts j}",
3990                    "{puts k}",
3991                    "{ after {puts x} time {puts y} }",
3992                    "{puts x}",
3993                    "{puts y}",
3994                ],
3995                "tcl: every arm list, arm body and evaluated argument is a \
3996                 script — including the sole argument of the second \
3997                 `uplevel`, which does not read as a level, and the two \
3998                 bodies of an arm whose pattern is spelled `after`"
3999            );
4000        }
4001        #[cfg(feature = "irules")]
4002        {
4003            ran += 1;
4004            let (kept, withdrawn, _) = braced_word_string_verdicts::<crate::langs::IrulesCode>(
4005                "irules",
4006                b"after {100} {log a}\n\
4007                  time {log b} {5}\n\
4008                  uplevel {1} {log c}\n\
4009                  uplevel {log d}\n\
4010                  namespace eval {my ns} {log e}\n\
4011                  namespace inscope {my ns2} {log f}\n\
4012                  namespace code {log g}\n",
4013                Irules::BracedWord as u16,
4014            );
4015            assert_eq!(
4016                kept,
4017                ["{100}", "{5}", "{1}", "{my ns}", "{my ns2}"],
4018                "irules: the same delay, count, level and namespace names are \
4019                 literals — the two dialects share one predicate and must not \
4020                 drift"
4021            );
4022            assert_eq!(
4023                withdrawn,
4024                [
4025                    "{log a}", "{log b}", "{log c}", "{log d}", "{log e}", "{log f}", "{log g}",
4026                ],
4027                "irules: every evaluated argument is a script"
4028            );
4029        }
4030        assert!(
4031            ran > 0,
4032            "neither tcl nor irules is enabled; this test asserted nothing"
4033        );
4034    }
4035
4036    /// A mixed-signature command whose *layout* cannot be resolved keeps
4037    /// the construct-wide script answer, and a resolvable one beside it
4038    /// still yields its value.
4039    ///
4040    /// Three shapes reach a fallback in
4041    /// `lang_helpers::tcl_family` that no other fixture does:
4042    ///
4043    /// - `namespace $sub {…}` — the subcommand is a substitution, not a
4044    ///   plain word, so no `ScriptSlots` row can be looked up at all.
4045    /// - `switch -matchvar {m} -indexvar {i}` — both options consume the
4046    ///   word after them, so the scan runs off the end without finding a
4047    ///   subject. *Two* pairs, because one leaves the scan at a list of
4048    ///   two whose second word an invented subject 0 would call the arm
4049    ///   list — the same answer, so a single pair proves nothing.
4050    /// - `switch bar {p} {puts c} {q} {puts d}` — the subject is a bare
4051    ///   `simple_word`, the one spelling neither the braced nor the `$v`
4052    ///   fixtures above exercise. *Two* arms, for the same reason: with
4053    ///   one, the trailing argument is the braced arm list either way, so
4054    ///   the subject's index does not change any answer.
4055    ///
4056    /// Pairing each with a resolvable line is what makes the claim
4057    /// two-sided: the exact vectors below say `{my ns}`, `{p}` and `{q}`
4058    /// are values *and* that `{puts b}`, `{m}` and `{i}` are not, so a
4059    /// fallback answering "value" instead moves rows between the lists.
4060    ///
4061    /// The `switch` rows are Tcl-only by construction. The iRules grammar
4062    /// models `switch`, so a well-formed one is never the generic
4063    /// `command` this rule reads, and a malformed one lands under an
4064    /// `ERROR` that `is_braced_literal_slot` rejects before the slot
4065    /// table — the same asymmetry `SCRIPT_TAKING_COMMANDS` records for
4066    /// its `for` and `switch` rows.
4067    #[test]
4068    #[cfg(any(feature = "tcl", feature = "irules"))]
4069    fn tcl_family_unresolvable_slot_layouts_keep_the_script_answer() {
4070        let mut ran = 0;
4071        #[cfg(feature = "tcl")]
4072        {
4073            ran += 1;
4074            let (kept, withdrawn, _) = braced_word_string_verdicts::<crate::langs::TclCode>(
4075                "tcl",
4076                b"namespace eval {my ns} {puts a}\n\
4077                  namespace $sub {puts b}\n\
4078                  switch -matchvar {m} -indexvar {i}\n\
4079                  switch bar {p} {puts c} {q} {puts d}\n",
4080                Tcl::BracedWord as u16,
4081            );
4082            assert_eq!(
4083                kept,
4084                ["{my ns}", "{p}", "{q}"],
4085                "tcl: a resolvable `namespace eval` name and both flat-form \
4086                 patterns behind a bare-word subject are literals"
4087            );
4088            assert_eq!(
4089                withdrawn,
4090                ["{puts a}", "{puts b}", "{m}", "{i}", "{puts c}", "{puts d}"],
4091                "tcl: an unresolvable `namespace` subcommand and a `switch` \
4092                 with no subject keep every braced argument a script"
4093            );
4094        }
4095        #[cfg(feature = "irules")]
4096        {
4097            ran += 1;
4098            let (kept, withdrawn, _) = braced_word_string_verdicts::<crate::langs::IrulesCode>(
4099                "irules",
4100                b"namespace eval {my ns} {log a}\n\
4101                  namespace $sub {log b}\n",
4102                Irules::BracedWord as u16,
4103            );
4104            assert_eq!(
4105                kept,
4106                ["{my ns}"],
4107                "irules: the resolvable `namespace eval` name is a literal"
4108            );
4109            assert_eq!(
4110                withdrawn,
4111                ["{log a}", "{log b}"],
4112                "irules: the unresolvable subcommand keeps its argument a script"
4113            );
4114        }
4115        assert!(
4116            ran > 0,
4117            "neither tcl nor irules is enabled; this test asserted nothing"
4118        );
4119    }
4120}