@verbatra/sdk 0.6.2 → 0.6.4

package/dist/index.js

@@ -31,27 +31,31 @@ var translationMemorySchema = z.object({
 function cacheFilePath(cwd) {
   return resolve(cwd, CACHE_FILE_NAME);
 }
+var UNUSABLE = { memory: EMPTY_MEMORY, writable: true };
 async function readTranslationMemory(path, fs) {
   let read;
   try {
     read = await fs.readFileBounded(path, MAX_CACHE_FILE_BYTES);
   } catch {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   if (read.kind !== "ok") {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   let parsed;
   try {
     parsed = JSON.parse(read.content);
   } catch {
-    return EMPTY_MEMORY;
+    return UNUSABLE;
   }
   const result = translationMemorySchema.safeParse(parsed);
-  if (!result.success || result.data.version !== CURRENT_VERSION) {
-    return EMPTY_MEMORY;
+  if (!result.success) {
+    return UNUSABLE;
   }
-  return result.data;
+  if (result.data.version !== CURRENT_VERSION) {
+    return { memory: EMPTY_MEMORY, writable: false };
+  }
+  return { memory: result.data, writable: true };
 }
 function lookupMemory(memory, fingerprint, locale, contentHash2) {
   return memory.entries[fingerprint]?.[locale]?.[contentHash2];
@@ -103,7 +107,10 @@ async function feedTranslationMemory(cwd, fs, fingerprint, additionsByLocale) {
   }
   try {
     const path = cacheFilePath(cwd);
-    const memory = await readTranslationMemory(path, fs);
+    const { memory, writable } = await readTranslationMemory(path, fs);
+    if (!writable) {
+      return;
+    }
     await writeTranslationMemory(path, applyAdditions(memory, fingerprint, additionsByLocale), fs);
   } catch {
   }
@@ -115,6 +122,18 @@ function defineConfig(config) {
 }
 
 // src/errors.ts
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function stringCode(error) {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return void 0;
+}
+function describeError(error, fallbackCode) {
+  return { code: stringCode(error) ?? fallbackCode, message: errorMessage(error) };
+}
 var SdkError = class extends Error {
   /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
   code;
@@ -1912,7 +1931,7 @@ async function loadExplicitWithMeta(explorer, configPath, cwd, fs) {
   try {
     result = await explorer.load(resolved);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
   const parsed = parseConfig(result?.config);
@@ -1937,7 +1956,7 @@ async function loadConfigWithMeta(options = {}) {
   try {
     result = await explorer.search(options.cwd);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
   if (result === null || result.isEmpty === true) {
@@ -2022,15 +2041,15 @@ async function acquireLock(path, fs, pollIntervalMs, deadline, notify) {
     if (await fs.createExclusive(path, lockPayload())) {
       return;
     }
+    if (notify !== void 0) {
+      await notify();
+    }
     if (Date.now() >= deadline) {
       throw new SdkError(
         "LOCK_CONTENDED",
         `Could not acquire the write lock at ${path}: another process may be holding it. If no verbatra process is currently running, this lock file was likely left behind by one that was killed; delete it and retry.`
       );
     }
-    if (notify !== void 0) {
-      await notify();
-    }
     const jitter = Math.random() * pollIntervalMs;
     await sleep(pollIntervalMs + jitter);
   }
@@ -2620,6 +2639,9 @@ async function fsyncDirBestEffort(path) {
   }
 }
 var nodeOps = {
+  mkdir: async (path) => {
+    await mkdir(path, { recursive: true });
+  },
   writeFile: (path, data) => writeFile(path, data, "utf8"),
   fsyncFile: (path) => fsyncPath(path),
   rename: (from, to) => rename(from, to),
@@ -2636,8 +2658,10 @@ function tempFileName2(path) {
   return join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`);
 }
 async function atomicWriteFile(path, data, ops = nodeOps) {
+  const directory = dirname(path);
   const tmp = tempFileName2(path);
   try {
+    await ops.mkdir(directory);
     await ops.writeFile(tmp, data);
     await ops.fsyncFile(tmp);
     await ops.rename(tmp, path);
@@ -2646,7 +2670,7 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
     throw error;
   }
   try {
-    await ops.fsyncDir(dirname(path));
+    await ops.fsyncDir(directory);
   } catch {
   }
 }
@@ -3309,6 +3333,12 @@ function extractPropertiesPlaceholders(value) {
 var UNICODE_ESCAPE = /^[0-9a-fA-F]{4}$/;
 var LEADING_WHITESPACE = /^[ \t\f]+/;
 var TRAILING_TERMINATOR = /(?:\r\n|\r|\n)$/;
+function detectLineTerminator(content) {
+  if (content.includes("\r\n")) {
+    return "\r\n";
+  }
+  return content.includes("\r") ? "\r" : "\n";
+}
 function isPropertiesWhitespace(char) {
   return char === " " || char === "	" || char === "\f";
 }
@@ -3514,7 +3544,7 @@ async function readStructure(filePath) {
     outcome = await readBounded2(filePath);
   } catch (error) {
     if (isFileNotFound(error)) {
-      return [];
+      return { items: [], terminator: "\n" };
     }
     throw new AdapterError("INVALID_STRUCTURE", "The destination file could not be read.");
   }
@@ -3524,13 +3554,16 @@ async function readStructure(filePath) {
   if (outcome.kind === "too-large") {
     throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
   }
-  return parseItems(outcome.content);
+  return {
+    items: parseItems(outcome.content),
+    terminator: detectLineTerminator(outcome.content)
+  };
 }
 async function serializePropertiesEntries(entries, filePath) {
-  const structure = await readStructure(filePath);
+  const { items, terminator } = await readStructure(filePath);
   const emitted = /* @__PURE__ */ new Set();
   const lines = [];
-  for (const item of structure) {
+  for (const item of items) {
     if (item.kind === "raw") {
       lines.push(item.text);
       continue;
@@ -3546,8 +3579,7 @@ async function serializePropertiesEntries(entries, filePath) {
       lines.push(formatEntry(key, entry.value));
     }
   }
-  return lines.length === 0 ? "" : `${lines.join("\n")}
-`;
+  return lines.length === 0 ? "" : `${lines.join(terminator)}${terminator}`;
 }
 function createPropertiesAdapter() {
   return createFlatFileAdapter({
@@ -3999,7 +4031,7 @@ async function readSource(config, cwd, fs, adapter) {
   try {
     return await adapter.read(sourcePath, config.sourceLocale);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError(
       "SOURCE_INVALID",
       `The source locale file at ${sourcePath} could not be read: ${detail}`
@@ -4100,6 +4132,9 @@ function gateCandidateValue(sourceEntry, candidateValue, adapter) {
   if (assessValueDegeneracy(sourceEntry.value, candidateValue).degenerate) {
     return { accepted: false, reason: "degenerate" };
   }
+  if (sourceEntry.value.trim() !== "" && candidateValue.trim() === "") {
+    return { accepted: false, reason: "empty" };
+  }
   return { accepted: true };
 }
 
@@ -4296,7 +4331,7 @@ function selectProvider(config, createProvider = buildProvider) {
   try {
     return createProvider(config);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorMessage(error);
     throw new SdkError(
       "PROVIDER_CONSTRUCTION_FAILED",
       `Failed to construct provider "${config.id}": ${detail}`
@@ -4519,13 +4554,6 @@ function budgetExceededNotice(tracker) {
 }
 
 // src/flow/locale-failure.ts
-function describeError(error) {
-  if (error instanceof Error) {
-    const code = error.code;
-    return { code: typeof code === "string" ? code : "LOCALE_FAILED", message: error.message };
-  }
-  return { code: "LOCALE_FAILED", message: String(error) };
-}
 function failureSummary(locale, error) {
   return {
     locale,
@@ -4545,7 +4573,7 @@ function failureSummary(locale, error) {
     unfilled: [],
     malformedRows: [],
     duplicateKeys: [],
-    error: describeError(error)
+    error: describeError(error, "LOCALE_FAILED")
   };
 }
 function deriveLocaleStatus(parts) {
@@ -4949,6 +4977,10 @@ function fanOutAccepted(params, group, acceptedRepresentative, outcome) {
     if (source === void 0) {
       continue;
     }
+    if (!gateCandidateValue(source, acceptedRepresentative.value, params.adapter).accepted) {
+      outcome.integrityMismatches.push(key);
+      continue;
+    }
     outcome.accepted.set(key, { value: acceptedRepresentative.value, source });
     if (flag !== void 0) {
       outcome.reviewFlags.set(key, flag);
@@ -4975,6 +5007,12 @@ function buildRequest3(params, entries) {
     ...params.adapter.comparePlaceholders !== void 0 ? { comparePlaceholders: params.adapter.comparePlaceholders } : {}
   };
 }
+async function shouldWriteTarget(params, path, changed) {
+  if (changed.accepted > 0 || changed.pruned > 0 || changed.generated > 0) {
+    return true;
+  }
+  return !await params.fs.fileExists(path);
+}
 async function runLocale(params) {
   const target = await readTargetResource({
     cwd: params.cwd,
@@ -5060,15 +5098,22 @@ async function runLocale(params) {
     merged.set(form.targetKey, { ...form.entry, namespace: target.namespace });
   }
   const path = localeFilePath(params.cwd, params.filesPattern, params.targetLocale);
-  await params.adapter.write(
-    {
-      locale: params.targetLocale,
-      namespace: target.namespace,
-      format: params.format,
-      entries: merged
-    },
-    path
-  );
+  const writeNeeded = await shouldWriteTarget(params, path, {
+    accepted: accepted.size,
+    pruned: pruned.length,
+    generated: generation.accepted.length
+  });
+  if (writeNeeded) {
+    await params.adapter.write(
+      {
+        locale: params.targetLocale,
+        namespace: target.namespace,
+        format: params.format,
+        entries: merged
+      },
+      path
+    );
+  }
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
   const notices = [
     ...pluralNotices,
@@ -5340,14 +5385,21 @@ async function createRunCacheState(input, config, cwd, dryRun, fs) {
   if (dryRun || input.cache === false) {
     return void 0;
   }
-  return {
-    memory: await readTranslationMemory(cacheFilePath(cwd), fs),
-    fingerprint: computeFingerprint(config),
-    additions: /* @__PURE__ */ new Map()
+  const { memory, writable } = await readTranslationMemory(cacheFilePath(cwd), fs);
+  return { memory, writable, fingerprint: computeFingerprint(config), additions: /* @__PURE__ */ new Map() };
+}
+function withCacheNotices(summaries, cache) {
+  if (cache === void 0 || cache.writable) {
+    return [...summaries];
+  }
+  const notice = {
+    code: "CACHE_VERSION_UNRECOGNIZED",
+    message: `${CACHE_FILE_NAME} carries a version this build does not recognize, so it was written by a newer verbatra. It was left untouched and this run used no cache. Upgrade verbatra, or delete the file to rebuild it in this build's format.`
   };
+  return summaries.map((summary) => ({ ...summary, notices: [...summary.notices, notice] }));
 }
 async function recordCacheAdditions(cwd, cache, fs) {
-  if (cache === void 0 || cache.additions.size === 0) {
+  if (cache === void 0 || cache.additions.size === 0 || !cache.writable) {
     return;
   }
   try {
@@ -5434,18 +5486,25 @@ async function runLocaleAt(context, targetLocales, localeIndex, runOne, results)
   context.onProgress?.({
     type: "locale-finished",
     locale: targetLocale,
-    translated: summary.translated.length
+    translated: summary.translated.length,
+    localeIndex,
+    totalLocales: targetLocales.length
   });
 }
 async function runLocalesWithProgress(context, targetLocales, runOne, concurrency) {
   const totalLocales = targetLocales.length;
   const results = new Array(totalLocales);
   let nextIndex = 0;
+  let abort;
   async function worker() {
-    while (nextIndex < totalLocales) {
+    while (abort === void 0 && nextIndex < totalLocales) {
       const localeIndex = nextIndex;
       nextIndex += 1;
-      await runLocaleAt(context, targetLocales, localeIndex, runOne, results);
+      try {
+        await runLocaleAt(context, targetLocales, localeIndex, runOne, results);
+      } catch (error) {
+        abort ??= { reason: error };
+      }
     }
   }
   const workerCount = Math.min(concurrency, totalLocales);
@@ -5454,6 +5513,9 @@ async function runLocalesWithProgress(context, targetLocales, runOne, concurrenc
     workers.push(worker());
   }
   await Promise.all(workers);
+  if (abort !== void 0) {
+    throw abort.reason;
+  }
   return results.filter((summary) => summary !== void 0);
 }
 async function runAllLocalesDry(context, targetLocales, concurrency) {
@@ -5530,7 +5592,8 @@ async function translate2(input, deps = {}) {
   };
   const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales, concurrency) : await runAllLocalesLive(context, config.targetLocales, concurrency);
   input.onProgress?.({ type: "run-finished", localesCompleted: summaries.length });
-  const { succeeded, partial, failed } = partition(summaries);
+  const locales = withCacheNotices(summaries, cache);
+  const { succeeded, partial, failed } = partition(locales);
   const usage = summaries.reduce(
     (total, summary2) => combineUsage(total, summary2.usage),
     void 0
@@ -5538,7 +5601,7 @@ async function translate2(input, deps = {}) {
   const budgetSummary = toBudgetSummary(budget);
   const summary = {
     dryRun,
-    locales: summaries,
+    locales,
     succeeded,
     partial,
     failed,
@@ -6110,12 +6173,12 @@ function classifyClear(row, sourceEntry, buckets) {
     buckets.withheld.add(row.key);
     return;
   }
-  buckets.accepted.set(row.key, { value: "", source: sourceEntry });
+  buckets.accepted.set(row.key, { value: "", source: sourceEntry, cleared: true });
 }
-function classifyRows(params, buckets) {
+function classifyRows(params, buckets, liveCandidates) {
   for (const row of params.sheet.rows) {
     if (row.translation === "") {
-      if (row.status === "changed") {
+      if (liveCandidates.has(row.key)) {
         buckets.unfilled.push(row.key);
       }
       trackBlankDrift(row, params, buckets);
@@ -6134,7 +6197,11 @@ function classifyRows(params, buckets) {
     }
     const reason = judge(row, sourceEntry, params.adapter);
     if (reason === void 0) {
-      buckets.accepted.set(row.key, { value: row.translation, source: sourceEntry });
+      buckets.accepted.set(row.key, {
+        value: row.translation,
+        source: sourceEntry,
+        cleared: false
+      });
     } else {
       buckets.mismatches.push(row.key);
       buckets.withheld.add(row.key);
@@ -6156,7 +6223,7 @@ function importLocale(params) {
     blankDrifted: /* @__PURE__ */ new Set(),
     unfilled: []
   };
-  classifyRows(params, buckets);
+  classifyRows(params, buckets, /* @__PURE__ */ new Set([...diff2.missing, ...diff2.changed]));
   const rowKeys = new Set(params.sheet.rows.map((row) => row.key));
   const invalidIcuSource = [...new Set(params.sourceInvalidIcuKeys)].filter((key) => rowKeys.has(key)).sort();
   const translated = [...buckets.accepted.keys()].sort();
@@ -6214,8 +6281,10 @@ function mergeAccepted(target, accepted) {
 }
 function sheetCacheAdditions(accepted) {
   const record = {};
-  for (const [, { value, source }] of accepted) {
-    record[contentHash(source)] = value;
+  for (const [, { value, source, cleared }] of accepted) {
+    if (!cleared) {
+      record[contentHash(source)] = value;
+    }
   }
   return record;
 }
@@ -6304,7 +6373,7 @@ async function importWorkbook(input, deps = {}) {
   try {
     data = await readWorkbook(bytes);
   } catch (error) {
-    throw new SdkError("SOURCE_INVALID", error.message);
+    throw new SdkError("SOURCE_INVALID", errorMessage(error));
   }
   const lock = await readLockFile(lockFilePath(cwd), fs);
   const ctx = {
@@ -6390,17 +6459,11 @@ function defaultRunTranslate(deps) {
 
 // src/watch/watch.ts
 var DEFAULT_DEBOUNCE_MS = 300;
-function describeError2(error) {
-  if (error instanceof Error) {
-    const code = error.code;
-    return { code: typeof code === "string" ? code : "WATCH_RUN_FAILED", message: error.message };
-  }
-  return { code: "WATCH_RUN_FAILED", message: String(error) };
-}
 async function watch(input, deps = {}) {
   const cwd = input.cwd ?? process.cwd();
   const debounceMs = input.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   const fs = deps.fs ?? defaultFs;
+  resolveRunConcurrency(input.concurrency, false, input.config);
   const sourcePath = localeFilePath(cwd, input.config.files.pattern, input.config.sourceLocale);
   if (!await fs.fileExists(sourcePath)) {
     throw new SdkError(
@@ -6427,7 +6490,7 @@ async function watch(input, deps = {}) {
     try {
       input.onRun({ status: "succeeded", summary: await runTranslate(runInput) });
     } catch (error) {
-      input.onRun({ status: "failed", error: describeError2(error) });
+      input.onRun({ status: "failed", error: describeError(error, "WATCH_RUN_FAILED") });
     }
   }
   function startRun() {