Stanza

Output and Exit Codes

Read what a run prints, and what its exit code means.

Findings

--fix and --check print one finding per line:

path:line:col: rule: message

A finding that --fix leaves for you to fix by hand ends with (by hand). The line and column count from 1, and the column counts UTF-16 code units, as VS Code does, so a path:line:col clicked in a terminal lands on the character.

The path is relative to the working directory, or absolute when stanza cannot read the working directory. A path holding a control character, a line or paragraph separator, " or \ prints quoted, in the escapes git status uses, such as "a\nb.ts", so a row always fits on one line, and a row that starts with " always holds a quoted path. Findings are sorted by path in byte order, the order git ls-files lists them in, then by line, column and rule id. --check prints every finding. --fix applies what it can and prints what is left, so its findings are the ones no rule could fix.

Given this file at src/load.ts:

src/load.ts
function parseConfig(text: string) {
  const raw = JSON.parse(
    text,
  );
  if (!isRecord(raw)) throw new Error("config must be an object");
  return raw;
}

stanza --check src/load.ts prints:

Finding
src/load.ts:5:3: after-multiline: add a blank line after the multi-line statement above

Besides the rule ids, a finding can name a file stanza cannot handle:

rule idmeaning
parsethe file cannot be read or parsed, and is left untouched
errorstanza failed on the file, or its fixed text would not parse, and it is left untouched
write--fix cannot write its fixes to the file, or the file changed while stanza ran

Each of these makes the run exit 2.

A file nested so deeply that parsing it could overflow stanza's stack is reported with the parse rule before stanza parses it, at the point where it passes the cap. The cap is 10,000 levels, or fewer when stanza runs on a smaller stack. Each bracket, brace, template substitution and JSX element is a level. So is each statement head (if, while, for, with, switch or do) whose body is still open, and each token in the same expression that opens a nested one: = and the other assignments, =>, ?, :, <, **, ..., new, await, yield, extends, keyof, readonly, unique and infer. Other operators, such as !, +, |, && or ., count one level for every 16 of them. A comma or a finished statement drops the count of the expression it ends:

Nested Too Deep
src/load.ts:1:10010: parse: nests more than 10000 levels deep, left untouched

A file that changes after stanza reads it, such as one an editor saves while --fix runs, keeps the new text. Stanza reports it and leaves it for the next run:

Changed File
src/load.ts:1:1: write: changed while stanza ran, left untouched

--fix writes a file in place when it cannot replace it, such as a hard link, a file in a read-only directory or a file mounted on its own. If that write fails and putting the original text back fails too, the finding says so:

Possibly Truncated File
src/load.ts:1:1: write: cannot write: no space left on device, restore failed, the file may be truncated

When stanza hits an internal error on a file, a bug in stanza rather than in the file, it leaves the file untouched, reports it with the error rule and goes on with the rest of the run:

Internal Error
src/load.ts:1:1: error: internal error (index out of bounds), left untouched

It also prints one line on stderr naming the file, the line to quote in a bug report, unless the run uses --fix --json --stdin, whose stderr holds only the findings:

Internal Error on Stderr
stanza: internal error on src/load.ts, left untouched: index out of bounds

An internal error outside any file ends the run with one line on stderr and exit 2:

Internal Error Outside a File
stanza: internal error: index out of bounds

Working Directory

Stanza needs the working directory only to read relative paths, --changed, --staged and stanza explain. When the directory it was started in has been deleted, --check or --fix over absolute paths goes ahead as usual and prints them as absolute paths. Any other run prints this and exits 2:

Deleted Working Directory
stanza: cannot read the working directory: no such file or directory

JSON

--json prints the findings as one JSON array instead. fixable says whether --fix applies the finding. For the example above:

--json
[
  {
    "path": "src/load.ts",
    "line": 5,
    "col": 3,
    "rule": "after-multiline",
    "message": "add a blank line after the multi-line statement above",
    "fixable": true
  }
]

Stdin

With --stdin <path>, stanza reads the source from stdin. The path only names the buffer: it picks the extension, the lint config and the skip rules, and need not exist.

modestdoutstderr
--fix --stdinthe fixed textfindings
--check --stdinfindingswarnings only

A path the skip rules exclude passes through untouched: --fix prints the input as it came. For format on save in an editor, see Editors.

Warnings on Stderr

Warnings and notices go to stderr and never change the exit code. The notice stanza prints when it cannot tell whether a lint config enforces braces is covered under Braces and Lint Config.

When stanza cannot read the line width from a config file it finds, it prints this warning unless the run uses --fix --json --stdin. The warning names each file it cannot read: an oxfmt, Biome or Prettier config, a package.json, or an .editorconfig. Here it is for an unreadable .oxfmtrc.json:

Width Warning
stanza: cannot read the line width from .oxfmtrc.json, so the next source sets it

Stanza takes the line width from the next source it checks.

When the system will not start a worker thread, under an address space limit for example, stanza formats that thread's share on the threads it has and prints one warning for the run:

Worker Warning
stanza: 2 of 3 worker threads failed to start, so the run went on without them: resource temporarily unavailable

Unwritable Output

When stanza cannot write its findings or its fixed text, on stdout or on the stderr that --fix --stdin prints findings to, it prints this on stderr and exits 2, since whatever reads the output never got the results:

Unwritable Output
stanza: cannot write output: no space left on device

A warning or notice that cannot be written changes no exit code. A reader that stops early, as | head does, is not a failure either, and the run keeps its own exit code.

Exit Codes

exit--fix and --check
0clean, or nothing was selected
1findings remain
2a usage error that names the problem, a missing or unsupported path, a path that is not a regular file, a file name that is not valid UTF-8, a file that cannot be read or parsed, fixes that cannot be written or a file that changed while stanza ran, an internal error, a git command that failed while picking files, a working directory stanza cannot read when the run needs it, or output stanza cannot write

Exit 2 wins over 1. A file that fails is reported and left untouched, and the rest of the run still goes ahead.

Under --fix, exit 1 means findings remain that --fix cannot apply, so an editor that formats through --fix --stdin has to accept 1 as success.

stanza explain and stanza hook have their own exit codes.

On this page