From c6de720ac3e90c2e10ea70c6df5aebcce746cac2 Mon Sep 17 00:00:00 2001 From: archae0pteryx Date: Thu, 19 Nov 2026 13:57:06 -0800 Subject: [PATCH 1/4] feat: add setup-trim-comments and harden trim-comments Add /setup-trim-comments, which surveys a repo (--survey) and writes its .commentrc. Roll back a failed or timed-out reviewer, scope the reviewer's edits to the flagged files, check comment removal per language, keep copies of everything the hook discards, accept bare directory names in include and exclude, make the hook command work in either plugin layout, and document the requirements and limits. --- .claude-plugin/marketplace.json | 17 +- .cursor-plugin/marketplace.json | 9 + .github/plugin/marketplace.json | 17 +- README.md | 11 + skills/.cursor-plugin/plugin.json | 1 + .../.cursor-plugin/plugin.json | 4 + skills/setup-trim-comments/SKILL.md | 61 +++++ skills/setup-trim-comments/agents/openai.yaml | 5 + skills/trim-comments/SKILL.md | 44 ++-- skills/trim-comments/hooks/hooks.json | 2 +- skills/trim-comments/scripts/trim_comments.py | 208 +++++++++++++++--- tests/test_trim_comments.py | 156 ++++++++++++- 12 files changed, 479 insertions(+), 56 deletions(-) create mode 100644 skills/setup-trim-comments/.cursor-plugin/plugin.json create mode 100644 skills/setup-trim-comments/SKILL.md create mode 100644 skills/setup-trim-comments/agents/openai.yaml diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 07e825a..dd1c2e2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -115,6 +115,18 @@ "homepage": "https://github.com/killallgit/killall-skills", "version": "5.6.0" }, + { + "name": "setup-trim-comments", + "source": "./", + "description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.", + "strict": false, + "skills": [ + "./skills/setup-trim-comments" + ], + "category": "workflow", + "homepage": "https://github.com/killallgit/killall-skills", + "version": "5.6.0" + }, { "name": "trim-comments", "source": "./", @@ -132,7 +144,7 @@ "hooks": [ { "type": "command", - "command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"", + "command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0", "timeout": 300 } ] @@ -167,6 +179,7 @@ "./skills/restate", "./skills/session-eject", "./skills/setup-agents-md", + "./skills/setup-trim-comments", "./skills/trim-comments", "./skills/wait-for-action" ], @@ -179,7 +192,7 @@ "hooks": [ { "type": "command", - "command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"", + "command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0", "timeout": 300 } ] diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index d68f6ea..ffddb99 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -80,6 +80,14 @@ "homepage": "https://github.com/killallgit/killall-skills", "version": "5.6.0" }, + { + "name": "setup-trim-comments", + "source": "./skills/setup-trim-comments", + "description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.", + "category": "workflow", + "homepage": "https://github.com/killallgit/killall-skills", + "version": "5.6.0" + }, { "name": "trim-comments", "source": "./skills/trim-comments", @@ -113,6 +121,7 @@ "./restate", "./session-eject", "./setup-agents-md", + "./setup-trim-comments", "./trim-comments", "./wait-for-action" ] diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 63e9f18..51cfc64 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -116,6 +116,18 @@ "homepage": "https://github.com/killallgit/killall-skills", "version": "5.6.0" }, + { + "name": "setup-trim-comments", + "source": "./", + "description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.", + "strict": false, + "skills": [ + "./skills/setup-trim-comments" + ], + "category": "workflow", + "homepage": "https://github.com/killallgit/killall-skills", + "version": "5.6.0" + }, { "name": "trim-comments", "source": "./", @@ -133,7 +145,7 @@ "hooks": [ { "type": "command", - "command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"", + "command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0", "timeout": 300 } ] @@ -168,6 +180,7 @@ "./skills/restate", "./skills/session-eject", "./skills/setup-agents-md", + "./skills/setup-trim-comments", "./skills/trim-comments", "./skills/wait-for-action" ], @@ -180,7 +193,7 @@ "hooks": [ { "type": "command", - "command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"", + "command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0", "timeout": 300 } ] diff --git a/README.md b/README.md index 41e2c0a..ffbecde 100644 --- a/README.md +++ b/README.md @@ -175,3 +175,14 @@ prints the `bd create` commands for an epic plus one bead per candidate, which it runs only for the candidates you pick. It keeps `GLOSSARY.md`, `ARCHITECTURE.md`, and `docs/adr/` current as decisions land. Words after the command name a direction. User-invoked only. + +## Trim comments + +The `trim-comments` plugin hook runs on every Stop in Claude Code. It finds the +comments and docstrings in the files the session edited, in any repo, and has a +reviewer on a different model delete the ones the code already says. The reviewer +may edit only the flagged files, and anything outside a comment is restored. +It acts only in repos that opt in with a `.commentrc` at the root, and it needs +`uv` and the `claude` CLI. `/setup-trim-comments` surveys a repo and writes that file; +`/trim-comments` runs the trimmer by hand. See `skills/trim-comments/SKILL.md` for +the config keys and the exact checks. Both are user-invoked only. diff --git a/skills/.cursor-plugin/plugin.json b/skills/.cursor-plugin/plugin.json index b7204aa..a2f1d1c 100644 --- a/skills/.cursor-plugin/plugin.json +++ b/skills/.cursor-plugin/plugin.json @@ -11,6 +11,7 @@ "./restate", "./session-eject", "./setup-agents-md", + "./setup-trim-comments", "./trim-comments", "./wait-for-action" ] diff --git a/skills/setup-trim-comments/.cursor-plugin/plugin.json b/skills/setup-trim-comments/.cursor-plugin/plugin.json new file mode 100644 index 0000000..dea20bc --- /dev/null +++ b/skills/setup-trim-comments/.cursor-plugin/plugin.json @@ -0,0 +1,4 @@ +{ + "name": "setup-trim-comments", + "description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover." +} diff --git a/skills/setup-trim-comments/SKILL.md b/skills/setup-trim-comments/SKILL.md new file mode 100644 index 0000000..83ecc62 --- /dev/null +++ b/skills/setup-trim-comments/SKILL.md @@ -0,0 +1,61 @@ +--- +name: setup-trim-comments +description: Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover. +disable-model-invocation: true +--- + +# Set up trim-comments + +Write the project's `.commentrc`: the file that opts a repo into the +`trim-comments` hook and sets its `include`, `exclude` and `extensions`. Work +from the repo root, which must be a git repository. When a `caveman` skill is +available in this session, invoke it first. + +The survey is the `trim-comments` script. It sits next to this skill, in +`../trim-comments/scripts/trim_comments.py`, and needs `trim-comments` installed. +When that path is missing, stop and tell the user to install `trim-comments` +beside this skill. + +## 1. Survey + +Run `uv run --python 3.12 /../trim-comments/scripts/trim_comments.py --survey` +from the repo root. When `.commentrc` exists, read it too: its keys are the +starting answers, and the survey already applies them. + +Done when you can say which directories hold the project's own code, which hold +vendored, fixture or example code, and which suffixes are `unsupported`. The +extension counts cover every tracked file, and the list stops at the top 15. + +## 2. Decide + +Ask one question per decision the survey leaves open, with a recommended option +first. Skip a decision the survey settles. + +- **`include`**: the top-level directories to cover, such as `src`. Recommend the + ones holding the project's own code. Omit `include` when the code spans the whole tree. +- **`exclude`**: the conventional directories present (`tests`, `fixtures`, + `migrations`, `examples`), tool and agent config directories (`.claude`, + `.agents`, `.beads`), and anything else vendored. Tests are the user's call: an + agent writes restating comments there too. +- **`extensions`**: each `unsupported` suffix with many files, mapped to `hash` + (`#` comments) or `slash` (`//` and `/* */`). Leave out suffixes whose comment + syntax is neither. + +Generated files with a `do not edit` header are skipped already; leave them out +of `exclude`. + +## 3. Write + +Write `.commentrc` at the repo root as JSON. A new file holds only the keys that +differ from the defaults, and `{}` enables the defaults. An existing file keeps +every key this run did not change, even one equal to a default. A directory is a +plain name (`src`, `tests`); a glob such as `**/migrations/**` also works, with `*` +staying within a directory and `**` crossing them. + +## 4. Verify + +Run the survey again. Done when it prints no `bad config` and the per-directory +counts match what the user chose. Fix the file and rerun until they do. + +End with the file's contents and one line: commit `.commentrc` so teammates and +worktrees inherit it. diff --git a/skills/setup-trim-comments/agents/openai.yaml b/skills/setup-trim-comments/agents/openai.yaml new file mode 100644 index 0000000..dfe6802 --- /dev/null +++ b/skills/setup-trim-comments/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Set up trim-comments" + short_description: "Write a project's .commentrc by surveying the repo and asking what to cover." +policy: + allow_implicit_invocation: false diff --git a/skills/trim-comments/SKILL.md b/skills/trim-comments/SKILL.md index 0b293c0..64bdd5d 100644 --- a/skills/trim-comments/SKILL.md +++ b/skills/trim-comments/SKILL.md @@ -15,36 +15,49 @@ Files come from two sources, each grouped by the git repo that holds it: - every file the transcript shows an `Edit`, `Write`, `MultiEdit` or `NotebookEdit` touching, in any repo - every file changed since `HEAD` (plus untracked) in the repo the session - started in, which catches changes made through Bash + started in, which catches changes made through Bash. Uncommitted work that + predates the session is in this set too, so its comments are reviewed. Each repo is reviewed under its own `.commentrc`, with `cwd` set to that repo. Edits made by subagents are not in the parent transcript; the second source is the only thing that sees them, and only in the session's own repo. -Run it by hand from the checkout to review: +Requires `uv` and the `claude` CLI on `PATH`. Run it by hand from the checkout to review: ```bash uv run --python 3.12 /scripts/trim_comments.py ``` `--dry-run` prints the flagged comments and the reviewer prompt without calling it. +`--survey` prints, under the current `.commentrc`, the repo's most common extensions +(top 15, counted over every tracked file), the reviewable files per top-level +directory, the generated-file count and the conventional directories present. +`/setup-trim-comments` uses it to write the `.commentrc`. ## Fixed behavior - The reviewer is `haiku`, or `sonnet` when the working agent ran on haiku, read from the session transcript. `TRIM_COMMENTS_MODEL` overrides it. -- The reviewer gets `Read` and `Edit` only (`--tools`, no MCP servers), through `claude -p`. +- The reviewer runs through `claude -p` with `Read` and `Edit` only, no MCP + servers, and `dontAsk` permissions. `Edit` is allowed on the flagged files by + path and denied everywhere else. A file whose path holds `* ? [ ] { } ( ) !` is + skipped, because those characters read as permission patterns. - Shebangs, license headers, common lint, type and tooling directives, and PEP 723 script blocks never reach the reviewer. - A reviewed file is checked after the edit and restored byte for byte when it fails: Python must keep the same syntax tree apart from docstrings, and other files may only lose comment lines or comment tails. -- Files the reviewer changes outside the flagged set are restored too, and a file - it creates is deleted. The summary line names them. +- The check runs when the reviewer fails or times out too, so a half-finished edit + is rolled back. A failed run is retried on the next Stop. +- Files the reviewer changes outside the flagged set are restored, and a file it + creates is deleted. The summary line names them. +- Everything the hook discards is copied into the git dir's + `trim-comments-rejected` folder first. - Outside Python, a `#` line inside a multi-line string (a YAML block scalar, a - heredoc) reads as a comment and can be removed. -- The hook fails open. A reviewer that errors or times out shows a warning and - never blocks the session. + heredoc) reads as a comment and can be removed. The check cannot tell it apart. +- The hook fails open. A reviewer error, a timeout or a missing `uv` or `claude` + shows a warning or does nothing, and never blocks the session. While the + reviewer runs the Stop waits, for up to 5 minutes. - Only files with a known extension are read, and only outside the default excludes: `node_modules`, `vendor`, `dist`, `build`, `.venv`, `venv`, `__pycache__`, `*.min.*`, `*_pb2.py`, `*.generated.*`. @@ -62,8 +75,8 @@ nothing there; an empty file enables the defaults. Every key is optional: ```json { - "include": ["src/**"], - "exclude": ["**/migrations/**", "tests/**"], + "include": ["src"], + "exclude": ["**/migrations/**", "tests"], "extensions": {".vue": "slash"} } ``` @@ -72,8 +85,13 @@ nothing there; an empty file enables the defaults. Every key is optional: - `exclude`: added to the default excludes. - `extensions`: maps a suffix to a style, adding it or overriding a default. - Globs match repo-relative paths: `*` stays within a directory, `**` crosses them. + A plain directory name such as `tests` or `src/` covers everything under it. - An invalid config shows a warning and skips the run. -Plugin installs register the hook on Claude Code. A host that does not set -`CLAUDE_PLUGIN_ROOT` runs the hook command as a no-op. `npx skills add` installs skills only, so -the hook never runs there. +## Hosts + +Plugin installs register the hook on Claude Code, where it is tested. The hook +command finds the script under `${CLAUDE_PLUGIN_ROOT}` in either plugin layout, and +does nothing when the variable is unset or the script is missing, so a host that +loads the hook file without that layout stays quiet. Other hosts are untested. +`npx skills add` installs skills only, so the hook never runs there. diff --git a/skills/trim-comments/hooks/hooks.json b/skills/trim-comments/hooks/hooks.json index 899f14a..72c21f8 100644 --- a/skills/trim-comments/hooks/hooks.json +++ b/skills/trim-comments/hooks/hooks.json @@ -5,7 +5,7 @@ "hooks": [ { "type": "command", - "command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"", + "command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0", "timeout": 300 } ] diff --git a/skills/trim-comments/scripts/trim_comments.py b/skills/trim-comments/scripts/trim_comments.py index 75ac873..8d0bd16 100644 --- a/skills/trim-comments/scripts/trim_comments.py +++ b/skills/trim-comments/scripts/trim_comments.py @@ -12,6 +12,7 @@ import sys import time import tokenize +from collections import Counter from dataclasses import dataclass from pathlib import Path @@ -19,6 +20,12 @@ MODEL_ENV = "TRIM_COMMENTS_MODEL" REVIEWER_MODELS = ("haiku", "sonnet") REVIEW_BUDGET = 280 +SNAPSHOT_LIMIT = 5_000_000 +UNSCOPABLE = set("*?[]{}()!") +CONVENTIONAL_DIRS = { + "tests", "test", "__tests__", "spec", "fixtures", "testdata", "snapshots", "__snapshots__", + "migrations", "third_party", "examples", +} EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"} CONFIG_FILE = ".commentrc" @@ -86,7 +93,7 @@ def python_comments(source: str) -> list[Comment]: def python_docstrings(source: str) -> list[Comment]: try: tree = ast.parse(source) - except SyntaxError: + except (SyntaxError, ValueError, RecursionError): return [] found = [] for node in ast.walk(tree): @@ -190,6 +197,10 @@ def string_list(config: dict, key: str) -> list[str]: return value +def with_subtrees(globs: list[str]) -> list[str]: + return [g for glob in globs for g in (glob, glob.rstrip("/") + "/**") if not glob.endswith("/**") or g == glob] + + def load_scope(root: str) -> Scope | None: try: text = Path(root, CONFIG_FILE).read_text() @@ -210,34 +221,64 @@ def load_scope(root: str) -> Scope | None: raise ValueError(f"{CONFIG_FILE}: unknown style in extensions {unknown}") return Scope( styles, - tuple(glob_regex(g) for g in include), - tuple(glob_regex(g) for g in [*DEFAULT_EXCLUDE, *exclude]), + tuple(glob_regex(g) for g in with_subtrees(include)), + tuple(glob_regex(g) for g in [*DEFAULT_EXCLUDE, *with_subtrees(exclude)]), ) def python_shape(source: str) -> str | None: try: tree = ast.parse(source) - except SyntaxError: + for node in ast.walk(tree): + if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)): + if ast.get_docstring(node, clean=False) is not None and len(node.body) > 1: + node.body = node.body[1:] + return ast.dump(tree) + except (SyntaxError, ValueError, RecursionError): return None - for node in ast.walk(tree): - if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)): - if ast.get_docstring(node, clean=False) is not None and len(node.body) > 1: - node.body = node.body[1:] - return ast.dump(tree) -def comment_only(line: str) -> bool: +def comment_only(line: str, style: str) -> bool: text = line.strip() - return not text or text.startswith(("#", "//", "/*", "* ", "*/")) or text == "*" + if not text: + return True + if style == "slash": + return text.startswith(("//", "/*", "* ", "*/")) or text == "*" + return text.startswith("#") and not text.startswith("#!") -def tail_trimmed(old: str, new: str) -> bool: +def comment_start(line: str, style: str) -> int | None: + if style == "slash": + match, marker = SLASH_COMMENT.search(line), "//" + if not match: + match, marker = BLOCK_OPEN.search(line), "/*" + else: + match, marker = HASH_COMMENT.search(line), "#" + return line.index(marker, match.start()) if match else None + + +def closes_strings(text: str, style: str) -> bool: + quotes = "\"'`" if style == "hash" else "\"`" + quote, escaped = "", False + for char in text: + if escaped: + escaped = False + elif char == "\\": + escaped = True + elif quote: + quote = "" if char == quote else quote + elif char in quotes: + quote = char + return not quote + + +def tail_trimmed(old: str, new: str, style: str) -> bool: + start = comment_start(old, style) kept = new.rstrip() - return old.startswith(kept) and old[len(kept):].strip().startswith(("#", "//", "/*")) + return start is not None and kept == old[:start].rstrip() and closes_strings(kept, style) -def only_comments_removed(old: str, new: str) -> bool: +def only_comments_removed(old: str, new: str, style: str) -> bool: old_lines, new_lines = old.splitlines(), new.splitlines() matcher = difflib.SequenceMatcher(None, old_lines, new_lines, autojunk=False) for tag, i1, i2, j1, j2 in matcher.get_opcodes(): @@ -248,9 +289,9 @@ def only_comments_removed(old: str, new: str) -> bool: kept = new_lines[j1:j2] j = 0 for line in old_lines[i1:i2]: - if j < len(kept) and (line.rstrip() == kept[j].rstrip() or tail_trimmed(line, kept[j])): + if j < len(kept) and (line.rstrip() == kept[j].rstrip() or tail_trimmed(line, kept[j], style)): j += 1 - elif not comment_only(line): + elif not comment_only(line, style): return False if j != len(kept): return False @@ -258,11 +299,13 @@ def only_comments_removed(old: str, new: str) -> bool: def edit_is_safe(rel: str, old: str, new: str, styles: dict[str, str]) -> bool: - if styles.get(Path(rel).suffix) == "python": + style = styles.get(Path(rel).suffix, "hash") + if style == "python": shape = python_shape(old) if shape is not None: return python_shape(new) == shape - return only_comments_removed(old, new) + style = "hash" + return only_comments_removed(old, new, style) def git(root: str, *args: str) -> list[str]: @@ -318,7 +361,7 @@ def reviewer_model(transcript_path: str) -> str: if forced := os.environ.get(MODEL_ENV): return forced worker = worker_model(transcript_path) - return next(model for model in REVIEWER_MODELS if model not in worker) + return next((model for model in REVIEWER_MODELS if model not in worker), REVIEWER_MODELS[0]) def build_prompt(flagged: dict[str, list[Comment]]) -> str: @@ -342,14 +385,17 @@ def build_prompt(flagged: dict[str, list[Comment]]) -> str: """ -def run_reviewer(root: str, model: str, prompt: str, timeout: float) -> subprocess.CompletedProcess: +def run_reviewer( + root: str, model: str, prompt: str, timeout: float, files: list[str] +) -> subprocess.CompletedProcess: + allowed = ["Read", *(f"Edit(/{os.path.realpath(Path(root, rel))})" for rel in files)] return subprocess.run( [ "claude", "-p", "--model", model, "--tools", "Read,Edit", - "--allowedTools", "Read,Edit", + "--allowedTools", *allowed, "--strict-mcp-config", - "--permission-mode", "acceptEdits", + "--permission-mode", "dontAsk", "--no-session-persistence", ], input=prompt, @@ -403,14 +449,41 @@ def targets(session_dir: str, transcript_path: str) -> dict[str, set[str]]: continue root = repo_root(os.path.dirname(real), cache) rel = os.path.relpath(real, root) if root else ".." - if root and not rel.startswith(".."): + if root and rel != ".." and not rel.startswith(".." + os.sep): found.setdefault(root, set()).add(rel) return found def snapshot(root: str) -> dict[str, bytes]: files = {rel: Path(root, rel) for rel in touched_files(root)} - return {rel: path.read_bytes() for rel, path in files.items() if path.is_file()} + return { + rel: path.read_bytes() + for rel, path in files.items() + if path.is_file() and path.stat().st_size <= SNAPSHOT_LIMIT + } + + +def git_path(root: str, name: str) -> Path | None: + found = git(root, "rev-parse", "--git-path", name) + return Path(root, found[0]) if found else None + + +def stash_rejected(root: str, rel: str, content: bytes) -> None: + folder = git_path(root, "trim-comments-rejected") + if folder is None: + return + target = folder / rel + try: + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(content) + except OSError: + pass + + +def save_state(state: Path, reviewed: dict[str, str]) -> None: + temporary = state.with_name(state.name + ".tmp") + temporary.write_text(json.dumps(reviewed)) + os.replace(temporary, state) def undo_strays(root: str, flagged: dict[str, list[Comment]], before: dict[str, bytes]) -> list[str]: @@ -419,6 +492,7 @@ def undo_strays(root: str, flagged: dict[str, list[Comment]], before: dict[str, if rel in flagged or before.get(rel) == content: continue path = Path(root, rel) + stash_rejected(root, rel, content) if rel in before: path.write_bytes(before[rel]) elif subprocess.run(["git", "-C", root, "checkout", "--", rel], capture_output=True).returncode: @@ -437,14 +511,14 @@ def review_repo(root: str, rels: set[str], model: str, dry_run: bool, deadline: if dry_run: print(f"{name}: no {CONFIG_FILE}; nothing to do", file=sys.stderr) return None - state = Path(root, git(root, "rev-parse", "--git-path", "trim-comments.json")[0]) - reviewed = load_reviewed(state) + state = git_path(root, "trim-comments.json") + reviewed = load_reviewed(state) if state else {} flagged: dict[str, list[Comment]] = {} originals: dict[str, bytes] = {} for rel in filter(scope.allows, sorted(rels)): path = Path(root, rel) - if not path.is_file() or reviewed.get(rel) == digest(path): + if UNSCOPABLE & set(rel) or not path.is_file() or reviewed.get(rel) == digest(path): continue raw = path.read_bytes() try: @@ -466,31 +540,42 @@ def review_repo(root: str, rels: set[str], model: str, dry_run: bool, deadline: if remaining <= 0: return f"{name}: skipped, out of time" untouched = snapshot(root) + failure = None try: - result = run_reviewer(root, model, build_prompt(flagged), remaining) + result = run_reviewer(root, model, build_prompt(flagged), remaining, list(flagged)) + if result.returncode != 0: + failure = f"reviewer ({model}) failed: {result.stderr.strip()[:300]}" except (OSError, subprocess.TimeoutExpired) as error: - return f"{name}: reviewer ({model}) did not run: {error}" - if result.returncode != 0: - return f"{name}: reviewer ({model}) failed: {result.stderr.strip()[:300]}" + failure = f"reviewer ({model}) did not run: {error}" after = 0 notes = [] for rel in flagged: path = Path(root, rel) try: - new = path.read_bytes().decode() + current = path.read_bytes() + new = current.decode() except (OSError, UnicodeDecodeError): - new = None + current, new = None, None if new is None or not edit_is_safe(rel, originals[rel].decode(), new, scope.styles): + if current is not None: + stash_rejected(root, rel, current) path.write_bytes(originals[rel]) new = originals[rel].decode() notes.append(f"reverted unsafe edit to {rel}") after += len(find_comments(rel, new, scope.styles)) - reviewed[rel] = digest(path) + if not failure: + reviewed[rel] = digest(path) if undone := undo_strays(root, flagged, untouched): notes.append(f"reverted reviewer edits to {', '.join(undone)}") + if notes: + notes.append("rejected copies are in the git dir's trim-comments-rejected folder") + if failure: + return "; ".join([f"{name}: {failure}", *notes]) try: - state.write_text(json.dumps(reviewed)) + if state is None: + raise OSError + save_state(state, reviewed) except OSError: notes.append("could not save review state") removed = max(before - after, 0) @@ -498,10 +583,61 @@ def review_repo(root: str, rels: set[str], model: str, dry_run: bool, deadline: return "; ".join([summary, *notes]) +def survey(root: str) -> str: + scope = load_scope(root) or Scope( + DEFAULT_STYLES, (), tuple(glob_regex(g) for g in DEFAULT_EXCLUDE) + ) + files = git_files(root, "ls-files", "--cached", "--others", "--exclude-standard") + suffixes = Counter(Path(f).suffix for f in files if Path(f).suffix) + reviewable = [f for f in files if scope.allows(f)] + generated = [f for f in reviewable if is_generated(head(Path(root, f)))] + kept = [f for f in reviewable if f not in generated] + conventional = Counter( + part for f in kept for part in set(Path(f).parts[:-1]) if part in CONVENTIONAL_DIRS + ) + lines = ["extensions (files, style):"] + lines += [f" {ext} {n} {scope.styles.get(ext, 'unsupported')}" for ext, n in suffixes.most_common(15)] + lines.append("reviewable files per top-level directory:") + lines += [f" {d} {n}" for d, n in Counter(f.split("/")[0] if "/" in f else "." for f in kept).most_common()] + lines.append(f"generated files skipped: {len(generated)}") + lines.append("conventional directories present (reviewable files):") + lines += [f" {d} {n}" for d, n in conventional.most_common()] + return "\n".join(lines) + + +def head(path: Path) -> str: + try: + with path.open("rb") as handle: + return handle.read(400).decode(errors="ignore") + except OSError: + return "" + + +def read_hook_input() -> dict: + if sys.stdin.isatty(): + return {} + try: + value = json.loads(sys.stdin.read().strip() or "{}") + except ValueError: + return {} + return value if isinstance(value, dict) else {} + + def main() -> int: + if "--survey" in sys.argv: + top = git(os.getcwd(), "rev-parse", "--show-toplevel") + if not top: + print("not a git repository", file=sys.stderr) + return 1 + try: + print(survey(top[0])) + except ValueError as error: + print(f"bad config: {error}", file=sys.stderr) + return 1 + return 0 if os.environ.get(GUARD): return 0 - hook_input = {} if sys.stdin.isatty() else json.loads(sys.stdin.read().strip() or "{}") + hook_input = read_hook_input() if hook_input.get("stop_hook_active"): return 0 dry_run = "--dry-run" in sys.argv diff --git a/tests/test_trim_comments.py b/tests/test_trim_comments.py index 33eea75..7d17637 100644 --- a/tests/test_trim_comments.py +++ b/tests/test_trim_comments.py @@ -8,7 +8,8 @@ from trim_comments import ( Comment, edit_is_safe, edited_paths, find_comments, is_generated, load_scope, review_repo, reviewer_model, - targets, touched_files, worker_model, + python_docstrings, python_shape, read_hook_input, run_reviewer, survey, targets, touched_files, + worker_model, ) PY = '''#!/usr/bin/env python3 @@ -228,6 +229,8 @@ def fake_claude(tmp_path, monkeypatch, mode): f"#!{sys.executable}\n" "import os, sys\n" "mode = os.environ['FAKE_CLAUDE']\n" + "if os.environ.get('FAKE_LOG'):\n" + " open(os.environ['FAKE_LOG'], 'a').write('x')\n" "if mode == 'fail':\n" " sys.stderr.write('quota'); sys.exit(1)\n" "lines = open('a.py').read().splitlines(True)\n" @@ -235,6 +238,10 @@ def fake_claude(tmp_path, monkeypatch, mode): " lines = [l for l in lines if '# note' not in l]\n" "if mode == 'mangle':\n" " lines = [l.replace('return x', 'return 0') for l in lines if '# note' not in l]\n" + "if mode == 'mangle_fail':\n" + " open('a.py', 'w').write('def f(x):\\n return 0\\n')\n" + " open('other.py', 'a').write('x = 2\\n')\n" + " sys.stderr.write('quota'); sys.exit(1)\n" "if mode == 'stray':\n" " open('other.py', 'a').write('x = 2\\n')\n" "if mode == 'create':\n" @@ -257,13 +264,23 @@ def review(tmp_path, rels=("a.py",)): return review_repo(str(tmp_path), set(rels), "haiku", False, time.monotonic() + 60) -def test_review_trims_and_skips_the_same_content_next_time(tmp_path, monkeypatch): +def test_review_trims_a_comment(tmp_path, monkeypatch): repo_with_comment(tmp_path) fake_claude(tmp_path, monkeypatch, "trim") assert "removed 1 of 1 comments in 1 files" in review(tmp_path) assert (tmp_path / "a.py").read_text() == "def f(x):\n return x\n" + + +def test_review_skips_a_file_whose_content_was_already_reviewed(tmp_path, tmp_path_factory, monkeypatch): + repo_with_comment(tmp_path) + log = tmp_path_factory.mktemp("log") / "calls.log" + monkeypatch.setenv("FAKE_LOG", str(log)) + fake_claude(tmp_path, monkeypatch, "keep") + + assert "removed 0 of 1 comments" in review(tmp_path) assert review(tmp_path) is None + assert log.read_text() == "x" def test_review_restores_a_file_whose_code_changed(tmp_path, monkeypatch): @@ -275,6 +292,8 @@ def test_review_restores_a_file_whose_code_changed(tmp_path, monkeypatch): assert "reverted unsafe edit to a.py" in message assert (tmp_path / "a.py").read_text() == original + rejected = tmp_path / ".git" / "trim-comments-rejected" / "a.py" + assert "return 0" in rejected.read_text() def test_review_reports_files_changed_outside_the_flagged_set(tmp_path, monkeypatch): @@ -376,3 +395,136 @@ def test_review_deletes_a_file_the_reviewer_created(tmp_path, monkeypatch): assert "reverted reviewer edits to made.py" in review(tmp_path) assert not (tmp_path / "made.py").exists() + + +def test_survey_reports_styles_directories_generated_files_and_config_errors(tmp_path): + subprocess.run(["git", "init", "-q", str(tmp_path)], check=True) + for rel, text in { + "src/a.py": "x = 1\n", + "src/b.py": "x = 1\n", + "tests/t.py": "x = 1\n", + "web/c.vue": "