governor-audit 0.3.0

Read-only BigQuery cost-audit tool — single-user, gcloud ADC only, no GCS / no GitHub / no dbt installation.

governor-audit

Read-only BigQuery cost-audit tool for single-user production audits. v0.3.0.

Posture: Single-user. gcloud ADC only. No GCS, no GitHub, no service-account JSON, no dbt installation, no shadow validation. The only thing it talks to over the network is BigQuery — and only to query INFORMATION_SCHEMA.JOBS_BY_PROJECT, INFORMATION_SCHEMA.COLUMNS, INFORMATION_SCHEMA.TABLE_STORAGE, and INFORMATION_SCHEMA.SCHEMATA_OPTIONS.

When to use this vs. the other governor packages

• governor-audit (this package): you have read access to a prod BigQuery project. You want a fast cost audit + detection findings without touching the dbt source code, running dbt, or setting up cloud infrastructure.
• governor-cli: you have the dbt project source on your machine and want to run dbt + propose fixes locally.
• governor-web: you operate the platform; you want shared infrastructure (GCS-backed manifests, GitHub PRs, scheduled syncs) for a team.

What you get

• Dashboard — Total / Build / Consumption / Flagged spend KPI cards, top-20 spenders bar chart, paginated cost-drivers table with click-to-sort columns and a per-row issue count, and a Storage Optimization panel listing per-dataset physical-billing opportunities with copyable ALTER SCHEMA actions.
• Detection engine — every enabled rule from governor_core.opportunities.rules runs against each cached job. Results are split into two buckets:
  • Issues (real cost / performance problems): slot_contention, join_explosion, partition_pruning, shuffle_spill, storage_billing_optimization. Listed standalone in /opportunities.
  • Suggestions (code-quality SQL rewrites): dead_cte, dead_column, dead_window_expression, unused_aggregation_output, redundant_order_by, unused_join, select_star, cross_join_unaggregated, self_join_anti_pattern. Attached to the issue they could improve, never standing on their own. Suggestions without a deterministic rewrite template are filtered out so the UI only shows actionable diffs.
• Opportunity detail — issue evidence (open by default) plus a stack of suggestion cards. Each suggestion card has a tabbed Diff / Original SQL view rendered from governor_core.solutions.templates. When no suggestions fire, the original SQL is still shown so you can read what ran.
• Settings — three pages:
  • Issues (/admin/settings/issues) — toggle the five issue rules.
  • Suggestions (/admin/settings/suggestions) — toggle the nine suggestion rules.
  • Storage Billing (/admin/settings/storage-billing) — pricing parameters for the storage billing rule.
  • Plus Account (gcloud principal + ADC probe), Appearance (light / dark / system), AI / LLM (Gemini API key, optional — reviewer code lands in a future release).
• Scan query preview — the configurations page shows the exact INFORMATION_SCHEMA SQL the next scan will run, with resolved timestamps, on a Jobs / Columns / Storage tabbed panel and a copy button.
• Reset cache — wipe everything INFORMATION_SCHEMA collected without losing your config.

Quickstart

gcloud auth application-default login
uv tool install governor-audit
governor-audit init --project prod-warehouse-123 --region us
governor-audit scan --days 30
governor-audit start
# open http://localhost:8765

The web UI exposes the same actions as the CLI plus the dashboard / settings views. After the first init you can do everything from the browser, including the setup wizard for any later config changes.

See the spec quickstarts for the full first-audit walkthrough:

• spec 141 quickstart — original audit MVP
• spec 144 — query-only rule catalog and synthetic manifest
• spec 145 — TABLE_STORAGE ingestion + dashboard storage panel

Architecture

• Storage: SQLite at ~/.governor-audit/state.db via governor_core.db.sqlite_compat. Four persisted shapes: BigQueryJob (raw INFORMATION_SCHEMA rows), TableColumnMetadata (column lists for SELECT * expansion), TableStorageMetric (per-table byte counts + per-dataset billing model — feeds the storage-billing rule), Opportunity (detection findings).
• Auth: gcloud Application Default Credentials only — google.auth.default(). No service-account JSON. No browser OAuth.
• Workload classification: manifest-free heuristic — dbt-originated CTAS / MERGE / INSERT / UPDATE / DELETE → build; non-dbt SELECT → consumption; ambiguous → other. Driven by the /* {"app": "dbt" comment-prefix the dbt-bigquery adapter prepends.
• Synthetic manifest (spec 144): audit reuses every governor_core rule unmodified by building a synthetic dbt-shaped manifest from BigQueryJob rows. Each row becomes a model node keyed by destination table; CTAS / MERGE wrappers are stripped so manifest-driven analyzers see the inner SELECT. The same pattern feeds governor_core.solutions.templates for deterministic before/after SQL diffs.
• Loopback only: the FastAPI app rejects any request whose Host: header isn't a localhost variant. Not a public service.

Versioning

governor-audit ships on its own version track, decoupled from the cloud bundle (governor-core / governor-web / governor-cli / governor-bq). Audit v0.2.x and cloud v0.7.x coexist. See scripts/release-audit.sh for the release flow.

License

MIT.