open-code-review-toolkit 0.9.0__tar.gz → 0.10.0__tar.gz

{open_code_review_toolkit-0.9.0 → open_code_review_toolkit-0.10.0}/.gitignore

@@ -12,6 +12,7 @@ build/
 dist/
 .review-context/
 .quality-logs/
+.tgrep-index/
 .idea/
 *.log
 .codex

{open_code_review_toolkit-0.9.0 → open_code_review_toolkit-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.9.0
+Version: 0.10.0
 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
@@ -234,7 +234,7 @@ Description-Content-Type: text/markdown
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/xeonvs/open-code-review-toolkit/badge)](https://securityscorecards.dev/viewer/?uri=github.com/xeonvs/open-code-review-toolkit)
 [![CodeQL](https://github.com/xeonvs/open-code-review-toolkit/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/xeonvs/open-code-review-toolkit/actions/workflows/codeql.yml)
 
-Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
+Open Code Review Toolkit is an unofficial review control and integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review), with GitLab CI and standalone local providers. It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, local Markdown reports, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
 
 > [!NOTE]
 > The project is under active development; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
@@ -257,13 +257,12 @@ python -m venv .venv
 python -m pip install open-code-review-toolkit
 ```
 
-The toolkit does not bundle OCR. Download the platform asset for exact
-[Open Code Review 1.11.3](https://github.com/alibaba/open-code-review/releases/tag/v1.11.3),
-verify it before installation against the [compatibility manifest](compatibility/ocr-support.json),
-and place the verified binary on `PATH`. The current Linux amd64 digest is
-`9726204ac81baee153fd65b1ff357c380f73e9d8091c4a73c3c9fb541b5164cb`; Darwin arm64 is
-`515cd92ce300b62dea2bcaf53e910cdf57b681e1d58bbd0a9e8e49617bca52fa`. The manifest owns
-the other platform hashes.
+The toolkit does not bundle OCR. Use `recommended_version` in the
+[compatibility manifest](compatibility/ocr-support.json) for this toolkit revision
+to select the exact [upstream release](https://github.com/alibaba/open-code-review/releases).
+Download its platform asset, verify it against that release entry's asset SHA-256,
+and place the verified binary on `PATH`. Do not substitute the latest upstream
+release or use another toolkit revision's manifest.
 
 Verify the installation without contacting an LLM provider:
 
@@ -272,18 +271,41 @@ ocr --version
 ocr-ci --help
 ```
 
-`ocr --version` must report `open-code-review v1.11.3`; `ocr-ci --help` must exit
+`ocr --version` must report the manifest's exact `recommended_version`; `ocr-ci --help` must exit
 successfully. `ocr-ci preflight` is an operational configuration check, not the installation
 smoke test.
 
 The exact recommended OCR release and its verified asset checksums live in the [versioned compatibility manifest](compatibility/ocr-support.json). CI should pin that release and 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`.
-The current OCR 1.11.3 integration defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
+The toolkit defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
-## How reviews evolve
+## Standalone local quick start
+
+With the qualified OCR binary and LLM environment configured, review an immutable
+commit without forge credentials:
+
+```console
+ocr-ci preflight --local
+ocr-ci review --local --result review.json --stderr review.stderr --report review.md -- --commit HEAD
+```
+
+Local execution uses the same OCR, mandatory evidence MCP, validation and DLP
+pipeline as CI. It publishes every admitted finding to a fresh private Markdown
+file and the console, without GitLab acquisition, suppression, approval or a
+fabricated publication receipt. See [local review](docs/local.md) for ranges,
+failure behavior and optional private `--debug-dir` bundles.
+
+Optional [reasoning and progress controls](docs/configuration.md#provider-endpoint-and-completion-cap-contract)
+do not change review rounds or budgets. Reasoning is unset by default; explicit
+`none` is a wire value whose support depends on the provider/model. Progress is
+off by default and emits only bounded toolkit phases to an interactive terminal
+or an explicitly nonblocking embedding stream; a conventional CI stderr pipe is
+intentionally not used because it can block a review.
+
+## How GitLab reviews evolve
 
 On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` or `@<live-bot-username> suppress` to keep a discussion open without future repeats; use the corresponding `resolve` command to resolve it after the next successful posting transaction. For example, a bot named `mr.bot` accepts the exact reply `@mr.bot resolve`.
 

{open_code_review_toolkit-0.9.0 → open_code_review_toolkit-0.10.0}/README.md

@@ -7,7 +7,7 @@
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/xeonvs/open-code-review-toolkit/badge)](https://securityscorecards.dev/viewer/?uri=github.com/xeonvs/open-code-review-toolkit)
 [![CodeQL](https://github.com/xeonvs/open-code-review-toolkit/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/xeonvs/open-code-review-toolkit/actions/workflows/codeql.yml)
 
-Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
+Open Code Review Toolkit is an unofficial review control and integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review), with GitLab CI and standalone local providers. It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, local Markdown reports, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
 
 > [!NOTE]
 > The project is under active development; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
@@ -30,13 +30,12 @@ python -m venv .venv
 python -m pip install open-code-review-toolkit
 ```
 
-The toolkit does not bundle OCR. Download the platform asset for exact
-[Open Code Review 1.11.3](https://github.com/alibaba/open-code-review/releases/tag/v1.11.3),
-verify it before installation against the [compatibility manifest](compatibility/ocr-support.json),
-and place the verified binary on `PATH`. The current Linux amd64 digest is
-`9726204ac81baee153fd65b1ff357c380f73e9d8091c4a73c3c9fb541b5164cb`; Darwin arm64 is
-`515cd92ce300b62dea2bcaf53e910cdf57b681e1d58bbd0a9e8e49617bca52fa`. The manifest owns
-the other platform hashes.
+The toolkit does not bundle OCR. Use `recommended_version` in the
+[compatibility manifest](compatibility/ocr-support.json) for this toolkit revision
+to select the exact [upstream release](https://github.com/alibaba/open-code-review/releases).
+Download its platform asset, verify it against that release entry's asset SHA-256,
+and place the verified binary on `PATH`. Do not substitute the latest upstream
+release or use another toolkit revision's manifest.
 
 Verify the installation without contacting an LLM provider:
 
@@ -45,18 +44,41 @@ ocr --version
 ocr-ci --help
 ```
 
-`ocr --version` must report `open-code-review v1.11.3`; `ocr-ci --help` must exit
+`ocr --version` must report the manifest's exact `recommended_version`; `ocr-ci --help` must exit
 successfully. `ocr-ci preflight` is an operational configuration check, not the installation
 smoke test.
 
 The exact recommended OCR release and its verified asset checksums live in the [versioned compatibility manifest](compatibility/ocr-support.json). CI should pin that release and 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`.
-The current OCR 1.11.3 integration defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
+The toolkit defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
-## How reviews evolve
+## Standalone local quick start
+
+With the qualified OCR binary and LLM environment configured, review an immutable
+commit without forge credentials:
+
+```console
+ocr-ci preflight --local
+ocr-ci review --local --result review.json --stderr review.stderr --report review.md -- --commit HEAD
+```
+
+Local execution uses the same OCR, mandatory evidence MCP, validation and DLP
+pipeline as CI. It publishes every admitted finding to a fresh private Markdown
+file and the console, without GitLab acquisition, suppression, approval or a
+fabricated publication receipt. See [local review](docs/local.md) for ranges,
+failure behavior and optional private `--debug-dir` bundles.
+
+Optional [reasoning and progress controls](docs/configuration.md#provider-endpoint-and-completion-cap-contract)
+do not change review rounds or budgets. Reasoning is unset by default; explicit
+`none` is a wire value whose support depends on the provider/model. Progress is
+off by default and emits only bounded toolkit phases to an interactive terminal
+or an explicitly nonblocking embedding stream; a conventional CI stderr pipe is
+intentionally not used because it can block a review.
+
+## How GitLab reviews evolve
 
 On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` or `@<live-bot-username> suppress` to keep a discussion open without future repeats; use the corresponding `resolve` command to resolve it after the next successful posting transaction. For example, a bot named `mr.bot` accepts the exact reply `@mr.bot resolve`.
 

{open_code_review_toolkit-0.9.0 → open_code_review_toolkit-0.10.0}/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.9.0'
-__version_tuple__ = version_tuple = (0, 9, 0)
+__version__ = version = '0.10.0'
+__version_tuple__ = version_tuple = (0, 10, 0)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.9.0 → open_code_review_toolkit-0.10.0}/src/ocr_toolkit/cli.py

@@ -24,7 +24,12 @@ def build_parser() -> argparse.ArgumentParser:
         version=f"%(prog)s {__version__}",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
-    subparsers.add_parser("preflight", help="Validate OCR, GitLab, and LLM access.")
+    preflight_parser = subparsers.add_parser(
+        "preflight", help="Validate review prerequisites and configured access."
+    )
+    preflight_parser.add_argument(
+        "--local", action="store_true", help="Validate standalone local review prerequisites."
+    )
     subparsers.add_parser("configure", help="Write the OCR runtime configuration.")
     subparsers.add_parser("mcp-config", help="Write OCR MCP server configuration.")
     review_parser = subparsers.add_parser(
@@ -32,6 +37,15 @@ def build_parser() -> argparse.ArgumentParser:
     )
     review_parser.add_argument("--result", required=True, help="OCR JSON output path.")
     review_parser.add_argument("--stderr", required=True, help="Full OCR stderr artifact path.")
+    review_parser.add_argument(
+        "--local", action="store_true", help="Review immutable Git refs and publish local Markdown."
+    )
+    review_parser.add_argument(
+        "--report", help="Fresh local Markdown path (default: --result path plus .md)."
+    )
+    review_parser.add_argument(
+        "--debug-dir", help="Fresh private diagnostic bundle directory (requires --local)."
+    )
     review_parser.add_argument(
         "--preserve-private-artifacts",
         action="store_true",
@@ -62,7 +76,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     args = build_parser().parse_args(argv)
     if args.command == "preflight":
-        return preflight.main()
+        return preflight.main(local=True) if args.local else preflight.main()
     if args.command == "configure":
         return configure.main()
     if args.command == "mcp-config":
@@ -75,6 +89,9 @@ def main(argv: Sequence[str] | None = None) -> int:
                 Path(args.stderr),
                 ocr_args,
                 preserve_private_artifacts=args.preserve_private_artifacts,
+                **({"local": True} if args.local else {}),
+                **({"report_path": Path(args.report)} if args.report is not None else {}),
+                **({"debug_dir": Path(args.debug_dir)} if args.debug_dir is not None else {}),
             )
         except review_runner.ReviewRunnerError as exc:
             print(f"Cannot run Open Code Review: {exc}", file=sys.stderr)

open_code_review_toolkit-0.10.0/src/ocr_toolkit/common/filesystem.py

@@ -0,0 +1,68 @@
+"""Small cross-platform filesystem durability helpers."""
+
+from __future__ import annotations
+
+import errno
+import os
+import stat
+from pathlib import Path
+
+
+def fsync_directory(descriptor: int) -> None:
+    """Persist a directory-entry change when the platform supports it."""
+
+    try:
+        os.fsync(descriptor)
+    except OSError as exc:
+        # Some supported filesystems reject directory fsync even though the
+        # atomic rename itself succeeded. Ignore only documented unsupported
+        # descriptor/filesystem cases; propagate genuine durability failures.
+        if exc.errno not in {errno.EINVAL, errno.ENOTSUP, errno.EBADF}:
+            raise
+
+
+def open_private_parent_directory(path: Path) -> tuple[int, str]:
+    """Open a path's parent without following replaceable pathname components.
+
+    The returned descriptor pins the parent directory.  Callers must use
+    descriptor-relative operations and close it themselves; returning an
+    absolute pathname would reintroduce the ancestor replacement race this
+    helper avoids.
+    """
+
+    absolute = path.absolute()
+    parts = [part for part in absolute.parts if part != os.path.sep]
+    if not parts:
+        raise ValueError("private output path must name a file or directory")
+    descriptor = os.open(os.path.sep, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        for component in parts[:-1]:
+            flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+            try:
+                child = os.open(component, flags, dir_fd=descriptor)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(component, mode=0o700, dir_fd=descriptor)
+                except FileExistsError:
+                    pass
+                try:
+                    child = os.open(component, flags, dir_fd=descriptor)
+                except OSError as exc:
+                    raise ValueError("private output parent must not be a symlink") from exc
+            except OSError as exc:
+                raise ValueError("private output parent must not be a symlink") from exc
+            os.close(descriptor)
+            descriptor = child
+        parent = os.fstat(descriptor)
+        if not stat.S_ISDIR(parent.st_mode):
+            raise OSError("private output parent is not a directory")
+        return descriptor, parts[-1]
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def same_file_identity(left: os.stat_result, right: os.stat_result) -> bool:
+    """Compare two pinned filesystem identities without following pathnames."""
+
+    return left.st_dev == right.st_dev and left.st_ino == right.st_ino

open_code_review_toolkit-0.10.0/src/ocr_toolkit/posting/comments.py

@@ -0,0 +1,21 @@
+"""Posting facade for shared report value normalization."""
+
+from ocr_toolkit.reporting.text import (
+    clean_text,
+    code_text,
+    comment_line,
+    compact_control_text,
+    compact_escaped_text,
+    compact_text,
+    line_number,
+)
+
+__all__ = [
+    "clean_text",
+    "code_text",
+    "comment_line",
+    "compact_control_text",
+    "compact_escaped_text",
+    "compact_text",
+    "line_number",
+]