blume 1.3.1 → 1.4.1

package/src/translate/meta.ts

@@ -0,0 +1,149 @@
+import { readFile } from "node:fs/promises";
+
+import { dirname, join, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import { createModuleLoader } from "../core/load-module.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import { folderMetaSchema } from "../core/schema.ts";
+import type { FolderMeta } from "../core/schema.ts";
+import type { Diagnostic } from "../core/types.ts";
+
+/**
+ * Folder-nav `meta.ts` titles are translatable under the `dir` parser ONLY:
+ * per-locale meta is a whole-file replacement, not a merge (`applyFolderMeta`
+ * looks up `<locale>/<group>` and falls back to shared meta, never to the
+ * default locale's file), and the `dot` parser has no per-locale meta
+ * mechanism at all. So the generated module must copy EVERY source key
+ * (order/pages/icon/collapsed) with only the title translated — otherwise the
+ * locale's navigation loses its ordering.
+ */
+
+/** One default-locale meta file whose title can be translated. */
+export interface TranslatableMeta {
+  /** The parsed meta module; copied wholesale into the generated module. */
+  data: FolderMeta;
+  /** Directory relative to the owning source's content root (`""` = root). */
+  dir: string;
+  /** Absolute path of the source meta file. */
+  file: string;
+  /** The owning source's content root (locale directories live under it). */
+  contentRoot: string;
+  /** Raw source text at discovery time — what the ledger hashes. */
+  raw: string;
+  /** POSIX root-relative path of the source meta file — the ledger key. */
+  sourceRel: string;
+  /** The source title to translate. */
+  title: string;
+}
+
+const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
+
+/** Where a locale's generated meta module lives (always written as `meta.ts`). */
+export const metaTargetPath = (
+  meta: TranslatableMeta,
+  locale: string
+): string => join(meta.contentRoot, locale, meta.dir, "meta.ts");
+
+/**
+ * Discover the default-locale `meta.{ts,js,mjs}` files whose titles a
+ * translation run covers. Skips (in order): non-`dir` i18n projects entirely,
+ * files inside a configured locale directory (those ARE translations),
+ * factory-form modules (a warning — the generator can't re-emit a function),
+ * modules that fail meta validation (the scan already errors on those), and
+ * modules with no `title` (nothing to translate).
+ */
+export const discoverTranslatableMeta = async (
+  project: BlumeProject
+): Promise<{ metas: TranslatableMeta[]; diagnostics: Diagnostic[] }> => {
+  const { i18n } = project.config;
+  if (!i18n || i18n.parser !== "dir") {
+    return { diagnostics: [], metas: [] };
+  }
+  const localeDirs = new Set(
+    i18n.locales.flatMap((locale) =>
+      locale.code === i18n.defaultLocale ? [] : [locale.code.toLowerCase()]
+    )
+  );
+
+  const load = createModuleLoader();
+  const metas: TranslatableMeta[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  const roots = project.sources.flatMap((source) =>
+    source.staged || !source.contentRoot ? [] : [source.contentRoot]
+  );
+  for (const contentRoot of roots) {
+    // oxlint-disable-next-line no-await-in-loop -- a project has O(1) sources
+    const files = await glob(META_FILES, {
+      absolute: true,
+      cwd: contentRoot,
+      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+      onlyFiles: true,
+    });
+    for (const file of files.toSorted()) {
+      const dir = relative(contentRoot, dirname(file));
+      const first = dir.split("/")[0]?.toLowerCase();
+      if (first && localeDirs.has(first)) {
+        continue;
+      }
+      // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
+      const [raw, mod] = await Promise.all([
+        readFile(file, "utf-8"),
+        load(file),
+      ]);
+      if (typeof mod === "function") {
+        diagnostics.push({
+          code: "BLUME_TRANSLATE_META_FACTORY",
+          file,
+          message:
+            "This meta file default-exports a function, so `blume translate` cannot generate per-locale copies of it.",
+          severity: "warning",
+          suggestion:
+            "Export a plain object, or author the locale's meta file by hand.",
+        });
+        continue;
+      }
+      const parsed = folderMetaSchema.safeParse(mod);
+      if (!parsed.success || parsed.data.title === undefined) {
+        continue;
+      }
+      metas.push({
+        contentRoot,
+        data: parsed.data,
+        dir: dir === "." ? "" : dir,
+        file,
+        raw,
+        sourceRel: relative(project.context.root, file),
+        title: parsed.data.title,
+      });
+    }
+  }
+  return { diagnostics, metas };
+};
+
+/**
+ * Emit the per-locale meta module: every source key copied verbatim, only the
+ * title swapped for its translation. Keys alphabetical, values as JSON.
+ */
+export const generateMetaModule = (
+  meta: FolderMeta,
+  translatedTitle: string
+): string => {
+  const data: Record<string, unknown> = {
+    ...meta,
+    title: translatedTitle,
+  };
+  const lines = Object.keys(data)
+    .toSorted()
+    .filter((key) => data[key] !== undefined)
+    .map((key) => `  ${key}: ${JSON.stringify(data[key])},`);
+  return [
+    "// Generated by `blume translate` — edit the default locale's meta file",
+    "// and rerun the translation instead of editing this copy.",
+    "export default {",
+    ...lines,
+    "};",
+    "",
+  ].join("\n");
+};

package/src/translate/prompts.ts

@@ -0,0 +1,95 @@
+import type { LocaleConfig } from "../core/schema.ts";
+
+/**
+ * The frontmatter key paths whose *values* an agent may translate. Everything
+ * else in the frontmatter is copied from the source verbatim by the validator,
+ * so this list is both the prompt's instruction and the reconciliation
+ * contract in `validate.ts`.
+ */
+export const TRANSLATABLE_KEY_PATHS: readonly (readonly string[])[] = [
+  ["title"],
+  ["description"],
+  ["sidebar", "label"],
+  ["sidebar", "badge"],
+  ["seo", "title"],
+  ["seo", "description"],
+];
+
+/** "French (fr)" — the configured display label plus the code. */
+const localeName = (locale: LocaleConfig): string =>
+  `${locale.label} (${locale.code})`;
+
+const KEY_LIST = TRANSLATABLE_KEY_PATHS.map((path) => path.join(".")).join(
+  ", "
+);
+
+/**
+ * The page-translation prompt. Delivered over stdin (no argv limits), so the
+ * full source file rides along inline. When the page was translated before,
+ * the previous translation rides along too: without it, every retranslation
+ * is a from-scratch rewrite in which the agent re-decides register, dialect,
+ * and terminology (du vs Sie, pt-BR vs pt-PT) and churns the whole page for
+ * a one-paragraph source edit.
+ */
+export const pagePrompt = (
+  sourceText: string,
+  target: LocaleConfig,
+  source: LocaleConfig,
+  previousTranslation?: string
+): string => {
+  const styleRule =
+    target.style === undefined
+      ? ""
+      : `
+- Write the translation in this style: ${target.style}`;
+  const previousRule =
+    previousTranslation === undefined
+      ? ""
+      : `
+- A translation of an earlier revision of this page is included below. Match its register, formality, dialect, and terminology exactly; re-translate only what the changed source requires and keep everything else word-for-word identical.${
+          target.style === undefined
+            ? ""
+            : " Where the previous translation disagrees with the style rule above, the style rule wins."
+        }`;
+  const previousSection =
+    previousTranslation === undefined
+      ? ""
+      : `
+The previous translation begins after this line and ends at the "page source" marker.
+${previousTranslation}`;
+  return `Translate the following documentation page from ${localeName(
+    source
+  )} into ${localeName(target)}.
+
+Rules:
+- Translate the prose: headings, paragraphs, list items, table cells, admonitions, and image alt text.
+- In the YAML frontmatter, translate ONLY the values of these keys: ${KEY_LIST}. Copy every other frontmatter key and value exactly as written.
+- Never translate or alter: code blocks, inline code, import/export statements, JSX/MDX component names and their attributes, URLs, link targets, HTML tags, or frontmatter keys.
+- Preserve the document structure exactly: the same headings, the same lists and tables, and the same number of code fences.${styleRule}${previousRule}
+- Output ONLY the complete translated file. Do not wrap it in a code fence. Do not add commentary before or after it.
+${previousSection}
+The page source begins after this line.
+${sourceText}`;
+};
+
+/**
+ * The sidebar-titles prompt: a JSON object of `{directory: title}` in, the
+ * same keys with translated values out.
+ */
+export const metaPrompt = (
+  titles: Record<string, string>,
+  target: LocaleConfig,
+  source: LocaleConfig
+): string => `Translate the following documentation sidebar section titles from ${localeName(
+  source
+)} into ${localeName(target)}.
+
+The input is a JSON object mapping a directory path to its title. Reply with ONLY a JSON object that has exactly the same keys, where each value is the title translated into ${localeName(
+  target
+)}. Do not translate the keys. Do not add commentary.${
+  target.style === undefined
+    ? ""
+    : `\nWrite the titles in this style: ${target.style}`
+}
+
+${JSON.stringify(titles, null, 2)}`;

package/src/translate/report.ts

@@ -0,0 +1,354 @@
+import { colors } from "consola/utils";
+import type { ColorFunction } from "consola/utils";
+
+import { AGENTS } from "../audit/agent.ts";
+import type { AgentKind } from "../audit/agent.ts";
+import { countBySeverity } from "../core/diagnostics.ts";
+import type { Diagnostic } from "../core/types.ts";
+import type {
+  TranslateItemResult,
+  TranslateItemStatus,
+  TranslateResult,
+} from "./run.ts";
+import type {
+  MetaWorkEntry,
+  TranslateWorkList,
+  WorkItem,
+  WorkStatus,
+} from "./work-list.ts";
+
+/**
+ * The live progress UI, colored via consola's `colors` (which honors
+ * NO_COLOR/FORCE_COLOR and TTY detection), matching the eval report's palette.
+ * Render functions are pure; the renderer takes an injectable `write`/`now` so
+ * tests never touch a real TTY or clock. The command sends everything here to
+ * stderr via the raw `write` — never `logger.info`, which consola drops in
+ * test and CI environments.
+ */
+
+const ESC = String.fromCodePoint(27);
+
+const GLYPH: Record<TranslateItemStatus, string> = {
+  failed: "✖",
+  partial: "!",
+  translated: "✔",
+};
+
+const STATUS_COLOR: Record<TranslateItemStatus, ColorFunction> = {
+  failed: colors.red,
+  partial: colors.yellow,
+  translated: colors.green,
+};
+
+export const SPINNER_FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏",
+];
+
+/** How often the TTY spinner advances (one frame per interval). */
+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"
+    ? `${item.sourceRel} → ${item.locale}`
+    : `meta title${item.entries.length === 1 ? "" : "s"} (${item.entries.length}) → ${item.locale}`;
+
+/**
+ * The in-flight spinner line a TTY rewrites in place: the oldest active
+ * item's label, how many more lanes are running, and the run's progress.
+ */
+export const spinnerLine = (
+  active: WorkItem[],
+  done: number,
+  total: number,
+  frame: number
+): string => {
+  const first = active[0] as WorkItem;
+  const more = active.length > 1 ? ` (+${active.length - 1} more)` : "";
+  return `  ${colors.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length] as string)} ${itemLabel(first)}${more} ${colors.dim(`${done}/${total}`)}`;
+};
+
+/** The permanent line printed when an item finishes. */
+export const itemEndLine = (result: TranslateItemResult): string => {
+  const color = STATUS_COLOR[result.status];
+  const glyph = color(GLYPH[result.status]);
+  const label = itemLabel(result.item);
+  if (result.status === "translated") {
+    const cells = [seconds(result.durationMs), money(result.costUsd)]
+      .filter((cell) => cell !== "")
+      .join(" ");
+    return `  ${glyph} ${label} ${colors.dim(cells)}`;
+  }
+  const word = result.status === "partial" ? "partial" : "failed";
+  return `  ${glyph} ${label} ${color(word)}${
+    result.detail ? colors.dim(`: ${result.detail}`) : ""
+  }`;
+};
+
+/** The header line the command prints before the first item runs. */
+export const translateHeaderLine = (
+  itemCount: number,
+  localeCount: number,
+  agent: AgentKind
+): string =>
+  `${colors.bold("blume translate")}  ${itemCount} item(s) · ${localeCount} locale(s) · ${AGENTS[agent].name}`;
+
+/**
+ * `Translated 11 files into 2 locales · 1 failed · 2 adopted · 8 already up to
+ * date · 4m 12s · $0.41` (cost only when the agent reports one).
+ */
+export const translateSummaryLine = (
+  result: TranslateResult,
+  workList: TranslateWorkList
+): string => {
+  const { counts } = result;
+  const parts = [
+    `Translated ${counts.translated} file${counts.translated === 1 ? "" : "s"} into ${workList.targetLocales.length} locale${workList.targetLocales.length === 1 ? "" : "s"}`,
+    counts.failed > 0 ? `${counts.failed} failed` : "",
+    counts.partial > 0 ? `${counts.partial} partial` : "",
+    workList.untracked.length > 0 ? `${workList.untracked.length} adopted` : "",
+    workList.upToDate > 0 ? `${workList.upToDate} already up to date` : "",
+    duration(result.durationMs),
+    money(result.costUsd),
+  ].filter((part) => part !== "");
+  return parts.join(" · ");
+};
+
+/** Dim warnings for work-list diagnostics (e.g. a factory-form meta file). */
+export const diagnosticLines = (diagnostics: Diagnostic[]): string[] =>
+  diagnostics.map(
+    (diagnostic) => `  ${colors.yellow("⚠")} ${colors.dim(diagnostic.message)}`
+  );
+
+/** Every (source, locale, status) drift row in a work list, pages then meta. */
+const driftRows = (
+  workList: TranslateWorkList
+): { locale: string; sourceRel: string; status: WorkStatus }[] =>
+  workList.items.flatMap((item) =>
+    item.kind === "page"
+      ? [
+          {
+            locale: item.locale,
+            sourceRel: item.sourceRel,
+            status: item.status,
+          },
+        ]
+      : item.entries.map((entry: MetaWorkEntry) => ({
+          locale: item.locale,
+          sourceRel: entry.meta.sourceRel,
+          status: entry.status,
+        }))
+  );
+
+/** One line per missing/stale pair, plus dim lines for untracked adoptions. */
+export const checkLines = (workList: TranslateWorkList): string[] => [
+  ...driftRows(workList).map(
+    (row) =>
+      `  ${colors.red("✖")} ${row.sourceRel} → ${row.locale} ${colors.dim(row.status)}`
+  ),
+  ...workList.untracked.map(
+    (entry) =>
+      `  ${colors.dim(`⊘ ${entry.sourceRel} → ${entry.locale} untracked (adopted by the next translate run)`)}`
+  ),
+];
+
+/** The `--check` totals: `2 missing · 1 stale · 1 untracked · 14 up to date`. */
+export const checkSummaryLine = (workList: TranslateWorkList): string => {
+  const rows = driftRows(workList);
+  const missing = rows.filter((row) => row.status === "missing").length;
+  const stale = rows.filter((row) => row.status === "stale").length;
+  const parts = [
+    missing > 0 ? `${missing} missing` : "",
+    stale > 0 ? `${stale} stale` : "",
+    workList.untracked.length > 0
+      ? `${workList.untracked.length} untracked`
+      : "",
+    `${workList.upToDate} up to date`,
+  ].filter((part) => part !== "");
+  return parts.join(" · ");
+};
+
+/** Whether a work list fails the `--check` gate (untracked never does). */
+export const hasDrift = (workList: TranslateWorkList): boolean =>
+  workList.items.length > 0;
+
+/**
+ * The machine-readable `--check` report. The `diagnostics` + `summary` shape
+ * matches `blume validate/audit/eval --json` exactly, with the drift report
+ * under `translate`.
+ */
+export const checkReportJson = (workList: TranslateWorkList): string => {
+  const locales: Record<
+    string,
+    { missing: string[]; stale: string[]; untracked: string[] }
+  > = {};
+  for (const locale of workList.targetLocales) {
+    locales[locale] = { missing: [], stale: [], untracked: [] };
+  }
+  for (const row of driftRows(workList)) {
+    locales[row.locale]?.[row.status].push(row.sourceRel);
+  }
+  for (const entry of workList.untracked) {
+    locales[entry.locale]?.untracked.push(entry.sourceRel);
+  }
+  return `${JSON.stringify(
+    {
+      diagnostics: workList.diagnostics,
+      summary: countBySeverity(workList.diagnostics),
+      translate: { locales, upToDate: workList.upToDate },
+    },
+    null,
+    2
+  )}\n`;
+};
+
+/** One run result lowered to JSON-friendly, root-relative fields. */
+const resultJson = (result: TranslateItemResult): Record<string, unknown> => ({
+  costUsd: result.costUsd,
+  detail: result.detail,
+  durationMs: result.durationMs,
+  kind: result.item.kind,
+  locale: result.item.locale,
+  status: result.status,
+  ...(result.item.kind === "page"
+    ? { source: result.item.sourceRel, target: result.item.targetRel }
+    : {
+        sources: result.item.entries.map((entry) => entry.meta.sourceRel),
+      }),
+});
+
+/** The machine-readable report for a translation run (`--json`). */
+export const translateReportJson = (
+  result: TranslateResult,
+  workList: TranslateWorkList
+): string => {
+  const diagnostics = [...workList.diagnostics, ...result.diagnostics];
+  return `${JSON.stringify(
+    {
+      diagnostics,
+      summary: countBySeverity(diagnostics),
+      translate: {
+        adopted: workList.untracked.length,
+        agent: result.agent,
+        costUsd: result.costUsd,
+        counts: result.counts,
+        durationMs: result.durationMs,
+        results: result.results.map(resultJson),
+        upToDate: workList.upToDate,
+      },
+    },
+    null,
+    2
+  )}\n`;
+};
+
+export interface ProgressRenderer {
+  onProgress: (
+    event:
+      | {
+          kind: "item-end";
+          index: number;
+          result: TranslateItemResult;
+          total: number;
+        }
+      | { kind: "item-start"; index: number; item: WorkItem; total: number }
+  ) => void;
+  stop: () => void;
+}
+
+/**
+ * Live progress: on a TTY the in-flight items render as one spinner line
+ * rewritten in place (`\r\x1B[K`) — a concurrent run shows the oldest active
+ * item plus a `(+n more)` count — and each completion prints its permanent
+ * line above it; off-TTY (CI) there is no interval and only the permanent
+ * per-item lines print.
+ */
+export const createProgressRenderer = (options: {
+  isTTY: boolean;
+  write: (chunk: string) => void;
+  now?: () => number;
+}): ProgressRenderer => {
+  const now = options.now ?? (() => performance.now());
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const active = new Map<number, WorkItem>();
+  let done = 0;
+  let total = 0;
+  let startedAt = 0;
+
+  const paint = (): void => {
+    if (active.size > 0) {
+      const frame = Math.floor((now() - startedAt) / SPINNER_INTERVAL_MS);
+      options.write(
+        `${REWRITE}${spinnerLine([...active.values()], done, total, frame)}`
+      );
+    }
+  };
+  const clearTimer = (): void => {
+    if (timer) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  return {
+    onProgress(event) {
+      ({ total } = event);
+      if (event.kind === "item-start") {
+        active.set(event.index, event.item);
+        if (!options.isTTY) {
+          return;
+        }
+        if (!timer) {
+          startedAt = now();
+          timer = setInterval(paint, SPINNER_INTERVAL_MS);
+          timer.unref?.();
+        }
+        paint();
+        return;
+      }
+      active.delete(event.index);
+      done += 1;
+      const line = itemEndLine(event.result);
+      if (!options.isTTY) {
+        options.write(`${line}\n`);
+        return;
+      }
+      options.write(`${REWRITE}${line}\n`);
+      if (active.size > 0) {
+        paint();
+      } else {
+        clearTimer();
+      }
+    },
+    stop() {
+      clearTimer();
+      active.clear();
+    },
+  };
+};