postgresai 0.14.0-dev.53 → 0.14.0-dev.55

package/scripts/embed-metrics.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env bun
+/**
+ * Build script to embed metrics.yml into the CLI bundle.
+ * 
+ * This script reads config/pgwatch-prometheus/metrics.yml and generates
+ * cli/lib/metrics-embedded.ts with the metrics data embedded as TypeScript.
+ * 
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ * 
+ * Usage: bun run scripts/embed-metrics.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+
+// Resolve paths relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const METRICS_YML_PATH = path.resolve(CLI_DIR, "../config/pgwatch-prometheus/metrics.yml");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/metrics-embedded.ts");
+
+interface MetricDefinition {
+  description?: string;
+  // YAML parses numeric keys (e.g., 11:, 14:) as numbers, representing PG major versions
+  sqls: Record<number, string>;
+  gauges?: string[];
+  statement_timeout_seconds?: number;
+  is_instance_level?: boolean;
+  node_status?: string;
+}
+
+interface MetricsYml {
+  metrics: Record<string, MetricDefinition>;
+}
+
+// Metrics needed for express mode reports
+const REQUIRED_METRICS = [
+  // Settings and version (A002, A003, A007, A013)
+  "settings",
+  // Database stats (A004)
+  "db_stats",
+  "db_size",
+  // Index health (H001, H002, H004)
+  "pg_invalid_indexes",
+  "unused_indexes",
+  "redundant_indexes",
+  // Stats reset info (H002)
+  "stats_reset",
+];
+
+function main() {
+  console.log(`Reading metrics from: ${METRICS_YML_PATH}`);
+  
+  if (!fs.existsSync(METRICS_YML_PATH)) {
+    console.error(`ERROR: metrics.yml not found at ${METRICS_YML_PATH}`);
+    process.exit(1);
+  }
+
+  const yamlContent = fs.readFileSync(METRICS_YML_PATH, "utf8");
+  const parsed = yaml.load(yamlContent) as MetricsYml;
+
+  if (!parsed.metrics) {
+    console.error("ERROR: No 'metrics' section found in metrics.yml");
+    process.exit(1);
+  }
+
+  // Extract only required metrics
+  const extractedMetrics: Record<string, MetricDefinition> = {};
+  const missingMetrics: string[] = [];
+
+  for (const metricName of REQUIRED_METRICS) {
+    if (parsed.metrics[metricName]) {
+      extractedMetrics[metricName] = parsed.metrics[metricName];
+    } else {
+      missingMetrics.push(metricName);
+    }
+  }
+
+  if (missingMetrics.length > 0) {
+    console.error(`ERROR: Missing required metrics: ${missingMetrics.join(", ")}`);
+    process.exit(1);
+  }
+
+  // Generate TypeScript code
+  const tsCode = generateTypeScript(extractedMetrics);
+
+  // Write output
+  fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+  console.log(`Generated: ${OUTPUT_PATH}`);
+  console.log(`Embedded ${Object.keys(extractedMetrics).length} metrics`);
+}
+
+function generateTypeScript(metrics: Record<string, MetricDefinition>): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    "// Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts",
+    `// Generated at: ${new Date().toISOString()}`,
+    "",
+    "/**",
+    " * Metric definition from metrics.yml",
+    " */",
+    "export interface MetricDefinition {",
+    "  description?: string;",
+    "  sqls: Record<number, string>;  // PG major version -> SQL query",
+    "  gauges?: string[];",
+    "  statement_timeout_seconds?: number;",
+    "}",
+    "",
+    "/**",
+    " * Embedded metrics for express mode reports.",
+    " * Only includes metrics required for CLI checkup reports.",
+    " */",
+    "export const METRICS: Record<string, MetricDefinition> = {",
+  ];
+
+  for (const [name, metric] of Object.entries(metrics)) {
+    lines.push(`  ${JSON.stringify(name)}: {`);
+    
+    if (metric.description) {
+      // Escape description for TypeScript string
+      const desc = metric.description.trim().replace(/\n/g, " ").replace(/\s+/g, " ");
+      lines.push(`    description: ${JSON.stringify(desc)},`);
+    }
+
+    // sqls keys are PG major versions (numbers in YAML, but Object.entries returns strings)
+    lines.push("    sqls: {");
+    for (const [versionKey, sql] of Object.entries(metric.sqls)) {
+      // YAML numeric keys may be parsed as numbers or strings depending on context;
+      // explicitly convert to ensure consistent numeric keys in output
+      const versionNum = typeof versionKey === "number" ? versionKey : parseInt(versionKey, 10);
+      // Use JSON.stringify for robust escaping of all special characters
+      lines.push(`      ${versionNum}: ${JSON.stringify(sql)},`);
+    }
+    lines.push("    },");
+
+    if (metric.gauges) {
+      lines.push(`    gauges: ${JSON.stringify(metric.gauges)},`);
+    }
+
+    if (metric.statement_timeout_seconds !== undefined) {
+      lines.push(`    statement_timeout_seconds: ${metric.statement_timeout_seconds},`);
+    }
+
+    lines.push("  },");
+  }
+
+  lines.push("};");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+main();
+

package/test/auth.test.ts

@@ -0,0 +1,258 @@
+import { describe, test, expect } from "bun:test";
+import { resolve } from "path";
+
+import * as util from "../lib/util";
+import * as pkce from "../lib/pkce";
+import * as authServer from "../lib/auth-server";
+
+function runCli(args: string[], env: Record<string, string> = {}) {
+  const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+  const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+  const result = Bun.spawnSync([bunBin, cliPath, ...args], {
+    env: { ...process.env, ...env },
+  });
+  return {
+    status: result.exitCode,
+    stdout: new TextDecoder().decode(result.stdout),
+    stderr: new TextDecoder().decode(result.stderr),
+  };
+}
+
+describe("URL resolution", () => {
+  test("resolveBaseUrls returns correct production defaults", () => {
+    const result = util.resolveBaseUrls();
+    expect(result.apiBaseUrl).toBe("https://postgres.ai/api/general");
+    expect(result.uiBaseUrl).toBe("https://console.postgres.ai");
+  });
+
+  test("resolveBaseUrls strips trailing slashes", () => {
+    const result = util.resolveBaseUrls({
+      apiBaseUrl: "https://example.com/api/",
+      uiBaseUrl: "https://example.com/",
+    });
+    expect(result.apiBaseUrl).toBe("https://example.com/api");
+    expect(result.uiBaseUrl).toBe("https://example.com");
+  });
+
+  test("resolveBaseUrls respects environment variables", () => {
+    const originalApiUrl = process.env.PGAI_API_BASE_URL;
+    const originalUiUrl = process.env.PGAI_UI_BASE_URL;
+
+    try {
+      process.env.PGAI_API_BASE_URL = "https://custom-api.example.com/api/";
+      process.env.PGAI_UI_BASE_URL = "https://custom-ui.example.com/";
+
+      const result = util.resolveBaseUrls();
+      expect(result.apiBaseUrl).toBe("https://custom-api.example.com/api");
+      expect(result.uiBaseUrl).toBe("https://custom-ui.example.com");
+    } finally {
+      if (originalApiUrl === undefined) {
+        delete process.env.PGAI_API_BASE_URL;
+      } else {
+        process.env.PGAI_API_BASE_URL = originalApiUrl;
+      }
+      if (originalUiUrl === undefined) {
+        delete process.env.PGAI_UI_BASE_URL;
+      } else {
+        process.env.PGAI_UI_BASE_URL = originalUiUrl;
+      }
+    }
+  });
+
+  test("resolveBaseUrls prefers CLI options over env vars", () => {
+    const originalApiUrl = process.env.PGAI_API_BASE_URL;
+
+    try {
+      process.env.PGAI_API_BASE_URL = "https://env.example.com/api/";
+
+      const result = util.resolveBaseUrls({
+        apiBaseUrl: "https://cli-option.example.com/api/",
+      });
+      expect(result.apiBaseUrl).toBe("https://cli-option.example.com/api");
+    } finally {
+      if (originalApiUrl === undefined) {
+        delete process.env.PGAI_API_BASE_URL;
+      } else {
+        process.env.PGAI_API_BASE_URL = originalApiUrl;
+      }
+    }
+  });
+
+  test("resolveBaseUrls uses config baseUrl for API", () => {
+    const result = util.resolveBaseUrls({}, { baseUrl: "https://config.example.com/api/" });
+    expect(result.apiBaseUrl).toBe("https://config.example.com/api");
+    // UI should still use default since config doesn't have uiBaseUrl
+    expect(result.uiBaseUrl).toBe("https://console.postgres.ai");
+  });
+
+  test("normalizeBaseUrl throws on invalid URL", () => {
+    expect(() => util.normalizeBaseUrl("not-a-url")).toThrow(/Invalid base URL/);
+  });
+
+  test("normalizeBaseUrl accepts valid URLs", () => {
+    expect(util.normalizeBaseUrl("https://example.com")).toBe("https://example.com");
+    expect(util.normalizeBaseUrl("https://example.com/")).toBe("https://example.com");
+    expect(util.normalizeBaseUrl("https://example.com/api/")).toBe("https://example.com/api");
+  });
+});
+
+describe("PKCE module", () => {
+  test("generateCodeVerifier returns correct length string", () => {
+    const verifier = pkce.generateCodeVerifier();
+    expect(typeof verifier).toBe("string");
+    expect(verifier.length).toBeGreaterThanOrEqual(43);
+    expect(verifier.length).toBeLessThanOrEqual(128);
+  });
+
+  test("generateCodeChallenge returns base64url encoded SHA256", () => {
+    const verifier = pkce.generateCodeVerifier();
+    const challenge = pkce.generateCodeChallenge(verifier);
+    expect(typeof challenge).toBe("string");
+    expect(challenge.length).toBeGreaterThan(0);
+    // Base64url encoding should not contain + or / characters
+    expect(challenge).not.toMatch(/[+/]/);
+  });
+
+  test("generateState returns random string", () => {
+    const state1 = pkce.generateState();
+    const state2 = pkce.generateState();
+    expect(typeof state1).toBe("string");
+    expect(state1.length).toBeGreaterThan(0);
+    expect(state1).not.toBe(state2); // Should be random
+  });
+
+  test("generatePKCEParams returns all required parameters", () => {
+    const params = pkce.generatePKCEParams();
+    expect(params.codeVerifier).toBeTruthy();
+    expect(params.codeChallenge).toBeTruthy();
+    expect(params.codeChallengeMethod).toBe("S256");
+    expect(params.state).toBeTruthy();
+  });
+});
+
+describe("Auth callback server", () => {
+  test("createCallbackServer returns correct interface", () => {
+    const server = authServer.createCallbackServer(0, "test-state", 1000);
+    expect(server.server).toBeTruthy();
+    expect(server.server.stop).toBeInstanceOf(Function);
+    expect(server.promise).toBeInstanceOf(Promise);
+    expect(server.ready).toBeInstanceOf(Promise);
+    expect(server.getPort).toBeInstanceOf(Function);
+
+    // Clean up
+    server.server.stop();
+  });
+
+  test("createCallbackServer binds to a port", async () => {
+    const server = authServer.createCallbackServer(0, "test-state", 5000);
+    const port = await server.ready;
+    expect(typeof port).toBe("number");
+    expect(port).toBeGreaterThan(0);
+
+    // Clean up
+    server.server.stop();
+  });
+
+  test("createCallbackServer responds to callback requests", async () => {
+    const testState = "test-state-" + Math.random().toString(36).substring(7);
+    const server = authServer.createCallbackServer(0, testState, 5000);
+    const port = await server.ready;
+
+    // Simulate OAuth callback
+    const testCode = "test-auth-code";
+    const callbackUrl = `http://127.0.0.1:${port}/callback?code=${testCode}&state=${testState}`;
+
+    const fetchPromise = fetch(callbackUrl);
+    const result = await server.promise;
+
+    expect(result.code).toBe(testCode);
+    expect(result.state).toBe(testState);
+
+    // Check response
+    const response = await fetchPromise;
+    expect(response.status).toBe(200);
+    const text = await response.text();
+    expect(text).toMatch(/Authentication successful/);
+  });
+
+  test("createCallbackServer rejects on state mismatch", async () => {
+    const server = authServer.createCallbackServer(0, "expected-state", 5000);
+    const port = await server.ready;
+
+    const callbackUrl = `http://127.0.0.1:${port}/callback?code=test-code&state=wrong-state`;
+
+    const fetchPromise = fetch(callbackUrl);
+
+    await expect(server.promise).rejects.toThrow(/State mismatch/);
+
+    const response = await fetchPromise;
+    expect(response.status).toBe(400);
+  });
+
+  test("createCallbackServer handles OAuth errors", async () => {
+    const server = authServer.createCallbackServer(0, "test-state", 5000);
+    const port = await server.ready;
+
+    const callbackUrl = `http://127.0.0.1:${port}/callback?error=access_denied&error_description=User%20denied%20access`;
+
+    const fetchPromise = fetch(callbackUrl);
+
+    await expect(server.promise).rejects.toThrow(/OAuth error: access_denied/);
+
+    const response = await fetchPromise;
+    expect(response.status).toBe(400);
+  });
+
+  test("createCallbackServer times out", async () => {
+    const server = authServer.createCallbackServer(0, "test-state", 100); // 100ms timeout
+    await server.ready;
+
+    await expect(server.promise).rejects.toThrow(/timeout/i);
+  });
+});
+
+describe("CLI auth commands", () => {
+  test("cli: auth login --help shows all options", () => {
+    const r = runCli(["auth", "login", "--help"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/--set-key/);
+    expect(r.stdout).toMatch(/--debug/);
+  });
+
+  test("cli: auth show-key --help works", () => {
+    const r = runCli(["auth", "show-key", "--help"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/show.*key/i);
+  });
+
+  test("cli: auth remove-key --help works", () => {
+    const r = runCli(["auth", "remove-key", "--help"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/remove.*key/i);
+  });
+});
+
+describe("maskSecret utility", () => {
+  test("masks short secrets completely", () => {
+    expect(util.maskSecret("abc")).toBe("****");
+    expect(util.maskSecret("12345678")).toBe("****");
+  });
+
+  test("masks medium secrets with visible ends", () => {
+    const masked = util.maskSecret("1234567890123456");
+    // maskSecret shows first 4 chars, middle masked, last 4 chars for 16-char strings
+    expect(masked).toMatch(/^1234\*+3456$/);
+  });
+
+  test("masks long secrets appropriately", () => {
+    const secret = "abcdefghij1234567890klmnopqrstuvwxyz";
+    const masked = util.maskSecret(secret);
+    expect(masked.startsWith("abcdefghij12")).toBe(true);
+    expect(masked.endsWith("wxyz")).toBe(true);
+    expect(masked).toMatch(/\*+/);
+  });
+
+  test("handles empty string", () => {
+    expect(util.maskSecret("")).toBe("");
+  });
+});

package/test/checkup.integration.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Integration tests for checkup command (express mode)
+ * Validates that CLI-generated reports match JSON schemas used by the Python reporter.
+ * This ensures compatibility between "express" and "full" (monitoring) modes.
+ */
+import { describe, test, expect, afterAll, beforeAll } from "bun:test";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as net from "net";
+import { Client } from "pg";
+import { resolve } from "path";
+import { readFileSync } from "fs";
+import Ajv2020 from "ajv/dist/2020";
+
+import * as checkup from "../lib/checkup";
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const schemasDir = resolve(import.meta.dir, "../../reporter/schemas");
+
+function findOnPath(cmd: string): string | null {
+  const result = Bun.spawnSync(["sh", "-c", `command -v ${cmd}`]);
+  if (result.exitCode === 0) {
+    return new TextDecoder().decode(result.stdout).trim();
+  }
+  return null;
+}
+
+function findPgBin(cmd: string): string | null {
+  const p = findOnPath(cmd);
+  if (p) return p;
+  const probe = Bun.spawnSync([
+    "sh",
+    "-c",
+    `ls -1 /usr/lib/postgresql/*/bin/${cmd} 2>/dev/null | head -n 1 || true`,
+  ]);
+  const out = new TextDecoder().decode(probe.stdout).trim();
+  if (out) return out;
+  return null;
+}
+
+function havePostgresBinaries(): boolean {
+  return !!(findPgBin("initdb") && findPgBin("postgres"));
+}
+
+function isRunningAsRoot(): boolean {
+  return process.getuid?.() === 0;
+}
+
+async function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address() as net.AddressInfo;
+      srv.close((err) => {
+        if (err) return reject(err);
+        resolve(addr.port);
+      });
+    });
+    srv.on("error", reject);
+  });
+}
+
+async function waitFor<T>(
+  fn: () => Promise<T>,
+  { timeoutMs = 10000, intervalMs = 100 } = {}
+): Promise<T> {
+  const start = Date.now();
+  while (true) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (Date.now() - start > timeoutMs) throw e;
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+}
+
+interface TempPostgres {
+  port: number;
+  socketDir: string;
+  cleanup: () => Promise<void>;
+  connect: (database?: string) => Promise<Client>;
+}
+
+async function createTempPostgres(): Promise<TempPostgres> {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "postgresai-checkup-"));
+  const dataDir = path.join(tmpRoot, "data");
+  const socketDir = path.join(tmpRoot, "sock");
+  fs.mkdirSync(socketDir, { recursive: true });
+
+  const initdb = findPgBin("initdb");
+  const postgresBin = findPgBin("postgres");
+  if (!initdb || !postgresBin) {
+    throw new Error("PostgreSQL binaries not found");
+  }
+
+  const init = Bun.spawnSync([initdb, "-D", dataDir, "-U", "postgres", "-A", "trust"]);
+  if (init.exitCode !== 0) {
+    throw new Error(new TextDecoder().decode(init.stderr) || new TextDecoder().decode(init.stdout));
+  }
+
+  const hbaPath = path.join(dataDir, "pg_hba.conf");
+  fs.appendFileSync(hbaPath, "\nlocal all all trust\n", "utf8");
+
+  const port = await getFreePort();
+  const postgresProc = Bun.spawn(
+    [postgresBin, "-D", dataDir, "-k", socketDir, "-h", "127.0.0.1", "-p", String(port)],
+    { stdio: ["ignore", "pipe", "pipe"] }
+  );
+
+  const cleanup = async () => {
+    postgresProc.kill("SIGTERM");
+    try {
+      await waitFor(
+        async () => {
+          if (postgresProc.exitCode === null) throw new Error("still running");
+        },
+        { timeoutMs: 5000, intervalMs: 100 }
+      );
+    } catch {
+      postgresProc.kill("SIGKILL");
+    }
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  };
+
+  const connect = async (database = "postgres"): Promise<Client> => {
+    const c = new Client({ host: socketDir, port, user: "postgres", database });
+    await c.connect();
+    return c;
+  };
+
+  // Wait for Postgres to start
+  await waitFor(async () => {
+    const c = await connect();
+    await c.end();
+  });
+
+  return { port, socketDir, cleanup, connect };
+}
+
+function validateAgainstSchema(report: any, checkId: string): void {
+  const schemaPath = resolve(schemasDir, `${checkId}.schema.json`);
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Schema not found: ${schemaPath}`);
+  }
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const validate = ajv.compile(schema);
+  const valid = validate(report);
+  if (!valid) {
+    const errors = validate.errors?.map(e => `${e.instancePath}: ${e.message}`).join(", ");
+    throw new Error(`${checkId} schema validation failed: ${errors}`);
+  }
+}
+
+// Skip tests if PostgreSQL binaries are not available
+const skipReason = !havePostgresBinaries()
+  ? "PostgreSQL binaries not available"
+  : isRunningAsRoot()
+  ? "Cannot run as root (PostgreSQL refuses)"
+  : null;
+
+// In CI, warn if integration tests are being skipped (helps catch configuration issues)
+const isCI = process.env.CI === "true" || process.env.GITLAB_CI === "true";
+if (skipReason && isCI) {
+  console.warn(`[CI WARNING] Integration tests skipped: ${skipReason}`);
+  console.warn("This may indicate a CI configuration issue - PostgreSQL binaries should be available.");
+}
+
+describe.skipIf(!!skipReason)("checkup integration: express mode schema compatibility", () => {
+  let pg: TempPostgres;
+  let client: Client;
+
+  beforeAll(async () => {
+    pg = await createTempPostgres();
+    client = await pg.connect();
+  });
+
+  afterAll(async () => {
+    if (client) await client.end();
+    if (pg) await pg.cleanup();
+  });
+
+  // Test all checks supported by express mode
+  const expressChecks = Object.keys(checkup.CHECK_INFO);
+
+  for (const checkId of expressChecks) {
+    test(`${checkId} report validates against shared schema`, async () => {
+      const generator = checkup.REPORT_GENERATORS[checkId];
+      expect(generator).toBeDefined();
+
+      const report = await generator(client, "test-node");
+
+      // Validate basic report structure (matching schema requirements)
+      expect(report).toHaveProperty("checkId", checkId);
+      expect(report).toHaveProperty("checkTitle");
+      expect(report).toHaveProperty("timestamptz");
+      expect(report).toHaveProperty("nodes");
+      expect(report).toHaveProperty("results");
+      expect(report.results).toHaveProperty("test-node");
+
+      // Validate against JSON schema (same schema used by Python reporter)
+      validateAgainstSchema(report, checkId);
+    });
+  }
+
+  test("generateAllReports produces valid reports for all checks", async () => {
+    const reports = await checkup.generateAllReports(client, "test-node");
+
+    expect(Object.keys(reports).length).toBe(expressChecks.length);
+
+    for (const [checkId, report] of Object.entries(reports)) {
+      validateAgainstSchema(report, checkId);
+    }
+  });
+
+  test("report structure matches Python reporter format", async () => {
+    // Generate A003 (settings) report and verify structure matches what Python produces
+    const report = await checkup.generateA003(client, "test-node");
+
+    // Check required fields match Python reporter output structure (per schema)
+    expect(report).toHaveProperty("checkId", "A003");
+    expect(report).toHaveProperty("checkTitle", "Postgres settings");
+    expect(report).toHaveProperty("timestamptz");
+    expect(report).toHaveProperty("nodes");
+    expect(report.nodes).toHaveProperty("primary");
+    expect(report.nodes).toHaveProperty("standbys");
+    expect(report).toHaveProperty("results");
+
+    // Results should have node-specific data
+    const nodeResult = report.results["test-node"];
+    expect(nodeResult).toHaveProperty("data");
+
+    // A003 should have settings as keyed object
+    expect(typeof nodeResult.data).toBe("object");
+
+    // Check postgres_version if present
+    if (nodeResult.postgres_version) {
+      expect(nodeResult.postgres_version).toHaveProperty("version");
+      expect(nodeResult.postgres_version).toHaveProperty("server_version_num");
+      expect(nodeResult.postgres_version).toHaveProperty("server_major_ver");
+      expect(nodeResult.postgres_version).toHaveProperty("server_minor_ver");
+    }
+  });
+
+  test("H001 (invalid indexes) has correct data structure", async () => {
+    const report = await checkup.generateH001(client, "test-node");
+    validateAgainstSchema(report, "H001");
+
+    const nodeResult = report.results["test-node"];
+    expect(nodeResult).toHaveProperty("data");
+    // data should be an object with indexes (may be empty on fresh DB)
+    expect(typeof nodeResult.data).toBe("object");
+  });
+
+  test("H002 (unused indexes) has correct data structure", async () => {
+    const report = await checkup.generateH002(client, "test-node");
+    validateAgainstSchema(report, "H002");
+
+    const nodeResult = report.results["test-node"];
+    expect(nodeResult).toHaveProperty("data");
+    expect(typeof nodeResult.data).toBe("object");
+  });
+
+  test("H004 (redundant indexes) has correct data structure", async () => {
+    const report = await checkup.generateH004(client, "test-node");
+    validateAgainstSchema(report, "H004");
+
+    const nodeResult = report.results["test-node"];
+    expect(nodeResult).toHaveProperty("data");
+    expect(typeof nodeResult.data).toBe("object");
+  });
+});