@indigoai-us/hq-cli 5.98.2 → 5.99.0

package/dist/lib/doctor/fixtures/discover.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Runtime fixture discovery and the UNTESTED coverage tier (US-007).
+ *
+ * Fixtures are discovered from `core/hook-tests/*.yaml` in the *resolved HQ
+ * tree* at runtime, not bundled into the CLI — so a maintainer adds or changes a
+ * hook's expectation by committing a YAML file to hq-core, with no npm release.
+ * This module is the I/O half of that contract: it reads the directory, hands
+ * each document to the pure {@link parseFixture} validator, cross-references the
+ * results against the hooks the wiring tier found registered, and emits the
+ * coverage results.
+ *
+ * The coverage line — `tested/total` — is the load-bearing output of this story.
+ * It is not cosmetic: a doctor that quietly reports nothing for the hooks it has
+ * no fixture for reads as a clean bill of health, which is precisely the false
+ * confidence the whole tool exists to prevent. So every registered hook without
+ * a fixture is reported UNTESTED by name, and the ratio is surfaced in the
+ * summary, making thin coverage impossible to miss and giving maintainers a
+ * number that only grows as fixtures are added.
+ *
+ * Result mapping, in precedence order per fixture:
+ *   - a malformed / non-YAML fixture            -> WARN (skipped, named)
+ *   - a fixture whose hook id is not registered -> WARN orphan (deleted hook?)
+ *   - a registered hook, unrecognised version   -> UNKNOWN (names both versions)
+ *   - a registered hook, valid fixture          -> counted as tested
+ * and per registered hook with no usable fixture -> UNTESTED.
+ */
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+import { type ParsedFixture } from "./schema.js";
+/** Directory, relative to the HQ root, fixtures are discovered from. */
+export declare const HOOK_TESTS_RELDIR: string;
+/** The id of the fixture-coverage family. */
+export declare const FIXTURES_FAMILY_ID = "fixtures";
+/** checkId of the single coverage-ratio result the report surfaces in its summary. */
+export declare const FIXTURE_COVERAGE_CHECK_ID = "hooks.fixtures.coverage";
+/**
+ * The hook ids the wiring tier found registered, deduplicated and sorted. A hook
+ * id is the identity a fixture is keyed by: the id passed to `hook-gate.sh` when
+ * a command routes through the gate (the common case), or the script's basename
+ * without `.sh` otherwise.
+ *
+ * Registrations are read from `.claude/settings.json` and
+ * `.claude/settings.local.json`. Claude and Grok both execute the canonical
+ * `.claude/hooks/` scripts and Codex only mirrors them, so the Claude settings
+ * carry the canonical hook-id set the fixtures are written against.
+ */
+export declare function registeredHookIds(hqRoot: string): string[];
+/** A fixture file located on disk and validated (or a YAML-load failure). */
+export interface DiscoveredFixture {
+    /** Path relative to the HQ root, e.g. `core/hook-tests/block-core-writes.yaml`. */
+    relpath: string;
+    /** Absolute path on disk. */
+    absPath: string;
+    /** Filename stem, used as the default hook id when the doc omits one. */
+    defaultHookId: string;
+    /** The validation outcome, or a YAML syntax error. */
+    parsed: ParsedFixture | {
+        status: "yaml-error";
+        message: string;
+    };
+}
+/** The outcome of scanning `core/hook-tests/` for fixtures. */
+export interface FixtureDiscovery {
+    /** Absolute fixtures directory (whether or not it exists). */
+    dir: string;
+    /** Whether `core/hook-tests/` exists on disk. */
+    present: boolean;
+    /** The fixture files found, in sorted filename order. Non-fixtures are skipped. */
+    fixtures: DiscoveredFixture[];
+}
+/**
+ * Discover and validate every fixture under `core/hook-tests/`. A `*.yaml` file
+ * that carries none of the fixture keys (for example `allowed-divergence.yaml`)
+ * is not a fixture and is skipped silently — only files that {@link
+ * looksLikeFixture} are validated and reported.
+ */
+export declare function discoverFixtures(hqRoot: string): FixtureDiscovery;
+/** The coverage tally: how many registered hooks have a usable fixture. */
+export interface FixtureCoverage {
+    /** Registered hooks with a valid, recognised-version fixture. */
+    tested: number;
+    /** Registered hooks in total. */
+    total: number;
+}
+/**
+ * Run the fixture-coverage tier against the resolved tree: enumerate registered
+ * hooks, discover fixtures, and emit UNTESTED / WARN / UNKNOWN results plus the
+ * `tested/total` coverage line. Read-only and never throws.
+ */
+export declare function checkFixtureCoverage(context: CheckContext): CheckResult[];
+/**
+ * The fixture-coverage check family. Registered alongside the hooks family so
+ * every run reports coverage; adding it needs no engine change (US-002's
+ * registry contract).
+ */
+export declare const fixtureCoverageFamily: CheckFamily;
+//# sourceMappingURL=discover.d.ts.map

package/dist/lib/doctor/fixtures/discover.js

@@ -0,0 +1,287 @@
+/**
+ * Runtime fixture discovery and the UNTESTED coverage tier (US-007).
+ *
+ * Fixtures are discovered from `core/hook-tests/*.yaml` in the *resolved HQ
+ * tree* at runtime, not bundled into the CLI — so a maintainer adds or changes a
+ * hook's expectation by committing a YAML file to hq-core, with no npm release.
+ * This module is the I/O half of that contract: it reads the directory, hands
+ * each document to the pure {@link parseFixture} validator, cross-references the
+ * results against the hooks the wiring tier found registered, and emits the
+ * coverage results.
+ *
+ * The coverage line — `tested/total` — is the load-bearing output of this story.
+ * It is not cosmetic: a doctor that quietly reports nothing for the hooks it has
+ * no fixture for reads as a clean bill of health, which is precisely the false
+ * confidence the whole tool exists to prevent. So every registered hook without
+ * a fixture is reported UNTESTED by name, and the ratio is surfaced in the
+ * summary, making thin coverage impossible to miss and giving maintainers a
+ * number that only grows as fixtures are added.
+ *
+ * Result mapping, in precedence order per fixture:
+ *   - a malformed / non-YAML fixture            -> WARN (skipped, named)
+ *   - a fixture whose hook id is not registered -> WARN orphan (deleted hook?)
+ *   - a registered hook, unrecognised version   -> UNKNOWN (names both versions)
+ *   - a registered hook, valid fixture          -> counted as tested
+ * and per registered hook with no usable fixture -> UNTESTED.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { scanHookCommand } from "../checks/claude-wiring.js";
+import { looksLikeFixture, parseFixture, SUPPORTED_FIXTURE_SCHEMA_VERSIONS, } from "./schema.js";
+/** Directory, relative to the HQ root, fixtures are discovered from. */
+export const HOOK_TESTS_RELDIR = path.join("core", "hook-tests");
+/** The id of the fixture-coverage family. */
+export const FIXTURES_FAMILY_ID = "fixtures";
+/** checkId of the single coverage-ratio result the report surfaces in its summary. */
+export const FIXTURE_COVERAGE_CHECK_ID = "hooks.fixtures.coverage";
+/** A `*.yaml` file in `core/hook-tests/` that is not a fixture and must be skipped. */
+const NON_FIXTURE_FILES = new Set(["allowed-divergence.yaml"]);
+// --- registered-hook enumeration ----------------------------------------------
+/**
+ * The hook ids the wiring tier found registered, deduplicated and sorted. A hook
+ * id is the identity a fixture is keyed by: the id passed to `hook-gate.sh` when
+ * a command routes through the gate (the common case), or the script's basename
+ * without `.sh` otherwise.
+ *
+ * Registrations are read from `.claude/settings.json` and
+ * `.claude/settings.local.json`. Claude and Grok both execute the canonical
+ * `.claude/hooks/` scripts and Codex only mirrors them, so the Claude settings
+ * carry the canonical hook-id set the fixtures are written against.
+ */
+export function registeredHookIds(hqRoot) {
+    const claudeDir = path.join(hqRoot, ".claude");
+    const commands = [
+        ...settingsCommands(path.join(claudeDir, "settings.json")),
+        ...settingsCommands(path.join(claudeDir, "settings.local.json")),
+    ];
+    const ids = new Set();
+    for (const command of commands) {
+        const id = hookIdFromCommand(command);
+        if (id)
+            ids.add(id);
+    }
+    return [...ids].sort();
+}
+/** Every `type: "command"` hook command across all events in one settings file. */
+function settingsCommands(file) {
+    const settings = readJson(file);
+    if (!settings || typeof settings !== "object")
+        return [];
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    const out = [];
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const item of inner) {
+                const hook = item;
+                if (hook?.type === "command" && typeof hook.command === "string") {
+                    out.push(hook.command);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The hook id a command identifies: the gated id when it routes through
+ * `hook-gate.sh`, else the basename (sans `.sh`) of the first script it runs.
+ * `hook-gate.sh` itself is never a hook id.
+ */
+function hookIdFromCommand(command) {
+    const scan = scanHookCommand(command);
+    if (scan.gatedHookId)
+        return scan.gatedHookId;
+    for (const rp of scan.requiredRelpaths) {
+        const base = path.basename(rp);
+        if (base === "hook-gate.sh")
+            continue;
+        return base.replace(/\.sh$/, "");
+    }
+    return null;
+}
+/**
+ * Discover and validate every fixture under `core/hook-tests/`. A `*.yaml` file
+ * that carries none of the fixture keys (for example `allowed-divergence.yaml`)
+ * is not a fixture and is skipped silently — only files that {@link
+ * looksLikeFixture} are validated and reported.
+ */
+export function discoverFixtures(hqRoot) {
+    const dir = path.join(hqRoot, HOOK_TESTS_RELDIR);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { dir, present: false, fixtures: [] };
+    }
+    const fixtures = [];
+    for (const name of names.sort()) {
+        if (!/\.ya?ml$/i.test(name))
+            continue;
+        if (NON_FIXTURE_FILES.has(name))
+            continue;
+        const absPath = path.join(dir, name);
+        const relpath = path.join(HOOK_TESTS_RELDIR, name);
+        const defaultHookId = name.replace(/\.ya?ml$/i, "");
+        let doc;
+        try {
+            doc = yaml.load(fs.readFileSync(absPath, "utf8"));
+        }
+        catch (error) {
+            fixtures.push({
+                relpath,
+                absPath,
+                defaultHookId,
+                parsed: { status: "yaml-error", message: error.message },
+            });
+            continue;
+        }
+        // A YAML file with none of the fixture keys is another kind of config file
+        // living in the same directory — skip it rather than flag it as malformed.
+        if (!looksLikeFixture(doc))
+            continue;
+        fixtures.push({
+            relpath,
+            absPath,
+            defaultHookId,
+            parsed: parseFixture(doc, { defaultHookId }),
+        });
+    }
+    return { dir, present: true, fixtures };
+}
+/**
+ * Run the fixture-coverage tier against the resolved tree: enumerate registered
+ * hooks, discover fixtures, and emit UNTESTED / WARN / UNKNOWN results plus the
+ * `tested/total` coverage line. Read-only and never throws.
+ */
+export function checkFixtureCoverage(context) {
+    const hqRoot = context.hqRoot;
+    const registered = registeredHookIds(hqRoot);
+    const registeredSet = new Set(registered);
+    const discovery = discoverFixtures(hqRoot);
+    const results = [];
+    const testedIds = new Set();
+    const unknownVersion = new Map();
+    for (const fixture of discovery.fixtures) {
+        const parsed = fixture.parsed;
+        if (parsed.status === "yaml-error") {
+            results.push({
+                status: "WARN",
+                checkId: "hooks.fixtures.invalid",
+                target: fixture.relpath,
+                message: `Fixture ${fixture.relpath} is not valid YAML and was skipped: ${parsed.message}`,
+                remediation: `Fix the YAML syntax in ${fixture.relpath}.`,
+            });
+            continue;
+        }
+        if (parsed.status === "invalid") {
+            results.push({
+                status: "WARN",
+                checkId: "hooks.fixtures.invalid",
+                target: fixture.relpath,
+                message: `Fixture ${fixture.relpath} is malformed and was skipped: ${parsed.message}.`,
+                remediation: `Correct ${fixture.relpath} against core/hook-tests/README.md.`,
+            });
+            continue;
+        }
+        const hookId = parsed.status === "ok"
+            ? parsed.fixture.hookId
+            : (parsed.hookId ?? fixture.defaultHookId);
+        // A fixture pointing at a hook that is registered nowhere is an orphan —
+        // most likely a leftover from a hook that was deleted. This takes precedence
+        // over the version check: there is no point telling the user a non-existent
+        // hook's fixture is on an unknown schema.
+        if (!registeredSet.has(hookId)) {
+            results.push({
+                status: "WARN",
+                checkId: "hooks.fixtures.orphan",
+                target: fixture.relpath,
+                message: `Fixture ${fixture.relpath} targets hook id "${hookId}", which is not registered in any settings file (orphan fixture).`,
+                remediation: `Remove ${fixture.relpath}, or restore the "${hookId}" hook registration.`,
+            });
+            continue;
+        }
+        if (parsed.status === "unsupported-version") {
+            unknownVersion.set(hookId, {
+                relpath: fixture.relpath,
+                declared: parsed.declaredVersion,
+            });
+            continue;
+        }
+        testedIds.add(hookId);
+    }
+    // Per registered hook, in sorted order: covered hooks are silent (counted in
+    // the ratio); a hook whose only fixture is on an unrecognised schema is
+    // UNKNOWN (never PASS); everything else is UNTESTED.
+    for (const hookId of registered) {
+        if (testedIds.has(hookId))
+            continue;
+        const unknown = unknownVersion.get(hookId);
+        if (unknown) {
+            results.push({
+                status: "UNKNOWN",
+                checkId: "hooks.fixtures.unknown-schema",
+                target: hookId,
+                message: `Fixture ${unknown.relpath} declares schema version ${formatVersion(unknown.declared)}, ` +
+                    `which this hq CLI does not recognise (supported: ${SUPPORTED_FIXTURE_SCHEMA_VERSIONS.join(", ")}); ` +
+                    `hook "${hookId}" cannot be evaluated and is not counted as tested.`,
+                remediation: "Upgrade the hq CLI, or re-author the fixture on a supported schema version.",
+            });
+            continue;
+        }
+        results.push({
+            status: "UNTESTED",
+            checkId: "hooks.fixtures.untested",
+            target: hookId,
+            message: `Hook "${hookId}" is registered but has no fixture; its behaviour is never exercised.`,
+            remediation: `Add core/hook-tests/${hookId}.yaml (see core/hook-tests/README.md).`,
+        });
+    }
+    const coverage = { tested: testedIds.size, total: registered.length };
+    results.push(coverageResult(coverage));
+    return results;
+}
+/**
+ * The single coverage-ratio result. Status NA: it is an informational meta-line,
+ * never a pass or a failure. The report surfaces its message in the run summary;
+ * its `target` carries the raw `tested/total` ratio for machine consumers.
+ */
+function coverageResult(coverage) {
+    const { tested, total } = coverage;
+    return {
+        status: "NA",
+        checkId: FIXTURE_COVERAGE_CHECK_ID,
+        target: `${tested}/${total}`,
+        message: `Fixture coverage: ${tested}/${total} registered hook${total === 1 ? "" : "s"} have a fixture.`,
+    };
+}
+/** Render a declared schema version for a message, quoting non-numbers. */
+function formatVersion(value) {
+    return typeof value === "number" ? String(value) : JSON.stringify(value);
+}
+/**
+ * The fixture-coverage check family. Registered alongside the hooks family so
+ * every run reports coverage; adding it needs no engine change (US-002's
+ * registry contract).
+ */
+export const fixtureCoverageFamily = {
+    id: FIXTURES_FAMILY_ID,
+    title: "Fixture coverage",
+    run: (context) => Promise.resolve(checkFixtureCoverage(context)),
+};
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=discover.js.map

package/dist/lib/doctor/fixtures/schema.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The hook-fixture schema — the declarative format that pins a hook's expected
+ * behaviour in a file shipped next to the hook (US-007).
+ *
+ * The owner's chosen split is the whole point of this module: all executable
+ * logic lives in hq-cli, but the per-hook expectation *data* lives in the HQ
+ * tree at `core/hook-tests/*.yaml`, so a hook and its test ship in the same
+ * hq-core commit and adding a test needs no CLI release. This file owns the
+ * data contract that bridge rests on:
+ *
+ *   - {@link parseFixture} validates one already-parsed YAML document into a
+ *     typed {@link HookFixture}, or classifies it as *unsupported-version* or
+ *     *invalid*. It never touches the filesystem — {@link discoverFixtures}
+ *     (discover.ts) handles I/O and hands plain objects here — which keeps the
+ *     schema a pure, exhaustively unit-testable function.
+ *
+ *   - An unrecognised {@link HookFixture.schemaVersion} is a first-class outcome,
+ *     not an error: a fixture written against a future schema must degrade to
+ *     UNKNOWN (naming both versions) rather than FAIL or, worse, PASS. Baking a
+ *     stale expectation into a green result is exactly the false-confidence
+ *     failure mode `hq doctor` exists to prevent.
+ *
+ *   - {@link classifyCaseStatus} encodes the `expectedFailure` rule (a case that
+ *     pins a known, unfixed defect): a failing such case reports KNOWN-DEFECT
+ *     rather than FAIL, and one that unexpectedly passes reports WARN that the
+ *     marker is stale and should be removed. Case *execution* is US-008; this
+ *     module owns only the classification semantics, so both the doctor and its
+ *     tests agree on what a case outcome means.
+ */
+import type { DoctorStatus } from "../types.js";
+/**
+ * Every fixture schema version this build of the CLI can interpret. A fixture
+ * declaring a version outside this set is reported UNKNOWN, never PASS — see
+ * {@link parseFixture}. Grows by one when the shape below changes.
+ */
+export declare const SUPPORTED_FIXTURE_SCHEMA_VERSIONS: readonly [1];
+/** A schema version this CLI understands. */
+export type FixtureSchemaVersion = (typeof SUPPORTED_FIXTURE_SCHEMA_VERSIONS)[number];
+/** The schema version new fixtures should be authored against. */
+export declare const CURRENT_FIXTURE_SCHEMA_VERSION: FixtureSchemaVersion;
+/** Whether `value` is a schema version this build recognises. */
+export declare function isSupportedSchemaVersion(value: unknown): value is FixtureSchemaVersion;
+/**
+ * A case's expected outcome. Exactly one of three kinds:
+ *   - `block`  — the hook is expected to block the action.
+ *   - `allow`  — the hook is expected to allow the action.
+ *   - `stderr` — the hook is expected to emit stderr matching `pattern`.
+ */
+export type ExpectedOutcome = {
+    kind: "block";
+} | {
+    kind: "allow";
+} | {
+    kind: "stderr";
+    pattern: string;
+};
+/**
+ * Marks a case as pinning a known, unfixed defect. A failing case carrying this
+ * reports KNOWN-DEFECT instead of FAIL; an unexpectedly passing one reports WARN
+ * (the marker is stale). The `reason` is required so a defect is never pinned
+ * silently.
+ */
+export interface ExpectedFailure {
+    /** Required, non-empty human reason the defect is tracked and unfixed. */
+    reason: string;
+}
+/** One named case within a fixture. */
+export interface FixtureCase {
+    /** Case name, unique within the fixture (used in result messages). */
+    name: string;
+    /** Lifecycle event to replay the case under, e.g. `PreToolUse`. */
+    event: string;
+    /** Tool name the case exercises, e.g. `Edit`, `Bash`, `Read`. */
+    tool: string;
+    /** The tool input payload handed to the hook. Opaque to the schema. */
+    input: unknown;
+    /** The outcome the hook is expected to produce. */
+    expect: ExpectedOutcome;
+    /** Present only when the case pins a known, unfixed defect. */
+    expectedFailure?: ExpectedFailure;
+}
+/** A fully-validated fixture for a single hook id. */
+export interface HookFixture {
+    /** The hook id this fixture guards, e.g. `block-core-writes`. */
+    hookId: string;
+    /** The schema version, guaranteed to be a supported one. */
+    schemaVersion: FixtureSchemaVersion;
+    /** The named cases, in document order. May be empty. */
+    cases: FixtureCase[];
+}
+/**
+ * The result of validating one fixture document. A closed union so every caller
+ * handles all three outcomes; only `ok` yields a usable {@link HookFixture}.
+ */
+export type ParsedFixture = {
+    status: "ok";
+    fixture: HookFixture;
+} | {
+    /** The declared version is not one this CLI understands. */
+    status: "unsupported-version";
+    /** The hook id (from the doc or the filename default), best-effort. */
+    hookId: string | null;
+    /** The version the fixture declared, verbatim, for the message. */
+    declaredVersion: unknown;
+    /** The versions this CLI does understand. */
+    supportedVersions: readonly number[];
+} | {
+    /** The document is malformed in a way unrelated to the version. */
+    status: "invalid";
+    /** The hook id when one could be identified, else null. */
+    hookId: string | null;
+    /** Why the document was rejected. */
+    message: string;
+};
+/** Options for {@link parseFixture}. */
+export interface ParseFixtureOptions {
+    /**
+     * The hook id to use when the document omits a `hookId` key — normally the
+     * fixture filename stem (`core/hook-tests/block-core-writes.yaml` ->
+     * `block-core-writes`). A `hookId` in the document takes precedence.
+     */
+    defaultHookId?: string;
+}
+/**
+ * Whether an already-parsed YAML document looks like a fixture at all. A file in
+ * `core/hook-tests/` that carries none of the fixture keys (for example
+ * `allowed-divergence.yaml`) is not a fixture and is skipped silently rather
+ * than reported as malformed.
+ */
+export declare function looksLikeFixture(raw: unknown): boolean;
+/**
+ * Validate one already-parsed fixture document. Pure: never reads the disk and
+ * never throws. The version is checked *before* the cases, because a future
+ * schema may shape its cases differently — so an unrecognised version short-
+ * circuits to `unsupported-version` without attempting to interpret the body.
+ */
+export declare function parseFixture(raw: unknown, options?: ParseFixtureOptions): ParsedFixture;
+/**
+ * The observed result of running one case. The caller normalises each platform's
+ * block protocol (a non-zero Claude/Codex exit, or a Grok stdout `deny`) into the
+ * single `blocked` boolean, so this module stays platform-agnostic.
+ */
+export interface ObservedOutcome {
+    /** True when the hook blocked the action. */
+    blocked: boolean;
+    /** Captured stderr from the hook run (empty string when none). */
+    stderr: string;
+}
+/**
+ * Whether an observed outcome satisfies a case's expectation. `stderr` patterns
+ * are treated as regular expressions, falling back to a substring test when the
+ * pattern is not valid regex so a fixture author's literal string still works.
+ */
+export declare function outcomeMatches(expected: ExpectedOutcome, observed: ObservedOutcome): boolean;
+/**
+ * Classify a case outcome into a {@link DoctorStatus}, applying the
+ * `expectedFailure` rule:
+ *
+ *   | met | expectedFailure | status       |
+ *   |-----|-----------------|--------------|
+ *   | yes | no              | PASS         |
+ *   | no  | no              | FAIL         |
+ *   | no  | yes             | KNOWN-DEFECT | (the pinned defect is still present)
+ *   | yes | yes             | WARN         | (marker is stale — remove it)
+ *
+ * `met` is whether the observed outcome matched the expectation
+ * ({@link outcomeMatches}). This is the single source of truth for what a case
+ * result means; US-008 executes the case and calls this to label it.
+ */
+export declare function classifyCaseStatus(met: boolean, expectedFailure?: ExpectedFailure): DoctorStatus;
+//# sourceMappingURL=schema.d.ts.map