@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-export-md.js

@@ -10,10 +10,14 @@ const formatTimestamp = (date) => {
     return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
         `${pad(date.getHours())}:${pad(date.getMinutes())}`;
 };
-/*  render the properties as a value-aligned key/value list  */
-const renderKeyValuesMd = (properties) => {
+/*  render the properties as a value-aligned key/value list, wrapping a
+    value carrying ";" onto a continuation line, as only a ";"-free first
+    line lets the item be recognized as a property again on re-parsing  */
+const renderKeyValuesMd = (properties, indent = "") => {
     const width = Math.max(...properties.map((property) => property.key.length)) + 1;
-    return properties.map((property) => `-   ${`${property.key}:`.padEnd(width)} ${property.value}`).join("\n");
+    return properties.map((property) => property.value.includes(";") ?
+        `${indent}-   ${property.key}:\n${indent}    ${property.value}` :
+        `${indent}-   ${`${property.key}:`.padEnd(width)} ${property.value}`.trimEnd()).join("\n");
 };
 /*  render a description statement with its optional rationale  */
 const renderDescriptionMd = (description) => description.description + (description.rationale !== undefined ?
@@ -23,28 +27,42 @@ const renderDescriptionMd = (description) => description.description + (descript
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     (object.paren !== undefined ? ` (${object.paren})` : "") +
     (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
-/*  render an object in the Concise Format (level 4 and deeper),
-    with its childs as nested list items  */
-const renderConciseMd = (object, level) => {
-    const indent = " ".repeat((level - 4) * 4);
+/*  whether any descendant of an object carries a multi-line description
+    (a fenced code block, an ordered list, a blockquote, or multiple
+    paragraphs), which no Concise Format item can carry  */
+const multiLineBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
+    && renderDescriptionMd(child.description).includes("\n")) || multiLineBelowMd(child));
+/*  render an object in the Concise Format as a list item of the
+    given nesting depth, with its childs as nested list items  */
+const renderConciseMd = (object, depth = 0) => {
+    const indent = " ".repeat(depth * 4);
     const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
-    segments.push(...object.properties.map((property) => `${property.key}: ${property.value}`));
+    /*  a value carrying ";" cannot be a segment, so its property has to
+        become a nested key/value item below the item instead  */
+    const wrapped = object.properties.filter((property) => property.value.includes(";"));
+    const inline = object.properties.filter((property) => !property.value.includes(";"));
+    segments.push(...inline.map((property) => `${property.key}: ${property.value}`));
     if (object.description !== undefined)
         segments.push(renderDescriptionMd(object.description));
-    /*  a description terminates the item with ".", while without one the
-        ";" segment terminator has to remain, as only it lets the item be
-        recognized as a concise object again on re-parsing  */
+    /*  a description terminates the item with ".", which on re-parsing
+        marks the last segment as the description (even one shaped like
+        "<key>: <value>"), while without one the ";" segment terminator
+        has to remain, as only it lets the item be recognized as concise  */
     const item = object.description !== undefined ?
         `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
         `${indent}-   ${segments.join("; ")};`;
-    return [item, ...object.childs.map((child) => renderConciseMd(child, level + 1))].join("\n");
+    return [item, renderKeyValuesMd(wrapped, `${indent}    `),
+        ...object.childs.map((child) => renderConciseMd(child, depth + 1))]
+        .filter((part) => part !== "").join("\n");
 };
-/*  render an object in the Complex Format (levels 1-3),
-    with childs from level 4 upwards in the Concise Format
-    and the optionally derived Gradia diagram spec embedded
-    as a "gradia" fenced code block below the heading  */
+/*  render an object in the Complex Format (levels 1-3), with childs from
+    level 4 upwards in the Concise Format -- unless a descendant carries
+    a multi-line description, so all childs (as siblings have to share
+    the format) stay in the Complex Format down to heading level 6 --,
+    and the optionally derived Gradia diagram spec embedded as a
+    "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
-    const heading = `${"#".repeat(level)}${" ".repeat(4 - level)}` +
+    const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +
         `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
     const parts = [heading];
     const spec = diagrams?.get(object);
@@ -54,14 +72,16 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(renderKeyValuesMd(object.properties));
     if (object.description !== undefined)
         parts.push(renderDescriptionMd(object.description));
-    if (level >= 3)
-        parts.push(object.childs.map((child) => renderConciseMd(child, level + 1)).join("\n"));
+    /*  the childs share one format, as a concise item following
+        a heading would attach to the heading's object instead  */
+    if (level >= 3 && !multiLineBelowMd(object))
+        parts.push(object.childs.map((child) => renderConciseMd(child)).join("\n"));
     else
         parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));
     return parts.filter((part) => part !== "").join("\n\n");
 };
 /*  render the entire specification into normalized Markdown  */
-export const renderMarkdown = async (specification, config) => {
+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)  */
@@ -70,9 +90,15 @@ export const renderMarkdown = async (specification, config) => {
         for (const [object, result] of specDiagrams(specification, config))
             if (result.spec !== undefined)
                 diagrams.set(object, result.spec);
-    return specification.artifacts.map((artifact) => "---\n" +
-        `Created:  ${formatTimestamp(artifact.created)}\n` +
-        `Modified: ${formatTimestamp(artifact.modified)}\n` +
+    /*  the single frontmatter block (only recognized at the start of a
+        file on re-parse) carries the earliest creation and the latest
+        modification timestamp of all artifacts  */
+    const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
+    const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
+    return "---\n" +
+        `Created:  ${formatTimestamp(created)}\n` +
+        `Modified: ${formatTimestamp(modified)}\n` +
         "---\n\n" +
-        artifact.objects.map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
+        specification.artifacts.flatMap((artifact) => artifact.objects)
+            .map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n") + "\n";
 };

package/dst/specbook-export-pdf.d.ts

@@ -1,7 +1,9 @@
 import type { OutlineEntry } from "./specbook-export-html.js";
 import type { ThemeMapping } from "./specbook-theme.js";
-export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: {
+type Heading = {
     title: string;
     subtitle?: string;
     logo: string;
-}, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+};
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+export {};

package/dst/specbook-export-pdf.js

@@ -78,6 +78,49 @@ const addOutline = async (doc, entries) => {
     doc.catalog.set(PDFName.of("Outlines"), root);
     doc.catalog.set(PDFName.of("PageMode"), PDFName.of("UseOutlines"));
 };
+/*  render the header/footer templates for the page decoration: they
+    render in an isolated context, so they need their own inline styling,
+    the regular font face embedded as a data: URI, and the special
+    "pageNumber" class for the injected page number  */
+const decorationTemplates = (heading, css, theme, left, right) => {
+    const fontFace = css.match(/@font-face\s*\{[^}]*\}/)?.[0] ?? "";
+    const subtitle = heading.subtitle?.trim();
+    const headText = escapeHtml(heading.title) +
+        (subtitle !== undefined && subtitle !== "" ? ` — ${escapeHtml(subtitle)}` : "");
+    return {
+        headerTemplate: `<style>${fontFace}</style>` +
+            "<div style=\"width: 100%; margin-top: 0.8cm;\">" +
+            `<div style="margin: 0 ${right} 0 ${left}; ` +
+            "font-family: 'Source Sans 3', sans-serif; " +
+            `font-size: 8pt; color: ${theme.symbol}; border-bottom: 1px solid ${theme.border}; ` +
+            "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
+            "align-items: flex-end;\">" +
+            `<span>${headText}</span>` +
+            `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
+            "</div></div>",
+        footerTemplate: `<style>${fontFace}</style>` +
+            "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
+            `<div style="margin: 0 ${right} 0 ${left}; ` +
+            "font-family: 'Source Sans 3', sans-serif; " +
+            `font-size: 8pt; color: ${theme.symbol}; display: flex; ` +
+            `justify-content: space-between; border-top: 1px solid ${theme.border}; ` +
+            "padding-top: 1mm;\">" +
+            `<span>${headText}</span>` +
+            `<span style="color: ${theme.muted}; font-weight: bold;" class="pageNumber"></span></div></div>`
+    };
+};
+/*  draw the vertical brand bar onto the left edge of the physical
+    paper of every page, as Chromium clips print content to the page
+    box (0.6rem at the 9pt print root)  */
+const drawBrandBar = async (doc, accent) => {
+    const { rgb } = await import("pdf-lib");
+    const hex = accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
+        .map((component) => parseInt(component, 16) / 255);
+    for (const page of doc.getPages())
+        page.drawRectangle({ x: 0, y: 0, width: 5.4,
+            height: page.getHeight(), color: rgb(r, g, b) });
+};
 /*  render a self-contained HTML document into a PDF via Playwright,
     re-rendering the HTML with the discovered ToC page numbers  */
 export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css, theme, paper = paperSizeDefault) => {
@@ -85,11 +128,6 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
     /*  the page geometry of the chosen paper size  */
     const setup = paperSetup(paper);
     const margin = setup.margin;
-    /*  the regular font face and the title/subtitle
-        text for the header/footer templates  */
-    const fontFace = css.match(/@font-face\s*\{[^}]*\}/)?.[0] ?? "";
-    const headText = escapeHtml(heading.title) +
-        (heading.subtitle !== undefined ? ` &mdash; ${escapeHtml(heading.subtitle)}` : "");
     /*  launch the Playwright Chromium browser, falling back to a
         system-installed Google Chrome if the Chromium download is missing  */
     let browser;
@@ -139,31 +177,10 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
             html = next;
             plain = await renderPdf(html);
         }
+        /*  render the final document, decorated with header/footer  */
         const decorated = await renderPdf(html, {
-            /*  the header/footer templates render in an isolated context,
-                so they need their own inline styling, the regular font face
-                embedded as a data: URI, and the special "title"/"pageNumber"
-                classes for the injected values  */
             displayHeaderFooter: true,
-            headerTemplate: `<style>${fontFace}</style>` +
-                "<div style=\"width: 100%; margin-top: 0.8cm;\">" +
-                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
-                "font-family: 'Source Sans 3', sans-serif; " +
-                `font-size: 8pt; color: ${theme.symbol}; border-bottom: 1px solid ${theme.border}; ` +
-                "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
-                "align-items: flex-end;\">" +
-                `<span>${headText}</span>` +
-                `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
-                "</div></div>",
-            footerTemplate: `<style>${fontFace}</style>` +
-                "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
-                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
-                "font-family: 'Source Sans 3', sans-serif; " +
-                `font-size: 8pt; color: ${theme.text}; display: flex; ` +
-                `justify-content: space-between; border-top: 1px solid ${theme.border}; ` +
-                "padding-top: 1mm;\">" +
-                `<span style="color: ${theme.symbol}">${headText}</span>` +
-                `<span style="color: ${theme.muted}; font-weight: bold;" class="pageNumber"></span></div></div>`
+            ...decorationTemplates(heading, css, theme, paperLength(setup, margin.left), paperLength(setup, margin.right))
         });
         /*  a title page carries no header/footer: as Chromium decorates
             all pages unconditionally, swap the first page of the
@@ -171,7 +188,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
             the ToC page number iteration) into the decorated document
             *in place*, which keeps the decorated document's link
             destinations (and hence the internal hyperlinks) intact  */
-        const { PDFDocument, rgb } = await import("pdf-lib");
+        const { PDFDocument } = await import("pdf-lib");
         const merged = await PDFDocument.load(decorated);
         if (html.includes("class=\"titlepage\"")) {
             const source = await PDFDocument.load(plain);
@@ -182,15 +199,8 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
         /*  attach the document outline for the viewer side-bar  */
         verbose("attaching PDF outline (bookmarks)");
         await addOutline(merged, outline);
-        /*  draw the vertical brand bar onto the left edge of the
-            physical paper of every page, as Chromium clips print
-            content to the page box (0.6rem at the 9pt print root)  */
-        const hex = theme.accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
-        const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
-            .map((component) => parseInt(component, 16) / 255);
-        for (const pdfPage of merged.getPages())
-            pdfPage.drawRectangle({ x: 0, y: 0, width: 5.4,
-                height: pdfPage.getHeight(), color: rgb(r, g, b) });
+        /*  decorate every page with the vertical brand bar  */
+        await drawBrandBar(merged, theme.accent);
         return Buffer.from(await merged.save());
     }
     finally {

package/dst/{specbook-struct-schema.d.ts → specbook-format-schema.d.ts}

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { type Config as GradiaConfig } from "@rse/gradia";
-export type SchemaSpecification = SchemaObject[];
+export type Schema = SchemaObject[];
 export type SchemaObject = {
     kind: string;
     name?: string;
@@ -19,6 +19,7 @@ export type SchemaDiagram = {
     edges?: string;
     center?: string;
     links?: "props" | "all";
+    edgeSource?: string;
     edgeTarget?: string;
     edgeArity?: string;
     hierarchy?: boolean;
@@ -39,4 +40,4 @@ export type SchemaProperty = {
     value?: string;
     optional?: boolean;
 };
-export declare const SchemaSpecification: v.GenericSchema<SchemaSpecification>;
+export declare const Schema: v.GenericSchema<Schema>;

package/dst/{specbook-struct-schema.js → specbook-format-schema.js}

@@ -8,9 +8,12 @@ import { Gradia } from "@rse/gradia";
 /*  ==== Schema ====  */
 /*  the Gradia rendering options, derived from the configuration
     defaults of Gradia: the option names constrain the allowed keys and
-    the types of the default values constrain the allowed value types  */
+    the types of the default values constrain the allowed value types
+    (with the numbers restricted to the finite, non-negative values
+    Gradia honors, as it silently drops all others)  */
 const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map(([key, value]) => [key,
-    typeof value === "boolean" ? v.boolean() : typeof value === "number" ? v.number() : v.string()]));
+    typeof value === "boolean" ? v.boolean() :
+        typeof value === "number" ? v.pipe(v.number(), v.finite(), v.minValue(0)) : v.string()]));
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
 const SchemaProperty = v.strictObject({
@@ -25,6 +28,7 @@ const SchemaDiagram = v.strictObject({
     edges: v.optional(v.string()),
     center: v.optional(v.string()),
     links: v.optional(v.picklist(["props", "all"])),
+    edgeSource: v.optional(v.string()),
     edgeTarget: v.optional(v.string()),
     edgeArity: v.optional(v.string()),
     hierarchy: v.optional(v.boolean()),
@@ -36,7 +40,7 @@ const SchemaDiagram = v.strictObject({
 });
 const SchemaFormat = v.strictObject({
     type: v.optional(v.picklist(["auto", "complex", "concise"])),
-    maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+    maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(2))),
     withUnusedProps: v.optional(v.boolean())
 });
 const SchemaObject = v.strictObject({
@@ -51,4 +55,4 @@ const SchemaObject = v.strictObject({
     props: v.optional(v.array(SchemaProperty)),
     childs: v.optional(v.array(v.lazy(() => SchemaObject)))
 });
-export const SchemaSpecification = v.pipe(v.array(SchemaObject), v.minLength(1));
+export const Schema = v.pipe(v.array(SchemaObject), v.minLength(1));

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

@@ -0,0 +1,31 @@
+import * as v from "valibot";
+export type Spec = {
+    artifacts: SpecArtifact[];
+};
+export type SpecArtifact = {
+    created: Date;
+    modified: Date;
+    objects: SpecObject[];
+};
+export type SpecObject = {
+    kind: string;
+    id: string;
+    anchor?: string;
+    paren?: string;
+    name: string;
+    primary?: boolean;
+    description?: SpecDescription;
+    properties: SpecProperty[];
+    childs: SpecObject[];
+};
+export type SpecDescription = {
+    description: string;
+    rationale?: string;
+    embedding?: string[];
+};
+export type SpecProperty = {
+    key: string;
+    value: string;
+    embedding?: string[];
+};
+export declare const Spec: v.GenericSchema<Spec>;

package/dst/{specbook-struct-spec.js → specbook-format-spec.js}

@@ -5,32 +5,32 @@
 */
 import * as v from "valibot";
 /*  ==== Schema ====  */
-const Property = v.object({
+const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),
     embedding: v.optional(v.array(v.string()))
 });
-const Description = v.object({
+const SpecDescription = v.object({
     description: v.string(),
     rationale: v.optional(v.string()),
     embedding: v.optional(v.array(v.string()))
 });
-const Object = v.object({
+const SpecObject = v.object({
     kind: v.string(),
     id: v.string(),
     anchor: v.optional(v.string()),
     paren: v.optional(v.string()),
     name: v.string(),
     primary: v.optional(v.boolean()),
-    description: v.optional(Description),
-    properties: v.array(Property),
-    childs: v.array(v.lazy(() => Object))
+    description: v.optional(SpecDescription),
+    properties: v.array(SpecProperty),
+    childs: v.array(v.lazy(() => SpecObject))
 });
-const Artifact = v.object({
+const SpecArtifact = v.object({
     created: v.date(),
     modified: v.date(),
-    objects: v.pipe(v.array(Object), v.minLength(1))
+    objects: v.pipe(v.array(SpecObject), v.minLength(1))
 });
-export const Specification = v.object({
-    artifacts: v.pipe(v.array(Artifact), v.minLength(1))
+export const Spec = v.object({
+    artifacts: v.pipe(v.array(SpecArtifact), v.minLength(1))
 });