feat: preservation markers -- SAAR:AUTO-START/END protect manual edits on re-run (OPE-140)

Author: DevanshuNEU

AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md -- saar
+
+Generated by [saar](https://getsaar.com). Re-run `saar . --format agents` to update auto-detected sections.
+
+160 functions, 25 classes, 16% async, 89% type-hinted.
+
+**Languages:** python (19 files)
+
+## Coding Conventions
+
+- Functions: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+
+Preferred imports:
+```
+from saar.models import CodebaseDNA
+import logging
+from pathlib import Path
+import re
+import tree_sitter_python as tspython
+import tree_sitter_javascript as tsjavascript
+from tree_sitter import Language, Parser
+from collections import Counter
+```
+
+## Logging
+
+- Use `logging.getLogger(__name__)` -- never bare `print()`
+
+## Critical Files
+
+These files have the most dependents in the codebase. Understand them before making changes.
+
+- `saar/models.py` (9 dependents)
+- `saar/dependency_analyzer.py` (2 dependents)
+- `saar/style_analyzer.py` (2 dependents)
+- `saar/extractor.py` (2 dependents)
+- `saar/formatters/markdown.py` (2 dependents)
+- `saar/formatters/claude_md.py` (2 dependents)
+- `saar/formatters/cursorrules.py` (2 dependents)
+- `saar/formatters/agents_md.py` (2 dependents)
+
+## Error Handling
+
+- Log exceptions before re-raising
+
+## Testing
+
+- Framework: pytest
+- Pattern: `test_*.py`
+- Fixtures: pytest fixtures
+- Mocking: unittest.mock
+- Shared fixtures in `conftest.py`
+
+## Project-Specific Rules
+
+*From `CLAUDE.md`*
+
+# CLAUDE.md -- saar
+
+160 functions, 25 classes.
+Async adoption: 16%.
+Type hint coverage: 89%.
+
+## Coding Conventions
+
+- Use `snake_case` for function names
+- Use `PascalCase` for class names
+- Use `UPPER_SNAKE_CASE` for constants
+
+Preferred imports:
+```
+from saar.models import CodebaseDNA
+import logging
+from pathlib import Path
+import re
+import tree_sitter_python as tspython
+import tree_sitter_javascript as tsjavascript
+from tree_sitter import Language, Parser
+from collections import Counter
+```
+
+## Logging
+
+- Use `logging.getLogger(__name__)` for all logging, never `print()`
+
+## Critical Files
+
+These files have the most dependents -- understand them before editing:
+
+- `saar/models.py` (9 dependents)
+- `saar/dependency_analyzer.py` (2 dependents)
+- `saar/style_analyzer.py` (2 dependents)
+- `saar/extractor.py` (2 dependents)
+- `saar/formatters/agents_md.py` (2 dependents)
+- `saar/formatters/copilot.py` (2 dependents)
+- `saar/formatters/claude_md.py` (2 dependents)
+- `saar/formatters/__init__.py` (2 dependents)
+
+## Error Handling
+
+- Always log exceptions before re-raising
+
+## Testing
+
+- Framework: pytest
+- Test file pattern: `test_*.py`
+- Fixture style: pytest fixtures
+- Mock with: unittest.mock
+- Shared fixtures live in `conftest.py`
+- Run: `pytest tests/ -v`

CLAUDE.md

@@ -1,6 +1,7 @@
+<!-- SAAR:AUTO-START -->
 # CLAUDE.md -- saar
 
-160 functions, 25 classes.
+164 functions, 26 classes.
 Async adoption: 16%.
 Type hint coverage: 89%.
 
@@ -34,9 +35,9 @@ These files have the most dependents -- understand them before editing:
 - `saar/dependency_analyzer.py` (2 dependents)
 - `saar/style_analyzer.py` (2 dependents)
 - `saar/extractor.py` (2 dependents)
-- `saar/formatters/agents_md.py` (2 dependents)
-- `saar/formatters/copilot.py` (2 dependents)
 - `saar/formatters/claude_md.py` (2 dependents)
+- `saar/formatters/copilot.py` (2 dependents)
+- `saar/formatters/cursorrules.py` (2 dependents)
 - `saar/formatters/__init__.py` (2 dependents)
 
 ## Error Handling
@@ -51,3 +52,4 @@ These files have the most dependents -- understand them before editing:
 - Mock with: unittest.mock
 - Shared fixtures live in `conftest.py`
 - Run: `pytest tests/ -v`
+<!-- SAAR:AUTO-END -->

saar/cli.py

@@ -139,13 +139,11 @@ def extract(
         target = _resolve_output_path(fmt, output, repo_path)
 
         if target is None:
+            # markdown goes to stdout -- no markers needed
             console.print(text)
-        elif target.exists() and not force:
-            console.print(f"  [yellow]skipped[/yellow] {target} (exists, use --force to overwrite)")
         else:
             target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(text, encoding="utf-8")
-            console.print(f"  [green]wrote[/green] {target}")
+            _write_with_markers(target, text, force=force, console=console)
 
     console.print("[bold green]done[/bold green]")
 
@@ -163,3 +161,51 @@ def _resolve_output_path(
 
     base = output_dir if output_dir else repo_path
     return base / filename
+
+
+_MARKER_START = "<!-- SAAR:AUTO-START -->"
+_MARKER_END = "<!-- SAAR:AUTO-END -->"
+
+
+def _write_with_markers(
+    target: Path, generated: str, *, force: bool, console: Console
+) -> None:
+    """Write generated content to target, preserving human edits outside markers.
+
+    On first write: wraps content in SAAR:AUTO-START/END markers.
+    On re-run: replaces only what's between the markers. Content the developer
+    wrote outside the markers (before or after) is never touched.
+
+    --force bypasses preservation and overwrites the whole file. Use it when
+    you want a clean slate with no manual edits preserved.
+    """
+    wrapped = f"{_MARKER_START}\n{generated.rstrip()}\n{_MARKER_END}\n"
+
+    if not target.exists():
+        target.write_text(wrapped, encoding="utf-8")
+        console.print(f"  [green]wrote[/green] {target}")
+        return
+
+    existing = target.read_text(encoding="utf-8")
+
+    if force:
+        # full overwrite -- discard everything including manual edits
+        target.write_text(wrapped, encoding="utf-8")
+        console.print(f"  [green]overwrote[/green] {target}")
+        return
+
+    start_idx = existing.find(_MARKER_START)
+    end_idx = existing.find(_MARKER_END)
+
+    if start_idx == -1 or end_idx == -1:
+        # No markers -- file exists but was written before markers were introduced
+        # (or is purely hand-written). Treat it like first write: prepend auto block.
+        target.write_text(wrapped + "\n" + existing, encoding="utf-8")
+        console.print(f"  [green]updated[/green] {target} (prepended auto block)")
+        return
+
+    # Splice: keep everything before the start marker and after the end marker
+    before = existing[:start_idx]
+    after = existing[end_idx + len(_MARKER_END):]
+    target.write_text(before + wrapped + after, encoding="utf-8")
+    console.print(f"  [green]updated[/green] {target} (preserved manual edits)")

tests/test_cli.py

@@ -82,17 +82,62 @@ def test_verbose_flag(self, tmp_repo: Path):
         result = runner.invoke(app, [str(tmp_repo), "--verbose"])
         assert result.exit_code == 0
 
-    def test_skips_existing_without_force(self, tmp_repo: Path):
-        """Should not overwrite existing CLAUDE.md without --force."""
-        existing = tmp_repo / "CLAUDE.md"
-        original = existing.read_text()
-        result = runner.invoke(app, [str(tmp_repo), "--format", "claude"])
+    def test_skips_existing_without_force(self, tmp_repo: Path, tmp_path: Path):
+        """File with markers: re-run updates auto block, does not skip entirely."""
+        output_dir = tmp_path / "out"
+        output_dir.mkdir()
+        # first run creates the file
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        first = (output_dir / "CLAUDE.md").read_text()
+        # second run without --force should update (not skip) because markers exist
+        result = runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
         assert result.exit_code == 0
-        assert "skipped" in result.stdout
-        assert existing.read_text() == original
+        assert "updated" in result.stdout or "wrote" in result.stdout
 
-    def test_force_overwrites(self, tmp_repo: Path):
-        """--force should overwrite existing files."""
-        result = runner.invoke(app, [str(tmp_repo), "--format", "claude", "--force"])
+    def test_force_overwrites(self, tmp_repo: Path, tmp_path: Path):
+        """--force does a clean overwrite discarding any manual edits."""
+        output_dir = tmp_path / "out"
+        output_dir.mkdir()
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        result = runner.invoke(
+            app, [str(tmp_repo), "--format", "claude", "--force", "-o", str(output_dir)]
+        )
         assert result.exit_code == 0
-        assert "wrote" in result.stdout
+        assert "overwrote" in result.stdout or "wrote" in result.stdout
+
+
+class TestPreservationMarkers:
+    """SAAR:AUTO-START/END markers preserve manual edits on re-run."""
+
+    def test_first_write_adds_markers(self, tmp_repo: Path, tmp_path: Path):
+        output_dir = tmp_path / "out"
+        output_dir.mkdir()
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        content = (output_dir / "CLAUDE.md").read_text()
+        assert "<!-- SAAR:AUTO-START -->" in content
+        assert "<!-- SAAR:AUTO-END -->" in content
+
+    def test_rerun_preserves_manual_edits(self, tmp_repo: Path, tmp_path: Path):
+        output_dir = tmp_path / "out"
+        output_dir.mkdir()
+        # first run
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        # developer adds a custom note after the auto block
+        target = output_dir / "CLAUDE.md"
+        target.write_text(target.read_text() + "\n## My Custom Notes\n- Never touch auth.py\n")
+        # second run
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        content = target.read_text()
+        assert "My Custom Notes" in content
+        assert "Never touch auth.py" in content
+
+    def test_force_discards_manual_edits(self, tmp_repo: Path, tmp_path: Path):
+        output_dir = tmp_path / "out"
+        output_dir.mkdir()
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "-o", str(output_dir)])
+        target = output_dir / "CLAUDE.md"
+        target.write_text(target.read_text() + "\n## My Custom Notes\n- Secret rule\n")
+        # --force should wipe manual edits
+        runner.invoke(app, [str(tmp_repo), "--format", "claude", "--force", "-o", str(output_dir)])
+        content = target.read_text()
+        assert "Secret rule" not in content