Development

How to build, test and document rgxr.

Toolchain

Quick start

nix develop                    # dev shell (Rust itself: rustup, not Nix)

docker run -d --name rgxr-pg -p 5432:5432 \
  -e POSTGRES_USER=rgxr -e POSTGRES_PASSWORD=rgxr -e POSTGRES_DB=rgxr \
  postgres:17-alpine

DATABASE_URL=postgres://rgxr:rgxr@localhost:5432/rgxr \
RGXR_DEV_MODE=true cargo run -p rgxr-api
# api: http://localhost:8080/healthz
# api-docs (Swagger): http://localhost:8080/api-docs

cd web && bun install && bun run dev
# web: http://localhost:5173 — the dev proxy forwards /api to :8080

RGXR_DEV_MODE=true serves requests without a token as anonymous and allows the Vite origin for CORS.

The images build the same way CI does:

docker build -f api.Dockerfile .
docker build -f web.Dockerfile web/

Rust gates

Exactly as CI runs them:

cargo fmt --check
cargo clippy --workspace --all-targets --locked
cargo test --workspace --locked

No unwrap, no expect

Workspace clippy lints unwrap_used and expect_used are deny (root Cargo.toml, [workspace.lints.clippy]; every crate inherits via [lints] workspace = true, and new crates MUST too). Tests are exempt via #![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))] at the crate root; tests/ integration crates get the same attribute (there, panicking IS the assertion mechanism). In library and request paths, recover instead: return Result, map to FaError, or return an error envelope. A panic in prod code fails review no matter how unlikely the path.

Docs

User-facing documentation lives in docs/*.md (plus the top-level README.md, which compiles too) and renders to the committed docs-html/ site via tern + pandoc (both in the dev shell):

nix develop -c tern --update   # once, or after changing .tern/config.toml
nix develop -c tern            # incremental rebuild

Commit the regenerated docs-html/ together with the source change. Never hand-edit docs-html/ (overwritten on every run) or .tern/data/ (replaced by --update). Mermaid diagrams in markdown work; the pipeline ships a mermaid filter. Screenshots live in resources/images/ and are referenced from the docs by forge /media/branch/... URLs, so no image-copy step exists.

Tutorials

The per-section walkthroughs (regex, editor, OPS, grammar, machines) are data, not code: tutorial content lives in web/src/lib/tutorial/ as typed step lists with inline English and Spanish content (the dojo’s lines.ts is the precedent). The pattern itself (opt-in lightbulb, sensei dock, spotlight, [ SHOW ME ]) is described in Design notes.

CI

Forgejo Actions (.forgejo/workflows/ci.yaml), on pushes to master, on v* tags and on pull requests:

Docs rendering stays local (tern); CI does not build docs-html/.

Commits

Conventional-ish, one line: type(scope): summary. Types seen in the log are feat, fix, docs; the scope names the area (core, api, web, render) and is omitted when a change spans the tree. Work lands through PRs, and the summary cites the issues it closes:

feat(core): PDA, TM and answer grading (#44 #45) (#53)
fix(web): reliable sensei problem generation + verified TM library (#58)