@eriknaslund/skiss 0.4.0 → 0.6.0

package/README.md

@@ -41,6 +41,7 @@ Skiss is text you can type while someone talks. A field is one line. A change is
 - **What you leave out means "not yet".** Never "unknown", never "none". A sketch is silent about what you do not know.
 - **`@Catalog` says which system owns a thing.** On a class, or on a single field when the box is really a view over two systems.
 - **`~` and `=` are two different statements.** `~` says two classes are about the same thing. `=` says which field joins to which. The first is a domain conversation, the second an integration conversation.
+- **`<` inherits, once.** `Jedi < Character` on the class line: the child has everything the parent has and adds its own. One parent, no mixins; it compiles to `is_a`.
 - **`#` describes, `?` doubts.** A description ends up in generated documentation. A doubt never does.
 - **Every line stands on its own.** A half-typed line breaks that line and nothing else, so the diagram keeps rendering while you type.
 - **Everything you can write compiles to valid LinkML.** Skiss is a strict subset. Nothing is lost on the way up.
@@ -62,11 +63,15 @@ Or without installing: `npx @eriknaslund/skiss diagram model.skiss`.
 
 `skiss diagram` writes a Mermaid class diagram to standard output; `-o diagram.mmd` writes it to a file, `--notes` includes the `?` doubts as notes, and `-` reads standard input. Anything the file gets wrong is reported on standard error, one line each, and the diagram is still drawn from the lines that parse. `--strict` makes that a non-zero exit. `skiss --help` lists the rest.
 
+`skiss render model.skiss -o model.svg` writes a picture rather than the Mermaid text. A class diagram is laid out in a browser, so this one command needs a browser: it delegates to the official [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli), which you install yourself with `npm install -g @mermaid-js/mermaid-cli`. Nothing in the package or the library depends on it, and `skiss render` says that line and exits 2 when it is not there. The format is the extension of `-o` — `.svg` or `.png` — and `--format svg|png` overrides it; with no `-o` the SVG goes to standard output, and a PNG always needs an `-o`. `--scale` is what the PNG is rasterised at and defaults to 2; `--notes`, `--strict` and the diagnostics work as they do for `diagram`. When `mmdc` itself fails, its exit status is the command's.
+
 `skiss compile model.skiss` writes a LinkML schema instead, as YAML on standard output. `--json` writes the same schema as JSON, `--name` sets the schema name (it defaults to the file name without its extension, and to `sketch` when reading standard input), and `-o`, `-`, `--strict` and the diagnostics work exactly as they do for `diagram`.
 
-`skiss import schema.linkml.yaml` goes the other way: it reads a LinkML schema, YAML or JSON, and writes Skiss. What the projection could not carry — `is_a`, patterns, `required`, the names it had to convert — is one line on standard error before the diagnostics, because a sketch is a smaller language than LinkML and that line says by how much. `-o`, `-` and the diagnostics work as they do for `compile`; `--strict` exits 1 when the projected sketch has a diagnostic, and also when anything was dropped. An input that is not a schema at all — not YAML, or YAML no schema can be read out of — produces no sketch, says why on standard error, and exits 2, the code every command uses for unreadable input.
+`skiss import schema.linkml.yaml` goes the other way: it reads a LinkML schema, YAML or JSON, and writes Skiss. What the projection could not carry — patterns, `required`, `mixins`, the names it had to convert — is one line on standard error before the diagnostics, because a sketch is a smaller language than LinkML and that line says by how much. `-o`, `-` and the diagnostics work as they do for `compile`; `--strict` exits 1 when the projected sketch has a diagnostic, and also when anything was dropped. An input that is not a schema at all — not YAML, or YAML no schema can be read out of — produces no sketch, says why on standard error, and exits 2, the code every command uses for unreadable input.
+
+`npm install @eriknaslund/skiss` also gives you the library: `compile`, `formatDiagnostic`, `parse`, `resolve`, `toLinkML`, `serialize`, `toMermaid`, `toSkiss`, `fromLinkML`, `formatDropped`, `importLinkML`, `tokenizeLine` and `VERSION`, browser-safe.
 
-`npm install @eriknaslund/skiss` also gives you the library: `compile`, `formatDiagnostic`, `parse`, `resolve`, `toLinkML`, `serialize`, `toMermaid`, `toSkiss`, `fromLinkML`, `formatDropped`, `importLinkML` and `VERSION`, browser-safe.
+`tokenizeLine` is there for editors: it says where the words of one line are — `{ kind, from, to }` for each run of characters, so a host can colour them. It is line-based and stateless, as the language is: one line in, its tokens out, nothing carried from the line before, and nothing said about a run it does not recognise, so a half-typed line keeps the colours it has earned. It is not a parser and reports nothing; diagnostics stay `parse` and `resolve`'s ([ADR 0010](docs/adr/0010-tokeniser-in-the-package.md)).
 
 Editors that render Skiss live are separate projects built on this package. This repository is the language, the library and the command line.
 
@@ -84,9 +89,9 @@ Editors that render Skiss live are separate projects built on this package. This
 
 ## Status
 
-0.4.0, published on npm as [`@eriknaslund/skiss`](https://www.npmjs.com/package/@eriknaslund/skiss). The language parses, resolves and diagnoses; `skiss diagram` draws it, `skiss compile` writes LinkML that the real LinkML toolchain validates in CI, and `skiss import` reads a LinkML schema back into a sketch. The library exports the same in both directions and is browser-safe.
+0.6.0, published on npm as [`@eriknaslund/skiss`](https://www.npmjs.com/package/@eriknaslund/skiss). The language parses, resolves and diagnoses; `skiss diagram` draws it, `skiss compile` writes LinkML that the real LinkML toolchain validates in CI, and `skiss import` reads a LinkML schema back into a sketch. The library exports the same in both directions and is browser-safe.
 
-The [specification](docs/SPEC.md) is at 0.2 and moves when the language does, which is not with every release. Not built: inheritance, and editing a projected schema so that what Skiss cannot express survives the edit (SPEC §8.1). [CHANGELOG.md](CHANGELOG.md) is what changed when.
+The [specification](docs/SPEC.md) is at 0.3 and moves when the language does, which is not with every release. Not built: editing a projected schema so that what Skiss cannot express survives the edit (SPEC §8.1). [CHANGELOG.md](CHANGELOG.md) is what changed when.
 
 ## License
 

package/dist/cli.js

@@ -1,10 +1,92 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFile, writeFile } from "fs/promises";
-import { basename, extname } from "path";
+import { spawnSync } from "child_process";
+import { constants } from "fs";
+import { access, mkdtemp, readFile, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { basename, delimiter, extname, join } from "path";
 import { parseArgs } from "util";
 
+// src/inheritance.ts
+function inheritance(classes) {
+  const declared = /* @__PURE__ */ new Map();
+  for (const cls of classes) {
+    if (!declared.has(cls.name.text)) declared.set(cls.name.text, cls);
+  }
+  const circles = /* @__PURE__ */ new Map();
+  const parentOf = (cls) => {
+    if (cls.parent === void 0 || circles.has(cls)) return void 0;
+    return declared.get(cls.parent.text);
+  };
+  for (const cls of declared.values()) {
+    const path = [cls];
+    const seen = new Set(path);
+    for (let next = parentOf(cls); next !== void 0; next = parentOf(next)) {
+      if (seen.has(next)) {
+        const circle = path.slice(path.indexOf(next));
+        let closer = circle[0];
+        for (const member2 of circle) {
+          if (member2.line > closer.line) closer = member2;
+        }
+        const at = circle.indexOf(closer);
+        circles.set(closer, [...circle.slice(at), ...circle.slice(0, at)]);
+        break;
+      }
+      path.push(next);
+      seen.add(next);
+    }
+  }
+  const ancestors = (cls) => {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set([cls]);
+    for (let next = parentOf(cls); next !== void 0; next = parentOf(next)) {
+      if (seen.has(next)) break;
+      out.push(next);
+      seen.add(next);
+    }
+    return out;
+  };
+  const find = (cls, matches) => {
+    for (const from of ancestors(cls)) {
+      const field = from.fields.find(matches);
+      if (field !== void 0) return { field, from };
+    }
+    return void 0;
+  };
+  return {
+    ancestors,
+    inherited: (cls, fieldName) => find(cls, (field) => field.name.text === fieldName),
+    inheritedIdentifier: (cls) => find(cls, (field) => field.identifier),
+    circle: (cls) => circles.get(cls)
+  };
+}
+function sameField(child, inheritedField) {
+  return meaning(child) === meaning(inheritedField);
+}
+var meaning = (field) => JSON.stringify([
+  field.name.text,
+  field.identifier,
+  typeMeaning(field),
+  field.system?.text,
+  field.joinsTo === void 0 ? void 0 : [field.joinsTo.className.text, field.joinsTo.fieldName.text],
+  field.description,
+  field.note
+]);
+function typeMeaning(field) {
+  const type = field.type;
+  if (type === void 0) return void 0;
+  switch (type.kind) {
+    case "primitive":
+      return [type.kind, type.name, type.many];
+    case "class":
+    case "unknown":
+      return [type.kind, type.name.text, type.many];
+    case "enum":
+      return [type.kind, type.values.map((v) => v.text), type.many];
+  }
+}
+
 // src/parse.ts
 var isWs = (c) => c === " " || c === "	";
 var trimWs = (s) => s.replace(/^[ \t]+/, "").replace(/[ \t]+$/, "");
@@ -28,7 +110,7 @@ function primitiveFor(word) {
   return Object.hasOwn(PRIMITIVES, word) ? PRIMITIVES[word] : void 0;
 }
 var FIELD_ORDER = "name, `*`, `: type`, `@System`, `= Class.field`, then `#` and `?`";
-var CLASS_ORDER = "name, `@System`, `~ Class`, then `#` and `?`";
+var CLASS_ORDER = "name, `< Parent`, `@System`, `~ Class`, then `#` and `?`";
 function parse(source) {
   const classes = [];
   const diagnostics = [];
@@ -115,7 +197,11 @@ function splitTrailer(text) {
   return trailer;
 }
 var WORD = /[\p{L}\p{N}_-]+/uy;
-var OPERATORS = ["*", ":", "@", "~", "=", ".", "|", "["];
+function wordAt(text, i) {
+  WORD.lastIndex = i;
+  return WORD.exec(text)?.[0];
+}
+var OPERATORS = ["*", ":", "@", "~", "=", ".", "|", "<", ",", "["];
 function tokenize(head) {
   const tokens = [];
   let i = 0;
@@ -125,11 +211,10 @@ function tokenize(head) {
       i++;
       continue;
     }
-    WORD.lastIndex = i;
-    const word = WORD.exec(head);
-    if (word !== null) {
-      tokens.push({ kind: "word", text: word[0], col: i, end: i + word[0].length });
-      i += word[0].length;
+    const word = wordAt(head, i);
+    if (word !== void 0) {
+      tokens.push({ kind: "word", text: word, col: i, end: i + word.length });
+      i += word.length;
       continue;
     }
     if (c === "[" && head[i + 1] === "]") {
@@ -177,6 +262,13 @@ function parseClassLine(text, line) {
     );
   }
   const node = { name: name(head, line), line };
+  const lt = peek(c);
+  if (lt?.kind === "<") {
+    take(c);
+    const parent = parseParent(c, lt);
+    if (!parent.ok) return parent;
+    node.parent = parent.value;
+  }
   const at = peek(c);
   if (at?.kind === "@") {
     take(c);
@@ -306,6 +398,31 @@ function parseFieldLine(text, line) {
   if (trailer.note !== void 0) node.note = trailer.note;
   return { ok: true, value: node };
 }
+function parseParent(c, lt) {
+  const parent = take(c);
+  if (parent === void 0 || parent.kind !== "word") {
+    return fail(
+      "E_UNPARSABLE",
+      "Expected a class name after `<`, e.g. `Jedi < Character`",
+      c.line,
+      parent ?? afterSpan(lt)
+    );
+  }
+  if (!CLASS_NAME.test(parent.text)) {
+    const message = Object.hasOwn(PRIMITIVES, parent.text) ? `\`${parent.text}\` is a primitive, not a class; a parent is a class` : `The class after \`<\` must be UpperCamelCase: \`${parent.text}\``;
+    return fail("E_BAD_NAME", message, c.line, parent);
+  }
+  const next = peek(c);
+  if (next?.kind === "," || next?.kind === "<") {
+    return fail(
+      "E_UNPARSABLE",
+      "A class has one parent; `<` takes a single class name",
+      c.line,
+      next
+    );
+  }
+  return { ok: true, value: name(parent, c.line) };
+}
 function parseSystem(c, at) {
   const system = take(c);
   if (system === void 0 || system.kind !== "word") {
@@ -415,7 +532,7 @@ function parseType(c, colon) {
   );
 }
 function unexpected(token, line, kind, order) {
-  const modifiers = kind === "field" ? ["*", ":", "@", "="] : ["@", "~"];
+  const modifiers = kind === "field" ? ["*", ":", "@", "="] : ["<", "@", "~"];
   if (modifiers.includes(token.kind)) {
     return fail(
       "E_UNPARSABLE",
@@ -424,10 +541,10 @@ function unexpected(token, line, kind, order) {
       token
     );
   }
-  if (token.text === "<") {
+  if (token.kind === "<") {
     return fail(
       "E_UNPARSABLE",
-      "`<` is reserved for inheritance and not yet part of the language",
+      "`<` marks inheritance and belongs on the class line: `Child < Parent`",
       line,
       token
     );
@@ -456,10 +573,14 @@ function resolve(doc) {
   };
   const classes = out.classes;
   const declared = new Set(classes.map((c) => c.name.text));
-  const warnings = [];
+  const found = [];
   const undeclared = /* @__PURE__ */ new Map();
+  const tree = inheritance(classes);
   const warn = (code, message, at) => {
-    warnings.push({ severity: "warning", code, message, line: at.line, col: at.col, end: at.end });
+    found.push({ severity: "warning", code, message, line: at.line, col: at.col, end: at.end });
+  };
+  const error = (code, message, at) => {
+    found.push({ severity: "error", code, message, line: at.line, col: at.col, end: at.end });
   };
   const reference = (name2) => {
     if (declared.has(name2.text)) return true;
@@ -480,9 +601,25 @@ function resolve(doc) {
         cls.name
       );
     }
+    const parent = cls.parent;
+    if (parent !== void 0) {
+      reference(parent);
+      const circle = tree.circle(cls);
+      if (circle !== void 0) {
+        const through = circle.slice(1).map((member2) => `\`${member2.name.text}\``);
+        const path = through.length === 0 ? "" : ` through ${through.join(", ")}`;
+        error(
+          "E_INHERITANCE_CYCLE",
+          `class \`${cls.name.text}\` inherits from itself${path}; this \`<\` is not carried`,
+          parent
+        );
+        cls.parent = void 0;
+      }
+    }
     if (cls.similarTo !== void 0) reference(cls.similarTo);
     const firstField = /* @__PURE__ */ new Map();
-    let identifier;
+    const inheritedIdentifier = tree.inheritedIdentifier(cls);
+    let identifier = inheritedIdentifier?.field;
     for (const field of cls.fields) {
       const earlierField = firstField.get(field.name.text);
       if (earlierField === void 0) firstField.set(field.name.text, field);
@@ -496,14 +633,23 @@ function resolve(doc) {
       if (field.identifier) {
         if (identifier === void 0) identifier = field;
         else {
+          const from = identifier === inheritedIdentifier?.field ? ` inherits the identifier \`${identifier.name.text}\` from class \`${inheritedIdentifier.from.name.text}\`, line` : ` already has the identifier \`${identifier.name.text}\` on line`;
           warn(
             "W_MULTIPLE_IDENTIFIERS",
-            `\`*\` on \`${field.name.text}\` is ignored: class \`${cls.name.text}\` already has the identifier \`${identifier.name.text}\` on line ${identifier.line}`,
+            `\`*\` on \`${field.name.text}\` is ignored: class \`${cls.name.text}\`${from} ${identifier.line}`,
             field.identifierAt ?? field.name
           );
           field.identifier = false;
         }
       }
+      const replaced = tree.inherited(cls, field.name.text);
+      if (replaced !== void 0 && sameField(field, replaced.field)) {
+        warn(
+          "W_REDUNDANT_OVERRIDE",
+          `field \`${field.name.text}\` is identical to the one inherited from class \`${replaced.from.name.text}\` on line ${replaced.field.line}`,
+          field.name
+        );
+      }
       if (field.type?.kind === "unknown") {
         const word = field.type.name.text;
         const suggestion = closestTypeWord(word);
@@ -541,8 +687,8 @@ function resolve(doc) {
     }
   }
   const present2 = new Set(out.diagnostics.map(key));
-  for (const w of warnings) {
-    if (!present2.has(key(w))) out.diagnostics.push(w);
+  for (const d of found) {
+    if (!present2.has(key(d))) out.diagnostics.push(d);
   }
   out.diagnostics.sort((a, b) => a.line - b.line);
   out.undeclared = [...undeclared.values()].map((n) => ({ ...n }));
@@ -573,6 +719,7 @@ function copyField(f) {
 }
 function copyClass(c) {
   const out = { ...c, name: copyName(c.name), fields: c.fields.map(copyField) };
+  if (c.parent !== void 0) out.parent = copyName(c.parent);
   if (c.system !== void 0) out.system = copyName(c.system);
   if (c.similarTo !== void 0) out.similarTo = copyName(c.similarTo);
   return out;
@@ -751,6 +898,7 @@ function buildClass(cls, mappingPrefix, enums) {
   const { node, fields } = cls;
   const out = {};
   if (node.description !== void 0) out.description = node.description;
+  if (node.parent !== void 0) out.is_a = node.parent.text;
   const annotations = {};
   if (node.system !== void 0) annotations.system = node.system.text;
   if (node.note !== void 0) annotations.note = node.note;
@@ -833,6 +981,7 @@ function toMermaid(doc, opts) {
   }
   for (const cls of resolved.classes) {
     const from = cls.name.text;
+    if (cls.parent !== void 0) lines.push(`  ${cls.parent.text} <|-- ${from}`);
     if (cls.similarTo !== void 0) lines.push(`  ${from} ..> ${cls.similarTo.text} : similar`);
     for (const field of cls.fields) {
       const type = field.type;
@@ -939,7 +1088,7 @@ function toSkiss(doc) {
 `;
 }
 function classBlock(cls) {
-  const head = cls.name.text + (cls.system === void 0 ? "" : ` @${cls.system.text}`) + (cls.similarTo === void 0 ? "" : ` ~ ${cls.similarTo.text}`);
+  const head = cls.name.text + (cls.parent === void 0 ? "" : ` < ${cls.parent.text}`) + (cls.system === void 0 ? "" : ` @${cls.system.text}`) + (cls.similarTo === void 0 ? "" : ` ~ ${cls.similarTo.text}`);
   return [withTrailer(head, cls), ...cls.fields.map(fieldLine)].join("\n");
 }
 function fieldLine(field) {
@@ -993,7 +1142,14 @@ var PRIMITIVE_RANGE = {
   uri: "uri",
   uriorcurie: "uri"
 };
-var CLASS_KEYS = /* @__PURE__ */ new Set(["description", "annotations", "close_mappings", "attributes", "slots"]);
+var CLASS_KEYS = /* @__PURE__ */ new Set([
+  "description",
+  "is_a",
+  "annotations",
+  "close_mappings",
+  "attributes",
+  "slots"
+]);
 var SLOT_KEYS = /* @__PURE__ */ new Set(["description", "annotations", "range", "multivalued", "identifier"]);
 var CLASS_TAGS = /* @__PURE__ */ new Set(["system", "note", "undeclared"]);
 var SLOT_TAGS = /* @__PURE__ */ new Set(["system", "note", "joins_to"]);
@@ -1036,7 +1192,7 @@ function fromLinkML(schema) {
   for (const key2 of Object.keys(classDefs)) {
     const names = /* @__PURE__ */ new Map();
     const taken = /* @__PURE__ */ new Set();
-    for (const slot of slotKeysOf(asRecord(get(classDefs, key2)) ?? {})) {
+    for (const slot of fieldKeysOf(key2)) {
       names.set(slot, unique(toFieldName(slot), taken));
     }
     fieldNames.set(key2, names);
@@ -1106,6 +1262,12 @@ function fromLinkML(schema) {
       const note = oneLine(rawNote);
       if (note !== void 0) node.note = note;
     } else if (rawNote !== void 0) report("annotation", name2, notText("note", rawNote));
+    const parent = stringOf(get(def, "is_a"));
+    if (parent !== void 0) {
+      const parentName = Object.hasOwn(classDefs, parent) ? classNameOf(parent) : toClassName(parent);
+      node.parent = at0(parentName);
+      reference(name2, parent, parentName);
+    }
     const mappings = stringList(get(def, "close_mappings"));
     const first = mappings[0];
     const target = first === void 0 ? "" : localName(first);
@@ -1128,6 +1290,9 @@ function fromLinkML(schema) {
           }
         }
         const block = get(def, other);
+        if (other === "is_a" && present(block) && stringOf(block) === void 0) {
+          report("is_a", name2, `${shown(block)} is not a class name`);
+        }
         if (other === "attributes" && present(block) && asRecord(block) === void 0) {
           report("attributes", name2, `${shown(block)} is not a map`);
         }
@@ -1142,10 +1307,12 @@ function fromLinkML(schema) {
           report("slot_usage", name2);
           continue;
         }
+        const written = slotKeysOf(def);
+        const inherited = inheritedSlots(key2);
         for (const slot of Object.keys(usage)) {
-          if (fieldNames.get(key2)?.has(slot) === true) {
+          if (written.includes(slot)) {
             report("slot_usage", `${name2}.${fieldNameOf(key2, slot)}`);
-          } else {
+          } else if (!inherited.has(slot)) {
             report("slot_usage", name2, `\`${slot}\` is inherited and not in the sketch`);
           }
         }
@@ -1153,9 +1320,10 @@ function fromLinkML(schema) {
       }
       report(other, name2);
     }
-    for (const slot of slotKeysOf(def)) {
+    const own = slotKeysOf(def);
+    for (const slot of fieldKeysOf(key2)) {
       const attributes = asRecord(get(def, "attributes")) ?? {};
-      const rawSlot = Object.hasOwn(attributes, slot) ? get(attributes, slot) : get(slotDefs, slot);
+      const rawSlot = !own.includes(slot) ? get(asRecord(get(def, "slot_usage")) ?? {}, slot) : Object.hasOwn(attributes, slot) ? get(attributes, slot) : get(slotDefs, slot);
       const slotDef = asRecord(rawSlot);
       if (slotDef === void 0 && present(rawSlot)) {
         report("slot", `${name2}.${fieldNameOf(key2, slot)}`, "is not a slot definition");
@@ -1292,6 +1460,34 @@ function fromLinkML(schema) {
     report("narrowed", element, `\`${range}\` is not a Skiss type; it falls back to string`);
     return { kind: "unknown", name: at0(word), many };
   }
+  function parentKeyOf(classKey) {
+    const def = asRecord(get(classDefs, classKey)) ?? {};
+    const parent = stringOf(get(def, "is_a"));
+    if (parent === void 0 || !Object.hasOwn(classDefs, parent)) return void 0;
+    return parent;
+  }
+  function inheritedSlots(classKey) {
+    const out = /* @__PURE__ */ new Set();
+    const seen = /* @__PURE__ */ new Set([classKey]);
+    let key2 = parentKeyOf(classKey);
+    while (key2 !== void 0 && !seen.has(key2)) {
+      seen.add(key2);
+      for (const slot of slotKeysOf(asRecord(get(classDefs, key2)) ?? {})) out.add(slot);
+      key2 = parentKeyOf(key2);
+    }
+    return out;
+  }
+  function fieldKeysOf(classKey) {
+    const def = asRecord(get(classDefs, classKey)) ?? {};
+    const keys = slotKeysOf(def);
+    const usage = asRecord(get(def, "slot_usage"));
+    if (usage === void 0) return keys;
+    const inherited = inheritedSlots(classKey);
+    for (const slot of Object.keys(usage)) {
+      if (inherited.has(slot) && !keys.includes(slot)) keys.push(slot);
+    }
+    return keys;
+  }
   function listedSomewhere(slot) {
     for (const key2 of Object.keys(classDefs)) {
       const def = asRecord(get(classDefs, key2)) ?? {};
@@ -1474,7 +1670,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.4.0";
+var VERSION = "0.6.0";
 
 // src/cli.ts
 var HELP = `Usage: skiss <command> [options]
@@ -1483,15 +1679,22 @@ Commands:
   diagram <file>       Write a Mermaid class diagram for a .skiss file.
   compile <file>       Write a LinkML schema for a .skiss file.
   import <file>        Write Skiss for a LinkML schema file, YAML or JSON.
+  render <file>        Write an SVG or a PNG of the class diagram, through
+                       the Mermaid CLI (mmdc), which must be installed.
                        <file> may be - to read standard input.
 
 Options:
   -o, --output <path>  Write the output to <path> instead of standard output
-      --notes          diagram: emit \`? text\` doubts as Mermaid notes
+      --notes          diagram, render: emit \`? text\` doubts as Mermaid notes
       --json           compile: write the schema as JSON instead of YAML
       --name <name>    compile: the schema name. Defaults to the file's
                        basename without its extension, or \`sketch\` for
                        standard input.
+      --format <fmt>   render: svg or png. Defaults to the extension of
+                       -o, and to svg when there is no -o. png needs an -o:
+                       only the SVG can go to standard output.
+      --scale <n>      render: the scale mmdc rasterises at. Defaults to 2
+                       for png, and to mmdc's own default for svg.
       --strict         Exit 1 when the input has any diagnostic; for import,
                        also when the projection dropped anything
   -h, --help           Show this help and exit
@@ -1508,8 +1711,11 @@ Exit codes:
   0  the output was produced
   1  --strict and the input has diagnostics (the output is still written)
   2  usage error, missing file, or unreadable input: for import, a text no
-     schema could be read out of, which produces no sketch at all
+     schema could be read out of, which produces no sketch at all; for
+     render, the Mermaid CLI not being installed
   70 internal error, a bug in skiss
+
+render exits with mmdc's own status when mmdc ran and failed.
 `;
 var EXIT_OK = 0;
 var EXIT_STRICT = 1;
@@ -1518,7 +1724,8 @@ var EXIT_INTERNAL = 70;
 var COMMANDS = {
   diagram: ["output", "notes", "strict"],
   compile: ["output", "json", "name", "strict"],
-  import: ["output", "strict"]
+  import: ["output", "strict"],
+  render: ["output", "notes", "format", "scale", "strict"]
 };
 var isCommand = (text) => Object.hasOwn(COMMANDS, text);
 var UsageError = class extends Error {
@@ -1540,6 +1747,8 @@ async function main(argv) {
       notes: { type: "boolean" },
       json: { type: "boolean" },
       name: { type: "string" },
+      format: { type: "string" },
+      scale: { type: "string" },
       strict: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean" }
@@ -1569,8 +1778,16 @@ async function main(argv) {
     }
   }
   const source = file === "-" ? await readStdin() : await readSource(file);
-  const { output, diagnostics, dropped } = runCommand(command, source, file, values);
   const label = file === "-" ? "<stdin>" : file;
+  if (command === "render") {
+    const picture = compile(source, { target: "mermaid", notes: values.notes });
+    for (const d of picture.diagnostics) process.stderr.write(`${formatDiagnostic(d, label)}
+`);
+    const status = await render(picture.output, values);
+    if (status !== EXIT_OK) return status;
+    return values.strict === true && picture.diagnostics.length > 0 ? EXIT_STRICT : EXIT_OK;
+  }
+  const { output, diagnostics, dropped } = runCommand(command, source, file, values);
   const report = formatDropped(dropped);
   if (report !== "") process.stderr.write(`${report}
 `);
@@ -1625,6 +1842,76 @@ async function writeOutput(path, text) {
     throw new UsageError(`cannot write \`${path}\`: ${reason(error)}`);
   }
 }
+var MMDC_MISSING = "skiss render needs the Mermaid CLI: npm install -g @mermaid-js/mermaid-cli";
+var isFormat = (text) => text === "svg" || text === "png";
+async function render(mermaid, values) {
+  const format = renderFormat(values);
+  const scale = renderScale(values.scale, format);
+  const mmdc = await findMmdc();
+  if (mmdc === void 0) {
+    process.stderr.write(`${MMDC_MISSING}
+`);
+    return EXIT_USAGE;
+  }
+  const dir = await mkdtemp(join(tmpdir(), "skiss-render-"));
+  try {
+    const input = join(dir, "diagram.mmd");
+    await writeFile(input, mermaid, "utf8");
+    const target = values.output ?? join(dir, `diagram.${format}`);
+    const args = ["-i", input, "-o", target, "-e", format, "-b", "transparent"];
+    if (scale !== void 0) args.push("--scale", scale);
+    const run = spawnSync(mmdc, args, {
+      stdio: ["ignore", "pipe", "inherit"],
+      encoding: "utf8"
+    });
+    if (run.error !== void 0)
+      throw new UsageError(`cannot run \`${mmdc}\`: ${reason(run.error)}`);
+    if (run.stdout !== "") process.stderr.write(run.stdout);
+    if (run.status !== EXIT_OK) return run.status ?? EXIT_INTERNAL;
+    if (values.output === void 0) process.stdout.write(await readFile(target, "utf8"));
+    return EXIT_OK;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+function renderFormat(values) {
+  if (values.format !== void 0) {
+    if (!isFormat(values.format)) {
+      throw new UsageError(`unknown \`--format ${values.format}\`: svg or png`);
+    }
+    if (values.format === "png" && values.output === void 0) {
+      throw new UsageError(
+        "render --format png needs -o <path>: a PNG cannot go to standard output"
+      );
+    }
+    return values.format;
+  }
+  if (values.output === void 0) return "svg";
+  const extension = extname(values.output).slice(1).toLowerCase();
+  if (isFormat(extension)) return extension;
+  throw new UsageError(
+    `cannot tell the format of \`${values.output}\`: give --format svg or --format png`
+  );
+}
+function renderScale(scale, format) {
+  if (scale === void 0) return format === "png" ? "2" : void 0;
+  const value = Number(scale);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new UsageError(`\`--scale ${scale}\` is not a positive number`);
+  }
+  return scale;
+}
+async function findMmdc() {
+  const onPath = (process.env.PATH ?? "").split(delimiter).filter((dir) => dir !== "").map((dir) => join(dir, "mmdc"));
+  for (const candidate of [...onPath, join(process.cwd(), "node_modules", ".bin", "mmdc")]) {
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
 function reason(error) {
   if (error instanceof Error) {
     const code = error.code;