@thymian/plugin-sampler 0.3.0-canary.20261007-e6cb8dc → 0.3.0-canary.20261007-cdbe1d3

package/dist/hooks/hook-utils.d.ts

@@ -1,20 +1,79 @@
 export type ParameterType = string | number | null | boolean;
 export type EndpointRequest = {
-    body: unknown;
+    body?: unknown;
     headers?: Record<PropertyKey, string | string[] | undefined>;
     query?: Record<PropertyKey, ParameterType>;
     cookies?: Record<PropertyKey, ParameterType>;
     path?: Record<PropertyKey, ParameterType | ParameterType[] | Record<string, ParameterType | ParameterType[]>>;
 };
+/**
+ * One declared response, as a cross-endpoint caller sees it.
+ *
+ * The same four fields the generated `TransactionResponse<T>` carries, so the
+ * internal signature and the one an author's editor shows are one contract.
+ * `mediaType` is the essence the response actually arrived with.
+ */
+export type EndpointResponse = {
+    body: unknown;
+    mediaType: string;
+    statusCode: number;
+    headers: Record<string, unknown>;
+};
 export type Endpoints = Record<string, {
     req: EndpointRequest;
-    res: {
-        body: unknown;
-        statusCode: number;
-        headers: Record<string, unknown>;
-    };
+    res: EndpointResponse;
+    /**
+     * Every response the Transaction's operation declares. Generated as a
+     * discriminated union; here it is the untyped stand-in, because the
+     * internal surface is only ever instantiated with `Record<string, never>`.
+     */
+    responses: EndpointResponse;
 }>;
-export interface HookUtils<E extends Endpoints = Record<string, never>> {
+/** Options for a cross-endpoint request. */
+export type RequestOptions = {
+    /**
+     * Run the target's own `beforeEach` → `authorize` → `afterEach` pipeline, so
+     * a seeding call behaves like the real run. Default `true`; `false` is the
+     * raw-seeding escape, and the way out of a cycle.
+     */
+    runHooks?: boolean;
+    /**
+     * Force authorization on or off for this call, overriding the target's own
+     * `authorize` flag. Authorization still needs a registered authorize hook.
+     */
+    authorize?: boolean;
+};
+/**
+ * The typed setters.
+ *
+ * They coexist with direct mutation and do exactly the same thing: a setter is
+ * a place for the compiler to know the name and the value type, not a different
+ * mechanism. Both write into the same request object.
+ *
+ * In an `afterEach` hook the request has already been sent, so a setter there
+ * changes nothing observable — the surface stays uniform rather than throwing.
+ */
+export interface HookSetters {
+    setHeader(name: string, value: string | string[] | undefined): void;
+    setQuery(name: string, value: unknown): void;
+    setPathParam(name: string, value: unknown): void;
+    setCookie(name: string, value: unknown): void;
+    setBody(body: unknown): void;
+    setAuthorize(authorize: boolean): void;
+}
+/**
+ * Reads a file next to the hook that asks for it.
+ *
+ * A relative path resolves against the **hook file's own directory**, not the
+ * working directory: a fixture lives beside the hook that uses it, and a hook
+ * must keep working when the run starts somewhere else.
+ */
+export interface HookFileHelpers {
+    readFile(path: string): Buffer;
+    readText(path: string, encoding?: BufferEncoding): string;
+    readJson<T = unknown>(path: string): T;
+}
+export interface HookUtils<E extends Endpoints = Record<string, never>> extends HookSetters, HookFileHelpers {
     skip(message: string): never;
     fail(message: string): never;
     info(message: string): void;
@@ -26,11 +85,20 @@ export interface HookUtils<E extends Endpoints = Record<string, never>> {
         actual?: unknown;
     }): void;
     timeout(message: string, durationMs: number): void;
-    request<R extends keyof E>(req: R, args: E[R]['req'], options?: {
-        runHooks?: boolean;
-        authorize?: boolean;
-        forStatusCode?: number;
-    }): Promise<E[R]['res']>;
+    /**
+     * Call another Transaction, addressed by its Selector.
+     *
+     * Keyed by Selector and resolved through the transaction catalog, so the keys
+     * the committed types carry and the strings resolved at run time are the same
+     * strings by construction. There is no `forStatusCode`: the Selector already
+     * carries the status you asked for.
+     *
+     * `args` **overlays** the generated request — parameter groups merge per key,
+     * the body deep-merges — and the answer is every response the operation
+     * declares, because initiating a Transaction is not the same as getting one.
+     * A status the description never declares throws `UndeclaredResponseError`.
+     */
+    request<R extends keyof E>(selector: R, args?: E[R]['req'], options?: RequestOptions): Promise<E[R]['responses']>;
     randomString(length?: number): string;
 }
 //# sourceMappingURL=hook-utils.d.ts.map

package/dist/hooks/hook-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-utils.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-utils.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CACX,WAAW,EACT,aAAa,GACb,aAAa,EAAE,GACf,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC,CAClD,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAC5B,MAAM,EACN;IACE,GAAG,EAAE,eAAe,CAAC;IACrB,GAAG,EAAE;QACH,IAAI,EAAE,OAAO,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;CACH,CACF,CAAC;AAEF,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IACpE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAE7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAE7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9C,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5D,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACrE,IAAI,CAAC;IAER,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnD,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,EACvB,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EACjB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAExB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC"}
+{"version":3,"file":"hook-utils.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-utils.ts"],"names":[],"mappings":"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"}

package/dist/hooks/invoke-hook.d.ts

@@ -0,0 +1,71 @@
+import { type HttpTestCaseResult, type Logger, ThymianBaseError } from '@thymian/core';
+import type { HookKind } from './hook-registration.js';
+import type { CollectedRegistration } from './load-user-hooks.js';
+/**
+ * Calls one user callback with the arguments its kind is given.
+ *
+ * The cast lives here and nowhere else: a registration's `callback` is stored as
+ * an opaque function because each kind's precise signature is the runner's
+ * contract and the generated `.d.ts` is what types it for the author.
+ *
+ * The return value is discarded on purpose. A hook's contract is to mutate in
+ * place and return nothing, and honouring a return corrupts the value for the
+ * most ordinary shorthand there is: `(r) => (r.headers.x = 'y')` evaluates to
+ * `'y'`.
+ */
+export declare function invokeHook(entry: CollectedRegistration, args: readonly unknown[]): Promise<unknown>;
+/**
+ * Where a hook's `utils` results go when there is no test case to attach them
+ * to — a run-scoped hook, or a `defineSample` that runs before any request
+ * exists. Logging them beats dropping them silently.
+ */
+export declare function reportHookResults(logger: Logger, results: readonly HttpTestCaseResult[]): void;
+/**
+ * Names the hook a sampler diagnostic came out of, without burying the
+ * diagnostic.
+ *
+ * A cycle error's value is the chain it prints and a setter-misuse error's is
+ * the sentence explaining the misuse — both live in `suggestions`, so wrapping
+ * the error in a "hook X threw" envelope would throw away the part worth
+ * reading. The location joins the suggestions instead, at the front, where it
+ * answers "which line do I open" before the diagnostic answers "why".
+ */
+export declare function attributeToHook(error: ThymianBaseError, kind: string, entry: CollectedRegistration): ThymianBaseError;
+/** What interpreting a hook's failure decided should happen next. */
+export type HookFailure = {
+    rethrow?: ThymianBaseError;
+    report?: {
+        skip: string;
+    } | {
+        fail: string;
+    };
+};
+/**
+ * The one interpretation every hook kind's failure goes through:
+ * `utils.skip`/`utils.fail` and an unhandled off-spec seed answer become a
+ * verdict for the kinds that have a Transaction to apply it to; a diagnostic
+ * the sampler itself raised keeps its own message and suggestions with the
+ * hook's location added; anything else is a defect in the hook and gets the
+ * envelope that names it.
+ *
+ * Every diagnostic that leaves here carries `severity: 'warn'`, and that is
+ * load-bearing rather than a judgement about how bad it is. An `error`-severity
+ * event closes the whole run through `Thymian.run`'s error subscription, which
+ * is precisely the behaviour the outcome model replaces: one broken hook used
+ * to end the command and hide every transaction after it.
+ */
+export declare function interpretHookFailure(e: unknown, kind: HookKind, entry: CollectedRegistration): HookFailure;
+/**
+ * Runs one hook through the shared attribution pipeline and always throws on
+ * failure — for `defineSample`, `beforeAll` and `afterAll`, which have no
+ * Transaction to report a `skip`/`fail` verdict against. Callable only with a
+ * kind outside {@link TRANSACTION_SCOPED_KINDS}, which is what guarantees
+ * {@link interpretHookFailure} always hands back a `rethrow` here and never a
+ * `report` with nowhere to go.
+ *
+ * The raw return value is handed back rather than discarded: `beforeAll` is
+ * the one kind whose return is not mutate-and-ignore — a returned function is
+ * a cleanup to run at teardown.
+ */
+export declare function invokeOrThrow(kind: Exclude<HookKind, 'beforeEach' | 'afterEach' | 'authorize'>, entry: CollectedRegistration, args: readonly unknown[]): Promise<unknown>;
+//# sourceMappingURL=invoke-hook.d.ts.map

package/dist/hooks/invoke-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/invoke-hook.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,MAAM,EACX,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAOvB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,IAAI,CAoBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,qBAAqB,GAC3B,gBAAgB,CAkBlB;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C,CAAC;AAgBF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,OAAO,EACV,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,qBAAqB,GAC3B,WAAW,CAsCb;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC,EACjE,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAAC,OAAO,CAAC,CAkBlB"}

package/dist/hooks/invoke-hook.js

@@ -0,0 +1,161 @@
+import { ThymianBaseError, } from '@thymian/core';
+import { FailError, SkipError, UndeclaredResponseError, } from './hook-errors.js';
+/**
+ * Calls one user callback with the arguments its kind is given.
+ *
+ * The cast lives here and nowhere else: a registration's `callback` is stored as
+ * an opaque function because each kind's precise signature is the runner's
+ * contract and the generated `.d.ts` is what types it for the author.
+ *
+ * The return value is discarded on purpose. A hook's contract is to mutate in
+ * place and return nothing, and honouring a return corrupts the value for the
+ * most ordinary shorthand there is: `(r) => (r.headers.x = 'y')` evaluates to
+ * `'y'`.
+ */
+export async function invokeHook(entry, args) {
+    const callback = entry.registration.callback;
+    return await callback(...args);
+}
+/**
+ * Where a hook's `utils` results go when there is no test case to attach them
+ * to — a run-scoped hook, or a `defineSample` that runs before any request
+ * exists. Logging them beats dropping them silently.
+ */
+export function reportHookResults(logger, results) {
+    for (const result of results) {
+        if (result.type === 'assertion-failure' || result.type === 'timeout') {
+            logger.error(result.message);
+        }
+        else if (result.type === 'warning' ||
+            // A nested request has no test case of its own, so these are the only
+            // place its failure is ever said out loud. At `info` a seed answered
+            // with a declared-but-different status was invisible at the default
+            // level, while every transaction that depended on it turned up
+            // `skipped` with nothing naming the cause — the reader saw the
+            // consequence and not the reason.
+            result.type === 'invalid-transaction' ||
+            result.type === 'execution-error') {
+            logger.warn(result.message);
+        }
+        else {
+            logger.info(result.message);
+        }
+    }
+}
+/**
+ * Names the hook a sampler diagnostic came out of, without burying the
+ * diagnostic.
+ *
+ * A cycle error's value is the chain it prints and a setter-misuse error's is
+ * the sentence explaining the misuse — both live in `suggestions`, so wrapping
+ * the error in a "hook X threw" envelope would throw away the part worth
+ * reading. The location joins the suggestions instead, at the front, where it
+ * answers "which line do I open" before the diagnostic answers "why".
+ */
+export function attributeToHook(error, kind, entry) {
+    return new ThymianBaseError(error.message, {
+        ...error.options,
+        // After the spread, never before it. An `error` closes the run
+        // (`thymian.ts`), which is the mechanism ADR-0023 §2 names and the sentence
+        // above promises to prevent — and every sampler-raised error that reaches
+        // here defaults to `error` because none of them sets a severity of its own:
+        // `UnknownSelectorError` and `MalformedSelectorError` from `utils.request`,
+        // `RequestCycleError`, a seed's `RequestSerializationError`,
+        // `NoRequestToShapeError`, `NoNestedRequestError`. A typo in a seed's
+        // selector is the most ordinary hook fault there is, and it ended the run.
+        severity: 'warn',
+        suggestions: [
+            `Raised by the ${kind} hook exported as "${entry.exportName}" from "${entry.file}".`,
+            ...(error.options.suggestions ?? []),
+        ],
+        cause: error.cause,
+    });
+}
+/**
+ * The kinds that run against one Transaction, and so have somewhere for a
+ * `utils.skip`/`utils.fail` verdict — or an unhandled off-spec seed answer —
+ * to land. `defineSample` runs before any request exists and `beforeAll`/
+ * `afterAll` run once for the whole run rather than per Transaction, so a
+ * control-flow throw from one of those has no Transaction to apply to and is
+ * treated like any other defect in the hook.
+ */
+const TRANSACTION_SCOPED_KINDS = new Set([
+    'beforeEach',
+    'afterEach',
+    'authorize',
+]);
+/**
+ * The one interpretation every hook kind's failure goes through:
+ * `utils.skip`/`utils.fail` and an unhandled off-spec seed answer become a
+ * verdict for the kinds that have a Transaction to apply it to; a diagnostic
+ * the sampler itself raised keeps its own message and suggestions with the
+ * hook's location added; anything else is a defect in the hook and gets the
+ * envelope that names it.
+ *
+ * Every diagnostic that leaves here carries `severity: 'warn'`, and that is
+ * load-bearing rather than a judgement about how bad it is. An `error`-severity
+ * event closes the whole run through `Thymian.run`'s error subscription, which
+ * is precisely the behaviour the outcome model replaces: one broken hook used
+ * to end the command and hide every transaction after it.
+ */
+export function interpretHookFailure(e, kind, entry) {
+    const controlFlow = TRANSACTION_SCOPED_KINDS.has(kind);
+    if (controlFlow && e instanceof SkipError) {
+        return { report: { skip: e.message } };
+    }
+    if (controlFlow && e instanceof FailError) {
+        return { report: { fail: e.message } };
+    }
+    // An off-spec seed answer that nobody caught. Reacting to it is opt-in, so
+    // letting it escape is a legitimate way to write a hook: the transaction
+    // cannot be executed as described, which is a skip and not a defect, and the
+    // message already names the seed and what it was answered with.
+    if (controlFlow && e instanceof UndeclaredResponseError) {
+        return { report: { skip: e.message } };
+    }
+    if (e instanceof ThymianBaseError) {
+        return { rethrow: attributeToHook(e, kind, entry) };
+    }
+    return {
+        rethrow: new ThymianBaseError(
+        // Deliberately without the Transaction: every surface that prints one
+        // already names it (ADR-0022), and repeating it under a header that says
+        // it is the noise this model removes. What only this sentence knows is
+        // which export in which file to open.
+        `The ${kind} hook exported as "${entry.exportName}" from "${entry.file}" threw.`, {
+            cause: e,
+            name: 'HookError',
+            ref: 'https://thymian.dev/references/errors/hook-error/',
+            severity: 'warn',
+        }),
+    };
+}
+/**
+ * Runs one hook through the shared attribution pipeline and always throws on
+ * failure — for `defineSample`, `beforeAll` and `afterAll`, which have no
+ * Transaction to report a `skip`/`fail` verdict against. Callable only with a
+ * kind outside {@link TRANSACTION_SCOPED_KINDS}, which is what guarantees
+ * {@link interpretHookFailure} always hands back a `rethrow` here and never a
+ * `report` with nowhere to go.
+ *
+ * The raw return value is handed back rather than discarded: `beforeAll` is
+ * the one kind whose return is not mutate-and-ignore — a returned function is
+ * a cleanup to run at teardown.
+ */
+export async function invokeOrThrow(kind, entry, args) {
+    try {
+        return await invokeHook(entry, args);
+    }
+    catch (e) {
+        const { rethrow } = interpretHookFailure(e, kind, entry);
+        if (!rethrow) {
+            // Unreachable: `kind`'s type excludes every member of
+            // TRANSACTION_SCOPED_KINDS, and that is the only set
+            // interpretHookFailure ever produces a `report` — never a `rethrow` —
+            // for.
+            throw new Error(`invariant violated: interpretHookFailure produced no rethrow for hook kind "${kind}"`);
+        }
+        throw rethrow;
+    }
+}
+//# sourceMappingURL=invoke-hook.js.map

package/dist/hooks/invoke-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-hook.js","sourceRoot":"","sources":["../../src/hooks/invoke-hook.ts"],"names":[],"mappings":"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"}

package/dist/hooks/load-user-hooks.d.ts

@@ -0,0 +1,96 @@
+import type { TransactionCatalog } from '../selectors/transaction-catalog.js';
+import type { HookDiagnostic } from './hook-diagnostics.js';
+import { type HookRegistration } from './hook-registration.js';
+/** The specifier a hook file writes. */
+export declare const HOOKS_RUNTIME_SPECIFIER = "@thymian/hooks";
+/**
+ * Keep a file iff its name ends in one of the six module extensions and is not a
+ * declaration file.
+ *
+ * `.tsx`/`.jsx` are not among them: JSX needs a transform pragma this jiti
+ * instance is not configured for, so such a file would be scanned only to fail
+ * on its own syntax.
+ *
+ * The declaration-file exclusion is case-insensitive while the keep pattern is
+ * not. `types.D.ts` ends in `.ts` and so matched the keep pattern, but missed a
+ * case-sensitive `\.d\.ts$` — and a hand-written declaration file handed to jiti
+ * fails on its own `declare module` syntax. Widening the exclusion can only ever
+ * skip a file that could not have executed; widening the keep pattern the same
+ * way would make the scan depend on filesystem case sensitivity.
+ */
+export declare function isHookFile(name: string): boolean;
+/** The hooks that apply to one Transaction, each in registration order. */
+export type TransactionHooks = {
+    readonly defineSample: readonly CollectedRegistration[];
+    readonly beforeEach: readonly CollectedRegistration[];
+    readonly afterEach: readonly CollectedRegistration[];
+    readonly authorize: readonly CollectedRegistration[];
+};
+/** A registration plus where it came from, which only the loader knows. */
+export type CollectedRegistration = {
+    registration: HookRegistration;
+    /** Hooks-dir-relative path, `/`-normalized. */
+    file: string;
+    /** Absolute directory of the hook file, for the file helpers. */
+    dir: string;
+    exportName: string;
+    /**
+     * Position in the whole scan: file order on the outside, registration order
+     * inside each file.
+     *
+     * The registration's own `order` cannot serve: it is stamped when the hook
+     * is created, and a hook created in a shared module is created when the
+     * first file that imports it is evaluated, not when the file that exports
+     * it is. This is the one number that orders every hook in the run against
+     * every other, which is what run-scoped teardown needs to reverse.
+     */
+    sequence: number;
+};
+export type LoadUserHooksResult = {
+    /** Hook files found, in load order. */
+    files: readonly string[];
+    /** Per-transaction bindings, keyed by transaction id. */
+    byTransactionId: ReadonlyMap<string, TransactionHooks>;
+    /** Run-scoped registrations, in registration order. */
+    runScoped: {
+        beforeAll: CollectedRegistration[];
+        afterAll: CollectedRegistration[];
+    };
+    /** The global `authorize(callback)` registrations, in registration order. */
+    globalAuthorize: CollectedRegistration[];
+    /** Every hook that does not resolve. A non-empty list must fail the run. */
+    diagnostics: readonly HookDiagnostic[];
+    /**
+     * Hooks that resolve but cannot both apply — today, two `defineSample` hooks
+     * on one Transaction. Kept apart from {@link diagnostics} because the fault is
+     * different and so is the sentence a reader needs: the selector is fine, the
+     * pair of hooks is not.
+     */
+    conflicts: readonly HookDiagnostic[];
+    /**
+     * Hooks a file created and did not export, so nothing can reach them.
+     *
+     * Kept apart from {@link diagnostics} for the same reason {@link conflicts}
+     * is: the selector resolves and the file loaded, so a sentence about hooks
+     * that "do not resolve" would send the reader to the one thing that is fine.
+     */
+    unexported: readonly HookDiagnostic[];
+    /**
+     * Things the scan could not do, which are not a hook failing to resolve.
+     *
+     * Kept apart from {@link diagnostics} on purpose: an unreadable subdirectory
+     * is why the walk goes a level at a time, and turning it into a fatal error
+     * would throw away every healthy hook in the tree — the outcome the level-wise
+     * walk exists to avoid. These are reported as warnings and the run continues.
+     */
+    warnings: readonly string[];
+};
+/**
+ * Scan the hooks directory and bind every registration it exports to the
+ * Transactions it names.
+ *
+ * A hooks directory that does not exist is not an error — `sampler init` is
+ * optional and a project may have no hooks at all — it is an empty result.
+ */
+export declare function loadUserHooks(hooksDir: string, catalog: TransactionCatalog): Promise<LoadUserHooksResult>;
+//# sourceMappingURL=load-user-hooks.d.ts.map

package/dist/hooks/load-user-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-user-hooks.d.ts","sourceRoot":"","sources":["../../src/hooks/load-user-hooks.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAG9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,wBAAwB,CAAC;AAwBhC,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMhD;AAED,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACtD,CAAC;AAOF,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,uCAAuC;IACvC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,yDAAyD;IACzD,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACvD,uDAAuD;IACvD,SAAS,EAAE;QACT,SAAS,EAAE,qBAAqB,EAAE,CAAC;QACnC,QAAQ,EAAE,qBAAqB,EAAE,CAAC;KACnC,CAAC;IACF,6EAA6E;IAC7E,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,4EAA4E;IAC5E,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC;;;;;OAKG;IACH,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,CAAC;AAgPF;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAgO9B"}