safegres 1.14.2 → 1.15.0

package/README.md

@@ -34,6 +34,39 @@ Pretty output prints the exposure line, score, and the exposed findings. Interna
 - `--verbose` — expand the internal advisories instead of collapsing them to a count.
 - `--exposed-only` — drop internal findings entirely.
 - `--format json` / `--format json-pretty` — machine-readable output (always carries every finding).
+- `--format markdown` — the same report as GitHub-flavoured markdown, for a job summary or a PR comment (see [CI](#ci)).
+- `--format sarif` — SARIF 2.1.0 for GitHub code scanning (see [CI](#ci)).
+
+### CI
+
+A plain audit is one command and one gate; `--format markdown` writes the report where a reviewer will actually see it:
+
+```yaml
+- name: Audit RLS
+  run: |
+    npx safegres audit --format markdown >> "$GITHUB_STEP_SUMMARY"
+    npx safegres audit --fail-on-grade B --summary
+  env:
+    PGHOST: localhost
+    PGUSER: postgres
+    PGPASSWORD: postgres
+```
+
+Scores lead, then the severity counts, then a table per dimension; internal (non-exposed) advisories and accepted baseline debt fold into `<details>` so the summary stays skimmable. To post it as a PR comment instead, pipe it to `gh pr comment --body-file -`. The same renderer is available to library callers as `renderMarkdown(report)`.
+
+#### Code scanning (SARIF)
+
+`--format sarif` emits SARIF 2.1.0, so findings become GitHub code-scanning alerts — Security tab, inline PR annotations, dismissals that stick:
+
+```yaml
+- run: npx safegres audit --perf --format sarif --sarif-sources ./deploy > safegres.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: safegres.sarif }
+```
+
+An alert needs a file and a line, but safegres reads the catalog — a live database has no source location. `--sarif-sources <dir>` scans that directory's `.sql` for the `CREATE TABLE` / `CREATE POLICY` that defines each object, so a finding on `app_public.widgets` points at the migration that created it (policy findings resolve to the `CREATE POLICY` line). Findings that don't resolve are still emitted, without a location — GitHub drops those, other SARIF consumers keep them.
+
+Results are fingerprinted by finding *identity* (code + relation + policy + subject, the same key the [perf baseline](#perf-baseline-the-ratchet) uses), never by message text, so rewording a rule in a later release doesn't close and reopen every alert. Perf rules are tagged `performance`, security rules `security`.
 
 ## What it checks
 
@@ -112,11 +145,15 @@ A slow database is a different problem from an unsafe one, so safegres scores th
 | X4 | low | index | **Policy calls a non-LEAKPROOF function** — the qual can't be pushed below joins or subquery scans |
 | X5 | low | index | **Redundant index** — an exact duplicate of, or a leading-column prefix of, another index |
 | X6 | low | index | **No primary key** and no usable replica identity — rows cannot be addressed by updates, deletes, or logical replication |
+| X7 | medium | index | **Search column with no index the search can use** — a `tsvector` without GIN/GiST, a `vector` without HNSW/IVFFlat |
+| X8 | info | index | **Sort-shaped column leads no index** (`timestamptz`/`date`) — ordering or cursor-paginating a connection by it sorts the whole table |
 | P1 | high | anti-pattern | Policy body calls a **VOLATILE function** — re-evaluated per row |
 | P1b | medium | anti-pattern | Policy body calls a **STABLE function** in a per-row position |
 
 Every check is pure catalog + AST analysis: deterministic, workload-free, and safe to run against an empty CI database. An index covers a foreign key only when its *leading* columns are the FK's columns and it covers every row — partial and expression indexes don't count, because the planner can't use them for the referential-integrity lookup. Constraint-backed, unique, partial, and expression indexes are never reported as redundant.
 
+X7 exists because the column type *is* the API declaration: `graphile-search` exposes a full-text filter for every `tsvector` column and a similarity search for every `vector` column, purely from the codec — so an unindexed one is a first-class API field backed by a sequential scan plus a per-row match or distance computation. BM25 and pg_trgm are deliberately not checked: those adapters are discovered *from* their indexes, so a missing index means the feature was never exposed. X8 is the one heuristic in the set — any column is orderable over a connection, but timestamps are what feeds are actually sorted and keyset-paginated by — so it defaults to `info`, contributes 0 to the score, and is meant to be read, not gated on (`perf.rules: { "X8": "off" }` to silence it). Trailing-position and partial indexes don't count for either rule: neither can serve the sort or the search on its own.
+
 X2–X4 are the checks a generic index linter can't make, because they read the policy predicate. RLS quals are evaluated *before* user quals, on every candidate row, for every caller — so an unindexed or cast-wrapped policy column is a whole-table tax rather than a slow query. X2 requires the policy column to be the *leading* column of some index (a trailing position can't serve the qual alone); X3 looks for an expression index matching the exact wrapped shape; X4 skips built-ins, whose leakproofness is a property of the server rather than a schema choice.
 
 ```bash
@@ -158,6 +195,59 @@ performance vs baseline:
 
 Entries are identified by `code` + relation + policy + subject (the constraint, index, expression, column, or function the finding is about), so rewording a message or retuning a severity between safegres versions never invalidates a committed baseline, and two findings of the same code on the same table stay distinct. Findings that disappear are reported as fixed — re-run `--write-perf-baseline` to lock the win in and stop them regressing silently. The diff is also carried in JSON output as `perf.diff`, and available to library callers as `diffPerf(findings, baseline)`.
 
+### Runtime statistics (`--stats`)
+
+The `X*` rules read the schema; the `S*` rules read what the workload actually did to it. They come from `pg_stat_user_tables`, `pg_stat_user_indexes` and — when the extension is installed — `pg_stat_statements`, so they only mean something against a database that has served representative traffic. Opt in with `--stats` (which implies `--perf`):
+
+| Code | Severity | Check |
+| --- | --- | --- |
+| S1 | medium | **Sequential-scan-dominant table** — seq scans outnumber index scans 10:1 on a table with indexes and ≥ 1000 live rows |
+| S2 | low | **Index the planner has never chosen** (`idx_scan = 0`) and larger than 1 MiB — pure write cost, unless it's there for a rare report |
+| S3 | low | **Dead-tuple bloat** — dead tuples ≥ 20% of live rows; autovacuum is not keeping up |
+| S4 | info | **Statement hotspot** — a statement taking ≥ 5% of sampled execution time whose relations are in scope |
+
+Every threshold is a floor, and every floor is configurable, because a counter is only evidence if there is enough of it:
+
+```jsonc
+{
+  "perf": {
+    "stats": {
+      "minRows": 1000,          // S1/S3: below this a scan is the right plan
+      "seqScanRatio": 10,       // S1: seq:idx scan ratio that counts as dominant
+      "minIndexBytes": 1048576, // S2: ignore indexes too small to be worth dropping
+      "deadTupleRatio": 0.2,    // S3
+      "minTimeShare": 0.05,     // S4: share of total sampled time
+      "topStatements": 5        // S4: cap
+    },
+    "scoring": { "includeStats": false }   // demote S* to advisories
+  }
+}
+```
+
+`S*` findings are **scored** on the perf axis — asking for `--stats` is the opt-in — but `perf.scoring.includeStats: false` demotes them to advisories if you want the grade to stay purely deterministic. The report carries its own provenance in `perf.stats`: how many tables were read, when the counters were last reset (the window the numbers describe), whether they were scored, and a note when `pg_stat_statements` isn't installed. Absent statistics are never an error; the audit just says so.
+
+### Planner proof (`--explain`)
+
+The `X*` rules *infer* from the catalog that nothing can serve a query shape. `--explain` asks the database instead: for each probeable finding it plans the query the finding is a claim about with `EXPLAIN (GENERIC_PLAN, FORMAT JSON)` — nothing is executed, and parameters stay parameters, so no value has to be invented for a column — and attaches the plan as `finding.evidence`.
+
+The interesting outcome is disagreement. A finding whose probe plans as an index scan is **refuted**: some index the catalog rules didn't credit (a hash index on an FK column, say) does serve it, so the finding is acknowledged, reported as info, and dropped from the perf score. The reverse is deliberately not symmetrical — an empty or unanalyzed table always seq-scans, so a seq scan **confirms** a finding only above a planner row estimate of 1000 (`perf.explain.minRows`); below that the probe is `inconclusive` and the finding is left exactly as the static rule made it.
+
+```bash
+safegres audit --perf --explain --database mydb
+```
+
+```
+[medium] X1  app_public.posts
+    foreign key posts_author_id_fkey has no covering index
+    plan (confirmed): Seq Scan
+[info] X1  app_public.notes
+    foreign key notes_author_id_fkey has no covering index — refuted by EXPLAIN (the planner serves this shape with an index)
+    plan (refuted): Bitmap Heap Scan → Bitmap Index Scan
+  planner proof: 1 confirmed, 1 refuted, 1 inconclusive of 3 probed
+```
+
+Probes exist for X1, X2, X7 and X8 — the rules that name a query shape. X5, X6, `P*` and `S*` are claims about the schema or the workload rather than a plan, so nothing is planned speculatively on their behalf. `GENERIC_PLAN` requires PostgreSQL 16+; on older servers the audit reports `perf.explain.unavailable` and leaves the findings untouched.
+
 ## Call graph (`--call-graph`)
 
 RLS findings tell you what the *tables* allow. The call graph tells you what the *functions* reach: starting from the exposed entry points (functions the API roles can `EXECUTE`), safegres statically walks each body and lists every **trust boundary** on the way — unscored, because a public `SECURITY DEFINER` calling private functions is the intended pattern (that's how `sign_in` works). The output is a deterministic checklist for human review:

package/checks/indexes.d.ts

@@ -36,3 +36,24 @@ export declare function checkRedundantIndexes(table: TableIndexSnapshot): Findin
  * realtime/change-feed features break.
  */
 export declare function checkMissingPrimaryKey(table: TableIndexSnapshot): Finding | null;
+/**
+ * X7: a search column with no index the search can use.
+ *
+ * A `tsvector` or `vector` column is exposed as a search field by
+ * `graphile-search` purely from its type — the schema promises a fast path.
+ * Without a GIN/GiST (full-text) or HNSW/IVFFlat (vector) index the promise
+ * is served by a sequential scan plus a per-row distance or match computation,
+ * which is the single worst plan the API can produce.
+ */
+export declare function checkUnindexedSearchColumns(table: TableIndexSnapshot): Finding[];
+/**
+ * X8: a sort-shaped column that leads no index.
+ *
+ * Every PostGraphile connection can be ordered by any column and paginated
+ * with a cursor over that order. Sorting on an unindexed column forces a full
+ * sort of the (RLS-filtered) result on every page, and keyset pagination
+ * degenerates into a scan-and-discard. Timestamp columns are singled out
+ * because they are what feeds are actually ordered by — a heuristic, hence
+ * `info` by default; turn it off with `perf.rules: { "X8": "off" }`.
+ */
+export declare function checkUnindexedSortColumns(table: TableIndexSnapshot): Finding[];

package/checks/indexes.js

@@ -9,6 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkUnindexedForeignKeys = checkUnindexedForeignKeys;
 exports.checkRedundantIndexes = checkRedundantIndexes;
 exports.checkMissingPrimaryKey = checkMissingPrimaryKey;
+exports.checkUnindexedSearchColumns = checkUnindexedSearchColumns;
+exports.checkUnindexedSortColumns = checkUnindexedSortColumns;
 /**
  * X1: a foreign key with no index that can serve it.
  *
@@ -114,6 +116,108 @@ function checkMissingPrimaryKey(table) {
         context: { replicaIdentity: table.replicaIdentity }
     };
 }
+/**
+ * Search column types that only perform with a specialised index, mapped to
+ * the access methods that can serve them.
+ *
+ * The column type *is* the declaration: `graphile-search` detects searchable
+ * columns by codec (tsvector → full-text filter, vector → similarity search),
+ * so a bare `tsvector` column is already an API promise. BM25 and pg_trgm are
+ * absent on purpose — they are discovered *from* their indexes, so a missing
+ * index means the feature was never exposed rather than exposed and slow.
+ */
+const SEARCH_TYPES = {
+    tsvector: {
+        methods: ['gin', 'gist'],
+        feature: 'full-text search',
+        example: 'USING gin (%s)'
+    },
+    vector: {
+        methods: ['hnsw', 'ivfflat'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s vector_cosine_ops)'
+    },
+    halfvec: {
+        methods: ['hnsw', 'ivfflat'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s halfvec_cosine_ops)'
+    },
+    sparsevec: {
+        methods: ['hnsw'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s sparsevec_cosine_ops)'
+    }
+};
+/**
+ * X7: a search column with no index the search can use.
+ *
+ * A `tsvector` or `vector` column is exposed as a search field by
+ * `graphile-search` purely from its type — the schema promises a fast path.
+ * Without a GIN/GiST (full-text) or HNSW/IVFFlat (vector) index the promise
+ * is served by a sequential scan plus a per-row distance or match computation,
+ * which is the single worst plan the API can produce.
+ */
+function checkUnindexedSearchColumns(table) {
+    if (table.isPartition)
+        return [];
+    const findings = [];
+    for (const column of table.columns) {
+        const spec = SEARCH_TYPES[column.baseType];
+        if (!spec)
+            continue;
+        const served = table.indexes.some((idx) => spec.methods.includes(idx.method) && idx.columns.includes(column.attnum));
+        if (served)
+            continue;
+        findings.push({
+            code: 'X7',
+            severity: 'medium',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `${table.schema}.${table.name}.${column.name} is a ${column.type} column with no ${spec.methods.join('/')} index — ${spec.feature} scans the whole table`,
+            hint: `CREATE INDEX ON ${table.schema}.${table.name} ${spec.example.replace('%s', column.name)};`,
+            context: { column: column.name, type: column.type, methods: spec.methods }
+        });
+    }
+    return findings;
+}
+/** Types whose columns are, in practice, what a connection is sorted by. */
+const SORT_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
+/**
+ * X8: a sort-shaped column that leads no index.
+ *
+ * Every PostGraphile connection can be ordered by any column and paginated
+ * with a cursor over that order. Sorting on an unindexed column forces a full
+ * sort of the (RLS-filtered) result on every page, and keyset pagination
+ * degenerates into a scan-and-discard. Timestamp columns are singled out
+ * because they are what feeds are actually ordered by — a heuristic, hence
+ * `info` by default; turn it off with `perf.rules: { "X8": "off" }`.
+ */
+function checkUnindexedSortColumns(table) {
+    if (table.isPartition)
+        return [];
+    // A leading column can serve both ASC and DESC ordering; a trailing one
+    // cannot serve the sort on its own.
+    const leading = new Set(table.indexes.filter((i) => !i.partial).map((i) => i.columns[0]).filter((c) => c !== undefined));
+    const findings = [];
+    for (const column of table.columns) {
+        if (!SORT_TYPES.has(column.baseType))
+            continue;
+        if (leading.has(column.attnum))
+            continue;
+        findings.push({
+            code: 'X8',
+            severity: 'info',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `${table.schema}.${table.name}.${column.name} (${column.type}) leads no index — ordering or paginating a connection by it sorts the whole table`,
+            hint: `If the API orders by this column, CREATE INDEX ON ${table.schema}.${table.name} (${column.name} DESC); otherwise disable X8 or add the table to perf.ignore.`,
+            context: { column: column.name, type: column.type }
+        });
+    }
+    return findings;
+}
 /**
  * True when `index` can serve an equality lookup on exactly `columns`:
  * its leading columns are that same set, and it covers every row.

package/checks/stats.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime-statistics checks (`--stats`, `S*`).
+ *
+ * These read the cumulative statistics views rather than the catalog, so
+ * unlike the `X*` rules they describe a workload rather than a schema: the
+ * same database can pass or fail depending on what traffic it has served.
+ * Every rule therefore takes a floor, so a cold or freshly-reset database
+ * produces silence instead of noise.
+ */
+import type { StatementUsage, StatsSnapshot, TableUsage } from '../pg/stats';
+import type { Finding } from '../types';
+export interface StatsThresholds {
+    /** Ignore tables with fewer live rows than this. Default 1000. */
+    minRows: number;
+    /** S1 fires when seqScans exceed indexScans by this factor. Default 10. */
+    seqScanRatio: number;
+    /** S2 ignores indexes smaller than this many bytes. Default 1 MiB. */
+    minIndexBytes: number;
+    /** S3 fires above this dead/live tuple ratio. Default 0.2. */
+    deadTupleRatio: number;
+    /** S4 fires for statements at or above this share of total time. Default 0.05. */
+    minTimeShare: number;
+    /** S4 reports at most this many statements. Default 5. */
+    topStatements: number;
+}
+export declare const DEFAULT_STATS_THRESHOLDS: StatsThresholds;
+/**
+ * S1: a table the planner reaches by sequential scan far more often than by
+ * index. On a table above the row floor that is a missing index, a policy
+ * predicate the planner can't use, or a query shape nothing covers.
+ */
+export declare function checkSeqScanDominant(table: TableUsage, thresholds: StatsThresholds): Finding | null;
+/**
+ * S2: an index the planner has never chosen. It still costs write throughput,
+ * disk, and vacuum time. Constraint-backed and unique indexes are exempt:
+ * they exist to enforce a constraint, not to be scanned.
+ */
+export declare function checkUnusedIndexes(table: TableUsage, thresholds: StatsThresholds): Finding[];
+/**
+ * S3: dead tuples the vacuum is not keeping up with. Bloat inflates every
+ * scan of the table and every index on it, and the planner's row estimates
+ * drift with it.
+ */
+export declare function checkDeadTuples(table: TableUsage, thresholds: StatsThresholds): Finding | null;
+/**
+ * S4: the statements the database actually spends its time in, restricted to
+ * ones touching a table in scope. This is not a defect — it is the ranked
+ * list to read the other findings against, so it is `info` by default.
+ */
+export declare function checkTopStatements(statements: StatementUsage[], tables: TableUsage[], thresholds: StatsThresholds): Finding[];
+/** Every stats finding for one snapshot. */
+export declare function checkStats(snapshot: StatsSnapshot, thresholds?: StatsThresholds): Finding[];

package/checks/stats.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Runtime-statistics checks (`--stats`, `S*`).
+ *
+ * These read the cumulative statistics views rather than the catalog, so
+ * unlike the `X*` rules they describe a workload rather than a schema: the
+ * same database can pass or fail depending on what traffic it has served.
+ * Every rule therefore takes a floor, so a cold or freshly-reset database
+ * produces silence instead of noise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATS_THRESHOLDS = void 0;
+exports.checkSeqScanDominant = checkSeqScanDominant;
+exports.checkUnusedIndexes = checkUnusedIndexes;
+exports.checkDeadTuples = checkDeadTuples;
+exports.checkTopStatements = checkTopStatements;
+exports.checkStats = checkStats;
+exports.DEFAULT_STATS_THRESHOLDS = {
+    minRows: 1000,
+    seqScanRatio: 10,
+    minIndexBytes: 1024 * 1024,
+    deadTupleRatio: 0.2,
+    minTimeShare: 0.05,
+    topStatements: 5
+};
+/**
+ * S1: a table the planner reaches by sequential scan far more often than by
+ * index. On a table above the row floor that is a missing index, a policy
+ * predicate the planner can't use, or a query shape nothing covers.
+ */
+function checkSeqScanDominant(table, thresholds) {
+    if (table.liveTuples < thresholds.minRows)
+        return null;
+    if (table.seqScans === 0)
+        return null;
+    if (table.seqScans < table.indexScans * thresholds.seqScanRatio)
+        return null;
+    // A table with no index at all is X6/X1 territory; the stats add nothing.
+    if (table.indexes.length === 0)
+        return null;
+    const perScan = Math.round(table.seqTuplesRead / Math.max(table.seqScans, 1));
+    return {
+        code: 'S1',
+        severity: 'medium',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} is scanned sequentially ${table.seqScans} times vs ${table.indexScans} index scans (${table.liveTuples} live rows, ~${perScan} rows read per scan)`,
+        hint: 'Find the query shape behind the scans (pg_stat_statements, auto_explain) and index for it — at this row count every seq scan reads the whole table.',
+        context: {
+            seqScans: table.seqScans,
+            indexScans: table.indexScans,
+            liveTuples: table.liveTuples
+        }
+    };
+}
+/**
+ * S2: an index the planner has never chosen. It still costs write throughput,
+ * disk, and vacuum time. Constraint-backed and unique indexes are exempt:
+ * they exist to enforce a constraint, not to be scanned.
+ */
+function checkUnusedIndexes(table, thresholds) {
+    const findings = [];
+    for (const index of table.indexes) {
+        if (index.scans > 0)
+            continue;
+        if (index.unique || index.constraint)
+            continue;
+        if (index.sizeBytes < thresholds.minIndexBytes)
+            continue;
+        findings.push({
+            code: 'S2',
+            severity: 'low',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Index ${index.name} on ${table.schema}.${table.name} has never been scanned (${formatBytes(index.sizeBytes)})`,
+            hint: `DROP INDEX ${table.schema}.${index.name}; — confirm the counters cover a representative window first (see perf.stats.since).`,
+            context: { index: index.name, sizeBytes: index.sizeBytes }
+        });
+    }
+    return findings;
+}
+/**
+ * S3: dead tuples the vacuum is not keeping up with. Bloat inflates every
+ * scan of the table and every index on it, and the planner's row estimates
+ * drift with it.
+ */
+function checkDeadTuples(table, thresholds) {
+    if (table.liveTuples < thresholds.minRows)
+        return null;
+    const ratio = table.deadTuples / Math.max(table.liveTuples, 1);
+    if (ratio < thresholds.deadTupleRatio)
+        return null;
+    return {
+        code: 'S3',
+        severity: 'low',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} is ${Math.round(ratio * 100)}% dead tuples (${table.deadTuples} dead / ${table.liveTuples} live${table.lastVacuum ? `, last vacuumed ${table.lastVacuum}` : ', never vacuumed'})`,
+        hint: 'VACUUM (ANALYZE) the table, then tune autovacuum for it (autovacuum_vacuum_scale_factor) — bloat is read by every scan and every index on the table.',
+        context: {
+            deadTuples: table.deadTuples,
+            liveTuples: table.liveTuples,
+            lastVacuum: table.lastVacuum
+        }
+    };
+}
+/**
+ * S4: the statements the database actually spends its time in, restricted to
+ * ones touching a table in scope. This is not a defect — it is the ranked
+ * list to read the other findings against, so it is `info` by default.
+ */
+function checkTopStatements(statements, tables, thresholds) {
+    const totalTime = statements.reduce((sum, s) => sum + s.totalTimeMs, 0);
+    if (totalTime <= 0)
+        return [];
+    const findings = [];
+    for (const statement of statements) {
+        if (findings.length >= thresholds.topStatements)
+            break;
+        const share = statement.totalTimeMs / totalTime;
+        if (share < thresholds.minTimeShare)
+            continue;
+        const matched = tables.filter((t) => statementTouches(statement.query, t));
+        if (matched.length === 0)
+            continue;
+        const relations = matched.map((t) => `${t.schema}.${t.name}`);
+        findings.push({
+            code: 'S4',
+            severity: 'info',
+            category: 'index',
+            schema: matched[0].schema,
+            table: matched[0].name,
+            message: `${Math.round(share * 100)}% of database execution time is spent in one statement over ${relations.join(', ')} (${statement.calls} calls, ${Math.round(statement.meanTimeMs)}ms mean)`,
+            hint: `EXPLAIN (ANALYZE, BUFFERS) this statement before acting on any other finding for these tables:\n    ${truncate(statement.query, 300)}`,
+            context: {
+                statement: truncate(statement.query, 300),
+                calls: statement.calls,
+                totalTimeMs: Math.round(statement.totalTimeMs),
+                meanTimeMs: Math.round(statement.meanTimeMs),
+                relations
+            }
+        });
+    }
+    return findings;
+}
+/** Every stats finding for one snapshot. */
+function checkStats(snapshot, thresholds = exports.DEFAULT_STATS_THRESHOLDS) {
+    const findings = [];
+    for (const table of snapshot.tables) {
+        const s1 = checkSeqScanDominant(table, thresholds);
+        if (s1)
+            findings.push(s1);
+        findings.push(...checkUnusedIndexes(table, thresholds));
+        const s3 = checkDeadTuples(table, thresholds);
+        if (s3)
+            findings.push(s3);
+    }
+    if (snapshot.statements) {
+        findings.push(...checkTopStatements(snapshot.statements, snapshot.tables, thresholds));
+    }
+    return findings;
+}
+/**
+ * Whether a normalised statement references a table. `pg_stat_statements`
+ * stores text, not parsed relations, so this matches the qualified name or
+ * the bare name on a word boundary — good enough to rank hotspots, and
+ * deliberately not used for anything that changes a severity.
+ */
+function statementTouches(query, table) {
+    const qualified = new RegExp(`\\b${escapeRegExp(table.schema)}\\.${escapeRegExp(table.name)}\\b`, 'i');
+    if (qualified.test(query))
+        return true;
+    const bare = new RegExp(`\\b(from|join|into|update)\\s+"?${escapeRegExp(table.name)}"?\\b`, 'i');
+    return bare.test(query);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function truncate(value, max) {
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GiB`;
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+    return `${Math.round(bytes / 1024)} KiB`;
+}

package/cli/audit.js

@@ -40,7 +40,9 @@ const audit_1 = require("../commands/audit");
 const loader_1 = require("../config/loader");
 const baseline_2 = require("../perf/baseline");
 const json_1 = require("../report/json");
+const markdown_1 = require("../report/markdown");
 const pretty_1 = require("../report/pretty");
+const sarif_1 = require("../report/sarif");
 const score_1 = require("../score/score");
 const types_1 = require("../types");
 const shared_1 = require("./shared");
@@ -90,7 +92,7 @@ Exposure (what the score is computed against):
   --exposed-only           Hide internal (non-exposed) findings from output
 
 Performance dimension (optional; scored separately from security):
-  --perf                   Also audit index hygiene (X1/X5/X6), policy-aware
+  --perf                   Also audit index hygiene (X1/X5/X6/X7/X8), policy-aware
                            index coverage (X2/X3/X4) and policy cost (P1/P1b),
                            scored on its own 0-100 axis (report.perf)
   --fail-on-perf-score <n> Exit non-zero if the perf score is below n (0-100)
@@ -101,6 +103,15 @@ Performance dimension (optional; scored separately from security):
   --perf-baseline <file>   Diff perf findings against a committed baseline and
                            report only NEW debt (implies --perf)
   --fail-on-new-perf       Exit non-zero when --perf-baseline finds new debt
+  --stats                  Also run the runtime-statistics rules (S1-S4) from
+                           pg_stat_user_tables and, when installed,
+                           pg_stat_statements (implies --perf). Workload-
+                           dependent: only meaningful against a database that
+                           has served representative traffic
+  --explain                Prove each probeable perf finding with
+                           EXPLAIN (GENERIC_PLAN) and attach the plan as
+                           evidence; findings the planner refutes are reported
+                           but unscored (implies --perf, needs PostgreSQL 16+)
 
 Call graph (unscored; human review):
   --call-graph             Analyze the functions reachable from the exposed entry
@@ -118,7 +129,12 @@ Audit options:
   --exclude-schemas <csv>  Skip these schemas
   --roles <csv>            Audit grants only for these roles (default: all)
   --exclude-roles <csv>    Skip grants for these roles
-  --format <fmt>           "pretty" (default) | "json" | "json-pretty"
+  --format <fmt>           "pretty" (default) | "json" | "json-pretty" | "markdown" | "sarif"
+                           (markdown is for CI: a GitHub job summary or PR comment;
+                           sarif uploads to GitHub code scanning)
+  --sarif-sources <dir>    With --format sarif: scan <dir> for the CREATE TABLE /
+                           CREATE POLICY that defines each object, so alerts point
+                           at the SQL that produced the finding
   --summary, -q            Print only exposure, score, and severity counts (no findings)
   --verbose                Expand internal (non-exposed) advisories (listed as a count otherwise)
   --fail-on <severity>     Exit non-zero if any finding >= severity
@@ -150,6 +166,8 @@ exports.default = async (argv, _prompter, _options) => {
             || typeof argv['write-perf-baseline'] === 'string'
             ? true
             : undefined,
+        stats: argv.stats === true ? true : undefined,
+        explain: argv.explain === true ? true : undefined,
         callGraph: argv['call-graph'] === true
             || typeof argv.baseline === 'string'
             || typeof argv['write-baseline'] === 'string',
@@ -216,6 +234,20 @@ exports.default = async (argv, _prompter, _options) => {
         case 'json-pretty':
             output = (0, json_1.renderJson)(report, { pretty: true });
             break;
+        case 'sarif':
+            output = (0, sarif_1.renderSarif)(report, {
+                sources: typeof argv['sarif-sources'] === 'string'
+                    ? (0, sarif_1.buildSourceIndex)(argv['sarif-sources'])
+                    : undefined
+            });
+            break;
+        case 'markdown':
+        case 'md':
+            output = (0, markdown_1.renderMarkdown)(report, {
+                summary: argv.summary === true,
+                verbose: argv.verbose === true
+            });
+            break;
         case 'pretty':
             output = (0, pretty_1.renderPretty)(report, {
                 color: colorEnabled,

package/commands/audit.d.ts

@@ -33,6 +33,17 @@ export interface AuditOptions extends IntrospectOptions {
      * `report.perf` with its own score. Overrides `config.perf.enabled`.
      */
     perf?: boolean;
+    /**
+     * Collect runtime statistics (`pg_stat_user_tables`, `pg_stat_statements`)
+     * and run the `S*` rules. Implies `perf`. Overrides `config.perf.stats.enabled`.
+     */
+    stats?: boolean;
+    /**
+     * Probe perf findings with `EXPLAIN (GENERIC_PLAN)` and attach the plan as
+     * evidence, acknowledging findings the planner refutes. Implies `perf`.
+     * Overrides `config.perf.explain.enabled`.
+     */
+    explain?: boolean;
     /**
      * Merged safegres configuration (rules, overrides, scoring). Rule settings
      * filter and retune findings; scoring settings drive the report score.