Skip to content

CLAUDE.md

Latest commit

 

History

History
135 lines (95 loc) · 7.02 KB

CLAUDE.md

File metadata and controls

135 lines (95 loc) · 7.02 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

  • Start development server: bun dev (runs on port 14000)
  • Build library: bun build (builds library with vite.config.lib.ts)
  • Build site: bun build:site (builds demo site with vite.config.ts)
  • Run tests: bun run test (runs unit tests scoped to src/ and test/unit/, excluding E2E). Do NOT run bun test without arguments — it picks up Playwright E2E files and reports false failures.
  • Analyze E2E diff: node scripts/analyze-compare-case.mjs --case <name> --json (structured diff attribution for compare-case pages; --output-dir <dir> saves html.png, svg.png, diff.png, report.json)
  • Run E2E tests: bun pw (runs Playwright tests)
  • Run E2E tests (CI): bun pw:ci (runs with GitHub reporter for CI)
  • Open Playwright UI: bun pw:ui
  • Update Playwright snapshots: bun pw:update
  • Install Playwright browsers: bun pw:install
  • Run smoke tests: bun pw:smoke
  • Lint code: bun eslint (runs ESLint with auto-fix)
  • Format code: bun prettier (runs Prettier)
  • Generate ANTLR parser: bun antlr (generates JavaScript parser from grammar)

Project Architecture

ZenUML is a JavaScript-based diagramming library for creating sequence diagrams from text definitions. The project has two main parts:

1. DSL Parser (ANTLR-based)

  • Grammar files: src/g4/ contains ANTLR grammar definitions
  • Generated parser: src/generated-parser/ contains generated JavaScript parser
  • Parser enhancements: src/parser/ contains custom functionality layered on top of ANTLR

2. React-based Renderer

  • Core entry point: src/core.tsx - main library export and ZenUml class
  • Component structure: src/components/ - React components for rendering diagrams
  • Store management: src/store/Store.ts - Jotai-based state management
  • Positioning engine: src/positioning/ - algorithms for layout and positioning

Key Components Architecture

  • DiagramFrame: Main container component that orchestrates the entire diagram
  • SeqDiagram: Core sequence diagram renderer with layers:
    • LifeLineLayer: Renders participants and their lifelines
    • MessageLayer: Renders messages and interactions between participants
  • Statement components: Individual renderers for different UML elements (interactions, fragments, etc.)

Parser Architecture

The parser uses a two-stage approach:

  1. ANTLR-generated parser: Converts text to parse tree
  2. Custom parser layer: Transforms parse tree into structured data for rendering

Key parser modules:

  • Participants.ts: Manages participant detection and ordering
  • MessageContext.ts: Handles message parsing and context
  • FrameBuilder.ts: Builds the overall diagram structure
  • Fragment handling: Support for UML fragments (alt, opt, loop, par, etc.)

Build System

The project uses Vite with two configurations:

  • vite.config.ts: Development server and demo site build
  • vite.config.lib.ts: Library build (ESM and UMD outputs)

Output formats:

  • ESM: dist/zenuml.esm.mjs for modern bundlers
  • UMD: dist/zenuml.js for browser scripts

Testing Strategy

  • Unit tests: Vitest for parser and utility functions
  • Component tests: React Testing Library for component logic
  • E2E tests: Playwright for full integration testing with visual snapshots
  • Test files: Co-located with source files using .spec.ts / .spec.tsx extensions

E2E Screenshot Snapshot Updates

Never update Playwright screenshots just to make a failing snapshot test pass. Before committing any updated E2E screenshot:

  1. Compare the before and after screenshots and identify exactly where the visual differences are.
  2. Use the existing diagram diff workflow where applicable: run node scripts/analyze-compare-case.mjs --case <name> --json for structured attribution, or --output-dir <dir> to save html.png, svg.png, diff.png, and report.json.
  3. For compare-case pages, treat the native diff panel / analyzer output as the source of truth. Locate connected diff clusters, their bounding boxes/centroids, and the nearest semantic targets such as labels, arrows, participant boxes, participant icons, stereotypes, groups, fragments, or comments.
  4. Judge the identified differences against the actual code change in the commit. Only update snapshots when the changed pixels are an intentional and correct consequence of the code change.
  5. In the PR or commit notes, state which elements changed, where they changed, and why the screenshot update is correct.

Key Dependencies

  • React 19: UI framework
  • ANTLR4: Parser generation
  • Jotai: State management
  • Tailwind CSS: Styling framework
  • html-to-image: PNG export functionality
  • Vite: Build tool and development server

Package Management

Uses Bun as the package manager and JavaScript runtime. Bun is a fast all-in-one JavaScript runtime that includes a package manager, test runner, and bundler.

Test Configuration

  • Unit tests: bun run test — runs bun test src test/unit, scoping to unit test folders only (excludes /tests E2E folder)
  • Vitest: Tests also support Vitest for IDE integration compatibility
  • E2E tests: bun pw - Runs Playwright tests in /tests folder
  • Test setup: test/setup.ts configures test environment (mocks IntersectionObserver, etc.)
  • Tests use vi mocking utilities from Vitest
  • Test files use .spec.ts / .spec.tsx extensions and are co-located with source files

Bug Fix Process

When starting work on a bug (especially from a GitHub issue):

  1. Reproduce first — write a minimal test case (unit test or Playwright E2E) that demonstrates the bug. The test must fail before any code changes.
  2. Capture a baseline — if the bug is visual, take a Playwright snapshot or screenshot of the broken state before fixing. This serves as evidence of what changed.
  3. Fix the code — make the minimal change to fix the bug.
  4. Verify the fix — the failing test from step 1 must now pass. All other existing tests must still pass.

Never skip the reproduction step. If you can't reproduce it, you don't understand the bug well enough to fix it.

No Speculative Codebase Claims

NEVER claim what the codebase does, uses, or contains without first verifying by reading or grepping the code. Phrases like "if we're currently using X", "since we already have Y", or "the codebase uses Z pattern" are forbidden unless you have Read/Grep/Glob evidence from this conversation.

  • Before making a claim about codebase state, verify it — use a subagent (Explore) if needed.
  • General programming knowledge is fine. Claims about this codebase require evidence.

Development Notes

  • The project builds both a library and a demo site
  • Parser generation requires Java and ANTLR4
  • E2E tests use visual snapshots for regression testing
  • The library is published as @zenuml/core to npm
  • GitHub Pages deployment is automated via GitHub Actions