@safegres/test 0.0.2 → 1.30.7

package/commands/doctor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `safegres doctor` — diagnose the environment before/alongside an audit:
+ * connection health, catalog visibility, audit blind spots, parser
+ * availability, and configuration problems.
+ */
+import { type LoadConfigParams } from '../config/loader';
+import { type QueryExecutor } from '../pg/introspect';
+export type DoctorStatus = 'ok' | 'warn' | 'fail';
+export interface DoctorCheck {
+    name: string;
+    status: DoctorStatus;
+    detail: string;
+}
+export interface DoctorReport {
+    checks: DoctorCheck[];
+    ok: boolean;
+}
+export type DoctorOptions = LoadConfigParams;
+export declare function doctor(client: QueryExecutor | null, options?: DoctorOptions): Promise<DoctorReport>;

package/commands/doctor.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * `safegres doctor` — diagnose the environment before/alongside an audit:
+ * connection health, catalog visibility, audit blind spots, parser
+ * availability, and configuration problems.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctor = doctor;
+const parse_1 = require("../ast/parse");
+const loader_1 = require("../config/loader");
+const resolve_1 = require("../config/resolve");
+const exposure_1 = require("../pg/exposure");
+const introspect_1 = require("../pg/introspect");
+async function doctor(client, options = {}) {
+    const checks = [];
+    let exposureConfig;
+    let publicRead = [];
+    // --- configuration ---
+    try {
+        const loaded = (0, loader_1.loadConfig)(options);
+        exposureConfig = loaded.config.exposure;
+        publicRead = loaded.config.public?.read ?? [];
+        if (loaded.isEmpty) {
+            checks.push({
+                name: 'config',
+                status: 'ok',
+                detail: 'no config file found — using built-in defaults (safegres:recommended behavior)'
+            });
+        }
+        else {
+            checks.push({ name: 'config', status: 'ok', detail: `loaded ${loaded.filepath}` });
+        }
+        try {
+            const resolved = (0, resolve_1.resolveRules)(loaded.config);
+            const disabled = [...resolved.rules.entries()].filter(([, r]) => !r.enabled).map(([c]) => c);
+            checks.push({
+                name: 'rules',
+                status: 'ok',
+                detail: disabled.length > 0
+                    ? `${resolved.rules.size - disabled.length} enabled, ${disabled.length} disabled (${disabled.join(', ')})`
+                    : `all ${resolved.rules.size} rules enabled`
+            });
+        }
+        catch (err) {
+            checks.push({ name: 'rules', status: 'fail', detail: err.message });
+        }
+    }
+    catch (err) {
+        checks.push({ name: 'config', status: 'fail', detail: err.message });
+    }
+    // --- SQL parser ---
+    try {
+        await (0, parse_1.parsePolicyExpression)('true');
+        checks.push({ name: 'parser', status: 'ok', detail: 'pgsql-parser is available (AST rules can run)' });
+    }
+    catch (err) {
+        checks.push({
+            name: 'parser',
+            status: 'warn',
+            detail: `pgsql-parser unavailable — AST rules (A7, P1, P1b, P5) will be skipped: ${err.message}`
+        });
+    }
+    // --- database ---
+    if (!client) {
+        checks.push({
+            name: 'connection',
+            status: 'fail',
+            detail: 'could not connect — check PG* env vars or --connection'
+        });
+        return finish(checks);
+    }
+    const exec = (0, introspect_1.asExecutor)(client);
+    try {
+        const { rows } = await exec.query('SELECT version() AS version, current_user AS usr, current_database() AS db');
+        checks.push({
+            name: 'connection',
+            status: 'ok',
+            detail: `${rows[0].db} as ${rows[0].usr} — ${rows[0].version.split(' on ')[0]}`
+        });
+    }
+    catch (err) {
+        checks.push({ name: 'connection', status: 'fail', detail: err.message });
+        return finish(checks);
+    }
+    try {
+        const { rows } = await exec.query('SELECT count(*)::text AS n FROM pg_policy');
+        checks.push({ name: 'catalog', status: 'ok', detail: `pg_policy readable (${rows[0].n} policies)` });
+    }
+    catch (err) {
+        checks.push({
+            name: 'catalog',
+            status: 'fail',
+            detail: `cannot read pg_policy — the audit needs catalog access: ${err.message}`
+        });
+    }
+    try {
+        const { rows } = await exec.query('SELECT rolsuper AS super, rolbypassrls AS bypass FROM pg_roles WHERE rolname = current_user');
+        const { super: isSuper, bypass } = rows[0] ?? { super: false, bypass: false };
+        if (isSuper || bypass) {
+            checks.push({
+                name: 'privileges',
+                status: 'ok',
+                detail: `current role ${isSuper ? 'is superuser' : 'has BYPASSRLS'} — full catalog visibility`
+            });
+        }
+        else {
+            checks.push({
+                name: 'privileges',
+                status: 'warn',
+                detail: 'current role is not superuser and lacks BYPASSRLS — policies/grants on tables it cannot see will be missing from the audit'
+            });
+        }
+    }
+    catch (err) {
+        checks.push({ name: 'privileges', status: 'warn', detail: err.message });
+    }
+    try {
+        const { rows } = await exec.query(`SELECT count(*)::text AS n FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE c.relkind IN ('r','p') AND c.relrowsecurity
+         AND n.nspname NOT IN ('pg_catalog','information_schema')`);
+        const n = Number(rows[0].n);
+        checks.push({
+            name: 'rls',
+            status: n > 0 ? 'ok' : 'warn',
+            detail: n > 0
+                ? `${n} table(s) have RLS enabled`
+                : 'no tables with RLS enabled — nothing for coverage/anti-pattern rules to audit'
+        });
+    }
+    catch (err) {
+        checks.push({ name: 'rls', status: 'warn', detail: err.message });
+    }
+    // --- exposure surface ---
+    try {
+        const exposure = await (0, exposure_1.resolveExposure)(exec, exposureConfig);
+        if (exposure.known) {
+            checks.push({
+                name: 'exposure',
+                status: 'ok',
+                detail: `${exposure.schemas.length} exposed schema(s) via ${exposure.source}${exposure.roles && exposure.roles.length > 0 ? ` (api roles: ${exposure.roles.join(', ')})` : ''}`
+            });
+        }
+        else {
+            checks.push({
+                name: 'exposure',
+                status: 'warn',
+                detail: 'no exposure surface configured — the audit assumes the whole database is reachable and caps the score. Declare `exposure.schemas` or use `exposure.resolver: "constructive"`.'
+            });
+        }
+    }
+    catch (err) {
+        checks.push({ name: 'exposure', status: 'warn', detail: err.message });
+    }
+    // --- declared public surface ---
+    if (publicRead.length > 0) {
+        try {
+            const { rows } = await exec.query(`SELECT n.nspname || '.' || c.relname AS qualified
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         WHERE c.relkind IN ('r','p')
+           AND n.nspname NOT IN ('pg_catalog','information_schema')`);
+            const qualified = rows.map((r) => r.qualified);
+            const stale = publicRead.filter((p) => !qualified.some((q) => (0, resolve_1.matchTablePattern)(p, q)));
+            checks.push({
+                name: 'public',
+                status: stale.length > 0 ? 'warn' : 'ok',
+                detail: stale.length > 0
+                    ? `stale \`public.read\` pattern(s) match no table: ${stale.join(', ')}`
+                    : `${publicRead.length} \`public.read\` pattern(s), all match at least one table`
+            });
+        }
+        catch (err) {
+            checks.push({ name: 'public', status: 'warn', detail: err.message });
+        }
+    }
+    return finish(checks);
+}
+function finish(checks) {
+    return { checks, ok: checks.every((c) => c.status !== 'fail') };
+}

package/commands/eval.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `safegres eval` — grade the auditor against a corpus with known answers.
+ *
+ * The audit answers "what is wrong with this database". Eval answers the
+ * question one level up: *is the auditor right?* It deploys each corpus case
+ * into a live database, audits it under a sealed preset, and grades the report
+ * against the case's answer key — recall (every expected finding present) and
+ * precision (nothing the case forbids).
+ *
+ * That makes it three things with one implementation: safegres's own
+ * calibration check, a harness an agent can be scored against (fix the case,
+ * re-run, require the findings to disappear), and a demonstration that the
+ * rules mean what the docs say.
+ */
+import type { Grade, SafegresConfig } from '../config/types';
+import { type CaseResult, type CorpusCase } from '../corpus';
+import { type QueryExecutor } from '../pg/introspect';
+export interface EvalOptions {
+    /**
+     * The configuration cases are graded under. Normally a sealed preset: the
+     * corpus measures the rules, so a local config file editing them would be
+     * measuring the wrong thing.
+     */
+    config?: SafegresConfig;
+    /** The preset name, recorded in each report's provenance. */
+    preset?: string;
+    /** Corpus directory. Defaults to the corpus shipped with the package. */
+    corpus?: string;
+    /** Case ids (or id prefixes) to run. Defaults to all of them. */
+    cases?: string[];
+    /** Skip the role bootstrap — for a database that already has the roles. */
+    skipBootstrap?: boolean;
+    /** Leave each case's schemas in the database instead of dropping them. */
+    keep?: boolean;
+    /** Called as each case finishes, for streaming progress. */
+    onResult?: (result: EvalCaseResult) => void;
+}
+export interface EvalCaseResult extends CaseResult {
+    title: string;
+    dimension: CorpusCase['dimension'];
+    /** The score on the case's own dimension, after its flaw is accounted for. */
+    score: number;
+    grade: Grade;
+    /** The answer key, so a failing case reads as an instruction. */
+    fix: string;
+}
+export interface EvalReport {
+    generatedAt: string;
+    /** The preset every case was graded under. */
+    preset?: string;
+    /** Configuration fingerprint shared by every case's report. */
+    fingerprint?: string;
+    sealed: boolean;
+    total: number;
+    passed: number;
+    /** Expected findings produced / expected findings total. */
+    recall: number;
+    /** Cases that produced no forbidden finding / cases total. */
+    precision: number;
+    results: EvalCaseResult[];
+}
+/**
+ * Deploy, audit and grade every selected case. Each case owns its schemas —
+ * its SQL drops them first — so cases neither see nor disturb each other, and
+ * the database is left as it was found unless `keep` says otherwise.
+ */
+export declare function runEval(client: QueryExecutor, options?: EvalOptions): Promise<EvalReport>;

package/commands/eval.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * `safegres eval` — grade the auditor against a corpus with known answers.
+ *
+ * The audit answers "what is wrong with this database". Eval answers the
+ * question one level up: *is the auditor right?* It deploys each corpus case
+ * into a live database, audits it under a sealed preset, and grades the report
+ * against the case's answer key — recall (every expected finding present) and
+ * precision (nothing the case forbids).
+ *
+ * That makes it three things with one implementation: safegres's own
+ * calibration check, a harness an agent can be scored against (fix the case,
+ * re-run, require the findings to disappear), and a demonstration that the
+ * rules mean what the docs say.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEval = runEval;
+const corpus_1 = require("../corpus");
+const introspect_1 = require("../pg/introspect");
+const audit_1 = require("./audit");
+function selectCases(all, ids) {
+    if (!ids || ids.length === 0)
+        return all;
+    const selected = all.filter((c) => ids.some((id) => c.id === id || c.id.startsWith(id)));
+    if (selected.length === 0) {
+        throw new Error(`No corpus case matches ${ids.join(', ')}. Available: ${all.map((c) => c.id).join(', ')}`);
+    }
+    return selected;
+}
+/**
+ * Deploy, audit and grade every selected case. Each case owns its schemas —
+ * its SQL drops them first — so cases neither see nor disturb each other, and
+ * the database is left as it was found unless `keep` says otherwise.
+ */
+async function runEval(client, options = {}) {
+    const exec = (0, introspect_1.asExecutor)(client);
+    const cases = selectCases((0, corpus_1.loadCorpus)(options.corpus), options.cases);
+    if (!options.skipBootstrap)
+        await exec.query((0, corpus_1.corpusBootstrap)());
+    const results = [];
+    let fingerprint;
+    let sealed = false;
+    for (const c of cases) {
+        await exec.query(c.sql);
+        try {
+            const report = await (0, audit_1.audit)(exec, {
+                config: options.config,
+                exposure: c.exposure,
+                schemas: c.exposure.schemas,
+                perf: true,
+                sealed: true,
+                ...(options.preset ? { preset: options.preset } : {})
+            });
+            fingerprint ??= report.provenance?.fingerprint;
+            sealed = report.provenance?.sealed ?? false;
+            const score = c.dimension === 'perf' ? report.perf?.score : report.score;
+            const result = {
+                ...(0, corpus_1.gradeCase)(report, c),
+                title: c.title,
+                dimension: c.dimension,
+                score: score?.value ?? 100,
+                grade: score?.grade ?? 'A+',
+                fix: c.fix
+            };
+            results.push(result);
+            options.onResult?.(result);
+        }
+        finally {
+            if (!options.keep) {
+                for (const schema of c.exposure.schemas ?? []) {
+                    await exec.query(`DROP SCHEMA IF EXISTS ${quoteIdent(schema)} CASCADE`);
+                }
+            }
+        }
+    }
+    const expected = results.reduce((n, r) => n + r.found.length + r.missed.length, 0);
+    const found = results.reduce((n, r) => n + r.found.length, 0);
+    const clean = results.filter((r) => r.falsePositives.length === 0).length;
+    return {
+        generatedAt: new Date().toISOString(),
+        ...(options.preset ? { preset: options.preset } : {}),
+        ...(fingerprint ? { fingerprint } : {}),
+        sealed,
+        total: results.length,
+        passed: results.filter((r) => r.passed).length,
+        recall: expected === 0 ? 1 : found / expected,
+        precision: results.length === 0 ? 1 : clean / results.length,
+        results
+    };
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}

package/config/fingerprint.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Provenance: proving *which rules* produced a score.
+ *
+ * Every knob that moves the number — a rule's severity, an override, a perf
+ * ignore, the exposed surface, the scoring weights — is deliberate and useful
+ * to a developer declaring intent in CI. To an evaluation harness scoring an
+ * agent, the same knobs are the cheapest way to win: turn off the rule, or
+ * re-baseline the debt, and the score goes up without the database changing.
+ *
+ * So a report carries a fingerprint of the configuration it was produced
+ * under. Two runs with the same fingerprint were graded by the same rules and
+ * are comparable; a different fingerprint means the ruler changed, and a
+ * harness can reject the run instead of believing the number.
+ *
+ * The fingerprint covers the *resolved* rules rather than the config text, so
+ * it is invariant to how the same posture was expressed (preset vs. explicit
+ * rules, key order, whitespace) and sensitive to anything that changes it.
+ */
+import type { SafegresConfig } from './types';
+/** Everything about a run that a comparison must be able to trust. */
+export interface Provenance {
+    /** The safegres version that produced the report. */
+    version: string;
+    /** `sha256:<hex>` over the resolved, score-relevant configuration. */
+    fingerprint: string;
+    /**
+     * True when the run refused local configuration: no discovered config file,
+     * no rule overrides, no baselines. An evaluation harness should require it.
+     */
+    sealed: boolean;
+    /** The preset the sealed run was graded under, when one was named. */
+    preset?: string;
+}
+/**
+ * `sha256:<hex>` over the resolved scoring surface and the safegres version.
+ * The version participates because a rule's *meaning* can change without its
+ * configuration changing, and two scores from different analyzers are no more
+ * comparable than two scores from different rule sets.
+ */
+export declare function configFingerprint(config: SafegresConfig, version: string): string;

package/config/fingerprint.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Provenance: proving *which rules* produced a score.
+ *
+ * Every knob that moves the number — a rule's severity, an override, a perf
+ * ignore, the exposed surface, the scoring weights — is deliberate and useful
+ * to a developer declaring intent in CI. To an evaluation harness scoring an
+ * agent, the same knobs are the cheapest way to win: turn off the rule, or
+ * re-baseline the debt, and the score goes up without the database changing.
+ *
+ * So a report carries a fingerprint of the configuration it was produced
+ * under. Two runs with the same fingerprint were graded by the same rules and
+ * are comparable; a different fingerprint means the ruler changed, and a
+ * harness can reject the run instead of believing the number.
+ *
+ * The fingerprint covers the *resolved* rules rather than the config text, so
+ * it is invariant to how the same posture was expressed (preset vs. explicit
+ * rules, key order, whitespace) and sensitive to anything that changes it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configFingerprint = configFingerprint;
+const crypto_1 = require("crypto");
+const resolve_1 = require("./resolve");
+/**
+ * A canonical JSON encoding: object keys sorted at every depth, so two configs
+ * that mean the same thing hash the same regardless of how they were written.
+ */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b));
+        return Object.fromEntries(entries.map(([k, v]) => [k, canonical(v)]));
+    }
+    return value;
+}
+/**
+ * The score-relevant projection of a config. Deliberately *not* the whole
+ * config: connection parameters, output formats and renderer options cannot
+ * move the number, and hashing them would make every run look incomparable.
+ */
+function scoringSurface(config) {
+    const { rules } = (0, resolve_1.resolveRules)(config);
+    return {
+        rules: [...rules.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([code, rule]) => [code, rule.enabled, rule.severity, canonical(rule.options ?? null)]),
+        overrides: (config.overrides ?? []).map((o) => canonical(o)),
+        scoring: canonical(config.scoring ?? {}),
+        publicRead: [...(config.public?.read ?? [])].sort(),
+        perfIgnore: [...(config.perf?.ignore ?? [])].sort(),
+        exposure: canonical({
+            ...config.exposure,
+            // An adapter is code, not data: identify it by name and let the version
+            // field carry the rest.
+            adapters: (config.exposure?.adapters ?? []).map((a) => typeof a === 'string' ? a : a.name)
+        })
+    };
+}
+/**
+ * `sha256:<hex>` over the resolved scoring surface and the safegres version.
+ * The version participates because a rule's *meaning* can change without its
+ * configuration changing, and two scores from different analyzers are no more
+ * comparable than two scores from different rule sets.
+ */
+function configFingerprint(config, version) {
+    const payload = JSON.stringify({ version, config: scoringSurface(config) });
+    return `sha256:${(0, crypto_1.createHash)('sha256').update(payload).digest('hex')}`;
+}

package/config/loader.d.ts

@@ -0,0 +1,44 @@
+import { type ConfigLoader, type ExplainedValue, type LoadResult } from 'confstash';
+import type { SafegresConfig } from './types';
+export type { ConfigLoader, ExplainedValue, LoadResult };
+/**
+ * The safegres config loader. Discovers `safegres.config.{ts,js,mjs,cjs}`,
+ * `.safegresrc{,.json,.yaml,.yml,.js}`, `safegres.json`, or the `"safegres"`
+ * package.json key by walking up from cwd; resolves `extends` against the
+ * built-in presets (or files / npm packages).
+ */
+export declare function safegresConfigLoader(): ConfigLoader<SafegresConfig>;
+export interface LoadConfigParams {
+    cwd?: string;
+    /** Explicit config file (skips discovery). */
+    configFile?: string;
+    /** Preset applied when no `extends` handling is needed from a file (CLI --preset). */
+    preset?: string;
+    /** Highest-precedence partial config (parsed CLI flags). */
+    overrides?: Partial<SafegresConfig>;
+    /**
+     * Grade under a built-in preset alone: skip config-file discovery entirely,
+     * so nothing in the working tree can move the score. For an evaluation
+     * harness, where the configuration is part of what is being tested.
+     */
+    sealed?: boolean;
+}
+/**
+ * Where a configured *path* should resolve from. A repository that splits its
+ * config into a shared base and a per-job file has two directories in play,
+ * and `ci/baseline.json` written in the base means the base's `ci/`, whichever
+ * file inherited it.
+ */
+export interface ConfigPathBase {
+    /** Directory to resolve a value declared at this dotted key against. */
+    dirFor(key: string): string;
+}
+/** Load and merge the effective safegres config. */
+export declare function loadConfig(params?: LoadConfigParams): LoadResult<SafegresConfig>;
+/**
+ * Resolve each configured path against the file that declared it, so an
+ * inherited `perf.baseline` keeps pointing at the base file's directory.
+ * Values that came from a preset or from CLI overrides have no directory of
+ * their own and fall back to the discovered config file, then to `cwd`.
+ */
+export declare function configPathBase(result: LoadResult<SafegresConfig>, cwd?: string): ConfigPathBase;