@eriknaslund/skiss 0.3.0 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 erik-naslund
+Copyright (c) 2026 Erik Näslund
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -64,7 +64,7 @@ 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 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.
+`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.
 
 `npm install @eriknaslund/skiss` also gives you the library: `compile`, `formatDiagnostic`, `parse`, `resolve`, `toLinkML`, `serialize`, `toMermaid`, `toSkiss`, `fromLinkML`, `formatDropped`, `importLinkML` and `VERSION`, browser-safe.
 
@@ -79,11 +79,14 @@ Editors that render Skiss live are separate projects built on this package. This
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the code is organised. |
 | [docs/adr/](docs/adr/) | Architecture decision records. |
 | [docs/ROADMAP.md](docs/ROADMAP.md) | What comes next. |
+| [docs/RELEASING.md](docs/RELEASING.md) | How a version reaches npm. |
 | [AGENTS.md](AGENTS.md) | How this repository is built. |
 
 ## Status
 
-Pre-release. The [specification](docs/SPEC.md) is at 0.1. Nothing is implemented yet.
+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.
+
+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.
 
 ## License
 

package/dist/cli.js

@@ -10,7 +10,8 @@ var isWs = (c) => c === " " || c === "	";
 var trimWs = (s) => s.replace(/^[ \t]+/, "").replace(/[ \t]+$/, "");
 var CLASS_NAME = /^[A-Z][A-Za-z0-9]*$/;
 var FIELD_NAME = /^[a-z][A-Za-z0-9]*$/;
-var SYSTEM_OR_VALUE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var SYSTEM_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var ENUM_VALUE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 var PRIMITIVES = {
   string: "string",
   int: "int",
@@ -315,7 +316,7 @@ function parseSystem(c, at) {
       system ?? afterSpan(at)
     );
   }
-  if (!SYSTEM_OR_VALUE.test(system.text)) {
+  if (!SYSTEM_NAME.test(system.text)) {
     return fail(
       "E_UNPARSABLE",
       `A system name is letters, digits, \`-\` and \`_\`, starting with a letter: \`${system.text}\``,
@@ -373,10 +374,10 @@ function parseType(c, colon) {
   }
   if (words.length > 1) {
     for (const w of words) {
-      if (!SYSTEM_OR_VALUE.test(w.text)) {
+      if (!ENUM_VALUE.test(w.text)) {
         return fail(
           "E_UNPARSABLE",
-          `An enum value is letters, digits, \`-\` and \`_\`, starting with a letter: \`${w.text}\``,
+          `An enum value is letters, digits, \`-\` and \`_\`, and does not start with \`-\` or \`_\`: \`${w.text}\``,
           c.line,
           w
         );
@@ -513,6 +514,18 @@ function resolve(doc) {
         );
       } else if (field.type?.kind === "class") {
         reference(field.type.name);
+      } else if (field.type?.kind === "enum") {
+        const seen = /* @__PURE__ */ new Set();
+        for (const value of field.type.values) {
+          if (seen.has(value.text)) {
+            warn(
+              "W_DUPLICATE_ENUM_VALUE",
+              `value \`${value.text}\` is already in this enum; it is carried once`,
+              value
+            );
+          }
+          seen.add(value.text);
+        }
       }
       if (field.joinsTo !== void 0) {
         const { className, fieldName } = field.joinsTo;
@@ -626,7 +639,8 @@ function toLinkML(doc, opts) {
   const classNames = new Set(classes.map((cls) => cls.node.name.text));
   for (const name2 of resolved.undeclared) classNames.add(name2.text);
   const enums = nameEnums(classes, classNames);
-  const prefixes = { linkml: "https://w3id.org/linkml/" };
+  const prefixes = nameKeyed();
+  prefixes.linkml = "https://w3id.org/linkml/";
   if (!Object.hasOwn(prefixes, schemaName)) prefixes[schemaName] = `${BASE_URI}/${schemaName}/`;
   const systemPrefix = /* @__PURE__ */ new Map();
   const addSystem = (system) => {
@@ -657,12 +671,12 @@ function toLinkML(doc, opts) {
     prefixes,
     imports: ["linkml:types"]
   };
-  const out = {};
+  const out = nameKeyed();
   for (const cls of classes) {
     out[cls.node.name.text] = buildClass(cls, mappingPrefix, enums);
   }
   for (const name2 of resolved.undeclared) {
-    if (!(name2.text in out)) out[name2.text] = { annotations: { undeclared: true } };
+    if (!Object.hasOwn(out, name2.text)) out[name2.text] = { annotations: { undeclared: true } };
   }
   if (Object.keys(out).length > 0) schema.classes = out;
   const enumBlock = buildEnums(classes, enums);
@@ -720,13 +734,13 @@ function nameEnums(classes, classNames) {
   return names;
 }
 function buildEnums(classes, enums) {
-  const out = {};
+  const out = nameKeyed();
   for (const { node, fields } of classes) {
     for (const field of fields) {
       if (field.type?.kind !== "enum") continue;
       const name2 = enums.get(useKey(node.name.text, field.name.text));
-      if (name2 === void 0 || name2 in out) continue;
-      const values = {};
+      if (name2 === void 0 || Object.hasOwn(out, name2)) continue;
+      const values = nameKeyed();
       for (const value of field.type.values) values[value.text] = null;
       out[name2] = { permissible_values: values };
     }
@@ -745,7 +759,7 @@ function buildClass(cls, mappingPrefix, enums) {
     const target = node.similarTo.text;
     out.close_mappings = [`${mappingPrefix(target)}:${target}`];
   }
-  const attributes = {};
+  const attributes = nameKeyed();
   for (const field of fields) {
     attributes[field.name.text] = buildAttribute(field, node.name.text, enums);
   }
@@ -783,10 +797,12 @@ function rangeOf(field, className, enums) {
   }
 }
 var RESERVED_PREFIXES = /* @__PURE__ */ new Set(["linkml", "xsd", "shex", "schema"]);
+var PROTOTYPE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var nameKeyed = () => /* @__PURE__ */ Object.create(null);
 var linkmlName = (text) => {
   const name2 = text.toLowerCase().replace(/[^a-z0-9]/g, "_");
   if (!/[a-z0-9]/.test(name2)) return "sketch";
-  if (RESERVED_PREFIXES.has(name2)) return `${name2}_`;
+  if (RESERVED_PREFIXES.has(name2) || PROTOTYPE_KEYS.has(name2)) return `${name2}_`;
   return /^[0-9]/.test(name2) ? `_${name2}` : name2;
 };
 var capitalise = (text) => text.charAt(0).toUpperCase() + text.slice(1);
@@ -949,10 +965,15 @@ function typeText2(type) {
   }
   return type.many ? `${text}[]` : text;
 }
+function writeDescription(text) {
+  const attached = text.replace(/[ \t]+\?(?=[ \t]|$)/g, "?");
+  return /^\?([ \t]|$)/.test(attached) ? `#${attached}` : `# ${attached}`;
+}
+var rewordsDescription = (text) => writeDescription(text) !== `# ${text}`;
 function withTrailer(head, node) {
   const parts2 = [];
   if (node.description !== void 0 && node.description !== "")
-    parts2.push(`# ${node.description}`);
+    parts2.push(writeDescription(node.description));
   if (node.note !== void 0 && node.note !== "") parts2.push(`? ${node.note}`);
   if (parts2.length === 0) return head;
   const gap = head.length < TRAILER_COLUMN - 1 ? " ".repeat(TRAILER_COLUMN - head.length) : "  ";
@@ -990,6 +1011,7 @@ var QUIET_SCHEMA_KEYS = /* @__PURE__ */ new Set([
   "slots",
   "enums"
 ]);
+var REWORDED = "a standalone `?` is attached to the word before it";
 var UNKNOWN_TYPE = /^[a-z][a-z0-9_-]*$/;
 function fromLinkML(schema) {
   const root = asRecord(schema);
@@ -1033,7 +1055,7 @@ function fromLinkML(schema) {
     const rawValues = get(asRecord(get(enumDefs, key2)) ?? {}, "permissible_values");
     const values = asRecord(rawValues);
     const keys = Object.keys(values ?? {});
-    const bad = keys.find((value) => !SYSTEM_OR_VALUE.test(value));
+    const bad = keys.find((value) => !ENUM_VALUE.test(value));
     if (values === void 0 && present(rawValues)) {
       unwritable.set(key2, `${shown(rawValues)} is not a map of permissible values`);
     } else if (keys.length < 2) {
@@ -1064,14 +1086,26 @@ function fromLinkML(schema) {
       }
       continue;
     }
+    const undeclared = annotations.get("undeclared");
+    if (undeclared !== void 0 && typeof undeclared !== "boolean") {
+      report("annotation", name2, notText("undeclared", undeclared));
+    }
     const node = { name: at0(name2), fields: [], line: 0 };
     const description = oneLine(stringOf(get(def, "description")));
-    if (description !== void 0) node.description = description;
+    if (description !== void 0) {
+      node.description = description;
+      if (rewordsDescription(description)) report("reworded", name2, REWORDED);
+    }
     const system = annotations.get("system");
-    if (typeof system === "string" && SYSTEM_OR_VALUE.test(system)) node.system = at0(system);
-    else if (system !== void 0) report("annotation", name2, "`system` is not a system name");
-    const note = oneLine(stringOf(annotations.get("note")));
-    if (note !== void 0) node.note = note;
+    if (typeof system === "string") {
+      if (SYSTEM_NAME.test(system)) node.system = at0(system);
+      else report("annotation", name2, "`system` is not a system name");
+    } else if (system !== void 0) report("annotation", name2, notText("system", system));
+    const rawNote = annotations.get("note");
+    if (typeof rawNote === "string") {
+      const note = oneLine(rawNote);
+      if (note !== void 0) node.note = note;
+    } else if (rawNote !== void 0) report("annotation", name2, notText("note", rawNote));
     const mappings = stringList(get(def, "close_mappings"));
     const first = mappings[0];
     const target = first === void 0 ? "" : localName(first);
@@ -1176,13 +1210,18 @@ function fromLinkML(schema) {
       line: 0
     };
     const description = oneLine(stringOf(get(def, "description")));
-    if (description !== void 0) field.description = description;
+    if (description !== void 0) {
+      field.description = description;
+      if (rewordsDescription(description)) report("reworded", element, REWORDED);
+    }
     const type = typeFor(element, name2, def);
     if (type !== void 0) field.type = type;
     const annotations = annotationsOf(def);
     const system = annotations.get("system");
-    if (typeof system === "string" && SYSTEM_OR_VALUE.test(system)) field.system = at0(system);
-    else if (system !== void 0) report("annotation", element, "`system` is not a system name");
+    if (typeof system === "string") {
+      if (SYSTEM_NAME.test(system)) field.system = at0(system);
+      else report("annotation", element, "`system` is not a system name");
+    } else if (system !== void 0) report("annotation", element, notText("system", system));
     const joins = annotations.get("joins_to");
     if (typeof joins === "string") {
       const dot = joins.indexOf(".");
@@ -1195,9 +1234,12 @@ function fromLinkML(schema) {
         reference(element, target, targetClass);
         reference(element, targetField, targetName);
       } else report("annotation", element, "`joins_to` is not `Class.field`");
-    } else if (joins !== void 0) report("annotation", element, "`joins_to` is not text");
-    const note = oneLine(stringOf(annotations.get("note")));
-    if (note !== void 0) field.note = note;
+    } 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);
+      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)) {
       if (!SLOT_KEYS.has(other)) {
         report(other, element);
@@ -1272,13 +1314,17 @@ var COUNTED = {
   class: ["class", "classes"],
   slot: ["slot", "slots"],
   schema: ["schema key", "schema keys"],
+  narrowed: ["narrowed range", "narrowed ranges"],
+  enum_detail: ["enum detail", "enum details"],
+  annotation: ["unreadable annotation", "unreadable annotations"],
+  reworded: ["description reworded", "descriptions reworded"],
   // `mixin: true` marks the class; `mixins: [M]` points at another one.
   mixin: ["mixin class", "mixin classes"],
   mixins: ["mixin", "mixins"],
   pattern: ["pattern", "patterns"],
   unit: ["unit", "units"]
 };
-var ENUM_KINDS = /* @__PURE__ */ new Set(["enum_detail"]);
+var UNREADABLE = "unreadable";
 function formatDropped(dropped) {
   const groups = /* @__PURE__ */ new Map();
   for (const entry of dropped) {
@@ -1287,15 +1333,21 @@ function formatDropped(dropped) {
     else group.push(entry);
   }
   const drops = [];
+  const notRead = [];
   let renamed = "";
   let inlined = "";
   for (const [kind, entries] of groups) {
+    if (kind === UNREADABLE) {
+      for (const entry of entries) notRead.push(entry.detail ?? "the schema could not be read");
+      continue;
+    }
     const phrase = phraseFor(kind, entries);
     if (kind === "renamed") renamed = phrase;
     else if (kind === "inlined") inlined = phrase;
     else drops.push(phrase);
   }
   const sentences = [];
+  if (notRead.length > 0) sentences.push(`Not read: ${notRead.join("; ")}.`);
   if (drops.length > 0) sentences.push(`Dropped: ${drops.join(", ")}.`);
   if (renamed !== "") sentences.push(`Renamed: ${renamed}.`);
   if (inlined !== "") sentences.push(`Inlined: ${inlined}.`);
@@ -1305,11 +1357,10 @@ function phraseFor(kind, entries) {
   const n = entries.length;
   const counted = Object.hasOwn(COUNTED, kind) ? COUNTED[kind] : void 0;
   if (counted !== void 0) return `${n} ${n === 1 ? counted[0] : counted[1]}`;
-  return `${kind} on ${n} ${nounFor(kind, entries)}`;
+  return `${kind} on ${n} ${nounFor(entries)}`;
 }
-function nounFor(kind, entries) {
+function nounFor(entries) {
   const one = entries.length === 1;
-  if (ENUM_KINDS.has(kind)) return one ? "enum" : "enums";
   const slots = entries.filter((entry) => entry.element.includes(".")).length;
   if (slots === entries.length) return one ? "slot" : "slots";
   if (slots === 0) return one ? "class" : "classes";
@@ -1360,12 +1411,18 @@ function annotationsOf(def) {
   if (annotations === void 0) return out;
   for (const tag of Object.keys(annotations)) {
     const raw = get(annotations, tag);
-    const value = asRecord(raw) === void 0 ? raw : get(asRecord(raw) ?? {}, "value");
-    if (typeof value === "string" || typeof value === "boolean") out.set(tag, value);
-    else out.set(tag, String(value));
+    const long = asRecord(raw);
+    const value = long === void 0 ? raw : get(long, "value");
+    out.set(tag, value ?? null);
   }
   return out;
 }
+function notText(tag, value) {
+  if (value === null) return `\`${tag}\` was written with no value`;
+  if (Array.isArray(value)) return `\`${tag}\` is a list, not text`;
+  if (typeof value === "object") return `\`${tag}\` is a map, not text`;
+  return `\`${tag}\` is a ${typeof value}, not text`;
+}
 function slotKeysOf(def) {
   const keys = Object.keys(asRecord(get(def, "attributes")) ?? {});
   for (const slot of stringList(get(def, "slots"))) {
@@ -1390,7 +1447,7 @@ var schemaElement = (root) => stringOf(get(root, "name")) ?? "schema";
 var nothing = (element, detail) => ({
   document: parse(""),
   source: "",
-  dropped: [{ kind: "schema", element, detail }]
+  dropped: [{ kind: UNREADABLE, element, detail }]
 });
 
 // src/import.ts
@@ -1417,7 +1474,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 
 // src/cli.ts
 var HELP = `Usage: skiss <command> [options]
@@ -1450,7 +1507,8 @@ wrote has, so their line numbers are lines of that sketch.
 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
+  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
   70 internal error, a bug in skiss
 `;
 var EXIT_OK = 0;
@@ -1520,9 +1578,15 @@ async function main(argv) {
 `);
   if (values.output === void 0) process.stdout.write(output);
   else await writeOutput(values.output, output);
+  if (unreadableInput(command, diagnostics, dropped)) return EXIT_USAGE;
   const strict = values.strict === true && (diagnostics.length > 0 || dropped.length > 0);
   return strict ? EXIT_STRICT : EXIT_OK;
 }
+function unreadableInput(command, diagnostics, dropped) {
+  if (command !== "import") return false;
+  if (dropped.some((entry) => entry.kind === "unreadable")) return true;
+  return diagnostics.some((d) => d.code === "E_NOT_YAML");
+}
 function runCommand(command, source, file, values) {
   if (command === "import") return importLinkML(source);
   if (command === "compile") {
@@ -1568,6 +1632,12 @@ function reason(error) {
   }
   return String(error);
 }
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (error) => {
+    if (error.code === "EPIPE") process.exit(EXIT_OK);
+    throw error;
+  });
+}
 main(process.argv.slice(2)).then(
   (code) => {
     process.exitCode = code;

package/dist/index.d.ts

@@ -68,7 +68,7 @@ type Severity = 'error' | 'warning';
  * `resolve` the `W_` codes, and `importLinkML` the one code of its own,
  * `E_NOT_YAML`, for a text no schema can be read out of.
  */
-type DiagnosticCode = 'E_UNPARSABLE' | 'E_FIELD_WITHOUT_CLASS' | 'E_MISSING_TYPE' | 'E_UNCLOSED_MANY' | 'E_BAD_NAME' | 'W_UNKNOWN_TYPE' | 'W_UNDECLARED_CLASS' | 'W_UNDECLARED_FIELD' | 'W_DUPLICATE_CLASS' | 'W_DUPLICATE_FIELD' | 'W_MULTIPLE_IDENTIFIERS' | 'E_NOT_YAML';
+type DiagnosticCode = 'E_UNPARSABLE' | 'E_FIELD_WITHOUT_CLASS' | 'E_MISSING_TYPE' | 'E_UNCLOSED_MANY' | 'E_BAD_NAME' | 'W_UNKNOWN_TYPE' | 'W_UNDECLARED_CLASS' | 'W_UNDECLARED_FIELD' | 'W_DUPLICATE_CLASS' | 'W_DUPLICATE_FIELD' | 'W_DUPLICATE_ENUM_VALUE' | 'W_MULTIPLE_IDENTIFIERS' | 'E_NOT_YAML';
 interface Diagnostic {
     severity: Severity;
     code: DiagnosticCode;
@@ -175,9 +175,9 @@ declare function formatDiagnostic(d: Diagnostic, file?: string): string;
 /**
  * One thing the projection could not carry. `kind` is the LinkML key, or one
  * of the projection's own kinds: `renamed`, `narrowed`, `inlined`,
- * `enum_detail`, `annotation`, `schema`. `element` names what carried it as
- * the sketch names it — `Class`, `Class.field` — or, for an enum, its LinkML
- * name, which the sketch does not keep.
+ * `enum_detail`, `annotation`, `reworded`, `schema`, `unreadable`. `element`
+ * names what carried it as the sketch names it — `Class`, `Class.field` — or,
+ * for an enum, its LinkML name, which the sketch does not keep.
  */
 interface Dropped {
     kind: string;
@@ -215,6 +215,6 @@ interface ResolvedDocument extends Document {
 }
 declare function resolve(doc: Document): ResolvedDocument;
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.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 TypeRef, VERSION, compile, formatDiagnostic, formatDropped, fromLinkML, importLinkML, parse, resolve, serialize, toLinkML, toMermaid, toSkiss };