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}