@yassimba/pi-loom-mermaid 0.2.0

package/src/loom-mermaid/diagrams/class.ts

@@ -0,0 +1,297 @@
+/**
+ * `classDiagram`: classes with member compartments and UML relations.
+ * Lenient: an unreadable statement is dropped and recorded in `warnings`.
+ *
+ * Compartments live on `Node.sections`: `[title, attrs, methods]`, where the
+ * title is the optional `«annotation»` line followed by the class name.
+ */
+
+import { Graph, type Head, type LineKind, MAX_MEMBERS, type Node, parseDir } from '../graph.ts'
+import { asciiLower, cleanLabel, decodeHtmlEntities, displayGenerics, isIdChar } from '../labels.ts'
+import { layoutClass } from '../graph-render.ts'
+import type { Diagram } from '../registry.ts'
+import {
+  firstWord,
+  headerKind,
+  nonEmpty,
+  parseClassAssign,
+  parseClassDef,
+  parseHref,
+  quoteMask,
+  splitColon,
+  splitOnce,
+  statementsOf,
+  takeTags,
+  words,
+} from '../statements.ts'
+
+export const classDiagram: Diagram = {
+  kind: 'class',
+  headers: ['classdiagram', 'classdiagram-v2'],
+  render(src, limits) {
+    const graph = parseClass(src)
+    if (graph === null) return null
+    const canvas = layoutClass(graph, limits)
+    if (canvas === null) return null
+    return { canvas, warnings: graph.warnings, classDefs: graph.classDefs }
+  },
+}
+
+/** Relation operators, longest-first so `--|>` wins over `--`. */
+const CLASS_OPS: [string, Head, Head, LineKind][] = [
+  ['<|--', 'triangle', 'none', 'solid'],
+  ['--|>', 'none', 'triangle', 'solid'],
+  ['<|..', 'triangle', 'none', 'dotted'],
+  ['..|>', 'none', 'triangle', 'dotted'],
+  ['*--', 'diamondFill', 'none', 'solid'],
+  ['--*', 'none', 'diamondFill', 'solid'],
+  ['o--', 'diamondOpen', 'none', 'solid'],
+  ['--o', 'none', 'diamondOpen', 'solid'],
+  ['<--', 'arrow', 'none', 'solid'],
+  ['-->', 'none', 'arrow', 'solid'],
+  ['<..', 'arrow', 'none', 'dotted'],
+  ['..>', 'none', 'arrow', 'dotted'],
+  ['--', 'none', 'none', 'solid'],
+  ['..', 'none', 'none', 'dotted'],
+]
+
+const MAX_CLASS_OP = 4
+
+function parseClass(src: string): Graph | null {
+  const statements = statementsOf(src)
+  const kind = headerKind(statements)
+  if (kind === null || !classDiagram.headers.includes(kind)) return null
+
+  const graph = new Graph()
+  /** Declare a class from an id token, attaching any `:::` tags it carries. */
+  const declare = (token: string): number | null => {
+    const { id, classes } = takeTags(token)
+    const idx = graph.nodeIndex(id, null, 'rect')
+    if (idx !== null) {
+      graph.nodes[idx].sections ??= [[displayGenerics(id)], [], []]
+      for (const cls of classes) graph.addClass(idx, cls)
+    }
+    return idx
+  }
+  /** The open `{` body: a class index, `'skip'` for a dropped class, or none. */
+  let curClass: number | 'skip' | null = null
+  /** `class A,B name` / `cssClass "A,B" name` assignments, applied post-walk. */
+  const classAssignments: [string[], string[]][] = []
+  /** `link A "url"` / `click A href "url"` targets, applied post-walk. */
+  const hrefs: [string, string][] = []
+
+  for (const st of statements.slice(1)) {
+    if (curClass !== null) {
+      if (st === '}') curClass = null
+      else if (curClass !== 'skip') pushMember(graph.nodes[curClass], st)
+      continue
+    }
+
+    const first = asciiLower(firstWord(st))
+    if (first === 'direction') {
+      graph.dir = parseDir(words(st)[1] ?? '')
+      continue
+    }
+    if (first === 'classdef') {
+      const def = parseClassDef(st.slice(firstWord(st).length))
+      if (def) for (const name of def.names) graph.classDefs[name] = def.props
+      continue
+    }
+    if (['note', 'callback', 'style', 'namespace', '}'].includes(first)) {
+      continue
+    }
+    if (first === 'link' || first === 'click') {
+      const target = parseHref(st.slice(firstWord(st).length))
+      if (target) hrefs.push(target)
+      continue
+    }
+    if (first === 'cssclass') {
+      const assign = parseClassAssign(st.slice(firstWord(st).length).replace(/"/g, ''))
+      if (assign) classAssignments.push(assign)
+      else graph.drop(st)
+      continue
+    }
+    if (first === 'class') {
+      const rest = st.slice('class'.length).trim()
+      const open = rest.endsWith('{')
+      let name = open ? rest.slice(0, -1).trim() : rest
+      // `class A["Label"]` (mermaid ≥10.1): the label titles the box, the id
+      // keys relations. Peel it before the space test — labels carry spaces.
+      let label: string | null = null
+      const labeled = /^(\S+?)\[(.+)\](:::\S+)?$/.exec(name)
+      if (labeled) {
+        name = labeled[1] + (labeled[3] ?? '')
+        label = nonEmpty(cleanLabel(labeled[2]))
+      }
+      if (!open && /\s/.test(name)) {
+        // Class names carry no spaces, so `class Agent focus` is the
+        // assignment form, as in flowcharts.
+        const assign = parseClassAssign(name)
+        if (assign) classAssignments.push(assign)
+        else graph.drop(st)
+      } else if (name === '' || /\s/.test(name)) {
+        // A bad declaration that opened a body swallows it whole; reading the
+        // members as top-level statements would misparse everything inside.
+        graph.drop(st)
+        if (open) curClass = 'skip'
+      } else {
+        const idx = declare(name)
+        if (idx !== null && label !== null) {
+          const node = graph.nodes[idx]
+          node.label = label
+          // The name is the last title line (an annotation may precede it).
+          const title = node.sections?.[0]
+          if (title) title[title.length - 1] = label
+        }
+        if (open) curClass = idx ?? 'skip'
+      }
+    } else if (st.startsWith('<<')) {
+      const split = splitOnce(st.slice(2), '>>')
+      const name = split ? split[1].trim() : ''
+      if (split === null || name === '' || /\s/.test(name)) {
+        graph.drop(st)
+      } else {
+        const idx = declare(name)
+        if (idx !== null) setAnnotation(graph.nodes[idx], split[0].trim())
+      }
+    } else {
+      const rel = parseClassRelation(st)
+      if (rel !== null) {
+        const f = declare(rel.from)
+        const t = f === null ? null : declare(rel.to)
+        if (f !== null && t !== null) {
+          graph.pushEdge({
+            from: f,
+            to: t,
+            label: rel.label,
+            cardFrom: rel.cardFrom,
+            cardTo: rel.cardTo,
+            headTo: rel.headTo,
+            headFrom: rel.headFrom,
+            line: rel.line,
+          })
+        }
+      } else {
+        const member = splitColon(st)
+        const id = member ? member[0].trim() : ''
+        const text = member ? member[1].trim() : ''
+        if (member === null || id === '' || /\s/.test(id) || text === '') {
+          graph.drop(st)
+        } else {
+          const idx = declare(id)
+          if (idx !== null) pushMember(graph.nodes[idx], text)
+        }
+      }
+    }
+    if (graph.truncated !== null) {
+      graph.warnings.push(`diagram truncated: ${graph.truncated}`)
+      break
+    }
+  }
+
+  graph.applyClasses(classAssignments)
+  graph.applyHrefs(hrefs)
+
+  return graph.nodes.length === 0 ? null : graph
+}
+
+/** Rewrite the title compartment as `«annotation»` over the class name. */
+function setAnnotation(node: Node, annotation: string): void {
+  ;(node.sections as string[][])[0] = [`«${annotation}»`, displayGenerics(node.label)]
+}
+
+/** Add a member to the attribute or method compartment, eliding past the cap. */
+function pushMember(node: Node, raw: string): void {
+  const sections = node.sections as string[][]
+  if (raw.startsWith('<<')) {
+    const split = splitOnce(raw.slice(2), '>>')
+    if (split) setAnnotation(node, split[0].trim())
+    return
+  }
+  const member = decodeHtmlEntities(displayGenerics(raw.trim()))
+  const list = member.includes('(') ? sections[2] : sections[1]
+  if (list.length < MAX_MEMBERS) list.push(member)
+  else if (list.length === MAX_MEMBERS) list.push('…')
+}
+
+interface ClassRelation {
+  from: string
+  to: string
+  headFrom: Head
+  headTo: Head
+  line: LineKind
+  label: string | null
+  cardFrom?: string
+  cardTo?: string
+}
+
+function parseClassRelation(st: string): ClassRelation | null {
+  const chars = [...st]
+  // Skip quoted spans, or the `..` inside a cardinality like `"0..*"` would
+  // match the dotted-link operator.
+  const quoted = quoteMask(chars)
+  let found: { pos: number; op: string; headFrom: Head; headTo: Head; line: LineKind } | null = null
+
+  outer: for (let pos = 0; pos < chars.length; pos++) {
+    if (quoted[pos]) continue
+    const tail = chars.slice(pos, pos + MAX_CLASS_OP).join('')
+    for (const [op, headFrom, headTo, line] of CLASS_OPS) {
+      if (!tail.startsWith(op)) continue
+      // `o` is also an identifier character: skip a match glued to a name.
+      if (op.startsWith('o') && pos > 0 && isIdChar(chars[pos - 1])) continue
+      const after = chars[pos + [...op].length]
+      if (op.endsWith('o') && after !== undefined && isIdChar(after)) continue
+      found = { pos, op, headFrom, headTo, line }
+      break outer
+    }
+  }
+  if (!found) return null
+
+  const lhsRaw = chars.slice(0, found.pos).join('').trim()
+  const rhsRaw = chars
+    .slice(found.pos + [...found.op].length)
+    .join('')
+    .trim()
+
+  const [lhs, cardFrom] = stripCardinalitySuffix(lhsRaw)
+  const [rhs, cardTo] = stripCardinalityPrefix(rhsRaw)
+
+  const split = splitColon(rhs)
+  const toId = (split ? split[0] : rhs).trim()
+  const relLabel = split ? nonEmpty(decodeHtmlEntities(split[1].trim())) : null
+
+  if (lhs === '' || toId === '' || /\s/.test(lhs) || /\s/.test(toId)) return null
+
+  return {
+    from: lhs,
+    to: toId,
+    headFrom: found.headFrom,
+    headTo: found.headTo,
+    line: found.line,
+    label: relLabel,
+    cardFrom: cardFrom === '' ? undefined : cardFrom,
+    cardTo: cardTo === '' ? undefined : cardTo,
+  }
+}
+
+/** `Class "1"` — a quoted cardinality trailing the left-hand name. */
+function stripCardinalitySuffix(s: string): [string, string] {
+  const t = s.trimEnd()
+  if (t.endsWith('"')) {
+    const rest = t.slice(0, -1)
+    const q = rest.lastIndexOf('"')
+    if (q !== -1) return [rest.slice(0, q).trimEnd(), rest.slice(q + 1)]
+  }
+  return [t, '']
+}
+
+/** `"0..*" Class` — a quoted cardinality leading the right-hand name. */
+function stripCardinalityPrefix(s: string): [string, string] {
+  const t = s.trimStart()
+  if (t.startsWith('"')) {
+    const rest = t.slice(1)
+    const q = rest.indexOf('"')
+    if (q !== -1) return [rest.slice(q + 1).trimStart(), rest.slice(0, q)]
+  }
+  return [t, '']
+}

package/src/loom-mermaid/diagrams/er.ts

@@ -0,0 +1,189 @@
+/**
+ * `erDiagram`: entities with attribute compartments and crow's-foot
+ * relationships. Lenient: an unreadable statement is dropped and recorded in
+ * `warnings`.
+ *
+ * Entities use `Node.sections` as `[title, attrs]`.
+ */
+
+import { Graph, type LineKind, MAX_MEMBERS, type Node } from '../graph.ts'
+import { cleanLabel, decodeHtmlEntities, displayGenerics } from '../labels.ts'
+import { layoutClass } from '../graph-render.ts'
+import type { Diagram } from '../registry.ts'
+import { headerKind, nonEmpty, splitOnce, statementsOf, words } from '../statements.ts'
+
+export const er: Diagram = {
+  kind: 'er',
+  headers: ['erdiagram'],
+  render(src, limits) {
+    const graph = parseEr(src)
+    if (graph === null) return null
+    const canvas = layoutClass(graph, limits)
+    if (canvas === null) return null
+    return { canvas, warnings: graph.warnings, classDefs: graph.classDefs }
+  },
+}
+
+function parseEr(src: string): Graph | null {
+  const statements = statementsOf(src)
+  const kind = headerKind(statements)
+  if (kind === null || !er.headers.includes(kind)) return null
+
+  const graph = new Graph()
+  /** The open `{` body: an entity index, `'skip'` for a dropped one, or none. */
+  let curEntity: number | 'skip' | null = null
+
+  for (const st of statements.slice(1)) {
+    if (curEntity !== null) {
+      if (st === '}') curEntity = null
+      else if (curEntity !== 'skip') pushErAttribute(graph.nodes[curEntity], st)
+      continue
+    }
+
+    const rel = splitErRelationship(st)
+    if (rel) {
+      const tokens = erTokens(rel.rel)
+      const op = tokens.length === 3 ? parseErOp(tokens[1]) : null
+      const f = op === null ? null : erEntity(graph, tokens[0])
+      const t = f === null ? null : erEntity(graph, tokens[2])
+      if (op === null || f === null || t === null) {
+        graph.drop(st)
+      } else {
+        const relLabel = rel.label === null ? '' : cleanLabel(rel.label)
+        graph.pushEdge({
+          from: f,
+          to: t,
+          label: nonEmpty(relLabel),
+          cardFrom: op.cardL,
+          cardTo: op.cardR,
+          headTo: 'none',
+          headFrom: 'none',
+          line: op.line,
+        })
+      }
+    } else {
+      const open = st.endsWith('{')
+      const decl = open ? st.slice(0, -1).trim() : st
+      if (decl === '' || erTokens(decl).length !== 1) {
+        // A bad declaration that opened a body swallows it whole; reading the
+        // attributes as top-level statements would misparse everything inside.
+        graph.drop(st)
+        if (open) curEntity = 'skip'
+      } else {
+        const idx = erEntity(graph, decl)
+        if (open) curEntity = idx ?? 'skip'
+      }
+    }
+    if (graph.truncated !== null) {
+      graph.warnings.push(`diagram truncated: ${graph.truncated}`)
+      break
+    }
+  }
+
+  return graph.nodes.length === 0 ? null : graph
+}
+
+/** Resolve an entity token (`NAME`, `"Quoted Name"` or `id[Label]`), keeping
+ * its title row fresh. A quoted name is its own identity; the quotes are not
+ * part of the title. */
+function erEntity(graph: Graph, token: string): number | null {
+  const open = token.startsWith('"') ? -1 : token.indexOf('[')
+  let idx: number | null
+  if (open !== -1) {
+    const id = token.slice(0, open)
+    if (!token.endsWith(']')) {
+      graph.warnings.push(`entity "${id}": alias is missing its closing \`]\``)
+    }
+    const label = cleanLabel(token.slice(open + 1).replace(/\]+$/, ''))
+    if (id === '' || label === '') return null
+    idx = graph.nodeLabel(id, label)
+  } else if (token.startsWith('"')) {
+    const label = cleanLabel(token)
+    if (label === '') return null
+    idx = graph.nodeIndex(token, label, 'rect')
+  } else {
+    idx = graph.nodeIndex(token, null, 'rect')
+  }
+  if (idx === null) return null
+  const node = graph.nodes[idx]
+  node.sections ??= [[], []]
+  node.sections[0] = [displayGenerics(node.label)]
+  return idx
+}
+
+/** Whitespace tokens, quoted spans kept whole so aliases may contain spaces. */
+function erTokens(s: string): string[] {
+  const out: string[] = []
+  let cur = ''
+  let inQuotes = false
+  for (const c of s) {
+    if (c === '"') {
+      inQuotes = !inQuotes
+      cur += c
+    } else if (!inQuotes && /\s/.test(c)) {
+      if (cur !== '') {
+        out.push(cur)
+        cur = ''
+      }
+    } else {
+      cur += c
+    }
+  }
+  if (cur !== '') out.push(cur)
+  return out
+}
+
+function splitErRelationship(st: string): { rel: string; label: string | null } | null {
+  const split = splitOnce(st, ':')
+  const rel = split ? split[0] : st
+  const label = split ? split[1].trim() : null
+  return erTokens(rel).some((t) => parseErOp(t) !== null) ? { rel, label } : null
+}
+
+const isAscii = (s: string): boolean => {
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) return false
+  return true
+}
+
+/** A crow's-foot operator: two cardinality glyphs around `--` or `..`. */
+function parseErOp(tok: string): { cardL: string; cardR: string; line: LineKind } | null {
+  if (tok.length !== 6 || !isAscii(tok)) return null
+  const mid = tok.slice(2, 4)
+  const line: LineKind | null = mid === '--' ? 'solid' : mid === '..' ? 'dotted' : null
+  if (line === null) return null
+  const cardL = erCard(tok.slice(0, 2))
+  const cardR = erCard(tok.slice(4, 6))
+  return cardL === null || cardR === null ? null : { cardL, cardR, line }
+}
+
+function erCard(tok: string): string | null {
+  switch (tok) {
+    case '|o':
+    case 'o|':
+      return '0..1'
+    case '||':
+      return '1'
+    case '}o':
+    case 'o{':
+      return '*'
+    case '}|':
+    case '|{':
+      return '1..*'
+    default:
+      return null
+  }
+}
+
+/** ER attributes are `type name`; a trailing quoted comment is dropped. */
+function pushErAttribute(node: Node, raw: string): void {
+  const attrs = (node.sections as string[][])[1]
+  const parts: string[] = []
+  for (const tok of words(raw)) {
+    if (tok.startsWith('"')) break
+    parts.push(tok)
+  }
+  if (parts.length === 0) return
+  const line = decodeHtmlEntities(parts.join(' '))
+  if (attrs.length < MAX_MEMBERS) attrs.push(line)
+  else if (attrs.length === MAX_MEMBERS) attrs.push('…')
+}