cz-cubics

v0.0.10

Published

19 days ago

A customizable Commitizen adapter

0High
0Medium
0Low

ishfaqahmed

commitizen commitizen-adapter cz

cz-cubics

A customizable Commitizen adapter with emoji-prefixed conventional commit messages, plus a ready-to-extend commitlint config.

Installation

pnpm add -D cz-cubics commitizen

{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-cubics"
    }
  }
}

or in .czrc:

{
  "path": "./node_modules/cz-cubics"
}

Then commit with:

pnpm commit

(assuming a "commit": "cz" script, or run commitizen/git cz directly)

Configuration

Config is resolved from the nearest of the following files, searched via find-up in this order:

.czrc
package.json

The first matching file that contains a config["cz-cubics"] key wins if both exist, .czrc takes precedence.

Config file shape

.czrc

{
  "config": {
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}

package.json

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-cubics"
    },
    "cz-cubics": {
      "headFormat": "{type}{scope}: {subject}"
    }
  }
}

Note cz-cubics sits as a sibling of commitizen under config, not nested inside it.

Custom configurations will be validated, invalid types, unknown skipQuestions values, or unrecognized {token}s in headFormat throws errors, rather than failing silently or on the first issue.

`CZCubicsConfig`

| Property | Type | Default | Description | | ------------------ | ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | types | CZCubicsCommitType[] | contents of defaultTypes.json | The list of commit types offered to the user. | | skipQuestions | string[] | [] | Skip any of: scope, body, issues, breaking. type and subject are mandatory and cannot be skipped. | | scopes | string[] | - | Predefined scope choices (Inquirer.js choices array) shown in the scope autocomplete prompt. | | questions | Object | - | Overrides for the generated Inquirer questions. | | subjectMaxLength | number | 100 | Maximum allowed length of the subject line. | | headFormat | string | "{emoji} {type}{scope}: {subject}" | Template for the commit header. Supports the tokens below. |

`CZCubicsCommitType`

Each entry in types (and in defaultTypes.json) has the shape:

{
  "name": "feat",
  "emoji": "✨",
  "description": "A new feature"
}

| Property | Type | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------------------ | | name | string | - | The conventional commit type keyword (e.g. feat, fix). | | emoji | string | "" | Emoji shown next to the type and inserted into the header via {emoji}. | | description | string | - | Explanatory text shown in the type selection prompt. |

`headFormat` tokens (`CZCubicsHeaderTokens`)

| Token | Resolves to | | ----------- | -------------------------------------------------- | | {emoji} | The selected type's emoji. | | {type} | The selected type's name. | | {scope} | (scope) if a scope was entered, otherwise empty. | | {subject} | The trimmed subject line. |

Any run of consecutive whitespace left behind by an omitted token (e.g. no scope) is collapsed to a single space.

Example `.czrc`

{
  "config": {
    "cz-cubics": {
      "types": [
        { "name": "feat", "emoji": "✨", "description": "A new feature" },
        { "name": "fix", "emoji": "🐛", "description": "A bug fix" }
      ],
      "scopes": ["api", "ui", "docs"],
      "skipQuestions": ["issues", "breaking"],
      "subjectMaxLength": 72,
      "headFormat": "{emoji} {type}{scope}: {subject}"
    }
  }
}

Commit message structure

The final message is assembled as:

<head>

<body>

BREAKING CHANGE: <breakingBody>

<footer (issues)>

head => built from headFormat, truncated to the terminal's column width.
body => the free-text body answer, wrapped to the terminal width. Newline can be added by using a pipe |
breaking => included only if a breaking change body was provided. Newline can be added by using a pipe |
footer => issue references, formatted via formatIssues.

Empty sections are omitted; the result is trimmed of trailing whitespace.

`commitlint` integration

This package ships its own commitlint.config.js, which consumers can extend directly instead of duplicating rules:

/** @type {import("@commitlint/types").UserConfig} */
module.exports = {
  extends: ["./node_modules/cz-cubics/commitlint.config.js"],
  // add or override rules here
};

It includes:

type-empty: never,
subject-empty: never,
subject-case: sentence-case, always enforced.
subject-max-length: 100, always enforced, taken from your resolved subjectMaxLength config.
type-enum: restricted to the name of each entry in your resolved types config, so only your configured commit types pass.
header-start-emoji: always enforced the header must start with an Extended_Pictographic character (an emoji), matching the leading {emoji} token in headFormat.
header-has-emoji: off by default (severity 0) same emoji detection, but checks the entire header line rather than just the leading token. Enable it (severity 2) with "always" if you want emoji allowed anywhere in the header rather than only at the start.
A parserPreset whose headerPattern and headerCorrespondence are built dynamically from your resolved headFormat, rather than hardcoded. This means:
- Changing headFormat in your config automatically changes what the linter parses and validates.
- Required tokens ({type}, {subject}) use a matching strategy that still lets the overall header parse successfully even when one of them is empty
- Optional tokens ({emoji}, {scope}) are correctly treated as absent when omitted, rather than requiring a placeholder value.

Requirements

cz-cubics/commitlint.config.js is a plain config object with no runtime dependency on any commitlint package itself. However, to actually lint commits you need @commitlint/cli installed in your own project, since that's what reads and executes the config:

pnpm add -D @commitlint/cli

Husky hook

Wire it up in .husky/commit-msg:

pnpm commitlint --edit "$1"

Make sure the hook file is executable (chmod +x .husky/commit-msg) and that core.hooksPath points at .husky (set automatically by the prepare: "husky" script).

License

MIT

Special Thanks

ngryman/cz-emoji: the core idea of emoji-based conventional commit types this adapter builds on.
commitizen/cz-cli: the adapter framework this package plugs into.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

cz-cubics

Installation

Configuration

Config file shape

CZCubicsConfig

CZCubicsCommitType

headFormat tokens (CZCubicsHeaderTokens)

Example .czrc

Commit message structure

commitlint integration

Requirements

Husky hook

License

Special Thanks

`CZCubicsConfig`

`CZCubicsCommitType`

`headFormat` tokens (`CZCubicsHeaderTokens`)

Example `.czrc`

`commitlint` integration