Pillar 03 · The polish
Diff stability
A one-line change is a one-line diff. One canonical format, one element per line, trailing commas, no reflow — so a review shows the change that was made, not the churn around it.
Review is reading diffs
Almost everything we trust about a change — the review, the blame, the revert, the bisect — is built on the diff. So the diff's signal-to-noise ratio is the real currency. In most codebases it's terrible: a formatter reflows a wrapped line, an import-sorter reshuffles a block, a rename touches every call site's whitespace, and the one line that matters is buried in fifty that don't.
Agents make this sharply worse. Given a small task, a model will happily rewrite a whole function — or a whole file — to change one thing, because regenerating is easier for it than editing surgically. The reviewer is left to diff a rewrite against the original and hope the only real change is the intended one. Glyph is built so that the layout gives the model nothing to churn.
01 One canonical layout, no choices
glyph fmt reprints every file in a single fixed layout: two-space indent, one
element per line once there's more than a couple, a trailing comma on every multi-line list,
and no reflow — the formatter never repacks your elements to fit a
line width. Because there's exactly one legal shape, there's nothing to argue about and
nothing for a tool to "fix" on the side. Adding a field is a single added line.
- type User = { id: number, name: - string } + type User = { id: number, name: + string, email: string }
type User = {
id: number,
name: string,
+ email: string,
}
The trailing comma is doing quiet work: because the last element already ends in a comma, adding a sibling never edits the line above it. One insertion, one line.
02 Order is stable, so history is legible
One element per line means reordering, inserting, or removing an item touches only that
item's lines — never its neighbours. git blame stays meaningful:
each line's last-touched commit is the commit that actually changed that element,
not the formatting pass that happened to repack the row it shared.
03 No barrel files — no import churn
Because imports never re-export and there are no index.ts aggregation layers
(E0102), adding or moving a symbol doesn't ripple through a barrel that every
consumer imports. The dependency edges you edit are the ones you meant to; the rest of the
import graph doesn't move.
04 Generation is idempotent, not a blob
The same discipline extends to generated code. glyph gen and
glyph regen reprint their output through the canonical formatter, so
regenerating after a spec change produces a minimal diff you can actually review
— a couple of changed lines, not a wholesale replacement of a machine-written file.
And every emitted .ts ships a source map, so even the compiled output traces
cleanly back to the line you changed.
type Task = {
id: number,
title: string,
+ done: bool,
}
// glyph regen re-ran the recorded command; this is the whole diff.
Diff stability is what turns "the agent changed something" into "the agent changed exactly this." When the noise floor is zero, review is fast and trust is cheap.
The benchmark — coming
The number that captures this is diff size per logical change: how many lines move when you make one intended edit, in Glyph versus an equivalent TypeScript change run through a typical formatter. Glyph isn't in real-world use yet, so the chart below is a placeholder that fills in with real measurements once there's real history to draw from.
TypeScript vs Glyph
It costs a little freedom — you don't get to hand-pack a line the way you like — and buys a lot of legibility in return. That's the trade every polish pillar makes: give up a choice that didn't matter to keep a signal that does.