feat: React pattern detection -- useQuery, cn(), custom hooks, canonical hook, shared types

Author: DevanshuNEU

CLAUDE.md

@@ -1,7 +1,7 @@
 <!-- SAAR:AUTO-START -->
 # CLAUDE.md -- saar
 
-282 functions, 47 classes.
+289 functions, 48 classes.
 Async adoption: 20%.
 Type hint coverage: 92%.
 

saar/extractor.py

@@ -838,8 +838,101 @@ def _has_lockfile(name: str) -> bool:
         elif "sass" in combined or "node-sass" in combined:
             fp.styling = "Sass/SCSS"
 
+        # -- React coding patterns from actual source files --
+        # scan .tsx/.ts/.jsx files to detect HOW the stack is being used,
+        # not just WHAT is installed
+        if fp.framework in ("React", "Next.js"):
+            self._detect_react_patterns(fp, repo_path)
+
         return fp
 
+    def _detect_react_patterns(self, fp, repo_path: Path) -> None:
+        """Scan React/TS source files to detect coding patterns.
+
+        This goes beyond package.json -- we look at actual usage in source
+        files to generate rules like "use useQuery, never raw fetch in useEffect"
+        rather than generic advice.
+        """
+        tsx_files = [
+            p for p in repo_path.rglob("*.tsx")
+            if not self._should_skip(p, repo_path)
+            and "node_modules" not in p.parts
+        ]
+        ts_files = [
+            p for p in repo_path.rglob("*.ts")
+            if not self._should_skip(p, repo_path)
+            and "node_modules" not in p.parts
+            and not p.name.endswith(".d.ts")
+        ]
+        all_fe_files = tsx_files + ts_files
+
+        if not all_fe_files:
+            return
+
+        use_query_count = 0
+        fetch_in_effect_count = 0
+        cn_usage_count = 0
+        hook_files = []
+        custom_hook_imports: dict = {}
+
+        for file_path in all_fe_files[:150]:  # cap for performance
+            content = self._safe_read_file(file_path)
+            if not content:
+                continue
+
+            # useQuery / useMutation from tanstack -- means they use React Query
+            if re.search(r"\buseQuery\b|\buseMutation\b|\buseInfiniteQuery\b", content):
+                use_query_count += 1
+
+            # raw fetch inside useEffect -- anti-pattern in React Query codebases
+            if re.search(r"useEffect\s*\(", content) and re.search(r"\bfetch\s*\(", content):
+                fetch_in_effect_count += 1
+
+            # cn() utility for conditional class merging
+            if re.search(r"\bcn\s*\(", content):
+                cn_usage_count += 1
+
+            # custom hooks in hooks/ directory
+            if "hooks" in file_path.parts and file_path.name.startswith("use"):
+                hook_files.append(file_path.stem)
+
+            # track which custom hooks are imported across components
+            for match in re.finditer(r"import\s+\{([^}]+)\}\s+from\s+['\"].*?hooks/([^'\"]+)['\"]", content):
+                imports = [i.strip() for i in match.group(1).split(",")]
+                for imp in imports:
+                    if imp.startswith("use"):
+                        custom_hook_imports[imp] = custom_hook_imports.get(imp, 0) + 1
+
+        # set flags based on counts
+        if use_query_count >= 2:
+            fp.uses_react_query = True
+
+        # only flag fetch-in-effect as an anti-pattern if they also use React Query
+        # -- otherwise it might be intentional
+        if fetch_in_effect_count == 0 and use_query_count >= 2:
+            fp.avoids_fetch_in_effect = True
+
+        if cn_usage_count >= 3:
+            fp.uses_cn_utility = True
+
+        if hook_files:
+            fp.has_custom_hooks = True
+            # find the most-imported custom hook -- canonical example
+            if custom_hook_imports:
+                fp.canonical_data_hook = max(custom_hook_imports, key=custom_hook_imports.get)
+
+        # check for shared types file
+        for candidate in ["src/types.ts", "src/types/index.ts", "types.ts", "src/types/index.tsx"]:
+            if (repo_path / candidate).exists():
+                fp.shared_types_file = candidate
+                break
+        # also check frontend/ subdirectory for monorepos
+        if not fp.shared_types_file:
+            for candidate in ["frontend/src/types.ts", "frontend/src/types/index.ts"]:
+                if (repo_path / candidate).exists():
+                    fp.shared_types_file = candidate
+                    break
+
     def _extract_config_patterns(self, files: List[Path], repo_path: Path) -> ConfigPattern:
         pattern = ConfigPattern()
 

saar/formatters/agents_md.py

@@ -115,6 +115,18 @@ def render_agents_md(dna: CodebaseDNA) -> str:
                 test_line += f" (`{fp.test_command}`)"
             lines.append(test_line)
 
+        # React-specific coding patterns detected from source files
+        if fp.uses_react_query:
+            lines.append("- Data fetching: use `useQuery`/`useMutation` -- never raw `fetch` in `useEffect`")
+        if fp.uses_cn_utility:
+            lines.append("- Class merging: use `cn()` from `@/lib/utils` for conditional Tailwind classes")
+        if fp.has_custom_hooks and fp.canonical_data_hook:
+            lines.append(f"- Custom hooks in `hooks/` -- canonical example: `{fp.canonical_data_hook}`")
+        elif fp.has_custom_hooks:
+            lines.append("- Custom hooks live in `hooks/` with `use` prefix")
+        if fp.shared_types_file:
+            lines.append(f"- Shared TypeScript interfaces in `{fp.shared_types_file}` -- don't duplicate types inline")
+
     # -- coding conventions --
     lines.append("## Coding Conventions\n")
     nc = dna.naming_conventions

saar/formatters/claude_md.py

@@ -53,6 +53,18 @@ def render_claude_md(dna: CodebaseDNA) -> str:
                 test_line += f" (`{fp.test_command}`)"
             lines.append(test_line)
 
+        # React-specific coding patterns detected from source files
+        if fp.uses_react_query:
+            lines.append("- Data fetching: use `useQuery`/`useMutation` -- never raw `fetch` in `useEffect`")
+        if fp.uses_cn_utility:
+            lines.append("- Class merging: use `cn()` from `@/lib/utils` for conditional Tailwind classes")
+        if fp.has_custom_hooks and fp.canonical_data_hook:
+            lines.append(f"- Custom hooks in `hooks/` -- canonical example: `{fp.canonical_data_hook}`")
+        elif fp.has_custom_hooks:
+            lines.append("- Custom hooks live in `hooks/` with `use` prefix")
+        if fp.shared_types_file:
+            lines.append(f"- Shared TypeScript interfaces in `{fp.shared_types_file}` -- don't duplicate inline")
+
     # -- coding conventions as imperative rules --
     lines.append("## Coding Conventions\n")
     nc = dna.naming_conventions

saar/models.py

@@ -107,6 +107,13 @@ class FrontendPattern:
     package_manager: Optional[str] = None   # bun, pnpm, yarn, npm
     build_tool: Optional[str] = None        # vite, webpack, turbopack
     language: Optional[str] = None          # typescript, javascript
+    # React-specific coding patterns (detected from .tsx/.ts source files)
+    uses_react_query: bool = False           # useQuery/useMutation detected in source
+    avoids_fetch_in_effect: bool = False     # no raw fetch inside useEffect
+    uses_cn_utility: bool = False            # cn() from @/lib/utils for class merging
+    canonical_data_hook: Optional[str] = None  # most-used custom data hook
+    has_custom_hooks: bool = False           # hooks/ directory with use* files
+    shared_types_file: Optional[str] = None # types.ts / types/ directory found
 
 
 @dataclass

tests/test_frontend_detector.py

@@ -287,3 +287,100 @@ def test_no_frontend_section_for_pure_python(self):
         dna = CodebaseDNA(repo_name="python-only")
         out = render_agents_md(dna)
         assert "## Frontend" not in out
+
+
+class TestReactPatternDetection:
+
+    def test_detects_react_query_usage(self, tmp_path: Path):
+        _write_pkg(tmp_path, {"react": "^18", "@tanstack/react-query": "^5"})
+        # need 2+ files with useQuery to pass the threshold
+        (tmp_path / "useUser.tsx").write_text(
+            "import { useQuery } from '@tanstack/react-query';\n"
+            "export const useUser = (id) => useQuery({ queryKey: ['user', id] });\n"
+        )
+        (tmp_path / "useRepos.tsx").write_text(
+            "import { useQuery } from '@tanstack/react-query';\n"
+            "export const useRepos = () => useQuery({ queryKey: ['repos'] });\n"
+        )
+        extractor = DNAExtractor()
+        dna = extractor.extract(str(tmp_path))
+        assert dna.frontend_patterns.uses_react_query is True
+
+    def test_detects_cn_utility(self, tmp_path: Path):
+        _write_pkg(tmp_path, {"react": "^18"})
+        (tmp_path / "Button.tsx").write_text(
+            "import { cn } from '@/lib/utils';\n"
+            "export const Button = ({ className }) => (\n"
+            "  <button className={cn('btn', className)}>click</button>\n"
+            ");\n"
+        )
+        (tmp_path / "Card.tsx").write_text(
+            "import { cn } from '@/lib/utils';\n"
+            "export const Card = ({ cls }) => <div className={cn('card', cls)} />;\n"
+        )
+        (tmp_path / "Input.tsx").write_text(
+            "import { cn } from '@/lib/utils';\n"
+            "export const Input = ({ cls }) => <input className={cn('input', cls)} />;\n"
+        )
+        extractor = DNAExtractor()
+        dna = extractor.extract(str(tmp_path))
+        assert dna.frontend_patterns.uses_cn_utility is True
+
+    def test_detects_custom_hooks(self, tmp_path: Path):
+        _write_pkg(tmp_path, {"react": "^18"})
+        hooks_dir = tmp_path / "hooks"
+        hooks_dir.mkdir()
+        (hooks_dir / "useAuth.ts").write_text("export const useAuth = () => ({});")
+        (hooks_dir / "useRepos.ts").write_text("export const useRepos = () => ({});")
+        (tmp_path / "app.tsx").write_text("const x = 1;")
+        extractor = DNAExtractor()
+        dna = extractor.extract(str(tmp_path))
+        assert dna.frontend_patterns.has_custom_hooks is True
+
+    def test_detects_canonical_hook(self, tmp_path: Path):
+        _write_pkg(tmp_path, {"react": "^18", "@tanstack/react-query": "^5"})
+        hooks_dir = tmp_path / "hooks"
+        hooks_dir.mkdir()
+        (hooks_dir / "useCachedQuery.ts").write_text("export const useCachedQuery = () => ({});")
+        # import useCachedQuery in 3 different components
+        for i in range(3):
+            (tmp_path / f"Component{i}.tsx").write_text(
+                "import { useCachedQuery } from '../hooks/useCachedQuery';\n"
+                "export const C = () => { const d = useCachedQuery(); return null; };\n"
+            )
+        extractor = DNAExtractor()
+        dna = extractor.extract(str(tmp_path))
+        assert dna.frontend_patterns.has_custom_hooks is True
+        assert dna.frontend_patterns.canonical_data_hook == "useCachedQuery"
+
+    def test_detects_shared_types_file(self, tmp_path: Path):
+        _write_pkg(tmp_path, {"react": "^18"})
+        src = tmp_path / "src"
+        src.mkdir()
+        (src / "types.ts").write_text("export interface User { id: string; }")
+        (tmp_path / "app.tsx").write_text("const x = 1;")
+        extractor = DNAExtractor()
+        dna = extractor.extract(str(tmp_path))
+        assert dna.frontend_patterns.shared_types_file == "src/types.ts"
+
+    def test_react_patterns_rendered_in_agents_md(self, tmp_path: Path):
+        from saar.formatters.agents_md import render_agents_md
+        from saar.models import CodebaseDNA, FrontendPattern
+
+        dna = CodebaseDNA(
+            repo_name="test",
+            frontend_patterns=FrontendPattern(
+                framework="React",
+                uses_react_query=True,
+                uses_cn_utility=True,
+                has_custom_hooks=True,
+                canonical_data_hook="useCachedQuery",
+                shared_types_file="src/types.ts",
+            )
+        )
+        out = render_agents_md(dna)
+        assert "useQuery" in out
+        assert "useEffect" in out
+        assert "cn()" in out
+        assert "useCachedQuery" in out
+        assert "src/types.ts" in out