Lint Rule Development

Purpose

Use this skill when creating new lint rules or assist actions for Biome. It provides scaffolding commands, implementation patterns, testing workflows, and documentation guidelines.

Prerequisites

1. Install required tools: just install-tools 2. Ensure cargo, just, and pnpm are available 3. Read crates/biome_analyze/CONTRIBUTING.md for in-depth concepts

Code Standards

CRITICAL: No Emojis

Emojis are BANNED in all lint rule code:

• NO emojis in rustdoc comments
• NO emojis in diagnostic messages
• NO emojis in code action descriptions
• NO emojis in test files or test comments
• NO emojis anywhere in the rule implementation

Keep all code and documentation professional and emoji-free.

Common Workflows

Create a New Lint Rule

Generate scaffolding for a JavaScript lint rule:

just new-js-lintrule useMyRuleName

For other languages:

just new-css-lintrule myRuleName
just new-json-lintrule myRuleName
just new-graphql-lintrule myRuleName

This creates a file in crates/biome_<language>_analyze/src/lint/nursery/use_my_rule_name.rs

All new lint rules must be placed in the nursery group, and require a patch changeset. Use the changeset skill to learn more about writing good changesets.

Implement the Rule

Basic rule structure (generated by scaffolding):

use biome_analyze::{context::RuleContext, declare_lint_rule, Rule, RuleDiagnostic};
use biome_js_syntax::JsIdentifierBinding;
use biome_rowan::AstNode;

declare_lint_rule! {
    /// Disallows the use of prohibited identifiers.
    pub UseMyRuleName {
        version: "next",
        name: "useMyRuleName",
        language: "js",
        recommended: false,
    }
}

impl Rule for UseMyRuleName {
    type Query = Ast<JsIdentifierBinding>;
    type State = ();
    type Signals = Option<Self::State>;
    type Options = ();

    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
        let binding = ctx.query();

        // Check if identifier matches your rule logic
        if binding.name_token().ok()?.text() == "prohibited_name" {
            return Some(());
        }

        None
    }

    fn diagnostic(ctx: &RuleContext<Self>, _state: &Self::State) -> Option<RuleDiagnostic> {
        let node = ctx.query();
        Some(
            RuleDiagnostic::new(
                rule_category!(),
                node.range(),
                // Pillar 1 — WHAT the error is.
                markup! {
                    "This identifier "<Emphasis>"prohibited_name"</Emphasis>" is not allowed."
                },
            )
            // Pillar 2 — WHY it is triggered / why it is a problem.
            .note(markup! {
                "Using this identifier leads to [specific problem]."
            })
            // Pillar 3 — WHAT the user should do to fix it.
            // Use a code action instead when an automated fix is possible.
            .note(markup! {
                "Replace it with [alternative] or remove it entirely."
            }),
        )
    }
}

Note: It's critically important to follow the guidelines in the High Quality Diagnostics section below when writing diagnostics.

The Three Diagnostic Pillars (REQUIRED)

Every diagnostic must follow the three pillars defined in crates/biome_analyze/CONTRIBUTING.md:

Example from `noUnusedVariables`:

RuleDiagnostic::new(
    rule_category!(),
    range,
    // Pillar 1: what
    markup! { "This variable "<Emphasis>{name}</Emphasis>" is unused." },
)
// Pillar 2: why
.note(markup! {
    "Unused variables are often the result of typos, incomplete refactors, or other sources of bugs."
})
// Pillar 3: what to do (here as a note; ideally a code action)
.note(markup! {
    "Remove the variable or use it."
})

Common mistakes to avoid:

• Combining pillars 2 and 3 into a single note — keep them separate.
• Writing pillar 3 as the only note, skipping pillar 2.
• Writing a pillar 1 message that already contains "why" — the message should stay short and factual; move the rationale to pillar 2.

Using Semantic Model

For rules that need binding analysis:

use crate::services::semantic::Semantic;

impl Rule for MySemanticRule {
    type Query = Semantic<JsReferenceIdentifier>;

    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
        let node = ctx.query();
        let model = ctx.model();

        // Check if binding is declared
        let binding = node.binding(model)?;

        // Get all references to this binding
        let all_refs = binding.all_references(model);

        // Get only read references
        let read_refs = binding.all_reads(model);

        // Get only write references
        let write_refs = binding.all_writes(model);

        Some(())
    }
}

Add Code Actions (Fixes)

To provide automatic fixes:

use biome_analyze::FixKind;

declare_lint_rule! {
    pub UseMyRuleName {
        version: "next",
        name: "useMyRuleName",
        language: "js",
        recommended: false,
        fix_kind: FixKind::Safe, // or FixKind::Unsafe
    }
}

impl Rule for UseMyRuleName {
    fn action(ctx: &RuleContext<Self>, _state: &Self::State) -> Option<JsRuleAction> {
        let node = ctx.query();
        let mut mutation = ctx.root().begin();

        // Example: Replace the node
        mutation.replace_node(
            node.clone(),
            make::js_identifier_binding(make::ident("replacement"))
        );

        Some(JsRuleAction::new(
            ctx.metadata().action_category(ctx.category(), ctx.group()),
            ctx.metadata().applicability(),
            markup! { "Use 'replacement' instead" }.to_owned(),
            mutation,
        ))
    }
}

Quick Testing

Use the quick test for rapid iteration:

// In crates/biome_js_analyze/tests/quick_test.rs
// Uncomment #[ignore] and modify:

const SOURCE: &str = r#"
const prohibited_name = 1;
"#;

let rule_filter = RuleFilter::Rule("nursery", "useMyRuleName");

Run the test:

cd crates/biome_js_analyze
cargo test quick_test -- --show-output

Create Snapshot Tests

Create test files in tests/specs/nursery/useMyRuleName/:

tests/specs/nursery/useMyRuleName/
├── invalid.js          # Code that triggers the rule
├── valid.js            # Code that doesn't trigger the rule
└── options.json        # Optional rule configuration

IMPORTANT: Magic Comments for Test Expectations

All test files MUST include magic comments at the top to set expectations:

• Valid tests (should not generate diagnostics):

/* should not generate diagnostics */
const allowed_name = 1;

• Invalid tests (should generate diagnostics):

// should generate diagnostics
const prohibited_name = 1;
const another_prohibited = 2;

For HTML files:

<!-- should not generate diagnostics -->
<!doctype html>
<html>...</html>

For languages that support both comment styles, use /* */ or // as appropriate. The comment should be the very first line of the file.

These magic comments:

• Document the intent of the test file
• Help reviewers understand what's expected
• Serve as a quick reference when debugging test failures

Example invalid.js:

// should generate diagnostics
**Every test file must start with a top-level comment** declaring whether it expects diagnostics. The test runner enforces this — see the `testing-codegen` skill for full rules. The short version:

`valid.js` — comment is **mandatory** (test panics without it):

/ should not generate diagnostics / const x = 1; const y = 2;

`invalid.js` — comment is strongly recommended (also enforced when present):

/ should generate diagnostics / const prohibited_name = 1; const another_prohibited = 2;

Example `valid.js`:

/ should not generate diagnostics / const allowed_name = 1; const another_allowed = 2;

Run snapshot tests:

just test-lintrule useMyRuleName

Review snapshots:

cargo insta accept # accept all snapshots cargo insta reject # reject all snapshots

### Generate Analyzer Code

During development, use the lightweight codegen commands:

just gen-rules # Updates rule registrations in *_analyze crates just gen-configuration # Updates configuration schemas

These generate enough code to compile and test your rule without errors.

For full codegen (migrations, schema, bindings, formatting), run:

just gen-analyzer

**Note:** The CI autofix job runs `gen-analyzer` automatically when you open a PR, so running it locally is optional.

### Format and Lint

Before committing:

just f # Format code just l # Lint code

### Adding Configurable Options

When a rule needs user-configurable behavior, add options via the `biome_rule_options` crate.
For the full reference (merge strategies, design guidelines, common patterns), see
[references/OPTIONS.md](references/OPTIONS.md).

**Quick workflow:**

**Step 1.** Define the options type in `biome_rule_options/src/<snake_case_rule_name>.rs`:

use biome_deserialize_macros::{Deserializable, Merge}; use serde::{Deserialize, Serialize};

#[derive(Debug, Default, Clone, Serialize, Deserialize, Deserializable, Merge)] #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))] #[serde(rename_all = "camelCase", deny_unknown_fields, default)] pub struct UseMyRuleNameOptions { #[serde(skip_serializing_if = "Option::is_none")] pub behavior: Option<MyBehavior>, }

**Step 2.** Wire it into the rule:

use biome_rule_options::use_my_rule_name::UseMyRuleNameOptions;

impl Rule for UseMyRuleName { type Options = UseMyRuleNameOptions;

fn run(ctx: &RuleContext<Self>) -> Self::Signals { let options = ctx.options(); let behavior = options.behavior.unwrap_or_default(); // ... } }

**Step 3.** Test with `options.json` in the test directory (see [references/OPTIONS.md](references/OPTIONS.md) for examples).

**Step 4.** Run codegen: `just gen-rules && just gen-configuration`

**Key rules:**
- All fields must be `Option<T>` for config merging to work
- Use `Box<[Box<str>]>` instead of `Vec<String>` for collection fields
- Use `#[derive(Merge)]` for simple cases, implement `Merge` manually for collections
- Only add options when truly needed (conflicting community preferences, multiple valid interpretations)

## Tips

- **Rule naming**: Use `no*` prefix for rules that forbid something (e.g., `noVar`), `use*` for rules that mandate something (e.g., `useConst`)
- **Nursery group**: All new rules start in the `nursery` group
- **Semantic queries**: Use `Semantic<Node>` query when you need binding/scope analysis
- **Multiple signals**: Return `Vec<Self::State>` or `Box<[Self::State]>` to emit multiple diagnostics
- **Safe vs Unsafe fixes**: Mark fixes as `Unsafe` if they could change program behavior
- **Check for globals**: Always verify if a variable is global before reporting it (use semantic model)
- **Error recovery**: When navigating CST, use `.ok()?` pattern to handle missing nodes gracefully
- **Testing arrays**: Use `.jsonc` files with arrays of code snippets for multiple test cases

## Common Mistakes to Avoid

Generally, mistakes revolve around allocating unnecessary data during rule execution, which can lead to performance issues. Common examples include:

- Placing `String` or `Box<str>` in a Rule's `State` type. It's a strong indicator that you are allocating a string unnecessarily. If the string comes from a CST token, this usually can be avoided by using `TokenText` instead.
- Building strings or other data structures only used in the code action in `run()` instead of `action()`. `run()` should only decide whether to emit a diagnostic; `action()` should build the fix. This matters for performance because building the action can be expensive, and we should avoid doing it when no diagnostic is emitted.
- Recursion. It's often completely unnecessary to write recursive functions, especially when you need to traverse node trees. There are existing utilities like `ancestors()`, `descendants()`, and `preorder()` that can cover the vast majority of cases.

## Common Query Types

// Simple AST query type Query = Ast<JsVariableDeclaration>;

// Semantic query (needs binding info) type Query = Semantic<JsReferenceIdentifier>;

// Multiple node types (requires declare_node_union!) declare_node_union! { pub AnyFunctionLike = AnyJsFunction | JsMethodObjectMember | JsMethodClassMember } type Query = Semantic<AnyFunctionLike>;

## High Quality Diagnostics

**VERY IMPORTANT**: Rule diagnostics MUST convey these messages, in this order:

1. What the problem is
2. Why it's a problem (motivation to fix the issue)
3. How to fix it (actionable advice)

If the rule has an `action()` to fix the issue, the 3rd message should go in the action's message. If not, it should go in the diagnostic's advice.

Diagnostics must remain focused on the specific issue that the rule is flagging. Avoid including superfluous details that aren't directly relevant to the problem, as this can overwhelm users and obscure the main point.
If a rule can flag multiple classes of the same category of issue, the diagnostic messages should be surgically customized to the specific issue being flagged, rather than using generic messages that apply to all cases. This ensures that users receive precise and relevant information about the problem and how to fix it.

### Examples

Good:

1. "Foo is not allowed here." 2. "Foo harms readability because of X, Y, Z." 3. "Consider using Bar instead, which is more concise and easier to read."

1. "Unexpected for-in loop." 2. "For-in loops are confusing and easy to misuse." 3. "You likely want to use a regular loop, for-of loop or forEach instead."

Bad:

1. "Prefer let or const over var." // conflates the what and the how in one message, 2. "var is bad." // not meaningful motivation to fix, doesn't explain the consequences // third message missing is bad, because it doesn't give users a clear path to fix the issue

1. "This var declaration is not at the top of its containing scope." // Good start, explains what the problem is 2. "Move standalone var declarations before other statements in the same function, script, module, or static block." // Doesn't explain why, only tells the action. The "why" must come second, after the what. 3. "At module scope, imports and leading "<Emphasis>"export var"</Emphasis>" declarations may appear before other statements." // Doesn't explain the action, just gives a superfluous detail about module scope.

## Tips

- New rules are always in the `nursery` group. No need to move them to another category.
- Changesets are always required for new rules. New rules are `patch` level changes. There's a skill to help write good changesets.

## References

- Full guide: `crates/biome_analyze/CONTRIBUTING.md`
- Rule examples: `crates/biome_js_analyze/src/lint/`
- Semantic model: Search for `Semantic<` in existing rules
- Testing guide: Main `CONTRIBUTING.md` testing section

Rule Options — Detailed Reference

This file contains detailed patterns, design guidelines, and examples for implementing configurable options on lint rules. For the quick-start workflow, see the main SKILL.md "Adding Configurable Options" section.

Define Rule Options Type

Options live in biome_rule_options crate. After running just gen-rules, a file is created for your rule.

Example for useThisConvention rule in biome_rule_options/src/use_this_convention.rs:

use biome_deserialize_macros::{Deserializable, Merge};
use serde::{Deserialize, Serialize};

#[derive(Debug, Default, Clone, Serialize, Deserialize, Deserializable)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields, default)]
pub struct UseThisConventionOptions {
    /// What behavior to enforce
    #[serde(skip_serializing_if = "Option::is_none")]
    behavior: Option<Behavior>,

    /// Threshold value between 0-255
    #[serde(skip_serializing_if = "Option::is_none")]
    threshold: Option<u8>,

    /// Exceptions to the behavior
    #[serde(skip_serializing_if = "Option::is_none")]
    behavior_exceptions: Option<Box<[Box<str>]>>,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize, Deserializable, Merge)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub enum Behavior {
    #[default]
    A,
    B,
    C,
}

Key points:

• All fields wrapped in Option<_> for proper merging
• Use Box<[Box<str>]> instead of Vec<String> (saves memory)
• #[serde(rename_all = "camelCase")] for JavaScript naming
• #[serde(deny_unknown_fields)] to catch typos
• #[serde(default)] makes all fields optional

Implement Merge Trait

Options from shared config + user config need merging:

impl biome_deserialize::Merge for UseThisConventionOptions {
    fn merge_with(&mut self, other: Self) {
        // `self` = shared config
        // `other` = user config

        // For simple values, use helper
        self.behavior.merge_with(other.behavior);
        self.threshold.merge_with(other.threshold);

        // For collections, typically reset instead of combine
        if let Some(exceptions) = other.behavior_exceptions {
            self.behavior_exceptions = Some(exceptions);
        }
    }
}

Merge strategies:

• Simple values (enums, numbers): Use merge_with() (takes user value if present)
• Collections: Usually reset to user value, not combine
• Derive macro: Can use #[derive(Merge)] for simple cases

Option Design Guidelines

When to Add Options

Good reasons:

• Conflicting style preferences in community
• Rule has multiple valid interpretations
• Different behavior needed for different environments

Bad reasons:

• Making rule "more flexible" without clear use case
• Avoiding making opinionated decision
• Working around incomplete implementation

Option Naming

// Good - clear, semantic names
allow_single_line: bool
max_depth: u8
ignore_patterns: Box<[Box<str>]>

// Bad - unclear, technical names
flag: bool
n: u8
list: Vec<String>

Option Types

// Simple values
enabled: bool
max_count: u8  // or u16, u32
min_length: usize

// Enums for fixed choices
#[derive(Deserializable, Merge)]
enum QuoteStyle {
    Single,
    Double,
    Preserve,
}

// Collections (use boxed slices)
patterns: Box<[Box<str>]>
ignore_names: Box<[Box<str>]>

// Complex nested options
#[derive(Deserializable)]
struct AdvancedOptions {
    mode: Mode,
    exclusions: Box<[Box<str>]>,
}

Common Patterns

// Pattern 1: Boolean option with default false
#[derive(Default)]
struct MyOptions {
    allow_something: Option<bool>,
}

impl Rule for MyRule {
    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
        let allow = ctx.options().allow_something.unwrap_or(false);
        if allow { return None; }
        // ...
    }
}

// Pattern 2: Enum option with default
#[derive(Default)]
enum Mode {
    #[default]
    Strict,
    Loose,
}

// Pattern 3: Collection option (exclusions)
fn run(ctx: &RuleContext<Self>) -> Self::Signals {
    let options = ctx.options();

    if let Some(exclusions) = &options.exclusions {
        if exclusions.iter().any(|ex| matches_name(ex, name)) {
            return None;  // Excluded
        }
    }

    // Check rule normally
}

// Pattern 4: Numeric threshold
fn run(ctx: &RuleContext<Self>) -> Self::Signals {
    let threshold = ctx.options().max_depth.unwrap_or(3);

    if depth > threshold {
        return Some(());
    }

    None
}

Document Options in Rule

Add options documentation to rule's rustdoc:

declare_lint_rule! {
    /// Enforces a specific convention for code organization.
    ///
    /// ## Options
    ///
    /// ### `behavior`
    ///
    /// Specifies which behavior to enforce. Accepted values are:
    /// - `"A"` (default): Enforces behavior A
    /// - `"B"`: Enforces behavior B
    /// - `"C"`: Enforces behavior C
    ///
    /// ### `threshold`
    ///
    /// A number between 0-255 (default: 50). Controls sensitivity of detection.
    ///
    /// ### `behaviorExceptions`
    ///
    /// An array of strings. Names listed here are excluded from the rule.
    ///
    /// ## Examples
    ///
    /// ### With default options
    ///
    /// [examples with default behavior]
    ///
    /// ### With `behavior` set to "B"
    ///
    /// ```json
    /// {
    ///   "useThisConvention": {
    ///     "level": "error",
    ///     "options": {
    ///       "behavior": "B"
    ///     }
    ///   }
    /// }
    /// ```
    ///
    /// [examples with behavior B]
    pub UseThisConvention {
        version: "next",
        name: "useThisConvention",
        language: "js",
        recommended: false,
    }
}

Configuration Merging Example

// shared.jsonc (extended configuration)
{
  "linter": {
    "rules": {
      "nursery": {
        "myRule": {
          "options": {
            "behavior": "A",
            "exclusions": ["foo"]
          }
        }
      }
    }
  }
}

// biome.jsonc (user configuration)
{
  "extends": ["./shared.jsonc"],
  "linter": {
    "rules": {
      "nursery": {
        "myRule": {
          "options": {
            "threshold": 30,
            "exclusions": ["bar"]  // Replaces ["foo"], doesn't append
          }
        }
      }
    }
  }
}

// Result after merging:
// behavior: "A" (from shared)
// threshold: 30 (from user)
// exclusions: ["bar"] (user replaces shared)

Test with Options

Create options.json in test directory:

tests/specs/nursery/useThisConvention/
├── invalid.js
├── valid.js
├── with_behavior_a/
│   ├── options.json
│   ├── invalid.js
│   └── valid.js
└── with_exceptions/
    ├── options.json
    └── valid.js

Example with_behavior_a/options.json:

{
  "linter": {
    "rules": {
      "nursery": {
        "useThisConvention": {
          "level": "error",
          "options": {
            "behavior": "A",
            "threshold": 10
          }
        }
      }
    }
  }
}

Options apply to all test files in that directory.

Tips

• Minimize options: Only add when truly needed
• Memory efficiency: Use Box<[Box<str>]> not Vec<String> for arrays
• Optional wrapping: All option fields should be Option<T> for proper merging
• Serde attributes: Always use rename_all = "camelCase" and deny_unknown_fields
• Schema generation: Use #[cfg_attr(feature = "schema", derive(JsonSchema))]
• Default trait: Implement or derive Default for option types
• Testing: Test with multiple option combinations
• Documentation: Document each option with examples in the rule's rustdoc
• Codegen: Run just gen-rules && just gen-configuration after adding options

References

• Analyzer guide: crates/biome_analyze/CONTRIBUTING.md § Rule Options
• Options crate: crates/biome_rule_options/
• Deserialize macros: crates/biome_deserialize_macros/
• Example rules with options: Search for type Options = in biome_*_analyze crates