docs: add formatter spec

[zimbatm]

Describe how formatters should ideally work.

Fixes #31

[basile-henry]

Looks great! 👍

Maybe it's a separate concern, but I do wonder: if we ever want prjfmt to have the option to check the format instead of applying the format, maybe this should make it into the specification.

If a formatter doesn't implement check functionality itself, that can be implemented in a wrapper script using diff (but then the formatter should probably not do in place formatting).

It might also make sense to not use the same options when in check mode. Some options might not make sense (for example ormolu's mode which can only be one of inplace, check or stdout). So maybe prjfmt could have a field check-args as well as args which would follow a similar specification but would only check if the files are formatted.

[basile-henry]

prjfmt.toml calls these args, it might be better to keep these two names synchronized. How about we rename this to args or alternatively rename the field in prjfmt.toml.

[zimbatm]

Good idea. I'm thinking we should do this the other way around and rename args to options. args is more generic and also includes the list of files that would be passed.

[Rizary]

I am still not sure whether we have to make a formatter spec or not. If the user still uses cargo fmt which does not adhere to the formatter spec, what's prjfmt's UX would be?

[zimbatm]

Regarding the --check option, we already have that capability built into prjfmt thanks to Rizary's eval cache. If the mtime has changed after the formatting, it means that the files have changed. Files would be changed as well but it doesn't matter IMO.

[basile-henry]

Alright, so this relies on:

If, and only if, a file format has changed

Is that a common feature of formatters? I don't think ormolu does that for example, I think it'll write the file even if it's the exact same content.

[zimbatm]

We'll see. Thanks to the spec it should be possible to petition upstream formatters to implement the right thing. In the worse-case scenario, it's possible to fallback on the source control to query if any files are dirty after the formatting occurs. And then ship with some common implementations in the documentation. For example for git, it just adds a single line of code to the CI.

[zimbatm]

Another missing aspect of the spec is the XDG config part that formatters can ship.

Let's ship this and gather more experience by trying out a ton of formatters. We can always come back and update the spec.