Overview
Every rule, which ones --fix applies and which ones --check only reports, and the order that decides a gap.
Stanza formats statement lists: the module top level, function bodies, arrow block bodies, methods, static blocks, if, loop and try blocks, and switch clause bodies. The blank line rules never touch the gaps between class members or namespace members.
At top level the rules read export const and export function as the declaration they export, so a constant joins the exported function that reads it. Imports and re-exports (export ... from) form one group: a multi-line import gets no blank line before the next import, and imports never count toward a wall. short-body and edge-blank are block rules and skip the top level.
import { dlopen, FFIType } from "bun:ffi";
const LOCK_WAIT = 10_000;
const LOCK_EX = 2;
const LOCK_NB = 4;
let libc: { flock(descriptor: number, operation: number): number } | undefined;
let libc: { flock(descriptor: number, operation: number): number } | undefined;
function flock(descriptor: number, operation: number): boolean {
libc ??= dlopen(process.platform === "darwin" ? "libc.dylib" : "libc.so.6", {
flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
}).symbols;
return libc.flock(descriptor, operation) === 0;
}
export { flock, LOCK_EX, LOCK_NB, LOCK_WAIT };Applied by --fix
| rule | what it does |
|---|---|
after-multiline | a statement that spans several lines is followed by a blank line |
switch-clauses | a blank line goes in between switch clauses and none is ever removed; the gap under a fall through label with an empty body is left as it is |
edge-blank | a block has no blank line right after { or right before } |
guard-join | a single-line declaration or assignment is followed directly by an if that references what it binds, whatever the body size and with or without else |
consume-join | a single-line declaration or assignment is followed directly by a return or switch that references what it binds |
use-join | a single-line declaration is followed directly by a loop, try or function declaration that references what it binds |
guard-chain | consecutive compact guards (if with a single statement body and no else) have no blank line between them |
let-step | a let that joins the block below it gets a blank line above it, so it starts its own step |
after-guard | a single-line guard that returns, throws, continues or breaks is followed by a blank line, unless the next statement is an if or a jump (return, throw, break, continue) |
short-body | a block of 2 or 3 compact statements has no blank lines, whether it is a function body, an arrow body, a method, a nested block or a switch clause body |
braces | a control flow body that is a single statement has no braces |
Reported by --check, Never Fixed
| rule | what it reports |
|---|---|
block-spacing | a multi-line block directly under a statement, when no rule decides the gap |
wall | 6 or more consecutive single-line statements with no blank line, reported only where a blank line --fix keeps can split the run |
--fix prints these findings too. It never changes the code for them.
A statement is compact when it sits on one line, or when it is a braceless if, for or while whose joined line fits the formatter width. An if with else is compact when every arm fits that way. short-body covers the details.
Stanza reads the width for each file. The nearest oxfmt, Biome or Prettier config that applies to it wins, including overrides. If that config sets no width, Stanza reads .editorconfig where the formatter does. Otherwise it uses the default width of the formatter the nearest package.json that lists one depends on: 100 for oxfmt, 80 for Biome or Prettier. With no formatter anywhere, it uses 80. When one directory has configs for two formatters, that dependency picks one, and when it does not, the smaller width wins. Tabs count as the formatter's tab width. stanza explain prints the width and where it came from.
How a Gap Is Decided
A gap is the space between two neighbouring statements in a list. One rule decides each gap. The rules are tried in a fixed order, and the first one with an opinion wins:
- short-body
- guard-chain
- after-multiline
- switch-clauses
- guard-join, consume-join and use-join
- after-guard
When none of them applies, the gap keeps the blank lines it has. let-step runs afterwards as a pass over the decided gaps. edge-blank looks at the space inside a block's braces rather than between statements, and braces runs on its own. A gap next to a statement under stanza-ignore is frozen: no rule touches it or reports it (see Directives). A statement that starts on the closing line of a multi-line statement is left alone.
Comments stay attached to the statement below them as long as no blank line separates them. A blank line inside a block comment does not separate it. An inserted blank line goes above the leading comments, and a trailing comment on the same line moves with its statement. When a blank line already separates a comment from the statement under it, the statement is detached: the gap above it is never edited or reported.
stanza explain <file>:<line> prints the rule that decided a line and what it outranked. See Explain.