Explain
Ask which rule decides a line, and why.
stanza explain [--no-braces] [--] <file>:<line>stanza explain explains the gap that ends at a line and the braced body that starts there. It changes nothing.
A Gap
For a gap it prints the two statements, the rule that decided, what it found (the name a declaration binds and the statement that reads it, a guard, a statement spanning several lines), the rules it outranked and what --fix would do.
When either statement is a braceless two line if, for or while, or a braceless if with else, it also prints width:. This names the width in columns, its config or default source, and the joined length of each such statement. The line says whether it fits on one line. For an if with else it names the number of arms and the joined length of the widest, and says whether each arm fits on its own line.
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 explain src/load.ts:5 prints:
src/load.ts:5
gap above line 5, no blank lines
2-4 const raw = JSON.parse(
5 if (!isRecord(raw)) throw new Error("config must be an object");
rule: after-multiline, wants a blank line
because: the statement above spans lines 2 to 4
outranked: guard-join, wants no blank line: `raw` is bound on line 2 and read by the `if` below it
result: --fix adds a blank lineA Braced Body
For a single statement body it says whether --fix removes the braces or why they stay:
- code after the body could continue the statement,
- a comment sits inside the braces,
--no-braceswas given,- or a lint config file enforces braces, named in the output (see Braces and Lint Config).
Options
It takes only --no-braces. It explains a file even when --fix and --check would skip it as generated or excluded, and ends with a note saying they skip it. For a file the stanza attribute opts out, the note names the attribute.
Use -- before a path that starts with -, such as stanza explain -- -draft.ts:5. Flags must come before --. Arguments after the first -- are literal, including --no-braces and any further --. Exactly one <file>:<line> location is required.
Exit Status
| exit | meaning |
|---|---|
| 0 | something was explained |
| 1 | no gap ends and no braced body starts on that line |
| 2 | a usage error, a path that is not a regular file, a file that cannot be read or parsed, a line beyond the end of the file, a working directory stanza cannot read, or an explanation stanza cannot write |
For an a.ts file with two lines, stanza explain a.ts:99 prints this on stderr and exits 2:
stanza: a.ts has 2 lines, not 99