@vernikr/size-report 2.4.0 → 2.5.0

package/src/init.js

@@ -5,64 +5,63 @@ import { advicePath, cliCommand, refuseCause } from './refusal.js';
 import { writeFileEnsured } from './artifact.js';
 import { packageManager } from './project.js';
 
-/* Закрепление настроек файлом (`--init`): то, что проект вывел о себе сам
- * (`src/project.js`), записывается туда, где его встретит следующий запуск.
+/* Pinning the settings to a file (`--init`): what the project derived about itself
+ * (`src/project.js`) is written where the next run will meet it.
  *
- * Отдельным модулем от вывода профиля: тот смотрит на проект впервые и почти всё о
- * нём угадывает, а этот делает одну вещь — кладёт результат файлом и говорит, что
- * записал. Требование к себе одно и оно жёсткое: **закреплённое обязано проходить
- * ту же проверку, которой его встретит первый запуск** — иначе подсказка приводит
- * человека в новый тупик (BLOCKERS §N2, REFACTOR R-0.4).
+ * A module of its own, separate from deriving the profile: that one looks at the project for the first
+ * time and guesses about almost everything, while this one does a single thing — puts the result into
+ * a file and says what it wrote. It has one strict requirement of itself: **what was pinned has to
+ * pass the very check the first run will apply**, or the advice leads a person into a new dead end.
  */
 
-/* Что сказать после записи: тем же порядком, что и раньше, — что записано, чем
- * заменятся приближения и что делать дальше. Строки собираются списком, а не
- * печатаются по ходу: тогда «что сказано» читается целиком. */
+/* What to say after writing: what was written, what will replace the approximations, and what to do
+ * next. The lines are assembled into a list rather than printed as they come, so that "what was said"
+ * can be read as a whole. */
 function draftLines(root, target, cfg) {
   const hasPkg = fs.existsSync(path.join(root, 'package.json'));
   const manager = packageManager(root);
   return [
-    '✓ настройки выведены из проекта и закреплены: ' + path.relative(root, target),
-    '  колонок: ' + cfg.columns.length + ' (' + cfg.columns.map((c) => c.label).slice(0, 6).join(', ')
+    '✓ settings derived from the project and pinned: ' + path.relative(root, target),
+    '  columns: ' + cfg.columns.length + ' (' + cfg.columns.map((c) => c.label).slice(0, 6).join(', ')
       + (cfg.columns.length > 6 ? ', …' : '') + ')',
-    '  исключено путей: ' + cfg.skip.length + ' (сам отчёт, замки зависимостей, карты, собранное)',
-    '  метрика min: настоящее сжатие (esbuild); без него — честное упрощение и код 4',
-    '  метрика tok: словарь o200k_base (gpt-tokenizer); без него — оценка по длине и код 4',
-    '  журнал: ' + (cfg.journal === null ? 'не найден — ссылки строк будут без разделов' : cfg.journal.path),
-    '  дальше: правьте колонки и метрики — какие файлы важны, знает только проект',
+    '  paths skipped: ' + cfg.skip.length + ' (the report itself, dependency locks, maps, build output)',
+    '  metric min: real compression (esbuild); without it — an honest simplification and code 4',
+    '  metric tok: the o200k_base dictionary (gpt-tokenizer); without it — an estimate by length and code 4',
+    '  journal: ' + (cfg.journal === null ? 'not found — row links will carry no sections' : cfg.journal.path),
+    '  next: edit the columns and the metrics — which files matter is known by the project alone',
     '          ' + (hasPkg
-      ? 'добавьте в package.json "sizes": "size --write" — тогда отчёт будет звать '
-        + manager + ' run sizes (проверка — без --write)'
-      : 'запуск: ' + cfg.fixCommand + ' (проверка — без --write)'),
-    '          ' + (hasPkg ? 'добавьте ' + manager + ' run test:sizes в CI' : 'добавьте проверку в CI')
-      + '; проверка — команда пакета, своих файлов в проект она не приносит'
+      ? 'add "sizes": "size --write" to package.json — then the report will be built by '
+        + manager + ' run sizes (the check — without --write)'
+      : 'run: ' + cfg.fixCommand + ' (the check — without --write)'),
+    '          ' + (hasPkg ? 'add ' + manager + ' run test:sizes to CI' : 'add the check to CI')
+      + '; the check is the package\'s command, it brings no files of its own into the project'
   ];
 }
 
-/* Пустой профиль — не отказ, а примечание: работа сделана, а колонки за человека не
- * выберет никто. Поэтому «!», а не «✗»: знак и код выхода не имеют права говорить
- * разное (каталог отказов считает такие знаки отдельно). */
+/* An empty profile is a note rather than a refusal: the work was done, and nobody will pick the columns
+ * for the person. Hence "!", not the cross: a mark and an exit code must not say different things (the
+ * refusal catalogue counts a cross as a refusal and a note as not one). */
 function noteNoColumns(root, target, cfg) {
   if (cfg.columns.length > 0) return;
-  console.error('! в проекте не нашлось путей, которые можно взять колонками'
-    + ' (история пуста или в ней нет знакомых расширений): черновик записан без колонок'
-    + '\n  впишите их руками в ' + path.relative(root, target)
-    + ' — без колонок проверка настроек скажет «не задано ни одной колонки»');
+  console.error('! no paths in the project could be taken as columns'
+    + ' (the history is empty or holds no familiar extensions): the draft is written without columns'
+    + '\n  write them by hand into ' + path.relative(root, target)
+    + ' — without columns the settings check will say "no columns are given (columns)"');
 }
 
 export function initMode(root, file, force) {
   const target = file ? path.resolve(root, file) : path.join(root, CONFIG_NAME);
   if (fs.existsSync(target) && !force) {
-    // Совет называет тот же файл, о котором шла речь: `--init --force` без файла
-    // перезаписал бы черновиком умолчательное имя, а не тот файл, что человек звал.
+    // The advice names the very file in question: `--init --force` without a file would overwrite the
+    // default name with a draft rather than the file the person named.
     const name = file === undefined || file === null ? CONFIG_NAME : advicePath(file);
-    refuseCause('конфиг уже есть', 'конфиг уже есть: ' + target
-      + '\n  починка: правьте его или перезапишите черновиком: ' + cliCommand('--init ' + name + ' --force'));
+    refuseCause('config already exists', 'config already exists: ' + target
+      + '\n  fix: edit it or overwrite it with a draft: ' + cliCommand('--init ' + name + ' --force'));
   }
-  // Закреплённое — то же, чем проект работает без файла (вывод из проекта поверх
-  // умолчаний), и оно же обязано проходить ту же проверку, которой его встретит
-  // запуск: путь в тексте отказа — тот файл, куда оно легло. «Выведено» и «путь
-  // отказа» в файл не пишутся: это свойства не настроек, а того, откуда они взялись.
+  // What is pinned is the very thing the project runs on without a file (the project's derivation on
+  // top of the defaults), and it has to pass the same check the run will apply: the path in a refusal
+  // text is the file it landed in. "Derived" and that path are not written to the file: they are
+  // properties of where the settings came from rather than of the settings.
   const cfg = derivedProfile(root);
   if (cfg.columns.length > 0) validateConfig(Object.assign({}, cfg, { path: target }));
   const written = Object.assign({}, cfg);

package/src/journal.js

@@ -1,9 +1,9 @@
-/* Журнал и ссылки: к какому разделу относится коммит и куда ведёт его описание.
- * Работает на тексте, а не на git: разделы ищутся в уже прочитанном файле. */
+/* The journal and links: which section a commit belongs to and where its description leads.
+ * It works on text rather than on git: sections are searched for in an already read file. */
 
-/* Журнал (WORKLOG/CHANGELOG/…): раздел, к которому относится коммит. Формат
- * заголовков задаётся регуляркой в конфиге; именованные группы `id` (короткий
- * номер для `§N`) и `title` необязательны — без них номер берётся первым словом. */
+/* A journal (WORKLOG/CHANGELOG/…): the section a commit belongs to. The heading format comes
+ * from a regular expression in the settings; the named groups `id` (the short number used by
+ * `§N`) and `title` are optional — without them the number is the first word. */
 export function parseSections(text, pattern) {
   const re = new RegExp(pattern);
   const list = [];
@@ -23,9 +23,11 @@ export function parseSections(text, pattern) {
   return list;
 }
 
-/* Раздел, к которому относится коммит: сначала вновь заведённый, иначе —
- * последний из отредактированных (журналы ведутся по возрастанию, так что правка
- * почти всегда касается хвоста). */
+/* The section a commit belongs to: a newly opened one first, otherwise the last of the edited
+ * ones in document order. Taking the last assumes a journal written in ascending order, as this
+ * tool's own defaults expect; the "newly added" case holds for any order, while in a journal
+ * written newest-first (CHANGELOG.md is one) the fallback would name the oldest edited section
+ * rather than the newest. */
 export function touchedSection(prevText, nowText, pattern) {
   const prev = new Map(parseSections(prevText, pattern).map((s) => [s.head, s.body]));
   const now = parseSections(nowText, pattern);
@@ -42,10 +44,10 @@ export function touchedSection(prevText, nowText, pattern) {
   return null;
 }
 
-/* Якорь — как у GitHub (github-slugger): пунктуация снимается целиком, каждый
- * пробел становится дефисом. Отсюда «13 — эфф» → «13--эфф» (два дефиса: тире
- * выброшено, пробелы остались каждый своим). Дефис, подчёркивание и буквы
- * (включая кириллицу) сохраняются, остальные пробельные символы — нет. */
+/* The anchor as GitHub makes it (github-slugger): punctuation is dropped entirely and every
+ * space becomes a hyphen. Hence "13 — eff" → "13--eff" (two hyphens: the dash is gone while both
+ * spaces stay). Hyphens, underscores and letters (Cyrillic included) survive; other whitespace
+ * does not. */
 export function anchor(head) {
   return head.toLowerCase().replace(/[^\p{L}\p{N} _-]/gu, '').replace(/ /g, '-');
 }
@@ -56,9 +58,9 @@ export function sectionLink(section, cfg) {
   return cfg.journal.url + '#' + anchor(what);
 }
 
-/* Ссылка строки: на раздел журнала, если раздел есть, иначе на сам коммит (шаблон
- * из настроек). Одно место для артефакта и для данных страницы: адрес раздела —
- * правило GitHub, и второе его воплощение разъехалось бы с первым. */
+/* The link of a row: to a journal section when there is one, otherwise to the commit itself (the
+ * template comes from the settings). One place for the artifact and for the data of the page: a
+ * section address follows GitHub's rule, and a second copy of it would drift from the first. */
 export function rowHref(section, sha, cfg) {
   if (section) return sectionLink(section, cfg);
   if (!cfg.links.commitUrl) return null;

package/src/locales.js

@@ -1,9 +1,7 @@
-/* Тексты отчёта: заголовки, подписи и служебные слова на языке проекта. Это
- * словарь, а не рендер: механика таблицы от языка не зависит. */
-
-/* Тексты артефакта: колонка, метрики и служебные слова. Механика (заголовки
- * таблицы, клетки, дельты) от локали не зависит, поэтому перевод — это словарь,
- * а не отдельный рендер. */
+/* Texts of the artifact and of the report page: headings, labels and service words, in the
+ * language of the project. A dictionary, not a renderer: the mechanics of the table (cells,
+ * deltas, headings) do not depend on the language, so translating a report means adding
+ * words here rather than writing a second renderer. */
 export const LOCALES = {
   ru: {
     html: 'ru',
@@ -12,29 +10,36 @@ export const LOCALES = {
     total: 'Общий объём',
     now: 'сейчас',
     categories: { code: 'Код', docs: 'Документация', chore: 'Служебные', assets: 'Ресурсы' },
-    /* Тексты страницы отчёта. Они лежат в самом файле отчёта (отдельным словарём,
-     * рядом с данными), поэтому меняются вместе с ним — и правка слова стоит
-     * пересборки отчёта, иначе файл разойдётся с историей. */
+    /* The page texts live inside the report file itself (a dictionary of their own, next to
+     * the data), so changing a word costs a rebuild of the report — otherwise the file
+     * drifts from the history. */
     page: {
       metrics: 'Метрики',
       files: 'Файлы',
       dir: 'все файлы папки {name} ({n})',
       dirNone: 'ни один файл папки {name} в отчёт не попал (в папке {n})',
-      /* Знак сложенной папки — своя цель нажатия: галочка отвечает за числа,
-       * знак — за то, сколько дерева видно. */
+      /* The fold mark is a click target of its own: the checkbox answers for the numbers,
+       * the mark for how much of the tree is visible. */
       foldClose: 'свернуть папку {name}',
       foldOpen: 'развернуть папку {name}',
-      /* Причина — у листа: в дереве он подписью, а не галочкой, и без этих слов
-       * читатель решил бы, что файл потерялся. */
+      /* The reason belongs to a leaf: in the tree it is a label rather than a checkbox,
+       * and without these words a reader would think the file was lost. */
       notMeasuredRule: 'не измеряется: такой файл колонкой быть не может'
         + ' (собранный, замок зависимостей, сам отчёт или слишком крупный)',
       notMeasuredChoice: 'не измеряется: в набор колонок отчёта не попал'
         + ' — набор задают настройки (columns)',
+      /* The tooltip of a measured file: where the file stands and how its category was decided.
+       * A file absent on HEAD is named by the path it came with, and a category comes either from
+       * the settings or from the extension — both are answers to the reader's "why so". */
+      notOnHead: ' (нет на HEAD)',
+      category: ' · категория: ',
+      categoryFromConfig: 'из настроек',
+      categoryByExtension: 'по расширению',
       all: 'все',
       sub: '{tool} {version} · {artifact}',
-      /* Слова точности: подпись метрики говорит про худшее в колонке, а клетки —
-       * про своё число. Одно слово на подпись и на подсказку клетки, чтобы не
-       * разошлось и не звучало по-разному. */
+      /* Words of precision: a metric label speaks about the worst in its column, a cell
+       * about its own number. One word serves both the label and the cell hint, so the two
+       * cannot drift or sound differently. */
       exact: 'точное число',
       approximate: 'приближение',
       approximateCell: 'приближённое число: ',
@@ -88,6 +93,10 @@ export const LOCALES = {
         + ' (built, a dependency lock, the report itself, or too large)',
       notMeasuredChoice: 'not measured: it is not in the report’s set of columns'
         + ' — that set comes from the settings (columns)',
+      notOnHead: ' (not on HEAD)',
+      category: ' · category: ',
+      categoryFromConfig: 'from the settings',
+      categoryByExtension: 'by extension',
       all: 'all',
       sub: '{tool} {version} · {artifact}',
       exact: 'an exact number',

package/src/metrics.js

@@ -4,18 +4,18 @@ import { EXACT_STRATEGIES, assertCompilable, byteLen, minifyForm, strategyFor }
 import { MINIFY_LOADERS, minifier, minifyWithEsbuild } from './minify.js';
 import { CHARS_PER_TOKEN, isBinary, tokenCount, tokenizer } from './tokens.js';
 
-/* Реестр метрик: что измеряется, нужен ли метрике текст и насколько честна цифра.
- * Отдельно от способов снятия балласта: метрика — это обещание про число, а не
- * способ его получить.
+/* The registry of metrics: what is measured, whether a metric needs the text, and how honest
+ * its number is. Separate from the ways of stripping ballast: a metric is a promise about a
+ * number rather than a way to obtain one.
  *
- * Описание метрики для читателя берётся не из полей реестра, а из `metricView`:
- * у одной и той же метрики оно зависит от настроек (`min` — это настоящее сжатие
- * или упрощение, `tok` — точный словарь или оценка), и разойтись двум ответам на
- * один вопрос негде. */
+ * The description a reader sees comes from `metricView` rather than from the registry fields:
+ * for one and the same metric it depends on the settings (`min` is either real compression or
+ * a simplification, `tok` either an exact dictionary or an estimate), and two answers to one
+ * question have nowhere to drift apart. */
 
-/* Способы получить метрику `min`: снятие балласта и настоящее сжатие. Механизм у
- * них разный, и обещание тоже, поэтому у каждого свой способ, своя честность и своё
- * примечание — и никто из них не выдаётся за другого. */
+/* The ways to obtain the `min` metric: stripping ballast and real compression. Their mechanism
+ * differs, and so does their promise, so each has its own method, its own honesty and its own
+ * note — and neither is passed off as the other. */
 export const MINIFY_ENGINES = ['strip', 'esbuild'];
 
 const STYLES = {
@@ -82,10 +82,10 @@ export const METRICS = {
       if (esbuildLoader(file, cfg) !== null) return byteLen(minifyWithEsbuild(text, file, rev));
       const min = minifyForm(text, file, cfg);
       const ext = path.extname(file).toLowerCase();
-      /* Гард стриппера стережёт упрощение, а не минификатор: минификатор разбирает
-       * файл сам и о своей неудаче говорит отказом (`src/minify.js`), а этот гард
-       * отвечает на вопрос, не выбросило ли наше снятие балласта чего-нибудь, кроме
-       * комментариев и отступов. */
+      /* The stripper's guard watches the simplification rather than the minifier: the minifier
+       * parses the file itself and reports its failure as a refusal (`src/minify.js`), while
+       * this guard answers whether our stripping threw away anything but comments and
+       * indentation. */
       if (strategyFor(file, cfg) === 'strip-js' && cfg.minify.guard.indexOf(ext) >= 0) {
         assertCompilable(min, rev, file, text);
       }
@@ -108,8 +108,8 @@ export const METRICS = {
   }
 };
 
-/* Описание метрики для читателя: `note` — что означает число, `method` — чем оно
- * получено, `accuracy` — точное оно или приближённое. */
+/* The description of a metric for a reader: `note` is what the number means, `method` how it
+ * was obtained, `accuracy` whether it is exact or approximate. */
 export function metricView(name, cfg) {
   const metric = METRICS[name];
   if (metric.view !== undefined) return metric.view(cfg);
@@ -121,12 +121,12 @@ export function metricView(name, cfg) {
   };
 }
 
-/* Подпись метрики `min`. Соглашение о честности: `accuracy` говорит про худшее в
- * колонке, а способ называет, где именно приближение, — поэтому один формат без
- * минификатора делает метрику приближённой целиком, а не прячется за «exact»
- * соседнего файла. Худшее берётся по тому же правилу, что и пометки клеток
- * (`pointExact`), а не по названию способа: отчёт, где нет ни одного
- * приближённого формата, точен и со снятым балластом. */
+/* The label of the `min` metric. The honesty convention: `accuracy` speaks about the worst in
+ * the column, while the method says where exactly the approximation is — so one format without
+ * a minifier makes the whole metric approximate instead of hiding behind the "exact" of a
+ * neighbouring file. The worst is taken by the same rule as the cell marks (`pointExact`)
+ * rather than by the name of the method: a report with no approximate format at all is exact
+ * even with the ballast stripped. */
 function minView(cfg) {
   const loc = cfg.locale;
   const rough = approximateFormats('min', cfg);
@@ -149,11 +149,11 @@ function minView(cfg) {
   };
 }
 
-/* Подпись метрики `tok`. Соглашение о честности то же, что у `min`: способ говорит,
- * каким словарём снято число (семейство и кодировка — часть счёта, а не подробность),
- * а `accuracy` — точное оно или приближённое. Приближённым оно становится в двух
- * случаях, и оба названы словами: форматы, для которых токены не считаются (у них
- * число идёт по байтам), и отсутствие словаря (тогда счёт идёт оценкой по длине). */
+/* The label of the `tok` metric. The honesty convention is the same as for `min`: the method
+ * says which dictionary produced the number (family and encoding are part of the count rather
+ * than a detail), and `accuracy` says whether it is exact or approximate. It turns approximate
+ * in two cases, both spelled out: formats for which tokens are not counted (their number runs
+ * by bytes) and a missing dictionary (then the count is an estimate by length). */
 function tokView(cfg) {
   const loc = cfg.locale;
   const settings = cfg.tokens;
@@ -179,24 +179,23 @@ function tokView(cfg) {
   };
 }
 
-/* Точное ли число у конкретной клетки — одно правило и для подписи метрики, и для
- * пометки клетки. Поэтому подпись не может разойтись с клетками, а список
- * приближённых форматов считается здесь же, по тому же правилу.
+/* Whether a particular cell holds an exact number — one rule for both the metric label and the
+ * cell mark. That is why the label cannot drift from the cells, and why the list of
+ * approximate formats is computed here, by the same rule.
  *
- * `min` точен там, где файл действительно минифицируется: минификатором или
- * разбором формата, который короче уже не станет (JSON теряет только незначащие
- * пробелы — список точных стратегий ведёт `strip.js`, потому что стратегии живут
- * там). `tok` точен там, где есть словарь и формат текстовый: «токены» картинки
- * или шрифта — это её байты. `raw` и `gzip` точны всегда: это однозначные
- * величины. */
+ * `min` is exact where the file really is minified: by the minifier, or by parsing a format
+ * that cannot get any shorter (JSON loses only insignificant whitespace — the list of exact
+ * strategies is owned by `strip.js`, where the strategies live). `tok` is exact where a
+ * dictionary exists and the format is text: the "tokens" of a picture or a font are its bytes.
+ * `raw` and `gzip` are always exact: they are unambiguous quantities. */
 export function pointExact(name, file, cfg) {
   if (name === 'min') return minifiedForm(file, cfg);
   if (name === 'tok') return tokenizer(cfg.tokens).tool !== null && !isBinary(file);
   return true;
 }
 
-/* Форматы этого отчёта, которые будут измерены приближённо. Список выводится из
- * настроек и правила точности, а не пишется руками. */
+/* The formats of this report that will be measured approximately. The list is derived from the
+ * settings and the rule of exactness rather than written by hand. */
 function approximateFormats(name, cfg) {
   const exts = [];
   cfg.columns.forEach((col) => {
@@ -213,9 +212,10 @@ function minifiedForm(file, cfg) {
   return esbuildLoader(file, cfg) !== null || EXACT_STRATEGIES.indexOf(strategyFor(file, cfg)) >= 0;
 }
 
-/* Идёт ли файл в минификатор: сжатие запрошено, доступно и не отменено явным
- * выбором проекта — `minify.ext` старше движка и служит выходом, если расширение
- * соврало о содержимом. Ответ один на два вопроса: как считать и что обещать. */
+/* Whether the file goes to the minifier: compression is requested, available and not overridden
+ * by an explicit choice of the project — `minify.ext` outranks the engine and serves as the way
+ * out when an extension lied about its content. One answer serves two questions: how to count
+ * and what to promise. */
 function esbuildLoader(file, cfg) {
   if (minEngine(cfg) !== 'esbuild') return null;
   const ext = path.extname(file).toLowerCase();
@@ -223,46 +223,47 @@ function esbuildLoader(file, cfg) {
   return MINIFY_LOADERS[ext] === undefined ? null : MINIFY_LOADERS[ext];
 }
 
-/* Действующий способ: запрошенный может быть недоступен — тогда метрика отступает
- * к другому счёту, а отступление объявляется наружу (`sensorGaps`), иначе
- * приближение ушло бы как точное число. */
+/* The engine actually in force: the requested one may be unavailable, in which case the metric
+ * falls back to another count — and the fallback is announced (`sensorGaps`), or an
+ * approximation would travel as an exact number. */
 export function minEngine(cfg) {
   if (cfg.minify.engine !== 'esbuild') return 'strip';
   return minifier().tool === null ? 'strip' : 'esbuild';
 }
 
-/* Чего не хватает для того, что просили: причина и починка для человека, по одной
- * на датчик. Причина загрузчика уходит только сюда — в подписи метрики она была бы
- * машинной строкой (путём чужого `node_modules`), от которой вывод перестал бы
- * быть одинаковым на разных машинах, а в подписи отчёта — понятным. */
+/* What is missing for what was asked: a cause and a fix for a human, one per sensor. The
+ * loader's cause goes here and nowhere else — inside the metric label it would be a machine
+ * string (a path into someone else's `node_modules`) that would make the output differ between
+ * machines, while the label in the report has to stay readable. */
 export function sensorGaps(cfg) {
   const gaps = [];
   const minify = minifier();
   if (cfg.minify.engine === 'esbuild' && minify.tool === null) {
     gaps.push({
-      why: 'метрика «min» считает упрощением: минификатор недоступен — ' + minify.why,
-      fix: 'поставьте необязательные зависимости заново или задайте "minify": {"engine": "strip"}'
+      why: 'the metric "min" counts by simplification: the minifier is unavailable — ' + minify.why,
+      fix: 'install the optional dependencies again or set "minify": {"engine": "strip"}'
     });
   }
   if (cfg.metrics.indexOf('tok') >= 0) {
     const tokens = tokenizer(cfg.tokens);
     if (tokens.tool === null) {
       gaps.push({
-        why: 'метрика «tok» считает оценкой по длине: словаря нет — ' + tokens.why,
-        fix: 'поставьте необязательные зависимости заново или уберите "tok" из metrics'
+        why: 'the metric "tok" counts by an estimate of length: there is no dictionary — ' + tokens.why,
+        fix: 'install the optional dependencies again or remove "tok" from metrics'
       });
     }
   }
   return gaps;
 }
 
-/* Одно место, где решается, читать метрику из размера объекта или из текста:
- * метрика без текста на недогруженном блобе — ошибка, а не молчаливый ноль. */
+/* The one place that decides whether a metric is read from the object size or from the text:
+ * a text-based metric on an unloaded blob is an error rather than a silent zero. */
 export function measureBlob(name, blob, file, cfg, rev) {
   const metric = METRICS[name];
   if (metric.fromSize) return blob.size;
   if (blob.text === null) {
-    throw new Error('метрике «' + name + '» нужно содержимое ' + file + ' на ' + rev.slice(0, 7) + ', а оно не прочитано');
+    throw new Error('the metric "' + name + '" needs the content of ' + file + ' at '
+      + rev.slice(0, 7) + ', and it was not read');
   }
   return metric.measure(blob.text, file, cfg, rev);
 }

package/src/minify.js

@@ -2,18 +2,19 @@ import path from 'path';
 import { loadOptional } from './optional.js';
 import { refuseCause } from './refusal.js';
 
-/* Настоящий минификатор — необязательная зависимость (её устройство — в
- * `src/optional.js`), а здесь только то, что знает сам минификатор: какие форматы
- * он берёт и как считается отказ.
+/* The real minifier is an optional dependency (how that works: `src/optional.js`); what lives
+ * here is what only the minifier knows — which formats it takes and how a refusal is counted.
  *
- * Отказ минификатора (файл не разобрался) исключением быть обязан: расширение
- * соврало о содержимом, и упрощение вместо сжатия подменило бы число молча. */
+ * A minifier refusal (the file did not parse) has to be an exception: the extension lied about
+ * the content, and falling back to a simplification would silently substitute another
+ * number. */
 
-/* Расширения, за которые отвечает минификатор. Таблица — единственный источник
- * правды и для замера, и для подписи метрики («остальные форматы — приближение»),
- * поэтому разойтись им нечем. JSX и TSX сюда не входят: выход зависит от настройки
- * `jsx` проекта (`React.createElement` против `react/jsx-runtime`), и мерить чужое
- * решение о рантайме — не наше дело; такие файлы честно считаются упрощением. */
+/* The extensions the minifier answers for. This table is the single source of truth both for
+ * the measurement and for the metric label ("the other formats are an approximation"), so the
+ * two cannot drift apart. JSX and TSX are not here: the output depends on the project's `jsx`
+ * setting (`React.createElement` versus `react/jsx-runtime`), and measuring someone else's
+ * decision about a runtime is not this tool's business — such files are honestly counted as a
+ * simplification. */
 export const MINIFY_LOADERS = {
   '.js': 'js', '.mjs': 'js', '.cjs': 'js',
   '.ts': 'ts', '.mts': 'ts', '.cts': 'ts',
@@ -22,21 +23,21 @@ export const MINIFY_LOADERS = {
 
 let probed = null;
 
-/* Ответ разбора — один на процесс: пробовать загрузку на каждом файле значило бы
- * платить за неё тысячи раз, а от файла решение не зависит. */
+/* The probe answer is kept for the process: probing on every file would mean paying for it
+ * thousands of times, while the answer does not depend on the file. */
 export function minifier() {
   if (probed === null) probed = loadOptional('esbuild');
   return probed;
 }
 
-/* Сжатие одного текста. Настройки выхода закреплены, а не взяты по умолчанию:
- * `charset: utf8` — потому что измеряется файл проекта в UTF-8 (умолчание
- * экранировало бы не-ASCII и число вышло бы больше настоящего), `legalComments:
- * none` — потому что комментарии снимают и все прочие стратегии, и число должно
- * означать одну вещь, а не две. `sourcefile` нужен ради причины в отказе. */
+/* Compressing one text. The output settings are pinned rather than left at their defaults:
+ * `charset: utf8` because what is measured is a UTF-8 file of the project (the default would
+ * escape non-ASCII and the number would come out larger than the real one), `legalComments:
+ * none` because every other strategy drops comments too and the number has to mean one thing
+ * rather than two, and `sourcefile` for the reason inside a refusal. */
 export function minifyWithEsbuild(text, file, rev) {
   const { tool, why } = minifier();
-  if (tool === null) throw new Error('минификатор недоступен: ' + why);
+  if (tool === null) throw new Error('the minifier is unavailable: ' + why);
   const ext = path.extname(file).toLowerCase();
   try {
     return tool.transformSync(text, {
@@ -47,19 +48,19 @@ export function minifyWithEsbuild(text, file, rev) {
       sourcefile: file
     }).code;
   } catch (e) {
-    // Совет называет один выход — тот, который этой причине и отвечает: смена
-    // минификатора на `strip` уберёт причину, но передаст тот же файл гарду
-    // `minify.guard`, у которого разговор тот же («это не JavaScript»).
-    refuseCause('минификатор не разобрал', 'esbuild не разобрал ' + file + ' на '
+    // The advice names the one way out that answers this very cause: switching the minifier to
+    // `strip` removes the cause but hands the same file to the `minify.guard` check, whose
+    // verdict would be the same ("this is not JavaScript").
+    refuseCause('minifier did not parse', 'esbuild did not parse ' + file + ' at '
       + rev.slice(0, 7) + ': ' + cause(e.message)
-      + '\n  починка: расширение соврало о содержимом или минификатор старше синтаксиса;'
-      + ' задайте этому расширению упрощение в minify.ext (например {"' + ext + '": "strip-lines"})');
+      + '\n  fix: the extension lied about its content or the minifier is older than the syntax;'
+      + ' give this extension a simplification in minify.ext (for example {"' + ext + '": "strip-lines"})');
   }
 }
 
-/* Причина у esbuild многострочная, и первая строка — «Transform failed with N
- * errors:»; сама причина стоит там, где начинается ошибка. Без неё отказ говорил
- * бы, что что-то не так, но не что именно. */
+/* The reason from esbuild spans several lines and its first line is "Transform failed with N
+ * errors:"; the cause itself stands where the error starts. Without it a refusal would say
+ * that something is wrong without saying what. */
 function cause(text) {
   const lines = String(text).split('\n');
   const at = lines.findIndex((line) => line.indexOf('ERROR:') >= 0);