@specific.dev/spectest 0.45.0 → 0.47.0

package/dist/components/supabase-config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * GoTrue's mail template types, as `config.toml` spells them. The container
+ * variable is the id upper-cased (`magic_link` -> `GOTRUE_MAILER_TEMPLATES_MAGIC_LINK`).
+ */
+export declare const MAIL_TEMPLATE_IDS: readonly ["invite", "confirmation", "recovery", "magic_link", "email_change", "reauthentication"];
+export type MailTemplateId = (typeof MAIL_TEMPLATE_IDS)[number];
+/** A template to serve to GoTrue: where the HTML lives, and its subject line. */
+export interface MailTemplateSpec {
+    /** Path to the HTML file, relative to the project root (or absolute). */
+    path: string;
+    /** Subject line. Left to GoTrue's default when absent. */
+    subject?: string;
+}
+/** Everything the component takes from the config file, grouped by the service it lands on. */
+export interface MappedSupabaseConfig {
+    /** GoTrue (`<name>-auth`) environment. */
+    auth: Record<string, string>;
+    /** PostgREST (`<name>-rest`) environment. */
+    rest: Record<string, string>;
+    /** Per-function JWT verification, by function name (`functions.<name>.verify_jwt`). */
+    functionVerifyJwt: Record<string, boolean>;
+    /** Function secrets (`edge_runtime.secrets`) that carry a literal value. */
+    functionSecrets: Record<string, string>;
+    /**
+     * Secrets the file explicitly defers to the environment — `env(NAME)`, which
+     * the Supabase CLI resolves from the developer's shell. There is no such
+     * shell here, so the value comes from the `env` option. Keyed by the
+     * secret's name, valued by the `env` name to read it from — the two differ
+     * whenever the file says `SECRET = "env(OTHER_NAME)"`.
+     */
+    deferredSecrets: Record<string, string>;
+    /**
+     * Settings whose value is an inline `encrypted:` ciphertext. Nothing here
+     * can decrypt one — that needs a `DOTENV_PRIVATE_KEY` from the developer's
+     * environment — so they are reported and left unset rather than guessed at.
+     */
+    encryptedValues: string[];
+    /** Custom mail templates, keyed by GoTrue template id. */
+    templates: Partial<Record<MailTemplateId, MailTemplateSpec>>;
+    /**
+     * Social sign-in providers the file declares (`[auth.external.<name>]`),
+     * keyed by the provider name GoTrue uses. Whether one can be *served* is the
+     * component's business: a provider spectest has an emulator for is stood up
+     * inside the environment, the rest are reported.
+     */
+    externalProviders: Record<string, ExternalProvider>;
+    /**
+     * Settings that are real, enabled, and not applied here — an OAuth provider,
+     * SMS. Reported so the file never looks applied when it is not; never fatal,
+     * because the config belongs to the project and is not ours to veto.
+     */
+    unsupported: {
+        key: string;
+        reason: string;
+    }[];
+    /** Keys no rule classified — a newer CLI than this map knows about. */
+    warnings: string[];
+}
+/** One `[auth.external.<name>]` block, as the file spells it. */
+export interface ExternalProvider {
+    enabled: boolean;
+    /** Literal values as the file gives them. */
+    clientId?: string;
+    secret?: string;
+    /** …and the `env` names a deferred value is read from. Absent a value, the
+     *  stack mints its own pair, which an emulator accepts — all that matters
+     *  is that it and GoTrue agree. */
+    clientIdFrom?: string;
+    secretFrom?: string;
+    /** The authority, where the provider allows one (Azure's tenant, Keycloak). */
+    url?: string;
+}
+/**
+ * Classify and map every leaf of a parsed config document.
+ *
+ * Never throws on content: a setting this component does not apply is
+ * *reported* (`unsupported`), not vetoed. The file belongs to the project and
+ * describes more than one environment — refusing to start over a key that is
+ * meaningless in a hermetic VM would make the whole option unadoptable for the
+ * projects that need it most. Silence is still the thing to avoid, so nothing
+ * unapplied goes unsaid.
+ */
+export declare function mapSupabaseConfig(doc: unknown): MappedSupabaseConfig;
+/**
+ * Parse a config file. The format follows the extension — Supabase is moving
+ * the canonical file from TOML to JSON, and both are read here so a project is
+ * never held back by which CLI version wrote it.
+ */
+export declare function parseSupabaseConfigFile(path: string): unknown;

package/dist/components/supabase-config.js

@@ -0,0 +1,447 @@
+// Reader for the Supabase CLI's project config file — the `supabase/` folder's
+// `config.toml` (or `config.json` on newer CLIs, which is becoming the
+// canonical format with TOML kept for back-compat).
+//
+// WHY THIS EXISTS. `config.toml` is where a project already declares the auth
+// rules it runs locally and in production: custom mail templates, redirect
+// allow lists, auth hooks, per-function JWT verification. None of it reached
+// the environment before, so a suite could pass against rules the real app
+// never runs under — and a flow that depends on a custom template (an invite
+// mail carrying `{{ .Token }}`) simply could not be tested.
+//
+// WHAT IT IS NOT. This is not a reimplementation of the CLI. The file
+// describes a whole local stack — ports, Studio, analytics, its own mailbox —
+// and spectest owns all of that. Only the settings a *test* can observe are
+// mapped; everything else is classified into one of two other buckets, and
+// nothing is ever passed through silently:
+//
+//   applied     — becomes container config (see RULES below)
+//   irrelevant  — spectest owns it (ports, topology, Studio); dropped in silence
+//   unsupported — real, and we do not apply it; fails env start unless the
+//                 caller lists it in `ignore`
+//
+// An unclassified key is a *warning*, not a failure: a newer CLI must not stop
+// an existing suite from starting.
+//
+// PROVENANCE. What each option means:
+//   https://supabase.com/docs/guides/local-development/cli/config
+// Which container variable it becomes is not in those docs — that mapping only
+// exists in the CLI's own per-service modules, and every applied rule below
+// cites the line it was taken from:
+//   supabase/cli apps/cli/src/legacy/commands/start/services/gotrue.service.ts
+// Note the two negated pairs (`enable_signup` -> DISABLE_SIGNUP,
+// `enable_confirmations` -> MAILER_AUTOCONFIRM). They are the mappings a
+// copy-paste gets silently backwards, which is why they are marked at the def
+// site.
+import { readFileSync } from "node:fs";
+/**
+ * GoTrue's mail template types, as `config.toml` spells them. The container
+ * variable is the id upper-cased (`magic_link` -> `GOTRUE_MAILER_TEMPLATES_MAGIC_LINK`).
+ */
+export const MAIL_TEMPLATE_IDS = [
+    "invite",
+    "confirmation",
+    "recovery",
+    "magic_link",
+    "email_change",
+    "reauthentication",
+];
+// ── value coercion ────────────────────────────────────────────────────────
+const str = (v) => String(v);
+const num = (v) => String(v);
+const bool = (v) => String(v === true);
+/** For the negated pairs: `enable_x = true` becomes `DISABLE_X = false`. */
+const not = (v) => String(v !== true);
+const csv = (v) => (Array.isArray(v) ? v.map(String).join(",") : String(v));
+/**
+ * `auth.password_requirements`' enum, expanded to the character classes GoTrue
+ * wants (cli gotrue.service.ts:137-142). An unknown value means "no
+ * requirement", matching the CLI's `?? ""`.
+ */
+const PASSWORD_REQUIREMENTS_TO_CHAR = {
+    letters_digits: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ:0123456789",
+    lower_upper_letters_digits: "abcdefghijklmnopqrstuvwxyz:ABCDEFGHIJKLMNOPQRSTUVWXYZ:0123456789",
+    lower_upper_letters_digits_symbols: "abcdefghijklmnopqrstuvwxyz:ABCDEFGHIJKLMNOPQRSTUVWXYZ:0123456789:!@#$%^&*()_+-=[]{};'\\:\"|<>?,./`~",
+};
+// ── rule constructors ─────────────────────────────────────────────────────
+/** A setting that becomes one GoTrue variable. */
+const auth = (key, envName, coerce) => ({
+    key,
+    bucket: "applied",
+    apply: (v, out) => {
+        out.auth[envName] = coerce(v);
+    },
+});
+/** A setting that becomes one PostgREST variable. */
+const rest = (key, envName, coerce) => ({
+    key,
+    bucket: "applied",
+    apply: (v, out) => {
+        out.rest[envName] = coerce(v);
+    },
+});
+const irrelevant = (key) => ({ key, bucket: "irrelevant" });
+/**
+ * A config value is either usable as-is, or a reference the surrounding
+ * environment is expected to supply. The file has two ways of deferring:
+ *
+ *   `env(NAME)`      the Supabase CLI reads NAME from `supabase/.env` at
+ *                    `start` / `config push` time
+ *   `encrypted:…`    a dotenvx ciphertext, decrypted at the same moment with
+ *                    `DOTENV_PRIVATE_KEY`
+ *
+ * A test VM has neither the dotenv (it is blocked from the upload — real
+ * credentials must not enter a test environment) nor the private key, so both
+ * resolve against the component's `secrets` option instead. What must never
+ * happen is passing either through: a function would then read the literal
+ * string `env(STRIPE_KEY)`, or a base64 ciphertext, and the ciphertext looks
+ * enough like a value to go unnoticed.
+ */
+function configValue(v) {
+    const raw = String(v);
+    if (raw === "")
+        return {};
+    // `env(NAME)` is a lookup in the surrounding environment, so NAME is the key.
+    const env = /^env\((.+)\)$/.exec(raw);
+    if (env)
+        return { from: env[1] };
+    // An `encrypted:` value is an inline dotenvx ciphertext, not a lookup: it
+    // names nothing, and decrypting it needs a `DOTENV_PRIVATE_KEY` that a test
+    // environment has no business holding. So it is reported and left unset —
+    // never guessed at, and never passed through as base64.
+    if (raw.startsWith("encrypted:"))
+        return { encrypted: true };
+    return { literal: raw };
+}
+const unsupported = (key, reason) => ({ key, bucket: "unsupported", reason });
+// ── the map ───────────────────────────────────────────────────────────────
+//
+// Order matters: the first matching rule wins, so specific keys precede the
+// `**` prefixes that sweep up the rest of a section.
+const RULES = [
+    // ── auth: core (cli gotrue.service.ts:440-448) ──────────────────────────
+    // NEGATED — `enable_signup = true` means DISABLE_SIGNUP = false.
+    auth("auth.enable_signup", "GOTRUE_DISABLE_SIGNUP", not),
+    auth("auth.jwt_expiry", "GOTRUE_JWT_EXP", num),
+    auth("auth.enable_anonymous_sign_ins", "GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED", bool),
+    auth("auth.enable_manual_linking", "GOTRUE_SECURITY_MANUAL_LINKING_ENABLED", bool),
+    auth("auth.enable_refresh_token_rotation", "GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED", bool),
+    auth("auth.refresh_token_reuse_interval", "GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL", num),
+    auth("auth.minimum_password_length", "GOTRUE_PASSWORD_MIN_LENGTH", num),
+    auth("auth.password_requirements", "GOTRUE_PASSWORD_REQUIRED_CHARACTERS", (v) => PASSWORD_REQUIREMENTS_TO_CHAR[String(v)] ?? ""),
+    // ── auth: email (cli gotrue.service.ts:451-462) ─────────────────────────
+    auth("auth.email.enable_signup", "GOTRUE_EXTERNAL_EMAIL_ENABLED", bool),
+    auth("auth.email.double_confirm_changes", "GOTRUE_MAILER_SECURE_EMAIL_CHANGE_ENABLED", bool),
+    // NEGATED — confirmations ON means autoconfirm OFF.
+    auth("auth.email.enable_confirmations", "GOTRUE_MAILER_AUTOCONFIRM", not),
+    auth("auth.email.secure_password_change", "GOTRUE_SECURITY_UPDATE_PASSWORD_REQUIRE_REAUTHENTICATION", bool),
+    auth("auth.email.otp_length", "GOTRUE_MAILER_OTP_LENGTH", num),
+    auth("auth.email.otp_expiry", "GOTRUE_MAILER_OTP_EXP", num),
+    // Go duration strings ("1s", "1m0s") pass through as written.
+    auth("auth.email.max_frequency", "GOTRUE_SMTP_MAX_FREQUENCY", str),
+    // The sender identity, which is about the mail rather than the transport —
+    // so it is taken from the file even though the host/port below are ours.
+    auth("auth.email.smtp.admin_email", "GOTRUE_SMTP_ADMIN_EMAIL", str),
+    auth("auth.email.smtp.sender_name", "GOTRUE_SMTP_SENDER_NAME", str),
+    // Custom templates. `content_path` is resolved by the caller, which is what
+    // serves the file — GoTrue fetches templates over HTTP, so a path alone is
+    // not enough (see the component's template server).
+    {
+        key: "auth.email.template.*.content_path",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            const id = path[3];
+            const p = String(v);
+            // An empty `content_path` is how the CLI spells "no custom template".
+            if (p === "")
+                return;
+            out.templates[id] = { ...out.templates[id], path: p };
+        },
+    },
+    {
+        key: "auth.email.template.*.subject",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            const id = path[3];
+            out.templates[id] = { ...(out.templates[id] ?? { path: "" }), subject: String(v) };
+        },
+    },
+    // ── auth: social sign-in (cli gotrue.service.ts:361-368) ────────────────
+    // Collected here, served by the component: each provider it has an emulator
+    // for is stood up inside the environment at that provider's real endpoints,
+    // so the app's production configuration keeps working.
+    {
+        key: "auth.external.*.*",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            const name = path[2];
+            const field = path[3];
+            const p = (out.externalProviders[name] ??= { enabled: false });
+            if (field === "enabled")
+                p.enabled = v === true;
+            // `env(NAME)` is a reference to the developer's own shell, so it names
+            // nothing here — the component supplies its own credentials instead.
+            else if (field === "client_id" || field === "secret") {
+                const r = configValue(v);
+                if (field === "client_id") {
+                    p.clientId = r.literal;
+                    p.clientIdFrom = r.from;
+                }
+                else {
+                    p.secret = r.literal;
+                    p.secretFrom = r.from;
+                }
+                if (r.encrypted)
+                    out.encryptedValues.push(`auth.external.${name}.${field}`);
+            }
+            else if (field === "url")
+                p.url = configValue(v).literal;
+        },
+    },
+    // ── auth: hooks (cli gotrue.service.ts:610-614) ─────────────────────────
+    // Generic on the hook name, unlike the CLI's fixed list, so a hook added
+    // upstream works here without a change: `auth.hook.before_user_created`
+    // becomes GOTRUE_HOOK_BEFORE_USER_CREATED_*.
+    {
+        key: "auth.hook.*.*",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            const prefix = path[2].toUpperCase();
+            const field = path[3];
+            if (field === "enabled")
+                out.auth[`GOTRUE_HOOK_${prefix}_ENABLED`] = bool(v);
+            else if (field === "uri")
+                out.auth[`GOTRUE_HOOK_${prefix}_URI`] = str(v);
+            else if (field === "secrets")
+                out.auth[`GOTRUE_HOOK_${prefix}_SECRETS`] = str(v);
+        },
+    },
+    // ── auth: OAuth server (cli gotrue.service.ts:641-646) ──────────────────
+    // Supabase Auth acting as an authorization *server*, so a third-party client
+    // (an MCP connector, say) can obtain tokens for the project's own API. Note
+    // the key rename: `authorization_url_path` -> `..._AUTHORIZATION_PATH`.
+    auth("auth.oauth_server.enabled", "GOTRUE_OAUTH_SERVER_ENABLED", bool),
+    auth("auth.oauth_server.authorization_url_path", "GOTRUE_OAUTH_SERVER_AUTHORIZATION_PATH", str),
+    auth("auth.oauth_server.allow_dynamic_registration", "GOTRUE_OAUTH_SERVER_ALLOW_DYNAMIC_REGISTRATION", bool),
+    // ── auth: sessions + MFA (cli gotrue.service.ts:539-545, 492-498) ───────
+    auth("auth.sessions.timebox", "GOTRUE_SESSIONS_TIMEBOX", str),
+    auth("auth.sessions.inactivity_timeout", "GOTRUE_SESSIONS_INACTIVITY_TIMEOUT", str),
+    auth("auth.mfa.max_enrolled_factors", "GOTRUE_MFA_MAX_ENROLLED_FACTORS", num),
+    auth("auth.mfa.totp.enroll_enabled", "GOTRUE_MFA_TOTP_ENROLL_ENABLED", bool),
+    auth("auth.mfa.totp.verify_enabled", "GOTRUE_MFA_TOTP_VERIFY_ENABLED", bool),
+    auth("auth.mfa.web_authn.enroll_enabled", "GOTRUE_MFA_WEB_AUTHN_ENROLL_ENABLED", bool),
+    auth("auth.mfa.web_authn.verify_enabled", "GOTRUE_MFA_WEB_AUTHN_VERIFY_ENABLED", bool),
+    // ── auth: rate limits (cli gotrue.service.ts:499-504) ───────────────────
+    auth("auth.rate_limit.email_sent", "GOTRUE_RATE_LIMIT_EMAIL_SENT", num),
+    auth("auth.rate_limit.anonymous_users", "GOTRUE_RATE_LIMIT_ANONYMOUS_USERS", num),
+    auth("auth.rate_limit.token_refresh", "GOTRUE_RATE_LIMIT_TOKEN_REFRESH", num),
+    auth("auth.rate_limit.sign_in_sign_ups", "GOTRUE_RATE_LIMIT_OTP", num),
+    auth("auth.rate_limit.token_verifications", "GOTRUE_RATE_LIMIT_VERIFY", num),
+    auth("auth.rate_limit.web3", "GOTRUE_RATE_LIMIT_WEB3", num),
+    // ── api (PostgREST) ────────────────────────────────────────────────────
+    rest("api.schemas", "PGRST_DB_SCHEMAS", csv),
+    rest("api.extra_search_path", "PGRST_DB_EXTRA_SEARCH_PATH", csv),
+    rest("api.max_rows", "PGRST_DB_MAX_ROWS", num),
+    // ── functions ──────────────────────────────────────────────────────────
+    {
+        key: "functions.*.verify_jwt",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            out.functionVerifyJwt[path[1]] = v === true;
+        },
+    },
+    {
+        key: "edge_runtime.secrets.*",
+        bucket: "applied",
+        apply: (v, out, path) => {
+            const name = path[2];
+            // The platform reserves this prefix, and `supabase secrets set` skips
+            // such an entry with a warning — so setting it here would work in a
+            // test and be absent in production.
+            if (name.startsWith("SUPABASE_"))
+                return;
+            const { literal, from, encrypted } = configValue(v);
+            if (literal !== undefined)
+                out.functionSecrets[name] = literal;
+            else if (from !== undefined)
+                out.deferredSecrets[name] = from;
+            else if (encrypted)
+                out.encryptedValues.push(`edge_runtime.secrets.${name}`);
+        },
+    },
+    // ── unsupported: real settings we deliberately do not apply ────────────
+    unsupported("auth.sms.**", "SMS delivery is not part of the stack"),
+    unsupported("auth.mfa.phone.**", "phone MFA needs SMS delivery, which is not part of the stack"),
+    unsupported("auth.web3.**", "web3 sign-in is not part of the stack"),
+    unsupported("auth.captcha.**", "a captcha provider is not reachable from a hermetic VM"),
+    unsupported("auth.third_party.**", "third-party auth providers are not part of the stack"),
+    unsupported("auth.email.notification.**", "account-change notification mails are not mapped yet"),
+    unsupported("storage.image_transformation.**", "image transformation is always on in this stack"),
+    unsupported("db.vault.**", "the vault is not seeded by this component"),
+    // ── irrelevant: spectest owns this ─────────────────────────────────────
+    // The SMTP *transport* is always the capture mailbox, which is the point of
+    // it: a test environment that mailed a real server would be neither hermetic
+    // nor assertable. (The sender identity above is a different thing and does
+    // come from the file.)
+    irrelevant("auth.email.smtp.**"),
+    // Addresses, not behaviour: the file's `site_url` / `additional_redirect_urls`
+    // name the developer's machine (`http://localhost:3000`), which in a VM is the
+    // browser's own namespace rather than the app container. The `auth` option
+    // supplies this environment's addresses instead.
+    irrelevant("auth.site_url"),
+    irrelevant("auth.additional_redirect_urls"),
+    irrelevant("auth.enabled"),
+    irrelevant("auth.jwt_secret"),
+    irrelevant("auth.signing_keys_path"),
+    irrelevant("project_id"),
+    irrelevant("api.**"),
+    irrelevant("db.**"),
+    irrelevant("realtime.**"),
+    irrelevant("storage.**"),
+    irrelevant("studio.**"),
+    irrelevant("inbucket.**"),
+    irrelevant("analytics.**"),
+    irrelevant("edge_runtime.**"),
+    irrelevant("functions.**"),
+    irrelevant("experimental.**"),
+    // Per-environment overrides of any section above. They describe a linked
+    // remote project, never the local stack.
+    irrelevant("remotes.**"),
+];
+// ── walking ───────────────────────────────────────────────────────────────
+function isTable(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function matches(pattern, path) {
+    const pat = pattern.split(".");
+    for (let i = 0; i < pat.length; i++) {
+        if (pat[i] === "**")
+            return true;
+        if (i >= path.length)
+            return false;
+        if (pat[i] !== "*" && pat[i] !== path[i])
+            return false;
+    }
+    return pat.length === path.length;
+}
+/**
+ * Does any rule live *below* this table? A section rule (`storage.**`) matches
+ * the section node itself, so without this check it would swallow the more
+ * specific rules written under it — `api.**` would drop `api.schemas`, and
+ * `storage.**` would hide the unsupported `storage.image_transformation`.
+ */
+function claimsDeeper(path) {
+    return RULES.some((r) => {
+        if (r.bucket === "irrelevant")
+            return false;
+        const pat = r.key.split(".");
+        if (pat.length <= path.length)
+            return false;
+        // The rule that matched this node is not "deeper" than it: `auth.sms.**`
+        // is a statement about `[auth.sms]` as a whole, and treating it as deeper
+        // would descend and report the section one key at a time.
+        if (pat[path.length] === "**")
+            return false;
+        for (let i = 0; i < path.length; i++) {
+            if (pat[i] === "**")
+                return false;
+            if (pat[i] !== "*" && pat[i] !== path[i])
+                return false;
+        }
+        return true;
+    });
+}
+/**
+ * Is this section switched off? A feature that is disabled in the file loses
+ * nothing by our not applying it, so it is not worth telling the user about.
+ * Covers the two spellings the config uses (`enabled`, and `enable_signup` for
+ * the email/SMS sections), and a pure container of sub-sections — `[auth.external]`
+ * with every provider disabled — where the container has no flag of its own.
+ */
+function isOff(v) {
+    if (!isTable(v))
+        return false;
+    if (v.enabled === false)
+        return true;
+    if (v.enabled === undefined && v.enable_signup === false)
+        return true;
+    if (v.enabled === undefined) {
+        const values = Object.values(v);
+        const tables = values.filter(isTable);
+        if (tables.length > 0 && tables.length === values.length)
+            return tables.every(isOff);
+    }
+    return false;
+}
+/**
+ * Classify and map every leaf of a parsed config document.
+ *
+ * Never throws on content: a setting this component does not apply is
+ * *reported* (`unsupported`), not vetoed. The file belongs to the project and
+ * describes more than one environment — refusing to start over a key that is
+ * meaningless in a hermetic VM would make the whole option unadoptable for the
+ * projects that need it most. Silence is still the thing to avoid, so nothing
+ * unapplied goes unsaid.
+ */
+export function mapSupabaseConfig(doc) {
+    const out = {
+        auth: {},
+        rest: {},
+        functionVerifyJwt: {},
+        functionSecrets: {},
+        templates: {},
+        externalProviders: {},
+        deferredSecrets: {},
+        encryptedValues: [],
+        unsupported: [],
+        warnings: [],
+    };
+    if (!isTable(doc))
+        return out;
+    const walk = (table, path) => {
+        for (const [k, v] of Object.entries(table)) {
+            const next = [...path, k];
+            const key = next.join(".");
+            const rule = RULES.find((r) => matches(r.key, next));
+            // A `**` rule is a statement about a whole subtree, so a section it
+            // matches is classified in one line rather than key by key — unless a
+            // more specific rule lives below it, in which case descend.
+            if (isTable(v)) {
+                const wholesale = rule !== undefined && rule.key.includes("**") && !claimsDeeper(next);
+                if (!wholesale) {
+                    walk(v, next);
+                    continue;
+                }
+            }
+            if (rule === undefined) {
+                out.warnings.push(key);
+                continue;
+            }
+            if (rule.bucket === "irrelevant")
+                continue;
+            if (rule.bucket === "unsupported") {
+                // A feature the file switches off loses nothing by not being applied,
+                // so it is not worth a line.
+                if (!isOff(v))
+                    out.unsupported.push({ key, reason: rule.reason ?? "not applied" });
+                continue;
+            }
+            rule.apply?.(v, out, next);
+        }
+    };
+    walk(doc, []);
+    return out;
+}
+/**
+ * Parse a config file. The format follows the extension — Supabase is moving
+ * the canonical file from TOML to JSON, and both are read here so a project is
+ * never held back by which CLI version wrote it.
+ */
+export function parseSupabaseConfigFile(path) {
+    const text = readFileSync(path, "utf8");
+    if (path.endsWith(".json"))
+        return JSON.parse(text);
+    // Bun parses TOML natively (no dependency, and synchronous — this runs while
+    // the services map is being built).
+    return globalThis.Bun.TOML.parse(text);
+}