# Formatting

`jadpo fmt` lays out your code, so you never choose a style. Equivalent
code always looks the same, and a diff only ever shows real changes
([Project layout and modules](project-layout-and-modules.md)). The
editor formats on save, and `jadpo fmt --check` fails when a file differs
from what the formatter would write.

```jadpo
type Flags = Object {
    done: Bool
    pinned: Bool
}

type Count = Int {
    min: 0
}
```

## Layout

The formatter decides indentation, spacing and blank lines: one between
declarations, never two. It writes one member per line, as above. A short
list such as `pick: [Todo.id, Todo.title]` stays on one line.

## The order of sections

The sections inside a declaration go in one order:

- a failure's `kind`, `code`, `message`, `client`, `internal`;
- a route's `authentication`, `rate_limit`, `input`, `output`, `status`,
  `deadline`, `run`;
- an entity's fields, then `identity`, `persistence`, `lifecycle`,
  `membership`, `policy`, `freshness`, `guard`, `person`.

Any other section keeps its written order after these. Fields are never
reordered, and a section's comments move with it.

The one exception is `config { }`: its fields are sorted by name, each
with its comments, so two workspaces that each add a setting rarely touch
the same lines ([Fields in name
order](10-configuration-and-time.md#fields-in-name-order)).

## Imports

Inside a project, `jadpo fmt` fixes each file's `use` lines before it lays
the file out ([Imports](imports.md)). It
adds a missing import, removes an unused one, and moves a name imported
from the wrong folder, by applying the edits that `jadpo check`'s import
problems carry. Then it sorts the lines. That needs the project's names
resolved, so it waits until every file parses. `jadpo fmt --check` fails
on a file whose imports it would change, as it does on one it would lay
out differently.

## The order of declarations

Inside a project, `jadpo fmt` also writes each file's declarations in
definition-before-use order, below its opening comments and `use` lines
([Files and names](files-and-names.md)):

- each declaration comes before the first that uses it, so the primary
  declaration, the one the file is named after, comes last;
- ties are broken by kind, then by the order the primary first reaches
  them;
- declarations that use each other keep the order they were written in;
- each keeps the comments written above it and after it on its line.

Test files and loose files have no primary declaration and keep their
order. `jadpo fmt --check` fails on a file out of order.

## Promotion

Promotion is the one layout change that moves code between files. When a
second file uses a type or helper, `jadpo check` reports
`layout.promotion_required` with a one-step fix. You apply it with the
editor's quick fix or `jadpo fmt --layout`, never on save, so a move is
always a visible, separate change.

`jadpo fmt --layout` makes every move a type needs: out of its file with
its comments, into a file of its own below the `use` lines it needs. Then
it fixes the imports the moves touched. Moving a helper function into a
library changes its calls, so that stays a change you make by hand.