Metadata-Version: 2.4
Name: ci-test-gate
Version: 0.1.0
Summary: LLM-powered test selection for CI — run only the tests that matter
Author-email: Yunare Maia <yunare@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yunaremaia/ci-test-gate
Project-URL: Repository, https://github.com/yunaremaia/ci-test-gate
Project-URL: Issues, https://github.com/yunaremaia/ci-test-gate/issues
Project-URL: Changelog, https://github.com/yunaremaia/ci-test-gate/blob/main/CHANGELOG.md
Keywords: ci,testing,test-selection,llm,github-actions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: openai>=1.0; extra == "dev"
Dynamic: license-file

# ci-test-gate

[![CI](https://github.com/yunaremaia/ci-test-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/yunaremaia/ci-test-gate/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/yunaremaia/ci-test-gate/branch/main/graph/badge.svg)](https://codecov.io/gh/yunaremaia/ci-test-gate)

**LLM-powered test selection for CI — run only the tests that matter.**

Tired of waiting 30+ minutes for CI when your change touches one file? `ci-test-gate` analyzes your PR diff and recommends which tests to run, skip, or require.

```bash
pip install git+https://github.com/yunaremaia/ci-test-gate.git
ci-test-gate suggest --diff pr.diff --test-files tests.txt
```

### How it works

```
┌──────────────────────────────────────────────────┐
│                    GitHub PR                      │
│                     │                             │
│         git diff main...HEAD                     │
│                     │                             │
│                     ▼                             │
│  ┌────────────────────────────────────────────┐  │
│  │           ci-test-gate engine              │  │
│  │                                            │  │
│  │  1. Parse diff into structured changes     │  │
│  │  2. Build context (imports, functions)     │  │
│  │  3. Classify tests (required/recommended/  │  │
│  │     optional)                              │  │
│  │  4. Output recommendation (JSON/Markdown) │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘
```

### Why?

- **Save CI minutes** — skip irrelevant tests
- **Faster feedback** — required tests run first
- **Risk-aware** — conservative by default
- **Multi-language** — Python, JS/TS, Go, Rust

See [docs/LANGUAGES.md](docs/LANGUAGES.md) for language-specific test pattern documentation.

### Modes

- `suggest` — Comment on PR with recommendations
- `gate` — Block merge if required tests didn't run
- `local` — Run before push to catch issues early

---

## LLM Classification

`ci-test-gate` supports LLM-powered semantic classification in addition to the built-in heuristic engine.
When enabled, it sends the diff context to an OpenAI-compatible API and lets the model reason about which tests are most likely affected.

### Enabling LLM mode

Pass `--llm` to the `suggest` or `local` command:

```bash
ci-test-gate suggest --diff pr.diff --test-files tests.txt --llm
```

### Configuration

| CLI flag | Environment variable | Default | Description |
|---|---|---|---|
| `--llm` | — | off | Enable LLM classification |
| `--llm-api-key` | `OPENAI_API_KEY` | — | API key for the OpenAI-compatible endpoint |
| `--llm-model` | `CI_TEST_GATE_MODEL` | `gpt-4o-mini` | Model to use |
| — | `OPENAI_BASE_URL` | OpenAI production | Base URL (for local/alternative endpoints) |

CLI flags take precedence over environment variables.

### Example — using a custom model

```bash
export OPENAI_API_KEY="sk-..."
ci-test-gate suggest \
  --diff pr.diff \
  --test-files tests.txt \
  --llm \
  --llm-model gpt-4o \
  --output json
```

### Fallback behaviour

If no API key is configured, or if the LLM call fails for any reason (network error, rate limit, malformed response), `ci-test-gate` automatically falls back to the heuristic classifier so your CI pipeline is never blocked.

---

### Roadmap

- [x] LLM semantic classification (v0.2.0)
- [ ] Gate mode enforcement (v0.2.0)
- [ ] Dashboard with savings metrics (v0.4.0)

### License

MIT

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing guidelines, and how to add a new classifier.
