ref-agents 1.0.0__py3-none-any.whl

ref_agents/core/language_detector.py

@@ -0,0 +1,388 @@
+"""Language Detection for REF Agents.
+
+Detects programming language and framework from file extensions and content.
+Used to load appropriate configuration for debt scanning and pattern detection.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+import json
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class LanguageInfo:
+    """Information about detected language and framework.
+
+    Attributes:
+        language: Primary language (python, typescript, javascript, java).
+        framework: Detected framework (react, angular, spring_boot) or None.
+        extensions: File extensions for this language.
+        confidence: Detection confidence (0.0-1.0).
+    """
+
+    language: str
+    framework: str | None = None
+    extensions: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        if self.framework:
+            return f"{self.language}/{self.framework}"
+        return self.language
+
+
+# Language definitions
+LANGUAGE_EXTENSIONS: dict[str, list[str]] = {
+    "python": [".py", ".pyw", ".pyi"],
+    "typescript": [".ts", ".tsx", ".mts", ".cts"],
+    "javascript": [".js", ".jsx", ".mjs", ".cjs"],
+    "java": [".java"],
+    "csharp": [".cs", ".csx"],
+}
+
+# Framework detection patterns (file content or project structure)
+FRAMEWORK_PATTERNS: dict[str, dict[str, Any]] = {
+    "react": {
+        "languages": ["typescript", "javascript"],
+        "imports": [
+            r"from\s+['\"]react['\"]",
+            r"import\s+.*\s+from\s+['\"]react['\"]",
+            r"require\(['\"]react['\"]\)",
+        ],
+        "files": ["package.json"],
+        "package_deps": ["react", "react-dom"],
+    },
+    "angular": {
+        "languages": ["typescript"],
+        "imports": [
+            r"from\s+['\"]@angular/",
+            r"import\s+.*\s+from\s+['\"]@angular/",
+        ],
+        "files": ["angular.json", "package.json"],
+        "package_deps": ["@angular/core"],
+        "decorators": ["@Component", "@NgModule", "@Injectable"],
+    },
+    "spring_boot": {
+        "languages": ["java"],
+        "imports": [
+            r"import\s+org\.springframework\.",
+            r"import\s+org\.springframework\.boot\.",
+        ],
+        "files": ["pom.xml", "build.gradle"],
+        "annotations": [
+            "@SpringBootApplication",
+            "@RestController",
+            "@Service",
+            "@Repository",
+        ],
+    },
+    "aspnet": {
+        "languages": ["csharp"],
+        # .csproj substring signals (rglob-based, not root-only)
+        "csproj_contains": [
+            "Microsoft.AspNetCore",
+            'Sdk="Microsoft.NET.Sdk.Web"',
+        ],
+        "imports": [
+            r"using\s+Microsoft\.AspNetCore\.",
+            r"using\s+Microsoft\.Extensions\.",
+        ],
+        "annotations": ["[ApiController]", "[HttpGet", "[HttpPost", "[Authorize]"],
+    },
+    "ef_core": {
+        "languages": ["csharp"],
+        "csproj_contains": ["Microsoft.EntityFrameworkCore"],
+        "imports": [r"using\s+Microsoft\.EntityFrameworkCore"],
+    },
+}
+
+
+class LanguageDetector:
+    """Detects programming language and framework from files.
+
+    Attributes:
+        project_root: Root directory of the project.
+        _framework_cache: Cached framework detection results.
+    """
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        """Initialize language detector.
+
+        Args:
+            project_root: Project root for framework detection. Defaults to cwd.
+        """
+        self.project_root = project_root or Path.cwd()
+        self._framework_cache: dict[str, str | None] = {}
+
+    def detect_from_extension(self, file_path: Path | str) -> str | None:
+        """Detect language from file extension.
+
+        Args:
+            file_path: Path to file.
+
+        Returns:
+            Language name or None if unknown.
+        """
+        path = Path(file_path)
+        ext = path.suffix.lower()
+
+        for language, extensions in LANGUAGE_EXTENSIONS.items():
+            if ext in extensions:
+                return language
+
+        return None
+
+    def detect_framework_from_content(
+        self,
+        content: str,
+        language: str,
+    ) -> str | None:
+        """Detect framework from file content.
+
+        Args:
+            content: File content.
+            language: Detected language.
+
+        Returns:
+            Framework name or None.
+        """
+        for framework, patterns in FRAMEWORK_PATTERNS.items():
+            if language not in patterns.get("languages", []):
+                continue
+
+            # Check import patterns
+            for pattern in patterns.get("imports", []):
+                if re.search(pattern, content):
+                    logger.debug(
+                        "framework_detected_from_import",
+                        framework=framework,
+                        pattern=pattern,
+                    )
+                    return framework
+
+            # Check decorators/annotations
+            for decorator in patterns.get("decorators", []) + patterns.get(
+                "annotations", []
+            ):
+                if decorator in content:
+                    logger.debug(
+                        "framework_detected_from_decorator",
+                        framework=framework,
+                        decorator=decorator,
+                    )
+                    return framework
+
+        return None
+
+    def _check_package_json_deps(
+        self, file_path: Path, deps_to_check: list[str]
+    ) -> bool:
+        """Check if package.json contains specific dependencies."""
+        try:
+            pkg = json.loads(file_path.read_text())
+            deps = {
+                **pkg.get("dependencies", {}),
+                **pkg.get("devDependencies", {}),
+            }
+            for dep in deps_to_check:
+                if dep in deps:
+                    return True
+        except (json.JSONDecodeError, OSError):
+            pass
+        return False
+
+    def _check_csproj_framework(self, substrings: list[str]) -> bool:
+        """Check if any .csproj under project root contains all given substrings.
+
+        Args:
+            substrings: Strings that must appear in at least one .csproj file.
+
+        Returns:
+            True if any .csproj contains at least one of the substrings.
+        """
+        for csproj in self.project_root.rglob("*.csproj"):
+            try:
+                content = csproj.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            if any(sub in content for sub in substrings):
+                logger.debug(
+                    "framework_detected_from_csproj",
+                    file=str(csproj),
+                )
+                return True
+        return False
+
+    def _check_framework_match(self, framework: str, patterns: dict[str, Any]) -> bool:
+        """Check if project matches framework patterns."""
+        # .NET frameworks: use rglob on .csproj (files are in subdirectories)
+        csproj_signals: list[str] = patterns.get("csproj_contains", [])
+        if csproj_signals and self._check_csproj_framework(csproj_signals):
+            return True
+
+        for filename in patterns.get("files", []):
+            file_path = self.project_root / filename
+            if not file_path.exists():
+                continue
+
+            # For package.json, check dependencies
+            if filename == "package.json":
+                if self._check_package_json_deps(
+                    file_path, patterns.get("package_deps", [])
+                ):
+                    return True
+            # For pom.xml/build.gradle, presence is enough
+            elif filename in ("pom.xml", "build.gradle", "angular.json"):
+                if filename == "angular.json":
+                    return True
+                elif framework == "spring_boot":
+                    try:
+                        build_content = file_path.read_text()
+                        if "spring-boot" in build_content.lower():
+                            return True
+                    except OSError:
+                        pass
+        return False
+
+    def detect_framework_from_project(self) -> str | None:
+        """Detect framework from project structure.
+
+        Returns:
+            Framework name or None.
+        """
+        # Check cache
+        cache_key = str(self.project_root)
+        if cache_key in self._framework_cache:
+            return self._framework_cache[cache_key]
+
+        detected: str | None = None
+
+        for framework, patterns in FRAMEWORK_PATTERNS.items():
+            if self._check_framework_match(framework, patterns):
+                detected = framework
+                break
+
+        self._framework_cache[cache_key] = detected
+        return detected
+
+    def detect(self, file_path: Path | str) -> LanguageInfo:
+        """Detect language and framework for a file.
+
+        Args:
+            file_path: Path to file.
+
+        Returns:
+            LanguageInfo with detected language and framework.
+        """
+        path = Path(file_path)
+
+        # Detect language from extension
+        language = self.detect_from_extension(path)
+
+        if not language:
+            logger.debug("unknown_language", file=str(path))
+            return LanguageInfo(
+                language="unknown",
+                confidence=0.0,
+            )
+
+        # Detect framework from project structure first (cached)
+        framework = self.detect_framework_from_project()
+
+        # If no framework from project, try from file content
+        if not framework and path.exists():
+            try:
+                content = path.read_text(encoding="utf-8")
+                framework = self.detect_framework_from_content(content, language)
+            except (OSError, UnicodeDecodeError):
+                pass
+
+        # Validate framework matches language
+        if framework:
+            expected_langs = FRAMEWORK_PATTERNS.get(framework, {}).get("languages", [])
+            if language not in expected_langs:
+                framework = None
+
+        return LanguageInfo(
+            language=language,
+            framework=framework,
+            extensions=LANGUAGE_EXTENSIONS.get(language, []),
+            confidence=1.0 if language != "unknown" else 0.0,
+        )
+
+    def detect_directory(self, directory: Path | str) -> dict[str, int]:
+        """Detect language distribution in a directory.
+
+        Args:
+            directory: Directory to scan.
+
+        Returns:
+            Dict mapping language to file count.
+        """
+        dir_path = Path(directory)
+        counts: dict[str, int] = {}
+
+        if not dir_path.exists():
+            return counts
+
+        exclude_dirs = {
+            "__pycache__",
+            "node_modules",
+            ".git",
+            ".venv",
+            "venv",
+            "dist",
+            "build",
+            "target",
+        }
+
+        for ext_list in LANGUAGE_EXTENSIONS.values():
+            for ext in ext_list:
+                for file_path in dir_path.rglob(f"*{ext}"):
+                    if any(excluded in file_path.parts for excluded in exclude_dirs):
+                        continue
+
+                    info = self.detect(file_path)
+                    lang_key = str(info)
+                    counts[lang_key] = counts.get(lang_key, 0) + 1
+
+        return counts
+
+
+def detect_language(file_path: str) -> str:
+    """Detect language for a file (convenience function).
+
+    Args:
+        file_path: Path to file.
+
+    Returns:
+        Language string (e.g., "python", "typescript/react").
+    """
+    detector = LanguageDetector()
+    info = detector.detect(file_path)
+    return str(info)
+
+
+def get_supported_languages() -> list[str]:
+    """Get list of supported languages.
+
+    Returns:
+        List of language names.
+    """
+    return list(LANGUAGE_EXTENSIONS.keys())
+
+
+def get_supported_frameworks() -> list[str]:
+    """Get list of supported frameworks.
+
+    Returns:
+        List of framework names.
+    """
+    return list(FRAMEWORK_PATTERNS.keys())

ref_agents/core/validation_models.py

@@ -0,0 +1,66 @@
+"""Pydantic models for role-output validation reports.
+
+Used by the `validate` MCP dispatcher and per-role validator modules in
+`ref_agents.tools.validators.*`. See SPEC-STORY-021 for full contract.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class Verdict(str, Enum):
+    """Outcome of a role-output validation pass."""
+
+    PASS = "PASS"
+    FAIL_AUTO = "FAIL_AUTO"
+    NEEDS_USER = "NEEDS_USER"
+    HALT = "HALT"
+
+
+class Gap(BaseModel):
+    """One reason a validator did not return PASS.
+
+    Attributes:
+        code: Machine-readable identifier (e.g., "ac_count_lt_3").
+        detail: Human-readable explanation.
+        location: Optional path / line / artifact pointer.
+    """
+
+    code: str
+    detail: str
+    location: str | None = None
+
+
+class UserQuestion(BaseModel):
+    """Question surfaced to the user when verdict is NEEDS_USER.
+
+    Attributes:
+        text: Question prompt.
+        options: Optional enumerated answer choices.
+    """
+
+    text: str
+    options: list[str] | None = None
+
+
+class ValidationReport(BaseModel):
+    """Outcome of a single `validate(role=...)` call.
+
+    Attributes:
+        verdict: Overall outcome.
+        score: Optional 0-5 quality score (PASS-style validators only).
+        gaps: List of failures preventing PASS.
+        halt_reason: Set when verdict == HALT.
+        user_questions: Set when verdict == NEEDS_USER.
+        validator_version: Identifier of the validator that produced this
+            report. Defaults to project version at evaluation time. Used
+            for audit bisection across validator revisions.
+    """
+
+    verdict: Verdict
+    score: float | None = None
+    gaps: list[Gap] = Field(default_factory=list)
+    halt_reason: str | None = None
+    user_questions: list[UserQuestion] = Field(default_factory=list)
+    validator_version: str = "3.13.2"

ref_agents/core/validation_primitives.py

@@ -0,0 +1,176 @@
+"""Shared primitives for role-output validators.
+
+Used by per-role validator modules in `ref_agents.tools.validators.*`.
+Each primitive is pure and deterministic — given identical inputs it
+returns identical outputs (no time, no randomness, no I/O beyond reading
+the artifact file passed in).
+
+See SPEC-STORY-021 / DESIGN-STORY-021 for the full contract.
+"""
+
+import json
+import re
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from ref_agents.errors import CycleDetectedError
+
+
+class ValidationOutcome(BaseModel):
+    """Result of `pydantic_schema_validator`."""
+
+    ok: bool
+    error: str | None = None
+    data: dict[str, Any] | None = None
+
+
+class BijectionResult(BaseModel):
+    """Result of `bijection_checker`."""
+
+    missing_in_a: list[str]
+    missing_in_b: list[str]
+
+
+def markdown_section_checker(path: Path, required_sections: list[str]) -> list[str]:
+    """Return required Markdown sections missing from a file.
+
+    Args:
+        path: Path to a Markdown file.
+        required_sections: Section titles (without leading "#" markers).
+
+    Returns:
+        Required sections not found in the file, in input order.
+        Empty list = all sections present.
+    """
+    if not required_sections:
+        return []
+
+    content = path.read_text(encoding="utf-8")
+    headers = set(re.findall(r"^#{1,6}\s+(.+?)\s*$", content, flags=re.MULTILINE))
+    return [s for s in required_sections if s not in headers]
+
+
+def regex_forbidden_scanner(path: Path, patterns: list[str]) -> list[tuple[str, int]]:
+    """Scan a file for forbidden regex patterns.
+
+    Args:
+        path: Path to the file to scan.
+        patterns: List of regex patterns; any match counts as forbidden.
+
+    Returns:
+        List of (pattern, line_number) tuples for each match.
+        Empty list = no forbidden tokens present.
+    """
+    if not patterns:
+        return []
+
+    compiled = [(p, re.compile(p)) for p in patterns]
+    matches: list[tuple[str, int]] = []
+
+    with path.open("r", encoding="utf-8") as f:
+        for lineno, line in enumerate(f, start=1):
+            for pattern, regex in compiled:
+                if regex.search(line):
+                    matches.append((pattern, lineno))
+    return matches
+
+
+def pydantic_schema_validator(path: Path, model: type[BaseModel]) -> ValidationOutcome:
+    """Validate a JSON file against a pydantic model.
+
+    Args:
+        path: Path to a JSON file.
+        model: Pydantic model class to validate against.
+
+    Returns:
+        ValidationOutcome with `ok=True` + parsed data on success,
+        or `ok=False` + structured error on failure. Never raises.
+    """
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return ValidationOutcome(ok=False, error=f"file_read_failed: {exc}")
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return ValidationOutcome(ok=False, error=f"json_decode_failed: {exc}")
+
+    try:
+        parsed = model.model_validate(data)
+    except ValidationError as exc:
+        return ValidationOutcome(ok=False, error=exc.json())
+
+    return ValidationOutcome(ok=True, data=parsed.model_dump())
+
+
+def bijection_checker(
+    set_a: Iterable[Any],
+    set_b: Iterable[Any],
+    key_fn_a: Callable[[Any], str],
+    key_fn_b: Callable[[Any], str],
+) -> BijectionResult:
+    """Compute bidirectional difference between two iterables.
+
+    Args:
+        set_a: First iterable.
+        set_b: Second iterable.
+        key_fn_a: Function deriving comparison key from each set_a element.
+        key_fn_b: Function deriving comparison key from each set_b element.
+
+    Returns:
+        BijectionResult with `missing_in_a` (keys present in b but not a)
+        and `missing_in_b` (keys present in a but not b). Sorted for
+        deterministic output.
+    """
+    keys_a = {key_fn_a(x) for x in set_a}
+    keys_b = {key_fn_b(x) for x in set_b}
+    return BijectionResult(
+        missing_in_a=sorted(keys_b - keys_a),
+        missing_in_b=sorted(keys_a - keys_b),
+    )
+
+
+def dag_validator(nodes: list[str], edges: list[tuple[str, str]]) -> None:
+    """Verify a directed graph is acyclic.
+
+    Args:
+        nodes: All node identifiers.
+        edges: Directed edges as (from, to) tuples.
+
+    Raises:
+        CycleDetectedError: If any cycle exists. `path` attribute holds
+            the ordered cycle node list.
+    """
+    if not nodes:
+        return
+
+    adjacency: dict[str, list[str]] = {n: [] for n in nodes}
+    for src, dst in edges:
+        if src in adjacency:
+            adjacency[src].append(dst)
+
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[str, int] = {n: WHITE for n in nodes}
+    stack: list[str] = []
+
+    def visit(node: str) -> None:
+        color[node] = GRAY
+        stack.append(node)
+        for neighbor in adjacency.get(node, []):
+            if neighbor not in color:
+                continue
+            if color[neighbor] == GRAY:
+                cycle_start = stack.index(neighbor)
+                raise CycleDetectedError(path=stack[cycle_start:] + [neighbor])
+            if color[neighbor] == WHITE:
+                visit(neighbor)
+        stack.pop()
+        color[node] = BLACK
+
+    for node in nodes:
+        if color[node] == WHITE:
+            visit(node)

ref_agents/errors.py

@@ -0,0 +1,34 @@
+"""Common exception hierarchy for REF Agents.
+
+All REF-specific exceptions derive from `AppError`. Use specific subclasses
+rather than bare `Exception`. Add new subclasses here when a new error
+category appears (avoid one-off ad-hoc classes scattered across modules).
+"""
+
+
+class AppError(Exception):
+    """Base class for all REF Agents application errors."""
+
+
+class CycleDetectedError(AppError):
+    """Raised when a DAG validator finds a cycle.
+
+    Attributes:
+        path: Ordered list of node IDs forming the cycle.
+    """
+
+    def __init__(self, path: list[str], message: str | None = None) -> None:
+        self.path = path
+        super().__init__(message or f"Cycle detected: {' -> '.join(path)}")
+
+
+class ValidatorLoadError(AppError):
+    """Raised when a registered role validator fails to import.
+
+    Attributes:
+        role: Role name whose validator failed to load.
+    """
+
+    def __init__(self, role: str, message: str | None = None) -> None:
+        self.role = role
+        super().__init__(message or f"Failed to load validator for role: {role}")