chapterjs 0.1.4 → 0.2.0

package/dist/cli/project.js

@@ -6,64 +6,66 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { setPublicDir } from '../assets/asset.js';
 import { listPublic, publicDeclarations } from '../assets/public.js';
-import { eventTypedFolders } from '../events/types.js';
 import { MissingForEvent } from '../events/registry.js';
 import { sourcesJoinVoice } from '../voice/usage.js';
 import { writeGenerated } from '../loader/generated.js';
-import { commandsConvention } from '../commands/convention.js';
+import { commandDeclaration, scanCommands } from '../commands/declaration.js';
 import { CommandRouter } from '../commands/router.js';
 import { findConflicts } from '../commands/tree.js';
-import { componentsConvention, findDuplicates, } from '../components/convention.js';
+import { componentDeclaration, findDuplicates, } from '../components/declaration.js';
 import { ComponentRouter } from '../components/router.js';
-import { tasksConvention } from '../tasks/convention.js';
-import { DEFAULT_PRESENCE, presenceConvention, } from '../presence/convention.js';
-import { assembleMessages, commandsDeclarations, languagesConvention, languageTypedFolders, messagesDeclarations, } from '../messages/convention.js';
+import { taskDeclaration } from '../tasks/declaration.js';
+import { DEFAULT_PRESENCE, presenceDeclaration, } from '../presence/declaration.js';
+import { assembleMessages, commandsDeclarations, languageDeclaration, languageDefaultsDeclaration, messagesDeclarations, scanLanguages, } from '../messages/declaration.js';
 import { translation } from '../messages/translate.js';
 import { translateCommand, unknownCommands } from '../messages/commands.js';
 import { TimerScheduler, } from '../tasks/scheduler.js';
 import { createBot } from '../core/bot.js';
 import { watchMemory } from '../core/memory.js';
 import { GatewayIntent } from '../discord/intents.js';
-import { eventsConvention } from '../events/convention.js';
+import { eventDeclaration } from '../events/declaration.js';
 import { EventRouter, intentsFor, intentsOf, limitsFor, } from '../events/router.js';
 import { GatewayFatalError, SessionLimitError } from '../gateway/errors.js';
-import { listFolder, loadBuilt, loadFolder, } from '../loader/loader.js';
+import { loadSources, readDeclarations, siteName, } from '../loader/loader.js';
 import { locate, messageOf } from '../loader/locate.js';
 import { DiscordApiError, DiscordUnavailableError, InvalidTokenError, } from '../rest/errors.js';
 import { PreflightFailure } from './preflight.js';
 /**
- * Writes the types of a project (`.chapterjs/`): one project per typed
- * folder (every event, every language file), and what every file gets,
- * like the files of `public/`. With the commands and the languages as
- * they loaded, a language file only offers the ones without `description`
- * in their file, `t` is typed from the default language and `default:
- * true` is refused in every file when another one says it (`defaults`,
- * the files that do); without them (`sync`, which runs nothing),
- * every command is offered and the first language file types `t`.
+ * Writes the types of a project (`.chapterjs/`): what the project adds to
+ * 'chapterjs', like the files of `public/`, its languages and its
+ * commands. With the project as it loaded (`info`), a language only
+ * offers the commands without `description`, `t` is typed from the
+ * default language and `default: true` is refused in every language that
+ * says it when another one does; without it (`sync`, which runs nothing),
+ * the commands and the languages are found by reading the files, every
+ * command is offered, and the first language or the one that says
+ * `default: true` types `t`.
  * @returns how many files were written
  */
-export async function writeTypes(cwd, commands, messages, defaults = []) {
-    const [files, languageFiles, commandFiles] = await Promise.all([
+export async function writeTypes(cwd, info) {
+    const [files, found, names] = await Promise.all([
         listPublic(cwd),
-        listFolder(cwd, languagesConvention),
-        listFolder(cwd, commandsConvention),
+        info ? null : scanLanguages(cwd),
+        info ? null : scanCommands(cwd),
     ]);
-    return writeGenerated(cwd, [...eventTypedFolders(), ...languageTypedFolders(languageFiles, defaults)], publicDeclarations(files) +
-        messagesDeclarations(languageFiles, messages ? messages.files.get(messages.default) : undefined), 
-    // Only language files use it, and they are in the main project.
-    commandsDeclarations(commandFiles.map(({ file }) => ({
-        file,
-        described: commands?.get(file)?.command.described ?? false,
-    }))));
+    const languages = info ? info.languages : found.languages;
+    const defaultLocale = info ? info.defaultLocale : found.defaultLocale;
+    const commands = info
+        ? info.commands
+        : names.map(name => ({ name, described: false }));
+    return writeGenerated(cwd, publicDeclarations(files) +
+        messagesDeclarations(languages, defaultLocale) +
+        languageDefaultsDeclaration(info?.languageDefaults ?? []) +
+        commandsDeclarations(commands));
 }
-/** The conventional folders of a project: one per feature. */
-export const CONVENTIONS = [
-    eventsConvention,
-    commandsConvention,
-    componentsConvention,
-    tasksConvention,
-    presenceConvention,
-    languagesConvention,
+/** The kinds of declarations a project is made of: one per feature. */
+export const DECLARATIONS = [
+    eventDeclaration,
+    commandDeclaration,
+    componentDeclaration,
+    taskDeclaration,
+    presenceDeclaration,
+    languageDeclaration,
 ];
 /** Whether the folder is a project: it has a `src` folder. */
 export async function hasSources(cwd, log) {
@@ -79,13 +81,45 @@ const PRIVATE_INTENTS = GatewayIntent.DirectMessages |
     GatewayIntent.DirectMessageTyping |
     GatewayIntent.DirectMessagePolls;
 const megabytes = (bytes) => `${Math.round(bytes / 1024 / 1024)} MB`;
+/** What tells one declaration from another: its file and its export. */
+const keyOf = (site) => `${site.file}#${site.export}`;
+/**
+ * Two declarations with the same name, where the name is the export's
+ * (a task): the later one is left out, with a message saying so.
+ */
+function sameNames(entries, nameOf, what) {
+    const seen = new Map();
+    const conflicts = [];
+    const valid = [...entries]
+        .sort((a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1)
+        .filter(entry => {
+        const first = seen.get(nameOf(entry));
+        if (!first) {
+            seen.set(nameOf(entry), entry);
+            return true;
+        }
+        conflicts.push({
+            file: entry.file,
+            export: entry.export,
+            message: `There is already a ${what} named ${nameOf(entry)}, in ${first.file}: the name of the export is the name of the ${what}, so rename one of them.`,
+        });
+        return false;
+    });
+    return { valid, conflicts };
+}
 export function createProject(options) {
     const { cwd, log } = options;
     // Where `asset()` reads the files of the project from.
     setPublicDir(cwd);
-    const report = ({ file, error }) => {
-        const where = locate(error, cwd);
-        log.error(`${where ? `${where.file}:${where.line}` : file} ${messageOf(error)}`);
+    const report = (failure) => {
+        const where = locate(failure.error, cwd);
+        log.error(`${where ? `${where.file}:${where.line}` : siteName(failure)} ${messageOf(failure.error)}`);
     };
     const router = new EventRouter((file, error) => report({ file, error }), (event, error) => {
         const missing = error instanceof MissingForEvent ? error : null;
@@ -109,11 +143,13 @@ export function createProject(options) {
     let components = new Map();
     let tasks = new Map();
     let presence = null;
+    /** The files the presence was declared in, to keep it when they break. */
+    let presenceFiles = new Set();
     // Joining voice needs the bot's own voice state, sent with an intent.
     let voice = options.joinsVoice ?? false;
     const neededIntents = () => intentsFor(events.values()) | (voice ? GatewayIntent.GuildVoiceStates : 0);
     let messages = null;
-    /** The last version of each language file that loaded. */
+    /** The last version of each language that loaded. */
     let languages = new Map();
     let languageDefaults = [];
     /** The bot running the files now, to give it what a reload changes. */
@@ -141,107 +177,134 @@ export function createProject(options) {
         get messages() {
             return messages;
         },
-        get languageDefaults() {
-            return languageDefaults;
-        },
+        typesInfo: () => ({
+            languages: [...languages.values()].map(entry => ({
+                file: entry.file,
+                export: entry.export,
+                name: entry.name,
+                locale: entry.language.locale,
+            })),
+            ...(messages ? { defaultLocale: messages.default } : {}),
+            languageDefaults,
+            commands: [...commands.values()].map(({ command }) => ({
+                name: command.path.join(' '),
+                described: command.described,
+            })),
+        }),
         report,
         async load() {
             const { built } = options;
             if (options.joinsVoice === undefined) {
                 voice = await sourcesJoinVoice(cwd);
             }
-            const [eventFiles, commandFiles, componentFiles, taskFiles, presenceFiles, messageFiles,] = await Promise.all(built
-                ? [
-                    loadBuilt(eventsConvention, built),
-                    loadBuilt(commandsConvention, built),
-                    loadBuilt(componentsConvention, built),
-                    loadBuilt(tasksConvention, built),
-                    loadBuilt(presenceConvention, built),
-                    loadBuilt(languagesConvention, built),
-                ]
-                : [
-                    loadFolder(cwd, eventsConvention),
-                    loadFolder(cwd, commandsConvention),
-                    loadFolder(cwd, componentsConvention),
-                    loadFolder(cwd, tasksConvention),
-                    loadFolder(cwd, presenceConvention),
-                    loadFolder(cwd, languagesConvention),
-                ]);
-            const nextEvents = new Map();
-            for (const { file, value } of eventFiles.loaded) {
-                nextEvents.set(file, { file, event: value });
-            }
-            for (const { file } of eventFiles.failed) {
-                const previous = events.get(file);
-                if (previous)
-                    nextEvents.set(file, previous);
-            }
-            events = nextEvents;
+            // Every file of src/ runs (or ran, in a build); what each exports is
+            // then read, kind by kind.
+            const sources = built ? { modules: built, failed: [] } : await loadSources(cwd);
+            const read = (declaration) => readDeclarations(sources.modules, declaration);
+            const [eventItems, commandItems, componentItems, taskItems, presenceItems, languageItems,] = [
+                read(eventDeclaration),
+                read(commandDeclaration),
+                read(componentDeclaration),
+                read(taskDeclaration),
+                read(presenceDeclaration),
+                read(languageDeclaration),
+            ];
+            const broken = new Set(sources.failed.map(({ file }) => file));
+            /**
+             * The next version of a kind: what loaded now, plus the last good
+             * version of what failed (an export that can't be read, or a file
+             * that can't run at all).
+             */
+            const next = (previous, items, make) => {
+                const result = new Map();
+                for (const item of items.loaded)
+                    result.set(keyOf(item), make(item));
+                const failedKeys = new Set(items.failed.map(({ file, export: exported }) => keyOf({ file, export: exported ?? 'default' })));
+                for (const [key, entry] of previous) {
+                    if (failedKeys.has(key) || broken.has(entry.file)) {
+                        result.set(key, entry);
+                    }
+                }
+                return result;
+            };
+            events = next(events, eventItems, item => ({
+                file: item.file,
+                export: item.export,
+                event: item.value,
+            }));
             router.set(events.values());
-            const entries = commandFiles.loaded.map(({ file, value }) => ({ file, command: value }));
-            for (const { file } of commandFiles.failed) {
-                const previous = commands.get(file);
-                if (previous)
-                    entries.push(previous);
-            }
-            const { valid, conflicts } = findConflicts(entries);
-            commands = new Map(valid.map(entry => [entry.file, entry]));
-            const pieces = componentFiles.loaded.map(({ file, value }) => ({ file, component: value }));
-            for (const { file } of componentFiles.failed) {
-                const previous = components.get(file);
-                if (previous)
-                    pieces.push(previous);
-            }
-            const unique = findDuplicates(pieces);
-            components = new Map(unique.valid.map(entry => [entry.file, entry]));
+            const { valid, conflicts } = findConflicts([
+                ...next(commands, commandItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    command: item.value,
+                })).values(),
+            ]);
+            commands = new Map(valid.map(entry => [keyOf(entry), entry]));
+            const unique = findDuplicates([
+                ...next(components, componentItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    component: item.value,
+                })).values(),
+            ]);
+            components = new Map(unique.valid.map(entry => [keyOf(entry), entry]));
             componentRouter.set(components.values());
-            const nextTasks = new Map();
-            for (const { file, value } of taskFiles.loaded) {
-                nextTasks.set(file, { file, task: value });
-            }
-            for (const { file } of taskFiles.failed) {
-                const previous = tasks.get(file);
-                if (previous)
-                    nextTasks.set(file, previous);
-            }
-            tasks = nextTasks;
+            const sameTask = sameNames([
+                ...next(tasks, taskItems, item => ({
+                    file: item.file,
+                    export: item.export,
+                    task: item.value,
+                })).values(),
+            ], entry => entry.task.name, 'task');
+            tasks = new Map(sameTask.valid.map(entry => [keyOf(entry), entry]));
             scheduler.set(tasks.values());
-            // One presence file. A second one (another extension) is left out.
-            const [first, ...extra] = presenceFiles.loaded;
+            // One presence. A second one is left out.
+            const [first, ...extra] = presenceItems.loaded;
             if (first)
                 presence = first.value;
-            else if (presenceFiles.failed.length === 0)
+            else if (presenceItems.failed.length === 0 &&
+                ![...broken].some(file => presenceFiles.has(file))) {
                 presence = null;
-            const twice = extra.map(({ file }) => ({
-                file,
-                error: new TypeError(`There are two presence files: ${first.file} is used, keep only one.`),
-            }));
-            const nextLanguages = new Map();
-            for (const { file, value } of messageFiles.loaded) {
-                nextLanguages.set(file, { file, language: value });
-            }
-            for (const { file } of messageFiles.failed) {
-                const previous = languages.get(file);
-                if (previous)
-                    nextLanguages.set(file, previous);
             }
-            // What the files say now, before a file is put back to its last good
-            // version: two files saying default: true are both underlined.
+            presenceFiles = new Set(presenceItems.loaded.map(({ file }) => file));
+            const twice = extra.map(item => ({
+                file: item.file,
+                export: item.export,
+                error: new TypeError(`There are two presences: the one of ${siteName(first)} is used, keep only one.`),
+            }));
+            const nextLanguages = next(languages, languageItems, item => ({
+                file: item.file,
+                export: item.export,
+                name: item.name,
+                language: item.value,
+            }));
+            // What the files say now, before a declaration is put back to its
+            // last good version: two languages saying default: true are both
+            // underlined.
             languageDefaults = [...nextLanguages.values()]
                 .filter(({ language }) => language.isDefault)
-                .map(({ file }) => file);
+                .map(({ language }) => language.locale);
             const previousLanguages = languages;
             languages = nextLanguages;
             let assembled = assembleMessages([...languages.values()]);
             // A language that no longer matches the others keeps its last version
-            // that did, like a file that no longer loads.
-            const restored = assembled.failed.filter(({ file }) => {
-                const previous = previousLanguages.get(file);
-                return previous !== undefined && previous !== languages.get(file);
+            // that did, like a declaration that no longer loads.
+            const restored = assembled.failed.filter(failure => {
+                const key = keyOf({
+                    file: failure.file,
+                    export: failure.export ?? 'default',
+                });
+                const previous = previousLanguages.get(key);
+                return previous !== undefined && previous !== languages.get(key);
             });
             if (restored.length > 0) {
-                for (const { file } of restored) {
-                    languages.set(file, previousLanguages.get(file));
+                for (const failure of restored) {
+                    const key = keyOf({
+                        file: failure.file,
+                        export: failure.export ?? 'default',
+                    });
+                    languages.set(key, previousLanguages.get(key));
                 }
                 const again = assembleMessages([...languages.values()]);
                 assembled = {
@@ -260,34 +323,36 @@ export function createProject(options) {
             // be described is left out.
             const badTexts = [...assembled.failed];
             if (messages) {
-                const paths = new Set([...commands.values()].map(entry => entry.command.path.join('/')));
-                for (const { file, path } of unknownCommands(messages, paths)) {
+                const names = new Set([...commands.values()].map(entry => entry.command.path.join(' ')));
+                for (const { file, path } of unknownCommands(messages, names)) {
                     badTexts.push({
                         file,
-                        error: new TypeError(`"commands" translates "${path}", which is not a command of this project${paths.size > 0 ? ` (its commands are: ${[...paths].join(', ')})` : ''}. The key is the path of the command file, like 'ping' or 'mod/ban'.`),
+                        error: new TypeError(`"commands" translates "${path}", which is not a command of this project${names.size > 0 ? ` (its commands are: ${[...names].join(', ')})` : ''}. The key is the name of the command, like 'ping' or 'mod ban'.`),
                     });
                 }
             }
-            for (const [file, entry] of commands) {
-                const { command, failed } = translateCommand(file, entry.command, messages);
+            for (const [key, entry] of commands) {
+                const { command, failed } = translateCommand(siteName(entry), entry.command, messages);
                 badTexts.push(...failed);
                 if (command)
-                    commands.set(file, { ...entry, command });
+                    commands.set(key, { ...entry, command });
                 else
-                    commands.delete(file);
+                    commands.delete(key);
             }
             commandRouter.set(commands.values());
             return [
-                ...eventFiles.failed,
-                ...commandFiles.failed,
-                ...componentFiles.failed,
-                ...taskFiles.failed,
-                ...presenceFiles.failed,
-                ...messageFiles.failed,
+                ...sources.failed,
+                ...eventItems.failed,
+                ...commandItems.failed,
+                ...componentItems.failed,
+                ...taskItems.failed,
+                ...presenceItems.failed,
+                ...languageItems.failed,
                 ...badTexts,
                 ...twice,
-                ...[...conflicts, ...unique.conflicts].map(({ file, message }) => ({
+                ...[...conflicts, ...unique.conflicts, ...sameTask.conflicts].map(({ file, export: exported, message }) => ({
                     file,
+                    export: exported,
                     error: new TypeError(message),
                 })),
             ];
@@ -299,7 +364,7 @@ export function createProject(options) {
                 tasks.size === 0 &&
                 presence === null &&
                 messages === null) {
-                return 'Nothing to run yet: add a file in src/commands/ or in a folder like src/events/messageCreate/';
+                return "Nothing to run yet: export a command or an event from a file of src/, like export default command({ name: 'ping', ... })";
             }
             return `${[
                 ...(commands.size > 0

package/dist/commands/command.d.ts

@@ -13,7 +13,7 @@ interface OptionBase {
     /**
      * What the option is for, shown under its name (1-100 characters). Here
      * when the command has its `description` here; otherwise in the default
-     * language file of `src/messages/`.
+     * language file of the project.
      */
     description?: string;
     /** Whether the user must fill it in. By default it is optional. */
@@ -270,13 +270,27 @@ export type CommandContext<Options extends CommandOptions = CommandOptions, Wher
     /** Who used the command. */
     user: User;
 } & TranslationContext & (Where extends 'guild' ? CommandInGuild : Where extends 'dm' ? CommandInDm : CommandInGuild | CommandInPrivate);
-/** What a command file gives to `command()`: what the command is and does. */
+/**
+ * The name of a slash command: lowercase letters, digits, `-` and `_`, 32
+ * characters at most (`'ping'`). A subcommand is written with its parents,
+ * separated by spaces: `'mod ban'` is `/mod ban`, `'mod roles add'` is
+ * `/mod roles add` (Discord allows nothing deeper).
+ * @see https://docs.discord.com/developers/interactions/application-commands#application-command-object-application-command-naming
+ */
+export type CommandName = string;
+/** What a file gives to `command()`: what the command is and does. */
 export interface CommandConfig<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = 'guild'> {
+    /**
+     * What people type after the `/`: `'ping'` is `/ping`. A subcommand is
+     * written with its parents: `'mod ban'` is `/mod ban`, `'mod roles add'`
+     * is `/mod roles add`.
+     */
+    name: CommandName;
     /**
      * What the command does, shown under its name (1-100 characters). Here,
      * with `locales` for its translations; or left out, and every text of
      * the command (description, options, their choices, translations) comes
-     * from the language files of `src/messages/`. One or the other.
+     * from the language files of the project. One or the other.
      */
     description?: string;
     /** What the user can fill in (25 options at most). */
@@ -319,20 +333,20 @@ export interface CommandConfig<Options extends CommandOptions = CommandOptions,
     /** What to do when someone uses the command. */
     run: (context: CommandContext<Options, Where>) => unknown;
 }
-/** What `command()` returns: the default export of a command file. */
-export interface CommandFile<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere> {
+/** What `command()` returns: a declaration the framework finds in the exports of a file. */
+export interface CommandDeclaration<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere> {
     /** What the file gave to `command()`, not checked yet. */
     readonly config: CommandConfig<Options, Where>;
 }
 /**
- * Declares a slash command. Export the result as the default export of a
- * file of `src/commands/`: the path of the file is the name of the command
- * (`src/commands/mod/ban.ts` is `/mod ban`).
+ * Declares a slash command. Export the result from any file of `src/`:
+ * `name` is what people type after the `/` (`'mod ban'` for `/mod ban`).
  *
  * ```ts
  * import { command } from 'chapterjs';
  *
- * export default command({
+ * export const ping = command({
+ *   name: 'ping',
  *   description: 'Replies with Pong!',
  *   async run({ interaction }) {
  *     await interaction.reply('Pong!');
@@ -340,7 +354,7 @@ export interface CommandFile<Options extends CommandOptions = CommandOptions, Wh
  * });
  * ```
  */
-export declare function command<const Options extends CommandOptions = {}, const Where extends CommandWhere = 'guild'>(config: CommandConfig<Options, Where>): CommandFile<Options, Where>;
+export declare function command<const Options extends CommandOptions = {}, const Where extends CommandWhere = 'guild'>(config: CommandConfig<Options, Where>): CommandDeclaration<Options, Where>;
 /** Whether a value was made by `command()`. */
-export declare function isCommandFile(value: unknown): value is CommandFile;
+export declare function isCommandDeclaration(value: unknown): value is CommandDeclaration;
 export {};

package/dist/commands/command.js

@@ -2,14 +2,14 @@
 // make the options a command declares typed in its `run` function.
 const BRAND = Symbol.for('chapterjs.command');
 /**
- * Declares a slash command. Export the result as the default export of a
- * file of `src/commands/`: the path of the file is the name of the command
- * (`src/commands/mod/ban.ts` is `/mod ban`).
+ * Declares a slash command. Export the result from any file of `src/`:
+ * `name` is what people type after the `/` (`'mod ban'` for `/mod ban`).
  *
  * ```ts
  * import { command } from 'chapterjs';
  *
- * export default command({
+ * export const ping = command({
+ *   name: 'ping',
  *   description: 'Replies with Pong!',
  *   async run({ interaction }) {
  *     await interaction.reply('Pong!');
@@ -21,7 +21,7 @@ export function command(config) {
     return Object.freeze({ [BRAND]: true, config });
 }
 /** Whether a value was made by `command()`. */
-export function isCommandFile(value) {
+export function isCommandDeclaration(value) {
     return (typeof value === 'object' &&
         value !== null &&
         value[BRAND] === true);

package/dist/commands/{convention.d.ts → declaration.d.ts}

@@ -1,6 +1,6 @@
 import { Locale } from '../discord/types/common.js';
 import { type CooldownLimits } from '../interactions/cooldown.js';
-import type { Convention } from '../loader/loader.js';
+import { type Declaration } from '../loader/loader.js';
 import { type AutocompleteContext, type CommandContext, type CommandOption, type CommandWhere, type Suggestion } from './command.js';
 /** A name or a description in other languages, as Discord takes them. */
 export type Localizations = Readonly<Partial<Record<Locale, string>>>;
@@ -18,20 +18,20 @@ export type LoadedOption = CommandOption & {
 };
 /** An `autocomplete` function of a file, as the router runs it. */
 export type AutocompleteFunction = (context: AutocompleteContext) => readonly Suggestion[] | Promise<readonly Suggestion[]>;
-/** A command file, checked: what the rest of the feature works with. */
+/** A command, checked: what the rest of the feature works with. */
 export interface LoadedCommand {
     /** The name and description of the command in other languages. */
     readonly names: Localizations;
     readonly descriptions: Localizations;
     /** The translations of the options, by option name. */
     readonly optionLocales: Readonly<Record<string, OptionLocales>>;
-    /** `['mod', 'ban']` for `src/commands/mod/ban.ts`: `/mod ban`. */
+    /** `['mod', 'ban']` for `name: 'mod ban'`: `/mod ban`. */
     readonly path: readonly string[];
     /**
      * Whether the file gives its own texts (`description`, `locales`). When
-     * it does not, the language files of `src/messages/` do: `description`
-     * and the descriptions of the options are empty until `project.ts`
-     * fills them in from the default language.
+     * it does not, the language files do: `description` and the
+     * descriptions of the options are empty until `project.ts` fills them
+     * in from the default language.
      */
     readonly described: boolean;
     readonly description: string;
@@ -56,9 +56,22 @@ export declare function checkLocales(locales: unknown, options: readonly LoadedO
     optionLocales: Record<string, OptionLocales>;
 };
 /**
- * `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 declare const commandsConvention: Convention<LoadedCommand>;
+export declare function readCommandName(name: unknown): string[];
+/**
+ * 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 declare const commandDeclaration: Declaration<LoadedCommand>;
+/**
+ * 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 declare function scanCommands(cwd: string): Promise<string[]>;