@alibaba-group/open-code-review 1.1.8 → 1.1.10

package/examples/gitlab_ci/.gitlab-ci.yml

@@ -0,0 +1,225 @@
+# OpenCodeReview - GitLab CI Merge Request Auto-Review Demo
+#
+# This pipeline automatically reviews Merge Requests using OpenCodeReview
+# and posts review comments (discussions) directly on the MR diff.
+#
+# Required CI/CD Variables (Settings → CI/CD → Variables):
+#   OCR_LLM_URL        - LLM API endpoint (e.g., https://api.openai.com/v1/chat/completions)
+#   OCR_LLM_AUTH_TOKEN - Authentication token for the LLM API (mark as "Masked")
+#   GITLAB_API_TOKEN   - GitLab Personal/Project Access Token with "api" scope
+#
+# Optional CI/CD Variables:
+#   OCR_LLM_MODEL      - Model name (default: gpt-4o)
+
+stages:
+  - review
+
+code-review:
+  stage: review
+  image: node:20
+  only:
+    - merge_requests
+  variables:
+    GIT_DEPTH: 0  # Full history needed for merge-base diff
+  script:
+    # Install OpenCodeReview
+    - npm install -g @alibaba-group/open-code-review
+
+    # Configure OCR
+    - mkdir -p ~/.open-code-review
+    # Gitlab CI/CD does not support confuring variables with value length less than 8, so you can't set use_anthropic as a CI variable
+    - |
+      ocr config set llm.url $OCR_LLM_URL
+      ocr config set llm.auth_token $OCR_LLM_AUTH_TOKEN
+      ocr config set llm.model $OCR_LLM_MODEL
+      ocr config set llm.use_anthropic false
+      ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'
+
+    # Run OCR review
+    - |
+      echo "Reviewing MR: ${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} against ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}"
+      ocr review \
+        --from "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}" \
+        --to "origin/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}" \
+        --format json \
+        --audience agent \
+        > /tmp/ocr-result.json 2>/tmp/ocr-stderr.log || true
+      echo "OCR review completed."
+      cat /tmp/ocr-result.json
+
+    # Post review comments to MR
+    - |
+      python3 << 'PYTHON_SCRIPT'
+      import json
+      import os
+      import sys
+      import urllib.request
+      import urllib.error
+
+      GITLAB_URL = os.environ.get("CI_SERVER_URL", "https://gitlab.com")
+      PROJECT_ID = os.environ["CI_PROJECT_ID"]
+      MR_IID = os.environ["CI_MERGE_REQUEST_IID"]
+      API_TOKEN = os.environ["GITLAB_API_TOKEN"]
+      SOURCE_BRANCH = os.environ["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]
+      TARGET_BRANCH = os.environ["CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]
+      COMMIT_SHA = os.environ["CI_COMMIT_SHA"]
+
+      API_BASE = f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}/merge_requests/{MR_IID}"
+
+      def api_request(endpoint, data=None, method="POST"):
+          """Make a GitLab API request."""
+          url = f"{API_BASE}{endpoint}"
+          headers = {
+              "PRIVATE-TOKEN": API_TOKEN,
+              "Content-Type": "application/json"
+          }
+          body = json.dumps(data).encode("utf-8") if data else None
+          req = urllib.request.Request(url, data=body, headers=headers, method=method)
+          try:
+              with urllib.request.urlopen(req) as resp:
+                  return json.loads(resp.read().decode("utf-8"))
+          except urllib.error.HTTPError as e:
+              print(f"API error {e.code}: {e.read().decode('utf-8')}", file=sys.stderr)
+              return None
+
+      def post_note(body):
+          """Post a general note/comment on the MR."""
+          return api_request("/notes", {"body": body})
+
+      def post_discussion(path, line, body, base_sha=None, start_sha=None, head_sha=None):
+          """Post an inline discussion on a specific file/line in the MR diff."""
+          position = {
+              "position_type": "text",
+              "new_path": path,
+              "old_path": path,
+              "new_line": line,
+              "base_sha": base_sha or TARGET_BRANCH,
+              "start_sha": start_sha or TARGET_BRANCH,
+              "head_sha": head_sha or COMMIT_SHA,
+          }
+          data = {
+              "body": body,
+              "position": position
+          }
+          return api_request("/discussions", data)
+
+      def format_comment(comment):
+          """Format a single review comment as markdown."""
+          body = comment.get("content", "")
+
+          existing = comment.get("existing_code", "")
+          suggestion = comment.get("suggestion_code", "")
+          if suggestion and existing:
+              body += "\n\n**Suggestion:**\n"
+              body += f"```suggestion:-0+0\n{suggestion}\n```"
+
+          return body
+
+      def format_comment_fallback(comment):
+          """Format a comment for fallback (non-inline) display."""
+          path = comment.get("path", "unknown")
+          start_line = comment.get("start_line", 0)
+          end_line = comment.get("end_line", 0)
+          content = comment.get("content", "")
+
+          md = f"### 📄 `{path}`"
+          if start_line and end_line:
+              md += f" (L{start_line}-L{end_line})"
+          md += f"\n\n{content}"
+
+          existing = comment.get("existing_code", "")
+          suggestion = comment.get("suggestion_code", "")
+          if suggestion and existing:
+              md += "\n\n<details><summary>💡 Suggested Change</summary>\n\n"
+              md += f"**Before:**\n```\n{existing}\n```\n\n"
+              md += f"**After:**\n```\n{suggestion}\n```\n\n"
+              md += "</details>"
+
+          return md
+
+      # --- Main ---
+
+      # Read OCR result (skip first line which is summary, not JSON)
+      try:
+          with open("/tmp/ocr-result.json", "r") as f:
+              next(f)  # Skip first line
+              result = json.load(f)
+      except (FileNotFoundError, json.JSONDecodeError) as e:
+          print(f"Failed to parse OCR output: {e}", file=sys.stderr)
+          stderr_content = ""
+          try:
+              with open("/tmp/ocr-stderr.log", "r") as f:
+                  stderr_content = f.read().strip()
+          except FileNotFoundError:
+              pass
+          if stderr_content:
+              post_note(f"⚠️ **OpenCodeReview** encountered an error:\n```\n{stderr_content}\n```")
+          sys.exit(0)
+
+      comments = result.get("comments", [])
+      warnings = result.get("warnings", [])
+
+      # No comments - post summary
+      if not comments:
+          message = result.get("message", "No comments generated. Looks good to me.")
+          post_note(f"✅ **OpenCodeReview**: {message}")
+          print("No review comments to post.")
+          sys.exit(0)
+
+      # Get MR diff metadata for position calculation
+      diff_refs = None
+      try:
+          versions_url = f"{API_BASE}/versions"
+          req = urllib.request.Request(versions_url, headers={"PRIVATE-TOKEN": API_TOKEN})
+          with urllib.request.urlopen(req) as resp:
+              versions = json.loads(resp.read().decode("utf-8"))
+          if versions:
+              latest = versions[0]
+              diff_refs = {
+                  "base_sha": latest.get("base_commit_sha", ""),
+                  "start_sha": latest.get("start_commit_sha", ""),
+                  "head_sha": latest.get("head_commit_sha", ""),
+              }
+      except Exception as e:
+          print(f"Warning: Could not fetch MR versions: {e}", file=sys.stderr)
+
+      # Post inline discussions for each comment
+      success_count = 0
+      failed_comments = []
+
+      for comment in comments:
+          path = comment.get("path", "")
+          end_line = comment.get("end_line", 0)
+          start_line = comment.get("start_line", end_line)
+          body = format_comment(comment)
+
+          if not path or not end_line:
+              failed_comments.append(comment)
+              continue
+
+          kwargs = {}
+          if diff_refs:
+              kwargs = diff_refs
+
+          result_resp = post_discussion(path, end_line, body, **kwargs)
+          if result_resp:
+              success_count += 1
+          else:
+              failed_comments.append(comment)
+
+      print(f"Successfully posted {success_count}/{len(comments)} inline comments.")
+
+      # Post fallback for any failed inline comments
+      if failed_comments:
+          fallback_body = f"🔍 **OpenCodeReview** found issues that could not be posted inline:\n\n---\n\n"
+          for comment in failed_comments:
+              fallback_body += format_comment_fallback(comment) + "\n\n---\n\n"
+          post_note(fallback_body)
+
+      # Post summary
+      summary = f"🔍 **OpenCodeReview** found **{len(comments)}** issue(s) in this MR."
+      if warnings:
+          summary += f"\n\n⚠️ {len(warnings)} warning(s) occurred during review."
+      post_note(summary)
+
+      PYTHON_SCRIPT

package/examples/gitlab_ci/README.md

@@ -0,0 +1,268 @@
+# OpenCodeReview - GitLab CI Demo
+
+This demo shows how to integrate OpenCodeReview into your GitLab CI/CD pipeline to automatically review Merge Requests and post review comments as inline discussions.
+
+## How It Works
+
+```
+MR Created/Updated → GitLab Pipeline Triggered → OCR Reviews Diff → Discussions Posted on MR
+```
+
+1. When a Merge Request is opened or updated, the pipeline triggers
+2. It installs OCR via npm in a `node:20` Docker image
+3. Runs `ocr review --from origin/<target> --to origin/<source> --format json` to analyze the diff
+4. Parses the JSON output and posts inline discussions on the MR using GitLab's Discussions API
+
+## Setup
+
+### 1. Copy the pipeline file
+
+Copy `.gitlab-ci.yml` to your repository root (or include it via `include:`):
+
+```bash
+cp .gitlab-ci.yml /path/to/your/repo/.gitlab-ci.yml
+```
+
+Or use GitLab's `include` feature in your existing `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: 'ci_demo/gitlab_ci/.gitlab-ci.yml'
+```
+
+### 2. Configure CI/CD Variables
+
+Go to your project's **Settings → CI/CD → Variables** and add:
+
+| Variable | Required | Masked | Description |
+|----------|----------|--------|-------------|
+| `OCR_LLM_URL` | Yes | No | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) |
+| `OCR_LLM_AUTH_TOKEN` | Yes | Yes | API authentication token |
+| `OCR_LLM_MODEL` | No | No | Model name (defaults to `gpt-4o`) |
+| `GITLAB_API_TOKEN` | Yes | Yes | GitLab access token with `api` scope |
+
+> **Note:** GitLab CI/CD does not support variables with values shorter than 8 characters, so `use_anthropic` cannot be set as a CI variable. The pipeline sets it to `false` by default. If you need to use Anthropic Claude models, you'll need to modify the `.gitlab-ci.yml` script directly.
+>
+> The pipeline also configures `llm.extra_body` to disable thinking mode for compatibility with various LLM providers.
+
+### 3. Create a GitLab Access Token
+
+You need a token with `api` scope to post discussions on MRs. Options:
+
+- **Project Access Token** (recommended): Settings → Access Tokens → Create with `api` scope
+- **Personal Access Token**: User Settings → Access Tokens → Create with `api` scope
+- **Group Access Token**: For organization-wide usage
+
+> **Note:** The built-in `CI_JOB_TOKEN` does NOT have sufficient permissions to create MR discussions, which is why a separate token is needed.
+>
+> **Tip:** For Project Access Tokens and Group Access Tokens, the token name determines the bot name shown in MR discussions. For example, naming your token `OpenCodeReview Bot` will make review comments appear as posted by `OpenCodeReview Bot`.
+
+## Example Output
+
+When an MR is reviewed, comments appear as:
+
+- **Inline discussions**: Directly on the changed lines in the MR diff view
+- **Summary note**: A final note summarizing the total number of issues found
+- **Fallback notes**: If inline posting fails for specific comments, they appear as regular MR notes with file/line references
+
+### Inline Discussion Example
+
+Comments are posted using GitLab's Discussion API with position data, so they appear directly next to the relevant code in the "Changes" tab.
+
+## Supported LLM Providers
+
+OCR supports both OpenAI and Anthropic API formats:
+
+- **OpenAI-compatible APIs** (default):
+  - OpenAI (GPT-4o, GPT-4, etc.)
+  - Azure OpenAI
+  - Self-hosted models (vLLM, Ollama, etc.)
+- **Anthropic APIs** (modify `.gitlab-ci.yml` to set `use_anthropic: true`):
+  - Anthropic Claude models
+
+## Customization
+
+### Use a specific OCR version
+
+```yaml
+script:
+  - npm install -g @alibaba-group/open-code-review@1.0.0
+```
+
+### Add custom review rules
+
+Use the `--rule` flag to pass a custom rules JSON file:
+
+```yaml
+script:
+  - ocr review --rule ./my-rules.json --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+```
+
+### Limit concurrency
+
+Adjust the `--concurrency` flag for large MRs to control the number of concurrent LLM requests:
+
+```yaml
+script:
+  - ocr review --concurrency 5 --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+```
+
+### Provide background context
+
+Use the `--background` flag to pass additional context that helps OCR better understand the purpose of the changes:
+
+```yaml
+script:
+  - ocr review --background "$CI_MERGE_REQUEST_TITLE" --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+```
+
+This is particularly useful when your MR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`) that clearly summarize what the MR implements. The background information helps OCR provide more relevant and context-aware review comments.
+
+### Change the trigger events
+
+By default, the pipeline uses `only: [merge_requests]`, which triggers on **all** MR events (creation, updates, reopen). GitLab CI does not natively support fine-grained control to trigger **only on MR creation**.
+
+To avoid re-reviewing on every push to an existing MR (and wasting LLM API tokens), you can check for existing OCR reviews **before** running `ocr review`. Use a wrapper script that skips the review step if OCR comments already exist:
+
+```yaml
+script:
+  # Install OpenCodeReview
+  - npm install -g @alibaba-group/open-code-review
+
+  # Configure OCR
+  - mkdir -p ~/.open-code-review
+  - |
+    ocr config set llm.url $OCR_LLM_URL
+    ocr config set llm.auth_token $OCR_LLM_AUTH_TOKEN
+    ocr config set llm.model $OCR_LLM_MODEL
+    ocr config set llm.use_anthropic false
+    ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'
+
+  # Check for existing OCR reviews and run review only if not found
+  - |
+    python3 << 'WRAPPER_SCRIPT'
+    import json
+    import os
+    import subprocess
+    import sys
+    import urllib.request
+
+    GITLAB_URL = os.environ.get("CI_SERVER_URL", "https://gitlab.com")
+    PROJECT_ID = os.environ["CI_PROJECT_ID"]
+    MR_IID = os.environ["CI_MERGE_REQUEST_IID"]
+    API_TOKEN = os.environ["GITLAB_API_TOKEN"]
+    SOURCE_BRANCH = os.environ["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]
+    TARGET_BRANCH = os.environ["CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]
+
+    # Check for existing OCR reviews
+    url = f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}/merge_requests/{MR_IID}/notes?per_page=100"
+    req = urllib.request.Request(url, headers={"PRIVATE-TOKEN": API_TOKEN})
+    with urllib.request.urlopen(req) as resp:
+        notes = json.loads(resp.read().decode("utf-8"))
+
+    for note in notes:
+        if "OpenCodeReview" in note.get("body", ""):
+            print("⏭️ OCR has already reviewed this MR. Skipping to save tokens.")
+            print("Delete previous OCR comments to re-trigger review.")
+            sys.exit(0)
+
+    # No existing review found - run OCR
+    print("🔍 No existing OCR review found. Running review...")
+    result = subprocess.run([
+        "ocr", "review",
+        "--from", f"origin/{TARGET_BRANCH}",
+        "--to", f"origin/{SOURCE_BRANCH}",
+        "--format", "json",
+        "--audience", "agent"
+    ], capture_output=True, text=True)
+
+    # Save output for the posting script
+    with open("/tmp/ocr-result.json", "w") as f:
+        f.write(result.stdout)
+    with open("/tmp/ocr-stderr.log", "w") as f:
+        f.write(result.stderr)
+
+    print("OCR review completed.")
+    WRAPPER_SCRIPT
+
+  # Post review comments to MR
+  - |
+    python3 << 'PYTHON_SCRIPT'
+    ...existing post script...
+    PYTHON_SCRIPT
+```
+
+The key logic: the Python wrapper checks for existing OCR comments before running `ocr review`. If found, it exits early with `sys.exit(0)` before consuming any LLM tokens. To re-trigger a review, users can manually delete the previous OCR comments.
+
+### Self-hosted GitLab
+
+The script automatically uses `CI_SERVER_URL` to determine the GitLab API base URL, so it works with self-hosted GitLab instances out of the box.
+
+### Use a Service Account as Review Bot
+
+By default, review comments are posted using the user who owns the access token configured in `GITLAB_API_TOKEN`. You can create a dedicated service account bot to post reviews with a custom identity, making it easier to distinguish automated reviews from human comments.
+
+For more details about GitLab service accounts, see the [GitLab Service Accounts documentation](https://docs.gitlab.com/ee/user/profile/service_accounts.html).
+
+#### Step 1: Create a Service Account
+
+Create a service account in your project:
+
+1. Go to your **Project → Settings → Service Accounts**
+2. Click **New service account**
+3. Fill in the following:
+   - **Name**: e.g., `OpenCodeReview Bot` (this will be the bot name shown in MR discussions)
+   - **Username**: Will be auto-generated based on the name
+4. Click **Create service account**
+
+#### Step 2: Invite the Service Account to Your Project
+
+After the service account is created, invite it to your project with appropriate permissions:
+
+1. Go to your **Project → Settings → Members**
+2. Click **Invite member**
+3. Search for the service account by name (e.g., `OpenCodeReview Bot`)
+4. Select the service account and assign a role (`Developer` or `Maintainer` required for posting discussions)
+5. Click **Invite**
+
+#### Step 3: Create an Access Token
+
+Generate an access token for the service account:
+
+1. Go to your **Project → Settings → Service Accounts**
+2. Click on the service account to view its details
+3. Click **Add new token**
+4. Configure the token:
+   - **Name**: e.g., `ocr-review-token`
+   - **Expiration**: As needed
+   - **Scope**: Select `api` (required for Discussions API)
+5. Click **Create token** and copy the token value
+
+#### Step 4: Update CI/CD Variables
+
+Update the `GITLAB_API_TOKEN` variable in your project's CI/CD settings:
+
+Go to **Settings → CI/CD → Variables** and update `GITLAB_API_TOKEN` with the service account's token.
+
+Now review comments will be posted with your service account identity (e.g., `OpenCodeReview Bot`), providing a clear and professional appearance for automated code reviews.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"API error 403"**: The `GITLAB_API_TOKEN` lacks `api` scope or doesn't have access to the project
+2. **"Failed to parse OCR output"**: Check that `OCR_LLM_URL` and `OCR_LLM_AUTH_TOKEN` variables are correctly set
+3. **"Cannot find merge-base"**: Ensure `GIT_DEPTH: 0` is set (full clone)
+4. **Inline comments on wrong lines**: GitLab requires exact SHA matching; the script fetches MR version metadata to get correct diff refs
+
+### Debugging
+
+Add verbose output to the review step:
+
+```yaml
+script:
+  - cat /tmp/ocr-result.json
+  - cat /tmp/ocr-stderr.log
+```
+
+

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "@alibaba-group/open-code-review",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "OpenCodeReview CLI — AI-powered code review tool",
   "bin": {
     "ocr": "bin/ocr.js"
   },
   "scripts": {
-    "postinstall": "node scripts/install.js",
-    "prepublishOnly": "cp NPM-README.md README.md",
-    "postpublish": "git checkout README.md"
+    "postinstall": "node scripts/install.js"
   },
   "repository": {
     "type": "git",

package/NPM-README.md

@@ -1,95 +0,0 @@
-# OpenCodeReview CLI
-
-AI-powered code review tool that reads Git diffs, sends changed files to a configurable LLM via OpenAI-compatible API, and generates structured review comments. It goes beyond surface-level analysis — the Agent can read project context for deep reviews.
-
-## Install
-
-```bash
-npm install -g @alibaba-group/open-code-review
-```
-
-After installation, the `ocr` command is available globally.
-
-### Version Control
-
-```bash
-# Install specific version
-OCR_VERSION=v1.0.0 npm install -g @alibaba-group/open-code-review
-```
-
-## Prerequisites
-
-**You must configure an LLM provider before using `ocr`.** The tool requires access to an OpenAI-compatible API endpoint (OpenAI, Claude, local models, etc.).
-
-```bash
-ocr config set llm.url https://api.anthropic.com/v1/messages \
-    && ocr config set llm.auth_token {{your-api-key}} \
-    && ocr config set llm.model claude-opus-4-6 \
-    && ocr config set llm.use_anthropic true  \
-    && ocr config set language Chinese
-```
-
-Config is stored in `~/.opencodereview/config.json`.
-
-Or via environment variables:
-
-```bash
-export OCR_LLM_URL=https://api.anthropic.com/v1/messages
-export OCR_LLM_TOKEN=your-api-key
-export OCR_LLM_MODEL=claude-opus-4-6
-```
-
-### Test Connectivity
-
-```bash
-ocr llm test
-```
-
-## Quick Start
-
-Navigate to any Git repository and run:
-
-```bash
-# Review all workspace changes
-ocr review
-
-# Review diff between two branches
-ocr review --from main --to feature-branch
-
-# Review a single commit
-ocr review --commit abc123
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ocr review` / `ocr r` | Start code review |
-| `ocr config set <key> <value>` | Manage configuration |
-| `ocr llm test` | Test LLM connectivity |
-| `ocr viewer` | Start WebUI session viewer |
-| `ocr version` | Show version info |
-
-## Common Options
-
-| Flag | Shorthand | Default | Description |
-|------|-----------|---------|-------------|
-| `--repo` | | current dir | Git repository root |
-| `--from` | | | Source ref (e.g., `main`) |
-| `--to` | | | Target ref (e.g., `feature-branch`) |
-| `--commit` | `-c` | | Review a single commit |
-| `--format` | `-f` | `text` | Output format: `text` or `json` |
-| `--concurrency` | | `4` | Max concurrent file reviews |
-| `--timeout` | | `10` | Per-file timeout (minutes) |
-
-## Features
-
-- **Three review modes**: workspace changes, branch range, single commit
-- **Context-aware**: Agent reads arbitrary files, searches code via `git grep`, inspects diffs
-- **Plan phase**: Large changes (>50 lines) get risk analysis first
-- **Any LLM**: Works with OpenAI, Claude-compatible endpoints, local models
-- **Concurrent**: Files reviewed in parallel (configurable workers)
-
-## License
-
-Apache-2.0