@safegres/test 0.0.1 → 1.30.7

package/esm/pg/paths.js

@@ -0,0 +1,159 @@
+/**
+ * Access-path signals: independent, individually-auditable pieces of evidence
+ * about whether anything reads a foreign key.
+ *
+ * X1 ("foreign key with no covering index") is right about the mechanics — a
+ * `DELETE` on the parent really does scan the child — but it assumes the child
+ * is a relation somebody traverses. On a provisioning-config table that
+ * assumption is false, and acting on the finding buys a write penalty on every
+ * insert in exchange for speeding up a scan of one row.
+ *
+ * The tempting gate, `pg_class.reltuples`, is useless here: safegres grades an
+ * ephemeral CI database that has never held data, so every row estimate is 0
+ * at exactly the moment we grade. Worse, row count is the wrong question — a
+ * huge append-only log nobody joins on wants no FK index, and a tiny lookup
+ * table hammered by every request does. The property we need is *reachability*.
+ *
+ * Reachability is not one boolean, and this module deliberately does not
+ * compute one. It collects signals, each of which points in one direction and
+ * says why, and leaves the verdict to the caller:
+ *
+ * - `policy-read` and `view-read` are **reads**. They are decisive: the
+ *   database itself traverses the column, so no amount of contrary evidence
+ *   makes the path unreachable.
+ * - `write-once-pointer` and `config-record` are **shape**. They are not
+ *   evidence of unreachability, only of a schema idiom — a `NOT NULL` key
+ *   defaulting to the nil UUID is a slot a provisioner fills in, and a table
+ *   with several of them looks like a config record rather than a relation.
+ *
+ * Shape alone must never suppress a finding. A generated API can expose a
+ * reverse relation over any foreign key regardless of how its default is
+ * written, and if it does, the path is reachable and the index is wanted.
+ *
+ * - `behavior-hidden` is the third kind, **declared**: the schema author has
+ *   said the reverse relation is not in the generated API. It comes from the
+ *   same behavior tags exposure reach reads, so the two axes agree about what
+ *   the API contains rather than each guessing separately. It is reported and
+ *   not acted on — a hidden relation is one missing path, not proof that
+ *   nothing traverses the key, since the referential-integrity scan on a
+ *   parent `DELETE` runs whatever the API exposes.
+ */
+export const DEFAULT_MIN_POINTERS = 2;
+/**
+ * Defaults that pin a key column to one value for every row the application
+ * does not overwrite — the nil UUID, a literal, a constant of any scalar type.
+ * A call to anything else (`uuidv7()`, `now()`, a sequence) is excluded: those
+ * produce a real distribution of keys.
+ */
+const CONSTANT_DEFAULT = /^(uuid_nil\(\)|'(?:[^']|'')*'(?:::[\w .]+(?:\[\])?)?|-?\d+(?:\.\d+)?|true|false)$/i;
+export function isConstantDefault(defaultExpr) {
+    if (!defaultExpr)
+        return false;
+    return CONSTANT_DEFAULT.test(defaultExpr.trim());
+}
+/** Key for {@link AccessPath} lookups: the relation plus the constraint name. */
+export function pathKey(schema, table, constraint) {
+    return `${schema}.${table}.${constraint}`;
+}
+/**
+ * One real reader ends the discussion, so a `read` signal always wins. Absent
+ * one, the shape has to hold at the *table* level before it means anything: a
+ * lone defaulted column is a habit, whereas a table built entirely out of them
+ * is an idiom. `write-once-pointer` on its own is therefore reported and not
+ * acted on.
+ */
+export function assess(signals) {
+    if (signals.some((s) => s.direction === 'read'))
+        return 'read';
+    if (signals.some((s) => s.name === 'config-record'))
+        return 'write-once-shaped';
+    return 'unknown';
+}
+/**
+ * Collect the signals for every foreign key in the snapshot.
+ *
+ * `tables` supplies the RLS policy predicates (as SQL text) and `viewBodies`
+ * the view definitions. Both are matched as whole-word tokens across the
+ * *whole* database rather than per relation — deliberately over-eager, because
+ * a spurious `read` signal costs one retained finding while a missing one
+ * could cost a dropped index.
+ */
+export function classifyPaths(indexSnapshot, tables, viewBodies, options = {}) {
+    const minPointers = options.minPointers ?? DEFAULT_MIN_POINTERS;
+    const hidden = options.hiddenBackwardRelations ?? new Set();
+    const policyTokens = identifierTokens(tables.flatMap((t) => t.policies.flatMap((p) => [p.using, p.withCheck])));
+    const viewTokens = identifierTokens(viewBodies);
+    const paths = new Map();
+    for (const table of indexSnapshot) {
+        const defaults = new Map(table.columns.map((c) => [c.attnum, c.defaultExpr]));
+        const readBy = (tokens, columns) => columns.filter((c) => tokens.has(c.toLowerCase()));
+        const pointers = table.foreignKeys.filter((fk) => fk.columns.length > 0 &&
+            fk.columns.every((a) => isConstantDefault(defaults.get(a) ?? null)) &&
+            readBy(policyTokens, fk.columnNames).length === 0 &&
+            readBy(viewTokens, fk.columnNames).length === 0);
+        for (const fk of table.foreignKeys) {
+            const signals = [];
+            const inPolicy = readBy(policyTokens, fk.columnNames);
+            if (inPolicy.length > 0) {
+                signals.push({
+                    name: 'policy-read',
+                    direction: 'read',
+                    detail: `an RLS policy predicate names ${inPolicy.join(', ')}`
+                });
+            }
+            const inView = readBy(viewTokens, fk.columnNames);
+            if (inView.length > 0) {
+                signals.push({
+                    name: 'view-read',
+                    direction: 'read',
+                    detail: `a view or materialized view names ${inView.join(', ')}`
+                });
+            }
+            if (pointers.some((p) => p.name === fk.name)) {
+                signals.push({
+                    name: 'write-once-pointer',
+                    direction: 'shape',
+                    detail: `every column of ${fk.name} has a constant default`
+                });
+            }
+            if (pointers.length >= minPointers && inPolicy.length === 0 && inView.length === 0) {
+                signals.push({
+                    name: 'config-record',
+                    direction: 'shape',
+                    detail: `${table.name} carries ${pointers.length} write-once pointers`
+                });
+            }
+            if (hidden.has(pathKey(table.schema, table.name, fk.name))) {
+                signals.push({
+                    name: 'behavior-hidden',
+                    direction: 'declared',
+                    detail: `a behavior declares the reverse relation over ${fk.name} absent from the API`
+                });
+            }
+            paths.set(pathKey(table.schema, table.name, fk.name), {
+                schema: table.schema,
+                table: table.name,
+                columns: fk.columnNames,
+                constraint: fk.name,
+                signals,
+                assessment: assess(signals)
+            });
+        }
+    }
+    return paths;
+}
+/**
+ * Every identifier-shaped token appearing in the given SQL, lowercased.
+ * Tokenising rather than substring-matching keeps `schema_id` from being
+ * "found" inside `private_schema_id`.
+ */
+function identifierTokens(sources) {
+    const out = new Set();
+    for (const sql of sources) {
+        if (!sql)
+            continue;
+        for (const token of sql.toLowerCase().match(/[a-z_][a-z0-9_$]*/g) ?? [])
+            out.add(token);
+    }
+    return out;
+}

package/esm/pg/proc.d.ts

@@ -0,0 +1,23 @@
+import type { QueryExecutor } from './introspect';
+/** `pg_proc.provolatile`: `i` immutable, `s` stable, `v` volatile. */
+export type Volatility = 'i' | 's' | 'v';
+export interface ProcVolatility {
+    /** Schema-qualified name, or bare name if in `pg_catalog` / a common system schema. */
+    name: string;
+    volatility: Volatility;
+    isSecurityDefiner: boolean;
+    /** `pg_proc.proleakproof` — a leakproof function can be pushed below a security qual. */
+    isLeakproof: boolean;
+    /** True if this is a built-in / system function (we usually allow-list these). */
+    isSystem: boolean;
+}
+/**
+ * Look up `(schema, name)` tuples in pg_proc and return their volatility.
+ * Returns a map keyed by the two names the AST walker might see:
+ *   - `schema.name` (schema-qualified)
+ *   - `name` (unqualified; only used when the function lives in `pg_catalog`)
+ */
+export declare function lookupVolatility(exec: QueryExecutor, names: Array<{
+    schema?: string;
+    name: string;
+}>): Promise<Map<string, ProcVolatility>>;

package/esm/pg/proc.js

@@ -0,0 +1,55 @@
+const SYSTEM_SCHEMAS = new Set([
+    'pg_catalog',
+    'information_schema',
+    'pg_toast'
+]);
+/**
+ * Look up `(schema, name)` tuples in pg_proc and return their volatility.
+ * Returns a map keyed by the two names the AST walker might see:
+ *   - `schema.name` (schema-qualified)
+ *   - `name` (unqualified; only used when the function lives in `pg_catalog`)
+ */
+export async function lookupVolatility(exec, names) {
+    if (names.length === 0)
+        return new Map();
+    // Dedupe input.
+    const seen = new Set();
+    const deduped = names.filter((n) => {
+        const key = `${n.schema ?? ''}.${n.name}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const { rows } = await exec.query(`
+    SELECT
+      n.nspname     AS schema,
+      p.proname     AS proname,
+      p.provolatile AS volatility,
+      p.prosecdef   AS security_definer,
+      p.proleakproof AS leakproof
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE (n.nspname, p.proname) IN (
+      SELECT unnest($1::text[]), unnest($2::text[])
+    )
+    `, [
+        deduped.map((n) => n.schema ?? 'pg_catalog'),
+        deduped.map((n) => n.name)
+    ]);
+    const map = new Map();
+    for (const r of rows) {
+        const info = {
+            name: `${r.schema}.${r.proname}`,
+            volatility: r.volatility,
+            isSecurityDefiner: r.security_definer,
+            isLeakproof: r.leakproof,
+            isSystem: SYSTEM_SCHEMAS.has(r.schema)
+        };
+        map.set(`${r.schema}.${r.proname}`, info);
+        if (r.schema === 'pg_catalog') {
+            map.set(r.proname, info);
+        }
+    }
+    return map;
+}

package/esm/pg/reach-inputs.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Extra catalog inputs the revocable-grant rule (L21) needs and no other rule
+ * reads: the ordinary triggers on a relation, and the SQL expressions a write
+ * to it evaluates — column defaults, generated columns and CHECK constraints.
+ *
+ * All three matter for one reason: they run as the *querying* role, not the
+ * table owner. A function called from a column default or a trigger body is a
+ * function the writing role must be able to EXECUTE, exactly as if it had
+ * called it directly — so a grant reached only that way is load-bearing and
+ * must not be reported revocable. The per-table policy predicates L21 also
+ * closes over already live on {@link TableSnapshot.policies}; only these three
+ * were missing.
+ */
+import type { QueryExecutor } from './introspect';
+/** A non-internal trigger on a relation, and the function it fires. */
+export interface RelationTrigger {
+    name: string;
+    /** The write commands that fire it (TRUNCATE is dropped — it grants nothing). */
+    events: Array<'INSERT' | 'UPDATE' | 'DELETE'>;
+    /** `INSTEAD OF` (view) vs an ordinary BEFORE/AFTER trigger. */
+    instead: boolean;
+    functionSchema: string;
+    functionName: string;
+}
+/** A SQL expression a write to the relation evaluates, as the querying role. */
+export interface RelationExpr {
+    kind: 'default' | 'generated' | 'check';
+    /** Column name for default/generated; constraint name for check. */
+    name: string;
+    expr: string;
+}
+export interface ReachInputs {
+    /** Triggers per relation, keyed `schema.table`. */
+    triggers: Map<string, RelationTrigger[]>;
+    /** Write-time expressions per relation, keyed `schema.table`. */
+    expressions: Map<string, RelationExpr[]>;
+}
+export interface ReachInputsOptions {
+    schemas?: string[];
+    excludeSchemas?: string[];
+}
+/**
+ * The triggers and write-time expressions of every relation in scope, in two
+ * cheap queries. Keyed the same way the table snapshot is (`schema.table`), so
+ * the engine can look inputs up by the relation it is already iterating.
+ */
+export declare function introspectReachInputs(exec: QueryExecutor, options?: ReachInputsOptions): Promise<ReachInputs>;

package/esm/pg/reach-inputs.js

@@ -0,0 +1,133 @@
+/**
+ * Extra catalog inputs the revocable-grant rule (L21) needs and no other rule
+ * reads: the ordinary triggers on a relation, and the SQL expressions a write
+ * to it evaluates — column defaults, generated columns and CHECK constraints.
+ *
+ * All three matter for one reason: they run as the *querying* role, not the
+ * table owner. A function called from a column default or a trigger body is a
+ * function the writing role must be able to EXECUTE, exactly as if it had
+ * called it directly — so a grant reached only that way is load-bearing and
+ * must not be reported revocable. The per-table policy predicates L21 also
+ * closes over already live on {@link TableSnapshot.policies}; only these three
+ * were missing.
+ */
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+/**
+ * The triggers and write-time expressions of every relation in scope, in two
+ * cheap queries. Keyed the same way the table snapshot is (`schema.table`), so
+ * the engine can look inputs up by the relation it is already iterating.
+ */
+export async function introspectReachInputs(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    const include = options.schemas ?? [];
+    // Both params are referenced unconditionally so the prepared statement's
+    // parameter count never depends on which branch of the include/exclude
+    // choice applies (`pg` binds by count, not by name).
+    const schemaFilter = 'AND CASE WHEN cardinality($1::text[]) > 0'
+        + ' THEN n.nspname = ANY($1::text[])'
+        + ' ELSE NOT (n.nspname = ANY($2::text[])) END';
+    const triggers = await introspectTriggers(exec, schemaFilter, include, excludes);
+    const expressions = await introspectExpressions(exec, schemaFilter, include, excludes);
+    return { triggers, expressions };
+}
+async function introspectTriggers(exec, schemaFilter, include, excludes) {
+    // tgtype bits (see access/tableam / commands/trigger.h): 1 ROW, 2 BEFORE,
+    // 4 INSERT, 8 DELETE, 16 UPDATE, 32 TRUNCATE, 64 INSTEAD OF. Decoded here so
+    // the engine gets event names, not a bitmask.
+    const { rows } = await exec.query(`
+    SELECT
+      n.nspname                      AS schema,
+      c.relname                      AS relation,
+      t.tgname                       AS name,
+      (t.tgtype & 4)  <> 0           AS fires_insert,
+      (t.tgtype & 16) <> 0           AS fires_update,
+      (t.tgtype & 8)  <> 0           AS fires_delete,
+      (t.tgtype & 64) <> 0           AS instead,
+      fn.nspname                     AS fn_schema,
+      p.proname                      AS fn_name
+    FROM pg_trigger t
+    JOIN pg_class c ON c.oid = t.tgrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_proc p ON p.oid = t.tgfoid
+    JOIN pg_namespace fn ON fn.oid = p.pronamespace
+    WHERE NOT t.tgisinternal
+      AND n.nspname NOT LIKE 'pg\\_%'
+      ${schemaFilter}
+    ORDER BY n.nspname, c.relname, t.tgname
+    `, [include, excludes]);
+    const out = new Map();
+    for (const r of rows) {
+        const events = [];
+        if (r.fires_insert)
+            events.push('INSERT');
+        if (r.fires_update)
+            events.push('UPDATE');
+        if (r.fires_delete)
+            events.push('DELETE');
+        const key = `${r.schema}.${r.relation}`;
+        const list = out.get(key) ?? [];
+        list.push({
+            name: r.name,
+            events,
+            instead: r.instead,
+            functionSchema: r.fn_schema,
+            functionName: r.fn_name
+        });
+        out.set(key, list);
+    }
+    return out;
+}
+async function introspectExpressions(exec, schemaFilter, include, excludes) {
+    const out = new Map();
+    const add = (key, expr) => {
+        const list = out.get(key) ?? [];
+        list.push(expr);
+        out.set(key, list);
+    };
+    // Column defaults and generated-column expressions both live in pg_attrdef;
+    // a generated column is flagged by pg_attribute.attgenerated.
+    const { rows: defaults } = await exec.query(`
+    SELECT
+      n.nspname                              AS schema,
+      c.relname                              AS relation,
+      a.attname                              AS column,
+      a.attgenerated <> ''                   AS generated,
+      pg_get_expr(ad.adbin, ad.adrelid)      AS expr
+    FROM pg_attrdef ad
+    JOIN pg_class c ON c.oid = ad.adrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_attribute a ON a.attrelid = ad.adrelid AND a.attnum = ad.adnum
+    WHERE n.nspname NOT LIKE 'pg\\_%'
+      ${schemaFilter}
+    ORDER BY n.nspname, c.relname, a.attnum
+    `, [include, excludes]);
+    for (const r of defaults) {
+        if (!r.expr)
+            continue;
+        add(`${r.schema}.${r.relation}`, {
+            kind: r.generated ? 'generated' : 'default',
+            name: r.column,
+            expr: r.expr
+        });
+    }
+    const { rows: checks } = await exec.query(`
+    SELECT
+      n.nspname                              AS schema,
+      c.relname                              AS relation,
+      con.conname                            AS name,
+      pg_get_expr(con.conbin, con.conrelid)  AS expr
+    FROM pg_constraint con
+    JOIN pg_class c ON c.oid = con.conrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE con.contype = 'c'
+      AND n.nspname NOT LIKE 'pg\\_%'
+      ${schemaFilter}
+    ORDER BY n.nspname, c.relname, con.conname
+    `, [include, excludes]);
+    for (const r of checks) {
+        if (!r.expr)
+            continue;
+        add(`${r.schema}.${r.relation}`, { kind: 'check', name: r.name, expr: r.expr });
+    }
+    return out;
+}

package/esm/pg/roles.d.ts

@@ -0,0 +1,28 @@
+import type { QueryExecutor } from './introspect';
+/** A filterable PostgreSQL role for audit purposes. */
+export interface RoleInfo {
+    name: string;
+    canLogin: boolean;
+    isSuper: boolean;
+    isSystem: boolean;
+}
+/**
+ * Enumerate every non-system role that could meaningfully appear as a
+ * grantee. By default we include every role — caller may pass `--roles`
+ * to narrow to e.g. `authenticated, anonymous`.
+ */
+export declare function listAuditableRoles(exec: QueryExecutor): Promise<RoleInfo[]>;
+export interface RoleResolution {
+    /** Final list of role names used for the audit. */
+    roles: string[];
+    /** Roles returned by pg_roles but filtered out. */
+    excluded: string[];
+}
+/**
+ * Apply `--roles` / `--exclude-roles` filters against the full pg_roles list.
+ *
+ * - If `include` is non-empty, only those names survive.
+ * - Else, every non-system role survives.
+ * - `exclude` is applied on top.
+ */
+export declare function resolveRoles(allRoles: RoleInfo[], include: string[] | undefined, exclude?: string[]): RoleResolution;

package/esm/pg/roles.js

@@ -0,0 +1,50 @@
+/**
+ * Enumerate every non-system role that could meaningfully appear as a
+ * grantee. By default we include every role — caller may pass `--roles`
+ * to narrow to e.g. `authenticated, anonymous`.
+ */
+export async function listAuditableRoles(exec) {
+    const { rows } = await exec.query(`
+    SELECT rolname, rolcanlogin, rolsuper
+    FROM pg_roles
+    ORDER BY rolname
+  `);
+    return rows.map((r) => ({
+        name: r.rolname,
+        canLogin: r.rolcanlogin,
+        isSuper: r.rolsuper,
+        isSystem: r.rolname.startsWith('pg_')
+    }));
+}
+/**
+ * Apply `--roles` / `--exclude-roles` filters against the full pg_roles list.
+ *
+ * - If `include` is non-empty, only those names survive.
+ * - Else, every non-system role survives.
+ * - `exclude` is applied on top.
+ */
+export function resolveRoles(allRoles, include, exclude = []) {
+    const excludeSet = new Set(exclude);
+    const includeSet = include && include.length > 0 ? new Set(include) : null;
+    const roles = [];
+    const excluded = [];
+    for (const r of allRoles) {
+        if (excludeSet.has(r.name)) {
+            excluded.push(r.name);
+            continue;
+        }
+        if (includeSet) {
+            if (includeSet.has(r.name))
+                roles.push(r.name);
+            else
+                excluded.push(r.name);
+            continue;
+        }
+        if (r.isSystem) {
+            excluded.push(r.name);
+            continue;
+        }
+        roles.push(r.name);
+    }
+    return { roles, excluded };
+}

package/esm/pg/stats.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Runtime statistics snapshot (`--stats`).
+ *
+ * Everything here reads the cumulative statistics views — `pg_stat_user_tables`,
+ * `pg_stat_user_indexes`, and (when installed) `pg_stat_statements`. Unlike the
+ * catalog checks, these numbers describe a *workload*: they are only as good as
+ * the traffic the database has seen since the counters were last reset, which is
+ * why the snapshot carries `statsReset` and why the checks take floors.
+ */
+import { type IntrospectOptions, type QueryExecutor } from './introspect';
+export interface IndexUsage {
+    name: string;
+    /** `pg_stat_user_indexes.idx_scan` — times the planner chose this index. */
+    scans: number;
+    /** `pg_relation_size` of the index, in bytes. */
+    sizeBytes: number;
+    unique: boolean;
+    /** Backs a PRIMARY KEY / UNIQUE / EXCLUDE constraint — never droppable alone. */
+    constraint: boolean;
+}
+export interface TableUsage {
+    schema: string;
+    name: string;
+    seqScans: number;
+    seqTuplesRead: number;
+    /** Index scans across every index on the table. */
+    indexScans: number;
+    liveTuples: number;
+    deadTuples: number;
+    /** `pg_relation_size` of the heap, in bytes. */
+    sizeBytes: number;
+    /** Most recent vacuum, manual or auto (ISO 8601), null if never. */
+    lastVacuum: string | null;
+    /** Most recent analyze, manual or auto (ISO 8601), null if never. */
+    lastAnalyze: string | null;
+    indexes: IndexUsage[];
+}
+export interface StatementUsage {
+    /** Normalised query text (parameters replaced by `$n`). */
+    query: string;
+    calls: number;
+    /** Total execution time across all calls, in milliseconds. */
+    totalTimeMs: number;
+    meanTimeMs: number;
+    /** Rows returned/affected across all calls. */
+    rows: number;
+}
+export interface StatsSnapshot {
+    tables: TableUsage[];
+    /** Present only when `pg_stat_statements` is installed and readable. */
+    statements?: StatementUsage[];
+    /**
+     * When the cumulative counters were last reset (ISO 8601), from
+     * `pg_stat_database`. A recent reset means the numbers describe a short
+     * window and the checks should be read as provisional.
+     */
+    statsReset: string | null;
+    /** Why `statements` is absent, for the report's `notes`. */
+    statementsUnavailable?: string;
+}
+/** Statements slower than this in aggregate are worth reporting at all. */
+export declare const DEFAULT_STATEMENT_LIMIT = 20;
+export declare function introspectStats(exec: QueryExecutor, options?: Pick<IntrospectOptions, 'schemas' | 'excludeSchemas' | 'extensions'> & {
+    statementLimit?: number;
+}): Promise<StatsSnapshot>;