prosebook 0.1.0 → 0.3.0

package/src/tools/endpoints.ts

@@ -0,0 +1,121 @@
+/**
+ * The dev server's half of the inspector (`inspector.ts`, `inspector-dialog.ts`): `__prosebook/open`,
+ * which opens an entry in the editor, and `__prosebook/entry`, which reads and edits one. Written over
+ * `Request` and `Response`, so each integration mounts them its own way: Vite as middleware, Bun as
+ * `Bun.serve` routes, Next behind a rewrite to a server of their own. Each opens the editor its dev
+ * server already launches.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import { CatalogError, entryLocation, loadCatalog, type EntryLocation } from './catalog.ts';
+import type { ResolvedConfig } from './config.ts';
+import { editEntry, readEntry, type EntryEdit } from './entry.ts';
+
+export interface EndpointOptions {
+  /** The path the endpoints sit under, ending in `/`: `/` by default. */
+  base?: string;
+  /** Opens an entry in the editor: a redirect to the dev server's own launcher, or a reply once it has. */
+  open: (at: EntryLocation) => Response | Promise<Response>;
+}
+
+/** Answers the inspector's requests, and nothing for any other path. */
+export function inspectorEndpoints(
+  config: ResolvedConfig | Promise<ResolvedConfig>,
+  { base = '/', open }: EndpointOptions,
+): (req: Request) => Promise<Response | undefined> {
+  return async (req) => {
+    const url = new URL(req.url);
+    if (url.pathname === `${base}__prosebook/open`) return openEntry(await config, url, open);
+    if (url.pathname === `${base}__prosebook/entry`) return entry(await config, req, url);
+    return undefined;
+  };
+}
+
+/**
+ * `?key=cart.items&locale=de`: the translation's entry, or the catalog's with `catalog` or when the
+ * locale has none. Read from disk, so a key added since the page loaded is found.
+ */
+async function openEntry(config: ResolvedConfig, url: URL, open: EndpointOptions['open']): Promise<Response> {
+  const key = url.searchParams.get('key') ?? '';
+  let message;
+  try {
+    message = loadCatalog(config).messages.find((m) => m.key === key);
+  } catch (e) {
+    return failed(e);
+  }
+  if (message === undefined)
+    return new Response(`no entry for "${key}" in the catalog: has it been renamed since the page loaded?`, { status: 404 });
+  const locale = url.searchParams.has('catalog') ? undefined : (url.searchParams.get('locale') ?? undefined);
+  return open(entryLocation(config, message, locale));
+}
+
+/**
+ * The inspector's dialog: GET `?key=…` reads an entry in every locale, POST `{ key, edit, write }`
+ * applies an edit (`entry.ts`). A POST writes files, so only the page itself may send one: same origin,
+ * and JSON, which a form on another site can't send without asking first.
+ */
+async function entry(config: ResolvedConfig, req: Request, url: URL): Promise<Response> {
+  if (req.method === 'GET') {
+    try {
+      return Response.json(readEntry(config, url.searchParams.get('key') ?? ''));
+    } catch (e) {
+      return failed(e);
+    }
+  }
+  const origin = req.headers.get('origin');
+  const sameOrigin = origin === null || new URL(origin).host === url.host;
+  if (req.method !== 'POST' || !sameOrigin || req.headers.get('content-type')?.startsWith('application/json') !== true)
+    return Response.json({ problems: [{ severity: 'error', message: 'edits come from the page, as JSON' }] }, { status: 403 });
+  try {
+    const { key, edit, write } = (await req.json()) as { key: string; edit: EntryEdit; write?: boolean };
+    const result = editEntry(config, key, edit, write === true);
+    return Response.json(result, { status: result.problems.length > 0 ? 422 : 200 });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+/** A redirect within the page's origin, to a launcher the dev server answers itself. */
+export const redirect = (path: string) => new Response(null, { status: 307, headers: { Location: path } });
+
+function failed(e: unknown): Response {
+  return Response.json(
+    { problems: e instanceof CatalogError ? e.problems : [{ severity: 'error', message: e instanceof Error ? e.message : String(e) }] },
+    { status: e instanceof CatalogError ? 409 : 400 },
+  );
+}
+
+/**
+ * The endpoints as Node middleware, for Vite's server and Next's. The request's host is the one the
+ * page was served from: a proxy's `x-forwarded-host`, as Next's rewrite sets, before its own.
+ */
+export function nodeMiddleware(
+  handle: (req: Request) => Promise<Response | undefined>,
+): (req: IncomingMessage, res: ServerResponse, next: () => void) => void {
+  return (req, res, next) => {
+    // Before reading the body, which a request for anything else leaves to whoever answers it.
+    if (req.url?.includes('/__prosebook/') !== true) return next();
+    const forwarded = req.headers['x-forwarded-host'];
+    const host = (Array.isArray(forwarded) ? forwarded[0] : forwarded) ?? req.headers.host ?? 'localhost';
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers))
+      for (const v of Array.isArray(value) ? value : value === undefined ? [] : [value]) headers.append(name, v);
+
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : Buffer.concat(chunks);
+      handle(new Request(`http://${host}${req.url}`, { method: req.method, headers, body }))
+        .then(async (response) => {
+          if (response === undefined) return next();
+          res.statusCode = response.status;
+          response.headers.forEach((value, name) => res.setHeader(name, value));
+          res.end(Buffer.from(await response.arrayBuffer()));
+        })
+        .catch((e: unknown) => {
+          res.statusCode = 500;
+          res.end(e instanceof Error ? e.message : String(e));
+        });
+    });
+  };
+}

package/src/tools/entry.ts

@@ -168,6 +168,83 @@ export function applyFixes(config: ResolvedConfig, catalog: Catalog, findings: F
   return { fixed, problems: [] };
 }
 
+export interface Imported {
+  /** Keys whose translation was written. */
+  written: string[];
+  /** Keys given back as they were: each still holds, so a stale one can be accepted. */
+  unchanged: string[];
+  /** What was left out, and why. The rest was written regardless. */
+  problems: Problem[];
+}
+
+/**
+ * Translations into `locale` from `prosebook todo`'s YAML filled in, by a person or a model, each
+ * written to the file its locale and area put it in. Text around a fenced block is left aside, as a
+ * model's reply has it, and an empty value is one left for later. An entry that would break the
+ * catalog is left out with its problem, so a reply with one bad entry still lands the others.
+ */
+export function importTranslations(config: ResolvedConfig, locale: string, reply: string): Imported {
+  const failed = (message: string, key?: string): Problem => ({ severity: 'error', key, message });
+  if (locale === config.source)
+    return { written: [], unchanged: [], problems: [failed(`${locale} is the source: import takes translations`)] };
+  const fenced = [...reply.matchAll(/^```[^\n]*\n([\s\S]*?)^```/gm)].map((m) => m[1]);
+  const doc = parseDocument(fenced.length > 0 ? fenced.join('\n') : reply);
+  if (doc.errors.length > 0 || !(isMap(doc.contents) || doc.contents === null)) {
+    const why = doc.errors[0]?.message.split('\n', 1)[0] ?? 'it is not a mapping';
+    return {
+      written: [],
+      unchanged: [],
+      problems: [failed(`the reply isn't YAML of \`key: translation\` (${why}): fix it, or ask for one YAML block`)],
+    };
+  }
+
+  const catalog = loadCatalog(config);
+  const problems: Problem[] = [];
+  const unchanged: string[] = [];
+  const pending = new Map<string, { file: string; text: string }>();
+  for (const pair of isMap(doc.contents) ? doc.contents.items : []) {
+    const key = isScalar(pair.key) ? String(pair.key.value) : String(pair.key);
+    const message = catalog.messages.find((m) => m.key === key);
+    if (message === undefined) {
+      problems.push(failed('no entry has this key: translate only the keys `prosebook todo` printed', key));
+      continue;
+    }
+    const value = isScalar(pair.value) ? pair.value.value : pair.value;
+    if (value === null || value === '') continue;
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      problems.push(failed('the translation is not text: give the message as one string', key));
+      continue;
+    }
+    const text = String(value);
+    if (text === message.translations.get(locale)?.text) unchanged.push(key);
+    else pending.set(key, { file: translationFile(config, message, locale), text });
+  }
+
+  // An entry whose own file reports it is left out, until what is left loads clean. A problem
+  // anywhere else means the catalog was broken before the reply, so nothing is written.
+  for (;;) {
+    const unsaved = new Map<string, string>();
+    for (const [key, { file, text }] of pending)
+      unsaved.set(resolve(config.root, file), withTranslation(contentOf(config, file, unsaved), key, text));
+    try {
+      loadCatalog(config, unsaved);
+    } catch (e) {
+      if (!(e instanceof CatalogError)) throw e;
+      const errors = e.problems.filter((p) => p.severity === 'error');
+      const own = errors.filter((p) => p.key !== undefined && pending.get(p.key)?.file === p.file);
+      if (own.length === 0) return { written: [], unchanged: [], problems: [...problems, ...errors] };
+      for (const p of own) if (p.key !== undefined) pending.delete(p.key);
+      problems.push(...own);
+      continue;
+    }
+    for (const [path, content] of unsaved) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    }
+    return { written: [...pending.keys()], unchanged, problems };
+  }
+}
+
 /** A file as the edit has it, as it is on disk, or empty when it is still to be made. */
 function contentOf(config: ResolvedConfig, file: string, unsaved: Map<string, string>): string {
   const path = resolve(config.root, file);

package/src/tools/generate.ts

@@ -12,6 +12,7 @@ import { loadCatalog, type Catalog, type Message } from './catalog.ts';
 import { compileLocale, localeModule, type Entry } from './compile.ts';
 import type { ResolvedConfig } from './config.ts';
 import { readLock, reconcile, serializeLock, type Lock, type StaleTranslation } from './lock.ts';
+import { nativeFiles } from './native/index.ts';
 import { pseudoAst } from './pseudo.ts';
 import { SYNTAX_NAME } from './syntax.ts';
 
@@ -127,44 +128,42 @@ function catalogLiteral(config: ResolvedConfig, locales: string[], ext: string):
 
 /** The JSON Schema an editor reads to complete and explain catalog entries. */
 export function catalogSchema(config: ResolvedConfig): object {
+  // The shorthand satisfies no required field, so it's offered only where none is.
+  const shorthand = { type: 'string', description: `The message, in ${SYNTAX_NAME[config.messageFormat]}, with nothing said about it.` };
+  const entry = {
+    type: 'object',
+    required: [config.source, ...config.require],
+    additionalProperties: false,
+    properties: {
+      [config.source]: { type: 'string', description: `The message, in ${SYNTAX_NAME[config.messageFormat]}.` },
+      kind: {
+        description: 'What sort of string it is.',
+        oneOf: Object.entries(config.kinds).map(([k, r]) => ({ const: k, description: r.doc })),
+      },
+      surface: {
+        description: 'Where the string sits.',
+        oneOf: Object.entries(config.surfaces).map(([k, d]) => ({ const: k, description: d })),
+      },
+      context: { type: 'string', description: 'One sentence telling a translator where the string appears and what it answers to.' },
+      args: { type: 'object', description: 'What each placeholder holds.', additionalProperties: { type: 'string' } },
+      fragment: { type: 'boolean', description: 'Completes something beside it rather than standing as a sentence.' },
+      comment: { type: 'string', description: 'A change asked of whoever edits the entry next. Make it, then delete the comment.' },
+      remove: { type: 'boolean', description: 'Asks for the entry to go: delete it, its translations and the code that reads it.' },
+      allow: {
+        type: 'object',
+        description: 'Lint rules this entry is exempt from, each with the reason.',
+        propertyNames: { enum: Object.keys(config.lint.rules) },
+        additionalProperties: { type: 'string' },
+      },
+    },
+  };
   return {
     $schema: 'https://json-schema.org/draft/2020-12/schema',
     title: 'prosebook catalog',
     description: 'Generated by `prosebook generate` from the config. Do not edit.',
     type: 'object',
     propertyNames: { pattern: '^[a-z0-9]+(?:[-_][a-z0-9]+)*(?:\\.[a-z0-9]+(?:[-_][a-z0-9]+)*)+$' },
-    additionalProperties: {
-      oneOf: [
-        { type: 'string', description: `The message, in ${SYNTAX_NAME[config.messageFormat]}, with nothing said about it.` },
-        {
-          type: 'object',
-          required: [config.source, ...config.require],
-          additionalProperties: false,
-          properties: {
-            [config.source]: { type: 'string', description: `The message, in ${SYNTAX_NAME[config.messageFormat]}.` },
-            kind: {
-              description: 'What sort of string it is.',
-              oneOf: Object.entries(config.kinds).map(([k, r]) => ({ const: k, description: r.doc })),
-            },
-            surface: {
-              description: 'Where the string sits.',
-              oneOf: Object.entries(config.surfaces).map(([k, d]) => ({ const: k, description: d })),
-            },
-            context: { type: 'string', description: 'One sentence telling a translator where the string appears and what it answers to.' },
-            args: { type: 'object', description: 'What each placeholder holds.', additionalProperties: { type: 'string' } },
-            fragment: { type: 'boolean', description: 'Completes something beside it rather than standing as a sentence.' },
-            comment: { type: 'string', description: 'A change asked of whoever edits the entry next. Make it, then delete the comment.' },
-            remove: { type: 'boolean', description: 'Asks for the entry to go: delete it, its translations and the code that reads it.' },
-            allow: {
-              type: 'object',
-              description: 'Lint rules this entry is exempt from, each with the reason.',
-              propertyNames: { enum: Object.keys(config.lint.rules) },
-              additionalProperties: { type: 'string' },
-            },
-          },
-        },
-      ],
-    },
+    additionalProperties: config.require.length === 0 ? { oneOf: [shorthand, entry] } : entry,
   };
 }
 
@@ -231,6 +230,7 @@ export function render(config: ResolvedConfig, accept?: Map<string, Set<string>
     );
   }
 
+  for (const [path, content] of nativeFiles(config, catalog, locales, entries, head)) files.set(path, content);
   files.set(join(config.catalog, 'catalog.schema.json'), `${JSON.stringify(catalogSchema(config), null, 2)}\n`);
   if (Object.keys(lock.translations).length > 0 || existsSync(config.lock)) files.set(config.lock, serializeLock(lock));
   return { catalog, files, lock, stale, entries };

package/src/tools/icu.ts

@@ -9,7 +9,33 @@ export type { MessageFormatElement };
 export { TYPE };
 
 export function parseMessage(text: string): MessageFormatElement[] {
-  return parse(text, { shouldParseSkeletons: true, requiresOtherClause: true });
+  const ast = parse(text, { shouldParseSkeletons: true, requiresOtherClause: true });
+  walk(ast, (el) => {
+    if ((isDateElement(el) || isTimeElement(el)) && typeof el.style === 'object' && el.style !== null && el.style.pattern.includes('j'))
+      el.style.parsedOptions = localHour(el.style.pattern);
+  });
+  return ast;
+}
+
+/**
+ * A skeleton's `j` is the hour as the locale writes it, 12 or 24. The parser resolves it only when
+ * given a locale and drops it otherwise, so `::yMMMdjmm` showed the minute alone. Read here as an
+ * hour with no cycle, which `Intl` gives the cycle of whatever locale formats it: "2:05 PM", "14:05".
+ */
+function localHour(pattern: string): Intl.DateTimeFormatOptions {
+  const run = /j+/.exec(pattern)![0];
+  const rest = pattern.replaceAll('j', '');
+  return { ...(rest === '' ? {} : dateFields(rest)), hour: run.length % 2 === 0 ? '2-digit' : 'numeric' };
+}
+
+/** What the parser reads from a date skeleton on its own; nothing where it can't parse it. */
+function dateFields(skeleton: string): Intl.DateTimeFormatOptions {
+  try {
+    const el = parse(`{d, date, ::${skeleton}}`, { shouldParseSkeletons: true })[0];
+    return el !== undefined && isDateElement(el) && typeof el.style === 'object' && el.style !== null ? el.style.parsedOptions : {};
+  } catch {
+    return {};
+  }
 }
 
 /**
@@ -39,6 +65,50 @@ function argType(el: MessageFormatElement): string | undefined {
   }
 }
 
+/**
+ * Formatting options read from arguments as the message renders, by `Intl` option: MF2's
+ * `{$price :currency currency=$code}`. MF1 has no way to say this, so only a tree read from MF2 has them.
+ */
+export type OptionArgs = Record<string, { arg: string; type: string }>;
+
+export function optionArgsOf(el: MessageFormatElement): OptionArgs | undefined {
+  if (el.type === TYPE.plural) return selectionOf(el)?.args;
+  if (!isNumberElement(el) && !isDateElement(el) && !isTimeElement(el)) return undefined;
+  const style = el.style;
+  return typeof style === 'object' && style !== null && 'args' in style ? (style as { args: OptionArgs }).args : undefined;
+}
+
+/**
+ * How an MF2 `.match` selects on a number, beyond its plural type: on the number as formatted, so
+ * the selector's digit options (`Intl.PluralRules` takes the same ones, some from arguments) decide
+ * the category, and on the value `:integer` rounds or `:percent` multiplies by 100. Kept with the
+ * selector's function as written, to write it back. MF1 selects on the bare value.
+ */
+export interface Selection {
+  fn: { name: string; options: Record<string, string>; args?: Record<string, string> };
+  options: Intl.PluralRulesOptions;
+  args?: OptionArgs;
+  value?: 'round' | 'percent';
+}
+
+export function selectionOf(el: MessageFormatElement): Selection | undefined {
+  return el.type === TYPE.plural ? (el as { selection?: Selection }).selection : undefined;
+}
+
+/**
+ * How a placeholder renders around its value: the text it shows when it has none, or one `Intl`
+ * can't format, and the marks isolating its direction from the text around it. MF2 sets these
+ * (`{$name}`, and isolation in a right-to-left locale); an MF1 placeholder shows `{name}`.
+ */
+export interface Placeholder {
+  fallback: string;
+  isolate?: readonly [open: string, close: string];
+}
+
+export function placeholderOf(el: MessageFormatElement, name: string): Placeholder {
+  return (el as { placeholder?: Placeholder }).placeholder ?? { fallback: `{${name}}` };
+}
+
 /** Calls `visit` on every element, inside plural and select arms and tags too. */
 export function walk(elements: MessageFormatElement[], visit: (el: MessageFormatElement) => void): void {
   for (const el of elements) {
@@ -50,12 +120,15 @@ export function walk(elements: MessageFormatElement[], visit: (el: MessageFormat
 
 export function argsOf(elements: MessageFormatElement[], clash: (name: string) => void = () => {}): Map<string, string> {
   const args = new Map<string, string>();
+  const add = (name: string, type: string) => {
+    const seen = args.get(name);
+    if (seen !== undefined && seen !== type) clash(name);
+    else args.set(name, type);
+  };
   walk(elements, (el) => {
+    for (const { arg, type } of Object.values(optionArgsOf(el) ?? {})) add(arg, type);
     const type = argType(el);
-    if (type === undefined || !('value' in el) || typeof el.value !== 'string') return;
-    const seen = args.get(el.value);
-    if (seen !== undefined && seen !== type) clash(el.value);
-    else args.set(el.value, type);
+    if (type !== undefined && 'value' in el && typeof el.value === 'string') add(el.value, type);
   });
   return args;
 }
@@ -95,8 +168,12 @@ export function numberOptions(el: NumberElement): Intl.NumberFormatOptions | und
   const unknown = style.tokens.filter((t) => !stemIsKnown(t.stem, t.options)).map((t) => t.stem);
   if (unknown.length > 0) throw new Error(`{${el.value}} has skeleton stems the formatter drops without a word: ${unknown.join(', ')}`);
   const options = style.parsedOptions as Intl.NumberFormatOptions;
+  // An option an argument gives is checked with a stand-in: `Intl` refuses a currency style without
+  // its currency. Whether the argument's value suits it is known only as the message renders.
+  const args = optionArgsOf(el) ?? {};
+  const given = { ...(args.currency && { currency: 'EUR' }), ...(args.unit && { unit: 'meter' }) };
   try {
-    new Intl.NumberFormat('en', options).resolvedOptions();
+    new Intl.NumberFormat('en', { ...options, ...given }).resolvedOptions();
   } catch (e) {
     throw new Error(`{${el.value}} has a skeleton Intl refuses: ${(e as Error).message}`, { cause: e });
   }
@@ -115,6 +192,9 @@ export function dateOptions(el: DateElement | TimeElement): Intl.DateTimeFormatO
     }
     return { [field]: style };
   }
+  // Every field the parser understands sets an option, and one it doesn't is dropped without a word.
+  const dropped = (style.pattern.match(/([A-Za-z])
*/g) ?? []).filter((f) => !f.startsWith('j') && Object.keys(dateFields(f)).length === 0);
+  if (dropped.length > 0) throw new Error(`{${el.value}} has date fields the formatter drops without a word: ${dropped.join(', ')}`);
   if (Object.keys(style.parsedOptions).length === 0)
     throw new Error(`{${el.value}} has a date skeleton the formatter reads nothing from: "${style.pattern}"`);
   try {
@@ -167,8 +247,13 @@ export function formatsOf(ast: MessageFormatElement[]): Map<string, string> {
       said = `${kind} \`${style}\``;
     } else if ('mf2' in style) {
       // Read from MF2: the function as written.
-      const { name, options } = (style as { mf2: { name: string; options: Record<string, string> } }).mf2;
-      said = `\`${[`:${name}`, ...Object.entries(options).map(([k, v]) => `${k}=${v}`)].join(' ')}\``;
+      const {
+        name,
+        options,
+        args = {},
+      } = (style as { mf2: { name: string; options: Record<string, string>; args?: Record<string, string> } }).mf2;
+      const written = [...Object.entries(options), ...Object.entries(args).map(([k, v]) => [k, `$${v}`])];
+      said = `\`${[`:${name}`, ...written.map(([k, v]) => `${k}=${v}`)].join(' ')}\``;
     } else if ('tokens' in style) {
       said = `${kind} \`::${style.tokens.map((t) => [t.stem, ...t.options].join('/')).join(' ')}\``;
     } else {

package/src/tools/index.ts

@@ -30,14 +30,16 @@ export {
 export {
   applyFixes,
   editEntry,
+  importTranslations,
   readEntry,
+  type Imported,
   type EntryEdit,
   type EntryFields,
   type EntryFinding,
   type EntryView,
   type EntryYaml,
 } from './entry.ts';
-export { defineConfig, loadConfig, resolveConfig, type ProsebookConfig, type ResolvedConfig } from './config.ts';
+export { defineConfig, loadConfig, resolveConfig, type NativeTarget, type ProsebookConfig, type ResolvedConfig } from './config.ts';
 export { catalogSchema, generate, localeEntries, localesOf, render, writeFiles, type Generated } from './generate.ts';
 export {
   applyEdits,
@@ -66,13 +68,27 @@ export {
   type SubstitutionRule,
 } from './lint.ts';
 export { formatDiff, wordDiff, type DiffPart } from './diff.ts';
-export { emptyLock, hash, readLock, reconcile, serializeLock, type Lock, type StaleTranslation } from './lock.ts';
+export { changeOf, emptyLock, hash, readLock, reconcile, serializeLock, type Lock, type StaleTranslation } from './lock.ts';
 export { DEFAULT_KINDS, DEFAULT_SURFACES, STRICT_LISTS, type KindRule, type Severity } from './presets.ts';
 export { pseudoAst, pseudoText } from './pseudo.ts';
-export { intlDate, intlNumber, parseMf2, toMf2, type Mf2Function } from './mf2.ts';
+export { intlDate, intlNumber, parseMf2, toMf2, type Isolate, type Mf2Function } from './mf2.ts';
 export { toMf1 } from './mf1.ts';
 export { applyMigrate, planMigrate, type MigratePlan } from './migrate.ts';
 export { readMessage, SYNTAX_NAME, writeMessage, type MessageFormatVersion } from './syntax.ts';
 export { syntaxKind, typescriptOracle, type Span, type TypeOracle, type ValueKind } from './types.ts';
+export { todoOf, type Todo } from './todo.ts';
 export { SarifReport, type SarifResult, type SarifTool } from './sarif.ts';
-export { hardcodedText, isReferenced, keyRefs, looksLikeCode, scan, sourceFiles, type Hardcoded, type KeyRefs } from './scan.ts';
+export {
+  hardcodedText,
+  isReferenced,
+  keyRefs,
+  looksLikeCode,
+  READERS,
+  scan,
+  sourceFiles,
+  unseenReads,
+  type Hardcoded,
+  type KeyRefs,
+  type Reads,
+  type UnseenRead,
+} from './scan.ts';

package/src/tools/lint.ts

@@ -37,11 +37,12 @@ interface RuleBase {
   /** Its severity under `extends: 'strict'`; `error` when unset. */
   strict?: Severity;
   /**
-   * Only entries of these kinds, or on these surfaces; an entry that says neither is skipped. Only
-   * the source unless `locale` says otherwise, since most writing rules are written for one language:
-   * `all` reads every locale, and a list those languages and their regions (`de` covers `de-CH`).
+   * Only entries of these kinds, on these surfaces, or in these areas (a key's first segment); an
+   * entry that says no kind or surface is skipped by a rule that names some. Only the source unless
+   * `locale` says otherwise, since most writing rules are written for one language: `all` reads
+   * every locale, and a list those languages and their regions (`de` covers `de-CH`).
    */
-  on?: { kind?: string[]; surface?: string[]; locale?: 'all' | string[] };
+  on?: { kind?: string[]; surface?: string[]; area?: string[]; locale?: 'all' | string[] };
 }
 
 /** A rule written as code. */
@@ -273,10 +274,14 @@ const NOT_PLURAL = new Set([
   'series',
 ]);
 
-/** The singular of an English plural noun, or nothing where it doesn't look like one. */
+/**
+ * The singular of an English plural noun, or nothing where it doesn't look like one. A word with no
+ * vowel is a unit or an abbreviation (`kbps`, `fps`, `hrs`), which reads the same after 1.
+ */
 export function singularOf(word: string): string | undefined {
   const lower = word.toLowerCase();
   if (word.length < 3 || !lower.endsWith('s') || lower.endsWith('ss') || NOT_PLURAL.has(lower)) return undefined;
+  if (!/[aeiouy]/.test(lower)) return undefined;
   if (/[^aeiou]ies$/.test(lower)) return `${word.slice(0, -3)}y`;
   if (/(?:s|x|z|ch|sh)es$/.test(lower)) return word.slice(0, -2);
   return word.slice(0, -1);
@@ -323,12 +328,14 @@ function eachRun(
 const COUNT_NAME = /^(?:n|num|count|total|amount|quantity)$|(?:count|total)$/i;
 
 /**
- * Whether an arm ends with a stop; nothing for an arm with no words. Which stop is the arm's own: a
- * question in `one` and a second sentence after it in `other` both end well.
+ * Whether an arm ends with a stop; nothing for an arm with no words, or one that trails off in an
+ * ellipsis (`Saving…`, `Save as…`), which is neither. Which stop is the arm's own: a question in
+ * `one` and a second sentence after it in `other` both end well.
  */
 function endsWithStop(arm: MessageFormatElement[]): boolean | undefined {
   const text = prose(renderAs(arm, 'other')).trim();
-  return text.replaceAll(HOLE, '').trim() === '' ? undefined : hasStop(text);
+  if (text.replaceAll(HOLE, '').trim() === '' || /(?:…|\.{3})["')”»」』]*$/u.test(text)) return undefined;
+  return hasStop(text);
 }
 
 /** Ends with a stop in any script (`。`, `؟`, `;` as Greek writes `?`), though not a comma. */
@@ -336,6 +343,17 @@ const hasStop = (text: string) => /(?![,，、،])[\p{Terminal_Punctuation}…][
 
 const CURRENCY_BEFORE = /[$€£¥₹]\s?$/;
 
+/**
+ * The ways a path through menus is written, the separator in a group: an arrow or `›` however
+ * spaced, and `>` or `/` only spaced between words or placeholders, with a capital after a slash,
+ * since "2 > 1" and "and / or" are no paths. The match takes the spaces around, so the fix spaces
+ * the separator.
+ */
+const PATH_SEPARATORS = new RegExp(
+  String.raw`\s*(→|->|›)\s*|(?<=[\p{L}${HOLE}])\s+(>)\s+(?=[\p{L}${HOLE}])|(?<=\p{L})\s+(\/)\s+(?=\p{Lu})`,
+  'gu',
+);
+
 const OFF_SCREEN = new Set(['aria']);
 
 const an = (word = 'string') => `${/^[aeiou]/i.test(word) ? 'an' : 'a'} ${word}`;
@@ -447,6 +465,19 @@ export const CORE_RULES = {
       return match === undefined ? [] : [{ message: 'no em-dash: a comma, a period or a colon does the job', match }];
     },
   },
+  path: {
+    description: 'A path through menus or settings is written with `lint.pathSeparator`, spaced: Settings › General.',
+    check: ({ text, config }) => {
+      const use = config.lint.pathSeparator;
+      for (const v of text.variants) {
+        for (const m of v.matchAll(PATH_SEPARATORS)) {
+          if ((m[1] ?? m[2] ?? m[3]) === use) continue;
+          return [{ message: `a path is written with a spaced ${use}`, match: m[0], fix: ` ${use} ` }];
+        }
+      }
+      return [];
+    },
+  },
   contractions: {
     description: '`could not`, `is not` and `cannot` are written as contractions.',
     check: ({ text }) =>
@@ -704,14 +735,19 @@ const readsLocale = (locales: 'all' | string[] | undefined, locale: string, sour
       locales.some((l) => locale.toLowerCase() === l.toLowerCase() || locale.toLowerCase().startsWith(`${l.toLowerCase()}-`));
 
 function applies(rule: RuleBase, message: Message, locale: string, sourceLocale: string): boolean {
-  const { kind, surface, locale: locales } = rule.on ?? {};
+  const { kind, surface, area, locale: locales } = rule.on ?? {};
   return (
     readsLocale(locales, locale, sourceLocale) &&
     (kind === undefined || (message.kind !== undefined && kind.includes(message.kind))) &&
-    (surface === undefined || (message.surface !== undefined && surface.includes(message.surface)))
+    (surface === undefined || (message.surface !== undefined && surface.includes(message.surface))) &&
+    (area === undefined || area.includes(message.area))
   );
 }
 
+/** A rule's severity for an entry: its area's, where `lint.areas` sets one. */
+export const severityOf = (config: ResolvedConfig, name: string, message: Message): Severity | undefined =>
+  config.lint.areas[message.area]?.[name] ?? config.lint.rules[name]?.severity;
+
 interface Literal {
   start: number;
   value: string;
@@ -784,7 +820,8 @@ export function lint(messages: Message[], config: ResolvedConfig): Finding[] {
       const text = locale === config.source ? source : readings(ast);
       const context: RuleContext = { message, locale, ast, kind, text, source, config };
       let literals: Literal[] | undefined;
-      for (const [name, { rule, severity }] of rules) {
+      for (const [name, { rule }] of rules) {
+        const severity = severityOf(config, name, message)!;
         if (severity === 'off' || !applies(rule, message, locale, config.source)) continue;
         let said: (string | Report)[];
         try {
@@ -814,7 +851,7 @@ export function lint(messages: Message[], config: ResolvedConfig): Finding[] {
       const rule = config.lint.rules[name];
       if (rule === undefined) {
         findings.push({ ...at, message: `allow.${name} is not a rule: ${rules.map(([n]) => n).join(', ')}` });
-      } else if (rule.severity === 'off') {
+      } else if (severityOf(config, name, message) === 'off') {
         continue;
       } else if (!fired.has(name)) {
         findings.push({ ...at, message: `allow.${name} exempts the entry from a rule it passes: remove it` });

package/src/tools/lock.ts

@@ -14,6 +14,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 
 import type { Catalog } from './catalog.ts';
+import { formatDiff, wordDiff } from './diff.ts';
 
 export interface Lock {
   version: 2;
@@ -59,6 +60,12 @@ export interface StaleTranslation {
   translation: string;
 }
 
+/** What changed in the source of a stale translation, as a word diff, or why that isn't known. */
+export function changeOf(stale: StaleTranslation): string {
+  if (stale.was === undefined) return "the earlier text isn't recorded (the lock predates prosebook 0.2)";
+  return formatDiff(wordDiff(stale.was, stale.now)).replaceAll('\n', ' ');
+}
+
 export interface Reconciled {
   lock: Lock;
   /** Per locale, per key: the translations made from a source that has changed since. */