@rse/gradia 1.1.9 → 1.2.1

package/dst/gradia-cli.js

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 /*  external dependencies  */
 import { Command, Option } from "commander";
 /*  internal dependencies  */
-import { configDefaults } from "./gradia-api-config.js";
+import { validateConfig } from "./gradia-api-config.js";
 import { Gradia, diagramTypes, diagramTypeDefault, diagramFormats, diagramFormatDefault } from "./gradia-api.js";
 /*  internal package meta-information  */
 const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
@@ -30,31 +30,14 @@ program.name("gradia")
     .argument("[input]", "input graph description file (omitted in MCP service mode)")
     .action(async (input, options) => {
     /*  parse and validate the rendering configuration options  */
-    const config = {};
-    const store = config;
+    const store = {};
     for (const nv of options.config) {
         const m = /^([a-z][a-z0-9-]*)=(.*)$/.exec(nv);
         if (m === null)
             throw new Error(`invalid configuration option "${nv}" (expected "<name>=<value>")`);
-        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")`);
-            store[key] = m[2] === "true";
-        }
-        else if (typeof configDefaults[key] === "number") {
-            const num = Number(m[2]);
-            if (m[2] === "" || !Number.isFinite(num) || num < 0)
-                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];
+        store[m[1]] = m[2];
     }
+    const config = validateConfig(store, { trusted: true });
     /*  optionally run as an MCP service instead of rendering once,
         with the command-line options acting as the defaults of the
         tool calls (and hence being the only trusted source of the

package/dst/gradia-mcp.js

@@ -8,8 +8,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 /*  internal dependencies  */
-import { configDefaults } from "./gradia-api-config.js";
-import { Gradia, diagramTypes, diagramFormats, diagramFormatDefault } from "./gradia-api.js";
+import { configDefaults, validateConfig } from "./gradia-api-config.js";
+import { Gradia, diagramTypes, diagramTypeDefault, diagramFormats, diagramFormatDefault } from "./gradia-api.js";
 /*  the rendering configuration options offered to the MCP client
     ("font-embed" is intentionally omitted, as the arguments of a tool
     call are treated as untrusted and it would allow the reading of
@@ -128,8 +128,8 @@ as <name>, terminals as "...", optional parts as [ ... ], repeatable parts as
   following node, i.e., the chain is equivalent to "a --> b" and "b --> c".
 - The <edge-name> is rendered as the label of the edge and the <edge-arity> as
   its cardinality label.
-- Four attribute keys are reserved and consumed by the renderer instead of being
-  displayed as a regular "<key>: <val>" line:
+- Seven 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. 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,
@@ -137,13 +137,47 @@ as <name>, terminals as "...", optional parts as [ ... ], repeatable parts as
   - "primary: true" renders the node in the primary node colors (and, for the
     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>.
+  - "group: <name>" places the node into the surrounding group box <name>,
+  - "parent: <id>" nests the node into the container node <id> (a node which
+    is implicitly declared if never referenced otherwise),
+  - "container: <type>" marks the node as a container whose members are laid
+    out with the diagram type <type> ("graph", "hub", or "grid"), even if it
+    has no members at all,
+  - "order: <number>" places the node explicitly (see below).
+- A "graph" (a "graph" container level, too) with at least one node carrying an
+  "order" attribute is laid out in that explicit order instead of by the layered
+  algorithm: the distinct order values become the rows, top-down in ascending
+  order, the nodes of one value fill their row left-to-right in declaration
+  order (wrapped into further rows beyond "graph-columns-max" nodes), and the
+  nodes without an order follow in the trailing rows. A "grid" places its tiles
+  in the order of the attribute, too, the tiles without one trailing. Use it to
+  impose a reading order (e.g. the order of a document), which lets every
+  reference to an earlier item point upward or leftward.
 - 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.
+  group "default", and every edge has to stay within a single group. A nested
+  node belongs to the group of its outermost container.
 - 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.
+- A node referenced as the "parent" of another node is a container: it is
+  rendered as a dashed grey box surrounding its members instead of as a node
+  box, with its label, "type", and "url" in the box head (its remaining
+  attributes are not rendered). Containers nest to any depth, but a node cannot
+  be a member of more than one container, and cannot be nested into itself.
+- The members of a container are laid out as a diagram of their own, with the
+  diagram type of the enclosing level unless overridden by "container: <type>",
+  and the container then takes part in the layout of the enclosing level as a
+  single box. Edges may connect any two nodes, across container boundaries and
+  to container nodes themselves, except a container with one of its own
+  members. An edge crossing the boundary of a container laid out as "graph" is
+  routed through the box border to the inner node (entering on the west and
+  leaving on the east side), while an edge crossing the boundary of a container
+  laid out as "hub" or "grid" ends at the box border instead. The diagram type
+  constraints apply to every container level (e.g., a "hub" container needs its
+  own primary node, and a "grid" container permits no edges among its members).
+- Use containers (not groups) to visualize zones, tiers, deployment units, or
+  packages whose members are connected to the outside world.
 - All remaining attributes are displayed as "<key>: <val>" lines inside the node
   box.
 
@@ -155,8 +189,9 @@ as <name>, terminals as "...", optional parts as [ ... ], repeatable parts as
     #config color-edge-line         #999999
 
     Animal: animal [ type: "abstract class", kind: base, url: "#animal", primary: true ]
-    Dog: dog
-    Cat: cat
+    Dog: dog [ parent: Pets ]
+    Cat: cat [ parent: Pets ]
+    Pets: "Domestic Pets" [ type: package ]
 
     Dog --(isa)--> Animal
     Cat --(isa)--> Animal
@@ -170,11 +205,11 @@ over them. The recognized options, with their types and built-in defaults, are:
 
 ${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, 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-*", "group-*", "container-*", "graph-*", "hub-*", and "grid-*" options
+control the rendering geometry (canvas margin, node box sizing, edge routing,
+group and container box 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
@@ -215,57 +250,26 @@ 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 = {
+/*  the arguments of the "gradia_render" tool (with their descriptions
+    reflecting the service defaults underlying the arguments)  */
+const toolArgumentsOf = (defaults) => ({
     input: z.string()
         .describe("The graph description in the Gradia input language (see the tool description for its grammar)."),
     type: z.enum(diagramTypes).optional()
         .describe("The diagram type. Takes precedence over a \"#type\" directive inside the input. " +
-        "Defaults to the \"#type\" directive of the input, else to \"graph\"."),
+        (defaults.type !== undefined ?
+            `Defaults to "${defaults.type}".` :
+            `Defaults to the "#type" directive of the input, else to "${diagramTypeDefault}".`)),
     format: z.enum(diagramFormats).optional()
         .describe("The output format: \"svg:standalone\" (a standalone SVG/XML document), " +
         "\"svg:embedded\" (the SVG without the \"<?xml?>\" declaration, for embedding into HTML), " +
         "\"url:xml\" (a \"data:image/svg+xml\" URL with URL-encoded XML), or " +
         "\"url:base64\" (a \"data:image/svg+xml\" URL with Base64-encoded XML). " +
-        `Defaults to "${diagramFormatDefault}".`),
+        `Defaults to "${defaults.format ?? diagramFormatDefault}".`),
     config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
         .describe("The rendering configuration options (see the tool description for their names, " +
         "types, and defaults). Takes precedence over the \"#config\" directives inside the input.")
-};
-/*  validate and coerce the rendering configuration options of a tool
-    call (the arguments are treated as untrusted, so an unknown option
-    or an invalid value is rejected instead of being silently applied)  */
-const validateConfig = (raw) => {
-    const config = {};
-    for (const [key, val] of Object.entries(raw)) {
-        if (!Object.hasOwn(configDefaults, key))
-            throw new Error(`unknown configuration option "${key}"`);
-        const k = key;
-        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" || 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;
-        }
-        else {
-            if (typeof val !== "string")
-                throw new Error(`invalid value "${String(val)}" for string configuration option "${key}" (expected a string)`);
-            if (k === "font-family" && val.endsWith(".woff2"))
-                throw new Error("configuration option \"font-family\" must not be the path to a WOFF2 file in this context");
-            config[k] = val;
-        }
-    }
-    return config;
-};
+});
 /*  run the MCP service on stdio  */
 export const serve = async (meta, defaults = {}) => {
     /*  establish the MCP server and its single tool  */
@@ -277,11 +281,11 @@ export const serve = async (meta, defaults = {}) => {
     server.registerTool("gradia_render", {
         title: "Render an object graph as an SVG diagram",
         description: toolDescription,
-        inputSchema: toolArguments,
+        inputSchema: toolArgumentsOf(defaults),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     }, async (args) => {
         try {
-            const config = { ...defaults.config, ...validateConfig(args.config ?? {}) };
+            const config = { ...defaults.config, ...validateConfig(args.config ?? {}, { trusted: false }) };
             const out = await Gradia.render(args.input, {
                 type: args.type ?? defaults.type,
                 format: args.format ?? defaults.format,

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":                       "1.1.9",
+    "version":                       "1.2.1",
     "license":                       "MIT",
     "author": {
         "name":                      "Dr. Ralf S. Engelschall",