feat: Add use-layers rule

docs/rules/use-layers.md

@@ -0,0 +1,122 @@
+# use-layers
+
+Require use of layers.
+
+## Background
+
+Layers are a way to organize the cascading of rules outside of their source code order. By defining named layers and describing their order, you can ensure that rules are applied in the order that best matches your use case. Here's an example:
+
+```css
+/* establish the cascade order */
+@layer reset, base, theme;
+
+/* import styles into the reset layer */
+@import url("reset.css") layer(reset);
+
+/* Theme styles */
+@layer theme {
+	body {
+		background-color: #f0f0f0;
+		color: #333;
+	}
+}
+
+/* Base styles */
+@layer base {
+	body {
+		font-family: Arial, sans-serif;
+		line-height: 1.6;
+	}
+}
+```
+
+In general, you don't want to mix rules inside of layers with rules outside of layers because you're then dealing with two different cascade behaviors.
+
+## Rule Details
+
+This rule enforces the use of layers and warns when any rule appears outside of a `@layer` block and if any layer doesn't have a name. Additionally, there are several options available to customize the behavior of this rule.
+
+Examples of incorrect code:
+
+```css
+/* no layer name */
+@import url(foo.css) layer;
+
+/* outside of layer */
+.my-style {
+	color: red;
+}
+
+/* no layer name */
+@layer {
+	a {
+		color: red;
+	}
+}
+```
+
+### Options
+
+This rule accepts an options object with the following properties:
+
+- `allowUnnamedLayers` (default: `false`) - Set to `true` to allow layers without names.
+- `layerNamePattern` (default: `""`) - Set to a regular expression string to validate all layer names.
+- `requireImportsLayers` (default: `false`) - Set to `true` to require that all `@import` rules must specify a layer.
+
+#### `allowUnnamedLayers: true`
+
+When `allowUnnamedLayers` is set to `true`, the following code is **correct**:
+
+```css
+/* eslint css/use-layers: ["error", { allowUnnamedLayers: true }] */
+/* no layer name */
+@import url(foo.css) layer;
+
+/* no layer name */
+@layer {
+	a {
+		color: red;
+	}
+}
+```
+
+#### `layerNamePattern`
+
+The `layerNamePattern` is a regular expression string that allows you to validate the name of layers and prevent misspellings.
+
+Here's an example of **incorrect** code:
+
+```css
+/* eslint css/use-layers: ["error", { layerNamePattern: "reset|theme|base" }] */
+/* possible typo */
+@import url(foo.css) layer(resett);
+
+/* unknown layer name */
+@layer defaults {
+	a {
+		color: red;
+	}
+}
+```
+
+#### `requireImportLayers: true`
+
+When `requireImportLayers` is set to `true`, the following code is **incorrect**:
+
+```css
+/* eslint css/use-layers: ["error", { requireImportLayers: true }] */
+/* missing layer */
+@import url(foo.css);
+```
+
+The following code is **correct**:
+
+```css
+/* eslint css/use-layers: ["error", { requireImportLayers: true }] */
+@import url(foo.css) layer;
+@import url(bar.css) layer(reset);
+```
+
+## When Not to Use It
+
+If you are defining rules without layers in a file (for example, `reset.css`) and then importing that file into a layer in another file (such as, `@import url(reset.css) layer(reset)`), then you should disable this rule in the imported file (in this example, `reset.css`). This rule is only needed in the file(s) that require layers.

src/index.js

@@ -13,6 +13,7 @@ import noEmptyBlocks from "./rules/no-empty-blocks.js";
 import noDuplicateImports from "./rules/no-duplicate-imports.js";
 import noInvalidProperties from "./rules/no-invalid-properties.js";
 import noInvalidAtRules from "./rules/no-invalid-at-rules.js";
+import useLayers from "./rules/use-layers.js";
 
 //-----------------------------------------------------------------------------
 // Plugin
@@ -31,6 +32,7 @@ const plugin = {
 		"no-duplicate-imports": noDuplicateImports,
 		"no-invalid-at-rules": noInvalidAtRules,
 		"no-invalid-properties": noInvalidProperties,
+		"use-layers": useLayers,
 	},
 	configs: {
 		recommended: {

src/rules/use-layers.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Rule to require layers in CSS.
+ * @author Nicholas C. Zakas
+ */
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+export default {
+	meta: {
+		type: /** @type {const} */ ("problem"),
+
+		docs: {
+			description: "Require use of layers",
+			recommended: true,
+		},
+
+		schema: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					allowUnnamedLayers: {
+						type: "boolean",
+					},
+					requireImportLayers: {
+						type: "boolean",
+					},
+					layerNamePattern: {
+						type: "string",
+					},
+				},
+				additionalProperties: false,
+			},
+			minItems: 0,
+			maxItems: 1,
+		},
+
+		defaultOptions: [
+			{
+				allowUnnamedLayers: false,
+				requireImportLayers: false,
+				layerNamePattern: "",
+			},
+		],
+
+		messages: {
+			missingLayer: "Expected rule to be within a layer.",
+			missingLayerName: "Expected layer to have a name.",
+			missingImportLayer: "Expected import to be within a layer.",
+			layerNameMismatch:
+				"Expected layer name '{{ name }}' to match pattern '{{pattern}}'.",
+		},
+	},
+
+	create(context) {
+		let layerDepth = 0;
+		const options = context.options[0];
+		const layerNameRegex = options.layerNamePattern
+			? new RegExp(options.layerNamePattern, "u")
+			: null;
+
+		return {
+			"Atrule[name=import]"(node) {
+				// layer, if present, must always be the second child of the prelude
+				const secondChild = node.prelude.children[1];
+				const layerNode =
+					secondChild?.name === "layer" ? secondChild : null;
+
+				if (options.requireImportLayers && !layerNode) {
+					context.report({
+						loc: node.loc,
+						messageId: "missingImportLayer",
+					});
+				}
+
+				if (layerNode) {
+					const isLayerFunction = layerNode.type === "Function";
+
+					if (!options.allowUnnamedLayers && !isLayerFunction) {
+						context.report({
+							loc: layerNode.loc,
+							messageId: "missingLayerName",
+						});
+					}
+				}
+			},
+
+			Layer(node) {
+				if (!layerNameRegex) {
+					return;
+				}
+
+				/*
+				 * Layer node location is incorrect.
+				 * https://github.com/csstree/csstree/issues/309
+				 */
+				if (!layerNameRegex.test(node.name)) {
+					context.report({
+						loc: node.loc,
+						messageId: "layerNameMismatch",
+						data: {
+							name: node.name,
+							pattern: options.layerNamePattern,
+						},
+					});
+				}
+			},
+
+			"Atrule[name=layer]"(node) {
+				layerDepth++;
+
+				if (!options.allowUnnamedLayers && !node.prelude) {
+					context.report({
+						loc: node.loc,
+						messageId: "missingLayerName",
+					});
+				}
+			},
+
+			"Atrule[name=layer]:exit"() {
+				layerDepth--;
+			},
+
+			Rule(node) {
+				if (layerDepth > 0) {
+					return;
+				}
+
+				context.report({
+					loc: node.loc,
+					messageId: "missingLayer",
+				});
+			},
+		};
+	},
+};