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