reladraw 0.1.0 → 0.2.0

package/dist/resolve.js

@@ -1,4 +1,4 @@
-import { describePlacement } from './ast.js';
+import { ALL_ATTR_KEYS, ATTR_KEYS, COLOR_KEYS, COLOR_PARTS, describePlacement, } from './ast.js';
 import { ARROW_LENGTH, CHILD_GAP, DECK_STEP, DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, HEADER_GAP, ICON_GAP, ICON_LINES, LABEL_CLEARANCE, PAD, SEPARATION_GAP, fontSizeFor, labelExtent, labelStyleFor, } from './constants.js';
 import { fix, reachability, tightest } from './constrain.js';
 import { SourceError } from './errors.js';
@@ -21,9 +21,10 @@ export function resolve(doc, options = {}) {
     const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
     const margin = options.margin ?? DEFAULT_MARGIN;
     const styles = collectStyles(doc.statements);
+    checkStyleKeys(doc.statements);
     const { nodes, byName, roots } = buildTree(doc.statements, styles);
     applyDecks(doc.statements, byName);
-    // Links are resolved to nodes before anything is sized, because a labelled
+    // Links are resolved to nodes before anything is sized, because a labeled
     // link claims room in the gap it crosses and so has to be in hand while the
     // gaps are being worked out. Nothing here reads geometry.
     const links = buildLinks(doc.statements, byName, styles);
@@ -97,6 +98,9 @@ function buildTree(statements, styles) {
             placements: stmt.placements,
             line: stmt.line,
         };
+        const kind = kindOf(node);
+        checkAttrs(kind, node.name, stmt.attrs, stmt.line);
+        checkStyleUse(kind, node.name, stmt.attrs, styles, stmt.line);
         const cut = stmt.name.lastIndexOf('.');
         if (cut === -1) {
             roots.push(node);
@@ -115,6 +119,122 @@ function buildTree(statements, styles) {
     }
     return { nodes, byName, roots };
 }
+/** How each kind reads in an error, and what it is actually made of. */
+const KIND_WORD = { box: 'box', note: 'note', glyph: 'glyph body', link: 'link' };
+const KIND_PARTS = {
+    box: 'a fill, a border and text',
+    note: 'bare text and nothing else',
+    glyph: 'a picture and the text under it',
+    link: 'a line and its label',
+};
+/**
+ * An attribute is refused on a kind that has no use for it — the same rule as
+ * an unknown `diagram` key, and for the same reason: a key that silently does
+ * nothing looks like the tool being broken. A color names a part and so is a
+ * special case of this, which is why the two checks are one.
+ *
+ * What is checked is what the author wrote *on this statement*, not what a
+ * style contributed. A style is a bundle meant to be shared across kinds — the
+ * benchmark's `synced` carries a fill and a border for the green boxes and a
+ * line for the four links joining them — so a key it carries that this kind has
+ * no part for is simply unused, and is not a mistake anybody made here. That is
+ * forced rather than chosen: checking the merged appearance would refuse the
+ * benchmark's own central idiom four times over. `checkStyleUse` is what keeps
+ * the permissiveness honest.
+ */
+function checkAttrs(kind, name, attrs, line) {
+    const allowed = ATTR_KEYS[kind];
+    // In the author's own order, so the error names the first offending word as
+    // it is read rather than the first in some list of ours.
+    for (const [key, value] of Object.entries(attrs)) {
+        if (allowed.includes(key))
+            continue;
+        if (!ALL_ATTR_KEYS.includes(key)) {
+            // Nothing anywhere in the language answers to this word, so the only
+            // remedy is the vocabulary itself.
+            throw new SourceError(`"${name}" has ${key}: ${value}, which is not an attribute. A ${KIND_WORD[kind]} takes ${allowed.join(', ')}`, line);
+        }
+        // A real word in the wrong place, and the two sorts of word want different
+        // explanations. A color names a *part*, so saying what the kind is made of
+        // is the whole reason it has no such color, and the remedy is the narrower
+        // list of parts it does have: `line:` on a box is a different mistake from
+        // `border:` on a note, and one hint cannot serve both.
+        if (COLOR_KEYS.includes(key)) {
+            const parts = COLOR_PARTS[kind].map((part) => `\`${part}:\``).join(', ');
+            throw new SourceError(`"${name}" is a ${KIND_WORD[kind]} and has ${key}: ${value}. A ${KIND_WORD[kind]} is ${KIND_PARTS[kind]}, so it has no ${key} — it takes ${parts}`, line);
+        }
+        // Anything else names no part, so what the kind is made of explains
+        // nothing. What does explain it is where the word *does* belong, which is
+        // also the more useful thing to be told: the author has usually written a
+        // real statement about the wrong half of the diagram.
+        throw new SourceError(`"${name}" is a ${KIND_WORD[kind]} and has ${key}: ${value}. \`${key}:\` belongs to ` +
+            `${listKinds(belongTo(key))} — a ${KIND_WORD[kind]} takes ${allowed.join(', ')}`, line);
+    }
+}
+/**
+ * A style may carry keys this kind has no use for, but it may not carry *only*
+ * those. Partial overlap is the normal case and the reason styles exist; zero
+ * overlap is a style name written on the wrong sort of thing, and nothing else.
+ *
+ * This is the check that lets `checkAttrs` ignore style-contributed keys
+ * without the silence coming back. It cannot catch a style that names every key
+ * in the language, since such a style contributes to everything by
+ * construction — that hole is left open, because nobody writes one by accident.
+ */
+function checkStyleUse(kind, name, attrs, styles, line) {
+    const named = attrs['style'];
+    if (named === undefined)
+        return;
+    const base = styles.get(named);
+    if (base === undefined)
+        return; // `appearanceOf` reports the missing style.
+    // A style naming another style is the one way to carry nothing at all: the
+    // parser already refuses one with no attributes, and `appearanceOf` does not
+    // recurse, so the name would sit there doing nothing.
+    const carried = Object.keys(base).filter((key) => key !== 'style');
+    if (carried.length === 0) {
+        throw new SourceError(`style "${named}" carries nothing but a style name`, line);
+    }
+    if (carried.some((key) => ATTR_KEYS[kind].includes(key)))
+        return;
+    throw new SourceError(`style "${named}" gives "${name}" nothing. It carries ${carried.join(' and ')}; ` +
+        `a ${KIND_WORD[kind]} is ${KIND_PARTS[kind]}`, line);
+}
+/**
+ * A style is a bundle spanning kinds, so its keys cannot be checked against any
+ * one of them — but a word that is an attribute of *nothing* is a misspelling
+ * wherever it sits, and a style was the last place in the language where one
+ * could hide.
+ */
+function checkStyleKeys(statements) {
+    for (const stmt of statements) {
+        if (stmt.kind !== 'style')
+            continue;
+        for (const [key, value] of Object.entries(stmt.attrs)) {
+            if (ALL_ATTR_KEYS.includes(key))
+                continue;
+            throw new SourceError(`style "${stmt.name}" has ${key}: ${value}, which is not an attribute. ` +
+                `The attributes are ${ALL_ATTR_KEYS.join(', ')}`, stmt.line);
+        }
+    }
+}
+/** Which kinds understand an attribute, in the order the table declares them. */
+function belongTo(key) {
+    return Object.keys(ATTR_KEYS).filter((kind) => ATTR_KEYS[kind].includes(key));
+}
+/** "a link", "a box or a glyph body", "a box, a note or a glyph body". */
+function listKinds(kinds) {
+    const words = kinds.map((kind) => `a ${KIND_WORD[kind]}`);
+    if (words.length <= 1)
+        return words[0] ?? 'nothing';
+    return `${words.slice(0, -1).join(', ')} or ${words[words.length - 1]}`;
+}
+/** Which of the four kinds a node is, which its `shape:` may decide. */
+function kindOf(node) {
+    if (node.kind === 'note')
+        return 'note';
+    return shapeFor(node.appearance, node.line).body !== undefined ? 'glyph' : 'box';
+}
 function appearanceOf(attrs, styles, line) {
     const named = attrs['style'];
     if (named === undefined)
@@ -155,6 +275,10 @@ function buildLinks(statements, byName, styles) {
             }),
             ...(stmt.between.axis !== undefined ? { axis: stmt.between.axis } : {}),
         };
+        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        const what = `${stmt.from} -> ${stmt.to}`;
+        checkAttrs('link', what, stmt.attrs, stmt.line);
+        checkStyleUse('link', what, stmt.attrs, styles, stmt.line);
         links.push({
             from,
             to,
@@ -162,7 +286,7 @@ function buildLinks(statements, byName, styles) {
             ...(stmt.label !== undefined ? { label: stmt.label } : {}),
             ...(between ? { between } : {}),
             attrs: stmt.attrs,
-            appearance: appearanceOf(stmt.attrs, styles, stmt.line),
+            appearance,
             line: stmt.line,
         });
     }
@@ -188,14 +312,6 @@ function sizeNode(node, links, measurer, fontSize, local) {
     const labelHeight = hasLabel ? node.lines.length * lineHeight : 0;
     if (node.kind === 'note') {
         // A note is bare text, so it gets no padding and takes no children.
-        // Both are refused rather than ignored, for the reason an unknown diagram
-        // key is: a note is bare text with no box to decorate or replace, so either
-        // word would silently do nothing and look like the tool being broken.
-        for (const key of ['icon', 'shape']) {
-            if (node.appearance[key] !== undefined) {
-                throw new SourceError(`"${node.name}" is a note and has ${key}: ${node.appearance[key]}. A note is bare text, with no box to ${key === 'icon' ? 'decorate' : 'replace'}`, node.line);
-            }
-        }
         node.width = labelWidth;
         node.height = labelHeight;
         return;
@@ -221,13 +337,15 @@ function sizeNode(node, links, measurer, fontSize, local) {
     const iconSide = icon === undefined ? 0 : glyphSide;
     const iconRoom = icon === undefined ? 0 : iconSide + (hasLabel ? ICON_GAP : 0);
     if (node.children.length === 0) {
-        // A band only exists because contents have to sit clear of it. A leaf has
-        // none, so its label is centred in the box and there is nothing for `at` or
-        // `align` to move it relative to. Refused rather than silently dropped.
-        const stated = Object.keys(node.label);
-        if (stated.length > 0) {
-            throw new SourceError(`"${node.name}" holds nothing and its label carries ${stated.join(' and ')}. ` +
-                `A label sits at one end of a box so its contents can have the other; with no contents it is centred, and there is nothing to say`, node.line);
+        // A band only exists because contents have to sit clear of it, and a leaf
+        // has none, so `at` has no end to name. `align` is a different question and
+        // is allowed: a label of several lines has lines of unequal length in any
+        // box, and ranging them left rather than centering them is a real thing to
+        // want. It was refused here too until 2026-09-09, purely because the two
+        // words arrive in the same brackets.
+        if (node.label['at'] !== undefined) {
+            throw new SourceError(`"${node.name}" holds nothing and its label carries at: ${node.label['at']}. ` +
+                `A label sits at one end of a box so its contents can have the other; with no contents there is no band for it to sit at either end of`, node.line);
         }
         node.width = labelWidth + iconRoom + PAD * 2;
         node.height = Math.max(labelHeight, iconSide) + PAD * 2;
@@ -419,11 +537,11 @@ function liftTo(node, indexOf, local) {
         height: node.height,
     };
 }
-/** The labelled links whose two ends are different members of this group. */
+/** The labeled links whose two ends are different members of this group. */
 function corridorsIn(links, locate, measurer, fontSize) {
     const corridors = [];
     for (const link of links) {
-        // An unlabelled link asks for nothing: every gap holds an arrowhead. And a
+        // An unlabeled link asks for nothing: every gap holds an arrowhead. And a
         // link told to pass between two named things carries its label in *that*
         // corridor rather than in the gap between its own ends, so widening this one
         // would make room where the label never goes.
@@ -543,11 +661,11 @@ function positionGroup(members, locate, extra, corridors = []) {
                 }
             }
         }
-        // An axis nobody spoke to falls back to the centre line of whatever the
+        // An axis nobody spoke to falls back to the center line of whatever the
         // node was placed against, which is why "right of docker" alone is a whole
         // position. Two different targets would decide which row the node shares,
         // so that is refused rather than guessed — but two targets named by one
-        // placement are a single region, and centring on it is unambiguous.
+        // placement are a single region, and centering on it is unambiguous.
         for (const axis of AXES) {
             if (spokenFor[axis])
                 continue;
@@ -563,7 +681,7 @@ function positionGroup(members, locate, extra, corridors = []) {
                     `"${describePlacement(first.placement)}" and "${describePlacement(other.placement)}" ` +
                     `would put it in different places`, other.placement.line);
             }
-            alignOn(axis, 'centre', first.targets, first.placement);
+            alignOn(axis, 'center', first.targets, first.placement);
         }
     }
     const solved = { x: [], y: [] };
@@ -604,7 +722,7 @@ function spanOf(targets, axis, base) {
 }
 /** Where a node of this size sits so that the named edge of it meets the span's. */
 function alignedAt(edge, span, own) {
-    if (edge === 'centre')
+    if (edge === 'center')
         return span.start + (span.size - own) / 2;
     if (edge === 'top' || edge === 'left')
         return span.start;
@@ -958,12 +1076,12 @@ function widestLine(lines, measurer, fontSize) {
  * and never becomes a coordinate in disguise.
  */
 function linesFor(text, attrs, line) {
-    const stated = attrs['width'];
+    const stated = attrs['wrap'];
     if (stated === undefined)
         return splitLines(text);
     const columns = Number(stated);
     if (!Number.isInteger(columns) || columns < 1) {
-        throw new SourceError(`width must be a whole number of characters, not "${stated}"`, line);
+        throw new SourceError(`wrap must be a whole number of characters, not "${stated}"`, line);
     }
     return splitLines(text).flatMap((part) => wrap(part, columns));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A diagram language where placement is stated, not computed.",
   "type": "module",
   "bin": {