Repository: eslint/css
Pull request #45 (2025-01-14 21:19:48)

fix: Suppress var() validation errors
<!--
    Thank you for contributing!

    ESLint adheres to the [OpenJS Foundation Code of Conduct](https://eslint.org/conduct).
-->

#### Prerequisites checklist

- [x] I have read the [contributing guidelines](https://github.com/eslint/eslint/blob/HEAD/CONTRIBUTING.md).

<!--
    Please ensure your pull request is ready:

    - Read the pull request guide (https://eslint.org/docs/latest/contribute/pull-requests)
    - Update or create tests
    - If performance-related, include a benchmark
    - Update documentation for this change (if appropriate)
-->

<!--
    The following is required for all pull requests:
-->

#### What is the purpose of this pull request?

Ensure that property values with `var(...)` don't throw an error in `no-invalid-properties`.

#### What changes did you make? (Give an overview)

- Catch `var() not supported` errors from CSS Tree and don't display to the user in `no-invalid-properties`
- Updated documentation for `no-invalid-properties`
- Added a test

#### Related Issues

refs #40

<!-- include tags like "fixes #123" or "refs #123" -->

#### Is there anything you'd like reviewers to focus on?

This isn't really a fix for the issue, just suppressing the error for now. This needs to be fixed upstream in CSSTree for a better fix:
https://github.com/csstree/csstree/issues/317


<!-- markdownlint-disable-file MD004 -->



Patch:
diff --git a/README.md b/README.md
index 5b89757..c3be5a3 100644
--- 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/no-invalid-properties.md b/docs/rules/no-invalid-properties.md
index def5eb2..767a101 100644
--- a/docs/rules/no-invalid-properties.md
+++ b/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.
diff --git a/docs/rules/use-layers.md b/docs/rules/use-layers.md
new file mode 100644
index 0000000..f396d04
--- /dev/null
+++ 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
index 8508faa..a0d5924 100644
--- 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
index bdaf915..233092b 100644
--- 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/no-invalid-properties.js b/src/rules/no-invalid-properties.js
index 3f9f343..74e8f0b 100644
--- a/src/rules/no-invalid-properties.js
+++ b/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: {
diff --git a/src/rules/use-layers.js b/src/rules/use-layers.js
new file mode 100644
index 0000000..13aadb3
--- /dev/null
+++ 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",
+				});
+			},
+		};
+	},
+};


Test patch:
diff --git a/tests/rules/no-invalid-properties.test.js b/tests/rules/no-invalid-properties.test.js
index 9ceced7..22005a8 100644
--- a/tests/rules/no-invalid-properties.test.js
+++ b/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: [
 		{
diff --git a/tests/rules/use-layers.test.js b/tests/rules/use-layers.test.js
new file mode 100644
index 0000000..6a99e7a
--- /dev/null
+++ b/tests/rules/use-layers.test.js
@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Tests for use-layers rule.
+ * @author Nicholas C. Zakas
+ */
+
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+
+import rule from "../../src/rules/use-layers.js";
+import css from "../../src/index.js";
+import { RuleTester } from "eslint";
+import dedent from "dedent";
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+const ruleTester = new RuleTester({
+	plugins: {
+		css,
+	},
+	language: "css/css",
+});
+
+ruleTester.run("use-layers", rule, {
+	valid: [
+		"@layer bar { a { color: red; } }",
+		"@layer foo { a { color: red; } }",
+		"@import 'foo.css' layer(foo);",
+		dedent`
+			@media (min-width: 600px) {
+				@layer foo {
+					a { color: bar }
+				}
+			}
+		`,
+		dedent`
+			@media (min-width: 600px) {
+				@layer foo {
+					a { color: bar }
+					@layer bar {
+						b { color: red; }
+					}
+				}
+			}
+		`,
+		{
+			code: "@layer { a { color: red; } }",
+			options: [{ allowUnnamedLayers: true }],
+		},
+		{
+			code: "@import 'foo.css' layer;",
+			options: [{ allowUnnamedLayers: true }],
+		},
+		{
+			code: "@import 'foo.css';",
+			options: [{ requireImportLayers: false }],
+		},
+	],
+	invalid: [
+		{
+			code: "a { color: bar }",
+			errors: [
+				{
+					messageId: "missingLayer",
+					line: 1,
+					column: 1,
+					endLine: 1,
+					endColumn: 17,
+				},
+			],
+		},
+		{
+			code: dedent`
+				a { color: bar }
+				@layer { a { color: red; } }
+			`,
+			errors: [
+				{
+					messageId: "missingLayer",
+					line: 1,
+					column: 1,
+					endLine: 1,
+					endColumn: 17,
+				},
+				{
+					messageId: "missingLayerName",
+					line: 2,
+					column: 1,
+					endLine: 2,
+					endColumn: 29,
+				},
+			],
+		},
+		{
+			code: dedent`
+				@layer { a { color: red; } }
+				a { color: bar }
+			`,
+			errors: [
+				{
+					messageId: "missingLayerName",
+					line: 1,
+					column: 1,
+					endLine: 1,
+					endColumn: 29,
+				},
+				{
+					messageId: "missingLayer",
+					line: 2,
+					column: 1,
+					endLine: 2,
+					endColumn: 17,
+				},
+			],
+		},
+		{
+			code: dedent`
+				@media (min-width: 600px) {
+					a { color: bar }
+				}
+			`,
+			errors: [
+				{
+					messageId: "missingLayer",
+					line: 2,
+					column: 2,
+					endLine: 2,
+					endColumn: 18,
+				},
+			],
+		},
+		{
+			code: dedent`
+				@media (min-width: 600px) {
+					@layer foo {
+						a { color: bar }
+						@layer bar {
+							b { color: red; }
+						}
+					}
+				}
+
+				p { color: red; }
+			`,
+			errors: [
+				{
+					messageId: "missingLayer",
+					line: 10,
+					column: 1,
+					endLine: 10,
+					endColumn: 18,
+				},
+			],
+		},
+		{
+			code: "@import 'foo.css';",
+			errors: [
+				{
+					messageId: "missingImportLayer",
+					line: 1,
+					column: 1,
+					endLine: 1,
+					endColumn: 19,
+				},
+			],
+		},
+		{
+			code: "@import 'foo.css' layer;",
+			errors: [
+				{
+					messageId: "missingLayerName",
+					line: 1,
+					column: 19,
+					endLine: 1,
+					endColumn: 24,
+				},
+			],
+		},
+		{
+			code: "@layer foo, baz { a { color: bar } }",
+			options: [{ layerNamePattern: "bar" }],
+			errors: [
+				{
+					messageId: "layerNameMismatch",
+					data: {
+						name: "foo",
+						pattern: "bar",
+					},
+					line: 1,
+					column: 8,
+					endLine: 1,
+					endColumn: 11,
+				},
+				{
+					messageId: "layerNameMismatch",
+					data: {
+						name: "baz",
+						pattern: "bar",
+					},
+					line: 1,
+					column: 13,
+					endLine: 1,
+					endColumn: 16,
+				},
+			],
+		},
+		{
+			code: "@layer foo, bar, baz;",
+			options: [{ layerNamePattern: "bar" }],
+			errors: [
+				{
+					messageId: "layerNameMismatch",
+					data: {
+						name: "foo",
+						pattern: "bar",
+					},
+					line: 1,
+					column: 8,
+					endLine: 1,
+					endColumn: 11,
+				},
+				{
+					messageId: "layerNameMismatch",
+					data: {
+						name: "baz",
+						pattern: "bar",
+					},
+					line: 1,
+					column: 18,
+					endLine: 1,
+					endColumn: 21,
+				},
+			],
+		},
+		{
+			code: "@import 'foo.css' layer(baz);",
+			options: [{ layerNamePattern: "bar" }],
+			errors: [
+				{
+					messageId: "layerNameMismatch",
+					data: {
+						name: "baz",
+						pattern: "bar",
+					},
+					line: 1,
+					column: 25,
+					endLine: 1,
+					endColumn: 28,
+				},
+			],
+		},
+		{
+			code: "@import 'foo.css'",
+			errors: [
+				{
+					messageId: "missingImportLayer",
+					line: 1,
+					column: 1,
+					endLine: 1,
+					endColumn: 18,
+				},
+			],
+		},
+	],
+});