feat: add stylelint v17 support

[zalishchuk]

Note

This PR was created with assistance from Claude. Please review thoroughly.

Summary

Add support for stylelint v17, which removed CommonJS support and is now ESM-only.

This PR uses dynamic import() to load stylelint, enabling support for ESM-only stylelint v17 while maintaining backward compatibility with v13-v16.

Closes #376

Technical notes

• tsconfig.json adds skipLibCheck: true because stylelint v17's type definitions import GlobbyOptions from globby, but globby v16 exports Options instead
• Tests use stylelintPath option instead of jest.mock() because Jest's module mocking doesn't intercept dynamic import() calls in CommonJS context. I investigated jest.unstable_mockModule() which does work, but it requires running Jest in native ESM mode (--experimental-vm-modules) which would require adding .js extensions to all test utility imports. Using stylelintPath is more practical - it uses stable APIs and tests a real plugin feature.

What kind of change does this PR introduce?

feat (new feature)

Did you add tests for your changes?

Yes. All 55 existing tests pass. Tests were updated to use the stylelintPath option for mocking instead of jest.mock(), since Jest's module mocking doesn't work reliably with dynamic import().

Does this PR introduce a breaking change?

Yes. Minimum Node.js version is now 20.19.0 (required by stylelint v17).

If relevant, what needs to be documented once your changes are merged or what have you already documented?

• Updated README.md to document the Node.js >= 20.19.0 requirement
• Bumped peer dependencies to include stylelint ^17.0.0
• Bumped engines to node >= 20.19.0
• Should bump to major version (v6.0.0) due to breaking Node.js requirement
• CHANGELOG should document the breaking change and migration path

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: ricardogobbosouza / name: Ricardo Gobbo de Souza (4807e56)
• ✅ login: zalishchuk / name: Alexander (00de567, 4744f0e, 4879edd, 570df41, a601e68)

[alexander-akait]

Please remove this

[zalishchuk]

Done

[zalishchuk]

@alexander-akait How should we handle this error?

Error: node_modules/stylelint/types/stylelint/index.d.ts(2,15): error TS2305: Module '"globby"' has no exported member 'GlobbyOptions'.
Error: node_modules/stylelint/types/stylelint/index.d.ts(2,36): error TS1541: Type-only import of an ECMAScript module from a CommonJS module must have a 'resolution-mode' attribute.
ERROR: "build:types" exited with 1.```

[zalishchuk]

Note that stylelint itself uses skipLibCheck: true in their tsconfig as of stylelint/stylelint#8875

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[alexander-akait]

@ricardogobbosouza Can you look at this too?

[zalishchuk]

stylelint/stylelint#8992
stylelint/stylelint#8991

[ricardogobbosouza]

@ricardogobbosouza Can you look at this too?

It seems good..

[ricardogobbosouza]

stylelint/stylelint#8992 stylelint/stylelint#8991

Waiting for this typing problem in styelint version 17

[alexander-akait]

Yeah, let's wait a fix from stylelint team

[zalishchuk]

@ricardogobbosouza @alexander-akait stylelint/stylelint#9007
I've updated the stylelint version, but it was still throwing a TypeScript error:

node_modules/stylelint/types/stylelint/index.d.ts:2:47 - error TS1541: Type-only import of an ECMAScript module from a CommonJS module must have a 'resolution-mode' attribute.

2 import type { Options as GlobbyOptions } from 'globby';
                                                ~~~~~~~~
                                                
Found 1 error in node_modules/stylelint/types/stylelint/index.d.ts:2

Updated the tsconfig.json to use "module": "nodenext",

[alexander-akait]

@ricardogobbosouza Can you review code and make a release when you will have time, thank you

[zalishchuk]

Previously, require() was used to load stylelint, which would immediately throw an error if the module was broken or missing, necessitating try/catch for error handling.

Now, with import(), stylelint loads lazily, and the setup() function only stores the path as a string without loading the module. The try/catch can no longer catch such errors.

Load errors are still managed as they propagate through the .catch() of lintFiles() and are reported via compilation.errors.

[yoyo837]

Should we also add Stylelint 17 to the CI matrix for Node.js 20/22/24?

[ricardogobbosouza]

Thanks @zalishchuk