@safegres/test 0.0.2 → 1.30.7

package/esm/exposure/reach.d.ts

@@ -0,0 +1,78 @@
+/**
+ * API reach: which relations a generated API can actually address.
+ *
+ * A plane made of schemas answers "is this relation in the API's schemas?",
+ * which is as much precision as a schema list can carry. It over-counts in a
+ * way that matters: a generated API exposes types and fields, not schemas, and
+ * a schema routinely contains relations the API deliberately does not surface
+ * — join tables, denormalised shadows, machine-only back-pointers.
+ *
+ * Where the author has *declared* that, the declaration is better evidence
+ * than anything else safegres can collect. `reltuples` and `idx_scan` are
+ * measurements, and safegres grades ephemeral CI databases that have never
+ * held data, so both read zero at exactly the moment they would have to mean
+ * something. A behavior tag reads the same in CI as in production.
+ *
+ * Two properties keep this honest:
+ *
+ * - **Only an explicit denial counts.** Presets grant most behaviors by
+ *   default, so the absence of `+list` says nothing whatsoever. Silence is
+ *   never read as denial.
+ * - **Unreachable means unreachable by *every* route.** A relation the API
+ *   cannot address at the root can still be addressed by traversing a relation
+ *   field from one that can, so this is a graph reachability problem and not a
+ *   per-table test. Subtracting a relation that is in fact addressable would
+ *   silently drop real findings out of the score, which is the one failure
+ *   mode worth designing against.
+ */
+import type { BehaviorSnapshot } from '../pg/behaviors';
+/**
+ * Abilities that between them cover every root entry point to a relation.
+ * All four must be denied before the relation is absent from the API root: a
+ * table that cannot be read but can still be inserted into is present.
+ */
+export declare const ROOT_ABILITIES: string[];
+/** The reverse (child-listing) field exists under any one of these. */
+export declare const BACKWARD_ABILITIES: string[];
+/** The forward (parent) field is a single record. */
+export declare const FORWARD_ABILITIES: string[];
+/** One foreign key, as reach cares about it. */
+export interface ReachEdge {
+    /** Referencing relation, `schema.table`. */
+    from: string;
+    /** Referenced relation, `schema.table`. */
+    to: string;
+    constraint: string;
+}
+export interface ReachInputs {
+    /** Every relation in scope, `schema.table`. */
+    relations: string[];
+    edges: ReachEdge[];
+    behaviors: BehaviorSnapshot;
+}
+export interface UnreachableRelation {
+    schema: string;
+    table: string;
+    /** Why it is unreachable, in one human-readable clause. */
+    reason: string;
+}
+export interface ApiReach {
+    /** Relations no field of the generated API can address. */
+    unreachable: UnreachableRelation[];
+    /**
+     * `schema.table.constraint` for every foreign key whose reverse relation is
+     * declared absent. A hidden reverse relation is not the same claim as an
+     * unreachable table — it is one path, not all of them — so it is reported
+     * separately and consumed by the X1 access-path signals.
+     */
+    hiddenBackwardRelations: string[];
+}
+/**
+ * Compute what the generated API can address.
+ *
+ * The traversal starts from every relation the API roots — anything not
+ * explicitly denied all of {@link ROOT_ABILITIES} — and walks relation fields
+ * in both directions. What it never visits is a relation that is denied at the
+ * root *and* has no surviving field pointing at it from anywhere reachable.
+ */
+export declare function computeApiReach(inputs: ReachInputs): ApiReach;

package/esm/exposure/reach.js

@@ -0,0 +1,105 @@
+/**
+ * API reach: which relations a generated API can actually address.
+ *
+ * A plane made of schemas answers "is this relation in the API's schemas?",
+ * which is as much precision as a schema list can carry. It over-counts in a
+ * way that matters: a generated API exposes types and fields, not schemas, and
+ * a schema routinely contains relations the API deliberately does not surface
+ * — join tables, denormalised shadows, machine-only back-pointers.
+ *
+ * Where the author has *declared* that, the declaration is better evidence
+ * than anything else safegres can collect. `reltuples` and `idx_scan` are
+ * measurements, and safegres grades ephemeral CI databases that have never
+ * held data, so both read zero at exactly the moment they would have to mean
+ * something. A behavior tag reads the same in CI as in production.
+ *
+ * Two properties keep this honest:
+ *
+ * - **Only an explicit denial counts.** Presets grant most behaviors by
+ *   default, so the absence of `+list` says nothing whatsoever. Silence is
+ *   never read as denial.
+ * - **Unreachable means unreachable by *every* route.** A relation the API
+ *   cannot address at the root can still be addressed by traversing a relation
+ *   field from one that can, so this is a graph reachability problem and not a
+ *   per-table test. Subtracting a relation that is in fact addressable would
+ *   silently drop real findings out of the score, which is the one failure
+ *   mode worth designing against.
+ */
+import { deniesAll, directionalBehavior } from '../pg/behaviors';
+/**
+ * Abilities that between them cover every root entry point to a relation.
+ * All four must be denied before the relation is absent from the API root: a
+ * table that cannot be read but can still be inserted into is present.
+ */
+export const ROOT_ABILITIES = ['select', 'insert', 'update', 'delete'];
+/** The reverse (child-listing) field exists under any one of these. */
+export const BACKWARD_ABILITIES = ['list', 'connection', 'single'];
+/** The forward (parent) field is a single record. */
+export const FORWARD_ABILITIES = ['single'];
+function splitRelation(relation) {
+    const dot = relation.indexOf('.');
+    return { schema: relation.slice(0, dot), table: relation.slice(dot + 1) };
+}
+/**
+ * Compute what the generated API can address.
+ *
+ * The traversal starts from every relation the API roots — anything not
+ * explicitly denied all of {@link ROOT_ABILITIES} — and walks relation fields
+ * in both directions. What it never visits is a relation that is denied at the
+ * root *and* has no surviving field pointing at it from anywhere reachable.
+ */
+export function computeApiReach(inputs) {
+    const { relations, edges, behaviors } = inputs;
+    const inScope = new Set(relations);
+    const rooted = relations.filter((relation) => !deniesAll(behaviors.tables.get(relation), ROOT_ABILITIES));
+    const hiddenBackwardRelations = [];
+    const adjacency = new Map();
+    const addEdge = (from, to) => {
+        const list = adjacency.get(from);
+        if (list)
+            list.push(to);
+        else
+            adjacency.set(from, [to]);
+    };
+    for (const edge of edges) {
+        const key = `${edge.from}.${edge.constraint}`;
+        const directions = behaviors.constraintDirections.get(key);
+        const backwardHidden = deniesAll(directionalBehavior(directions, 'backward'), BACKWARD_ABILITIES);
+        if (backwardHidden)
+            hiddenBackwardRelations.push(key);
+        // The reverse field lives on the referenced table and reaches the
+        // referencing one.
+        if (!backwardHidden && inScope.has(edge.to))
+            addEdge(edge.to, edge.from);
+        const forwardHidden = deniesAll(directionalBehavior(directions, 'forward'), FORWARD_ABILITIES);
+        if (!forwardHidden && inScope.has(edge.from))
+            addEdge(edge.from, edge.to);
+    }
+    const reached = new Set();
+    const queue = [...rooted];
+    for (const relation of rooted)
+        reached.add(relation);
+    while (queue.length > 0) {
+        const current = queue.pop();
+        for (const next of adjacency.get(current) ?? []) {
+            if (!inScope.has(next) || reached.has(next))
+                continue;
+            reached.add(next);
+            queue.push(next);
+        }
+    }
+    const unreachable = [];
+    for (const relation of relations) {
+        if (reached.has(relation))
+            continue;
+        const inbound = edges.filter((e) => e.to === relation || e.from === relation).length;
+        unreachable.push({
+            ...splitRelation(relation),
+            reason: `a behavior denies ${ROOT_ABILITIES.join(', ')} on the relation`
+                + (inbound > 0
+                    ? ', and every relation field that could reach it is denied too'
+                    : ', and no relation field points at it')
+        });
+    }
+    return { unreachable, hiddenBackwardRelations: hiddenBackwardRelations.sort() };
+}

package/esm/exposure/routines.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Routine exposure: which functions an untrusted role can actually call.
+ *
+ * The exposure surface answers "which relations can the API address?", and
+ * every finding was graded by that question — including the ones that are not
+ * about a relation at all. A definer function lives in a private schema, so by
+ * relation reach it is unexposed; but `anonymous` holds `EXECUTE` on it, so it
+ * is one call away from whatever its owner can touch. Grading it by its schema
+ * is not conservative, it is wrong in the dangerous direction.
+ *
+ * The question a routine finding is graded by is therefore the callability
+ * one: can an untrusted role reach the function itself — `USAGE` on its
+ * schema, and `EXECUTE` on the function, directly, by inheritance, or through
+ * Postgres's default `EXECUTE TO PUBLIC`.
+ */
+import type { RoleGraph } from '../checks/lattice';
+import { type SchemaAclInfo } from '../pg/acl';
+import type { FunctionSnapshot } from '../pg/functions';
+export interface RoutineReachOptions {
+    /** Roles a request can arrive as — the API edge, plus its anonymous roles. */
+    roles: string[];
+    graph: RoleGraph;
+    schemaAcls: Map<string, SchemaAclInfo>;
+    /**
+     * Schemas on the API surface. A trigger function is not directly callable
+     * whatever its ACL says, so it is judged the way its firing is: reachable
+     * when a write that fires it is.
+     */
+    exposedSchemas: Set<string>;
+}
+/**
+ * Every `schema.name` an untrusted role can execute. Overloads collapse: the
+ * finding names a function, not a signature, and a role that can call one
+ * overload can reach the body the rule is talking about.
+ */
+export declare function resolveRoutineReach(functions: FunctionSnapshot[], options: RoutineReachOptions): Set<string>;

package/esm/exposure/routines.js

@@ -0,0 +1,54 @@
+/**
+ * Routine exposure: which functions an untrusted role can actually call.
+ *
+ * The exposure surface answers "which relations can the API address?", and
+ * every finding was graded by that question — including the ones that are not
+ * about a relation at all. A definer function lives in a private schema, so by
+ * relation reach it is unexposed; but `anonymous` holds `EXECUTE` on it, so it
+ * is one call away from whatever its owner can touch. Grading it by its schema
+ * is not conservative, it is wrong in the dangerous direction.
+ *
+ * The question a routine finding is graded by is therefore the callability
+ * one: can an untrusted role reach the function itself — `USAGE` on its
+ * schema, and `EXECUTE` on the function, directly, by inheritance, or through
+ * Postgres's default `EXECUTE TO PUBLIC`.
+ */
+import { canEnterSchema } from '../pg/acl';
+/**
+ * Every `schema.name` an untrusted role can execute. Overloads collapse: the
+ * finding names a function, not a signature, and a role that can call one
+ * overload can reach the body the rule is talking about.
+ */
+export function resolveRoutineReach(functions, options) {
+    const reachable = new Set();
+    if (options.roles.length === 0)
+        return reachable;
+    for (const fn of functions) {
+        const key = `${fn.schema}.${fn.name}`;
+        if (reachable.has(key))
+            continue;
+        if (fn.returnsTrigger) {
+            // Postgres refuses a direct call however wide the ACL is. What reaches
+            // the body is a write to the table the trigger is attached to, so the
+            // API surface is the right question after all.
+            if (options.exposedSchemas.has(fn.schema))
+                reachable.add(key);
+            continue;
+        }
+        if (options.roles.some((role) => canExecute(fn, role, options)))
+            reachable.add(key);
+    }
+    return reachable;
+}
+function canExecute(fn, role, { graph, schemaAcls }) {
+    if (!canEnterSchema(fn.schema, role, graph, schemaAcls))
+        return false;
+    const attrs = graph.get(role);
+    if (attrs?.isSuper)
+        return true;
+    if (role === fn.owner)
+        return true;
+    return fn.grants.some((g) => g.role === 'PUBLIC'
+        || g.role === role
+        || (attrs?.inheritsFrom ?? []).includes(g.role));
+}

package/esm/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Public surface of `safegres` — a pure-PostgreSQL Row-Level-Security auditor.
+ *
+ * The auditor introspects pg_class / pg_policy / role grants and emits
+ * structured findings (A1–A7, P1, P5). It has no knowledge of any specific
+ * application schema or policy DSL.
+ */
+export { parsePolicyExpression, type PgAstNode, type PolicyExpression, PolicyParseError } from './ast/parse';
+export type { BaselineBoundary, CallGraphBaseline, CallGraphDiff } from './callgraph/baseline';
+export { boundaryKey, diffCallGraph, parseBaseline, serializeBaseline, toBaseline } from './callgraph/baseline';
+export type { CallGraphEdge, CallGraphNode, CallGraphOptions, CallGraphReport, ChecklistCode, ChecklistItem } from './callgraph/graph';
+export { buildCallGraph } from './callgraph/graph';
+export { checkUntrustedColumnGrants } from './checks/column-grants';
+export type { FunctionBodyAnalysis } from './checks/definer-function';
+export { analyzeFunctionBodies, checkDefinerFunctionReach, checkInsteadOfTriggerWrite, checkUnreadableFunctionReach } from './checks/definer-function';
+export type { SuppressedView, ViewBodyAnalysis } from './checks/definer-view';
+export { analyzeViewBodies, checkDefinerViewBypass, checkUnauditedViewReach, checkUnreadableViewReach } from './checks/definer-view';
+export { checkMissingPrimaryKey, checkRedundantIndexes, checkUnindexedForeignKeys, checkUnindexedSearchColumns, checkUnindexedSortColumns } from './checks/indexes';
+export type { EffectiveColumnGrant, EffectiveGrant, GrantVia, LatticeRoleOptions, RoleAccessEntry, RoleAccessRelation, RoleGraph } from './checks/lattice';
+export { checkDeadPolicies, checkDeadSchemaUsage, checkIndirectCoverageGaps, checkUnreachableGrants, checkUntrustedIndirectAccess, computeRoleAccess, effectiveColumnGrants, effectiveGrants } from './checks/lattice';
+export { checkUntrustedForeignTableGrants, checkUntrustedSequenceGrants } from './checks/object-acls';
+export type { PolicyClause, PredicateColumn } from './checks/policy-index';
+export { checkNonLeakproofPolicyFunctions, checkPolicyColumnCasts, checkUnhoistedPolicyFunctions, checkUnindexedPolicyColumns, collectPredicateColumns } from './checks/policy-index';
+export type { RoleTrustOptions } from './checks/role-trust';
+export { checkPublicGrants, checkUntrustedRolePolicies, checkUntrustedRoleWrites } from './checks/role-trust';
+export type { StatsThresholds } from './checks/stats';
+export { checkDeadTuples, checkSeqScanDominant, checkStats, checkTopStatements, checkUnusedIndexes, DEFAULT_STATS_THRESHOLDS } from './checks/stats';
+export type { ViewExposureAnalysis } from './checks/view-exposure';
+export { analyzeViewExposure, checkLeakyFilterView, checkMatviewSnapshot } from './checks/view-exposure';
+export type { ViewWriteAnalysis } from './checks/view-writes';
+export { analyzeViewWrites, checkDefinerViewWrite, checkUncheckedViewWrite, checkViewRuleBypass } from './checks/view-writes';
+export type { BaselineCandidate, BaselineSelection, ChosenBaseline, RejectedCandidate, SelectBaselineOptions } from './ci/baseline';
+export { CANDIDATE_LIMIT, MAX_BASELINE_AGE_MS, selectBaseline } from './ci/baseline';
+export type { GithubBaselineOptions, GithubBaselineResult } from './ci/github';
+export { selectGithubBaseline } from './ci/github';
+export type { AuditOptions } from './commands/audit';
+export { audit } from './commands/audit';
+export type { DoctorCheck, DoctorOptions, DoctorReport, DoctorStatus } from './commands/doctor';
+export { doctor } from './commands/doctor';
+export type { EvalCaseResult, EvalOptions, EvalReport } from './commands/eval';
+export { runEval } from './commands/eval';
+export type { Provenance } from './config/fingerprint';
+export { configFingerprint } from './config/fingerprint';
+export type { LoadConfigParams } from './config/loader';
+export { loadConfig, safegresConfigLoader } from './config/loader';
+export { constructive, graphile, hasura, minimal, multiTenant, oltp, postgrest, PRESETS, recommended, strict, supabase } from './config/presets';
+export type { ResolvedRule, ResolvedRules } from './config/resolve';
+export { allAstRulesDisabled, applyRulesToFindings, ConfigValidationError, defaultRuleMap, matchTablePattern, resolveRules, ruleCodesForDimension, rulesForTable } from './config/resolve';
+export { CONFIG_SHAPE, SCHEMA_ID, toJsonSchema } from './config/schema';
+export type { CallGraphConfig, EvalConfig, ExposureConfig, FailOnConfig, GithubCommentConfig, GithubReportConfig, Grade, OutputsConfig, OverrideEntry, PerfConfig, PlaneConfig, PlaneFailOnConfig, PlaneKind, ReportConfig, RulesConfig, RuleSetting, SafegresConfig, ScoringConfig, SourceConfig } from './config/types';
+export { validateConfigShape } from './config/validate';
+export type { CaseResult, CorpusCase, ExpectedFinding } from './corpus';
+export { corpusBootstrap, corpusDir, gradeCase, loadCase, loadCorpus } from './corpus';
+export type { ExposureAdapter, PlaneInput, ReachContext } from './exposure/adapters';
+export { BUILTIN_ADAPTERS, constructiveAdapter, definePlanes, graphileAdapter, hasuraAdapter, postgraphileAdapter, postgrestAdapter, resolveAdapters, supabaseAdapter } from './exposure/adapters';
+export type { PlaneReach } from './exposure/planes';
+export { onPlane, relationKey, resolvePlaneReach, scorePlane, stampPlanes } from './exposure/planes';
+export type { ApiReach, ReachEdge, ReachInputs, UnreachableRelation } from './exposure/reach';
+export { BACKWARD_ABILITIES, computeApiReach, FORWARD_ABILITIES, ROOT_ABILITIES } from './exposure/reach';
+export type { BaselineFinding, PerfBaseline, PerfDiff } from './perf/baseline';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
+export type { ExplainOptions, ExplainReport } from './perf/explain';
+export { proveFindings } from './perf/explain';
+export type { RoleAttributes, SchemaAclGrant, SchemaAclInfo, SchemaAclOptions } from './pg/acl';
+export { introspectRoleGraph, introspectSchemaAcls } from './pg/acl';
+export type { ResolvedExposure, ResolvedPlane } from './pg/exposure';
+export { resolveConstructiveExposure, resolveExposure, resolvePlanes, resolveReach, UNKNOWN_EXPOSURE } from './pg/exposure';
+export type { FunctionGrant, FunctionSnapshot, IntrospectFunctionOptions } from './pg/functions';
+export { introspectFunctions } from './pg/functions';
+export type { ColumnInfo, ForeignKeyInfo, IndexInfo, TableIndexSnapshot, ViewSnapshot } from './pg/indexes';
+export { introspectIndexes, introspectViews } from './pg/indexes';
+export { type ColumnGrantInfo, type GrantInfo, type IntrospectOptions, introspectTables, type PgPrivilege, type PolicyCmd, type PolicyInfo, type QueryExecutor, type TableSnapshot } from './pg/introspect';
+export type { ObjectAclSnapshot, PgObjectKind } from './pg/objects';
+export { introspectObjectAcls } from './pg/objects';
+export { listAuditableRoles, resolveRoles } from './pg/roles';
+export type { IndexUsage, StatementUsage, StatsSnapshot, TableUsage } from './pg/stats';
+export { introspectStats } from './pg/stats';
+export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
+export type { BaselineProvenance, DimensionSnapshot, ReportComparison, ReportSnapshot, RuleDelta, ScoreDelta } from './report/compare';
+export { baselineLabel, compareReports, describeBaseline, formatAge, formatDelta, parseSnapshot, serializeSnapshot, toSnapshot } from './report/compare';
+export type { GithubRenderOptions } from './report/github';
+export { COMMENT_MARKER, emitGithub, gradeBadge, postStickyComment, renderAnnotations, renderGithubComment, renderGithubSummary, scoreBadge } from './report/github';
+export { renderJson } from './report/json';
+export type { RenderMarkdownOptions } from './report/markdown';
+export { renderMarkdown } from './report/markdown';
+export type { RenderPrettyOptions } from './report/pretty';
+export { renderPretty } from './report/pretty';
+export type { BuildSourceIndexOptions, RenderSarifOptions, SourceIndex, SourceLocation } from './report/sarif';
+export { buildSourceIndex, renderSarif } from './report/sarif';
+export type { ReportView, ViewConfig, ViewDimension, ViewFindings, ViewScore, ViewSection } from './report/view';
+export { ALL_SECTIONS, matchPlane, selectView, viewConfigFromReportConfig } from './report/view';
+export type { RuleMeta } from './rules/registry';
+export { dimensionOf, expandRuleSelector, isKnownRule, RULES, RULES_BY_CODE } from './rules/registry';
+export type { Score, ScoreContext, ScoreDeduction } from './score/score';
+export { computeScore, DEFAULT_GRADE_BANDS, DEFAULT_WEIGHTS, meetsGrade } from './score/score';
+export * from './types';

package/esm/index.js

@@ -1,6 +1,57 @@
-export * from './admin';
-export * from './connect';
-export * from './manager';
-export * from './roles';
-export * from './seed';
-export * from './test-client';
+/**
+ * Public surface of `safegres` — a pure-PostgreSQL Row-Level-Security auditor.
+ *
+ * The auditor introspects pg_class / pg_policy / role grants and emits
+ * structured findings (A1–A7, P1, P5). It has no knowledge of any specific
+ * application schema or policy DSL.
+ */
+export { parsePolicyExpression, PolicyParseError } from './ast/parse';
+export { boundaryKey, diffCallGraph, parseBaseline, serializeBaseline, toBaseline } from './callgraph/baseline';
+export { buildCallGraph } from './callgraph/graph';
+export { checkUntrustedColumnGrants } from './checks/column-grants';
+export { analyzeFunctionBodies, checkDefinerFunctionReach, checkInsteadOfTriggerWrite, checkUnreadableFunctionReach } from './checks/definer-function';
+export { analyzeViewBodies, checkDefinerViewBypass, checkUnauditedViewReach, checkUnreadableViewReach } from './checks/definer-view';
+export { checkMissingPrimaryKey, checkRedundantIndexes, checkUnindexedForeignKeys, checkUnindexedSearchColumns, checkUnindexedSortColumns } from './checks/indexes';
+export { checkDeadPolicies, checkDeadSchemaUsage, checkIndirectCoverageGaps, checkUnreachableGrants, checkUntrustedIndirectAccess, computeRoleAccess, effectiveColumnGrants, effectiveGrants } from './checks/lattice';
+export { checkUntrustedForeignTableGrants, checkUntrustedSequenceGrants } from './checks/object-acls';
+export { checkNonLeakproofPolicyFunctions, checkPolicyColumnCasts, checkUnhoistedPolicyFunctions, checkUnindexedPolicyColumns, collectPredicateColumns } from './checks/policy-index';
+export { checkPublicGrants, checkUntrustedRolePolicies, checkUntrustedRoleWrites } from './checks/role-trust';
+export { checkDeadTuples, checkSeqScanDominant, checkStats, checkTopStatements, checkUnusedIndexes, DEFAULT_STATS_THRESHOLDS } from './checks/stats';
+export { analyzeViewExposure, checkLeakyFilterView, checkMatviewSnapshot } from './checks/view-exposure';
+export { analyzeViewWrites, checkDefinerViewWrite, checkUncheckedViewWrite, checkViewRuleBypass } from './checks/view-writes';
+export { CANDIDATE_LIMIT, MAX_BASELINE_AGE_MS, selectBaseline } from './ci/baseline';
+export { selectGithubBaseline } from './ci/github';
+export { audit } from './commands/audit';
+export { doctor } from './commands/doctor';
+export { runEval } from './commands/eval';
+export { configFingerprint } from './config/fingerprint';
+export { loadConfig, safegresConfigLoader } from './config/loader';
+export { constructive, graphile, hasura, minimal, multiTenant, oltp, postgrest, PRESETS, recommended, strict, supabase } from './config/presets';
+export { allAstRulesDisabled, applyRulesToFindings, ConfigValidationError, defaultRuleMap, matchTablePattern, resolveRules, ruleCodesForDimension, rulesForTable } from './config/resolve';
+export { CONFIG_SHAPE, SCHEMA_ID, toJsonSchema } from './config/schema';
+export { validateConfigShape } from './config/validate';
+export { corpusBootstrap, corpusDir, gradeCase, loadCase, loadCorpus } from './corpus';
+export { BUILTIN_ADAPTERS, constructiveAdapter, definePlanes, graphileAdapter, hasuraAdapter, postgraphileAdapter, postgrestAdapter, resolveAdapters, supabaseAdapter } from './exposure/adapters';
+export { onPlane, relationKey, resolvePlaneReach, scorePlane, stampPlanes } from './exposure/planes';
+export { BACKWARD_ABILITIES, computeApiReach, FORWARD_ABILITIES, ROOT_ABILITIES } from './exposure/reach';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
+export { proveFindings } from './perf/explain';
+export { introspectRoleGraph, introspectSchemaAcls } from './pg/acl';
+export { resolveConstructiveExposure, resolveExposure, resolvePlanes, resolveReach, UNKNOWN_EXPOSURE } from './pg/exposure';
+export { introspectFunctions } from './pg/functions';
+export { introspectIndexes, introspectViews } from './pg/indexes';
+export { introspectTables } from './pg/introspect';
+export { introspectObjectAcls } from './pg/objects';
+export { listAuditableRoles, resolveRoles } from './pg/roles';
+export { introspectStats } from './pg/stats';
+export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
+export { baselineLabel, compareReports, describeBaseline, formatAge, formatDelta, parseSnapshot, serializeSnapshot, toSnapshot } from './report/compare';
+export { COMMENT_MARKER, emitGithub, gradeBadge, postStickyComment, renderAnnotations, renderGithubComment, renderGithubSummary, scoreBadge } from './report/github';
+export { renderJson } from './report/json';
+export { renderMarkdown } from './report/markdown';
+export { renderPretty } from './report/pretty';
+export { buildSourceIndex, renderSarif } from './report/sarif';
+export { ALL_SECTIONS, matchPlane, selectView, viewConfigFromReportConfig } from './report/view';
+export { dimensionOf, expandRuleSelector, isKnownRule, RULES, RULES_BY_CODE } from './rules/registry';
+export { computeScore, DEFAULT_GRADE_BANDS, DEFAULT_WEIGHTS, meetsGrade } from './score/score';
+export * from './types';

package/esm/lint/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Source-level SQL/PL/pgSQL convention linter.
+ *
+ * This module used to carry safegres's own copy of the linter. It now lives in
+ * the standalone `@pgsql/lint` package (source text in → findings out, no `pg`
+ * dependency); safegres consumes it as "the catalog adapter", feeding it the
+ * `pg_get_functiondef` text it already reads. This file is a thin re-export so
+ * the rest of safegres keeps importing from `../lint` unchanged.
+ */
+export type { DynamicSqlSite, LintOptions, LintProblem, LintResult, LintRule, LintRuleMeta, LintUnit, SqlFragment, SuppressedProblem, SuppressionScope } from '@pgsql/lint';
+export { LINT_RULES, LINT_RULES_BY_CODE, LINT_RULES_BY_ID, lintDefinition, parseUnit, Suppressions } from '@pgsql/lint';

package/esm/lint/index.js

@@ -0,0 +1,10 @@
+/**
+ * Source-level SQL/PL/pgSQL convention linter.
+ *
+ * This module used to carry safegres's own copy of the linter. It now lives in
+ * the standalone `@pgsql/lint` package (source text in → findings out, no `pg`
+ * dependency); safegres consumes it as "the catalog adapter", feeding it the
+ * `pg_get_functiondef` text it already reads. This file is a thin re-export so
+ * the rest of safegres keeps importing from `../lint` unchanged.
+ */
+export { LINT_RULES, LINT_RULES_BY_CODE, LINT_RULES_BY_ID, lintDefinition, parseUnit, Suppressions } from '@pgsql/lint';

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/perf/explain.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Proof by EXPLAIN (`--explain`).
+ *
+ * The `X*` rules infer from the catalog that a query *shape* has no index to
+ * serve it. This turns the inference into evidence: for each finding that has
+ * a probe shape, plan the query the finding is about and read the plan back.
+ *
+ * The planner is the authority, so the interesting outcome is disagreement —
+ * a finding whose probe plans as an index scan is **refuted** (some index the
+ * catalog rules didn't credit does serve it) and stops counting against the
+ * score. The reverse is not symmetrical: an empty or unanalyzed table always
+ * seq-scans, so a seq scan only *confirms* a finding above the row floor;
+ * below it the probe is inconclusive and the finding is left exactly as it
+ * was.
+ *
+ * Probes use `EXPLAIN (GENERIC_PLAN)` — parameters stay parameters, nothing
+ * is executed, and no value has to be invented for a column whose domain we
+ * know nothing about. That requires PostgreSQL 16+.
+ */
+import type { TableIndexSnapshot } from '../pg/indexes';
+import type { QueryExecutor } from '../pg/introspect';
+import type { Finding } from '../types';
+export interface ExplainOptions {
+    /**
+     * Below this planner row estimate a sequential scan is the correct plan, so
+     * a seq-scan result proves nothing. Default 1000.
+     */
+    minRows?: number;
+}
+export interface ExplainReport {
+    /** Findings that were probed. */
+    probed: number;
+    /** Probes whose plan showed the scan the finding predicted. */
+    confirmed: number;
+    /** Probes the planner served with an index — the finding was wrong. */
+    refuted: number;
+    /** Probes on tables too small for the plan to mean anything. */
+    inconclusive: number;
+    /** Why probing was skipped entirely, when it was. */
+    unavailable?: string;
+}
+/**
+ * Plan a probe for every probeable perf finding and annotate it in place.
+ * Findings the planner refutes are acknowledged (reported, unscored).
+ */
+export declare function proveFindings(exec: QueryExecutor, findings: Finding[], tables: Map<string, TableIndexSnapshot>, options?: ExplainOptions): Promise<ExplainReport>;