@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/mithaq/define.d.ts

@@ -0,0 +1,335 @@
+import { type FieldList, type RowFieldWhere } from './rows.ts';
+import type { Ref } from './user.ts';
+import { defaultGlobalOperations, defaultOperations, type ContextOf, type DefaultLists, type OperationDeclaration, type SchemasOf } from '../asas/runner/steps.ts';
+import { defaultFields, defaultGlobalFields } from '../base/fields.ts';
+import { draftFields, versionOperations } from '../versions/versions.ts';
+import type { KayanVersions } from '../versions/index.ts';
+import type { DerivedInput, OperationParsed } from '../asas/runner/write.ts';
+import type { Language } from './language.ts';
+import type { ActorBoundAccess, Access, Field, FieldOf, Indexes, KayanService, KindValue, LocalesOf, MessageTree, RuntimeField, ServiceOf } from './types.ts';
+import type { AuthStrategy } from '../asas/actor.ts';
+import type { KayanConfigOf } from './rukn.ts';
+type KayanAuthOf<Targets> = AuthStrategy | {
+    provider: 'local';
+    options: unknown;
+} | {
+    provider: 'better-auth';
+    server: (targets: Targets, vocabulary: {
+        catalog: readonly string[];
+        statements: Readonly<Record<string, readonly string[]>>;
+        referenced: (id: string) => Promise<number>;
+    }) => unknown;
+};
+type StrayLocales<Copy, Locale extends string> = {
+    [Stray in Exclude<keyof Copy, Locale>]: never;
+};
+type StrayMessages<Copy, Locale extends string> = Copy extends Readonly<Record<string, string>> ? StrayLocales<Copy, Locale> : {
+    [Key in keyof Copy]: StrayMessages<Copy[Key], Locale>;
+};
+type StrayDescription<F, Locale extends string> = F extends {
+    description: infer Copy;
+} ? {
+    description: StrayLocales<Copy, Locale>;
+} : unknown;
+type StrayPlaceholder<F, Locale extends string> = F extends {
+    placeholder: infer Copy;
+} ? {
+    placeholder: StrayLocales<Copy, Locale>;
+} : unknown;
+type KayanTargetsOf<L extends Language, Fields extends Record<string, unknown>, Service extends {
+    service?: unknown;
+} = {
+    service?: KayanService;
+}> = {
+    [Name in Exclude<keyof L['targets'], 'service'>]?: L['targets'][Name] extends {
+        capability: 'tenant';
+    } ? never : KayanConfigOf<L, Fields, L['targets'][Name]>;
+} & Service;
+/** The language's tenant target, which is under the key `tenant` alone, or `never`. */
+type TenantOf<L extends Language> = L['targets'] extends {
+    tenant: infer T extends {
+        capability: 'tenant';
+        relationTo: string;
+        field: {
+            rules: object;
+        };
+    };
+} ? T : never;
+type TenantBinding<L extends Language, F> = F extends {
+    targets: {
+        tenant: unknown;
+    };
+} ? [TenantOf<L>] extends [never] ? {
+    targets: {
+        tenant: never;
+    };
+} : {
+    kind: 'relationship';
+    relationTo: TenantOf<L>['relationTo'] | (() => {
+        name: TenantOf<L>['relationTo'];
+    });
+    hasMany?: never;
+    rules?: {
+        required?: true;
+        index?: true;
+        providedBy?: {
+            readonly create: 'application';
+            readonly update: 'never';
+        };
+        onDelete?: 'restrict';
+        defaultValue?: never;
+    };
+    targets: {
+        tenant: true;
+    } & {
+        [Name in StoreKeys<L['targets']> | SchemaKeys<L['targets']>]?: never;
+    };
+} : unknown;
+type TenantKey<Fields> = {
+    [N in keyof Fields]: Fields[N] extends {
+        targets: {
+            tenant: true;
+        };
+    } ? N : never;
+}[keyof Fields] & string;
+type TenantDefaulted<L extends Language, Fields> = true extends {
+    [N in keyof Fields]: Fields[N] extends {
+        targets: {
+            tenant: true;
+        };
+    } ? true : never;
+}[keyof Fields] ? {
+    [N in keyof Fields]: Fields[N] extends {
+        targets: {
+            tenant: true;
+        };
+    } ? Fields[N] & {
+        rules: TenantOf<L>['field']['rules'];
+    } : Fields[N];
+} : Fields;
+type OperationOf<L extends Language, Fields extends Record<string, RuntimeField>, Data extends Record<string, unknown> = Record<string, unknown>> = [ServiceOf<L>] extends [never] ? never : OperationDeclaration<DefaultLists, SchemasOf<L, Fields>, LocalesOf<L>, FieldOf<L>, Data, ContextOf<ServiceOf<L>>>;
+type DataOf<L extends Language, Fields extends Record<string, RuntimeField>, Operation> = OperationParsed<Operation, DerivedInput<Operation, Fields, L, []>> extends infer Data ? Data extends Record<string, unknown> ? Data : Record<string, unknown> : Record<string, unknown>;
+type StoreKeys<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        capability: 'store';
+    } ? Name : never;
+}[keyof Targets] & string;
+type SchemaKeys<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        capability: 'screen' | 'service' | 'storage' | 'store' | 'tenant' | 'versions';
+    } ? never : Name;
+}[keyof Targets] & string;
+type NamedStore<Name> = [Name] extends [undefined] ? {
+    store?: undefined;
+} : {
+    store: Name;
+};
+type NamedSchema<Name> = [Name] extends [undefined] ? {
+    schema?: undefined;
+} : {
+    schema: Name;
+};
+type CheckedFields<L extends Language, Fields extends Record<string, FieldOf<L>>> = Fields & {
+    [N in keyof Fields]: {
+        [Key in Exclude<keyof Fields[N], keyof Field<string, L['rules']>>]: never;
+    } & StrayLocales<Fields[N]['label'], LocalesOf<L>> & StrayDescription<Fields[N], LocalesOf<L>> & StrayPlaceholder<Fields[N], LocalesOf<L>> & TenantBinding<L, Fields[N]>;
+};
+type AnyFunction = (...args: never) => unknown;
+/**
+ * `operations` written as data `O`, or as a function of the defaults whose result is `R`. The two
+ * are told apart by `O` having no keys, never by a union: under a union TypeScript stops checking a
+ * written object for excess properties, and a misspelled key would pass. A stray key in a returned
+ * object, which no excess check reaches, is refused by name.
+ */
+type DeclaredOperations<L extends Language, Fields extends Record<string, RuntimeField>, O, R, Defaults> = O & ([keyof O] extends [never] ? ((args: {
+    defaults: Defaults;
+}) => R & NoInfer<Record<string, OperationOf<L, Fields, never>> & {
+    [Name in keyof R]: OperationOf<L, Fields, DataOf<L, Fields, R[Name]>> & {
+        [Key in Exclude<keyof R[Name], keyof OperationOf<L, Fields, never>>]?: never;
+    };
+}>) | NoInfer<Record<string, OperationOf<L, Fields, never>>> : NoInfer<Record<string, OperationOf<L, Fields, never>>> & NoInfer<{
+    [Name in keyof O]: OperationOf<L, Fields, DataOf<L, Fields, O[Name]>>;
+}>);
+/** The operations a kayan declared, whichever way it wrote them. */
+type OperationsOf<O, R> = [keyof O] extends [never] ? ([O] extends [AnyFunction] ? R : O) : O;
+/** Data, or a function of what the language offers that returns it, run once where the kayan is declared. */
+type OverDefaults<Declared, Defaults> = Declared | ((args: {
+    defaults: Defaults;
+}) => Declared);
+/** The name of the language's versions target, which a kayan keeps versions through by writing an entry under it. */
+type VersionsKey<L extends Language> = {
+    [Name in keyof L['targets']]: L['targets'][Name] extends {
+        capability: 'versions';
+    } ? Name : never;
+}[keyof L['targets']];
+/** What `fields: ({ defaults }) => ...` is handed: the id and timestamps, and the status field of a kayan that keeps drafts. */
+type FieldDefaults<Kept> = typeof defaultFields & (Kept extends {
+    readonly drafts: true | object;
+} ? typeof draftFields : unknown);
+/** What `operations: ({ defaults }) => ...` is handed: the shipped operations, and the version ones of a kayan that keeps versions. */
+type OperationDefaults<Kept> = typeof defaultOperations & ([Kept] extends [undefined] ? unknown : typeof versionOperations);
+type Paths<Fields> = Extract<keyof Fields, string> | {
+    [Name in Extract<keyof Fields, string>]: Fields[Name] extends {
+        relationTo: () => {
+            fields: infer Target;
+        };
+    } ? `${Name}.${Extract<keyof Target, string>}` : Fields[Name] extends {
+        relationTo: string;
+    } ? `${Name}.${string}` : never;
+}[Extract<keyof Fields, string>];
+type FieldValue<F, L extends Language> = F extends {
+    kind: infer Name extends keyof L['kinds'];
+} ? L['kinds'][Name] extends {
+    pointsAtRow: true;
+} ? unknown : KindValue<L['kinds'][Name]> : unknown;
+type CheckedOperand<Operator, Operand, Value> = Operand extends Ref ? Operand extends (Operator extends 'in' | 'not_in' ? Ref<readonly Value[]> : Ref<Value>) ? Operand : never : Operand;
+/** Every key of a row's `Where` is a path of this kayan, or it is `never`. */
+type CheckedWhere<W, Path extends string, Fields, L extends Language> = {
+    [Key in keyof W]: Key extends 'and' | 'or' ? W[Key] extends infer List extends readonly unknown[] ? {
+        [At in keyof List]: CheckedWhere<List[At], Path, Fields, L>;
+    } : never : Key extends Path ? W[Key] extends RowFieldWhere ? {
+        [Operator in keyof W[Key]]: CheckedOperand<Operator, W[Key][Operator], Key extends keyof Fields ? FieldValue<Fields[Key], L> : unknown>;
+    } : never : never;
+};
+type CheckedAnswer<Answer, Path extends string, Fields, L extends Language> = Answer extends boolean ? Answer : CheckedWhere<Answer, Path, Fields, L>;
+type CheckedRow<Row, Path extends string, Name extends string, Fields, L extends Language> = {
+    [Key in keyof Row]: Key extends 'fields' ? Row[Key] extends readonly FieldList<Name>[] ? Row[Key] : never : Key extends 'permissions' ? Row[Key] extends '*' | readonly string[] ? Row[Key] : never : Key extends 'create' | 'delete' | 'read' | 'update' ? CheckedAnswer<Row[Key], Path, Fields, L> : never;
+};
+type CheckedRows<AccessDef, Fields, L extends Language> = AccessDef extends {
+    rows: infer Table;
+} ? {
+    rows: {
+        [Role in keyof Table]: CheckedRow<Table[Role], Paths<Fields>, Extract<keyof Fields, string>, Fields, L>;
+    };
+} : unknown;
+/** Bound to one language, so a kayan is checked against that language's kinds. */
+export declare const defineKayan: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> | AnyFunction = Record<never, never>, const AccessDef extends ({
+    create?: Access;
+    read?: Access;
+    update?: Access;
+    delete?: Access;
+    tenant?: false;
+} | (ActorBoundAccess<unknown> & {
+    create?: unknown;
+    read?: unknown;
+    update?: unknown;
+    delete?: unknown;
+})) = {
+    create?: Access;
+    read?: Access;
+    update?: Access;
+    delete?: Access;
+}, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const Auth extends KayanAuthOf<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined, const Kept extends KayanVersions | undefined = undefined, const R = Record<never, never>>(kayan: {
+    name: Name;
+    /** The provider that authenticates this kayan: `betterAuth({ server })`, `local({ secret })`, or a strategy. */
+    auth?: Auth;
+    /**
+     * The fields, in column order: `{ ...defaultFields, title }`, or `({ defaults }) => ({ ...defaults, title })`.
+     * TypeScript types a callback beside them that reads the fields, such as an operation's `input`
+     * over the derived shapes, before it reads what the function returns, so such a kayan writes them as an object.
+     */
+    fields: OverDefaults<CheckedFields<L, Fields>, FieldDefaults<Kept>>;
+    /** This kayan's own copy, nested by the parts of each key. A key a field's own `label` also claims is a collision. */
+    messages?: Messages & { [Key in keyof Messages]: StrayMessages<Messages[Key], LocalesOf<L>>; };
+    /** Where `mithaq generate messages` writes this kayan's file, if not the default. */
+    out?: string;
+    /** What each target of this build says about this kayan, by the target's name: `{ drizzle: pgTable(...) }`, `targets.<screen>`, `targets.service`. */
+    targets?: KayanTargetsOf<L, Fields, {
+        service?: {
+            /** Every operation this kayan answers, and nothing else: `{ ...defaultOperations, archive }`, or `({ defaults }) => ({ ...defaults, archive })`. */
+            operations?: DeclaredOperations<L, Fields, O, R, OperationDefaults<Kept>>;
+            /** The store this kayan is written through. One of the language's targets. */
+            store?: StoreName;
+            /** The target a write is validated against. One of the language's targets. */
+            schema?: SchemaName;
+        };
+    }> & { [Name_1 in VersionsKey<L>]?: Kept; };
+    /** This kayan's own open bag, for the project's own code. Nothing in mithaq reads it, and it stays on the server. */
+    custom?: Record<string, unknown>;
+    access?: AccessDef & CheckedRows<AccessDef, Fields, L>;
+    /** The table name. Defaults to the name. */
+    dbName?: DbName;
+    /** The Postgres schema this kayan's tables are built in. No key, or `'public'`, is `public`. */
+    schemaName?: string;
+    /**
+     * Indexes over this kayan's own columns, each over the fields it names, in order, and unique where it says so.
+     * A list is built beside the defaults; `({ defaults }) => [...]` answers the whole list. A group,
+     * `{ within: 'organization', unique: ['code'] }`, is indexes led by the tenant field.
+     */
+    indexes?: Indexes<NoInfer<keyof Fields & string>, NoInfer<TenantKey<Fields>>>;
+}) => {
+    name: Name;
+    auth?: Auth;
+    access?: AccessDef;
+    dbName?: DbName;
+    schemaName?: string;
+    indexes?: Indexes<keyof Fields & string, TenantKey<Fields>>;
+    messages?: Messages;
+    out?: string;
+    targets: KayanTargetsOf<L, Fields, {
+        service: {
+            operations: NoInfer<OperationsOf<O, R>>;
+        } & NamedStore<StoreName> & NamedSchema<SchemaName>;
+    }>;
+    custom?: Record<string, unknown>;
+    fields: TenantDefaulted<L, Fields>;
+    /** The language this kayan was declared in, on the type alone, so `tools.of(kayan)` types a call from it. */
+    readonly '~language'?: L;
+};
+/** The language a kayan's `'~language'` brand names, and the open language on one that carries none. */
+export type LanguageOf<K> = K extends {
+    readonly '~language'?: infer L extends Language;
+} ? L : Language;
+/** A global's access: read and update, and no more. */
+type GlobalAccess = {
+    read?: Access;
+    update?: Access;
+};
+/**
+ * Declares a global, a kayan of one row. It spreads `defaultGlobalFields` and runs
+ * `defaultGlobalOperations`; a tenant field makes it one row per tenant.
+ */
+export declare const defineGlobal: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> | AnyFunction = Record<never, never>, const AccessDef extends GlobalAccess = Record<never, never>, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined, const R = Record<never, never>>(global: {
+    name: Name;
+    /** The fields, in column order: `{ ...defaultFields, ...defaultGlobalFields, siteTitle }`, or `({ defaults }) => ({ ...defaults, siteTitle })`. */
+    fields: OverDefaults<CheckedFields<L, Fields>, typeof defaultFields & typeof defaultGlobalFields>;
+    /** This global's own copy, nested by the parts of each key, as on any kayan. */
+    messages?: Messages & { [Key in keyof Messages]: StrayMessages<Messages[Key], LocalesOf<L>>; };
+    /** Where `mithaq generate messages` writes this global's file, if not the default. */
+    out?: string;
+    /** What each target says about this global, exactly as on any kayan. */
+    targets?: KayanTargetsOf<L, Fields, {
+        service?: {
+            /** The two operations a global runs, `defaultGlobalOperations` or a list of the same names, or `({ defaults }) => defaults`. */
+            operations?: DeclaredOperations<L, Fields, O, R, typeof defaultGlobalOperations>;
+            /** The store this global is written through. One of the language's targets. */
+            store?: StoreName;
+            /** The target a write is validated against. One of the language's targets. */
+            schema?: SchemaName;
+        };
+    }>;
+    /** This global's own open bag, for the project's own code. Nothing in mithaq reads it, and it stays on the server. */
+    custom?: Record<string, unknown>;
+    /** Read and update only: a create or delete key is refused by the type. */
+    access?: AccessDef & { [Key in Exclude<keyof AccessDef, 'read' | 'update'>]: never; };
+    /** The table name. Defaults to the name. */
+    dbName?: DbName;
+    /** The Postgres schema this global's tables are built in. No key, or `'public'`, is `public`. */
+    schemaName?: string;
+}) => {
+    name: Name;
+    access?: AccessDef;
+    dbName?: DbName;
+    schemaName?: string;
+    single: true;
+    messages?: Messages;
+    out?: string;
+    targets: KayanTargetsOf<L, Fields, {
+        service: {
+            operations: NoInfer<OperationsOf<O, R>>;
+        } & NamedStore<StoreName> & NamedSchema<SchemaName>;
+    }>;
+    custom?: Record<string, unknown>;
+    fields: TenantDefaulted<L, Fields>;
+};
+export {};

package/dist/mithaq/define.js

@@ -0,0 +1,57 @@
+import { applyRows, rowFields, rowsOf } from './rows.js';
+import { isVersions, languageRows, serviceTargetOf, tenantDefaults } from './language.js';
+import { defaultGlobalOperations, defaultOperations, resolveOperations } from '../asas/runner/steps.js';
+import { defaultFields, defaultGlobalFields } from '../base/fields.js';
+import { draftFields, versionOperations } from '../versions/versions.js';
+const overDefaults = (declared, defaults) => typeof declared === 'function' ? declared({ defaults }) : declared;
+/** Bound to one language, so a kayan is checked against that language's kinds. */
+export const defineKayan = (language) => (kayan) => {
+    const versioning = Object.keys(language.targets).find((name) => isVersions(language.targets[name]));
+    const kept = versioning === undefined ? undefined : kayan.targets?.[versioning];
+    const declaredFields = overDefaults(kayan.fields, { ...defaultFields, ...(kept?.drafts && draftFields) });
+    // The key order is the column order but for the timestamps, which a new table puts last: nothing is merged in.
+    const fields = Object.fromEntries(Object.entries(declaredFields).map(([name, field]) => [name, tenantDefaults(language, field)]));
+    // A tenant-owned kayan inherits the language's rows; one opts out on its access.
+    const declared = kayan.access;
+    const owned = Object.values(fields).some((field) => field.targets?.tenant !== undefined);
+    const inherited = declared?.tenant === false || !owned ? undefined : languageRows(language);
+    const compiled = rowsOf(declared) ?? inherited;
+    if (compiled) {
+        for (const [name, field] of Object.entries(fields)) {
+            // ANDed with the row's answer, so it narrows and never widens. The kayan's name goes
+            // with it, since one compiled table is shared by every kayan that inherits it.
+            fields[name] = {
+                ...field,
+                access: rowFields({ compiled, name, declared: field.access, kayan: kayan.name }),
+            };
+        }
+    }
+    // A steps function runs once, here, so the kayan carries data a tool reads without calling anything.
+    const own = kayan.targets?.service;
+    const declaredOperations = overDefaults(own?.operations, { ...defaultOperations, ...(kept && versionOperations) });
+    const operations = resolveOperations(declaredOperations, serviceTargetOf(language));
+    return {
+        ...kayan,
+        ...(compiled ? { access: applyRows(compiled, declared) } : {}),
+        fields,
+        targets: { ...kayan.targets, service: { ...own, operations } },
+    };
+};
+/**
+ * Declares a global, a kayan of one row. It spreads `defaultGlobalFields` and runs
+ * `defaultGlobalOperations`; a tenant field makes it one row per tenant.
+ */
+export const defineGlobal = (language) => {
+    const kayan = defineKayan(language);
+    return (global) => {
+        const service = global.targets?.service;
+        const declared = {
+            ...global,
+            fields: overDefaults(global.fields, { ...defaultFields, ...defaultGlobalFields }),
+            targets: { ...global.targets, service: { ...service, operations: overDefaults(service?.operations, defaultGlobalOperations) } },
+        };
+        // `defineKayan`'s own access object, untouched: a rebuilt one would drop the rows
+        // marker, and the permission check would stand aside for every global operation.
+        return ({ ...kayan(declared), single: true });
+    };
+};

package/dist/mithaq/generate-messages.d.ts

@@ -0,0 +1,38 @@
+import type { MessageRegistry } from './messages.ts';
+/**
+ * What a run found: `changed`, the files a run writes, and the refusals, each naming what is wrong
+ * and where. `unverifiable`, the labels written as functions, is reported and never fails.
+ */
+export type MessagesReport = {
+    changed: string[];
+    missing: string[];
+    noSource: string[];
+    resolver: string[];
+    collisions: string[];
+    unverifiable: string[];
+    data: string[];
+};
+/**
+ * Writes one file per scope, and with `check` writes nothing and reports what a run would change and every gap:
+ * a missing locale, a key with no source or missing from the resolver, a key two scopes claim, and rows short of a locale.
+ */
+export declare const generateMessages: ({ registry, directory, check, root, rows, }: {
+    registry: MessageRegistry;
+    directory: URL;
+    check?: boolean;
+    /** The project's own root, which a scope's own `out` is resolved from. */
+    root?: URL;
+    /** Reads a page of one kayan's rows, for the data gap. Omitted, the scan is skipped. */
+    rows?: (entry: MessageRegistry['localized'][number]) => Promise<Record<string, unknown>[]>;
+}) => Promise<MessagesReport>;
+/** Everything a `--check` refuses, which is everything but the unverifiable list. */
+export declare const refusals: (report: MessagesReport) => string[];
+/**
+ * `mithaq generate messages`, from the project's root, answering its exit code. The data scan connects
+ * read-only, and a check that could not scan fails: rows short of a locale break every read of the kayan.
+ */
+export declare const run: ({ project, check, dataScan }: {
+    project: URL;
+    check: boolean;
+    dataScan?: boolean;
+}) => Promise<number>;

package/dist/mithaq/generate-messages.js

@@ -0,0 +1,235 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { Refusal } from './refusal.js';
+import { flattenMessageFile, nestMessageFile } from './message-file.js';
+const fileOf = (name, out, directory, root) => out ? new URL(out, root) : new URL(`${name}.json`, directory);
+// What is on disk wins: these files are the project's to translate, so a run adds a
+// missing key and keeps every translation when rewriting the file shape.
+const merge = (copy, current, locales) => {
+    if (typeof copy === 'function')
+        return null;
+    if (typeof copy === 'string')
+        return copy;
+    const held = current && typeof current === 'object' ? current : {};
+    // `??`, not `||`: a locale the project left empty is its answer, and is still reported missing.
+    return Object.fromEntries(locales.map((locale) => [locale, held[locale] ?? copy[locale] ?? '']));
+};
+/**
+ * Writes one file per scope, and with `check` writes nothing and reports what a run would change and every gap:
+ * a missing locale, a key with no source or missing from the resolver, a key two scopes claim, and rows short of a locale.
+ */
+export const generateMessages = async ({ registry, directory, check = false, root = directory, rows, }) => {
+    // With no locale every record would be `{}` and every gate would pass, dropping
+    // every string and reporting nothing.
+    if (!registry.locales.length) {
+        throw new Refusal('The language declares no locales, so `mithaq generate messages` has nothing to write a copy file against.');
+    }
+    // Two scopes resolving to one path would each report the other's keys as having no source.
+    const files = registry.scopes.map((scope) => fileOf(scope.name, scope.out, directory, root));
+    files.forEach((file, at) => {
+        // Compared ignoring case, because macOS's default volume puts `courses.json` into
+        // an existing `Courses.json`.
+        const first = files.findIndex((one) => one.href.toLowerCase() === file.href.toLowerCase());
+        if (first !== at) {
+            throw new Refusal(`Scopes "${registry.scopes[first].name}" and "${registry.scopes[at].name}" both write ${file.pathname}. Give one of them its own \`out\`.`);
+        }
+    });
+    // Read before any write, so a file that stops the run stops it before the first write.
+    const committed = [];
+    for (const file of files) {
+        // A file that is there and does not parse is refused, not read as `{}`: every
+        // translation in it would be rewritten with nothing reported.
+        const held = await readFile(file, 'utf8').catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        let parsed = {};
+        try {
+            if (held !== undefined)
+                parsed = JSON.parse(held);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Refusal(`${file.pathname} is not a copy file \`mithaq generate messages\` can read, and generating would overwrite it. Fix it or delete it.`);
+        }
+        committed.push(parsed);
+    }
+    const report = { changed: [], missing: [], noSource: [], resolver: [], collisions: [], unverifiable: [], data: [] };
+    for (const [key, claims] of Object.entries(registry.collisions)) {
+        report.collisions.push(`"${key}" is claimed by ${claims.join(' and ')}.`);
+    }
+    // Needs no database, so it is found here and not hidden by `--no-data-scan`.
+    for (const kayan of new Set(registry.localized.filter((entry) => !entry.sort).map((entry) => entry.kayan))) {
+        report.data.push(`Kayan "${kayan}" has no field the store can sort a page by, so its localized fields cannot be scanned. Give it one field that is not localized.`);
+    }
+    // `messagesOf` puts this scope first, so it is filled before any kayan's scope reads it.
+    let floor = {};
+    for (const [at, scope] of registry.scopes.entries()) {
+        const file = files[at];
+        const current = flattenMessageFile({ file: committed[at], locales: registry.locales });
+        const wanted = { ...current };
+        for (const key of Object.keys(current)) {
+            if (!Object.hasOwn(scope.keys, key))
+                report.noSource.push(`${scope.name}.${key} is an entry with no source. Delete it; a run keeps it.`);
+        }
+        if (scope.name === 'mithaq')
+            floor = wanted;
+        for (const key of Object.keys(scope.keys).sort()) {
+            const source = scope.seeds?.[key];
+            const from = source ? floor[source] : undefined;
+            let held = current[key];
+            // A locale still holding core's sentence is a seed rather than a person's, so a default
+            // changed in `mithaq.json` reaches every field that never said otherwise.
+            if (from && typeof from === 'object' && held && typeof held === 'object') {
+                const shipped = scope.keys[key];
+                held = Object.fromEntries(Object.entries(held).filter(([locale, value]) => value !== (shipped[locale] ?? '')));
+            }
+            const entry = merge(from && typeof from === 'object' ? from : scope.keys[key], held, registry.locales);
+            wanted[key] = entry;
+            if (entry === null) {
+                report.unverifiable.push(`${scope.name}.${key} is a function, so no locale of it can be verified.`);
+                continue;
+            }
+            if (typeof entry === 'string') {
+                report.unverifiable.push(`${scope.name}.${key} is one string the resolver returned, so no locale of it can be verified.`);
+                continue;
+            }
+            for (const locale of registry.locales) {
+                if (!entry[locale])
+                    report.missing.push(`${scope.name}.${key} has no "${locale}".`);
+            }
+        }
+        const source = `${JSON.stringify(nestMessageFile(wanted), null, 2)}\n`;
+        if (source === `${JSON.stringify(committed[at], null, 2)}\n`)
+            continue;
+        report.changed.push(scope.out ?? `${scope.name}.json`);
+        if (check)
+            continue;
+        // Per file: a scope's own `out` may name a directory no run has made yet.
+        await mkdir(new URL('.', file), { recursive: true });
+        await writeFile(file, source);
+    }
+    // The same refusal as the type error, for a build where a resolver reached this far short of a key.
+    if (registry.resolved) {
+        const shipped = registry.scopes.find((scope) => scope.name === 'mithaq');
+        const project = registry.scopes.find((scope) => scope.name === 'project');
+        for (const key of Object.keys(shipped.keys)) {
+            // A refusal sentence seeds every per-field key one locale at a time, which one opaque string cannot.
+            if (/^(rules\.|kinds\.[^.]+\.invalid$)/.test(key))
+                continue;
+            if (!(key in project.keys))
+                report.resolver.push(`The messages resolver returned no "${key}".`);
+        }
+    }
+    if (rows) {
+        for (const entry of registry.localized) {
+            // Already named above, once for the kayan rather than once for each of
+            // its localized fields, and there is no page to ask for without a sort.
+            if (!entry.sort)
+                continue;
+            for (const row of await rows(entry)) {
+                const value = row[entry.field];
+                if (!value || typeof value !== 'object')
+                    continue;
+                const held = Object.values(value);
+                if (held.some((one) => one === null) && held.some((one) => one !== null)) {
+                    report.data.push(`Kayan "${entry.kayan}" field "${entry.field}" holds a row written before a locale was added, so every read of that kayan fails. Backfill it.`);
+                    break;
+                }
+            }
+        }
+    }
+    return report;
+};
+/** Everything a `--check` refuses, which is everything but the unverifiable list. */
+export const refusals = (report) => [
+    ...report.collisions,
+    ...report.resolver,
+    ...report.missing,
+    ...report.noSource,
+    ...report.data,
+    ...report.changed.map((file) => `${file} is not what a run would write.`),
+];
+/**
+ * `mithaq generate messages`, from the project's root, answering its exit code. The data scan connects
+ * read-only, and a check that could not scan fails: rows short of a locale break every read of the kayan.
+ */
+export const run = async ({ project, check, dataScan = true }) => {
+    const { generate } = (await import(__rewriteRelativeImportExtension(new URL('src/mithaq.ts', project).href)));
+    const directory = new URL(generate?.messages ?? 'src/messages/', project);
+    const { asas } = (await import(__rewriteRelativeImportExtension(new URL('src/asas.ts', project).href)));
+    let rows;
+    /** Why the scan did not answer, which fails the check rather than shading it. */
+    let unscanned = '';
+    if (check && dataScan && asas.messages.localized.length) {
+        try {
+            // Read-only: a connect that pushed would apply a migration past its guards and seed the roles.
+            await asas.connect({ readOnly: true });
+            rows = async (entry) => {
+                try {
+                    return (await asas.targets[entry.store].find({
+                        kayan: entry.kayan,
+                        args: { limit: 0, page: 1, sort: { field: entry.sort, direction: 'asc' } },
+                    })).docs;
+                }
+                catch (error) {
+                    // The scan did not run, so the check cannot say the table is clean.
+                    unscanned = error.message;
+                    return [];
+                }
+            };
+        }
+        catch (error) {
+            unscanned = error.message;
+        }
+    }
+    // In a `finally`: a refusal is a throw, and one escaping it would leave the connection open.
+    let report;
+    try {
+        report = await generateMessages({ registry: asas.messages, directory, check, root: project, rows });
+    }
+    finally {
+        // `try`/`catch`: a synchronous throw from `destroy` returns nothing to attach a `.catch()` to.
+        try {
+            await asas.destroy();
+        }
+        catch {
+            // Nothing was connected, which is the ordinary path.
+        }
+    }
+    for (const line of report.unverifiable)
+        console.log(`Unverifiable: ${line}`);
+    if (check && !dataScan && asas.messages.localized.length) {
+        console.log('The data scan was skipped: --no-data-scan.');
+    }
+    const refused = refusals(report);
+    if (!check)
+        for (const line of report.noSource)
+            console.log(line);
+    if (check && (refused.length || unscanned)) {
+        for (const line of refused)
+            console.error(line);
+        // Only a file a run would rewrite: a run leaves an empty locale, a
+        // collision, a resolver gap and a data gap exactly as they are.
+        if (report.changed.length)
+            console.error('Run `mithaq generate messages`.');
+        // Its own line: it is no gap in the copy, but the one a diff cannot show went unmeasured.
+        if (unscanned) {
+            console.error(`The data scan did not run: ${unscanned}`);
+            console.error('Run it against the database, or pass `--no-data-scan` on a project that has none.');
+        }
+        return 1;
+    }
+    console.log(report.changed.length ? `Wrote ${report.changed.sort().join(', ')}.` : 'Messages are up to date.');
+    return 0;
+};