@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-diagram.js

@@ -4,8 +4,10 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { Gradia } from "@rse/gradia";
-import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths, expandReferences, plainText } from "./specbook-link.js";
+import { diagramsOf } from "./specbook-format-schema.js";
+import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths, chainOf, expandReferences, plainText, referenceText } from "./specbook-link.js";
 import { collectSchemas, collectParenProps } from "./specbook-parse-semantic.js";
+import { referencedCoverage, specCoverage } from "./specbook-coverage.js";
 import { literal } from "./specbook-verbose.js";
 /*  the single Wiki-style reference match (the non-global sibling of
     the imported, global "referenceRegex")  */
@@ -49,7 +51,7 @@ const quoted = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"
     string otherwise  */
 const atom = (text) => {
     const plain = text.replace(/\s+/g, " ").trim();
-    return /^[^\s[\]():,">#]+$/.test(plain) && !plain.includes("--") ? plain : quoted(plain);
+    return /^[^\s[\]{}():,">#]+$/.test(plain) && !plain.includes("--") ? plain : quoted(plain);
 };
 /*  render a text as a Gradia edge name or edge arity token
     (each with its own, more lenient character set)  */
@@ -62,6 +64,12 @@ const configValue = (value) => {
     const text = String(value).replace(/\s+/g, " ").trim();
     return /^[^\s"]+$/.test(text) ? text : quoted(text);
 };
+const messageKinds = {
+    call: "sync", sync: "sync",
+    signal: "async", async: "async",
+    return: "return", create: "create",
+    destroy: "destroy"
+};
 /*  the properties of an object, the synthetic one included  */
 const propsOf = (parenProps, object) => {
     const synthetic = parenProps.get(object);
@@ -69,13 +77,43 @@ const propsOf = (parenProps, object) => {
 };
 /*  the value of a single property of an object, by its key  */
 const propValue = (parenProps, object, key) => propsOf(parenProps, object).find((property) => property.key === key)?.value;
+/*  the badge icon of an object: the fixed one of its object kind, or the
+    one the value of the configured property maps onto, else the default  */
+const badgeOf = (ctx, object) => {
+    const badge = ctx.schemas.get(object)?.badge;
+    if (badge === undefined || typeof badge === "string")
+        return badge;
+    const value = plainText(propValue(ctx.parenProps, object, badge.property) ?? "").trim();
+    return Object.hasOwn(badge.map, value) ? badge.map[value] : badge.default;
+};
+/*  whether an object stands for several instances: the value of the
+    configured property of its object kind matches the configured pattern  */
+const isMultiple = (ctx, object) => {
+    const multiple = ctx.schemas.get(object)?.multiple;
+    if (multiple === undefined)
+        return false;
+    const value = propValue(ctx.parenProps, object, multiple.property);
+    return value !== undefined && new RegExp(multiple.pattern).test(plainText(value));
+};
+/*  the initial tokens or the capacity of a place of a "petri" diagram,
+    or the duration or earliest start of a task of a "gantt" diagram:
+    the trimmed value of the property the option of the same name
+    names (if any)  */
+const optionValue = (ctx, diagram, node, key) => {
+    const name = diagram[key];
+    const value = name !== undefined ? propValue(ctx.parenProps, node, name) : undefined;
+    return value !== undefined ? plainText(value).trim() : undefined;
+};
 /*  generate the Gradia spec text of a derived diagram, opened by a
     "#type" directive and the configured "#config" directives so every
     embedded spec is self-contained: one node statement per object (the
     unique anchor path as the node id, the object name as the displayed
-    label, the container node as the parent) and one edge statement per
-    derived edge  */
-const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting) => {
+    label, the container node as the parent, band, or cluster, the badge icon
+    and the multiplicity of its object kind, the "incomplete" mark of an
+    uncovered object, the pseudo-state kind of a synthetic pseudo-state,
+    the place or transition kind of a Petri net node, the duration and
+    start of a task) and one edge statement per derived edge  */
+const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting, pseudo, places) => {
     const { index, anchors, positions, parenProps } = ctx;
     const lines = [`#type ${type}`];
     const config = { ...diagramPresets, ...diagram.config };
@@ -86,9 +124,10 @@ const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting
     /*  the explicit top-down order of an "ordered" diagram: the members
         of a container share one row (which Gradia wraps), while the
         top-level nodes stack in document order, a synthetic container
-        taking the position of its first member  */
+        taking the position of its first member (a "matrix" or "tree"
+        knows no container rows, so there every node takes its own position)  */
     const orderOf = (node) => {
-        if (nesting.parentOf.has(node))
+        if (nesting.parentOf.has(node) && type !== "matrix" && type !== "tree")
             return 0;
         let order = positions.get(node) ?? Number.MAX_SAFE_INTEGER;
         for (const [member, container] of nesting.parentOf)
@@ -109,12 +148,61 @@ const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting
         if (type === "hub" ? node === center : node.primary === true)
             attrs.push("primary: true");
         const container = nesting.parentOf.get(node);
-        if (container !== undefined)
+        const banded = type === "layer" || type === "slice";
+        if (banded || type === "matrix" || type === "gantt") {
+            /*  a "layer", "slice", "matrix", or "gantt" diagram knows no
+                containers: in a "layer" or "slice" one the container
+                names the band of the node and the containers enclosing
+                it the path of the clusters grouping that band, while in
+                a "matrix" one a container (itself a row and column there)
+                and all containers of a node form the path of its partition
+                (in a "gantt" one just the containers of a task, as a
+                container is no task)  */
+            if (banded && container !== undefined)
+                attrs.push(`${type}: ${atom(plainText(container.name))}`);
+            const clusters = new Array();
+            for (let p = banded ? (container !== undefined ? nesting.parentOf.get(container) : undefined) :
+                nesting.containers.has(node) ? node : container; p !== undefined; p = nesting.parentOf.get(p))
+                clusters.unshift(plainText(p.name));
+            if (clusters.length > 0)
+                attrs.push(`cluster: ${atom(clusters.join("/"))}`);
+        }
+        else if (container !== undefined && type !== "tree")
             attrs.push(`parent: ${atom(anchors.get(container) ?? container.id)}`);
         if (diagram.nest?.layout !== undefined && nesting.containers.has(node))
             attrs.push(`container: ${diagram.nest.layout}`);
         if (diagram.ordered === true)
             attrs.push(`order: ${orderOf(node)}`);
+        const badge = badgeOf(ctx, node);
+        if (badge !== undefined)
+            attrs.push(`badge: ${badge}`);
+        if (isMultiple(ctx, node))
+            attrs.push("multiple: true");
+        const marking = diagram.markUncovered ?? "none";
+        if (((marking === "referenced" || marking === "all") && ctx.uncovered.referenced.has(node))
+            || ((marking === "coverage" || marking === "all") && ctx.uncovered.coverage.has(node)))
+            attrs.push("mark: incomplete");
+        const state = pseudo.get(node);
+        if (state !== undefined)
+            attrs.push(`state: ${state}`);
+        /*  the kind of a node of a "petri" diagram, plus the initial
+            tokens and the capacity of a place, and the duration and the
+            earliest start of a task of a "gantt" diagram  */
+        if (places !== undefined) {
+            attrs.push(`petri: ${places.has(node) ? "place" : "transition"}`);
+            if (places.has(node))
+                for (const key of ["tokens", "capacity"]) {
+                    const value = optionValue(ctx, diagram, node, key);
+                    if (value !== undefined)
+                        attrs.push(`${key}: ${value}`);
+                }
+        }
+        if (type === "gantt")
+            for (const key of ["duration", "start"]) {
+                const value = optionValue(ctx, diagram, node, key);
+                if (value !== undefined)
+                    attrs.push(`${key}: ${value}`);
+            }
         /*  attach the values of the configured properties as Gradia
             key/value attributes (a node lacking a property is fine, as
             the node set can mix objects of different kinds), with every
@@ -135,17 +223,29 @@ const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting
             const op = "--" +
                 (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
                 (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
+            const attrs = new Array();
+            if (edge.kind !== undefined && edge.kind !== "sync")
+                attrs.push(`kind: ${edge.kind}`);
+            if (edge.duration !== undefined && edge.duration !== "")
+                attrs.push(`duration: ${atom(edge.duration)}`);
+            if (edge.time !== undefined && edge.time !== "")
+                attrs.push(`time: ${atom(edge.time)}`);
             lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
-                atom(anchors.get(edge.target) ?? edge.target.id));
+                atom(anchors.get(edge.target) ?? edge.target.id) +
+                (attrs.length > 0 ? ` { ${attrs.join(", ")} }` : ""));
         }
     }
     return lines.join("\n") + "\n";
 };
 /*  derive the reference edges of a diagram from the "[[...]]" references
-    of the node objects (per the "links" selection, named with the
-    property key when "labeled", and for a "deep" diagram also of their
-    descendants, with the reference count as the arity), with every
-    target lifted to its nearest node  */
+    of the node objects (per the "links" selection: all property values,
+    also the texts, or the values of the listed properties only, named
+    with the property key when "labeled", for a "deep" diagram also of
+    their descendants, with the reference count as the arity, and also
+    of their descendants of the "descend" kinds, uncounted and named with
+    the descendant kind when "labeled"), with every target lifted to its
+    nearest node, and with the edges of the "reverse" properties pointing
+    back onto the node  */
 const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
     const { index, anchors, parents, parenProps } = ctx;
     const edges = new Array();
@@ -159,22 +259,34 @@ const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
     };
     for (const node of nodes) {
         /*  the reference-carrying objects of the node: the node itself
-            and, for a "deep" diagram, its descendants (halting at
-            the descendants which are nodes on their own)  */
+            and, for a "deep" diagram, its descendants, else its
+            descendants of the "descend" kinds (each halting at the
+            descendants which are nodes on their own)  */
         const objects = new Array();
+        const descended = new Set();
         const walk = (object) => {
             objects.push(object);
-            if (diagram.deep === true)
-                for (const child of object.children)
-                    if (!nodeSet.has(child))
-                        walk(child);
+            for (const child of object.children) {
+                if (nodeSet.has(child))
+                    continue;
+                if (diagram.deep === true)
+                    walk(child);
+                else if ((diagram.descend ?? []).includes(child.kind)) {
+                    descended.add(child);
+                    walk(child);
+                }
+            }
         };
         walk(node);
         const counts = new Map();
         for (const object of objects) {
-            const texts = propsOf(parenProps, object).map((property) => ({
+            const texts = propsOf(parenProps, object)
+                .filter((property) => !Array.isArray(diagram.links) || diagram.links.includes(property.key))
+                .map((property) => ({
                 text: property.value,
-                name: diagram.labeled === true ? property.key.toLowerCase() : undefined
+                name: diagram.labeled !== true ? undefined :
+                    descended.has(object) ? object.kind.toLowerCase() : property.key.toLowerCase(),
+                reversed: (diagram.reverse ?? []).includes(property.key)
             }));
             if (diagram.links === "all" && object.description !== undefined) {
                 texts.push({ text: object.description.description });
@@ -183,19 +295,20 @@ const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
                 if (object.description.elaboration !== undefined)
                     texts.push({ text: object.description.elaboration });
             }
-            for (const { text, name } of texts)
-                for (const m of plainText(text).matchAll(referenceRegex)) {
+            for (const { text, name, reversed = false } of texts)
+                for (const m of referenceText(text).matchAll(referenceRegex)) {
                     const target = lift(resolveUnique(index, m[1].trim(), object).target);
                     if (target !== undefined && target !== node) {
-                        const key = `${anchors.get(target) ?? target.id}\u0000${name ?? ""}`;
-                        const entry = counts.get(key) ?? { target, name, count: 0 };
+                        const key = `${anchors.get(target) ?? target.id}\u0000${name ?? ""}\u0000${reversed}`;
+                        const entry = counts.get(key) ?? { target, name, reversed, count: 0 };
                         entry.count++;
                         counts.set(key, entry);
                     }
                 }
         }
-        for (const { target, name, count } of counts.values())
-            edges.push({ source: node, target, name,
+        /*  an edge of a "reverse" property points back onto the node  */
+        for (const { target, name, reversed, count } of counts.values())
+            edges.push({ source: reversed ? target : node, target: reversed ? node : target, name,
                 arity: diagram.deep === true ? String(count) : undefined });
     }
     return edges;
@@ -203,52 +316,195 @@ const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
 /*  derive the object edges of a diagram from the edge objects by
     convention (source: parent object, target: first reference in the
     property values, name: object name, arity: "ARITY" property),
-    overridable via "edgeSource"/"edgeTarget"/"edgeArity"  */
-const deriveObjectEdges = (ctx, diagram, nodeSet, edgeObjects, errors) => {
+    overridable via "edgeSource"/"edgeTarget"/"edgeArity", where a
+    configured target property carrying several references (a "list"
+    valued one) yields one edge per resolvable target, where the
+    "edgeGuard" property value follows the name in brackets, and where
+    the "edgeKind", "edgeDuration", and "edgeTime" property values make
+    the message kind and the timing constraints of a "sequence" diagram  */
+const deriveObjectEdges = (ctx, diagram, admits, edgeObjects, errors) => {
     const { index, parents, parenProps } = ctx;
     const edges = new Array();
-    /*  resolve the node an edge object references through a named
-        property, or through its first single-reference property when
-        no name is configured (skipping the source property)  */
-    const edgeNode = (edgeObject, key) => {
+    /*  resolve the nodes an edge object references through a named
+        property (all of its references), or through the first reference
+        of its first single-reference property when no name is configured
+        (skipping the source property)  */
+    const edgeNodes = (edgeObject, key) => {
         const value = key !== undefined ?
             propValue(parenProps, edgeObject, key) :
             propsOf(parenProps, edgeObject).filter((property) => property.key !== diagram.edgeSource)
-                .map((property) => property.value).find((v) => referenceOnce.test(v));
-        const reference = value !== undefined ? plainText(value).match(referenceOnce)?.[1].trim() : undefined;
-        return reference !== undefined ? resolveUnique(index, reference, edgeObject).target : undefined;
+                .map((property) => property.value).find((v) => referenceOnce.test(referenceText(v)));
+        if (value === undefined)
+            return [];
+        const references = Array.from(referenceText(value).matchAll(referenceRegex), (m) => m[1].trim());
+        return (key !== undefined ? references : references.slice(0, 1))
+            .map((reference) => resolveUnique(index, reference, edgeObject).target)
+            .filter((target) => target !== undefined);
     };
     for (const edgeObject of edgeObjects) {
         const source = diagram.edgeSource !== undefined ?
-            edgeNode(edgeObject, diagram.edgeSource) : parents.get(edgeObject);
-        const target = edgeNode(edgeObject, diagram.edgeTarget);
+            edgeNodes(edgeObject, diagram.edgeSource)[0] : parents.get(edgeObject);
+        const targets = edgeNodes(edgeObject, diagram.edgeTarget);
         if (source === undefined) {
             errors.push({ object: edgeObject, reason: diagram.edgeSource !== undefined ?
                     "carries no resolvable source reference" :
                     "has no parent object as source" });
             continue;
         }
-        if (target === undefined) {
+        if (targets.length === 0) {
             errors.push({ object: edgeObject, reason: "carries no resolvable target reference" });
             continue;
         }
-        if (!nodeSet.has(source) || !nodeSet.has(target))
-            continue;
         const arity = propValue(parenProps, edgeObject, diagram.edgeArity ?? "ARITY");
-        edges.push({ source, target, name: plainText(edgeObject.name),
-            arity: arity !== undefined ? plainText(arity) : undefined });
+        const guard = diagram.edgeGuard !== undefined ?
+            propValue(parenProps, edgeObject, diagram.edgeGuard) : undefined;
+        const name = plainText(edgeObject.name) + (guard !== undefined ?
+            ` [${plainText(expandReferences(guard, (reference) => resolveUnique(index, reference, edgeObject).target?.name ?? reference))}]` : "");
+        const text = (key) => {
+            const value = key !== undefined ? propValue(parenProps, edgeObject, key) : undefined;
+            return value !== undefined ? plainText(value).trim() : undefined;
+        };
+        const label = text(diagram.edgeKind);
+        const kind = label !== undefined && Object.hasOwn(messageKinds, label.toLowerCase()) ?
+            messageKinds[label.toLowerCase()] : undefined;
+        if (label !== undefined && kind === undefined) {
+            errors.push({ object: edgeObject, reason: `carries the unknown message kind "${label}"` });
+            continue;
+        }
+        for (const target of targets)
+            if (admits(source) && admits(target))
+                edges.push({ source, target, name,
+                    arity: arity !== undefined ? plainText(arity) : undefined,
+                    kind, duration: text(diagram.edgeDuration), time: text(diagram.edgeTime), object: edgeObject });
     }
     return edges;
 };
+/*  validate the messages of a "sequence" diagram exactly like Gradia
+    does, so an invalid message becomes a diagnostic on its edge object
+    instead of failing the rendering: a participant is created at most
+    once, and only by the first message it takes part in, takes part in
+    no further message once destroyed, and a duration constraint needs
+    a call answered by a return (the next return from its callee to its
+    caller, answering the innermost such call still open on the callee)  */
+const validateMessages = (edges, errors) => {
+    const seen = new Set();
+    const destroyed = new Set();
+    const pending = new Map();
+    const answered = new Set();
+    edges.forEach((edge, i) => {
+        const kind = edge.kind ?? "sync";
+        for (const party of [edge.source, edge.target])
+            if (destroyed.has(party))
+                errors.push({ object: edge.object,
+                    reason: `involves participant "${party.name}" after its destruction` });
+        if (kind === "create" && (edge.source === edge.target || seen.has(edge.target)))
+            errors.push({ object: edge.object, reason: `cannot create participant "${edge.target.name}", ` +
+                    "as only the first message a participant takes part in can create it" });
+        seen.add(edge.source);
+        seen.add(edge.target);
+        if (kind === "destroy")
+            destroyed.add(edge.target);
+        if (kind === "sync" || kind === "create")
+            pending.set(edge.target, [...(pending.get(edge.target) ?? []), i]);
+        else if (kind === "return") {
+            const calls = pending.get(edge.source) ?? [];
+            const k = calls.findLastIndex((call) => edges[call].source === edge.target);
+            if (k >= 0) {
+                answered.add(calls[k]);
+                calls.length = k;
+            }
+        }
+    });
+    edges.forEach((edge, i) => {
+        if (edge.duration !== undefined && edge.duration !== "" && !answered.has(i))
+            errors.push({ object: edge.object,
+                reason: "carries a duration, but is not a call answered by a return" });
+    });
+};
+/*  validate the net of a "petri" diagram exactly like Gradia does, so
+    an invalid net becomes a diagnostic on the offending object instead
+    of failing the rendering: the initial tokens of a place are an
+    integer of at least 0 and its capacity one of at least 1, holding
+    them, and every arc connects a place with a transition  */
+const validatePetri = (ctx, diagram, nodes, edges, places, errors) => {
+    for (const node of nodes) {
+        if (!places.has(node))
+            continue;
+        const numbers = {};
+        for (const [key, min] of [["tokens", 0], ["capacity", 1]]) {
+            const value = optionValue(ctx, diagram, node, key);
+            if (value === undefined)
+                continue;
+            if (!(/^\d+$/).test(value) || Number(value) < min)
+                errors.push({ object: node, reason: `carries the invalid ${key} "${value}" ` +
+                        `(expected an integer of at least ${min})` });
+            else
+                numbers[key] = Number(value);
+        }
+        if (numbers.tokens !== undefined && numbers.capacity !== undefined && numbers.tokens > numbers.capacity)
+            errors.push({ object: node, reason: "carries more tokens than its capacity" });
+    }
+    for (const edge of edges)
+        if (places.has(edge.source) === places.has(edge.target))
+            errors.push({ object: edge.object ?? edge.source,
+                reason: `connects ${places.has(edge.source) ? "place" : "transition"} "${edge.source.name}" ` +
+                    `with ${places.has(edge.target) ? "place" : "transition"} "${edge.target.name}", ` +
+                    "but an arc connects a place with a transition only" });
+};
+/*  validate the schedule of a "gantt" diagram exactly like Gradia does,
+    so an invalid plan becomes a diagnostic on the offending object
+    instead of failing the rendering: the duration and the earliest
+    start of a task are non-negative numbers, and the dependencies form
+    no cycle (reported on the first task of the cycle found)  */
+const validateGantt = (ctx, diagram, nodes, edges, errors) => {
+    for (const node of nodes)
+        for (const key of ["duration", "start"]) {
+            const value = optionValue(ctx, diagram, node, key);
+            if (value !== undefined && !(/^\d+(?:\.\d+)?$/).test(value))
+                errors.push({ object: node, reason: `carries the invalid ${key} "${value}" ` +
+                        "(expected a non-negative number)" });
+        }
+    const successors = new Map();
+    for (const edge of edges)
+        successors.set(edge.source, [...(successors.get(edge.source) ?? []), edge.target]);
+    const done = new Set();
+    const path = new Set();
+    const visit = (node) => {
+        if (path.has(node))
+            return true;
+        if (done.has(node))
+            return false;
+        path.add(node);
+        const cyclic = (successors.get(node) ?? []).some(visit);
+        path.delete(node);
+        done.add(node);
+        return cyclic;
+    };
+    for (const node of nodes)
+        if (visit(node)) {
+            errors.push({ object: node, reason: "takes part in a cycle of dependencies" });
+            break;
+        }
+};
 /*  derive the edges of a diagram: the reference edges of the node
     objects, the object edges of the edge objects, and the containment
     edges of the object hierarchy (a "grid" diagram is edge-less by
-    definition, so no edges are derived at all)  */
+    definition, so no edges are derived at all, and a "sequence" diagram
+    knows the object edges, its messages, only)  */
 const deriveEdges = (ctx, diagram, type, nodes, nodeSet, edgeObjects, errors) => {
     const edges = new Array();
-    if (type !== "grid") {
+    if (type === "sequence") {
+        /*  a "sequence" diagram draws the edge objects as its messages
+            alone, as references and the object nesting carry no order,
+            between any objects unless "nodes" restricts its participants  */
+        for (const field of ["links", "hierarchy", "deep", "descend", "reverse", "labeled"])
+            if (diagram[field] !== undefined && diagram[field] !== false)
+                errors.push({ reason: `"sequence" diagram cannot carry a "${field}" configuration` });
+        edges.push(...deriveObjectEdges(ctx, diagram, (object) => diagram.nodes === undefined || nodeSet.has(object), edgeObjects, errors));
+    }
+    else if (type !== "grid") {
         edges.push(...deriveReferenceEdges(ctx, diagram, nodes, nodeSet));
-        edges.push(...deriveObjectEdges(ctx, diagram, nodeSet, edgeObjects, errors));
+        edges.push(...deriveObjectEdges(ctx, diagram, (object) => nodeSet.has(object), edgeObjects, errors));
         /*  derive the containment edges from the object hierarchy, as
             the nesting of the objects carries no "[[...]]" reference  */
         if (diagram.hierarchy === true)
@@ -259,7 +515,7 @@ const deriveEdges = (ctx, diagram, type, nodes, nodeSet, edgeObjects, errors) =>
             }
     }
     else {
-        for (const field of ["edges", "hierarchy", "deep", "labeled", "onlyConnected"])
+        for (const field of ["edges", "hierarchy", "deep", "descend", "reverse", "labeled", "onlyConnected"])
             if (diagram[field] !== undefined && diagram[field] !== false)
                 errors.push({ reason: "\"grid\" diagram cannot carry " +
                         `${(/^[aeiou]/).test(field) ? "an" : "a"} "${field}" configuration` });
@@ -408,25 +664,36 @@ const deriveCenterEdges = (ctx, cfg, nodes, center, errors) => {
 };
 /*  derive the nesting of the nodes into container nodes: per node the
     first configured property carrying exactly one resolvable reference
-    names its container (added to the node set when absent, and nested
-    on its own in turn), else its parent object when part of the node
-    set, else a synthetic container per object kind; a node nested into
-    itself or into a cycle stays un-nested and is reported  */
-const deriveNesting = (ctx, nest, nodes, nodeSet, errors) => {
+    (or, with "multiple", at least one, the further ones collected
+    apart) names its container (added to the node set when absent, and
+    nested on its own in turn), else its parent object when part of the
+    node set, else a synthetic container per object kind; a node nested
+    into itself or into a cycle stays un-nested and is reported  */
+const deriveNesting = (ctx, nest, nodes, nodeSet, errors, multiple = false) => {
     const { index, parents, parenProps } = ctx;
     const parentOf = new Map();
+    const furtherOf = new Map();
     const byKind = new Map();
+    const include = (container) => {
+        if (!nodeSet.has(container)) {
+            nodes.push(container);
+            nodeSet.add(container);
+        }
+    };
     /*  the iteration also visits the containers appended underway  */
     for (const node of nodes) {
         let container;
+        let further = new Array();
         for (const key of nest.properties ?? []) {
             const value = propValue(parenProps, node, key);
-            const refs = value !== undefined ? Array.from(plainText(value).matchAll(referenceRegex)) : [];
-            if (refs.length !== 1)
-                continue;
-            container = resolveUnique(index, refs[0][1].trim(), node).target;
-            if (container !== undefined)
+            const refs = value !== undefined ? Array.from(referenceText(value).matchAll(referenceRegex)) : [];
+            const targets = (multiple || refs.length === 1 ? refs : [])
+                .map((ref) => resolveUnique(index, ref[1].trim(), node).target)
+                .filter((target) => target !== undefined);
+            if (targets.length > 0) {
+                [container, ...further] = targets;
                 break;
+            }
         }
         if (container === undefined && nest.parent === true) {
             const parent = parents.get(node);
@@ -452,12 +719,13 @@ const deriveNesting = (ctx, nest, nodes, nodeSet, errors) => {
             continue;
         }
         parentOf.set(node, container);
-        if (!nodeSet.has(container)) {
-            nodes.push(container);
-            nodeSet.add(container);
+        include(container);
+        if (further.length > 0) {
+            furtherOf.set(node, further);
+            further.forEach(include);
         }
     }
-    return { parentOf, containers: new Set(parentOf.values()) };
+    return { parentOf, containers: new Set(parentOf.values()), furtherOf };
 };
 /*  lift the edges crossing a container boundary onto the containers:
     an end is replaced by its outermost ancestor container not enclosing
@@ -516,6 +784,8 @@ const deriveNodes = (index, object, diagram, errors) => {
     walk(object);
     return nodes;
 };
+/*  the end objects of a list of edges, in the order of their first occurrence  */
+const endsOf = (edges) => new Set(edges.flatMap((edge) => [edge.source, edge.target]));
 /*  project a "hub" diagram onto its center object: only the edges
     incident to the center and only the nodes connected through them
     remain, as Gradia requires exactly this constrained topology, and
@@ -525,33 +795,45 @@ const deriveNodes = (index, object, diagram, errors) => {
     target of its self-loop, too  */
 const projectHub = (nodes, edges, center) => {
     const incident = edges.filter((edge) => edge.source === center || edge.target === center);
-    const connected = new Set([center]);
-    for (const edge of incident) {
-        connected.add(edge.source);
-        connected.add(edge.target);
-    }
+    const connected = endsOf(incident).add(center);
     const columns = 1 +
         (incident.some((edge) => edge.target === center && edge.source !== center) ? 1 : 0) +
         (incident.some((edge) => edge.source === center) ? 1 : 0);
     return { nodes: nodes.filter((node) => connected.has(node)), edges: incident, columns };
 };
 /*  derive the Gradia spec of a single object from its "diagram:"
-    schema configuration (the returned spec is absent whenever the
-    configured diagram situation is invalid, the node set is empty,
-    or the diagram collapses onto a single node)  */
-const deriveDiagram = (ctx, object, diagram) => {
-    const { index, anchors } = ctx;
+    schema configuration and its optional "automaton:" one (the
+    returned spec is absent whenever the configured diagram situation
+    is invalid, the node set is empty, or the diagram collapses onto a
+    single node)  */
+const deriveDiagram = (ctx, object, diagram, automaton) => {
+    const { index, anchors, parenProps } = ctx;
     const type = diagram.type ?? "graph";
     const errors = new Array();
     /*  determine the node objects and the edge objects (default: none),
-        with the edge objects never acting as nodes themselves  */
-    let nodes = deriveNodes(index, object, diagram, errors);
-    const edgeObjects = diagram.edges !== undefined ? resolvePatterns(index, errors, diagram.edges, "edges") : [];
+        with the edge objects never acting as nodes themselves, where a
+        "local" diagram keeps only the matches of its patterns below
+        the object itself (as the patterns match corpus-wide), and where
+        a "sequence" diagram without "nodes" takes its participants from
+        its messages instead (see below)  */
+    let nodes = type === "sequence" && diagram.nodes === undefined ? [] :
+        deriveNodes(index, object, diagram, errors);
+    let edgeObjects = diagram.edges !== undefined ? resolvePatterns(index, errors, diagram.edges, "edges") : [];
+    if (diagram.local === true) {
+        const below = (match) => chainOf(index, match).includes(object);
+        nodes = nodes.filter(below);
+        edgeObjects = edgeObjects.filter(below);
+    }
     const edgeSet = new Set(edgeObjects);
     nodes = nodes.filter((node) => !edgeSet.has(node));
     const nodeSet = new Set(nodes);
-    /*  derive the edges of the diagram  */
+    /*  derive the edges of the diagram, with the message kinds and the
+        timing constraints known to a "sequence" diagram only  */
     let edges = deriveEdges(ctx, diagram, type, nodes, nodeSet, edgeObjects, errors);
+    if (type !== "sequence")
+        for (const field of ["edgeKind", "edgeDuration", "edgeTime"])
+            if (diagram[field] !== undefined)
+                errors.push({ reason: `"${type}" diagram cannot carry an "${field}" configuration` });
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
     if (type !== "hub") {
@@ -563,15 +845,25 @@ const deriveDiagram = (ctx, object, diagram) => {
     const derived = type === "hub" ?
         deriveCenter(ctx, object, diagram, nodes, nodeSet, errors) : { center: object };
     if (derived === undefined)
-        return { errors };
+        return { type, errors };
     const { center, centerUrl } = derived;
     /*  synthesize the center edges of a "hub" diagram, as the nodes
         carry no "[[...]]" reference to a synthetic center, and only
         then deduplicate all edges, as a center edge of a real center
-        can coincide with a reference edge of a node onto it  */
+        can coincide with a reference edge of a node onto it (except
+        the messages of a "sequence" diagram, which may repeat)  */
     if (type === "hub" && diagram.centerEdges !== undefined)
         edges.push(...deriveCenterEdges(ctx, diagram.centerEdges, nodes, center, errors));
-    edges = dedupEdges(edges, anchors);
+    if (type !== "sequence")
+        edges = dedupEdges(edges, anchors);
+    /*  the participants of a "sequence" diagram line up in the order
+        their messages first involve them, the uninvolved ones dropped  */
+    if (type === "sequence") {
+        nodes = Array.from(endsOf(edges));
+        if (diagram.ordered === true)
+            errors.push({ reason: "\"sequence\" diagram cannot carry an \"ordered\" configuration" });
+        validateMessages(edges, errors);
+    }
     /*  project a "hub" diagram onto its center object, which has
         to be part of the node set  */
     let columns;
@@ -582,37 +874,98 @@ const deriveDiagram = (ctx, object, diagram) => {
             ({ nodes, edges, columns } = projectHub(nodes, edges, center));
     }
     /*  nest the nodes into container nodes (except in a "hub" diagram,
-        where every container would need a primary node of its own),
-        dropping the edges between a container and its own members,
-        which Gradia rejects, as the nesting already shows them  */
-    let nesting = { parentOf: new Map(), containers: new Set() };
+        where every container would need a primary node of its own, in a
+        "state" diagram, where every container would be a composite state
+        needing an initial state of its own, and in a "sequence" or "petri"
+        diagram, whose nodes nest not at all), dropping the edges between
+        a container and its own members, which Gradia rejects, as the
+        nesting already shows them  */
+    let nesting = { parentOf: new Map(), containers: new Set(), furtherOf: new Map() };
     if (diagram.nest !== undefined) {
-        if (type === "hub")
-            errors.push({ reason: "\"hub\" diagram cannot carry a \"nest\" configuration" });
+        if (type === "hub" || type === "state" || type === "sequence" || type === "petri")
+            errors.push({ reason: `"${type}" diagram cannot carry a "nest" configuration` });
         else {
-            nesting = deriveNesting(ctx, diagram.nest, nodes, nodeSet, errors);
-            if (diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
+            nesting = deriveNesting(ctx, diagram.nest, nodes, nodeSet, errors, type === "tree");
+            const banded = type === "layer" || type === "slice" || type === "gantt";
+            if ((banded || type === "tree" || type === "matrix") && diagram.nest.layout !== undefined)
+                errors.push({ reason: `"${type}" diagram cannot carry a "nest" layout configuration` });
+            if ((banded || type === "tree") && diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
+                errors.push({ reason: `"${type}" diagram cannot carry a "nest" crossing configuration` });
+            if (banded) {
+                /*  a "layer" or "slice" diagram draws its containers as
+                    bands and cluster groups, a "gantt" one as the
+                    partitions of its rows, instead of as nodes, so they
+                    drop the edges ending at one  */
+                nodes = nodes.filter((node) => !nesting.containers.has(node));
+                edges = edges.filter((edge) => !nesting.containers.has(edge.source)
+                    && !nesting.containers.has(edge.target));
+            }
+            else if (type !== "tree" && diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
                 edges = liftEdges(edges, nesting.parentOf, diagram.nest.crossing, anchors);
-            edges = edges.filter((edge) => nesting.parentOf.get(edge.source) !== edge.target
-                && nesting.parentOf.get(edge.target) !== edge.source);
+            /*  a "matrix" diagram keeps its containers as regular rows
+                and columns (only partitioning their members), so it
+                keeps their edges onto their own members, too  */
+            if (type !== "matrix")
+                edges = edges.filter((edge) => nesting.parentOf.get(edge.source) !== edge.target
+                    && nesting.parentOf.get(edge.target) !== edge.source);
+            /*  a "tree" diagram draws the nesting as its parent-to-child
+                edges (the containers staying nodes), placed first, as the
+                first edge into a node makes its source the parent, while
+                every other edge (the ones from the further containers of
+                a node included) becomes a dashed cross link  */
+            if (type === "tree")
+                edges = [
+                    ...Array.from(nesting.parentOf, ([member, container]) => ({ source: container, target: member })),
+                    ...Array.from(nesting.furtherOf).flatMap(([member, further]) => further.map((container) => ({ source: container, target: member }))),
+                    ...edges
+                ];
         }
     }
+    if ((type === "layer" || type === "slice") && diagram.ordered === true)
+        errors.push({ reason: `"${type}" diagram cannot carry an "ordered" configuration` });
     /*  the "onlyConnected" filtering keeps only the nodes with at
-        least one incident edge (sensible for "graph" diagrams only),
-        and the containers enclosing such a node  */
-    if (diagram.onlyConnected === true && type === "graph") {
-        const connected = new Set();
-        for (const edge of edges) {
-            connected.add(edge.source);
-            connected.add(edge.target);
-        }
+        least one incident edge (sensible for all diagrams except the
+        "hub" and "grid" ones), and the containers enclosing such a node  */
+    if (diagram.onlyConnected === true && type !== "hub" && type !== "grid") {
+        const connected = endsOf(edges);
         for (const node of Array.from(connected))
             for (let p = nesting.parentOf.get(node); p !== undefined; p = nesting.parentOf.get(p))
                 connected.add(p);
         nodes = nodes.filter((node) => connected.has(node));
     }
+    /*  a "matrix" diagram keeps a container as a row and column only
+        where it takes part in the relation itself, as a mere grouping
+        object (like a requirement group) would yield an empty row and
+        column, while it still names the partition of its members  */
+    if (type === "matrix")
+        nodes = nodes.filter((node) => !nesting.containers.has(node)
+            || edges.some((edge) => edge.source === node || edge.target === node));
+    /*  a "petri" diagram takes the objects matching its "places" patterns
+        as its places and all other nodes as its transitions (without
+        "places", Gradia infers them from the arcs), where the "tokens"
+        and "capacity" options name properties of the places  */
+    let places;
+    if (type === "petri" && diagram.places !== undefined) {
+        places = new Set(resolvePatterns(index, errors, diagram.places, "places"));
+        validatePetri(ctx, diagram, nodes, edges, places, errors);
+    }
+    else
+        for (const field of ["places", "tokens", "capacity"])
+            if (diagram[field] !== undefined)
+                errors.push({ reason: type === "petri" ?
+                        `"petri" diagram cannot carry a "${field}" configuration without a "places" one` :
+                        `"${type}" diagram cannot carry a "${field}" configuration` });
+    /*  a "gantt" diagram takes the nodes as its tasks (a node without a
+        duration being a milestone) and the edges as their dependencies,
+        where the "duration" and "start" options name properties of the tasks  */
+    if (type === "gantt")
+        validateGantt(ctx, diagram, nodes, edges, errors);
+    else
+        for (const field of ["duration", "start"])
+            if (diagram[field] !== undefined)
+                errors.push({ reason: `"${type}" diagram cannot carry a "${field}" configuration` });
     if (errors.length > 0)
-        return { errors };
+        return { type, errors };
     /*  an empty node set silently omits the diagram, as a wildcard
         "nodes" pattern legitimately matches nothing when an optional
         kind is absent, and the "collapse" handling (enabled by default)
@@ -620,16 +973,41 @@ const deriveDiagram = (ctx, object, diagram) => {
         such a diagram carries no information beyond the object itself  */
     if (nodes.length === 0
         || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
-        return { errors };
-    return { spec: renderSpec(ctx, diagram, type, center, centerUrl, nodes, edges, nesting),
+        return { type, errors };
+    /*  a "state" diagram of an object kind carrying an "automaton" draws
+        its flags as pseudo-states, which Gradia knows instead: a single
+        initial one leading into every node flagged initial, and a single
+        final one every node flagged final leads into  */
+    const pseudo = new Map();
+    if (type === "state" && automaton !== undefined) {
+        for (const role of ["initial", "final"]) {
+            const states = nodes.filter((node) => node.kind === automaton.nodes
+                && plainText(propValue(parenProps, node, automaton[role]) ?? "").trim() === "true");
+            if (states.length === 0)
+                continue;
+            const state = { kind: "", id: `${anchors.get(object) ?? object.id}-@${role}`,
+                name: role, properties: [], children: [] };
+            pseudo.set(state, role);
+            if (role === "initial") {
+                nodes.unshift(state);
+                edges.push(...states.map((target) => ({ source: state, target })));
+            }
+            else {
+                nodes.push(state);
+                edges.push(...states.map((source) => ({ source, target: state })));
+            }
+        }
+    }
+    return { type, spec: renderSpec(ctx, diagram, type, center, centerUrl, nodes, edges, nesting, pseudo, places),
         config: { ...diagramPresets, ...diagram.config }, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
     lint validation and every renderer of an export derive the very
     same diagrams of the very same parsed specification again  */
 const derivations = new WeakMap();
-/*  derive the Gradia specs of all diagram-configured objects
-    of a specification (memoized per specification and schema)  */
+/*  derive the Gradia specs of all diagrams of all diagram-configured
+    objects of a specification, in their configured order (memoized
+    per specification and schema)  */
 export const specDiagrams = (specification, config) => {
     const derived = derivations.get(specification);
     if (derived !== undefined && derived.config === config)
@@ -643,35 +1021,54 @@ export const specDiagrams = (specification, config) => {
         positions.set(node.object, position);
     });
     const schemas = collectSchemas(specification, config);
-    /*  re-derive the synthetic properties of the consumed parenthesized
+    /*  determine the uncovered objects (only where a diagram marks them
+        at all, as resolving all references is not for free): the ones
+        lacking their demanded "referenced" coverage, and the ones a
+        "coverage" report counts as unreferenced while no other report
+        counts them as referenced; and
+        re-derive the synthetic properties of the consumed parenthesized
         name tokens, as the derivation sees the AST alone, while the
         parsing context holding them is long gone by export time  */
-    const ctx = { index, anchors, positions, parents, parenProps: collectParenProps(schemas) };
+    const markings = new Set(Array.from(schemas.values()).flatMap((schema) => diagramsOf(schema).map((diagram) => diagram.markUncovered ?? "none")));
+    const uncovered = { referenced: new Set(), coverage: new Set() };
+    if (markings.has("referenced") || markings.has("all"))
+        for (const result of referencedCoverage(index, schemas))
+            result.uncovered.forEach((object) => uncovered.referenced.add(object));
+    if (markings.has("coverage") || markings.has("all")) {
+        const reports = Array.from(specCoverage(index, schemas).values()).flat();
+        const covered = new Set(reports.flatMap((report) => report.covered));
+        for (const report of reports)
+            for (const object of report.uncovered)
+                if (!covered.has(object))
+                    uncovered.coverage.add(object);
+    }
+    const ctx = { index, anchors, positions, parents, schemas,
+        parenProps: collectParenProps(schemas), uncovered };
     const results = new Map();
-    for (const [object, schema] of schemas)
-        if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(ctx, object, schema.diagram));
+    for (const [object, schema] of schemas) {
+        const diagrams = diagramsOf(schema);
+        if (diagrams.length > 0)
+            results.set(object, diagrams.map((diagram) => deriveDiagram(ctx, object, diagram, schema.automaton)));
+    }
     derivations.set(specification, { config, results });
     return results;
 };
-/*  determine the diagram-configured objects whose diagrams the given
-    aspects omit: the ones of a diagram type and the ones from an object
-    tree nesting level on (the top-level objects being level 1)  */
+/*  determine the diagrams the given aspects omit: the ones of a diagram
+    type and the ones from an object tree nesting level on (the top-level
+    objects being level 1)  */
 export const omittedDiagrams = (specification, config, omit) => {
     const omitted = new Set();
     if (omit.size === 0)
         return omitted;
-    const schemas = collectSchemas(specification, config);
+    const results = specDiagrams(specification, config);
     for (const node of buildLinkIndex(specification)) {
-        const diagram = schemas.get(node.object)?.diagram;
-        if (diagram === undefined)
-            continue;
         let level = 1;
         for (let parent = node.parent; parent !== undefined; parent = parent.parent)
             level++;
-        if (omit.has(`diagram:${diagram.type ?? "graph"}`)
-            || [1, 2, 3].some((n) => n <= level && omit.has(`diagram:${n}`)))
-            omitted.add(node.object);
+        for (const result of results.get(node.object) ?? [])
+            if (omit.has(`diagram:${result.type}`)
+                || [1, 2, 3].some((n) => n <= level && omit.has(`diagram:${n}`)))
+                omitted.add(result);
     }
     return omitted;
 };
@@ -681,51 +1078,57 @@ export const omittedDiagrams = (specification, config, omit) => {
     passes and formats of a single export render the very same diagrams
     over and over again  */
 let svgCache = new Map();
-/*  render the Gradia specs of all diagram-configured objects of a
-    specification into embeddable SVGs (a runtime rendering failure omits
-    the diagram and is surfaced as a notice only, as the statically
-    detectable invalid situations are already reported as lint
-    diagnostics), served from the cache where possible, which is
-    afterwards swept to the diagrams of this very rendering, so it never
-    grows beyond a single document; the omitted diagrams are skipped  */
+/*  render the Gradia specs of all diagrams of all diagram-configured
+    objects of a specification into embeddable SVGs, in their configured
+    order (a runtime rendering failure omits the diagram and is surfaced
+    as a notice only, as the statically detectable invalid situations are
+    already reported as lint diagnostics), served from the cache where
+    possible, which is afterwards swept to the diagrams of this very
+    rendering, so it never grows beyond a single document; the omitted
+    diagrams are skipped  */
 export const renderDiagrams = async (specification, config, verbose, omit = new Set()) => {
     const cache = new Map();
     const rendered = new Map();
     const omitted = omittedDiagrams(specification, config, omit);
     let cached = 0;
-    for (const [object, result] of specDiagrams(specification, config)) {
-        if (result.spec === undefined || omitted.has(object))
-            continue;
-        const key = result.spec + JSON.stringify(result.config ?? {});
-        let svg = svgCache.get(key) ?? cache.get(key);
-        if (svg !== undefined)
-            cached++;
-        else {
-            try {
-                svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
-            }
-            catch (err) {
-                verbose?.(`rendering diagram of ${object.kind} "${literal(plainText(object.name))}" failed: ` +
-                    (err instanceof Error ? err.message : String(err)));
+    let total = 0;
+    for (const [object, results] of specDiagrams(specification, config)) {
+        for (const result of results) {
+            if (result.spec === undefined || omitted.has(result))
                 continue;
+            const key = result.spec + JSON.stringify(result.config ?? {});
+            let svg = svgCache.get(key) ?? cache.get(key);
+            if (svg !== undefined)
+                cached++;
+            else {
+                try {
+                    svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
+                }
+                catch (err) {
+                    verbose?.(`rendering ${result.type} diagram of ${object.kind} ` +
+                        `"${literal(plainText(object.name))}" failed: ` +
+                        (err instanceof Error ? err.message : String(err)));
+                    continue;
+                }
             }
+            cache.set(key, svg);
+            rendered.set(object, [...(rendered.get(object) ?? []), { ...result, svg }]);
+            total++;
         }
-        cache.set(key, svg);
-        rendered.set(object, { ...result, svg });
     }
     svgCache = cache;
-    if (cached > 0 && cached === rendered.size)
+    if (cached > 0 && cached === total)
         verbose?.(`reusing ${literal(cached)} cached diagram(s)`);
     else
-        verbose?.(`rendering ${literal(rendered.size)} diagram(s) (${literal(cached)} cached)`);
+        verbose?.(`rendering ${literal(total)} diagram(s) (${literal(cached)} cached)`);
     return rendered;
 };
 /*  validate all configured diagrams of a specification, reporting
     every invalid diagram situation as a file/line-precise diagnostic  */
 export const validateDiagrams = (ctx, specification, config) => {
     const seen = new Set();
-    for (const [object, result] of specDiagrams(specification, config))
-        for (const error of result.errors) {
+    for (const [object, results] of specDiagrams(specification, config))
+        for (const error of results.flatMap((result) => result.errors)) {
             /*  attribute an edge object situation to the offending edge
                 object itself and report it just once, as a wildcard
                 "edges" pattern lets every diagram walk the very same