scratch-l10n 6.1.102 → 6.1.103

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scratch-l10n",
-  "version": "6.1.102",
+  "version": "6.1.103",
   "description": "Localization for the Scratch 3.0 components",
   "main": "./dist/l10n.js",
   "browser": "./src/index.mjs",
@@ -55,7 +55,7 @@
     "lodash.defaultsdeep": "4.6.1",
     "mkdirp": "3.0.1",
     "transifex": "1.6.6",
-    "tsx": "4.23.1"
+    "tsx": "4.23.4"
   },
   "devDependencies": {
     "@babel/cli": "7.29.7",

package/scripts/lib/help-utils.mts

@@ -61,16 +61,22 @@ const DRY_RUN = !!process.env.DRY_RUN && process.env.DRY_RUN !== '0' && process.
 /**
  * Wall-clock budget for a single run, in minutes (override with `HELP_SYNC_MAX_MINUTES`). When it is
  * exceeded the sync stops starting new writes, persists the baseline for everything that finished, and
- * exits cleanly. This matters because the baseline is restored from and saved to a CI cache whose save
- * step only runs when the job is not cancelled: finishing under the job's hard `timeout-minutes` keeps
- * partial progress, so a first-time full sync that cannot complete in one run converges over several
- * daily runs instead of losing everything to a timeout.
+ * exits cleanly. Durability across a cancellation is already handled by the incremental baseline flush
+ * plus the workflow's save-on-cancel step, so this budget is the graceful path, not the safety net:
+ * exiting cleanly under the step's hard `timeout-minutes` lets the run print its failure summary, exit
+ * non-zero on genuine errors, and finish as a success rather than a cancellation -- so real problems
+ * surface (and alert) while the baseline is still converging instead of being masked by a timeout.
  */
 const RUN_TIME_BUDGET_MS = (() => {
   const minutes = Number(process.env.HELP_SYNC_MAX_MINUTES)
   return (Number.isFinite(minutes) && minutes > 0 ? minutes : 24) * 60_000
 })()
-/** When this run began, used to enforce {@link RUN_TIME_BUDGET_MS}. */
+/**
+ * When this run began, used to enforce {@link RUN_TIME_BUDGET_MS}. Each sync phase (`pull:help:names`,
+ * `pull:help:articles`) runs as its own job step with its own step-level `timeout-minutes`, so this
+ * per-process clock starts alongside that step's timeout: the soft budget sits just under it, stopping
+ * new writes and exiting cleanly (reporting failures) before the step is hard-killed.
+ */
 const runStartedAt = Date.now()
 /** Count of changed, supported pairs left unattempted because the run hit its time budget. */
 let deferredForBudget = 0
@@ -192,6 +198,49 @@ const markSynced = (resource: string, locale: string): void => {
   }
 }
 
+/** Minimum interval between incremental baseline flushes, to bound both progress loss and write churn. */
+const BASELINE_FLUSH_INTERVAL_MS = 15_000
+/** When the baseline was last flushed to disk, used to debounce {@link maybeFlushBaseline}. */
+let lastBaselineFlushAt = 0
+
+/**
+ * Merge the pairs synced so far into the baseline and persist it to disk. A no-op in a dry run (which
+ * must never mutate the baseline) and before change detection is initialized: a script that calls
+ * saveItem without initChangeDetection (the locale-debug pull) leaves baseline/currentStats empty, and
+ * persisting then would clobber the real baseline with an empty file, forcing the next sync to re-sync
+ * everything. Safe to call from concurrently-running saveItem tasks: JS is single-threaded and
+ * {@link saveBaseline} writes atomically, so calls cannot interleave a partial file.
+ */
+const flushBaseline = (): void => {
+  if (DRY_RUN || !changeDetectionReady) {
+    return
+  }
+  for (const [key, timestamp] of syncedPairs) {
+    baseline.set(key, timestamp)
+  }
+  saveBaseline(baseline)
+  lastBaselineFlushAt = Date.now()
+}
+
+/**
+ * Persist the baseline if enough time has passed since the last flush. Called as the sync makes
+ * progress so a run cancelled mid-sync (for example by its phase step's timeout) still keeps what it
+ * finished on disk, letting the workflow's save-on-cancel step cache it and the next run continue
+ * instead of restarting a full sync. The graceful path still calls {@link flushBaseline} once more at
+ * the end via {@link finalizeSync}.
+ */
+const maybeFlushBaseline = (): void => {
+  // Nothing to persist in a dry run or before change detection is initialized, so skip the debounce
+  // entirely rather than calling flushBaseline (a no-op there) on every batch. flushBaseline keeps the
+  // same guards for the finalizeSync path.
+  if (DRY_RUN || !changeDetectionReady) {
+    return
+  }
+  if (Date.now() - lastBaselineFlushAt >= BASELINE_FLUSH_INTERVAL_MS) {
+    flushBaseline()
+  }
+}
+
 /**
  * Finish the run: persist the advanced baseline (unless this is a dry run) and print the failure
  * summary. Call once, after all saves have completed.
@@ -203,10 +252,7 @@ export const finalizeSync = (): void => {
         `${plannedWrites} Freshdesk write(s). No writes were issued and the baseline was left unchanged.`,
     )
   } else {
-    for (const [key, timestamp] of syncedPairs) {
-      baseline.set(key, timestamp)
-    }
-    saveBaseline(baseline)
+    flushBaseline()
     console.log(`Synced ${syncedPairs.size} (resource, locale) pair(s); baseline now holds ${baseline.size} entries.`)
   }
   if (deferredForBudget > 0) {
@@ -537,5 +583,8 @@ export const saveItem = async (item: TransifexResourceObject, languages: string[
         }
       }),
     )
+    // Persist progress periodically so a run cancelled mid-sync keeps what it finished (see
+    // maybeFlushBaseline); the interval debounce keeps this from writing on every batch.
+    maybeFlushBaseline()
   }
 }

package/scripts/lib/sync-baseline.mts

@@ -8,7 +8,7 @@
  * The file location is overridable via `HELP_SYNC_BASELINE_FILE` so the persistence mechanism (a
  * committed repo file vs. a restored CI cache) can change without touching this code.
  */
-import { readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs'
 import { dirname } from 'path'
 import { messageOf } from './errors.mts'
 
@@ -42,7 +42,11 @@ export const loadBaseline = (path?: string): SyncBaseline => {
 }
 
 /**
- * Persist the baseline to disk, sorted by key for a stable, diff-friendly file.
+ * Persist the baseline to disk, sorted by key for a stable, diff-friendly file. The write is atomic
+ * (write a temp file, then rename over the target) because the sync flushes the baseline repeatedly
+ * as it makes progress and relies on the file surviving an abrupt kill (a job timeout mid-write). A
+ * partial `writeFileSync` would otherwise leave a truncated file that {@link loadBaseline} discards as
+ * corrupt, throwing away every pair synced so far. `renameSync` within the same directory is atomic.
  * @param baseline - the baseline to write
  * @param path - override for the baseline file location; defaults to `HELP_SYNC_BASELINE_FILE` or {@link DEFAULT_BASELINE_PATH}
  */
@@ -53,5 +57,7 @@ export const saveBaseline = (baseline: SyncBaseline, path?: string): void => {
   for (const key of [...baseline.keys()].sort()) {
     sorted[key] = baseline.get(key) ?? null
   }
-  writeFileSync(file, JSON.stringify(sorted, null, 2) + '\n')
+  const tempFile = `${file}.tmp`
+  writeFileSync(tempFile, JSON.stringify(sorted, null, 2) + '\n')
+  renameSync(tempFile, file)
 }