feat: expose registry to define custom rules, formatters

Author: muthukrishnan24

README.md

@@ -50,7 +50,12 @@ commitlint checks if your commit message meets the [conventional commit format](
     - [Trailer / sign-off rules](#trailer--sign-off-rules)
     - [Breaking change rules](#breaking-change-rules)
   - [Available Formatters](#available-formatters)
-  - [Extensibility](#extensibility)
+  - [Programmatic Usage](#programmatic-usage)
+    - [One-liner with default config](#one-liner-with-default-config)
+    - [Full control with default config](#full-control-with-default-config)
+    - [Lint with a config file](#lint-with-a-config-file)
+    - [Custom rules](#custom-rules)
+    - [Custom formatters](#custom-formatters)
   - [FAQ](#faq)
   - [License](#license)
 
@@ -223,7 +228,7 @@ ignores: []
 
 ### Commit Types
 
-Commonly used commit types from [Conventional Commit Types](https://github.com/commitizen/conventional-commit-types)
+Commonly used commit types
 
 | Type     | Description                                                                      |
 |:---------|:---------------------------------------------------------------------------------|
@@ -411,13 +416,237 @@ Total 1 errors, 0 warnings, 0 other severities
 {"input":"fear: do not fear for commit message","issues":[{"description":"type 'fear' is not allowed, you can use one of [build chore ci docs feat fix perf refactor revert style test]","name":"type-enum","severity":"error"}]}
 ```
 
-## Extensibility
+## Programmatic Usage
+
+All public packages are importable. The module path is `github.com/conventionalcommit/commitlint`.
+
+```bash
+go get github.com/conventionalcommit/commitlint@latest
+```
+
+Key packages:
+
+| Package | Purpose |
+|:--------|:--------|
+| `config` | Parse config files, build a `Linter`, access defaults |
+| `lint` | Core types: `Linter`, `Rule`, `Formatter`, `Config`, `Result`, `Issue` |
+| `registry` | Register and look up custom rules / formatters |
+| `rule` | Built-in rule implementations |
+| `formatter` | Built-in formatters (`default`, `json`) |
+
+### One-liner with default config
+
+The simplest entry point — no config file required:
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/conventionalcommit/commitlint/config"
+)
+
+func main() {
+    result, err := config.LintMessage("feat: add login page")
+    if err != nil {
+        panic(err)
+    }
+
+    for _, issue := range result.Issues() {
+        fmt.Printf("%s: %s: %s\n", issue.Severity(), issue.RuleName(), issue.Description())
+    }
+
+    if len(result.Issues()) == 0 {
+        fmt.Println("commit message is valid")
+    }
+}
+```
+
+### Full control with default config
+
+Build the linter yourself for more control (e.g. to swap the formatter):
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/conventionalcommit/commitlint/config"
+    "github.com/conventionalcommit/commitlint/formatter"
+)
+
+func main() {
+    conf := config.NewDefault()
+    // optionally customise conf here
+
+    linter, err := config.NewLinter(conf)
+    if err != nil {
+        panic(err)
+    }
+
+    result, err := linter.ParseAndLint("feat: add login page")
+    if err != nil {
+        panic(err)
+    }
+
+    out, err := (&formatter.JSONFormatter{}).Format(result)
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println(out)
+}
+```
+
+### Lint with a config file
+
+Load a `.commitlint.yaml` and lint against it:
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/conventionalcommit/commitlint/config"
+)
+
+func main() {
+    conf, err := config.Parse(".commitlint.yaml")
+    if err != nil {
+        panic(err)
+    }
+
+    linter, err := config.NewLinter(conf)
+    if err != nil {
+        panic(err)
+    }
+
+    result, err := linter.ParseAndLint("feat: add login page")
+    if err != nil {
+        panic(err)
+    }
+
+    for _, issue := range result.Issues() {
+        fmt.Printf("%s: %s\n", issue.RuleName(), issue.Description())
+    }
+}
+```
+
+### Custom rules
+
+Implement the `lint.Rule` interface and register it before building a linter:
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/conventionalcommit/commitlint/config"
+    "github.com/conventionalcommit/commitlint/lint"
+    "github.com/conventionalcommit/commitlint/registry"
+)
+
+// NoWIPRule rejects commit messages whose description starts with "WIP".
+type NoWIPRule struct{}
+
+func (r *NoWIPRule) Name() string { return "no-wip" }
+func (r *NoWIPRule) Apply(setting lint.RuleSetting) error { return nil }
+func (r *NoWIPRule) Validate(commit lint.Commit) (*lint.Issue, error) {
+    if len(commit.Description()) >= 3 && commit.Description()[:3] == "WIP" {
+        return lint.NewIssue("description must not start with WIP"), nil
+    }
+    return nil, nil
+}
+
+func main() {
+    if err := registry.RegisterRule(&NoWIPRule{}); err != nil {
+        panic(err)
+    }
+
+    conf := config.NewDefault()
+    conf.Rules = append(conf.Rules, "no-wip")
+    conf.Settings["no-wip"] = lint.RuleSetting{}
+
+    linter, err := config.NewLinter(conf)
+    if err != nil {
+        panic(err)
+    }
+
+    result, err := linter.ParseAndLint("feat: WIP do not merge")
+    if err != nil {
+        panic(err)
+    }
+
+    for _, issue := range result.Issues() {
+        fmt.Printf("%s: %s\n", issue.RuleName(), issue.Description())
+    }
+}
+```
+
+### Custom formatters
+
+Implement `lint.Formatter` and register it:
+
+```go
+package main
+
+import (
+    "fmt"
+    "strings"
+    "github.com/conventionalcommit/commitlint/config"
+    "github.com/conventionalcommit/commitlint/lint"
+    "github.com/conventionalcommit/commitlint/registry"
+)
+
+type SimpleFormatter struct{}
+
+func (f *SimpleFormatter) Name() string { return "simple" }
+func (f *SimpleFormatter) Format(result *lint.Result) (string, error) {
+    if len(result.Issues()) == 0 {
+        return "ok", nil
+    }
+    var sb strings.Builder
+    for _, issue := range result.Issues() {
+        fmt.Fprintf(&sb, "[%s] %s: %s\n", issue.Severity(), issue.RuleName(), issue.Description())
+    }
+    return sb.String(), nil
+}
+
+func main() {
+    if err := registry.RegisterFormatter(&SimpleFormatter{}); err != nil {
+        panic(err)
+    }
+
+    conf := config.NewDefault()
+    conf.Formatter = "simple"
+
+    format, err := config.GetFormatter(conf)
+    if err != nil {
+        panic(err)
+    }
+
+    linter, err := config.NewLinter(conf)
+    if err != nil {
+        panic(err)
+    }
+
+    result, err := linter.ParseAndLint("bad message")
+    if err != nil {
+        panic(err)
+    }
+
+    out, err := format.Format(result)
+    if err != nil {
+        panic(err)
+    }
+    fmt.Print(out)
+}
+```
 
 ## FAQ
 
 - How to have custom config for each repository?
 
-  Place `.commitlint.yaml` file in repo root directory. linter follows [config precedence](#precedence).
+  Place `.commitlint.yaml` file in repo root directory. linter follows [config precedence](#config-precedence).
 
   To create a sample config, run `commitlint config create` (or `commitlint config create --all` to include all available settings)
 

config/api.go

@@ -0,0 +1,15 @@
+package config
+
+import "github.com/conventionalcommit/commitlint/lint"
+
+// LintMessage lints commitMsg using the default configuration.
+// It is the simplest entry point for programmatic use: no config file is needed.
+//
+// For custom configuration use Parse or NewDefault, then NewLinter.
+func LintMessage(commitMsg string) (*lint.Result, error) {
+	linter, err := NewLinter(NewDefault())
+	if err != nil {
+		return nil, err
+	}
+	return linter.ParseAndLint(commitMsg)
+}

config/config.go

@@ -14,8 +14,8 @@ import (
 
 	"github.com/conventionalcommit/commitlint/formatter"
 	"github.com/conventionalcommit/commitlint/internal"
-	"github.com/conventionalcommit/commitlint/internal/registry"
 	"github.com/conventionalcommit/commitlint/lint"
+	"github.com/conventionalcommit/commitlint/registry"
 )
 
 // Parse parse given file in confPath, and return Config instance, error if any

config/default_test.go

@@ -3,7 +3,7 @@ package config
 import (
 	"testing"
 
-	"github.com/conventionalcommit/commitlint/internal/registry"
+	"github.com/conventionalcommit/commitlint/registry"
 )
 
 func TestDefaultLint(t *testing.T) {

config/lint.go

@@ -3,8 +3,8 @@ package config
 import (
 	"fmt"
 
-	"github.com/conventionalcommit/commitlint/internal/registry"
 	"github.com/conventionalcommit/commitlint/lint"
+	"github.com/conventionalcommit/commitlint/registry"
 )
 
 // NewLinter returns Linter for given confFilePath

internal/registry/registry_test.go

@@ -1,4 +1,6 @@
-// Package registry contains registered rules and formatters
+// Package registry holds the global registry of rules and formatters.
+// External packages can call RegisterRule and RegisterFormatter to extend
+// commitlint with custom rules or formatters before building a linter.
 package registry
 
 import (
@@ -12,33 +14,38 @@ import (
 
 var globalRegistry = newRegistry()
 
-// RegisterRule registers a custom rule
-// if rule already exists, returns error
+// RegisterRule registers a custom rule.
+// Returns an error if a rule with the same name is already registered.
 func RegisterRule(r lint.Rule) error {
 	return globalRegistry.RegisterRule(r)
 }
 
-// RegisterFormatter registers a custom formatter
-// if formatter already exists, returns error
+// RegisterFormatter registers a custom formatter.
+// Returns an error if a formatter with the same name is already registered.
 func RegisterFormatter(format lint.Formatter) error {
 	return globalRegistry.RegisterFormatter(format)
 }
 
-// GetRule returns Rule with given name
+// GetRule returns the Rule registered under name, and whether it was found.
 func GetRule(name string) (lint.Rule, bool) {
 	return globalRegistry.GetRule(name)
 }
 
-// GetFormatter returns Formatter with given name
+// GetFormatter returns the Formatter registered under name, and whether it was found.
 func GetFormatter(name string) (lint.Formatter, bool) {
 	return globalRegistry.GetFormatter(name)
 }
 
-// Rules returns all registered rules
+// Rules returns all registered rules.
 func Rules() []lint.Rule {
 	return globalRegistry.Rules()
 }
 
+// Formatters returns all registered formatters.
+func Formatters() []lint.Formatter {
+	return globalRegistry.Formatters()
+}
+
 type registry struct {
 	mut *sync.Mutex