Fix URL metadata for plugins

[Reda011]

What steps are needed to reproduce the bug?

I reproduced the question in many Plugins Libraries, such as stylelint-z-index-value-constraint、stylelint-scss and so on.

Next, take stylelint-scss as an example：

step1:
npm i stylelint-scss in my project;

step2:
creat an test file called test.less;

fill it with：(from stylelint-scss/ selector-no-redundant-nesting-selector's testFile)
called test.less
step3:
.stylelintrc.js

module.exports = { plugins: [ "stylelint-scss", ], rules: { "scss/selector-no-redundant-nesting-selector": true, }, };
step4:
it give me error tips: 'Unnecessary nesting selector (&) (scss/selector-no-redundant-nesting-selector)Stylelint(scss/selector-no-redundant-nesting-selector)'

But, Stylelint(scss/selector-no-redundant-nesting-selector) had no url.

What Stylelint configuration is needed to reproduce the bug?

module.exports = {
plugins: [
"stylelint-scss",
],
rules: {
"scss/selector-no-redundant-nesting-selector": true,
},
};

How did you run Stylelint?

cli

Which version of Stylelint are you using?

"stylelint": "^14.9.1","stylelint-scss": "^4.3.0"

What did you expect to happen?

I click the error tips "...Stylelint(scss/selector-no-redundant-nesting-selector)"

and I can open the web URL which was set in the library.

What actually happened?

I clicked and I can‘t open the web Url which was set in the library.

Does the bug relate to non-standard syntax?

No response

Proposal to fix the bug

No response

[ybiquitous]

@Reda011 Thanks for opening the issue and using the template.

This behavior seems to be due to the mismatch between our doc and code on exporting rules.

The doc instructs using multiple module.exports,

stylelint/docs/developer-guide/plugins.md

Lines 53 to 55 in e424be5

	module.exports.ruleName = ruleName;
	module.exports.messages = messages;
	module.exports.meta = meta;

but the built-in rules are using a single module.exports:

stylelint/lib/rules/alpha-value-notation/index.js

Lines 203 to 206 in e424be5

	rule.ruleName = ruleName;
	rule.messages = messages;
	rule.meta = meta;
	module.exports = rule;

I think we should make it work in both cases. Maybe, we may need to fix the following code:

stylelint/lib/lintPostcssResult.js

Line 100 in b013ac0

postcssResult.stylelint.ruleMetadata[ruleName] = ruleFunction.meta || {};

---

I've labeled the issue as ready to implement. Please consider contributing if you have time.

There are steps on how to fix a bug in a rule in the Developer guide.

[Reda011]

I checked these Plugins' Libraries, but it doesn't work even using a single module.exports:

stylelint-scss/selector-no-redundant-nesting-selector

Is there any other possibility?

[ybiquitous]

@Reda011 Umm..., it seems the stylelint-scss plugin works 🤔
(verbose formatter can show a link to meta.url)

$ cat package.json
{
  "dependencies": {
    "stylelint": "14.9.1",
    "stylelint-config-recommended-scss": "7.0.0"
  },
  "stylelint": {
    "extends": "stylelint-config-recommended-scss"
  },
  "scripts": {
    "test": "stylelint \"*.{css,scss}\" -f verbose"
  }
}

$ cat a.scss
@foo{}

$ npm it
...
a.scss
 1:1  ✖  Unexpected unknown at-rule "@foo"  scss/at-rule-no-unknown
 1:5  ✖  Unexpected empty block             block-no-empty

1 source checked
 /Users/koba/tmp/foo/a.scss

2 problems found
 severity level "error": 2
  scss/at-rule-no-unknown: 1
  block-no-empty: 1
...

[Reda011]

uh, I created a new project to test this, looks like it still doesn't work:

Is it related to my environment?

[ybiquitous]

Maybe, some IDEs like VSCode may not support terminal links. See the code of the verbose formatter:

stylelint/lib/formatters/verboseFormatter.js

Lines 138 to 144 in 0bd6976

	function ruleLink(rule, metadata) {
	if (metadata && metadata.url) {
	return terminalLink(rule, metadata.url);
	}
	return rule;
	}

stylelint/lib/formatters/terminalLink.js

Lines 8 to 15 in 0bd6976

	/**
	* @see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
	*
	* @param {string} text
	* @param {string} url
	* @returns {string}
	*/
	module.exports = function terminalLink(text, url) {

See also Hyperlinks in Terminal Emulators

[Reda011]

Look this, I got these messages without terminal command but automatic verification：

block-no-empty is a rule, it worked;

selector-no-redundant-nesting-selector and at-rule-no-unknown are plugins of stylelint-scss, they didn't work.

[ybiquitous]

I'm not sure, but it seems a problem with the VSCode extension... 🤔

https://github.com/stylelint/vscode-stylelint/blob/d38b5db38debc59e4a00fdb73716202b4b43e38b/src/utils/stylelint/warning-to-diagnostic.ts#L51

[jeddy3]

We only recently added the capability for plugins to include optional metadata and none of the ones listed above uses it, including the stylelint-scss plugin pack.

However, I locally tested a plugin that does and I saw the same behaviour. We will need to look into this more, perhaps adding the fix suggested in #6245 (comment).

[Reda011]

@jeddy3 Ok, thanks!

[ybiquitous]

@Reda011 I've opened PR #6264 to fix the plugin document. I think the document is incorrect, not the code.

Maybe, the new doc way as below should work for your plugin: 👇🏼

stylelint/docs/developer-guide/plugins.md

Lines 16 to 55 in 121a34f

	```js
	// Abbreviated example
	const stylelint = require("stylelint");
	const ruleName = "plugin/foo-bar";
	const messages = stylelint.utils.ruleMessages(ruleName, {
	expected: "Expected ..."
	});
	const meta = {
	url: "https://github.com/foo-org/stylelint-foo/blob/main/src/rules/foo-bar/README.md"
	// deprecated: true,
	};
	const ruleFunction = (primaryOption, secondaryOptionObject) => {
	return (postcssRoot, postcssResult) => {
	const validOptions = stylelint.utils.validateOptions(
	postcssResult,
	ruleName,
	{
	/* .. */
	}
	);
	if (!validOptions) {
	return;
	}
	// ... some logic ...
	stylelint.utils.report({
	/* .. */
	});
	};
	};
	ruleFunction.ruleName = ruleName;
	ruleFunction.messages = messages;
	ruleFunction.meta = meta;
	module.exports = stylelint.createPlugin(ruleName, ruleFunction);
	```

[jeddy3]

We only recently added the capability for plugins to include optional metadata and none of the ones listed above uses it, including the stylelint-scss plugin pack.

My bad. I was looking at a local version of stylelint-scss that was out of date. I hadn't realised @ybiquitous added URL metadata to the SCSS plugin back in May.

Maybe, the new doc way as below should work for your plugin:

I tried this way, but still no success. It may just be a local issue for me.

#6245 (comment)

Shall we transfer this issue to the VS Code extension repo? (although it's currently unmaintained)

[ybiquitous]

Shall we transfer this issue to the VS Code extension repo? (although it's currently unmaintained)

Sounds good. 👍🏼

I previously changed the VSCode extension to use the rule metadata (stylelint/vscode-stylelint#375), but it might be insufficient.

[ybiquitous]

I've opened the issue stylelint/vscode-stylelint#415.

[jeddy3]

@Reda011 Resolved in latest version of the VS Code extension: stylelint/vscode-stylelint#416

[Reda011]

stylelint/vscode-stylelint#416

Ok, I'll try it, thanks.

[Reda011]

I updated stylelint's version to 14.10.0, and it worked in my custom plugins library.

Thank you(@ybiquitous @jeddy3 ).