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..9b1046d 100644 --- a/README.md +++ b/README.md @@ -175,3 +175,17 @@ 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, plus every +uncommitted or untracked file in the repo the session started in, including work +that predates the session. A reviewer on a different model deletes the ones the code +already says. The reviewer may edit only the flagged files, and an edit that changes +code is restored; outside Python, a `#` line inside a multi-line string (a YAML block +scalar, a heredoc) reads as a comment and can be removed. +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..d586778 --- /dev/null +++ b/skills/setup-trim-comments/SKILL.md @@ -0,0 +1,64 @@ +--- +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. In `exclude`, write a directory as a +plain name (`tests`) to match it at any depth, or as a path (`src/gen`) to anchor it at +the repo root. In `include`, plain names are anchored at the repo root (`src`); use +`**/lib` for any depth. A glob such as `**/migrations/**` works in both, with `*` +staying within a directory and `**` crossing them. + +## 4. Verify + +Run the survey again. Done when it prints no `bad config`, the per-directory +counts match what the user chose, and each excluded conventional directory has left +the `conventional directories present` list. 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..638dcd7 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, no user, project or local settings, 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. An unsafe edit is rolled + back; a deletion that passes is kept, and the file 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,16 @@ 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. + An `exclude` name without a slash (`tests`, `*.snap.py`) matches at any depth, like + gitignore, and covers everything under a directory of that name. A path with a slash + (`src/gen`) and every `include` entry (`src`) is anchored at the repo root; write + `**/lib` to include `lib` at any depth. - 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..07bd094 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,19 @@ def string_list(config: dict, key: str) -> list[str]: return value +def with_subtrees(globs: list[str], any_depth: bool) -> list[str]: + expanded = [] + for glob in globs: + name = glob.rstrip("/") + floating = any_depth and "/" not in name + expanded.append(glob) + if floating: + expanded.append(f"**/{name}") + if not glob.endswith("/**"): + expanded.append(f"**/{name}/**" if floating else f"{name}/**") + return expanded + + def load_scope(root: str) -> Scope | None: try: text = Path(root, CONFIG_FILE).read_text() @@ -210,35 +230,78 @@ 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, any_depth=False)), + tuple(glob_regex(g) for g in [*DEFAULT_EXCLUDE, *with_subtrees(exclude, any_depth=True)]), ) 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, inside_block: bool = False) -> bool: text = line.strip() - return not text or text.startswith(("#", "//", "/*", "* ", "*/")) or text == "*" - - -def tail_trimmed(old: str, new: str) -> bool: - kept = new.rstrip() - return old.startswith(kept) and old[len(kept):].strip().startswith(("#", "//", "/*")) - - -def only_comments_removed(old: str, new: str) -> bool: + if not text: + return True + if style != "slash": + return text.startswith("#") and not text.startswith("#!") + closes_cleanly = "*/" not in text or text.endswith("*/") + if inside_block: + return closes_cleanly + return (text.startswith("//") or text.startswith("/*")) and closes_cleanly + + +def block_flags(lines: list[str]) -> list[bool]: + flags, open_block = [], False + for line in lines: + flags.append(open_block) + if open_block: + open_block = "*/" not in line + else: + opener = comment_start(line, "slash") + open_block = opener is not None and line.startswith("/*", opener) and "*/" not in line[opener:] + return flags + + +def comment_start(line: str, style: str, single_quotes: bool | None = None) -> int | None: + if single_quotes is None: + single_quotes = style == "hash" + quotes = "\"`'" if single_quotes else "\"`" + markers = ("//", "/*") if style == "slash" else ("#",) + quote, escaped = "", False + for i, char in enumerate(line): + if escaped: + escaped = False + elif char == "\\": + escaped = True + elif quote: + quote = "" if char == quote else quote + elif char in quotes: + quote = char + elif line.startswith(markers, i) and (i == 0 or line[i - 1].isspace()): + return i + return None + + +def tail_trimmed(old: str, new: str, style: str, single_quotes: bool) -> bool: + start = comment_start(old, style, single_quotes) + if start is None or new.rstrip() != old[:start].rstrip(): + return False + tail = old[start:] + return not tail.startswith("/*") or "*/" not in tail or tail.rstrip().endswith("*/") + + +def only_comments_removed(old: str, new: str, style: str, single_quotes: bool = True) -> bool: old_lines, new_lines = old.splitlines(), new.splitlines() + inside = block_flags(old_lines) matcher = difflib.SequenceMatcher(None, old_lines, new_lines, autojunk=False) for tag, i1, i2, j1, j2 in matcher.get_opcodes(): if tag == "equal": @@ -247,10 +310,11 @@ def only_comments_removed(old: str, new: str) -> bool: return False 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])): + for i in range(i1, i2): + line = old_lines[i] + if j < len(kept) and (line.rstrip() == kept[j].rstrip() or tail_trimmed(line, kept[j], style, single_quotes)): j += 1 - elif not comment_only(line): + elif not comment_only(line, style, inside[i]): return False if j != len(kept): return False @@ -258,11 +322,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, Path(rel).suffix != ".rs") def git(root: str, *args: str) -> list[str]: @@ -318,7 +384,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 +408,18 @@ 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", + "--setting-sources", "", + "--permission-mode", "dontAsk", "--no-session-persistence", ], input=prompt, @@ -403,22 +473,54 @@ 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]: +def snapshot(root: str) -> dict[str, bytes | None]: 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() if path.stat().st_size <= SNAPSHOT_LIMIT else None + for rel, path in files.items() + if path.is_file() + } + + +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 / f"{rel}.{time.time_ns()}" + 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]: +def undo_strays( + root: str, flagged: dict[str, list[Comment]], before: dict[str, bytes | None] +) -> list[str]: undone = [] for rel, content in snapshot(root).items(): if rel in flagged or before.get(rel) == content: continue + if content is None or (rel in before and before[rel] is None): + 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 +539,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 +568,45 @@ 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() - except (OSError, UnicodeDecodeError): + current = path.read_bytes() + except OSError: + current = None + try: + new = current.decode() if current is not None else None + except UnicodeDecodeError: new = 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 +614,64 @@ 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) + allowed = [f for f in files if scope.allows(f)] + unscopable = [f for f in allowed if UNSCOPABLE & set(f)] + reviewable = [f for f in allowed if f not in unscopable] + 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(f"files skipped for special characters in the path: {len(unscopable)}") + 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..7afb923 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,15 @@ 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 == 'badbytes':\n" + " open('a.py', 'wb').write(b'\\xff\\xfe not utf8\\n')\n" + " sys.exit(0)\n" + "if mode == 'truncate':\n" + " open('other.py', 'w').write('y\\n')\n" "if mode == 'stray':\n" " open('other.py', 'a').write('x = 2\\n')\n" "if mode == 'create':\n" @@ -257,13 +269,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 +297,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").glob("a.py.*") + assert "return 0" in rejected.read_text() def test_review_reports_files_changed_outside_the_flagged_set(tmp_path, monkeypatch): @@ -376,3 +400,236 @@ 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": "