Metadata-Version: 2.4
Name: release-readiness-core
Version: 0.4.0
Summary: Project-agnostic release readiness engine and adapters
Project-URL: Homepage, https://github.com/psuthar/release-readiness-core
Project-URL: Repository, https://github.com/psuthar/release-readiness-core
Project-URL: Changelog, https://github.com/psuthar/release-readiness-core/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/psuthar/release-readiness-core/issues
Author-email: Paresh Suthar <paresh@suthar.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

## release-readiness-core

Project-agnostic deterministic release-readiness engine and adapters.

### Package layout

| Path | Role |
|------|------|
| `release_readiness_core.engine` | Core validation merge types and deterministic summary |
| `release_readiness_core.pr_gate` | Generic N-input PR gate combiner |
| `release_readiness_core.readiness_engine` | Full artifact-based PASS/WARN/BLOCK evaluation |
| `release_readiness_core.cli` | CLI entries `release-readiness` (validation summary) and `release-readiness-evaluate` (YAML + artifacts) |
| `release_readiness_core.readiness_io` | JSON/YAML/git helpers for evaluate |
| `release_readiness_core.adapters` | Optional helpers (Playwright → schema, GitHub check payloads) |

### Quickstart

The fastest path (PyPI — no git access to this repo required):

```bash
pip install "release-readiness-core==0.3.4"
release-readiness-init my-project
```

Pin the version you want (see [PyPI](https://pypi.org/project/release-readiness-core/)). To install a specific commit instead, use a [git SHA install](#install-from-git-sha-pinned) below.

Or run the engine directly against an inline JSON list:

```bash
uv sync
uv run release-readiness --input-json '[{"key":"go-test","status":"PASS"}]'
```

Evaluate from a YAML config and optional JSON artifacts (writes `report.json`, `report.md`, and `artifacts/release-readiness.json` under the repo root):

```bash
uv run release-readiness-evaluate --repo-root . --config path/to/config.yaml \
  --empty-diff --output-dir artifacts/release-readiness
```

Adapter CLIs:

```bash
# Playwright JSON reporter -> readiness e2e shape
uv run playwright-to-readiness --input playwright-results.json --output e2e_results.json \
  --validation-map ops/release-readiness/validation_map.yaml

# JUnit XML (Cypress / Jest / pytest / Mocha / etc.) -> readiness e2e shape
uv run junit-to-readiness --input test-results.xml --output e2e_results.json \
  --validation-map ops/release-readiness/validation_map.yaml

# LCOV info -> readiness coverage shape
uv run lcov-to-readiness --input coverage/lcov.info --output coverage.json \
  --baseline-percent 85

# PR-risk semantic combiner (consumes existing pr-risk.json)
uv run pr-risk-semantic --pr-risk-json artifacts/pr-risk.json --generator-outcome success
```

`--validation-map` is optional on Playwright and JUnit; without it the converter emits an empty `validations` object (counts and failures still reported). For Playwright, override default spec extensions with `--spec-extensions ts,js,mjs,e2e`.

The N-input PR gate combiner lives in `release_readiness_core.pr_gate` (`combine_gate_inputs`).

### Install from PyPI (version-pinned)

```bash
pip install "release-readiness-core==0.3.4"
```

### Install from Git (SHA-pinned)

```bash
pip install "git+https://github.com/psuthar/release-readiness-core.git@<sha>"
```

Use this when you need an unreleased commit or a fork. Release policy and versioning: [`RELEASE.md`](RELEASE.md).

### Development

```bash
uv run pytest
uv build
```

### Configuring PR Risk for your project

`release-readiness-pr-risk` ships a generic, language-agnostic baseline by default — domains classify everything to `other`, only generic gates (CI fetch depth, PR review summary, workflow / config validation, add tests / evidence, intent alignment, scattered review plan, test proximity, hotspot regression) fire. To make it project-specific (auth E2E gate when `src/auth/` changes, migration validation when SQL files change, etc.), author a `pr-risk-config.yaml`:

- Walkthrough: [`docs/how-to/7-configure-pr-risk.md`](docs/how-to/7-configure-pr-risk.md)
- Predicate vocabulary + detector template reference: [`docs/reference/pr-risk-config.md`](docs/reference/pr-risk-config.md)
- Examples: [`examples/pr-risk/python-service.yaml`](examples/pr-risk/python-service.yaml), [`examples/pr-risk/node-service.yaml`](examples/pr-risk/node-service.yaml)
- Schema: [`docs/contracts/pr-risk-config-v1.schema.json`](docs/contracts/pr-risk-config-v1.schema.json)

`release-readiness-init` writes a commented starter at `ops/release-readiness/pr-risk-config.yaml`; `release-readiness-doctor --pr-risk-config <path>` validates it (typos, malformed predicates, references to undeclared domains, unknown evidence templates).

### How-to guides

- Quickstart — adopt the package in a new project: `docs/how-to/0-quickstart.md`
- Map evidence — wire CI artifacts to validation keys: `docs/how-to/1-map-evidence.md`
- Tune scoring — penalties, thresholds, remediation: `docs/how-to/2-tune-scoring.md`
- CI integration — GitHub Checks and the generic adapter pattern: `docs/how-to/3-ci-integration.md`
- Multi-job CI — split smoke / e2e / coverage across jobs: `docs/how-to/4-multi-job-ci.md`
- Branch protection — make the readiness check required: `docs/how-to/5-branch-protection.md`
- Migrating from an existing gate: `docs/how-to/6-migrate-from-existing-gate.md`
- Configure PR Risk for your project: `docs/how-to/7-configure-pr-risk.md`
- Recipe matrix — adapter snippets per stack (Playwright / pytest / Cypress / Jest / Vitest / Go): `docs/how-to/8-recipe-matrix.md`
- Adoption tiers — pick reusable workflow vs. composables vs. raw CLIs: `docs/how-to/9-adoption-tiers.md`

### Reference

- Outputs glossary — every field in `report.json` / `release-readiness.json` explained: `docs/reference/outputs.md`
- JSON contracts: `docs/contracts/`
- Release process and SHA-pin policy: `RELEASE.md`
- Changelog: `CHANGELOG.md`

### Pre-flight

Before wiring CI, run the doctor against your scaffolded config:

```bash
release-readiness-doctor --config ops/release-readiness/config.yaml \
  --smoke-results evidence/smoke.json \
  --e2e-results evidence/e2e.json \
  --coverage evidence/coverage.json
```

Doctor catches config typos, evidence-shape mismatches, and common inconsistencies (e.g. `failed_count > 0` but `failures: []`) before they reach a real run. Exits non-zero on any error.

### Two CLIs — when to use which

- `release-readiness-evaluate` — the **full evaluator**. Loads `config.yaml`, reads evidence files, computes PASS/WARN/BLOCK, writes `report.json` / `report.md` / `release-readiness.json`. **Use this in CI.**
- `release-readiness` — a **lightweight summary** of validation booleans given inline JSON. No scoring, no thresholds, no artifacts on disk. Useful for quick sanity checks (`release-readiness --input-json '[{"key":"x","status":"PASS"}]'`) or as a debugging probe in scripts. **Not a substitute for the evaluator in production CI.**

### Contracts and Spike Notes

- Package boundary API contract spike notes: `docs/spikes/package-boundary-api-contract.md`
- Validation-key handling prep (validation keys → config): `docs/prep/validation-key-handling.md`
- PR risk input schema: `docs/contracts/pr-risk-input-v1.schema.json`
- Readiness output schema: `docs/contracts/release-readiness-output-v1.schema.json`
- Validation config draft schema: `docs/contracts/validation-config-v1.schema.json`
- Contract reference guide: `docs/contracts/README.md`

### MCP Setup (Cursor + Claude)

This repo mirrors the same MCP server set used in TalkBack:
- `talkback`
- `github`
- `atlassian`

Create `.env.mcp` in the repo root (or export these vars in your shell):

```bash
TALKBACK_MCP_AUTH_HEADER="Bearer <talkback-api-key>"
TALKBACK_MCP_ACTING_USER_ID="<talkback-user-uuid>"
GITHUB_PERSONAL_ACCESS_TOKEN="<github-pat>"
ATLASSIAN_DOMAIN="<your-domain>.atlassian.net"
ATLASSIAN_EMAIL="<your-email>"
ATLASSIAN_API_TOKEN="<atlassian-api-token>"
```

Then generate local MCP config for both tools:

```bash
./scripts/setup-mcp-config.sh
```

This writes:
- `.cursor/mcp.json` (Cursor)
- `.mcp.json` (Claude Code project scope)

Both files are gitignored.

### Agent Command Workflows

This repository supports the same Jira automation command patterns as TalkBack.

- `implement <TICKET-KEY>` Standard ticket workflow: code + tests + PR + Jira transition to In Review.
- `implement <TICKET-KEY> FULL_AUTO` Includes standard workflow plus post-PR gate polling, merge, and Jira Done transition.
- `run epic <TICKET-KEY>` / `continue epic <TICKET-KEY>` Epic automation mode that runs each child ticket as FULL_AUTO and drains remaining work.

Policy ownership:
- Entry point: `CLAUDE.md`
- Jira workflow: `docs/agent/workflow-jira.md`
- FULL_AUTO merge rules: `docs/agent/workflow-full-auto.md`
- Epic run rules: `docs/agent/workflow-epic-run.md`
- Testing policy: `docs/agent/testing-validation.md`
- Rule map: `docs/agent/rule-ownership.md`

Epic mode uses the same merge gate as FULL_AUTO in this repo: PR Gate `success` plus `mergeable_state: clean`.

