Add support to checkAgainstRule with custom rules

[aaronccasanova]

What is the problem you're trying to solve?

Currently, the checkAgainstRule utility only resolves built-in rules. However, my team has a use case in which we'd like to call checkAgainstRule with other (local) custom rules e.g.

// config
module.exports = {
  plugins: ['./rules/main-rule', './rules/custom-rule-1', './rules/custom-rule-2'],
  rules: { 'scope/main-rule': settings },
}
// main-rule.js
module.exports = createPlugin(ruleName, (primary) => {
  return (root, result) => {
    stylelint.utils.checkAgainstRule({
      ruleName: 'scope/custom-rule-1', // Error: Rule 'scope/custom-rule-1' does not exist
      ruleSettings: customSettings,
    })
  }
})

What solution would you like to see?

We'd like to be able to use checkAgainstRule with (local) custom rules. Being that all pluginFunctions are accessible on result.stylelint.config.pluginFunctions, this update seems like it would be a non-breaking change by optionally passing the result object to checkAgainstRule e.g.

// main-rule.js
module.exports = createPlugin(ruleName, (primary) => {
  return (root, result) => {
    stylelint.utils.checkAgainstRule({
      result,
      ruleName: 'scope/custom-rule-1', // Resolves and checks against custom rules
      ruleSettings: customSettings,
    })
  }
}

// stylelint/checkAgainstRule.js
const rule = options.result.stylelint.config?.pluginFunctions[options.ruleName] || rules[options.ruleName];

if (!rule) throw new Error(`Rule '${options.ruleName}' does not exist`);

[ybiquitous]

@aaronccasanova Thanks for the proposal. The idea sounds good to me.

It seems no breaking to add a new optional property to the options parameter of checkAgainstRule() like this:

	checkAgainstRule: <T, O extends Object>(
-		options: { ruleName: string; ruleSettings: ConfigRuleSettings<T, O>; root: PostCSS.Root },
+		options: { ruleName: string; ruleSettings: ConfigRuleSettings<T, O>; root: PostCSS.Root, result?: PostcssResult },
 		callback: (warning: PostCSS.Warning) => void,
 	) => void;

But just in case, I've marked this issue as needs discussion to see whether this feature would affect our ecosystem. We could implement the idea if there were no objections or concerns.

[ybiquitous]

Since it seems there are no objections, I've labeled the issue as ready to implement. Please consider contributing if you have time.

[aaronccasanova]

Great! I'll start working on the implementation 👍