Dev

[amirouche]

Changes: dev vs origin/main

Summary

The dev branch is a significant refactor of mutation.py focused on eliminating external dependencies, improving correctness, expanding test coverage, and improving CLI ergonomics. Version bumped from 0.5.0 → 0.6.0.

---

Dependencies removed

Both aiostream and docopt have been dropped. mutation.py now depends only on coverage (plus stdlib). All removed functionality was replaced inline:

Removed	Replaced with
docopt	cli_read() — custom argument parser
aiostream	asyncio.wait() loop
pygments	ANSI diff printer (inline)
tqdm	Progress class (inline)
loguru	_Logger shim wrapping stdlib logging
humanize	humanize() function (inline)
termcolor	green() / red() ANSI helpers
zstandard	stdlib zlib
ulid	make_uid() — ms timestamp + random bytes

---

New features

cli_read() — custom argument parser

Replaces docopt. Parses sys.argv into (keywords, standalone, extra) tuples. The -- sentinel separates pytest passthrough args from mutation args. Fully tested with 9 new unit tests.

_diff_applies() — stale mutation detection

New function that validates whether a stored diff still applies to the current source before patching. Used in:

• mutation_ignored_gc — prunes stale ignored mutations
• install_module_loader — exits with EXIT_STALE = 5 if the mutation is stale

CLASSIFICATION_STALE = 6 / EXIT_STALE = 5

New classification for mutations whose diffs no longer apply to current source. Stale mutations are excluded from the replay queue.

MutateString skips docstrings

_is_docstring(node, tree) helper added. String mutations are no longer applied to module/class/function docstrings, reducing noise.

---

Fixes and correctness

• make_uid(): Fixed overflow — now uses milliseconds (time.time_ns() // 1_000_000) as 6 bytes instead of microseconds as 8 bytes.
• mutation_pass → mutation_is_survivor: Renamed for clarity.
• replay_mutation / mutation_diff_size: db argument dropped — functions now open their own DB connection.
• run(): timeout is now a required argument (no default None) to prevent accidental unbounded waits.
• patch(): Variable l renamed to ln (ruff E741 fix). Context-line validation intentionally not enforced (diffs are against ast.unparse canonical form, not original source).
• ForceConditional: Now covers while, assert, and ternary (IfExp) nodes, not just if.
• MutateIterator: Now handles AsyncFor in addition to For.
• MutateExceptionHandler: Class header was missing (orphaned methods at module scope) — restored.
• Progress.update(): Added delta parameter to reduce terminal noise on large runs.
• Import cleanup: Removed unused functools, itertools, from ast import Constant, from uuid import UUID, and duplicate imports.

---

Test coverage added

24 new test functions covering:

• ForceConditional — while, assert, ternary
• MutateIterator — AsyncFor
• MutateString — docstring skipping
• StatementDrop — basic cases, skips pass/bare-expr
• DefinitionDrop — basic cases, sole-definition guard
• InjectException — subscript (string key, int key), division, guarded skip, int() call
• cli_read — 9 tests covering all edge cases

---

Makefile

• check now runs pytest tests.py + ruff check (was: running mutation play on foobar)
• check-with-coverage now covers mutation module (was: foobar)
• check-survivors command fixed: uses --exclude="foobar/test*.py" to avoid treating test files as source
• Added targets: lint, doc, clean, todo, xxx, serve, wip

---

CI (.github/workflows/ci.yml)

• Added GitHub Actions workflow (was absent in origin/main)
• Steps: uv sync → ruff check → check-fail-fast → check-with-coverage → check-survivors
• check-survivors runs with continue-on-error: true — survivors are expected and should not block CI

---

foobar/ example project

• foobar/ex.py: Added a dead-code branch (untested no_op function) to demonstrate DefinitionDrop
• foobar/tests.py: Added one additional assertion