chapterjs 0.1.4 → 0.2.0

package/dist/loader/loader.d.ts

@@ -1,72 +1,85 @@
-/**
- * A folder of the project whose files the framework loads, or one file at
- * the root of `src/`.
- */
-export interface Convention<T> {
-    /**
-     * The folder, inside `src/`. With `single`, the name of the one file
-     * instead: `'presence'` is `src/presence.ts`.
-     */
-    folder: string;
+/** 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 convention is one file, `src/<folder>.ts`, not a folder. `check`
-     * and `read` receive its name with its extension (`presence.ts`).
+     * 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.
      */
-    single?: boolean;
-    /** What one file is called in messages: "event", "command"... */
+    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;
     /**
-     * Checks where a file is, before it is run. `path` is its path inside
-     * the folder, with `/`, without the `(group)` folders (see below). Throws
-     * an error whose message says where the file should be.
+     * 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.
      */
-    check?(path: string): void;
+    list: boolean;
     /**
-     * Checks what a file exports and returns what the feature needs from it.
-     * Throws an error whose message says what the file should export.
+     * Checks a declaration and returns what the feature needs from it.
+     * Throws an error whose message says what to write.
      */
-    read(exports: Record<string, unknown>, path: string): T;
+    read(value: unknown, site: ExportSite): T;
 }
-export interface LoadedFile<T> {
-    /** The path from the project folder, with `/`: `src/events/ping.ts`. */
-    file: string;
+/** 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: LoadedFile<T>[];
+    loaded: LoadedItem<T>[];
     failed: FailedFile[];
-    /** Every file found, loaded or not. */
-    files: string[];
 }
-/** The path of a file as the feature reads it: without `(group)` folders. */
-export declare function logicalPath(inside: string): string;
-/** A file of a conventional folder, found but not run. */
+/** 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/events/ping.ts`. */
+    /** The path from the project folder, with `/`: `src/ping.ts`. */
     file: string;
     /** Where it is on disk. */
     path: string;
 }
-/**
- * The files of a conventional folder, in a stable order (or the one file
- * of a single-file convention, under every source extension it has).
- */
-export declare function listFolder(projectDir: string, convention: Pick<Convention<unknown>, 'folder' | 'single'>): Promise<FoundFile[]>;
-/** Loads every file of a conventional folder. A broken file never throws. */
-export declare function loadFolder<T>(projectDir: string, convention: Convention<T>): Promise<LoadResult<T>>;
-/** A file of the project as a build kept it: already run. */
-export interface BuiltFile {
-    /** The path it had in the project: `src/events/ping.ts`. */
+/** 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 files of a conventional folder from a build, which ran them
- * all at once: nothing is scanned and nothing is imported.
+ * 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 loadBuilt<T>(convention: Convention<T>, built: readonly BuiltFile[]): Promise<LoadResult<T>>;
+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

@@ -1,28 +1,20 @@
-// Loads the files users drop in the conventional folders of their project.
-// One mechanism for every folder: a feature only says which folder it owns
-// and how to read what a file exports.
+// 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$/;
-/**
- * How users organise a conventional folder without changing what it means,
- * the same in every feature:
- * - a file or a folder whose name starts with `_` is private: never
- *   loaded by the framework, free to hold shared code;
- * - a folder whose name is in parentheses, like `(moderation)`, only groups
- *   files: it is not part of what the path says, at any depth.
- */
-const PRIVATE = /^_/;
-const GROUP = /^\(.*\)$/;
-/** The path of a file as the feature reads it: without `(group)` folders. */
-export function logicalPath(inside) {
-    const parts = inside.split('/');
-    return parts
-        .filter((part, index) => index === parts.length - 1 || !GROUP.test(part))
-        .join('/');
-}
+/** 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;
@@ -30,57 +22,26 @@ async function scan(dir) {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        // A folder the project does not have is a feature it does not use.
         if (error.code === 'ENOENT')
             return [];
         throw error;
     }
     const files = [];
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
-        if (PRIVATE.test(entry.name))
-            continue;
         const path = join(dir, entry.name);
         if (entry.isDirectory())
             files.push(...(await scan(path)));
-        else if (SOURCE.test(entry.name) && !DECLARATION.test(entry.name)) {
+        else if (SOURCE.test(entry.name) &&
+            !DECLARATION.test(entry.name) &&
+            !TEST.test(entry.name)) {
             files.push(path);
         }
     }
     return files;
 }
-/** Whether a path of the project is the file of a single-file convention. */
-function isSingle(file, folder) {
-    return (file.startsWith(`src/${folder}.`) &&
-        SOURCE.test(file) &&
-        !DECLARATION.test(file) &&
-        !file.slice(`src/${folder}.`.length).includes('/'));
-}
-/** The one file of a single-file convention, with any source extension. */
-async function scanSingle(dir, name) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    return entries
-        .filter(entry => entry.isFile() &&
-        entry.name.startsWith(`${name}.`) &&
-        SOURCE.test(entry.name) &&
-        !DECLARATION.test(entry.name))
-        .map(entry => join(dir, entry.name));
-}
-/**
- * The files of a conventional folder, in a stable order (or the one file
- * of a single-file convention, under every source extension it has).
- */
-export async function listFolder(projectDir, convention) {
-    const paths = convention.single
-        ? await scanSingle(join(projectDir, 'src'), convention.folder)
-        : await scan(join(projectDir, 'src', convention.folder));
+/** 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('/'),
@@ -88,48 +49,71 @@ export async function listFolder(projectDir, convention) {
     }))
         .sort((a, b) => (a.file < b.file ? -1 : 1));
 }
-/**
- * Hands what files export to the convention of their folder. `exportsOf`
- * gives what a file exports (by running it, or from a build that already
- * did); a file that fails, there or in the convention, never throws.
- */
-async function readFiles(convention, files, exportsOf) {
-    const prefix = convention.single ? 'src/' : `src/${convention.folder}/`;
-    const result = { loaded: [], failed: [], files: [...files] };
-    await Promise.all(files.map(async (file) => {
+/** 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 {
-            const inside = logicalPath(file.slice(prefix.length));
-            // A misplaced file is not run at all.
-            convention.check?.(inside);
-            const value = convention.read(await exportsOf(file), inside);
-            result.loaded.push({ file, value });
+            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.loaded.sort(byFile);
+    result.modules.sort(byFile);
     result.failed.sort(byFile);
-    result.files.sort();
     return result;
 }
-/** Loads every file of a conventional folder. A broken file never throws. */
-export async function loadFolder(projectDir, convention) {
-    const found = await listFolder(projectDir, convention);
-    const paths = new Map(found.map(({ file, path }) => [file, path]));
-    return readFiles(convention, found.map(({ file }) => file), file => importFile(paths.get(file)));
-}
+/** The name of a file, without its folders and its extension. */
+const baseName = (file) => file
+    .split('/')
+    .pop()
+    .replace(/\.[^.]+$/, '');
 /**
- * Reads the files of a conventional folder from a build, which ran them
- * all at once: nothing is scanned and nothing is imported.
+ * 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 loadBuilt(convention, built) {
-    const prefix = `src/${convention.folder}/`;
-    const mine = new Map(built
-        .filter(({ file }) => convention.single
-        ? isSingle(file, convention.folder)
-        : file.startsWith(prefix))
-        .map(({ file, exports }) => [file, exports]));
-    return readFiles(convention, [...mine.keys()], file => Promise.resolve(mine.get(file)));
+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/main.d.ts

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

package/dist/main.js

@@ -1,6 +1,5 @@
 // What `import ... from 'chapterjs'` loads at runtime: the public API, plus
-// the functions whose type depends on where they are imported from. Their
-// types are not here but in the `.chapterjs/` folder of each project.
+// `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 { event } from './events/event.js';
 export { asset } from './assets/asset.js';

package/dist/messages/commands.d.ts

@@ -1,14 +1,14 @@
-import { type LoadedCommand } from '../commands/convention.js';
+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 languages of `src/messages/`. */
+/** 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 paths the languages translate that no command file has, by file. */
+/** The names the languages translate that no command has, by file. */
 export declare function unknownCommands(messages: LoadedMessages, known: ReadonlySet<string>): {
     file: string;
     path: string;

package/dist/messages/commands.js

@@ -1,11 +1,11 @@
-// The `commands` of the languages of `src/messages/`: what Discord shows of
-// each command in each language. A command has its texts in one place: in
+// 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/convention.js';
+import { checkLocales, } from '../commands/declaration.js';
 import { commandName } from '../commands/tree.js';
-/** The paths the languages translate that no command file has, by file. */
+/** 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) {
@@ -18,14 +18,14 @@ export function unknownCommands(messages, known) {
     return unknown;
 }
 /** Where the default language file is, or would be. */
-export const defaultLanguageFile = (messages) => messages?.files.get(messages.default) ?? 'src/messages/en-US.ts';
+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 path = command.path.join(' ');
     const name = commandName(command.path);
     const failed = [];
     const languages = [...(messages?.commands ?? [])].filter(([, section]) => path in section);
@@ -53,8 +53,25 @@ export function translateCommand(file, command, messages) {
             });
         }
     }
-    const main = messages ? given.get(messages.default) : undefined;
-    const description = main?.descriptions[messages.default];
+    // 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,
@@ -65,7 +82,9 @@ export function translateCommand(file, command, messages) {
     const options = [];
     for (const option of command.options) {
         const text = option.description ||
-            main?.optionLocales[option.name]?.descriptions[messages.default];
+            (mainLocale
+                ? main?.optionLocales[option.name]?.descriptions[mainLocale]
+                : undefined);
         if (!text) {
             failed.push({
                 file,
@@ -81,7 +100,7 @@ export function translateCommand(file, command, messages) {
     const descriptions = {};
     const optionLocales = {};
     for (const [locale, texts] of given) {
-        if (locale === messages.default)
+        if (locale === mainLocale)
             continue;
         const text = texts.names[locale];
         if (text !== undefined)

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;