Prepare 16.0.0

[ybiquitous]

• Remove deprecated rules #6961
• Remove Node.js 14 support  #6740
• Move to ESM #5291
• Revert Node.js API returned resolved object change #7141
• Support ESM plugins #7327
• Support custom formatter for ESM #7267
• Support custom syntax for ESM #7269
• Deprecate CommonJS plugins #7340

Nice to have:

• Stabilise functional support for message option #6966
• Change default syntax behaviour to always use safe-parser with fix regardless of extension  #7116

I think it's a good time to start a discussion about the next major version.

Ref:

• Previous major version (Feb 2023): https://github.com/stylelint/stylelint/releases/tag/15.0.0
• Prepare 15.0.0 #6409
• future-major milestone

Please suggest other issues with a comment if you have any ideas.

[jeddy3]

I'm catching up on my notifications. Seeing all the releases and hard work done over the last few months is fantastic!

I think it's a good time to start a discussion about the next major version.

I agree, and with including #6740 & #5291.

Let's also remove the deprecated rules now that community plugins are available. One of the original motivations for deprecating the stylistic rules was to aid our migration to ESM, as those rules are the bulk of the oldest parts of our codebase.

@ybiquitous As an aside, do you have admin rights to recover my Stylelint 1password account? Something is up with my secret key.

[ybiquitous]

@jeddy3 Welcome back! 😄

I agree with removing the deprecated rules, and I just updated this issue description.

As an aside, do you have admin rights to recover my Stylelint 1password account? Something is up with my secret key.

Oh..., I don't have any admin access to 1password and am unsure about 1password details. 😓

[jeddy3]

I was able to get access myself via my old laptop. I've given you admin access in case you need it in the future.

[ybiquitous]

@jeddy3 Thanks. I can access it as an admin. 👍🏼

By the way, can I invite @mattxwang? He has recently performed releasing work many times (also today).
If he can access Twitter, we can leave releasing work to him completely.

[jeddy3]

By the way, can I invite @mattxwang?

Absolutely. You can invite him to the Team Member's group with access to the shared vault. @mattxwang Thanks for doing the recent releases. You're doing a fantastic job!

[ybiquitous]

@mattxwang I've sent an invitation to your email on your profile page. Can you check it, please?

[ybiquitous]

I've added #6966 to the "Discussing" list.

[mattxwang]

@mattxwang I've sent an invitation to your email on your profile page. Can you check it, please?

Thanks - just signed up with an account with my public email address!

[ybiquitous]

@mattxwang I've confirmed your account. Let me know if you're in trouble. 👍🏼

[mattxwang]

@ybiquitous should I have access to a shared vault? I don't see anything under my items in the UI.

[ybiquitous]

@mattxwang Oh, sorry! I forgot to assign you to the shared vault. 🙇🏼 Can you see it now?

[mattxwang]

Thanks @ybiquitous - it works now!

[mattxwang]

Sorry the permissions conversation got a bit off-target! To re-focus - I've started the removing deprecated rules process at #6979. @ybiquitous had a good suggestion of a v16 branch, so I've created one: https://github.com/stylelint/stylelint/tree/v16

[ybiquitous]

Thanks for creating the v16 branch, @mattxwang. 👍🏼

Reminder: we may need to regularly merge changes on main into v16 to reduce conflicts.

[jeddy3]

As the ball is rolling on this (#6979), I've converted the top post into a task list.

[Mouvedia]

concerning futur-major

• I also think that Fix multi-line double-slash command comments #5348 is low priority because it has an easy fix (using /* … */)
• Use exports field in package.json to forbid unexpected API usage #6258 would require someone to decide what we ought to expose based on the usage in the wild
• Change exit code for CLI flag error #4989 is a breaking change, but the status should be changed to needs investigation or needs clarification
• #​5042 may be added if we don't go the dual route (see rationale)

[mattxwang]

Sorry for being a bit MIA, my work at NEU ended up being a bit more consuming than I thought. I have a couple of weeks before instruction starts where I can get into the nitty gritty. What could I best help out with? I know @ybiquitous has been doing a great job with ESM migration - would you like more reviews there and/or me to help with the migration?

Alternatively, I could start doing the rest of #6966, which could be done (almost) completely asynchronously, and could in theory be folded into future v15 releases.

[ybiquitous]

@mattxwang Thanks for the proposal and help. Yes, I need more support and review for my ESM migration work. But, of course, you can take on tasks that you are interested in.

We need to migrate so many rules' codes to ESM, and tasks not directly related to ESM, like #6966, also remain. You're free to do any work. 😉

[ybiquitous]

I've just added #7141 to the task list on #6930 (comment).

[Mouvedia]

I think that we should remove some issues so that we can merge v16 sooner.
It has diverged way too much IMHO.

• can be postponed to 16.1+
  • Stabilise functional support for message option #6966: doesn't have to be finished, it's not a blocker
  • Use exports field in package.json to forbid unexpected API usage #6258: would be cool to have, but it's not a must have for the major
• are medium to low priority
  • Fix multi-line double-slash command comments #5348
  • Change default syntax behaviour to always use safe-parser with fix regardless of extension  #7116

That would leave us with only #5291 left; @ybiquitous is sure working hard towards its completion.
What do you think of dropping these 4 for now?

[ybiquitous]

https://github.com/stylelint/stylelint/releases/tag/16.0.0-2 is out! The main change is the addition of ESM plugin support (#7339).

[jeddy3]

I've begun migrating stylelint-scales to ESM to test our latest prerelease and to check if anything needs to be added to our migration guide for plugin authors. It was mostly smooth going, but there were a few oddities.

1. I followed the latest plugin example, and used this export structure:

rule.ruleName = ruleName;
rule.messages = messages;
rule.meta = meta;

export default createPlugin(ruleName, rule);

I now have to destructure the nested rule object in my tests:

- const { messages, ruleName } = require("..");
+ import rule from "../index.js";
+ const {
+  rule: { messages, ruleName },
+ } = rule;

Because it has this signature:

{
  ruleName: 'scales/alpha-values',
  rule: [Function: rule] {
    primaryOptionArray: true,
    ruleName: 'scales/alpha-values',
    messages: { expected: [Function (anonymous)] },
    meta: {
      url: 'https://github.com/jeddy3/stylelint-scales/blob/main/lib/rules/alpha-values/README.md',
      fixable: true
    }
  }
}

Does that nested structure look right? It seems off.

2. I was slightly thrown when setting up our Jest preset as I had to update the path.

- global.testRule = getTestRule({ plugins: ["./"] });
+ global.testRule = getTestRule({ plugins: ["./lib/index.js"] });

I assume this has something to do with change from main to exports:

{
-  "main": "lib/index.js",
+  "exports": "./lib/index.js",
}

Did I get something wrong? If not, we'll want to add something to the migration guide as part of #7340.

3. Lastly, Jest is tripping up on Windows and Node.js@18 on *nix.

*nix:

A jest worker process (pid=2039) was terminated by another process: signal=SIGSEGV, exitCode=null. Operating system logs may contain more information on why this occurred.

Windows:

D:\a\stylelint-scales\stylelint-scales\node_modules\.bin\jest:2
basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
          ^^^^^^^
SyntaxError: missing ) after argument list

@ybiquitous Did you encounter either of these when migrating the tests for Stylelint's built-in rules to ESM?

[ybiquitous]

@jeddy3 Thanks for trying. I answer them below.

1. I followed the latest plugin example, and used this export structure:

Yes, right. The previous code in CJS is incorrect:

module.exports = createPlugin(ruleName, rule);
module.exports.ruleName = ruleName;
module.exports.messages = messages;

should have been:

rule.ruleName = ruleName;
rule.messages = messages;
module.exports = createPlugin(ruleName, rule);

However, because the ruleName and messages have not been used in the user-facing area, I guess no problems would have occurred.

The new code in ESM is correct. 👌🏼

For your information, I share the following type definitions with 15.11.0 for a plugin and rule. They will not change with 16.0.0, too:

• stylelint/types/stylelint/index.d.ts

  Line 72 in 8914d46

  type Plugin = { default?: { ruleName: string; rule: Rule } } | { ruleName: string; rule: Rule };

• stylelint/types/stylelint/index.d.ts

  Lines 221 to 226 in 8914d46

  	type Rule<P = any, S = any> = RuleBase<P, S> & {
  	ruleName: string;
  	messages: RuleMessages;
  	primaryOptionArray?: boolean;
  	meta?: RuleMeta;
  	};

---

2. I was slightly thrown when setting up our Jest preset as I had to update the path.

The change to exports is correct. I agree with the addition to the migration guide. 👍🏼

3. Lastly, Jest is tripping up on Windows and Node.js@18 on *nix.

For the SIGSEGV error (segmentation fault), #7329 seems to be related, but I'm not 100% sure at this time. 🤔

And I'm unsure about the SyntaxError on Windows. I also will look into your plugin code.

[Mouvedia]

moved to #7340

## concerning 2.

Replace "main": "index.js" with "exports": "./index.js" in your package.json.

This should be removed. It's not necessary; it's equivalent but slightly less compatible with other tools that might only pick up main.

You should add a note saying that a dual ESM/CJS plugin that would target stylelint 14 and ≥15 would require both exports and main. The reason being #6477, which pushed the minimum node version above 13.
i.e. since exports was introduced in version 13 a plugin supporting only stylelint ≥15 would only require one or the other

[ybiquitous]

@Mouvedia For #6930 (comment), can you please comment on #7340 instead of here? There are so many comments already on this issue.

[newives]

May I ask when the official version will be released?

[ybiquitous]

I've just opened PR #7116 to address #7116. I believe it should be the last significant PR toward 16.0.0.

Although we don't have a specific plan, I hope to release 16.0.0 by the end of this year.

[firefoxic]

I may sound silly, but watching all the things you have to do for a dual module system makes me feel sorry for your efforts. It seems like it would be much easier for you to switch completely to pure ESM in version 16, and declare version 15 as LTS for a year (or two), which you maintain in a separate branch, releasing only patches with bug fixes, maybe one or two minor versions.

Although I feel sorry for the effort you've spent, because you'll remove it all in the next major version anyway, at the same time I admire the work you've done ♥️

[jeddy3]

I believe it should be the last significant PR toward 16.0.0.

Yes, I agree. We can put out another prerelease, do some more local testing and give the documentation the once over, and then I think we're about ready to release! 🚀

[newives]

Wow, great, looking forward to it 🎉

[newives]

@ybiquitous Thank you so much for your work, love you so much

[ybiquitous]

https://github.com/stylelint/stylelint/releases/tag/16.0.0-3 is out! Please try npm i stylelint@next. 🙏🏼

[firefoxic]

Is the idea of creating a testRule using node:test shelved for now?

[ybiquitous]

@firefoxic Thanks for the reminder. I've just created the repository, although it's still blank: https://github.com/stylelint/stylelint-test-rule-node. Please let us know if you want to contribute to the new package.

Ref #7340 (comment)

[firefoxic]

Please try npm i stylelint@next. 🙏🏼

I tried to use 16.0.0-3 in the plugin, and unexpectedly got failed tests for two rules. Here is an example of one of the fails (I left only the code itself: + expected and - received):

+:root { --foo: { color: red }; --bar: { color: blue }; --foo-bar: { color: blue }; --bar-foo: { color: red }; }
-:root { --foo: {; color: red }; --bar: {; color: blue }; --foo-bar: {; color: blue }; --bar-foo: {; color: red } }

Started looking into their history, and found the reason for adding exactly the tests that failed: #1806 and #1830.

Given that the @apply draft spec is abandoned (with no plans for revival), it seems I can safely remove anything related to custom property sets. But perhaps I'm missing something. Though that's hardly of interest to you, since that's not why you removed those rules 🤭

I'm more interested in why the fails happened only now. Having looked at the diff between 16.0.0-3 and 16.0.0-2 a bit, I haven't yet been able to figure out what affected them. And most importantly: in the code of 16.0.0-3 I could only find empty sets of custom properties (such as :root { --foo: {}; }), tests with them don't fail. So maybe this behavior is undesirable, and maybe you should be aware of it.

[ybiquitous]

@firefoxic Thanks a lot for the feedback. I'm also concerned about the change. Can you share where I can look into the failure? (tests on stylelint-stylistic/stylelint-stylistic#6 seems successful)

[firefoxic]

Can you share where I can look into the failure? (tests on firefoxic/stylelint-codeguide#6 seems successful)

Yeah, sure. Habit of not pushing until fixed 🤭

[firefoxic]

I could only find empty sets of custom properties (such as :root { --foo: {}; }), tests with them don't fail.

My assumption was wrong — it's not about an empty set, because there is one set that is not empty:

Warning

Careful with dark mode on!

Big and light screenshot

It's about the fix option, because the code breaks when you enable it.

And still, the question is relevant for me: why do we need code samples in tests with invalid CSS syntax and without specifying customSyntax? Maybe we should get rid of them altogether? Or at least move them to separate tests with the corresponding customSyntax?

[Mouvedia]

It's about the fix option, because the code breaks when you enable it.

That's probably 1e8517e#diff-5a796b3daf3cbd1194a107ee4510d9c802312af9c7487158cd203e6b3f92caf9R126
Can you try the commit before and confirm?

[firefoxic]

That's probably 1e8517e#diff-5a796b3daf3cbd1194a107ee4510d9c802312af9c7487158cd203e6b3f92caf9R126

Yes, it is.
And I consider it lucky that this commit highlighted (indirectly, through the plugin) the presence of non-standard syntax in Stylelint's tests. I think it doesn't belong there. But you know better 🙂

[firefoxic]

If node@14 is no longer supported, maybe fix this deprecated flag too?

stylelint/.husky/pre-commit

Line 6 in a83af3e

npx --no-install lint-staged

And by the way, have you considered switching to pnpm?

[ybiquitous]

@firefoxic

If node@14 is no longer supported, maybe fix this deprecated flag too?

Good catch. Can you open PR to change the flag if you have time?

have you considered switching to pnpm?

As I remember, there are no issues, but a related one is #6298. You can freely open an issue to suggest pnpm if you have a strong opinion.

[Mouvedia]

@firefoxic #6930 (comment) is not a blocker for v16?

[firefoxic]

Not anymore. I removed those tests with non-standard syntax from the plugin. If such tests don't fail in Stylelint, it's probably not critical.