Diff: Use doc_name when returned by the CLI

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.

use Diff.DiffResult

- import Diff instead of explicit type DiffResponse
- use Diff.DiffResult

Require version v2.10.1 of bump-cli (cf previous commit)

cf related PR on CLI bump-sh/cli#828

Author: Polo2

src/diff.ts

@@ -1,8 +1,8 @@
 import type { Repo } from './github.js';
-import type { DiffResponse } from 'bump-cli';
+import { Diff } from 'bump-cli';
 import { bumpDiffComment, shaDigest } from './common.js';
 
-export async function run(diff: DiffResponse, repo: Repo): Promise<void> {
+export async function run(diff: Diff.DiffResult, repo: Repo): Promise<void> {
   const digestContent = [diff.markdown];
   if (diff.public_url) {
     digestContent.push(diff.public_url);
@@ -13,7 +13,7 @@ export async function run(diff: DiffResponse, repo: Repo): Promise<void> {
   return repo.createOrUpdateComment(body, digest);
 }
 
-function buildCommentBody(repo: Repo, diff: DiffResponse, digest: string) {
+function buildCommentBody(repo: Repo, diff: Diff.DiffResult, digest: string) {
   const emptySpace = '';
   const poweredByBump = '###### _Powered by [Bump.sh](https://bump.sh)_';
   let text = 'No structural change, nothing to display.';
@@ -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: Diff.DiffResult, docName: string): string {
   const structureTitle = `### 🤖 ${docName} API structural change detected`;
   const contentTitle = `### ℹ️ ${docName} API content change detected`;
   const breakingTitle = `### 🚨 Breaking ${docName} API change detected`;
@@ -52,7 +46,7 @@ function title(diff: DiffResponse, doc: string, hub?: string, branch?: string):
   }
 }
 
-function viewDiffLink(diff: DiffResponse): string {
+function viewDiffLink(diff: Diff.DiffResult): string {
   if (diff.public_url) {
     return `
 [Preview documentation](${diff.public_url!})
@@ -61,3 +55,23 @@ function viewDiffLink(diff: DiffResponse): string {
     return '';
   }
 }
+
+function docName(
+  diff: Diff.DiffResult,
+  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;
+}

src/main.ts

@@ -100,7 +100,7 @@ export async function run(): Promise<void> {
             overlays1,
             overlays2,
           )
-          .then((result: bump.DiffResponse | undefined) => {
+          .then((result: bump.Diff.DiffResult | undefined) => {
             if (result) {
               diff.run(result, repo).catch(handleErrors);
             } else {

tests/diff.test.ts

@@ -32,7 +32,7 @@ describe('diff.ts', () => {
   });
 
   test('test github diff run process', async () => {
-    const result: bump.DiffResponse = {
+    const result: bump.Diff.DiffResult = {
       id: '123abc',
       markdown: `* one
 * two
@@ -60,6 +60,38 @@ 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.Diff.DiffResult = {
+      id: '123abc',
+      markdown: `**Doc has a name**`,
+      public_url: 'https://bump.sh/doc/my-doc/changes/654',
+      breaking: false,
+      doc_name: 'My API Documentation',
+    };
+    const digest = 'ccc5f7d8e472d46cd38e108bf43fbc46243807a2';
+
+    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>
+
+**Doc has a name**
+
 </details>
 
 ###### _Powered by [Bump.sh](https://bump.sh)_
@@ -69,10 +101,11 @@ describe('diff.ts', () => {
   });
 
   test('test github diff with no structural change', async () => {
-    const result: bump.DiffResponse = {
+    const result: bump.Diff.DiffResult = {
       id: '123abc',
       public_url: 'https://bump.sh/doc/my-doc/changes/654',
       breaking: false,
+      doc_name: 'My API Documentation',
     };
     const digest = '3999a0fe6ad27841bd6342128f7028ab2cea1c57';
 
@@ -81,7 +114,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)
 
@@ -94,7 +127,7 @@ No structural change, nothing to display.
   });
 
   test('test github diff with breaking changes', async () => {
-    const result: bump.DiffResponse = {
+    const result: bump.Diff.DiffResult = {
       id: '123abc',
       markdown: `* one
 * two
@@ -129,7 +162,7 @@ No structural change, nothing to display.
   });
 
   test('test github diff without public url', async () => {
-    const result: bump.DiffResponse = {
+    const result: bump.Diff.DiffResult = {
       id: '123abc',
       markdown: `* one
 * two

tests/main.test.ts

@@ -11,7 +11,7 @@ nock.disableNetConnect();
 // Mock stdout/stderr
 stdout.start();
 
-import type { DiffResponse } from 'bump-cli';
+import { Diff } from 'bump-cli';
 
 // Mock the Bump CLI commands
 jest.unstable_mockModule('bump-cli', () => bump);
@@ -20,7 +20,7 @@ jest.unstable_mockModule('@actions/github', () => github);
 jest.unstable_mockModule('../src/github.js', () => repo);
 
 const originalGhToken = process.env['GITHUB_TOKEN'];
-const diffExample: DiffResponse = {
+const diffExample: Diff.DiffResult = {
   id: 'hello-123',
   markdown: 'one',
   public_url: 'https://bump.sh/doc/my-doc/changes/654',