@refrakt-md/runes 0.40.0 → 0.41.1

package/dist/lib/composition.js

@@ -59,6 +59,7 @@
  */
 import Markdoc from '@markdoc/markdoc';
 import yaml from 'yaml';
+import { CompositionError } from './composition-errors.js';
 import { METABLOCK_ATTR, METABLOCK_OWNER_ATTR } from '@refrakt-md/transform';
 import { createComponentRenderable } from './component.js';
 import { resolveEmitReference, sectionLookup } from './resolver.js';
@@ -79,6 +80,32 @@ export function compositionFor(schema) {
 /** Tags a template may not contain: they resolve at preprocess, a stage a
  *  template comes after (D4). `include` is the route for a repeated block that
  *  needs one. */
+export { CompositionError, COMPOSITION_ERRORS } from './composition-errors.js';
+/**
+ * The 0-based line, within a YAML frontmatter block, of the key at `path` —
+ * each key searched for after the line its parent was found on. A best-effort
+ * locator for error reporting, not a YAML parser: `undefined` when not found.
+ */
+export function frontmatterKeyLine(frontmatter, path) {
+    const lines = frontmatter.split(/\r?\n/);
+    let from = 0;
+    let hit;
+    for (const key of path) {
+        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const re = new RegExp(`^\\s*(?:-\\s+)?["']?${escaped}["']?\\s*:`);
+        hit = undefined;
+        for (let i = from; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+                hit = i;
+                break;
+            }
+        }
+        if (hit === undefined)
+            return undefined;
+        from = hit + 1;
+    }
+    return hit;
+}
 const PREPROCESSOR_TAGS = new Set(['data', 'snippet', 'include']);
 /** Markdoc's own tags, which are template vocabulary rather than placed runes. */
 const MARKDOC_TAGS = new Set(['if', 'else']);
@@ -124,7 +151,7 @@ function slotFields(model, fail) {
     const fields = new Map();
     const m = typeof model === 'function' ? model({}) : model;
     if ('when' in m) {
-        fail('a conditional (`when`) content model is not supported by a composition — the template, not the model, is where an assembly varies.');
+        fail('content-model-type', 'a conditional (`when`) content model is not supported by a composition — the template, not the model, is where an assembly varies.');
     }
     const s = m;
     const addField = (f) => {
@@ -148,7 +175,7 @@ function slotFields(model, fail) {
         });
     }
     else {
-        fail(`a \`${s.type}\` content model is not supported by a composition. Declare a \`sequence\` or \`sections\` model, whose fields are the slots.`);
+        fail('content-model-type', `a \`${s.type}\` content model is not supported by a composition. Declare a \`sequence\` or \`sections\` model, whose fields are the slots.`);
     }
     return fields;
 }
@@ -245,13 +272,19 @@ function soleSlot(n) {
  */
 export function compileComposition(template, options) {
     const { rune, tag, body } = template;
-    const fail = (msg) => {
-        throw new Error(`Rune "${rune}": invalid composition template — ${msg}`);
+    /** The template node being checked, so a failure can say where it is. */
+    let current;
+    const fail = (code, msg) => {
+        const err = new CompositionError(code, `Rune "${rune}": invalid composition template — ${msg}`);
+        const line = current?.lines?.[0];
+        if (typeof line === 'number')
+            err.bodyLine = line;
+        throw err;
     };
     if (typeof body !== 'string')
-        fail('the template body must be a string.');
+        fail('invalid-value', 'the template body must be a string.');
     if (typeof tag !== 'string' || !/^[a-z][a-z0-9]*$/.test(tag)) {
-        fail('`tag` must be an element name.');
+        fail('invalid-value', '`tag` must be an element name.');
     }
     const ast = Markdoc.parse(normaliseEach(body));
     const fields = slotFields(options.contentModel, fail);
@@ -265,20 +298,20 @@ export function compileComposition(template, options) {
             const [root, name] = path;
             if (root === 'attrs') {
                 if (name === undefined)
-                    fail('`$attrs` must name an attribute, as `$attrs.<name>`.');
+                    fail('attrs-undeclared', '`$attrs` must name an attribute, as `$attrs.<name>`.');
                 if (!declared.has(name)) {
-                    fail(`\`$attrs.${name}\` names no declared attribute (declared: ${[...declared].join(', ') || 'none'}).`);
+                    fail('attrs-undeclared', `\`$attrs.${name}\` names no declared attribute (declared: ${[...declared].join(', ') || 'none'}).`);
                 }
             }
             else if (root === 'each') {
                 if (!scope.each) {
-                    fail(`\`$each${name ? `.${name}` : ''}\` is used outside an \`each\` slot; it exists only inside one (D26).`);
+                    fail('each-outside-slot', `\`$each${name ? `.${name}` : ''}\` is used outside an \`each\` slot; it exists only inside one (D26).`);
                 }
                 if (name === undefined)
-                    fail('`$each` must name a field, as `$each.<name>`.');
+                    fail('each-field-not-emitted', '`$each` must name a field, as `$each.<name>`.');
                 if (!scope.each.fields.includes(name)) {
                     const exposed = scope.each.fields;
-                    fail(`\`$each.${name}\` names no field of slot \`${scope.each.slot}\`. \`$each\` exposes exactly the content model's \`emitAttributes\` (${exposed.join(', ') || 'none declared'}) — declare it there (D26).`);
+                    fail('each-field-not-emitted', `\`$each.${name}\` names no field of slot \`${scope.each.slot}\`. \`$each\` exposes exactly the content model's \`emitAttributes\` (${exposed.join(', ') || 'none declared'}) — declare it there (D26).`);
                 }
             }
         }
@@ -294,9 +327,22 @@ export function compileComposition(template, options) {
     };
     /** Check one template node and return its outline entries. */
     const check = (n, scope) => {
-        if (n.type === 'error') {
-            const errors = n.errors ?? [];
-            fail(`Markdoc could not parse it: ${errors.map((e) => e.message).join('; ') || 'syntax error'}.`);
+        const parent = current;
+        current = n.lines?.length ? n : current;
+        try {
+            return checkNode(n, scope);
+        }
+        finally {
+            current = parent;
+        }
+    };
+    const checkNode = (n, scope) => {
+        // A syntax error is an `error` node; an unclosed or unopened tag parses as
+        // a tag carrying a critical error, and would otherwise build silently.
+        const errors = n
+            .errors;
+        if (n.type === 'error' || errors?.some((e) => e.level === 'critical')) {
+            fail('template-parse', `Markdoc could not parse it: ${(errors ?? []).map((e) => e.message).join('; ') || 'syntax error'}.`);
         }
         checkVariables(n, scope);
         if (isSlotTag(n))
@@ -305,14 +351,14 @@ export function compileComposition(template, options) {
             return [checkMetablock(n, scope)];
         if (n.type === 'tag' && n.tag) {
             if (PREPROCESSOR_TAGS.has(n.tag)) {
-                fail(`it contains \`{% ${n.tag} %}\`, which resolves at preprocess, before a template renders (D4). A repeated block that needs \`${n.tag}\` is an \`{% include %}\`, not a composition.`);
+                fail('preprocessor-tag', `it contains \`{% ${n.tag} %}\`, which resolves at preprocess, before a template renders (D4). A repeated block that needs \`${n.tag}\` is an \`{% include %}\`, not a composition.`);
             }
             if (MARKDOC_TAGS.has(n.tag)) {
                 const children = outlineOf(n.children, scope);
                 return n.tag === 'if' ? [{ conditional: true, children }] : children;
             }
             if (selfNames.has(n.tag)) {
-                fail(`it places \`{% ${n.tag} %}\`, which is the rune itself — a composition cycle.`);
+                fail('composition-cycle', `it places \`{% ${n.tag} %}\`, which is the rune itself — a composition cycle.`);
             }
             placements.push({ rune: n.tag, ...(scope.parentRune ? { parent: scope.parentRune } : {}) });
             const children = outlineOf(n.children, { ...scope, parentRune: n.tag });
@@ -329,38 +375,38 @@ export function compileComposition(template, options) {
         const each = n.attributes.each;
         for (const key of Object.keys(n.attributes)) {
             if (key !== 'name' && key !== 'each') {
-                fail(`a \`{% slot %}\` takes \`name\` and \`each\` only, not \`${key}\`.`);
+                fail('slot-invalid', `a \`{% slot %}\` takes \`name\` and \`each\` only, not \`${key}\`.`);
             }
         }
         if (each !== undefined && each !== true)
-            fail('`each` on a slot takes no value.');
+            fail('slot-invalid', '`each` on a slot takes no value.');
         if (name === undefined) {
             if (!scope.each) {
-                fail('a bare `{% slot /%}` means "this item\'s content" and is only valid inside an `each` slot. Name the field it places.');
+                fail('bare-slot-misplaced', 'a bare `{% slot /%}` means "this item\'s content" and is only valid inside an `each` slot. Name the field it places.');
             }
             if (each)
-                fail('a bare `{% slot /%}` cannot itself iterate.');
+                fail('slot-invalid', 'a bare `{% slot /%}` cannot itself iterate.');
             if (n.children.length > 0)
-                fail('a bare `{% slot /%}` takes no fallback content.');
+                fail('slot-invalid', 'a bare `{% slot /%}` takes no fallback content.');
             return { slot: '' };
         }
         if (typeof name !== 'string' || name === '')
-            fail('a slot `name` must be a non-empty string.');
+            fail('slot-invalid', 'a slot `name` must be a non-empty string.');
         if (scope.each) {
-            fail(`slot \`${name}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside.`);
+            fail('slot-inside-each', `slot \`${name}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside.`);
         }
         const field = fields.get(name);
         if (!field) {
-            fail(`slot \`${name}\` names no field of the content model (fields: ${[...fields.keys()].join(', ') || 'none'}) (D26).`);
+            fail('slot-unknown-field', `slot \`${name}\` names no field of the content model (fields: ${[...fields.keys()].join(', ') || 'none'}) (D26).`);
         }
         if (placedSlots.has(name)) {
-            fail(`slot \`${name}\` is placed twice. A slot is placed exactly once; two positions are two declared fields, or a theme's concern (D26).`);
+            fail('slot-placed-twice', `slot \`${name}\` is placed twice. A slot is placed exactly once; two positions are two declared fields, or a theme's concern (D26).`);
         }
         placedSlots.set(name, n);
         slotOrder.push(name);
         if (each) {
             if (!field.list) {
-                fail(`slot \`${name}\` iterates with \`each\`, but field \`${name}\` holds a single value, not a list (D26).`);
+                fail('each-on-single-field', `slot \`${name}\` iterates with \`each\`, but field \`${name}\` holds a single value, not a list (D26).`);
             }
             const children = outlineOf(n.children, {
                 ...scope,
@@ -368,7 +414,7 @@ export function compileComposition(template, options) {
             });
             const sawBare = JSON.stringify(children).includes('"slot":""');
             if (!sawBare) {
-                fail(`the \`each\` slot \`${name}\` never places its item — a bare \`{% slot /%}\` inside it is the item's content, and without one that content is dropped (D11).`);
+                fail('each-item-unplaced', `the \`each\` slot \`${name}\` never places its item — a bare \`{% slot /%}\` inside it is the item's content, and without one that content is dropped (D11).`);
             }
             return { slot: name, each: true, ...(children.length > 0 ? { children } : {}) };
         }
@@ -386,27 +432,27 @@ export function compileComposition(template, options) {
     function checkMetablock(n, scope) {
         for (const key of Object.keys(n.attributes)) {
             if (key !== 'name') {
-                fail(`a \`{% metablock %}\` takes \`name\` only, not \`${key}\`.`);
+                fail('metablock-invalid', `a \`{% metablock %}\` takes \`name\` only, not \`${key}\`.`);
             }
         }
         const name = n.attributes.name;
         if (typeof name !== 'string' || name === '') {
-            fail('a `{% metablock %}` needs a `name`: the declared block it places.');
+            fail('metablock-invalid', 'a `{% metablock %}` needs a `name`: the declared block it places.');
         }
         if (n.children.length > 0) {
-            fail(`\`{% metablock name="${name}" %}\` takes no content; write it self-closing.`);
+            fail('metablock-invalid', `\`{% metablock name="${name}" %}\` takes no content; write it self-closing.`);
         }
         if (n.inline) {
-            fail(`\`{% metablock name="${name}" /%}\` sits inside a line of text. A meta block is a block; place it on its own line.`);
+            fail('metablock-invalid', `\`{% metablock name="${name}" /%}\` sits inside a line of text. A meta block is a block; place it on its own line.`);
         }
         if (scope.each) {
-            fail(`\`{% metablock name="${name}" /%}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside (D7).`);
+            fail('metablock-inside-each', `\`{% metablock name="${name}" /%}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside (D7).`);
         }
         if (!declaredBlocks.has(name)) {
-            fail(`\`{% metablock name="${name}" /%}\` names no declared block (declared: ${[...declaredBlocks].join(', ') || 'none'}). Declare it under \`blocks\` (D7).`);
+            fail('metablock-undeclared', `\`{% metablock name="${name}" /%}\` names no declared block (declared: ${[...declaredBlocks].join(', ') || 'none'}). Declare it under \`blocks\` (D7).`);
         }
         if (placedBlocks.has(name)) {
-            fail(`meta block \`${name}\` is placed twice. A block is placed exactly once: two placements would give two nodes one \`data-name\` (D7).`);
+            fail('metablock-placed-twice', `meta block \`${name}\` is placed twice. A block is placed exactly once: two placements would give two nodes one \`data-name\` (D7).`);
         }
         placedBlocks.add(name);
         return { metablock: name };
@@ -415,7 +461,7 @@ export function compileComposition(template, options) {
     // D11 — a field no slot places parses and then silently does not render.
     const unplaced = [...fields.keys()].filter((f) => !placedSlots.has(f));
     if (unplaced.length > 0) {
-        fail(`content-model field${unplaced.length > 1 ? 's' : ''} ${unplaced.map((f) => `\`${f}\``).join(', ')} ${unplaced.length > 1 ? 'are' : 'is'} placed by no slot, so authored content would be dropped. Place ${unplaced.length > 1 ? 'each' : 'it'} with \`{% slot name="…" /%}\` (D11).`);
+        fail('field-unplaced', `content-model field${unplaced.length > 1 ? 's' : ''} ${unplaced.map((f) => `\`${f}\``).join(', ')} ${unplaced.length > 1 ? 'are' : 'is'} placed by no slot, so authored content would be dropped. Place ${unplaced.length > 1 ? 'each' : 'it'} with \`{% slot name="…" /%}\` (D11).`);
     }
     // The type the rune claims — on the table, its fallback, or any of its rows.
     const schemaType = options.schema?.type ??
@@ -752,69 +798,77 @@ const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
  * silently preferred.
  */
 export function parseCompositionDefinition(rune, source) {
-    const fail = (msg) => {
-        throw new Error(`Rune "${rune}": invalid composition definition — ${msg}`);
+    let frontmatter = '';
+    /** Throw, located at the frontmatter key `at` names when it is given. */
+    const fail = (code, msg, at) => {
+        const err = new CompositionError(code, `Rune "${rune}": invalid composition definition — ${msg}`);
+        const index = typeof at === 'number' ? at : at ? frontmatterKeyLine(frontmatter, at) : undefined;
+        // The frontmatter's first line is the source's second, after `---`.
+        err.line = index === undefined ? 1 : index + 2;
+        throw err;
     };
     if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(rune)) {
-        fail('the rune name must be kebab-case.');
+        fail('name-not-kebab', 'the rune name must be kebab-case.');
     }
     if (typeof source !== 'string')
-        fail('the definition must be a string.');
+        fail('invalid-value', 'the definition must be a string.');
     const match = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/.exec(source);
     if (!match)
-        fail('it has no frontmatter block (`---` … `---`) declaring its input.');
+        fail('no-frontmatter', 'it has no frontmatter block (`---` … `---`) declaring its input.');
+    frontmatter = match[1];
     let front;
     try {
-        front = yaml.parse(match[1]) ?? {};
+        front = yaml.parse(frontmatter) ?? {};
     }
     catch (e) {
-        fail(`its frontmatter is not valid YAML: ${e.message}`);
+        const pos = e.linePos?.[0]?.line;
+        fail('frontmatter-yaml', `its frontmatter is not valid YAML: ${e.message}`, typeof pos === 'number' ? pos - 1 : undefined);
     }
     if (!front || typeof front !== 'object' || Array.isArray(front)) {
-        fail('its frontmatter must be a mapping.');
+        fail('frontmatter-yaml', 'its frontmatter must be a mapping.');
     }
     const fm = front;
     for (const key of Object.keys(fm)) {
         if (DEFINITION_KEYS.has(key))
             continue;
         if (key === 'rune' || key === 'name') {
-            fail(`frontmatter key \`${key}\` restates the rune's name, which is the file's name. Remove it (SPEC-153 D9).`);
+            fail('name-restated', `frontmatter key \`${key}\` restates the rune's name, which is the file's name. Remove it (SPEC-153 D9).`, [key]);
         }
         if (STYLE_KEYS.has(key)) {
-            fail(`frontmatter key \`${key}\` would ship styles. A composed rune has no block and ships no CSS: its appearance is the primitives' (D2). A rune that needs its own styling is a declared rune in a plugin.`);
+            fail('style-key', `frontmatter key \`${key}\` would ship styles. A composed rune has no block and ships no CSS: its appearance is the primitives' (D2). A rune that needs its own styling is a declared rune in a plugin.`, [key]);
         }
         if (EMIT_KEYS.has(key)) {
-            fail(`frontmatter key \`${key}\` declares a second emit path. A definition's template is its emit path; exactly one of a slot declaration, a template or a \`transform\` (D5).`);
+            fail('second-emit-path', `frontmatter key \`${key}\` declares a second emit path. A definition's template is its emit path; exactly one of a slot declaration, a template or a \`transform\` (D5).`, [key]);
         }
         if (key === 'layout') {
-            fail("frontmatter key `layout` cannot apply: `layout` places a rune's own containers, and a composed rune's containers belong to the primitives it places (D7). Arrange them in the template.");
+            fail('layout-key', "frontmatter key `layout` cannot apply: `layout` places a rune's own containers, and a composed rune's containers belong to the primitives it places (D7). Arrange them in the template.", [key]);
         }
-        fail(`unknown frontmatter key \`${key}\` (expected ${[...DEFINITION_KEYS].join(', ')}).`);
+        fail('unknown-key', `unknown frontmatter key \`${key}\` (expected ${[...DEFINITION_KEYS].join(', ')}).`, [key]);
     }
     const tag = (fm.tag ?? 'div');
     if (typeof tag !== 'string' || !/^[a-z][a-z0-9]*$/.test(tag))
-        fail('`tag` must be an element name.');
+        fail('invalid-value', '`tag` must be an element name.', ['tag']);
     let aliases;
     if (fm.aliases !== undefined) {
         if (!Array.isArray(fm.aliases) || !fm.aliases.every((a) => typeof a === 'string')) {
-            fail('`aliases` must be a list of names.');
+            fail('invalid-value', '`aliases` must be a list of names.', ['aliases']);
         }
         aliases = fm.aliases;
     }
     if (fm.description !== undefined && typeof fm.description !== 'string') {
-        fail('`description` must be a string.');
+        fail('invalid-value', '`description` must be a string.', ['description']);
     }
-    const attributes = parseAttributes(fm.attributes, fail);
-    const contentModel = parseContentModel(fm.content, fail);
+    const attributes = parseAttributes(fm.attributes, (code, msg, at) => fail(code, msg, ['attributes', ...(at ?? [])]));
+    const contentModel = parseContentModel(fm.content, (code, msg, at) => fail(code, msg, ['content', ...(at ?? [])]));
     for (const key of ['schema', 'registers', 'metaFields', 'blocks']) {
         const v = fm[key];
         if (v !== undefined && (!v || typeof v !== 'object' || Array.isArray(v))) {
-            fail(`\`${key}\` must be a mapping.`);
+            fail('invalid-value', `\`${key}\` must be a mapping.`, [key]);
         }
     }
     if (fm.provides !== undefined &&
         (!Array.isArray(fm.provides) || !fm.provides.every((p) => typeof p === 'string'))) {
-        fail('`provides` must be a list of names.');
+        fail('invalid-value', '`provides` must be a list of names.', ['provides']);
     }
     return {
         rune,
@@ -829,36 +883,41 @@ export function parseCompositionDefinition(rune, source) {
         ...(fm.blocks ? { blocks: fm.blocks } : {}),
         ...(fm.provides ? { provides: fm.provides } : {}),
         template: match[2],
+        // `---`, the frontmatter's lines, `---`: the body starts on the next.
+        templateLine: frontmatter.split(/\r?\n/).length + 3,
+        frontmatter,
     };
 }
-function parseAttributes(raw, fail) {
+function parseAttributes(raw, sectionFail) {
+    const fail = (code, msg) => sectionFail(code, msg);
     if (raw === undefined)
         return {};
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        fail('`attributes` must be a mapping.');
+        fail('attribute-invalid', '`attributes` must be a mapping.');
     const out = {};
     for (const [name, decl] of Object.entries(raw)) {
         const where = `attribute \`${name}\``;
+        const at = (code, msg) => sectionFail(code, msg, [name]);
         if (!/^[a-z][a-zA-Z0-9]*(-[a-z0-9]+)*$/.test(name))
-            fail(`${where}: not a valid attribute name.`);
+            at('attribute-invalid', `${where}: not a valid attribute name.`);
         if (!decl || typeof decl !== 'object' || Array.isArray(decl)) {
-            fail(`${where} must be a mapping such as \`{ type: string }\`.`);
+            at('attribute-invalid', `${where} must be a mapping such as \`{ type: string }\`.`);
         }
         const d = decl;
         for (const key of Object.keys(d)) {
             if (!ATTRIBUTE_KEYS.has(key)) {
-                fail(`${where}: unknown key \`${key}\` (expected ${[...ATTRIBUTE_KEYS].join(', ')}).`);
+                at('attribute-invalid', `${where}: unknown key \`${key}\` (expected ${[...ATTRIBUTE_KEYS].join(', ')}).`);
             }
         }
         const type = ATTRIBUTE_TYPES[String(d.type ?? 'string')];
         if (!type)
-            fail(`${where}: \`type\` must be string, number or boolean.`);
+            at('attribute-invalid', `${where}: \`type\` must be string, number or boolean.`);
         if (d.matches !== undefined) {
             if (!Array.isArray(d.matches) || d.matches.length === 0) {
-                fail(`${where}: \`matches\` must be a non-empty list.`);
+                at('attribute-invalid', `${where}: \`matches\` must be a non-empty list.`);
             }
             if (RESERVED_MODIFIERS.has(kebab(name))) {
-                fail(`${where} declares \`matches\`, so it would render as \`data-${kebab(name)}\` — an attribute the engine writes itself. Rename it (D2a).`);
+                at('attribute-reserved', `${where} declares \`matches\`, so it would render as \`data-${kebab(name)}\` — an attribute the engine writes itself. Rename it (D2a).`);
             }
         }
         out[name] = {
@@ -882,39 +941,42 @@ const FIELD_KEYS = new Set([
 ]);
 /** A field list as YAML writes it: a mapping keyed by name, or a list with `name`. */
 function parseFields(raw, where, fail) {
+    const section = where.split('.').pop();
     if (raw === undefined)
         return [];
     const entries = Array.isArray(raw)
         ? raw.map((f) => [String(f?.name ?? ''), f])
         : raw && typeof raw === 'object'
             ? Object.entries(raw)
-            : fail(`\`${where}\` must be a mapping of fields.`);
+            : fail('content-model-invalid', `\`${where}\` must be a mapping of fields.`);
     return entries.map(([name, f]) => {
+        const at = (code, msg) => fail(code, msg, [section, name]);
         if (!/^[a-z][a-zA-Z0-9]*(-[a-zA-Z0-9]+)*$/.test(name)) {
-            fail(`\`${where}\`: \`${name}\` is not a valid field name.`);
+            at('content-model-invalid', `\`${where}\`: \`${name}\` is not a valid field name.`);
         }
         if (!f || typeof f !== 'object')
-            fail(`\`${where}.${name}\` must be a mapping.`);
+            at('content-model-invalid', `\`${where}.${name}\` must be a mapping.`);
         const def = { ...f };
         delete def.name;
         for (const key of Object.keys(def)) {
             if (!FIELD_KEYS.has(key)) {
-                fail(`\`${where}.${name}\`: unknown key \`${key}\` (expected ${[...FIELD_KEYS].join(', ')}).`);
+                at('content-model-invalid', `\`${where}.${name}\`: unknown key \`${key}\` (expected ${[...FIELD_KEYS].join(', ')}).`);
             }
         }
         if (typeof def.match !== 'string')
-            fail(`\`${where}.${name}\` needs a \`match\`.`);
+            at('content-model-invalid', `\`${where}.${name}\` needs a \`match\`.`);
         return { name, ...def };
     });
 }
-function parseHeadingExtract(raw, fail) {
+function parseHeadingExtract(raw, sectionFail) {
+    const fail = (code, msg) => sectionFail(code, msg, ['headingExtract']);
     const fields = raw?.fields;
     if (!Array.isArray(fields))
-        fail('`content.headingExtract.fields` must be a list.');
+        fail('content-model-invalid', '`content.headingExtract.fields` must be a list.');
     return {
         fields: fields.map((f) => {
             if (typeof f?.name !== 'string' || typeof f.pattern !== 'string') {
-                fail('a `headingExtract` field needs a `name` and a `pattern`.');
+                fail('content-model-invalid', 'a `headingExtract` field needs a `name` and a `pattern`.');
             }
             let pattern = 'remainder';
             if (f.pattern !== 'remainder') {
@@ -922,7 +984,7 @@ function parseHeadingExtract(raw, fail) {
                     pattern = new RegExp(f.pattern);
                 }
                 catch (e) {
-                    fail(`headingExtract \`${f.name}\`: \`pattern\` is not a regular expression: ${e.message}`);
+                    fail('content-model-invalid', `headingExtract \`${f.name}\`: \`pattern\` is not a regular expression: ${e.message}`);
                 }
             }
             return {
@@ -950,15 +1012,15 @@ function parseContentModel(raw, fail) {
     if (raw === undefined)
         return { type: 'sequence', fields: [] };
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        fail('`content` must be a mapping.');
+        fail('content-model-invalid', '`content` must be a mapping.');
     const c = raw;
     const allowed = c.type === 'sequence' ? SEQUENCE_KEYS : c.type === 'sections' ? SECTIONS_KEYS : null;
     if (!allowed) {
-        fail(`\`content.type\` must be \`sequence\` or \`sections\`${c.type ? `, not \`${String(c.type)}\`` : ''}: a composition's slots are the model's fields.`);
+        fail('content-model-type', `\`content.type\` must be \`sequence\` or \`sections\`${c.type ? `, not \`${String(c.type)}\`` : ''}: a composition's slots are the model's fields.`);
     }
     for (const key of Object.keys(c)) {
         if (!allowed.has(key)) {
-            fail(`\`content\`: unknown key \`${key}\` for a ${String(c.type)} model.`);
+            fail('content-model-invalid', `\`content\`: unknown key \`${key}\` for a ${String(c.type)} model.`, [key]);
         }
     }
     if (c.type === 'sequence') {
@@ -968,21 +1030,21 @@ function parseContentModel(raw, fail) {
         };
     }
     if (c.fields !== undefined && c.preamble !== undefined) {
-        fail('`content` declares both `fields` and `preamble`; they are one thing — use `preamble`.');
+        fail('content-model-invalid', '`content` declares both `fields` and `preamble`; they are one thing — use `preamble`.');
     }
     const sectionModel = c.sectionModel === undefined
         ? {
             type: 'sequence',
             fields: [{ name: 'body', match: 'any', optional: true, greedy: true }],
         }
-        : parseContentModel(c.sectionModel, fail);
+        : parseContentModel(c.sectionModel, (code, msg, at) => fail(code, msg, ['sectionModel', ...(at ?? [])]));
     if (c.emitAttributes !== undefined) {
         const ea = c.emitAttributes;
         if (!ea ||
             typeof ea !== 'object' ||
             Array.isArray(ea) ||
             !Object.values(ea).every((v) => typeof v === 'string')) {
-            fail('`content.emitAttributes` must map names to `$heading`, `$<field>` or a literal.');
+            fail('content-model-invalid', '`content.emitAttributes` must map names to `$heading`, `$<field>` or a literal.', ['emitAttributes']);
         }
     }
     return {
@@ -1081,13 +1143,13 @@ export function checkCompositions(catalog, tableOf) {
                     ? (parentEntry?.entry.dataRune ?? parentEntry?.name ?? parent)
                     : undefined;
                 if (parentRune !== requiredRune) {
-                    throw new Error(`Rune "${name}": its template places \`{% ${placedName} %}\`, which requires \`{% ${requiredRune} %}\` as its parent, ${parent ? `but sits inside \`{% ${parent} %}\`` : `but the template's nearest rune around it is "${name}" itself`}. Place \`{% ${requiredRune} %}\` and let its content model produce the \`${placed.name}\` children (D12).`);
+                    throw new CompositionError('parent-required', `Rune "${name}": its template places \`{% ${placedName} %}\`, which requires \`{% ${requiredRune} %}\` as its parent, ${parent ? `but sits inside \`{% ${parent} %}\`` : `but the template's nearest rune around it is "${name}" itself`}. Place \`{% ${requiredRune} %}\` and let its content model produce the \`${placed.name}\` children (D12).`);
                 }
             }
             if (info.schemaType && placed.entry.schema) {
                 const peer = emittedTypes(placed.entry, tableOf(placed.entry.schema)).find((t) => !SUBORDINATE_SCHEMA_TYPES.has(t));
                 if (peer) {
-                    throw new Error(`Rune "${name}": it declares schema type \`${info.schemaType}\` and its template places \`{% ${placedName} %}\`, which declares the peer type \`${peer}\`. Two top-level entities in one subtree — compose into a type, never from one: place primitives that emit no type, or a subordinate one such as \`figure\` (D9).`);
+                    throw new CompositionError('peer-schema-type', `Rune "${name}": it declares schema type \`${info.schemaType}\` and its template places \`{% ${placedName} %}\`, which declares the peer type \`${peer}\`. Two top-level entities in one subtree — compose into a type, never from one: place primitives that emit no type, or a subordinate one such as \`figure\` (D9).`);
                 }
             }
         }
@@ -1104,7 +1166,7 @@ export function checkCompositions(catalog, tableOf) {
             return;
         if (state.get(name) === 'visiting') {
             const cycle = [...stack.slice(stack.indexOf(name)), name];
-            throw new Error(`Composition cycle: ${cycle.map((n) => `"${n}"`).join(' places ')}. A composed rune cannot place itself, directly or through another.`);
+            throw new CompositionError('composition-cycle', `Composition cycle: ${cycle.map((n) => `"${n}"`).join(' places ')}. A composed rune cannot place itself, directly or through another.`);
         }
         state.set(name, 'visiting');
         stack.push(name);