@rse/specbook 0.9.2

package/dst/specbook-parse-value.js

@@ -0,0 +1,123 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { Tokenizr } from "tokenizr";
+/*  the lexer for value expressions (members are either bare words or
+    double-quoted strings, mirroring the quoting of reference segments)  */
+const lexer = new Tokenizr();
+lexer.rule(/\/((?:\\.|[^\\/])*)\//, (ctx, match) => {
+    ctx.accept("regex", match[1]);
+});
+lexer.rule(/\[\[([^[\]]+)\]\]/, (ctx, match) => {
+    ctx.accept("reference", match[1].trim());
+});
+lexer.rule(/(enum|tags|list)\(/, (ctx, match) => {
+    ctx.accept("opener", match[1]);
+});
+lexer.rule(/"((?:\\"|[^"])*)"/, (ctx, match) => {
+    ctx.accept("member", match[1].replace(/\\"/g, "\""));
+});
+lexer.rule(/[^,()/[\]"\s]+/, (ctx, match) => {
+    ctx.accept("member", match[0]);
+});
+lexer.rule(/,/, (ctx) => {
+    ctx.accept("comma");
+});
+lexer.rule(/\)/, (ctx) => {
+    ctx.accept("close");
+});
+lexer.rule(/\s+/, (ctx) => {
+    ctx.ignore();
+});
+/*  describe a token for error messages  */
+const tokenName = (token) => token.type === "EOF" ? "end of expression" : `"${token.text}"`;
+/*  parse a single expression from the token stream  */
+const parseValueExpr = (tokens, pos, nested) => {
+    const token = tokens[pos.i++];
+    if (token.type === "regex") {
+        const source = String(token.value);
+        try {
+            return { kind: "regex", regex: new RegExp(source), source };
+        }
+        catch (err) {
+            throw new Error(`invalid regular expression "/${source}/": ` +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    else if (token.type === "reference")
+        return { kind: "reference", pattern: String(token.value) };
+    else if (token.type === "opener" && (token.value === "enum" || token.value === "tags")) {
+        const members = new Array();
+        for (;;) {
+            const member = tokens[pos.i++];
+            if (member.type !== "member")
+                throw new Error(`expected member in "${token.value}(...)", got ${tokenName(member)}`);
+            members.push(String(member.value));
+            const sep = tokens[pos.i++];
+            if (sep.type === "close")
+                break;
+            if (sep.type !== "comma")
+                throw new Error(`expected "," or ")" in "${token.value}(...)", got ${tokenName(sep)}`);
+        }
+        return { kind: token.value === "enum" ? "enum" : "tags", members };
+    }
+    else if (token.type === "opener" && token.value === "list") {
+        if (nested)
+            throw new Error("nested \"list(...)\" is not allowed");
+        const alternatives = new Array();
+        for (;;) {
+            alternatives.push(parseValueExpr(tokens, pos, true));
+            const sep = tokens[pos.i++];
+            if (sep.type === "close")
+                break;
+            if (sep.type !== "comma")
+                throw new Error(`expected "," or ")" in "list(...)", got ${tokenName(sep)}`);
+        }
+        return { kind: "list", alternatives };
+    }
+    else
+        throw new Error(`expected value expression, got ${tokenName(token)}`);
+};
+/*  compile a value expression, memoized per source string  */
+const cache = new Map();
+export const compileValueExpr = (source) => {
+    let expr = cache.get(source);
+    if (expr === undefined) {
+        const tokens = lexer.reset().input(source).tokens();
+        const pos = { i: 0 };
+        expr = parseValueExpr(tokens, pos, false);
+        if (tokens[pos.i].type !== "EOF")
+            throw new Error(`unexpected trailing ${tokenName(tokens[pos.i])}`);
+        cache.set(source, expr);
+    }
+    return expr;
+};
+/*  split a property value at top-level commas, honoring double-quoted
+    sections and "[[...]]" reference bracketing  */
+export const splitItems = (text) => {
+    const parts = [""];
+    let quoted = false;
+    let bracketed = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === "\"")
+            quoted = !quoted;
+        if (!quoted && !bracketed && char === "[" && text[i + 1] === "[") {
+            parts[parts.length - 1] += "[[";
+            bracketed = true;
+            i++;
+        }
+        else if (!quoted && bracketed && char === "]" && text[i + 1] === "]") {
+            parts[parts.length - 1] += "]]";
+            bracketed = false;
+            i++;
+        }
+        else if (!quoted && !bracketed && char === ",")
+            parts.push("");
+        else
+            parts[parts.length - 1] += char;
+    }
+    return parts.map((part) => part.trim()).filter((part) => part !== "");
+};

package/dst/specbook-parse.d.ts

@@ -0,0 +1,8 @@
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
+export { type SourceFile, type ParseResult, embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+export declare class Parser {
+    private ctx;
+    parse(sources: SourceFile[], config?: SchemaSpecification): ParseResult;
+}
+export declare const parseSpecification: (sources: SourceFile[], config?: SchemaSpecification) => ParseResult;

package/dst/specbook-parse.js

@@ -0,0 +1,43 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as v from "valibot";
+import { Specification } from "./specbook-struct-spec.js";
+import { buildLinkIndex } from "./specbook-link.js";
+import { ParseContext } from "./specbook-parse-common.js";
+import { parseFile } from "./specbook-parse-syntax.js";
+import { validate, validateReferences } from "./specbook-parse-semantic.js";
+import { validateDiagrams } from "./specbook-diagram.js";
+/*  re-export the public parsing types and embedding helpers  */
+export { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+/*  parser for a set of specification Markdown files  */
+export class Parser {
+    ctx = new ParseContext();
+    /*  parse all source files into the specification AST and
+        optionally validate the result against a configuration  */
+    parse(sources, config) {
+        const artifacts = new Array();
+        for (const source of sources)
+            artifacts.push(...parseFile(this.ctx, source));
+        const specification = { artifacts };
+        if (artifacts.length > 0) {
+            this.ctx.linkIndex = buildLinkIndex(specification);
+            if (config !== undefined)
+                validate(this.ctx, specification, config);
+            validateReferences(this.ctx, specification);
+            if (config !== undefined)
+                validateDiagrams(this.ctx, specification, config);
+            const result = v.safeParse(Specification, specification);
+            if (!result.success)
+                for (const issue of result.issues) {
+                    const path = (issue.path ?? []).map((item) => String(item.key)).join(".");
+                    this.ctx.diagnose(sources[0]?.file ?? "", 1, `internal AST invalid at "${path}": ${issue.message}`);
+                }
+        }
+        return { specification, diagnostics: this.ctx.diagnostics };
+    }
+}
+/*  convenience wrapper for one-shot parsing  */
+export const parseSpecification = (sources, config) => new Parser().parse(sources, config);

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

@@ -0,0 +1,35 @@
+import * as v from "valibot";
+import { type Config as GradiaConfig } from "@rse/gradia";
+export type SchemaSpecification = SchemaObject[];
+export type SchemaObject = {
+    kind: string;
+    name?: string;
+    id?: string;
+    file?: string;
+    desc?: string;
+    optional?: boolean;
+    diagram?: SchemaDiagram;
+    props?: SchemaProperty[];
+    childs?: SchemaObject[];
+};
+export type SchemaDiagram = {
+    type?: "graph" | "hub" | "grid";
+    nodes?: string;
+    edges?: string;
+    center?: string;
+    links?: "props" | "all";
+    edgeTarget?: string;
+    edgeArity?: string;
+    hierarchy?: boolean;
+    onlyConnected?: boolean;
+    collapse?: boolean;
+    qualified?: boolean;
+    config?: Partial<GradiaConfig>;
+};
+export type SchemaProperty = {
+    name: string;
+    desc?: string;
+    value?: string;
+    optional?: boolean;
+};
+export declare const SchemaSpecification: v.GenericSchema<SchemaSpecification>;

package/dst/specbook-struct-schema.js

@@ -0,0 +1,47 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as v from "valibot";
+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  */
+const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map(([key, value]) => [key,
+    typeof value === "boolean" ? v.boolean() : typeof value === "number" ? v.number() : 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.object({
+    name: v.string(),
+    desc: v.optional(v.string()),
+    value: v.optional(v.string()),
+    optional: v.optional(v.boolean())
+});
+const SchemaDiagram = v.object({
+    type: v.optional(v.picklist(["graph", "hub", "grid"])),
+    nodes: v.optional(v.string()),
+    edges: v.optional(v.string()),
+    center: v.optional(v.string()),
+    links: v.optional(v.picklist(["props", "all"])),
+    edgeTarget: v.optional(v.string()),
+    edgeArity: v.optional(v.string()),
+    hierarchy: v.optional(v.boolean()),
+    onlyConnected: v.optional(v.boolean()),
+    collapse: v.optional(v.boolean()),
+    qualified: v.optional(v.boolean()),
+    config: v.optional(SchemaDiagramConfig)
+});
+const SchemaObject = v.object({
+    kind: v.string(),
+    name: v.optional(v.string()),
+    id: v.optional(v.string()),
+    file: v.optional(v.string()),
+    desc: v.optional(v.string()),
+    optional: v.optional(v.boolean()),
+    diagram: v.optional(SchemaDiagram),
+    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));

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

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

package/dst/specbook-struct-spec.js

@@ -0,0 +1,36 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as v from "valibot";
+/*  ==== Schema ====  */
+const Property = v.object({
+    key: v.string(),
+    value: v.string(),
+    embedding: v.optional(v.array(v.string()))
+});
+const Description = v.object({
+    description: v.string(),
+    rationale: v.optional(v.string()),
+    embedding: v.optional(v.array(v.string()))
+});
+const Object = 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))
+});
+const Artifact = v.object({
+    created: v.date(),
+    modified: v.date(),
+    objects: v.pipe(v.array(Object), v.minLength(1))
+});
+export const Specification = v.object({
+    artifacts: v.pipe(v.array(Artifact), v.minLength(1))
+});

package/dst/specbook-theme.d.ts

@@ -0,0 +1,16 @@
+export type ThemeStyle = "light" | "dark";
+export type ThemeColors = {
+    base: string[];
+    accent: string[];
+    search: string[];
+};
+export declare const themeColors: (tone: string) => ThemeColors;
+export declare const themeStylesheet: (colors: ThemeColors) => string;
+export type ThemeMapping = {
+    text: string;
+    muted: string;
+    symbol: string;
+    border: string;
+    accent: string;
+};
+export declare const themeMapping: (colors: ThemeColors, style: ThemeStyle) => ThemeMapping;

package/dst/specbook-theme.js

@@ -0,0 +1,38 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { parse, generate } from "@rse/mrcs";
+/*  generate the theme color spreads from the theme color tone:
+    a grey base spread, a tone-derived accent spread, and a search
+    spread derived from the complement-transposed tone  */
+export const themeColors = (tone) => {
+    const transposed = tone.endsWith("^") ? tone.slice(0, -1) : `${tone}^`;
+    return {
+        base: generate(parse("#000000/32")),
+        accent: generate(parse(`${tone}+40-5/32`)),
+        search: generate(parse(`${transposed}+40-5/32`))
+    };
+};
+/*  render the theme colors into the layer-1 ":root" CSS variable
+    block "--theme-color-{base,accent,search}-{1..32}"  */
+export const themeStylesheet = (colors) => ":root {\n" +
+    colors.base.map((color, i) => `    --theme-color-base-${i + 1}: ${color};\n`).join("") +
+    colors.accent.map((color, i) => `    --theme-color-accent-${i + 1}: ${color};\n`).join("") +
+    colors.search.map((color, i) => `    --theme-color-search-${i + 1}: ${color};\n`).join("") +
+    "}\n";
+/*  map the theme color spreads onto the semantic theme colors,
+    aligned with the layer-2 CSS mapping of the HTML rendering  */
+export const themeMapping = (colors, style) => {
+    const idx = style === "dark" ?
+        { text: 28, muted: 22, symbol: 20, border: 16, accent: 24 } :
+        { text: 5, muted: 22, symbol: 24, border: 28, accent: 12 };
+    return {
+        text: colors.base[idx.text - 1],
+        muted: colors.base[idx.muted - 1],
+        symbol: colors.base[idx.symbol - 1],
+        border: colors.base[idx.border - 1],
+        accent: colors.accent[idx.accent - 1]
+    };
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+    "name":                                "@rse/specbook",
+    "version":                             "0.9.2",
+    "publishConfig":                       { "access": "public" },
+    "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
+    "license":                             "Apache-2.0",
+    "author": {
+        "name":                            "Dr. Ralf S. Engelschall",
+        "email":                           "rse@engelschall.com",
+        "url":                             "http://engelschall.com"
+    },
+    "type":                                "module",
+    "main":                                "dst/specbook-api.js",
+    "types":                               "dst/specbook-api.d.ts",
+    "bin": {
+        "specbook":                        "dst/specbook-cli.js"
+    },
+    "files":                               [ "dst" ],
+    "dependencies": {
+        "marked":                          "18.0.10",
+        "marked-smartypants":              "1.1.12",
+        "yaml":                            "2.9.0",
+        "json5":                           "2.2.3",
+        "pdf-lib":                         "1.17.1",
+        "subset-font":                     "2.5.0",
+        "@rse/mrcs":                       "0.9.1",
+        "@rse/gradia":                     "0.9.4",
+        "@toon-format/toon":               "4.1.1",
+        "valibot":                         "1.4.2",
+        "nunjucks":                        "3.2.4",
+        "@rse/nunjucks-addons":            "2.2.0",
+        "textframe":                       "1.2.1",
+        "@swc/html":                       "1.16.1",
+        "tokenizr":                        "2.2.1",
+        "playwright":                      "1.62.1",
+        "ai":                              "7.0.68",
+        "@ai-sdk/anthropic":               "4.0.39",
+        "@ai-sdk/openai":                  "4.0.43",
+        "@openrouter/ai-sdk-provider":     "3.0.0",
+        "ollama-ai-provider-v2":           "4.0.1",
+        "source-code-error":               "1.2.0",
+        "commander":                       "15.0.0",
+        "@modelcontextprotocol/sdk":       "1.30.0",
+        "zod":                             "4.4.3"
+    },
+    "devDependencies": {
+        "eslint":                          "9.39.5",
+        "@eslint/js":                      "9.39.5",
+        "typescript-eslint":               "8.67.0",
+        "eslint-plugin-promise":           "7.3.0",
+        "eslint-plugin-import":            "2.32.0",
+        "neostandard":                     "0.13.0",
+        "globals":                         "17.11.0",
+        "@types/node":                     "26.2.0",
+        "@types/subset-font":              "2.3.0",
+        "@types/nunjucks":                 "3.2.6",
+        "typescript":                      "6.0.3",
+        "tsx":                             "4.23.12",
+        "source-sans":                     "3.52.0",
+        "source-code-pro":                 "2.42.0",
+        "@fontsource/noto-sans-symbols":   "5.3.0",
+        "postcss":                         "8.5.26",
+        "postcss-cli":                     "11.0.1",
+        "postcss-url":                     "10.1.4",
+        "@rse/stx":                        "1.1.6",
+        "shx":                             "0.4.0",
+        "nodemon":                         "3.1.14"
+    },
+    "upd":                                 [ "!eslint", "!@eslint/js", "!typescript" ],
+    "allowScripts": {
+        "fsevents":                        true,
+        "esbuild":                         true
+    },
+    "scripts": {
+        "start":                           "stx -v4 -l warning -c etc/stx.conf"
+    }
+}