safegres 1.12.0 → 1.13.0

package/README.md

@@ -47,7 +47,7 @@ Pretty output prints the exposure line, score, and the exposed findings. Interna
 | A6 | info | fail-closed | coverage | UPDATE has `USING` but **no `WITH CHECK`** (row-smuggling surface) |
 | A7 | critical | fail-open | anti-pattern | Trivially-permissive **WRITE** policy (INSERT/UPDATE/DELETE/ALL with literal `true`) |
 | A8 | low | fail-open | anti-pattern | Trivially-permissive **SELECT** policy (`USING (true)` — confirm public-read is intended) |
-| P1 | high | neutral | anti-pattern | Policy body calls a **VOLATILE function** (per-row evaluation) |
+| P1 | high | neutral | anti-pattern | Policy body calls a **VOLATILE function** (per-row evaluation) — *scored on the [perf axis](#performance-dimension---perf)* |
 | P5 | high | fail-open | anti-pattern | Policy body references **`session_user`** / `current_user` / `pg_has_role(...)` |
 | R1 | critical | fail-open | anti-pattern | An **untrusted role** (options: `{ roles: [...] }`) holds a write privilege |
 | R2 | high | fail-open | anti-pattern | A permissive write policy applies to an untrusted role or PUBLIC |
@@ -100,6 +100,44 @@ Some open reads are deliberate — pricing tables, reference data, a public user
 - An open read on any *undeclared* table stays a scored finding — even in a `*_public`-named schema. Naming is never treated as intent; the config declaration is.
 - `safegres doctor` warns about stale `public.read` patterns that no longer match any table.
 
+## Performance dimension (`--perf`)
+
+A slow database is a different problem from an unsafe one, so safegres scores them separately: `safegres perf` (or `safegres audit --perf`) adds `report.perf` with its own findings, summary, and 0-100 score. It is **off by default** — a plain `audit` behaves exactly as before, and no perf finding ever touches the security score.
+
+| Code | Severity | Category | Check |
+| --- | --- | --- | --- |
+| X1 | medium | index | **Foreign key with no covering index** — joins and cascading deletes seq-scan the child table |
+| X2 | medium | index | **RLS policy filters on an unindexed column** — the security qual seq-scans on every query against the table |
+| X3 | medium | index | **Policy casts or wraps its own column** (`tenant_id::text = …`, `lower(email) = …`) with no matching expression index |
+| 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 |
+| 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.
+
+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
+safegres perf --database mydb
+safegres audit --database mydb --perf --fail-on-perf-grade B
+```
+
+```jsonc
+{
+  "perf": {
+    "enabled": true,
+    "rules": { "X6": "off" },          // perf-dimension codes only
+    "ignore": ["app_public.audit_*"],  // declared-intentional perf debt
+    "scoring": { "densityK": 0.17 }
+  },
+  "failOn": { "perfGrade": "B" }
+}
+```
+
+Tables matched by `perf.ignore` are acknowledged — reported as info, excluded from the perf score — the same way `public.read` works for open reads. Perf findings live in `report.findings` alongside the security ones (so `--fail-on <severity>` still sees them), but only they feed `report.perf.score`, and only security findings feed `report.score`.
+
 ## 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

@@ -0,0 +1,38 @@
+/**
+ * Structural index-hygiene checks (perf dimension, `X*`).
+ *
+ * Everything here is pure catalog analysis — deterministic, workload-free,
+ * and safe to run in CI against an empty database.
+ */
+import type { TableIndexSnapshot } from '../pg/indexes';
+import type { Finding } from '../types';
+/**
+ * X1: a foreign key with no index that can serve it.
+ *
+ * An index covers a FK when its *leading* columns are exactly the FK's
+ * columns (order among them is irrelevant for equality lookups) and it
+ * covers every row. Without one, `ON DELETE`/`ON UPDATE` checks on the
+ * referenced side and joins on the referencing side degrade to sequential
+ * scans.
+ *
+ * Partial and expression indexes do not count: the planner cannot rely on
+ * them for the referential-integrity lookup.
+ */
+export declare function checkUnindexedForeignKeys(table: TableIndexSnapshot): Finding[];
+/**
+ * X5: an index that another index already serves.
+ *
+ * Two shapes: an exact duplicate, or a non-unique index whose columns are a
+ * leading-column prefix of a wider index. Both cost write throughput and
+ * disk for nothing. Constraint-backed indexes (PK/UNIQUE/EXCLUDE) are never
+ * reported — dropping them would drop the constraint.
+ */
+export declare function checkRedundantIndexes(table: TableIndexSnapshot): Finding[];
+/**
+ * X6: no primary key and no usable replica identity.
+ *
+ * Rows cannot be addressed individually: updates and deletes have no cheap
+ * lookup path, logical replication and CDC cannot identify old rows, and
+ * realtime/change-feed features break.
+ */
+export declare function checkMissingPrimaryKey(table: TableIndexSnapshot): Finding | null;

package/checks/indexes.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Structural index-hygiene checks (perf dimension, `X*`).
+ *
+ * Everything here is pure catalog analysis — deterministic, workload-free,
+ * and safe to run in CI against an empty database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUnindexedForeignKeys = checkUnindexedForeignKeys;
+exports.checkRedundantIndexes = checkRedundantIndexes;
+exports.checkMissingPrimaryKey = checkMissingPrimaryKey;
+/**
+ * X1: a foreign key with no index that can serve it.
+ *
+ * An index covers a FK when its *leading* columns are exactly the FK's
+ * columns (order among them is irrelevant for equality lookups) and it
+ * covers every row. Without one, `ON DELETE`/`ON UPDATE` checks on the
+ * referenced side and joins on the referencing side degrade to sequential
+ * scans.
+ *
+ * Partial and expression indexes do not count: the planner cannot rely on
+ * them for the referential-integrity lookup.
+ */
+function checkUnindexedForeignKeys(table) {
+    // Partitions inherit their parent's indexes; the parent carries the finding.
+    if (table.isPartition)
+        return [];
+    const findings = [];
+    for (const fk of table.foreignKeys) {
+        if (fk.columns.length === 0)
+            continue;
+        if (table.indexes.some((idx) => indexCoversColumns(idx, fk.columns)))
+            continue;
+        const cols = fk.columnNames.join(', ');
+        findings.push({
+            code: 'X1',
+            severity: 'medium',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Foreign key ${fk.name} on ${table.schema}.${table.name} (${cols}) has no covering index`,
+            hint: `CREATE INDEX ON ${table.schema}.${table.name} (${cols}); without it, deletes/updates on ${fk.references} and joins across this key scan the whole table.`,
+            context: { constraint: fk.name, columns: fk.columnNames, references: fk.references }
+        });
+    }
+    return findings;
+}
+/**
+ * X5: an index that another index already serves.
+ *
+ * Two shapes: an exact duplicate, or a non-unique index whose columns are a
+ * leading-column prefix of a wider index. Both cost write throughput and
+ * disk for nothing. Constraint-backed indexes (PK/UNIQUE/EXCLUDE) are never
+ * reported — dropping them would drop the constraint.
+ */
+function checkRedundantIndexes(table) {
+    const findings = [];
+    const candidates = table.indexes.filter((i) => !i.primary && !i.constraint && !i.partial && !i.expression && !i.unique);
+    for (const idx of candidates) {
+        const covering = table.indexes.find((other) => {
+            if (other.name === idx.name)
+                return false;
+            if (other.partial || other.expression)
+                return false;
+            if (other.method !== idx.method)
+                return false;
+            if (!isPrefix(idx.columns, other.columns))
+                return false;
+            // Exact duplicates: report only one of the pair, deterministically.
+            if (idx.columns.length === other.columns.length && idx.name < other.name)
+                return false;
+            return true;
+        });
+        if (!covering)
+            continue;
+        const duplicate = idx.columns.length === covering.columns.length;
+        findings.push({
+            code: 'X5',
+            severity: 'low',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Index ${idx.name} (${idx.columnNames.join(', ')}) is ${duplicate ? 'a duplicate of' : 'a leading-column prefix of'} `
+                + `${covering.name} (${covering.columnNames.join(', ')})`,
+            hint: `DROP INDEX ${table.schema}.${idx.name}; every query it serves is served by ${covering.name}.`,
+            context: { index: idx.name, coveredBy: covering.name, duplicate }
+        });
+    }
+    return findings;
+}
+/**
+ * X6: no primary key and no usable replica identity.
+ *
+ * Rows cannot be addressed individually: updates and deletes have no cheap
+ * lookup path, logical replication and CDC cannot identify old rows, and
+ * realtime/change-feed features break.
+ */
+function checkMissingPrimaryKey(table) {
+    if (table.isPartition)
+        return null;
+    if (table.hasPrimaryKey)
+        return null;
+    // `f` (FULL) and `i` (index) still give logical decoding an identity.
+    if (table.replicaIdentity === 'f' || table.replicaIdentity === 'i')
+        return null;
+    return {
+        code: 'X6',
+        severity: 'low',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} has no primary key`,
+        hint: 'Add a primary key, or set REPLICA IDENTITY FULL / USING INDEX, so rows can be addressed by updates, deletes, and logical replication.',
+        context: { replicaIdentity: table.replicaIdentity }
+    };
+}
+/**
+ * True when `index` can serve an equality lookup on exactly `columns`:
+ * its leading columns are that same set, and it covers every row.
+ */
+function indexCoversColumns(index, columns) {
+    if (index.partial || index.expression)
+        return false;
+    if (index.method !== 'btree')
+        return false;
+    if (index.columns.length < columns.length)
+        return false;
+    const leading = new Set(index.columns.slice(0, columns.length));
+    return columns.every((c) => leading.has(c));
+}
+/** True when `a` is a leading-column prefix of `b` (`a` may equal `b`). */
+function isPrefix(a, b) {
+    if (a.length > b.length)
+        return false;
+    return a.every((col, i) => b[i] === col);
+}

package/checks/policy-index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Policy-aware performance checks (X2/X3/X4).
+ *
+ * These are the checks a generic index linter can't make: they read the RLS
+ * policy predicate and ask whether the *security* qual — the one Postgres
+ * evaluates first, on every candidate row, for every query against the table —
+ * can actually use an index.
+ *
+ * All three are static (catalog + AST only); no runtime statistics, no EXPLAIN.
+ */
+import type { PgAstNode } from '../ast/parse';
+import type { TableIndexSnapshot } from '../pg/indexes';
+import type { TableSnapshot } from '../pg/introspect';
+import type { ProcVolatility } from '../pg/proc';
+import type { Finding } from '../types';
+export type PolicyClause = 'USING' | 'WITH CHECK';
+/** A column of the policy's own table, as referenced by the policy predicate. */
+export interface PredicateColumn {
+    column: string;
+    clause: PolicyClause;
+    /**
+     * The cast type or function name wrapping the column reference, if any.
+     * `undefined` means the column is compared directly (index-usable).
+     */
+    wrappedBy?: string;
+    /** True when `wrappedBy` is a cast rather than a function call. */
+    isCast?: boolean;
+}
+/**
+ * Collect the policy's own columns that participate in a comparison, along
+ * with any cast/function wrapping them.
+ *
+ * Only single-part column references (`tenant_id`) and references qualified
+ * with the table's own name/alias (`posts.tenant_id`) count — a column from a
+ * subquery's table belongs to that table's policies, not this one.
+ */
+export declare function collectPredicateColumns(expr: PgAstNode, clause: PolicyClause, tableName: string): PredicateColumn[];
+/**
+ * X2: a policy predicate compares a column that has no index with that column
+ * in the leading position, so the security qual degrades to a sequential scan
+ * on every query touching the table.
+ */
+export declare function checkUnindexedPolicyColumns(table: TableSnapshot, indexes: TableIndexSnapshot, columns: Map<string, PredicateColumn[]>): Finding[];
+/**
+ * X3: the policy wraps its own column in a cast or function call
+ * (`tenant_id::text = ...`, `lower(email) = ...`). A plain b-tree index on the
+ * bare column can't serve that comparison — it needs a matching expression
+ * index, or the cast should move to the other side of the operator.
+ */
+export declare function checkPolicyColumnCasts(table: TableSnapshot, indexes: TableIndexSnapshot, columns: Map<string, PredicateColumn[]>): Finding[];
+/**
+ * X4: the policy predicate calls a non-LEAKPROOF function.
+ *
+ * Postgres assigns security quals a lower security level than user quals and
+ * will not push a non-leakproof qual below a join or subquery scan. The
+ * practical effect is that the policy filter is applied later and to more rows
+ * than necessary, and index scans on the underlying relation are given up.
+ *
+ * System functions are exempt: their leakproofness is a fixed property of the
+ * server, not something the schema author chose.
+ */
+export declare function checkNonLeakproofPolicyFunctions(table: TableSnapshot, expr: PgAstNode, volatility: Map<string, ProcVolatility>, policyName: string): Finding[];

package/checks/policy-index.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Policy-aware performance checks (X2/X3/X4).
+ *
+ * These are the checks a generic index linter can't make: they read the RLS
+ * policy predicate and ask whether the *security* qual — the one Postgres
+ * evaluates first, on every candidate row, for every query against the table —
+ * can actually use an index.
+ *
+ * All three are static (catalog + AST only); no runtime statistics, no EXPLAIN.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectPredicateColumns = collectPredicateColumns;
+exports.checkUnindexedPolicyColumns = checkUnindexedPolicyColumns;
+exports.checkPolicyColumnCasts = checkPolicyColumnCasts;
+exports.checkNonLeakproofPolicyFunctions = checkNonLeakproofPolicyFunctions;
+const traverse_1 = require("@pgsql/traverse");
+const walk_1 = require("../ast/walk");
+/**
+ * Comparison-ish nodes worth indexing for. We deliberately ignore `IS NULL`,
+ * boolean tests and the like: an index rarely helps there, so flagging them
+ * would be noise.
+ */
+const COMPARISON_TAGS = new Set(['A_Expr', 'SubLink', 'NullTest', 'ScalarArrayOpExpr']);
+/**
+ * Collect the policy's own columns that participate in a comparison, along
+ * with any cast/function wrapping them.
+ *
+ * Only single-part column references (`tenant_id`) and references qualified
+ * with the table's own name/alias (`posts.tenant_id`) count — a column from a
+ * subquery's table belongs to that table's policies, not this one.
+ */
+function collectPredicateColumns(expr, clause, tableName) {
+    const out = [];
+    const seen = new Set();
+    (0, traverse_1.walk)(expr, (path) => {
+        if (path.tag !== 'ColumnRef')
+            return;
+        const parts = (0, walk_1.columnRefPath)(path.node);
+        const column = ownColumnName(parts, tableName);
+        if (!column)
+            return;
+        const { wrappedBy, isCast } = wrappingOf(path);
+        if (!inComparison(path))
+            return;
+        const key = `${clause}:${column}:${wrappedBy ?? ''}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ column, clause, wrappedBy, isCast });
+    });
+    return out;
+}
+/**
+ * X2: a policy predicate compares a column that has no index with that column
+ * in the leading position, so the security qual degrades to a sequential scan
+ * on every query touching the table.
+ */
+function checkUnindexedPolicyColumns(table, indexes, columns) {
+    const out = [];
+    const leading = leadingColumns(indexes);
+    for (const [policyName, cols] of columns) {
+        const reported = new Set();
+        for (const col of cols) {
+            // A wrapped column is X3's business — the raw column being indexed
+            // wouldn't help the wrapped comparison anyway.
+            if (col.wrappedBy)
+                continue;
+            if (leading.has(col.column))
+                continue;
+            if (reported.has(col.column))
+                continue;
+            reported.add(col.column);
+            out.push({
+                code: 'X2',
+                severity: 'medium',
+                category: 'index',
+                schema: table.schema,
+                table: table.name,
+                policy: policyName,
+                message: `Policy "${policyName}" on ${table.schema}.${table.name} filters by ${col.column}, which is not the leading column of any index`,
+                hint: `RLS quals run before user quals on every row the planner considers, so an unindexed policy column forces a sequential scan for all callers. CREATE INDEX ON ${table.schema}.${table.name} (${col.column}).`,
+                context: { column: col.column, clause: col.clause }
+            });
+        }
+    }
+    return out;
+}
+/**
+ * X3: the policy wraps its own column in a cast or function call
+ * (`tenant_id::text = ...`, `lower(email) = ...`). A plain b-tree index on the
+ * bare column can't serve that comparison — it needs a matching expression
+ * index, or the cast should move to the other side of the operator.
+ */
+function checkPolicyColumnCasts(table, indexes, columns) {
+    const out = [];
+    const expressionDefs = indexes.indexes
+        .filter((i) => i.expression)
+        .map((i) => i.definition.toLowerCase());
+    for (const [policyName, cols] of columns) {
+        const reported = new Set();
+        for (const col of cols) {
+            if (!col.wrappedBy)
+                continue;
+            const key = `${col.column}:${col.wrappedBy}`;
+            if (reported.has(key))
+                continue;
+            reported.add(key);
+            if (expressionDefs.some((def) => defCovers(def, col)))
+                continue;
+            const shape = col.isCast
+                ? `${col.column}::${col.wrappedBy}`
+                : `${col.wrappedBy}(${col.column})`;
+            out.push({
+                code: 'X3',
+                severity: 'medium',
+                category: 'index',
+                schema: table.schema,
+                table: table.name,
+                policy: policyName,
+                message: `Policy "${policyName}" on ${table.schema}.${table.name} compares ${shape} — a plain index on ${col.column} cannot serve this`,
+                hint: col.isCast
+                    ? `Cast the other side of the comparison instead, or add a matching expression index: CREATE INDEX ON ${table.schema}.${table.name} ((${shape})).`
+                    : `Add a matching expression index: CREATE INDEX ON ${table.schema}.${table.name} ((${shape})).`,
+                context: { column: col.column, expression: shape, clause: col.clause }
+            });
+        }
+    }
+    return out;
+}
+/**
+ * X4: the policy predicate calls a non-LEAKPROOF function.
+ *
+ * Postgres assigns security quals a lower security level than user quals and
+ * will not push a non-leakproof qual below a join or subquery scan. The
+ * practical effect is that the policy filter is applied later and to more rows
+ * than necessary, and index scans on the underlying relation are given up.
+ *
+ * System functions are exempt: their leakproofness is a fixed property of the
+ * server, not something the schema author chose.
+ */
+function checkNonLeakproofPolicyFunctions(table, expr, volatility, policyName) {
+    const out = [];
+    const seen = new Set();
+    (0, traverse_1.walk)(expr, (path) => {
+        if (path.tag !== 'FuncCall')
+            return;
+        const qualified = (0, walk_1.funcNameQualified)(path.node);
+        const bare = qualified.split('.').pop() ?? qualified;
+        const info = volatility.get(qualified) ?? volatility.get(bare);
+        if (!info)
+            return;
+        if (info.isSystem)
+            return;
+        if (info.isLeakproof)
+            return;
+        if (seen.has(info.name))
+            return;
+        seen.add(info.name);
+        out.push({
+            code: 'X4',
+            severity: 'low',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            policy: policyName,
+            message: `Policy "${policyName}" on ${table.schema}.${table.name} calls non-LEAKPROOF function ${info.name}`,
+            hint: 'Non-leakproof quals cannot be pushed below joins or subquery scans, so the policy filter is applied late and to more rows than necessary. If the function provably leaks nothing about its arguments (no error messages containing values), mark it LEAKPROOF.',
+            context: { function: info.name }
+        });
+    });
+    return out;
+}
+/** Columns that sit in the leading position of at least one index. */
+function leadingColumns(indexes) {
+    const out = new Set();
+    for (const index of indexes.indexes) {
+        const first = index.columnNames[0];
+        if (first)
+            out.add(first);
+    }
+    return out;
+}
+/**
+ * Resolve a column reference to a bare column name on `tableName`, or null if
+ * it belongs to another relation (or is `*`).
+ */
+function ownColumnName(parts, tableName) {
+    if (parts.length === 1)
+        return parts[0] === '*' ? null : parts[0];
+    if (parts.length === 2 && parts[0] === tableName)
+        return parts[1] === '*' ? null : parts[1];
+    return null;
+}
+/** Nearest enclosing cast or function call, if the column is wrapped by one. */
+function wrappingOf(path) {
+    const parent = path.parent;
+    if (!parent)
+        return {};
+    if (parent.tag === 'TypeCast') {
+        const typeName = castTypeName(parent.node);
+        return typeName ? { wrappedBy: typeName, isCast: true } : {};
+    }
+    if (parent.tag === 'FuncCall') {
+        return { wrappedBy: (0, walk_1.funcNameQualified)(parent.node), isCast: false };
+    }
+    return {};
+}
+/** True when the column participates in a comparison rather than, say, a projection. */
+function inComparison(path) {
+    let cursor = path.parent;
+    // Allow one or two wrapping levels (cast, function call) between the column
+    // and the comparison it feeds.
+    for (let depth = 0; cursor && depth < 3; depth++) {
+        if (COMPARISON_TAGS.has(cursor.tag))
+            return true;
+        cursor = cursor.parent;
+    }
+    return false;
+}
+function castTypeName(typeCast) {
+    const typeName = typeCast.typeName;
+    if (!typeName)
+        return null;
+    const names = typeName.names;
+    if (!Array.isArray(names) || names.length === 0)
+        return null;
+    const last = names[names.length - 1];
+    const str = (last.String ?? last.string);
+    if (!str)
+        return null;
+    const value = String((str.sval ?? str.str) ?? '');
+    return value.length > 0 ? value : null;
+}
+/**
+ * Heuristic match of an expression index definition against a wrapped column.
+ * `pg_get_indexdef` renders casts as `((col)::text)` and calls as `lower(col)`,
+ * so requiring both tokens is enough to avoid the common false positive
+ * without parsing the definition back into an AST.
+ */
+function defCovers(definitionLower, col) {
+    const wrapper = (col.wrappedBy ?? '').toLowerCase();
+    const column = col.column.toLowerCase();
+    if (!wrapper)
+        return false;
+    if (col.isCast)
+        return definitionLower.includes(`::${wrapper}`) && definitionLower.includes(column);
+    return definitionLower.includes(`${wrapper}(`) && definitionLower.includes(column);
+}

package/cli/audit.js

@@ -88,6 +88,12 @@ Exposure (what the score is computed against):
                            them become unscored internal advisories
   --exposed-only           Hide internal (non-exposed) findings from output
 
+Performance dimension (optional; scored separately from security):
+  --perf                   Also audit index hygiene (X1/X5/X6) and score it 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)
+  --fail-on-perf-grade <g> Exit non-zero if the perf grade is below g (A+|A|B|C|D)
+
 Call graph (unscored; human review):
   --call-graph             Analyze the functions reachable from the exposed entry
                            points and list trust boundaries: SECURITY DEFINER hops,
@@ -131,6 +137,7 @@ exports.default = async (argv, _prompter, _options) => {
         includeRoles: (0, shared_1.csvList)(argv.roles),
         excludeRoles: (0, shared_1.csvList)(argv['exclude-roles']),
         skipAstChecks: argv['skip-ast'] === true,
+        perf: argv.perf === true ? true : undefined,
         callGraph: argv['call-graph'] === true
             || typeof argv.baseline === 'string'
             || typeof argv['write-baseline'] === 'string',
@@ -215,6 +222,20 @@ exports.default = async (argv, _prompter, _options) => {
         log.error(`grade ${report.score.grade} is below --fail-on-grade ${failOnGrade}`);
         process.exit(1);
     }
+    const failOnPerfScore = typeof argv['fail-on-perf-score'] === 'number'
+        ? argv['fail-on-perf-score']
+        : config.failOn?.perfScore;
+    if (failOnPerfScore != null && report.perf && report.perf.score.value < failOnPerfScore) {
+        log.error(`perf score ${report.perf.score.value} is below --fail-on-perf-score ${failOnPerfScore}`);
+        process.exit(1);
+    }
+    const failOnPerfGrade = typeof argv['fail-on-perf-grade'] === 'string'
+        ? argv['fail-on-perf-grade']
+        : config.failOn?.perfGrade;
+    if (failOnPerfGrade && report.perf && !(0, score_1.meetsGrade)(report.perf.score.grade, failOnPerfGrade)) {
+        log.error(`perf grade ${report.perf.score.grade} is below --fail-on-perf-grade ${failOnPerfGrade}`);
+        process.exit(1);
+    }
     if (argv['fail-on-new-boundaries'] === true
         && report.callGraphDiff
         && report.callGraphDiff.added.length > 0) {

package/cli/commands.js

@@ -18,6 +18,7 @@ Usage:
 
 Commands:
   audit           Audit grants, RLS flags, policy coverage, and anti-patterns
+  perf            Audit index hygiene and policy cost (audit --perf)
   doctor          Diagnose environment, connection, and configuration
   print-config    Show the resolved effective configuration
   help            Show this help message
@@ -26,6 +27,7 @@ Run \`safegres <command> --help\` for command-specific options.
 `;
 const commandMap = {
     audit: audit_1.default,
+    perf: (argv, prompter, options) => (0, audit_1.default)({ ...argv, perf: true }, prompter, options),
     doctor: doctor_1.default,
     'print-config': print_config_1.default
 };

package/commands/audit.d.ts

@@ -27,6 +27,12 @@ export interface AuditOptions extends IntrospectOptions {
      * exposed entry points. Adds `report.callGraph`.
      */
     callGraph?: boolean;
+    /**
+     * Collect and score the performance dimension: index-hygiene rules (`X*`)
+     * on top of the policy-cost rules (P1/P1b) the audit already runs. Adds
+     * `report.perf` with its own score. Overrides `config.perf.enabled`.
+     */
+    perf?: boolean;
     /**
      * Merged safegres configuration (rules, overrides, scoring). Rule settings
      * filter and retune findings; scoring settings drive the report score.