QueryGuard.Cli 0.1.0

QueryGuard.Cli

Records a query baseline from QueryGuard.NET JSON reports, and verifies later runs against it, so a query-count regression shows up in CI without any baseline plumbing written by hand.

dotnet tool install -g QueryGuard.Cli

The workflow

Your tests measure and write JSON reports:

await new QueryGuardJsonReporter().WriteAsync(result, "artifacts/queryguard/companies.json");

Record what the code costs today, once, and commit the file:

queryguard baseline record

Then on every run:

queryguard verify --summary artifacts/queryguard/summary.md

2 report(s), 2 scope(s) compared.
  REGRESSION GET /api/companies: 3 -> 51
             GET /api/users: unchanged

1 scope(s) run more queries than the baseline.
If that is intended, re-record the baseline and commit it.

3 -> 51 needs no threshold to read, which is the point: WithMaxQueries(10) needs someone to know that ten is right, and on an unmeasured endpoint nobody does.

Commands

queryguard baseline record [--reports <path>] [--baseline <file>]
queryguard verify [--reports <path>] [--baseline <file>] [--summary <file>] [--fail-on-regression]

Exit codes: 0 success, including a regression found without the flag; 1 bad usage or an unreadable file; 2 a regression, with --fail-on-regression.

Things worth knowing

It reports by default and fails on request. More queries is a fact; whether it is a defect is a judgement. A new feature legitimately costs queries.

Recording merges rather than replaces. A run that measured three endpoints will not delete the baseline for every endpoint it did not exercise.

A new scope is not a regression, and a scope missing from the run is ignored rather than reported as removed: a filtered test run would otherwise claim every endpoint it skipped had been deleted.

It does not run your tests. Measurement happens in the test process where the DbContext lives. A tool that owned that would have to guess your test command, your target framework, and your fixture wiring.

Files that are not QueryGuard reports are skipped, so a coverage file in the same directory does not stop the run.

In GitHub Actions

The QueryGuard action posts the table as a sticky pull request comment:

- run: dotnet test
- run: queryguard verify --summary artifacts/queryguard/summary.md
- uses: Benziza/queryguard-dotnet@v0.1.0

Full documentation: docs/baselines.

Versioning

The 0.1 public API is stable within the 0.1 release line. The baseline document carries its own schemaVersion, and a file written by a future major version is rejected rather than read optimistically. A silently empty baseline would report every scope as new and hide every regression.