@safegres/test 0.0.1 → 1.30.7

package/esm/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/esm/commands/doctor.js

@@ -0,0 +1,178 @@
+/**
+ * `safegres doctor` — diagnose the environment before/alongside an audit:
+ * connection health, catalog visibility, audit blind spots, parser
+ * availability, and configuration problems.
+ */
+import { parsePolicyExpression } from '../ast/parse';
+import { loadConfig } from '../config/loader';
+import { matchTablePattern, resolveRules } from '../config/resolve';
+import { resolveExposure } from '../pg/exposure';
+import { asExecutor } from '../pg/introspect';
+export async function doctor(client, options = {}) {
+    const checks = [];
+    let exposureConfig;
+    let publicRead = [];
+    // --- configuration ---
+    try {
+        const loaded = 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 = 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 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 = 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 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) => 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/esm/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/esm/commands/eval.js

@@ -0,0 +1,90 @@
+/**
+ * `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 { corpusBootstrap, gradeCase, loadCorpus } from '../corpus';
+import { asExecutor } from '../pg/introspect';
+import { audit } from './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.
+ */
+export async function runEval(client, options = {}) {
+    const exec = asExecutor(client);
+    const cases = selectCases(loadCorpus(options.corpus), options.cases);
+    if (!options.skipBootstrap)
+        await exec.query(corpusBootstrap());
+    const results = [];
+    let fingerprint;
+    let sealed = false;
+    for (const c of cases) {
+        await exec.query(c.sql);
+        try {
+            const report = await 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 = {
+                ...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/esm/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/esm/config/fingerprint.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { createHash } from 'crypto';
+import { resolveRules } from './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 } = 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.
+ */
+export function configFingerprint(config, version) {
+    const payload = JSON.stringify({ version, config: scoringSurface(config) });
+    return `sha256:${createHash('sha256').update(payload).digest('hex')}`;
+}

package/esm/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;

package/esm/config/loader.js

@@ -0,0 +1,172 @@
+import { createConfigLoader } from 'confstash';
+import * as path from 'path';
+import { PRESETS } from './presets';
+import { resolveRules } from './resolve';
+import { validateConfigShape } from './validate';
+/**
+ * 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 function safegresConfigLoader() {
+    return createConfigLoader({
+        tool: 'safegres',
+        presets: PRESETS,
+        defaults: {},
+        validate: (config) => {
+            validateConfigShape(config); // unknown keys, wrong value kinds
+            resolveRules(config); // throws ConfigValidationError on bad rules/overrides
+        }
+    });
+}
+/** Load and merge the effective safegres config. */
+export function loadConfig(params = {}) {
+    if (params.sealed)
+        return loadSealedConfig(params.preset);
+    const loader = safegresConfigLoader();
+    const overrides = { ...(params.overrides ?? {}) };
+    if (params.preset) {
+        const name = params.preset.includes(':') ? params.preset : `safegres:${params.preset}`;
+        if (!(name in PRESETS)) {
+            throw new Error(`Unknown preset "${params.preset}". Available: ${Object.keys(PRESETS).join(', ')}`);
+        }
+        overrides.extends = name;
+    }
+    // `extends` in overrides isn't expanded by confstash (it only expands file
+    // layers), so a CLI --preset is merged in as a layer *below* the file config.
+    const result = describeExtendsFailure(() => loader.loadSync({
+        cwd: params.cwd,
+        configFile: params.configFile,
+        overrides: stripExtends(overrides)
+    }));
+    const config = withUnionedOverrides(result);
+    if (params.preset) {
+        const presetConfig = PRESETS[overrides.extends];
+        return { ...result, config: mergePreset(presetConfig, config) };
+    }
+    return { ...result, config };
+}
+/**
+ * A missing `extends` target surfaces from the loader as a bare `ENOENT` on a
+ * path nobody typed — the resolved one. Say what it was reached from, and that
+ * a name is a preset while a path is a file, which is the actual mistake.
+ */
+function describeExtendsFailure(load) {
+    try {
+        return load();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes('ENOENT'))
+            throw error;
+        throw new Error(`${message}\nsafegres: an "extends" target could not be read. A built-in preset is a name `
+            + `(${Object.keys(PRESETS).join(', ')}); anything else is resolved as a path relative to `
+            + 'the file that declared it, or as an npm package.');
+    }
+}
+/**
+ * `overrides` is a list of scoped exceptions, so inheriting one file from
+ * another has to *add* to it. Array-typed keys otherwise replace — a child
+ * that narrows `exposure.schemas` means the narrower list — but replacing here
+ * would silently drop the base file's exceptions, which is how a shared config
+ * turns into two divergent copies. Preset chains have always unioned it; this
+ * makes a file chain agree.
+ */
+function withUnionedOverrides(result) {
+    const seen = new Set();
+    const unioned = [];
+    for (const layer of result.layers) {
+        for (const override of layer.config.overrides ?? []) {
+            const key = JSON.stringify(override);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            unioned.push(override);
+        }
+    }
+    if (unioned.length === 0)
+        return result.config;
+    return { ...result.config, overrides: unioned };
+}
+/**
+ * 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 function configPathBase(result, cwd = process.cwd()) {
+    const fallback = result.filepath ? path.dirname(result.filepath) : cwd;
+    return {
+        dirFor(key) {
+            // Highest precedence first: the layer that won the merge is the layer
+            // whose directory the value is written relative to.
+            for (let i = result.layers.length - 1; i >= 0; i--) {
+                const layer = result.layers[i];
+                if (valueAt(layer.config, key) === undefined)
+                    continue;
+                return layer.source === 'file' && layer.origin ? path.dirname(layer.origin) : fallback;
+            }
+            return fallback;
+        }
+    };
+}
+function valueAt(config, key) {
+    let node = config;
+    for (const part of key.split('.')) {
+        if (node == null || typeof node !== 'object')
+            return undefined;
+        node = node[part];
+    }
+    return node;
+}
+/**
+ * The sealed config: one named preset, expanded, and nothing else. No
+ * discovery, no overrides, no `extends` to a local file — so the only thing
+ * that can change the score is the database.
+ */
+function loadSealedConfig(preset = 'recommended') {
+    const name = preset.includes(':') ? preset : `safegres:${preset}`;
+    if (!(name in PRESETS)) {
+        throw new Error(`Unknown preset "${preset}". Available: ${Object.keys(PRESETS).join(', ')}`);
+    }
+    return { config: expandPreset(PRESETS[name]), layers: [], isEmpty: true };
+}
+function stripExtends(config) {
+    const { extends: _extends, ...rest } = config;
+    return rest;
+}
+function mergePreset(preset, over) {
+    const base = expandPreset(preset);
+    return {
+        ...base,
+        ...over,
+        rules: { ...(base.rules ?? {}), ...(over.rules ?? {}) },
+        scoring: { ...(base.scoring ?? {}), ...(over.scoring ?? {}) },
+        failOn: { ...(base.failOn ?? {}), ...(over.failOn ?? {}) },
+        // Per name: a project adds its own card without dropping the preset's,
+        // and redefines one by naming it.
+        ...(base.scorecards || over.scorecards
+            ? { scorecards: { ...(base.scorecards ?? {}), ...(over.scorecards ?? {}) } }
+            : {}),
+        overrides: [...(base.overrides ?? []), ...(over.overrides ?? [])],
+        // Merged per-key so retuning `skipOwned` doesn't silently drop the
+        // preset's `ignore` list. Omitted entirely when neither side sets it.
+        ...(base.extensions || over.extensions
+            ? { extensions: { ...(base.extensions ?? {}), ...(over.extensions ?? {}) } }
+            : {})
+    };
+}
+function expandPreset(preset) {
+    if (!preset.extends)
+        return preset;
+    const parents = Array.isArray(preset.extends) ? preset.extends : [preset.extends];
+    let acc = {};
+    for (const p of parents) {
+        const parent = PRESETS[p];
+        if (parent)
+            acc = mergePreset(expandPreset(parent), acc);
+    }
+    const { extends: _extends, ...rest } = preset;
+    return mergePreset(acc, rest);
+}