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: messageA 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:
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:
src/load.ts:5:3: after-multiline: add a blank line after the multi-line statement aboveBesides the rule ids, a finding can name a file stanza cannot handle:
| rule id | meaning |
|---|---|
parse | the file cannot be read or parsed, and is left untouched |
error | stanza 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:
src/load.ts:1:10010: parse: nests more than 10000 levels deep, left untouchedA 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:
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:
src/load.ts:1:1: write: cannot write: no space left on device, restore failed, the file may be truncatedWhen 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:
src/load.ts:1:1: error: internal error (index out of bounds), left untouchedIt 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:
stanza: internal error on src/load.ts, left untouched: index out of boundsAn internal error outside any file ends the run with one line on stderr and exit 2:
stanza: internal error: index out of boundsWorking 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:
stanza: cannot read the working directory: no such file or directoryJSON
--json prints the findings as one JSON array instead. fixable says whether --fix applies the finding. For the example above:
[
{
"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.
| mode | stdout | stderr |
|---|---|---|
--fix --stdin | the fixed text | findings |
--check --stdin | findings | warnings 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:
stanza: cannot read the line width from .oxfmtrc.json, so the next source sets itStanza 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:
stanza: 2 of 3 worker threads failed to start, so the run went on without them: resource temporarily unavailableUnwritable 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:
stanza: cannot write output: no space left on deviceA 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 |
|---|---|
| 0 | clean, or nothing was selected |
| 1 | findings remain |
| 2 | a 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.