zombie-mermaid 2.2.3 → 2.2.6

package/packages/mcp/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Craft Docs
-Copyright (c) 2026 Dustin Fadler
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/packages/mcp/src/index.ts

@@ -1,17 +0,0 @@
-// ============================================================================
-// zombie-mermaid/mcp — MCP server entry point
-//
-// Exposes the library's SVG/ASCII rendering as Model Context Protocol
-// tools. Import `createMcpServer()` to embed the server in your own
-// process and connect it to any MCP Transport, or run `zombie-mermaid mcp`
-// from the CLI for a ready-to-use stdio server (see src/cli/mcp.ts).
-//
-// Usage:
-//   import { createMcpServer } from 'zombie-mermaid/mcp'
-//   import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-//
-//   const server = createMcpServer()
-//   await server.connect(new StdioServerTransport())
-// ============================================================================
-
-export { createMcpServer } from './server.ts'

package/packages/mcp/src/server.ts

@@ -1,135 +0,0 @@
-// ============================================================================
-// zombie-mermaid MCP server
-//
-// Wires the library's existing SVG/ASCII rendering functions, plus a
-// mechanical sequence-diagram semantic check, up as Model Context Protocol
-// tools. No rendering or checking logic lives here — see src/mcp/tools/*.ts
-// for the thin per-tool adapters, src/index.ts / src/ascii/index.ts for the
-// actual renderers, and packages/mermaid-parser/src/sequence/activation-check.ts
-// for the check.
-// ============================================================================
-
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { getPackageVersion } from '../../../src/package-info.ts'
-import { renderSvgInputShape, renderSvgHandler } from './tools/render-svg.ts'
-import {
-  renderAsciiInputShape,
-  renderAsciiHandler,
-} from './tools/render-ascii.ts'
-import {
-  checkSequenceActivationsInputShape,
-  checkSequenceActivationsHandler,
-} from './tools/check-sequence-activations.ts'
-import {
-  fixSequenceActivationsInputShape,
-  fixSequenceActivationsHandler,
-} from './tools/fix-sequence-activations.ts'
-
-/**
- * Build a zombie-mermaid MCP server exposing `render_mermaid_svg`,
- * `render_mermaid_ascii`, and `check_mermaid_sequence_activations` tools.
- *
- * Not connected to any transport — callers wire it up. See
- * src/cli/mcp.ts for the stdio entry point used by `zombie-mermaid mcp`,
- * or connect it to the MCP SDK's `InMemoryTransport` to embed/test it
- * in-process without spawning anything.
- */
-export function createMcpServer(): McpServer {
-  const server = new McpServer({
-    name: 'zombie-mermaid',
-    version: getPackageVersion(),
-  })
-
-  server.registerTool(
-    'render_mermaid_svg',
-    {
-      title: 'Render Mermaid diagram to SVG',
-      description:
-        'Render Mermaid diagram source to a self-contained SVG string. ' +
-        'Supports flowcharts, state diagrams, sequence diagrams, class ' +
-        'diagrams, ER diagrams, and XY charts.',
-      inputSchema: renderSvgInputShape,
-      annotations: {
-        title: 'Render Mermaid diagram to SVG',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-      },
-    },
-    renderSvgHandler,
-  )
-
-  server.registerTool(
-    'render_mermaid_ascii',
-    {
-      title: 'Render Mermaid diagram to ASCII/Unicode art',
-      description:
-        'Render Mermaid diagram source to a plain-text ASCII or Unicode ' +
-        'box-drawing diagram, suitable for a terminal or a chat/agent ' +
-        'context. Supports flowcharts, state diagrams, sequence diagrams, ' +
-        'class diagrams, and ER diagrams.',
-      inputSchema: renderAsciiInputShape,
-      annotations: {
-        title: 'Render Mermaid diagram to ASCII/Unicode art',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-      },
-    },
-    renderAsciiHandler,
-  )
-
-  server.registerTool(
-    'check_mermaid_sequence_activations',
-    {
-      title: 'Check Mermaid sequence diagram activation balance',
-      description:
-        'Check a Mermaid sequence diagram for activation/deactivation ' +
-        'imbalance: every "activate X" (or "+" arrow shorthand) must be ' +
-        'closed by a matching "deactivate X" ("-" shorthand). Returns a ' +
-        'JSON report ({ ok, issues }) rather than rendering anything. ' +
-        'Mechanical and deterministic — no LLM judgment involved. Only ' +
-        'sequence diagrams are supported.',
-      inputSchema: checkSequenceActivationsInputShape,
-      annotations: {
-        title: 'Check Mermaid sequence diagram activation balance',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-      },
-    },
-    checkSequenceActivationsHandler,
-  )
-
-  server.registerTool(
-    'fix_mermaid_sequence_activations',
-    {
-      title: 'Fix Mermaid sequence diagram activation balance',
-      description:
-        'Check a Mermaid sequence diagram for activation/deactivation ' +
-        'imbalance and, where mechanically safe, return a corrected ' +
-        'version: a dangling "activate X" (or "+" shorthand) with no ' +
-        'matching "deactivate X" gets one appended. An unmatched ' +
-        '"deactivate X" with nothing open is reported but not auto-fixed ' +
-        '(no safe, unambiguous edit exists without source-position ' +
-        'tracking). Returns a JSON report ({ ok, fixedDiagram, ' +
-        'fixesApplied, remainingIssues }) rather than rendering anything. ' +
-        'Mechanical and deterministic — no LLM judgment involved. Only ' +
-        'sequence diagrams are supported.',
-      inputSchema: fixSequenceActivationsInputShape,
-      annotations: {
-        title: 'Fix Mermaid sequence diagram activation balance',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-      },
-    },
-    fixSequenceActivationsHandler,
-  )
-
-  return server
-}

package/packages/mcp/src/tools/check-sequence-activations.ts

@@ -1,91 +0,0 @@
-// ============================================================================
-// zombie-mermaid MCP server — `check_mermaid_sequence_activations` tool
-//
-// A mechanical, deterministic semantic check that complements the existing
-// render tools: every "activate X" (or "+" arrow shorthand) in a Mermaid
-// sequence diagram must be closed by a matching "deactivate X" ("-"
-// shorthand) before the diagram ends. No LLM judge involved — see
-// packages/mermaid-parser/src/sequence/activation-check.ts for the actual
-// check, which reuses the same activation-stack bookkeeping
-// packages/svg-renderer/src/sequence/layout.ts already runs to *draw*
-// activation bars.
-//
-// Why this tool, and why it isn't duplicating agentic-mermaid's `verify`
-// tool (github.com/adewale/agentic-mermaid): that tool's own docs describe
-// it as reporting "structural, geometric, and lint warnings" — dangling
-// edges, label overflow, duplicate/unreachable nodes — a general
-// graph-structure check with no sequence-diagram-specific handling. Neither
-// it nor ordinary Mermaid syntax validators check activation/deactivation
-// balance, which research behind issue #536 found is where LLM-generated
-// sequence diagrams actually go wrong most often (not basic syntax).
-// ============================================================================
-
-import { z } from 'zod'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import { detectDiagramType, splitStatements } from '@zombie-mermaid/core'
-import {
-  parseSequenceDiagram,
-  checkActivationBalance,
-} from '@zombie-mermaid/mermaid-parser'
-
-export const checkSequenceActivationsInputShape = {
-  diagram: z
-    .string()
-    .min(1, 'diagram must not be empty')
-    .describe(
-      'Mermaid sequence diagram source text, e.g. "sequenceDiagram\\n  ' +
-        'A->>+B: hi\\n  B-->>-A: bye". Must start with "sequenceDiagram" ' +
-        '— this tool does not check other diagram types.',
-    ),
-}
-
-export interface CheckSequenceActivationsToolArgs {
-  diagram: string
-}
-
-/**
- * MCP tool handler for `check_mermaid_sequence_activations`. Parses the
- * given source as a Mermaid sequence diagram and reports every
- * activation/deactivation imbalance as a structured JSON result (`ok` plus
- * an `issues` array) — this tool never renders anything.
- *
- * Returns an MCP tool error (`isError: true`, not a thrown exception) both
- * for invalid Mermaid syntax and for a non-sequence diagram, since this
- * check only makes sense for `sequenceDiagram` source.
- */
-export function checkSequenceActivationsHandler(
-  input: CheckSequenceActivationsToolArgs,
-): CallToolResult {
-  try {
-    const diagramType = detectDiagramType(input.diagram)
-    if (diagramType !== 'sequence') {
-      return {
-        isError: true,
-        content: [
-          {
-            type: 'text',
-            text:
-              'This tool only checks sequence diagrams (source must start ' +
-              `with "sequenceDiagram"); detected diagram type: "${diagramType}".`,
-          },
-        ],
-      }
-    }
-    const lines = splitStatements(input.diagram)
-    const diagram = parseSequenceDiagram(lines)
-    const result = checkActivationBalance(diagram)
-    return {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    }
-  } catch (err) {
-    return {
-      isError: true,
-      content: [
-        {
-          type: 'text',
-          text: `Failed to check diagram activations: ${err instanceof Error ? err.message : String(err)}`,
-        },
-      ],
-    }
-  }
-}

package/packages/mcp/src/tools/fix-sequence-activations.ts

@@ -1,77 +0,0 @@
-// ============================================================================
-// zombie-mermaid MCP server — `fix_mermaid_sequence_activations` tool
-//
-// The "optionally proposes a fix" half of issue #539, complementing
-// `check_mermaid_sequence_activations` (which only reports issues). Reuses
-// packages/mermaid-parser/src/sequence/activation-fix.ts, which — see that
-// file's header — only auto-fixes DANGLING_ACTIVATION (a mechanically safe,
-// unambiguous append); UNMATCHED_DEACTIVATION comes back as a remaining
-// issue for a human (or a future LLM-based layer) to resolve rather than
-// risk an incorrect text edit.
-// ============================================================================
-
-import { z } from 'zod'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import { detectDiagramType } from '@zombie-mermaid/core'
-import { fixActivationBalance } from '@zombie-mermaid/mermaid-parser'
-
-export const fixSequenceActivationsInputShape = {
-  diagram: z
-    .string()
-    .min(1, 'diagram must not be empty')
-    .describe(
-      'Mermaid sequence diagram source text, e.g. "sequenceDiagram\\n  ' +
-        'activate A\\n  A->>B: hi". Must start with "sequenceDiagram" — ' +
-        'this tool does not check other diagram types.',
-    ),
-}
-
-export interface FixSequenceActivationsToolArgs {
-  diagram: string
-}
-
-/**
- * MCP tool handler for `fix_mermaid_sequence_activations`. Parses the given
- * source as a Mermaid sequence diagram, checks activation/deactivation
- * balance, and returns a structured JSON result: `ok`, the (possibly
- * unchanged) `fixedDiagram`, `fixesApplied` (human-readable descriptions),
- * and any `remainingIssues` that couldn't be auto-fixed.
- *
- * Returns an MCP tool error (`isError: true`, not a thrown exception) both
- * for invalid Mermaid syntax and for a non-sequence diagram, matching
- * `check-sequence-activations.ts`'s error handling.
- */
-export function fixSequenceActivationsHandler(
-  input: FixSequenceActivationsToolArgs,
-): CallToolResult {
-  try {
-    const diagramType = detectDiagramType(input.diagram)
-    if (diagramType !== 'sequence') {
-      return {
-        isError: true,
-        content: [
-          {
-            type: 'text',
-            text:
-              'This tool only fixes sequence diagrams (source must start ' +
-              `with "sequenceDiagram"); detected diagram type: "${diagramType}".`,
-          },
-        ],
-      }
-    }
-    const result = fixActivationBalance(input.diagram)
-    return {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    }
-  } catch (err) {
-    return {
-      isError: true,
-      content: [
-        {
-          type: 'text',
-          text: `Failed to fix diagram activations: ${err instanceof Error ? err.message : String(err)}`,
-        },
-      ],
-    }
-  }
-}

package/packages/mcp/src/tools/render-ascii.ts

@@ -1,99 +0,0 @@
-// ============================================================================
-// zombie-mermaid MCP server — `render_mermaid_ascii` tool
-//
-// Thin MCP adapter around the library's own renderMermaidASCII(). No new
-// rendering logic lives here — this only maps a validated tool call onto
-// AsciiRenderOptions and back onto an MCP CallToolResult.
-// ============================================================================
-
-import { z } from 'zod'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
-import type { AsciiRenderOptions } from '@zombie-mermaid/ascii-renderer'
-
-export const renderAsciiInputShape = {
-  diagram: z
-    .string()
-    .min(1, 'diagram must not be empty')
-    .describe(
-      'Mermaid diagram source text, e.g. "graph LR\\n  A --> B". Supports ' +
-        'flowcharts, state diagrams, sequence diagrams, class diagrams, and ' +
-        'ER diagrams.',
-    ),
-  useAscii: z
-    .boolean()
-    .optional()
-    .describe(
-      'true = plain ASCII characters (+, -, |, >); false/unset = Unicode ' +
-        'box-drawing characters (┌, ─, │, ►). Default: false.',
-    ),
-  paddingX: z
-    .number()
-    .int()
-    .nonnegative()
-    .optional()
-    .describe(
-      'Horizontal spacing between nodes. Default: 5. Flowchart/state diagrams only.',
-    ),
-  paddingY: z
-    .number()
-    .int()
-    .nonnegative()
-    .optional()
-    .describe(
-      'Vertical spacing between nodes. Default: 5. Flowchart/state diagrams only.',
-    ),
-  boxBorderPadding: z
-    .number()
-    .int()
-    .nonnegative()
-    .optional()
-    .describe(
-      'Padding inside node boxes. Default: 1. Flowchart/state diagrams only.',
-    ),
-}
-
-export interface RenderAsciiToolArgs {
-  diagram: string
-  useAscii?: boolean | undefined
-  paddingX?: number | undefined
-  paddingY?: number | undefined
-  boxBorderPadding?: number | undefined
-}
-
-/**
- * MCP tool handler for `render_mermaid_ascii`. Renders Mermaid source to a
- * plain ASCII/Unicode-art string.
- *
- * Color mode is deliberately fixed to `'none'` rather than exposed as an
- * option: the CLI's `--theme` flag produces ANSI color escapes meant for a
- * real terminal, but an MCP tool result is text inserted into a chat/agent
- * context, where raw ANSI escapes would render as garbage rather than
- * color. (In practice `renderMermaidASCII`'s own auto-detection already
- * resolves to `'none'` here, since the MCP server's stdout is a pipe used
- * for the JSON-RPC transport, not a TTY — this makes that outcome explicit
- * instead of incidental.)
- */
-export function renderAsciiHandler(input: RenderAsciiToolArgs): CallToolResult {
-  try {
-    const options: AsciiRenderOptions = {
-      useAscii: input.useAscii,
-      paddingX: input.paddingX,
-      paddingY: input.paddingY,
-      boxBorderPadding: input.boxBorderPadding,
-      colorMode: 'none',
-    }
-    const ascii = renderMermaidASCII(input.diagram, options)
-    return { content: [{ type: 'text', text: ascii }] }
-  } catch (err) {
-    return {
-      isError: true,
-      content: [
-        {
-          type: 'text',
-          text: `Failed to render diagram to ASCII: ${err instanceof Error ? err.message : String(err)}`,
-        },
-      ],
-    }
-  }
-}

package/packages/mcp/src/tools/render-svg.ts

@@ -1,95 +0,0 @@
-// ============================================================================
-// zombie-mermaid MCP server — `render_mermaid_svg` tool
-//
-// Thin MCP adapter around the library's own renderMermaidSVG(). No new
-// rendering logic lives here — this only maps a validated tool call onto
-// RenderOptions and back onto an MCP CallToolResult.
-// ============================================================================
-
-import { z } from 'zod'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import { renderMermaidSVG } from '../../../../src/index.ts'
-import { THEMES } from '@zombie-mermaid/core'
-import type { DiagramColors } from '@zombie-mermaid/core'
-
-/**
- * Narrow a string array to zod's required non-empty-tuple shape without an
- * `as` assertion. `THEMES` always has entries (it's a populated module-level
- * const), but `Object.keys()` returns a plain `string[]` the type system
- * can't statically know is non-empty.
- */
-function toNonEmptyStringTuple(values: string[]): [string, ...string[]] {
-  const [first, ...rest] = values
-  if (first === undefined) {
-    throw new Error('Expected at least one built-in theme to be registered')
-  }
-  return [first, ...rest]
-}
-
-const themeNames = toNonEmptyStringTuple(Object.keys(THEMES))
-
-export const renderSvgInputShape = {
-  diagram: z
-    .string()
-    .min(1, 'diagram must not be empty')
-    .describe(
-      'Mermaid diagram source text, e.g. "graph TD\\n  A --> B". Supports ' +
-        'flowcharts, state diagrams, sequence diagrams, class diagrams, ER ' +
-        'diagrams, and XY charts.',
-    ),
-  theme: z
-    .enum(themeNames)
-    .optional()
-    .describe(`Built-in theme name. One of: ${themeNames.join(', ')}`),
-  transparent: z
-    .boolean()
-    .optional()
-    .describe(
-      'Render with a transparent background instead of the theme background color. Default: false.',
-    ),
-  font: z
-    .string()
-    .optional()
-    .describe('Font family for diagram text. Default: "Inter".'),
-}
-
-export interface RenderSvgToolArgs {
-  diagram: string
-  theme?: string | undefined
-  transparent?: boolean | undefined
-  font?: string | undefined
-}
-
-/**
- * MCP tool handler for `render_mermaid_svg`. Renders Mermaid source to a
- * self-contained SVG string, returned as `text` content — SVG is XML text,
- * not the raster image the `image` content type expects.
- *
- * Catches rendering errors (e.g. invalid Mermaid syntax) and returns them
- * as an MCP tool error result (`isError: true`) instead of throwing, so a
- * bad diagram from the caller surfaces as a normal tool response rather
- * than a protocol-level failure.
- */
-export function renderSvgHandler(input: RenderSvgToolArgs): CallToolResult {
-  try {
-    const themeColors: DiagramColors | undefined = input.theme
-      ? THEMES[input.theme]
-      : undefined
-    const svg = renderMermaidSVG(input.diagram, {
-      ...themeColors,
-      transparent: input.transparent,
-      font: input.font,
-    })
-    return { content: [{ type: 'text', text: svg }] }
-  } catch (err) {
-    return {
-      isError: true,
-      content: [
-        {
-          type: 'text',
-          text: `Failed to render diagram to SVG: ${err instanceof Error ? err.message : String(err)}`,
-        },
-      ],
-    }
-  }
-}

package/packages/mermaid-parser/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Craft Docs
-Copyright (c) 2026 Dustin Fadler
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/packages/mermaid-parser/src/class/format.ts

@@ -1,15 +0,0 @@
-// ============================================================================
-// Class member formatting — shared between the SVG (layout.ts) and ASCII
-// (ascii/class-diagram.ts) renderers so method parentheses/params can't drift
-// between the two again. See issue #290.
-// ============================================================================
-
-import type { ClassMember } from './types.ts'
-
-/** Format a class member as a display string: visibility + name(+params for methods) + optional type */
-export function formatClassMember(m: ClassMember): string {
-  const vis = m.visibility ? `${m.visibility} ` : ''
-  const name = m.isMethod ? `${m.name}(${m.params || ''})` : m.name
-  const type = m.type ? `: ${m.type}` : ''
-  return `${vis}${name}${type}`
-}