pluk 0.3.1

Symbol lookup / search engine CLI

Pluk

Pluk is a git-commit–aware, backend-first symbol lookup and cross-reference engine with impact analysis. It helps developers explore and refactor large codebases by indexing symbol definitions and usages across one or more Git repositories.

Designed for clarity, speed, and developer ergonomics, Pluk runs as a simple CLI tool on the host, while all heavy computation (indexing, querying, storage) runs in isolated Docker containers.

Features

• Symbol search and definition lookup
• Git commit–aware cross-reference indexing
• Impact analysis of symbol usage across history
• Fully containerized backend (Postgres + Redis)
• Pip-installable host CLI
• Single unified Python codebase for host shim and CLI core

Installation

pip install pluk

Ensure Docker and Docker Compose are installed and running on your machine.

Usage

# Initialize and index a repository
pluk init ~/myrepo

# Search for a symbol
pluk search MyClass

# Show where a symbol is defined
pluk define my_function

# Show usage/impact of a symbol
pluk impact my_function

# Show changes to a symbol across commits
pluk diff abc123 def456 --symbol SomeClass

All commands are executed from the host. Pluk automatically starts the necessary backend services in Docker under the hood.

---

Data Flow

Pluk uses the host shim (pluk) to forward commands into a running container where the core CLI (plukd) executes. The plukd CLI interacts with Postgres and Redis over Docker’s internal network. Output is streamed back to the host terminal.

---

Architecture

• pluk (host shim): Ensures the container stack is up and forwards CLI calls via docker compose exec.
• plukd (real CLI): Executes commands inside the container using the indexed symbol graph.
• Postgres: Stores the symbol graph, commits, and metadata.
• Redis: Caches results of expensive queries like impact analysis.

Development

Project structure:

src/pluk/
├── bootstrap.py     # Host shim
├── cli.py           # Container CLI logic

Entry points (in pyproject.toml):

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

Build and run:

pip install -e .
pluk init .

Tests

• Unit tests for CLI and shim logic
• Integration test: pluk init on toy repo
• Requires Docker daemon running locally

License

MIT License