Skip to content

setup.md

Latest commit

 

History

History
108 lines (77 loc) · 4.08 KB

setup.md

File metadata and controls

108 lines (77 loc) · 4.08 KB
Raw

Developer Setup

Quick start with mise

The fastest way to get a complete dev environment is with mise:

# Clone the repo
git clone git@github.com:kevinswiber/mmdflux.git
cd mmdflux

# Install all tools (Rust nightly, Node, cargo bins, etc.)
# Git hooks are installed automatically as part of cocogitto setup.
mise install

# Verify everything works
just check

mise reads mise.toml at the project root and installs everything automatically, including git hooks for Conventional Commits enforcement. The stable Rust toolchain is managed separately by rust-toolchain.toml via rustup.

Manual setup

If you prefer to manage tools yourself, install the following:

Tool Purpose Install
Rust (stable + nightly) Build, test, format rustup install stable nightly
just Task runner cargo install just or brew install just
cargo-nextest Parallel test runner cargo install cargo-nextest
cocogitto 6.5.0 Conventional Commits enforcement cargo install cocogitto@6.5.0
cargo-edit cargo set-version used by release hooks cargo install cargo-edit
Node.js (LTS) MMDS packages, module-map scripts, dagre debug scripts via nvm or brew
jq JSON processing in scripts and hooks brew install jq or system package manager

Optional (for specific workflows):

Tool Purpose Install
wasm-pack WebAssembly builds cargo install wasm-pack
gh GitHub CLI for CI checks and release assets brew install gh
@mermaid-js/mermaid-cli Mermaid parity comparison npm install -g @mermaid-js/mermaid-cli

First-time setup

# Clone the repo
git clone git@github.com:kevinswiber/mmdflux.git
cd mmdflux

# Install git hooks (enforces Conventional Commits)
just setup-hooks

# Verify everything works
just check

Commit conventions

This project uses Conventional Commits. The commit-msg hook validates messages automatically via cocogitto.

Format: <type>(<optional scope>): <description>

Types: feat, fix, chore, docs, refactor, test, ci, perf, style, build

For non-trivial changes, include a body after a blank line explaining what changed and why.

Day-to-day commands

Run just to see all available recipes. The most common:

just test              # Run all tests
just lint              # Clippy + fmt check
just check             # Lint + test + architecture
just fmt               # Format code
just run diagram.mmd   # Run the CLI

See the Justfile for the full list.

Diagnostics and tracing

The CLI supports opt-in tracing output for development diagnostics:

mmdflux --log mmdflux::runtime=debug diagram.mmd >/tmp/render.txt
mmdflux --log mmdflux::graph::grid::routing=trace --log-format json diagram.mmd
mmdflux --log mmdflux::engines::graph::algorithms::layered::kernel::order=trace --log-file /tmp/mmdflux.log diagram.mmd

--log takes precedence over MMDFLUX_LOG; MMDFLUX_LOG takes precedence over RUST_LOG. Tracing output goes to stderr unless --log-file is provided, so rendered text, SVG, and MMDS output remain safe to pipe from stdout.

xtask accepts the same global tracing flags before the subcommand and uses MMDFLUX_XTASK_LOG before falling back to RUST_LOG:

cargo xtask --log xtask=debug architecture check
MMDFLUX_XTASK_LOG=xtask=debug cargo xtask readme-assets check

Parity fixture dumpers such as MMDFLUX_DEBUG_PIPELINE, MMDFLUX_DEBUG_LAYOUT, and MMDFLUX_DEBUG_BORDER_NODES remain separate deterministic file/stderr contracts. Use trace filters for interactive diagnostics and the MMDFLUX_DEBUG_* dumpers only for their documented parity or probe artifacts.