Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
192 lines (143 loc) · 6.66 KB

CONTRIBUTING.md

File metadata and controls

192 lines (143 loc) · 6.66 KB
Raw

Contributing to tracedecay

Thanks for your interest in contributing! This guide covers everything you need to get started.

Getting Started

git clone https://github.com/ScriptedAlchemy/tracedecay.git
cd tracedecay
cargo build
cargo nextest run --workspace --no-fail-fast

Requires Rust 1.70+ (edition 2021).

Project Structure

src/
  extraction/    Language-specific extractors (tree-sitter based)
  db/            Database layer (libSQL)
  graph/         Knowledge graph queries and traversal
  mcp/           MCP server (tools + handlers)
  context/       Context builder for AI-ready output
  resolution/    Cross-file reference resolution
  sync.rs        Incremental sync engine
  main.rs        CLI entry point
tests/           Integration tests (one per module/language)
tests/fixtures/  Sample source files for extraction tests
vendor/          Vendored tree-sitter grammars
docs/            Design docs and guides

Feature Flags

tracedecay supports 31 languages via feature flags:

Feature Languages
lite (default subset) Rust, Go, Java, Scala, TypeScript/JS, Python, C, C++, Kotlin, C#, Swift
medium +Dart, Pascal, PHP, Ruby, Bash, Protobuf, PowerShell, Nix, VB.NET
full (default) +Lua, Zig, Obj-C, Perl, Batch, Fortran, COBOL, MSBasic2, GW-BASIC, QBasic

Build with fewer languages for faster compile times during development:

cargo build --no-default-features --features lite
cargo nextest run --no-default-features --features lite

Making Changes

  1. Fork and branch from master for stable changes, beta for experimental features.
  2. Write tests. Every extraction change should have a corresponding test in tests/. Follow the existing pattern: create a fixture in tests/fixtures/ and assert on extracted nodes/edges.
  3. Run the full test suite before submitting: 
    cargo nextest run --workspace --no-fail-fast
    Cargo-launched test processes are isolated from your real ~/.tracedecay profile: .cargo/config.toml pins TRACEDECAY_DATA_DIR to target/test-profile/.tracedecay (enforced by tests/test_profile_isolation_test.rs). Tests that need a private profile should still override it per-test, e.g. via common::TraceDecayStorageEnvGuard or common::apply_tracedecay_home_env.
  4. Format your code with the standard Rust toolchain: 
    cargo fmt
cargo clippy --workspace --all-targets

Rebrand compatibility changes

For changes touching naming, legacy env vars, storage paths, generated agent config, plugin paths, or cleanup behavior, follow docs/REBRAND-COMPATIBILITY-POLICY.md. Update compatibility warnings, migration cleanup, and docs together.

Clippy policy

The CI Clippy job runs the same command contributors should run locally before pushing:

cargo clippy --workspace --all-targets

This check is blocking in CI: the workflow fails if cargo clippy --workspace --all-targets exits non-zero. The crate-level lint policy in src/lib.rs currently denies clippy::all, clippy::unwrap_used, and clippy::expect_used; new violations of those lints must be fixed or justified with the narrowest practical #[allow(...)] at the affected item. Do not add a broad allow or weaken the crate policy just to get CI green.

clippy::pedantic remains advisory. Pedantic diagnostics are emitted as warnings and should be addressed when they point to a real maintainability issue, but they do not block CI unless a future policy change promotes a specific lint to deny.

There is no separate Clippy baseline file today. If a policy change intentionally promotes additional advisory lints to blocking, update src/lib.rs, fix or narrowly allow the existing violations in the same change, and update this section so the contributor command and blocking/advisory split still match CI.

Adding a New Language Extractor

  1. Add a tree-sitter grammar dependency (or vendor it under vendor/).
  2. Create src/extraction/{lang}_extractor.rs implementing the Extractor trait.
  3. Register it in the LanguageRegistry with a feature flag (e.g., lang-{name}).
  4. Add a fixture file tests/fixtures/sample.{ext} and a test module tests/extraction_suite/{lang}.rs, then register it with a mod {lang}; declaration in tests/extraction_suite/main.rs.
  5. Update the feature flag tables in Cargo.toml and this document.

Validating Plugins and Skills

Changes under cursor-plugin/, codex-plugin/, or src/agents/ are covered by a layered validation system: vendored JSON-schema checks, per-host skill frontmatter contracts, cross-bundle sync/parity tests, and a CI schema-validation workflow. cursor-plugin/ is the source of truth — never hand-edit mirrored Codex skills. Before submitting, run:

cargo nextest run -E 'binary(=agent_suite)'

See docs/PLUGIN-VALIDATION.md for the full layer breakdown, schema refresh procedure, and how to add a skill or a new ecosystem bundle correctly.

Running Specific Tests

# All extractor tests for a specific language (module inside the
# consolidated extraction_suite binary)
cargo nextest run -E 'binary(=extraction_suite) and test(/^rust::/)'

# A single test by name
cargo nextest run test_find_stale_files

# Only sync-related tests
cargo nextest run sync

Commit Messages

Follow conventional commit style:

fix: handle UTF-16 encoded files in sync
feat: add Dart annotation extraction
refactor: simplify reference resolver lookup

Keep the first line under 72 characters. Add a body explaining why if the change isn't obvious.

Install the local commit-msg hook once per checkout:

scripts/install-git-hooks.sh

CI validates commit subjects with:

scripts/check-conventional-commits.sh origin/master..HEAD

Run the same command locally before pushing to lint every non-merge commit in a branch range. Merge commits are skipped to match CI behavior.

Pull Requests

  • Target master for bug fixes and stable features.
  • Target beta for experimental or breaking changes.
  • Keep PRs focused — one logical change per PR.
  • Include test coverage for new behavior.
  • Update CHANGELOG.md under an [Unreleased] section.

Reporting Issues

Open an issue at https://github.com/ScriptedAlchemy/tracedecay/issues with:

  • tracedecay version (tracedecay --version)
  • OS and architecture
  • Steps to reproduce
  • Expected vs. actual behavior

Code of Conduct

This project follows the Contributor Covenant. Be respectful and constructive.

License

By contributing, you agree that your contributions will be licensed under the MIT License.