performance-lint-rules

Performance Guidelines

Prefer top-level node kind checks

Put node kind checks at the rule entry point. If a rule only handles a few syntactic forms, start run with an AstKind match and return for all other nodes, even when a helper filters again internally. This lets lintgen derive narrower NODE_TYPES and avoids dispatching the rule on unrelated AST nodes.

After changing the relevant node kinds for a rule, regenerate the rule runner with cargo lintgen and consider adding or updating assert_rule_runs_on_node_types coverage in crates/oxc_linter/src/rule.rs.

Implement only the needed entry point. If a rule is a whole-file pass over semantic indexes, use run_once by itself. Implementing both run and run_once prevents useful node-type narrowing.

Do cheaper checks first

Order checks from cheapest and most selective to most expensive. Return quickly for common non-matches before doing semantic lookups, allocations, or deeper traversal.

• Matching a small fixed string set with matches! before semantic checks.
• Rejecting lowercase identifiers before global-object checks when only constructors can match.
• Checking whether a JSX attribute starts with aria- before lowercasing it.
• Checking for required syntax such as a key prop before looking up callback parameter symbols.
• Checking source_range(span).contains("this") before running a visitor that only finds this.

Delay expensive context

Most files do not contain lint errors. Do not prepare diagnostics, labels, help text, fix data, ancestors, symbols, JSX element types, or replacement strings until the rule has found a syntactic candidate that could actually report.

Iterate over the smallest set possible

• Use run_once when the rule only needs a whole-file pass and does not need to run on every node.
• Iterate over symbols instead of AST nodes when looking for references to specific names.
• Prefer targeted lists or semantic data over broad AST traversal when available.
• For name-based binding checks, use ctx.scoping().get_binding(scope_id, name) instead of scanning every binding in get_bindings(scope_id).
• For global or unresolved identifier checks, start from ctx.scoping().root_unresolved_references().get(name) for the small set of relevant names instead of visiting every IdentifierReference.
• When iterating unresolved references, still verify the reference is the right kind: skip references with a symbol, type-only references, and nodes whose AstKind is not the expected identifier or member access.
• When checking imported specifiers or exported names, iterate the concrete specifiers or precomputed export set rather than scanning all root bindings for every item.