fix: enforce strict syntax for `@charset` in no-invalid-at-rules by thecalamiity · Pull Request #192 · eslint/css

thecalamiity · 2025-07-07T17:27:56Z

Prerequisites checklist

I have read the contributing guidelines.

What is the purpose of this pull request?

To enforce strict syntax requirements for the @charset rule. This ensures that only valid @charset declarations are accepted.

What changes did you make? (Give an overview)

Updated the no-invalid-at-rules rule to strictly validate @charset syntax. Now enforces:
- The encoding must be enclosed in double quotes.
- There must be exactly one space after @charset.
- The rule must be immediately terminated with a semicolon.
Added tests to cover valid and invalid @charset usages.
Updated the documentation to note the strict requirements for @charset.

Related Issues

Fixes #185

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

Copilot

Pull Request Overview

This PR enhances the no-invalid-at-rules rule to strictly validate @charset declarations, ensuring they use double quotes, exactly one space, and terminate with a semicolon.

Introduced charsetPattern and validateCharsetRule to enforce syntax in the rule implementation
Added test cases covering valid and invalid @charset variations
Updated documentation to detail the strict requirements and examples

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/rules/no-invalid-at-rules.test.js	Added valid/invalid test cases for `@charset`
src/rules/no-invalid-at-rules.js	Implemented `validateCharsetRule` and regex check
docs/rules/no-invalid-at-rules.md	Added note and examples for strict `@charset`

Comments suppressed due to low confidence (1)

docs/rules/no-invalid-at-rules.md:75

[nitpick] Describing @charset as "not an at-rule" is misleading; consider rephrasing to clarify that it is a special at-rule requiring placement as the very first statement in a stylesheet.

Note on `@charset`: Although it begins with an `@` symbol, it is not an at-rule. It is a specific byte sequence of the following form:

nzakas

Overall, this looks really good. What do you think about adding autofix to this rule? It seems like it should possible to just reformat the @charset so that it's correct.

lumirlumir · 2025-07-17T14:19:30Z

ping @thecalamiity

Tanujkanti4441 · 2025-08-07T10:53:20Z

+		{
+			code: "@charset 'UTF-8';",
+			output: '@charset "UTF-8";',
+			errors: [
+				{
+					messageId: "invalidPrelude",
+					data: {
+						name: "charset",
+						prelude: "'UTF-8'",
+						expected: "<string>",
+					},
+					line: 1,
+					column: 10,
+					endLine: 1,
+					endColumn: 17,
+				},
+			],
+		},


In the case of a syntax error in @charset, the error message invalidPrelude seems incorrect, such as in this test, the message would be:

Invalid prelude ''UTF-8'' found for at-rule '@charset'. Expected '<string>'.

Here it says, <string> is expected to be used, which is already used here, but with wrong quotes.

And in the case of @charset "UTF-8", where a semicolon is missing, it has the same error message.

What do you think about adding an error message only to report syntax errors?

Are you suggesting that instead of reporting invalidPrelude, we should report a single, more general error for all these cases? Something like:

invalidCharsetSyntax: "Invalid @charset syntax. Expected: @charset \"<encoding-name>\"; (double quotes, exactly one space after @charset, and a semicolon at the end)."

Yes, but i feel this error message seems a bit descriptive; instead, we can just suggest the correct syntax, like for -
@charset "UTF-8" message can be something like this:

Invalid @charset syntax. Expected '@charset "UTF-8";'

Please feel free to choose the words that you find more accurate here.

Just updated the @charset error message - PTAL when you can.

snitin315 · 2025-08-09T09:54:01Z

+				end: {
+					line: loc.start.line,
+					column: loc.start.column + name.length + 1,


Should be end?

Suggested change

end: {

line: loc.start.line,

column: loc.start.column + name.length + 1,

end: {

line: loc.end.line,

column: loc.end.column + name.length + 1,

Using start is correct because we only want to highlight the at-rule name (@charset).

Shouldn't we report the whole node?

@charse "utf-8" ^^^^^^^^^^^^^^^ @charset ""; ^^^^^^^^^^^^

We report each issue individually rather than flagging the entire at-rule in one go.
For example, if the name is invalid we report unknownAtRule, and if the prelude is missing we report missingPrelude, etc.

snitin315 · 2025-08-09T09:56:32Z

+				const encoding =
+					preludeText.match(charsetEncodingPattern)?.[1] ?? "UTF-8";


Why do we need ?? "UTF-8"? In which case will we reach the right operand?

When the encoding is missing, e.g., @charset "";

Can we add this test case? empty string.

I’ve added a test for the empty string case and changed the behavior so we no longer autofix when the encoding is missing or whitespace-only. Previously we defaulted to "UTF-8", but I found this surprising since it guessed a value the user didn’t provide. Now it just reports the issue without autofixing. What do you think of this approach?

snitin315

LGTM, thanks! Leaving it open for 2nd review

nzakas

LGTM. Thanks.

fix: enforce strict syntax for @charset in no-invalid-at-rules

837497e

github-project-automation Bot added this to Triage Jul 7, 2025

eslint-github-bot Bot added the bug Something isn't working label Jul 7, 2025

github-project-automation Bot moved this to Needs Triage in Triage Jul 7, 2025

thecalamiity added 3 commits July 7, 2025 20:54

fix incorrect code example

c8f7753

fix CI failure

1045d30

fix CI failure

1d43501

nzakas requested a review from Copilot July 8, 2025 15:13

Copilot AI reviewed Jul 8, 2025

View reviewed changes

Comment thread src/rules/no-invalid-at-rules.js Outdated

nzakas reviewed Jul 8, 2025

View reviewed changes

nzakas moved this from Needs Triage to Implementing in Triage Jul 8, 2025

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

add autofix for @charset formatting issues

cc22870

Tanujkanti4441 reviewed Aug 7, 2025

View reviewed changes

improve @charset error messaging

00a2a3e

snitin315 reviewed Aug 9, 2025

View reviewed changes

avoid autofixing missing @charset encoding

d8d45fb

snitin315 approved these changes Aug 20, 2025

View reviewed changes

nzakas added the contributor pool label Aug 20, 2025

nzakas approved these changes Aug 20, 2025

View reviewed changes

nzakas merged commit 4d3d140 into eslint:main Aug 20, 2025
22 checks passed

github-project-automation Bot moved this from Implementing to Complete in Triage Aug 20, 2025

github-actions Bot mentioned this pull request Aug 19, 2025

chore: release 0.11.0 🚀 #202

Merged

		const encoding =
		preludeText.match(charsetEncodingPattern)?.[1] ?? "UTF-8";

Uh oh!

Conversation

thecalamiity commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

lumirlumir commented Jul 17, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thecalamiity Aug 7, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snitin315 Aug 10, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snitin315 left a comment

Choose a reason for hiding this comment

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

thecalamiity commented Jul 7, 2025 •

edited

Loading

thecalamiity Aug 7, 2025 •

edited

Loading

snitin315 Aug 10, 2025 •

edited

Loading