Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (40 loc) · 6.45 KB

CONTRIBUTING.md

File metadata and controls

59 lines (40 loc) · 6.45 KB
Raw

Contributing to CALM

CALM (Coding Agent Liveness Map) is early and solo-maintained right now — which means a single contribution can actually matter. This file is deliberately biased toward non-code ways to help first, because a healthy project needs more than pull requests.

You don't have to write code to contribute

  • Proofread the just-translated docs. docs/comparison.md and docs/mcp-client-setup.md were Vietnamese-only for a while and have now been translated to English (matching the main README and docs/architecture.md) — a native-English pass to catch anything a machine-assisted translation got stiff or unclear is still valuable.
  • Try CALM on a codebase in a Tier-0.5 language — 7 are on by default (C, C++, C#, Ruby, PHP, Shell, R), 11 more are opt-in behind one Cargo feature flag each (Kotlin, Swift, Scala, Dart, Lua, Elixir, Haskell, OCaml, Zig, PowerShell, Groovy) — and report where the regex/line-scan symbol extraction (or, once a language has a SCIP provider wired, the cross-reference resolution) gives a wrong or missing answer. benchmarks/resolution/ tracks known gaps (e.g. Dart parses symbols but produces zero call edges — a tree-sitter grammar limitation, not a bug) — new reports directly inform what gets prioritized next.
  • Write up your own workflow. A blog post or short thread showing CALM catching something before it caused a breakage is worth more than most code contributions, and we'll link to it from the README.
  • Add yourself to "Who's using CALM." Even a one-line entry ("we use it to review agent-generated PRs before merge") helps the next person trust the project. (ADOPTERS.md doesn't exist yet — open a PR creating it if you're the first!)
  • Answer questions in Issues/Discussions. Solo maintainer plus a growing user base is exactly the gap where a knowledgeable early user helps the most.

Ways to help with code

Roadmap items currently open, roughly in priority order:

  1. Hook adapters for other MCP hosts. calm init --hooks[=nudge|enforce] now scaffolds the PreToolUse/PostToolUse deny-hook wiring generically (backed by calm-core::hooks/hooks_check), but it only targets Claude Code's hook schema so far. VS Code/GitHub Copilot uses the same PreToolUse / permissionDecision: deny shape, so that port should be close to a direct translation. Cursor (beforeMCPExecution) and Windsurf (Cascade Hooks) use different shapes and need their own adapters.
  2. Resolver accuracy. False positives/negatives in coreness/is_hub classification, edge cases in the SCIP-overlay caching key. Also useful: getting more of the optional SCIP cross-reference providers (Go, Java, C#, PHP, C, Ruby — see install_hint in repo_overview's health_summary) easier to install, since call-graph precision for those languages is capped without one installed.
  3. New Tier-0.5 → Tier-0 promotions. SQL and Dart both already ship (SQL has its own standalone sqlparser-based indexer — real grammar, not regex — but deliberately stops short of a call graph, since "calls" isn't a coherent concept across SQL dialects; Dart is Tier-0.5 with the known zero-call-edge grammar limit noted above) — the next candidates are whichever Tier-0.5 language your own report from the "try CALM on a Tier-0.5 language" bullet above turns up as highest-friction.
  4. A sandboxed, multi-language execution broker for verification. verify_change runs one check (cargo check, unsandboxed beyond a wall-clock timeout and digest binding) — see KNOWN_LIMITATIONS.md's "Verification is single-language..." entry. Extending to go test/tsc --noEmit/pytest needs a shared network/filesystem/env execution-policy abstraction built first, not each language bolted directly onto a bare subprocess call.
  5. Change-kind-aware risk classification. compute_touch_risk sees caller-count/hub-status, a path-based risk_rules floor, and (since 0.6.0) escalates to "high" when a touched symbol's own signature text actually changes — but still can't tell a comment tweak from a body-only change from an auth-check removal that leaves the signature alone. Needs the diff content turned into a fuller classified axis and folded into the risk model. See KNOWN_LIMITATIONS.md.
  6. Multi-file change-set / transaction. Today every edit_lines/edit_symbol/format_files call is its own independent, file-scoped EditTransaction. The 0.6.0 batch_status tool reports one aggregate view (counts by state, which are still missing, whether any failed) across a caller-supplied list of tx_ids, but doesn't group transactions server-side, gate anything, or add rollback — the atomicity/rollback gap is unchanged. See KNOWN_LIMITATIONS.md.

KNOWN_LIMITATIONS.md has the full list (including smaller items not listed here) with the reasoning for why each is deliberately deferred rather than half-built.

Please open a GitHub Issue before starting on anything larger than a small fix, so effort doesn't collide with what's already in progress.

Development setup

git clone https://github.com/Eilodon/CALM.git
cd CALM
cargo build --release   # build.rs fetches + checksum-verifies the embedding model from Hugging Face Hub once, then vendors it into the binary — no Git LFS involved
cargo test --workspace  # embeddings is on by default, no extra --features flag needed

Before opening a PR

Run scripts/ci-local.sh — it reproduces every blocking CI gate in one command and reports all failures at once, instead of finding them one push at a time:

  • scripts/ci-local.sh — default: fmt + all clippy feature-sets + doc-truth + cargo test --workspace (fast, offline)
  • scripts/ci-local.sh --lint — lint + doc checks only (fastest pre-push gate)
  • scripts/ci-local.sh --full — everything CI runs, including the feature-matrix tests, fitness-check, and crash-injection

The individual gates it wraps, if you'd rather run them by hand:

  • cargo fmt and cargo clippy clean
  • cargo test --workspace passes
  • calm fitness-check --project-root . passes against this repo's own thresholds — CALM reviewing itself is part of the point
  • Commit messages explain why, not just what — the git-co-change mining feature literally mines this history later

Code of conduct

Be the kind of contributor you'd want reviewing your own PR. (A formal CODE_OF_CONDUCT.md is on the list — flag it if you'd like to help draft one.)

License

By contributing, you agree your contribution is licensed under the project's MIT License.