etch-loop 0.1.0__tar.gz → 0.2.0__tar.gz

etch_loop-0.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: etch-loop
+Version: 0.2.0
+Summary: Run Claude Code in a fix-break loop until your codebase is clean
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+```
+  ███████╗████████╗ ██████╗██╗  ██╗
+  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
+  █████╗     ██║   ██║     ███████║
+  ██╔══╝     ██║   ██║     ██╔══██║
+  ███████╗   ██║   ╚██████╗██║  ██║
+  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
+```
+
+> Run Claude Code in a scan-fix-break loop until your codebase is clean.
+
+---
+
+```
+┌─ etch loop v0.2.0  . ───────────────────────────────────────────────┐
+│                                                                      │
+│  -  iteration  1                                                     │
+│  +  scanner    issues found   src/auth.py:42 — no empty token check  │
+│  +  fixer      committed      fix(edge): guard empty token in auth   │
+│  x  breaker    issues         unguarded access still reachable       │
+│                                                                      │
+│  -  iteration  2                                                     │
+│  +  scanner    issues found   src/auth.py:61 — missing None check    │
+│  +  fixer      committed      fix(edge): null guard on session obj   │
+│  >  breaker    running        ░░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░   │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  iterations 2   fixes 2   breaker issues 1   1m 48s elapsed         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## install
+
+```bash
+uv tool install etch-loop
+```
+
+## usage
+
+```bash
+etch init                        # analyze codebase with Claude, write prompt files
+etch run                         # start the loop
+etch run "the auth module"       # focus on a specific area
+etch run -n 5                    # max 5 iterations
+etch run --dry-run               # preview prompt, don't run
+etch run --verbose               # show full Claude output
+```
+
+---
+
+## how it works
+
+Each iteration has three phases: **scan → fix → break**.
+
+1. **Scanner** reads the codebase and outputs a specific list of issues — file paths, line numbers, descriptions
+2. If the scanner finds nothing, the loop stops
+3. **Fixer** receives the scanner's list and fixes those exact issues, then commits
+4. **Breaker** adversarially reviews the full codebase, looking for anything missed or newly introduced
+5. If the breaker finds nothing, the loop stops — clean pass
+6. If the breaker finds something, it's fed back to the next iteration's fixer
+
+```
+┌─ done ───────────────────────────────────────────────────┐
+│                                                          │
+│  iterations      3                                       │
+│  fixes           3                                       │
+│  breaker issues  1                                       │
+│  elapsed         2m 44s                                  │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## etch init
+
+`etch init` runs Claude against your codebase before writing any files. It reads your source, detects the languages and structure, and generates three prompt files tailored to your project — no placeholders to edit.
+
+```
+┌─ etch init v0.2.0 ───────────────────────────────────────┐
+│  >  analyzing  ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
+│  +  analyzed codebase                                    │
+│  +  SCAN.md                                              │
+│  +  ETCH.md                                              │
+│  +  BREAK.md                                             │
+└──────────────────────────────────────────────────────────┘
+```
+
+**`SCAN.md`** — tells the scanner what to look for and how to report findings.
+
+**`ETCH.md`** — tells the fixer how to fix things: surgical, no refactoring, one fix per commit.
+
+**`BREAK.md`** — tells the breaker to scan the full codebase adversarially and report anything that could go wrong.
+
+All three files are editable. Use `etch run "focus description"` to narrow the scope without editing files.
+
+---
+
+## requirements
+
+- Python 3.11+
+- [`claude`](https://claude.ai/code) CLI installed and authenticated
+- A git repository (etch-loop commits each fix automatically)

etch_loop-0.2.0/README.md

@@ -0,0 +1,105 @@
+```
+  ███████╗████████╗ ██████╗██╗  ██╗
+  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
+  █████╗     ██║   ██║     ███████║
+  ██╔══╝     ██║   ██║     ██╔══██║
+  ███████╗   ██║   ╚██████╗██║  ██║
+  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
+```
+
+> Run Claude Code in a scan-fix-break loop until your codebase is clean.
+
+---
+
+```
+┌─ etch loop v0.2.0  . ───────────────────────────────────────────────┐
+│                                                                      │
+│  -  iteration  1                                                     │
+│  +  scanner    issues found   src/auth.py:42 — no empty token check  │
+│  +  fixer      committed      fix(edge): guard empty token in auth   │
+│  x  breaker    issues         unguarded access still reachable       │
+│                                                                      │
+│  -  iteration  2                                                     │
+│  +  scanner    issues found   src/auth.py:61 — missing None check    │
+│  +  fixer      committed      fix(edge): null guard on session obj   │
+│  >  breaker    running        ░░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░   │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  iterations 2   fixes 2   breaker issues 1   1m 48s elapsed         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## install
+
+```bash
+uv tool install etch-loop
+```
+
+## usage
+
+```bash
+etch init                        # analyze codebase with Claude, write prompt files
+etch run                         # start the loop
+etch run "the auth module"       # focus on a specific area
+etch run -n 5                    # max 5 iterations
+etch run --dry-run               # preview prompt, don't run
+etch run --verbose               # show full Claude output
+```
+
+---
+
+## how it works
+
+Each iteration has three phases: **scan → fix → break**.
+
+1. **Scanner** reads the codebase and outputs a specific list of issues — file paths, line numbers, descriptions
+2. If the scanner finds nothing, the loop stops
+3. **Fixer** receives the scanner's list and fixes those exact issues, then commits
+4. **Breaker** adversarially reviews the full codebase, looking for anything missed or newly introduced
+5. If the breaker finds nothing, the loop stops — clean pass
+6. If the breaker finds something, it's fed back to the next iteration's fixer
+
+```
+┌─ done ───────────────────────────────────────────────────┐
+│                                                          │
+│  iterations      3                                       │
+│  fixes           3                                       │
+│  breaker issues  1                                       │
+│  elapsed         2m 44s                                  │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## etch init
+
+`etch init` runs Claude against your codebase before writing any files. It reads your source, detects the languages and structure, and generates three prompt files tailored to your project — no placeholders to edit.
+
+```
+┌─ etch init v0.2.0 ───────────────────────────────────────┐
+│  >  analyzing  ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
+│  +  analyzed codebase                                    │
+│  +  SCAN.md                                              │
+│  +  ETCH.md                                              │
+│  +  BREAK.md                                             │
+└──────────────────────────────────────────────────────────┘
+```
+
+**`SCAN.md`** — tells the scanner what to look for and how to report findings.
+
+**`ETCH.md`** — tells the fixer how to fix things: surgical, no refactoring, one fix per commit.
+
+**`BREAK.md`** — tells the breaker to scan the full codebase adversarially and report anything that could go wrong.
+
+All three files are editable. Use `etch run "focus description"` to narrow the scope without editing files.
+
+---
+
+## requirements
+
+- Python 3.11+
+- [`claude`](https://claude.ai/code) CLI installed and authenticated
+- A git repository (etch-loop commits each fix automatically)

{etch_loop-0.1.0 → etch_loop-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "etch-loop"
-version = "0.1.0"
+version = "0.2.0"
 requires-python = ">=3.11"
 description = "Run Claude Code in a fix-break loop until your codebase is clean"
 readme = "README.md"

etch_loop-0.2.0/src/etch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

etch_loop-0.2.0/src/etch/analyze.py

@@ -0,0 +1,306 @@
+"""Codebase analysis for generating tailored prompt files."""
+
+from __future__ import annotations
+
+import subprocess
+from collections import Counter
+from pathlib import Path
+
+
+_LANG_MAP: dict[str, str] = {
+    ".py": "Python",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".swift": "Swift",
+    ".cpp": "C++",
+    ".c": "C",
+    ".cs": "C#",
+    ".php": "PHP",
+    ".ex": "Elixir",
+    ".exs": "Elixir",
+    ".hs": "Haskell",
+    ".scala": "Scala",
+    ".clj": "Clojure",
+    ".lua": "Lua",
+    ".sh": "Shell",
+    ".bash": "Shell",
+}
+
+_FRAMEWORK_HINTS: dict[str, str] = {
+    "pyproject.toml": "Python project",
+    "setup.py": "Python project",
+    "package.json": "Node.js project",
+    "go.mod": "Go module",
+    "Cargo.toml": "Rust crate",
+    "Gemfile": "Ruby project",
+    "pom.xml": "Java/Maven project",
+    "build.gradle": "Java/Gradle project",
+    "mix.exs": "Elixir/Mix project",
+    "composer.json": "PHP project",
+}
+
+_SKIP_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "env",
+    "dist", "build", ".next", "target", "vendor", ".cache",
+}
+
+
+def analyze(root: Path | None = None) -> dict:
+    """Analyze a codebase and return structured info.
+
+    Returns a dict with keys:
+        languages: list of (language, file_count) sorted by count
+        source_dirs: list of top-level source directories
+        entry_points: list of likely entry point files
+        framework: detected framework/project type string or None
+        total_files: int
+        is_git: bool
+    """
+    root = root or Path.cwd()
+
+    files = _list_files(root)
+    total = len(files)
+
+    # Language detection
+    ext_counts: Counter[str] = Counter()
+    for f in files:
+        ext = Path(f).suffix.lower()
+        if ext in _LANG_MAP:
+            ext_counts[ext] += 1
+
+    lang_counts: Counter[str] = Counter()
+    for ext, count in ext_counts.items():
+        lang_counts[_LANG_MAP[ext]] += count
+
+    languages = lang_counts.most_common(3)
+
+    # Source directories (top-level dirs that contain source files)
+    top_dirs: Counter[str] = Counter()
+    for f in files:
+        parts = Path(f).parts
+        if len(parts) > 1 and parts[0] not in _SKIP_DIRS:
+            top_dirs[parts[0]] += 1
+
+    source_dirs = [d for d, _ in top_dirs.most_common(5) if not d.startswith(".")]
+
+    # Entry points
+    entry_points = _find_entry_points(root, files)
+
+    # Framework detection
+    framework = None
+    for marker, label in _FRAMEWORK_HINTS.items():
+        if (root / marker).exists():
+            framework = label
+            break
+
+    return {
+        "languages": languages,
+        "source_dirs": source_dirs,
+        "entry_points": entry_points,
+        "framework": framework,
+        "total_files": total,
+        "is_git": (root / ".git").exists(),
+    }
+
+
+def build_init_prompt(info: dict) -> str:
+    """Build the Claude prompt used during etch init to analyze the codebase."""
+    file_tree = "\n".join(f"  {f}" for f in _list_files(Path.cwd())[:60])
+    if not file_tree:
+        file_tree = "  (no tracked files)"
+
+    lang_summary = ", ".join(f"{lang} ({n})" for lang, n in info["languages"]) or "unknown"
+    framework = info["framework"] or "unknown"
+
+    return f"""You are analyzing a codebase to configure an automated edge-case hunting tool.
+
+The tool will run Claude Code in a fix-break loop to find and patch edge cases.
+Your job is to write a focused scope description that tells the fixer exactly where to look.
+
+## Codebase stats
+- Framework: {framework}
+- Languages: {lang_summary}
+- Total files: {info["total_files"]}
+
+## File tree
+{file_tree}
+
+## Instructions
+
+Read the key source files in this codebase. Then write a concise scope description covering:
+- The highest-risk areas for edge cases in THIS specific codebase
+- Specific files or modules worth focusing on
+- Any patterns you spotted that suggest missing error handling
+
+Rules:
+- Output ONLY the scope description as plain prose or bullet points
+- No markdown headers, no preamble, no "here is the scope" intro
+- Be specific to this codebase — not generic advice
+- Keep it under 150 words
+"""
+
+
+def build_scan_md(info: dict, agent_scope: str | None = None) -> str:
+    """Generate a tailored SCAN.md from analysis results."""
+    scope = agent_scope.strip() if agent_scope else _format_scope(info)
+
+    return f"""# SCAN — scanner prompt
+
+You are a code analyst. Your job is to find edge cases before the fixer runs.
+
+## Your mission
+
+Read the codebase and produce a precise, actionable list of issues:
+- Unhandled edge cases and boundary conditions
+- Missing null/None/empty checks
+- Unhandled exceptions and error paths
+- Off-by-one errors
+- Race conditions or unsafe concurrent access
+- Missing input validation at system boundaries
+
+For each issue, include the file path, line number (if known), and a one-line description.
+
+## Rules
+
+1. DO NOT edit any files — read only
+2. List each issue on its own line, e.g.:
+   - src/auth.py:42 — no check for empty token string
+   - src/api.js:108 — unhandled promise rejection in fetchUser()
+3. Be specific — vague findings are not useful
+4. End your output with EXACTLY one of these tokens on its own line:
+   - `ETCH_ISSUES_FOUND` — if you found issues worth fixing
+   - `ETCH_ALL_CLEAR` — if the code looks solid
+
+## Scope
+
+{scope}
+"""
+
+
+def build_etch_md(info: dict, agent_scope: str | None = None) -> str:
+    """Generate a tailored ETCH.md from analysis results."""
+    scope = agent_scope.strip() if agent_scope else _format_scope(info)
+
+    return f"""# ETCH — fixer prompt
+
+You are a surgical code reviewer focused on edge cases and robustness.
+
+## Your mission
+
+Scan the codebase for:
+- Unhandled edge cases and boundary conditions
+- Missing null/None/empty checks
+- Unhandled exceptions and error paths
+- Off-by-one errors
+- Race conditions or unsafe concurrent access
+- Missing input validation at system boundaries
+
+## Rules
+
+1. Fix only what you find — do not refactor, rename, or reorganize
+2. One logical fix per commit (the harness will commit for you)
+3. Do not add comments explaining what you fixed
+4. If you find nothing, make no changes
+
+## Scope
+
+{scope}
+
+## Commit format
+
+The harness commits automatically. Each commit will be:
+  fix(edge): <short description of what was fixed>
+"""
+
+
+def build_break_md(info: dict, agent_scope: str | None = None) -> str:
+    """Generate a tailored BREAK.md from analysis results."""
+    scope = agent_scope.strip() if agent_scope else _format_scope(info)
+
+    return f"""# BREAK — breaker prompt
+
+You are an adversarial code reviewer. Your job is to find anything that could go wrong.
+
+## Your mission
+
+Scan the entire codebase with fresh eyes. Do not limit yourself to recent changes.
+
+Look for:
+- Edge cases and boundary conditions that are unhandled anywhere in the code
+- Functions that assume valid input without checking
+- Error paths that are silently swallowed or ignored
+- Race conditions, off-by-one errors, null/empty/zero not guarded
+- Anything that would cause unexpected behavior in production
+
+Be adversarial — think like someone actively trying to make this code fail.
+
+## Rules
+
+1. DO NOT edit any files — read only
+2. Report your findings clearly, one per line
+3. End your output with EXACTLY one of these tokens on its own line:
+   - `ETCH_ISSUES_FOUND` — if you found anything worth fixing
+   - `ETCH_ALL_CLEAR` — if the code looks solid
+
+## Scope
+
+{scope}
+"""
+
+
+def _format_scope(info: dict) -> str:
+    lines = []
+    if info["source_dirs"]:
+        dirs = "  ".join(f"{d}/" for d in info["source_dirs"])
+        lines.append(f"Directories: {dirs}")
+    if info["entry_points"]:
+        eps = "  ".join(info["entry_points"][:3])
+        lines.append(f"Entry points: {eps}")
+    if info["framework"]:
+        lines.append(f"Project type: {info['framework']}")
+    lines.append(f"Total tracked files: {info['total_files']}")
+    return "\n".join(lines) if lines else "Entire repository"
+
+
+def _list_files(root: Path) -> list[str]:
+    """Return tracked files via git ls-files, falling back to filesystem walk."""
+    try:
+        result = subprocess.run(
+            ["git", "ls-files"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip().splitlines()
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+
+    # Fallback: walk filesystem
+    files = []
+    for p in root.rglob("*"):
+        if p.is_file() and not any(part in _SKIP_DIRS for part in p.parts):
+            try:
+                files.append(str(p.relative_to(root)))
+            except ValueError:
+                pass
+    return files
+
+
+def _find_entry_points(root: Path, files: list[str]) -> list[str]:
+    """Heuristically identify entry point files."""
+    candidates = []
+    names = {"main.py", "app.py", "index.ts", "index.js", "main.go",
+              "main.rs", "server.py", "server.ts", "cli.py", "manage.py"}
+    for f in files:
+        if Path(f).name in names:
+            candidates.append(f)
+    return candidates[:4]

etch_loop-0.2.0/src/etch/cli.py

@@ -0,0 +1,107 @@
+"""CLI entry points for etch-loop."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from etch import agent, analyze, display, loop
+from etch.agent import AgentError
+
+app = typer.Typer(
+    name="etch",
+    help="Run Claude Code in a fix-break loop, hunting for edge cases.",
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+
+@app.command()
+def init() -> None:
+    """Analyze the codebase with Claude and write tailored SCAN.md, ETCH.md, BREAK.md."""
+    root = Path.cwd()
+    info = analyze.analyze(root)
+    init_prompt = analyze.build_init_prompt(info)
+
+    agent_scope: str | None = None
+    with display.InitDisplay() as disp:
+        disp.start_scan()
+        try:
+            agent_scope = agent.run(init_prompt)
+            disp.finish_scan(success=True)
+        except AgentError as exc:
+            disp.finish_scan(success=False)
+            disp.add_line(display.SYM_NEUTRAL, display.DIM, f"falling back to static analysis ({exc})")
+
+        for dest, content, label in [
+            (root / "SCAN.md",  analyze.build_scan_md(info, agent_scope),  "SCAN.md"),
+            (root / "ETCH.md",  analyze.build_etch_md(info, agent_scope),  "ETCH.md"),
+            (root / "BREAK.md", analyze.build_break_md(info, agent_scope), "BREAK.md"),
+        ]:
+            if dest.exists():
+                disp.add_line(display.SYM_NEUTRAL, display.DIM, f"{label} already exists, skipping")
+            else:
+                dest.write_text(content, encoding="utf-8")
+                disp.add_line(display.SYM_OK, display.GREEN, label)
+
+
+@app.command()
+def run(
+    focus: str = typer.Argument(
+        default=None,
+        help="Optional focus description, e.g. 'the auth module' or 'error handling in payments'.",
+    ),
+    prompt: str = typer.Option(
+        "./ETCH.md",
+        "--prompt",
+        help="Path to the fixer prompt file (ETCH.md).",
+        show_default=True,
+    ),
+    max_iterations: int = typer.Option(
+        20,
+        "--max-iterations",
+        "-n",
+        help="Maximum number of fix-break cycles.",
+        show_default=True,
+        min=1,
+    ),
+    no_commit: bool = typer.Option(
+        False,
+        "--no-commit",
+        help="Skip git commits after fixer runs.",
+        is_flag=True,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the fixer prompt and exit without running.",
+        is_flag=True,
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Stream agent output to the terminal.",
+        is_flag=True,
+    ),
+) -> None:
+    """Run the fix-break loop against the current repository.
+
+    Optionally pass a focus description to narrow the scan:
+
+      etch run "the authentication module"
+
+      etch run "error handling in the payments flow"
+    """
+    try:
+        loop.run(
+            prompt_path=prompt,
+            max_iterations=max_iterations,
+            no_commit=no_commit,
+            dry_run=dry_run,
+            verbose=verbose,
+            focus=focus,
+        )
+    except KeyboardInterrupt:
+        display.print_interrupted()
+        raise typer.Exit(code=130)