fantomas 8.0.0-alpha-017

This package has no dependencies.

### Added

- `fantomas doctor <file>` walks one file through everything Fantomas does to it and reports what happened at each step: whether the path is a file Fantomas formats, which `.fantomasignore` governs it and which line of that file decided, which settings apply and which `.editorconfig` set each one, what formatting produced and where the result first parts from the file, whether Fantomas accepts its own output, and whether formatting that output again leaves it alone. It writes nothing, so it is safe against a working tree you have not committed. Every question it answers was answerable before only by reading two configuration formats by hand and knowing the order Fantomas resolves them in. It takes one file rather than a folder, because the answers differ per file, and it exits 0 for a file it could diagnose whatever it found, 1 for a path it cannot look at or a step that failed. `--json` writes the same walk as one document with a key per step. [#3421](https://github.com/fsprojects/fantomas/pull/3421)
- The `.fantomasignore` line that matched a path is now knowable rather than only the yes or no. `doctor` quotes it with its line number, the way `git check-ignore -v` does, and names every line that matches when more than one does, since a `!` pattern further down is exactly the case nobody spots by eye. [#3421](https://github.com/fsprojects/fantomas/pull/3421)
- `doctor` decides whether a file would be rewritten the way a format run decides it, by comparing the text as it is. A file whose line endings are the only thing out of step is therefore reported as needing formatting, where `fantomas check` deliberately overlooks that difference and calls the same file already formatted. What it reports is where the file and the result first part, rather than a count of the lines that differ by position: that is not a count of edits, because splitting one long line into five moves every line below it. [#3421](https://github.com/fsprojects/fantomas/pull/3421)
- A file under a folder a compiler or a package manager wrote, such as `obj`, is named as such by `doctor`. A run over the tree above it never opens that folder, whatever the ignore file says, and sending its owner to read their `.fantomasignore` sends them to read the wrong file. [#3421](https://github.com/fsprojects/fantomas/pull/3421)

### Changed

- Breaking: output that Fantomas will not accept from itself is reported as what it is, and shows you the part of that output it would not accept. `Fantomas produced code that is not valid F#.` read as though the file were at fault, and reaching it always means the opposite: the input parsed, or a parse failure would have been reported instead. The report now says that nothing was written and the file is untouched, that this is a bug in Fantomas rather than a problem with the code, and where to report it, in the shape a parse failure and an unmodellable construct already print. [#3419](https://github.com/fsprojects/fantomas/pull/3419)
- Breaking: that report carries what the parser said about the rejected output, and the lines of the output around it with a caret under the failure, so there is a small reproduction to cut from it. Up to now the run said only that something was invalid, and finding out what meant running again with `--force` and reading the result. The diagnostics carry no line and column of their own: the output they would count into is written nowhere, so a position in it is a coordinate you cannot follow, and a path an editor could open would take you to the wrong line of the right file. The carets say where, and the report says out loud that the lines below it are the output rather than your file. `--json` carries the same diagnostics in the `diagnostics` array a parse failure already uses. `fantomas check` reports all of it the same way, where it used to run the whole explanation on after `could not be checked:`. [#3419](https://github.com/fsprojects/fantomas/pull/3419)
- The two reports that ask you to file a bug, for output Fantomas would not accept and for a construct it cannot model, name one place to send it rather than two. They used to add the issue tracker as an alternative for a file too large for the online tool to carry, which offered a choice at the point somebody least wants one. [#3419](https://github.com/fsprojects/fantomas/pull/3419)
- Breaking: `Fantomas.Core.CodeFormatter.IsValidFSharpCodeAsync` became `ValidateFSharpCodeAsync` and answers with a `ValidationResult` rather than a `bool`. Read `.IsValid` off it where the verdict was all you wanted; `.Diagnostics` is what Fantomas refused, positioned, and is empty exactly when the source is valid. The boolean discarded it, so anything that had to say why had to parse the source a second time to find out, which is why the tool could not show you its own bad output. A warning Fantomas tolerates, such as [#3396](https://github.com/fsprojects/fantomas/issues/3396) on IWSAM types, is not among them. [#3419](https://github.com/fsprojects/fantomas/pull/3419)

### Fixed

- A `[<return: ...>]` attribute written in front of an `extern` declaration was dropped from the output. The parser moves such an attribute out of the binding's attribute list and into its arity information, and the `extern` path never looked there, so the line was silently deleted. Bindings already put those attributes back; `extern` now does the same. An attribute written on the return type itself, `extern [<MarshalAs(UnmanagedType.I1)>] bool f(int options)`, is reported in both places and stays where it was written. [#3420](https://github.com/fsprojects/fantomas/issues/3420)