feat: new restrict-dependency-ranges rule

[michaelfaith]

PR Checklist

• Addresses an existing open issue: fixes 🚀 Feature: add restrict dependency ranges rule #959
• That issue was marked as status: accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

This change adds a new rule that allows you to restrict usage of semver ranges on dependencies using any of the following matching options:

• by dependency name or regex pattern
• by version
• by dependency type

Closes #959

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.58%. Comparing base (966e175) to head (618bafd).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #998      +/-   ##
==========================================
+ Coverage   99.50%   99.58%   +0.07%     
==========================================
  Files          19       20       +1     
  Lines        1223     1451     +228     
  Branches      142      193      +51     
==========================================
+ Hits         1217     1445     +228     
  Misses          6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[JoshuaKGoldberg]

🚀 The core logic seems very reasonable and good to me, really nice job! I think it makes sense to go in order like this and check the first (last, reversed) matching dependency.

Mainly requesting changes on:

• Docs: adding some more examples to make usage more clear
• Testing: some of the lines don't fail any tests for me when removed locally
• Some suggestions around refactors

WDYT?

[michaelfaith]

From the "Lint Markdown" step: Each sentence should be on its own line
Really? That seems super heavy-handed...

@JoshuaKGoldberg not directly related to this change, but the first time I'm seeing this error (I think it came in with the CTA update since I just rebased with main). How strongly do you feel about this rule? I'm personally not a fan, but if it's something you feel strongly about, I'll work around it.

[JoshuaKGoldberg]

😄 I do feel strongly in favor about it, I think it's really nice to have a 1:1 of "line that can be diffed in Git" to sentences. But also if you end up hating it enough to send a PR that removes it from this repo, I'll approve it.

ACK that it's kind of inconvenient to not have it be integrated into ESLint; I'm hoping that later this year as @eslint/markdown gets fleshed out I can switch from Markdownlint to ESLint altogether...

[michaelfaith]

ACK that it's kind of inconvenient to not have it be integrated into ESLint

That actually touches on the second reason i'm not a fan of the rule haha.

I have two main issues with it. For the first, i think we can generally agree on the following three statements?

1. Documentation is extremely valuable, but also not something that people always think to do (unless you maintain a project or are long in the tooth like me, it's often an afterthought). So it's something we should generally incentivise contributors to do, by making it as easy as possible to create high quality documentation.
2. Writing good documentation is an art and not a science. Explaining something in a way that's easy for others to consume, understand, and relate to requires a fair amount of empathy and creative thinking.
3. Writing prose one sentence per line does not come natural, and would not be how anyone would naturally write documentation unless they happen to know (and remember) this rule was in place.

Those three things tell a story of us believing that something is truly valuable, but then creating friction around contributing it. More often than not, people contributing new code will hit up against that, and get frustrated (like i did 😆). That, then discourages people from even bothering. And all of that could be ok, if we believe the benefits outweigh the cost. And i just don't see that being the case. If i think about the kinds of changes people might make to existing documentation, i don't really see what value having them one sentence per line brings in terms of diff review. Certainly not enough to outweigh the cost. For something like the dangling comma formatting rule (which promises a similar value proposition), that calculus is much more in favor of the rule, since it's something we interact with way more.

And that brings me to the second point of grief: like dangling commas, this is a formatting concern. And i think we generally agree that formatting is the domain of prettier, not lint. This isn't something that feels like it should belong in any lint tool, whether it be markdownlint or eslint. In my mind, if it should exist at all, it should go in prettier.

Happy to be convinced otherwise, if i'm missing something, or not looking at this correctly. 😊

[JoshuaKGoldberg]

You make a lot of good points! Agreed, getting folks to write docs in the first place >>> nitpicking the formatting of those docs 😄. Filed JoshuaKGoldberg/create-typescript-app#2216.

[JoshuaKGoldberg]

💯 solid!

[github-actions]

🎉 This is included in version v0.30.0 🎉

The release is available on:

• GitHub releases
• npm package (@latest dist-tag)

Cheers! 📦🚀