#!/usr/bin/env python3 """Mutation tests for docs/stats-and-power-cut.md Cut 4 (all draw is continuous -- input capacitors). Cut 4 closes Cut 3's named, temporary exception for the four instant draws (a burst, a shot, a ping, a hit taken): each now spends from its own InputCapacitor, fed continuously by PowerBus like every other consumer, instead of the entity's shared bus capacitors directly through the now-deleted Entity.TrySpendCapacitorCharge/CanSpendCapacitorCharge. This script mutates each rule's own line of code and asserts the named test in InputCapacitorTests.cs goes red for exactly that reason. A no-op control mutation proves the read/replace/restore path is transparent. Usage: python tests/mutation_tests_stats_power_cut4.py --cultlib-root Only touches files under this repository; every mutation is reversed before the script exits, including on failure. """ from __future__ import annotations import argparse import subprocess import sys from dataclasses import dataclass from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent TEST_PROJECT = REPO_ROOT / "tests" / "Aetheria.Shared.Tests" @dataclass class Mutation: rule: str file: str anchor: str mutated: str test: str expect: str # "red" (mutant must be killed) or "green" (the no-op control) MUTATIONS: list[Mutation] = [ # --- No-op control: proves the anchor/replace/restore mechanism is transparent --- Mutation( rule="control (no-op round trip)", file="Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs", anchor=" public void AddCharge(float amount) => Charge = clamp(Charge + amount, 0f, Capacity);", mutated=" public void AddCharge(float amount) => Charge = clamp(Charge + amount, 0f, Capacity);", test="InputCapacitorTests.AddChargeNeverExceedsCapacity", expect="green", ), # --- AddCharge must clamp to Capacity: an input capacitor is sized to exactly one activation, so nothing # --- (a rounding surplus, a Capacity that shrank after charge had already banked) may ever report more # --- charge than one activation could use. --- Mutation( rule="AddCharge must clamp to Capacity", file="Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs", anchor=" public void AddCharge(float amount) => Charge = clamp(Charge + amount, 0f, Capacity);", mutated=" public void AddCharge(float amount) => Charge = Charge + amount;", test="InputCapacitorTests.AddChargeNeverExceedsCapacity", expect="red", ), # --- TrySpend must refuse before moving anything it cannot fully cover -- the exact atomicity contract # --- Entity.TrySpendCapacitorCharge had, now scoped to one behaviour's own buffer. Deleting the upfront # --- check restores the old TryConsumeEnergy-class bug: a cost this buffer cannot fully pay would still # --- partially drain it. --- Mutation( rule="TrySpend must refuse before spending anything it cannot fully cover", file="Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs", anchor=( " if (cost < .01f) return true;\n" " if (!CanSpend(cost)) return false;" ), mutated=" if (cost < .01f) return true;", test="InputCapacitorTests.TrySpendMovesNothingWhenTheCostCannotBeFullyCovered", expect="red", ), # --- Default rate derives from Capacity/cooldown (Q4 ruling: "derived from energy and cooldown"). Dropping # --- the division collapses the derived rate to Capacity itself (refill in 1 second regardless of the # --- weapon's own cooldown), which RateOverrideReplacesTheDerivedDefault pins directly. --- Mutation( rule="the default rate must derive from Capacity/cooldown, not just Capacity", file="Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs", anchor=" Rate = rateOverride > 0f ? rateOverride : (cooldown > 0f ? Capacity / cooldown : Capacity);", mutated=" Rate = rateOverride > 0f ? rateOverride : Capacity;", test="InputCapacitorTests.RateOverrideReplacesTheDerivedDefault", expect="red", ), # --- Cut 4's own verification bullet: "a weapon whose input capacitor is partly filled does not fire a # --- partial shot." A fire attempt must spend exactly Capacity -- never a lesser, possibly-partial amount # --- -- so it only ever succeeds at full charge. Spending 0 instead bypasses the whole-shot requirement: # --- every attempt would "succeed" regardless of charge. --- Mutation( rule="a fire attempt must spend exactly Capacity, never a lesser amount", file="Assets/Scripts/ServerShared/Behaviors/InstantWeapon.cs", anchor=" protected bool TrySpendActivationEnergy() => Item == null || _capacitor.TrySpend(_capacitor.Capacity);", mutated=" protected bool TrySpendActivationEnergy() => Item == null || _capacitor.TrySpend(0f);", test="InputCapacitorTests.WeaponDoesNotFireOnAPartialCharge", expect="red", ), # --- The other half of the same rule, at the fill site instead of the spend site: the capacitor must only # --- ever bank the fraction PowerBus actually granted (Item.PowerSupply), never the whole request # --- regardless of supply -- otherwise a weapon on half power would still reach full charge (and fire) on # --- the very first tick, exactly the "every draw succeeds" bug Cut 3 exists to remove, just relocated. --- Mutation( rule="the capacitor must only bank the fraction PowerBus actually granted, not the whole request", file="Assets/Scripts/ServerShared/Behaviors/InstantWeapon.cs", anchor=" _capacitor.AddCharge(_capacitor.RequestedFill(dt) * Item.PowerSupply);", mutated=" _capacitor.AddCharge(_capacitor.RequestedFill(dt));", test="InputCapacitorTests.WeaponDoesNotFireOnAPartialCharge", expect="red", ), # --- Shield is the map's named exception: a hit is not a chosen activation, so its reserve is a continuous # --- one that may absorb an arbitrary fraction of a hit's cost, unlike a weapon's shot (always spent # --- whole). Requiring a hit to cover the WHOLE reserve before absorbing anything collapses that # --- distinction back into an activation buffer, which the map explicitly says not to give it. # --- # --- F8 (docs/stats-and-power-cut.md, Soul pass 2026-09-19) re-anchor: the shield reserve ruling # --- (2026-09-19) gave Shield a Broken state, splitting CanTakeHit's old single-expression body # --- (`return Item == null || _reserve.CanSpend(...)`) into an Item-null check, a Broken check, and this # --- CanSpend call as its own line; F5 (the same Soul pass) then made the whole method a pure query. The # --- rule under test -- CanSpend reads the hit's own cost, not a full-reserve requirement -- is unchanged # --- and still reachable from this same line. --- Mutation( rule="the shield reserve must allow a partial draw, not require a full reserve before absorbing a hit", file="Assets/Scripts/ServerShared/Behaviors/Shield.cs", anchor=" return _reserve.CanSpend(damage * EnergyUsage);", mutated=" return _reserve.CanSpend(_reserve.Capacity);", test="InputCapacitorTests.ShieldReserveAllowsAPartialDrawButRefusesAHitItCannotFullyCover", expect="red", ), ] def replace_unique(path: Path, anchor: str, mutated: str) -> None: original = path.read_text(encoding="utf-8") count = original.count(anchor) if count != 1: raise SystemExit(f"{path}: anchor must occur exactly once, found {count}\n---\n{anchor}") path.write_text(original.replace(anchor, mutated), encoding="utf-8") def run_test(cultlib_root: str, test: str) -> tuple[int, str]: proc = subprocess.run( ["dotnet", "test", str(TEST_PROJECT), f"-p:CultLibRoot={cultlib_root}", "--filter", f"FullyQualifiedName~{test}"], capture_output=True, text=True, timeout=300, ) return proc.returncode, proc.stdout + proc.stderr def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--cultlib-root", required=True) args = parser.parse_args() failures: list[str] = [] originals: dict[str, str] = {} for m in MUTATIONS: if m.file not in originals: originals[m.file] = (REPO_ROOT / m.file).read_text(encoding="utf-8") def restore_all() -> None: for file, text in originals.items(): (REPO_ROOT / file).write_text(text, encoding="utf-8") try: for m in MUTATIONS: print(f"\n=== {m.rule} (expect {m.expect}) ===") path = REPO_ROOT / m.file replace_unique(path, m.anchor, m.mutated) code, output = run_test(args.cultlib_root, m.test) passed = "Passed!" in output and code == 0 if m.expect == "green": if not passed: failures.append(f"{m.rule}: expected green (test passing), got failure\n{output[-2000:]}") else: print(f"OK: {m.test} passed under a no-op mutation, as expected") else: if passed: failures.append(f"{m.rule}: expected red (mutant killed), but {m.test} still passed") else: print(f"OK: {m.test} went red under the mutation, as expected") # Restore this file immediately so the next mutation starts from a clean tree. path.write_text(originals[m.file], encoding="utf-8") finally: restore_all() if failures: print("\n=== FAILURES ===") for f in failures: print(f"- {f}") return 1 print("\nAll mutations behaved as declared.") return 0 if __name__ == "__main__": sys.exit(main())