@vernikr/size-report 2.4.0 → 2.6.0

package/src/cli.js

@@ -9,22 +9,19 @@ import {
   checkMode, coverageMode, dataMode, doctorMode, explainMode, hookMode, jsonMode, writeMode
 } from './modes.js';
 
-/* Вход инструмента: разбор строки, чтение проекта и доставка запроса режиму.
+/* The tool's entry point: parse the line, read the project, hand the request to a mode.
  *
- * Здесь не осталось ни грамматики (`src/args.js`), ни самих режимов
- * (`src/modes.js`), ни закрепления настроек (`src/init.js`) — только то, без чего
- * вход не вход: откуда берётся корень проекта, каким ключом назван файл настроек и
- * как отказ превращается в код выхода. Здесь же сказано вслух, когда настроек нет
- * и работа идёт на выведенных из проекта: это общее для всех режимов, а не их дело. Разделение не косметическое: цепочка
- * ветвлений «что запрошено» росла с каждым режимом и держала сложность входа, а
- * правила грамматики и тексты отказов проверяются своим каталогом
- * (`tools/refusals.js`), который считает их места в исходниках.
+ * Neither the grammar (`src/args.js`) nor the modes (`src/modes.js`) nor pinning the
+ * settings (`src/init.js`) is left here — only what makes this an entry point at all:
+ * where the project root comes from, how the settings file is named, and how a refusal
+ * turns into an exit code. Saying out loud that there is no settings file and the settings
+ * were derived from the project belongs here as well: that holds for every mode, not for
+ * one of them.
  */
 
-/* Исполнитель запроса: ключ — то, чем запрос назван (команда или режим), а «просто
- * запуск» — пустая строка. Разбор уже проверил сочетания, поэтому здесь остаётся
- * выбор из готового списка, а не решение: у каждого названного есть свой
- * исполнитель, и вызывается он без пробежек по `if`. */
+/* Request runners: the key is what the request is called (a command or a mode), and "a
+ * bare run" is the empty string. The parser has already checked the combinations, so this
+ * is a lookup with a runner for every name, not a decision. */
 const RUNNERS = {
   check: (c, x) => coverageMode(x.cfg, x.root, x.configFile, c.json),
   explain: (c, x) => explainMode(x.cfg, x.root, c.arg[0], c.json),
@@ -35,26 +32,26 @@ const RUNNERS = {
 
 const asked = (cmd) => (cmd.verb === null ? (cmd.mode === null ? '' : cmd.mode) : cmd.verb);
 
-/* Постановка хука без спроса — здесь, а не в `doctor` и не в `hook-run`: первый
- * только докладывает, а второй зовётся уже из поставленного хука. Ставится один раз
- * в клоне и называется вслух, дальше молчит: отчёт обновляется после каждого
- * коммита без ручного шага (устройство и границы — `src/hook.js`). */
+/* Installing the hook without being asked belongs here, not in `doctor` (which only
+ * reports) and not in `hook-run` (which is called from an already installed hook). It
+ * installs once per clone, says so, and is silent afterwards: the report is rebuilt after
+ * every commit with no manual step (design and limits: `src/hook.js`). */
 function ensureHook(root, cfg) {
   const files = autoInstall(root, cfg);
   if (files === null) return;
-  console.error('· хук поставлен: ' + files.join(', ') + ' — отчёт обновляется после каждого'
-    + ' коммита (снять: ' + cliCommand('uninstall-hook') + ')');
+  console.error('· hook installed: ' + files.join(', ') + ' — the report is rebuilt after every'
+    + ' commit (remove it: ' + cliCommand('uninstall-hook') + ')');
 }
 
-/* Доставка. Диагностика и хук отвечают до чтения настроек: им нужен не весь
- * проект, а окружение, и отказывать им из-за настроек было бы неверно — про
- * настройки они как раз и докладывают. */
+/* Delivery. Diagnostics and the hook answer before the settings are read: they need the
+ * environment rather than the whole project, and refusing them over settings would be
+ * wrong — the settings are exactly what they report about. */
 function deliver(cmd, base) {
   if (cmd.verb === 'doctor') return doctorMode(base.root, base.configFile, cmd.json);
   if (HOOK_COMMANDS.indexOf(cmd.verb) >= 0) return hookMode(cmd.verb, base.root, base.configFile);
   const ctx = { root: base.root, configFile: base.configFile, cfg: loadConfig(base.configFile, base.root) };
-  // Примечание идёт в stderr: у `--json` и `--data` в stdout лежат данные, и
-  // подмешивать в них рассказ о настройках значило бы ломать разбор.
+  // The note goes to stderr: `--json` and `--data` own stdout, and mixing a story about
+  // the settings into data would break parsing.
   if (ctx.cfg.derived) derivedLines(ctx.cfg).forEach((line) => console.error(line));
   ensureHook(base.root, ctx.cfg);
   return RUNNERS[asked(cmd)](cmd, ctx);
@@ -77,11 +74,11 @@ export function main() {
       console.error('✗ ' + e.message);
       return e.code;
     }
-    // Непредвиденное — дефект инструмента, а не тупик пользователя: так это и
-    // сказано в тексте (иначе человек ищет ошибку у себя), а стек нужен целиком,
-    // иначе такой отказ нечем разбирать.
-    console.error('✗ внутренняя ошибка (это дефект инструмента, а не проекта —'
-      + ' пришлите, пожалуйста, этот текст целиком):\n' + e.stack);
+    // Unexpected failures are a defect of the tool, not a dead end for the user, and the
+    // text says so — otherwise the user looks for the mistake on their side. The stack is
+    // printed whole: nothing else can diagnose such a refusal.
+    console.error('✗ internal error (this is a defect of the tool, not of the project —'
+      + ' please send this text whole):\n' + e.stack);
     return EXIT.INTERNAL;
   }
 }

package/src/config.js

@@ -9,36 +9,35 @@ import { TOKEN_DEFAULTS, TOKEN_FAMILIES } from './tokens.js';
 import { CATEGORY_ORDER } from './data.js';
 import { projectConfig } from './project.js';
 
-/* Настройки проекта-потребителя: значения по умолчанию, чтение и проверка.
- * Настройки описывают проект, а не механику, поэтому проверка стоит здесь же и
- * без неё не идёт ни один режим. */
+/* The settings of a consumer project: defaults, reading and checking. Settings describe a project
+ * rather than the mechanics, which is why the check lives right here, and no mode runs without it. */
 
 export const CONFIG_NAME = 'size-table.config.json';
 
 export const DEFAULT_CONFIG = {
   output: 'size-report.html',
-  locale: 'ru',
-  title: '',          // по умолчанию — заголовок из локали
+  locale: 'en',
+  title: '',          // by default: the heading from the locale
   heading: '',
-  // Починка — зов, который не может уйти в реестр: путь внутри проекта. Имя
-  // пакета здесь не годится (`npx <имя>` в проекте без пакета — чужой код).
+  // The fix is a call that stays inside the project: the package name would send the reader to the registry,
+  // which serves a revision the project never pinned.
   fixCommand: invocation() + ' --write',
   metrics: ['raw', 'min'],
   columns: [],
-  // `engine` — чем считается метрика `min`: снятием балласта (умолчание, под ним
-  // сняты замороженные эталоны) или настоящим сжатием минификатором.
+  // `engine` says what counts the `min` metric: stripping ballast (the default, and the one the
+  // frozen fixtures were taken under) or real compression by the minifier.
   minify: { engine: 'strip', ext: {}, guard: ['.js', '.mjs', '.cjs'] },
-  // Токены: каким словарём считать. Семейство — про модели, кодировка — про число.
+  // Tokens: which dictionary counts them. The family is about models, the encoding about the number.
   tokens: Object.assign({}, TOKEN_DEFAULTS),
-  // Автоматика хука: хук обновляет отчёт после каждого коммита и ставится сам —
-  // после установки пакета (`bin/postinstall.js`) и при первом запуске в проекте
-  // (`src/hook.js`); этот ключ — её выключатель (`.size-report/…` не нужен: снятие
-  // хука возвращает проект к прежнему поведению).
+  // Hook automation: the hook rebuilds the report after every commit and installs itself — after the
+  // package is installed (`bin/postinstall.js`) and on the first run in a project (`src/hook.js`);
+  // this key is its switch (no `.size-report/…` state is needed: removing the hook returns the
+  // project to its previous behaviour).
   hooks: { enabled: true },
   journal: null,
   links: { commitUrl: '' },
-  // Слияние — обычный коммит: у него есть правки разрешения конфликта, и без
-  // строки они не попали бы в сумму дельт над текущим размером.
+  // A merge is an ordinary commit: it carries the edits that resolved a conflict, and without a row
+  // they would never reach the sum of deltas above the current size.
   rows: { merges: true, sha: true },
   skip: []
 };
@@ -56,49 +55,46 @@ export function gitRoot() {
       encoding: 'utf8', maxBuffer: MAX_BUF, env: gitEnv()
     }).trim();
   } catch (e) {
-    // Два тупика с разной починкой — «git не запустился» и «репозитория здесь нет»,
-    // — и расходятся они по тому, что сказал сам git, а не по догадке: ENOENT
-    // значит, что не нашлась программа. Один текст на оба случая («не git-репозиторий
-    // или git недоступен») не называл ни одного из них.
+    // Two dead ends with different fixes — "git did not start" and "there is no repository here" —
+    // are told apart by what git itself said rather than by a guess: ENOENT means the program was not
+    // found. One text for both ("not a git repository, or git is unavailable") named neither of them.
     if (e.code === 'ENOENT') {
-      refuseCause('нет git', 'git не запустился: его нет в PATH (таблица собирается по его'
-        + ' истории, а смотрю я в ' + process.cwd() + ').\n'
-        + '  починка: поставьте git (https://git-scm.com) и повторите команду');
+      refuseCause('git missing', 'git did not start: it is not in PATH (the table is built from its'
+        + ' history, and the directory I look in is ' + process.cwd() + ').\n'
+        + '  fix: install git (https://git-scm.com) and run the command again');
     }
-    refuseCause('не git-репозиторий', 'git не видит здесь репозитория: таблица собирается по его'
-      + ' истории (сейчас смотрю в ' + process.cwd() + ').\n'
-      + '  смотрите: запущена ли команда из каталога проекта\n'
-      + '  починка: если истории ещё нет — создайте её: git init');
+    refuseCause('not a git repository', 'git sees no repository here: the table is built from its'
+      + ' history (the directory I look in is ' + process.cwd() + ').\n'
+      + '  see: whether the command was run from the directory of the project\n'
+      + '  fix: if there is no history yet, create it: git init');
   }
 }
 
-/* Настроек нет — их выводит сам проект (`src/project.js`), и работа начинается сразу:
- * заводить файл ради первого запуска незачем, а `--init` закрепляет выведенное
- * файлом, когда его хотят править. Так бывает только с умолчательным именем: файл,
- * названный ключом `--config`, — это уже запрос про конкретный файл, и его
- * отсутствие остаётся отказом (иначе опечатка в пути молча дала бы чужие настройки).
- * `path` назван словами, а не путём: файла нет, и текст «правьте <путь>» привёл бы
- * человека к тому, чего в проекте не лежит. */
+/* No settings file — the project derives them (`src/project.js`) and work starts at once: there is no
+ * reason to create a file for a first run, and `--init` pins the derived ones to a file when someone
+ * wants to edit them. This happens for the default name only: a file named by `--config` is already a
+ * request for that very file, so its absence stays a refusal (otherwise a typo in the path would
+ * silently yield someone else's settings). `path` is given in words rather than as a path: there is no
+ * file, and "edit <path>" would lead the reader to something the project does not have. */
 export function derivedConfig(root) {
   const cfg = derivedProfile(root);
-  cfg.path = 'настройки, выведенные из проекта';
+  cfg.path = 'derived from the project';
   cfg.derived = true;
   validateConfig(cfg);
   return cfg;
 }
 
-/* Выведенное из проекта + умолчания — то, чем проект работает без файла, и то,
- * что закрепляет `--init`. Одно место на две роли (иначе «файл» и «работа без
- * файла» разошлись бы колонкой или числом), а сам вывод (`src/project.js`) о
- * умолчаниях не знает: он говорит только то, что видит в проекте. */
+/* Derived from the project plus the defaults — what a project runs on without a file, and what
+ * `--init` pins. One place for two roles (or "the file" and "work without a file" would drift by a
+ * column or a number), while the deriving itself (`src/project.js`) knows nothing of the defaults: it
+ * says only what it sees in the project. */
 export function derivedProfile(root) {
   return withDefaults(projectConfig(root));
 }
 
-/* Настройки поверх умолчаний — одним местом на два источника (файл и проект):
- * вложенное досыпается по ключам, потому что `minify: {engine: …}` не значит «у
- * `minify` больше нет других полей», а значило бы, что снятие балласта потеряло
- * список расширений. */
+/* Settings on top of the defaults — one place for two sources (a file and the project): nested keys
+ * are filled in by key, because `minify: {engine: …}` does not mean "`minify` has no other fields",
+ * and reading it that way would lose the stripping's list of extensions. */
 function withDefaults(raw) {
   const cfg = Object.assign({}, DEFAULT_CONFIG, raw);
   ['minify', 'tokens', 'hooks', 'links', 'rows'].forEach((key) => {
@@ -107,25 +103,25 @@ function withDefaults(raw) {
   return cfg;
 }
 
-/* Настройки читаются как есть и досыпаются значениями по умолчанию: у проекта,
- * который только подключил генератор, конфиг может быть в три строки. */
+/* Settings are read as they are and filled in with the defaults: in a project that has just attached
+ * the generator the config may be three lines long. */
 export function loadConfig(file, root) {
   if (!fs.existsSync(file)) {
-    // Совет называет тот же файл, о котором шла речь: `--init` без файла записал бы
-    // черновик под умолчательным именем в корне проекта — то есть починил бы не то,
-    // о чём спросили. Имя не называем ровно тогда, когда оно и так умолчательное.
+    // The advice names the very file in question: `--init` without a file would write a draft under the
+    // default name in the project root — fixing something other than what was asked. The name is left
+    // out exactly when it is the default one anyway.
     const dflt = root !== undefined && path.resolve(root, CONFIG_NAME) === path.resolve(file);
     if (dflt) return derivedConfig(root);
-    refuseCause('нет файла настроек', 'нет файла настроек ' + file
-      + '\n  создайте его: ' + cliCommand('--init ' + advicePath(file))
-      + '\n  смотрите: без «--config» настройки не нужны — они выводятся из проекта');
+    refuseCause('no settings file', 'no settings file ' + file
+      + '\n  create it: ' + cliCommand('--init ' + advicePath(file))
+      + '\n  see: without "--config" no settings are needed — they are derived from the project');
   }
   let raw;
   try {
     raw = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (e) {
-    refuseCause('настройки не разобраны', 'не разобран ' + file + ': ' + e.message
-      + '\n  починка: правьте ' + file + '; образец настроек даёт ' + cliCommand('--init') + ' в пустом каталоге');
+    refuseCause('settings not parsed', 'cannot parse ' + file + ': ' + e.message
+      + '\n  fix: edit ' + file + '; a sample of settings comes from ' + cliCommand('--init') + ' in an empty directory');
   }
   const cfg = withDefaults(raw);
   cfg.path = file;
@@ -133,23 +129,23 @@ export function loadConfig(file, root) {
   return cfg;
 }
 
-/* Колонки: метка и пути — имена, а не что попало: путь числом или объектом молча не
- * совпадает ни с чем, и колонка отчитывается нулём строк за успех. Отказ обязан
- * случиться здесь, а не превратиться в пустой отчёт. */
+/* Columns: a label and paths have to be names rather than anything at all — a path given as a number
+ * or an object silently matches nothing, and the column reports zero rows as success. The refusal has
+ * to happen here instead of turning into an empty report. */
 function checkColumns(cfg, fail) {
-  if (!cfg.columns || cfg.columns.length === 0) fail('не задано ни одной колонки (columns)');
+  if (!cfg.columns || cfg.columns.length === 0) fail('no columns are given (columns)');
   const labels = new Set();
   cfg.columns.forEach((c, i) => {
     const pathsAreNames = c && Array.isArray(c.paths)
       && c.paths.length > 0 && c.paths.every((p) => typeof p === 'string' && p !== '');
     if (!c || typeof c.label !== 'string' || c.label === '' || !pathsAreNames) {
-      fail('колонка №' + (i + 1) + ' должна быть {label, paths: [...]} из непустых строк: '
-        + JSON.stringify(c).slice(0, 90) + '\n  смотрите: черновик с готовыми колонками даёт '
-        + cliCommand('--init <файл>'));
+      fail('column #' + (i + 1) + ' has to be {label, paths: [...]} of non-empty strings: '
+        + JSON.stringify(c).slice(0, 90) + '\n  see: a draft with ready columns comes from '
+        + cliCommand('--init <file>'));
     }
-    if (labels.has(c.label)) fail('метка колонки «' + c.label + '» повторяется');
+    if (labels.has(c.label)) fail('the column label "' + c.label + '" repeats');
     if (c.category !== undefined && CATEGORY_ORDER.indexOf(c.category) < 0) {
-      fail('категория «' + c.category + '» у колонки «' + c.label + '» неизвестна: '
+      fail('the category "' + c.category + '" of the column "' + c.label + '" is unknown: '
         + CATEGORY_ORDER.join(', '));
     }
     labels.add(c.label);
@@ -157,51 +153,51 @@ function checkColumns(cfg, fail) {
 }
 
 function checkMetrics(cfg, fail) {
-  if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) fail('не заданы метрики (metrics)');
+  if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) fail('no metrics are given (metrics)');
   cfg.metrics.forEach((m) => {
-    if (!METRICS[m]) fail('неизвестная метрика «' + m + '» (есть: ' + Object.keys(METRICS).join(', ') + ')');
+    if (!METRICS[m]) fail('unknown metric "' + m + '" (there are: ' + Object.keys(METRICS).join(', ') + ')');
   });
 }
 
 function checkMinify(cfg, fail) {
   if (MINIFY_ENGINES.indexOf(cfg.minify.engine) < 0) {
-    fail('неизвестный способ минификации «' + cfg.minify.engine + '» (есть: ' + MINIFY_ENGINES.join(', ') + ')');
+    fail('unknown minification engine "' + cfg.minify.engine + '" (there are: ' + MINIFY_ENGINES.join(', ') + ')');
   }
 }
 
 function checkTokens(cfg, fail) {
   const family = TOKEN_FAMILIES[cfg.tokens.family];
   if (family === undefined) {
-    fail('неизвестное семейство токенизатора «' + cfg.tokens.family + '» (есть: '
+    fail('unknown tokenizer family "' + cfg.tokens.family + '" (there are: '
       + Object.keys(TOKEN_FAMILIES).join(', ') + ')');
   }
   if (family.encodings.indexOf(cfg.tokens.encoding) < 0) {
-    fail('неизвестная кодировка токенизатора «' + cfg.tokens.encoding + '» у семейства '
-      + cfg.tokens.family + ' (есть: ' + family.encodings.join(', ') + ')');
+    fail('unknown tokenizer encoding "' + cfg.tokens.encoding + '" of the family '
+      + cfg.tokens.family + ' (there are: ' + family.encodings.join(', ') + ')');
   }
 }
 
-/* Файл таблицы не может быть её колонкой: размер артефакта зависит от числа строк,
- * то есть от самого себя. */
+/* The report file cannot be a column of itself: the size of the artifact depends on the number of
+ * rows, that is, on itself. */
 function checkOutput(cfg, fail) {
   cfg.columns.forEach((c) => {
-    if (c.paths.indexOf(cfg.output) >= 0) fail('файл таблицы (' + cfg.output + ') не может быть колонкой');
+    if (c.paths.indexOf(cfg.output) >= 0) fail('the size table file (' + cfg.output + ') cannot be a column');
   });
-  if (!cfg.output) fail('не задан output');
+  if (!cfg.output) fail('output is not set');
 }
 
 function checkJournal(cfg, fail) {
   if (!cfg.journal) return;
-  if (!cfg.journal.path) fail('journal.path не задан');
-  if (!cfg.journal.pattern) fail('journal.pattern не задан');
-  try { new RegExp(cfg.journal.pattern); } catch (e) { fail('journal.pattern не компилируется: ' + e.message); }
+  if (!cfg.journal.path) fail('journal.path is not set');
+  if (!cfg.journal.pattern) fail('journal.pattern is not set');
+  try { new RegExp(cfg.journal.pattern); } catch (e) { fail('journal.pattern does not compile: ' + e.message); }
 }
 
-/* Что настройки говорят про путь: `columns` — его отслеживает колонка, `excluded` — он
- * объявлен исключением (`skip` и сам файл отчёта), `outside` — мимо того и другого.
- * Суждение одно на два ответа: `check` спрашивает его про всю историю, `explain` — про
- * один коммит. Знакомство считается по колонкам целиком, а не по метке: у колонки путей
- * может быть несколько (переименование), и любой из них — она сама. */
+/* What the settings say about a path: `columns` — a column tracks it, `excluded` — it is declared an
+ * exception (`skip` and the report file itself), `outside` — neither. One judgement for two answers:
+ * `check` asks it about the whole history, `explain` about a single commit. Membership is counted over
+ * all paths of a column rather than by its label: a column may have several paths (a rename), and any
+ * of them is that column. */
 export function pathRoles(cfg) {
   const tracked = new Set();
   cfg.columns.forEach((col) => col.paths.forEach((p) => tracked.add(p)));
@@ -212,26 +208,26 @@ export function pathRoles(cfg) {
   };
 }
 
-/* Починка «мимо колонок» — один текст на два ответа, и он называет пути: команда без
- * имён не команда. Текст собирается из имён, а не приписывает их по ветке, поэтому и
- * предусматривать тут нечего: коммит без файлов вовсе починки не получает — на пустом
- * списке её не зовут (см. `fixFor` в `src/explain.js`). */
+/* The fix for "outside the columns" — one text for two answers, and it names the paths: a command
+ * without names is no command. The text is assembled from the names rather than appending them per
+ * branch, which is why nothing has to be guarded here: a commit with no files at all gets no fix — the
+ * list being empty, nobody calls it (`fixFor` in `src/explain.js`). */
 export function outsideFix(paths) {
-  return 'допишите эти пути колонкой или в «skip» файла ' + CONFIG_NAME + ': ' + paths.join(', ');
+  return 'add these paths as a column or to "skip" of ' + CONFIG_NAME + ': ' + paths.join(', ');
 }
 
 export function validateConfig(cfg) {
-  const fail = (msg) => refuseCause('настройки неверны',
-    'конфиг ' + cfg.path + ': ' + msg + '\n  починка: правьте ' + cfg.path);
+  const fail = (msg) => refuseCause('settings invalid',
+    'config ' + cfg.path + ': ' + msg + '\n  fix: edit ' + cfg.path);
   checkColumns(cfg, fail);
   checkMetrics(cfg, fail);
   checkMinify(cfg, fail);
   checkTokens(cfg, fail);
-  if (!LOCALES[cfg.locale]) fail('неизвестная локаль «' + cfg.locale + '» (есть: ' + Object.keys(LOCALES).join(', ') + ')');
-  // Выключатель хука — «да/нет», а не «правда/ложь»: `false` от случайной строки
-  // отличать обязан инструмент, иначе выключенная автоматика осталась бы включённой.
+  if (!LOCALES[cfg.locale]) fail('unknown locale "' + cfg.locale + '" (there are: ' + Object.keys(LOCALES).join(', ') + ')');
+  // The hook switch is a yes/no rather than a truthy/falsy one: the tool has to tell `false` from a
+  // stray string, or switched-off automation would stay switched on.
   if (typeof cfg.hooks.enabled !== 'boolean') {
-    fail('hooks.enabled — не «да/нет»: ' + JSON.stringify(cfg.hooks.enabled));
+    fail('hooks.enabled is not a yes/no: ' + JSON.stringify(cfg.hooks.enabled));
   }
   checkOutput(cfg, fail);
   checkJournal(cfg, fail);

package/src/css.js

@@ -1,23 +1,23 @@
 import fs from 'node:fs';
 
-/* Оформление отчёта — обычные `.css` рядом с кодом, а не строки внутри модулей:
- * то же правило, что и у программы страницы (`src/page/app.js`), — исходник видит
- * редактор, а не только шаблонная строка. Читаются они с диска относительно
- * своего места, поэтому работают и у того, кто поставил пакет.
+/* The report's styling is ordinary `.css` next to the code rather than strings inside modules — the same rule
+ * as for the page's program (`src/page/app.js`): an editor sees a real source file instead of a template
+ * string. They are read from disk relative to their own place, so they work for whoever installed the package
+ * as well.
  *
- * Наборов два, и у каждого своя роль:
+ * There are two sets, each with a role of its own:
  *
- *   1. `table.css` — **таблица**: геометрия клеток, липкие шапка и колонка коммита,
- *      подпись коммита, цвета дельт.
- *   2. `page/app.css` — оформление страницы **сверх таблицы**: холст, панель
- *      выбора, состояния пустоты и адаптации под узкое окно.
+ *   1. `table.css` — the **table**: cell geometry, the sticky header and commit column, a commit's caption,
+ *      the colours of the deltas.
+ *   2. `page/app.css` — the page's look **on top of the table**: the canvas, the panel of choices, the empty
+ *      states and the adaptation to a narrow window.
  *
- * Соглашение о цвете дельт задано один раз — в `table.css`: `.up` зелёный, `.down`
- * красный (рост — «больше логики», а не тревога). Второго места у него нет
- * намеренно: рост не может быть показан разными цветами в двух местах одной
- * страницы. Смена соглашения — две строки в `table.css`.
+ * The convention about the colour of a delta is set once, in `table.css`: `.up` green, `.down` red (growth is
+ * "more logic" rather than alarm). It has no second place on purpose: growth cannot be shown in different
+ * colours in two spots of one page. Changing the convention is two lines in `table.css`.
  *
- * Путь у `readCss` — от каталога `src/`: так его видит движок, где бы он ни лежал.
+ * The path given to `readCss` is relative to the `src/` directory: that is how the engine sees it wherever it
+ * lies.
  */
 
 export const TABLE_CSS = readCss('./table.css');

package/src/data.js

@@ -6,15 +6,13 @@ import { build, skipLine } from './history.js';
 import { projectTree } from './project.js';
 import { TOOL_PKG } from './tool.js';
 
-/* Категории файлов и контракт со страницей: абсолютные значения и устройство
- * таблицы, без единой производной величины. Всё, что страница считает сама,
- * начинается там, где этот модуль заканчивается. */
+/* File categories and the contract with the page: absolute values and the shape of the table, with no
+ * derived quantity at all. Everything the page counts itself begins where this module ends. */
 
-/* Категория файла — только для быстрых кнопок «включить/выключить группу» на
- * странице: на числа она не влияет. Правило одно — расширение даёт категорию, всё
- * остальное считается кодом; категория, заданная в настройках колонки, старше
- * правила, и в данных видно, откуда она взялась (`categoryBy`): ручное решение
- * объяснимо, а таблица расширений — догадка по имени файла. */
+/* A file's category is only for the page's quick on/off buttons for a group: it does not reach the
+ * numbers. The rule is one: the extension gives the category, everything else counts as code; a category
+ * set in the column's settings outranks that rule, and the data says where it came from (`categoryBy`) — a
+ * manual decision is explainable, while a table of extensions is a guess by file name. */
 export const CATEGORY_EXTS = {
   docs: ['.md', '.markdown', '.rst', '.txt', '.adoc'],
   chore: ['.json', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.conf', '.lock', '.editorconfig'],
@@ -29,15 +27,14 @@ export function categoryOf(col) {
   return { key: known === undefined ? 'code' : known, by: 'auto' };
 }
 
-/* Контракт между движком и страницей: абсолютные значения и устройство таблицы —
- * и ни одной производной величины. Дельты, суммы, «сейчас» и фильтры считает
- * страница: движок не знает, что включено в просмотр, поэтому заранее посчитать
- * сумму он не может. Числа в контракте те же, что в артефакте, — это та же правда,
- * разложенная по полям.
+/* The engine-to-page contract: deltas, totals, "now" and the filters are counted by the page — the engine
+ * does not know what is switched on in the view, so it cannot total anything up in advance. The numbers
+ * here are the same as in the artifact: one truth laid out in fields.
  *
- * Причины пропущенных коммитов идут строками — и остаются ими: у страницы нет
- * вопроса, на который пригодилось бы поле («почему у коммита нет строки» задают
- * командой `explain`, и там причина уже разложена). */
+ * The reasons of skipped commits travel as strings and stay strings: they are sentences for a person, and
+ * the question behind them (why a commit has no row) is asked by the `explain` command, where the reason is
+ * laid out into fields. The page does not carry this list at all, and on purpose: the report's own commit
+ * is one of the skipped ones, so the file would never become a fixed point. */
 export function reportData(cfg, root) {
   const { rows, state, dropped, last } = build(cfg, root);
   const loc = LOCALES[cfg.locale];
@@ -67,45 +64,24 @@ export function reportData(cfg, root) {
     categories: CATEGORY_ORDER.filter((key) => files.some((f) => f.category === key))
       .map((key) => ({ key: key, label: loc.categories[key] })),
     files: files,
-    /* Дерево страницы — дерево проекта: все пути, а не только колонки. Числа есть
-     * лишь у колонок, поэтому у каждой записи каталога сказано, чего ей не
-     * досталось: `why` пусто — файл измеряется, иначе названа причина. */
+    /* The page's tree is the project's tree: every path rather than the columns alone. The numbers belong to
+     * columns only, which is why each catalogue entry says what it did not get: `why` empty — the file is
+     * measured, otherwise a reason is named. */
     catalog: projectTree(root, cfg.output, files.map((f) => (f.path === null ? f.paths[0] : f.path))),
     rows: rows.map((r) => Object.assign(rowShape(r),
       { href: rowHref(r.section, r.sha, cfg), values: r.cells })),
     now: state.map((s) => (s === null ? null : s.cells)),
-    /* Какие колонки тронул последний коммит: страница по этому знаку ставит их
-     * впереди — читателю нужнее то, что изменилось только что. Это факт из истории,
-     * а не производная величина: она не считает, а говорит, чего коснулась правка. */
+    /* Which columns the last commit touched: the page puts those in front by this mark — a reader needs what
+     * changed just now rather than the rest. This is a fact from the history rather than a derived quantity:
+     * it does not count anything, it says what the edit touched. */
     last: last,
-    approx: approxMarks(rows, state, cfg),
     skipped: dropped.map(skipLine)
   };
 }
 
-/* Пометки приближённых клеток — по одной записи на метрику: строка знаков по
- * клеткам строк и строка знаков по верхней строке «сейчас». '1' — число получено
- * упрощением или оценкой, '0' — точное. Метрика без ни одной пометки в отчёте не
- * появляется вовсе: все числа точны — молчание.
- *
- * Знак ставит движок там же, где считает число, — из того же правила, что и
- * подпись метрики. Поэтому страница ничего про пути и форматы не выводит: она
- * только показывает то, что сказано, и второго правила точности не заводит. */
-function approxMarks(rows, state, cfg) {
-  const out = {};
-  cfg.metrics.forEach((m) => {
-    const mark = (flags) => (flags !== null && flags[m] ? '1' : '0');
-    const inRows = rows.map((r) => r.approx.map(mark).join('')).join('');
-    const now = state.map((s) => mark(s === null ? null : s.approx)).join('');
-    if (inRows.indexOf('1') >= 0 || now.indexOf('1') >= 0) out[m] = { rows: inRows, now: now };
-  });
-  return out;
-}
-
-/* Общая часть строки ответа: она есть и у контракта страницы (`--data`), и у
- * прежней формы `--json` (она заморожена эталоном паритета). Одно место — потому
- * что разойтись эти два ответа могут ровно здесь, а **порядок полей и есть байты
- * ответа**: они в объекте в том же порядке, в каком их печатает замороженная форма. */
+/* The part of a row shared by both answers: the page's contract (`--data`) and the older `--json` form (frozen
+ * by the parity fixture). One place, because these two answers can drift apart exactly here, and **the order
+ * of the fields is the bytes of the answer**: the object holds them in the order the frozen form prints. */
 export function rowShape(r) {
   return {
     sha: r.sha,
@@ -115,7 +91,7 @@ export function rowShape(r) {
   };
 }
 
-/* Производные величины живут в `src/derived.js`: их считает и артефакт (импорт
- * ниже), и страница (получает тот же файл текстом). Второго расчёта той же
- * таблицы нет вовсе, поэтому разойтись молча двум отчётам нечем — это стережёт
- * `test/contract-derived.test.js`. */
+/* The derived quantities live in `src/derived.js`: the page gets that whole file pasted into itself as text
+ * (`pageScript`), while the terminal answers import it. There is no second calculation of the same table, so
+ * the page's numbers and the artifact's bytes have nothing to drift apart with — `test/contract-derived.test.js`
+ * guards that. */