feat: frontend stack detection -- framework, test runner, component lib, state, styling (OPE-141 partial)

Author: DevanshuNEU

CLAUDE.md

@@ -1,8 +1,8 @@
 <!-- SAAR:AUTO-START -->
 # CLAUDE.md -- saar
 
-253 functions, 38 classes.
-Async adoption: 21%.
+281 functions, 47 classes.
+Async adoption: 20%.
 Type hint coverage: 92%.
 
 ## Coding Conventions
@@ -34,14 +34,14 @@ import os
 
 These files have the most dependents -- understand them before editing:
 
-- `saar/models.py` (14 dependents)
-- `saar/formatters/agents_md.py` (4 dependents)
+- `saar/models.py` (15 dependents)
+- `saar/formatters/agents_md.py` (5 dependents)
 - `saar/formatters/_tribal.py` (4 dependents)
+- `saar/extractor.py` (3 dependents)
+- `saar/interview.py` (3 dependents)
 - `saar/cli.py` (3 dependents)
 - `saar/formatters/claude_md.py` (3 dependents)
-- `saar/interview.py` (3 dependents)
 - `saar/dependency_analyzer.py` (2 dependents)
-- `saar/style_analyzer.py` (2 dependents)
 
 ## Error Handling
 

saar/extractor.py

@@ -692,6 +692,154 @@ def _extract_test_patterns(
 
         return pattern
 
+    def _extract_frontend_patterns(self, repo_path: Path) -> Optional["FrontendPattern"]:
+        """Detect frontend stack by reading package.json files.
+
+        Reads all package.json files found (handles monorepos with multiple
+        frontend packages). Returns None if no package.json found -- meaning
+        this is a pure backend/Python repo.
+        """
+        from saar.models import FrontendPattern
+        import json
+
+        pkg_files = [
+            p for p in repo_path.rglob("package.json")
+            if not self._should_skip(p, repo_path)
+            and "node_modules" not in p.parts
+        ]
+        if not pkg_files:
+            return None
+
+        # merge deps across all package.json files (monorepo support)
+        all_deps: dict = {}
+        all_dev_deps: dict = {}
+        all_scripts: dict = {}
+        for pkg_file in pkg_files:
+            try:
+                data = json.loads(pkg_file.read_text(encoding="utf-8"))
+                all_deps.update(data.get("dependencies", {}))
+                all_dev_deps.update(data.get("devDependencies", {}))
+                all_scripts.update(data.get("scripts", {}))
+            except Exception:
+                continue
+
+        combined = {**all_deps, **all_dev_deps}
+        if not combined:
+            return None
+
+        fp = FrontendPattern()
+
+        # -- package manager (check repo root AND subdirs for lockfiles) --
+        def _has_lockfile(name: str) -> bool:
+            # check root first, then any immediate subdirectory
+            if (repo_path / name).exists():
+                return True
+            return any(
+                (p / name).exists()
+                for p in repo_path.iterdir()
+                if p.is_dir() and not self._should_skip(p, repo_path)
+            )
+
+        if _has_lockfile("bun.lock") or _has_lockfile("bun.lockb"):
+            fp.package_manager = "bun"
+        elif _has_lockfile("pnpm-lock.yaml"):
+            fp.package_manager = "pnpm"
+        elif _has_lockfile("yarn.lock"):
+            fp.package_manager = "yarn"
+        else:
+            fp.package_manager = "npm"
+
+        # -- JS/TS language --
+        if "typescript" in combined or any(k.startswith("@types/") for k in combined):
+            fp.language = "TypeScript"
+        else:
+            fp.language = "JavaScript"
+
+        # -- UI framework (order matters -- Next before React) --
+        if "next" in combined:
+            fp.framework = "Next.js"
+        elif "nuxt" in combined or "nuxt3" in combined:
+            fp.framework = "Nuxt"
+        elif "@sveltejs/kit" in combined or "svelte" in combined:
+            fp.framework = "SvelteKit" if "@sveltejs/kit" in combined else "Svelte"
+        elif "astro" in combined:
+            fp.framework = "Astro"
+        elif "@angular/core" in combined:
+            fp.framework = "Angular"
+        elif "react" in combined or "react-dom" in combined:
+            fp.framework = "React"
+        elif "vue" in combined:
+            fp.framework = "Vue"
+
+        # -- build tool --
+        if "vite" in combined or "@vitejs/plugin-react" in combined:
+            fp.build_tool = "Vite"
+        elif "turbopack" in combined or ("next" in combined and "webpack" not in combined):
+            fp.build_tool = "Turbopack"
+        elif "webpack" in combined:
+            fp.build_tool = "webpack"
+
+        # -- test framework --
+        if "vitest" in combined:
+            fp.test_framework = "Vitest"
+            # find the test run command
+            test_cmd = all_scripts.get("test", "")
+            if "vitest" in test_cmd:
+                pm = fp.package_manager or "npm"
+                run = "run" if pm in ("bun", "npm", "yarn", "pnpm") else ""
+                fp.test_command = f"{pm} {run} test".strip()
+        elif "jest" in combined or "@jest/core" in combined:
+            fp.test_framework = "Jest"
+            fp.test_command = "jest"
+        elif "@playwright/test" in combined:
+            fp.test_framework = "Playwright"
+        elif "cypress" in combined:
+            fp.test_framework = "Cypress"
+        elif "mocha" in combined:
+            fp.test_framework = "Mocha"
+
+        # -- component library --
+        # shadcn/ui uses @radix-ui/* -- check for 3+ radix packages as signal
+        radix_count = sum(1 for k in combined if k.startswith("@radix-ui/"))
+        if radix_count >= 3:
+            fp.component_library = "shadcn/ui"
+        elif "@mui/material" in combined or "@material-ui/core" in combined:
+            fp.component_library = "Material UI"
+        elif "@chakra-ui/react" in combined:
+            fp.component_library = "Chakra UI"
+        elif "antd" in combined:
+            fp.component_library = "Ant Design"
+        elif "react-bootstrap" in combined:
+            fp.component_library = "React Bootstrap"
+        elif "@mantine/core" in combined:
+            fp.component_library = "Mantine"
+
+        # -- state management --
+        if "@tanstack/react-query" in combined or "react-query" in combined:
+            fp.state_management = "TanStack Query"
+        elif "zustand" in combined:
+            fp.state_management = "Zustand"
+        elif "@reduxjs/toolkit" in combined or "redux" in combined:
+            fp.state_management = "Redux Toolkit" if "@reduxjs/toolkit" in combined else "Redux"
+        elif "jotai" in combined:
+            fp.state_management = "Jotai"
+        elif "valtio" in combined:
+            fp.state_management = "Valtio"
+        elif "recoil" in combined:
+            fp.state_management = "Recoil"
+
+        # -- styling --
+        if "tailwindcss" in combined:
+            fp.styling = "Tailwind CSS"
+        elif "styled-components" in combined:
+            fp.styling = "styled-components"
+        elif "@emotion/react" in combined or "@emotion/styled" in combined:
+            fp.styling = "Emotion"
+        elif "sass" in combined or "node-sass" in combined:
+            fp.styling = "Sass/SCSS"
+
+        return fp
+
     def _extract_config_patterns(self, files: List[Path], repo_path: Path) -> ConfigPattern:
         pattern = ConfigPattern()
 
@@ -802,6 +950,7 @@ def extract(
             router_pattern=router_pattern,
             team_rules=team_rules,
             team_rules_source=team_rules_source,
+            frontend_patterns=self._extract_frontend_patterns(path),
         )
 
         # Enrich with style analysis (AST-based, more precise than regex)

saar/formatters/agents_md.py

@@ -87,6 +87,34 @@ def render_agents_md(dna: CodebaseDNA) -> str:
         )
         lines.append(f"**Languages:** {lang_str}\n")
 
+    # -- frontend stack --
+    fp = dna.frontend_patterns
+    if fp:
+        lines.append("\n## Frontend\n")
+        stack_parts = []
+        if fp.framework:
+            stack_parts.append(fp.framework)
+        if fp.language:
+            stack_parts.append(fp.language)
+        if fp.build_tool:
+            stack_parts.append(fp.build_tool)
+        if stack_parts:
+            lines.append(f"**Stack:** {' + '.join(stack_parts)}")
+        if fp.package_manager:
+            pm = fp.package_manager
+            lines.append(f"- Package manager: `{pm}` -- always use `{pm} install`, never npm/yarn")
+        if fp.component_library:
+            lines.append(f"- Component library: {fp.component_library} -- use over custom components")
+        if fp.state_management:
+            lines.append(f"- State management: {fp.state_management}")
+        if fp.styling:
+            lines.append(f"- Styling: {fp.styling} -- no raw CSS files")
+        if fp.test_framework:
+            test_line = f"- Frontend tests: {fp.test_framework}"
+            if fp.test_command:
+                test_line += f" (`{fp.test_command}`)"
+            lines.append(test_line)
+
     # -- coding conventions --
     lines.append("## Coding Conventions\n")
     nc = dna.naming_conventions

saar/formatters/claude_md.py

@@ -25,6 +25,34 @@ def render_claude_md(dna: CodebaseDNA) -> str:
             lines.append(f"Type hint coverage: {dna.type_hint_pct:.0f}%.")
         lines.append("")
 
+    # -- frontend stack --
+    fp = dna.frontend_patterns
+    if fp:
+        lines.append("\n## Frontend\n")
+        stack_parts = []
+        if fp.framework:
+            stack_parts.append(fp.framework)
+        if fp.language:
+            stack_parts.append(fp.language)
+        if fp.build_tool:
+            stack_parts.append(fp.build_tool)
+        if stack_parts:
+            lines.append(f"**Stack:** {' + '.join(stack_parts)}")
+        if fp.package_manager:
+            pm = fp.package_manager
+            lines.append(f"- Package manager: `{pm}` -- always use `{pm} install`, never npm/yarn")
+        if fp.component_library:
+            lines.append(f"- Component library: {fp.component_library} -- use over custom components")
+        if fp.state_management:
+            lines.append(f"- State management: {fp.state_management}")
+        if fp.styling:
+            lines.append(f"- Styling: {fp.styling} -- no raw CSS files")
+        if fp.test_framework:
+            test_line = f"- Frontend tests: {fp.test_framework}"
+            if fp.test_command:
+                test_line += f" (`{fp.test_command}`)"
+            lines.append(test_line)
+
     # -- coding conventions as imperative rules --
     lines.append("## Coding Conventions\n")
     nc = dna.naming_conventions

saar/models.py

@@ -95,6 +95,20 @@ class TestPattern:
     coverage_config: bool = False
 
 
+@dataclass
+class FrontendPattern:
+    """Detected frontend stack patterns from package.json analysis."""
+    framework: Optional[str] = None          # next, react, vue, nuxt, svelte, astro
+    test_framework: Optional[str] = None     # vitest, jest, playwright, cypress
+    test_command: Optional[str] = None       # e.g. "bun run test", "npx vitest"
+    component_library: Optional[str] = None  # shadcn/ui, mui, chakra, antd
+    state_management: Optional[str] = None   # tanstack-query, zustand, redux
+    styling: Optional[str] = None           # tailwind, styled-components, emotion
+    package_manager: Optional[str] = None   # bun, pnpm, yarn, npm
+    build_tool: Optional[str] = None        # vite, webpack, turbopack
+    language: Optional[str] = None          # typescript, javascript
+
+
 @dataclass
 class ConfigPattern:
     """Detected configuration patterns."""
@@ -117,6 +131,7 @@ class CodebaseDNA:
     logging_patterns: LoggingPattern = field(default_factory=LoggingPattern)
     naming_conventions: NamingConventions = field(default_factory=NamingConventions)
     test_patterns: TestPattern = field(default_factory=TestPattern)
+    frontend_patterns: Optional[FrontendPattern] = None
     config_patterns: ConfigPattern = field(default_factory=ConfigPattern)
     middleware_patterns: List[str] = field(default_factory=list)
     common_imports: List[str] = field(default_factory=list)