typemut 0.1.0__py3-none-any.whl

typemut/__init__.py

@@ -0,0 +1,3 @@
+"""typemut — Mutation testing for type annotations."""
+
+__version__ = "0.1.0"

typemut/cli.py

@@ -0,0 +1,247 @@
+"""CLI entry point for typemut."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from typemut.config import Config, load_config
+from typemut.db import Database, MutantRow
+from typemut.discovery import discover_annotations, discover_files
+
+console = Console()
+
+
+def _load(config_path: str, db_path: str | None) -> tuple[Config, Database]:
+    cfg = load_config(Path(config_path))
+    db = Database(Path(db_path or cfg.db_path))
+    return cfg, db
+
+
+@click.group()
+@click.option(
+    "-C",
+    "--project-dir",
+    default=None,
+    type=click.Path(exists=True, file_okay=False),
+    help="Change to this directory before running (target project root).",
+)
+@click.pass_context
+def main(ctx: click.Context, project_dir: str | None) -> None:
+    """typemut — Mutation testing for type annotations."""
+    import os
+
+    if project_dir:
+        os.chdir(project_dir)
+
+
+@main.command()
+@click.option("--config", "config_path", default="typemut.toml", help="Config file.")
+@click.option("--db", "db_path", default=None, help="Database file.")
+def init(config_path: str, db_path: str | None) -> None:
+    """Discover all possible mutations and store in database."""
+    cfg, db = _load(config_path, db_path)
+
+    # Import operators here to avoid circular imports
+    from typemut.registry import Registry
+    from typemut.operators import get_enabled_operators
+
+    module_dir = Path(cfg.module_path)
+    if not module_dir.exists():
+        console.print(f"[red]Module path not found: {module_dir}[/red]")
+        raise SystemExit(1)
+
+    files = discover_files(module_dir, cfg.excluded_modules)
+    console.print(f"Found [bold]{len(files)}[/bold] Python files in {module_dir}")
+
+    # Build registry from all files
+    registry = Registry.from_files(files)
+
+    operators = get_enabled_operators(cfg.operators)
+    console.print(f"Enabled operators: {', '.join(op.name for op in operators)}")
+
+    db.clear()
+    total = 0
+
+    for py_file in files:
+        annotations = discover_annotations(
+            py_file, skip_comments=cfg.skip_comments
+        )
+        mutants: list[MutantRow] = []
+
+        for ann in annotations:
+            for op in operators:
+                for mutation in op.find_mutations(ann.node, ann.context, registry):
+                    mutants.append(
+                        MutantRow(
+                            id=None,
+                            module_path=str(py_file),
+                            operator=mutation.operator,
+                            line=mutation.line,
+                            col=mutation.col,
+                            original_annotation=mutation.original,
+                            mutated_annotation=mutation.mutated,
+                            description=mutation.description,
+                        )
+                    )
+
+        if mutants:
+            db.insert_many(mutants)
+            total += len(mutants)
+
+    console.print(
+        f"[green]Found {total} type annotation mutations "
+        f"across {len(files)} modules[/green]"
+    )
+    db.close()
+
+
+@main.command("exec")
+@click.option("--config", "config_path", default="typemut.toml", help="Config file.")
+@click.option("--db", "db_path", default=None, help="Database file.")
+@click.option("--jobs", default=1, help="Number of parallel jobs.")
+def exec_cmd(config_path: str, db_path: str | None, jobs: int) -> None:
+    """Run type checker against each mutation."""
+    cfg, db = _load(config_path, db_path)
+
+    from typemut.engine import check_baseline, run_all_mutants
+
+    pending = db.get_pending()
+    if not pending:
+        console.print("[yellow]No pending mutants. Run 'typemut init' first.[/yellow]")
+        db.close()
+        return
+
+    console.print("Running baseline check...")
+    ok, output = check_baseline(cfg.test_command, cfg.timeout)
+    if not ok:
+        console.print("[red]Baseline check failed — type checker reports errors on unmodified code:[/red]")
+        console.print(output)
+        db.close()
+        raise SystemExit(1)
+    console.print("[green]Baseline clean.[/green]")
+
+    console.print(f"Running [bold]{len(pending)}[/bold] mutations...")
+    run_all_mutants(db, pending, cfg.test_command, cfg.timeout)
+    db.close()
+    console.print("[green]Done.[/green]")
+
+
+@main.command()
+@click.option("--db", "db_path", default="typemut.sqlite", help="Database file.")
+def report(db_path: str) -> None:
+    """Show mutation testing results."""
+    db = Database(Path(db_path))
+
+    from typemut.reporting.terminal import print_report
+
+    print_report(db, console)
+    db.close()
+
+
+@main.command()
+@click.option("--db", "db_path", default="typemut.sqlite", help="Database file.")
+@click.option("-o", "--output", "out_path", default=None, help="Output file (default: stdout).")
+@click.option("--open", "open_browser", is_flag=True, help="Open report in browser.")
+def html(db_path: str, out_path: str | None, open_browser: bool) -> None:
+    """Generate HTML report."""
+    db = Database(Path(db_path))
+
+    from typemut.reporting.html import generate_html
+
+    report = generate_html(db)
+    db.close()
+
+    if out_path:
+        Path(out_path).write_text(report)
+        console.print(f"Report saved to [bold]{out_path}[/bold]")
+    else:
+        out_path = "typemut-report.html"
+        Path(out_path).write_text(report)
+        console.print(f"Report saved to [bold]{out_path}[/bold]")
+
+    if open_browser:
+        import webbrowser
+        webbrowser.open(f"file://{Path(out_path).resolve()}")
+
+
+@main.command()
+@click.option("--config", "config_path", default="typemut.toml", help="Config file.")
+@click.option("--db", "db_path", default=None, help="Database file.")
+def run(config_path: str, db_path: str | None) -> None:
+    """Run full pipeline: discover mutations, execute, and report."""
+    from typemut.engine import check_baseline, run_all_mutants
+    from typemut.operators import get_enabled_operators
+    from typemut.registry import Registry
+    from typemut.reporting.terminal import print_report
+
+    cfg, db = _load(config_path, db_path)
+
+    module_dir = Path(cfg.module_path)
+    if not module_dir.exists():
+        console.print(f"[red]Module path not found: {module_dir}[/red]")
+        raise SystemExit(1)
+
+    # Init
+    files = discover_files(module_dir, cfg.excluded_modules)
+    console.print(f"Found [bold]{len(files)}[/bold] Python files in {module_dir}")
+
+    registry = Registry.from_files(files)
+    operators = get_enabled_operators(cfg.operators)
+    console.print(f"Enabled operators: {', '.join(op.name for op in operators)}")
+
+    db.clear()
+    total = 0
+
+    for py_file in files:
+        annotations = discover_annotations(py_file, skip_comments=cfg.skip_comments)
+        mutants: list[MutantRow] = []
+
+        for ann in annotations:
+            for op in operators:
+                for mutation in op.find_mutations(ann.node, ann.context, registry):
+                    mutants.append(
+                        MutantRow(
+                            id=None,
+                            module_path=str(py_file),
+                            operator=mutation.operator,
+                            line=mutation.line,
+                            col=mutation.col,
+                            original_annotation=mutation.original,
+                            mutated_annotation=mutation.mutated,
+                            description=mutation.description,
+                        )
+                    )
+
+        if mutants:
+            db.insert_many(mutants)
+            total += len(mutants)
+
+    console.print(f"[green]Discovered {total} mutations[/green]")
+
+    if total == 0:
+        console.print("[yellow]Nothing to test.[/yellow]")
+        db.close()
+        return
+
+    # Baseline check
+    console.print("Running baseline check...")
+    ok, output = check_baseline(cfg.test_command, cfg.timeout)
+    if not ok:
+        console.print("[red]Baseline check failed — type checker reports errors on unmodified code:[/red]")
+        console.print(output)
+        db.close()
+        raise SystemExit(1)
+    console.print("[green]Baseline clean.[/green]")
+
+    # Exec
+    pending = db.get_pending()
+    console.print(f"Running [bold]{len(pending)}[/bold] mutations...")
+    run_all_mutants(db, pending, cfg.test_command, cfg.timeout)
+
+    # Report
+    console.print()
+    print_report(db, console)
+    db.close()

typemut/config.py

@@ -0,0 +1,62 @@
+"""TOML config parsing for typemut."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class OperatorsConfig:
+    remove_union_member: bool = True
+    swap_literal_value: bool = True
+    swap_sibling_type: bool = True
+    strip_annotated: bool = True
+    remove_optional: bool = True
+    add_optional: bool = True
+    swap_container_type: bool = True
+
+
+@dataclass
+class Config:
+    module_path: str = "src"
+    test_command: str = "mypy src/"
+    timeout: int = 30
+    excluded_modules: list[str] = field(default_factory=list)
+    skip_comments: list[str] = field(
+        default_factory=lambda: ["type: ignore", "pragma: no mutate"]
+    )
+    operators: OperatorsConfig = field(default_factory=OperatorsConfig)
+    db_path: str = "typemut.sqlite"
+
+
+def load_config(path: Path) -> Config:
+    """Load config from a TOML file."""
+    text = path.read_text()
+    raw = tomllib.loads(text)
+
+    section = raw.get("typemut", {})
+    ops_raw = section.pop("operators", {})
+
+    operators = OperatorsConfig(
+        remove_union_member=ops_raw.get("remove-union-member", True),
+        swap_literal_value=ops_raw.get("swap-literal-value", True),
+        swap_sibling_type=ops_raw.get("swap-sibling-type", True),
+        strip_annotated=ops_raw.get("strip-annotated", True),
+        remove_optional=ops_raw.get("remove-optional", True),
+        add_optional=ops_raw.get("add-optional", True),
+        swap_container_type=ops_raw.get("swap-container-type", True),
+    )
+
+    return Config(
+        module_path=section.get("module-path", "src"),
+        test_command=section.get("test-command", "mypy src/"),
+        timeout=section.get("timeout", 30),
+        excluded_modules=section.get("excluded-modules", []),
+        skip_comments=section.get(
+            "skip-comments", ["type: ignore", "pragma: no mutate"]
+        ),
+        operators=operators,
+        db_path=section.get("db", "typemut.sqlite"),
+    )

typemut/db.py

@@ -0,0 +1,156 @@
+"""SQLite database for mutation results."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+SCHEMA = """\
+CREATE TABLE IF NOT EXISTS mutants (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    module_path TEXT NOT NULL,
+    operator TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL DEFAULT 0,
+    original_annotation TEXT NOT NULL,
+    mutated_annotation TEXT NOT NULL,
+    description TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    output TEXT,
+    duration_seconds REAL
+);
+
+CREATE INDEX IF NOT EXISTS idx_status ON mutants(status);
+CREATE INDEX IF NOT EXISTS idx_module ON mutants(module_path);
+"""
+
+
+@dataclass
+class MutantRow:
+    id: int | None
+    module_path: str
+    operator: str
+    line: int
+    col: int
+    original_annotation: str
+    mutated_annotation: str
+    description: str
+    status: str = "pending"
+    output: str | None = None
+    duration_seconds: float | None = None
+
+
+class Database:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.conn = sqlite3.connect(str(path))
+        self.conn.row_factory = sqlite3.Row
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        self.conn.executescript(SCHEMA)
+
+    def insert_mutant(self, mutant: MutantRow) -> int:
+        cursor = self.conn.execute(
+            """INSERT INTO mutants
+               (module_path, operator, line, col, original_annotation,
+                mutated_annotation, description, status)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                mutant.module_path,
+                mutant.operator,
+                mutant.line,
+                mutant.col,
+                mutant.original_annotation,
+                mutant.mutated_annotation,
+                mutant.description,
+                mutant.status,
+            ),
+        )
+        self.conn.commit()
+        return cursor.lastrowid  # type: ignore[return-value]
+
+    def insert_many(self, mutants: list[MutantRow]) -> None:
+        self.conn.executemany(
+            """INSERT INTO mutants
+               (module_path, operator, line, col, original_annotation,
+                mutated_annotation, description, status)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            [
+                (
+                    m.module_path,
+                    m.operator,
+                    m.line,
+                    m.col,
+                    m.original_annotation,
+                    m.mutated_annotation,
+                    m.description,
+                    m.status,
+                )
+                for m in mutants
+            ],
+        )
+        self.conn.commit()
+
+    def update_result(
+        self,
+        mutant_id: int,
+        status: str,
+        output: str | None = None,
+        duration: float | None = None,
+    ) -> None:
+        self.conn.execute(
+            """UPDATE mutants
+               SET status = ?, output = ?, duration_seconds = ?
+               WHERE id = ?""",
+            (status, output, duration, mutant_id),
+        )
+        self.conn.commit()
+
+    def get_pending(self) -> list[MutantRow]:
+        rows = self.conn.execute(
+            "SELECT * FROM mutants WHERE status = 'pending' ORDER BY id"
+        ).fetchall()
+        return [self._row_to_mutant(r) for r in rows]
+
+    def get_all(self) -> list[MutantRow]:
+        rows = self.conn.execute("SELECT * FROM mutants ORDER BY id").fetchall()
+        return [self._row_to_mutant(r) for r in rows]
+
+    def get_summary(self) -> dict[str, dict[str, int]]:
+        """Return per-module summary: {module: {killed: N, survived: N, ...}}."""
+        rows = self.conn.execute(
+            """SELECT module_path, status, COUNT(*) as cnt
+               FROM mutants GROUP BY module_path, status"""
+        ).fetchall()
+        summary: dict[str, dict[str, int]] = {}
+        for row in rows:
+            module = row["module_path"]
+            if module not in summary:
+                summary[module] = {}
+            summary[module][row["status"]] = row["cnt"]
+        return summary
+
+    def clear(self) -> None:
+        self.conn.execute("DELETE FROM mutants")
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    @staticmethod
+    def _row_to_mutant(row: sqlite3.Row) -> MutantRow:
+        return MutantRow(
+            id=row["id"],
+            module_path=row["module_path"],
+            operator=row["operator"],
+            line=row["line"],
+            col=row["col"],
+            original_annotation=row["original_annotation"],
+            mutated_annotation=row["mutated_annotation"],
+            description=row["description"],
+            status=row["status"],
+            output=row["output"],
+            duration_seconds=row["duration_seconds"],
+        )

typemut/discovery.py

@@ -0,0 +1,201 @@
+"""Find type annotation nodes in Python source using parso."""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+import parso
+from parso.python.tree import (
+    BaseNode,
+    Leaf,
+    Module,
+)
+
+
+class AnnotationContext(Enum):
+    VARIABLE = "variable"
+    PARAMETER = "parameter"
+    RETURN = "return"
+
+
+@dataclass
+class AnnotationNode:
+    file: Path
+    node: BaseNode | Leaf
+    context: AnnotationContext
+    line: int
+    col: int
+    code: str
+
+
+def _get_annotation_from_annassign(node: BaseNode) -> BaseNode | Leaf | None:
+    """Extract annotation node from an annassign (e.g. `x: int = 5`).
+
+    annassign structure: ':', annotation [, '=', value]
+    The annotation is the child after the ':' operator.
+    """
+    children = node.children
+    # children[0] is ':', children[1] is the annotation
+    if len(children) >= 2:
+        return children[1]
+    return None
+
+
+def _get_annotation_from_tfpdef(node: BaseNode) -> BaseNode | Leaf | None:
+    """Extract annotation node from a tfpdef (e.g. `x: int` in function params).
+
+    tfpdef structure: name, ':', annotation
+    """
+    children = node.children
+    if len(children) >= 3:
+        return children[2]
+    return None
+
+
+def _get_return_annotation(funcdef: BaseNode) -> BaseNode | Leaf | None:
+    """Extract return annotation from funcdef.
+
+    Look for '->' operator and take the next sibling.
+    """
+    children = funcdef.children
+    for i, child in enumerate(children):
+        if hasattr(child, "value") and child.value == "->":
+            if i + 1 < len(children):
+                return children[i + 1]
+    return None
+
+
+def _line_text(file_lines: list[str], line: int) -> str:
+    """Get the text of a specific line (1-indexed)."""
+    if 1 <= line <= len(file_lines):
+        return file_lines[line - 1]
+    return ""
+
+
+def _should_skip_line(line_text: str, skip_comments: list[str]) -> bool:
+    """Check if a line contains any skip comment."""
+    return any(comment in line_text for comment in skip_comments)
+
+
+def _is_any(node: BaseNode | Leaf) -> bool:
+    """Check if an annotation node is just `Any`."""
+    if isinstance(node, Leaf) and node.value == "Any":
+        return True
+    return False
+
+
+def discover_annotations(
+    file: Path,
+    source: str | None = None,
+    skip_comments: list[str] | None = None,
+) -> list[AnnotationNode]:
+    """Discover all type annotation nodes in a Python source file."""
+    if source is None:
+        source = file.read_text()
+    if skip_comments is None:
+        skip_comments = ["type: ignore", "pragma: no mutate"]
+
+    file_lines = source.splitlines()
+    tree = parso.parse(source)
+    annotations: list[AnnotationNode] = []
+
+    def visit(node: BaseNode | Leaf) -> None:
+        if isinstance(node, BaseNode):
+            # Variable annotation: x: int
+            if node.type == "annassign":
+                ann = _get_annotation_from_annassign(node)
+                if ann is not None and not _is_any(ann):
+                    line = ann.start_pos[0]
+                    if not _should_skip_line(
+                        _line_text(file_lines, line), skip_comments
+                    ):
+                        annotations.append(
+                            AnnotationNode(
+                                file=file,
+                                node=ann,
+                                context=AnnotationContext.VARIABLE,
+                                line=line,
+                                col=ann.start_pos[1],
+                                code=ann.value if isinstance(ann, Leaf) else _node_code(ann),
+                            )
+                        )
+
+            # Parameter annotation: def f(x: int)
+            elif node.type == "tfpdef":
+                ann = _get_annotation_from_tfpdef(node)
+                if ann is not None and not _is_any(ann):
+                    line = ann.start_pos[0]
+                    if not _should_skip_line(
+                        _line_text(file_lines, line), skip_comments
+                    ):
+                        annotations.append(
+                            AnnotationNode(
+                                file=file,
+                                node=ann,
+                                context=AnnotationContext.PARAMETER,
+                                line=line,
+                                col=ann.start_pos[1],
+                                code=ann.value if isinstance(ann, Leaf) else _node_code(ann),
+                            )
+                        )
+
+            # Return annotation: def f() -> int
+            elif node.type == "funcdef":
+                ann = _get_return_annotation(node)
+                if ann is not None and not _is_any(ann):
+                    line = ann.start_pos[0]
+                    if not _should_skip_line(
+                        _line_text(file_lines, line), skip_comments
+                    ):
+                        annotations.append(
+                            AnnotationNode(
+                                file=file,
+                                node=ann,
+                                context=AnnotationContext.RETURN,
+                                line=line,
+                                col=ann.start_pos[1],
+                                code=ann.value if isinstance(ann, Leaf) else _node_code(ann),
+                            )
+                        )
+
+            # Recurse into children
+            for child in node.children:
+                visit(child)
+
+    visit(tree)
+    return annotations
+
+
+def _node_code(node: BaseNode | Leaf) -> str:
+    """Get the exact source code text of a node, preserving whitespace."""
+    code = node.get_code()
+    # get_code() includes the prefix (leading whitespace) of the first leaf.
+    # Strip it to get just the annotation text.
+    first = node
+    while hasattr(first, "children") and first.children:
+        first = first.children[0]
+    if hasattr(first, "prefix"):
+        prefix = first.prefix
+        if code.startswith(prefix):
+            code = code[len(prefix) :]
+    return code
+
+
+def discover_files(
+    module_path: Path,
+    excluded_modules: list[str] | None = None,
+) -> list[Path]:
+    """Find all Python files in the given module path, respecting exclusions."""
+    if excluded_modules is None:
+        excluded_modules = []
+
+    files: list[Path] = []
+    for py_file in sorted(module_path.rglob("*.py")):
+        rel = str(py_file)
+        if any(fnmatch.fnmatch(rel, pattern) for pattern in excluded_modules):
+            continue
+        files.append(py_file)
+    return files