chapterjs 0.4.0 → 0.5.0

package/dist/testing/smoke.js

@@ -5,7 +5,7 @@
 // function threw: the content is the scenarios' business.
 import { Permissions } from '../discord/permissions.js';
 import { ChannelType } from '../discord/types/channel.js';
-import { commandName } from '../commands/tree.js';
+import { commandName, describeCommand, } from '../commands/tree.js';
 import { EVENTS } from '../events/registry.js';
 const UNICODE = '🙂 héllo wörld — ça va ?';
 const FILE = {
@@ -152,9 +152,90 @@ function hard(option) {
             ];
     }
 }
+/** The longest message Discord accepts. */
+const MAX_MESSAGE = 2000;
+/**
+ * The checks of a menu command: used on an ordinary message or person, and
+ * on the hard ones (a message at its longest, the bot, the owner, someone
+ * who left...).
+ */
+function menuCheck({ command, file }) {
+    const declaration = { config: { run: command.run } };
+    const subject = describeCommand(command);
+    const dm = command.where === 'dm';
+    const cases = [];
+    const use = (session, on, where = {}) => {
+        const by = userFor(session, command);
+        return Promise.resolve(on(session, by))
+            .then(target => session.use(declaration, { on: target }, {
+            by,
+            ...where,
+        }))
+            .then(() => { });
+    };
+    if (command.type === 'message') {
+        // The message is written where the menu is used.
+        const say = (content, author) => (session, by) => session.say(content, {
+            by: author?.(session) ?? session.someone,
+            ...(dm ? { in: 'dm', by } : {}),
+        });
+        cases.push({ label: 'on a message', run: session => use(session, say('Hello!')) }, {
+            label: 'on a message at its longest, with unicode',
+            run: session => use(session, say(`${UNICODE} ${textOf(MAX_MESSAGE)}`.slice(0, MAX_MESSAGE))),
+        });
+        if (!dm) {
+            cases.push({
+                label: 'on a message of the owner',
+                run: session => use(session, say('Hello!', current => current.owner)),
+            }, {
+                label: 'on a message of someone who left',
+                run: session => use(session, async (current, by) => {
+                    // Someone of its own, who writes and then leaves.
+                    const writer = current.member('gone-writer');
+                    const message = await say('Hello!', () => writer)(current, by);
+                    current.world.members.delete(writer.id);
+                    return message;
+                }),
+            });
+        }
+        if (command.where === 'both') {
+            cases.push({
+                label: 'in a private message',
+                run: session => use(session, (current, by) => current.say('Hello!', { by, in: 'dm' })),
+            });
+        }
+        return { subject, file, cases };
+    }
+    cases.push({
+        label: 'on someone',
+        run: session => use(session, current => current.member('alice')),
+    }, { label: 'on who uses it', run: session => use(session, (_, by) => by) }, { label: 'on the bot', run: session => use(session, current => current.me) });
+    if (!dm) {
+        cases.push({
+            label: 'on the owner',
+            run: session => use(session, current => current.owner),
+        }, {
+            label: 'on someone who left',
+            run: session => use(session, current => {
+                const gone = current.member('gone');
+                current.world.members.delete(gone.id);
+                return gone;
+            }),
+        });
+    }
+    if (command.where === 'both') {
+        cases.push({
+            label: 'in a private message',
+            run: session => use(session, (_, by) => by, { in: 'dm' }),
+        });
+    }
+    return { subject, file, cases };
+}
 /** The checks of the commands. */
 function commandChecks(project) {
     return [...project.commands.values()].map((entry) => {
+        if (entry.command.type !== 'slash')
+            return menuCheck(entry);
         const { command, file } = entry;
         const declaration = { config: { run: command.run } };
         const subject = `command ${commandName(command.path)}`;
@@ -274,6 +355,9 @@ function componentChecks(project) {
         const { component, file } = entry;
         if (component.kind === 'embed')
             continue;
+        // Only waited for (`message.waitForClick()`): nothing of its own runs.
+        if (component.kind !== 'modal' && !component.run)
+            continue;
         const { name, data } = component;
         const target = (values) => ({
             customId: [
@@ -644,6 +728,32 @@ function taskChecks(project) {
         ],
     }));
 }
+/**
+ * The check of the presence, when it has functions: each runs once, as
+ * the rotation would run it.
+ */
+function presenceChecks(project) {
+    const file = project.presenceFile;
+    const presence = project.presence;
+    if (!file || !presence)
+        return [];
+    const hasFunctions = typeof presence.activities === 'function' ||
+        presence.activities.some(one => typeof one.name === 'function');
+    if (!hasFunctions)
+        return [];
+    return [
+        {
+            subject: 'the presence',
+            file,
+            cases: [
+                {
+                    label: 'once',
+                    run: session => session.project.runPresence(session.bot),
+                },
+            ],
+        },
+    ];
+}
 /** Every check of the project, in the order of the report. */
 export function smokeChecks(project) {
     const events = eventChecks(project);
@@ -653,6 +763,7 @@ export function smokeChecks(project) {
             ...componentChecks(project),
             ...events.checks,
             ...taskChecks(project),
+            ...presenceChecks(project),
         ],
         notSimulated: events.notSimulated,
     };

package/dist/testing/world.js

@@ -59,6 +59,11 @@ const unknown = (what, code) => ({
     status: 404,
     body: { message: `Unknown ${what}`, code },
 });
+/** What Discord answers an action the bot is not high enough for. */
+const MISSING_PERMISSIONS = {
+    status: 403,
+    body: { message: 'Missing Permissions', code: 50013 },
+};
 /** The regular expression matching a documented path, placeholders filled. */
 function patternOf(path) {
     const source = path
@@ -238,15 +243,49 @@ export class World {
                 tertiary_color: null,
             },
             hoist: false,
-            position: options.position ?? this.roles.size,
+            position: options.position ?? 1,
             permissions: (options.permissions ?? 0n).toString(),
             managed: false,
             mentionable: false,
             flags: 0,
         };
+        // A new role goes at the bottom, just above @everyone, as Discord
+        // places it: the ones from there up move up one.
+        for (const other of this.roles.values()) {
+            if (other.position >= role.position && other.id !== this.guildId)
+                other.position += 1;
+        }
         this.roles.set(role.id, role);
         return role;
     }
+    /**
+     * Whether the bot may act on someone: kick, ban, change their nickname,
+     * roles or timeout. Never on the owner of the server, and only on members
+     * whose highest role is lower than the bot's.
+     * @see https://docs.discord.com/developers/topics/permissions#permission-hierarchy
+     */
+    #outranks(userId) {
+        if (userId === this.ownerId)
+            return false;
+        if (userId === this.botId)
+            return true;
+        const member = this.members.get(userId);
+        return !member || this.#highest(this.botId) > this.#highest(userId);
+    }
+    /**
+     * Whether the bot may give or take this role from someone: a role lower
+     * than its highest, on someone it outranks (itself included).
+     */
+    #givable(userId, roleId) {
+        const role = this.roles.get(roleId);
+        return (this.#outranks(userId) &&
+            (role?.position ?? 0) < this.#highest(this.botId));
+    }
+    /** The position of someone's highest role (0: @everyone only). */
+    #highest(userId) {
+        const member = this.members.get(userId);
+        return Math.max(0, ...(member?.roles ?? []).map(id => this.roles.get(id)?.position ?? 0));
+    }
     addChannel(name, options = {}) {
         const channel = {
             id: this.snowflake(),
@@ -750,6 +789,8 @@ export class World {
                 return found.refused;
             const { member } = found;
             const changes = body(request);
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             if ('nick' in changes)
                 member.nick = changes.nick ?? null;
             if (Array.isArray(changes.roles))
@@ -783,6 +824,8 @@ export class World {
                 return found.refused;
             if (!this.roles.has(roleId))
                 return unknown('Role', 10011);
+            if (!this.#givable(userId, roleId))
+                return MISSING_PERMISSIONS;
             if (!found.member.roles.includes(roleId))
                 found.member.roles.push(roleId);
             this.memberUpdated(found.member);
@@ -794,6 +837,8 @@ export class World {
                 return found.refused;
             if (!this.roles.has(roleId))
                 return unknown('Role', 10011);
+            if (!this.#givable(userId, roleId))
+                return MISSING_PERMISSIONS;
             found.member.roles = found.member.roles.filter(id => id !== roleId);
             this.memberUpdated(found.member);
             return {};
@@ -802,6 +847,8 @@ export class World {
             const found = memberOr404(guildId, userId);
             if ('refused' in found)
                 return found.refused;
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             this.removeMember(userId);
             return {};
         });
@@ -828,6 +875,8 @@ export class World {
             const user = this.users.get(userId);
             if (!user)
                 return unknown('User', 10013);
+            if (!this.#outranks(userId))
+                return MISSING_PERMISSIONS;
             const reason = request.headers['x-audit-log-reason'];
             this.bans.set(userId, {
                 user,
@@ -863,7 +912,7 @@ export class World {
             const failed = [];
             for (const id of ids) {
                 const user = this.users.get(id);
-                if (!user || this.bans.has(id)) {
+                if (!user || this.bans.has(id) || !this.#outranks(id)) {
                     failed.push(id);
                     continue;
                 }

package/dist/util/call-site.d.ts

@@ -0,0 +1,4 @@
+/** The stack of the moment a call is made. */
+export declare function callSite(): Error;
+/** Adds where the call was made to an error that came later. */
+export declare function fromSite(error: unknown, site: Error): unknown;

package/dist/util/call-site.js

@@ -0,0 +1,22 @@
+// Where a call of the files was made, for an error that comes later. An
+// error made after an `await` only has the lines of the files in its stack
+// when they awaited the call: `member.ban()` written without `await`, and
+// refused by Discord, would point nowhere in the project. `callSite()` is
+// taken when the call is made, before anything is awaited, and
+// `fromSite()` adds its lines to the error, so `locate()` finds the line
+// that asked whether the call was awaited or not.
+/** The stack of the moment a call is made. */
+export function callSite() {
+    return new Error('Called here');
+}
+/** Adds where the call was made to an error that came later. */
+export function fromSite(error, site) {
+    if (!(error instanceof Error) || typeof error.stack !== 'string') {
+        return error;
+    }
+    const frames = (site.stack ?? '').split('\n').slice(1).join('\n');
+    if (frames && !error.stack.includes(frames)) {
+        error.stack = `${error.stack}\n${frames}`;
+    }
+    return error;
+}

package/dist/voice/connection.d.ts

@@ -69,6 +69,8 @@ export declare class VoiceManager {
         secure?: boolean;
         joinTimeout?: number;
         endedGrace?: number;
+        /** Where nothing can play: what `join()` says at once. */
+        unavailable?: string;
     });
     /** The connection of the bot in a server, if it is in voice there. */
     connectionOf(guildId: Snowflake): VoiceConnection | null;

package/dist/voice/connection.js

@@ -218,6 +218,8 @@ export class VoiceManager {
     #secure;
     #joinTimeout;
     #endedGrace;
+    /** Why voice can't be joined here (`chapterjs test`), or `null`. */
+    #unavailable;
     constructor(ctx, gateway, options) {
         this.#ctx = ctx;
         this.#gateway = gateway;
@@ -225,6 +227,7 @@ export class VoiceManager {
         this.#secure = options.secure ?? true;
         this.#joinTimeout = options.joinTimeout ?? JOIN_TIMEOUT;
         this.#endedGrace = options.endedGrace ?? 3000;
+        this.#unavailable = options.unavailable ?? null;
     }
     /** The connection of the bot in a server, if it is in voice there. */
     connectionOf(guildId) {
@@ -249,6 +252,8 @@ export class VoiceManager {
      * same server. Resolves once audio can be sent.
      */
     async join(channel, options = {}) {
+        if (this.#unavailable !== null)
+            throw new Error(this.#unavailable);
         const guild = channel.guild;
         const me = guild.me;
         const permissions = me.permissionsIn(channel);
@@ -273,7 +278,16 @@ export class VoiceManager {
             ? existing
             : new VoiceConnection(this, guild.id, channel.id);
         this.#connections.set(guild.id, connection);
-        await this.#request(guild.id, channel, options);
+        try {
+            await this.#request(guild.id, channel, options);
+        }
+        catch (error) {
+            // Made again here: the reason comes from a timer or from leave(),
+            // whose lines are not the one of the file that asked to join.
+            throw error instanceof Error
+                ? new Error(error.message, { cause: error })
+                : error;
+        }
         if (channel.isStage)
             await this.#speakOnStage(guild.id, channel);
         return connection;

package/dist/voice/usage.d.ts

@@ -1,4 +1,5 @@
+import type { CodeUse } from '../loader/usage.js';
+/** Joining voice, as `loader/usage.ts` looks for it. */
+export declare const VOICE_USE: CodeUse;
 /** Whether some code joins a voice channel. */
 export declare function joinsVoice(code: string): boolean;
-/** Whether a file of `src/` joins a voice channel. */
-export declare function sourcesJoinVoice(cwd: string): Promise<boolean>;

package/dist/voice/usage.js

@@ -2,32 +2,20 @@
 // a bot its own voice state with the GUILD_VOICE_STATES intent, without
 // which `join()` can't finish: like every intent, it is asked for when the
 // project needs it, and only then.
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { GatewayIntent } from '../discord/intents.js';
 /**
  * A call to `join()` without an argument or with options: what joining a
  * voice channel looks like. The `join(', ')` of a list does not match; a
  * `join()` of a list does, and only costs an intent.
  */
 const JOINS_VOICE = /\.join\(\s*(?:\)|\{)/;
-const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+/** Joining voice, as `loader/usage.ts` looks for it. */
+export const VOICE_USE = {
+    name: 'voice',
+    pattern: JOINS_VOICE,
+    intents: GatewayIntent.GuildVoiceStates,
+};
 /** Whether some code joins a voice channel. */
 export function joinsVoice(code) {
     return JOINS_VOICE.test(code);
 }
-/** Whether a file of `src/` joins a voice channel. */
-export async function sourcesJoinVoice(cwd) {
-    const src = join(cwd, 'src');
-    const entries = await readdir(src, {
-        recursive: true,
-        withFileTypes: true,
-    }).catch(() => []);
-    for (const entry of entries) {
-        if (!entry.isFile() || !SOURCE.test(entry.name))
-            continue;
-        const code = await readFile(join(entry.parentPath, entry.name), 'utf8');
-        if (joinsVoice(code))
-            return true;
-    }
-    return false;
-}

package/dist/waiting/usage.d.ts

@@ -0,0 +1,5 @@
+import type { CodeUse } from '../loader/usage.js';
+/** `waitForMessage(` or `collectMessages(`: the messages of a channel. */
+export declare const MESSAGES_USE: CodeUse;
+/** `waitForReaction(`: the reactions to a message. */
+export declare const REACTIONS_USE: CodeUse;

package/dist/waiting/usage.js

@@ -0,0 +1,19 @@
+// What waiting needs from Discord, seen in the code: messages only reach
+// the bot with the intents of messages (and their text with Message
+// Content), reactions with the intents of reactions. Clicks need none.
+// https://docs.discord.com/developers/events/gateway#gateway-intents
+import { GatewayIntent } from '../discord/intents.js';
+/** `waitForMessage(` or `collectMessages(`: the messages of a channel. */
+export const MESSAGES_USE = {
+    name: 'messages',
+    pattern: /\.(?:waitForMessage|collectMessages)\s*\(/,
+    intents: GatewayIntent.GuildMessages |
+        GatewayIntent.DirectMessages |
+        GatewayIntent.MessageContent,
+};
+/** `waitForReaction(`: the reactions to a message. */
+export const REACTIONS_USE = {
+    name: 'reactions',
+    pattern: /\.waitForReaction\s*\(/,
+    intents: GatewayIntent.GuildMessageReactions | GatewayIntent.DirectMessageReactions,
+};

package/dist/waiting/waiters.d.ts

@@ -0,0 +1,48 @@
+/** What can be waited for. */
+export type WaitKind = 'message' | 'reaction' | 'click';
+/** One wait, as a structure asks for it. */
+export interface WaitRequest {
+    readonly kind: WaitKind;
+    /** Whether what is offered is what the wait is for. */
+    match(offered: unknown): boolean;
+    /** How many to take before the wait ends: 1 to wait for one. */
+    readonly max: number;
+    /** How long it waits, in milliseconds. */
+    readonly within: number;
+}
+/**
+ * Told when a run of the files starts and stops waiting, for `chapterjs
+ * test`: a run that waits is not one to wait for.
+ */
+export interface WaitWatcher {
+    parked(run: object): void;
+    resumed(run: object): void;
+}
+/** The waits of a bot. */
+export interface Waiters {
+    /**
+     * Waits for what fits the request, until `max` were taken or the time is
+     * up: resolves with what was taken, in order (maybe nothing).
+     */
+    wait<T>(request: WaitRequest): Promise<T[]>;
+    /** Whether a wait is waiting for this kind: nothing is built otherwise. */
+    wants(kind: WaitKind): boolean;
+    /**
+     * Gives what just happened to the waits that want it. A click goes to
+     * one wait only, and nothing else runs it: returns whether one took it.
+     */
+    offer(kind: WaitKind, offered: unknown): boolean;
+    /** Ends every wait with what it has: the bot stops. */
+    close(): void;
+}
+/** The waits of a bot, in memory: the default. */
+export declare class MemoryWaiters implements Waiters {
+    #private;
+    constructor(options?: {
+        watch?: WaitWatcher;
+    });
+    wait<T>(request: WaitRequest): Promise<T[]>;
+    wants(kind: WaitKind): boolean;
+    offer(kind: WaitKind, offered: unknown): boolean;
+    close(): void;
+}

package/dist/waiting/waiters.js

@@ -0,0 +1,107 @@
+// Waiting for what comes next: the next message of a channel, a click on
+// the buttons of a message, a reaction. A function of the files asks
+// (`channel.waitForMessage()`, `message.waitForClick()`...), the bot offers
+// what Discord sends, and the first thing that fits ends the wait, or the
+// time does. One mechanism for every kind: a new kind of wait is a new
+// `WaitKind` and the place that offers it.
+//
+// Waits live in the process, behind the `Waiters` interface: everything of
+// one server reaches one process (its shard), so a wait always hears what
+// it waits for. A restart ends them: nothing is kept.
+import { currentRun } from '../store/scope.js';
+/** The kinds a single wait takes for itself: nothing else runs them. */
+const EXCLUSIVE = new Set(['click']);
+/** The waits of a bot, in memory: the default. */
+export class MemoryWaiters {
+    #pending = new Map();
+    /** How many waits each run has going. */
+    #runs = new Map();
+    #watch;
+    constructor(options = {}) {
+        this.#watch = options.watch;
+    }
+    wait(request) {
+        return new Promise((resolve, reject) => {
+            const run = currentRun();
+            const taken = [];
+            const list = this.#pending.get(request.kind) ?? new Set();
+            this.#pending.set(request.kind, list);
+            const pending = {
+                request,
+                taken,
+                run,
+                // Nothing of the bot waits for it: a wait never keeps it running.
+                timer: setTimeout(() => pending.end(), request.within).unref(),
+                end: error => {
+                    if (!list.delete(pending))
+                        return;
+                    clearTimeout(pending.timer);
+                    if (list.size === 0)
+                        this.#pending.delete(request.kind);
+                    this.#leave(run);
+                    if (error === undefined)
+                        resolve(taken);
+                    else
+                        reject(error);
+                },
+            };
+            list.add(pending);
+            this.#enter(run);
+        });
+    }
+    wants(kind) {
+        return (this.#pending.get(kind)?.size ?? 0) > 0;
+    }
+    offer(kind, offered) {
+        const list = this.#pending.get(kind);
+        if (!list)
+            return false;
+        let took = false;
+        for (const pending of [...list]) {
+            let fits;
+            try {
+                fits = pending.request.match(offered);
+            }
+            catch (error) {
+                // A test of the files that throws ends its wait with the error,
+                // thrown where the files wait: reported with their line.
+                pending.end(error ?? new Error('The test of the wait threw.'));
+                continue;
+            }
+            if (!fits)
+                continue;
+            took = true;
+            pending.taken.push(offered);
+            if (pending.taken.length >= pending.request.max)
+                pending.end();
+            if (EXCLUSIVE.has(kind))
+                break;
+        }
+        return took;
+    }
+    close() {
+        for (const list of [...this.#pending.values()]) {
+            for (const pending of [...list])
+                pending.end();
+        }
+    }
+    #enter(run) {
+        if (!run)
+            return;
+        const count = this.#runs.get(run) ?? 0;
+        this.#runs.set(run, count + 1);
+        if (count === 0)
+            this.#watch?.parked(run);
+    }
+    #leave(run) {
+        if (!run)
+            return;
+        const count = (this.#runs.get(run) ?? 1) - 1;
+        if (count > 0) {
+            this.#runs.set(run, count);
+            return;
+        }
+        this.#runs.delete(run);
+        this.#watch?.resumed(run);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterjs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Discord framework: ultra simple, but ultra customizable. Your files become a bot, typed end to end, with nothing to register.",
   "keywords": [
     "discord",