Ideas to improve CLI user experience

[rubiesonthesky]

I'm opening this as discussion, so it's easier to gauge which ideas would be worth feature request.

CLI command separation

This relates partly to #1341

Add different commands to invoke javascript migration and typescript improvements.

Example of what I mean:

• typestat -> will just prints instructions / commands
• typestat ts -> this is the typescript improvements (or typestat enhance like the package)
• typestat js -> this is the javascript migration to typescript (or typestat initialize like the package)

This would skip the need for first question. Priting options / usage, would act as same way as the question.

Motivation

I was running biome and was once again impressed, how quick and easy it is to use without any setup. Same for knip. So I think it would make TypeStat better, if it could draw inspiration from those. I think that usually users know already which one they are going to need. :)

CLI new arguments / options

Some new arguments / options, that could be useful

• --color, this should be enabled by default but that would bring --no-color to us. That is something that could be useful in certain situations. For example, if you would run this tool in CI.
  • It's not clear cut, if there is wide need for this. However, it's easy to implement.
• max waves
  • There is already feature request here Feature to set max waves for run #1426
  • I think this could be useful for debugging with code bases that are generating a lot errors. Could be marked as experimental or under debugging to not promote the usage of regular users.
• Some other ways to invoke ways to help debugging?

Able to run as a "linter" / "dry-run"

I think, this also would be nice feature. This is coming from the thinking what biome and knip are doing. So you could just quickly run the command to check does it find any issues. It wouldn't need to go past wave 1. If there are mutations in wave 1, it could report those and exit saying that are possibly others.

Motivation

Because biome and knip are so easy to run in any code bases without setup, I sometimes run them just for fun to see if there are some issues. Sometimes, it's easier to run biome lint before you setup to eslint lint, just to gauge what is happening.

Able to commit migrations automatically

I think it would be nice to see what is happening in the code base. Especially when there are a lot changes. There are few ways that this could be implemented and few ways this could be used.

• New commit after every wave - I don't think this is useful
• New commit after 10 / x waves - I think this is something I would prefer
  • I have this huge code base where things start going really wrong after some time, this tool has been running. It could be useful, that I could go and check where things went wrong.
• New commit when first improvement phase is done
  • Here I'm referring that if you have multiple setups set in typestat.json, it would run first and create a commit with nice commit message. Then starting to do the second one. For example, if you are doing some fixes and then you have cleanup phase.

Motivation

The inspiration for the last option comes from Angular CLI and their ng update command. You can use it with -C flag and then it will create nice new commit after every migration. Those commits have good commit messages to inform you why it was done. This helps you to check what the migration actually did and was there something that went wrong.

[JoshuaKGoldberg]

CLI new arguments / options ... --color

Making the CLI more approachable and fun would be fantastic. IME anything that does a lot of complex changes, such as codemods, will naturally come across as confusing and unapproachable to most folks. I'd love to see some design proposals for the CLI that explain in more ... human-oriented terms what's happening.

[JoshuaKGoldberg]

CLI new arguments / options ... max waves / #1426
Able to commit migrations automatically

The debugging aspect as mentioned in #1426 is a good idea. Also the idea of having commits made periodically... I'd hoped that having before & after commands that can be run between alongside waves would be helpful for adding in hooks like this. For example, maybe you'd want to run a check after each wave that if there were more than arbitrarily 50 lines changed, make a commit?

I think before changing much we should really nail down - what are the real user needs of the developers? Are max waves, commands, etc. actually the best ways of satisfying them? Or is there something else we could do?

Example: making it easier/possible to configure TypeStat to operate in individual sections of the codebase in order?

[rubiesonthesky]

making it easier/possible to configure TypeStat to operate in individual sections of the codebase in order?

This sounds good to me. Like maybe it would be that it fixes types X, Y, Z and then it would create commit saying that. Or if it would first concentrate on some sub folder and fix types there.

I think there are two major ways for user to use this

• When they are running custom mutations, then it would make sense that there is clear instruction how to add git commit hook to "after / before"
• If user is running default set of mutations that the tool offers, they could invoke auto commits with either cli flag or with choosing it wrong prompting.

In both cases, there should be requirement that that the git status is clean before doing anything.

[JoshuaKGoldberg]

Able to run as a "linter" / "dry-run"

Yes! But the tricky thing is, I'm not convinced we even want users to know what "waves" are. This ties into the thoughts on the friendlier CLI: do users really care about that concept? I think not - that that's just an implementation detail to them. What they really care about is the end results from a run.

The current architecture is 100% file-system-oriented. It reads & writes files to & from disk. The APIs are swappable (see https://github.com/JoshuaKGoldberg/TypeStat/blob/16f76cf106033d5ca45da3eed82de3120aae4c08/src/services/language.ts) but there's no way to do that yet. I've been assuming that #20 will involve moving to a system that allows making everything completely virtual. @typescript/vfs has also become a thing since then. It'd be great to use that and not have to have file system stuffs on the disk at all!