meocord 4.2.0 → 4.2.2

package/dist/esm/testing/meocord-testing-module.js

@@ -6,7 +6,7 @@ import { ReactionHandlerAction } from '../enum/controller.enum.js';
 import { CooldownStore, MemoryCooldownStore } from '../common/cooldown-store.js';
 import { ExecutionContext } from '../common/execution-context.js';
 import { Translator, missingTranslatorError } from '../common/translator.js';
-import { injectedTokens, singletonContextError } from '../core/guard-runner.js';
+import { injectedTokens, singletonContextError, recordInstanceContainers } from '../core/guard-runner.js';
 import { appPresenterOf, runHandler, appStages, bindGlobalStages, prepareHandlerStages, prepareAppPresenter, prepareThemes, bindAppPresenter } from '../core/handler-pipeline.js';
 import { setPresenter } from '../common/response/presenter.js';
 import { componentRouteFor, commandMismatch, handlerInput } from '../core/handler-input.js';
@@ -23,21 +23,25 @@ import { messageCommandHooks } from '../core/message-params.js';
 import { appObservers, assertObservers, bindObservers } from '../core/observer-runner.js';
 import { HandlerRegistry } from '../core/handler-registry.js';
 import { adviseInPlaceOfInjecting, meocordClasses } from '../core/meocord-classes.js';
-import { startupClasses, assertStartupClasses, lateGuardCheck } from '../core/startup-roots.js';
+import { startupClasses, assertStartupClasses, lateGuardCheck, stageDependencies } from '../core/startup-roots.js';
 import { markStartupChecked, assertStartupChecked } from '../core/startup-checked.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { ShardContext, shardCallHandler } from '../core/shard-context.js';
 import { isAppClassToken } from '../core/lifecycle-order.js';
-import { lifecycleEntry, runShutdownSequence, runReadyHooks, callsSettled } from '../core/lifecycle-hooks.js';
-import { createMockClient } from './mock-interaction.js';
+import { runShutdownSequence, runReadyHooks, ReadyPass, lifecycleEntry, callsSettled } from '../core/lifecycle-hooks.js';
+import { createMockClient, noteReactionDispatch } from './mock-interaction.js';
 import { Dispatcher } from '../core/dispatcher.js';
 import { createFallback } from '../core/fallback.js';
 import { Logger } from '../common/logger.js';
 import { isExplainedError, markExplained } from '../common/explained-error.js';
-import { declaredErrorsOf, collectStartupErrors, startupError, stopOnStartupErrors, isRefusal, logStartupErrors } from '../util/refusal.util.js';
+import { collectStartupErrors, declaredErrorsOf, startupError, stopOnStartupErrors, isRefusal, logStartupErrors } from '../util/refusal.util.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, shutdownTimeoutProblem } from '../util/shutdown-timeout.util.js';
-import { resolveProviders, tokenName, bindsOwnToken, providerMap, bindProvider, resolutionOrder, isClassProvider, assertProvided, tokenDependencies } from '../core/providers.js';
+import { isConstructor, describeValue } from '../util/value.util.js';
+import { resolveProviders, tokenName, bindsOwnToken, providerMap, assertProvidedServices, bindProvider, resolutionOrder, isClassProvider, assertProvided, tokenDependencies } from '../core/providers.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
+import { getReactionHandlers } from '../decorator/controller.decorator.js';
+import { strictMocks } from './strict-mocks.js';
+import { warnOnce } from '../common/deprecation.js';
 import { META } from '../util/metadata-keys.js';
 import { isUserOutcome } from '../common/user-outcome.js';
 
@@ -110,7 +114,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
         await this.resolving;
         if (options.ready) {
             const { client = createMockClient(), primary = true } = options.ready === true ? {} : options.ready;
-            this.readying ?? (this.readying = this.runReady(client, primary));
+            this.readying ?? (this.readying = this.readyPass.run(()=>this.runReady(client, primary)));
             await this.readying;
         }
         return this;
@@ -125,12 +129,21 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * It first gives up the theme read outside calls, if `init({ ready: true })` made it this module's;
    * reads outside calls then return MeoCord's defaults until another module or app is ready.
    *
+   * A stopped bot runs nothing more. Once `close()` is called, a module still runs what `dispatch`, `invoke` and `emit`
+   * are given, against services shut down, or shutting down, and warns once that it is closed, so a `close()` in the
+   * wrong place shows.
+   *
    * The cooldown store and what it injects shut down last, in the same sequence as the bot's. When any of them has an
    * `onShutdown`, the calls `invoke`, `dispatch` and `emit` have under way finish first, then the store operations
    * they started, so the store's last writes still reach it. The module stops waiting for the whole sequence after
    * its `shutdownTimeout`, 10 seconds unless set, and logs that it did. Give a test whose fake store never answers, or
    * whose `onShutdown` never settles, a short `shutdownTimeout`.
    *
+   * A `close()` while `init({ ready: true })` runs the `onReady` hooks waits for them first, within the same
+   * `shutdownTimeout`. An `onReady` still running once only the hooks' share of it is left is named in a warning, and
+   * its class is shut down all the same, as everything the module constructed is. One that calls `close()` itself isn't
+   * waited for.
+   *
    * @returns Once every hook has run. Rejects with the error of a hook that failed, or an
    *   `AggregateError` naming each when several did.
    *
@@ -145,14 +158,18 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(module.get(POOL).ended).toBe(true)
    * ```
    */ async close() {
+        // An onReady awaiting close() would otherwise hold up the close that waits for it
+        this.readyPass.excuseCurrent();
         this.closing ?? (this.closing = (async ()=>{
-            // A close during init waits for the hooks it started, so it shuts down whatever they constructed
-            await this.readying?.catch(()=>undefined);
-            const entries = this.lifecycle.filter((unit)=>this.constructed.has(unit.token))// Already made, so this returns the instance; a provided value may be anything, null included
-            .map((unit)=>lifecycleEntry(unit, this.container.get(unit.token) ?? {}));
+            // A close during init waits for the providers it started, and the sequence for its onReady hooks, so it shuts
+            // down whatever they constructed
+            await this.resolving?.catch(()=>undefined);
+            const entries = ()=>this.lifecycle.filter((unit)=>this.constructed.has(unit.token))// Already made, so this returns the instance; a provided value may be anything, null included
+                .map((unit)=>lifecycleEntry(unit, this.container.get(unit.token) ?? {}));
             const failures = [];
             await runShutdownSequence(this.container, entries, {
                 drainCalls: ()=>callsSettled(this.calls),
+                readyPass: this.readyPass,
                 timeoutMs: this.shutdownTimeout,
                 hookFailed: (name, error)=>failures.push({
                         name,
@@ -166,6 +183,11 @@ import { isUserOutcome } from '../common/user-outcome.js';
         })());
         await this.closing;
     }
+    /** Warns once, after `close()`, that a call runs against services already shut down. */ warnIfClosed() {
+        if (this.closing === undefined || this.warnedClosed) return;
+        this.warnedClosed = true;
+        new Logger('TestingModule').warn('This testing module is closed, and its services are shut down, or shutting down, so dispatch, invoke and emit run ' + 'against that state. Close it after the last call, in afterEach.');
+    }
     async runReady(client, primary) {
         // As the bot claims it before it comes online, so onReady reads the app's theme
         claimAmbientAppTheme(this.container);
@@ -181,6 +203,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
         }, [], {
             resolveFailed: failed,
             hookFailed: failed
+        }, {
+            runOnReady: this.readyPass.runOnReady
         });
         throwFailures('onReady', failures);
     }
@@ -252,7 +276,9 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * @returns Whether the handler ran, and the error a filter handled, if any. Rejects with an error no
    *   filter handles, or with the error a filter throws: the built-in fallback, which answers such
    *   errors in the bot, does not run here. Rejects before running anything with an interaction or a
-   *   message the handler's route does not match, naming both.
+   *   message the handler's route does not match, naming both. Given fewer arguments than the handler
+   *   declares, with a first that is neither an interaction nor a message, such as a reaction without its
+   *   `ReactionEvent`, it rejects under `useStrictMocks()`, and otherwise warns once and runs the handler.
    *
    * @example
    * ```ts
@@ -274,6 +300,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(outcome.error).toBeInstanceOf(GuardDeniedError)
    * ```
    */ async invoke(controller, methodName, ...args) {
+        this.warnIfClosed();
         await this.init();
         if (!this.controllers.includes(controller)) {
             throw new Error(`${controller.name} is not a controller of this testing module. Add it to \`controllers\`.`);
@@ -303,6 +330,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 hooks = messageCommandHooks(route, params, first, start, given, this.messageOptions.types);
             }
         }
+        this.checkArgumentCount(controller, methodName, instance[methodName], first, callArgs.length);
         const presenter = appPresenterOf(this.container);
         // A message command's errors are drawn by the app's presenter too, as an interaction's are
         const client = first instanceof BaseInteraction || first instanceof Message ? first.client : undefined;
@@ -319,6 +347,19 @@ import { isUserOutcome } from '../common/user-outcome.js';
             error
         };
     }
+    /**
+   * Refuses under `useStrictMocks()`, or warns once otherwise, a call that gives a handler fewer arguments than it
+   * declares when `invoke` builds none for it, as for a reaction given without its `ReactionEvent`.
+   */ checkArgumentCount(controller, methodName, method, first, given) {
+        if (first instanceof BaseInteraction || first instanceof Message || method.length <= given) return;
+        const reaction = getReactionHandlers(controller.prototype).some((handler)=>handler.method === methodName);
+        const problem = `${controller.name}.${methodName} takes ${method.length} arguments, and invoke was given ${given}: ` + (reaction ? 'pass its ReactionEvent after the reaction, as { user, action }.' : 'pass each argument it takes.');
+        if (strictMocks()) throw new Error(problem);
+        const key = `${controller.name}.${methodName}`;
+        if (this.warnedArgumentCounts.has(key)) return;
+        this.warnedArgumentCounts.add(key);
+        new Logger('TestingModule').warn(problem);
+    }
     /** Counts `call` as under way until it settles. */ track(call) {
         this.calls.add(call);
         void call.then(()=>this.calls.delete(call), ()=>this.calls.delete(call));
@@ -364,6 +405,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
         return this.dispatcher;
     }
     async dispatch(input, options) {
+        this.warnIfClosed();
         await this.init();
         this.registerClient(input);
         const dispatcher = this.dispatcherOf();
@@ -381,6 +423,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
             unhandled: (error)=>unhandled.push(error)
         };
         if (options) {
+            noteReactionDispatch(input);
             await this.track(dispatcher.reaction(input, {
                 user: options.user,
                 action: options.action ?? ReactionHandlerAction.ADD
@@ -410,15 +453,20 @@ import { isUserOutcome } from '../common/user-outcome.js';
         };
     }
     /**
-   * Emits a client event to the module's `@On` and `@Once` handlers, through the same pipeline the app
-   * runs them in: the global guards of the module's `app`, then each handler's own. Handlers on the
-   * module's controllers, class providers and their dependencies all receive it. A `@Once` handler
-   * handles only the first event, as it would on a client.
+   * Emits a client event to the module's `@On` and `@Once` handlers, through the pipeline the app runs
+   * them in up to its event fallback: the global guards of the module's `app`, then each handler's own.
+   * Handlers on the module's controllers, class providers and their dependencies all receive it. A
+   * `@Once` handler handles only the first event, as it would on a client.
+   *
+   * The bot's event fallback doesn't run here. On a bot, a guard's `GuardDeniedError` is logged and the
+   * event skipped, and a handler's `UserError` is logged and, when the event carries a message, answered
+   * as a reply to it; here both reject `emit` as any error does, so a test checks them with `rejects`.
    *
    * @param event - The client event, such as `'guildMemberAdd'`.
    * @param args - The event's arguments, typed from discord.js's `ClientEvents`.
-   * @returns How many handlers ran. Rejects once every handler has settled if any threw: with that
-   *   error when one handler failed, or an `AggregateError` of them when several did.
+   * @returns How many handlers ran. Rejects once every handler has settled if any threw, a guard's
+   *   `GuardDeniedError` and a handler's `UserError` included: with that error when one handler failed,
+   *   or an `AggregateError` of them when several did.
    *
    * @example
    * ```ts
@@ -430,6 +478,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(ran).toBe(1)
    * ```
    */ async emit(event, ...args) {
+        this.warnIfClosed();
         await this.init();
         const calls = [];
         for (const cls of this.eventClasses){
@@ -474,7 +523,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
         this.appWarnUnanswered = appWarnUnanswered;
         this.services = services;
         this.shutdownTimeout = shutdownTimeout;
+        /** The `onReady` hooks' pass, which `close()` waits for, less one whose `onReady` called `close()`. */ this.readyPass = new ReadyPass();
+        this.warnedClosed = false;
         /** The `@Once` handlers that have already handled their event, as a client forgets its once listeners. */ this.firedOnce = new Set();
+        /** The handlers already warned about for being given fewer arguments than they take, so each is named once. */ this.warnedArgumentCounts = new Set();
         /** The calls under way, each removed once it settles: what `close()` lets finish before the cooldown store stops. */ this.calls = new Set();
     }
 }
@@ -539,6 +591,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
     /**
    * Replaces a guard with a stub wherever it applies, globally or on a controller or handler.
    *
+   * It stands in for the guard wherever the guard is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. The stub needs a `canActivate`, its own or its prototype's: `compile()` refuses one without
+   * it under `useStrictMocks()`, and otherwise warns.
+   *
    * @param guard - The guard class to replace.
    * @example
    * ```ts
@@ -556,6 +612,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * Replaces an interceptor with a stub wherever it applies, globally or on a controller or handler.
    * The stub's `intercept` receives the context and `next`; call `next.handle()` to run the handler.
    *
+   * It stands in for the interceptor wherever it is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. A stub without `intercept` is refused by `compile()` under `useStrictMocks()`, and
+   * otherwise warned about.
+   *
    * @param interceptor - The interceptor class to replace.
    * @example
    * ```ts
@@ -573,6 +633,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * Replaces an exception filter with a stub wherever it applies. The filter's `@Catch` still decides
    * which errors reach the stub.
    *
+   * It stands in for the filter wherever it is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. A stub without `catch` is refused by `compile()` under `useStrictMocks()`, and otherwise
+   * warned about.
+   *
    * @param filter - The filter class to replace.
    * @example
    * ```ts
@@ -705,9 +769,52 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 const providers = providerMap(this.wiring?.providers ?? [], '@MeoCord({ providers })');
                 for (const [token, provider] of providerMap(this.options.providers ?? [], "the testing module's providers"))providers.set(token, provider);
                 for (const [token, override] of this.overrides)providers.set(token, override);
+                // A stage override stands in for its class wherever the class is bound. A stage also provided takes the stub in
+                // place of its provider, one binding per token, and runs lifecycle hooks as that provider would; any other is
+                // bound on its own below, as the bot never makes a lifecycle unit of it. A stub that can't run is named here
+                const stageStubs = new Map();
+                for (const [method, overrides, kind] of [
+                    [
+                        'canActivate',
+                        this.guardOverrides,
+                        'overrideGuard'
+                    ],
+                    [
+                        'intercept',
+                        this.interceptorOverrides,
+                        'overrideInterceptor'
+                    ],
+                    [
+                        'catch',
+                        this.filterOverrides,
+                        'overrideFilter'
+                    ]
+                ]){
+                    for (const [stage, stub] of overrides){
+                        if (providers.has(stage)) providers.set(stage, {
+                            provide: stage,
+                            useValue: stub
+                        });
+                        else stageStubs.set(stage, stub);
+                        if (typeof stub[method] === 'function') continue;
+                        const problem = `${kind}(${stage.name}).useValue(…) has no ${method} method.`;
+                        if (strictMocks()) startupError(new Error(problem));
+                        else warnOnce(new Logger('TestingModule'), `${problem} A call that reaches ${stage.name} fails; useStrictMocks() refuses it here.`);
+                    }
+                }
                 // Each pass of checks ends before the next step that is no check, so a module with one error stops where it always did
                 stopOnStartupErrors();
+                // What the walk below takes as classes, reported with what the walk finds; an entry refused here is left out of it
                 const services = this.wiring?.services ?? [];
+                if (this.options.app) assertProvidedServices(this.options.app.name, services, providers, "@MeoCord({ providers }) or the testing module's providers");
+                for (const controller of this.options.controllers ?? []){
+                    if (!isConstructor(controller)) startupError(new Error(`the testing module's controllers takes classes, not ${describeValue(controller)}.`));
+                }
+                const observers = [
+                    ...this.options.app ? appObservers(this.options.app) : [],
+                    ...this.options.observers ?? []
+                ];
+                assertObservers("the testing module's observers", observers);
                 const appOptions = this.options.app ? Reflect.getMetadata(META.appOptions, this.options.app) : undefined;
                 // The app's own store, as the bot binds it, whether the module is given the app or built from it; none when the
                 // test provides the CooldownStore, so nothing builds the app's or asks for what it injects
@@ -716,18 +823,16 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 const themeResolver = themeResolverClass(stages?.themeFor?.resolvers);
                 // Every class the module runs, as the app finds them, except stage classes an override stands in for
                 const i18n = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.i18n;
+                const appPresenterClass = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter;
                 const startup = startupClasses({
-                    controllers: this.options.controllers ?? [],
+                    controllers: (this.options.controllers ?? []).filter(isConstructor),
                     services,
                     providers,
                     stages,
-                    presenter: this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter,
+                    presenter: appPresenterClass,
                     cooldownStore: store,
                     themeFor: stages?.themeFor?.resolvers,
-                    observers: [
-                        ...this.options.app ? appObservers(this.options.app) : [],
-                        ...this.options.observers ?? []
-                    ],
+                    observers,
                     stubs: [
                         ...this.guardOverrides.keys(),
                         ...this.interceptorOverrides.keys(),
@@ -752,16 +857,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
                         throw new Error(`${needClient.map((cls)=>cls.name).join(', ')} ${needClient.length === 1 ? 'injects' : 'inject'} the Discord Client, ` + 'which a testing module does not make: give one in its providers, such as ' + '{ provide: Client, useValue: createMockClient() }.');
                     });
                 }
-                // Bind guard overrides — prevents inversify from auto-wiring guard dependencies
-                for (const [guardClass, stub] of this.guardOverrides){
-                    container.bind(guardClass).toConstantValue(stub);
-                }
-                for (const [filterClass, stub] of this.filterOverrides){
-                    container.bind(filterClass).toConstantValue(stub);
-                }
-                for (const [interceptorClass, stub] of this.interceptorOverrides){
-                    container.bind(interceptorClass).toConstantValue(stub);
-                }
+                // A stage override nothing provides, bound before the classes so none of them binds the stage itself
+                for (const [stage, stub] of stageStubs)container.bind(stage).toConstantValue(stub);
                 // The app's cooldown policy, so a test of a failing store sees what the bot would do
                 if (appOptions && !container.isBound(COOLDOWN_POLICY)) container.bind(COOLDOWN_POLICY).toConstantValue(cooldownPolicyFrom(appOptions));
                 // The app's translator, unless a provider stands in for it
@@ -825,16 +922,12 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 // As the app does when it is created, so a test sees the refusal the bot would give
                 assertDistinctCommands(this.options.controllers ?? []);
                 if (this.options.app) prepareAppPresenter(container, this.options.app);
-                const observers = [
-                    ...this.options.app ? appObservers(this.options.app) : [],
-                    ...this.options.observers ?? []
-                ];
-                assertObservers("the testing module's observers", observers);
-                // Only @Observer classes are bound as observers
-                stopOnStartupErrors();
                 bindObservers(container, observers);
                 // The store calls ask: the test's own when it provides CooldownStore, else the app's
                 const boundStore = store ?? (providers.has(CooldownStore) ? CooldownStore : undefined);
+                // What the stages and presenter inject, as the bot makes it; a stage the test replaced contributes nothing
+                const stageServices = stageDependencies(startup, providers, appPresenterClass);
+                for (const service of stageServices)bindClass(service);
                 // The order the app runs lifecycle hooks in: its cooldown store, then providers, controllers and observers, each
                 // after what it injects
                 const lifecycle = resolutionOrder(container, providers, [
@@ -843,6 +936,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
                     ] : [],
                     ...providers.keys(),
                     ...services,
+                    ...stageServices,
                     ...themeResolver ? [
                         themeResolver
                     ] : [],
@@ -863,6 +957,11 @@ import { isUserOutcome } from '../common/user-outcome.js';
                     ...this.options.controllers ?? [],
                     ...startup.classes
                 ])Reflect.defineMetadata(META.container, container, cls);
+                // And each instance with the module that made it, as another module made from the same classes stamps them again
+                recordInstanceContainers(container, [
+                    ...this.options.controllers ?? [],
+                    ...startup.classes
+                ]);
                 prepareThemes(container, appClasses);
                 // A handler with no builder is how a fixture is written, so only what is always a mistake is named
                 warnUnregisteredCommands(this.options.controllers ?? [], {
@@ -936,7 +1035,15 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * @param options - The controllers, providers, observers and app the module is built from.
    * @returns The builder, to override what the test replaces before `compile()`.
    */ static create(options) {
-        return new TestingModuleBuilder(options);
+        // A controller listed twice is one controller, as the bot and fromApp take it
+        return new TestingModuleBuilder({
+            ...options,
+            ...options.controllers && {
+                controllers: [
+                    ...new Set(options.controllers)
+                ]
+            }
+        });
     }
     /**
    * Starts building a testing module from a whole `@MeoCord` app, wired as the bot wires it.
@@ -954,7 +1061,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * @param app - The class `@MeoCord` decorates.
    * @param options - Providers that replace the app's by token, extra controllers, and observers.
    * @returns The builder, whose `override*` methods still apply, for `compile()`.
-   * @throws TypeError when `app` is not a `@MeoCord` class.
+   * @throws TypeError when `app` is not a `@MeoCord` class. After {@link reportAllStartupErrors}, an app whose
+   *   `@MeoCord` was refused throws the error it was refused for instead.
    *
    * @example
    * ```ts
@@ -995,7 +1103,13 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * ```
    */ static fromApp(app, options = {}) {
         const appOptions = Reflect.getMetadata(META.appOptions, app);
-        if (!appOptions) throw new TypeError(`${app?.name ?? String(app)} is not a @MeoCord app: fromApp takes the class @MeoCord decorates.`);
+        if (!appOptions) {
+            // A refused @MeoCord stores no options, so its own errors, kept with startupErrors: 'all', say why
+            collectStartupErrors(()=>declaredErrorsOf([
+                    app
+                ]).forEach(startupError));
+            throw new TypeError(`${app?.name ?? String(app)} is not a @MeoCord app: fromApp takes the class @MeoCord decorates.`);
+        }
         const controllers = [
             ...new Set([
                 ...appOptions.controllers,