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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# 🏰 Kivia
> Self-documenting Name Analyser for Go
Name things so your code explains itself.
Kivia is a fast, local-only analyser that flags identifiers whose terms are absent from dictionary sources or resemble abbreviations of dictionary words. It is built for teams that want explicit, readable naming conventions without external AI calls.
## Philosophy
Identifier names should be fully self-documenting.
Kivia enforces a strict readability standard:
- Prefer full words over shorthand
- Avoid ambiguous abbreviations
- Keep the naming intent clear from the identifier itself
Examples:
- `userNum` → invalid (`num` is an abbreviation)
- `ctx` → invalid (`ctx` is an abbreviation)
- `userCount` → valid
- `requestContext` → valid
## Rules
1. **Dictionary words pass**: If a token is present in the loaded dictionary sources, it passes.
2. **Abbreviations are violations**: If a token expands to a dictionary word (for example, `ctx` -> `context`), it is flagged.
3. **Unknown terms are violations**: If a token is not in the dictionary and does not map to a known expansion, it is flagged.
4. **Minimum length is explicit**: `--min-eval-length` determines whether short identifiers are evaluated.
Kivia also applies dictionary-backed spelling-variant matching for common British/American pairs (for example `normalise`/`normalize`, `colour`/`color`, `centre`/`center`).
## How It Works
Kivia parses Go source using the standard library's AST, extracts identifiers, tokenises names (camel, snake, or kebab), and evaluates each token against a local NLP dictionary pipeline.
- No network requests
- No LLM/API dependency
- Deterministic local analysis
## Installation
```bash
go install github.com/Fuwn/kivia@latest
```
Or build locally:
```bash
go build -o ./bin/kivia .
```
## Usage
```bash
# Analyse a package tree
kivia --path ./...
# Ignore single-letter names during evaluation
kivia --path ./... --min-eval-length 2
# Ignore specific violations
kivia --path ./... --ignore name=ctx --ignore file=testdata
# JSON output without context payload
kivia --path ./... --format json --omit-context
```
### Flags
| Flag | Description |
|------|-------------|
| `--path` | Path to analyse (`directory`, `file`, or `./...`). |
| `--omit-context` | Hide usage context in output. |
| `--min-eval-length` | Minimum identifier length in runes to evaluate (must be `>= 1`). |
| `--format` | Output format: `text` or `json`. |
| `--fail-on-violation` | Exit with code `1` when violations are found. |
| `--ignore` | Ignore violations by matcher. Repeatable. Prefixes: `name=`, `kind=`, `file=`, `reason=`, `func=`. |
## Ignore Matchers
`--ignore` supports targeted filtering:
- `name=<substring>`
- `kind=<substring>`
- `file=<substring>`
- `reason=<substring>`
- `func=<substring>`
Without a prefix, the matcher is applied as a substring across all violation fields.
Example:
```bash
kivia --path ./... \
--ignore name=ctx \
--ignore reason=abbreviation \
--ignore file=_test.go
```
## Output
### Text (default)
```text
internal/example/sample.go:12:9 parameter "ctx": Contains abbreviation: ctx.
context: type=context.Context, function=Handle
```
### JSON
```json
{
"violations": [
{
"identifier": {
"name": "ctx",
"kind": "parameter",
"file": "internal/example/sample.go",
"line": 12,
"column": 9,
"context": {
"enclosingFunction": "Handle",
"type": "context.Context"
}
},
"reason": "Contains abbreviation: ctx."
}
]
}
```
## Identifier Scope (Go)
Kivia currently extracts and evaluates:
- Types
- Functions and methods
- Receivers
- Parameters
- Named results
- Variables (`var`/`const` and `:=`)
- Range keys and values
- Struct fields
- Interface methods
## Dictionary and NLP Source
Kivia loads dictionary data only from configured/system dictionary files.
1. `KIVIA_DICTIONARY_PATH` (optional): one path or multiple paths separated by your OS path separator (`:` on macOS/Linux, `;` on Windows). Commas are also accepted.
2. If `KIVIA_DICTIONARY_PATH` is not set, Kivia uses a default set of dictionary files (for example, `/usr/share/dict/words`, `/usr/share/dict/web2`, and Hunspell dictionaries when present).
3. If no usable words are found, the analysis fails with an error.
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
|