CI integration

First: fetch-depth: 0

Forget this and everything breaks

dowsing computes change frequency from git history. CI checkouts are shallow by default, so you have to ask for the full history explicitly. dowsing warns when it detects a shallow clone, but the numbers it prints are not trustworthy.

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

dowsing reads only your git history and your TypeScript sources. It does not need the repository's node_modules, so you can skip the install step entirely.

Quality gate

dowsing check --min-file-health 3

Exits with code 1 if anything is in violation.

By default it checks nothing

Only the thresholds you name explicitly are enforced.

dowsing check          # → checks nothing, always succeeds

That is deliberate. A gate that turns the repository red on day one does not get fixed — it gets disabled. Measure where you are, start at a level that passes today, and tighten as things improve.

Available thresholds

Option	Meaning
--min-file-health <n>	Floor for file health
--min-package-health <n>	Floor for package health
--max-hotspot <n>	Ceiling for hotspot score (0–1)
--min-bus-factor <n>	Floor for package bus factor
--max-hidden-coupling <n>	Ceiling on hidden coupling count

Violations come with the reason attached.

✗ 1 violation (1 rule checked)
┌─────────────────┬──────────────────────────┬────────┬───────────┐
│ rule            │ target                   │ actual │ threshold │
├─────────────────┼──────────────────────────┼────────┼───────────┤
│ min-file-health │ src/ast/metrics.ts       │    4.5 │         5 │
└─────────────────┴──────────────────────────┴────────┴───────────┘

Risk assessment for a PR

dowsing diff origin/main --markdown

Reports, in Markdown, what kind of risky ground this PR touched.

## dowsing — risk assessment

`origin/main...HEAD`: 21 files changed, 16 analysed across 4 packages

> **It touches 7 hotspots.** These change often and are complex — review them closely.

| file                             | hotspot | health | commits | lines |
| -------------------------------- | ------: | -----: | ------: | ----: |
| `packages/core/src/report.ts` 🔥 |    0.96 |   10.0 |       6 |    76 |

### 🔗 Packages that usually change alongside these, but were not touched

| changed         | not touched            | degree | co-changes |
| --------------- | ---------------------- | -----: | ---------: |
| @acme/admin-web | **@acme/customer-web** |    33% |         91 |

It does not judge whether the change is correct

dowsing is not a linter. It never says "this change is wrong". It surfaces the risk of the ground you stepped on and asks you to confirm. Even when a usual co-change partner was left untouched, it adds "this does not necessarily need changing" — because correlation is not causation.

GitHub Code Scanning (SARIF)

dowsing check --sarif dowsing.sarif

- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: dowsing.sarif
    category: dowsing

It deliberately does not emit everything

SARIF output is limited to findings — places where several indicators overlap — and threshold violations.

Listing every smell as an alert produces thousands of entries and betrays the entire point of the tool, which is to give you a priority order. dowsing is not a replacement for a static-analysis linter.

The analysis conditions (time window, exclusion counts, whether the clone was shallow) are kept in properties, so you can always tell what the result was based on.

Templates

Two are provided in templates/github-actions/.

File	Purpose
dowsing-pr.yml	Comment risk assessment on PRs
dowsing-check.yml	Quality gate + Code Scanning

Copy them as-is. They also document how to choose thresholds.

Runtime on a monorepo

For reference — 3,920 commits, 40 packages, 2,238 files:

Command	Time
analyze	~7 s
analyze --verify-churn	~12 s
diff	~8 s

Comfortably within what you can afford in CI.