Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.6 KB
Raw Blame
/**
 * Refactor wave 1 (W4 doctor, EO11 / DX O5): the doctor check registry
 * contract.
 *
 * - Every entry's `name` and every name in its `emits[]` is categorized by
 *   src/core/doctor-categories.ts, the single category authority. An
 *   uncategorized entry fails with FAIL / Why / Fix / See text.
 * - `emits[]` is exactly what the entry's `run` can push (AST walk from
 *   test/helpers/doctor-registry-ast.ts), so the category check cannot be
 *   dodged by an incomplete list.
 * - The runtime registry matches the statically walked one, and only the two
 *   gate entries return STOP_DOCTOR, placed where master's buildChecks
 *   returned early (the W0 golden's `early_returns_after`).
 */
import { describe, expect, test } from 'bun:test';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { DOCTOR_CHECK_REGISTRY } from '../src/commands/doctor/registry.ts';
import type { DoctorEntry } from '../src/commands/doctor/context.ts';
import {
  BRAIN_CHECK_NAMES,
  META_CHECK_NAMES,
  OPS_CHECK_NAMES,
  SKILL_CHECK_NAMES,
} from '../src/core/doctor-categories.ts';
import { extractDoctorRegistryEntries } from './helpers/doctor-registry-ast.ts';
import { GOLDENS_DIR } from './helpers/golden.ts';

const CATEGORIZED = new Set([...BRAIN_CHECK_NAMES, ...SKILL_CHECK_NAMES, ...OPS_CHECK_NAMES, ...META_CHECK_NAMES]);

/** One FAIL/Why/Fix/See block per uncategorized name, empty when every entry is categorized. */
function uncategorizedFailures(entries: ReadonlyArray<Pick<DoctorEntry, 'name' | 'emits'> & { file?: string }>): string[] {
  const out: string[] = [];
  for (const e of entries) {
    const where = e.file ? `${e.file} ` : '';
    for (const [field, name] of [['name', e.name] as const, ...e.emits.map((n) => ['emits', n] as const)]) {
      if (CATEGORIZED.has(name)) continue;
      out.push(
        [
          `FAIL: ${where}doctor registry entry '${e.name}' ${field} '${name}' is not categorized`,
          'Why:  src/core/doctor-categories.ts is the single category authority; an uncategorized check falls through to meta and skews category_scores.',
          `Fix:  add '${name}' to exactly one of BRAIN_CHECK_NAMES / SKILL_CHECK_NAMES / OPS_CHECK_NAMES / META_CHECK_NAMES in src/core/doctor-categories.ts`,
          'See:  docs/TESTING.md#doctor-check-registry',
        ].join('\n'),
      );
    }
  }
  return out;
}

const STATIC = extractDoctorRegistryEntries();

describe('doctor check registry contract', () => {
  test('every entry name and emitted check is categorized in doctor-categories.ts', () => {
    const failures = uncategorizedFailures(STATIC);
    if (failures.length > 0) throw new Error(failures.join('\n\n'));
    expect(failures).toEqual([]);
  });

  test('an uncategorized entry fails with FAIL / Why / Fix / See text (bad fixture)', () => {
    const bad = [{ name: 'resolver_health', emits: ['resolver_health', 'not_a_check_example'], file: 'src/commands/doctor/checks/fixture.ts' }];
    const failures = uncategorizedFailures(bad);
    expect(failures).toHaveLength(1);
    const [msg] = failures;
    expect(msg).toStartWith("FAIL: src/commands/doctor/checks/fixture.ts doctor registry entry 'resolver_health' emits 'not_a_check_example'");
    expect(msg).toContain('\nWhy:  ');
    expect(msg).toContain("\nFix:  add 'not_a_check_example' to exactly one of");
    expect(msg).toContain('src/core/doctor-categories.ts');
    expect(msg).toContain('\nSee:  docs/TESTING.md#doctor-check-registry');
    expect(uncategorizedFailures([{ name: 'bad_entry_example', emits: [] }])[0]).toContain("name 'bad_entry_example' is not categorized");
    expect(uncategorizedFailures([{ name: 'rls', emits: ['rls'] }])).toEqual([]);
  });

  test("emits[] lists exactly the checks each entry's run can push, and name is one of them", () => {
    for (const e of STATIC) {
      if (JSON.stringify(e.emits) !== JSON.stringify(e.names)) {
        console.error(
          `FAIL: entry ${e.entry} declares emits ${JSON.stringify(e.emits)} but its run pushes ${JSON.stringify(e.names)}\nWhy: emits[] is checked against an AST walk of run, which only sees checks.push({ name: '<literal>', ... }) inside run itself.\nFix: build const checks: Check[] = [] in run and call checks.push({ name: '<literal>', ... }) directly (no helper, no returned array literal), or correct emits.\nSee: test/helpers/doctor-registry-ast.ts, CONTRIBUTING.md#where-does-my-change-go`,
        );
      }
      expect({ entry: e.entry, emits: e.emits }).toEqual({ entry: e.entry, emits: e.names });
      if (e.names.length > 0) expect({ entry: e.entry, nameEmitted: e.names.includes(e.name) }).toEqual({ entry: e.entry, nameEmitted: true });
    }
  });

  test('the runtime registry is the statically walked registry, in order', () => {
    expect(DOCTOR_CHECK_REGISTRY.map((e) => ({ name: e.name, emits: [...e.emits] }))).toEqual(
      STATIC.map((e) => ({ name: e.name, emits: e.emits })),
    );
  });

  test("only the two gates stop, right where master's buildChecks returned early", () => {
    const golden = JSON.parse(readFileSync(join(GOLDENS_DIR, 'doctor', 'registry-build-checks.json'), 'utf-8')) as {
      golden: { early_returns_after: string[] };
    };
    const stops = STATIC.map((e, i) => ({ e, i })).filter(({ e }) => e.stops);
    expect(stops.map(({ e }) => e.entry)).toEqual(['dbChecksGateEntry', 'connectionGateEntry']);
    for (const { e } of stops) expect({ entry: e.entry, emits: e.emits }).toEqual({ entry: e.entry, emits: [] });
    const lastBefore = stops.map(({ i }) => STATIC.slice(0, i).flatMap((e) => e.names).at(-1));
    expect(lastBefore).toEqual(golden.golden.early_returns_after);
  });
});