Auto-fixes code formatting by running mix format.

Reports how many files were modified.

In its default mode this is the only stage that modifies code - all other stages are read-only. That is the right default for the interactive loop, where a developer wants drift fixed rather than reported, but it means formatting can never fail a run: drift is silently rewritten by whoever runs the gate next.

Check mode

format: [check: true] in .quality.exs makes the stage check instead:

stages: [
  format: [check: true]
]

In check mode the stage runs mix format --check-formatted and stops there. A clean tree passes; drift fails the stage with the file list, and nothing is written - CI stays authoritative about formatting instead of the next gate run absorbing the diff, and an unattended agent's gate does not mutate the working tree mid-run. The stage keeps the name "Format" in both modes, so nothing that routes on the report has to know which mode produced it.

The stats key says which claim is being made: files_formatted in the default mode (that many files were rewritten), files_needing_format in check mode (that many files would be).

Projects with no formatter

mix format needs a .formatter.exs (or explicit patterns) and fails without one. That is a project that has never used the formatter, not a project with a problem, so the stage reports it as skipped rather than failing the run over a missing config file. The same applies in check mode: a project that has never used the formatter has nothing to check.

When formatting fails

mix format succeeds on any code it can parse, so the usual outcome is a pass. It does fail on a file with a syntax error, and the stage reports that rather than reading the file list out of the failed run: a SyntaxError line names no .ex file to count, so the stage used to print a green tick as the first line of a run on a broken file. Compile says the same thing moments later, but the run should not have claimed otherwise in the meantime. Check mode reports the same failure the same way.