feat: add allowUnknownVariables option to no-invalid-properties (#178)

Co-authored-by: Tanuj Kanti <[email protected]>

Author: jgoz

docs/rules/no-invalid-properties.md

@@ -44,11 +44,31 @@ body {
 }
 ```
 
-### Limitations
+## Options
 
-When a variable is used in a property value, such as `var(--my-color)`, the rule can only properly be validated if the parser has already encountered the `--my-color` custom property. For example, this will validate correctly:
+This rule accepts an option which is an object with the following property:
+
+- `allowUnknownVariables` (default: `false`) - Ignore variables that cannot be traced to custom properties in the current file.
+
+When a variable is used in a property value, such as `var(--my-color)`, the rule can only properly be validated if the parser has already encountered the `--my-color` custom property. With `{ allowUnknownVariables: false }`, unknown variables will result in a linting error. With `{ allowUnknownVariables: true }`, the property value will be ignored and only the property name will be validated.
+
+Examples of **incorrect** code with `{ allowUnknownVariables: false }` (the default):
 
 ```css
+/* eslint css/no-invalid-properties: ["error", { allowUnknownVariables: false }] */
+
+a {
+	color: var(--my-color);
+}
+```
+
+This code uses `var(--my-color)` before `--my-color` is defined, or whether it is defined in another CSS file. Therefore, `color: var(--my-color)` cannot be properly validated.
+
+Examples of **correct** code with `{ allowUnknownVariables: false }`:
+
+```css
+/* eslint css/no-invalid-properties: ["error", { allowUnknownVariables: false }] */
+
 :root {
 	--my-color: red;
 }
@@ -60,7 +80,29 @@ a {
 
 This code defines `--my-color` before it is used and therefore the rule can validate the `color` property. If `--my-color` was not defined before `var(--my-color)` was used, it results in a lint error because the validation cannot be completed.
 
-If the custom property is defined in another file, it's recommended to create a dummy rule just to ensure proper validation.
+Examples of **incorrect** code with `{ allowUnknownVariables: true }`:
+
+```css
+/* eslint css/no-invalid-properties: ["error", { allowUnknownVariables: true }] */
+
+a {
+	ccolorr: var(--my-color);
+}
+```
+
+This code uses an unknown property `ccolorr`, which results in a validation error. The unknown reference to `var(--my-color)` is ignored.
+
+Examples of **correct** code with `{ allowUnknownVariables: true }`:
+
+```css
+/* eslint css/no-invalid-properties: ["error", { allowUnknownVariables: true }] */
+
+a {
+	color: var(--my-color);
+}
+```
+
+Even though `var(--my-color)` cannot be traced to a custom property definition, this code passes validation.
 
 ## When Not to Use It
 

src/rules/no-invalid-properties.js

@@ -7,7 +7,7 @@
 // Imports
 //-----------------------------------------------------------------------------
 
-import { isSyntaxMatchError } from "../util.js";
+import { isSyntaxMatchError, isSyntaxReferenceError } from "../util.js";
 
 //-----------------------------------------------------------------------------
 // Type Definitions
@@ -17,7 +17,8 @@ import { isSyntaxMatchError } from "../util.js";
  * @import { CSSRuleDefinition } from "../types.js"
  * @import { ValuePlain, FunctionNodePlain, CssLocationRange } from "@eslint/css-tree";
  * @typedef {"invalidPropertyValue" | "unknownProperty" | "unknownVar"} NoInvalidPropertiesMessageIds
- * @typedef {CSSRuleDefinition<{ RuleOptions: [], MessageIds: NoInvalidPropertiesMessageIds }>} NoInvalidPropertiesRuleDefinition
+ * @typedef {[{allowUnknownVariables?: boolean}]} NoInvalidPropertiesOptions
+ * @typedef {CSSRuleDefinition<{ RuleOptions: NoInvalidPropertiesOptions, MessageIds: NoInvalidPropertiesMessageIds }>} NoInvalidPropertiesRuleDefinition
  */
 
 //-----------------------------------------------------------------------------
@@ -72,6 +73,24 @@ export default {
 			url: "https://github.com/eslint/css/blob/main/docs/rules/no-invalid-properties.md",
 		},
 
+		schema: [
+			{
+				type: "object",
+				properties: {
+					allowUnknownVariables: {
+						type: "boolean",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		defaultOptions: [
+			{
+				allowUnknownVariables: false,
+			},
+		],
+
 		messages: {
 			invalidPropertyValue:
 				"Invalid value '{{value}}' for property '{{property}}'. Expected {{expected}}.",
@@ -95,6 +114,8 @@ export default {
 		 */
 		const replacements = [];
 
+		const [{ allowUnknownVariables }] = context.options;
+
 		return {
 			"Rule > Block > Declaration"() {
 				replacements.push(new Map());
@@ -153,7 +174,7 @@ export default {
 							offsets.forEach(offset => {
 								varsFoundLocs.set(offset, func.loc);
 							});
-						} else {
+						} else if (!allowUnknownVariables) {
 							context.report({
 								loc: func.children[0].loc,
 								messageId: "unknownVar",
@@ -205,22 +226,27 @@ export default {
 						return;
 					}
 
-					// unknown property
-					context.report({
-						loc: {
-							start: node.loc.start,
-							end: {
-								line: node.loc.start.line,
-								column:
-									node.loc.start.column +
-									node.property.length,
+					if (
+						!allowUnknownVariables ||
+						isSyntaxReferenceError(error)
+					) {
+						// unknown property
+						context.report({
+							loc: {
+								start: node.loc.start,
+								end: {
+									line: node.loc.start.line,
+									column:
+										node.loc.start.column +
+										node.property.length,
+								},
+							},
+							messageId: "unknownProperty",
+							data: {
+								property: node.property,
 							},
-						},
-						messageId: "unknownProperty",
-						data: {
-							property: node.property,
-						},
-					});
+						});
+					}
 				}
 			},
 		};

src/util.js

@@ -8,7 +8,7 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @import { SyntaxMatchError } from "@eslint/css-tree"
+ * @import { SyntaxMatchError, SyntaxReferenceError } from "@eslint/css-tree"
  */
 
 //-----------------------------------------------------------------------------
@@ -24,6 +24,15 @@ export function isSyntaxMatchError(error) {
 	return typeof error.syntax === "string";
 }
 
+/**
+ * Determines if an error is a syntax reference error.
+ * @param {Object} error The error object to check.
+ * @returns {error is SyntaxReferenceError} True if the error is a syntax reference error, false if not.
+ */
+export function isSyntaxReferenceError(error) {
+	return typeof error.reference === "string";
+}
+
 /**
  * Finds the line and column offsets for a given offset in a string.
  * @param {string} text The text to search.

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

@@ -47,6 +47,14 @@ ruleTester.run("no-invalid-properties", rule, {
 				},
 			},
 		},
+		{
+			code: "a { color: var(--my-color); }",
+			options: [{ allowUnknownVariables: true }],
+		},
+		{
+			code: "a { --my-color: red; color: var(--my-color); background-color: var(--unknown-var); }",
+			options: [{ allowUnknownVariables: true }],
+		},
 
 		/*
 		 * CSSTree doesn't currently support custom functions properly, so leaving
@@ -404,5 +412,49 @@ ruleTester.run("no-invalid-properties", rule, {
 				},
 			],
 		},
+		{
+			code: "a { colorr: var(--my-color); }",
+			options: [{ allowUnknownVariables: true }],
+			errors: [
+				{
+					messageId: "unknownProperty",
+					data: {
+						property: "colorr",
+					},
+					line: 1,
+					column: 5,
+					endLine: 1,
+					endColumn: 11,
+				},
+			],
+		},
+		{
+			code: "a { --my-color: 10px; color: var(--my-color); background_color: var(--unknown-var); }",
+			options: [{ allowUnknownVariables: true }],
+			errors: [
+				{
+					messageId: "invalidPropertyValue",
+					data: {
+						property: "color",
+						value: "10px",
+						expected: "<color>",
+					},
+					line: 1,
+					column: 30,
+					endLine: 1,
+					endColumn: 45,
+				},
+				{
+					messageId: "unknownProperty",
+					data: {
+						property: "background_color",
+					},
+					line: 1,
+					column: 47,
+					endLine: 1,
+					endColumn: 63,
+				},
+			],
+		},
 	],
 });