Stanza

Introduction

An opinionated formatter for turning function bodies into readable steps.

Stanza formats the spacing inside function bodies, the one thing other formatters leave alone, so it runs alongside them without fighting. It edits only blank lines, brace tokens and the line break under a header whose braces it removed, and it is deterministic and idempotent. Today it reads TypeScript and JavaScript.

The style is mine, hence opinionated. A function body reads as a sequence of steps, one blank line between steps, none inside a step. A fetch and the if (!response.ok) that guards it are one step. A ten line query and the return after it are two. If that is not how you read code, this tool will annoy you.

stanza --fix on a function with two guards:

function publish(draft: Draft) {
  if (!draft.title) throw new Error("title required");

  const slug = slugify(draft.title);
  if (exists(slug)) throw new Error(`${slug} is taken`);

  save(draft, slug);
  notify(draft.author);
}

Stanza is a native binary for macOS and Linux, installed from npm with Node.js or Bun. Without either, take a release binary instead.

npx @ryuugg/stanza --check src    # run once without installing
npm i -g @ryuugg/stanza           # put stanza on your PATH

Why

Agent-written code tends to arrive as one block: a forty line function without a single blank line. Writing the rules into an AGENTS.md helped less than you would think, so I turned them into a tool and run it as a hook at the end of every agent turn. It fixes what it can decide on its own and reports the rest.

Also, I just wanted to play around with oxc-parser. Everything above is a very elaborate excuse.

On this page