py-harness-cli 0.3.0__py3-none-any.whl

harness/scan/layout.py

@@ -0,0 +1,254 @@
+"""Report why a project is difficult to read, and what to change first.
+
+Four problems are detected, listed here in the order they are worth
+fixing:
+
+* `cycle`    - two modules import each other, so neither can be read alone.
+* `flat`     - one directory holds many modules with no grouping.
+* `god`      - one module is much larger than the others around it.
+* `no-tests` - the project contains no test files.
+
+Only the first problem is turned into an instruction. A model given four
+instructions at once tends to change four things at once; a model given one
+instruction changes one thing, which can then be checked.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+from harness.paths import rel_posix
+from harness.scan.project_scan import SKIP_DIR
+
+FLAT_MAX_MODULES = 12
+# A module far bigger than the ones beside it. This is not the same
+# thing as a god module and no longer says it is: `scan.design` calls a
+# file with too many top-level functions a god module, and the two
+# disagreed in both directions. A 300-byte file with four functions is
+# one by that rule and not by this; a 7 KB file holding two long
+# functions is one by this and not by that, and since the design review
+# started reporting long functions, that case has a better answer.
+OUTSIZED_RATIO = 3
+OUTSIZED_MIN_BYTES = 6000
+MAX_FINDINGS = 4
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One structural problem found in a project.
+
+    Fields:
+        kind: "cycle", "flat", "outsized" or "no-tests".
+        detail: what was found, naming the files involved.
+        move: the change to make, written as an instruction.
+    """
+
+    kind: str
+    detail: str
+    move: str
+
+
+def _modules(project: Path) -> list[Path]:
+    root = project.resolve()
+    return [
+        path
+        for path in sorted(root.rglob("*.py"))
+        if not any(part in SKIP_DIR for part in path.parts)
+    ]
+
+
+def _module_name(path: Path, root: Path) -> str:
+    """Dotted name for a file, as an import inside this project spells it."""
+    rel = path.resolve().relative_to(root).with_suffix("")
+    parts = list(rel.parts)
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+
+def _local_imports(path: Path, root: Path) -> set[str]:
+    """Dotted modules this file imports, relative imports resolved.
+
+    The first version kept only the last component of each import, and
+    the graph was keyed on the file name. Two things followed on a real
+    repository, where the same file name appears many times: distinct
+    modules merged into one node, and `rich.console` counted as an
+    import of a local `console.py`. Every cycle reported on a 4,580-file
+    project was one of those, four out of four.
+    """
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError, ValueError):
+        return set()
+    package = _module_name(path, root).rsplit(".", 1)
+    package = package[0] if len(package) == 2 else ""
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.level:
+                # `from . import x` and `from .mod import y` are relative
+                # to the package this file sits in.
+                base = package.split(".") if package else []
+                climb = node.level - 1
+                base = base[: len(base) - climb] if climb else base
+                stem = ".".join(part for part in (*base, node.module or "") if part)
+            else:
+                stem = node.module or ""
+            if not stem:
+                continue
+            names.add(stem)
+            for alias in node.names:
+                names.add(f"{stem}.{alias.name}")
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                names.add(alias.name)
+    return names
+
+
+def find_cycles(project: Path) -> list[tuple[str, str]]:
+    root = project.resolve()
+    modules = _modules(project)
+    by_name = {_module_name(path, root): path for path in modules}
+
+    # A sub-project keeps its own root: demo/orders/src/report.py is
+    # imported as `src.report` from inside demo/orders. Accept a dotted
+    # path that is the tail of exactly one module, so that still counts,
+    # while an ambiguous tail counts for nothing.
+    tails: dict[str, list[str]] = {}
+    for name in by_name:
+        parts = name.split(".")
+        for start in range(1, len(parts)):
+            tails.setdefault(".".join(parts[start:]), []).append(name)
+
+    def resolve(imported: set[str], self_name: str) -> set[str]:
+        found = set()
+        for item in imported:
+            if item in by_name:
+                found.add(item)
+                continue
+            # Only a dotted path. A bare top-level name competes with
+            # every package on the machine: `import logging` beside a
+            # local `infrastructure/logging/` package resolved to it and
+            # invented two cycles on a real repository.
+            if "." not in item:
+                continue
+            unique = tails.get(item, ())
+            if len(unique) == 1:
+                found.add(unique[0])
+        return found - {self_name}
+
+    graph = {
+        name: resolve(_local_imports(path, root), name)
+        for name, path in by_name.items()
+    }
+    pairs = {
+        tuple(sorted((name, other)))
+        for name, deps in graph.items()
+        for other in deps
+        if name in graph.get(other, set())
+    }
+    return sorted(
+        (rel_posix(by_name[left], root), rel_posix(by_name[right], root))
+        for left, right in pairs
+    )
+
+
+def find_flat_packages(project: Path) -> list[tuple[str, int]]:
+    root = project.resolve()
+    counts: dict[str, int] = {}
+    for path in _modules(project):
+        parent = path.parent
+        key = rel_posix(parent, root) if parent != root else "."
+        counts[key] = counts.get(key, 0) + 1
+    return sorted(
+        ((name, n) for name, n in counts.items() if n > FLAT_MAX_MODULES),
+        key=lambda item: (-item[1], item[0]),
+    )
+
+
+def find_outsized_modules(project: Path) -> list[tuple[str, int]]:
+    root = project.resolve()
+    sizes = []
+    for path in _modules(project):
+        try:
+            sizes.append((rel_posix(path, root), path.stat().st_size))
+        except OSError:
+            continue
+    if len(sizes) < 3:
+        return []
+    median = sorted(size for _rel, size in sizes)[len(sizes) // 2]
+    return sorted(
+        (
+            (rel, size)
+            for rel, size in sizes
+            if size >= OUTSIZED_MIN_BYTES and size > median * OUTSIZED_RATIO
+        ),
+        key=lambda item: -item[1],
+    )
+
+
+def has_tests(project: Path) -> bool:
+    root = project.resolve()
+    return any(
+        path.name.startswith("test_")
+        for path in root.rglob("test_*.py")
+        if not any(part in SKIP_DIR for part in path.parts)
+    )
+
+
+def review_layout(project: Path) -> list[Finding]:
+    out: list[Finding] = []
+    for left, right in find_cycles(project):
+        out.append(
+            Finding(
+                "cycle",
+                f"{left} and {right} import each other",
+                f"Move what they share into a new module both import. "
+                f"Action: grep Query: def .*  Path: {left}",
+            )
+        )
+    for name, count in find_flat_packages(project):
+        out.append(
+            Finding(
+                "flat",
+                f"{name}/ holds {count} modules with no grouping",
+                f"Group {name}/ by what each module is for, one folder per "
+                "job, and give each folder an __init__.py that says so.",
+            )
+        )
+    for rel, size in find_outsized_modules(project):
+        out.append(
+            Finding(
+                "outsized",
+                f"{rel} is {size // 1024} KB — far larger than its neighbours",
+                f"Action: read Path: {rel} and split the one group of "
+                "functions that does not belong with the rest.",
+            )
+        )
+    if not has_tests(project):
+        out.append(
+            Finding(
+                "no-tests",
+                "no test_*.py anywhere in this project",
+                "Action: patch Path: tests/test_smoke.py with one unittest "
+                "for the function you touch next.",
+            )
+        )
+    return out[:MAX_FINDINGS]
+
+
+def render_layout(project: Path) -> str:
+    findings = review_layout(project)
+    if not findings:
+        return (
+            "layout: no cycles, no oversized package, no outsized module, tests "
+            "present. Nothing to restructure — do the task."
+        )
+    lines = [f"layout: {len(findings)} finding(s), worst first."]
+    for finding in findings:
+        lines.append(f"  [{finding.kind}] {finding.detail}")
+    lines.append("")
+    lines.append(f"Next move (do only this one): {findings[0].move}")
+    return "\n".join(lines)

harness/scan/names.py

@@ -0,0 +1,308 @@
+"""Undefined-name scan. Deterministic compiler-style oracle. No model.
+
+A small model will write `subtotl` next to `subtotal = ...` and then say
+done. The existing test suite often does not call the broken function, so
+`run` exits 0. This scan is the extra oracle: names that are loaded but
+never bound, the way a compiler would complain.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+def _builtin_names() -> set[str]:
+    raw = __builtins__
+    names = set(raw) if isinstance(raw, dict) else set(dir(raw))
+    # Module dunders are bound by the interpreter, not by the source.
+    return names | {
+        "Ellipsis", "NotImplemented", "False", "None", "True",
+        "__file__", "__name__", "__doc__", "__package__", "__spec__",
+        "__loader__", "__builtins__", "__debug__",
+    }
+
+
+_BUILTINS = _builtin_names()
+
+
+def _store_names(node: ast.AST) -> set[str]:
+    names: set[str] = set()
+    if isinstance(node, ast.Name):
+        names.add(node.id)
+    elif isinstance(node, (ast.Tuple, ast.List)):
+        for child in node.elts:
+            names.update(_store_names(child))
+    elif isinstance(node, ast.Starred):
+        names.update(_store_names(node.value))
+    return names
+
+
+# 3.12 added `type X = ...`. Absent on 3.11, which this project supports.
+_TYPE_ALIAS = getattr(ast, "TypeAlias", None)
+
+
+def _assign_names(node: ast.AST) -> set[str]:
+    if isinstance(node, ast.Assign):
+        names: set[str] = set()
+        for target in node.targets:
+            names.update(_store_names(target))
+        return names
+    if isinstance(node, ast.AnnAssign) and node.target:
+        return _store_names(node.target)
+    if isinstance(node, ast.AugAssign):
+        return _store_names(node.target)
+    if isinstance(node, ast.NamedExpr):
+        return _store_names(node.target)
+    if isinstance(node, (ast.For, ast.AsyncFor)):
+        return _store_names(node.target)
+    if isinstance(node, ast.withitem) and node.optional_vars:
+        return _store_names(node.optional_vars)
+    if isinstance(node, ast.ExceptHandler) and node.name:
+        return {node.name}
+    if isinstance(node, (ast.Import, ast.ImportFrom)):
+        found: set[str] = set()
+        for alias in node.names:
+            found.add(alias.asname or alias.name.split(".")[0])
+        return found
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return {node.name}
+    # `type Properties = dict[str, JsonValue]`, the 3.12 alias spelling.
+    # The node type does not exist before 3.12, and this project runs on
+    # 3.11 as well, so it is looked up rather than named.
+    if _TYPE_ALIAS is not None and isinstance(node, _TYPE_ALIAS):
+        return _store_names(node.name)
+    # `case InputSubmitted(text):` binds `text` for the branch body.
+    if isinstance(node, (ast.MatchAs, ast.MatchStar)) and node.name:
+        return {node.name}
+    if isinstance(node, ast.MatchMapping) and node.rest:
+        return {node.rest}
+    return set()
+
+
+def _argument_names(args: ast.arguments) -> set[str]:
+    """Every parameter name a signature binds."""
+    names = {
+        arg.arg
+        for arg in (*args.posonlyargs, *args.args, *args.kwonlyargs)
+    }
+    if args.vararg:
+        names.add(args.vararg.arg)
+    if args.kwarg:
+        names.add(args.kwarg.arg)
+    return names
+
+
+def _type_param_names(node: ast.AST) -> set[str]:
+    """Names bound by PEP 695 type parameters: `def tool[F](...)`.
+
+    Python 3.12 spelling, and the only place `F` or `T` is declared in a
+    file that uses it. Without this they read as undefined, which was
+    the largest group left in a real project after module scope was
+    handled properly.
+    """
+    return {param.name for param in getattr(node, "type_params", []) or []}
+
+
+def _function_bound(function: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    bound = {function.name} | _argument_names(function.args) | _type_param_names(function)
+    for node in ast.walk(function):
+        if node is function:
+            continue
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            bound.add(node.name)
+            bound.update(_type_param_names(node))
+        # A nested function or lambda binds its own parameters. Only their
+        # names were collected, so every such parameter read looked
+        # undefined: `item`, `text`, `prompt` across this project's own code.
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            bound.update(_argument_names(node.args))
+        bound.update(_assign_names(node))
+        if isinstance(node, ast.comprehension):
+            bound.update(_store_names(node.target))
+    return bound
+
+
+def _module_scope_bound(tree: ast.Module) -> set[str]:
+    """Every name module scope binds, including inside `if` and `try`.
+
+    Only the top level of `tree.body` used to count, so the two most
+    common shapes in typed and cross-platform code read as undefined:
+
+        if TYPE_CHECKING:
+            from rich.markdown import Markdown   # used in an annotation
+
+        try:
+            import termios                       # POSIX only
+        except ImportError:
+            termios = None
+
+    Both run fine. On a sample of 600 files from a real project, 18 were
+    reported as having an undefined name and these two shapes accounted
+    for them. Function and class bodies are separate scopes and are not
+    descended into.
+    """
+    bound: set[str] = set()
+
+    def walk(body: list[ast.stmt]) -> None:
+        for node in body:
+            bound.update(_assign_names(node))
+            bound.update(_type_param_names(node))
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                continue
+            for field in ("body", "orelse", "finalbody"):
+                inner = getattr(node, field, None)
+                if isinstance(inner, list):
+                    walk([item for item in inner if isinstance(item, ast.stmt)])
+            for handler in getattr(node, "handlers", []) or []:
+                bound.update(_assign_names(handler))
+                walk(handler.body)
+            for item in getattr(node, "items", []) or []:
+                bound.update(_assign_names(item))
+
+    walk(tree.body)
+    return bound
+
+
+def undefined_names(source: str) -> list[str]:
+    """Load-names in functions that are not bound in the module or the function."""
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return []
+    module_bound = set(_BUILTINS) | _module_scope_bound(tree)
+    found: list[str] = []
+    seen: set[str] = set()
+
+    def scan(function: ast.AST, bound: set[str]) -> None:
+        inner = bound | _function_bound(function)
+        for child in ast.walk(function):
+            if not isinstance(child, ast.Name) or not isinstance(child.ctx, ast.Load):
+                continue
+            if child.id in inner or child.id in seen:
+                continue
+            seen.add(child.id)
+            found.append(child.id)
+
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            scan(node, module_bound)
+        elif isinstance(node, ast.ClassDef):
+            # Methods were never scanned, and every unittest test is one.
+            # A test calling a function it forgot to import looked clean.
+            class_bound = set(module_bound)
+            for member in node.body:
+                class_bound.update(_assign_names(member))
+                if isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    class_bound.add(member.name)
+            for member in node.body:
+                if isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    scan(member, class_bound)
+    return found
+
+
+def new_undefined(original: str, draft: str) -> list[str]:
+    """Undefined names the draft added. Existing planted bugs are ignored."""
+    before = set(undefined_names(original))
+    return [name for name in undefined_names(draft) if name not in before]
+
+
+def undefined_in_file(path: Path) -> list[str]:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    return undefined_names(source)
+
+
+def _module_file(project: Path, dotted: str) -> Path | None:
+    """The file a `from a.b import c` refers to, if it is in this project."""
+    parts = dotted.split(".")
+    for candidate in (
+        project.joinpath(*parts).with_suffix(".py"),
+        project.joinpath(*parts, "__init__.py"),
+        project.joinpath(*parts[1:]).with_suffix(".py") if len(parts) > 1 else None,
+    ):
+        if candidate is not None and candidate.is_file():
+            return candidate
+    return None
+
+
+def _defined_in(source: str) -> set[str]:
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return set()
+    names: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            names.add(node.name)
+        names.update(_assign_names(node))
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                names.add(alias.asname or alias.name.split(".")[0])
+    return names
+
+
+def missing_import_targets(project: Path, source: str) -> list[tuple[str, str]]:
+    """Imports of names this project's own modules do not define.
+
+    A test that imports a function nobody has written yet reads as valid
+    Python — the import binds the name, so the undefined-name scan sees
+    nothing — and fails only when the suite runs.
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return []
+    missing: list[tuple[str, str]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom) or node.level or not node.module:
+            continue
+        target = _module_file(Path(project), node.module)
+        if target is None:
+            continue
+        try:
+            defined = _defined_in(target.read_text(encoding="utf-8"))
+        except OSError:
+            continue
+        for alias in node.names:
+            if alias.name != "*" and alias.name not in defined:
+                missing.append((node.module, alias.name))
+    return missing
+
+
+# Names a small model reaches for without importing them. The fix for
+# these is an import line, never a rename.
+_IMPORTABLE = {
+    "Path": "from pathlib import Path",
+    "PurePath": "from pathlib import PurePath",
+    "dataclass": "from dataclasses import dataclass",
+    "field": "from dataclasses import field",
+    "Counter": "from collections import Counter",
+    "defaultdict": "from collections import defaultdict",
+    "Any": "from typing import Any",
+    "Iterable": "from collections.abc import Iterable",
+    "Sequence": "from collections.abc import Sequence",
+    "Callable": "from collections.abc import Callable",
+    "datetime": "from datetime import datetime",
+    "date": "from datetime import date",
+    "timedelta": "from datetime import timedelta",
+    "os": "import os",
+    "sys": "import sys",
+    "re": "import re",
+    "json": "import json",
+    "csv": "import csv",
+    "math": "import math",
+    "shutil": "import shutil",
+    "subprocess": "import subprocess",
+    "tempfile": "import tempfile",
+    "zipfile": "import zipfile",
+    "tarfile": "import tarfile",
+    "urllib": "import urllib.request",
+    "unittest": "import unittest",
+}
+
+
+def import_for(name: str) -> str:
+    """The import line that binds `name`, if it is one of the usual ones."""
+    return _IMPORTABLE.get(name, "")