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

package/dist/hooks/load-user-hooks.js

@@ -0,0 +1,432 @@
+import { readdir, realpath } from 'node:fs/promises';
+import { createRequire, Module } from 'node:module';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createJiti } from 'jiti';
+import { toTypeScriptPath } from '../ts-path.js';
+import { entryExists } from '../utils.js';
+import { hookFileImportError } from './hook-diagnostics.js';
+import { createdRegistrations, isHookRegistration, } from './hook-registration.js';
+import { resolveTargeting } from './resolve-targeting.js';
+/**
+ * `@thymian/hooks` is resolved by **this** alias — not by a tsconfig `paths`
+ * entry and not by a committed `.d.ts` — which is what lets a hook file import
+ * runtime values in a workspace with no generated directory, no generated
+ * tsconfig and `sampler init` never run.
+ *
+ * Two properties are load-bearing:
+ *
+ * - **An absolute path, never a bare specifier.** The package exports only `"."`
+ *   and `"./package.json"`, so `'@thymian/plugin-sampler/hook-api'` would be
+ *   blocked by the exports map in a published install, and adding a subpath
+ *   export would put an internal module on the public surface. Deriving the path
+ *   from `import.meta.url` sidesteps the exports map entirely.
+ * - **Extensionless.** jiti resolves `.js .mjs .cjs .ts .mts .cts` itself, so one
+ *   target serves `dist/hooks/hook-api.js` in an installed CLI and
+ *   `src/hooks/hook-api.ts` when running from source, identically.
+ */
+const hooksRuntimeModule = fileURLToPath(new URL('./hook-api.js', import.meta.url)).replace(/\.[cm]?js$/, '');
+/** The specifier a hook file writes. */
+export 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 function isHookFile(name) {
+    if (/\.d\.[cm]?ts$/i.test(name)) {
+        return false;
+    }
+    return /\.[cm]?[jt]s$/.test(name);
+}
+/** Hooks-dir-relative, `/`-normalized — the sort key and the diagnostic label. */
+function hooksDirRelative(hooksDir, full) {
+    return toTypeScriptPath(relative(hooksDir, full));
+}
+/**
+ * One directory level, then its subdirectories.
+ *
+ * Deliberately not `readdir({ recursive: true })`: that is a single call, so an
+ * `EACCES` on any nested directory rejects the *whole* walk and loses every
+ * healthy hook in the tree. Walking a level at a time costs one `readdir` per
+ * directory and confines a failure to the subtree that actually failed.
+ *
+ * Dot-directories are skipped, so an editor's or a tool's cache inside the hooks
+ * tree is not scanned.
+ */
+async function walkHookDirectory(hooksDir, dir, isRoot, files, warnings) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isRoot) {
+            throw error;
+        }
+        warnings.push(`The hooks subdirectory "${hooksDirRelative(hooksDir, dir)}" could not be read (${error instanceof Error ? error.message : String(error)}), so any hooks inside it were not loaded.`);
+        return;
+    }
+    const directories = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        // `Dirent`'s type flags describe the entry itself, never the symlink's
+        // target — `isFile()`/`isDirectory()` are both false for a symlink, which
+        // already keeps one out of `files`/`directories` below. What was missing
+        // is the word: a hook that silently never runs because its file is a
+        // symlink looks exactly like a Thymian bug, so it is named rather than
+        // dropped.
+        if (entry.isSymbolicLink()) {
+            warnings.push(`The hooks entry "${hooksDirRelative(hooksDir, full)}" is a symlink and was skipped: symlinked hook files and directories are not followed.`);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            // `node_modules` is never a source of hooks, however it got there —
+            // installed by the user's own tooling or vendored by hand — so it is
+            // excluded by name rather than relying on every install layout to
+            // happen to start with a dot.
+            if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                directories.push(full);
+            }
+            continue;
+        }
+        if (entry.isFile() && isHookFile(entry.name)) {
+            files.push(full);
+        }
+    }
+    for (const directory of directories) {
+        await walkHookDirectory(hooksDir, directory, false, files, warnings);
+    }
+}
+/**
+ * A stable load order: hooks-dir-relative key, by code unit.
+ *
+ * `readdir` order is filesystem-dependent, and composition order is observable,
+ * so the order hooks are loaded in is a decision rather than an accident.
+ */
+function compareKeys(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Every registration exported by one module namespace, with its export name.
+ *
+ * Both a registration and an array of them count, at any export name including
+ * `default`. Nothing here calls a value to find out what it is: functions are
+ * rejected structurally by {@link isHookRegistration}.
+ */
+function collectFromNamespace(namespace, file, dir) {
+    if (typeof namespace !== 'object' || namespace === null) {
+        return [];
+    }
+    const collected = [];
+    for (const exportName of Object.keys(namespace)) {
+        let value;
+        try {
+            value = namespace[exportName];
+        }
+        catch {
+            // A getter that throws is not a hook; the module's other exports stand.
+            continue;
+        }
+        if (isHookRegistration(value)) {
+            collected.push({
+                registration: value,
+                file,
+                dir,
+                exportName,
+                sequence: 0,
+            });
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const element of value) {
+                if (isHookRegistration(element)) {
+                    collected.push({
+                        registration: element,
+                        file,
+                        dir,
+                        exportName,
+                        sequence: 0,
+                    });
+                }
+            }
+        }
+    }
+    return collected;
+}
+/**
+ * jiti's module cache is Node's own `require.cache`, which is one object per
+ * process, so the loader can read it through any `require`.
+ */
+function moduleCache() {
+    return createRequire(import.meta.url).cache;
+}
+/**
+ * Forget every module one scan evaluated, so the next scan evaluates the
+ * files as they are then.
+ *
+ * The module cache is on for the scan's sake, not the process's: a hook file
+ * may be edited between two scans of one long-lived process — `thymian serve`
+ * dispatching `validate` after every save — and so may a module a hook file
+ * imports. Evicting exactly what the scan added, rather than what lies under
+ * the hooks directory, is what covers that second case, and it keeps the
+ * cache from growing by one scan's worth of entries per call. A registration
+ * already collected is unaffected: it is held by reference, and the cache
+ * entry was only ever the way to reach it.
+ */
+function evictScannedModules(cachedBefore) {
+    const cache = moduleCache();
+    for (const id of Object.keys(cache)) {
+        // An installed package is not edited between scans, and jiti's own
+        // transformer is among them: evicting it would re-load the transpiler
+        // on every scan for nothing.
+        if (!cachedBefore.has(id) && !/[\\/]node_modules[\\/]/.test(id)) {
+            delete cache[id];
+        }
+    }
+}
+/**
+ * Make every path jiti resolves under the hooks directory take ONE spelling,
+ * so a file is one module-cache entry however it was reached. Returns the
+ * function that undoes it.
+ *
+ * jiti keys its module cache by the path its resolver returns, and it has two
+ * resolvers that spell a path differently on Windows. A path that exists as
+ * written — every file the scan imports, `./shared.ts`, `./shared` — goes
+ * through exsolve and comes back with forward slashes. `./shared.js` naming a
+ * `.ts` file does not exist as written, so jiti rewrites it to `.ts` and asks
+ * Node's `require.resolve`, which answers with backslashes. `C:/…/shared.ts`
+ * and `C:\…\shared.ts` are two cache entries, so the file was evaluated twice:
+ * a re-exported hook was two objects, a re-exported `defineSample` a conflict
+ * with itself, and an import cycle re-entered its first file and created a
+ * hook nothing exported. On POSIX both spellings are the same string, which is
+ * why only Windows saw it.
+ *
+ * `Module._resolveFilename` is what `require.resolve` calls, so rewriting its
+ * answer to forward slashes aligns the second resolver with the first. It is
+ * scoped to the scan and to paths under `root`, so nothing else in the process
+ * resolves differently, and it is a no-op where the separator already is `/`.
+ */
+function unifyResolvedPathSpelling(root) {
+    if (sep === '/') {
+        return () => undefined;
+    }
+    // Private Node API, absent from the type declarations.
+    const internals = Module;
+    const original = internals._resolveFilename;
+    internals._resolveFilename = function (request, ...rest) {
+        const resolved = original.call(this, request, ...rest);
+        const fromRoot = relative(root, resolved);
+        return fromRoot.startsWith('..') || isAbsolute(fromRoot)
+            ? resolved
+            : resolved.replaceAll('\\', '/');
+    };
+    return () => {
+        internals._resolveFilename = original;
+    };
+}
+function emptyTransactionHooks() {
+    return {
+        defineSample: [],
+        beforeEach: [],
+        afterEach: [],
+        authorize: [],
+    };
+}
+/**
+ * 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 async function loadUserHooks(hooksDir, catalog) {
+    const diagnostics = [];
+    const conflicts = [];
+    const unexported = [];
+    const warnings = [];
+    const byTransactionId = new Map();
+    const runScoped = {
+        beforeAll: [],
+        afterAll: [],
+    };
+    const globalAuthorize = [];
+    if (!(await entryExists(hooksDir))) {
+        return {
+            files: [],
+            byTransactionId,
+            runScoped,
+            globalAuthorize,
+            diagnostics,
+            conflicts,
+            unexported,
+            warnings,
+        };
+    }
+    // The REAL path, because the module cache is keyed by what jiti resolves an
+    // import to, and jiti resolves through symlinks. Handed a path with a
+    // symlink in it — macOS's `/var` is one onto `/private/var` — the file the
+    // scan imports and the same file reached through `./shared.js` were two
+    // cache entries, evaluated twice, and the re-export was two objects again.
+    const root = await realpath(hooksDir);
+    const found = [];
+    await walkHookDirectory(root, root, true, found, warnings);
+    const files = found
+        .map((full) => ({ full, key: hooksDirRelative(root, full) }))
+        .sort((a, b) => compareKeys(a.key, b.key));
+    const jiti = createJiti(hooksRuntimeModule, {
+        alias: { [HOOKS_RUNTIME_SPECIFIER]: hooksRuntimeModule },
+        // A hook file is user code that may have been edited between runs, and a
+        // run is short-lived: nothing is gained by caching its transpilation, and a
+        // stale entry would be served silently.
+        fsCache: false,
+        // Cached for the span of ONE scan — see `evictScannedModules`. With the
+        // cache off, a module two hook files import was evaluated once per
+        // importer, so a re-exported hook was a different object per exporting
+        // file: bound twice, and a re-exported `defineSample` a conflict with
+        // itself. A re-export is the same binding in ESM; caching for the scan
+        // makes it the same object here too, which is what lets `collected` be
+        // deduplicated by identity below without touching the conflict check
+        // — two genuinely distinct hooks remain two objects.
+        moduleCache: true,
+    });
+    const collected = [];
+    // Emptied per scan, so what it holds is this scan's registrations and the
+    // slice taken after each import is that file's.
+    const created = createdRegistrations();
+    const createdPerFile = [];
+    const exported = new Set();
+    const cachedBefore = new Set(Object.keys(moduleCache()));
+    created.length = 0;
+    const restoreResolution = unifyResolvedPathSpelling(root);
+    try {
+        for (const { full, key } of files) {
+            const createdBefore = created.length;
+            let namespace;
+            try {
+                namespace = await jiti.import(full);
+            }
+            catch (error) {
+                throw hookFileImportError(key, error);
+            }
+            // Registration order **within the file**, not export order: an ESM
+            // namespace exposes its keys sorted, so `order` is the only thing that
+            // knows which hook the file created first.
+            //
+            // Sorted per file rather than once at the end: `order` is stamped by the
+            // hooks runtime at creation, and a hook created in a shared module is
+            // created when the FIRST importer is evaluated, so a global sort by
+            // `order` would interleave the files. File order is the outer key and
+            // it is already deterministic; `order` only has to sequence what one
+            // file exports.
+            const fromFile = collectFromNamespace(namespace, key, dirname(full)).sort((a, b) => a.registration.order - b.registration.order);
+            createdPerFile.push({ file: key, created: created.slice(createdBefore) });
+            for (const entry of fromFile) {
+                // One hook, however many files re-export it. The first exporting file
+                // in load order is the one it is attributed to.
+                if (exported.has(entry.registration)) {
+                    continue;
+                }
+                exported.add(entry.registration);
+                collected.push(entry);
+            }
+        }
+    }
+    finally {
+        restoreResolution();
+        evictScannedModules(cachedBefore);
+    }
+    // A hook created and never exported is unreachable: discovery is
+    // export-based, so it never fires, and a hook that never fires looks exactly
+    // like one with nothing to do. It was the only failure here that was silent.
+    //
+    // Checked only once every file has been scanned, because a hook created in a
+    // shared module is created when the first file that IMPORTS it is evaluated
+    // — accusing that file would fail a run over a hook that another file
+    // exports and that does fire.
+    for (const { file, created: createdHere } of createdPerFile) {
+        for (const registration of createdHere) {
+            if (exported.has(registration)) {
+                continue;
+            }
+            unexported.push({
+                file,
+                reason: `a ${registration.kind} hook was created here but never exported, so nothing can reach it`,
+                suggestions: [
+                    `Assign it to an export, as in: export const shape = ${registration.kind}(...)`,
+                ],
+            });
+        }
+    }
+    // One number ordering every hook in the run against every other. Assigned
+    // here, once the file-then-registration order is settled, because that is the
+    // only place both halves are known.
+    collected.forEach((entry, index) => {
+        entry.sequence = index;
+    });
+    for (const entry of collected) {
+        const { registration } = entry;
+        if (registration.kind === 'beforeAll' || registration.kind === 'afterAll') {
+            runScoped[registration.kind].push(entry);
+            continue;
+        }
+        if (registration.kind === 'authorize' &&
+            registration.target === undefined) {
+            globalAuthorize.push(entry);
+            continue;
+        }
+        const targeted = resolveTargeting(registration.kind, registration.target, entry, catalog, diagnostics);
+        for (const transaction of targeted) {
+            let hooks = byTransactionId.get(transaction.transactionId);
+            if (!hooks) {
+                hooks = emptyTransactionHooks();
+                byTransactionId.set(transaction.transactionId, hooks);
+            }
+            // `defineSample` is set-once per Transaction. A second one is a conflict
+            // rather than a last-wins override, and it is reported at load time —
+            // not when that Transaction happens to be sampled — because the mistake
+            // exists whether or not the run reaches it.
+            const conflicting = hooks.defineSample[0];
+            if (registration.kind === 'defineSample' && conflicting) {
+                conflicts.push({
+                    file: entry.file,
+                    exportName: entry.exportName,
+                    reason: `defineSample is already defined for the selector "${catalog.selectorFor(transaction.transactionId) ?? transaction.transactionId}" by "${conflicting.exportName}" in ${conflicting.file}; a Transaction can have only one`,
+                    suggestions: [
+                        'Merge the two into one defineSample, or target a different selector.',
+                    ],
+                });
+                continue;
+            }
+            // Two authorize hooks in the same tier on one Transaction: the later one
+            // wins, which is what lets a file override an earlier one — but silently
+            // dropping a set of credentials is worth a word, since a reader who just
+            // met the `defineSample` conflict will expect one.
+            const supersededAuthorize = registration.kind === 'authorize' ? hooks.authorize.at(-1) : undefined;
+            if (supersededAuthorize) {
+                warnings.push(`Two authorize hooks target the same transaction: "${entry.exportName}" in ${entry.file} supersedes "${supersededAuthorize.exportName}" in ${supersededAuthorize.file}. Only the last one runs.`);
+            }
+            hooks[registration.kind].push(entry);
+        }
+    }
+    return {
+        files: files.map(({ key }) => key),
+        byTransactionId,
+        runScoped,
+        globalAuthorize,
+        diagnostics,
+        conflicts,
+        unexported,
+        warnings,
+    };
+}
+//# sourceMappingURL=load-user-hooks.js.map

package/dist/hooks/load-user-hooks.js.map

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

package/dist/hooks/nested-request.d.ts

@@ -0,0 +1,21 @@
+import { ThymianBaseError } from '@thymian/core';
+import type { Selector } from '../selectors/selector.js';
+/**
+ * The Selectors whose pipelines are currently on the stack.
+ *
+ * Travels with the hook context rather than living in the runner, because that
+ * is what makes the guard reflect *this* call's ancestry instead of whatever
+ * the runner happened to be doing last.
+ */
+export type SelectorChain = readonly Selector[];
+/**
+ * A seeding call has re-entered a Transaction already on the stack.
+ *
+ * Printing the chain is the whole point: `A → B → A` is a mistake three files
+ * apart, and the middle of the cycle is where the fix goes. Without it the run
+ * would recurse until the stack gave out, and a stack overflow names nothing.
+ */
+export declare function requestCycleError(chain: SelectorChain, selector: Selector): ThymianBaseError;
+/** Whether `selector` is already on `chain`. */
+export declare function isOnChain(chain: SelectorChain, selector: Selector): boolean;
+//# sourceMappingURL=nested-request.d.ts.map

package/dist/hooks/nested-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-request.d.ts","sourceRoot":"","sources":["../../src/hooks/nested-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,QAAQ,EAAE,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAclB;AAED,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAE3E"}

package/dist/hooks/nested-request.js

@@ -0,0 +1,24 @@
+import { ThymianBaseError } from '@thymian/core';
+/**
+ * A seeding call has re-entered a Transaction already on the stack.
+ *
+ * Printing the chain is the whole point: `A → B → A` is a mistake three files
+ * apart, and the middle of the cycle is where the fix goes. Without it the run
+ * would recurse until the stack gave out, and a stack overflow names nothing.
+ */
+export function requestCycleError(chain, selector) {
+    const path = [...chain, selector].map((entry) => `"${entry}"`).join('\n  → ');
+    return new ThymianBaseError(`A cross-endpoint request would re-enter "${selector}", which is already running.`, {
+        name: 'RequestCycleError',
+        ref: 'https://thymian.dev/references/errors/request-cycle-error/',
+        suggestions: [
+            `The chain is:\n  ${path}`,
+            'Break the cycle, or pass `{ runHooks: false }` to seed from the raw request without running the target’s hooks.',
+        ],
+    });
+}
+/** Whether `selector` is already on `chain`. */
+export function isOnChain(chain, selector) {
+    return chain.includes(selector);
+}
+//# sourceMappingURL=nested-request.js.map

package/dist/hooks/nested-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-request.js","sourceRoot":"","sources":["../../src/hooks/nested-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAajD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAoB,EACpB,QAAkB;IAElB,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE9E,OAAO,IAAI,gBAAgB,CACzB,4CAA4C,QAAQ,8BAA8B,EAClF;QACE,IAAI,EAAE,mBAAmB;QACzB,GAAG,EAAE,4DAA4D;QACjE,WAAW,EAAE;YACX,oBAAoB,IAAI,EAAE;YAC1B,iHAAiH;SAClH;KACF,CACF,CAAC;AACJ,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,SAAS,CAAC,KAAoB,EAAE,QAAkB;IAChE,OAAO,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/hooks/overlay-args.d.ts

@@ -0,0 +1,40 @@
+import type { HttpRequestTemplate } from '@thymian/core';
+import type { EndpointRequest } from './hook-utils.js';
+/**
+ * Overlays a caller's arguments onto a generated request.
+ *
+ * The generated sample plus the target's own hooks already produce a complete,
+ * schema-satisfying request. Arguments are therefore an **overlay**, not a
+ * replacement: a seeding call states the one field that has to differ — a name
+ * it will assert on later, an id it just created — and inherits everything
+ * else. Requiring the whole request instead made the caller re-state a body
+ * the description had already described.
+ *
+ * Parameter groups merge per key. The body deep-merges (see
+ * {@link deepMergeBody}).
+ */
+export declare function applyArgs(template: HttpRequestTemplate, args: EndpointRequest): HttpRequestTemplate;
+/**
+ * Merges an overlay body onto the generated one: **objects recurse, arrays and
+ * primitives replace, `null` overrides.**
+ *
+ * Arrays replace rather than merge because a positional merge needs an index
+ * the caller cannot know is stable, and a per-element merge would produce
+ * elements the schema never described. `null` overrides for the same reason it
+ * is not "absent": a description that allows `null` means it, and merging
+ * around it would make the one value you cannot express the one you meant.
+ *
+ * Written here rather than taken from a library so that the rule the generated
+ * `DeepPartial` types promise and the rule the runtime applies are the same
+ * three sentences, in one place.
+ *
+ * Every key is handled as an **own property**, never through `in` or a bare
+ * `[key] =` assignment. `key in base` is true for `'toString'` on a base that
+ * never declared it — it walks the prototype chain — and `merged[key] = …`
+ * for `key === '__proto__'` does not create a data property at all: it
+ * invokes the inherited setter and repoints `merged`'s own prototype. Neither
+ * is a filter field's schema value; a body field named `__proto__` is exactly
+ * as ordinary as one named anything else, and this is what makes it one.
+ */
+export declare function deepMergeBody(base: unknown, overlay: unknown): unknown;
+//# sourceMappingURL=overlay-args.d.ts.map

package/dist/hooks/overlay-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-args.d.ts","sourceRoot":"","sources":["../../src/hooks/overlay-args.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,EAAE,eAAe,GACpB,mBAAmB,CAerB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAsBtE"}

package/dist/hooks/overlay-args.js

@@ -0,0 +1,84 @@
+/**
+ * Overlays a caller's arguments onto a generated request.
+ *
+ * The generated sample plus the target's own hooks already produce a complete,
+ * schema-satisfying request. Arguments are therefore an **overlay**, not a
+ * replacement: a seeding call states the one field that has to differ — a name
+ * it will assert on later, an id it just created — and inherits everything
+ * else. Requiring the whole request instead made the caller re-state a body
+ * the description had already described.
+ *
+ * Parameter groups merge per key. The body deep-merges (see
+ * {@link deepMergeBody}).
+ */
+export function applyArgs(template, args) {
+    return {
+        ...template,
+        headers: { ...template.headers, ...args.headers },
+        query: { ...template.query, ...args.query },
+        cookies: { ...template.cookies, ...args.cookies },
+        pathParameters: { ...template.pathParameters, ...args.path },
+        // `Object.hasOwn`, never `in`: `in` walks the prototype chain, so an args
+        // object inheriting a `body` — from `Object.prototype` being polluted, or
+        // from a caller's own base object — would overlay a body the caller never
+        // passed.
+        ...(Object.hasOwn(args, 'body')
+            ? { body: deepMergeBody(template.body, args.body) }
+            : {}),
+    };
+}
+/**
+ * Merges an overlay body onto the generated one: **objects recurse, arrays and
+ * primitives replace, `null` overrides.**
+ *
+ * Arrays replace rather than merge because a positional merge needs an index
+ * the caller cannot know is stable, and a per-element merge would produce
+ * elements the schema never described. `null` overrides for the same reason it
+ * is not "absent": a description that allows `null` means it, and merging
+ * around it would make the one value you cannot express the one you meant.
+ *
+ * Written here rather than taken from a library so that the rule the generated
+ * `DeepPartial` types promise and the rule the runtime applies are the same
+ * three sentences, in one place.
+ *
+ * Every key is handled as an **own property**, never through `in` or a bare
+ * `[key] =` assignment. `key in base` is true for `'toString'` on a base that
+ * never declared it — it walks the prototype chain — and `merged[key] = …`
+ * for `key === '__proto__'` does not create a data property at all: it
+ * invokes the inherited setter and repoints `merged`'s own prototype. Neither
+ * is a filter field's schema value; a body field named `__proto__` is exactly
+ * as ordinary as one named anything else, and this is what makes it one.
+ */
+export function deepMergeBody(base, overlay) {
+    if (!isPlainObject(base) || !isPlainObject(overlay)) {
+        return overlay;
+    }
+    const merged = { ...base };
+    for (const key of Object.keys(overlay)) {
+        const value = overlay[key];
+        const next = Object.prototype.hasOwnProperty.call(base, key)
+            ? deepMergeBody(base[key], value)
+            : value;
+        Object.defineProperty(merged, key, {
+            value: next,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return merged;
+}
+/**
+ * A JSON object, and nothing that merely looks like one.
+ *
+ * `null`, arrays, `Buffer`s and dates all answer `'object'` to `typeof`, and
+ * every one of them is a value the caller means to replace whole.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=overlay-args.js.map

package/dist/hooks/overlay-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-args.js","sourceRoot":"","sources":["../../src/hooks/overlay-args.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACvB,QAA6B,EAC7B,IAAqB;IAErB,OAAO;QACL,GAAG,QAAQ;QACX,OAAO,EAAE,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;QACjD,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE;QAC3C,OAAO,EAAE,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;QACjD,cAAc,EAAE,EAAE,GAAG,QAAQ,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE;QAC5D,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,UAAU;QACV,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;YAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,OAAgB;IAC3D,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IAEpD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC;YAC1D,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;YACjC,CAAC,CAAC,KAAK,CAAC;QAEV,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE;YACjC,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;IAE1D,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC"}

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

@@ -0,0 +1,16 @@
+import type { ThymianHttpTransaction } from '@thymian/core';
+import type { TransactionCatalog } from '../selectors/transaction-catalog.js';
+import type { HookDiagnostic } from './hook-diagnostics.js';
+import type { CollectedRegistration } from './load-user-hooks.js';
+/**
+ * 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 declare function resolveTargeting(kind: string, target: unknown, entry: CollectedRegistration, catalog: TransactionCatalog, diagnostics: HookDiagnostic[]): readonly ThymianHttpTransaction[];
+//# sourceMappingURL=resolve-targeting.d.ts.map