Fix developer experience for non-standard syntax in *-no-unknown

[GoldsteinE]

Clearly describe the bug

stylelint -s scss reports @each and @if as unknown rules

Which rule, if any, is the bug related to?

at-rule-no-unknown

What code is needed to reproduce the bug?

@if true {
  .test {
    display: block;
  }
}

What stylelint configuration is needed to reproduce the bug?

"use strict";

module.exports = {
  rules: {
    "at-rule-no-unknown": true,
  }
};

Which version of stylelint are you using?

13.7.0

How are you running stylelint: CLI, PostCSS plugin, Node.js API?

CLI with stylelint -s scss test.scss

Does the bug relate to non-standard syntax (e.g. SCSS, Less etc.)?

Yes, it's related to SCSS at-rules

What did you expect to happen?

No warnings to be flagged.

What actually happened (e.g. what warnings or errors did you get)?

The following warnings were flagged:

test.scss
 1:1  ✖  Unexpected unknown at-rule "@if"   at-rule-no-unknown

[hudochenkov]

From rule description:

This rule considers at-rules defined in the CSS Specifications, up to and including Editor's Drafts, to be known.

I would suggest using scss/at-rule-no-unknown from stylelint-scss instead of core at-rule-no-unknown.

---

@stylelint/contributors I think we can improve developer experience here. It's a common issue, when developers, who lint Sass files get to this problem (#3293, #3190, #2952). Documentation update it's not enough, because people might setup stylelint and use stylelint-config-standard without configuring any rule and then get this warning.

I propose to add suggestion to use scss/at-rule-no-unknown in violation text if violation happens for Sass files:

test.scss
 1:1  ✖  Unexpected unknown at-rule "@if". You probably want to use "scss/at-rule-no-unknown" from stylelint-scss plugin instead of core "at-rule-no-unknown" rule   at-rule-no-unknown

Copy should be refined, probably. @jeddy3 is good with that :)

[nosilleg]

If this was ESLint I would have said "Use the overrides key to disable at-rule-no-unknown and enable scss/at-rule-no-unknown for *.scss files"

Even if we implement the overrides key for stylelint we're still left with the "problem" of the scss/at-rule-no-unknown being part of the external stylelint-scss plugin instead of a stylelint-org supported package. For me having references/config pointing to non-stylelint-org config isn't the "right™" thing to do.

Documentation saying that stylelint-config-standard and all core rules are only approved for *.css files is better in my eyes.

I would certainly implement it with overrides in something that wasn't stylelint-org code as stylelint-config-standard is.

An obvious way around my comments would be to adopt stylelint-scss as part of the stylelint project, and therefore stylelint-config-standard could use it in comments or overrides without relying on external dependencies.

These are my initial thoughts, but I wouldn't protest if @hudochenkov merged his solution.

[ybiquitous]

I agree with the idea of @hudochenkov:

I think we can improve developer experience here.

But currently, I think we would be hard to:

adopt stylelint-scss as part of the stylelint project

Because the adoption might increase the core project's code and our maintenance cost.
(EDIT: the latter quotation is from @nosilleg)

So, I propose a compromise: to copy the scss/at-rule-no-unknown and scss/comment-no-empty rules into the stylelint project. I have 2 reasons for my propose:

1. Both rules' implementations are strongly related to the core rules: at-rule-no-unknown and comment-no-empty.
2. Both rules' implementations are not so difficult, so copying would be expected not to increase the maintenance cost so much.

Note that I have opened the 3 pull requests about the 2 rules (but not merged sadly... 😢 ):

• Fix duplicate rule names in at-rule-no-unknown message stylelint-scss/stylelint-scss#481
• Describe core rule comment-no-empty stylelint-scss/stylelint-scss#483
• Unify messages for comment-no-empty and scss/comment-no-empty stylelint-scss/stylelint-scss#484

What do you think?

[nosilleg]

@ybiquitous I completely agree that we should be trying to improve the developer experience where we can.

adopt stylelint-scss as part of the stylelint project

Because the adoption might increase the core project's code and our maintenance cost.

I completely agree with this as well. We don't want to overburden the limited resources of the core team. (aside: if we don't think stylelint-scss is actively maintained then maybe we shouldn't specifically direct users to use it. Or if it is actively maintained then maybe the burden wouldn't be too much?)

So, I propose a compromise: to copy the scss/at-rule-no-unknown and scss/comment-no-empty rules into the stylelint project.

How would these be integrated? Two options I can think of right now:

1. These could become core rules. This doesn't sit well in my mind. It means that not only is stylelint-org supporting a different source type than css, but we'd be supporting it in core. This is the opposite direction that ESLint & Prettier are taking at the moment, which is to externalize code that isn't exceptionally core.

2. We could have a stylelint-org maintained stylelint-scss-mini repo, that is a stripped down stylelint-scss and use it in stylelint-config-standard.

For me both of these cause concern for users who want to use stylelint-config-standard and stylelint-scss full at the same time. I would assume that they would need to disable the core/stylelint-scss-mini checks that were covered by styleline-scss, or they would get duplicates.

I think so far we have four not-mutually-exclusive options:

1. Update the documentation to say that the core rules are for css syntax only, and if use use something else to see https://github.com/stylelint/awesome-stylelint for next steps.

2. Make references to specific external libraries in the documentation and/or log output.

3. Adopt stylelint-scss into stylelint-org so that references are not external to stylelint-org.

4. Partially adopt stylelint-scss and potentially blur the line of what is core, or have potential issues between stylelint-org code that minimally supports scss, and packages that attempt to fully support scss.

Please don't take the above as gospel, I'd like feedback. I'm sure there are things I haven't thought of, or different ways of thinking about things that I have considered.

[ybiquitous]

@nosilleg Thank you for clarifying the problems!

I also think we need more discussion and feedback about this issue.

[jeddy3]

Yes, I think we can improve the DX here.

@nosilleg Thanks for pulling together the proposals.

This is the opposite direction that ESLint & Prettier are taking at the moment, which is to externalize code that isn't exceptionally core.

I agree. I think stylelint should be for CSS while being extensible by the community for other styling dialects. For example, I imagine in the future an external stylelint-config-standard-scss package that brings together the postcss-scss parser and the stylelint-scss plugin pack, much like the Vue config for ESlint does.

With that in mind and to the problem at hand, I suggest we make tweaks to both the docs and violation message to see if that reduces how often this comes up.

We can:

• add "to the CSS specifications" to the violation messages of the *-no-unknown rules, e.g. 'Unexpected unknown to the CSS specifications at-rule "@if"'
• add a link to scss/at-rule-no-known from the at-rule-no-unknown README, e.g. "This rule considers at-rules defined in the CSS Specifications, up to and including Editor's Drafts, to be known. If you're writing SCSS, you may want to use the related rule from the stylelint-scss plugin pack instead."
• emphasise that the "Getting Started" steps are for when you're writing CSS, and better signpost the "Customize" section which suggests using a SCSS specific config if you're writing SCSS.

I think that'll improve the DX while keeping the built-in rules (and the code of their violation messages) focused on CSS.

[jeddy3]

As there are no objections to the above proposal. I'll label this ready to implement.

Please consider contributing if you have time.

[Airkro]

@jeddy3

I think this is the same view: #4122

[jeddy3]

Docs were improved for 14.0.0 release.