@gaunt-sloth/core 2.0.0-alpha.35 → 2.0.0-alpha.37

package/dist/config/configDiscovery.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @packageDocumentation
+ * The catchable error a config **load** raises when the configuration itself cannot be used. The
+ * cases, all one class on purpose:
+ *
+ * - an explicitly-named identity profile (or an `extends` base) that resolves to no config;
+ * - a `--config` path that does not exist;
+ * - a config layer present but malformed — a removed pre-2.0 shape, a bad approvals rule grammar,
+ *   a schema mismatch, an unresolvable `approvals.rater`;
+ * - a config that read fine but names no usable model — no `llm` block, no `llm.type`, an
+ *   `llm.type` with no provider module, or a provider module that cannot build from a JSON spec;
+ * - a provider instance that could not be constructed for a reason other than a missing API key
+ *   (that one is {@link MissingProviderKeyError}, which carries the key details);
+ * - no configuration file anywhere at all.
+ *
+ * Deliberately dependency-free (no imports beyond types) so the config barrel, the loader and
+ * downstream consumers can all reach it without an import cycle — the same shape
+ * `providerKeys.ts` uses for {@link MissingProviderKeyError}.
+ *
+ * **Why this is an error object and not a process exit.** Loading configuration is a *library*
+ * operation, and a library that terminates the process denies every caller the chance to classify
+ * the failure. `gth eval` in particular distinguishes a **harness** error (exit 2 — the suite could
+ * not be evaluated) from a **product** failure (exit 1 — the SUT ran and failed); a `process.exit(1)`
+ * inside config discovery collapses that contract, reporting a typo in `--judge` exactly as it
+ * reports a genuine regression. Callers that legitimately want to terminate — the CLI entry points —
+ * catch it at their top level, where the exit code is chosen deliberately.
+ *
+ * One class covers every case above on purpose: no caller needs to tell them apart (all of them mean
+ * "this configuration cannot be used"), and the fields carry whichever detail applies. Sub-classing
+ * per case would only push the callers back to the marker-list problem this class exists to end —
+ * a consumer that wants the underlying failure reads `cause`.
+ */
+/** What a config load knows about the configuration it could not use. */
+export interface ConfigDiscoveryDetails {
+    /**
+     * The explicitly-requested identity profile that did not resolve, when that is the failure.
+     * Undefined for a malformed-config failure, which is about a file rather than a profile name.
+     */
+    identityProfile?: string | undefined;
+    /**
+     * Human-readable source of the offending config layer (e.g. `.gsloth.config.json`,
+     * `.gsloth.config.json (global)`, `<name> (extends base)`), when a layer was read and rejected.
+     */
+    sourceLabel?: string | undefined;
+}
+/**
+ * A configuration could not be used: a named identity profile has no config, or a config layer is
+ * malformed.
+ *
+ * Thrown (never exited on) by the config loader, so `gth eval`, `gth batch`, the AG-UI/ACP servers
+ * and any embedding consumer can classify the failure and choose their own exit code.
+ */
+export declare class ConfigDiscoveryError extends Error implements ConfigDiscoveryDetails {
+    /** Duck-typed marker so {@link isConfigDiscoveryError} works across duplicated module copies. */
+    readonly gthConfigDiscoveryError: true;
+    readonly identityProfile: string | undefined;
+    readonly sourceLabel: string | undefined;
+    constructor(message: string, details?: ConfigDiscoveryDetails, options?: {
+        cause?: unknown;
+    });
+    /**
+     * Serialize the machine-readable half. `JSON.stringify(error)` would otherwise drop `message`
+     * (an Error's `message` is a non-enumerable own property), which is exactly the field a report
+     * consumer shows a human next to the profile or the file that failed.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+    } & ConfigDiscoveryDetails;
+}
+/**
+ * True when `value` is a {@link ConfigDiscoveryError}.
+ *
+ * Duck-typed on the marker property rather than `instanceof` on purpose: a consumer that ends up
+ * with two copies of `@gaunt-sloth/core` on disk (a `file:` dep, a hoisting split) would fail an
+ * `instanceof` check against a genuinely-correct error and mis-handle a config failure as an
+ * unexpected crash — exactly the distinction this error exists to make.
+ */
+export declare function isConfigDiscoveryError(value: unknown): value is ConfigDiscoveryError;

package/dist/config/configDiscovery.js

@@ -0,0 +1,80 @@
+/**
+ * @packageDocumentation
+ * The catchable error a config **load** raises when the configuration itself cannot be used. The
+ * cases, all one class on purpose:
+ *
+ * - an explicitly-named identity profile (or an `extends` base) that resolves to no config;
+ * - a `--config` path that does not exist;
+ * - a config layer present but malformed — a removed pre-2.0 shape, a bad approvals rule grammar,
+ *   a schema mismatch, an unresolvable `approvals.rater`;
+ * - a config that read fine but names no usable model — no `llm` block, no `llm.type`, an
+ *   `llm.type` with no provider module, or a provider module that cannot build from a JSON spec;
+ * - a provider instance that could not be constructed for a reason other than a missing API key
+ *   (that one is {@link MissingProviderKeyError}, which carries the key details);
+ * - no configuration file anywhere at all.
+ *
+ * Deliberately dependency-free (no imports beyond types) so the config barrel, the loader and
+ * downstream consumers can all reach it without an import cycle — the same shape
+ * `providerKeys.ts` uses for {@link MissingProviderKeyError}.
+ *
+ * **Why this is an error object and not a process exit.** Loading configuration is a *library*
+ * operation, and a library that terminates the process denies every caller the chance to classify
+ * the failure. `gth eval` in particular distinguishes a **harness** error (exit 2 — the suite could
+ * not be evaluated) from a **product** failure (exit 1 — the SUT ran and failed); a `process.exit(1)`
+ * inside config discovery collapses that contract, reporting a typo in `--judge` exactly as it
+ * reports a genuine regression. Callers that legitimately want to terminate — the CLI entry points —
+ * catch it at their top level, where the exit code is chosen deliberately.
+ *
+ * One class covers every case above on purpose: no caller needs to tell them apart (all of them mean
+ * "this configuration cannot be used"), and the fields carry whichever detail applies. Sub-classing
+ * per case would only push the callers back to the marker-list problem this class exists to end —
+ * a consumer that wants the underlying failure reads `cause`.
+ */
+/** Marker property carried by every {@link ConfigDiscoveryError}; see {@link isConfigDiscoveryError}. */
+const CONFIG_DISCOVERY_MARKER = 'gthConfigDiscoveryError';
+/**
+ * A configuration could not be used: a named identity profile has no config, or a config layer is
+ * malformed.
+ *
+ * Thrown (never exited on) by the config loader, so `gth eval`, `gth batch`, the AG-UI/ACP servers
+ * and any embedding consumer can classify the failure and choose their own exit code.
+ */
+export class ConfigDiscoveryError extends Error {
+    /** Duck-typed marker so {@link isConfigDiscoveryError} works across duplicated module copies. */
+    gthConfigDiscoveryError = true;
+    identityProfile;
+    sourceLabel;
+    constructor(message, details = {}, options) {
+        super(message, options);
+        this.name = 'ConfigDiscoveryError';
+        this.identityProfile = details.identityProfile;
+        this.sourceLabel = details.sourceLabel;
+    }
+    /**
+     * Serialize the machine-readable half. `JSON.stringify(error)` would otherwise drop `message`
+     * (an Error's `message` is a non-enumerable own property), which is exactly the field a report
+     * consumer shows a human next to the profile or the file that failed.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            identityProfile: this.identityProfile,
+            sourceLabel: this.sourceLabel,
+        };
+    }
+}
+/**
+ * True when `value` is a {@link ConfigDiscoveryError}.
+ *
+ * Duck-typed on the marker property rather than `instanceof` on purpose: a consumer that ends up
+ * with two copies of `@gaunt-sloth/core` on disk (a `file:` dep, a hoisting split) would fail an
+ * `instanceof` check against a genuinely-correct error and mis-handle a config failure as an
+ * unexpected crash — exactly the distinction this error exists to make.
+ */
+export function isConfigDiscoveryError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[CONFIG_DISCOVERY_MARKER] === true);
+}
+//# sourceMappingURL=configDiscovery.js.map

package/dist/config/configDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configDiscovery.js","sourceRoot":"","sources":["../../src/config/configDiscovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yGAAyG;AACzG,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAgB1D;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,iGAAiG;IACxF,uBAAuB,GAAG,IAAa,CAAC;IACxC,eAAe,CAAqB;IACpC,WAAW,CAAqB;IAEzC,YACE,OAAe,EACf,OAAO,GAA2B,EAAE,EACpC,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,uBAAuB,CAAC,KAAK,IAAI,CACrE,CAAC;AACJ,CAAC"}

package/dist/config/loader.d.ts

@@ -38,11 +38,12 @@ export declare function findProjectConfigPath(commandLineConfigOverrides: Comman
  * config happens to be present / a global config exists," a distinction the loader's fall-through
  * deliberately blurs.
  *
- * PURE PREDICATE — never throws, never calls `exit` (contrast the loader's interactive-CLI
- * `exit(1)` safety net in {@link initConfig}). So batch/eval code (e.g. `gth eval --judge <profile>`
- * and BATCH-12's identity matrix) can pre-check an explicitly-requested profile and raise its OWN
- * catchable error / graceful exit code instead of dying on an uncatchable `process.exit`. A
- * blank/whitespace-only name counts as "no profile" → `undefined`.
+ * PURE PREDICATE — never throws, never calls `exit`, so it can be asked the question without
+ * committing to an outcome. {@link initConfig} uses it to enforce that an explicitly-named profile
+ * really exists (raising a catchable {@link ConfigDiscoveryError} when it does not), and callers
+ * that want to CLASSIFY rather than fail — BATCH-12's identity matrix checks every declared identity
+ * up front so one message can name them all — ask it directly. A blank/whitespace-only name counts
+ * as "no profile" → `undefined`.
  *
  * @param identityProfile The explicitly-requested identity profile name.
  * @returns The resolved profile config path, or `undefined` when the profile has no config.