Merge branch 'main' into fix-cjs-types

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 -->
 

docs/rules/no-invalid-properties.md

@@ -42,6 +42,10 @@ body {
 }
 ```
 
+### Limitations
+
+This rule uses the lexer from [CSSTree](https://github.com/csstree/csstree), which does not support validation of property values that contain variable references (i.e., `var(--bg-color)`). The lexer throws an error when it comes across a variable reference, and rather than displaying that error, this rule ignores it. This unfortunately means that this rule cannot properly validate properties values that contain variable references. We'll continue to work towards a solution for this.
+
 ## When Not to Use It
 
 If you aren't concerned with invalid properties, then you can safely disable this rule.

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.

package.json

@@ -72,7 +72,7 @@
     "@eslint/core": "^0.10.0",
     "@eslint/plugin-kit": "^0.2.5",
     "@types/css-tree": "^2.3.10",
-    "css-tree": "^3.0.1"
+    "css-tree": "^3.1.0"
   },
   "devDependencies": {
     "@eslint/json": "^0.5.0",

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/no-invalid-properties.js

@@ -56,6 +56,18 @@ export default {
 						return;
 					}
 
+					/*
+					 * There's no current way to get lexing to work when a
+					 * `var()` is present in a value. Rather than blowing up,
+					 * we'll just ignore it.
+					 *
+					 * https://github.com/csstree/csstree/issues/317
+					 */
+
+					if (error.message.endsWith("var() is not supported")) {
+						return;
+					}
+
 					// unknown property
 					context.report({
 						loc: {

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",
+				});
+			},
+		};
+	},
+};

tests/rules/no-invalid-properties.test.js

@@ -32,6 +32,7 @@ ruleTester.run("no-invalid-properties", rule, {
 		"a { color: red; -moz-transition: bar }",
 		"@font-face { font-weight: 100 400 }",
 		'@property --foo { syntax: "*"; inherits: false; }',
+		"a { --my-color: red; color: var(--my-color) }",
 	],
 	invalid: [
 		{