Skip to content

Latest commit

 

History

History
227 lines (188 loc) · 9.98 KB

contributing.md

File metadata and controls

227 lines (188 loc) · 9.98 KB

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:

rustc --version
python --version
cargo --version

Building

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

cargo fmt --all -- --check     # formatting gate (CI-equivalent)
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features -- --skip parity --test-threads=4  # CI-equivalent test run
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:

    cargo test --locked tool_registration_tables_are_in_sync -- --nocapture
  4. Regenerate docs from the registry:

    cargo run --locked --features dev-tools --bin generate-docs

    This updates the profile reference block in architecture/mcp-server.md, the Generated Registry Facts block in architecture/overview.md, and generated/tool-cards.md. README.md and docs/ are 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).

cargo test --test lib parity

The Rust catalog contains 86 tools; the Python reference defines 67. The parity suite lists 39 accepted test cases across categories C1-C6, represented by 40 ignored test instances. They cover shell tokenization, prompt inspection, Unicode policy, output shape, tool ordering, and error handling. These are documented differences, not current merge-gate failures. See docs/parity.md for details.

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:

cargo deny check advisories bans licenses sources  # license, advisory, ban, and source checks

Allowed licenses (deny.toml): MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception, Unlicense, Unicode-DFS-2016, Unicode-3.0, Zlib, ISC, BSD-3-Clause, CDLA-Permissive-2.0. The last three cover the TLS stack behind in-process self-update (rustls/ring/webpki-roots): all OSI-approved or standard trust-root-data licenses. 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.