feat: useNamedLayer (#11377)

Author: Netail

.changeset/calm-bottles-jog.md

@@ -0,0 +1,13 @@
+---
+"@biomejs/biome": patch
+---
+
+Added a new nursery rule [`useNamedLayer`](https://biomejs.dev/linter/rules/use-named-layer) which disallows anonymous cascade layers.
+
+```css
+@layer {
+  a {
+    color: red;
+  }
+}
+```

crates/biome_cli/src/execute/migrate/eslint_any_rule_to_biome.rs

@@ -0,0 +1,107 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_css_syntax::{CssImportAnonymousLayer, CssLayerAtRule};
+use biome_diagnostics::Severity;
+use biome_rowan::{AstNode, AstSeparatedList, declare_node_union};
+use biome_rule_options::use_named_layer::UseNamedLayerOptions;
+
+declare_lint_rule! {
+    /// Disallow anonymous cascade layers.
+    ///
+    /// A cascade layer created with `@layer { ... }` or imported with
+    /// `@import "..." layer` has no name. Anonymous layers get their own place
+    /// in the cascade order, but because they cannot be referred to by name,
+    /// no later rule can add styles to them or reorder them. This makes the
+    /// cascade harder to reason about and prevents reusing the layer.
+    ///
+    /// Give every layer a name so it can be referenced, appended to, and
+    /// ordered explicitly through a `@layer` statement.
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```css,expect_diagnostic
+    /// @layer {
+    ///   a {
+    ///     color: red;
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ```css,expect_diagnostic
+    /// @import "theme.css" layer;
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```css
+    /// @layer base {
+    ///   a {
+    ///     color: red;
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ```css
+    /// @import "theme.css" layer(base);
+    /// ```
+    ///
+    pub UseNamedLayer {
+        version: "next",
+        name: "useNamedLayer",
+        language: "css",
+        recommended: false,
+        severity: Severity::Warning,
+        sources: &[RuleSource::EslintCss("use-layers").inspired()],
+    }
+}
+
+impl Rule for UseNamedLayer {
+    type Query = Ast<AnyUseNamedLayerQuery>;
+    type State = ();
+    type Signals = Option<Self::State>;
+    type Options = UseNamedLayerOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
+        let node = ctx.query();
+
+        match node {
+            AnyUseNamedLayerQuery::CssImportAnonymousLayer(_) => return Some(()),
+            AnyUseNamedLayerQuery::CssLayerAtRule(at_rule) => {
+                let layer = at_rule.layer().ok()?;
+                let dec = layer.as_css_layer_declaration()?;
+                if dec.references().is_empty() {
+                    return Some(());
+                }
+            }
+        }
+
+        None
+    }
+
+    fn diagnostic(ctx: &RuleContext<Self>, _state: &Self::State) -> Option<RuleDiagnostic> {
+        let node = ctx.query();
+        Some(
+            RuleDiagnostic::new(
+                rule_category!(),
+                node.range(),
+                markup! {
+                    "Missing cascade layer name."
+                },
+            )
+            .note(markup! {
+                "An anonymous layer cannot be referenced, so later rules cannot append to it or reorder it."
+            })
+            .note(markup! {
+                "Give the layer a name, for example "<Emphasis>"@layer base { ... }"</Emphasis>"."
+            }),
+        )
+    }
+}
+
+declare_node_union! {
+    pub AnyUseNamedLayerQuery = CssLayerAtRule | CssImportAnonymousLayer
+}

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

@@ -0,0 +1,8 @@
+/* should generate diagnostics */
+@import url(foo.css) layer;
+
+@layer {
+	.test {
+		color: red;
+	}
+}

crates/biome_configuration/src/generated/linter_options_check.rs

@@ -0,0 +1,62 @@
+---
+source: crates/biome_css_analyze/tests/spec_tests.rs
+expression: invalid.css
+---
+# Input
+```css
+/* should generate diagnostics */
+@import url(foo.css) layer;
+
+@layer {
+	.test {
+		color: red;
+	}
+}
+
+```
+
+# Diagnostics
+```
+invalid.css:2:22 lint/nursery/useNamedLayer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ! Missing cascade layer name.
+  
+    1 │ /* should generate diagnostics */
+  > 2 │ @import url(foo.css) layer;
+      │                      ^^^^^
+    3 │ 
+    4 │ @layer {
+  
+  i An anonymous layer cannot be referenced, so later rules cannot append to it or reorder it.
+  
+  i Give the layer a name, for example @layer base { ... }.
+  
+  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.
+  
+
+```
+
+```
+invalid.css:4:2 lint/nursery/useNamedLayer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ! Missing cascade layer name.
+  
+    2 │ @import url(foo.css) layer;
+    3 │ 
+  > 4 │ @layer {
+      │  ^^^^^^^
+  > 5 │ 	.test {
+  > 6 │ 		color: red;
+  > 7 │ 	}
+  > 8 │ }
+      │ ^
+    9 │ 
+  
+  i An anonymous layer cannot be referenced, so later rules cannot append to it or reorder it.
+  
+  i Give the layer a name, for example @layer base { ... }.
+  
+  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/src/lint/nursery/use_named_layer.rs

@@ -0,0 +1,14 @@
+/* should not generate diagnostics */
+@import url(foo.css) layer(reset);
+
+@layer reset {
+	.test {
+		color: red;
+	}
+}
+
+@layer reset.text {
+	.test {
+		color: red;
+	}
+}

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

@@ -0,0 +1,22 @@
+---
+source: crates/biome_css_analyze/tests/spec_tests.rs
+expression: valid.css
+---
+# Input
+```css
+/* should not generate diagnostics */
+@import url(foo.css) layer(reset);
+
+@layer reset {
+	.test {
+		color: red;
+	}
+}
+
+@layer reset.text {
+	.test {
+		color: red;
+	}
+}
+
+```