@rse/specbook 0.9.4 → 0.9.6

package/dst/specbook-cli.js

@@ -6,13 +6,18 @@
 */
 import * as fs from "node:fs";
 import { Command } from "commander";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec, version } from "./specbook-api.js";
+import chalk from "chalk";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, version } from "./specbook-api.js";
 import { serveMcp } from "./specbook-mcp.js";
-/*  route verbose messages to stderr, keeping stdout reserved
-    for the command outputs and the MCP protocol  */
-const verboseOf = (opts) => (msg) => {
-    if (opts.verbose)
-        process.stderr.write(`specbook: ${msg}\n`);
+/*  route verbose messages to stderr, keeping stdout reserved for the
+    command outputs and the MCP protocol, and qualify every message with
+    the tool name plus the scope path of the emitting command, where
+    Chalk styles the output only if the terminal supports colors  */
+const verboseOf = (opts, ...scope) => (cmd, msg) => {
+    if (opts.verbose) {
+        const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
+        process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
+    }
 };
 /*  write a buffer to stdout, awaiting the write callback which only
     fires once the data has been flushed to the underlying pipe, so a
@@ -28,12 +33,12 @@ const writeStdout = (data) => {
     });
 };
 /*  write a command result to the output file or stdout  */
-const writeOutput = async (output, data, verbose) => {
+const writeOutput = async (output, data, cmd, verbose) => {
     if (output === "-")
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(`wrote "${output}" (${Buffer.byteLength(data)} bytes)`);
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`);
     }
 };
 /*  determine an option default value, overridable via a
@@ -45,10 +50,13 @@ const envDefaultFlag = (name, fallback) => {
     const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
-/*  provide the common options of all sub-commands  */
-const withCommonOptions = (command) => command
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
-    .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
+/*  provide the verbose option of all sub-commands  */
+const withVerboseOption = (command) => command
+    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false));
+/*  provide the common options of the specification processing sub-commands,
+    for which the YAML schema configuration is mandatory  */
+const withCommonOptions = (command) => withVerboseOption(command)
+    .requiredOption("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
@@ -57,12 +65,11 @@ program.name("specbook")
     .action(() => {
     program.help();
 });
-program.command("mcp")
+withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
     .action(async (opts) => {
-    verboseOf(opts)("starting MCP server on stdio");
-    await serveMcp(verboseOf(opts));
+    verboseOf(opts)("mcp", "starting MCP server on stdio");
+    await serveMcp(verboseOf(opts, "mcp"));
 });
 withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
@@ -87,7 +94,7 @@ withCommonOptions(program.command("lint"))
     if (result.diagnostics.length > 0)
         process.exitCode = 1;
     else
-        verboseOf(opts)("specification valid");
+        verboseOf(opts)("lint", "specification valid");
 });
 withCommonOptions(program.command("export"))
     .description("export the specification Markdown files below the base directory " +
@@ -104,43 +111,20 @@ withCommonOptions(program.command("export"))
     const buffers = await specbook.export({ config: opts.config, basedir: opts.basedir,
         formats: distinct });
     for (const { format, output } of outputs)
-        await writeOutput(output, buffers[distinct.indexOf(format)], verboseOf(opts));
+        await writeOutput(output, buffers[distinct.indexOf(format)], "export", verboseOf(opts));
 });
-withCommonOptions(program.command("describe"))
-    .description("describe the configured specification format as Markdown")
+/*  the describe command also describes the generic SpecBook models and
+    formats alone, so its YAML schema configuration stays optional  */
+withVerboseOption(program.command("describe"))
+    .description("describe the SpecBook models and formats as Markdown")
+    .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"))
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
+    .option("-e, --embed", "embed the YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const text = await specbook.describe({ config: opts.config });
-    await writeOutput(opts.output, text, verboseOf(opts));
-});
-withCommonOptions(program.command("import"))
-    .description("import foreign sources into the specification artifact files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
-    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
-    .option("--model <model>", "AI model", envDefault("model"))
-    .argument("<input-files...>", "foreign source files to import")
-    .action(async (inputs, opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const written = await specbook.import({ config: opts.config, basedir: opts.basedir,
-        inputs, provider: opts.provider, model: opts.model });
-    await writeStdout(written.length > 0 ?
-        `imported into artifact file(s): ${written.join(", ")}\n` :
-        "no artifact files were changed\n");
-});
-withCommonOptions(program.command("edit"))
-    .description("apply a free-text edit request to the specification artifact files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
-    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
-    .option("--model <model>", "AI model", envDefault("model"))
-    .argument("<query>", "free-text edit request")
-    .action(async (query, opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const written = await specbook.edit({ config: opts.config, basedir: opts.basedir,
-        query, provider: opts.provider, model: opts.model });
-    await writeStdout(written.length > 0 ?
-        `edited artifact file(s): ${written.join(", ")}\n` :
-        "no artifact files were changed\n");
+    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir, embed: opts.embed });
+    await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
 try {
     await program.parseAsync();

package/dst/specbook-cmd-describe.d.ts

@@ -1,2 +1,5 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
-export declare const describeConfiguration: (config: SchemaSpecification) => string;
+export declare const describeFormat: (options: {
+    config?: string;
+    basedir?: string;
+    embed?: boolean;
+}) => string;

package/dst/specbook-cmd-describe.js

@@ -3,97 +3,38 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import textframe from "textframe";
-/*  collapse folded YAML prose into a single line  */
-const collapse = (text) => (text ?? "").replace(/\s+/g, " ").trim();
-/*  the static description of the generic Markdown syntax  */
-const syntax = textframe `
-    #   SpecBook Specification Format
-
-    A specification consists of Markdown *artifact* files, each carrying a
-    frontmatter with \`Created:\` and \`Modified:\` timestamps (format
-    \`yyyy-LL-dd HH:mm\`) and a tree of *objects*. Every object has a *kind*,
-    a *name*, a unique anchor *id*, optional *properties* (key/value pairs),
-    an optional *description* statement with an optional rationale, and
-    optional *child* objects. Two concrete syntaxes exist:
-
-    ##  Complex Format (used on levels 1-3)
-
-    \`\`\`
-    #   <kind>: <name> (<id>)
-
-    -   <key>: <value>
-    -   [...]
-
-    <statement>, BECAUSE <rationale>.
-    \`\`\`
-
-    Level 1 (\`#\`) carries the artifact id in parentheses. Levels 2 (\`##\`)
-    and 3 (\`###\`) instead carry an HTML anchor \`<a id="<id>"></a>\` after
-    the name, where the id uses the artifact id as its prefix.
-
-    ##  Concise Format (used on level 4 and deeper)
-
-    \`\`\`
-    -   <kind>: <name>; <key>: <value>; [...]; <statement>, BECAUSE <rationale>.
-    \`\`\`
-
-    Child objects nest as indented list items below their parent item.
-
-    ##  Primary Marker
-
-    In both formats a literal \`(*)\` directly after the \`<name>\` marks the
-    object as *primary* (e.g. the primary attribute of an entity). It is
-    distinct from an id given as \`(<id>)\` and both may be combined.
-
-    ##  Configured Artifacts
-
-    The following artifacts, object kinds, and properties are configured.
-    Object kinds and property names are *case-sensitive* and must be
-    written exactly as configured. Properties marked \`required\` must be
-    present, and property values must match their given constraint (if
-    any, else any value is allowed): \`/xxx/\` requires a match of the
-    regular expression, \`[[xxx]]\` requires exactly one Wiki-style link
-    reference resolving into the (usually wildcard) reference pattern,
-    \`enum(xxx,yyy)\` requires one of the listed members, \`tags(xxx,yyy)\`
-    requires a comma-separated set of the listed members (each at most
-    once), and \`list(xxx[, ...])\` requires a comma-separated list of
-    items, each matching one of the alternative constraints.
-`;
-/*  describe a single configured property  */
-const describeProperty = (prop, indent) => {
-    let line = `${indent}-   property \`${prop.name}\` (${prop.optional === true ? "optional" : "required"}`;
-    if (prop.value !== undefined)
-        line += `, constraint \`${prop.value}\``;
-    line += `): ${collapse(prop.desc)}`;
-    return line;
-};
-/*  describe a single configured object kind (and recursively its childs)  */
-const describeObject = (object, level, indent) => {
-    const lines = new Array();
-    lines.push(`${indent}-   object kind \`${object.kind}\` on level ${level}` +
-        `${object.optional === true ? " (optional)" : ""}: ${collapse(object.desc)}`);
-    for (const prop of object.props ?? [])
-        lines.push(describeProperty(prop, `${indent}    `));
-    for (const child of object.childs ?? [])
-        lines.push(describeObject(child, level + 1, `${indent}    `));
-    return lines.join("\n");
-};
-/*  describe the configured specification format as Markdown  */
-export const describeConfiguration = (config) => {
-    const sections = new Array();
-    for (const artifact of config) {
-        const lines = new Array();
-        lines.push(`### ${artifact.kind}: ${artifact.name ?? ""} (${artifact.kind}-${artifact.id ?? ""})`);
-        lines.push("");
-        if (artifact.file !== undefined)
-            lines.push(`-   file: \`${artifact.file}\``);
-        lines.push(`-   description: ${collapse(artifact.desc)}`);
-        for (const prop of artifact.props ?? [])
-            lines.push(describeProperty(prop, ""));
-        for (const child of artifact.childs ?? [])
-            lines.push(describeObject(child, 2, ""));
-        sections.push(lines.join("\n"));
+/*  provide the build-time bundled description of the generic
+    SpecBook models and formats  */
+const description = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-format.md"), "utf8");
+/*  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  */
+export const describeFormat = (options) => {
+    const sections = [description()];
+    if (options.config !== undefined || options.basedir !== undefined) {
+        sections.push("SpecBook Project Instantiation\n" +
+            "==============================\n");
+        if (options.config !== undefined && options.embed === true)
+            sections.push(textframe(`
+                The **SpecBook SCHEMA Model** of this particular project is the following
+                YAML schema configuration of the file \`${options.config}\`:
+            `) + "\n```yaml\n" +
+                fs.readFileSync(options.config, "utf8").replace(/\n*$/, "\n") +
+                "```\n");
+        else if (options.config !== undefined)
+            sections.push(textframe(`
+                The **SpecBook SCHEMA Model** of this particular project is the YAML
+                schema configuration in the file \`${options.config}\`.
+            `));
+        if (options.basedir !== undefined)
+            sections.push(textframe(`
+                The **SpecBook SPEC Model** of this particular project is the set of
+                specification Markdown files in the directory \`${options.basedir}\`.
+            `));
     }
-    return `${syntax}\n${sections.join("\n\n")}\n`;
+    return sections.join("\n");
 };

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

@@ -1,9 +1,9 @@
-import type { Specification } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import type { Spec } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
 export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 export type ExportFormat = typeof formats[number];
 export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Specification, format: ExportFormat, verbose: (msg: string) => void, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: (msg: string) => void, config?: Schema) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -10,6 +10,7 @@ import { renderAst } from "./specbook-export-ast.js";
 import { renderMarkdown } from "./specbook-export-md.js";
 import { renderHtml, htmlOutline } from "./specbook-export-html.js";
 import { htmlToPdf } from "./specbook-export-pdf.js";
+import { literal } from "./specbook-verbose.js";
 /*  the supported export formats  */
 export const formats = ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 /*  the filename extensions mapping onto the export formats  */
@@ -42,7 +43,7 @@ export const parseOutputSpec = (spec) => {
 export const exportSpecification = async (specification, format, verbose, config) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
-    verbose(`exporting specification as "${format}"`);
+    verbose(`exporting specification as "${literal(format)}"`);
     if (format === "json" || format === "json5" || format === "yaml" || format === "toon")
         return renderAst(specification, format, config);
     else if (format === "md")
@@ -51,11 +52,11 @@ export const exportSpecification = async (specification, format, verbose, config
         fonts subsetted to the CHARSET of the specification (if any)  */
     const charset = documentCharset(specification);
     if (charset !== undefined)
-        verbose(`subsetting embedded fonts to charset "${charset}"`);
+        verbose(`subsetting embedded fonts to charset "${literal(charset)}"`);
     /*  the theme tone (THEME-TONE) drives the layer-1 color spread
         variables and the PDF decoration colors  */
     const tone = documentThemeTone(specification) ?? "#336699";
-    verbose(`generating theme color spreads (tone "${tone}")`);
+    verbose(`generating theme color spreads (tone "${literal(tone)}")`);
     const colors = themeColors(tone);
     /*  the paper size (PAPER-SIZE) drives the PDF page setup and the
         print-time height constraint of the diagrams  */

package/dst/specbook-cmd-init.d.ts

@@ -1,6 +1,6 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Schema } from "./specbook-format-schema.js";
 export interface InitOptions {
-    config: SchemaSpecification;
+    config: Schema;
     basedir?: string;
     verbose: (msg: string) => void;
 }

package/dst/specbook-cmd-init.js

@@ -5,35 +5,57 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { timestamp } from "./specbook-llm.js";
+import { literal } from "./specbook-verbose.js";
+/*  the current time in the frontmatter timestamp format  */
+const timestamp = () => {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+};
 /*  initialize the configured specification artifact files below the
-    base directory with their frontmatter and artifact heading  */
+    base directory with their frontmatter and artifact headings, where
+    all artifacts configured onto the same file reside in it side by
+    side, following each other on level 1  */
 export const initSpecification = (options) => {
     const basedir = options.basedir ?? ".";
     fs.mkdirSync(basedir, { recursive: true });
     const now = timestamp();
     const created = new Array();
+    /*  group the configured artifacts by their file, preserving the
+        schema order both of the files and of the artifacts within  */
+    const groups = new Map();
     for (const artifact of options.config) {
         if (artifact.file === undefined)
             continue;
-        const file = path.join(basedir, artifact.file);
-        if (fs.existsSync(file)) {
-            options.verbose(`skipping existing artifact file "${artifact.file}"`);
+        const group = groups.get(artifact.file);
+        if (group === undefined)
+            groups.set(artifact.file, [artifact]);
+        else
+            group.push(artifact);
+    }
+    for (const [file, artifacts] of groups) {
+        const target = path.join(basedir, file);
+        if (fs.existsSync(target)) {
+            options.verbose(`skipping existing artifact file "${literal(file)}"`);
             continue;
         }
-        const name = artifact.name ?? "";
-        const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
+        const headings = artifacts.map((artifact) => {
+            const name = artifact.name ?? "";
+            const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
+            return `#   ${artifact.kind}: ${name}${paren}\n` + "\n";
+        }).join("");
         const text = "---\n" +
             `Created:  ${now}\n` +
             `Modified: ${now}\n` +
             "---\n" +
             "\n" +
-            `#   ${artifact.kind}: ${name}${paren}\n` +
-            "\n";
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, text, "utf8");
-        options.verbose(`created artifact file "${artifact.file}"`);
-        created.push(artifact.file);
+            headings;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, text, "utf8");
+        options.verbose(`created artifact file "${literal(file)}" ` +
+            `with ${literal(artifacts.length)} artifact(s)`);
+        created.push(file);
     }
     return created;
 };

package/dst/specbook-cmd-lint.d.ts

@@ -1,15 +1,15 @@
 import { type Diagnostic } from "./specbook-diagnostic.js";
-import { type Specification } from "./specbook-struct-spec.js";
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Spec } from "./specbook-format-spec.js";
+import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
-    config?: string;
+    config: string;
     basedir: string;
     verbose: (msg: string) => void;
 }
 export interface LintResult {
-    specification: Specification;
+    specification: Spec;
     diagnostics: Diagnostic[];
-    config?: SchemaSpecification;
+    config?: Schema;
 }
-export declare const scanMarkdown: (basedir: string) => string[];
+export declare const schemaFiles: (config: Schema) => Map<string, boolean>;
 export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -6,34 +6,47 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig } from "./specbook-config.js";
+import { literal } from "./specbook-verbose.js";
 import { parseSpecification } from "./specbook-parse.js";
-/*  recursively scan a base directory for Markdown files  */
-export const scanMarkdown = (basedir) => fs.readdirSync(basedir, { recursive: true, withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
-    .map((entry) => path.join(entry.parentPath, entry.name))
-    .sort();
+/*  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  */
+export const schemaFiles = (config) => {
+    const files = new Map();
+    for (const artifact of config) {
+        if (artifact.file === undefined)
+            continue;
+        files.set(artifact.file, (files.get(artifact.file) ?? true) && artifact.optional === true);
+    }
+    return files;
+};
 /*  lint the specification Markdown files below the base directory
-    against the optional configuration  */
+    against the configuration  */
 export const lint = (options) => {
     const diagnostics = new Array();
-    /*  load the optional YAML schema configuration  */
-    let config;
-    if (options.config !== undefined) {
-        options.verbose(`loading configuration "${options.config}"`);
-        const loaded = loadConfig(options.config);
-        diagnostics.push(...loaded.diagnostics);
-        config = loaded.config ?? undefined;
-    }
-    /*  parse and validate the specification Markdown files  */
-    const exists = fs.existsSync(options.basedir) && fs.statSync(options.basedir).isDirectory();
-    const files = exists ? scanMarkdown(options.basedir) : [];
-    options.verbose(`parsing ${files.length} specification file(s) below "${options.basedir}"`);
-    if (files.length === 0)
-        diagnostics.push({ file: options.basedir, line: 1, column: 1,
-            message: exists ? "no Markdown files found below base directory" :
-                "base directory does not exist" });
+    /*  load the mandatory YAML schema configuration  */
+    options.verbose(`loading configuration "${literal(options.config)}"`);
+    const loaded = loadConfig(options.config);
+    diagnostics.push(...loaded.diagnostics);
+    const config = loaded.config ?? undefined;
+    /*  read the artifact files the configuration references, resolved
+        against the base directory and tolerating an absent file if all
+        its artifacts are optional  */
+    const files = config !== undefined ? schemaFiles(config) : new Map();
+    options.verbose(`parsing ${literal(files.size)} specification file(s) ` +
+        `below "${literal(options.basedir)}"`);
+    if (config !== undefined && files.size === 0)
+        diagnostics.push({ file: options.config, line: 1, column: 1,
+            message: "no artifact files configured" });
     const sources = new Array();
-    for (const file of files) {
+    for (const [name, optional] of files) {
+        const file = path.join(options.basedir, name);
+        if (!fs.existsSync(file)) {
+            if (!optional)
+                diagnostics.push({ file, line: 1, column: 1,
+                    message: "missing artifact file" });
+            continue;
+        }
         try {
             sources.push({ file, text: fs.readFileSync(file, "utf8") });
         }

package/dst/specbook-config.d.ts

@@ -1,6 +1,6 @@
-import { SchemaSpecification } from "./specbook-struct-schema.js";
+import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 export declare const loadConfig: (file: string) => {
-    config: SchemaSpecification | null;
+    config: Schema | null;
     diagnostics: Diagnostic[];
 };

package/dst/specbook-config.js

@@ -6,7 +6,7 @@
 import * as fs from "node:fs";
 import { parse as parseYaml, parseDocument, YAMLParseError } from "yaml";
 import * as v from "valibot";
-import { SchemaSpecification } from "./specbook-struct-schema.js";
+import { Schema } from "./specbook-format-schema.js";
 import { compileValueExpr } from "./specbook-parse-value.js";
 /*  determine line/column of a YAML document path via the CST  */
 const lineColOfPath = (yaml, cst, path) => {
@@ -58,7 +58,7 @@ export const loadConfig = (file) => {
         cst ??= parseDocument(yaml);
         return lineColOfPath(yaml, cst, path);
     };
-    const result = v.safeParse(SchemaSpecification, obj);
+    const result = v.safeParse(Schema, obj);
     if (!result.success) {
         for (const issue of result.issues) {
             const path = (issue.path ?? []).map((item) => item.key);

package/dst/specbook-diagram.d.ts

@@ -1,9 +1,9 @@
-import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
 import { type ParseContext } from "./specbook-parse-common.js";
 export interface DiagramResult {
     spec?: string;
     errors: string[];
 }
-export declare const specDiagrams: (specification: Specification, config: SchemaSpecification) => Map<SpecObject, DiagramResult>;
-export declare const validateDiagrams: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;
+export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
+export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -10,9 +10,6 @@ const referenceOnce = /\[\[([^[\]]+)\]\]/;
 /*  strip the inline code markup of a name or property value
     (preserved in the AST for rendering) for labeling purposes  */
 const plainText = (text) => text.replace(/`/g, "");
-/*  strip a trailing parenthesized annotation from a
-    property key (e.g. "WHEN (Context)")  */
-const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
 /*  render a text as a Gradia atom: a bareword where possible
     (no whitespace, no special characters, no "--"), a quoted
     string otherwise  */
@@ -58,7 +55,7 @@ const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
             the node set can mix objects of different kinds), with every
             "[[...]]" reference stripped to its target object name  */
         for (const key of diagram.properties ?? []) {
-            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
+            const value = node.properties.find((property) => property.key === key)?.value;
             if (value !== undefined) {
                 const text = value.replace(referenceRegex, (_, reference) => {
                     const target = resolveUnique(index, reference.trim()).target;
@@ -128,8 +125,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         objects (per the "links" selection) and from the edge objects by
         convention (source: parent object, target: first reference in the
         property values, name: object name, arity: "ARITY" property),
-        overridable via "edgeTarget"/"edgeArity" (a "grid" diagram is
-        edge-less by definition, so no edges are derived for it at all)  */
+        overridable via "edgeSource"/"edgeTarget"/"edgeArity" (a "grid"
+        diagram is edge-less by definition, so no edges are derived at all)  */
     let edges = new Array();
     if (type !== "grid") {
         for (const node of nodes) {
@@ -146,16 +143,25 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
                         edges.push({ source: node, target });
                 }
         }
-        for (const edgeObject of edgeObjects) {
-            const source = parents.get(edgeObject);
-            const value = diagram.edgeTarget !== undefined ?
-                edgeObject.properties.find((property) => plainKey(property.key) === diagram.edgeTarget)?.value :
-                edgeObject.properties.map((property) => property.value)
-                    .find((v) => referenceOnce.test(v));
+        /*  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) => {
+            const value = key !== undefined ?
+                edgeObject.properties.find((property) => property.key === key)?.value :
+                edgeObject.properties.filter((property) => property.key !== diagram.edgeSource)
+                    .map((property) => property.value).find((v) => referenceOnce.test(v));
             const reference = value?.match(referenceOnce)?.[1].trim();
-            const target = reference !== undefined ? resolveUnique(index, reference).target : undefined;
+            return reference !== undefined ? resolveUnique(index, reference).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);
             if (source === undefined) {
-                errors.push(`diagram edge object "${edgeObject.name}" has no parent object as source`);
+                errors.push(diagram.edgeSource !== undefined ?
+                    `diagram edge object "${edgeObject.name}" carries no resolvable source reference` :
+                    `diagram edge object "${edgeObject.name}" has no parent object as source`);
                 continue;
             }
             if (target === undefined) {
@@ -164,7 +170,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             }
             if (!nodeSet.has(source) || !nodeSet.has(target))
                 continue;
-            const arity = edgeObject.properties.find((property) => plainKey(property.key) === (diagram.edgeArity ?? "ARITY"))?.value;
+            const arity = edgeObject.properties.find((property) => property.key === (diagram.edgeArity ?? "ARITY"))?.value;
             edges.push({ source, target, name: plainText(edgeObject.name),
                 arity: arity !== undefined ? plainText(arity) : undefined });
         }

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

@@ -1,4 +1,4 @@
-import type { Specification } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import type { Spec } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
 export type AstFormat = "json" | "json5" | "yaml" | "toon";
-export declare const renderAst: (specification: Specification, format: AstFormat, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema) => Promise<Buffer>;