@rse/specbook 1.2.2 → 1.2.3

package/README.md

@@ -70,7 +70,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 -   **HTML Export for Developers**:
     The HTML export is a self-contained single document with a
     table-of-contents (also as a slide-in side panel for quick navigation),
-    full-text search, embedded images, and a light/dark
+    full-text search, embedded images, a scroll progress meter (which
+    also scrolls back to the top on click), and a light/dark
     theme toggle. It is intended for the day-to-day online reading during
     development. The HTML export can map all object kinds to nested
     sections or compact tables, or an automatic mixture which collapses

package/dst/specbook-api.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { glob } from "glob";
-import { loadConfig } from "./specbook-config.js";
+import { loadConfig, configStatistics } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
@@ -69,6 +69,9 @@ export class SpecBook {
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
+        const stats = configStatistics(config);
+        verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
     /*  initialize the configured specification artifact files
@@ -112,8 +115,9 @@ export class SpecBook {
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        return this.renderFormats(lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", verbose }), requested, verbose, options.realtime === true);
+        const result = lint({ config: await this.configFiles(options.config),
+            basedir: options.basedir ?? ".", verbose });
+        return this.renderFormats(result, requested, verbose, options.realtime === true);
     }
     /*  keep an export in sync with its sources (the shared core of
         "watch" and "preview"): every change of a configuration file, of an

package/dst/specbook-cmd-describe.js

@@ -78,13 +78,13 @@ const schemaSection = (config, schema, embed, standard, compress) => {
     yaml = compressYaml(yaml, compress);
     return textframe(`
         The **SpecBook SCHEMA Model** is the following YAML schema configuration:
-    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
+    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n";
 };
 /*  render the reference to the specification Markdown files  */
 const specSection = (basedir) => textframe(`
         The **SpecBook SPEC Model** is the set of Markdown specification files in directory:
         @${basedir}
-    `) + "\n";
+    `);
 /*  describe the generic SpecBook models and formats as Markdown,
     optionally extended by the references to (or the embeddings of) the
     artifacts of the particular project instantiation, and optionally

package/dst/specbook-cmd-lint.js

@@ -5,9 +5,9 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { loadConfig } from "./specbook-config.js";
+import { loadConfig, configStatistics } from "./specbook-config.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification, resolveArtifact } from "./specbook-parse.js";
+import { parseSpecification, specStatistics, resolveArtifact } from "./specbook-parse.js";
 /*  collect the distinct artifact files the schema configuration
     references, in their declaration order, each mapped onto whether
     all of its artifacts are optional and hence the file may be absent  */
@@ -30,6 +30,11 @@ export const lint = (options) => {
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
     const config = loaded.config;
+    if (config !== undefined) {
+        const stats = configStatistics(config);
+        options.verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
+    }
     /*  read the artifact files the configuration references, resolved
         against the base directory and tolerating an absent file if all
         its artifacts are optional  */
@@ -64,6 +69,9 @@ export const lint = (options) => {
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
     watched.push(...result.assets);
+    const stats = specStatistics(result.specification);
+    options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
+        `and ${literal(stats.links)} link relationship(s)`);
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file
         is already reported above) or else against the configuration  */

package/dst/specbook-cmd-preview.js

@@ -10,11 +10,6 @@ import { literal } from "./specbook-verbose.js";
 /*  the default listening address and port of the preview server  */
 export const previewAddr = "127.0.0.1";
 export const previewPort = 12345;
-/*  the placeholder page answering a GET before the first successful
-    export: it still carries the live preview client, so the browser
-    subscribes to the "RELOAD" command right away and replaces itself
-    with the document once the first export arrives  */
-const placeholder = renderPlaceholder("no specification export available yet");
 /*  serve the live HTML preview: a plain GET on "/" answers with the
     most recent HTML export (or with the 503 placeholder page before the
     first successful one), while a WebSocket upgrade on "/" subscribes
@@ -24,16 +19,18 @@ export const servePreview = async (options) => {
     const clients = new Set();
     const fastify = Fastify();
     await fastify.register(fastifyWebsocket);
+    /*  the placeholder page answering a GET before the first successful
+        export: it still carries the live preview client, so the browser
+        subscribes to the "RELOAD" command right away and replaces itself
+        with the document once the first export arrives  */
+    const placeholder = renderPlaceholder("no specification export available yet");
     /*  answer a plain GET with the document and subscribe a WebSocket upgrade  */
     fastify.route({
         method: "GET",
         url: "/",
         handler: (_request, reply) => {
-            if (html === undefined)
-                return reply.code(503).type("text/html; charset=utf-8")
-                    .header("cache-control", "no-store").send(placeholder);
-            return reply.type("text/html; charset=utf-8")
-                .header("cache-control", "no-store").send(html);
+            reply.type("text/html; charset=utf-8").header("cache-control", "no-store");
+            return html === undefined ? reply.code(503).send(placeholder) : reply.send(html);
         },
         wsHandler: (socket, request) => {
             /*  identify the client by its remote address and port  */

package/dst/specbook-config.d.ts

@@ -1,5 +1,9 @@
 import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
+export declare const configStatistics: (config: Schema) => {
+    objects: number;
+    links: number;
+};
 export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];

package/dst/specbook-config.js

@@ -48,14 +48,15 @@ const mergeConfig = (target, source, list) => {
     if (source === null || source === undefined)
         return target;
     else if (Array.isArray(target) && Array.isArray(source)) {
+        const items = target;
         for (const item of source) {
-            const i = target.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
+            const i = items.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
             if (i < 0)
-                target.push(item);
+                items.push(item);
             else
-                target[i] = mergeConfig(target[i], item, list);
+                items[i] = mergeConfig(items[i], item, list);
         }
-        return target;
+        return items;
     }
     else if (isPlainObject(target) && isPlainObject(source))
         return mergeWith(target, source, (t, s, key) => Array.isArray(t) && Array.isArray(s) ? mergeConfig(t, s, key) : undefined);
@@ -90,7 +91,10 @@ const posOfMergedPath = (docs, merged, path) => {
         for (const segment of path) {
             const key = typeof segment === "number" && Array.isArray(own) ?
                 own.findIndex((item) => identityOf(item, list) === identityOf(at(node, segment), list)) : segment;
-            if (typeof key === "number" ? !Array.isArray(own) || key < 0 : !isPlainObject(own) || !(key in own))
+            const reaches = typeof key === "number" ?
+                Array.isArray(own) && key >= 0 :
+                isPlainObject(own) && key in own;
+            if (!reaches)
                 break;
             translated.push(key);
             node = at(node, segment);
@@ -242,6 +246,25 @@ const checkConstraints = (config, posOfPath) => {
     check(config, [], 1);
     return diagnostics;
 };
+/*  the statistics of a schema configuration: the number of specified
+    object kinds (recursively) and of relationship kinds, i.e. the
+    reference-valued properties (whose expressions are valid, as the
+    configuration is validated before use)  */
+export const configStatistics = (config) => {
+    let objects = 0;
+    let links = 0;
+    const walk = (object) => {
+        objects++;
+        for (const prop of object.props ?? [])
+            if (prop.value !== undefined && admitsReferences(compileValueExpr(prop.value)))
+                links++;
+        for (const child of object.childs ?? [])
+            walk(child);
+    };
+    for (const object of config)
+        walk(object);
+    return { objects, links };
+};
 /*  load and validate the YAML schema configuration, merged in order out
     of its files (the later ones into the earlier ones), where every file
     has to be readable and syntactically valid on its own, while the
@@ -282,10 +305,10 @@ export const loadConfig = (files) => {
     }
     if (diagnostics.length > 0)
         return { diagnostics };
-    /*  merge the documents in order, out of fresh and unshared
-        conversions, as the merge mutates its target while the raw ones
-        have to stay intact for the path translation  */
-    const merged = docs.map(({ doc }) => unshared(doc.toJS()))
+    /*  merge the documents in order, out of unshared deep copies of
+        the conversions, as the merge mutates its target while the raw
+        ones have to stay intact for the path translation  */
+    const merged = docs.map(({ raw }) => unshared(raw))
         .reduce((target, source) => mergeConfig(target, source));
     /*  semantically validate the merged result against the schema of the configuration  */
     const posOfPath = (path) => posOfMergedPath(docs, merged, path);

package/dst/specbook-diagram.js

@@ -213,9 +213,12 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
         if (diagram.onlyConnected === true)
             errors.push({ reason: "\"grid\" diagram cannot carry an \"onlyConnected\" configuration" });
     }
-    /*  deduplicate the edges (a containment or object edge can coincide
-        with a reference edge, and several edge objects can describe
-        the very same edge)  */
+    return edges;
+};
+/*  deduplicate the edges (a containment, object, or center edge can
+    coincide with a reference edge, and several edge objects can
+    describe the very same edge)  */
+const dedupEdges = (edges, anchors) => {
     const seenEdges = new Set();
     return edges.filter((edge) => {
         const key = `${anchors.get(edge.source) ?? edge.source.id}` +
@@ -368,7 +371,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
     const edgeSet = new Set(edgeObjects);
     nodes = nodes.filter((node) => !edgeSet.has(node));
     const nodeSet = new Set(nodes);
-    /*  derive the (deduplicated) edges of the diagram  */
+    /*  derive the edges of the diagram  */
     let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors);
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
@@ -384,9 +387,12 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
         return { errors };
     const { center, centerUrl } = derived;
     /*  synthesize the center edges of a "hub" diagram, as the nodes
-        carry no "[[...]]" reference to a synthetic center  */
+        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  */
     if (type === "hub" && diagram.centerEdges !== undefined)
         edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, parenProps, errors));
+    edges = dedupEdges(edges, anchors);
     /*  a "hub" diagram is the hub-projection onto its center object:
         only the edges incident to the center and only the nodes
         connected through them remain, with self-loops dropped, as
@@ -513,11 +519,11 @@ export const validateDiagrams = (ctx, specification, config) => {
                 object itself and report it just once, as a wildcard
                 "edges" pattern lets every diagram walk the very same
                 edge objects again  */
-            const meta = ctx.objectMeta.get(error.object ?? object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(error.object ?? object);
             const message = error.object !== undefined ?
                 `invalid diagram edge on ${error.object.kind} "${error.object.name}": ${error.reason}` :
                 `invalid diagram on ${object.kind} "${object.name}": ${error.reason}`;
-            const key = `${meta.file}${meta.line}${message}`;
+            const key = `${meta.file}\u0000${meta.line}\u0000${message}`;
             if (seen.has(key))
                 continue;
             seen.add(key);

package/dst/specbook-export-common.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import fs from "node:fs";
+import { plainText } from "./specbook-link.js";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -128,24 +129,16 @@ const typographyGlyphs = [
     0x00A0, 0x00AB, 0x00BB, 0x2013, 0x2014, 0x2018, 0x2019,
     0x201A, 0x201C, 0x201D, 0x201E, 0x2022, 0x2026, 0x2039, 0x203A
 ];
-/*  the memoized subsetted stylesheets, keyed by the (shared) codepoint
-    set of the charset, as the font subsetting is expensive and the
-    formats of a single export, the watch and preview re-exports, and
-    the MCP service request the very same subset over and over again  */
+/*  the memoized subsetted stylesheets (as pending or settled promises,
+    so concurrent requests share a single subsetting), keyed by the
+    (shared) codepoint set of the charset, as the font subsetting is
+    expensive and the formats of a single export, the watch and preview
+    re-exports, and the MCP service request the very same subset over
+    and over again  */
 const subsetCache = new Map();
-/*  provide the stylesheet with its embedded fonts subsetted to the
-    codepoints of a charset plus the always-used symbol and typography
-    glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
-export const subsetStylesheet = async (charset) => {
-    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
-    if (codepoints === undefined)
-        return stylesheet();
-    const cached = subsetCache.get(codepoints);
-    if (cached !== undefined)
-        return cached;
-    const css = stylesheet();
+/*  subset the embedded fonts of a stylesheet to the glyphs of a text  */
+const subsetFonts = async (css, text) => {
     const { default: subsetFont } = await import("subset-font");
-    const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
     let result = "";
     let last = 0;
     for (const m of css.matchAll(/url\("data:font\/woff2;base64,([^"]+)"\)/g)) {
@@ -154,18 +147,36 @@ export const subsetStylesheet = async (charset) => {
             `url("data:font/woff2;base64,${subset.toString("base64")}")`;
         last = m.index + m[0].length;
     }
-    const subsetted = result + css.slice(last);
-    subsetCache.set(codepoints, subsetted);
+    return result + css.slice(last);
+};
+/*  provide the stylesheet with its embedded fonts subsetted to the
+    codepoints of a charset plus the always-used symbol and typography
+    glyphs (no charset or a full Unicode charset keeps the fonts complete),
+    where a failed subsetting leaves the cache, so the next request retries  */
+export const subsetStylesheet = async (charset) => {
+    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
+    if (codepoints === undefined)
+        return stylesheet();
+    let subsetted = subsetCache.get(codepoints);
+    if (subsetted === undefined) {
+        const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
+        subsetted = subsetFonts(stylesheet(), text);
+        subsetted.catch(() => { subsetCache.delete(codepoints); });
+        subsetCache.set(codepoints, subsetted);
+    }
     return subsetted;
 };
 /*  determine the document title and subtitle from the title object (an
-    empty TITLE counts as absent, exactly like for the title page)  */
+    empty TITLE counts as absent, exactly like for the title page), with
+    the inline code markup stripped, as the plain-text targets (the HTML
+    <title>, the PDF metadata and page header) render no Markdown  */
 export const documentTitle = (specification) => {
     const title = titleProperty(specification, "TITLE")?.trim();
+    const subtitle = titleProperty(specification, "SUBTITLE")?.trim();
     return {
-        title: title !== undefined && title !== "" ? title :
-            titleObject(specification)?.name ?? "Specification",
-        subtitle: titleProperty(specification, "SUBTITLE")?.trim()
+        title: plainText(title !== undefined && title !== "" ? title :
+            titleObject(specification)?.name ?? "Specification"),
+        subtitle: subtitle !== undefined ? plainText(subtitle) : undefined
     };
 };
 /*  determine the document logo as a self-contained data: URL, taken from the

package/dst/specbook-export-html.css

@@ -81,6 +81,8 @@ html.theme-light {
   --theme-color-specbook-popup-schema-desc: var(--theme-color-base-32);
   --theme-color-specbook-popup-spec-path: var(--theme-color-accent-12);
   --theme-color-specbook-popup-spec-desc: var(--theme-color-base-5);
+  --theme-color-specbook-progress-done: var(--theme-color-accent-12);
+  --theme-color-specbook-progress-todo: var(--theme-color-accent-31);
   --gradia-font-family: "Source Sans 3";
   --gradia-color-node-regular-name: var(--theme-color-accent-12);
   --gradia-color-node-regular-box: var(--theme-color-accent-30);
@@ -122,6 +124,8 @@ html.theme-light {
     --theme-color-specbook-popup-schema-desc: var(--theme-color-base-7);
     --theme-color-specbook-popup-spec-path: var(--theme-color-accent-24);
     --theme-color-specbook-popup-spec-desc: var(--theme-color-base-29);
+    --theme-color-specbook-progress-done: var(--theme-color-accent-24);
+    --theme-color-specbook-progress-todo: var(--theme-color-accent-4);
     --gradia-color-node-regular-name: var(--theme-color-accent-21);
     --gradia-color-node-regular-box: var(--theme-color-accent-3);
     --gradia-color-node-regular-border: var(--theme-color-accent-7);
@@ -437,6 +441,64 @@ div.realtime-status.reloaded svg.realtime-icon {
     display: none;
   }
 }
+/*  the scroll progress meter (screen-only): a ring at the bottom right
+    corner of the viewport (fixed independent of the content scrolling),
+    whose DONE part (the arc drawn clockwise from the top, together with
+    the upward arrow in its center, drawn like the tab icons) reflects
+    the scrolled fraction of the document over the TODO part (the full
+    circle in the lighter progress color beneath), which stays hidden
+    while the page is scrolled near the top (fading in once scrolled
+    beyond 400px) and scrolls the page back to the top on click, where
+    the DONE part and the arrow brighten on hover like the tabs  */
+div.scroll-progress {
+  position: fixed;
+  right: 1.5rem;
+  bottom: 1.5rem;
+  z-index: 30;
+  width: 3rem;
+  height: 3rem;
+  line-height: 0;
+  color: var(--theme-color-specbook-progress-done);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+div.scroll-progress.shown {
+  opacity: 1;
+  pointer-events: auto;
+}
+div.scroll-progress:hover {
+  color: var(--theme-color-specbook-accent-soft);
+}
+div.scroll-progress svg.scroll-ring {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  transform: rotate(-90deg);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-todo {
+  stroke: var(--theme-color-specbook-progress-todo);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-done {
+  stroke: currentColor;
+}
+div.scroll-progress svg.scroll-icon {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 1.1rem;
+  height: 1.1rem;
+  transform: translate(-50%, -50%);
+}
+@media print {
+  div.scroll-progress {
+    display: none;
+  }
+}
 /*  the side panel of the table of contents (screen-only): a fixed
     full-height drawer at the left viewport edge, carrying a replica of
     the brand bar on its right edge, which exactly covers the brand bar