KiCadRoutingTools

#!/usr/bin/env python3
"""Mutation battery for #711 / #712 / #706.

Green tests are not evidence of coverage. Every row below breaks one thing the
three test files CLAIM to hold down; a row that survives is a hole in the
tests, and a row recorded as an expected survivor is a finding rather than a
convenience.

    python3 tests/mutate_711.py            # every row
    python3 tests/mutate_711.py --list
    python3 tests/mutate_711.py --row conjunct-never-fires

A row is KILLED by a FAILURE or by an ERROR. An anchor that does not match
EXACTLY ONCE is reported BROKEN, never skipped: a mutation that silently
edited nothing would be recorded as a surviving row, which is the opposite of
what it means.

Refuses to start on a dirty target tree, because it restores the ORIGINAL text
from disk and would write committed text over uncommitted work.

THE MEASURED TABLE GOES IN THE HEADER OF THE TEST FILE IT DEFENDS, FROM THE
RUN -- never predicted here and never edited afterwards to match.
"""
import argparse
import os
import subprocess
import sys

REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

KILLED, SURVIVED, BROKEN = 'KILLED', 'SURVIVED', 'BROKEN'

TARGETS = {
    'fp': os.path.join(REPO, 'py_placer', 'placement', 'floorplan.py'),
    'sd': os.path.join(REPO, 'py_placer', 'placement', 'seeder.py'),
    'db': os.path.join(REPO, 'py_placer', 'placement', 'design_brief.py'),
    'cb': os.path.join(REPO, 'py_router', 'copy_board.py'),
}

T712 = 'tests/test_712_edge_centering.py'
T711 = 'tests/test_711_design_brief.py'
T706 = 'tests/test_706_seat_edge_target.py'
TSIB = 'tests/test_711_sibling_lists.py'
TSCH = 'tests/test_549_floorplan_schema.py'

#: (name, target, old, new, tests, expected)
ROWS = [
    # ---- #712: the grade -------------------------------------------------
    ('conjunct-never-fires', 'fp',
     "    centre_claim = c.get('center_on_edge')",
     "    return\n    centre_claim = c.get('center_on_edge')",
     (T712,), KILLED),
    ('measure-only-when-declared', 'fp',
     "    ctx.edge_seating.append(row)\n    if not declared:",
     "    if declared:\n        ctx.edge_seating.append(row)\n    if not declared:",
     (T712,), KILLED),
    ('centring-has-a-default-threshold', 'fp',
     "    declared = centre_claim is not None or band_claim is not None",
     "    declared = True\n    centre_claim = centre_claim or {'tolerance_mm': 1.0}",
     (T712,), KILLED),
    ('offset-loses-its-sign', 'fp',
     "    offset = centre - (lo + span / 2.0)",
     "    offset = abs(centre - (lo + span / 2.0))",
     (T712,), KILLED),
    ('no-outside_mm-for-the-repair-census', 'fp',
     "                          'outside_mm': round(abs(offset) - tol, 4)},",
     "                          },",
     (T712,), KILLED),

    # ---- #712: the span basis -------------------------------------------
    ('span-always-bbox', 'fp',
     "    rings = list(getattr(gate, 'rings', None) or [])\n    if rings:",
     "    rings = []\n    if rings:",
     (T712,), KILLED),
    ('abstain-never-fires', 'fp',
     "    if outline.get('simple_rectangle') and not outline.get('cutouts'):",
     "    if True:",
     (T712,), KILLED),
    ('split-runs-accepted-as-one', 'fp',
     "        if len(merged) != 1:",
     "        if False:",
     (T712,), KILLED),
    ('claim-with-no-edge-infers-one', 'fp',
     "    edge = c.get('edge')\n    if not edge:",
     "    edge = c.get('edge') or _nearest_edge(part.rect, ctx.outline_bounds)\n    if not edge:",
     (T712,), KILLED),

    # ---- #712: the schema ------------------------------------------------
    ('both-along-edge-forms-allowed', 'fp',
     "    if centre is not None and band is not None:",
     "    if False:",
     (TSCH, T712, T711), KILLED),
    ('tolerance_mm-gets-a-default', 'fp',
     "        if 'tolerance_mm' not in centre:",
     "        centre.setdefault('tolerance_mm', 1.0)\n        if False:",
     (TSCH, T712), KILLED),
    ('inverted-band-accepted', 'fp',
     "        if not f0 < f1:",
     "        if False:",
     (TSCH, T712, T711), KILLED),
    # RE-ANCHORED for #837 (2 -> 3) and again for #902 (3 -> 4). The mutation
    # is restated rather than transliterated each time: it must move the
    # version BELOW the one #712's fields need, so `5 -> 4` would be a bump
    # merely smaller rather than absent -- a row that could survive for the
    # wrong reason. `5 -> 1` is the same claim the row has always made.
    # RE-ANCHORED for #893, which took READER_VERSION 4 -> 5, #959
    # (#1000), which took it 5 -> 6, and #1051, which took it 6 -> 7.
    ('reader-version-not-bumped', 'fp',
     "READER_VERSION = 7",
     "READER_VERSION = 1",
     (TSCH, T712), KILLED),

    # ---- #711: the brief -------------------------------------------------
    ('board-brief-accepted-as-a-design-brief', 'db',
     "    if kind != KIND:",
     "    if False:",
     (T711,), KILLED),
    ('height-silently-accepted', 'db',
     "    for bad, why in sorted(_REFUSED_TOP_LEVEL.items()):",
     "    for bad, why in sorted({}.items()):",
     (T711,), KILLED),
    ('duplicate-interface-allowed', 'db',
     "        if ref in seen_refs:",
     "        if False:",
     (T711,), KILLED),
    ('unknown-edge-becomes-a-claim', 'db',
     "        elif edge == UNKNOWN:",
     "        elif edge == UNKNOWN and False:",
     (T711,), KILLED),
    ('unknown-and-absent-collapse', 'db',
     "    absent = [k for k in _TIER0",
     "    absent = [] or [k for k in ()",
     (T711,), KILLED),
    ('inferred-outranks-declared', 'db',
     "        base.update({k: v for k, v in c.items() if k != 'context'})",
     "        base.update({k: v for k, v in c.items()\n                     if k != 'context' and k not in base})",
     (T711,), KILLED),
    ('evidence-dropped-on-merge', 'db',
     "        base = by_ref.get(ref)\n        if base is None:",
     "        base = dict(c) if by_ref.get(ref) else None\n        if base is None:",
     (T711,), KILLED),
    ('absent-ref-silently-dropped', 'db',
     "            unmatched.append(ref)\n        conns.append(entry)",
     "            unmatched.append(ref)\n            continue\n        conns.append(entry)",
     (T711,), KILLED),
    ('fixed-becomes-must_lock', 'db',
     "    if wrote_along_edge:",
     "    fragment['must_lock'] = [f['ref'] for f in brief.fixed]\n    if wrote_along_edge:",
     (T711,), KILLED),
    ('min_reader-written-always', 'db',
     "    if wrote_along_edge:\n        # The first real use",
     "    if True:\n        # The first real use",
     (T711,), KILLED),
    ('a-corrupt-sibling-is-swallowed', 'db',
     "    except (OSError, ValueError) as exc:\n        raise BriefError(f\"cannot read design brief {path}: {exc}\") from None",
     "    except (OSError, ValueError):\n        return empty_brief()",
     (T711,), KILLED),

    # ---- #711: the sibling list -----------------------------------------
    ('brief-not-carried-by-siblings', 'cb',
     '                ".design-brief.json")',
     '                )',
     (TSIB, T711), KILLED),

    # ---- #706: the seat --------------------------------------------------
    ('seat-ignores-the-declaration', 'sd',
     '        if declared is not None:',
     '        if False:',
     (T706,), KILLED),
    ('declared-window-not-clamped', 'sd',
     '        if win is not None:',
     '        if False:',
     (T706,), KILLED),
    ('origin-centre-currency-error', 'sd',
     '    origin_pos = centre_pos - _centre_offset_mm(part, edge)',
     '    origin_pos = centre_pos',
     (T706,), KILLED),
    ('ladder-not-scaled-to-the-window', 'sd',
     '        step = ((f_hi - f_lo) / 0.8) if win is not None else 1.0',
     '        step = 1.0',
     (T706,), KILLED),
    ('rotation-gate-open-to-undeclared', 'sd',
     "    if declared is not None and not _already_on_its_edge(state, part):",
     "    if not _already_on_its_edge(state, part):",
     (T706,), KILLED),
    ('rotation-guard-deleted', 'sd',
     "    if declared is not None and not _already_on_its_edge(state, part):",
     "    if declared is not None:",
     (T706,), KILLED),
    ('rotation-note-reads-the-new-angle', 'sd',
     'own rotation {was_rot:g}deg',
     'own rotation {part.rot:g}deg',
     (T706,), KILLED),
    # Stage 1 carries the declaration TWICE, and the two are not equivalent.
    # `_dec` sets the preferred start; the window clamp bounds the result.
    # Measured on splitflap_driver J17 with `center_on_edge {0.5}`: both live
    # -> x 121.92, the declared CENTRE; `_dec` killed -> 121.42, the near
    # EDGE of the window, 0.500mm out; the window killed -> 121.92 again,
    # because `_dec` alone already names the centre; BOTH killed -> 91.44,
    # frac 1/3, the even distribution.
    #
    # So the start is load-bearing and the window is the redundant one -- the
    # opposite of what an earlier version of this comment recorded, which
    # survived only because the test's bound was exactly the offset the
    # mutation produced.
    ('stage-one-ignores-the-declared-start', 'sd',
     "            _dec = _declared_frac(c)",
     "            _dec = None",
     (T706,), KILLED),
    ('stage-one-drops-the-declared-window', 'sd',
     "            if _win is not None:",
     "            if False:",
     (T706,), SURVIVED),
    # The pair TOGETHER is load-bearing, and this is the row that proves it.
    # Measured on splitflap_driver with two declared north connectors and
    # `center_on_edge {tolerance_mm: 1.0}` on J17: both paths live -> x
    # 121.92 (the centre); BOTH disabled -> x 91.44, which is frac 1/3, the
    # even distribution. Either one alone still lands on the centre, which is
    # why the two rows above are recorded survivors rather than deleted: they
    # say WHICH redundancy exists, and this row says the redundancy is not
    # dead code.
    ('stage-one-ignores-the-declaration-entirely', 'sd',
     "            _dec = _declared_frac(c)",
     "            c = {k: v for k, v in c.items() "
     "if k not in ('center_on_edge', 'along_edge_band')}; "
     "_dec = _declared_frac(c)",
     (T706,), KILLED),
]

# Every anchor must match its target exactly once BEFORE anything is
# rewritten. A stale anchor otherwise reports BROKEN mid-run, after the
# witnesses have been paid for; this is the one second (#877).
from mutation_anchors import preflight   # noqa: E402
preflight(__file__)


def _clear_pycache():
    """Delete every `__pycache__` under the repo.

    NOT optional, and not paranoia. Measured on this battery's own first run:
    the `reader-version-not-bumped` row rewrites `READER_VERSION = 2` as
    `READER_VERSION = 1` -- the SAME NUMBER OF BYTES -- and CPython's import
    cache keys on (mtime, size). Restoring the original within the same
    filesystem timestamp granularity left a `.pyc` compiled from the MUTANT,
    and every later import in the session read `READER_VERSION == 1` from a
    tree whose source said 2. A row can then be "killed" by the previous
    row's leftovers rather than by its own edit, which makes the whole table
    a fiction.
    """
    import shutil
    for dirpath, dirnames, _ in os.walk(REPO):
        if '.git' in dirpath:
            continue
        for d in list(dirnames):
            if d == '__pycache__':
                shutil.rmtree(os.path.join(dirpath, d), ignore_errors=True)
                dirnames.remove(d)


def _dirty(paths):
    r = subprocess.run(['git', 'diff', '--quiet', '--'] + list(paths),
                       cwd=REPO)
    return r.returncode != 0


def _run(tests):
    for t in tests:
        r = subprocess.run([sys.executable, '-X', 'utf8', t], cwd=REPO,
                           capture_output=True, encoding='utf-8',
                           errors='replace', timeout=1800)
        if r.returncode != 0:
            return KILLED, f"{t} exit {r.returncode}"
    return SURVIVED, ''


def main(argv=None):
    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
    ap.add_argument('--row', action='append')
    ap.add_argument('--list', action='store_true')
    a = ap.parse_args(argv)

    rows = ROWS
    if a.row:
        want = set(a.row)
        rows = [r for r in ROWS if r[0] in want]
        missing = want - {r[0] for r in rows}
        if missing:
            print(f"unknown row(s): {sorted(missing)}", file=sys.stderr)
            return 2
    if a.list:
        for name, tgt, _, _, tests, exp in ROWS:
            print(f"  {name:42s} {tgt}  expect {exp}  ({', '.join(tests)})")
        return 0

    used = sorted({TARGETS[r[1]] for r in rows})
    if _dirty(used):
        print("REFUSING: the target tree is dirty. This restores the ORIGINAL "
              "text from disk and would write committed text over uncommitted "
              "work.", file=sys.stderr)
        return 2

    results = {}
    for name, tgt, old, new, tests, expected in rows:
        path = TARGETS[tgt]
        # `raw` restores byte-exactly; `src` is universal-newline TEXT, so a
        # multi-line anchor written with a bare newline matches a CRLF file.
        # Matching on the raw byte decode silently found NOTHING in three
        # rows -- which the battery reported as BROKEN rather than as three
        # surviving mutations, and that is exactly why an anchor which misses
        # is an error here and not a skip.
        raw = open(path, 'rb').read()
        with open(path, encoding='utf-8') as _fh:
            src = _fh.read()
        n = src.count(old)
        if n != 1:
            results[name] = (BROKEN, f"anchor matched {n} times, expected 1")
            print(f"  {name:42s} BROKEN  (anchor matched {n} times)")
            continue
        try:
            with open(path, 'w', encoding='utf-8') as _fh:
                _fh.write(src.replace(old, new, 1))
            _clear_pycache()
            verdict, why = _run(tests)
        finally:
            # BYTE-EXACT, from the bytes read: a text round trip normalises
            # line endings and leaves every target permanently "modified",
            # which then trips this battery's own dirty-tree refusal.
            open(path, 'wb').write(raw)
            _clear_pycache()
        results[name] = (verdict, why)
        mark = 'ok ' if verdict == expected else 'DISAGREES'
        print(f"  {name:42s} {verdict:9s} {mark}  {why}")

    killed = sum(1 for v, _ in results.values() if v == KILLED)
    surv = sum(1 for v, _ in results.values() if v == SURVIVED)
    broken = sum(1 for v, _ in results.values() if v == BROKEN)
    disagree = [n for n, (v, _) in results.items()
                if v != dict((r[0], r[5]) for r in rows)[n]]
    print(f"\n{len(results)} rows: {killed} killed, {surv} survived, "
          f"{broken} broken, {len(disagree)} disagreeing with expectation")
    if disagree:
        print(f"  disagreeing: {sorted(disagree)}")
    return 1 if (broken or disagree) else 0


if __name__ == '__main__':
    sys.exit(main())