Fix inconsistent types

[adalinesimonian]

@types/stylelint is poorly synchronized with the stylelint package, which is why the VS Code extension uses a script to pull down the types from the Stylelint repository (which is hackish in and of itself). However, even these type definitions are structured oddly and have some inconsistencies.

Ideally, if these inconsistencies are resolved, it would be optimal to have the Stylelint package provide its own type definitions in-package using "types": "types/stylelint/index.d.ts", which entirely avoids the problem of keeping in sync with @types/stylelint and ensures consistent typings in the Stylelint repository and downstream.

Here are a few of the issues that I've encountered downstream in the VS Code extension:

test/lib/warnings-to-diagnostics/test.js:

Also in test/workspace/rule-doc/test-plugin.js

const { lint } = /** @type {import('stylelint').StylelintPublicAPI} */ (require('stylelint'));

• Required because lint is not defined on the stylelint module. const { lint } = require('stylelint'); results in a Property 'lint' does not exist on type 'typeof import("stylelint")'.ts(2339) error. Having the private and public API being defined as types on the module instead of a namespace export is atypical.

  Changing this may mean that the same types can be consumed both by Stylelint itself and downstream, unblocking the option of exposing types in package.json.

• StylelintPublicAPI.lint has the type Function, which means that its return value is not typed and is not subject to type-checking without manually typing its return value. But doing that would mean that if its return type changed, the change would go unnoticed by Typescript.

test/workspace/lint/stylelint.config.js:

// TODO: Workaround for bad typings upstream
/** @type {StylelintConfig & { overrides: StylelintConfig }} */
const config = {
	// ...
	overrides: [
		// ...
		{
			files: ['**/*.scss'],
			// Workaround necessary for the following line
			customSyntax: 'postcss-scss',
		},
	],
};

StylelintConfigOverride has a very limited number of properties that are allowed, even though the override implementation allows almost every property (as far as I can tell from digging through the code). In this case, customSyntax isn't allowed by the types even though it's allowed by Stylelint, hence the workaround. Otherwise the customSyntax property results in the error:

Type '{ files: string[]; customSyntax: string; }' is not assignable to type 'StylelintConfigOverride'.
  Object literal may only specify known properties, and 'customSyntax' does not exist in type 'StylelintConfigOverride'.ts(2322)

Instead of it being defined with Pick<...>, it may make more sense to define it with Omit<...> and block the properties that aren't supported. This would also mean the type wouldn't need to be manually updated anytime a new configuration property is added.

test/workspace/rule-doc/test-plugin.js:

module.exports = stylelint.createPlugin(
	ruleName,
	// TODO: Workaround for bad typings upstream
	/** @type {import('stylelint').StylelintRule} */ (
		/** @type {unknown} */ (
			(/** @type {any} */ primaryOption) => {
				return (
					/** @type {PostCSSRoot} */ postcssRoot,
					/** @type {PostCSSResult} */ postcssResult,
				) => {
					const validOptions = stylelint.utils.validateOptions(postcssResult, ruleName, {
						actual: primaryOption,
					});

					if (!validOptions) {
						return;
					}

					stylelint.utils.report({
						ruleName,
						result: postcssResult,
						message: messages.expected,
						node: postcssRoot,
						index: 5,
					});
				};
			}
		)
	),
);

This workaround is necessary because the StylelintRule type expects specific properties added to the function, even though createPlugin doesn't require these properties, whether in the implementation or in the documentation. Without this type conversion Typescript throws the error:

Argument of type '(primaryOption: any) => (postcssRoot: PostCSSRoot, postcssResult: PostCSSResult) => void' is not assignable to parameter of type 'StylelintRule<any, any>'.
  Type '(primaryOption: any) => (postcssRoot: Root, postcssResult: PostcssResult) => void' is missing the following properties from type '{ ruleName: string; messages: StylelintRuleMessages; primaryOptionArray?: boolean | undefined; }': ruleName, messagests(2345)

Perhaps these properties are indeed necessary somewhere else in the codebase that I'm unaware of. In that event, it shouldn't be the exact same type that's used in createPlugin. Otherwise, if they are not required anywhere, they should be made optional.

---

Let me know if I've missed any context!

[hudochenkov]

Improvement to types are always welcome.

We also have an issue open for creating TypeScript definitions #4399

[adalinesimonian]

Glad to hear it! I just submitted a PR for discussion that resolves all the problems outlined in this issue: #5582.