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

package/dist/hooks/resolve-targeting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-targeting.d.ts","sourceRoot":"","sources":["../../src/hooks/resolve-targeting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAU5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAS9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAsBlE;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,cAAc,EAAE,GAC5B,SAAS,sBAAsB,EAAE,CAkBnC"}

package/dist/hooks/resolve-targeting.js

@@ -0,0 +1,168 @@
+import { nearestPathHints } from '../selectors/nearest-paths.js';
+import { hasWildcard, matchesPathGlob } from '../selectors/path-glob.js';
+import { isSelector, malformedSelectorHints, parseSelector, } from '../selectors/selector.js';
+import { emptyValueFields, filterProblems, isTransactionFilter, matchesTransactionFilter, pathValuesOf, } from '../selectors/transaction-filter.js';
+/**
+ * The selectors a target names, or `undefined` when it is not a selector form.
+ *
+ * Takes `unknown` rather than a target type: a `.js` hook file is legal input
+ * and is not type-checked, so the value here is whatever the user passed.
+ */
+function selectorsOf(target) {
+    if (typeof target === 'string') {
+        return [target];
+    }
+    if (Array.isArray(target) && target.every((v) => typeof v === 'string')) {
+        return target;
+    }
+    return undefined;
+}
+/**
+ * The Transactions a target covers, reporting whatever stops it covering any.
+ *
+ * A target that resolves to nothing is a diagnostic, never an empty result that
+ * runs quietly. There are four ways a hook can silently stop doing its job — a
+ * dangling Selector, a value that is not a legal filter value, a path or glob
+ * that names nothing, and a filter whose legal values intersect nothing — and
+ * each one gets its own sentence, because "this matched nothing" is true and
+ * useless when the cause is one typo.
+ */
+export function resolveTargeting(kind, target, entry, catalog, diagnostics) {
+    const where = { file: entry.file, exportName: entry.exportName };
+    const selectors = selectorsOf(target);
+    if (selectors) {
+        return resolveSelectors(kind, selectors, where, catalog, diagnostics);
+    }
+    if (isTransactionFilter(target)) {
+        return resolveFilter(kind, target, where, catalog, diagnostics);
+    }
+    diagnostics.push({
+        ...where,
+        reason: `${kind} was given a target that is neither a selector, a list of selectors, nor a transaction filter`,
+    });
+    return [];
+}
+function resolveSelectors(kind, selectors, where, catalog, diagnostics) {
+    if (selectors.length === 0) {
+        diagnostics.push({
+            ...where,
+            reason: `${kind} was given an empty list of selectors, so it targets nothing`,
+        });
+        return [];
+    }
+    const resolved = [];
+    // Naming one transaction twice targets it once.
+    //
+    // Composing lists is the ordinary way to build a target —
+    // `beforeEach([...PUBLIC, ...ADMIN], fn)` — and one transaction in both
+    // halves is a duplicate the author cannot see. Bound twice, the hook runs
+    // twice per request, and a `defineSample` written that way reports a
+    // conflict against itself.
+    const bound = new Set();
+    for (const selector of selectors) {
+        const transaction = catalog.tryResolve(selector);
+        if (transaction) {
+            if (!bound.has(transaction.transactionId)) {
+                bound.add(transaction.transactionId);
+                resolved.push(transaction);
+            }
+            continue;
+        }
+        // A target is user input like any other, and a hand-authored selector can
+        // fail to even parse — never thrown from here, or a single typo'd target
+        // would crash `validate`, `show` and `sync` instead of being recorded
+        // against the hook that carries it. `isSelector` is what tells "malformed"
+        // apart from "well-formed but unknown", which decides whether a grammar
+        // hint or a near-miss is the useful thing to say.
+        if (!isSelector(selector)) {
+            diagnostics.push({
+                ...where,
+                reason: `${kind} targets "${selector}", which is not a valid transaction selector`,
+                suggestions: malformedSelectorHints(selector),
+            });
+            continue;
+        }
+        diagnostics.push({
+            ...where,
+            reason: `${kind} targets the selector "${selector}", which names no transaction in the loaded API description`,
+            suggestions: catalog.nearMissSuggestions(parseSelector(selector)),
+        });
+    }
+    return resolved;
+}
+/**
+ * The Transactions a filter covers.
+ *
+ * Faults are reported in the order they stop mattering: a filter whose text
+ * cannot mean anything is not asked what it matches, an empty value array is
+ * named before the catalog is even consulted, and a vacuous path value is
+ * named individually before the filter as a whole is called empty.
+ */
+function resolveFilter(kind, filter, where, catalog, diagnostics) {
+    const problems = filterProblems(filter);
+    if (problems.length > 0) {
+        diagnostics.push({
+            ...where,
+            reason: `${kind} was given a filter that cannot mean anything: ${problems.join('; ')}`,
+        });
+        return [];
+    }
+    // A field given an explicit, empty value array is a shape the grammar
+    // accepts — it is not a "cannot mean anything" fault — but it is a
+    // disjunction of zero alternatives, which matches nothing by construction.
+    // Named here, the same way an empty list of selectors is: a hook must never
+    // silently apply to every Transaction because a computed array came back
+    // empty.
+    const emptyFields = emptyValueFields(filter);
+    if (emptyFields.length > 0) {
+        const plural = emptyFields.length > 1;
+        const names = emptyFields.map((name) => `"${name}"`).join(', ');
+        diagnostics.push({
+            ...where,
+            reason: `${kind} targets a filter whose ${plural ? 'fields' : 'field'} ${names} ${plural ? 'were' : 'was'} given an empty list of values, so it targets nothing`,
+        });
+        return [];
+    }
+    const paths = catalog.paths();
+    if (paths.length === 0) {
+        diagnostics.push({
+            ...where,
+            reason: `${kind} targets a filter, but no transactions are loaded, so no filter can match`,
+            suggestions: [
+                'Check that your configured specifications were found and describe at least one operation.',
+            ],
+        });
+        return [];
+    }
+    let vacuous = false;
+    for (const value of pathValuesOf(filter)) {
+        if (paths.some((path) => matchesPathGlob(value, path))) {
+            continue;
+        }
+        vacuous = true;
+        diagnostics.push({
+            ...where,
+            reason: hasWildcard(value)
+                ? `${kind} targets the path glob "${value}", which matches no path in the loaded API description`
+                : `${kind} targets the path "${value}", which no path in the loaded API description is spelled as`,
+            suggestions: nearestPathHints(value, paths),
+        });
+    }
+    if (vacuous) {
+        return [];
+    }
+    const matched = catalog
+        .transactions()
+        .filter((transaction) => matchesTransactionFilter(filter, transaction));
+    if (matched.length === 0) {
+        diagnostics.push({
+            ...where,
+            reason: `${kind} targets a filter whose values are all valid but intersect no transaction in the loaded API description`,
+            suggestions: [
+                'Every field of a filter must hold at the same time, so check whether the combination can exist — a method and a status that never occur together, for example.',
+            ],
+        });
+    }
+    return matched;
+}
+//# sourceMappingURL=resolve-targeting.js.map

package/dist/hooks/resolve-targeting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-targeting.js","sourceRoot":"","sources":["../../src/hooks/resolve-targeting.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,aAAa,GAEd,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,GAEb,MAAM,oCAAoC,CAAC;AAM5C;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAAe;IAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QACxE,OAAO,MAA6B,CAAC;IACvC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,MAAe,EACf,KAA4B,EAC5B,OAA2B,EAC3B,WAA6B;IAE7B,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;IACjE,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAEtC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IAClE,CAAC;IAED,WAAW,CAAC,IAAI,CAAC;QACf,GAAG,KAAK;QACR,MAAM,EAAE,GAAG,IAAI,+FAA+F;KAC/G,CAAC,CAAC;IAEH,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,gBAAgB,CACvB,IAAY,EACZ,SAA8B,EAC9B,KAAY,EACZ,OAA2B,EAC3B,WAA6B;IAE7B,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,8DAA8D;SAC9E,CAAC,CAAC;QAEH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,gDAAgD;IAChD,EAAE;IACF,0DAA0D;IAC1D,wEAAwE;IACxE,0EAA0E;IAC1E,qEAAqE;IACrE,2BAA2B;IAC3B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAEjD,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC1C,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC7B,CAAC;YAED,SAAS;QACX,CAAC;QAED,0EAA0E;QAC1E,yEAAyE;QACzE,sEAAsE;QACtE,2EAA2E;QAC3E,wEAAwE;QACxE,kDAAkD;QAClD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,WAAW,CAAC,IAAI,CAAC;gBACf,GAAG,KAAK;gBACR,MAAM,EAAE,GAAG,IAAI,aAAa,QAAQ,8CAA8C;gBAClF,WAAW,EAAE,sBAAsB,CAAC,QAAQ,CAAC;aAC9C,CAAC,CAAC;YAEH,SAAS;QACX,CAAC;QAED,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,0BAA0B,QAAQ,6DAA6D;YAC9G,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;SAClE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CACpB,IAAY,EACZ,MAAyB,EACzB,KAAY,EACZ,OAA2B,EAC3B,WAA6B;IAE7B,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,kDAAkD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SACvF,CAAC,CAAC;QAEH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sEAAsE;IACtE,mEAAmE;IACnE,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,SAAS;IACT,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAE7C,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhE,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,2BAA2B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,IAAI,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,uDAAuD;SACjK,CAAC,CAAC;QAEH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAE9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,2EAA2E;YAC1F,WAAW,EAAE;gBACX,2FAA2F;aAC5F;SACF,CAAC,CAAC;QAEH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YACvD,SAAS;QACX,CAAC;QAED,OAAO,GAAG,IAAI,CAAC;QAEf,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC;gBACxB,CAAC,CAAC,GAAG,IAAI,2BAA2B,KAAK,wDAAwD;gBACjG,CAAC,CAAC,GAAG,IAAI,sBAAsB,KAAK,8DAA8D;YACpG,WAAW,EAAE,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO;SACpB,YAAY,EAAE;SACd,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAE1E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,MAAM,EAAE,GAAG,IAAI,yGAAyG;YACxH,WAAW,EAAE;gBACX,gKAAgK;aACjK;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/hooks/run-scoped-hooks.d.ts

@@ -0,0 +1,83 @@
+import type { Logger } from '@thymian/core';
+import type { HookUtilsFactory } from './hook-utils-factory.js';
+import type { CollectedRegistration } from './load-user-hooks.js';
+/**
+ * The run-scoped half of the lifecycle: `beforeAll` on a first-touch latch, and
+ * `afterAll` plus any cleanups `beforeAll` returned, on close.
+ *
+ * "Once before the run" has no meaning until something decides when the run
+ * starts, and the sampler's first observation of a run is the first request. So
+ * the latch is armed by the first `beforeRequest`, and it is also what gates
+ * teardown: a command that never sends a request — `sampler show`, `sampler
+ * init` — must not run somebody's teardown.
+ */
+export declare class RunScopedHooks {
+    private readonly logger;
+    private readonly makeUtils;
+    private beforeAll;
+    private teardown;
+    /**
+     * The latch itself: `undefined` until the first `beforeRequest` arms it,
+     * then the one setup run every caller — sequential or concurrent — awaits.
+     *
+     * A memoized promise rather than a boolean, because a boolean only answers
+     * "has setup started", and under concurrent dispatch a second caller can
+     * observe that answer before the first caller's `beforeAll` has finished (or
+     * failed). Memoizing the promise itself means every caller awaits the same
+     * settlement: nobody's request proceeds until setup resolves, and if it
+     * rejects, every caller — however many raced in — rejects with it.
+     */
+    private startPromise;
+    constructor(logger: Logger, makeUtils: HookUtilsFactory);
+    /**
+     * Adopt newly loaded hooks.
+     *
+     * A reload drops teardown that the previous load's `beforeAll` registered. It
+     * has to: those closures were built against a format that is no longer
+     * loaded, and running them later would tear down a fixture whose description
+     * has changed underneath. A reload mid-run is not a shape the CLI produces.
+     */
+    load(hooks: {
+        beforeAll: readonly CollectedRegistration[];
+        afterAll: readonly CollectedRegistration[];
+    }): void;
+    /**
+     * Arm the latch and run `beforeAll` in registration order, once — memoized as
+     * a promise, so every caller (sequential or concurrent) awaits the very same
+     * setup run instead of each independently checking whether one already
+     * started.
+     *
+     * The assignment happens synchronously, before {@link runBeforeAll}'s body
+     * gets its first chance to `await` anything: a second, concurrent caller
+     * reaching this method — however soon after the first — always finds
+     * {@link startPromise} already set and receives *that* promise rather than
+     * starting a second run. That is what makes concurrent dispatch safe: no
+     * caller's request proceeds until this promise settles, and if it rejects,
+     * every caller who awaited it rejects with it — none of their requests were
+     * ever sent.
+     *
+     * The latch is armed **before** the callbacks run, so a `beforeAll` that
+     * threw still gets its teardown — and so a later request cannot re-run setup
+     * that already failed.
+     */
+    start(): Promise<void>;
+    /**
+     * The setup run itself. Failure goes through the same attribution wrapper
+     * every other hook kind does — there is no `beforeAll`-specific copy of it
+     * here any more — and propagates out of the memoized promise so every
+     * awaiter sees it.
+     */
+    private runBeforeAll;
+    /**
+     * Run teardown in reverse order of the run: one list holding both the
+     * cleanups `beforeAll` returned and the `afterAll` hooks, reversed.
+     *
+     * Best-effort, because `core.close` is not a place a failure can be acted on —
+     * the report is already written. A teardown error is logged as a warning and
+     * the rest still runs, so one leaking fixture cannot strand the others.
+     *
+     * Latch-gated: nothing runs if no request was ever sent.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=run-scoped-hooks.d.ts.map

package/dist/hooks/run-scoped-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-scoped-hooks.d.ts","sourceRoot":"","sources":["../../src/hooks/run-scoped-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAYlE;;;;;;;;;GASG;AACH,qBAAa,cAAc;IAkBvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAlB5B,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,QAAQ,CAAsB;IAEtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY,CAA4B;gBAG7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,gBAAgB;IAG9C;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE;QACV,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;QAC5C,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;KAC5C,GAAG,IAAI;IAsBR;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB;;;;;OAKG;YACW,YAAY;IAyB1B;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAiC7B"}

package/dist/hooks/run-scoped-hooks.js

@@ -0,0 +1,153 @@
+import { invokeOrThrow, reportHookResults } from './invoke-hook.js';
+/**
+ * The run-scoped half of the lifecycle: `beforeAll` on a first-touch latch, and
+ * `afterAll` plus any cleanups `beforeAll` returned, on close.
+ *
+ * "Once before the run" has no meaning until something decides when the run
+ * starts, and the sampler's first observation of a run is the first request. So
+ * the latch is armed by the first `beforeRequest`, and it is also what gates
+ * teardown: a command that never sends a request — `sampler show`, `sampler
+ * init` — must not run somebody's teardown.
+ */
+export class RunScopedHooks {
+    logger;
+    makeUtils;
+    beforeAll = [];
+    teardown = [];
+    /**
+     * The latch itself: `undefined` until the first `beforeRequest` arms it,
+     * then the one setup run every caller — sequential or concurrent — awaits.
+     *
+     * A memoized promise rather than a boolean, because a boolean only answers
+     * "has setup started", and under concurrent dispatch a second caller can
+     * observe that answer before the first caller's `beforeAll` has finished (or
+     * failed). Memoizing the promise itself means every caller awaits the same
+     * settlement: nobody's request proceeds until setup resolves, and if it
+     * rejects, every caller — however many raced in — rejects with it.
+     */
+    startPromise;
+    constructor(logger, makeUtils) {
+        this.logger = logger;
+        this.makeUtils = makeUtils;
+    }
+    /**
+     * Adopt newly loaded hooks.
+     *
+     * A reload drops teardown that the previous load's `beforeAll` registered. It
+     * has to: those closures were built against a format that is no longer
+     * loaded, and running them later would tear down a fixture whose description
+     * has changed underneath. A reload mid-run is not a shape the CLI produces.
+     */
+    load(hooks) {
+        this.beforeAll = hooks.beforeAll;
+        this.startPromise = undefined;
+        // `afterAll` hooks are teardown from the start; cleanups join as their
+        // `beforeAll` returns them. One list, one order — so an `afterAll`
+        // registered after a `beforeAll` runs *before* that `beforeAll`'s cleanup
+        // when the list is reversed.
+        this.teardown = hooks.afterAll.map((entry) => ({
+            sequence: entry.sequence,
+            describe: `the afterAll hook exported as "${entry.exportName}" from "${entry.file}"`,
+            run: async () => {
+                const { utils, results } = this.makeUtils(entry);
+                try {
+                    await invokeOrThrow('afterAll', entry, [utils]);
+                }
+                finally {
+                    reportHookResults(this.logger, results);
+                }
+            },
+        }));
+    }
+    /**
+     * Arm the latch and run `beforeAll` in registration order, once — memoized as
+     * a promise, so every caller (sequential or concurrent) awaits the very same
+     * setup run instead of each independently checking whether one already
+     * started.
+     *
+     * The assignment happens synchronously, before {@link runBeforeAll}'s body
+     * gets its first chance to `await` anything: a second, concurrent caller
+     * reaching this method — however soon after the first — always finds
+     * {@link startPromise} already set and receives *that* promise rather than
+     * starting a second run. That is what makes concurrent dispatch safe: no
+     * caller's request proceeds until this promise settles, and if it rejects,
+     * every caller who awaited it rejects with it — none of their requests were
+     * ever sent.
+     *
+     * The latch is armed **before** the callbacks run, so a `beforeAll` that
+     * threw still gets its teardown — and so a later request cannot re-run setup
+     * that already failed.
+     */
+    start() {
+        this.startPromise ??= this.runBeforeAll();
+        return this.startPromise;
+    }
+    /**
+     * The setup run itself. Failure goes through the same attribution wrapper
+     * every other hook kind does — there is no `beforeAll`-specific copy of it
+     * here any more — and propagates out of the memoized promise so every
+     * awaiter sees it.
+     */
+    async runBeforeAll() {
+        for (const entry of this.beforeAll) {
+            const { utils, results } = this.makeUtils(entry);
+            let returned;
+            try {
+                returned = await invokeOrThrow('beforeAll', entry, [utils]);
+            }
+            finally {
+                reportHookResults(this.logger, results);
+            }
+            if (typeof returned === 'function') {
+                const cleanup = returned;
+                this.teardown.push({
+                    sequence: entry.sequence,
+                    describe: `the cleanup returned by the beforeAll hook exported as "${entry.exportName}" from "${entry.file}"`,
+                    run: async () => {
+                        await cleanup();
+                    },
+                });
+            }
+        }
+    }
+    /**
+     * Run teardown in reverse order of the run: one list holding both the
+     * cleanups `beforeAll` returned and the `afterAll` hooks, reversed.
+     *
+     * Best-effort, because `core.close` is not a place a failure can be acted on —
+     * the report is already written. A teardown error is logged as a warning and
+     * the rest still runs, so one leaking fixture cannot strand the others.
+     *
+     * Latch-gated: nothing runs if no request was ever sent.
+     */
+    async close() {
+        if (!this.startPromise) {
+            return;
+        }
+        // Setup may still be in flight, or may have rejected, by the time close
+        // runs. Either way, teardown waits for it to settle first: racing ahead
+        // would read {@link teardown} while `runBeforeAll` is still pushing
+        // cleanups onto it, and a rejection here is not this method's to report —
+        // whoever awaited `start()` already saw it. Best-effort teardown still
+        // runs for whatever succeeded before the rejection.
+        await this.startPromise.catch(() => {
+            // Ignored here: whoever awaited `start()` already saw this rejection.
+        });
+        const items = this.teardown
+            .splice(0)
+            // A stable sort, so two items registered in the same position keep the
+            // order they joined the list in.
+            .map((item, index) => ({ item, index }))
+            .sort((a, b) => b.item.sequence - a.item.sequence || b.index - a.index)
+            .map(({ item }) => item);
+        for (const item of items) {
+            try {
+                await item.run();
+            }
+            catch (e) {
+                this.logger.warn(`Teardown continued after ${item.describe} threw: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=run-scoped-hooks.js.map

package/dist/hooks/run-scoped-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-scoped-hooks.js","sourceRoot":"","sources":["../../src/hooks/run-scoped-hooks.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAapE;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAc;IAkBN;IACA;IAlBX,SAAS,GAAqC,EAAE,CAAC;IACjD,QAAQ,GAAmB,EAAE,CAAC;IAEtC;;;;;;;;;;OAUG;IACK,YAAY,CAA4B;IAEhD,YACmB,MAAc,EACd,SAA2B;QAD3B,WAAM,GAAN,MAAM,CAAQ;QACd,cAAS,GAAT,SAAS,CAAkB;IAC3C,CAAC;IAEJ;;;;;;;OAOG;IACH,IAAI,CAAC,KAGJ;QACC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,uEAAuE;QACvE,mEAAmE;QACnE,0EAA0E;QAC1E,6BAA6B;QAC7B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC7C,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,kCAAkC,KAAK,CAAC,UAAU,WAAW,KAAK,CAAC,IAAI,GAAG;YACpF,GAAG,EAAE,KAAK,IAAI,EAAE;gBACd,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBAEjD,IAAI,CAAC;oBACH,MAAM,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBAClD,CAAC;wBAAS,CAAC;oBACT,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC;SACF,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK;QACH,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;QAE1C,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,YAAY;QACxB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACjD,IAAI,QAAiB,CAAC;YAEtB,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9D,CAAC;oBAAS,CAAC;gBACT,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC1C,CAAC;YAED,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACnC,MAAM,OAAO,GAAG,QAAqB,CAAC;gBAEtC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,QAAQ,EAAE,2DAA2D,KAAK,CAAC,UAAU,WAAW,KAAK,CAAC,IAAI,GAAG;oBAC7G,GAAG,EAAE,KAAK,IAAI,EAAE;wBACd,MAAM,OAAO,EAAE,CAAC;oBAClB,CAAC;iBACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QAED,wEAAwE;QACxE,wEAAwE;QACxE,oEAAoE;QACpE,0EAA0E;QAC1E,uEAAuE;QACvE,oDAAoD;QACpD,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE;YACjC,sEAAsE;QACxE,CAAC,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ;aACxB,MAAM,CAAC,CAAC,CAAC;YACV,uEAAuE;YACvE,iCAAiC;aAChC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;aACvC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACtE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAE3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;YACnB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,4BAA4B,IAAI,CAAC,QAAQ,WAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACjG,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,21 +1,7 @@
-import { type HttpRequestTemplate, type SerializedThymianFormat, type ThymianHttpTransaction, type ThymianPlugin, type ThymianSchema } from '@thymian/core';
-import { type SamplerValidationReport } from './validation/validate-sampler-output.js';
+import { type HttpRequestTemplate, type ThymianHttpTransaction, type ThymianPlugin, type ThymianSchema } from '@thymian/core';
+import { type ValidationReport as SamplerValidationReport } from './validation/validate-sampler.js';
 declare module '@thymian/core' {
     interface ThymianActions {
-        'sampler.init': {
-            event: {
-                format: SerializedThymianFormat;
-                overwrite?: boolean;
-            };
-            response: void;
-        };
-        'sampler.validate': {
-            event: {
-                format: SerializedThymianFormat;
-                forPath?: string;
-            };
-            response: SamplerValidationReport;
-        };
         'core.request.sample': {
             event: {
                 transaction: ThymianHttpTransaction;
@@ -33,11 +19,48 @@ declare module '@thymian/core' {
                 $encoding?: string;
             };
         };
-        'sampler.path-from-transaction': {
+        'sampler.show': {
             event: {
-                transactionId: string;
+                selector: string;
+            };
+            response: {
+                selector: string;
+                request: HttpRequestTemplate;
+            };
+        };
+        'sampler.sync': {
+            event: {
+                /** Report what would change and write nothing. The CI gate. */
+                check?: boolean;
+            };
+            response: {
+                /** Generated files whose **types** would change, or did. */
+                changed: string[];
+                /** Whether anything was written. */
+                wrote: boolean;
+                /**
+                 * Generated files whose **bytes** changed. A superset of `changed`: a
+                 * description edit rewrites a JSDoc comment without moving a type.
+                 */
+                rewritten?: string[];
+            };
+        };
+        'sampler.validate': {
+            event: Record<string, never>;
+            response: SamplerValidationReport;
+        };
+        'sampler.init': {
+            event: Record<string, never>;
+            response: {
+                /** The sampler root, absolute. */
+                root: string;
+                /** Generated files written, relative to the root. */
+                generated: string[];
+                /** Whether a tsconfig was scaffolded, or one was already there. */
+                tsconfig: 'written' | 'kept';
+                /** What the user has to do to their own tsconfig, in their own words. */
+                rootExcludeNote: string[];
             };
-            response: string | undefined;
         };
     }
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAG5B,KAAK,sBAAsB,EAE3B,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAgBvB,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,cAAc;QACtB,cAAc,EAAE;YACd,KAAK,EAAE;gBACL,MAAM,EAAE,uBAAuB,CAAC;gBAChC,SAAS,CAAC,EAAE,OAAO,CAAC;aACrB,CAAC;YACF,QAAQ,EAAE,IAAI,CAAC;SAChB,CAAC;QAEF,kBAAkB,EAAE;YAClB,KAAK,EAAE;gBACL,MAAM,EAAE,uBAAuB,CAAC;gBAChC,OAAO,CAAC,EAAE,MAAM,CAAC;aAClB,CAAC;YACF,QAAQ,EAAE,uBAAuB,CAAC;SACnC,CAAC;QAEF,qBAAqB,EAAE;YACrB,KAAK,EAAE;gBACL,WAAW,EAAE,sBAAsB,CAAC;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;aACnC,CAAC;YACF,QAAQ,EAAE,mBAAmB,CAAC;SAC/B,CAAC;QAEF,sBAAsB,EAAE;YACtB,KAAK,EAAE;gBACL,WAAW,EAAE,MAAM,CAAC;gBACpB,MAAM,EAAE,aAAa,CAAC;aACvB,CAAC;YACF,QAAQ,EAAE;gBAAE,QAAQ,EAAE,OAAO,CAAC;gBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;SACrD,CAAC;QAEF,+BAA+B,EAAE;YAC/B,KAAK,EAAE;gBACL,aAAa,EAAE,MAAM,CAAC;aACvB,CAAC;YACF,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;SAC9B,CAAC;KACH;CACF;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AA8CF,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,CA8MrE,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,mBAAmB,EAExB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AA0BvB,OAAO,EAGL,KAAK,gBAAgB,IAAI,uBAAuB,EACjD,MAAM,kCAAkC,CAAC;AAE1C,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,cAAc;QACtB,qBAAqB,EAAE;YACrB,KAAK,EAAE;gBACL,WAAW,EAAE,sBAAsB,CAAC;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;aACnC,CAAC;YACF,QAAQ,EAAE,mBAAmB,CAAC;SAC/B,CAAC;QAEF,sBAAsB,EAAE;YACtB,KAAK,EAAE;gBACL,WAAW,EAAE,MAAM,CAAC;gBACpB,MAAM,EAAE,aAAa,CAAC;aACvB,CAAC;YACF,QAAQ,EAAE;gBAAE,QAAQ,EAAE,OAAO,CAAC;gBAAC,SAAS,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;SACrD,CAAC;QAEF,cAAc,EAAE;YACd,KAAK,EAAE;gBACL,QAAQ,EAAE,MAAM,CAAC;aAClB,CAAC;YACF,QAAQ,EAAE;gBACR,QAAQ,EAAE,MAAM,CAAC;gBACjB,OAAO,EAAE,mBAAmB,CAAC;aAC9B,CAAC;SACH,CAAC;QAEF,cAAc,EAAE;YACd,KAAK,EAAE;gBACL,+DAA+D;gBAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;aACjB,CAAC;YACF,QAAQ,EAAE;gBACR,4DAA4D;gBAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;gBAClB,oCAAoC;gBACpC,KAAK,EAAE,OAAO,CAAC;gBACf;;;mBAGG;gBACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;aACtB,CAAC;SACH,CAAC;QAEF,kBAAkB,EAAE;YAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC7B,QAAQ,EAAE,uBAAuB,CAAC;SACnC,CAAC;QAEF,cAAc,EAAE;YACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC7B,QAAQ,EAAE;gBACR,kCAAkC;gBAClC,IAAI,EAAE,MAAM,CAAC;gBACb,qDAAqD;gBACrD,SAAS,EAAE,MAAM,EAAE,CAAC;gBACpB,mEAAmE;gBACnE,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;gBAC7B,yEAAyE;gBACzE,eAAe,EAAE,MAAM,EAAE,CAAC;aAC3B,CAAC;SACH,CAAC;KACH;CACF;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,CA+OrE,CAAC;AAEF,eAAe,YAAY,CAAC"}