meocord 4.2.1 → 4.2.3

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

@@ -1,12 +1,63 @@
 import { getMessageHandlers } from '../decorator/controller.decorator.js';
 import { routeSpecificity } from './route-specificity.js';
-import { isKnownParamType, BUILT_IN_TYPES, isGuildType, fitsParamType } from './message-params.js';
-import { isSpace, splitFlagWords, splitWords, restFrom } from './message-words.js';
+import { isKnownParamType, BUILT_IN_TYPES, isGuildType, effectiveScope, fitsParamType } from './message-params.js';
+import { isSpace, splitFlagWords, literalFlags, splitWords, restFrom, isLiteralFlag } from './message-words.js';
+import { setOwn, shadowInherited } from '../util/value.util.js';
 import { startupError } from '../util/refusal.util.js';
+import { warnOnce } from '../common/deprecation.js';
+import { Logger } from '../common/logger.js';
 
+const logger = new Logger('MeoCord');
 /** Whether a route's scope lets it run where the message was sent. */ const fitsScope = (scope, inGuild)=>inGuild === undefined || scope === 'any' || scope === 'guild' === inGuild;
 const PARAM = /^\{(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\.\.\.)?(\?)?\}$/;
 const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
+/**
+ * A whole brace pair that PARAM or FLAG refused, read loosely to tell its name from its type: anything up to `:` or `}`,
+ * then the marks a param ends with, `...` and `?`, wherever they were written.
+ */ const LOOSE_FLAG = /^\{--([^:}]*?)(?::([^}]*?))?(\.\.\.)?(\?)?\}$/;
+const LOOSE_PARAM = /^\{([^:}]*?)(?::([^}]*?))?(\.\.\.)?(\?)?\}$/;
+/** A name or type with marks after it, as one written out of order carries them. */ const MARKED = /^(.*?)((?:\.\.\.|\?)+)$/;
+/** A param's name, and a flag's, which also starts with a letter, as a message could not give it otherwise. */ const PARAM_NAME = /^\w+$/;
+const FLAG_NAME = /^[A-Za-z]\w*$/;
+/** A param as its pattern writes it, which the grammar spells only one way. */ const writtenParam = (token)=>`{${token.param}${token.type ? `:${token.type}` : ''}${token.rest ? '...' : ''}${token.optional ? '?' : ''}}`;
+/** A flag as its pattern writes it. */ const writtenFlag = (flag)=>`{--${flag.flag}${flag.type ? `:${flag.type}` : ''}${flag.optional ? '?' : ''}}`;
+/**
+ * Why a word with a brace in it is no param or flag: text around its braces, or a whole pair whose name, type or marks
+ * the syntax doesn't take. Each names the rule broken, with the word mended as an example.
+ */ function notAParam(word) {
+    const flag = LOOSE_FLAG.exec(word);
+    if (flag) {
+        const [, name, type, rest] = flag;
+        if (rest || word.includes('...')) {
+            return `"${word}" is not a flag: a flag doesn't take the rest of the message; a param does, such as {${mended(unmarked(name), 'param')}...}.`;
+        }
+        if (unmarked(name) !== name || type !== undefined && unmarked(type) !== type) {
+            const typed = type === undefined ? '' : `:${unmarked(type)}`;
+            return `"${word}" is not a flag: its ? goes last, as in {--${unmarked(name)}${typed}?}.`;
+        }
+        if (!FLAG_NAME.test(name)) {
+            return `"${word}" is not a flag: a flag's name starts with a letter, then letters, digits or _, such as {--${mended(name, 'flag')}}.`;
+        }
+        return `"${word}" is not a flag: a type is a name, or words to choose from joined by |, such as {--${name}:on|off}.`;
+    }
+    const param = LOOSE_PARAM.exec(word);
+    if (param) {
+        const [, name, type] = param;
+        if (unmarked(name) !== name || type !== undefined && unmarked(type) !== type) {
+            const typed = type === undefined ? '' : `:${unmarked(type)}`;
+            const ordered = `{${unmarked(name)}${typed}${word.includes('...') ? '...' : ''}${word.includes('?') ? '?' : ''}}`;
+            return `"${word}" is not a param: its marks go last, ... then ?, as in ${ordered}.`;
+        }
+        if (!PARAM_NAME.test(name)) return `"${word}" is not a param: a param's name is ASCII letters, digits and _, such as {${mended(name, 'param')}}.`;
+        return `"${word}" is not a param: a type is a name, or words to choose from joined by |, such as {${name}:on|off}.`;
+    }
+    return `"${word}" is not a param: a param is a whole word, such as {name}, {name:type}, {name...}, {name?} or a flag, {--name}.`;
+}
+/** A name or type without the marks written after it, `...` and `?`. */ const unmarked = (text)=>MARKED.exec(text)?.[1] ?? text;
+/** A name with each character the syntax doesn't take as `_`, and a flag's led by a letter, for an example. */ function mended(name, kind) {
+    const word = name.replace(/\W/g, '_') || kind;
+    return kind === 'flag' && !/^[A-Za-z]/.test(word) ? `flag${word}` : word;
+}
 /**
  * Reads a pattern into its words and flags. Throws for a pattern of flags alone, a param that is not a whole word, a
  * name given twice, a rest param that is not last, a word after an optional param that is not optional too, an untyped
@@ -42,9 +93,7 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
     words.forEach((word, index)=>{
         const match = PARAM.exec(word);
         if (!match) {
-            if (/[{}]/.test(word)) {
-                throw new Error(`"${word}" is not a param: a param is a whole word, such as {name}, {name:type}, {name...}, {name?} or a flag, {--name}.`);
-            }
+            if (/[{}]/.test(word)) throw new Error(notAParam(word));
             tokens.push({
                 literal: word
             });
@@ -67,7 +116,7 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
         const next = tokens[index + 1];
         if (!('param' in token) || !token.optional || !next) return;
         if (!('param' in next) || !next.optional) {
-            throw new Error(`{${token.param}?} is optional, so only optional params may follow it; "${'param' in next ? `{${next.param}}` : next.literal}" is not.`);
+            throw new Error(`${writtenParam(token)} is optional, so only optional params may follow it; "${'param' in next ? writtenParam(next) : next.literal}" is not.`);
         }
         if (token.type === undefined || token.type === 'string') {
             throw new Error(`{${token.param}${token.type ? ':string' : ''}?} comes before another optional param, so it needs a type that tells its words ` + `from the next param's, such as {${token.param}:int?}: as text, it would take every word.`);
@@ -80,10 +129,15 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
         rest: params.some((token)=>token.rest),
         optional: params.some((token)=>token.optional)
     });
+    const inheritedNames = [
+        ...params.map((token)=>token.param),
+        ...flags.map((flag)=>flag.flag)
+    ].filter((name)=>name in Object.prototype);
     return {
         tokens,
         flags,
-        specificity
+        specificity,
+        inheritedNames
     };
 }
 /** A prefix setting as a list, where `''` stands for none. */ function prefixList(prefix) {
@@ -134,7 +188,20 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
         ...mention
     ]);
 }
-/** Whether two routes accept some of the same messages: a start they share, and words that match alike. */ function sameMessages(a, b, options) {
+/** Where two routes of equal rank and shape part: the one with a required param where the other has an optional one comes first. */ function compareOptional(a, b) {
+    for(let i = 0; i < Math.min(a.length, b.length); i++){
+        const [aToken, bToken] = [
+            a[i],
+            b[i]
+        ];
+        if ('param' in aToken && 'param' in bToken && aToken.optional !== bToken.optional) return aToken.optional ? 1 : -1;
+    }
+    return 0;
+}
+/**
+ * Whether two routes accept some of the same messages: a start they share, and words that match alike. `'optional'`
+ * when they do only because a required param and an optional one, in one position, both take a word there.
+ */ function sameMessages(a, b, options) {
     // A case-insensitive word matches every message the case-sensitive one does
     const exact = a.caseSensitive && b.caseSensitive;
     const key = (start)=>typeof start === 'string' && !exact ? start.toLowerCase() : start;
@@ -152,13 +219,55 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
         ].some((start)=>theirs.has(key(start)));
     });
     if (!startAlike || a.tokens.length !== b.tokens.length) return false;
-    return a.tokens.every((token, i)=>{
+    let byOptional = false;
+    const alike = a.tokens.every((token, i)=>{
         const other = b.tokens[i];
         if ('literal' in token) {
             return 'literal' in other && (exact ? token.literal === other.literal : token.literal.toLowerCase() === other.literal.toLowerCase());
         }
-        return 'param' in other && token.rest === other.rest && token.optional === other.optional;
+        if (!('param' in other) || token.rest !== other.rest) return false;
+        if (token.optional !== other.optional) byOptional = true;
+        return true;
     });
+    return alike && (byOptional ? 'optional' : true);
+}
+/** What a static empty prefix list does now, which a prefix function's `[]` doesn't: take messages as they are. */ const EMPTY_PREFIX_LIST = "`[]` takes messages as they are, with no prefix; write `''` for that";
+/**
+ * The warnings for message handlers a bot starts with today though a message can't reach them as written, each once,
+ * for the app or the handler: a static empty prefix list, which takes messages as they are, where a prefix function's
+ * `[]` starts no command; and two flags of a command that reads flags in any case whose names differ only in case, the
+ * second of which is never set. The next major version (5.0) changes the first and refuses the second.
+ */ function messageRouteWarnings(routes, options) {
+    const warnings = [];
+    if (Array.isArray(options.prefix) && options.prefix.length === 0) {
+        warnings.push(`@MeoCord({ messages: { prefix: [] } }): ${EMPTY_PREFIX_LIST}. In the next major version (5.0), \`[]\` starts no command, ` + "as a prefix function's `[]` does.");
+    }
+    const seen = new Map();
+    for (const route of routes){
+        // A handler's aliases share its options and flags, so each is read once; one method can carry several handlers
+        const pattern = route.aliasOf ?? route.pattern;
+        const methods = seen.get(route.controllerClass) ?? seen.set(route.controllerClass, new Map()).get(route.controllerClass);
+        const patterns = methods.get(route.method) ?? methods.set(route.method, new Set()).get(route.method);
+        if (patterns.has(pattern)) continue;
+        patterns.add(pattern);
+        const handler = `${route.controllerClass.name}.${route.method}: @MessageHandler('${pattern}'`;
+        const own = getMessageHandlers(route.controllerClass.prototype).find((candidate)=>candidate.method === route.method && candidate.pattern === pattern)?.options;
+        if (Array.isArray(own?.prefix) && own.prefix.length === 0) {
+            warnings.push(`${handler}, { prefix: [] }): ${EMPTY_PREFIX_LIST}, or \`false\` for no prefix and no mention. In the next major ` + 'version (5.0), `[]` starts no command.');
+        }
+        if (route.caseSensitive) continue;
+        const first = new Map();
+        for (const flag of route.flags){
+            const same = first.get(flag.flag.toLowerCase());
+            if (!same) {
+                first.set(flag.flag.toLowerCase(), flag);
+                continue;
+            }
+            warnings.push(`${handler}): ${writtenFlag(same)} and ${writtenFlag(flag)} differ only in case, and this command reads flags in any ` + `case, so --${flag.flag} always sets ${writtenFlag(same)} and ${writtenFlag(flag)} is never set. Rename one, or set ` + 'caseSensitive: true. The next major version (5.0) refuses this.');
+            break;
+        }
+    }
+    return warnings;
 }
 /**
  * Every patterned message handler of the given controllers, most specific first, read from metadata
@@ -227,14 +336,21 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
             });
         }
     }
-    routes.sort((a, b)=>b.specificity - a.specificity || compareShapes(a.tokens, b.tokens) || Number(takesAppStart(a)) - Number(takesAppStart(b)));
+    routes.sort((a, b)=>b.specificity - a.specificity || compareShapes(a.tokens, b.tokens) || compareOptional(a.tokens, b.tokens) || Number(takesAppStart(a)) - Number(takesAppStart(b)));
     for(let i = 0; i < routes.length; i++){
         for(let j = i + 1; j < routes.length; j++){
             const [a, b] = [
                 routes[i],
                 routes[j]
             ];
-            if (!sameMessages(a, b, options)) continue;
+            const same = sameMessages(a, b, options);
+            if (!same) continue;
+            // Ranked by their params, so the same one answers whatever the order; 5.0 refuses these as it does the rest
+            if (same === 'optional') {
+                if (a.controllerClass === b.controllerClass && a.method === b.method) continue;
+                warnOnce(logger, `${a.controllerClass.name}.${a.method}: ${describeRoute(a)} and ${describeRoute(b)} in ${b.controllerClass.name}.${b.method} can ` + `take the same messages, as one takes a word where the other has an optional param; ${a.controllerClass.name}.${a.method} ` + 'answers those. Change one pattern, or give one its own prefix. The next major version (5.0) stops the bot at startup for these.');
+                continue;
+            }
             // One handler under two spellings, such as 'hello' and 'Hello', is one route, its pattern's over an alias's
             if (a.controllerClass === b.controllerClass && a.method === b.method) {
                 if (a.aliasOf && !b.aliasOf) routes[i] = b;
@@ -279,7 +395,7 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
     if (scope !== 'dm') return;
     const param = tokens.find((token)=>'param' in token && token.type !== undefined && isGuildType(token.type));
     const flag = flags.find((candidate)=>candidate.type !== undefined && isGuildType(candidate.type));
-    const shown = param ? `{${param.param}:${param.type}}` : flag && `{--${flag.flag}:${flag.type}}`;
+    const shown = param ? writtenParam(param) : flag && writtenFlag(flag);
     if (shown) throw new Error(`scope is 'dm', but ${shown} is found only in a server.`);
 }
 /** Refuses a handler's `mention` other than `'only'`. */ function assertMention({ mention }) {
@@ -391,11 +507,11 @@ const trieNode = ()=>({
     for(let t = 0; t < tail.length && w < words.length; t++){
         const token = tail[t];
         if (token.rest) {
-            params[token.param] = restFrom(text, words[w].start, cuts);
+            setOwn(params, token.param, restFrom(text, words[w].start, cuts));
             return params;
         }
         if (t < tail.length - 1 && !fitsParamType(token.type, words[w].value, caseSensitive)) continue;
-        params[token.param] = words[w++].value;
+        setOwn(params, token.param, words[w++].value);
     }
     return w === words.length ? params : undefined;
 }
@@ -440,9 +556,12 @@ const wordKey = (word, caseSensitive)=>caseSensitive ? word : word.toLowerCase()
                 return;
             }
             if ('literal' in token) {
+                var _node1;
                 const key = wordKey(token.literal, route.caseSensitive);
                 let next = node.words.get(key);
                 if (!next) node.words.set(key, next = trieNode());
+                // Such a word typed bare is taken out as a flag before the words are walked, so it is matched as one too
+                if (route.flags.length > 0 && token.literal.startsWith('--')) ((_node1 = node).flagWords ?? (_node1.flagWords = new Map())).set(key, next);
                 node = next;
                 continue;
             }
@@ -461,6 +580,8 @@ const wordKey = (word, caseSensitive)=>caseSensitive ? word : word.toLowerCase()
     ];
     for (const group of all){
         const flagged = group.flagged;
+        // A pattern's own leading `--` word stays reachable there: given bare, it is taken out as a flag, so the message
+        // seems to start with one
         if (flagged) group.flaggedAfterFlag = {
             ...flagged,
             words: new Map()
@@ -501,7 +622,16 @@ const wordKey = (word, caseSensitive)=>caseSensitive ? word : word.toLowerCase()
     if (first === undefined || node.param || node.rests.length > 0 || node.tails.length > 0 || node.ends.length > 0) return true;
     return node.words.has(first);
 }
-/** The ranks of every route the words reach from `node`. Each node sits at one word depth, so each is visited once. */ function reach(node, words, i, text, cuts, caseSensitive, found) {
+/**
+ * The ranks of every route the words reach from `node`. A pattern's own `--` word is reached by that word, or by a flag
+ * of its name given bare in its place, which takes no word.
+ */ function reach(node, words, i, text, cuts, caseSensitive, flags, found) {
+    if (node.flagWords) {
+        for (const flag of flags){
+            const next = flag.at === i && flag.value === undefined ? node.flagWords.get(wordKey(`--${flag.name}`, caseSensitive)) : undefined;
+            if (next) reach(next, words, i, text, cuts, caseSensitive, flags, found);
+        }
+    }
     for (const tail of node.tails)if (assignTail(tail.tokens, words, i, text, cuts, caseSensitive)) found.push(tail.rank);
     if (i === words.length) {
         for (const rank of node.ends)found.push(rank);
@@ -509,22 +639,34 @@ const wordKey = (word, caseSensitive)=>caseSensitive ? word : word.toLowerCase()
     }
     for (const rank of node.rests)found.push(rank);
     const next = node.words.get(wordKey(words[i].value, caseSensitive));
-    if (next) reach(next, words, i + 1, text, cuts, caseSensitive, found);
-    if (node.param) reach(node.param, words, i + 1, text, cuts, caseSensitive, found);
+    if (next) reach(next, words, i + 1, text, cuts, caseSensitive, flags, found);
+    if (node.param) reach(node.param, words, i + 1, text, cuts, caseSensitive, flags, found);
 }
-/** The params a route's words capture, given words its pattern is known to match. */ function paramsOf(route, words, text, cuts) {
+/**
+ * The params a route's words capture, given words its pattern is known to match. A pattern's own `--` word that the
+ * message gave as a flag, one of `taken`, takes no word.
+ */ function paramsOf(route, words, text, cuts, taken) {
     const tail = tailStart(route.tokens);
-    const params = tail === -1 ? {} : assignTail(route.tokens.slice(tail), words, tail, text, cuts, route.caseSensitive);
-    for(let i = 0; i < (tail === -1 ? route.tokens.length : tail) && i < words.length; i++){
+    const params = {};
+    let left = taken;
+    let w = 0;
+    for(let i = 0; i < (tail === -1 ? route.tokens.length : tail) && w < words.length; i++){
         const token = route.tokens[i];
-        if ('literal' in token) continue;
+        if ('literal' in token) {
+            if (left > 0 && token.literal.startsWith('--') && wordKey(words[w].value, route.caseSensitive) !== wordKey(token.literal, route.caseSensitive)) left--;
+            else w++;
+            continue;
+        }
         if (token.rest) {
-            params[token.param] = restFrom(text, words[i].start, cuts);
-            break;
+            setOwn(params, token.param, restFrom(text, words[w].start, cuts));
+            return params;
         }
-        params[token.param] = words[i].value;
+        setOwn(params, token.param, words[w++].value);
     }
-    return params;
+    return tail === -1 ? params : {
+        ...params,
+        ...assignTail(route.tokens.slice(tail), words, w, text, cuts, route.caseSensitive)
+    };
 }
 /**
  * The text after the start a message used for the group's routes, or `undefined` when it used none: a mention
@@ -577,7 +719,7 @@ const indexes = new WeakMap();
         const found = [];
         if (mayEnter(group.root, first)) {
             const words = wordsOf(rest);
-            reach(group.root, words, 0, rest, NONE, group.caseSensitive, found);
+            reach(group.root, words, 0, rest, NONE, group.caseSensitive, NONE, found);
             for (const rank of found){
                 if (fitsScope(routes[rank].scope, starts.inGuild)) {
                     if (!best || rank < best.rank) best = {
@@ -606,7 +748,7 @@ const indexes = new WeakMap();
         };
         found.length = 0;
         const from = scanned.words[0]?.start === 0 ? flagged : group.flaggedAfterFlag;
-        reach(from, scanned.words, 0, rest, scanned.cuts, group.caseSensitive, found);
+        reach(from, scanned.words, 0, rest, scanned.cuts, group.caseSensitive, scanned.flags, found);
         for (const rank of found){
             const candidate = {
                 rank,
@@ -623,11 +765,16 @@ const indexes = new WeakMap();
     const chosen = best ?? outside;
     if (!chosen) return undefined;
     const route = routes[chosen.rank];
-    const params = paramsOf(route, chosen.words, chosen.rest, chosen.cuts);
-    for (const { name, value } of chosen.flags){
+    // The flags the pattern's own `--` words took are those words, and set none of its flags
+    const taken = literalFlags(route.tokens, route.caseSensitive, chosen.words, chosen.flags);
+    const params = paramsOf(route, chosen.words, chosen.rest, chosen.cuts, taken.size);
+    chosen.flags.forEach(({ name, value }, index)=>{
+        if (taken.has(index)) return;
         const declared = route.flags.find((flag)=>wordKey(flag.flag, route.caseSensitive) === wordKey(name, route.caseSensitive));
-        if (declared) params[declared.flag] = value ?? '';
-    }
+        if (declared) setOwn(params, declared.flag, value ?? '');
+    });
+    // A param or flag left out reads as left out, not as what Object.prototype has under its name
+    if (route.inheritedNames.length > 0) shadowInherited(params, route.inheritedNames);
     return {
         route,
         params,
@@ -657,19 +804,28 @@ const indexes = new WeakMap();
         if (first !== undefined && !group.commands.has(first)) continue;
         const plain = splitWords(rest);
         // A route with flags counts the words left once the message's flags are taken out
-        const positional = mayEnter(group.flagged, first) && rest.includes('--') ? splitFlagWords(rest).words : plain;
+        const scanned = mayEnter(group.flagged, first) && rest.includes('--') ? splitFlagWords(rest) : {
+            words: plain,
+            flags: NONE
+        };
         const candidates = group.commands.get(wordKey(plain[0]?.value ?? '', group.caseSensitive)) ?? [];
         for (const rank of candidates){
             if (best && rank >= best.rank) break;
-            const words = routes[rank].flags.length > 0 ? positional : plain;
-            const command = commandWordsOf(routes[rank].tokens);
-            if (command.every((word, i)=>words[i] && wordKey(words[i].value, group.caseSensitive) === wordKey(word, group.caseSensitive))) {
+            const flagged = routes[rank].flags.length > 0;
+            const words = flagged ? scanned.words : plain;
+            const flags = flagged ? scanned.flags : NONE;
+            const taken = commandWordsTaken(commandWordsOf(routes[rank].tokens), words, flags, group.caseSensitive);
+            if (taken !== -1) {
                 const named = {
                     rank,
                     start: text.slice(0, text.length - rest.length),
-                    given: words.length - command.length
+                    given: {
+                        words,
+                        flags
+                    }
                 };
-                if (fitsScope(routes[rank].scope, starts.inGuild)) {
+                // Where it works as dispatch answers it, so a DM's usage comes from a route that works there
+                if (fitsScope(effectiveScope(routes[rank]), starts.inGuild)) {
                     best = named;
                     break;
                 }
@@ -684,6 +840,17 @@ const indexes = new WeakMap();
         given: chosen.given
     };
 }
+/**
+ * How many of a message's words a route's command words take, or -1 when the message names another command. A
+ * command's own `--` word may be given bare as a flag in its place, and takes no word.
+ */ function commandWordsTaken(command, words, flags, caseSensitive) {
+    let w = 0;
+    for (const word of command){
+        if (words[w] && wordKey(words[w].value, caseSensitive) === wordKey(word, caseSensitive)) w++;
+        else if (!flags.some((flag)=>isLiteralFlag(flag, word, w, caseSensitive))) return -1;
+    }
+    return w;
+}
 /**
  * The subcommands a message names the parent of, when no pattern matches it and it names no command: the routes whose
  * command words begin with the most of the message's words, short of all of them, as `!config` does for `config set …`
@@ -726,11 +893,18 @@ const indexes = new WeakMap();
     }
     return found.length > 0 ? found : undefined;
 }
+/**
+ * Whether a message has text a handler could take; dispatch runs no handler for one without. Content that isn't a
+ * string, as a mock's placeholder without strict mocks, is no text.
+ */ function hasMessageText(content) {
+    return typeof content === 'string' && content.trim() !== '';
+}
 /**
  * What a test calling a handler with a message alone passes as its params, as dispatch builds them: `undefined` for a
- * listener, `{}` for a message without content, else what the pattern captures with the route and start; for one naming
- * the command without fitting it, the route, start and `given`, the words after the command words. Either only when
- * dispatch would give the message to this handler among `controllers`; otherwise why it does not reach the handler.
+ * listener, `{}` for a message whose content isn't a string, as a mock's without strict mocks, else what the pattern
+ * captures with the route and start; for one naming the command without fitting it, the route, start and `given`, the
+ * message's words and flags. Either only when dispatch would give the message to this handler among
+ * `controllers`; otherwise why it does not reach the handler, a message with no text included.
  */ async function messageParamsFor(controllerClass, methodName, message, options, controllers = [
     controllerClass
 ]) {
@@ -742,6 +916,13 @@ const indexes = new WeakMap();
     if (typeof message.content !== 'string') return {
         params: {}
     };
+    const handler = `${controllerClass.name}.${methodName}`;
+    const pattern = routes.find((route)=>!route.aliasOf)?.pattern ?? routes[0].pattern;
+    if (!hasMessageText(message.content)) {
+        return {
+            mismatch: `message has no text, so dispatch runs no handler for it: give the mock the content ${handler}'s pattern '${pattern}' takes.`
+        };
+    }
     const botId = message.client?.user?.id;
     const all = buildMessageRoutes(controllers, options);
     const starts = await messageStartsFor(all, options, message, typeof botId === 'string' ? botId : undefined);
@@ -750,7 +931,7 @@ const indexes = new WeakMap();
     if (target && (target.route.controllerClass !== controllerClass || target.route.method !== methodName)) {
         const other = `${target.route.controllerClass.name}.${target.route.method}`;
         return {
-            mismatch: `message '${message.content}' does not reach ${controllerClass.name}.${methodName}: dispatch runs ${other}.`
+            mismatch: `message '${message.content}' does not reach ${handler}: dispatch runs ${other}.`
         };
     }
     if (target && 'params' in target) return {
@@ -764,10 +945,9 @@ const indexes = new WeakMap();
         start: target.start,
         given: target.given
     };
-    const pattern = routes.find((route)=>!route.aliasOf)?.pattern ?? routes[0].pattern;
     return {
-        mismatch: `message '${message.content}' does not match ${controllerClass.name}.${methodName}'s pattern '${pattern}'.`
+        mismatch: `message '${message.content}' does not match ${handler}'s pattern '${pattern}'.`
     };
 }
 
-export { afterStart, buildMessageRoutes, commandWordsOf, fitsScope, matchMessageCommand, matchMessageRoute, matchMessageSubcommands, messageParamsFor, messageStarts, messageStartsFor, parseMessagePattern, staticMessageStarts, usesAppPrefix };
+export { afterStart, buildMessageRoutes, commandWordsOf, fitsScope, hasMessageText, matchMessageCommand, matchMessageRoute, matchMessageSubcommands, messageParamsFor, messageRouteWarnings, messageStarts, messageStartsFor, parseMessagePattern, staticMessageStarts, usesAppPrefix };

package/dist/esm/core/message-words.js

@@ -109,7 +109,8 @@ const isFlagNameChar = (code, first)=>code >= 97 && code <= 122 || code >= 65 &&
                 }
                 flags.push({
                     name,
-                    value
+                    value,
+                    at: words.length
                 });
                 cuts.push(start, j);
                 i = j;
@@ -144,5 +145,32 @@ const isFlagNameChar = (code, first)=>code >= 97 && code <= 122 || code >= 65 &&
     }
     return (rest + text.slice(from)).trimEnd();
 }
+const caseKey = (word, caseSensitive)=>caseSensitive ? word : word.toLowerCase();
+/** Whether a flag, given bare in place `at` among the other words, is a pattern's own `--` word `literal`. */ const isLiteralFlag = (flag, literal, at, caseSensitive)=>flag.at === at && flag.value === undefined && caseKey(`--${flag.name}`, caseSensitive) === caseKey(literal, caseSensitive);
+/**
+ * The flags a pattern's own `--` words take from a message, as indexes into `flags`: where the pattern has such a word,
+ * a flag of that name given bare in that place among the message's other words is the word, not a flag. A word typed in
+ * quotes is matched as any word is, and is taken first.
+ */ function literalFlags(tokens, caseSensitive, words, flags) {
+    const taken = new Set();
+    if (flags.length === 0) return taken;
+    let w = 0;
+    for (const token of tokens){
+        if (!('literal' in token)) {
+            // Literal words come before the optional and rest params, which a pattern ends with
+            if (token.rest || token.optional) break;
+            w++;
+            continue;
+        }
+        if (w < words.length && caseKey(words[w].value, caseSensitive) === caseKey(token.literal, caseSensitive)) {
+            w++;
+            continue;
+        }
+        const index = flags.findIndex((flag, i)=>!taken.has(i) && isLiteralFlag(flag, token.literal, w, caseSensitive));
+        if (index === -1) break;
+        taken.add(index);
+    }
+    return taken;
+}
 
-export { isSpace, restFrom, splitFlagWords, splitWords };
+export { caseKey, isLiteralFlag, isSpace, literalFlags, restFrom, splitFlagWords, splitWords };

package/dist/esm/core/observer-runner.js

@@ -5,6 +5,7 @@ import { bindShared } from './interceptor-runner.js';
 import { appliesTo } from './stage-scope.js';
 import { respond } from '../common/response/response-state.js';
 import { startupError } from '../util/refusal.util.js';
+import { isConstructor } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
 /** Where a container keeps the observers its calls are reported to, in order. */ const OBSERVERS = Symbol('observers');
@@ -12,7 +13,7 @@ const logger = new Logger('Observer');
 /** Reports each entry that is not an `@Observer` class, naming where it was listed. */ function assertObservers(where, observers) {
     for (const observer of observers){
         if (typeof observer !== 'function' || !Reflect.getMetadata(META.observerClass, observer)) {
-            const name = typeof observer === 'function' ? observer.name : String(observer);
+            const name = isConstructor(observer) ? observer.name || 'an anonymous class' : typeof observer === 'function' ? 'a function' : String(observer);
             startupError(new Error(`${where} takes classes decorated with @Observer(), not ${name}.`));
             continue;
         }
@@ -68,8 +69,9 @@ function observersOf(container) {
 }
 /**
  * Where an interaction's answer stands: a repliable one's `ResponseState`, and an autocomplete answered
- * or not. `undefined` for anything that is not an interaction.
+ * or not. `undefined` for anything that is not an interaction's call, an event carrying one included.
  */ function responsePhaseOf(context) {
+    if (context.getType() === 'event') return undefined;
     const interaction = context.getInteraction();
     if (!interaction) return undefined;
     if (interaction.isAutocomplete()) return interaction.responded ? 'replied' : 'unanswered';

package/dist/esm/core/process-state.js

@@ -0,0 +1,19 @@
+import { stopRequests } from '../util/stop-request.util.js';
+import { shared } from '../util/shared-state.util.js';
+
+/** Where both builds of this version keep the process's state, as {@link shared} names it. */ const PROCESS_STATE = 'processState';
+/**
+ * What the process's apps share, kept by both builds of this version, so a process that loads both has one pair of
+ * signal listeners and one shutdown, which stops the apps either build started, one exit code a failed start set, and
+ * one end of a failed shard.
+ */ const processState = shared(PROCESS_STATE, ()=>({
+        /** Closes each started app: runs its shutdown hooks and destroys its client, resolving `false` on failure. */ runningApps: new Set(),
+        stopRequest: stopRequests(),
+        signalHandlersInstalled: false,
+        shuttingDown: undefined,
+        /** Whether a failed start, of a provider's factory or the login, set the exit code, so a later login knows to clear it. */ startFailureSetExitCode: false,
+        /** Whether `meocord start --dev` was told the bot could not log in, so a later login tells it the bot is online. */ toldDevRunnerLoginFailed: false,
+        /** Whether this shard is already ending, so a failure reported twice, as one going on uncaught is, ends it once. */ shardEnding: false
+    }));
+
+export { processState };