Add rule metadata to public API

[ybiquitous]

What is the problem you're trying to solve?

I want to write a custom formatter with rule metadata (e.g. rule doc URL), but now there is no way to use easily rule metadata.

For example, the built-in verbose formatter uses an internal API (_postcssResult):

stylelint/lib/formatters/verboseFormatter.js

Lines 109 to 119 in ece68bc

	function ruleMetadata(results) {
	const firstResult = results[0];
	return (
	(firstResult &&
	firstResult._postcssResult &&
	firstResult._postcssResult.stylelint &&
	firstResult._postcssResult.stylelint.ruleMetadata) ||
	{}
	);
	}

I want to use a public API for this purpose.

What solution would you like to see?

I think that the simplest way is to add a property for rule metadata to LinterResult (used as the second argument of Formatter). See the relevant type definitions:

Formatter:

stylelint/types/stylelint/index.d.ts

Line 129 in ece68bc

export type Formatter = (results: LintResult[], returnValue?: LinterResult) => string;

NOTE: It looks possible to change returnValue?: LinterResult (optional) to returnValue: LinterResult (required).

LinterResult:

stylelint/types/stylelint/index.d.ts

Lines 311 to 328 in ece68bc

	export type LinterResult = {
	/**
	* The working directory from which the linter was run when the
	* results were generated.
	*/
	cwd: string;
	results: LintResult[];
	errored: boolean;
	output: any;
	maxWarningsExceeded?: {
	maxWarnings: number;
	foundWarnings: number;
	};
	reportedDisables: DisableOptionsReport;
	descriptionlessDisables?: DisableOptionsReport;
	needlessDisables?: DisableOptionsReport;
	invalidScopeDisables?: DisableOptionsReport;
	};

The use of LinterResult on the public API:

stylelint/types/stylelint/index.d.ts

Lines 367 to 372 in ece68bc

	export type PublicApi = PostCSS.PluginCreator<PostcssPluginOptions> & {
	/**
	* Runs stylelint with the given options and returns a Promise that
	* resolves to the results.
	*/
	lint: (options: LinterOptions) => Promise<LinterResult>;

If you know of a better way, please let me know.

[jeddy3]

I think that the simplest way is to add a property for rule metadata to LinterResult (used as the second argument of Formatter).

SGTM. Labelled as ready to implement.