feat(utils): add git helper

packages/utils/src/lib/git.integration.test.ts

@@ -2,11 +2,20 @@ import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { type SimpleGit, simpleGit } from 'simple-git';
 import { expect } from 'vitest';
-import { getGitRoot, getLatestCommit, toGitPath } from './git';
+import {
+  getCurrentBranchOrTag,
+  getGitRoot,
+  getLatestCommit,
+  guardAgainstLocalChanges,
+  safeCheckout,
+  statusIsClean,
+  toGitPath,
+} from './git';
 import { toUnixPath } from './transform';
 
-describe('git utils', () => {
+describe('git utils in a git repo with a branch and commits', () => {
   const baseDir = join(process.cwd(), 'tmp', 'testing-git-repo');
+  const changesDir = join(baseDir, 'changes-dir');
   let git: SimpleGit;
 
   beforeAll(async () => {
@@ -21,12 +30,19 @@ describe('git utils', () => {
 
     await git.add('README.md');
     await git.commit('Create README');
+
+    await git.checkout(['-b', 'feature-branch']);
   });
 
   afterAll(async () => {
     await rm(baseDir, { recursive: true, force: true });
   });
 
+  afterEach(async () => {
+    await rm(changesDir, { recursive: true, force: true });
+    await git.checkout(['master']);
+  });
+
   it('should log latest commit', async () => {
     const gitCommitDateRegex =
       /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{1,2} \d{2}:\d{2}:\d{2} \d{4} [+|-]\d{4}$/;
@@ -60,4 +76,86 @@ describe('git utils', () => {
       'Backend/API/Startup.cs',
     );
   });
+
+  it('statusIsClean should return false if some changes are given', async () => {
+    await mkdir(changesDir, { recursive: true });
+    await writeFile(join(changesDir, 'change.md'), '# hello-change\n');
+    await expect(statusIsClean(git)).resolves.toBe(false);
+  });
+
+  it('statusIsClean should return true if no changes are given', async () => {
+    await expect(statusIsClean(git)).resolves.toBe(true);
+  });
+
+  it('guardAgainstLocalChanges should throw if history is dirty', async () => {
+    await mkdir(changesDir, { recursive: true });
+    await writeFile(join(changesDir, 'change.md'), '# hello-change\n');
+    await expect(guardAgainstLocalChanges(git)).rejects.toThrow(
+      'Working directory needs to be clean before we you can proceed. Commit your local changes or stash them.',
+    );
+  });
+
+  it('guardAgainstLocalChanges should not throw if history is clean', async () => {
+    await expect(guardAgainstLocalChanges(git)).resolves.toBeUndefined();
+  });
+
+  it('safeCheckout should checkout target branch in clean state', async () => {
+    await expect(git.branch()).resolves.toEqual(
+      expect.objectContaining({ current: 'master' }),
+    );
+    await expect(
+      safeCheckout('feature-branch', {}, git),
+    ).resolves.toBeUndefined();
+    await expect(git.branch()).resolves.toEqual(
+      expect.objectContaining({ current: 'feature-branch' }),
+    );
+  });
+
+  it('safeCheckout should throw if history is dirty', async () => {
+    await mkdir(changesDir, { recursive: true });
+    await writeFile(join(changesDir, 'change.md'), '# hello-change\n');
+    await expect(safeCheckout('master', {}, git)).rejects.toThrow(
+      'Working directory needs to be clean before we you can proceed. Commit your local changes or stash them.',
+    );
+  });
+
+  it('safeCheckout should clean local changes and check out to master', async () => {
+    // needs to get reset to be clean
+    await mkdir(changesDir, { recursive: true });
+    await writeFile(join(changesDir, 'change.md'), '# hello-change\n');
+    // needs to get cleaned to be clean
+    await writeFile(join(baseDir, 'README.md'), '# hello-world-2\n');
+
+    await expect(
+      safeCheckout('feature-branch', { forceCleanStatus: true }, git),
+    ).resolves.toBeUndefined();
+    await expect(git.branch()).resolves.toEqual(
+      expect.objectContaining({ current: 'feature-branch' }),
+    );
+  });
+
+  it('getCurrentBranchOrTag should log current branch', async () => {
+    await expect(getCurrentBranchOrTag(git)).resolves.toBe('master');
+  });
+});
+
+describe('git utils in a git repo without a branch and commits', () => {
+  const baseDir = join(process.cwd(), 'tmp', 'testing-git-repo');
+  let git: SimpleGit;
+
+  beforeAll(async () => {
+    await mkdir(baseDir, { recursive: true });
+    git = simpleGit(baseDir);
+    await git.init();
+  });
+
+  afterAll(async () => {
+    await rm(baseDir, { recursive: true, force: true });
+  });
+
+  it('getCurrentBranchOrTag should throw if no branch is given', async () => {
+    await expect(getCurrentBranchOrTag(git)).rejects.toThrow(
+      "git: 'describe --tags --exact-match' is not a git command. See 'git --help'",
+    );
+  });
 });

packages/utils/src/lib/git.ts

@@ -38,17 +38,60 @@ export async function toGitPath(
 
 export function validateCommitData(
   commitData: CommitData | null,
-  options: { throwError?: boolean } = {},
+  options: { throwError?: true } = {},
 ): commitData is CommitData {
-  const { throwError = false } = options;
   if (!commitData) {
     const msg = 'no commit data available';
-    if (throwError) {
+    if (options?.throwError) {
       throw new Error(msg);
     } else {
+      // @TODO replace with ui().logger.warning
       console.warn(msg);
       return false;
     }
   }
   return true;
 }
+
+export function statusIsClean(git = simpleGit()): Promise<boolean> {
+  return git.status(['-s']).then(r => r.files.length === 0);
+}
+
+export async function guardAgainstLocalChanges(
+  git = simpleGit(),
+): Promise<void> {
+  const isClean = await statusIsClean(git);
+  if (!isClean) {
+    throw new Error(
+      'Working directory needs to be clean before we you can proceed. Commit your local changes or stash them.',
+    );
+  }
+}
+
+export async function getCurrentBranchOrTag(
+  git = simpleGit(),
+): Promise<string> {
+  return (
+    (await git.branch().then(r => r.current)) ||
+    // @TODO replace with simple git
+    (await git.raw(['describe --tags --exact-match']).then(out => out.trim()))
+  );
+}
+
+export async function safeCheckout(
+  branchOrHash: string,
+  options: {
+    forceCleanStatus?: true;
+  } = {},
+  git = simpleGit(),
+): Promise<void> {
+  // git requires a clean history to check out a branch
+  if (options?.forceCleanStatus) {
+    await git.raw(['reset', '--hard']);
+    await git.clean(['f', 'd']);
+    // @TODO replace with ui().logger.info
+    console.info(`git status cleaned`);
+  }
+  await guardAgainstLocalChanges(git);
+  await git.checkout(branchOrHash);
+}

tsconfig.base.json

@@ -28,8 +28,8 @@
       ],
       "@code-pushup/models": ["packages/models/src/index.ts"],
       "@code-pushup/nx-plugin": ["packages/nx-plugin/src/index.ts"],
-      "@code-pushup/test-utils": ["testing/test-utils/src/index.ts"],
       "@code-pushup/test-setup": ["testing/test-setup/src/index.ts"],
+      "@code-pushup/test-utils": ["testing/test-utils/src/index.ts"],
       "@code-pushup/utils": ["packages/utils/src/index.ts"]
     }
   },