testing-conventions 0.0.44__tar.gz → 0.0.45__tar.gz

{testing_conventions-0.0.44 → testing_conventions-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testing-conventions
-Version: 0.0.44
+Version: 0.0.45
 Requires-Dist: cosmic-ray
 Requires-Dist: coverage
 Summary: Enforce testing conventions in libraries (Python, TypeScript, and Rust).

testing_conventions-0.0.45/python/testing_conventions/mutation/baseline.py

@@ -0,0 +1,32 @@
+"""The baseline check: the unit suite must pass over unmutated code.
+
+``cosmic_ray`` is imported lazily (the module imports without the engine; the check itself
+is unit-tested with a fake ``cosmic_ray`` injected).
+"""
+from __future__ import annotations
+
+
+def check_baseline(config):
+    """Run the suite once with no mutation, raising ``RuntimeError`` if it fails. cosmic-ray
+    reports the unmutated baseline ``killed`` when the tests fail on their own — without this
+    guard every mutant would falsely ``die`` on the already-failing suite and we'd report a
+    clean pass."""
+    import tempfile
+    from pathlib import Path
+
+    from cosmic_ray.commands import execute
+    from cosmic_ray.work_db import WorkDB, use_db
+    from cosmic_ray.work_item import WorkItem
+
+    with tempfile.TemporaryDirectory() as tmp:
+        with use_db(Path(tmp) / "baseline.sqlite", mode=WorkDB.Mode.create) as database:
+            database.clear()
+            database.add_work_item(WorkItem(mutations=[], job_id="baseline"))
+            execute(database, config)
+            _, result = next(database.results)
+    outcome = getattr(result.test_outcome, "value", result.test_outcome)
+    if outcome == "killed":
+        raise RuntimeError(
+            "the Python unit suite did not pass unmutated (cosmic-ray baseline failed):\n"
+            + (result.output or "")
+        )

testing_conventions-0.0.45/python/testing_conventions/mutation/cli.py

@@ -0,0 +1,35 @@
+"""The mutation adapter's orchestrator (#248), the Python counterpart of the TypeScript
+``mutationCLI``: parse args, drive cosmic-ray in-process, and emit the normalized-results
+JSON the rust core gates on. A pure, importable function; ``main.py`` is the executable that
+runs it.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from testing_conventions.mutation.baseline import check_baseline
+from testing_conventions.mutation.config import build_config
+from testing_conventions.mutation.normalize import normalize
+from testing_conventions.mutation.parse_args import parse_args
+from testing_conventions.mutation.session import run_session
+
+
+def mutation_cli(argv):
+    """Run the adapter over ``argv``: build the cosmic-ray config, check the baseline, run the
+    session, and write the normalized results to ``--out``. Any failure is printed to stderr
+    and turned into a non-zero exit code."""
+    try:
+        args = parse_args(argv)
+        config = build_config(args.modules)
+        check_baseline(config)
+        results = [
+            mutant
+            for mutation, result in run_session(config)
+            if (mutant := normalize(mutation, result)) is not None
+        ]
+        with open(args.out, "w", encoding="utf-8") as handle:
+            json.dump(results, handle)
+    except Exception as error:  # surface any adapter failure as a clean non-zero exit
+        sys.stderr.write(f"{error}\n")
+        sys.exit(1)

testing_conventions-0.0.45/python/testing_conventions/mutation/config.py

@@ -0,0 +1,39 @@
+"""Build the cosmic-ray configuration the adapter drives.
+
+[`render_config`] is the pure TOML-rendering half; [`build_config`] parses it into
+cosmic-ray's ``ConfigDict`` (the object ``init`` / ``execute`` consume). ``cosmic_ray`` is
+imported lazily so the module imports without the engine installed — the pure renderer stays
+testable anywhere, and the dogfood coverage job (which installs only coverage + pytest) can
+collect this package.
+"""
+from __future__ import annotations
+
+# Test files cosmic-ray must never mutate (it would mutate the suite itself). Mirrors the
+# excludes the CLI-driven Rust arm used.
+EXCLUDES = ["*_test.py", "test_*.py", "conftest.py"]
+
+
+def render_config(modules):
+    """Render the ``cosmic-ray`` TOML for a run over ``modules`` (a list of source-file
+    paths; empty ⇒ the whole project, ``"."``). ``pytest`` runs the suite; the ``local``
+    distributor runs each mutant in this adapter's own process tree."""
+    paths = modules or ["."]
+    module_path = ", ".join(f'"{p}"' for p in paths)
+    excludes = ", ".join(f'"{glob}"' for glob in EXCLUDES)
+    return (
+        "[cosmic-ray]\n"
+        f"module-path = [{module_path}]\n"
+        "timeout = 30.0\n"
+        f"excluded-modules = [{excludes}]\n"
+        'test-command = "python3 -m pytest -q -p no:cacheprovider"\n'
+        "\n"
+        "[cosmic-ray.distributor]\n"
+        'name = "local"\n'
+    )
+
+
+def build_config(modules):
+    """The parsed cosmic-ray ``ConfigDict`` for a run over ``modules``."""
+    from cosmic_ray.config import deserialize_config
+
+    return deserialize_config(render_config(modules))

testing_conventions-0.0.45/python/testing_conventions/mutation/conftest.py

@@ -0,0 +1,68 @@
+"""Shared fakes for the mutation adapter's unit tests.
+
+The adapter imports ``cosmic_ray`` lazily (inside the functions), so the engine need not be
+installed to unit-test it. This fixture installs a fake ``cosmic_ray`` package tree in
+``sys.modules`` for the duration of a test, and the lazy imports resolve to it — injecting the
+dependency via ``sys.modules`` (never ``monkeypatch`` or an inline ``patch``, which the
+isolation lint forbids), the same technique the version-conditional ``tomlcompat`` test uses.
+"""
+from __future__ import annotations
+
+import contextlib
+import sys
+from types import ModuleType, SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+
+@pytest.fixture
+def cosmic_ray():
+    """Yield the adapter's cosmic-ray seams as configurable mocks. ``db`` is the fake
+    ``WorkDB`` a test configures (``db.results`` for the baseline, ``db.completed_work_items``
+    for the session); the rest are the ``find_modules`` / ``init`` / ``execute`` / ... calls."""
+    saved = {
+        name: mod
+        for name, mod in sys.modules.items()
+        if name == "cosmic_ray" or name.startswith("cosmic_ray.")
+    }
+    for name in saved:
+        del sys.modules[name]
+
+    seams = SimpleNamespace(
+        db=MagicMock(name="WorkDB"),
+        deserialize_config=MagicMock(name="deserialize_config"),
+        find_modules=MagicMock(name="find_modules", return_value=[]),
+        filter_paths=MagicMock(name="filter_paths", side_effect=lambda mods, excl: list(mods)),
+        init=MagicMock(name="init"),
+        execute=MagicMock(name="execute"),
+        WorkItem=MagicMock(name="WorkItem"),
+    )
+
+    @contextlib.contextmanager
+    def use_db(path, mode=None):
+        yield seams.db
+
+    def module(name, **attrs):
+        mod = ModuleType(name)
+        for key, value in attrs.items():
+            setattr(mod, key, value)
+        sys.modules[name] = mod
+        return mod
+
+    root = module("cosmic_ray")
+    root.commands = module("cosmic_ray.commands", init=seams.init, execute=seams.execute)
+    root.modules = module(
+        "cosmic_ray.modules", find_modules=seams.find_modules, filter_paths=seams.filter_paths
+    )
+    root.config = module("cosmic_ray.config", deserialize_config=seams.deserialize_config)
+    root.work_db = module(
+        "cosmic_ray.work_db", use_db=use_db, WorkDB=SimpleNamespace(Mode=SimpleNamespace(create=1))
+    )
+    root.work_item = module("cosmic_ray.work_item", WorkItem=seams.WorkItem)
+
+    yield seams
+
+    for name in [n for n in sys.modules if n == "cosmic_ray" or n.startswith("cosmic_ray.")]:
+        del sys.modules[name]
+    sys.modules.update(saved)

testing_conventions-0.0.45/python/testing_conventions/mutation/main.py

@@ -0,0 +1,9 @@
+"""Executable entry for the Python mutation arm (#248): the rust binary spawns
+``python -m testing_conventions.mutation.main`` and this runs [`mutation_cli`] over the
+process arguments. Kept thin so the orchestration stays a pure, importable function.
+"""
+import sys
+
+from testing_conventions.mutation.cli import mutation_cli
+
+mutation_cli(sys.argv[1:])

testing_conventions-0.0.45/python/testing_conventions/mutation/normalize.py

@@ -0,0 +1,30 @@
+"""Map a cosmic-ray work item + result onto the normalized mutation schema (#245).
+
+The rust core gates over one engine-agnostic representation
+(``{file, line, status, mutator}``); this turns cosmic-ray's per-mutant outcome into it,
+the Python counterpart of the TypeScript adapter's ``to-normalized``. It reads only plain
+attributes off the passed objects, so it needs no ``cosmic_ray`` import.
+"""
+from __future__ import annotations
+
+# cosmic-ray's ``TestOutcome`` values → the normalized ``MutantStatus`` vocabulary.
+# ``survived`` / ``killed`` map straight across; ``incompetent`` (the mutation produced code
+# the interpreter rejected — a syntax / import error, never a viable mutant) is
+# ``compile_error``. cosmic-ray has no distinct no-coverage outcome: an uncovered mutant's
+# suite still passes, so it reports ``survived``.
+STATUS = {"survived": "survived", "killed": "killed", "incompetent": "compile_error"}
+
+
+def normalize(mutation, result):
+    """Return the normalized mutant dict for one completed work item, or ``None`` to skip a
+    work item with no usable outcome (the worker never judged it — abnormal / no test)."""
+    outcome = result.test_outcome
+    status = STATUS.get(getattr(outcome, "value", outcome))
+    if status is None:
+        return None
+    return {
+        "file": str(mutation.module_path).replace("\\", "/"),
+        "line": mutation.start_pos[0],
+        "status": status,
+        "mutator": mutation.operator_name,
+    }

testing_conventions-0.0.45/python/testing_conventions/mutation/parse_args.py

@@ -0,0 +1,28 @@
+"""Parse the mutation adapter's CLI arguments.
+
+The rust binary spawns ``python -m testing_conventions.mutation.main`` and passes these:
+``--out <path>`` (where to write the normalized-results JSON — the rule passes a temp file)
+and ``--module <path>`` (repeatable; the source files to mutate, for a diff-scoped run).
+Without any ``--module`` the whole project is mutated.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Args:
+    """The adapter's parsed arguments."""
+
+    out: str
+    modules: list[str] = field(default_factory=list)
+
+
+def parse_args(argv):
+    """Parse ``argv`` (a list of strings) into [`Args`]."""
+    parser = argparse.ArgumentParser(prog="testing-conventions-mutation")
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--module", action="append", default=[], dest="modules")
+    ns = parser.parse_args(argv)
+    return Args(out=ns.out, modules=ns.modules)

testing_conventions-0.0.45/python/testing_conventions/mutation/session.py

@@ -0,0 +1,35 @@
+"""Run a cosmic-ray session over the configured modules.
+
+``cosmic_ray`` is imported lazily (the module imports without the engine; the session is
+unit-tested with a fake ``cosmic_ray`` injected).
+"""
+from __future__ import annotations
+
+
+def run_session(config):
+    """Init + execute cosmic-ray over ``config``'s ``module-path`` and return a list of
+    ``(MutationSpec, WorkResult)`` — the first mutation of each completed work item paired
+    with its outcome. The session DB lives in an out-of-tree temp dir; cosmic-ray mutates
+    each source file in place and reverts it, so the scanned tree is left as it was."""
+    import tempfile
+    from pathlib import Path
+
+    import cosmic_ray.commands
+    import cosmic_ray.modules
+    from cosmic_ray.work_db import WorkDB, use_db
+
+    module_path = config["module-path"]
+    paths = (
+        [Path(module_path)]
+        if isinstance(module_path, str)
+        else [Path(entry) for entry in module_path]
+    )
+    modules = cosmic_ray.modules.find_modules(paths)
+    modules = cosmic_ray.modules.filter_paths(modules, config.get("excluded-modules", ()))
+    with tempfile.TemporaryDirectory() as tmp:
+        with use_db(Path(tmp) / "session.sqlite", mode=WorkDB.Mode.create) as database:
+            cosmic_ray.commands.init(modules, database, config.operators_config)
+            cosmic_ray.commands.execute(database, config)
+            return [
+                (item.mutations[0], result) for item, result in database.completed_work_items
+            ]

{testing_conventions-0.0.44 → testing_conventions-0.0.45}/rust/CHANGELOG.md

@@ -31,6 +31,16 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `testing-conventions` launcher passes the adapter's path to the binary as a `--ts-mutation-adapter`
   argument on a `unit mutation` invocation; the SDK `measure_typescript` takes it as a trailing
   `adapter: &Path`. See [MIGRATIONS](./MIGRATIONS.md).
+- **`unit mutation --language python` drives cosmic-ray in-process through a bundled adapter** (#248,
+  epic #239). The Python arm now spawns a Python adapter shipped in the wheel (`python3 -m
+  testing_conventions.mutation.main`) that drives cosmic-ray via its `WorkDB` library API and emits
+  the normalized `NormalizedMutant` schema (#239) the gate consumes — replacing the `cosmic-ray` CLI
+  orchestration (baseline/init/exec/dump spawns + JSONL dump parse). The tool drives the engine; the
+  project supplies its own test runner (pytest). maturin ships the binary directly as the wheel's
+  script, so — unlike the TS arm's launcher-injected path — the binary resolves the adapter as an
+  installed module (from the wheel's site-packages; the diff-scoped run passes the changed `.py`
+  files as `--module` and the core filters survivors to the changed lines). `measure_python`'s
+  signature is unchanged. See [MIGRATIONS](./MIGRATIONS.md).
 
 ### Removed
 
@@ -39,6 +49,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   the TS arm no longer parses a Stryker report file; the bundled adapter emits the normalized schema
   (#239) directly. Consume `parse_normalized_results` + `evaluate_normalized` instead. See
   [MIGRATIONS](./MIGRATIONS.md).
+- **BREAKING: the cosmic-ray `dump` types are gone** (#248). `mutation::{parse_cosmic_ray_dump,
+  cosmic_ray_mutated_lines, CosmicRayLine, CrWorkItem, CrMutation, CrResult}` are removed — the Python
+  arm no longer parses a `cosmic-ray dump`; the bundled adapter emits the normalized schema (#239)
+  directly. Consume `parse_normalized_results` + `evaluate_normalized` instead. See
+  [MIGRATIONS](./MIGRATIONS.md).
 
 ### Fixed
 

{testing_conventions-0.0.44 → testing_conventions-0.0.45}/rust/Cargo.lock

@@ -1139,7 +1139,7 @@ dependencies = [
 
 [[package]]
 name = "testing-conventions"
-version = "0.0.44"
+version = "0.0.45"
 dependencies = [
  "anyhow",
  "clap",

{testing_conventions-0.0.44 → testing_conventions-0.0.45}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "testing-conventions"
-version = "0.0.44"
+version = "0.0.45"
 edition = "2021"
 license = "MIT"
 authors = ["Kevin Scott <me@thekevinscott.com>"]

{testing_conventions-0.0.44 → testing_conventions-0.0.45}/rust/MIGRATIONS.md

@@ -15,6 +15,16 @@ Each entry has five sections, in order:
 
 ### Summary
 
+Wires the Python arm to drive cosmic-ray in-process through a **bundled Python adapter** (#248,
+building on the #239 core). `unit mutation --language python` now spawns a Python adapter shipped in
+the wheel (`python3 -m testing_conventions.mutation.main`) that drives cosmic-ray via its `WorkDB`
+library API and emits the normalized `NormalizedMutant` schema (#239) the gate consumes — replacing
+the `cosmic-ray` CLI orchestration. maturin ships the rust binary directly as the wheel's script (no
+Python launcher to inject a path, unlike the TS arm), so the binary invokes the adapter as an
+installed module, resolved from the wheel's environment alongside cosmic-ray. One breaking SDK change:
+the cosmic-ray `dump` types are removed (see **Required changes**); `measure_python`'s signature is
+unchanged.
+
 Wires the TypeScript arm to drive Stryker through a **bundled Node adapter** (#246, building on the
 #239 core). `unit mutation --language typescript` now spawns a Node adapter shipped with the npm
 package that drives Stryker via its own Node API and emits the normalized `NormalizedMutant` schema
@@ -569,6 +579,19 @@ core (#239) — the same types the bundled adapter emits and the Rust/Python arm
 | `mutation::parse_stryker_report`, `mutation::stryker_survivors` | `mutation::parse_normalized_results` + `mutation::evaluate_normalized` |
 | `mutation::{StrykerReport, StrykerFile, StrykerMutant, StrykerLocation}` | `mutation::NormalizedMutant` |
 
+The cosmic-ray `dump` types are removed the same way (#248): the Python arm no longer parses a
+`cosmic-ray dump`. Switch to the normalized core:
+
+| Removed | Replacement |
+| --- | --- |
+| `mutation::parse_cosmic_ray_dump`, `mutation::cosmic_ray_mutated_lines` | `mutation::parse_normalized_results` + `mutation::evaluate_normalized` |
+| `mutation::{CosmicRayLine, CrWorkItem, CrMutation, CrResult}` | `mutation::NormalizedMutant` |
+
+`measure_python`'s signature is unchanged; it now spawns the bundled Python adapter (`python3 -m
+testing_conventions.mutation.main`) rather than the `cosmic-ray` CLI. In production the wheel makes
+`testing_conventions` importable (site-packages); the rust integration tests set
+`PYTHONPATH=packages/python/python` for their staged fixtures.
+
 `measure_typescript` takes a trailing `adapter: &Path` — the path to the bundled Node adapter
 (`packages/node/dist/mutation/main.js`):