tdd-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-08-16
+
+### Added
+
+- `baseline_captured` reports `run_s` and `collect_s` alongside `elapsed_s`. The
+  suite run and the per-file collection have unrelated cost models — one scales
+  with tests, the other with files — so a single total could not say which was
+  slow, and answering that meant measuring projects by hand outside the tool.
+- `TDD_TIMING=1` emits a `command_timing` line per subprocess on stderr
+  (`label`, `command`, `cwd`, `duration_ms`, `exit_code`), covering every
+  subprocess the tool spawns: suite runs, per-file collection, lint/typecheck
+  gates, doctor probes and artifact hooks. Off by default — the per-file loop
+  would otherwise emit one line per test file on every invocation. `label` is
+  one of `suite`, `collect`, `gate`, `doctor`; an unlabelled row comes from a
+  third-party adapter, since every built-in call site names itself (R8.4).
+
+### Fixed
+
+- `tdd doctor` no longer emits a blocker it cannot explain. Every failing check
+  now carries a `detail` naming what to fix, enforced by the checklist recorder
+  so a check added later inherits the guarantee. Previously `worktree clean`
+  failed with `detail: ""`, leaving an agent with `resolve_blocker` and nothing
+  to resolve — it re-ran doctor and read the identical output.
+- `worktree clean` is scoped to dirt a run would actually read: a declared
+  project root, a declared artifact path, or `tdd.toml`. Build residue is
+  excluded via `config.is_ignored`, so doctor's own `uv run` / `vitest list`
+  probes (`.venv`, `node_modules`, caches) can no longer be what makes doctor
+  fail. Unrelated dirt is reported in the passing check's `detail` rather than
+  blocking the run.
+
 ## [0.3.0] - 2026-08-10
 
 ### Added

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Ledger-backed TDD process controller for autonomous coding agents
 Project-URL: Homepage, https://github.com/geuben/tdd-cli
 Project-URL: Repository, https://github.com/geuben/tdd-cli

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/pyproject.toml

@@ -47,7 +47,7 @@ packages = ["src/tddcli"]
 include = ["src", "tests", "examples", "README.md", "LICENSE", "CHANGELOG.md", "SECURITY.md"]
 
 [dependency-groups]
-dev = ["pytest>=8.0", "pytest-json-report>=1.5", "ruff>=0.5"]
+dev = ["pytest>=8.0", "pytest-json-report>=1.5", "ruff>=0.5", "zizmor>=1.29"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/src/tddcli/__init__.py

@@ -3,4 +3,4 @@
 State is derived from observed test execution, never asserted by the caller.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/src/tddcli/adapters/base.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 import os
 import subprocess
+import time
 from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
 
 from .. import leases
+from ..envelope import heartbeat
 
 NOT_FOUND = "not_found"
 NOT_COLLECTED = "not_collected"
@@ -78,10 +80,26 @@ def clip_failure(text: str, limit: int = 1500) -> str:
     return f"{text[:head]}\n… [clipped] …\n{text[-tail:]}"
 
 
+#: Opt-in per-command timing. Off by default: the per-file collect loop would emit
+#: one line per test file on every invocation, drowning the heartbeats that exist
+#: to make a slow baseline legible.
+TIMING_ENV = "TDD_TIMING"
+
+
 def run_command(
     command: str, cwd: Path, timeout: int = 1800,
     extra_env: dict[str, str] | None = None,
+    label: str | None = None,
 ) -> tuple[int, str, str]:
+    """Every subprocess the tool spawns passes through here, which makes it the one
+    place worth timing: suite runs, per-file collection, lint and typecheck gates,
+    doctor probes, artifact hooks.
+
+    `label` is what makes the rows groupable. This function sees a command string
+    and a cwd — not which project or phase asked for it — so an unlabelled timing
+    is readable by a human and useless to a query.
+    """
+    started = time.monotonic()
     proc = subprocess.run(
         command,
         shell=True,
@@ -91,6 +109,15 @@ def run_command(
         timeout=timeout,
         env=None if extra_env is None else {**os.environ, **extra_env},
     )
+    if os.environ.get(TIMING_ENV):
+        heartbeat(
+            event="command_timing",
+            label=label,
+            command=command,
+            cwd=str(cwd),
+            duration_ms=int((time.monotonic() - started) * 1000),
+            exit_code=proc.returncode,
+        )
     return proc.returncode, proc.stdout, proc.stderr
 
 
@@ -130,6 +157,7 @@ class Adapter:
                 command.replace("{workers}", str(workers)),
                 self.root,
                 extra_env={"TDD_WORKERS": str(workers), **(extra_env or {})},
+                label="suite",
             )
 
     def _test_cmd(self) -> str:
@@ -184,7 +212,7 @@ class Adapter:
     def _gate(self, commands: list[str]) -> GateResult:
         chunks = []
         for cmd in commands:
-            code, out, err = run_command(cmd, self.root)
+            code, out, err = run_command(cmd, self.root, label="gate")
             if code != 0:
                 chunks.append(f"$ {cmd}\n{out}\n{err}".strip())
         return GateResult(ok=not chunks, output="\n\n".join(chunks)[:4000])

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/src/tddcli/adapters/pytest_adapter.py

@@ -199,7 +199,7 @@ class PytestAdapter(Adapter):
         ]
         for cmd, env in probes:
             code, out, err = run_command(
-                f"{cmd} --collect-only -q", self.root, extra_env=env
+                f"{cmd} --collect-only -q", self.root, extra_env=env, label="doctor"
             )
             if code != 0:
                 chunks.append(out.strip())
@@ -215,7 +215,9 @@ class PytestAdapter(Adapter):
         if not self.project.overrides:
             return GateResult(ok=True)
         probe = f"{self._test_cmd().replace('{workers}', '0')} --collect-only -q"
-        code, out, err = run_command(probe, self.root, extra_env=self._suite_env(None))
+        code, out, err = run_command(
+            probe, self.root, extra_env=self._suite_env(None), label="doctor"
+        )
         reached = sorted({
             f for f in (
                 line.split("::", 1)[0]
@@ -243,6 +245,7 @@ class PytestAdapter(Adapter):
                 f"{base} --collect-only -q {shlex.quote(str(rel))}",
                 self.root,
                 extra_env=env,
+                label="collect",
             )
             if code != 0:
                 result.failed_files[str(rel)] = (err or out).strip()[:800]

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/src/tddcli/adapters/vitest_adapter.py

@@ -177,7 +177,7 @@ class VitestAdapter(Adapter):
         """
         chunks = []
         code, out, err = run_command(
-            self._collect_cmd(), self.root, extra_env=self._suite_env(None)
+            self._collect_cmd(), self.root, extra_env=self._suite_env(None), label="doctor"
         )
         if code != 0:
             chunks.append((err or out).strip())
@@ -190,7 +190,7 @@ class VitestAdapter(Adapter):
                 )
                 continue
             code, out, err = run_command(
-                ov.collect_command, self.root, extra_env=self._suite_env(ov)
+                ov.collect_command, self.root, extra_env=self._suite_env(ov), label="doctor"
             )
             if code != 0:
                 chunks.append((err or out).strip())
@@ -204,7 +204,7 @@ class VitestAdapter(Adapter):
         if not self.project.overrides:
             return GateResult(ok=True)
         code, out, err = run_command(
-            self._collect_cmd(), self.root, extra_env=self._suite_env(None)
+            self._collect_cmd(), self.root, extra_env=self._suite_env(None), label="doctor"
         )
         reached = sorted({
             f for f in (
@@ -237,7 +237,8 @@ class VitestAdapter(Adapter):
             base = ov.collect_command if ov else self._collect_cmd()
             env = self._suite_env(ov)
             code, out, err = run_command(
-                f"{base} {shlex.quote(str(rel))}", self.root, extra_env=env
+                f"{base} {shlex.quote(str(rel))}", self.root, extra_env=env,
+                label="collect",
             )
 
             payload = _extract_json(out)

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/src/tddcli/cli.py

@@ -13,6 +13,7 @@ import socket
 import sqlite3
 import sys
 import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -217,16 +218,61 @@ def _legacy_artifacts(worktree: Path) -> list[Path]:
     return sorted(found)
 
 
-def cmd_doctor(args) -> Envelope:
-    worktree = _worktree()
+def _doctor_checklist() -> tuple[list[dict], Callable]:
+    """A checks list and its recorder, which refuses a blocker it cannot explain.
+
+    `resolve_blocker` with an empty `detail` is unfalsifiable: an agent is told to
+    fix something and given nothing to fix. It re-runs doctor, reads the identical
+    output, and loops. Enforcing the detail here means a check added later inherits
+    the guarantee instead of relying on its author to remember.
+    """
     checks: list[dict] = []
 
     def check(name, ok, detail="", project=None):
+        if not ok and not str(detail).strip():
+            raise AssertionError(
+                f"doctor check {name!r} would fail silently: a failing check must"
+                " name what to fix"
+            )
         entry = {"check": name, "ok": bool(ok), "detail": detail}
         if project is not None:
             entry["project"] = project
         checks.append(entry)
 
+    return checks, check
+
+
+def _blocks_the_loop(rel_path: str, cfg) -> bool:
+    """Whether dirt at `rel_path` is somewhere a run would actually read it."""
+    if rel_path == config_mod.CONFIG_NAME:
+        return True
+    if cfg.owning_project(rel_path) is not None:
+        return True
+    return any(art.owns(rel_path) for art in cfg.artifacts.values())
+
+
+def _cleanliness_detail(blocking: list[str], unrelated: list[str]) -> str:
+    def listed(paths: list[str]) -> str:
+        head = ", ".join(paths[:5])
+        return head if len(paths) <= 5 else f"{head} (+{len(paths) - 5} more)"
+
+    if blocking:
+        return (
+            f"uncommitted changes a run would observe: {listed(blocking)}."
+            " Commit, stash, or gitignore them before `tdd run start`."
+        )
+    if unrelated:
+        return (
+            f"clean where a run reads; {len(unrelated)} unrelated path(s) left as-is:"
+            f" {listed(unrelated)}"
+        )
+    return ""
+
+
+def cmd_doctor(args) -> Envelope:
+    worktree = _worktree()
+    checks, check = _doctor_checklist()
+
     check("worktree resolvable", True, str(worktree))
     try:
         cfg = config_mod.load(worktree)
@@ -246,13 +292,20 @@ def cmd_doctor(args) -> Envelope:
         root = worktree / project.root
         check("root exists", root.is_dir(), str(root), project=name)
         check("adapter known", project.adapter in adapters.available(), project.adapter, project=name)
-        check("test_paths declared", bool(project.test_paths), project=name)
+        declared = bool(project.test_paths)
+        check(
+            "test_paths declared", declared,
+            "" if declared
+            else f"add `test_paths` to [project.{name}] in tdd.toml — without it no"
+                 " suite can be discovered for this project",
+            project=name,
+        )
         if project.adapter == "pytest":
             # The probe runs in the project's own environment (uv, poetry, pipenv,
             # pdm or the active venv) — hardcoding `uv run` here failed the check
             # on any non-uv project even with the plugin installed.
             probe = adapters.build(project, worktree).plugin_probe_cmd()
-            code, out, err = adapters.base.run_command(probe, root)
+            code, out, err = adapters.base.run_command(probe, root, label="doctor")
             check("pytest-json-report installed", code == 0, (err or "")[:200], project=name)
 
         # Run before `collectable()` so this actionable message wins over
@@ -289,11 +342,33 @@ def cmd_doctor(args) -> Envelope:
         projects[name] = {"ok": all(c["ok"] for c in checks[before:])}
 
     for art in cfg.artifacts.values():
-        check(f"artifact {art.name}: has check or regenerate", bool(art.check or art.regenerate))
+        # One evaluation feeds both `ok` and the detail: evaluating the condition
+        # twice lets them disagree, and a passing check that still says "add a hook"
+        # is the same misdirection as a failing check that says nothing.
+        has_hook = bool(art.check or art.regenerate)
+        check(
+            f"artifact {art.name}: has check or regenerate", has_hook,
+            "" if has_hook
+            else f"add `check` or `regenerate` to [artifact.{art.name}] in tdd.toml —"
+                 " freshness cannot be verified without one",
+        )
 
     stale = _legacy_artifacts(worktree)
-    check("no legacy state artifacts", not stale, ", ".join(str(s) for s in stale[:5]))
-    check("worktree clean", not gitutil.is_dirty(worktree))
+    check(
+        "no legacy state artifacts", not stale,
+        f"delete these pre-ledger state files: {', '.join(str(s) for s in stale[:5])}"
+        if stale else "",
+    )
+
+    # Only dirt a run would read can corrupt one. Blocking on everything else
+    # stopped agents on unrelated notes and editor settings, and — because the
+    # check named no path — gave them nothing to act on but a re-run. `is_ignored`
+    # also excludes doctor's own probe residue (`.venv`, `node_modules`, caches),
+    # so running doctor can no longer be what makes doctor fail.
+    dirt = sorted(p for p in gitutil.dirty_paths(worktree) if not cfg.is_ignored(p))
+    blocking = [p for p in dirt if _blocks_the_loop(p, cfg)]
+    unrelated = [p for p in dirt if p not in set(blocking)]
+    check("worktree clean", not blocking, _cleanliness_detail(blocking, unrelated))
 
     ok = all(c["ok"] for c in checks)
     return Envelope(
@@ -364,12 +439,18 @@ def _probe_projects(cfg, worktree, ledger, on_progress):
     for done, (name, project) in enumerate(cfg.projects.items(), start=1):
         adapter = adapters.build(project, worktree)
         started = time.monotonic()
-        verdict, collection = adapter.run(None), adapter.collect()
+        verdict = adapter.run(None)
+        ran = time.monotonic()
+        collection = adapter.collect()
         elapsed = time.monotonic() - started
         probes[name] = (verdict, collection)
+        # Split, not just totalled: `run` and `collect` have unrelated cost models
+        # — one scales with tests, the other with files — and a single number sends
+        # whoever asks "why was that slow?" out of the tool to measure by hand.
         heartbeat(
             event="baseline_captured", project=name,
             test_count=len(collection.tests), elapsed_s=round(elapsed, 2),
+            run_s=round(ran - started, 2), collect_s=round(elapsed - (ran - started), 2),
         )
         on_progress(done, name)
     return probes

tdd_cli-0.4.0/tests/test_doctor_blockers.py

@@ -0,0 +1,173 @@
+"""Every blocker `tdd doctor` emits must name what to fix.
+
+The incident: doctor returned `resolve_blocker` / "Resolve the failing checks above"
+with a single failing check — `{"check": "worktree clean", "ok": false, "detail": ""}`.
+The dirt was an unrelated planning note and a `.claude/settings.json` edit. The agent
+could not see either, guessed, re-ran doctor, and got the identical opaque failure.
+
+Two invariants close that loop:
+
+1. A failing check always carries a detail. `check()` raises rather than record an
+   unfalsifiable blocker, so the class cannot reappear in a check added later.
+2. Only dirt the loop would actually observe blocks — a declared project root, a
+   declared artifact, or `tdd.toml`. Everything else is reported, not enforced
+   (the PRD's "tree clean enough", §8.1).
+"""
+
+from __future__ import annotations
+
+from conftest import git, run_cli
+
+
+def _check(out: dict, name: str) -> dict:
+    matches = [c for c in out["result"]["checks"] if c["check"] == name]
+    assert len(matches) == 1, out["result"]["checks"]
+    return matches[0]
+
+
+def test_dirt_inside_a_project_root_blocks_and_names_the_path(repo):
+    (repo / "backend" / "app" / "scratch.py").write_text("x = 1\n")
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is False
+    assert "backend/app/scratch.py" in clean["detail"]
+
+
+def test_a_modified_tdd_toml_blocks(repo):
+    (repo / "tdd.toml").write_text((repo / "tdd.toml").read_text() + "\n")
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is False
+    assert "tdd.toml" in clean["detail"]
+
+
+def test_dirt_outside_every_declared_root_does_not_block(repo):
+    """The incident's own shape: a planning note and an editor setting. Neither is
+    readable by any adapter, so neither can corrupt a baseline."""
+    (repo / "tasks").mkdir()
+    (repo / "tasks" / "fix-406-proxy-ws-forwarding.md").write_text("# plan\n")
+    (repo / ".claude").mkdir()
+    (repo / ".claude" / "settings.json").write_text("{}\n")
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is True, clean
+    # Reported, not enforced — a human still wants to know the tree is not pristine.
+    assert "tasks/fix-406-proxy-ws-forwarding.md" in clean["detail"]
+
+
+def test_doctors_own_probe_residue_does_not_block(repo):
+    """Doctor shells out to `uv run` and `vitest list`, which write `.venv`,
+    `node_modules` and cache directories into the tree it then grades. Without this,
+    running doctor is what makes doctor fail — and running it again re-does it."""
+    (repo / "backend" / ".venv" / "bin").mkdir(parents=True)
+    (repo / "backend" / ".venv" / "bin" / "python").write_text("")
+    (repo / "backend" / "__pycache__").mkdir()
+    (repo / "backend" / "__pycache__" / "app.pyc").write_text("")
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is True, clean
+
+
+def test_blocking_dirt_is_reported_even_when_unrelated_dirt_exists(repo):
+    (repo / "backend" / "app" / "scratch.py").write_text("x = 1\n")
+    (repo / "notes.md").write_text("# notes\n")
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is False
+    assert "backend/app/scratch.py" in clean["detail"]
+
+
+def test_no_failing_check_is_ever_emitted_without_a_detail(repo_broken):
+    """The structural half. `repo_broken` fails collection; dirty the tree and break
+    the artifact wiring too, so several failure paths run in one invocation."""
+    (repo_broken / "verify" / "tests" / "test_extra.py").write_text("\n")
+    (repo_broken / "tdd.toml").write_text(
+        (repo_broken / "tdd.toml").read_text()
+        + '\n[artifact.openapi]\npath = "openapi.json"\nproduced_by = "backend"\n'
+    )
+
+    out = run_cli(repo_broken, "doctor")
+    failing = [c for c in out["result"]["checks"] if not c["ok"]]
+    assert failing, out["result"]["checks"]
+    for c in failing:
+        assert c["detail"].strip(), c
+
+
+def test_a_check_cannot_fail_without_a_detail():
+    """Enforced at the helper, so a check added later inherits the guarantee rather
+    than relying on its author to remember."""
+    import pytest
+
+    from tddcli.cli import _doctor_checklist
+
+    checks, check = _doctor_checklist()
+    check("fine", False, "here is what to do")
+    with pytest.raises(AssertionError, match="silent"):
+        check("silent", False)
+    assert [c["check"] for c in checks] == ["fine"]
+
+
+def _with_artifact(repo, hook: str = 'regenerate = "true"') -> None:
+    (repo / "schema").mkdir(exist_ok=True)
+    (repo / "schema" / "openapi.json").write_text("{}\n")
+    (repo / "tdd.toml").write_text(
+        (repo / "tdd.toml").read_text()
+        + f'\n[artifact.openapi]\npath = "schema/openapi.json"\n'
+          f'produced_by = "backend"\n{hook}\n'
+    )
+    git(repo, "add", "-A")
+    git(repo, "commit", "-q", "-m", "declare openapi artifact")
+
+
+def test_dirt_at_a_declared_artifact_path_blocks(repo):
+    """An artifact sits outside every project root but is still read by a run —
+    `run start` verifies its freshness. Uncommitted drift there is exactly the
+    staleness the artifact edge exists to catch."""
+    _with_artifact(repo)
+    (repo / "schema" / "openapi.json").write_text('{"drift": true}\n')
+
+    clean = _check(run_cli(repo, "doctor"), "worktree clean")
+    assert clean["ok"] is False
+    assert "schema/openapi.json" in clean["detail"]
+
+
+def test_an_artifact_needs_only_one_of_check_or_regenerate(repo):
+    """Either hook alone makes freshness verifiable — requiring both would fail
+    every artifact that only knows how to rebuild itself."""
+    _with_artifact(repo, hook='regenerate = "true"')
+
+    assert _check(run_cli(repo, "doctor"), "artifact openapi: has check or regenerate")["ok"] is True
+
+    _check_only = repo / "tdd.toml"
+    _check_only.write_text(_check_only.read_text().replace('regenerate = "true"', 'check = "true"'))
+    git(repo, "add", "-A")
+    git(repo, "commit", "-q", "-m", "swap regenerate for check")
+
+    assert _check(run_cli(repo, "doctor"), "artifact openapi: has check or regenerate")["ok"] is True
+
+
+def test_a_long_dirt_list_is_truncated_but_the_fifth_path_is_not(repo):
+    """The detail is read by an agent, so it stays bounded — but the boundary must
+    not eat a path it had room for."""
+    for i in range(5):
+        (repo / "backend" / "app" / f"f{i}.py").write_text("x = 1\n")
+
+    detail = _check(run_cli(repo, "doctor"), "worktree clean")["detail"]
+    assert "more)" not in detail, detail
+    assert "backend/app/f4.py" in detail
+
+    (repo / "backend" / "app" / "f5.py").write_text("x = 1\n")
+    detail = _check(run_cli(repo, "doctor"), "worktree clean")["detail"]
+    assert "(+1 more)" in detail, detail
+
+
+def test_test_paths_omission_says_what_to_add(repo):
+    (repo / "tdd.toml").write_text(
+        '[project.backend]\nroot = "backend"\nadapter = "pytest"\ntest_paths = []\n'
+    )
+    git(repo, "add", "-A")
+    git(repo, "commit", "-q", "-m", "drop test_paths")
+
+    declared = _check(run_cli(repo, "doctor"), "test_paths declared")
+    assert declared["ok"] is False
+    assert "test_paths" in declared["detail"]

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/tests/test_failure_clipping.py

@@ -46,7 +46,7 @@ def test_pytest_target_failure_keeps_the_error_at_the_tail(tmp_path, monkeypatch
     adapter = _pytest_adapter(tmp_path)
     longrepr = ("connector frame\n" * 300) + "ConnectionRefusedError: [Errno 61]"
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         marker = "--json-report-file="
         path = command.split(marker, 1)[1].split(" --", 1)[0]
         Path(path.strip("'\"")).write_text(json.dumps({

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/tests/test_project_commands.py

@@ -62,7 +62,7 @@ def test_only_reporting_flags_are_appended(tmp_path, monkeypatch):
     adapter = adapters.build(project, tmp_path)
     seen = {}
 
-    def fake_run(command, cwd, timeout=1800, extra_env=None):
+    def fake_run(command, cwd, timeout=1800, extra_env=None, label=None):
         seen["command"] = command
         return 1, "", "no report"
 

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/tests/test_project_env.py

@@ -54,7 +54,7 @@ def test_default_suite_runs_with_the_project_env_expanded(tmp_path, monkeypatch)
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append((command, extra_env))
         marker = "--json-report-file="
         path = command.split(marker, 1)[1].split(" --", 1)[0]
@@ -95,7 +95,7 @@ def test_pytest_collection_of_default_files_carries_the_project_env(
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append((command, extra_env))
         return 0, "tests/test_a.py::test_a\n", ""
 
@@ -114,7 +114,7 @@ def test_vitest_default_suite_runs_with_the_project_env(tmp_path, monkeypatch):
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append((command, extra_env))
         return 0, json.dumps({"testResults": []}), ""
 

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/tests/test_suite_overrides.py

@@ -110,7 +110,7 @@ def _fake_pytest_run(reports_by_prefix: dict[str, dict], seen: list):
     """A run_command double that answers each suite command with its own report,
     keyed by command prefix, writing the JSON where the real plugin would."""
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append((command, extra_env))
         for prefix, report in reports_by_prefix.items():
             if command.startswith(prefix):
@@ -195,7 +195,7 @@ def test_pytest_broken_override_suite_is_a_loud_error_not_a_silent_gap(
     project = project_with(tmp_path, 'test_command = "pytest tests"\n' + OVERRIDE_BLOCK)
     adapter = adapters.build(project, tmp_path)
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         if command.startswith("pytest contract"):
             return 4, "", "ERROR: file or directory not found: contract"
         marker = "--json-report-file="
@@ -222,7 +222,7 @@ def test_pytest_collection_routes_override_files_to_the_override_command(
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append((command, extra_env))
         name = "test_api.py::test_ping" if "contract" in command else "test_a.py::test_a"
         return 0, name, ""
@@ -272,7 +272,7 @@ def test_vitest_run_finds_a_target_that_only_the_override_config_reaches(
     project = project_with(tmp_path, VITEST_OVERRIDE, adapter="vitest")
     adapter = adapters.build(project, tmp_path)
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         if "--config vitest.contract.config.ts" in command:
             report = _vitest_report(
                 str(tmp_path / "backend" / "contract" / "api.contract.test.ts"),
@@ -331,7 +331,7 @@ def test_vitest_collection_routes_override_files_to_the_override_command(
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append(command)
         return 0, "contract/api.contract.test.ts > pings the api", ""
 
@@ -479,7 +479,7 @@ def test_vitest_duplicate_test_id_across_suites_is_a_loud_error(
             ]
         }
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         if "--config" in command:
             return 0, json.dumps(result("passed")), ""
         return 1, json.dumps(result("failed")), ""
@@ -500,7 +500,7 @@ def test_pytest_isolation_probe_flags_default_reach_into_override_files(
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append(command)
         return 0, (
             "tests/test_a.py::test_a\n"
@@ -528,7 +528,7 @@ def test_pytest_isolation_probe_passes_when_the_default_suite_is_scoped(
     monkeypatch.setattr(
         adapters.pytest_adapter,
         "run_command",
-        lambda command, cwd, timeout=1800, extra_env=None: (
+        lambda command, cwd, timeout=1800, extra_env=None, label=None: (
             0, "tests/test_a.py::test_a\n", ""
         ),
     )
@@ -550,7 +550,7 @@ def test_vitest_isolation_probe_flags_default_reach_into_override_files(
     adapter = adapters.build(project, tmp_path)
     seen: list = []
 
-    def fake(command, cwd, timeout=1800, extra_env=None):
+    def fake(command, cwd, timeout=1800, extra_env=None, label=None):
         seen.append(command)
         return 0, (
             "src/__tests__/a.test.ts > adds\n"
@@ -570,7 +570,7 @@ def test_isolation_probe_is_free_when_a_project_declares_no_overrides(
     project = project_with(tmp_path, 'test_command = "pytest tests"\n')
     adapter = adapters.build(project, tmp_path)
 
-    def explode(command, cwd, timeout=1800, extra_env=None):
+    def explode(command, cwd, timeout=1800, extra_env=None, label=None):
         raise AssertionError("no probe should run without overrides")
 
     monkeypatch.setattr(adapters.pytest_adapter, "run_command", explode)

tdd_cli-0.4.0/tests/test_timing_visibility.py

@@ -0,0 +1,149 @@
+"""Where a slow command actually spent its time.
+
+A `run start` took 23 minutes and reported one number per project — `elapsed_s`,
+covering `run()` and `collect()` together. Answering "which of the two?" required
+measuring the projects by hand, outside the tool, in a different checkout; the
+warm numbers that produced did not match the cold ones and the first diagnosis
+drawn from them was wrong.
+
+The tool already holds both timings at the moment it discards them. Two seams
+make them visible:
+
+* `baseline_captured` reports `run_s` and `collect_s` separately, so the split is
+  in the output the agent already prints.
+* `run_command` — the single choke point every subprocess passes through — emits a
+  `command_timing` line under `TDD_TIMING=1`, which attributes cost per command:
+  per-file collection, gates, doctor probes, artifact hooks. Off by default,
+  because the per-file loop would otherwise emit one line per test file on every
+  invocation.
+"""
+
+from __future__ import annotations
+
+import json
+
+from conftest import run_cli, write_plan
+from tddcli.adapters import base
+
+PLAN = """---
+cycles:
+  - n: 1
+    project: backend
+    title: "adding two numbers"
+    test: "tests/test_add.py::test_add_two_numbers"
+    stub_expected: ["app/calc.py"]
+    commit_red: "test: adding two numbers"
+    commit_green: "feat: add()"
+---
+
+# Plan
+"""
+
+
+def _lines(stderr: str, event: str) -> list[dict]:
+    found = []
+    for line in stderr.splitlines():
+        try:
+            payload = json.loads(line.strip())
+        except json.JSONDecodeError:
+            continue
+        if payload.get("event") == event:
+            found.append(payload)
+    return found
+
+
+def _start(repo):
+    plan = write_plan(repo, PLAN)
+    assert run_cli(repo, "plan", "register", plan)["ok"]
+    return run_cli(repo, "run", "start", "--plan", plan)
+
+
+def test_baseline_reports_run_and_collect_separately(repo, capsys):
+    out = _start(repo)
+    assert out["ok"], out
+
+    backend = next(
+        line for line in _lines(capsys.readouterr().err, "baseline_captured")
+        if line["project"] == "backend"
+    )
+    assert isinstance(backend["run_s"], (int, float)), backend
+    assert isinstance(backend["collect_s"], (int, float)), backend
+
+
+def test_the_split_still_adds_up_to_the_reported_total(repo, capsys):
+    """`elapsed_s` stays, so existing consumers keep working — and it must remain
+    the sum of the parts, or the split is describing a different thing."""
+    out = _start(repo)
+    assert out["ok"], out
+
+    backend = next(
+        line for line in _lines(capsys.readouterr().err, "baseline_captured")
+        if line["project"] == "backend"
+    )
+    assert backend["run_s"] + backend["collect_s"] <= backend["elapsed_s"] + 0.05
+    assert backend["elapsed_s"] - (backend["run_s"] + backend["collect_s"]) < 0.5
+
+
+def test_command_timing_is_silent_unless_asked_for(repo, capsys, monkeypatch):
+    monkeypatch.delenv(base.TIMING_ENV, raising=False)
+    assert _start(repo)["ok"]
+    assert _lines(capsys.readouterr().err, "command_timing") == []
+
+
+def test_command_timing_names_the_command_and_its_cost(repo, capsys, monkeypatch):
+    monkeypatch.setenv(base.TIMING_ENV, "1")
+    assert _start(repo)["ok"]
+
+    timings = _lines(capsys.readouterr().err, "command_timing")
+    assert timings, "TDD_TIMING=1 produced no command_timing lines"
+    for entry in timings:
+        assert isinstance(entry["duration_ms"], int)
+        assert entry["command"]
+        assert isinstance(entry["exit_code"], int)
+
+
+def test_a_timed_command_is_attributed_to_its_caller(repo, capsys, monkeypatch):
+    """Without a label the rows are readable but not groupable: `run_command` sees
+    a command string and a cwd, not which project or phase asked for it."""
+    monkeypatch.setenv(base.TIMING_ENV, "1")
+    assert _start(repo)["ok"]
+
+    timings = _lines(capsys.readouterr().err, "command_timing")
+    labels = {entry.get("label") for entry in timings}
+    assert "suite" in labels, labels
+    assert "collect" in labels, labels
+
+
+def test_the_per_file_collect_loop_is_attributed_per_file(repo, capsys, monkeypatch):
+    """The loop's cost is per file, so its timing has to be too — a single total
+    cannot say which file is slow."""
+    monkeypatch.setenv(base.TIMING_ENV, "1")
+    assert _start(repo)["ok"]
+
+    collects = [
+        entry for entry in _lines(capsys.readouterr().err, "command_timing")
+        if entry.get("label") == "collect"
+    ]
+    assert collects, "no collect timings"
+    assert any("test_smoke.py" in entry["command"] for entry in collects), collects
+
+
+def test_doctor_probes_are_labelled_as_doctor(repo, capsys, monkeypatch):
+    """Doctor's probes reach `run_command` from three places — the reporter check
+    in `cmd_doctor`, `collectable()` and `override_isolation()` — and both adapter
+    methods are called from nowhere else. Unlabelled they arrive as `label: null`,
+    indistinguishable from a third-party adapter's unlabelled call."""
+    monkeypatch.setenv(base.TIMING_ENV, "1")
+    assert run_cli(repo, "doctor")["ok"]
+
+    timings = _lines(capsys.readouterr().err, "command_timing")
+    assert timings, "TDD_TIMING=1 produced no command_timing lines for doctor"
+    assert {entry.get("label") for entry in timings} == {"doctor"}, timings
+
+
+def test_timing_does_not_disturb_the_command_result(repo, monkeypatch):
+    """The wrapper returns exactly what the subprocess returned."""
+    monkeypatch.setenv(base.TIMING_ENV, "1")
+    code, out, err = base.run_command("echo hello", repo)
+    assert code == 0
+    assert out.strip() == "hello"

{tdd_cli-0.3.0 → tdd_cli-0.4.0}/tests/test_worker_leases.py

@@ -127,7 +127,7 @@ def test_live_foreign_lease_counts(lease_dir):
 def recorded(monkeypatch):
     calls: list[dict] = []
 
-    def stub(command, cwd, timeout=1800, extra_env=None):
+    def stub(command, cwd, timeout=1800, extra_env=None, label=None):
         calls.append({"command": command, "cwd": cwd, "extra_env": extra_env})
         return 1, "", ""