feat: Add commit hash and GH user to commit info (#347)

Author: granny

docusaurus.config.ts

@@ -6,8 +6,11 @@ import footer from "./config/footer.config";
 import { env } from "process";
 import { Config } from "@docusaurus/types";
 import { Options } from "@docusaurus/plugin-content-docs";
+import { getFileCommitHash } from "@docusaurus/utils/src/gitUtils";
+import { AUTHOR_FALLBACK, AuthorData, commitCache, cacheAuthorData } from "./src/util/authorUtils";
 
 const preview = env.VERCEL_ENV === "preview";
+cacheAuthorData(preview);
 
 const url = (preview && `https://${env.VERCEL_URL}`) || "https://docs.papermc.io";
 
@@ -80,6 +83,28 @@ const config: Config = {
       headingIds: false,
     },
     format: "detect",
+    parseFrontMatter: async (params) => {
+      const result = await params.defaultParseFrontMatter(params);
+      let author: AuthorData = {
+        ...AUTHOR_FALLBACK,
+      };
+      if (process.env.NODE_ENV !== "development") {
+        const { commit } = await getFileCommitHash(params.filePath);
+        const username = commitCache.get(commit);
+        author = {
+          commit,
+          username: username ?? AUTHOR_FALLBACK.username,
+        };
+      }
+
+      return {
+        ...result,
+        frontMatter: {
+          ...result.frontMatter,
+          author: author,
+        },
+      };
+    },
   },
 
   themes: [

package.json

@@ -73,7 +73,8 @@
   "packageManager": "[email protected]+sha256.01c01eeb990e379b31ef19c03e9d06a14afa5250b82e81303f88721c99ff2e6f",
   "pnpm": {
     "patchedDependencies": {
-      "@docusaurus/[email protected]": "patches/@[email protected]"
+      "@docusaurus/[email protected]": "patches/@[email protected]",
+      "@docusaurus/[email protected]": "patches/@[email protected]"
     }
   }
 }

patches/@[email protected]

@@ -0,0 +1,128 @@
+diff --git a/src/gitUtils.ts b/src/gitUtils.ts
+index 869982b2241c30629df3b83c7c75b9ce9f6a35d1..c3116d7a725d4a5420286baac8147f4e821e5631 100644
+--- a/src/gitUtils.ts
++++ b/src/gitUtils.ts
+@@ -95,6 +95,13 @@ export async function getFileCommitDate(
+   timestamp: number;
+   author?: string;
+ }> {
++  await throwGitErrors(file);
++  const regex = retrieveCorrectRegex(includeAuthor);
++  const result = await runGitCommandOnFile(file, createArgs('', includeAuthor, age));
++  const match = matchFromRegex(file, regex, result);
++  return matchDateAndTimestamp(match, includeAuthor);
++}
++async function throwGitErrors(file: string) {
+   if (!hasGit()) {
+     throw new GitNotFoundError(
+       `Failed to retrieve git history for "${file}" because git is not installed.`,
+@@ -106,22 +113,39 @@ export async function getFileCommitDate(
+       `Failed to retrieve git history for "${file}" because the file does not exist.`,
+     );
+   }
++}
++
++function createArgs(format: string, includeAuthor?: boolean, age: 'oldest' | 'newest' = 'oldest') {
++  // We add a "RESULT:" prefix to make parsing easier
++  // See why: https://github.com/facebook/docusaurus/pull/10022
++  const resultFormat = includeAuthor ? 'RESULT:%ct,%an' : 'RESULT:%ct';
+ 
+   const args = [
+-    `--format=%ct${includeAuthor ? ',%an' : ''}`,
++    `--format=${includeAuthor === undefined ? format : resultFormat}`,
+     '--max-count=1',
+     age === 'oldest' ? '--follow --diff-filter=A' : undefined,
+   ]
+     .filter(Boolean)
+     .join(' ');
+ 
++  return args;
++}
++async function runGitCommandOnFile(file: string, args: string): Promise<{
++  code: number;
++  stdout: string;
++  stderr: string;
++}> {
++  const command = `git -c log.showSignature=false log ${args} -- "${path.basename(
++    file,
++  )}"`;
++
+   const result = await new Promise<{
+     code: number;
+     stdout: string;
+     stderr: string;
+   }>((resolve) => {
+     shell.exec(
+-      `git log ${args} -- "${path.basename(file)}"`,
++      command,
+       {
+         // Setting cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+         cwd: path.dirname(file),
+@@ -138,11 +162,19 @@ export async function getFileCommitDate(
+       `Failed to retrieve the git history for file "${file}" with exit code ${result.code}: ${result.stderr}`,
+     );
+   }
+-  let regex = /^(?<timestamp>\d+)$/;
+-  if (includeAuthor) {
+-    regex = /^(?<timestamp>\d+),(?<author>.+)$/;
+-  }
+ 
++  return result;
++}
++function retrieveCorrectRegex(includeAuthor: boolean) {
++  // We only parse the output line starting with our "RESULT:" prefix
++  // See why https://github.com/facebook/docusaurus/pull/10022
++  const regex = includeAuthor
++    ? /(?:^|\n)RESULT:(?<timestamp>\d+),(?<author>.+)(?:$|\n)/
++    : /(?:^|\n)RESULT:(?<timestamp>\d+)(?:$|\n)/;
++
++  return regex;
++}
++function matchFromRegex(file: string, regex: RegExp, result: { code: number; stdout: string; stderr: string; }): RegExpMatchArray {
+   const output = result.stdout.trim();
+ 
+   if (!output) {
+@@ -159,6 +191,13 @@ export async function getFileCommitDate(
+     );
+   }
+ 
++  return match;
++}
++function matchDateAndTimestamp(match: RegExpMatchArray, includeAuthor: boolean): {
++  date: Date;
++  timestamp: number;
++  author?: string;
++} {
+   const timestampInSeconds = Number(match.groups!.timestamp);
+   const timestamp = timestampInSeconds * 1_000;
+   const date = new Date(timestamp);
+@@ -168,3 +207,29 @@ export async function getFileCommitDate(
+   }
+   return {date, timestamp};
+ }
++
++/**
++ * Fetches the git history of a file and returns a relevant commit hash.
++ *
++ * @throws {@link GitNotFoundError} If git is not found in `PATH`.
++ * @throws {@link FileNotTrackedError} If the current file is not tracked by git.
++ * @throws Also throws when `git log` exited with non-zero, or when it outputs
++ * unexpected text.
++ */
++export async function getFileCommitHash(
++  /** Absolute path to the file. */
++  file: string,
++): Promise<{
++  /** The author's commit hash, as returned from git. */
++  commit: string;
++}>;
++
++export async function getFileCommitHash(file: string): Promise<{
++  commit: string;
++}> {
++  throwGitErrors(file);
++  const result = await runGitCommandOnFile(file, createArgs('RESULT:%h', undefined, 'newest'))
++  const regex = /(?:^|\n)RESULT:(?<commit>\w+)(?:$|\n)/;
++  const match = matchFromRegex(file, regex, result);
++  return {commit: match.groups!.commit!};
++}