feat: implement noEmptyDocumentation

Author: Netail

.changeset/wise-hoops-dream.md

@@ -0,0 +1,32 @@
+---
+"@biomejs/biome": patch
+---
+
+Added the new nursery rule [`noEmptyDocumentation`](https://biomejs.dev/linter/rules/no-empty-documentation), which disallows empty documentation (comments & descriptions) in HTML, CSS, JavaScript, JSON & GraphQL.
+
+```html
+<!-- -->
+<input/>
+```
+
+```css
+/* */
+.invalid {}
+```
+
+```js
+/* */
+let invalid = 1;
+```
+
+```jsonc
+{
+  /* */
+  "name": "John Doe"
+}
+```
+
+```graphql
+" "
+query {}
+```

crates/biome_configuration/src/analyzer/linter/rules.rs

@@ -0,0 +1,145 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_css_syntax::{AnyCssRoot, CssLanguage};
+use biome_rowan::{AstNode, SyntaxNode, SyntaxTriviaPiece, TextRange};
+use biome_rule_options::no_empty_documentation::NoEmptyDocumentationOptions;
+
+declare_lint_rule! {
+    /// Disallow empty documentation.
+    ///
+    /// Enforces that comments are not empty. This helps maintain code quality by preventing meaningless
+    /// or placeholder comments that don't provide any documentation value.
+    ///
+    /// Empty comments clutter the codebase and should be removed. This rule catches comments (`/* */`) that contain no meaningful content.
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```css,expect_diagnostic
+    /// /* */
+    /// p {}
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```css
+    /// /* Valid */
+    /// p {}
+    /// ```
+    ///
+    pub NoEmptyDocumentation {
+        version: "next",
+        name: "noEmptyDocumentation",
+        language: "css",
+        recommended: false,
+        sources: &[RuleSource::Stylelint("comment-no-empty").same()],
+    }
+}
+
+impl Rule for NoEmptyDocumentation {
+    type Query = Ast<AnyCssRoot>;
+    type State = Vec<TextRange>;
+    type Signals = Option<Self::State>;
+    type Options = NoEmptyDocumentationOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
+        let node = ctx.query();
+        let syntax_node = node.syntax();
+
+        let mut found = Vec::new();
+        found.append(&mut empty_comments(syntax_node));
+
+        for descendant in syntax_node.descendants() {
+            found.append(&mut empty_comments(&descendant));
+        }
+
+        found.sort_unstable_by_key(|range| (range.start(), range.end()));
+        found.dedup();
+
+        if found.is_empty() {
+            return None;
+        }
+
+        Some(found)
+    }
+
+    fn diagnostic(_ctx: &RuleContext<Self>, state: &Self::State) -> Option<RuleDiagnostic> {
+        let mut diagnostic = RuleDiagnostic::new(
+            rule_category!(),
+            state.first()?,
+            markup! {
+                "Unexpected empty documentation."
+            },
+        );
+
+        for range in &state[1..] {
+            diagnostic = diagnostic.detail(
+                range,
+                markup! {
+                    "More empty documentation."
+                },
+            );
+        }
+
+        Some(diagnostic.note(markup! {
+            "Empty documentation provides no value. Remove them or add meaningful content."
+        }))
+    }
+}
+
+fn leading_comments(syntax_node: &SyntaxNode<CssLanguage>) -> Vec<SyntaxTriviaPiece<CssLanguage>> {
+    if let Some(token) = syntax_node.first_token() {
+        token
+            .leading_trivia()
+            .pieces()
+            .filter(|piece| piece.is_comments())
+            .collect()
+    } else {
+        Vec::new()
+    }
+}
+
+fn trailing_comments(syntax_node: &SyntaxNode<CssLanguage>) -> Vec<SyntaxTriviaPiece<CssLanguage>> {
+    if let Some(token) = syntax_node.last_token() {
+        token
+            .leading_trivia()
+            .pieces()
+            .filter(|piece| piece.is_comments())
+            .collect()
+    } else {
+        Vec::new()
+    }
+}
+
+fn is_empty_comment(trivia_piece: &SyntaxTriviaPiece<CssLanguage>) -> bool {
+    let text = trivia_piece.text().trim();
+
+    // Remove comment prefixes and check if anything remains
+    let content = if let Some(stripped) = text.strip_prefix("/*") {
+        if let Some(stripped) = stripped.strip_suffix("*/") {
+            stripped.trim()
+        } else {
+            stripped.trim()
+        }
+    } else {
+        text
+    };
+
+    content.is_empty()
+}
+
+fn empty_comments(syntax_node: &SyntaxNode<CssLanguage>) -> Vec<TextRange> {
+    let mut comments = Vec::new();
+
+    comments.append(&mut leading_comments(syntax_node));
+    comments.append(&mut trailing_comments(syntax_node));
+
+    comments
+        .iter()
+        .filter(|comment| is_empty_comment(comment))
+        .map(|comment| comment.text_range())
+        .collect()
+}

crates/biome_configuration/src/generated/linter_options_check.rs

@@ -0,0 +1,6 @@
+/* should generate diagnostics */
+
+/* */
+.invalid {
+	display: flex;
+}

crates/biome_css_analyze/src/lint/nursery/no_empty_documentation.rs

@@ -0,0 +1,34 @@
+---
+source: crates/biome_css_analyze/tests/spec_tests.rs
+expression: invalid.css
+---
+# Input
+```css
+/* should generate diagnostics */
+
+/* */
+.invalid {
+	display: flex;
+}
+
+```
+
+# Diagnostics
+```
+invalid.css:3:1 lint/nursery/noEmptyDocumentation ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected empty documentation.
+  
+    1 │ /* should generate diagnostics */
+    2 │ 
+  > 3 │ /* */
+      │ ^^^^^
+    4 │ .invalid {
+    5 │ 	display: flex;
+  
+  i Empty documentation provides no value. Remove them or add meaningful content.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```

crates/biome_css_analyze/tests/specs/nursery/noEmptyDocumentation/invalid.css

@@ -0,0 +1,6 @@
+/* should not generate diagnostics */
+
+/* Valid */
+.valid {
+	display: flex;
+}

crates/biome_css_analyze/tests/specs/nursery/noEmptyDocumentation/invalid.css.snap

@@ -0,0 +1,14 @@
+---
+source: crates/biome_css_analyze/tests/spec_tests.rs
+expression: valid.css
+---
+# Input
+```css
+/* should not generate diagnostics */
+
+/* Valid */
+.valid {
+	display: flex;
+}
+
+```