Metadata-Version: 2.5
Name: bitexoft-verify
Version: 0.2.1
Summary: Verifica las entregas de los proyectos de Bitexoft: la misma herramienta en tu máquina y en CI.
Author: Bitexoft
License: Proprietary
Keywords: ai,api,education,python,verification
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Education :: Testing
Requires-Python: >=3.10
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: pyyaml>=6.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# bitexoft-verify

The platform's only definition of "correct". It runs in two places and decides the same
thing in both:

| Where | When | What it is worth |
|---|---|---|
| Your machine | while you work, answers in seconds | informative |
| GitHub Actions | on every push, pinned, clean environment | **official** |

The difference shows up as `provenance.surface` in the report. The platform marks a
delivery as verified only on a green CI report.

## Install

Python 3.10 or newer — the version Ubuntu 22.04 LTS ships, so a stock Linux works without
upgrading anything.

```bash
pip install bitexoft-verify            # core; one small dependency below 3.11
pip install 'bitexoft-verify[api]'     # adds what later deliveries need to verify APIs
```

If pip answers `requires a different Python`, check your version with `python3 -V`. The
project itself targets a newer Python than the tool does: each delivery's contract states
what it needs.

## Use

```bash
bitexoft-verify check A1          # verify A1
bitexoft-verify check A3          # verify A3 and, on the way, A1 and A2
bitexoft-verify check A3 --only   # just A3
bitexoft-verify deliveries        # what this version can verify
```

Exit codes: `0` all green, `1` something fails, `2` could not even start.

## `bitexoft.toml`

Organise your project however you like. You declare it here and verification reads it
from here; what is not negotiable is the **shape** of the boundaries, not their names.

```toml
[project]
id = "chaos-sports-lab"
package = "chaoslab"

[layers]
domain = "chaoslab.domain"

[cli]
module = "chaoslab"        # run as `python -m chaoslab`
# main = "main.py"         # or a script, if that is your entry point
```

## The three gates

- **Acceptance** — that it works: the contract's symbols, impossible objects refused,
  value semantics, the geometry, the entry point and its exit codes.
- **Design** — that it is built well: the domain's boundary read from the syntax tree,
  your tests passing, at least one test that builds an impossible object.
- **Evidence** — that you understand it. The CLI **does not judge** this gate: it always
  reports `skip` with a message. You close it on the platform by writing the why and
  comparing it against the rubric.

A check never fails for something you cannot fix: if an optional dependency or a git tag
is missing, it **skips** with a message saying what to do.

## Cumulative verification

Verifying A3 also runs A1 and A2, with inherited checks tagged `[A1]`. That is what makes
the method agile: every delivery leaves the whole project standing, and a regression in
old work shows up while verifying the new.

## The sample files

Deliveries are verified against files the CLI ships with, not against one you wrote. For
A1 that is 30 instants crossing all three block states, plus a copy with one coordinate
off the pitch to check that bad data fails cleanly instead of printing a traceback at the
user. They are synthetic: no third-party data is distributed here.

## Development

```bash
pip install -e '.[dev,api]'
pytest                               # builds a fake learner repository and verifies it
ruff check .
python tools/make_fixtures.py        # regenerate the sample files
```

Before changing what a check says when it fails, or the layout of the output, read
[`docs/foundations/03-feedback-self-explanation-calibration.md`](../docs/foundations/03-feedback-self-explanation-calibration.md)
(the verifier's messages are the feedback a learner reads) and ADR 0002. The check ids and the report
schema are a contract with the platform: do not rename them.

## Releasing

The version is written once, in `__version__` (`src/bitexoft_verify/__init__.py`). The pin in
`.github/workflows/verify.yml` (`cli-version`) must match its `major.minor`; a test checks it.

First release, by hand on pypi.org:

1. Account → Publishing → *Add a pending publisher*: project `bitexoft-verify`, owner `bitexoft`,
   repository `sports-lab-v1`, workflow `release-verify.yml`, environment `pypi`.
2. In the repository settings, create the environment `pypi`.

Each release:

```bash
git tag verify-v0.2.0 && git push origin verify-v0.2.0
```

The workflow runs `pytest` on 3.10 and 3.12, refuses a tag that differs from `__version__`, builds
with `python -m build` and publishes with trusted publishing (no tokens). Check it in a clean
environment: `pipx run --spec bitexoft-verify bitexoft-verify deliveries`.
