From 6616c79fe9c208ab729086371cbbf882ac4d6e39 Mon Sep 17 00:00:00 2001
From: Polo M2B <polo2bodi@gmail.com>
Date: Thu, 11 Jun 2026 11:29:38 +0200
Subject: [PATCH] Diff: Use doc_name when returned by the CLI

cf related PR on CLI https://github.com/bump-sh/cli/pull/828

When diff is requested to the CLI,
doc.id may has been used as doc parameter.

In this case, GitHub comment is not easy to read,
api.id has no sense on this comment.

We add a test in the docName logic (moved in its own function as tiny refacto),
and favor DiffResponse.doc_name when provided.

About retro-compatibiliy:
Even if DiffResponse.doc_name will be included in the next release
of bump-cli, field is missing for previous versions.

I handled the retro-compatibility with a
`bump.DiffResponse & { doc_name?: string }`
but I'm not very proud, WDYT dear reviewer?
---
 src/diff.ts        | 30 ++++++++++++++++++++++--------
 tests/diff.test.ts | 43 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 63 insertions(+), 10 deletions(-)

diff --git a/src/diff.ts b/src/diff.ts
index 72a2a869..2de4aa90 100644
--- a/src/diff.ts
+++ b/src/diff.ts
@@ -25,20 +25,14 @@ ${diff.markdown}
 </details>`;
   }
 
-  return [title(diff, repo.doc, repo.hub, repo.branch)]
+  return [title(diff, docName(diff, repo.doc, repo.hub, repo.branch))]
     .concat([viewDiffLink(diff)])
     .concat([text, emptySpace])
     .concat([poweredByBump, bumpDiffComment(repo.docDigest, digest)])
     .join('\n');
 }
 
-function title(diff: DiffResponse, doc: string, hub?: string, branch?: string): string {
-  let docName = [hub, doc].filter((e) => e).join('/');
-  // Capitalize doc name
-  docName = docName.charAt(0).toUpperCase() + docName.slice(1);
-  if (branch) {
-    docName = `${docName} (branch: ${branch})`;
-  }
+function title(diff: DiffResponse, docName: string): string {
   const structureTitle = `### 🤖 ${docName} API structural change detected`;
   const contentTitle = `### ℹ️ ${docName} API content change detected`;
   const breakingTitle = `### 🚨 Breaking ${docName} API change detected`;
@@ -61,3 +55,23 @@ function viewDiffLink(diff: DiffResponse): string {
     return '';
   }
 }
+
+function docName(
+  diff: DiffResponse & { doc_name?: string },
+  doc: string,
+  hub?: string,
+  branch?: string,
+): string {
+  const docNameFromDiff = diff.doc_name;
+  let name: string;
+  if (docNameFromDiff) {
+    name = docNameFromDiff;
+  } else {
+    name = [hub, doc].filter((e) => e).join('/');
+    name = name.charAt(0).toUpperCase() + name.slice(1);
+  }
+  if (branch) {
+    name = `${name} (branch: ${branch})`;
+  }
+  return name;
+}
diff --git a/tests/diff.test.ts b/tests/diff.test.ts
index 6fd2f7b3..b22c7e5e 100644
--- a/tests/diff.test.ts
+++ b/tests/diff.test.ts
@@ -60,6 +60,44 @@ describe('diff.ts', () => {
 * three
 
 
+</details>
+
+###### _Powered by [Bump.sh](https://bump.sh)_
+<!-- Bump.sh digest=${digest} doc=${docDigest} -->`,
+      digest,
+    );
+  });
+
+  test('test github diff run process (with doc_name)', async () => {
+    const result: bump.DiffResponse & { doc_name?: string } = {
+      id: '123abc',
+      markdown: `* one
+* two
+* three
+`,
+      public_url: 'https://bump.sh/doc/my-doc/changes/654',
+      breaking: false,
+      doc_name: 'My API Documentation',
+    };
+    const digest = '4b81e612cafa6580f8ad3bfe9e970b2d961f58c2';
+
+    const repo = new Repo('id-42', '', 'v2');
+    const docDigest = shaDigest(['id-42', '', 'v2']);
+
+    await diff.run(result, repo);
+
+    expect(repo.createOrUpdateComment).toHaveBeenCalledWith(
+      `### 🤖 My API Documentation (branch: v2) API structural change detected
+
+[Preview documentation](https://bump.sh/doc/my-doc/changes/654)
+
+<details open><summary>Structural change details</summary>
+
+* one
+* two
+* three
+
+
 </details>
 
 ###### _Powered by [Bump.sh](https://bump.sh)_
@@ -69,10 +107,11 @@ describe('diff.ts', () => {
   });
 
   test('test github diff with no structural change', async () => {
-    const result: bump.DiffResponse = {
+    const result: bump.DiffResponse & { doc_name?: string } = {
       id: '123abc',
       public_url: 'https://bump.sh/doc/my-doc/changes/654',
       breaking: false,
+      doc_name: 'My API Documentation',
     };
     const digest = '3999a0fe6ad27841bd6342128f7028ab2cea1c57';
 
@@ -81,7 +120,7 @@ describe('diff.ts', () => {
     await diff.run(result, repo);
 
     expect(repo.createOrUpdateComment).toHaveBeenCalledWith(
-      `### ℹ️ My-hub/hello (branch: v1) API content change detected
+      `### ℹ️ My API Documentation (branch: v1) API content change detected
 
 [Preview documentation](https://bump.sh/doc/my-doc/changes/654)