chapterjs 0.1.2 → 0.2.0

package/dist/cli/project.js

@@ -0,0 +1,517 @@
+// What `chapterjs dev` and `chapterjs start` share: the files of a project,
+// loaded and routed, and a bot that runs them. Each command adds what makes
+// it different (reloading for one, every server and several processes for
+// the other).
+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 { MissingForEvent } from '../events/registry.js';
+import { sourcesJoinVoice } from '../voice/usage.js';
+import { writeGenerated } from '../loader/generated.js';
+import { commandDeclaration, scanCommands } from '../commands/declaration.js';
+import { CommandRouter } from '../commands/router.js';
+import { findConflicts } from '../commands/tree.js';
+import { componentDeclaration, findDuplicates, } from '../components/declaration.js';
+import { ComponentRouter } from '../components/router.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 { eventDeclaration } from '../events/declaration.js';
+import { EventRouter, intentsFor, intentsOf, limitsFor, } from '../events/router.js';
+import { GatewayFatalError, SessionLimitError } from '../gateway/errors.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/`): 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, info) {
+    const [files, found, names] = await Promise.all([
+        listPublic(cwd),
+        info ? null : scanLanguages(cwd),
+        info ? null : scanCommands(cwd),
+    ]);
+    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 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) {
+    if ((await stat(join(cwd, 'src')).catch(() => null))?.isDirectory()) {
+        return true;
+    }
+    log.error('There is no src folder here.\nRun this command in the folder of your bot (the one with package.json), or create a project with "pnpm create chapter".');
+    return false;
+}
+/** The intents that only bring what happens in private messages. */
+const PRIVATE_INTENTS = GatewayIntent.DirectMessages |
+    GatewayIntent.DirectMessageReactions |
+    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 = (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;
+        const what = missing?.what === 'user'
+            ? 'the user who did it'
+            : 'the channel it happened in';
+        log.warn(`A ${event} event was not given to your files: Discord did not let the bot read ${what} (${messageOf(missing ? missing.cause : error)}).`);
+    });
+    const reporter = {
+        onError: (file, error) => report({ file, error }),
+        onWarning: (file, message) => log.warn(`${file} ${message}`),
+        ...(options.deferAfter === undefined
+            ? {}
+            : { deferAfter: options.deferAfter }),
+    };
+    const commandRouter = new CommandRouter(reporter);
+    const componentRouter = new ComponentRouter(reporter);
+    const scheduler = new TimerScheduler(reporter);
+    let events = new Map();
+    let commands = new Map();
+    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 that loaded. */
+    let languages = new Map();
+    let languageDefaults = [];
+    /** The bot running the files now, to give it what a reload changes. */
+    let running = null;
+    /** The presence each bot was given last, to send only what changed. */
+    const given = new WeakMap();
+    let lost = false;
+    const count = (size, one, many) => `${size} ${size === 1 ? one : many}`;
+    return {
+        get events() {
+            return events;
+        },
+        get commands() {
+            return commands;
+        },
+        get components() {
+            return components;
+        },
+        get tasks() {
+            return tasks;
+        },
+        get presence() {
+            return presence;
+        },
+        get messages() {
+            return messages;
+        },
+        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);
+            }
+            // 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 { 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 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. A second one is left out.
+            const [first, ...extra] = presenceItems.loaded;
+            if (first)
+                presence = first.value;
+            else if (presenceItems.failed.length === 0 &&
+                ![...broken].some(file => presenceFiles.has(file))) {
+                presence = null;
+            }
+            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(({ 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 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 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 = {
+                    messages: again.messages,
+                    failed: [
+                        ...assembled.failed,
+                        ...again.failed.filter(({ file }) => !assembled.failed.some(one => one.file === file)),
+                    ],
+                };
+            }
+            messages = assembled.messages;
+            if (running)
+                running.ctx.messages = messages;
+            // A command has its texts in its file, or in the language files: the
+            // languages give them to the ones without, and a command that can't
+            // be described is left out.
+            const badTexts = [...assembled.failed];
+            if (messages) {
+                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${names.size > 0 ? ` (its commands are: ${[...names].join(', ')})` : ''}. The key is the name of the command, like 'ping' or 'mod ban'.`),
+                    });
+                }
+            }
+            for (const [key, entry] of commands) {
+                const { command, failed } = translateCommand(siteName(entry), entry.command, messages);
+                badTexts.push(...failed);
+                if (command)
+                    commands.set(key, { ...entry, command });
+                else
+                    commands.delete(key);
+            }
+            commandRouter.set(commands.values());
+            return [
+                ...sources.failed,
+                ...eventItems.failed,
+                ...commandItems.failed,
+                ...componentItems.failed,
+                ...taskItems.failed,
+                ...presenceItems.failed,
+                ...languageItems.failed,
+                ...badTexts,
+                ...twice,
+                ...[...conflicts, ...unique.conflicts, ...sameTask.conflicts].map(({ file, export: exported, message }) => ({
+                    file,
+                    export: exported,
+                    error: new TypeError(message),
+                })),
+            ];
+        },
+        summary() {
+            if (events.size === 0 &&
+                commands.size === 0 &&
+                components.size === 0 &&
+                tasks.size === 0 &&
+                presence === null &&
+                messages === null) {
+                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
+                    ? [count(commands.size, 'command', 'commands')]
+                    : []),
+                ...(events.size > 0 ? [count(events.size, 'event', 'events')] : []),
+                ...(components.size > 0
+                    ? [count(components.size, 'component', 'components')]
+                    : []),
+                ...(tasks.size > 0 ? [count(tasks.size, 'task', 'tasks')] : []),
+                ...(presence ? ['a presence'] : []),
+                ...(messages
+                    ? [
+                        `messages in ${count(messages.locales.size, 'language', 'languages')}`,
+                    ]
+                    : []),
+            ].join(', ')} loaded`;
+        },
+        isEmpty: () => events.size === 0 &&
+            commands.size === 0 &&
+            components.size === 0 &&
+            tasks.size === 0 &&
+            presence === null &&
+            messages === null,
+        filesNeeding: intent => [...events.values()]
+            .filter(({ event }) => (intentsOf(event) & GatewayIntent[intent]) !== 0)
+            .map(({ file }) => file),
+        intents: (privateEvents = true) => neededIntents() & (privateEvents ? ~0 : ~PRIVATE_INTENTS),
+        async connect(connection) {
+            const created = createBot({
+                token: connection.token,
+                version: options.version,
+                intents: neededIntents() &
+                    (connection.privateEvents === false ? ~PRIVATE_INTENTS : ~0),
+                guildFilter: connection.guildFilter,
+                privateEvents: connection.privateEvents,
+                presence: presence?.raw,
+                shards: connection.shards,
+                identifyGate: connection.identifyGate,
+                ...(connection.identifyInterval === undefined
+                    ? {}
+                    : { gateway: { identifyInterval: connection.identifyInterval } }),
+                // Only what the files of the project use is remembered.
+                cache: { limits: limitsFor(events.values()) },
+                // A local fake of Discord (tests) serves voice without TLS too.
+                voice: { secure: !connection.apiUrl?.startsWith('http://') },
+                rest: {
+                    ...(connection.apiUrl ? { baseUrl: connection.apiUrl } : {}),
+                    ...(connection.globalLimit === undefined
+                        ? {}
+                        : { globalLimit: connection.globalLimit }),
+                },
+                beforeDispatch: (event, data) => router.before(created.ctx, event, data),
+                onDispatch(event, data, info) {
+                    router.dispatch(created.ctx, event, data, {
+                        joined: info.joined,
+                        before: info.before,
+                    });
+                    if (event === 'INTERACTION_CREATE') {
+                        const interaction = data;
+                        commandRouter.dispatch(created.ctx, interaction);
+                        componentRouter.dispatch(created.ctx, interaction);
+                    }
+                },
+                onEvent(event) {
+                    if (event.type === 'disconnected' && !lost) {
+                        lost = true;
+                        log.warn('Connection to Discord lost, reconnecting...');
+                    }
+                    else if (event.type === 'ready' && lost) {
+                        lost = false;
+                        log.reload('Reconnected to Discord');
+                    }
+                    else if (event.type === 'fatal') {
+                        log.error(event.error.message);
+                        connection.onFatal(created);
+                    }
+                    else if (event.type === 'stateError') {
+                        log.warn(`An event of Discord (${event.event}) could not be read: ${messageOf(event.error)}`);
+                    }
+                    else if (event.type === 'voiceWarning') {
+                        log.warn(`Voice: ${event.message}`);
+                    }
+                },
+            });
+            given.set(created, presence?.key ?? '');
+            created.ctx.messages = messages;
+            running = created;
+            await created.connect();
+            return created;
+        },
+        applyPresence(bot) {
+            const key = presence?.key ?? '';
+            if (given.get(bot) === key)
+                return false;
+            given.set(bot, key);
+            bot.setPresence(presence?.raw ?? DEFAULT_PRESENCE);
+            return true;
+        },
+        ready(bot) {
+            const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+            router.emit('ready', {
+                user,
+                guilds: bot.ctx.cache.guilds,
+                ...translation(bot.ctx, null),
+            });
+        },
+        startTasks(current) {
+            scheduler.start(() => {
+                const bot = current();
+                if (!bot?.ctx.self)
+                    return null;
+                const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+                return user
+                    ? {
+                        user,
+                        guilds: bot.ctx.cache.guilds,
+                        ...translation(bot.ctx, null),
+                    }
+                    : null;
+            });
+        },
+        stopTasks: () => scheduler.stop(),
+        // The bot looks after its own memory: it remembers less before memory
+        // is full, and only speaks up when it can't give up anything more.
+        watchMemory: current => watchMemory({
+            cache: () => current()?.ctx.cache,
+            onTightened: ({ members, forgotten }, { used, limit }) => log.info(`Memory was getting full (${megabytes(used)} of ${megabytes(limit)}): the bot now remembers ${members} members per server at most, and forgot ${forgotten} members and users it had not seen for the longest. Nothing changes for your code.`),
+            onRestored: ({ members }) => log.info(`Memory is fine again: the bot remembers up to ${members} members per server again.`),
+            onFull: ({ used, limit }, freed) => log.warn(`The bot uses ${megabytes(used)} of the ${megabytes(limit)} of memory it can use, and already remembers as little as it can: ${current()?.ctx.cache.guilds.size ?? 0} servers and ${current()?.ctx.cache.channels.size ?? 0} channels, which it needs. Remembering less freed ${megabytes(freed)}. If your own code keeps things that only grow (a list, a Map), that is what fills it: look there first. Otherwise give the bot more memory: set NODE_OPTIONS=--max-old-space-size=4096 (in MB) on a machine that has that much.`),
+        }),
+    };
+}
+/** Says what went wrong in words the developer can act on. */
+export function explain(error, log) {
+    if (error instanceof PreflightFailure)
+        return;
+    if (error instanceof InvalidTokenError ||
+        error instanceof GatewayFatalError ||
+        error instanceof SessionLimitError ||
+        error instanceof DiscordUnavailableError) {
+        log.error(error.message);
+    }
+    else if (error instanceof DiscordApiError) {
+        log.error(`Discord refused a request the framework needs to start: ${error.message}`);
+    }
+    else {
+        log.error(`Something unexpected happened: ${messageOf(error)}\nThis is probably a bug in ChapterJS: please report it at https://github.com/chapterjs/chapterjs/issues`);
+    }
+}

package/dist/cli/start.d.ts

@@ -0,0 +1,25 @@
+import { type Assignment } from './cluster.js';
+import type { Log } from './log.js';
+export interface StartOptions {
+    /** The folder of the project. */
+    cwd: string;
+    env: Record<string, string | undefined>;
+    /** The version of the framework. */
+    version: string;
+    log: Log;
+    /** Aborted when the bot is asked to stop (Ctrl+C, the host). */
+    signal: AbortSignal;
+    /** Shows a line printed by another process of the bot. */
+    write: (line: string) => void;
+    /** How many processes to use, when the developer says so. */
+    processes?: number | undefined;
+    /** The share of this process, when another one started it. */
+    assignment?: Assignment | null;
+    /** How the other processes are started: this command again. */
+    script: string;
+    args: readonly string[];
+    /** Only tests change this. */
+    deferAfter?: number;
+}
+/** Runs until stopped. Resolves with the exit code of the process. */
+export declare function start(options: StartOptions): Promise<number>;