meocord 4.1.2 → 4.2.1

package/dist/esm/testing/discord-defaults.js

@@ -1,9 +1,66 @@
-import { GuildPremiumTier, GuildVerificationLevel, GuildNSFWLevel, Locale, Guild, ClientUser, User, GuildMember, Role, Collection, MessageType, Message, CommandInteraction, AutocompleteInteraction, GuildChannel, BaseInteraction, ChannelType, TextChannel, NewsChannel, VoiceChannel, ForumChannel, MediaChannel, ThreadChannel, DMChannel, BaseChannel, Client, BaseGuild, SnowflakeUtil, PermissionsBitField } from 'discord.js';
-import { memberRoles, createMockUser, createMockGuild } from './mock-interaction.js';
+import { GuildChannel, MessageReaction, MessageMentions, Message, GuildMember, BaseGuild, Guild, ModalSubmitInteraction, TextChannel, ThreadChannel, BaseGuildVoiceChannel, GuildPremiumTier, GuildVerificationLevel, GuildNSFWLevel, Locale, PresenceManager, ClientUser, UserFlagsBitField, User, GuildMemberFlagsBitField, Role, Collection, MessageType, ReactionManager, ChatInputCommandInteraction, CommandInteraction, AutocompleteInteraction, ReactionUserManager, BaseInteraction, ChannelType, NewsChannel, VoiceChannel, ForumChannel, MediaChannel, DMChannel, BaseChannel, Client, PermissionsBitField, PermissionFlagsBits } from 'discord.js';
+import { createMockChannel, createMockGuild, createMockMessage, ownedManager, memberRoles, createMockUser, createChatInputOptions, readPlaceAs, botMemberOf, heldChannelOf, isRawMember, isUnsetEveryone, NEW_SERVER_EVERYONE_PERMISSIONS } from './mock-interaction.js';
+import { nextSnowflake } from './snowflake.js';
+import { strictMocks } from './strict-mocks.js';
+import { Logger } from '../common/logger.js';
+import { warnOnce } from '../common/deprecation.js';
 
+const mockLogger = new Logger('Mocks');
+/**
+ * A member's permissions where an interaction was made, as Discord computes them: under strict mocks, every permission
+ * for an Administrator or the owner, else the channel's overwrites on top of `member.permissions`, so a test that sets
+ * those keeps the base; otherwise `member.permissions`, with a warning once where strict mocks would read otherwise.
+ */ function inChannel(interaction, member) {
+    const base = member.permissions;
+    // Only a server the mock caches has the overwrites to apply
+    const { guild } = interaction;
+    if (!(guild instanceof Guild)) return base;
+    const computed = base.has(PermissionFlagsBits.Administrator) || member.id === guild.ownerId ? new PermissionsBitField(PermissionsBitField.All).freeze() : withOverwrites(base, overwritingChannel(interaction, guild), member);
+    if (strictMocks()) return computed;
+    if (!computed.equals(base)) {
+        const lost = new PermissionsBitField(base).remove(computed).toArray();
+        const gained = new PermissionsBitField(computed).remove(base).toArray();
+        const change = lost.length > 0 ? [
+            `without ${lost.join(', ')}`
+        ] : [];
+        if (gained.length > 0) change.push(`with ${gained.join(', ')}`);
+        warnOnce(mockLogger, `${interaction.constructor.name}.memberPermissions reads the member's own permissions here, without the ` + "channel's overwrites or every permission an Administrator or the owner has; in the next major version (5.0) " + `it reads them as Discord computes them in the channel, ${change.join(' and ')}. Set memberPermissions on the ` + 'mock, or call useStrictMocks() to compute them now.');
+    }
+    // Unless the test set them, a member's permissions come from its roles, @everyone's included
+    if (!Object.prototype.hasOwnProperty.call(member, 'permissions')) warnOnUnsetEveryone(interaction, guild, 'memberPermissions', base);
+    return base;
+}
+/**
+ * Warns once, as `key`, where `permissions` read a server's @everyone role default mode made with none, and lack what
+ * strict mocks give @everyone in a new server.
+ */ function warnOnUnsetEveryone(interaction, guild, key, permissions) {
+    const everyone = guild.roles.everyone;
+    if (!everyone || !isUnsetEveryone(everyone) || permissions.has(NEW_SERVER_EVERYONE_PERMISSIONS)) return;
+    warnOnce(mockLogger, `${interaction.constructor.name}.${key} reads the server's @everyone role here with no permissions; in the next major ` + 'version (5.0) it has the permissions Discord gives @everyone in a new server, as strict mocks read it. Set ' + 'guild.roles.everyone.permissions, or call useStrictMocks() to read it so now.');
+}
+/**
+ * The channel whose overwrites apply where an interaction was made, read without making or caching one: a thread's
+ * parent, or undefined where the channel, or a thread's parent, is one the mock would make, which has none.
+ */ function overwritingChannel(interaction, guild) {
+    const channel = heldChannelOf(interaction, guild);
+    // A thread's parent by the id the test gave it or one already read, so strict mocks' parent isn't made for this read
+    const parentId = (thread)=>Object.prototype.hasOwnProperty.call(thread, 'parentId') ? thread.parentId : madeParentIds.get(thread);
+    const at = channel instanceof ThreadChannel ? guild.channels.cache.get(parentId(channel) ?? '') : channel;
+    return at instanceof GuildChannel ? at : undefined;
+}
+// The parent id strict mocks made for each thread made without one, once read
+const madeParentIds = new WeakMap();
+// Private in discord.js's typings, though they are what its own permissionsFor computes with; called on the prototype
+// so a test's stub on the channel stays for its caller
+const channelPermissions = GuildChannel.prototype;
+/** `base` with `channel`'s overwrites for `member` applied, in discord.js's order: @everyone's, the roles', the member's. */ function withOverwrites(base, channel, member) {
+    if (!channel) return base;
+    // Given the member and its roles as verified, as discord.js's memberPermissions does, so it resolves nothing again
+    const overwrites = channelPermissions.overwritesFor.call(channel, member, true, member.roles.cache);
+    return new PermissionsBitField(base).remove(overwrites.everyone?.deny ?? 0n).add(overwrites.everyone?.allow ?? 0n).remove(overwrites.roles.length > 0 ? overwrites.roles.map((role)=>role.deny) : 0n).add(overwrites.roles.length > 0 ? overwrites.roles.map((role)=>role.allow) : 0n).remove(overwrites.member?.deny ?? 0n).add(overwrites.member?.allow ?? 0n).freeze();
+}
 /** A permission set with none, frozen as discord.js freezes the ones it gives. */ const noPermissions = ()=>new PermissionsBitField().freeze();
 /** A property discord.js computes from the others: its own getter runs, reading the mock's values. */ const REAL_GETTER = Symbol('real getter');
-const snowflake = ()=>SnowflakeUtil.generate().toString();
 /** A class and its defaults, typed together so a default that stops fitting its property fails to compile. */ const defaultsOf = (Class, defaults)=>[
         Class.prototype,
         defaults
@@ -16,7 +73,7 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
     defaultsOf(Guild, {
         name: ()=>'Guild',
         preferredLocale: ()=>Locale.EnglishUS,
-        ownerId: snowflake,
+        ownerId: nextSnowflake,
         memberCount: ()=>1,
         available: ()=>true,
         large: ()=>false,
@@ -29,6 +86,9 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
         shardId: ()=>0,
         nsfwLevel: ()=>GuildNSFWLevel.Default,
         verificationLevel: ()=>GuildVerificationLevel.None,
+        presences: (guild)=>ownedManager(PresenceManager.prototype, {
+                guild
+            }),
         premiumTier: ()=>GuildPremiumTier.None,
         createdTimestamp: REAL_GETTER,
         createdAt: REAL_GETTER
@@ -43,6 +103,7 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
         discriminator: ()=>'0',
         avatar: ()=>null,
         system: ()=>false,
+        flags: ()=>new UserFlagsBitField(),
         tag: REAL_GETTER,
         displayName: REAL_GETTER,
         defaultAvatarURL: REAL_GETTER,
@@ -63,12 +124,12 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
         premiumSinceTimestamp: ()=>null,
         communicationDisabledUntilTimestamp: ()=>null,
         pending: ()=>false,
+        flags: ()=>new GuildMemberFlagsBitField().freeze(),
         displayName: REAL_GETTER,
         roles: (member)=>memberRoles(member, []),
         permissions: REAL_GETTER
     }),
     defaultsOf(Role, {
-        id: snowflake,
         name: ()=>'role',
         // Above @everyone, which a server's role manager makes at position 0
         position: ()=>1,
@@ -106,30 +167,71 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
         poll: ()=>null,
         interactionMetadata: ()=>null,
         stickers: ()=>new Collection(),
+        messageSnapshots: ()=>new Collection(),
+        reactions: (message)=>ownedManager(ReactionManager.prototype, {
+                message
+            }),
         url: REAL_GETTER
     }),
     // A command's name and a component's customId say which handler a call is for, so they stay the test's to give
+    defaultsOf(ChatInputCommandInteraction, {
+        options: ()=>createChatInputOptions()
+    }),
     defaultsOf(CommandInteraction, {
-        commandId: snowflake,
+        commandId: nextSnowflake,
         commandGuildId: ()=>null
     }),
     defaultsOf(AutocompleteInteraction, {
-        commandId: snowflake,
-        commandGuildId: ()=>null
+        commandId: nextSnowflake,
+        commandGuildId: ()=>null,
+        options: ()=>createChatInputOptions()
+    }),
+    defaultsOf(MessageReaction, {
+        users: (reaction)=>ownedManager(ReactionUserManager.prototype, {
+                reaction
+            })
     }),
     defaultsOf(BaseInteraction, {
-        applicationId: snowflake,
+        applicationId: nextSnowflake,
         token: ()=>'mock-interaction-token',
         version: ()=>1,
         context: ()=>null,
+        entitlements: ()=>new Collection(),
         // What Discord sends with an interaction in a server, the member's permissions there; typed for a cached one
-        memberPermissions: (interaction)=>interaction.guildId && interaction.member instanceof GuildMember ? interaction.member.permissions : null,
-        // The bot's permissions where the interaction was made: its member's in the channel, or none outside a server
-        appPermissions: (interaction)=>{
-            const { guild, channel } = interaction;
-            const me = guild instanceof Guild ? guild.members.me : null;
-            return (me && channel instanceof GuildChannel ? channel.permissionsFor(me) : null) ?? noPermissions();
-        }
+        // Each reads where the interaction is as its own, and warns by its own name where strict mocks place it otherwise
+        memberPermissions: (interaction)=>readPlaceAs(interaction, 'memberPermissions', ()=>{
+                const { guildId } = interaction;
+                const member = interaction.member;
+                if (!guildId) return null;
+                if (member instanceof GuildMember) return inChannel(interaction, member);
+                // A raw member's permissions are the string Discord sends, read as discord.js reads them
+                return isRawMember(member) && !interaction.guild ? new PermissionsBitField(BigInt(member.permissions)).freeze() : null;
+            }),
+        // The bot's permissions where the interaction was made: its member's in the channel, or in a thread its parent, as
+        // discord.js computes them; none outside a server
+        appPermissions: (interaction)=>readPlaceAs(interaction, 'appPermissions', ()=>{
+                const { guild } = interaction;
+                const me = guild instanceof Guild ? botMemberOf(guild) : null;
+                if (!(me instanceof GuildMember) || heldChannelOf(interaction, guild) === null) return noPermissions();
+                // discord.js's own computation, given its own overwritesFor over a test's stub on the channel; a channel the
+                // mock would make has no overwrites
+                const at = overwritingChannel(interaction, guild) ?? {
+                    guild,
+                    permissionOverwrites: {
+                        cache: new Collection()
+                    }
+                };
+                const channel = Object.create(at, {
+                    overwritesFor: {
+                        value: channelPermissions.overwritesFor
+                    }
+                });
+                const permissions = channelPermissions.memberPermissions.call(channel, me, true);
+                // The bot's member has @everyone's too
+                warnOnUnsetEveryone(interaction, guild, 'appPermissions', permissions);
+                return permissions;
+            }, // A server the bot isn't in has no guild in either mode, so no permissions in both
+            (place)=>!place.raw)
     }),
     defaultsOf(TextChannel, {
         type: ()=>ChannelType.GuildText,
@@ -165,7 +267,7 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
     }),
     defaultsOf(GuildChannel, {
         name: ()=>'channel',
-        guildId: (channel)=>typeof channel.guild?.id === 'string' ? channel.guild.id : snowflake(),
+        guildId: (channel)=>typeof channel.guild?.id === 'string' ? channel.guild.id : nextSnowflake(),
         position: ()=>0,
         rawPosition: ()=>0,
         parentId: ()=>null
@@ -184,12 +286,138 @@ const snowflake = ()=>SnowflakeUtil.generate().toString();
         nameAcronym: REAL_GETTER
     })
 ]);
-/** The default a mock of `target`'s class has for `key`, read from the nearest class that has one. */ function discordDefault(target, key) {
+/**
+ * What strict mocks also read as Discord sends it, for discord.js's getters that read it: a server for a channel or
+ * thread made without one, a thread's parent text channel in it, and data that is otherwise a placeholder.
+ */ const STRICT_DEFAULTS = new Map([
+    defaultsOf(Message, {
+        content: ()=>'',
+        editedTimestamp: ()=>null,
+        editedAt: REAL_GETTER
+    }),
+    defaultsOf(MessageMentions, {
+        repliedUser: ()=>null
+    }),
+    defaultsOf(Guild, {
+        rulesChannelId: ()=>null,
+        publicUpdatesChannelId: ()=>null,
+        systemChannel: REAL_GETTER
+    }),
+    defaultsOf(BaseGuild, {
+        verified: REAL_GETTER
+    }),
+    defaultsOf(GuildMember, {
+        presence: REAL_GETTER
+    }),
+    defaultsOf(ModalSubmitInteraction, {
+        message: ()=>null
+    }),
+    defaultsOf(ThreadChannel, {
+        guild: ()=>createMockGuild(),
+        guildId: (thread)=>thread.guild.id,
+        parentId: (thread)=>{
+            const parent = createMockChannel(TextChannel, {
+                guild: thread.guild
+            });
+            thread.guild.channels.cache.set(parent.id, parent);
+            madeParentIds.set(thread, parent.id);
+            return parent.id;
+        },
+        parent: REAL_GETTER,
+        ownerId: nextSnowflake,
+        archived: ()=>false,
+        locked: ()=>false
+    }),
+    defaultsOf(GuildChannel, {
+        guild: ()=>createMockGuild(),
+        parent: REAL_GETTER
+    }),
+    // Full once its members reach a user limit, which a voice channel has none of unless given one
+    defaultsOf(BaseGuildVoiceChannel, {
+        userLimit: ()=>0,
+        full: REAL_GETTER
+    }),
+    // A reaction's message, as discord.js always has one, is a whole one
+    defaultsOf(MessageReaction, {
+        count: ()=>1,
+        me: ()=>false,
+        message: ()=>createMockMessage()
+    })
+]);
+/**
+ * What a mock reads as a placeholder unless strict mocks read it as discord.js gives it, by the value a test sets for
+ * that, which the warning on reading one names.
+ */ const PLACEHOLDER_VALUES = new Map([
+    [
+        MessageReaction.prototype,
+        {
+            me: 'false',
+            message: 'createMockMessage()'
+        }
+    ],
+    [
+        MessageMentions.prototype,
+        {
+            repliedUser: 'null'
+        }
+    ],
+    [
+        Message.prototype,
+        {
+            editedAt: 'null'
+        }
+    ],
+    [
+        GuildMember.prototype,
+        {
+            presence: 'null'
+        }
+    ],
+    [
+        BaseGuild.prototype,
+        {
+            verified: 'false'
+        }
+    ],
+    [
+        Guild.prototype,
+        {
+            systemChannel: 'null'
+        }
+    ],
+    [
+        GuildChannel.prototype,
+        {
+            parent: 'null'
+        }
+    ],
+    [
+        ModalSubmitInteraction.prototype,
+        {
+            message: 'null'
+        }
+    ]
+]);
+/** The value a test sets for `key` on a mock of `target`'s class, when a mock reads it as a placeholder. */ function placeholderValue(target, key) {
     for(let proto = Object.getPrototypeOf(target); proto !== null; proto = Object.getPrototypeOf(proto)){
-        const found = DEFAULTS.get(proto)?.[key];
-        if (found !== undefined) return found;
+        const value = PLACEHOLDER_VALUES.get(proto)?.[key];
+        if (value !== undefined) return value;
+    }
+    return undefined;
+}
+/** The default a mock of `target`'s class has for `key`, read from the nearest class that has one, strict ones first. */ function discordDefault(target, key) {
+    for (const defaults of strictMocks() ? [
+        STRICT_DEFAULTS,
+        DEFAULTS
+    ] : [
+        DEFAULTS
+    ]){
+        for(let proto = Object.getPrototypeOf(target); proto !== null; proto = Object.getPrototypeOf(proto)){
+            const found = defaults.get(proto)?.[key];
+            if (found !== undefined) return found;
+        }
     }
     return undefined;
 }
 
-export { REAL_GETTER, discordDefault };
+export { REAL_GETTER, discordDefault, placeholderValue };

package/dist/esm/testing/index.js

@@ -1,6 +1,8 @@
 export { MeoCordTestingModule, TestingModule, TestingModuleBuilder } from './meocord-testing-module.js';
-export { createChatInputOptions, createMock, createMockChannel, createMockClient, createMockGuild, createMockInteraction, createMockMember, createMockMessage, createMockUser } from './mock-interaction.js';
-export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks } from './mock-fn.js';
+export { createChatInputOptions, createMock, createMockChannel, createMockClient, createMockGuild, createMockInteraction, createMockMember, createMockMessage, createMockRawMember, createMockUser } from './mock-interaction.js';
+export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks, useMockFn } from './mock-fn.js';
+export { useStrictMocks } from './strict-mocks.js';
+export { reportAllStartupErrors } from './startup-errors.js';
 export { findRouteConflicts, resolveRoute } from './routing.js';
 export { createModalFields } from './modal-fields.js';
 export { expectCompleteCatalog } from './catalog.js';

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

@@ -2,7 +2,7 @@ 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 } from '../decorator/controller.decorator.js';
+import { getMessageHandlers, getHandlerRoutes, getDeclaredRoutes } from '../decorator/controller.decorator.js';
 import { appObservers } from '../core/observer-runner.js';
 
 /**
@@ -37,7 +37,7 @@ import { appObservers } from '../core/observer-runner.js';
  * @group Testing
  * @category Inspection
  * @see {@link createExecutionContext}
- * @see {@link https://meocord.dev/docs/4.1/testing-recipes | Testing recipes}
+ * @see {@link https://meocord.dev/docs/4.2/testing-recipes | Testing recipes}
  */ function inspectHandler(controller, methodName, options = {}) {
     const context = new HandlerExecutionContext({
         controller,
@@ -46,7 +46,7 @@ import { appObservers } from '../core/observer-runner.js';
     });
     const globals = options.app ? appStages(options.app) : undefined;
     const { guards, interceptors, filters } = handlerStages(controller.prototype, methodName, globals);
-    return {
+    const inspection = {
         controller,
         methodName,
         guards: Object.freeze([
@@ -68,6 +68,23 @@ import { appObservers } from '../core/observer-runner.js';
         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
+    Object.defineProperty(inspection, 'inheritedRoutes', {
+        value: Object.freeze(inheritedRoutesOf(controller.prototype, methodName)),
+        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) {
+    const answered = [
+        ...new Set(getHandlerRoutes(prototype).filter((route)=>route.method === methodName).map((route)=>route.label))
+    ];
+    // 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);
+        if (own.length > 0) return at === prototype ? answered.filter((label)=>!own.includes(label)) : answered;
+    }
+    return [];
 }
 
 export { inspectHandler };