Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (123 loc) · 4.68 KB

CONTRIBUTING.md

File metadata and controls

181 lines (123 loc) · 4.68 KB
Raw

Contributing to krait

Thank you for your interest in contributing! This document covers everything you need to get started.

Table of Contents

Development Setup

Prerequisites

  • Rust 1.85 or later (rustup update stable)
  • A language server for testing (optional but recommended):
    • TypeScript: npm install -g @vtsls/language-server
    • Rust: rustup component add rust-analyzer
    • Go: go install golang.org/x/tools/gopls@latest

Build

git clone https://github.com/Codestz/krait
cd krait
cargo build

Release build

cargo build --release
./target/release/krait --help

Project Structure

src/
  main.rs           Entry point, CLI dispatch, watch loop
  lib.rs            Library root, public API
  cli.rs            Clap command definitions
  client.rs         CLI-to-daemon client, command_to_request()
  protocol.rs       Wire protocol types (Request / Response)
  daemon/           UDS server, lifecycle, request dispatch
  lsp/              LSP client, transport, multiplexer, install
  index/            SQLite symbol index, cache, file watcher
  commands/         Business logic per command
  output/           Output formatters (compact, json, human)
  detect/           Language detection, project root detection
  lang/             Language-specific helpers
tests/
  fixtures/         Minimal Rust projects for e2e tests
  e2e_phase1.rs     CLI smoke tests (no LSP required)
  e2e_phase2.rs     LSP integration tests (marked #[ignore])
  e2e_phase3.rs     Discovery command tests (marked #[ignore])
internal-docs/
  VISION.md         Project goals and philosophy
  ARCHITECTURE.md   Technical architecture details
  ROADMAP.md        Future roadmap

Running Tests

Unit tests (always pass, no external dependencies)

cargo test

This runs 299+ unit tests and basic CLI smoke tests. No language servers or external projects required.

LSP integration tests (optional)

The e2e tests in e2e_phase2.rs and e2e_phase3.rs use real LSP servers and are marked #[ignore] to keep CI fast. Run them locally with:

# Requires rust-analyzer
cargo test -- --ignored

These tests use fixture projects in tests/fixtures/ (included in the repository) — they do not depend on any external codebases.

Code Style

Clippy

All clippy lints must pass. The project uses strict settings (all = deny, pedantic = warn):

cargo clippy

Fix any warnings before submitting a PR. Clippy is enforced in CI.

Error handling

  • Use anyhow for errors in binary/daemon code
  • Use thiserror for library-level error types
  • No .unwrap() in library code — always propagate with ?

Functions

  • Keep functions under 50 lines; extract helpers if needed
  • Write #[cfg(test)] mod tests { ... } alongside every non-trivial module

Formatting

cargo fmt

Formatting is enforced in CI.

Submitting Changes

Small fixes and typos

Open a pull request directly.

New features or significant changes

  1. Open an issue first to discuss the approach
  2. Reference the issue in your PR
  3. Include tests for new behavior
  4. Update relevant docs if the architecture changes

Pull request checklist

  • cargo fmt — no formatting diff
  • cargo clippy — zero warnings
  • cargo test — all tests pass
  • New behavior has unit tests
  • PR description explains the motivation

Architecture Overview

Krait has three layers:

CLI (src/main.rs, src/cli.rs, src/client.rs) Parses arguments, connects to the daemon over a Unix socket, prints results. Stateless.

Daemon (src/daemon/) One process per project root. Manages LSP lifecycles, serves requests, maintains the symbol index. Started automatically on first use, shuts down after inactivity.

LSP layer (src/lsp/) The LspMultiplexer runs one language server process per language and dynamically attaches workspace folders via workspace/didChangeWorkspaceFolders. Responses are buffered out-of-order and matched by request ID.

For deeper context, read internal-docs/VISION.md and internal-docs/ARCHITECTURE.md.

Reporting Bugs

Use GitHub Issues. Include:

  • krait version (krait --version)
  • OS and architecture
  • Minimal reproduction steps
  • Output with RUST_LOG=debug krait <command> if the issue involves LSP communication

Security

See SECURITY.md for the vulnerability reporting process.