fix: OPE-182 + OPE-183 -- large repo resilience + exception list readability

OPE-182a: RecursionError on complex files now caught gracefully
  - dependency_analyzer.py now catches RecursionError explicitly
  - Logs warning and continues (was crashing visibly on posthog api.ts)
  - RecursionError is a BaseException subclass, not caught by 'except Exception'

OPE-182b: File limit raised 10K->25K + visible warning instead of silent truncation
  - MAX_FILES: 10,000 -> 25,000 (PostHog has 19K, most repos <10K)
  - When limit hit: warning shown in detection summary to the user
  - models.py: CodebaseDNA.analysis_warnings list added
  - CLI _show_detection_summary: prints all analysis_warnings in yellow

OPE-183: Exception list no longer an unreadable blob
  - When <=10 exceptions: listed inline as before
  - When >10 exceptions: shows top 10 + grep command to find the rest
  - PostHog had 105 exceptions in one line -- now shows top 10 + search hint
  - Never-create-new-exception-class rule added automatically when >10 found

Tests: 457 passing

Author: DevanshuNEU

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saar"
-version = "0.5.2"
+version = "0.5.3"
 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.2"
+__version__ = "0.5.3"

saar/cli.py

@@ -530,6 +530,11 @@ def _show_detection_summary(dna, console, no_interview: bool) -> bool:
         table.add_row(label, f"[cyan]{value}[/cyan]")
 
     console.print(table)
+
+    # show analysis warnings (file limit, recursion skips, etc.) -- OPE-182
+    for warning in getattr(dna, "analysis_warnings", []):
+        console.print(f"  [yellow]⚠[/yellow]  [dim]{warning}[/dim]")
+
     console.print()
 
     if not interactive:

saar/dependency_analyzer.py

@@ -135,6 +135,9 @@ def analyze_file(self, file_path: str) -> Dict:
                 "language": language,
                 "import_count": len(imports),
             }
+        except RecursionError:
+            logger.warning("Skipped %s (recursion limit -- file too complex)", file_path)
+            return {"file": file_path, "imports": [], "language": language}
         except Exception as e:
             logger.error("Error analyzing %s: %s", file_path, e)
             return {"file": file_path, "imports": [], "language": language}

saar/extractor.py

@@ -87,7 +87,7 @@ class DNAExtractor:
     }
 
     MAX_FILE_SIZE = 1024 * 1024  # 1MB
-    MAX_FILES = 10000  # raised -- large monorepos can have many files after exclusions
+    MAX_FILES = 25000  # generous limit -- PostHog has 19K, most repos <10K
 
     RULES_FILES = [
         "CLAUDE.md",
@@ -117,6 +117,7 @@ def __init__(self) -> None:
         self._file_cache: Dict[Path, str] = {}
         self._stats = {"files_read": 0, "files_skipped": 0, "read_errors": 0}
         self._active_skip_dirs = set(self.SKIP_DIRS)
+        self._file_limit_hit = False  # set True when MAX_FILES cap is reached
 
     # -- file I/O ---------------------------------------------------------
 
@@ -222,6 +223,8 @@ def _discover_files(self, repo_path: Path) -> Tuple[List[Path], List[Path]]:
                         continue
                     total = len(app_files) + len(test_files)
                     if total >= self.MAX_FILES:
+                        # Store hit count on self so CLI can warn user
+                        self._file_limit_hit = True
                         logger.warning("Hit max file limit (%d)", self.MAX_FILES)
                         break
                     if self._is_test_file(item):
@@ -1395,6 +1398,16 @@ def extract(
             "DNA extraction complete: %.2fs, %d files read, %d skipped",
             elapsed, self._stats["files_read"], self._stats["files_skipped"],
         )
+
+        # surface file limit warning directly on DNA (OPE-182)
+        if self._file_limit_hit:
+            total_files = len(app_files) + len(test_files)
+            dna.analysis_warnings.append(
+                f"Large repo: analysed {total_files:,} files (cap={self.MAX_FILES:,}). "
+                "Some files may be missing from critical-files and exception detection. "
+                "Use --exclude to focus on specific directories."
+            )
+
         return dna
 
     def _enrich_with_style(self, dna: CodebaseDNA, repo_path: str) -> None:

saar/formatters/agents_md.py

@@ -224,7 +224,22 @@ def render_agents_md(dna: CodebaseDNA) -> str:
     if ep.exception_classes or ep.http_exception_usage or ep.logging_on_error:
         lines.append("\n## Error Handling\n")
         if ep.exception_classes:
-            lines.append(f"- Use domain exceptions: `{', '.join(ep.exception_classes)}`")
+            all_exc = ep.exception_classes
+            total = len(all_exc)
+            if total <= 10:
+                # few enough -- list them all inline
+                lines.append(f"- Use domain exceptions: `{', '.join(all_exc)}`")
+            else:
+                # too many to list -- show top 10 + search hint (OPE-183)
+                top = all_exc[:10]
+                lines.append(
+                    f"- Use domain exceptions ({total} total). Most common: "
+                    f"`{', '.join(top)}`"
+                )
+                lines.append(
+                    "- Never create new exception classes without checking: "
+                    "`grep -r 'class.*Error\\|class.*Exception' . --include='*.py' -l`"
+                )
         if ep.http_exception_usage:
             lines.append("- Use HTTPException for API errors")
         if ep.logging_on_error:

saar/models.py

@@ -165,6 +165,8 @@ class CodebaseDNA:
     # canonical examples -- most-imported file per category (OPE-142)
     # Each entry: {"category": str, "file": str, "import_count": int, "reason": str}
     canonical_examples: List = field(default_factory=list)
+    # analysis warnings -- shown in detection summary (e.g. file limit hit)
+    analysis_warnings: List[str] = field(default_factory=list)
 
     def to_dict(self) -> Dict:
         return asdict(self)

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.2" in result.stdout
+        assert "0.5.3" in result.stdout
 
     def test_help(self):
         result = runner.invoke(app, ["--help"])