meocord 2.1.1 → 3.0.0

package/README.md

@@ -16,6 +16,7 @@
   - [meocord.config.ts](#meocordconfigts)
   - [ESLint](#eslint)
 - [CLI Reference](#cli-reference)
+- [Command Parameters](#command-parameters)
 - [Guards](#guards)
 - [Custom Decorators](#custom-decorators)
 - [Testing](#testing)
@@ -240,6 +241,70 @@ npx meocord g --help              # list all generator sub-commands
 
 ---
 
+## Command Parameters
+
+Buttons, select menus and modals route on their `customId`, and a pattern can capture parts of it. Captured values arrive as the handler's second argument.
+
+```typescript
+@Command('profile/{ownerId}/{uid}', CommandType.BUTTON)
+async showProfile(interaction: ButtonInteraction, { ownerId, uid }) {
+  // customId `profile/123/800000001` gives ownerId '123', uid '800000001'
+}
+```
+
+`/` separates segments, and **a parameter must occupy a whole segment** — the same rule Express and Rails use for a path. A pattern that breaks it is rejected when the command is registered:
+
+```typescript
+@Command('profile/{uuid}', CommandType.BUTTON)      // fine
+@Command('gi-profile/{ownerId}', CommandType.BUTTON) // fine — the hyphen is inside a literal segment
+@Command('profile-{uuid}', CommandType.BUTTON)       // throws
+```
+
+```
+Invalid pattern "profile-{uuid}": {uuid} must occupy a whole segment, so it has to be
+preceded and followed by "/" or by the ends of the pattern. Write "a/{uuid}" rather
+than "a-{uuid}".
+```
+
+### Why the rule exists
+
+A parameter matches anything up to the next `/`, so an identifier you do not control is captured whole — a hyphen inside a uuid is data, not structure:
+
+```typescript
+@Command('profile/{uuid}', CommandType.BUTTON)
+// `profile/8400e29b-41d4-a716`  ->  uuid '8400e29b-41d4-a716'
+```
+
+That only works because the separator cannot appear inside a value. Let a parameter share a segment with a literal and the boundary disappears: `profile-{uuid}` and `profile-{uuid}-{id}` both match `profile-a-b-c`, and neither reading is more correct than the other. No rule can settle that afterwards, so the shape is refused up front.
+
+Segment counts then keep neighbours apart on their own:
+
+```typescript
+@Command('profile/{uuid}', CommandType.BUTTON)        // profile/8400e29b-41d4-a716
+@Command('profile/{uuid}/{id}', CommandType.BUTTON)   // profile/8400e29b-41d4-a716/99
+```
+
+Each id matches exactly one of them.
+
+### Overlapping patterns
+
+Two patterns with the same segment count can still both match. The one spelling out more literal text wins, so declaration order and file layout never decide it:
+
+```typescript
+@Command('profile/summary/{ownerId}/{uid}', CommandType.BUTTON)  // wins profile/summary/123/456
+@Command('profile/{uuid}/{other}/{uid}', CommandType.BUTTON)     // wins everything else
+```
+
+Ties between equally literal patterns go to the one with fewer parameters. The ranking is computed once when commands are registered, so dispatch stays a single ordered lookup.
+
+Where two patterns trade a literal for a parameter in opposite positions — `a/{x}/c` and `a/b/{y}` both take `a/b/c` — neither is more literal, and MeoCord logs a warning at startup naming the pair.
+
+### When nothing matches
+
+An unroutable interaction replies "Command not found!" to the user and logs a warning naming the `customId` or command that failed to match. If a control appears dead, that log line is the first place to look.
+
+---
+
 ## Guards
 
 Guards run before the handler method. Each guard implements `canActivate` — return `true` to allow, `false` to block.

package/dist/cjs/_shared/{controller.decorator-DX5lFlPZ.cjs → controller.decorator-CC6BjHkS.cjs}

@@ -79,29 +79,62 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
  */ function getMessageHandlers(controller) {
     return Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, controller) || [];
 }
+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 An object containing the generated regex and parameter names.
+ * @returns The regex, the parameter names, and how specific the pattern is.
  */ function createRegexFromPattern(pattern) {
     const params = [];
-    // Escape special characters except for {} and -
-    const escapedPattern = pattern.replace(/[/\\^$*+?.()|[\]]/g, '\\$&') // Removed hyphen `-` from this list
-    ;
-    // Replace placeholders with named capturing groups
-    const regexPattern = escapedPattern.replace(/\{(\w+)}/g, (_, param)=>{
-        if (!/^\w+$/.test(param)) {
-            throw new Error(`Invalid parameter name: ${param}. Parameter names must be alphanumeric.`);
+    let regexPattern = '';
+    let cursor = 0;
+    let literalLength = 0;
+    PLACEHOLDER_PATTERN.lastIndex = 0;
+    let match;
+    while((match = PLACEHOLDER_PATTERN.exec(pattern)) !== null){
+        const [placeholder, param] = match;
+        const literal = pattern.slice(cursor, match.index);
+        const after = pattern[match.index + placeholder.length];
+        // A parameter has to own its segment. Sharing one with a literal leaves no
+        // boundary a sibling pattern can be told apart by, and the resulting overlap has
+        // no correct reading -- `profile-{uuid}` and `profile-{uuid}-{id}` both take
+        // `profile-a-b`. Registration is the last point where that is still fixable.
+        if (literal !== '' && !literal.endsWith(PARAM_SEPARATOR) || after !== undefined && after !== PARAM_SEPARATOR) {
+            throw new Error(`Invalid pattern "${pattern}": {${param}} must occupy a whole segment, so it has to be ` + `preceded and followed by "${PARAM_SEPARATOR}" or by the ends of the pattern. ` + `Write "a${PARAM_SEPARATOR}{${param}}" rather than "a-{${param}}".`);
         }
+        literalLength += literal.length;
+        regexPattern += escapeLiteral(literal);
+        regexPattern += `(?<${param}>[^${PARAM_SEPARATOR}]+)`;
         params.push(param);
-        return `(?<${param}>[a-zA-Z0-9]+)`;
-    });
-    // Construct the final regex
+        cursor = match.index + placeholder.length;
+    }
+    const trailing = pattern.slice(cursor);
+    literalLength += trailing.length;
+    regexPattern += escapeLiteral(trailing);
     const regex = new RegExp(`^${regexPattern}$`);
+    // Literal text is the signal: a pattern spelling out more of the id describes it
+    // more exactly than one leaving it to a parameter. Fewer parameters breaks a tie
+    // between equal-length patterns, so the ranking is total and never falls back to
+    // declaration order.
+    const specificity = literalLength * 1000 - params.length;
     return {
         regex,
-        params
+        params,
+        specificity
     };
 }
 /**
@@ -145,6 +178,7 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
         let commandType;
         let regex;
         let dynamicParams = [];
+        let specificity;
         // Determine command type and builder
         if (typeof builderOrType === 'function') {
             const builderObj = new builderOrType();
@@ -157,9 +191,10 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
             commandType = builderOrType;
         }
         if (commandType !== enum_index.CommandType.SLASH && commandType !== enum_index.CommandType.CONTEXT_MENU) {
-            const { regex: generatedRegex, params } = createRegexFromPattern(commandName);
+            const { regex: generatedRegex, params, specificity: patternSpecificity } = createRegexFromPattern(commandName);
             regex = generatedRegex;
             dynamicParams = params;
+            specificity = patternSpecificity;
         }
         // Ensure commandName supports multiple entries
         if (!commands[commandName]) {
@@ -170,7 +205,8 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
             builder: builderInstance,
             type: commandType,
             regex,
-            dynamicParams
+            dynamicParams,
+            specificity
         });
         Reflect.defineMetadata(COMMAND_METADATA_KEY, commands, target);
     };
@@ -206,11 +242,47 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
         }
     };
 }
+/**
+ * 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.
+ */ function findAmbiguousRoutes(patterns) {
+    const isParam = (segment)=>PLACEHOLDER_PATTERN.test(segment);
+    const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);
+    const collisions = [];
+    for(let i = 0; i < patterns.length; i++){
+        for(let j = i + 1; j < patterns.length; j++){
+            const left = segmentsOf(patterns[i]);
+            const right = segmentsOf(patterns[j]);
+            if (left.length !== right.length) continue;
+            const disjoint = left.some((segment, index)=>{
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const leftIsParam = isParam(segment);
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const rightIsParam = isParam(right[index]);
+                return !leftIsParam && !rightIsParam && segment !== right[index];
+            });
+            if (!disjoint) collisions.push([
+                patterns[i],
+                patterns[j]
+            ]);
+        }
+    }
+    return collisions;
+}
 
 exports.Command = Command;
 exports.Controller = Controller;
 exports.MessageHandler = MessageHandler;
+exports.PARAM_SEPARATOR = PARAM_SEPARATOR;
 exports.ReactionHandler = ReactionHandler;
+exports.findAmbiguousRoutes = findAmbiguousRoutes;
 exports.getCommandMap = getCommandMap;
 exports.getMessageHandlers = getMessageHandlers;
 exports.getReactionHandlers = getReactionHandlers;

package/dist/cjs/core/index.cjs

@@ -4,7 +4,7 @@ require('reflect-metadata');
 var inversify = require('inversify');
 var discord_js = require('discord.js');
 var theme = require('../_shared/theme-Bz-D4RbT.cjs');
-var controller_decorator = require('../_shared/controller.decorator-DX5lFlPZ.cjs');
+var controller_decorator = require('../_shared/controller.decorator-CC6BjHkS.cjs');
 var lodashEs = require('lodash-es');
 var enum_index = require('../enum/index.cjs');
 var Table = require('cli-table3');
@@ -26,6 +26,15 @@ const createErrorEmbed = (description)=>{
     return embed;
 };
 
+/** Identifies an unmatched interaction for the log, by whichever field would have routed it. */ function describeUnmatched(interaction) {
+    if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
+        return `command "${interaction.commandName}"`;
+    }
+    if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+        return `customId "${interaction.customId}"`;
+    }
+    return `interaction type ${interaction.type}`;
+}
 class MeoCordApp {
     getInstance(controllerClass) {
         if (!this.controllerInstancesCache.has(controllerClass)) {
@@ -114,7 +123,49 @@ class MeoCordApp {
             this.logger.error('Error during command registration:', error);
         }
     }
+    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));
+        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.
+   */ reportAmbiguousRoutes(routes) {
+        const collisions = controller_decorator.findAmbiguousRoutes(routes.map(({ pattern })=>pattern));
+        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.`);
+    }
     async handleInteraction(interaction) {
+        // Component interactions route on a pattern, so they go through the ranked table.
+        // Slash and context-menu commands match their name exactly and cannot overlap.
+        if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+            const customId = interaction.customId;
+            for (const { controllerClass, meta } of this.getComponentRoutes()){
+                const match = meta.regex.exec(customId);
+                if (!match) continue;
+                interaction.dynamicParams = match.groups ?? {};
+                await this.executeCommand(this.getInstance(controllerClass), meta, interaction, customId);
+                return;
+            }
+        }
         for (const controllerClass of this.controllerClasses){
             const controllerInstance = this.getInstance(controllerClass);
             const commandMap = controller_decorator.getCommandMap(controllerInstance);
@@ -124,60 +175,18 @@ class MeoCordApp {
             if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
                 commandIdentifier = interaction.commandName;
                 commandMetadataArray = commandMap[commandIdentifier];
-            } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                commandIdentifier = interaction.customId;
-                const foundEntry = Object.entries(commandMap).find(([commandName, metaArray])=>{
-                    if (!Array.isArray(metaArray)) return false;
-                    return metaArray.some((meta)=>{
-                        if (!meta.regex || !commandIdentifier) return false;
-                        const match = meta.regex.exec(commandIdentifier);
-                        if (match?.groups) {
-                            interaction.dynamicParams = match.groups;
-                            return true;
-                        }
-                        return commandIdentifier === commandName;
-                    });
-                });
-                if (foundEntry) {
-                    commandMetadataArray = foundEntry[1];
-                }
             }
             if (commandMetadataArray && commandMetadataArray.length > 0) {
                 const commandMetadata = commandMetadataArray[0];
-                const { methodName, type } = commandMetadata;
-                try {
-                    if (type === enum_index.CommandType.SLASH && interaction.isChatInputCommand() || type === enum_index.CommandType.BUTTON && interaction.isButton() || type === enum_index.CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === enum_index.CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
-                        this.logger.log('[INTERACTION]', `[${enum_index.CommandType[type]}]`, `[${methodName}]`);
-                        let dynamicParams = {};
-                        if (interaction.isChatInputCommand() && interaction.options) {
-                            dynamicParams = interaction.options.data.reduce((acc, opt)=>{
-                                acc[opt.name] = opt.value;
-                                return acc;
-                            }, {});
-                        } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                            dynamicParams = interaction.dynamicParams || {};
-                        }
-                        await controllerInstance[methodName](interaction, dynamicParams);
-                        return;
-                    } else {
-                        this.logger.debug(type, methodName, enum_index.CommandType.BUTTON, interaction.isButton());
-                        this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
-                    }
-                } catch (error) {
-                    this.logger.error(`Error executing command "${commandIdentifier}":`, error);
-                    if (interaction.isRepliable()) {
-                        const embed = createErrorEmbed('An error occurred while executing the command.');
-                        await interaction.reply({
-                            embeds: [
-                                embed
-                            ],
-                            flags: discord_js.MessageFlagsBitField.Flags.Ephemeral
-                        });
-                    }
-                }
+                await this.executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier);
                 return;
             }
         }
+        // Log what actually failed to match. The user's "Command not found!" says nothing
+        // about which id was unroutable, so a control that is emitted but never routed --
+        // a customId whose value broke its pattern, or a handler nobody wrote -- stays
+        // invisible until somebody reports the dead button.
+        this.logger.warn(`No handler matched ${describeUnmatched(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
         if (interaction.isRepliable()) {
             const embed = createErrorEmbed('Command not found!');
             await interaction.reply({
@@ -188,6 +197,40 @@ class MeoCordApp {
             });
         }
     }
+    /**
+   * Runs a resolved command, shared by both dispatch paths so a pattern-matched
+   * component and a named slash command behave identically once the route is chosen.
+   */ async executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier) {
+        const { methodName, type } = commandMetadata;
+        try {
+            if (type === enum_index.CommandType.SLASH && interaction.isChatInputCommand() || type === enum_index.CommandType.BUTTON && interaction.isButton() || type === enum_index.CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === enum_index.CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === enum_index.CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
+                this.logger.log('[INTERACTION]', `[${enum_index.CommandType[type]}]`, `[${methodName}]`);
+                let dynamicParams = {};
+                if (interaction.isChatInputCommand() && interaction.options) {
+                    dynamicParams = interaction.options.data.reduce((acc, opt)=>{
+                        acc[opt.name] = opt.value;
+                        return acc;
+                    }, {});
+                } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+                    dynamicParams = interaction.dynamicParams ?? {};
+                }
+                await controllerInstance[methodName](interaction, dynamicParams);
+                return;
+            }
+            this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
+        } catch (error) {
+            this.logger.error(`Error executing command "${commandIdentifier}":`, error);
+            if (interaction.isRepliable()) {
+                const embed = createErrorEmbed('An error occurred while executing the command.');
+                await interaction.reply({
+                    embeds: [
+                        embed
+                    ],
+                    flags: discord_js.MessageFlagsBitField.Flags.Ephemeral
+                });
+            }
+        }
+    }
     async handleMessage(message) {
         if (message.author.bot || !message.content?.trim()) return;
         const messageContent = message.content.trim();

package/dist/cjs/decorator/index.cjs

@@ -3,7 +3,7 @@
 require('reflect-metadata');
 var inversify = require('inversify');
 var metadataKey_enum = require('../_shared/metadata-key.enum-BzzvGUId.cjs');
-var controller_decorator = require('../_shared/controller.decorator-DX5lFlPZ.cjs');
+var controller_decorator = require('../_shared/controller.decorator-CC6BjHkS.cjs');
 var discord_js = require('discord.js');
 require('../enum/index.cjs');
 
@@ -249,7 +249,9 @@ export class ButtonInteractionGuard implements GuardInterface {
 exports.Command = controller_decorator.Command;
 exports.Controller = controller_decorator.Controller;
 exports.MessageHandler = controller_decorator.MessageHandler;
+exports.PARAM_SEPARATOR = controller_decorator.PARAM_SEPARATOR;
 exports.ReactionHandler = controller_decorator.ReactionHandler;
+exports.findAmbiguousRoutes = controller_decorator.findAmbiguousRoutes;
 exports.getCommandMap = controller_decorator.getCommandMap;
 exports.getMessageHandlers = controller_decorator.getMessageHandlers;
 exports.getReactionHandlers = controller_decorator.getReactionHandlers;

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

@@ -1,12 +1,21 @@
 import { SlashCommandBuilder, MessageFlagsBitField } from 'discord.js';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
-import { getCommandMap, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import { sample } from 'lodash-es';
 import { createErrorEmbed } from '../util/embed.util.js';
 import { ReactionHandlerAction, CommandType } from '../enum/controller.enum.js';
 import CliTable3 from 'cli-table3';
 
+/** Identifies an unmatched interaction for the log, by whichever field would have routed it. */ function describeUnmatched(interaction) {
+    if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
+        return `command "${interaction.commandName}"`;
+    }
+    if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+        return `customId "${interaction.customId}"`;
+    }
+    return `interaction type ${interaction.type}`;
+}
 class MeoCordApp {
     getInstance(controllerClass) {
         if (!this.controllerInstancesCache.has(controllerClass)) {
@@ -95,7 +104,49 @@ class MeoCordApp {
             this.logger.error('Error during command registration:', error);
         }
     }
+    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));
+        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.
+   */ reportAmbiguousRoutes(routes) {
+        const collisions = findAmbiguousRoutes(routes.map(({ pattern })=>pattern));
+        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.`);
+    }
     async handleInteraction(interaction) {
+        // Component interactions route on a pattern, so they go through the ranked table.
+        // Slash and context-menu commands match their name exactly and cannot overlap.
+        if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+            const customId = interaction.customId;
+            for (const { controllerClass, meta } of this.getComponentRoutes()){
+                const match = meta.regex.exec(customId);
+                if (!match) continue;
+                interaction.dynamicParams = match.groups ?? {};
+                await this.executeCommand(this.getInstance(controllerClass), meta, interaction, customId);
+                return;
+            }
+        }
         for (const controllerClass of this.controllerClasses){
             const controllerInstance = this.getInstance(controllerClass);
             const commandMap = getCommandMap(controllerInstance);
@@ -105,60 +156,18 @@ class MeoCordApp {
             if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
                 commandIdentifier = interaction.commandName;
                 commandMetadataArray = commandMap[commandIdentifier];
-            } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                commandIdentifier = interaction.customId;
-                const foundEntry = Object.entries(commandMap).find(([commandName, metaArray])=>{
-                    if (!Array.isArray(metaArray)) return false;
-                    return metaArray.some((meta)=>{
-                        if (!meta.regex || !commandIdentifier) return false;
-                        const match = meta.regex.exec(commandIdentifier);
-                        if (match?.groups) {
-                            interaction.dynamicParams = match.groups;
-                            return true;
-                        }
-                        return commandIdentifier === commandName;
-                    });
-                });
-                if (foundEntry) {
-                    commandMetadataArray = foundEntry[1];
-                }
             }
             if (commandMetadataArray && commandMetadataArray.length > 0) {
                 const commandMetadata = commandMetadataArray[0];
-                const { methodName, type } = commandMetadata;
-                try {
-                    if (type === CommandType.SLASH && interaction.isChatInputCommand() || type === CommandType.BUTTON && interaction.isButton() || type === CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
-                        this.logger.log('[INTERACTION]', `[${CommandType[type]}]`, `[${methodName}]`);
-                        let dynamicParams = {};
-                        if (interaction.isChatInputCommand() && interaction.options) {
-                            dynamicParams = interaction.options.data.reduce((acc, opt)=>{
-                                acc[opt.name] = opt.value;
-                                return acc;
-                            }, {});
-                        } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                            dynamicParams = interaction.dynamicParams || {};
-                        }
-                        await controllerInstance[methodName](interaction, dynamicParams);
-                        return;
-                    } else {
-                        this.logger.debug(type, methodName, CommandType.BUTTON, interaction.isButton());
-                        this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
-                    }
-                } catch (error) {
-                    this.logger.error(`Error executing command "${commandIdentifier}":`, error);
-                    if (interaction.isRepliable()) {
-                        const embed = createErrorEmbed('An error occurred while executing the command.');
-                        await interaction.reply({
-                            embeds: [
-                                embed
-                            ],
-                            flags: MessageFlagsBitField.Flags.Ephemeral
-                        });
-                    }
-                }
+                await this.executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier);
                 return;
             }
         }
+        // Log what actually failed to match. The user's "Command not found!" says nothing
+        // about which id was unroutable, so a control that is emitted but never routed --
+        // a customId whose value broke its pattern, or a handler nobody wrote -- stays
+        // invisible until somebody reports the dead button.
+        this.logger.warn(`No handler matched ${describeUnmatched(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
         if (interaction.isRepliable()) {
             const embed = createErrorEmbed('Command not found!');
             await interaction.reply({
@@ -169,6 +178,40 @@ class MeoCordApp {
             });
         }
     }
+    /**
+   * Runs a resolved command, shared by both dispatch paths so a pattern-matched
+   * component and a named slash command behave identically once the route is chosen.
+   */ async executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier) {
+        const { methodName, type } = commandMetadata;
+        try {
+            if (type === CommandType.SLASH && interaction.isChatInputCommand() || type === CommandType.BUTTON && interaction.isButton() || type === CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
+                this.logger.log('[INTERACTION]', `[${CommandType[type]}]`, `[${methodName}]`);
+                let dynamicParams = {};
+                if (interaction.isChatInputCommand() && interaction.options) {
+                    dynamicParams = interaction.options.data.reduce((acc, opt)=>{
+                        acc[opt.name] = opt.value;
+                        return acc;
+                    }, {});
+                } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+                    dynamicParams = interaction.dynamicParams ?? {};
+                }
+                await controllerInstance[methodName](interaction, dynamicParams);
+                return;
+            }
+            this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
+        } catch (error) {
+            this.logger.error(`Error executing command "${commandIdentifier}":`, error);
+            if (interaction.isRepliable()) {
+                const embed = createErrorEmbed('An error occurred while executing the command.');
+                await interaction.reply({
+                    embeds: [
+                        embed
+                    ],
+                    flags: MessageFlagsBitField.Flags.Ephemeral
+                });
+            }
+        }
+    }
     async handleMessage(message) {
         if (message.author.bot || !message.content?.trim()) return;
         const messageContent = message.content.trim();

package/dist/esm/decorator/controller.decorator.js

@@ -77,29 +77,62 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
  */ function getMessageHandlers(controller) {
     return Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, controller) || [];
 }
+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 An object containing the generated regex and parameter names.
+ * @returns The regex, the parameter names, and how specific the pattern is.
  */ function createRegexFromPattern(pattern) {
     const params = [];
-    // Escape special characters except for {} and -
-    const escapedPattern = pattern.replace(/[/\\^$*+?.()|[\]]/g, '\\$&') // Removed hyphen `-` from this list
-    ;
-    // Replace placeholders with named capturing groups
-    const regexPattern = escapedPattern.replace(/\{(\w+)}/g, (_, param)=>{
-        if (!/^\w+$/.test(param)) {
-            throw new Error(`Invalid parameter name: ${param}. Parameter names must be alphanumeric.`);
+    let regexPattern = '';
+    let cursor = 0;
+    let literalLength = 0;
+    PLACEHOLDER_PATTERN.lastIndex = 0;
+    let match;
+    while((match = PLACEHOLDER_PATTERN.exec(pattern)) !== null){
+        const [placeholder, param] = match;
+        const literal = pattern.slice(cursor, match.index);
+        const after = pattern[match.index + placeholder.length];
+        // A parameter has to own its segment. Sharing one with a literal leaves no
+        // boundary a sibling pattern can be told apart by, and the resulting overlap has
+        // no correct reading -- `profile-{uuid}` and `profile-{uuid}-{id}` both take
+        // `profile-a-b`. Registration is the last point where that is still fixable.
+        if (literal !== '' && !literal.endsWith(PARAM_SEPARATOR) || after !== undefined && after !== PARAM_SEPARATOR) {
+            throw new Error(`Invalid pattern "${pattern}": {${param}} must occupy a whole segment, so it has to be ` + `preceded and followed by "${PARAM_SEPARATOR}" or by the ends of the pattern. ` + `Write "a${PARAM_SEPARATOR}{${param}}" rather than "a-{${param}}".`);
         }
+        literalLength += literal.length;
+        regexPattern += escapeLiteral(literal);
+        regexPattern += `(?<${param}>[^${PARAM_SEPARATOR}]+)`;
         params.push(param);
-        return `(?<${param}>[a-zA-Z0-9]+)`;
-    });
-    // Construct the final regex
+        cursor = match.index + placeholder.length;
+    }
+    const trailing = pattern.slice(cursor);
+    literalLength += trailing.length;
+    regexPattern += escapeLiteral(trailing);
     const regex = new RegExp(`^${regexPattern}$`);
+    // Literal text is the signal: a pattern spelling out more of the id describes it
+    // more exactly than one leaving it to a parameter. Fewer parameters breaks a tie
+    // between equal-length patterns, so the ranking is total and never falls back to
+    // declaration order.
+    const specificity = literalLength * 1000 - params.length;
     return {
         regex,
-        params
+        params,
+        specificity
     };
 }
 /**
@@ -143,6 +176,7 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
         let commandType;
         let regex;
         let dynamicParams = [];
+        let specificity;
         // Determine command type and builder
         if (typeof builderOrType === 'function') {
             const builderObj = new builderOrType();
@@ -155,9 +189,10 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
             commandType = builderOrType;
         }
         if (commandType !== CommandType.SLASH && commandType !== CommandType.CONTEXT_MENU) {
-            const { regex: generatedRegex, params } = createRegexFromPattern(commandName);
+            const { regex: generatedRegex, params, specificity: patternSpecificity } = createRegexFromPattern(commandName);
             regex = generatedRegex;
             dynamicParams = params;
+            specificity = patternSpecificity;
         }
         // Ensure commandName supports multiple entries
         if (!commands[commandName]) {
@@ -168,7 +203,8 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
             builder: builderInstance,
             type: commandType,
             regex,
-            dynamicParams
+            dynamicParams,
+            specificity
         });
         Reflect.defineMetadata(COMMAND_METADATA_KEY, commands, target);
     };
@@ -204,5 +240,39 @@ const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
         }
     };
 }
+/**
+ * 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.
+ */ function findAmbiguousRoutes(patterns) {
+    const isParam = (segment)=>PLACEHOLDER_PATTERN.test(segment);
+    const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);
+    const collisions = [];
+    for(let i = 0; i < patterns.length; i++){
+        for(let j = i + 1; j < patterns.length; j++){
+            const left = segmentsOf(patterns[i]);
+            const right = segmentsOf(patterns[j]);
+            if (left.length !== right.length) continue;
+            const disjoint = left.some((segment, index)=>{
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const leftIsParam = isParam(segment);
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const rightIsParam = isParam(right[index]);
+                return !leftIsParam && !rightIsParam && segment !== right[index];
+            });
+            if (!disjoint) collisions.push([
+                patterns[i],
+                patterns[j]
+            ]);
+        }
+    }
+    return collisions;
+}
 
-export { Command, Controller, MessageHandler, ReactionHandler, getCommandMap, getMessageHandlers, getReactionHandlers };
+export { Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers };

package/dist/esm/decorator/index.js

@@ -1,5 +1,5 @@
 export { Service } from './service.decorator.js';
 export { CommandBuilder } from './command-builder.decorator.js';
-export { Command, Controller, MessageHandler, ReactionHandler, getCommandMap, getMessageHandlers, getReactionHandlers } from './controller.decorator.js';
+export { Command, Controller, MessageHandler, PARAM_SEPARATOR, ReactionHandler, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers } from './controller.decorator.js';
 export { Guard, UseGuard } from './guard.decorator.js';
 export { MeoCord } from './app.decorator.js';

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

@@ -22,7 +22,28 @@ declare class MeoCordApp {
     private getInstance;
     start(): Promise<void>;
     registerCommands(): Promise<void>;
+    /**
+     * Every pattern-matched route, ordered most specific first.
+     *
+     * Built once and cached, so dispatch stays a single ordered walk with an early exit
+     * rather than paying to rank anything per interaction. Ordering here is what lets
+     * `gi-profile-summary-{ownerId}-{uid}` keep the ids it owns when
+     * `gi-profile-{uuid}-{uid}` would also match them — without it, the winner would be
+     * whichever controller happened to be registered first.
+     */
+    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.
+     */
+    private reportAmbiguousRoutes;
     private handleInteraction;
+    /**
+     * Runs a resolved command, shared by both dispatch paths so a pattern-matched
+     * component and a named slash command behave identically once the route is chosen.
+     */
+    private executeCommand;
     private handleMessage;
     private handleReaction;
     private gracefulShutdown;

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

@@ -57,6 +57,13 @@ interface CommandMetadata<T extends string = string> {
     type: CommandType;
     regex?: RegExp;
     dynamicParams?: T[];
+    /**
+     * How specific this pattern is; higher wins when more than one route matches the
+     * same customId. A greedy parameter can overlap a more literal sibling —
+     * `gi-profile-{uuid:*}-{uid}` also matches an id meant for
+     * `gi-profile-summary-{ownerId}-{uid}` — so dispatch cannot rely on declaration order.
+     */
+    specificity?: number;
 }
 type CommandInteractionType<CBC extends CommandType.SLASH | CommandType.CONTEXT_MENU, T extends CommandBuilderConstructor<CBC> | CommandType> = T extends CommandType.BUTTON ? ButtonInteraction : T extends CommandType.SELECT_MENU ? StringSelectMenuInteraction : T extends CommandBuilderConstructor<CommandType.SLASH> ? ChatInputCommandInteraction : T extends CommandBuilderConstructor<CommandType.CONTEXT_MENU> ? UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction : T extends CommandType.MODAL_SUBMIT ? ModalSubmitInteraction : never;
 
@@ -150,6 +157,8 @@ declare function getMessageHandlers(controller: any): {
     keyword: string | undefined;
     method: string;
 }[];
+/** The character a parameter will not cross, so one pattern segment maps to one value. */
+declare const PARAM_SEPARATOR = "/";
 /**
  * Decorator to register command methods in a controller.
  *
@@ -195,6 +204,18 @@ declare function getCommandMap<T extends string>(controller: any): Record<string
  * ```
  */
 declare function Controller(): (target: any) => void;
+/**
+ * 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.
+ */
+declare function findAmbiguousRoutes(patterns: string[]): [string, string][];
 
 /**
  * MeoCord Framework
@@ -334,4 +355,4 @@ declare function MeoCord(options: {
     services?: ServiceIdentifier[];
 }): (target: any) => void;
 
-export { Command, CommandBuilder, Controller, Guard, MeoCord, MessageHandler, ReactionHandler, Service, UseGuard, getCommandMap, getMessageHandlers, getReactionHandlers };
+export { Command, CommandBuilder, Controller, Guard, MeoCord, MessageHandler, PARAM_SEPARATOR, ReactionHandler, Service, UseGuard, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers };

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": "2.1.1",
+  "version": "3.0.0",
   "type": "module",
   "engines": {
     "node": ">=22"