chapterjs 0.3.0 → 0.5.0

package/dist/loader/loader.js

@@ -11,6 +11,28 @@ import { importFile } from './hot.js';
 export const siteName = (site) => site.export === undefined || site.export === 'default'
     ? site.file
     : `${site.file} (${site.export})`;
+/** What tells one export of the project from another: `src/a.ts#ban`. */
+export const siteKey = (site) => `${site.file}#${site.export}`;
+/**
+ * The order in which declarations that can't both be kept (two with one
+ * name) are read, the first one winning: what already ran first (`running`,
+ * the `siteKey`s of the declarations of the last load), so that a file saved
+ * in dev never takes its name from one that works, then by file and export,
+ * so that the choice never depends on the order the files were found in.
+ */
+export function bySite(entries, running = new Set()) {
+    const before = (entry) => (running.has(siteKey(entry)) ? 0 : 1);
+    return [...entries].sort((a, b) => before(a) - before(b) ||
+        (a.file === b.file
+            ? a.export < b.export
+                ? -1
+                : a.export > b.export
+                    ? 1
+                    : 0
+            : a.file < b.file
+                ? -1
+                : 1));
+}
 const SOURCE = /\.(?:ts|mts|js|mjs)$/;
 const DECLARATION = /\.d\.m?ts$/;
 /** Tests next to the code: they are for a test runner, not for the bot. */
@@ -68,7 +90,7 @@ export async function loadFiles(files) {
             result.modules.push({ file, exports: await importFile(path) });
         }
         catch (error) {
-            result.failed.push({ file, error });
+            result.failed.push({ file, error: readable(error) });
         }
     }));
     const byFile = (a, b) => a.file < b.file ? -1 : 1;
@@ -76,6 +98,19 @@ export async function loadFiles(files) {
     result.failed.sort(byFile);
     return result;
 }
+/**
+ * A file Node can't read as TypeScript gets the words of its parser
+ * ("Expected ',', got ';'"): what they mean is said after them. The error
+ * is the same, so its line is still found.
+ */
+function readable(error) {
+    if (error instanceof SyntaxError &&
+        error.code === 'ERR_INVALID_TYPESCRIPT_SYNTAX' &&
+        !error.message.includes('This line can not be read')) {
+        error.message = `${error.message.replace(/\.?$/, '.')} This line can not be read: look for a bracket, a comma or a quote missing or in excess, here or just before.`;
+    }
+    return error;
+}
 /** The name of a file, without its folders and its extension. */
 const baseName = (file) => file
     .split('/')
@@ -103,22 +138,32 @@ export function readDeclarations(modules, declaration) {
             export: exported,
             name: exported === 'default' ? baseName(file) : exported,
         };
-        const read = (one) => {
+        const read = (one, at) => {
             if (seen.has(one))
                 return;
             seen.add(one);
-            result.loaded.push({ ...site, value: declaration.read(one, site) });
+            result.loaded.push({ ...at, value: declaration.read(one, at) });
         };
         try {
             if (declaration.is(value))
-                read(value);
+                read(value, site);
             else if (Array.isArray(value) && value.some(declaration.is)) {
                 if (!declaration.list) {
                     throw new TypeError(`This export is a list with a ${declaration.one} in it: export each ${declaration.one} on its own (export const ${site.name} = ...), its name is the name of its export.`);
                 }
-                for (const one of value)
-                    if (declaration.is(one))
-                        read(one);
+                // Each one of the list is told apart by its place in it (`events[2]`),
+                // and read on its own: one that is wrong leaves the others running.
+                value.forEach((one, index) => {
+                    if (!declaration.is(one))
+                        return;
+                    const at = { ...site, export: `${exported}[${index}]` };
+                    try {
+                        read(one, at);
+                    }
+                    catch (error) {
+                        result.failed.push({ file, export: at.export, error });
+                    }
+                });
             }
         }
         catch (error) {

package/dist/loader/usage.d.ts

@@ -0,0 +1,15 @@
+/** A use of the framework seen in the code, and the intents it needs. */
+export interface CodeUse {
+    /** What the use is called in `build.json`: `'voice'`, `'messages'`... */
+    readonly name: string;
+    /** What the code looks like when it does it. */
+    readonly pattern: RegExp;
+    /** The intents Discord must be asked for (`GatewayIntent` bits). */
+    readonly intents: number;
+}
+/** The uses found: for each name, the files that do it (`src/quiz.ts`). */
+export type FoundUses = Readonly<Record<string, readonly string[]>>;
+/** Reads the files of `src/` for each use. */
+export declare function scanUses(cwd: string, uses: readonly CodeUse[]): Promise<FoundUses>;
+/** The intents the uses found need. */
+export declare function usesIntents(uses: readonly CodeUse[], found: FoundUses): number;

package/dist/loader/usage.js

@@ -0,0 +1,40 @@
+// What a project does that only its code shows: no declaration says that
+// it joins voice or waits for a message, yet Discord only sends what that
+// needs with an intent. Each feature describes such a use (`CodeUse`) and
+// the files of `src/` are read for it, so the intent is asked for when the
+// project needs it, and only then, like the intents of its events.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+/** Test files are never loaded by the bot. */
+const TEST = /\.(?:test|spec)\.[^.]+$/;
+/** Reads the files of `src/` for each use. */
+export async function scanUses(cwd, uses) {
+    const found = {};
+    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) || TEST.test(entry.name)) {
+            continue;
+        }
+        if (entry.name.endsWith('.d.ts'))
+            continue;
+        const path = join(entry.parentPath, entry.name);
+        const code = await readFile(path, 'utf8').catch(() => '');
+        for (const use of uses) {
+            if (use.pattern.test(code)) {
+                (found[use.name] ??= []).push(relative(cwd, path).split('\\').join('/'));
+            }
+        }
+    }
+    for (const files of Object.values(found))
+        files.sort();
+    return found;
+}
+/** The intents the uses found need. */
+export function usesIntents(uses, found) {
+    return uses.reduce((intents, use) => (found[use.name]?.length ?? 0) > 0 ? intents | use.intents : intents, 0);
+}

package/dist/loader/watch.d.ts

@@ -4,9 +4,11 @@
  */
 export declare function snapshotFolder(dir: string): Promise<string>;
 /**
- * Calls `onChange` when files under `dir` are saved, once per burst: an
- * editor often writes a file in several steps, and saving several files at
- * once is one change.
+ * Calls `onChange` when files under `dir` are saved, once per change: an
+ * editor often writes a file in several steps, saving several files at once
+ * is one change, and the system may tell a save twice, a moment apart (macOS
+ * does for a file written then renamed over the old one). What is compared
+ * is the folder itself, so a save that changed nothing reloads nothing.
  */
 export declare function watchFolder(dir: string, onChange: () => void, { delay, loaded, }?: {
     delay?: number;

package/dist/loader/watch.js

@@ -20,13 +20,31 @@ export async function snapshotFolder(dir) {
     return files.sort().join('\n');
 }
 /**
- * Calls `onChange` when files under `dir` are saved, once per burst: an
- * editor often writes a file in several steps, and saving several files at
- * once is one change.
+ * Calls `onChange` when files under `dir` are saved, once per change: an
+ * editor often writes a file in several steps, saving several files at once
+ * is one change, and the system may tell a save twice, a moment apart (macOS
+ * does for a file written then renamed over the old one). What is compared
+ * is the folder itself, so a save that changed nothing reloads nothing.
  */
 export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder(dir), } = {}) {
     let timer = null;
     let closed = false;
+    /** The folder as the last load saw it. */
+    let lastSeen = loaded;
+    /** One comparison at a time, in the order the bursts ended. */
+    let comparing = Promise.resolve();
+    const compare = () => {
+        comparing = comparing.then(async () => {
+            if (closed)
+                return;
+            await watcher.refresh();
+            const [then, now] = await Promise.all([lastSeen, snapshotFolder(dir)]);
+            if (closed || then === now)
+                return;
+            lastSeen = Promise.resolve(now);
+            onChange();
+        });
+    };
     const changed = () => {
         if (closed)
             return;
@@ -34,25 +52,14 @@ export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = null;
-            onChange();
+            compare();
         }, delay);
     };
-    const watcher = watch(dir, { recursive: true }, changed);
-    // The folder being deleted is not a reason to crash the bot.
-    watcher.on('error', () => { });
+    const watcher = watchTree(dir, changed);
     // The system takes a moment to really start watching: a file saved
     // between the load and that moment would be missed. The folder is
     // compared, a little later, with what it was when it was loaded.
-    const before = loaded;
-    const catchUps = [300, 1500].map(wait => setTimeout(() => {
-        void Promise.all([before, snapshotFolder(dir)]).then(([then, now]) => {
-            if (then !== now && lastSeen !== now) {
-                lastSeen = now;
-                changed();
-            }
-        });
-    }, wait));
-    let lastSeen = null;
+    const catchUps = [300, 1500].map(wait => setTimeout(compare, wait));
     return {
         close() {
             closed = true;
@@ -64,3 +71,67 @@ export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder
         },
     };
 }
+/**
+ * Calls `listener` when anything under `dir` changes. macOS and Windows watch
+ * a tree themselves. Elsewhere Node watches every file on its own, and a file
+ * written then renamed over the old one (how vim and JetBrains save) is a new
+ * file it never watches again: its next saves would be missed. So each folder
+ * is watched instead, which hears every file in it whatever replaced it, and
+ * `refresh()` follows the folders created or deleted since.
+ */
+function watchTree(dir, listener) {
+    const open = (path, recursive) => {
+        const watcher = watch(path, { recursive }, listener);
+        // A folder being deleted is not a reason to crash the bot.
+        watcher.on('error', () => { });
+        return watcher;
+    };
+    if (process.platform === 'darwin' || process.platform === 'win32') {
+        const watcher = open(dir, true);
+        return { refresh: async () => { }, close: () => watcher.close() };
+    }
+    const watchers = new Map();
+    let closed = false;
+    const refresh = async () => {
+        const entries = await readdir(dir, {
+            recursive: true,
+            withFileTypes: true,
+        }).catch(() => []);
+        if (closed)
+            return;
+        const folders = new Set([
+            dir,
+            ...entries
+                .filter(entry => entry.isDirectory())
+                .map(entry => join(entry.parentPath, entry.name)),
+        ]);
+        for (const [path, watcher] of watchers) {
+            if (folders.has(path))
+                continue;
+            watcher.close();
+            watchers.delete(path);
+        }
+        for (const path of folders) {
+            if (watchers.has(path))
+                continue;
+            try {
+                watchers.set(path, open(path, false));
+            }
+            catch {
+                // Deleted since it was listed: the next refresh forgets it.
+            }
+        }
+    };
+    // The folder itself at once, so nothing is missed while the rest is read.
+    watchers.set(dir, open(dir, false));
+    void refresh();
+    return {
+        refresh,
+        close() {
+            closed = true;
+            for (const watcher of watchers.values())
+                watcher.close();
+            watchers.clear();
+        },
+    };
+}

package/dist/messages/commands.js

@@ -25,6 +25,9 @@ export const defaultLanguageFile = (messages) => messages?.files.get(messages.de
  * already does. What is wrong is reported on the file it is wrong in.
  */
 export function translateCommand(file, command, messages) {
+    // A menu command has its name and translations in its file, always.
+    if (command.type !== 'slash')
+        return { command, failed: [] };
     const path = command.path.join(' ');
     const name = commandName(command.path);
     const failed = [];

package/dist/messages/messages.d.ts

@@ -8,6 +8,7 @@ import type { Locale } from '../discord/types/common.js';
  * out. `{count}` in a form is the number itself.
  */
 export interface PluralText {
+    /** For 0, in every language; and where a language has a form of its own for other numbers too (Arabic, Latvian). */
     zero?: string;
     one?: string;
     two?: string;

package/dist/messages/translate.js

@@ -146,7 +146,11 @@ export function fill(key, template, params, locale = 'en-US') {
         if (typeof count !== 'number') {
             throw new TypeError(`The message "${key}" is a plural: its {count} is a number, got ${JSON.stringify(count)}.`);
         }
-        const form = pluralRule(locale).select(count);
+        // A `zero` written is for 0 in every language, as people expect it
+        // ("no apple"): the rules of English never pick it by themselves.
+        const form = count === 0 && template.forms.has('zero')
+            ? 'zero'
+            : pluralRule(locale).select(count);
         template = template.forms.get(form) ?? template.forms.get('other');
     }
     let text = '';

package/dist/presence/declaration.d.ts

@@ -1,17 +1,64 @@
 import type { Declaration } from '../loader/loader.js';
 import { type RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import { type ActivityKind, type PresenceContext, type PresenceStatusName } from './presence.js';
+/** The text of an activity as a file gives it: a text, or a function. */
+export type LoadedText = string | ((context: PresenceContext) => string | Promise<string>);
+/** An activity, checked. */
+export interface LoadedActivity {
+    readonly type: ActivityKind | 'streaming';
+    readonly name: LoadedText;
+    readonly url?: string;
+    /** How long it is shown, in milliseconds. */
+    readonly for: number;
+}
+/** The function of a file that gives the activities. */
+export type ActivitiesFunction = (context: PresenceContext) => unknown | Promise<unknown>;
 /** The presence, checked: what the gateway sends. */
 export interface LoadedPresence {
-    /** The Update Presence payload (also sent with Identify). */
+    readonly status: PresenceStatusName;
+    /** The activities shown in turn (none, one or several), or the function giving them. */
+    readonly activities: readonly LoadedActivity[] | ActivitiesFunction;
+    /**
+     * What the bot connects with (sent with Identify): the first activity
+     * when it is known without running anything, else the status alone.
+     */
     readonly raw: RawGatewayPresenceUpdate;
-    /** What tells one presence from another: the payload, as text. */
+    /**
+     * What tells one presence from another: what it sends, and the code of
+     * its functions, as text. The same file saved again has the same key.
+     */
     readonly key: string;
 }
+/** How long an activity is shown when the file does not say. */
+export declare const DEFAULT_FOR = 30000;
+/**
+ * The shortest time an activity may be shown. "Clients may only update
+ * their game status 5 times per 20 seconds": one every 5 seconds is
+ * always sent at once.
+ * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+ */
+export declare const MIN_FOR = 5000;
 /**
  * What a bot without a presence shows: online, doing nothing. Sent when
  * the declaration is removed while the bot runs.
  */
 export declare const DEFAULT_PRESENCE: RawGatewayPresenceUpdate;
+/**
+ * What the gateway sends for a status and the activity shown, with its
+ * text. `since` and `afk` are about a person's client going idle: a bot is
+ * never away from its keyboard.
+ */
+export declare function toRaw(status: PresenceStatusName, activity: {
+    type: LoadedActivity['type'];
+    url?: string;
+} | null, name: string): RawGatewayPresenceUpdate;
+/** Checks the text of an activity a function gave, when it ran. */
+export declare function checkText(name: unknown): string;
+/**
+ * Checks a list of activities: the one of a file, or what its function
+ * gave when it ran.
+ */
+export declare function readActivities(value: unknown): LoadedActivity[];
 /**
  * The presence of the bot, declared once anywhere in `src/` with
  * `presence()` and exported.

package/dist/presence/declaration.js

@@ -1,14 +1,17 @@
 // What a file declares with `presence()`: what the bot shows under its
 // name. It is checked when it loads and turned into what the gateway
 // sends, so a wrong status or type is explained before the bot connects.
+// The activities a function gives are checked the same way when it runs
+// (`readActivities`).
 import { ActivityType, } from '../discord/types/gateway-events.js';
-import { isPresenceDeclaration } from './presence.js';
+import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+import { isPresenceDeclaration, } from './presence.js';
 const fail = message => {
     throw new TypeError(message);
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const KEYS = ['status', 'activity'];
-const ACTIVITY_KEYS = ['type', 'name', 'url'];
+const KEYS = ['status', 'activity', 'activities'];
+const ACTIVITY_KEYS = ['type', 'name', 'url', 'for'];
 /**
  * The statuses a file may give.
  * @see https://docs.discord.com/developers/events/gateway-events#update-presence-status-types
@@ -32,6 +35,17 @@ const TYPES = {
  * @see https://docs.discord.com/developers/events/gateway-events#activity-object-activity-types
  */
 const STREAM_URL = /^https:\/\/(?:www\.)?(?:twitch\.tv|youtube\.com)\//;
+/** How long an activity is shown when the file does not say. */
+export const DEFAULT_FOR = 30_000;
+/**
+ * The shortest time an activity may be shown. "Clients may only update
+ * their game status 5 times per 20 seconds": one every 5 seconds is
+ * always sent at once.
+ * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+ */
+export const MIN_FOR = 5_000;
+/** The most activities a list may have. */
+const MAX_ACTIVITIES = 100;
 const list = (words) => words.map(word => `'${word}'`).join(', ');
 const EXAMPLE = `presence({ status: 'online', activity: { type: 'watching', name: 'over the server' } })`;
 /**
@@ -44,25 +58,86 @@ export const DEFAULT_PRESENCE = Object.freeze({
     status: 'online',
     afk: false,
 });
-/** Turns a checked config into what the gateway sends. */
-function toRaw(config) {
+/**
+ * What the gateway sends for a status and the activity shown, with its
+ * text. `since` and `afk` are about a person's client going idle: a bot is
+ * never away from its keyboard.
+ */
+export function toRaw(status, activity, name) {
     const activities = [];
-    if (config.activity) {
-        const { type, name, url } = config.activity;
+    if (activity) {
+        const { type, url } = activity;
         activities.push(type === 'custom'
             ? // A custom status shows its `state`; `name` is not shown but required.
                 { name: 'Custom Status', type: TYPES.custom, state: name }
             : { name, type: TYPES[type], ...(url ? { url } : {}) });
     }
-    // `since` and `afk` are about a person's client going idle: a bot is
-    // never away from its keyboard.
-    return {
-        since: null,
-        activities,
-        status: config.status ?? 'online',
-        afk: false,
-    };
+    return { since: null, activities, status, afk: false };
 }
+/** Checks the text of an activity a function gave, when it ran. */
+export function checkText(name) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        return fail(`The "name" of the activity is the text shown under the name of the bot: it can't be empty${typeof name === 'string' ? '' : ` (got ${JSON.stringify(name) ?? typeof name})`}.`);
+    }
+    return name;
+}
+/** Checks one activity: `where` says which one, in messages. */
+function readActivity(activity, where) {
+    if (!isRecord(activity)) {
+        return fail(`${where} is what the bot is doing, an object: { type: 'playing', name: '/help' }`);
+    }
+    for (const key of Object.keys(activity)) {
+        if (!ACTIVITY_KEYS.includes(key)) {
+            fail(`"${key}" is not something an activity has. It can have: ${ACTIVITY_KEYS.join(', ')}.`);
+        }
+    }
+    const { type, name, url } = activity;
+    if (typeof type !== 'string' || !(type in TYPES)) {
+        fail(`The "type" of ${where} is ${JSON.stringify(type)}: it can be ${list(Object.keys(TYPES))}.`);
+    }
+    if (typeof name !== 'function')
+        checkText(name);
+    if (type === 'streaming') {
+        if (typeof url !== 'string' || !STREAM_URL.test(url)) {
+            fail(`A "streaming" activity needs the "url" of the stream, and Discord only accepts a https://twitch.tv/ or a https://youtube.com/ link${typeof url === 'string' ? ` (got ${JSON.stringify(url)})` : ''}.`);
+        }
+    }
+    else if (url !== undefined) {
+        fail(`"url" only goes with a "streaming" activity: a ${JSON.stringify(type)} activity has no link.`);
+    }
+    let ms = DEFAULT_FOR;
+    if (activity.for !== undefined) {
+        const parsed = typeof activity.for === 'string' ? parseDuration(activity.for) : null;
+        if (parsed === null) {
+            fail(`"for" of ${where} is how long it is shown, a duration (${DURATION_EXAMPLE}): got ${JSON.stringify(activity.for) ?? typeof activity.for}.`);
+        }
+        if (parsed < MIN_FOR) {
+            fail(`"for" of ${where} is ${JSON.stringify(activity.for)}: an activity is shown 5 seconds at least, since Discord takes 5 changes of presence per 20 seconds.`);
+        }
+        ms = parsed;
+    }
+    return Object.freeze({
+        type: type,
+        name: name,
+        ...(url === undefined ? {} : { url: url }),
+        for: ms,
+    });
+}
+/**
+ * Checks a list of activities: the one of a file, or what its function
+ * gave when it ran.
+ */
+export function readActivities(value) {
+    if (!Array.isArray(value)) {
+        return fail(`"activities" is a list of activities, like [{ type: 'playing', name: '/help', for: '30s' }]: got ${JSON.stringify(value) ?? typeof value}.`);
+    }
+    if (value.length > MAX_ACTIVITIES) {
+        fail(`"activities" has ${value.length} activities: ${MAX_ACTIVITIES} at most.`);
+    }
+    return value.map((activity, index) => readActivity(activity, `activity ${index + 1} of "activities"`));
+}
+/** A function as text, so that the same code saved again is not a change. */
+const codeOf = (value) => typeof value === 'function' ? `ƒ ${String(value)}` : value;
 /**
  * The presence of the bot, declared once anywhere in `src/` with
  * `presence()` and exported.
@@ -82,37 +157,45 @@ export const presenceDeclaration = {
                 fail(`"${key}" is not something a presence has. It can have: ${KEYS.join(', ')}.`);
             }
         }
-        const { status, activity } = config;
-        if (status !== undefined &&
-            !STATUSES.includes(status)) {
+        const { status = 'online', activity } = config;
+        if (!STATUSES.includes(status)) {
             fail(`"status" is ${JSON.stringify(status)}: it can be ${list(STATUSES)}.`);
         }
+        if (activity !== undefined && config.activities !== undefined) {
+            fail(`A presence has "activity" (one) or "activities" (several, shown in turn), not both.`);
+        }
+        let activities = [];
         if (activity !== undefined) {
             if (!isRecord(activity)) {
                 fail(`"activity" is what the bot is doing, an object: activity: { type: 'playing', name: '/help' }`);
             }
-            for (const key of Object.keys(activity)) {
-                if (!ACTIVITY_KEYS.includes(key)) {
-                    fail(`"${key}" is not something an activity has. It can have: ${ACTIVITY_KEYS.join(', ')}.`);
-                }
-            }
-            const { type, name, url } = activity;
-            if (typeof type !== 'string' || !(type in TYPES)) {
-                fail(`The "type" of the activity is ${JSON.stringify(type)}: it can be ${list(Object.keys(TYPES))}.`);
-            }
-            if (typeof name !== 'string' || name.trim() === '') {
-                fail(`The "name" of the activity is the text shown under the name of the bot: it can't be empty.`);
-            }
-            if (type === 'streaming') {
-                if (typeof url !== 'string' || !STREAM_URL.test(url)) {
-                    fail(`A "streaming" activity needs the "url" of the stream, and Discord only accepts a https://twitch.tv/ or a https://youtube.com/ link${typeof url === 'string' ? ` (got ${JSON.stringify(url)})` : ''}.`);
-                }
-            }
-            else if (url !== undefined) {
-                fail(`"url" only goes with a "streaming" activity: a ${JSON.stringify(type)} activity has no link.`);
+            activities = [readActivity(activity, 'the activity')];
+        }
+        else if (typeof config.activities === 'function') {
+            activities = config.activities;
+        }
+        else if (config.activities !== undefined) {
+            activities = readActivities(config.activities);
+            if (activities.length === 0) {
+                fail(`"activities" is empty: give it the activities to show in turn, or leave it out.`);
             }
         }
-        const raw = toRaw(config);
-        return { raw, key: JSON.stringify(raw) };
+        const first = Array.isArray(activities) ? activities[0] : undefined;
+        const raw = toRaw(status, first && typeof first.name === 'string' ? first : null, first && typeof first.name === 'string' ? first.name : '');
+        const shape = Array.isArray(activities)
+            ? activities.map(one => ({ ...one, name: codeOf(one.name) }))
+            : codeOf(activities);
+        return {
+            status: status,
+            activities,
+            raw,
+            // One activity whose text is known: told apart by what it sends, so
+            // a presence written another way but sending the same is no change.
+            key: Array.isArray(activities) &&
+                activities.length <= 1 &&
+                activities.every(one => typeof one.name === 'string' && one.for === DEFAULT_FOR)
+                ? JSON.stringify(raw)
+                : JSON.stringify({ status, activities: shape }),
+        };
     },
 };