@dxos/diagram 0.11.1 → 0.13.0

package/src/dsl/cli.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Converts a diagram source into DSL text: `moon run diagram:convert -- <file>`, or stdin.
+// A file rather than a library call because the point of the DSL is that a scene becomes something
+// you check in, and the first step of doing that is getting the text out.
+//
+
+import * as Effect from 'effect/Effect';
+import { readFileSync } from 'node:fs';
+
+import * as EffectEx from '@dxos/effect/EffectEx';
+
+import { SOURCES, convert } from './convert.ts';
+
+const USAGE = `Usage: convert [--source <${SOURCES.map(({ id }) => id).join('|')}>] [<file>]
+
+Reads a diagram source (stdin when no file is given) and writes the equivalent DSL.
+The output is the laid-out form: the dialect places everything, and the text is the result.
+
+Sources:
+${SOURCES.map(({ id, description }) => `  ${id.padEnd(16)} ${description}`).join('\n')}`;
+
+const main = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    return;
+  }
+
+  const at = args.indexOf('--source');
+  const source = at === -1 ? undefined : args[at + 1];
+  // `at + 1` is only a value index when the flag is present; `-1 + 1 === 0` would otherwise eat
+  // the first positional argument and silently read stdin instead of the named file.
+  const [file] = args.filter((arg, index) => !arg.startsWith('-') && !(at !== -1 && index === at + 1));
+  const text = readFileSync(file ?? 0, 'utf8');
+
+  process.stdout.write(yield* convert(text, { source }));
+});
+
+EffectEx.runPromise(main).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/src/dsl/compile.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SemanticEngine from '../semantic-engine.ts';
+import { type ParseResult, read, withLayout } from './parse.ts';
+
+/** Options for {@link compile}. */
+export type CompileOptions = Pick<SemanticEngine.SolveOptions, 'emitCandidate'>;
+
+/**
+ * Reads a document and lays out its semantic statements with the full search, which also tries the
+ * mermaid engine's placements when nothing was hinted. Asynchronous only because that engine's ELK
+ * is; a document of scene statements alone reads exactly as {@link parse} reads it.
+ */
+export const compile: (text: string, options?: CompileOptions) => Effect.Effect<ParseResult> = Effect.fn('Dsl.compile')(
+  function* (text: string, options: CompileOptions = {}) {
+    const reading = read(text);
+    const { diagram } = reading;
+    if (!diagram) {
+      return withLayout(reading);
+    }
+    const solution = yield* Effect.promise(() => SemanticEngine.compile(diagram, options));
+    return withLayout(reading, solution);
+  },
+);

package/src/dsl/convert.test.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as EffectEx from '@dxos/effect/EffectEx';
+
+import { BASIC, CLASS_DIAGRAM } from '../testing.ts';
+import { UndetectedSourceError, UnknownSourceError, convert, detect } from './convert.ts';
+import { parse } from './parse.ts';
+import { printCommands } from './print.ts';
+
+describe('convert', () => {
+  test('detects a flowchart and a classDiagram', ({ expect }) => {
+    expect(detect(BASIC.trim())?.id).toEqual('mermaid');
+    expect(detect(CLASS_DIAGRAM.trim())?.id).toEqual('uml');
+    expect(detect('not a diagram')).toBeUndefined();
+  });
+
+  for (const [name, source] of Object.entries({ BASIC, CLASS_DIAGRAM })) {
+    test(`${name} converts to DSL that parses back cleanly`, async ({ expect }) => {
+      const text = await EffectEx.runPromise(convert(source.trim()));
+      const { commands, problems } = parse(text);
+      expect(problems).toEqual([]);
+      expect(commands.length).toBeGreaterThan(0);
+      // Output is canonical, so converting and reprinting is a fixed point.
+      expect(printCommands(commands)).toEqual(text);
+    });
+  }
+
+  test('the emitted form is post-layout — every object carries an origin', async ({ expect }) => {
+    const { commands } = parse(await EffectEx.runPromise(convert(BASIC.trim())));
+    const upserts = commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
+    expect(upserts.length).toBeGreaterThan(0);
+    expect(upserts.every(({ origin }) => origin !== undefined)).toBe(true);
+  });
+
+  test('an explicit source overrides detection', async ({ expect }) => {
+    const elk = await EffectEx.runPromise(convert(BASIC.trim()));
+    const layered = await EffectEx.runPromise(convert(BASIC.trim(), { source: 'mermaid-layered' }));
+    expect(parse(layered).problems).toEqual([]);
+    // Same graph, different placement engine, so the text must differ.
+    expect(layered).not.toEqual(elk);
+  });
+
+  test('an unusable input fails with a typed error rather than throwing', async ({ expect }) => {
+    await expect(EffectEx.runPromise(convert('not a diagram'))).rejects.toThrow(UndetectedSourceError);
+    await expect(EffectEx.runPromise(convert(BASIC.trim(), { source: 'd2' }))).rejects.toThrow(UnknownSourceError);
+  });
+});

package/src/dsl/convert.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Text in another diagram language, out as ours. Every source language already compiles to
+// `Scene.Command[]`, and the DSL already prints those, so a converter is the two halves joined —
+// which is why adding a dialect costs nothing here.
+//
+// The output is the POST-layout form, and there is no other option: the DSL has no unpositioned
+// node to emit. That is the point of converting — you run mermaid once to get a layout, then keep
+// the result as something you can hand-tune, diff and review. See `docs/DSL.md`.
+//
+
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+import * as MermaidEngine from '../mermaid-engine.ts';
+import * as Mermaid from '../mermaid.ts';
+import type * as Scene from '../scene.ts';
+import * as Uml from '../uml.ts';
+import { printCommands } from './print.ts';
+
+/** A source language that can be turned into DSL text. */
+export type Source = {
+  id: string;
+  description: string;
+  /** True when a source string looks like this language, for `convert` to pick without being told. */
+  detect: (source: string) => boolean;
+  compile: (source: string) => Effect.Effect<readonly Scene.Command[]>;
+};
+
+/** Mermaid `classDiagram`, laid out synchronously by the UML engine. */
+export const umlSource: Source = {
+  id: 'uml',
+  description: 'Mermaid classDiagram.',
+  detect: Uml.isClassDiagram,
+  compile: (source) => Effect.sync(() => Uml.compile(source)),
+};
+
+/**
+ * Mermaid `flowchart`, laid out by the ELK-backed engine. ELK is promise-based, so the platform
+ * boundary sits here rather than leaking a Promise into the rest of the pipeline.
+ */
+export const mermaidSource: Source = {
+  id: 'mermaid',
+  description: 'Mermaid flowchart, including the `%% ref` and UML edge-token extensions.',
+  detect: (source) => /^\s*(flowchart|graph)\s+/m.test(source),
+  compile: (source) => Effect.promise(() => MermaidEngine.compile(source)),
+};
+
+/** Mermaid flowchart without the ELK pass — the simple layered placement in `mermaid.ts`. */
+export const mermaidLayeredSource: Source = {
+  id: 'mermaid-layered',
+  description: "Mermaid flowchart with the dialect's own layered placement rather than ELK.",
+  detect: () => false,
+  compile: (source) => Effect.sync(() => Mermaid.compile(source)),
+};
+
+export const SOURCES: readonly Source[] = [umlSource, mermaidSource, mermaidLayeredSource];
+
+/** The language a source string is written in, or undefined when nothing claims it. */
+export const detect = (source: string): Source | undefined => SOURCES.find(({ detect }) => detect(source));
+
+const known = () => SOURCES.map(({ id }) => id).join(', ');
+
+/** Tagged so the failure channel stays discriminated rather than collapsing into bare `Error`. */
+export class UnknownSourceError extends Data.TaggedError('DiagramUnknownSource')<{ id: string }> {
+  override get message(): string {
+    return `Unknown source language "${this.id}"; known: ${known()}.`;
+  }
+}
+
+export class UndetectedSourceError extends Data.TaggedError('DiagramUndetectedSource')<{}> {
+  override get message(): string {
+    return `Could not tell what language this is; pass one of: ${known()}.`;
+  }
+}
+
+export type ConvertOptions = {
+  /** Force a language instead of detecting one. */
+  source?: string;
+};
+
+/** Compiles `text` through its dialect and prints the result as DSL text. */
+export const convert = (
+  text: string,
+  { source }: ConvertOptions = {},
+): Effect.Effect<string, UnknownSourceError | UndetectedSourceError> =>
+  Effect.gen(function* () {
+    const language = source === undefined ? detect(text) : SOURCES.find(({ id }) => id === source);
+    if (!language) {
+      return yield* Effect.fail(
+        source === undefined ? new UndetectedSourceError() : new UnknownSourceError({ id: source }),
+      );
+    }
+    return printCommands(yield* language.compile(text));
+  });

package/src/dsl/diagram.grammar

@@ -0,0 +1,195 @@
+//
+// Copyright 2026 DXOS.org
+//
+// Lezer grammar for the diagram DSL — the text form of `src/scene.ts`.
+// Generate: lezer-generator --typeScript src/dsl/diagram.grammar -o src/dsl/gen/diagram.ts
+//
+// Two layers share one grammar. The scene statements (`object`, `elements`, `move`, `remove`) place
+// every shape at a coordinate; the semantic statements (`diagram`, `group`, `node`, `edge`) state
+// intent and leave placement and routing to `semantic-engine.ts`. A document may mix them.
+//
+// Brace-delimited and whitespace-insensitive, so an element's positional geometry
+// (`0,0 100x50`) stays on one line without the newline carrying meaning. Attribute names and
+// values are plain `name` tokens rather than keywords: the grammar accepts any `name=value`
+// and `lint.ts` rejects the ones the schema does not define, which is what lets an unknown
+// attribute report itself instead of failing the parse three tokens later.
+//
+
+@top Document { statement* }
+
+@skip { space | Comment }
+
+statement {
+  ObjectDecl |
+  ElementsDecl |
+  MoveStmt |
+  RemoveObjectStmt |
+  RemoveElementsStmt |
+  DiagramDecl |
+  GroupDecl |
+  NodeDecl |
+  EdgeDecl
+}
+
+// object <id> [@ x,y] [scale=…] [index=…] [ref=…] { … }
+ObjectDecl { kw<"object"> Id ObjectAttr* Body }
+
+// elements <objectId> { … } — adds to an existing object.
+ElementsDecl { kw<"elements"> Id Body }
+
+MoveStmt { kw<"move"> Id Origin }
+
+RemoveObjectStmt { kw<"remove"> kw<"object"> Id }
+
+// remove elements <objectId> <elementId>+
+RemoveElementsStmt { kw<"remove"> kw<"elements"> Id Id+ }
+
+ObjectAttr { Origin | Attribute }
+
+//
+// Semantic statements.
+//
+
+// diagram [@ x,y] [flow=down] [grid=384x224] [box=192x96] [aspect=4:3]
+DiagramDecl { kw<"diagram"> (Origin | Attribute)* }
+
+// group <id> ["label"] [relation <group>]* [compact] [gap=…] [max-width=…] [color=…] { node … edge … }
+// Groups do not nest; the grammar accepts a nested one so it can be reported rather than mis-parsed.
+// `compact` is a keyword, not a name, because a bare name here would read as the start of a relation.
+GroupDecl { kw<"group"> Id Label? (Relation | Attribute | Compact)* GroupBody }
+Compact { kw<"compact"> }
+GroupBody { "{" (NodeDecl | EdgeDecl | GroupDecl)* "}" }
+
+// node <id> ["label"] [@ x,y | @cell(c,r)] [~]<relation> <node> … [ref=…] [color=…] [shape=…]
+NodeDecl { kw<"node"> Id Label? (Pin | Relation | Attribute)* }
+
+// `@ x,y` is exact, in scene units; `@cell(c,r)` names a grid cell.
+Pin { "@" (Point | CellRef) }
+CellRef { kw<"cell"> "(" Coord "," Coord ")" }
+
+// The relation word is a plain name checked by the reader, so `left` or `below` stay usable as ids;
+// LR(1) tells it from an attribute by the `=` that follows an attribute name.
+Relation { Soft? RelationKind Id }
+Soft { "~" }
+RelationKind { name }
+
+// edge A[:[~]sides] (, B…)* (-> | <-> | -- | <relationship>) C[:[~]sides] (, D…)* ["label"] [via …] [bus[=name]] [attr=…]*
+// `~` before the sides makes them a preference the router weighs, not a rule.
+EdgeDecl { kw<"edge"> EndList EdgeOp EndList Label? (Via | Bus | Attribute)* }
+EndList { EdgeEnd ("," EdgeEnd)* }
+EdgeEnd { Id (":" Soft? SideList)? }
+SideList { Side ("|" Side)* }
+Side { name }
+// A relationship word in place of the arrow says what the edge means and sets its markers:
+// `Dog extends Animal`, `Order composes LineItem`, `Team owns Member`, `Customer one-to-many Order`.
+EdgeOp { "->" | "<->" | "--" | RelationWord }
+RelationWord { name }
+
+// Each waypoint pins one or both coordinates of the route, in scene units or as `cell(c,r)`, where
+// a half cell (`cell(1.5,_)`) is the channel between two columns or rows.
+Via { kw<"via"> Waypoint+ }
+Waypoint { Coord "," Coord | CellRef }
+Coord { Number | Unbound }
+
+Bus { kw<"bus"> ("=" Id)? }
+Origin { "@" Point }
+
+Body { "{" Element* "}" }
+
+Element {
+  BoxElement |
+  CircleElement |
+  PathElement |
+  ArcElement |
+  TextElement |
+  ArrowElement |
+  PortalElement
+}
+
+BoxElement    { BoxKind Id Point Size Label? Attribute* }
+CircleElement { kw<"circle"> Id Point Number Label? Attribute* }
+PathElement   { PathKind Id Point Point+ Attribute* }
+ArcElement    { kw<"arc"> Id Point Number Range Attribute* }
+TextElement   { kw<"text"> Id Point Label Attribute* }
+ArrowElement  { kw<"arrow"> Id Connection Label? Attribute* }
+PortalElement { kw<"portal"> Id Point Size Label? Attribute* }
+
+BoxKind  { kw<"rect"> | kw<"ellipse"> | kw<"diamond"> | kw<"triangle"> }
+PathKind { kw<"line"> | kw<"curve"> }
+
+// Both ends are written. `from`/`to` are independently optional in the schema, and `_` is how an
+// absent one is spelled — writing the omission rather than leaving a hole keeps the trailing end
+// distinguishable from the attributes that follow it, which an optional operand is not.
+Connection { Endpoint "->" Endpoint }
+Endpoint { Point | Ref | Unbound }
+Unbound { kw<"_"> }
+
+// `element`, `object/element`, either with `#port` — the spelling `Scene.formatRef` emits.
+// Quoted when an id in it cannot lex bare (a dialect may produce `1st/box` from a numeric node id).
+Ref { name | String }
+
+// Every attribute is `name=value`, with no bare flags: after `->` a bare word would otherwise be
+// ambiguous between a ref endpoint and a flag, which LR(1) cannot settle, and `closed=true` is
+// the only case that wanted one.
+Attribute { AttrName "=" AttrValue }
+AttrName  { name }
+AttrValue { Number | Size | Ratio | String | Word }
+// `aspect=4:3`.
+Ratio { Number ":" Number }
+
+// `head=triangle`, `head=arrow` and `tail=circle` are schema literals that are also element-kind
+// keywords, and a reserved word no longer lexes as a plain name. Listing every reserved word —
+// not just the three that collide today — keeps this correct when the schema gains another.
+Word {
+  name |
+  kw<"object"> | kw<"elements"> | kw<"move"> | kw<"remove"> |
+  kw<"rect"> | kw<"ellipse"> | kw<"diamond"> | kw<"triangle"> |
+  kw<"circle"> | kw<"line"> | kw<"curve"> | kw<"arc"> |
+  kw<"text"> | kw<"arrow"> | kw<"portal"> |
+  kw<"diagram"> | kw<"group"> | kw<"node"> | kw<"edge"> | kw<"cell"> | kw<"via"> | kw<"bus"> | kw<"compact">
+}
+
+Id    { name | String }
+Label { String }
+Point { Number "," Number }
+Range { Number ".." Number }
+
+Number { number }
+Size   { size }
+
+// Keyword specialization: the statement and element-kind words drive the structure, so they
+// must not lex as ids. An id that collides is written quoted (the printer does it).
+kw<term> { @specialize[@name={term}]<name, term> }
+
+@tokens {
+  nameStart { $[a-zA-Z_] }
+  nameChar  { $[a-zA-Z0-9_\-] }
+
+  // One token covers plain ids and refs: `#` is both the port separator and the comment
+  // character, and longest-match is what makes `A/box#left` a ref while ` # note` is a
+  // comment. A comment therefore needs whitespace in front of it.
+  name { nameStart nameChar* ("/" nameStart nameChar*)? ("#" nameStart nameChar*)? }
+
+  digits { @digit+ }
+  // The exponent is accepted because the printer emits `String(value)`, which switches to
+  // exponent notation outside roughly 1e-7..1e21 — without it, printing such a scene would
+  // produce text this grammar rejects.
+  exponent { $[eE] $[+\-]? digits }
+  decimal { "-"? digits ("." digits)? exponent? }
+  number { decimal }
+  // `100x50`, longer than the `100` a bare number would match, so the tokenizer prefers it.
+  size { decimal "x" decimal }
+
+  String { '"' (!["\\] | "\\" _)* '"' }
+
+  Comment { "#" ![\n]* }
+
+  space { $[ \t\r\n]+ }
+
+  "@" "->" "<->" "--" ".." "{" "}" "=" "," ":" "|" "~" "(" ")"
+
+  @precedence { size, number }
+  @precedence { name, Comment }
+}
+
+@detectDelim