@in-the-loop-labs/pair-review 2.3.3 → 2.4.0

package/src/chat/api-reference.js

@@ -0,0 +1,539 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * API Reference Module
+ *
+ * Provides two views of the pair-review HTTP API:
+ * 1. renderApiDocs  — full markdown reference with curl examples
+ * 2. buildApiCheatSheet — compact endpoint-only cheat sheet (~2KB, budget < 2.5KB)
+ *
+ * Both substitute real port and reviewId values into the output.
+ */
+
+/**
+ * Full API reference markdown, derived from the SKILL.md specification.
+ * Placeholders {{PORT}} and {{REVIEW_ID}} are replaced with real values.
+ * @param {Object} options
+ * @param {number|string} options.port - Server port
+ * @param {number|string} options.reviewId - Current review ID
+ * @returns {string} Complete API reference in markdown
+ */
+function renderApiDocs({ port, reviewId }) {
+  if (reviewId == null) {
+    throw new Error('reviewId is required for renderApiDocs');
+  }
+  if (port == null) {
+    throw new Error('port is required for renderApiDocs');
+  }
+
+  return API_DOCS_TEMPLATE
+    .replace(/\{\{PORT\}\}/g, String(port))
+    .replace(/\{\{REVIEW_ID\}\}/g, String(reviewId));
+}
+
+/**
+ * Compact cheat sheet with endpoint signatures and key params.
+ * Under 2.5KB total, with real port/reviewId baked in.
+ * @param {Object} options
+ * @param {number|string} options.port - Server port
+ * @param {number|string} options.reviewId - Current review ID
+ * @returns {string} Cheat sheet in markdown
+ */
+function buildApiCheatSheet({ port, reviewId }) {
+  if (reviewId == null) {
+    throw new Error('reviewId is required for buildApiCheatSheet');
+  }
+  if (port == null) {
+    throw new Error('port is required for buildApiCheatSheet');
+  }
+
+  return CHEAT_SHEET_TEMPLATE
+    .replace(/\{\{PORT\}\}/g, String(port))
+    .replace(/\{\{REVIEW_ID\}\}/g, String(reviewId));
+}
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const API_DOCS_TEMPLATE = `# pair-review API Reference
+
+## Comments
+
+All comment operations use a single set of unified endpoints.
+
+### List all comments
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments
+\`\`\`
+
+Optional query param: \`includeDismissed=true\` to include soft-deleted (inactive) comments.
+
+**Response:** \`{ "success": true, "comments": [...] }\`
+
+### Create a comment
+
+A single endpoint handles both line-level and file-level comments. If \`line_start\` is present, it creates a line-level comment; if omitted, it creates a file-level comment.
+
+**Line-level comment:**
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "file": "src/example.js",
+    "line_start": 42,
+    "line_end": 42,
+    "side": "right",
+    "body": "This variable should be renamed for clarity.",
+    "type": "suggestion",
+    "title": "Rename variable"
+  }'
+\`\`\`
+
+**File-level comment (omit \`line_start\`):**
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "file": "src/example.js",
+    "body": "This file needs better error handling throughout.",
+    "type": "suggestion",
+    "title": "Error handling"
+  }'
+\`\`\`
+
+**Response:** \`{ "success": true, "commentId": 123, "message": "Comment saved successfully" }\`
+
+Required fields: \`file\`, \`body\`.
+Optional fields: \`line_start\`, \`line_end\`, \`side\` ("left" or "right"), \`diff_position\`, \`commit_sha\`, \`parent_id\`, \`type\`, \`title\`.
+
+### Get a single comment
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments/COMMENT_ID
+\`\`\`
+
+### Update a comment
+
+\`\`\`bash
+curl -s -X PUT http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments/COMMENT_ID \\
+  -H 'Content-Type: application/json' \\
+  -d '{ "body": "Updated comment text." }'
+\`\`\`
+
+**Response:** \`{ "success": true, "message": "Comment updated successfully" }\`
+
+### Delete a comment
+
+> **Terminology note:** The UI refers to this operation as "dismiss." When a user asks to "dismiss a comment," use this DELETE endpoint.
+
+Soft-deletes the comment. If the comment was adopted from an AI suggestion, the parent suggestion is automatically transitioned to "dismissed" status.
+
+\`\`\`bash
+curl -s -X DELETE http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments/COMMENT_ID
+\`\`\`
+
+**Response:** \`{ "success": true, "message": "Comment deleted successfully", "dismissedSuggestionId": null }\`
+
+### Restore a deleted comment
+
+\`\`\`bash
+curl -s -X PUT http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments/COMMENT_ID/restore
+\`\`\`
+
+**Response:** \`{ "success": true, "message": "Comment restored successfully", "comment": {...} }\`
+
+### Bulk delete all comments
+
+Deletes all user comments for a review. Also dismisses any parent AI suggestions.
+
+\`\`\`bash
+curl -s -X DELETE http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/comments
+\`\`\`
+
+**Response:** \`{ "success": true, "deletedCount": 5, "dismissedSuggestionIds": [...], "message": "Deleted 5 user comments" }\`
+
+---
+
+## Suggestions
+
+All suggestion operations use unified endpoints. These work identically for both PR and local reviews.
+
+### List AI suggestions
+
+\`\`\`bash
+curl -s 'http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/suggestions'
+\`\`\`
+
+Optional query params:
+- \`levels\` — comma-separated list of levels: \`"final"\`, \`"1"\`, \`"2"\`, \`"3"\`. Default: \`"final"\` (orchestrated suggestions only).
+- \`runId\` — specific analysis run UUID. Default: latest run.
+
+**Response:** \`{ "suggestions": [{ "id": 1, "file": "...", "line_start": 10, "type": "bug", "title": "...", "body": "...", "status": "active", ... }] }\`
+
+### Check if suggestions exist
+
+\`\`\`bash
+curl -s 'http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/suggestions/check'
+\`\`\`
+
+Optional query param: \`runId\` (specific analysis run UUID).
+
+**Response:** \`{ "hasSuggestions": true, "analysisHasRun": true, "summary": "...", "stats": { "issues": 2, "suggestions": 3, "praise": 1 } }\`
+
+### Update AI suggestion status
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/suggestions/SUGGESTION_ID/status \\
+  -H 'Content-Type: application/json' \\
+  -d '{ "status": "dismissed" }'
+\`\`\`
+
+Valid statuses: \`"dismissed"\`, \`"active"\` (restore).
+
+> **Note:** Setting status to \`"adopted"\` directly is not allowed. Adoption must create a linked user comment via \`parent_id\`, which is why raw status-setting cannot do it. Use \`POST /suggestions/:id/adopt\` for adopt-as-is or \`POST /suggestions/:id/edit\` for adopt-with-edits.
+
+**Response:** \`{ "success": true, "status": "dismissed" }\`
+
+### Adopt an AI suggestion as-is
+
+Atomically creates a user comment from the suggestion's body/type/title (with category prefix), sets \`parent_id\` linkage, and updates suggestion status to \`adopted\`.
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/suggestions/SUGGESTION_ID/adopt
+\`\`\`
+
+No request body required.
+
+**Response:** \`{ "success": true, "userCommentId": 124, "message": "Suggestion adopted as user comment" }\`
+
+### Adopt an AI suggestion with edits
+
+Edits the suggestion text and adopts it as a new user comment.
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/suggestions/SUGGESTION_ID/edit \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "action": "adopt_edited",
+    "editedText": "The edited comment body to adopt as a user comment."
+  }'
+\`\`\`
+
+**Response:** \`{ "success": true, "userCommentId": 125, "message": "Suggestion edited and adopted as user comment" }\`
+
+---
+
+## Analysis Launch
+
+Analysis launch endpoints are **mode-specific** because starting an analysis requires mode-specific context (worktree paths for PRs, local directory paths for local reviews). Once launched, all subsequent analysis management uses the shared endpoints below.
+
+### Trigger AI analysis (PR mode)
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/pr/OWNER/REPO/PR_NUMBER/analyses \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "provider": "claude",
+    "model": "claude-sonnet-4-5-20250929",
+    "tier": "balanced",
+    "customInstructions": "Focus on security issues."
+  }'
+\`\`\`
+
+### Trigger AI analysis (local mode)
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/local/{{REVIEW_ID}}/analyses \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "provider": "claude",
+    "tier": "balanced",
+    "customInstructions": "Focus on security issues."
+  }'
+\`\`\`
+
+**Response (both modes):** \`{ "analysisId": "uuid", "runId": "uuid", "status": "started", "message": "AI analysis started in background" }\`
+
+Optional body fields: \`provider\`, \`model\`, \`tier\` ("fast", "balanced", "thorough"), \`customInstructions\`, \`skipLevel3\` (boolean), \`enabledLevels\` (object like \`{"1": true, "2": true, "3": false}\`).
+
+### Trigger council analysis (PR mode)
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/pr/OWNER/REPO/PR_NUMBER/analyses/council \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "councilId": "COUNCIL_UUID",
+    "customInstructions": "Focus on security."
+  }'
+\`\`\`
+
+### Trigger council analysis (local mode)
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/local/{{REVIEW_ID}}/analyses/council \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "councilId": "COUNCIL_UUID",
+    "customInstructions": "Focus on security."
+  }'
+\`\`\`
+
+**Response (both modes):** \`{ "analysisId": "uuid", "runId": "uuid", "status": "started", "message": "Council analysis started in background", "isCouncil": true }\`
+
+Required: either \`councilId\` (UUID of a saved council config) or \`councilConfig\` (inline config object).
+Optional: \`customInstructions\`, \`configType\` ("advanced" or "council").
+
+---
+
+## Analysis Status (Review-Level)
+
+Check whether an analysis is currently running for a review. This is a unified endpoint that works for both PR and local reviews.
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/analyses/status
+\`\`\`
+
+**Response (running):** \`{ "running": true, "analysisId": "uuid", "status": {...} }\`
+**Response (idle):** \`{ "running": false, "analysisId": null, "status": null }\`
+
+---
+
+## Analysis Management
+
+These shared endpoints operate on analysis UUIDs (returned when you launch an analysis). They work for both PR and local reviews.
+
+### Get analysis status by ID
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/analyses/ANALYSIS_ID/status
+\`\`\`
+
+**Response:** \`{ "id": "...", "status": "running"|"completed"|"failed"|"cancelled", "levels": {...}, "progress": "...", ... }\`
+
+### Cancel an analysis
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/analyses/ANALYSIS_ID/cancel
+\`\`\`
+
+**Response:** \`{ "success": true, "message": "Analysis cancelled", "processesKilled": 2, "status": "cancelled" }\`
+
+### Real-time progress (WebSocket)
+
+Analysis progress is delivered via WebSocket, not HTTP polling.
+
+1. Connect to \`ws://localhost:{{PORT}}/ws\`
+2. Subscribe: \`{ "action": "subscribe", "topic": "analysis:ANALYSIS_ID" }\`
+3. Receive progress events: \`{ "type": "progress", "topic": "analysis:ANALYSIS_ID", ... }\`
+
+For simple polling, use \`GET /api/analyses/ANALYSIS_ID/status\` instead.
+
+### List analysis runs for a review
+
+\`\`\`bash
+curl -s 'http://localhost:{{PORT}}/api/analyses/runs?reviewId={{REVIEW_ID}}'
+\`\`\`
+
+**Response:** \`{ "runs": [{ "id": "uuid", "review_id": 1, "provider": "claude", "status": "completed", ... }] }\`
+
+### Get latest analysis run for a review
+
+\`\`\`bash
+curl -s 'http://localhost:{{PORT}}/api/analyses/runs/latest?reviewId={{REVIEW_ID}}'
+\`\`\`
+
+**Response:** \`{ "run": { "id": "uuid", "review_id": 1, "provider": "claude", "status": "completed", ... } }\`
+
+### Get a specific analysis run by ID
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/analyses/runs/RUN_ID
+\`\`\`
+
+**Response:** \`{ "run": { "id": "uuid", ... } }\`
+
+### Import external analysis results
+
+Submit analysis results produced outside pair-review (e.g., by a coding agent):
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/analyses/results \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "path": "/absolute/path/to/repo",
+    "headSha": "abc123",
+    "provider": "claude",
+    "summary": "Analysis summary text",
+    "suggestions": [
+      {
+        "file": "src/example.js",
+        "line_start": 10,
+        "line_end": 15,
+        "type": "bug",
+        "title": "Potential null reference",
+        "description": "This could throw if input is null."
+      }
+    ],
+    "fileLevelSuggestions": []
+  }'
+\`\`\`
+
+Required: either \`path\` + \`headSha\` (local mode) or \`repo\` + \`prNumber\` (PR mode).
+Each suggestion requires: \`file\`, \`type\`, \`title\`, \`description\`.
+
+**Response (HTTP 201):** \`{ "runId": "uuid", "reviewId": 1, "totalSuggestions": 5, "status": "completed" }\`
+
+---
+
+## Comment Types
+
+The \`type\` field on comments and suggestions can be one of:
+- \`"bug"\` - Bug or defect
+- \`"suggestion"\` - General suggestion
+- \`"improvement"\` - Code improvement
+- \`"security"\` - Security concern
+- \`"performance"\` - Performance issue
+- \`"design"\` - Design/architecture concern
+- \`"praise"\` - Positive feedback
+- \`"style"\` or \`"code-style"\` - Style/formatting
+- \`"nitpick"\` - Minor nitpick
+- \`"question"\` - Question for the author
+
+---
+
+## Context Files
+
+Add non-diff files to the review's diff panel for reference during discussion. Each context file shows a specific line range from a file that isn't part of the PR/local changes.
+
+### Add a context file
+
+\`\`\`bash
+curl -s -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/context-files \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "file": "src/utils/helpers.js",
+    "line_start": 42,
+    "line_end": 78,
+    "label": "Helper function used by the changed code"
+  }'
+\`\`\`
+
+**Response (HTTP 201):** \`{ "success": true, "contextFile": { "id": 1, "review_id": 1, "file": "...", "line_start": 42, "line_end": 78, "label": "..." } }\`
+
+Required fields: \`file\` (must be a relative path without \`..\` segments), \`line_start\`, \`line_end\`.
+Optional fields: \`label\`.
+
+### List context files
+
+\`\`\`bash
+curl -s http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/context-files
+\`\`\`
+
+**Response:** \`{ "success": true, "contextFiles": [...] }\`
+
+### Remove a context file
+
+\`\`\`bash
+curl -s -X DELETE http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/context-files/CONTEXT_FILE_ID
+\`\`\`
+
+**Response:** \`{ "success": true, "message": "Context file removed" }\`
+
+### Remove all context files
+
+\`\`\`bash
+curl -s -X DELETE http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/context-files
+\`\`\`
+
+**Response:** \`{ "success": true, "deletedCount": 3, "message": "Removed 3 context files" }\`
+
+### Guidelines
+
+- Use judiciously -- only add files that are directly relevant to the discussion.
+- Keep ranges focused on specific functions/blocks (max 500 lines).
+- Use the \`label\` field to explain why the file is relevant.
+- Context files appear in the diff panel below the actual changes.
+- Reference context files in chat using backtick notation: \`\` \`src/utils/helpers.js:42-78\` \`\`.
+
+---
+
+## Diff Hunk Expansion
+
+Expand collapsed diff gaps to reveal hidden lines. Useful when you need to show the user lines that are inside a collapsed hunk. This is a transient UI command — expansions are not persisted.
+
+### Expand a hunk
+
+\`\`\`bash
+curl -X POST http://localhost:{{PORT}}/api/reviews/{{REVIEW_ID}}/expand-hunk \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "file": "src/app.js",
+    "line_start": 10,
+    "line_end": 20,
+    "side": "right"
+  }'
+\`\`\`
+
+**Required fields:**
+- \`file\` (string): Path of the changed file in the diff
+- \`line_start\` (integer): First line to reveal (>= 1)
+- \`line_end\` (integer): Last line to reveal (>= \`line_start\`)
+
+**Optional fields:**
+- \`side\` (string): \`"left"\` or \`"right"\` (default: \`"right"\`)
+
+**Response:** \`{ "success": true }\``;
+
+const CHEAT_SHEET_TEMPLATE = `# pair-review API Cheat Sheet
+
+Full docs: \`curl http://localhost:{{PORT}}/api.md?reviewId={{REVIEW_ID}}\`
+
+Base: \`http://localhost:{{PORT}}\` | Review: \`{{REVIEW_ID}}\`
+
+## Comments — /api/reviews/{{REVIEW_ID}}/comments
+- \`GET\` — List all (?includeDismissed=true)
+- \`POST\` — Create {file, body, ?line_start, ?line_end, ?side, ?type, ?title} (no line_start=file-level)
+- \`GET /:id\` — Get one
+- \`PUT /:id\` — Update {body}
+- \`DELETE /:id\` — Dismiss (soft-delete)
+- \`PUT /:id/restore\` — Restore dismissed
+- \`DELETE\` (no id) — Bulk dismiss all
+
+## Suggestions — /api/reviews/{{REVIEW_ID}}/suggestions
+- \`GET\` — List (?levels=final,1,2,3 &runId=UUID)
+- \`GET /check\` — Exists? (?runId=UUID)
+- \`POST /:id/status\` — Dismiss/restore {status}
+- \`POST /:id/adopt\` — Adopt as-is (no body)
+- \`POST /:id/edit\` — Adopt edited {action:"adopt_edited", editedText:"..."}
+
+## Analysis Launch (mode-specific)
+- \`POST /api/pr/:owner/:repo/:pr/analyses\` — PR analysis
+- \`POST /api/local/{{REVIEW_ID}}/analyses\` — Local analysis
+  Body: {?provider, ?model, ?tier, ?customInstructions, ?skipLevel3, ?enabledLevels}
+- \`POST .../analyses/council\` — Council (add /council to above)
+  Body: {councilId|councilConfig, ?customInstructions}
+
+## Analysis Status & Management
+- \`GET /api/reviews/{{REVIEW_ID}}/analyses/status\` — Running?
+- \`GET /api/analyses/:id/status\` — Status by analysis ID
+- \`POST /api/analyses/:id/cancel\` — Cancel
+- WebSocket /ws: subscribe "analysis:{id}" for progress
+- \`GET /api/analyses/runs?reviewId={{REVIEW_ID}}\` — List runs
+- \`GET /api/analyses/runs/latest?reviewId={{REVIEW_ID}}\` — Latest run
+- \`GET /api/analyses/runs/:id\` — Specific run
+- \`POST /api/analyses/results\` — Import external results
+
+## Context Files — /api/reviews/{{REVIEW_ID}}/context-files
+- \`POST\` — Add {file, line_start, line_end, ?label}
+- \`GET\` — List all
+- \`DELETE /:id\` — Remove one
+- \`DELETE\` (no id) — Remove all
+
+## Diff Hunk Expansion
+- \`POST /api/reviews/{{REVIEW_ID}}/expand-hunk\` — {file, line_start, line_end, ?side}
+
+## Comment Types
+bug | suggestion | improvement | security | performance | design | praise | style | nitpick | question`;
+
+module.exports = { renderApiDocs, buildApiCheatSheet };