rung-cli 0.1.2__py3-none-any.whl

rung/__init__.py

@@ -0,0 +1,3 @@
+"""Rung: an opinionated verification ladder for software written with coding agents."""
+
+__version__ = "0.1.2"

rung/__main__.py

@@ -0,0 +1,3 @@
+from rung.cli import main
+
+raise SystemExit(main())

rung/agents/__init__.py

@@ -0,0 +1,15 @@
+"""Make coding agents work inside the ladder instead of around it.
+
+Two layers. Guidance (`install`): Claude Code skills and an AGENTS.md section saying how to use
+Rung, how to write TLA+ and Lean, and which shortcuts are off limits. Enforcement (`hooks`): a
+Claude Code `Stop` hook that keeps an agent from finishing while its edits are unverified.
+Guidance can be ignored; the hook cannot.
+"""
+
+from rung.agents.hooks import HOOK_COMMAND, main_stop_hook, stop_hook
+from rung.agents.install import BEGIN, END, install, install_stop_hook, install_verify_skill
+
+__all__ = [
+    "BEGIN", "END", "HOOK_COMMAND", "install", "install_stop_hook", "install_verify_skill", "main_stop_hook",
+    "stop_hook",
+]  # fmt: skip

rung/agents/hooks.py

@@ -0,0 +1,66 @@
+"""The Claude Code `Stop` hook: an agent may not finish while its edits are unverified.
+
+Claude Code runs `rung hook stop` when the agent tries to end its turn and sends a JSON
+payload on stdin (`cwd`, `stop_hook_active`, ...). Exit code 2 blocks the stop and shows
+stderr to the agent as the reason to continue. The hook fails open on anything unexpected,
+and allows the stop when `stop_hook_active` is set, so it can never trap an agent in a loop.
+See https://code.claude.com/docs/en/hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from rung.checks import runner
+from rung.core import config, git
+
+HOOK_COMMAND = "rung hook stop"
+BLOCK = 2
+
+
+def stop_hook(cwd: Path, payload: str) -> tuple[int, str]:
+    """Decide whether an agent may stop. Returns (exit code, message for the agent)."""
+    try:
+        data = json.loads(payload) if payload.strip() else {}
+    except json.JSONDecodeError:
+        data = {}
+    if data.get("stop_hook_active"):
+        return 0, ""  # already blocked once this turn; do not loop
+    try:
+        root = config.find_root(cwd)
+        cfg = config.load(root)
+        # Compare with where the branch left its base, so committing the edits does not hide them.
+        try:
+            changed = git.changed_files(root, git.default_base(root))
+        except git.GitError:
+            changed = git.changed_files(root, "HEAD")
+    except Exception:
+        return 0, ""
+    if not changed:
+        return 0, ""
+    pending = [c for c in runner.select(cfg, [], changed) if not runner.status(cfg, c).trusted]
+    if not pending:
+        return 0, ""
+    ids = " ".join(c.id for c in pending)
+    return BLOCK, (
+        f"Rung: your edits touch checks that are not freshly passing: {ids}.\n"
+        f"Run `rung check {ids}` and fix what fails before finishing. "
+        "If a check cannot pass for a reason outside this task, say so explicitly."
+    )
+
+
+def main_stop_hook() -> int:
+    payload = sys.stdin.read() if not sys.stdin.isatty() else ""
+    # Claude Code sends the session's directory in the payload and exports CLAUDE_PROJECT_DIR.
+    try:
+        where = json.loads(payload).get("cwd") if payload.strip() else None
+    except (json.JSONDecodeError, AttributeError):
+        where = None
+    start = Path(where or os.environ.get("CLAUDE_PROJECT_DIR") or Path.cwd())
+    code, message = stop_hook(start, payload)
+    if message:
+        print(message, file=sys.stderr)
+    return code

rung/agents/install.py

@@ -0,0 +1,120 @@
+"""Install guidance for coding agents: Claude Code skills, an AGENTS.md section, and the Stop hook.
+
+Skills are installed for Claude Code under `.claude/skills/`; the AGENTS.md section is read by
+Codex, Cursor and other agents. Every skill body comes from `rung.guides`, the same text Rung
+sends to the model when it drafts specs and proofs itself.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rung import guides
+from rung.agents.hooks import HOOK_COMMAND
+from rung.core.config import ConfigError
+
+BEGIN, END = "<!-- rung:begin -->", "<!-- rung:end -->"
+
+USAGE = """\
+# Working with Rung
+
+This repository proves its behaviour instead of asserting it. Rung is a CLI; this skill only
+says how to use it.
+
+## Rules
+
+{rules}
+## Commands
+
+- `rung check --changed`: run the checks your change touches and record verdicts.
+- `rung status`: `stale` means covered code or a spec changed since the last green run.
+- `rung laws`: which laws hold.
+- `rung prove '<test command>'`: show your new test fails without the fix and passes with it.
+- `rung report`: everything at once; add `--json` to read it programmatically.
+"""
+
+SKILLS = {
+    "rung": (
+        "Verify changes with Rung (laws, scans, TLA+, Lean, differential tests, evidence ledger). Use before "
+        "declaring any change done, when a check fails or goes stale, when fixing a bug, or when adding a "
+        "dependency, law, spec or proof."
+    ),
+    "rung-tla": (
+        "Write or fix a TLA+ spec that mirrors real code and model-checks with TLC. Use when creating or "
+        "editing a .tla/.cfg file, or when a TLC counterexample needs reading."
+    ),
+    "rung-property": (
+        "Write or strengthen Hypothesis or fast-check property-based tests for a law. Use when adding a "
+        "property test, when `rung draft property` reports surviving mutants, or when a property fails."
+    ),
+    "rung-lean": (
+        "Write or fix a core-only Lean 4 model with kernel-checked proofs and a differential-testing "
+        "program. Use when creating or editing .lean files or when a Lean proof or build fails."
+    ),
+}
+
+
+def _skill(name: str, description: str, body: str) -> str:
+    return f"---\nname: {name}\ndescription: >-\n  {description}\n---\n\n{body}"
+
+
+def _write_skill(root: Path, name: str, body: str, description: str) -> Path:
+    path = root / ".claude" / "skills" / name / "SKILL.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_skill(name, description, body))
+    return path
+
+
+def install(root: Path, *, hooks: bool = False, lean_version: str = "the pinned version") -> list[Path]:
+    rules = guides.load("rules")
+    bodies = {
+        "rung": USAGE.format(rules=rules),
+        "rung-tla": guides.load("tla"),
+        "rung-property": guides.load("property"),
+        "rung-lean": guides.load("lean", lean_version=lean_version),
+    }
+    written = [_write_skill(root, name, bodies[name], desc) for name, desc in SKILLS.items()]
+
+    agents = root / "AGENTS.md"
+    block = f"{BEGIN}\n## Verification (Rung)\n\n{rules}{END}\n"
+    text = agents.read_text() if agents.exists() else ""
+    if BEGIN in text and END in text:
+        head, _, rest = text.partition(BEGIN)
+        _, _, tail = rest.partition(END)
+        text = head + block.rstrip("\n") + tail
+    else:
+        text = (text.rstrip() + "\n\n" if text.strip() else "") + block
+    agents.write_text(text)
+    written.append(agents)
+
+    if hooks:
+        written.append(install_stop_hook(root))
+    return written
+
+
+def install_verify_skill(root: Path, project: str, check_id: str) -> Path:
+    """A project-specific skill pointing agents at the proven drive script and its feature map."""
+    slug = "".join(ch if ch.isalnum() else "-" for ch in project.lower()).strip("-") or "app"
+    description = (
+        f"Drive {project} the way a user does and record evidence. Use after any user-facing change "
+        "(UI, API, CLI), and before saying such a change works."
+    )
+    body = guides.load("verify", project=project, check_id=check_id)
+    return _write_skill(root, f"verify-{slug}", body, description)
+
+
+def install_stop_hook(root: Path) -> Path:
+    """Add the Stop hook to `.claude/settings.json`, keeping everything already there."""
+    path = root / ".claude" / "settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        settings = json.loads(path.read_text()) if path.exists() else {}
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path} is not plain JSON ({exc}); add the Stop hook by hand or remove comments") from exc
+    stop = settings.setdefault("hooks", {}).setdefault("Stop", [])
+    present = any(h.get("command") == HOOK_COMMAND for group in stop for h in group.get("hooks", []))
+    if not present:
+        stop.append({"hooks": [{"type": "command", "command": HOOK_COMMAND, "timeout": 120}]})
+    path.write_text(json.dumps(settings, indent=2) + "\n")
+    return path

rung/analysis/__init__.py

@@ -0,0 +1 @@
+"""Reading a repository: the survey, the recommended plan, and the report over verdicts and laws."""

rung/analysis/plan.py

@@ -0,0 +1,165 @@
+"""Recommend checks for a repository, cheapest and most widely useful first.
+
+The ladder is applied by escalation, not by climbing every rung everywhere.
+Every repository benefits from the cheap rungs: tests recorded as evidence,
+security scanners gated on new findings, vetted dependencies, fix proofs.
+Formal methods are recommended only where the survey finds code they pay off
+for: TLA+ for stateful protocols, a Lean model for small pure cores.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+
+from rung.analysis.survey import Inspection
+from rung.checks.presets import PRESETS
+from rung.core.config import safe_id
+
+LADDER = (
+    ("tests", "Record the test suite as evidence; prove that each bug fix's test catches the bug."),
+    ("security", "Gate on new secrets, vulnerable or invented dependencies, and risky CI workflows."),
+    ("architecture", "Make the wrong shortcut impossible: import boundaries and lint rules, in CI."),
+    ("runtime", "Drive the real app like a user and keep the evidence: transcripts, screenshots, video."),
+    ("protocol", "Model stateful code (queues, retries, leases, sync) in TLA+ and check every interleaving."),
+    ("model", "Prove the laws of a small pure core in Lean and hold the real code to it on random inputs."),
+)
+
+
+@dataclass
+class Recommendation:
+    rung: str
+    title: str
+    why: str
+    targets: list[str] = field(default_factory=list)
+    effort: str = "low"
+    command: str = ""
+
+
+def _scanner_rec(tool: str, check_id: str, why: str) -> Recommendation:
+    preset = PRESETS[tool]
+    installed = shutil.which(tool) is not None
+    command = f"rung add scan {check_id} --tool {tool}"
+    if not installed:
+        why += f" Install it first: {preset.install}."
+    return Recommendation("security", f"Scan for {preset.purpose}", why, effort="low", command=command)
+
+
+def static_check_id(project_path: str, kind: str) -> str:
+    """`typecheck` at the root, `frontend-typecheck` for a sub-project."""
+    return kind if project_path == "." else safe_id(f"{project_path.replace('/', '-')}-{kind}")
+
+
+def plan(info: Inspection, existing: set[str] | None = None) -> list[Recommendation]:
+    """Recommendations for a surveyed repository, skipping check ids that already exist."""
+    existing = existing or set()
+    recs: list[Recommendation] = []
+    lang = info.primary_language
+
+    tested = [p for p in info.projects if p.test_command]
+    for project in tested:
+        name = static_check_id(project.path, "tests")
+        if name in existing:
+            continue
+        label = "the" if project.path == "." else f"the {project.path}"
+        cwd = "" if project.path == "." else f" --cwd {project.path} --covers '{project.path}/**'"
+        recs.append(Recommendation(
+            "tests", f"Record {label} test suite as a check",
+            "A green run becomes a ledger entry tied to the exact code it ran against, and goes stale "
+            "when that code changes.",
+            command=f"rung add command {name}{cwd} --run '{project.test_command}'",
+        ))  # fmt: skip
+    if tested:
+        first = tested[0]
+        cwd = "" if first.path == "." else f" --cwd {first.path}"
+        recs.append(Recommendation(
+            "tests", "Prove bug-fix tests catch the bug",
+            "Agents often write regression tests that pass with or without the fix. `rung prove` runs the "
+            "branch's new tests on the merge base, where they must fail, and on the branch, where they must pass.",
+            command=f"rung prove{cwd} '{first.test_command}'",
+        ))  # fmt: skip
+
+    for project in info.projects:
+        for kind, command in project.static:
+            name = static_check_id(project.path, kind)
+            if name in existing:
+                continue
+            cwd = "" if project.path == "." else f" --cwd {project.path} --covers '{project.path}/**'"
+            recs.append(Recommendation(
+                "architecture", f"Record {command!r} as a check",
+                "The project already configures it; recorded as a check, an agent cannot finish with it failing, "
+                "and the `shortcuts` check stops it being silenced.",
+                command=f"rung add command {name}{cwd} --run '{command}'",
+            ))  # fmt: skip
+        where = "" if project.path == "." else f" in {project.path}"
+        for tool in project.unrecorded:
+            recs.append(Recommendation(
+                "architecture", f"Record a check for {tool.split(' ', 1)[0]}{where} by hand",
+                f"Configured but not recorded automatically: {tool}.",
+            ))  # fmt: skip
+    if "shortcuts" not in existing:
+        recs.append(Recommendation(
+            "tests", "Block the shortcuts agents take to get to green",
+            "New `@ts-ignore`, `# type: ignore`, `as any`, lint disables, skipped or focused tests, deleted tests, "
+            "lowered coverage thresholds and relaxed type-checker settings block; existing ones do not. No tool "
+            "to install.",
+            command="rung add shortcuts shortcuts",
+        ))  # fmt: skip
+
+    if "secrets" not in existing:
+        recs.append(_scanner_rec("gitleaks", "secrets", "Leaked keys are the most common agent-introduced incident."))
+    if "vulnerable-deps" not in existing:
+        recs.append(_scanner_rec("osv-scanner", "vulnerable-deps", "Known-vulnerable dependency versions."))
+    if "deps" not in existing:
+        recs.append(Recommendation(
+            "security", "Vet every newly added dependency",
+            "Agents sometimes add packages that do not exist; attackers register those names. New packages "
+            "must exist on their registry and be at least 30 days old unless a person allows them.",
+            command="rung add deps deps",
+        ))  # fmt: skip
+    if info.ci and "workflows" not in existing and any(p.startswith(".github/workflows/") for p in info.ci):
+        recs.append(_scanner_rec("zizmor", "workflows", "CI workflows run with secrets and write access."))
+    if lang in ("Python", "TypeScript", "JavaScript", "Go", "Java", "Ruby") and "code-patterns" not in existing:
+        recs.append(_scanner_rec("semgrep", "code-patterns", "Injection, SSRF and unsafe deserialization patterns."))
+
+    if not info.lint:
+        recs.append(Recommendation(
+            "architecture", "Add a linter and import-boundary rules",
+            f"No lint configuration found. Agents copy the patterns they see; for {lang}, a linter plus "
+            "layer rules stops the shortcut before review. Record it with `rung add command lint --run ...`.",
+        ))  # fmt: skip
+
+    if info.surfaces and info.surfaces != ["library"]:
+        recs.append(Recommendation(
+            "runtime", f"Record runtime evidence for the {info.surfaces[0]}",
+            "Write a script that launches the app, drives one feature end to end, and saves what it saw to "
+            "$RUNG_EVIDENCE_DIR (a transcript, response bodies, a screenshot or a video). It must record "
+            "something to pass.",
+            effort="medium", command="rung add evidence runtime --run '<your drive script>'",
+        ))  # fmt: skip
+
+    if info.protocol_candidates:
+        top = info.protocol_candidates[:3]
+        recs.append(Recommendation(
+            "protocol", "Model the stateful core in TLA+",
+            "These files look like they hold state, retries or leases, where bugs need a specific "
+            "interleaving that tests rarely reach: " + "; ".join(c.path for c in top) + ". Worth it only if "
+            "a concurrency bug here would be expensive.",
+            targets=[c.path for c in top], effort="high", command=f"rung draft tla {top[0].path}",
+        ))  # fmt: skip
+    if info.model_candidates:
+        top = info.model_candidates[:3]
+        recs.append(Recommendation(
+            "model", "Model a pure core in Lean and test the code against it",
+            "Small, side-effect-free logic (pricing, permissions, parsers, reducers) is where a proven model "
+            "pays off: " + "; ".join(c.path for c in top) + ".",
+            targets=[c.path for c in top], effort="high", command=f"rung draft lean {top[0].path}",
+        ))  # fmt: skip
+
+    recs.append(Recommendation(
+        "ledger", "Gate pull requests on fresh verdicts",
+        "In CI, `rung check --changed` runs what a branch touches and blocks only what it introduces; "
+        "`rung report` writes the pull request comment.",
+        command="rung check --changed",
+    ))  # fmt: skip
+    return recs

rung/analysis/report.py

@@ -0,0 +1,125 @@
+"""One structured report over checks, laws, new findings and proofs.
+
+The same data renders as JSON (for agents and tools) or Markdown (for a pull
+request comment). The Markdown starts with a marker so CI can update one
+comment in place instead of posting a new one on every push.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rung.checks import runner
+from rung.core import laws, ledger
+from rung.core.config import Config
+
+COMMENT_MARKER = "<!-- rung-report -->"
+STATE_ICON = {"fresh": "✅", "stale": "🟡", "failing": "❌", "never": "⚪"}
+LAW_ICON = {"held": "✅", "unproven": "🟡", "broken": "❌", "proposed": "📝", "unenforced": "⚪"}
+
+
+def build(config: Config) -> dict[str, Any]:
+    statuses = {s.check_id: s for s in runner.statuses(config)}
+    verdicts = ledger.read_all(config.root)
+
+    rows = []
+    new_findings = []
+    below_threshold = 0
+    for check in config.checks:
+        s = statuses[check.id]
+        latest = s.entry or {}
+        rows.append({
+            "id": check.id,
+            "kind": check.kind,
+            "state": s.state,
+            "summary": latest.get("summary", ""),
+            "at": latest.get("at", ""),
+            "changed": s.changed,
+        })  # fmt: skip
+        for f in (latest.get("details") or {}).get("findings", []):
+            if f.get("status") == "new":
+                new_findings.append({"check": check.id, **f})
+            elif f.get("status") == "new-below-threshold":
+                below_threshold += 1
+
+    law_rows = []
+    for law in laws.load(config.root):
+        state, why = laws.state(law, statuses)
+        law_rows.append({"id": law.id, "text": law.text, "state": state, "why": why})
+
+    proofs = []
+    for p in (v for v in verdicts.values() if v.get("kind") == "proof"):
+        # A proof is about specific bytes: once its tests or the fixed code change, it no longer holds.
+        files = p.get("details", {}).get("files", [])
+        current = ledger.inputs_digest(ledger.snapshot(config.root, files))
+        stale = p["verdict"] == "pass" and current != p.get("inputs", {}).get("digest")
+        proofs.append({
+            "id": p["check"], "verdict": "stale" if stale else p["verdict"],
+            "summary": "the tests or the fixed code changed since this proof" if stale else p["summary"],
+            "tests": p.get("details", {}).get("tests", []),
+        })  # fmt: skip
+
+    trusted = sum(1 for r in rows if r["state"] == "fresh")
+    held = sum(1 for law in law_rows if law["state"] == "held")
+    approved = sum(1 for law in law_rows if law["state"] != "proposed")
+    return {
+        "project": config.name,
+        "checks": rows,
+        "laws": law_rows,
+        "new_findings": new_findings,
+        "proofs": proofs,
+        "ledger_intact": not any("invalid" in v for v in verdicts.values()),
+        "summary": {
+            "checks_fresh": trusted,
+            "checks_total": len(rows),
+            "laws_held": held,
+            "laws_approved": approved,
+            "new_findings": len(new_findings),
+            "new_below_threshold": below_threshold,
+        },
+    }
+
+
+def markdown(data: dict[str, Any]) -> str:
+    s = data["summary"]
+    out = [
+        COMMENT_MARKER,
+        f"### Rung · {data['project']}",
+        "",
+        f"**{s['checks_fresh']}/{s['checks_total']}** checks fresh · "
+        f"**{s['laws_held']}/{s['laws_approved']}** approved laws held · "
+        f"**{s['new_findings']}** new blocking findings"
+        + (f" ({s['new_below_threshold']} more below the blocking level)" if s["new_below_threshold"] else ""),
+        "",
+    ]
+    if not data["ledger_intact"]:
+        out += ["> ❗ Some verdict files are corrupt or were edited by hand; those checks must be re-run.", ""]
+
+    if data["laws"]:
+        out += ["| | Law | Status |", "|---|---|---|"]
+        for law in data["laws"]:
+            out.append(f"| {LAW_ICON[law['state']]} | {law['text']} | {law['state']}: {law['why']} |")
+        out.append("")
+
+    out += ["| | Check | Kind | Result |", "|---|---|---|---|"]
+    for row in data["checks"]:
+        detail = row["summary"] or "never run"
+        if row["state"] == "stale" and row["changed"]:
+            detail += f" (stale: {', '.join(row['changed'][:3])})"
+        out.append(f"| {STATE_ICON[row['state']]} | `{row['id']}` | {row['kind']} | {detail} |")
+    out.append("")
+
+    if data["new_findings"]:
+        out += ["<details><summary>New blocking findings</summary>", ""]
+        for f in data["new_findings"][:50]:
+            where = f"{f['path']}:{f['line']}" if f.get("line") else f.get("path", "")
+            out.append(f"- **{f['level']}** `{f['rule']}` in `{where}` ({f['check']}): {f.get('message', '')[:200]}")
+        out += ["", "</details>", ""]
+
+    if data["proofs"]:
+        out += ["**Fix proofs**", ""]
+        for p in data["proofs"]:
+            icon = {"pass": "✅", "stale": "🟡"}.get(p["verdict"], "❌")
+            out.append(f"- {icon} `{', '.join(p['tests'])}`: {p['summary']}")
+        out.append("")
+    return "\n".join(out)