@vernikr/size-report 2.4.0 → 2.5.0

package/bin/postinstall.js

@@ -1,28 +1,27 @@
 #!/usr/bin/env node
-/* Постановка хука после установки пакета: чтобы отчёт обновлялся с первого же
- * коммита, не требуя ни запуска инструмента, ни файла настроек.
+/* Hook installation after the package is installed: the report is rebuilt from the very
+ * first commit, with neither the tool run nor a settings file.
  *
- * Здесь только поиск проекта-потребителя: сам хук ставит `autoInstall`
- * (`src/hook.js`) — то же место, что и при первом запуске, иначе «поставлено при
- * установке» и «поставлено при запуске» могли бы разойтись содержимым файла.
+ * Only the consumer project is located here: the hook itself is installed by
+ * `autoInstall` (`src/hook.js`) — the same place as on the first run, so that "installed
+ * by the installer" and "installed by the first run" cannot diverge in the file content.
  *
- * Код выхода всегда 0: установка зависимостей не должна падать из-за того, что
- * услугу не удалось оказать (нет git, нет прав, чужой хук, CI). Причина не
- * печатается: у фоновой работы нет читателя, а точная причина есть у команды
- * `install-hook`.
+ * The exit code is always 0: installing dependencies must not fail because a service
+ * could not be rendered (no git, no permissions, a foreign hook, CI), and the reason is
+ * not printed — background work has no reader, while `install-hook` has the exact one.
  *
- * Отдельная тонкость: платформы, где скрипты зависимостей по умолчанию не
- * исполняются (pnpm 10, yarn berry), зовут этот файл не всегда — тогда хук
- * ставится при первом запуске инструмента в проекте. Оба пути ведут в одно место. */
+ * One subtlety: platforms that skip dependency scripts by default (pnpm 10, yarn berry)
+ * do not always call this file; there the hook is installed by the first run of the tool
+ * in the project. Both paths lead to the same place. */
 
 import fs from 'fs';
 import path from 'path';
 import { autoInstall } from '../src/hook.js';
 
-/* Каталог проекта-потребителя ищется в порядке убывания точности: `INIT_CWD`
- * (его ставят npm и pnpm, запуская скрипт пакета), `npm_config_local_prefix`,
- * затем подъём от текущего каталога вверх до ближайшего `.git`. Подъём нужен,
- * потому что сам скрипт исполняется из `node_modules`, где репозитория нет. */
+/* The consumer project directory, most precise candidate first: `INIT_CWD` (set by npm
+ * and pnpm when they run a package script), `npm_config_local_prefix`, and finally a walk
+ * up from the current directory to the nearest `.git` — the script itself runs from
+ * `node_modules`, where there is no repository. */
 function projectRoot() {
   const candidates = [process.env.INIT_CWD, process.env.npm_config_local_prefix, process.cwd()];
   for (const start of candidates) {
@@ -46,6 +45,6 @@ function gitRootOf(start) {
 const root = projectRoot();
 const files = root === null ? null : autoInstall(root, null);
 if (files !== null && process.env.SIZE_REPORT_QUIET !== '1') {
-  console.error('· size-report: хук поставлен (' + files.join(', ') + ') — отчёт обновляется после'
-    + ' каждого коммита; снять: size uninstall-hook');
+  console.error('· size-report: hook installed (' + files.join(', ') + ') — the report refreshes after'
+    + ' every commit; remove it: size uninstall-hook');
 }

package/bin/size.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-/* Точка входа команды `size`. Разбор аргументов и режимы живут в движке: держать
- * их здесь значило бы, что движок нельзя импортировать, не исполнив команду. */
+/* The `size` entry point. Arguments and modes live in the engine: keeping them here
+ * would mean the engine could not be imported without running the command. */
 import { main } from '../src/size-table.js';
 
 process.exitCode = main();

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@vernikr/size-report",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "author": "vernikr",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vernikr/size-report.git"
   },
-  "description": "Учёт роста объёма кода и документов по истории git: raw / min / токены; отчёт — один самодостаточный файл, обновляется хуком сам",
+  "description": "Tracking how the volume of code and documents grows across git history: raw / min / tokens; the report is one self-contained file, refreshed by the hook on its own",
   "type": "module",
   "license": "MIT",
   "packageManager": "pnpm@10.6.1",
@@ -27,7 +27,6 @@
     "src",
     "templates",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -66,7 +65,7 @@
     "report"
   ],
   "devDependencies": {
-    "@vernikr/size-report": "2.3.0",
+    "@vernikr/size-report": "2.4.0",
     "c8": "10",
     "dependency-cruiser": "17",
     "eslint": "^9.18.0",

package/src/args.js

@@ -1,24 +1,24 @@
 import { cliCommand, advicePath, refuseCause } from './refusal.js';
 
-/* Грамматика командной строки: что человек назвал и законно ли это сочетание.
+/* Command-line grammar: what the user named, and whether that combination is legal.
  *
- * Один разбор на входе, до чтения проекта. Он решает всё сразу — какой режим
- * запрошен, совместим ли он с командой и с остальными ключами, все ли ключи
- * получили значение, нет ли лишних слов, — и отвечает либо планом, либо отказом.
- * Поэтому порядок ветвлений в `main` ничего не решает: правило «так нельзя» — это
- * значение, а не место в коде, и наружу оно выходит одним способом — отказом с
- * названным виновником и готовой командой.
+ * One parse, at the entry, before the project is read. It settles everything at once —
+ * which mode was asked for, whether it fits the command and the other flags, whether every
+ * flag got a value, whether there are extra words — and answers with either a plan or a
+ * refusal. That is why the order of branches in `main` decides nothing: "you cannot do
+ * that" is a value, not a place in the code, and it surfaces in one way only — as a refusal
+ * naming the culprit and the command that fixes it.
  *
- * Ключи трёх родов: режимы (взаимоисключающие — они задают, что делать), ключи со
- * значением (забирают следующий аргумент) и переключатели. Команда — первое слово
- * вне ключей: её чтение не зависит от места в строке, поэтому и `size check
- * --config x`, и `size --config x check` — одно и то же.
+ * Flags come in three kinds: modes (mutually exclusive — they say what to do), value flags
+ * (they take the next argument) and switches. A command is the first word outside the
+ * flags, so its position in the line does not matter: `size check --config x` and
+ * `size --config x check` are the same.
  *
- * Файл отдельный от `cli.js`, потому что вопросы у них разные: здесь — «что
- * запрошено и можно ли так», там — «что по запросу делать». Отсюда и цена ошибки
- * в каждом: неверное правило здесь ломает все режимы сразу, поэтому проверки
- * разложены по группам (режим, слово, форма ответа), а каталог отказов считает их
- * места и требует проверки на каждое.
+ * The file is separate from `cli.js` because the questions differ: here "what was asked and
+ * may it be so", there "what to do about it". Hence the price of a wrong rule here — it
+ * breaks every mode at once — and hence the checks split by subject, with the refusal
+ * catalogue (`tools/refusals.js`) counting their sites in the sources and demanding a test
+ * for each.
  */
 
 const MODES = ['--init', '--write', '--data'];
@@ -28,23 +28,23 @@ const COMMANDS = ['check', 'explain', 'doctor', 'install-hook', 'uninstall-hook'
 const ANSWER_COMMANDS = ['check', 'explain', 'doctor'];
 export const HOOK_COMMANDS = ['install-hook', 'uninstall-hook', 'hook-run'];
 
-/* Ключ со значением: забирает следующий аргумент и возвращает, сколько съел. У
- * `--init` и `--write` пустое значение — законное «по умолчанию», а у `--config`
- * это молчаливый пропуск: настройки были бы взяты не те, что назвал человек. */
+/* A value flag takes the next argument and reports how many it consumed. An empty value is
+ * a legitimate "default" for `--init` and `--write`, but for `--config` it would be a
+ * silent skip: the settings read would not be the ones the user named. */
 function takeValue(flag, args, i, values) {
   const next = args[i + 1];
   const none = next === undefined || next[0] === '-';
   if (none && flag === '--config') {
-    refuseCause('ключ без значения', 'у ключа «' + flag + '» нет значения: нужен файл настроек'
-      + '\n  починка: ' + cliCommand(flag + ' <файл>'));
+    refuseCause('flag without a value', 'the flag "' + flag + '" has no value: a settings file is needed'
+      + '\n  fix: ' + cliCommand(flag + ' <file>'));
   }
   values[flag] = none ? null : next;
   return none ? 0 : 1;
 }
 
-/* Один проход по строке: слова, режимы и значения ключей. Отказы здесь — только
- * про сам ключ (незнакомый, повторённый, без значения): сочетания разбирает
- * `checkArgs`, потому что они про названное вместе, а не про отдельный аргумент. */
+/* One pass over the line: words, modes, flag values. Refusals here are about a single flag
+ * only (unknown, repeated, missing a value); combinations belong to `checkArgs`, because
+ * they are about what was named together rather than about one argument. */
 function scan(args) {
   const seen = new Set();
   const modes = [];
@@ -54,10 +54,10 @@ function scan(args) {
     const a = args[i];
     if (a[0] !== '-') { words.push(a); continue; }
     if (FLAGS.indexOf(a) < 0) {
-      refuseCause('незнакомый ключ', 'незнакомый ключ «' + a + '»\n  починка: ' + cliCommand('--help'));
+      refuseCause('unknown flag', 'unknown flag "' + a + '"\n  fix: ' + cliCommand('--help'));
     }
     if (seen.has(a)) {
-      refuseCause('повтор ключа', 'ключ «' + a + '» назван дважды\n  починка: ' + cliCommand('--help'));
+      refuseCause('repeated flag', 'the flag "' + a + '" is named twice\n  fix: ' + cliCommand('--help'));
     }
     seen.add(a);
     if (VALUE_FLAGS.indexOf(a) >= 0) i += takeValue(a, args, i, values);
@@ -66,98 +66,98 @@ function scan(args) {
   return { seen: seen, modes: modes, values: values, words: words };
 }
 
-/* Совет повторяет настройки, которые человек назвал: без `--config` команда ищет
- * файл под умолчательным именем, в проекте с другим именем не находит его и уводит
- * человека во второй отказ — про файл настроек, которого у него нет. */
+/* The advice repeats the settings the user named: without it a command looks for the
+ * default file name, does not find it in a project that named the file otherwise, and sends
+ * the user into a second refusal — about a settings file they do not have. */
 function advisor(values) {
   const given = typeof values['--config'] === 'string'
     ? '--config ' + advicePath(values['--config']) + ' ' : '';
   return (rest) => cliCommand(given + rest);
 }
 
-/* Режим против ключей: сами режимы взаимоисключающие, а `--force` и `--config`
- * работают не с каждым из них. */
+/* A mode against the flags: the modes exclude each other, and `--force` and `--config` do
+ * not go with every one of them. */
 function checkModes(plan) {
   const { modes, seen, mode, advice } = plan;
   if (modes.length > 1) {
-    refuseCause('два режима сразу', 'два режима сразу: «' + modes[0] + '» и «' + modes[1] + '» — режим один'
-      + '\n  починка: ' + advice(modes[0]));
+    refuseCause('two modes at once', 'two modes at once: "' + modes[0] + '" and "' + modes[1]
+      + '" — it is one mode' + '\n  fix: ' + advice(modes[0]));
   }
   if (seen.has('--force') && mode !== '--init') {
-    refuseCause('несовместимый ключ', 'ключ «--force» работает только с «--init»'
-      + '\n  починка: ' + cliCommand('--init --force'));
+    refuseCause('incompatible flag', 'the flag "--force" works only with "--init"'
+      + '\n  fix: ' + cliCommand('--init --force'));
   }
   if (seen.has('--config') && mode === '--init') {
-    refuseCause('несовместимый ключ', 'у «--init» свой файл, а «--config» называет настройки проекта'
-      + '\n  починка: ' + cliCommand('--init <файл>'));
+    refuseCause('incompatible flag', '"--init" has a file of its own, while "--config" names the'
+      + ' settings of the project' + '\n  fix: ' + cliCommand('--init <file>'));
   }
 }
 
-/* Слово, которого команда не знает. Отдельным вопросом, потому что виновников
- * тут двое: опечатка в команде — и лишнее значение режима, который своё значение
- * уже забрал (у `--init` и `--write` оно одно). Оба случая обязаны назвать своего
- * виновника: у `--config` остаток — именно команда, и зов её разбирается как
- * команда, а не как лишнее слово. */
+/* A word the command does not know. Its own question, because there are two possible
+ * culprits: a typo in the command, or an extra value for a mode that already took one
+ * (`--init` and `--write` take a single value). Either way the culprit has to be named: a
+ * leftover after `--config` is the command itself, and its call is parsed as a command
+ * rather than as an extra word. */
 function checkUnknownWord(plan) {
   const { verb, values, advice } = plan;
   if (verb === null || COMMANDS.indexOf(verb) >= 0) return;
   const valued = MODES.find((f) => VALUE_FLAGS.indexOf(f) >= 0 && typeof values[f] === 'string');
   if (valued !== undefined) {
-    refuseCause('лишнее слово', 'лишнее слово «' + verb + '»: «' + valued + '» принимает одно значение'
-      + '\n  починка: ' + advice(valued + ' ' + advicePath(values[valued])));
+    refuseCause('extra word', 'the extra word "' + verb + '": "' + valued + '" takes one value'
+      + '\n  fix: ' + advice(valued + ' ' + advicePath(values[valued])));
   }
-  refuseCause('неизвестная команда', 'неизвестная команда «' + verb + '»\n  починка: ' + cliCommand('--help'));
+  refuseCause('unknown command', 'unknown command "' + verb + '"\n  fix: ' + cliCommand('--help'));
 }
 
-/* Слово и режим вместе: команда задаёт, что ответить, режим — что записать, и
- * одновременно они не работают. */
+/* A word and a mode together: the command says what to answer, the mode what to write, and
+ * the two do not work at once. */
 function checkWordAgainstMode(plan) {
   const { verb, mode, advice } = plan;
   if (verb === null || mode === null) return;
-  refuseCause('команда и режим', 'команда «' + verb + '» и режим «' + mode + '» — разное, вместе они не работают'
-    + '\n  починка: ' + advice(verb));
+  refuseCause('command and mode', 'the command "' + verb + '" and the mode "' + mode
+    + '" are different things and do not work together' + '\n  fix: ' + advice(verb));
 }
 
-/* Сколько слов принято: у `explain` коммит один и он обязателен, у остальных
- * команд аргументов нет вовсе. Коммит либо не назван, либо назван не один раз —
- * тупика два, а починка одна и та же. */
+/* How many words are accepted: `explain` takes exactly one commit and requires it, the
+ * other commands take no argument at all. A missing commit and several commits are two
+ * dead ends with one and the same fix. */
 function checkWordCount(plan) {
   const { verb, arg, advice } = plan;
   if (verb === 'explain' && arg.length === 0) {
-    refuseCause('нет коммита', 'команде «explain» нужен коммит: имя ревизии (HEAD, ветка, тег),'
-      + ' sha или его начало'
-      + '\n  починка: ' + advice('explain <коммит>'));
+    refuseCause('no commit', 'the command "explain" needs a commit: a revision name (HEAD, a branch,'
+      + ' a tag), a sha or its beginning'
+      + '\n  fix: ' + advice('explain <commit>'));
   }
   if (verb === 'explain' && arg.length > 1) {
-    refuseCause('лишнее слово', 'команда «explain» принимает один коммит, а не ' + arg.length
-      + ': «' + arg.slice(1).join('», «') + '» лишние\n  починка: ' + advice('explain <коммит>'));
+    refuseCause('extra word', 'the command "explain" takes one commit, not ' + arg.length
+      + ': "' + arg.slice(1).join('", "') + '" are extra\n  fix: ' + advice('explain <commit>'));
   }
   if (verb !== null && verb !== 'explain' && arg.length > 0) {
-    refuseCause('лишнее слово', 'команда «' + verb + '» аргументов не принимает: «' + arg[0] + '» лишний'
-      + '\n  починка: ' + advice(verb));
+    refuseCause('extra word', 'the command "' + verb + '" takes no arguments: "' + arg[0] + '" is extra'
+      + '\n  fix: ' + advice(verb));
   }
 }
 
-/* Форма ответа против всего остального. `--json` — не режим, а форма, и правило у
- * него одно: ответ бывает ровно у трёх команд и у запуска без команды (прежняя
- * форма данных — она заморожена эталоном паритета, убрать её нельзя). У команды
- * без ответа просить нечего, а у режима ответ уже один — запись; оба случая —
- * отказ, и каждый называет своего виновника. */
+/* The shape of the answer against everything else. `--json` is a shape, not a mode, and it
+ * has one rule: exactly three commands and a bare run have an answer — the bare run is the
+ * older data form, frozen by the parity fixture and therefore not removable. A command
+ * without an answer has nothing to ask for, and a mode already has one answer, the write;
+ * both are refusals, and each names its culprit. */
 function checkAnswer(plan) {
   const { verb, mode, seen, advice } = plan;
   if (seen.has('--json') && verb !== null && ANSWER_COMMANDS.indexOf(verb) < 0) {
-    refuseCause('нет ответа в JSON', 'у команды «' + verb + '» нет ответа в JSON'
-      + '\n  починка: ' + advice(verb));
+    refuseCause('no JSON answer', 'the command "' + verb + '" has no answer in JSON'
+      + '\n  fix: ' + advice(verb));
   }
   if (seen.has('--json') && verb === null && mode !== null) {
-    refuseCause('два ответа сразу', '«--json» и режим «' + mode + '» — разное: данные или запись, но не оба'
-      + '\n  починка: ' + advice(mode));
+    refuseCause('two answers at once', '"--json" and the mode "' + mode + '" are different: the data or'
+      + ' the write, not both' + '\n  fix: ' + advice(mode));
   }
 }
 
-/* Проверки сочетаний — тремя группами и одним планом на всех: план это то, что
- * разбор уже знает (слово, аргумент, режим, названные ключи и совет), а группы
- * отвечают каждая за своё. Возврат — готовый план запуска. */
+/* Combination checks, in groups over one plan: the plan holds what the parse already knows
+ * (the word, the argument, the mode, the named flags and the advice), each group answers for
+ * its own subject, and what comes back is a ready plan to run. */
 function checkArgs(scanned) {
   const { words, seen, values, modes } = scanned;
   const plan = {
@@ -184,7 +184,7 @@ function checkArgs(scanned) {
 }
 
 export function parseArgs(args) {
-  // Справка отвечает всегда и первой: она и есть выход из любой опечатки.
+  // Help always answers, and answers first: it is the way out of any typo.
   if (args.indexOf('--help') >= 0 || args.indexOf('-h') >= 0) return { help: true };
   const scanned = scan(args);
   return Object.assign({ help: false, values: scanned.values }, checkArgs(scanned));

package/src/artifact.js

@@ -3,28 +3,28 @@ import path from 'path';
 import { reportData } from './data.js';
 import { pageHtml } from './page/build.js';
 
-/* Отчёт — один файл: самодостаточная страница. Она и есть артефакт, потому что
- * несёт всё сама (данные, оформление, программу), а второй формы того же отчёта не
- * существует: два вывода одной истории разошлись бы молча, и выбрать, какой из них
- * верный, было бы нечем.
+/* The report is one file: a self-sufficient page. It is the artifact because it carries everything itself
+ * (data, styling, program), and a second form of the same report does not exist: two outputs of one history
+ * would drift apart silently, with nothing to tell which of them is right.
  *
- * Через это место проходят оба потребителя — режим записи (`--write`) и хук после
- * коммита (`src/hook.js`), поэтому «что записано в файл» не может разойтись между
- * ними: в коммит хук кладёт ровно те байты, которые показывает `--write`.
+ * Both consumers pass through here — the writing mode (`--write`) and the hook after a commit
+ * (`src/hook.js`), so "what went into the file" cannot drift between them: the hook commits exactly the bytes
+ * `--write` shows.
  *
- * Каталог создаётся здесь же: `--write docs/size-report.html` в свежем проекте —
- * обычный запуск, а не ошибка пользователя. Тем же путём пишется черновик настроек
- * (`--init`), поэтому он один на пакет. */
+ * The directory is created here as well: `--write docs/size-report.html` in a fresh project is an ordinary run
+ * rather than a user's mistake. The settings draft (`--init`) is written the same way, which is why there is one
+ * such place in the package. */
 
-/* Запись файла с созданием каталога: путь может не существовать ни одной своей
- * частью — это не ошибка того, кто его назвал. */
+/* Writing a file while creating the directory: not a single part of the path may exist, and that is not a
+ * mistake of whoever named it. */
 export function writeFileEnsured(file, text) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, text);
 }
 
-/* Собранные байты отчёта без записи: они же нужны проверке (`таблица совпадает с
- * историей`), и собирать их вторым способом значило бы сверять не то, что пишется. */
+/* The report's bytes built without writing: the check needs them too (it compares the file on disk with exactly
+ * these bytes and reports it as diverging from the history), and building them a second way would compare
+ * something other than what gets written. */
 export function artifact(cfg, root) {
   const data = reportData(cfg, root);
   return { data: data, html: pageHtml(data, cfg), file: path.join(root, cfg.output) };

package/src/check.js

@@ -4,29 +4,27 @@ import { sensorGaps } from './metrics.js';
 import { outsideFix, pathRoles } from './config.js';
 import { cliCommand } from './refusal.js';
 
-/* Полнота покрытия — ответ на вопрос «всё ли в истории попало в отчёт». Правило
- * из требований (§4.2) одно: каждый путь, тронутый историей, обязан быть либо
- * колонкой, либо объявленным исключением (`skip` и сам файл отчёта), а путь,
- * который не то и не другое, — это нарушение: изменение прошло мимо отчёта.
+/* Coverage — the answer to "did everything in the history get into the report". The project's rule of
+ * completeness is one: every path the history touched has to be either a column or a declared exception
+ * (`skip` and the report file itself), and a path that is neither is a violation — an edit went past the
+ * report.
  *
- * Поэтому полнота считается по фактам истории (объединение изменённых путей всех
- * коммитов), а не по списку файлов в дереве: файл, появившийся и удалённый до
- * HEAD, в дереве не виден, а история его помнит — и его правки не посчитаны
- * ничем. Отсюда же и то, чего инструмент не утверждает: он не говорит, «правильные»
- * ли колонки выбрал проект, — он говорит только, что мимо них ничего не прошло и
- * что именно не поместилось.
+ * Hence coverage is counted over the facts of the history (the union of the changed paths of every commit)
+ * rather than over the file list in the tree: a file created and deleted before HEAD is invisible there
+ * while the history remembers it, and its edits went into no number at all. The same place explains what
+ * the tool does **not** claim: it does not say whether the project picked the "right" columns — only that
+ * nothing went past them, and what exactly did not fit.
  *
- * Сводка по строкам идёт тем же проходом, что и отчёты (`measureHistory`), — по
- * тем же причинам, что и везде: второго расчёта в пакете нет. Отсюда цена: ответ
- * стоит одного прохода по истории, как и любой отчёт. */
+ * The rows are counted by the same run as the reports (`measureHistory`), for the usual reason: there is no
+ * second calculation in the package. That is the price — the answer costs one pass over the history, like
+ * any report. */
 
-// Сколько путей и коммитов показывать человеку в тексте: остальное — числом.
+// How many paths and commits to show a person in the text: the rest as a number.
 const SHOW = 8;
 
-/* Список коммитов одной причины — строками не длиннее экрана: у большой истории
- * одних пропущенных коммитов набирается полсотни, и одна строка на всех не
- * читается вовсе. Все они остаются в ответе (и целиком — в `--json`), но перенос
- * делает его читаемым. */
+/* The list of commits of one reason — lines no longer than a screen: a large history gathers fifty dropped
+ * commits alone, and one line for all of them is not readable at all. Every one of them stays in the answer
+ * (in full in `--json`), while the wrapping is what makes it readable. */
 function wrapped(head, items) {
   const lines = [];
   let line = head;
@@ -39,15 +37,15 @@ function wrapped(head, items) {
   return lines;
 }
 
-const REASON_WORD = { merge: 'слияние', report: 'только таблица', flat: 'без изменения объёма' };
+const REASON_WORD = { merge: 'merges', report: 'report only', flat: 'no change of volume' };
 
 function short(sha) {
   return sha.slice(0, 7);
 }
 
-/* Пути, тронутые историей, разложенные на три части: отслеживаемые колонками,
- * исключённые объявлением и незнакомые. Само суждение — одно и живёт в настройках
- * (`pathRoles`), а здесь только его применение ко всей истории. */
+/* The paths the history touched, split in three: tracked by columns, excluded by declaration, and unknown.
+ * The judgement itself is one and lives with the settings (`pathRoles`); here it is only applied to the
+ * whole history. */
 function pathCoverage(cfg, commits) {
   const role = pathRoles(cfg);
   const seen = { covered: new Set(), excluded: new Set() };
@@ -57,9 +55,8 @@ function pathCoverage(cfg, commits) {
       const kind = role(f);
       if (kind === 'columns') { seen.covered.add(f); return; }
       if (kind === 'excluded') { seen.excluded.add(f); return; }
-      /* Коммит, заведший путь, — первый по истории (порядок чтения — от старых к
-       * новым), и показывается он человеку как улика: по нему видно, чья это была
-       * правка. */
+      /* The commit that introduced the path is the first one in the history (reads run oldest first), and it
+       * is shown to a person as evidence: it tells whose edit it was. */
       if (!unknown.has(f)) unknown.set(f, { path: f, since: c.sha, subject: c.subject });
     });
   });
@@ -70,9 +67,9 @@ function pathCoverage(cfg, commits) {
   };
 }
 
-/* Полный ответ: настройки, история, пути, датчики — и вердикт. `ok` — это только
- * «мимо отчёта не прошло»: датчик, считающий приближённо, вердикта не меняет (это
- * отдельный код выхода, как и у остальных режимов). */
+/* The full answer: settings, history, paths, sensors — and the verdict. `ok` means only "nothing went past
+ * the report": a sensor counting approximately does not change the verdict (it has an exit code of its own,
+ * as in every other mode). */
 export function coverage(cfg, root, configFile) {
   assertFullHistory(root);
   const commits = readHistory(root);
@@ -104,26 +101,28 @@ export function coverage(cfg, root, configFile) {
   };
 }
 
-/* Текст для человека: короткое «да» или список того, что не поместилось, — с
- * путём, коммитом, который его завёл, и готовой командой. Печатает `cli`, а не
- * этот модуль: у модуля нет и не должно быть вывода. */
+/* The text for a person: a short "yes", or the list of what did not fit — with the path, the commit that
+ * introduced it, and a ready command. `cli` does the printing rather than this module: a module has no
+ * output and must not have one. */
 export function coverageText(rep) {
   const lines = [];
   const unknown = rep.paths.unknown;
-  const counts = '  история: ' + rep.history.commits + ' коммитов, ' + rep.history.rows + ' строк, без строки '
+  const counts = '  history: ' + rep.history.commits + ' commits, ' + rep.history.rows + ' rows, without a row '
     + rep.history.dropped.length;
   if (!rep.ok) {
-    lines.push('✗ покрытие: ' + unknown.length + (unknown.length === 1 ? ' путь' : ' путей')
-      + ' истории не отслеживается и не исключён');
+    lines.push('✗ coverage: ' + unknown.length
+      + (unknown.length === 1
+        ? ' path of the history is neither tracked nor excluded'
+        : ' paths of the history are neither tracked nor excluded'));
     unknown.slice(0, SHOW).forEach((u) => {
-      lines.push('    ' + u.path + ' — с ' + short(u.since) + ' «' + u.subject.slice(0, 60) + '»');
+      lines.push('    ' + u.path + ' — since ' + short(u.since) + ' "' + u.subject.slice(0, 60) + '"');
     });
-    if (unknown.length > SHOW) lines.push('    … ещё ' + (unknown.length - SHOW));
-    lines.push('  починка: ' + outsideFix(unknown.map((u) => u.path))
-      + '; черновик колонок по расширениям даёт ' + cliCommand('--init draft.json'));
+    if (unknown.length > SHOW) lines.push('    … and ' + (unknown.length - SHOW) + ' more');
+    lines.push('  fix: ' + outsideFix(unknown.map((u) => u.path))
+      + '; a draft of columns by extension: ' + cliCommand('--init draft.json'));
   } else {
-    lines.push('✓ покрытие: ' + rep.history.commits + ' коммитов истории, ' + rep.history.rows
-      + ' строк, тронутые пути отслеживаются или исключены');
+    lines.push('✓ coverage: ' + rep.history.commits + ' commits of the history, ' + rep.history.rows
+      + ' rows, every touched path is tracked or excluded');
   }
   lines.push(counts + ' (' + Object.keys(rep.history.byReason)
     .filter((k) => rep.history.byReason[k] > 0)
@@ -134,7 +133,7 @@ export function coverageText(rep) {
       if (shas.length > 0) lines.push(...wrapped('    ' + REASON_WORD[key] + ' (' + shas.length + '): ', shas));
     });
   }
-  lines.push('  пути: ' + rep.paths.covered + ' отслеживаются, ' + rep.paths.excluded + ' исключены'
-    + (rep.ok ? '' : ', ' + unknown.length + ' незнакомы'));
+  lines.push('  paths: ' + rep.paths.covered + ' tracked, ' + rep.paths.excluded + ' excluded'
+    + (rep.ok ? '' : ', ' + unknown.length + ' unknown'));
   return lines.join('\n');
 }