meocord 4.0.0-beta.4 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # meocord
 
+## 4.0.0
+
+MeoCord 4 builds with Rsbuild instead of webpack, requires Node.js 22.13 and dotenv 18, and can
+deploy a bot without `node_modules`. Most bots need two changes; see the
+[migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md).
+
+### Major Changes
+
+- [#22](https://github.com/l7aromeo/meocord/pull/22) [`4deb96f`](https://github.com/l7aromeo/meocord/commit/4deb96fd73f86a29c46b9bb080c13e6267246cb1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Build with [Rsbuild](https://rsbuild.rs) instead of webpack. Production builds are several times
+  faster, and webpack and its four loader and plugin packages are no longer installed with MeoCord.
+  The output layout is unchanged: `dist/main.js`, and assets under `dist/assets/` with the same names.
+  Production source maps now list sources as `../src/...` paths instead of `webpack://` URLs.
+
+  **Breaking:** the `webpack` hook in `meocord.config.ts` is replaced by `rsbuild`, which receives
+  Rsbuild's configuration. A config that still declares `webpack` stops the build with a message
+  saying so. `MeoCordWebpackConfig` is removed; import `RsbuildConfig` from `meocord/interface`
+  instead. The [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#2-replace-the-webpack-hook-with-rsbuild) shows where each
+  webpack setting goes.
+
+- [#44](https://github.com/l7aromeo/meocord/pull/44) [`e48472e`](https://github.com/l7aromeo/meocord/commit/e48472e9ffee2f0371a7a2a71a4063e99ce61674) Thanks [@l7aromeo](https://github.com/l7aromeo)! - **Breaking:** `meocord/decorator` exports only the decorators. The routing helpers it also exported
+  — `getCommandMap`, `getMessageHandlers`, `getReactionHandlers`, `getAutocompleteHandlers`,
+  `findAmbiguousRoutes` and `PARAM_SEPARATOR` — are internal to MeoCord now. See the
+  [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#internal-helpers-are-no-longer-exported).
+
+- [#19](https://github.com/l7aromeo/meocord/pull/19) [`204c7be`](https://github.com/l7aromeo/meocord/commit/204c7bec74886c931732cb771d9178b47fbec5e8) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Require dotenv 18. The `dotenv` peer dependency moves from `^17.4.2` to `^18.0.3`, so install
+  `dotenv@18` alongside MeoCord 4. No application code changes — `import 'dotenv/config'` behaves
+  the same. See the [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#1-upgrade-dotenv-to-18).
+
+- [#33](https://github.com/l7aromeo/meocord/pull/33) [`21b06ae`](https://github.com/l7aromeo/meocord/commit/21b06ae6810cfe203abadcadc6f7b7247c7b305b) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Require Node.js 22.13 or newer, up from 22.0. A built bot loads its compiled config with `require()`
+  of an ES module. Node 22.12 runs that without a flag but still warns on every start and crashes on a
+  config that throws; 22.13 is the first 22 release that does neither. Bun is unaffected. See the
+  [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#before-you-start-nodejs-2213).
+
+- [#36](https://github.com/l7aromeo/meocord/pull/36) [`45e564e`](https://github.com/l7aromeo/meocord/commit/45e564e6baff17313037372ec56baa1711a3584c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - **Breaking:** `app.start()` rejects when the login fails. It logged the error and resolved, so a bot
+  with an invalid token went on to log "Application started" and exit with code 0, which Docker's
+  `restart: on-failure`, systemd and CI all read as success. It now sets the exit code to 1 before
+  rejecting, so a bot that fails to log in exits 1 with its entry point unchanged. See the
+  [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#4-build-and-start).
+
+### Minor Changes
+
+- [#22](https://github.com/l7aromeo/meocord/pull/22) [`4deb96f`](https://github.com/l7aromeo/meocord/commit/4deb96fd73f86a29c46b9bb080c13e6267246cb1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Add `bundleDependencies`, which puts everything a bot needs inside `dist`, so it deploys without
+  `node_modules` or an install step. Plain JavaScript dependencies are bundled into `main.js`. Native
+  addons such as `sharp` are found while building and copied, with their platform binary, into
+  `dist/node_modules` — nothing has to be listed. Only binaries for the platform building are copied,
+  whichever package manager installed them.
+
+  A build carrying native addons records its platform in `dist/meocord.platform.json`, and a bot
+  started on another platform stops before going online with a message naming both. Build on the
+  platform you deploy to. See
+  [Self-contained builds](https://github.com/l7aromeo/meocord#self-contained-builds).
+
+- [#47](https://github.com/l7aromeo/meocord/pull/47) [`9652436`](https://github.com/l7aromeo/meocord/commit/965243660323277827a64851f28da9cda2c2fe0c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Add `resolveRoute` and `findRouteConflicts` to `meocord/testing`, for testing which handler a
+  component's customId reaches. `resolveRoute(App, { type, customId })` gives the answer dispatch
+  gives — across every controller the app registers, for that component type, most specific pattern
+  first — as the controller, the handler method and its name, and the captured params, or `undefined`.
+  `findRouteConflicts(App)` returns the pattern pairs that can match the same customId, which MeoCord
+  otherwise only warns about at startup. Both read decorator metadata only, and dispatch runs on the
+  same matcher.
+
+### Patch Changes
+
+- [#22](https://github.com/l7aromeo/meocord/pull/22) [`4deb96f`](https://github.com/l7aromeo/meocord/commit/4deb96fd73f86a29c46b9bb080c13e6267246cb1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Read `meocord.config.ts` on every build. `meocord build` read the compiled `dist/meocord.config.mjs`
+  left by the previous build, so a config edit took effect one build late, and the watcher's reload
+  on a config change reloaded nothing.
+
+- [#22](https://github.com/l7aromeo/meocord/pull/22) [`4deb96f`](https://github.com/l7aromeo/meocord/commit/4deb96fd73f86a29c46b9bb080c13e6267246cb1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Start the bot with `bun --no-install` from `meocord start`. Without it, bun downloads any package it
+  cannot find while the bot runs, which a bot deployed without `node_modules` would do in
+  production. If you start `dist/main.js` with bun yourself, pass the flag too.
+
+- [#37](https://github.com/l7aromeo/meocord/pull/37) [`a9452c2`](https://github.com/l7aromeo/meocord/commit/a9452c256beace70141bb87ed33c693d14064d14) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Type the CommonJS build as CommonJS. Every entry point's `require` condition resolved to the ESM
+  declarations, so a CommonJS TypeScript project was told `meocord/core` is an ES module it cannot
+  `require`, even with `skipLibCheck`. Each entry now ships `.d.cts` declarations for `require`, and
+  `meocord/eslint` types its `module.exports` array as what `require` returns.
+
+- [#33](https://github.com/l7aromeo/meocord/pull/33) [`21b06ae`](https://github.com/l7aromeo/meocord/commit/21b06ae6810cfe203abadcadc6f7b7247c7b305b) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Load the compiled config without a transpiler. A built bot reads `dist/meocord.config.mjs` with
+  `require()` and no longer falls back to `meocord.config.ts` when it is missing, so jiti stays out of
+  a bot bundled with `bundleDependencies`. `meocord build` fails when the config does not compile,
+  instead of warning and producing a bot that cannot start.
+
+- [#35](https://github.com/l7aromeo/meocord/pull/35) [`b93a771`](https://github.com/l7aromeo/meocord/commit/b93a771b19664345fec4222d5a2c29dcf5b31a0d) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Generate code that passes a new application's own `lint`. A generated guard failed `tsc` and ESLint
+  — `GuardInterface` imported as a value, and an unused `context` parameter — and generated message and
+  reaction controllers imported names they never used, which only the application's ESLint, run in the
+  background after generating, removed. New applications also typecheck `meocord.config.ts`: the
+  template's `tsconfig.json` includes it instead of excluding it, so a type error in the config fails
+  `lint`, and editors resolve `paths` aliases imported there. `noEmit` stays on, so `tsc` writes nothing
+  beside it.
+
+- [#25](https://github.com/l7aromeo/meocord/pull/25) [`2179f85`](https://github.com/l7aromeo/meocord/commit/2179f85c2912d45e3fefbf996ca267c19a1a773c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Stop `meocord generate` overwriting files. Slash, context-menu and primary entry point controllers
+  all wrote one shared `builders/sample.builder.ts`, so generating a second controller replaced a
+  builder you had already edited. Each controller now gets its own `builders/<name>.builder.ts`
+  exporting `<Name>CommandBuilder`, and registers a command named after it — `admin/ban` registers
+  `admin-ban` — rather than every one registering `sample-slash`. Generating a controller, service or
+  guard refuses if any file it would write already exists.
+
+- [#40](https://github.com/l7aromeo/meocord/pull/40) [`3629edd`](https://github.com/l7aromeo/meocord/commit/3629eddaf20bd0947d24e5582aa167b2c0ca0d47) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Lint `meocord.config.ts`. The shared ESLint config from `meocord/eslint` ignored it, so the config
+  alone skipped the rules every other file follows — unused imports, formatting. It is linted like the
+  rest now; the typecheck it already gets is unchanged.
+
+- [#24](https://github.com/l7aromeo/meocord/pull/24) [`5e2a54b`](https://github.com/l7aromeo/meocord/commit/5e2a54b67a1f9f51c4c3a3e8cf51247de2ac2528) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Type `deleted` on `createMockMessage()`. The mock tracks and documents it, but it was missing from
+  the type, so `message.deleted` did not compile.
+
+- [#24](https://github.com/l7aromeo/meocord/pull/24) [`5e2a54b`](https://github.com/l7aromeo/meocord/commit/5e2a54b67a1f9f51c4c3a3e8cf51247de2ac2528) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Accept slash command builders that add options. `@CommandBuilder(CommandType.SLASH)` rejected
+  `new SlashCommandBuilder().addStringOption(...)`, whose type narrows to
+  `SlashCommandOptionsOnlyBuilder`, so the most common builder — one command with an option — did
+  not compile.
+
+- [#21](https://github.com/l7aromeo/meocord/pull/21) [`bebf116`](https://github.com/l7aromeo/meocord/commit/bebf1168466595546017a317b62acd3707ff2d1c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Generate applications with current test tooling: vitest and `@vitest/coverage-istanbul` 5,
+  `unplugin-swc` 2, and current eslint, prettier and typescript-eslint. A new application's
+  `test:coverage` no longer fails on its decorated entry files.
+
+## 4.0.0-beta.5
+
+### Minor Changes
+
+- [#47](https://github.com/l7aromeo/meocord/pull/47) [`9652436`](https://github.com/l7aromeo/meocord/commit/965243660323277827a64851f28da9cda2c2fe0c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Add `resolveRoute` and `findRouteConflicts` to `meocord/testing`, for testing which handler a
+  component's customId reaches. `resolveRoute(App, { type, customId })` gives the answer dispatch gives
+  — across every controller the app registers, for that component type, most specific pattern first —
+  as the controller, the handler method and its name, and the captured params, or `undefined`. `findRouteConflicts(App)` returns the
+  pattern pairs that can match the same customId, which MeoCord otherwise only warns about at startup.
+  Both read decorator metadata only, and dispatch runs on the same matcher.
+
 ## 4.0.0-beta.4
 
 ### Major Changes

package/README.md

@@ -689,7 +689,7 @@ bun run test:typecheck    # tsc -p tsconfig.test.json
 bun run lint              # eslint --fix + tsc
 ```
 
-In your own bot project, add Vitest (or keep Jest) plus a `vitest.config.ts` with SWC if you use decorator metadata — see this repo's config for reference. Generated apps include `*.spec.ts` stubs but not a test runner config yet.
+Generated apps come with Vitest set up — `vitest.config.ts` with SWC for decorator metadata, and `test`, `test:watch` and `test:coverage` scripts — plus a spec beside every generated component. In an older project, add Vitest (or keep Jest) with the same SWC setup; `meocord/testing` works with either.
 
 ### `MeoCordTestingModule`
 
@@ -884,6 +884,39 @@ expect(msg.delete).toHaveBeenCalledTimes(1)
 
 </details>
 
+<details>
+<summary><b><code>resolveRoute</code> / <code>findRouteConflicts</code></b></summary>
+
+Tests which handler a component's customId reaches — the same answer dispatch gives, across every
+controller your app registers, most specific pattern first. They read decorator metadata only, so
+they need no Discord client, config or container. They check routing alone: guards are not run, and
+whether a controller's dependencies are bound is for `MeoCordTestingModule` to test.
+
+```typescript
+import { findRouteConflicts, resolveRoute } from 'meocord/testing'
+import { CommandType } from 'meocord/enum'
+import App from '@src/app'
+import { ProfileController } from '@src/controllers/button/profile.button.controller'
+
+it('routes the profile button to its handler', () => {
+  const route = resolveRoute(App, { type: CommandType.BUTTON, customId: 'profile/111/8000' })
+
+  // The method itself rather than its name, so renaming it in your editor updates the test too.
+  expect(route?.handler).toBe(ProfileController.prototype.showProfile)
+  expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
+})
+
+// Patterns that can match the same customId, as a failing test rather than a startup warning.
+it('has no overlapping component patterns', () => {
+  expect(findRouteConflicts(App)).toEqual([])
+})
+```
+
+`resolveRoute` returns the `controller`, the `handler` method and its name as `method`, and the
+`params` the pattern captured — or `undefined` when no route handles the customId.
+
+</details>
+
 <details>
 <summary><b><code>createMock</code></b></summary>
 

package/dist/cjs/_shared/component-routes-RTZZ3t5i.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+var controller_decorator = require('./controller.decorator-DnKZ29W4.cjs');
+
+/** Every customId-pattern route of the given controllers, most specific first, read from metadata alone. */ function buildComponentRoutes(controllerClasses) {
+    const routes = [];
+    for (const controllerClass of controllerClasses){
+        const commandMap = controller_decorator.getCommandMap(controllerClass.prototype);
+        if (!commandMap) continue;
+        for (const [pattern, metaArray] of Object.entries(commandMap)){
+            if (!Array.isArray(metaArray)) continue;
+            for (const meta of metaArray){
+                if (meta.regex) routes.push({
+                    controllerClass,
+                    meta,
+                    pattern
+                });
+            }
+        }
+    }
+    return routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
+}
+/**
+ * The route dispatch runs for a customId: the first, in rank order, whose type `acceptsType` allows
+ * and whose pattern matches, with the captured params.
+ */ function matchComponentRoute(routes, acceptsType, customId) {
+    for (const route of routes){
+        if (!acceptsType(route.meta.type)) continue;
+        const match = route.meta.regex.exec(customId);
+        if (match) return {
+            route,
+            params: {
+                ...match.groups
+            }
+        };
+    }
+    return undefined;
+}
+/** Pattern pairs that can match one customId, compared only within a component type, as dispatch does. */ function findComponentRouteConflicts(routes) {
+    const byType = new Map();
+    for (const { meta, pattern } of routes)byType.set(meta.type, [
+        ...byType.get(meta.type) ?? [],
+        pattern
+    ]);
+    return [
+        ...byType
+    ].flatMap(([type, patterns])=>controller_decorator.findAmbiguousRoutes(patterns).map((pair)=>({
+                type,
+                patterns: pair
+            })));
+}
+
+exports.buildComponentRoutes = buildComponentRoutes;
+exports.findComponentRouteConflicts = findComponentRouteConflicts;
+exports.matchComponentRoute = matchComponentRoute;

package/dist/cjs/_shared/{controller.decorator-CqgGgjj3.cjs → controller.decorator-DnKZ29W4.cjs}

@@ -3,7 +3,6 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var enum_index = require('../enum/index.cjs');
-var metadataKey_enum = require('./metadata-key.enum-DG7cVMc4.cjs');
 var discord_js = require('discord.js');
 
 /**
@@ -311,7 +310,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
         if (typeof builderOrType === 'function') {
             const builderObj = new builderOrType();
             builderInstance = builderObj.build(commandName);
-            commandType = Reflect.getMetadata(metadataKey_enum.MetadataKey.CommandType, builderOrType);
+            commandType = Reflect.getMetadata(enum_index.MetadataKey.CommandType, builderOrType);
             if (!(commandType in enum_index.CommandType)) {
                 throw new Error(`Metadata for 'commandType' is missing on builder ${builderOrType.name}`);
             }
@@ -401,7 +400,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
  * ```
  */ function Controller() {
     return function(target) {
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
     };
@@ -448,6 +447,7 @@ exports.getCommandMap = getCommandMap;
 exports.getMessageHandlers = getMessageHandlers;
 exports.getReactionHandlers = getReactionHandlers;
 exports.hasCustomId = hasCustomId;
+exports.isCustomIdRouted = isCustomIdRouted;
 exports.matchesCommandType = matchesCommandType;
 exports.resolveCommandPaths = resolveCommandPaths;
 exports.resolveOptionParams = resolveOptionParams;

package/dist/cjs/core/index.cjs

@@ -4,13 +4,13 @@ require('reflect-metadata');
 var inversify = require('inversify');
 var discord_js = require('discord.js');
 var theme = require('../_shared/theme-C8w8ivsR.cjs');
-var controller_decorator = require('../_shared/controller.decorator-CqgGgjj3.cjs');
+var controller_decorator = require('../_shared/controller.decorator-DnKZ29W4.cjs');
 var lodashEs = require('lodash-es');
 var enum_index = require('../enum/index.cjs');
 var Table = require('cli-table3');
+var componentRoutes = require('../_shared/component-routes-RTZZ3t5i.cjs');
 var fs = require('fs');
 var path = require('path');
-var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
 require('node:util');
 require('dayjs');
 require('dayjs/plugin/utc.js');
@@ -200,44 +200,18 @@ class MeoCordApp {
     }
     getComponentRoutes() {
         if (this.componentRoutes) return this.componentRoutes;
-        const routes = [];
-        for (const controllerClass of this.controllerClasses){
-            const commandMap = controller_decorator.getCommandMap(this.getInstance(controllerClass));
-            if (!commandMap) continue;
-            for (const [pattern, metaArray] of Object.entries(commandMap)){
-                if (!Array.isArray(metaArray)) continue;
-                for (const meta of metaArray){
-                    if (meta.regex) routes.push({
-                        controllerClass,
-                        meta,
-                        pattern
-                    });
-                }
-            }
-        }
-        routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
+        const routes = componentRoutes.buildComponentRoutes(this.controllerClasses);
         this.reportAmbiguousRoutes(routes);
         this.componentRoutes = routes;
         return routes;
     }
     /**
-   * Warns rather than throws: an app whose patterns overlap boots and works today, and
-   * refusing to start would turn a latent mis-route into an outage on upgrade.
+   * Warns rather than throws: an app whose patterns overlap boots and works, and refusing to start
+   * would turn a latent mis-route into an outage.
    */ reportAmbiguousRoutes(routes) {
-        // Grouped by command type first: dispatch only considers routes whose component
-        // type matches the interaction, so a button and a select menu sharing a pattern
-        // are never in competition and reporting them would be a false alarm.
-        const byType = new Map();
-        for (const { meta, pattern } of routes){
-            const patterns = byType.get(meta.type) ?? [];
-            patterns.push(pattern);
-            byType.set(meta.type, patterns);
-        }
-        const collisions = [
-            ...byType.values()
-        ].flatMap((patterns)=>controller_decorator.findAmbiguousRoutes(patterns));
-        if (collisions.length === 0) return;
-        this.logger.warn(`${collisions.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + collisions.map(([left, right])=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${controller_decorator.PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
+        const conflicts = componentRoutes.findComponentRouteConflicts(routes);
+        if (conflicts.length === 0) return;
+        this.logger.warn(`${conflicts.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + conflicts.map(({ patterns: [left, right] })=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${controller_decorator.PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
     }
     getAutocompleteRoutes() {
         if (this.autocompleteRoutes) return this.autocompleteRoutes;
@@ -283,14 +257,12 @@ class MeoCordApp {
         // Commands match their registered name exactly and cannot overlap.
         if (controller_decorator.hasCustomId(interaction)) {
             const customId = interaction.customId;
-            for (const { controllerClass, meta } of this.getComponentRoutes()){
-                // A button and a select menu may legitimately share a customId shape, so the
-                // pattern alone does not identify the handler -- the component type does.
-                if (!controller_decorator.matchesCommandType(meta.type, interaction)) continue;
-                const match = meta.regex.exec(customId);
-                if (!match) continue;
-                interaction.dynamicParams = match.groups ?? {};
-                await this.executeCommand(this.getInstance(controllerClass), meta, interaction, customId);
+            // The component type as well as the pattern: a button and a select menu may share a customId shape.
+            const matched = componentRoutes.matchComponentRoute(this.getComponentRoutes(), (type)=>controller_decorator.matchesCommandType(type, interaction), customId);
+            if (matched) {
+                const { route, params } = matched;
+                interaction.dynamicParams = params;
+                await this.executeCommand(this.getInstance(route.controllerClass), route.meta, interaction, customId);
                 return;
             }
         }
@@ -560,11 +532,11 @@ class MeoCordApp {
  * Recursively binds a class and all its constructor dependencies to the container in singleton scope.
  */ function bindDependencies(container, cls) {
     if (container.isBound(cls)) return;
-    if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, cls)) {
+    if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, cls)) {
         inversify.injectable()(cls);
     }
     container.bind(cls).toSelf().inSingletonScope();
-    const deps = Reflect.getMetadata(metadataKey_enum.MetadataKey.ParamTypes, cls) || [];
+    const deps = Reflect.getMetadata(enum_index.MetadataKey.ParamTypes, cls) || [];
     for (const dep of deps){
         if (dep === discord_js.Client) continue;
         bindDependencies(container, dep);
@@ -572,7 +544,7 @@ class MeoCordApp {
 }
 class MeoCordFactory {
     static create(target) {
-        const options = Reflect.getMetadata(metadataKey_enum.MetadataKey.AppOptions, target);
+        const options = Reflect.getMetadata(enum_index.MetadataKey.AppOptions, target);
         if (!options) {
             if (typeof target === 'function') {
                 this.logger.error(`No @MeoCord() options found for class: ${target.name}`);
@@ -605,7 +577,7 @@ class MeoCordFactory {
         }
         // Stamp each controller class with the container so @UseGuard can resolve guards
         for (const ctrl of options.controllers){
-            Reflect.defineMetadata(metadataKey_enum.MetadataKey.Container, container, ctrl);
+            Reflect.defineMetadata(enum_index.MetadataKey.Container, container, ctrl);
         }
         return new MeoCordApp(options.controllers, container, discordClient, meocordConfig.discordToken, options.activities);
     }

package/dist/cjs/decorator/index.cjs

@@ -2,10 +2,9 @@
 
 require('reflect-metadata');
 var inversify = require('inversify');
-var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
-var controller_decorator = require('../_shared/controller.decorator-CqgGgjj3.cjs');
+var enum_index = require('../enum/index.cjs');
+var controller_decorator = require('../_shared/controller.decorator-DnKZ29W4.cjs');
 var discord_js = require('discord.js');
-require('../enum/index.cjs');
 
 /**
  * Marks a class as a service, injectable into controllers and other services.
@@ -21,7 +20,7 @@ require('../enum/index.cjs');
  * ```
  */ function Service() {
     return function(target) {
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
     };
@@ -44,11 +43,11 @@ require('../enum/index.cjs');
  */ function CommandBuilder(commandType) {
     return function(target) {
         // Check if the class is already injectable; if not, make it injectable dynamically
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
         // Define the command type metadata for the target class
-        Reflect.defineMetadata(metadataKey_enum.MetadataKey.CommandType, commandType, target);
+        Reflect.defineMetadata(enum_index.MetadataKey.CommandType, commandType, target);
     };
 }
 
@@ -62,7 +61,7 @@ function applyGuards(descriptor, guards, propertyKey) {
         if (!isValidContext(context)) {
             throw new Error(`The first argument of ${String(propertyKey)} must be an instance of Interaction, Message, or MessageReaction.`);
         }
-        const container = Reflect.getMetadata(metadataKey_enum.MetadataKey.Container, this.constructor);
+        const container = Reflect.getMetadata(enum_index.MetadataKey.Container, this.constructor);
         for (const guard of guards){
             let guardInstance;
             if (isGuardWithParams(guard)) {
@@ -101,7 +100,7 @@ function applyGuards(descriptor, guards, propertyKey) {
  * ```
  */ function Guard() {
     return function(target) {
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
     };
@@ -129,7 +128,7 @@ function applyGuards(descriptor, guards, propertyKey) {
         if (descriptor && propertyKey) {
             // Method Decorator
             applyGuards(descriptor, guards, String(propertyKey));
-            Reflect.defineMetadata(metadataKey_enum.MetadataKey.Guards, guards, target, propertyKey);
+            Reflect.defineMetadata(enum_index.MetadataKey.Guards, guards, target, propertyKey);
         } else if (typeof target === 'function' && !propertyKey && !descriptor) {
             // Class Decorator
             const prototype = target.prototype;
@@ -145,7 +144,7 @@ function applyGuards(descriptor, guards, propertyKey) {
                 if (methodDescriptor) {
                     applyGuards(methodDescriptor, guards, methodName);
                     Object.defineProperty(prototype, methodName, methodDescriptor);
-                    Reflect.defineMetadata(metadataKey_enum.MetadataKey.Guards, guards, prototype, methodName);
+                    Reflect.defineMetadata(enum_index.MetadataKey.Guards, guards, prototype, methodName);
                 }
             }
         }
@@ -175,10 +174,10 @@ function applyGuards(descriptor, guards, propertyKey) {
  * ```
  */ function MeoCord(options) {
     return (target)=>{
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
-        Reflect.defineMetadata(metadataKey_enum.MetadataKey.AppOptions, options, target);
+        Reflect.defineMetadata(enum_index.MetadataKey.AppOptions, options, target);
     };
 }
 

package/dist/cjs/enum/index.cjs

@@ -1,7 +1,5 @@
 'use strict';
 
-var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
-
 /**
  * The kind of interaction a `@Command` method handles. Each member is one Discord interaction type,
  * so the handler's parameter type follows from it; entity select menus are separate members for
@@ -27,6 +25,36 @@ var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
     return ReactionHandlerAction;
 }({});
 
-exports.MetadataKey = metadataKey_enum.MetadataKey;
+/**
+ * Centralised metadata keys used across the framework's `Reflect` calls.
+ *
+ * Keeping them here prevents typos, documents the Inversify 8 key rename,
+ * and makes key changes a single-file edit.
+ */ var MetadataKey = /*#__PURE__*/ function(MetadataKey) {
+    /**
+   * Set by Inversify 8's `injectable()` decorator.
+   */ MetadataKey["Injectable"] = "@inversifyjs/core/classIsInjectableFlagReflectKey";
+    /**
+   * Stores the Inversify `Container` instance on a controller class.
+   * Set by `MeoCordFactory.create()`, read by `@UseGuard` at runtime.
+   */ MetadataKey["Container"] = "inversify:container";
+    /**
+   * Stores the `@MeoCord()` options object on the app class.
+   * Read by `MeoCordFactory.create()` to wire up the container.
+   */ MetadataKey["AppOptions"] = "meocord:app-options";
+    /**
+   * TypeScript compiler-emitted metadata listing constructor parameter types.
+   * Requires `"emitDecoratorMetadata": true` in tsconfig.
+   */ MetadataKey["ParamTypes"] = "design:paramtypes";
+    /**
+   * Stores the guard list applied to a method or class via `@UseGuard`.
+   */ MetadataKey["Guards"] = "guards";
+    /**
+   * Stores the `CommandType` on a `@CommandBuilder` class.
+   */ MetadataKey["CommandType"] = "commandType";
+    return MetadataKey;
+}({});
+
 exports.CommandType = CommandType;
+exports.MetadataKey = MetadataKey;
 exports.ReactionHandlerAction = ReactionHandlerAction;

package/dist/cjs/testing/index.cjs

@@ -2,8 +2,10 @@
 
 require('reflect-metadata');
 var inversify = require('inversify');
-var metadataKey_enum = require('../_shared/metadata-key.enum-DG7cVMc4.cjs');
+var enum_index = require('../enum/index.cjs');
 var discord_js = require('discord.js');
+var componentRoutes = require('../_shared/component-routes-RTZZ3t5i.cjs');
+var controller_decorator = require('../_shared/controller.decorator-DnKZ29W4.cjs');
 
 function isValueProvider(p) {
     return 'useValue' in p;
@@ -67,7 +69,7 @@ function isValueProvider(p) {
                 container.bind(provider.provide).toConstantValue(provider.useValue);
             } else {
                 const cls = provider.useClass;
-                if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, cls)) {
+                if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, cls)) {
                     inversify.injectable()(cls);
                 }
                 container.bind(provider.provide).to(cls).inSingletonScope();
@@ -80,11 +82,11 @@ function isValueProvider(p) {
         // Recursively bind controllers and their dependencies, skipping already-bound tokens
         const bindClass = (cls)=>{
             if (container.isBound(cls)) return;
-            if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, cls)) {
+            if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, cls)) {
                 inversify.injectable()(cls);
             }
             container.bind(cls).toSelf().inSingletonScope();
-            const deps = Reflect.getMetadata(metadataKey_enum.MetadataKey.ParamTypes, cls) || [];
+            const deps = Reflect.getMetadata(enum_index.MetadataKey.ParamTypes, cls) || [];
             for (const dep of deps){
                 bindClass(dep);
             }
@@ -92,7 +94,7 @@ function isValueProvider(p) {
         for (const ctrl of this.options.controllers ?? []){
             bindClass(ctrl);
             // Stamp container on controller class so @UseGuard works in tests too
-            Reflect.defineMetadata(metadataKey_enum.MetadataKey.Container, container, ctrl);
+            Reflect.defineMetadata(enum_index.MetadataKey.Container, container, ctrl);
         }
         return new TestingModule(container);
     }
@@ -866,6 +868,60 @@ function findPrototypeMethod(instance, name) {
     return stubDeep(base);
 }
 
+/** The controllers `@MeoCord({ controllers })` registers on an application class. */ function controllersOf(app) {
+    const options = Reflect.getMetadata(enum_index.MetadataKey.AppOptions, app);
+    if (!options) throw new TypeError(`${app.name || 'The given class'} is not decorated with @MeoCord().`);
+    return options.controllers ?? [];
+}
+/**
+ * Resolves which handler a component's customId reaches, the way dispatch does: across every
+ * controller the application registers, for that component type, most specific pattern first.
+ *
+ * Reads decorator metadata only, so it runs in a plain unit test with no Discord client, config
+ * or container. It checks routing alone: guards are not run, and whether the controller's
+ * dependencies are bound is for `MeoCordTestingModule` to test.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @param component - The component type and the customId it carries.
+ * @returns The handler that runs, or `undefined` when no route handles the customId.
+ *
+ * @example
+ * ```ts
+ * const route = resolveRoute(App, { type: CommandType.BUTTON, customId: 'profile/111/8000' })
+ * expect(route?.handler).toBe(ProfileController.prototype.showProfile)
+ * expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
+ * ```
+ */ function resolveRoute(app, component) {
+    if (!controller_decorator.isCustomIdRouted(component.type)) {
+        throw new TypeError(`${component.type} commands are routed by name, not by customId.`);
+    }
+    const routes = componentRoutes.buildComponentRoutes(controllersOf(app));
+    const matched = componentRoutes.matchComponentRoute(routes, (type)=>type === component.type, component.customId);
+    if (!matched) return undefined;
+    const { route, params } = matched;
+    const method = route.meta.methodName;
+    return {
+        controller: route.controllerClass,
+        method,
+        handler: route.controllerClass.prototype[method],
+        params
+    };
+}
+/**
+ * Finds component patterns that can match the same customId, which MeoCord otherwise only warns
+ * about at startup. Patterns are compared within a component type, as dispatch does.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @returns Each conflicting pattern pair, with its component type.
+ *
+ * @example
+ * ```ts
+ * expect(findRouteConflicts(App)).toEqual([])
+ * ```
+ */ function findRouteConflicts(app) {
+    return componentRoutes.findComponentRouteConflicts(componentRoutes.buildComponentRoutes(controllersOf(app)));
+}
+
 exports.MeoCordTestingModule = MeoCordTestingModule;
 exports.TestingModule = TestingModule;
 exports.TestingModuleBuilder = TestingModuleBuilder;
@@ -878,4 +934,6 @@ exports.createMockGuild = createMockGuild;
 exports.createMockInteraction = createMockInteraction;
 exports.createMockMessage = createMockMessage;
 exports.createMockUser = createMockUser;
+exports.findRouteConflicts = findRouteConflicts;
 exports.isMockFunction = isMockFunction;
+exports.resolveRoute = resolveRoute;

package/dist/esm/core/component-routes.js

@@ -0,0 +1,51 @@
+import { findAmbiguousRoutes, getCommandMap } from '../decorator/controller.decorator.js';
+
+/** Every customId-pattern route of the given controllers, most specific first, read from metadata alone. */ function buildComponentRoutes(controllerClasses) {
+    const routes = [];
+    for (const controllerClass of controllerClasses){
+        const commandMap = getCommandMap(controllerClass.prototype);
+        if (!commandMap) continue;
+        for (const [pattern, metaArray] of Object.entries(commandMap)){
+            if (!Array.isArray(metaArray)) continue;
+            for (const meta of metaArray){
+                if (meta.regex) routes.push({
+                    controllerClass,
+                    meta,
+                    pattern
+                });
+            }
+        }
+    }
+    return routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
+}
+/**
+ * The route dispatch runs for a customId: the first, in rank order, whose type `acceptsType` allows
+ * and whose pattern matches, with the captured params.
+ */ function matchComponentRoute(routes, acceptsType, customId) {
+    for (const route of routes){
+        if (!acceptsType(route.meta.type)) continue;
+        const match = route.meta.regex.exec(customId);
+        if (match) return {
+            route,
+            params: {
+                ...match.groups
+            }
+        };
+    }
+    return undefined;
+}
+/** Pattern pairs that can match one customId, compared only within a component type, as dispatch does. */ function findComponentRouteConflicts(routes) {
+    const byType = new Map();
+    for (const { meta, pattern } of routes)byType.set(meta.type, [
+        ...byType.get(meta.type) ?? [],
+        pattern
+    ]);
+    return [
+        ...byType
+    ].flatMap(([type, patterns])=>findAmbiguousRoutes(patterns).map((pair)=>({
+                type,
+                patterns: pair
+            })));
+}
+
+export { buildComponentRoutes, findComponentRouteConflicts, matchComponentRoute };

package/dist/esm/core/meocord.app.js

@@ -1,12 +1,13 @@
 import { ApplicationCommandType, SlashCommandBuilder, MessageFlagsBitField } from 'discord.js';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
-import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getAutocompleteHandlers, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getCommandMap, PARAM_SEPARATOR, getAutocompleteHandlers, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import { sample } from 'lodash-es';
 import { createErrorEmbed } from '../util/embed.util.js';
 import { describeInteraction, hasCustomId, matchesCommandType, resolveCommandPaths, focusedOptionName, resolveOptionParams } from '../util/interaction.util.js';
 import { ReactionHandlerAction, CommandType } from '../enum/controller.enum.js';
 import CliTable3 from 'cli-table3';
+import { buildComponentRoutes, findComponentRouteConflicts, matchComponentRoute } from './component-routes.js';
 
 /** What Discord assumes a command body is when it carries no type of its own. */ const DEFAULT_APPLICATION_COMMAND_TYPE = ApplicationCommandType.ChatInput;
 /**
@@ -182,44 +183,18 @@ class MeoCordApp {
     }
     getComponentRoutes() {
         if (this.componentRoutes) return this.componentRoutes;
-        const routes = [];
-        for (const controllerClass of this.controllerClasses){
-            const commandMap = getCommandMap(this.getInstance(controllerClass));
-            if (!commandMap) continue;
-            for (const [pattern, metaArray] of Object.entries(commandMap)){
-                if (!Array.isArray(metaArray)) continue;
-                for (const meta of metaArray){
-                    if (meta.regex) routes.push({
-                        controllerClass,
-                        meta,
-                        pattern
-                    });
-                }
-            }
-        }
-        routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
+        const routes = buildComponentRoutes(this.controllerClasses);
         this.reportAmbiguousRoutes(routes);
         this.componentRoutes = routes;
         return routes;
     }
     /**
-   * Warns rather than throws: an app whose patterns overlap boots and works today, and
-   * refusing to start would turn a latent mis-route into an outage on upgrade.
+   * Warns rather than throws: an app whose patterns overlap boots and works, and refusing to start
+   * would turn a latent mis-route into an outage.
    */ reportAmbiguousRoutes(routes) {
-        // Grouped by command type first: dispatch only considers routes whose component
-        // type matches the interaction, so a button and a select menu sharing a pattern
-        // are never in competition and reporting them would be a false alarm.
-        const byType = new Map();
-        for (const { meta, pattern } of routes){
-            const patterns = byType.get(meta.type) ?? [];
-            patterns.push(pattern);
-            byType.set(meta.type, patterns);
-        }
-        const collisions = [
-            ...byType.values()
-        ].flatMap((patterns)=>findAmbiguousRoutes(patterns));
-        if (collisions.length === 0) return;
-        this.logger.warn(`${collisions.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + collisions.map(([left, right])=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
+        const conflicts = findComponentRouteConflicts(routes);
+        if (conflicts.length === 0) return;
+        this.logger.warn(`${conflicts.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + conflicts.map(({ patterns: [left, right] })=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
     }
     getAutocompleteRoutes() {
         if (this.autocompleteRoutes) return this.autocompleteRoutes;
@@ -265,14 +240,12 @@ class MeoCordApp {
         // Commands match their registered name exactly and cannot overlap.
         if (hasCustomId(interaction)) {
             const customId = interaction.customId;
-            for (const { controllerClass, meta } of this.getComponentRoutes()){
-                // A button and a select menu may legitimately share a customId shape, so the
-                // pattern alone does not identify the handler -- the component type does.
-                if (!matchesCommandType(meta.type, interaction)) continue;
-                const match = meta.regex.exec(customId);
-                if (!match) continue;
-                interaction.dynamicParams = match.groups ?? {};
-                await this.executeCommand(this.getInstance(controllerClass), meta, interaction, customId);
+            // The component type as well as the pattern: a button and a select menu may share a customId shape.
+            const matched = matchComponentRoute(this.getComponentRoutes(), (type)=>matchesCommandType(type, interaction), customId);
+            if (matched) {
+                const { route, params } = matched;
+                interaction.dynamicParams = params;
+                await this.executeCommand(this.getInstance(route.controllerClass), route.meta, interaction, customId);
                 return;
             }
         }

package/dist/esm/package.json.js

@@ -1,4 +1,4 @@
-var version = "4.0.0-beta.4";
+var version = "4.0.0";
 var packageJson = {
 	version: version};
 

package/dist/esm/testing/index.js

@@ -1,3 +1,4 @@
 export { MeoCordTestingModule, TestingModule, TestingModuleBuilder } from './meocord-testing-module.js';
 export { createChatInputOptions, createMock, createMockChannel, createMockClient, createMockGuild, createMockInteraction, createMockMessage, createMockUser } from './mock-interaction.js';
 export { createMockFn, isMockFunction } from './mock-fn.js';
+export { findRouteConflicts, resolveRoute } from './routing.js';

package/dist/esm/testing/routing.js

@@ -0,0 +1,59 @@
+import { MetadataKey } from '../enum/metadata-key.enum.js';
+import { findComponentRouteConflicts, buildComponentRoutes, matchComponentRoute } from '../core/component-routes.js';
+import { isCustomIdRouted } from '../util/interaction.util.js';
+
+/** The controllers `@MeoCord({ controllers })` registers on an application class. */ function controllersOf(app) {
+    const options = Reflect.getMetadata(MetadataKey.AppOptions, app);
+    if (!options) throw new TypeError(`${app.name || 'The given class'} is not decorated with @MeoCord().`);
+    return options.controllers ?? [];
+}
+/**
+ * Resolves which handler a component's customId reaches, the way dispatch does: across every
+ * controller the application registers, for that component type, most specific pattern first.
+ *
+ * Reads decorator metadata only, so it runs in a plain unit test with no Discord client, config
+ * or container. It checks routing alone: guards are not run, and whether the controller's
+ * dependencies are bound is for `MeoCordTestingModule` to test.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @param component - The component type and the customId it carries.
+ * @returns The handler that runs, or `undefined` when no route handles the customId.
+ *
+ * @example
+ * ```ts
+ * const route = resolveRoute(App, { type: CommandType.BUTTON, customId: 'profile/111/8000' })
+ * expect(route?.handler).toBe(ProfileController.prototype.showProfile)
+ * expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
+ * ```
+ */ function resolveRoute(app, component) {
+    if (!isCustomIdRouted(component.type)) {
+        throw new TypeError(`${component.type} commands are routed by name, not by customId.`);
+    }
+    const routes = buildComponentRoutes(controllersOf(app));
+    const matched = matchComponentRoute(routes, (type)=>type === component.type, component.customId);
+    if (!matched) return undefined;
+    const { route, params } = matched;
+    const method = route.meta.methodName;
+    return {
+        controller: route.controllerClass,
+        method,
+        handler: route.controllerClass.prototype[method],
+        params
+    };
+}
+/**
+ * Finds component patterns that can match the same customId, which MeoCord otherwise only warns
+ * about at startup. Patterns are compared within a component type, as dispatch does.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @returns Each conflicting pattern pair, with its component type.
+ *
+ * @example
+ * ```ts
+ * expect(findRouteConflicts(App)).toEqual([])
+ * ```
+ */ function findRouteConflicts(app) {
+    return findComponentRouteConflicts(buildComponentRoutes(controllersOf(app)));
+}
+
+export { findRouteConflicts, resolveRoute };

package/dist/types/core/index.d.cts

@@ -54,8 +54,8 @@ declare class MeoCordApp {
     private componentRoutes?;
     private getComponentRoutes;
     /**
-     * Warns rather than throws: an app whose patterns overlap boots and works today, and
-     * refusing to start would turn a latent mis-route into an outage on upgrade.
+     * Warns rather than throws: an app whose patterns overlap boots and works, and refusing to start
+     * would turn a latent mis-route into an outage.
      */
     private reportAmbiguousRoutes;
     /**

package/dist/types/core/index.d.ts

@@ -54,8 +54,8 @@ declare class MeoCordApp {
     private componentRoutes?;
     private getComponentRoutes;
     /**
-     * Warns rather than throws: an app whose patterns overlap boots and works today, and
-     * refusing to start would turn a latent mis-route into an outage on upgrade.
+     * Warns rather than throws: an app whose patterns overlap boots and works, and refusing to start
+     * would turn a latent mis-route into an outage.
      */
     private reportAmbiguousRoutes;
     /**

package/dist/types/testing/index.d.cts

@@ -1,8 +1,8 @@
 import { ServiceIdentifier, Container } from 'inversify';
 import { GuardInterface } from '../interface/index.cjs';
 import { CacheType, CommandInteractionOptionResolver, Channel, Client, Guild, Message, User } from 'discord.js';
+import { CommandType } from '../enum/index.cjs';
 import '@rsbuild/core';
-import '../controller.enum-BL6wEQls.cjs';
 
 interface ValueProvider<T = any> {
     provide: ServiceIdentifier<T>;
@@ -268,5 +268,65 @@ interface ChatInputOptions {
  */
 declare function createChatInputOptions<Cached extends CacheType = any>(opts?: ChatInputOptions): DeepMocked<CommandInteractionOptionResolver<Cached>>;
 
-export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, isMockFunction };
-export type { ChatInputOptions, ClassProvider, DeepMocked, Mock, MockInstance, MockProps, MockResult, MockState, MockedFunction, Provider, TestingModuleOptions, ValueProvider };
+type ControllerClass = new (...args: any[]) => any;
+
+/** The command types routed by customId pattern: buttons, select menus and modals. */
+type ComponentCommandType = Exclude<CommandType, CommandType.SLASH | CommandType.CONTEXT_MENU | CommandType.PRIMARY_ENTRY_POINT>;
+/** The handler a component interaction reaches. */
+interface ResolvedRoute {
+    /** The controller class declaring the handler. */
+    controller: ControllerClass;
+    /** The name of the handler method. */
+    method: string;
+    /**
+     * The handler method itself, for assertions that survive renaming it:
+     * `expect(route?.handler).toBe(ProfileController.prototype.showProfile)`.
+     */
+    handler: (...args: any[]) => unknown;
+    /** The values captured by the pattern's `{name}` segments. */
+    params: Record<string, string>;
+}
+/** Two patterns of one component type that can both match a customId. */
+interface RouteConflict {
+    type: ComponentCommandType;
+    patterns: [string, string];
+}
+/**
+ * Resolves which handler a component's customId reaches, the way dispatch does: across every
+ * controller the application registers, for that component type, most specific pattern first.
+ *
+ * Reads decorator metadata only, so it runs in a plain unit test with no Discord client, config
+ * or container. It checks routing alone: guards are not run, and whether the controller's
+ * dependencies are bound is for `MeoCordTestingModule` to test.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @param component - The component type and the customId it carries.
+ * @returns The handler that runs, or `undefined` when no route handles the customId.
+ *
+ * @example
+ * ```ts
+ * const route = resolveRoute(App, { type: CommandType.BUTTON, customId: 'profile/111/8000' })
+ * expect(route?.handler).toBe(ProfileController.prototype.showProfile)
+ * expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
+ * ```
+ */
+declare function resolveRoute(app: ControllerClass, component: {
+    type: ComponentCommandType;
+    customId: string;
+}): ResolvedRoute | undefined;
+/**
+ * Finds component patterns that can match the same customId, which MeoCord otherwise only warns
+ * about at startup. Patterns are compared within a component type, as dispatch does.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @returns Each conflicting pattern pair, with its component type.
+ *
+ * @example
+ * ```ts
+ * expect(findRouteConflicts(App)).toEqual([])
+ * ```
+ */
+declare function findRouteConflicts(app: ControllerClass): RouteConflict[];
+
+export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, findRouteConflicts, isMockFunction, resolveRoute };
+export type { ChatInputOptions, ClassProvider, ComponentCommandType, DeepMocked, Mock, MockInstance, MockProps, MockResult, MockState, MockedFunction, Provider, ResolvedRoute, RouteConflict, TestingModuleOptions, ValueProvider };

package/dist/types/testing/index.d.ts

@@ -1,8 +1,8 @@
 import { ServiceIdentifier, Container } from 'inversify';
 import { GuardInterface } from '../interface/index.js';
 import { CacheType, CommandInteractionOptionResolver, Channel, Client, Guild, Message, User } from 'discord.js';
+import { CommandType } from '../enum/index.js';
 import '@rsbuild/core';
-import '../controller.enum-BL6wEQls.js';
 
 interface ValueProvider<T = any> {
     provide: ServiceIdentifier<T>;
@@ -268,5 +268,65 @@ interface ChatInputOptions {
  */
 declare function createChatInputOptions<Cached extends CacheType = any>(opts?: ChatInputOptions): DeepMocked<CommandInteractionOptionResolver<Cached>>;
 
-export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, isMockFunction };
-export type { ChatInputOptions, ClassProvider, DeepMocked, Mock, MockInstance, MockProps, MockResult, MockState, MockedFunction, Provider, TestingModuleOptions, ValueProvider };
+type ControllerClass = new (...args: any[]) => any;
+
+/** The command types routed by customId pattern: buttons, select menus and modals. */
+type ComponentCommandType = Exclude<CommandType, CommandType.SLASH | CommandType.CONTEXT_MENU | CommandType.PRIMARY_ENTRY_POINT>;
+/** The handler a component interaction reaches. */
+interface ResolvedRoute {
+    /** The controller class declaring the handler. */
+    controller: ControllerClass;
+    /** The name of the handler method. */
+    method: string;
+    /**
+     * The handler method itself, for assertions that survive renaming it:
+     * `expect(route?.handler).toBe(ProfileController.prototype.showProfile)`.
+     */
+    handler: (...args: any[]) => unknown;
+    /** The values captured by the pattern's `{name}` segments. */
+    params: Record<string, string>;
+}
+/** Two patterns of one component type that can both match a customId. */
+interface RouteConflict {
+    type: ComponentCommandType;
+    patterns: [string, string];
+}
+/**
+ * Resolves which handler a component's customId reaches, the way dispatch does: across every
+ * controller the application registers, for that component type, most specific pattern first.
+ *
+ * Reads decorator metadata only, so it runs in a plain unit test with no Discord client, config
+ * or container. It checks routing alone: guards are not run, and whether the controller's
+ * dependencies are bound is for `MeoCordTestingModule` to test.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @param component - The component type and the customId it carries.
+ * @returns The handler that runs, or `undefined` when no route handles the customId.
+ *
+ * @example
+ * ```ts
+ * const route = resolveRoute(App, { type: CommandType.BUTTON, customId: 'profile/111/8000' })
+ * expect(route?.handler).toBe(ProfileController.prototype.showProfile)
+ * expect(route?.params).toEqual({ ownerId: '111', uid: '8000' })
+ * ```
+ */
+declare function resolveRoute(app: ControllerClass, component: {
+    type: ComponentCommandType;
+    customId: string;
+}): ResolvedRoute | undefined;
+/**
+ * Finds component patterns that can match the same customId, which MeoCord otherwise only warns
+ * about at startup. Patterns are compared within a component type, as dispatch does.
+ *
+ * @param app - The application class decorated with `@MeoCord`.
+ * @returns Each conflicting pattern pair, with its component type.
+ *
+ * @example
+ * ```ts
+ * expect(findRouteConflicts(App)).toEqual([])
+ * ```
+ */
+declare function findRouteConflicts(app: ControllerClass): RouteConflict[];
+
+export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, findRouteConflicts, isMockFunction, resolveRoute };
+export type { ChatInputOptions, ClassProvider, ComponentCommandType, DeepMocked, Mock, MockInstance, MockProps, MockResult, MockState, MockedFunction, Provider, ResolvedRoute, RouteConflict, TestingModuleOptions, ValueProvider };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "meocord",
   "description": "Decorator-based Discord bot framework built on discord.js. Brings NestJS-style controllers, dependency injection, guards, and testing utilities to bot development — with a full CLI and TypeScript-first design.",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0",
   "type": "module",
   "engines": {
     "node": ">=22.13"

package/dist/cjs/_shared/metadata-key.enum-DG7cVMc4.cjs

@@ -1,33 +0,0 @@
-'use strict';
-
-/**
- * Centralised metadata keys used across the framework's `Reflect` calls.
- *
- * Keeping them here prevents typos, documents the Inversify 8 key rename,
- * and makes key changes a single-file edit.
- */ var MetadataKey = /*#__PURE__*/ function(MetadataKey) {
-    /**
-   * Set by Inversify 8's `injectable()` decorator.
-   */ MetadataKey["Injectable"] = "@inversifyjs/core/classIsInjectableFlagReflectKey";
-    /**
-   * Stores the Inversify `Container` instance on a controller class.
-   * Set by `MeoCordFactory.create()`, read by `@UseGuard` at runtime.
-   */ MetadataKey["Container"] = "inversify:container";
-    /**
-   * Stores the `@MeoCord()` options object on the app class.
-   * Read by `MeoCordFactory.create()` to wire up the container.
-   */ MetadataKey["AppOptions"] = "meocord:app-options";
-    /**
-   * TypeScript compiler-emitted metadata listing constructor parameter types.
-   * Requires `"emitDecoratorMetadata": true` in tsconfig.
-   */ MetadataKey["ParamTypes"] = "design:paramtypes";
-    /**
-   * Stores the guard list applied to a method or class via `@UseGuard`.
-   */ MetadataKey["Guards"] = "guards";
-    /**
-   * Stores the `CommandType` on a `@CommandBuilder` class.
-   */ MetadataKey["CommandType"] = "commandType";
-    return MetadataKey;
-}({});
-
-exports.MetadataKey = MetadataKey;