chapterjs 0.1.1 → 0.1.4

package/dist/loader/hot.js

@@ -0,0 +1,85 @@
+// How Node loads the files of a project.
+//
+// Imports without extension: `import { greet } from '../lib/greet'` finds
+// `greet.ts` (or `greet/index.ts`), as people expect. Node alone asks for
+// the extension; writing it still works.
+//
+// Hot reload: Node keeps every imported module forever, by URL. Each reload
+// gets a new "generation" number, added to the URL of every file of the
+// project (and only of the project: packages keep their single copy). A
+// file and everything it imports from the project are then loaded again.
+import { registerHooks } from 'node:module';
+import { pathToFileURL } from 'node:url';
+const PARAM = 'chapter';
+let generation = 0;
+let root = null;
+let hot = false;
+/** What an import without extension may be, in the order it is tried. */
+const CANDIDATES = [
+    '.ts',
+    '.mts',
+    '.js',
+    '.mjs',
+    '/index.ts',
+    '/index.mts',
+    '/index.js',
+    '/index.mjs',
+];
+const EXTENSION = /\.(?:m?ts|m?js)$/;
+/**
+ * Takes over how the files under `dir` are loaded. Called once, before
+ * loading. With `reload`, `nextGeneration()` makes them load again.
+ */
+export function enableProjectLoader(dir, { reload }) {
+    if (root !== null)
+        throw new Error('The project loader is already enabled.');
+    root = pathToFileURL(dir).href.replace(/\/?$/, '/');
+    hot = reload;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const fromProject = root !== null &&
+                context.parentURL?.startsWith(root) === true &&
+                specifier.startsWith('.');
+            let result;
+            try {
+                result = nextResolve(specifier, context);
+            }
+            catch (error) {
+                if (!fromProject || EXTENSION.test(specifier))
+                    throw error;
+                // No extension: look for the file people mean.
+                for (const candidate of CANDIDATES) {
+                    try {
+                        result = nextResolve(specifier.replace(/\/$/, '') + candidate, context);
+                        break;
+                    }
+                    catch {
+                        // Try the next one.
+                    }
+                }
+                if (!result)
+                    throw error;
+            }
+            if (hot && root !== null && result.url.startsWith(root)) {
+                return {
+                    ...result,
+                    url: `${result.url.split('?')[0]}?${PARAM}=${generation}`,
+                };
+            }
+            return result;
+        },
+    });
+}
+/** Makes the next imports load the files again. */
+export function nextGeneration() {
+    generation++;
+}
+/** Imports a file of the project, in its current version. */
+export function importFile(path) {
+    const url = pathToFileURL(path).href;
+    return import(hot ? `${url}?${PARAM}=${generation}` : url);
+}
+/** Removes what hot reload adds to the paths shown in errors. */
+export function cleanPath(text) {
+    return text.replace(new RegExp(`\\?${PARAM}=\\d+`, 'g'), '');
+}

package/dist/loader/loader.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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;
+    /**
+     * The convention is one file, `src/<folder>.ts`, not a folder. `check`
+     * and `read` receive its name with its extension (`presence.ts`).
+     */
+    single?: boolean;
+    /** What one file is called in messages: "event", "command"... */
+    one: string;
+    many: string;
+    /**
+     * 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.
+     */
+    check?(path: string): void;
+    /**
+     * Checks what a file exports and returns what the feature needs from it.
+     * Throws an error whose message says what the file should export.
+     */
+    read(exports: Record<string, unknown>, path: string): T;
+}
+export interface LoadedFile<T> {
+    /** The path from the project folder, with `/`: `src/events/ping.ts`. */
+    file: string;
+    value: T;
+}
+export interface FailedFile {
+    file: string;
+    error: unknown;
+}
+export interface LoadResult<T> {
+    loaded: LoadedFile<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. */
+export interface FoundFile {
+    /** The path from the project folder, with `/`: `src/events/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`. */
+    file: string;
+    exports: Record<string, unknown>;
+}
+/**
+ * Reads the files of a conventional folder from a build, which ran them
+ * all at once: nothing is scanned and nothing is imported.
+ */
+export declare function loadBuilt<T>(convention: Convention<T>, built: readonly BuiltFile[]): Promise<LoadResult<T>>;

package/dist/loader/loader.js

@@ -0,0 +1,135 @@
+// 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.
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { importFile } from './hot.js';
+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('/');
+}
+/** 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) {
+        // 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)) {
+            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));
+    return paths
+        .map(path => ({
+        file: relative(projectDir, path).split(sep).join('/'),
+        path,
+    }))
+        .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) => {
+        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 });
+        }
+        catch (error) {
+            result.failed.push({ file, error });
+        }
+    }));
+    const byFile = (a, b) => a.file < b.file ? -1 : 1;
+    result.loaded.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)));
+}
+/**
+ * Reads the files of a conventional folder from a build, which ran them
+ * all at once: nothing is scanned and nothing is imported.
+ */
+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)));
+}

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,3 @@
+export * from './index.js';
+export { event } from './events/event.js';
+export { asset } from './assets/asset.js';

package/dist/main.js

@@ -0,0 +1,6 @@
+// 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.
+export * from './index.js';
+export { event } from './events/event.js';
+export { asset } from './assets/asset.js';

package/dist/messages/commands.d.ts

@@ -0,0 +1,23 @@
+import { type LoadedCommand } from '../commands/convention.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/`. */
+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. */
+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,123 @@
+// 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
+// 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 { commandName } from '../commands/tree.js';
+/** The paths the languages translate that no command file 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) ?? 'src/messages/en-US.ts';
+/**
+ * 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)}`),
+            });
+        }
+    }
+    const main = messages ? given.get(messages.default) : undefined;
+    const description = main?.descriptions[messages.default];
+    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 ||
+            main?.optionLocales[option.name]?.descriptions[messages.default];
+        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 === messages.default)
+            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/convention.d.ts

@@ -0,0 +1,89 @@
+import type { Locale } from '../discord/types/common.js';
+import type { TypedFolder } from '../loader/generated.js';
+import { type Convention, type FailedFile, type FoundFile } from '../loader/loader.js';
+import { type LoadedMessages, type Template } from './translate.js';
+/** A language file, checked: what the languages are assembled from. */
+export interface LoadedLanguage {
+    /** The language, from the name of the file. */
+    readonly locale: Locale;
+    /** Whether the file 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 path of the command file, not checked yet. */
+    readonly commands: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * `src/messages/`: one file per language. Each file exports by default
+ * what `language()` returns:
+ *
+ * ```ts
+ * // src/messages/fr.ts
+ * import { language } from 'chapterjs';
+ *
+ * export default language({ texts: { pong: 'Pong !' } });
+ * ```
+ */
+export declare const languagesConvention: Convention<LoadedLanguage>;
+/** A language file as the project loaded it. */
+export interface LanguageEntry {
+    readonly file: string;
+    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[];
+};
+/**
+ * The augmentation that types `t` from the files themselves: the editor
+ * reads the default language of `src/messages/` directly, so the keys
+ * and placeholders follow every keystroke; the other languages take the
+ * texts they do not have from it. Which file is the default is known
+ * once the files ran (`defaultFile`, from the loaded messages): until
+ * then (`sync`), the first file is taken. Nothing when the folder has no
+ * language.
+ */
+export declare function messagesDeclarations(files: readonly FoundFile[], defaultFile?: string): string;
+/**
+ * One typed folder per language file: in `src/messages/fr.ts`, the
+ * `language()` imported from 'chapterjs' knows the other files. When
+ * another one says `default: true` (`defaults`, the files that do, known
+ * once they ran: `dev` and `build` give them, `sync` runs nothing), it
+ * refuses `default: true`, naming that file: a second default language is
+ * underlined in the editor, and no longer only reported in the console.
+ * Each project takes `main` (the commands a language file may translate)
+ * and not `shared`, which types `t` from the default file: a language file
+ * checked with the `language()` of another would be a false error.
+ */
+export declare function languageTypedFolders(files: readonly FoundFile[], defaults?: readonly string[]): TypedFolder[];
+/** A command file, and whether it has its own `description`. */
+export interface DeclaredCommand {
+    /** `src/commands/(mod)/mod/ban.ts` */
+    readonly file: string;
+    /**
+     * Whether the file gives its own texts; `false` when it is not known,
+     * like before the file 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 file: the path of each command file, `true`
+ * when the language files describe it and `false` when the file has its
+ * own `description`, so that the editor only offers the first ones. The
+ * path comes from the file name; whether it is described comes from
+ * running the file (`dev` and `build` know it, `sync` does not). The
+ * command files themselves are never referred to: their `t` is typed from
+ * the languages, which would be a circle. Nothing when the project has no
+ * command.
+ */
+export declare function commandsDeclarations(commands: readonly DeclaredCommand[]): string;