ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/evaluate_gate.py

@@ -0,0 +1,119 @@
+"""Validation gate evaluation functions for quantifying AC quality metrics."""
+
+from typing import TypedDict
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+def _count_matches_in_list(items: list[str], keywords: list[str]) -> int:
+    """Count items that contain any of the keywords.
+
+    Args:
+        items: List of strings to search
+        keywords: Keywords to search for
+
+    Returns:
+        Count of items containing at least one keyword
+    """
+    return sum(
+        1 for item in items if any(keyword in item.lower() for keyword in keywords)
+    )
+
+
+class TestStrategyResult(TypedDict):
+    """Result of test strategy evaluation."""
+
+    has_test_strategy: bool
+    gherkin_ratio: float
+    gherkin_count: int
+    total_ac_count: int
+
+
+class AmbiguityResult(TypedDict):
+    """Result of ambiguity evaluation."""
+
+    is_ambiguous: bool
+    ambiguous_count: int
+    total_ac_count: int
+    ambiguous_terms_found: list[str]
+
+
+def evaluate_test_strategy(acceptance_criteria: list[str]) -> TestStrategyResult:
+    """Evaluate if acceptance criteria have a test strategy.
+
+    Uses Gherkin format detection (Given/When/Then keywords) to determine
+    if AC have a testable strategy. Threshold: gherkin_ratio >= 0.4.
+
+    Args:
+        acceptance_criteria: List of acceptance criteria strings
+
+    Returns:
+        TestStrategyResult with has_test_strategy boolean and metrics
+    """
+    if not acceptance_criteria:
+        return TestStrategyResult(
+            has_test_strategy=False,
+            gherkin_ratio=0.0,
+            gherkin_count=0,
+            total_ac_count=0,
+        )
+
+    gherkin_keywords = ["given", "when", "then", "and", "but"]
+    gherkin_count = _count_matches_in_list(acceptance_criteria, gherkin_keywords)
+    total_ac_count = len(acceptance_criteria)
+    gherkin_ratio = gherkin_count / total_ac_count
+
+    # Threshold: gherkin_ratio >= 0.4 = has_test_strategy=True
+    has_test_strategy = gherkin_ratio >= 0.4  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+
+    return TestStrategyResult(
+        has_test_strategy=has_test_strategy,
+        gherkin_ratio=gherkin_ratio,
+        gherkin_count=gherkin_count,
+        total_ac_count=total_ac_count,
+    )
+
+
+def evaluate_ambiguous(acceptance_criteria: list[str]) -> AmbiguityResult:
+    """Evaluate if acceptance criteria contain ambiguous terms.
+
+    Detects ambiguous terms that make AC untestable or unclear.
+    Uses same logic as invest_scorer._score_estimable().
+
+    Args:
+        acceptance_criteria: List of acceptance criteria strings
+
+    Returns:
+        AmbiguityResult with is_ambiguous boolean and detected terms
+    """
+    if not acceptance_criteria:
+        return AmbiguityResult(
+            is_ambiguous=False,
+            ambiguous_count=0,
+            total_ac_count=0,
+            ambiguous_terms_found=[],
+        )
+
+    ambiguous_terms = ["fast", "quickly", "user-friendly", "easy", "intuitive"]
+    ambiguous_found: list[str] = []
+
+    for ac in acceptance_criteria:
+        ac_lower = ac.lower()
+        for term in ambiguous_terms:
+            if term in ac_lower and term not in ambiguous_found:
+                ambiguous_found.append(term)
+
+    ambiguous_count = len(ambiguous_found)
+    total_ac_count = len(acceptance_criteria)
+
+    # If any ambiguous terms found, AC is ambiguous
+    is_ambiguous = ambiguous_count > 0
+
+    return AmbiguityResult(
+        is_ambiguous=is_ambiguous,
+        ambiguous_count=ambiguous_count,
+        total_ac_count=total_ac_count,
+        ambiguous_terms_found=ambiguous_found,
+    )

ref_agents/tools/external_detector.py

@@ -0,0 +1,524 @@
+"""External Dependency Detector for REF Agents.
+
+Scans codebases to auto-detect external dependencies:
+- Environment variable references (API URLs, endpoints)
+- Known third-party API client libraries
+- Hardcoded URL literals
+- Config file endpoint definitions
+- NuGet packages from .csproj and packages.config (C#)
+
+Never touches .env files (security).
+"""
+
+import ast
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# Known external API client libraries
+KNOWN_API_CLIENTS: dict[str, str] = {
+    "stripe": "Stripe Payment API",
+    "boto3": "AWS Services",
+    "botocore": "AWS Services",
+    "twilio": "Twilio Communication API",
+    "sendgrid": "SendGrid Email API",
+    "slack_sdk": "Slack API",
+    "google.cloud": "Google Cloud Services",
+    "azure": "Azure Services",
+    "requests_oauthlib": "OAuth Provider",
+    "httpx": "HTTP Client (external calls)",
+    "aiohttp": "Async HTTP Client (external calls)",
+    "requests": "HTTP Client (external calls)",
+    "urllib3": "HTTP Client (external calls)",
+    "redis": "Redis Database",
+    "pymongo": "MongoDB",
+    "psycopg2": "PostgreSQL",
+    "mysql": "MySQL",
+    "elasticsearch": "Elasticsearch",
+    "kafka": "Apache Kafka",
+    "pika": "RabbitMQ",
+    "celery": "Celery Task Queue",
+}
+
+# Patterns for env var extraction
+ENV_VAR_PATTERNS: list[str] = [
+    r'os\.getenv\(["\']([A-Z_]+(?:URL|API|ENDPOINT|HOST|SERVICE)[A-Z_]*)["\']',
+    r'os\.environ\[["\']([A-Z_]+(?:URL|API|ENDPOINT|HOST|SERVICE)[A-Z_]*)["\']',
+    r'os\.environ\.get\(["\']([A-Z_]+(?:URL|API|ENDPOINT|HOST|SERVICE)[A-Z_]*)["\']',
+]
+
+# Known external NuGet package prefixes → description
+KNOWN_NUGET_CLIENTS: dict[str, str] = {
+    "Stripe.net": "Stripe Payment API",
+    "AWSSDK": "AWS Services",
+    "Twilio": "Twilio Communication API",
+    "SendGrid": "SendGrid Email API",
+    "SlackAPI": "Slack API",
+    "Google.Cloud": "Google Cloud Services",
+    "Azure": "Azure Services",
+    "Microsoft.Azure": "Azure Services",
+    "StackExchange.Redis": "Redis Database",
+    "MongoDB.Driver": "MongoDB",
+    "Npgsql": "PostgreSQL",
+    "MySql.Data": "MySQL",
+    "MySqlConnector": "MySQL",
+    "Elasticsearch.Net": "Elasticsearch",
+    "NEST": "Elasticsearch",
+    "Confluent.Kafka": "Apache Kafka",
+    "RabbitMQ.Client": "RabbitMQ",
+    "MassTransit": "Message Bus",
+    "Refit": "HTTP Client (typed REST)",
+    "RestSharp": "HTTP Client (external calls)",
+    "Flurl": "HTTP Client (external calls)",
+    "Polly": "Resilience / Retry Policy",
+    "Serilog": "Structured Logging",
+    "NLog": "Logging",
+    "Hangfire": "Background Jobs",
+    "Quartz": "Job Scheduler",
+    "PayPal": "PayPal Payment API",
+    "Braintree": "Braintree Payment API",
+    "Okta": "Okta Identity API",
+    "Auth0": "Auth0 Identity API",
+    "Datadog": "Datadog APM",
+    "OpenTelemetry": "OpenTelemetry",
+    "NewRelic": "New Relic APM",
+    "Sentry": "Sentry Error Tracking",
+    "LaunchDarkly": "Feature Flags",
+    "Contentful": "Contentful CMS API",
+    "Algolia": "Algolia Search API",
+    "Segment": "Segment Analytics",
+    "Mixpanel": "Mixpanel Analytics",
+    "SendinBlue": "SendinBlue Email API",
+    "PusherServer": "Pusher WebSocket API",
+    "FirebaseAdmin": "Firebase API",
+}
+
+# URL pattern
+URL_PATTERN = re.compile(
+    r'["\']'
+    r'(https?://(?!localhost|127\.0\.0\.1|0\.0\.0\.0)[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}[^\s"\']*)'
+    r'["\']'
+)
+
+
+@dataclass
+class ExternalDependency:
+    """Represents a detected external dependency."""
+
+    name: str
+    dep_type: str  # 'env_var', 'api_client', 'url', 'config'
+    source_file: str
+    line_number: int | None = None
+    description: str = ""
+
+    def to_dict(self) -> dict[str, str | int | None]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "type": self.dep_type,
+            "file": self.source_file,
+            "line": self.line_number,
+            "description": self.description,
+        }
+
+
+@dataclass
+class ScanResult:
+    """Result of external dependency scan."""
+
+    dependencies: list[ExternalDependency] = field(default_factory=list)
+    files_scanned: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def env_vars(self) -> list[ExternalDependency]:
+        """Get environment variable dependencies."""
+        return [d for d in self.dependencies if d.dep_type == "env_var"]
+
+    @property
+    def api_clients(self) -> list[ExternalDependency]:
+        """Get API client dependencies."""
+        return [d for d in self.dependencies if d.dep_type == "api_client"]
+
+    @property
+    def urls(self) -> list[ExternalDependency]:
+        """Get URL dependencies."""
+        return [d for d in self.dependencies if d.dep_type == "url"]
+
+    @property
+    def nuget_packages(self) -> list[ExternalDependency]:
+        """Get NuGet package dependencies."""
+        return [d for d in self.dependencies if d.dep_type == "nuget_package"]
+
+
+def _scan_file_for_env_vars(file_path: Path, content: str) -> list[ExternalDependency]:
+    """Scan file content for environment variable references.
+
+    Args:
+        file_path: Path to the file being scanned.
+        content: File content.
+
+    Returns:
+        List of detected env var dependencies.
+    """
+    deps: list[ExternalDependency] = []
+    seen: set[str] = set()
+
+    for pattern in ENV_VAR_PATTERNS:
+        for match in re.finditer(pattern, content):
+            var_name = match.group(1)
+            if var_name not in seen:
+                seen.add(var_name)
+                # Find line number
+                line_num = content[: match.start()].count("\n") + 1
+                deps.append(
+                    ExternalDependency(
+                        name=var_name,
+                        dep_type="env_var",
+                        source_file=str(file_path),
+                        line_number=line_num,
+                        description="Environment variable for external endpoint",
+                    )
+                )
+
+    return deps
+
+
+def _scan_file_for_api_clients(
+    file_path: Path, content: str
+) -> list[ExternalDependency]:
+    """Scan file for known API client library imports.
+
+    Args:
+        file_path: Path to the file being scanned.
+        content: File content.
+
+    Returns:
+        List of detected API client dependencies.
+    """
+    deps: list[ExternalDependency] = []
+    seen: set[str] = set()
+
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return deps
+
+    for node in ast.walk(tree):
+        module_name: str | None = None
+
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                module_name = alias.name.split(".")[0]
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                module_name = node.module.split(".")[0]
+
+        if module_name and module_name in KNOWN_API_CLIENTS:
+            if module_name not in seen:
+                seen.add(module_name)
+                deps.append(
+                    ExternalDependency(
+                        name=module_name,
+                        dep_type="api_client",
+                        source_file=str(file_path),
+                        line_number=getattr(node, "lineno", None),
+                        description=KNOWN_API_CLIENTS[module_name],
+                    )
+                )
+
+    return deps
+
+
+def _scan_file_for_urls(file_path: Path, content: str) -> list[ExternalDependency]:
+    """Scan file for hardcoded external URLs.
+
+    Args:
+        file_path: Path to the file being scanned.
+        content: File content.
+
+    Returns:
+        List of detected URL dependencies.
+    """
+    deps: list[ExternalDependency] = []
+    seen: set[str] = set()
+
+    for match in URL_PATTERN.finditer(content):
+        url = match.group(1)
+        # Extract domain
+        domain_match = re.search(r"https?://([^/]+)", url)
+        domain = domain_match.group(1) if domain_match else url
+
+        if domain not in seen:
+            seen.add(domain)
+            line_num = content[: match.start()].count("\n") + 1
+            deps.append(
+                ExternalDependency(
+                    name=domain,
+                    dep_type="url",
+                    source_file=str(file_path),
+                    line_number=line_num,
+                    description=f"External URL: {url[:50]}...",
+                )
+            )
+
+    return deps
+
+
+def _describe_nuget_package(package_id: str) -> str:
+    """Return a human-readable description for a NuGet package ID.
+
+    Args:
+        package_id: NuGet package identifier (e.g. 'StackExchange.Redis').
+
+    Returns:
+        Description from KNOWN_NUGET_CLIENTS or generic fallback.
+    """
+    for prefix, description in KNOWN_NUGET_CLIENTS.items():
+        if package_id.startswith(prefix):
+            return description
+    return f"NuGet package: {package_id}"
+
+
+def _scan_csproj_for_packages(csproj_path: Path) -> list[ExternalDependency]:
+    """Extract PackageReference entries from a .csproj file.
+
+    Args:
+        csproj_path: Path to the .csproj file.
+
+    Returns:
+        List of ExternalDependency for each PackageReference found.
+    """
+    deps: list[ExternalDependency] = []
+    try:
+        tree = ET.parse(csproj_path)  # noqa: S314 — local file, not from network
+    except ET.ParseError as e:
+        logger.warning("csproj_parse_error", file=str(csproj_path), error=str(e))
+        return deps
+    except OSError as e:
+        logger.warning("csproj_read_error", file=str(csproj_path), error=str(e))
+        return deps
+
+    root = tree.getroot()
+    seen: set[str] = set()
+
+    # ElementTree strips namespace prefixes; .csproj elements are un-namespaced
+    for ref in root.iter("PackageReference"):
+        package_id = ref.get("Include") or ref.get("Update") or ""
+        if not package_id or package_id in seen:
+            continue
+        seen.add(package_id)
+        deps.append(
+            ExternalDependency(
+                name=package_id,
+                dep_type="nuget_package",
+                source_file=str(csproj_path),
+                line_number=None,
+                description=_describe_nuget_package(package_id),
+            )
+        )
+
+    logger.debug(
+        "csproj_scanned",
+        file=str(csproj_path),
+        packages_found=len(deps),
+    )
+    return deps
+
+
+def _scan_packages_config(packages_config_path: Path) -> list[ExternalDependency]:
+    """Extract package entries from a legacy packages.config file.
+
+    Args:
+        packages_config_path: Path to the packages.config file.
+
+    Returns:
+        List of ExternalDependency for each package found.
+    """
+    deps: list[ExternalDependency] = []
+    try:
+        tree = ET.parse(packages_config_path)  # noqa: S314 — local file, not from network
+    except ET.ParseError as e:
+        logger.warning(
+            "packages_config_parse_error",
+            file=str(packages_config_path),
+            error=str(e),
+        )
+        return deps
+    except OSError as e:
+        logger.warning(
+            "packages_config_read_error",
+            file=str(packages_config_path),
+            error=str(e),
+        )
+        return deps
+
+    root = tree.getroot()
+    seen: set[str] = set()
+
+    for pkg in root.iter("package"):
+        package_id = pkg.get("id") or ""
+        if not package_id or package_id in seen:
+            continue
+        seen.add(package_id)
+        deps.append(
+            ExternalDependency(
+                name=package_id,
+                dep_type="nuget_package",
+                source_file=str(packages_config_path),
+                line_number=None,
+                description=_describe_nuget_package(package_id),
+            )
+        )
+
+    logger.debug(
+        "packages_config_scanned",
+        file=str(packages_config_path),
+        packages_found=len(deps),
+    )
+    return deps
+
+
+def scan_directory(directory: str | Path) -> ScanResult:
+    """Scan a directory for external dependencies.
+
+    Args:
+        directory: Path to directory to scan.
+
+    Returns:
+        ScanResult with all detected dependencies.
+    """
+    result = ScanResult()
+    dir_path = Path(directory)
+
+    if not dir_path.exists():
+        result.errors.append(f"Directory not found: {directory}")
+        return result
+
+    # Find all Python files, excluding common non-code directories
+    exclude_dirs = {
+        "__pycache__",
+        ".git",
+        ".venv",
+        "venv",
+        "node_modules",
+        ".tox",
+        "dist",
+        "build",
+    }
+
+    for py_file in dir_path.rglob("*.py"):
+        # Skip excluded directories
+        if any(excluded in py_file.parts for excluded in exclude_dirs):
+            continue
+
+        try:
+            content = py_file.read_text(encoding="utf-8")
+            result.files_scanned += 1
+
+            # Scan for all dependency types
+            result.dependencies.extend(_scan_file_for_env_vars(py_file, content))
+            result.dependencies.extend(_scan_file_for_api_clients(py_file, content))
+            result.dependencies.extend(_scan_file_for_urls(py_file, content))
+
+        except (OSError, UnicodeDecodeError) as e:
+            result.errors.append(f"Error reading {py_file}: {e}")
+            logger.warning("file_read_error", file=str(py_file), error=str(e))
+
+    # C# NuGet packages: modern SDK-style (.csproj PackageReference)
+    csproj_exclude = {"bin", "obj", ".git", "node_modules"}
+    for csproj_file in dir_path.rglob("*.csproj"):
+        if any(excluded in csproj_file.parts for excluded in csproj_exclude):
+            continue
+        result.dependencies.extend(_scan_csproj_for_packages(csproj_file))
+        result.files_scanned += 1
+
+    # C# NuGet packages: legacy packages.config (pre-SDK projects)
+    for pkg_config in dir_path.rglob("packages.config"):
+        if any(excluded in pkg_config.parts for excluded in csproj_exclude):
+            continue
+        result.dependencies.extend(_scan_packages_config(pkg_config))
+        result.files_scanned += 1
+
+    logger.info(
+        "scan_complete",
+        files_scanned=result.files_scanned,
+        dependencies_found=len(result.dependencies),
+    )
+
+    return result
+
+
+def generate_codemap_section(result: ScanResult) -> str:
+    """Generate CODE_MAP.md External Dependencies section.
+
+    Args:
+        result: Scan result with dependencies.
+
+    Returns:
+        Markdown formatted section.
+    """
+    output = """## External Dependencies
+*Auto-detected by external_detector.py*
+
+"""
+
+    if not result.dependencies:
+        output += "No external dependencies detected.\n"
+        return output
+
+    # Group by type
+    if result.env_vars:
+        output += "### Environment Variables (External Endpoints)\n\n"
+        output += "| Variable | File | Line | Notes |\n"
+        output += "|----------|------|------|-------|\n"
+        for dep in result.env_vars:
+            output += f"| `{dep.name}` | `{Path(dep.source_file).name}` | {dep.line_number or '-'} | {dep.description} |\n"
+        output += "\n"
+
+    if result.api_clients:
+        output += "### External API Clients\n\n"
+        output += "| Library | Service | File | Line |\n"
+        output += "|---------|---------|------|------|\n"
+        for dep in result.api_clients:
+            output += f"| `{dep.name}` | {dep.description} | `{Path(dep.source_file).name}` | {dep.line_number or '-'} |\n"
+        output += "\n"
+
+    if result.urls:
+        output += "### Hardcoded External URLs\n\n"
+        output += "| Domain | File | Line | Notes |\n"
+        output += "|--------|------|------|-------|\n"
+        for dep in result.urls:
+            output += f"| `{dep.name}` | `{Path(dep.source_file).name}` | {dep.line_number or '-'} | ⚠️ Consider using env var |\n"
+        output += "\n"
+
+    return output
+
+
+def scan_and_report(directory: str) -> str:
+    """Scan directory and return formatted report.
+
+    Args:
+        directory: Path to scan.
+
+    Returns:
+        Status message with summary.
+    """
+    result = scan_directory(directory)
+
+    if result.errors:
+        return f"Scan completed with errors: {result.errors}"
+
+    summary = (
+        f"Scanned {result.files_scanned} files. "
+        f"Found: {len(result.env_vars)} env vars, "
+        f"{len(result.api_clients)} API clients, "
+        f"{len(result.urls)} URLs."
+    )
+
+    return summary