Skip to content
effect-analyzer

All Formats Reference

effect-analyzer supports over 25 output formats. Use --format <name> on the CLI, or let auto mode select the best combination for your program.

Mermaid Diagrams

Section titled “Mermaid Diagrams”
Format CLI Flag Description Best For
Standard flowchart --format mermaid Full control-flow graph with all paths Complex programs with branching
Railway --format mermaid-railway Linear happy path with error branches Sequential generators
Execution paths --format mermaid-paths Each execution path as a separate flow Understanding all possible routes
Enhanced --format mermaid-enhanced Rich annotations (types, services, errors) per node Documentation and review
Service map --format mermaid-services Service dependency graph Understanding DI topology
Error flow --format mermaid-errors Error producers, handlers, propagation Debugging error handling
Decision tree --format mermaid-decisions Conditional branching visualization Programs with many if/match
Cause hierarchy --format mermaid-causes Cause and Exit wrapping structure Cause/Exit pattern analysis
Concurrency --format mermaid-concurrency Parallel and race fork/join structure Programs with Effect.all/Effect.race
Timeline --format mermaid-timeline Step sequence as a timeline Temporal ordering of steps
Layer graph --format mermaid-layers Layer composition and dependencies Layer architecture review
Retry strategy --format mermaid-retry Retry and timeout policy visualization Programs with retry/timeout
Testability --format mermaid-testability What needs mocking and what to test Test planning
Data flow --format mermaid-dataflow Data dependencies between pipe steps Understanding value flow
Composition (library API) Cross-program call graph Multi-program projects

Structured Output

Section titled “Structured Output”
Format CLI Flag Description Best For
JSON --format json Full IR serialized as JSON Tooling integration
Stats --format stats Complexity metrics and analysis statistics Quick complexity check
Explain --format explain Plain-English narrative of program behavior Documentation, onboarding
Summary --format summary One-line description per program Directory overviews
Matrix --format matrix Program-by-service dependency table Cross-cutting dependency view
Showcase --format showcase Detailed step-by-step breakdown Comprehensive documentation
Migration --format migration Patterns that could migrate to Effect Adoption planning

Statecharts

Section titled “Statecharts”

These read @typeonce/effect-machine machines (Machine.make({...}).handle({...})) rather than the Effect IR, so they work on machine-only files that contain no Effect program. See State Machines.

Format CLI Flag Description Best For
Mermaid statechart --format mermaid-statechart Machine as stateDiagram-v2, coverage-annotated Embedding in markdown
SVG statechart --format svg-statechart Self-contained XState-styled SVG Sharing a single file
Local visualizer --format statechart-html One page: SVG, coverage report, XState config Reviewing a machine
XState config --format xstate-config Paste-ready createMachine({...}) stately.ai/viz import
Coverage report --format statechart-coverage Unhandled events, unreachable states, dead ends CI gate (exits non-zero on warnings)
Terminal window
# Diagram + coverage + paste-ready config, opened in your browser
npx effect-analyze ./machine.ts --format statechart-html --open


# CI gate with a coverage floor, or JSON for dashboards
npx effect-analyze ./src --format statechart-coverage --min-coverage 60
npx effect-analyze ./src --format statechart-coverage --coverage-json

API Documentation

Section titled “API Documentation”
Format CLI Flag Description Best For
API docs --format api-docs HttpApi structure as markdown API documentation
OpenAPI paths --format openapi-paths Minimal OpenAPI paths for spec merging OpenAPI integration
OpenAPI runtime --format openapi-runtime Full OpenAPI spec via OpenApi.fromApi Complete spec generation

Interactive

Section titled “Interactive”
Format How to Use Description Best For
Interactive HTML renderInteractiveHTML(ir) (library API) Self-contained HTML with search, filtering, path explorer, themes Exploration, sharing

Auto Mode

Section titled “Auto Mode”

When no --format is specified, the analyzer runs in auto mode:

  1. Selects a baseline diagram - railway for simple programs, flowchart for complex ones
  2. Scores the program’s characteristics (error density, service count, concurrency, etc.)
  3. Adds up to 2 specialized views based on the highest-scoring characteristics
Terminal window
# Auto mode (default)
npx effect-analyze ./src/program.ts


# Equivalent to explicitly requesting auto
npx effect-analyze ./src/program.ts --format auto

Combining with Output Options

Section titled “Combining with Output Options”

All formats support the following output options:

Terminal window
# Save to file
npx effect-analyze ./src/program.ts --format mermaid-railway -o diagram.md


# Compact JSON (no indentation)
npx effect-analyze ./src/program.ts --format json --compact


# Control flow direction
npx effect-analyze ./src/program.ts --format mermaid --direction LR


# Include trivial programs (schemas, thin wrappers)
npx effect-analyze ./src/program.ts --include-trivial
Section titled “Related”