feat: custom explanations with --suppress

crates/biome_analyze/src/lib.rs

@@ -786,6 +786,8 @@ pub struct SuppressionCommentEmitterPayload<'a, L: Language> {
     pub suppression_text: &'a str,
     /// The original range of the diagnostic where the rule was triggered
     pub diagnostic_text_range: &'a TextRange,
+    /// Explanation for the suppression to be used with `--suppress` and `--reason`
+    pub suppression_reason: String,
 }
 
 type SignalHandler<'a, L, Break> = &'a mut dyn FnMut(&dyn AnalyzerSignal<L>) -> ControlFlow<Break>;

crates/biome_analyze/src/matcher.rs

@@ -380,6 +380,7 @@ mod tests {
                 _: &mut BatchMutation<Self::Language>,
                 _: ApplySuppression<Self::Language>,
                 _: &str,
+                _: String,
             ) {
                 unreachable!("")
             }

crates/biome_analyze/src/options.rs

@@ -77,6 +77,9 @@ pub struct AnalyzerOptions {
 
     /// The file that is being analyzed
     pub file_path: PathBuf,
+
+    /// Suppression reason to be used with `--suppress` and `--reason`
+    pub suppression_reason: Option<String>,
 }
 
 impl AnalyzerOptions {

crates/biome_analyze/src/registry.rs

@@ -428,6 +428,7 @@ impl<L: Language + Default> RegistryRule<L> {
                     result,
                     params.services,
                     params.suppression_action,
+                    params.options.suppression_reason.clone(),
                     params.options,
                 ));
 

crates/biome_analyze/src/rule.rs

@@ -881,6 +881,7 @@ pub trait Rule: RuleMeta + Sized {
         ctx: &RuleContext<Self>,
         text_range: &TextRange,
         suppression_action: &dyn SuppressionAction<Language = RuleLanguage<Self>>,
+        suppression_reason: Option<String>,
     ) -> Option<SuppressAction<RuleLanguage<Self>>>
     where
         Self: 'static,
@@ -901,6 +902,7 @@ pub trait Rule: RuleMeta + Sized {
                 mutation: &mut mutation,
                 token_offset: token,
                 diagnostic_text_range: text_range,
+                suppression_reason: suppression_reason.unwrap_or("<explanation>".to_string()),
             });
 
             Some(SuppressAction {

crates/biome_analyze/src/signals.rs

@@ -310,6 +310,8 @@ pub(crate) struct RuleSignal<'phase, R: Rule> {
     services: &'phase ServiceBag,
     /// An optional action to suppress the rule.
     suppression_action: &'phase dyn SuppressionAction<Language = RuleLanguage<R>>,
+    /// An optional explanation for the suppression to be used with `--suppress` and `--reason`
+    suppression_reason: Option<String>,
     /// A list of strings that are considered "globals" inside the analyzer
     options: &'phase AnalyzerOptions,
 }
@@ -326,7 +328,7 @@ where
         suppression_action: &'phase dyn SuppressionAction<
             Language = <<R as Rule>::Query as Queryable>::Language,
         >,
-
+        suppression_reason: Option<String>,
         options: &'phase AnalyzerOptions,
     ) -> Self {
         Self {
@@ -335,6 +337,7 @@ where
             state,
             services,
             suppression_action,
+            suppression_reason,
             options,
         }
     }
@@ -402,9 +405,12 @@ where
                 });
             };
             if let Some(text_range) = R::text_range(&ctx, &self.state) {
-                if let Some(suppression_action) =
-                    R::suppress(&ctx, &text_range, self.suppression_action)
-                {
+                if let Some(suppression_action) = R::suppress(
+                    &ctx,
+                    &text_range,
+                    self.suppression_action,
+                    self.suppression_reason.clone(),
+                ) {
                     let action = AnalyzerAction {
                         rule_name: Some((<R::Group as RuleGroup>::NAME, R::METADATA.name)),
                         category: ActionCategory::Other(Cow::Borrowed(SUPPRESSION_ACTION_CATEGORY)),

crates/biome_analyze/src/suppression_action.rs

@@ -10,6 +10,7 @@ pub trait SuppressionAction {
             mutation,
             suppression_text,
             diagnostic_text_range,
+            suppression_reason,
         } = payload;
 
         // retrieve the most suited, most left token where the diagnostics was emitted
@@ -22,7 +23,12 @@ pub trait SuppressionAction {
         });
 
         if let Some(apply_suppression) = apply_suppression {
-            self.apply_suppression(mutation, apply_suppression, suppression_text);
+            self.apply_suppression(
+                mutation,
+                apply_suppression,
+                suppression_text,
+                suppression_reason,
+            );
         }
     }
 
@@ -72,6 +78,7 @@ pub trait SuppressionAction {
         mutation: &mut BatchMutation<Self::Language>,
         apply_suppression: ApplySuppression<Self::Language>,
         suppression_text: &str,
+        suppression_reason: String,
     );
 }
 

crates/biome_analyze/src/syntax.rs

@@ -166,6 +166,7 @@ mod tests {
                 _: &mut BatchMutation<Self::Language>,
                 _: ApplySuppression<Self::Language>,
                 _: &str,
+                _: String,
             ) {
                 unreachable!("")
             }

crates/biome_cli/src/commands/check.rs

@@ -142,6 +142,7 @@ impl CommandRunner for CheckCommandPayload {
                 apply_unsafe: self.apply_unsafe,
                 write: self.write,
                 suppress: false,
+                suppression_reason: None,
                 fix: self.fix,
                 unsafe_: self.unsafe_,
             },

crates/biome_cli/src/commands/lint.rs

@@ -25,6 +25,7 @@ pub(crate) struct LintCommandPayload {
     pub(crate) fix: bool,
     pub(crate) unsafe_: bool,
     pub(crate) suppress: bool,
+    pub(crate) suppression_reason: Option<String>,
     pub(crate) linter_configuration: Option<PartialLinterConfiguration>,
     pub(crate) vcs_configuration: Option<PartialVcsConfiguration>,
     pub(crate) files_configuration: Option<PartialFilesConfiguration>,
@@ -138,6 +139,7 @@ impl CommandRunner for LintCommandPayload {
                 fix: self.fix,
                 unsafe_: self.unsafe_,
                 suppress: self.suppress,
+                suppression_reason: self.suppression_reason.clone(),
             },
             console,
         )?;
@@ -148,6 +150,7 @@ impl CommandRunner for LintCommandPayload {
             skip: self.skip.clone(),
             vcs_targeted: (self.staged, self.changed).into(),
             suppress: self.suppress,
+            suppression_reason: self.suppression_reason.clone(),
         })
         .set_report(cli_options))
     }

crates/biome_cli/src/commands/migrate.rs

@@ -85,6 +85,7 @@ impl CommandRunner for MigrateCommandPayload {
             fix: self.fix,
             unsafe_: false,
             suppress: false,
+            suppression_reason: None,
         })
     }
 

crates/biome_cli/src/commands/mod.rs

@@ -1,6 +1,8 @@
 use crate::changed::{get_changed_files, get_staged_files};
 use crate::cli_options::{cli_options, CliOptions, CliReporter, ColorsArg};
-use crate::diagnostics::{DeprecatedArgument, DeprecatedConfigurationFile};
+use crate::diagnostics::{
+    DeprecatedArgument, DeprecatedConfigurationFile, IncompatibleEndConfiguration,
+};
 use crate::execute::Stdin;
 use crate::logging::LoggingKind;
 use crate::{
@@ -187,10 +189,6 @@ pub enum BiomeCommand {
         #[bpaf(long("write"), switch)]
         write: bool,
 
-        /// Fix diagnostics with suppression comments if the language supports it.
-        #[bpaf(long("suppress"))]
-        suppress: bool,
-
         /// Allow to do unsafe fixes, should be used with `--write` or `--fix`
         #[bpaf(long("unsafe"), switch)]
         unsafe_: bool,
@@ -207,6 +205,14 @@ pub enum BiomeCommand {
         #[bpaf(long("apply-unsafe"), switch, hide_usage)]
         apply_unsafe: bool,
 
+        /// Bulk fix diagnostics with suppression comments if the language supports it.
+        #[bpaf(long("suppress"))]
+        suppress: bool,
+
+        /// Explanation for suppressing diagnostics with `--suppress`
+        #[bpaf(long("reason"), argument("STRING"))]
+        suppression_reason: Option<String>,
+
         #[bpaf(external(partial_linter_configuration), hide_usage, optional)]
         linter_configuration: Option<PartialLinterConfiguration>,
 
@@ -708,6 +714,7 @@ pub(crate) struct FixFileModeOptions {
     apply_unsafe: bool,
     write: bool,
     suppress: bool,
+    suppression_reason: Option<String>,
     fix: bool,
     unsafe_: bool,
 }
@@ -725,6 +732,7 @@ pub(crate) fn determine_fix_file_mode(
         write,
         fix,
         suppress,
+        suppression_reason: _,
         unsafe_,
     } = options;
 
@@ -763,6 +771,7 @@ fn check_fix_incompatible_arguments(options: FixFileModeOptions) -> Result<(), C
         apply_unsafe,
         write,
         suppress,
+        suppression_reason,
         fix,
         unsafe_,
     } = options;
@@ -795,7 +804,13 @@ fn check_fix_incompatible_arguments(options: FixFileModeOptions) -> Result<(), C
         ));
     } else if suppress && fix {
         return Err(CliDiagnostic::incompatible_arguments("--suppress", "--fix"));
-    }
+    } else if !suppress && suppression_reason.is_some() {
+        return Err(CliDiagnostic::IncompatibleEndConfiguration(
+            IncompatibleEndConfiguration {
+                reason: "`--reason` is only valid when `--suppress` is used.".to_string(),
+            },
+        ));
+    };
     Ok(())
 }
 
@@ -983,20 +998,21 @@ mod tests {
 
     #[test]
     fn incompatible_arguments() {
-        for (apply, apply_unsafe, write, suppress, fix, unsafe_) in [
-            (true, true, false, false, false, false), // --apply --apply-unsafe
-            (true, false, true, false, false, false), // --apply --write
-            (true, false, false, false, true, false), // --apply --fix
-            (false, true, false, false, false, true), // --apply-unsafe --unsafe
-            (false, true, true, false, false, false), // --apply-unsafe --write
-            (false, true, false, false, true, false), // --apply-unsafe --fix
-            (false, false, true, false, true, false), // --write --fix
+        for (apply, apply_unsafe, write, suppress, suppression_reason, fix, unsafe_) in [
+            (true, true, false, false, None, false, false), // --apply --apply-unsafe
+            (true, false, true, false, None, false, false), // --apply --write
+            (true, false, false, false, None, true, false), // --apply --fix
+            (false, true, false, false, None, false, true), // --apply-unsafe --unsafe
+            (false, true, true, false, None, false, false), // --apply-unsafe --write
+            (false, true, false, false, None, true, false), // --apply-unsafe --fix
+            (false, false, true, false, None, true, false), // --write --fix
         ] {
             assert!(check_fix_incompatible_arguments(FixFileModeOptions {
                 apply,
                 apply_unsafe,
                 write,
                 suppress,
+                suppression_reason,
                 fix,
                 unsafe_
             })
@@ -1008,10 +1024,10 @@ mod tests {
     fn safe_fixes() {
         let mut console = BufferConsole::default();
 
-        for (apply, apply_unsafe, write, suppress, fix, unsafe_) in [
-            (true, false, false, false, false, false), // --apply
-            (false, false, true, false, false, false), // --write
-            (false, false, false, false, true, false), // --fix
+        for (apply, apply_unsafe, write, suppress, suppression_reason, fix, unsafe_) in [
+            (true, false, false, false, None, false, false), // --apply
+            (false, false, true, false, None, false, false), // --write
+            (false, false, false, false, None, true, false), // --fix
         ] {
             assert_eq!(
                 determine_fix_file_mode(
@@ -1020,6 +1036,7 @@ mod tests {
                         apply_unsafe,
                         write,
                         suppress,
+                        suppression_reason,
                         fix,
                         unsafe_
                     },
@@ -1035,10 +1052,10 @@ mod tests {
     fn safe_and_unsafe_fixes() {
         let mut console = BufferConsole::default();
 
-        for (apply, apply_unsafe, write, suppress, fix, unsafe_) in [
-            (false, true, false, false, false, false), // --apply-unsafe
-            (false, false, true, false, false, true),  // --write --unsafe
-            (false, false, false, false, true, true),  // --fix --unsafe
+        for (apply, apply_unsafe, write, suppress, suppression_reason, fix, unsafe_) in [
+            (false, true, false, false, None, false, false), // --apply-unsafe
+            (false, false, true, false, None, false, true),  // --write --unsafe
+            (false, false, false, false, None, true, true),  // --fix --unsafe
         ] {
             assert_eq!(
                 determine_fix_file_mode(
@@ -1047,6 +1064,7 @@ mod tests {
                         apply_unsafe,
                         write,
                         suppress,
+                        suppression_reason,
                         fix,
                         unsafe_
                     },
@@ -1062,15 +1080,16 @@ mod tests {
     fn no_fix() {
         let mut console = BufferConsole::default();
 
-        let (apply, apply_unsafe, write, suppress, fix, unsafe_) =
-            (false, false, false, false, false, false);
+        let (apply, apply_unsafe, write, suppress, suppression_reason, fix, unsafe_) =
+            (false, false, false, false, None, false, false);
         assert_eq!(
             determine_fix_file_mode(
                 FixFileModeOptions {
                     apply,
                     apply_unsafe,
                     write,
                     suppress,
+                    suppression_reason,
                     fix,
                     unsafe_
                 },

crates/biome_cli/src/diagnostics.rs

@@ -223,7 +223,7 @@ pub struct ServerNotRunning;
     )
 )]
 pub struct IncompatibleEndConfiguration {
-    reason: String,
+    pub reason: String,
 }
 
 #[derive(Debug, Diagnostic)]

crates/biome_cli/src/execute/mod.rs

@@ -159,6 +159,8 @@ pub enum TraversalMode {
         vcs_targeted: VcsTargeted,
         /// Supress existing diagnostics with a `// biome-ignore` comment
         suppress: bool,
+        /// Explanation for suppressing diagnostics with `--suppress` and `--reason`
+        suppression_reason: Option<String>,
     },
     /// This mode is enabled when running the command `biome ci`
     CI {

crates/biome_cli/src/execute/process_file.rs

@@ -209,9 +209,13 @@ pub(crate) fn process_file(ctx: &TraversalOptions, biome_path: &BiomePath) -> Fi
         let shared_context = &SharedTraversalOptions::new(ctx);
 
         match ctx.execution.traversal_mode {
-            TraversalMode::Lint { .. } => {
+            TraversalMode::Lint {
+                ref suppression_reason,
+                suppress,
+                ..
+            } => {
                 // the unsupported case should be handled already at this point
-                lint(shared_context, biome_path)
+                lint(shared_context, biome_path, suppress, suppression_reason)
             }
             TraversalMode::Format { .. } => {
                 // the unsupported case should be handled already at this point

crates/biome_cli/src/execute/process_file/assists.rs

@@ -28,6 +28,7 @@ pub(crate) fn assists_with_guard<'ctx>(
                     RuleCategoriesBuilder::default().with_action().build(),
                     only.clone(),
                     skip.clone(),
+                    None,
                 )
                 .with_file_path_and_code(
                     workspace_file.path.display().to_string(),

crates/biome_cli/src/execute/process_file/check.rs

@@ -18,7 +18,7 @@ pub(crate) fn check_file<'ctx>(
     tracing::info_span!("Process check", path =? workspace_file.path.display()).in_scope(
         move || {
             if file_features.supports_lint() {
-                let lint_result = lint_with_guard(ctx, &mut workspace_file);
+                let lint_result = lint_with_guard(ctx, &mut workspace_file, false, None);
                 match lint_result {
                     Ok(status) => {
                         if status.is_changed() {