feat: Initial commitHEADmain

1 files changed, 164 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2cc58af
--- /dev/null
+++ b/README.md
@@ -0,0 +1,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.