feat: add commit types description

Author: zdm

lib/commands/git/commit-msg.js

@@ -38,6 +38,17 @@ git commit -m"feat(core)!: commit description"
         const pkg = this._findGitPackage();
         if ( !pkg ) return;
 
+        // prepare types
+        const types = {};
+        for ( const [ type, config ] of Object.entries( pkg.cliConfig?.commits.types || {} ) ) {
+            if ( !config ) continue;
+
+            types[ type ] = {
+                ...config,
+                type,
+            };
+        }
+
         const message = fs.readFileSync( process.cli.arguments.path, "utf8" ),
             isRevert = fs.existsSync( ".git/REVERT_HEAD" );
 
@@ -53,7 +64,7 @@ git commit -m"feat(core)!: commit description"
         // merge commit
         if ( commit.isMerge ) {
 
-            // merge commit shoild have default message
+            // merge commit should have default message
             if ( !commit.hasDefaultMergeSubject ) {
                 return this.#throwError( `Merge commit message should start with "Merge" keyword.` );
             }
@@ -79,28 +90,17 @@ git commit -m"feat(core)!: commit description"
                 return this.#throwError( `Commit message subject should not ends with ".".` );
             }
 
-            const type = pkg.cliConfig?.commits.types[ commit.type ] || null,
-                scopes = new Set( Object.entries( pkg.cliConfig?.commits[ type?.primaryChange
+            const type = types[ commit.type ],
+                scopes = new Map( Object.entries( pkg.cliConfig?.commits[ type?.primaryChange
                     ? "primaryScopes"
-                    : "secondaryScopes" ] || {} )
-                    .map( ( [ key, value ] ) => ( value
-                        ? key
-                        : null ) )
-                    .filter( item => item ) );
+                    : "secondaryScopes" ] || {} ).filter( ( [ key, value ] ) => value ) );
 
             // check strict type
             if ( pkg.cliConfig?.commits.strictType ) {
 
                 // commit type is not valid
                 if ( !type ) {
-                    return this.#throwError( `Commit type is not valid. Allowed types: ${ Object.entries( pkg.cliConfig.commits.types )
-                        .map( ( key, value ) => ( value
-                            ? key
-                            : null ) )
-                        .filter( item => item )
-                        .sort()
-                        .map( item => `"${ item }"` )
-                        .join( ", " ) }.` );
+                    return this.#throwError( `Commit type is not valid. Allowed types:\n${ this.#getAllowedTypes( types ) }` );
                 }
             }
 
@@ -113,10 +113,7 @@ git commit -m"feat(core)!: commit description"
                     // commit scope is not valid
                     if ( !scopes.has( commit.scope ) ) {
                         if ( scopes.size ) {
-                            return this.#throwError( `Commit scope is not valid. Allowed scopes for this commit type are: ${ [ ...scopes ]
-                                .sort()
-                                .map( item => `"${ item }"` )
-                                .join( ", " ) }.` );
+                            return this.#throwError( `Commit scope is not valid. Allowed scopes for this commit type are:\n${ this.#getAllowedScopes( scopes ) }` );
                         }
                         else {
                             return this.#throwError( `Commit scope is not allowed for this commit type.` );
@@ -127,10 +124,7 @@ git commit -m"feat(core)!: commit description"
 
             // commit scope is required
             else if ( type.requireScope && scopes.size ) {
-                return this.#throwError( `Commit scope is required. Allowed scopes for this commit type are: ${ [ ...scopes ]
-                    .sort()
-                    .map( item => `"${ item }"` )
-                    .join( ", " ) }.` );
+                return this.#throwError( `Commit scope is required. Allowed scopes for this commit type are:\n${ this.#getAllowedScopes( scopes ) }` );
             }
 
             // restrict breaking changes to the primary changes only
@@ -148,11 +142,21 @@ git commit -m"feat(core)!: commit description"
 
         // commit type is required
         else if ( pkg.cliConfig?.commits.requireType ) {
-            return this.#throwError( `Commit message must follow conventional commits syntax.` );
+            return this.#throwError( `Commit type is required. Allowed types:\n${ this.#getAllowedTypes( types ) }` );
         }
     }
 
     // private
+    #getAllowedTypes ( types ) {
+        return Object.values( types )
+            .map( type => `    - "${ type.type }": ${ type.description };` )
+            .join( "\n" );
+    }
+
+    #getAllowedScopes ( scopes ) {
+        return [ ...scopes.keys() ].map( scope => `    - "${ scope }": ${ scopes.get( scope ) };` ).join( "\n" );
+    }
+
     #throwError ( message ) {
         throw result( [ 500, `${ message }\nRefer to the documentation: ${ ansi.link( "https://www.conventionalcommits.org/en/" ) }.` ] );
     }

lib/git/changelog.js

@@ -62,6 +62,14 @@ export default class GitChangelog {
         return this.#changes.hasBreakingChanges;
     }
 
+    get hasFeatureChanges () {
+        return this.#changes.hasFeatureChanges;
+    }
+
+    get hasFixChanges () {
+        return this.#changes.hasFixChanges;
+    }
+
     // public
     async createChangelog ( { currentRelease, header, text, ansi = true } = {} ) {
         currentRelease ||= this.#currentRelease;

resources/cli.config.yaml

@@ -61,21 +61,25 @@ commits:
 
   types:
     feat:
+      description: a commit that introduces a new feature to the codebase (MINOR in Semantic Versioning)
       primaryChange: true
       notableChange: true
       requireScope: true
       strictScope: true
     fix:
+      description: a commit that patches a bug in your codebase (PATCH in Semantic Versioning)
       primaryChange: true
       notableChange: true
       requireScope: true
       strictScope: true
     refactor:
+      description: a code change that neither fixes a bug nor adds a feature
       primaryChange: true
       notableChange: false
       requireScope: true
       strictScope: true
     chore:
+      description: a commit that does not affect main codebase
       primaryChange: false
       notableChange: false
       requireScope: true
@@ -84,11 +88,11 @@ commits:
   primaryScopes: ~
 
   secondaryScopes:
-    build: Package build related changes
-    deps: Package dependencies updates
-    docs: Documentation changes
-    metadata: Package metadata changes
-    release: Package release
-    style: Code stylistic changes
+    build: package build related changes
+    deps: package dependencies updates
+    docs: documentation changes
+    metadata: package metadata changes
+    release: package release
+    style: code stylistic changes
 
 docs: ~

resources/schemas/cli.config.schema.yaml

@@ -156,12 +156,13 @@ properties:
             - type: object
               properties:
                 title: { type: string }
+                description: { type: string }
                 primaryChange: { type: boolean }
                 notableChange: { type: boolean }
                 requireScope: { type: boolean }
                 strictScope: { type: boolean }
               additionalProperties: false
-              required: [primaryChange, notableChange, requireScope, strictScope]
+              required: [description, primaryChange, notableChange, requireScope, strictScope]
 
       primaryScopes:
         anyOf: