meocord 4.0.0-beta.3 → 4.0.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # meocord
 
+## 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
+
+- [#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).
+
 ## 4.0.0-beta.3
 
 ### Patch Changes

package/README.md

@@ -273,7 +273,9 @@ See [Self-contained builds](#self-contained-builds) for when to turn on `bundleD
 
 ### ESLint
 
-MeoCord exports a base ESLint config from `meocord/eslint`. Extend it as needed:
+MeoCord exports a base ESLint config from `meocord/eslint`. It lints your TypeScript, `meocord.config.ts`
+included, with type information from `tsconfig.json`, `tsconfig.test.json` and `tsconfig.eslint.json`; a
+file ESLint reports as not included in any of them needs listing in one. Extend it as needed:
 
 ```javascript
 import meocordEslint, { typescriptConfig } from 'meocord/eslint'
@@ -687,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`
 
@@ -882,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-9nIxOp9y.cjs → controller.decorator-DnKZ29W4.cjs}

@@ -3,18 +3,11 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var enum_index = require('../enum/index.cjs');
-var metadataKey_enum = require('./metadata-key.enum-aABGdodb.cjs');
 var discord_js = require('discord.js');
 
 /**
- * The discord.js class each command type is handled by.
- *
- * One table rather than a chain of `isButton() || isStringSelectMenu() || ...`: the
- * registration guard in `@Command`, the dispatcher, and the type-level
- * `CommandInteractionType` all have to agree on what a command type accepts, and a
- * chain repeated in three files drifts the moment a fifth select menu appears. Adding
- * a `CommandType` member without an entry here is a compile error, not a silent
- * fall-through to "Command not found!".
+ * The discord.js class check for each command type, shared by `@Command`, the dispatcher and
+ * `CommandInteractionType`. A `CommandType` without an entry here fails to compile.
  */ const INTERACTION_MATCHERS = {
     [enum_index.CommandType.SLASH]: (interaction)=>interaction instanceof discord_js.ChatInputCommandInteraction,
     [enum_index.CommandType.CONTEXT_MENU]: (interaction)=>interaction instanceof discord_js.ContextMenuCommandInteraction,
@@ -32,47 +25,24 @@ var discord_js = require('discord.js');
     enum_index.CommandType.CONTEXT_MENU,
     enum_index.CommandType.PRIMARY_ENTRY_POINT
 ]);
-/**
- * Whether an interaction is the kind the given command type handles.
- *
- * @param type - The command type declared on `@Command`.
- * @param interaction - The interaction being dispatched.
- */ function matchesCommandType(type, interaction) {
+/** Whether an interaction is the kind the given command type handles. */ function matchesCommandType(type, interaction) {
     const matches = INTERACTION_MATCHERS[type];
     return matches !== undefined && matches(interaction);
 }
 /**
- * Whether the command type is routed by matching a customId pattern.
- *
- * Components carry an application-defined customId and so are matched by pattern;
- * commands carry a name Discord itself registered and are matched exactly.
- *
- * @param type - The command type declared on `@Command`.
+ * Whether a command type is routed by customId pattern: components carry an application-defined
+ * customId, while commands are matched by the name Discord registered.
  */ function isCustomIdRouted(type) {
     return !NAME_ROUTED_TYPES.has(type);
 }
-/**
- * Whether an interaction carries a customId, and so can be routed by pattern.
- *
- * @param interaction - The interaction being dispatched.
- */ function hasCustomId(interaction) {
+/** Whether an interaction carries a customId, and so can be routed by pattern. */ function hasCustomId(interaction) {
     return interaction instanceof discord_js.MessageComponentInteraction || interaction instanceof discord_js.ModalSubmitInteraction;
 }
 /** Separates a command from its subcommand group and subcommand in a route key. */ const COMMAND_PATH_SEPARATOR = ' ';
 /**
- * The route keys a chat input interaction can be handled by, most specific first.
- *
- * Discord sends `/settings notify email` as one interaction named `settings`, so
- * routing on `commandName` alone gives every subcommand of a command the same handler
- * — and the framework would run whichever one was declared first. The full path is
- * tried before the bare name so a command can either split its subcommands across
- * methods or keep handling them in one, but never both by accident.
- *
- * A group is never dropped on the way down: `settings notify email` does not fall back
- * to `settings email`, because a second group could declare its own `email` and the
- * two would be indistinguishable.
- *
- * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * The route keys a chat input interaction can be handled by, most specific first:
+ * `settings notify email`, then `settings`. Discord names the whole interaction `settings`, so the
+ * full path comes first; a group is never skipped, since two groups may share a subcommand name.
  * @returns The keys to look up, most specific first.
  */ function resolveCommandPaths(interaction) {
     const { commandName } = interaction;
@@ -99,24 +69,14 @@ var discord_js = require('discord.js');
     discord_js.ApplicationCommandOptionType.SubcommandGroup
 ]);
 /**
- * The value a handler should receive for one option.
- *
- * Discord sends entity options as a snowflake plus a `resolved` payload, and discord.js
- * puts that payload on the option as `user`/`role`/`channel`/`attachment`. Passing
- * `value` alone would hand the handler a bare id string for `@user`, forcing every
- * handler to re-fetch what the gateway already delivered.
+ * The value a handler receives for one option: the resolved user, role, channel or attachment
+ * discord.js attaches, rather than a bare snowflake to re-fetch.
  */ function resolveOptionValue(option) {
     return option.attachment ?? option.channel ?? option.role ?? option.user ?? option.member ?? option.value;
 }
 /**
- * Flattens a chat input interaction's options into the params record handlers receive.
- *
- * Subcommand and subcommand-group options are containers, not values — for
- * `/settings notify email true` the top level holds only `notify`. Recursing past them
- * means a subcommand handler sees `{ email: true }`, the same shape a flat command's
- * handler sees.
- *
- * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * Flattens an interaction's options into the params record handlers receive, looking through
+ * subcommand and group containers, so `/settings notify email true` yields `{ email: true }`.
  * @returns Each supplied option keyed by name, with entity options resolved.
  */ function resolveOptionParams(interaction) {
     const data = interaction.options?.data;
@@ -135,14 +95,8 @@ var discord_js = require('discord.js');
     return params;
 }
 /**
- * The name of the option the user is currently typing, or `undefined`.
- *
- * `getFocused` throws when nothing is focused rather than returning null, and it is
- * absent altogether on a hand-built test double. Neither is worth failing a dispatch
- * over — an autocomplete with no focused option simply matches no option-specific
- * handler.
- *
- * @param interaction - The autocomplete interaction being dispatched.
+ * The name of the option the user is typing, or undefined when nothing is focused; `getFocused`
+ * throws then, and hand-built test doubles lack it entirely.
  */ function focusedOptionName(interaction) {
     if (typeof interaction.options?.getFocused !== 'function') return undefined;
     try {
@@ -254,21 +208,9 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
 /** The character a parameter will not cross, so one pattern segment maps to one value. */ const PARAM_SEPARATOR = '/';
 /** Escapes a literal stretch of a pattern so only placeholders stay meaningful. */ const escapeLiteral = (literal)=>literal.replace(/[/\\^$*+?.()|[\]{}]/g, '\\$&');
 /**
- * Helper function to create regex and parameter mappings from a pattern string.
- *
- * A `{name}` matches anything up to the next `/`, the same rule Express and Rails use
- * for a path segment. That is what lets a value the application does not control — a
- * uuid, an opaque vendor id, a slug — be captured whole without the author annotating
- * anything, since a hyphen inside it is data rather than structure.
- *
- * It also keeps neighbouring patterns apart: `profile/{uuid}` and `profile/{uuid}/{id}`
- * cannot both match one id, because a parameter cannot swallow the separator between
- * them. Patterns separated by `-` instead have no such boundary, so a pair like
- * `profile-{uuid}` and `profile-{uuid}-{id}` is ambiguous — {@link findAmbiguousRoutes}
- * reports those at registration.
- *
- * @param pattern - The pattern string to parse.
- * @returns The regex, the parameter names, and how specific the pattern is.
+ * Compiles a pattern into a regex, its parameter names and its specificity. A `{name}` matches up to
+ * the next `/`, so a uuid is captured whole and `profile/{uuid}` never overlaps `profile/{uuid}/{id}`;
+ * `-`-separated patterns can, which {@link findAmbiguousRoutes} reports at registration.
  */ function createRegexFromPattern(pattern) {
     const params = [];
     let regexPattern = '';
@@ -368,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}`);
             }
@@ -405,19 +347,13 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     return Reflect.getMetadata(COMMAND_METADATA_KEY, controller);
 }
 /**
- * Decorator to register an autocomplete handler for a chat input command's option.
+ * Registers an autocomplete handler for an option of a chat input command.
  *
- * Autocomplete is a separate interaction from the command it belongs to, and Discord
- * sends it while the user is still typing. It is not a `@Command`: nothing is
- * registered for it — the option's own `setAutocomplete(true)` is what turns it on —
- * and it is answered with `interaction.respond()` rather than a reply. Leaving it
- * unhandled is not silent to the user: the client shows a loading state until the
- * three-second window closes.
+ * Enable it on the option with `setAutocomplete(true)` and answer with `interaction.respond()`.
  *
- * @param commandPath - The command to complete, e.g. `settings` or `settings notify email`
- *   for a subcommand. Parts are separated by a single space, as Discord displays them.
- * @param optionName - The option to complete. Omit to handle every option of the command,
- *   branching on `interaction.options.getFocused(true)`.
+ * @param commandPath - The command, such as `search` or `settings notify email` for a subcommand.
+ * @param optionName - The option to complete. Omit to handle every option, branching on
+ *   `interaction.options.getFocused(true)`.
  *
  * @example
  * ```typescript
@@ -439,13 +375,8 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     };
 }
 /**
- * Retrieves autocomplete handler metadata from a given controller.
- *
- * Handlers naming an option come first, so a command-wide handler acts as the fallback
- * for options no specific handler claimed rather than shadowing them by declaration order.
- *
- * @param controller - The controller class instance.
- * @returns The registered autocomplete handlers, most specific first.
+ * Returns a controller's autocomplete handlers, option-specific ones first.
+ * @param controller - The controller instance.
  */ function getAutocompleteHandlers(controller) {
     const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, controller) || [];
     return [
@@ -453,7 +384,7 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
     ].sort((a, b)=>Number(Boolean(b.optionName)) - Number(Boolean(a.optionName)));
 }
 /**
- * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
+ * Marks a class as a controller, to be listed in `@MeoCord({ controllers })`.
  *
  * @example
  * ```typescript
@@ -463,28 +394,20 @@ const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
  *
  *   @Command('ping', PingCommandBuilder)
  *   async ping(interaction: ChatInputCommandInteraction) {
- *     const response = await this.pingService.handlePing()
- *     await interaction.reply(response)
+ *     await interaction.reply(await this.pingService.handlePing())
  *   }
  * }
  * ```
  */ function Controller() {
     return function(target) {
-        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+        if (!Reflect.hasMetadata(enum_index.MetadataKey.Injectable, target)) {
             inversify.injectable()(target);
         }
     };
 }
 /**
- * Finds pattern pairs that can both match one customId.
- *
- * Patterns of different segment counts are disjoint, because a parameter cannot cross
- * `/`. Within the same count, two patterns overlap unless some position holds literals
- * that differ: `a/{x}/c` and `a/b/{y}` both take `a/b/c`, and neither is more literal
- * than the other, so ranking cannot settle it either.
- *
- * @param patterns - The registered patterns.
- * @returns Each ambiguous pair, once, in the order the patterns were given.
+ * Finds pairs of customId patterns that can both match one id, such as `a/{x}/c` and `a/b/{y}`.
+ * @returns Each ambiguous pair once, in the order the patterns were given.
  */ function findAmbiguousRoutes(patterns) {
     const isParam = (segment)=>PLACEHOLDER_PATTERN.test(segment);
     const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);
@@ -524,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/_shared/{theme-Dqwlnz0m.cjs → theme-C8w8ivsR.cjs}

@@ -13,17 +13,9 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 let cachedConfig;
 let configLoaded = false;
 /**
- * Loads the configuration a built application runs with: `dist/meocord.config.mjs`, which
- * `meocord build` compiles from `meocord.config.ts`.
- *
- * Reads only the compiled file, which is plain JavaScript and needs no transpiler, tsconfig or
- * source. Reading `meocord.config.ts` is {@link loadMeoCordSourceConfig}'s job, and it lives in its
- * own module because it needs jiti: this one is imported by the logger and the factory, so a
- * bot built with `bundleDependencies` bundles whatever it imports.
- *
- * The result is cached after the first load.
- *
- * @returns The configuration, or undefined when there is no compiled config or it fails to load.
+ * Loads the configuration a built application runs with, `dist/meocord.config.mjs`, and caches it.
+ * Imports no transpiler, since the logger and the factory import this module into every bot.
+ * @returns The configuration, or undefined when the compiled config is missing or fails to load.
  */ function loadMeoCordConfig() {
     if (configLoaded) return cachedConfig;
     configLoaded = true;
@@ -39,7 +31,7 @@ let configLoaded = false;
     try {
         // Called through a variable so a bundler does not try to resolve the path while building the
         // application; the file is only there once the build is done.
-        const load = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('_shared/theme-Dqwlnz0m.cjs', document.baseURI).href)));
+        const load = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('_shared/theme-C8w8ivsR.cjs', document.baseURI).href)));
         const loaded = load(compiledPath);
         return loaded.default ?? loaded;
     } catch (error) {

package/dist/cjs/common/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var theme = require('../_shared/theme-Dqwlnz0m.cjs');
+var theme = require('../_shared/theme-C8w8ivsR.cjs');
 require('node:util');
 require('dayjs');
 require('dayjs/plugin/utc.js');