chapterjs 0.1.2 → 0.2.0

package/dist/loader/loader.d.ts

@@ -0,0 +1,85 @@
+/** Where a declaration was found: a file of the project, and its export. */
+export interface ExportSite {
+    /** The path from the project folder, with `/`: `src/moderation/ban.ts`. */
+    file: string;
+    /** The name of the export: `'ban'`, or `'default'`. */
+    export: string;
+    /**
+     * The name the export gives to what it declares: the name of the export,
+     * or the name of the file (without extension) for the default export.
+     */
+    name: string;
+}
+/** A kind of declaration a feature reads from the exports of the files. */
+export interface Declaration<T> {
+    /** What one is called in messages: "event", "command"... */
+    one: string;
+    many: string;
+    /** Whether a value is one of these, before it is read. */
+    is(value: unknown): boolean;
+    /**
+     * Whether a file may export several in a list. Only what names itself
+     * (an event, a command, a language) may: a list has no export name to
+     * give each one.
+     */
+    list: boolean;
+    /**
+     * Checks a declaration and returns what the feature needs from it.
+     * Throws an error whose message says what to write.
+     */
+    read(value: unknown, site: ExportSite): T;
+}
+/** A declaration, read, with where it comes from. */
+export interface LoadedItem<T> extends ExportSite {
+    value: T;
+}
+/** An export the framework could not use, or a file that could not run. */
+export interface FailedFile {
+    file: string;
+    /** The export that failed, when the file itself ran. */
+    export?: string;
+    error: unknown;
+}
+/** The declarations of one kind found in the files. */
+export interface LoadResult<T> {
+    loaded: LoadedItem<T>[];
+    failed: FailedFile[];
+}
+/** What `file` is called in a message: `src/a.ts`, or `src/a.ts (ban)`. */
+export declare const siteName: (site: {
+    file: string;
+    export?: string;
+}) => string;
+/** A file of the project, found but not run. */
+export interface FoundFile {
+    /** The path from the project folder, with `/`: `src/ping.ts`. */
+    file: string;
+    /** Where it is on disk. */
+    path: string;
+}
+/** Every source file of `src/`, in a stable order. */
+export declare function listSources(projectDir: string): Promise<FoundFile[]>;
+/** A file of the project, run: what it exports. */
+export interface LoadedModule {
+    /** The path from the project folder: `src/ping.ts`. */
+    file: string;
+    exports: Record<string, unknown>;
+}
+/** The files of the project, run (`modules`) or not (`failed`). */
+export interface LoadedSources {
+    modules: LoadedModule[];
+    failed: FailedFile[];
+}
+/** Runs every file of `src/`. A file that fails to run never throws. */
+export declare function loadSources(projectDir: string): Promise<LoadedSources>;
+/**
+ * Reads the declarations of one kind from what the files export. Every
+ * export is looked at; the ones the kind recognises are read, the others
+ * are someone else's (another kind, or plain code). The same value
+ * exported twice (re-exported by another file) is one declaration, at the
+ * first place it is found. An export that can't be read is returned in
+ * `failed`, with its name, and never throws.
+ */
+export declare function readDeclarations<T>(modules: readonly LoadedModule[], declaration: Declaration<T>): LoadResult<T>;
+/** A file of the project as a build kept it: already run. */
+export type BuiltFile = LoadedModule;

package/dist/loader/loader.js

@@ -0,0 +1,119 @@
+// Loads the files of a project and finds what they declare. Every source
+// file under `src/` is loaded, wherever it is and whatever it is called:
+// what the framework runs is what the files export, made with one of its
+// functions (`command()`, `event()`, `button()`...). One mechanism for
+// every feature: a feature only says how to recognise and read its
+// declarations.
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { importFile } from './hot.js';
+/** What `file` is called in a message: `src/a.ts`, or `src/a.ts (ban)`. */
+export const siteName = (site) => site.export === undefined || site.export === 'default'
+    ? site.file
+    : `${site.file} (${site.export})`;
+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. */
+const TEST = /\.(?:test|spec)\.[^.]+$/;
+/** The source files of a folder and its subfolders, in a stable order. */
+async function scan(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const files = [];
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await scan(path)));
+        else if (SOURCE.test(entry.name) &&
+            !DECLARATION.test(entry.name) &&
+            !TEST.test(entry.name)) {
+            files.push(path);
+        }
+    }
+    return files;
+}
+/** Every source file of `src/`, in a stable order. */
+export async function listSources(projectDir) {
+    const paths = await scan(join(projectDir, 'src'));
+    return paths
+        .map(path => ({
+        file: relative(projectDir, path).split(sep).join('/'),
+        path,
+    }))
+        .sort((a, b) => (a.file < b.file ? -1 : 1));
+}
+/** Runs every file of `src/`. A file that fails to run never throws. */
+export async function loadSources(projectDir) {
+    const found = await listSources(projectDir);
+    const result = { modules: [], failed: [] };
+    await Promise.all(found.map(async ({ file, path }) => {
+        try {
+            result.modules.push({ file, exports: await importFile(path) });
+        }
+        catch (error) {
+            result.failed.push({ file, error });
+        }
+    }));
+    const byFile = (a, b) => a.file < b.file ? -1 : 1;
+    result.modules.sort(byFile);
+    result.failed.sort(byFile);
+    return result;
+}
+/** The name of a file, without its folders and its extension. */
+const baseName = (file) => file
+    .split('/')
+    .pop()
+    .replace(/\.[^.]+$/, '');
+/**
+ * Reads the declarations of one kind from what the files export. Every
+ * export is looked at; the ones the kind recognises are read, the others
+ * are someone else's (another kind, or plain code). The same value
+ * exported twice (re-exported by another file) is one declaration, at the
+ * first place it is found. An export that can't be read is returned in
+ * `failed`, with its name, and never throws.
+ */
+export function readDeclarations(modules, declaration) {
+    const result = { loaded: [], failed: [] };
+    const seen = new Set();
+    const sites = [...modules]
+        .sort((a, b) => (a.file < b.file ? -1 : 1))
+        .flatMap(({ file, exports }) => Object.keys(exports)
+        .sort()
+        .map(name => ({ file, export: name, value: exports[name] })));
+    for (const { file, export: exported, value } of sites) {
+        const site = {
+            file,
+            export: exported,
+            name: exported === 'default' ? baseName(file) : exported,
+        };
+        const read = (one) => {
+            if (seen.has(one))
+                return;
+            seen.add(one);
+            result.loaded.push({ ...site, value: declaration.read(one, site) });
+        };
+        try {
+            if (declaration.is(value))
+                read(value);
+            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);
+            }
+        }
+        catch (error) {
+            result.failed.push({ file, export: exported, error });
+        }
+    }
+    return result;
+}

package/dist/loader/locate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where in the project an error comes from: the first place of its stack
+ * that is a file of the project (not a package, not Node itself).
+ */
+export declare function locate(error: unknown, projectDir: string): {
+    file: string;
+    line: number;
+} | null;
+/** The message of an error, on one line, without hot reload noise. */
+export declare function messageOf(error: unknown): string;

package/dist/loader/locate.js

@@ -0,0 +1,36 @@
+import { relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cleanPath } from './hot.js';
+/**
+ * Where in the project an error comes from: the first place of its stack
+ * that is a file of the project (not a package, not Node itself).
+ */
+export function locate(error, projectDir) {
+    if (!(error instanceof Error) || typeof error.stack !== 'string')
+        return null;
+    const stack = cleanPath(error.stack);
+    // `file:///project/src/a.ts:3:7` in a stack frame, or `/project/src/a.ts:3`
+    // on the first line of a syntax error.
+    const pattern = /(file:\/\/[^\s():]+|(?:\/|[A-Za-z]:\\)[^\s():]+):(\d+)/g;
+    for (const match of stack.matchAll(pattern)) {
+        let path = match[1];
+        try {
+            if (path.startsWith('file://'))
+                path = fileURLToPath(path);
+        }
+        catch {
+            continue;
+        }
+        const inside = relative(projectDir, path);
+        if (inside.startsWith('..') || inside.split(sep).includes('node_modules')) {
+            continue;
+        }
+        return { file: inside.split(sep).join('/'), line: Number(match[2]) };
+    }
+    return null;
+}
+/** The message of an error, on one line, without hot reload noise. */
+export function messageOf(error) {
+    const text = error instanceof Error ? error.message : `Thrown value: ${String(error)}`;
+    return cleanPath(text).trim();
+}

package/dist/loader/watch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What every file under a folder looks like right now: taken before the
+ * files are loaded, it lets `watchFolder` notice what was saved since.
+ */
+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.
+ */
+export declare function watchFolder(dir: string, onChange: () => void, { delay, loaded, }?: {
+    delay?: number;
+    /** The folder as it was when its files were loaded. */
+    loaded?: Promise<string>;
+}): {
+    close(): void;
+};

package/dist/loader/watch.js

@@ -0,0 +1,66 @@
+import { watch } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * What every file under a folder looks like right now: taken before the
+ * files are loaded, it lets `watchFolder` notice what was saved since.
+ */
+export async function snapshotFolder(dir) {
+    const entries = await readdir(dir, {
+        recursive: true,
+        withFileTypes: true,
+    }).catch(() => []);
+    const files = await Promise.all(entries
+        .filter(entry => entry.isFile())
+        .map(async (entry) => {
+        const path = join(entry.parentPath, entry.name);
+        const info = await stat(path).catch(() => null);
+        return `${path}:${info?.mtimeMs ?? 0}:${info?.size ?? 0}`;
+    }));
+    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.
+ */
+export function watchFolder(dir, onChange, { delay = 60, loaded = snapshotFolder(dir), } = {}) {
+    let timer = null;
+    let closed = false;
+    const changed = () => {
+        if (closed)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            onChange();
+        }, delay);
+    };
+    const watcher = watch(dir, { recursive: true }, changed);
+    // The folder being deleted is not a reason to crash the bot.
+    watcher.on('error', () => { });
+    // 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;
+    return {
+        close() {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const catchUp of catchUps)
+                clearTimeout(catchUp);
+            watcher.close();
+        },
+    };
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export * from './index.js';
+export { asset } from './assets/asset.js';

package/dist/main.js

@@ -0,0 +1,5 @@
+// What `import ... from 'chapterjs'` loads at runtime: the public API, plus
+// `asset()`, whose type depends on the project it is imported from. Its
+// type is not here but in the `.chapterjs/` folder of each project.
+export * from './index.js';
+export { asset } from './assets/asset.js';

package/dist/messages/commands.d.ts

@@ -0,0 +1,23 @@
+import { type LoadedCommand } from '../commands/declaration.js';
+import type { FailedFile } from '../loader/loader.js';
+import type { LoadedMessages } from './translate.js';
+/** A command given its texts by the language files. */
+export interface TranslatedCommand {
+    /** The command, described; `null` when it can't be, said in `failed`. */
+    readonly command: LoadedCommand | null;
+    /** What is wrong, on the file it is wrong in. */
+    readonly failed: readonly FailedFile[];
+}
+/** The names the languages translate that no command has, by file. */
+export declare function unknownCommands(messages: LoadedMessages, known: ReadonlySet<string>): {
+    file: string;
+    path: string;
+}[];
+/** Where the default language file is, or would be. */
+export declare const defaultLanguageFile: (messages: LoadedMessages | null) => string;
+/**
+ * Gives a command its texts from the languages, when its file does not
+ * describe it; refuses the languages that describe a command its file
+ * already does. What is wrong is reported on the file it is wrong in.
+ */
+export declare function translateCommand(file: string, command: LoadedCommand, messages: LoadedMessages | null): TranslatedCommand;

package/dist/messages/commands.js

@@ -0,0 +1,142 @@
+// The `commands` of the language files: what Discord shows of each command
+// in each language. A command has its texts in one place: in
+// its file (`description`, `locales`), or in the language files, where the
+// default language gives what Discord shows to everyone and the others
+// their translations. Which one is decided by `description` in the file.
+import { checkLocales, } from '../commands/declaration.js';
+import { commandName } from '../commands/tree.js';
+/** The names the languages translate that no command has, by file. */
+export function unknownCommands(messages, known) {
+    const unknown = [];
+    for (const [locale, section] of messages.commands) {
+        for (const path of Object.keys(section)) {
+            if (!known.has(path)) {
+                unknown.push({ file: messages.files.get(locale), path });
+            }
+        }
+    }
+    return unknown;
+}
+/** Where the default language file is, or would be. */
+export const defaultLanguageFile = (messages) => messages?.files.get(messages.default) ?? 'the default language file';
+/**
+ * Gives a command its texts from the languages, when its file does not
+ * describe it; refuses the languages that describe a command its file
+ * already does. What is wrong is reported on the file it is wrong in.
+ */
+export function translateCommand(file, command, messages) {
+    const path = command.path.join(' ');
+    const name = commandName(command.path);
+    const failed = [];
+    const languages = [...(messages?.commands ?? [])].filter(([, section]) => path in section);
+    if (command.described) {
+        for (const [locale] of languages) {
+            failed.push({
+                file: messages.files.get(locale),
+                error: new TypeError(`${name} is described in ${file}: remove its description there to translate it here, or remove it here.`),
+            });
+        }
+        return { command, failed };
+    }
+    const where = defaultLanguageFile(messages);
+    const example = (inside) => `${where} (commands: { ${JSON.stringify(path)}: { ${inside} } })`;
+    // Each language is checked on its own, so an error names its file.
+    const given = new Map();
+    for (const [locale, section] of languages) {
+        try {
+            given.set(locale, checkLocales({ [locale]: section[path] }, command.options));
+        }
+        catch (error) {
+            failed.push({
+                file: messages.files.get(locale),
+                error: new TypeError(`In "commands", for ${name}: ${error instanceof Error ? error.message : String(error)}`),
+            });
+        }
+    }
+    // The default language describes the command; when it does not, the
+    // first language that does (en-US first) is what Discord shows to all.
+    const order = messages
+        ? [...given.keys()].sort((a, b) => a === messages.default
+            ? -1
+            : b === messages.default
+                ? 1
+                : a === 'en-US'
+                    ? -1
+                    : b === 'en-US'
+                        ? 1
+                        : a < b
+                            ? -1
+                            : 1)
+        : [];
+    const mainLocale = order.find(locale => given.get(locale).descriptions[locale]) ??
+        messages?.default;
+    const main = mainLocale ? given.get(mainLocale) : undefined;
+    const description = mainLocale ? main?.descriptions[mainLocale] : undefined;
+    if (description === undefined) {
+        failed.push({
+            file,
+            error: new TypeError(`This command has no description: write it in ${example("description: '...'")}, or in the file (description: '...').`),
+        });
+        return { command: null, failed };
+    }
+    const options = [];
+    for (const option of command.options) {
+        const text = option.description ||
+            (mainLocale
+                ? main?.optionLocales[option.name]?.descriptions[mainLocale]
+                : undefined);
+        if (!text) {
+            failed.push({
+                file,
+                error: new TypeError(`The option "${option.name}" of ${name} has no description: write it in ${example(`options: { ${option.name}: { description: '...' } }`)}, or in the file.`),
+            });
+            return { command: null, failed };
+        }
+        options.push({ ...option, description: text });
+    }
+    // The other languages are translations; the default one is what Discord
+    // shows to everyone, and needs none.
+    const names = {};
+    const descriptions = {};
+    const optionLocales = {};
+    for (const [locale, texts] of given) {
+        if (locale === mainLocale)
+            continue;
+        const text = texts.names[locale];
+        if (text !== undefined)
+            names[locale] = text;
+        const about = texts.descriptions[locale];
+        if (about !== undefined)
+            descriptions[locale] = about;
+        for (const [option, theirs] of Object.entries(texts.optionLocales)) {
+            const target = (optionLocales[option] ??= {
+                names: {},
+                descriptions: {},
+                choices: {},
+            });
+            const optionName = theirs.names[locale];
+            if (optionName !== undefined)
+                target.names[locale] = optionName;
+            const optionAbout = theirs.descriptions[locale];
+            if (optionAbout !== undefined)
+                target.descriptions[locale] = optionAbout;
+            for (const [choice, choiceTexts] of Object.entries(theirs.choices)) {
+                const choiceText = choiceTexts[locale];
+                if (choiceText !== undefined) {
+                    (target.choices[choice] ??= {})[locale] = choiceText;
+                }
+            }
+        }
+    }
+    return {
+        command: {
+            ...command,
+            description,
+            options: Object.freeze(options),
+            names,
+            descriptions,
+            optionLocales,
+        },
+        failed,
+    };
+}

package/dist/messages/declaration.d.ts

@@ -0,0 +1,89 @@
+import type { Locale } from '../discord/types/common.js';
+import { type Declaration, type ExportSite, type FailedFile } from '../loader/loader.js';
+import { type LoadedMessages, type Template } from './translate.js';
+/** A language, checked: what the languages are assembled from. */
+export interface LoadedLanguage {
+    /** The language. */
+    readonly locale: Locale;
+    /** Whether it says it is the default language. */
+    readonly isDefault: boolean;
+    /** The texts, compiled. */
+    readonly texts: ReadonlyMap<string, Template>;
+    /** The phrases of the framework this file translates, compiled. */
+    readonly framework: ReadonlyMap<string, Template>;
+    /** The `commands` section, by the name of the command, not checked yet. */
+    readonly commands: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * A language, declared anywhere in `src/` with `language()`: `locale` says
+ * which one, `texts` what the bot says in it.
+ */
+export declare const languageDeclaration: Declaration<LoadedLanguage>;
+/** A language as the project loaded it, with where it is declared. */
+export interface LanguageEntry extends ExportSite {
+    readonly language: LoadedLanguage;
+}
+/**
+ * Puts the languages together: one default, which `t` is typed from and
+ * gives a text to the languages that do not have it, and every other
+ * language with texts the default has, the same placeholders included. A
+ * language that does not match is left out and reported on its file: the
+ * others still work. `null` when there is no language at all.
+ */
+export declare function assembleMessages(entries: readonly LanguageEntry[]): {
+    messages: LoadedMessages | null;
+    failed: FailedFile[];
+};
+/** A language, where it is declared. */
+export interface DeclaredLanguage extends ExportSite {
+    readonly locale: Locale;
+}
+/**
+ * The augmentation that types `t` from the files themselves: the editor
+ * reads every declaration of the default language directly, so the keys
+ * and placeholders follow every keystroke; the other languages take the
+ * texts they do not have from it. `languages` is every language declared,
+ * `defaultLocale` the one `t` is typed from (the first one when it is not
+ * known yet: `sync`, which runs nothing). Nothing when the project has no
+ * language.
+ */
+export declare function messagesDeclarations(languages: readonly DeclaredLanguage[], defaultLocale?: Locale): string;
+/**
+ * The augmentation that underlines a second default language in the
+ * editor: when more than one language says `default: true` (`defaults`,
+ * the ones that do, known once the files ran), `language()` refuses
+ * `default: true` for each of them, so they are both underlined and not
+ * only reported in the console. Nothing when at most one says it.
+ */
+export declare function languageDefaultsDeclaration(defaults: readonly Locale[]): string;
+/**
+ * The languages of a project, found without running its files: a text
+ * search for `language({ locale: '...' })` in the exports of each file.
+ * Approximate on purpose, for `sync`, which runs nothing: `dev` and
+ * `build` then write the exact ones. Returns the languages with the one
+ * that says `default: true`, when one does.
+ */
+export declare function scanLanguages(cwd: string): Promise<{
+    languages: DeclaredLanguage[];
+    defaultLocale?: Locale;
+}>;
+/** A command, and whether it has its own `description`. */
+export interface DeclaredCommand {
+    /** `'ping'`, `'mod ban'` */
+    readonly name: string;
+    /**
+     * Whether the command gives its own texts; `false` when it is not
+     * known, like before the files ran: the language files may then
+     * describe it.
+     */
+    readonly described: boolean;
+}
+/**
+ * The augmentation that offers the commands of the project in the
+ * `commands` of a language: the name of each command, `true` when the
+ * language files describe it and `false` when the command has its own
+ * `description`, so that the editor only offers the first ones. Both come
+ * from running the files (`dev` and `build` know them, `sync` does not and
+ * offers any name). Nothing when the project has no command.
+ */
+export declare function commandsDeclarations(commands: readonly DeclaredCommand[]): string;