safegres 1.13.0 → 1.14.0

package/README.md

@@ -138,6 +138,26 @@ safegres audit --database mydb --perf --fail-on-perf-grade 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`.
 
+### Perf baseline (the ratchet)
+
+An established schema will not reach a clean perf report in one pass — but it can refuse to get worse. Commit today's findings as accepted debt, then gate CI on findings that are *not* in the baseline:
+
+```bash
+safegres audit --write-perf-baseline .safegres-perf.json          # snapshot (implies --perf)
+safegres audit --perf-baseline .safegres-perf.json                # diff: new vs accepted vs fixed
+safegres audit --perf-baseline .safegres-perf.json --fail-on-new-perf   # gate: exit 1 on new debt
+```
+
+```
+performance vs baseline:
+
+1 new perf finding since the baseline:
+  [medium] X1 app_public.comments — foreign key with no covering index
+  (14 accepted, 2 fixed)
+```
+
+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)`.
+
 ## 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/cli/audit.js

@@ -38,6 +38,7 @@ const fs = __importStar(require("fs"));
 const baseline_1 = require("../callgraph/baseline");
 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 pretty_1 = require("../report/pretty");
 const score_1 = require("../score/score");
@@ -89,10 +90,17 @@ 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) and score it on
-                           its own 0-100 axis (report.perf)
+  --perf                   Also audit index hygiene (X1/X5/X6), 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)
   --fail-on-perf-grade <g> Exit non-zero if the perf grade is below g (A+|A|B|C|D)
+  --write-perf-baseline <file>
+                           Snapshot today's perf findings to <file> as accepted
+                           debt (implies --perf)
+  --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
 
 Call graph (unscored; human review):
   --call-graph             Analyze the functions reachable from the exposed entry
@@ -137,7 +145,11 @@ 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,
+        perf: argv.perf === true
+            || typeof argv['perf-baseline'] === 'string'
+            || typeof argv['write-perf-baseline'] === 'string'
+            ? true
+            : undefined,
         callGraph: argv['call-graph'] === true
             || typeof argv.baseline === 'string'
             || typeof argv['write-baseline'] === 'string',
@@ -165,6 +177,21 @@ exports.default = async (argv, _prompter, _options) => {
         fs.writeFileSync(argv['write-baseline'], (0, baseline_1.serializeBaseline)((0, baseline_1.toBaseline)(report.callGraph)));
         log.info(`wrote call-graph baseline: ${argv['write-baseline']}`);
     }
+    if (typeof argv['write-perf-baseline'] === 'string' && report.perf) {
+        fs.writeFileSync(argv['write-perf-baseline'], (0, baseline_2.serializePerfBaseline)((0, baseline_2.toPerfBaseline)(report.perf.findings)));
+        log.info(`wrote perf baseline: ${argv['write-perf-baseline']}`);
+    }
+    if (typeof argv['perf-baseline'] === 'string' && report.perf) {
+        let raw;
+        try {
+            raw = fs.readFileSync(argv['perf-baseline'], 'utf8');
+        }
+        catch {
+            log.error(`cannot read --perf-baseline file: ${argv['perf-baseline']} (create one with --write-perf-baseline)`);
+            process.exit(2);
+        }
+        report.perf.diff = (0, baseline_2.diffPerf)(report.perf.findings, (0, baseline_2.parsePerfBaseline)(raw));
+    }
     if (typeof argv.baseline === 'string' && report.callGraph) {
         let raw;
         try {
@@ -236,6 +263,11 @@ exports.default = async (argv, _prompter, _options) => {
         log.error(`perf grade ${report.perf.score.grade} is below --fail-on-perf-grade ${failOnPerfGrade}`);
         process.exit(1);
     }
+    if (argv['fail-on-new-perf'] === true && report.perf?.diff && report.perf.diff.added.length > 0) {
+        const count = report.perf.diff.added.length;
+        log.error(`${count} new performance finding${count === 1 ? '' : 's'} since the perf baseline — fix them, or re-baseline with --write-perf-baseline to accept`);
+        process.exit(1);
+    }
     if (argv['fail-on-new-boundaries'] === true
         && report.callGraphDiff
         && report.callGraphDiff.added.length > 0) {

package/esm/cli/audit.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import { diffCallGraph, parseBaseline, serializeBaseline, toBaseline } from '../callgraph/baseline';
 import { audit } from '../commands/audit';
 import { loadConfig } from '../config/loader';
+import { diffPerf, parsePerfBaseline, serializePerfBaseline, toPerfBaseline } from '../perf/baseline';
 import { renderJson } from '../report/json';
 import { renderPretty } from '../report/pretty';
 import { meetsGrade } from '../score/score';
@@ -54,10 +55,17 @@ 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) and score it on
-                           its own 0-100 axis (report.perf)
+  --perf                   Also audit index hygiene (X1/X5/X6), 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)
   --fail-on-perf-grade <g> Exit non-zero if the perf grade is below g (A+|A|B|C|D)
+  --write-perf-baseline <file>
+                           Snapshot today's perf findings to <file> as accepted
+                           debt (implies --perf)
+  --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
 
 Call graph (unscored; human review):
   --call-graph             Analyze the functions reachable from the exposed entry
@@ -102,7 +110,11 @@ export default async (argv, _prompter, _options) => {
         includeRoles: csvList(argv.roles),
         excludeRoles: csvList(argv['exclude-roles']),
         skipAstChecks: argv['skip-ast'] === true,
-        perf: argv.perf === true ? true : undefined,
+        perf: argv.perf === true
+            || typeof argv['perf-baseline'] === 'string'
+            || typeof argv['write-perf-baseline'] === 'string'
+            ? true
+            : undefined,
         callGraph: argv['call-graph'] === true
             || typeof argv.baseline === 'string'
             || typeof argv['write-baseline'] === 'string',
@@ -130,6 +142,21 @@ export default async (argv, _prompter, _options) => {
         fs.writeFileSync(argv['write-baseline'], serializeBaseline(toBaseline(report.callGraph)));
         log.info(`wrote call-graph baseline: ${argv['write-baseline']}`);
     }
+    if (typeof argv['write-perf-baseline'] === 'string' && report.perf) {
+        fs.writeFileSync(argv['write-perf-baseline'], serializePerfBaseline(toPerfBaseline(report.perf.findings)));
+        log.info(`wrote perf baseline: ${argv['write-perf-baseline']}`);
+    }
+    if (typeof argv['perf-baseline'] === 'string' && report.perf) {
+        let raw;
+        try {
+            raw = fs.readFileSync(argv['perf-baseline'], 'utf8');
+        }
+        catch {
+            log.error(`cannot read --perf-baseline file: ${argv['perf-baseline']} (create one with --write-perf-baseline)`);
+            process.exit(2);
+        }
+        report.perf.diff = diffPerf(report.perf.findings, parsePerfBaseline(raw));
+    }
     if (typeof argv.baseline === 'string' && report.callGraph) {
         let raw;
         try {
@@ -201,6 +228,11 @@ export default async (argv, _prompter, _options) => {
         log.error(`perf grade ${report.perf.score.grade} is below --fail-on-perf-grade ${failOnPerfGrade}`);
         process.exit(1);
     }
+    if (argv['fail-on-new-perf'] === true && report.perf?.diff && report.perf.diff.added.length > 0) {
+        const count = report.perf.diff.added.length;
+        log.error(`${count} new performance finding${count === 1 ? '' : 's'} since the perf baseline — fix them, or re-baseline with --write-perf-baseline to accept`);
+        process.exit(1);
+    }
     if (argv['fail-on-new-boundaries'] === true
         && report.callGraphDiff
         && report.callGraphDiff.added.length > 0) {

package/esm/index.d.ts

@@ -33,6 +33,8 @@ export type { ForeignKeyInfo, IndexInfo, TableIndexSnapshot } from './pg/indexes
 export { introspectIndexes } from './pg/indexes';
 export { type IntrospectOptions, introspectTables, type PgPrivilege, type PolicyCmd, type PolicyInfo, type QueryExecutor, type TableSnapshot } from './pg/introspect';
 export { listAuditableRoles, resolveRoles } from './pg/roles';
+export type { BaselineFinding, PerfBaseline, PerfDiff } from './perf/baseline';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
 export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
 export { renderJson } from './report/json';
 export { renderPretty } from './report/pretty';

package/esm/index.js

@@ -21,6 +21,7 @@ export { introspectFunctions } from './pg/functions';
 export { introspectIndexes } from './pg/indexes';
 export { introspectTables } from './pg/introspect';
 export { listAuditableRoles, resolveRoles } from './pg/roles';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
 export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
 export { renderJson } from './report/json';
 export { renderPretty } from './report/pretty';

package/esm/perf/baseline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Perf baseline: a committed snapshot of accepted performance debt.
+ *
+ * The point is the ratchet. A large schema will not reach a clean perf report
+ * in one pass, but it can refuse to get worse: commit the current findings,
+ * then fail CI only on findings that are *not* in the baseline.
+ *
+ * Only the identity of a finding is stored — code, relation, policy, and the
+ * one context field that distinguishes findings of the same code on the same
+ * relation. Messages, severities and hints may be reworded between safegres
+ * versions without invalidating a committed baseline.
+ */
+import type { Finding } from '../types';
+export interface PerfBaseline {
+    version: 1;
+    findings: BaselineFinding[];
+}
+export interface BaselineFinding {
+    code: string;
+    schema?: string;
+    table?: string;
+    policy?: string;
+    /** The rule-specific subject: constraint, index, column, expression, or function. */
+    subject?: string;
+}
+export interface PerfDiff {
+    /** Findings present now but absent from the baseline — new debt. */
+    added: Finding[];
+    /** Baseline entries no longer produced — fixed, or the relation is gone. */
+    removed: BaselineFinding[];
+    /** Findings that matched the baseline — accepted debt, still reported. */
+    accepted: Finding[];
+}
+export declare function subjectOf(finding: Finding): string | undefined;
+export declare function findingKey(entry: BaselineFinding): string;
+export declare function toBaselineFinding(finding: Finding): BaselineFinding;
+export declare function toPerfBaseline(findings: Finding[]): PerfBaseline;
+export declare function diffPerf(findings: Finding[], baseline: PerfBaseline): PerfDiff;
+export declare function parsePerfBaseline(raw: string): PerfBaseline;
+export declare function serializePerfBaseline(baseline: PerfBaseline): string;

package/esm/perf/baseline.js

@@ -0,0 +1,83 @@
+/**
+ * Perf baseline: a committed snapshot of accepted performance debt.
+ *
+ * The point is the ratchet. A large schema will not reach a clean perf report
+ * in one pass, but it can refuse to get worse: commit the current findings,
+ * then fail CI only on findings that are *not* in the baseline.
+ *
+ * Only the identity of a finding is stored — code, relation, policy, and the
+ * one context field that distinguishes findings of the same code on the same
+ * relation. Messages, severities and hints may be reworded between safegres
+ * versions without invalidating a committed baseline.
+ */
+/**
+ * Context keys that identify *which* object a finding is about, in priority
+ * order (X3 carries both `expression` and `column`; the expression is the
+ * narrower identity). Rules that can only fire once per relation — X6 — set
+ * none of these and are keyed by code + relation alone.
+ */
+const SUBJECT_KEYS = ['constraint', 'index', 'expression', 'column', 'function'];
+export function subjectOf(finding) {
+    const context = finding.context;
+    if (!context)
+        return undefined;
+    for (const key of SUBJECT_KEYS) {
+        const value = context[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+export function findingKey(entry) {
+    return [entry.code, entry.schema ?? '', entry.table ?? '', entry.policy ?? '', entry.subject ?? ''].join('|');
+}
+export function toBaselineFinding(finding) {
+    const subject = subjectOf(finding);
+    return {
+        code: finding.code,
+        ...(finding.schema ? { schema: finding.schema } : {}),
+        ...(finding.table ? { table: finding.table } : {}),
+        ...(finding.policy ? { policy: finding.policy } : {}),
+        ...(subject ? { subject } : {})
+    };
+}
+export function toPerfBaseline(findings) {
+    const seen = new Set();
+    const out = [];
+    for (const finding of findings) {
+        const entry = toBaselineFinding(finding);
+        const key = findingKey(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    out.sort((a, b) => findingKey(a).localeCompare(findingKey(b)));
+    return { version: 1, findings: out };
+}
+export function diffPerf(findings, baseline) {
+    const baseKeys = new Set(baseline.findings.map(findingKey));
+    const currentKeys = new Set();
+    const added = [];
+    const accepted = [];
+    for (const finding of findings) {
+        const key = findingKey(toBaselineFinding(finding));
+        currentKeys.add(key);
+        if (baseKeys.has(key))
+            accepted.push(finding);
+        else
+            added.push(finding);
+    }
+    const removed = baseline.findings.filter((entry) => !currentKeys.has(findingKey(entry)));
+    return { added, removed, accepted };
+}
+export function parsePerfBaseline(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== 1 || !Array.isArray(data.findings)) {
+        throw new Error('invalid perf baseline: expected { version: 1, findings: [...] }');
+    }
+    return { version: 1, findings: data.findings };
+}
+export function serializePerfBaseline(baseline) {
+    return JSON.stringify(baseline, null, 2) + '\n';
+}

package/esm/report/pretty.js

@@ -84,6 +84,22 @@ export function renderPretty(report, options = {}) {
     if (security.length === 0) {
         lines.push('no findings.');
     }
+    if (report.perf?.diff) {
+        const { added, removed, accepted } = report.perf.diff;
+        lines.push('', 'performance vs baseline:', '');
+        if (added.length === 0) {
+            lines.push(`no new perf debt (${accepted.length} accepted, ${removed.length} fixed).`);
+        }
+        else {
+            lines.push(paint('high', `${added.length} new perf finding${added.length === 1 ? '' : 's'} since the baseline:`));
+            for (const f of added)
+                lines.push(renderFinding(f, paint));
+            lines.push(paint('info', `  (${accepted.length} accepted, ${removed.length} fixed)`));
+        }
+        if (removed.length > 0) {
+            lines.push(paint('info', `  fixed since the baseline: ${removed.map((r) => `${r.code} ${r.schema}.${r.table}`).join(', ')} — re-baseline to lock the win in`));
+        }
+    }
     if (report.perf) {
         const perfExposed = report.perf.findings.filter((f) => f.exposed !== false);
         const perfInternal = report.perf.findings.length - perfExposed.length;

package/esm/types.d.ts

@@ -90,6 +90,11 @@ export interface PerfReport {
     summary: Summary;
     /** Perf score — computed only over perf-dimension findings. */
     score: import('./score/score').Score;
+    /**
+     * Diff against a committed perf baseline (`--perf-baseline`): which findings
+     * are new debt, which were fixed, which are accepted.
+     */
+    diff?: import('./perf/baseline').PerfDiff;
 }
 export interface Report {
     version: string;

package/index.d.ts

@@ -33,6 +33,8 @@ export type { ForeignKeyInfo, IndexInfo, TableIndexSnapshot } from './pg/indexes
 export { introspectIndexes } from './pg/indexes';
 export { type IntrospectOptions, introspectTables, type PgPrivilege, type PolicyCmd, type PolicyInfo, type QueryExecutor, type TableSnapshot } from './pg/introspect';
 export { listAuditableRoles, resolveRoles } from './pg/roles';
+export type { BaselineFinding, PerfBaseline, PerfDiff } from './perf/baseline';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
 export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
 export { renderJson } from './report/json';
 export { renderPretty } from './report/pretty';

package/index.js

@@ -21,8 +21,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isKnownRule = exports.expandRuleSelector = exports.dimensionOf = exports.renderPretty = exports.renderJson = exports.renderCallGraphDiff = exports.renderCallGraph = exports.resolveRoles = exports.listAuditableRoles = exports.introspectTables = exports.introspectIndexes = exports.introspectFunctions = exports.UNKNOWN_EXPOSURE = exports.resolveExposure = exports.resolveConstructiveExposure = exports.rulesForTable = exports.ruleCodesForDimension = exports.resolveRules = exports.matchTablePattern = exports.defaultRuleMap = exports.ConfigValidationError = exports.applyRulesToFindings = exports.allAstRulesDisabled = exports.strict = exports.recommended = exports.PRESETS = exports.minimal = exports.constructive = exports.safegresConfigLoader = exports.loadConfig = exports.doctor = exports.audit = exports.checkUntrustedRoleWrites = exports.checkUntrustedRolePolicies = exports.checkPublicGrants = exports.collectPredicateColumns = exports.checkUnindexedPolicyColumns = exports.checkPolicyColumnCasts = exports.checkNonLeakproofPolicyFunctions = exports.checkUnindexedForeignKeys = exports.checkRedundantIndexes = exports.checkMissingPrimaryKey = exports.buildCallGraph = exports.toBaseline = exports.serializeBaseline = exports.parseBaseline = exports.diffCallGraph = exports.boundaryKey = exports.PolicyParseError = exports.parsePolicyExpression = void 0;
-exports.meetsGrade = exports.DEFAULT_WEIGHTS = exports.DEFAULT_GRADE_BANDS = exports.computeScore = exports.RULES_BY_CODE = exports.RULES = void 0;
+exports.toPerfBaseline = exports.toBaselineFinding = exports.subjectOf = exports.serializePerfBaseline = exports.parsePerfBaseline = exports.findingKey = exports.diffPerf = exports.resolveRoles = exports.listAuditableRoles = exports.introspectTables = exports.introspectIndexes = exports.introspectFunctions = exports.UNKNOWN_EXPOSURE = exports.resolveExposure = exports.resolveConstructiveExposure = exports.rulesForTable = exports.ruleCodesForDimension = exports.resolveRules = exports.matchTablePattern = exports.defaultRuleMap = exports.ConfigValidationError = exports.applyRulesToFindings = exports.allAstRulesDisabled = exports.strict = exports.recommended = exports.PRESETS = exports.minimal = exports.constructive = exports.safegresConfigLoader = exports.loadConfig = exports.doctor = exports.audit = exports.checkUntrustedRoleWrites = exports.checkUntrustedRolePolicies = exports.checkPublicGrants = exports.collectPredicateColumns = exports.checkUnindexedPolicyColumns = exports.checkPolicyColumnCasts = exports.checkNonLeakproofPolicyFunctions = exports.checkUnindexedForeignKeys = exports.checkRedundantIndexes = exports.checkMissingPrimaryKey = exports.buildCallGraph = exports.toBaseline = exports.serializeBaseline = exports.parseBaseline = exports.diffCallGraph = exports.boundaryKey = exports.PolicyParseError = exports.parsePolicyExpression = void 0;
+exports.meetsGrade = exports.DEFAULT_WEIGHTS = exports.DEFAULT_GRADE_BANDS = exports.computeScore = exports.RULES_BY_CODE = exports.RULES = exports.isKnownRule = exports.expandRuleSelector = exports.dimensionOf = exports.renderPretty = exports.renderJson = exports.renderCallGraphDiff = exports.renderCallGraph = void 0;
 var parse_1 = require("./ast/parse");
 Object.defineProperty(exports, "parsePolicyExpression", { enumerable: true, get: function () { return parse_1.parsePolicyExpression; } });
 Object.defineProperty(exports, "PolicyParseError", { enumerable: true, get: function () { return parse_1.PolicyParseError; } });
@@ -82,6 +82,14 @@ Object.defineProperty(exports, "introspectTables", { enumerable: true, get: func
 var roles_1 = require("./pg/roles");
 Object.defineProperty(exports, "listAuditableRoles", { enumerable: true, get: function () { return roles_1.listAuditableRoles; } });
 Object.defineProperty(exports, "resolveRoles", { enumerable: true, get: function () { return roles_1.resolveRoles; } });
+var baseline_2 = require("./perf/baseline");
+Object.defineProperty(exports, "diffPerf", { enumerable: true, get: function () { return baseline_2.diffPerf; } });
+Object.defineProperty(exports, "findingKey", { enumerable: true, get: function () { return baseline_2.findingKey; } });
+Object.defineProperty(exports, "parsePerfBaseline", { enumerable: true, get: function () { return baseline_2.parsePerfBaseline; } });
+Object.defineProperty(exports, "serializePerfBaseline", { enumerable: true, get: function () { return baseline_2.serializePerfBaseline; } });
+Object.defineProperty(exports, "subjectOf", { enumerable: true, get: function () { return baseline_2.subjectOf; } });
+Object.defineProperty(exports, "toBaselineFinding", { enumerable: true, get: function () { return baseline_2.toBaselineFinding; } });
+Object.defineProperty(exports, "toPerfBaseline", { enumerable: true, get: function () { return baseline_2.toPerfBaseline; } });
 var callgraph_1 = require("./report/callgraph");
 Object.defineProperty(exports, "renderCallGraph", { enumerable: true, get: function () { return callgraph_1.renderCallGraph; } });
 Object.defineProperty(exports, "renderCallGraphDiff", { enumerable: true, get: function () { return callgraph_1.renderCallGraphDiff; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safegres",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Pure-Postgres Row-Level Security auditor: grants, RLS enforcement, policy coverage, and risky SQL policy patterns, plus an optional index-hygiene performance score. No app framework required.",
   "main": "index.js",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@inquirerer/utils": "^3.3.9",
     "@pgpmjs/logger": "^2.23.0",
-    "@pgsql/traverse": "^18.1.0",
+    "@pgsql/traverse": "^18.4.0",
     "@pgsql/types": "^18.0.0",
     "confstash": "^0.1.0",
     "inquirerer": "^4.9.1",
@@ -68,7 +68,7 @@
     "@types/node": "^22.0.0",
     "@types/pg": "^8.20.0",
     "makage": "^0.3.0",
-    "pgsql-test": "^5.9.1"
+    "pgsql-test": "^5.9.2"
   },
-  "gitHead": "6c59df639625959f2db55ee1c6a3768c580045f0"
+  "gitHead": "a1e9ab2788365ab377102d3952f16b4b529a89a1"
 }

package/perf/baseline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Perf baseline: a committed snapshot of accepted performance debt.
+ *
+ * The point is the ratchet. A large schema will not reach a clean perf report
+ * in one pass, but it can refuse to get worse: commit the current findings,
+ * then fail CI only on findings that are *not* in the baseline.
+ *
+ * Only the identity of a finding is stored — code, relation, policy, and the
+ * one context field that distinguishes findings of the same code on the same
+ * relation. Messages, severities and hints may be reworded between safegres
+ * versions without invalidating a committed baseline.
+ */
+import type { Finding } from '../types';
+export interface PerfBaseline {
+    version: 1;
+    findings: BaselineFinding[];
+}
+export interface BaselineFinding {
+    code: string;
+    schema?: string;
+    table?: string;
+    policy?: string;
+    /** The rule-specific subject: constraint, index, column, expression, or function. */
+    subject?: string;
+}
+export interface PerfDiff {
+    /** Findings present now but absent from the baseline — new debt. */
+    added: Finding[];
+    /** Baseline entries no longer produced — fixed, or the relation is gone. */
+    removed: BaselineFinding[];
+    /** Findings that matched the baseline — accepted debt, still reported. */
+    accepted: Finding[];
+}
+export declare function subjectOf(finding: Finding): string | undefined;
+export declare function findingKey(entry: BaselineFinding): string;
+export declare function toBaselineFinding(finding: Finding): BaselineFinding;
+export declare function toPerfBaseline(findings: Finding[]): PerfBaseline;
+export declare function diffPerf(findings: Finding[], baseline: PerfBaseline): PerfDiff;
+export declare function parsePerfBaseline(raw: string): PerfBaseline;
+export declare function serializePerfBaseline(baseline: PerfBaseline): string;

package/perf/baseline.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Perf baseline: a committed snapshot of accepted performance debt.
+ *
+ * The point is the ratchet. A large schema will not reach a clean perf report
+ * in one pass, but it can refuse to get worse: commit the current findings,
+ * then fail CI only on findings that are *not* in the baseline.
+ *
+ * Only the identity of a finding is stored — code, relation, policy, and the
+ * one context field that distinguishes findings of the same code on the same
+ * relation. Messages, severities and hints may be reworded between safegres
+ * versions without invalidating a committed baseline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subjectOf = subjectOf;
+exports.findingKey = findingKey;
+exports.toBaselineFinding = toBaselineFinding;
+exports.toPerfBaseline = toPerfBaseline;
+exports.diffPerf = diffPerf;
+exports.parsePerfBaseline = parsePerfBaseline;
+exports.serializePerfBaseline = serializePerfBaseline;
+/**
+ * Context keys that identify *which* object a finding is about, in priority
+ * order (X3 carries both `expression` and `column`; the expression is the
+ * narrower identity). Rules that can only fire once per relation — X6 — set
+ * none of these and are keyed by code + relation alone.
+ */
+const SUBJECT_KEYS = ['constraint', 'index', 'expression', 'column', 'function'];
+function subjectOf(finding) {
+    const context = finding.context;
+    if (!context)
+        return undefined;
+    for (const key of SUBJECT_KEYS) {
+        const value = context[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function findingKey(entry) {
+    return [entry.code, entry.schema ?? '', entry.table ?? '', entry.policy ?? '', entry.subject ?? ''].join('|');
+}
+function toBaselineFinding(finding) {
+    const subject = subjectOf(finding);
+    return {
+        code: finding.code,
+        ...(finding.schema ? { schema: finding.schema } : {}),
+        ...(finding.table ? { table: finding.table } : {}),
+        ...(finding.policy ? { policy: finding.policy } : {}),
+        ...(subject ? { subject } : {})
+    };
+}
+function toPerfBaseline(findings) {
+    const seen = new Set();
+    const out = [];
+    for (const finding of findings) {
+        const entry = toBaselineFinding(finding);
+        const key = findingKey(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    out.sort((a, b) => findingKey(a).localeCompare(findingKey(b)));
+    return { version: 1, findings: out };
+}
+function diffPerf(findings, baseline) {
+    const baseKeys = new Set(baseline.findings.map(findingKey));
+    const currentKeys = new Set();
+    const added = [];
+    const accepted = [];
+    for (const finding of findings) {
+        const key = findingKey(toBaselineFinding(finding));
+        currentKeys.add(key);
+        if (baseKeys.has(key))
+            accepted.push(finding);
+        else
+            added.push(finding);
+    }
+    const removed = baseline.findings.filter((entry) => !currentKeys.has(findingKey(entry)));
+    return { added, removed, accepted };
+}
+function parsePerfBaseline(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== 1 || !Array.isArray(data.findings)) {
+        throw new Error('invalid perf baseline: expected { version: 1, findings: [...] }');
+    }
+    return { version: 1, findings: data.findings };
+}
+function serializePerfBaseline(baseline) {
+    return JSON.stringify(baseline, null, 2) + '\n';
+}

package/report/pretty.js

@@ -90,6 +90,22 @@ function renderPretty(report, options = {}) {
     if (security.length === 0) {
         lines.push('no findings.');
     }
+    if (report.perf?.diff) {
+        const { added, removed, accepted } = report.perf.diff;
+        lines.push('', 'performance vs baseline:', '');
+        if (added.length === 0) {
+            lines.push(`no new perf debt (${accepted.length} accepted, ${removed.length} fixed).`);
+        }
+        else {
+            lines.push(paint('high', `${added.length} new perf finding${added.length === 1 ? '' : 's'} since the baseline:`));
+            for (const f of added)
+                lines.push(renderFinding(f, paint));
+            lines.push(paint('info', `  (${accepted.length} accepted, ${removed.length} fixed)`));
+        }
+        if (removed.length > 0) {
+            lines.push(paint('info', `  fixed since the baseline: ${removed.map((r) => `${r.code} ${r.schema}.${r.table}`).join(', ')} — re-baseline to lock the win in`));
+        }
+    }
     if (report.perf) {
         const perfExposed = report.perf.findings.filter((f) => f.exposed !== false);
         const perfInternal = report.perf.findings.length - perfExposed.length;

package/types.d.ts

@@ -90,6 +90,11 @@ export interface PerfReport {
     summary: Summary;
     /** Perf score — computed only over perf-dimension findings. */
     score: import('./score/score').Score;
+    /**
+     * Diff against a committed perf baseline (`--perf-baseline`): which findings
+     * are new debt, which were fixed, which are accepted.
+     */
+    diff?: import('./perf/baseline').PerfDiff;
 }
 export interface Report {
     version: string;