@vernikr/size-report 2.4.0 → 2.5.0

package/src/page/app.js

@@ -2,20 +2,19 @@ import { appData, appUi, appView, appWrite, appNotice, appLinkUse, appRead, appA
 import { appBody, appHead, appState } from './table.js';
 import { appPanel } from './panel.js';
 
-/* Сборка таблицы: что показывать (метрики и файлы, оставленные читателем) и куда
- * это положить. Разметку шапки и строк строит глава таблицы, числа — общий расчёт:
- * здесь остаётся только решение и вставка, своих чисел у сборки нет. */
+/* Assembling the table: what to show (the metrics and files the reader left on) and where to put it. The table
+ * chapter builds the markup of the head and the rows, the shared calculation gives the numbers — all that is
+ * left here is the decision and the insertion, with no numbers of its own. */
 function appTable() {
   const shown = appData.metrics.filter((m) => appView.metrics[m.key]);
   const metrics = shown.map((m) => m.key);
   const on = appView.files;
   const files = [];
   appData.files.forEach((f, i) => { if (on[i]) files.push(i); });
-  /* Колонки, которых коснулся последний коммит, идут впереди: отчёт пересобирается
-   * после каждого коммита, и первый вопрос читателя — что принесла эта правка. Внутри
-   * каждой части порядок прежний, из настроек: `sort` устойчив, а порядок колонок — это
-   * то, к чему читатель привык. Знак берётся из истории (её знает движок), а не из
-   * чисел: правка без изменения размера тоже правка. */
+  /* The columns the last commit touched come first: the report is rebuilt after every commit, and a reader's first
+   * question is what that edit brought. Inside each part the order stays as it comes from the settings — `sort` is
+   * stable, and the order of the columns is what the reader is used to. The mark comes from the history (which the
+   * engine knows) rather than from the numbers: an edit that changed no size is an edit too. */
   files.sort((a, b) => (appData.last[a] === true ? 0 : 1) - (appData.last[b] === true ? 0 : 1));
 
   const table = document.getElementById('grid');
@@ -31,12 +30,11 @@ function appTable() {
   appWrite();
 }
 
-/* Прокрутка панели — свойство панели, а не разметки, поэтому она переживает
- * пересборку: иначе каждый клик по галочке возвращал бы список к началу, и до
- * нижних файлов дерева было бы не добраться. Запоминается прокрутка панели и
- * списка файлов — у каждого она своя, а в узком окне прокручивается список.
- * Элементы берутся те, что есть в разметке страницы (`src/page/build.js`):
- * второго перечисления мест прокрутки в пакете нет. */
+/* The panel's scroll is a property of the panel rather than of the markup, which is why it survives a rebuild:
+ * otherwise every click on a checkbox would send the list back to the top and the files at its end would be
+ * unreachable. Both the panel's scroll and the file list's are remembered — each has one of its own, and in a
+ * narrow window it is the list that scrolls. The elements are the ones the page really has (`#panel` from the
+ * markup, `.files` inside it from the panel): there is no second list of scroll places in the package. */
 const appScrolled = ['#panel', '#panel .files'];
 function appScrollTop() {
   return appScrolled.map((sel) => {
@@ -52,12 +50,11 @@ function appScrollBack(saved) {
   });
 }
 
-/* Панель перерисовывается целиком, поэтому поле, стоящее под клавиатурой, и
- * прокрутка после каждой пересборки возвращаются на своё место: иначе
- * переключение с Tab и Space требовало бы начинать обход панели заново, а
- * прокрутка — искать своё место заново. Место поля опознаётся порядковым номером —
- * порядок полей панели от данных не зависит. Фокус ставится без прокрутки (`preventScroll`):
- * он возвращает клавиатуру, а не двигает список. */
+/* The panel is redrawn whole, so the field under the keyboard and the scroll come back to their places after every
+ * rebuild: otherwise switching with Tab and Space would mean walking the panel from the start again, and the scroll
+ * would have to find its place anew. A field is identified by its ordinal number — the order of the panel's fields
+ * does not change between rebuilds. The focus is set without scrolling (`preventScroll`): it returns the keyboard
+ * rather than moving the list. */
 function appRender(keepNotice) {
   const at = Array.from(document.querySelectorAll('#panel input')).indexOf(document.activeElement);
   const saved = appScrollTop();
@@ -65,16 +62,16 @@ function appRender(keepNotice) {
   appScrollBack(saved);
   if (at >= 0) document.querySelectorAll('#panel input')[at].focus({ preventScroll: true });
   appTable();
-  /* Сообщение о ссылке переживает отрисовку, которая сама же им и вызвана, и
-   * гаснет от действия читателя: он его уже прочитал. */
+  /* The message about the link survives the very drawing it caused, and fades on the reader's next action: he has read
+   * it by then. */
   if (keepNotice !== true) appNotice('');
 }
 
-/* Восстановление — до первой отрисовки: у того, кто открыл страницу впервые,
- * разметка обязана быть умолчанием, а не чужим выбором. Ссылка старше памяти: это
- * явный выбор отправителя, и пока читатель ничего не менял, она его собственный
- * выбор не подменяет — в память её запись не идёт. Отказ ссылки — не пустая
- * таблица, а сообщение: читателю видно и что произошло, и что показано вместо. */
+/* Restoring happens before the first drawing: for someone opening the page for the first time the view has to be the
+ * default rather than someone else's choice. A link outranks the memory: it is the sender's explicit choice, and
+ * while the reader has changed nothing it does not replace his own — writing it to the memory is what does not
+ * happen. A refused link is not an empty table but a message: the reader sees both what happened and what is shown
+ * instead. */
 const appStart = appLinkUse();
 if (appStart === 'ours') appTransient = true;
 else if (appStart === 'refused') appForeign = true;
@@ -82,20 +79,18 @@ if (appStart !== 'ours') {
   const appSaved = appRead();
   if (appSaved !== null) appApply(appSaved);
 }
-/* Сложенное дерево — память смотрящего, а не выбор читателя: она возвращается и
- * тогда, когда открыта чужая ссылка (иначе присланная ссылка разложила бы дерево
- * заново на каждом заходе). */
+/* The folded tree is the onlooker's memory rather than the reader's choice: it comes back even when someone else's
+ * link is open (otherwise a link sent over would unfold the tree again on every visit). */
 appFoldRead();
 appRender(true);
 appStartup = false;
 appForeign = false;
 appTransient = false;
 
-/* Якорь сменился на открытой странице: выбор из нового адреса применяется тем же
- * кодом, что и при открытии. Свой собственный адрес такого события не поднимает
- * (`replaceState` его не вызывает), поэтому петли здесь нет. Отказ не трогает ни
- * вид — читатель продолжает смотреть то, что смотрел, — ни адрес: его прислали
- * читателю, и до первого его действия это не наше. */
+/* The anchor changed on an open page: the choice in the new address is applied by the same code as at opening. The
+ * page's own address raises no such event (`replaceState` does not), so there is no loop here. A refusal touches
+ * neither the view — the reader keeps looking at what he looked at — nor the address: it was sent to the reader,
+ * and until he acts it is not ours. */
 window.addEventListener('hashchange', () => {
   const state = appLinkUse();
   if (state === 'refused') appForeign = true;

package/src/page/build.js

@@ -2,27 +2,25 @@ import fs from 'fs';
 import { fill, LOCALES } from '../locales.js';
 import { PAGE_CSS, TABLE_CSS } from '../css.js';
 
-/* Экранирование текста в разметке — здесь, потому что единственный, кто собирает
- * разметку из данных, — эта сборка: остальное рисует страница узлами. */
+/* Escaping text for markup lives here, because this builder is the only place that turns data into markup: the rest
+ * is drawn as nodes by the page. */
 export function esc(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
 
-/* Сборка страницы отчёта: данные и программа в одном файле, внешних ссылок нет.
- * Оформление — тоже обычные файлы: общая часть таблицы (`table.css`) и своё
- * оформление страницы (`app.css`).
+/* Building the report's page: data and program in one file, with no external reference. The styling comes as ordinary
+ * files too: the table's shared part (`table.css`) and the page's own (`app.css`).
  *
- * Программа страницы — обычные исходники (главы `src/page/*.js` и общий расчёт
- * `src/derived.js`), а не строки в движке: их видит линтер, их же движок
- * вклеивает в страницу. Модульный синтаксис снимается при вклейке: в браузере,
- * открывшем файл с диска, разрешать `import` нечем, а объявления обязаны попасть
- * в общую область видимости в порядке вклейки — сперва расчёт, затем главы.
+ * The page's program is ordinary sources (the chapters in `src/page/*.js` and the shared calculation in
+ * `src/derived.js`) rather than strings inside the engine: a linter sees them, and the engine pastes them into the
+ * page. Module syntax is removed while pasting: in a browser that opened a file from disk there is nothing to resolve
+ * `import` with, and the declarations have to reach the shared scope in the order of pasting — the calculation first,
+ * then the chapters.
  *
- * Главы — по предметам страницы, и порядок вклейки (список ниже) — это порядок
- * объявлений в собранной программе: первым идёт расчёт, за ним состояние
- * выбора, узлы, панель, таблица и сборка. Главы — **срезы одного текста**: вклейка
- * склеивает их подряд, поэтому собранная страница осталась бы той же, если бы
- * главы снова стали одним файлом. */
+ * The chapters follow the page's subjects, and the order of pasting (the list below) is the order of declarations in
+ * the assembled program: the calculation first, then the choice's state, the nodes, the panel, the table and the
+ * assembling. The chapters are **slices of one text**: pasting glues them in a row, so the assembled page would stay
+ * the same if the chapters became one file again. */
 export function stripModules(src) {
   return src.split('\n')
     .filter((line) => !/^import\s.*;\s*$/.test(line))
@@ -34,16 +32,16 @@ export function pageSource(file) {
   return stripModules(fs.readFileSync(new URL(file, import.meta.url), 'utf8'));
 }
 
-/* Список глав — здесь же, а не в проверках: он один на сборку и на сторожа
- * (`test/page-view.test.js` читает ту же программу и сверяет её с исходниками). */
+/* The list of chapters lives here rather than in the tests: one copy for the builder and for the guard
+ * (`test/page-view.test.js` reads the same program and compares it with the sources). */
 export const PAGE_PARTS = ['./state.js', './dom.js', './panel.js', './table.js', './app.js'];
 
 export function pageScript() {
   return pageSource('../derived.js') + '\n' + PAGE_PARTS.map((part) => pageSource(part)).join('');
 }
 
-/* Подпись под заголовком: чем собран отчёт и где он лежит. Путь — текстом, а не
- * ссылкой: страница открывается с диска и ни от чего не зависит. */
+/* The note under the heading: what built the report and where it lies. The path is plain text rather than a link: the
+ * page opens from disk and depends on nothing. */
 function subText(data, page) {
   return fill(page.sub, {
     tool: data.tool.name,
@@ -52,8 +50,8 @@ function subText(data, page) {
   });
 }
 
-/* Тексты страницы: заголовки колонок, подписи панели, легенда и состояния. В
- * артефакт они не идут — это словарь страницы, а не отчёта. */
+/* The page's texts: column captions, panel labels, the legend and the empty states. They are the page's dictionary
+ * rather than the report's: the data block carries none of them, and the report's own words live in the locale. */
 function uiText(page, loc) {
   return {
     commit: loc.commit,
@@ -69,29 +67,35 @@ function uiText(page, loc) {
     linkForeign: page.linkForeign,
     linkBroken: page.linkBroken,
     linkExtra: page.linkExtra,
-    /* Точность — двумя словами: подпись метрики говорит про худшее в колонке,
-     * подсказка клетки — про её собственное число. */
+    /* Accuracy in two words: a metric's caption speaks about the worst in its column, while a cell's tooltip speaks
+     * about its own number. */
     exact: page.exact,
     approximate: page.approximate,
     approxCell: page.approximateCell,
-    /* Почему файла нет в отчёте — словами: причину называет движок знаком (`why`),
-     * а страница одевает знак в текст, как и всё остальное в панели. */
+    /* Why a file is not in the report, in words: the engine names the reason with a mark (`why`), and the page dresses
+     * the mark in text, as it does with everything else in the panel. */
     notMeasuredRule: page.notMeasuredRule,
     notMeasuredChoice: page.notMeasuredChoice,
+    /* The tooltip of a file's checkbox: where the file stands and how its category was decided. The
+     * panel keeps no words of its own — a Russian report stays Russian in its chrome too, and an
+     * English one gets English there. */
+    notOnHead: page.notOnHead,
+    category: page.category,
+    categoryFromConfig: page.categoryFromConfig,
+    categoryByExtension: page.categoryByExtension,
     methodLabel: page.panelMethod,
     empty: page.emptyMetrics,
     noFiles: page.noFiles,
-    /* {command} подставляет страница: у неё есть данные, а {now} — уже здесь. */
+    /* {command} is substituted by the page, which holds the data, while {now} is filled in here. */
     note: page.note.replace(/\{now\}/g, loc.now)
   };
 }
 
-/* Что в файл не идёт. Первое — список пропущенных коммитов: он меняется от
- * коммита самого отчёта (тот, кому нечего сказать, попадает в список), и файл
- * перестал бы быть **неподвижной точкой** — пересборка после его же коммита давала
- * бы другие байты, а хук коммитил бы отчёт бесконечно. Странице этот список не
- * нужен вовсе: она его не показывает. Читателю он по-прежнему доступен — `--data`,
- * `--json` и `explain` отвечают этим же проходом. */
+/* What does not go into the file. First, the list of skipped commits: it changes with the report's own commit (one
+ * with nothing to say lands in the list), and the file would stop being a **fixed point** — a rebuild after its own
+ * commit would yield different bytes and the hook would commit the report forever. The page has no use for the list
+ * at all: it does not show it. It stays available to the reader — `--data`, `--json` and `explain` answer from the
+ * same run. */
 const NOT_IN_FILE = ['skipped'];
 
 export function pagePayload(data) {
@@ -100,10 +104,8 @@ export function pagePayload(data) {
   return out;
 }
 
-/* Страница отчёта — один файл: данные лежат в нём же, скрипт вклеен, внешних
- * ссылок нет. Поэтому она открывается двойным щелчком и работает без сети.
- * `<` в данных экранируется: иначе подпись коммита или путь закрыли бы тег
- * раньше времени (в JSON такой экранированный символ читается как обычный). */
+/* The report's page is one file: the data lies in it, the script is pasted in, there are no external references. Hence
+ * it opens with a double click and works without a network. */
 export function pageHtml(data, cfg) {
   const loc = LOCALES[cfg.locale];
   return '<!doctype html>\n<html lang="' + esc(loc.html) + '">\n<head>\n<meta charset="utf-8">\n'
@@ -122,9 +124,8 @@ export function pageHtml(data, cfg) {
     + '<script>\n' + pageScript() + '</script>\n</body>\n</html>\n';
 }
 
-/* JSON внутри страницы: `<` экранируется, иначе подпись коммита или путь закрыли
- * бы тег раньше времени (в JSON такой экранированный символ читается как самый
- * обычный). */
+/* JSON inside the page: `<` is escaped, or a commit's subject or a path would close the tag early (inside a JSON
+ * string such an escaped character reads as a most ordinary one). */
 function jsonInHtml(value) {
   return JSON.stringify(value).replace(/</g, '\\u003c');
 }

package/src/page/dom.js

@@ -6,9 +6,8 @@ export function appEl(tag, cls, text) {
   return el;
 }
 
-/* Переключатель — метка вокруг поля ввода: цель нажатия одна, поэтому по нему
- * попадают и мышь, и клавиатура (`Space` на поле ввода), и вспомогательные
- * технологии. Подпись видимая, подробности — во всплывающей строке. */
+/* A switch is a label around an input: one click target, which is why a mouse, the keyboard (`Space` on the input)
+ * and assistive technology all reach it. The label is visible, the details live in the tooltip. */
 export function appBox(label, title, checked, onChange, cls) {
   const box = appEl('label', 'box' + (cls ? ' ' + cls : ''));
   const input = document.createElement('input');
@@ -21,16 +20,16 @@ export function appBox(label, title, checked, onChange, cls) {
   return box;
 }
 
-/* Галочка, которую нечем переключить: место в дереве есть, а включать нечего —
- * файла нет в колонках, отчёт его не измеряет. Она снята и недоступна: так строка
- * выглядит как все прочие (глаз сравнивает одно с одним), но видно, что это не
- * «выключено читателем», а «не измеряется». Причина — во всплывающей строке. */
+/* A checkbox with nothing to switch: the place in the tree exists while there is nothing to switch on — the file is
+ * not among the columns and the report does not measure it. The checkbox is off and unavailable: that way the row
+ * looks like every other one (the eye compares like with like) while showing that this is not "switched off by the
+ * reader" but "not measured". The reason lives in the tooltip. */
 export function appOffBox(label, title, cls) {
   const box = appBox(label, title, false, null, cls);
   box.classList.add('plain');
   box.querySelector('input').disabled = true;
-  /* Подсказка — на всей строке, а не только на поле: у недоступного поля браузер её
-   * не показывает, а причина читателю нужна именно здесь. */
+  /* The tooltip goes on the whole row rather than the input alone: a browser shows none for a disabled input, while
+   * the reader needs the reason right here. */
   box.title = title;
   return box;
 }

package/src/page/panel.js

@@ -1,52 +1,53 @@
 import { appEl, appBox, appOffBox } from './dom.js';
 import { appData, appUi, appView, appFileAt, appFoldSet, appMeasured } from './state.js';
 
-/* Галочку файла ставит только файл: и категория, и папка в дереве — способы
- * переставить те же галочки сразу группой, а своего состояния у них нет. Иначе
- * одно и то же решение жило бы в двух местах и расходилось. */
+/* Only a file sets a file's checkbox: both a category and a folder in the tree are ways to set the same checkboxes as
+ * a group and keep no state of their own. Otherwise one and the same decision would live in two places and drift
+ * apart. */
 function appFileBox(i) {
   const f = appData.files[i];
-  const where = appFileAt(i) + (f.path === null ? ' (нет на HEAD)' : '');
-  return appBox(f.label, where + ' · категория: '
-    + (f.categoryBy === 'config' ? 'из настроек' : 'по расширению'), appView.files[i], (e) => {
+  const where = appFileAt(i) + (f.path === null ? appUi.notOnHead : '');
+  return appBox(f.label, where + appUi.category
+    + (f.categoryBy === 'config' ? appUi.categoryFromConfig : appUi.categoryByExtension),
+  appView.files[i], (e) => {
     appView.files[i] = e.target.checked;
     appRender();
   });
 }
 
-/* Файл, которого в отчёте нет: он стоит в дереве на своём месте, но галочка у
- * него снята и недоступна — чисел для него не измеряли, и переключать нечего.
- * Причину читатель видит во всплывающей строке, а не догадывается по виду. */
+/* A file that is not in the report: it stands in its place in the tree with its checkbox off and unavailable — no
+ * numbers were measured for it, so there is nothing to switch. The reader sees the reason in the tooltip rather than
+ * guessing it from the look. */
 function appUnmeasuredBox(entry) {
   return appOffBox(entry.path.split('/').pop(), entry.path + ' · '
     + (entry.why === 'rule' ? appUi.notMeasuredRule : appUi.notMeasuredChoice));
 }
 
-/* Все измеряемые файлы поддерева — то, чем управляет переключатель папки: файл
- * вне отчёта переключать нечего. */
+/* Every measured file of a subtree — what a folder's switch controls: a file outside the report has nothing to
+ * switch. */
 function appIndexes(node) {
   const out = node.files.slice();
   node.dirs.forEach((sub) => { out.push(...appIndexes(sub)); });
   return out;
 }
 
-/* Сколько файлов в поддереве — вместе с теми, что в отчёт не попали. */
+/* How many files a subtree holds — including the ones that made it into no report. */
 function appCount(node) {
   let n = node.files.length + node.others.length;
   node.dirs.forEach((sub) => { n += appCount(sub); });
   return n;
 }
 
-/* Узел дерева: измеряемые файлы (колонки), прочие файлы проекта и подпапки. */
+/* A tree node: the measured files (columns), the project's other files and the subfolders. */
 function appNode() {
   return { files: [], others: [], dirs: new Map() };
 }
 
-/* Переключатель папки: его галочка ведёт за собой всё поддерево и показывает три
- * состояния — все файлы включены, часть, ни одного. Рядом число файлов; если в
- * папке есть и те, что вне отчёта, оно написано долей («2/5»): читателю важно, что
- * в папке пять файлов, а измеряются два. Папка без единого измеряемого файла
- * остаётся на месте, но её галочка снята и недоступна: включать в ней нечего. */
+/* A folder's switch: its checkbox carries the whole subtree with it and shows three states — every file on, some,
+ * none. The number of files stands next to it; when the folder also holds files outside the report, it is written as
+ * a fraction ("2/5"): what matters to the reader is that the folder holds five files while two are measured. A folder
+ * without a single measured file stays in place with its checkbox off and unavailable: there is nothing to switch on
+ * in it. */
 function appDirHead(name, sub) {
   const idx = appIndexes(sub);
   const total = appCount(sub);
@@ -68,18 +69,16 @@ function appDirHead(name, sub) {
   return head;
 }
 
-/* Знак папки — своя цель нажатия, отдельная от галочки: галочка отвечает за числа
- * (включает файлы поддерева), а знак — за то, сколько дерева видно. Одна цель на
- * два разных действия означала бы, что сложить папку можно только вместе с
- * включением её файлов. Знак нарисован спаном, а не кнопкой, потому что в строке
- * папки рядом уже стоит метка-галочка, а вложенная в метку кнопка поднимала бы её
- * же нажатие.
+/* The folder's sign is a click target of its own, separate from the checkbox: the checkbox answers for the numbers (it
+ * switches the subtree's files on), while the sign answers for how much of the tree is visible. One target for two
+ * different decisions would mean a folder can be folded only together with switching its files on. The sign is drawn
+ * as a span rather than a button and stands beside the label rather than inside it: a label is one click target, and a
+ * control nested in it would be reached as that same target.
  *
- * Клик по знаку ничего не пересобирает: поддерево лежит в разметке, а прячет его
- * класс на строке. Пересборка здесь была бы честной работой впустую — она считает
- * таблицу целиком (в этом проекте — сотни строк на полторы сотни колонок), то есть
- * платит за числа, которых складывание не меняет. Поэтому меняются только три
- * вещи, которые читатель и видит: класс, знак и запись в памяти. */
+ * A click on the sign rebuilds nothing: the subtree lies in the markup and a class on the row hides it. A rebuild here
+ * would be honest work for nothing — it counts the whole table (every row by every column) and so pays for numbers
+ * folding does not change. That is why only the three things the reader sees change: the class, the sign and the note
+ * in the memory. */
 function appFoldBox(name, path) {
   const folded = appView.folded[path] === true;
   const box = appEl('span', 'fold', folded ? '▸' : '▾');
@@ -95,8 +94,8 @@ function appFoldBox(name, path) {
   return box;
 }
 
-/* Листья уровня: измеряемые файлы и файлы вне отчёта — вперемешку и по алфавиту
- * имени, как в дереве файлов, а не отдельными списками. */
+/* The leaves of one level: measured files and files outside the report mixed together and sorted by name, the way a
+ * file tree reads, rather than as separate lists. */
 function appLeaves(node) {
   const items = node.files.map((i) => ({ name: appData.files[i].label, i: i, entry: null }));
   node.others.forEach((entry) => {
@@ -105,8 +104,8 @@ function appLeaves(node) {
   return items.sort((a, b) => (a.name < b.name ? -1 : (a.name > b.name ? 1 : 0)));
 }
 
-/* Строка папки: знак складывания, галочка с числом файлов и поддерево. Сложенная
- * папка отличается только классом — разметка одна и та же. */
+/* A folder row: the folding sign, the checkbox with the number of files and the subtree. A folded folder differs by
+ * its class alone — the markup stays the same. */
 function appDir(name, sub, prefix) {
   const here = prefix === '' ? name : prefix + '/' + name;
   const folded = appView.folded[here] === true;
@@ -117,18 +116,17 @@ function appDir(name, sub, prefix) {
   return li;
 }
 
-// Строка листа: измеряемый файл — с галочкой, файл вне отчёта — со снятой.
+// A leaf row: a measured file comes with a checkbox, a file outside the report with one switched off.
 function appLeaf(leaf) {
   const li = appEl('li');
   li.appendChild(leaf.entry === null ? appFileBox(leaf.i) : appUnmeasuredBox(leaf.entry));
   return li;
 }
 
-/* Узлы одного уровня: сперва всё, что в отчёте (папки по алфавиту, затем листья —
- * их порядок из `appLeaves`), потом то, чего в отчёте нет: папки без измеряемых
- * файлов и файлы вне колонок. Так решено не из вкуса: у всего вне отчёта галочка
- * снята и недоступна, и в конце списка оно не отвлекает от того, что в таблице,
- * а найти его по-прежнему можно — оно там же, где было. */
+/* The nodes of one level: first everything in the report (folders alphabetically, then the leaves in the order
+ * `appLeaves` gives), then what is not in it — folders without a measured file and files outside the columns. That is
+ * not a matter of taste: everything outside the report has its checkbox off and unavailable, so at the end of the list
+ * it does not distract from what is in the table, while it can still be found — in the same place where it was. */
 function appTreeList(node, prefix) {
   const list = appEl('ul', 'tree');
   const dirs = [...node.dirs.keys()].sort()
@@ -142,8 +140,8 @@ function appTreeList(node, prefix) {
   return list;
 }
 
-/* Место листа в дереве: путь делится по «/», промежуточные папки заводятся по
- * дороге. Одно место на измеряемые и прочие — иначе они разошлись бы папками. */
+/* A leaf's place in the tree: the path is split on "/" and the intermediate folders are created on the way. One place
+ * for measured and other files alike — otherwise they would drift apart in folders. */
 function appLeafAt(node, p, i, entry) {
   const parts = p.split('/');
   for (let d = 0; d < parts.length - 1; d++) {
@@ -154,11 +152,10 @@ function appLeafAt(node, p, i, entry) {
   else node.others.push(entry);
 }
 
-/* Дерево страницы — дерево проекта: узлы берутся из каталога (все пути, которые
- * видит git), поэтому в нём есть и файлы вне отчёта. Измеряемый лист — колонка, и
- * путь у него тот же, что в подписи файла; колонка, чьего файла на HEAD уже нет, в
- * каталог не попала (в индексе её нет) и стоит на месте по последнему известному
- * пути. */
+/* The page's tree is the project's tree: the nodes come from the catalogue (every path git sees), which is why it also
+ * holds files outside the report. A measured leaf is a column, and its path is the one in the file's caption; a column
+ * whose file is gone from HEAD never entered the catalogue (the index does not hold it) and stands in place by the last
+ * path known. */
 function appTree() {
   const root = appNode();
   appData.files.forEach((_f, i) => appLeafAt(root, appFileAt(i), i, null));
@@ -183,9 +180,9 @@ export function appPanel() {
     }, 'metric'));
   });
   metrics.appendChild(mrow);
-  /* Чем получено каждое число — видно, а не только во всплывающей строке: словарь
-   * токенов и способ сжатия выбираются настройками запуска, переключить их
-   * странице нечем, и читателю важно знать это, не наводя мышь. */
+  /* What produced each number is visible rather than hidden in a tooltip: the token dictionary and the way of
+   * compression are chosen by the settings of the run, the page has nothing to switch them with, and the reader needs
+   * to know this without pointing a mouse. */
   appData.metrics.forEach((m) => {
     metrics.appendChild(appEl('p', 'about', m.label + ' — ' + appUi.methodLabel + ' ' + m.method));
   });
@@ -193,8 +190,8 @@ export function appPanel() {
 
   const files = appEl('fieldset', 'files');
   files.appendChild(appEl('legend', null, appUi.files));
-  /* Строка категорий помечена классом: список файлов листается, и она остаётся на
-   * виду (липкость — в широкой раскладке, там панель и прокручивается). */
+  /* The row of categories is marked by a class: the file list scrolls, and the row stays in sight (its stickiness lives
+   * in the wide layout, which is where the panel scrolls). */
   const cats = appEl('div', 'row cats');
   appData.categories.forEach((cat) => {
     const idx = [];