stylelint: correct several interfaces

[43081j]

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change. (Run with npm test.)
• Follow the advice from the readme.
• Avoid common mistakes.
• Run npm run lint package-name (or tsc if no tslint.json is present).
• Provide a URL to documentation or source code which provides context for the suggested changes: https://stylelint.io/developer-guide/plugins/
• Increase the version number in the header if appropriate.
• If you are making substantial changes, consider adding a tslint.json containing { "extends": "dtslint/dt.json" }.

---

A few of the types were wrong.

Here's what has been done:

• Introduce postcss types to replace a few any (postcss is already a whitelisted dep in types-publisher)
• Add the unix formatter
• Use Partial for linter configuration (its a bad idea to have a fully optional interface)
• Replace the invalid JSON type (which actually refers to JSON.parse etc) with a new stylelint configuration interface
• Introduce a couple of missing options
• Change ignorePath to a string (it is)
• Remove postcssResults from linter results (stylelint's docs say this exists, however it does not exist anywhere in their source anymore. I guess it is better to not expose a non-existent thing rather than follow the probably-outdated documentation)
• Fix createPlugin which had the wrong interface (two params, to include the primary option)
• Add createRuleTester
• Add Plugin interface

You can see more about these things here:
https://stylelint.io/developer-guide/plugins/

However, many of the changes were found by digging through stylelint's docs and much of their source in the spare hour I had.

[typescript-bot]

@43081j Thank you for submitting this PR!

🔔 @alan-agius4 @filipsalpe - please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

If no reviewer appears after a week, a DefinitelyTyped maintainer will review the PR instead.

[43081j]

alright this should be right now.

This is a breaking change so i would like to bump the version (and should) but it means it won't match with stylelint's anymore. What do people suggest? RuleOption has been renamed (and removed from plugins) because it was plain wrong in the previous type definitions.

because the types were so wrong to begin with, it could be more tolerable to push this breaking change as a minor bump but i'd still rather not if its a popular package.

[typescript-bot]

After 5 days, no one has reviewed the PR 😞. A maintainer will be reviewing the PR in the next few days and will either merge it or request revisions. Thank you for your patience!

[sheetalkamat]

@43081j Please refer to https://github.com/DefinitelyTyped/DefinitelyTyped#if-a-library-is-updated-to-a-new-major-version-with-breaking-changes-how-should-i-update-its-type-declaration-package to see how to update the version for breaking change.

[43081j]

Yup I'm aware. I have been waiting for someone to review the changes first is all.

I will bump the major version tomorrow. This will put the version out of sync with stylelint. Which is another reason I hadn't yet, as mentioned in my original post.

Note that it is indeed the right thing to do, just an observation about the divergence.

[43081j]

@sheetalkamat bumped the major version. it is now out of sync with stylelint's version but seems the right thing to do.

[alan-agius4]

The major version bump is incorrect there is no such version of stylelint

[alan-agius4]

There is no such stylelint version.

[sheetalkamat]

@sandersn This is correct change? The change is breaking change but library hasn't moved to new version

[sandersn]

I vote for an existing minor version, such as 9.5.

[43081j]

There doesn't need to be AFAIK @alan-agius4

The docs specify:

Sometimes type declaration package versions and library package versions can get out of sync.

The correct way ahead here is one of two, depending on the situation (and information i don't have on hand):

• If the types aren't so widely used we keep the same version aligned to stylelint its self
• If the types are used by many we have no choice but to bump the major version as this is indeed a breaking change to the types

You cannot break/avoid semver just to keep a version in sync with the package it provides types for. This would introduce breaking type changes into peoples builds with a minor version (or by your train of thought, a patch version, even worse).

The reason for this unfortunately is because the original types were wrong (enough that a "clean up" is a breaking change, so, quite...).

someone like @sandersn might be able to offer some advice here

[43081j]

also im still in dire need of a code review on this. i barely use stylelint and went through the sources for a few hours to get this right, so im fairly sure its right but also could do with someone trying it out in a real use case.

it now matches up with whats in stylelint's docs and sources (and in fact i opened 3 issues at stylelint because their docs are wrong). so it should be fine and is definitely better than before

[typescript-bot]

@43081j One or more reviewers has requested changes. Please address their comments. I'll be back once they sign off or you've pushed new commits or comments. Thank you!

[sandersn]

Well, it's a tradeoff between breaking old users — not bumping major — and confusing new users — creating types for a future version that may itself have different types.

Personally, I think the right compromise would be to bump the minor version so that things may break for old users, but hopefully in an obvious way. People who care about compatibility should have locked their dependencies anyway. And it make @types/stylelint easier to understand, both now and in the future when styleline@10 is available.

[sandersn]

I vote for an existing minor version, such as 9.5.

[43081j]

@sandersn WDYT about just matching the latest stylelint version? 9.10

to be honest the whole "matching up of versions" causes great headaches. I've lost count of the number of times i've seen someone ship a breaking change under a patch shamelessly because they think its more important to avoid divergence. I wish things were different.

[sandersn]

@43081j given the current situation, 9.10 seems like the best idea.

[43081j]

@sandersn sorted.

is it worth opening an issue for discussion somewhere (if there's an appropriate place)? as this situation seems to happen relatively often

[sandersn]

The new code seems structurally reasonable but I haven't checked it against the source.

[sandersn]

@43081j I know the DT issue tracker is awash with ignored issues, but if you open an issue there and assign (or tag) me, @RyanCavanaugh and @rbuckton we are the three people who spend time thinking about Typescript + DT versioning. We can discuss there.