234 lines
15 KiB
Python
234 lines
15 KiB
Python
import dataclasses
|
|
import posixpath
|
|
import re
|
|
import typing
|
|
|
|
from review_rules.round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
|
|
from git_cli.git_command import commits
|
|
from run_heavy.capped_docker import finds_this_docker
|
|
from rule_hook.heavy_command import heavy
|
|
from command_lines.shell_command import launched, Simple
|
|
from review_rules.review_folder import REPORTS
|
|
from command_lines.docker_command import unlimited
|
|
|
|
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "repeat-read", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Rule:
|
|
holds: str
|
|
checked: str
|
|
# False where no marker waives the rule: overrides() grants none for it.
|
|
overridable: bool = True
|
|
|
|
|
|
RULES: dict[RuleName, Rule] = {
|
|
"action-pin": Rule(
|
|
"a GitHub or Gitea Action is pinned to a semver tag, such as @v3 or @v3.1.2, never to a branch, and to a commit SHA only in a pipeline that tests our own specific builds",
|
|
"`uses:` in a .github or .gitea workflow, or in action.yml",
|
|
),
|
|
"commit-one-line": Rule(
|
|
"a commit message is one line, prefixed with the ticket ID when the work has one",
|
|
"git commit takes its message as one -m with no line break; -F, a second -m and a heredoc are blocked",
|
|
),
|
|
"docker-run-memory": Rule(
|
|
"a container made with docker run or docker create has a memory limit and a swap limit, as large as its work needs, such as `--memory 4g --memory-swap 4g`, so a runaway container fails alone instead of starving the machine; a swap limit equal to the memory limit keeps it out of swap",
|
|
"docker run, docker create, docker container run and docker container create, whether direct or through a launcher such as nice or timeout. One under run-heavy passes, as run-heavy's docker adds the limits on Linux, unless it names docker by its path, or changes or clears PATH, as env -i, sudo or doas do. A container a script or docker compose starts is not checked",
|
|
),
|
|
"ignorefile-sorted": Rule(
|
|
"each block of an ignore file is sorted in code-point order, as LC_ALL=C sort does, since its order carries no meaning; where order matters, such as a re-include after its exclude, split the block with a blank line or a comment",
|
|
"a .*ignore file; a block already unsorted before the edit is left alone",
|
|
),
|
|
"image-pin": Rule(
|
|
"a container image is pinned to its full patch version, such as node:24.18.1-bookworm-slim, or to a date-stamped tag or an @sha256: digest, so the same commit builds the same image on every day; an image that publishes no three-part tag, such as postgres:16.4, takes an override",
|
|
"a Dockerfile's FROM and COPY --from, and `image:` and `container:` in a compose file or workflow",
|
|
),
|
|
"no-ai-attribution": Rule(
|
|
"no commit, PR, issue comment or file carries a Claude or Anthropic attribution, such as a co-author trailer or a generated-with line",
|
|
"a git, gh, tea or chunk-pr command, and any file written",
|
|
),
|
|
# A Read carries no text for a marker, and a misjudged read has a way through that the message names, so no marker waives it.
|
|
"repeat-read": Rule(
|
|
"an agent reads no lines of a file that its context already holds unchanged, since each read pays for them again; where the context lacks them although the transcript shows them, as after Claude Code cleared old tool results, read them with another command, such as `grep -n '' <file> | sed -n '<A>,<B>p'`; a Read goes through until the agent has read the file with Read or written it with Edit, MultiEdit or Write, and again once the file changed after that, since those refuse a file until then",
|
|
"a Read call, and a Bash command that is one `cat <file>`, `head [-n <N> | -<N>] <file>` or `sed -n '<A>[,<B>]p' <file>`, with no pipe or redirect, against the reads in the calling agent's own transcript since its last compaction",
|
|
overridable=False,
|
|
),
|
|
# A reviewer only reports, so no marker waives it.
|
|
"reviewer-report": Rule(
|
|
f"a reviewer writes only its report, with Write, into a file under ~/{REPORTS}/",
|
|
"a Write, Edit or MultiEdit call from inside an agent under agents/",
|
|
overridable=False,
|
|
),
|
|
# A rung is not a judgment call, and the refusal names the arguments to pass, so no marker waives it.
|
|
"reviewer-rung": Rule(
|
|
"a reviewer, a comprehension seat or the security pass runs on the rung loop-claude names for it: for a seat or the security pass the project's rung, and for a reviewer the highest of the project's rung, the worker's and the one the chunk's item's E + I picks, or the project's rung where the branch changes only Markdown no agent follows, so a worker below the project's rung cannot hand a review to its own cheaper model",
|
|
"an Agent call, in a claude loop-claude started, whose subagent type is an agent under agents/, or whose prompt opens with seat-prompts.md's opening sentence or the one larv-review's Security section sets; and a `security-review` or `claude-security` Skill call in such a claude, which runs on its caller's rung, unless the caller is a subagent whose prompt opens with that sentence",
|
|
overridable=False,
|
|
),
|
|
# The cap holds with no ask, so no marker waives it.
|
|
"round-cap": Rule(
|
|
f"a larv-review pass takes at most {CAP} rounds per chunk, and the release review's architecture and principles passes {RELEASE_REVIEW_CAP}, and none after them: the fixes answering its last round merge once the gate passes. A round commit names one of larv-review's passes, so a misspelled one cannot slip past its cap",
|
|
"a git commit whose message opens `Answer <pass> round <n>:`, counted with the pass's round commits on the branch since the default branch as last fetched, less the one an --amend replaces",
|
|
overridable=False,
|
|
),
|
|
"round-title-counts": Rule(
|
|
"a larv-review round's commit title gives the counts of 🔴 and 🟡 findings the round reported, and how many of them a reviewer marked `[misread]`, at most the two together, such as `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted test`, since score-outcomes counts them",
|
|
"a git commit whose message opens `Answer <pass> round <n>:`",
|
|
),
|
|
"run-heavy": Rule(
|
|
"a heavy command, which loads the machine for minutes, runs under ~/.claude/bin/run-heavy, so sessions running at once cannot starve the machine",
|
|
"a docker build, docker buildx build or docker compose build, and a run of mutate-changes, or of cargo mutants, Infection, mutmut or Stryker, the mutation tools it runs, whether direct, through a launcher such as uvx, or inside docker run, docker exec or docker compose run or exec. A gate script is not checked, since no program can tell it from a light one",
|
|
),
|
|
"todo-rank-check": Rule(
|
|
"while todo.md has changes, staged or not, a git commit waits until rank_todo.py --check passes on it: the checkout's own bin/rank_todo.py where the checkout is of this setup's repo, else ~/.claude/bin/rank_todo.py",
|
|
"a git commit in a checkout whose todo.md has changes",
|
|
),
|
|
}
|
|
# The lookahead ends each reason at the next marker on its line, or at the line's end. The reason is lazy, so it stops at the next marker instead of running on and swallowing the markers after it.
|
|
# An HTML marker's closing `-->` stays in its reason; `overrides` strips it.
|
|
OVERRIDE = re.compile(r"(?:#|<!--)\s*rule-override ([a-z-]+):([^\n]*?)(?=[ \t]*(?:#|<!--)\s*rule-override |$)", re.MULTILINE)
|
|
# [-] keeps this file from matching itself.
|
|
ATTRIBUTION = re.compile(r"co-authored[-]by:[^\n]*\b(?:claude|anthropic)\b|generated with \[?claude code", re.IGNORECASE)
|
|
SEMVER = re.compile(r"v?\d+(?:\.\d+){0,2}")
|
|
# Two-part tags such as postgres:16.4 stay blocked: the rule bans node:24.18, which reads the same, so such an image takes an override.
|
|
PATCH = re.compile(r"v?\d+\.\d+\.\d+(?:[-+_.].*)?|.*\d{8}.*")
|
|
FROM = re.compile(r"^[ \t]*FROM[ \t]+(?:--\S+[ \t]+)*(\S+)(?:[ \t]+AS[ \t]+(\S+))?", re.IGNORECASE | re.MULTILINE)
|
|
COPIED = re.compile(r"^[ \t]*COPY[ \t].*?--from=(\S+)", re.IGNORECASE | re.MULTILINE)
|
|
IMAGE = re.compile(r"^[ \t]*(?:-[ \t]+)?(?:image|container):[ \t]*[\"']?([^\s\"'#{]+)", re.MULTILINE)
|
|
USES = re.compile(r"^[ \t]*(?:-[ \t]+)?uses:[ \t]*[\"']?([^\s\"'#]+)", re.MULTILINE)
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Breach:
|
|
rule: RuleName
|
|
detail: str
|
|
# The checkout whose log records an override of this breach.
|
|
directory: str
|
|
# The lines a commit adds to the breach's file: its markers override this breach, as a Write's text overrides its own file's.
|
|
marked: str = ""
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Checked:
|
|
"""What rule-hook found in one tool call: the messages to show, whether it blocks the call, and the overrides to log."""
|
|
messages: list[str]
|
|
blocked: bool
|
|
# Each breach an override let through, with its reason; logged only when the call goes through.
|
|
overridden: list[tuple[Breach, str]]
|
|
|
|
|
|
def overrides(written: str) -> tuple[dict[str, str], list[str]]:
|
|
"""The rules the text overrides with their reasons, and the markers that name no rule or give no reason; a marker for a rule that takes no override is neither."""
|
|
given = [(rule, reason.strip().removesuffix("-->").strip()) for rule, reason in OVERRIDE.findall(written)]
|
|
granted = {rule: reason for rule, reason in given if rule in RULES and RULES[rule].overridable and reason}
|
|
return granted, [f"rule-override {rule}: {reason}" for rule, reason in given if rule not in RULES or not reason]
|
|
|
|
|
|
def check(breaches: list[Breach], written: str, markdown: bool, bash: bool) -> Checked:
|
|
granted, malformed = overrides(written)
|
|
# A marker overrides a breach when it is in the call's own text or in the breach's file.
|
|
grants = [granted | overrides(breach.marked)[0] for breach in breaches]
|
|
blocking = [breach for breach, grant in zip(breaches, grants) if breach.rule not in grant]
|
|
messages = [f"`{marker}` names no rule below, or gives no reason." for marker in malformed] if blocking else []
|
|
where = "the command" if bash else "the text you write, as a comment line"
|
|
for rule in sorted({breach.rule for breach in blocking}):
|
|
details = "; ".join(breach.detail for breach in blocking if breach.rule == rule)
|
|
if not RULES[rule].overridable:
|
|
messages.append(f"Blocked by rule {rule}: {details}. The rule: {RULES[rule].holds}. No marker overrides it.")
|
|
continue
|
|
marker = f"<!-- rule-override {rule}: <reason> -->" if markdown else f"# rule-override {rule}: <reason>"
|
|
messages.append(f"Blocked by rule {rule}: {details}. The rule: {RULES[rule].holds}. Where it does not fit this case, add `{marker}` to {where}; larv-review rules on the reason.")
|
|
return Checked(messages, bool(blocking), [(breach, grant[breach.rule]) for breach, grant in zip(breaches, grants) if breach.rule in grant])
|
|
|
|
|
|
def command_breaches(command: str, simples: list[Simple], home: str) -> list[Breach]:
|
|
breaches = []
|
|
found = commits(simples, home)
|
|
publishing = [simple for simple in simples if posixpath.basename(simple.words[0]) in ("chunk-pr", "gh", "git", "tea")]
|
|
if publishing and ATTRIBUTION.search(command):
|
|
breaches.append(Breach("no-ai-attribution", "the command carries an attribution", publishing[0].directory))
|
|
for simple in simples:
|
|
if heavy(simple.words):
|
|
breaches.append(Breach("run-heavy", f"run `{' '.join(simple.words)[:80]}` under `~/.claude/bin/run-heavy`, in the background", simple.directory))
|
|
if unlimited_container(simple.words):
|
|
breaches.append(Breach("docker-run-memory", f"give `{' '.join(simple.words)[:80]}` a memory limit and a swap limit as large as its work needs", simple.directory))
|
|
for commit in found:
|
|
if commit.from_file:
|
|
breaches.append(Breach("commit-one-line", "pass the message as one -m '<line>', not from a file", commit.directory))
|
|
elif len(commit.messages) > 1 or any("\n" in message.strip() for message in commit.messages):
|
|
breaches.append(Breach("commit-one-line", "pass the message as one -m '<line>', with no heredoc, second -m or newline", commit.directory))
|
|
if any(lacks_counts(message) for message in commit.messages):
|
|
breaches.append(Breach("round-title-counts", "open the summary after the round's colon with `<k> 🔴, <m> 🟡 (<j> misread);`, where <j> is at most <k> + <m>", commit.directory))
|
|
return breaches
|
|
|
|
|
|
def unlimited_container(words: list[str]) -> bool:
|
|
"""Whether the simple command, directly or through a launcher, starts a container that lacks a memory limit or a swap limit."""
|
|
docker = launched(words, {"docker"})
|
|
if docker is None or not unlimited(docker.arguments):
|
|
return False
|
|
return not ("run-heavy" in docker.launchers and finds_this_docker(docker.word, docker.before))
|
|
|
|
|
|
def file_breaches(path: str, before: str, added: str, after: str) -> list[Breach]:
|
|
"""Breaches in an edit of path: added is the text the edit writes, after the whole file it leaves."""
|
|
breaches = [Breach("no-ai-attribution", f"{path} would carry an attribution", posixpath.dirname(path))] if ATTRIBUTION.search(added) else []
|
|
return breaches + image_breaches(path, before, added, after) + action_breaches(path, added) + ignore_breaches(path, before, after)
|
|
|
|
|
|
def image_breaches(path: str, before: str, added: str, after: str) -> list[Breach]:
|
|
name = posixpath.basename(path)
|
|
if name.startswith(("Dockerfile", "Containerfile")) or name.endswith((".dockerfile", ".Dockerfile", ".containerfile")):
|
|
stages = {stage.lower() for _, stage in FROM.findall(before + "\n" + after) if stage} | {"scratch"}
|
|
images = [image for image, _ in FROM.findall(added) if image.lower() not in stages] + [image for image in COPIED.findall(added) if image.lower() not in stages and not image.isdigit()]
|
|
elif "compose" in name and name.endswith((".yml", ".yaml")) or workflow(path):
|
|
images = IMAGE.findall(added)
|
|
else:
|
|
images = []
|
|
return [Breach("image-pin", f"{path}: {image}", posixpath.dirname(path)) for image in images if not pinned(image)]
|
|
|
|
|
|
def action_breaches(path: str, added: str) -> list[Breach]:
|
|
actions = USES.findall(added) if workflow(path) else []
|
|
return [Breach("action-pin", f"{path}: uses: {action}", posixpath.dirname(path)) for action in actions if not tagged(action)]
|
|
|
|
|
|
def ignore_breaches(path: str, before: str, after: str) -> list[Breach]:
|
|
name = posixpath.basename(path)
|
|
if not (name.startswith(".") and name.endswith("ignore")):
|
|
return []
|
|
already = [block for block in blocks(before) if block != sorted(block)]
|
|
return [Breach("ignorefile-sorted", f"{path}: sort the block {block[0]!r} through {block[-1]!r} as {', '.join(sorted(block))}", posixpath.dirname(path)) for block in blocks(after) if block != sorted(block) and block not in already]
|
|
|
|
|
|
def workflow(path: str) -> bool:
|
|
return any(folder in "/" + path for folder in ("/.github/workflows/", "/.gitea/workflows/")) or posixpath.basename(path) in ("action.yml", "action.yaml")
|
|
|
|
|
|
def pinned(image: str) -> bool:
|
|
if "$" in image or "{{" in image or "@sha256:" in image:
|
|
return True
|
|
tail = image.rsplit("/", 1)[-1]
|
|
return ":" in tail and PATCH.fullmatch(tail.split(":", 1)[1]) is not None
|
|
|
|
|
|
def tagged(action: str) -> bool:
|
|
if action.startswith(("./", "docker://")) or "$" in action or "{{" in action:
|
|
return True
|
|
return "@" in action and SEMVER.fullmatch(action.rsplit("@", 1)[1]) is not None
|
|
|
|
|
|
def blocks(written: str) -> list[list[str]]:
|
|
"""An ignore file's runs of patterns, split at each blank line and comment."""
|
|
runs: list[list[str]] = [[]]
|
|
for line in written.splitlines():
|
|
if line.strip() and not line.startswith("#"):
|
|
runs[-1].append(line)
|
|
elif runs[-1]:
|
|
runs.append([])
|
|
return [run for run in runs if run]
|
|
|
|
|
|
def rules_help() -> str:
|
|
return "\n".join(f" {name}\n The rule: {rule.holds}.\n Checked in: {rule.checked}." + ("" if rule.overridable else "\n Takes no override.") for name, rule in RULES.items())
|