bqcost 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Gryazev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# bqcost
+
+**Catch the BigQuery query that would've cost $10k — in your PR.**
+
+`sqlfluff` catches your style. **bqcost catches the query that scans 3 TB.** It dry-runs every
+changed `.sql`/dbt model, prices the scan, flags the cost **regression vs your base branch**, and
+comments the number on the PR — before you merge.
+
+> BigQuery bills by bytes scanned. One missing partition filter turns a $0.02 query into a $20
+> one (or a $10k one). bqcost surfaces that in review, not on the invoice.
+
+![bqcost catching a $20 scan before merge](docs/demo.svg)
+
+<sub>Prefer an animated GIF? `vhs docs/demo.tape` renders one from a real run.</sub>
+
+---
+
+## Quickstart (≈30 seconds)
+
+```bash
+# authenticate once (Application Default Credentials)
+gcloud auth application-default login
+
+# lint a file or a directory of .sql
+npx bqcost lint ./models
+```
+
+```text
+bqcost: scanned 1 file(s), est. $20.20, 2 finding(s)
+
+examples/big-scan.sql  ($20.20, 3310.3 GB)
+  [R2] scans 3310.3 GB ($20.20) of partitioned table bigquery-public-data.crypto_ethereum.transactions — check the partition filter
+        fix: narrow the filter on partition column `block_timestamp` (e.g. WHERE block_timestamp >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
+  [R1] SELECT * — reads every column (3310.3 GB)
+        fix: project only the columns you need instead of *
+```
+
+That's a real dry-run against a real table — **$20.20, 3.3 TB**, caught before it ran.
+
+## In CI — the cost gate on every PR
+
+```yaml
+# .github/workflows/bqcost.yml
+name: bqcost
+on: pull_request
+jobs:
+  cost:
+    runs-on: ubuntu-latest
+    permissions: { contents: read, pull-requests: write }
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }              # bqcost needs base..head
+      - uses: google-github-actions/auth@v2   # your GCP service account
+        with: { credentials_json: '${{ secrets.GCP_SA_KEY }}' }
+      - uses: dagryazev/bqcost@v1              # dry-runs changed .sql, posts a sticky PR comment
+```
+
+On each PR bqcost posts (and updates) one comment: cost per changed file, **Δ vs base**, and the
+findings. It fails the check when a change adds more than your threshold (default $1).
+
+## Pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/dagryazev/bqcost
+    rev: v1
+    hooks:
+      - id: bqcost
+```
+
+## What it checks
+
+| rule | flags | how |
+|------|-------|-----|
+| **R2** | a big scan of a **partitioned** table (the missing partition filter) | **measured** — real dry-run bytes, not a static guess |
+| **R1** | `SELECT *` on a table that actually costs | AST + cost |
+| **R4** | `CROSS JOIN` fan-out | AST |
+| **R5** | `ORDER BY` without `LIMIT` | AST |
+
+R2 is measured on purpose: BigQuery's optimizer prunes many predicates that "look" unprunable
+(`DATE(ts) = …`, `EXTRACT(YEAR …)`), so a static "function wrap ⇒ no pruning" rule would cry wolf.
+bqcost reads what the query **actually** scans instead. (See `docs/decisions.md`.)
+
+## Configuration — `.bqcost.yml`
+
+```yaml
+pricePerTiB: 6.25            # on-demand $/TiB (US)
+regression:
+  absUsd: 1                  # fail a PR when a file adds > $1
+rules:
+  r1: { minBytes: 1073741824 }        # 1 GiB — below this, SELECT * is quiet
+  r2: { minScanBytes: 107374182400 }  # 100 GiB — flag scans bigger than this
+allowlist: ["reporting.big_daily_rollup"]   # skip known-huge tables
+disabledRules: ["R5"]
+dbt: { manifestPath: target/manifest.json } # lint compiled SQL, not Jinja
+```
+
+Silence one query inline:
+
+```sql
+SELECT * FROM `p.d.events`  -- bqcost:ignore        (all rules)
+SELECT * FROM `p.d.events`  -- bqcost:ignore R1     (just R1)
+```
+
+## Is it safe? Yes — dry-run only
+
+bqcost uses BigQuery **dry-run**: it validates and prices the query **without executing it and
+without reading a single row**. Dry-runs are free and don't consume slots. Give it a service
+account with `roles/bigquery.jobUser` + `roles/bigquery.dataViewer` (read-only) and nothing more.
+
+## dbt
+
+Point `dbt.manifestPath` at your `target/manifest.json` (after `dbt compile`) and bqcost lints the
+**compiled** SQL, so `{{ ref() }}` is resolved to real tables.
+
+## License
+
+MIT.

package/dist/cli.js

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/core/config.ts
+import { z } from "zod";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+var ConfigSchema = z.object({
+  pricePerTiB: z.number().positive().default(6.25),
+  currency: z.string().default("USD"),
+  paths: z.array(z.string()).default(["**/*.sql"]),
+  /** Substrings of table refs to skip entirely (e.g. a known-huge reporting table). */
+  allowlist: z.array(z.string()).default([]),
+  /** Rule ids to turn off (e.g. ["R5"]). */
+  disabledRules: z.array(z.string()).default([]),
+  /** Cost-regression gate vs the base branch. */
+  regression: z.object({ absUsd: z.number().default(1) }).default({}),
+  /** dbt: point at a compiled manifest.json to lint compiled SQL instead of Jinja source. */
+  dbt: z.object({ manifestPath: z.string().optional() }).default({}),
+  rules: z.object({
+    r1: z.object({ minBytes: z.number().default(1 * 2 ** 30) }).default({}),
+    r2: z.object({ minScanBytes: z.number().default(100 * 2 ** 30) }).default({})
+  }).default({})
+});
+function defaultConfig() {
+  return ConfigSchema.parse({});
+}
+function loadConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".bqcost.yml");
+  if (!existsSync(path)) return defaultConfig();
+  return ConfigSchema.parse(parseYaml(readFileSync(path, "utf8")) ?? {});
+}
+
+// src/run.ts
+import { existsSync as existsSync2 } from "fs";
+
+// src/core/extract.ts
+import { readFileSync as readFileSync3, readdirSync, statSync } from "fs";
+import { join as join2, extname } from "path";
+
+// src/core/parse.ts
+import pkg from "node-sql-parser";
+var { Parser } = pkg;
+var parser = new Parser();
+var OPT = { database: "BigQuery" };
+function tableRefs(sql) {
+  try {
+    const list = parser.tableList(sql, OPT);
+    return list.map((t) => t.split("::").slice(1).filter((x) => x && x !== "null").join(".")).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function parse(sql) {
+  try {
+    const ast = parser.astify(sql, OPT);
+    return { ast, tables: tableRefs(sql) };
+  } catch (e) {
+    return { parseError: (e?.message ?? String(e)).split("\n")[0], tables: [] };
+  }
+}
+
+// src/adapters/dbt.ts
+import { readFileSync as readFileSync2 } from "fs";
+function loadCompiledSql(manifestPath) {
+  const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  const out = /* @__PURE__ */ new Map();
+  for (const node of Object.values(manifest.nodes ?? {})) {
+    const sql = node.compiled_code ?? node.raw_code;
+    if (node.original_file_path && sql) out.set(node.original_file_path, sql);
+  }
+  return out;
+}
+function compiledFor(file, compiled) {
+  const norm = file.replace(/\\/g, "/");
+  for (const [key, sql] of compiled) {
+    if (norm === key || norm.endsWith("/" + key) || norm.endsWith(key)) return sql;
+  }
+  return void 0;
+}
+
+// src/core/extract.ts
+function findSqlFiles(target) {
+  const st = statSync(target);
+  if (st.isFile()) return extname(target) === ".sql" ? [target] : [];
+  const out = [];
+  for (const entry of readdirSync(target)) out.push(...findSqlFiles(join2(target, entry)));
+  return out;
+}
+function extract(files, compiled) {
+  return files.map((file) => {
+    const dbtSql = compiled && compiledFor(file, compiled);
+    const rawText = dbtSql ?? readFileSync3(file, "utf8");
+    const p = parse(rawText);
+    return {
+      id: file,
+      sourceFile: file,
+      rawText,
+      kind: dbtSql ? "dbt_model" : "sql",
+      refs: p.tables,
+      ast: p.ast,
+      parseError: p.parseError
+    };
+  });
+}
+
+// src/core/cost.ts
+var TIB = 2 ** 40;
+function bytesToUsd(bytes, pricePerTiB) {
+  return bytes / TIB * pricePerTiB;
+}
+function formatUsd(usd) {
+  const neg = usd < 0;
+  const a = Math.abs(usd);
+  const s = a < 0.01 ? `$${a.toFixed(4)}` : `$${a.toFixed(2)}`;
+  return neg ? `-${s}` : s;
+}
+function regress(head, base, absUsd, pricePerTiB) {
+  const headBytes = head.totalBytesProcessed;
+  const baseBytes = base?.dryRunOk ? base.totalBytesProcessed : null;
+  const deltaBytes = headBytes - (baseBytes ?? 0);
+  const deltaUsd = bytesToUsd(deltaBytes, pricePerTiB);
+  return { headBytes, baseBytes, deltaBytes, deltaUsd, verdict: deltaUsd >= absUsd ? "fail" : "ok" };
+}
+
+// src/core/rules/r2-partition-scan.ts
+var r2PartitionScan = {
+  id: "R2",
+  severity: "warn",
+  check(ctx) {
+    const { cost, tables, cfg } = ctx;
+    if (!cost?.dryRunOk) return [];
+    if (cost.totalBytesProcessed < cfg.rules.r2.minScanBytes) return [];
+    const partRef = cost.referencedTables.find((r) => tables.get(r)?.isPartitioned);
+    if (!partRef) return [];
+    const meta = tables.get(partRef);
+    const gb2 = (cost.totalBytesProcessed / 2 ** 30).toFixed(1);
+    return [
+      {
+        ruleId: "R2",
+        severity: "warn",
+        message: `scans ${gb2} GB (${formatUsd(cost.estimatedUsd)}) of partitioned table ${partRef} \u2014 check the partition filter`,
+        fixHint: meta.partitionColumn ? `narrow the filter on partition column \`${meta.partitionColumn}\` (e.g. WHERE ${meta.partitionColumn} >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))` : `add a filter on the partition column of ${partRef}`
+      }
+    ];
+  }
+};
+
+// src/core/rules/ast.ts
+function collectSelects(node, out = []) {
+  if (!node || typeof node !== "object") return out;
+  if (Array.isArray(node)) {
+    for (const n of node) collectSelects(n, out);
+    return out;
+  }
+  if (node.type === "select") out.push(node);
+  for (const v of Object.values(node)) {
+    if (v && typeof v === "object") collectSelects(v, out);
+  }
+  return out;
+}
+function selectHasStar(sel) {
+  const cols = sel?.columns;
+  if (cols === "*") return true;
+  if (!Array.isArray(cols)) return false;
+  return cols.some((c) => c === "*" || c?.expr?.type === "star" || c?.expr?.column === "*");
+}
+
+// src/core/rules/r1-select-star.ts
+var r1SelectStar = {
+  id: "R1",
+  severity: "info",
+  check(ctx) {
+    const ast = ctx.unit.ast;
+    if (!ast) return [];
+    const bytes = ctx.cost?.totalBytesProcessed ?? 0;
+    if (ctx.cost?.dryRunOk && bytes < ctx.cfg.rules.r1.minBytes) return [];
+    if (!collectSelects(ast).some(selectHasStar)) return [];
+    const gb2 = ctx.cost?.dryRunOk ? ` (${(bytes / 2 ** 30).toFixed(1)} GB)` : "";
+    return [
+      {
+        ruleId: "R1",
+        severity: "info",
+        message: `SELECT * \u2014 reads every column${gb2}`,
+        fixHint: "project only the columns you need instead of *"
+      }
+    ];
+  }
+};
+
+// src/core/rules/r4-cross-join.ts
+var r4CrossJoin = {
+  id: "R4",
+  severity: "warn",
+  check(ctx) {
+    const ast = ctx.unit.ast;
+    if (!ast) return [];
+    for (const sel of collectSelects(ast)) {
+      const from = sel.from;
+      if (!Array.isArray(from)) continue;
+      for (const f of from) {
+        if (String(f?.join ?? "").toUpperCase().includes("CROSS")) {
+          return [
+            {
+              ruleId: "R4",
+              severity: "warn",
+              message: "CROSS JOIN \u2014 cartesian fan-out risk",
+              fixHint: "add join keys (ON/USING) or confirm the intent"
+            }
+          ];
+        }
+      }
+    }
+    return [];
+  }
+};
+
+// src/core/rules/r5-orderby-no-limit.ts
+var r5OrderByNoLimit = {
+  id: "R5",
+  severity: "info",
+  check(ctx) {
+    const ast = ctx.unit.ast;
+    if (!ast) return [];
+    for (const sel of collectSelects(ast)) {
+      const hasOrder = Array.isArray(sel.orderby) ? sel.orderby.length > 0 : !!sel.orderby;
+      if (hasOrder && !sel.limit) {
+        return [
+          {
+            ruleId: "R5",
+            severity: "info",
+            message: "ORDER BY without LIMIT \u2014 sorts the whole result",
+            fixHint: "add LIMIT, or drop ORDER BY in a subquery/CTE"
+          }
+        ];
+      }
+    }
+    return [];
+  }
+};
+
+// src/core/rules/index.ts
+var RULES = [r2PartitionScan, r1SelectStar, r4CrossJoin, r5OrderByNoLimit];
+
+// src/core/suppress.ts
+function ignoredRules(sql) {
+  const m = sql.match(/--\s*bqcost:ignore(.*)$/im);
+  if (!m) return null;
+  const ids = m[1].trim().split(/[,\s]+/).map((s) => s.toUpperCase()).filter(Boolean);
+  return ids.length ? new Set(ids) : "all";
+}
+function applySuppressions(unit, cost, findings, cfg) {
+  const refs = [...unit.refs, ...cost?.referencedTables ?? []];
+  if (cfg.allowlist.some((a) => refs.some((r) => r.includes(a)))) return [];
+  const ign = ignoredRules(unit.rawText);
+  if (ign === "all") return [];
+  const disabled = new Set(cfg.disabledRules.map((s) => s.toUpperCase()));
+  return findings.filter(
+    (f) => !(ign && ign.has(f.ruleId)) && !disabled.has(f.ruleId.toUpperCase())
+  );
+}
+
+// src/run.ts
+async function ruleFindings(unit, cost, bq, config) {
+  const tables = /* @__PURE__ */ new Map();
+  if (cost.dryRunOk) {
+    for (const ref of cost.referencedTables) {
+      const meta = await bq.fetchTableMeta(ref);
+      if (meta) tables.set(ref, meta);
+    }
+  }
+  const raw = RULES.flatMap((r) => r.check({ unit, cost, tables, cfg: config }));
+  return applySuppressions(unit, cost, raw, config);
+}
+async function run(target, config, bq) {
+  const mp = config.dbt.manifestPath;
+  const compiled = mp && existsSync2(mp) ? loadCompiledSql(mp) : void 0;
+  const units = extract(findSqlFiles(target), compiled);
+  const results = [];
+  for (const unit of units) {
+    let cost;
+    let findings2 = [];
+    if (bq) {
+      cost = await bq.estimateCost(unit.rawText);
+      findings2 = await ruleFindings(unit, cost, bq, config);
+    }
+    results.push({ unit, cost, findings: findings2 });
+  }
+  const findings = results.flatMap((r) => r.findings);
+  const totalUsd = results.reduce((s, r) => s + (r.cost?.estimatedUsd ?? 0), 0);
+  return { scanned: units.length, results, findings, totalUsd };
+}
+
+// src/ci.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join3 } from "path";
+
+// src/core/normalize.ts
+function normalize(sql) {
+  return sql.replace(/--[^\n]*/g, " ").replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\s+/g, " ").trim();
+}
+function sqlUnchanged(a, b) {
+  return normalize(a) === normalize(b);
+}
+
+// src/adapters/git.ts
+import { execFileSync } from "child_process";
+function git(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" });
+}
+function changedSqlFiles(base, cwd) {
+  const out = git(["diff", "--name-only", "--diff-filter=AM", `${base}...HEAD`], cwd);
+  return out.split("\n").map((s) => s.trim()).filter((f) => f.endsWith(".sql"));
+}
+function fileAtBase(base, path, cwd) {
+  try {
+    return git(["show", `${base}:${path}`], cwd);
+  } catch {
+    return null;
+  }
+}
+
+// src/ci.ts
+async function runChanged(base, cwd, config, bq) {
+  const files = changedSqlFiles(base, cwd);
+  const results = [];
+  for (const file of files) {
+    const headSql = readFileSync4(join3(cwd, file), "utf8");
+    const head = await bq.estimateCost(headSql);
+    let regression;
+    let findings = [];
+    if (head.dryRunOk) {
+      const baseSql = fileAtBase(base, file, cwd);
+      const baseCost = baseSql && !sqlUnchanged(baseSql, headSql) ? await bq.estimateCost(baseSql) : null;
+      regression = regress(head, baseCost, config.regression.absUsd, config.pricePerTiB);
+      const p = parse(headSql);
+      const unit = { id: file, sourceFile: file, rawText: headSql, kind: "sql", refs: p.tables, ast: p.ast };
+      findings = await ruleFindings(unit, head, bq, config);
+    }
+    results.push({ file, head, regression, findings });
+  }
+  const totalDeltaUsd = results.reduce((s, r) => s + (r.regression?.deltaUsd ?? 0), 0);
+  const verdict = results.some((r) => r.regression?.verdict === "fail") ? "fail" : "ok";
+  return { base, results, totalDeltaUsd, verdict };
+}
+
+// src/core/report.ts
+var gb = (bytes) => (bytes / 2 ** 30).toFixed(1) + " GB";
+function renderCli(report) {
+  const lines = [
+    `bqcost: scanned ${report.scanned} file(s), est. ${formatUsd(report.totalUsd)}, ${report.findings.length} finding(s)`
+  ];
+  for (const r of report.results) {
+    if (!r.findings.length) continue;
+    const cost = r.cost?.dryRunOk ? `  (${formatUsd(r.cost.estimatedUsd)}, ${gb(r.cost.totalBytesProcessed)})` : "";
+    lines.push(`
+${r.unit.sourceFile}${cost}`);
+    for (const f of r.findings) {
+      lines.push(`  [${f.ruleId}] ${f.message}`);
+      if (f.fixHint) lines.push(`        fix: ${f.fixHint}`);
+    }
+  }
+  return lines.join("\n");
+}
+function renderCi(ci) {
+  const lines = [
+    `bqcost CI vs ${ci.base}: ${ci.results.length} changed file(s), \u0394 ${formatUsd(ci.totalDeltaUsd)}, verdict ${ci.verdict.toUpperCase()}`
+  ];
+  for (const r of ci.results) {
+    if (!r.head?.dryRunOk) {
+      lines.push(`
+${r.file}  (not estimated: ${r.head?.error ?? "no estimate"})`);
+      continue;
+    }
+    const reg = r.regression;
+    const delta = reg.baseBytes == null ? "new query" : `\u0394 ${formatUsd(reg.deltaUsd)}`;
+    const mark = reg.verdict === "fail" ? "\u274C" : "\u2705";
+    lines.push(`
+${r.file}  ${formatUsd(r.head.estimatedUsd)} (${gb(r.head.totalBytesProcessed)})  ${delta} ${mark}`);
+    for (const f of r.findings) {
+      lines.push(`  [${f.ruleId}] ${f.message}`);
+      if (f.fixHint) lines.push(`        fix: ${f.fixHint}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/adapters/bigquery.ts
+import { BigQuery } from "@google-cloud/bigquery";
+var BqClient = class {
+  bq;
+  location;
+  pricePerTiB;
+  metaCache = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.bq = new BigQuery(opts.projectId ? { projectId: opts.projectId } : {});
+    this.location = opts.location;
+    this.pricePerTiB = opts.pricePerTiB;
+  }
+  /** Dry-run cost. Fail-soft: on error returns `dryRunOk:false` rather than throwing. */
+  async estimateCost(sql) {
+    try {
+      const [job] = await this.bq.createQueryJob({
+        query: sql,
+        dryRun: true,
+        location: this.location
+      });
+      const stats = job.metadata?.statistics ?? {};
+      const bytes = Number(stats.totalBytesProcessed ?? 0);
+      const refs = (stats.query?.referencedTables ?? []).map(
+        (t) => `${t.projectId}.${t.datasetId}.${t.tableId}`
+      );
+      return {
+        totalBytesProcessed: bytes,
+        estimatedUsd: bytesToUsd(bytes, this.pricePerTiB),
+        referencedTables: refs,
+        dryRunOk: true
+      };
+    } catch (e) {
+      return {
+        totalBytesProcessed: 0,
+        estimatedUsd: 0,
+        referencedTables: [],
+        dryRunOk: false,
+        error: e?.message ?? String(e)
+      };
+    }
+  }
+  /** Partition/clustering metadata for `project.dataset.table` (cached, fail-soft). */
+  async fetchTableMeta(fqName) {
+    if (this.metaCache.has(fqName)) return this.metaCache.get(fqName) ?? null;
+    const meta = await this.loadTableMeta(fqName);
+    this.metaCache.set(fqName, meta);
+    return meta;
+  }
+  async loadTableMeta(fqName) {
+    const parts = fqName.split(".");
+    if (parts.length !== 3) return null;
+    const [project, dataset, table] = parts;
+    try {
+      const [md] = await this.bq.dataset(dataset, { projectId: project }).table(table).getMetadata();
+      const tp = md.timePartitioning;
+      const rp = md.rangePartitioning;
+      let partitionColumn = null;
+      let partitionType = null;
+      if (tp) {
+        partitionColumn = tp.field ?? "_PARTITIONTIME";
+        partitionType = tp.field ? tp.type ?? "DAY" : "INGESTION_TIME";
+      } else if (rp) {
+        partitionColumn = rp.field ?? null;
+        partitionType = "RANGE";
+      }
+      return {
+        fqName,
+        sizeBytes: md.numBytes != null ? Number(md.numBytes) : null,
+        isPartitioned: !!(tp || rp),
+        partitionColumn,
+        partitionType,
+        clusteringColumns: md.clustering?.fields ?? [],
+        isView: md.type === "VIEW"
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/cli.ts
+function bqFromEnv(pricePerTiB) {
+  return process.env.GOOGLE_APPLICATION_CREDENTIALS ? new BqClient({
+    projectId: process.env.BQCOST_PROJECT_ID,
+    location: process.env.BQCOST_LOCATION,
+    pricePerTiB
+  }) : null;
+}
+var program = new Command();
+program.name("bqcost").description("Catch the BigQuery query that would've cost $10k \u2014 in your PR.").version("0.0.0");
+program.command("lint").argument("<paths...>", "files or directories of .sql to lint").action(async (paths) => {
+  const config = loadConfig();
+  const bq = bqFromEnv(config.pricePerTiB);
+  let failed = false;
+  for (const p of paths) {
+    const report = await run(p, config, bq);
+    console.log(renderCli(report));
+    if (report.findings.some((f) => f.severity === "error")) failed = true;
+  }
+  process.exitCode = failed ? 1 : 0;
+});
+program.command("ci").description("cost-regression gate for changed .sql vs a base git ref").option("--base <ref>", "base git ref", "origin/main").action(async (opts) => {
+  const config = loadConfig();
+  const bq = bqFromEnv(config.pricePerTiB);
+  if (!bq) {
+    console.error("bqcost ci needs BigQuery creds (GOOGLE_APPLICATION_CREDENTIALS).");
+    process.exitCode = 2;
+    return;
+  }
+  const ci = await runChanged(opts.base, process.cwd(), config, bq);
+  console.log(renderCi(ci));
+  process.exitCode = ci.verdict === "fail" ? 1 : 0;
+});
+program.parseAsync();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "bqcost",
+  "version": "0.1.0",
+  "description": "Catch the BigQuery query that would've cost $10k — in your PR. Dry-run cost + regression gate for CI.",
+  "keywords": [
+    "bigquery",
+    "cost",
+    "finops",
+    "dbt",
+    "sql",
+    "linter",
+    "github-action",
+    "pre-commit",
+    "ci",
+    "dry-run"
+  ],
+  "homepage": "https://github.com/dagryazev/bqcost#readme",
+  "bugs": "https://github.com/dagryazev/bqcost/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dagryazev/bqcost.git"
+  },
+  "license": "MIT",
+  "author": "Denis Gryazev",
+  "type": "module",
+  "bin": { "bqcost": "dist/cli.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "label:r2": "tsx scripts/label-r2.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@google-cloud/bigquery": "^7.9.0",
+    "commander": "^12.1.0",
+    "node-sql-parser": "^5.3.4",
+    "yaml": "^2.6.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@actions/core": "^1.11.1",
+    "@actions/github": "^6.0.0",
+    "@types/node": "^22.9.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5"
+  }
+}