Gawain’s Quest: Enforcing Type Hints on Every Python Variable – An Engineering Deep‑Dive", **"slug":** "gawain-require-type-hints-python

dict[str, Any]

dict[str, ANY]

Source Files → Python AST Parser → Gawain AST Visitor → Hint‑Compliance Engine → Exit Code

list[int]

list

--jobs N

multiprocessing.Pool

--jobs=4

# gawain_core.py
"""Core implementation of Gawain – a zero‑tolerance type‑hint enforcer.

The module provides a `check_file` function that returns a list of violation
records. Each record is a tuple: (filename, line, column, message).
"""

import ast
from pathlib import Path
from typing import List, Tuple, Set

Violation = Tuple[str, int, int, str]

class HintVisitor(ast.NodeVisitor):
    """Traverse the AST and collect binding sites lacking explicit hints."""

    def __init__(self, filename: str):
        self.filename = filename
        self.violations: List[Violation] = []
        # Keep track of names that have been annotated already (e.g., via
        # `global` or `nonlocal`).
        self.annotated: Set[str] = set()

    # ---------------------------------------------------------------------
    # Helper utilities
    # ---------------------------------------------------------------------
    def _report(self, node: ast.AST, msg: str) -> None:
        self.violations.append(
            (self.filename, node.lineno, node.col_offset, msg)
        )

    def _is_annotated(self, target: ast.AST) -> bool:
        """Return True if the target already has an annotation.

        Handles `AnnAssign` (PEP‑526) and type comments attached to `Assign`.
        """
        if isinstance(target, ast.AnnAssign):
            return True
        # For plain Assign we need to look for a type comment on the node.
        if isinstance(target, ast.Assign) and getattr(target, "type_comment", None):
            return True
        return False

    # ---------------------------------------------------------------------
    # Visitor methods – each binding construct is examined.
    # ---------------------------------------------------------------------
    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        # Arguments
        for arg in node.args.args + node.args.kwonlyargs:
            if arg.annotation is None:
                self._report(arg, "GAW001 missing type hint for function argument")
        # Return annotation is optional – we do not enforce it here.
        self.generic_visit(node)

    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
        # Already annotated – nothing to do.
        self.generic_visit(node)

    def visit_Assign(self, node: ast.Assign) -> None:
        # If the whole statement has a type comment, we consider it annotated.
        if getattr(node, "type_comment", None):
            self.generic_visit(node)
            return
        # Otherwise, each target must be annotated elsewhere – which we cannot
        # infer statically, so we flag it.
        for target in node.targets:
            if isinstance(target, (ast.Name, ast.Tuple, ast.List)):
                self._report(target, "GAW001 missing type hint for variable assignment")
        self.generic_visit(node)

    def visit_For(self, node: ast.For) -> None:
        # The loop variable must be annotated.
        if isinstance(node.target, ast.Name):
            self._report(node.target, "GAW001 missing type hint for for‑loop variable")
        self.generic_visit(node)

    def visit_With(self, node: ast.With) -> None:
        for item in node.items:
            if item.optional_vars and isinstance(item.optional_vars, ast.Name):
                self._report(item.optional_vars, "GAW001 missing type hint for with‑as variable")
        self.generic_visit(node)

    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
        if node.name and isinstance(node.name, ast.Name):
            self._report(node.name, "GAW001 missing type hint for exception variable")
        self.generic_visit(node)

    # Comprehensions – treat the iteration variable similarly.
    def visit_ListComp(self, node: ast.ListComp) -> None:
        for gen in node.generators:
            if isinstance(gen.target, ast.Name):
                self._report(gen.target, "GAW001 missing type hint in list comprehension")
        self.generic_visit(node)

    # Add analogous visitors for SetComp, DictComp, GeneratorExp if needed.


def check_file(path: Path) -> List[Violation]:
    """Parse *path* and return a list of Gawain violations.

    The function raises `SyntaxError` if the source cannot be parsed – the caller
    should decide whether to treat that as a CI failure.
    """
    source = path.read_text(encoding="utf-8")
    tree = ast.parse(source, filename=str(path), type_comments=True)
    visitor = HintVisitor(str(path))
    visitor.visit(tree)
    return visitor.violations

# ---------------------------------------------------------------------
# CLI entry point – mimics the behaviour of `flake8` plugins.
# ---------------------------------------------------------------------
if __name__ == "__main__":
    import argparse, sys
    parser = argparse.ArgumentParser(description="Gawain – enforce type hints")
    parser.add_argument("files", nargs="+", type=Path, help="Python source files")
    parser.add_argument("-j", "--jobs", type=int, default=1, help="Parallel workers")
    args = parser.parse_args()

    from concurrent.futures import ProcessPoolExecutor, as_completed

    all_violations: List[Violation] = []
    with ProcessPoolExecutor(max_workers=args.jobs) as pool:
        futures = {pool.submit(check_file, p): p for p in args.files