Skip to main content

big_code_analysis_ast/
getter.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 [`Getter`] accessors — names, space kinds, Halstead classes — and
10//! their per-language impls.
11
12use crate::token_role::TokenRole;
13
14use crate::lang_helpers::tcl_family::{
15    ArgumentRoles, Dialect, SWITCH_COMMAND, argument_slots_are_readable, fills_script_slot,
16    namespace_script_slots, script_slots,
17};
18use crate::space_kind::SpaceKind;
19use crate::traits::Search;
20use generic_angles::{GenericAngleKinds, never_misparsed};
21use js_family::impl_js_family_get_op_type;
22
23use crate::*;
24
25/// Bounds- and UTF-8-checked text extraction for a node's byte span.
26///
27/// `code` is `&[u8]`, so slicing it carries no char-boundary
28/// precondition; the two guards here cover two unrelated failure modes:
29///
30/// * `std::str::from_utf8` rejects non-UTF-8 bytes. This one is
31///   reachable from ordinary use — `big_code_analysis::Ast::parse` accepts
32///   arbitrary bytes, so a node span in a partially-binary source need
33///   not be valid UTF-8.
34/// * `code.get` bounds-checks the range. This one is reachable only by
35///   violating the same-parse precondition documented on `Getter`, i.e.
36///   `big_code_analysis::Ast::from_tree_sitter` adopting a tree built from longer
37///   source than the `code` passed alongside it.
38///
39/// Both degrade to `None`. The walker stores a space's name as
40/// `Option<String>` (`spaces.rs`), so that records an unnamed space
41/// rather than crashing — note this is *not* the same path as a node
42/// with no `name` field, which `get_func_space_name` reports as
43/// `Some("<anonymous>")` without reaching here. The unguarded sibling
44/// slice sites return infallible
45/// types feeding metric arithmetic or rendered output; there the only
46/// available fallback would be a fabricated empty value that silently
47/// corrupts a count, so they rely on the precondition instead. The
48/// asymmetry is deliberate: guarding is free here because `Option` is
49/// already part of this signature's contract (#1059).
50#[inline]
51pub(crate) fn node_text<'a>(code: &'a [u8], node: &Node) -> Option<&'a str> {
52    code.get(node.start_byte()..node.end_byte())
53        .and_then(|bytes| std::str::from_utf8(bytes).ok())
54}
55
56macro_rules! get_operator {
57    ($language:ident) => {
58        #[inline]
59        fn get_operator_id_as_str(id: u16) -> &'static str {
60            let typ = id.into();
61            match typ {
62                $language::LPAREN => "()",
63                $language::LBRACK => "[]",
64                // role-bypass: allow(StringLit) — the spelling of a bracket pair in the
65                // vocabulary; PHP's `StringLit` row `wraps` the same `{` as an interpolation
66                // opener, which is a different question
67                $language::LBRACE => "{}",
68                _ => typ.into(),
69            }
70        }
71    };
72}
73
74// The byte-less `get_space_kind` of a language whose space tree is its
75// `FuncOpener` and `Container` rows (#1696), the Getter half of
76// `checker.rs`'s `impl_byte_less_func_space!`: forwards with no bytes
77// and a known-empty chain, which the build asserts neither row reads
78// (#1793). Ruby and Elixir keep hand-written spellings for the reasons
79// given there.
80macro_rules! impl_byte_less_space_kind {
81    ($roles:ident) => {
82        fn get_space_kind(node: &Node) -> SpaceKind {
83            const _: () = assert!(
84                !$crate::roles::$roles::func_opener::TEXT_GATED
85                    && !$crate::roles::$roles::func_opener::CHAIN_GATED
86                    && !$crate::roles::$roles::container::TEXT_GATED
87                    && !$crate::roles::$roles::container::CHAIN_GATED,
88                "a space-opening row reads bytes or the chain; the byte-less spelling cannot forward with none"
89            );
90            Self::get_space_kind_with_code(node, &[], Ancestors::known(&[]))
91        }
92    };
93}
94
95/// Emits a [`Getter::get_keyword_role`] from the language's `Modifier`,
96/// `DeclKeyword` and `Primitive` rows. A modifier or declaration
97/// keyword is an operator everywhere; a primitive is the operator the
98/// C family, Java and TypeScript make it unless the invocation says
99/// `primitive: Operand`, the PHP reading. Takes the language's module
100/// under `crate::roles`.
101macro_rules! keyword_roles {
102    ($roles:ident) => {
103        keyword_roles!($roles, primitive: Operator);
104    };
105    ($roles:ident, primitive: $primitive_role:ident) => {
106        #[inline]
107        fn get_keyword_role<'a>(
108            node: &Node<'a>,
109            code: &[u8],
110            ancestors: Ancestors<'a, '_>,
111        ) -> TokenRole {
112            use $crate::roles::$roles::{decl_keyword, modifier, primitive};
113            let kind = node.kind_id();
114            if modifier::pays_at_leaf_kind(kind, node, code, ancestors)
115                || decl_keyword::pays_at_leaf_kind(kind, node, code, ancestors)
116            {
117                TokenRole::Operator
118            } else if primitive::pays_at_leaf_kind(kind, node, code, ancestors) {
119                TokenRole::$primitive_role
120            } else {
121                TokenRole::Unknown
122            }
123        }
124    };
125}
126
127/// Emits a [`Getter::get_paying_role`] that bills the paying token of
128/// each listed row as an operator: the `Comparison`, `ShortCircuit`,
129/// `EagerLogical`, `Ternary`, `CaseArm`, `Guard` and `NullSafe` rows
130/// of the language's module under `crate::roles` (#1694, #1695), and —
131/// in the `control_flow` form — the `Branch`, `Switch`, `Loop`, `Catch`
132/// and `ElseIf` rows too (#1697). That form is for the keyword-paying
133/// languages (the C and JS families, Java, Groovy, Python): a
134/// statement-paying language's control-flow rows list no token payer,
135/// so the form would bill nothing there and the plain form is kept.
136/// `ElseIf` pays only where the grammar gives the clause a keyword of its
137/// own, Python's `elif`; the C-family and JVM rows list no payer and bill
138/// nothing. Each row is read at its token projection
139/// (`pays_at_token_kind`) — the operator token, which is what Halstead
140/// counts — so an owning `binary_expression` bills nothing here and its
141/// `<` bills once, and a `pays_itself` owner, which pays the counting
142/// consumers at the leaf but is a node with no token to bill (Groovy's `a
143/// !in b`), bills nothing; an owner-only row (Kotlin's infix `and`, whose
144/// name is an `identifier`; every statement-paying language's `Branch`)
145/// lists no payer and bills nothing. The control-flow rows' keyword
146/// payers (`if`, `for`, …) are ungated on every row but two, so a token
147/// stranded under `ERROR` bills here exactly as the `get_op_type` arm it
148/// left billed it. The two are Python's `If gated_by not_under_ternary`,
149/// which declines the ternary's `if` for the counting consumers, and
150/// Rust's `For gated_by not_in_type_syntax`, which declines `impl T for
151/// S` and `for<'a>` (#1720); Halstead still bills those spellings,
152/// through the byte-less `get_op_type` arm each language keeps the
153/// keyword in, so a change to either side must keep the two in step.
154macro_rules! paying_roles {
155    ($roles:ident) => {
156        paying_roles!(@emit $roles []);
157    };
158    ($roles:ident, control_flow) => {
159        paying_roles!(@emit $roles [branch, switch, r#loop, catch, else_if]);
160    };
161    (@emit $roles:ident [$($more:ident),*]) => {
162        #[inline]
163        fn get_paying_role<'a>(
164            node: &Node<'a>,
165            code: &[u8],
166            ancestors: Ancestors<'a, '_>,
167        ) -> TokenRole {
168            use $crate::roles::$roles::{
169                case_arm, comparison, eager_logical, guard, null_safe, short_circuit, ternary,
170                $($more,)*
171            };
172            let kind = node.kind_id();
173            if comparison::pays_at_token_kind(kind, node, code, ancestors)
174                || short_circuit::pays_at_token_kind(kind, node, code, ancestors)
175                || eager_logical::pays_at_token_kind(kind, node, code, ancestors)
176                || ternary::pays_at_token_kind(kind, node, code, ancestors)
177                || case_arm::pays_at_token_kind(kind, node, code, ancestors)
178                || guard::pays_at_token_kind(kind, node, code, ancestors)
179                || null_safe::pays_at_token_kind(kind, node, code, ancestors)
180                $(|| $more::pays_at_token_kind(kind, node, code, ancestors))*
181            {
182                TokenRole::Operator
183            } else {
184                TokenRole::Unknown
185            }
186        }
187    };
188}
189
190/// The row classifications where they answer — the keyword rows first,
191/// then the paying-construct rows — otherwise the byte-less
192/// [`Getter::get_op_type`]: the one fallback every spelling of
193/// [`Getter::get_op_type_with_code`] ends in. An override of that
194/// method calls this, never `get_op_type` directly, so a row is read on
195/// every path the walk takes. A free function rather than a provided
196/// method so no language can override the fallback and skip its rows.
197#[inline]
198#[must_use]
199pub(crate) fn keyword_or_op_type<'a, G: Getter + ?Sized>(
200    node: &Node<'a>,
201    code: &[u8],
202    ancestors: Ancestors<'a, '_>,
203) -> TokenRole {
204    match G::get_keyword_role(node, code, ancestors) {
205        TokenRole::Unknown => match G::get_paying_role(node, code, ancestors) {
206            TokenRole::Unknown => G::get_op_type(node, ancestors),
207            role => role,
208        },
209        role => role,
210    }
211}
212
213/// The default space name: the node's `name` field, else `<anonymous>`.
214///
215/// A free function as well as the trait default so a language that needs
216/// to name a *few* kinds specially can delegate the rest rather than
217/// restate the rule — `<get>` / `<set>` / `<init>` / `<static-init>` in
218/// Kotlin, Java and Groovy all do (#1184). Calling `Self::…` there would
219/// recurse.
220#[must_use]
221pub fn default_func_space_name<'a, 'tree>(
222    node: &Node<'tree>,
223    code: &'a [u8],
224    _ancestors: Ancestors<'tree, '_>,
225) -> Option<&'a str> {
226    // we're in a function or in a class
227    if let Some(name) = node.child_by_field_name("name") {
228        node_text(code, &name)
229    } else {
230        Some("<anonymous>")
231    }
232}
233
234/// Per-language accessors the space walker and the Halstead
235/// operator/operand classification dispatch through.
236///
237/// # Precondition
238///
239/// Every method taking a `code: &[u8]` next to a `&Node` slices `code`
240/// by that node's byte range. `code` must be the exact buffer `node` was
241/// parsed from — `big_code_analysis::Ast::source` for a node obtained from the
242/// same `big_code_analysis::Ast`. Pairing a node with any other buffer reads the
243/// wrong bytes at best and panics on an out-of-bounds index at worst;
244/// the same precondition is documented on [`crate::dump_node`] (#795).
245/// `node_text` — reached from the default `get_func_space_name` and
246/// from the per-language `get_func_name` overrides — is the sole
247/// bounds-checked slice; see its docs for why the rest deliberately
248/// are not.
249#[doc(hidden)]
250/// The kinds one Tcl-family dialect spells the braced-word construct
251/// with, for [`Getter::is_subsumed_braced_word`] and
252/// [`Getter::braced_word_op_type`]. A struct rather than a row of `u16`
253/// parameters because the ids are same-typed and positional: a
254/// transposed pair compiles and silently inverts the rule for that
255/// dialect.
256pub struct BracedWordKinds {
257    /// `braced_word_simple`, the literal *value* form.
258    pub value: u16,
259    /// `braced_word`, the *script* form.
260    pub script: u16,
261    /// `comment`, the one named child of a script that is not a
262    /// command.
263    pub comment: u16,
264    /// `command`, the generic command node. Its `name` field carries
265    /// the leading word [`Getter::is_value_braced_word`] recognises the
266    /// construct by, and it is the only parent a *generic* argument
267    /// list hangs from. The hidden `_command` supertype (`Command2` in
268    /// both enums) is deliberately absent: the parser never emits it
269    /// (grammar-dispatch §2).
270    pub command: u16,
271    /// `word_list`, a command's `arguments` field — and, in both
272    /// grammars, also the argument list of the modelled `namespace`
273    /// construct, which is why the rule reads the grandparent rather
274    /// than stopping here.
275    pub word_list: u16,
276    /// `simple_word`, the only spelling of a command name this rule
277    /// resolves. A computed name (`$cmd {…}`, `[pick] {…}`) parses as
278    /// `variable_substitution` / `command_substitution` and is not
279    /// statically resolvable at all.
280    pub simple_word: u16,
281    /// `argument`, one entry of a `proc` parameter list. A modelled
282    /// slot that holds a *value* rather than a script: a defaulted
283    /// parameter (`proc p {a {b {x y}}}`) spells its default as a
284    /// `braced_word`, and a default is never evaluated as code.
285    pub argument: u16,
286    /// `procedure`, the modelled `proc` construct. Its `name` field is a
287    /// `braced_word` when the name holds a space (`proc {my proc} …`),
288    /// and a name is a literal although the construct's other braced
289    /// slot, the body, is a script
290    /// ([`Getter::is_braced_literal_slot`]).
291    pub procedure: u16,
292    /// `namespace`, the modelled construct — not the keyword token that
293    /// shares its name. Its `word_list` holds a subcommand followed by
294    /// that subcommand's arguments, and only three subcommands take a
295    /// script ([`Getter::is_braced_literal_slot`]).
296    pub namespace: u16,
297    /// `{`, the brace opener — the *only* node
298    /// [`Getter::braced_word_op_type`] may revise. A braced word's
299    /// operator children are not the opener alone: `_terminator` is a
300    /// hidden rule, so a `;` separating two commands is inlined as a
301    /// direct child of the `braced_word` and both dialects classify it
302    /// as an operator. Keying the revision on the parent kind alone
303    /// therefore swallowed those separators too, taking
304    /// `lappend x {puts a ; puts b}` to `n1` 0 / `N1` 0 and
305    /// `halstead.effort` — a gated threshold metric — to `0.0`.
306    pub open_brace: u16,
307}
308
309/// Per-language accessors that *name* and *classify* what a node is:
310/// the function or space name, the [`SpaceKind`] a node opens, and the
311/// [`TokenRole`] of a leaf.
312///
313/// Every method but [`get_keyword_role`](Self::get_keyword_role) has a
314/// default that answers "nothing" (`None`, [`SpaceKind::Unknown`],
315/// [`TokenRole::Unknown`]); a language overrides only the ones its
316/// grammar expresses. The keyword classifier is required, so a language
317/// says through its rows — declared or `absent` — which keywords it has.
318pub trait Getter {
319    /// Names the function `node` declares. Defaults to
320    /// [`get_func_space_name`](Self::get_func_space_name).
321    #[must_use]
322    fn get_func_name<'a, 'tree>(
323        node: &Node<'tree>,
324        code: &'a [u8],
325        ancestors: Ancestors<'tree, '_>,
326    ) -> Option<&'a str> {
327        Self::get_func_space_name(node, code, ancestors)
328    }
329
330    /// Names the space `node` opens.
331    ///
332    /// `ancestors` is the chain the caller descended through. Elixir
333    /// needs it: its `def` / `defmodule` heads are ordinary `Call`
334    /// nodes, and one inside a `quote` template names no space at all,
335    /// which is a question about what encloses the call (#1088).
336    #[must_use]
337    fn get_func_space_name<'a, 'tree>(
338        node: &Node<'tree>,
339        code: &'a [u8],
340        ancestors: Ancestors<'tree, '_>,
341    ) -> Option<&'a str> {
342        default_func_space_name(node, code, ancestors)
343    }
344
345    /// The kind of space `node` opens, or [`SpaceKind::Unknown`] when it
346    /// opens none.
347    #[must_use]
348    fn get_space_kind(_node: &Node) -> SpaceKind {
349        SpaceKind::Unknown
350    }
351
352    /// Source-aware variant of [`get_space_kind`](Self::get_space_kind). The default
353    /// forwards to the byte-less classifier; languages whose space
354    /// kinds are encoded in macro identifier text (Elixir's
355    /// `defmodule` / `def` / `defp` / `defmacro` / `defmacrop` Calls)
356    /// override this so the walker can attribute the correct
357    /// `SpaceKind` to each promoted func space (#275).
358    ///
359    /// `ancestors` is the chain the caller descended through; Elixir
360    /// needs it to see whether the `Call` sits inside a `quote`
361    /// template without paying `Node::parent`'s `O(depth)` (#1084).
362    #[inline]
363    #[must_use]
364    fn get_space_kind_with_code<'a>(
365        node: &Node<'a>,
366        _code: &[u8],
367        _ancestors: Ancestors<'a, '_>,
368    ) -> SpaceKind {
369        Self::get_space_kind(node)
370    }
371
372    /// Classifies `node` as a Halstead operator, operand, or neither.
373    ///
374    /// **Punctuation and delimiters are vocabulary, so they classify as
375    /// operators whatever grammatical role they serve.** Halstead
376    /// counts the alphabet a program is written in and has no notion of
377    /// a decision, so a `<` is the same vocabulary entry whether it
378    /// opens a JSX tag, brackets a Lua `<const>` attribute, names a C#
379    /// `operator <` overload, or delimits a Perl `<FH>` readline. Every
380    /// impl that classifies punctuation at all bills `(`, `{`, `[`, `,`,
381    /// `;`, `.` and `:` on exactly that reading, for each glyph its
382    /// language spells. Python and Rust were the last two exceptions,
383    /// closed by #1486.
384    ///
385    /// A *decision* metric gates the same token by role, and is
386    /// supposed to disagree: ABC's `conditions` counts a `<` only under
387    /// a `binary_expression` (#1274, #1275, #1280, #1297), so each of
388    /// the four constructs above scores zero there while `bca ops`
389    /// still reports the bracket. #1395 settled that the two answers
390    /// are both correct rather than a drift to be reconciled;
391    /// `tests/parity/abc_halstead_bracket_parity.rs` fails if a later
392    /// consistency pass flips either side.
393    ///
394    /// The one suppression that reading admits is **a literal's own
395    /// delimiter**. There the punctuation is not vocabulary in its own
396    /// right — the literal it wraps is already counted, so billing its
397    /// quotes fabricates an arithmetic or comparison operator the
398    /// source never spelled, and the score moves with the author's
399    /// choice of delimiter. It takes two shapes, and only the first is
400    /// an arm of this method.
401    ///
402    /// Nine arms suppress a delimiter whose enclosing literal node is
403    /// itself the operand, each guarded on the delimiter's *parent*
404    /// being that literal: Elixir's sigil (#1256), the regex `/` of the
405    /// JS family (#1314), of Perl and of Ruby (#1312), Ruby's subshell
406    /// backtick (#1360), Groovy's slashy string and the raw-string `(`
407    /// of both C++ grammars (#1314), and Objective-C's `@` before an
408    /// `NSString` literal.
409    ///
410    /// The tenth is [`braced_word_op_type`], which Tcl and iRules route
411    /// their `{` through. A braced *value* is a literal to
412    /// [`Checker::is_string_with_code`] and to the dump, so its opener
413    /// is withdrawn for the same reason — `puts {c d}` and
414    /// `puts "c d"` have to agree on the operator column — but the
415    /// operands are the words *inside* it rather than the braced word
416    /// itself, so the parent test above does not describe it. #1318
417    /// established that arm and #1382 widened it to the value slots of
418    /// a script-taking command.
419    ///
420    /// A bracket delimiting *syntax* fits neither shape: no literal
421    /// would absorb its contribution, so it stays an operator. A
422    /// generic list's `<` / `>` is billed like the other bracket pairs,
423    /// once as `<>` on the opener ([`Self::get_operator_spelling`], #1559),
424    /// which leaves the comparison `<` and `>` their own entries.
425    ///
426    /// `ancestors` is the chain the walker descended through. Most
427    /// impls read a parent from it to disambiguate a token whose role
428    /// depends on what encloses it — the nine literal-delimiter arms
429    /// above, plus, among others, Python's `not` / `in` / `is` inside
430    /// the compound `not in` / `is not`, Rust's `||` and `!` inside a
431    /// binary expression rather than a doc-comment marker, the
432    /// namespace identifier in both C++ grammars, Bash's `$name`, the
433    /// name inside a Tcl or iRules variable substitution, and Groovy's
434    /// `super` in a wildcard bound. Reaching those parents with
435    /// [`Node::parent`] instead costs `O(depth)` per node (#1096).
436    ///
437    /// [`braced_word_op_type`]: Self::braced_word_op_type
438    /// [`Checker::is_string_with_code`]: crate::Checker::is_string_with_code
439    #[must_use]
440    fn get_op_type<'a>(_node: &Node<'a>, _ancestors: Ancestors<'a, '_>) -> TokenRole {
441        TokenRole::Unknown
442    }
443
444    /// Classifies `node` when it is a keyword the language's role rows
445    /// declare — a `Modifier`, `DeclKeyword` or `Primitive` — and
446    /// answers [`TokenRole::Unknown`] for every other node (#1693).
447    ///
448    /// The rows in `crate::roles` say *which* kinds are those keywords;
449    /// this method says what Halstead makes of one, which is the
450    /// language's choice: the C family, Java and TypeScript bill a
451    /// primitive as an operator, PHP as an operand. Every language's
452    /// three rows are declared or `absent`, and
453    /// [`get_op_type`](Self::get_op_type) lists no keyword a row owns.
454    /// Required rather than defaulted: a language that inherited
455    /// `Unknown` here would bill no keyword and nothing would say so,
456    /// where `keyword_roles!` over three `absent` rows says the same
457    /// thing on purpose.
458    #[must_use]
459    fn get_keyword_role<'a>(
460        node: &Node<'a>,
461        code: &[u8],
462        ancestors: Ancestors<'a, '_>,
463    ) -> TokenRole;
464
465    /// The Halstead role of a node some *paying-construct* row of
466    /// `crate::roles` declares — the paying token of a `Comparison`,
467    /// `ShortCircuit`, `EagerLogical`, `Ternary`, `CaseArm`, `Guard` or
468    /// `NullSafe` row — and [`TokenRole::Unknown`] for every other node
469    /// (#1694, #1695). Read after [`get_keyword_role`](Self::get_keyword_role)
470    /// and before the byte-less [`get_op_type`](Self::get_op_type) on
471    /// every path the walk takes.
472    ///
473    /// Every language with a grammar of its own overrides it, through
474    /// `paying_roles!` or by hand; the `Unknown` default serves the two
475    /// whose rows are all `absent` — `ccomment` and `preproc`, which
476    /// have no operators to bill.
477    ///
478    /// A row gates its payers on *application* — Java's `<` under a
479    /// `binary_expression`, C++'s `&&` not in a reference declarator —
480    /// because the counting consumers need that gate. Halstead bills
481    /// the other spellings too (`List<T>`, `int&& x`, `operator<`), so
482    /// each language's `get_op_type` keeps those as the gated-out
483    /// complement, under a `role-bypass: allow` naming the row.
484    #[inline]
485    #[must_use]
486    fn get_paying_role<'a>(
487        _node: &Node<'a>,
488        _code: &[u8],
489        _ancestors: Ancestors<'a, '_>,
490    ) -> TokenRole {
491        TokenRole::Unknown
492    }
493
494    /// Source-aware variant of [`get_op_type`], and the spelling the
495    /// walk calls. The default forwards to the crate-private
496    /// `keyword_or_op_type`, which reads [`get_keyword_role`], then
497    /// [`get_paying_role`](Self::get_paying_role), and falls
498    /// back to [`get_op_type`]; languages whose Halstead operand
499    /// classification depends on token text override this and end in
500    /// the same call. Kotlin uses
501    /// it to recover the variable in a short-form string template
502    /// (`"Hi $name"`), which the grammar emits as bare `string_content`
503    /// tokens with no structured interpolation node — the distinction
504    /// between an interpolated `$name` and a literal `$5` is only
505    /// visible in the source bytes (#454).
506    ///
507    /// [`get_op_type`]: Self::get_op_type
508    /// [`get_keyword_role`]: Self::get_keyword_role
509    #[inline]
510    #[must_use]
511    fn get_op_type_with_code<'a>(
512        node: &Node<'a>,
513        code: &[u8],
514        ancestors: Ancestors<'a, '_>,
515    ) -> TokenRole {
516        keyword_or_op_type::<Self>(node, code, ancestors)
517    }
518
519    /// The fixed spelling an operator `node` is keyed under in place of
520    /// its kind id, for a token whose kind the grammar shares with a
521    /// different operator; `None` keys it by kind. A generic list's `<`
522    /// is the case (#1559): it has the comparison's kind but is keyed as
523    /// the `"<>"` pair, as `()`, `[]` and `{}` are. Consulted only for a
524    /// node [`get_op_type_with_code`](Self::get_op_type_with_code) calls
525    /// an operator.
526    #[inline]
527    #[must_use]
528    fn get_operator_spelling<'a>(
529        _node: &Node<'a>,
530        _ancestors: Ancestors<'a, '_>,
531    ) -> Option<&'static str> {
532        None
533    }
534
535    /// Returns the source-byte slice used to key a Halstead *operand*.
536    /// The default keys on the operand node's full byte range. Kotlin
537    /// overrides this to narrow a short-interpolation name token
538    /// (`$name`) to its leading identifier prefix, because the grammar
539    /// glues trailing inter-segment text onto the name token
540    /// (`"$a $b"` → `"a "`); keying the raw bytes would record a
541    /// distinct `"a "` operand and break parity with the long `${a}`
542    /// form (#454).
543    #[inline]
544    #[must_use]
545    fn get_operand_id<'a>(
546        node: &Node<'a>,
547        code: &'a [u8],
548        _ancestors: Ancestors<'a, '_>,
549    ) -> &'a [u8] {
550        &code[node.start_byte()..node.end_byte()]
551    }
552
553    /// Classifies a string-literal `node` as a single Halstead
554    /// operand, *unless* it wraps an interpolation child drawn from
555    /// `interp_kinds` — in which case the wrapper yields
556    /// [`TokenRole::Unknown`] because the inner expressions are
557    /// walked and counted separately. Counting the wrapper too would
558    /// double-count their contribution to `N2`.
559    ///
560    /// This declares the per-language interpolation skip once (issue
561    /// #420), replacing nine independently-added regression fixes
562    /// (#183 / #184 / #191 / #192 / #199 / #277, …). Each language
563    /// supplies only its own grammar's interpolation child-kind ids;
564    /// the per-call rationale lives at each call site.
565    #[must_use]
566    fn string_operand_type(node: &Node, interp_kinds: &[u16]) -> TokenRole {
567        if node.wraps_any(interp_kinds) {
568            TokenRole::Unknown
569        } else {
570            TokenRole::Operand
571        }
572    }
573
574    /// Whether `node` is a fragment of a Tcl-family braced word rather
575    /// than a token of its own, and so contributes no operand (#1354).
576    ///
577    /// The two dialects are deliberate clones, so the rule is declared
578    /// once and instantiated with each grammar's [`BracedWordKinds`];
579    /// the per-call rationale lives at each call site. It answers yes
580    /// in two cases:
581    ///
582    /// - `node` sits directly inside a braced *value*
583    ///   (`braced_word_simple`). Tcl evaluates nothing between braces,
584    ///   so the value is its whole span and the parts inside it are
585    ///   letters — the wrapper carries the one operand. This subsumes
586    ///   #1314's narrower guard on the opening `{`, which is one more
587    ///   such child.
588    /// - `node` is a braced *script* (`braced_word`) holding at least
589    ///   one command — a named child other than a comment. Commands are
590    ///   what the walk descends into and counts in their own right, so
591    ///   billing the block as well would count its whole text a second
592    ///   time. A comment is named too, but no arm classifies it, so a
593    ///   body holding only comments is billed like an empty one rather
594    ///   than like nothing at all.
595    ///
596    /// A `script` with no command is deliberately not subsumed: the
597    /// same kind serves as the value slot of every command the grammar
598    /// does not special-case, where `lappend l {}` is an empty list and
599    /// the brace pair is its only carrier (grammar-dispatch §6). An
600    /// empty or comment-only `proc` body is spelled identically and so
601    /// also scores one operand, its whole text. #1318 can now tell the
602    /// two apart by the enclosing command, but it bills them alike, so
603    /// this arm needs no help from it.
604    ///
605    /// This is the *byte-less* half of the braced-word rule and it is
606    /// not the whole of it. [`braced_word_op_type`] suppresses the `{`
607    /// of a script-kind word the enclosing command shows to be a plain
608    /// value, and both Tcl-family getters reach it through
609    /// [`get_op_type_with_code`], which is what the walk calls
610    /// (grammar-dispatch §7). It revises no operand, so this arm's
611    /// answers stand unchanged.
612    ///
613    /// [`braced_word_op_type`]: Self::braced_word_op_type
614    /// [`get_op_type_with_code`]: Self::get_op_type_with_code
615    #[must_use]
616    fn is_subsumed_braced_word<'a>(
617        node: &Node<'a>,
618        ancestors: Ancestors<'a, '_>,
619        kinds: &BracedWordKinds,
620    ) -> bool {
621        ancestors.parent_has_kind(node, kinds.value)
622            || (node.kind_id() == kinds.script
623                && node
624                    .children()
625                    .any(|child| child.is_named() && child.kind_id() != kinds.comment))
626    }
627
628    /// The generic `command` node `word` is an argument of, paired with
629    /// that command's own ancestry — or `None` when `word` instead
630    /// fills a slot of a construct the grammar models, and so is a
631    /// script by construction.
632    ///
633    /// Both dialects hang a *generic* command's arguments off a
634    /// `word_list` and a *modelled* construct's slots off that
635    /// construct's own node (`procedure`, `if`, `else`, `elseif`,
636    /// `while`, `foreach`, `catch`, `try`, `finally`, `argument`, plus
637    /// iRules' `when_event`, `for`, `switch_arm`, `on_handler`,
638    /// `trap_handler` and the three `dict` loops). Asking the parent
639    /// kind therefore answers "is this a generic argument" without
640    /// enumerating the modelled parents — a list that would be a
641    /// coverage claim to re-derive on every grammar bump
642    /// (grammar-dispatch §1), and that a grammar gaining one more
643    /// modelled construct would silently invalidate.
644    ///
645    /// A `word_list` whose own parent is *not* a `command` is
646    /// `namespace`'s argument list — the one modelled construct in
647    /// either grammar that reaches its body through a `word_list`. The
648    /// grandparent test answers `None` there, so `namespace eval ns
649    /// {…}` keeps its body a script.
650    ///
651    /// A braced word directly under a `command` is the command *name*
652    /// (`{puts} hi`), not an argument, and also answers `None`: its
653    /// caller decides that case before asking, because a name is
654    /// always a literal and must not pick up the `switch`-arm rescue
655    /// below.
656    #[must_use]
657    fn generic_argument_command<'tree, 'chain>(
658        word: &Node<'tree>,
659        ancestors: Ancestors<'tree, 'chain>,
660        kinds: &BracedWordKinds,
661    ) -> Option<(Node<'tree>, Ancestors<'tree, 'chain>)> {
662        let mut chain = ancestors.iter(word);
663        let (parent, _) = chain.next()?;
664        if parent.kind_id() != kinds.word_list {
665            return None;
666        }
667        let (grandparent, grandparent_ancestors) = chain.next()?;
668        (grandparent.kind_id() == kinds.command).then_some((grandparent, grandparent_ancestors))
669    }
670
671    /// Whether a braced *script*-kind word is really a plain value —
672    /// the literal `{a b}` of `lappend x {a b}` rather than the block
673    /// of `eval {…}` (#1318).
674    ///
675    /// The two roles share one kind, so no kind-scoped arm can separate
676    /// them; recognition is out-of-band, by the enclosing command's
677    /// leading word (grammar-dispatch §9). A word that fills a modelled
678    /// construct's slot is a script; a word passed to a command in
679    /// `SCRIPT_TAKING_COMMANDS` is a script; **everything else is a
680    /// value**.
681    ///
682    /// That default is the load-bearing choice, and it is deliberately
683    /// the opposite of "keep today's answer for anything unrecognised":
684    ///
685    /// - The script-taking set is *closed* and small — Tcl defines no
686    ///   user-extensible control structures, so a command that
687    ///   evaluates a braced argument is either a core command listed
688    ///   above or a proc that forwards to `eval` / `uplevel`. The
689    ///   value-taking set is *open*: every user proc and every package
690    ///   command that takes a list or a pattern is in it. An
691    ///   unrecognised name is therefore far likelier to be value-taking.
692    /// - Defaulting to script *fabricates* — it reports a `{}` operator
693    ///   for a block the source does not contain. Defaulting to value
694    ///   can only *omit*: one `N1` occurrence per script handed to an
695    ///   unlisted command, and — when no modelled construct in the same
696    ///   space opens a block — the `{}` vocabulary entry with them.
697    ///   That last case is where the cost shows: a top-level
698    ///   `dict for {k v} $d { puts $k }` with nothing around it has no
699    ///   operator left, and Halstead's difficulty is a product with
700    ///   `n1` in it, so `effort` reads `0.0` rather than a little low.
701    ///   Inside a `proc` the `proc` keyword and body brace keep the
702    ///   space non-zero, which is the scope `halstead.effort` is gated
703    ///   at; and the same `0.0` was already the answer for a file of
704    ///   `set x {a b}` lines, so it is Halstead's shape on an
705    ///   operator-free space, not a new failure mode. The omission
706    ///   stays bounded only because the answer is scoped to the brace:
707    ///   see [`braced_word_op_type`] for the measurement that decided
708    ///   it, and for why suppressing the *contents* of a value would
709    ///   have made it unbounded instead.
710    /// - It stops the score moving with the author's choice of
711    ///   delimiter, which is what #695, #1312 and #1314 each restored
712    ///   elsewhere: `puts {c d}` and `puts "c d"` now agree on the
713    ///   operator column.
714    ///
715    /// The cost is a script passed to an unlisted command — a Tk
716    /// `-command {…}` callback, `trace add variable v w {…}`, a
717    /// subcommand dispatch (`dict for`, `interp eval`), a user-defined
718    /// `with_lock {…}` — losing the `{}` its block deserves. No
719    /// structural signal distinguishes those cases: the grammar parses
720    /// `{a b}` and `{puts hi}` into the same shape. The code inside
721    /// them is still counted, so the loss is one operator occurrence
722    /// per such block, plus the vocabulary entry in the case above.
723    ///
724    /// [`braced_word_op_type`]: Self::braced_word_op_type
725    #[must_use]
726    fn is_value_braced_word<'a>(
727        word: &Node<'a>,
728        code: &[u8],
729        ancestors: Ancestors<'a, '_>,
730        kinds: &BracedWordKinds,
731    ) -> bool {
732        // Two positions answer "value" without consulting any command
733        // name, and both must be asked before the lookup below,
734        // because neither hangs off a `command` the way an argument
735        // does — and the second must not reach the `switch`-arm
736        // rescue.
737        //
738        // A defaulted `proc` parameter (`proc p {a {b {x y}}}`) is the
739        // one modelled slot holding a value: a default is data the
740        // interpreter assigns, never a script it evaluates.
741        //
742        // A braced word directly under a `command` is that command's
743        // *name* (`{puts} hi` invokes `puts`), so it is a literal word.
744        // Inside a `switch` arm list the name is the arm's *pattern*,
745        // and a braced pattern (`switch -regexp $v { {^a.*b$} {…} }`)
746        // is idiomatic — rescuing it as an arm body would fabricate a
747        // block around a regex.
748        if ancestors
749            .parent(word)
750            .is_some_and(|parent| [kinds.argument, kinds.command].contains(&parent.kind_id()))
751        {
752            return true;
753        }
754        let Some((command, command_ancestors)) =
755            Self::generic_argument_command(word, ancestors, kinds)
756        else {
757            return false;
758        };
759        if Self::command_leading_word(&command, code, kinds)
760            .and_then(script_slots)
761            .is_some()
762        {
763            return false;
764        }
765        !(Self::is_switch_arm(&command, code, command_ancestors, kinds)
766            && Self::is_switch_arm_body(word, &command))
767    }
768
769    /// Whether `node` is a Tcl-family braced *script* — a `proc` or `if`
770    /// body, an iRules `when` handler — rather than a braced literal
771    /// (#1381).
772    ///
773    /// The positive form of [`is_value_braced_word`], narrowed to the
774    /// script kind so it answers `false` for every node of every other
775    /// kind and for the two literal spellings, and narrowed again by the
776    /// value slots [`is_braced_literal_slot`] recognises. That makes it
777    /// the question the *non-Halstead* classifiers ask:
778    /// `Checker::is_string_with_code` must not call a `proc` body a
779    /// string literal, and `Alterator::keeps_children` must stop the dump
780    /// flattening one into a leaf, which dropped the body from it. Both
781    /// once listed `braced_word` beside `quoted_word` and
782    /// `braced_word_simple`, which is right for the literal role and
783    /// wrong for the script role the same kind also serves.
784    ///
785    /// Stated here rather than in each of the five call sites so the
786    /// string, dump and Halstead classifiers cannot drift apart on the
787    /// same bytes (grammar-dispatch §7). Halstead was the deliberate
788    /// exception between #1318 and #1382: `braced_word_op_type` asked
789    /// [`is_value_braced_word`] alone, so the braces of the value slots
790    /// [`is_braced_literal_slot`] adds still billed a `{}` operator
791    /// while the other two called the same bytes a literal. #1382
792    /// closed it — that call site now asks this predicate — so a braced
793    /// value is a value to all three, and `after {100} {puts hi}` bills
794    /// the one `{}` its `{puts hi}` block earns rather than two.
795    ///
796    /// The remaining §7 note is one of scope, not of disagreement: the
797    /// three differ only where Halstead's *operand* half keys on
798    /// whether a body holds a command, which makes an empty or
799    /// comment-only `proc` body an operand there and not a string here.
800    ///
801    /// [`is_value_braced_word`]: Self::is_value_braced_word
802    /// [`is_braced_literal_slot`]: Self::is_braced_literal_slot
803    #[must_use]
804    fn is_braced_script_word<'a>(
805        node: &Node<'a>,
806        code: &[u8],
807        ancestors: Ancestors<'a, '_>,
808        kinds: &BracedWordKinds,
809    ) -> bool {
810        node.kind_id() == kinds.script
811            && !Self::is_value_braced_word(node, code, ancestors, kinds)
812            && !Self::is_braced_literal_slot(node, code, ancestors, kinds)
813    }
814
815    /// Whether `word`, a braced word [`is_value_braced_word`] calls a
816    /// script, fills a slot whose documented syntax takes a *value*.
817    ///
818    /// [`is_value_braced_word`] answers by command name alone. Most of the
819    /// names it recognises have a mixed signature, though, so that answer
820    /// made a *value* — a millisecond count, a namespace name, a `switch`
821    /// subject — a script (#1381 review). This
822    /// is the per-argument half: `proc` has one value slot the grammar
823    /// names as a field, and every other construct declares its layout in
824    /// one of the two tables in `lang_helpers::tcl_family`, which
825    /// `fills_script_slot` applies.
826    ///
827    /// Each value here was a string and a flat dump leaf before #1381, and
828    /// would otherwise have become a script under it: the dump rendered
829    /// `{my proc}` as a command named `my` and `{100}` as one named `100`,
830    /// and `namespace export {…}` and `namespace ensemble create -map {…}`
831    /// both occur in the Tcl 8.6 standard library. Since #1382 Halstead
832    /// reads the same answer through [`is_braced_script_word`], so the
833    /// braces of these values quote rather than open (`after {100} {…}`
834    /// scores the `{}` of its script and no other).
835    ///
836    /// Two guards keep the construct-wide answer. A switch arm list parses
837    /// as commands, so an arm whose *pattern* is spelled `proc`,
838    /// `namespace`, `after` or `switch` builds one of these shapes around
839    /// what are really arm bodies — [`is_switch_arm`] recognises it first.
840    /// And an argument list whose own slot sequence is unreadable has no
841    /// positions worth trusting.
842    ///
843    /// That second guard is `tcl_family::argument_slots_are_readable`,
844    /// which asks the *slots* rather than the owner — asking
845    /// [`Node::has_error`] of the command withdrew every value slot of a
846    /// command whose only error sat inside one of its script arguments.
847    /// Its doc carries the measurement. A list *longer* than the
848    /// signature admits is the second way to be unreadable, and
849    /// `tcl_family::ScriptSlots::LastOf` is where that one lives.
850    ///
851    /// A `try … trap` clause is out of reach only where the grammar
852    /// wraps it: inside a `proc` or a `namespace eval` body the Tcl
853    /// grammar recovers into an `ERROR` node and no role signal
854    /// survives, but at the top level the same clause parses as a plain
855    /// `trap` command whose slots this does read. An earlier revision
856    /// of this paragraph said "the multi-line `try … trap` clause" was
857    /// out of reach outright, which is where the `finally` defect
858    /// `LastOf` now guards hid (#1382 review).
859    ///
860    /// [`Node::has_error`]: crate::Node::has_error
861    /// [`is_braced_script_word`]: Self::is_braced_script_word
862    /// [`is_value_braced_word`]: Self::is_value_braced_word
863    /// [`is_switch_arm`]: Self::is_switch_arm
864    #[must_use]
865    fn is_braced_literal_slot<'a>(
866        word: &Node<'a>,
867        code: &[u8],
868        ancestors: Ancestors<'a, '_>,
869        kinds: &BracedWordKinds,
870    ) -> bool {
871        let mut chain = ancestors.iter(word);
872        // A value slot is an *argument*, so it sits at least two levels
873        // below the root; neither grammar puts a braced word at the root
874        // or directly under it (a statement-position braced word is
875        // wrapped in a `command`, so `{a b}` alone on a line is still two
876        // deep). Both exits are therefore unreachable from a walk and are
877        // here because this is a `pub` trait method any node may be
878        // handed — `braced_slot_tests` calls it at both depths.
879        let Some((parent, above_parent)) = chain.next() else {
880            return false;
881        };
882        if parent.kind_id() == kinds.procedure {
883            let is_name =
884                matches!(parent.child_by_field_name("name"), Some(name) if name.id() == word.id());
885            return is_name && !Self::is_switch_arm(&parent, code, above_parent, kinds);
886        }
887        let Some((owner, above_owner)) = chain.next() else {
888            return false;
889        };
890        if parent.kind_id() != kinds.word_list
891            || !argument_slots_are_readable(&owner, &parent, ancestors)
892            || Self::is_switch_arm(&owner, code, above_owner, kinds)
893        {
894            return false;
895        }
896        let dialect = Dialect { code, kinds };
897        // At both pinned grammars a `word_list` has exactly two possible
898        // owners — `command`'s `arguments` field and `namespace`'s child
899        // — so the third arm is unreachable and stays as the answer a
900        // grammar that grew a third owner should get: no layout, hence
901        // the construct-wide script answer.
902        // `a_word_list_is_owned_only_by_a_command_or_a_namespace` fails
903        // when that stops being true, which is the event this arm exists
904        // for.
905        let roles = if owner.kind_id() == kinds.namespace {
906            namespace_script_slots(&parent, dialect).map(|slots| ArgumentRoles { slots, first: 1 })
907        } else if owner.kind_id() == kinds.command {
908            Self::command_leading_word(&owner, code, kinds)
909                .and_then(script_slots)
910                .map(|slots| ArgumentRoles { slots, first: 0 })
911        } else {
912            None
913        };
914        roles.is_some_and(|roles| !fills_script_slot(word, &parent, roles, dialect))
915    }
916
917    /// Whether `word`, an argument of a `switch` arm command
918    /// ([`is_switch_arm`]), sits in a *body* position rather than a
919    /// *pattern* position.
920    ///
921    /// The arm list is a flat run of `pattern body pattern body …`,
922    /// and the grammar breaks it into commands at newlines. One arm per
923    /// line gives each command a pattern for its name and a body for
924    /// its sole argument; several arms on one line give the first
925    /// pattern's command the whole run as arguments, so the arguments
926    /// alternate `body pattern body …`. The command-name test above
927    /// keeps the *first* braced pattern a literal, but without this
928    /// gate every later one was rescued as a body, and a one-line
929    /// `switch -regexp $v { {^a} {…} {^b} {…} }` fabricated a `{}`
930    /// around `{^b}` that the same arms written one per line did not —
931    /// the score moving with layout, which is what the rule exists to
932    /// stop.
933    ///
934    /// Position is the only signal because it is what Tcl itself uses:
935    /// `switch` pairs the list up by index, with no marker on either
936    /// half. The parity holds across the words that can interpose — a
937    /// `-` fall-through body and a `default` pattern are both
938    /// `simple_word`s and take a slot each — so an even index is a body
939    /// and an odd one a pattern. This is the one place the rule needs a
940    /// sibling *index* rather than a parent kind, and it runs once per
941    /// braced argument of such a command.
942    ///
943    /// The index comes from [`Cursor::goto_first_child_for_byte`], which
944    /// is `O(log n)` in the argument count. A `children().position(..)`
945    /// scan answers identically in `O(n)`, and since every braced word
946    /// of a one-line arm list asks, that made the Halstead walk — and,
947    /// once #1381 routed them through this rule, `find` / `count
948    /// --type string` and the `Ast` dump — quadratic in the width of
949    /// one line: seconds per request at tens of KB (#1381 review). The
950    /// id check keeps the scan's answer for a word that is not one of
951    /// the command's arguments at all.
952    ///
953    /// [`is_switch_arm`]: Self::is_switch_arm
954    /// [`Cursor::goto_first_child_for_byte`]: crate::node::Cursor::goto_first_child_for_byte
955    #[must_use]
956    fn is_switch_arm_body(word: &Node<'_>, command: &Node<'_>) -> bool {
957        // `is_value_braced_word` asks only for a word it has already
958        // placed inside this command's `arguments`, so the field is
959        // always there on that path. It is not always there on the
960        // method's own contract — an argument-less `switch` is a
961        // `command` with a `name` and nothing else — and such a command
962        // has no body position at all.
963        let Some(arguments) = command.child_by_field_name("arguments") else {
964            return false;
965        };
966        let mut cursor = arguments.cursor();
967        let index = cursor.goto_first_child_for_byte(word.start_byte());
968        cursor.node().id() == word.id() && matches!(index, Some(index) if index.is_multiple_of(2))
969    }
970
971    /// A command's leading word, when it is a statically resolvable
972    /// `simple_word`.
973    ///
974    /// Located by field rather than by index (grammar-dispatch §3): the
975    /// name is `command`'s `name` field in both grammars. A computed
976    /// name (`$cmd {…}`, `[pick] {…}`) parses as a substitution node and
977    /// is not resolvable at all, and a name spelled in quotes or braces
978    /// (`"eval" {…}`) is legal Tcl that this deliberately leaves
979    /// unresolved — the same limitation `tcl_command_name` records for
980    /// the Cognitive and Cyclomatic walkers.
981    #[must_use]
982    fn command_leading_word<'c>(
983        command: &Node<'_>,
984        code: &'c [u8],
985        kinds: &BracedWordKinds,
986    ) -> Option<&'c str> {
987        let name = command.child_by_field_name("name")?;
988        if name.kind_id() != kinds.simple_word {
989            return None;
990        }
991        let text = node_text(code, &name)?;
992        // `::eval` *is* `eval`, and without the strip the qualified form
993        // fell to the value default and lost its block. The rule and the
994        // reason it stops at the *leading* qualifier live with the
995        // helper, which the four metrics that resolve a leading word
996        // without this table share (#1381 review).
997        Some(crate::lang_helpers::strip_global_qualifier(text))
998    }
999
1000    /// Whether `command` is really one `pattern body` pair of a Tcl
1001    /// `switch` arm list rather than a command of its own.
1002    ///
1003    /// Tcl models no `switch`, so `switch $v {a {…} b {…}}` parses the
1004    /// arm list as a braced word whose interior is a `command` named
1005    /// after the *first pattern* — `a` here — with the arm bodies as
1006    /// its arguments (grammar-dispatch §9; the Cognitive walker reads
1007    /// the same shape through `tcl_switch_arm_list`). Without this
1008    /// test the bodies would read as literals passed to a command
1009    /// called `a`, which is exactly what the value default is for
1010    /// everywhere else. iRules models `switch` with `switch_arm`
1011    /// children, so its arm bodies never reach here.
1012    #[must_use]
1013    fn is_switch_arm<'a>(
1014        command: &Node<'a>,
1015        code: &[u8],
1016        ancestors: Ancestors<'a, '_>,
1017        kinds: &BracedWordKinds,
1018    ) -> bool {
1019        ancestors
1020            .iter(command)
1021            .next()
1022            .is_some_and(|(arm_list, above)| {
1023                arm_list.kind_id() == kinds.script
1024                    && Self::generic_argument_command(&arm_list, above, kinds)
1025                        .and_then(|(switch, _)| Self::command_leading_word(&switch, code, kinds))
1026                        == Some(SWITCH_COMMAND)
1027            })
1028    }
1029
1030    /// Whether the `{` of `node`'s parent braced word opens a block,
1031    /// or merely quotes a literal (#1318).
1032    ///
1033    /// This is #1314's guard with its kind test replaced by a role
1034    /// test. #1314 suppressed the opener of a `braced_word_simple`,
1035    /// the literal form the grammars emit only in the value slots they
1036    /// special-case; everywhere else a literal is a `braced_word`, the
1037    /// same kind a block uses, and its `{` still reported a `{}`
1038    /// operator for a block the source does not contain —
1039    /// `lappend x {a b}`, `puts {c d}`, and every user proc taking a
1040    /// list.
1041    ///
1042    /// The role is [`is_braced_script_word`], the same predicate
1043    /// `Checker::is_string_with_code` and `Alterator::keeps_children`
1044    /// ask, so the three classifiers answer one question about one set
1045    /// of bytes (grammar-dispatch §7). That was not so between #1318
1046    /// and #1382: this call site asked [`is_value_braced_word`] alone
1047    /// and billed a `{}` for the value slots of a script-taking
1048    /// command, which the other two had called literals since #1381.
1049    /// The exception, and what closing it moved, is recorded on
1050    /// [`is_braced_script_word`], which owns the §7 story for all five
1051    /// call sites.
1052    ///
1053    /// **It revises the operator only, and deliberately leaves the
1054    /// words inside a value alone.** Suppressing them too would make
1055    /// `lappend x {a b}` score like its `set x {a b}` synonym, which
1056    /// is the tidier answer for that line — and the wrong one in
1057    /// general, because the same braced argument of an unrecognised
1058    /// command is just as often real code: an `oo::class create C {…}`
1059    /// body, a `tcltest` `-body {…}`, an `apply {{x} {…}}` lambda.
1060    /// Suppressing contents was built and measured on a file holding
1061    /// one of each; it took n1 5 → 2, N1 8 → 2, n2 25 → 15 and
1062    /// N2 32 → 15, the class body, the test body and the lambda each
1063    /// collapsing into a single operand, and `halstead.effort` — a
1064    /// gated threshold metric — collapsing with them. So the rule only
1065    /// ever withdraws a claim the classifier cannot support; it never
1066    /// discards code the walk has already read.
1067    ///
1068    /// The residual is the asymmetry #1382 opens with, and it is the
1069    /// **contract**, not an outstanding defect: a braced value scores
1070    /// one operand where the grammar names the command (`set x {a b}`)
1071    /// and one per word where only the command name would
1072    /// (`lappend x {a b}`). #1382 weighed the two ways of closing it
1073    /// and took neither. Reading the *contents* — no substitution, no
1074    /// nested block, therefore list-like — is the measurement above,
1075    /// already taken and already rejected. Widening the one-operand
1076    /// treatment to a *value*-taking command list needs the mirror of
1077    /// `SCRIPT_TAKING_COMMANDS`, and that set is open where this one is
1078    /// closed: every user proc is in it, so the list is incomplete by
1079    /// construction and would leave three behaviours where there are
1080    /// two. Both trade a bounded over-report of the operand vocabulary
1081    /// for an unbounded loss of real code, which is the trade the
1082    /// paragraph above declines.
1083    ///
1084    /// Keeping to the operator also keeps the whole thing cheap: only
1085    /// a braced word's own opener can change answer, so the test is one
1086    /// kind comparison and one parent lookup, the same scope #1354 and
1087    /// #1314 use. Two lookups are `O(log n)` rather than `O(1)`, both
1088    /// cursor seeks by byte and both reached only from a *command whose
1089    /// name resolves*: [`is_switch_arm_body`] needs a `switch` arm
1090    /// word's index among its command's arguments, and — since #1382 —
1091    /// [`is_braced_literal_slot`] needs the same index to place a word
1092    /// against the layout `lang_helpers::tcl_family` records. An
1093    /// ancestor scan would have been `O(depth)` per node and quadratic
1094    /// on a deeply nested `expr`, the shape #1122 warns about.
1095    ///
1096    /// The base answer the opener test revises is the one
1097    /// [`get_op_type_with_code`](Self::get_op_type_with_code)'s default
1098    /// gives — the keyword rows first — so a Tcl-family row is read on
1099    /// this path as on every other (#1693).
1100    ///
1101    /// [`is_braced_literal_slot`]: Self::is_braced_literal_slot
1102    /// [`is_braced_script_word`]: Self::is_braced_script_word
1103    /// [`is_switch_arm_body`]: Self::is_switch_arm_body
1104    /// [`is_value_braced_word`]: Self::is_value_braced_word
1105    #[must_use]
1106    fn braced_word_op_type<'a>(
1107        node: &Node<'a>,
1108        code: &[u8],
1109        ancestors: Ancestors<'a, '_>,
1110        kinds: &BracedWordKinds,
1111    ) -> TokenRole {
1112        let base = keyword_or_op_type::<Self>(node, code, ancestors);
1113        // Only the opener can change answer, and the test has to say so
1114        // rather than infer it from the parent kind. A braced word's
1115        // operator children are the `{` *and* every `;` separating two
1116        // of its commands — `_terminator` is a hidden rule, so the
1117        // separator is inlined as a direct child of the `braced_word`
1118        // and both dialects list `SEMI` as an operator. The closer is
1119        // unclassified and a `\n` terminator is not an operator, so
1120        // those two are the whole set.
1121        if node.kind_id() != kinds.open_brace || !matches!(base, TokenRole::Operator) {
1122            return base;
1123        }
1124        let quotes_a_literal = ancestors.iter(node).next().is_some_and(|(parent, above)| {
1125            parent.kind_id() == kinds.script
1126                && !Self::is_braced_script_word(&parent, code, above, kinds)
1127        });
1128        if quotes_a_literal {
1129            TokenRole::Unknown
1130        } else {
1131            base
1132        }
1133    }
1134
1135    /// The grammar's name for the operator kind `id`, used to render a
1136    /// Halstead operator; empty for languages that do not report them.
1137    #[must_use]
1138    fn get_operator_id_as_str(_id: u16) -> &'static str {
1139        ""
1140    }
1141}
1142
1143mod bash;
1144mod c;
1145mod ccomment;
1146mod cpp;
1147mod csharp;
1148mod elixir;
1149mod generic_angles;
1150mod go;
1151mod groovy;
1152mod irules;
1153mod java;
1154mod javascript;
1155mod js_family;
1156mod kotlin;
1157mod lua;
1158mod mozcpp;
1159mod mozjs;
1160mod objc;
1161mod perl;
1162mod php;
1163mod preproc;
1164mod python;
1165mod ruby;
1166mod rust;
1167mod tcl;
1168mod tsx;
1169mod typescript;
1170
1171#[cfg(test)]
1172mod node_text_tests {
1173    use super::node_text;
1174    use crate::langs::RustParser;
1175    use crate::traits::ParserTrait;
1176    use std::path::PathBuf;
1177
1178    /// A node whose span lies inside the buffer it was parsed from
1179    /// yields its exact source text.
1180    #[cfg(feature = "rust")]
1181    #[test]
1182    fn in_bounds_span_returns_text() {
1183        let src = "fn x() {}";
1184        let parser = RustParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.rs"), None);
1185        let root = parser.root();
1186        assert_eq!(node_text(parser.code(), &root), Some(src));
1187    }
1188
1189    /// Reslicing a node against a *shorter* buffer (the stale-span hazard
1190    /// the guard exists for) must degrade to `None`, not panic. A direct
1191    /// `&code[start..end]` would panic here — this is the revert check.
1192    #[cfg(feature = "rust")]
1193    #[test]
1194    fn out_of_bounds_span_returns_none_not_panic() {
1195        let src = "fn x() {}";
1196        let parser = RustParser::new(src.as_bytes().to_vec(), &PathBuf::from("t.rs"), None);
1197        let root = parser.root();
1198        assert!(root.end_byte() > 2);
1199        let truncated = &src.as_bytes()[..2];
1200        assert_eq!(node_text(truncated, &root), None);
1201    }
1202
1203    /// The UTF-8 guard is the *other* failure mode, and unlike the range
1204    /// guard it is reachable without violating the same-parse
1205    /// precondition: `Ast::parse` accepts arbitrary bytes. A span whose
1206    /// bytes are not valid UTF-8 must yield `None`, not a panic and not
1207    /// lossy replacement characters.
1208    #[cfg(feature = "rust")]
1209    #[test]
1210    fn non_utf8_span_returns_none() {
1211        let mut src = b"fn ".to_vec();
1212        src.extend_from_slice(&[0xF0, 0x9F]);
1213        src.extend_from_slice(b"() {}");
1214        let parser = RustParser::new(src.clone(), &PathBuf::from("t.rs"), None);
1215        let root = parser.root();
1216        assert_eq!(root.end_byte(), src.len());
1217        assert_eq!(node_text(parser.code(), &root), None);
1218    }
1219}
1220
1221#[cfg(test)]
1222mod ancestor_tests {
1223    use super::Getter;
1224    use crate::node::{Ancestors, Node};
1225    use crate::test_support::for_each_node_with_chain;
1226    use crate::traits::LanguageInfo;
1227
1228    /// `get_func_space_name` must name a space the same whether it reads
1229    /// the walker's ancestor chain or climbs with `Node::parent`.
1230    ///
1231    /// Two grammars consult an ancestor here, for different reasons:
1232    /// the JS family names an anonymous `function` / arrow from the
1233    /// `pair` or `variable_declarator` holding it, and Elixir skips
1234    /// naming a `def` that sits inside a `quote` template. #1088 moved
1235    /// both onto the chain.
1236    #[cfg(any(
1237        feature = "elixir",
1238        feature = "javascript",
1239        feature = "mozjs",
1240        feature = "typescript",
1241    ))]
1242    fn assert_name_parity<L: LanguageInfo + Getter>(
1243        label: &str,
1244        code: &[u8],
1245        expect_named: &[&str],
1246    ) {
1247        let mut seen: Vec<&str> = Vec::new();
1248        let visited = for_each_node_with_chain::<L>(code, |node: &Node<'_>, chain| {
1249            let known = L::get_func_space_name(node, code, Ancestors::known(chain));
1250            let climbing = L::get_func_space_name(node, code, Ancestors::unknown());
1251            assert_eq!(
1252                known,
1253                climbing,
1254                "{label}: name of {} at row {} disagrees",
1255                node.kind(),
1256                node.start_row()
1257            );
1258            if let Some(name) = known
1259                && expect_named.contains(&name)
1260                && !seen.contains(&name)
1261            {
1262                seen.push(name);
1263            }
1264        });
1265        assert!(visited > 20, "{label}: fixture is too small to prove much");
1266        for name in expect_named {
1267            assert!(
1268                seen.contains(name),
1269                "{label}: no node resolved to {name:?}, so the fixture no longer \
1270                 exercises the ancestor-derived naming it was added for"
1271            );
1272        }
1273    }
1274
1275    #[cfg(all(
1276        feature = "elixir",
1277        feature = "javascript",
1278        feature = "mozjs",
1279        feature = "typescript",
1280    ))]
1281    #[test]
1282    fn func_space_name_agrees_between_known_and_climbing() {
1283        // `outer` and `keyed` are only reachable through the parent:
1284        // the function expressions themselves carry no `name` field.
1285        //
1286        // All four JS-family grammars are exercised, not just
1287        // JavaScript: their `get_func_space_name` impls are separate
1288        // copies of the same body against four distinct `kind_id`
1289        // enums, so a `Pair` / `VariableDeclarator` id that drifted in
1290        // one grammar would be invisible here if only one were checked.
1291        let js_source =
1292            b"var outer = function () { return 1; };\nvar o = { keyed: function () { return 2; } };\n";
1293        assert_name_parity::<crate::langs::JavascriptCode>(
1294            "javascript",
1295            js_source,
1296            &["outer", "keyed"],
1297        );
1298        assert_name_parity::<crate::langs::MozjsCode>("mozjs", js_source, &["outer", "keyed"]);
1299        assert_name_parity::<crate::langs::TypescriptCode>(
1300            "typescript",
1301            js_source,
1302            &["outer", "keyed"],
1303        );
1304        assert_name_parity::<crate::langs::TsxCode>("tsx", js_source, &["outer", "keyed"]);
1305        // `multi` is named from its `Call` head; the `def a` inside the
1306        // `quote` template is not a definition, so it falls through to
1307        // the field-less default.
1308        assert_name_parity::<crate::langs::ElixirCode>(
1309            "elixir",
1310            b"defmodule Foo do\n  defmacro multi do\n    quote do\n      def a, do: 1\n    end\n  end\nend\n",
1311            &["Foo", "multi"],
1312        );
1313    }
1314}
1315
1316/// The `is_braced_literal_slot` / `is_switch_arm_body` guards that no
1317/// Tcl-family walk can reach, and the grammar shape each rests on.
1318#[cfg(test)]
1319#[cfg(any(feature = "tcl", feature = "irules"))]
1320mod braced_slot_tests {
1321    use super::{BracedWordKinds, Getter};
1322    // Gated with the rows that name it: `Tcl` is read only by the
1323    // `feature = "tcl"` helpers below, so the module's wider
1324    // `any(tcl, irules)` gate would leave this unused — and `ci.yml` sets
1325    // `RUSTFLAGS: "-D warnings"`, which turns that into a hard failure on
1326    // an `irules`-without-`tcl` build.
1327    #[cfg(feature = "tcl")]
1328    use crate::Tcl;
1329    use crate::node::{Ancestors, Node};
1330    use crate::test_support::for_each_node_with_chain;
1331    use crate::traits::LanguageInfo;
1332
1333    /// No node shallower than an argument can fill a value slot.
1334    ///
1335    /// A value slot is an argument, and both grammars hang an argument at
1336    /// least two levels below the root — under a `word_list` under a
1337    /// `command`, or under a construct's own node. A statement-position
1338    /// braced word is no exception: `{a b}` alone on a line is a `command`
1339    /// wrapping the braced word, never the braced word itself. So the root
1340    /// and its direct children are exactly the depths
1341    /// `is_braced_literal_slot`'s two chain exits answer for, and no walk
1342    /// reaches either.
1343    ///
1344    /// They are still the method's contract — it is `pub`, takes any node,
1345    /// and must not read a slot into something with no argument list above
1346    /// it. Flipping either exit to `true` makes this fail.
1347    fn assert_no_shallow_value_slot<L: LanguageInfo + Getter>(
1348        label: &str,
1349        code: &[u8],
1350        kinds: &BracedWordKinds,
1351    ) {
1352        let (mut roots, mut children) = (0, 0);
1353        for_each_node_with_chain::<L>(code, |node: &Node<'_>, chain| {
1354            if chain.len() > 1 {
1355                return;
1356            }
1357            for ancestors in [Ancestors::known(chain), Ancestors::unknown()] {
1358                assert!(
1359                    !L::is_braced_literal_slot(node, code, ancestors, kinds),
1360                    "{label}: a {} at depth {} filled a value slot",
1361                    node.kind(),
1362                    chain.len()
1363                );
1364            }
1365            if chain.is_empty() {
1366                roots += 1;
1367            } else {
1368                children += 1;
1369            }
1370        });
1371        assert_eq!(roots, 1, "{label}: exactly one root");
1372        assert!(
1373            children > 1,
1374            "{label}: the fixture must put several nodes directly under the \
1375             root, or the depth-1 exit goes unexercised"
1376        );
1377    }
1378
1379    #[test]
1380    #[cfg(feature = "tcl")]
1381    fn tcl_no_node_above_an_argument_fills_a_value_slot() {
1382        assert_no_shallow_value_slot::<crate::langs::TclCode>(
1383            "tcl",
1384            b"{a b}\nproc {my proc} {} {}\nnamespace export {c d}\n",
1385            &crate::lang_helpers::tcl::BRACED_WORD_KINDS,
1386        );
1387    }
1388
1389    #[test]
1390    #[cfg(feature = "irules")]
1391    fn irules_no_node_above_an_argument_fills_a_value_slot() {
1392        assert_no_shallow_value_slot::<crate::langs::IrulesCode>(
1393            "irules",
1394            b"{a b}\nproc {my proc} {} {}\nnamespace export {c d}\n",
1395            &crate::lang_helpers::irules::BRACED_WORD_KINDS,
1396        );
1397    }
1398
1399    /// Every braced word of `code` that fills a value slot, in source
1400    /// order. Tcl only: `is_braced_literal_slot` is a provided method, so
1401    /// both dialects run the identical body over their own kind table.
1402    ///
1403    /// Walks with [`Ancestors::unknown`] rather than through
1404    /// `for_each_node_with_chain`, whose fixtures must parse cleanly so a
1405    /// walk cannot cover error recovery by accident — which is exactly
1406    /// what the callers below are about. The two spellings answer
1407    /// identically here; `assert_no_shallow_value_slot` above asserts
1408    /// that on every node it visits.
1409    #[cfg(feature = "tcl")]
1410    fn value_slot_texts(code: &[u8]) -> Vec<String> {
1411        let tree = crate::node::Tree::new::<crate::langs::TclCode>(code);
1412        tree.get_root()
1413            .preorder()
1414            .filter(|node| {
1415                <crate::langs::TclCode as Getter>::is_braced_literal_slot(
1416                    node,
1417                    code,
1418                    Ancestors::unknown(),
1419                    &crate::lang_helpers::tcl::BRACED_WORD_KINDS,
1420                )
1421            })
1422            .map(|node| node.utf8_text(code).unwrap_or_default().to_owned())
1423            .collect()
1424    }
1425
1426    /// A parse error nested inside one argument's *script* leaves its
1427    /// sibling *value* slots alone (#1381 review).
1428    ///
1429    /// `Node::has_error` is transitive, so asking it of the command
1430    /// withdrew the rescue from every argument: `trap {pat} {v} {puts ]}`
1431    /// lost both value slots, and the dump then rendered each as a
1432    /// fabricated `command` named after its own text. What decides
1433    /// whether the positions are readable is the argument list's own slot
1434    /// sequence, and an error *inside* an argument moves no sibling's
1435    /// index. Verified by reverting the guard to `owner.has_error()`:
1436    /// the error row then comes back empty and this fails.
1437    ///
1438    /// Asserted as the *same* list for both fixtures rather than as a
1439    /// non-empty one for the error row. The well-formed row is what pins
1440    /// that the fixture still spells two value slots at all, so trimming
1441    /// one out fails here instead of quietly reducing the claim to
1442    /// "nothing changed".
1443    #[test]
1444    #[cfg(feature = "tcl")]
1445    fn an_error_inside_a_script_argument_keeps_the_sibling_value_slots() {
1446        let well_formed = value_slot_texts(b"trap {pat} {v} {puts j}\n");
1447        assert_eq!(
1448            well_formed,
1449            ["{pat}", "{v}"],
1450            "the fixture must spell two value slots before an error is added"
1451        );
1452        assert_eq!(
1453            value_slot_texts(b"trap {pat} {v} {puts ]}\n"),
1454            well_formed,
1455            "an error inside the script argument moves no sibling's index"
1456        );
1457    }
1458
1459    /// The other half of the same rule: an `ERROR` token occupying a slot
1460    /// of the argument list *does* shift every argument after it, so the
1461    /// construct-wide answer is the right one there.
1462    ///
1463    /// `on code varList script` reads its slots by position, and the
1464    /// stray `]` takes one of its own — so `{code}` is no longer
1465    /// followed by the variable list the signature puts there and the
1466    /// layout cannot be trusted. Without this row the guard could be
1467    /// deleted outright and the test above would still pass.
1468    ///
1469    /// The fixture keeps the clause's three arguments deliberately: the
1470    /// `]` replaces the variable list rather than joining it, so
1471    /// `ScriptSlots::LastOf`'s arity rule still admits the list and
1472    /// `argument_slots_are_readable` is the only guard that can reject
1473    /// it. A four-argument spelling would be rejected twice over and
1474    /// this row would stop naming which guard it tests (#1382 review).
1475    ///
1476    /// The well-formed row is what keeps the empty one from passing
1477    /// vacuously: `on` reaching the slot table at all is what makes the
1478    /// error row's emptiness mean something, and dropping that row from
1479    /// `SCRIPT_TAKING_COMMANDS` empties both. The siblings either side
1480    /// of this test anchor the same way.
1481    #[test]
1482    #[cfg(feature = "tcl")]
1483    fn an_error_occupying_a_slot_withdraws_the_layout() {
1484        assert_eq!(
1485            value_slot_texts(b"on {code} {v} {puts j}\n"),
1486            ["{code}", "{v}"],
1487            "the fixture must spell two value slots before the error \
1488             takes one of their places"
1489        );
1490        assert!(
1491            value_slot_texts(b"on {code} ] {puts j}\n").is_empty(),
1492            "an ERROR token in the argument list makes every position \
1493             unreadable"
1494        );
1495    }
1496
1497    /// The third way a layout stops being readable: the grammar groups
1498    /// a *following* clause into this one, so the list is longer than
1499    /// the signature admits (#1382 review).
1500    ///
1501    /// Tcl models neither `on` nor `trap` outside a `try`, so a
1502    /// top-level `try … trap … finally` parses the whole tail as one
1503    /// generic `trap` command — `p v b finally c`. Reading "the script
1504    /// is the last argument" off that names the `finally` body and
1505    /// calls the handler body a value, which withdraws the `{}` of a
1506    /// real block and flattens it out of the dump. Both rows run the
1507    /// same clause, so the second cannot pass by the fixture having
1508    /// stopped spelling a value slot at all.
1509    #[test]
1510    #[cfg(feature = "tcl")]
1511    fn a_handler_clause_of_the_wrong_arity_withdraws_the_layout() {
1512        assert_eq!(
1513            value_slot_texts(b"try {puts a} trap {p} {v} {puts b}\n"),
1514            ["{p}", "{v}"],
1515            "a three-argument `trap` clause spells two value slots"
1516        );
1517        assert!(
1518            value_slot_texts(b"try {puts a} trap {p} {v} {puts b} finally {puts c}\n").is_empty(),
1519            "a trailing `finally` joins the same generic `trap` command, \
1520             so no position in its argument list is trustworthy"
1521        );
1522    }
1523
1524    /// A command with no argument list has no `switch`-arm body position.
1525    ///
1526    /// `is_value_braced_word` only ever asks about a word it has already
1527    /// placed inside the command's `arguments`, so that field is always
1528    /// present on the walk's path. It is absent for an argument-less
1529    /// command — `switch` on a line by itself is a `command` carrying only
1530    /// its `name` — and the method has to answer for one, because a
1531    /// bodiless command has no even-indexed slot to be in.
1532    ///
1533    /// The second half is the same method's positive answer on a real arm
1534    /// list, so the first cannot be satisfied by a constant.
1535    #[test]
1536    #[cfg(feature = "tcl")]
1537    fn a_command_without_arguments_has_no_switch_arm_body() {
1538        use crate::node::Tree;
1539
1540        let code = b"switch\nswitch $v { p {puts a} }\n";
1541        let tree = Tree::new::<crate::langs::TclCode>(code);
1542        let root = tree.get_root();
1543        let bare = root.child(0).expect("the bare `switch` command");
1544        let name = bare
1545            .child_by_field_name("name")
1546            .expect("even a bare command names itself");
1547        assert!(
1548            bare.child_by_field_name("arguments").is_none(),
1549            "the fixture's first command must carry no argument list"
1550        );
1551        assert!(
1552            !<crate::langs::TclCode as Getter>::is_switch_arm_body(&name, &bare),
1553            "a command with no argument list has no body position"
1554        );
1555
1556        let arm = find_arm_named_p(&root, code).expect("the arm command named `p`");
1557        let body = arm
1558            .child_by_field_name("arguments")
1559            .and_then(|args| args.child(0))
1560            .expect("the arm's body");
1561        assert!(
1562            <crate::langs::TclCode as Getter>::is_switch_arm_body(&body, &arm),
1563            "the arm's sole argument is its body, or the assertion above is \
1564             satisfied by a constant"
1565        );
1566    }
1567
1568    /// The `command` a Tcl `switch` arm list spells its first pattern as.
1569    #[cfg(feature = "tcl")]
1570    fn find_arm_named_p<'a>(node: &Node<'a>, code: &[u8]) -> Option<Node<'a>> {
1571        let named_p = node.kind_id() == Tcl::Command as u16
1572            && node
1573                .child_by_field_name("name")
1574                .is_some_and(|name| name.utf8_text(code) == Some("p"));
1575        if named_p {
1576            return Some(*node);
1577        }
1578        node.children()
1579            .find_map(|child| find_arm_named_p(&child, code))
1580    }
1581
1582    /// Only a `command` and a `namespace` own a `word_list`, which is what
1583    /// makes `is_braced_literal_slot`'s third owner arm unreachable.
1584    ///
1585    /// Checked against both pinned grammars' `node-types.json` when that
1586    /// arm was written; this is the executable half, so a grammar bump
1587    /// handing a `word_list` to a third construct fails here rather than
1588    /// silently routing it to the no-layout answer.
1589    fn assert_word_list_owners<L: LanguageInfo>(label: &str, code: &[u8], kinds: &BracedWordKinds) {
1590        let mut seen = 0;
1591        for_each_node_with_chain::<L>(code, |node: &Node<'_>, chain| {
1592            if node.kind_id() != kinds.word_list {
1593                return;
1594            }
1595            let owner = chain.last().expect("a word_list is never the root");
1596            assert!(
1597                [kinds.command, kinds.namespace].contains(&owner.kind_id()),
1598                "{label}: a word_list owned by {}",
1599                owner.kind()
1600            );
1601            seen += 1;
1602        });
1603        assert!(seen > 2, "{label}: fixture reached only {seen} word_lists");
1604    }
1605
1606    /// Both owners plus the modelled constructs either grammar spells, so
1607    /// a new owner among them is what the assertion catches.
1608    const WORD_LIST_OWNER_FIXTURE: &[u8] = b"proc p {x} { puts $x }\n\
1609        namespace eval ns { puts hi }\n\
1610        namespace export {a b}\n\
1611        if {$x} { puts a } else { puts b }\n\
1612        while {$x} { puts a }\n\
1613        foreach i {1 2} { puts $i }\n\
1614        catch { puts a } msg\n\
1615        eval {puts hi}\n\
1616        switch $v { p {puts a} }\n\
1617        lappend l {c d}\n";
1618
1619    #[test]
1620    #[cfg(feature = "tcl")]
1621    fn tcl_a_word_list_is_owned_only_by_a_command_or_a_namespace() {
1622        assert_word_list_owners::<crate::langs::TclCode>(
1623            "tcl",
1624            WORD_LIST_OWNER_FIXTURE,
1625            &crate::lang_helpers::tcl::BRACED_WORD_KINDS,
1626        );
1627    }
1628
1629    #[test]
1630    #[cfg(feature = "irules")]
1631    fn irules_a_word_list_is_owned_only_by_a_command_or_a_namespace() {
1632        assert_word_list_owners::<crate::langs::IrulesCode>(
1633            "irules",
1634            WORD_LIST_OWNER_FIXTURE,
1635            &crate::lang_helpers::irules::BRACED_WORD_KINDS,
1636        );
1637    }
1638}
1639
1640#[cfg(test)]
1641mod keyword_role_tests {
1642    //! `get_keyword_role` is read on every path to a `TokenRole`, and
1643    //! the byte-less `get_op_type` no longer knows a keyword (#1693).
1644    //! Each spelling the walk can call is exercised on one language:
1645    //! the default forwarder, a `get_op_type_with_code` override, and
1646    //! `braced_word_op_type`.
1647
1648    use super::{Getter, keyword_or_op_type};
1649    use crate::node::{Ancestors, Node};
1650    use crate::test_support::for_each_node_with_chain;
1651    use crate::token_role::TokenRole;
1652    use crate::traits::LanguageInfo;
1653
1654    /// The `(kind, role)` pairs `classify` answers for every leaf of
1655    /// `source` that it does not call `Unknown`.
1656    #[cfg(any(
1657        feature = "c",
1658        feature = "cpp",
1659        feature = "mozcpp",
1660        feature = "objc",
1661        feature = "java",
1662        feature = "groovy",
1663        feature = "javascript",
1664        feature = "mozjs",
1665        feature = "typescript",
1666        feature = "python",
1667        feature = "rust",
1668        feature = "kotlin",
1669    ))]
1670    fn roles_of<L: LanguageInfo + Getter>(
1671        source: &[u8],
1672        classify: impl for<'a> Fn(&Node<'a>, &[u8], Ancestors<'a, '_>) -> TokenRole,
1673    ) -> Vec<(&'static str, TokenRole)> {
1674        let mut out = Vec::new();
1675        for_each_node_with_chain::<L>(source, |node, chain| {
1676            let role = classify(node, source, Ancestors::known(chain));
1677            if role != TokenRole::Unknown {
1678                out.push((node.kind(), role));
1679            }
1680        });
1681        out
1682    }
1683
1684    /// Kotlin's byte-less `get_op_type` string arm reads the `StringLit`
1685    /// row's `wraps` list through `string_operand_type`: a plain literal
1686    /// is one operand and an interpolating one (the long `${…}` form,
1687    /// the only one the byte-less arm can see) is `Unknown`, as the
1688    /// `_with_code` arm answers for both. The byte-less arm is reached
1689    /// only when no row and no `_with_code` arm answers first, which
1690    /// nothing on the walk does for a string literal, so it is asked
1691    /// here directly.
1692    #[cfg(feature = "kotlin")]
1693    #[test]
1694    fn kotlin_byte_less_string_arm_reads_the_rows_wraps_list() {
1695        use crate::KotlinCode;
1696        let source = b"val a = \"plain\"\nval b = \"x ${a} y\"\nval c = \"\"\"raw\"\"\"\n";
1697        let byte_less = roles_of::<KotlinCode>(source, |n, _, a| KotlinCode::get_op_type(n, a))
1698            .into_iter()
1699            .filter(|(kind, _)| matches!(*kind, "string_literal" | "multiline_string_literal"))
1700            .collect::<Vec<_>>();
1701        let with_code = roles_of::<KotlinCode>(source, KotlinCode::get_op_type_with_code)
1702            .into_iter()
1703            .filter(|(kind, _)| matches!(*kind, "string_literal" | "multiline_string_literal"))
1704            .collect::<Vec<_>>();
1705        // `"plain"` and `\"\"\"raw\"\"\"` are operands; the interpolating
1706        // `"x ${a} y"` is `Unknown` and so absent from both lists.
1707        assert_eq!(
1708            byte_less,
1709            [
1710                ("string_literal", TokenRole::Operand),
1711                ("multiline_string_literal", TokenRole::Operand),
1712            ]
1713        );
1714        assert_eq!(
1715            byte_less, with_code,
1716            "the two spellings agree on every literal"
1717        );
1718    }
1719
1720    /// The control-flow keywords of a keyword-paying language — `if`,
1721    /// `for`, `while`, `catch`, Java's and Groovy's `switch` — reach
1722    /// `Operator` through `get_paying_role` (the `Branch` / `Loop` /
1723    /// `Catch` / `Switch` rows' token projection, #1697) and through the
1724    /// walk's `get_op_type_with_code`, and the byte-less `get_op_type`
1725    /// no longer bills them; `else`, which no row owns, still goes
1726    /// through the byte-less arm. The keyword *tokens* are the anonymous
1727    /// `if` / `for` / … kinds, so a `kind()` of `"if"` here is never the
1728    /// statement.
1729    #[cfg(any(
1730        feature = "c",
1731        feature = "cpp",
1732        feature = "mozcpp",
1733        feature = "objc",
1734        feature = "java",
1735        feature = "groovy",
1736        feature = "javascript",
1737        feature = "mozjs",
1738        feature = "typescript",
1739        feature = "python",
1740        feature = "rust",
1741    ))]
1742    fn control_keywords_bill_through_the_rows<L: LanguageInfo + Getter>(
1743        source: &[u8],
1744        keywords: &[&'static str],
1745    ) {
1746        let via_walk = roles_of::<L>(source, L::get_op_type_with_code);
1747        let via_rows = roles_of::<L>(source, L::get_paying_role);
1748        let via_byte_less = roles_of::<L>(source, |n, _, a| L::get_op_type(n, a));
1749        for &kw in keywords {
1750            let billed = (kw, TokenRole::Operator);
1751            assert!(via_walk.contains(&billed), "{kw}: missing from the walk");
1752            assert!(via_rows.contains(&billed), "{kw}: the rows do not bill it");
1753            assert!(
1754                !via_byte_less.contains(&billed),
1755                "{kw}: still billed byte-less"
1756            );
1757        }
1758        let else_kw = ("else", TokenRole::Operator);
1759        assert!(
1760            via_byte_less.contains(&else_kw),
1761            "`else` is no row's and stays"
1762        );
1763        assert!(!via_rows.contains(&else_kw));
1764    }
1765
1766    /// One row per language that joined `paying_roles!(…, control_flow)`;
1767    /// the C-family and JS-family sources are shared across their
1768    /// dialects.
1769    macro_rules! control_keywords_test {
1770        ($name:ident, $feature:literal, $code:ident, $source:expr, $keywords:expr) => {
1771            #[cfg(feature = $feature)]
1772            #[test]
1773            fn $name() {
1774                control_keywords_bill_through_the_rows::<crate::$code>($source, $keywords);
1775            }
1776        };
1777    }
1778
1779    #[cfg(any(feature = "c", feature = "objc"))]
1780    const CONTROL_KEYWORDS_C: &[&str] = &["if", "for", "while"];
1781    #[cfg(any(
1782        feature = "cpp",
1783        feature = "mozcpp",
1784        feature = "javascript",
1785        feature = "mozjs",
1786        feature = "typescript"
1787    ))]
1788    const CONTROL_KEYWORDS_WITH_CATCH: &[&str] = &["if", "for", "while", "catch"];
1789    #[cfg(any(feature = "java", feature = "groovy"))]
1790    const CONTROL_KEYWORDS_JVM: &[&str] = &["if", "for", "while", "switch", "catch"];
1791    #[cfg(any(feature = "cpp", feature = "mozcpp"))]
1792    const CONTROL_KEYWORDS_CPP_SOURCE: &[u8] =
1793        b"int f(int a) { if (a) { } else { } for (;;) { } while (a) { } try { } catch (int e) { } return 0; }\n";
1794    #[cfg(any(feature = "javascript", feature = "mozjs", feature = "typescript"))]
1795    const CONTROL_KEYWORDS_JS_SOURCE: &[u8] =
1796        b"function f(a) { if (a) { } else { } for (;;) { } while (a) { } try { } catch (e) { } }\n";
1797
1798    control_keywords_test!(
1799        c_control_keywords_are_billed_by_the_rows,
1800        "c",
1801        CCode,
1802        b"int f(int a) { if (a) { } else { } for (;;) { } while (a) { } switch (a) { } return 0; }\n",
1803        CONTROL_KEYWORDS_C
1804    );
1805    control_keywords_test!(
1806        cpp_control_keywords_are_billed_by_the_rows,
1807        "cpp",
1808        CppCode,
1809        CONTROL_KEYWORDS_CPP_SOURCE,
1810        CONTROL_KEYWORDS_WITH_CATCH
1811    );
1812    control_keywords_test!(
1813        mozcpp_control_keywords_are_billed_by_the_rows,
1814        "mozcpp",
1815        MozcppCode,
1816        CONTROL_KEYWORDS_CPP_SOURCE,
1817        CONTROL_KEYWORDS_WITH_CATCH
1818    );
1819    control_keywords_test!(
1820        objc_control_keywords_are_billed_by_the_rows,
1821        "objc",
1822        ObjcCode,
1823        b"@implementation A\n- (int)f:(int)a { if (a) { } else { } for (;;) { } while (a) { } return 0; }\n@end\n",
1824        CONTROL_KEYWORDS_C
1825    );
1826    control_keywords_test!(
1827        java_control_keywords_are_billed_by_the_rows,
1828        "java",
1829        JavaCode,
1830        b"class A { void f(int a) { if (a > 0) { } else { } for (;;) { } while (a > 0) { } switch (a) { } try { } catch (Exception e) { } } }\n",
1831        CONTROL_KEYWORDS_JVM
1832    );
1833    control_keywords_test!(
1834        groovy_control_keywords_are_billed_by_the_rows,
1835        "groovy",
1836        GroovyCode,
1837        b"class A { void f(int a) { if (a) { } else { } for (;;) { } while (a) { } switch (a) { } try { } catch (Exception e) { } } }\n",
1838        CONTROL_KEYWORDS_JVM
1839    );
1840    control_keywords_test!(
1841        javascript_control_keywords_are_billed_by_the_rows,
1842        "javascript",
1843        JavascriptCode,
1844        CONTROL_KEYWORDS_JS_SOURCE,
1845        CONTROL_KEYWORDS_WITH_CATCH
1846    );
1847    control_keywords_test!(
1848        mozjs_control_keywords_are_billed_by_the_rows,
1849        "mozjs",
1850        MozjsCode,
1851        CONTROL_KEYWORDS_JS_SOURCE,
1852        CONTROL_KEYWORDS_WITH_CATCH
1853    );
1854    control_keywords_test!(
1855        typescript_control_keywords_are_billed_by_the_rows,
1856        "typescript",
1857        TypescriptCode,
1858        CONTROL_KEYWORDS_JS_SOURCE,
1859        CONTROL_KEYWORDS_WITH_CATCH
1860    );
1861    control_keywords_test!(
1862        tsx_control_keywords_are_billed_by_the_rows,
1863        "typescript",
1864        TsxCode,
1865        CONTROL_KEYWORDS_JS_SOURCE,
1866        CONTROL_KEYWORDS_WITH_CATCH
1867    );
1868    // Python's `if` is deliberately not in its list: the statement's
1869    // keyword bills through the row, but the ternary's — which the
1870    // `Branch` row's gate declines — still bills through the byte-less
1871    // arm, so `if` is on both paths and `else` is the only pure control.
1872    control_keywords_test!(
1873        python_control_keywords_are_billed_by_the_rows,
1874        "python",
1875        PythonCode,
1876        b"def f(a, xs):\n    if a:\n        pass\n    elif a:\n        pass\n    else:\n        pass\n    assert a\n    for x in xs:\n        pass\n    while a:\n        break\n    try:\n        pass\n    except E:\n        pass\n",
1877        &["elif", "assert", "for", "while", "except"]
1878    );
1879    // Rust's `for` is deliberately not in its list, for Python's reason:
1880    // the loop's keyword bills through the row, but the type-syntax
1881    // spellings — `impl T for S`, `for<'a>`, which the `Loop` row's gate
1882    // declines (#1720) — still bill through the byte-less arm.
1883    control_keywords_test!(
1884        rust_control_keywords_are_billed_by_the_rows,
1885        "rust",
1886        RustCode,
1887        b"fn f(a: bool, xs: &[u8]) { if a { } else { } for _x in xs { } while a { break; } loop { break; } }\n",
1888        &["if", "while", "loop"]
1889    );
1890
1891    /// Every `for` in the source bills as an *operator* through the walk
1892    /// (#1720 left Halstead untouched): the loop's through the `Loop`
1893    /// row, the four type-syntax spellings through the byte-less arm the
1894    /// row's gate hands them to — so the walk bills all five, the rows
1895    /// one, and the byte-less arm (which sees every spelling) five.
1896    #[cfg(feature = "rust")]
1897    #[test]
1898    fn rust_type_syntax_for_still_bills_as_an_operator() {
1899        let source = b"trait T {}\nstruct S;\nimpl T for S {}\nfn f<F: for<'a> Fn(&'a u8)>(_: F) {}\ntype P = for<'a> fn(&'a u8);\nfn a(_: impl for<'a> Fn(&'a u8)) {}\nfn r(xs: &[u8]) { for _x in xs {} }\n";
1900        let for_operators = |roles: Vec<(&str, TokenRole)>| {
1901            roles
1902                .into_iter()
1903                .filter(|&(kind, role)| kind == "for" && role == TokenRole::Operator)
1904                .count()
1905        };
1906        let via_walk = for_operators(roles_of::<crate::RustCode>(
1907            source,
1908            crate::RustCode::get_op_type_with_code,
1909        ));
1910        let via_rows = for_operators(roles_of::<crate::RustCode>(
1911            source,
1912            crate::RustCode::get_paying_role,
1913        ));
1914        let via_byte_less = for_operators(roles_of::<crate::RustCode>(source, |n, _, a| {
1915            crate::RustCode::get_op_type(n, a)
1916        }));
1917        assert_eq!((via_walk, via_rows, via_byte_less), (5, 1, 5));
1918    }
1919
1920    /// A C-family modifier, declaration keyword and primitive reach
1921    /// `Operator` through `get_op_type_with_code` and through
1922    /// `get_keyword_role` alone, and the byte-less `get_op_type` no
1923    /// longer bills any of the three.
1924    #[cfg(feature = "c")]
1925    #[test]
1926    fn c_keywords_are_billed_by_the_rows_not_the_byte_less_arm() {
1927        use crate::CCode;
1928        let source = b"static struct S { unsigned int a; } s;\n";
1929        let via_walk = roles_of::<CCode>(source, CCode::get_op_type_with_code);
1930        let via_rows = roles_of::<CCode>(source, CCode::get_keyword_role);
1931        let via_byte_less = roles_of::<CCode>(source, |n, _, a| CCode::get_op_type(n, a));
1932        let keywords = [
1933            ("static", TokenRole::Operator),
1934            ("struct", TokenRole::Operator),
1935            ("unsigned", TokenRole::Operator),
1936            ("primitive_type", TokenRole::Operator),
1937        ];
1938        assert_eq!(via_rows, keywords, "the rows bill exactly the keywords");
1939        for keyword in &keywords {
1940            assert!(
1941                via_walk.contains(keyword),
1942                "{keyword:?} missing from the walk: {via_walk:?}"
1943            );
1944            assert!(
1945                !via_byte_less.contains(keyword),
1946                "{keyword:?} is still billed by the byte-less arm: {via_byte_less:?}"
1947            );
1948        }
1949        // Everything the byte-less arm answers, the walk answers too:
1950        // the rows only add to it.
1951        for pair in &via_byte_less {
1952            assert!(
1953                via_walk.contains(pair),
1954                "{pair:?} lost on the walk: {via_walk:?}"
1955            );
1956        }
1957        assert_eq!(via_walk.len(), via_byte_less.len() + keywords.len());
1958    }
1959
1960    /// `keyword_or_op_type` merges the row's answer with the byte-less
1961    /// arm's. On this fixture no node answers both, so it pins the
1962    /// merged stream; the `Conflict` getter below pins the order.
1963    #[cfg(feature = "cpp")]
1964    #[test]
1965    fn keyword_or_op_type_merges_the_row_with_the_byte_less_arm() {
1966        use crate::CppCode;
1967        let source = b"const int x = 1;\n";
1968        let merged = roles_of::<CppCode>(source, keyword_or_op_type::<CppCode>);
1969        assert_eq!(
1970            merged,
1971            [
1972                ("const", TokenRole::Operator),
1973                ("primitive_type", TokenRole::Operator),
1974                ("identifier", TokenRole::Operand),
1975                ("=", TokenRole::Operator),
1976                ("number_literal", TokenRole::Operand),
1977                (";", TokenRole::Operator),
1978            ]
1979        );
1980    }
1981
1982    /// A getter whose row and byte-less arm disagree on every node: the
1983    /// row says `Operand`, the arm `Operator`. Shipped languages do
1984    /// conflict on a few nodes — a Groovy `int` is a `Primitive` row
1985    /// operator and a `type_identifier` operand to the arm, an ObjC
1986    /// property-attribute word a `Modifier` row operator and an
1987    /// `identifier` operand — and their Halstead tests pin each
1988    /// outcome; this pins the rule those outcomes follow from, on every
1989    /// node of a fixture rather than one spelling per language.
1990    /// Built through the macro rather than a hand-written `impl` so the
1991    /// per-language test gate does not read the C test's `CCode::`
1992    /// calls as calls to these methods.
1993    struct Conflict;
1994
1995    macro_rules! conflicting_getter {
1996        ($name:ident, $row:ident, $arm:ident) => {
1997            impl Getter for $name {
1998                fn get_keyword_role<'a>(
1999                    _node: &Node<'a>,
2000                    _code: &[u8],
2001                    _ancestors: Ancestors<'a, '_>,
2002                ) -> TokenRole {
2003                    TokenRole::$row
2004                }
2005
2006                fn get_op_type<'a>(_node: &Node<'a>, _ancestors: Ancestors<'a, '_>) -> TokenRole {
2007                    TokenRole::$arm
2008                }
2009            }
2010        };
2011    }
2012
2013    conflicting_getter!(Conflict, Operand, Operator);
2014
2015    /// Where the row and the byte-less arm both answer, the row wins:
2016    /// swapping the two in `keyword_or_op_type` fails here.
2017    #[cfg(feature = "cpp")]
2018    #[test]
2019    fn keyword_or_op_type_prefers_the_row_on_a_conflict() {
2020        use crate::CppCode;
2021        let roles = roles_of::<CppCode>(b"x;\n", keyword_or_op_type::<Conflict>);
2022        // Every node — the unit, the statement, `x` and `;` — answers
2023        // both ways, and the row's way is the one that comes out.
2024        assert_eq!(
2025            roles,
2026            [
2027                ("translation_unit", TokenRole::Operand),
2028                ("expression_statement", TokenRole::Operand),
2029                ("identifier", TokenRole::Operand),
2030                (";", TokenRole::Operand),
2031            ]
2032        );
2033    }
2034
2035    /// Every `get_op_type_with_code` override ends in
2036    /// `keyword_or_op_type`, so a language reads its keyword rows on
2037    /// the override's path too, pinned by comparing the walk's answer
2038    /// against the fallback's on a fixture the override does not touch.
2039    ///
2040    /// Java's `class` and `int` reach `Operator` only through its rows,
2041    /// so an override reverted to `Self::get_op_type` drops both and
2042    /// fails here.
2043    #[cfg(feature = "java")]
2044    #[test]
2045    fn java_override_reaches_the_fallback() {
2046        use crate::JavaCode;
2047        let source = b"class A { int f() { return 1; } }\n";
2048        let walk = roles_of::<JavaCode>(source, JavaCode::get_op_type_with_code);
2049        let fallback = roles_of::<JavaCode>(source, keyword_or_op_type::<JavaCode>);
2050        assert_eq!(walk, fallback);
2051        assert!(walk.contains(&("class", TokenRole::Operator)), "{walk:?}");
2052    }
2053
2054    /// `braced_word_op_type` revises the fallback's answer rather than
2055    /// the byte-less arm's: Tcl's `proc` reaches `Operator` only through
2056    /// its `DeclKeyword` row, so a revision built on `Self::get_op_type`
2057    /// loses it and the one withdrawn operator below is no longer the
2058    /// literal's brace alone.
2059    #[cfg(feature = "tcl")]
2060    #[test]
2061    fn tcl_braced_word_path_reaches_the_fallback() {
2062        use crate::TclCode;
2063        let source = b"proc f {a} {\n    lappend x {b c}\n    return $x\n}\n";
2064        let offsets = |classify: fn(&Node<'_>, &[u8], Ancestors<'_, '_>) -> TokenRole| {
2065            let mut out = Vec::new();
2066            for_each_node_with_chain::<TclCode>(source, |node, chain| {
2067                if classify(node, source, Ancestors::known(chain)) != TokenRole::Unknown {
2068                    out.push((node.start_byte(), node.kind()));
2069                }
2070            });
2071            out
2072        };
2073        let walk = offsets(TclCode::get_op_type_with_code);
2074        let fallback = offsets(keyword_or_op_type::<TclCode>);
2075        // The braced-word revision withdraws the `{` of `lappend`'s
2076        // literal (#1318), and only that: the walk is the fallback
2077        // minus the one operator at that byte.
2078        let literal = source
2079            .windows(5)
2080            .position(|w| w == b"{b c}")
2081            .expect("fixture spells the literal");
2082        let withdrawn: Vec<_> = fallback
2083            .iter()
2084            .filter(|pair| !walk.contains(pair))
2085            .collect();
2086        assert_eq!(
2087            withdrawn,
2088            [&(literal, "{")],
2089            "walk {walk:?}\nfallback {fallback:?}"
2090        );
2091        assert_eq!(walk.len() + 1, fallback.len());
2092    }
2093}