meocord 4.1.1 → 4.2.0

package/dist/cli.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "meocordVersion": "4.1.1",
+  "meocordVersion": "4.2.0",
   "name": "meocord",
   "description": "CLI for managing the MeoCord application",
   "usage": "[options] [command]",

package/dist/esm/bin/app-template/README.md.template

@@ -94,7 +94,9 @@ interceptors, filters })`. An observer hears about every call once listed in
 `meocord/testing` provides `MeoCordTestingModule` for building a controller with its
 dependencies, `invoke` for running a handler through its guards, interceptors and
 filters as the bot does, and `createMockInteraction` and friends for driving it without
-a Discord connection. `vitest.setup.ts` resets those mocks after every test, so set
+a Discord connection. `vitest.setup.ts` has those mocks made with `vi.fn`, so Vitest
+treats them as its own, and has them compute what discord.js computes, such as a
+message's `editable`, rather than placeholders. It resets them after every test, so set
 what a mock returns in the test, or in `beforeEach`, that relies on it.
 
 ## Linting

package/dist/esm/bin/app-template/src/controllers/button/sample.button.controller.spec.ts.template

@@ -9,6 +9,10 @@ import {
 } from 'meocord/testing'
 import { SampleButtonController } from '@src/controllers/button/sample.button.controller.js'
 
+// Discord user ids, as the customId and the guard compare them
+const owner = '200000000000000001'
+const stranger = '200000000000000002'
+
 const clickBy = (userId: string, customId = 'button-click') => {
   const user = createMockUser()
   user.id = userId
@@ -19,7 +23,7 @@ describe('SampleButtonController', () => {
   const module = MeoCordTestingModule.create({ controllers: [SampleButtonController] }).compile()
 
   it('locks the message while it works, then answers', async () => {
-    const interaction = clickBy('someone')
+    const interaction = clickBy(stranger)
 
     await module.invoke(SampleButtonController, 'handleButton', interaction)
 
@@ -29,16 +33,16 @@ describe('SampleButtonController', () => {
   })
 
   it('answers the owner of the button', async () => {
-    const interaction = clickBy('owner', 'button-with/owner')
+    const interaction = clickBy(owner, `button-with/${owner}`)
 
     // The customId's route gives the handler its ownerId
     await module.invoke(SampleButtonController, 'handleButtonWithId', interaction)
 
-    expect(getResponse(interaction).calls.at(-1)?.payload).toMatchObject({ content: 'Button of <@owner> clicked!' })
+    expect(getResponse(interaction).calls.at(-1)?.payload).toMatchObject({ content: `Button of <@${owner}> clicked!` })
   })
 
   it('denies anyone else before touching the message', async () => {
-    const interaction = clickBy('stranger', 'button-with/owner')
+    const interaction = clickBy(stranger, `button-with/${owner}`)
 
     await expect(module.invoke(SampleButtonController, 'handleButtonWithId', interaction)).rejects.toThrow(
       GuardDeniedError,

package/dist/esm/bin/app-template/src/controllers/button/sample.button.controller.ts.template

@@ -15,8 +15,8 @@ export class SampleButtonController {
     await respond(interaction).send({ content: 'Button clicked!' })
   }
 
-  // Only the user whose id the customId carries gets past OwnerGuard
-  @Command('button-with/{ownerId}', CommandType.BUTTON)
+  // Only the user whose id the customId carries gets past OwnerGuard; `:snowflake` takes only a Discord id
+  @Command('button-with/{ownerId:snowflake}', CommandType.BUTTON)
   @UseGuard(OwnerGuard)
   @Cooldown({ uses: 5, seconds: 60 })
   @Defer()

package/dist/esm/bin/app-template/src/guards/owner.guard.spec.ts.template

@@ -7,30 +7,34 @@ import { OwnerGuard } from '@src/guards/owner.guard.js'
 
 @Controller()
 class CardController {
-  @Command('card/{ownerId}', CommandType.BUTTON)
+  @Command('card/{ownerId:snowflake}', CommandType.BUTTON)
   @UseGuard(OwnerGuard)
   async open(interaction: ButtonInteraction) {
     await interaction.deferUpdate()
   }
 }
 
+// Discord user ids, as the customId and the guard compare them
+const owner = '200000000000000001'
+const stranger = '200000000000000002'
+
 const clickBy = (userId: string) => {
   const user = createMockUser()
   user.id = userId
   // invoke reads ownerId from the customId, as dispatch does
-  return createMockInteraction(ButtonInteraction, { customId: 'card/owner', user })
+  return createMockInteraction(ButtonInteraction, { customId: `card/${owner}`, user })
 }
 
 describe('OwnerGuard', () => {
   const module = MeoCordTestingModule.create({ controllers: [CardController] }).compile()
 
   it("lets the button's owner through", async () => {
-    const { ran } = await module.invoke(CardController, 'open', clickBy('owner'))
+    const { ran } = await module.invoke(CardController, 'open', clickBy(owner))
 
     expect(ran).toBe(true)
   })
 
   it('denies anyone else with a GuardDeniedError', async () => {
-    await expect(module.invoke(CardController, 'open', clickBy('stranger'))).rejects.toThrow(GuardDeniedError)
+    await expect(module.invoke(CardController, 'open', clickBy(stranger))).rejects.toThrow(GuardDeniedError)
   })
 })

package/dist/esm/bin/app-template/src/guards/owner.guard.ts.template

@@ -3,7 +3,7 @@ import { Guard } from 'meocord/decorator'
 import { GuardDeniedError } from 'meocord/common'
 import { type GuardInterface } from 'meocord/interface'
 
-/** Lets only the user whose id a button carries use it: `@Command('card/{ownerId}', ...)` */
+/** Lets only the user whose id a button carries use it: `@Command('card/{ownerId:snowflake}', ...)` */
 @Guard()
 export class OwnerGuard implements GuardInterface {
   canActivate(interaction: ButtonInteraction, { ownerId }: { ownerId: string }): boolean {

package/dist/esm/bin/app-template/vitest.config.ts.template

@@ -24,7 +24,7 @@ export default defineConfig({
   test: {
     globals: true,
     setupFiles: ['./vitest.setup.ts'],
-    // vi.fn() mocks only; vitest.setup.ts resets the mocks from meocord/testing
+    // Every mock's calls, meocord/testing's included; vitest.setup.ts also resets meocord's to how each was created
     clearMocks: true,
     include: ['src/**/*.spec.ts'],
     coverage: {

package/dist/esm/bin/app-template/vitest.setup.ts.template

@@ -1,6 +1,10 @@
 import 'reflect-metadata'
-import { resetAllMocks } from 'meocord/testing'
-import { afterEach } from 'vitest'
+import { resetAllMocks, useMockFn, useStrictMocks } from 'meocord/testing'
+import { afterEach, vi } from 'vitest'
 
-// Every test starts from mocks as they were created: clearMocks in vitest.config.ts reaches only vi.fn()
+// meocord/testing makes its mocks with vi.fn, so Vitest's matchers, config and vi.mocked() treat them as its own
+useMockFn(vi.fn)
+// Mocks compute what discord.js computes, such as a message's editable or a member's kickable, rather than placeholders
+useStrictMocks()
+// Every test starts from meocord's mocks as they were created
 afterEach(() => resetAllMocks())

package/dist/esm/build/load-config.pre-entry.js

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { installStackRemapper } from './stack-remap.js'
 import { listenForDevRunnerStop } from '../util/dev-runner.util.js'
-import { BUILD_MODE_KEY, BUNDLE_ENTRY_KEY } from '../util/bundle-entry.util.js'
+import { BUILD_MODE_KEY, BUNDLE_ENTRY_KEY, STARTUP_ERRORS_KEY } from '../util/bundle-entry.util.js'
 import { loadMeoCordConfig } from '../util/meocord-config-loader.util.js'
 
 // First, so a restart `meocord start --dev` asks for while the bundle still loads is heard
@@ -26,4 +26,7 @@ __webpack_public_path__ = `${path.dirname(bundle).replace(/\\/g, '/')}/`
 // bundled, else a copy of it, and require's cache evaluates the config once either way; the factory reports a failure
 const config = loadMeoCordConfig()
 
+// Before the entry's decorators run, so with 'all' they keep their startup errors for create() to report together
+if (config?.startupErrors === 'all') globalThis[STARTUP_ERRORS_KEY] = 'all'
+
 if (config?.sourceMappedStacks !== false) installStackRemapper(bundle)

package/dist/esm/common/decorator.js

@@ -1,7 +1,7 @@
 import { warnDeprecated } from './deprecation.js';
 import { Logger } from './logger.js';
 import { MetadataKey } from '../enum/metadata-key.enum.js';
-import { refuse, decoratedName } from '../util/refusal.util.js';
+import { declaring, refuse, decoratedName } from '../util/refusal.util.js';
 
 /**
  * Composes several class or method decorators into one.
@@ -30,9 +30,9 @@ import { refuse, decoratedName } from '../util/refusal.util.js';
  *
  * @group Utilities
  * @see {@link createMetadata}
- * @see {@link https://meocord.dev/docs/4.1/custom-decorators | Custom decorators}
+ * @see {@link https://meocord.dev/docs/4.2/custom-decorators | Custom decorators}
  */ function applyDecorators(...decorators) {
-    return function(target, propertyKey, descriptor) {
+    return declaring(function(target, propertyKey, descriptor) {
         // Last first, as TypeScript applies decorators stacked, each given what the one before it returned
         const ordered = [
             ...decorators
@@ -45,7 +45,7 @@ import { refuse, decoratedName } from '../util/refusal.util.js';
         let current = target;
         for (const decorator of ordered)current = decorator(current) ?? current;
         return current;
-    };
+    });
 }
 const logger = new Logger('SetMetadata');
 /** The prefix of every key MeoCord keeps its own metadata under. */ const MEOCORD_PREFIX = 'meocord:';
@@ -84,7 +84,7 @@ const logger = new Logger('SetMetadata');
  * @see {@link createMetadata}
  */ function SetMetadata(metadataKey, metadataValue) {
     warnDeprecated(logger, 'SetMetadata', 'createMetadata');
-    return function(target, propertyKey) {
+    return declaring(function(target, propertyKey) {
         // Checked where it applies, so the refusal names the handler or controller
         const owner = metadataKey.startsWith(MEOCORD_PREFIX) ? `MeoCord keeps its own metadata under keys beginning "${MEOCORD_PREFIX}"` : INJECTION_KEYS.has(metadataKey) ? 'dependency injection reads how to make the class from it' : undefined;
         if (owner) {
@@ -95,7 +95,7 @@ const logger = new Logger('SetMetadata');
         } else {
             Reflect.defineMetadata(metadataKey, metadataValue, target);
         }
-    };
+    });
 }
 
 export { SetMetadata, applyDecorators };

package/dist/esm/common/deprecation.js

@@ -14,10 +14,10 @@ const warned = new Set();
  */ function warnPlaceholder(logger, value, outcome, how) {
     warnOnce(logger, `${value} reads a placeholder here; in the next major version (5.0) ${outcome}. ${how}`);
 }
-function warnOnce(logger, text) {
+/** Logs `text` once per run, however often it is asked for. */ function warnOnce(logger, text) {
     if (warned.has(text)) return;
     warned.add(text);
     logger.warn(text);
 }
 
-export { warnDeprecated, warnDeprecatedBehaviour, warnPlaceholder };
+export { warnDeprecated, warnDeprecatedBehaviour, warnOnce, warnPlaceholder };

package/dist/esm/common/errors.js

@@ -90,7 +90,7 @@ import { renderText } from './meocord-text.js';
  * @group Responses
  * @category Errors
  * @see {@link Catch}
- * @see {@link https://meocord.dev/docs/4.1/exception-filters | Exception filters}
+ * @see {@link https://meocord.dev/docs/4.2/exception-filters | Exception filters}
  */ class CommandNotFoundError extends Error {
     /** @param message - What the error says, `No handler matched the interaction.` unless given. */ constructor(message = 'No handler matched the interaction.'){
         super(message);
@@ -163,7 +163,7 @@ import { renderText } from './meocord-text.js';
  * @category Errors
  * @see {@link MessageHandler}
  * @see {@link translateError}
- * @see {@link https://meocord.dev/docs/4.1/message-commands | Message commands}
+ * @see {@link https://meocord.dev/docs/4.2/message-commands | Message commands}
  */ class MessageUsageError extends Error {
     /**
    * @param usage - The command as the user should type it, such as `!ban <target> [reason…]`, or one line per

package/dist/esm/common/execution-context.js

@@ -33,7 +33,7 @@ import { useTheme } from '../core/theme-scope.js';
  * @group Utilities
  * @see {@link createMetadata}
  * @see {@link StageParams}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */ class ExecutionContext {
     /**
    * The response state of the interaction being handled, the same one `respond(interaction)` returns,

package/dist/esm/common/metadata.js

@@ -31,7 +31,7 @@ import 'reflect-metadata';
  *
  * @group Utilities
  * @see {@link ExecutionContext}
- * @see {@link https://meocord.dev/docs/4.1/guards | Guards}
+ * @see {@link https://meocord.dev/docs/4.2/guards | Guards}
  */ function createMetadata(description) {
     const key = Symbol(description);
     const decorator = (value)=>function(target, propertyKey) {

package/dist/esm/common/route.js

@@ -14,6 +14,10 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
             decodeSegment(value)
         ]));
 }
+/** The segment types whose value is text, which `build` takes only as a string. */ const TEXT_TYPES = new Set([
+    'snowflake',
+    'uuid'
+]);
 /**
  * Makes a typed route from a customId pattern, so one declaration serves the handler and the ids that reach it.
  *
@@ -48,7 +52,7 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
  *
  * @group Utilities
  * @see {@link Route}
- * @see {@link https://meocord.dev/docs/4.1/components | Buttons, selects and modals}
+ * @see {@link https://meocord.dev/docs/4.2/components | Buttons, selects and modals}
  */ function route(pattern) {
     const { params, types } = createRegexFromPattern(pattern);
     const names = new Set(params);
@@ -60,6 +64,11 @@ const PLACEHOLDER = /\{(\w+)(?::([^}/]*))?}/g;
             const value = Object.hasOwn(values, name) ? values[name] : undefined;
             const type = Object.hasOwn(types, name) ? types[name] : undefined;
             if (value === undefined || value === null) throw new TypeError(`route('${pattern}').build() needs a value for ${placeholder}.`);
+            // A snowflake's or uuid's value is its text: a number for a snowflake may have lost digits before it got here
+            if (type && TEXT_TYPES.has(type) && typeof value !== 'string') {
+                const lost = type === 'snowflake' ? ' A number may have lost digits already: pass the ID as text, such as user.id.' : '';
+                throw new TypeError(`route('${pattern}').build() got the ${typeof value} ${String(value)} for ${placeholder}, which takes its value as a string.${lost}`);
+            }
             const text = String(value);
             if (text === '') throw new TypeError(`route('${pattern}').build() got an empty {${name}}, which no customId segment can hold.`);
             // A typed segment must read back as the value it was built from, or the route could never match it

package/dist/esm/common/translate-error.js

@@ -58,7 +58,7 @@ import { interactionLocale, messageLocale, textOfIssue, renderText } from './meo
  * @group Utilities
  * @category Localisation
  * @see {@link createTranslator}
- * @see {@link https://meocord.dev/docs/4.1/localisation | Localisation}
+ * @see {@link https://meocord.dev/docs/4.2/localisation | Localisation}
  */ function translateError(error, t, target) {
     const locale = target instanceof BaseInteraction ? interactionLocale(target) : target instanceof Message ? messageLocale(target) : target;
     return errorText(error, t, locale);

package/dist/esm/core/command-conflicts.js

@@ -1,11 +1,12 @@
 import { ApplicationCommandType, ApplicationCommandOptionType } from 'discord.js';
 import { Logger } from '../common/logger.js';
-import { getCommandMap, getAutocompleteHandlers, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import { serialise, registrationKey, SENT_AS, commandNameOf } from './command-registration.js';
-import { buildComponentRoutes, findComponentRouteConflicts, literalFirst } from './component-routes.js';
+import { buildComponentRoutes, findComponentRouteConflicts } from './component-routes.js';
 import { CommandType } from '../enum/controller.enum.js';
 import { isCustomIdRouted } from '../util/interaction.util.js';
-import { refuse } from '../util/refusal.util.js';
+import { startupError } from '../util/refusal.util.js';
+import { META } from '../util/metadata-keys.js';
 import { listed } from '../util/user-text.util.js';
 
 const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.methodName}`;
@@ -28,7 +29,7 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
  * Refuses commands of which only one could run or be registered: two handlers of one slash command name or subcommand
  * path or of one context menu name and kind, or two builders of one command; a command's subcommands, and a user and a
  * message context menu of one name, are no clash. The app, `meocord register`, the shard manager and testing call it.
- * @throws Error naming both handlers, or both builders, with what to do instead.
+ * Each clash is a startup error, naming both handlers or both builders with what to do instead; see `startupError`.
  */ function assertDistinctCommands(controllerClasses) {
     const handlers = new Map();
     const builders = new Map();
@@ -46,7 +47,8 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
                 const key = `${meta.type}\0${name}`;
                 const earlier = (handlers.get(key) ?? []).find((other)=>overlap(other.meta, meta));
                 if (earlier) {
-                    throw refuse(new Error(`${where(earlier)}: it and ${where(here)} both handle the ${describe(meta.type, name, contextMenuKind(meta) ?? contextMenuKind(earlier.meta))}, ` + `so only ${where(earlier)} would ever run. Keep one handler for it, or give the other a name or ` + `subcommand path of its own.`));
+                    startupError(new Error(`${where(earlier)}: it and ${where(here)} both handle the ${describe(meta.type, name, contextMenuKind(meta) ?? contextMenuKind(earlier.meta))}, ` + `so only ${where(earlier)} would ever run. Keep one handler for it, or give the other a name or ` + `subcommand path of its own.`));
+                    continue;
                 }
                 handlers.set(key, [
                     ...handlers.get(key) ?? [],
@@ -67,7 +69,7 @@ const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.metho
                         name: typeof body.name === 'string' ? body.name : name
                     });
                 } else if (built.meta.builderClass !== meta.builderClass) {
-                    throw refuse(new Error(`${where(built)}: its builder ${built.meta.builderClass.name} and ${meta.builderClass.name} on ${where(here)} both ` + `build the ${describe(meta.type, built.name, contextMenuKind(meta))}, and Discord registers one command ` + `per name and type, so only the first would be. Keep one builder, on a single @Command, and declare ` + `the other handlers with CommandType.${meta.type}.`));
+                    startupError(new Error(`${where(built)}: its builder ${built.meta.builderClass.name} and ${meta.builderClass.name} on ${where(here)} both ` + `build the ${describe(meta.type, built.name, contextMenuKind(meta))}, and Discord registers one command ` + `per name and type, so only the first would be. Keep one builder, on a single @Command, and declare ` + `the other handlers with CommandType.${meta.type}.`));
                 }
             }
         }
@@ -245,18 +247,21 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
 /**
  * Warns about a handler a subclass re-declares on other routes while it still answers the ones it inherits, for
  * `@Command`, `@MessageHandler`, `@ReactionHandler` and `@Autocomplete` alike. The next major version (5.0) drops
- * the inherited routes. Every class a listed controller extends is checked once, a base that is not listed included.
+ * the inherited routes. Every class a listed controller extends is checked, a base that is not listed included, for
+ * the methods the controller still inherits through it.
  */ function warnInheritedRoutes(controllerClasses) {
-    const checked = new Set();
-    const problems = [];
+    // A set, so a class two listed controllers extend is named once, for the routes either of them still answers
+    const problems = new Set();
     for (const controllerClass of controllerClasses){
+        // Methods a class below re-declares with @Controller({ inheritedRoutes: 'replace' }): the listed controller inherits
+        // nothing of them from above it, so a class above is not named for them
+        const cut = new Set();
         for(let prototype = controllerClass.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)){
-            if (checked.has(prototype)) break;
-            checked.add(prototype);
             const declared = getDeclaredRoutes(prototype);
             const base = Object.getPrototypeOf(prototype);
             if (declared.length === 0 || !base) continue;
-            const inherited = getHandlerRoutes(base);
+            if (Reflect.getOwnMetadata(META.replacesInheritedRoutes, prototype)) for (const route of declared)cut.add(route.method);
+            const inherited = getHandlerRoutes(base).filter((route)=>!cut.has(route.method));
             for (const method of new Set(declared.map((route)=>route.method))){
                 const own = [
                     ...new Set(declared.filter((route)=>route.method === method).map((route)=>route.label))
@@ -266,17 +271,19 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
                 ].filter((label)=>!own.includes(label));
                 if (kept.length === 0) continue;
                 const name = prototype.constructor.name;
-                problems.push(`  ${name}.${method} answers ${listed(kept)}, which it inherits, as well as its own ${listed(own)}.`);
+                problems.add(`  ${name}.${method} answers ${listed(kept)}, which it inherits, as well as its own ${listed(own)}.`);
             }
         }
     }
-    if (problems.length === 0) return;
-    const one = problems.length === 1;
-    logger.warn(`${problems.length} re-declared ${one ? 'handler still answers routes it inherits' : 'handlers still answer routes they inherit'}:\n` + `${problems.join('\n')}\nIn the next major version (5.0), a handler's own routes replace the ones it inherits. ` + "To keep an inherited route, declare it on the subclass's method as well.");
+    if (problems.size === 0) return;
+    const one = problems.size === 1;
+    logger.warn(`${problems.size} re-declared ${one ? 'handler still answers routes it inherits' : 'handlers still answer routes they inherit'}:\n` + `${[
+        ...problems
+    ].join('\n')}\nIn the next major version (5.0), a handler's own routes replace the ones it inherits. ` + "To keep an inherited route, declare it on the subclass's method as well; to drop it now, give the subclass " + "@Controller({ inheritedRoutes: 'replace' }).");
 }
 /**
- * Warns of customId patterns of one component type that can match one customId, naming the handler that runs and why;
- * an app whose patterns overlap works, so refusing to start would turn a latent mis-route into an outage.
+ * Warns of customId patterns of one component type that rank equally and can match one customId, naming an id both
+ * match and the handler that runs. An app with such a pair works, so it starts; the next major version (5.0) refuses.
  * @throws Error for two handlers whose patterns match the same customIds, which the app refuses as well.
  */ function warnOverlappingPatterns(controllerClasses) {
     const routes = buildComponentRoutes(controllerClasses);
@@ -286,23 +293,16 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
             `${route.meta.type}\0${route.pattern}`,
             route
         ]));
-    const lines = conflicts.map(({ type, patterns: [left, right] })=>{
-        const outcome = ambiguityOutcome(routeOf.get(`${type}\0${left}`), routeOf.get(`${type}\0${right}`));
-        return `  "${left}"  vs  "${right}": ${outcome}`;
-    });
-    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${lines.join('\n')}`);
-}
-/**
- * Which of two overlapping routes runs for the ids both match, and why: `runs` ranks first. Between equally
- * specific patterns, the order they are listed in decides until 5.0, which prefers the earlier literal segment.
- */ function ambiguityOutcome(runs, other) {
     const name = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.methodName}`;
-    if ((runs.meta.specificity ?? 0) !== (other.meta.specificity ?? 0)) return `${name(runs)} runs, as its pattern is more specific.`;
-    const together = runs.controllerClass === other.controllerClass;
-    const listed = together ? 'it is declared first' : 'its controller is listed first';
-    if (!literalFirst(other.pattern, runs.pattern)) return `${name(runs)} runs, as ${listed}.`;
-    const reorder = together ? `Declare ${name(other)} first` : `List ${other.controllerClass.name} first`;
-    return `${name(runs)} runs, as ${listed}. In the next major version (5.0), ${name(other)} runs instead, as ` + `"${other.pattern}" spells out the first segment where the two differ. ${reorder}, or make the patterns distinct.`;
+    const lines = conflicts.map(({ type, patterns: [left, right], customId })=>{
+        const [runs, other] = [
+            routeOf.get(`${type}\0${left}`),
+            routeOf.get(`${type}\0${right}`)
+        ];
+        const listed = runs.controllerClass === other.controllerClass ? 'it is declared first' : 'its controller is listed first';
+        return `  "${left}"  vs  "${right}", which both match "${customId}": ${name(runs)} runs, as ${listed}.`;
+    });
+    logger.warn(`${conflicts.length} pattern pair(s) rank equally and can match the same customId, so the order they are listed in ` + `decides which one runs:\n${lines.join('\n')}\nMake the patterns distinct: in the next major version (5.0), ` + 'MeoCord refuses to start with such a pair.');
 }
 
 export { assertDistinctCommands, messageDecorator, reactionDecorator, warnHandlersOffControllers, warnInheritedRoutes, warnOverlappingPatterns, warnUnregisteredCommands };

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

@@ -1,10 +1,36 @@
-import { getCommandMap, patternShape, findAmbiguousRoutes, createRegexFromPattern } from '../decorator/controller.decorator.js';
+import { getCommandMap, patternShape, paramNarrowness, sharedCustomId, createRegexFromPattern } from '../decorator/controller.decorator.js';
 import { decodeRouteParams } from '../common/route.js';
 import { parseSegment } from './scalar-types.js';
 import { refuse } from '../util/refusal.util.js';
 
 /**
- * Every customId-pattern route of the given controllers, most specific first, read from metadata alone.
+ * How a pattern ranks, one character per segment twice over: `L` for literal text or `P` for a param, then how narrow
+ * each param is, the narrowest as the lowest digit. Two keys of one length compare as text: literal before param at
+ * the first segment where they differ, then the narrower type.
+ */ function rankKey(pattern) {
+    const narrowness = pattern.split('/').map(paramNarrowness);
+    const kinds = narrowness.map((rank)=>rank === undefined ? 'L' : 'P').join('');
+    return `${kinds}/${narrowness.map((rank)=>String(rank === undefined ? 0 : 9 - rank)).join('')}`;
+}
+/**
+ * Orders two routes as dispatch tries them. Left to right, the first segment one pattern spells out as literal text
+ * while the other leaves it to a param ranks the literal one first: `a/{x}` before `{x}/abcd`, `profile/me/{section}`
+ * before `profile/{userId}/edit`. Between patterns that leaves tied, the first param where one type is narrower ranks
+ * it first: words to choose from, then `bool`, `uuid`, `snowflake`, `int`, `number`, then text. Patterns of different
+ * segment counts, which no customId matches both of, are ordered by count only so the order is total; component
+ * patterns have no catch-all param. What remains tied keeps its listing order.
+ */ function rank(keys) {
+    return (a, b)=>{
+        const [left, right] = [
+            keys.get(a),
+            keys.get(b)
+        ];
+        if (left.length !== right.length) return left.length - right.length;
+        return left < right ? -1 : left > right ? 1 : 0;
+    };
+}
+/**
+ * Every customId-pattern route of the given controllers, in the order dispatch tries them, read from metadata alone.
  * Throws for two handlers whose patterns match the same customIds of one component type; one handler
  * declared under two spellings of a pattern keeps one route.
  */ function buildComponentRoutes(controllerClasses) {
@@ -37,22 +63,11 @@ import { refuse } from '../util/refusal.util.js';
             }
         }
     }
-    // A stable sort, so equally specific patterns keep the order their controllers and handlers are listed in
-    return routes.sort((a, b)=>(b.meta.specificity ?? 0) - (a.meta.specificity ?? 0));
-}
-/**
- * Whether `a` spells out the first segment where it and `b` differ as literal text while `b` leaves it to a
- * parameter, the tie-break between equally specific patterns in the next major version (5.0).
- */ function literalFirst(a, b) {
-    const [left, right] = [
-        a.split('/'),
-        b.split('/')
-    ];
-    for(let i = 0; i < Math.min(left.length, right.length); i++){
-        const leftLiteral = !left[i].includes('{');
-        if (leftLiteral !== !right[i].includes('{')) return leftLiteral;
-    }
-    return false;
+    // A stable sort, so what the ranking leaves tied keeps the order controllers and handlers are listed in
+    return routes.sort(rank(new Map(routes.map((route)=>[
+            route,
+            rankKey(route.pattern)
+        ]))));
 }
 /** A component type as an error names it: `button`, `modal submit`, `select menu`. */ const typeLabel = (type)=>type.toLowerCase().replaceAll('_', ' ');
 /**
@@ -77,6 +92,12 @@ const typesByPattern = new Map();
     if (!types) typesByPattern.set(pattern, types = createRegexFromPattern(pattern).types);
     return types;
 }
+/**
+ * The params `pattern`, compiled as `regex`, captures from a customId, each typed param as its value:
+ * `undefined` when the customId does not match, or a segment is not a value of its param's type.
+ */ function readCustomId(pattern, regex, customId) {
+    return readCustomIdSegments(pattern, regex, customId)?.values;
+}
 /** {@link readCustomId}'s values, with each param's text as the customId gave it. */ function readCustomIdSegments(pattern, regex, customId) {
     const match = regex.exec(customId);
     if (!match) return undefined;
@@ -94,18 +115,40 @@ const typesByPattern = new Map();
         text
     };
 }
-/** 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
-            })));
+/**
+ * Pattern pairs of one component type that the ranking leaves tied and that can match one customId, each with the
+ * pattern that runs, the one ranked first in `routes`, and an id both match. Only patterns of one rank key, read
+ * together, can tie, so each group is compared within itself.
+ */ function findComponentRouteConflicts(routes) {
+    const groups = new Map();
+    for (const route of routes){
+        // The literal text and each param's narrowness: patterns that differ in either rank apart or match no id in common
+        const key = `${route.meta.type}\0${route.pattern.split('/').map((segment)=>paramNarrowness(segment) ?? `=${segment}`).join('\0')}`;
+        groups.set(key, [
+            ...groups.get(key) ?? [],
+            route
+        ]);
+    }
+    const conflicts = [];
+    for (const group of groups.values()){
+        for(let i = 0; i < group.length; i++){
+            for(let j = i + 1; j < group.length; j++){
+                const customId = sharedCustomId(group[i].pattern, group[j].pattern);
+                if (customId === undefined) continue;
+                const patterns = [
+                    group[i].pattern,
+                    group[j].pattern
+                ];
+                conflicts.push({
+                    type: group[i].meta.type,
+                    patterns,
+                    runs: group[i].pattern,
+                    customId
+                });
+            }
+        }
+    }
+    return conflicts;
 }
 
-export { buildComponentRoutes, findComponentRouteConflicts, literalFirst, matchComponentRoute };
+export { buildComponentRoutes, findComponentRouteConflicts, matchComponentRoute, readCustomId };