feat: Add use-layers rule (#27)

* feat: Add use-layers rule * Update README * @import should require layers by default * Fix types error * use-layers should not be recommended * Upgrade CSSTree to fix layer location error * Add valid test * Update src/rules/use-layers.js Co-authored-by: Milos Djermanovic <[email protected]> * Update docs/rules/use-layers.md Co-authored-by: Milos Djermanovic <[email protected]> * Update src/rules/use-layers.js Co-authored-by: Milos Djermanovic <[email protected]> --------- Co-authored-by: Milos Djermanovic <[email protected]>
eslint · Jan 15, 2025 · 6ebf57e · 6ebf57e
1 parent 222b17a
commit 6ebf57e
Show file tree

Hide file tree

Showing 6 changed files with 526 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -62,6 +62,7 @@ export default [
 | [`no-empty-blocks`](./docs/rules/no-empty-blocks.md)             | Disallow empty blocks            |       yes       |
 | [`no-invalid-at-rules`](./docs/rules/no-invalid-at-rules.md)     | Disallow invalid at-rules        |       yes       |
 | [`no-invalid-properties`](./docs/rules/no-invalid-properties.md) | Disallow invalid properties      |       yes       |
+| [`use-layers`](./docs/rules/use-layers.md)                       | Require use of layers            |       no        |
 
 <!-- Rule Table End -->
 

diff --git a/docs/rules/use-layers.md b/docs/rules/use-layers.md
@@ -0,0 +1,124 @@
+# 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:
+
+1. Any rule appears outside of a `@layer` block.
+1. Any `@import` doesn't specify a layer.
+1. If any layer doesn't have a name.
+
+Examples of incorrect code:
+
+```css
+/* no layer name */
+@import url(foo.css) layer;
+
+/* no layer */
+@import url(bar.css);
+
+/* outside of layer */
+.my-style {
+	color: red;
+}
+
+/* no layer name */
+@layer {
+	a {
+		color: red;
+	}
+}
+```
+
+There are also additional options to customize the behavior of this rule.
+
+### 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.
+- `requireImportLayers` (default: `true`) - Set to `false` to allow `@import` rules without 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: false`
+
+When `requireImportLayers` is set to `false`, the following code is **correct**:
+
+```css
+/* eslint css/use-layers: ["error", { requireImportLayers: false }] */
+@import url(foo.css);
+@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.
diff --git a/package.json b/package.json
@@ -70,7 +70,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@eslint/plugin-kit": "^0.2.3",
-    "css-tree": "^3.0.1"
+    "css-tree": "^3.1.0"
   },
   "devDependencies": {
     "@eslint/core": "^0.7.0",

diff --git a/src/index.js b/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: {

diff --git a/src/rules/use-layers.js b/src/rules/use-layers.js
@@ -0,0 +1,131 @@
+/**
+ * @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",
+			url: "https://github.com/eslint/css/blob/main/docs/rules/use-layers.md",
+		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					allowUnnamedLayers: {
+						type: "boolean",
+					},
+					requireImportLayers: {
+						type: "boolean",
+					},
+					layerNamePattern: {
+						type: "string",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		defaultOptions: [
+			{
+				allowUnnamedLayers: false,
+				requireImportLayers: true,
+				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;
+				}
+
+				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",
+				});
+			},
+		};
+	},
+};