reladraw 0.17.1 → 0.19.0

package/README.md

@@ -43,7 +43,7 @@ npm install -g reladraw
 reladraw render diagram.reladraw -o diagram.svg
 ```
 
-`reladraw check diagram.reladraw` prints the warnings without writing a picture.
+`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns.
 
 Or from a clone, which also gets you the examples:
 
@@ -86,7 +86,7 @@ That gets you a copy of the skill at the time you run it, so you'll need to re-r
 
 ## Status
 
-Version 0.17.1. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
+Version 0.19.0. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.17.1
+# Syntax reference — 0.19.0
 
 What the language accepts. The changelog at the end lists what changed in each published version; 0.17.0's changes are large, and its entry has a table of every old spelling and what to write instead.
 
@@ -55,7 +55,7 @@ What every statement of a kind has is positional; what is optional is a key. A w
 
 **A value ends when its own shape is complete.** `height: 0.5 group height  right of a` reads a size, then a placement. `to: top, right of z` keeps `right of z` inside `to:`, because it is part of that value. So word order stays free and nothing is ambiguous.
 
-**A bracket modifies the one thing it follows.** A setting that belongs to one part of a statement is written in brackets right after that part: a placement's `(gap: wide)`, a text's `(size: small, wrap: 30)`, a line's `line: (path: square)`, a layout's `layout: column (gap: none)`, a waypoint's `b top (gap: wide)`. The scope is visible instead of inferred. Inside a bracket the comma is optional.
+**A bracket modifies the one thing it follows.** A setting that belongs to one part of a statement is written in brackets right after that part: a placement's `(gap: wide)`, a text's `(size: small, wrap: 30)`, a line's `line: (path: square)`, a layout's `layout: column (gap: none)`, a waypoint's `b top (gap: wide)`. The scope is visible instead of inferred. Inside a bracket the comma is optional, and spaces around it don't matter: `(corners: rounded,path: square)` and `(corners: rounded , path: square)` are both `(corners: rounded, path: square)`.
 
 ### Names and words
 
@@ -104,14 +104,44 @@ node <name> ["<text>" [(<text settings>)]] [<placement> | <attribute>] ...
 
 Every node has one body, the thing drawn where it is, named by one of two keys.
 
-`shape:` is the outline:
+`shape:` is the outline. A shape geometry has a word for is named by it, and takes settings in a bracket after its name for what its box doesn't decide: an amount, in the file's unit, and a direction, whose first word below is the default.
+
+| shape | draws | its bracket |
+|---|---|---|
+| `rectangle` | the plain box, its corners rounded unless `corners: sharp`; the default | |
+| `document` | the box with its top-right corner folded, for an artifact rather than a process; its other corners follow `corners:` | `fold:` |
+| `circle` | a circle sized to hold its text; given a `width:` and a `height:` that differ, an ellipse | |
+| `diamond` | a diamond, a flowchart's decision | |
+| `pill` | a box with both ends round, a flowchart's start or end | |
+| `parallelogram` | a slanted box, a flowchart's input or output | `slant:`, `lean: right \| left` |
+| `hexagon` | a box with pointed ends, a flowchart's preparation | `point:` |
+| `trapezoid` | a box narrower at one end, a flowchart's manual operation | `taper:`, `narrow: bottom \| top` |
+| `triangle` | a triangle, a flowchart's merge (down) or extract (up) | `aim: down \| up \| left \| right` |
+| `cylinder` | a cylinder standing, or `lying` on its side, for stored data | `cap:`, `lying` |
+| `none` | no outline, fill or padding: bare text, or an invisible container | |
+
+```
+node in    "read input"  shape: parallelogram (slant: 2, lean: left)
+node queue "queue"       shape: cylinder (cap: 1.5, lying)  right of in
+node flat  "valid?"      shape: diamond  width: 20  height: 5  below in
+```
+
+A flowchart shape geometry has no word for is named `flow-` and what it means, and drawn the way the flowchart standard draws it, with no settings:
 
 | shape | draws |
 |---|---|
-| `rectangle` | the plain box, its corners rounded unless `corners: sharp`; the default |
-| `document` | the box with its top-right corner folded, for an artifact rather than a process; its other corners follow `corners:` |
-| `circle` | a circle sized to hold its text, always round |
-| `none` | no outline, fill or padding: bare text, or an invisible container |
+| `flow-subprocess` | a step drawn as its own chart: a box with a bar inside each side |
+| `flow-document` | a document as the standard draws it, its bottom wavy |
+| `flow-off-page` | continued on another page: a box pointed at the bottom |
+| `flow-delay` | a delay or a wait: a box with its right end round |
+| `flow-manual-input` | typed in by hand: a box whose top slopes |
+| `flow-stored-data` | the standard's other storage: curved ends, the right one hollow |
+| `flow-loop-start`, `flow-loop-end` | the start and end of a loop: a box with two corners cut, at the top or the bottom |
+| `flow-card` | a punched card: a box with its top-left corner cut |
+| `flow-display` | a screen: pointed on the left, round on the right |
+| `flow-tape` | magnetic tape: a circle with a tail |
+| `flow-punched-tape` | paper tape: wavy top and bottom |
+| `flow-collate` | collate: two triangles point to point, its text on a patch where they meet |
 
 `icon:` is a picture the node is drawn *as*, with no box:
 
@@ -131,11 +161,15 @@ node aside "Written by a nightly cron job." (wrap: 30)  shape: none  below dump
 node svc  icon: cube  right of dump
 ```
 
-Writing both keys is an error naming both. An unknown name is refused with the whole set. A name says what a thing is, never what the picture looks like: `document`, not `folded-corner`. The exception is a picture with no single meaning, such as `circle` or `cube`.
+Writing both keys is an error naming both. An unknown name is refused with the whole set, and so is a setting the shape doesn't take. A shape is named for how it looks, `diamond` and never `decision`, and no picture has two names. An icon is named for what it is: `package`, not `open-box`.
+
+**Size and text.** A shape grows until its text, with its padding, fits at the shape's middle, the center of its area: a diamond is twice the padded text each way, and a triangle's text sits a third of the way from its base. A stated `width:` and `height:` stretch the shape to fill them, which is how a diamond is made flatter; a text that no longer fits is drawn as it is and reported as `text-overflow`. The text-position words of a [node's text](#where-it-sits), such as `(inside bottom)`, move it off the middle. `flow-collate`'s text sits on a patch of its own fill where its two triangles meet; `(fill: none)` in the text's bracket draws it without one.
+
+**Sides.** A side of a shape is the stretch of its outline between the lines from its middle to two corners of its box: a rectangle's sides, a circle's quarters, and on a diamond the stretch round each point. So `from: right` leaves a diamond from its right point, as a flowchart's "no" does, and means the same on every shape. A corner such as `top-right` is where the line from the middle to that corner of the box meets the outline: on a circle halfway between its sides, on a diamond the middle of an edge. Several line ends on one side spread along it.
 
-A picture can't contain anything. A `shape: none` node with children is an invisible container ([Containers](#containers)). A circle can hold other nodes, centered in it. A side of a circle is the quarter of it about that compass point, so `from: right` means the same on every shape; several line ends on one side spread round that arc, each meeting the circle square on.
+A picture can't contain anything. A `shape: none` node with children is an invisible container ([Containers](#containers)). A circle can hold other nodes, centered in it; the other shapes don't hold nodes yet, and one with children is refused.
 
-**Corners.** `corners: sharp` draws a box's corners square, and `corners: rounded`, the default, draws them as they always were. It is the same word and values as a line's `corners:`. It reaches every outline with corners: a rectangle, a container, and a document's three round corners, whose fold stays as it is. A circle has none, so `corners:` written on a circle is refused; from a style or a default it lands only on the nodes with corners. A picture and bare text have no outline, so they refuse it too. Like a color, it never moves anything.
+**Corners.** `corners: sharp` draws a box's corners square, and `corners: rounded`, the default, draws them as they always were. It is the same word and values as a line's `corners:`. It reaches every outline with corners that round: a rectangle, a container, a `flow-subprocess`, and a document's three round corners, whose fold stays as it is. Every other shape is drawn with its points sharp, so `corners:` written on one is refused; from a style or a default it lands only on the nodes it can. A picture and bare text have no outline, so they refuse it too. Like a color, it never moves anything.
 
 ```
 style plain  corners: sharp
@@ -324,7 +358,7 @@ left-center   center          right-center
 bottom-left   bottom-center   bottom-right
 ```
 
-**A side is a segment and a point is a point.** Bare `top` is the whole side; `top-center` is the one point halfway along it, which is why every midpoint carries `-center`. Naming a side leaves the other axis free. On a circle, a corner is the point on the circle halfway between its two sides.
+**A side is a segment and a point is a point.** Bare `top` is the whole side; `top-center` is the one point halfway along it, which is why every midpoint carries `-center`. Naming a side leaves the other axis free. On any shape but a box, a point is where the line from the shape's middle toward that point of its box meets the outline ([Sides](#the-body)): on a circle a corner is halfway between its two sides.
 
 A part is written as the name, then the part: `b top`, `e bottom-left`, `hub text`.
 
@@ -588,6 +622,7 @@ node aside "Written nightly." (size: small, wrap: 30)  shape: none
 | `size` | `small`, `normal` or `large`; a multiple of normal (`1.2`); or pixels (`16px`) |
 | `wrap` | a count of characters to fold at, on top of ` / ` |
 | `align` | how the text's own lines range: `left`, `center`, `right`, or where along a side for a title (below) |
+| `fill` | on a `flow-collate` only, the patch behind its text: a color, or `none` |
 
 `small` is 21/25 of normal and `large` the same step the other way. The names are preferred: bundled into a style, a size says *why* one text is smaller. `wrap:` is a character count, not a distance: it is how a text is made narrow and tall to sit beside something.
 
@@ -1127,6 +1162,59 @@ reladraw check diagram.reladraw
 
 The output is a standalone SVG: every picture is drawn into it as path data, never from a font or a linked file. A web page can draw a diagram in place with `<reladraw-diagram>`; see "In a web page" in the README.
 
+### Formatting
+
+```
+reladraw format diagram.reladraw other.reladraw
+reladraw format --check diagram.reladraw
+reladraw format - < diagram.reladraw
+reladraw format --init
+```
+
+`format` lays each file out again in place. By default every statement is on one line, and neighboring statements with the same keyword line their clauses up in columns, each as wide as its longest clause plus two spaces; a blank line or a new keyword starts a new set of columns, and a comment line between them doesn't. A comment at the end of a line lines up with the others in its set. A statement written over several lines with a comment among them keeps its lines, with the indent tidied. Blank lines stay as written, and so do Windows line endings.
+
+Inside a clause, spacing comes out as these pages write it, whatever was typed: one space after a key's colon and between words, none just inside a bracket, and a comma against the word before it, so `line:( corners:rounded , path:square )` becomes `line: (corners: rounded, path: square)`.
+
+Only whitespace changes, and the order of clauses when `clause-order` asks: every word is copied as it was written, and the result is checked to draw exactly what the original did. A file that doesn't parse is reported and left alone, and the other files still run. `--check` changes nothing, prints each file that would change, and fails if there is one, for a pre-commit hook or CI. A shell expands `*.reladraw` into the files; folders aren't searched.
+
+`-` in place of the files reads the diagram from standard input and prints it formatted, touching no file. That is how an editor formats a buffer, saved or not: Vim's `:%!reladraw format -`, or the command a format-on-save package runs. Its settings come from the nearest `.reladraw-format` to the current folder.
+
+The settings are in the nearest `.reladraw-format`, in the file's folder or a folder above it; with none, the defaults. A project that puts one at its top keeps everyone's formatting the same. `reladraw format --init` writes one in the current folder with every setting at its default and a comment on what each value does, and refuses if one is there already. One setting a line, as in a diagram:
+
+```
+// keep each clause straight after the last
+columns: off
+clause-gap: 2
+```
+
+| setting | values, default first |
+|---|---|
+| `wrap-at` | `off`, or a number of characters: past it, a statement wraps onto as few lines as fit |
+| `clause-per-line-at` | `off`, a number of characters, or `always`: past it, every clause gets its own line |
+| `first-line` | `text` (keyword, name and texts), `name`: where a broken statement's first line ends |
+| `clause-order` | `as-written`, or a list of kinds: `placement`, and keys by name, such as `style, placement, fill` |
+| `columns` | `aligned`, `off` |
+| `columns-shared-by` | `same-keyword-neighbors`, `neighbors`, `same-keyword` (across blank lines), `file` |
+| `clause-gap` | a number of spaces, `2`; or `tab`, with `columns: off` only |
+| `trailing-comments` | `shared-column`, `after-statement` |
+| `comments-inside` | `keep-lines`, `move-above` (joined, comments above it), `refuse` (left alone, comment named) |
+| `continued-lines-indent` | where a broken or kept statement's later lines start: `4` or another number, `tab`, `under-name`, `under-name + 2`, `under-text` (under the name when there's no text) |
+| `blank-lines` | `as-written`, `exactly 2`, `at-most 3` |
+| `edge-name-and-ends` | `one-column`, `own-columns` (name, each end and the arrow a column each) |
+
+An unknown setting, one written twice, or a value it doesn't take is an error naming it.
+
+**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured on its own, before columns, so whether it breaks never depends on its neighbors; its first line still lines up with theirs. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
+
+```
+// wrap-at: 60
+node  confirm  "Confirm"
+    below accept (gap: tight)  left of accept (gap: wide)
+    style: plain
+```
+
+**Ordering clauses.** `clause-order` lists the kinds of clause in the order they are written: `placement` for every relation, and a key by its name (`style`, `fill`, `via`). Kinds it leaves out follow, in the order written, and clauses of one kind keep theirs. A node's or edge's texts never move, since the language takes them only straight after the name; `text` in the list means a style's `text:` key. A clause never moves where moving it would change what the statement says.
+
 ## Attributes
 
 Every attribute, and what takes one. A node's kind is what its body is: a box (`shape:`), a picture (`icon:`) or bare text (`shape: none`).
@@ -1139,7 +1227,7 @@ Every attribute, and what takes one. A node's kind is what its body is: a box (`
 | `badge` | ✓ | | | | a picture joined to the text |
 | `cards` | ✓ | | | | a deck's cards, when they are only texts, front first |
 | `fill`, `border` | ✓ | | | | colors |
-| `corners` | ✓ | | | | `sharp` or `rounded`; not on a circle. A line's go in `line: (…)` |
+| `corners` | ✓ | | | | `sharp` or `rounded`; only on a box's outline. A line's go in `line: (…)` |
 | `text` | ✓ | ✓ | ✓ | ✓ | in a style only; on a statement, the bracket after the text |
 | `layout` | ✓ | | ✓ | | how the children are arranged |
 | `gather-children` | ✓ | | ✓ | | where the children sit in spare room |
@@ -1193,6 +1281,21 @@ Designed and absent from the code.
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal is refused by name with the replacement quoted, rather than dropped in silence: an older file stops with an error saying what to write instead.
 
+**0.19.0**
+
+- **`reladraw format`** lays a file out again: each statement on one line, neighboring statements with the same keyword lined up in columns, comments kept beside what they are about. No word is respelled, and the result is checked to draw what the original did. `--check` fails on a file that would change, and `.reladraw-format` holds a project's settings; `reladraw format --init` writes one with every setting explained. `reladraw format -` reads standard input and prints the result, for editors. A long statement can wrap past a width (`wrap-at`) or go one clause to a line (`clause-per-line-at`), and `clause-order` puts placements and keys in a chosen order. The playground has a Format button (Shift+Alt+F, undone with Ctrl+Z) and a panel for its settings, which can copy them as a `.reladraw-format`. Spacing inside a clause is evened out too: `gap:tight` becomes `gap: tight`, `( gap: tight )` becomes `(gap: tight)`. Prompted by #14, where a long statement was hard to read in a plain editor.
+- **A comma may touch the next word or stand apart from both.** `(corners: rounded,path: square)` used to be refused with "`corners` has no value", and `(at: start , above edge)` was refused in a text's bracket; both now read as `rounded, path:` and `start, above` do.
+- **The playground opens and saves `.reladraw` files**, with Open… and Save… above the source. Save suggests the name of the file last opened or saved; Chrome and Edge ask where to put it, other browsers save it with the downloads. Opening a file over edits that haven't been saved to one asks first.
+- **The playground's error message can be copied**, with a Copy button beside it or by selecting it. Only the underlined line number jumps to the line now; a click anywhere on the message used to, which took a selection away.
+- **The playground no longer fails on some diagrams with 0.18.0's shapes**, which stopped with "insidePolygon is not defined". The command line was unaffected.
+- **The agent skill checks it matches the installed tool.** It compares its own version with `reladraw --version` and tells the user which of the two to update.
+
+**0.18.0**
+
+- **More shapes, for flowcharts and the rest** (#18): `diamond`, `pill`, `parallelogram`, `hexagon`, `trapezoid`, `triangle` and `cylinder`, named for how they look, and the flowchart standard's shapes that have no geometric name as `flow-` and what they mean, from `flow-subprocess` and `flow-delay` to `flow-collate`. A shape's settings go in a bracket after its name: `shape: parallelogram (slant: 2, lean: left)`, `shape: cylinder (lying)`, `shape: document (fold: 1.5)`.
+- **A shape grows to hold its text at its middle**, and a stated `width:` and `height:` stretch it. Its sides are the stretches of outline round its points, so `from: right` leaves a diamond from its right point.
+- **A circle given a `width:` and a `height:` that differ is an ellipse.** It used to stay round and say nothing about the height.
+
 **0.17.1**
 
 - **`reladraw --version`**, or `-v`, prints the version.

package/dist/checks.js

@@ -9,7 +9,8 @@
  */
 import { isWithin, joinedToText } from './model.js';
 import { ARROW_MARKER_WIDTH, LINE_WIDTH, UNIT, arrowLength } from './constants.js';
-import { crossingPoints, describeEdge, planSides, traceRoute, traceVisible } from './lines.js';
+import { centerOf, crossingPoints, describeEdge, faceOfNode, planSides, traceRoute, traceVisible } from './lines.js';
+import { clearOf, insideOutline, sizeFor } from './outline.js';
 import { placeLineTexts } from './linetexts.js';
 /**
  * The kinds of finding, each with whether it is on when nothing says. Named in
@@ -135,8 +136,8 @@ function edgeNodeOverlaps(layout, routes) {
             if (holdsEnd(node, edge))
                 continue;
             const inner = { x: node.x + 1, y: node.y + 1, width: node.width - 2, height: node.height - 2 };
-            const round = node.body.kind === 'shape' && node.body.outline === 'circle';
-            const through = round ? crossingCircle(trace, node) : crossing(trace, inner);
+            const face = faceOfNode(node);
+            const through = face.round || face.outline ? crossingCircle(trace, node, face) : crossing(trace, inner);
             if (through === undefined)
                 continue;
             const own = node === edge.from || node === edge.to;
@@ -249,14 +250,18 @@ function crossing(trace, box) {
     return { enters, leaves };
 }
 /**
- * The same for a circle, which is drawn in its node's square: walked a couple
- * of pixels at a time, a point counting as inside only past a pixel within the
- * outline, so a line ending on the circle doesn't cross it.
+ * The same for a circle, or any outline but a rectangle's, which is drawn in
+ * its node's box: walked a couple of pixels at a time, a point counting as
+ * inside only past a pixel within the outline, so a line ending on it doesn't
+ * cross it.
  */
-function crossingCircle(trace, node) {
+function crossingCircle(trace, node, face) {
     const radius = node.width / 2 - 1;
-    const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
-    const inside = (p) => Math.hypot(p.x - center.x, p.y - center.y) < radius;
+    const center = centerOf(face);
+    const polygon = face.outline;
+    const inside = polygon
+        ? (p) => insideOutline(polygon, p) && clearOf(polygon, p, 1)
+        : (p) => Math.hypot(p.x - center.x, p.y - center.y) < radius;
     const sideAt = (p) => {
         const dx = p.x - center.x;
         const dy = p.y - center.y;
@@ -564,6 +569,22 @@ function textOverflows(layout) {
         const place = node.textAttrs['place'];
         if (place !== undefined && place !== 'center' && !place.startsWith('inside'))
             continue;
+        const face = faceOfNode(node);
+        if (face.outline && node.body.outline !== 'flow-collate') {
+            // Any other outline than a box's: the text spills where it passes the outline.
+            const { outline, look } = node.body;
+            const corners = [0, 0.5, 1].flatMap((fx) => [0, 0.5, 1].map((fy) => ({ x: node.x + text.x + text.width * fx, y: node.y + text.y + text.height * fy })));
+            if (corners.every((p) => insideOutline(face.outline, p)))
+                continue;
+            const needs = sizeFor(outline, look, text.width, text.height);
+            const wider = Math.max(0, needs.width - node.width);
+            const taller = Math.max(0, needs.height - node.height);
+            const more = [wider > EPSILON ? `${units(wider)} more width` : '', taller > EPSILON ? `${units(taller)} more height` : ''].filter((part) => part.length > 0);
+            found.push(new Finding('text-overflow', `the text of node ${node.name} runs past the outline of its ${outline}` + (more.length > 0 ? `; it needs ${more.join(' and ')}` : ''), node.line));
+            continue;
+        }
+        if (node.body.outline === 'flow-collate')
+            continue;
         const spill = {
             left: Math.max(0, -text.x),
             right: Math.max(0, text.x + text.width - node.width),

package/dist/cli.js

@@ -4,17 +4,32 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { nearMatch, readChecks } from './checks.js';
 import { SourceError } from './errors.js';
+import { format } from './format.js';
+import { DEFAULT_FORMAT, readFormatSettings, SETTINGS_FILE, settingsFileText } from './format-settings.js';
 import { draw } from './index.js';
 import { THEME_NAMES, THEMES } from './themes.js';
 const USAGE = `reladraw — draw a diagram from stated placement
 
   reladraw render <input.reladraw> [-o <output.svg>] [options]
   reladraw check <input.reladraw> [options]
+  reladraw format <input.reladraw>... [--check]
+  reladraw format - [--check]
+  reladraw format --init
 
   render      draw the diagram to an SVG, and print any findings: places
               where the picture, drawn as written, may not read as meant.
   check       lay the diagram out and print only the findings. No SVG is
               written, so a good one is left alone while you iterate.
+  format      lay each file out again in place: spacing, columns, comments
+              and blank lines. No word is respelled, and a file that
+              doesn't parse is left alone. The nearest .reladraw-format, in
+              the file's folder or one above it, holds the settings.
+              --check changes nothing, and fails if a file would change.
+              - reads the diagram from standard input and prints it
+              formatted, for an editor; settings come from the current
+              folder up.
+              --init writes a .reladraw-format here, every setting at its
+              default with what it does.
 
   -o, --out   where render writes the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
@@ -29,7 +44,7 @@ const USAGE = `reladraw — draw a diagram from stated placement
               print the version.
   -h, --help  print this.
 `;
-const COMMANDS = ['render', 'check'];
+const COMMANDS = ['render', 'check', 'format'];
 async function main(argv) {
     if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
         process.stdout.write(USAGE);
@@ -56,6 +71,8 @@ async function main(argv) {
         return 1;
     }
     const command = verb;
+    if (command === 'format')
+        return formatFiles(argv.slice(1));
     let input;
     let out;
     let theme;
@@ -172,6 +189,176 @@ async function main(argv) {
     process.stderr.write(`${target}\n`);
     return 0;
 }
+/**
+ * `reladraw format`: each file laid out again in place, by the settings in
+ * the nearest `.reladraw-format`. A file that fails is reported and the rest
+ * still run, so one broken file doesn't hide the state of the others.
+ */
+async function formatFiles(args) {
+    const files = [];
+    let check = false;
+    let init = false;
+    for (const arg of args) {
+        if (arg === '--check')
+            check = true;
+        else if (arg === '--init')
+            init = true;
+        else if (arg.startsWith('-') && arg !== '-') {
+            process.stderr.write(`reladraw: format takes --check and --init, not ${arg}\n`);
+            return 1;
+        }
+        else
+            files.push(arg);
+    }
+    if (init) {
+        if (check || files.length > 0) {
+            process.stderr.write('reladraw: --init writes a settings file and formats nothing — run reladraw format --init on its own\n');
+            return 1;
+        }
+        if (existsSync(SETTINGS_FILE)) {
+            process.stderr.write(`reladraw: there is already a ${SETTINGS_FILE} here — delete it first to write a fresh one\n`);
+            return 1;
+        }
+        await writeFile(SETTINGS_FILE, settingsFileText(), 'utf8');
+        process.stderr.write(`${resolvePath(SETTINGS_FILE)}\n`);
+        return 0;
+    }
+    if (files.length === 0) {
+        process.stderr.write('reladraw: no input file — reladraw format <input.reladraw>..., or - to read standard input\n');
+        return 1;
+    }
+    if (files.includes('-'))
+        return formatStandardInput(files, check);
+    let status = 0;
+    const found = new Map();
+    for (const file of files) {
+        let settings = DEFAULT_FORMAT;
+        try {
+            const nearest = nearestSettings(dirname(resolvePath(file)), found);
+            if (nearest)
+                settings = nearest.settings;
+        }
+        catch (error) {
+            if (!(error instanceof SettingsError))
+                throw error;
+            process.stderr.write(`${error.cause.format(error.path)}\n`);
+            status = 1;
+            continue;
+        }
+        let source;
+        try {
+            source = await readFile(file, 'utf8');
+        }
+        catch {
+            process.stderr.write(`reladraw: can't read ${file}\n`);
+            status = 1;
+            continue;
+        }
+        let laid;
+        try {
+            laid = format(source, settings);
+        }
+        catch (error) {
+            process.stderr.write(error instanceof SourceError ? `${error.format(file)}\n` : `reladraw: ${file}: ${error.message}\n`);
+            status = 1;
+            continue;
+        }
+        if (laid === source)
+            continue;
+        if (check) {
+            process.stderr.write(`${file}: not formatted — reladraw format ${file} lays it out\n`);
+            status = 1;
+            continue;
+        }
+        await writeFile(file, laid, 'utf8');
+        process.stderr.write(`formatted ${file}\n`);
+    }
+    return status;
+}
+/**
+ * `reladraw format -`: the diagram read from standard input and printed
+ * formatted, which is how an editor formats a buffer it hasn't saved. The
+ * settings are the nearest `.reladraw-format` from the current folder. With
+ * `--check` nothing is printed, and it fails if the text would change.
+ */
+async function formatStandardInput(files, check) {
+    if (files.length > 1) {
+        process.stderr.write('reladraw: - reads standard input, so it goes on its own — reladraw format -\n');
+        return 1;
+    }
+    if (process.stdin.isTTY) {
+        process.stderr.write('reladraw: format - reads a diagram from standard input — pipe one in: reladraw format - < diagram.reladraw\n');
+        return 1;
+    }
+    let settings = DEFAULT_FORMAT;
+    try {
+        settings = nearestSettings(process.cwd(), new Map())?.settings ?? DEFAULT_FORMAT;
+    }
+    catch (error) {
+        if (!(error instanceof SettingsError))
+            throw error;
+        process.stderr.write(`${error.cause.format(error.path)}\n`);
+        return 1;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const source = Buffer.concat(chunks).toString('utf8');
+    let laid;
+    try {
+        laid = format(source, settings);
+    }
+    catch (error) {
+        process.stderr.write(error instanceof SourceError ? `${error.format('<stdin>')}\n` : `reladraw: <stdin>: ${error.message}\n`);
+        return 1;
+    }
+    if (check) {
+        if (laid === source)
+            return 0;
+        process.stderr.write('<stdin>: not formatted\n');
+        return 1;
+    }
+    process.stdout.write(laid);
+    return 0;
+}
+/** A `.reladraw-format` that doesn't read, and where it is. */
+class SettingsError extends Error {
+    path;
+    cause;
+    constructor(path, cause) {
+        super(cause.message);
+        this.path = path;
+        this.cause = cause;
+    }
+}
+/**
+ * The settings in the nearest `.reladraw-format`, looking in `folder` and
+ * then each folder above it, or nothing when there is none. Each folder is
+ * looked in once however many files share it.
+ */
+function nearestSettings(folder, found) {
+    const known = found.get(folder);
+    if (known !== undefined)
+        return known;
+    const path = resolvePath(folder, SETTINGS_FILE);
+    let result;
+    if (existsSync(path)) {
+        try {
+            result = { path, settings: readFormatSettings(readFileSync(path, 'utf8')) };
+        }
+        catch (error) {
+            if (error instanceof SourceError)
+                throw new SettingsError(path, error);
+            throw error;
+        }
+    }
+    else {
+        const parent = dirname(folder);
+        result = parent === folder ? null : nearestSettings(parent, found);
+    }
+    found.set(folder, result);
+    return result;
+}
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
     process.stderr.write(`reladraw: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(1);

package/dist/format-settings.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How `reladraw format` lays a file out. Each key is a setting as it is
+ * written in a `.reladraw-format` file, so an error, the generated file and
+ * the code all use one name for each.
+ */
+export interface FormatSettings {
+    'wrap-at': 'off' | number;
+    'clause-per-line-at': 'off' | 'always' | number;
+    'first-line': 'text' | 'name';
+    'continued-lines-indent': number | 'tab' | 'under-name' | 'under-text' | {
+        underName: number;
+    };
+    'clause-order': 'as-written' | string[];
+    'clause-gap': number | 'tab';
+    columns: 'aligned' | 'off';
+    'columns-shared-by': 'same-keyword-neighbors' | 'neighbors' | 'same-keyword' | 'file';
+    'comments-inside': 'keep-lines' | 'move-above' | 'refuse';
+    'trailing-comments': 'shared-column' | 'after-statement';
+    'blank-lines': 'as-written' | {
+        exactly: number;
+    } | {
+        atMost: number;
+    };
+    'edge-name-and-ends': 'one-column' | 'own-columns';
+}
+/** One setting: what it controls, its values in words, and how to read one. */
+interface Setting {
+    name: keyof FormatSettings;
+    /** One sentence for the generated file: what the setting controls. */
+    about: string;
+    /** Each value as written, and what it means. The first is the default. */
+    values: [string, string][];
+    /** The default, as written. */
+    written: string;
+    /** The value as written, read; a string thrown is the reason it is refused. */
+    read: (value: string) => FormatSettings[keyof FormatSettings];
+}
+/**
+ * The kinds of clause `clause-order` can list: a statement's texts, its
+ * placements, and each key by its own name. `text` is also a style's `text:`
+ * key, which is a style's way of saying what a text says.
+ */
+export declare const CLAUSE_KINDS: readonly string[];
+export declare const SETTINGS: Setting[];
+export declare const DEFAULT_FORMAT: FormatSettings;
+/** The file a project's settings are written in. */
+export declare const SETTINGS_FILE = ".reladraw-format";
+/**
+ * Read a `.reladraw-format` file: one `key: value` setting a line, `//`
+ * comments, blank lines. An unknown setting, one written twice, or a value it
+ * doesn't take is refused by name, with the line.
+ */
+export declare function readFormatSettings(text: string): FormatSettings;
+/**
+ * The `.reladraw-format` that `reladraw format --init` writes: every setting
+ * at its default, each under a comment saying what it controls and what each
+ * of its values means.
+ */
+export declare function settingsFileText(): string;
+export {};