constant-docs 0.4.0__py3-none-any.whl

constant_docs/auto.py

@@ -0,0 +1,239 @@
+"""Unattended regeneration, without putting a model in the package.
+
+The hooks this tool ships need a live agent session. The case `auto` is bought
+for is a fleet where changes arrive from a chat client, a timer, and a person
+editing files directly — three write paths, none of which fires a hook. A tool
+whose automation only works inside one harness is not automated for that.
+
+So `auto` runs a **command declared in configuration**, and then checks what it
+left behind:
+
+```yaml
+auto:
+  command: "<your agent> -p 'Run the constant-docs settle loop'"
+  when: stale
+  budget: 5
+```
+
+Three properties follow, and each is why this shape rather than a built-in
+client:
+
+- **No credential in the tool, and none needed in CI.** The property that makes
+  `verify` safe to run anywhere survives untouched
+- **A new harness is a configuration line.** The command is split with `shlex`
+  and run directly, so an agent CLI, a script and a Makefile target all work
+- **The command's success is not taken on trust.** `auto` re-runs `verify`
+  afterwards and fails if the documents are still stale. An automation that
+  fires a command and assumes it worked reports success without checking, which
+  is the failure this project has now found repeatedly
+
+## The exit codes, which must not collapse
+
+| Code | Meaning |
+|---|---|
+| 0 | The command ran and everything is clean afterwards |
+| 1 | The command ran and something is still stale |
+| 2 | The command could not run, or exited non-zero |
+
+A command that ran and achieved nothing is a working automation producing no
+result. A command that could not run is a broken one. A scheduler that cannot
+tell them apart retries the wrong one.
+
+> [!warning] This executes a command from the repository's configuration
+> `auto` is the only thing here that runs anything, and what it runs is whatever
+> `constant-docs.yaml` says. That is the same trust model as a Makefile or a
+> package script — but it is worth stating, because nothing else in this tool
+> has it. Three things bound it: it never fires from a hook, it must be invoked
+> deliberately, and the command is split with `shlex` rather than handed to a
+> shell, so there are no pipes, no redirection and no expansion.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from constant_docs import state
+from constant_docs.state import STATE_DIR
+
+# One JSON object per line, appended. The evidence that automation works, and
+# without it "the docs update themselves" is a claim with nothing behind it.
+# Local rather than committed: it lives beside the dirty set, under a directory
+# that is gitignored, because it is a record of what happened on one machine.
+LOG_FILE = "auto.jsonl"
+
+# The selected module keys, space-separated, so a command need parse nothing to
+# know what it was asked for.
+MODULES_ENV = "CONSTANT_DOCS_MODULES"
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """What one `auto` run did, and what it left behind."""
+
+    # Three states, not two, because "did not need to run" and "could not run"
+    # are opposite outcomes that a two-way flag would collapse into one.
+    attempted: bool  # the command was reached for
+    ran: bool  # the command actually executed
+    command_exit: int | None
+    selected: list[str]
+    skipped: list[str]
+    still_stale: list[str]
+    clean: bool
+
+    @property
+    def exit_code(self) -> int:
+        """0 clean, 1 still stale, 2 could not run. Never collapsed."""
+        if not self.attempted:
+            # Nothing was stale — which is not the same as nothing being
+            # wrong. `verify` also fails on an orphan, a conformance issue or
+            # a refused diagram, and reporting 0 for a repository it exits 1
+            # on is an automation reporting success without having looked.
+            return 0 if self.clean else 1
+        if not self.ran:
+            return 2  # the command could not be started
+        if self.command_exit:
+            return 2  # it ran and failed
+        return 0 if self.clean else 1
+
+
+def log_path(repo_root: Path) -> Path:
+    """Where the record of automated runs is kept."""
+    return repo_root / STATE_DIR / LOG_FILE
+
+
+def record(repo_root: Path, outcome: Outcome) -> None:
+    """Append one run to the record.
+
+    Best effort: a record that cannot be written must not fail a run that
+    otherwise worked. Losing a line of evidence is worse than nothing and much
+    better than losing the regeneration.
+    """
+    entry = {
+        "when": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "modules": list(outcome.selected),
+        "skipped": list(outcome.skipped),
+        "command_exit": outcome.command_exit,
+        "still_stale": list(outcome.still_stale),
+        "clean": outcome.clean,
+    }
+    path = log_path(repo_root)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass
+
+
+def run(cfg: Any, repo_root: Path, config_path: Path | None = None) -> Outcome:
+    """Settle, run the configured command, verify, and report.
+
+    The tool calls no model. It runs what configuration names, waits for it,
+    and then checks the repository rather than believing the exit code.
+
+    *config_path* is the file *cfg* was loaded from. Passed in rather than
+    rebuilt from *repo_root*, because rebuilding it meant hardcoding the
+    default filename: `auto other.yaml` then ran one repository's command and
+    reported another's cleanliness, or died naming a file nobody had asked
+    for. It defaults to the conventional name only so an older caller keeps
+    working.
+    """
+    from constant_docs.api import verify
+
+    settings = cfg.auto
+    resolved = Path(config_path) if config_path else repo_root / "constant-docs.yaml"
+    before = verify(resolved)
+    stale = sorted(set(before.stale) | set(before.missing))
+
+    if settings.when == "stale" and not stale:
+        outcome = Outcome(
+            attempted=False,
+            ran=False,
+            command_exit=None,
+            selected=[],
+            skipped=[],
+            still_stale=[],
+            # Not simply True: nothing being stale says nothing about the
+            # orphans, conformance issues and content issues `verify` also
+            # gates on, and a scheduler told "clean" stops looking.
+            clean=before.exit_code == 0,
+        )
+        # Recorded even so: "nothing to do" is evidence that the automation
+        # ran, and an empty log is indistinguishable from one that never fired.
+        record(repo_root, outcome)
+        return outcome
+
+    selected = stale if settings.budget is None else stale[: settings.budget]
+    skipped = [] if settings.budget is None else stale[settings.budget :]
+
+    # Seed the dirty set with exactly what this run is asking for.
+    #
+    # This is what makes `auto` compose with everything else. In the case it
+    # exists for, no hook ever fired — the change arrived from a timer, a chat
+    # client, or somebody editing files directly — so the dirty set is empty
+    # and a command whose loop is `settle` would find no work at all. `auto`
+    # discovers staleness by hash and records it, so the ordinary loop then
+    # works unchanged.
+    #
+    # Replacing rather than adding is what makes the budget real: the command
+    # sees the capped set, whatever the shape of its loop. Nothing is lost —
+    # the dirty set is recovery state, and `verify` sees every stale module
+    # whatever it says.
+    # Read, modify, write — like every other caller. Building a fresh
+    # `Dirty` reset `blocked_signature` and `blocked_count` to their
+    # defaults, which is the Stop-hook loop guard: one `auto` run wiped a
+    # released set's sentinel and the next `settle --hook` blocked the
+    # identical unchanged plan all over again.
+    dirty = state.read(repo_root)
+    dirty.modules = list(selected)
+    state.write(repo_root, dirty)
+
+    environment = dict(os.environ)
+    environment[MODULES_ENV] = " ".join(selected)
+
+    try:
+        completed = subprocess.run(
+            shlex.split(settings.command),
+            cwd=str(repo_root),
+            env=environment,
+            check=False,
+            timeout=settings.timeout,
+        )
+        command_exit: int | None = completed.returncode
+    except (OSError, ValueError, subprocess.TimeoutExpired):
+        # Cannot run: a missing executable, an unparseable command, a run that
+        # never returned. Distinct from a command that ran and failed only in
+        # that both are exit 2 — which is the honest answer, because in neither
+        # case did the automation do its job.
+        outcome = Outcome(
+            attempted=True,
+            ran=False,
+            command_exit=None,
+            selected=selected,
+            skipped=skipped,
+            still_stale=stale,
+            clean=False,
+        )
+        record(repo_root, outcome)
+        return outcome
+
+    after = verify(resolved)
+    still_stale = sorted(set(after.stale) | set(after.missing))
+    outcome = Outcome(
+        attempted=True,
+        ran=True,
+        command_exit=command_exit,
+        selected=selected,
+        skipped=skipped,
+        still_stale=still_stale,
+        clean=after.exit_code == 0,
+    )
+    record(repo_root, outcome)
+    return outcome