Conventional Commits Parser

A robust Rust library for parsing Conventional Commits, adding human and machine-readable meaning to commit messages.

Table of Contents

• Features
• Installation
• Usage
• Valid Commit Structure
• Invalid Commits
• API Reference
• Contributing
• License

Features

• Parse Conventional Commits into structured data
• Tokenize commit messages for detailed analysis
• Identify commit type, scope, description, body, and footer
• Detect breaking changes
• Robust error handling for invalid commits

Installation

Add this to your Cargo.toml:

[dependencies]
conventional-commit = "0.1.0"

Usage

Here's a quick example of how to use the Conventional Commits Parser:

use conventional_commit::{parse_commit, Lexer};

fn main() -> Result<(), String> {
    let input = "feat(parser): add ability to parse conventional commits".to_string();
    let mut lexer = Lexer::new(input);
    let tokens = lexer.lex()?;
    let commit = parse_commit(tokens)?;
    println!("{:?}", commit);
    Ok(())
}

Valid Commit Structure

A valid Conventional Commit has the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Components:

1. Type: Describes the kind of change (e.g., feat, fix, docs, style, refactor, test, chore).

   • Must be lowercase.
   • Examples: feat, fix, docs

2. Scope (optional): Describes what area of the project is changing.

   • Enclosed in parentheses.
   • Can use kebab-case, lowercase, or uppercase.
   • Examples: (parser), (ui), (docs)

3. Breaking Change Indicator (optional): An exclamation mark (!) before the colon.

   • Indicates a breaking change.
   • Example: feat!: or feat(scope)!:

4. Description: A brief explanation of the change.

   • Separated from the type (and scope) by a colon and space.
   • Written in the imperative mood.
   • Example: add ability to parse conventional commits

5. Body (optional): Provides additional contextual information about the change.

   • Must be separated from the description by a blank line.
   • Can be multiple paragraphs.

6. Footer (optional): Used for referencing issues, noting breaking changes, etc.

   • Must start with a word token followed by :<space> or <space>#.
   • Common footers: BREAKING CHANGE:, Refs:, Reviewed-by:

Examples of Valid Commits:

feat(parser): add ability to parse conventional commits

This commit introduces a new parser for Conventional Commits.
The parser can identify commit types, scopes, and descriptions.

Refs: #123

fix!: correct critical bug in authentication flow

BREAKING CHANGE: This changes the API for user authentication.
Old auth tokens will no longer be valid.

docs: update README with new API examples

Updated the README to include examples of how to use
the new parsing functions introduced in v2.0.0.

Invalid Commits

The following are examples of invalid commits and why they're incorrect:

1. Missing type:

   add new feature
   

   Error: Commit type is missing.

2. Unclosed scope:

   feat(parser: add new parsing logic
   

   Error: Scope is not properly closed with a parenthesis.

3. Missing description:

   feat(ui):
   

   Error: Description is missing.

API Reference

For detailed API documentation, please refer to the rustdoc comments in the source code.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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