chapterjs 0.1.4 → 0.2.0

package/dist/commands/{convention.js → declaration.js}

@@ -1,14 +1,15 @@
-// `src/commands/`: the path of a file is the name of a slash command.
-// Everything a file declares is checked when it loads, against the limits
-// of Discord, so a mistake is explained before Discord refuses it.
+// What a file declares with `command()`, checked when it loads against the
+// limits of Discord, so a mistake is explained before Discord refuses it.
 // https://docs.discord.com/developers/interactions/application-commands
 import { ALL_PERMISSIONS } from '../discord/permissions.js';
 import { ChannelType } from '../discord/types/channel.js';
 import { Locale } from '../discord/types/common.js';
 import { PermissionFlags } from '../discord/types/permissions.js';
 import { COOLDOWN_SCOPES, NO_COOLDOWN, } from '../interactions/cooldown.js';
+import { readFile } from 'node:fs/promises';
+import { listSources } from '../loader/loader.js';
 import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
-import { isCommandFile, } from './command.js';
+import { isCommandDeclaration, } from './command.js';
 /**
  * The names of commands and options: lowercase letters of any language,
  * digits, `-` and `_`, 32 characters at most.
@@ -39,6 +40,7 @@ const OPTION_KEYS = {
     channel: ['channelTypes'],
 };
 const COMMAND_KEYS = [
+    'name',
     'description',
     'options',
     'locales',
@@ -388,41 +390,45 @@ function checkPermissions(permissions) {
     }
     return bits & ALL_PERMISSIONS;
 }
+const EXAMPLE = `command({ name: 'ping', description: '...', run({ interaction }) { ... } })`;
 /**
- * `src/commands/`: each file is a slash command, named after its path.
- * One folder makes a command with subcommands (`mod/ban.ts` is `/mod ban`),
- * two make a group (`mod/roles/add.ts` is `/mod roles add`): Discord allows
- * nothing deeper.
+ * The parts of the name of a command: `'mod ban'` is `['mod', 'ban']`.
+ * One part is a command, two a subcommand, three a subcommand in a group:
+ * Discord allows nothing deeper.
  */
-export const commandsConvention = {
-    folder: 'commands',
+export function readCommandName(name) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        return fail(`This command has no "name": what people type after the /, like ${EXAMPLE}. A subcommand is written with its parents: name: 'mod ban' is /mod ban.`);
+    }
+    const parts = name.trim().split(/\s+/);
+    if (parts.length > 3) {
+        fail(`The name ${JSON.stringify(name)} has ${parts.length} words: Discord allows a command, a group and a subcommand, so 3 at most ('mod roles add' is /mod roles add).`);
+    }
+    for (const part of parts) {
+        if (!isName(part)) {
+            fail(`"${part}" can't be in the name of a command: use lowercase letters, digits, - and _ only, 32 characters at most.`);
+        }
+    }
+    return parts;
+}
+/**
+ * A slash command, declared anywhere in `src/` with `command()`: `name` is
+ * what people type after the `/`, with its parents for a subcommand
+ * (`'mod ban'` is `/mod ban`, `'mod roles add'` is `/mod roles add`). A
+ * file may declare several.
+ */
+export const commandDeclaration = {
     one: 'command',
     many: 'commands',
-    check(path) {
-        const parts = path.replace(/\.[^./]+$/, '').split('/');
-        if (parts.length > 3) {
-            fail(`This file is ${parts.length - 1} folders deep: Discord allows a command, a group and a subcommand, so 2 folders at most (src/commands/mod/roles/add.ts is /mod roles add).`);
-        }
-        for (const part of parts) {
-            if (!isName(part)) {
-                fail(`"${part}" can't be in the name of a command: use lowercase letters, digits, - and _ only, 32 characters at most. The path of the file is the name of the command.`);
-            }
-        }
-    },
-    read(exports, path) {
-        const file = exports.default;
-        const parts = path.replace(/\.[^./]+$/, '').split('/');
-        if (!isCommandFile(file)) {
-            const example = `import { command } from 'chapterjs'; export default command({ description: '...', run({ interaction }) { ... } })`;
-            return fail('default' in exports
-                ? `The default export of this file must be what command() returns: ${example}`
-                : `This file has no default export. It should look like: ${example}`);
-        }
-        const config = file.config;
+    is: isCommandDeclaration,
+    list: true,
+    read(value) {
+        const config = value.config;
         if (!isRecord(config)) {
-            return fail(`command() needs an object: command({ description: '...', run({ interaction }) { ... } })`);
+            return fail(`command() needs an object: ${EXAMPLE}`);
         }
         checkKeys('a command', config, COMMAND_KEYS);
+        const parts = readCommandName(config.name);
         // No description: the language files describe the command, options
         // included, and hold its translations.
         const described = config.description !== undefined;
@@ -430,7 +436,7 @@ export const commandsConvention = {
             ? checkDescription('this command', config.description)
             : '';
         if (!described && config.locales !== undefined) {
-            fail(`This command has no "description", so its texts come from the language files of src/messages/: put its "locales" there too (commands: { ... }), or give it a description here.`);
+            fail(`This command has no "description", so its texts come from the language files: put its "locales" there too (commands: { ... }), or give it a description here.`);
         }
         if (typeof config.run !== 'function') {
             fail(`This command has no "run": the function to run when someone uses it, like async run({ interaction }) { await interaction.reply('Pong!'); }`);
@@ -462,3 +468,25 @@ export const commandsConvention = {
         });
     },
 };
+/** `command({ ... name: '...' ... })`, as written in a file. */
+const DECLARED = /\bcommand\s*\(\s*\{[^]*?\bname\s*:\s*['"`]([^'"`]+)['"`]/g;
+/**
+ * The names of the commands of a project, found without running its
+ * files: a text search for `command({ name: '...' })`. Approximate on
+ * purpose, for `sync`, which runs nothing: `dev` and `build` then write
+ * the exact ones. Whether a command is described is not known: none is.
+ */
+export async function scanCommands(cwd) {
+    const names = new Set();
+    for (const { path } of await listSources(cwd)) {
+        const code = await readFile(path, 'utf8').catch(() => '');
+        if (!code.includes('command('))
+            continue;
+        for (const match of code.matchAll(DECLARED)) {
+            const name = match[1].trim().split(/\s+/).join(' ');
+            if (name !== '')
+                names.add(name);
+        }
+    }
+    return [...names].sort();
+}

package/dist/commands/tree.d.ts

@@ -1,21 +1,25 @@
 import { type BulkOverwriteGuildApplicationCommandsJSONParams } from '../discord/types/application-command.js';
-import type { LoadedCommand } from './convention.js';
+import type { LoadedCommand } from './declaration.js';
 /** A command with the file it comes from. */
 export interface CommandEntry {
     file: string;
+    /** The export it is: `'default'`, or its name. */
+    export: string;
     command: LoadedCommand;
 }
-/** Two files that can't both be commands. */
+/** Two declarations that can't both be commands. */
 export interface CommandConflict {
     file: string;
+    export: string;
     message: string;
 }
 export type CommandPayload = BulkOverwriteGuildApplicationCommandsJSONParams;
 /** `/mod ban` for `['mod', 'ban']`. */
 export declare const commandName: (path: readonly string[]) => string;
 /**
- * Finds the files that can't be commands together, and leaves them out:
- * - two files with the same name (in different `(group)` folders);
+ * Finds the declarations that can't be commands together, and leaves them
+ * out:
+ * - two commands with the same name;
  * - a command that also has subcommands: Discord only lets people use the
  *   subcommands.
  */

package/dist/commands/tree.js

@@ -1,9 +1,10 @@
-// Turns the command files of a project into what Discord registers: one
+// Turns the commands of a project into what Discord registers: one
 // application command per top-level name, with its subcommands and groups.
 // https://docs.discord.com/developers/interactions/application-commands#subcommands-and-subcommand-groups
 import { ApplicationCommandOptionType, ApplicationCommandType, } from '../discord/types/application-command.js';
 import { ApplicationIntegrationType } from '../discord/types/application.js';
 import { InteractionContextType } from '../discord/types/interaction.js';
+import { siteName } from '../loader/loader.js';
 const TYPES = {
     string: ApplicationCommandOptionType.String,
     integer: ApplicationCommandOptionType.Integer,
@@ -76,8 +77,9 @@ function toOption(option, locales, autocomplete) {
 /** `/mod ban` for `['mod', 'ban']`. */
 export const commandName = (path) => `/${path.join(' ')}`;
 /**
- * Finds the files that can't be commands together, and leaves them out:
- * - two files with the same name (in different `(group)` folders);
+ * Finds the declarations that can't be commands together, and leaves them
+ * out:
+ * - two commands with the same name;
  * - a command that also has subcommands: Discord only lets people use the
  *   subcommands.
  */
@@ -85,7 +87,13 @@ export function findConflicts(entries) {
     const conflicts = [];
     const seen = new Map();
     const unique = [...entries]
-        .sort((a, b) => (a.file < b.file ? -1 : 1))
+        .sort((a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1)
         .filter(entry => {
         const key = entry.command.path.join(' ');
         const first = seen.get(key);
@@ -95,7 +103,8 @@ export function findConflicts(entries) {
         }
         conflicts.push({
             file: entry.file,
-            message: `${commandName(entry.command.path)} is already ${first.file}: two files can't be the same command. A folder in parentheses only groups files, it is not part of the name.`,
+            export: entry.export,
+            message: `${commandName(entry.command.path)} is already declared in ${siteName(first)}: two commands can't have the same name.`,
         });
         return false;
     });
@@ -108,7 +117,8 @@ export function findConflicts(entries) {
             return true;
         conflicts.push({
             file: entry.file,
-            message: `${commandName(path)} can't be a command and have subcommands (${child.file} is ${commandName(child.command.path)}): Discord only lets people use the subcommands. Move this file into the folder, for example as ${[...path, 'run'].join('/')}.ts.`,
+            export: entry.export,
+            message: `${commandName(path)} can't be a command and have subcommands (${siteName(child)} is ${commandName(child.command.path)}): Discord only lets people use the subcommands. Make this one a subcommand too, for example name: '${[...path, 'run'].join(' ')}'.`,
         });
         return false;
     });

package/dist/components/button.d.ts

@@ -29,30 +29,29 @@ export interface ButtonLook<Data extends DataShape = DataShape> {
 }
 /** What `run` receives when the button is clicked. */
 export type ButtonContext<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = InteractiveContext<Data> & TranslationContext & PlaceOf<Where, ComponentInteraction>;
-/** What a button file gives to `button()`. */
+/** What a file gives to `button()`. */
 export interface ButtonConfig<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends ButtonLook<Data>, InteractiveConfig<Data, Where> {
     /** What to do when someone clicks the button. */
     run: (context: ButtonContext<Data, Where>) => unknown;
 }
 /**
- * What `button()` returns: the default export of a button file. Import it
- * where you send a message, and call it with the data the button carries
- * (`ban({ userId })`); a button without data is used as is (`confirm`), or
- * called with a look (`confirm({ disabled: true })`).
+ * What `button()` returns: a declaration the framework finds in the exports
+ * of a file. Import it where you send a message, and call it with the data
+ * the button carries (`ban({ userId })`); a button without data is used as
+ * is (`confirm`), or called with a look (`confirm({ disabled: true })`).
  */
-export type ButtonFile<Data extends DataShape = {}> = {
+export type ButtonDeclaration<Data extends DataShape = {}> = {
     /** What the file gave to `button()`, not checked yet. */
     readonly config: unknown;
 } & ({} extends Data ? ((look?: ButtonLook) => ButtonComponent) & ButtonComponent : {} extends DataInputOf<Data> ? ((data?: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent) & ButtonComponent : (data: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent);
 /**
- * Declares a button. Export the result as the default export of a file of
- * `src/components/buttons/`: the path of the file is what tells the
- * button apart, so you never write an id.
+ * Declares a button. Export the result from any file of `src/`: the name
+ * of the export is what tells the button apart, so you never write an id.
  *
  * ```ts
  * import { button } from 'chapterjs';
  *
- * export default button({
+ * export const confirm = button({
  *   label: 'Confirm',
  *   style: 'success',
  *   async run({ interaction }) {
@@ -61,11 +60,12 @@ export type ButtonFile<Data extends DataShape = {}> = {
  * });
  * ```
  */
-export declare function button<const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: ButtonConfig<Data, Where>): ButtonFile<Data>;
-/** A button file, checked. */
+export declare function button<const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: ButtonConfig<Data, Where>): ButtonDeclaration<Data>;
+/** A button, checked. */
 export interface LoadedButton {
     readonly kind: 'button';
-    readonly path: string;
+    /** The name of the export that declares it: its id for Discord. */
+    readonly name: string;
     readonly look: Required<Pick<ButtonLook, 'style' | 'disabled'>> & Pick<ButtonLook, 'label' | 'emoji'>;
     readonly data: DataShape;
     readonly where: ComponentWhere;

package/dist/components/button.js

@@ -1,12 +1,11 @@
-// `button()`, as the files of `src/components/buttons/` import it from
-// 'chapterjs': what the button looks like, what it carries, and what to do
-// when it is clicked.
+// `button()`, as user files import it from 'chapterjs': what the button
+// looks like, what it carries, and what to do when it is clicked.
 // https://docs.discord.com/developers/components/reference#button
 import { Limits } from '../discord/api.js';
 import { ButtonStyle, ComponentType, } from '../discord/types/component.js';
 import { isDynamic, resolveText } from './component.js';
 import { checkData, encodeCustomId, } from './custom-id.js';
-import { createFile } from './file.js';
+import { createComponent } from './declared.js';
 import { emojiOf } from './instance.js';
 export const BUTTON_STYLES = {
     primary: ButtonStyle.Primary,
@@ -15,14 +14,13 @@ export const BUTTON_STYLES = {
     danger: ButtonStyle.Danger,
 };
 /**
- * Declares a button. Export the result as the default export of a file of
- * `src/components/buttons/`: the path of the file is what tells the
- * button apart, so you never write an id.
+ * Declares a button. Export the result from any file of `src/`: the name
+ * of the export is what tells the button apart, so you never write an id.
  *
  * ```ts
  * import { button } from 'chapterjs';
  *
- * export default button({
+ * export const confirm = button({
  *   label: 'Confirm',
  *   style: 'success',
  *   async run({ interaction }) {
@@ -32,7 +30,7 @@ export const BUTTON_STYLES = {
  * ```
  */
 export function button(config) {
-    return createFile('button', config, {
+    return createComponent('button', config, {
         asPiece: true,
         pieceKind: 'button',
     });
@@ -74,7 +72,7 @@ export function readLook(what, look) {
 /** The button as Discord takes it, for the data and the look given. */
 export function renderButton(loaded, args) {
     const hasData = Object.keys(loaded.data).length > 0;
-    const name = loaded.path.split('/').pop();
+    const { name } = loaded;
     if (args.length > (hasData ? 2 : 1)) {
         fail(`${name} takes ${hasData ? 'its data, then a look' : 'a look'} at most: ${hasData ? `${name}({ ... }, { disabled: true })` : `${name}({ disabled: true })`}.`);
     }
@@ -86,7 +84,7 @@ export function renderButton(loaded, args) {
     const base = {
         type: ComponentType.Button,
         style: BUTTON_STYLES[look.style],
-        custom_id: encodeCustomId(loaded.path, loaded.data, values),
+        custom_id: encodeCustomId(loaded.name, loaded.data, values),
     };
     if (look.emoji !== undefined)
         base.emoji = emojiOf(look.emoji, name);

package/dist/components/component.d.ts

@@ -12,7 +12,7 @@ import type { Translator } from '../messages/messages.js';
  * component carries.
  */
 export interface TextContext<Data extends DataShape = DataShape> {
-    /** The texts of `src/messages/`, in the language of who will read the message. */
+    /** The texts of the language files, in the language of who will read the message. */
     t: Translator;
     /** What the component carries, as declared in `data`. */
     data: [DataShape] extends [Data] ? Record<string, string | number | boolean> : DataValuesOf<Data>;

package/dist/components/component.js

@@ -1,4 +1,4 @@
-// What every interactive component of `src/components/` shares: where it
+// What every interactive component (button, menu, form) shares: where it
 // works, who may use it, what it carries, and what its `run` receives
 // about the place it was used in.
 /** Whether a text is computed when the message is sent. */

package/dist/components/custom-id.d.ts

@@ -53,14 +53,14 @@ export declare const needsNoData: (shape: DataShape) => boolean;
 /** Checks the values a file gives to a component against its `data`. */
 export declare function checkData(what: string, shape: DataShape, values: unknown): Record<string, string | number | boolean>;
 /**
- * The `custom_id` of a component: its path, then its values in the order
+ * The `custom_id` of a component: its name, then its values in the order
  * of the declaration. Discord accepts 100 characters: when the data does
  * not fit, the error says by how much.
  */
-export declare function encodeCustomId(path: string, shape: DataShape, values: Record<string, string | number | boolean>): string;
-/** The path and the encoded values of a `custom_id` the framework wrote. */
+export declare function encodeCustomId(name: string, shape: DataShape, values: Record<string, string | number | boolean>): string;
+/** The name and the encoded values of a `custom_id` the framework wrote. */
 export declare function decodeCustomId(id: string): {
-    path: string;
+    name: string;
     parts: string[];
 };
 /**

package/dist/components/custom-id.js

@@ -1,6 +1,6 @@
-// The `custom_id` of a component is never written by users: it is the path
-// of the file of the component (`buttons/ban`), followed by the data the
-// component carries, encoded by the framework. Stateless by design: it
+// The `custom_id` of a component is never written by users: it is the name
+// of the export that declares the component (`ban`), followed by the data
+// the component carries, encoded by the framework. Stateless by design: it
 // survives a restart, and every process of the bot reads it the same way.
 // https://docs.discord.com/developers/components/reference#anatomy-of-a-component-custom-id
 import { Limits } from '../discord/api.js';
@@ -76,24 +76,24 @@ export function checkData(what, shape, values) {
     return result;
 }
 /**
- * The `custom_id` of a component: its path, then its values in the order
+ * The `custom_id` of a component: its name, then its values in the order
  * of the declaration. Discord accepts 100 characters: when the data does
  * not fit, the error says by how much.
  */
-export function encodeCustomId(path, shape, values) {
-    const parts = [path];
-    for (const name of Object.keys(shape))
-        parts.push(escape(String(values[name])));
+export function encodeCustomId(name, shape, values) {
+    const parts = [name];
+    for (const field of Object.keys(shape))
+        parts.push(escape(String(values[field])));
     const id = parts.join(SEPARATOR);
     if (id.length > Limits.CustomId) {
-        throw new RangeError(`The data of ${path} is ${id.length - path.length - 1} characters long once encoded, and Discord leaves ${Limits.CustomId - path.length - 1} for it (its id is ${path}, ${path.length} characters, out of ${Limits.CustomId}). Carry less: an id instead of a name, or a shorter file name.`);
+        throw new RangeError(`The data of ${name} is ${id.length - name.length - 1} characters long once encoded, and Discord leaves ${Limits.CustomId - name.length - 1} for it (its id is ${name}, ${name.length} characters, out of ${Limits.CustomId}). Carry less: an id instead of a name, or a shorter export name.`);
     }
     return id;
 }
-/** The path and the encoded values of a `custom_id` the framework wrote. */
+/** The name and the encoded values of a `custom_id` the framework wrote. */
 export function decodeCustomId(id) {
-    const [path = '', ...parts] = split(id);
-    return { path, parts };
+    const [name = '', ...parts] = split(id);
+    return { name, parts };
 }
 /**
  * The values a `custom_id` carries, typed as the component declares them.

package/dist/components/declaration.d.ts

@@ -0,0 +1,42 @@
+import type { Declaration } from '../loader/loader.js';
+import { type LoadedButton } from './button.js';
+import { isEmbedDeclaration } from './embed.js';
+import { type ComponentKind } from './declared.js';
+import { type LoadedModal } from './modal.js';
+import { type LoadedSelect } from './select.js';
+/** An embed, checked (when it is static). */
+export interface LoadedEmbed {
+    readonly kind: 'embed';
+    /** The name of the export that declares it. */
+    readonly name: string;
+}
+/** A component, checked: what the router works with. */
+export type LoadedComponent = LoadedButton | LoadedSelect | LoadedModal | LoadedEmbed;
+/** What each kind is called in messages. */
+export declare const WHAT: Record<ComponentKind, string>;
+/**
+ * A component (a button, a select menu, a form or an embed), declared
+ * anywhere in `src/` with `button()`, `select()`, `modal()` or `embed()`,
+ * and exported: the name of the export is its id, so a file may declare
+ * several, each under its own export.
+ */
+export declare const componentDeclaration: Declaration<LoadedComponent>;
+/** Two components of the same kind with the same name: the later one is left out. */
+export declare function findDuplicates<T extends {
+    file: string;
+    export: string;
+    component: {
+        kind: ComponentKind;
+        name: string;
+    };
+}>(entries: readonly T[]): {
+    valid: T[];
+    conflicts: {
+        file: string;
+        export: string;
+        message: string;
+    }[];
+};
+/** Whether a declaration is an embed: nothing to route. */
+export declare const isEmbedLoaded: (component: LoadedComponent) => component is LoadedEmbed;
+export { isEmbedDeclaration };