scratch-l10n 6.1.103 → 6.1.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scratch-l10n",
-  "version": "6.1.103",
+  "version": "6.1.105",
   "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.4"
+    "tsx": "4.23.8"
   },
   "devDependencies": {
     "@babel/cli": "7.29.7",
@@ -76,7 +76,7 @@
     "eslint": "9.39.5",
     "eslint-config-scratch": "11.0.53",
     "format-message-cli": "6.2.4",
-    "globals": "17.8.0",
+    "globals": "17.9.0",
     "husky": "8.0.3",
     "jshint": "2.13.6",
     "json": "9.0.6",
@@ -84,7 +84,7 @@
     "prettier": "3.9.6",
     "rimraf": "2.7.1",
     "scratch-semantic-release-config": "4.0.1",
-    "semantic-release": "25.0.8",
+    "semantic-release": "25.0.9",
     "webpack": "4.47.0",
     "webpack-cli": "3.3.12"
   },

package/scripts/lib/annotations.mts

@@ -0,0 +1,55 @@
+/**
+ * @file
+ * Emit GitHub Actions workflow annotations for problems found during a run, so they surface at the
+ * top of the run page (and inline in the log) instead of only in the raw output. A no-op outside
+ * GitHub Actions, so local runs stay quiet.
+ */
+
+/** True when running inside a GitHub Actions runner, where `::error::`/`::warning::` are meaningful. */
+const IN_GITHUB_ACTIONS = process.env.GITHUB_ACTIONS === 'true'
+
+/**
+ * GitHub surfaces only about the first ten annotations of each level per step in the run UI. A
+ * first-time full sync can fail on many items; emitting hundreds would be truncated there anyway and
+ * just spams the log, so cap what we emit and note once when the cap is reached. The full, unbounded
+ * list still goes to stderr and the failure summary.
+ */
+const MAX_ANNOTATIONS_PER_LEVEL = 10
+
+type AnnotationLevel = 'error' | 'warning' | 'notice'
+
+const emittedByLevel: Record<AnnotationLevel, number> = { error: 0, warning: 0, notice: 0 }
+
+// In a workflow command's message, only `%`, CR and LF are special and must be encoded. The order
+// matters: encode `%` first so the escapes we add are not themselves re-encoded.
+const escapeData = (value: string): string => value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A')
+
+// A property value (such as `title`) additionally encodes `:` and `,`.
+const escapeProperty = (value: string): string => escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C')
+
+/**
+ * Emit a single GitHub Actions annotation. No-op outside Actions and after the per-level display cap
+ * is reached (the full list still reaches stderr and the failure summary).
+ * @param annotation - the annotation to emit
+ * @param annotation.level - annotation severity (`error`, `warning`, or `notice`)
+ * @param annotation.message - the annotation body; may contain newlines and a URL
+ * @param annotation.title - optional short bold header (for example, the failing item)
+ */
+export const emitAnnotation = (annotation: { level: AnnotationLevel; message: string; title?: string }): void => {
+  const { level, message, title } = annotation
+  if (!IN_GITHUB_ACTIONS) {
+    return
+  }
+  emittedByLevel[level]++
+  if (emittedByLevel[level] > MAX_ANNOTATIONS_PER_LEVEL) {
+    if (emittedByLevel[level] === MAX_ANNOTATIONS_PER_LEVEL + 1) {
+      // Say so once; the rest are in the log and the summary rather than the annotations UI.
+      console.log(
+        `Reached the GitHub annotation display limit for ${level}s; further ${level}s appear in the log only.`,
+      )
+    }
+    return
+  }
+  const titlePart = title ? ` title=${escapeProperty(title)}` : ''
+  process.stdout.write(`::${level}${titlePart}::${escapeData(message)}\n`)
+}

package/scripts/lib/errors.mts

@@ -10,3 +10,51 @@
  * @returns the error message, or a string representation of a non-Error throw
  */
 export const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err))
+
+/**
+ * Describe where a `JSON.parse` failed, for a diagnostic message. V8 reports the byte offset (and, on
+ * newer Node, the line and column) in the error message; combined with the original text this pins the
+ * problem to a snippet and, for a flat `{"key": "value"}` file, the key whose value is malformed.
+ * Best-effort: returns undefined when the error is not a positioned JSON parse error or the text can't
+ * be read, so callers fall back to the plain message.
+ * @param error - the caught value (expected to be a `SyntaxError` from `JSON.parse`)
+ * @param text - the exact string that was parsed
+ * @returns a one-line description (location, nearby key, snippet), or undefined
+ */
+export const describeJsonParseError = (error: unknown, text: string): string | undefined => {
+  if (!(error instanceof SyntaxError) || typeof text !== 'string') {
+    return undefined
+  }
+  const posMatch = /in JSON at position (\d+)/.exec(error.message)
+  if (!posMatch) {
+    return undefined
+  }
+  const pos = Number(posMatch[1])
+  if (!Number.isFinite(pos)) {
+    return undefined
+  }
+  const lineColMatch = /\(line (\d+) column (\d+)\)/.exec(error.message)
+  const where = lineColMatch ? `line ${lineColMatch[1]}, column ${lineColMatch[2]}` : `position ${pos}`
+  // Recover the enclosing key of a flat KEYVALUEJSON object: the value that failed to parse is
+  // preceded by `"<key>":`, so scan back from the error position to that key. Heuristic (a colon or
+  // quote inside an earlier string can fool it), so it is reported as "near key", not an exact locator.
+  let nearKey: string | undefined
+  const before = text.slice(0, pos)
+  const colon = before.lastIndexOf(':')
+  if (colon > 0) {
+    const keyClose = before.lastIndexOf('"', colon)
+    if (keyClose > 0) {
+      const keyOpen = before.lastIndexOf('"', keyClose - 1)
+      if (keyOpen >= 0) {
+        nearKey = before.slice(keyOpen + 1, keyClose)
+      }
+    }
+  }
+  // A short, whitespace-collapsed window around the failure so the operator can eyeball the bad text.
+  const snippet = text
+    .slice(Math.max(0, pos - 30), pos + 30)
+    .replace(/\s+/g, ' ')
+    .trim()
+  const keyPart = nearKey ? ` near key "${nearKey}"` : ''
+  return `malformed JSON at ${where}${keyPart}: …${snippet}…`
+}

package/scripts/lib/help-utils.mts

@@ -4,7 +4,8 @@
  */
 import { promises as fsPromises } from 'fs'
 import { mkdirp } from 'mkdirp'
-import { messageOf } from './errors.mts'
+import { emitAnnotation } from './annotations.mts'
+import { describeJsonParseError, messageOf } from './errors.mts'
 import FreshdeskApi, {
   FreshdeskArticleCreate,
   FreshdeskArticleStatus,
@@ -14,7 +15,15 @@ import FreshdeskApi, {
 import { loadBaseline, saveBaseline, SyncBaseline } from './sync-baseline.mts'
 import { TransifexStringKeyValueJson, TransifexStringsKeyValueJson, TransifexStrings } from './transifex-formats.mts'
 import { TransifexResourceObject } from './transifex-objects.mts'
-import { txPull, txResourcesObjects, txAvailableLanguages, txResourceLanguageStats } from './transifex.mts'
+import {
+  txPull,
+  txResourcesObjects,
+  txAvailableLanguages,
+  txResourceLanguageStats,
+  transifexEditorLink,
+  txPullErrorCause,
+  SOURCE_LOCALE,
+} from './transifex.mts'
 import { emitWarning } from './warnings.mts'
 
 const FD = new FreshdeskApi('https://mitscratch.freshdesk.com', process.env.FRESHDESK_TOKEN ?? '')
@@ -25,12 +34,30 @@ const TX_PROJECT = 'scratch-help'
 // transparently by the client (paced requests, `Retry-After`-aware retries), so anything that reaches
 // here is a genuine problem worth a human's attention. `reportFailures` prints a consolidated summary
 // and fails the run at the end, so real errors are surfaced rather than lost in the log.
-const failures: { context: string; message: string }[] = []
-const recordFailure = (context: string, error: unknown): void => {
+const failures: { context: string; message: string; link?: string }[] = []
+const recordFailure = (context: string, error: unknown, link?: string): void => {
   const message = messageOf(error)
+  // A txPull error carries the failing (resource, locale) — and, for a parse failure, the raw text —
+  // on its `cause`, so we can build a Transifex link and describe malformed JSON without the call site
+  // passing anything. An explicit link still wins: some callers know the fix lives on the source (`en`)
+  // rather than the translation locale the pull used.
+  const cause = txPullErrorCause(error)
+  const resolvedLink =
+    link ??
+    (cause
+      ? transifexEditorLink({ project: cause.project, resource: cause.resource, lang: cause.locale })
+      : undefined)
+  const detail = cause?.buffer != null ? describeJsonParseError(error, cause.buffer) : undefined
+  const fullMessage = detail ? `${message} — ${detail}` : message
   // Genuine failures go to stderr (like the consolidated summary), so they stand apart from normal output.
-  process.stderr.write(`Error: ${context}: ${message}\n`)
-  failures.push({ context, message })
+  process.stderr.write(`Error: ${context}: ${fullMessage}${resolvedLink ? ` (${resolvedLink})` : ''}\n`)
+  failures.push({ context, message: fullMessage, link: resolvedLink })
+  // Surface it on the run page too (no-op off CI). The full list still lives in stderr and the summary.
+  emitAnnotation({
+    level: 'error',
+    title: context,
+    message: resolvedLink ? `${fullMessage}\n${resolvedLink}` : fullMessage,
+  })
 }
 
 /**
@@ -43,7 +70,7 @@ export const reportFailures = (): void => {
   }
   console.error(`\n${failures.length} item(s) failed to sync to Freshdesk:`)
   for (const failure of failures) {
-    console.error(`  - ${failure.context}: ${failure.message}`)
+    console.error(`  - ${failure.context}: ${failure.message}${failure.link ? ` (${failure.link})` : ''}`)
   }
   process.exitCode = 1
 }
@@ -386,6 +413,8 @@ const serializeNameSave = async (
           warnedKeys.add(warnedKey)
           emitWarning(
             `Warning: key "${key}" in Transifex resource "${resource.attributes.name}" refers to Freshdesk id ${id} which no longer exists. Remove this key from the Transifex resource.`,
+            // The key is removed from the source, so point at the source language, not a translation.
+            transifexEditorLink({ project: TX_PROJECT, resource: resource.attributes.slug, lang: SOURCE_LOCALE }),
           )
         }
         continue
@@ -409,7 +438,11 @@ const serializeNameSave = async (
     } catch (error) {
       // Record the failure so the job still reports a non-zero exit at the end, then move on to the
       // next entry.
-      recordFailure(`${resource.attributes.name} entry "${key}" for ${locale}`, error)
+      recordFailure(
+        `${resource.attributes.name} entry "${key}" for ${locale}`,
+        error,
+        transifexEditorLink({ project: TX_PROJECT, resource: resource.attributes.slug, lang: locale }),
+      )
       allOk = false
     }
   }
@@ -430,11 +463,13 @@ interface FreshdeskFolderInTransifex {
  * Internal function serialize Freshdesk requests to avoid getting rate limited
  * @param  json   object with keys corresponding to article ids
  * @param  locale language code
+ * @param  resourceSlug Transifex resource slug for these articles, used to build editor links in warnings and failures
  * @returns true if every article saved without a failure
  */
 const serializeFolderSave = async (
   json: TransifexStrings<FreshdeskFolderInTransifex>,
   locale: string,
+  resourceSlug: string,
 ): Promise<boolean> => {
   let allOk = true
   for (const [idString, value] of Object.entries(json)) {
@@ -457,6 +492,7 @@ const serializeFolderSave = async (
               `(${locale}); shorten them in Transifex: ${droppedTags
                 .map(tag => `"${tag}" (${tag.length} chars)`)
                 .join(', ')}.`,
+            transifexEditorLink({ project: TX_PROJECT, resource: resourceSlug, lang: locale }),
           )
         }
         body.tags = validTags
@@ -470,7 +506,11 @@ const serializeFolderSave = async (
     } catch (error) {
       // Record the failure so the job still reports a non-zero exit at the end, then move on to the
       // next article.
-      recordFailure(`article ${idString} for ${locale}`, error)
+      recordFailure(
+        `article ${idString} for ${locale}`,
+        error,
+        transifexEditorLink({ project: TX_PROJECT, resource: resourceSlug, lang: locale }),
+      )
       allOk = false
     }
   }
@@ -491,7 +531,7 @@ export const localizeFolder = async (folderAttributes: TransifexResourceObject,
       locale,
       'default',
     )
-    return await serializeFolderSave(data, locale)
+    return await serializeFolderSave(data, locale, folderAttributes.attributes.slug)
   } catch (e) {
     recordFailure(`${folderAttributes.attributes.slug} for ${locale}`, e)
     return false
@@ -579,7 +619,11 @@ export const saveItem = async (item: TransifexResourceObject, languages: string[
             markSynced(slug, l)
           }
         } catch (err) {
-          recordFailure(`saving ${slug} for ${l}`, err)
+          recordFailure(
+            `saving ${slug} for ${l}`,
+            err,
+            transifexEditorLink({ project: TX_PROJECT, resource: slug, lang: l }),
+          )
         }
       }),
     )

package/scripts/lib/transifex.mts

@@ -12,7 +12,63 @@ import {
 } from './transifex-objects.mts'
 
 const ORG_NAME = 'llk'
-const SOURCE_LOCALE = 'en'
+export const SOURCE_LOCALE = 'en'
+
+/**
+ * Build a deep link to the Transifex online editor for a resource in one language, matching the URL
+ * the web app uses: `app.transifex.com/<org>/<project>/translate/#<lang>/<resource>[/<stringId>]`.
+ * @param params - link target
+ * @param params.project - project slug (for example, `scratch-help`)
+ * @param params.resource - resource slug (for example, `Accessibility_4000040849_json`)
+ * @param params.lang - language code: the source ({@link SOURCE_LOCALE}) for a source-side fix, or the
+ *   translation locale for a bad translation
+ * @param params.stringId - optional Transifex numeric string id to focus a single string; omitted, the
+ *   link lands on the resource (with its first string shown)
+ * @returns the editor URL
+ */
+export const transifexEditorLink = (params: {
+  project: string
+  resource: string
+  lang: string
+  stringId?: string | number
+}): string => {
+  const { project, resource, lang, stringId } = params
+  const base = `https://app.transifex.com/${ORG_NAME}/${project}/translate/#${lang}/${resource}`
+  return stringId == null ? base : `${base}/${stringId}`
+}
+
+/**
+ * Shape attached to a {@link txPull} error's `cause`, carrying the context needed to locate and link
+ * the failing (resource, locale) in Transifex (and, for a parse failure, the raw file that failed).
+ */
+export interface TxPullErrorCause {
+  project: string
+  resource: string
+  locale: string
+  buffer: string | null
+}
+
+/**
+ * Read the {@link TxPullErrorCause} that {@link txPull} attaches to its errors, if present, so a
+ * failure handler can build a Transifex link (and read the raw buffer for a parse failure) without the
+ * call site threading that context through.
+ * @param error - the caught value
+ * @returns the cause, or undefined if the error did not come from txPull
+ */
+export const txPullErrorCause = (error: unknown): TxPullErrorCause | undefined => {
+  const cause = (error as { cause?: unknown } | null)?.cause
+  if (
+    cause &&
+    typeof cause === 'object' &&
+    typeof (cause as TxPullErrorCause).project === 'string' &&
+    typeof (cause as TxPullErrorCause).resource === 'string' &&
+    typeof (cause as TxPullErrorCause).locale === 'string' &&
+    (typeof (cause as TxPullErrorCause).buffer === 'string' || (cause as TxPullErrorCause).buffer === null)
+  ) {
+    return cause as TxPullErrorCause
+  }
+  return undefined
+}
 
 if (!process.env.TX_TOKEN) {
   throw new Error('TX_TOKEN is not defined.')

package/scripts/lib/warnings.mts

@@ -3,24 +3,30 @@
  * Shared helper for reporting non-fatal problems during help sync.
  */
 import { appendFileSync } from 'fs'
+import { emitAnnotation } from './annotations.mts'
 import { messageOf } from './errors.mts'
 
 /**
  * Log a warning to the console and, when the `WARNINGS_FILE` environment variable is set, append it
  * to that file. CI reads the file after the sync to surface warnings in the job summary and to send
  * a notification, so a warning is the right tool for a problem worth a human's attention that should
- * not fail the run (for example, a resource we deliberately skip).
+ * not fail the run (for example, a resource we deliberately skip). Also emits a GitHub Actions
+ * warning annotation (a no-op off CI) so the problem shows on the run page, not just in the log.
  * @param warning - the warning message; a trailing newline is added when written to the file
+ * @param link - optional convenience URL (for example, a Transifex editor deep link) appended to the
+ *   warning so a reader can jump straight to where the fix is made
  */
-export const emitWarning = (warning: string): void => {
-  console.warn(warning)
+export const emitWarning = (warning: string, link?: string): void => {
+  const line = link ? `${warning} (${link})` : warning
+  console.warn(line)
   if (process.env.WARNINGS_FILE) {
     // The file write is best-effort: emitWarning is the non-fatal path (often called from a catch
     // block), so a failed append must not turn a warning into a crash.
     try {
-      appendFileSync(process.env.WARNINGS_FILE, warning + '\n')
+      appendFileSync(process.env.WARNINGS_FILE, line + '\n')
     } catch (error) {
       console.warn(`Could not append to WARNINGS_FILE "${process.env.WARNINGS_FILE}": ${messageOf(error)}`)
     }
   }
+  emitAnnotation({ level: 'warning', message: line })
 }