tdd-cli 0.1.0__py3-none-any.whl

tddcli/config.py

@@ -0,0 +1,255 @@
+"""tdd.toml — the project registry and artifact graph (§7.1).
+
+Roots are declared, never discovered by scanning for marker files (R7.1): two
+projects in one repo can share a marker, and directory-listing order must not decide
+which suite runs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import tomllib
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+from pathlib import Path
+
+CONFIG_NAME = "tdd.toml"
+
+#: Build output the tool must never author, regardless of the repository's .gitignore.
+#: Without this, a run in a repo lacking a .gitignore commits __pycache__ alongside
+#: the test it was asked to commit.
+DEFAULT_IGNORES = (
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".coverage",
+    "htmlcov",
+    ".DS_Store",
+    ".tox",
+    "*.pyc",
+    "*.pyo",
+    "*.egg-info",
+)
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+@dataclass
+class Project:
+    name: str
+    root: str
+    adapter: str
+    test_paths: list[str] = field(default_factory=list)
+    lint: list[str] = field(default_factory=list)
+    typecheck: list[str] = field(default_factory=list)
+    in_close_sweep: bool = True
+    #: The project's own suite command. Without this the tool runs its adapter's
+    #: default invocation, which can differ from what the project actually runs —
+    #: parallelism, plugins, markers — so the suite under TDD is not the suite the
+    #: team trusts. The adapter appends only its reporting flags.
+    test_command: str | None = None
+    #: Per-file collection. Must not be parallelised: collection is cheap and xdist
+    #: adds startup cost per file.
+    collect_command: str | None = None
+
+    def owns(self, rel_path: str) -> bool:
+        if self.root == ".":     # single-project repo: the root is the worktree itself
+            return True
+        return rel_path == self.root or rel_path.startswith(self.root.rstrip("/") + "/")
+
+    def relative_to_root(self, rel_path: str) -> str:
+        prefix = self.root.rstrip("/") + "/"
+        return rel_path[len(prefix):] if rel_path.startswith(prefix) else rel_path
+
+    def is_test_file(self, rel_path: str) -> bool:
+        """rel_path is relative to the worktree root."""
+        if not self.owns(rel_path):
+            return False
+        inner = self.relative_to_root(rel_path)
+        for pattern in self.test_paths:
+            if pattern.endswith("/"):
+                if inner.startswith(pattern):
+                    return True
+            elif fnmatch(inner, pattern) or fnmatch(rel_path, pattern):
+                return True
+            elif inner.startswith(pattern.rstrip("/") + "/"):
+                return True
+        return False
+
+
+@dataclass
+class Artifact:
+    name: str
+    path: str
+    produced_by: str
+    regenerate: str | None = None
+    check: str | None = None
+    consumed_by: list[str] = field(default_factory=list)
+    generated: bool = False
+
+    @property
+    def upstream_artifact(self) -> str | None:
+        if self.produced_by.startswith("artifact."):
+            return self.produced_by.split(".", 1)[1]
+        return None
+
+    def owns(self, rel_path: str) -> bool:
+        p = self.path.rstrip("/")
+        return rel_path == p or rel_path.startswith(p + "/")
+
+
+@dataclass
+class Config:
+    worktree: Path
+    projects: dict[str, Project]
+    artifacts: dict[str, Artifact]
+    ignores: tuple[str, ...] = DEFAULT_IGNORES
+
+    def is_ignored(self, rel_path: str) -> bool:
+        parts = Path(rel_path).parts
+        for pattern in self.ignores:
+            if any(fnmatch(part, pattern) for part in parts):
+                return True
+            if fnmatch(rel_path, pattern):
+                return True
+        return False
+
+    def project(self, name: str) -> Project:
+        if name not in self.projects:
+            raise ConfigError(
+                f"unknown project {name!r}; registered: {sorted(self.projects)}"
+            )
+        return self.projects[name]
+
+    def owning_project(self, rel_path: str) -> Project | None:
+        # Longest root wins, so nested roots resolve deterministically; a "." root
+        # counts as length zero so any nested root beats the repo-root project.
+        def depth(p: Project) -> int:
+            return 0 if p.root == "." else len(p.root)
+
+        best = None
+        for proj in self.projects.values():
+            if proj.owns(rel_path) and (best is None or depth(proj) > depth(best)):
+                best = proj
+        return best
+
+    def is_generated(self, rel_path: str) -> bool:
+        """R7.7 — generated output is excluded from authorship accounting."""
+        return any(art.owns(rel_path) for art in self.artifacts.values() if art.generated)
+
+    def artifact_chain(self, art: Artifact) -> list[Artifact]:
+        """`art` plus every upstream artifact its regenerate hook may refresh."""
+        chain, seen = [art], {art.name}
+        while (up := chain[-1].upstream_artifact) is not None and up not in seen:
+            chain.append(self.artifacts[up])
+            seen.add(up)
+        return chain
+
+    def close_sweep_projects(self, cycle_projects: list[str], touched: set[str]) -> list[str]:
+        """R9.2 — the cycle's own projects, plus anything downstream of an artifact it touched."""
+        names = {n for n in cycle_projects}
+        for art in self.artifacts.values():
+            if self._artifact_touched(art, touched):
+                names.update(art.consumed_by)
+        return [n for n in sorted(names) if self.projects[n].in_close_sweep]
+
+    def _artifact_touched(self, art: Artifact, touched: set[str]) -> bool:
+        producer = art.produced_by
+        if producer.startswith("artifact."):
+            upstream = self.artifacts.get(producer.split(".", 1)[1])
+            return bool(upstream and self._artifact_touched(upstream, touched))
+        proj = self.projects.get(producer)
+        if proj is None:
+            return False
+        return any(proj.owns(p) for p in touched)
+
+    def full_sweep_projects(self) -> list[str]:
+        return sorted(self.projects)
+
+
+def config_sha(worktree: Path) -> str:
+    """Hash of tdd.toml as it stands in the working tree.
+
+    The registry is deliberately a reviewed, branch-scoped file rather than ledger
+    state — but that makes it editable mid-run, and one edit is load-bearing:
+    widening `test_paths` to match implementation files would silently disable the
+    RED-commit classification that detects implementation written during RED. The
+    ledger pins this hash at run start so the drift surfaces.
+    """
+    path = worktree / CONFIG_NAME
+    return hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else ""
+
+
+def find_config(start: Path) -> Path | None:
+    cur = start.resolve()
+    for candidate in [cur, *cur.parents]:
+        if (candidate / CONFIG_NAME).is_file():
+            return candidate / CONFIG_NAME
+    return None
+
+
+def load(worktree: Path) -> Config:
+    path = worktree / CONFIG_NAME
+    if not path.is_file():
+        raise ConfigError(f"no {CONFIG_NAME} at {worktree}")
+    raw = tomllib.loads(path.read_text())
+
+    projects: dict[str, Project] = {}
+    for name, body in (raw.get("project") or {}).items():
+        if "root" not in body:
+            raise ConfigError(f"project {name!r} has no root")
+        if "adapter" not in body:
+            raise ConfigError(f"project {name!r} has no adapter")
+        projects[name] = Project(
+            name=name,
+            root=body["root"].rstrip("/"),
+            adapter=body["adapter"],
+            test_paths=body.get("test_paths", []),
+            lint=body.get("lint", []),
+            typecheck=body.get("typecheck", []),
+            in_close_sweep=body.get("in_close_sweep", True),
+            test_command=body.get("test_command"),
+            collect_command=body.get("collect_command"),
+        )
+
+    artifacts: dict[str, Artifact] = {}
+    for name, body in (raw.get("artifact") or {}).items():
+        artifacts[name] = Artifact(
+            name=name,
+            path=body["path"],
+            produced_by=body["produced_by"],
+            regenerate=body.get("regenerate"),
+            check=body.get("check"),
+            consumed_by=body.get("consumed_by", []),
+            generated=body.get("generated", False),
+        )
+
+    for art in artifacts.values():
+        up = art.upstream_artifact
+        if up is not None and up not in artifacts:
+            raise ConfigError(f"artifact {art.name!r} names unknown upstream artifact {up!r}")
+        if up is None and art.produced_by not in projects:
+            raise ConfigError(
+                f"artifact {art.name!r} produced_by unknown project {art.produced_by!r}"
+            )
+        for c in art.consumed_by:
+            if c not in projects:
+                raise ConfigError(f"artifact {art.name!r} consumed_by unknown project {c!r}")
+
+    if not projects:
+        raise ConfigError("no projects registered")
+    extra = tuple(raw.get("ignore", []))
+    return Config(
+        worktree=worktree,
+        projects=projects,
+        artifacts=artifacts,
+        ignores=DEFAULT_IGNORES + extra,
+    )

tddcli/contract.py

@@ -0,0 +1,237 @@
+"""Plan contracts from YAML front-matter, hashed at the committed blob (§7.2).
+
+The plan's *commit* is the contract, so a planning agent needs no integration with
+this tool and an implementing agent cannot quietly move its own goalposts: editing
+front-matter mid-run changes the blob and raises `plan_blob_changed` (R7.11).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from . import gitutil
+from .config import Config
+
+FENCE = "---"
+
+STANDARD = "standard"
+PIN = "pin"
+CONTRACT = "contract"
+REFACTOR = "refactor"
+
+
+class ContractError(RuntimeError):
+    """Malformed front-matter. Hard-fails registration (R7.10)."""
+
+
+@dataclass
+class DeclaredCycle:
+    ordinal: int
+    kind: str
+    projects: list[str]
+    tests: list[str]
+    title: str = ""
+    files: list[str] = field(default_factory=list)
+    stub_expected: list[str] = field(default_factory=list)
+    modifies_tests: list[str] = field(default_factory=list)
+    commit_messages: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "n": self.ordinal,
+            "kind": self.kind,
+            "projects": self.projects,
+            "tests": self.tests,
+            "title": self.title,
+            "files": self.files,
+            "stub_expected": self.stub_expected,
+            "modifies_tests": self.modifies_tests,
+            "commit_messages": self.commit_messages,
+        }
+
+    @staticmethod
+    def from_dict(d: dict) -> "DeclaredCycle":
+        return DeclaredCycle(
+            ordinal=d["n"],
+            kind=d["kind"],
+            projects=d["projects"],
+            tests=d["tests"],
+            title=d.get("title", ""),
+            files=d.get("files", []),
+            stub_expected=d.get("stub_expected", []),
+            modifies_tests=d.get("modifies_tests", []),
+            commit_messages=d.get("commit_messages", {}),
+        )
+
+
+@dataclass
+class PlanContract:
+    plan_path: str
+    status: str                      # declared | undeclared
+    cycles: list[DeclaredCycle]
+    annotation_keys: list[str]
+    blob_sha: str | None = None
+    commit_sha: str | None = None
+
+
+def split_front_matter(text: str) -> str | None:
+    """Return the raw YAML block, or None when there is no front-matter at all."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != FENCE:
+        return None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == FENCE:
+            return "\n".join(lines[1:i])
+    return None
+
+
+def _as_list(value, field_name: str, ordinal: int) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list) and all(isinstance(v, str) for v in value):
+        return list(value)
+    raise ContractError(f"cycle {ordinal}: {field_name} must be a string or list of strings")
+
+
+def parse_cycle(raw: dict, config: Config | None) -> DeclaredCycle:
+    if not isinstance(raw, dict):
+        raise ContractError(f"each cycle must be a mapping, got {type(raw).__name__}")
+    if "n" not in raw:
+        raise ContractError("every cycle needs an `n` ordinal")
+    ordinal = raw["n"]
+    if not isinstance(ordinal, int):
+        raise ContractError(f"cycle ordinal must be an integer, got {ordinal!r}")
+
+    flags = [
+        name for name, key in (
+            (PIN, "pin_cycle"),
+            (CONTRACT, "contract_cycle"),
+            (REFACTOR, "refactor_cycle"),
+        ) if raw.get(key)
+    ]
+    if len(flags) > 1:
+        raise ContractError(
+            f"cycle {ordinal}: cycle kinds are exclusive, got {flags}"
+        )
+    kind = flags[0] if flags else STANDARD
+
+    tests = _as_list(raw.get("tests") or raw.get("test"), "test", ordinal)
+    projects = _as_list(raw.get("projects") or raw.get("project"), "project", ordinal)
+    if not projects:
+        raise ContractError(f"cycle {ordinal}: no project declared")
+
+    # A refactor cycle changes structure without changing behaviour: existing tests are
+    # the guard, so it has no target of its own and opens straight into refactor.
+    if kind == REFACTOR and tests:
+        raise ContractError(
+            f"cycle {ordinal}: a refactor cycle declares no test — the existing suite"
+            " is the guard. Use a pin cycle if new behaviour must be characterised first."
+        )
+    if kind != REFACTOR and not tests:
+        raise ContractError(
+            f"cycle {ordinal}: no test declared. Mark it `refactor_cycle: true` if it"
+            " is behaviour-preserving with no new test."
+        )
+
+    if len(tests) > 1 and kind != CONTRACT:
+        raise ContractError(
+            f"cycle {ordinal}: {len(tests)} tests declared but this is not a contract cycle."
+            " One behaviour per cycle (R9.8)."
+        )
+    if kind == CONTRACT and len(tests) < 2:
+        raise ContractError(
+            f"cycle {ordinal}: contract cycles must declare more than one target test"
+        )
+
+    if config is not None:
+        for name in projects:
+            if name not in config.projects:
+                raise ContractError(
+                    f"cycle {ordinal}: unknown project {name!r};"
+                    f" registered: {sorted(config.projects)}"
+                )
+
+    commits = {}
+    for phase_key in ("red", "green", "refactor", "pin"):
+        msg = raw.get(f"commit_{phase_key}")
+        if msg is not None:
+            if not isinstance(msg, str):
+                raise ContractError(f"cycle {ordinal}: commit_{phase_key} must be a string")
+            commits[phase_key] = msg
+
+    return DeclaredCycle(
+        ordinal=ordinal,
+        kind=kind,
+        projects=projects,
+        tests=tests,
+        title=raw.get("title", ""),
+        files=_as_list(raw.get("files"), "files", ordinal),
+        stub_expected=_as_list(raw.get("stub_expected"), "stub_expected", ordinal),
+        modifies_tests=_as_list(raw.get("modifies_tests"), "modifies_tests", ordinal),
+        commit_messages=commits,
+    )
+
+
+def parse(text: str, plan_path: str, config: Config | None = None) -> PlanContract:
+    """Absent front-matter is legitimate (R7.9); malformed front-matter is a defect (R7.10)."""
+    block = split_front_matter(text)
+    if block is None:
+        return PlanContract(plan_path=plan_path, status="undeclared", cycles=[], annotation_keys=[])
+
+    try:
+        data = yaml.safe_load(block)
+    except yaml.YAMLError as exc:
+        raise ContractError(f"front-matter is not valid YAML: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ContractError("front-matter must be a mapping")
+    if "cycles" not in data:
+        raise ContractError("front-matter present but declares no `cycles`")
+    if not isinstance(data["cycles"], list) or not data["cycles"]:
+        raise ContractError("`cycles` must be a non-empty list")
+
+    cycles = [parse_cycle(c, config) for c in data["cycles"]]
+    ordinals = [c.ordinal for c in cycles]
+    if len(set(ordinals)) != len(ordinals):
+        raise ContractError(f"duplicate cycle ordinals: {ordinals}")
+    cycles.sort(key=lambda c: c.ordinal)
+
+    keys = data.get("annotation_keys", [])
+    if not isinstance(keys, list) or not all(isinstance(k, str) for k in keys):
+        raise ContractError("annotation_keys must be a list of strings")
+
+    return PlanContract(
+        plan_path=plan_path,
+        status="declared",
+        cycles=cycles,
+        annotation_keys=keys,
+    )
+
+
+def register(worktree: Path, plan_rel: str, config: Config | None) -> PlanContract:
+    """Read the plan as committed — never the working-tree copy."""
+    try:
+        blob, commit = gitutil.blob_sha_at_head(worktree, plan_rel)
+        text = gitutil.show_at_head(worktree, plan_rel)
+    except gitutil.GitError as exc:
+        raise ContractError(
+            f"{plan_rel} must be committed before registration: {exc}"
+        ) from exc
+    contract = parse(text, plan_rel, config)
+    contract.blob_sha = blob
+    contract.commit_sha = commit
+    return contract
+
+
+def cycles_to_json(cycles: list[DeclaredCycle]) -> str:
+    return json.dumps([c.to_dict() for c in cycles])
+
+
+def cycles_from_json(blob: str) -> list[DeclaredCycle]:
+    return [DeclaredCycle.from_dict(d) for d in json.loads(blob)]

tddcli/envelope.py

@@ -0,0 +1,96 @@
+"""Output envelope and the closed next_action verb set (R8.3a).
+
+`verb` is the authority on control flow. `detail` is human-readable and explicitly
+non-authoritative — skills and hooks dispatch on the verb, never on the prose.
+Adding a verb is a specification change.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass, field
+from enum import Enum
+
+VERB_SET_VERSION = 2
+
+#: Version of the envelope shape itself — the top-level keys and their meaning.
+#: Harness hooks and skills parse this structure programmatically; bump it on any
+#: change to the shape so consumers can detect drift instead of breaking silently.
+ENVELOPE_VERSION = 1
+
+
+class Verb(str, Enum):
+    WRITE_TEST = "write_test"
+    WRITE_IMPLEMENTATION = "write_implementation"
+    CREATE_STUB = "create_stub"
+    FIX_REGRESSION = "fix_regression"
+    RUN_SENSITIVITY_CHECK = "run_sensitivity_check"
+    NAME_TARGET_TEST = "name_target_test"
+    REFACTOR_OR_ADVANCE = "refactor_or_advance"
+    CONFIRM_CYCLE_APPLICABLE = "confirm_cycle_applicable"
+    ANNOTATE_CYCLE = "annotate_cycle"
+    RESOLVE_BLOCKER = "resolve_blocker"
+    AWAIT_BASELINE = "await_baseline"
+    COMPLETE = "complete"
+    BLOCKED = "blocked"
+
+
+TERMINAL_VERBS = {Verb.COMPLETE, Verb.BLOCKED}
+
+
+@dataclass
+class NextAction:
+    verb: Verb
+    detail: str
+
+    @property
+    def terminal(self) -> bool:
+        return self.verb in TERMINAL_VERBS
+
+    def to_dict(self) -> dict:
+        return {
+            "verb": self.verb.value,
+            "detail": self.detail,
+            "terminal": self.terminal,
+            "verb_set_version": VERB_SET_VERSION,
+        }
+
+
+@dataclass
+class Envelope:
+    ok: bool = True
+    run: dict | None = None
+    result: dict = field(default_factory=dict)
+    next_action: NextAction | None = None
+    error: str | None = None
+    #: Set by commands that have already written human-readable output. The envelope
+    #: is still returned (tests assert on it) but is not printed alongside the prose.
+    silent: bool = False
+
+    def to_dict(self) -> dict:
+        out: dict = {"ok": self.ok, "envelope_version": ENVELOPE_VERSION}
+        if self.error is not None:
+            out["error"] = self.error
+        out["run"] = self.run
+        out["result"] = self.result
+        out["next_action"] = self.next_action.to_dict() if self.next_action else None
+        return out
+
+    def emit(self) -> int:
+        if not self.silent:
+            json.dump(self.to_dict(), sys.stdout, indent=2, default=str)
+            sys.stdout.write("\n")
+        return 0 if self.ok else 1
+
+
+def failure(error: str, **result) -> Envelope:
+    return Envelope(ok=False, error=error, result=result)
+
+
+def heartbeat(**fields) -> None:
+    """A progress line on stderr. Never stdout — PRD §8's envelope
+    contract lives there, and NDJSON in front of it breaks every consumer that does
+    `json.loads(stdout)`. `flush=True` is not optional: unflushed output defeats the
+    entire purpose of making a slow baseline legible while it runs."""
+    print(json.dumps(fields), file=sys.stderr, flush=True)