open-code-review-toolkit 0.4.5__tar.gz → 0.4.7__tar.gz

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.4.5
+Version: 0.4.7
 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
@@ -243,7 +243,7 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.8`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.9.1`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 
@@ -255,11 +255,18 @@ 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.
+
 Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the evidence collector supplies target-ref decisions to OCR and never lets a source change self-authorize its own review. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
 
-## Project development
+## Project architecture
 
-The project is evolving from bounded background generation toward a shared Repository Evidence Engine: one deterministic evidence model will support both a compact OCR bootstrap and a built-in read-only MCP server. Development is ordered by outcomes and dependencies rather than speculative dates.
+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 evidence 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.
 
 - [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.
@@ -283,7 +290,7 @@ See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gi
 
 ## Configuration and safety
 
-Configuration is environment-only in v0.1. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
+Configuration is environment-driven. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
 
 Repository content, OCR output, and provider responses are untrusted inputs. The toolkit applies bounded reads and writes, secret redaction, Unicode normalization, Markdown/quick-action neutralization, fingerprinted comments, ownership boundaries for human replies, and rollback controls. Review the [security and trust model](docs/security.md) before enabling write access.
 

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/README.md

@@ -17,7 +17,7 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.8`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.9.1`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 
@@ -29,11 +29,18 @@ 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.
+
 Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the evidence collector supplies target-ref decisions to OCR and never lets a source change self-authorize its own review. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
 
-## Project development
+## Project architecture
 
-The project is evolving from bounded background generation toward a shared Repository Evidence Engine: one deterministic evidence model will support both a compact OCR bootstrap and a built-in read-only MCP server. Development is ordered by outcomes and dependencies rather than speculative dates.
+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 evidence 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.
 
 - [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.
@@ -57,7 +64,7 @@ See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gi
 
 ## Configuration and safety
 
-Configuration is environment-only in v0.1. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
+Configuration is environment-driven. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
 
 Repository content, OCR output, and provider responses are untrusted inputs. The toolkit applies bounded reads and writes, secret redaction, Unicode normalization, Markdown/quick-action neutralization, fingerprinted comments, ownership boundaries for human replies, and rollback controls. Review the [security and trust model](docs/security.md) before enabling write access.
 

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/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.4.5'
-__version_tuple__ = version_tuple = (0, 4, 5)
+__version__ = version = '0.4.7'
+__version_tuple__ = version_tuple = (0, 4, 7)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/src/ocr_toolkit/evidence/mcp.py

@@ -106,7 +106,7 @@ def _optional_filter(arguments: dict[str, object], name: str) -> str | None:
 
 
 def _encode_cursor(offset: int, query: _Query) -> str:
-    """Encode an opaque, tamper-evident pagination position."""
+    """Encode an opaque, query-bound self-validating pagination position."""
 
     state = f"{offset}:{query.key()}"
     checksum = hashlib.sha256(f"ocr-evidence-v1:{state}".encode()).hexdigest()[:16]

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

@@ -0,0 +1,125 @@
+"""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.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,
+) -> 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),
+        )
+    if 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",
+    )

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/src/ocr_toolkit/posting/formatting.py

@@ -17,6 +17,7 @@ from ocr_toolkit.common.markdown import (
 )
 from ocr_toolkit.common.redaction import redact_sensitive
 from ocr_toolkit.ocr_result import TOOLKIT_RESULT_SCHEMA_VERSION
+from ocr_toolkit.posting.approval import ApprovalResult, approval_summary_line
 from ocr_toolkit.posting.comments import (
     clean_text,
     code_text,
@@ -34,14 +35,13 @@ from ocr_toolkit.posting.settings import (
     MAX_REVIEWER_GUIDE_LABEL_CHARS,
     MAX_REVIEWER_GUIDE_LOCATION_CHARS,
     MAX_REVIEWER_GUIDE_TEXT_CHARS,
-    MAX_SUGGESTION_CODE_CHARS,
-    MAX_SUGGESTION_SPAN_LINES,
     MAX_TOOL_CALL_NAME_CHARS,
     MAX_TOOL_CALL_SUMMARY_TOOLS,
     SUGGESTION_HEADER,
     post_emoji,
     post_mode,
 )
+from ocr_toolkit.posting.suggestions import SuggestionDecision, SuggestionState
 
 OCR_FINDING_CATEGORIES = {
     "bug",
@@ -85,22 +85,6 @@ CATEGORY_EMOJI = {
 }
 
 
-def suggestion_range_suffix(comment: dict[str, Any]) -> str:
-    """Return a GitLab suggestion range suffix."""
-
-    end_line = line_number(comment.get("end_line") or comment.get("line"))
-    start_line = line_number(comment.get("start_line") or comment.get("line") or end_line)
-
-    if start_line <= 0 or end_line <= 0 or start_line > end_line:
-        return ""
-
-    span = end_line - start_line
-    if span > MAX_SUGGESTION_SPAN_LINES:
-        return ""
-
-    return f"-0+{span}"
-
-
 def inline_code(value: str) -> str:
     """Return a Markdown inline-code representation safe for backticks."""
 
@@ -136,34 +120,33 @@ def format_finding_tags(comment: dict[str, Any], *, emoji: bool | None = None) -
     return " · ".join(tags)
 
 
-def format_suggestion_block(comment: dict[str, Any]) -> str:
-    """Return a GitLab suggestion block if OCR supplied replacement code."""
+def format_suggestion_block(decision: SuggestionDecision) -> str:
+    """Render one previously validated GitLab suggestion decision."""
 
-    suggestion = code_text(comment.get("suggestion_code"))
-    if not suggestion.strip() or comment.get("_ocr_suggestion_noop") is True:
-        return ""
-
-    if "```" in suggestion:
+    if decision.state in {SuggestionState.ABSENT, SuggestionState.NO_OP}:
         return ""
+    if decision.state is SuggestionState.OMITTED:
+        return f"\n\nSuggestion block was omitted because {decision.omission_message}."
+    return (
+        f"\n\n{SUGGESTION_HEADER}\n```suggestion:{decision.range_suffix}\n"
+        f"{decision.replacement}\n```"
+    )
 
-    if any(line.lstrip().startswith("/") for line in suggestion.splitlines()):
-        return ""
 
-    if len(suggestion) > MAX_SUGGESTION_CODE_CHARS:
-        return (
-            "\n\nSuggestion block was omitted because the generated replacement "
-            "was too large to publish safely."
-        )
+def format_suggestion_omission(decision: SuggestionDecision) -> str:
+    """Render a bounded explanation for a withheld actionable suggestion."""
 
-    range_suffix = suggestion_range_suffix(comment)
-    if not range_suffix:
+    if decision.state is not SuggestionState.OMITTED:
         return ""
-
-    return f"\n\n{SUGGESTION_HEADER}\n```suggestion:{range_suffix}\n{suggestion}\n```"
+    return f"\n\nSuggestion block was omitted because {decision.omission_message}."
 
 
 def format_inline_comment(
-    comment: dict[str, Any], include_suggestion: bool = True, *, emoji: bool | None = None
+    comment: dict[str, Any],
+    include_suggestion: bool = True,
+    *,
+    suggestion_decision: SuggestionDecision | None = None,
+    emoji: bool | None = None,
 ) -> str:
     """Format one OCR comment as Markdown for an inline GitLab discussion."""
 
@@ -173,12 +156,19 @@ def format_inline_comment(
     tags = format_finding_tags(comment, emoji=emoji)
     body = f"{tags}\n\n{content}" if tags else content
     if include_suggestion:
-        body += format_suggestion_block(comment)
+        body += format_suggestion_block(
+            suggestion_decision or SuggestionDecision(SuggestionState.ABSENT)
+        )
 
     return body
 
 
-def format_fallback_comment(comment: dict[str, Any], *, emoji: bool | None = None) -> str:
+def format_fallback_comment(
+    comment: dict[str, Any],
+    *,
+    suggestion_decision: SuggestionDecision | None = None,
+    emoji: bool | None = None,
+) -> str:
     """Format an OCR comment for a fallback non-inline MR note."""
 
     path = clean_text(comment.get("path")) or "unknown"
@@ -202,10 +192,13 @@ def format_fallback_comment(comment: dict[str, Any], *, emoji: bool | None = Non
         f"{format_inline_comment(comment, include_suggestion=False, emoji=emoji)}"
     )
 
+    decision = suggestion_decision or SuggestionDecision(SuggestionState.ABSENT)
+    body += format_suggestion_omission(decision)
+
     existing = code_text(comment.get("existing_code"))
     suggestion = code_text(comment.get("suggestion_code"))
 
-    if existing.strip() and suggestion.strip() and comment.get("_ocr_suggestion_noop") is not True:
+    if existing.strip() and suggestion.strip() and decision.state is not SuggestionState.NO_OP:
         body += "\n\n<details><summary>Suggested change details</summary>\n\n"
         body += "**Before:**\n"
         body += markdown_code_block(
@@ -228,16 +221,23 @@ def format_fallback_comment(comment: dict[str, Any], *, emoji: bool | None = Non
 
 
 def format_fallback_comment_chunks(
-    comments: Sequence[dict[str, Any]], *, emoji: bool | None = None
+    comments: Sequence[tuple[dict[str, Any], SuggestionDecision]],
+    *,
+    emoji: bool | None = None,
 ) -> list[str]:
     """Split fallback comments into safe chunks before publishing MR notes."""
 
     chunks: list[str] = []
     current = ""
 
-    for comment in comments:
+    for comment, suggestion_decision in comments:
         item = truncate_note_body(
-            format_fallback_comment(comment, emoji=emoji), max_chars=FALLBACK_NOTE_CHUNK_BUDGET
+            format_fallback_comment(
+                comment,
+                suggestion_decision=suggestion_decision,
+                emoji=emoji,
+            ),
+            max_chars=FALLBACK_NOTE_CHUNK_BUDGET,
         )
         separator = "\n\n---\n\n" if current else ""
 
@@ -776,6 +776,7 @@ def summarize_result(
     coverage_diagnostics: CoverageDiagnostics | None = None,
     warnings: Sequence[Any] = (),
     suppressed_count: int = 0,
+    approval_result: ApprovalResult | None = None,
     emoji: bool | None = None,
 ) -> str:
     """Build one decision-first summary for every validated OCR outcome."""
@@ -892,6 +893,8 @@ def summarize_result(
     technical.append(
         f"- Posting: {inline_count} inline, {fallback_count} fallback, {omitted_count} omitted"
     )
+    if approval_result is not None:
+        technical.append(approval_summary_line(approval_result))
     if suppressed_count:
         technical.append(f"- Reviewer suppression: {suppressed_count}")
     if coverage_summary:

{open_code_review_toolkit-0.4.5 → open_code_review_toolkit-0.4.7}/src/ocr_toolkit/posting/gitlab.py

@@ -58,6 +58,7 @@ class GitLabWriteResult:
 
     status: str
     response: Any | None = None
+    http_status: int | None = None
 
     @property
     def posted(self) -> bool:
@@ -282,7 +283,7 @@ def api_write_url_detailed(
         print(f"GitLab API error {exc.code} for {method} {url}: {safe_body}", file=sys.stderr)
         if _is_invalid_position_error(exc.code, raw_body):
             return GitLabWriteResult("invalid_position")
-        return GitLabWriteResult("write_failed")
+        return GitLabWriteResult("write_failed", http_status=exc.code)
     except GitLabResponseTooLarge as exc:
         print(f"GitLab API response too large for {method} {url}: {exc}", file=sys.stderr)
         return GitLabWriteResult("write_failed")
@@ -515,6 +516,29 @@ def delete_plain_note(config: GitLabConfig, note_id: int) -> bool:
     return response is not None
 
 
+def update_plain_note(config: GitLabConfig, note_id: int, body: str) -> GitLabWriteResult:
+    """Update one known toolkit-owned summary without retrying the write."""
+
+    return api_write_url_detailed(
+        url=f"{config.api_base}/notes/{note_id}",
+        api_token=config.api_token,
+        auth_header=config.auth_header,
+        data={"body": build_marked_note_body(body)},
+        method="PUT",
+    )
+
+
+def approve_merge_request(config: GitLabConfig, sha: str) -> GitLabWriteResult:
+    """Approve exactly one merge-request head without retrying the write."""
+
+    return api_write_url_detailed(
+        url=f"{config.api_base}/approve",
+        api_token=config.api_token,
+        auth_header=config.auth_header,
+        data={"sha": sha},
+    )
+
+
 def delete_discussion_note(config: GitLabConfig, discussion_id: str, note_id: int) -> bool:
     """Delete a note inside a merge request discussion thread."""