react-cheminfo 0.22.0 → 0.24.0

package/src/structure/core/conformers.ts

@@ -0,0 +1,282 @@
+import type { Molecule } from 'openchemlib';
+
+import { ordinal } from '../../format/core/words.ts';
+
+import { minimiseConformer, rankByEnergy } from './conformerMinimise.ts';
+import { isKeptMinimum, minimisedShapes } from './conformerMinimum.ts';
+import type {
+  ConformerOptions,
+  MinimisationAlgorithm,
+} from './conformerOptions.ts';
+import type {
+  ConformerRefinement,
+  ConformerSetRefinement,
+} from './conformerRefine.ts';
+import type { ConformerSession } from './conformerSession.ts';
+import {
+  keepConformerSession,
+  openConformerSession,
+  readPotentialCount,
+} from './conformerSession.ts';
+import type { ConformerShape } from './conformerShape.ts';
+import { conformerShape, hasFiniteCoordinates } from './conformerShape.ts';
+import type { MolfileExport } from './molfileExport.ts';
+import { toMolfileExport } from './molfileExport.ts';
+
+export { strategyConstant } from './conformerSession.ts';
+
+/** One conformer of the input structure, ready to display and to export. */
+export interface Conformer {
+  /** 1-based position in {@link ConformerSet.conformers}. */
+  id: number;
+  /** The 3D structure, as a molfile the viewer can parse. */
+  molfile: MolfileExport;
+  /** Total force-field energy in kcal/mol, `null` when it was not computed. */
+  energy: number | null;
+  /** Energy above the lowest conformer of the set, `null` without an energy. */
+  relativeEnergy: number | null;
+  /**
+   * What a better method said about this conformer, once `refineConformers` has
+   * relaxed it. `null` until then, which is what a plain force-field run leaves.
+   * @default null
+   */
+  refinement: ConformerRefinement | null;
+}
+
+/**
+ * Which energies a set is ordered by: the force field's own, or the ones a
+ * refinement pass produced.
+ */
+export type ConformerRanking = 'force-field' | 'refined';
+
+/** Why {@link generateConformers} stopped asking for more conformers. */
+export type StopReason = 'exhausted' | 'count' | 'timeout';
+
+/** The complete outcome of one conformer run. */
+export interface ConformerSet {
+  /** The conformers kept, most stable first; one without an energy follows every one that has one. */
+  conformers: Conformer[];
+  /** OpenChemLib's estimate of the reachable conformers, `-1` when unavailable. */
+  potentialConformerCount: number;
+  /** Which of the three limits ended the run. */
+  stoppedBy: StopReason;
+  /** Wall-clock duration of the run, initialisation and continuations included. */
+  elapsedMilliseconds: number;
+  /** Plain sentences about conformers that were dropped or left unminimised. */
+  warnings: string[];
+  /** The force field that was asked for, echoed so a reader knows what the energies mean. */
+  minimisation: MinimisationAlgorithm;
+  /** Conformers the generator handed back, dropped ones included: where a continuation resumes. */
+  produced: number;
+  /** The options of the run, so a continuation draws from the same sequence. */
+  options: ConformerOptions;
+  /** Which of the two energies {@link ConformerSet.conformers} is ordered by. */
+  rankedBy: ConformerRanking;
+  /**
+   * What the refinement pass did, `null` for a set no better method has seen.
+   * @default null
+   */
+  refinement: ConformerSetRefinement | null;
+}
+
+/** The two options a continuation takes from the caller rather than from the run. */
+export type ConformerLimits = Pick<
+  ConformerOptions,
+  'maxConformers' | 'timeoutSeconds'
+>;
+
+/**
+ * Generate conformers of a structure, optionally relaxing each one with MMFF94.
+ *
+ * The caller's molecule is never touched: the run works on a compact copy that
+ * receives the explicit hydrogens the generator needs.
+ *
+ * The run ends on the first of three limits — the generator runs out of new
+ * torsion sets, `maxConformers` conformers are in hand, or the time budget is
+ * spent. **A timeout is not an error**: whatever was produced is returned, with
+ * `stoppedBy` saying why there is not more.
+ *
+ * The budget covers the whole call, initialisation included, and is read again
+ * once a conformer is in hand, so no further minimisation starts past the
+ * deadline. The one step already running cannot be cut short, so a caller
+ * waiting from another thread must allow one step on top of `timeoutSeconds`.
+ *
+ * Minimisation is best-effort: a conformer MMFF94 refuses is kept with a `null`
+ * energy and a warning rather than lost. A minimised conformer that lands in a
+ * minimum already kept, such as the flipped copy of a cyclohexane chair, is
+ * not kept a second time; the mirror image of a chiral minimum, such as the
+ * second gauche butane, is a minimum of its own.
+ * @param molecule - Structure to embed. Not mutated.
+ * @param options - Strategy, limits, seed and force field.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns Every conformer kept, most stable first, with relative energies and any warnings.
+ * @throws {Error} When the structure is empty or OpenChemLib refuses to initialise it.
+ */
+export function generateConformers(
+  molecule: Molecule,
+  options: ConformerOptions,
+  now: () => number = defaultClock,
+): ConformerSet {
+  return runConformers(molecule, options, null, now);
+}
+
+/**
+ * Ask the run that produced `previous` for more conformers.
+ *
+ * The continuation draws from the same seeded sequence with the same force
+ * field, so the result is the set a single larger run would have produced:
+ * the new conformers are ranked among the previous ones, the ids follow that
+ * order, and every relative energy is measured again from the lowest of all.
+ * A refined set cannot be extended: its molfiles hold the relaxed geometries
+ * while its `energy` fields still hold the force field's numbers, so the two
+ * would no longer describe one conformer and the duplicate check would compare
+ * shapes against energies that do not belong to them. Generate a larger set and
+ * refine that instead.
+ * @param molecule - The structure `previous` was generated from. Not mutated.
+ * @param previous - The set to extend. Not mutated.
+ * @param limits - How many more conformers to find, and the time budget of this call.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns The extended set, its duration the sum of both runs.
+ * @throws {Error} When the structure is empty, when `previous` has been refined,
+ * or when OpenChemLib refuses to initialise it.
+ */
+export function continueConformers(
+  molecule: Molecule,
+  previous: ConformerSet,
+  limits: ConformerLimits,
+  now: () => number = defaultClock,
+): ConformerSet {
+  const options: ConformerOptions = {
+    ...previous.options,
+    maxConformers: limits.maxConformers,
+    timeoutSeconds: limits.timeoutSeconds,
+  };
+  return runConformers(molecule, options, previous, now);
+}
+
+function defaultClock(): number {
+  return performance.now();
+}
+
+interface Accumulator {
+  conformers: Conformer[];
+  /** Shape of each conformer, `null` for one without an energy. */
+  shapes: Array<ConformerShape | null>;
+  warnings: string[];
+}
+
+function runConformers(
+  molecule: Molecule,
+  options: ConformerOptions,
+  previous: ConformerSet | null,
+  now: () => number,
+): ConformerSet {
+  if (previous?.refinement != null) {
+    throw new Error(
+      `This set was refined with ${previous.refinement.method}, so it cannot be extended. Generate a larger set, then refine it again.`,
+    );
+  }
+  const prepared = molecule.getCompactCopy();
+  prepared.addImplicitHydrogens();
+  if (prepared.getAllAtoms() === 0) {
+    throw new Error('The structure is empty: there is nothing to embed in 3D.');
+  }
+
+  // Setting up the torsion sets is the slow half of a flexible run — seconds on
+  // a long chain — so it is inside both the budget and the reported duration.
+  const start = now();
+  const session = openConformerSession(
+    prepared,
+    options,
+    previous?.produced ?? 0,
+  );
+  const potentialConformerCount =
+    previous?.potentialConformerCount ?? readPotentialCount(session);
+  const conformers =
+    previous === null ? [] : copyConformers(previous.conformers);
+  const into: Accumulator = {
+    conformers,
+    shapes: minimisedShapes(conformers),
+    warnings: previous === null ? [] : [...previous.warnings],
+  };
+  const budget = Math.max(options.timeoutSeconds * 1000, 0);
+  const stoppedBy = collect(
+    session,
+    options,
+    into.conformers.length + options.maxConformers,
+    () => now() - start >= budget,
+    into,
+  );
+  keepConformerSession(prepared, options, session);
+
+  return {
+    conformers: rankByEnergy(into.conformers),
+    potentialConformerCount,
+    stoppedBy,
+    elapsedMilliseconds: (previous?.elapsedMilliseconds ?? 0) + now() - start,
+    warnings: into.warnings,
+    minimisation: options.minimisation,
+    produced: session.produced,
+    options,
+    rankedBy: 'force-field',
+    refinement: null,
+  };
+}
+
+function collect(
+  session: ConformerSession,
+  options: ConformerOptions,
+  target: number,
+  spent: () => boolean,
+  into: Accumulator,
+): StopReason {
+  while (true) {
+    if (into.conformers.length >= target) return 'count';
+    if (spent()) return 'timeout';
+    const conformer =
+      session.pending ?? session.generator.getNextConformerAsMolecule();
+    session.pending = null;
+    if (conformer === null) return 'exhausted';
+    // Minimisation runs to completion once entered, so a conformer that arrives
+    // past the deadline is kept aside for a continuation rather than bought now.
+    if (spent()) {
+      session.pending = conformer;
+      return 'timeout';
+    }
+    session.produced++;
+    if (!hasFiniteCoordinates(conformer)) {
+      into.warnings.push(
+        `The ${ordinal(session.produced)} conformer produced was dropped: the generator placed some of its atoms at non-finite coordinates.`,
+      );
+      continue;
+    }
+    const energy = minimiseConformer(
+      conformer,
+      options,
+      session.produced,
+      into.warnings,
+    );
+    const shape = energy === null ? null : conformerShape(conformer);
+    if (
+      energy !== null &&
+      shape !== null &&
+      isKeptMinimum(energy, shape, into.conformers, into.shapes)
+    ) {
+      continue;
+    }
+    into.conformers.push({
+      id: into.conformers.length + 1,
+      molfile: toMolfileExport(conformer),
+      energy,
+      relativeEnergy: null,
+      refinement: null,
+    });
+    into.shapes.push(shape);
+  }
+}
+
+function copyConformers(conformers: readonly Conformer[]): Conformer[] {
+  const copies: Conformer[] = [];
+  for (const conformer of conformers) copies.push({ ...conformer });
+  return copies;
+}

package/src/structure/core/geometryRelaxer.ts

@@ -0,0 +1,71 @@
+/**
+ * A geometry a relaxer is handed: element symbols plus flat Cartesian
+ * coordinates in ångström, `x,y,z` per atom.
+ */
+export interface RelaxableGeometry {
+  /** Element symbol per atom, explicit hydrogens included. */
+  elements: string[];
+  /** Flat `x,y,z` per atom in ångström, length `3 · elements.length`. */
+  coordinates: Float64Array;
+}
+
+/** What a relaxer reports for one structure. */
+export interface RelaxedGeometry {
+  /**
+   * The relaxed coordinates, in the input's atom order. Translated freely;
+   * never rotated, which is what lets {@link RelaxedGeometry} be compared with
+   * the geometry it came from by removing both centroids.
+   */
+  coordinates: Float64Array;
+  /**
+   * Total energy at `coordinates`, **in kcal/mol**, so it can be read against a
+   * force-field energy without a second unit in the UI.
+   */
+  energy: number;
+  /**
+   * The dispersion term of `energy`, kcal/mol, or `null` from a method that has
+   * none. It is the part a force field of the MMFF94 era does not model at all,
+   * and a large part of why conformers re-rank.
+   * @default null
+   */
+  dispersionEnergy: number | null;
+  /** Optimizer cycles spent. `0` when there was nothing to relax. */
+  cycles: number;
+  /** Whether the optimizer met its convergence criteria. */
+  converged: boolean;
+  /** Plain sentences about anything the caller should know. */
+  warnings: string[];
+}
+
+/** How a relaxation run is watched and cancelled. */
+export interface RelaxerOptions {
+  /**
+   * Called as each structure finishes, so a caller can show progress over a
+   * batch that runs for seconds.
+   * @default undefined
+   */
+  onSettled?: (done: number, total: number) => void;
+  /**
+   * Gives the run up. A relaxer is not obliged to be able to interrupt a
+   * structure already in flight.
+   * @default undefined
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Something that relaxes geometries with a real electronic structure behind it,
+ * and reports the energy **at the geometry it returns**.
+ *
+ * This is the seam between a site and the semi-empirical engine: nothing in
+ * `react-cheminfo/core` imports one, so a site that never refines a geometry
+ * downloads no WebAssembly. `xtbRelaxer` from `react-cheminfo/xtb` is the
+ * implementation, GFN2-xTB through `xtb-wasm`.
+ *
+ * An implementation must return one result per request, in request order, and
+ * must keep each structure's atom order.
+ */
+export type GeometryRelaxer = (
+  geometries: readonly RelaxableGeometry[],
+  options?: RelaxerOptions,
+) => Promise<RelaxedGeometry[]>;

package/src/structure/core/index.ts

@@ -34,12 +34,25 @@ export type { IdCodeValue } from './editorValue.ts';
 export { isEmptyIdCode, splitEditorValue, splitIdCode } from './editorValue.ts';
 export type { FragmentQuery } from './fragmentQuery.ts';
 export { fragmentQuery, sameFragmentQuery } from './fragmentQuery.ts';
+export type {
+  GeometryRelaxer,
+  RelaxableGeometry,
+  RelaxedGeometry,
+  RelaxerOptions,
+} from './geometryRelaxer.ts';
+export {
+  centredRmsd,
+  readRelaxableGeometry,
+  writeRelaxedCoordinates,
+} from './moleculeCoordinates.ts';
 export type { MolfileClassification, MolfileVersion } from './molfile.ts';
 export {
   classifyMolfile,
   looksLikeMolfile,
   molfileAtomCount,
 } from './molfile.ts';
+export type { MolfileExport } from './molfileExport.ts';
+export { readMolfileExport, toMolfileExport } from './molfileExport.ts';
 export type { ReadStructureResult, StructureKind } from './readStructure.ts';
 export { looksLikeSmarts, readStructure } from './readStructure.ts';
 export type { StructureError } from './structureError.ts';

package/src/structure/core/moleculeCoordinates.ts

@@ -0,0 +1,93 @@
+import type { Molecule } from 'openchemlib';
+
+import type { RelaxableGeometry } from './geometryRelaxer.ts';
+
+/**
+ * Read the elements and 3D coordinates of a molecule into the flat form an
+ * engine takes.
+ * @param molecule - A molecule carrying 3D coordinates. Not modified.
+ * @returns Its geometry in ångström, one entry per atom of `getAllAtoms()`.
+ */
+export function readRelaxableGeometry(molecule: Molecule): RelaxableGeometry {
+  const atoms = molecule.getAllAtoms();
+  const elements = new Array<string>(atoms);
+  const coordinates = new Float64Array(atoms * 3);
+  for (let atom = 0; atom < atoms; atom++) {
+    elements[atom] = molecule.getAtomLabel(atom);
+    coordinates[atom * 3] = molecule.getAtomX(atom);
+    coordinates[atom * 3 + 1] = molecule.getAtomY(atom);
+    coordinates[atom * 3 + 2] = molecule.getAtomZ(atom);
+  }
+  return { elements, coordinates };
+}
+
+/**
+ * Write flat coordinates back onto a molecule, atom for atom.
+ * @param molecule - The molecule to move. Mutated.
+ * @param coordinates - Flat `x,y,z` per atom in ångström.
+ * @throws {Error} When there is not one position per atom.
+ */
+export function writeRelaxedCoordinates(
+  molecule: Molecule,
+  coordinates: Float64Array,
+): void {
+  const atoms = molecule.getAllAtoms();
+  if (coordinates.length !== atoms * 3) {
+    throw new Error(
+      `The relaxed geometry has ${coordinates.length / 3} positions for ${atoms} atoms.`,
+    );
+  }
+  for (let atom = 0; atom < atoms; atom++) {
+    molecule.setAtomX(atom, coordinates[atom * 3] as number);
+    molecule.setAtomY(atom, coordinates[atom * 3 + 1] as number);
+    molecule.setAtomZ(atom, coordinates[atom * 3 + 2] as number);
+  }
+}
+
+/**
+ * Root-mean-square displacement between two geometries of the same atoms, each
+ * taken about its own centroid, in ångström.
+ *
+ * Removing the centroids is what makes the number mean "how far the atoms
+ * moved" rather than "how far the molecule was translated": a relaxer is free
+ * to recentre a molecule, and the `GeometryRelaxer` contract forbids it to
+ * rotate one.
+ * @param before - Flat coordinates before.
+ * @param after - Flat coordinates after.
+ * @returns The RMSD in ångström, `0` for an empty geometry.
+ * @throws {Error} When the two do not hold the same number of atoms.
+ */
+export function centredRmsd(before: Float64Array, after: Float64Array): number {
+  if (before.length !== after.length) {
+    throw new Error(
+      `Cannot compare ${before.length / 3} positions with ${after.length / 3}.`,
+    );
+  }
+  const atoms = before.length / 3;
+  if (atoms === 0) return 0;
+  const centreBefore = centroid(before, atoms);
+  const centreAfter = centroid(after, atoms);
+  let total = 0;
+  for (let atom = 0; atom < atoms; atom++) {
+    for (let axis = 0; axis < 3; axis++) {
+      const gap =
+        (before[atom * 3 + axis] as number) -
+        (centreBefore[axis] as number) -
+        ((after[atom * 3 + axis] as number) - (centreAfter[axis] as number));
+      total += gap * gap;
+    }
+  }
+  return Math.sqrt(total / atoms);
+}
+
+function centroid(coordinates: Float64Array, atoms: number): Float64Array {
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  for (let atom = 0; atom < atoms; atom++) {
+    x += coordinates[atom * 3] as number;
+    y += coordinates[atom * 3 + 1] as number;
+    z += coordinates[atom * 3 + 2] as number;
+  }
+  return new Float64Array([x / atoms, y / atoms, z / atoms]);
+}

package/src/structure/core/molfileExport.ts

@@ -0,0 +1,62 @@
+import type { Molecule } from 'openchemlib';
+
+import { classifyMolfile } from './molfile.ts';
+
+/** A molfile plus the molstar format id that can actually parse it. */
+export interface MolfileExport {
+  /** molstar's format id: `mol` reads V2000, `sdf` reads V2000 and V3000. */
+  format: 'mol' | 'sdf';
+  /** The molfile text, exactly as OpenChemLib wrote it. */
+  data: string;
+}
+
+/**
+ * Serialise a molecule for the 3D viewer and for export.
+ *
+ * V2000 is written whenever it can be: its counts line holds three digits per
+ * field, so above 999 atoms OpenChemLib writes `?` where the count belongs and
+ * the file becomes unreadable. V3000 is used from that size on.
+ *
+ * Coordinates are emitted exactly as OpenChemLib writes them — the whole
+ * molecule is negated in y and z relative to `getAtomY/Z`, which is a rigid
+ * rotation and therefore invisible to the viewer, to the energies and to any
+ * other file consumer.
+ *
+ * Hydrogens are in the file only if they are explicit atoms, so call this on a
+ * conformer, which always carries them.
+ * @param molecule - Structure with 3D coordinates already set. Not mutated.
+ * @returns The molfile and the format id to hand molstar.
+ * @throws {Error} When the molfile carries no atoms.
+ */
+export function toMolfileExport(molecule: Molecule): MolfileExport {
+  const data =
+    molecule.getAllAtoms() > V2000_MAX_ATOMS
+      ? molecule.toMolfileV3()
+      : molecule.toMolfile();
+  return readMolfileExport(data);
+}
+
+/**
+ * Pick the molstar format id for a molfile of unknown version, and refuse the
+ * ones that would render nothing.
+ *
+ * molstar's `mol` parser does not understand a V3000 CTAB: it returns zero atoms
+ * with `isError: false`, so the viewer shows an empty scene and reports no
+ * error. The version is read from the text rather than assumed from whichever
+ * writer produced it, because the text is the only thing molstar itself looks
+ * at.
+ * @param data - A molfile, V2000 or V3000.
+ * @returns The format id paired with the unchanged text.
+ * @throws {Error} When the molfile carries no atoms — the silent failure this guards.
+ */
+export function readMolfileExport(data: string): MolfileExport {
+  const { version, atomCount } = classifyMolfile(data);
+  if (atomCount === 0) {
+    throw new Error(
+      'Molfile has an empty atom block: molstar would render an empty scene without reporting an error.',
+    );
+  }
+  return { format: version === 'v3000' ? 'sdf' : 'mol', data };
+}
+
+const V2000_MAX_ATOMS = 999;

package/src/structure/core/oclResources.ts

@@ -0,0 +1,41 @@
+import { Resources } from 'openchemlib';
+
+/**
+ * Register OpenChemLib's static resources once, without which
+ * `ConformerGenerator` and `ForceFieldMMFF94` throw on construction.
+ *
+ * Repeated calls share the first call's promise; a failed registration is
+ * forgotten so a later call can retry.
+ * @param url - Where to fetch `resources.json`. Omit under Node.js to read it
+ * from the installed package; in a browser or a worker it is required.
+ * @returns A promise that settles once the resources are usable.
+ */
+export function registerResources(url?: string): Promise<void> {
+  registration ??= register(url).catch((error: unknown) => {
+    registration = null;
+    throw error;
+  });
+  return registration;
+}
+
+let registration: Promise<void> | null = null;
+
+async function register(url?: string): Promise<void> {
+  if (url !== undefined) {
+    await Resources.registerFromUrl(url);
+    return;
+  }
+  const runtime = globalThis as { process?: { versions?: { node?: string } } };
+  if (runtime.process?.versions?.node === undefined) {
+    throw new Error(
+      'registerResources needs a url outside Node.js: a browser page or worker cannot read resources.json from node_modules',
+    );
+  }
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  Resources.registerFromNodejs(
+    require
+      .resolve('openchemlib')
+      .replace(/openchemlib\.js$/, 'resources.json'),
+  );
+}

package/src/translate/core/catalog.ts

@@ -0,0 +1,83 @@
+/**
+ * The shape of the messages a site or a library owns, and where they are kept.
+ *
+ * A catalog is one directory of a repository holding `en.json`, the source of
+ * truth, and one flat file per locale beside it. The site registers each of
+ * its catalogs with the repository and the directory, so a translation made
+ * anywhere on the page can be sent back to the file it belongs to.
+ */
+
+/** Messages by key; every value is an ICU MessageFormat string. */
+export type Messages = Record<string, string>;
+
+/** The locale every catalog is written in first. */
+export const SOURCE_LOCALE = 'en';
+
+/** One catalog a page renders messages from. */
+export interface CatalogSource {
+  /**
+   * The name the page knows the catalog by, unique on the page, e.g.
+   * `translate.cheminfo.org` or `react-cheminfo/share`.
+   */
+  id: string;
+  /** The GitHub repository the files live in, written `owner/repo`. */
+  repository: string;
+  /**
+   * The directory holding `en.json` and the locale files, relative to the
+   * repository root, e.g. `frontend/src/locales`.
+   */
+  directory: string;
+  /** The English messages. */
+  messages: Messages;
+}
+
+/** Which message of which catalog. */
+export interface MessageRef {
+  /** The catalog, by the id the page registered it under. */
+  catalogId: string;
+  /** The key of the message in that catalog. */
+  key: string;
+}
+
+const DIRECTORY_SEGMENT = /^[\w-][\w.-]*$/;
+
+/**
+ * The message a catalog holds under a key, never one inherited from
+ * `Object.prototype`: a key like `constructor` is only a message when the
+ * catalog defines it.
+ * @param messages - The catalog's messages.
+ * @param key - The key asked for.
+ * @returns The message, or `undefined` when the catalog has none.
+ */
+export function ownMessage(
+  messages: Messages,
+  key: string,
+): string | undefined {
+  return Object.hasOwn(messages, key) ? messages[key] : undefined;
+}
+
+/**
+ * Whether a path can name a catalog directory: relative, without `.` or `..`
+ * segments, and ending in a directory called `locales`. The server only ever
+ * writes inside such a directory.
+ * @param value - The candidate path, e.g. `frontend/src/locales`.
+ * @returns True when the path is acceptable.
+ */
+export function isCatalogDirectory(value: string): boolean {
+  const segments = value.split('/');
+  if (segments.at(-1) !== 'locales') return false;
+  for (const segment of segments) {
+    if (!DIRECTORY_SEGMENT.test(segment)) return false;
+  }
+  return true;
+}
+
+/**
+ * The file a catalog keeps one locale's messages in.
+ * @param directory - The catalog directory.
+ * @param locale - The locale.
+ * @returns The path, relative to the repository root.
+ */
+export function catalogFile(directory: string, locale: string): string {
+  return `${directory}/${locale}.json`;
+}