loopgate 0.1.0__py3-none-any.whl

mutation/check_mutmut.py

@@ -0,0 +1,163 @@
+"""FAIL CI WHEN MUTMUT'S AGGREGATE EXPORT CONTAINS TEST GAPS.
+
+Mutation testing mutates the source code, e.g. a boolean flips, a constant shifts, a comparison widens.
+A mutant that dies proves a test assertion was working on that line. A mutant that SURVIVES is a variant of
+source code that shows tests execute (i.e. test coverage is met there) BUT the test is flimsy:
+has weak assertions, overly-mock, happy path only, missing edge cases, no real assert in test, weak logic.
+
+i.e. Mutmut tests the tests. Mutmut breaks source then runs test suite. If test fails, the break was noticed,
+a mutated source code variant is "killed." If every test passes after mutation the break went unnoticed,
+mutant code variant "survived".
+
+Mutmut docs: https://mutmut.readthedocs.io/
+    mutmut run       # generate mutants and run the test suite against all source code + its mutants
+    mutmut browse    # TUI over the survivors
+    mutmut results   # plain-text summary
+
+Config in pyproject.toml [tool.mutmut]
+
+Each mutant variant has a name, e.g. tests.test_file.x_lazy_assert__mutmut_2. Mutmut records mutant as killed
+or survived before you inspect, and re-uses variant until source code changes.
+
+CASE:
+- best: 100% test coverage, run mutmut -> many mutations, none survive, nothing for you to kill
+(tests are strongly sensitive to change)
+- good: <100% coverage, run mutmut -> many mutations, none survive, you have to hunt some
+(the tests that exist are good but you miss coverage)
+- worst: 100% coverage, run mutmut -> many mutations, ALL survive + no easy kills
+(there are many low quality tests)
+- realistic: run mutmut, some mutants created, some survive, you find some to kill
+
+PROCESS:
+
+1. Run mutmut: mutations appear / are killed
+2. Inspect: You look at surviving mutations
+3. Test Update: You add or improve test assertions
+4. Re-run: You ensure the mutant is killed
+
+5. Updating Source Code
+- Dead Code
+Sometimes a mutant survives because source code is redundant, e.g. If changing a line doesn't break a test,
+ask if that code is needed. Maybe delete the useless code instead of writing tests.
+- Surviving Mutants
+You do not need to reach zero mutants, e.g. if changing source effects performance negatively, message output
+would change, equivalent code swap e.g. i < 10 => i != 10
+
+Locally you can run `mutmut run` to generate mutants. Your test suite must be green.
+Then `mutmut export-cicd-stats` to get a report.
+Run *this* script to use that report to get a score and badge-capable score for your README.
+```
+> mutmut run
+⠼ Generating mutants
+    done in 2457ms (6 files mutated, 7 ignored, 0 unmodified)
+⠧ Running stats
+    done
+⠼ Running clean tests
+    done
+⠏ Running forced fail test
+    done
+Running mutation testing
+⠼ 1434/1434  🎉 1207 🫥 0  ⏰ 1  🤔 0  🙁 226  🔇 0  🧙 0
+5.28 mutations/second
+> mutmut export-cicd-stats
+Saved CI/CD stats to mutants/mutmut-cicd-stats.json
+> python mutation/check_mutmut.py  # writes `mutation-score.json` in the format Shields expects and prints:
+
+───────────────MUTMUT MUTATION RESULTS ───────────────
+
+            killed                          1207
+            survived                        226
+            total                           1434
+            no_tests                        0
+            skipped                         0
+            suspicious                      0
+            timeout                         1
+            check_was_interrupted_by_user   0
+            segfault                        0
+            Mutation Score:                84.2
+
+Add to README:
+[![mutation](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/BRANCH/
+mutation-score.json)](https://github.com/OWNER/REPO/blob/BRANCH/mutation-score.json)
+
+> git commit && git push
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from rich import print as rprint
+from rich.console import Console
+from rich.table import Table
+
+console = Console(force_terminal=True, color_system=None if os.environ.get("RALPH_LOOP") else "auto")
+
+MINIMUM_MUTATION_SCORE = 60.0  # increase over time
+
+
+def update_mutation_score() -> float:
+    """Read the Mutmut report and write the latest repository mutation score.
+
+    Returns:
+        Latest calculated mutation score.
+    """
+    stats_report_path = Path("mutants/mutmut-cicd-stats.json")
+    badge_score = Path("mutation-score.json")
+    if not stats_report_path.exists():
+        repo_root = Path(__file__).resolve().parents[1]
+        stats_report_path = repo_root / stats_report_path
+        badge_score = repo_root / badge_score
+    mutation_score = analyze_mutmut_report_passed(str(stats_report_path))
+    badge = {"schemaVersion": 1, "label": "mutation", "message": f"{mutation_score:.1f}%", "color": "#177445"}
+    badge_score.write_text(json.dumps(badge, indent=4) + "\n", encoding="utf-8")
+    return mutation_score
+
+
+def analyze_mutmut_report_passed(file_path: str = "mutants/mutmut-cicd-stats.json") -> float:
+    """Read the mutmut CI JSON results created each Sunday night.
+
+    Args:
+        file_path (str): Default filepath to read mutmut run stats from.
+
+    Returns:
+        mutation_score: float value, killed + timeout mutants as a% of all
+
+    Raises:
+        JSONDecodeError: If the report does not contain valid JSON.
+    """
+    mutation_score: float = 0.0
+    if not Path(file_path).exists():
+        rprint(f"[bold red]Mutmut report not at {file_path}[/]:\nRun `mutmut run && mutmut export-cicd-stats`")
+        return mutation_score
+    data: dict[str, int] = {}
+    with Path(file_path).open("r", encoding="utf-8") as fp:
+        try:
+            data = json.load(fp)
+        except json.JSONDecodeError:
+            rprint(rf"[red]JSONDecodeError [/]'{file_path}'")
+            raise
+
+    total_mutants = data.get("total", 0)
+    skipped = data.get("skipped", 0)
+    tested_mutants = total_mutants - skipped
+    if tested_mutants > 0:
+        killed = data.get("killed", 0)
+        timeout = data.get("timeout", 0)
+        mutation_score = ((killed + timeout) / tested_mutants) * 100
+
+    console.rule("[bold cyan]MUTMUT MUTATION RESULTS[/]", style="blink cyan on grey15")
+    table = Table(box=None)
+    for stat, result in data.items():
+        table.add_row(f"[dim]{stat}[/]", f"[blue] {result}[/]")
+    table.add_row("[cyan]Mutation Score:[/]", f"[dim yellow2]{mutation_score:.1f}[/]")
+    console.print(table, justify="center")
+
+    return mutation_score
+
+
+if __name__ == "__main__":
+    if update_mutation_score() < MINIMUM_MUTATION_SCORE:
+        raise SystemExit(1)

preferences/preferences.py

@@ -0,0 +1,306 @@
+"""AST-based structural style checks for staged Python files.
+
+OPTIONAL for humans to use or edit! The functions below are examples to use. Or delete.
+
+Agents in the loop cannot edit this file. It's in `FORBIDDEN_DIRS` at `harness/gate.py`.
+
+This module should reflect the repo owner's personal coding style hates. It's personal.
+e.g. indiscriminate __underscore_names, **star-unpacking, pointless classes, loops instead of Set math.
+
+Use this file ONLY for rules that ruff, pylint, and pyright cannot express but you want enforced. Keep short.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Callable
+
+# A check looks at ONE AST node and returns a complaint or None if the node is fine.
+# It never walks the tree. root preferences_violations does the walk and feeds nodes to functions.
+Check = Callable[[ast.AST], "str | None"]
+
+
+def is_in_class(node: ast.AST) -> bool:
+    """Checks if ode is inside a class
+
+    Args:
+        node: The node in question to check, is it in a class?
+
+    Returns:
+        bool True is in class, else False
+    """
+    current = getattr(node, "parent", None)
+    while current:
+        if isinstance(current, ast.ClassDef):
+            return True
+        current = getattr(current, "parent", None)
+    return False
+
+
+def chaotic_continue_statements(node: ast.AST) -> str | None:
+    """Catch continue statements that are hard to follow: inside a while loop, or buried two or more
+    if/for blocks deep. A single `if` guard directly inside a loop is fine -- that is normal Python.
+
+    Example:
+        for x in xs:              -> fine: a plain continue in its loop
+            continue
+        for x in xs:              -> flagged: two `if` blocks deep
+            if a:
+                if b:
+                    continue
+        for x in xs:              -> flagged: nested loops
+            for y in ys:
+                continue
+        while cond:               -> flagged: any continue in a while loop (freeze risk)
+            continue
+
+    Args:
+        node: One piece of the parsed code to look at.
+
+    Returns:
+        A short message if the continue is in a while loop or over-nested, otherwise None.
+    """
+    # Ban continue inside while loops to prevent infinite freezes.
+    if isinstance(node, ast.While) and any(isinstance(child, ast.Continue) for child in ast.walk(node)):
+        return "'continue' inside a while loop banned to prevent infinite freezes"
+    # Only continue statements can be over-nested; a guard here keeps the walk below un-nested.
+    if not isinstance(node, ast.Continue):
+        return None
+    # A continue is over-nested when it sits two or more if/for blocks deep. One 'if' guard directly
+    # inside its loop (the common `for ...: if ...: continue`) is fine; anything deeper is not.
+    blocks: list[str] = []
+    ancestor = getattr(node, "parent", None)
+    while ancestor is not None:
+        if isinstance(ancestor, ast.If | ast.For | ast.While):
+            blocks.append(type(ancestor).__name__)
+        ancestor = getattr(ancestor, "parent", None)
+    # Every continue needs one enclosing loop; a single 'if' above that loop is still fine.
+    if len(blocks) >= 2 and blocks not in (["If", "For"], ["If", "While"]):
+        return "Overly-nested 'continue' detected inside multiple if/for blocks"
+    return None
+
+
+def lazy_any_type_hints(node: ast.AST) -> str | None:
+    """Catch agents using 'Any' to escape strict type checks.
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the arg is annotated `Any`/`typing.Any`, else None.
+    """
+    if isinstance(node, ast.arg) and node.annotation:
+        item_is_any = isinstance(node.annotation, ast.Name) and node.annotation.id == "Any"  # matches Any
+        uses_typing_dot_any = (
+            isinstance(node.annotation, ast.Attribute)
+            and isinstance(node.annotation.value, ast.Name)
+            and node.annotation.value.id == "typing"
+            and node.annotation.attr == "Any"
+        )  # matches typing.Any
+        if item_is_any or uses_typing_dot_any:
+            return f"Lazy 'Any' type hint detected for argument '{node.arg}'"
+    return None
+
+
+def lambda_found(node: ast.AST) -> str | None:
+    """Catches all lambdas. Ruff E731 only flags lambdas directly assigned to a variable name.
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the node is a lambda, else None.
+    """
+    if isinstance(node, ast.Lambda):
+        return "Lambda found hurting readability and adding complexity, prefer map() or filter()"
+    return None
+
+
+def named_with_underscore_and_not_in_class_or_dunder(node: ast.AST) -> str | None:
+    """A def, arg, or assignment target starts with '_' and is not in a class object.
+
+    The conventional discard name ``_`` is exempt.
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the name has a prohibited leading underscore, else None.
+    """
+    if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+        name = node.name
+    elif isinstance(node, ast.arg):
+        name = node.arg
+    elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+        name = node.id
+    else:
+        return None
+    if name.startswith("__") and not name.endswith("__"):
+        return f"Name '{name} starts with a dunder, rename it"
+    if name != "_" and name.startswith("_") and not name.endswith("__") and not is_in_class(node):
+        return f"Name '{name}' starts with underscore and is not in a class"
+
+    return None
+
+
+def hidden_signature_star_args(node: ast.AST) -> str | None:
+    """Reject function definitions that use *args, **kwargs, a bare *, or /.
+
+    Example:
+        def send(*args, **kwargs): ...  -> flagged
+        def send(a, *, b): ...          -> flagged
+        def send(a, /, b): ...          -> flagged
+        def send(a, b): ...             -> fine
+
+    Args:
+        node: One piece of the parsed code to look at.
+
+    Returns:
+        A complaint if the definition uses *args, **kwargs, a bare *, or /, otherwise None.
+    """
+    if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and (
+        node.args.vararg or node.args.kwarg or node.args.kwonlyargs or node.args.posonlyargs
+    ):
+        return "'*args', '**kwargs', '*', and '/' hide the function signature, use explicit parameters"
+    return None
+
+
+def dynamic_star_call(node: ast.AST) -> str | None:
+    """Do not spread a variable in a call's arguments with *, e.g. f(*items).
+
+    When you write f(*items), you can't tell how many arguments f is really getting, and the call breaks
+    if the list is the wrong length. Spreading a list or tuple written out right there, like f(*[1, 2, 3]),
+    is fine because its length is plain to see. A variable, or a list that spreads something else inside
+    it like f(*[1, *items]), is not.
+
+    We only look at '*', not '**'. Keyword unpacking like f(**opts) is a normal, readable Python idiom
+    (passing config through, or super().__init__(**kwargs)), and the one wasteful case, f(**{"a": 1}),
+    is already caught by ruff's PIE804. Positional '*' is the riskier one: the wrong length is a crash.
+
+    Example:
+        f(*items)        -> flagged: 'items' could be any length
+        f(*[1, *items])  -> flagged: the list grows with 'items'
+        f(*[1, 2, 3])    -> fine: exactly three arguments always
+        f(**kwargs)      -> left alone on purpose: keyword unpacking is a normal, readable pattern
+
+    Args:
+        node: One piece of the parsed code to look at.
+
+    Returns:
+        A short message if a * argument is not a plain, fixed-length list or tuple, otherwise None.
+    """
+    if isinstance(node, ast.Call):
+        for arg in node.args:
+            # A '*' spread is fine only on a written-out list/tuple whose length you can see.
+            # A variable, or a literal that spreads something inside (like [1, *more]), hides it.
+            if isinstance(arg, ast.Starred) and not (
+                isinstance(arg.value, ast.List | ast.Tuple)
+                and not any(isinstance(element, ast.Starred) for element in arg.value.elts)
+            ):
+                return "Dynamic '*' call hides positional arguments; pass explicit arguments"
+    return None
+
+
+def pointless_class(node: ast.AST) -> str | None:
+    """A plain class with no base/decorator/keyword and at most one method. Beyond too-few-public-methods
+    R0903 because leaves classes with parents and only attacks bare classes.
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the node is such a pointless class, else None.
+    """
+    if isinstance(node, ast.ClassDef) and not (node.bases or node.keywords or node.decorator_list):
+        methods = [item for item in node.body if isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef)]
+        if len(methods) <= 1:
+            return f"'{node.name}': no base, decorator, or behavior: use function or Pydantic"
+    return None
+
+
+def lazy_assert(node: ast.AST) -> str | None:
+    """No empty checks or lazy conditions but test nothing.
+    ast.Constant catches True, False, None, 1, 0, 'pass'
+    The others catch literal list/dict/tuple structures like [] or {}
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the node is a lazy constant/literal assert, else None.
+    """
+    if isinstance(node, ast.Assert) and isinstance(node.test, (ast.Constant, ast.List, ast.Dict, ast.Tuple)):
+        return "Lazy test assertion detected"
+    return None
+
+
+def objects_injected_into_runtime_memory(node: ast.AST) -> str | None:
+    """Check ast.Call nodes to find name calls that manipulate global state.
+    Python keeps internal memory dictionary of each current variable/function. Do not allow calling globals()
+    or locals() to grab/inject variables to runtime (instead of writing e.g. a dict).
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if the node calls globals()/locals(), else None.
+    """
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in {"globals", "locals"}:
+        return "Dynamic injection of memory registry spotted"
+    return None
+
+
+def complex_comprehension(node: ast.AST) -> str | None:
+    """Use Type Set math or loops when comprehensions become complex.
+
+    Args:
+        node: The AST node under inspection.
+
+    Returns:
+        A complaint if a multi-generator comprehension also filters, else None.
+    """
+    if isinstance(node, ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp) and len(node.generators) > 1:
+        for generator in node.generators:
+            if generator.ifs:
+                return "Overly complex comprehension, use a loop or type Set math"
+    return None
+
+
+# To add a style rule: write a dumb one-node function above and register it here under its kind.
+CHECKS: dict[str, Check] = {
+    "named_with_underscore_and_not_in_class_or_dunder": named_with_underscore_and_not_in_class_or_dunder,
+    "hidden_signature_star_args": hidden_signature_star_args,
+    "dynamic_star_call": dynamic_star_call,
+    "pointless_class": pointless_class,
+    "lazy_assert": lazy_assert,
+    "objects_injected_into_runtime_memory": objects_injected_into_runtime_memory,
+    "lambda_found": lambda_found,
+    "lazy_any_type_hints": lazy_any_type_hints,
+    "chaotic_continue_statements": chaotic_continue_statements,
+    "complex_comprehension": complex_comprehension,
+}
+
+
+def preferences_violations(path: str, source: str) -> str:
+    """Run every registered check on one Python file in a single AST walk.
+
+    Args:
+        path: File path used to prefix each violation message.
+        source: Python source text to parse and walk.
+
+    Returns:
+        Violation messages string
+    """
+    violations: list[str] = []
+    tree = ast.parse(source)
+    for parent in ast.walk(tree):  # link each node to its parent so checks can inspect nesting
+        for child in ast.iter_child_nodes(parent):
+            child.__dict__["parent"] = parent  # nodes are parent->child, add parent<-child for nested checks
+    for node in ast.walk(tree):
+        lineno = getattr(node, "lineno", "?")
+        for check in CHECKS.values():
+            message = check(node)
+            if message:
+                violations.append(f"{path}:{lineno}: {message}")
+
+    return "\n".join(violations)