blume 1.4.2 → 1.5.0

package/src/translate/report.ts

@@ -3,6 +3,7 @@ import type { ColorFunction } from "consola/utils";
 
 import { AGENTS } from "../audit/agent.ts";
 import type { AgentKind } from "../audit/agent.ts";
+import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import type {
@@ -28,17 +29,17 @@ import type {
 
 const ESC = String.fromCodePoint(27);
 
-const GLYPH: Record<TranslateItemStatus, string> = {
+const GLYPH = {
   failed: "✖",
   partial: "!",
   translated: "✔",
-};
+} satisfies Record<TranslateItemStatus, string>;
 
-const STATUS_COLOR: Record<TranslateItemStatus, ColorFunction> = {
+const STATUS_COLOR = {
   failed: colors.red,
   partial: colors.yellow,
   translated: colors.green,
-};
+} satisfies Record<TranslateItemStatus, ColorFunction>;
 
 export const SPINNER_FRAMES = [
   "⠋",
@@ -59,20 +60,6 @@ export const SPINNER_INTERVAL_MS = 80;
 /** The clear-to-start-of-line prefix every TTY rewrite uses. */
 const REWRITE = `\r${ESC}[K`;
 
-const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
-
-const money = (cost: number | undefined): string =>
-  cost === undefined ? "" : `$${cost.toFixed(2)}`;
-
-const duration = (ms: number): string => {
-  if (ms < 60_000) {
-    return seconds(ms);
-  }
-  const minutes = Math.floor(ms / 60_000);
-  const rest = Math.round((ms % 60_000) / 1000);
-  return `${minutes}m ${rest}s`;
-};
-
 /** `docs/guides/install.mdx → fr`, or the batched meta call's label. */
 export const itemLabel = (item: WorkItem): string =>
   item.kind === "page"
@@ -89,8 +76,12 @@ export const spinnerLine = (
   total: number,
   frame: number
 ): string => {
+  // SAFETY: the renderer only paints while at least one item is active, so the
+  // oldest active entry exists.
   const first = active[0] as WorkItem;
   const more = active.length > 1 ? ` (+${active.length - 1} more)` : "";
+  // SAFETY: `frame % SPINNER_FRAMES.length` is always an index into the
+  // non-empty frames array.
   return `  ${colors.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length] as string)} ${itemLabel(first)}${more} ${colors.dim(`${done}/${total}`)}`;
 };
 
@@ -229,7 +220,7 @@ export const checkReportJson = (workList: TranslateWorkList): string => {
 };
 
 /** One run result lowered to JSON-friendly, root-relative fields. */
-const resultJson = (result: TranslateItemResult): Record<string, unknown> => ({
+const resultJson = (result: TranslateItemResult) => ({
   costUsd: result.costUsd,
   detail: result.detail,
   durationMs: result.durationMs,

package/src/translate/run.ts

@@ -2,9 +2,11 @@ import { existsSync } from "node:fs";
 import { mkdtemp, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 
+import pLimit from "p-limit";
+import pMap from "p-map";
 import { join } from "pathe";
 
-import { AGENTS, WINDOWS_COMMAND_NOT_FOUND } from "../audit/agent.ts";
+import { AGENTS } from "../audit/agent.ts";
 import type { AgentKind } from "../audit/agent.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -56,8 +58,9 @@ export interface TranslateRunOptions {
    * Called after each finished item to flush the ledger to disk, so an
    * interrupted run keeps everything already translated. Calls are serialized
    * here — concurrent workers finishing together never race the same file.
+   * The flush's result (`writeLedger`'s wrote-or-not boolean) is ignored.
    */
-  persistLedger?: () => Promise<unknown>;
+  persistLedger?: () => Promise<boolean | undefined>;
   project: BlumeProject;
   /** The spawn function — injectable so tests never launch a real agent. */
   run?: HeadlessRunner;
@@ -89,9 +92,9 @@ interface RunContext {
 const metaDirKey = (dir: string): string => (dir === "" ? "." : dir);
 
 /**
- * One headless agent call. A Windows shell launch reports a missing executable
- * through exit code 9009 instead of a spawn error, so that is normalized to
- * the ENOENT rejection the command layer already turns into an install hint.
+ * One headless agent call. A missing executable rejects with ENOENT on every
+ * platform (the runner spawns without a shell), which the command layer turns
+ * into an install hint.
  */
 const invokeAgent = async (
   context: RunContext,
@@ -104,13 +107,6 @@ const invokeAgent = async (
     translateAgentArgs(context.kind, messagePath),
     { cwd: context.dir, prompt, timeoutMs: context.timeoutMs }
   );
-  if (!result.timedOut && result.code === WINDOWS_COMMAND_NOT_FOUND) {
-    const missing = new Error(
-      `${context.bin} was not found on PATH`
-    ) as NodeJS.ErrnoException;
-    missing.code = "ENOENT";
-    throw missing;
-  }
   return await readAgentOutput(context.kind, result, messagePath);
 };
 
@@ -134,6 +130,8 @@ const runPageItem = async (
   });
 
   const sourceText = await readFile(item.sourcePath, "utf-8");
+  // SAFETY: `targets` maps every configured locale, and work items only carry
+  // configured locale codes.
   const target = context.targets.get(item.locale) as LocaleConfig;
   // A hand-authored translation can live at a non-canonical name (see
   // WorkStatus); the disk probe finds only canonical targets, and a miss just
@@ -180,6 +178,8 @@ const runMetaItem = async (
   const titles = Object.fromEntries(
     item.entries.map((entry) => [metaDirKey(entry.meta.dir), entry.meta.title])
   );
+  // SAFETY: `targets` maps every configured locale, and work items only carry
+  // configured locale codes.
   const target = context.targets.get(item.locale) as LocaleConfig;
   const output = await invokeAgent(
     context,
@@ -262,6 +262,7 @@ export const runTranslate = async (
   if (!i18n) {
     throw new Error("blume translate requires i18n to be configured");
   }
+  // SAFETY: the config schema requires `defaultLocale` to be one of `locales`.
   const source = i18n.locales.find(
     (locale) => locale.code === i18n.defaultLocale
   ) as LocaleConfig;
@@ -277,42 +278,31 @@ export const runTranslate = async (
   };
 
   const { items } = options.workList;
-  const results: TranslateItemResult[] = Array.from({ length: items.length });
   const concurrency = Math.max(
     1,
     Math.min(options.concurrency ?? 1, items.length || 1)
   );
 
-  // The persist chain: whichever lane finishes next appends its flush after
-  // the previous one, so two lanes never write the ledger file concurrently.
-  let persisting: Promise<unknown> = Promise.resolve();
-  const persist = (): Promise<unknown> => {
-    // The chain is the mutex: appending with .then() serializes flushes.
-    // oxlint-disable-next-line promise/prefer-await-to-then
-    persisting = persisting.then(() => options.persistLedger?.());
-    return persisting;
-  };
+  // The persist mutex: ledger flushes from concurrent lanes are serialized so
+  // two lanes never write the ledger file at the same time.
+  const persistLimit = pLimit(1);
+  const persist = (): Promise<boolean | undefined> =>
+    persistLimit(() => options.persistLedger?.());
 
-  let nextIndex = 0;
-  const worker = async (): Promise<void> => {
-    while (nextIndex < items.length) {
-      const index = nextIndex;
-      nextIndex += 1;
-      const item = items[index] as WorkItem;
+  const results = await pMap(
+    items,
+    async (item: WorkItem, index): Promise<TranslateItemResult> => {
       options.onProgress?.({
         index,
         item,
         kind: "item-start",
         total: items.length,
       });
-      // oxlint-disable-next-line no-await-in-loop -- each worker is a serial lane
       const result = await (item.kind === "page"
         ? runPageItem(item, index, context, options.ledger)
         : runMetaItem(item, index, context, options.ledger));
-      results[index] = result;
-      // Flush this item's stamps before claiming the next one, so a kill
-      // loses at most the in-flight items.
-      // oxlint-disable-next-line no-await-in-loop
+      // Flush this item's stamps before the slot frees for the next item, so
+      // a kill loses at most the in-flight items.
       await persist();
       options.onProgress?.({
         index,
@@ -320,9 +310,10 @@ export const runTranslate = async (
         result,
         total: items.length,
       });
-    }
-  };
-  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      return result;
+    },
+    { concurrency }
+  );
 
   const diagnostics: Diagnostic[] = [];
   for (const result of results) {
@@ -331,11 +322,11 @@ export const runTranslate = async (
     }
   }
 
-  const counts: Record<TranslateItemStatus, number> = {
+  const counts = {
     failed: 0,
     partial: 0,
     translated: 0,
-  };
+  } satisfies Record<TranslateItemStatus, number>;
   for (const result of results) {
     counts[result.status] += 1;
   }

package/src/translate/validate.ts

@@ -13,6 +13,24 @@ export type ValidationResult =
   | { ok: true; text: string }
   | { ok: false; reason: string };
 
+/**
+ * A parsed YAML frontmatter value (agent meta replies parse from JSON into the
+ * same shape). js-yaml can also mint Dates and other rich scalars; the
+ * traversal below only ever distinguishes "keyed object" from "string", so
+ * they ride along as the object arm.
+ */
+type FrontmatterValue =
+  | string
+  | number
+  | boolean
+  | null
+  | FrontmatterValue[]
+  | FrontmatterData;
+
+interface FrontmatterData {
+  [key: string]: FrontmatterValue;
+}
+
 const FRONTMATTER_OPEN = /^---\r?\n/u;
 const FENCE_LINE = /^\s*(?:```|~~~)/u;
 
@@ -33,27 +51,41 @@ export const stripOuterFence = (text: string): string => {
 const countFenceLines = (text: string): number =>
   text.split("\n").filter((line) => FENCE_LINE.test(line)).length;
 
-const getPath = (data: unknown, path: readonly string[]): unknown => {
-  let value: unknown = data;
+const isKeyedObject = (
+  value: FrontmatterValue | undefined
+): value is FrontmatterData => typeof value === "object" && value !== null;
+
+const isString = (value: FrontmatterValue | undefined): value is string =>
+  typeof value === "string";
+
+const getPath = (
+  data: FrontmatterValue,
+  path: readonly string[]
+): FrontmatterValue | undefined => {
+  let value: FrontmatterValue | undefined = data;
   for (const key of path) {
-    if (typeof value !== "object" || value === null) {
+    if (!isKeyedObject(value)) {
       return;
     }
-    value = (value as Record<string, unknown>)[key];
+    value = value[key];
   }
   return value;
 };
 
 /** Set `path` on `data`; only called for paths whose parents exist in `data`. */
 const setPath = (
-  data: Record<string, unknown>,
+  data: FrontmatterData,
   path: readonly string[],
   value: string
 ): void => {
   let parent = data;
   for (const key of path.slice(0, -1)) {
-    parent = parent[key] as Record<string, unknown>;
+    // SAFETY: callers only set paths that getPath already resolved to a string
+    // on this same (cloned) data, so every intermediate step is a keyed object.
+    parent = parent[key] as FrontmatterData;
   }
+  // SAFETY: every TRANSLATABLE_KEY_PATHS entry is a non-empty tuple, so the
+  // path always has a final key.
   parent[path.at(-1) as string] = value;
 };
 
@@ -84,7 +116,7 @@ export const validateTranslation = (
     };
   }
 
-  let parsed: { content: string; data: Record<string, unknown> };
+  let parsed: { content: string; data: FrontmatterData };
   try {
     parsed = matter(candidate);
   } catch {
@@ -114,13 +146,13 @@ export const validateTranslation = (
   // Reconciliation by reconstruction: start from the SOURCE data and overlay
   // only the translatable key paths where both sides hold a string and the
   // translation is non-empty.
-  const data = structuredClone(source.data) as Record<string, unknown>;
+  const data: FrontmatterData = structuredClone(source.data);
   for (const path of TRANSLATABLE_KEY_PATHS) {
     const original = getPath(source.data, path);
     const translated = getPath(parsed.data, path);
     if (
-      typeof original === "string" &&
-      typeof translated === "string" &&
+      isString(original) &&
+      isString(translated) &&
       translated.trim() !== ""
     ) {
       setPath(data, path, translated);
@@ -133,6 +165,12 @@ export const validateTranslation = (
   };
 };
 
+/** A meta-batch parse: recovered titles by key, plus the keys still missing. */
+export interface MetaTitlesResult {
+  titles: Record<string, string>;
+  missing: string[];
+}
+
 /**
  * Extract translated sidebar titles from a meta reply: tolerant first-`{`
  * to-last-`}` extraction (the eval `parseVerdict` idiom). Keys missing or
@@ -141,10 +179,10 @@ export const validateTranslation = (
 export const parseMetaTitles = (
   agentText: string,
   expectedKeys: readonly string[]
-): { titles: Record<string, string>; missing: string[] } => {
+): MetaTitlesResult => {
   const start = agentText.indexOf("{");
   const end = agentText.lastIndexOf("}");
-  let parsed: unknown;
+  let parsed: FrontmatterValue | undefined;
   if (start !== -1 && end > start) {
     try {
       parsed = JSON.parse(agentText.slice(start, end + 1));
@@ -152,16 +190,13 @@ export const parseMetaTitles = (
       parsed = undefined;
     }
   }
-  const record =
-    typeof parsed === "object" && parsed !== null
-      ? (parsed as Record<string, unknown>)
-      : {};
+  const record: FrontmatterData = isKeyedObject(parsed) ? parsed : {};
 
   const titles: Record<string, string> = {};
   const missing: string[] = [];
   for (const key of expectedKeys) {
     const value = record[key];
-    if (typeof value === "string" && value.trim() !== "") {
+    if (isString(value) && value.trim() !== "") {
       titles[key] = value;
     } else {
       missing.push(key);

package/src/cli/coalesce.ts

@@ -1,43 +0,0 @@
-/**
- * Wrap an async task so it never runs concurrently with itself. Triggering the
- * returned function while a run is in flight coalesces into a single trailing
- * run after the current one settles.
- *
- * Dev regeneration (`scanProject` + `generateRuntime`) is expensive on a large
- * project — a full content re-scan that allocates big strings. A plain debounce
- * still lets a fast burst of watch events (or, before it was fixed, a `.blume/`
- * watch storm) start a new scan before the previous finished, piling up
- * overlapping scans until the heap is exhausted (observed as an OOM after
- * minutes of looping). Single-flighting bounds it to one scan at a time while
- * still guaranteeing a final run reflects the latest change.
- *
- * The task must not reject: a rejection would surface as an unhandled promise
- * rejection, so callers handle their own errors and always resolve.
- */
-export const coalescedRunner = (task: () => Promise<void>): (() => void) => {
-  let inFlight: Promise<void> | null = null;
-  let pending = false;
-
-  // Drain any run requested during the current run, then release the lock. The
-  // `inFlight` promise is assigned synchronously by the caller below, so a
-  // re-entrant trigger sees the lock immediately and only sets `pending`.
-  const cycle = async (): Promise<void> => {
-    try {
-      do {
-        pending = false;
-        // oxlint-disable-next-line no-await-in-loop -- serialized by design
-        await task();
-      } while (pending);
-    } finally {
-      inFlight = null;
-    }
-  };
-
-  return () => {
-    if (inFlight) {
-      pending = true;
-      return;
-    }
-    inFlight = cycle();
-  };
-};