gerenuk 0.1.0__tar.gz

gerenuk-0.1.0/.claude/settings.json

@@ -0,0 +1,2 @@
+{
+}

gerenuk-0.1.0/.claude/skills/rust-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: rust-review
+context: fork
+description: Deep Rust code quality review. Auto-invoke when finishing a task, before marking work complete, when the user asks to review code, or when preparing a PR. Covers error handling, async correctness, duplicated logic, test quality, performance patterns, idiomatic Rust, docs-code alignment, and API design beyond what clippy catches.
+---
+
+# Deep Code Review for gerenuk
+
+Perform a thorough code quality review of the changes in this project. Go beyond what clippy and rustfmt catch. Focus on the areas below and report findings grouped by severity: 🔴 Must Fix, 🟡 Should Fix, 🟢 Suggestion.
+
+First, run `cargo fmt --all -- --check` and `cargo clippy --all-targets --all-features -- -D warnings` to confirm the automated checks pass. If they don't, fix those first before proceeding with the deep review.
+
+## 1. Error Handling Quality
+
+- `.unwrap()` outside tests is forbidden. Flag any instance.
+- Check that `.context("message")` is used when propagating errors from external crates with `?` — bare `?` loses context about what operation failed.
+- Flag `Result` return types where the function never actually returns `Err` (remove the wrapper — clippy catches this as `unnecessary_wraps` but double-check).
+- Flag `.map_err(|_| ...)` that silently discards error information.
+- Verify error types are specific enough — no `String` as error type, no `anyhow::Error` leaking into library-style modules.
+- Check that `thiserror` error variants have `#[from]` or manual `From` impls for their sources.
+
+## 2. Async / Tokio Correctness
+
+- Flag any `MutexGuard` or `RwLockGuard` held across an `.await` point — this can deadlock or prevent `Send` futures.
+- Flag blocking operations (std::fs, std::process::Command, heavy computation) running directly in async context without `spawn_blocking`.
+- Check that spawned tasks (`tokio::spawn`) have their `JoinHandle` either awaited or explicitly dropped with a comment explaining why.
+- Verify `tokio::select!` branches handle cancellation correctly (partially completed work).
+- Check for unbounded channels or queues that could cause memory issues under load.
+
+## 3. Duplicated Logic
+
+- Search for functions or code blocks that do substantially the same thing with minor variations. Flag them and suggest extraction into a shared function, trait, or generic.
+- Pay special attention to:
+  - LSP message construction patterns (likely repeated across commands)
+  - Error handling boilerplate that could be a helper
+  - Serialization/deserialization patterns
+  - Similar match arms across different functions
+- Suggest concrete refactoring: which function to extract, what parameters it should take.
+
+## 4. Test Quality
+
+- **Tests that don't assert**: Flag any test that just calls code without asserting on the result. Running without panicking is not a test.
+- **Tests that assert too little**: `assert!(result.is_ok())` without checking the value inside is weak. Suggest asserting on the actual content.
+- **Overly verbose tests**: Tests with excessive setup that obscure what's actually being tested. Suggest extracting test helpers or fixtures.
+- **Missing edge cases**: For each public function, check if tests cover: empty input, error paths, boundary conditions.
+- **Test naming**: Test names should describe the behavior being tested, not the implementation (`test_returns_error_on_missing_file` not `test_function_xyz`).
+- **Integration vs unit**: Verify that unit tests (in `#[cfg(test)] mod tests`) test internal logic, while `tests/integration/` tests exercise the public CLI interface.
+- Suggest adding `proptest` for any function that transforms data (roundtrip properties).
+
+## 5. Performance Patterns
+
+- Flag unnecessary `.clone()` — suggest borrowing or restructuring ownership.
+- Flag `.collect::<Vec<_>>()` immediately followed by `.iter()` — the intermediate collection is usually unnecessary.
+- Prefer `&str` over `String`, `&[T]` over `Vec<T>`, `&Path` over `PathBuf` in function parameters when ownership isn't needed.
+- Flag large structs being passed by value instead of reference.
+- Check for `Arc::clone(&x)` vs `x.clone()` — the former is required by our lint config for clarity.
+- In async code, flag futures that capture large amounts of data across await points.
+
+## 6. Idiomatic Rust
+
+- Prefer iterator chains over manual `for` loops with `push`.
+- Use `if let` / `let else` instead of `match` with a single interesting arm and a wildcard.
+- Suggest `impl From<X> for Y` instead of standalone conversion functions.
+- Suggest `Display` implementations instead of `to_string()` methods.
+- Flag `&String`, `&Vec<T>`, `&Box<T>` in function signatures — use `&str`, `&[T]`, `&T` instead.
+- Check doc comments on all public types and functions.
+
+## 7. Documentation ↔ Code Alignment
+
+- **Check that `docs/src/how-it-works.md` still matches the actual architecture.** In particular:
+  - Do the diagrams (daemon layers, request lifecycle, client pool flow) reflect the current code paths in `src/daemon/` and `src/lsp/`?
+  - Are the RPC method names listed in the "Available RPC methods" table still accurate? Cross-check against the actual enum/dispatch in the daemon server code.
+  - Do the described concurrency patterns (single-pipe, batch processing, sequential LSP requests) still hold?
+  - Are timeouts, retry counts, and backoff intervals mentioned in prose consistent with the constants in the code?
+- **Check that `docs/src/commands/*.md` describe the current CLI interface.** Compare the documented flags and subcommands against the `clap` definitions in `src/cli/`.
+- **Check that `docs/src/performance.md` benchmarks and claims are not contradicted by recent changes.**
+- Flag any mismatch as 🔴 Must Fix — stale docs are worse than no docs.
+
+## 8. API and Module Design
+
+- Is `main.rs` thin? It should just parse args and call into library code.
+- Are module boundaries clean? Each module should have a clear responsibility.
+- Check for any `pub` items that don't need to be public.
+- Flag circular dependencies between modules.
+
+## Output Format
+
+Group all findings by severity, then by area. For each finding:
+- State **what** the issue is and **where** (file:line or function name)
+- Explain **why** it matters
+- Suggest a **concrete fix** (not just "improve this")
+
+End with a summary: X must-fix, Y should-fix, Z suggestions.
+
+$ARGUMENTS

gerenuk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,38 @@
+version: 2
+updates:
+  # Rust (Cargo) dependencies
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "rust"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"
+
+  # Python dependencies. `ty-find` is a runtime dependency in pyproject.toml,
+  # and it is the project gerenuk drives, so a new release matters here.
+  # Weekly is enough — there is no lockfile at the root to keep in step.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"

gerenuk-0.1.0/.github/workflows/audit.yml

@@ -0,0 +1,29 @@
+name: "Cargo Audit"
+
+on:
+  push:
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+  pull_request:
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  audit:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Run cargo-audit
+        uses: actions-rust-lang/audit@v1

gerenuk-0.1.0/.github/workflows/cargo-deny.yml

@@ -0,0 +1,35 @@
+name: "Cargo Deny"
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "deny.toml"
+  pull_request:
+    paths:
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "deny.toml"
+
+permissions:
+  contents: read
+
+jobs:
+  deny:
+    name: ${{ matrix.check }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        check: [bans, licenses, sources]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Run cargo-deny (${{ matrix.check }})
+        uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          command: check ${{ matrix.check }}
+          arguments: --all-features

gerenuk-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+  schedule:
+    - cron: "0 6 * * 1" # Weekly on Monday at 06:00 UTC
+
+permissions:
+  security-events: write
+  packages: read
+  actions: read
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze Rust
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: rust
+          build-mode: none
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:rust"

gerenuk-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Deploy docs
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "src/**"  # rebuild when CLI changes (help text may change)
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Lint mermaid diagrams
+        run: |
+          cd docs && npm ci --silent
+          cd .. && node docs/lint-mermaid.mjs
+
+      - name: Install mdBook and preprocessors
+        run: |
+          mkdir -p bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.5.2/mdbook-v0.5.2-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+          curl -sSL https://github.com/badboy/mdbook-mermaid/releases/download/v0.17.0/mdbook-mermaid-v0.17.0-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+          echo "$PWD/bin" >> $GITHUB_PATH
+
+      - name: Sync docs version badge with Cargo.toml
+        run: bash docs/gen-version.sh
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Generate llms.txt
+        run: bash docs/generate-llms-txt.sh
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/book/html
+
+      - uses: actions/deploy-pages@v5
+        id: deployment

gerenuk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --strip
+          manylinux: 2_28
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: target/wheels/*.whl
+
+  build-sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install maturin
+        run: pip install maturin
+
+      - name: Build sdist
+        run: maturin sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: target/wheels/*.tar.gz
+
+  create-release:
+    name: Create GitHub Release
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+
+      - name: Flatten artifacts
+        run: |
+          mkdir -p wheels
+          find dist -name '*.whl' -exec cp {} wheels/ \;
+          find dist -name '*.tar.gz' -exec cp {} wheels/ \;
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: wheels/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build-wheels, build-sdist, create-release]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') && github.event_name == 'push'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gerenuk
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+
+      - name: Flatten artifacts
+        run: |
+          mkdir -p wheels
+          find dist -name '*.whl' -exec cp {} wheels/ \;
+          find dist -name '*.tar.gz' -exec cp {} wheels/ \;
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: wheels/
+          skip-existing: true

gerenuk-0.1.0/.github/workflows/review.yml

@@ -0,0 +1,84 @@
+name: Code Review
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "docs/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "clippy.toml"
+      - "rustfmt.toml"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "docs/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "clippy.toml"
+      - "rustfmt.toml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  fmt:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # The suite stubs `tyf` via GERENUK_TYF, so neither ty-find nor ty is
+      # needed here. See tests/common/mod.rs.
+      - run: cargo test --all-features
+
+  fixture:
+    name: Fixture package tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Run the fixture package's pytest suite
+        working-directory: tests/fixtures/sample_pkg
+        run: uv run --with pytest --with hatchling python -m pytest -q
+
+  docs:
+    name: Docs are in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Version badge matches Cargo.toml
+        run: bash docs/gen-version.sh --check
+      - name: Shared snippets are injected
+        run: bash docs/inject-shared.sh --check

gerenuk-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# Rust
+/target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+cf/
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Claude Code
+.claude/worktrees/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# maturin / PyO3
+*.so
+*.pyd
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+
+# Fixture package virtualenvs
+tests/fixtures/**/.venv/
+
+# mdBook build output (docs/book.toml build-dir)
+docs/book/

gerenuk-0.1.0/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Project Overview
+
+`gerenuk` is a CLI that audits Python symbols by driving `tyf` (from
+[ty-find](https://github.com/mojzis/ty-find)). It is a hybrid Rust/Python
+project: a Rust binary packaged as a Python wheel via maturin.
+
+It reports two things per file: symbols nothing references, and symbols only
+tests reach. A second command, `changed-symbols`, maps the working tree's git
+diff to the Python symbols it changed — the first stage of impact-based pytest
+selection, and the one part of the crate that needs `git` rather than `tyf`.
+Architecture details: `docs/dev/ARCHITECTURE.md`.
+
+## Prerequisites
+
+- **`tyf`** on `PATH` for `audit`/`doctor` (`uv add --dev ty ty-find`). Not
+  needed for the test suite — the tests stub it.
+- **`git`** on `PATH` for `changed-symbols` and its tests, or `GERENUK_GIT`
+  pointing at it. That is all it needs.
+- **`uv`** for the fixture package's pytest suite.
+
+## Common Commands
+
+```sh
+# Pre-commit checks (always run before committing)
+cargo fmt --all -- --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test --all-features
+
+make review        # the above, plus the fixture pytest suite, audit and deny
+make review-quick  # skip the network checks
+make test-fixture  # just the Python fixture package's pytest suite
+make docs          # build the mdBook site + llms.txt
+```
+
+If formatting fails, fix it with `cargo fmt --all` and re-run.
+
+## Development Workflow
+
+All features and bug fixes follow TDD (red-green-refactor). No implementation
+code without a failing test first. Bug fixes must include a regression test that
+fails without the fix.
+
+## Test Changes Require Deliberation
+
+When a test fails during implementation:
+
+1. **Stop and diagnose.** Understand WHY it fails before changing anything. Is
+   the test wrong, or is the implementation wrong?
+2. **Default assumption: the test is right.** Fix the implementation first.
+3. **If the test genuinely needs updating** (requirements changed, API evolved),
+   explain what changed and why the old assertion is no longer correct before
+   modifying it.
+4. **Never weaken an assertion just to make it pass.** Making a test more
+   permissive without understanding the failure is not a fix.
+5. **If uncertain, ask.** A 2-line question is cheaper than a silent wrong
+   decision.
+
+## Key Invariants
+
+- **`tyf::Runner::run` and `git::Git::run` are the only functions that spawn a
+  process.** Everything downstream takes parsed data. Keep it that way — it is
+  what makes `analyze`, `changed` and `report` testable with no `tyf`, no `ty`,
+  no `git` and no Python. Adding a third seam needs a very good reason.
+- **`changed-symbols` must never construct a `tyf::Runner`.** Discovery happens
+  inside the `Audit` and `Doctor` arms of `Cli::run`, not before the match. A
+  test in `tests/changed_symbols.rs` runs with an empty `PATH` to enforce this.
+- **`changed::Sources` is the seam the classification is tested through.** New
+  inputs go behind that trait, not into `changed::analyze` directly, or the unit
+  tests stop being able to run without a repository.
+- **`main.rs` stays thin.** Argument parsing, tracing setup, exit-code mapping.
+  Command bodies belong in `cli.rs`.
+- **Exit codes are part of the contract.** `0` clean, `1` findings, `2` the run
+  could not complete. Do not collapse `1` and `2`. `changed-symbols` is an
+  inventory rather than a verdict, so it returns `0` or `2` and never `1`.
+- **The fixture package and the canned payloads must agree.** Changing the call
+  graph in `tests/fixtures/sample_pkg` means updating both its pytest suite and
+  the stub payloads in `tests/audit.rs`.
+- **`clippy::unwrap_used` / `expect_used` are denied outside tests.** Use
+  `anyhow::Context` on every `?` that crosses an I/O or parsing boundary.
+- **A symbol's `added`/`modified`/`deleted` verdict comes from whether it exists
+  on each side of the diff, not from which side the hunk touched.** Deleting
+  lines from a function that still exists is a modification; its callers were
+  never orphaned. Renames are deliberately *not* paired — a moved module is a
+  new module, so the old path's symbols are `deleted` and the new path's
+  `added`.
+- **Do not trust `tyf`'s production/test split.** Its heuristic reads the whole
+  absolute path, so a project under a `tests/` directory has every reference
+  filed as a test. `analyze::split_refs` re-derives the buckets from paths
+  relative to the workspace root, and drops the symbol's own definition. The
+  stub payloads in `tests/audit.rs` reproduce both quirks — keep them that way.
+
+## Docs
+
+The mdBook site under `docs/` deploys to GitHub Pages on push to `main`
+(`.github/workflows/docs.yml`), along with `llms.txt` and `llms-full.txt`.
+
+- Shared prose lives in `docs/shared/` and is injected into `README.md` and
+  `docs/src/setup.md` by `docs/inject-shared.sh`. Edit the shared file, then run
+  the script — never edit between the `<!-- BEGIN SHARED:... -->` markers.
+- `docs/gen-version.sh` syncs the docs version badge with `Cargo.toml`.
+- Adding a page means adding it to `docs/src/SUMMARY.md`; the `llms.txt`
+  generator reads that file.