Package Exports

parse-commit-message

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (parse-commit-message) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

parse-commit-message

Extensible parser for git commit messages following Conventional Commits Specification

Please consider following this project's author, Charlike Mike Reagent, and ⭐ the project to show your ❤️ and support.

If you have any how-to kind of questions, please read the Contributing Guide and Code of Conduct documents. For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Project is semantically versioned & automatically released from GitHub Actions with Lerna.

Topic	Contact
Any legal or licensing questions, like private or commerical use
For any critical problems and security reports
Consulting, professional support, personal or team training
For any questions about Open Source, partnerships and sponsoring

Install
- Exposed named methods
- Types
API
Contributing
License

(TOC generated by verb using markdown-toc)

Install

This project requires Node.js >=10.13.0 (see Support & Release Policy). Install it using yarn or npm.
We highly recommend to use Yarn when you think to contribute to this project.

$ yarn add parse-commit-message

TODO: need to add support in jest-runner-docs to handle multiple files in src/. For now read the comments there.

Exposed named methods

export {
  // methods that accepts
  // string, array of strings, Commit and etc
  parse,
  stringify,
  validate,
  check,
  // methods only for the "header",
  // e.g. the first lien of a commit
  parseHeader,
  stringifyHeader,
  validateHeader,
  checkHeader,
  // methods that accepts only Commit type object
  parseCommit,
  stringifyCommit,
  validateCommit,
  checkCommit,
  // main
  applyPlugins,
  mappers,
  plugins,
  // utils
  stringToHeader,
  toArray,
  cleaner,
  errorMsg,
  isBreakingChange,
  isValidString,
  normalizeCommit,
};

Types

export interface CommitResult {
  error?: Error;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  value?: any;
}

export interface Mention {
  index: number;
  handle: string;
  mention: string;
}

export interface HeaderType {
  type: string;
  scope?: string | null;
  subject: string;
}

export interface SimpleHeader {
  value: string;
}

export type Header = HeaderType | SimpleHeader;

export interface Commit {
  header: Header;
  body?: string | null;
  footer?: string | null;
  increment?: string | boolean;
  isBreaking?: boolean;
  mentions?: Array<Mention>;
  [key: string]: any;
}

export type PossibleCommit = string | Commit | Array<Commit>;

export type Plugin = (
  commit: Commit,
  normalize?: boolean,
) => void | {} | Commit;
export type Plugins = Plugin | Array<Plugin>;

export interface Mappers {
  mentions: Plugin;
  isBreaking: Plugin;
  isBreakingChange: Plugin;
}

export interface Options {
  caseSensitive: boolean; // default false
  normalize: boolean; // default true
  headerRegex: string | RegExp;
}

API

Generated using jest-runner-docs.

.applyPlugins

Apply a set of plugins over all of the given commits. A plugin is a simple function passed with Commit object, which may be returned to modify and set additional properties to the Commit object.

Signature

function(plugins, commits, options)

Params

plugins {Plugins} - a simple function like (commit) => {}
commits {PossibleCommit} - a PossibleCommit or an array of strings; a value which should already be gone through parse
returns {Array<Commit>} - plus the modified or added properties from each function in plugins

The commits should be coming from parse, validate (with ret option) or the check methods. It does not do checking and validation.

Example

import dedent from 'dedent';
import { applyPlugins, plugins, parse, check } from './src';

const commits = [
  'fix: bar qux',
  dedent`feat(foo): yea yea

  Awesome body here with @some mentions
  resolves #123

  BREAKING CHANGE: ouch!`,
  'chore(ci): updates for ci config',
  {
    header: { type: 'fix', subject: 'Barry White' },
    body: 'okey dude',
    foo: 'possible',
  },
];

// Parses, normalizes, validates
// and applies plugins
const results = applyPlugins(plugins, check(parse(commits)));

console.log(results);
// => [ { body: null,
//   footer: null,
//   header: { scope: null, type: 'fix', subject: 'bar qux' },
//   mentions: [],
//   increment: 'patch',
//   isBreaking: false },
// { body: 'Awesome body here with @some mentions\nresolves #123',
//   footer: 'BREAKING CHANGE: ouch!',
//   header: { scope: 'foo', type: 'feat', subject: 'yea yea' },
//   mentions: [ [Object] ],
//   increment: 'major',
//   isBreaking: true },
// { body: null,
//   footer: null,
//   header:
//    { scope: 'ci', type: 'chore', subject: 'updates for ci config' },
//   mentions: [],
//   increment: false,
//   isBreaking: false },
// { body: 'okey dude',
//   footer: null,
//   header: { scope: null, type: 'fix', subject: 'Barry White' },
//   foo: 'possible',
//   mentions: [],
//   increment: 'patch',
//   isBreaking: false } ]

.plugins

An array which includes mentions and increment built-in plugins. The mentions is an array of objects. Basically what's returned from the collect-mentions package.

Params

Example

import { plugins, applyPlugins, parse } from 'parse-commit-message';

console.log(plugins); // =>  [mentions, increment]
console.log(plugins[0]); // => [Function mentions]
console.log(plugins[0]); // => [Function increment]

const cmts = parse([
  'fix: foo @bar @qux haha',
  'feat(cli): awesome @tunnckoCore feature\n\nSuper duper baz!'
  'fix: ooh\n\nBREAKING CHANGE: some awful api change'
]);

const commits = applyPlugins(plugins, cmts);
console.log(commits);
// => [
//   {
//     header: { type: 'fix', scope: '', subject: 'foo bar baz' },
//     body: '',
//     footer: '',
//     increment: 'patch',
//     isBreaking: false,
//     mentions: [
//       { handle: '@bar', mention: 'bar', index: 8 },
//       { handle: '@qux', mention: 'qux', index: 13 },
//     ]
//   },
//   {
//     header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//     body: 'Super duper baz!',
//     footer: '',
//     increment: 'minor',
//     isBreaking: false,
//     mentions: [
//       { handle: '@tunnckoCore', mention: 'tunnckoCore', index: 18 },
//     ]
//   },
//   {
//     header: { type: 'fix', scope: '', subject: 'ooh' },
//     body: 'BREAKING CHANGE: some awful api change',
//     footer: '',
//     increment: 'major',
//     isBreaking: true,
//     mentions: [],
//   },
// ]

.mappers

An object (named set) which includes mentions and increment built-in plugins.

Params

Example

import { mappers, applyPlugins, parse } from 'parse-commit-message';

console.log(mappers); // => { mentions, increment }
console.log(mappers.mentions); // => [Function mentions]
console.log(mappers.increment); // => [Function increment]

const flat = true;
const parsed = parse('fix: bar', flat);
console.log(parsed);
// => {
//   header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//   body: 'Super duper baz!',
//   footer: '',
// }

const commit = applyPlugins([mappers.increment], parsed);
console.log(commit);
// => [{
//   header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//   body: 'Super duper baz!',
//   footer: '',
//   increment: 'patch',
// }]

back to top

Contributing

Guides and Community

Please read the Contributing Guide and Code of Conduct documents for advices.

For bug reports and feature requests, please join our community forum and open a thread there with prefixing the title of the thread with the name of the project if there's no separate channel for it.

Consider reading the Support and Release Policy guide if you are interested in what are the supported Node.js versions and how we proceed. In short, we support latest two even-numbered Node.js release lines.

Support the project

Become a Partner or Sponsor? 💵 Check the Partner, Sponsor or Omega-level tiers! 🎉 You can get your company logo, link & name on this file. It's also rendered on package page in npmjs.com and yarnpkg.com sites too! 🚀

Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. ✨

Wonderful Contributors

Thanks to the hard work of these wonderful people this project is alive! It follows the all-contributors specification. Don't hesitate to add yourself to that list if you have made any contribution! ;) See how, here.

_{Charlike Mike Reagent} 💻 📖 💬 👀 🔍

Consider showing your support to them. 💖

back to top

License

Copyright (c) 2018-present, Charlike Mike Reagent <opensource@tunnckocore.com> & contributors.
Released under the MPL-2.0 License.