devguard-scanner 0.1.0__py3-none-any.whl

devguard/ai/providers/openai_compat.py

@@ -0,0 +1,157 @@
+"""Built-in providers: OpenAI and OpenAI-compatible Chat Completions APIs (extra: devguard-scanner[openai]).
+
+`openai`              the OpenAI API.
+`openai-compatible`   Ollama, vLLM, LM Studio, llama.cpp server, OpenRouter, company gateways, and other
+                      services exposing the Chat Completions API. Requires `base_url`.
+
+Profile settings:
+    model               required
+    api_key             resolved from secrets (local servers usually accept any value)
+    base_url            endpoint; required for openai-compatible
+    temperature         sent only if set (several models reject sampling parameters)
+    max_tokens_param    "max_completion_tokens" (default for openai) or "max_tokens" (default for compatible)
+    tool_calling        false for servers/models without function calling (core then uses prompted tools)
+    max_context_tokens  context size used to bound the evidence payload (default 128000)
+    data_stays_local    true for local servers; shown in the consent notice
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from devguard.ai.sdk import (
+    CompletionRequest,
+    CompletionResponse,
+    Message,
+    ProviderCapabilities,
+    ToolCall,
+    Usage,
+    error_response,
+)
+
+
+class OpenAICompatibleProvider:
+    def __init__(self, settings: dict[str, Any], *, name: str, default_tokens_param: str) -> None:
+        try:
+            import openai
+        except ImportError as exc:  # pragma: no cover - optional extra
+            raise RuntimeError(
+                "The 'openai' package is not installed. Run: pip install 'devguard-scanner[openai]'"
+            ) from exc
+        self.name = name
+        self._openai = openai
+        if name == "openai-compatible" and not settings.get("base_url") and not settings.get("_client"):
+            raise ValueError("openai-compatible profiles require base_url")
+        self.client = settings.get("_client") or openai.OpenAI(
+            api_key=settings.get("api_key") or "not-needed",
+            base_url=settings.get("base_url"),
+            max_retries=int(settings.get("max_retries", 2)),
+        )
+        self.temperature = settings.get("temperature")
+        self.tokens_param = settings.get("max_tokens_param", default_tokens_param)
+        self.tool_calling = bool(settings.get("tool_calling", True))
+        self.context = int(settings.get("max_context_tokens", 128_000))
+        self.local = bool(settings.get("data_stays_local", False))
+
+    def capabilities(self) -> ProviderCapabilities:
+        return ProviderCapabilities(
+            tool_calling=self.tool_calling,
+            structured_output=False,
+            max_context_tokens=self.context,
+            data_stays_local=self.local,
+        )
+
+    def complete(self, request: CompletionRequest) -> CompletionResponse:
+        params: dict[str, Any] = {
+            "model": request.model,
+            "messages": _to_messages(request.messages),
+            self.tokens_param: request.max_output_tokens,
+            "timeout": request.timeout_s,
+        }
+        if request.tools and self.tool_calling:
+            params["tools"] = [
+                {
+                    "type": "function",
+                    "function": {"name": t.name, "description": t.description, "parameters": t.input_schema},
+                }
+                for t in request.tools
+            ]
+        if self.temperature is not None:
+            params["temperature"] = float(self.temperature)
+        o = self._openai
+        try:
+            resp = self.client.chat.completions.create(**params)
+        except o.RateLimitError as exc:
+            return error_response(request.model, f"rate limited: {exc}")
+        except o.APIStatusError as exc:
+            return error_response(request.model, f"API error {exc.status_code}: {exc.message}")
+        except o.APITimeoutError:
+            return error_response(request.model, "request timed out")
+        except o.APIConnectionError as exc:
+            return error_response(request.model, f"connection error: {exc}")
+        if not resp.choices:
+            return error_response(request.model, "empty response")
+        choice = resp.choices[0]
+        calls: list[ToolCall] = []
+        for c in choice.message.tool_calls or []:
+            try:
+                args = json.loads(c.function.arguments or "{}")
+            except json.JSONDecodeError:
+                args = {"_invalid_json": c.function.arguments}
+            calls.append(ToolCall(id=c.id, name=c.function.name, arguments=args if isinstance(args, dict) else {}))
+        finish = choice.finish_reason
+        stop = (
+            "tool_use"
+            if calls
+            else "max_tokens"
+            if finish == "length"
+            else "refused"
+            if finish == "content_filter"
+            else "final"
+        )
+        usage = Usage(
+            input_tokens=getattr(resp.usage, "prompt_tokens", None),
+            output_tokens=getattr(resp.usage, "completion_tokens", None),
+        )
+        return CompletionResponse(
+            text=choice.message.content,
+            tool_calls=calls,
+            stop_reason=stop,  # type: ignore[arg-type]
+            usage=usage,
+            model=resp.model or request.model,
+            error="content filtered" if stop == "refused" else None,
+        )
+
+
+def _to_messages(messages: list[Message]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        if m.role == "tool":
+            out += [{"role": "tool", "tool_call_id": r.call_id, "content": r.content} for r in m.tool_results]
+        elif m.role == "assistant" and m.tool_calls:
+            out.append(
+                {
+                    "role": "assistant",
+                    "content": m.content or None,
+                    "tool_calls": [
+                        {
+                            "id": c.id,
+                            "type": "function",
+                            "function": {"name": c.name, "arguments": json.dumps(c.arguments)},
+                        }
+                        for c in m.tool_calls
+                    ],
+                }
+            )
+        else:
+            out.append({"role": m.role, "content": m.content})
+    return out
+
+
+def make_provider(settings: dict[str, Any]) -> OpenAICompatibleProvider:
+    return OpenAICompatibleProvider(settings, name="openai-compatible", default_tokens_param="max_tokens")
+
+
+def make_openai_provider(settings: dict[str, Any]) -> OpenAICompatibleProvider:
+    return OpenAICompatibleProvider(settings, name="openai", default_tokens_param="max_completion_tokens")

devguard/ai/registry.py

@@ -0,0 +1,160 @@
+"""Provider discovery and loading (PLG-002..006).
+
+Providers load only from: built-in entry points, installed packages exposing the `devguard.ai_providers`
+entry point, or a Python file named in user-level configuration. Paths inside the scan target are refused
+(SAFE-017). Secrets are referenced as `env:VAR` and resolved at call time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import os
+import sys
+from dataclasses import dataclass, field
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from devguard.ai.sdk import AIProvider
+from devguard.core.config import is_within
+
+ENTRY_POINT_GROUP = "devguard.ai_providers"
+
+
+class ProviderError(Exception):
+    pass
+
+
+class AIProfile(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    provider: str
+    model: str = ""
+    plugin: str | None = None  # "path/to/file.py:factory" when provider == "python"
+    secrets: dict[str, str] = Field(default_factory=dict)
+
+    def settings(self) -> dict[str, Any]:
+        return dict(self.model_extra or {})
+
+
+class AIConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    default_profile: str | None = None
+    max_steps: int = 8
+    max_tool_calls: int = 20
+    max_total_tokens: int = 400_000
+    max_cost_usd: float | None = 1.0
+    timeout_s: float = 120.0
+    max_output_tokens: int = 16_000
+    send_excerpts: bool = True
+    top_k: int = 25
+    allowed_plugins: list[str] | None = None
+    profiles: dict[str, AIProfile] = Field(default_factory=dict)
+
+
+@dataclass
+class LoadedProvider:
+    provider: AIProvider
+    profile_name: str
+    profile: AIProfile
+    origin: str  # "entry point <dist> <version>" or "file <path> sha256:<..>"
+    settings: dict[str, Any] = field(default_factory=dict)
+
+
+def resolve_secret(ref: str) -> str:
+    if ref.startswith("env:"):
+        var = ref[4:]
+        value = os.environ.get(var)
+        if not value:
+            raise ProviderError(f"environment variable {var} is not set")
+        return value
+    if ref.startswith("keychain:"):
+        try:
+            import keyring  # optional
+        except ImportError as exc:
+            raise ProviderError("keychain: secrets need the optional 'keyring' package") from exc
+        value = keyring.get_password("devguard", ref[9:])
+        if not value:
+            raise ProviderError(f"no keychain entry devguard/{ref[9:]}")
+        return value
+    raise ProviderError("secrets must be referenced as env:VAR or keychain:NAME, never written inline")
+
+
+def available_entry_points() -> dict[str, str]:
+    out: dict[str, str] = {}
+    for ep in entry_points(group=ENTRY_POINT_GROUP):
+        dist = getattr(ep, "dist", None)
+        origin = f"{dist.name} {dist.version}" if dist is not None else "unknown distribution"
+        out[ep.name] = origin
+    return out
+
+
+def load_provider(cfg: AIConfig, profile_name: str | None, target: Path | None) -> LoadedProvider:
+    name = profile_name or cfg.default_profile
+    if not name:
+        raise ProviderError("no AI profile selected: pass --ai-profile or set ai.default_profile in your user config")
+    profile = cfg.profiles.get(name)
+    if profile is None:
+        raise ProviderError(f"unknown AI profile {name!r}; configured: {', '.join(sorted(cfg.profiles)) or 'none'}")
+    if cfg.allowed_plugins is not None and profile.provider not in cfg.allowed_plugins:
+        raise ProviderError(f"provider {profile.provider!r} is not in ai.allowed_plugins")
+    settings = profile.settings()
+    settings["model"] = profile.model
+    for key, ref in profile.secrets.items():
+        settings[key] = resolve_secret(ref)
+    if profile.provider == "python":
+        factory, origin = _load_file_plugin(profile.plugin, target)
+    else:
+        factory, origin = _load_entry_point(profile.provider)
+    try:
+        provider = factory(settings)
+    except Exception as exc:
+        raise ProviderError(f"provider {profile.provider!r} failed to initialize: {exc}") from exc
+    for attr in ("name", "capabilities", "complete"):
+        if not hasattr(provider, attr):
+            raise ProviderError(f"provider {profile.provider!r} does not implement AIProvider ({attr} missing)")
+    return LoadedProvider(
+        provider, name, profile, origin, {k: v for k, v in settings.items() if k not in profile.secrets}
+    )
+
+
+def _load_entry_point(name: str) -> tuple[Any, str]:
+    for ep in entry_points(group=ENTRY_POINT_GROUP):
+        if ep.name == name:
+            dist = getattr(ep, "dist", None)
+            origin = f"entry point {name} ({dist.name} {dist.version})" if dist else f"entry point {name}"
+            try:
+                return ep.load(), origin
+            except Exception as exc:
+                raise ProviderError(f"cannot load provider {name!r}: {exc}") from exc
+    raise ProviderError(f"no provider named {name!r}. Installed: {', '.join(sorted(available_entry_points()))}")
+
+
+def _load_file_plugin(spec: str | None, target: Path | None) -> tuple[Any, str]:
+    if not spec or ":" not in spec:
+        raise ProviderError('python profiles need plugin = "/path/to/file.py:factory"')
+    path_str, _, func = spec.rpartition(":")
+    path = Path(path_str).expanduser().resolve()
+    if target is not None and is_within(path, target):
+        raise ProviderError("refusing to load a provider plugin from inside the scan target")
+    if not path.is_file() or path.suffix != ".py":
+        raise ProviderError(f"plugin file not found: {path}")
+    digest = hashlib.sha256(path.read_bytes()).hexdigest()[:12]
+    mod_name = f"devguard_user_plugin_{digest}"
+    spec_obj = importlib.util.spec_from_file_location(mod_name, path)
+    if spec_obj is None or spec_obj.loader is None:
+        raise ProviderError(f"cannot import {path}")
+    module = importlib.util.module_from_spec(spec_obj)
+    sys.modules[mod_name] = module
+    try:
+        spec_obj.loader.exec_module(module)  # user-configured plugin code, loaded like any installed package
+    except Exception as exc:
+        raise ProviderError(f"plugin {path} failed to import: {exc}") from exc
+    factory = getattr(module, func, None)
+    if not callable(factory):
+        raise ProviderError(f"{path} has no callable {func!r}")
+    return factory, f"file {path} sha256:{digest}"

devguard/ai/run.py

@@ -0,0 +1,119 @@
+"""AI stage orchestration: profile loading, consent (AI-003), response cache (AI-011), failure containment."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from devguard.ai.investigator import LoopInvestigator, build_evidence
+from devguard.ai.registry import AIConfig, ProviderError, load_provider
+from devguard.core.config import user_data_dir
+from devguard.core.models import AIReport
+from devguard.core.service import ScanOutcome
+
+
+def _consent_file() -> Path:
+    return user_data_dir() / "ai-consent.json"
+
+
+def _consent_key(profile: str, provider: str, model: str) -> str:
+    return f"{profile}|{provider}|{model}"
+
+
+def has_consent(key: str) -> bool:
+    try:
+        return key in json.loads(_consent_file().read_text())
+    except (OSError, ValueError):
+        return False
+
+
+def record_consent(key: str) -> None:
+    path = _consent_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        data = []
+    if key not in data:
+        data.append(key)
+    path.write_text(json.dumps(data, indent=1))
+
+
+def run_ai(
+    outcome: ScanOutcome,
+    ai_settings: dict,
+    *,
+    profile: str | None,
+    tools_enabled: bool,
+    assume_consent: bool,
+    use_cache: bool = True,
+    ask: Callable[[str], bool] | None = None,
+) -> AIReport:
+    """Run the AI stage. Never raises: every failure becomes AIReport(status="failed"/"skipped")."""
+    try:
+        cfg = AIConfig.model_validate(ai_settings)
+    except Exception as exc:
+        return AIReport(status="failed", error=f"invalid [ai] configuration: {exc}")
+    target = Path(outcome.fs.root)
+    try:
+        loaded = load_provider(cfg, profile, target)
+    except ProviderError as exc:
+        return AIReport(status="failed", profile=profile or cfg.default_profile, error=str(exc))
+    caps = loaded.provider.capabilities()
+    key = _consent_key(loaded.profile_name, loaded.profile.provider, loaded.profile.model)
+    _, summary, _ = build_evidence(outcome.result, cfg, caps.max_context_tokens)
+    if not caps.data_stays_local and not assume_consent and not has_consent(key):
+        excerpts = "redacted code excerpts" if summary["excerpts_included"] else "no code excerpts"
+        tools = "read-only tool results (file contents on request, redacted)" if tools_enabled else "no tool access"
+        notice = (
+            f"AI investigation will send data to provider '{loaded.profile.provider}' "
+            f"(profile '{loaded.profile_name}', model '{loaded.profile.model or 'default'}'):\n"
+            f"  - {summary['findings_sent']} finding(s) with {excerpts} (~{summary['bytes']} bytes)\n"
+            f"  - {tools}\n"
+            "Secrets are redacted before sending. The provider's data-handling terms apply.\nProceed?"
+        )
+        if ask is None or not ask(notice):
+            return AIReport(
+                status="skipped",
+                profile=loaded.profile_name,
+                provider=loaded.profile.provider,
+                error="no consent to send data (use --yes-send-code in non-interactive runs)",
+            )
+        record_consent(key)
+    investigator = LoopInvestigator(loaded, cfg, tools_enabled=tools_enabled)
+    cache_path = None
+    if use_cache:
+        evidence, _, _ = build_evidence(outcome.result, cfg, caps.max_context_tokens)
+        cache_path = user_data_dir() / "ai-cache" / f"{investigator.cache_key(evidence)}.json"
+        if cache_path.is_file():
+            try:
+                cached = AIReport.model_validate_json(cache_path.read_text())
+                cached.usage = {**cached.usage, "cached": True}
+                return cached
+            except ValueError:
+                pass
+    try:
+        report = investigator.investigate(outcome)
+    except Exception as exc:
+        return AIReport(
+            status="failed",
+            profile=loaded.profile_name,
+            provider=loaded.profile.provider,
+            plugin=loaded.origin,
+            error=f"{type(exc).__name__}: {exc}",
+        )
+    if cache_path is not None and report.status == "completed":
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(report.model_dump_json())
+    return report
+
+
+def interactive_ask(prompt: str) -> bool:
+    if not sys.stdin.isatty() or os.environ.get("CI"):
+        return False
+    sys.stderr.write(prompt + " [y/N] ")
+    sys.stderr.flush()
+    return sys.stdin.readline().strip().lower() in ("y", "yes")

devguard/ai/sdk.py

@@ -0,0 +1,102 @@
+"""DevGuard Provider Plugin API, version 1 (public and stable; see docs/plugins.md).
+
+A provider plugin translates ONE completion request into a vendor API call and back. The agent loop,
+tools, policy, redaction, budgets, and output validation all live in DevGuard's core, so a plugin cannot
+widen what the AI can access.
+
+Every plugin exposes a factory:
+
+    def make_provider(settings: dict[str, Any]) -> AIProvider
+
+`settings` contains the profile's non-secret settings plus resolved secrets (e.g. settings["api_key"]).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol, runtime_checkable
+
+PLUGIN_API_VERSION = "1"
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    input_schema: dict[str, Any]  # JSON Schema
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    call_id: str
+    content: str  # already capped and redacted by the core
+    is_error: bool = False
+
+
+@dataclass(frozen=True)
+class Message:
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)  # assistant turns
+    tool_results: list[ToolResult] = field(default_factory=list)  # tool turns
+    # Opaque data a provider returned with this assistant turn (CompletionResponse.provider_data).
+    # The core passes it back unchanged so providers can replay their native content (e.g. thinking blocks).
+    provider_data: Any = None
+
+
+@dataclass(frozen=True)
+class CompletionRequest:
+    messages: list[Message]
+    tools: list[ToolSpec]  # empty in no-tools mode
+    output_schema: dict[str, Any] | None  # JSON Schema for the final answer
+    model: str
+    max_output_tokens: int
+    temperature: float | None  # providers may ignore it (some models reject sampling parameters)
+    timeout_s: float
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cost_usd: float | None = None  # optional; the core estimates from token prices otherwise
+
+
+@dataclass(frozen=True)
+class CompletionResponse:
+    text: str | None
+    tool_calls: list[ToolCall]
+    stop_reason: Literal["final", "tool_use", "max_tokens", "refused", "error"]
+    usage: Usage
+    model: str  # model that actually answered (may differ after a provider-side fallback)
+    error: str | None = None
+    provider_data: Any = None
+
+
+@dataclass(frozen=True)
+class ProviderCapabilities:
+    tool_calling: bool
+    structured_output: bool
+    max_context_tokens: int
+    data_stays_local: bool
+
+
+@runtime_checkable
+class AIProvider(Protocol):
+    name: str
+
+    def capabilities(self) -> ProviderCapabilities: ...
+
+    def complete(self, request: CompletionRequest) -> CompletionResponse: ...
+
+
+def error_response(model: str, message: str) -> CompletionResponse:
+    """Helper for plugins: report a failure instead of raising."""
+    return CompletionResponse(text=None, tool_calls=[], stop_reason="error", usage=Usage(), model=model, error=message)

devguard/ai/testing.py

@@ -0,0 +1,126 @@
+"""Contract checks for provider plugins (PLG-009).
+
+Plugin authors can run these from pytest:
+
+    from devguard.ai.testing import run_contract
+    def test_my_provider():
+        report = run_contract(make_provider({"model": "...", "api_key": "..."}), model="...")
+        assert report.ok, report.failures
+
+`devguard ai test --ai-profile NAME` runs the same checks against a configured profile. Only synthetic data
+is sent; no repository content.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from devguard.ai.sdk import (
+    AIProvider,
+    CompletionRequest,
+    CompletionResponse,
+    Message,
+    ProviderCapabilities,
+    ToolResult,
+    ToolSpec,
+)
+
+_ECHO_TOOL = ToolSpec(
+    name="lookup_rule",
+    description="Look up a rule by id and return its title.",
+    input_schema={
+        "type": "object",
+        "properties": {"rule_id": {"type": "string"}},
+        "required": ["rule_id"],
+        "additionalProperties": False,
+    },
+)
+
+
+@dataclass
+class ContractReport:
+    passed: list[str] = field(default_factory=list)
+    failures: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.failures
+
+
+def _req(model: str, messages: list[Message], tools: list[ToolSpec] | None = None) -> CompletionRequest:
+    return CompletionRequest(
+        messages=messages,
+        tools=tools or [],
+        output_schema=None,
+        model=model,
+        max_output_tokens=2000,
+        temperature=None,
+        timeout_s=90,
+    )
+
+
+def run_contract(provider: AIProvider, model: str) -> ContractReport:
+    r = ContractReport()
+    caps = provider.capabilities()
+    if not isinstance(caps, ProviderCapabilities):
+        r.failures.append("capabilities() must return ProviderCapabilities")
+        return r
+    r.passed.append("capabilities")
+
+    sys_msg = Message("system", "You are a test harness. Follow instructions exactly.")
+    resp = provider.complete(_req(model, [sys_msg, Message("user", 'Reply with the JSON object {"ok": true} only.')]))
+    if not isinstance(resp, CompletionResponse):
+        r.failures.append("complete() must return CompletionResponse")
+        return r
+    if resp.stop_reason == "error":
+        r.failures.append(f"plain completion failed: {resp.error}")
+        return r
+    try:
+        text = resp.text or ""
+        json.loads(text[text.find("{") : text.rfind("}") + 1])
+        r.passed.append("plain completion returns JSON when asked")
+    except ValueError:
+        r.notes.append("plain completion did not return clean JSON; the core will retry with feedback")
+
+    if caps.tool_calling:
+        msgs = [sys_msg, Message("user", "Call the lookup_rule tool with rule_id DG-TEST-001, then tell me the title.")]
+        first = provider.complete(_req(model, msgs, [_ECHO_TOOL]))
+        if not first.tool_calls:
+            r.failures.append(f"declared tool_calling but no tool call was returned (stop_reason={first.stop_reason})")
+        else:
+            call = first.tool_calls[0]
+            if call.name != "lookup_rule" or not isinstance(call.arguments, dict):
+                r.failures.append("tool call has wrong name or non-dict arguments")
+            msgs += [
+                Message("assistant", first.text or "", first.tool_calls, provider_data=first.provider_data),
+                Message("tool", tool_results=[ToolResult(c.id, "Title: Test rule") for c in first.tool_calls]),
+            ]
+            second = provider.complete(_req(model, msgs, [_ECHO_TOOL]))
+            if second.stop_reason == "error":
+                r.failures.append(f"tool-result round trip failed: {second.error}")
+            elif "test rule" not in (second.text or "").lower():
+                r.notes.append("model did not repeat the tool result; round trip technically succeeded")
+                r.passed.append("tool round trip")
+            else:
+                r.passed.append("tool round trip")
+    else:
+        r.notes.append("tool_calling=False: the core will use the prompted tool protocol")
+
+    bad = provider.complete(
+        CompletionRequest(
+            messages=[Message("user", "hi")],
+            tools=[],
+            output_schema=None,
+            model="devguard-nonexistent-model",
+            max_output_tokens=10,
+            temperature=None,
+            timeout_s=30,
+        )
+    )
+    if bad.stop_reason == "error":
+        r.passed.append("errors are returned, not raised")
+    else:
+        r.notes.append("unknown model did not produce an error (some gateways ignore the model name)")
+    return r