Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (61 loc) · 3 KB

CLAUDE.md

File metadata and controls

76 lines (61 loc) · 3 KB
Raw

rpg-encoder

Rust workspace for building Repository Planning Graphs (RPGs) — semantic code understanding via MCP.

Build & Verify

cargo fmt --all                                    # format
cargo clippy --workspace --all-targets -- -D warnings  # lint
cargo test --workspace                             # test (640+ tests)
cargo build --release -p rpg-mcp                   # release binary

Before every commit: run fmt, clippy, and test. All three must pass. Do not skip or suppress warnings.

Git Workflow

Branch naming

  • fix/* — bug fixes
  • feat/* — new features
  • docs/* — documentation only
  • chore/* — tooling, deps, version bumps

Commits

Use conventional commits:

  • fix: bug fix
  • feat: new feature
  • chore: tooling, version bump, deps
  • docs: documentation
  • refactor: code restructure (no behavior change)
  • test: adding or fixing tests

Issue-first workflow

  1. Open a GitHub issue describing the problem or feature
  2. Create a branch from main (fix/issue-description or feat/issue-description)
  3. Make commits on the branch
  4. Open a PR referencing the issue (Closes #N or Ref #N)
  5. Merge via squash merge (gh pr merge --squash --delete-branch)
  6. Pull main locally after merge

Release process

  1. Bump version in root Cargo.toml ([workspace.package] version) AND npm/package.json
  2. Run cargo fmt && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace
  3. Commit: chore: bump version to X.Y.Z
  4. Tag: git tag vX.Y.Z
  5. Push: git push origin main && git push origin vX.Y.Z
  6. The release workflow auto-builds binaries, creates a GitHub release, and publishes to npm

Project Structure

crates/
  rpg-core/      # Graph data model, storage, schema, LCA
  rpg-parser/    # Tree-sitter entity extraction (Rust, Python, JS/TS, Go, Java, C/C++)
  rpg-encoder/   # Semantic lifting, grounding, dependency resolution
  rpg-nav/       # Search, explore, fetch, export (navigation layer)
  rpg-cli/       # CLI binary
  rpg-mcp/       # MCP server binary (stdio JSON-RPC)

Key files

  • crates/rpg-encoder/src/prompts/*.md — LLM prompt templates (included via include_str!)
  • crates/rpg-mcp/src/prompts/server_instructions.md — LIFTER PROTOCOL
  • crates/rpg-core/src/graph.rs — Core graph data model (Entity, RPGraph, EdgeKind)
  • crates/rpg-encoder/src/grounding.rs — Dependency resolution + artifact grounding

Architecture notes

  • All serialized maps use BTreeMap for deterministic JSON output
  • Edges are sorted by (source, target, kind) before serialization
  • lifting_coverage() excludes Module entities (they get features via aggregation)
  • The connected coding agent IS the LLM for lifting (no API key needed)
  • Edge kinds: Imports, Invokes, Inherits, Composes, Renders, ReadsState, WritesState, Dispatches, DataFlow, Contains

CI Checks

The GitHub Actions workflow runs: fmt --check, clippy -D warnings, test --workspace. All must pass for PRs.