Conventional Commits message linter and parser

It recognizes the common build, chore, CI, documentation, feature, fix, performance, refactor, revert, style, and test types. Use it to catch malformed or unknown headers before they enter a shared history, release workflow, or automated changelog. The compact result is ready for scripts without additional text parsing.

Check the header and extract useful fields

Send the complete commit message in the text field. The linter normalizes line endings and examines the first line as the Conventional Commits header, so a message may still contain a blank line, body paragraphs, and footers below it. A valid header begins with a recognized lowercase type. It may continue with a scope in parentheses, may add an exclamation mark to flag a breaking change, and must then contain a colon, exactly one separating space, and a non-empty description. For example, <code>feat(parser): support escaped delimiters</code> yields the type <code>feat</code>, the scope <code>parser</code>, and the description <code>support escaped delimiters</code>. The normal result also includes <code>valid: true</code> and a Boolean breaking field. When no scope is present, the scope property is omitted instead of being filled with a misleading empty or null value. Syntax failures and unknown types produce an invalid-input error with a direct explanation, allowing an editor hook or pipeline to show a useful correction rather than interpreting a partly parsed result.

Understand the recognized convention

Conventional Commits defines the shape of a header while leaving projects room to establish their own type vocabulary. This capability deliberately uses a fixed, practical set so results are predictable across repositories: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test. A correctly shaped header with another word still fails because accepting every word would not provide the requested type validation. Types must be lowercase. Scopes are optional and may contain lowercase letters, digits, dots, underscores, slashes, or hyphens; they must start with a letter or digit. This makes common scopes such as <code>api</code>, <code>web-client</code>, and <code>packages/core</code> usable while rejecting ambiguous whitespace and unmatched parentheses. The description preserves its original punctuation and capitalization, but it may not start or end with whitespace. An exclamation mark immediately before the colon indicates a breaking change and is returned separately. A <code>BREAKING CHANGE</code> footer may remain in the body, but the current result derives its breaking Boolean from the header marker only; it does not interpret footer semantics.

Place deterministic validation in development workflows

Use the linter at the earliest point where a proposed message is available: a commit-message editor hook, a pull-request check, a merge queue, or a service that prepares release metadata. A local hook gives the quickest feedback, while server-side validation ensures that commits created by automation or alternate clients follow the same policy. The parser is deterministic and performs a bounded string scan. It does not call a repository host, inspect a Git object, infer intent from a diff, rewrite the supplied description, or contact any external service. The same input therefore produces the same fields or the same error in a browser and through the API. Treat the returned type, scope, and description as classification data that can feed changelog grouping, release rules, or dashboards, but keep project-specific semantic checks separate. For example, this linter can confirm that <code>fix(auth): reject expired tokens</code> is structurally valid; it cannot prove that the change fixes a bug or that <code>auth</code> is an allowed package in your repository. Combine it with repository policy when stricter scope lists or ticket references are required.