meocord 4.1.2 → 4.2.1

package/dist/esm/common/translator.js

@@ -1,6 +1,7 @@
 import { Locale } from 'discord.js';
 import { refuse } from '../util/refusal.util.js';
 import { Logger } from './logger.js';
+import { sharedName } from '../util/shared-state.util.js';
 
 /**
  * Declares a message catalog, keeping each message's text as its type so the params it takes can be checked.
@@ -61,8 +62,8 @@ import { Logger } from './logger.js';
 /**
  * Where a translator made by `createTranslator` keeps its catalogs, for MeoCord's texts, `@MeoCord` and
  * `expectCompleteCatalog`.
- */ const CATALOGS = Symbol('catalogs');
-/** How MeoCord's own texts read a translator made by `createTranslator`: the catalogs that serve a locale, in order. */ const LOCALE_CHAIN = Symbol('localeChain');
+ */ const CATALOGS = Symbol.for(sharedName('translator:catalogs'));
+/** How MeoCord's own texts read a translator made by `createTranslator`: the catalogs that serve a locale, in order. */ const LOCALE_CHAIN = Symbol.for(sharedName('translator:localeChain'));
 /** For a class that injects `Translator` in an app that configured none. */ function missingTranslatorError(cls) {
     return new Error(`${cls.name}: it injects Translator, but @MeoCord has no i18n. Pass @MeoCord({ i18n: t }), where t comes from createTranslator.`);
 }
@@ -109,6 +110,22 @@ function interpolate(message, params) {
     }
     return typeof current === 'object' && current !== null;
 }
+/** The locale Discord shows a locale's users when that locale has no localization of its own, by its locale fallbacks. */ const FALLBACK_PARTNERS = {
+    [Locale.EnglishUS]: Locale.EnglishGB,
+    [Locale.EnglishGB]: Locale.EnglishUS,
+    [Locale.SpanishLATAM]: Locale.SpanishES
+};
+/** Each key with a `.` in it, which `lookup` splits as a path and so never reaches, with the group it sits in. */ function dottedKeys(catalog, group = '') {
+    return Object.entries(catalog).flatMap(([name, value])=>[
+            ...name.includes('.') ? [
+                {
+                    name,
+                    group
+                }
+            ] : [],
+            ...typeof value === 'object' && value !== null ? dottedKeys(value, group ? `${group}.${name}` : name) : []
+        ]);
+}
 class CatalogTranslator extends Translator {
     /** The catalogs that serve a locale, most specific first, ending with the default. */ [LOCALE_CHAIN](requested) {
         const chain = [];
@@ -127,10 +144,13 @@ class CatalogTranslator extends Translator {
     translate(requested, key, params = {}) {
         for (const locale of this[LOCALE_CHAIN](requested)){
             const message = lookup(this.catalogs[locale], key);
-            if (message !== undefined) return interpolate(pluralForm({
+            if (message === undefined) continue;
+            // An empty translation, as tools export an untranslated string, counts as missing: Discord refuses an empty reply
+            const text = pluralForm({
                 message,
                 locale
-            }, params.count), params);
+            }, params.count);
+            if (text !== '') return interpolate(text, params);
         }
         this.warnUnknown(key);
         return key;
@@ -160,11 +180,16 @@ class CatalogTranslator extends Translator {
         for (const locale of this.locales){
             if (locale === this.defaultLocale) continue;
             const message = lookup(this.catalogs[locale], key);
-            // A translation with a {param} is left out: Discord would show it as written
-            if (typeof message === 'string' && placeholderNames(message).length === 0) {
+            // A translation with a {param} is left out, as Discord would show it as written, and so is an empty one
+            if (typeof message === 'string' && message !== '' && placeholderNames(message).length === 0) {
                 localized[locale] = fillPlaceholders(message, (_name, whole)=>whole);
             }
         }
+        // Discord gives a locale it falls back from its partner's value, so the default keeps its own wording beside one
+        const partner = FALLBACK_PARTNERS[this.defaultLocale];
+        if (partner && localized[partner] !== undefined && typeof original === 'string' && original !== '') {
+            localized[this.defaultLocale] = fillPlaceholders(original, (_name, whole)=>whole);
+        }
         return localized;
     }
     for(interaction, options = {}) {
@@ -243,6 +268,12 @@ class CatalogTranslator extends Translator {
         }
     }
     if (!locales[defaultLocale]) throw refuse(new Error(`The default locale "${defaultLocale}" has no catalog in locales.`));
+    const logger = new Logger('Translator');
+    for (const [locale, catalog] of Object.entries(locales)){
+        for (const { name, group } of dottedKeys(catalog)){
+            logger.warn(`The ${locale} catalog's key "${name}"${group ? ` in ${group}` : ''} has a ".", which a lookup reads as a path, so its ` + 'message is never found. Nest it as a group instead.');
+        }
+    }
     // Typed by the default catalog; at runtime every catalog is read the same way.
     return new CatalogTranslator(defaultLocale, locales);
 }

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/command-registration.js

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import path from 'path';
 import { ApplicationCommandType, Routes } from 'discord.js';
 import CliTable3 from 'cli-table3';
@@ -103,19 +103,35 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     const guilds = options.config?.guilds ?? [];
     return !everythingTarget(options) && guilds.length > 0 && ids(guilds).length === 0;
 }
+/** Whether a command is an activity's primary entry point, which Discord takes only globally. */ const isEntryPoint = (command)=>command.body.type === ApplicationCommandType.PrimaryEntryPoint;
+/** What a blank guild to register every command to says, as an unset variable gives one. */ const BLANK_GUILD = 'No commands were registered: the guild to register to is blank. Give a guild id, or leave it out to register where commands.* says.';
 /**
  * Where each command is sent: one bulk update per scope. A scope's update replaces everything the application has
  * there, so the default scope is included even when it ends up empty, unless `commands.guilds` lists no guild id.
+ *
+ * A primary entry point command goes in the global update, as Discord refuses a guild update that holds one. A run
+ * that sends everything to one guild sends nothing global, so it leaves the entry point out.
  */ function planTargets(commands, options, logger) {
+    // Registering to the default scopes instead could publish everywhere
+    if (options.onlyGuild !== undefined && !options.onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return [];
+    }
     const everythingTo = everythingTarget(options);
-    if (everythingTo) return [
-        {
-            scope: {
-                guild: everythingTo
-            },
-            commands
+    if (everythingTo) {
+        // A global update from here would hold only what this run sends, deleting the application's other global commands
+        for (const command of commands.filter(isEntryPoint)){
+            logger.warn(`Entry point command "${command.name}" is registered globally only; a production run or \`meocord register\` registers it.`);
         }
-    ];
+        return [
+            {
+                scope: {
+                    guild: everythingTo
+                },
+                commands: commands.filter((command)=>!isEntryPoint(command))
+            }
+        ];
+    }
     const defaultGuilds = ids(options.config?.guilds);
     const nowhere = defaultGuildsEmpty(options);
     const targets = new Map();
@@ -133,7 +149,12 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     });
     const unregistered = [];
     for (const command of commands){
-        if (command.guilds) {
+        if (isEntryPoint(command)) {
+            if (command.guilds) {
+                logger.warn(`Entry point command "${command.name}" can only be registered globally, so the guilds its builder lists are ignored.`);
+            }
+            add('global', command);
+        } else if (command.guilds) {
             const own = ids(command.guilds);
             // Falling back to the default scope could publish a staff-only command everywhere.
             if (own.length === 0) logger.warn(`Command "${command.name}" lists no guild ids in its builder, so it is not registered.`);
@@ -151,7 +172,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
         }
     }
     if (nowhere) {
-        const outcome = unregistered.length === 0 ? 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
+        const outcome = unregistered.length === 0 ? targets.has('global') ? 'only the entry point command is registered globally' : 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
         logger.warn(`commands.guilds lists no guild id, as an unset environment variable leaves it, so ${outcome}. ` + `Set the guild ids, or remove commands.guilds to register globally.`);
     }
     return [
@@ -180,28 +201,57 @@ const describeScope = (scope)=>scope === 'global' ? 'globally' : `to guild ${sco
     return path.join(nodeModules, '.cache', 'meocord', `commands-${applicationId}-${scopeKey(scope)}.json`);
 }
 const hashOf = (commands)=>createHash('sha256').update(JSON.stringify(commands.map(({ body })=>body))).digest('hex');
-function readHash(file, logger) {
+function readRecord(file, logger) {
     if (!file || !existsSync(file)) return undefined;
     try {
-        return JSON.parse(readFileSync(file, 'utf8')).hash;
+        return JSON.parse(readFileSync(file, 'utf8'));
     } catch (error) {
         logger.debug(`Could not read the registered commands, so they are sent again: ${String(error)}`);
         return undefined;
     }
 }
-function writeHash(file, hash, logger) {
+function writeRecord(file, record, logger) {
     if (!file) return;
     try {
         mkdirSync(path.dirname(file), {
             recursive: true
         });
-        writeFileSync(file, `${JSON.stringify({
-            hash
-        })}\n`);
+        writeFileSync(file, `${JSON.stringify(record)}\n`);
     } catch (error) {
         logger.debug(`Could not record the registered commands: ${String(error)}`);
     }
 }
+/** Forgets what development last sent to a scope, once that scope is written some other way. */ function forgetRecord(file, logger) {
+    if (!file || !existsSync(file)) return;
+    try {
+        rmSync(file);
+    } catch (error) {
+        logger.debug(`Could not forget the registered commands: ${String(error)}`);
+    }
+}
+/**
+ * Each command's `id:version`, sorted, from what Discord lists or answers a bulk update with; `undefined` for anything
+ * else. Discord gives a command a new version whenever it is updated, so the set changes with any edit, removal or
+ * re-registration, from this checkout or any other.
+ */ function versionsOf(commands) {
+    if (!Array.isArray(commands)) return undefined;
+    const versions = commands.map((command)=>{
+        const { id, version } = command ?? {};
+        return typeof id === 'string' && typeof version === 'string' ? `${id}:${version}` : undefined;
+    });
+    return versions.every((version)=>version !== undefined) ? versions.sort() : undefined;
+}
+/** Whether Discord still holds a scope as development last sent it, by each command's version; a failed listing doesn't. */ async function stillAsSent(rest, route, record, scope, logger) {
+    if (!record.versions) return false;
+    let registered;
+    try {
+        registered = await rest.get(route);
+    } catch (error) {
+        logger.debug(`Could not list the commands registered ${describeScope(scope)}, so they are sent again: ${String(error)}`);
+        return false;
+    }
+    return versionsOf(registered)?.join('\n') === record.versions.join('\n');
+}
 function logRegistered(target, logger) {
     const table = new CliTable3({
         head: [
@@ -224,22 +274,29 @@ function logRegistered(target, logger) {
     };
     for (const { name, body } of target.commands){
         const options = Array.isArray(body.options) ? body.options : [];
+        // A subcommand or a subcommand group, not a plain option
+        const subcommands = options.filter((option)=>option.type === 1 || option.type === 2);
         table.push([
             name,
             typeNames[typeof body.type === 'number' ? body.type : 1] ?? 'Command',
-            options.map((option)=>option.name).join(', ')
+            subcommands.map((option)=>option.name).join(', ')
         ]);
     }
     logger.log(`Registered ${target.commands.length} bot commands ${describeScope(target.scope)}:\n${table.toString()}`);
 }
 /**
- * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send, unless
- * `force`. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
+ * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send and still
+ * registered as sent, which one listing per skipped scope checks by each command's version, unless `force`. A blank `onlyGuild` registers nothing. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
  * leftovers, which `clearOther` removes; a development-guild run or a `commands.guilds` with no id only warns. Never
  * throws.
  * @returns Whether every scope was sent or unchanged, and `commands.guilds`, if set, lists a guild id.
  */ async function registerCommands(options) {
     const { rest, applicationId, controllerClasses, logger, config, development, onlyGuild, force = false } = options;
+    // An unset variable passed as the guild; registering to the default scopes instead could publish everywhere
+    if (onlyGuild !== undefined && !onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return false;
+    }
     const commands = collectCommands(controllerClasses, logger);
     if (!commands) return false;
     const targets = planTargets(commands, {
@@ -256,18 +313,26 @@ function logRegistered(target, logger) {
     let succeeded = !guildsEmpty;
     let sent = false;
     for (const target of targets){
-        const file = development ? cacheFile(applicationId, target.scope) : undefined;
+        const file = cacheFile(applicationId, target.scope);
         const hash = hashOf(target.commands);
-        if (development && !force && readHash(file, logger) === hash) {
+        const route = routeFor(applicationId, target.scope);
+        // Unchanged since development last sent it, and still what Discord holds there
+        const record = development && !force ? readRecord(file, logger) : undefined;
+        if (record?.hash === hash && await stillAsSent(rest, route, record, target.scope, logger)) {
             logger.log(`Commands ${describeScope(target.scope)} are unchanged; not registering them again.`);
             continue;
         }
         try {
-            await rest.put(routeFor(applicationId, target.scope), {
+            const answered = await rest.put(route, {
                 body: target.commands.map(({ body })=>body)
             });
             sent = true;
-            if (development) writeHash(file, hash, logger);
+            // Outside development the record would be stale, so the next development start sends again
+            if (development) writeRecord(file, {
+                hash,
+                versions: versionsOf(answered)
+            }, logger);
+            else forgetRecord(file, logger);
             logRegistered(target, logger);
         } catch (error) {
             succeeded = false;
@@ -296,13 +361,17 @@ function logRegistered(target, logger) {
         if (!Array.isArray(existing) || existing.length === 0) continue;
         const names = existing.map(({ name })=>name).join(', ');
         if (!config?.clearOther || keptBecause) {
-            logger.warn(`${existing.length} command(s) are still registered ${describeScope(scope)} (${names}), which this ` + `configuration does not register to, so Discord keeps showing them there. ` + (config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : 'Set commands.clearOther to remove them.'));
+            // Advising clearOther when it would not apply sends the reader to a setting that changes nothing
+            const advice = !keptBecause ? 'Set commands.clearOther to remove them.' : config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : `They are not removed ${keptBecause}, even with commands.clearOther.`;
+            logger.warn(`${existing.length} command(s) are still registered ${describeScope(scope)} (${names}), which this ` + `configuration does not register to, so Discord keeps showing them there. ${advice}`);
             continue;
         }
         try {
             await rest.put(routeFor(applicationId, scope), {
                 body: []
             });
+            // What development last sent there is gone, so its next start sends again
+            forgetRecord(cacheFile(applicationId, scope), logger);
             logger.log(`Removed ${existing.length} command(s) left registered ${describeScope(scope)}: ${names}`);
         } catch (error) {
             logger.error(`Error removing the commands left registered ${describeScope(scope)}:`, error);

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

@@ -1,4 +1,4 @@
-import { getCommandMap } from '../decorator/controller.decorator.js';
+import { commandsNamed, getCommandMap } from '../decorator/controller.decorator.js';
 import { resolveCommandPaths, matchesHandler } from '../util/interaction.util.js';
 
 /** The keys a command is routed by, most specific first: a chat command's full path, then its name; none for anything else. */ function commandRouteKeys(interaction) {
@@ -15,7 +15,7 @@ import { resolveCommandPaths, matchesHandler } from '../util/interaction.util.js
  */ function matchCommandRoute(controllers, interaction) {
     for (const key of commandRouteKeys(interaction)){
         for (const controllerClass of controllers){
-            const meta = getCommandMap(controllerClass.prototype)?.[key]?.find((each)=>matchesHandler(each, interaction));
+            const meta = commandsNamed(getCommandMap(controllerClass.prototype), key).find((each)=>matchesHandler(each, interaction));
             if (meta) return {
                 controllerClass,
                 meta

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 };