Add urls pointing to docs on all messages

[remcohaszing]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

Allow unified-lint-rule to accept an object instead of a source string, which can specify named properties, including source and url. The url is set on all reported vfile messages.

All remark-lint rules have been updated to use an object and set the url.

Closes #272

[ChristianMurphy]

I like the idea of adding more metadata for reporters to be able to surface 👍

[ChristianMurphy]

I wonder if it would make sense to use some of the same semantics eslint uses? 🤔
They leverage a docs field https://eslint.org/docs/developer-guide/working-with-rules#rule-basics

docs (object) is required for core rules of ESLint:

• description (string) provides the short description of the rule in the rules index
• category (string) specifies the heading under which the rule is listed in the rules index
• recommended (boolean) is whether the "extends": "eslint:recommended" property in a configuration file enables the rule
• url (string) specifies the URL at which the full documentation can be accessed (enabling code editors to provide a helpful link on highlighted rule violations)
• suggestion (boolean) specifies whether rules can return suggestions (defaults to false if omitted)

In particular, description, category, and url seem relevant.
And having it scoped (to docs or something else) keeps url open to any other uses we may have in the future.

[remcohaszing]

I could nest the url property inside an object property docs. Although none of the other properties seem to map to any properties relevant to vfile messages. I also don’t really see another use case for the url property.

I think it’s fine as-is, but if you feel strong about this and it’s ok with @wooorm,, I’ll introduce the docs object with only url for now.

[ChristianMurphy]

I don't feel strongly about scoping.
I do find url floating in meta confusing though.
If I saw

{
  origin: "something",
  url: "https://example.com"
}

without some additional context/comments, I'd have very little understanding of the intent.

Something like:

{
  lintRuleName: "something",
  documentationUrl: "https://example.com"
}

would be more verbose, but clearer.

[remcohaszing]

I agree if you put it that way. Although url and origin match the names of the properties on vfile messages they represent.

[ChristianMurphy]

Hmmm, thoughts @wooorm? 💭

Another approach could be to update the type definition to carry some description through.
#273 (comment)
Which would benefit folks using an IDE with TS-language-server support, but would still leave ambiguity otherwise.

[wooorm]

• category — that’s a bit like origin
• recommended — more needed because ESLint does stuff by default, whereas remark-lint is opt-in only
• suggestion — some retext rules add an actual/expected, but lint rules don’t
• description — how much should this be? Markdown? Short message? Isn’t either the error message or the full readme enough? vfile-reporter does support a note I believe btw, which can have some more information

---

Re Christian’s point on:

{
  origin: "something",
  url: "https://example.com"
}

looking nondescript, I’d say that perhaps it is that way because of how it’s abstracted. A more practical example:

{
  origin: 'remark-lint:blockquote-indentation',
  url: 'https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation#readme'
},

looks clear to me.

---

And for types as an alternative, the description is already defined in the types (@fileoverview) and extracted and put into the readme.
We could:

• Put that description in the JSDoc attached to the rule
• Put the description in a string (and the URL), and instead generate the readme based on actual code rather than comments

[remcohaszing]

We could:

• Put that description in the JSDoc attached to the rule
• Put the description in a string (and the URL), and instead generate the readme based on actual code rather than comments

Yes, we could. Although I doubt this has much added value. unified-lint-rule could support note anyway, but I think this is out of scope for this PR.

[ChristianMurphy]

Probably outside of the scope of the PR, but another thing I noticed.
The readme for unified-lint-rule doesn't include an API section

[wooorm]

Looks good to me. @ChristianMurphy?

[wooorm]

Released!