Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.4 KB
Raw Blame
/**
 * v0.39 behavioral coverage for `gbrain doctor`'s check orchestrator.
 *
 * Drives the exported `buildChecks(engine, args, dbSource): Promise<Check[]>`
 * seam directly (added in v0.39 — extracted from runDoctor's body so the
 * orchestrator is unit-testable without process.exit). Pairs with the
 * subprocess smoke at test/doctor-cli-smoke.test.ts which covers the
 * runDoctor render + exit-code path the seam can't reach in-process.
 *
 * Coverage strategy (D2 — "outcome-shaped + snapshot pin"):
 *   - Snapshot pin the check-name list against a fresh PGLite brain so
 *     accidental check drop-outs during refactors fail loudly with a
 *     reviewable diff at PR time.
 *   - Exercise computeDoctorReport math (3 fails → 60 pts lost, etc.) with
 *     synthesized inputs so the aggregation contract is pinned.
 *   - Honor the --fast flag's skip-set (DB checks absent).
 *   - --json arg is wrapper-only; buildChecks output unaffected.
 *
 * Per-check leaf coverage is deferred to a TODO (see plan): doctor.ts
 * exports 20+ check helpers (whoknowsHealthCheck, takesWeightGridCheck, …)
 * that warrant their own parameterized test file.
 */
import { describe, expect, test, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import {
  buildChecks,
  computeDoctorReport,
  type Check,
} from '../src/commands/doctor.ts';
import { buildEmbedSkipMarker } from '../src/core/embed-skip.ts';
import { PAGE_MAX_BYTES } from '../src/core/page-size-policy.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await resetPgliteState(engine);
});

describe('computeDoctorReport — pure score aggregation', () => {
  test('empty checks → healthy, score 100', () => {
    const r = computeDoctorReport([]);
    expect(r.schema_version).toBe(2);
    expect(r.status).toBe('healthy');
    expect(r.health_score).toBe(100);
    expect(r.checks).toEqual([]);
  });

  test('all ok → healthy, score 100', () => {
    const checks: Check[] = [
      { name: 'a', status: 'ok', message: '' },
      { name: 'b', status: 'ok', message: '' },
      { name: 'c', status: 'ok', message: '' },
    ];
    const r = computeDoctorReport(checks);
    expect(r.status).toBe('healthy');
    expect(r.health_score).toBe(100);
  });

  test('one warn → warnings, -5 points', () => {
    const checks: Check[] = [
      { name: 'a', status: 'ok', message: '' },
      { name: 'b', status: 'warn', message: '' },
    ];
    const r = computeDoctorReport(checks);
    expect(r.status).toBe('warnings');
    expect(r.health_score).toBe(95);
  });

  test('one fail → unhealthy, -20 points', () => {
    const r = computeDoctorReport([{ name: 'a', status: 'fail', message: '' }]);
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(80);
  });

  test('3 fails → unhealthy, -60 points (audit-driver math)', () => {
    const checks: Check[] = [
      { name: 'a', status: 'fail', message: '' },
      { name: 'b', status: 'fail', message: '' },
      { name: 'c', status: 'fail', message: '' },
    ];
    const r = computeDoctorReport(checks);
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(40);
  });

  test('mixed ok + warn + fail → unhealthy (fail dominates)', () => {
    const r = computeDoctorReport([
      { name: 'a', status: 'ok', message: '' },
      { name: 'b', status: 'warn', message: '' },
      { name: 'c', status: 'fail', message: '' },
    ]);
    // 1 fail (-20) + 1 warn (-5) = 75; fail status dominates ranking.
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(75);
  });

  test('score is clamped at 0 (never negative)', () => {
    const many: Check[] = Array.from({ length: 10 }, (_, i) => ({
      name: `f${i}`,
      status: 'fail' as const,
      message: '',
    }));
    const r = computeDoctorReport(many);
    expect(r.health_score).toBe(0);
    expect(r.status).toBe('unhealthy');
  });
});

describe('buildChecks — orchestrator against PGLite', () => {
  test('returns a non-empty Check[] against a fresh brain', async () => {
    const checks = await buildChecks(engine, []);
    expect(Array.isArray(checks)).toBe(true);
    expect(checks.length).toBeGreaterThan(10);
    // Every check has the contracted shape.
    for (const c of checks) {
      expect(typeof c.name).toBe('string');
      expect(['ok', 'warn', 'fail']).toContain(c.status);
      expect(typeof c.message).toBe('string');
    }
  });

  test('snapshot: load-bearing check names always run against a fresh brain', async () => {
    // Behavior-preservation snapshot (D6 lock). Pinning a CURATED subset of
    // load-bearing checks rather than the full list so this test stays stable
    // when new checks land deliberately — but breaks loudly if a known
    // load-bearing check accidentally drops out during a refactor.
    //
    // Deliberately tight set: only checks whose code path is unconditional
    // given an engine + has no env / config dependencies that vary between
    // test processes. Adding more sensitive checks here (e.g. ones that
    // read process.env) caused cross-shard flakes under the parallel runner.
    // Per-check leaf coverage is the TODO that targets the broader surface.
    const checks = await buildChecks(engine, []);
    const names = new Set(checks.map(c => c.name));
    const loadBearing = [
      'connection',
      'schema_version',
      'brain_score',
      'sync_freshness',
      'search_mode',
      'eval_drift',
      'reranker_health',
      'embedding_width_consistency',
      'autopilot_lock_scope',
    ];
    // NOTE: sync_failures and slug_fallback_audit are deliberately NOT in
    // the load-bearing set — they're only pushed when the corresponding
    // JSONL file exists. Tests run on isolated tmpdir GBRAIN_HOMEs where
    // those files may or may not exist depending on which sibling tests
    // already wrote audit lines.
    const missing = loadBearing.filter(n => !names.has(n));
    expect(missing, `load-bearing checks missing from buildChecks result: ${missing.join(', ')}`).toEqual([]);
    // Plus a minimum total count — drops below ~30 means something
    // bigger went wrong than the snapshot can name.
    expect(checks.length).toBeGreaterThan(30);
  });

  test('--fast skips DB-dependent checks; filesystem checks still run', async () => {
    // Fast-mode bails out of the DB section entirely. When an engine is
    // available, the early-return skips pushing a connection check (no
    // probe happened); when engine is null AND --fast, a warn-status
    // synthesized connection check is added. Filesystem checks above
    // the DB phase always run.
    const checks = await buildChecks(engine, ['--fast']);
    const names = new Set(checks.map(c => c.name));
    // DB-dependent checks should NOT be present.
    expect(names.has('schema_version')).toBe(false);
    expect(names.has('brain_score')).toBe(false);
    expect(names.has('sync_freshness')).toBe(false);
    // Filesystem checks above the DB phase still ran.
    expect(names.has('resolver_health')).toBe(true);

    // The null-engine + --fast path DOES synthesize a connection warn.
    const fsOnlyChecks = await buildChecks(null, ['--fast'], 'env:DATABASE_URL');
    const fsOnlyNames = new Set(fsOnlyChecks.map(c => c.name));
    expect(fsOnlyNames.has('connection')).toBe(true);
    const conn = fsOnlyChecks.find(c => c.name === 'connection')!;
    expect(conn.status).toBe('warn');
    expect(conn.message.toLowerCase()).toContain('fast');
  });

  test('--json arg does NOT alter the returned check list', async () => {
    // --json is a wrapper-level concern (controls outputResults render mode);
    // the buildChecks seam should return the same checks regardless.
    const without = await buildChecks(engine, []);
    const withJson = await buildChecks(engine, ['--json']);
    expect(withJson.map(c => c.name)).toEqual(without.map(c => c.name));
  });

  test('returns partial check list when engine is null (no early process.exit)', async () => {
    // Pre-v0.39 the no-engine path called outputResults + process.exit
    // directly. Post-extract it returns the partial list so the wrapper
    // decides exit code. This is the load-bearing assertion that proves
    // the early-exit refactor preserved observable behavior.
    const checks = await buildChecks(null, []);
    expect(Array.isArray(checks)).toBe(true);
    const connection = checks.find(c => c.name === 'connection');
    expect(connection).toBeDefined();
    expect(connection!.status).toBe('warn');
  });

  test('content-sanity checks run on PGLite — oversized page warns, none die on the dead postgres singleton (#1871)', async () => {
    // Pre-fix these three checks reached the DB via db.getConnection() —
    // the postgres.js singleton, which is never connected on the default
    // PGLite engine — so every run reported
    // "Skipped (No database connection: connect() has not been called)".
    const big = 'oversized page body prose for the block threshold probe. '.repeat(Math.ceil((PAGE_MAX_BYTES + 1) / 57)); // over the 24 MiB default block
    await engine.putPage('wiki/oversized-probe-1871', {
      type: 'note',
      title: 'Oversized Probe 1871',
      compiled_truth: big,
      timeline: '',
      frontmatter: {},
    });

    const checks = await buildChecks(engine, []);

    const oversized = checks.find(c => c.name === 'oversized_pages');
    expect(oversized).toBeDefined();
    expect(oversized!.status).toBe('warn');
    expect(oversized!.message).toContain('oversized-probe-1871');

    // The sibling checks now execute for real on PGLite too.
    const junk = checks.find(c => c.name === 'scraper_junk_pages');
    expect(junk).toBeDefined();
    expect(junk!.message).not.toContain('Skipped');
    const mbc = checks.find(c => c.name === 'markdown_body_completeness');
    expect(mbc).toBeDefined();

    // No check on a healthy PGLite brain reports the dead-singleton error.
    for (const c of checks) {
      expect(c.message).not.toContain('connect() has not been called');
    }
  });

  test('oversized_pages excludes pages that already took the embed_skip remediation (gbrain dogfooding find)', async () => {
    // The warn message for this check says "existing oversized pages can be
    // ... accepted as non-embeddable" (i.e. frontmatter.embed_skip set).
    // Before this fix the underlying query never excluded those pages, so a
    // page an operator had already remediated the documented way kept
    // re-appearing in this check's output on every run with no way to clear
    // it short of deleting the page. Uses the real production marker shape
    // (an object from buildEmbedSkipMarker, not a bare boolean) — the
    // canonical writer (src/core/content-sanity.ts) never writes a boolean,
    // and the exclusion must match what actually lands in frontmatter.
    const big = 'oversized page body prose for the embed_skip exclusion probe. '.repeat(Math.ceil((PAGE_MAX_BYTES + 1) / 62));
    await engine.putPage('wiki/oversized-embed-skip-probe', {
      type: 'note',
      title: 'Oversized Embed-Skip Probe',
      compiled_truth: big,
      timeline: '',
      frontmatter: { embed_skip: buildEmbedSkipMarker(big.length) },
    });

    const checks = await buildChecks(engine, []);
    const oversized = checks.find(c => c.name === 'oversized_pages');
    expect(oversized).toBeDefined();
    // Positive control above (line ~227) proves the same byte count without
    // embed_skip DOES warn and names the page — this proves the ONLY
    // difference (embed_skip set) is what excludes it.
    expect(oversized!.status).toBe('ok');
    expect(oversized!.message).not.toContain('oversized-embed-skip-probe');
  });

  test('oversized_pages still warns when embed_skip is absent (does not exclude every page)', async () => {
    // Sibling positive control to the exclusion test above: a page with no
    // embed_skip key at all must still warn, proving the exclusion is
    // scoped to the marker's presence and isn't a query regression that
    // silently stops counting oversized pages altogether.
    //
    // Note: per the canonical contract in src/core/embed-skip.ts
    // (isEmbedSkipped: "any non-null value" is skip, by design — the
    // predicate is key-EXISTENCE, not a boolean value check), an explicit
    // `embed_skip: false` is ALSO treated as skip, matching every other
    // embed-skip consumer in the codebase (embed.ts, postgres-engine.ts,
    // pglite-engine.ts). This check must stay consistent with that shared
    // contract rather than inventing its own true/false semantics.
    const big = 'oversized page body prose for the embed_skip-absent probe. '.repeat(Math.ceil((PAGE_MAX_BYTES + 1) / 59));
    await engine.putPage('wiki/oversized-embed-skip-absent-probe', {
      type: 'note',
      title: 'Oversized Embed-Skip-Absent Probe',
      compiled_truth: big,
      timeline: '',
    });

    const checks = await buildChecks(engine, []);
    const oversized = checks.find(c => c.name === 'oversized_pages');
    expect(oversized).toBeDefined();
    expect(oversized!.status).toBe('warn');
    expect(oversized!.message).toContain('oversized-embed-skip-absent-probe');
  });

  test('#6526: oversized_pages honors a DB-plane content_sanity.bytes_block override', async () => {
    // The check read bytes_block from the file and env planes only (loadConfig), so a
    // `gbrain config set content_sanity.bytes_block N` that the write gate honors never
    // reached it. It now uses the gate's resolution (import-screen.ts effectiveBytesBlock).
    // The page sits between the operator's 500_000 and the 24 MiB default, with no
    // embed_skip marker, so the DB-plane value alone decides the warn.
    const lowered = 500_000;
    await engine.setConfig('content_sanity.bytes_block', String(lowered));
    try {
      const big = 'oversized page body prose for the db-plane override probe. '.repeat(11_000); // ~650KB
      await engine.putPage('wiki/oversized-db-plane-probe', {
        type: 'note',
        title: 'Oversized DB-Plane Probe',
        compiled_truth: big,
        timeline: '',
      });

      const checks = await buildChecks(engine, []);
      const oversized = checks.find(c => c.name === 'oversized_pages');
      expect(oversized).toBeDefined();
      expect(oversized!.status).toBe('warn');
      expect(oversized!.message).toContain('oversized-db-plane-probe');
      expect(oversized!.message).toContain(`${lowered}`);
    } finally {
      await engine.unsetConfig('content_sanity.bytes_block');
    }
  });

  test('mixed-outcome render path: synthesized checks aggregate as expected', () => {
    // The orchestrator's render path (outputResults in the wrapper) reads
    // the same DoctorReport.status enum we compute here. Pin the
    // ok+warn+fail aggregation so the wrapper's render of a real mixed
    // brain state is reproducible.
    const mixed: Check[] = [
      { name: 'resolver_health', status: 'ok', message: '50 skills' },
      { name: 'sync_failures', status: 'warn', message: '2 unacked' },
      { name: 'schema_version', status: 'fail', message: 'mid-upgrade' },
    ];
    const r = computeDoctorReport(mixed);
    expect(r.status).toBe('unhealthy');
    expect(r.health_score).toBe(75);
    expect(r.checks).toHaveLength(3);
    expect(r.checks.map(c => c.status)).toEqual(['ok', 'warn', 'fail']);
  });
});