@rse/specbook 1.0.3 → 1.1.0

package/dst/specbook-export-md.js

@@ -5,6 +5,7 @@
 */
 import { specDiagrams } from "./specbook-diagram.js";
 import { becauseRegex } from "./specbook-parse-common.js";
+import { isTitleObject } from "./specbook-export-common.js";
 /*  format a timestamp in the frontmatter format  */
 const formatTimestamp = (date) => {
     const pad = (n) => String(n).padStart(2, "0");
@@ -91,11 +92,12 @@ const renderObjectMd = (object, level, diagrams) => {
 export const renderMarkdown = (specification, config) => {
     /*  derive the Gradia specs of the diagram-configured objects
         (an invalid diagram situation omits the diagram, as it is
-        already reported as a lint diagnostic)  */
+        already reported as a lint diagnostic, and the diagram of
+        the title object is reserved for the HTML/PDF export)  */
     const diagrams = new Map();
     if (config !== undefined)
         for (const [object, result] of specDiagrams(specification, config))
-            if (result.spec !== undefined)
+            if (result.spec !== undefined && !isTitleObject(object))
                 diagrams.set(object, result.spec);
     /*  the single frontmatter block (only recognized at the start of a
         file on re-parse) carries the earliest creation and the latest

package/dst/specbook-format-schema.d.ts

@@ -7,22 +7,49 @@ export type SchemaObject = {
     id?: string;
     file?: string;
     desc?: string;
+    refs?: string;
     optional?: boolean;
+    referenced?: string[];
+    automaton?: SchemaAutomaton;
     diagram?: SchemaDiagram;
     format?: SchemaFormat;
     props?: SchemaProperty[];
     childs?: SchemaObject[];
 };
+export type SchemaAutomaton = {
+    nodes: string;
+    edges: string;
+    source: string;
+    target: string;
+    initial: string;
+    final: string;
+};
+export type SchemaDiagramCenter = {
+    source?: string;
+    property?: string;
+    label?: string;
+    kind?: string;
+};
+export type SchemaDiagramCenterEdges = {
+    property: string;
+    inbound?: string;
+    outbound?: string;
+    both?: string;
+    labeled?: string;
+};
 export type SchemaDiagram = {
     type?: "graph" | "hub" | "grid";
     nodes?: string;
     edges?: string;
-    center?: string;
+    center?: string | SchemaDiagramCenter;
+    centerEdges?: SchemaDiagramCenterEdges;
     links?: "props" | "all";
+    labeled?: boolean;
     edgeSource?: string;
     edgeTarget?: string;
     edgeArity?: string;
     hierarchy?: boolean;
+    deep?: boolean;
     onlyConnected?: boolean;
     collapse?: boolean;
     qualified?: boolean;
@@ -39,5 +66,10 @@ export type SchemaProperty = {
     desc?: string;
     value?: string;
     optional?: boolean;
+    unique?: boolean | string;
+    present?: boolean | string;
+    local?: boolean;
+    symmetric?: boolean;
+    acyclic?: boolean;
 };
 export declare const Schema: v.GenericSchema<Schema>;

package/dst/specbook-format-schema.js

@@ -20,18 +20,47 @@ const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),
     value: v.optional(v.string()),
-    optional: v.optional(v.boolean())
+    optional: v.optional(v.boolean()),
+    unique: v.optional(v.union([v.boolean(), v.string()])),
+    present: v.optional(v.union([v.boolean(), v.string()])),
+    local: v.optional(v.boolean()),
+    symmetric: v.optional(v.boolean()),
+    acyclic: v.optional(v.boolean())
+});
+const SchemaAutomaton = v.strictObject({
+    nodes: v.string(),
+    edges: v.string(),
+    source: v.string(),
+    target: v.string(),
+    initial: v.string(),
+    final: v.string()
+});
+const SchemaDiagramCenter = v.strictObject({
+    source: v.optional(v.string()),
+    property: v.optional(v.string()),
+    label: v.optional(v.string()),
+    kind: v.optional(v.string())
+});
+const SchemaDiagramCenterEdges = v.strictObject({
+    property: v.string(),
+    inbound: v.optional(v.string()),
+    outbound: v.optional(v.string()),
+    both: v.optional(v.string()),
+    labeled: v.optional(v.string())
 });
 const SchemaDiagram = v.strictObject({
     type: v.optional(v.picklist(["graph", "hub", "grid"])),
     nodes: v.optional(v.string()),
     edges: v.optional(v.string()),
-    center: v.optional(v.string()),
+    center: v.optional(v.union([v.string(), SchemaDiagramCenter])),
+    centerEdges: v.optional(SchemaDiagramCenterEdges),
     links: v.optional(v.picklist(["props", "all"])),
+    labeled: v.optional(v.boolean()),
     edgeSource: v.optional(v.string()),
     edgeTarget: v.optional(v.string()),
     edgeArity: v.optional(v.string()),
     hierarchy: v.optional(v.boolean()),
+    deep: v.optional(v.boolean()),
     onlyConnected: v.optional(v.boolean()),
     collapse: v.optional(v.boolean()),
     qualified: v.optional(v.boolean()),
@@ -49,7 +78,10 @@ const SchemaObject = v.strictObject({
     id: v.optional(v.string()),
     file: v.optional(v.string()),
     desc: v.optional(v.string()),
+    refs: v.optional(v.string()),
     optional: v.optional(v.boolean()),
+    referenced: v.optional(v.pipe(v.array(v.string()), v.minLength(1))),
+    automaton: v.optional(SchemaAutomaton),
     diagram: v.optional(SchemaDiagram),
     format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),

package/dst/specbook-format.md

@@ -59,7 +59,9 @@ level, the object kinds of the deeper levels, and their properties
 with optional value constraints: regular expressions `/xxx/` (implicitly
 anchored, so they have to match the value as a whole),
 object references `[[xxx]]`, enumerations `enum(xxx,yyy)`, tag sets
-`tags(xxx,yyy)`, and lists `list(xxx[, ...])` of such alternatives.
+`tags(xxx,yyy)`, and lists `list(xxx[, ...])` of such alternatives,
+whose comma-separated items are split at top-level commas only, i.e.
+outside double quotes, `[[xxx]]` references, and parentheses.
 
 ```ts
 type Schema = SchemaObject[]
@@ -69,22 +71,49 @@ type SchemaObject = {
     id?:               string
     file?:             string
     desc?:             string
+    refs?:             string
     optional?:         boolean
+    referenced?:       string[]
+    automaton?:        SchemaAutomaton
     diagram?:          SchemaDiagram
     format?:           SchemaFormat
     props?:            SchemaProperty[]
     childs?:           SchemaObject[]
 }
+type SchemaAutomaton = {
+    nodes:             string
+    edges:             string
+    source:            string
+    target:            string
+    initial:           string
+    final:             string
+}
+type SchemaDiagramCenter = {
+    source?:           string
+    property?:         string
+    label?:            string
+    kind?:             string
+}
+type SchemaDiagramCenterEdges = {
+    property:          string
+    inbound?:          string
+    outbound?:         string
+    both?:             string
+    labeled?:          string
+}
 type SchemaDiagram = {
     type?:             "graph" | "hub" | "grid"
     nodes?:            string
     edges?:            string
-    center?:           string
+    center?:           string | SchemaDiagramCenter
+    centerEdges?:      SchemaDiagramCenterEdges
     links?:            "props" | "all"
+    labeled?:          boolean
     edgeSource?:       string
     edgeTarget?:       string
     edgeArity?:        string
     hierarchy?:        boolean
+    deep?:             boolean
     onlyConnected?:    boolean
     collapse?:         boolean
     qualified?:        boolean
@@ -101,6 +130,11 @@ type SchemaProperty = {
     desc?:             string
     value?:            string
     optional?:         boolean
+    unique?:           boolean | string
+    present?:          boolean | string
+    local?:            boolean
+    symmetric?:        boolean
+    acyclic?:          boolean
 }
 type SchemaGradiaConfig = Partial<{
     "font-family":               string
@@ -160,7 +194,7 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE artifacts and their content follow one recursive structure
 
 -   `SchemaObject.kind: string`:
-    kind name of the object (e.g. `SPEC`, `REQUIREMENT`), unique among
+    kind name of the object (e.g. `REQS`, `REQUIREMENT`), unique among
     its siblings, on level 1 together with its `id`,
     BECAUSE it discriminates objects and anchors `[[xxx]]` references
 
@@ -181,17 +215,35 @@ type SchemaGradiaConfig = Partial<{
     prose description of the object kind,
     BECAUSE it guides the authors and instructs the AI
 
+-   `SchemaObject.refs?: string`:
+    Markdown list of the standards, books, articles, or websites
+    (`-   <id>: <title> (<year>),` followed by an indented `<url>` line)
+    primarily describing the methodology the object kind picks up (left
+    out when the configuration is emitted compressed by level 2 or higher),
+    BECAUSE the authors and the AI can consult the original method
+
 -   `SchemaObject.optional?: boolean`:
     whether the kind may be absent below its parent or, for a level 1
     artifact, from its file (default: `false`),
     BECAUSE not every kind is mandatory below every parent object
 
+-   `SchemaObject.referenced?: string[]`:
+    wildcard references (e.g. `[[*]]` for any object, `[[UC.USE-CASE:*]]`
+    for the use cases) matching the objects -- themselves or through their
+    descendants -- from which every object of this kind has to be referenced
+    at least once, where a lapse is reported as a warning only,
+    BECAUSE a term nobody uses or a requirement no use case exercises is dead weight
+
+-   `SchemaObject.automaton?: SchemaAutomaton`:
+    finite state machine the child objects of every object of this kind form,
+    BECAUSE a lifecycle is only trustworthy when its dead-ends and livelocks are ruled out
+
 -   `SchemaObject.diagram?: SchemaDiagram`:
     diagram generated for every object of this kind,
     BECAUSE relations buried in references are graspable only when drawn
 
 -   `SchemaObject.format?: SchemaFormat`:
-    HTML/PDF rendering format of the child objects of this kind,
+    HTML/PDF rendering format of the objects of this kind,
     BECAUSE rich objects need sections, uniform ones read as tables
 
 -   `SchemaObject.props?: SchemaProperty[]`:
@@ -202,6 +254,37 @@ type SchemaGradiaConfig = Partial<{
     object kinds allowed one level below this object (RECURSION),
     BECAUSE the nesting defines and bounds the document structure
 
+-   `SchemaAutomaton`:
+    finite state machine formed by the child objects of an object: the
+    nodes have to be reachable from an initial node, a node without
+    outgoing edge has to be final (else it is a dead-end), and a final
+    node has to be reachable from every node (else it is a livelock),
+    BECAUSE the structural sanity of a state machine is checkable, not just describable
+
+-   `SchemaAutomaton.nodes: string`:
+    child object kind whose objects are the nodes (e.g. `STATE`),
+    BECAUSE the states are objects of their own, carrying descriptions and flags
+
+-   `SchemaAutomaton.edges: string`:
+    child object kind whose objects are the edges (e.g. `TRANSITION`),
+    BECAUSE the transitions are objects of their own, carrying guards and effects
+
+-   `SchemaAutomaton.source: string`:
+    reference-valued property of an edge object referencing its source node,
+    BECAUSE an edge is directed
+
+-   `SchemaAutomaton.target: string`:
+    reference-valued property of an edge object referencing its target node,
+    BECAUSE an edge is directed
+
+-   `SchemaAutomaton.initial: string`:
+    property of a node object flagging (with the value `true`) an initial node,
+    BECAUSE reachability needs a start (the check is skipped without any initial node)
+
+-   `SchemaAutomaton.final: string`:
+    property of a node object flagging (with the value `true`) a final node,
+    BECAUSE resting is legal in a final node only (the livelock check is skipped without any final node)
+
 -   `SchemaDiagram`:
     diagram derived for every object of an object kind,
     BECAUSE the relations of a specification are graspable only when drawn
@@ -218,14 +301,33 @@ type SchemaGradiaConfig = Partial<{
     comma-separated `[[xxx]]` patterns of the objects acting as edges, not nodes,
     BECAUSE some relations are objects, yet still connect two nodes
 
--   `SchemaDiagram.center?: string`:
-    object a `hub` diagram is projected onto (default: `self`),
-    BECAUSE a hub needs one focus, not always the owning object
+-   `SchemaDiagram.center?: string | SchemaDiagramCenter`:
+    object a `hub` diagram is projected onto (default: `self`), or a
+    synthetic center node, labeled from a referenced `source` object (or
+    one of its properties, via `property`) or a literal `label`, typed
+    (under `qualified`) by `kind`, and linked to the `source` object,
+    BECAUSE the focus of a hub is not always a specification object --
+    the solution itself, e.g., sits in the middle of a context diagram
+    without being modeled anywhere
+
+-   `SchemaDiagram.centerEdges?: SchemaDiagramCenterEdges`:
+    synthesized center edges of a `hub`: the `property` of the node
+    objects whose `inbound` value maps onto a node-to-center edge, whose
+    `outbound` value onto a center-to-node edge, and whose `both` value
+    onto both edges (the second placement rendered as a "ghost" node),
+    each optionally named by the value of the `labeled` property,
+    BECAUSE the nodes carry no `[[xxx]]` reference to a synthetic center,
+    so their relation to it lives in a direction property instead
 
 -   `SchemaDiagram.links?: "props" | "all"`:
     edge source: property values (`props`) or also texts (`all`),
     BECAUSE prose references are incidental and need an opt-in
 
+-   `SchemaDiagram.labeled?: boolean`:
+    whether the edges derived from property values carry the lower-cased
+    property key as their label (default: `false`),
+    BECAUSE edges of several reference properties need telling apart
+
 -   `SchemaDiagram.edgeSource?: string`:
     edge property naming the source node (default: the parent object),
     BECAUSE an edge object is not always nested below its own source
@@ -243,6 +345,11 @@ type SchemaGradiaConfig = Partial<{
     whether containment edges derive from the nesting (default: `false`),
     BECAUSE the nesting carries no reference and would stay invisible
 
+-   `SchemaDiagram.deep?: boolean`:
+    whether the references of the descendants of a node count as its own,
+    lifted to their nearest node and counted as the arity (default: `false`),
+    BECAUSE the relations between coarse objects live in their fine parts
+
 -   `SchemaDiagram.onlyConnected?: boolean`:
     whether a `graph` drops its edge-less nodes (default: `false`),
     BECAUSE isolated nodes dilute a diagram about relationships
@@ -264,7 +371,7 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE layout tuning is cosmetics, not a schema concern
 
 -   `SchemaFormat`:
-    HTML/PDF rendering of the child objects of an object kind,
+    HTML/PDF rendering of the objects of an object kind among their siblings,
     BECAUSE one uniform rendering fits neither rich nor numerous objects
 
 -   `SchemaFormat.type?: "auto" | "complex" | "concise"`:
@@ -272,7 +379,7 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE sections bury small objects, tables truncate rich ones
 
 -   `SchemaFormat.maxTableColumns?: number`:
-    maximum column count of the tables below (default: `4`),
+    maximum column count of the table of the kind (default: `4`),
     BECAUSE the fixed print/PDF page width bounds the table width
 
 -   `SchemaFormat.withUnusedProps?: boolean`:
@@ -299,6 +406,33 @@ type SchemaGradiaConfig = Partial<{
     whether the property may be missing (default: `false`),
     BECAUSE not every property applies to every object
 
+-   `SchemaProperty.unique?: boolean | string`:
+    whether every value (`true`) or only the values matching a regexp or
+    enum expression occur at most once among the sibling objects of the kind,
+    BECAUSE some markers, like a `Main` flow, designate a single sibling
+
+-   `SchemaProperty.present?: boolean | string`:
+    whether some value (`true`) or a value matching a regexp or enum
+    expression has to occur on at least one of the (existing) sibling
+    objects of the kind, so that `unique` plus `present` demand exactly one,
+    BECAUSE some markers, like an initial state, are not just single but indispensable
+
+-   `SchemaProperty.local?: boolean`:
+    whether the reference-valued property has to reference objects below
+    the parent object of the referencing object only (default: `false`),
+    BECAUSE a transition between the states of two different lifecycles is nonsense
+
+-   `SchemaProperty.symmetric?: boolean`:
+    whether every object the reference-valued property references has to
+    reference the referencing object back through the same property
+    (default: `false`),
+    BECAUSE an undirected relation authored on one side only is half a lie
+
+-   `SchemaProperty.acyclic?: boolean`:
+    whether following the reference-valued property from object to object
+    must never return to an object already passed (default: `false`),
+    BECAUSE a hierarchy with a loop has no root and an inclusion with a loop never ends
+
 -   `SchemaGradiaConfig`:
     the Gradia rendering options, mirrored from `@rse/gradia`,
     BECAUSE the diagram cosmetics remain Gradia's concern, not SpecBook's
@@ -335,7 +469,15 @@ type SchemaGradiaConfig = Partial<{
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
-descriptions as well.
+descriptions as well. With `deep: true` the references of all
+descendants of a node object count as its own, every referenced object
+is lifted to its nearest ancestor-or-self within the node set, and the
+number of references behind an edge becomes its arity, so a diagram of
+coarse objects (like the artifacts of a whole specification) shows the
+relations living in their fine-grained parts. With `labeled: true` an
+edge derived from a property value carries the lower-cased property key
+as its label, telling the edges of different properties apart, while
+the edges derived from descriptions stay unlabeled.
 
 An object acting as an edge (`edges`) connects its parent object to the
 object its target property references. Where an edge object is a sibling
@@ -360,6 +502,18 @@ comma-separated `[[xxx]]` reference patterns (`nodes` defaults to the
 object itself plus all objects below it), and `center` names the object
 a `hub` is projected onto (default: `self`).
 
+Instead of naming an existing object, `center` can also declare a
+*synthetic* center node, which represents something no specification
+object models -- like the solution itself in the middle of a context
+diagram. Such a center is labeled from a referenced `source` object (or
+one of its properties, via `property`) or a literal `label`, and links
+to the `source` object. As the nodes carry no `[[xxx]]` reference to a
+synthetic center, `centerEdges` synthesizes the edges from a direction
+`property` of the node objects: its `inbound` value maps onto a
+node-to-center edge, its `outbound` value onto a center-to-node edge,
+and its `both` value onto both edges, each optionally named by the value
+of the `labeled` property.
+
 `onlyConnected` drops the edge-less nodes of a `graph`, `collapse`
 (default: `true`) omits a degenerated diagram consisting of a single
 node only, `qualified` labels every node with its object kind,
@@ -371,19 +525,26 @@ rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
 ### Format
 
 An object kind can furthermore carry a `format` field, which controls
-how the HTML/PDF export renders the child objects of every object of
-that kind. Its `type` selects the rendering: `complex` (nested
-sections), `concise` (compact per-kind tables), or the default `auto`,
-which collapses only the deepest level into tables.
-
-Below a `concise` object, unconfigured children implicitly stay
+how the HTML/PDF export renders the objects of that kind among their
+siblings, so that the sibling kinds below one parent can render
+differently (e.g. one kind as a table, another as sections). Its `type`
+selects the rendering: `complex` (nested sections), `concise` (one
+compact table of all sibling objects of the kind), or the default
+`auto`, which collapses only the deepest level into tables.
+
+Inside a `concise` table, unconfigured child kinds implicitly stay
 `concise` and render as sub-tables inside the description cells, while
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
-the columns of the compact tables below the object (wider groups chunk
-their properties into embedded per-object tables), and `withUnusedProps`
+the columns of the compact table of the kind (a wider group chunks
+its properties into embedded per-object tables), and `withUnusedProps`
 (default: `false`) unconditionally renders the defined but unused
-properties of that kind, as empty property table lines or table columns.
+properties of that kind, as property table lines or table columns. In
+the HTML/PDF export, a property absent from an object shows an "empty
+set" marker in place of its value, which tells it apart from a property
+given with an empty value.
+Property lines and table columns follow the property order of the
+schema, with properties unknown to the schema appended in document order.
 Objects collapsed into tables carry no headings and hence leave the
 table of contents and the PDF outline.
 
@@ -531,9 +692,12 @@ SpecBook SCHEMA Model
 ### Artifacts
 
 A schema consists of a YAML file, which is exactly a serialization of
-the object model defined by the **SpecBook SCHEMA Meta Model**. If no
-particular schema is given, the standard schema configuration bundled
-with **SpecBook** applies.
+the object model defined by the **SpecBook SCHEMA Meta Model**, or of
+several such files, merged in order into one schema (the later files
+into the earlier ones, where the objects merge deeply and the elements
+of the lists are matched by their identity). If no particular schema is
+given, the standard schema configuration bundled with **SpecBook**
+applies.
 
 SpecBook SPEC Model
 -------------------
@@ -671,7 +835,7 @@ order:
     (e.g. `## ENTITY: Attendee Browser {{attendee}}`).
 
 -   `(<token/>)`: a parenthesized token with three possible roles: on
-    level 1 it becomes the artifact id (e.g. `# SPEC: Data Model (DM)`);
+    level 1 it becomes the artifact id (e.g. `# DATA: Data Model (DM)`);
     on deeper levels it acts as the implicit anchor id.
 
 -   `(*)`: the *primary* marker, flagging the object as primary (e.g.
@@ -701,7 +865,7 @@ whole.
 
 The description of a Complex Format object is all block content below
 its heading (up to the next heading) except the property list:
-paragraphs, blockquotes, ordered lists (e.g. scenario steps), and
+paragraphs, blockquotes, ordered lists (e.g. scenario steps or test case procedures), and
 fenced code blocks. A fenced code block
 of language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
@@ -741,7 +905,11 @@ below the artifact with id `FV`).
 A reference has to resolve to exactly one object: a single-segment
 reference tries the variants (1) id/anchor, (2) name, and (3)
 `<kind/>:<name-or-id/>` in order, where the first variant yielding any
-matches decides; several matches are an ambiguity and zero matches an
+matches decides; several matches are narrowed down to the ones nearest
+to the referencing object, i.e. sharing the longest ancestor chain with
+it (so `[[STATE:Draft]]` inside a lifecycle picks the `Draft` state of
+this very lifecycle, even if other lifecycles carry a `Draft` state,
+too); still several matches are an ambiguity and zero matches an
 unresolvable reference, both reported by the linter. Wildcard references
 resolve into match *sets* and are used in the schema configuration to
 constrain reference-valued properties (e.g. `[[PERSONA:*]]` or