@rse/gradia 0.9.8 → 1.0.0

package/dst/gradia-cli.js

@@ -13,7 +13,6 @@ import { Command, Option } from "commander";
 /*  internal dependencies  */
 import { configDefaults } from "./gradia-api-config.js";
 import { Gradia, diagramTypes, diagramTypeDefault, diagramFormats, diagramFormatDefault } from "./gradia-api.js";
-import { serve as serveMCP } from "./gradia-mcp.js";
 /*  internal package meta-information  */
 const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
 /*  establish the command-line interface  */
@@ -37,9 +36,9 @@ program.name("gradia")
         const m = /^([a-z][a-z0-9-]*)=(.*)$/.exec(nv);
         if (m === null)
             throw new Error(`invalid configuration option "${nv}" (expected "<name>=<value>")`);
-        const key = m[1];
-        if (!Object.hasOwn(configDefaults, key))
+        if (!Object.hasOwn(configDefaults, m[1]))
             throw new Error(`unknown configuration option "${m[1]}"`);
+        const key = m[1];
         if (typeof configDefaults[key] === "boolean") {
             if (m[2] !== "true" && m[2] !== "false")
                 throw new Error(`invalid value "${m[2]}" for boolean configuration option "${key}" (expected "true" or "false")`);
@@ -51,6 +50,8 @@ program.name("gradia")
                 throw new Error(`invalid value "${m[2]}" for numeric configuration option "${key}" (expected a non-negative number)`);
             store[key] = num;
         }
+        else if (m[2] === "")
+            throw new Error(`invalid empty value for string configuration option "${key}"`);
         else
             store[key] = m[2];
     }
@@ -63,6 +64,7 @@ program.name("gradia")
             throw new Error("option \"--mcp\" cannot be combined with an input graph description file");
         if (options.output !== undefined)
             throw new Error("option \"--mcp\" cannot be combined with option \"--output\"");
+        const { serve: serveMCP } = await import("./gradia-mcp.js");
         await serveMCP(pkg, { type: options.type, format: options.format, config });
         return;
     }

package/dst/gradia-mcp.js

@@ -16,7 +16,7 @@ import { Gradia, diagramTypes, diagramFormats, diagramFormatDefault } from "./gr
     arbitrary local WOFF2 files)  */
 const configOptions = Object.entries(configDefaults)
     .filter(([key]) => key !== "font-embed")
-    .map(([key, val]) => `  - "${key}" (${typeof val === "number" ? "number" : "string"}, default: ${JSON.stringify(val)})`)
+    .map(([key, val]) => `  - "${key}" (${typeof val}, default: ${JSON.stringify(val)})`)
     .join("\n");
 /*  the comprehensive description of the "gradia_render" tool, teaching
     the AI the complete input language and the available parameters  */
@@ -28,11 +28,37 @@ component relationships, data flows, dependency graphs, and similar structures.
 ## Diagram Types
 
 - "graph": a loosely grid-snapped layered layout of the whole graph. This is
-  the general-purpose type and the built-in default.
+  the general-purpose type and the built-in default. It accepts any topology,
+  including self-loops and free-standing nodes.
 - "hub": a hub graph, placing the single primary node (the node carrying the
   attribute "primary: true") in the center, its input nodes to the left and
-  its output nodes to the right.
-- "grid": a compact grid of tiles for an edge-less graph.
+  its output nodes to the right. It accepts only the constrained topology
+  described below.
+- "grid": a compact grid of tiles for an edge-less graph. The nodes are placed
+  in declaration order onto a roughly square, row-major grid.
+
+### Diagram Type Constraints
+
+The "hub" type rejects the input with an error unless all of the following
+conditions hold:
+
+- Exactly one node carries the attribute "primary: true".
+- Every edge either points to or originates from that primary node. An edge
+  between two non-primary nodes is rejected.
+- The primary node carries no self-loop.
+- Every non-primary node is an input or an output of the primary node, i.e.,
+  no node is free-standing.
+
+A node which is both an input and an output of the primary node is placed
+twice, once in the input column and once in the output column. The second
+placement is rendered as a dashed "ghost" box, colored by the
+"color-node-ghost-*" options.
+
+The "grid" type rejects the input with an error as soon as the graph contains
+at least one edge.
+
+The "graph" type imposes no such constraints and hence is the safe choice
+whenever the topology is not known to fit "hub" or "grid".
 
 ## Input Language
 
@@ -85,6 +111,10 @@ as <name>, terminals as "...", optional parts as [ ... ], repeatable parts as
 - A <string> cannot span lines. Inside it, "\\" escapes the following character.
 - A <directive> is a <comment> which occupies its entire line and starts with
   the keyword "#config" or "#type". All other comments are ignored.
+- Of multiple "#type" directives the last one wins, and a directive naming an
+  invalid type is silently ignored. A "#config" directive naming an unknown
+  option or carrying an invalid value is silently ignored, too, whereas the
+  same mistake in the "config" tool argument is rejected with an error.
 
 ### Semantic Rules
 
@@ -100,14 +130,20 @@ as <name>, terminals as "...", optional parts as [ ... ], repeatable parts as
   its cardinality label.
 - Four attribute keys are reserved and consumed by the renderer instead of being
   displayed as a regular "<key>: <val>" line:
-  - "url: <url>" renders the node box as a hyperlink,
+  - "url: <url>" renders the node box as a hyperlink. Only relative URLs and
+    the schemes "http", "https", and "mailto" are honored; any other URL is
+    silently dropped and the node box then simply stays unlinked,
   - "type: <name>" renders <name> as a smaller text above the node label,
   - "primary: true" renders the node in the primary node colors (and, for the
-    diagram type "hub", marks the single central hub node),
+    diagram type "hub", marks the single central hub node). The value has to
+    be the literal string "true",
   - "group: <name>" places the node into the surrounding group box <name>.
 - A node cannot be a member of more than one group. As soon as at least one node
   carries a "group" attribute, all nodes without one implicitly belong to the
   group "default", and every edge has to stay within a single group.
+- The groups are laid out individually with the selected diagram type and then
+  stacked vertically as decorated group boxes. For the type "hub" this means
+  that every single group needs its own primary node.
 - All remaining attributes are displayed as "<key>: <val>" lines inside the node
   box.
 
@@ -136,12 +172,37 @@ ${configOptions}
 
 The "size-*", "group-*", "graph-*", "hub-*", and "grid-*" options control the
 rendering geometry (canvas margin, node box sizing, edge routing, group box
-spacing, and the per-diagram-type layout) and take non-negative numbers. The
-"font-family" and "color-*" options are embedded into the generated SVG: when
-such an option is not explicitly configured, the SVG instead references the CSS
-custom property "--gradia-<option>" (definable by an embedding HTML document)
-and falls back to the built-in default. Leave them unset unless a particular
-look is explicitly requested.
+spacing, and the per-diagram-type layout) and take non-negative numbers, except
+the boolean "grid-node-width-equal", which forces all node boxes of a "grid"
+diagram to the width of the widest one.
+
+The "size-node-width-max" option additionally enables the word-wrapping of the
+node box texts: given a positive value, the node name, its type, and its
+attribute lines are greedily broken at whitespace, so that the node box stays
+within the given width and grows in height instead. This is the only way to
+produce multi-line node boxes. The default "0" disables the wrapping entirely
+and hence lets a node box become as wide as its longest text. A single word
+wider than the maximum is never broken and still widens the box beyond it.
+
+The "grid-columns-min" and "grid-columns-max" options control the column count
+of a "grid" diagram, which by default is derived from the node count as a
+roughly square grid: "grid-columns-min" (default 3) raises the derived count,
+so that a few nodes still share a single row instead of being stacked, while
+"grid-columns-max" (default 4) caps it, so that larger diagrams grow in height
+only. The column count never exceeds the node count and the maximum always
+wins over the minimum.
+
+The "font-family" and "color-*" options are embedded into the generated SVG:
+when such an option is not explicitly configured, the SVG instead references
+the CSS custom property "--gradia-<option>" (definable by an embedding HTML
+document) and falls back to the built-in default. Leave them unset unless a
+particular look is explicitly requested.
+
+The "font-family" option is either the built-in font family "Source Sans 3" or
+a plain font family name resolved by the displaying document. A path to a
+WOFF2 file is rejected in this context, exactly like the option "font-embed":
+both are available only through the (trusted) command-line options of the
+service.
 
 ## Result
 
@@ -149,6 +210,10 @@ The tool returns the rendered diagram as a single text result, in the requested
 output format. For the "svg:*" formats this is the SVG/XML document, which is
 usually written to a "*.svg" file; for the "url:*" formats it is a
 "data:image/svg+xml" URL, usable as the "src" of an HTML "<img>" element.
+
+On a malformed input, a violated diagram type constraint, or an invalid "config"
+argument, the tool instead returns an error result whose text starts with
+"gradia: ERROR: ", followed by the reason.
 `.trim();
 /*  the arguments of the "gradia_render" tool  */
 const toolArguments = {
@@ -176,11 +241,17 @@ const validateConfig = (raw) => {
         if (!Object.hasOwn(configDefaults, key))
             throw new Error(`unknown configuration option "${key}"`);
         const k = key;
-        if (typeof configDefaults[k] === "boolean")
+        if (k === "font-embed")
             throw new Error(`configuration option "${key}" is not available in this context`);
+        else if (typeof configDefaults[k] === "boolean") {
+            if (typeof val !== "boolean" && val !== "true" && val !== "false")
+                throw new Error(`invalid value "${String(val)}" for boolean configuration option "${key}" ` +
+                    "(expected \"true\" or \"false\")");
+            config[k] = typeof val === "boolean" ? val : val === "true";
+        }
         else if (typeof configDefaults[k] === "number") {
             const num = Number(val);
-            if (typeof val === "boolean" || !Number.isFinite(num) || num < 0)
+            if (typeof val === "boolean" || val === "" || !Number.isFinite(num) || num < 0)
                 throw new Error(`invalid value "${String(val)}" for numeric configuration option "${key}" ` +
                     "(expected a non-negative number)");
             config[k] = num;

package/package.json

@@ -3,7 +3,7 @@
     "description":                   "Object Graph Diagram Rendering",
     "keywords":                      [ "object", "graph", "diagram", "rendering", "svg", "layout", "api", "cli" ],
     "publishConfig":                 { "access": "public" },
-    "version":                       "0.9.8",
+    "version":                       "1.0.0",
     "license":                       "MIT",
     "author": {
         "name":                      "Dr. Ralf S. Engelschall",
@@ -26,7 +26,7 @@
     "dependencies": {
         "commander":                 "15.0.0",
         "@antv/layout":              "2.0.0",
-        "nanoid":                    "6.0.1",
+        "pure-uuid":                 "2.0.0",
         "source-sans":               "3.52.0",
         "@modelcontextprotocol/sdk": "1.30.0",
         "zod":                       "4.4.3"