ccval 0.6.0

A validator for conventional commits
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# Validation Rules

After a commit message is parsed, `ccval` applies validation rules from your configuration.

See [`PARSING.md`](PARSING.md) for the commit message grammar and parse errors.

## Available Fields

You can attach rules to these fields:

```yaml
preset: default

message: <RULES>
header: <RULES>
type: <RULES>
scope: <RULES>
description: <RULES>
body: <RULES>
footer-token: <RULES>
footer-value: <RULES>
footers:
  Closes: <RULES>
```

- `message` is the full commit message
- `header` is the first line, including its trailing newline
- `type`, `scope`, and `description` come from the parsed header
- `body` is everything between the blank line after the header and the first footer, including its trailing newline when present
- `footer-token` and `footer-value` apply to every footer
- `footer-value` includes its trailing newline
- for `Token #value` footers such as `Closes #123`, the stored footer value is `123\n` (without `#`)
- `footers.<name>` applies to a specific footer value such as `Closes`

Footer values may span multiple lines until the next recognized footer.

## Available Rules

| Rule | Meaning |
|------|---------|
| `max-length` | Maximum total length, including newlines |
| `max-line-length` | Maximum per-line length, excluding newline characters |
| `required` | Field must be present |
| `forbidden` | Field must not be present |
| `regexes` | All regexes must match |
| `values` | Field must match one of the allowed values |

## Notes About Length Rules

- `max-length` checks the full field length exactly as stored
- `max-line-length` checks each line separately
- for fields that include a trailing newline, `max-line-length` ignores that trailing newline when measuring line length
- for fields that include a trailing newline, `regexes` match the stored text including that newline
- for fields that include a trailing newline, `values` compares after stripping that final newline

This means `max-length` and `max-line-length` are not interchangeable.

## Rule Examples

Allow only selected commit types:

```yaml
type:
  values:
    - feat
    - fix
    - docs
```

Require a scope:

```yaml
scope:
  required: true
```

Reject descriptions with leading or trailing spaces:

```yaml
description:
  regexes:
    - '^[^ ].*'
    - '^.*[^ ]$'
```

Limit header line length:

```yaml
header:
  max-line-length: 50
```

Require a specific footer:

```yaml
footers:
  Closes:
    required: true
```

## Presets

`ccval` includes these presets:

- `default` - formatting rules for description spacing and newline handling in body/footer values
- `strict` - `default` plus header length limits and common type/scope restrictions

Start with a preset and override only the rules you need.

Merge behavior:

- command-line `-p/--preset` overrides `preset:` inside the config file
- rule properties you omit keep the preset's values
- `regexes: []` explicitly clears inherited preset regexes for that field

## Validation Errors

Validation errors are reported after parsing succeeds.

Examples:

- `type 'foo' is not in allowed values: ["feat", "fix"]`
- `header line length 51 is greater than 50`
- `required scope is missing`
- `description does not match regex '^.*[^ ]$'`

## Example: Parseable but Fails Validation

As in [`PARSING.md`](PARSING.md), `\n` denotes a newline character in the example below.

```yaml
preset: strict

scope:
  required: true

footers:
  Closes:
    required: true
```

This message is parseable, but it fails validation because the required `scope` and `Closes` footer are missing:

```text
feat: add repository option\n
```