kv-cli 0.9.0__tar.gz → 0.11.0__tar.gz
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.
- kv_cli-0.11.0/.gitattributes +6 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/CHANGELOG.md +75 -4
- {kv_cli-0.9.0 → kv_cli-0.11.0}/Cargo.lock +1 -1
- {kv_cli-0.9.0 → kv_cli-0.11.0}/Cargo.toml +1 -1
- {kv_cli-0.9.0 → kv_cli-0.11.0}/PKG-INFO +28 -14
- {kv_cli-0.9.0 → kv_cli-0.11.0}/README.md +27 -13
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/ci.md +57 -4
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/configuration.md +5 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/development.md +2 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/frameworks.md +4 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/json-payload.md +2 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/rules/KV003.md +13 -1
- {kv_cli-0.9.0 → kv_cli-0.11.0}/schema/contract.v1.json +4 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/audit.rs +151 -8
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/config.rs +21 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/frameworks.rs +193 -47
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/main.rs +53 -1
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/python.rs +208 -2
- kv_cli-0.11.0/src/sarif.rs +295 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/cli.rs +303 -0
- kv_cli-0.11.0/tests/fixtures/deploy.py.sarif +643 -0
- kv_cli-0.11.0/tests/fixtures/sarif-schema-2.1.0.json +3389 -0
- kv_cli-0.11.0/tests/fixtures/sarif-schema-2.1.0.md +14 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.github/workflows/action-selftest.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.github/workflows/ci.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.github/workflows/release.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.github/workflows/wheels.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.gitignore +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/.pre-commit-hooks.yaml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/LICENSE +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/Makefile +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action/annotate.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action/audit.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action/install.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action/summary.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action/upload.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/action.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/0001-contract-distribution.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/0002-tenancy.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/0003-active-contributor.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/0004-membership-and-roles.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/0005-api-tokens.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/adr/fixtures/0003-worked-example.json +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/contract-pinning.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/how-it-works.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/media/kv-cli-demo.svg +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/rules/KV001.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/docs/rules/KV002.md +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/examples/dump.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/packaging/homebrew/formula.sh +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/pyproject.toml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/compliant.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/configs/.env.example +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/configs/.env.production +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/configs/airflow.cfg +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/configs/secrets.toml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/configs/settings.json +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/credentials.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/deploy.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/airflow_dag.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/databricks_dlt.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/dbt_model.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/flink_job.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/polars_etl.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/profiles.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/frameworks/snowpark_proc.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/samples/notebooks/exploration.ipynb +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/schema/findings.v1.json +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/configscan.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/fix.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/jinja.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/notebook.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/payload.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/src/yamlscan.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/common/mod.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/.gitattributes +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/baseline.tsv +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/.env.example +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/airflow.cfg +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/camel.json +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/camel.json.expect +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/ci.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/profiles.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/secrets.toml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/settings.json +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/config/settings.json.expect +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/notebooks/analysis.ipynb +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/notebooks/analysis.ipynb.expect +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/edge/bom.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/edge/crlf.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/edge/latin1.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/edge/syntax_error.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/edge/tabs.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/frameworks/airflow.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/frameworks/databricks.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/frameworks/dbt_model.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/frameworks/flink.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/frameworks/snowpark.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/kv001_scope.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/kv002_forms.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/kv002_values.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/cases/python/kv003_infra.py +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/edge.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/matrix/names.tsv +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus/matrix/values.tsv +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/corpus.rs +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/fixtures/gate-test-kovallent.yml +0 -0
- {kv_cli-0.9.0 → kv_cli-0.11.0}/tests/fixtures/payload-v0.7.2.json +0 -0
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Text files are stored and checked out with LF on every platform. The rule
|
|
2
|
+
# docs are compiled into the binary with include_str!, and golden files are
|
|
3
|
+
# compared byte for byte, so a CRLF checkout (core.autocrlf on Windows) would
|
|
4
|
+
# change both. tests/corpus/.gitattributes overrides this for case files,
|
|
5
|
+
# which must keep their exact bytes.
|
|
6
|
+
* text=auto eol=lf
|
|
@@ -15,6 +15,81 @@ Nothing yet.
|
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
18
|
+
## [0.11.0] — 2026-11-18
|
|
19
|
+
|
|
20
|
+
SARIF output for code-scanning tools. Contract fingerprints, the JSON payload
|
|
21
|
+
and exit codes are unchanged.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- **`kv-cli audit --format sarif`** writes one SARIF 2.1.0 log to stdout,
|
|
26
|
+
built from the same findings and run as `--format json`.
|
|
27
|
+
- `tool.driver` names kv-cli and its version, with one rule each for KV001,
|
|
28
|
+
KV002 and KV003, described with the text `kv-cli explain` prints: the
|
|
29
|
+
title, the first paragraph of "What it catches", and the whole page as
|
|
30
|
+
help.
|
|
31
|
+
- Each finding is one result: its code as `ruleId`, `level` from its
|
|
32
|
+
intrinsic severity (`--strict` does not change it, as in JSON), its
|
|
33
|
+
message, and its file (the same normalized path as `path`) and line.
|
|
34
|
+
- `partialFingerprints` carries the finding's fingerprint under
|
|
35
|
+
`kovallent/v1`, equal to its JSON `fingerprint`.
|
|
36
|
+
- Result properties carry `symbol`, `subject`, `detail`, `framework` and
|
|
37
|
+
`report_only` as in JSON. A KV002 detail stays redacted.
|
|
38
|
+
- Run properties carry the scope block, `contract_sha256`, `contract_path`
|
|
39
|
+
and `schema_version`, so no result travels without its scope.
|
|
40
|
+
- Files in `skipped` are `invocations[0].toolExecutionNotifications` at
|
|
41
|
+
level `warning`, so a partial parse is never silent.
|
|
42
|
+
- Exit codes are unchanged (0, 1, 2, 3), and no star line follows SARIF.
|
|
43
|
+
- Tests validate the output against the SARIF 2.1.0 schema, vendored in
|
|
44
|
+
`tests/fixtures`, so they make no network call.
|
|
45
|
+
- **docs/ci.md: Code scanning with SARIF.** Uploading the log with
|
|
46
|
+
`github/codeql-action/upload-sarif` (`security-events: write`), in addition
|
|
47
|
+
to the exit-code gate, never in place of it: a code-scanning alert does not
|
|
48
|
+
block a merge unless a ruleset makes it.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## [0.10.0] — 2026-11-18
|
|
53
|
+
|
|
54
|
+
Two precision fixes for a first run. **Contract fingerprints are unchanged,
|
|
55
|
+
including the built-in default's (`a6edcff00199c1cf`), but findings can
|
|
56
|
+
change**: the same contract now reports fewer KV003 findings in files that use
|
|
57
|
+
no data framework, and can report KV001 on functions it used to exempt by
|
|
58
|
+
mistake.
|
|
59
|
+
|
|
60
|
+
### Changed
|
|
61
|
+
|
|
62
|
+
- **KV003's name rule waits for a framework.** `infrastructure.key_patterns`,
|
|
63
|
+
by default `*warehouse*`, `*catalog*`, `*cluster_id*`, `*workspace_url*` and
|
|
64
|
+
`*bucket*` plus any you added, now applies only in Python files where a
|
|
65
|
+
framework profile is detected. In a file that imports no data framework,
|
|
66
|
+
`warehouse = "PROD_WH"` is no longer reported. Value patterns, such as
|
|
67
|
+
`s3://` URIs and JDBC URLs, still apply in every Python file, and each
|
|
68
|
+
profile's own key rules still apply where the profile is detected (Snowpark
|
|
69
|
+
adds `*warehouse*`, Databricks `*catalog*`, Polars `*bucket*`). The new
|
|
70
|
+
contract field `infrastructure.global_key_patterns_require_framework`
|
|
71
|
+
(default `true`) controls this; set it to `false` to keep 0.9.0's behaviour.
|
|
72
|
+
At its default the field is left out of the serialized contract, so no
|
|
73
|
+
fingerprint moves; set to `false`, it is part of the contract and changes the
|
|
74
|
+
fingerprint, so re-pin `--expect-contract`. `schema/contract.v1.json` and the
|
|
75
|
+
`kv-cli init` template include it.
|
|
76
|
+
|
|
77
|
+
### Fixed
|
|
78
|
+
|
|
79
|
+
- **A framework's decorator must come from the framework.** A decorator a
|
|
80
|
+
profile owns or governs (Databricks `@table`, `@view`, `@pandas_udf`; Flink
|
|
81
|
+
and Snowpark `@udf`; Airflow `@task` and others) used to match by its last
|
|
82
|
+
segment alone, so Flask's `@app.view` or a locally defined `@table` silently
|
|
83
|
+
exempted its function from KV001 and made the file count as a Databricks
|
|
84
|
+
file. It now matches only when the file imports it from a module the profile
|
|
85
|
+
detects: `from dlt import table`, or `import pyspark.sql.functions as F` for
|
|
86
|
+
`@F.pandas_udf`. A decorator imported from elsewhere or defined in the file
|
|
87
|
+
exempts nothing, so its function is checked as normal. A decorator whose
|
|
88
|
+
name the file never binds still matches by name, as before. No contract
|
|
89
|
+
field changes.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
18
93
|
## [0.9.0] — 2026-11-17
|
|
19
94
|
|
|
20
95
|
A run names every file it checked, including the ones that passed, each with
|
|
@@ -1021,10 +1096,6 @@ recall.
|
|
|
1021
1096
|
|
|
1022
1097
|
- `serde_yaml` is pinned at its final `0.9` release and is unmaintained
|
|
1023
1098
|
upstream. `serde_norway` / `serde_yml` are drop-in replacements.
|
|
1024
|
-
- The `databricks` profile owns bare `@table`, `@view` and `@pandas_udf`, which
|
|
1025
|
-
are generic enough to collide with unrelated decorators.
|
|
1026
|
-
- KV003's `*catalog*` / `*bucket*` / `*warehouse*` are global rather than
|
|
1027
|
-
framework-scoped, and are the most likely source of first-run noise.
|
|
1028
1099
|
- dbt SQL models are not parsed; dbt coverage is Python models plus YAML
|
|
1029
1100
|
credentials.
|
|
1030
1101
|
- The contract fingerprint is truncated to 64 bits — sized for change
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: kv-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.11.0
|
|
4
4
|
Classifier: Environment :: Console
|
|
5
5
|
Classifier: Intended Audience :: Developers
|
|
6
6
|
Classifier: Programming Language :: Rust
|
|
@@ -85,15 +85,24 @@ FIXED applied 18 changes across 1 file
|
|
|
85
85
|
|
|
86
86
|
## Quickstart
|
|
87
87
|
|
|
88
|
-
**1. Install.**
|
|
88
|
+
**1. Install.** From PyPI, with pip or uv:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pip install kv-cli
|
|
92
|
+
uv tool install kv-cli
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Either one installs the prebuilt binary from a wheel, with no Rust toolchain needed. There are wheels for Linux x86-64 and ARM64 (glibc and musl), macOS Apple silicon and Intel, and Windows x86-64. On any other platform, pip builds from source, which needs Rust and a C compiler.
|
|
96
|
+
|
|
97
|
+
On macOS or Linux with Homebrew:
|
|
89
98
|
|
|
90
99
|
```bash
|
|
91
100
|
brew install kovallent/tap/kv-cli
|
|
92
101
|
```
|
|
93
102
|
|
|
94
|
-
It installs the prebuilt binary
|
|
103
|
+
It installs the prebuilt binary too, and `brew upgrade kv-cli` picks up new releases.
|
|
95
104
|
|
|
96
|
-
|
|
105
|
+
Or download your platform's archive from the [latest release](https://github.com/kovallent/kv-cli/releases/latest) and unpack it:
|
|
97
106
|
|
|
98
107
|
| Platform | Archive |
|
|
99
108
|
| --- | --- |
|
|
@@ -173,7 +182,7 @@ jobs:
|
|
|
173
182
|
runs-on: ubuntu-latest
|
|
174
183
|
steps:
|
|
175
184
|
- uses: actions/checkout@v4
|
|
176
|
-
- uses: kovallent/kv-cli@v0.
|
|
185
|
+
- uses: kovallent/kv-cli@v0.11.0
|
|
177
186
|
with:
|
|
178
187
|
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
179
188
|
```
|
|
@@ -195,7 +204,7 @@ jobs:
|
|
|
195
204
|
- uses: actions/checkout@v4
|
|
196
205
|
- name: Install kv-cli
|
|
197
206
|
env:
|
|
198
|
-
KV_VERSION: v0.
|
|
207
|
+
KV_VERSION: v0.11.0
|
|
199
208
|
TARGET: x86_64-unknown-linux-gnu
|
|
200
209
|
run: |
|
|
201
210
|
cd "$RUNNER_TEMP"
|
|
@@ -219,7 +228,7 @@ Exit codes are a stable interface, and each one is a problem for a different own
|
|
|
219
228
|
| **2** | Tool error, including "no files to audit" | Whoever operates the gate |
|
|
220
229
|
| **3** | Contract drift (`--expect-contract`) | Whoever owns the contract |
|
|
221
230
|
|
|
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.
|
|
231
|
+
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 `--format sarif`, or after a failing run, and it makes no network call.
|
|
223
232
|
|
|
224
233
|
### Stop a pull request from weakening the contract
|
|
225
234
|
|
|
@@ -250,14 +259,19 @@ With the Action, that is the `expect-contract` input; in the workflow without it
|
|
|
250
259
|
|
|
251
260
|
```yaml
|
|
252
261
|
repos:
|
|
253
|
-
- repo: https://github.com/kovallent/kv-cli
|
|
254
|
-
rev: v0.
|
|
262
|
+
- repo: https://github.com/kovallent/kv-cli-pre-commit
|
|
263
|
+
rev: v0.11.0
|
|
255
264
|
hooks:
|
|
256
265
|
- id: kv-cli # audits staged Python, notebooks and config files
|
|
257
266
|
- id: kv-cli-contract # validates .kovallent.yaml when it changes
|
|
267
|
+
- id: kv-cli-strict # manual stage: pre-commit run kv-cli-strict --hook-stage manual --all-files
|
|
258
268
|
```
|
|
259
269
|
|
|
260
|
-
|
|
270
|
+
[kv-cli-pre-commit](https://github.com/kovallent/kv-cli-pre-commit) declares the same hooks as `language: python` and pins `kv-cli` to the same version, which pip installs from the prebuilt wheels: no contributor needs a Rust toolchain, and nothing compiles.
|
|
271
|
+
|
|
272
|
+
`repo: https://github.com/kovallent/kv-cli` still works as a hook repository too, as `language: rust`: pre-commit builds kv-cli from source on first run, which needs Rust and a C compiler.
|
|
273
|
+
|
|
274
|
+
To use an installed binary instead:
|
|
261
275
|
|
|
262
276
|
```yaml
|
|
263
277
|
repos:
|
|
@@ -280,7 +294,7 @@ A hook is advisory: `--no-verify` skips it, and a fresh clone installs none. It
|
|
|
280
294
|
| Command | Purpose |
|
|
281
295
|
| --- | --- |
|
|
282
296
|
| `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`. |
|
|
297
|
+
| `kv-cli audit [PATHS]` | Scan for violations. `--strict`, `--format json` or `sarif`, `--config`, `--expect-contract`. |
|
|
284
298
|
| `kv-cli fix [PATHS]` | Apply the standard fixes, backing up each file to `.kvbak`. `--dry-run`, `--no-backup`. |
|
|
285
299
|
| `kv-cli explain [CODE]` | Print a rule's reference: what it catches, how to fix it, how to suppress it. |
|
|
286
300
|
| `kv-cli contract check` | Validate the contract without scanning code, listing every problem with its line. |
|
|
@@ -337,7 +351,7 @@ A signature the framework owns is exempt from `KV001`, because the framework cal
|
|
|
337
351
|
- **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
352
|
- [Configuration](docs/configuration.md): the contract file, how patterns match, editor validation, upgrading.
|
|
339
353
|
- [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.
|
|
354
|
+
- [CI with the GitHub Action](docs/ci.md): the Action's inputs, required status checks, protecting the workflow, uploading with OIDC, code scanning with SARIF.
|
|
341
355
|
- [Contract pinning](docs/contract-pinning.md): stopping a pull request from weakening the contract.
|
|
342
356
|
- [JSON payload](docs/json-payload.md): the `--format json` schema.
|
|
343
357
|
- [How it works](docs/how-it-works.md): the AST scanner, config scanners and what `fix` changes.
|
|
@@ -347,10 +361,10 @@ A signature the framework owns is exempt from `KV001`, because the framework cal
|
|
|
347
361
|
### Other ways to install
|
|
348
362
|
|
|
349
363
|
```bash
|
|
350
|
-
cargo install --git https://github.com/kovallent/kv-cli --tag v0.
|
|
364
|
+
cargo install --git https://github.com/kovallent/kv-cli --tag v0.11.0
|
|
351
365
|
```
|
|
352
366
|
|
|
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.
|
|
367
|
+
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.
|
|
354
368
|
|
|
355
369
|
---
|
|
356
370
|
|
|
@@ -70,15 +70,24 @@ FIXED applied 18 changes across 1 file
|
|
|
70
70
|
|
|
71
71
|
## Quickstart
|
|
72
72
|
|
|
73
|
-
**1. Install.**
|
|
73
|
+
**1. Install.** From PyPI, with pip or uv:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install kv-cli
|
|
77
|
+
uv tool install kv-cli
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Either one installs the prebuilt binary from a wheel, with no Rust toolchain needed. There are wheels for Linux x86-64 and ARM64 (glibc and musl), macOS Apple silicon and Intel, and Windows x86-64. On any other platform, pip builds from source, which needs Rust and a C compiler.
|
|
81
|
+
|
|
82
|
+
On macOS or Linux with Homebrew:
|
|
74
83
|
|
|
75
84
|
```bash
|
|
76
85
|
brew install kovallent/tap/kv-cli
|
|
77
86
|
```
|
|
78
87
|
|
|
79
|
-
It installs the prebuilt binary
|
|
88
|
+
It installs the prebuilt binary too, and `brew upgrade kv-cli` picks up new releases.
|
|
80
89
|
|
|
81
|
-
|
|
90
|
+
Or download your platform's archive from the [latest release](https://github.com/kovallent/kv-cli/releases/latest) and unpack it:
|
|
82
91
|
|
|
83
92
|
| Platform | Archive |
|
|
84
93
|
| --- | --- |
|
|
@@ -158,7 +167,7 @@ jobs:
|
|
|
158
167
|
runs-on: ubuntu-latest
|
|
159
168
|
steps:
|
|
160
169
|
- uses: actions/checkout@v4
|
|
161
|
-
- uses: kovallent/kv-cli@v0.
|
|
170
|
+
- uses: kovallent/kv-cli@v0.11.0
|
|
162
171
|
with:
|
|
163
172
|
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
164
173
|
```
|
|
@@ -180,7 +189,7 @@ jobs:
|
|
|
180
189
|
- uses: actions/checkout@v4
|
|
181
190
|
- name: Install kv-cli
|
|
182
191
|
env:
|
|
183
|
-
KV_VERSION: v0.
|
|
192
|
+
KV_VERSION: v0.11.0
|
|
184
193
|
TARGET: x86_64-unknown-linux-gnu
|
|
185
194
|
run: |
|
|
186
195
|
cd "$RUNNER_TEMP"
|
|
@@ -204,7 +213,7 @@ Exit codes are a stable interface, and each one is a problem for a different own
|
|
|
204
213
|
| **2** | Tool error, including "no files to audit" | Whoever operates the gate |
|
|
205
214
|
| **3** | Contract drift (`--expect-contract`) | Whoever owns the contract |
|
|
206
215
|
|
|
207
|
-
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.
|
|
216
|
+
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 `--format sarif`, or after a failing run, and it makes no network call.
|
|
208
217
|
|
|
209
218
|
### Stop a pull request from weakening the contract
|
|
210
219
|
|
|
@@ -235,14 +244,19 @@ With the Action, that is the `expect-contract` input; in the workflow without it
|
|
|
235
244
|
|
|
236
245
|
```yaml
|
|
237
246
|
repos:
|
|
238
|
-
- repo: https://github.com/kovallent/kv-cli
|
|
239
|
-
rev: v0.
|
|
247
|
+
- repo: https://github.com/kovallent/kv-cli-pre-commit
|
|
248
|
+
rev: v0.11.0
|
|
240
249
|
hooks:
|
|
241
250
|
- id: kv-cli # audits staged Python, notebooks and config files
|
|
242
251
|
- id: kv-cli-contract # validates .kovallent.yaml when it changes
|
|
252
|
+
- id: kv-cli-strict # manual stage: pre-commit run kv-cli-strict --hook-stage manual --all-files
|
|
243
253
|
```
|
|
244
254
|
|
|
245
|
-
|
|
255
|
+
[kv-cli-pre-commit](https://github.com/kovallent/kv-cli-pre-commit) declares the same hooks as `language: python` and pins `kv-cli` to the same version, which pip installs from the prebuilt wheels: no contributor needs a Rust toolchain, and nothing compiles.
|
|
256
|
+
|
|
257
|
+
`repo: https://github.com/kovallent/kv-cli` still works as a hook repository too, as `language: rust`: pre-commit builds kv-cli from source on first run, which needs Rust and a C compiler.
|
|
258
|
+
|
|
259
|
+
To use an installed binary instead:
|
|
246
260
|
|
|
247
261
|
```yaml
|
|
248
262
|
repos:
|
|
@@ -265,7 +279,7 @@ A hook is advisory: `--no-verify` skips it, and a fresh clone installs none. It
|
|
|
265
279
|
| Command | Purpose |
|
|
266
280
|
| --- | --- |
|
|
267
281
|
| `kv-cli init` | Write a commented `.kovallent.yaml` and report what it enables. `--force` overwrites. |
|
|
268
|
-
| `kv-cli audit [PATHS]` | Scan for violations. `--strict`, `--format json`, `--config`, `--expect-contract`. |
|
|
282
|
+
| `kv-cli audit [PATHS]` | Scan for violations. `--strict`, `--format json` or `sarif`, `--config`, `--expect-contract`. |
|
|
269
283
|
| `kv-cli fix [PATHS]` | Apply the standard fixes, backing up each file to `.kvbak`. `--dry-run`, `--no-backup`. |
|
|
270
284
|
| `kv-cli explain [CODE]` | Print a rule's reference: what it catches, how to fix it, how to suppress it. |
|
|
271
285
|
| `kv-cli contract check` | Validate the contract without scanning code, listing every problem with its line. |
|
|
@@ -322,7 +336,7 @@ A signature the framework owns is exempt from `KV001`, because the framework cal
|
|
|
322
336
|
- **Rules:** [KV001](docs/rules/KV001.md), [KV002](docs/rules/KV002.md), [KV003](docs/rules/KV003.md), also available offline as `kv-cli explain <code>`.
|
|
323
337
|
- [Configuration](docs/configuration.md): the contract file, how patterns match, editor validation, upgrading.
|
|
324
338
|
- [Frameworks](docs/frameworks.md): profiles, owned signatures, governed decorators.
|
|
325
|
-
- [CI with the GitHub Action](docs/ci.md): the Action's inputs, required status checks, protecting the workflow, uploading with OIDC.
|
|
339
|
+
- [CI with the GitHub Action](docs/ci.md): the Action's inputs, required status checks, protecting the workflow, uploading with OIDC, code scanning with SARIF.
|
|
326
340
|
- [Contract pinning](docs/contract-pinning.md): stopping a pull request from weakening the contract.
|
|
327
341
|
- [JSON payload](docs/json-payload.md): the `--format json` schema.
|
|
328
342
|
- [How it works](docs/how-it-works.md): the AST scanner, config scanners and what `fix` changes.
|
|
@@ -332,10 +346,10 @@ A signature the framework owns is exempt from `KV001`, because the framework cal
|
|
|
332
346
|
### Other ways to install
|
|
333
347
|
|
|
334
348
|
```bash
|
|
335
|
-
cargo install --git https://github.com/kovallent/kv-cli --tag v0.
|
|
349
|
+
cargo install --git https://github.com/kovallent/kv-cli --tag v0.11.0
|
|
336
350
|
```
|
|
337
351
|
|
|
338
|
-
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.
|
|
352
|
+
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.
|
|
339
353
|
|
|
340
354
|
---
|
|
341
355
|
|
|
@@ -30,7 +30,7 @@ jobs:
|
|
|
30
30
|
steps:
|
|
31
31
|
- uses: actions/checkout@v4
|
|
32
32
|
|
|
33
|
-
- uses: kovallent/kv-cli@v0.
|
|
33
|
+
- uses: kovallent/kv-cli@v0.11.0
|
|
34
34
|
with:
|
|
35
35
|
# An organization variable: pull-request authors cannot edit it.
|
|
36
36
|
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
@@ -44,12 +44,12 @@ Set `KOVALLENT_CONTRACT_SHA` once, as an **organization** variable, to your cont
|
|
|
44
44
|
|
|
45
45
|
### Pinning the Action
|
|
46
46
|
|
|
47
|
-
`uses: kovallent/kv-cli@v0.
|
|
47
|
+
`uses: kovallent/kv-cli@v0.11.0` runs the `action.yml` from that tag and, by default, the kv-cli binary from the same release. To pin the Action by commit SHA instead, set `version`, because a SHA names no release:
|
|
48
48
|
|
|
49
49
|
```yaml
|
|
50
|
-
- uses: kovallent/kv-cli@<full commit SHA> # v0.
|
|
50
|
+
- uses: kovallent/kv-cli@<full commit SHA> # v0.11.0
|
|
51
51
|
with:
|
|
52
|
-
version: v0.
|
|
52
|
+
version: v0.11.0
|
|
53
53
|
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
54
54
|
```
|
|
55
55
|
|
|
@@ -117,6 +117,59 @@ When `upload-url` is set, the Action requests a GitHub Actions OIDC token with t
|
|
|
117
117
|
- **HTTPS only.** An `upload-url` that is not `https://` is refused with a warning, so the token is never sent in the clear.
|
|
118
118
|
- **Best-effort.** A failed upload, an error response or a missing token prints a warning and never changes the job's result. The upload is attempted once, because retrying a POST could deliver the report twice.
|
|
119
119
|
|
|
120
|
+
## Code scanning with SARIF
|
|
121
|
+
|
|
122
|
+
`kv-cli audit --format sarif` writes the same run as the JSON report, as one SARIF 2.1.0 log, which GitHub code scanning can show as alerts on the pull request and in the repository's Security tab. **This is in addition to the exit-code gate, never in place of it.** A code-scanning alert does not block a merge unless a ruleset with code scanning merge protection says so; the `Kovallent gate` required check is what blocks it.
|
|
123
|
+
|
|
124
|
+
Add two steps after the gate, and `security-events: write` to the permissions:
|
|
125
|
+
|
|
126
|
+
```yaml
|
|
127
|
+
permissions:
|
|
128
|
+
contents: read
|
|
129
|
+
# Needed by upload-sarif.
|
|
130
|
+
security-events: write
|
|
131
|
+
# Also needed in a private repository.
|
|
132
|
+
# actions: read
|
|
133
|
+
|
|
134
|
+
jobs:
|
|
135
|
+
gate:
|
|
136
|
+
name: Kovallent gate
|
|
137
|
+
runs-on: ubuntu-latest
|
|
138
|
+
steps:
|
|
139
|
+
- uses: actions/checkout@v4
|
|
140
|
+
|
|
141
|
+
- uses: kovallent/kv-cli@v0.11.0
|
|
142
|
+
with:
|
|
143
|
+
expect-contract: ${{ vars.KOVALLENT_CONTRACT_SHA }}
|
|
144
|
+
|
|
145
|
+
# Runs whether or not the gate passed. Its own exit code is ignored:
|
|
146
|
+
# the step above already decided the job's result.
|
|
147
|
+
- name: kv-cli SARIF
|
|
148
|
+
if: always()
|
|
149
|
+
run: pipx run --spec kv-cli==0.11.0 kv-cli audit --format sarif > kv-cli.sarif || true
|
|
150
|
+
|
|
151
|
+
- name: Upload to code scanning
|
|
152
|
+
if: always()
|
|
153
|
+
uses: github/codeql-action/upload-sarif@v4
|
|
154
|
+
with:
|
|
155
|
+
sarif_file: kv-cli.sarif
|
|
156
|
+
category: kv-cli
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`pipx run` installs kv-cli's prebuilt wheel from PyPI into a throwaway environment; keep its version the same as the Action's.
|
|
160
|
+
|
|
161
|
+
What the log holds:
|
|
162
|
+
|
|
163
|
+
- **One result per finding**, with the rule (`KV001`, `KV002`, `KV003`), the level from the finding's own severity (`--strict` does not change it, as in the JSON report), the message, and the file and line. A KV002 result carries the same redacted detail as the JSON report, never the value.
|
|
164
|
+
- **`partialFingerprints`** holds the finding's fingerprint under `kovallent/v1`, equal to `fingerprint` in the JSON report: stable across commits, since it excludes the line number. GitHub does not use it: it tracks alerts with its own `primaryLocationLineHash`, which `upload-sarif` computes from the source. Other SARIF consumers can.
|
|
165
|
+
- **The rules** are described with the same text as `kv-cli explain`.
|
|
166
|
+
- **Files that were not fully analysed** (a syntax error, an unreadable file) are tool notifications, so a partial parse is never silent.
|
|
167
|
+
- **The scope block and the contract fingerprint** are run properties. Code scanning does not show them, but they travel with the results.
|
|
168
|
+
|
|
169
|
+
Locations use the same paths as findings: relative to the folder holding `.kovallent.yaml`. Code scanning reads them relative to the repository root, so alerts line up when the contract is at the root, as it usually is.
|
|
170
|
+
|
|
171
|
+
Code scanning is available for public repositories, and for organization-owned private repositories with GitHub Code Security.
|
|
172
|
+
|
|
120
173
|
## Runners
|
|
121
174
|
|
|
122
175
|
Release assets exist for Linux x64 and arm64 (glibc), macOS x64 and arm64, and Windows x64. The Action runs in `bash` and uses `curl`, `tar`, and `sha256sum` or `shasum`. Annotations and the job summary use `jq`. GitHub-hosted runners have all of these; on a self-hosted runner without `jq`, the Action warns and skips those two steps, and the exit code still gates.
|
|
@@ -64,6 +64,11 @@ infrastructure:
|
|
|
64
64
|
|
|
65
65
|
## Upgrading
|
|
66
66
|
|
|
67
|
+
**Upgrading to 0.10.0.** Fingerprints do not change, but two behaviours do, and both can change your findings.
|
|
68
|
+
|
|
69
|
+
- **KV003's name rule waits for a framework.** `infrastructure.key_patterns` (by default `*warehouse*`, `*catalog*`, `*cluster_id*`, `*workspace_url*`, `*bucket*`, plus any you added) now applies only in Python files where a framework profile is detected. In other Python files, a `warehouse = "PROD_WH"` is no longer reported. Value patterns, such as `s3://` URIs, still apply everywhere, and so do each profile's own key rules where the profile is detected. To keep 0.9.0's behaviour, set `infrastructure.global_key_patterns_require_framework: false`. Unlike the default, that value is part of the contract, so it changes the fingerprint: re-pin `--expect-contract` if you set it.
|
|
70
|
+
- **Framework decorators are resolved through imports.** A decorator a profile owns or governs, such as `@table`, `@view`, `@udf`, `@pandas_udf` or Airflow's `@task`, now counts only if the file imports it from that framework (`from dlt import table`, `import pyspark.sql.functions as F` then `@F.pandas_udf`). A decorator imported from elsewhere or defined in the file, such as Flask's `@app.view` or a local `def table(f): ...`, no longer exempts its function, so the function is checked against the contract and may now get KV001. A decorator whose name is bound nowhere in the file is still matched by name, as before.
|
|
71
|
+
|
|
67
72
|
**Upgrading to 0.7.1.** Fingerprints do not change. A credential assigned on a line after a syntax error, such as `password = "s3cr3t"`, is now reported as KV002; its detail says it was read from a line that does not parse. Load the value from the environment as for any KV002. Fixing only the syntax error does not clear it, because the file then parses and the credential is found the usual way.
|
|
68
73
|
|
|
69
74
|
**Upgrading to 0.7.0.** Fingerprints do not change. A literal inside a Jinja template is now reported: `{{ env_var('DBT_PASSWORD', 's3cr3t') }}` falls back to a hardcoded password, so it is KV002. Remove the fallback, or use a placeholder such as `'changeme'`.
|
|
@@ -36,4 +36,6 @@ Push a tag `vX.Y.Z` matching `Cargo.toml`. The release workflow builds the five
|
|
|
36
36
|
|
|
37
37
|
The same tag runs `.github/workflows/wheels.yml`, which builds seven wheels (Linux x86-64 and ARM64, each manylinux and musllinux; macOS arm64 and x86-64; Windows x86-64) and an sdist with maturin, smoke-tests three of them, and publishes all of them to PyPI. It is separate from the release workflow, so a PyPI outage cannot fail a GitHub release, and it fails before publishing if the tag does not match `Cargo.toml`. `pyproject.toml` declares no version: maturin reads it from `Cargo.toml`. Publishing uses PyPI's trusted publishing, so no PyPI token is stored. Before the first publish, add a trusted publisher on [pypi.org](https://pypi.org/manage/account/publishing/) and on [test.pypi.org](https://test.pypi.org/manage/account/publishing/) (a pending publisher, while the project does not exist yet): owner `kovallent`, repository `kv-cli`, workflow `wheels.yml`, environment `pypi`. Create the `pypi` environment in the repository settings too. A manual run (**Actions → Wheels → Run workflow**) publishes to TestPyPI by default; PyPI only from a tag.
|
|
38
38
|
|
|
39
|
+
**After each PyPI publish, bump and tag the pre-commit mirror to the same version.** In [kovallent/kv-cli-pre-commit](https://github.com/kovallent/kv-cli-pre-commit), set `version`, the `kv-cli==` pin in `pyproject.toml` and the README's `rev:` to `X.Y.Z`, then push the tag `vX.Y.Z`. Its CI fails if the four disagree. The README's pre-commit snippet here names that mirror at `rev: vX.Y.Z`, so the mirror's tag has to exist before the release is announced.
|
|
40
|
+
|
|
39
41
|
The tap update needs a repository secret, `HOMEBREW_TAP_TOKEN`: a fine-grained personal access token limited to `kovallent/homebrew-tap`, with **Contents: Read and write**. Without it, the release still publishes, but the `homebrew` job fails and brew users stay on the previous version. Fine-grained tokens expire, so renew it before the expiry date you chose.
|
|
@@ -13,8 +13,12 @@ Run `kv-cli frameworks` for the live list. Each profile is scoped to files that
|
|
|
13
13
|
|
|
14
14
|
**Signatures a framework owns are exempt from `KV001`.** A `@dlt.table` function takes no arguments because DLT calls it; `def model(dbt, session)` is fixed by dbt. Injecting `target_environment` there would break the pipeline, so the exemption overrides the user's own name patterns — a function called `daily_sales_job` matches `*_job`, but under `@dlt.table` it is left alone. Airflow's `@dag` is owned for the same reason: its parameters become DAG params shown in the UI and in `{{ params.* }}`, so adding them silently changes the DAG.
|
|
15
15
|
|
|
16
|
+
**An owned or governed decorator must come from the framework.** `@table`, `@view`, `@udf`, `@pandas_udf` and `@task` are common names, so a decorator counts only when the file imports it from the framework: `from dlt import table`, or `import pyspark.sql.functions as F` for `@F.pandas_udf`. A decorator imported from anywhere else, or defined in the file, such as Flask's `@app.view` or a local `def table(f): ...`, exempts nothing: its function is checked like any other, and the decorator does not make the file count as a framework file. A decorator whose name the file never binds still matches by name, since such code cannot run unless a star import supplies it.
|
|
17
|
+
|
|
16
18
|
User `exempt_name_patterns` still win over framework rules, so `@task def _internal_step()` stays out of scope.
|
|
17
19
|
|
|
20
|
+
The contract's own KV003 name rule, `infrastructure.key_patterns` (`*warehouse*`, `*bucket*` and the rest), waits for a framework too: by default it applies only in files where a profile is detected. See [KV003](rules/KV003.md).
|
|
21
|
+
|
|
18
22
|
A profile can also work the other way: `governed_decorators` puts functions **into** `KV001` scope. Airflow's `@task` is the one case — TaskFlow tasks are called from your own DAG body, so the contract parameter can be threaded through at the call site. Declaring it on the profile means the behaviour no longer depends on your contract happening to list a decorator named `task`.
|
|
19
23
|
|
|
20
24
|
Governed decorators can be report-only (`governed_auto_fix: false`), which Airflow's `@task` is. `audit` flags a missing parameter, but `fix` refuses to insert it and prints a `manual:` item instead — `extract_orders("s3://...")` would not pass the new argument, so an inserted default would read `"dev"` in every environment while looking correct. **An Airflow-heavy repository therefore cannot reach a clean audit from `fix` alone; you have to thread the parameter through the call site yourself.** This is scoped to the framework: ordinary functions in the same DAG file are still fixed normally.
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
`schema/findings.v1.json` is generated from the Rust types by `kv-cli schema`; a test asserts the committed document matches and that a real run validates against it, so the two cannot drift.
|
|
4
4
|
|
|
5
|
+
For code-scanning tools, `kv-cli audit --format sarif` writes the same run as a SARIF 2.1.0 log: each finding as a result, with its fingerprint under `partialFingerprints.kovallent/v1`, and the scope block and contract fingerprint as run properties. See [Code scanning with SARIF](ci.md#code-scanning-with-sarif).
|
|
6
|
+
|
|
5
7
|
* **Version and identity.** `run` carries `schema_version` (bumped only on a breaking payload change, independent of `tool_version`), run identity (`repo`, `commit`, `branch`, `timestamp`), contract provenance, and a scope block. Identity is never guessed: `repo` and `commit` come from the CI environment (`GITHUB_REPOSITORY`, `CI_COMMIT_SHA`, …) or from `--repo` / `--commit` / `--branch`, and `identity_source` records which — `"flag"`, `"env:GITHUB_SHA"`, or absent.
|
|
6
8
|
* **Severity reporting.** Severity is reported as emitted. `errors` and `warnings` count intrinsic severities regardless of `--strict`; the flag is emitted so a consumer can apply the policy itself. Otherwise a strict run reports every finding as an error and the payload cannot say how many were warnings.
|
|
7
9
|
* **Completeness.** No file can vanish from the payload. Every file `kv-cli` resolves for scanning is either represented in `findings`/`files_scanned` or named in `run.skipped[]` as `{path, reason, severity, detail}`, reason being `"syntax_error"` or `"unreadable"`. A syntax error is a warning — matching how `KV003` was introduced, it does not fail CI by default and is promoted under `--strict`. An unreadable file is always an error, since there is no lenient reading of "the tool could not check this file."
|
|
@@ -11,6 +11,8 @@ code works in that one environment and either breaks in the others or,
|
|
|
11
11
|
worse, writes to the wrong one.
|
|
12
12
|
|
|
13
13
|
```python
|
|
14
|
+
from snowflake.snowpark import Session
|
|
15
|
+
|
|
14
16
|
WAREHOUSE = "ANALYTICS_PROD_WH" # KV003: name rule
|
|
15
17
|
df.write.parquet("s3://acme-prod-orders/") # KV003: object-store URI
|
|
16
18
|
```
|
|
@@ -18,6 +20,14 @@ df.write.parquet("s3://acme-prod-orders/") # KV003: object-store URI
|
|
|
18
20
|
Python files only. Config files are where environment-specific values
|
|
19
21
|
belong, so KV003 never applies to them.
|
|
20
22
|
|
|
23
|
+
The name rule, `infrastructure.key_patterns`, applies only in files that use
|
|
24
|
+
a data framework, that is, where a framework profile is detected. In a file
|
|
25
|
+
that imports none, a `warehouse` or `bucket` is as likely to be a CLI option
|
|
26
|
+
or a test fixture as a deployment target. Value patterns, such as the
|
|
27
|
+
object-store URI above, apply in every Python file. To apply the name rule in
|
|
28
|
+
every Python file, as before 0.10.0, set
|
|
29
|
+
`infrastructure.global_key_patterns_require_framework: false`.
|
|
30
|
+
|
|
21
31
|
Framework profiles add their own identifiers in files that use the
|
|
22
32
|
framework. For example, Snowpark adds `account` and `role`, and Airflow adds
|
|
23
33
|
`conn_id`, `pool` and `queue`. `kv-cli frameworks` lists them all.
|
|
@@ -54,6 +64,8 @@ LEGACY_BUCKET = "s3://acme-archive/" # kovallent:allow-infra
|
|
|
54
64
|
## Contract keys
|
|
55
65
|
|
|
56
66
|
`infrastructure.enabled`, `infrastructure.severity`,
|
|
57
|
-
`infrastructure.key_patterns`,
|
|
67
|
+
`infrastructure.key_patterns`,
|
|
68
|
+
`infrastructure.global_key_patterns_require_framework`,
|
|
69
|
+
`infrastructure.value_patterns`,
|
|
58
70
|
`infrastructure.allow_values`, `infrastructure.exempt_key_patterns`,
|
|
59
71
|
`infrastructure.ignore_marker`
|
|
@@ -141,6 +141,10 @@
|
|
|
141
141
|
},
|
|
142
142
|
"type": "array"
|
|
143
143
|
},
|
|
144
|
+
"global_key_patterns_require_framework": {
|
|
145
|
+
"description": "Apply `key_patterns` only in files where a framework profile applies.\nIn a file that uses no data framework, `warehouse` or `bucket` is as\nlikely to be a CLI option or a test fixture as a deployment target, so\nthe default skips the key rule there. `value_patterns` and each\nprofile's own key rules apply as before. Set to `false` for 0.9.0's\nbehaviour: `key_patterns` in every Python file.",
|
|
146
|
+
"type": "boolean"
|
|
147
|
+
},
|
|
144
148
|
"ignore_marker": {
|
|
145
149
|
"default": "kovallent:allow-infra",
|
|
146
150
|
"type": "string"
|