bitbucket-gemini-action 1.0.0

package/src/gemini/prompts.ts

@@ -0,0 +1,331 @@
+/**
+ * Gemini Prompt Templates
+ * System prompts and prompt builders for code review
+ */
+
+import {
+  combinePresets,
+  getPreset,
+  getAllPresetKeys,
+  type ReviewPreset,
+} from "./presets.js";
+
+export const CODE_REVIEW_SYSTEM_PROMPT = `You are an expert code reviewer assistant integrated with Bitbucket. Your role is to provide helpful, actionable feedback on pull requests.
+
+## Your Capabilities
+- Analyze code changes for bugs, security issues, and best practices
+- Suggest improvements for code quality and maintainability
+- Identify potential performance issues
+- Check for proper error handling
+- Verify code follows project conventions
+
+## Guidelines
+1. **Be Constructive**: Focus on helping improve the code, not criticizing the author
+2. **Be Specific**: Point to exact lines and provide concrete suggestions
+3. **Be Concise**: Keep comments focused and actionable
+4. **Prioritize**: Focus on important issues first (bugs > security > style)
+5. **Explain Why**: Always explain the reasoning behind suggestions
+6. **Suggest Alternatives**: When pointing out issues, suggest better approaches
+
+## Comment Format
+- Use markdown for formatting
+- For code suggestions, use fenced code blocks with language hints
+- Keep inline comments short (1-3 sentences)
+- Use the general PR comment for summaries and overall feedback
+
+## What to Look For
+- Logic errors and potential bugs
+- Security vulnerabilities (SQL injection, XSS, etc.)
+- Null/undefined handling
+- Error handling completeness
+- Type safety issues
+- Performance concerns
+- Code duplication
+- Naming clarity
+- Documentation gaps (for public APIs)
+
+## What NOT to Do
+- Don't nitpick style issues covered by linters
+- Don't request changes for subjective preferences
+- Don't leave comments without actionable suggestions
+- Don't focus on trivial issues when there are bigger concerns`;
+
+export const TAG_MODE_SYSTEM_PROMPT = `${CODE_REVIEW_SYSTEM_PROMPT}
+
+## Tag Mode Behavior
+You were triggered by a user mentioning @gemini in a comment. Respond directly to their question or request. Focus your response on what they specifically asked for.
+
+If they asked a question, answer it.
+If they requested a review, review the relevant code.
+If they asked for clarification, provide context.`;
+
+export const AGENT_MODE_SYSTEM_PROMPT = `${CODE_REVIEW_SYSTEM_PROMPT}
+
+## Agent Mode Behavior
+You are running in automated mode, triggered by a pipeline or automation. Execute the provided prompt completely and thoroughly. Be systematic and cover all aspects mentioned in the prompt.`;
+
+export interface PRContext {
+  title: string;
+  description: string;
+  author: string;
+  sourceBranch: string;
+  targetBranch: string;
+  files: Array<{
+    path: string;
+    status: string;
+    additions: number;
+    deletions: number;
+  }>;
+  diff: string;
+  comments?: Array<{
+    author: string;
+    content: string;
+    path?: string;
+    line?: number;
+    createdAt: string;
+  }>;
+}
+
+export function buildPRReviewPrompt(context: PRContext): string {
+  const filesSummary = context.files
+    .map(
+      (f) =>
+        `- ${f.path} (${f.status}): +${f.additions}/-${f.deletions}`
+    )
+    .join("\n");
+
+  return `## Pull Request Review Request
+
+### PR Details
+- **Title**: ${context.title}
+- **Author**: ${context.author}
+- **Branch**: ${context.sourceBranch} → ${context.targetBranch}
+
+### Description
+${context.description || "_No description provided_"}
+
+### Changed Files
+${filesSummary}
+
+### Diff
+\`\`\`diff
+${context.diff}
+\`\`\`
+
+${context.comments?.length ? `### Existing Comments\n${formatComments(context.comments)}` : ""}
+
+---
+
+Please review this pull request and provide feedback. Focus on:
+1. Any bugs or logic errors
+2. Security concerns
+3. Code quality improvements
+4. Missing error handling
+5. Performance considerations
+
+Use the available tools to leave inline comments on specific lines and a summary comment for overall feedback.`;
+}
+
+export function buildTagModePrompt(
+  context: PRContext,
+  userMessage: string,
+  mentionAuthor: string
+): string {
+  const filesSummary = context.files
+    .map(
+      (f) =>
+        `- ${f.path} (${f.status}): +${f.additions}/-${f.deletions}`
+    )
+    .join("\n");
+
+  return `## User Request
+
+**@${mentionAuthor}** mentioned you with the following message:
+
+> ${userMessage}
+
+---
+
+### PR Context
+- **Title**: ${context.title}
+- **Author**: ${context.author}
+- **Branch**: ${context.sourceBranch} → ${context.targetBranch}
+
+### Description
+${context.description || "_No description provided_"}
+
+### Changed Files
+${filesSummary}
+
+### Diff
+\`\`\`diff
+${context.diff}
+\`\`\`
+
+${context.comments?.length ? `### Recent Comments\n${formatComments(context.comments)}` : ""}
+
+---
+
+Please respond to the user's request. Address their specific question or concern.`;
+}
+
+export function buildAgentModePrompt(
+  context: PRContext,
+  agentPrompt: string
+): string {
+  const filesSummary = context.files
+    .map(
+      (f) =>
+        `- ${f.path} (${f.status}): +${f.additions}/-${f.deletions}`
+    )
+    .join("\n");
+
+  return `## Automated Task
+
+Execute the following task:
+
+${agentPrompt}
+
+---
+
+### PR Context
+- **Title**: ${context.title}
+- **Author**: ${context.author}
+- **Branch**: ${context.sourceBranch} → ${context.targetBranch}
+
+### Description
+${context.description || "_No description provided_"}
+
+### Changed Files
+${filesSummary}
+
+### Diff
+\`\`\`diff
+${context.diff}
+\`\`\`
+
+---
+
+Complete the requested task using the available tools.`;
+}
+
+function formatComments(
+  comments: NonNullable<PRContext["comments"]>
+): string {
+  return comments
+    .map((c) => {
+      const location = c.path
+        ? `on \`${c.path}${c.line ? `:${c.line}` : ""}\``
+        : "";
+      return `- **${c.author}** ${location} (${c.createdAt}):\n  > ${c.content.split("\n").join("\n  > ")}`;
+    })
+    .join("\n\n");
+}
+
+/**
+ * Build system prompt with presets
+ */
+export function buildSystemPromptWithPresets(
+  baseSystemPrompt: string,
+  presetKeys: string[],
+  customPrompt?: string
+): string {
+  // If no presets or custom prompt, return base
+  if (presetKeys.length === 0 && !customPrompt) {
+    return baseSystemPrompt;
+  }
+
+  // Validate preset keys
+  const validKeys = getAllPresetKeys();
+  const invalidKeys = presetKeys.filter((key) => !validKeys.includes(key));
+  if (invalidKeys.length > 0) {
+    console.warn(`⚠️ Unknown preset keys: ${invalidKeys.join(", ")}`);
+  }
+
+  const validPresetKeys = presetKeys.filter((key) => validKeys.includes(key));
+
+  // Combine presets
+  const presetPrompt = combinePresets(validPresetKeys, customPrompt);
+
+  if (!presetPrompt) {
+    return baseSystemPrompt;
+  }
+
+  return `${baseSystemPrompt}
+
+---
+
+${presetPrompt}`;
+}
+
+/**
+ * Build prompt with presets for PR review
+ */
+export function buildPRReviewPromptWithPresets(
+  context: PRContext,
+  presetKeys: string[],
+  customPrompt?: string
+): string {
+  const basePrompt = buildPRReviewPrompt(context);
+  const presetPrompt = combinePresets(presetKeys, customPrompt);
+
+  if (!presetPrompt) {
+    return basePrompt;
+  }
+
+  return `${basePrompt}
+
+---
+
+${presetPrompt}`;
+}
+
+/**
+ * Build agent mode prompt with presets
+ */
+export function buildAgentModePromptWithPresets(
+  context: PRContext,
+  agentPrompt: string,
+  presetKeys: string[],
+  customPrompt?: string
+): string {
+  const basePrompt = buildAgentModePrompt(context, agentPrompt);
+  const presetPrompt = combinePresets(presetKeys, customPrompt);
+
+  if (!presetPrompt) {
+    return basePrompt;
+  }
+
+  return `${basePrompt}
+
+---
+
+${presetPrompt}`;
+}
+
+/**
+ * Build tag mode prompt with presets
+ */
+export function buildTagModePromptWithPresets(
+  context: PRContext,
+  userMessage: string,
+  mentionAuthor: string,
+  presetKeys: string[],
+  customPrompt?: string
+): string {
+  const basePrompt = buildTagModePrompt(context, userMessage, mentionAuthor);
+  const presetPrompt = combinePresets(presetKeys, customPrompt);
+
+  if (!presetPrompt) {
+    return basePrompt;
+  }
+
+  return `${basePrompt}
+
+---
+
+${presetPrompt}`;
+}
+
+// Re-export preset utilities for convenience
+export { combinePresets, getPreset, getAllPresetKeys, type ReviewPreset };

package/src/gemini/tools.ts

@@ -0,0 +1,226 @@
+/**
+ * Gemini Function Calling Tools Definition
+ * Tools for code review and PR interaction
+ */
+
+import { SchemaType, type FunctionDeclaration } from "@google/generative-ai";
+
+/**
+ * Tool for creating inline comments on specific code lines
+ */
+export const createInlineCommentTool: FunctionDeclaration = {
+  name: "create_inline_comment",
+  description:
+    "Create an inline comment on a specific line of code in the pull request. Use this to provide targeted feedback on specific code changes.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      path: {
+        type: SchemaType.STRING,
+        description: "The file path relative to the repository root",
+      },
+      line: {
+        type: SchemaType.NUMBER,
+        description: "The line number to comment on (1-indexed)",
+      },
+      content: {
+        type: SchemaType.STRING,
+        description:
+          "The comment content in markdown format. Be specific and actionable.",
+      },
+    },
+    required: ["path", "line", "content"],
+  },
+};
+
+/**
+ * Tool for creating a general PR comment
+ */
+export const createPRCommentTool: FunctionDeclaration = {
+  name: "create_pr_comment",
+  description:
+    "Create a general comment on the pull request. Use this for overall feedback, summaries, or questions that are not specific to a particular line of code.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      content: {
+        type: SchemaType.STRING,
+        description:
+          "The comment content in markdown format. Structure your feedback clearly.",
+      },
+    },
+    required: ["content"],
+  },
+};
+
+/**
+ * Tool for updating the tracking comment
+ */
+export const updateTrackingCommentTool: FunctionDeclaration = {
+  name: "update_tracking_comment",
+  description:
+    "Update the AI assistant's tracking comment to show progress or final results.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      content: {
+        type: SchemaType.STRING,
+        description: "The updated content for the tracking comment in markdown",
+      },
+      status: {
+        type: SchemaType.STRING,
+        enum: ["in_progress", "completed", "failed"],
+        description: "The current status of the review",
+      },
+    },
+    required: ["content", "status"],
+  },
+};
+
+/**
+ * Tool for reading file contents
+ */
+export const readFileTool: FunctionDeclaration = {
+  name: "read_file",
+  description:
+    "Read the contents of a file from the repository. Use this to understand the full context of code changes.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      path: {
+        type: SchemaType.STRING,
+        description: "The file path relative to the repository root",
+      },
+      startLine: {
+        type: SchemaType.NUMBER,
+        description: "Optional starting line number (1-indexed)",
+      },
+      endLine: {
+        type: SchemaType.NUMBER,
+        description: "Optional ending line number (1-indexed)",
+      },
+    },
+    required: ["path"],
+  },
+};
+
+/**
+ * Tool for searching code in the repository
+ */
+export const searchCodeTool: FunctionDeclaration = {
+  name: "search_code",
+  description:
+    "Search for code patterns or text in the repository. Use this to find related code, usages, or definitions.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      query: {
+        type: SchemaType.STRING,
+        description: "The search query (supports regex)",
+      },
+      filePattern: {
+        type: SchemaType.STRING,
+        description: "Optional glob pattern to filter files (e.g., '*.ts')",
+      },
+      maxResults: {
+        type: SchemaType.NUMBER,
+        description: "Maximum number of results to return (default: 20)",
+      },
+    },
+    required: ["query"],
+  },
+};
+
+/**
+ * Tool for getting pipeline/CI status
+ */
+export const getPipelineStatusTool: FunctionDeclaration = {
+  name: "get_pipeline_status",
+  description:
+    "Get the current status of the pipeline builds for this PR or branch.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      includeHistory: {
+        type: SchemaType.BOOLEAN,
+        description: "Include recent build history (default: false)",
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * Tool for suggesting code fixes
+ */
+export const suggestFixTool: FunctionDeclaration = {
+  name: "suggest_fix",
+  description:
+    "Suggest a code fix for a specific issue. This creates a code suggestion that can be applied directly.",
+  parameters: {
+    type: SchemaType.OBJECT,
+    properties: {
+      path: {
+        type: SchemaType.STRING,
+        description: "The file path relative to the repository root",
+      },
+      startLine: {
+        type: SchemaType.NUMBER,
+        description: "The starting line number of the code to replace",
+      },
+      endLine: {
+        type: SchemaType.NUMBER,
+        description: "The ending line number of the code to replace",
+      },
+      suggestedCode: {
+        type: SchemaType.STRING,
+        description: "The suggested replacement code",
+      },
+      explanation: {
+        type: SchemaType.STRING,
+        description: "Brief explanation of why this change is suggested",
+      },
+    },
+    required: ["path", "startLine", "endLine", "suggestedCode", "explanation"],
+  },
+};
+
+/**
+ * All available tools for code review
+ */
+export const codeReviewTools: FunctionDeclaration[] = [
+  createInlineCommentTool,
+  createPRCommentTool,
+  updateTrackingCommentTool,
+  readFileTool,
+  searchCodeTool,
+  getPipelineStatusTool,
+  suggestFixTool,
+];
+
+/**
+ * Subset of tools for lightweight reviews
+ */
+export const lightweightReviewTools: FunctionDeclaration[] = [
+  createInlineCommentTool,
+  createPRCommentTool,
+  readFileTool,
+];
+
+/**
+ * Get tools based on mode
+ */
+export function getToolsForMode(
+  mode: "full" | "lightweight" | "agent"
+): FunctionDeclaration[] {
+  switch (mode) {
+    case "full":
+      return codeReviewTools;
+    case "lightweight":
+      return lightweightReviewTools;
+    case "agent":
+      return codeReviewTools;
+    default:
+      return lightweightReviewTools;
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Bitbucket Gemini Action
+ * Main entry point for the action
+ */
+
+export { prepare } from "./entrypoints/prepare.js";
+export { execute } from "./entrypoints/execute.js";
+
+// Bitbucket API
+export { BitbucketClient } from "./bitbucket/api/client.js";
+export { parseBitbucketContext } from "./bitbucket/context.js";
+export type {
+  BitbucketPullRequest,
+  BitbucketComment,
+  BitbucketUser,
+  ParsedBitbucketContext,
+} from "./bitbucket/types.js";
+
+// Gemini API
+export { GeminiClient } from "./gemini/client.js";
+export { codeReviewTools, getToolsForMode } from "./gemini/tools.js";
+export {
+  buildPRReviewPrompt,
+  buildTagModePrompt,
+  buildAgentModePrompt,
+} from "./gemini/prompts.js";
+
+// Modes
+export { detectMode, getMode, shouldAnyModeTrigger } from "./modes/registry.js";
+export type { Mode, ModeName, ModeContext } from "./modes/types.js";
+
+// Utils
+export { getEnvConfig, getGeminiApiKey } from "./utils/env.js";
+export { withRetry } from "./utils/retry.js";
+
+/**
+ * Run the full action (prepare + execute)
+ */
+export async function run(): Promise<void> {
+  const { prepare } = await import("./entrypoints/prepare.js");
+  const { execute } = await import("./entrypoints/execute.js");
+
+  const prepareResult = await prepare();
+
+  if (!prepareResult.success) {
+    console.error("Prepare phase failed:", prepareResult.error);
+    process.exit(1);
+  }
+
+  if (!prepareResult.shouldContinue) {
+    console.log("No action needed:", prepareResult.error || "No trigger");
+    process.exit(0);
+  }
+
+  const executeResult = await execute();
+
+  if (!executeResult.success) {
+    console.error("Execute phase failed:", executeResult.error);
+    process.exit(1);
+  }
+
+  console.log("Action completed successfully");
+}
+
+// Run if executed directly
+if (import.meta.main) {
+  run().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}