open-code-review-toolkit 0.6.2__tar.gz → 0.6.3__tar.gz

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.6.2
+Version: 0.6.3
 Summary: Unofficial GitLab CI integration layer for Open Code Review
 Project-URL: Homepage, https://github.com/xeonvs/open-code-review-toolkit
 Project-URL: Repository, https://github.com/xeonvs/open-code-review-toolkit
@@ -258,18 +258,13 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-After every current review note publishes, the GitLab adapter can add a
-conservative approval bound to the exact reviewed source SHA. This write is
-enabled by default; set `OCR_AUTO_APPROVE=false` before upgrading when the bot
-must remain comment-only. GitLab approval rules and protected-branch policy
-remain authoritative. The toolkit only adds an eligible approval; it never
-removes an existing approval when a later review is ineligible or disabled.
+After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v3's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata remains eligible, while degraded metadata, legacy receipts, any external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
 
 Accepted tradeoffs can be recorded in `.opencodereview/accepted-decisions.md`; the evidence collector supplies only applicable target-ref decisions and never lets a source change self-authorize its review. Root and nested target `AGENTS.md`/`CLAUDE.md` guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) and [Target project guidance](docs/configuration.md#target-project-guidance) for formats and trust boundaries.
 
 ## Project architecture
 
-The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Reviewed external stdio or native HTTPS MCP servers compose alongside it without replacing the built-in evidence boundary.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. GitLab MR reviews allow operator-configured external MCP only over remote HTTPS; developer-local execution may retain explicit stdio peers. Direct external MCP remains privileged operator configuration and comment-only; planned M5 external records use the separate toolkit-owned broker boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Roadmap](ROADMAP.md) - milestone status, dependencies, outcomes, and completion signals.

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/README.md

@@ -31,18 +31,13 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-After every current review note publishes, the GitLab adapter can add a
-conservative approval bound to the exact reviewed source SHA. This write is
-enabled by default; set `OCR_AUTO_APPROVE=false` before upgrading when the bot
-must remain comment-only. GitLab approval rules and protected-branch policy
-remain authoritative. The toolkit only adds an eligible approval; it never
-removes an existing approval when a later review is ineligible or disabled.
+After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v3's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata remains eligible, while degraded metadata, legacy receipts, any external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
 
 Accepted tradeoffs can be recorded in `.opencodereview/accepted-decisions.md`; the evidence collector supplies only applicable target-ref decisions and never lets a source change self-authorize its review. Root and nested target `AGENTS.md`/`CLAUDE.md` guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) and [Target project guidance](docs/configuration.md#target-project-guidance) for formats and trust boundaries.
 
 ## Project architecture
 
-The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Reviewed external stdio or native HTTPS MCP servers compose alongside it without replacing the built-in evidence boundary.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. GitLab MR reviews allow operator-configured external MCP only over remote HTTPS; developer-local execution may retain explicit stdio peers. Direct external MCP remains privileged operator configuration and comment-only; planned M5 external records use the separate toolkit-owned broker boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Roadmap](ROADMAP.md) - milestone status, dependencies, outcomes, and completion signals.

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/src/ocr_toolkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.2'
-__version_tuple__ = version_tuple = (0, 6, 2)
+__version__ = version = '0.6.3'
+__version_tuple__ = version_tuple = (0, 6, 3)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/src/ocr_toolkit/evidence/review_context.py

@@ -38,6 +38,22 @@ LABEL_STATUSES = frozenset(
     }
 )
 MAX_LABELS = 32
+CONTEXT_MODES = frozenset({"off", "metadata", "enriched"})
+
+
+class ReviewContextModeError(ValueError):
+    """Report an unsupported or unavailable review-context mode safely."""
+
+
+def parse_review_context_mode(raw: str | None) -> str:
+    """Return the closed context mode without echoing untrusted configuration."""
+
+    mode = (raw or "").strip().lower() or "off"
+    if mode not in CONTEXT_MODES:
+        raise ReviewContextModeError("OCR_REVIEW_CONTEXT_MODE is invalid")
+    if mode == "enriched":
+        raise ReviewContextModeError("OCR_REVIEW_CONTEXT_MODE=enriched is not available")
+    return mode or "off"
 
 
 def context_provenance(provider: str) -> str:
@@ -84,6 +100,21 @@ class MergeRequestContext:
         labels = self.fields.get("labels")
         return bool(isinstance(labels, Mapping) and labels.get("values"))
 
+    @property
+    def state(self) -> str:
+        """Return whether every selected metadata field is completely represented."""
+
+        complete_text = {"absent", "admitted"}
+        complete_labels = {"absent", "admitted"}
+        for name in ("title", "description", "source_branch"):
+            field = self.fields.get(name)
+            if not isinstance(field, Mapping) or field.get("status") not in complete_text:
+                return "degraded"
+        labels = self.fields.get("labels")
+        if not isinstance(labels, Mapping) or labels.get("status") not in complete_labels:
+            return "degraded"
+        return "complete"
+
     def evidence_value(self) -> dict[str, object]:
         """Return the closed persisted descriptor value."""
 

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/src/ocr_toolkit/mcp_config.py

@@ -35,6 +35,7 @@ SENSITIVE_HEADER_NAME_RE = re.compile(
 TRUE_VALUES = {"1", "true", "yes", "on"}
 FALSE_VALUES = {"0", "false", "no", "off", ""}
 BUILTIN_EVIDENCE_SERVER = "ocr_toolkit_evidence"
+MCP_PROFILES = frozenset({"local", "gitlab_mr"})
 
 
 class MCPConfigError(Exception):
@@ -64,6 +65,7 @@ class MCPCapability:
     server: str
     tools: tuple[str, ...]
     builtin: bool = False
+    transport: str = "stdio"
 
 
 @dataclass(frozen=True, slots=True)
@@ -93,6 +95,17 @@ def _string_list(value: Any, field: str, *, limit: int) -> list[str]:
     return result
 
 
+def _tool_names(value: Any, field: str) -> list[str]:
+    """Validate one explicit OCR-compatible tool-name allowlist."""
+
+    tools = _string_list(value, field, limit=MAX_MCP_TOOLS)
+    if any(not tool for tool in tools):
+        raise MCPConfigError(f"{field} must not contain empty tool names")
+    if len(set(tools)) != len(tools):
+        raise MCPConfigError(f"{field} must not contain duplicate tool names")
+    return tools
+
+
 def _env_assignments(value: Any, env_from: Any, server_name: str) -> tuple[list[str], list[str]]:
     """Build stdio environment assignments and collect values for redaction."""
 
@@ -187,6 +200,11 @@ def _headers(value: Any, env_from: Any, server_name: str) -> tuple[dict[str, str
             )
         if not isinstance(item, str):
             raise MCPConfigError(f"servers.{server_name}.headers.{name} must be a string")
+        if item.startswith("$") and MCP_ENV_NAME_RE.fullmatch(item[1:]):
+            raise MCPConfigError(
+                f"servers.{server_name}.headers.{name} resembles an environment reference; "
+                "use headers_from"
+            )
         if not item or len(item) > MAX_MCP_HEADER_VALUE_CHARS:
             raise MCPConfigError(
                 f"servers.{server_name}.headers.{name} must be non-empty and at most "
@@ -265,8 +283,11 @@ def _remote_url(value: Any, server_name: str) -> str:
     return value
 
 
-def parse_mcp_servers(raw: str | None = None) -> list[MCPServerConfig]:
-    """Return bounded stdio and remote configs from OCR_MCP_SERVERS_JSON."""
+def parse_mcp_servers(raw: str | None = None, *, profile: str = "local") -> list[MCPServerConfig]:
+    """Return bounded external configs admitted by one execution profile."""
+
+    if profile not in MCP_PROFILES:
+        raise MCPConfigError("internal MCP execution profile is invalid")
 
     raw = os.environ.get("OCR_MCP_SERVERS_JSON", "") if raw is None else raw
     raw = raw.strip()
@@ -329,7 +350,11 @@ def parse_mcp_servers(raw: str | None = None) -> list[MCPServerConfig]:
         transport = server.get("type", "stdio")
         if transport not in {"stdio", "remote"}:
             raise MCPConfigError(f"servers.{name}.type must be 'stdio' or 'remote'")
-        common_fields = {"name", "type", "enabled", "tools", "setup"}
+        if profile == "gitlab_mr" and transport != "remote":
+            raise MCPConfigError("GitLab merge-request reviews require external remote MCP")
+        common_fields = {"name", "type", "enabled", "tools"}
+        if transport == "stdio":
+            common_fields.add("setup")
         transport_fields = (
             {"command", "args", "env", "env_from"}
             if transport == "stdio"
@@ -340,7 +365,7 @@ def parse_mcp_servers(raw: str | None = None) -> list[MCPServerConfig]:
             fields = ", ".join(sorted(unknown_fields))
             raise MCPConfigError(f"servers.{name} has unsupported fields for {transport}: {fields}")
 
-        tools = _string_list(server.get("tools", []), f"servers.{name}.tools", limit=MAX_MCP_TOOLS)
+        tools = _tool_names(server.get("tools", []), f"servers.{name}.tools")
         if not tools:
             raise MCPConfigError(f"servers.{name}.tools must explicitly allow at least one tool")
         if TOOL_NAME in tools:
@@ -404,28 +429,98 @@ def _replace_configured_servers() -> bool:
     raise MCPConfigError("OCR_MCP_REPLACE must be a boolean (true/false, 1/0, yes/no, or on/off)")
 
 
-def _existing_capability(name: str, value: Any) -> MCPCapability:
-    """Validate the safe capability fields of one existing OCR MCP entry."""
+def _existing_server(
+    name: str, value: Any, *, profile: str
+) -> tuple[dict[str, Any], MCPCapability, tuple[str, ...]]:
+    """Revalidate one inherited OCR MCP entry through the active exact schema."""
 
     if not isinstance(name, str) or not MCP_NAME_RE.fullmatch(name):
         raise MCPConfigError("Existing OCR MCP server name is invalid")
     if not isinstance(value, dict):
         raise MCPConfigError(f"Existing OCR MCP server {name!r} is not a JSON object")
-    tools = _string_list(value.get("tools", []), f"existing.{name}.tools", limit=MAX_MCP_TOOLS)
-    if not tools:
-        raise MCPConfigError(
-            f"Existing OCR MCP server {name!r} must explicitly allow at least one tool"
+    if name == BUILTIN_EVIDENCE_SERVER:
+        raise MCPConfigError("the toolkit-owned MCP server cannot be inherited")
+    normalized = dict(value)
+    transport = normalized.get("type", "stdio")
+    # Toolkit <=0.6.2 persisted an empty setup key for every remote entry.
+    # Normalize only that exact legacy no-op; non-empty inherited setup remains
+    # invalid and new remote input never admits the field.
+    if transport == "remote" and normalized.get("setup") == "":
+        normalized.pop("setup")
+    if transport == "stdio" and isinstance(normalized.get("env"), list):
+        environment: dict[str, str] = {}
+        for assignment in normalized["env"]:
+            if not isinstance(assignment, str) or "=" not in assignment:
+                raise MCPConfigError(f"Existing OCR MCP server {name!r} has invalid env")
+            key, item = assignment.split("=", 1)
+            if key in environment:
+                raise MCPConfigError(f"Existing OCR MCP server {name!r} has duplicate env name")
+            environment[key] = item
+        normalized["env"] = environment
+    elif transport == "remote" and isinstance(normalized.get("headers"), dict):
+        literal_headers: dict[str, object] = {}
+        headers_from: dict[str, str] = {}
+        for header, item in normalized["headers"].items():
+            source = item[1:] if isinstance(item, str) and item.startswith("$") else ""
+            if source and MCP_ENV_NAME_RE.fullmatch(source):
+                headers_from[header] = source
+            else:
+                literal_headers[header] = item
+        if literal_headers:
+            normalized["headers"] = literal_headers
+        else:
+            normalized.pop("headers", None)
+        if headers_from:
+            inherited_sources = normalized.get("headers_from")
+            if inherited_sources is None:
+                normalized["headers_from"] = headers_from
+            elif isinstance(inherited_sources, dict):
+                normalized_names = {str(header).casefold() for header in inherited_sources}
+                if any(header.casefold() in normalized_names for header in headers_from):
+                    raise MCPConfigError(
+                        f"Existing OCR MCP server {name!r} has duplicate header sources"
+                    )
+                normalized["headers_from"] = {**inherited_sources, **headers_from}
+    raw = json.dumps({name: normalized}, separators=(",", ":"), ensure_ascii=False)
+    parsed = parse_mcp_servers(raw, profile=profile)
+    if len(parsed) != 1:
+        raise MCPConfigError(f"Existing OCR MCP server {name!r} is disabled or invalid")
+    server = parsed[0]
+    payload: dict[str, Any] = {
+        "type": server.transport,
+        "tools": server.tools,
+    }
+    if server.transport == "stdio":
+        payload.update(
+            {
+                "command": server.command,
+                "args": server.args,
+                "env": server.env,
+                "setup": server.setup,
+            }
         )
-    if TOOL_NAME in tools:
-        raise MCPConfigError(f"Existing MCP tool name {TOOL_NAME!r} is reserved by the toolkit")
-    return MCPCapability(name, tuple(tools))
+    else:
+        payload.update({"url": server.url, "headers": server.headers})
+    return (
+        payload,
+        MCPCapability(server.name, tuple(server.tools), transport=server.transport),
+        tuple(server.secret_values),
+    )
 
 
-def compose_mcp_servers(servers: list[MCPServerConfig], *, replace: bool) -> MCPComposition:
+def compose_mcp_servers(
+    servers: list[MCPServerConfig], *, replace: bool, profile: str = "local"
+) -> MCPComposition:
     """Build OCR's registry from independent optional and mandatory MCP entries."""
 
+    if profile not in MCP_PROFILES:
+        raise MCPConfigError("internal MCP execution profile is invalid")
+    if profile == "gitlab_mr" and any(server.transport != "remote" for server in servers):
+        raise MCPConfigError("GitLab merge-request reviews require external remote MCP")
+
     payload: dict[str, dict[str, Any]] = {}
     capabilities: list[MCPCapability] = []
+    secret_values: list[str] = []
     if not replace:
         try:
             current = read_ocr_config().get("mcp_servers", {})
@@ -433,20 +528,26 @@ def compose_mcp_servers(servers: list[MCPServerConfig], *, replace: bool) -> MCP
             raise MCPConfigError(str(exc)) from exc
         if not isinstance(current, dict):
             raise MCPConfigError("Existing OCR mcp_servers value is not a JSON object")
+        declared_names = {server.name for server in servers}
         for name, value in current.items():
-            if name == BUILTIN_EVIDENCE_SERVER:
+            # Explicit operator input replaces the same named inherited entry;
+            # validate only the state that will survive into the final registry.
+            if name == BUILTIN_EVIDENCE_SERVER or name in declared_names:
                 continue
-            capability = _existing_capability(name, value)
-            payload[name] = value
+            inherited, capability, inherited_secrets = _existing_server(
+                name, value, profile=profile
+            )
+            payload[name] = inherited
             capabilities.append(capability)
+            secret_values.extend(inherited_secrets)
 
-    secret_values: list[str] = []
     for server in servers:
         payload[server.name] = {
             "type": server.transport,
-            "setup": server.setup,
             "tools": server.tools,
         }
+        if server.transport == "stdio":
+            payload[server.name]["setup"] = server.setup
         if server.transport == "stdio":
             payload[server.name].update(
                 {"command": server.command, "args": server.args, "env": server.env}
@@ -454,7 +555,7 @@ def compose_mcp_servers(servers: list[MCPServerConfig], *, replace: bool) -> MCP
         else:
             payload[server.name].update({"url": server.url, "headers": server.headers})
         secret_values.extend(server.secret_values)
-        capability = MCPCapability(server.name, tuple(server.tools))
+        capability = MCPCapability(server.name, tuple(server.tools), transport=server.transport)
         capabilities = [item for item in capabilities if item.server != server.name]
         capabilities.append(capability)
 
@@ -497,10 +598,14 @@ def compose_mcp_servers(servers: list[MCPServerConfig], *, replace: bool) -> MCP
     )
 
 
-def build_mcp_composition() -> MCPComposition:
-    """Parse environment settings into the complete OCR MCP composition."""
+def build_mcp_composition(*, profile: str = "local") -> MCPComposition:
+    """Parse environment settings into the complete profiled MCP composition."""
 
-    return compose_mcp_servers(parse_mcp_servers(), replace=_replace_configured_servers())
+    return compose_mcp_servers(
+        parse_mcp_servers(profile=profile),
+        replace=_replace_configured_servers(),
+        profile=profile,
+    )
 
 
 def apply_mcp_composition(composition: MCPComposition) -> None:

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/src/ocr_toolkit/ocr_result.py

@@ -18,11 +18,13 @@ from ocr_toolkit.common.redaction import sanitize_ocr_value
 DEFAULT_MAX_RESULT_BYTES = 2_000_000
 MAX_RESULT_BYTES_HARD_LIMIT = 20_000_000
 TOOLKIT_RESULT_KEY = "_ocr_toolkit"
-TOOLKIT_RESULT_SCHEMA_VERSION = 2
-SUPPORTED_TOOLKIT_RESULT_SCHEMA_VERSIONS = frozenset({1, TOOLKIT_RESULT_SCHEMA_VERSION})
-AUTOMATIC_APPROVAL_BLOCK_REASON = "author-controlled merge-request context was admitted"
+TOOLKIT_RESULT_SCHEMA_VERSION = 3
+SUPPORTED_TOOLKIT_RESULT_SCHEMA_VERSIONS = frozenset({1, 2, TOOLKIT_RESULT_SCHEMA_VERSION})
 # The receipt can name the 16 configured external servers plus the mandatory built-in.
 MAX_TOOLKIT_MCP_USAGE_SERVERS = 17
+MAX_TOOLKIT_MCP_TOOLS_PER_SERVER = 128
+MAX_TOOLKIT_MCP_TOOL_NAME_CHARS = 4_096
+MAX_TOOLKIT_MCP_USAGE_COUNT = 1_000_000_000
 TOOLKIT_MCP_SERVER_NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
 
 

open_code_review_toolkit-0.6.3/src/ocr_toolkit/posting/approval.py

@@ -0,0 +1,266 @@
+"""Conservative policy and typed outcomes for GitLab automatic approval."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from ocr_toolkit.ocr_result import (
+    MAX_TOOLKIT_MCP_TOOL_NAME_CHARS,
+    MAX_TOOLKIT_MCP_TOOLS_PER_SERVER,
+    MAX_TOOLKIT_MCP_USAGE_COUNT,
+    MAX_TOOLKIT_MCP_USAGE_SERVERS,
+    TOOLKIT_MCP_SERVER_NAME_RE,
+)
+from ocr_toolkit.posting.settings import BooleanSetting
+from ocr_toolkit.result_contract import ReviewOutcome
+
+ALLOWED_CATEGORIES = frozenset({"style", "documentation", "maintainability"})
+MAX_APPROVABLE_FINDINGS = 3
+
+
+class ApprovalStatus(str, Enum):
+    """Closed public states for one automatic-approval transaction."""
+
+    APPROVED = "approved"
+    NOT_ELIGIBLE = "not eligible"
+    DISABLED = "disabled"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalResult:
+    """Bounded status rendered in the review summary and runner log."""
+
+    status: ApprovalStatus
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalEligibility:
+    """Policy conclusion before provider state is consulted."""
+
+    eligible: bool
+    result: ApprovalResult
+
+
+def evaluate_approval_policy(
+    setting: BooleanSetting,
+    outcome: ReviewOutcome,
+    comments: list[dict[str, Any]],
+    warnings: list[Any],
+    omitted_count: int,
+    toolkit_metadata: Any = None,
+) -> ApprovalEligibility:
+    """Evaluate the fixed v0.4.7 policy from authoritative OCR data."""
+
+    if not setting.enabled:
+        reason = (
+            "configuration was invalid and failed closed"
+            if not setting.valid
+            else "disabled by OCR_AUTO_APPROVE"
+        )
+        return ApprovalEligibility(
+            False,
+            ApprovalResult(ApprovalStatus.DISABLED, reason),
+        )
+    metadata_reason = automatic_approval_metadata_reason(toolkit_metadata)
+    if metadata_reason:
+        reason = metadata_reason
+    elif toolkit_metadata["evidence"]["mandatory"] is not outcome.requires_evidence_mcp:
+        reason = "the review-time approval receipt is missing or invalid"
+    elif not outcome.manifest_present:
+        reason = "the OCR result has no authoritative coverage manifest"
+    elif outcome.kind != "clean" or outcome.budget_exceeded:
+        reason = "the OCR review did not complete cleanly"
+    elif outcome.failed_count or outcome.waived_count:
+        reason = "coverage contained failed or waived items"
+    elif warnings:
+        reason = "the OCR review reported warnings"
+    elif omitted_count:
+        reason = "one or more findings were omitted from publication"
+    elif len(comments) > MAX_APPROVABLE_FINDINGS:
+        reason = f"the review reported more than {MAX_APPROVABLE_FINDINGS} findings"
+    else:
+        reason = ""
+
+    if reason:
+        return ApprovalEligibility(
+            False,
+            ApprovalResult(ApprovalStatus.NOT_ELIGIBLE, reason),
+        )
+
+    for comment in comments:
+        severity = comment.get("severity")
+        category = comment.get("category")
+        if severity != "low":
+            return ApprovalEligibility(
+                False,
+                ApprovalResult(
+                    ApprovalStatus.NOT_ELIGIBLE,
+                    "a finding had a blocking or malformed severity",
+                ),
+            )
+        if not isinstance(category, str) or category not in ALLOWED_CATEGORIES:
+            return ApprovalEligibility(
+                False,
+                ApprovalResult(
+                    ApprovalStatus.NOT_ELIGIBLE,
+                    "a finding had a blocking or malformed category",
+                ),
+            )
+
+    return ApprovalEligibility(
+        True,
+        ApprovalResult(
+            ApprovalStatus.SKIPPED,
+            "awaiting post-publication SHA verification",
+        ),
+    )
+
+
+def approval_summary_line(result: ApprovalResult) -> str:
+    """Render exactly one bounded automatic-approval state line."""
+
+    return f"- Automatic approval: `{result.status.value}` — {result.reason}."
+
+
+def provisional_approval_result(eligibility: ApprovalEligibility) -> ApprovalResult:
+    """Return a fail-closed state safe to publish before provider readback."""
+
+    if not eligibility.eligible:
+        return eligibility.result
+    return ApprovalResult(
+        ApprovalStatus.FAILED,
+        "automatic approval has not yet been confirmed",
+    )
+
+
+def _full_sha(value: Any) -> bool:
+    return (
+        isinstance(value, str)
+        and len(value) == 40
+        and all(char in "0123456789abcdef" for char in value)
+    )
+
+
+def _positive_id(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
+    """Return the closed review-time receipt blocker for automatic approval."""
+
+    invalid = "the review-time approval receipt is missing or invalid"
+    if not isinstance(toolkit_metadata, dict):
+        return invalid
+    schema_version = toolkit_metadata.get("schema_version")
+    if schema_version in {1, 2}:
+        return "the review-time approval receipt predates current eligibility controls"
+    if schema_version != 3 or set(toolkit_metadata) != {
+        "schema_version",
+        "review",
+        "context",
+        "mcp",
+        "evidence",
+    }:
+        return invalid
+
+    review = toolkit_metadata.get("review")
+    if not isinstance(review, dict) or set(review) != {"source_sha", "policy_sha", "mr_author_id"}:
+        return invalid
+    if not _full_sha(review.get("source_sha")) or not _full_sha(review.get("policy_sha")):
+        return invalid
+    if not _positive_id(review.get("mr_author_id")):
+        return invalid
+
+    context = toolkit_metadata.get("context")
+    if not isinstance(context, dict) or set(context) != {"mode", "state", "classes"}:
+        return invalid
+    mode = context.get("mode")
+    state = context.get("state")
+    classes = context.get("classes")
+    expected_classes = [] if mode == "off" else ["merge_request_metadata"]
+    if (
+        mode not in {"off", "metadata"}
+        or state not in {"disabled", "complete", "degraded"}
+        or classes != expected_classes
+        or (mode == "off" and state != "disabled")
+        or (mode == "metadata" and state == "disabled")
+    ):
+        return invalid
+
+    mcp = toolkit_metadata.get("mcp")
+    if not isinstance(mcp, dict) or set(mcp) != {"capabilities", "usage"}:
+        return invalid
+    capabilities = mcp.get("capabilities")
+    usage = mcp.get("usage")
+    if (
+        not isinstance(capabilities, list)
+        or not 1 <= len(capabilities) <= MAX_TOOLKIT_MCP_USAGE_SERVERS
+        or not isinstance(usage, dict)
+        or len(usage) > MAX_TOOLKIT_MCP_USAGE_SERVERS
+    ):
+        return invalid
+    servers: set[str] = set()
+    tool_owners: set[str] = set()
+    external = False
+    builtin_server = "ocr_toolkit_evidence"
+    for capability in capabilities:
+        if not isinstance(capability, dict) or set(capability) != {"server", "transport", "tools"}:
+            return invalid
+        server = capability.get("server")
+        transport = capability.get("transport")
+        tools = capability.get("tools")
+        if (
+            not isinstance(server, str)
+            or TOOLKIT_MCP_SERVER_NAME_RE.fullmatch(server) is None
+            or server in servers
+            or transport not in {"builtin", "stdio", "remote"}
+            or not isinstance(tools, list)
+            or not 1 <= len(tools) <= MAX_TOOLKIT_MCP_TOOLS_PER_SERVER
+            or any(
+                not isinstance(tool, str) or not tool or len(tool) > MAX_TOOLKIT_MCP_TOOL_NAME_CHARS
+                for tool in tools
+            )
+            or len(set(tools)) != len(tools)
+            or any(tool in tool_owners for tool in tools)
+            or (server == builtin_server) != (transport == "builtin")
+            or (server == builtin_server and tools != [builtin_server])
+        ):
+            return invalid
+        servers.add(server)
+        tool_owners.update(tools)
+        external = external or server != builtin_server
+    if builtin_server not in servers:
+        return invalid
+    if any(
+        not isinstance(server, str)
+        or server not in servers
+        or not isinstance(count, int)
+        or isinstance(count, bool)
+        or not 0 < count <= MAX_TOOLKIT_MCP_USAGE_COUNT
+        for server, count in usage.items()
+    ):
+        return invalid
+
+    evidence = toolkit_metadata.get("evidence")
+    if not isinstance(evidence, dict) or set(evidence) != {"mandatory", "used"}:
+        return invalid
+    mandatory = evidence.get("mandatory")
+    used = evidence.get("used")
+    evidence_called = usage.get(builtin_server, 0) > 0
+    if (
+        not isinstance(mandatory, bool)
+        or not isinstance(used, bool)
+        or used is not evidence_called
+        or (mandatory and not used)
+    ):
+        return invalid
+    if context.get("state") == "degraded":
+        return "the selected review context was degraded"
+    if external:
+        return "external MCP was configured for a comment-only review"
+    return ""

{open_code_review_toolkit-0.6.2 → open_code_review_toolkit-0.6.3}/src/ocr_toolkit/posting/formatting.py

@@ -488,7 +488,11 @@ def format_mcp_usage_summary(toolkit_metadata: Any) -> str:
         or toolkit_metadata.get("schema_version") not in SUPPORTED_TOOLKIT_RESULT_SCHEMA_VERSIONS
     ):
         return ""
-    mcp_usage = toolkit_metadata.get("mcp_usage")
+    if toolkit_metadata.get("schema_version") == 3:
+        mcp = toolkit_metadata.get("mcp")
+        mcp_usage = mcp.get("usage") if isinstance(mcp, dict) else None
+    else:
+        mcp_usage = toolkit_metadata.get("mcp_usage")
     if not isinstance(mcp_usage, dict):
         return ""
     used: list[tuple[str, int]] = []