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