@vernikr/size-report 2.4.0 → 2.6.0

package/src/page/table.js

@@ -1,51 +1,51 @@
-import { cellParts, commitParts, nowModel, rowModel, valueParts } from '../derived.js';
+import { cellParts, commitParts, deltaOf, nowModel, rowModel, valueParts } from '../derived.js';
 import { appEl } from './dom.js';
-import { appData, appUi, appView, appMetric } from './state.js';
-
-/* Приближённая клетка: пометка берётся из данных движка, а не выводится здесь из
- * пути файла, — правило точности живёт там же, где считаются числа. У клетки
- * файла это её собственное число, у итога — худшее из вошедших в него, иначе
- * сумма обещала бы точность, которой нет у слагаемых. Возвращается описание
- * метрики (её способ и идёт в подсказку клетки) либо ничего. */
-export function appApprox(where, files, key) {
-  const marks = appData.approx[key];
-  if (marks === undefined) return null;
-  const row = where === 'now' ? marks.now : marks.rows;
-  const base = where === 'now' ? 0 : where * appData.files.length;
-  for (let i = 0; i < files.length; i++) {
-    if (row.charAt(base + files[i]) === '1') return appMetric[key];
-  }
-  return null;
-}
-
-/* Класс клетки собирается в одном месте: и пометка приближения, и пропуск
- * («файла нет») — свойства самой клетки, а не её содержимого. */
-function appCellClass(first, miss, approx) {
-  return 'num' + (first ? ' g' : '') + (miss ? ' miss' : '') + (approx === null ? '' : ' approx');
-}
-
-// Разметка клетки строки-коммита: правила — в cellParts, здесь только узел.
-export function appCell(cell, first, approx) {
-  const parts = cellParts(cell.value, cell.delta, '−');
-  const td = appEl('td', appCellClass(first, parts.miss, approx));
-  if (approx !== null) td.title = appUi.approxCell + approx.method;
+import { appData, appUi, appView } from './state.js';
+
+/* The table is built once and then only shown and hidden. That rests on three things that do not depend on the
+ * reader: a cell's content and colour come from the pair (commit, file) and a metric (`cellParts`, `valueParts`),
+ * the order of the columns comes from the files alone, and only the visibility and the totals are the choice's.
+ * Hence nothing below builds a node after the first drawing — a click writes a class and a number.
+ *
+ * What makes this cheap is a cache of references to the nodes of every column (`appTable` returns it): reaching a
+ * cell through the markup costs several times what changing it does (measured: `tr.children[i]` 0.0254 ms against
+ * `classList.toggle` 0.0070 ms), and the first drawing creates every node anyway, so collecting them is free. The
+ * columns of the fixed layout — a `<col>` per column, carrying the counted width — are collected there too.
+ *
+ * The totals are the only numbers that move with the choice, and they are carried rather than recounted: a sum is
+ * linear, so a file switched off subtracts exactly its own numbers — the same integers the first drawing wrote.
+ */
+
+/* The cell's class: the metric's track (`m0`, `m1`, … — one class per metric, which is what hides a whole metric
+ * at once), the group it belongs to (every cell of a group, not the first one: the group's left border is carried
+ * by the first *enabled* metric, and the styling decides which that is), and the gap ("no such file"). */
+function appCellClass(mi, miss) {
+  return 'num g m' + mi + (miss ? ' miss' : '');
+}
+
+/* A cell filled where it stands: the totals are written again on every click, and a cell has to forget its own
+ * content first — a delta is a node of its own, so `textContent` alone would leave it behind. */
+function appFill(td, parts) {
+  td.textContent = '';
   if (parts.dir === null) td.textContent = parts.text;
   else td.appendChild(appEl('span', 'delta ' + parts.dir, parts.text));
   return td;
 }
 
-// Разметка клетки верхней строки: правила — в valueParts.
-export function appValueCell(value, first, approx) {
+// The markup of a commit row's cell: the rules live in cellParts, only the node is here.
+export function appCell(cell, mi) {
+  const parts = cellParts(cell.value, cell.delta, '−');
+  return appFill(appEl('td', appCellClass(mi, parts.miss)), parts);
+}
+
+// The markup of the top row's cell: the rules live in valueParts.
+export function appValueCell(value, mi) {
   const parts = valueParts(value);
-  const td = appEl('td', appCellClass(first, parts.miss, approx));
-  if (approx !== null) td.title = appUi.approxCell + approx.method;
-  td.textContent = parts.text;
-  return td;
+  return appFill(appEl('td', appCellClass(mi, parts.miss)), parts);
 }
 
-/* Подпись коммита — той же разметкой, что в статической таблице: дата, тема,
- * метка раздела журнала. Ширину колонки и обрезку длинной темы задаёт общая часть
- * оформления, поэтому колонка не прыгает при переключении файлов. */
+/* A commit's caption: the date, the subject, the journal section's mark. The column's width and the clipping of a long
+ * subject come from the shared part of the styling, which is why the column does not jump when files are switched. */
 export function appCommit(row) {
   const parts = commitParts(row, appData.report.showSha, row.href);
   const name = parts.href ? appEl('a', 'subj', parts.subject) : appEl('span', 'subj', parts.subject);
@@ -63,15 +63,9 @@ export function appCommit(row) {
   return th;
 }
 
-export function appSubHead(metrics) {
-  const tr = appEl('tr');
-  metrics.forEach((m, mi) => tr.appendChild(appEl('th', mi === 0 ? 'g' : '', m.label)));
-  return tr;
-}
-
-/* Состояния пустоты: когда чисел не будет вовсе, страница говорит об этом словами,
- * а не сеткой без колонок. Файлы можно выключить все — тогда остаётся общий объём,
- * и подсказка объясняет, почему колонок нет. */
+/* The empty states: when there will be no numbers at all, the page says so in words rather than showing a grid without
+ * columns. Every file can be switched off — then the total volume remains, and the note explains why there are no
+ * columns. The table itself stands there either way: this is about what is shown, not about what exists. */
 export function appState(metricsCount, filesCount) {
   const state = document.getElementById('state');
   const text = metricsCount === 0 ? appUi.empty : (filesCount === 0 ? appUi.noFiles : '');
@@ -80,26 +74,44 @@ export function appState(metricsCount, filesCount) {
   document.getElementById('shell').hidden = metricsCount === 0;
 }
 
-/* Шапка: строка групп (итог и файлы) и строка метрик под ней. Метрики повторяются
- * на каждый файл, поэтому подшапка собирается один раз, а дальше её узлы
- * переезжают в следующие — копий разметки не заводится. */
-export function appHead(shown, files, metrics) {
+/* The order of the columns: the files 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, and it depends on the files rather than on the choice: that is what lets a column be hidden
+ * without moving the others. */
+export function appOrder() {
+  const files = [];
+  appData.files.forEach((_f, i) => files.push(i));
+  files.sort((a, b) => (appData.last[a] === true ? 0 : 1) - (appData.last[b] === true ? 0 : 1));
+  return files;
+}
+
+/* The header: a row of groups (the total and the files) and a row of metrics under it — every metric of every file,
+ * because nothing here knows the choice. The headings whose `colSpan` follows the number of enabled metrics and the
+ * headings of each file's column are collected in the cache: they are the nodes a click has to touch. */
+export function appHead(files, metrics, cache) {
   const head = appEl('tr');
   const commit = appEl('th', 'c-commit', appUi.commit);
   commit.rowSpan = 2;
   head.appendChild(commit);
-  const total = appEl('th', 'g', appUi.total);
-  total.colSpan = metrics.length;
-  head.appendChild(total);
-  files.forEach((i) => {
-    const th = appEl('th', 'g', appData.files[i].label);
+  const subs = appEl('tr');
+  const group = (label, i) => {
+    const th = appEl('th', 'gh', label);
     th.colSpan = metrics.length;
     head.appendChild(th);
-  });
-  const subs = appSubHead(shown);
-  files.forEach(() => {
-    const more = appSubHead(shown);
-    while (more.firstChild) subs.appendChild(more.firstChild);
+    cache.spans.push(th);
+    /* The group's own heading belongs to the column: hiding a file has to take its caption with it, or the header
+     * would keep a name over numbers that are gone. */
+    if (i !== null) cache.cols[i].push(th);
+    metrics.forEach((_key, mi) => {
+      const cell = appEl('th', 'g m' + mi, appData.metrics[mi].label);
+      subs.appendChild(cell);
+      if (i !== null) cache.cols[i].push(cell);
+    });
+  };
+  group(appUi.total, null);
+  files.forEach((i) => {
+    cache.cols[i] = [];
+    group(appData.files[i].label, i);
   });
   const thead = appEl('thead');
   thead.appendChild(head);
@@ -107,39 +119,211 @@ export function appHead(shown, files, metrics) {
   return thead;
 }
 
-/* Строка-коммит: подпись и числа. Дельты считает общий расчёт (`rowModel`) — тот
- * же, что считает статическую таблицу; здесь только узлы. Пометка приближения —
- * своя у каждой клетки: у итога по всем вошедшим файлам, у файла — по нему самому. */
-export function appRow(r, metrics, files) {
+/* A text's breadth in `ch`, the unit a column is measured in: a digit is exactly one `ch` in this table's font
+ * (measured in Chrome: 8.67px against 8.67px), and a thin space is counted as a third of a digit — nothing else is
+ * discounted. Without that one fraction every number column would come out a fifth wider than the number in it (the
+ * grouping makes a text 21 % narrower than its characters, measured), which would give back more than the padding and
+ * the clipping of this step save. What is left over-measures — a letter is 0.84 of a `ch`, a slash 0.48 — and that is
+ * the safe side: a cell clips nothing, so a column a character short would show a number running over its neighbour. */
+function appBreadth(text) {
+  let wide = 0;
+  for (let i = 0; i < text.length; i++) wide += text[i] === '\u2009' ? 0.35 : 1;
+  return wide;
+}
+
+/* The widest text of every column, counted before a single node is made: the numbers of the commit rows — through
+ * `rowModel`, the very model the cells are drawn from, so a column cannot be sized for a number other than the one
+ * that will stand in it — the absolute sizes of the "now" row and the metric's own caption. */
+function appWidest(files, keys) {
+  const wide = files.map(() => keys.map(() => 0));
+  const total = keys.map(() => 0);
+  const put = (into, mi, breadth) => { if (breadth > into[mi]) into[mi] = breadth; };
+  const delta = (cell) => appBreadth(cellParts(cell.value, cell.delta, '−').text);
+  const value = (v) => appBreadth(valueParts(v).text);
+  appData.rows.forEach((row, r) => {
+    const model = rowModel(row.values, r === 0 ? null : appData.rows[r - 1].values, keys);
+    model.total.forEach((cell, mi) => put(total, mi, delta(cell)));
+    files.forEach((i) => model.files[i].forEach((cell, mi) => put(wide[i], mi, delta(cell))));
+  });
+  const now = nowModel(appData.now, keys);
+  now.total.forEach((v, mi) => put(total, mi, value(v)));
+  files.forEach((i) => now.files[i].forEach((v, mi) => put(wide[i], mi, value(v))));
+  keys.forEach((_key, mi) => {
+    const caption = appBreadth(appData.metrics[mi].label);
+    put(total, mi, caption);
+    wide.forEach((per) => put(per, mi, caption));
+  });
+  return { total: total, files: wide };
+}
+
+/* A group's heading — a file's name, the word over the total — is one line over the columns of that group
+ * (`white-space: nowrap` in the shared styling), so the group as a whole has to be wide enough for it, or the names of
+ * two neighbouring groups would run into one another. The caption is divided among the metrics of the group rather than
+ * weighed against their sum: every column carries at least its share, so the group can never come out narrower than the
+ * caption, while a column that is wider anyway keeps its own count. */
+function appGroupWide(per, label) {
+  const share = Math.ceil(appBreadth(label) / per.length);
+  return per.map((n) => Math.max(n, share));
+}
+
+/* The columns, before the rows: `table-layout: fixed` reads the first row of the table and takes the widths from there,
+ * so they are known while the table is built rather than measured by the browser over every cell of it. A column
+ * carries the metric's class (`m0`, `m1`, …) — which is what hides a whole metric at once — and its counted width in
+ * `ch`; the styling adds the padding and the border to it (`#grid col`), because a count and a drawing are one sum
+ * rather than two. The columns of a file are collected where its cells are, so one switch writes one class over both. */
+function appCols(files, wide, cache) {
+  const group = appEl('colgroup');
+  const add = (n, mi) => {
+    const col = appEl('col', 'm' + mi);
+    col.style.setProperty('--ch', n + 'ch');
+    group.appendChild(col);
+    return col;
+  };
+  group.appendChild(appEl('col', 'c-commit'));
+  appGroupWide(wide.total, appUi.total).forEach(add);
+  files.forEach((i) => appGroupWide(wide.files[i], appData.files[i].label)
+    .forEach((n, mi) => { cache.cols[i].push(add(n, mi)); }));
+  return group;
+}
+
+/* A file's share of a row: one cell per metric, in the order of the table's columns, and each is put into its
+ * column's cache while it is made. The maker is what tells a commit's delta from an absolute size at HEAD — the walk
+ * over the files is one, and there is no second one to drift away. */
+function appRowCells(tr, model, files, cache, make) {
+  files.forEach((i) => {
+    model.files[i].forEach((value, mi) => {
+      const td = make(value, mi);
+      cache.cols[i].push(td);
+      tr.appendChild(td);
+    });
+  });
+}
+
+/* A commit row: the caption and the numbers. The deltas come from the shared calculation (`rowModel`) rather than
+ * from here — two ways to count one row would be two answers. The model is taken whole (every file) because the
+ * table holds every column, and the column order of the table is applied by taking the model by the file's own
+ * index: the model lists the files the way the data does, not the way the columns stand. */
+export function appRow(r, files, metrics, cache) {
   const row = appData.rows[r];
   const prev = r === 0 ? null : appData.rows[r - 1];
-  const model = rowModel(row.values, prev === null ? null : prev.values, metrics, appView.files);
+  const model = rowModel(row.values, prev === null ? null : prev.values, metrics);
   const tr = appEl('tr');
   tr.appendChild(appCommit(row));
   model.total.forEach((cell, mi) => {
-    tr.appendChild(appCell(cell, mi === 0, appApprox(r, files, metrics[mi])));
+    const td = appCell(cell, mi);
+    cache.sums[mi][r] = cell.value;
+    cache.cells[mi][r] = td;
+    tr.appendChild(td);
   });
-  model.files.forEach((cells, fi) => cells.forEach((cell, mi) => {
-    tr.appendChild(appCell(cell, mi === 0, appApprox(r, [files[fi]], metrics[mi])));
-  }));
+  appRowCells(tr, model, files, cache, appCell);
   return tr;
 }
 
-/* Тело: строки коммитов снизу вверх (свежие первыми) плюс верхняя строка «сейчас»
- * с абсолютными размерами на HEAD. Дельты под ней сходятся с ней, поэтому она и
- * стоит первой. */
-export function appBody(metrics, files) {
+/* The top row holds the absolute sizes at HEAD: an absolute number stands in the table once, and it is the one every
+ * delta below it adds up to. Its numbers are the state at HEAD rather than the last commit's cells, which is why the
+ * running sums take them from here instead of assuming they are the row above. */
+export function appNow(files, metrics, cache) {
+  const tr = appEl('tr', 'now');
+  tr.appendChild(appEl('th', 'c-commit', appUi.now));
+  const model = nowModel(appData.now, metrics);
+  const last = appData.rows.length;
+  model.total.forEach((v, mi) => {
+    const td = appValueCell(v, mi);
+    cache.sums[mi][last] = v;
+    cache.cells[mi][last] = td;
+    tr.appendChild(td);
+  });
+  appRowCells(tr, model, files, cache, appValueCell);
+  return tr;
+}
+
+/* The body: the commit rows from the newest down, plus the "now" row with the absolute sizes at HEAD. The deltas
+ * under it add up to it, which is why it stands first. */
+export function appBody(files, metrics, cache) {
   const body = appEl('tbody');
-  for (let r = appData.rows.length - 1; r >= 0; r--) body.appendChild(appRow(r, metrics, files));
-
-  const now = appEl('tr', 'now');
-  now.appendChild(appEl('th', 'c-commit', appUi.now));
-  const nowCells = nowModel(appData.now, metrics, appView.files);
-  nowCells.total.forEach((v, mi) => now.appendChild(appValueCell(v, mi === 0,
-    appApprox('now', files, metrics[mi]))));
-  nowCells.files.forEach((cells, fi) => cells.forEach((v, mi) => {
-    now.appendChild(appValueCell(v, mi === 0, appApprox('now', [files[fi]], metrics[mi])));
-  }));
-  body.insertBefore(now, body.firstChild);
+  for (let r = appData.rows.length - 1; r >= 0; r--) body.appendChild(appRow(r, files, metrics, cache));
+  body.insertBefore(appNow(files, metrics, cache), body.firstChild);
   return body;
 }
+
+/* The whole table, built once. What the cache holds is what the reader's choice works with: the nodes of each file's
+ * column — its cells, its headings and its `<col>` (`cols`), the group headings whose colSpan follows the enabled
+ * metrics (`spans`), the cells of the totals (`cells`), the running sums (`sums`) and those same sums with every
+ * column on (`all`) — the sums a view painted again starts from. */
+export function appTable(grid) {
+  const metrics = appData.metrics.map((m) => m.key);
+  const files = appOrder();
+  const cache = { grid: grid, keys: metrics, cols: [], spans: [], cells: [], sums: [], all: [] };
+  metrics.forEach(() => {
+    cache.cells.push([]);
+    cache.sums.push([]);
+  });
+  grid.textContent = '';
+  grid.appendChild(appHead(files, metrics, cache));
+  grid.appendChild(appBody(files, metrics, cache));
+  /* The columns stand before the rows rather than beside them: a `<colgroup>` is where the fixed layout reads its
+   * widths from, and it has to be in the markup before the browser settles on a layout — the drawing is one pass, not
+   * two. */
+  grid.insertBefore(appCols(files, appWidest(files, metrics), cache), grid.firstChild);
+  cache.all = cache.sums.map((row) => row.slice());
+  return cache;
+}
+
+/* A file's column shown or hidden: its cells and its headings together, one class per node and no new node. A hidden
+ * column keeps its place in the markup — the order of the columns is the files' business, not the choice's. */
+export function appColumn(cache, i, on) {
+  cache.cols[i].forEach((node) => node.classList.toggle('off', !on));
+}
+
+/* A file's share of the totals: switched off it takes exactly its own numbers out of the running sums, switched on
+ * it puts them back. Two rows per file are the whole of it — the numbers are the data's, and a sum of integers is
+ * exact in either direction. */
+export function appContribute(cache, i, on) {
+  const sign = on ? 1 : -1;
+  appData.rows.forEach((row, r) => {
+    const values = row.values[i];
+    if (values === null) return;
+    cache.keys.forEach((key, mi) => { cache.sums[mi][r] += sign * values[key]; });
+  });
+  const values = appData.now[i];
+  if (values === null) return;
+  const last = appData.rows.length;
+  cache.keys.forEach((key, mi) => { cache.sums[mi][last] += sign * values[key]; });
+}
+
+/* The totals written where they stand: a data row shows the change against the row below it, the "now" row the
+ * absolute size — the same rules the first drawing used (`cellParts`, `valueParts`), so the reader sees one kind of
+ * number and not two. */
+export function appTotals(cache) {
+  const last = appData.rows.length;
+  cache.cells.forEach((cells, mi) => {
+    cells.forEach((td, r) => {
+      if (r === last) { appFill(td, valueParts(cache.sums[mi][r])); return; }
+      appFill(td, cellParts(cache.sums[mi][r], deltaOf(cache.sums[mi][r], r === 0 ? null : cache.sums[mi][r - 1]), '−'));
+    });
+  });
+}
+
+/* The running sums of the whole view again: a link, a record from the memory and the first drawing change the choice
+ * as a whole rather than a column, so the sums start from the sums with every column on and take the switched-off
+ * ones out — one copy of the numbers instead of a recount. */
+export function appTotalsReset(cache) {
+  cache.sums = cache.all.map((row) => row.slice());
+  appData.files.forEach((_f, i) => { if (!appView.files[i]) appContribute(cache, i, false); });
+  appTotals(cache);
+}
+
+/* The metrics of the choice: a class on the table hides every cell of a metric at once, and the group headings follow
+ * how many are left — two things that change, instead of a pass over the metric's cells (measured: 2.20 ms and 265
+ * operations against 433 ms and 56 496 for walking them). `.m-none` is what the styling reads to drop the group's
+ * left border when there is nothing left to separate. */
+export function appMetrics(cache) {
+  let on = 0;
+  cache.keys.forEach((key, mi) => {
+    const visible = appView.metrics[key] === true;
+    if (visible) on++;
+    cache.grid.classList.toggle('m-off-' + mi, !visible);
+  });
+  cache.grid.classList.toggle('m-none', on === 0);
+  cache.spans.forEach((th) => { th.colSpan = on === 0 ? 1 : on; });
+}

package/src/parse-worker.js

@@ -1,18 +1,18 @@
 import vm from 'vm';
 import { workerData } from 'worker_threads';
 
-/* Рабочий поток разбора: компилирует текст и отвечает причиной (или её
- * отсутствием). Исполнения нет — `SourceTextModule` только разбирает текст,
- * поэтому ни `import`, ни код модуля не выполняются: файл проекта остаётся
- * чужим кодом, который никто не запускает.
+/* The parsing worker: it compiles the text and answers with a reason (or with the absence of
+ * one). Nothing is executed — `SourceTextModule` only parses the text, so neither `import`
+ * nor the code of the module runs: the file of the project stays foreign code that nobody
+ * launches.
  *
- * Флаги приходят от главного потока (`--experimental-vm-modules` — без него
- * `vm.SourceTextModule` не существует, `--no-warnings` — иначе предупреждение об
- * эксперименте ушло бы в вывод команды). Модуля может не быть: тогда ответ несёт
- * `available: false`, и главный поток возвращается к запуску `node --check`.
+ * The flags arrive from the main thread (`--experimental-vm-modules`, without which
+ * `vm.SourceTextModule` does not exist, and `--no-warnings` lest the experimental warning end
+ * up in the command's output). The module may be absent: then the answer carries
+ * `available: false`, and the main thread falls back to launching `node --check`.
  *
- * Готовность ответа отмечается в общей памяти: главный поток ждёт её синхронно
- * (`Atomics.wait`), потому что измерение истории синхронное.
+ * Readiness is marked in shared memory: the main thread waits for it synchronously
+ * (`Atomics.wait`), because measuring the history is synchronous.
  */
 const { port, sig } = workerData;
 const available = typeof vm.SourceTextModule === 'function';

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 worded 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 });
   }