tepyd 0.5.0__py3-none-any.whl

tepyd/__init__.py

@@ -0,0 +1,12 @@
+"""Tepyd — TEst PYramid Doctor.
+
+Diagnose a project's test pyramid: its mass (test vs source LOC and shape),
+its structural mirroring of the source tree, and how well each tier actually
+covers the code it claims to.
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+__all__ = ["main"]

tepyd/cli.py

@@ -0,0 +1,333 @@
+"""Command-line entry point for Tepyd.
+
+``init`` scaffolds a ``[tool.tepyd]`` config; ``mass``, ``mirror``,
+``cover`` (per-tier focused coverage) and ``report`` (which synthesises the
+others into advice) are implemented. ``audit`` is reserved for a later phase.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import cover, init, mass, mirror, report
+from .config import Config, ConfigError, find_project_root, load_config
+from .discovery import discover_units
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tepyd",
+        description="Tepyd — TEst PYramid Doctor: diagnose a project's test pyramid.",
+    )
+    parser.add_argument(
+        "-C",
+        "--root",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="Project directory to analyse (default: discover from cwd).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_p = sub.add_parser(
+        "init",
+        help="Guess this project's layout and write a [tool.tepyd] section.",
+    )
+    init_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the section that would be written, without modifying anything.",
+    )
+    init_p.set_defaults(func=_run_init)
+
+    mass_p = sub.add_parser(
+        "mass",
+        help="Test-LOC vs source-LOC, tier mix, and pyramid shape.",
+    )
+    mass_p.add_argument(
+        "--min-src",
+        type=int,
+        default=20,
+        help="Skip source units smaller than this LOC (default 20).",
+    )
+    _add_json(mass_p)
+    _add_exclude(mass_p)
+    mass_p.set_defaults(func=_run_mass)
+
+    mirror_p = sub.add_parser(
+        "mirror",
+        help="Structural mirroring of the test tree against the source tree.",
+    )
+    mirror_p.add_argument(
+        "--max-depth",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Only check source packages within N levels of the source root.",
+    )
+    _add_json(mirror_p)
+    _add_exclude(mirror_p)
+    mirror_p.set_defaults(func=_run_mirror)
+
+    cover_p = sub.add_parser(
+        "cover",
+        help="Per-tier focused coverage: which tier actually exercises each unit.",
+    )
+    cover_p.add_argument(
+        "--tier",
+        action="append",
+        default=None,
+        metavar="NAME",
+        dest="tiers",
+        help="Measure only this tier (repeatable; default: all tiers).",
+    )
+    cover_p.add_argument(
+        "--min-src",
+        type=int,
+        default=20,
+        help="Skip units with fewer than this many source statements (default 20).",
+    )
+    _add_json(cover_p)
+    _add_exclude(cover_p)
+    cover_p.set_defaults(func=_run_cover)
+
+    report_p = sub.add_parser(
+        "report",
+        help="Run every check and explain the results, with advice.",
+    )
+    report_p.add_argument(
+        "--format",
+        choices=("text", "md"),
+        default="text",
+        help="Output format (default: text).",
+    )
+    report_p.add_argument(
+        "--level",
+        choices=("newb", "junior", "senior", "expert"),
+        default="senior",
+        help="How much to explain: newb teaches the concepts, expert is a "
+        "terse checklist (default: senior).",
+    )
+    report_p.add_argument(
+        "--min-src",
+        type=int,
+        default=20,
+        help="Skip source units smaller than this LOC (default 20).",
+    )
+    report_p.add_argument(
+        "--max-depth",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Mirror check: only source packages within N levels of the root.",
+    )
+    _add_exclude(report_p)
+    report_p.set_defaults(func=_run_report)
+
+    return parser
+
+
+def _add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON instead of the human-readable report.",
+    )
+
+
+def _add_exclude(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help="Skip this source unit (repeatable), on top of config exclusions.",
+    )
+
+
+def _stdin_is_interactive() -> bool:
+    try:
+        return sys.stdin is not None and sys.stdin.isatty()
+    except (ValueError, OSError):
+        return False
+
+
+def _interactive_ask(question: str, options: list[str], default: str) -> str:
+    """Prompt the user to choose one of ``options`` (Enter accepts default)."""
+    print(question)
+    for i, opt in enumerate(options, 1):
+        suffix = "  (default)" if opt == default else ""
+        print(f"  {i}) {opt}{suffix}")
+    while True:
+        raw = input(f"Choice [1-{len(options)}, default {default}]: ").strip()
+        if not raw:
+            return default
+        if raw in options:
+            return raw
+        if raw.isdigit() and 1 <= int(raw) <= len(options):
+            return options[int(raw) - 1]
+        print("  Enter a number from the list or a package name.")
+
+
+def _run_init(args: argparse.Namespace) -> int:
+    root = find_project_root(args.root or Path.cwd())
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        print(
+            f"tepyd init: no pyproject.toml found at {root} — "
+            "run from your project root.",
+            file=sys.stderr,
+        )
+        return 2
+    if init.has_tepyd_section(root):
+        print(
+            f"tepyd init: [tool.tepyd] is already present in {pyproject} — "
+            "leaving it untouched."
+        )
+        return 0
+
+    ask = _interactive_ask if _stdin_is_interactive() else None
+    config, notes = init.detect_config(root, ask=ask)
+    section = init.render_section(config)
+    if args.dry_run:
+        print(section, end="")
+        return 0
+
+    init.write_section(root, section)
+    print(f"Wrote [tool.tepyd] to {pyproject}.")
+    print(
+        f"  src_root = {config.src_root}   "
+        f"tiers: {', '.join(t.name for t in config.tiers)}"
+    )
+    for note in notes:
+        print(f"  note: {note}", file=sys.stderr)
+    print("Review it, then run `tepyd mass` or `tepyd mirror`.")
+    return 0
+
+
+def _empty_units_message(config: Config, min_src: int) -> str:
+    """Diagnose *why* no units were analysed: none discovered (likely a flat
+    package or wrong src_root) vs. all discovered units below --min-src."""
+    if not discover_units(config):
+        return (
+            f"(no source units found under {config.src_path}. Tepyd treats each "
+            "sub-package — a sub-directory of src_root — as a unit, and this "
+            "path has none. If your source is a flat package of modules, set "
+            '`units = ["*.py"]` in [tool.tepyd] to analyse modules; otherwise '
+            "check `src_root`.)"
+        )
+    return (
+        f"(source units were found under {config.src_path}, but none reached "
+        f"the --min-src {min_src} LOC threshold — lower it to include smaller "
+        "units.)"
+    )
+
+
+def _run_mass(args: argparse.Namespace) -> int:
+    config = load_config(args.root)
+    rows = mass.build_rows(config, min_src=args.min_src, extra_exclude=args.exclude)
+    if not rows:
+        print(_empty_units_message(config, args.min_src), file=sys.stderr)
+        return 1
+    if args.json:
+        print(mass.emit_json(rows))
+    else:
+        print(mass.format_table(config, rows))
+        print(mass.summary(config, rows))
+    return 0
+
+
+def _run_mirror(args: argparse.Namespace) -> int:
+    config = load_config(args.root)
+    report = mirror.build_mirror(
+        config,
+        max_depth=args.max_depth,
+        extra_exclude=tuple(args.exclude),
+    )
+    if not report.source_packages:
+        print(
+            f"(no source units found under {config.src_path}. If this is a flat "
+            'package of modules, set units = ["*.py"] in [tool.tepyd]; otherwise '
+            "check src_root.)",
+            file=sys.stderr,
+        )
+        return 1
+    if args.json:
+        print(mirror.emit_json(report))
+    else:
+        print(mirror.format_mirror(report))
+    return 0
+
+
+def _run_cover(args: argparse.Namespace) -> int:
+    config = load_config(args.root)
+    selected = tuple(args.tiers) if args.tiers else None
+    try:
+        report = cover.run_cover(
+            config,
+            tiers=selected,
+            min_src=args.min_src,
+            extra_exclude=tuple(args.exclude),
+        )
+    except cover.CoverToolError as exc:
+        print(f"tepyd cover: {exc}", file=sys.stderr)
+        return 2
+
+    if not report.units:
+        # Surface why nothing was measured: failed tiers, or just an empty
+        # source tree below the --min-src gate.
+        if report.failures:
+            print(cover.summary(report), file=sys.stderr)
+            print("(no coverage data)", file=sys.stderr)
+        else:
+            print(_empty_units_message(config, args.min_src), file=sys.stderr)
+        return 1
+
+    # Surface failed/partial tiers on stderr even on the success path, so they
+    # aren't lost when stdout is piped to a file. (Exit stays 0 — best-effort;
+    # JSON consumers get the full `failures`/`warnings` arrays.)
+    for failure in report.failures:
+        print(f"  tier {failure.tier} not measured: {failure.reason}", file=sys.stderr)
+    for warning in report.warnings:
+        print(f"  tier {warning.tier}: {warning.reason}", file=sys.stderr)
+
+    if args.json:
+        print(cover.emit_json(report))
+    else:
+        print(cover.format_table(report))
+        print(cover.summary(report))
+    return 0
+
+
+def _run_report(args: argparse.Namespace) -> int:
+    config = load_config(args.root)
+    data = report.build_report(
+        config,
+        min_src=args.min_src,
+        max_depth=args.max_depth,
+        extra_exclude=tuple(args.exclude),
+    )
+    if not data.rows and not data.mirror.source_packages:
+        print(
+            f"(nothing to analyse under {config.src_path})",
+            file=sys.stderr,
+        )
+        return 1
+    print(report.render(config, data, fmt=args.format, level=args.level), end="")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except ConfigError as exc:
+        print(f"tepyd: configuration error: {exc}", file=sys.stderr)
+        return 2
+    except FileNotFoundError as exc:
+        # e.g. counter='cloc' with cloc absent — message already printed.
+        print(f"tepyd: {exc}", file=sys.stderr)
+        return 2

tepyd/config.py

@@ -0,0 +1,251 @@
+"""Configuration model for Tepyd, loaded from ``[tool.tepyd]``.
+
+Everything the original one-off script hardwired — the source root, the
+tier names and locations, the source-unit slicing rules, the policy
+exclusions — lives here as data, with the author's own layout shipped as
+the default so this project (and others that share the layout) work with
+zero config. Any project that differs overrides only what differs.
+
+The schema deliberately keeps a few doors open for later phases without
+paying for them now:
+
+- ``src_root``/``src_package`` are single values today, but the loader
+  tolerates a *list* so monorepo support (Phase 3+) is an additive change.
+- ``Tier.markers`` feeds the future ``audit`` lens; unset, it costs nothing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, cast
+
+import tomllib
+
+# --- Defaults : the author's current layout -------------------------------
+#
+# These mirror `sandbox/cloc_test_ratios.py` so the zero-config experience
+# matches what the script produced. NOTE the one deliberate departure:
+# `exclude` defaults to EMPTY. Exclusions (`faker`, `jobs`) are per-project
+# *policy*, not *layout* — baking them into every project's defaults would
+# silently drop real packages elsewhere. Layout is a default; policy is not.
+
+DEFAULT_SRC_ROOT = "src/app"
+DEFAULT_SRC_PACKAGE = "app"
+# Glob patterns slicing the source tree into units, first-match-wins:
+# explode every module one level deep, then take each remaining top-level
+# package as one unit. A pattern's match is skipped if a previous pattern
+# already claimed something beneath it (so `modules/` itself never doubles
+# as a unit once `modules/*` exploded it).
+DEFAULT_UNITS: tuple[str, ...] = ("modules/*", "*")
+
+# Default counter: the built-in tokenize-based one, so `pip install tepyd`
+# works with no external binary. `cloc` stays available as an opt-in for
+# those who want its stricter, multi-language counting.
+DEFAULT_COUNTER = "internal"
+VALID_COUNTERS = frozenset({"internal", "cloc"})
+
+
+class ConfigError(ValueError):
+    """Raised when ``[tool.tepyd]`` is present but malformed."""
+
+
+@dataclass(frozen=True)
+class Tier:
+    """One rung of the pyramid — a directory of tests of a given cost.
+
+    Tiers are ordered cheapest-first in the config; that order is load
+    bearing (the first tier is "unit", the last is the most expensive),
+    so the pyramid-shape logic needs no per-tier "is this the cap?" flag.
+    """
+
+    name: str
+    root: str  # filesystem path relative to the project root
+    label: str = ""  # human column header; defaults to `name`
+    target_share: float | None = None  # policy: min fraction of test LOC
+    strip_prefix: str = ""  # mapping rewrite for tiers that flatten layout
+    # Regex markers for the future `audit` lens (what imports/fixtures say
+    # a file in this tier should use). Unused until Phase 3.
+    markers: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.label:
+            # frozen dataclass — assign through object.__setattr__.
+            object.__setattr__(self, "label", self.name)
+
+
+@dataclass(frozen=True)
+class Config:
+    """A fully-resolved Tepyd configuration for one project."""
+
+    project_root: Path
+    src_root: str
+    src_package: str
+    units: tuple[str, ...]
+    tiers: tuple[Tier, ...]
+    exclude: dict[str, str] = field(default_factory=dict)  # name -> reason
+    counter: str = DEFAULT_COUNTER
+
+    @property
+    def src_path(self) -> Path:
+        """Absolute path to the analysed source root."""
+        return self.project_root / self.src_root
+
+    def tier(self, name: str) -> Tier:
+        for t in self.tiers:
+            if t.name == name:
+                return t
+        raise KeyError(name)
+
+
+def find_project_root(start: Path) -> Path:
+    """Walk up from ``start`` to the nearest dir holding a pyproject.toml.
+
+    Falls back to ``start`` itself if none is found, so the tool still runs
+    (against defaults) in a directory that simply has no pyproject yet.
+    """
+    start = start.resolve()
+    for candidate in (start, *start.parents):
+        if (candidate / "pyproject.toml").is_file():
+            return candidate
+    return start
+
+
+def load_config(start: Path | None = None) -> Config:
+    """Load ``[tool.tepyd]`` from the project containing ``start`` (or cwd)."""
+    root = find_project_root(start or Path.cwd())
+    raw: dict[str, Any] = {}
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        with pyproject.open("rb") as fh:
+            data = tomllib.load(fh)
+        raw = data.get("tool", {}).get("tepyd", {})
+    return build_config(root, raw)
+
+
+def build_config(project_root: Path, raw: dict[str, Any]) -> Config:
+    """Turn a parsed ``[tool.tepyd]`` table into a validated `Config`.
+
+    Separated from `load_config` so tests can feed a dict directly without
+    touching the filesystem.
+    """
+    src_root = _single_path(raw.get("src_root", DEFAULT_SRC_ROOT), "src_root")
+    src_package = _single_path(
+        raw.get("src_package", DEFAULT_SRC_PACKAGE), "src_package"
+    )
+
+    units = tuple(raw.get("units", DEFAULT_UNITS))
+    if not units:
+        raise ConfigError("`units` must list at least one glob pattern.")
+
+    tiers = _parse_tiers(raw.get("tiers"))
+    exclude = _parse_exclude(raw.get("exclude", {}))
+
+    counter = raw.get("counter", DEFAULT_COUNTER)
+    if counter not in VALID_COUNTERS:
+        raise ConfigError(
+            f"`counter` must be one of {sorted(VALID_COUNTERS)}, got {counter!r}."
+        )
+
+    return Config(
+        project_root=project_root,
+        src_root=src_root,
+        src_package=src_package,
+        units=units,
+        tiers=tiers,
+        exclude=exclude,
+        counter=counter,
+    )
+
+
+def _single_path(value: object, key: str) -> str:
+    """Accept a string today; reject (with a forward-looking message) the
+    list form reserved for monorepo support so the error is actionable."""
+    if isinstance(value, list):
+        raise ConfigError(
+            f"`{key}` as a list (monorepo mode) is not supported yet — "
+            "use a single path for now."
+        )
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"`{key}` must be a non-empty string.")
+    # Normalise a trailing slash (a natural way to write a directory) so it
+    # can't break path matching downstream (e.g. the cover lens's prefixes).
+    normalised = value.rstrip("/")
+    if not normalised:
+        raise ConfigError(f"`{key}` must be a non-empty string.")
+    return normalised
+
+
+def default_tiers() -> tuple[Tier, ...]:
+    return (
+        Tier("a_unit", "tests/a_unit", label="unit", target_share=0.60),
+        Tier("b_integration", "tests/b_integration", label="integration"),
+        Tier("c_e2e", "tests/c_e2e", label="http-e2e"),
+        Tier(
+            "e2e_playwright",
+            "e2e_playwright",
+            label="browser",
+            strip_prefix="modules/",
+        ),
+    )
+
+
+def _parse_tiers(raw_tiers: Any) -> tuple[Tier, ...]:
+    if raw_tiers is None:
+        return default_tiers()
+    if not isinstance(raw_tiers, list) or not raw_tiers:
+        raise ConfigError("`tiers` must be a non-empty array of tables.")
+
+    tiers: list[Tier] = []
+    seen: set[str] = set()
+    for i, entry in enumerate(raw_tiers):
+        if not isinstance(entry, dict):
+            raise ConfigError(f"tier #{i} must be a table.")
+        # Re-bind to an explicitly-typed local: the parsed TOML table has a
+        # dynamic value type, and narrowing alone leaves strict checkers with
+        # an unusable `dict[Unknown, Unknown]`.
+        table = cast("dict[str, Any]", entry)
+        try:
+            name = table["name"]
+            root = table["root"]
+        except KeyError as exc:
+            raise ConfigError(f"tier #{i} is missing required key {exc}.") from exc
+        if name in seen:
+            raise ConfigError(f"duplicate tier name {name!r}.")
+        seen.add(name)
+
+        target = table.get("target_share")
+        if target is not None and not (0.0 <= float(target) <= 1.0):
+            raise ConfigError(
+                f"tier {name!r}: target_share must be in [0, 1], got {target}."
+            )
+
+        tiers.append(
+            Tier(
+                name=name,
+                root=root,
+                label=table.get("label", ""),
+                target_share=target,
+                strip_prefix=table.get("strip_prefix", ""),
+                markers=tuple(table.get("markers", ())),
+            )
+        )
+    return tuple(tiers)
+
+
+def _parse_exclude(raw_exclude: Any) -> dict[str, str]:
+    """Exclusions carry a required, non-empty reason — the policy decision
+    is documented at the point it's made, and a future reader can challenge
+    it."""
+    if not isinstance(raw_exclude, dict):
+        raise ConfigError("`exclude` must be a table of name -> reason.")
+    table = cast("dict[str, Any]", raw_exclude)
+    out: dict[str, str] = {}
+    for name, reason in table.items():
+        if not isinstance(reason, str) or not reason.strip():
+            raise ConfigError(
+                f"exclude {name!r} needs a non-empty reason string "
+                "(why is this unit not tested?)."
+            )
+        out[name] = reason
+    return out