@wroud/github

@wroud/github is a lightweight library designed to work with git history and GitHub-specific information like co-authors, issues, commit links, and GitHub references. It provides a structured way to parse commit messages, handle GitHub metadata, and generate proper GitHub URLs for issues and commits.

This library uses the IGitCommitInfo interface from @wroud/git. You can obtain git commits by using the getGitCommits function from @wroud/git.

Features

• GitHub metadata: Extract co-authors, GitHub issue links, and commit references from git commits.
• TypeScript: Written in TypeScript for type safety and modern JavaScript support.
• GitHub URL generation: Easily generate URLs for issues and commits.
• Pure ESM package

Installation

Install via npm:

npm install @wroud/github @wroud/git

Install via yarn:

yarn add @wroud/github @wroud/git

Documentation

For detailed usage and API reference, visit the documentation site.

Example

import { getGitCommits } from "@wroud/git";
import {
  getGithubTrailers,
  getGithubLink,
  gitGithubLinks,
} from "@wroud/github";

const REPOSITORY = "wroud/repository";

// Fetch commits using getGitCommits from @wroud/git
async function printCommitLinks() {
  for await (const commit of getGitCommits({
    from: "v1.0.0",
    to: "HEAD",
    customLinks: [...gitGithubLinks], // Pass gitGithubLinks to getGitCommits
  })) {
    let message = commit.message;

    // Extract GitHub trailers (including co-authors)
    const trailers = getGithubTrailers(commit);

    // Iterate through commit links and replace tokens with GitHub links
    for (const [token, link] of Object.entries(commit.links)) {
      const githubLink = getGithubLink(link, REPOSITORY);

      if (githubLink) {
        message = message.replaceAll(token, `[${token}](${githubLink})`);
      }
    }

    console.log(`Commit: ${commit.hash}`);
    console.log(`Message: ${message}`);
    if (trailers.coAuthors.length) {
      console.log(
        `Co-authors: ${trailers.coAuthors.map((coAuthor) => coAuthor.name).join(", ")}`,
      );
    }
  }
}

printCommitLinks();

API

Interfaces

IGithubCoAuthor

Represents information about a GitHub co-author.

interface IGithubCoAuthor {
  name: string;
  username?: string;
  usernameLink?: string;
  link?: string;
  email?: string;
}

IGithubTrailers

Contains metadata such as GitHub co-authors.

interface IGithubTrailers {
  coAuthors: IGithubCoAuthor[];
}

Functions

getGithubTrailers

Extracts GitHub trailers (such as co-authors) from a commit message.

function getGithubTrailers(
  commit: IGitCommitInfo,
  options?: { loadGithubUserNames?: boolean },
): IGithubTrailers;

getGithubLink

Generates a GitHub link for a specific issue or commit.

function getGithubLink(link: IGitLink, repository: string): string | null;

Constants

gitGithubLinks

A list of regular expressions to match GitHub issue and PR references.

const gitGithubLinks = [
  /[^\w](?<token>#(?<link>\d+)(?<gh>))/gi,
  /[^\w](?<token>GH-(?<link>\d+)(?<gh>))/g,
  /[^\w](?<token>(?<repository>[^\/\s]+\/[^\/\s]+)#(?<link>\d+)(?<gh>))/gi,
];

GithubURL

Utility to generate GitHub issue and commit URLs.

const GithubURL = {
  issue: (repository: string, issue: number) =>
    `https://github.com/${repository}/issues/${issue}`,
  commit: (repository: string, hash: string) =>
    `https://github.com/${repository}/commit/${hash}`,
};

Changelog

All notable changes to this project will be documented in the CHANGELOG file.

License

This project is licensed under the MIT License. See the LICENSE file for details.