feat: all in one migration command

[dickermoshe]

Generates Dumped Schema, Tests and Steps with a single command.
Uses build.yaml config to define database and file paths.

Fixes: #3216

This basically wraps generate,dump and steps`.
A small refactor is needed to make the code in each of those commands reusable by this new command.

[github-actions]

🚀 Deployed on https://deploy-preview-3250--moor.netlify.app

[simolus3]

I was worried about supporting multiple databases, but splitting generated migration assets into different directories is a clever solution.
The implementation looks good to me, some things I'm wondering from a DX perspective:

1. Most users will have exactly one database - I think we should make that case a little easier by also allowing a simple String (as a file path) in the databases option (or perhaps with a separate database key).
2. Maybe we could use the entries of that map to not only configure the name of the database (which doesn't appear to be considered for file paths) but also the location under test/ where the default test should be added to?
3. I kind of view this as a "make the first migration tooling setup easier" command. In particular, I imagine that users will want to use the output of writeGeneratedTest() as a starting point to add own migration tests too. So maybe we shouldn't overwrite the file every time and instead only write it if it doesn't exist?

[dickermoshe]

1 will require fighting with freezed. Not sure how to do that? sealed unions?
2 & 3 are already in the works.

[simolus3]

1 will require fighting with freezed

We're using json serializable. I think you can keep the field for this and then use @JsonKey with a fromJson annotation to keep maps unchanged and map and strings to a single-element map. Don't spend too much time on this, I can figure it out if needed.

[dickermoshe]

We must resolve #3219 (comment)

[dickermoshe]

@simolus3 How do you suppose I write tests for all this.

Most of this functionality is copied from generate, steps and dump.
The only additional feature is the data validation, which is just a scaffold users fill with before and after data.

[dickermoshe]

@simolus3
Read for review. Tests are all written, lmk if you think I've missed something.

I did not implement point 1 myself. Left for you to implement - it's likely quicker for you given your familiarity with json_serializable.

Regarding point 3, we could put a function in the generated v_toV_.dart files which are not overwritten.
What do you think this function would look like and when should it be ran?

Overall, I this is coming together much quicker than I would like.
This is a tool I would personally find very useful, however it's possible that I overlooked something.

---

Please try this out yourself in practice and Lmk what the user experience is like.
It's hard to put myself in the package users' shoes. As a maintainer, I might be missing things that are obvious to someone using the package.

[simolus3]

This generally looks good to me. Some bigger notes are:

1. We should adopt this in the example/migrations project (if necessary, copy the existing schema dumps into the directory where this tool would expect them). Then let's add a section at the top of the readme showing how to use the new all-in-one command. We can keep the older commands as a reference for users who need manual control.
2. Since we expect that most users will want to run this command instead of the previous multiple invocations, let's highlight it more prominently. I think it deserves to be at the top of the migrations tooling page, mentioning that it does everything the other commands are doing in a single step, and that the other commands are then mostly intended for users needing more customization / integration into other tools.
3. Instead of pointing to --help on the documentation website, I think the website should give an introduction into the command or at least point to the migrations example. The colorful usage output looks great, but users will probably expect this information on the site as well.

[dickermoshe]

Agree, moved around some around of the docs.

[simolus3]

Thanks for the great work! LGTM.

I'll just try to get the CI fixed :D