@chesterbrains/translify-cli 0.2.0 → 0.3.0

package/README.md

@@ -126,6 +126,7 @@ 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:
@@ -133,7 +134,8 @@ 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
+- `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
@@ -196,9 +198,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 +234,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 | `lint` found placeholder errors, or more warnings than `--max-warnings` |
 
 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/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/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';
@@ -136,6 +137,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,72 @@ 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 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 = [];
+    let namespace;
+    let key;
+    for (const cell of res.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 = 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')
+                lines.push(`${VALUE_INDENT}${pc.dim(JSON.stringify(cut(cell.value)))}`);
+        }
+    }
+    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.3.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.3.0",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {