feat: add collectVariableUsage API

[JoshuaKGoldberg]

PR Checklist

• Addresses an existing open issue: fixes 🚀 Feature: Port collectVariableUsage from tsutils #263
• That issue was marked as status: accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

Directly ports the exported public collectVariableUsage function from tsutils. Adds in some unit test coverage too.

I'd wanted to refactor its source to be less reliant on class hierarchies... but there's a lot going on there. Out of scope for now. I did apply a few touchups:

• Changed "soft" privates to use #.
• Renamed VariableInfo to UsageInfo.
  • It's used both for types and values, so referring to them as "variables" was confusing to me.
  • Please shout at me if you can think of a better name or believe the original name to be better!
• Switches the const enums to just enums.
• Adds test coverage for the most common cases.
  • It's not super thorough, so if you spot some logic you think should be tested, shout at me and I'm happy to add it in if I can

[codecov]

Codecov Report

Merging #274 (2489e11) into main (ebfe350) will increase coverage by 3.60%.
Report is 1 commits behind head on main.
The diff coverage is 56.95%.

@@            Coverage Diff             @@
##             main     #274      +/-   ##
==========================================
+ Coverage   50.00%   53.60%   +3.60%     
==========================================
  Files          20       28       +8     
  Lines         460      832     +372     
  Branches      181      276      +95     
==========================================
+ Hits          230      446     +216     
- Misses        203      313     +110     
- Partials       27       73      +46     

Flag	Coverage Δ
4.3.5	52.88% <56.14%> (+3.53%)	⬆️
4.6.4	53.00% <56.14%> (+3.43%)	⬆️
4.9.5	53.12% <55.88%> (+3.12%)	⬆️
latest	53.00% <55.88%> (+3.22%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
src/usage/getPropertyName.ts	0.00% <0.00%> (ø)
src/usage/declarations.ts	38.88% <38.88%> (ø)
src/usage/getUsageDomain.ts	42.42% <42.42%> (ø)
src/usage/scopes.ts	57.51% <57.51%> (ø)
src/usage/UsageWalker.ts	65.62% <65.62%> (ø)
src/usage/utils.ts	66.66% <66.66%> (ø)
src/usage/Scope.ts	87.50% <87.50%> (ø)
src/modifiers.ts	100.00% <100.00%> (+100.00%)	⬆️
src/test/utils.ts	88.88% <100.00%> (+0.65%)	⬆️
src/usage/collectVariableUsage.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more