@indigoai-us/hq-cli 5.98.2 → 5.99.0

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

@@ -0,0 +1,248 @@
+/**
+ * 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.
+ */
+/**
+ * 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 const SUPPORTED_FIXTURE_SCHEMA_VERSIONS = [1];
+/** The schema version new fixtures should be authored against. */
+export const CURRENT_FIXTURE_SCHEMA_VERSION = 1;
+/** Whether `value` is a schema version this build recognises. */
+export function isSupportedSchemaVersion(value) {
+    return (typeof value === "number" &&
+        SUPPORTED_FIXTURE_SCHEMA_VERSIONS.includes(value));
+}
+/**
+ * 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 function looksLikeFixture(raw) {
+    if (!isRecord(raw))
+        return false;
+    return "schemaVersion" in raw || "cases" in raw || "hookId" in raw;
+}
+/**
+ * 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 function parseFixture(raw, options = {}) {
+    if (!isRecord(raw)) {
+        return {
+            status: "invalid",
+            hookId: options.defaultHookId ?? null,
+            message: "fixture is not a mapping",
+        };
+    }
+    const hookId = resolveHookId(raw, options.defaultHookId);
+    if (hookId === null) {
+        return {
+            status: "invalid",
+            hookId: null,
+            message: "fixture is missing a `hookId` and no filename default was given",
+        };
+    }
+    if (!("schemaVersion" in raw)) {
+        return {
+            status: "invalid",
+            hookId,
+            message: "fixture is missing the required `schemaVersion` field",
+        };
+    }
+    const declaredVersion = raw.schemaVersion;
+    if (!isSupportedSchemaVersion(declaredVersion)) {
+        return {
+            status: "unsupported-version",
+            hookId,
+            declaredVersion,
+            supportedVersions: SUPPORTED_FIXTURE_SCHEMA_VERSIONS,
+        };
+    }
+    if (!("cases" in raw) || !Array.isArray(raw.cases)) {
+        return {
+            status: "invalid",
+            hookId,
+            message: "fixture `cases` must be a list",
+        };
+    }
+    const cases = [];
+    const seenNames = new Set();
+    for (let i = 0; i < raw.cases.length; i++) {
+        const parsed = parseCase(raw.cases[i], i);
+        if (typeof parsed === "string") {
+            return { status: "invalid", hookId, message: parsed };
+        }
+        if (seenNames.has(parsed.name)) {
+            return {
+                status: "invalid",
+                hookId,
+                message: `duplicate case name "${parsed.name}"`,
+            };
+        }
+        seenNames.add(parsed.name);
+        cases.push(parsed);
+    }
+    return {
+        status: "ok",
+        fixture: { hookId, schemaVersion: declaredVersion, cases },
+    };
+}
+/** Validate one case object; returns the case or an error message string. */
+function parseCase(raw, index) {
+    const where = `case #${index + 1}`;
+    if (!isRecord(raw))
+        return `${where} is not a mapping`;
+    const name = raw.name;
+    if (typeof name !== "string" || name.trim() === "") {
+        return `${where} is missing a non-empty \`name\``;
+    }
+    const label = `case "${name}"`;
+    const event = raw.event;
+    if (typeof event !== "string" || event.trim() === "") {
+        return `${label} is missing a non-empty \`event\``;
+    }
+    const tool = raw.tool;
+    if (typeof tool !== "string" || tool.trim() === "") {
+        return `${label} is missing a non-empty \`tool\``;
+    }
+    if (!("input" in raw)) {
+        return `${label} is missing a tool \`input\` payload`;
+    }
+    if (!("expect" in raw)) {
+        return `${label} is missing an \`expect\` outcome`;
+    }
+    const expect = parseExpectedOutcome(raw.expect);
+    if (typeof expect === "string")
+        return `${label}: ${expect}`;
+    const expectedFailure = parseExpectedFailure(raw.expectedFailure);
+    if (typeof expectedFailure === "string")
+        return `${label}: ${expectedFailure}`;
+    const parsedCase = {
+        name,
+        event,
+        tool,
+        input: raw.input,
+        expect,
+    };
+    if (expectedFailure)
+        parsedCase.expectedFailure = expectedFailure;
+    return parsedCase;
+}
+/** Parse the `expect` field into an {@link ExpectedOutcome} or an error string. */
+function parseExpectedOutcome(raw) {
+    if (raw === "block")
+        return { kind: "block" };
+    if (raw === "allow")
+        return { kind: "allow" };
+    if (isRecord(raw) && "stderr" in raw) {
+        const pattern = raw.stderr;
+        if (typeof pattern !== "string" || pattern === "") {
+            return "`expect.stderr` must be a non-empty pattern string";
+        }
+        return { kind: "stderr", pattern };
+    }
+    return "`expect` must be `block`, `allow`, or `{ stderr: <pattern> }`";
+}
+/**
+ * Parse the optional `expectedFailure` field. Returns undefined when absent, the
+ * validated marker when present and well-formed, or an error string. The
+ * `reason` is mandatory — a defect must never be pinned without one.
+ */
+function parseExpectedFailure(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw))
+        return "`expectedFailure` must be a mapping with a `reason`";
+    const reason = raw.reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+        return "`expectedFailure` requires a non-empty `reason`";
+    }
+    return { reason };
+}
+/** The hook id from the document, falling back to the filename default. */
+function resolveHookId(raw, defaultHookId) {
+    const declared = raw.hookId;
+    if (typeof declared === "string" && declared.trim() !== "")
+        return declared;
+    if (defaultHookId && defaultHookId.trim() !== "")
+        return defaultHookId;
+    return null;
+}
+/**
+ * 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 function outcomeMatches(expected, observed) {
+    switch (expected.kind) {
+        case "block":
+            return observed.blocked;
+        case "allow":
+            return !observed.blocked;
+        case "stderr":
+            return stderrMatches(expected.pattern, observed.stderr);
+    }
+}
+function stderrMatches(pattern, stderr) {
+    try {
+        return new RegExp(pattern).test(stderr);
+    }
+    catch {
+        return stderr.includes(pattern);
+    }
+}
+/**
+ * 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 function classifyCaseStatus(met, expectedFailure) {
+    if (expectedFailure)
+        return met ? "WARN" : "KNOWN-DEFECT";
+    return met ? "PASS" : "FAIL";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=schema.js.map

package/dist/lib/doctor/hook-gate-profiles.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Parse the three INDEPENDENT allowlists inside `.claude/hooks/hook-gate.sh`.
+ *
+ * `hook-gate.sh` defines three separate profile functions —
+ * `is_in_minimal_profile`, `is_in_standard_profile`, `is_in_strict_profile` —
+ * each a plain `case "$1" in …` allowlist. They are NOT supersets of one
+ * another: a hook id added to only one list silently no-ops under any other
+ * profile (the gate reads stdin, discards it, and returns pass-through `exit 0`
+ * — the hook never runs and there is no error). The default runtime profile is
+ * `standard`.
+ *
+ * A documented incident (policy `hq-hook-gate-three-profile-lists`) is the whole
+ * reason this parser exists: `block-hq-root-git-mutation.sh` was added only to
+ * `is_in_minimal_profile`, passed a 17-case direct-invocation test matrix, and
+ * still no-opped under the default `standard` profile. This module lets the
+ * doctor mechanically verify that every gated hook id is a member of ALL THREE
+ * profiles and name the specific missing ones when it is not.
+ *
+ * The parser is deliberately tolerant of formatting: it locates each profile
+ * function body, walks its `case` clauses, and collects the labels of every
+ * clause that leads to `return 0`. It never executes the shell.
+ */
+/** The three `hook-gate.sh` allowlist profiles. */
+export type GateProfile = "minimal" | "standard" | "strict";
+/** Canonical ordering of the gate profiles. */
+export declare const GATE_PROFILES: readonly GateProfile[];
+/** The hook ids allowlisted by each profile. */
+export interface HookGateProfiles {
+    minimal: Set<string>;
+    standard: Set<string>;
+    strict: Set<string>;
+}
+/** Which profiles list a given hook id, and which are missing it. */
+export interface GateMembership {
+    /** Profiles whose allowlist contains the id, in canonical order. */
+    present: GateProfile[];
+    /** Profiles whose allowlist is missing the id, in canonical order. */
+    missing: GateProfile[];
+}
+/**
+ * Parse `hook-gate.sh` source into the three profile allowlists.
+ *
+ * For each profile, the `is_in_<profile>_profile()` function is located and its
+ * body scanned: every `case` clause that leads to `return 0` contributes its
+ * pipe-separated labels (the `*)` fall-through leads to `return 1` and is
+ * ignored). A profile whose function is absent, or whose allowlist is empty,
+ * yields an empty set rather than throwing.
+ */
+export declare function parseHookGateProfiles(source: string): HookGateProfiles;
+/**
+ * Determine which of the three profiles list `hookId`. Comparison is exact —
+ * profile allowlists key on the hook id, not the script filename.
+ */
+export declare function gateMembership(hookId: string, profiles: HookGateProfiles): GateMembership;
+//# sourceMappingURL=hook-gate-profiles.d.ts.map

package/dist/lib/doctor/hook-gate-profiles.js

@@ -0,0 +1,107 @@
+/**
+ * Parse the three INDEPENDENT allowlists inside `.claude/hooks/hook-gate.sh`.
+ *
+ * `hook-gate.sh` defines three separate profile functions —
+ * `is_in_minimal_profile`, `is_in_standard_profile`, `is_in_strict_profile` —
+ * each a plain `case "$1" in …` allowlist. They are NOT supersets of one
+ * another: a hook id added to only one list silently no-ops under any other
+ * profile (the gate reads stdin, discards it, and returns pass-through `exit 0`
+ * — the hook never runs and there is no error). The default runtime profile is
+ * `standard`.
+ *
+ * A documented incident (policy `hq-hook-gate-three-profile-lists`) is the whole
+ * reason this parser exists: `block-hq-root-git-mutation.sh` was added only to
+ * `is_in_minimal_profile`, passed a 17-case direct-invocation test matrix, and
+ * still no-opped under the default `standard` profile. This module lets the
+ * doctor mechanically verify that every gated hook id is a member of ALL THREE
+ * profiles and name the specific missing ones when it is not.
+ *
+ * The parser is deliberately tolerant of formatting: it locates each profile
+ * function body, walks its `case` clauses, and collects the labels of every
+ * clause that leads to `return 0`. It never executes the shell.
+ */
+/** Canonical ordering of the gate profiles. */
+export const GATE_PROFILES = [
+    "minimal",
+    "standard",
+    "strict",
+];
+/**
+ * Parse `hook-gate.sh` source into the three profile allowlists.
+ *
+ * For each profile, the `is_in_<profile>_profile()` function is located and its
+ * body scanned: every `case` clause that leads to `return 0` contributes its
+ * pipe-separated labels (the `*)` fall-through leads to `return 1` and is
+ * ignored). A profile whose function is absent, or whose allowlist is empty,
+ * yields an empty set rather than throwing.
+ */
+export function parseHookGateProfiles(source) {
+    return {
+        minimal: extractProfileIds(source, "minimal"),
+        standard: extractProfileIds(source, "standard"),
+        strict: extractProfileIds(source, "strict"),
+    };
+}
+/**
+ * Determine which of the three profiles list `hookId`. Comparison is exact —
+ * profile allowlists key on the hook id, not the script filename.
+ */
+export function gateMembership(hookId, profiles) {
+    const present = [];
+    const missing = [];
+    for (const profile of GATE_PROFILES) {
+        if (profiles[profile].has(hookId))
+            present.push(profile);
+        else
+            missing.push(profile);
+    }
+    return { present, missing };
+}
+/**
+ * Extract the allowlisted ids of one profile function from `hook-gate.sh`
+ * source. Returns an empty set when the function is absent or its allowlist is
+ * empty (an all-`*)` case body).
+ */
+function extractProfileIds(source, profile) {
+    const ids = new Set();
+    const body = profileFunctionBody(source, profile);
+    if (body === null)
+        return ids;
+    // A `case` body is a series of `<labels>) <commands> ;;` clauses. Splitting on
+    // `;;` isolates each clause; the ones whose commands include `return 0` are the
+    // allowlist entries. The label portion is everything before that clause's first
+    // `)`; the first clause additionally carries the `case "$1" in` preamble, which
+    // is stripped at the `in` keyword (no hook id is the bare word `in`).
+    for (const clause of body.split(";;")) {
+        if (!/\breturn\s+0\b/.test(clause))
+            continue;
+        const closeParen = clause.indexOf(")");
+        if (closeParen < 0)
+            continue;
+        let labels = clause.slice(0, closeParen);
+        const inKeyword = /\bin\b/.exec(labels);
+        if (inKeyword)
+            labels = labels.slice(inKeyword.index + inKeyword[0].length);
+        for (const token of labels.split("|")) {
+            const id = token.trim();
+            if (id.length > 0 && id !== "*" && !/\s/.test(id))
+                ids.add(id);
+        }
+    }
+    return ids;
+}
+/**
+ * Return the body (between the opening `{` and its matching line-leading `}`) of
+ * `is_in_<profile>_profile()`, or null when the function is not defined. The
+ * body contains a `case … esac`, never a nested `}`, so the first line-leading
+ * `}` after the opening brace is the function's own close.
+ */
+function profileFunctionBody(source, profile) {
+    const open = new RegExp(`is_in_${profile}_profile\\s*\\(\\)\\s*\\{`).exec(source);
+    if (!open)
+        return null;
+    const rest = source.slice(open.index + open[0].length);
+    const close = rest.search(/\n\s*\}/);
+    return close >= 0 ? rest.slice(0, close) : rest;
+}
+//# sourceMappingURL=hook-gate-profiles.js.map

package/dist/lib/doctor/json-output.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The `--json` output document for `hq doctor`, and its versioned contract.
+ *
+ * The JSON surface is what US-014's advisory CI job and US-012's harness-audit
+ * integration consume, so it has to be stable from the first release. Two
+ * guarantees make that possible:
+ *
+ *   - {@link DOCTOR_JSON_SCHEMA_VERSION} is a single explicit integer, pinned by
+ *     a snapshot test. A breaking change to the shape forces the version to
+ *     move, and moving it forces the snapshot to be updated in the same diff —
+ *     so the contract cannot change silently.
+ *
+ *   - The document is a pure function of the resolved root, the detected
+ *     platform, and the family results. It performs no I/O and no formatting
+ *     beyond serialisation, so it renders identically in a TTY, a pipe, or CI.
+ *
+ * `target` and `remediation` are emitted only when present, matching the
+ * per-item result shape where both are optional.
+ */
+import { type DoctorPlatform, type StatusCounts } from "./report.js";
+import type { DoctorStatus, FamilyRun } from "./types.js";
+/**
+ * The `--json` schema version. Bump on any breaking change to the document
+ * shape; the snapshot test in report.test.ts fails until the bump is
+ * acknowledged, which is the whole point.
+ *
+ * v2 (US-011): each finding may carry a structured `fix` object (auto-fixable?,
+ * exact action, equivalent command). It appears regardless of whether `--fix`
+ * was passed, so a consumer can see what `--fix` would do without invoking it.
+ */
+export declare const DOCTOR_JSON_SCHEMA_VERSION = 2;
+/**
+ * The structured remediation of a finding, as it appears in the JSON document
+ * (US-011 AC1). Present on any actionable finding (FAIL/WARN); a `command` is ""
+ * when there is no single equivalent shell command.
+ */
+export interface DoctorJsonFix {
+    /** Whether `hq doctor --fix` is allowed to repair this finding mechanically. */
+    autoFixable: boolean;
+    /** Plain-language description of the exact repair. */
+    action: string;
+    /** The equivalent shell command, or "" when none exists. */
+    command: string;
+}
+/** One result as it appears in the JSON document. */
+export interface DoctorJsonResult {
+    /** Status from the fixed vocabulary. */
+    status: DoctorStatus;
+    /** The family that produced this result, e.g. `hooks`. */
+    family: string;
+    /** Stable machine id for the check, e.g. `hooks.settings-present`. */
+    checkId: string;
+    /** What was inspected. Present only when the result carries one. */
+    target?: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Remediation hint. Present only when the result carries one. */
+    remediation?: string;
+    /** Structured remediation (US-011). Present on actionable findings only. */
+    fix?: DoctorJsonFix;
+}
+/** The complete `--json` document. */
+export interface DoctorJsonDocument {
+    /** Output-contract version. See {@link DOCTOR_JSON_SCHEMA_VERSION}. */
+    schemaVersion: number;
+    /** The detected agent platform and its evidence (placeholder until US-003). */
+    platform: DoctorPlatform;
+    /** The resolved HQ tree root. */
+    hqRoot: string;
+    /** Per-status tallies across all results. */
+    summary: StatusCounts;
+    /** The exit code this run produced: 0, or 1 when any FAIL/UNKNOWN is present. */
+    exitCode: number;
+    /** The full, flattened result list in family/registration order. */
+    results: DoctorJsonResult[];
+}
+/** Input to {@link buildDoctorJson}. */
+export interface BuildDoctorJsonInput {
+    /** The resolved HQ root. */
+    hqRoot: string;
+    /** Grouped per-family results. */
+    families: FamilyRun[];
+    /** Detected platform. Defaults to {@link UNKNOWN_PLATFORM}. */
+    platform?: DoctorPlatform;
+}
+/** Assemble the machine-readable document from a completed run. */
+export declare function buildDoctorJson(input: BuildDoctorJsonInput): DoctorJsonDocument;
+/** Serialise the document as pretty-printed JSON with a trailing newline. */
+export declare function renderJson(document: DoctorJsonDocument): string;
+//# sourceMappingURL=json-output.d.ts.map

package/dist/lib/doctor/json-output.js

@@ -0,0 +1,76 @@
+/**
+ * The `--json` output document for `hq doctor`, and its versioned contract.
+ *
+ * The JSON surface is what US-014's advisory CI job and US-012's harness-audit
+ * integration consume, so it has to be stable from the first release. Two
+ * guarantees make that possible:
+ *
+ *   - {@link DOCTOR_JSON_SCHEMA_VERSION} is a single explicit integer, pinned by
+ *     a snapshot test. A breaking change to the shape forces the version to
+ *     move, and moving it forces the snapshot to be updated in the same diff —
+ *     so the contract cannot change silently.
+ *
+ *   - The document is a pure function of the resolved root, the detected
+ *     platform, and the family results. It performs no I/O and no formatting
+ *     beyond serialisation, so it renders identically in a TTY, a pipe, or CI.
+ *
+ * `target` and `remediation` are emitted only when present, matching the
+ * per-item result shape where both are optional.
+ */
+import { computeExitCode, summarize, UNKNOWN_PLATFORM, } from "./report.js";
+import { deriveRemediation } from "./fix/remediation.js";
+/**
+ * The `--json` schema version. Bump on any breaking change to the document
+ * shape; the snapshot test in report.test.ts fails until the bump is
+ * acknowledged, which is the whole point.
+ *
+ * v2 (US-011): each finding may carry a structured `fix` object (auto-fixable?,
+ * exact action, equivalent command). It appears regardless of whether `--fix`
+ * was passed, so a consumer can see what `--fix` would do without invoking it.
+ */
+export const DOCTOR_JSON_SCHEMA_VERSION = 2;
+/** Assemble the machine-readable document from a completed run. */
+export function buildDoctorJson(input) {
+    const results = [];
+    for (const run of input.families) {
+        for (const result of run.results) {
+            results.push(toJsonResult(run.family.id, result));
+        }
+    }
+    return {
+        schemaVersion: DOCTOR_JSON_SCHEMA_VERSION,
+        platform: input.platform ?? UNKNOWN_PLATFORM,
+        hqRoot: input.hqRoot,
+        summary: summarize(input.families),
+        exitCode: computeExitCode(input.families),
+        results,
+    };
+}
+/** Convert one {@link CheckResult} into its JSON form, omitting empty optionals. */
+function toJsonResult(familyId, result) {
+    const remediation = deriveRemediation(result);
+    return {
+        status: result.status,
+        family: familyId,
+        checkId: result.checkId,
+        ...(result.target !== undefined ? { target: result.target } : {}),
+        message: result.message,
+        ...(result.remediation !== undefined
+            ? { remediation: result.remediation }
+            : {}),
+        ...(remediation
+            ? {
+                fix: {
+                    autoFixable: remediation.autoFixable,
+                    action: remediation.action,
+                    command: remediation.command,
+                },
+            }
+            : {}),
+    };
+}
+/** Serialise the document as pretty-printed JSON with a trailing newline. */
+export function renderJson(document) {
+    return JSON.stringify(document, null, 2) + "\n";
+}
+//# sourceMappingURL=json-output.js.map