Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (80 loc) · 2.91 KB

CONTRIBUTING.md

File metadata and controls

112 lines (80 loc) · 2.91 KB
Raw

Contributing to codeloom

Thank you for your interest in contributing to codeloom! This guide will help you get started.

Development Setup

# Clone the repository
git clone https://github.com/algodesigner/codeloom.git
cd codeloom

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests with coverage
pytest

# Run a specific test file
pytest tests/test_store.py

# Run with verbose output
pytest -v

# Run property-based tests
pytest tests/test_graph_properties.py -v

# Run stress tests (small only)
SKIP_STRESS=0 pytest tests/stress/ -v

# Run full stress suite (slow — includes 10k-file repo)
FULL_STRESS=1 SKIP_STRESS=0 pytest tests/stress/ -v

Code Style

We use Ruff for linting and formatting:

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

Key conventions:

  • Line length: 100 characters
  • Target Python: 3.10+
  • Import sorting: isort-compatible (handled by Ruff)

Project Structure

codeloom/
├── cli/          # Click-based CLI interface
├── core/         # Pipeline stages (detect, extract, build, cluster, analyze)
├── query/        # Hybrid search engine (vector + graph + keyword + RRF)
└── storage/      # SQLite + FAISS storage layer

Making Changes

  1. Fork the repository and create a feature branch from main.
  2. Write tests for any new functionality in tests/.
  3. Run the test suite to ensure nothing is broken.
  4. Follow the existing code style — Ruff will help enforce this.
  5. Keep commits focused — one logical change per commit.

Pull Request Guidelines

  • Keep PRs focused on a single change.
  • Include a clear description of what the PR does and why.
  • Ensure all tests pass before submitting.
  • Update documentation if you change public APIs or CLI commands.

Architecture Notes

The pipeline follows a linear flow:

detect → extract → build → embed → cluster → analyze → store
  • detect: Scans directories, classifies files by language.
  • extract: Tree-sitter AST extraction with regex fallback.
  • build: Assembles a NetworkX DiGraph with deduplication.
  • embed: Generates sentence-transformer embeddings locally.
  • cluster: Hierarchical Leiden community detection.
  • analyze: Structural analysis (god nodes, hubs, quality metrics).
  • store: SQLite + FTS5 + FAISS vector index, all in a single file.

Reporting Issues

  • Use GitHub Issues for bug reports and feature requests.
  • Include reproduction steps for bugs.
  • Mention your Python version and OS.

License

By contributing, you agree that your contributions will be licensed under the MIT License.