# Contributing to eggsact
## Prerequisites
- **Rust toolchain** (stable, minimum 1.89.0) -- `rustup` is recommended for installation.
- **Python 3.x** -- required for parity tests only. Install `eggcalc` dependencies from
the repo root.
Verify your setup:
```sh
rustc --version
python --version
cargo --version
```
## Building
```sh
cargo build # debug build
cargo build --release # optimized release build
```
The debug binary lands in `target/debug/eggsact`. The parity test suite expects this
path, so run `cargo build` before running parity tests.
## Testing
```sh
cargo fmt --all -- --check # formatting gate (CI-equivalent)
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features # all tests (unit, integration, parity)
cargo run --locked --features dev-tools --bin generate-docs -- --check # generated docs freshness
cargo package --locked --verbose # crates.io package verification
cargo test --locked --lib # unit tests within src/ only
cargo test --locked --test lib parity # parity tests against Python
cargo test --locked --doc # doc tests
cargo deny check advisories bans licenses sources # supply-chain audit
```
Unit tests live inside `src/` files as `#[cfg(test)]` modules. Integration and parity
tests live in `tests/`. The parity test entry point is `tests/lib.rs`, which declares
the `parity` module.
## Project Structure
```
eggsact/
src/
main.rs # CLI entry point, argument parsing
lib.rs # Library root, re-exports run()/evaluate()
calc/ # Calculator core (5 files)
mod.rs
evaluator.rs # AST-based expression evaluation
normalize.rs # Natural language normalization
units.rs # Unit definitions and conversion
context.rs # Per-evaluation mutable state (EvalContext)
mcp/ # MCP server protocol, runtime, registry, validation
server.rs # Protocol orchestration, stdio loop, dispatch
compat.rs # CompatibilityMode enum
registry/ # Tool registration (ToolSpec declarations, single source of truth)
mod.rs # Re-exports, tests
types.rs # ToolDefinition, ToolSpec, enums
all_tools.rs # ALL_TOOLS aggregation from specs/
listing.rs # Filtering, audience, schema compaction
specs/ # ToolSpec declarations per tool category
mod.rs # Re-exports all category slices
math.rs # MATH_TOOLS
text.rs # TEXT_TOOLS
... # One file per category
protocol.rs # JSON-RPC types
response.rs # ToolResponse, error sanitization, finding helpers
runtime.rs # Rate limiter, constants, profile management
schema_validation.rs
machine_codes.rs # Machine-readable response codes
budget.rs # Per-tool budgets, composite sub-budgets
schemas/ # JSON-schema builders per tool category
mod.rs
...
tools/ # MCP tool implementations (by category)
helpers.rs # Shared constants, utilities
math.rs # Math & unit tools
text.rs # Text processing tools (18)
json.rs # JSON tools (6)
regex.rs # Regex tools (3)
validation.rs # Validation tools (4)
path.rs # Path tools (6)
shell.rs # Shell tools (4)
list.rs # List tools (3)
markdown.rs # Markdown tools (2)
patch.rs # Patch tools (5)
config.rs # Config tools (3) + TOML shape tool (toml category handler lives here)
identifier.rs # Identifier tools (3)
unicode.rs # Unicode tools (2)
version.rs # Version tools (2)
cargo.rs # Cargo tool (1)
dependency.rs # Dependency tool (1)
diagnostics.rs # Diagnostics tools (3)
repo.rs # Repo tools (5)
analysis.rs # Analysis tools (4)
network.rs # Network literal tools (2)
encoding.rs # Codec and radix tools (2)
temporal.rs # Datetime and cron tools (2)
agent/ # In-process agent API (ToolRegistry, Profile, call_json)
preflight/ # Typed preflight wrappers
services/ # Typed composite services (RepoFacts, PatchAnalysis, SecurityInspection, ...)
temporal/ # Fixed-offset datetime/cron cores (leaf, like text/)
text/ # Text processing library (27 modules)
integrate.rs # Read-only per-client MCP setup renderers
update.rs # Verified binary self-update
tests/
lib.rs # Test entry point
parity/ # Python/Rust comparison tests
mcp/ # MCP protocol tests
calc/ # Calculator tests
text/ # Text processing tests
```
## Adding a New MCP Tool
1. **Implement the function** in `src/tools/<category>.rs`. Follow the existing pattern:
take `&Value`, validate arguments at the boundary, call a library function when
one exists, and return `ToolResponse`.
2. **Add a `ToolSpec` entry** in `src/mcp/specs/<category>.rs`. This is the single
source of truth for tool registration — it defines the handler, category, tier,
tags, profiles, input schema, and output schema all in one place. Each category
exports a `pub const <CATEGORY>_TOOLS: &[ToolSpec]` slice, which `all_tools.rs`
aggregates into the combined `ALL_TOOLS`.
3. **Run the invariant test** to verify sync:
```bash
cargo test --locked tool_registration_tables_are_in_sync -- --nocapture
```
4. **Regenerate docs** from the registry:
```bash
cargo run --locked --features dev-tools --bin generate-docs
```
This updates the profile reference block in `architecture/mcp-server.md`
and `generated/tool-cards.md`. README is hand-maintained and not touched.
5. **Prefer reusable library code** under `src/text/` or `src/calc/` for business
logic. Keep `src/tools/*.rs` wrappers thin so the same behavior is testable
without going through JSON-RPC.
6. **Add tests** at the right layer:
- Library behavior: `tests/text/` or `tests/calc/`.
- MCP request/response behavior: `tests/mcp/`.
- Python reference compatibility: `tests/parity/` using `compare_tool_parity()`.
## Adding a New Text Processing Function
1. **Add the implementation** in the appropriate module under `src/text/`. Match the
existing code style for that module.
2. **Re-export from `src/text/mod.rs`** if the function is part of the public API.
Add a `pub use` line and update the `pub mod` list if you created a new module.
3. **Add unit tests** in the same file as `#[cfg(test)]` module, or in a separate file
under `tests/text/` for integration-level coverage.
4. **Add an MCP tool wrapper** if the function should be exposed to MCP clients. Create
a thin wrapper in `src/tools/<category>.rs` that parses input, calls your function, and
returns the result as a `ToolResponse`. Add a `ToolSpec` entry in `src/mcp/specs/<category>.rs`
and run `cargo run --features dev-tools --bin generate-docs` to regenerate docs.
## Code Style
- Use type annotations on all public functions and structs.
- Use `serde` for JSON serialization. Derive `Serialize` and `Deserialize` on data
structures.
- Follow existing naming conventions: snake_case for functions and variables,
PascalCase for types.
- Keep error types consistent with the existing set: `input_too_large`,
`invalid_arguments`, `evaluation_error`, etc.
- Prefer `std::collections::HashMap` for hash maps (no external hash-map dependency).
- Keep the crate standard-library-plus-minimal-deps. Check `Cargo.toml` before
adding a new dependency.
## Parity with Python
The parity suite compares Rust MCP tool output against the Python `eggcalc` reference.
It requires Python 3.x and `eggcalc` at `../eggcalc` (sibling directory).
```sh
cargo test --test lib parity
```
As of 2026-09-11, the Rust parity suite has known gaps documented in `docs/parity.md`
(`Verification status` and `Known parity gaps` sections). The 86-tool Rust superset
passes for matching tools; the 37 remaining failures are categorized as accepted
behavioral differences (shell tokenization, prompt input inspect, unicode policy check,
tool output drift, tools/list ordering, and error handling drift). Closing these gaps
is out of scope for release polish and is tracked for follow-up work.
When changing behavior, verify parity tests for the affected tools still pass. If your
change introduces a valid behavioral difference from Python, update the parity test to
accept the new behavior and document the divergence in `docs/parity.md`.
## Compatibility Policy
Before making breaking changes, review `docs/compatibility-policy.md` for
stability guarantees, deprecation timelines, and what constitutes a breaking
change across the Rust API, MCP tools, input/output schemas, machine codes,
and profiles.
## Supply-Chain Auditing
The project uses `cargo-deny` (configured in `deny.toml`) for
dependency hygiene:
```sh
cargo deny check advisories bans licenses sources # license, advisory, ban, and source checks
```
Allowed licenses: MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception, Unlicense,
Unicode-DFS-2016, Unicode-3.0, Zlib. All are permissive and compatible with
the project's MIT license.
## Release Process
The canonical release process is documented in `docs/release.md`. Key points: GitHub CI verifies merge correctness but does not publish; the maintainer runs `scripts/release-check.sh` locally, publishes manually with `cargo publish --locked`, and creates the version tag after successful publication. See `docs/verification.md` for the full verification doctrine.