@eriknaslund/skiss 0.7.0 → 0.8.0

package/README.md

@@ -46,7 +46,7 @@ Skiss is text you can type while someone talks. A field is one line. A change is
 - **`@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.
+- **`#` describes, `?` doubts.** A description ends up in generated documentation. A doubt never does. A description too long for the line continues on indented `#` lines under it, and the `#` block at the top of the file describes the whole sketch.
 - **Names are ASCII.** `A`–`Z`, `a`–`z`, `0`–`9`, and nothing else: a name becomes an identifier and a URI in LinkML, a class in generated Python, a node in a diagram, and none of those take the rest of the alphabet. The words of the domain, in whatever alphabet they are spoken, go in the `#` description ([SPEC §4](docs/SPEC.md#4-grammar)).
 - **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.
@@ -72,9 +72,26 @@ Or without installing: `npx @eriknaslund/skiss diagram model.skiss`.
 
 `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 glossary model.skiss` writes what the sketch says about the words in it, as Markdown: one section per class, with its fields in a table and the `#` descriptions as the definitions. A sketch is where each thing is named, so the terminology page is generated from it rather than kept beside it and allowed to drift.
+
+```
+# A build and release pipeline
+
+## Environment
+
+System: Platform. One installation of the platform, with its own data.
+
+| Field | Type | Description |
+|---|---|---|
+| id | identifier | |
+| purpose | build / test / playtest / live | |
+```
+
+`--classes` writes the terms alone, as a `| Term | Definition |` table, which is the shape a glossary page usually wants; `--notes` adds the `? ` doubts as open questions, which nothing else in the output shows, because a doubt is never documentation. `--name` is the heading, and `-o`, `-`, `--strict` and the diagnostics work exactly as they do for `compile`.
+
 `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`, `toGlossary`, `toSkiss`, `fromLinkML`, `formatDropped`, `importLinkML`, `tokenizeLine` 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)).
 
@@ -94,9 +111,9 @@ Editors that render Skiss live are separate projects built on this package. This
 
 ## Status
 
-0.7.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.8.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.3.1 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.
+The [specification](docs/SPEC.md) is at 0.4.0 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

@@ -127,19 +127,47 @@ function primitiveFor(word) {
 var DROPPED = "dropped-class";
 var FIELD_ORDER = "name, `*`, `: type`, `@System`, `= Class.field`, then `#` and `?`";
 var CLASS_ORDER = "name, `< Parent`, `@System`, `~ Class`, then `#` and `?`";
+var NO_ELEMENT_ABOVE = "A description line needs a class or a field above it";
 function parse(source) {
   const classes = [];
   const diagnostics = [];
   let current;
+  let target;
+  const header = [];
+  let inHeader = true;
   const text0 = source.startsWith("\uFEFF") ? source.slice(1) : source;
   const lines = text0.split(/\r\n|\n|\r/);
   for (let i = 0; i < lines.length; i++) {
     const line = i + 1;
     const text = (lines[i] ?? "").replace(/[ \t]+$/, "");
     const first = text[0];
-    if (first === void 0 || first === "#") continue;
+    if (first === void 0) {
+      inHeader = false;
+      continue;
+    }
+    if (first === "#") {
+      if (inHeader) header.push(headerLine(text));
+      continue;
+    }
+    inHeader = false;
     if (isWs(first)) {
       const start = text.search(/[^ \t]/);
+      if (text[start] === "#" || isDoubtMarker(text, start)) {
+        if (current === DROPPED) continue;
+        if (target === void 0) {
+          diagnostics.push({
+            severity: "error",
+            code: "E_UNPARSABLE",
+            message: NO_ELEMENT_ABOVE,
+            line,
+            col: start,
+            end: text.length
+          });
+          continue;
+        }
+        continueTrailer(target, splitTrailer(text));
+        continue;
+      }
       if (current === void 0) {
         diagnostics.push({
           severity: "error",
@@ -153,7 +181,10 @@ function parse(source) {
       }
       const result = parseFieldLine(text, line);
       if (!result.ok) diagnostics.push(result.diagnostic);
-      else if (current !== DROPPED) current.fields.push(result.value);
+      else if (current !== DROPPED) {
+        current.fields.push(result.value);
+        target = result.value;
+      }
       continue;
     }
     if (/\p{L}/u.test(first)) {
@@ -161,9 +192,11 @@ function parse(source) {
       if (result.ok) {
         classes.push(result.value);
         current = result.value;
+        target = result.value;
       } else {
         diagnostics.push(result.diagnostic);
         current = result.atName ? DROPPED : void 0;
+        target = void 0;
       }
       continue;
     }
@@ -176,7 +209,14 @@ function parse(source) {
       end: text.length
     });
   }
-  return { classes, diagnostics };
+  const document = { classes, diagnostics };
+  const description = header.filter((part) => part !== "").join(" ");
+  if (description !== "") document.description = description;
+  return document;
+}
+function headerLine(text) {
+  const rest = text.slice(1);
+  return isWs(rest[0]) ? rest.slice(1) : rest;
 }
 function isDoubtMarker(text, i) {
   return text[i] === "?" && isWs(text[i - 1]) && (i + 1 === text.length || isWs(text[i + 1]));
@@ -212,6 +252,15 @@ function splitTrailer(text) {
   }
   return trailer;
 }
+function continueTrailer(node, trailer) {
+  if (trailer.description !== void 0) {
+    node.description = node.description === void 0 ? trailer.description : `${node.description} ${trailer.description}`;
+  }
+  if (trailer.note !== void 0) {
+    node.note = node.note === void 0 ? trailer.note : `${node.note}
+${trailer.note}`;
+  }
+}
 var WORD = /[\p{L}\p{N}_-]+/uy;
 function wordAt(text, i) {
   WORD.lastIndex = i;
@@ -332,8 +381,10 @@ function parseFieldLine(text, line) {
   const head = take(c);
   if (head === void 0) {
     const col = text.search(/[^ \t]/);
-    const message = text[col] === "#" ? "A `#` comment must start at column 0; an indented line is a field and needs a name" : "A field line needs a field name before its trailer";
-    return fail("E_UNPARSABLE", message, line, { col, end: Math.max(col + 1, text.length) });
+    return fail("E_UNPARSABLE", "A field line needs a field name before its trailer", line, {
+      col,
+      end: Math.max(col + 1, text.length)
+    });
   }
   if (head.kind !== "word") return unexpected(head, line, "field", FIELD_ORDER);
   if (!FIELD_NAME.test(head.text)) {
@@ -793,6 +844,109 @@ function levenshtein(a, b) {
   return previous[b.length] ?? 0;
 }
 
+// src/generators/glossary.ts
+var DEFAULT_NAME = "Glossary";
+function toGlossary(doc, opts) {
+  const resolved = resolve(doc);
+  const notes = opts?.notes === true;
+  const declared = new Set(resolved.classes.map((cls) => cls.name.text));
+  const blocks = [`# ${opts?.name ?? DEFAULT_NAME}`];
+  const description = resolved.description;
+  if (description !== void 0 && description !== "") blocks.push(description);
+  if (opts?.classes === true) blocks.push(termTable(resolved.classes, notes));
+  else for (const cls of resolved.classes) blocks.push(...section(cls, declared, notes));
+  return `${blocks.join("\n\n")}
+`;
+}
+function section(cls, declared, notes) {
+  const out = [`## ${cls.name.text}`];
+  const paragraph = sentencesOf(cls).join(" ");
+  if (paragraph !== "") out.push(paragraph);
+  if (cls.fields.length > 0) out.push(fieldTable(cls, declared));
+  if (notes) {
+    const questions = openQuestions(cls);
+    if (questions.length > 0) out.push("**Open questions**", questions.join("\n"));
+  }
+  return out;
+}
+var FIELD_COLUMNS = ["Field", "Type", "Description"];
+function fieldTable(cls, declared) {
+  const rows = [row(FIELD_COLUMNS), divider(FIELD_COLUMNS.length)];
+  for (const field of cls.fields) {
+    rows.push(row([field.name.text, typeCell(field, declared), descriptionCell(field)]));
+  }
+  return rows.join("\n");
+}
+function typeCell(field, declared) {
+  const parts2 = [];
+  if (field.identifier) parts2.push("identifier");
+  const type = typeText(field.type, declared);
+  if (type !== void 0) parts2.push(type);
+  return parts2.join(", ");
+}
+function typeText(type, declared) {
+  if (type === void 0) return void 0;
+  let text;
+  switch (type.kind) {
+    case "primitive":
+      text = type.written.text;
+      break;
+    case "unknown":
+      text = type.name.text;
+      break;
+    case "class":
+      text = declared.has(type.name.text) ? link(type.name.text) : type.name.text;
+      break;
+    case "enum":
+      text = type.values.map((value) => value.text).join(" / ");
+      break;
+  }
+  return type.many ? `list of ${text}` : text;
+}
+var link = (name2) => `[${name2}](#${name2.toLowerCase()})`;
+function descriptionCell(field) {
+  const sentences = [];
+  if (field.system !== void 0) sentences.push(`System: ${field.system.text}.`);
+  if (field.joinsTo !== void 0) {
+    sentences.push(`Joins to ${field.joinsTo.className.text}.${field.joinsTo.fieldName.text}.`);
+  }
+  const description = field.description;
+  if (description === void 0 || description === "") return sentences.join(" ");
+  if (sentences.length === 0) return description;
+  return [stopped(description), ...sentences].join(" ");
+}
+function termTable(classes, notes) {
+  const columns = notes ? ["Term", "Definition", "Open questions"] : ["Term", "Definition"];
+  const rows = [row(columns), divider(columns.length)];
+  for (const cls of classes) {
+    const cells = [cls.name.text, sentencesOf(cls).join(" ")];
+    if (notes) cells.push(doubtsOf(cls.note).join("<br>"));
+    rows.push(row(cells));
+  }
+  return rows.join("\n");
+}
+function sentencesOf(cls) {
+  const out = [];
+  if (cls.system !== void 0) out.push(`System: ${cls.system.text}.`);
+  if (cls.parent !== void 0) out.push(`Extends ${cls.parent.text}.`);
+  if (cls.similarTo !== void 0) out.push(`Similar to ${cls.similarTo.text}.`);
+  if (cls.description !== void 0 && cls.description !== "") out.push(sentence(cls.description));
+  return out;
+}
+var sentence = (text) => stopped(text.charAt(0).toUpperCase() + text.slice(1));
+var stopped = (text) => /[.!?]$/.test(text) ? text : `${text}.`;
+var doubtsOf = (note) => note === void 0 ? [] : note.split("\n").filter((doubt) => doubt !== "");
+function openQuestions(cls) {
+  const out = doubtsOf(cls.note).map((doubt) => `- ${doubt}`);
+  for (const field of cls.fields) {
+    for (const doubt of doubtsOf(field.note)) out.push(`- ${field.name.text}: ${doubt}`);
+  }
+  return out;
+}
+var row = (cells) => `|${cells.map((cell) => cell === "" ? " " : ` ${cellText(cell)} `).join("|")}|`;
+var divider = (columns) => `|${"---|".repeat(columns)}`;
+var cellText = (text) => text.replaceAll("|", "\\|").replaceAll("\n", " ");
+
 // src/generators/linkml.ts
 var BASE_URI = "https://example.org";
 var RANGE = {
@@ -835,9 +989,11 @@ function toLinkML(doc, opts) {
     if (system === void 0) return schemaName;
     return systemPrefix.get(system) ?? schemaName;
   };
+  const description = resolved.description;
   const schema = {
     id: `${BASE_URI}/${schemaName}`,
     name: schemaName,
+    ...description === void 0 || description === "" ? {} : { description },
     default_prefix: schemaName,
     default_range: "string",
     prefixes,
@@ -996,10 +1152,12 @@ function toMermaid(doc, opts) {
   }
   if (notes) {
     for (const cls of resolved.classes) {
-      if (cls.note !== void 0) lines.push(`  note for ${cls.name.text} ${quote(cls.note)}`);
+      for (const doubt of doubts(cls.note)) {
+        lines.push(`  note for ${cls.name.text} ${quote(doubt)}`);
+      }
       for (const field of cls.fields) {
-        if (field.note !== void 0) {
-          lines.push(`  note for ${cls.name.text} ${quote(`${field.name.text}: ${field.note}`)}`);
+        for (const doubt of doubts(field.note)) {
+          lines.push(`  note for ${cls.name.text} ${quote(`${field.name.text}: ${doubt}`)}`);
         }
       }
     }
@@ -1024,11 +1182,11 @@ function toMermaid(doc, opts) {
 }
 function member(field) {
   const marker = field.identifier ? "*" : "+";
-  const type = field.type === void 0 ? "" : `${typeText(field.type)} `;
+  const type = field.type === void 0 ? "" : `${typeText2(field.type)} `;
   const system = field.system === void 0 ? "" : ` @${field.system.text}`;
   return `${marker}${type}${field.name.text}${system}`;
 }
-function typeText(type) {
+function typeText2(type) {
   let text;
   switch (type.kind) {
     case "primitive":
@@ -1044,6 +1202,7 @@ function typeText(type) {
   }
   return type.many ? `${text}[]` : text;
 }
+var doubts = (note) => note === void 0 ? [] : note.split("\n").filter((line) => line !== "");
 var quote = (text) => `"${text.replaceAll('"', "'")}"`;
 
 // src/serialize.ts
@@ -1093,8 +1252,17 @@ function hasControlCharacter(text) {
 // src/compile.ts
 function compile(source, opts) {
   const doc = resolve(parse(source));
-  const output = opts.target === "linkml" ? serialize(toLinkML(doc, { schemaName: opts.schemaName }), opts.format ?? "yaml") : toMermaid(doc, { notes: opts.notes });
-  return { output, diagnostics: doc.diagnostics };
+  return { output: generate(doc, opts), diagnostics: doc.diagnostics };
+}
+function generate(doc, opts) {
+  switch (opts.target) {
+    case "linkml":
+      return serialize(toLinkML(doc, { schemaName: opts.schemaName }), opts.format ?? "yaml");
+    case "glossary":
+      return toGlossary(doc, { name: opts.name, classes: opts.classes, notes: opts.notes });
+    case "mermaid":
+      return toMermaid(doc, { notes: opts.notes });
+  }
 }
 
 // src/diagnostics.ts
@@ -1106,20 +1274,27 @@ function formatDiagnostic(d, file) {
 // src/generators/skiss.ts
 var TRAILER_COLUMN = 40;
 function toSkiss(doc) {
-  if (doc.classes.length === 0) return "";
-  return `${doc.classes.map(classBlock).join("\n\n")}
+  const description = doc.description;
+  const blocks = description === void 0 || description === "" ? [] : [`# ${description}`];
+  for (const cls of doc.classes) blocks.push(classBlock(cls));
+  if (blocks.length === 0) return "";
+  return `${blocks.join("\n\n")}
 `;
 }
 function classBlock(cls) {
   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");
+  const lines = [withTrailer(head, cls), ...doubtLines(cls.note, "  ")];
+  for (const field of cls.fields) lines.push(fieldLine(field), ...doubtLines(field.note, "    "));
+  return lines.join("\n");
 }
+var doubtsOf2 = (note) => note === void 0 ? [] : note.split("\n").filter((doubt) => doubt !== "");
+var doubtLines = (note, indent) => doubtsOf2(note).slice(1).map((doubt) => `${indent}? ${doubt}`);
 function fieldLine(field) {
-  const type = typeText2(field.type);
+  const type = typeText3(field.type);
   const head = `  ${field.name.text}` + (field.identifier ? "*" : "") + (type === void 0 ? "" : `: ${type}`) + (field.system === void 0 ? "" : ` @${field.system.text}`) + (field.joinsTo === void 0 ? "" : ` = ${field.joinsTo.className.text}.${field.joinsTo.fieldName.text}`);
   return withTrailer(head, field);
 }
-function typeText2(type) {
+function typeText3(type) {
   if (type === void 0) return void 0;
   let text;
   switch (type.kind) {
@@ -1146,7 +1321,8 @@ function withTrailer(head, node) {
   const parts2 = [];
   if (node.description !== void 0 && node.description !== "")
     parts2.push(writeDescription(node.description));
-  if (node.note !== void 0 && node.note !== "") parts2.push(`? ${node.note}`);
+  const [doubt] = doubtsOf2(node.note);
+  if (doubt !== void 0) parts2.push(`? ${doubt}`);
   if (parts2.length === 0) return head;
   const gap = head.length < TRAILER_COLUMN - 1 ? " ".repeat(TRAILER_COLUMN - head.length) : "  ";
   return head + gap + parts2.join(" ");
@@ -1179,6 +1355,8 @@ var SLOT_TAGS = /* @__PURE__ */ new Set(["system", "note", "joins_to"]);
 var QUIET_SCHEMA_KEYS = /* @__PURE__ */ new Set([
   "id",
   "name",
+  // SPEC §8: the schema's own `description` is the document description.
+  "description",
   "prefixes",
   "imports",
   "default_prefix",
@@ -1282,7 +1460,7 @@ function fromLinkML(schema) {
     } else if (system !== void 0) report("annotation", name2, notText("system", system));
     const rawNote = annotations.get("note");
     if (typeof rawNote === "string") {
-      const note = oneLine(rawNote);
+      const note = doubtLines2(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"));
@@ -1385,7 +1563,10 @@ function fromLinkML(schema) {
   for (const key2 of Object.keys(root)) {
     if (!QUIET_SCHEMA_KEYS.has(key2)) report("schema", schemaName, `\`${key2}\``);
   }
-  const source = toSkiss({ classes, diagnostics: [] });
+  const projected = { classes, diagnostics: [] };
+  const schemaDescription = oneLine(stringOf(get(root, "description")));
+  if (schemaDescription !== void 0) projected.description = schemaDescription;
+  const source = toSkiss(projected);
   return { document: parse(source), source, dropped };
   function buildField(classKey, className, slot, def) {
     const name2 = fieldNameOf(classKey, slot);
@@ -1428,7 +1609,7 @@ function fromLinkML(schema) {
     } else if (joins !== void 0) report("annotation", element, notText("joins_to", joins));
     const rawNote = annotations.get("note");
     if (typeof rawNote === "string") {
-      const note = oneLine(rawNote);
+      const note = doubtLines2(rawNote);
       if (note !== void 0) field.note = note;
     } else if (rawNote !== void 0) report("annotation", element, notText("note", rawNote));
     for (const other of Object.keys(def)) {
@@ -1654,6 +1835,10 @@ function oneLine(text) {
   const line = text.replace(/\s*[\r\n]+\s*/g, " ").trim();
   return line === "" ? void 0 : line;
 }
+function doubtLines2(text) {
+  const lines = text.split(/\r\n|\n|\r/).map((line) => line.trim()).filter((line) => line !== "");
+  return lines.length === 0 ? void 0 : lines.join("\n");
+}
 var list = (items) => items.map((item) => `\`${item}\``).join(", ");
 var at0 = (text) => ({ text, line: 0, col: 0, end: 0 });
 var stringType = (many) => ({
@@ -1693,7 +1878,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.7.0";
+var VERSION = "0.8.0";
 
 // src/cli.ts
 var HELP = `Usage: skiss <command> [options]
@@ -1701,6 +1886,7 @@ var HELP = `Usage: skiss <command> [options]
 Commands:
   diagram <file>       Write a Mermaid class diagram for a .skiss file.
   compile <file>       Write a LinkML schema for a .skiss file.
+  glossary <file>      Write the descriptions of a .skiss file as Markdown.
   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.
@@ -1709,10 +1895,12 @@ Commands:
 Options:
   -o, --output <path>  Write the output to <path> instead of standard output
       --notes          diagram, render: emit \`? text\` doubts as Mermaid notes
+                       glossary: list the doubts as open questions
       --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.
+      --classes        glossary: write the classes alone, as a table of terms
+      --name <name>    compile: the schema name; glossary: the heading.
+                       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.
@@ -1747,6 +1935,7 @@ var EXIT_INTERNAL = 70;
 var COMMANDS = {
   diagram: ["output", "notes", "strict"],
   compile: ["output", "json", "name", "strict"],
+  glossary: ["output", "classes", "notes", "name", "strict"],
   import: ["output", "strict"],
   render: ["output", "notes", "format", "scale", "strict"]
 };
@@ -1769,6 +1958,7 @@ async function main(argv) {
       output: { type: "string", short: "o" },
       notes: { type: "boolean" },
       json: { type: "boolean" },
+      classes: { type: "boolean" },
       name: { type: "string" },
       format: { type: "string" },
       scale: { type: "string" },
@@ -1829,11 +2019,22 @@ function unreadableInput(command, diagnostics, dropped) {
 }
 function runCommand(command, source, file, values) {
   if (command === "import") return importLinkML(source);
+  if (command === "glossary") {
+    return {
+      ...compile(source, {
+        target: "glossary",
+        name: values.name ?? defaultName(file),
+        classes: values.classes,
+        notes: values.notes
+      }),
+      dropped: []
+    };
+  }
   if (command === "compile") {
     return {
       ...compile(source, {
         target: "linkml",
-        schemaName: values.name ?? defaultSchemaName(file),
+        schemaName: values.name ?? defaultName(file),
         format: values.json === true ? "json" : "yaml"
       }),
       dropped: []
@@ -1841,7 +2042,7 @@ function runCommand(command, source, file, values) {
   }
   return { ...compile(source, { target: "mermaid", notes: values.notes }), dropped: [] };
 }
-var defaultSchemaName = (file) => file === "-" ? "sketch" : basename(file, extname(file));
+var defaultName = (file) => file === "-" ? "sketch" : basename(file, extname(file));
 async function readSource(file) {
   try {
     return await readFile(file, "utf8");

package/dist/index.d.ts

@@ -87,6 +87,14 @@ interface Diagnostic {
 interface Document {
     classes: ClassNode[];
     diagnostics: Diagnostic[];
+    /**
+     * SPEC §3.1: the run of comment lines that starts on the first line of the
+     * file, each stripped of its `#` and one space, joined with a single space.
+     * Absent when the file does not start with one. It is the only column-0
+     * comment the document holds, and it compiles to the schema's own
+     * `description` (SPEC §5.1).
+     */
+    description?: string;
     /**
      * Class names referenced by `:`, `~` or `=` but never declared, each once,
      * in first-reference order and at its first reference's position. Absent
@@ -95,6 +103,22 @@ interface Document {
     undeclared?: Name[];
 }
 
+/** What `resolve` returns: a `Document` whose `undeclared` list is always present. */
+interface ResolvedDocument extends Document {
+    undeclared: Name[];
+}
+declare function resolve(doc: Document): ResolvedDocument;
+
+interface GlossaryOptions {
+    /** The `#` heading. Normally the file name; defaults to `Glossary`. */
+    name?: string;
+    /** Write the terms alone: one row per class, no fields. Off by default. */
+    classes?: boolean;
+    /** Add the `? text` doubts as open questions. Off by default. */
+    notes?: boolean;
+}
+declare function toGlossary(doc: ResolvedDocument, opts?: GlossaryOptions): string;
+
 interface MermaidOptions {
     /** Emit `? text` doubts as `note for` lines. Off by default. */
     notes?: boolean;
@@ -129,6 +153,8 @@ interface LinkMLEnum {
 interface LinkMLSchema {
     id: string;
     name: string;
+    /** The document description (SPEC §3.1), written directly after `name`. */
+    description?: string;
     default_prefix: string;
     default_range: string;
     prefixes: Record<string, string>;
@@ -157,12 +183,18 @@ interface LinkMLCompileOptions {
     /** Defaults to `yaml`, the form LinkML itself reads. */
     format?: SerializeFormat;
 }
+/** `toGlossary` text from the source (issue #90). */
+interface GlossaryCompileOptions extends GlossaryOptions {
+    target: 'glossary';
+    /** The heading. Normally the file name, as `schemaName` is. */
+    name: string;
+}
 /**
  * A union rather than one shape with optional keys, so `schemaName` is
  * required exactly when it is used and a `mermaid` call cannot carry a
  * `format` that would be ignored.
  */
-type CompileOptions = MermaidCompileOptions | LinkMLCompileOptions;
+type CompileOptions = MermaidCompileOptions | LinkMLCompileOptions | GlossaryCompileOptions;
 interface CompileResult {
     /** The generated text, `\n`-terminated, whatever the platform. */
     output: string;
@@ -262,12 +294,6 @@ declare function importLinkML(text: string): ImportResult;
 
 declare function parse(source: string): Document;
 
-/** What `resolve` returns: a `Document` whose `undeclared` list is always present. */
-interface ResolvedDocument extends Document {
-    undeclared: Name[];
-}
-declare function resolve(doc: Document): ResolvedDocument;
-
-declare const VERSION = "0.7.0";
+declare const VERSION = "0.8.0";
 
-export { type ClassNode, type CompileOptions, type CompileResult, type Diagnostic, type DiagnosticCode, type Document, type Dropped, type FieldNode, type FromLinkMLResult, type ImportResult, type JoinRef, type LinkMLAnnotations, type LinkMLAttribute, type LinkMLClass, type LinkMLCompileOptions, type LinkMLEnum, type LinkMLOptions, type LinkMLSchema, type MermaidCompileOptions, type MermaidOptions, type Name, type Primitive, type ResolvedDocument, type SerializeFormat, type Severity, type Token, type TokenKind, type TypeRef, VERSION, compile, formatDiagnostic, formatDropped, fromLinkML, importLinkML, parse, resolve, serialize, toLinkML, toMermaid, toSkiss, tokenizeLine };
+export { type ClassNode, type CompileOptions, type CompileResult, type Diagnostic, type DiagnosticCode, type Document, type Dropped, type FieldNode, type FromLinkMLResult, type GlossaryCompileOptions, type GlossaryOptions, type ImportResult, type JoinRef, type LinkMLAnnotations, type LinkMLAttribute, type LinkMLClass, type LinkMLCompileOptions, type LinkMLEnum, type LinkMLOptions, type LinkMLSchema, type MermaidCompileOptions, type MermaidOptions, type Name, type Primitive, type ResolvedDocument, type SerializeFormat, type Severity, type Token, type TokenKind, type TypeRef, VERSION, compile, formatDiagnostic, formatDropped, fromLinkML, importLinkML, parse, resolve, serialize, toGlossary, toLinkML, toMermaid, toSkiss, tokenizeLine };

package/dist/index.js

@@ -117,19 +117,47 @@ function primitiveFor(word) {
 var DROPPED = "dropped-class";
 var FIELD_ORDER = "name, `*`, `: type`, `@System`, `= Class.field`, then `#` and `?`";
 var CLASS_ORDER = "name, `< Parent`, `@System`, `~ Class`, then `#` and `?`";
+var NO_ELEMENT_ABOVE = "A description line needs a class or a field above it";
 function parse(source) {
   const classes = [];
   const diagnostics = [];
   let current;
+  let target;
+  const header = [];
+  let inHeader = true;
   const text0 = source.startsWith("\uFEFF") ? source.slice(1) : source;
   const lines = text0.split(/\r\n|\n|\r/);
   for (let i = 0; i < lines.length; i++) {
     const line = i + 1;
     const text = (lines[i] ?? "").replace(/[ \t]+$/, "");
     const first = text[0];
-    if (first === void 0 || first === "#") continue;
+    if (first === void 0) {
+      inHeader = false;
+      continue;
+    }
+    if (first === "#") {
+      if (inHeader) header.push(headerLine(text));
+      continue;
+    }
+    inHeader = false;
     if (isWs(first)) {
       const start = text.search(/[^ \t]/);
+      if (text[start] === "#" || isDoubtMarker(text, start)) {
+        if (current === DROPPED) continue;
+        if (target === void 0) {
+          diagnostics.push({
+            severity: "error",
+            code: "E_UNPARSABLE",
+            message: NO_ELEMENT_ABOVE,
+            line,
+            col: start,
+            end: text.length
+          });
+          continue;
+        }
+        continueTrailer(target, splitTrailer(text));
+        continue;
+      }
       if (current === void 0) {
         diagnostics.push({
           severity: "error",
@@ -143,7 +171,10 @@ function parse(source) {
       }
       const result = parseFieldLine(text, line);
       if (!result.ok) diagnostics.push(result.diagnostic);
-      else if (current !== DROPPED) current.fields.push(result.value);
+      else if (current !== DROPPED) {
+        current.fields.push(result.value);
+        target = result.value;
+      }
       continue;
     }
     if (/\p{L}/u.test(first)) {
@@ -151,9 +182,11 @@ function parse(source) {
       if (result.ok) {
         classes.push(result.value);
         current = result.value;
+        target = result.value;
       } else {
         diagnostics.push(result.diagnostic);
         current = result.atName ? DROPPED : void 0;
+        target = void 0;
       }
       continue;
     }
@@ -166,7 +199,14 @@ function parse(source) {
       end: text.length
     });
   }
-  return { classes, diagnostics };
+  const document = { classes, diagnostics };
+  const description = header.filter((part) => part !== "").join(" ");
+  if (description !== "") document.description = description;
+  return document;
+}
+function headerLine(text) {
+  const rest = text.slice(1);
+  return isWs(rest[0]) ? rest.slice(1) : rest;
 }
 function isDoubtMarker(text, i) {
   return text[i] === "?" && isWs(text[i - 1]) && (i + 1 === text.length || isWs(text[i + 1]));
@@ -202,6 +242,15 @@ function splitTrailer(text) {
   }
   return trailer;
 }
+function continueTrailer(node, trailer) {
+  if (trailer.description !== void 0) {
+    node.description = node.description === void 0 ? trailer.description : `${node.description} ${trailer.description}`;
+  }
+  if (trailer.note !== void 0) {
+    node.note = node.note === void 0 ? trailer.note : `${node.note}
+${trailer.note}`;
+  }
+}
 var WORD = /[\p{L}\p{N}_-]+/uy;
 function wordAt(text, i) {
   WORD.lastIndex = i;
@@ -322,8 +371,10 @@ function parseFieldLine(text, line) {
   const head = take(c);
   if (head === void 0) {
     const col = text.search(/[^ \t]/);
-    const message = text[col] === "#" ? "A `#` comment must start at column 0; an indented line is a field and needs a name" : "A field line needs a field name before its trailer";
-    return fail("E_UNPARSABLE", message, line, { col, end: Math.max(col + 1, text.length) });
+    return fail("E_UNPARSABLE", "A field line needs a field name before its trailer", line, {
+      col,
+      end: Math.max(col + 1, text.length)
+    });
   }
   if (head.kind !== "word") return unexpected(head, line, "field", FIELD_ORDER);
   if (!FIELD_NAME.test(head.text)) {
@@ -783,6 +834,109 @@ function levenshtein(a, b) {
   return previous[b.length] ?? 0;
 }
 
+// src/generators/glossary.ts
+var DEFAULT_NAME = "Glossary";
+function toGlossary(doc, opts) {
+  const resolved = resolve(doc);
+  const notes = opts?.notes === true;
+  const declared = new Set(resolved.classes.map((cls) => cls.name.text));
+  const blocks = [`# ${opts?.name ?? DEFAULT_NAME}`];
+  const description = resolved.description;
+  if (description !== void 0 && description !== "") blocks.push(description);
+  if (opts?.classes === true) blocks.push(termTable(resolved.classes, notes));
+  else for (const cls of resolved.classes) blocks.push(...section(cls, declared, notes));
+  return `${blocks.join("\n\n")}
+`;
+}
+function section(cls, declared, notes) {
+  const out = [`## ${cls.name.text}`];
+  const paragraph = sentencesOf(cls).join(" ");
+  if (paragraph !== "") out.push(paragraph);
+  if (cls.fields.length > 0) out.push(fieldTable(cls, declared));
+  if (notes) {
+    const questions = openQuestions(cls);
+    if (questions.length > 0) out.push("**Open questions**", questions.join("\n"));
+  }
+  return out;
+}
+var FIELD_COLUMNS = ["Field", "Type", "Description"];
+function fieldTable(cls, declared) {
+  const rows = [row(FIELD_COLUMNS), divider(FIELD_COLUMNS.length)];
+  for (const field of cls.fields) {
+    rows.push(row([field.name.text, typeCell(field, declared), descriptionCell(field)]));
+  }
+  return rows.join("\n");
+}
+function typeCell(field, declared) {
+  const parts2 = [];
+  if (field.identifier) parts2.push("identifier");
+  const type = typeText(field.type, declared);
+  if (type !== void 0) parts2.push(type);
+  return parts2.join(", ");
+}
+function typeText(type, declared) {
+  if (type === void 0) return void 0;
+  let text;
+  switch (type.kind) {
+    case "primitive":
+      text = type.written.text;
+      break;
+    case "unknown":
+      text = type.name.text;
+      break;
+    case "class":
+      text = declared.has(type.name.text) ? link(type.name.text) : type.name.text;
+      break;
+    case "enum":
+      text = type.values.map((value) => value.text).join(" / ");
+      break;
+  }
+  return type.many ? `list of ${text}` : text;
+}
+var link = (name2) => `[${name2}](#${name2.toLowerCase()})`;
+function descriptionCell(field) {
+  const sentences = [];
+  if (field.system !== void 0) sentences.push(`System: ${field.system.text}.`);
+  if (field.joinsTo !== void 0) {
+    sentences.push(`Joins to ${field.joinsTo.className.text}.${field.joinsTo.fieldName.text}.`);
+  }
+  const description = field.description;
+  if (description === void 0 || description === "") return sentences.join(" ");
+  if (sentences.length === 0) return description;
+  return [stopped(description), ...sentences].join(" ");
+}
+function termTable(classes, notes) {
+  const columns = notes ? ["Term", "Definition", "Open questions"] : ["Term", "Definition"];
+  const rows = [row(columns), divider(columns.length)];
+  for (const cls of classes) {
+    const cells = [cls.name.text, sentencesOf(cls).join(" ")];
+    if (notes) cells.push(doubtsOf(cls.note).join("<br>"));
+    rows.push(row(cells));
+  }
+  return rows.join("\n");
+}
+function sentencesOf(cls) {
+  const out = [];
+  if (cls.system !== void 0) out.push(`System: ${cls.system.text}.`);
+  if (cls.parent !== void 0) out.push(`Extends ${cls.parent.text}.`);
+  if (cls.similarTo !== void 0) out.push(`Similar to ${cls.similarTo.text}.`);
+  if (cls.description !== void 0 && cls.description !== "") out.push(sentence(cls.description));
+  return out;
+}
+var sentence = (text) => stopped(text.charAt(0).toUpperCase() + text.slice(1));
+var stopped = (text) => /[.!?]$/.test(text) ? text : `${text}.`;
+var doubtsOf = (note) => note === void 0 ? [] : note.split("\n").filter((doubt) => doubt !== "");
+function openQuestions(cls) {
+  const out = doubtsOf(cls.note).map((doubt) => `- ${doubt}`);
+  for (const field of cls.fields) {
+    for (const doubt of doubtsOf(field.note)) out.push(`- ${field.name.text}: ${doubt}`);
+  }
+  return out;
+}
+var row = (cells) => `|${cells.map((cell) => cell === "" ? " " : ` ${cellText(cell)} `).join("|")}|`;
+var divider = (columns) => `|${"---|".repeat(columns)}`;
+var cellText = (text) => text.replaceAll("|", "\\|").replaceAll("\n", " ");
+
 // src/generators/linkml.ts
 var BASE_URI = "https://example.org";
 var RANGE = {
@@ -825,9 +979,11 @@ function toLinkML(doc, opts) {
     if (system === void 0) return schemaName;
     return systemPrefix.get(system) ?? schemaName;
   };
+  const description = resolved.description;
   const schema = {
     id: `${BASE_URI}/${schemaName}`,
     name: schemaName,
+    ...description === void 0 || description === "" ? {} : { description },
     default_prefix: schemaName,
     default_range: "string",
     prefixes,
@@ -986,10 +1142,12 @@ function toMermaid(doc, opts) {
   }
   if (notes) {
     for (const cls of resolved.classes) {
-      if (cls.note !== void 0) lines.push(`  note for ${cls.name.text} ${quote(cls.note)}`);
+      for (const doubt of doubts(cls.note)) {
+        lines.push(`  note for ${cls.name.text} ${quote(doubt)}`);
+      }
       for (const field of cls.fields) {
-        if (field.note !== void 0) {
-          lines.push(`  note for ${cls.name.text} ${quote(`${field.name.text}: ${field.note}`)}`);
+        for (const doubt of doubts(field.note)) {
+          lines.push(`  note for ${cls.name.text} ${quote(`${field.name.text}: ${doubt}`)}`);
         }
       }
     }
@@ -1014,11 +1172,11 @@ function toMermaid(doc, opts) {
 }
 function member(field) {
   const marker = field.identifier ? "*" : "+";
-  const type = field.type === void 0 ? "" : `${typeText(field.type)} `;
+  const type = field.type === void 0 ? "" : `${typeText2(field.type)} `;
   const system = field.system === void 0 ? "" : ` @${field.system.text}`;
   return `${marker}${type}${field.name.text}${system}`;
 }
-function typeText(type) {
+function typeText2(type) {
   let text;
   switch (type.kind) {
     case "primitive":
@@ -1034,6 +1192,7 @@ function typeText(type) {
   }
   return type.many ? `${text}[]` : text;
 }
+var doubts = (note) => note === void 0 ? [] : note.split("\n").filter((line) => line !== "");
 var quote = (text) => `"${text.replaceAll('"', "'")}"`;
 
 // src/serialize.ts
@@ -1083,8 +1242,17 @@ function hasControlCharacter(text) {
 // src/compile.ts
 function compile(source, opts) {
   const doc = resolve(parse(source));
-  const output = opts.target === "linkml" ? serialize(toLinkML(doc, { schemaName: opts.schemaName }), opts.format ?? "yaml") : toMermaid(doc, { notes: opts.notes });
-  return { output, diagnostics: doc.diagnostics };
+  return { output: generate(doc, opts), diagnostics: doc.diagnostics };
+}
+function generate(doc, opts) {
+  switch (opts.target) {
+    case "linkml":
+      return serialize(toLinkML(doc, { schemaName: opts.schemaName }), opts.format ?? "yaml");
+    case "glossary":
+      return toGlossary(doc, { name: opts.name, classes: opts.classes, notes: opts.notes });
+    case "mermaid":
+      return toMermaid(doc, { notes: opts.notes });
+  }
 }
 
 // src/diagnostics.ts
@@ -1096,20 +1264,27 @@ function formatDiagnostic(d, file) {
 // src/generators/skiss.ts
 var TRAILER_COLUMN = 40;
 function toSkiss(doc) {
-  if (doc.classes.length === 0) return "";
-  return `${doc.classes.map(classBlock).join("\n\n")}
+  const description = doc.description;
+  const blocks = description === void 0 || description === "" ? [] : [`# ${description}`];
+  for (const cls of doc.classes) blocks.push(classBlock(cls));
+  if (blocks.length === 0) return "";
+  return `${blocks.join("\n\n")}
 `;
 }
 function classBlock(cls) {
   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");
+  const lines = [withTrailer(head, cls), ...doubtLines(cls.note, "  ")];
+  for (const field of cls.fields) lines.push(fieldLine(field), ...doubtLines(field.note, "    "));
+  return lines.join("\n");
 }
+var doubtsOf2 = (note) => note === void 0 ? [] : note.split("\n").filter((doubt) => doubt !== "");
+var doubtLines = (note, indent) => doubtsOf2(note).slice(1).map((doubt) => `${indent}? ${doubt}`);
 function fieldLine(field) {
-  const type = typeText2(field.type);
+  const type = typeText3(field.type);
   const head = `  ${field.name.text}` + (field.identifier ? "*" : "") + (type === void 0 ? "" : `: ${type}`) + (field.system === void 0 ? "" : ` @${field.system.text}`) + (field.joinsTo === void 0 ? "" : ` = ${field.joinsTo.className.text}.${field.joinsTo.fieldName.text}`);
   return withTrailer(head, field);
 }
-function typeText2(type) {
+function typeText3(type) {
   if (type === void 0) return void 0;
   let text;
   switch (type.kind) {
@@ -1136,7 +1311,8 @@ function withTrailer(head, node) {
   const parts2 = [];
   if (node.description !== void 0 && node.description !== "")
     parts2.push(writeDescription(node.description));
-  if (node.note !== void 0 && node.note !== "") parts2.push(`? ${node.note}`);
+  const [doubt] = doubtsOf2(node.note);
+  if (doubt !== void 0) parts2.push(`? ${doubt}`);
   if (parts2.length === 0) return head;
   const gap = head.length < TRAILER_COLUMN - 1 ? " ".repeat(TRAILER_COLUMN - head.length) : "  ";
   return head + gap + parts2.join(" ");
@@ -1169,6 +1345,8 @@ var SLOT_TAGS = /* @__PURE__ */ new Set(["system", "note", "joins_to"]);
 var QUIET_SCHEMA_KEYS = /* @__PURE__ */ new Set([
   "id",
   "name",
+  // SPEC §8: the schema's own `description` is the document description.
+  "description",
   "prefixes",
   "imports",
   "default_prefix",
@@ -1272,7 +1450,7 @@ function fromLinkML(schema) {
     } else if (system !== void 0) report("annotation", name2, notText("system", system));
     const rawNote = annotations.get("note");
     if (typeof rawNote === "string") {
-      const note = oneLine(rawNote);
+      const note = doubtLines2(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"));
@@ -1375,7 +1553,10 @@ function fromLinkML(schema) {
   for (const key2 of Object.keys(root)) {
     if (!QUIET_SCHEMA_KEYS.has(key2)) report("schema", schemaName, `\`${key2}\``);
   }
-  const source = toSkiss({ classes, diagnostics: [] });
+  const projected = { classes, diagnostics: [] };
+  const schemaDescription = oneLine(stringOf(get(root, "description")));
+  if (schemaDescription !== void 0) projected.description = schemaDescription;
+  const source = toSkiss(projected);
   return { document: parse(source), source, dropped };
   function buildField(classKey, className, slot, def) {
     const name2 = fieldNameOf(classKey, slot);
@@ -1418,7 +1599,7 @@ function fromLinkML(schema) {
     } else if (joins !== void 0) report("annotation", element, notText("joins_to", joins));
     const rawNote = annotations.get("note");
     if (typeof rawNote === "string") {
-      const note = oneLine(rawNote);
+      const note = doubtLines2(rawNote);
       if (note !== void 0) field.note = note;
     } else if (rawNote !== void 0) report("annotation", element, notText("note", rawNote));
     for (const other of Object.keys(def)) {
@@ -1644,6 +1825,10 @@ function oneLine(text) {
   const line = text.replace(/\s*[\r\n]+\s*/g, " ").trim();
   return line === "" ? void 0 : line;
 }
+function doubtLines2(text) {
+  const lines = text.split(/\r\n|\n|\r/).map((line) => line.trim()).filter((line) => line !== "");
+  return lines.length === 0 ? void 0 : lines.join("\n");
+}
 var list = (items) => items.map((item) => `\`${item}\``).join(", ");
 var at0 = (text) => ({ text, line: 0, col: 0, end: 0 });
 var stringType = (many) => ({
@@ -1881,7 +2066,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.7.0";
+var VERSION = "0.8.0";
 export {
   VERSION,
   compile,
@@ -1892,6 +2077,7 @@ export {
   parse,
   resolve,
   serialize,
+  toGlossary,
   toLinkML,
   toMermaid,
   toSkiss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eriknaslund/skiss",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A text notation for sketching data models, compiled to LinkML",
   "type": "module",
   "license": "MIT",