fix: OPE-181/184/185 -- data safety + false positive framework detection

OPE-181: never overwrite hand-crafted AGENTS.md
  - _write_with_markers() now detects files without SAAR markers
  - If existing file has 5+ lines and no markers: skip with clear message
  - Interactive mode: asks user before overwriting
  - Non-interactive/CI: always skips, never silently destroys content
  - --force flag explicitly bypasses protection
  - Tested: PostHog's 78-line AGENTS.md now safely skipped

OPE-185: skip examples/ and compiled/ from all analysis
  - Added to SKIP_DIRS: examples, example, demo, demos, playground,
    playgrounds, starters, templates, fixtures, test-fixtures
  - Added: compiled, bundles, vendor, vendors (OPE-184)
  - Fixes shadcn/Zustand false positives on vercel/next.js
  - Fixes Express false positive on storybookjs/react-native

OPE-178: fix Express false positive from CommonJS require()
  - Was: r'^const\s+\w+\s*=\s*require\(' -- matches ANY require() call
  - Now: r'require\([\'"']express[\'"]')' -- matches only express import
  - Every JS file using CommonJS style was scoring as 'Express backend'
  - storybookjs/react-native: Backend: Express -> no backend (correct)

Also fixed: OPE-179 (markers splice leading newline stripped)
  - after.lstrip('\n') prevents double blank lines below AUTO-END
  - Empty after section no longer adds trailing newline

Tests: 457 passing

Author: DevanshuNEU

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saar"
-version = "0.5.0"
+version = "0.5.1"
 description = "Extract the essence of your codebase. Auto-generate AGENTS.md, CLAUDE.md, .cursorrules and more."
 readme = "README.md"
 license = "MIT"

saar/__init__.py

@@ -1,3 +1,3 @@
 """Saar -- extract the essence of your codebase."""
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"

saar/cli.py

@@ -620,28 +620,75 @@ def _line_count(text: str) -> int:
     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")
+        # No saar markers -- file exists but has never been written by saar.
+        # This means it's either hand-crafted or written by another tool.
+        # We must NOT silently overwrite hand-crafted files. (OPE-181)
+        existing_lines = _line_count(existing)
+
+        if existing_lines >= 5 and not force:
+            # Substantial hand-crafted file -- protect it.
+            # In interactive mode: ask. In non-interactive: skip with clear message.
+            import sys
+            import os
+            is_tty = sys.stdin.isatty() and sys.stdout.isatty()
+            ci = any(os.environ.get(v) for v in [
+                "CI", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL",
+                "CIRCLECI", "TRAVIS", "BUILDKITE",
+            ])
+            interactive = is_tty and not ci
+
+            if interactive:
+                try:
+                    import questionary
+                    answer = questionary.confirm(
+                        f"{_display_path(target)} exists ({existing_lines} lines, "
+                        "not generated by saar). Overwrite it?",
+                        default=False,
+                    ).ask()
+                    if not answer:
+                        console.print(
+                            f"  [yellow]skipped[/yellow] {_display_path(target)}  "
+                            "[dim]Use --force to overwrite.[/dim]"
+                        )
+                        return
+                except Exception:
+                    # questionary not available -- fall through to skip
+                    console.print(
+                        f"  [yellow]skipped[/yellow] {_display_path(target)}  "
+                        f"[dim]({existing_lines} lines, not generated by saar). "
+                        "Use --force to overwrite.[/dim]"
+                    )
+                    return
+            else:
+                # Non-interactive (CI / --no-interview): never overwrite silently.
+                console.print(
+                    f"  [yellow]skipped[/yellow] {_display_path(target)}  "
+                    f"[dim]({existing_lines} lines, not generated by saar). "
+                    "Use --force to overwrite.[/dim]"
+                )
+                return
+
+        # Either force=True, or the file is essentially empty (<5 lines).
+        # Safe to write.
+        target.write_text(wrapped, encoding="utf-8")
         console.print(
-            f"  [green]updated[/green] {_display_path(target)}"
-            f"  [dim]({_line_count(wrapped + existing)} lines)[/dim]"
+            f"  [green]wrote[/green] {_display_path(target)}"
+            f"  [dim]({_line_count(wrapped)} lines)[/dim]"
         )
         return
 
     # Splice: keep everything before the start marker and after the end marker.
-    # Use find() for END to get the first legitimate closing marker (the one that
-    # belongs to this auto-block). Then strip any orphaned SAAR markers from the
-    # preserved manual content -- these can accumulate from old runs or copy-paste.
+    # Splice: keep before START + new auto block + after END.
     # rfind() would be wrong here: it would swallow manual content sitting between
     # the legitimate END and an orphaned END. (OPE-169)
     before = existing[:start_idx]
     after = existing[end_idx + len(_MARKER_END):]
 
-    # Strip any orphaned SAAR markers from the preserved manual section.
+    # Strip orphaned SAAR markers and leading blank lines. (OPE-179)
     after = after.replace(_MARKER_START, "").replace(_MARKER_END, "")
+    after = after.lstrip("\n")
 
-    final = before + wrapped + after
+    final = before + wrapped + ("\n" + after if after.strip() else "")
     target.write_text(final, encoding="utf-8")
     console.print(
         f"  [green]updated[/green] {_display_path(target)}"

saar/extractor.py

@@ -60,12 +60,20 @@ class DNAExtractor:
         "node_modules", ".next", ".nuxt", ".svelte-kit",
         # build outputs
         "dist", "build", "out", "target",
+        # compiled/vendored assets -- never source code (OPE-184)
+        "compiled", "bundles", "vendor", "vendors",
         # test/coverage artifacts
         "coverage", ".pytest_cache", "htmlcov", ".nyc_output",
         # cloned repo dirs (the specific OCI case)
         "repos",
         # ide
         ".idea", ".vscode",
+        # example/demo apps -- not the primary project (OPE-185)
+        # These directories contain demo applications that use different stacks.
+        # Scanning them produces false positives (Express in a React Native lib,
+        # shadcn/ui in the Next.js framework repo itself, etc.)
+        "examples", "example", "demo", "demos", "playground", "playgrounds",
+        "starters", "templates", "fixtures", "test-fixtures",
     }
 
     # file suffixes that are never source code -- skip regardless of directory
@@ -302,7 +310,7 @@ def _detect_framework(self, files: List[Path]) -> Optional[str]:
             "flask": [r"^from flask\b", r"^import flask\b"],
         }
         js_indicators = {
-            "express": [r"^const\s+\w+\s*=\s*require\("],
+            "express": [r"require\(['\"]express['\"]\)", r"from ['\"]express['\"]"],
             "nextjs": [r"^import\s+.*from\s+.next/"],
             "nestjs": [r"^import\s+.*from\s+.@nestjs/"],
         }

tests/test_cli.py

@@ -13,7 +13,7 @@ class TestCLI:
     def test_version(self):
         result = runner.invoke(app, ["--version"])
         assert result.exit_code == 0
-        assert "0.5.0" in result.stdout
+        assert "0.5.1" in result.stdout
 
     def test_help(self):
         result = runner.invoke(app, ["--help"])