225 lines
14 KiB
Python
225 lines
14 KiB
Python
import dataclasses
|
|
import posixpath
|
|
import re
|
|
import typing
|
|
|
|
from round_titles import CAP, lacks_counts, past_cap
|
|
from git_command import commits
|
|
from rule_hook.heavy_command import heavy
|
|
from shell_command import launched, Simple
|
|
from review_folder import REPORTS
|
|
from docker_command import unlimited
|
|
|
|
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "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, unless it names docker by its path or sets its own PATH. 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 or tea command, and any file written",
|
|
),
|
|
# A reviewer only reports, so no marker waives it.
|
|
"reviewer-report": Rule(
|
|
f"a reviewer writes nothing but 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's subagent 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, 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",
|
|
overridable=False,
|
|
),
|
|
"round-cap": Rule(
|
|
f"a larv-review pass takes at most {CAP} rounds per chunk, so a commit titled `Answer <pass> round <n>:` with <n> past {CAP} waits for the human's yes, which the override reason quotes",
|
|
"a git commit whose message opens `Answer <pass> round <n>:`",
|
|
),
|
|
"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 cargo mutants, Infection, mutmut or Stryker, the mutation tools stability-reviewer names, 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 ~/.claude/bin/rank_todo.py --check passes on it",
|
|
"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
|
|
|
|
|
|
@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)
|
|
blocking = [breach for breach in breaches if breach.rule not in granted]
|
|
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}.")
|
|
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, granted[breach.rule]) for breach in breaches if breach.rule in granted])
|
|
|
|
|
|
def command_breaches(command: str, simples: list[Simple], home: str) -> list[Breach]:
|
|
breaches = []
|
|
found = commits(simples, home)
|
|
publishing = [simple for simple in simples if simple.words[0] in ("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(past_cap(message) for message in commit.messages):
|
|
breaches.append(Breach("round-cap", f"the pass has had its {CAP} rounds; ask the human, and quote the yes in the override", 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
|
|
# On Linux, run-heavy's docker adds the limits a container lacks, where PATH finds it: docker named bare, with no PATH of the command's own.
|
|
capped = "run-heavy" in docker.launchers and words[len(words) - len(docker.arguments) - 1] == "docker" and not any(word.startswith("PATH=") for word in words)
|
|
return not capped
|
|
|
|
|
|
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())
|