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