@chesterbrains/translify-cli 0.2.0 → 0.4.0

package/README.md

@@ -126,14 +126,16 @@ flutter gen-l10n
 | `translify push` | Upload source and target files |
 | `translify pull` | Download translation files |
 | `translify status` | Exit 1 if local files differ from Translify |
+| `translify lint` | Exit 6 if translations in Translify have placeholder errors (or too many warnings) |
 | `translify publish <env>` | Publish an environment, e.g. `production` |
 
 Options:
 
 - `push`: `--dry-run`, `--overwrite-targets`, `--prune`, `-y/--yes`, `--namespace <ns>`, `--status <draft|needs-review|approved>`
 - `pull` and `status`: `--from <working|env:slug>`, `--locale <locale>` (as named on disk), `--namespace <ns>`, `--only-approved`
-- `publish`: `--fail-on-withheld`
-- `--json` on `push`, `pull`, `status` and `publish`: machine-readable output on stdout
+- `publish`: `--fail-on-withheld`, `--allow-errors`
+- `lint`: `--namespace <ns>`, `--locale <locale>` (as named on disk), `--severity <error|warning>` (only list cells whose worst issue is this severity; counts and the exit code are unaffected), `--max-warnings <n>`
+- `--json` on `push`, `pull`, `status`, `publish` and `lint`: machine-readable output on stdout
 - `--debug` (global): print error details and stack traces
 
 ## Conflict rules
@@ -154,6 +156,7 @@ When the project has **Require review** turned on in Translify:
 - `push` lands target-locale translations it writes as **needs review**. `--status draft` or `--status needs-review` picks the status explicitly, and `--status approved` approves them as they land. The source file is always approved. Each locale row shows the status its cells landed in, and the output counts approved translations that went back to review because this push changed their source text.
 - Without review, `push` approves everything it writes, and `--status draft` / `--status needs-review` are refused (`REVIEW_DISABLED`).
 - `publish` to an environment with **Publish approved text only** ships the last approved text of each translation. The output adds how many translations were **carried over** (the approved text went out instead of a newer, unapproved edit) and how many were **withheld** (never approved, so left out). Publishing still succeeds; `--fail-on-withheld` exits 5 when anything was withheld, for pipelines that must ship everything reviewed.
+- `publish` refuses when a translation that would go live has a placeholder error (a missing or extra placeholder, invalid ICU, a printf type mismatch). Nothing is published, the refused translations are listed like `lint` lists them, and the command exits 6. Warnings never block. On an environment with **Publish approved text only**, only approved translations count: one carried over from its last approved text never blocks. `--allow-errors` publishes anyway and reports how many went out with errors; the publish is recorded in the activity log with the override.
 - `pull --only-approved` writes the approved text from the working copy and leaves out translations that were never approved, for building a release bundle without publishing. `status --only-approved` compares against the same. It works with `--from working` only: environments already apply the gate.
 
 ## CI (GitHub Actions)
@@ -196,9 +199,24 @@ jobs:
           TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
 ```
 
+Fail CI when translations in Translify have placeholder errors:
+
+```yaml
+- run: npx translify lint --max-warnings 0
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+```
+
+`lint` checks what is stored in Translify, not your local files; run it after `push`, or before `pull`/`publish` on deploy.
+It covers what this repository pulls: only the namespaces of fixed-`namespace` rules, or the whole
+project when a rule uses `{namespace}`. It needs a key with the `pull` scope.
+
 Pull and publish on deploy:
 
 ```yaml
+- run: npx translify lint
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
 - run: npx translify pull
   env:
     TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
@@ -217,6 +235,7 @@ Pull and publish on deploy:
 | 3 | Plan quota exceeded |
 | 4 | Network failure, server error, push too large, CLI too old, transaction conflict, or rate limited after 3 retries |
 | 5 | `publish --fail-on-withheld`: the publish went through, but the review gate withheld some translations |
+| 6 | Placeholder errors: `lint` found them (or more warnings than `--max-warnings`), or `publish` refused because translations with errors would go live |
 
 The server's error `code` decides the exit code first; the HTTP status is only used for codes the CLI does not know.
 

package/dist/commands/lint.js

@@ -0,0 +1,56 @@
+import { CliError, EXIT } from '../errors.js';
+import { toTranslifyLocale } from '../patterns.js';
+import { renderLint } from '../render.js';
+export const LINT_SEVERITIES = ['error', 'warning'];
+export const LINT_UNSUPPORTED = 'This Translify server does not support lint yet.';
+/**
+ * What this repo would pull: the flag, else the whole project when any rule is a
+ * `{namespace}` wildcard, else the fixed namespaces. Undefined means no filter.
+ */
+export const lintNamespaces = (config, flag) => {
+    if (flag !== undefined)
+        return flag;
+    if (config.files.some((rule) => rule.namespace === undefined))
+        return undefined;
+    const fixed = [...new Set(config.files.flatMap((rule) => (rule.namespace === undefined ? [] : [rule.namespace])))].sort();
+    return fixed.length === 0 ? undefined : fixed.join(',');
+};
+export const parseMaxWarnings = (raw) => {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new CliError(EXIT.failed, '--max-warnings must be a whole number, 0 or more.');
+    return Number(raw);
+};
+/** Nest's own 404 for an unknown route has no `code`; every CLI error the server sends has one. */
+const isMissingRoute = (error) => {
+    if (!(error instanceof CliError) || typeof error.details !== 'object' || error.details === null)
+        return false;
+    const body = error.details;
+    return body.statusCode === 404 && body.code === undefined;
+};
+export async function runLint(opts, deps) {
+    const maxWarnings = parseMaxWarnings(opts.maxWarnings);
+    const query = {};
+    const namespaces = lintNamespaces(deps.config, opts.namespace);
+    if (namespaces !== undefined)
+        query.namespaces = namespaces;
+    if (opts.locale !== undefined)
+        query.locales = toTranslifyLocale(opts.locale, deps.config);
+    if (opts.severity !== undefined)
+        query.severity = opts.severity.toUpperCase();
+    let res;
+    try {
+        res = await deps.api.get('/cli/v1/lint', query);
+    }
+    catch (error) {
+        if (isMissingRoute(error))
+            throw new CliError(EXIT.failed, LINT_UNSUPPORTED);
+        throw error;
+    }
+    const { errors, warnings } = res.summary;
+    deps.out(opts.json === true
+        ? JSON.stringify({ response: res, summary: { errors, warnings, truncated: res.truncated } })
+        : renderLint(res, deps.config, { severity: opts.severity }));
+    return errors > 0 || (maxWarnings !== undefined && warnings > maxWarnings) ? EXIT.issues : EXIT.ok;
+}

package/dist/commands/publish.js

@@ -1,15 +1,37 @@
-import { EXIT } from '../errors.js';
+import { CliError, EXIT } from '../errors.js';
+import { renderIssueCells } from '../render.js';
+const isInvalidCells = (details) => typeof details === 'object' && details !== null && details.code === 'INVALID_CELLS';
+/** The server's one-line refusal, the cells grouped like `lint`, and the way out. */
+const refusal = (body, config) => {
+    const cells = Array.isArray(body.cells) ? body.cells : [];
+    const lines = [
+        `Publish refused: ${body.total} translation(s) with placeholder errors would go live. Nothing was published.`,
+        ...renderIssueCells(cells, config),
+    ];
+    if (body.total > cells.length)
+        lines.push(`Showing first ${cells.length} of ${body.total}.`);
+    lines.push('Fix them (translify lint lists every issue) or re-run with --allow-errors.');
+    return new CliError(EXIT.issues, lines.join('\n'), body);
+};
 export async function runPublish(environment, deps) {
-    const res = await deps.api.post('/cli/v1/publish', { environment });
+    // Only send the flag when it is set: a server older than the gate rejects unknown fields.
+    const request = deps.allowErrors === true ? { environment, allowErrors: true } : { environment };
+    const res = await deps.api.post('/cli/v1/publish', request).catch((error) => {
+        if (error instanceof CliError && isInvalidCells(error.details))
+            throw refusal(error.details, deps.config);
+        throw error;
+    });
     const carriedOverCount = res.carriedOverCount ?? 0;
     const withheldCount = res.withheldCount ?? 0;
+    const errorCount = res.errorCount ?? 0;
     // An ungated environment reports 0 / 0; keep its output as it was before review state.
     const gate = carriedOverCount > 0 || withheldCount > 0 ? ` ${carriedOverCount} carried over, ${withheldCount} withheld.` : '';
+    const errors = errorCount > 0 ? ` ${errorCount} with placeholder errors.` : '';
     deps.out(deps.json === true
         ? JSON.stringify({
             response: res,
-            summary: { environment, publishedCount: res.publishedCount, carriedOverCount, withheldCount },
+            summary: { environment, publishedCount: res.publishedCount, carriedOverCount, withheldCount, errorCount },
         })
-        : `Published ${res.publishedCount} translation(s) to ${environment}.${gate}`);
+        : `Published ${res.publishedCount} translation(s) to ${environment}.${gate}${errors}`);
     return deps.failOnWithheld === true && withheldCount > 0 ? EXIT.withheld : EXIT.ok;
 }

package/dist/errors.js

@@ -1,5 +1,5 @@
 // Minimal for Task 6.2; Task 6.3 owns this file and extends it.
-export const EXIT = { ok: 0, failed: 1, auth: 2, quota: 3, network: 4, withheld: 5 };
+export const EXIT = { ok: 0, failed: 1, auth: 2, quota: 3, network: 4, withheld: 5, issues: 6 };
 /** Every expected failure. `index.ts` prints `message` and exits with `exitCode`; anything else is a bug. */
 export class CliError extends Error {
     exitCode;

package/dist/http.js

@@ -32,6 +32,7 @@ const CODE_EXIT = {
     RATE_LIMITED: EXIT.network,
     REVIEW_DISABLED: EXIT.failed,
     APPROVED_ONLY_REQUIRES_WORKING: EXIT.failed,
+    INVALID_CELLS: EXIT.issues,
 };
 const exitFor = (status, code) => {
     const byCode = code === undefined ? undefined : CODE_EXIT[code];
@@ -88,6 +89,8 @@ const describeBody = (status, body) => {
             return 'Review is off for this project, so --status draft or needs-review cannot be used. Turn on "Require review" in the project settings, or drop --status.';
         case 'APPROVED_ONLY_REQUIRES_WORKING':
             return ONLY_APPROVED_NEEDS_WORKING;
+        case 'INVALID_CELLS':
+            return `Publish refused: ${String(body.total)} translation(s) with placeholder errors would go live. Nothing was published.`;
         case 'TRANSACTION_CONFLICT':
             return 'The server hit a transaction conflict. Try again.';
         case 'RATE_LIMITED':

package/dist/index.js

@@ -2,6 +2,7 @@
 import { confirm, input, password, select } from '@inquirer/prompts';
 import { Command, Option } from 'commander';
 import { runInit } from './commands/init.js';
+import { LINT_SEVERITIES, parseMaxWarnings, runLint } from './commands/lint.js';
 import { runLogin } from './commands/login.js';
 import { runPublish } from './commands/publish.js';
 import { runPull } from './commands/pull.js';
@@ -105,13 +106,17 @@ program
     .command('publish <environment>')
     .description('Publish an environment')
     .option('--fail-on-withheld', 'exit 5 when the review gate withheld any translation (the publish still happens)')
+    .option('--allow-errors', 'publish even when translations with placeholder errors would go live (otherwise refused, exit 6)')
     .option('--json', 'machine-readable output')
     .action(async (environment, opts) => {
+    const { api, config } = await withApi();
     process.exitCode = await runPublish(environment, {
-        api: (await withApi()).api,
+        api,
+        config,
         out,
         json: opts.json,
         failOnWithheld: opts.failOnWithheld,
+        allowErrors: opts.allowErrors,
     });
 });
 program
@@ -136,6 +141,18 @@ program
     .action(async (opts) => {
     process.exitCode = await runPull({ ...opts, check: true }, { ...(await withApi()), out });
 });
+program
+    .command('lint')
+    .description('Exit 6 if translations in Translify have placeholder errors (or too many warnings)')
+    .option('--namespace <ns>', 'only this namespace')
+    .option('--locale <locale>', 'only this locale (as named on disk)')
+    .addOption(new Option('--severity <severity>', 'only list cells whose worst issue is this severity; counts and the exit code are unaffected').choices(LINT_SEVERITIES))
+    .option('--max-warnings <n>', 'also exit 6 when there are more than n warnings')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    parseMaxWarnings(opts.maxWarnings);
+    process.exitCode = await runLint(opts, { ...(await withApi()), out });
+});
 try {
     await program.parseAsync(process.argv);
 }

package/dist/render.js

@@ -1,4 +1,5 @@
 import pc from 'picocolors';
+import { toFsLocale } from './patterns.js';
 const MAX_ORPHANS = 20;
 const MAX_UNKNOWN = 5;
 /** APPROVED gets no label: it is all a project without review ever sees. */
@@ -78,3 +79,77 @@ export function renderPush(res, view = {}) {
         lines.push(pc.red(`  Deleted ${res.pruned} key(s).`));
     return lines.join('\n');
 }
+const MAX_VALUE = 80;
+/** Where the issue text starts: 4 indent + locale 8 + 1 + severity 8 + 1. */
+const VALUE_INDENT = ' '.repeat(22);
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+const braces = (arg) => `{${arg ?? '?'}}`;
+/** One line of plain English per issue; a code this CLI does not know prints as-is. */
+const issueText = (issue) => {
+    const categories = (issue.categories ?? []).join(', ');
+    switch (issue.code) {
+        case 'ICU_INVALID':
+            return `invalid ICU: ${issue.message ?? 'parse error'}${issue.offset === undefined || issue.offset === null ? '' : ` at ${issue.offset}`}`;
+        case 'PLACEHOLDER_MISSING':
+            return `missing placeholder ${braces(issue.arg)}`;
+        case 'PLACEHOLDER_EXTRA':
+            return `unexpected placeholder ${braces(issue.arg)}`;
+        case 'PLACEHOLDER_KIND_MISMATCH':
+            return `placeholder ${braces(issue.arg)} is used differently than in the source`;
+        case 'PLURAL_CATEGORY_MISSING':
+            return `plural ${braces(issue.arg)} is missing ${categories}`;
+        case 'PLURAL_CATEGORY_UNKNOWN':
+            return `plural ${braces(issue.arg)} has categories this locale does not use: ${categories}`;
+        default:
+            return issue.code;
+    }
+};
+const cut = (value) => (value.length > MAX_VALUE ? `${value.slice(0, MAX_VALUE - 1)}…` : value);
+/**
+ * ESLint-style: namespace, then key, then one line per issue with the locale as named on disk.
+ * Rows arrive sorted by the server; only the grouping headers are added here.
+ */
+export function renderIssueCells(cells, config) {
+    const lines = [];
+    let namespace;
+    let key;
+    for (const cell of cells) {
+        if (cell.namespace !== namespace) {
+            namespace = cell.namespace;
+            key = undefined;
+            lines.push(pc.bold(namespace));
+        }
+        if (cell.key !== key) {
+            key = cell.key;
+            lines.push(`  ${key}`);
+        }
+        const locale = (config === undefined ? cell.locale : toFsLocale(cell.locale, config)).padEnd(8);
+        for (const issue of cell.issues) {
+            const label = issue.severity === 'ERROR' ? pc.red('error'.padEnd(8)) : pc.yellow('warning'.padEnd(8));
+            lines.push(`    ${locale} ${label} ${issueText(issue)}`);
+            if (issue.code === 'ICU_INVALID' && cell.value !== undefined) {
+                lines.push(`${VALUE_INDENT}${pc.dim(JSON.stringify(cut(cell.value)))}`);
+            }
+        }
+    }
+    return lines;
+}
+export function renderLint(res, config, view = {}) {
+    const { errors, warnings } = res.summary;
+    if (errors + warnings === 0)
+        return pc.green(`✔ No issues in ${res.summary.locales.length} locale(s).`);
+    const lines = renderIssueCells(res.cells, config);
+    if (res.truncated) {
+        const matched = view.severity === 'error' ? errors : view.severity === 'warning' ? warnings : errors + warnings;
+        lines.push(pc.yellow(`Showing first ${res.cells.length} of ${matched} cells. Narrow with --namespace / --locale, or use --json.`));
+    }
+    const perLocale = res.summary.locales
+        .filter((row) => row.errors + row.warnings > 0)
+        .map((row) => `${toFsLocale(row.locale, config)} ${row.errors}/${row.warnings}`)
+        .join(' · ');
+    const totals = `${plural(errors, 'error')}, ${plural(warnings, 'warning')}${perLocale === '' ? '' : ` — ${perLocale}`}`;
+    if (lines.length > 0)
+        lines.push('');
+    lines.push(errors > 0 ? pc.red(`✖ ${totals}`) : pc.yellow(`⚠ ${totals}`));
+    return lines.join('\n');
+}

package/dist/version.js

@@ -1,3 +1,3 @@
 // Must equal package.json "version"; src/version.test.ts fails when they drift.
-export const VERSION = '0.2.0';
+export const VERSION = '0.4.0';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesterbrains/translify-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {