Implement suppression of plugin diagnostics #4667

[wanghaoPolar]

This doc discuss changes related to Implement suppression of plugin diagnostics #4667

syntax

current implementation use // biome-ignore lint/plugin/myCustomPlugin: <reason>.

Implementation

See More

I'm new to biome and open source, please forgive any naive from my side. 🙇‍♂️

Below I list how suppression comment works in biome and possible changes need to make for #4667

Step 1: Parse suppression comment to {[{ category, value }], reason}

The parser for comments is at `/crates/biome_suppression/src/lib.rs``

fn parse_suppression_comment
fn parse_suppression_line

For each comment line that starts with 'biome-ignore', parse by syntax { <category> { (<value>) }? }+: <reason> and return { [ { category, value } ], reason}

For example, with comment // biome-ignore lint/a11y/noAccessKey(v) some reason for ignoring
Return {[{category="lint/a11y/noAccessKey", value="v"}], reason="some reason for ignoring"}

All categories are prebuild and defined in crates/biome_diagnostics_categories/src/categories.rs. if not included, will cause parse fail.

Task 1:

The initial proposed format to suppress plugin diagnostics is // biome-ignore plugin/<plugin-name> <reason>
category part is plugin/<plugin-name>, it's dynamic, we don't know the plugin-name at build time.

To handle this, we need to add ad-hoc logic to category parsing if category starts with plugin/ to get dynamic subcategory value.

#[derive(Debug, PartialEq, Eq)]
pub struct Suppression<'a> {
    // ...
-   pub categories: Vec<(&'a Category, Option<&'a str>)>, // Vec<(category, value)>
+   pub categories: Vec<(&'a Category, Option<&'a str>, Option<&'a str>)>, // Vec<(category, subcategory, value)>
}

Step 2: Generate AnalyzerSuppression from (category, subcategory, value)

after getting (category, subcategory, value), generate corresponding AnalyzerSuppression, defined at crates/biome_analyze/src/lib.rs

pub struct AnalyzerSuppression<'a> {
    /// The kind of suppression
    pub(crate) kind: AnalyzerSuppressionKind<'a>,

    /// The range where the `biome-ignore` comment is placed inside the whole text
    pub(crate) ignore_range: Option<TextRange>,

    /// The kind of `biome-ignore` comment used for this suppression
    pub(crate) variant: AnalyzerSuppressionVariant,
}

pub enum AnalyzerSuppressionKind<'a> {
    /// A suppression disabling all lints eg. `// biome-ignore lint`
    Everything,
    /// A suppression disabling a specific rule eg. `// biome-ignore lint/complexity/useWhile`
    Rule(&'a str),
    /// A suppression to be evaluated by a specific rule eg. `// biome-ignore lint/correctness/useExhaustiveDependencies(foo)`
    RuleInstance(&'a str, &'a str),
+    /// A suppression disabling a plugin eg. `// biome-ignore plugin/my-plugin`
+    Plugin(Option<&'a str>),
}

Task 2

Implement above changes

Step 3: Ignore signal by AnalyzerSuppression

in crates/biome_analyze/src/lib.rs, at handle_comment method, it parse comment to AnalyzerSuppression and store them as TopLevelSuppression, LineSuppression and RangeSuppression.

struct LineSuppression {
    /// Line index this comment is suppressing lint rules for
    line_index: usize,
    /// Range of source text covered by the suppression comment
    comment_span: TextRange,
    /// Range of source text this comment is suppressing lint rules for
    text_range: TextRange,
    /// Set to true if this comment has set the `suppress_all` flag to true
    /// (must be restored to false on expiration)
    suppress_all: bool,
    /// List of all the rules this comment has started suppressing (must be
    /// removed from the suppressed set on expiration)
    suppressed_rules: Vec<RuleFilter<'static>>,
    /// List of all the rule instances this comment has started suppressing.
    suppressed_instances: Vec<(RuleFilter<'static>, String)>,
    /// Set to `true` when a signal matching this suppression was emitted and
    /// suppressed
    did_suppress_signal: bool,
}

then at flush_matches method, when handling each signal, it try to find a suppression that match the signal by line_index, text_range and suppress filters, if match, the signal is suppressed.

Task 3

Plugins are run after exiting lint runners are finished, we need to match and suppress diagnosis.

1. During the lint runners execution, all suppressions a collected.
2. After lint runners, during plugin evaluation, every time there is a diagnosis, we can check to see if it is suppressed. (see crates/biome_analyze/src/lib.rs Analyzer::run )

[arendjr]

Thanks for the clear write-up!

Task 1

You make a good observation that we'll need a dynamic subcategory. So the static category can remain plugin, which I think already exists. But instead of changing the syntax as you suggest in your choices, I'd try to see if you can "special-case" the plugin case: Just look whether the category starts with "plugin/", and if so, set the category to plugin, and the subcategory to whatever comes after. This way, we don't need a special syntax and can still handle a dynamic subcategory for this use case.

The reason why I'd suggest doing it this way is because I would try to avoid leaking the implementation details of static vs. dynamic categories to the user. If we introduce a special syntax for this, it just adds confusion: Why another syntax? Why can't it work like other categories? We'd have no way to explain the rationale without explaining the implementation.

Task 2

I don't think we'll need PluginInstance just yet, so let's keep it out until there is a need for it. Otherwise your suggestion sounds good 👍

Task 3

Sounds good to me! 🚀

PS.: Maybe @ematipico also has some insights here that I might've missed.

[ematipico]

All categories are prebuild and defined in crates/biome_diagnostics_categories/src/categories.rs. if not included, will cause parse fail.

That's not technically correct. That file contains is there only to create a macro called category! that fails at runtime. So, internally, we have auto completion and the macro fails if we pass a category we don't expect .

Under the hoods, categories can be whatever we want.

Regarding task 3, there's no need for a new suppression kind I think, because plugins aren't going to introduce a new variant of biome-ignore-*, so they will behave as current suppressions.

[wanghaoPolar]

Thanks for helping review! I will fix the errors and finalize details in this doc soon and start the implementation 🤝

[wanghaoPolar]

Sorry for the long delay. I have finished a basic implementation for suppress plugin.
I'll update asap when ready for review.