@vernikr/size-report 2.4.0 → 2.6.0

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 lose comments and
+ * indentation"), 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);

package/src/modes.js

@@ -13,28 +13,24 @@ import { artifact, rebuild } from './artifact.js';
 import { sensorGaps } from './metrics.js';
 import { totalsOf } from './derived.js';
 
-/* Режимы: что инструмент делает по запросу. Разбор аргументов — в `src/args.js`, а
- * сюда приходит готовый план: какой режим, какой ключ, что печатать. Здесь же их
- * общие мелочи (знак «!» о другом счёте, вердикт, размер словами) — один владелец
- * на все режимы, потому что один и тот же счёт и один и тот же знак не должны
- * разойтись между `--write`, `--data`, `--page` и `size check`.
- *
- * Что где: сборка и сверка отчёта (`--write`, проверка), данные контракта
- * (`--data`), полнота покрытия (`size check`), диагностика (`doctor`), хук и
- * объяснение пропущенной строки. Файл знает про все остальные модули сразу — это
- * его работа: связать их в одну команду.
+/* Modes: what the tool does on request. The arguments are parsed in `src/args.js`, and a
+ * ready plan arrives here — which mode, which flag, what to print. Their shared bits live
+ * here too (the "!" note about a different count, the verdict, a size in words), one owner
+ * for all modes, so that one count and one mark cannot diverge between `--write`, `--data`,
+ * `check` and the rest. Knowing every other module at once is this file's job: it ties them
+ * into one command.
  */
 
 function kmb(bytes) {
-  return Math.round(bytes / 1024) + ' КБ';
+  return Math.round(bytes / 1024) + ' KB';
 }
 
-/* Деградация — не ошибка, а факт отчёта: числа получены другим счётом (упрощение
- * вместо сжатия, оценка вместо точного счёта), потому что необязательной
- * зависимости нет. Факт печатается один раз на датчик и становится кодом 4 — иначе
- * приближение уезжало бы в CI как успех. */
+/* Degradation is a fact of the report, not an error: the numbers came from a different
+ * method (stripping instead of minification, an estimate instead of a counted one) because
+ * an optional dependency is missing. The fact is printed once per sensor and becomes code
+ * 4 — otherwise a different count would travel into CI as the requested one. */
 function note(gaps) {
-  gaps.forEach((gap) => console.error('! ' + gap.why + '\n  починка: ' + gap.fix));
+  gaps.forEach((gap) => console.error('! ' + gap.why + '\n  fix: ' + gap.fix));
   return gaps.length === 0 ? EXIT.OK : EXIT.SENSOR;
 }
 
@@ -42,12 +38,12 @@ function sensorNote(cfg) {
   return note(sensorGaps(cfg));
 }
 
-/* Вердикт режима вместе с заметками о датчиках: заметка печатается всегда — молчание
- * о другом счёте читается как точное число, и расхождение остаётся без причины, — а
- * код остаётся первым по важности. Нарушение старше приближения (тот же порядок, что
- * у `size check` и у `doctor`): код 4 говорит «числа честные, но другим счётом», а
- * когда таблица расходится, этого никто не проверял — расхождение может быть и
- * настоящей правкой мимо отчёта. */
+/* The mode's verdict together with the sensor notes: the note is printed always — silence
+ * about a different count reads as the requested one, and a disagreement would be left without
+ * a cause — while the code stays the more important one. A violation outranks a sensor note
+ * (the same order as in `check` and `doctor`): code 4 claims the difference is explained by the
+ * missing sensor, and when the table disagrees nobody checked that — the disagreement may be a
+ * real edit that went past the report. */
 function verdict(code, gaps) {
   const sensors = note(gaps);
   return code === EXIT.OK ? sensors : code;
@@ -56,7 +52,7 @@ function verdict(code, gaps) {
 export function check(cfg, want, root) {
   const out = path.join(root, cfg.output);
   if (!fs.existsSync(out)) {
-    console.error('✗ таблица размеров: нет файла ' + cfg.output + ' — соберите её: ' + cfg.fixCommand);
+    console.error('✗ size table: no file ' + cfg.output + ' — build it: ' + cfg.fixCommand);
     return 1;
   }
   const have = fs.readFileSync(out, 'utf8');
@@ -66,22 +62,22 @@ export function check(cfg, want, root) {
   const b = want.split('\n');
   let i = 0;
   while (i < a.length && i < b.length && a[i] === b[i]) i++;
-  console.error('✗ таблица размеров: ' + cfg.output + ' расходится с историей git (строка ' + (i + 1) + '):');
-  console.error('    в файле:    ' + (a[i] === undefined ? '<строк нет>' : a[i].trim().slice(0, 160)));
-  console.error('    по истории: ' + (b[i] === undefined ? '<строк нет>' : b[i].trim().slice(0, 160)));
+  console.error('✗ size table: ' + cfg.output + ' diverged from the git history (line ' + (i + 1) + '):');
+  console.error('    in the file:    ' + (a[i] === undefined ? '<no rows>' : a[i].trim().slice(0, 160)));
+  console.error('    by the history: ' + (b[i] === undefined ? '<no rows>' : b[i].trim().slice(0, 160)));
   const missing = [...want.matchAll(/id="c-([^"]+)"/g)].map((m) => m[1])
     .filter((id) => have.indexOf('id="c-' + id + '"') === -1);
   if (missing.length > 0) {
-    console.error('  строк нет в файле: ' + missing.length + ' (' + missing.slice(0, 5).join(', ')
+    console.error('  rows missing in the file: ' + missing.length + ' (' + missing.slice(0, 5).join(', ')
       + (missing.length > 5 ? ', …' : '') + ')');
   }
-  console.error('  починка: ' + cfg.fixCommand + ' — и закоммитить ' + cfg.output + ' отдельным коммитом.');
+  console.error('  fix: ' + cfg.fixCommand + ' — and commit ' + cfg.output + ' in a commit of its own.');
   return 1;
 }
 
-/* Путь, названный ключом (`--write <файл>`), — это настройка `output` этого
- * запуска: отчёт обязан называть себя тем путём, по которому лежит, иначе подпись в
- * нём указывала бы на чужое место. */
+/* A path named on the command line (`--write <file>`) is this run's `output` setting: the
+ * report has to name itself by the path it lies at, or the note inside it would point
+ * somewhere else. */
 function withOutput(cfg, root, file) {
   if (typeof file !== 'string') return cfg;
   return Object.assign({}, cfg, { output: path.relative(root, path.resolve(file)) });
@@ -90,10 +86,10 @@ function withOutput(cfg, root, file) {
 export function writeMode(cfg, root, file) {
   const out = rebuild(withOutput(cfg, root, file), root);
   const { rows, files, now, skipped } = out.data;
-  console.log('✓ ' + path.relative(root, out.file) + ': ' + rows.length + ' строк × ' + files.length + ' файлов, '
-    + kmb(byteLen(out.html)) + ' (пропущено без строки: ' + skipped.length + ' — '
+  console.log('✓ ' + path.relative(root, out.file) + ': ' + rows.length + ' rows × ' + files.length + ' files, '
+    + kmb(byteLen(out.html)) + ' (skipped without a row: ' + skipped.length + ' — '
     + skipped.join(', ') + ')');
-  console.log('  состояние на HEAD: ' + files.map((f, i) => f.label + ' '
+  console.log('  state at HEAD: ' + files.map((f, i) => f.label + ' '
     + (now[i] === null ? '—' : cfg.metrics.map((m) => now[i][m]).join('/'))).join(', '));
   return sensorNote(cfg);
 }
@@ -102,45 +98,45 @@ export function checkMode(cfg, root) {
   const out = artifact(cfg, root);
   const code = check(cfg, out.html, root);
   if (code === 0) {
-    console.log('✓ отчёт: ' + out.data.rows.length + ' коммитов × ' + out.data.files.length + ' файлов '
-      + 'совпадает с историей (' + cfg.output + ', ' + kmb(byteLen(out.html)) + ')');
+    console.log('✓ report: ' + out.data.rows.length + ' commits × ' + out.data.files.length + ' files '
+      + 'matches the history (' + cfg.output + ', ' + kmb(byteLen(out.html)) + ')');
   }
   return verdict(code, sensorGaps(cfg));
 }
 
-/* Ответ команды: `--json` — машинная форма того же ответа, а не второй ответ.
- * Одна на три команды, чтобы «кто печатает и в каком виде» не разошёлся между
- * ними: разойтись он может только здесь, а байты ответа — то, чем пользуется
- * агент. Текст берётся функцией: в машинной форме он не нужен вовсе. */
+/* A command's answer: `--json` is the machine form of the same answer, not a second one.
+ * Shared by three commands so that "who prints and in which shape" cannot diverge between
+ * them — that can only diverge here, and the bytes of the answer are what an agent consumes.
+ * The text comes as a function: the machine form does not need it at all. */
 function answer(rep, asJson, text) {
   if (asJson) process.stdout.write(JSON.stringify(rep, null, 2) + '\n');
   else console.log(text(rep));
   return rep;
 }
 
-/* Полнота покрытия (`size check`): настройки, история, пути, датчики. Не путать с
- * `checkMode` выше — тот про таблицу и историю («файл совпадает с тем, что
- * сосчитано»), а этот про то, что сосчитано **всё**: ни один путь истории не
- * прошёл мимо колонок. Разные вопросы, поэтому и разные команды: держать отчёт в
- * git не обязательно, а вот полноту терять нельзя — она той же проверкой и
- * заменяется. */
+/* Coverage (`size check`): settings, history, paths, sensors. Not to be confused with
+ * `checkMode` above, which asks whether the file matches what was computed; this one asks
+ * whether **everything** was computed — no path of the history went past the columns.
+ * Different questions, hence different commands: keeping the report in git is optional,
+ * losing completeness is not — and this command is what replaces that check. */
 export function coverageMode(cfg, root, configFile, asJson) {
   const rep = answer(coverage(cfg, root, configFile), asJson, coverageText);
   return verdict(rep.ok ? EXIT.OK : EXIT.VIOLATION, rep.sensors);
 }
 
-/* Диагностика одним ответом (`size doctor`): окружение, зависимости, настройки и
- * покрытие — сборкой из тех же кусков, что и остальные режимы. Код выхода — не
- * «что-то не так», а первый по важности (настройки → история → покрытие →
- * приближение): по нему агент ветвится, а текст читает человек. */
+/* Diagnostics in one answer (`size doctor`): environment, dependencies, settings and
+ * coverage, assembled from the same pieces as the other modes. The exit code is not
+ * "something is wrong" but the first by importance (settings → history → coverage →
+ * sensor): an agent branches on it, a human reads the text. */
 export function doctorMode(root, configFile, asJson) {
   return answer(doctor(root, configFile), asJson, doctorText).exit;
 }
 
-/* Хук: установка, снятие и то, что он зовёт сам. Ставится и снимается только
- * явной командой; `hook-run` зовётся хуком и всегда отвечает кодом 0 — коммит уже
- * сделан, и валить его нечем (устройство и причины — `src/hook.js`). Строка о
- * сделанном идёт в stderr: она часть вывода git, а не данных инструмента. */
+/* The hook: installing, removing, and the call the hook itself makes. Installing and
+ * removing happen by explicit command only; `hook-run` is called by the hook and always
+ * answers 0 — the commit is already made and there is nothing to fail it for (design and
+ * reasons: `src/hook.js`). What it did goes to stderr: it is part of git's output, not tool
+ * data. */
 export function hookMode(verb, root, configFile) {
   if (verb === 'hook-run') {
     const rep = hookRun(root, configFile);
@@ -152,17 +148,18 @@ export function hookMode(verb, root, configFile) {
   return rep.code;
 }
 
-/* Объяснение пропущенной строки (`size explain <коммит>`): ответ есть у любого
- * коммита, поэтому код выхода 0 и у «строка есть», и у «строки нет»; 2 — только
- * когда названного коммита в истории нет или префикс подходит нескольким. */
+/* Explaining a skipped row (`size explain <commit>`): any resolvable commit has an answer,
+ * so the exit code is 0 both when the row is there and when it is not; 2 belongs to a commit
+ * that cannot be resolved — an unknown name, an ambiguous prefix, or one outside the
+ * history. */
 export function explainMode(cfg, root, target, asJson) {
   answer(explainCommit(cfg, root, target), asJson, explainText);
   return EXIT.OK;
 }
 
-/* Данные контракта в stdout — для страницы и для агента: та же правда, что в
- * артефакте, но без вёрстки и без производных величин. Прежняя форма `--json`
- * остаётся нетронутой: она заморожена эталоном паритета (fixtures/parity). */
+/* Contract data on stdout — for the page and for an agent: the same truth as in the
+ * artifact, without markup and without derived numbers. The older `--json` form stays
+ * untouched: the parity fixture freezes it (`fixtures/parity`). */
 export function dataMode(cfg, root) {
   process.stdout.write(JSON.stringify(reportData(cfg, root), null, 2) + '\n');
   return sensorNote(cfg);

package/src/optional.js

@@ -1,22 +1,24 @@
 import { createRequire } from 'module';
 
-/* Необязательные зависимости: минификатор и токенизатор. Их отсутствие — не отказ,
- * а другой счёт (упрощение вместо сжатия, оценка вместо точного счёта), поэтому
- * загрузка у них общая и с одним устройством: ленивая, синхронная (`createRequire`
- * — замер синхронный проход, и `import()` сделал бы асинхронной всю цепочку ради
- * одного датчика) и без исключения наружу — недоступность возвращается ответом.
+/* Optional dependencies: the minifier and the tokenizer. Missing ones are not a refusal but a
+ * different count (a simplification instead of compression, an estimate instead of a counted
+ * one), so their loading is shared and shaped the same way: lazy, synchronous
+ * (`createRequire` — measuring is one synchronous pass, and `import()` would make the whole
+ * chain asynchronous for the sake of a single sensor) and without an exception escaping —
+ * unavailability comes back as an answer.
  *
- * Шов отсутствия — окружение `SIZE_REPORT_NO_OPTIONAL`: тем же путём идёт установка
- * без необязательных зависимостей и платформа, для которой пакета нет. Им же
- * проверяется, что инструмент работает и без них. */
+ * The seam of their absence is the `SIZE_REPORT_NO_OPTIONAL` environment variable: the same
+ * path serves an install without optional dependencies and a platform the package is not built
+ * for. It is also how the tests check that the tool works without them. */
 
 export const NO_OPTIONAL = 'SIZE_REPORT_NO_OPTIONAL';
 
-/* Версия берётся у самого пакета: число зависит от словаря и от алгоритма, поэтому
- * она попадает в способ, которым получено значение, а не остаётся в `node_modules`. */
+/* The version is read from the package itself: the number depends on the dictionary and on the
+ * algorithm, so it belongs in the method the value came from rather than staying inside
+ * `node_modules`. */
 export function loadOptional(spec) {
   if (process.env[NO_OPTIONAL]) {
-    return { tool: null, version: null, why: 'необязательные зависимости выключены (' + NO_OPTIONAL + ')' };
+    return { tool: null, version: null, why: 'the optional dependencies are switched off (' + NO_OPTIONAL + ')' };
   }
   const require = createRequire(import.meta.url);
   try {