agentrepocoach 0.2.0__py3-none-any.whl

agentrepocoach/adapters/go.py

@@ -0,0 +1,283 @@
+"""Go language adapter.
+
+Detects Go repos via ``go.mod`` presence. Walks the repo for production
+``.go`` files (excluding ``_test.go``), scans ``return fmt.Errorf(`` /
+``errors.New(`` / custom error returns, and detects Go doc comments above
+exported declarations.
+
+Go's error model differs from throw-based languages: errors are returned
+values, not thrown exceptions. This adapter maps Go error-creation sites
+(``fmt.Errorf``, ``errors.New``, ``&CustomError{}``) to the ``ThrowSite``
+model. The "exception type" is the error constructor or custom type name.
+
+All analysis is regex-based — no AST parsing, stdlib only.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable
+
+from .base import (
+    Declaration,
+    LanguageAdapter,
+    ThrowSite,
+    count_file_loc,
+    iter_source_files,
+    read_text_safely,
+)
+
+_GO_SUFFIX: tuple[str, ...] = (".go",)
+_GO_TEST_SUFFIX: tuple[str, ...] = ("_test.go",)
+
+# Error-creation patterns (Go returns errors, doesn't throw them).
+_ERRORS_NEW_PATTERN = re.compile(r"\berrors\.New\s*\(")
+_FMT_ERRORF_PATTERN = re.compile(r"\bfmt\.Errorf\s*\(")
+_CUSTOM_ERROR_PATTERN = re.compile(r"&([A-Z][A-Za-z0-9_]*Error)\s*\{")
+
+# Declaration patterns — Go uses capitalization for visibility.
+_FUNC_PATTERN = re.compile(r"^func\s+(?:\([^)]+\)\s+)?([A-Za-z_]\w*)\s*\(")
+_TYPE_PATTERN = re.compile(r"^type\s+([A-Za-z_]\w*)\s+(?:struct|interface|int|string)")
+_CONST_VAR_PATTERN = re.compile(r"^(?:var|const)\s+([A-Za-z_]\w*)\s")
+
+# Test function pattern.
+_TEST_FUNC_PATTERN = re.compile(r"^func\s+(Test[A-Z]\w*)\s*\(")
+# Go convention: TestFoo_Bar_Baz or TestFooBar.
+_TEST_NAMING_PATTERN = re.compile(r"^Test[A-Z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+$")
+
+# Generic error constructors (too generic for good agent UX).
+_GENERIC_ERROR_NAMES: frozenset[str] = frozenset({
+    "errors.New",
+    "fmt.Errorf",
+})
+
+_FIX_HINT_KEYWORDS: tuple[str, ...] = (
+    "hint:", "fix:", "see ", "try ", "use ", "check ", "did you mean",
+    "suggested fix", "to fix", "to resolve", "example:", "ensure",
+    "install", "provide", "verify", "configure", "expected",
+)
+
+_TEST_DIR_CANDIDATES: tuple[str, ...] = ("test", "tests", "internal/test")
+
+
+class GoAdapter(LanguageAdapter):
+    """Go adapter."""
+
+    name = "go"
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    def detect(self, repo_path: Path) -> float:
+        if (repo_path / "go.mod").is_file():
+            return 1.0
+        if any(repo_path.rglob("*.go")):
+            return 0.5
+        return 0.0
+
+    # ------------------------------------------------------------------
+    # File discovery
+    # ------------------------------------------------------------------
+
+    def find_production_files(self, repo_path: Path) -> list[Path]:
+        all_go = iter_source_files(repo_path, suffixes=_GO_SUFFIX)
+        return [f for f in all_go if not _is_test_file(f)]
+
+    def find_test_files(self, repo_path: Path) -> list[Path]:
+        all_go = iter_source_files(repo_path, suffixes=_GO_SUFFIX)
+        return [f for f in all_go if _is_test_file(f)]
+
+    def find_production_modules(self, repo_path: Path) -> list[str]:
+        """Return Go package directory names containing production .go files."""
+        modules: set[str] = set()
+        for f in self.find_production_files(repo_path):
+            # Use the parent directory name as the module/package name.
+            pkg = f.parent.name
+            if pkg and pkg != repo_path.name:
+                modules.add(pkg)
+        # If all files are at repo root, use the module name from go.mod.
+        if not modules:
+            mod_file = repo_path / "go.mod"
+            if mod_file.is_file():
+                text = read_text_safely(mod_file)
+                m = re.search(r"^module\s+(\S+)", text, re.MULTILINE)
+                if m:
+                    modules.add(m.group(1).rsplit("/", 1)[-1])
+        return sorted(modules)
+
+    # ------------------------------------------------------------------
+    # Throw-site analysis (Go: error-creation sites)
+    # ------------------------------------------------------------------
+
+    def scan_throw_sites(
+        self,
+        files: Iterable[Path],
+        hint_marker: str,
+        domain_exception_types: set[str],
+    ) -> list[ThrowSite]:
+        sites: list[ThrowSite] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+
+            # errors.New() sites
+            for match in _ERRORS_NEW_PATTERN.finditer(text):
+                context = _extract_context(text, match.start())
+                line_no = text.count("\n", 0, match.start()) + 1
+                sites.append(
+                    ThrowSite(
+                        file=path,
+                        line=line_no,
+                        exception_type="errors.New",
+                        has_fix_hint=_has_fix_hint(context, hint_marker),
+                        is_user_defined=False,
+                        is_generic=True,
+                    )
+                )
+
+            # fmt.Errorf() sites
+            for match in _FMT_ERRORF_PATTERN.finditer(text):
+                context = _extract_context(text, match.start())
+                line_no = text.count("\n", 0, match.start()) + 1
+                sites.append(
+                    ThrowSite(
+                        file=path,
+                        line=line_no,
+                        exception_type="fmt.Errorf",
+                        has_fix_hint=_has_fix_hint(context, hint_marker),
+                        is_user_defined=False,
+                        is_generic=True,
+                    )
+                )
+
+            # Custom error types: &CustomError{}
+            for match in _CUSTOM_ERROR_PATTERN.finditer(text):
+                error_type = match.group(1)
+                context = _extract_context(text, match.start())
+                line_no = text.count("\n", 0, match.start()) + 1
+                sites.append(
+                    ThrowSite(
+                        file=path,
+                        line=line_no,
+                        exception_type=error_type,
+                        has_fix_hint=_has_fix_hint(context, hint_marker),
+                        is_user_defined=error_type in domain_exception_types,
+                        is_generic=False,
+                    )
+                )
+        return sites
+
+    def generic_exception_names(self) -> set[str]:
+        return set(_GENERIC_ERROR_NAMES)
+
+    # ------------------------------------------------------------------
+    # Declarations
+    # ------------------------------------------------------------------
+
+    def scan_declarations(self, files: Iterable[Path]) -> list[Declaration]:
+        declarations: list[Declaration] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+            declarations.extend(self._scan_declarations_in_text(path, text))
+        return declarations
+
+    def _scan_declarations_in_text(self, path: Path, text: str) -> list[Declaration]:
+        lines = text.splitlines()
+        results: list[Declaration] = []
+        for i, line in enumerate(lines):
+            name = _match_declaration(line)
+            if name is None:
+                continue
+            # Go visibility: uppercase first letter = exported (public).
+            visibility = "public" if name[0].isupper() else "internal"
+            results.append(
+                Declaration(
+                    file=path,
+                    line=i + 1,
+                    name=name,
+                    visibility=visibility,
+                    has_doc_comment=_has_preceding_go_doc(lines, i),
+                )
+            )
+        return results
+
+    # ------------------------------------------------------------------
+    # Test methods
+    # ------------------------------------------------------------------
+
+    def find_test_methods(self, files: Iterable[Path]) -> list[tuple[Path, str]]:
+        results: list[tuple[Path, str]] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+            for line in text.splitlines():
+                m = _TEST_FUNC_PATTERN.match(line)
+                if m:
+                    results.append((path, m.group(1)))
+        return results
+
+    def test_naming_pattern(self) -> re.Pattern[str]:
+        return _TEST_NAMING_PATTERN
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_test_file(path: Path) -> bool:
+    return path.name.endswith("_test.go")
+
+
+def _extract_context(text: str, start: int, max_chars: int = 500) -> str:
+    """Extract text from start through the next closing paren or brace."""
+    end = min(start + max_chars, len(text))
+    depth = 0
+    for i in range(start, end):
+        ch = text[i]
+        if ch in ("(", "{"):
+            depth += 1
+        elif ch in (")", "}"):
+            depth -= 1
+            if depth == 0:
+                return text[start:i + 1]
+    return text[start:end]
+
+
+def _has_fix_hint(text: str, hint_marker: str) -> bool:
+    lower = text.lower()
+    if hint_marker and hint_marker.lower() in lower:
+        return True
+    for keyword in _FIX_HINT_KEYWORDS:
+        if keyword in lower:
+            return True
+    return False
+
+
+def _match_declaration(line: str) -> str | None:
+    """Return the declaration name if the line declares a func, type, or var/const."""
+    for pattern in (_FUNC_PATTERN, _TYPE_PATTERN, _CONST_VAR_PATTERN):
+        m = pattern.match(line)
+        if m:
+            return m.group(1)
+    return None
+
+
+def _has_preceding_go_doc(lines: list[str], index: int) -> bool:
+    """Return True if the line above is a Go doc comment (``//`` comment block)."""
+    j = index - 1
+    while j >= 0:
+        stripped = lines[j].strip()
+        if stripped == "":
+            j -= 1
+            continue
+        return stripped.startswith("//")
+    return False
+
+
+GoAdapter.count_file_loc = staticmethod(count_file_loc)  # type: ignore[attr-defined]

agentrepocoach/adapters/python.py

@@ -0,0 +1,244 @@
+"""Python language adapter.
+
+Detects Python repos via ``pyproject.toml`` / ``setup.py`` presence. Walks
+``src/`` or top-level packages for production files and ``tests/`` / ``test/``
+for test files. Scans ``raise`` statements, classifies exception types, and
+detects docstring presence above top-level declarations.
+
+Deliberately minimal: this adapter is new at launch and not research-backed
+to the same degree as the C# adapter. A "Python adapter validation" doc
+published post-launch will compare scores on 3 popular Python repos.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable
+
+from .base import (
+    Declaration,
+    LanguageAdapter,
+    ThrowSite,
+    count_file_loc,
+    iter_source_files,
+    read_text_safely,
+)
+
+_PYTHON_SUFFIX: tuple[str, ...] = (".py",)
+
+_RAISE_PATTERN = re.compile(r"\braise\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:\(|$)")
+
+_PUBLIC_DECL_PATTERN = re.compile(r"^(class|def)\s+([A-Za-z][A-Za-z0-9_]*)\s*[\(:]")
+_PRIVATE_DECL_PATTERN = re.compile(r"^(class|def)\s+(_[A-Za-z0-9_]*)\s*[\(:]")
+
+_TEST_METHOD_PATTERN = re.compile(r"^\s*def\s+(test_[A-Za-z0-9_]+)\s*\(", re.MULTILINE)
+_TEST_SNAKE_PATTERN = re.compile(r"^test_[a-z][a-z0-9_]*_[a-z0-9_]+_[a-z0-9_]+$")
+
+# Stdlib exception types considered "too generic" for good agent UX.
+_GENERIC_EXCEPTION_NAMES: frozenset[str] = frozenset({
+    "Exception",
+    "BaseException",
+    "RuntimeError",
+    "ValueError",
+    "TypeError",
+})
+
+_PROD_DIR_CANDIDATES: tuple[str, ...] = ("src", "lib")
+_TEST_DIR_CANDIDATES: tuple[str, ...] = ("tests", "test")
+
+
+class PythonAdapter(LanguageAdapter):
+    """Python adapter. MVP implementation."""
+
+    name = "python"
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    def detect(self, repo_path: Path) -> float:
+        if (repo_path / "pyproject.toml").is_file():
+            return 1.0
+        if (repo_path / "setup.py").is_file():
+            return 0.9
+        if any(repo_path.rglob("*.py")):
+            return 0.6
+        return 0.0
+
+    # ------------------------------------------------------------------
+    # File discovery
+    # ------------------------------------------------------------------
+
+    def find_production_files(self, repo_path: Path) -> list[Path]:
+        production_roots = self._production_roots(repo_path)
+        results: list[Path] = []
+        for root in production_roots:
+            results.extend(iter_source_files(root, suffixes=_PYTHON_SUFFIX))
+        return results
+
+    def find_test_files(self, repo_path: Path) -> list[Path]:
+        results: list[Path] = []
+        for name in _TEST_DIR_CANDIDATES:
+            candidate = repo_path / name
+            if candidate.is_dir():
+                results.extend(iter_source_files(candidate, suffixes=_PYTHON_SUFFIX))
+        return results
+
+    def find_production_modules(self, repo_path: Path) -> list[str]:
+        """Top-level package directories under src/ or the repo root."""
+        modules: set[str] = set()
+        for root in self._production_roots(repo_path):
+            for entry in root.iterdir():
+                if entry.is_dir() and (entry / "__init__.py").is_file():
+                    modules.add(entry.name)
+        return sorted(modules)
+
+    def _production_roots(self, repo_path: Path) -> list[Path]:
+        roots: list[Path] = []
+        for name in _PROD_DIR_CANDIDATES:
+            candidate = repo_path / name
+            if candidate.is_dir():
+                roots.append(candidate)
+        if not roots:
+            # Fall back: top-level packages in the repo root that are NOT tests.
+            for entry in repo_path.iterdir():
+                if not entry.is_dir():
+                    continue
+                if entry.name in _TEST_DIR_CANDIDATES:
+                    continue
+                if entry.name.startswith("."):
+                    continue
+                if (entry / "__init__.py").is_file():
+                    roots.append(entry)
+        return roots
+
+    # ------------------------------------------------------------------
+    # Throw-site analysis (Python: raise sites)
+    # ------------------------------------------------------------------
+
+    def scan_throw_sites(
+        self,
+        files: Iterable[Path],
+        hint_marker: str,
+        domain_exception_types: set[str],
+    ) -> list[ThrowSite]:
+        sites: list[ThrowSite] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+            for match in _RAISE_PATTERN.finditer(text):
+                exception_type = match.group(1)
+                line_no = text.count("\n", 0, match.start()) + 1
+                # Lightweight message extraction: take the rest of the line.
+                line_start = text.rfind("\n", 0, match.start()) + 1
+                line_end = text.find("\n", match.start())
+                if line_end == -1:
+                    line_end = len(text)
+                line_text = text[line_start:line_end]
+                sites.append(
+                    ThrowSite(
+                        file=path,
+                        line=line_no,
+                        exception_type=exception_type,
+                        has_fix_hint=_has_fix_hint(line_text, hint_marker),
+                        is_user_defined=exception_type in domain_exception_types,
+                        is_generic=exception_type in _GENERIC_EXCEPTION_NAMES,
+                    )
+                )
+        return sites
+
+    def generic_exception_names(self) -> set[str]:
+        return set(_GENERIC_EXCEPTION_NAMES)
+
+    # ------------------------------------------------------------------
+    # Declarations
+    # ------------------------------------------------------------------
+
+    def scan_declarations(self, files: Iterable[Path]) -> list[Declaration]:
+        declarations: list[Declaration] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+            declarations.extend(self._scan_declarations_in_text(path, text))
+        return declarations
+
+    def _scan_declarations_in_text(self, path: Path, text: str) -> list[Declaration]:
+        lines = text.splitlines()
+        results: list[Declaration] = []
+        for i, line in enumerate(lines):
+            if line.startswith(" ") or line.startswith("\t"):
+                # Only top-level declarations.
+                continue
+            public_match = _PUBLIC_DECL_PATTERN.match(line)
+            if public_match and not public_match.group(2).startswith("_"):
+                results.append(
+                    Declaration(
+                        file=path,
+                        line=i + 1,
+                        name=public_match.group(2),
+                        visibility="public",
+                        has_doc_comment=_has_following_docstring(lines, i),
+                    )
+                )
+                continue
+            private_match = _PRIVATE_DECL_PATTERN.match(line)
+            if private_match:
+                results.append(
+                    Declaration(
+                        file=path,
+                        line=i + 1,
+                        name=private_match.group(2),
+                        visibility="private",
+                        has_doc_comment=_has_following_docstring(lines, i),
+                    )
+                )
+        return results
+
+    # ------------------------------------------------------------------
+    # Test methods
+    # ------------------------------------------------------------------
+
+    def find_test_methods(self, files: Iterable[Path]) -> list[tuple[Path, str]]:
+        results: list[tuple[Path, str]] = []
+        for path in files:
+            text = read_text_safely(path)
+            if not text:
+                continue
+            for match in _TEST_METHOD_PATTERN.finditer(text):
+                results.append((path, match.group(1)))
+        return results
+
+    def test_naming_pattern(self) -> re.Pattern[str]:
+        return _TEST_SNAKE_PATTERN
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _has_fix_hint(text: str, hint_marker: str) -> bool:
+    lower = text.lower()
+    if hint_marker and hint_marker.lower() in lower:
+        return True
+    for phrase in ("hint:", "fix:", "see ", "try ", "use ", "check ", "did you mean"):
+        if phrase in lower:
+            return True
+    return False
+
+
+def _has_following_docstring(lines: list[str], index: int) -> bool:
+    """Return True if the next non-blank line after ``index`` starts a docstring."""
+    j = index + 1
+    while j < len(lines):
+        stripped = lines[j].strip()
+        if stripped == "":
+            j += 1
+            continue
+        return stripped.startswith('"""') or stripped.startswith("'''")
+    return False
+
+
+PythonAdapter.count_file_loc = staticmethod(count_file_loc)  # type: ignore[attr-defined]