Fix `declaration-property-value-no-unknown` false negatives for math functions by ragini-pandey · Pull Request #9011 · stylelint/stylelint

ragini-pandey · 2026-02-01T09:17:38Z

Which issue, if any, is this issue related to?

Is there anything in the PR that needs further explanation?

This PR adds validation for calc() expressions in the declaration-property-value-no-unknown rule to catch invalid type combinations.

Changes

Added @csstools/css-calc dependency to validate calc expressions
Enhanced calc validation by:
- Attempting to solve calc expressions using @csstools/css-calc
- If the expression can be solved (e.g., calc(2px * 2) → 4px), validating the result with csstree
- If the expression cannot be solved, checking for invalid type mixing patterns (e.g., calc(2px + 2) - adding dimension and unitless number)
Added helper functions:
- validateMathFunctions() - validates calc/clamp/min/max expressions
- hasInvalidTypeMix() - detects invalid type combinations in expressions
- findMathExpression() - extracts the math expression from the value for error reporting

Examples

Now correctly reports errors for:

/* Invalid: unitless number for property expecting length */
a { height: calc(2); }
a { height: calc(2 + 2); }

/* Invalid: mixing dimension and unitless number in addition */
a { height: calc(2px + 2); }

Still accepts valid expressions:

/* Valid: results in a length */
a { height: calc(2px * 2); }

/* Valid: mixed units that are both lengths */
a { margin: calc(100% - 10px); }

/* Valid: multiplication with variables */
a { height: calc(var(--foo) * 2); }

The validation is conservative - it only reports errors for clearly invalid patterns while allowing expressions that might be valid but cannot be fully resolved at parse time (like percentage + pixel combinations).

…ty-value-no-unknown rule

changeset-bot · 2026-02-01T09:17:41Z

🦋 Changeset detected

Latest commit: c3d5e13

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
stylelint	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…alue

github-actions · 2026-02-04T05:08:11Z

This PR is packaged and the instant preview is available (c3d5e13). View the demo website.

Install it locally:

npm i -D https://pkg.pr.new/stylelint@c3d5e13

…alue

ybiquitous

Thanks for the pull request. Please take a look at my review comments?

lib/rules/declaration-property-value-no-unknown/index.mjs

ybiquitous · 2026-02-04T11:19:37Z

Plus, can you improve the coverage? There are uncovered lines, ref:
https://app.codecov.io/gh/stylelint/stylelint/pull/9011

ybiquitous

[suggestion]

stylelint/types/stylelint/index.d.ts

Lines 656 to 658 in f673be9

    
           RejectedMessage<[property: string, value: string]> & { 
        
           	rejectedParseError: (property: string, value: string) => string; 
        
           }

lib/rules/declaration-property-value-no-unknown/index.mjs

ybiquitous · 2026-02-05T08:01:34Z

@ragini-pandey Thanks, overall LGTM. 👍🏼

But there are still uncovered lines. Do you think it's reasonable to cover them by adding test cases?
https://app.codecov.io/gh/stylelint/stylelint/pull/9011

ybiquitous

@romainmenke This PR introduces your package @csstools/css-calc. I'd appreciate it if you could provide any thoughts on using the package. 🙏🏼

jeddy3

Thank you for the PR.

I've made two minor suggestions.

.changeset/twelve-islands-help.md

lib/rules/declaration-property-value-no-unknown/index.mjs

…alue

…no-unknown rule

ybiquitous · 2026-02-05T14:19:18Z

But there are still uncovered lines. Do you think it's reasonable to cover them by adding test cases?
https://app.codecov.io/gh/stylelint/stylelint/pull/9011

@ragini-pandey Any updates on the coverage?

romainmenke · 2026-02-05T14:31:24Z

@ybiquitous I will take a look as soon as possible.

My immediate concern is that this library isn't intended for this use case.

It does implement most of the math related features in CSS but its focus is on doing so outside the context of a browser. This means that it can't convert between rem and px and likewise can't resolve percentage values.

It was created to be able to generate fallback values for relative colors that can contain math expressions. This scope is considerably narrow than validating/linting math expressions in general in the context of a browser.

I did mention this library in the linked issue because it does illustrate some of the complexity involved in handling CSS math expressions. But I did not mean to imply it should be used to solve that issue. I could have stated that more clearly.

That said, if it does seem to work and makes this rule more helpful then that is obviously good.

My concern is that it can only be used in the simplest of cases, e.g. width: calc(3 + 2). As in this case it can simplify the expression to 5 which isn't valid for width.

So I wonder if all the analysis can instead be done without this package?

But I need to take a closer look and I am unsure when I will have time for this.

lib/rules/declaration-property-value-no-unknown/__tests__/index.mjs

ybiquitous · 2026-02-05T15:44:27Z

@romainmenke Thanks a lot for providing helpful information. Your concern about the @csstools/css-calc package makes sense to me, and I understand that your time for OSS is limited. Please take care of your own time. 😃

It looks like all the test cases added by this PR cover a wide range of use cases, but to be honest, are you concerned that the math function support might be causing a bunch of false positives and reported issues?

Also, could we mitigate this by documenting the limitation in the rule's README?

As much as possible, I'd like to avoid potential issues that can exhaust maintainers.

romainmenke · 2026-02-05T17:02:29Z

First of all, thank you for working on this @ragini-pandey 🙇
I think this direction is indeed interesting and will help users avoid some issues 🎉

I think the current approach will only cause false negatives and no (or very few) false positives.

We might have to tweak the rule in the future in case math functions are added that do mix numbers with either dimensions or percentages. I recall such a function being discussed in the CSSWG recently but don't remember what it was. I hope I stumble on it again :) But this is the only source of false negatives this approach can cause.

As @ragini-pandey stated the rule is conservative and I think that is the right tradeoff for now :)

Some interesting false positives:

Demo

.a {
  width: calc(20ms + 10%);
}

.b {
  width: calc((50px) + 50);
  width: calc((30px + 20px) + (30 + 20));
  width: calc(calc(30px + 20px) + calc(30 + 20));
}

I think that the chance of user error goes up as complexity of the expression increases.
So it would be nice if we can also handle some of these cases.

But we can also do that in a follow up issue.

Overal I think this change is good :)
It strikes a good balance between adding some extra reporting and having too much complexity here in Stylelint for something that should be added upstream in csstree.

Thank you again @ragini-pandey for working on this

… invalid option types

ragini-pandey · 2026-02-05T18:36:17Z

Thank you for such a detailed and through review @jeddy3 @ybiquitous @romainmenke
Learned a lot and will carry these learnings forward in upcoming PRs.

…alue

ybiquitous

@romainmenke Thanks for your thoughts. We can go ahead.

@ragini-pandey Thanks for addressing my requests, LGTM 👍🏼

jeddy3

@ragini-pandey Thank you for the pull request. It's looking great.

@ybiquitous & @romainmenke Thanks for the first reviews; it shaped up nicely.

I've requested a couple of changes: a style nit and a performance one.

This is one of our slowest rules, and tokenising adds an additional overhead. We can mitigate it with an early, cheap (regex) check before doing a thorough one.

Benchmarks:

# Baseline (`main`)
Warnings: 40
Mean: 745.3653410909092 ms
Deviation: 40.79649635044739 ms

# This branch:
Warnings: 40
Mean: 837.4639167 ms
Deviation: 42.56683379415065 ms

# With cheap check:
Warnings: 40
Mean: 747.5652725454546 ms
Deviation: 51.039669110864516 ms

lib/rules/declaration-property-value-no-unknown/index.mjs

jeddy3 · 2026-02-06T15:47:27Z

lib/rules/declaration-property-value-no-unknown/index.mjs

+import { mathFunctions } from '../../reference/functions.mjs';
+
 const { next: syntaxPatches } = syntaxPatchesJson;



Suggested change

const HAS_MATH_FUNCTION = new RegExp(`\\b(?:${[...mathFunctions.values()].join('|')})\\(`, 'i');

lib/rules/declaration-property-value-no-unknown/index.mjs

…aration-property-value-no-unknown rule

ragini-pandey · 2026-02-06T18:26:39Z

I’m having trouble hitting 98% coverage. I tried using AI as well, but some negative cases seem impossible to cover.

…alue

jeddy3

Thanks for making the changes. LGTM, thank you!

I’m having trouble hitting 98% coverage

I think that's fine as it's sometimes not possible.

ragini-pandey · 2026-02-08T14:36:31Z

codecov/patch — 96.55% of diff hit (target 97.99%)

Thanks for making the changes. LGTM, thank you!

I’m having trouble hitting 98% coverage

I think that's fine as it's sometimes not possible.

Ohk. Understood.
Then how do we merge this PR with failing check of codecov/patc?

jeddy3 · 2026-02-08T18:00:27Z

Merged, thank you. Your fix will be included in the next release.

Then how do we merge this PR with failing check of codecov/patc?

Maintainers have the permissions to do that.

@adalinesimonian

@jeddy3

@jeddy3

@jeddy3

Add support for calc() and other math functions in declaration-proper…

c994e72

…ty-value-no-unknown rule

ragini-pandey requested a review from a team as a code owner February 1, 2026 09:17

ragini-pandey changed the title ~~Add support for calc() and other math functions in declaration-proper…~~ Add support for calc() and other math functions in declaration-property-value-no-unknown rule Feb 1, 2026

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

622ae93

…alue

ragini-pandey and others added 2 commits February 4, 2026 10:52

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

9c3cfff

…alue

chore: trigger CI re-run

6a13879

ybiquitous changed the title ~~Add support for calc() and other math functions in declaration-property-value-no-unknown rule~~ Add calc support to declaration-property-value-no-unknown Feb 4, 2026

ybiquitous added 2 commits February 4, 2026 19:59

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

d58c57a

…alue

Add changeset

ec4f8bf

ybiquitous reviewed Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

ybiquitous requested changes Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

ybiquitous reviewed Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Show resolved Hide resolved

ybiquitous reviewed Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Show resolved Hide resolved

ybiquitous reviewed Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

ybiquitous reviewed Feb 4, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

ragini-pandey added 2 commits February 4, 2026 21:24

Add tests for calc() with incompatible types and nested math functions

28f2c78

Add test for calc() nested inside min() with type mix

5e14e2a

ragini-pandey requested a review from ybiquitous February 4, 2026 16:22

ybiquitous reviewed Feb 5, 2026

View reviewed changes

jeddy3 changed the title ~~Add calc support to declaration-property-value-no-unknown~~ Fix declaration-property-value-no-unknown false negatives for math functions Feb 5, 2026

jeddy3 reviewed Feb 5, 2026

View reviewed changes

.changeset/twelve-islands-help.md Outdated Show resolved Hide resolved

lib/rules/declaration-property-value-no-unknown/index.mjs Outdated Show resolved Hide resolved

ragini-pandey and others added 2 commits February 5, 2026 15:19

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

e555f3d

…alue

Fix false negatives for math functions in declaration-property-value-…

a26dd40

…no-unknown rule

ragini-pandey requested a review from ybiquitous February 5, 2026 11:57

Add tests for calc() with various math functions and type checks

8263775

ybiquitous reviewed Feb 5, 2026

View reviewed changes

lib/rules/declaration-property-value-no-unknown/__tests__/index.mjs Show resolved Hide resolved

Add tests for various calc() scenarios and improve error handling for…

025a87d

… invalid option types

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

4cae158

…alue

ragini-pandey requested review from jeddy3 and ybiquitous February 5, 2026 18:37

ybiquitous approved these changes Feb 6, 2026

View reviewed changes

Add tests for calc() and @Property declarations with various scenarios

6b5abd9

jeddy3 requested changes Feb 6, 2026

View reviewed changes

Refactor import statements and enhance math function handling in decl…

2086aec

…aration-property-value-no-unknown rule

ragini-pandey requested a review from jeddy3 February 6, 2026 18:28

Merge branch 'main' into fix/8891-calc-support-declaration-property-v…

c3d5e13

…alue

jeddy3 approved these changes Feb 8, 2026

View reviewed changes

jeddy3 merged commit 8ea57a9 into stylelint:main Feb 8, 2026
15 of 16 checks passed

romainmenke mentioned this pull request Feb 11, 2026

Fix declaration-property-value-no-unknown false negatives/positives for math functions #9064

Merged

	RejectedMessage<[property: string, value: string]> & {
	rejectedParseError: (property: string, value: string) => string;
	}

		import { mathFunctions } from '../../reference/functions.mjs';

		const { next: syntaxPatches } = syntaxPatchesJson;



	const HAS_MATH_FUNCTION = new RegExp(`\\b(?:${[...mathFunctions.values()].join('\|')})\\(`, 'i');

Uh oh!

Conversation

ragini-pandey commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue, if any, is this issue related to?

Is there anything in the PR that needs further explanation?

Changes

Examples

Uh oh!

changeset-bot bot commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ybiquitous left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ybiquitous commented Feb 4, 2026

Uh oh!

ybiquitous left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ybiquitous commented Feb 5, 2026

Uh oh!

ybiquitous left a comment

Choose a reason for hiding this comment

Uh oh!

jeddy3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ybiquitous commented Feb 5, 2026

Uh oh!

romainmenke commented Feb 5, 2026

Uh oh!

Uh oh!

ybiquitous commented Feb 5, 2026

Uh oh!

romainmenke commented Feb 5, 2026

Uh oh!

ragini-pandey commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ybiquitous left a comment

Choose a reason for hiding this comment

Uh oh!

jeddy3 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jeddy3 Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

ragini-pandey Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ragini-pandey commented Feb 6, 2026

Uh oh!

jeddy3 left a comment

Choose a reason for hiding this comment

Uh oh!

ragini-pandey commented Feb 8, 2026

codecov/patch — 96.55% of diff hit (target 97.99%)

Uh oh!

Uh oh!

jeddy3 commented Feb 8, 2026

Uh oh!

ragini-pandey commented Feb 1, 2026 •

edited

Loading

changeset-bot bot commented Feb 1, 2026 •

edited

Loading

github-actions bot commented Feb 4, 2026 •

edited

Loading

ragini-pandey commented Feb 5, 2026 •

edited

Loading

jeddy3 left a comment •

edited

Loading