Skip to content
Ferrigura

Ferrigura / Guide

Developing ferrigura

How to set up the repository, run the checks, and make the common kinds of change. The rules behind it are 0003 (commit messages) and 0005 (what every change must pass).

Setup

  • Rust: the toolchain is pinned by rust-toolchain.toml (stable, with clippy and rustfmt); rustup installs it on first use.
  • Node.js and pnpm: the harness in tools/port needs Node.js 22.12 or newer and the pnpm version its package.json pins. With corepack (corepack enable), run pnpm from inside tools/port, where corepack finds that version; a pnpm installed on its own switches to it either way. The repository's root holds no JavaScript project, so every harness command runs with -C tools/port or from inside it.
  • The reference: tools/reference/setup.sh builds upstream Mermaid at the pin with its patches into target/reference/<commit>, in about half a minute the first time (0014). The harness takes it from there, or from REFERENCE_ROOT.
  • Chromium, for the geometry runs: pnpm -C tools/port exec playwright install chromium.
pnpm -C tools/port install

tools/reference/setup.sh

pnpm -C tools/port install also installs the pre-commit hook, which formats and lints the staged files.

  • The README: README.md is generated from README.md.src by mdtheme, which frames it with the Sebastian Software theme pinned in mdtheme.yaml. Edit the source, run mise run readme:write, and commit both. mise installs the mdtheme version that mise.toml and mise.lock pin; rendering fetches the theme from GitHub.
mise trust && mise install --locked

The checks

What CI runs on every change (0005):

cargo fmt --all --check

cargo clippy --all-targets -- -D warnings

RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace

cargo test --workspace

pnpm -C tools/port run lint

pnpm -C tools/port test

mise run readme:check

On an aarch64 machine (CI runs it on macOS), the output of the whole corpus is pinned by hashes:

cargo test --release --test snapshots

Checking a change against the reference

  • A parser change: pnpm -C tools/port port:diff <type> compares the canonical models of ferrigura and the reference on every input of the type.
  • A renderer change: pnpm -C tools/port port:geometry <type> renders the fixtures and probes with both in Chromium and compares the geometry; --filter <text> narrows the fixtures and --images <dir> writes side-by-side PNGs.
  • A change to shared code (text, the unified renderer, configuration) must not move the output of other types: run the snapshots, and tools/snapshots/diff.sh shows which renders moved.
  • A change that moves the output on purpose rewrites the snapshots in the same commit:
UPDATE_SNAPSHOTS=1 cargo test --release --test snapshots

tools/port/README.md lists every command of the harness, the run types, and the scripts that regenerate the corpora and fixtures.

A difference from the reference

Every difference has one place (0014):

  • ferrigura is wrong: fix ferrigura.
  • ferrigura is behind a newer Mermaid: a pending entry in tools/port/exceptions.ts, with the issue that tracks the fix.
  • Mermaid is wrong: a patch under tools/reference/patches/, a diff against the pinned commit with the earlier patches applied, whose header says what it fixes (tools/reference/README.md).
  • ferrigura leaves it out on purpose: an unsupported entry with its reason.

The Node.js packages

From node/:

pnpm install --frozen-lockfile --ignore-scripts

pnpm build

Then pnpm test, pnpm typecheck, pnpm lint, pnpm format:check and pnpm pack:check; the last installs the packed facade and the host's platform package into a fresh project. A local run exercises only the host's binary; CI builds and checks all seven targets (0016).

Releases

release-please opens a release pull request from the commit messages on main; merging it tags v<version> and publishes the crates and npm packages (0004). Nothing else is needed for a release. To retry a failed publish, run publish.yml by hand with the release's tag.

The website

The Ardo site in homepage/ uses the shared Ferramenta theme without local CSS. Its documentation routes are generated from the repository's canonical Markdown; edit those source files rather than the ignored generated routes. The authored entry guide lives in homepage/content/.

From homepage/, run pnpm install, then pnpm dev for a local server. pnpm verify checks the native SVG samples, website source, rendered links and browser behavior. The examples are rendered by the Rust CLI; no Mermaid runtime is shipped to render them in the visitor's browser. GitHub Actions deploys the site from main to GitHub Pages under /ferrigura/.