@zombie-mermaid/core 2.2.1

package/src/statements.ts

@@ -0,0 +1,197 @@
+// ============================================================================
+// zombie-mermaid — shared statement splitting
+//
+// Every parser entry point (flowchart/state in src/parser.ts, the four
+// specialized parsers dispatched from src/index.ts and src/ascii/index.ts)
+// needs the same thing: turn raw Mermaid source into a list of trimmed,
+// comment-free statements. They each used to do it inline with
+// `.split('\n').map(trim).filter(...)`, which meant semicolon separators —
+// valid Mermaid, and the form `detectDiagramType` already assumed when
+// isolating the header — were understood by nobody.
+//
+// This module is the single source of truth for "what counts as one
+// statement".
+// ============================================================================
+
+/**
+ * Matches a character reference in either spelling Mermaid accepts.
+ *
+ * HTML/XML form: `&`, `#`, `😀`.
+ * Mermaid's own form, which uses `#` where HTML uses `&`: `#59;`, `#9829;`,
+ * `#quot;` — the documented way to put a literal semicolon, quote, or symbol
+ * into a label.
+ *
+ * Both end in a semicolon that belongs to the reference, not to statement
+ * separation. Splitting one apart corrupts the label *and* invents a
+ * statement out of the remainder.
+ */
+const ENTITY_AT = /^[&#](?:#?[0-9]+|#?[xX][0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/
+
+/** Characters that can open a character reference. */
+const ENTITY_STARTERS = new Set(['&', '#'])
+
+/**
+ * Index of the `%%` that starts a comment on this line, or -1.
+ *
+ * A Mermaid comment runs to the end of the line, so everything after it —
+ * including any further `;`-separated fragments — is commented out. Scanning
+ * for it before splitting is what makes that true: dropping fragments that
+ * merely *begin* with `%%` afterwards leaves `graph TD; A-->B; %% note; C-->D`
+ * still parsing `C-->D` as code.
+ *
+ * Quote- and reference-aware for the same reasons the splitter is, so a `%%`
+ * inside a label is text rather than a comment marker.
+ */
+function commentStart(line: string): number {
+  let quote: '"' | "'" | null = null
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!
+
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      continue
+    }
+    if (ENTITY_STARTERS.has(ch)) {
+      const entity = ENTITY_AT.exec(line.slice(i))
+      if (entity) {
+        i += entity[0].length - 1
+        continue
+      }
+    }
+    if (ch === '%' && line[i + 1] === '%') return i
+  }
+
+  return -1
+}
+
+/**
+ * Split one already-newline-separated line on its statement-separating
+ * semicolons.
+ *
+ * A semicolon separates statements unless it is:
+ *   - inside a quoted string (`A["a; b"]`), or
+ *   - the terminator of a character reference (`A[&amp;]`).
+ *
+ * Quote tracking is deliberately simple — Mermaid has no escape sequence
+ * inside quoted labels, so a quote character always opens or closes a span.
+ */
+function splitOnSemicolons(line: string): string[] {
+  const parts: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!
+
+    if (quote !== null) {
+      current += ch
+      if (ch === quote) quote = null
+      continue
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      current += ch
+      continue
+    }
+
+    if (ENTITY_STARTERS.has(ch)) {
+      // Copy a whole character reference in one go so its trailing ';' can't
+      // be read as a separator. Guarded on '#' as well as '&': Mermaid's own
+      // `#59;` spelling is far more common in diagrams than the HTML one.
+      const entity = ENTITY_AT.exec(line.slice(i))
+      if (entity) {
+        current += entity[0]
+        i += entity[0].length - 1
+        continue
+      }
+    }
+
+    if (ch === ';') {
+      parts.push(current)
+      current = ''
+      continue
+    }
+
+    current += ch
+  }
+
+  parts.push(current)
+  return parts
+}
+
+/**
+ * One statement produced by the splitter, paired with the 1-based physical
+ * source line it came from.
+ *
+ * `line` is captured while walking `text.split('\n')`, before blank lines
+ * and `%%` comment lines are dropped — so it survives being the original
+ * source line number even though a statement's array index no longer does.
+ * This is what lets every parser built on top of `splitStatements`/
+ * `splitStatementsByLine` report *where* an error is, not just quote back
+ * the offending statement's text (see issue #760).
+ */
+export interface Statement {
+  text: string
+  line: number
+}
+
+/**
+ * Split Mermaid source into trimmed statements, grouped by the physical
+ * source line each one came from — dropping blank lines and `%%` comment
+ * lines.
+ *
+ * Newlines and semicolons both separate statements, matching Mermaid's own
+ * `graph TD; A-->B;` form. Comments are removed *before* semicolon splitting
+ * so that a `;` inside a comment can't resurrect the rest of that line as
+ * code.
+ *
+ * The grouping is what lets a caller tell a genuine multi-line continuation
+ * (crossing from one line's group into the next) apart from an explicit
+ * `;`-separated statement on the *same* line (a later entry within one
+ * group) — see `src/parser.ts`'s `mergeContinuationLines`, which only
+ * treats the former as mergeable.
+ */
+export function splitStatementsByLine(text: string): Statement[][] {
+  const groups: Statement[][] = []
+  const rawLines = text.split('\n')
+
+  for (let lineIndex = 0; lineIndex < rawLines.length; lineIndex++) {
+    let line = rawLines[lineIndex]!.trim()
+    const lineNumber = lineIndex + 1
+
+    /*
+     * Cut the comment off first. A Mermaid comment runs to end of line, so
+     * anything after `%%` is commented out — including further `;`-separated
+     * fragments. Splitting first and discarding fragments that start with
+     * `%%` would leave `A-->B; %% note; C-->D` parsing `C-->D` as code.
+     */
+    const comment = commentStart(line)
+    if (comment !== -1) line = line.slice(0, comment).trim()
+    if (line.length === 0) continue
+
+    const statements: Statement[] = []
+    for (const part of splitOnSemicolons(line)) {
+      const statement = part.trim()
+      if (statement.length === 0) continue
+      statements.push({ text: statement, line: lineNumber })
+    }
+    if (statements.length > 0) groups.push(statements)
+  }
+
+  return groups
+}
+
+/**
+ * Split Mermaid source into trimmed statements, dropping blank lines and
+ * `%%` comment lines. See `splitStatementsByLine` for the line-grouped form
+ * this flattens.
+ */
+export function splitStatements(text: string): Statement[] {
+  return splitStatementsByLine(text).flat()
+}

package/src/style-directives.ts

@@ -0,0 +1,214 @@
+// ============================================================================
+// Style directives — `classDef`, `class A,B name`, `cssClass "A,B" name`,
+// `style A ...`, and the `A:::name` shorthand.
+//
+// Mermaid's flowchart and class diagrams share one styling grammar
+// (https://mermaid.js.org/syntax/flowchart.html#styling-and-classes,
+// https://mermaid.js.org/syntax/classDiagram.html#styling). The flowchart
+// parser grew the first implementation; this module is that implementation
+// lifted out so the class-diagram parser can reuse it rather than copy it
+// (issue #420). Both parsers feed a `StyleDirectives` bag, and both layouts
+// resolve a node's final style through `resolveNodeStyle` with the same
+// cascade — so a `classDef default` means the same thing in every diagram
+// type that supports it.
+// ============================================================================
+
+/** The three maps a styling-aware diagram carries. `MermaidGraph` and
+ * `ClassDiagram` both satisfy this structurally. */
+export interface StyleDirectives {
+  /** Maps class names to their style properties (from `classDef name prop:val`) */
+  classDefs: Map<string, Record<string, string>>
+  /** Maps node IDs to their assigned class name (from `class A,B name`, `cssClass "A,B" name`, or `A:::name`) */
+  classAssignments: Map<string, string>
+  /** Maps node IDs to inline styles (from `style X fill:#f00,stroke:#333`) */
+  nodeStyles: Map<string, Record<string, string>>
+}
+
+/** Parse "fill:#f00,stroke:#333" style property strings into a Record */
+export function parseStyleProps(propsStr: string): Record<string, string> {
+  // Strip trailing semicolons — Mermaid tolerates them (e.g. `stroke:#f00;`)
+  const cleaned = propsStr.replace(/;\s*$/, '')
+  const props: Record<string, string> = {}
+  for (const pair of cleaned.split(',')) {
+    const colonIdx = pair.indexOf(':')
+    if (colonIdx > 0) {
+      const key = pair.slice(0, colonIdx).trim()
+      const val = pair.slice(colonIdx + 1).trim()
+      if (key && val) {
+        props[key] = val
+      }
+    }
+  }
+  return props
+}
+
+/**
+ * `classDef name prop:val,prop:val` — define a named style class.
+ *
+ * Mermaid's `classList` rule accepts a comma-separated list of names
+ * (`classDef a,b font-size:12pt`) in both the flowchart and class grammars;
+ * every name in the list gets the same properties.
+ *
+ * Returns true when `line` was a classDef statement (and has been applied).
+ */
+export function tryApplyClassDef(
+  line: string,
+  target: StyleDirectives,
+): boolean {
+  const match = line.match(/^classDef\s+([\w,-]+)\s+(.+)$/)
+  if (!match) return false
+  const props = parseStyleProps(match[2]!)
+  for (const name of match[1]!.split(',')) {
+    const trimmed = name.trim()
+    if (trimmed) target.classDefs.set(trimmed, props)
+  }
+  return true
+}
+
+/**
+ * `class A,B className` — attach a style class to one or more nodes.
+ *
+ * Allows an optional trailing semicolon (`class A,B foo;`) — Mermaid treats
+ * it as valid/optional, and `classDef`/`style` already tolerate it via their
+ * `(.+)$` capture. Without this, the semicolon form fails to match here and
+ * falls through to node parsing, rendering a stray node labelled "class".
+ *
+ * Returns true when `line` was a class-assignment statement.
+ */
+export function tryApplyClassAssignment(
+  line: string,
+  target: StyleDirectives,
+): boolean {
+  const match = line.match(/^class\s+([\w,-]+)\s+([\w-]+)\s*;?\s*$/)
+  if (!match) return false
+  const className = match[2]!
+  for (const id of match[1]!.split(',')) {
+    target.classAssignments.set(id.trim(), className)
+  }
+  return true
+}
+
+/**
+ * `cssClass "A,B" className` — the class-diagram grammar's own attachment
+ * form (`cssClassStatement: CSSCLASS STR ALPHA` in classDiagram.jison).
+ * Same effect as `class A,B className`.
+ *
+ * Returns true when `line` was a cssClass statement.
+ */
+export function tryApplyCssClass(
+  line: string,
+  target: StyleDirectives,
+): boolean {
+  const match = line.match(/^cssClass\s+"([^"]*)"\s+([\w-]+)\s*;?\s*$/)
+  if (!match) return false
+  const className = match[2]!
+  for (const id of match[1]!.split(',')) {
+    const trimmed = id.trim()
+    if (trimmed) target.classAssignments.set(trimmed, className)
+  }
+  return true
+}
+
+/**
+ * `style A,B fill:#f00,stroke:#333` — inline style on specific nodes.
+ * Repeated `style` statements for the same node merge property by property.
+ *
+ * Returns true when `line` was a style statement.
+ */
+export function tryApplyStyleStatement(
+  line: string,
+  target: StyleDirectives,
+): boolean {
+  const match = line.match(/^style\s+([\w,-]+)\s+(.+)$/)
+  if (!match) return false
+  const props = parseStyleProps(match[2]!)
+  for (const id of match[1]!.split(',').map((s) => s.trim())) {
+    target.nodeStyles.set(id, { ...target.nodeStyles.get(id), ...props })
+  }
+  return true
+}
+
+/**
+ * Split the `:::className` shorthand off a node/class identifier.
+ *
+ * `Animal:::someclass` → `{ id: 'Animal', className: 'someclass' }`;
+ * an identifier without the shorthand comes back unchanged with no class.
+ * Class names follow CSS identifier conventions (word characters and
+ * hyphens), the same constraint the flowchart parser's CLASS_SHORTHAND_REGEX
+ * applies.
+ */
+export function splitClassShorthand(identifier: string): {
+  id: string
+  className?: string
+} {
+  const match = identifier.match(/^(.+?):::([\w][\w-]*)$/)
+  if (!match) return { id: identifier }
+  return { id: match[1]!, className: match[2]! }
+}
+
+/**
+ * Resolve the final inline style for a node from classDefs and nodeStyles.
+ *
+ * Cascade, weakest to strongest:
+ *   1. `classDef default` — Mermaid's implicit base for every node
+ *   2. the node's own assigned class (`class A foo` / `A:::foo`)
+ *   3. an explicit `style A ...` directive
+ *
+ * Returns undefined when nothing in the cascade applies, so callers can fall
+ * back to theme defaults without an empty-object check.
+ */
+export function resolveNodeStyle(
+  nodeId: string,
+  directives: StyleDirectives,
+): Record<string, string> | undefined {
+  let result: Record<string, string> | undefined
+
+  /*
+   * `classDef default` applies to every node without being assigned. It was
+   * previously honored only when a node named it explicitly (`class X
+   * default`), which silently diverges from Mermaid: a diagram styling all
+   * its nodes via `classDef default` rendered unstyled with no error.
+   */
+  const defaultDef = directives.classDefs.get('default')
+  if (defaultDef) {
+    result = { ...defaultDef }
+  }
+
+  // Then the node's own class, overriding the default property by property.
+  const className = directives.classAssignments.get(nodeId)
+  if (className) {
+    const classDef = directives.classDefs.get(className)
+    if (classDef) {
+      result = result ? { ...result, ...classDef } : { ...classDef }
+    }
+  }
+
+  // Then, apply explicit style directives (override class styles)
+  const nodeStyle = directives.nodeStyles.get(nodeId)
+  if (nodeStyle) {
+    result = result ? { ...result, ...nodeStyle } : { ...nodeStyle }
+  }
+
+  return result
+}
+
+/**
+ * Validate a user-authored class name (from `:::className` or
+ * `class A className`) before it's emitted into the SVG `class` attribute.
+ *
+ * The parsers already constrain class names to word characters and hyphens
+ * (see `splitClassShorthand` above and the flowchart parser's
+ * CLASS_SHORTHAND_REGEX), so this is a defense-in-depth allowlist rather
+ * than an escaping step — a class name can't be made "safe" by escaping
+ * since any character other than a valid CSS identifier character would
+ * break the class token itself, not just the surrounding attribute quotes.
+ * Anything that doesn't match a valid CSS identifier (letters, digits,
+ * underscore, hyphen; not starting with a digit or a hyphen+digit) is
+ * dropped rather than emitted.
+ */
+export function sanitizeClassName(
+  className: string | undefined,
+): string | undefined {
+  if (!className) return undefined
+  return /^-?[a-zA-Z_][a-zA-Z0-9_-]*$/.test(className) ? className : undefined
+}