# `ExQuality.Stages.Format`
[🔗](https://github.com/riddler/ex_quality/blob/v0.15.0/lib/ex_quality/stages/format.ex#L1)

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.

# `run`

```elixir
@spec run(keyword()) :: ExQuality.Stage.result()
```

Runs the format stage.

First checks which files need formatting, then formats them - or, with
`format: [check: true]`, reports them as a failure and writes nothing.
Returns a result with the list of files, the tool's output when `mix format`
itself failed, or a `:skipped` result when the project has no
`.formatter.exs`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*