Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (71 loc) · 5.78 KB

CONTRIBUTING.md

File metadata and controls

88 lines (71 loc) · 5.78 KB
Raw

Contributing to ECAA-workflow

Build requirements

  • Rust — pinned via rust-toolchain.toml. rustup installs the channel automatically on first cargo invocation. Required components (rustfmt, clippy, rust-src) are part of the pin.
  • mold linker — apt install mold (Debian/Ubuntu), dnf install mold (Fedora), brew install mold (macOS). .cargo/config.toml routes the linker through it.
  • cargo-nextest (optional) — cargo install --locked cargo-nextest. Process-per-test runner; falls back to cargo test when absent.
  • sccache (required) — cargo install --locked sccache. .cargo/config.toml sets rustc-wrapper = "sccache" unconditionally, so the build fails without it on PATH; make doctor surfaces its absence. (No manual RUSTC_WRAPPER export needed.)
  • cargo-hakari (required if you touch any Cargo.toml) — cargo install --locked cargo-hakari. Regenerate workspace-hack with cargo hakari generate && cargo hakari manage-deps --yes.
  • bacon (optional) — cargo install --locked bacon. Background cargo check/test/clippy for the inner loop; bacon.toml pre-configures jobs.
  • Node.js 20+ and npm — for the web UI in ui/ and the Playwright e2e tier.
  • GNU make — used by every shortcut here.
  • Python 3.10+ (optional) — only needed for a handful of helper scripts.

Run make doctor after install to verify every tool is on PATH.

Build and test

make build     # cargo build
make test      # cargo test --workspace
make check     # test + tsc --noEmit on the UI
make clippy    # cargo clippy --workspace -- -D warnings
make fmt       # cargo fmt --all
make test-ui   # Vitest on ui/
make e2e-playwright  # Playwright mocked tier

make help lists every target with a one-line description.

Workspace layout

crates/
  core/             — classifier, atom registry, archetype registry, modality registry,
                      composer, RO-Crate emitter, claim verifier, task model
  conversation/     — LLM-mediated chat service (Anthropic client, sessions, tools, prompt)
  cli/              — ecaa-workflow binary (chat, intake, build, dag, serve)
  server/           — ecaa-workflow-server binary (Axum HTTP + SSE backend)
  harness/          — ecaa-workflow-harness binary (agent loop executor + ProgressClient)
  ecaa-conformance/ — ECAA validator + types
  ecaa-types/       — shared type schema for ECAA package + audit-proof output
  workspace-hack/   — auto-generated by cargo hakari to unify dependency resolution
ui/                 — React 18 + Vite + TypeScript frontend
e2e/                — Playwright end-to-end tests (mocked tier)
lib/plotting{,_r}/  — Python + R plot renderers executed in the agent container
config/
  modalities/         — per-modality manifests
  modality-keywords.yaml
  project-class-keywords.yaml
  archetypes/         — composer fast-path: declarative scaffolds over atoms
  stage-atoms/        — atom library: typed (operation × input × output) triples
  downstream-policy/  — JSON policies emitted into packages
  compute-profiles/   — AWS + SLURM sizing tables + GPU capability map
  gene-panels/        — marker-gene YAMLs consumed by discover_* stages
  plot-affordances/   — semantic type → renderer module registry
scripts/            — operational + agent dispatch shell/Python scripts
testdata/scenarios/ — public-data test scenarios
tests/              — conversation fixture corpus, golden workflows, auditability corpus
docs/ecaa-spec/     — ECAA conformance contract: TTL, SHACL, JSON-LD, 8 JSON Schemas

All four binaries link against crates/core; CLI/server also link against crates/conversation. Never fork logic between a binary and core — put it in core and call it from the binary.

Code conventions

  • cargo fmt and cargo clippy -D warnings are enforced. Run them before pushing.
  • Deterministic output. Emitted packages must be byte-reproducible for the same intake and config. Use BTreeMap, not HashMap; avoid timestamps in generated artifacts; avoid random IDs outside uuid_short().
  • Compiler is synchronous. tokio is allowed in server, conversation, and cli (for serve only). Never in core or harness. Harness uses ureq (sync).
  • LLM as UX shim. Closed tool vocabulary (Tool::COUNT asserted at compile time). High-impact actions are gated by deterministic server state, not LLM inference.
  • Confirmation discipline. emit_package returns PreconditionFailure unless session.user_confirmed == true. It must be the only tool call in its turn.
  • Adding a modality requires (1) a manifest under config/modalities/<id>.yaml, (2) the matching archetype under config/archetypes/<id>.yaml, (3) a classifier or composer test case in crates/core.

UI conventions

  • React 18 function components + hooks only. No router, no global state library, no CSS-in-JS runtime.
  • App.tsx owns the single useConversation and useSseChatEvents instances and threads them into both panes. One session + one EventSource per page.
  • ui/src/api/chatClient.ts is the source of truth for the chat REST contract. ui/src/types/ is generated by make types — don't hand-edit.

Commit conventions

  • One logical change per commit.
  • Commit messages follow Conventional Commits (feat(core):, fix(cli):, docs:, refactor:, test:).
  • Include the matching test update in the same commit as the code change when feasible.

Comment hygiene

Source comments describe what the code does and why, not when it was written. Do not reference plan documents, phase/sprint identifiers, PR numbers, ticket IDs, or implementation dates in source comments. Put that context in the commit message — it rots gracefully and stays discoverable via git log / git blame.