# Coverage and CI gates: coverage, impacted-tests, doc-drift, security check, health check

Flags for ingesting coverage, gating a change on patch coverage, selecting the tests a change needs, and the doc-drift, security and health gates.

How to wire these into a pipeline is on [Gates in CI](https://docs.repowise.dev/ci). This page
lists every flag. To combine these gates with rules about components,
owners and tests in one policy, see
[`repowise check`](https://docs.repowise.dev/cli/changes#repowise-check).

## `repowise coverage add`

Ingest coverage reports into the index. With no path it discovers
`coverage/lcov.info`, `coverage.xml`, `coverage.out`, JaCoCo XML, a
repo-root `.coverage` and similar. `init` and `update` also ingest what they
discover.

```bash
repowise coverage add [PATHS...] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `PATHS` | string |  | Report paths or quoted globs ('artifacts/**/lcov.info'). PATH=PREFIX prepends PREFIX to the paths inside that report. A path that matches no file is an error. |
| `--format` | string |  | Force a parser: lcov, cobertura, clover, repowise-json, go-coverprofile, jacoco |
| `--strict` | boolean | `false` | Also exit non-zero when some report files did not map to the repo tree. |
| `--path` | string |  | Repo path (defaults to cwd / workspace primary). |
| `--verbose / -v` | boolean | `false` | Show debug logs. |

```bash
repowise coverage add                          # discover reports
repowise coverage add .coverage                # plus the per-test map (pytest --cov=<package> --cov-context=test)
repowise coverage add web.lcov api.lcov        # merged, a line any report ran counts as run
repowise coverage add web/coverage/lcov.info=web
```

It exits non-zero when nothing was stored, so `coverage add ... || exit 1`
tells a real ingest from a no-op. Each ingest is kept as history (the newest
50), which draws the coverage trend in the dashboard and in
[`get_health`](https://docs.repowise.dev/mcp/get-health).

## `repowise coverage status`

Show the coverage currently ingested. `--path`, `--format table|json`.

## `repowise coverage check`

Gate a change on its patch coverage: the share of the changed executable
lines the tests ran. Needs git and a report. No index.

```bash
repowise coverage check [REVSPEC] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `REVSPEC` | string |  | origin/main...HEAD, base..head or one commit. Default: the CI pull request's target, else the remote's default branch. |
| `--report` | string |  | Report path or glob, repeatable, PATH=PREFIX allowed. Default: coverage.paths, else discovery. |
| `--report-format` | string |  | Force a parser: lcov, cobertura, clover, repowise-json, go-coverprofile, jacoco |
| `--fail-under` | number |  | Exit 1 below this patch coverage percent. Default: coverage.fail_under. Unset reports without gating. |
| `--min-coverable-lines` | number |  | A change with fewer changed executable lines is reported but never fails. Default: coverage.min_coverable_lines. |
| `--fail-under-risky` | number |  | Gate the risky files alone (hotspots or bug magnets from the index; on git alone, the top quartile by bug-fix history). Default: coverage.fail_under_risky. |
| `--fail-under-branches` | number |  | Gate the share of branches taken on changed lines. Reported beside patch coverage, never blended in. Default: coverage.fail_under_branches. |
| `--base-report` | string |  | Report measured at the change's base. Adds project coverage at base and head, and files whose coverage changed outside the change. |
| `--max-drop` | number |  | Exit 1 when project coverage falls more than this many points from the base. Default: coverage.max_drop. |
| `--path` | string |  | A path inside the repository. Config is read at the repo root. |
| `--format` | string | `table` | table, json, markdown, github |

```bash
repowise coverage check origin/main...HEAD --report coverage/lcov.info --fail-under 80
repowise coverage check --report 'artifacts/**/lcov.info' --min-coverable-lines 5
repowise coverage check --report lcov.info --base-report base/lcov.info --max-drop 0.5
```

Rows list the riskiest changed files first. With an index, each uncovered
range also names up to three test files to extend. Path-scoped gates in
`coverage.gates` are judged too; see
[Configuration](https://docs.repowise.dev/installation/configuration#coverage-and-test-selection).

## `repowise coverage suggest-gates`

Propose path-scoped `coverage.gates` from CODEOWNERS, top-level packages
and, when indexed, graph communities. Writes nothing: paste what you keep
under `coverage:` and give each gate a `fail_under`.

```bash
repowise coverage suggest-gates                  # yaml block to paste
repowise coverage suggest-gates --format json
```

## `repowise impacted-tests`

Print the tests a change needs. With a per-test coverage map it matches
changed lines; without one it follows the import and call graph, and lists
those tests apart as not coverage-backed.

```bash
repowise impacted-tests [REVSPEC] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `REVSPEC` | string |  | A range or commit. Default: the staged changes locally, the pull request's change in CI. |
| `--staged` | boolean | `false` | Diff the staged changes (git diff --cached). |
| `--format` | string | `table` | table, json, list (test ids, one per line), args (one line of runner arguments, or :all) |
| `--runner` | string | `auto` | Who --format args is for: auto, pytest, go, jest, files |
| `--explain` | string |  | A test file or node id: say why it was or was not selected (the changed file, the evidence and the import route, or the rule that runs it) and its place in the run order. Added to --format json as explain |
| `--prioritize` | boolean | `false` | With --format args, list or json: the whole suite, the selected tests first in run order, then every other test. Skips nothing |
| `--path` | string |  | Repo path (defaults to cwd / workspace primary). |

```bash
repowise impacted-tests main...HEAD
repowise impacted-tests main...HEAD --format args --runner pytest
repowise impacted-tests main...HEAD --explain tests/unit/test_api.py
repowise impacted-tests main...HEAD --format args --prioritize
```

`--format args` prints `:all` whenever the selection is not certain, with
the reasons on stderr. Branch on that, never on an empty line. The rules and
the `tests.*` config keys are on [Gates in CI](https://docs.repowise.dev/ci#run-only-the-tests-a-change-needs).

## `repowise doc-drift`

Show [documentation drift](https://docs.repowise.dev/intelligence/doc-drift): references in
your markdown that the tree no longer supports. Without `--check` it reads
the findings the index stored. With `--check` it reads the working tree and
needs no index.

```bash
repowise doc-drift [PATH] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--kind` | string |  | Only this reference class, repeatable: path, link, anchor, command, symbol |
| `--document` | string |  | Only findings in this document (repo-relative). Repeatable. |
| `--min-confidence` | number |  | Hide findings below this confidence (0 to 1). |
| `--check` | boolean | `false` | Gate mode: read the working tree without an index and exit 1 when the gate fails. With --kind symbol it also checks symbols, which needs an index. |
| `--fail-on-confidence` | number | `0.7` | With --check, fail on findings at or above this confidence. |
| `--baseline` | string |  | With --check, accept findings recorded in this file; only new ones fail. |
| `--write-baseline` | string |  | With --check, record the current findings to this file and exit 0. |
| `--fail-on-baseline-growth` | boolean | `false` | With --baseline, exit 1 when the file lists a finding the same file at the change's base does not (the --since base, else the CI target branch). A baseline the base lacks is new and passes. |
| `--since` | string |  | With --check, gate only drift this change is answerable for. A ref means REF...HEAD plus uncommitted changes; auto reads the target branch from CI. |
| `--format` | string | `table` | table, json, markdown, github, sarif, gitlab |
| `--repo` | string |  | In workspace mode, target one repo. |
| `--no-workspace` | boolean | `false` | Force single-repo mode. |

```bash
repowise doc-drift                              # everything the index stored
repowise doc-drift --kind anchor                # renamed-heading links only
repowise doc-drift --check --since auto --format github
```

## `repowise security check`

Gate a change on the [security findings](https://docs.repowise.dev/intelligence/security-signals)
it adds. Scans the files the change touched and keeps findings on changed
lines. Secret kinds are also checked in every commit of the change, so a key
added and then deleted inside it still fails. Needs git only.

```bash
repowise security check [REVSPEC] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `REVSPEC` | string |  | origin/main...HEAD, base..head or one commit. Default: the CI pull request's target, else the remote's default branch. |
| `--fail-on` | string | `high` | Exit 1 on a finding of this severity or above: high, med, low |
| `--staged` | boolean | `false` | Check what the next commit records. For a pre-commit hook; takes no REVSPEC. |
| `--baseline` | string |  | Accept findings recorded in this file; only new ones fail. |
| `--write-baseline` | string |  | Add this change's findings to this file and exit 0. |
| `--fail-on-baseline-growth` | boolean | `false` | Exit 1 when --baseline lists a finding the same file at the change's base does not, so a re-saved baseline cannot hide new findings. A baseline the base lacks is new and passes. |
| `--path` | string |  | A path inside the repository. |
| `--format` | string | `table` | table, json, markdown, github, sarif, gitlab |

```bash
repowise security check origin/main...HEAD
repowise security check --staged
repowise security check --format sarif > security.sarif
```

A `repowise-security-ignore` comment on a finding's line silences it
(`repowise-security-ignore: kind, kind` silences only those kinds). It is
still counted and listed. To run the check before every commit, use
[`repowise hook install --security`](https://docs.repowise.dev/cli/hook#repowise-hook-install).

## `repowise health check`

Gate a change on the [code-health findings](https://docs.repowise.dev/intelligence/code-health)
it introduces. Needs git only: no index, no database, no API key. It analyses
the changed files at the change's base and head and compares their findings
by file, marker and symbol, never by line. Only code-shape findings
(complexity, nesting, size, duplication, error handling) decide; git history,
coverage and file scores never do.

```bash
repowise health check [REVSPEC] [OPTIONS]
```

| Finding | Default | With `--fail-on worsened` |
|---------|---------|---------------------------|
| Introduced on lines the change wrote, at `--fail-at` or above | fails | fails |
| Made worse by the change, at `--fail-at` or above | warns | fails |
| Either of those below `--fail-at`, or in a test file | warns | warns |
| Moved or renamed with its code, away from the changed lines, or not code shape | context only | context only |

| Name | Type | Default | Description |
|---|---|---|---|
| `REVSPEC` | string |  | origin/main...HEAD, base..head or one commit. Default: the CI pull request's target, else the remote's default branch. |
| `--fail-on` | string | `introduced` | introduced, or worsened to also fail on findings the change made worse |
| `--fail-at` | string | `high` | Lowest severity that can fail: medium, high, critical. Findings below it warn |
| `--diff-risk` | string | `warn` | Level of the diff-risk rules: warn, error or off. LEVEL sets every rule, RULE=LEVEL one; repeatable |
| `--path` | string |  | A path inside the repository (defaults to cwd). |
| `--format` | string | `table` | table, json, markdown, github, sarif, gitlab |

```bash
repowise health check origin/main...HEAD
repowise health check --fail-on worsened --fail-at medium
repowise health check --diff-risk error --diff-risk test-only-branch=off
repowise health check --format sarif > health.sarif
repowise health check --format gitlab > gl-code-quality-health.json
```

Three diff-risk rules read the changed text in any supported language:

| Rule | Flags |
|------|-------|
| `added-suppression` | A new lint, type-check, coverage or repowise suppression comment or attribute, or a marker newly disabled in `.repowise/health-rules.json` |
| `weakened-tests` | A new unconditional skip or focus marker, fewer test cases or assertions, a loosened coverage threshold |
| `test-only-branch` | A new test-environment check in production code |

A marker that moved to another file with its code does not count. Rules in
`.repowise/health-rules.json` are read as the change's base has them, so a
change cannot loosen its own gate.

Exit codes: `0` passed (warnings included), `1` gate failed, `2` could not
evaluate (not a git repository, unknown revision, no merge-base in a shallow
clone, an invalid `health-rules.json` at the base, more than 300 changed code
files, or no changed code file could be read).

With `--format github`, each failing finding's annotation ends in a one-line
fix hint, and a failing run names the `repowise health check` command that
reproduces it locally, in the job log and the summary. To run the same check
before an agent commits or pushes, see
[`repowise hook health-gate`](https://docs.repowise.dev/cli/hook#repowise-hook-health-gate-installuninstallstatus).

## `repowise ci-summary`

Combine the gates a CI job ran into one verdict table, appended to the GitHub
job summary, and print the combined verdict (`pass`, `warn` or `fail`). Each
gate run with `--format github` while `REPOWISE_GATE_SUMMARY_DIR` names a
directory leaves its result there; a gate that left nothing reads as could not
evaluate.

```bash
repowise ci-summary SUMMARY_DIR --gate NAME=EXIT_CODE... [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--gate` | string |  | Required. A gate that ran and its exit code, in the order to list them. Repeatable; required. |
| `--comment-file` | string |  | Write the pull-request comment, with each gate's findings, here. |
| `--previous` | string |  | The comment this run replaces; findings it listed that are gone count as resolved. |
| `--comment-key` | string |  | Tells this comment apart from another run's on the same pull request. |

The [GitHub Action](https://docs.repowise.dev/ci#github-actions) runs it for you.