@eriknaslund/skiss 0.6.0 → 0.7.0

package/README.md

@@ -25,6 +25,10 @@ CharacterPage @Community ~ Character    # the community wiki's version
 
 That is the whole language. Classes at column 0, fields indented under them, a handful of punctuation marks.
 
+**Try it live:** <https://erik-naslund.github.io/skiss-playground/> draws a sketch as you type, shares it as a link and exports SVG, PNG and LinkML. Nothing to install, nothing leaves your browser.
+
+**Let an assistant write it:** [`skills/skiss`](skills/skiss/SKILL.md) is an agent skill for Claude, a custom GPT or any assistant with a system prompt, so it writes valid Skiss and draws it, with or without the compiler at hand.
+
 ## Why
 
 You sit down with someone who knows the domain. Within the hour you want a shared picture of it: what the things are, what they are called, which system owns them, how they hang together.
@@ -43,6 +47,7 @@ Skiss is text you can type while someone talks. A field is one line. A change is
 - **`~` 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.
+- **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.
 
@@ -73,7 +78,7 @@ Or without installing: `npx @eriknaslund/skiss diagram model.skiss`.
 
 `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.
+Editors that render Skiss live are separate projects built on this package. This repository is the language, the library and the command line. To try the language without installing anything, open the [playground](https://erik-naslund.github.io/skiss-playground/): write a sketch, watch the diagram, share a link. Inside Obsidian, the [obsidian-skiss](https://github.com/erik-naslund/obsidian-skiss) plugin renders `skiss` code blocks in your notes.
 
 ## Where to look
 
@@ -89,9 +94,9 @@ Editors that render Skiss live are separate projects built on this package. This
 
 ## Status
 
-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.
+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.
 
-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.
+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.
 
 ## License
 

package/dist/cli.js

@@ -94,6 +94,21 @@ var CLASS_NAME = /^[A-Z][A-Za-z0-9]*$/;
 var FIELD_NAME = /^[a-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 NAME_CHAR = /^[A-Za-z0-9]$/;
+var WORD_CHAR = /^[A-Za-z0-9_-]$/;
+var CLASS_RULE = "UpperCamelCase in ASCII letters and digits (A-Z, a-z, 0-9), uppercase first";
+var FIELD_RULE = "lowerCamelCase in ASCII letters and digits (a-z, A-Z, 0-9), lowercase first";
+function nameFault(text, allowed) {
+  for (const ch of text) {
+    if (!allowed.test(ch)) return `\`${ch}\` is not one of them.`;
+  }
+  const first = text.slice(0, 1);
+  const kind = /[A-Z]/.test(first) ? "an uppercase letter" : /[a-z]/.test(first) ? "a lowercase letter" : /[0-9]/.test(first) ? "a digit" : `\`${first}\``;
+  return `\`${text}\` starts with ${kind}.`;
+}
+function badName(rule, text, allowed = NAME_CHAR) {
+  return `${rule}: \`${text}\`. ${nameFault(text, allowed)}`;
+}
 var PRIMITIVES = {
   string: "string",
   int: "int",
@@ -109,6 +124,7 @@ var PRIMITIVES = {
 function primitiveFor(word) {
   return Object.hasOwn(PRIMITIVES, word) ? PRIMITIVES[word] : void 0;
 }
+var DROPPED = "dropped-class";
 var FIELD_ORDER = "name, `*`, `: type`, `@System`, `= Class.field`, then `#` and `?`";
 var CLASS_ORDER = "name, `< Parent`, `@System`, `~ Class`, then `#` and `?`";
 function parse(source) {
@@ -136,8 +152,8 @@ function parse(source) {
         continue;
       }
       const result = parseFieldLine(text, line);
-      if (result.ok) current.fields.push(result.value);
-      else diagnostics.push(result.diagnostic);
+      if (!result.ok) diagnostics.push(result.diagnostic);
+      else if (current !== DROPPED) current.fields.push(result.value);
       continue;
     }
     if (/\p{L}/u.test(first)) {
@@ -147,7 +163,7 @@ function parse(source) {
         current = result.value;
       } else {
         diagnostics.push(result.diagnostic);
-        current = void 0;
+        current = result.atName ? DROPPED : void 0;
       }
       continue;
     }
@@ -236,10 +252,11 @@ function take(c) {
   return t;
 }
 var name = (t, line) => ({ text: t.text, line, col: t.col, end: t.end });
-function fail(code, message, line, span) {
+function fail(code, message, line, span, atName = false) {
   return {
     ok: false,
-    diagnostic: { severity: "error", code, message, line, col: span.col, end: span.end }
+    diagnostic: { severity: "error", code, message, line, col: span.col, end: span.end },
+    atName
   };
 }
 var afterSpan = (after) => ({ col: after.end, end: after.end });
@@ -248,17 +265,21 @@ function parseClassLine(text, line) {
   const c = { tokens: tokenize(trailer.head), pos: 0, line };
   const head = take(c);
   if (head === void 0 || head.kind !== "word") {
-    return fail("E_UNPARSABLE", "A class line must start with a class name", line, {
-      col: 0,
-      end: Math.max(1, trailer.head.length)
-    });
+    return fail(
+      "E_UNPARSABLE",
+      "A class line must start with a class name",
+      line,
+      { col: 0, end: Math.max(1, trailer.head.length) },
+      true
+    );
   }
   if (!CLASS_NAME.test(head.text)) {
     return fail(
       "E_BAD_NAME",
-      `Class names are UpperCamelCase (letters and digits, uppercase first): \`${head.text}\``,
+      badName(`Class names are ${CLASS_RULE}`, head.text),
       line,
-      head
+      head,
+      true
     );
   }
   const node = { name: name(head, line), line };
@@ -291,9 +312,10 @@ function parseClassLine(text, line) {
     if (!CLASS_NAME.test(target.text)) {
       return fail(
         "E_BAD_NAME",
-        `The class after \`~\` must be UpperCamelCase: \`${target.text}\``,
+        badName(`The class after \`~\` must be ${CLASS_RULE}`, target.text),
         line,
-        target
+        target,
+        true
       );
     }
     node.similarTo = name(target, line);
@@ -315,12 +337,7 @@ function parseFieldLine(text, line) {
   }
   if (head.kind !== "word") return unexpected(head, line, "field", FIELD_ORDER);
   if (!FIELD_NAME.test(head.text)) {
-    return fail(
-      "E_BAD_NAME",
-      `Field names are lowerCamelCase (letters and digits, lowercase first): \`${head.text}\``,
-      line,
-      head
-    );
+    return fail("E_BAD_NAME", badName(`Field names are ${FIELD_RULE}`, head.text), line, head);
   }
   const node = { name: name(head, line), line, identifier: false };
   const star = peek(c);
@@ -359,7 +376,7 @@ function parseFieldLine(text, line) {
     if (!CLASS_NAME.test(className.text)) {
       return fail(
         "E_BAD_NAME",
-        `The class after \`=\` must be UpperCamelCase: \`${className.text}\``,
+        badName(`The class after \`=\` must be ${CLASS_RULE}`, className.text),
         line,
         className
       );
@@ -385,7 +402,7 @@ function parseFieldLine(text, line) {
     if (!FIELD_NAME.test(fieldName.text)) {
       return fail(
         "E_BAD_NAME",
-        `The field after \`= ${className.text}.\` must be lowerCamelCase: \`${fieldName.text}\``,
+        badName(`The field after \`= ${className.text}.\` must be ${FIELD_RULE}`, fieldName.text),
         line,
         fieldName
       );
@@ -409,8 +426,8 @@ function parseParent(c, 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 message = Object.hasOwn(PRIMITIVES, parent.text) ? `\`${parent.text}\` is a primitive, not a class; a parent is a class` : badName(`The class after \`<\` must be ${CLASS_RULE}`, parent.text);
+    return fail("E_BAD_NAME", message, c.line, parent, true);
   }
   const next = peek(c);
   if (next?.kind === "," || next?.kind === "<") {
@@ -436,7 +453,11 @@ function parseSystem(c, at) {
   if (!SYSTEM_NAME.test(system.text)) {
     return fail(
       "E_UNPARSABLE",
-      `A system name is letters, digits, \`-\` and \`_\`, starting with a letter: \`${system.text}\``,
+      badName(
+        "A system name is ASCII letters, digits, `-` and `_` (A-Z, a-z, 0-9), starting with a letter",
+        system.text,
+        WORD_CHAR
+      ),
       c.line,
       system
     );
@@ -494,7 +515,11 @@ function parseType(c, colon) {
       if (!ENUM_VALUE.test(w.text)) {
         return fail(
           "E_UNPARSABLE",
-          `An enum value is letters, digits, \`-\` and \`_\`, and does not start with \`-\` or \`_\`: \`${w.text}\``,
+          badName(
+            "An enum value is ASCII letters, digits, `-` and `_` (A-Z, a-z, 0-9), and does not start with `-` or `_`",
+            w.text,
+            WORD_CHAR
+          ),
           c.line,
           w
         );
@@ -514,7 +539,7 @@ function parseType(c, colon) {
     if (!CLASS_NAME.test(word)) {
       return fail(
         "E_BAD_NAME",
-        `A referenced class must be UpperCamelCase: \`${word}\``,
+        badName(`A referenced class must be ${CLASS_RULE}`, word),
         c.line,
         first
       );
@@ -986,9 +1011,7 @@ function toMermaid(doc, opts) {
     for (const field of cls.fields) {
       const type = field.type;
       if (type?.kind === "class") {
-        lines.push(
-          type.many ? `  ${from} "1" --> "*" ${type.name.text} : ${field.name.text}` : `  ${from} --> ${type.name.text} : ${field.name.text}`
-        );
+        lines.push(`  ${from} --> ${type.name.text} : ${field.name.text}`);
       }
       if (field.joinsTo !== void 0) {
         const { className, fieldName } = field.joinsTo;
@@ -1670,7 +1693,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 
 // src/cli.ts
 var HELP = `Usage: skiss <command> [options]

package/dist/index.d.ts

@@ -268,6 +268,6 @@ interface ResolvedDocument extends Document {
 }
 declare function resolve(doc: Document): ResolvedDocument;
 
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.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 };

package/dist/index.js

@@ -84,6 +84,21 @@ var CLASS_NAME = /^[A-Z][A-Za-z0-9]*$/;
 var FIELD_NAME = /^[a-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 NAME_CHAR = /^[A-Za-z0-9]$/;
+var WORD_CHAR = /^[A-Za-z0-9_-]$/;
+var CLASS_RULE = "UpperCamelCase in ASCII letters and digits (A-Z, a-z, 0-9), uppercase first";
+var FIELD_RULE = "lowerCamelCase in ASCII letters and digits (a-z, A-Z, 0-9), lowercase first";
+function nameFault(text, allowed) {
+  for (const ch of text) {
+    if (!allowed.test(ch)) return `\`${ch}\` is not one of them.`;
+  }
+  const first = text.slice(0, 1);
+  const kind = /[A-Z]/.test(first) ? "an uppercase letter" : /[a-z]/.test(first) ? "a lowercase letter" : /[0-9]/.test(first) ? "a digit" : `\`${first}\``;
+  return `\`${text}\` starts with ${kind}.`;
+}
+function badName(rule, text, allowed = NAME_CHAR) {
+  return `${rule}: \`${text}\`. ${nameFault(text, allowed)}`;
+}
 var PRIMITIVES = {
   string: "string",
   int: "int",
@@ -99,6 +114,7 @@ var PRIMITIVES = {
 function primitiveFor(word) {
   return Object.hasOwn(PRIMITIVES, word) ? PRIMITIVES[word] : void 0;
 }
+var DROPPED = "dropped-class";
 var FIELD_ORDER = "name, `*`, `: type`, `@System`, `= Class.field`, then `#` and `?`";
 var CLASS_ORDER = "name, `< Parent`, `@System`, `~ Class`, then `#` and `?`";
 function parse(source) {
@@ -126,8 +142,8 @@ function parse(source) {
         continue;
       }
       const result = parseFieldLine(text, line);
-      if (result.ok) current.fields.push(result.value);
-      else diagnostics.push(result.diagnostic);
+      if (!result.ok) diagnostics.push(result.diagnostic);
+      else if (current !== DROPPED) current.fields.push(result.value);
       continue;
     }
     if (/\p{L}/u.test(first)) {
@@ -137,7 +153,7 @@ function parse(source) {
         current = result.value;
       } else {
         diagnostics.push(result.diagnostic);
-        current = void 0;
+        current = result.atName ? DROPPED : void 0;
       }
       continue;
     }
@@ -226,10 +242,11 @@ function take(c) {
   return t;
 }
 var name = (t, line) => ({ text: t.text, line, col: t.col, end: t.end });
-function fail(code, message, line, span) {
+function fail(code, message, line, span, atName = false) {
   return {
     ok: false,
-    diagnostic: { severity: "error", code, message, line, col: span.col, end: span.end }
+    diagnostic: { severity: "error", code, message, line, col: span.col, end: span.end },
+    atName
   };
 }
 var afterSpan = (after) => ({ col: after.end, end: after.end });
@@ -238,17 +255,21 @@ function parseClassLine(text, line) {
   const c = { tokens: tokenize(trailer.head), pos: 0, line };
   const head = take(c);
   if (head === void 0 || head.kind !== "word") {
-    return fail("E_UNPARSABLE", "A class line must start with a class name", line, {
-      col: 0,
-      end: Math.max(1, trailer.head.length)
-    });
+    return fail(
+      "E_UNPARSABLE",
+      "A class line must start with a class name",
+      line,
+      { col: 0, end: Math.max(1, trailer.head.length) },
+      true
+    );
   }
   if (!CLASS_NAME.test(head.text)) {
     return fail(
       "E_BAD_NAME",
-      `Class names are UpperCamelCase (letters and digits, uppercase first): \`${head.text}\``,
+      badName(`Class names are ${CLASS_RULE}`, head.text),
       line,
-      head
+      head,
+      true
     );
   }
   const node = { name: name(head, line), line };
@@ -281,9 +302,10 @@ function parseClassLine(text, line) {
     if (!CLASS_NAME.test(target.text)) {
       return fail(
         "E_BAD_NAME",
-        `The class after \`~\` must be UpperCamelCase: \`${target.text}\``,
+        badName(`The class after \`~\` must be ${CLASS_RULE}`, target.text),
         line,
-        target
+        target,
+        true
       );
     }
     node.similarTo = name(target, line);
@@ -305,12 +327,7 @@ function parseFieldLine(text, line) {
   }
   if (head.kind !== "word") return unexpected(head, line, "field", FIELD_ORDER);
   if (!FIELD_NAME.test(head.text)) {
-    return fail(
-      "E_BAD_NAME",
-      `Field names are lowerCamelCase (letters and digits, lowercase first): \`${head.text}\``,
-      line,
-      head
-    );
+    return fail("E_BAD_NAME", badName(`Field names are ${FIELD_RULE}`, head.text), line, head);
   }
   const node = { name: name(head, line), line, identifier: false };
   const star = peek(c);
@@ -349,7 +366,7 @@ function parseFieldLine(text, line) {
     if (!CLASS_NAME.test(className.text)) {
       return fail(
         "E_BAD_NAME",
-        `The class after \`=\` must be UpperCamelCase: \`${className.text}\``,
+        badName(`The class after \`=\` must be ${CLASS_RULE}`, className.text),
         line,
         className
       );
@@ -375,7 +392,7 @@ function parseFieldLine(text, line) {
     if (!FIELD_NAME.test(fieldName.text)) {
       return fail(
         "E_BAD_NAME",
-        `The field after \`= ${className.text}.\` must be lowerCamelCase: \`${fieldName.text}\``,
+        badName(`The field after \`= ${className.text}.\` must be ${FIELD_RULE}`, fieldName.text),
         line,
         fieldName
       );
@@ -399,8 +416,8 @@ function parseParent(c, 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 message = Object.hasOwn(PRIMITIVES, parent.text) ? `\`${parent.text}\` is a primitive, not a class; a parent is a class` : badName(`The class after \`<\` must be ${CLASS_RULE}`, parent.text);
+    return fail("E_BAD_NAME", message, c.line, parent, true);
   }
   const next = peek(c);
   if (next?.kind === "," || next?.kind === "<") {
@@ -426,7 +443,11 @@ function parseSystem(c, at) {
   if (!SYSTEM_NAME.test(system.text)) {
     return fail(
       "E_UNPARSABLE",
-      `A system name is letters, digits, \`-\` and \`_\`, starting with a letter: \`${system.text}\``,
+      badName(
+        "A system name is ASCII letters, digits, `-` and `_` (A-Z, a-z, 0-9), starting with a letter",
+        system.text,
+        WORD_CHAR
+      ),
       c.line,
       system
     );
@@ -484,7 +505,11 @@ function parseType(c, colon) {
       if (!ENUM_VALUE.test(w.text)) {
         return fail(
           "E_UNPARSABLE",
-          `An enum value is letters, digits, \`-\` and \`_\`, and does not start with \`-\` or \`_\`: \`${w.text}\``,
+          badName(
+            "An enum value is ASCII letters, digits, `-` and `_` (A-Z, a-z, 0-9), and does not start with `-` or `_`",
+            w.text,
+            WORD_CHAR
+          ),
           c.line,
           w
         );
@@ -504,7 +529,7 @@ function parseType(c, colon) {
     if (!CLASS_NAME.test(word)) {
       return fail(
         "E_BAD_NAME",
-        `A referenced class must be UpperCamelCase: \`${word}\``,
+        badName(`A referenced class must be ${CLASS_RULE}`, word),
         c.line,
         first
       );
@@ -976,9 +1001,7 @@ function toMermaid(doc, opts) {
     for (const field of cls.fields) {
       const type = field.type;
       if (type?.kind === "class") {
-        lines.push(
-          type.many ? `  ${from} "1" --> "*" ${type.name.text} : ${field.name.text}` : `  ${from} --> ${type.name.text} : ${field.name.text}`
-        );
+        lines.push(`  ${from} --> ${type.name.text} : ${field.name.text}`);
       }
       if (field.joinsTo !== void 0) {
         const { className, fieldName } = field.joinsTo;
@@ -1858,7 +1881,7 @@ function notYAML(error) {
 }
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 export {
   VERSION,
   compile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eriknaslund/skiss",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A text notation for sketching data models, compiled to LinkML",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.13",
-    "@mermaid-js/mermaid-cli": "^11.17.0",
+    "@mermaid-js/mermaid-cli": "^12.0.0",
     "@types/node": "^26.6.1",
     "jsdom": "^30.0.1",
     "mermaid": "^12.0.0",