@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/schema/doctor-cli.ts

@@ -5,62 +5,8 @@
  */
 import path from "path";
 import chalk from "chalk";
-import fs from "fs";
-import { runDoctor, loadCollections } from "./doctor";
-import { checkPolicyDrift, formatPolicyDrift, hasDrift } from "../security/policy-drift";
-import { validatePolicyPgRoles, warnOnAnonymousGrants } from "../security/rls-enforcement";
-import { logger } from "@rebasepro/server";
-
-/**
- * The RLS half of the doctor: policies actually deployed vs the ones the
- * collections describe, plus policy roles this server could never satisfy.
- *
- * Returns true when something is wrong, so callers can set the exit code.
- */
-async function runPolicyChecks(collectionsPath: string, databaseUrl?: string): Promise<boolean> {
-    if (!databaseUrl) {
-        logger.warn(chalk.yellow("  ⚠ No DATABASE_URL — skipping RLS policy checks"));
-        return false;
-    }
-
-    let problems = false;
-    const { Pool } = await import("pg");
-    const pool = new Pool({ connectionString: databaseUrl });
-    try {
-        const collections = await loadCollections(path.resolve(process.cwd(), collectionsPath));
-        const runSql = async (text: string) => (await pool.query(text)).rows as Record<string, unknown>[];
-
-        // A policy naming a role the server never runs as filters every row, so
-        // the collection reads as empty. Report it without booting a server.
-        try {
-            await validatePolicyPgRoles(runSql, collections as never);
-            logger.info(chalk.green("  ✓ Policy roles are usable by this server"));
-        } catch (err) {
-            problems = true;
-            logger.info("");
-            logger.error(chalk.red(err instanceof Error ? err.message : String(err)));
-        }
-
-        // A rule that reads as a lockdown but is true for every caller compiles
-        // to a grant. Report it without booting a server.
-        warnOnAnonymousGrants(collections as never);
-
-        const drift = await checkPolicyDrift(pool as never, collections);
-        logger.info("");
-        if (hasDrift(drift)) {
-            problems = true;
-            logger.info(chalk.yellow("  RLS policies: database does not match your collections"));
-            logger.info(formatPolicyDrift(drift));
-        } else {
-            logger.info(chalk.green("  ✓ RLS policies match your collections"));
-        }
-    } catch (err) {
-        logger.warn(chalk.yellow("  ⚠ Could not check RLS policies"), { error: err });
-    } finally {
-        await pool.end();
-    }
-    return problems;
-}
+import { runDoctor } from "./doctor";
+import { exitCodeForPolicyGate, runPolicyChecks } from "./doctor-policy-checks";
 
 async function main() {
     const collectionsArg = process.argv.find((a) => a.startsWith("--collections="));
@@ -91,9 +37,9 @@ async function main() {
     const databaseUrl = process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING;
 
     if (policiesOnly) {
-        // Non-zero so this can gate CI — the whole point of the flag.
-        if (await runPolicyChecks(collectionsPath, databaseUrl)) process.exit(1);
-        return;
+        // Non-zero so this can gate CI — the whole point of the flag, and a
+        // check that could not run has not passed. See exitCodeForPolicyGate.
+        process.exit(exitCodeForPolicyGate(await runPolicyChecks(collectionsPath, databaseUrl)));
     }
 
     const report = await runDoctor({
@@ -103,15 +49,18 @@ async function main() {
         databaseUrl: databaseUrl ?? undefined
     });
 
-    const policiesDrifted = await runPolicyChecks(collectionsPath, databaseUrl);
+    const policyStatus = await runPolicyChecks(collectionsPath, databaseUrl);
 
-    // Exit with non-zero code if there are errors
-    if (report.summary.errors > 0 || policiesDrifted) {
+    // Exit non-zero if there are errors. A policy run that could not happen is
+    // reported loudly above but does not fail the interactive command — the
+    // same treatment the skipped database phase gets. `--policies` is the gate,
+    // and that one fails closed.
+    if (report.summary.errors > 0 || policyStatus === "problems") {
         process.exit(1);
     }
 }
 
 main().catch((err) => {
-    logger.error(chalk.red("  ✗ Doctor failed"), { error: err });
+    console.error(chalk.red("  ✗ Doctor failed"), err instanceof Error ? (err.stack ?? err.message) : String(err));
     process.exit(1);
 });

package/src/schema/doctor-policy-checks.ts

@@ -0,0 +1,105 @@
+/**
+ * The RLS half of `rebase doctor`, and the exit code `--policies` gates CI on.
+ *
+ * Lives beside `doctor-cli.ts` rather than inside it because that file runs
+ * `main()` on import: a gate whose failure modes cannot be unit-tested is how
+ * this one shipped reporting success for work it never did.
+ */
+import path from "path";
+import chalk from "chalk";
+import { CollectionConfig } from "@rebasepro/types";
+import { loadCollections } from "./doctor";
+import { checkPolicyDrift, formatPolicyDrift, hasDrift } from "../security/policy-drift";
+import { validatePolicyPgRoles, warnOnAnonymousGrants } from "../security/rls-enforcement";
+
+/**
+ * What the RLS checks concluded.
+ *
+ * `unchecked` exists because "we could not look" and "we looked and it is fine"
+ * used to be reported identically: a collections path that did not resolve made
+ * the loader return `[]` (it warns, it does not throw), `checkPolicyDrift`
+ * early-returned an empty diff, and the gate printed
+ * `✓ RLS policies match your collections` having compared zero policies against
+ * zero collections. Any exception at all — a collection file that throws on
+ * import, a `pg_policies` read the CI role is not granted, a connection reset —
+ * did the same thing through a `warn`, and exited 0.
+ */
+export type PolicyCheckStatus = "ok" | "problems" | "unchecked";
+
+/**
+ * The exit code for `rebase doctor --policies`.
+ *
+ * A gate that could not run has not passed. Only a completed, clean check
+ * exits 0 — anything else, including "we never opened a connection", is a
+ * failure, or the flag certifies a database nobody looked at.
+ */
+export function exitCodeForPolicyGate(status: PolicyCheckStatus): 0 | 1 {
+    return status === "ok" ? 0 : 1;
+}
+
+/**
+ * Policies actually deployed vs the ones the collections describe, plus policy
+ * roles this server could never satisfy.
+ *
+ * Never reports `ok` for work it did not do — see {@link PolicyCheckStatus}.
+ */
+export async function runPolicyChecks(collectionsPath: string, databaseUrl?: string): Promise<PolicyCheckStatus> {
+    if (!databaseUrl) {
+        console.error(chalk.yellow("  ⚠ No DATABASE_URL — RLS policies were NOT checked"));
+        return "unchecked";
+    }
+
+    const resolvedPath = path.resolve(process.cwd(), collectionsPath);
+    let problems = false;
+    const { Pool } = await import("pg");
+    const pool = new Pool({ connectionString: databaseUrl });
+    try {
+        const collections: CollectionConfig[] = await loadCollections(resolvedPath);
+
+        // Zero collections is not "no drift", it is nothing to compare. The
+        // loader returns `[]` for a path that does not exist, so the commonest
+        // way to get here is a `--collections` path resolved against the wrong
+        // directory — which used to render as a green tick.
+        if (collections.length === 0) {
+            console.error(chalk.red(`  ✗ No collections found in ${resolvedPath}`));
+            console.error(chalk.gray("    RLS policies were NOT checked. Pass --collections=<dir> if your collections live elsewhere."));
+            return "unchecked";
+        }
+
+        const runSql = async (text: string) => (await pool.query(text)).rows as Record<string, unknown>[];
+
+        // A policy naming a role the server never runs as filters every row, so
+        // the collection reads as empty. Report it without booting a server.
+        try {
+            await validatePolicyPgRoles(runSql, collections as never);
+            console.log(chalk.green("  ✓ Policy roles are usable by this server"));
+        } catch (err) {
+            problems = true;
+            console.log("");
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        }
+
+        // A rule that reads as a lockdown but is true for every caller compiles
+        // to a grant. Report it without booting a server.
+        warnOnAnonymousGrants(collections as never);
+
+        const drift = await checkPolicyDrift(pool as never, collections);
+        console.log("");
+        if (hasDrift(drift)) {
+            problems = true;
+            console.log(chalk.yellow("  RLS policies: database does not match your collections"));
+            console.log(formatPolicyDrift(drift));
+        } else {
+            console.log(chalk.green(`  ✓ RLS policies match your collections (${collections.length} collection(s) checked)`));
+        }
+    } catch (err) {
+        // Fail closed. This catch covers every query and every collection import
+        // above, so returning the pre-catch verdict made the documented CI gate
+        // green on exactly the runs it exists to catch.
+        console.error(chalk.red("  ✗ Could not check RLS policies:"), err instanceof Error ? err.message : String(err));
+        return "unchecked";
+    } finally {
+        await pool.end();
+    }
+    return problems ? "problems" : "ok";
+}

package/src/schema/doctor.ts

@@ -15,9 +15,9 @@ import chalk from "chalk";
 import { CollectionConfig, isPostgresCollectionConfig, Property, NumberProperty, StringProperty, DateProperty, ArrayProperty, MapProperty, RelationProperty, type ResolvedManyToMany, type ResolvedBelongsTo, isManyToMany } from "@rebasepro/types";
 import { generateSchema } from "./generate-drizzle-schema-logic";
 import { generateTypedefs } from "@rebasepro/codegen";
-import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
+import { getTableName, resolveCollectionRelations, findRelation, relationalCollections } from "@rebasepro/common";
 import { toSnakeCase } from "@rebasepro/utils";
-import { logger, loadCollectionsFromDirectory } from "@rebasepro/server";
+import { loadCollectionsFromDirectory } from "@rebasepro/server";
 
 /**
  * Resolve the SQL column name for a property.
@@ -33,11 +33,27 @@ const resolveColumnName = (propName: string, prop?: Property | null): string =>
 
 // ── Types ────────────────────────────────────────────────────────────────
 
+/**
+ * The report is CLI output, not application logging.
+ *
+ * `logger.info` is gated by `LOG_LEVEL`, which is a documented setting and
+ * ships in the scaffold's own `.env.example`: a developer who quietened their
+ * dev server with `LOG_LEVEL=warn` got a `rebase doctor` that printed nothing
+ * at all and still exited 1, with no way to tell a failing run from a crashed
+ * one. At the default level every line of the ASCII box arrived with
+ * `ℹ️ [INFO] ` glued to the front of it, and under `NODE_ENV=production` the
+ * whole report became JSON log records with the chalk escapes inside.
+ * `packages/cli` writes all of its output this way for the same reason.
+ */
+const out = (line = ""): void => {
+    console.log(line);
+};
+
 export type IssueSeverity = "error" | "warning" | "info";
 
 export interface DoctorIssue {
     severity: IssueSeverity;
-    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated";
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated" | "sdk_ungeneratable";
     table?: string;
     column?: string;
     expected?: string;
@@ -46,11 +62,27 @@ export interface DoctorIssue {
     fix: string;
 }
 
+export interface DoctorPhase {
+    passed: boolean;
+    issues: DoctorIssue[];
+    /**
+     * Why this phase never ran, when it did not.
+     *
+     * A check that did not happen is a third state, not a passing one. While a
+     * skipped phase initialised to `{ passed: true, issues: [] }` it rendered as
+     * `✅ Collections → Database: In sync` and counted towards
+     * `✓ All schemas are in sync!` — so a project whose connection string was
+     * spelled `POSTGRES_URL`, or a CI job that never exported one, got two green
+     * ticks and exit 0 against a database with no tables in it.
+     */
+    skipped?: string;
+}
+
 export interface DoctorReport {
-    collectionsToSchema: { passed: boolean; issues: DoctorIssue[] };
-    collectionsToSdk: { passed: boolean; issues: DoctorIssue[] };
-    schemaToDatabase: { passed: boolean; issues: DoctorIssue[] };
-    summary: { passed: number; warnings: number; errors: number };
+    collectionsToSchema: DoctorPhase;
+    collectionsToSdk: DoctorPhase;
+    schemaToDatabase: DoctorPhase;
+    summary: { passed: number; skipped: number; warnings: number; errors: number };
 }
 
 // ── Column type mapping (mirrors generate-drizzle-schema-logic.ts) ───────
@@ -149,7 +181,7 @@ export async function loadCollections(collectionsPath: string): Promise<Collecti
 export async function checkCollectionsVsSchema(
     collections: CollectionConfig[],
     schemaFilePath: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // Check if schema file exists
@@ -164,8 +196,10 @@ export async function checkCollectionsVsSchema(
 issues };
     }
 
-    // Re-generate schema in-memory and compare with file on disk
-    const postgresCollections = collections.filter(isPostgresCollectionConfig);
+    // Re-generate schema in-memory and compare with file on disk. Only the
+    // collections the generator itself will emit — a Firestore collection has
+    // no table in the generated file and must not be reported as missing one.
+    const postgresCollections = relationalCollections(collections);
     if (postgresCollections.length === 0) {
         return { passed: true,
 issues };
@@ -208,7 +242,7 @@ issues };
 export async function checkCollectionsVsSdk(
     collections: CollectionConfig[],
     sdkFilePath: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // The typed SDK is opt-in — nothing in a scaffolded project imports it until
@@ -248,12 +282,27 @@ issues };
         }
     } catch (err: unknown) {
         const message = err instanceof Error ? err.message : String(err);
-        issues.push({
-            severity: "warning",
-            category: "sdk_stale",
-            message: `Could not regenerate SDK types for comparison: ${message}`,
-            fix: "Run `rebase generate-sdk` to verify"
-        });
+
+        // A `CodegenError` is not "the comparison did not run" — it is the
+        // schema saying it cannot produce a valid typed client at all, most
+        // often two slugs collapsing onto one accessor. Reporting that as a
+        // warning about staleness described the wrong problem and pointed at a
+        // command that would fail the same way.
+        if (err instanceof Error && err.name === "CodegenError") {
+            issues.push({
+                severity: "error",
+                category: "sdk_ungeneratable",
+                message: `The typed SDK cannot be generated from these collections: ${message}`,
+                fix: "Fix the collection definitions named above, then run `rebase generate-sdk`"
+            });
+        } else {
+            issues.push({
+                severity: "warning",
+                category: "sdk_stale",
+                message: `Could not regenerate SDK types for comparison: ${message}`,
+                fix: "Run `rebase generate-sdk` to verify"
+            });
+        }
     }
 
     return { passed: issues.length === 0,
@@ -280,7 +329,7 @@ interface DbEnumValue {
 export async function checkCollectionsVsDatabase(
     collections: CollectionConfig[],
     databaseUrl: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // Dynamic import to avoid loading pg when not needed
@@ -292,7 +341,7 @@ export async function checkCollectionsVsDatabase(
     const schemas = Array.from(new Set([
         "public",
         "rebase",
-        ...collections
+        ...relationalCollections(collections)
             .filter(isPostgresCollectionConfig)
             .map(c => c.schema)
             .filter((s): s is string => !!s)
@@ -383,7 +432,7 @@ export async function checkCollectionsVsDatabase(
 
         // ── Compare each collection against the database ─────────────────
 
-        const postgresCollections = collections.filter(isPostgresCollectionConfig);
+        const postgresCollections = relationalCollections(collections);
 
         for (const collection of postgresCollections) {
             const tableName = getTableName(collection);
@@ -595,96 +644,99 @@ issues };
 // ── Report Rendering ─────────────────────────────────────────────────────
 
 export function renderReport(report: DoctorReport): void {
-    logger.info("");
-    logger.info(chalk.bold("  🩺 Rebase Schema Doctor"));
-    logger.info(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
-    logger.info("");
+    out();
+    out(chalk.bold("  🩺 Rebase Schema Doctor"));
+    out(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+    out();
 
     // Phase 1
-    renderPhase(
-        "Collections → Generated Schema",
-        report.collectionsToSchema.passed,
-        report.collectionsToSchema.issues
-    );
+    renderPhase("Collections → Generated Schema", report.collectionsToSchema);
 
     // Phase 2
-    renderPhase(
-        "Collections → Database",
-        report.schemaToDatabase.passed,
-        report.schemaToDatabase.issues
-    );
+    renderPhase("Collections → Database", report.schemaToDatabase);
 
     // Phase 3
-    renderPhase(
-        "Collections → SDK Types",
-        report.collectionsToSdk.passed,
-        report.collectionsToSdk.issues
-    );
+    renderPhase("Collections → SDK Types", report.collectionsToSdk);
 
     // Summary
-    logger.info(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
-    const { passed, warnings, errors } = report.summary;
+    out(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+    const { passed, skipped, warnings, errors } = report.summary;
 
     const parts: string[] = [];
     parts.push(chalk.green(`${passed} passed`));
+    if (skipped > 0) parts.push(chalk.yellow(`${skipped} skipped`));
     if (warnings > 0) parts.push(chalk.yellow(`${warnings} warnings`));
     if (errors > 0) parts.push(chalk.red(`${errors} errors`));
 
-    logger.info(`  Summary: ${parts.join(", ")}`);
-    logger.info("");
+    out(`  Summary: ${parts.join(", ")}`);
+    out();
 
     if (errors > 0) {
-        logger.info(chalk.red.bold("  ✗ Schema drift detected. Run the suggested fixes above."));
+        out(chalk.red.bold("  ✗ Schema drift detected. Run the suggested fixes above."));
     } else if (warnings > 0) {
-        logger.info(chalk.yellow.bold("  ⚠ Minor issues detected. Consider running the suggested fixes."));
+        out(chalk.yellow.bold("  ⚠ Minor issues detected. Consider running the suggested fixes."));
+    } else if (skipped > 0) {
+        // Never "all schemas are in sync" off the back of a check that did not
+        // run: a clean bill of health has to come from measurement.
+        out(chalk.yellow.bold(`  ⚠ Nothing wrong in the checks that ran, but ${skipped} did not run — this is not a clean bill of health.`));
     } else {
-        logger.info(chalk.green.bold("  ✓ All schemas are in sync!"));
+        out(chalk.green.bold("  ✓ All schemas are in sync!"));
     }
-    logger.info("");
+    out();
 }
 
-function renderPhase(label: string, passed: boolean, issues: DoctorIssue[]): void {
+function renderPhase(label: string, phase: DoctorPhase): void {
+    // A phase that never ran gets its own marker and its reason. It is neither
+    // "In sync" nor a drift report; conflating it with the former is what let
+    // doctor certify a database it had not opened.
+    if (phase.skipped) {
+        out(`  ${chalk.yellow("⏭")}  ${label}: ${chalk.yellow(`skipped (${phase.skipped})`)}`);
+        out();
+        return;
+    }
+
+    const issues = phase.issues;
     const errorCount = issues.filter((i) => i.severity === "error").length;
     const warnCount = issues.filter((i) => i.severity === "warning").length;
     const infoIssues = issues.filter((i) => i.severity === "info");
 
     // Informational notes don't make a phase unhealthy, so key the header off
-    // real problems rather than `passed` alone.
+    // real problems rather than `phase.passed` alone.
     if (errorCount === 0 && warnCount === 0) {
-        logger.info(`  ${chalk.green("✅")} ${label}: ${chalk.green("In sync")}`);
+        out(`  ${chalk.green("✅")} ${label}: ${chalk.green("In sync")}`);
     } else {
         const parts: string[] = [];
         if (errorCount > 0) parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
         if (warnCount > 0) parts.push(`${warnCount} warning${warnCount > 1 ? "s" : ""}`);
-        logger.info(`  ${chalk.yellow("⚠️")}  ${label}: ${chalk.yellow(parts.join(", "))}`);
+        out(`  ${chalk.yellow("⚠️")}  ${label}: ${chalk.yellow(parts.join(", "))}`);
     }
-    logger.info("");
+    out();
 
     // Notes render as a quiet one-liner, not a full drift box.
     for (const issue of infoIssues) {
         const fixPart = issue.fix ? chalk.gray(` — ${issue.fix}`) : "";
-        logger.info(`  ${chalk.gray("ℹ")} ${chalk.gray(issue.message)}${fixPart}`);
-        logger.info("");
+        out(`  ${chalk.gray("ℹ")} ${chalk.gray(issue.message)}${fixPart}`);
+        out();
     }
 
     for (const issue of issues.filter((i) => i.severity !== "info")) {
         const severityIcon = issue.severity === "error" ? chalk.red("✗") : chalk.yellow("⚠");
         const categoryLabel = formatCategory(issue.category);
-        logger.info(`  ${chalk.gray("┌─")} ${severityIcon} ${chalk.bold(categoryLabel)} ${chalk.gray("─".repeat(Math.max(0, 42 - categoryLabel.length)))}`);
+        out(`  ${chalk.gray("┌─")} ${severityIcon} ${chalk.bold(categoryLabel)} ${chalk.gray("─".repeat(Math.max(0, 42 - categoryLabel.length)))}`);
 
         if (issue.table) {
             const colPart = issue.column ? ` │ Column: ${chalk.cyan(issue.column)}` : "";
-            logger.info(`  ${chalk.gray("│")} Table: ${chalk.cyan(issue.table)}${colPart}`);
+            out(`  ${chalk.gray("│")} Table: ${chalk.cyan(issue.table)}${colPart}`);
         }
 
         if (issue.expected && issue.actual) {
-            logger.info(`  ${chalk.gray("│")} Expected: ${chalk.green(issue.expected)} │ Actual: ${chalk.red(issue.actual)}`);
+            out(`  ${chalk.gray("│")} Expected: ${chalk.green(issue.expected)} │ Actual: ${chalk.red(issue.actual)}`);
         }
 
-        logger.info(`  ${chalk.gray("│")} ${issue.message}`);
-        logger.info(`  ${chalk.gray("│")} Fix: ${chalk.blue(issue.fix)}`);
-        logger.info(`  ${chalk.gray("└" + "─".repeat(48))}`);
-        logger.info("");
+        out(`  ${chalk.gray("│")} ${issue.message}`);
+        out(`  ${chalk.gray("│")} Fix: ${chalk.blue(issue.fix)}`);
+        out(`  ${chalk.gray("└" + "─".repeat(48))}`);
+        out();
     }
 }
 
@@ -699,7 +751,8 @@ function formatCategory(cat: DoctorIssue["category"]): string {
         enum_value_mismatch: "Enum Value Mismatch",
         missing_foreign_key: "Missing Foreign Key",
         sdk_stale: "Stale SDK Types",
-        sdk_not_generated: "SDK Types Not Generated"
+        sdk_not_generated: "SDK Types Not Generated",
+        sdk_ungeneratable: "SDK Cannot Be Generated"
     };
     return labels[cat];
 }
@@ -712,38 +765,44 @@ export async function runDoctor(options: {
     sdkPath: string;
     databaseUrl?: string;
 }): Promise<DoctorReport> {
-    logger.info("");
-    logger.info(chalk.bold("  🩺 Loading collections..."));
+    out();
+    out(chalk.bold("  🩺 Loading collections..."));
     const collections = await loadCollections(options.collectionsPath);
     if (collections.length === 0) {
-        logger.error(chalk.red("  ✗ No collections found."));
+        console.error(chalk.red("  ✗ No collections found."));
         process.exit(1);
     }
-    logger.info(chalk.gray(`  Found ${collections.length} collection(s)`));
-    logger.info("");
+    out(chalk.gray(`  Found ${collections.length} collection(s)`));
+    out();
 
     // Phase 1: Collections ↔ Generated Schema
-    logger.info(chalk.gray("  Checking Collections → Generated Schema..."));
+    out(chalk.gray("  Checking Collections → Generated Schema..."));
     const collectionsToSchema = await checkCollectionsVsSchema(collections, options.schemaPath);
 
     // Phase 2: Collections ↔ Database (only if we have a DATABASE_URL)
-    let schemaToDatabase: { passed: boolean; issues: DoctorIssue[] } = { passed: true,
-issues: [] };
+    let schemaToDatabase: DoctorPhase;
     if (options.databaseUrl) {
-        logger.info(chalk.gray("  Checking Collections → Database..."));
+        out(chalk.gray("  Checking Collections → Database..."));
         schemaToDatabase = await checkCollectionsVsDatabase(collections, options.databaseUrl);
     } else {
-        logger.info(chalk.yellow("  ⚠ DATABASE_URL not set — skipping database comparison."));
-        logger.info(chalk.gray("    Set DATABASE_URL in your .env to enable full drift detection."));
+        // Not `{ passed: true }`: see DoctorPhase.skipped.
+        schemaToDatabase = { passed: false,
+issues: [],
+skipped: "DATABASE_URL not set" };
+        out(chalk.yellow("  ⚠ DATABASE_URL not set — skipping database comparison."));
+        out(chalk.gray("    Set DATABASE_URL in your .env to enable full drift detection."));
     }
 
     // Phase 3: Collections ↔ SDK Types
-    logger.info(chalk.gray("  Checking Collections → SDK Types..."));
+    out(chalk.gray("  Checking Collections → SDK Types..."));
     const collectionsToSdk = await checkCollectionsVsSdk(collections, options.sdkPath);
 
-    const allIssues = [...collectionsToSchema.issues, ...schemaToDatabase.issues, ...collectionsToSdk.issues];
+    const phases = [collectionsToSchema, schemaToDatabase, collectionsToSdk];
+    const allIssues = phases.flatMap((p) => p.issues);
     const summary = {
-        passed: [collectionsToSchema, schemaToDatabase, collectionsToSdk].filter((p) => p.passed).length,
+        // A skipped phase is not a passing one, however few issues it collected.
+        passed: phases.filter((p) => p.passed && !p.skipped).length,
+        skipped: phases.filter((p) => p.skipped).length,
         warnings: allIssues.filter((i) => i.severity === "warning").length,
         errors: allIssues.filter((i) => i.severity === "error").length
     };