Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
108 lines (81 loc) · 3.07 KB

CONTRIBUTING.md

File metadata and controls

108 lines (81 loc) · 3.07 KB
Raw

Contributing to CodeWell

Thank you for your interest in contributing.

Getting Started

  1. Clone the repository

    git clone https://github.com/Fitz798/CodeWell.git
cd codewell

  2. Create a virtual environment

    python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.\.venv\Scripts\Activate.ps1  # Windows PowerShell

  3. Install in development mode

    pip install -e ".[dev]"

  4. Run tests

    pytest

Development Requirements

  • Python 3.10+
  • Hatchling for builds
  • SQLite3 (bundled with Python)

Code Quality

Before submitting a PR, ensure:

ruff check .                    # Lint
mypy src/codewell             # Type check
pytest                          # Tests

CI enforces all three gates on Python 3.10, 3.12, and 3.13.

Project Structure

src/codewell/          # Main package
  cli.py                 # CLI entrypoint (28 subcommands)
  context.py             # Context pack assembly + V2 retrieval logic
  indexer.py             # Workspace indexing
  store.py               # SQLite storage engine
  search.py              # FTS5 lexical search
  python_parser.py       # Python AST parser
  javascript_parser.py   # JS/TS regex parser
  models.py              # Shared data models
  schema.py              # SQLite schema migrations
  utils.py               # Shared utilities

tests/                   # Test suite (484 tests)
  test_parsers.py        # Parser unit tests (111 tests)
  test_store.py          # Storage unit tests (41 tests)
  test_context.py        # Context pack tests
  ...

docs/                    # Documentation
  V2_MASTER_PLAN.md      # V2 master plan
  V2_PROGRESS_*.md       # Detailed progress log
  ARCHITECTURE_V2.md     # Architecture overview

scripts/                 # Evaluation and utility scripts
  agent_eval_session.py  # Agent evaluation harness
  check_release.py       # Pre-release quality gate

Architecture Principles

  • Local-first: No required LLM API, embeddings, or hosted services
  • SQLite + static retrieval: Default baseline uses FTS5 search and graph expansion
  • Optional enhancers: LLM planners and embedding models are strictly optional plug-ins
  • Rule-based V2: Multi-goal decomposition is rules-driven, not LLM-dependent
  • Language support: Python via AST, JavaScript/TypeScript via regex parser

Evaluation

CodeWell uses a custom agent evaluation framework. See:

  • docs/AGENT_EVAL_SUMMARY.md — evaluation methodology
  • scripts/agent_eval_session.py — evaluation harness (prepare-run, run-batch, record-run)
  • scripts/agent_eval_repeated_run_summary.py — median ratio computation

New retrieval features should ideally include evaluation tasks that demonstrate value.

Submitting Changes

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Run python scripts/check_release.py for the full quality gate
  4. Submit a PR against main
  5. CI will verify on Python 3.10, 3.12, and 3.13

Questions?

Open an issue or start a discussion on the repository.