@atlassian-dc-mcp/bitbucket 0.32.0 → 0.33.0

package/src/__tests__/bitbucket-service.test.ts

@@ -1212,6 +1212,168 @@ describe('BitbucketService', () => {
     });
   });
 
+  describe('getBranchDiff', () => {
+    const { request: mockRequest } = require('../bitbucket-client/core/request.js');
+    // Trimmed capture of a real Bitbucket DC 9.x compare/diff response.
+    const mockCompareDiff = {
+      fromHash: '4ab70c4ea742bd2102e929a3b58811a69a46ff23',
+      toHash: 'feature/my-branch',
+      diffs: [
+        {
+          source: { toString: 'Dockerfile' },
+          destination: { toString: 'Dockerfile' },
+          hunks: [
+            {
+              sourceLine: 1,
+              sourceSpan: 2,
+              destinationLine: 1,
+              destinationSpan: 3,
+              segments: [
+                { type: 'CONTEXT', lines: [{ line: 'FROM node:20-alpine' }] },
+                { type: 'ADDED', lines: [{ line: 'COPY shbdn ./shbdn' }] },
+                { type: 'REMOVED', lines: [{ line: 'RUN npm ci' }] }
+              ]
+            }
+          ]
+        }
+      ],
+      truncated: false
+    };
+
+    it('should diff the whole comparison against the default branch when only a source branch is given', async () => {
+      mockRequest.mockResolvedValue(mockCompareDiff);
+
+      const result = await bitbucketService.getBranchDiff(
+        mockProjectKey,
+        mockRepositorySlug,
+        'feature/my-branch'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(
+        'diff --git a/Dockerfile b/Dockerfile\n' +
+        '--- a/Dockerfile\n' +
+        '+++ b/Dockerfile\n' +
+        '@@ -1,2 +1,3 @@\n' +
+        ' FROM node:20-alpine\n' +
+        '+COPY shbdn ./shbdn\n' +
+        '-RUN npm ci'
+      );
+      expect(mockRequest).toHaveBeenCalledWith(
+        expect.any(Object),
+        {
+          method: 'GET',
+          url: '/api/latest/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path}',
+          path: {
+            'path': '',
+            'projectKey': mockProjectKey,
+            'repositorySlug': mockRepositorySlug,
+          },
+          query: {
+            'from': 'feature/my-branch',
+            'to': undefined,
+            'contextLines': undefined,
+            'srcPath': undefined,
+            'whitespace': undefined,
+          },
+          errors: {
+            401: `The currently authenticated user has insufficient permissions to view the repository.`,
+            404: `The repository, or one of the compared refs, does not exist.`,
+          },
+        }
+      );
+    });
+
+    it('should not request text/plain, which the compare resource rejects with 406', async () => {
+      mockRequest.mockResolvedValue(mockCompareDiff);
+
+      await bitbucketService.getBranchDiff(mockProjectKey, mockRepositorySlug, 'feature/my-branch');
+
+      expect(mockRequest).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.not.objectContaining({ headers: expect.anything() })
+      );
+    });
+
+    it('should pass all optional parameters through and normalize the file path', async () => {
+      mockRequest.mockResolvedValue(mockCompareDiff);
+
+      const result = await bitbucketService.getBranchDiff(
+        mockProjectKey,
+        mockRepositorySlug,
+        'feature/my-branch',
+        'main',
+        '/src/file.txt',
+        '5',
+        'old/file.txt',
+        'ignore-all'
+      );
+
+      expect(result.success).toBe(true);
+      expect(mockRequest).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({
+          path: expect.objectContaining({ 'path': '/src/file.txt' }),
+          query: {
+            'from': 'feature/my-branch',
+            'to': 'main',
+            'contextLines': '5',
+            'srcPath': 'old/file.txt',
+            'whitespace': 'ignore-all',
+          },
+        })
+      );
+    });
+
+    it('should return the raw payload when output is full', async () => {
+      mockRequest.mockResolvedValue(mockCompareDiff);
+
+      const result = await bitbucketService.getBranchDiff(
+        mockProjectKey,
+        mockRepositorySlug,
+        'feature/my-branch',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        'full'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(mockCompareDiff);
+    });
+
+    it('should normalize project key and repository slug casing', async () => {
+      mockRequest.mockResolvedValue(mockCompareDiff);
+
+      await bitbucketService.getBranchDiff('test', 'TEST-REPO', 'feature/my-branch');
+
+      expect(mockRequest).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({
+          path: expect.objectContaining({
+            'projectKey': 'TEST',
+            'repositorySlug': 'test-repo',
+          }),
+        })
+      );
+    });
+
+    it('should handle API errors gracefully', async () => {
+      mockRequest.mockRejectedValue(new Error('API Error'));
+
+      const result = await bitbucketService.getBranchDiff(
+        mockProjectKey,
+        mockRepositorySlug,
+        'feature/my-branch'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('API Error');
+    });
+  });
+
   describe('getFileContent', () => {
     const mockFileContent = 'FROM node:20-alpine\n\nWORKDIR /app\n';
 

package/src/__tests__/compare-diff-mapper.test.ts

@@ -0,0 +1,116 @@
+import { formatCompareDiffAsUnified } from '../compare-diff-mapper.js';
+
+describe('formatCompareDiffAsUnified', () => {
+  it('should report an empty comparison', () => {
+    expect(formatCompareDiffAsUnified({ diffs: [] })).toBe('No differences found.');
+    expect(formatCompareDiffAsUnified({})).toBe('No differences found.');
+  });
+
+  it('should render added and removed files against /dev/null', () => {
+    const result = formatCompareDiffAsUnified({
+      diffs: [
+        {
+          source: null,
+          destination: { toString: 'new-file.js' },
+          hunks: [
+            {
+              sourceLine: 0,
+              sourceSpan: 0,
+              destinationLine: 1,
+              destinationSpan: 1,
+              segments: [{ type: 'ADDED', lines: [{ line: 'export const a = 1;' }] }]
+            }
+          ]
+        },
+        {
+          source: { toString: 'old-file.js' },
+          destination: null,
+          hunks: [
+            {
+              sourceLine: 1,
+              sourceSpan: 1,
+              destinationLine: 0,
+              destinationSpan: 0,
+              segments: [{ type: 'REMOVED', lines: [{ line: 'export const b = 2;' }] }]
+            }
+          ]
+        }
+      ]
+    });
+
+    expect(result).toBe(
+      'diff --git a/new-file.js b/new-file.js\n' +
+      '--- /dev/null\n' +
+      '+++ b/new-file.js\n' +
+      '@@ -0,0 +1,1 @@\n' +
+      '+export const a = 1;\n' +
+      'diff --git a/old-file.js b/old-file.js\n' +
+      '--- a/old-file.js\n' +
+      '+++ /dev/null\n' +
+      '@@ -1,1 +0,0 @@\n' +
+      '-export const b = 2;'
+    );
+  });
+
+  it('should note files without a textual diff', () => {
+    const result = formatCompareDiffAsUnified({
+      diffs: [{ source: { toString: 'logo.png' }, destination: { toString: 'logo.png' } }]
+    });
+
+    expect(result).toContain('[no textual diff available]');
+  });
+
+  it('should surface server-side truncation at hunk, file and diff level', () => {
+    const result = formatCompareDiffAsUnified({
+      truncated: true,
+      diffs: [
+        {
+          source: { toString: 'big.txt' },
+          destination: { toString: 'big.txt' },
+          truncated: true,
+          hunks: [{ sourceLine: 1, sourceSpan: 1, destinationLine: 1, destinationSpan: 1, segments: [], truncated: true }]
+        }
+      ]
+    });
+
+    expect(result).toContain('[hunk truncated by the Bitbucket server]');
+    expect(result).toContain('[file diff truncated by the Bitbucket server]');
+    expect(result).toContain('[diff truncated by the Bitbucket server; narrow the comparison with `path`]');
+  });
+
+  it('should prefix segments by type and default unknown types to context', () => {
+    const result = formatCompareDiffAsUnified({
+      diffs: [
+        {
+          source: { toString: 'f.txt' },
+          destination: { toString: 'f.txt' },
+          hunks: [
+            {
+              sourceLine: 10,
+              sourceSpan: 3,
+              destinationLine: 10,
+              destinationSpan: 4,
+              segments: [
+                { type: 'CONTEXT', lines: [{ line: 'keep' }] },
+                { type: 'REMOVED', lines: [{ line: 'gone' }] },
+                { type: 'ADDED', lines: [{ line: 'fresh' }] },
+                { type: 'SOMETHING_NEW', lines: [{ line: 'unknown' }] }
+              ]
+            }
+          ]
+        }
+      ]
+    });
+
+    expect(result).toBe(
+      'diff --git a/f.txt b/f.txt\n' +
+      '--- a/f.txt\n' +
+      '+++ b/f.txt\n' +
+      '@@ -10,3 +10,4 @@\n' +
+      ' keep\n' +
+      '-gone\n' +
+      '+fresh\n' +
+      ' unknown'
+    );
+  });
+});

package/src/bitbucket-service.ts

@@ -3,6 +3,7 @@ import { OpenAPI, ProjectService, PullRequestsService, RepositoryService } from
 import { request as __request } from './bitbucket-client/core/request.js';
 import { handleApiOperation, resolveOpenApiBase } from '@atlassian-dc-mcp/common';
 import { simplifyInboxPullRequests } from './inbox-pr-mapper.js';
+import { CompareDiffResponse, formatCompareDiffAsUnified } from './compare-diff-mapper.js';
 import { BITBUCKET_PRODUCT, getDefaultPageSize, getMissingConfig } from './config.js';
 import { fetchMergeability, mergePullRequest, type MergePullRequestParams } from './pr-merge.js';
 import {
@@ -26,6 +27,8 @@ function resolveToken(token: string | (() => string | undefined), missingTokenMe
 
 type DiffLineType = 'ADDED' | 'REMOVED' | 'CONTEXT';
 
+type BranchDiffOutputMode = 'unified' | 'full';
+
 /**
  * Build a Bitbucket DC inline comment anchor.
  *
@@ -704,6 +707,66 @@ export class BitbucketService {
     );
   }
 
+  /**
+   * Get text diff between two branches, with or without an existing pull request.
+   *
+   * Mirrors the Bitbucket "compare" view: the diff contains changes reachable from
+   * `sourceBranch` but not from `targetBranch`.
+   * @param projectKey The project key
+   * @param repositorySlug The repository slug
+   * @param sourceBranch The source branch, tag or commit
+   * @param targetBranch Optional target branch, tag or commit. Defaults to the repository default branch
+   * @param path Optional file path to limit the diff to a single file
+   * @param contextLines Optional number of context lines to include around added/removed lines
+   * @param srcPath Optional previous path to the file, if the file has been copied, moved or renamed
+   * @param whitespace Optional whitespace flag which can be set to 'ignore-all'
+   * @param output Render a unified diff or return the raw RestDiff payload. Defaults to 'unified'
+   * @returns Promise with the diff between the two refs
+   */
+  async getBranchDiff(
+    projectKey: string,
+    repositorySlug: string,
+    sourceBranch: string,
+    targetBranch?: string,
+    path?: string,
+    contextLines?: string,
+    srcPath?: string,
+    whitespace?: string,
+    output: BranchDiffOutputMode = 'unified'
+  ) {
+    projectKey = projectKey.toUpperCase();
+    repositorySlug = repositorySlug.toLowerCase();
+    // The endpoint is `/compare/diff{path}`: an empty path diffs the whole comparison,
+    // a file path must keep its leading slash to stay a separate URL segment.
+    const trimmedPath = path?.replace(/^\/+/, '') ?? '';
+    return handleApiOperation(
+      async () => {
+        const diff = await __request<CompareDiffResponse>(OpenAPI, {
+          method: 'GET',
+          url: '/api/latest/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path}',
+          path: {
+            'path': trimmedPath ? `/${trimmedPath}` : '',
+            'projectKey': projectKey,
+            'repositorySlug': repositorySlug,
+          },
+          query: {
+            'from': sourceBranch,
+            'to': targetBranch,
+            'contextLines': contextLines,
+            'srcPath': srcPath,
+            'whitespace': whitespace,
+          },
+          errors: {
+            401: `The currently authenticated user has insufficient permissions to view the repository.`,
+            404: `The repository, or one of the compared refs, does not exist.`,
+          },
+        });
+        return output === 'full' ? diff : formatCompareDiffAsUnified(diff);
+      },
+      'Error fetching branch diff'
+    );
+  }
+
   /**
    * Create a pull request
    * @param projectKey The project key (also used as the destination repository's project)
@@ -1133,6 +1196,17 @@ export const bitbucketToolSchemas = {
     untilId: z.string().optional().describe("The until commit hash to stream a diff between two arbitrary hashes"),
     whitespace: z.string().optional().describe("Optional whitespace flag which can be set to 'ignore-all'")
   },
+  getBranchDiff: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    sourceBranch: z.string().describe("The source branch, tag or commit to diff (e.g. 'feature/my-branch'). Changes reachable from here but not from targetBranch are returned"),
+    targetBranch: z.string().optional().describe("The target branch, tag or commit to compare against. Defaults to the repository's default branch"),
+    path: z.string().optional().describe("Limit the diff to a single file path. Omit to get the diff for every changed file"),
+    contextLines: z.string().optional().describe("Number of context lines to include around added/removed lines in the diff"),
+    srcPath: z.string().optional().describe("The previous path to the file, if the file has been copied, moved or renamed"),
+    whitespace: z.string().optional().describe("Optional whitespace flag which can be set to 'ignore-all'"),
+    output: z.enum(['unified', 'full']).optional().describe("Render the comparison as a unified diff or return the raw RestDiff payload. Defaults to unified.")
+  },
   createPullRequest: {
     projectKey: z.string().describe("The destination repository's project key"),
     repositorySlug: z.string().describe("The destination repository's slug"),

package/src/compare-diff-mapper.ts

@@ -0,0 +1,99 @@
+// Shape of the `RestDiff` payload returned by the Bitbucket compare/diff resource.
+interface DiffLine {
+  line: string;
+  truncated?: boolean;
+}
+
+interface DiffSegment {
+  type: string;
+  lines?: DiffLine[];
+}
+
+interface DiffHunk {
+  sourceLine?: number;
+  sourceSpan?: number;
+  destinationLine?: number;
+  destinationSpan?: number;
+  segments?: DiffSegment[];
+  truncated?: boolean;
+}
+
+interface FileDiff {
+  source?: { toString: string } | null;
+  destination?: { toString: string } | null;
+  hunks?: DiffHunk[];
+  truncated?: boolean;
+}
+
+export interface CompareDiffResponse {
+  fromHash?: string;
+  toHash?: string;
+  diffs?: FileDiff[];
+  truncated?: boolean;
+}
+
+const SEGMENT_PREFIXES: Record<string, string> = {
+  ADDED: '+',
+  REMOVED: '-',
+  CONTEXT: ' ',
+};
+
+function renderHunk(hunk: DiffHunk, out: string[]): void {
+  out.push(`@@ -${hunk.sourceLine ?? 0},${hunk.sourceSpan ?? 0} +${hunk.destinationLine ?? 0},${hunk.destinationSpan ?? 0} @@`);
+  for (const segment of hunk.segments ?? []) {
+    const prefix = SEGMENT_PREFIXES[segment.type] ?? ' ';
+    for (const line of segment.lines ?? []) {
+      out.push(`${prefix}${line.line}`);
+    }
+  }
+  if (hunk.truncated) {
+    out.push('[hunk truncated by the Bitbucket server]');
+  }
+}
+
+function renderFile(file: FileDiff, out: string[]): void {
+  // A missing source means the file was added, a missing destination that it was deleted.
+  const source = file.source?.toString;
+  const destination = file.destination?.toString;
+  const oldPath = source ? `a/${source}` : '/dev/null';
+  const newPath = destination ? `b/${destination}` : '/dev/null';
+
+  out.push(`diff --git ${source ? `a/${source}` : `a/${destination}`} ${destination ? `b/${destination}` : `b/${source}`}`);
+  out.push(`--- ${oldPath}`);
+  out.push(`+++ ${newPath}`);
+
+  const hunks = file.hunks ?? [];
+  if (hunks.length === 0) {
+    // Bitbucket omits hunks for binary files and for pure mode/rename changes.
+    out.push('[no textual diff available]');
+  }
+  for (const hunk of hunks) {
+    renderHunk(hunk, out);
+  }
+  if (file.truncated) {
+    out.push('[file diff truncated by the Bitbucket server]');
+  }
+}
+
+/**
+ * Render a Bitbucket `RestDiff` payload as a unified diff.
+ *
+ * The compare resource only speaks JSON (it answers 406 to `Accept: text/plain`, unlike the
+ * pull request diff resource), so the structured payload is folded into the far more compact
+ * unified format that models already understand.
+ */
+export function formatCompareDiffAsUnified(diff: CompareDiffResponse): string {
+  const files = diff.diffs ?? [];
+  if (files.length === 0) {
+    return 'No differences found.';
+  }
+
+  const out: string[] = [];
+  for (const file of files) {
+    renderFile(file, out);
+  }
+  if (diff.truncated) {
+    out.push('[diff truncated by the Bitbucket server; narrow the comparison with `path`]');
+  }
+  return out.join('\n');
+}

package/src/index.ts

@@ -179,6 +179,16 @@ server.tool(
   }
 );
 
+server.tool(
+  "bitbucket_getBranchDiff",
+  "Get the diff between two branches, tags or commits — including branches that have no pull request yet. Returns the same comparison as the Bitbucket 'compare' view: changes reachable from sourceBranch but not from targetBranch, rendered as a unified diff. targetBranch defaults to the repository's default branch. Use this to review work in progress before a PR exists; once a PR exists, prefer bitbucket_getPullRequestChanges + bitbucket_getPullRequestDiff.",
+  bitbucketToolSchemas.getBranchDiff,
+  async ({ projectKey, repositorySlug, sourceBranch, targetBranch, path, contextLines, srcPath, whitespace, output }) => {
+    const result = await bitbucketService.getBranchDiff(projectKey, repositorySlug, sourceBranch, targetBranch, path, contextLines, srcPath, whitespace, output);
+    return formatToolResponse(result);
+  }
+);
+
 server.tool(
   "bitbucket_createPullRequest",
   "Create a new pull request in a Bitbucket repository. Supports fork-based pull requests by passing fromProjectKey/fromRepositorySlug when the source repository differs from the destination (projectKey/repositorySlug). IMPORTANT: Before creating a PR, use bitbucket_getRequiredReviewers to fetch required reviewers for the source and target branches to ensure the PR is not created without mandatory reviewers.",