feat(blog): add LastUpdateAuthor & LastUpdateTime (#9912)

Co-authored-by: OzakIOne <OzakIOne@users.noreply.github.com>
Co-authored-by: sebastien <lorber.sebastien@gmail.com>

packages/docusaurus-utils/src/__tests__/__fixtures__/simple-site/doc with space.md

@@ -0,0 +1 @@
+# Hoo hoo, if this path tricks you...

packages/docusaurus-utils/src/__tests__/__fixtures__/simple-site/hello.md

@@ -0,0 +1,7 @@
+---
+id: hello
+title: Hello, World !
+slug: /
+---
+
+Hello

packages/docusaurus-utils/src/__tests__/gitUtils.test.ts

@@ -9,6 +9,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import {createTempRepo} from '@testing-utils/git';
 import {FileNotTrackedError, getFileCommitDate} from '../gitUtils';
+import {getFileLastUpdate} from '../lastUpdateUtils';
 
 /* eslint-disable no-restricted-properties */
 function initializeTempRepo() {
@@ -136,4 +137,22 @@ describe('getFileCommitDate', () => {
       /Failed to retrieve git history for ".*nonexistent.txt" because the file does not exist./,
     );
   });
+
+  it('multiple files not tracked by git', async () => {
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+    const tempFilePath1 = path.join(repoDir, 'file1.md');
+    const tempFilePath2 = path.join(repoDir, 'file2.md');
+    await fs.writeFile(tempFilePath1, 'Lorem ipsum :)');
+    await fs.writeFile(tempFilePath2, 'Lorem ipsum :)');
+    await expect(getFileLastUpdate(tempFilePath1)).resolves.toBeNull();
+    await expect(getFileLastUpdate(tempFilePath2)).resolves.toBeNull();
+    expect(consoleMock).toHaveBeenCalledTimes(1);
+    expect(consoleMock).toHaveBeenLastCalledWith(
+      expect.stringMatching(/not tracked by git./),
+    );
+    await fs.unlink(tempFilePath1);
+    await fs.unlink(tempFilePath2);
+  });
 });

packages/docusaurus-utils/src/__tests__/lastUpdateUtils.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {jest} from '@jest/globals';
+import fs from 'fs-extra';
+import path from 'path';
+import {createTempRepo} from '@testing-utils/git';
+import shell from 'shelljs';
+import {
+  getFileLastUpdate,
+  GIT_FALLBACK_LAST_UPDATE_AUTHOR,
+  GIT_FALLBACK_LAST_UPDATE_DATE,
+  readLastUpdateData,
+} from '@docusaurus/utils';
+
+describe('getFileLastUpdate', () => {
+  const {repoDir} = createTempRepo();
+
+  const existingFilePath = path.join(
+    __dirname,
+    '__fixtures__/simple-site/hello.md',
+  );
+  it('existing test file in repository with Git timestamp', async () => {
+    const lastUpdateData = await getFileLastUpdate(existingFilePath);
+    expect(lastUpdateData).not.toBeNull();
+
+    const {author, timestamp} = lastUpdateData!;
+    expect(author).not.toBeNull();
+    expect(typeof author).toBe('string');
+
+    expect(timestamp).not.toBeNull();
+    expect(typeof timestamp).toBe('number');
+  });
+
+  it('existing test file with spaces in path', async () => {
+    const filePathWithSpace = path.join(
+      __dirname,
+      '__fixtures__/simple-site/doc with space.md',
+    );
+    const lastUpdateData = await getFileLastUpdate(filePathWithSpace);
+    expect(lastUpdateData).not.toBeNull();
+
+    const {author, timestamp} = lastUpdateData!;
+    expect(author).not.toBeNull();
+    expect(typeof author).toBe('string');
+
+    expect(timestamp).not.toBeNull();
+    expect(typeof timestamp).toBe('number');
+  });
+
+  it('non-existing file', async () => {
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+    const nonExistingFileName = '.nonExisting';
+    const nonExistingFilePath = path.join(
+      __dirname,
+      '__fixtures__',
+      nonExistingFileName,
+    );
+    await expect(getFileLastUpdate(nonExistingFilePath)).rejects.toThrow(
+      /An error occurred when trying to get the last update date/,
+    );
+    expect(consoleMock).toHaveBeenCalledTimes(0);
+    consoleMock.mockRestore();
+  });
+
+  it('git does not exist', async () => {
+    const mock = jest.spyOn(shell, 'which').mockImplementationOnce(() => null);
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+    const lastUpdateData = await getFileLastUpdate(existingFilePath);
+    expect(lastUpdateData).toBeNull();
+    expect(consoleMock).toHaveBeenLastCalledWith(
+      expect.stringMatching(
+        /.*\[WARNING\].* Sorry, the last update options require Git\..*/,
+      ),
+    );
+
+    consoleMock.mockRestore();
+    mock.mockRestore();
+  });
+
+  it('temporary created file that is not tracked by git', async () => {
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+    const tempFilePath = path.join(repoDir, 'file.md');
+    await fs.writeFile(tempFilePath, 'Lorem ipsum :)');
+    await expect(getFileLastUpdate(tempFilePath)).resolves.toBeNull();
+    expect(consoleMock).toHaveBeenCalledTimes(1);
+    expect(consoleMock).toHaveBeenLastCalledWith(
+      expect.stringMatching(/not tracked by git./),
+    );
+    await fs.unlink(tempFilePath);
+  });
+});
+
+describe('readLastUpdateData', () => {
+  const testDate = '2021-01-01';
+  const testDateTime = new Date(testDate).getTime() / 1000;
+  const testAuthor = 'ozaki';
+
+  it('read last time show author time', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: true},
+      {date: testDate},
+    );
+    expect(lastUpdatedAt).toEqual(testDateTime);
+    expect(lastUpdatedBy).toBe(GIT_FALLBACK_LAST_UPDATE_AUTHOR);
+  });
+
+  it('read last author show author time', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: true},
+      {author: testAuthor},
+    );
+    expect(lastUpdatedBy).toEqual(testAuthor);
+    expect(lastUpdatedAt).toBe(GIT_FALLBACK_LAST_UPDATE_DATE);
+  });
+
+  it('read last all show author time', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: true},
+      {author: testAuthor, date: testDate},
+    );
+    expect(lastUpdatedBy).toEqual(testAuthor);
+    expect(lastUpdatedAt).toEqual(testDateTime);
+  });
+
+  it('read last default show none', async () => {
+    const lastUpdate = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: false, showLastUpdateTime: false},
+      {},
+    );
+    expect(lastUpdate).toEqual({});
+  });
+
+  it('read last author show none', async () => {
+    const lastUpdate = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: false, showLastUpdateTime: false},
+      {author: testAuthor},
+    );
+    expect(lastUpdate).toEqual({});
+  });
+
+  it('read last time show author', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: false},
+      {date: testDate},
+    );
+    expect(lastUpdatedBy).toBe(GIT_FALLBACK_LAST_UPDATE_AUTHOR);
+    expect(lastUpdatedAt).toBeUndefined();
+  });
+
+  it('read last author show author', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: false},
+      {author: testAuthor},
+    );
+    expect(lastUpdatedBy).toBe('ozaki');
+    expect(lastUpdatedAt).toBeUndefined();
+  });
+
+  it('read last default show author default', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: false},
+      {},
+    );
+    expect(lastUpdatedBy).toBe(GIT_FALLBACK_LAST_UPDATE_AUTHOR);
+    expect(lastUpdatedAt).toBeUndefined();
+  });
+
+  it('read last time show time', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: false, showLastUpdateTime: true},
+      {date: testDate},
+    );
+    expect(lastUpdatedBy).toBeUndefined();
+    expect(lastUpdatedAt).toEqual(testDateTime);
+  });
+
+  it('read last author show time', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: false, showLastUpdateTime: true},
+      {author: testAuthor},
+    );
+    expect(lastUpdatedBy).toBeUndefined();
+    expect(lastUpdatedAt).toEqual(GIT_FALLBACK_LAST_UPDATE_DATE);
+  });
+
+  it('read last author show time only - both front matter', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: false, showLastUpdateTime: true},
+      {author: testAuthor, date: testDate},
+    );
+    expect(lastUpdatedBy).toBeUndefined();
+    expect(lastUpdatedAt).toEqual(testDateTime);
+  });
+
+  it('read last author show author only - both front matter', async () => {
+    const {lastUpdatedAt, lastUpdatedBy} = await readLastUpdateData(
+      '',
+      {showLastUpdateAuthor: true, showLastUpdateTime: false},
+      {author: testAuthor, date: testDate},
+    );
+    expect(lastUpdatedBy).toEqual(testAuthor);
+    expect(lastUpdatedAt).toBeUndefined();
+  });
+});