bitexoft-verify 0.2.0__py3-none-any.whl

bitexoft_verify/manifest.py

@@ -0,0 +1,103 @@
+"""The `bitexoft.toml` manifest.
+
+This is what decouples the checks from the learner's code. Without it, verifying would
+mean imposing package names and paths: "your package is called chaoslab and your domain
+lives in chaoslab/domain". With it, everyone organises their project as they like and
+declares where they put each thing; what is not negotiable is the SHAPE of the
+boundaries, not their names.
+
+    [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
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+# tomllib joined the standard library in 3.11. Before that the same library is `tomli`,
+# which is declared as a conditional dependency. The learner should not have to upgrade
+# their interpreter to read a six-line configuration file.
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - exercised on Python 3.10
+    import tomli as tomllib  # type: ignore[no-redef]
+
+MANIFEST_NAME = "bitexoft.toml"
+
+
+class ManifestError(Exception):
+    """The manifest is missing, is not valid TOML, or lacks required keys."""
+
+
+@dataclass(frozen=True, slots=True)
+class Manifest:
+    root: Path
+    data: dict
+
+    @property
+    def project_id(self) -> str:
+        return str(self.get("project.id", ""))
+
+    def get(self, dotted: str, default: object | None = None) -> object | None:
+        node: object = self.data
+        for part in dotted.split("."):
+            if not isinstance(node, dict) or part not in node:
+                return default
+            node = node[part]
+        return node
+
+    def require(self, dotted: str) -> str:
+        value = self.get(dotted)
+        if not isinstance(value, str) or value.strip() == "":
+            raise ManifestError(f"key '{dotted}' is missing from {MANIFEST_NAME}")
+        return value
+
+    def missing(self, keys: list[str]) -> list[str]:
+        return [k for k in keys if not isinstance(self.get(k), str) or str(self.get(k)).strip() == ""]
+
+    def layer(self, name: str) -> str | None:
+        value = self.get(f"layers.{name}")
+        return value if isinstance(value, str) else None
+
+    def layer_path(self, name: str) -> Path | None:
+        """A layer's folder, resolved from its dotted module path."""
+        module = self.layer(name)
+        if not module:
+            return None
+        candidate = self.root / Path(*module.split("."))
+        return candidate if candidate.is_dir() else None
+
+    def resolve(self, reference: str) -> str:
+        """Expands contract placeholders: `<layers.domain>.models` -> `chaoslab.domain.models`."""
+        out = reference
+        while "<" in out and ">" in out:
+            start, end = out.index("<"), out.index(">")
+            key = out[start + 1 : end]
+            value = self.get(key)
+            if not isinstance(value, str):
+                raise ManifestError(f"the contract uses '{key}' and the manifest does not declare it")
+            out = out[:start] + value + out[end + 1 :]
+        return out
+
+
+def load(root: Path) -> Manifest:
+    path = root / MANIFEST_NAME
+    if not path.is_file():
+        raise ManifestError(
+            f"{MANIFEST_NAME} not found in {root}. Create it at the repository root: "
+            "declare your package and where each layer lives."
+        )
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ManifestError(f"{MANIFEST_NAME} is not valid TOML: {exc}") from exc
+    return Manifest(root=root, data=data)

bitexoft_verify/report.py

@@ -0,0 +1,234 @@
+"""The report: the only thing that leaves this tool and the only thing the platform reads.
+
+The same object is written locally and in CI. What changes between the two is
+`provenance.surface`, and all the difference in authority follows from it:
+
+    local  -> informative, for working with answers in seconds
+    ci     -> official, run pinned and in a clean environment
+
+The schema is versioned on purpose: the platform rejects what it does not recognise
+instead of half-interpreting it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from numbers import Real
+from pathlib import Path
+from typing import Literal
+
+from .codes import ISSUE_CODES
+
+# Still v3 (ADR 0028): `issues` is optional, a report without it is valid, and a copy of the
+# platform that does not know the field ignores it.
+SCHEMA = "bitexoft.verify.report/v3"
+
+Status = Literal["pass", "fail", "skip"]
+Surface = Literal["local", "ci"]
+
+Scalar = str | int | float | bool
+Param = Scalar | list
+
+CODE_PATTERN = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+
+
+def _plain(value: object, nested: bool = False) -> Param:
+    """A value as plain JSON: text, a number, a boolean, or a flat list of those."""
+    if isinstance(value, str | bool | int | float):
+        return value
+    if isinstance(value, list | tuple) and not nested:
+        return [_plain(item, nested=True) for item in value]
+    if isinstance(value, Real):
+        return float(value)
+    return str(value)
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One problem a check found, as data: a stable code and the values behind it.
+
+    The sentence a learner reads is not here. The platform writes it, in the learner's language,
+    from the code and the parameters (ADR 0027); the CLI writes an English one for the terminal.
+    A wrong code or a stray parameter is a bug in a check, so it raises.
+    """
+
+    code: str
+    params: dict[str, Param] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.code not in ISSUE_CODES:
+            raise ValueError(f"unknown issue code {self.code!r}: add it to bitexoft_verify/codes.py")
+        if not CODE_PATTERN.match(self.code):
+            raise ValueError(f"issue code {self.code!r} is not <area>.<kind> in lower case")
+        stray = set(self.params) - set(ISSUE_CODES[self.code])
+        if stray:
+            raise ValueError(f"issue {self.code!r} does not take {', '.join(sorted(stray))}")
+        # What the learner's code returns is not ours to reject: a value that is not plain JSON
+        # (a numpy float, an object) becomes a number or text, so describing a failure never
+        # becomes a second failure.
+        object.__setattr__(self, "params", {name: _plain(value) for name, value in self.params.items()})
+
+    def as_dict(self) -> dict:
+        return {"code": self.code, "params": dict(self.params)}
+
+
+def issue(code: str, **params: Param) -> Issue:
+    return Issue(code, params)
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    """One concrete check. `message` explains a failure or justifies a skip.
+
+    `title` is always English: it is emitted by the tool, and the platform localises
+    known check ids, falling back to this text. `issues` says the same as `message` as data, one
+    entry per problem (ADR 0028); `message` stays, in English, for the terminal and as the fallback.
+    """
+
+    id: str
+    title: str
+    status: Status
+    message: str | None = None
+    issues: tuple[Issue, ...] = ()
+
+    def as_dict(self) -> dict:
+        data: dict = {"id": self.id, "title": self.title, "status": self.status}
+        if self.message:
+            data["message"] = self.message
+        if self.issues:
+            data["issues"] = [item.as_dict() for item in self.issues]
+        return data
+
+
+class Problems:
+    """What one check found wrong: the sentence for the terminal and the issues that say it as data.
+
+    Each entry keeps its sentence and its issues together, where the problem is found, so the
+    message and the issues cannot drift apart. `failing` builds the check with the same sentence the
+    check always produced.
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[tuple[str, tuple[Issue, ...]]] = []
+
+    def add(self, text: str, code: str, **params: Param) -> None:
+        self._entries.append((text, (Issue(code, params),)))
+
+    def add_group(self, text: str, issues: list[Issue]) -> None:
+        """Several issues told in one sentence."""
+        self._entries.append((text, tuple(issues)))
+
+    def __bool__(self) -> bool:
+        return bool(self._entries)
+
+    def failing(self, check_id: str, title: str, separator: str = " | ", limit: int | None = None) -> Check:
+        entries = self._entries[:limit] if limit is not None else self._entries
+        return Check(
+            check_id,
+            title,
+            "fail",
+            separator.join(text for text, _ in entries),
+            tuple(item for _, issues in entries for item in issues),
+        )
+
+
+@dataclass(slots=True)
+class Gate:
+    """A group of checks. The gate fails if any of them fails."""
+
+    id: str
+    checks: list[Check] = field(default_factory=list)
+
+    @property
+    def status(self) -> Status:
+        if any(check.status == "fail" for check in self.checks):
+            return "fail"
+        if self.checks and all(check.status == "skip" for check in self.checks):
+            return "skip"
+        return "pass"
+
+    def as_dict(self) -> dict:
+        return {"id": self.id, "status": self.status, "checks": [check.as_dict() for check in self.checks]}
+
+
+def detect_surface(explicit: str | None = None) -> Surface:
+    """CI detects itself: nobody has to remember a flag."""
+    if explicit in ("local", "ci"):
+        return explicit  # type: ignore[return-value]
+    return "ci" if os.environ.get("GITHUB_ACTIONS") == "true" else "local"
+
+
+def detect_provenance(surface: Surface) -> dict:
+    env = os.environ
+    repo = env.get("GITHUB_REPOSITORY")
+    run_id = env.get("GITHUB_RUN_ID")
+    server = env.get("GITHUB_SERVER_URL", "https://github.com")
+    return {
+        "surface": surface,
+        "repo": repo,
+        "commit": env.get("GITHUB_SHA"),
+        "run_url": f"{server}/{repo}/actions/runs/{run_id}" if repo and run_id else None,
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z"),
+    }
+
+
+@dataclass(slots=True)
+class Report:
+    project: str
+    delivery: str
+    cli_version: str
+    gates: list[Gate]
+    surface: Surface = "local"
+    # Reserved for the graduated-help mechanism. `help_level` is the highest level of
+    # assistance taken for this delivery (0 = none) and `provided_files` lists files the
+    # learner did not write. They are declared now, and always emitted, so the platform
+    # never has to deal with two report shapes once help ships.
+    help_level: int = 0
+    provided_files: list[str] = field(default_factory=list)
+
+    @property
+    def failed(self) -> int:
+        return sum(1 for gate in self.gates for check in gate.checks if check.status == "fail")
+
+    @property
+    def passed(self) -> int:
+        return sum(1 for gate in self.gates for check in gate.checks if check.status == "pass")
+
+    @property
+    def skipped(self) -> int:
+        return sum(1 for gate in self.gates for check in gate.checks if check.status == "skip")
+
+    @property
+    def total(self) -> int:
+        return sum(len(gate.checks) for gate in self.gates)
+
+    @property
+    def ok(self) -> bool:
+        return self.failed == 0
+
+    def as_dict(self) -> dict:
+        return {
+            "schema": SCHEMA,
+            "cli_version": self.cli_version,
+            "project": self.project,
+            "delivery": self.delivery,
+            "provenance": detect_provenance(self.surface),
+            "autonomy": {"help_level": self.help_level, "provided_files": sorted(self.provided_files)},
+            "gates": [gate.as_dict() for gate in self.gates],
+            "summary": {
+                "status": "pass" if self.ok else "fail",
+                "passed": self.passed,
+                "failed": self.failed,
+                "skipped": self.skipped,
+                "total": self.total,
+            },
+        }
+
+    def write(self, path: Path) -> Path:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.as_dict(), indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        return path

bitexoft_verify/runner.py

@@ -0,0 +1,101 @@
+"""Picks and runs the checks for a delivery.
+
+Verification is CUMULATIVE: verifying A3 also runs A1 and A2. That is what makes the
+method agile rather than merely incremental — every delivery leaves the whole project
+standing, and a regression in old work surfaces while verifying the new.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+from .checks import a1
+from .checks.common import Context
+from .manifest import Manifest, load
+from .report import Check, Gate, Report
+
+# Deliveries in the order they are meant to be built. Adding one is adding a line here
+# plus its module; nothing else in the tool needs to know.
+DELIVERIES: dict[str, object] = {"A1": a1}
+DELIVERY_ID = re.compile(r"^[A-G][0-9]{1,2}$")
+
+# Deliveries whose checks are frozen (ADR 0009). Some of A1's checks are the shared ones in
+# `checks/common.py`, which can describe a failure as structured issues (ADR 0028). A frozen
+# delivery's results must not change, so they are emitted without `issues`: the `message` and
+# the statuses are exactly what they always were, and the platform shows that message as it is.
+# Taking A1 out of this set is a decision for a new ADR, not a tidy-up.
+FROZEN_DELIVERIES = frozenset({"A1"})
+
+
+class UnknownDelivery(Exception):
+    """That delivery has no published checks yet."""
+
+
+def available_deliveries() -> list[str]:
+    return list(DELIVERIES)
+
+
+def _prepare_imports(root: Path) -> None:
+    """The learner's code wins: their root goes first on sys.path."""
+    entry = str(root.resolve())
+    if entry in sys.path:
+        sys.path.remove(entry)
+    sys.path.insert(0, entry)
+
+
+def _retag(check: Check, delivery_id: str) -> Check:
+    """Marks an inherited check so a regression says which delivery it came from."""
+    return Check(
+        id=f"{delivery_id.lower()}_{check.id}",
+        title=f"[{delivery_id}] {check.title}",
+        status=check.status,
+        message=check.message,
+        issues=check.issues,
+    )
+
+
+def run(
+    root: Path,
+    delivery_id: str,
+    *,
+    cli_version: str,
+    surface: str = "local",
+    cumulative: bool = True,
+    manifest: Manifest | None = None,
+    timeout: int = 180,
+) -> Report:
+    if not DELIVERY_ID.match(delivery_id):
+        raise UnknownDelivery(f"'{delivery_id}' is not a delivery identifier, such as A1")
+    if delivery_id not in DELIVERIES:
+        raise UnknownDelivery(
+            f"delivery {delivery_id} has no published checks yet "
+            f"(available: {', '.join(available_deliveries())}). Update bitexoft-verify."
+        )
+
+    manifest = manifest or load(root)
+    _prepare_imports(root)
+    ctx = Context(root=root, manifest=manifest, timeout=timeout)
+
+    order = available_deliveries()
+    wanted = order[: order.index(delivery_id) + 1] if cumulative else [delivery_id]
+
+    merged: dict[str, Gate] = {}
+    for current in wanted:
+        module = DELIVERIES[current]
+        for gate in module.gates(ctx):  # type: ignore[attr-defined]
+            target = merged.setdefault(gate.id, Gate(gate.id))
+            for check in gate.checks:
+                if current in FROZEN_DELIVERIES and check.issues:
+                    check = replace(check, issues=())
+                target.checks.append(check if current == delivery_id else _retag(check, current))
+
+    return Report(
+        project=manifest.project_id or "unknown",
+        delivery=delivery_id,
+        cli_version=cli_version,
+        gates=[merged[key] for key in ("acceptance", "design", "evidence") if key in merged],
+        surface=surface,  # type: ignore[arg-type]
+    )

bitexoft_verify-0.2.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: bitexoft-verify
+Version: 0.2.0
+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`.

bitexoft_verify-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+bitexoft_verify/__init__.py,sha256=ztmdVEmKeQyrOoF-IvxGkoN9Wr8QpwVhaEXHfiJFKvU,91
+bitexoft_verify/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+bitexoft_verify/cli.py,sha256=U5UkgX5gdnRv_J6otLKFNWESzuG7GRG3EqRIJCnbDkA,4609
+bitexoft_verify/codes.py,sha256=mZkelfk8SAxKVxgFEG56Xbhpnn7Sx9ZJF8zGLb9qOVI,2653
+bitexoft_verify/manifest.py,sha256=Rcdi-FBh6-2wxYCkOCyr5SdUW9QFm9Mgt0mnALCtJXM,3728
+bitexoft_verify/report.py,sha256=XkEu0vOwFDZ4tmi4X5kYXmH9v5o9VojulPixpQa-6CI,8538
+bitexoft_verify/runner.py,sha256=9FPLOBeD3phIsxT5mCA1pDWrozADB8UdAoBiaBEa0CM,3612
+bitexoft_verify/checks/__init__.py,sha256=zluliHovi0N9aMMRr6sXhhYonMcLT6UX3Tr6q6v8N-0,39
+bitexoft_verify/checks/a1.py,sha256=ooeSykNKXQCZ-8gcvh4z9yzbPZZdkOTh68UAXsdVwZQ,15716
+bitexoft_verify/checks/common.py,sha256=mDo-LKMldGjmYMvFR_GWcNwO5FgothVh2YjG65sc_aM,10779
+bitexoft_verify/data/README.md,sha256=FBoTovLSIQ6IKhPOtz5iUFbs-QGFed1BwFbMh4inuX8,706
+bitexoft_verify/data/a1_impossible_sample.csv,sha256=kvnTYoEnt82ZFwMUmGd1UOr6qMMsJ8sRHHH40CpDvk4,5298
+bitexoft_verify/data/a1_match_sample.csv,sha256=8NEKo2gvY_Z12-Q1KBdKnSpRV2SPXOOE58VfAccVH74,5298
+bitexoft_verify/data/a2_isolated_sample.csv,sha256=O5iGlwlS1tlmym1axT7PRtuu-QEWvJzWd2BtbEFvps0,5310
+bitexoft_verify/data/issue-codes.json,sha256=Cv77fIn9nfKvzvPh7tiG9NiRyRYDUpLwHq_UCjpnNyI,1002
+bitexoft_verify-0.2.0.dist-info/METADATA,sha256=vPXFttEZ03Oh4PC0p_D-l-wJSzThQqj1ChNiq7oMlm8,5336
+bitexoft_verify-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bitexoft_verify-0.2.0.dist-info/entry_points.txt,sha256=MI-OtsbZc0x0PEh3SbFEr87zUEs01vwuENgDX5Tkvas,61
+bitexoft_verify-0.2.0.dist-info/RECORD,,

bitexoft_verify-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

bitexoft_verify-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bitexoft-verify = bitexoft_verify.cli:main