feat: no-invalid-properties allowUnknownVariables option

[jgoz]

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?

[linux-foundation-easycla]

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]

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]

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

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

Suggested change

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

[jgoz]

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]

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]

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]

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

[snitin315]

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.

[nzakas]

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

[nzakas]

@jgoz please double-check the lint error.

[jgoz]

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

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]

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

[nzakas]

Thanks @lumirlumir 🙏

[jgoz]

Merged from main

[snitin315]

LGTM, thanks!

Stale & comments resolved