CodeYinkx

Secure, free-to-use, open-source-core automated code review for GitHub pull requests. Static analysis first (Ruff + Bandit), an optional and provider-independent AI pass second, and safe inline review comments — never an approval, a merge, or a write.

• Runs with no paid credentials: AI is off by default and the whole product runs end-to-end against a deterministic mock GitHub client.
• Treats every reviewed repository as hostile input: code is never executed and a repository's own tool configuration is never trusted.
• Enforces limits server-side, deduplicates webhooks by delivery id and by commit, and publishes only findings validated against the diff.

---

Quick start (no credentials required)

python -m venv .venv
. .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

cp .env.example .env           # GITHUB_MODE=mock is the default
python -m app.cli initdb
python -m app.cli seed         # demo user + one simulated repository

# terminal 1 — web
python -m app.cli web          # http://127.0.0.1:8000

# terminal 2 — worker
python -m app.cli worker

# terminal 3 — prove the pipeline end to end
curl -s localhost:8000/readyz

Open http://127.0.0.1:8000, sign in (mock mode signs in a local dev user), and the dashboard shows repository and review state. The banner makes it explicit that GitHub is simulated.

Run the checks

pytest -q                      # 178 tests, offline
ruff check . && ruff format --check .
bandit -q -r app
alembic upgrade head           # then: alembic downgrade base

alembic upgrade head # then: alembic downgrade base

## What it does

1. A signed GitHub webhook arrives for `pull_request` (`opened`,
   `reopened`, `synchronize`).
2. The delivery is recorded (deduplicated) and a **durable** review job is
   enqueued, keyed by `repository#pr@commit`, so a repeated webhook cannot
   create a second review.
3. The worker claims the job with an atomic, leased update, fetches the changed
   files, and runs the static analyzers on bounded input in a private workspace.
4. Findings are normalized, deduplicated by a stable fingerprint, and mapped to
   changed lines. Anything unmappable is reported in the summary rather than
   attached to an invented line.
5. If AI is enabled **and** the repository opted in, a bounded, redacted excerpt
   is sent to an OpenAI-compatible endpoint; its output is schema-validated and
   any failure degrades to static-only results.
6. A single `COMMENT` review is submitted, with previously published findings
   suppressed by fingerprint.

## Production

The demo path above never contacts GitHub. A real deployment needs a PostgreSQL
database, a long-running worker and a GitHub App:

1. Set `APP_ENV=production` and the values from
   [`.env.production.example`](.env.production.example).
2. Run `python -m alembic upgrade head`.
3. Run the web process and `python -m app.worker` separately.
4. Install the App at `/github/install` and sign in.

The application **fails closed** in production: mock mode, SQLite, the
development `SECRET_KEY` and `AUTO_INIT_DB=true` all stop startup. `/readyz`
reports database, schema and worker liveness. Full instructions and the honest
cost/free-tier table are in [docs/deployment.md](docs/deployment.md).

Tenancy is enforced from GitHub's own installation grants: a signed-in user sees
only installations GitHub confirmed for them, and another tenant's review,
finding or repository settings return `404`.

## Documentation

| Document | Contents |
| --- | --- |
| [docs/architecture.md](docs/architecture.md) | Modules, data model and request lifecycle |
| [docs/github-app.md](docs/github-app.md) | Creating and configuring the GitHub App |
| [docs/deployment.md](docs/deployment.md) | Hosting, PostgreSQL, web + worker, backups |
| [docs/vercel.md](docs/vercel.md) | Vercel + Supabase deployment with on-demand review processing |
| [docs/development.md](docs/development.md) | Local setup, tests, migrations |
| [docs/api.md](docs/api.md) | HTTP routes and JSON shapes |
| [docs/limitations.md](docs/limitations.md) | Supported languages and honest gaps |
| [SECURITY.md](SECURITY.md) | Threat model and responsible disclosure |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow |

## Open-source core vs hosted service

Everything in this repository is the **open-source core** (MIT): the analyzer
pipeline, GitHub App integration, queue, quota accounting and dashboard. A
hosted service, if one is operated, adds nothing proprietary to the review
engine — it only runs this code against real installations. No secrets,
deployment data or private configuration belong in this repository.

## Status

This is an MVP with a production deployment path. Check
[docs/limitations.md](docs/limitations.md) before relying on it: Python is the
only fully supported language today, JavaScript/TypeScript support is not
implemented, and Semgrep is disabled in this build.

It is **not** claimed to be production-ready until a real GitHub App has
reviewed a real pull request end to end against PostgreSQL with the worker
running. Everything verified offline is listed in the limitations document.