Clean up code and document edge cases before release

Author: jevakallio

src/git.ts

@@ -4,6 +4,13 @@ import { Lifecycle } from './types';
 
 const git = SimpleGit();
 
+/**
+ * Gets the second item on the reflog. In post-merge hook, this
+ * should be the HEAD of the branch before the merge.
+ *
+ * If this assumption turns out not to be correct, this may
+ * under- or over-report notifications
+ */
 export function getLastRef(): Promise<string> {
   return git
     .raw('reflog', '--pretty=format:"%h"', '--no-patch', '-1', 'HEAD@{1}')
@@ -13,17 +20,20 @@ export function getLastRef(): Promise<string> {
 export async function getLogStream(lifecycle: Lifecycle, args: string[]) {
   switch (lifecycle) {
     case 'merge':
+      // all commits since the previous HEAD on this branch
       return log({ from: await getLastRef() });
 
     case 'rewrite':
       // perhaps not the most accurate method, PRs welcome
       return log({ from: 'origin', to: 'HEAD' });
 
     case 'checkout':
+      // post-checkout hook receives old and new branch HEAD as args
       const [from, to] = args;
       return log({ from, to });
 
     case 'since':
+      // since is our own command, not called by any git hook
       return log({ from: args[0] });
 
     default:

src/index.ts

@@ -1,17 +1,7 @@
-// import commits from 'git-raw-commits';
 import meow from 'meow';
 import showNotifications from './showNotifications';
-import { Lifecycle, Flags } from './types';
 import { getLogStream } from './git';
-
-async function hook(lifecycle: Lifecycle, args: string[], flags: Flags) {
-  // get all commit messages for the relevant revision range
-  // depending on which git hook / command was executed
-  const logs = await getLogStream(lifecycle, args);
-
-  // stream through logs and print any found notifications
-  showNotifications(logs, flags);
-}
+import { Lifecycle, Flags } from './types';
 
 const cli = meow(
   `
@@ -60,4 +50,19 @@ const cli = meow(
   }
 );
 
-hook(cli.input[0] as Lifecycle, cli.input.slice(1), cli.flags);
+async function hook(lifecycle: Lifecycle, args: string[], flags: Flags) {
+  // get all commit messages for the relevant revision range
+  // depending on which git hook / command was executed
+  const logs = await getLogStream(lifecycle, args);
+
+  // stream through logs and print any found notifications
+  showNotifications(logs, flags);
+}
+
+// first argument is the git hook method
+const lifecycle = cli.input[0] as Lifecycle;
+
+// rest of the positional args come from the git hook
+const gitHookArgs = cli.input.slice(1);
+
+hook(lifecycle, gitHookArgs, cli.flags);

src/showNotifications.ts

@@ -4,6 +4,10 @@ import detectNewline from 'detect-newline';
 import boxen from 'boxen';
 import chalk from 'chalk';
 
+/**
+ * Reads given stream of git log messages and prints
+ * out any lines prefixed with the git-notify tag
+ */
 export default async function showNotifications(
   messageStream: Stream.Readable,
   flags: Flags