feat: no-invalid-properties allowUnknownVariables option #178

jgoz · 2025-06-19T23:11:47Z

Prerequisites checklist

I have read the contributing guidelines.

What is the purpose of this pull request?

Adds an option to no-invalid-properties called allowUnknownVariables. When true, variable references that can't be traced to a custom property definition are ignored.

What changes did you make? (Give an overview)

Added an options schema for no-invalid-properties describing allowUnknownVariables. When the option is true, do the following:

Ignore variable references that were not found up to this point (skip reporting unknownVar)
Only report unknownProperty for errors of type SyntaxReferenceError, which indicate that the property is unknown

Also updated documentation for the rule to reflect this option as best I could.

Related Issues

Fixes #175

Is there anything you'd like reviewers to focus on?

Adds an option to `no-invalid-properties` called `allowUnknownVariables`. When true, variable references that can't be traced to a custom property definition are ignored. Fixes eslint#175

linux-foundation-easycla · 2025-06-19T23:11:53Z

The committers listed above are authorized under a signed CLA.

✅ login: jgoz / name: John Gozde (a9277ff, 748bba5, c160867, 4b7cdf6, 4314b64, 913e62c)

Copilot

Pull Request Overview

Adds an allowUnknownVariables option to the no-invalid-properties rule, letting users ignore variable references that can’t be traced to custom properties and adjust which errors are reported accordingly.

Updated rule schema and logic to default allowUnknownVariables to false, skip unknownVar reports when enabled, and only report unknownProperty on reference errors.
Introduced a new helper isSyntaxReferenceError in util.js and modified imports.
Expanded tests and documentation to cover the new option.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
tests/rules/no-invalid-properties.test.js	Added valid and invalid tests exercising `allowUnknownVariables`
src/util.js	Added `isSyntaxReferenceError` helper and updated import doc
src/rules/no-invalid-properties.js	Introduced schema option, wired up `allowUnknownVariables` in reporting logic
docs/rules/no-invalid-properties.md	Documented the new `allowUnknownVariables` option and examples

Comments suppressed due to low confidence (2)

src/util.js:30

[nitpick] The JSDoc @returns type uses a TypeScript type predicate. For clarity and consistency with JSDoc conventions, consider changing this to @returns {boolean} and describing the predicate in the description.

 * @returns {error is SyntaxReferenceError} True if the error is a syntax reference error, false if not.

docs/rules/no-invalid-properties.md:47

[nitpick] After replacing the old Limitations section, you may want to reintroduce it (or rename it) to explain any remaining parser limitations, or ensure that the table of contents and heading hierarchy are updated for clarity.

## Options

Copilot · 2025-06-20T18:54:32Z

src/rules/no-invalid-properties.js

+				properties: {
+					allowUnknownVariables: {
+						type: "boolean",
+						default: false,


ESLint does not apply default values from the schema at runtime. Since you already fallback in code (?? false), you can remove this default property to avoid confusion.

Suggested change

default: false,

Copilot · 2025-06-20T18:54:32Z

src/rules/no-invalid-properties.js

@@ -72,6 +73,18 @@ export default {
 			url: "https://github.com/eslint/css/blob/main/docs/rules/no-invalid-properties.md",
 		},

+		schema: [


[nitpick] Consider adding additionalProperties: false inside the schema object to prevent unknown or misspelled options from silently being accepted.

nzakas

This is looking really good. Just one note to clean things up a bit.

nzakas · 2025-06-20T18:58:48Z

src/rules/no-invalid-properties.js

@@ -95,6 +108,9 @@ export default {
 		 */
 		const replacements = [];

+		const allowUnknownVariables =
+			context.options?.[0]?.allowUnknownVariables ?? false;


If you use defaultOptions (example), then you can do this:

Suggested change

context.options?.[0]?.allowUnknownVariables ?? false;

context.options.[0].allowUnknownVariables;

Ah, thank you. Updated, but used destructuring syntax to match the style in relative-font-units

snitin315

Thanks for the PR. I found one issue while defining fallbacks in var

/* eslint css/no-invalid-properties: ["error"] */

:root {
	--my-color: red;
}

a {
	color: var(--my-color, red); // This now reports error - Unknown property 'color' found  css/no-invalid-propertie
}

snitin315 · 2025-06-21T15:44:25Z

Another case:

/* eslint css/no-invalid-properties: ["error",  { allowUnknownVariables: false }] */

:root {
	--my-color: red;
}

.two {
	color: var(--my-color, var(--my-background, pink));  //  error  Unknown property 'color' found  css/no-invalid-properties
}

jgoz · 2025-06-21T23:29:34Z

Thanks for the PR. I found one issue while defining fallbacks in var

Good catch, but I think this issue exists in main. Maybe it should be treated as a separate issue?

Edit: Both of the cases you point out are unrelated to my changes and are both issues that exist in main.

Tanujkanti4441 · 2025-06-22T09:17:18Z

Good catch, but I think this issue exists in main. Maybe it should be treated as a separate issue?

Edit: Both of the cases you point out are unrelated to my changes and are both issues that exist in main.

I can also reproduce this in main, have created an issue to discuss this #180

docs/rules/no-invalid-properties.md

snitin315 · 2025-06-23T03:59:39Z

Good catch, but I think this issue exists in main. Maybe it should be treated as a separate issue?

I see. Yes, let's tackle it separately.

Co-authored-by: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com>

nzakas

LGTM, thanks! Would like @snitin315 and @Tanujkanti4441 to verify their feedback has been addressed before merging.

nzakas · 2025-06-24T14:38:35Z

@jgoz please double-check the lint error.

jgoz · 2025-06-24T15:09:21Z

@nzakas That was a formatting error in a file I didn't change, so I'm not sure what happened there. I merged the latest from main in case it was an artifact of GHA's pull_request behavior that operates on a synthetic merge commit.

lumirlumir · 2025-06-25T06:49:20Z

Hi everyone, The CI failure is due to the newly released Prettier v3.6.0.

I’ve opened #182 to fix the issue. Once it’s merged into main, the error should be resolved.

lumirlumir · 2025-06-25T11:25:14Z

#182 has now been merged, so the CI error should be resolved once we merge the main branch. 👍

nzakas · 2025-06-25T14:28:12Z

Thanks @lumirlumir 🙏

jgoz · 2025-06-25T16:57:19Z

Merged from main

snitin315

LGTM, thanks!

Stale & comments resolved

feat: no-invalid-properties allowUnknownVariables option

748bba5

Adds an option to `no-invalid-properties` called `allowUnknownVariables`. When true, variable references that can't be traced to a custom property definition are ignored. Fixes eslint#175

github-project-automation bot moved this to Needs Triage in Triage Jun 19, 2025

github-project-automation bot added this to Triage Jun 19, 2025

eslint-github-bot bot added the feature label Jun 19, 2025

lumirlumir added the accepted There is consensus among the team that this change meets the criteria for inclusion label Jun 20, 2025

nzakas requested a review from Copilot June 20, 2025 18:52

nzakas added the contributor pool label Jun 20, 2025

Copilot AI reviewed Jun 20, 2025

View reviewed changes

nzakas reviewed Jun 20, 2025

View reviewed changes

Clean up schema, defaultOptions

a9277ff

nzakas moved this from Needs Triage to Implementing in Triage Jun 20, 2025

snitin315 requested changes Jun 21, 2025

View reviewed changes

Tanujkanti4441 previously requested changes Jun 22, 2025

View reviewed changes

jgoz and others added 2 commits June 23, 2025 08:46

Apply suggestions from code review

c160867

Co-authored-by: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com>

Update example

4b7cdf6

jgoz requested review from Tanujkanti4441 and snitin315 June 23, 2025 14:49

nzakas approved these changes Jun 24, 2025

View reviewed changes

nzakas moved this from Implementing to Second Review Needed in Triage Jun 24, 2025

Merge branch 'main' into feat-allowUnknownVariables

4314b64

lumirlumir mentioned this pull request Jun 25, 2025

chore: fix CI error related to prettier fmt #182

Merged

1 task

Merge branch 'main' into feat-allowUnknownVariables

913e62c

snitin315 approved these changes Jun 26, 2025

View reviewed changes

snitin315 merged commit 932cf62 into eslint:main Jun 26, 2025
22 checks passed

github-project-automation bot moved this from Second Review Needed to Complete in Triage Jun 26, 2025

github-actions bot mentioned this pull request Jun 26, 2025

chore: release 0.10.0 🚀 #177

Open

jgoz deleted the feat-allowUnknownVariables branch June 26, 2025 14:33

	context.options?.[0]?.allowUnknownVariables ?? false;
	context.options.[0].allowUnknownVariables;

Uh oh!

feat: no-invalid-properties allowUnknownVariables option #178

feat: no-invalid-properties allowUnknownVariables option #178

Uh oh!

Conversation

jgoz commented Jun 19, 2025

Prerequisites checklist

What is the purpose of this pull request?

What changes did you make? (Give an overview)

Related Issues

Is there anything you'd like reviewers to focus on?

Uh oh!

linux-foundation-easycla bot commented Jun 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

nzakas Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

jgoz Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

snitin315 left a comment

Choose a reason for hiding this comment

Uh oh!

snitin315 commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jgoz commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tanujkanti4441 commented Jun 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

snitin315 commented Jun 23, 2025

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

nzakas commented Jun 24, 2025

Uh oh!

jgoz commented Jun 24, 2025

Uh oh!

lumirlumir commented Jun 25, 2025

Uh oh!

lumirlumir commented Jun 25, 2025

Uh oh!

nzakas commented Jun 25, 2025

Uh oh!

jgoz commented Jun 25, 2025

Uh oh!

snitin315 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Jun 19, 2025 •

edited

Loading

snitin315 commented Jun 21, 2025 •

edited

Loading

jgoz commented Jun 21, 2025 •

edited

Loading