Add support for meta.url to enable links in terminal

[ybiquitous]

What is the problem you're trying to solve?

As discussed with #2622, I think it is very useful if stylelint rules (including plugins) could have metadata with doc URL, deprecated, etc. like ESLint.

For example, use cases:

• Tools or plugins like stylelint-find-rules
• Create rule links on a terminal (see Add links to terminal output #5835)
• Generate a simple document for rules
• and so on...

Actually, we had metadata with the deprecated property:

stylelint/lib/rules/at-rule-blacklist/index.js

Line 62 in 16b4595

rule.meta = { deprecated: true };

Also, the Stylelint document below has described rule metadata:

stylelint/docs/developer-guide/rules.md

Line 198 in 9e75552

2. Add the appropriate meta data to mark the rule as deprecated.

What solution would you like to see?

I propose to define a metadata schema via the document and type definitions (TypeScript).

For example of a rule with metadata:

// lib/rules/color-no-invalid-hex/index.js
rule.ruleName = ruleName;
rule.messages = messages;

rule.meta = {
  type: 'problem', // or 'convention' etc.
  docs: {
    description: 'Disallow invalid hex colors.',
    url: 'https://stylelint.io/user-guide/rules/list/color-no-invalid-hex',
  },
  deprecated: false,
  fixable: true,
  schema: [
    { type: 'boolean' }, // primary
  ],
};

module.exports = rule;

For the Rule type of the TypeScript definitions, we would add a meta property:

stylelint/types/stylelint/index.d.ts

Lines 154 to 164 in 9e75552

	export type RuleBase<P = any, S = any> = (
	primaryOption: P,
	secondaryOptions: Record<string, S>,
	context: PluginContext,
	) => (root: PostCSS.Root, result: PostcssResult) => Promise<void> | void;
	export type Rule<P = any, S = any> = RuleBase<P, S> & {
	ruleName: string;
	messages: RuleMessages;
	primaryOptionArray?: boolean;
	};

[jeddy3]

SGTM. I suggest we start with meta.url so that plugins can opt into the terminal links. We can open up follow up issues for other properties as we need them / want to work on them.

Should we explicitly define the URL for the built-in rules or continue to build it from the rule name?

[ybiquitous]

@jeddy3 Thanks for the feedback!

I agree with the small start to add meta.url. 👍🏼

And, I think it better to "explicitly define the URL for the built-in rules" like ESLint does. It is straightforward and doesn't require any extra build steps.

[jeddy3]

Labelled as ready.

Let's include updating the plugin docs as part of the pull request.