Add rule to order definitions

[wooorm]

Subject of the feature

It’s hard to sort definitions manually, and vague how to do it.

Problem

My list of definitions, at the end of readmes, is messy

Expected behavior

Options to sort a) alphabetically, b) first-use?

Alternatives

?

Questions

• what about (groups of) definitions throughout the document, instead of the end?
• “Alphabetical” is complex, should localization be supported?
• Warn naïvely, for every wrongly sorted definition, or shortest “diff”. As in, if one definition should move down 10 places, do you warn for that? For the 9 definitions that move up? All?

[github-actions]

Hi! This was marked as ready to be worked on! Note that while this is ready to be worked on, nothing is said about priority: it may take a while for this to be solved.

Is this something you can and want to work on?

Team: please use the area/* (to describe the scope of the change), platform/* (if this is related to a specific one), and semver/* and type/* labels to annotate this. If this is first-timers friendly, add good first issue and if this could use help, add help wanted.

[remcohaszing]

I like this idea!

• what about (groups of) definitions throughout the document, instead of the end?

I think definitions should be sorted within each group. Requiring a list of definitions to be moved to the end could be a separate rule.

• Warn naïvely, for every wrongly sorted definition, or shortest “diff”. As in, if one definition should move down 10 places, do you warn for that? For the 9 definitions that move up? All?

I’d say a definition is sorted wrongly if it should appear above it’s sibling.

[remark]: https://remark.js.org

[unifiedjs]: https://unifiedjs.com

[rehype]: https://rehype.js.org
 ^^^^^^-- message: “rehype” link reference should be sorted before “unifiedjs”

---

Auto fixing may be nice as well. See vfile/vfile-message#13 (comment)

[wooorm]

I think definitions should be sorted within each group. Requiring a list of definitions to be moved to the end could be a separate rule.

So the rule would first create “groups” (nodes with the same parent that do not have non-definitions between them). 👍

---

But what about:

[a]: #

[z]: #

[b]: #

[c]: #

[d]: #

3 warnings for b, c, and d? Or one for z? (Not sure if you already took this example into account, which I sort of alluded to in the prose)

[remcohaszing]

In that case only b would be reported. If this is corrected, the file looks like this:

[a]: #

[b]: #

[z]: #

[c]: #

[d]: #

Now c will be reported.

Something is always reported if an item is out of order, so the user will have to repeat this process until everything is sorted as expected.

---

It would also be possible to report b, c, and d. That would mean that for each definition in the group would need to be checked against all of its preceding siblings until a violation is found.

In the end this has the same result: The user has to sort the definitions until no more messages appear. It may be a bit more daunting if 3 violations are reported.

I don’t think It’s necessarily more or less correct to do so. If the checks would happen from end to start, then only z would be reported with either strategy.

[Xunnamius]

I've taken a stab at this, though as a remark transformer rather than a remark-lint rule: remark-sort-definitions.