xpath-style

name	xpath-style
description	Guidelines and conventions for writing, composing, and formatting XPath expressions when building or refactoring linters. Use this skill whenever writing or analyzing XPath queries in linter definitions.

XPath Style and Composition in {lintr}

When implementing, refactoring, or reviewing XPath expressions across lintr (R/), adhere to the following composition, styling, robust AST targeting, and performance guidelines established by project maintainers:

1. Direct Path Steps & Predicates over self::* Transitions

• Avoid redundant self::* navigation axes: When filtering nodes based on ancestral or parent structure, express structural requirements directly inside the target predicate rather than prepending an explicit self::*[...] / step before traversing to siblings or children.
• Leverage shared parent context for siblings: Because following or preceding siblings (following-sibling::*, preceding-sibling::*) share the exact same structural parent (parent::*) as the starting context node, express structural parent conditions directly inside the sibling predicates without extra bracket nesting (parent::expr/OP-LEFT-BRACE over [parent::expr[OP-LEFT-BRACE]]).

  # Anti-pattern: Unnecessary self::* step and nested bracket evaluation
  self::*[parent::expr[OP-LEFT-BRACE]]
    /following-sibling::*[not(self::OP-RIGHT-BRACE)]
  
  # Preferred: Direct verification of parent structure within the sibling predicate
  following-sibling::*[
    parent::expr/OP-LEFT-BRACE
    and not(self::OP-RIGHT-BRACE)
  ][1]
  

2. Modular Composition (glue::glue()) & Helper Utilities

• Decompose complex queries into modular variables: Avoid large, monolithic XPath strings. Break distinct node criteria, structural targets, and sub-conditions into well-named variables (expr_after_control, terminal_call_cond, unreachable_expr_cond_ws) and synthesize the complete expression cleanly using glue().
• Parenthesize compound expressions prior to unions or depth traversing: When combining complex branches via union (|) or traversing deeper via //expr[...] or /following-sibling::*, wrap individual sub-expressions inside explicit parentheses within the composite glue() string:

  xpath_after_terminal_node <- glue("
    ({expr_after_control} | {terminal_fun_expr})//expr[{terminal_call_cond}]/{unreachable_expr_cond_ws}
    | ({expr_after_control} | {terminal_fun_expr})//expr[{terminal_call_cond}]/{unreachable_expr_cond_sc}
    | ({expr_after_control})//expr[NEXT or BREAK]/{unreachable_expr_cond_ws}
  ")
  

• Use built-in {lintr} XPath helpers for 3+ items: Use internal helper functions like xp_or(), xp_and(), and xp_text_in_table() for tables of 3 or more entries (e.g. xp_text_in_table(c("sprintf", "gettextf", "paste"))). For length-2 conditions (text() = 'foo' or text() = 'bar'), write direct literal disjunctions instead—never suggest or replace length-2 table checks with xp_text_in_table(), as direct literal comparisons are cleaner and avoid string interpolation overhead.
• Factor shared invariant predicates out of compound disjunctions: When matching multiple candidate structures inside a predicate using or, factor shared conjuncts out to the surrounding scope instead of distributing them inside every branch. For example, use STR_CONST and (branch_A or branch_B) rather than (branch_A and STR_CONST) or (branch_B and STR_CONST). This reduces evaluation duplication and instantly exposes what truly separates the target branches.
• Order unnested single conditions before multi-condition parenthesized expressions: Inside compound or structures (STR_CONST and (...)), place single-condition branches (preceding-sibling::*[not(self::COMMENT)][2][self::SYMBOL_SUB[...]]) ahead of multi-condition compound branches (). Ordering unnested conditions first eliminates distracting double-bracket indentation right at the opening transition (), markedly improving visual structure and readability.

3. Multi-Line Formatting, Indentation, & Visual Hierarchy

• Format multi-line strings clearly: For non-trivial predicates or sequential criteria, break strings across lines with clean leading whitespace indentation that accurately reflects logical depth and bracket scope ([ ... ]).
• Avoid paste() for multi-line XPath strings: Write clean, multi-line literal strings directly rather than piecing together fragments with paste(...).
• Lead with operators and axis steps on continuation lines: Start continuation lines cleanly with logical boolean operators (and, or, |) or navigation path boundaries (/following-sibling::*, /parent::expr) so visual structure and conditions can be assessed rapidly:

  unreachable_expr_cond_ws <- "
    following-sibling::*[
      parent::expr/OP-LEFT-BRACE
      and not(self::OP-RIGHT-BRACE or self::OP-SEMICOLON or self::ELSE or preceding-sibling::ELSE)
      and (not(self::COMMENT) or @line2 > preceding-sibling::*[not(self::COMMENT)][1]/@line2)
    ][1]"
  

4. XPath Performance & Entry Point Anchoring

• Avoid //* XPaths entirely: Wildcard descendant scanning (//*) is a severe performance bottleneck across {xml2} and libxml2. Even an extensive union chain of specific node names (//A[expr] | //B[expr]) consistently yields substantial speed optimizations (often 3x or greater) compared to unconstrained wildcard matching.
• Avoid //expr XPaths as entry points: Because over one-third of all AST nodes in an R codebase are <expr>, querying //expr as an initial anchor only eliminates a minimal portion of the parse tree. Always anchor initial traversals on more specific syntax nodes (//IF, //FOR, //RIGHT_ASSIGN, //EQ_SUB).
• Use xml_find_function_calls() over //SYMBOL_FUNCTION_CALL entry points: Whenever a linter checks for calls to specific functions, never anchor directly on //SYMBOL_FUNCTION_CALL[text() = 'foo' or text() = 'bar']. Instead, fetch pre-cached structures via source_expression$xml_find_function_calls(c("foo", "bar")), which executes significantly faster across multi-option lookups.
• Prefer xml_find_lgl_() with boolean(...) or not(...) over is.na(xml_find_first_()):
  • xml_find_first() creates intermediate R objects: an XPtrNode external pointer, a list with node and doc elements, names, and class attributes. When testing existence or matching, this object allocation is pure overhead.
  • xml_find_lgl_(x, "boolean(...)") evaluates XPATH_BOOLEAN directly inside libxml2 and returns a flat atomic logical vector with zero intermediate R object allocations. On realistic parse trees, xml_find_lgl_() is ~1.7x faster and consumes 67–75% less memory on large nodesets than xml_find_first_().
  • XPath boolean requirement: In XPath 1.0, xml_find_lgl_() requires an expression that evaluates to a boolean (e.g. boolean(...), not(...), =, ). Passing a raw node query like throws an error.

5. Self-Documentation & Explicit Exclusion Comments

• Annotate structural distinctions: Provide brief, explicit comments above multi-line modular XPath definitions clarifying structural design decisions or separate handling regimes (# normal case: expression after terminal call is on the next line vs # robustness case: expression after terminal call is on the same line).
• Document syntax exclusions right where defined: Whenever an XPath guards against edge-case structures (not(OP-DOLLAR or OP-AT) or not(self::ELSE or preceding-sibling::ELSE)), document the practical rationale or tracking reference directly above (# NB: use not(OP-DOLLAR) to prevent matching process$stop(), #1051) so regressions are prevented during future structural iterations.