agentic-mermaid 0.1.1 → 0.2.0

package/src/class/types.ts

@@ -1,129 +0,0 @@
-// ============================================================================
-// Class diagram types
-//
-// Models the parsed and positioned representations of a Mermaid class diagram.
-// Class diagrams show UML class relationships, inheritance, composition, etc.
-// ============================================================================
-
-import type { PositionedDiagram } from '../types.ts'
-
-/** Parsed class diagram — logical structure from mermaid text */
-export interface ClassDiagram {
-  /** Optional accessibility title (Mermaid accTitle) */
-  accessibilityTitle?: string
-  /** Optional accessibility description (Mermaid accDescr) */
-  accessibilityDescription?: string
-  /** All class definitions */
-  classes: ClassNode[]
-  /** Relationships between classes */
-  relationships: ClassRelationship[]
-  /** Optional namespace groupings */
-  namespaces: ClassNamespace[]
-}
-
-export interface ClassNode {
-  id: string
-  label: string
-  /** Annotation like <<interface>>, <<abstract>>, <<service>>, <<enumeration>> */
-  annotation?: string
-  /** Class attributes (fields/properties) */
-  attributes: ClassMember[]
-  /** Class methods (functions) */
-  methods: ClassMember[]
-}
-
-export interface ClassMember {
-  /** Visibility: + public, - private, # protected, ~ package */
-  visibility: '+' | '-' | '#' | '~' | ''
-  /** Member name */
-  name: string
-  /** Type annotation (e.g., "String", "int", "void") */
-  type?: string
-  /** Whether the member is static (underlined in UML) */
-  isStatic?: boolean
-  /** Whether the member is abstract (italic in UML) */
-  isAbstract?: boolean
-  /** Whether the member is a method (renders with parentheses) */
-  isMethod?: boolean
-  /** Method parameters (e.g., "data", "key, val") — only for methods */
-  params?: string
-}
-
-/** Relationship types following UML conventions */
-export type RelationshipType =
-  | 'inheritance'   // A <|-- B   (solid line, hollow triangle)
-  | 'composition'   // A *-- B    (solid line, filled diamond)
-  | 'aggregation'   // A o-- B    (solid line, hollow diamond)
-  | 'association'   // A --> B    (solid line, open arrow)
-  | 'dependency'    // A ..> B    (dashed line, open arrow)
-  | 'realization'   // A ..|> B   (dashed line, hollow triangle)
-
-export interface ClassRelationship {
-  from: string
-  to: string
-  type: RelationshipType
-  /**
-   * Which end of the relationship line has the UML marker (triangle, diamond, arrow).
-   * Determined by the arrow syntax direction:
-   *   - Prefix markers like `<|--`, `*--`, `o--` → 'from' (marker on left/from side)
-   *   - Suffix markers like `..|>`, `-->`, `..>`, `--*`, `--o` → 'to' (marker on right/to side)
-   */
-  markerAt: 'from' | 'to'
-  /** Label on the relationship line */
-  label?: string
-  /** Cardinality at the "from" end (e.g., "1", "*", "0..1") */
-  fromCardinality?: string
-  /** Cardinality at the "to" end */
-  toCardinality?: string
-}
-
-export interface ClassNamespace {
-  name: string
-  classIds: string[]
-}
-
-// ============================================================================
-// Positioned class diagram — ready for SVG rendering
-// ============================================================================
-
-export interface PositionedClassDiagram extends PositionedDiagram {
-  width: number
-  height: number
-  accessibilityTitle?: string
-  accessibilityDescription?: string
-  classes: PositionedClassNode[]
-  relationships: PositionedClassRelationship[]
-}
-
-export interface PositionedClassNode {
-  id: string
-  label: string
-  annotation?: string
-  attributes: ClassMember[]
-  methods: ClassMember[]
-  x: number
-  y: number
-  width: number
-  height: number
-  /** Height of the header section (name + annotation) */
-  headerHeight: number
-  /** Height of the attributes section */
-  attrHeight: number
-  /** Height of the methods section */
-  methodHeight: number
-}
-
-export interface PositionedClassRelationship {
-  from: string
-  to: string
-  type: RelationshipType
-  /** Which end of the line has the UML marker — propagated from ClassRelationship */
-  markerAt: 'from' | 'to'
-  label?: string
-  fromCardinality?: string
-  toCardinality?: string
-  /** Path points from source to target */
-  points: Array<{ x: number; y: number }>
-  /** Dagre-computed label center position (avoids overlaps between nearby edges) */
-  labelPosition?: { x: number; y: number }
-}

package/src/cli/agent-instructions.ts

@@ -1 +0,0 @@
-export const AGENT_INSTRUCTIONS = "# Agentic Mermaid — agent-use guide\n\nThis is the canonical agent-use guide. The same content is emitted by `am --agent-instructions`. A doc-sync test asserts the two are byte-identical.\n\n## When to use Agentic Mermaid\n\nUse Agentic Mermaid when an agent needs to create, edit, verify, describe, or render Mermaid diagrams through deterministic library, CLI, or MCP calls. It is strongest when the workflow needs typed edits, semantic fact read-back, CI-safe verification, or reproducible SVG, PNG, ASCII, and Unicode output.\n\nDo not use the hosted MCP for private diagrams; use the local library, CLI, or self-hosted MCP so source stays in your environment. Use another tool when the artifact is not Mermaid source or requires freeform canvas editing that Mermaid cannot express.\n\n## Quick start\n\nChoose the narrowest channel. New diagrams: build with `buildMermaid(kind, ops)` — or `createMermaid(kind)` then typed mutations — and verify/render the result; author Mermaid source directly only for syntax the typed ops do not model. Existing structured diagrams: parse → narrow → mutate → verify → serialize. Code Mode/library are best for multi-step edits; CLI is best for one-shot verify/render/preview. Code Mode exposes `mermaid.*`; library users import the same names from `agentic-mermaid/agent` — including `describeOps(family)` and `opSignatures(family)`, which return each op's exact fields, required-ness, inlined enum values, and constraint/default notes (e.g. journey score `integer 1..5`, flowchart shape `default: rectangle`) so you can look up an unfamiliar op instead of guessing; use `describeMermaidFacts` / `checkMermaid` when you need semantic read-back such as `edge Processing -> [*] : done`, `member Duck +quack()`, or `task Docs start after core`. A hosted MCP at `agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC) exposes `execute` (Code Mode), `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, and the declarative `mutate` (edit a `source`) and `build` (author from a `family`) — which apply a JSON op list and return `{ok,family,source,verify}`, prescriptive `{ok:false,…,error}` on a bad op; prefer them for structured edits and reserve `execute` for logic the ops do not express — all with 64KB input caps; the call shape is a plain POST (stateless, no initialize handshake): `POST /mcp` with `content-type: application/json` and body `{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"verify\",\"arguments\":{\"source\":\"flowchart TD\\n  A --> B\"}}}`. Prefer the local library, CLI, or a self-hosted MCP and reach for the hosted endpoint only when you cannot install. Agentic Mermaid outputs ASCII, PNG, and SVG; Unicode text and JSON layout are also available. Flowchart authoring facts: quote any label carrying punctuation (`id[\"HTTPS /api/sessions*\"]`); `\\n` inside a quoted label is a line break and canonicalizes to `<br>` on serialize; `subgraph id[\"Title\"] … end` groups nodes; labeled and dotted edges are `A -- \"label\" --> B`, `A -.-> B`, and `A -. \"label\" .-> B`. For every other family, read that family's exact header, edge, and relationship syntax from its `example` in `am capabilities --json` (`capabilities.json` `families[].example`) rather than assuming flowchart syntax — e.g. class inheritance `Base <|-- Derived`, ER cardinality `A ||--o{ B : label`, architecture edges `api:R --> L:db`.\n\n```ts\nconst source = 'flowchart TD\\n  API --> DB'\nconst d0 = mermaid.parseMermaid(source)\nif (!d0.ok) throw new Error('parse')\n\nconst flow = mermaid.asFlowchart(d0.value)\nif (!flow) return { phase: 'narrow', family: d0.value.kind }\n\nconst d1 = mermaid.mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })\nif (!d1.ok) throw new Error('mutate')\n\nconst verify = mermaid.verifyMermaid(d1.value)\nif (!verify.ok) return { phase: 'verify', warnings: verify.warnings }\n\nreturn { source: mermaid.serializeMermaid(d1.value) }\n```\n\nBlank-slate authoring stays on the typed path — no hand-written source:\n\n```ts\nconst built = mermaid.buildMermaid('flowchart', [\n  { kind: 'add_node', id: 'API', label: 'API' },\n  { kind: 'add_node', id: 'DB', label: 'DB' },\n  { kind: 'add_edge', from: 'API', to: 'DB' },\n], { direction: 'LR' })\nif (!built.ok) return { phase: 'build', error: built.error }\n\nconst check = mermaid.verifyMermaid(built.value)\nif (!check.ok) return { phase: 'verify', warnings: check.warnings }\n\nreturn { source: mermaid.serializeMermaid(built.value) }\n```\n\nUse `asFlowchart` / `asState` / `asSequence` / `asTimeline` / `asClass` / `asEr` / `asJourney` / `asArchitecture` / `asXyChart` / `asPie` / `asQuadrant` / `asGantt` before mutating existing diagrams. State diagrams own a dedicated body: `asState` narrows them and state-shaped ops (`add_state`, `add_transition`, `make_composite`, …) apply; `asFlowchart` returns null on a state diagram. Sequence diagrams are segment-preserving: one with `Note`/`alt`/`loop`/`par`/`activate`/`autonumber`/`title` still narrows via `asSequence` and keeps its participant/message ops while those unmodeled lines ride along verbatim; `remove_message`/`set_message_text` indexes address only top-level messages (messages inside an `alt`/`loop` block are not touched); only an un-segmentable sequence (e.g. an unbalanced `end`) falls back to opaque. Gantt charts are segment-preserving too: title/section/task ops stay live while calendar directives (`dateFormat`, `excludes`, …), `click` lines, and comments ride along verbatim; gantt rendering never reads the wall clock — pass `ganttToday` to draw the today marker. In Code Mode, SDK-returned diagrams are read-only; structured edits must go through `mermaid.mutate`. Opaque-fallback bodies (any unmodeled syntax) round-trip losslessly as source-level bodies but do not expose structured mutation; return an unsupported-family result unless the task explicitly asks for source-level editing, then re-parse and verify before returning.\n\n## The verify-before-commit rule\n\nRun `verifyMermaid` at every commit point — anywhere the result would be saved, sent, or shown. For new diagrams, verify the authored source. For existing diagrams, verify after mutation and before serializing. You may batch several `mutate` calls between verifications, but never serialize a `ValidDiagram` whose `verify` result you have not inspected. `verify.ok` is structural, not a visual-quality or semantic-correctness score; for task-critical meaning, inspect `describeMermaidFacts(d)` or call `checkMermaid(d, requiredFacts)` before returning.\n\n## Tier 1 vs Tier 2 vs Tier 3 warnings\n\nTier 1 (structural, reliable, universal): `EMPTY_DIAGRAM`, `EDGE_MISANCHORED`, `OFF_CANVAS`, `GROUP_BREACH`, `UNKNOWN_SHAPE`, `LABEL_OVERFLOW` (rendered-line char count over the longest displayed line — `<br>`/`\\n` split lines, XML entities decode to one char, formatting tags strip; default cap 40, raise via `labelCharCap` / `am verify --label-cap N` when long labels are intentional instead of truncating the user's text), `UNRESOLVABLE_SCHEDULE` (gantt: parses but the schedule cannot resolve — render would fail; `reason` names the `GANTT_*` error), `RENDER_FAILED` (any family: the source verifies structurally but the strict render parser throws, so rendering would fail; `reason` carries the renderer error — a clean verify proves the diagram actually renders). Applies to every family. Never suppress Tier 1 errors.\n\nTier 2 (geometric, advisory, flowchart-specific): `NODE_OVERLAP`, `ROUTE_SELF_CROSS`, plus the route-contract tripwires `ROUTE_HITCH`, `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`, `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`, `ROUTE_STALE_AFTER_NODE_MOVE` (docs/design/system/route-contracts.md — the layout pipeline upholds these itself, so they fire only on pipeline regressions). Route tripwires fire for flowchart/state; class and ER additionally run boundary-anchor and overlap checks (`ROUTE_SHAPE_MISANCHOR`, `NODE_OVERLAP` on class/entity boxes). For other families, geometric concerns surface via perceptual metrics (`measureQuality(layoutMermaid(d))`). See `docs/quality.md`. Don't gate CI on Tier 2 alone.\n\nTier 3 (lint, advisory): `DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `INEFFECTIVE_CONFIG`. These catch common agent mistakes, source-preserved Mermaid syntax that is not fully modeled, and content-bearing sources whose local layout renders nothing. They never flip `verify.ok`; inspect and fix when the task asks for clean maintainable diagrams. `DECISION_BRANCH_UNLABELED` means a multi-exit decision diamond has an unlabeled branch. `COMMENT_DROPPED` means in-body `%%` comments will not survive structured serialization; the leading wrapper (frontmatter, `%%{init}%%` directives, comments before the header) always round-trips byte-verbatim. `UNSUPPORTED_SYNTAX` means either a Mermaid construct (for example flowchart edge IDs, edge metadata, click/href, or markdown strings) is preserved losslessly as source but is not fully modeled by local structured mutation/render semantics, or `syntax: \"empty_layout\"` means the source carries content but the local layout produced a 0x0 canvas with no nodes, edges, or groups. Inspect the warning message and `verify.layout` before accepting the artifact. `CONTENT_DROPPED_ON_ROUNDTRIP` means the structured node/edge/group tally changed across a parse → serialize → re-parse cycle — canonical serialization is silently dropping or duplicating content even though the bytes may re-parse; treat it as a faithfulness bug to report. `INEFFECTIVE_CONFIG` means a Mermaid config field was accepted for compatibility but has no effect on this family's output (the warning names the field).\n\n## CLI verbs\n\n`am capabilities --json` — JSON envelope listing families, `families[].editPolicy`, `families[].mutationOps`, warning codes, output formats (`svg`, `ascii`, `unicode`, `png`, `json`). Schema-stable; use it to self-discover.\n`am batch --jsonl` — JSONL stdin → JSONL stdout for render/verify/parse/serialize/mutate. Malformed lines surface error but don't abort the stream.\n`am render <file…> --format svg|ascii|unicode|json [--security strict] [--style <names|file.json>] [--seed N]` — JSON = layout shape; --security strict = no external-fetch refs; `--style` takes a stack (comma-separated names and/or .json spec files, merged left → right, e.g. `--style hand-drawn,dracula`) and applies to svg/png; `--seed` re-rolls styled ink. Multiple files → results array for non-PNG formats. `--watch` is single-file/non-PNG only. PNG uses `--format png --output file.png` for one input and does not support watch/multi-input.\n`am preview <file|-> [--output out.html] [--open] [--json] [--security strict]` — standalone strict-mode HTML preview for human inspection.\n`am mutate <file|-> (--op '<JSON>'|--ops '<JSON array|file>') [--json]` — apply mutation(s), run verify, emit source only if verify succeeds. JSON success includes `{ok,source,verify}`; verify failure exits 3 and omits source.\n`am verify <file|-> [--json] [--label-cap N] [--suppress CODES]` — full tiered verify; exit 3 only on error-severity findings. `am parse` (ValidDiagram JSON), `am serialize` (ValidDiagram JSON on stdin → canonical source), and `am format` (idempotent reformat) round out the loop.\n`am describe <file|-> [--format text|json|facts]` — prose summary, structured AX tree (`{nodes,edges,entryPoints,sinks}`, #7349), or semantic fact lines. Library: `describeMermaid(d, {format})`, `describeMermaidFacts(d)`, `checkMermaid(d, facts)`.\n`am styles [--json]` — list registered styles: the default, full looks, and palette-only themes, with backends and blurbs.\n`am llms-txt` — agent-discovery digest (llms.txt convention).\n`am init-agent [--dir .] [--force]` — writes a non-clobbering AGENTS.md section, root skills/ bundle, and .mcp.json sample into a consumer repo.\n`am render-markdown <file.md> [--ascii]` — render each Mermaid fenced block; skips invalid diagrams, never aborts the file. JSON: `{blocks:[{index,ok,output|error}]}`.\nExit codes: `0` ok, `2` arg/parse/mutation error, `3` verify-failed, `4` internal. Parse and verify-failure errors carry `error.details` arrays, not stringified blobs.\n\nLibrary extras: `renderMermaidPNG(src,{fitTo,background,style,seed,fontDirs})` returns PNG bytes; `renderMermaidASCIIWithMeta(src)` → `{ascii,regions,warnings,routeParity}` for TUI click-mapping; `describeMermaidFacts(d)` / `checkMermaid(d, facts)` expose deterministic semantic facts; `analyzeMermaid(d)` / `analyzeMermaidSource(source)` returns non-rendering feedback/action/Gantt analysis; `asciiToMermaid(ascii)` reverses flowchart ASCII (best-effort, lossy); `verifyNoExternalRefs(svg)` asserts no external fetch; `renderMermaidSVG(src,{idPrefix})` namespaces def ids for multi-diagram pages. See SECURITY.md.\n\n## Styles\n\nEvery library render call accepts `style`: a built-in name (for example `hand-drawn`, `watercolor`, `blueprint`, `accessible-high-contrast`, `status-dashboard`, or any theme name — a theme is a palette-only style), an inline spec (a plain JSON record of palette/font/stroke/fill/backdrop fields, all optional), or a stack merged left → right (`{ style: ['hand-drawn', 'dracula'] }`). `seed` re-rolls the ink wobble of styled looks and never moves layout, so `(source, style, seed)` reproduces an image exactly. Custom styles are data, not code: check untrusted records with `validateStyleSpec(json)` (returns problems; `[]` = usable) and register reusable ones with `registerStyle({ name, ... })` — importable from `agentic-mermaid` and `agentic-mermaid/agent`. `style: 'crisp'` (or unset) is the byte-identical default; styles apply uniformly to all twelve families. The authoring guide and quality rubric live in docs/style-authoring.md. SVG declares any font; PNG bundles the faces the built-in looks use and falls back to DejaVu Sans for unbundled families (supply extras via `fontDirs`).\n\n## Anti-patterns\n\n- Regenerating an existing parsed diagram instead of mutating it. Defeats round-trip; produces noise.\n- Verifying only after a long risky edit chain. Loses precision about which op broke it.\n- Serializing before reading `verify.ok` / `verify.warnings` / `verify.layout`.\n- Concatenating source to edit an existing structured diagram when a typed `mutate` op exists. For new diagrams prefer `buildMermaid`/`createMermaid`; direct source authoring is fine for unmodeled syntax.\n- Calling `mutate` on an opaque-fallback body; the structured-family narrower returns null for unmodeled syntax, so edit its preserved source instead.\n"

package/src/cli/am-bin.ts

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-// Published CLI entrypoint (node-runnable). The Bun-based bin/am.ts is kept for
-// local development; tsup compiles this file to dist/am.js for npm consumers.
-import { runAmCli } from './run-entrypoint.ts'
-
-const code = await runAmCli(process.argv.slice(2)); if (code !== 0) process.exit(code)

package/src/cli/exit-codes.ts

@@ -1,18 +0,0 @@
-// ============================================================================
-// am CLI — exit code conventions.
-//
-// Replaces the inline 0/1/2 literals across src/cli/index.ts with a single
-// shared scheme so downstream scripts can branch on cause-of-failure.
-// ============================================================================
-
-/** Success. The command produced its expected output. */
-export const EXIT_OK = 0
-
-/** Usage / argument-parse error (bad flag, missing file, malformed --op JSON). */
-export const EXIT_ARG_ERROR = 2
-
-/** Verify ran successfully but the diagram has errors (warnings of severity 'error'). */
-export const EXIT_VERIFY_FAILED = 3
-
-/** Uncaught exception inside the CLI (a bug). */
-export const EXIT_INTERNAL = 4