meocord 4.2.1 → 4.2.3

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

@@ -1,5 +1,5 @@
 import { fitsScope, commandWordsOf, afterStart } from './message-routes.js';
-import { isGuildType, primaryFirst, usageOf, paramTypeLabel } from './message-params.js';
+import { effectiveScope, primaryFirst, usageOf, paramTypeLabel } from './message-params.js';
 import { splitWords } from './message-words.js';
 import { usageHeading } from '../common/errors.js';
 import { textRenderer } from '../common/meocord-text.js';
@@ -31,12 +31,13 @@ import { userWords } from '../util/user-text.util.js';
     const text = content.trim();
     const rest = afterStart(text, starts.prefixes.filter((prefix)=>prefix !== ''), starts.mention, caseSensitive);
     if (!rest) return undefined;
-    const [first] = splitWords(rest);
+    const [first, second] = splitWords(rest);
     const key = (word)=>caseSensitive ? word : word.toLowerCase();
     if (!first || !words.some((word)=>key(word) === key(first.value))) return undefined;
+    // From where the next word starts, as the help word may have been written in quotes
     return {
         start: text.slice(0, text.length - rest.length),
-        query: rest.slice(first.value.length).trim()
+        query: second ? rest.slice(second.start).trim() : ''
     };
 }
 /** The start a caller would type a route with here: its own prefix, a mention, or the start the help message used. */ function displayStart(route, start, starts) {
@@ -45,11 +46,6 @@ import { userWords } from '../util/user-text.util.js';
     if (route.prefix !== undefined) return route.prefix[0] ?? '';
     return start;
 }
-/** Where a route works: its scope, narrowed to servers by a `member`, `role` or `channel` param or flag. */ function effectiveScope(route) {
-    if (route.scope !== 'any') return route.scope;
-    const guildOnly = route.tokens.some((token)=>'param' in token && token.type !== undefined && isGuildType(token.type)) || route.flags.some((flag)=>flag.type !== undefined && isGuildType(flag.type));
-    return guildOnly ? 'guild' : 'any';
-}
 /** A route's params and flags, each with what it takes in words. */ function paramsOf(route, types, render) {
     const params = route.tokens.flatMap((token)=>{
         if (!('param' in token)) return [];
@@ -249,23 +245,49 @@ const sortedEntries = (entries)=>entries.sort((a, b)=>a.usage < b.usage ? -1 : a
         scope
     ].filter((line)=>line !== undefined).join('\n');
 }
-/** Splits a reply into Discord-sized messages at line breaks, a line longer than one message cut where it must be. */ function splitReply(text) {
+// Built on first use, for a line longer than a message
+let graphemes;
+/**
+ * Where a line longer than one message is cut: after the last character a reader sees as one, such as an emoji, a flag
+ * or a letter with its accent, that still fits. A single such character longer than a message is cut between code points.
+ */ function fittingCut(piece) {
+    let cut = 0;
+    graphemes ?? (graphemes = new Intl.Segmenter(undefined, {
+        granularity: 'grapheme'
+    }));
+    for (const { index, segment } of graphemes.segment(piece)){
+        if (index + segment.length > MAX_REPLY_LENGTH) break;
+        cut = index + segment.length;
+    }
+    if (cut > 0) return cut;
+    const high = piece.charCodeAt(MAX_REPLY_LENGTH - 1);
+    return high >= 0xd800 && high <= 0xdbff ? MAX_REPLY_LENGTH - 1 : MAX_REPLY_LENGTH;
+}
+/**
+ * Splits a reply into Discord-sized messages at line breaks, a line longer than one message cut where it must be. A
+ * message of only whitespace, which Discord refuses as empty, is left out.
+ */ function splitReply(text) {
     const chunks = [];
+    const push = (chunk)=>{
+        if (chunk.trim() !== '') chunks.push(chunk);
+    };
     let current = '';
     for (const line of text.split('\n')){
-        for(let piece = line;; piece = piece.slice(MAX_REPLY_LENGTH)){
-            const part = piece.slice(0, MAX_REPLY_LENGTH);
+        for(let piece = line;;){
+            const cut = piece.length <= MAX_REPLY_LENGTH ? piece.length : fittingCut(piece);
+            const part = piece.slice(0, cut);
             const joined = current ? `${current}\n${part}` : part;
             if (joined.length <= MAX_REPLY_LENGTH) current = joined;
             else {
-                chunks.push(current);
+                push(current);
                 current = part;
             }
-            if (piece.length <= MAX_REPLY_LENGTH) break;
+            if (cut === piece.length) break;
+            piece = piece.slice(cut);
         }
     }
-    if (current) chunks.push(current);
+    push(current);
     return chunks;
 }
 
-export { computeMessageHelp, effectiveScope, helpInvocation, helpWords, isListable, matchHelpRequest, renderMessageHelp, splitReply };
+export { computeMessageHelp, helpInvocation, helpWords, isListable, matchHelpRequest, renderMessageHelp, splitReply };

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

@@ -1,9 +1,10 @@
 import { MessageUsageError } from '../common/errors.js';
 import { usageIssue } from '../common/meocord-text.js';
 import { MessageEntityRef, resolveRefs } from './message-entities.js';
-import { splitWords, splitFlagWords } from './message-words.js';
+import { caseKey, isLiteralFlag, splitWords, splitFlagWords, literalFlags } from './message-words.js';
 import { lookupTable, duration, bool, number, choicesOf } from './scalar-types.js';
 import { userWords } from '../util/user-text.util.js';
+import { setOwn, ownValue, shadowInherited } from '../util/value.util.js';
 
 /** The ID a mention or a bare snowflake names, for the mention's kind. */ function idOf(word, mention) {
     return (mention.exec(word) ?? /^(\d{17,20})$/.exec(word))?.[1];
@@ -11,6 +12,10 @@ import { userWords } from '../util/user-text.util.js';
 const USER_MENTION = /^<@!?(\d{17,20})>$/;
 const ROLE_MENTION = /^<@&(\d{17,20})>$/;
 const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
+/** The server's role a word names: its mention or ID, else its name in any case. */ function roleNamed(guild, word) {
+    const id = idOf(word, ROLE_MENTION);
+    return id ? guild.roles.cache.get(id) : guild.roles.cache.find((candidate)=>candidate.name.toLowerCase() === word.toLowerCase());
+}
 /** The scalar types, each turning a word into its value or `undefined`, and the Discord ones, which resolve below. */ const BUILT_IN_TYPES = lookupTable({
     string: (word)=>word,
     int: (word)=>number(word, true),
@@ -41,7 +46,18 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     'channel'
 ]);
 /** Whether a param type is found only in a server. */ const isGuildType = (type)=>GUILD_TYPES.has(type);
-/** Whether a route's pattern takes a param found only in a server, so a DM gets its usage instead. */ const needsGuild = (route)=>route.tokens.some((token)=>'param' in token && token.type !== undefined && GUILD_TYPES.has(token.type));
+/** Whether a route's pattern takes a `member`, `role` or `channel` param, optional or not. */ const takesGuildParam = (route)=>route.tokens.some((token)=>'param' in token && token.type !== undefined && GUILD_TYPES.has(token.type));
+/**
+ * Whether a route works only in a server, as dispatch decides it: a `member`, `role` or `channel` param, optional or
+ * not, or a required flag of one of those types. An optional flag of those types refuses a DM only when it is given.
+ */ const needsGuild = (route)=>takesGuildParam(route) || route.flags.some((flag)=>!flag.optional && flag.type !== undefined && GUILD_TYPES.has(flag.type));
+/**
+ * Where a route works: its scope, narrowed to servers by a `member`, `role` or `channel` param, or required flag, as
+ * dispatch narrows it.
+ */ function effectiveScope(route) {
+    if (route.scope !== 'any') return route.scope;
+    return needsGuild(route) ? 'guild' : 'any';
+}
 /** Whether a pattern's `{name:type}` names a type: built in, words to choose from, or one the app adds. */ function isKnownParamType(type, types) {
     return type in BUILT_IN_TYPES || Boolean(choicesOf(type)) || appType(types, type) !== undefined;
 }
@@ -121,14 +137,7 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
  */ function assertMessageScope(route, message, start) {
     const inGuild = message.guildId !== null && message.guildId !== undefined;
     if (route.scope === 'guild' && !inGuild) {
-        throw new MessageUsageError(usageOf(route, start), [
-            usageIssue({
-                key: 'meocord.usage.serverOnly'
-            })
-        ], {
-            serverOnly: true,
-            quiet: start === ''
-        });
+        throw serverOnly(usageOf(route, start), start === '');
     }
     if (route.scope === 'dm' && inGuild) {
         throw new MessageUsageError(usageOf(route, start), [
@@ -141,6 +150,15 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
         });
     }
 }
+/** The usage error for a message sent outside a server to a command, or with a flag, that only a server has. */ const serverOnly = (usage, quiet)=>new MessageUsageError(usage, [
+        usageIssue({
+            key: 'meocord.usage.serverOnly'
+        })
+    ], {
+        serverOnly: true,
+        quiet
+    });
+/** Whether a message gives one of a route's flags of a type only a server has, such as `--in=#general`. */ const givesGuildFlag = (route, flags)=>flags.some((given)=>route.flags.some((flag)=>flag.type !== undefined && GUILD_TYPES.has(flag.type) && caseKey(flag.flag, route.caseSensitive) === caseKey(given.name, route.caseSensitive)));
 /** Whether a value an app's `parse` returned is a ref to resolve after the guards. */ const isRef = (value)=>typeof value === 'object' && value !== null && 'cached' in value && typeof value.resolve === 'function';
 /**
  * The params a matched route's guards see, read from the words with no request to Discord: typed params and lists as
@@ -163,18 +181,20 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     const issues = [];
     const items = [];
     for (const token of route.tokens){
-        if (!('param' in token) || token.type === undefined || raw[token.param] === undefined) continue;
+        // Only a word the message gave is typed: an own one, never what Object.prototype has under the param's name
+        const word = 'param' in token ? ownValue(raw, token.param) : undefined;
+        if (!('param' in token) || token.type === undefined || word === undefined) continue;
         if (!token.rest) {
             items.push({
                 key: token.param,
                 label: token.param,
                 type: token.type,
-                word: raw[token.param]
+                word
             });
             continue;
         }
-        const words = splitWords(raw[token.param]);
-        params[token.param] = new Array(words.length);
+        const words = splitWords(word);
+        setOwn(params, token.param, new Array(words.length));
         words.forEach(({ value }, index)=>items.push({
                 key: token.param,
                 label: token.param,
@@ -184,19 +204,12 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
             }));
     }
     const flagIssues = route.flags.length > 0 ? readFlags(route, message, start, params, items) : [];
+    // readFlags takes out each flag's key, so one left out whose name Object.prototype has reads as left out again
+    if (route.inheritedNames.length > 0) shadowInherited(params, route.inheritedNames);
     const guild = message.guild;
-    if (!guild && (needsGuild(route) || items.some((item)=>GUILD_TYPES.has(item.type)))) {
-        throw new MessageUsageError(usage, [
-            usageIssue({
-                key: 'meocord.usage.serverOnly'
-            })
-        ], {
-            serverOnly: true,
-            quiet
-        });
-    }
+    if (!guild && (needsGuild(route) || items.some((item)=>GUILD_TYPES.has(item.type)))) throw serverOnly(usage, quiet);
     const put = (item, value)=>{
-        if (item.index === undefined) params[item.key] = value;
+        if (item.index === undefined) setOwn(params, item.key, value);
         else params[item.key][item.index] = value;
     };
     const refs = [];
@@ -233,8 +246,7 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
             }
         } else if (type === 'role') {
             // Roles are cached with the Guilds intent, so a role is known here or not at all
-            const id = idOf(word, ROLE_MENTION);
-            const role = id ? guild.roles.cache.get(id) : guild.roles.cache.find((candidate)=>candidate.name.toLowerCase() === word.toLowerCase());
+            const role = roleNamed(guild, word);
             if (role) {
                 refer(item, 'role', new MessageEntityRef('role', role.id, message.client, guild));
                 continue;
@@ -274,9 +286,9 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     const params = {
         ...parsed.params
     };
-    for (const [key, value] of Object.entries(params))if (Array.isArray(value)) params[key] = [
+    for (const [key, value] of Object.entries(params))if (Array.isArray(value)) setOwn(params, key, [
         ...value
-    ];
+    ]);
     const issues = [];
     for (const slot of refs){
         const value = slot.ref instanceof MessageEntityRef ? found.get(slot.ref) : await slot.ref.resolve();
@@ -284,7 +296,7 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
             issues.push(missingEntity(slot));
             continue;
         }
-        if (slot.index === undefined) params[slot.key] = value;
+        if (slot.index === undefined) setOwn(params, slot.key, value);
         else params[slot.key][slot.index] = value;
     }
     if (issues.length > 0) throw new MessageUsageError(usage, issues, {
@@ -350,7 +362,11 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     return {
         parseArgs: async (args)=>{
             assertMessageScope(route, message, start);
-            if (given !== undefined) throw new MessageUsageError(usageOf(route, start), missingParams(route, given));
+            if (given !== undefined) {
+                // A DM to a command only a server has is told so before what its words lack, as one whose words fit is
+                if (!message.guild && (needsGuild(route) || givesGuildFlag(route, given.flags))) throw serverOnly(usageOf(route, start), start === '');
+                throw new MessageUsageError(usageOf(route, start), missingParams(route, given, types, message.guild));
+            }
             if (!hasTypedParams(route)) return args;
             parsed = await parseMessageParams(route, params, message, start, types);
             return [
@@ -401,7 +417,11 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     const given = new Map();
     const unknown = new Set();
     const text = (message.content ?? '').trim();
-    for (const flag of splitFlagWords(text.slice(start.length)).flags){
+    const split = splitFlagWords(text.slice(start.length));
+    // A flag the pattern's own `--` word took is that word, and neither one of its flags nor unknown
+    const literal = literalFlags(route.tokens, route.caseSensitive, split.words, split.flags);
+    for (const [index, flag] of split.flags.entries()){
+        if (literal.has(index)) continue;
         const declared = route.flags.find((candidate)=>key(candidate.flag) === key(flag.name));
         if (declared) given.set(declared.flag, flag);
         else if (!unknown.has(flag.name)) {
@@ -427,7 +447,7 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
                     value: userWords(value)
                 }
             }, flag.flag));
-            else params[flag.flag] = on;
+            else setOwn(params, flag.flag, on);
         } else if (!given.has(flag.flag)) {
             if (!flag.optional) issues.push(usageIssue({
                 key: 'meocord.usage.missing',
@@ -455,24 +475,84 @@ const CHANNEL_MENTION = /^<#(\d{17,20})>$/;
     return issues;
 }
 /**
- * What is wrong with a command whose words a message named but whose pattern it does not fit, given how many
- * words followed the command words: each required param it left out, or words beyond what the pattern takes.
- */ function missingParams(route, given) {
-    const firstParam = route.tokens.findIndex((token)=>!('literal' in token));
-    const after = firstParam === -1 ? [] : route.tokens.slice(firstParam);
-    const missing = after.slice(given).filter((token)=>'param' in token && !token.optional).map((token)=>usageIssue({
-            key: 'meocord.usage.missing',
-            params: {
-                param: token.param
+ * What is wrong with a command whose words a message named but whose pattern it does not fit, read word by word
+ * against the pattern: each word or required param it left out, a word given another in its place, else words
+ * beyond what the pattern takes, else the first word its param's built-in type does not take; and then each required
+ * flag it left out, as a message whose words fit is told. With none of those true, there are none, and the usage stands
+ * alone.
+ */ function missingParams(route, given, types, guild) {
+    const { words, flags } = given;
+    const missing = [];
+    // The flags given bare in place of the pattern's own `--` words, which are those words and set no flag
+    const literal = new Set();
+    let unfit;
+    let w = 0;
+    for (const token of route.tokens){
+        if ('literal' in token) {
+            if (w < words.length && caseKey(words[w].value, route.caseSensitive) === caseKey(token.literal, route.caseSensitive)) {
+                w++;
+                continue;
             }
-        }, token.param));
-    if (missing.length > 0) return missing;
-    return [
+            // A pattern's own `--` word given bare in its place takes no word; another word in its place is not taken
+            const word = flags.find((flag)=>!literal.has(flag) && isLiteralFlag(flag, token.literal, w, route.caseSensitive));
+            if (word) literal.add(word);
+            else missing.push(usageIssue({
+                key: 'meocord.usage.missing',
+                params: {
+                    param: token.literal
+                }
+            }));
+        } else if (w === words.length) {
+            if (!token.optional) missing.push(usageIssue({
+                key: 'meocord.usage.missing',
+                params: {
+                    param: token.param
+                }
+            }, token.param));
+        } else if (token.rest) {
+            w = words.length;
+        } else {
+            // Words fill the params in order, as the usage shows them
+            const word = words[w++].value;
+            const type = token.type;
+            if (!unfit && type !== undefined && isUnfit(type, word, route.caseSensitive, guild)) {
+                unfit = {
+                    key: token.param,
+                    label: token.param,
+                    type,
+                    word
+                };
+            }
+        }
+    }
+    // With none of these, the reason may be one MeoCord has no text for, as a role's name the matcher takes only as a
+    // mention or an ID
+    const reasons = missing.length > 0 ? missing : w < words.length ? [
         usageIssue({
             key: 'meocord.usage.tooManyWords'
         })
+    ] : unfit ? [
+        wrongType(unfit, types)
+    ] : [];
+    // So one reply names all the message lacks, rather than the flags only once its words fit
+    const missingFlags = route.flags.filter((flag)=>flag.type !== undefined && !flag.optional && !flags.some((sent)=>!literal.has(sent) && caseKey(sent.name, route.caseSensitive) === caseKey(flag.flag, route.caseSensitive))).map((flag)=>usageIssue({
+            key: 'meocord.usage.missing',
+            params: {
+                param: `--${flag.flag}`
+            }
+        }, flag.flag));
+    return [
+        ...reasons,
+        ...missingFlags
     ];
 }
+/**
+ * Whether a param of a type is known not to take a word: a built-in type or words to choose from that the word doesn't
+ * fit. A role is also found by its name, so only a word that names none of the server's roles is unfit.
+ */ function isUnfit(type, word, caseSensitive, guild) {
+    if (type === 'role') return guild !== null && roleNamed(guild, word) === undefined;
+    return (type in BUILT_IN_TYPES || Boolean(choicesOf(type))) && !fitsParamType(type, word, caseSensitive);
+}
 /** Whether a route's params need resolving: it declares a type for one, or has flags. */ const hasTypedParams = (route)=>route.flags.length > 0 || route.tokens.some((token)=>'param' in token && token.type !== undefined);
 
-export { BUILT_IN_TYPES, assertMessageScope, fetchMessageParams, fitsParamType, hasTypedParams, isGuildType, isKnownParamType, messageCommandHooks, missingParams, needsGuild, paramTypeLabel, parseMessageParams, primaryFirst, subcommandUsageError, usageOf };
+export { BUILT_IN_TYPES, assertMessageScope, effectiveScope, fetchMessageParams, fitsParamType, hasTypedParams, isGuildType, isKnownParamType, messageCommandHooks, missingParams, needsGuild, paramTypeLabel, parseMessageParams, primaryFirst, subcommandUsageError, takesGuildParam, usageOf };