npm - @alibaba-group/open-code-review - Versions diffs - 1.1.8 → 1.1.10 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/CONTRIBUTING.md +0 -1
package/CONTRIBUTING.zh-CN.md +0 -1
package/README.md +302 -45
package/README.zh-CN.md +22 -0
package/examples/README.md +10 -0
package/examples/github_actions/README.md +223 -0
package/examples/github_actions/ocr-review.yml +321 -0
package/examples/gitlab_ci/.gitlab-ci.yml +225 -0
package/examples/gitlab_ci/README.md +268 -0
package/package.json +2 -4
package/NPM-README.md +0 -95

package/examples/github_actions/README.md ADDED Viewed

@@ -0,0 +1,223 @@
+# OpenCodeReview - GitHub Actions Demo
+This demo shows how to integrate OpenCodeReview into your GitHub Actions workflow to automatically review Pull Requests and post review comments.
+## How It Works
+```
+PR Created/Updated → GitHub Actions Triggered → OCR Reviews Diff → Comments Posted on PR
+     OR
+Comment with trigger keyword ↗
+```
+1. When a PR is opened, synchronized, or reopened, the workflow triggers
+2. Alternatively, when a comment containing `/open-code-review` or `@open-code-review` is posted on a PR, the workflow triggers
+3. It installs OCR via `npm install -g @alibaba-group/open-code-review`
+4. Runs `ocr review --from origin/<base> --to origin/<head> --format json` to analyze the diff
+5. Parses the JSON output and posts inline review comments on the PR using GitHub's Pull Request Review API
+## Setup
+### 1. Copy the workflow file
+Copy `ocr-review.yml` to your repository's `.github/workflows/` directory:
+```bash
+mkdir -p .github/workflows
+cp ocr-review.yml .github/workflows/ocr-review.yml
+```
+### 2. Configure secrets
+Go to your repository's **Settings → Secrets and variables → Actions** and add:
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `OCR_LLM_URL` | Yes | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) |
+| `OCR_LLM_AUTH_TOKEN` | Yes | API authentication token |
+| `OCR_LLM_MODEL` | No | Model name (defaults to `gpt-4o`) |
+| `OCR_LLM_USE_ANTHROPIC` | No | Set to `true` if using Anthropic Claude models |
+> **Note:** `GITHUB_TOKEN` is automatically provided by GitHub Actions with the required `pull-requests: write` permission.
+>
+> The workflow also configures `llm.extra_body` to disable thinking mode for compatibility with various LLM providers.
+## Customization
+### Change the trigger events
+Modify the `on.pull_request.types` array in the workflow file:
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+```
+### Customize comment trigger keywords
+By default, the workflow triggers when a PR comment starts with `/open-code-review` or `@open-code-review`. You can customize these keywords by modifying the `if` condition in the workflow:
+```yaml
+if: |
+  github.event_name == 'pull_request' ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/review')) ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '@mybot'))
+```
+Or use a more flexible pattern with `contains` to trigger on any comment containing the keyword:
+```yaml
+if: |
+  github.event_name == 'pull_request' ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
+```
+> **Note:** The condition `github.event.issue.pull_request` ensures the comment is on a PR, not a regular issue.
+### Use a specific OCR version
+```yaml
+- name: Install OpenCodeReview
+  run: 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
+- name: Run OCR review
+  run: ocr review --rule ./my-rules.json --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+### Limit concurrency
+Adjust the `--concurrency` flag for large PRs to control the number of concurrent LLM requests:
+```yaml
+- name: Run OCR review
+  run: ocr review --concurrency 5 --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+### Provide background context
+Use the `--background` flag to pass additional context that helps OCR better understand the purpose of the changes:
+```yaml
+- name: Run OCR review
+  run: ocr review --background "${{ github.event.pull_request.title }}" --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+This is particularly useful when your PR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`) that clearly summarize what the PR implements. The background information helps OCR provide more relevant and context-aware review comments.
+### Customize the review comment author with GitHub App
+By default, review comments are posted using the built-in `GITHUB_TOKEN`, which appears as `github-actions[bot]`. You can customize this by creating a GitHub App and using its credentials instead.
+For more details about GitHub Apps, see the [GitHub Apps documentation](https://docs.github.com/en/apps).
+#### Step 1: Create a GitHub App
+1. Go to your organization or personal account **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Fill in the following:
+   - **GitHub App name**: e.g., `OpenCodeReview Bot`
+   - **Homepage URL**: Your repository or documentation URL
+   - **Webhook**: Uncheck "Active" (not needed for this use case)
+3. Under **Repository permissions**, set:
+   - **Pull requests**: Read and write
+   - **Contents**: Read-only (for fetching diffs)
+   - **Metadata**: Read-only (required)
+4. Click **Create GitHub App**
+#### Step 2: Generate a Private Key
+1. After creating the app, scroll down to **Private keys**
+2. Click **Generate a private key**
+3. Download and save the `.pem` file securely
+Note your App ID from the app settings page.
+#### Step 3: Install the App
+1. In the left sidebar, click **Install App**
+2. Select the repositories where you want to use OCR
+3. After installation, note the **Installation ID** from the URL (e.g., `https://github.com/settings/installations/12345` → Installation ID is `12345`)
+#### Step 4: Configure Repository Secrets
+Add the following secrets to your repository (**Settings → Secrets and variables → Actions**):
+| Secret | Description |
+|--------|-------------|
+| `GITHUB_APP_ID` | Your GitHub App's ID |
+| `GITHUB_APP_PRIVATE_KEY` | Contents of the `.pem` file (including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`) |
+| `GITHUB_APP_INSTALLATION_ID` | The Installation ID from Step 3 |
+#### Step 5: Update the Workflow
+Add a step to obtain a token from the GitHub App, then use it in the "Post review comments to PR" step:
+```yaml
+- name: Get GitHub App Token
+  id: app-token
+  uses: actions/create-github-app-token@v1
+  with:
+    app-id: ${{ secrets.GITHUB_APP_ID }}
+    private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}
+- name: Post review comments to PR
+  uses: actions/github-script@v7
+  with:
+    github-token: ${{ steps.app-token.outputs.token }}
+    script: |
+      # ... existing script
+```
+Now review comments will be posted with your custom GitHub App identity (e.g., `OpenCodeReview Bot`), providing a more professional and distinguishable appearance in your PRs.
+## Example Output
+When a PR is reviewed, comments appear directly in the PR's "Files changed" tab:
+- ✅ If no issues found: A comment saying "No comments generated. Looks good to me."
+- 🔍 If issues found: Inline review comments with suggestions using GitHub's native suggestion syntax
+### Inline Comment Example
+The workflow uses GitHub's `suggestion` code block syntax, so reviewers can apply fixes with one click:
+````markdown
+**Suggestion:**
+```suggestion
+// Fixed code here
+```
+````
+## 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** (set `OCR_LLM_USE_ANTHROPIC: true`):
+  - Anthropic Claude models
+## Troubleshooting
+### Common Issues
+1. **"Failed to parse OCR output"**: Check that `OCR_LLM_URL` and `OCR_LLM_AUTH_TOKEN` secrets are correctly set
+2. **"Cannot find merge-base"**: Ensure `fetch-depth: 0` is set in the checkout step
+3. **Review comments not appearing on correct lines**: This can happen when the diff has changed since the review started; the workflow handles this gracefully with a fallback to issue comments
+### Debugging
+Enable debug logging by adding to the OCR review step:
+```yaml
+env:
+  OCR_DEBUG: "1"
+```

package/examples/github_actions/ocr-review.yml ADDED Viewed

@@ -0,0 +1,321 @@
+# OpenCodeReview - GitHub Actions PR Auto-Review Demo
+#
+# This workflow automatically reviews pull requests using OpenCodeReview
+# and posts review comments directly on the PR.
+#
+# Triggers:
+#   - PR opened, synchronized, or reopened
+#   - Comment on PR containing '/open-code-review' or '@open-code-review'
+#
+# Required secrets:
+#   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
+#
+# Optional secrets:
+#   OCR_LLM_MODEL      - Model name (default: gpt-4o)
+#
+# Note: GITHUB_TOKEN is automatically provided by GitHub Actions.
+name: OpenCodeReview PR Review
+on:
+  pull_request:
+    types: [opened]
+  issue_comment:
+    types: [created]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  code-review:
+    runs-on: ubuntu-latest
+    # Run on PR events, or on comments starting with trigger keywords
+    if: |
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/open-code-review')) ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '@open-code-review'))
+    steps:
+      - name: Get PR context
+        id: pr-context
+        if: github.event_name != 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // For issue_comment events, get PR info
+            const prNumber = context.issue.number;
+            const { data: pullRequest } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber
+            });
+            core.setOutput('base_ref', pullRequest.base.ref);
+            core.setOutput('head_ref', pullRequest.head.ref);
+            core.setOutput('head_sha', pullRequest.head.sha);
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for merge-base diff
+          ref: ${{ github.event_name != 'pull_request' && steps.pr-context.outputs.head_sha || '' }}
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install OpenCodeReview
+        run: npm install -g @alibaba-group/open-code-review
+      - name: Configure OCR
+        run: |
+          ocr config set llm.url ${{ secrets.OCR_LLM_URL }}
+          ocr config set llm.auth_token ${{ secrets.OCR_LLM_AUTH_TOKEN }}
+          ocr config set llm.model ${{ secrets.OCR_LLM_MODEL }}
+          ocr config set llm.use_anthropic ${{ secrets.OCR_LLM_USE_ANTHROPIC }}
+          ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'
+      - name: Run OpenCodeReview
+        id: review
+        run: |
+          # Get base and head refs from PR context (different for comment triggers)
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_REF="${{ github.event.pull_request.base.ref }}"
+            HEAD_REF="${{ github.event.pull_request.head.ref }}"
+          else
+            BASE_REF="${{ steps.pr-context.outputs.base_ref }}"
+            HEAD_REF="${{ steps.pr-context.outputs.head_ref }}"
+          fi
+          echo "Reviewing PR: ${HEAD_REF} against ${BASE_REF}"
+          # Run OCR in range mode with JSON output
+          ocr review \
+            --from "origin/${BASE_REF}" \
+            --to "origin/${HEAD_REF}" \
+            --format json \
+            --audience agent \
+            > /tmp/ocr-result.json 2>/tmp/ocr-stderr.log || true
+          echo "OCR review completed. Output:"
+          cat /tmp/ocr-result.json
+          echo "OCR review completed. Error log:"
+          cat /tmp/ocr-stderr.log
+      - name: Post review comments to PR
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const path = '/tmp/ocr-result.json';
+            // Read OCR output (skip first line which is not valid JSON)
+            let result;
+            try {
+              const raw = fs.readFileSync(path, 'utf8');
+              const jsonContent = raw.substring(raw.indexOf('\n') + 1);
+              result = JSON.parse(jsonContent);
+            } catch (e) {
+              console.log('Failed to parse OCR output:', e.message);
+              // Post a simple comment if parsing fails
+              const stderr = fs.readFileSync('/tmp/ocr-stderr.log', 'utf8').trim();
+              if (stderr) {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: `⚠️ **OpenCodeReview** encountered an error:\n\`\`\`\n${stderr}\n\`\`\``
+                });
+              }
+              return;
+            }
+            const comments = result.comments || [];
+            const warnings = result.warnings || [];
+            // If no comments, post a summary
+            if (comments.length === 0) {
+              const message = result.message || 'No comments generated. Looks good to me.';
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: `✅ **OpenCodeReview**: ${message}`
+              });
+              return;
+            }
+            // Prepare PR review with inline comments
+            const prNumber = context.issue.number;
+            let commitSha;
+            // Get commit SHA from event context
+            if (context.eventName === 'pull_request') {
+              commitSha = context.payload.pull_request.head.sha;
+            } else {
+              // For comment events, we need to fetch the PR
+              const { data: pullRequest } = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: prNumber
+              });
+              commitSha = pullRequest.head.sha;
+            }
+            // Build review comments array for the PR review API
+            // Only inline comments with line info can be posted via createReview
+            const reviewComments = [];
+            const commentsWithoutLine = [];
+            for (const comment of comments) {
+              const body = formatComment(comment);
+              // Check if comment has valid line information for inline comment (line >= 1)
+              const hasValidLine = (comment.start_line >= 1) || (comment.end_line >= 1);
+              if (!hasValidLine) {
+                commentsWithoutLine.push({ comment, body });
+                continue;
+              }
+              const reviewComment = {
+                path: comment.path,
+                body: body
+              };
+              // Use line range if available
+              if (comment.start_line >= 1 && comment.end_line >= 1 && comment.start_line !== comment.end_line) {
+                reviewComment.start_line = comment.start_line;
+                reviewComment.line = comment.end_line;
+                reviewComment.start_side = 'RIGHT';
+                reviewComment.side = 'RIGHT';
+              } else if (comment.end_line >= 1) {
+                reviewComment.line = comment.end_line;
+                reviewComment.side = 'RIGHT';
+              } else if (comment.start_line >= 1) {
+                reviewComment.line = comment.start_line;
+                reviewComment.side = 'RIGHT';
+              }
+              reviewComments.push(reviewComment);
+            }
+            // Submit as a single PR review with all comments
+            const totalCount = comments.length;
+            const inlineCount = reviewComments.length;
+            const summaryCount = commentsWithoutLine.length;
+            let summaryBody = `🔍 **OpenCodeReview** found **${totalCount}** issue(s) in this PR.`;
+            if (totalCount > 0) {
+              summaryBody += `\n- ✅ ${inlineCount} posted as inline comment(s)`;
+              summaryBody += `\n- 📝 ${summaryCount} posted as summary (missing line info)`;
+            }
+            if (warnings.length > 0) {
+              summaryBody += `\n\n⚠️ ${warnings.length} warning(s) occurred during review.`;
+            }
+            // Add comments without line info to summary body
+            for (const { comment, body } of commentsWithoutLine) {
+              summaryBody += '\n\n---\n\n';
+              summaryBody += formatCommentMarkdown(comment);
+            }
+            // Statistics tracking
+            let successCount = 0;
+            let failedCount = 0;
+            const failedComments = [];
+            try {
+              await github.rest.pulls.createReview({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: prNumber,
+                commit_id: commitSha,
+                body: summaryBody,
+                event: 'COMMENT',
+                comments: reviewComments
+              });
+              successCount = reviewComments.length;
+              console.log(`Successfully posted review with ${successCount} inline comments (${commentsWithoutLine.length} in summary)`);
+            } catch (e) {
+              console.log('Failed to post review with inline comments:', e.message);
+              console.log('Falling back to posting comments individually...');
+              // Fallback: post comments one by one
+              for (const reviewComment of reviewComments) {
+                try {
+                  await github.rest.pulls.createReview({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    pull_number: prNumber,
+                    commit_id: commitSha,
+                    body: '',
+                    event: 'COMMENT',
+                    comments: [reviewComment]
+                  });
+                  successCount++;
+                  console.log(`Successfully posted comment for ${reviewComment.path}`);
+                } catch (innerE) {
+                  failedCount++;
+                  failedComments.push({ comment: reviewComment, error: innerE.message });
+                  console.log(`Failed to post comment for ${reviewComment.path}: ${innerE.message}`);
+                }
+              }
+              // Post summary comment with statistics
+              let finalBody = summaryBody;
+              finalBody += `\n\n---\n\n📊 **Posting Statistics:**`;
+              finalBody += `\n- ✅ Successfully posted: ${successCount} comment(s)`;
+              if (failedCount > 0) {
+                finalBody += `\n- ❌ Failed to post: ${failedCount} comment(s)`;
+              }
+              // Add failed comments details
+              if (failedComments.length > 0) {
+                finalBody += '\n\n<details><summary>❌ Failed Comments Details</summary>\n\n';
+                for (const { comment, error } of failedComments) {
+                  finalBody += `- \`${comment.path}\`: ${error}\n`;
+                }
+                finalBody += '\n</details>';
+              }
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: finalBody
+              });
+            }
+            function formatComment(comment) {
+              let body = comment.content || '';
+              // Add code suggestion if available
+              if (comment.suggestion_code && comment.existing_code) {
+                body += '\n\n**Suggestion:**\n';
+                body += '```suggestion\n';
+                body += comment.suggestion_code;
+                if (!comment.suggestion_code.endsWith('\n')) body += '\n';
+                body += '```';
+              }
+              return body;
+            }
+            function formatCommentMarkdown(comment) {
+              let md = `### 📄 \`${comment.path}\``;
+              if (comment.start_line && comment.end_line) {
+                md += ` (L${comment.start_line}-L${comment.end_line})`;
+              }
+              md += '\n\n';
+              md += comment.content || '';
+              if (comment.suggestion_code && comment.existing_code) {
+                md += '\n\n<details><summary>💡 Suggested Change</summary>\n\n';
+                md += '**Before:**\n```\n' + comment.existing_code + '\n```\n\n';
+                md += '**After:**\n```\n' + comment.suggestion_code + '\n```\n\n';
+                md += '</details>';
+              }
+              return md;
+            }