meocord 4.2.1 → 4.2.3

package/dist/esm/testing/inspect-handler.js

@@ -2,15 +2,22 @@ import 'reflect-metadata';
 import { HandlerExecutionContext } from '../common/execution-context.js';
 import { appStages, handlerStages } from '../core/handler-pipeline.js';
 import { handlerCooldowns } from '../core/cooldown-runner.js';
-import { getMessageHandlers, getHandlerRoutes, getDeclaredRoutes } from '../decorator/controller.decorator.js';
+import { getMessageHandlers, getHandlerRoutes, eventRoute, getDeclaredRoutes, ownEventHandlers, getCommandMap, getAutocompleteHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getEventHandlers } from '../decorator/event.decorator.js';
+import { appliesTo } from '../core/stage-scope.js';
+import { Logger } from '../common/logger.js';
+import { warnOnce } from '../common/deprecation.js';
+import { strictMocks } from './strict-mocks.js';
 import { appObservers } from '../core/observer-runner.js';
 
 /**
  * Reports what runs when a handler is dispatched, and the metadata declared on it, without running anything.
  *
  * Use it to check that decorators set a handler up as intended: its guards with their params, its interceptors,
- * filters and cooldowns, in the order dispatch applies them. To check what a handler does, run it with
- * {@link TestingModule.invoke}.
+ * filters and cooldowns, in the order dispatch applies them. Under `useStrictMocks()`, the guards, interceptors and
+ * observers are those dispatch runs for the handler's context types: a stage declared with `types` is listed only for
+ * a handler of one of them, and an autocomplete lists no interceptors. Default mode lists every one, with a warning
+ * once where dispatch runs fewer. To check what a handler does, run it with {@link TestingModule.invoke}.
  *
  * @param controller - The controller class declaring the handler.
  * @param methodName - The handler method's name.
@@ -46,14 +53,20 @@ import { appObservers } from '../core/observer-runner.js';
     });
     const globals = options.app ? appStages(options.app) : undefined;
     const { guards, interceptors, filters } = handlerStages(controller.prototype, methodName, globals);
+    const observers = options.app ? appObservers(options.app) : [];
+    const stages = runStages(controller.prototype, methodName, {
+        guards,
+        interceptors,
+        observers
+    });
     const inspection = {
         controller,
         methodName,
         guards: Object.freeze([
-            ...guards
+            ...stages.guards
         ]),
         interceptors: Object.freeze([
-            ...interceptors
+            ...stages.interceptors
         ]),
         filters: Object.freeze(filters.flat()),
         cooldowns: Object.freeze(handlerCooldowns(controller.prototype, methodName).map(({ seconds, uses, per, bypass, by })=>Object.freeze({
@@ -64,24 +77,92 @@ import { appObservers } from '../core/observer-runner.js';
                 by: by !== undefined
             }))),
         pattern: getMessageHandlers(controller.prototype).find((handler)=>handler.method === methodName)?.pattern,
-        observers: Object.freeze(options.app ? appObservers(options.app) : []),
+        observers: Object.freeze([
+            ...stages.observers
+        ]),
         get: (metadata)=>context.get(metadata),
         getAll: (metadata)=>context.getAll(metadata)
     };
     // Read by a test but not compared by toEqual, so an assertion on the result's other fields holds
+    const routes = Object.freeze(inheritedRoutesOf(controller.prototype, methodName, false));
+    const withEvents = Object.freeze(inheritedRoutesOf(controller.prototype, methodName, true));
     Object.defineProperty(inspection, 'inheritedRoutes', {
-        value: Object.freeze(inheritedRoutesOf(controller.prototype, methodName)),
+        get: ()=>{
+            if (strictMocks()) return withEvents;
+            if (withEvents.length > routes.length) {
+                warnOnce(new Logger('inspectHandler'), `inspectHandler() here leaves the @On and @Once events ${controller.name}.${methodName} inherits out of ` + 'inheritedRoutes, though the bot answers them; under useStrictMocks() it lists them.');
+            }
+            return routes;
+        },
         enumerable: false
     });
     return inspection;
 }
-/** The routes `methodName` answers that the class declaring it last doesn't declare for it: those it inherits. */ function inheritedRoutesOf(prototype, methodName) {
+/** The context types dispatch calls `methodName` with: one for each kind of route it answers. */ function handlerContextTypes(prototype, methodName) {
+    const answers = [
+        [
+            'interaction',
+            Object.values(getCommandMap(prototype) ?? {}).some((metas)=>metas.some((meta)=>meta.methodName === methodName))
+        ],
+        [
+            'autocomplete',
+            getAutocompleteHandlers(prototype).some((handler)=>handler.methodName === methodName)
+        ],
+        [
+            'message',
+            getMessageHandlers(prototype).some((handler)=>handler.method === methodName)
+        ],
+        [
+            'reaction',
+            getReactionHandlers(prototype).some((handler)=>handler.method === methodName)
+        ],
+        [
+            'event',
+            getEventHandlers(prototype).some((handler)=>handler.method === methodName)
+        ]
+    ];
+    return answers.filter(([, answered])=>answered).map(([type])=>type);
+}
+/**
+ * The guards, interceptors and observers dispatch runs for the handler, by the same `appliesTo` it uses: those for one
+ * of its context types, and no interceptors for an autocomplete. Default mode lists every one, and warns once where
+ * that lists more; a method no route reaches lists every one in both modes.
+ */ function runStages(prototype, methodName, all) {
+    const types = handlerContextTypes(prototype, methodName);
+    if (types.length === 0) return all;
+    const forTypes = (entries, among)=>entries.filter((entry)=>among.some((type)=>appliesTo(entry, type)));
+    const run = {
+        ...all,
+        guards: forTypes(all.guards, types),
+        // Autocomplete answers within three seconds and has no reply to shape, so it runs no interceptors
+        interceptors: forTypes(all.interceptors, types.filter((type)=>type !== 'autocomplete')),
+        observers: forTypes(all.observers, types)
+    };
+    if (strictMocks()) return run;
+    const handlerName = `${prototype.constructor.name}.${methodName}`;
+    const count = (stages)=>stages.guards.length + stages.interceptors.length + stages.observers.length;
+    if (count(run) < count(all)) {
+        warnOnce(new Logger('inspectHandler'), `inspectHandler() here lists the guards, interceptors and observers of every context type for ${handlerName}, ` + "where dispatch runs only those of its own; under useStrictMocks() it lists the ones dispatch runs.");
+    }
+    return all;
+}
+/**
+ * The routes `methodName` answers that the class declaring it last doesn't declare for it: those it inherits, its
+ * `@On` and `@Once` events among them when `events` is set.
+ */ function inheritedRoutesOf(prototype, methodName, events) {
+    const labels = (routes)=>routes.filter((route)=>route.method === methodName).map((route)=>route.label);
     const answered = [
-        ...new Set(getHandlerRoutes(prototype).filter((route)=>route.method === methodName).map((route)=>route.label))
+        ...new Set(labels([
+            ...getHandlerRoutes(prototype),
+            ...events ? getEventHandlers(prototype).map(eventRoute) : []
+        ]))
     ];
     // The nearest class with its own decorators on the method; a class that only overrides it declares none
     for(let at = prototype; at && at !== Object.prototype; at = Object.getPrototypeOf(at)){
-        const own = getDeclaredRoutes(at).filter((route)=>route.method === methodName).map((route)=>route.label);
+        const own = labels([
+            ...getDeclaredRoutes(at),
+            ...events ? ownEventHandlers(at).map(eventRoute) : []
+        ]);
         if (own.length > 0) return at === prototype ? answered.filter((label)=>!own.includes(label)) : answered;
     }
     return [];