feat: Add help cli

[dominicduffin1]

PR Checklist

• Addresses an existing open issue: fixes 🚀 Feature: Add a --help CLI option #703
• That issue was marked as status: accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

I've added functionality to print to the terminal help documentation based on the existing docs when the --help or -h terminal flags are used.

This will run in place of the functionality.

I've marked this as a draft PR as I have a few questions so it is not yet complete, maybe you can assist @JoshuaKGoldberg :

• What kind of test coverage would you be looking for for this functionality?
• What is the best approach to fetch the version number?
• I'm not clear what is meant by "running parseargs" to check for missing options (from the issue).

Beyond that, is what I've included and how I've formatted the printout what you were expecting?

[codecov]

Codecov Report

Merging #775 (9a1d298) into main (8918987) will increase coverage by 18.94%.
Report is 1 commits behind head on main.
The diff coverage is 99.39%.

@@             Coverage Diff             @@
##             main     #775       +/-   ##
===========================================
+ Coverage   75.16%   94.10%   +18.94%     
===========================================
  Files          88       95        +7     
  Lines        4852     5429      +577     
  Branches      196      431      +235     
===========================================
+ Hits         3647     5109     +1462     
+ Misses       1200      319      -881     
+ Partials        5        1        -4     

Flag	Coverage Δ
create	70.75% <73.09%> (?)
initialize	40.90% <73.09%> (+2.56%)	⬆️
migrate	69.72% <73.09%> (-0.04%)	⬇️
unit	71.46% <99.19%> (?)

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

Files	Coverage Δ
src/bin/help.ts	100.00% <100.00%> (ø)
src/bin/packageJson.ts	100.00% <100.00%> (ø)
src/shared/options/args.ts	100.00% <100.00%> (ø)
src/shared/readFileSafe.ts	100.00% <100.00%> (+33.33%)	⬆️
src/shared/readFileSafeAsJson.ts	100.00% <100.00%> (ø)
src/bin/index.ts	96.93% <89.28%> (+22.54%)	⬆️

... and 52 files with indirect coverage changes

📣 Codecov offers a browser extension for seamless coverage viewing on GitHub. Try it in Chrome or Firefox today!

[JoshuaKGoldberg]

Looks like a solid start! Left some comments around refactors, but I'm very into the general visuals you're going with. 🚀

[dominicduffin1]

@JoshuaKGoldberg I just wanted to give you a progress update:

• I've refactored the help print logic to use functions and merged the source data into the objects in src/shared/options/args.ts.
• I've gone with the option of always logging the version number and deduplicated the package name
• To get the version from the package.json I couldn't get the safer looking method of using URL to work, I've done something that seems to work in development but I'm not confident about it - will keep on looking at this.
• There are some lint issues with any types which I need to resolve.

[dominicduffin1]

Hi @JoshuaKGoldberg! I think I've covered everything that came up in this conversation, so I've marked the PR as ready for review. I am of course willing to work on any additional feedback!

I've been getting an error on one of the e2e tests, pnpm run test:migrate, both on this branch and on main. I'm not sure if I'm running the test wrong or if there's an issue?

Oh no! Running the migrate script modified some files:
 - .github/workflows/build.yml
 - .github/workflows/lint-markdown.yml
 - .github/workflows/lint-package-json.yml
 - .github/workflows/lint-packages.yml
 - .github/workflows/lint-spelling.yml
 - .github/workflows/post-release.yml
 - .github/workflows/prettier.yml
 - .github/workflows/tsc.yml

That likely indicates changes made to the repository without
corresponding updates to templates in src/.

[JoshuaKGoldberg]

Yeah sorry about the migrate test noise - it's not related to this PR. You were right to check on main. It's just broken for everyone. I'll fix it now. #796

[JoshuaKGoldberg]

Wonderful 🚀! This is shaping up really nicely. Thanks for iterating on it!

I left some cleanup comments - a few are just style nitpicks, and a few are more structural. Please do let me know if you think I'm off base on any of them (or just want to chat alternatives)! ❤️

[JoshuaKGoldberg]

- [ ] Addresses an existing open issue: fixes #000

Don't forget to reference the issue 😄

[dominicduffin1]

I've also excluded the help snapshot from the cspell linter as it was causing it to fail.

[JoshuaKGoldberg]

Fantastic, thanks so much! You put a lot of work into this and I really appreciate it 🙌 great!

[JoshuaKGoldberg]

@all-contributors please add @dominicduffin1 for code.

🤖 Beep boop! This comment was added automatically by all-contributors-auto-action.
Not all contributions can be detected from Git & GitHub alone. Please comment any missing contribution types this bot missed.
...and of course, thank you for contributing! 💙

[allcontributors]

@JoshuaKGoldberg

I've put up a pull request to add @dominicduffin1! 🎉

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[github-actions]

🎉 This is included in version v1.43.0 🎉

The release is available on:

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

Cheers! 📦🚀