pluk 0.3.4

Symbol lookup / search engine CLI

Pluk

Git-commit–aware symbol lookup & impact analysis engine

Pluk gives developers “go-to-definition”, “find-all-references”, and “blast-radius” impact queries across one or more Git repositories. Heavy lifting (indexing, querying, storage) runs in isolated Docker containers; a lightweight host CLI bootstraps and delegates commands.

---

Key Features

• symbol search (pluk search) and definition lookup (pluk define)
• Impact analysis (pluk impact) to trace downstream dependents via recursive CTEs & caching
• Commit-aware indexing: evolves symbol graph across Git history (pluk diff)
• Zero-friction install: pip install pluk + Docker & Compose
• Containerized backend: PostgreSQL for the graph, Redis for cache
• Single Python codebase: host shim (pluk.bootstrap) + container CLI (pluk.cli)

---

Quickstart

1. Install

   pip install pluk
   

   Ensure Docker & Docker Compose are installed and your user can run docker.

2. Bootstrap & index

   pluk init /path/to/your/repo
   

   Sets up containers and indexes the repo.

3. Run queries

   pluk search MyClass         # search definitions & refs
   pluk define my_function      # show definition location
   pluk impact computeFoo        # trace downstream dependents
   pluk diff abc123 def456        # symbol changes between commits
   

4. Manage services

   pluk start    # launch FastAPI server + worker
   pluk cleanup   # teardown Docker Compose stack
   

All commands run on the host; Pluk manages Docker Compose under ~/.pluk/docker-compose.yml by default.

---

Data Flow

Pluk’s host shim (pluk) writes a Compose file and delegates commands into the container CLI (plukd). Inside the container, plukd interacts with Postgres and Redis; results stream back to your terminal.

---

Architecture

[Host CLI: pluk] ── docker-compose ──▶ [Container: plukd]
                                    │
                                    ├─▶ Postgres (symbol graph)
                                    └─▶ Redis (cache)

• pluk (host shim)

  • Writes and manages docker-compose.yml under ~/.pluk/
  • Forwards user commands into the container via docker compose exec

• plukd (container CLI)

  • Implements init, search, define, impact, diff, start, cleanup
  • Parses repos, builds AST index, executes queries with SQL & Python

• Postgres stores commits, symbol definitions, and reference links

• Redis caches expensive recursive queries for sub-second responses

---

Development

# Clone & install in editable mode
git clone https://github.com/Jorstors/pluk.git
cd pluk
pip install -e .

• Project layout (src/pluk):

  • bootstrap.py — host shim entrypoint (pluk)
  • cli.py — container CLI (plukd)

• Entry points in pyproject.toml:

  [project.scripts]
  pluk  = "pluk.bootstrap:main"
  plukd = "pluk.cli:main"
  

---

Testing

• Unit tests for argument parsing and shim logic (pytest)
• Integration tests invoking pluk init on a sample repo

pytest tests/

Note: Docker daemon must be running locally.

---

🔖 Versioning

We use bumpver for semantic versioning:

bumpver patch   # 0.1.0 → 0.1.1
bumpver minor    # 0.1.1 → 0.2.0
bumpver major     # 0.2.0 → 1.0.0

---

📄 License

Distributed under the MIT License. See LICENSE for details.