reladraw 0.16.0 → 0.17.0

package/dist/cli.js

@@ -1,31 +1,62 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 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 { compile } from './index.js';
+import { draw } from './index.js';
 import { THEME_NAMES, THEMES } from './themes.js';
-const USAGE = `reladraw — render a diagram from stated placement
+const USAGE = `reladraw — draw a diagram from stated placement
 
-  reladraw <input.reladraw> [-o <output.svg>] [--theme <name>]
+  reladraw render <input.reladraw> [-o <output.svg>] [options]
+  reladraw check <input.reladraw> [options]
 
-  -o, --out   where to write the SVG. Defaults to the input path with
+  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.
+
+  -o, --out   where render writes the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
   --theme     render in this theme, whatever the file's \`diagram theme:\`
               says. One of ${THEME_NAMES.join(', ')}.
+  --guides    draw the guides: everything written with \`guide\` in front,
+              dashed, to see how the picture is built.
+  --checks    turn kinds of finding on or off, over what the file says:
+              --checks "edge-crossings: on, node-overlap: off"
+  --no-checks print no findings. Errors still print.
   -h, --help  print this.
 `;
+const COMMANDS = ['render', 'check'];
 async function main(argv) {
     if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
         process.stdout.write(USAGE);
         return argv.length === 0 ? 1 : 0;
     }
+    const verb = argv[0];
+    if (!COMMANDS.includes(verb)) {
+        // A file where the command goes is the old form, and is told the new one;
+        // anything else is a command that does not exist, with the near one.
+        if (/\.reladraw$/.test(verb) || existsSync(verb)) {
+            process.stderr.write(`reladraw: a command comes first — reladraw render ${argv.join(' ')}\n`);
+        }
+        else {
+            const near = nearMatch(verb, COMMANDS);
+            process.stderr.write(`reladraw: there is no command "${verb}"` +
+                (near ? ` — did you mean ${near}?\n` : ` — the commands are ${COMMANDS.join(', ')}\n`));
+        }
+        return 1;
+    }
+    const command = verb;
     let input;
     let out;
     let theme;
-    for (let i = 0; i < argv.length; i += 1) {
+    let checks;
+    let noChecks = false;
+    let guides = false;
+    for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
-        if (arg === '-o' || arg === '--out') {
+        if ((arg === '-o' || arg === '--out') && command === 'render') {
             out = argv[i + 1];
             if (out === undefined) {
                 process.stderr.write('reladraw: -o needs a path\n');
@@ -33,6 +64,10 @@ async function main(argv) {
             }
             i += 1;
         }
+        else if (arg === '-o' || arg === '--out') {
+            process.stderr.write('reladraw: check writes no SVG, so it takes no -o; reladraw render writes one\n');
+            return 1;
+        }
         else if (arg === '--theme') {
             theme = argv[i + 1];
             if (theme === undefined) {
@@ -45,6 +80,20 @@ async function main(argv) {
             }
             i += 1;
         }
+        else if (arg === '--checks') {
+            checks = argv[i + 1];
+            if (checks === undefined) {
+                process.stderr.write('reladraw: --checks needs a list, such as --checks "edge-crossings: on"\n');
+                return 1;
+            }
+            i += 1;
+        }
+        else if (arg === '--no-checks') {
+            noChecks = true;
+        }
+        else if (arg === '--guides') {
+            guides = true;
+        }
         else if (arg.startsWith('-') && arg !== '-') {
             process.stderr.write(`reladraw: unknown option ${arg}\n`);
             return 1;
@@ -58,17 +107,40 @@ async function main(argv) {
         }
     }
     if (input === undefined) {
-        process.stderr.write('reladraw: no input file\n');
+        process.stderr.write(`reladraw: no input file — reladraw ${command} <input.reladraw>\n`);
+        return 1;
+    }
+    if (noChecks && checks !== undefined) {
+        process.stderr.write('reladraw: --no-checks and --checks say opposite things; give one\n');
+        return 1;
+    }
+    if (noChecks && command === 'check') {
+        process.stderr.write('reladraw: check with --no-checks would print nothing; reladraw render draws\n');
         return 1;
     }
+    // Read once here, so a mistake in --checks is reported before the file is drawn.
+    let overChecks;
+    if (checks !== undefined) {
+        const written = checks;
+        try {
+            readChecks(written, {});
+        }
+        catch (error) {
+            process.stderr.write(`reladraw: --checks: ${error.message}\n`);
+            return 1;
+        }
+        overChecks = (fromFile) => readChecks(written, fromFile);
+    }
     const source = await readFile(input, 'utf8');
-    let svg;
+    let drawn;
     try {
-        svg = compile(source, {
+        drawn = draw(source, {
             ...(theme === undefined ? {} : { theme: THEMES[theme] }),
+            ...(guides ? { guides: true } : {}),
             // An icon's file is found from the diagram, not from wherever the tool
             // happens to be run.
             readIconFile: (path) => readFileSync(resolvePath(dirname(input), path), 'utf8'),
+            ...(noChecks ? { checks: false } : overChecks ? { checks: overChecks } : {}),
         });
     }
     catch (error) {
@@ -78,13 +150,17 @@ async function main(argv) {
         }
         throw error;
     }
+    for (const finding of drawn.findings)
+        process.stderr.write(`${finding.format(input)}\n`);
+    if (command === 'check')
+        return 0;
     if (out === '-') {
-        process.stdout.write(svg);
+        process.stdout.write(drawn.svg);
         return 0;
     }
     const target = resolvePath(out ?? input.replace(/\.[^.]+$/, '') + '.svg');
     await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, svg, 'utf8');
+    await writeFile(target, drawn.svg, 'utf8');
     process.stderr.write(`${target}\n`);
     return 0;
 }

package/dist/constants.d.ts

@@ -4,21 +4,24 @@ import type { Measurer } from './measure.js';
 import { type Line } from './text.js';
 /** Inside a box, between its border and its contents. */
 export declare const PAD = 14;
-/** Between stacked children of one container. */
-export declare const CHILD_GAP = 10;
+/**
+ * The file's unit, in pixels: about a quarter of an ordinary one-line box, so
+ * the gap words land near whole numbers. Findings measure in it. Provisional
+ * until the gap words are measured against it.
+ */
+export declare const UNIT = 12;
 /** Between a container's own text and its first child. */
 export declare const HEADER_GAP = 10;
 /**
- * How far each deck copy is offset behind the front face. It has to clear a
- * whole line of text plus the padding above it, or a copy's text is drawn and
- * then immediately covered by the copy in front of it.
+ * How far each card of a deck sits up and to the left of the one in front. It
+ * has to clear a whole line of text plus the padding above it, or a card's
+ * text is drawn and then immediately covered by the card in front of it.
  */
 export declare const DECK_STEP = 34;
 /**
- * The named gaps a placement may ask for, each a *minimum* distance rather than a
- * fixed one. Anything the author puts between two things widens the space
- * between them on its own, so no gap here ever has to be chosen large enough
- * to leave room for something else.
+ * The named gaps a placement may ask for, each an exact distance in whole
+ * units. Chosen 2026-10-14 against today's spacing: 2, 4 and 8 units keep the
+ * old look, where 1, 2 and 3 left a line barely longer than its arrowhead.
  */
 export declare const GAPS: Record<string, number>;
 /**
@@ -59,43 +62,6 @@ export declare const THICKNESS: Record<string, number>;
  * thickness is a size, like a text's, and a size is allowed to take room.
  */
 export declare function arrowLength(thickness: number): number;
-/**
- * Line left showing behind the head of an edge with no text, so a gap an arrow
- * crosses is at least this plus its heads. Stacked children sit `CHILD_GAP`
- * apart, which is less than one head, and an arrow between them drew as a head
- * with no line. This is what the tightest named gap already leaves behind a
- * normal head, so any gap an author could have asked for holds it unchanged.
- */
-export declare const BARE_EDGE_RUN: number;
-/**
- * Line left showing between an edge's text and the box at that end of the
- * corridor it crosses.
- *
- * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
- * Those two keep two things from touching, and the least distance that reads as
- * "not touching" is the right one. This one has something to show: a text sits
- * in a knockout that erases the line behind it, so whatever is left either side
- * is the entire evidence that the text belongs to an edge at all. At ten pixels
- * it did not read as a line — the seed diagram in the playground drew as a word
- * with a dash beside it — so it is the length of a run of line, not a margin.
- *
- * Say `gap:` if you want the corridor wider than its contents.
- */
-export declare const TEXT_CLEARANCE = 20;
-/**
- * How much room an edge's text takes along one axis.
- *
- * The knockout rectangle drawn behind a text is the text plus five either side,
- * so that rectangle, not the glyphs, is what must not overlap anything.
- *
- * Shared by the resolver, which widens a corridor to hold a text, and the
- * renderer, which spaces the lanes of a channel by it, so the two cannot
- * disagree about how much room a text needs. The two ask different questions of
- * it and both are right: the resolver measures *along* the run, so an edge
- * traveling horizontally needs the text's width; the renderer measures *across*
- * the channel, so an edge traveling horizontally down one needs its height.
- */
-export declare function textExtent(lines: Line[], textAttrs: Attrs, axis: 'x' | 'y', measurer: Measurer, fontSize: number, line: number): number;
 /**
  * The widest of these lines, which is how wide the block of them is. Shared by
  * the resolver, which sizes a node to hold its text, and the renderer, which
@@ -116,9 +82,9 @@ export declare const ICON_GAP = 10;
 export declare const DEFAULT_FONT_SIZE = 14;
 /**
  * The named text sizes, each a multiple of the document's own size. A plain
- * number of pixels is accepted too, as it is for a gap: nothing else in the
- * diagram moving can make it wrong. The names stay the default because they
- * follow the document's size when that is retuned, and a number does not.
+ * number is a multiple too, and `16px` a size in pixels: nothing else in the
+ * diagram moving can make either wrong. The names stay preferred because they
+ * say why one text is bigger than another.
  *
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25
@@ -169,9 +135,3 @@ export interface TextStyle {
  * cannot disagree about which end the band is at.
  */
 export declare function textStyleFor(attrs: Attrs, line: number, fallbackAlign?: 'start' | 'middle', fallbackAt?: Position): TextStyle;
-/**
- * Where a leaf's text or badge starts vertically, given which end it sits at.
- * Shared, because the resolver works out the text's box and the renderer draws
- * it, and the two must not be able to disagree.
- */
-export declare function leafTop(end: 'top' | 'center' | 'bottom', y: number, height: number, own: number): number;

package/dist/constants.js

@@ -3,29 +3,32 @@ import { SourceError } from './errors.js';
 import { plain } from './text.js';
 /** Inside a box, between its border and its contents. */
 export const PAD = 14;
-/** Between stacked children of one container. */
-export const CHILD_GAP = 10;
+/**
+ * The file's unit, in pixels: about a quarter of an ordinary one-line box, so
+ * the gap words land near whole numbers. Findings measure in it. Provisional
+ * until the gap words are measured against it.
+ */
+export const UNIT = 12;
 /** Between a container's own text and its first child. */
 export const HEADER_GAP = 10;
 /**
- * How far each deck copy is offset behind the front face. It has to clear a
- * whole line of text plus the padding above it, or a copy's text is drawn and
- * then immediately covered by the copy in front of it.
+ * How far each card of a deck sits up and to the left of the one in front. It
+ * has to clear a whole line of text plus the padding above it, or a card's
+ * text is drawn and then immediately covered by the card in front of it.
  */
 export const DECK_STEP = 34;
 /**
- * The named gaps a placement may ask for, each a *minimum* distance rather than a
- * fixed one. Anything the author puts between two things widens the space
- * between them on its own, so no gap here ever has to be chosen large enough
- * to leave room for something else.
+ * The named gaps a placement may ask for, each an exact distance in whole
+ * units. Chosen 2026-10-14 against today's spacing: 2, 4 and 8 units keep the
+ * old look, where 1, 2 and 3 left a line barely longer than its arrowhead.
  */
 export const GAPS = {
     // A zero gap turns an offset into edge-to-edge contact, so "my top edge
     // against Docker's bottom edge" needs no vocabulary of its own.
     none: 0,
-    tight: 24,
-    normal: 56,
-    wide: 110,
+    tight: 2 * UNIT,
+    normal: 4 * UNIT,
+    wide: 8 * UNIT,
 };
 /**
  * How far apart two boxes are pushed when they would otherwise overlap. Small
@@ -71,47 +74,6 @@ export const THICKNESS = {
 export function arrowLength(thickness) {
     return ARROW_MARKER_WIDTH * thickness;
 }
-/**
- * Line left showing behind the head of an edge with no text, so a gap an arrow
- * crosses is at least this plus its heads. Stacked children sit `CHILD_GAP`
- * apart, which is less than one head, and an arrow between them drew as a head
- * with no line. This is what the tightest named gap already leaves behind a
- * normal head, so any gap an author could have asked for holds it unchanged.
- */
-export const BARE_EDGE_RUN = GAPS['tight'] - ARROW_LENGTH;
-/**
- * Line left showing between an edge's text and the box at that end of the
- * corridor it crosses.
- *
- * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
- * Those two keep two things from touching, and the least distance that reads as
- * "not touching" is the right one. This one has something to show: a text sits
- * in a knockout that erases the line behind it, so whatever is left either side
- * is the entire evidence that the text belongs to an edge at all. At ten pixels
- * it did not read as a line — the seed diagram in the playground drew as a word
- * with a dash beside it — so it is the length of a run of line, not a margin.
- *
- * Say `gap:` if you want the corridor wider than its contents.
- */
-export const TEXT_CLEARANCE = 20;
-/**
- * How much room an edge's text takes along one axis.
- *
- * The knockout rectangle drawn behind a text is the text plus five either side,
- * so that rectangle, not the glyphs, is what must not overlap anything.
- *
- * Shared by the resolver, which widens a corridor to hold a text, and the
- * renderer, which spaces the lanes of a channel by it, so the two cannot
- * disagree about how much room a text needs. The two ask different questions of
- * it and both are right: the resolver measures *along* the run, so an edge
- * traveling horizontally needs the text's width; the renderer measures *across*
- * the channel, so an edge traveling horizontally down one needs its height.
- */
-export function textExtent(lines, textAttrs, axis, measurer, fontSize, line) {
-    const size = fontSizeFor('edge', textAttrs, fontSize, line);
-    const width = lines.reduce((widest, drawn) => Math.max(widest, measurer.measure(plain(drawn), size).width), 0);
-    return axis === 'x' ? width + 10 : lines.length * measurer.lineHeight(size);
-}
 /**
  * The widest of these lines, which is how wide the block of them is. Shared by
  * the resolver, which sizes a node to hold its text, and the renderer, which
@@ -134,9 +96,9 @@ export const ICON_GAP = 10;
 export const DEFAULT_FONT_SIZE = 14;
 /**
  * The named text sizes, each a multiple of the document's own size. A plain
- * number of pixels is accepted too, as it is for a gap: nothing else in the
- * diagram moving can make it wrong. The names stay the default because they
- * follow the document's size when that is retuned, and a number does not.
+ * number is a multiple too, and `16px` a size in pixels: nothing else in the
+ * diagram moving can make either wrong. The names stay preferred because they
+ * say why one text is bigger than another.
  *
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25
@@ -168,15 +130,13 @@ export function fontSizeFor(kind, textAttrs, fontSize, line) {
     const scale = TEXT_SIZES[named];
     if (scale !== undefined)
         return Math.round(fontSize * scale);
-    if (/^\d+(\.\d+)?$/.test(named) && Number(named) > 0)
-        return Number(named);
-    const unit = named.match(/^(\d+(?:\.\d+)?)px$/);
-    const hint = unit
-        ? `; write "size: ${unit[1]}", a size's number is already in pixels`
-        : named.startsWith('-') || /^0+(\.0+)?$/.test(named)
-            ? '; a text size has to be more than zero'
-            : '';
-    throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')} or a number of pixels, not "${named}"${hint}`, line);
+    // A bare number is a multiple of normal; `px` fixes it in pixels (design.org 3.8).
+    const number = /^(\d*\.?\d+)(px)?$/.exec(named);
+    if (number && Number(number[1]) > 0) {
+        return number[2] ? Number(number[1]) : Math.round(fontSize * Number(number[1]));
+    }
+    const hint = named.startsWith('-') || /^0*\.?0+(px)?$/.test(named) ? '; a text size has to be more than zero' : '';
+    throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')}, a multiple of normal such as 1.2, or pixels such as 16px, not "${named}"${hint}`, line);
 }
 export const DEFAULT_MARGIN = 40;
 /**
@@ -206,7 +166,11 @@ export function textStyleFor(attrs, line, fallbackAlign = 'start', fallbackAt =
             : `a text's at takes one of ${POSITIONS.join(', ')}, not "${written}"`, line);
     }
     const at = written ?? fallbackAt;
-    const align = attrs['align'];
+    // On a left or right side, align: says where along it (top, center or
+    // bottom), which the resolver has checked; the lines keep their default.
+    const onLeftOrRight = attrs['place']?.endsWith(' left') === true || attrs['place']?.endsWith(' right') === true;
+    const along = onLeftOrRight && (attrs['align'] === 'top' || attrs['align'] === 'bottom');
+    const align = along ? undefined : attrs['align'];
     if (align !== undefined && TEXT_ALIGNMENTS[align] === undefined) {
         throw new SourceError(`a text's align takes left, center or right, not "${align}"`, line);
     }
@@ -218,15 +182,3 @@ export function textStyleFor(attrs, line, fallbackAlign = 'start', fallbackAt =
         align: align === undefined ? fallbackAlign : TEXT_ALIGNMENTS[align],
     };
 }
-/**
- * Where a leaf's text or badge starts vertically, given which end it sits at.
- * Shared, because the resolver works out the text's box and the renderer draws
- * it, and the two must not be able to disagree.
- */
-export function leafTop(end, y, height, own) {
-    if (end === 'top')
-        return y + PAD;
-    if (end === 'bottom')
-        return y + height - PAD - own;
-    return y + (height - own) / 2;
-}

package/dist/grammar.d.ts

@@ -40,7 +40,7 @@ export type TokenKind =
  | 'name'
 /** `->`, `<-`, `<->`, and `--` or `-` for a plain line. */
  | 'arrow'
-/** Placement and edge vocabulary: `right`, `of`, `level`, `with`, `and`, `between`, … */
+/** Placement and line vocabulary: `right`, `of`, `even`, `with`, `and`, `between`, `via`'s stops, … */
  | 'relation'
 /** A `key:` opening an attribute or a bracketed modifier. */
  | 'attribute'
@@ -64,7 +64,7 @@ export interface Span {
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon", "point", "region", "bundle", "guide"];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there

package/dist/grammar.js

@@ -26,16 +26,23 @@
  * editor formats need and the reason a `.reladraw` grammar is small in all of
  * them.
  */
-import { DIRECTIONS, MARKS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
+import { DEFAULT_TARGETS, DIRECTIONS, MARKS, PARTS, POINT_TEXT_SIDES, POSITIONS, SIDES } from './ast.js';
 /**
  * The words a statement may open with. `parseStatement` in `parser.ts` is the
  * authority — its switch is what actually accepts them — and this list mirrors
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon', 'point', 'region', 'bundle', 'guide'];
 /** Statements whose second word declares a name. `diagram` has none. */
-const DECLARES_NAME = ['node', 'style', 'icon'];
+const DECLARES_NAME = ['node', 'style', 'icon', 'point', 'region', 'bundle'];
+/**
+ * Keywords that take another after them: `guide region channel`, `default
+ * leaf`, `default guide edge`. The words that may follow are the kinds a
+ * default is written for, so `leaf` and `container` color as keywords there.
+ */
+const LEADS = ['guide', 'default'];
+const FOLLOWERS = [...new Set(DEFAULT_TARGETS.flatMap((target) => target.split(' ')))];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there
@@ -45,19 +52,45 @@ export const RELATION_WORDS = [
     ...DIRECTIONS,
     ...SIDES,
     ...POSITIONS,
-    ...Object.keys(PASSAGE_AXES),
+    // `tall text`, `server top-left`: the part of a node a placement names.
+    ...PARTS,
+    ...POINT_TEXT_SIDES,
     // The connecting words. `of` is optional after a direction, `and` joins
-    // targets, `between` opens a passage, `level with` is the alignment, and
-    // `on ... at ...` is the overlay. Note `of` and `at` are what tell the two
-    // position vocabularies apart: a direction is always followed by `of`, a
-    // named position always preceded by `at`.
+    // targets, `between` names the point between two things, `even with` is the
+    // alignment, and `on ... at ...` is the overlay. Note `of` and `at` are what
+    // tell the two position vocabularies apart: a direction is always followed
+    // by `of`, a named position always preceded by `at`.
     'of',
     'at',
     'on',
     'and',
-    'level',
+    'even',
     'with',
     'between',
+    // Points (design.org 4): a fraction of the way, a point from two things,
+    // a region's corners.
+    'down',
+    'up',
+    'across',
+    'from',
+    'to',
+    // `(inside top)`, `outside router right`, `via: inside p top`.
+    'inside',
+    'outside',
+    // Lines (design.org 6): `straight down from z3`, `each child of pool`,
+    // `leg climb`, `via: through slot horizontal`.
+    'straight',
+    'each',
+    'child',
+    'leg',
+    'through',
+    'horizontal',
+    'vertical',
+    // A line's text (design.org 7.3): `(left of edge)`, `(on: longest level)`.
+    // `edge` here is the line the text belongs to; at the start of a line it is
+    // still the keyword, since the keyword is matched first.
+    'edge',
+    'level',
 ];
 /** Longest first, so `above-left` is not read as `above` followed by `-left`. */
 function alternation(words) {
@@ -137,6 +170,11 @@ const COMMENT = sticky(PATTERNS.comment);
 const KEYWORD = sticky(PATTERNS.keyword);
 const WORD = sticky(PATTERNS.word);
 const WORD_IN_GROUP = sticky(PATTERNS.wordInGroup);
+const ARROW = new RegExp(`^${PATTERNS.arrow}$`);
+/** Whether a whole word is an arrow, as the parser's `looksLikeArrow` asks. */
+function isArrow(word) {
+    return ARROW.test(word);
+}
 function sticky(source) {
     return new RegExp(source, 'y');
 }
@@ -178,9 +216,21 @@ export function highlightLine(line) {
         }
         if (opening) {
             opening = false;
-            const keyword = match(KEYWORD, line, at);
+            let keyword = match(KEYWORD, line, at);
             if (keyword !== null) {
                 push('keyword', at + keyword.length);
+                // `default guide edge` leads twice, so this loops.
+                while (LEADS.includes(keyword)) {
+                    const space = match(SPACE, line, at);
+                    if (space === null)
+                        break;
+                    const next = match(WORD, line, at + space.length);
+                    if (next === null || !FOLLOWERS.includes(next))
+                        break;
+                    push('plain', at + space.length);
+                    push('keyword', at + next.length);
+                    keyword = next;
+                }
                 if (DECLARES_NAME.includes(keyword)) {
                     const space = match(SPACE, line, at);
                     if (space !== null) {
@@ -193,6 +243,16 @@ export function highlightLine(line) {
                             push('name', at + name.length);
                     }
                 }
+                else if (keyword === 'edge') {
+                    // `edge req client -> api`: a word before the ends names the line,
+                    // told apart by the arrow coming third rather than second, which is
+                    // the parser's own test.
+                    const head = /^([ \t]+)([^\s"]+)[ \t]+([^\s"]+)[ \t]+(\S+)/.exec(line.slice(at));
+                    if (head && !isArrow(head[3]) && isArrow(head[4]) && !RELATION_WORDS.includes(head[2])) {
+                        push('plain', at + head[1].length);
+                        push('name', at + head[2].length);
+                    }
+                }
                 continue;
             }
         }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './ast.js';
+export * from './checks.js';
 export * from './constants.js';
 export * from './errors.js';
 export * from './grammar.js';
@@ -8,6 +9,7 @@ export { parse } from './parser.js';
 export { resolve, type ResolveOptions } from './resolve.js';
 export { render, type RenderOptions } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES, type Theme } from './themes.js';
+import { type Checks, type Finding } from './checks.js';
 import { type RenderOptions } from './render.js';
 import { type ResolveOptions } from './resolve.js';
 /**
@@ -16,3 +18,21 @@ import { type ResolveOptions } from './resolve.js';
  * the statement starts on; see `blame`.
  */
 export declare function compile(source: string, options?: ResolveOptions & RenderOptions): string;
+export interface DrawOptions extends ResolveOptions, RenderOptions {
+    /**
+     * Which kinds of finding to look for. Absent: what the file's
+     * `diagram checks: (…)` says over the defaults. A function: given that, it
+     * returns the checks to run, which is how `--checks` lays itself over the
+     * file. `false`: none, as `--no-checks`.
+     */
+    checks?: false | ((fromFile: Checks) => Checks);
+}
+/**
+ * Source text in; the SVG and the findings about it out. A finding never stops
+ * the drawing: it says where the picture, drawn as written, may not read as
+ * meant.
+ */
+export declare function draw(source: string, options?: DrawOptions): {
+    svg: string;
+    findings: Finding[];
+};

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './ast.js';
+export * from './checks.js';
 export * from './constants.js';
 export * from './errors.js';
 export * from './grammar.js';
@@ -8,6 +9,7 @@ export { parse } from './parser.js';
 export { resolve } from './resolve.js';
 export { render } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES } from './themes.js';
+import { fileChecks, findings } from './checks.js';
 import { SourceError } from './errors.js';
 import { blame, parse } from './parser.js';
 import { render } from './render.js';
@@ -18,7 +20,22 @@ import { resolve } from './resolve.js';
  * the statement starts on; see `blame`.
  */
 export function compile(source, options = {}) {
-    const run = (text) => render(resolve(parse(text), options), options);
+    return draw(source, { ...options, checks: false }).svg;
+}
+/**
+ * Source text in; the SVG and the findings about it out. A finding never stops
+ * the drawing: it says where the picture, drawn as written, may not read as
+ * meant.
+ */
+export function draw(source, options = {}) {
+    const run = (text) => {
+        const layout = resolve(parse(text), options);
+        const svg = render(layout, options);
+        if (options.checks === false)
+            return { svg, findings: [] };
+        const fromFile = fileChecks(layout);
+        return { svg, findings: findings(layout, options.checks ? options.checks(fromFile) : fromFile) };
+    };
     try {
         return run(source);
     }