@vernikr/size-report 2.4.0 → 2.5.0

package/src/parse.js

@@ -5,49 +5,45 @@ import { execFileSync } from 'child_process';
 import { Worker, MessageChannel, receiveMessageOnPort } from 'worker_threads';
 import { fileURLToPath } from 'url';
 
-/* Разбор модуля: один рабочий поток на прогон вместо запуска Node на каждую
- * клетку.
+/* Parsing a module: one worker per run instead of launching Node per cell.
  *
- * Зачем. Гард компиляции обязан понимать модуль (`import`/`export` в `.js` —
- * обычное дело у проекта с бандлером, см. `strip.js`), а единственный разбор
- * модуля без исполнения — `vm.SourceTextModule` — живёт только под флагом
- * `--experimental-vm-modules`, которого у процесса нет. Раньше это решалось
- * запуском `node --check` на каждую клетку: 97 мс на запуск и минуты на истории,
- * где модуль меняется каждым коммитом.
+ * Why. The compile guard has to understand a module (`import`/`export` inside `.js` is
+ * ordinary in a project with a bundler — see `strip.js`), while the only parse of a module
+ * without executing it, `vm.SourceTextModule`, exists only under `--experimental-vm-modules`,
+ * which this process is not started with. It used to be solved by `node --check` per cell:
+ * 97 ms per launch and minutes across a history where a module changes at every commit.
  *
- * Как. Поток поднимается при первом модуле и живёт до конца прогона, поэтому
- * скриптовые проекты за него не платят вовсе. Обмен синхронный — измерение
- * истории синхронное: запрос уходит `postMessage`, готовность ответа отмечается
- * в `SharedArrayBuffer`, а ответ забирается `receiveMessageOnPort` (тот же приём,
- * что в примере Node для синхронного канала в поток). Поток `unref`-нут: команда
- * заканчивается вместе со своей работой, а не вместе с потоком.
+ * How. The worker starts at the first module and lives until the end of the run, so a
+ * script-only project never pays for it. The exchange is synchronous, as history measurement
+ * is: the request goes out through `postMessage`, readiness is marked in a `SharedArrayBuffer`,
+ * and the answer is taken with `receiveMessageOnPort` — the same trick as in Node's example of
+ * a synchronous channel to a worker. The worker is `unref`-ed: the command ends with its
+ * work, not with the thread.
  *
- * Чем платит. Старт потока — разовая цена (~55 мс на машине замера), и разбор
- * опирается на экспериментальный API: флаг `--experimental-vm-modules` передаётся
- * самому потоку, поэтому команда пользователя не меняется. Текст передаётся в
- * поток копией — на файлах в десятки мегабайт это десятки миллисекунд, всё ещё
- * дешевле запуска процесса.
+ * What it costs. Starting the worker is a one-off (~55 ms on the machine the measurement was
+ * taken on), and the parsing relies on an experimental API: the flag is passed to the worker
+ * itself, so the user's command does not change. The text is copied into the worker — tens of
+ * milliseconds for files of tens of megabytes, still cheaper than launching a process.
  *
- * Куда отступает. К запуску `node --check` — медленнее, но не мягче: когда файла
- * потока нет (неполная упаковка), когда поток не ответил за отведённое время
- * (умер) и когда в потоке не оказалось `vm.SourceTextModule` (Node без модулей
- * vm). Отступление молчаливое: сломавшийся быстрый путь стоит секунд, а не
- * правильности, и его место стережёт проверка способа разбора (`parseMode`).
+ * Where it falls back. To `node --check` — slower, not weaker: when the worker file is missing
+ * (an incomplete package), when the worker did not answer in time (it died), and when it turns
+ * out to have no `vm.SourceTextModule` (a Node without the vm module). The fallback is silent:
+ * a broken fast path costs seconds rather than correctness, and its place is watched by the
+ * parse-mode check (`parseMode`).
  */
 
 const WORKER_FILE = fileURLToPath(new URL('./parse-worker.js', import.meta.url));
 const FLAGS = ['--experimental-vm-modules', '--no-warnings'];
 const WAIT_MS = 2000;
 
-let parser = null;      // живой поток { worker, port, sig } или null
-let hopeless = false;   // поток не поднялся: второй раз не пробуем
+let parser = null;      // the live thread { worker, port, sig } or null
+let hopeless = false;   // the thread did not come up: no second try
 let seq = 0;
-let mode = null;        // 'thread' | 'node' — чем разобран последний модуль
+let mode = null;        // 'thread' | 'node' — how the last module was parsed
 
-/* Причина, по которой текст не разбирается как модуль, или null, если
- * разбирается. «Не удалось проверить» наружу не выходит никогда: разбор без
- * потока уходит в `node --check`, а он отвечает тем же — причиной или её
- * отсутствием. */
+/* The reason the text does not parse as a module, or null if it does. "Could not check"
+ * never leaves this function: without a worker the parse goes to `node --check`, which
+ * answers the same way — with a reason or with its absence. */
 export function moduleError(text) {
   const fromThread = inThread(text);
   if (fromThread !== undefined) {
@@ -58,9 +54,9 @@ export function moduleError(text) {
   return onNodeCheck(text);
 }
 
-/* Способ разбора последнего модуля. Нужен, чтобы быстрый путь не деградировал
- * молча: проверка утверждает, что на проекте с модулями он действительно поток,
- * а не прежний запуск. */
+/* How the last module was parsed. Kept so that the fast path cannot degrade silently: a
+ * check asserts that on a project with modules it really is the worker and not the old
+ * launch. */
 export function parseMode() {
   return mode;
 }
@@ -69,15 +65,15 @@ function inThread(text) {
   const live = start();
   if (!live) return undefined;
   const id = ++seq;
-  // Сначала ноль в том же слове, которым поток отмечает готовность: ответ,
-  // пришедший раньше ожидания, иначе было бы видно как «ещё не начинали».
+  // Zero goes into the same word the worker marks readiness with: an answer arriving before
+  // the wait would otherwise look like "not started yet".
   Atomics.store(live.sig, 0, 0);
   live.port.postMessage({ id: id, text: text });
   if (Atomics.wait(live.sig, 0, 0, WAIT_MS) === 'timed-out') return bury();
   for (;;) {
     const got = receiveMessageOnPort(live.port);
     if (!got) return bury();
-    if (got.message.id !== id) continue;   // прежний ответ (поток отвечал не нам)
+    if (got.message.id !== id) continue;   // a stale answer (it replied to another request)
     if (got.message.available === false) return bury();
     return got.message.error === null ? null : String(got.message.error);
   }
@@ -95,8 +91,8 @@ function start() {
     const worker = new Worker(WORKER_FILE, {
       execArgv: FLAGS, workerData: { port: port2, sig: sig }, transferList: [port2]
     });
-    // Без обработчика ошибка потока стала бы исключением процесса, а её место —
-    // в отступлении к запуску.
+    // Without a handler a worker error would become an exception of the process, while its
+    // place is in the fallback to a launch.
     worker.on('error', bury);
     worker.on('exit', bury);
     worker.unref();
@@ -107,7 +103,8 @@ function start() {
   return parser;
 }
 
-// Поток больше не годится: дальше разбираем запуском, и вернуться уже некуда.
+// The worker is no longer usable: parsing goes through a launch from here on, with no way
+// back.
 function bury() {
   const dead = parser;
   parser = null;
@@ -116,10 +113,10 @@ function bury() {
   return undefined;
 }
 
-/* Отступление: `node --check` по временному файлу. Расширение `.mjs` здесь не
- * косметика — у временного файла нет манифеста, и только расширение говорит
- * Node, что текст надо читать как модуль. Причина берётся из `stderr`: там
- * сначала эхо строки с ошибкой, потом сам `SyntaxError` и стек. */
+/* The fallback: `node --check` on a temporary file. The `.mjs` extension is not cosmetic —
+ * a temporary file has no manifest, and only the extension tells Node to read the text as a
+ * module. The reason comes from `stderr`, which holds the echoed offending line first, then
+ * the `SyntaxError` itself and the stack. */
 function onNodeCheck(text) {
   const tmp = path.join(os.tmpdir(), 'size-table-guard-' + process.pid + '-mod.mjs');
   try {
@@ -129,7 +126,8 @@ function onNodeCheck(text) {
   } catch (e) {
     const lines = String((e && e.stderr) || (e && e.message) || e).split('\n')
       .map((l) => l.trim()).filter((l) => l !== '');
-    return lines.find((l) => /^\w*Error\b/.test(l)) || lines[0] || 'модуль не разбирается';
+    // The fallback reason travels into a printed refusal, so it is Russian like the rest of the output.
+    return lines.find((l) => /^\w*Error\b/.test(l)) || lines[0] || 'the module does not parse';
   } finally {
     fs.rmSync(tmp, { force: true });
   }

package/src/project.js

@@ -4,46 +4,44 @@ import { execFileSync } from 'child_process';
 import { MAX_BUF, git, gitArgv, gitEnv, gitTry, readHistory } from './git.js';
 import { cliCommand, invocation } from './refusal.js';
 
-/* Настройки, выведенные из самого проекта: что считать, где журнал, куда писать и
- * что колонкой быть не может.
+/* Settings derived from the project itself: what to measure, where the journal is, where to write,
+ * and what cannot be a column.
  *
- * Зачем отдельно от `src/config.js`. Тот читает **готовые** настройки и только
- * затем их проверяет, а этот смотрит на проект впервые и почти всё о нём
- * догадывается — та же работа, что была у черновика (`--init`). Отсюда две роли
- * одного вывода: без файла настроек он и есть настройки (проект работает сразу,
- * ничего не заводив), а с `--init` он же ложится файлом, который дальше правят.
- * Второго вывода «как угадать проект» в пакете нет.
+ * Why separate from `src/config.js`: that one reads **ready** settings and checks them, while this
+ * one looks at the project for the first time and guesses about almost everything — the same work
+ * the draft used to do (`--init`). Hence the two roles of one output: with no settings file it *is*
+ * the settings (the project works at once, having set up nothing), and under `--init` the very same
+ * output is written to a file, which is edited afterwards. There is no second way to guess a project
+ * in this package.
  *
- * Два правила, из которых выведено всё остальное.
+ * Two rules, from which everything else follows.
  *
- * **Колонка — это файл.** Состояние движка хранит на колонку один путь, а список
- * путей колонки — её переименования (в ревизии берётся тот, который в ней есть).
- * Поэтому «папка целиком» колонкой быть не может, и профиль называет файлы, а не
- * группы путей. Колонкой идёт **каждый** отслеживаемый файл, который можно
- * измерить: выборка из проекта выдавала объём выборки за объём проекта.
+ * **A column is a file.** The report names a column by one path — the first of its list — while the
+ * whole list is the column's renames, and a revision resolves whichever of them is present there. So
+ * "a whole directory" cannot be a column, and the profile names files rather than groups of paths. A
+ * column is **every** tracked file that can be measured: a sample of the project passed the volume of
+ * the sample off as the volume of the project.
  *
- * **Профиль обязан проходить ту же проверку, которой его встретит первый запуск**
- * (BLOCKERS §N2, REFACTOR R-0.4): путь, не ставший колонкой и не объявленный
- * исключением, — это код 1 на первом же прогоне. Поэтому `skip` называет и то,
- * что колонкой быть не может (сам отчёт, замки зависимостей, собранное, незнакомый
- * формат, слишком крупный файл), и то, чего git не отслеживает: так первый `check`
- * зелёный, а про каждый файл вне отчёта сказано, почему его там нет.
+ * **The profile has to pass the very check its first run will apply**: a path that became neither a
+ * column nor a declared exception is code 1 on that first run. So `skip` names both what cannot be a
+ * column (the report itself, dependency locks, built output, an unknown format, a file too large) and
+ * what git does not track: that way the first `check` is green, and every file outside the report has
+ * a stated reason for standing there.
  */
 
-/* Что вообще берётся колонкой: текстовые формы, с которыми движок умеет работать.
- * Файл без знакомого расширения (`LICENSE`, `.gitignore`) колонкой не становится и
- * называется исключением. */
+/* What may become a column at all: the text forms the engine can work with. A file without a known
+ * extension (`LICENSE`, `.gitignore`) never becomes one and is named as an exception. */
 const KNOWN_EXTS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.html', '.css', '.scss',
   '.json', '.yaml', '.yml', '.toml', '.md', '.txt', '.py', '.rb', '.go', '.rs', '.sh'];
 
 const JOURNALS = ['WORKLOG.md', 'CHANGELOG.md', 'CHANGES.md', 'HISTORY.md'];
 
-/* Порог по размеру — предохранитель: очень крупный файл в истории обычно собран или
- * сгенерирован, и в отчёте он перевесил бы весь проект. */
+/* The size threshold is a guard: a very large file is usually built or generated, and in the report
+ * it would outweigh the whole project. */
 const MAX_BYTES = 512 * 1024;
 
-/* Индекс — путь и размер: `ls-files -s` даёт объекты, размер спрашивается у них
- * одной пачкой (`cat-file --batch-check`), а не чтением содержимого. */
+/* The index gives paths and sizes: `ls-files -s` yields the objects, and their sizes are asked for in
+ * one batch (`cat-file --batch-check`) rather than by reading the content. */
 function indexFiles(root) {
   const listed = git(root, ['ls-files', '-s']).split('\n').filter((l) => l !== '');
   const sizes = new Map();
@@ -60,25 +58,25 @@ function indexFiles(root) {
   return listed.map((line) => ({ p: line.split('\t')[1], size: sizes.get(line.split(/\s+/)[1]) || 0 }));
 }
 
-/* История — объединение путей всех коммитов, тем же чтением, которым пользуется
- * полнота (`readHistory`): иначе профиль и `check` считали бы разные истории. Файл,
- * живущий только в истории, в отчёте просто пуст на HEAD — это не потеря, а факт, и
- * колонкой (или исключением) он быть обязан. */
+/* The history is the union of the paths of every commit, read the same way coverage reads it
+ * (`readHistory`): otherwise the profile and `check` would count different histories. A file living
+ * only in the history is simply empty at HEAD — a fact rather than a loss, and it has to be a column
+ * (or an exception). */
 function historyPaths(root) {
   const seen = new Set();
   try {
     readHistory(root).forEach((c) => c.files.forEach((f) => seen.add(f)));
   } catch (e) {
-    // У репозитория без коммитов истории нет вовсе: `git log` там отказывает, и
-    // это состояние проекта, а не дефект инструмента — `--init` обязан работать и
-    // в нём (первый запуск бывает и до первого коммита).
+    // A repository without commits has no history at all: `git log` refuses there, and that is a state
+    // of the project rather than a defect of the tool — `--init` has to work in one too (a first run
+    // may come before the first commit).
     if (/does not have any commits/.test(String(e.stderr))) return seen;
     throw e;
   }
   return seen;
 }
 
-// Дерево и история — одним списком: колонкой становится всё, что тронула история.
+// The tree and the history in one list: everything the history touched may become a column.
 function allPaths(root) {
   const files = indexFiles(root);
   const known = new Set(files.map((f) => f.p));
@@ -88,23 +86,22 @@ function allPaths(root) {
   return files;
 }
 
-// Наличие каталога решает, куда ляжет отчёт: рядом с доками или в корне.
+// Whether the project has this path at all; nothing else is asked of this helper.
 function exists(root, p) {
   return fs.existsSync(path.join(root, p));
 }
 
-/* Куда ложится отчёт — одно на пакет: `docs/size-report.html`, и каталог создаётся
- * сам. Прежняя развилка («в доки, если они есть, иначе в корень») убрана по замеру:
- * в свежем проекте каталога `docs` ещё нет, и отчёт оказывался в корне — то есть
- * ни в том месте, где его ищут, ни в том, куда его хочет положить человек,
- * который ставит пакет ради отчёта. Каталог здесь не признак проекта, а часть
- * адреса; создавать его — работа того, кто пишет файл (`writeFileEnsured`). */
+/* Where the report lands — one answer for the package: `docs/size-report.html`, with the directory
+ * created by the writer (`writeFileEnsured`). A fork on the existence of `docs/` was measured and
+ * dropped: a fresh project has no such directory, so the report ended up in the root — neither where
+ * it is looked for nor where a person installing the package for the sake of the report would put it.
+ * The directory is part of the address here, not a sign of a project. */
 function outputOf() {
   return 'docs/size-report.html';
 }
 
-/* Менеджер пакетов — по lock-файлу, а не догадкой: команда обязана существовать
- * в чужом проекте. Один на два места (команду починки и подсказку `--init`). */
+/* The package manager comes from a lock file rather than a guess: the command has to exist in
+ * someone else's project. One answer for two places (the fix command and the `--init` prompt). */
 export function packageManager(root) {
   if (exists(root, 'pnpm-lock.yaml')) return 'pnpm';
   return exists(root, 'yarn.lock') ? 'yarn' : 'npm';
@@ -118,12 +115,12 @@ function readJson(file) {
   }
 }
 
-/* Подпись артефакта и отказы цитируют эту команду, поэтому она обязана работать
- * здесь и сейчас: свой скрипт — только если он объявлен (иначе `npm run sizes`
- * отвечает «нет такого скрипта», а совет, который не работает, — худшая подсказка),
- * иначе — установленный пакет внутри проекта. Имени пакета в команде нет намеренно:
- * `npx <имя>` без установленного пакета уходит в реестр и запускает чужой код
- * (REFACTOR R-4.21). */
+/* The artifact's note and the refusals quote this command, so it has to work right here and now: the
+ * project's own script only if it is declared (or `npm run sizes` answers "no such script", and
+ * advice that does not work is the worst kind), otherwise the installed package inside the project.
+ * The package name is deliberately absent from the command: with no package installed it would send the
+ * reader to the registry, which serves a revision the project never pinned, while a path inside the
+ * project refuses on the spot. */
 function fixCommandOf(root) {
   const pkg = readJson(path.join(root, 'package.json')) || {};
   const script = pkg.scripts === undefined ? '' : pkg.scripts.sizes;
@@ -131,10 +128,10 @@ function fixCommandOf(root) {
   return packageManager(root) + ' run sizes';
 }
 
-/* Ссылка на коммит — из адреса origin: два хозяина собирают её одним правилом из
- * владельца и пути к репозиторию (у GitLab в пути бывают подгруппы, поэтому путь
- * берётся целиком), а всякий третий хозяин — догадка, которая ведёт не туда.
- * Remote нет или он не тот — ссылок нет: пустой шаблон строка просто не несёт. */
+/* The commit link comes from the origin address: the two hosts are covered by one rule that builds
+ * the address from the host and the repository path (GitLab nests subgroups, hence the whole path),
+ * while any third host would be a guess leading somewhere else. No remote, or the wrong one — no
+ * links: an empty template is simply not spelled out. */
 const REMOTE_RE = /^\S+?(?:@|\/\/)(?:[^@/]*@)?(github\.com|gitlab\.com)[/:]+((?:[^/\s]+\/)*[^/\s]+?)(?:\.git)?$/;
 
 function commitUrlOf(root) {
@@ -148,9 +145,9 @@ function journalOf(root) {
   return JOURNALS.find((p) => exists(root, p)) || '';
 }
 
-/* Колонкой не становится: сам отчёт (его размер зависит от числа строк, то есть от
- * себя), замки зависимостей (их размер — про чужие пакеты), карты и собранное (их
- * сделала сборка, а не человек) и всё, чего движок не умеет читать. */
+/* What never becomes a column: the report itself (its size depends on the number of rows, that is,
+ * on itself), dependency locks (their size is about someone else's packages), maps and built output
+ * (made by a build rather than by a person), and anything the engine cannot read. */
 function generated(p, output) {
   const ext = path.extname(p).toLowerCase();
   return p === output || KNOWN_EXTS.indexOf(ext) < 0
@@ -158,8 +155,8 @@ function generated(p, output) {
     || /\.min\./.test(p) || /\.map$/.test(p);
 }
 
-/* Метка колонки — имя файла; совпадение имён в разных папках разводится путём, а
- * если и путь занят — числом. Повтор метки проверка настроек не пропустит. */
+/* A column's label is the file name; a clash of names in different directories is split by the path
+ * and, if that is taken too, by a number. The settings check lets no repeated label through. */
 function labelFor(used, p) {
   const candidates = [path.basename(p), p];
   const free = candidates.find((name) => used.indexOf(name) < 0);
@@ -169,17 +166,16 @@ function labelFor(used, p) {
   return p + ' (' + n + ')';
 }
 
-/* Выбор колонок: колонкой идёт всё, что можно измерить, — то есть каждый файл
- * проекта, а не выборка из него. Выборка (прежде — крупнейшие по одному от каждого
- * расширения, всего не больше двенадцати) врала дважды: отчёт называл объём файлов,
- * которых в нём не было, а читатель принимал это за объём проекта. Границы остались
- * только у того, что колонкой **не может** быть: сам отчёт, замки, собранное,
- * незнакомый формат и слишком крупный файл (`generated` и `MAX_BYTES`) — они уходят
- * в `skip` и называются там.
+/* How columns are chosen: everything measurable becomes one — that is, every file of the project
+ * rather than a sample of it. The sample (formerly the largest file per extension, at most twelve)
+ * lied twice: the report named the volume of files it did not contain, and a reader took that for the
+ * volume of the project. The only things left out are those that **cannot** be a column: the report
+ * itself, locks, built output, an unknown format, and a file too large (`generated` and `MAX_BYTES`) —
+ * they go to `skip` and are named there.
  *
- * Порядок колонок — по кругу от каждого расширения, от крупнейшего к мелкому:
- * сперва то, чего в проекте больше всего, и в каждом расширении крупное раньше
- * мелкого. Это порядок чтения отчёта, а не вес: числа от него не зависят. */
+ * The order of columns is a ring over the extensions, largest first: what the project has most of comes
+ * first, and within an extension the large comes before the small. That is the reading order of the
+ * report rather than weight — numbers do not depend on it. */
 function columnsOf(files, journal) {
   const byExt = new Map();
   files.forEach((f) => {
@@ -211,23 +207,23 @@ export function projectConfig(root) {
   const output = outputOf(root);
   const journal = journalOf(root);
   const files = allPaths(root);
-  /* Колонками идёт отслеживаемое git: файл, которого на HEAD нет, измерять нечего
-   * (в отчёте он был бы пуст во всех строках). Путь, живущий только в истории,
-   * поэтому — исключение, а не колонка; сам список путей — всё равно полный. */
+  /* Only what git tracks becomes a column: a file absent at HEAD has nothing to measure (it would be
+   * empty in every row of the report). A path living only in the history is therefore an exception
+   * rather than a column, while the list of paths stays complete either way. */
   const tracked = new Set(indexFiles(root).map((f) => f.p));
   const readable = files.filter((f) => tracked.has(f.p) && !generated(f.p, output) && f.size <= MAX_BYTES);
   const columns = columnsOf(readable, journal);
   const taken = new Set(columns.reduce((all, c) => all.concat(c.paths), []));
-  // Язык, заголовок, порядок строк и выключатель хука не выводятся ни из чего:
-  // они берутся из умолчаний (`DEFAULT_CONFIG`), а не выдаются за вывод из проекта.
+  // The language, the title, the row order and the hook switch are derived from nothing: they come
+  // from the defaults (`DEFAULT_CONFIG`) instead of being passed off as derived from the project.
   return {
     output: output,
     fixCommand: fixCommandOf(root),
     metrics: ['raw', 'min', 'tok'],
-    // Настоящее сжатие и настоящий словарь, а не приближения: новый проект не должен
-    // начинать с чисел, которые честны наполовину. Без необязательной зависимости
-    // метрика отступает к другому счёту и прогон возвращает код 4 — это сказано
-    // подписью метрики, а не умолчанием.
+    // Real compression and a real dictionary rather than approximations: a new project must not start
+    // with numbers that are honest only by half. Without the optional dependency the metric falls back
+    // to another count and the run returns code 4 — said by the metric label rather than left to a
+    // default.
     minify: { engine: 'esbuild' },
     tokens: { family: 'openai', encoding: 'o200k_base' },
     columns: columns,
@@ -238,30 +234,30 @@ export function projectConfig(root) {
       anchor: 'heading'
     },
     links: { commitUrl: commitUrlOf(root) },
-    // Исключения — всё, что колонкой не стало: то, что ею быть не может, и то, чего
-    // git не отслеживает (путь из одной истории). Так первый запуск полон, а
-    // названное в `skip` — это ответ на вопрос «почему его нет в отчёте».
+    // Exceptions are everything that did not become a column: what cannot be one, and what git does
+    // not track (a path from the history alone). That way the first run is complete, and what `skip`
+    // names is the answer to "why is it not in the report".
     skip: [output].concat(files.filter((f) => !taken.has(f.p)).map((f) => f.p))
       .filter((p, i, all) => all.indexOf(p) === i)
   };
 }
 
-/* Путь самого отчёта — в проекте ли он назван (не пустой, не абсолютный и не с
- * выходом наверх): только такой путь дереву можно назвать листом. */
+/* Whether the report's own path lies inside the project (non-empty, not absolute, not climbing out):
+ * only such a path can be named as a leaf of the tree. */
 const ownPath = (output) => output !== '' && !path.isAbsolute(output) && output.indexOf('..') !== 0;
 
-/* Каталог проекта для страницы: все пути, которые видит git, и причина у тех из
- * них, что колонкой не стали (`null` — стал: страница по этому знаку решает, лист
- * — галочка или подпись). Дерево страницы — дерево проекта, поэтому пути берутся
- * из индекса, а не из колонок; причины — **теми же** правилами, по которым профиль
- * выбирает колонки (`generated` и предел размера), иначе подсказка говорила бы
- * одно, а выбор колонок делал другое. Колонка, чьего файла на HEAD уже нет, в
- * каталог не попадает: в индексе её нет, а на месте в дереве её держит страница.
+/* The project catalogue for the page: every path git sees, with a reason for those that did not become
+ * columns (`null` means it did — the page reads this mark to decide between a checkbox and a label).
+ * The page's tree is the project's tree, so the paths come from the index rather than from the columns,
+ * and the reasons follow **the same** rules the profile uses to pick columns (`generated` and the size
+ * limit) — otherwise the hint would say one thing while the choice of columns did another. A column
+ * whose file is gone from HEAD does not enter the catalogue: the index does not hold it, and the page
+ * keeps its place in the tree.
  *
- * Сам отчёт в каталоге есть всегда — и пока он ещё не собран, и когда он вне git:
- * его отслеживаемость — свойство момента, а не проекта. Зависеть от неё отчёт не
- * должен: иначе первая же пересборка в свежем клоне даёт другие байты (отчёт в
- * каталоге появился), и хук коммитит его второй раз на пустом месте. */
+ * The report itself is always in the catalogue, both before it is first built and while it is not
+ * tracked: whether it is tracked is a property of the moment rather than of the project. The report
+ * must not depend on it — otherwise the first rebuild in a fresh clone yields different bytes (the
+ * report appeared in the catalogue) and the hook commits it a second time out of nowhere. */
 export function projectTree(root, output, measured) {
   const files = indexFiles(root);
   if (ownPath(output) && files.every((f) => f.p !== output)) files.push({ p: output, size: 0 });
@@ -272,9 +268,9 @@ export function projectTree(root, output, measured) {
   }));
 }
 
-/* Имя черновика (`sniffColumns`) осталось публичным: на него опираются те, кто звал
- * вывод колонок (`test/api.test.js` держит список имён), и форма ответа та же —
- * колонки, знакомые расширения проекта и сколько путей всего. */
+/* The draft's name (`sniffColumns`) stays public: the callers of the column output rely on it
+ * (`test/api.test.js` holds the list of names), and the shape of the answer is the same — columns,
+ * the extensions the project knows, and how many paths there are in total. */
 export function sniffColumns(root) {
   const files = allPaths(root);
   const exts = [...new Set(files.map((f) => path.extname(f.p).toLowerCase()))]
@@ -282,20 +278,20 @@ export function sniffColumns(root) {
   return { columns: projectConfig(root).columns, exts: exts, total: files.length };
 }
 
-/* Что сказать человеку, когда настроек нет и работать пришлось на выведенных: одна
- * строка про то, что вышло, и одна — про то, чем это закрепить. Текст — тем же
- * списком, что и находка `doctor`: два ответа об одном не должны разойтись словами. */
+/* What to tell a person when there is no settings file and the settings had to be derived: one line
+ * about what came out, one about how to pin it. The text comes from the same list as the `doctor`
+ * finding: two answers about one thing must not drift apart in words. */
 export function derivedSummary(cfg) {
   const labels = cfg.columns.map((c) => c.label);
-  return 'настройки выведены из проекта (файла нет): колонок ' + cfg.columns.length
+  return 'settings derived from the project (no file): columns ' + cfg.columns.length
     + ' (' + labels.slice(0, 5).join(', ') + (labels.length > 5 ? ', …' : '') + '),'
-    + ' исключено путей ' + cfg.skip.length;
+    + ' paths skipped ' + cfg.skip.length;
 }
 
 export function derivedLines(cfg) {
   return [
     '! ' + derivedSummary(cfg),
-    '  закрепить их файлом (дальше правьте как удобно; иначе состав колонок меняется'
-      + ' от прогона к прогону): ' + cliCommand('--init')
+    '  pin them with a file of their own (then edit it as you like; otherwise the set of columns'
+      + ' changes from run to run): ' + cliCommand('--init')
   ];
 }