commit-parser/dist/index.d.mts

A tiny parser for conventional commits that extracts metadata like type, scope, breaking changes and references

import * as quansync_macro0 from "quansync/macro";

//#region src/types.d.ts
interface GitCommitAuthor {
  /**
   * The author's name.
   */
  name: string;
  /**
   * The author's email.
   */
  email: string;
}
interface RawGitCommit {
  /**
   * The commit message.
   */
  message: string;
  /**
   * The commit body.
   */
  body: string;
  /**
   * The short hash of the commit.
   */
  shortHash: string;
  /**
   * The full hash of the commit.
   */
  hash: string;
  /**
   * The author of the commit.
   */
  author: GitCommitAuthor;
  /**
   * The commit date as a string.
   */
  date: string;
}
interface Reference {
  /**
   * The type of the reference (issue or pull request).
   */
  type: "issue" | "pull-request";
  /**
   * The value of the reference (e.g., the issue or pull request number).
   */
  value: string;
}
interface GitCommit extends Omit<RawGitCommit, "author"> {
  /**
   * Whether the commit follows conventional commit guidelines.
   */
  isConventional: boolean;
  /**
   * Whether the commit introduces a breaking change.
   */
  isBreaking: boolean;
  /**
   * The type of the commit (e.g., feat, fix, chore).
   * If this is a non-conventional commit, this will be an empty string.
   */
  type: string;
  /**
   * The scope of the commit (e.g., core, ui).
   */
  scope: string | undefined;
  /**
   * Cleaned subject:
   * - For conventional commits: subject without type/scope/! and without PR refs.
   * - For non-conventional commits: original subject without PR refs.
   */
  description: string;
  /**
   * List of references (issues, pull requests) mentioned in the commit message.
   */
  references: Reference[];
  /**
   * List of all authors (primary + co-authors)
   */
  authors: GitCommitAuthor[];
}
//#endregion
//#region src/commits.d.ts
interface GetCommitsOptions {
  /**
   * The starting reference (commit, branch, tag). If undefined, it will fetch commits up to the `to` reference.
   * @default undefined
   */
  from?: string;
  /**
   * The ending reference. Defaults to "HEAD".
   * @default "HEAD"
   */
  to?: string;
  /**
   * The current working directory where the git command will be executed.
   * If not provided, the command will run in the process's current directory.
   * @default process.cwd()
   */
  cwd?: string;
  /**
   * The folder to provide to the git command.
   * This is useful when you only want to retrieve commits from a specific folder.
   * @default undefined
   */
  folder?: string;
}
/**
 * Retrieves and parses git commits from a repository.
 *
 * @param {GetCommitsOptions} options - Options for fetching and parsing git commits.
 * @returns {QuansyncFn<GitCommit[], [options: GetCommitsOptions]>} An array of structured git commits.
 *
 * @example
 * ```typescript
 * // Get all commits up to HEAD
 * const commits = await getCommits({ to: "HEAD" });
 *
 * // Get commits between two references
 * const commits = await getCommits({ from: "v1.0.0", to: "HEAD" });
 * ```
 *
 * @example
 * ```typescript
 * // Synchronous usage
 * const commits = getCommits.sync({ from: "v1.0.0" });
 * ```
 */
declare const getCommits: quansync_macro0.QuansyncFn<GitCommit[], [options: GetCommitsOptions]>;
//#endregion
//#region src/grouping.d.ts
interface GroupByTypeOptions {
  /**
   * Whether to include non-conventional commits under a separate key
   * @default true
   */
  includeNonConventional?: boolean;
  /**
   * The key under which to group non-conventional commits
   *
   * @default "misc"
   */
  nonConventionalKey?: string;
  /**
   * List of commit types to exclude from grouping
   */
  excludeKeys?: string[];
  /**
   * Combine multiple keys into one group
   */
  mergeKeys?: Record<string, string[]>;
}
/**
 * Groups commits by their conventional commit type. Non-conventional commits
 * are optionally grouped under a configurable key.
 *
 * Rules:
 * - Conventional commits use their lowercased `type` value as key.
 * - Non-conventional commits are grouped under `nonConventionalKey` if
 *   `includeNonConventional` is true; otherwise they are skipped.
 * - Commits without a type (when expected) are skipped.
 *
 * @param {GitCommit[]} commits List of commits to group.
 * @param {GroupByTypeOptions} opts Options controlling grouping behavior.
 * @returns {Map<string, GitCommit[]>} Map keyed by commit type (or `nonConventionalKey`) with arrays of commits.
 *
 * @example
 * ```ts
 * const result = groupByType(commits, { nonConventionalKey: 'other' });
 * const featCommits = result.get('feat');
 * const miscCommits = result.get('other');
 * ```
 */
declare function groupByType(commits: GitCommit[], opts?: GroupByTypeOptions): Map<string, GitCommit[]>;
//#endregion
//#region src/parse.d.ts
/**
 * Parses a raw git commit string into a structured format.
 *
 * @param {string} commit - A raw git commit string delimited by '|' character
 * @returns {RawGitCommit} A structured representation of the git commit
 */
declare function parseRawCommit(commit: string): RawGitCommit;
/**
 * Parses a raw git commit into a structured format with additional metadata
 *
 * @param {RawGitCommit} rawCommit - The raw git commit to parse
 * @returns {GitCommit} A structured representation of the git commit with additional metadata
 */
declare function parseCommit(rawCommit: RawGitCommit): GitCommit;
//#endregion
export { type GetCommitsOptions, type GitCommit, type GitCommitAuthor, type GroupByTypeOptions, type RawGitCommit, type Reference, getCommits, groupByType, parseCommit, parseRawCommit };