evizi-kit 1.0.0

package/kits/shared/skills/pr-review/references/output-schema.md

@@ -0,0 +1,130 @@
+# Review Output Schema & Configuration
+
+## Standard Review Output (review.json)
+
+Create a JSON file following this schema and save it to the project root as `review.json`.
+
+### Full Example
+
+```json
+{
+  "prNumber": 42,
+  "status": "REQUEST_CHANGES",
+  "summary": "Found 2 critical issues and 1 warning.",
+  "statistics": {
+    "filesReviewed": 5,
+    "totalComments": 3,
+    "criticalCount": 2,
+    "warningCount": 1,
+    "suggestionCount": 0
+  },
+  "comments": [
+    {
+      "path": "src/utils/api.ts",
+      "line": 15,
+      "category": "Security",
+      "severity": "critical",
+      "title": "Hardcoded API Key",
+      "body": "API keys should never be committed to the repository.",
+      "recommendation": "Use environment variables instead",
+      "codeSnippet": "const API_KEY = process.env.API_KEY;"
+    }
+  ],
+  "metadata": {
+    "reviewedAt": "2026-02-03T15:30:00Z",
+    "baseBranch": "main",
+    "sourceBranch": "feature/new-feature",
+    "commitSha": "abc123def456"
+  }
+}
+```
+
+### Field Definitions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prNumber` | integer | Yes | PR/MR number |
+| `status` | string | Yes | `APPROVE`, `REQUEST_CHANGES`, or `COMMENT` |
+| `summary` | string | Yes | Human-readable summary |
+| `statistics` | object | No | Review statistics |
+| `comments` | array | Yes | List of inline comments |
+| `metadata` | object | No | Additional metadata |
+
+### Comment Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | string | Yes | File path from repo root |
+| `line` | integer | Yes | Line number in new file |
+| `category` | string | Yes | `Security`, `Bug`, `BreakingChange`, `Performance`, `Pattern`, `Type`, `Readability`, `Naming` |
+| `severity` | string | Yes | `critical`, `warning`, `suggestion` |
+| `title` | string | Yes | Short issue title |
+| `body` | string | Yes | Detailed description |
+| `recommendation` | string | No | Suggested fix |
+| `codeSnippet` | string | No | Recommended code |
+
+### Status Rules
+
+- **`APPROVE`** — No critical issues or warnings found. Suggestions only.
+- **`REQUEST_CHANGES`** — At least one critical issue found. The PR should not be merged as-is.
+- **`COMMENT`** — Warnings or suggestions found, but nothing blocking.
+
+---
+
+## Configuration
+
+Required in `.documents-design/project.config.json`:
+
+```json
+{
+  "baseBranch": "main",
+  "platform": "github",
+  "platformConfig": {
+    "github": { "apiUrl": "https://api.github.com" }
+  },
+  "repos": {
+    "webAuto": {
+      "github": { "owner": "your-org", "repo": "your-web-auto-repo" }
+    }
+  },
+  "enableCommentPosting": true,
+  "enableNotification": true
+}
+```
+
+### Configuration Options
+
+- `baseBranch` (string, required) — The branch to compare against (e.g., "main", "develop")
+- `platform` (string, required) — Git platform: "github", "gitlab", "gitea", or "bitbucket"
+- `platformConfig.{platform}.apiUrl` (string, required) — Platform API base URL
+- `repos` (object, required) — Named map of repositories, each with platform-specific connection details
+- `enableCommentPosting` (boolean, default: true) — Enable/disable posting inline comments to git platform
+- `enableNotification` (boolean, default: false) — Enable/disable Google Chat notifications
+
+### Operation Modes
+
+1. **Full Mode** — Posts comments + sends notification
+   - Config: `enableCommentPosting: true`, `enableNotification: true`
+   - Requires: Platform token + Google Chat webhook URL
+
+2. **Comment-Only Mode** — Posts comments, no notification
+   - Config: `enableCommentPosting: true`, `enableNotification: false`
+   - Requires: Platform token
+
+3. **Notification-Only Mode** — Only sends notification (no comments posted)
+   - Config: `enableCommentPosting: false`, `enableNotification: true`
+   - Requires: Google Chat webhook URL only (no git token needed)
+
+---
+
+## Dependencies
+
+- **Git CLI** — For fetching and analyzing PR code
+- **Python 3.8+** — For running the post-review script
+- **Platform Token** — Required only if `enableCommentPosting: true`
+  - GitHub: `GITHUB_TOKEN`
+  - GitLab: `GITLAB_TOKEN`
+  - Gitea: `GITEA_TOKEN`
+  - Bitbucket: `BITBUCKET_TOKEN` + `BITBUCKET_USERNAME`
+- **Google Chat Webhook** — Required only if `enableNotification: true`
+  - `GOOGLE_CHAT_WEBHOOK_URL`