kv-cli 0.9.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
Binary file
|
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: kv-cli
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Classifier: Environment :: Console
|
|
5
|
+
Classifier: Intended Audience :: Developers
|
|
6
|
+
Classifier: Programming Language :: Rust
|
|
7
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Summary: Contract guardrails for data pipelines: missing parameters, hardcoded secrets and pinned infrastructure, caught before code leaves the workstation.
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
12
|
+
Project-URL: Changelog, https://github.com/kovallent/kv-cli/blob/main/CHANGELOG.md
|
|
13
|
+
Project-URL: Homepage, https://github.com/kovallent/kv-cli
|
|
14
|
+
Project-URL: Issues, https://github.com/kovallent/kv-cli/issues
|
|
15
|
+
|
|
16
|
+
# kv-cli
|
|
17
|
+
|
|
18
|
+
**Local contract guardrails for Python data pipelines.** Airflow, dbt, Databricks, Snowpark, Flink, Polars.
|
|
19
|
+
|
|
20
|
+
[](https://github.com/kovallent/kv-cli/actions/workflows/ci.yml)
|
|
21
|
+
[](https://github.com/kovallent/kv-cli/releases/latest)
|
|
22
|
+
[](LICENSE)
|
|
23
|
+
[](https://github.com/kovallent/kv-cli/releases)
|
|
24
|
+
[](https://github.com/kovallent/kv-cli/discussions)
|
|
25
|
+
|
|
26
|
+
Some pipeline bugs are syntactically fine and pass their tests. They break only when the code runs somewhere other than the author's laptop. `kv-cli` catches three kinds before the code leaves the workstation:
|
|
27
|
+
|
|
28
|
+
| Rule | Catches | Severity |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| [`KV001`](docs/rules/KV001.md) | A governed function missing a required parameter such as `target_environment` | per parameter |
|
|
31
|
+
| [`KV002`](docs/rules/KV002.md) | A hardcoded credential, in code, notebooks or config | error |
|
|
32
|
+
| [`KV003`](docs/rules/KV003.md) | Infrastructure pinned to one environment: a warehouse, bucket, cluster ID or endpoint | warning |
|
|
33
|
+
|
|
34
|
+
It is a single binary with no runtime dependencies. It parses your code locally with tree-sitter, needs no account and makes no network call. Run `kv-cli explain KV002` for any rule's reference, offline.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## What a run looks like
|
|
39
|
+
|
|
40
|
+
This is a real session against [`samples/deploy.py`](samples/deploy.py), shortened where marked `…`:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
$ kv-cli init
|
|
44
|
+
created ./.kovallent.yaml
|
|
45
|
+
· required parameters: target_environment, dry_run
|
|
46
|
+
· secret detectors: 9 name patterns, 12 value patterns
|
|
47
|
+
· framework profiles: dbt, polars, flink, databricks, snowpark, airflow (auto-detected per file)
|
|
48
|
+
|
|
49
|
+
Next: kv-cli audit
|
|
50
|
+
|
|
51
|
+
$ kv-cli audit --strict samples/deploy.py
|
|
52
|
+
kv-cli audit .kovallent.yaml 1 file
|
|
53
|
+
· contract a6edcff00199c1cf
|
|
54
|
+
· functions: 7 in scope, 0 framework-exempt, 2 user-exempt, 1 out of scope
|
|
55
|
+
|
|
56
|
+
samples/deploy.py
|
|
57
|
+
11 error KV002 `DB_PASSWORD` is assigned a hardcoded literal
|
|
58
|
+
value "s3…" (<redacted>, 20 chars) - load it from the environment or a secret store
|
|
59
|
+
20 error KV001 `deploy_service` is missing contract parameter `target_environment`
|
|
60
|
+
expected signature to declare `target_environment: str = "dev"`
|
|
61
|
+
in scope: name matches applies_to.name_patterns "deploy*"
|
|
62
|
+
…
|
|
63
|
+
|
|
64
|
+
· files: 1 failing, 0 warning-only, 0 clean, 0 skipped
|
|
65
|
+
FAIL 13 errors, 6 warnings (19 gating under --strict)
|
|
66
|
+
|
|
67
|
+
$ kv-cli fix samples/deploy.py
|
|
68
|
+
kv-cli fix
|
|
69
|
+
|
|
70
|
+
samples/deploy.py
|
|
71
|
+
+ added `target_environment` to deploy_service()
|
|
72
|
+
~ `DB_PASSWORD` now reads os.environ["DB_PASSWORD"]
|
|
73
|
+
…
|
|
74
|
+
|
|
75
|
+
manual: samples/deploy.py:90 `password` has a hardcoded default; move the lookup into the body so it is read per call, not at import time
|
|
76
|
+
FIXED applied 18 changes across 1 file
|
|
77
|
+
…
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- **The secret is redacted** in the output. A tool that prints credentials into CI logs has moved the leak, not closed it.
|
|
81
|
+
- **`fix` rewrites code rather than describing it.** It inserts missing parameters and moves credentials to `os.environ`. It leaves a hardcoded *default* as a `manual:` item, because `os.environ[...]` in a default is read once, at import time.
|
|
82
|
+
- **The run states its scope.** `7 in scope, 0 framework-exempt, …` is the denominator behind the result. Without it, a repository where every function is framework-owned would look identical to one that complies.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Quickstart
|
|
87
|
+
|
|
88
|
+
**1. Install.** On macOS or Linux with Homebrew:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
brew install kovallent/tap/kv-cli
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
It installs the prebuilt binary, with no Rust toolchain needed, and `brew upgrade kv-cli` picks up new releases.
|
|
95
|
+
|
|
96
|
+
Without Homebrew, download your platform's archive from the [latest release](https://github.com/kovallent/kv-cli/releases/latest) and unpack it:
|
|
97
|
+
|
|
98
|
+
| Platform | Archive |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| macOS, Apple silicon | `kv-cli-aarch64-apple-darwin.tar.gz` |
|
|
101
|
+
| macOS, Intel | `kv-cli-x86_64-apple-darwin.tar.gz` |
|
|
102
|
+
| Linux x86-64 | `kv-cli-x86_64-unknown-linux-gnu.tar.gz` |
|
|
103
|
+
| Linux ARM64 | `kv-cli-aarch64-unknown-linux-gnu.tar.gz` |
|
|
104
|
+
| Windows x86-64 | `kv-cli-x86_64-pc-windows-msvc.tar.gz` (contains `kv-cli.exe`) |
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# macOS / Linux: set TARGET to the archive name for your platform, minus kv-cli- and .tar.gz
|
|
108
|
+
TARGET=aarch64-apple-darwin
|
|
109
|
+
curl -sSL "https://github.com/kovallent/kv-cli/releases/latest/download/kv-cli-$TARGET.tar.gz" | tar xz
|
|
110
|
+
sudo mv kv-cli /usr/local/bin/
|
|
111
|
+
kv-cli --version
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
On Windows 10 and later, unpack with the built-in `tar -xzf kv-cli-x86_64-pc-windows-msvc.tar.gz` and put `kv-cli.exe` on your `PATH`.
|
|
115
|
+
|
|
116
|
+
Each release ships `SHA256SUMS`. To verify a download, run `grep "$TARGET" SHA256SUMS | shasum -a 256 -c` (or `sha256sum -c` on Linux).
|
|
117
|
+
|
|
118
|
+
> **macOS says the app "cannot be opened"?** The binary is not notarized, and archives downloaded through a browser are quarantined. Run `xattr -d com.apple.quarantine kv-cli`. Downloads made with `curl`, as above, are not affected.
|
|
119
|
+
|
|
120
|
+
**2. Run it on a pipeline repository.**
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
cd ~/your-pipeline-repo
|
|
124
|
+
kv-cli audit # works with built-in defaults
|
|
125
|
+
kv-cli init # optional: write .kovallent.yaml to tune the rules
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Exit `0` means compliant and `1` means findings. A 500-file repository takes about 0.3s on 8 cores.
|
|
129
|
+
|
|
130
|
+
### Try it on the bundled samples first
|
|
131
|
+
|
|
132
|
+
`samples/` ships pipelines that trip every rule, so you can read real output before trusting the tool with your own code:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
git clone https://github.com/kovallent/kv-cli && cd kv-cli
|
|
136
|
+
kv-cli init # created ./.kovallent.yaml
|
|
137
|
+
kv-cli audit --strict samples/ # FAIL 31 errors, 17 warnings — by design
|
|
138
|
+
kv-cli audit --show-clean samples/ # also lists each clean file, with its scope
|
|
139
|
+
kv-cli fix samples/deploy.py # FIXED applied 18 changes across 1 file
|
|
140
|
+
kv-cli audit samples/compliant.py # PASS — must always be clean
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`samples/deploy.py` exercises every detector and suppression. `samples/frameworks/` has one file per supported stack. `samples/credentials.py` shows every form a hardcoded credential takes, next to names that are *not* credentials. `samples/configs/` and `samples/notebooks/` cover `.env`, `airflow.cfg`, TOML, JSON and a notebook whose saved output printed a token. A test checks the counts above against the real output.
|
|
144
|
+
|
|
145
|
+
### It found nothing. Is it working?
|
|
146
|
+
|
|
147
|
+
1. **Your models are SQL.** SQL is not analysed. Python gets the full audit; notebooks and config files (YAML, `.env`, TOML, INI/`.cfg`, JSON) are scanned for credentials only.
|
|
148
|
+
2. **Your functions are not governed.** By default, `KV001` covers functions named like `deploy*`, `run_*`, `*_pipeline`, `*_job` or `main`, or decorated with `@task`. Run `kv-cli init` and edit `applies_to`, or see [`KV001`](docs/rules/KV001.md).
|
|
149
|
+
3. **A framework owns your signatures.** Check the scope line. A low `in scope` count with a high `framework-exempt` count means the exemption is working, not missing things. See [frameworks](docs/frameworks.md).
|
|
150
|
+
|
|
151
|
+
`kv-cli audit --show-clean` names each clean file with its own scope, so you can confirm a specific file was checked. A file reads `nothing enforced` when none of its functions were under the contract, and `credentials only` when it is a config file or notebook.
|
|
152
|
+
|
|
153
|
+
If no file matched at all, that is not a pass. The run exits `2` with `no files to audit` and names the patterns it tried.
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Use it in CI
|
|
158
|
+
|
|
159
|
+
### With the GitHub Action
|
|
160
|
+
|
|
161
|
+
`uses: kovallent/kv-cli@<tag>` installs the release binary for the runner, verifies it against the release's `SHA256SUMS`, annotates each finding on the pull request, writes a job summary with the scope block, and exits with kv-cli's exit code. The gate is that exit code, computed on the runner, so it works without any Kovallent service:
|
|
162
|
+
|
|
163
|
+
```yaml
|
|
164
|
+
name: kovallent
|
|
165
|
+
on:
|
|
166
|
+
pull_request:
|
|
167
|
+
push:
|
|
168
|
+
branches: [main]
|
|
169
|
+
|
|
170
|
+
jobs:
|
|
171
|
+
gate:
|
|
172
|
+
name: Kovallent gate
|
|
173
|
+
runs-on: ubuntu-latest
|
|
174
|
+
steps:
|
|
175
|
+
- uses: actions/checkout@v4
|
|
176
|
+
- uses: kovallent/kv-cli@v0.9.0
|
|
177
|
+
with:
|
|
178
|
+
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
To upload the JSON report, set `upload-url`. The Action authenticates with a GitHub Actions OIDC token, so **the calling workflow needs `permissions: id-token: write`**. The upload is best-effort and never changes the result. [CI with the GitHub Action](docs/ci.md) covers every input, making the job a required status check, and protecting `.github/workflows/` with `CODEOWNERS`.
|
|
182
|
+
|
|
183
|
+
### Without the Action
|
|
184
|
+
|
|
185
|
+
Add this as `.github/workflows/kovallent.yml`. It installs a pinned release, verifies its checksum and fails the pull request on any finding:
|
|
186
|
+
|
|
187
|
+
```yaml
|
|
188
|
+
name: kovallent
|
|
189
|
+
on: [pull_request]
|
|
190
|
+
|
|
191
|
+
jobs:
|
|
192
|
+
audit:
|
|
193
|
+
runs-on: ubuntu-latest
|
|
194
|
+
steps:
|
|
195
|
+
- uses: actions/checkout@v4
|
|
196
|
+
- name: Install kv-cli
|
|
197
|
+
env:
|
|
198
|
+
KV_VERSION: v0.9.0
|
|
199
|
+
TARGET: x86_64-unknown-linux-gnu
|
|
200
|
+
run: |
|
|
201
|
+
cd "$RUNNER_TEMP"
|
|
202
|
+
base="https://github.com/kovallent/kv-cli/releases/download/$KV_VERSION"
|
|
203
|
+
curl -sSLO "$base/kv-cli-$TARGET.tar.gz"
|
|
204
|
+
curl -sSLO "$base/SHA256SUMS"
|
|
205
|
+
grep "kv-cli-$TARGET.tar.gz" SHA256SUMS | sha256sum -c -
|
|
206
|
+
tar -xzf "kv-cli-$TARGET.tar.gz"
|
|
207
|
+
echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
|
|
208
|
+
- run: kv-cli audit --strict
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`--strict` fails on warnings too, `KV003` included. Drop it to gate on errors only.
|
|
212
|
+
|
|
213
|
+
Exit codes are a stable interface, and each one is a problem for a different owner:
|
|
214
|
+
|
|
215
|
+
| Code | Meaning | Escalates to |
|
|
216
|
+
| --- | --- | --- |
|
|
217
|
+
| **0** | Compliant | — |
|
|
218
|
+
| **1** | Findings | The pull-request author |
|
|
219
|
+
| **2** | Tool error, including "no files to audit" | Whoever operates the gate |
|
|
220
|
+
| **3** | Contract drift (`--expect-contract`) | Whoever owns the contract |
|
|
221
|
+
|
|
222
|
+
After a successful run in a terminal or CI log, `kv-cli` prints one dimmed line to stderr asking for a GitHub star. It never appears in stdout, alongside `--format json`, or after a failing run, and it makes no network call.
|
|
223
|
+
|
|
224
|
+
### Stop a pull request from weakening the contract
|
|
225
|
+
|
|
226
|
+
The contract is the policy, so a pull request that edits `.kovallent.yaml` could switch off the very checks meant to stop it. Pin the contract's fingerprint where pull-request authors can't edit it, and any change to a rule fails the gate with exit `3`, while reformatting or editing a comment does not.
|
|
227
|
+
|
|
228
|
+
```diff
|
|
229
|
+
# .kovallent.yaml, changed in the pull request
|
|
230
|
+
secrets:
|
|
231
|
+
- enabled: true
|
|
232
|
+
+ enabled: false
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
```text
|
|
236
|
+
$ kv-cli audit --expect-contract a6edcff00199c1cf
|
|
237
|
+
…
|
|
238
|
+
CONTRACT DRIFT the local contract is not the one this repository pins
|
|
239
|
+
expected a6edcff00199c1cf
|
|
240
|
+
local 8e556afd14a4f728
|
|
241
|
+
findings above were computed against the local contract
|
|
242
|
+
this is not a code failure - it escalates to whoever owns the contract
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
With the Action, that is the `expect-contract` input; in the workflow without it, `kv-cli audit --strict --expect-contract ${{ vars.KOVALLENT_CONTRACT_SHA }}`. Either way the value comes from `kv-cli contract show` and is stored as an organization variable. [Contract pinning](docs/contract-pinning.md) covers why the pin must live outside the repository and how to close the remaining gaps. For machine-readable output, `--format json` emits a [documented payload](docs/json-payload.md), with `run.contract_drift` set on a mismatch.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Pre-commit
|
|
250
|
+
|
|
251
|
+
```yaml
|
|
252
|
+
repos:
|
|
253
|
+
- repo: https://github.com/kovallent/kv-cli
|
|
254
|
+
rev: v0.9.0
|
|
255
|
+
hooks:
|
|
256
|
+
- id: kv-cli # audits staged Python, notebooks and config files
|
|
257
|
+
- id: kv-cli-contract # validates .kovallent.yaml when it changes
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
These hooks build kv-cli from source on first run (`language: rust`), so each contributor needs Rust and a C compiler and waits through one compile. To use an installed binary instead:
|
|
261
|
+
|
|
262
|
+
```yaml
|
|
263
|
+
repos:
|
|
264
|
+
- repo: local
|
|
265
|
+
hooks:
|
|
266
|
+
- id: kv-cli
|
|
267
|
+
name: kv-cli contract audit
|
|
268
|
+
entry: kv-cli audit
|
|
269
|
+
language: system
|
|
270
|
+
types: [text]
|
|
271
|
+
files: '(\.(py|ipynb|ya?ml|toml|ini|cfg|json|env)|(^|/)\.env(\.[^/]*)?)$'
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
A hook is advisory: `--no-verify` skips it, and a fresh clone installs none. It is where a finding is cheapest to fix. The CI gate is what guarantees compliance.
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Commands
|
|
279
|
+
|
|
280
|
+
| Command | Purpose |
|
|
281
|
+
| --- | --- |
|
|
282
|
+
| `kv-cli init` | Write a commented `.kovallent.yaml` and report what it enables. `--force` overwrites. |
|
|
283
|
+
| `kv-cli audit [PATHS]` | Scan for violations. `--strict`, `--format json`, `--config`, `--expect-contract`. |
|
|
284
|
+
| `kv-cli fix [PATHS]` | Apply the standard fixes, backing up each file to `.kvbak`. `--dry-run`, `--no-backup`. |
|
|
285
|
+
| `kv-cli explain [CODE]` | Print a rule's reference: what it catches, how to fix it, how to suppress it. |
|
|
286
|
+
| `kv-cli contract check` | Validate the contract without scanning code, listing every problem with its line. |
|
|
287
|
+
| `kv-cli contract show` | Print the effective contract, with every default marked, and its fingerprint. |
|
|
288
|
+
| `kv-cli contract schema` | Print the JSON Schema for `.kovallent.yaml`, for editor validation. |
|
|
289
|
+
| `kv-cli frameworks` | Show the built-in framework profiles and what each contributes. |
|
|
290
|
+
| `kv-cli schema` | Print the JSON Schema of the `--format json` payload. |
|
|
291
|
+
|
|
292
|
+
Every command takes `--help`, with examples.
|
|
293
|
+
|
|
294
|
+
To suppress one finding, add a trailing `# kovallent:allow-secret` (`KV002`) or `# kovallent:allow-infra` (`KV003`). To exempt a function from `KV001`, add its name to `applies_to.exempt_name_patterns`.
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## Framework support
|
|
299
|
+
|
|
300
|
+
Each profile applies only to files that use the framework, detected from imports. That scoping is what makes aggressive rules safe: `warehouse` would be noisy everywhere, but in a file that imports `snowflake` it is precise.
|
|
301
|
+
|
|
302
|
+
| Profile | Detected by | Contributes |
|
|
303
|
+
| --- | --- | --- |
|
|
304
|
+
| **dbt** | `def model(dbt, session)` | Owns the model signature; `profiles.yml` credentials |
|
|
305
|
+
| **polars** | `import polars` | `storage_options` credentials; object-store paths |
|
|
306
|
+
| **flink** | `import pyflink` | Owns `@udf`/`@udtf`/`@udaf`; broker and JDBC endpoints |
|
|
307
|
+
| **databricks** | `import dlt` / `databricks` / `pyspark` | Owns `@dlt.table`/`@dlt.view`; PATs; workspace URLs, cluster IDs, DBFS paths |
|
|
308
|
+
| **snowpark** | `import snowflake` | Owns `@sproc`/`@udf`; account, warehouse, role |
|
|
309
|
+
| **airflow** | `import airflow` | Owns `@dag`/`@task_group`/`@setup`/`@teardown`; governs `@task` (report-only); Fernet keys; `conn_id`, pool, queue |
|
|
310
|
+
|
|
311
|
+
A signature the framework owns is exempt from `KV001`, because the framework calls it and adding a parameter would break the pipeline. [Frameworks](docs/frameworks.md) covers the details, including why Airflow's `@task` is reported but never auto-fixed.
|
|
312
|
+
|
|
313
|
+
## Stack compatibility
|
|
314
|
+
|
|
315
|
+
* **Python:** source written for any Python 3 release through 3.14. `kv-cli` never runs Python; it parses source with tree-sitter, so no interpreter is needed and the version installed does not matter. Covered syntax includes `:=` and `/` parameters (3.8), `match` (3.10), `except*` (3.11), `type` aliases, generic `def f[T]` / `class C[T]` and nested-quote f-strings (3.12), and `t"…"` template strings and unparenthesised `except A, B:` (3.14).
|
|
316
|
+
* **Known gap:** type-parameter defaults (`def f[T = int]`, 3.13) do not parse. Such a file is audited on a partial parse and listed as `syntax_error` (a warning; an error under `--strict`); findings elsewhere in the file are still reported, and `fix` will not rewrite it.
|
|
317
|
+
* **Files:** Python gets all three rules. Notebooks and config files (YAML, `.env`, TOML, INI/`.cfg`, JSON) get `KV002`. Files must be UTF-8; anything else is reported as unreadable rather than guessed at.
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## How this differs from other tools
|
|
322
|
+
|
|
323
|
+
| | Linters (Ruff, Flake8, SQLFluff) | Secret scanners (detect-secrets, gitleaks) | AppSec (CodeQL) | **kv-cli** |
|
|
324
|
+
| --- | --- | --- | --- | --- |
|
|
325
|
+
| Checks the code is **well-formed** | yes | — | partial | — |
|
|
326
|
+
| Checks the code is **portable across environments** | no | no | no | **yes** |
|
|
327
|
+
| Data-stack aware (Airflow, dbt, Databricks, Snowpark) | no | no | no | **yes** |
|
|
328
|
+
| Enforces a **required-parameter contract** | no | no | no | **yes** |
|
|
329
|
+
| Runs locally with nothing transmitted | yes | yes | usually not | **yes** |
|
|
330
|
+
|
|
331
|
+
`detect-secrets` finds high-entropy strings. `KV002` also finds a literal assigned to a name your contract forbids, which catches `password = "dev"`. Neither has any concept of "this function must accept `target_environment`."
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Documentation
|
|
336
|
+
|
|
337
|
+
- **Rules:** [KV001](docs/rules/KV001.md), [KV002](docs/rules/KV002.md), [KV003](docs/rules/KV003.md), also available offline as `kv-cli explain <code>`.
|
|
338
|
+
- [Configuration](docs/configuration.md): the contract file, how patterns match, editor validation, upgrading.
|
|
339
|
+
- [Frameworks](docs/frameworks.md): profiles, owned signatures, governed decorators.
|
|
340
|
+
- [CI with the GitHub Action](docs/ci.md): the Action's inputs, required status checks, protecting the workflow, uploading with OIDC.
|
|
341
|
+
- [Contract pinning](docs/contract-pinning.md): stopping a pull request from weakening the contract.
|
|
342
|
+
- [JSON payload](docs/json-payload.md): the `--format json` schema.
|
|
343
|
+
- [How it works](docs/how-it-works.md): the AST scanner, config scanners and what `fix` changes.
|
|
344
|
+
- [Development](docs/development.md): building, testing and the labelled corpus.
|
|
345
|
+
- [Architecture decisions](docs/adr/) and the [changelog](CHANGELOG.md).
|
|
346
|
+
|
|
347
|
+
### Other ways to install
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
cargo install --git https://github.com/kovallent/kv-cli --tag v0.9.0
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Building from source (`cargo install`, `make release`) needs a C compiler for the tree-sitter grammar: Xcode Command Line Tools on macOS, `build-essential` on Debian/Ubuntu. The first compile takes a few minutes. There is no PyPI package, so `pip install kv-cli` will not work.
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## Contributing
|
|
358
|
+
|
|
359
|
+
Contributions are welcome: a new rule, a parsing improvement, a bug fix.
|
|
360
|
+
|
|
361
|
+
1. Fork and branch (`git checkout -b feature/new-rule`).
|
|
362
|
+
2. Open a thread in [Discussions](https://github.com/kovallent/kv-cli/discussions) if you want to talk it through first.
|
|
363
|
+
3. Run `make check` and open a pull request. [Development](docs/development.md) explains the test suite.
|
|
364
|
+
|
|
365
|
+
Released under the [MIT License](LICENSE).
|
|
366
|
+
|
|
367
|
+
## Community
|
|
368
|
+
|
|
369
|
+
* [Announcements](https://github.com/kovallent/kv-cli/discussions/categories/announcements): release notes and roadmap.
|
|
370
|
+
* [Ideas and feature requests](https://github.com/kovallent/kv-cli/discussions/categories/ideas-feature-requests): propose a rule or a framework profile.
|
|
371
|
+
* [Q&A](https://github.com/kovallent/kv-cli/discussions/categories/q-a): setup, rules, custom configuration.
|
|
372
|
+
* [Kovallent Enterprise waitlist](https://www.kovallent.com): team-wide policy governance and scorecards.
|
|
373
|
+
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
kv_cli-0.9.0.data/scripts/kv-cli.exe,sha256=DMMeaStU1trcY8a2F4ZOVR8ccrWUmmWShdX3vvaCy60,3238400
|
|
2
|
+
kv_cli-0.9.0.dist-info/METADATA,sha256=23gdHDO1ylbS9sJ6gy2s9E67qsSRqn41x71imaI3o9k,19900
|
|
3
|
+
kv_cli-0.9.0.dist-info/WHEEL,sha256=Uvw7WSmy7Kj2FBk8Va4L_dq4MDW8X5Ynby-pOX3ZNS0,94
|
|
4
|
+
kv_cli-0.9.0.dist-info/licenses/LICENSE,sha256=xKi6gXTLXcmBMOpktyfSAchWaJMaKWc2XL6qizW5VCs,1087
|
|
5
|
+
kv_cli-0.9.0.dist-info/sboms/kv-cli.cyclonedx.json,sha256=zi6UPHakxHVzDthwl5osKcluc6Ybh4sO2DjJRDQC7AU,76419
|
|
6
|
+
kv_cli-0.9.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kovallent
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|