252 lines
18 KiB
Python
252 lines
18 KiB
Python
import dataclasses
|
|
import posixpath
|
|
import re
|
|
import typing
|
|
|
|
from review_rules.round_titles import CAP, COUNTS, EXAMPLE, lacks_counts, OPENING, RELEASE_REVIEW_CAP
|
|
from git_cli.git_command import CommitCall
|
|
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 project_config import templates
|
|
from command_lines.docker_command import unlimited
|
|
|
|
RuleName = typing.Literal["action-pin", "commit-one-line", "commit-title", "docker-run-memory", "env-file-read", "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",
|
|
),
|
|
"commit-title": Rule(
|
|
"a commit's title fits the `commit-title` template the project's config names, such as `[{id}] {summary}`, so the project's log reads as its owners write it",
|
|
"the -m of a git commit in a checkout whose config sets `commit-title`, on a branch that fits the config's `branch` template; on any other branch, as for a chunk with no plan item, the title may be the bare summary. A round title, from `Answer <pass> round <n>:` to its end, is the template's {summary}. While the config cannot be read, every commit is 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",
|
|
),
|
|
# A marker would let the credentials into the transcript all the same, so no marker waives it.
|
|
"env-file-read": Rule(
|
|
"an agent never reads ~/.claude/.env or a project's env-file, the file of credentials the project's config names, since a value the agent reads lands in its transcript, which loop-claude archives and the backups copy; it leaves a tool that needs a credential to read the file itself, gets the file's path from `~/.claude/bin/project-config env-file`, and spells the path another way, such as \"the .env in ~/.claude\", in a command that must mention it without reading it, such as a commit's title, and searches only a folder without it",
|
|
"against ~/.claude/.env and the env-file of every config under ~/.claude-projects: a Read of one; a Grep of one, or of a folder holding one, unless a checkout ignores the file and the Grep's glob cannot match it; and a Bash command that spells one's path, or names it in a word or a redirect's target from the directory `cd` left the command in, whether or not the command reads it; and a Bash command that runs `ag`, `grep -r` or `rg` over a folder holding one, or over the directory `cd` left the command in where it names no folder, unless the tool skips the file: `ag` and `rg` skip a hidden file, one below a hidden folder of the search and one a checkout ignores, and `rg` one that none of its globs matches",
|
|
overridable=False,
|
|
),
|
|
"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. The rungs rank as on the project's routing ladder, and the review is refused while that ladder cannot be read",
|
|
"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",
|
|
f"a git commit whose message opens `{OPENING}`, 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(
|
|
f"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 `{EXAMPLE}`, since score-outcomes counts them",
|
|
f"a git commit whose message opens `{OPENING}`",
|
|
),
|
|
"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, and every git commit where the project's config puts todo.md outside the checkout, where the checkout's commits don't say whether it changed; and a git commit in the config's folder, `~/.claude-projects/<key>/`, 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]) -> list[Breach]:
|
|
breaches = []
|
|
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))
|
|
return breaches
|
|
|
|
|
|
def title_breaches(commit: CommitCall, titles: templates.Titles, branch_template: str, branch: str | None) -> list[Breach]:
|
|
"""The breaches of the commit's message, read through titles, the project's title templates. branch is the checkout's branch, None where it has none, and branch_template the config's `branch`: templates.misfits says when the title must fit the commit template."""
|
|
breaches = []
|
|
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))
|
|
# A message of several lines breaks commit-one-line above, which says how to fix it.
|
|
if misfit := [message for message in commit.messages[:1] if "\n" not in message.strip() and templates.misfits(titles.commit, branch_template, branch, message)]:
|
|
breaches.append(Breach("commit-title", f"title the commit as the project's config asks, `{titles.commit}`, where {{id}} is the ID of the chunk's first item; `{misfit[0].strip()[:80]}` doesn't fit", commit.directory))
|
|
if any(lacks_counts(titles.summary(message.strip())) for message in commit.messages):
|
|
breaches.append(Breach("round-title-counts", f"open the summary after the round's colon with `{COUNTS}`, 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())
|