@vernikr/size-report 2.3.0 → 2.5.0

package/src/strip/js.js

@@ -1,20 +1,20 @@
-/* Снятие комментариев и отступов — метрика «объём без балласта», а не
- * минификация: пробелы внутри строк и порядок токенов не трогаются (это позволит
- * сравнивать числа между языками и не зависит от чужого инструмента, которого в
- * проекте нет). Строки и шаблоны проходят насквозь, блочный комментарий
- * заменяется пробелом, чтобы `a` и `b` из `a` + блочный комментарий + `b` не
- * склеились в одно имя, перевод строки после `//` сохраняется — он разделяет
- * токены.
+/* Comments and indentation stripped — "volume without ballast" rather than minification:
+ * spaces inside strings and the order of tokens stay untouched, which keeps numbers
+ * comparable across languages and keeps this path free of any foreign tool (the real
+ * minifier is an optional dependency, and this is what remains without it). Strings and
+ * templates pass through whole, a block comment becomes a space — so that `a` and `b` around
+ * one do not merge into a single name — and the newline after `//` survives, because it
+ * separates tokens.
  *
- * Проход разложен по случаям: комментарий, регексп, строка и обычный символ.
- * Случай говорит, сколько он съел (`false` — не его), и все они делят одно
- * состояние прохода; состояния «по копии на случай» здесь не заводится, потому
- * что решение о регекспе зависит от всего, что уже выведено.
+ * The pass is split by case: comment, regex, string, ordinary character. A case reports how
+ * much it consumed (`false` — not its turn), and all of them share one pass state; a state
+ * per case is not kept because the decision about a regex depends on everything printed so
+ * far.
  */
 
-/* Состояние прохода: текст, место в нём и то, чем отличают регексп от деления, —
- * последний значимый символ вывода и хвост последнего слова (после `return` идёт
- * выражение, а не деление). */
+/* Pass state: the text, the position in it, and what tells a regex from a division — the last
+ * significant character printed and the tail of the last word (`return` is followed by an
+ * expression rather than by a division). */
 function scanOf(src) {
   return { src: src, out: '', i: 0, last: '', word: '' };
 }
@@ -22,15 +22,15 @@ function scanOf(src) {
 export function stripJs(src) {
   const s = scanOf(src);
   while (s.i < src.length) {
-    /* Комментарные пары проверяются до регекси: ни `/`, ни `*` не могут быть
-     * первым символом литерала регекспа, а вот `/*` в начале файла — обычное дело. */
+    /* Comment pairs are checked before regexes: neither `/` nor `*` can start a regex
+     * literal, while `/*` is an ordinary thing to meet. */
     if (skipLineComment(s) || skipBlockComment(s) || takeRegex(s) || takeString(s)) continue;
     putChar(s);
   }
   return s.out;
 }
 
-// Строчный комментарий: `//` съедается до перевода строки, сам перевод остаётся.
+// A line comment: `//` is eaten up to the newline, the newline itself stays.
 function skipLineComment(s) {
   if (s.src[s.i] !== '/' || s.src[s.i + 1] !== '/') return false;
   const nl = s.src.indexOf('\n', s.i);
@@ -38,7 +38,7 @@ function skipLineComment(s) {
   return true;
 }
 
-// Блочный комментарий — на пробел: он разделяет имена, но не занимает объём.
+// A block comment becomes a space: it separates names without taking up volume.
 function skipBlockComment(s) {
   if (s.src[s.i] !== '/' || s.src[s.i + 1] !== '*') return false;
   const end = s.src.indexOf('*/', s.i + 2);
@@ -47,10 +47,10 @@ function skipBlockComment(s) {
   return true;
 }
 
-/* Регексп начинается там, где ожидается операнд: после оператора, открывающей
- * скобки или ключевого слова. Признак грубый, но его хватает: без него
- * `replace(/\//g, …)` читалось бы как начало строчного комментария и резало
- * строку (проверено гардом компиляции). */
+/* A regex starts where an operand is expected: after an operator, an opening bracket or a
+ * keyword. The sign is crude, and it can afford to be: a regex this pass mistakes for code,
+ * or code it mistakes for a comment, does not compile — and that is exactly what the guard
+ * checks (`strip/guard.js`). */
 const REGEX_KEYWORDS = ['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'case', 'do', 'else', 'yield', 'await'];
 
 function regexAllowed(last, word) {
@@ -75,7 +75,7 @@ function endOfRegex(src, start) {
   while (i < src.length) {
     const ch = src[i];
     if (ch === '\\') { i += 2; continue; }
-    if (ch === '\n') return start + 1; // наткнулись на строку — значит, это был не регексп
+    if (ch === '\n') return start + 1; // a newline means this was not a regex after all
     if (ch === '[') inClass = true;
     else if (ch === ']') inClass = false;
     else if (ch === '/' && !inClass) return i + 1;
@@ -84,7 +84,7 @@ function endOfRegex(src, start) {
   return start + 1;
 }
 
-// Строка или шаблон — целиком, вместе со своим содержимым.
+// A string or a template passes through whole, its content included.
 function takeString(s) {
   const quote = s.src[s.i];
   if (quote !== '"' && quote !== "'" && quote !== '`') return false;
@@ -102,7 +102,7 @@ function endOfString(src, start, quote) {
     const ch = src[i];
     if (ch === '\\') { i += 2; continue; }
     if (ch === quote) return i + 1;
-    // В шаблоне `${…}` живёт выражение, а в нём — свои строки.
+    // A template holds an expression in `${…}`, and that expression has strings of its own.
     if (quote === '`' && ch === '$' && src[i + 1] === '{') { i = endOfTemplateExpr(src, i + 2); continue; }
     i++;
   }
@@ -123,8 +123,8 @@ function endOfTemplateExpr(src, start) {
   return src.length;
 }
 
-/* Обычный символ: он попадает в вывод, а состояние прохода запоминает по нему,
- * где может стоять регексп. */
+/* An ordinary character: it goes into the output, and the pass state remembers by it where a
+ * regex may stand. */
 function putChar(s) {
   const ch = s.src[s.i];
   s.out += ch;

package/src/strip.js

@@ -2,16 +2,13 @@ import path from 'path';
 import { stripJs } from './strip/js.js';
 import { compactJson, stripCss, stripHtml, stripLines } from './strip/forms.js';
 
-/* Снятие балласта: правило, какая форма текста к какому файлу применяется.
- * Только преобразование текста — ни истории, ни настроек этот модуль не знает.
+/* Stripping ballast: which form of text applies to which file. Only text transformation —
+ * the module knows no history and reads no settings, only the strategy it is handed. What
+ * binds the forms to a file lives here: the extension, the strategy, and which strategies
+ * count as exact.
  *
- * Разбор форм лежит рядом и по предметам: проход по JS (`strip/js.js`), формы
- * разметки, стилей, строк и JSON (`strip/forms.js`) и гард компиляции
- * (`strip/guard.js`). Здесь остаётся то, что связывает их с файлом: расширение,
- * стратегия и что считать точным числом.
- *
- * Имена форм наружу отдаются отсюда же: точка входа пакета берёт их по одному
- * адресу, и переезд разбора не должен быть виден тому, кто на них опирался. */
+ * The forms are re-exported from here, so that the package entry point has one address for
+ * them and a move inside the parsing stays invisible to whoever relied on them. */
 
 export { stripJs, stripCss, stripHtml, stripLines, compactJson };
 export { assertCompilable } from './strip/guard.js';
@@ -20,10 +17,10 @@ export function byteLen(text) {
   return Buffer.byteLength(text, 'utf8');
 }
 
-/* Стратегия по расширению. Незнакомое расширение получает снятие отступов и
- * пустых строк — безопасный минимум: снимать комментарии «на глаз» в синтаксисе,
- * которого генератор не знает (например, `#` в YAML или отступы в Python),
- * значило бы мерить уже другой файл. */
+/* The strategy for an extension. An unknown extension gets indentation and blank lines
+ * removed — the safe minimum: stripping comments by eye in a syntax the generator was never
+ * taught (`#` in YAML, indentation in Python) would measure a different file than the one on
+ * disk. */
 const MINIFY_BY_EXT = {
   '.js': 'strip-js', '.mjs': 'strip-js', '.cjs': 'strip-js',
   '.html': 'strip-html', '.htm': 'strip-html',
@@ -32,11 +29,11 @@ const MINIFY_BY_EXT = {
 };
 export const STRATEGIES = ['strip-js', 'strip-html', 'strip-css', 'json', 'strip-lines', 'none'];
 
-/* Стратегии, которые и есть минификация: JSON теряет только незначащие пробелы
- * (числа приводятся к кратчайшей записи), и короче его не сделает никто. Остальные
- * — упрощение: они снимают балласт, но не переименовывают и не перестраивают код,
- * и обещать за них точное число нельзя. Список ведёт тот модуль, который владеет
- * стратегиями; метрика по нему решает, точное у неё число или приближённое. */
+/* The strategies that are minification itself: JSON loses only insignificant whitespace
+ * (numbers take their shortest form) and nobody can make it shorter. The rest are a
+ * simplification — they drop ballast but neither rename nor restructure code, so no exact
+ * number can be promised for them. The list is owned here, next to the strategies, and the
+ * metric reads it to decide whether its number is exact or approximate. */
 export const EXACT_STRATEGIES = ['json'];
 
 export function strategyFor(file, cfg) {
@@ -44,8 +41,8 @@ export function strategyFor(file, cfg) {
   return (cfg.minify.ext && cfg.minify.ext[ext]) || MINIFY_BY_EXT[ext] || 'strip-lines';
 }
 
-/* Что делает стратегия — разбор формы принадлежит ей, а не списку здесь:
- * диспетчер только выбирает, кого позвать, и повторяет словарь стратегий. */
+/* What a strategy does belongs to the strategy rather than to this list: the dispatcher only
+ * picks whom to call, and repeats the strategy names because the parsing lives elsewhere. */
 export function minifyForm(text, file, cfg) {
   const how = strategyFor(file, cfg);
   if (how === 'none') return text;
@@ -54,5 +51,5 @@ export function minifyForm(text, file, cfg) {
   if (how === 'strip-css') return stripLines(stripCss(text));
   if (how === 'json') return compactJson(text);
   if (how === 'strip-lines') return stripLines(text);
-  throw new Error('неизвестная стратегия минификации «' + how + '» (есть: ' + STRATEGIES.join(', ') + ')');
+  throw new Error('unknown minification strategy "' + how + '" (have: ' + STRATEGIES.join(', ') + ')');
 }

package/src/table.css

@@ -1,35 +1,34 @@
-/* Гарнитура одна на всю таблицу; числа выравниваются по разрядам за счёт
- * tabular-nums, а не за счёт моноширинного шрифта. */
+/* One type face for the whole table; numbers line up by their digits thanks to tabular-nums rather than through a
+ * monospaced font. */
 table { border-collapse: collapse; font-variant-numeric: tabular-nums; }
 th, td { padding: 2px 7px; border-bottom: 1px solid rgba(127, 127, 127, .25); white-space: nowrap; }
-/* Шапка из двух строк: обе липкие, поэтому вторая сдвинута ровно на высоту первой
- * (line-height 20 + 2px нижней границы), иначе строки накладывались бы друг на друга. */
+/* A two-row header: both rows stick, so the second is offset by exactly the first one's height (line-height 20 plus the
+ * 2px bottom border), or the rows would overlap. */
 thead th { position: sticky; top: 0; z-index: 3; background: Canvas; text-align: center; line-height: 20px; padding: 0 7px; }
 thead tr:first-child th { border-bottom-width: 2px; }
 thead tr:last-child th { top: 22px; }
 .num { text-align: right; }
 .g { border-left: 1px solid rgba(127, 127, 127, .35); }
-/* Липкая левая колонка: фон непрозрачный (Canvas), иначе при скролле вправо под
- * клеткой были бы видны числа. Ярус выше соседних клеток (2) и ниже шапки (3);
- * угол шапки — выше всех, иначе группы колонок наползают на «Коммит». */
+/* The sticky left column: an opaque background (Canvas), or numbers would show through the cell when scrolling sideways. A
+ * tier above the neighbouring cells (2) and below the header (3); the header's corner is above them all, or the column groups
+ * would crawl over the commit column. */
 .c-commit { position: sticky; left: 0; z-index: 2; background: Canvas; text-align: left; font-weight: 400; }
 .c-commit a { color: inherit; }
 thead .c-commit { z-index: 6; }
-/* Ширину колонки задаёт этот блок. Без него содержимое ячейки выходило за её
- * границы и рисовалось поверх соседних чисел: у ячейки таблицы нет обрезки. */
+/* This block sets the column's width. Without it the cell's content went past its borders and was drawn over the neighbouring
+ * numbers: a table cell clips nothing. */
 .clip { display: flex; align-items: baseline; gap: 6px; width: 300px; }
 .when { flex: none; opacity: .7; }
 .subj { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; display: block; }
 .subj.plain { opacity: .7; }
 .sect { flex: none; opacity: .7; font-size: 11px; text-decoration: none; border-bottom: 1px dotted currentColor; }
-/* Рост зелёный, спад красный — по договорённости с заказчиком (рост — «больше
- * логики», а не тревога). */
+/* Growth green, fall red — by agreement with whoever asked for the report (growth is "more logic" rather than alarm). */
 .up { color: #1e8449; }
 .down { color: #c0392b; }
 .miss { opacity: .5; }
-/* Верхняя строка — текущие размеры: она же и объясняет, к чему относятся дельты. */
+/* The top row holds the current sizes: it is also what explains what the deltas refer to. */
 tr.now th, tr.now td { border-bottom: 2px solid rgba(127, 127, 127, .35); }
 tr.now .c-commit { font-weight: 600; }
-/* Подсветка строки — наложением, а не подменой фона: липкая колонка обязана
- * оставаться непрозрачной, иначе под ней при скролле видны числа. */
+/* A row's highlight is laid over rather than swapped in: the sticky column has to stay opaque, or numbers show through it
+ * when scrolling. */
 tbody tr:hover th, tbody tr:hover td { background-image: linear-gradient(rgba(127, 127, 127, .08), rgba(127, 127, 127, .08)); }

package/src/tokens.js

@@ -1,16 +1,16 @@
 import path from 'path';
 import { loadOptional } from './optional.js';
 
-/* Токенизатор — та же дисциплина, что у минификатора: необязательная зависимость с
- * ленивой загрузкой (устройство — в `src/optional.js`). Отличие одно: токенизатор
- * берёт любой текст, отказать ему не в чем, поэтому отсутствие зависимости — не
- * отказ, а другой счёт: оценка по длине, помеченная приближением в подписи метрики.
+/* The tokenizer follows the same discipline as the minifier: an optional dependency, loaded
+ * lazily (how that works: `src/optional.js`). One difference: the tokenizer takes any text and
+ * has nothing to refuse, so a missing dependency is not a refusal but a different count — an
+ * estimate by length, marked as an approximation in the metric label.
  *
- * Семейство — про модели, кодировка — про число: один и тот же файл считается
- * по-разному в `cl100k_base` и `o200k_base`, поэтому кодировка выбирается рядом с
- * семейством, а не подразумевается. Семейство тут одно, и это не недоделка: у
- * остальных нет словаря, который можно было бы назвать их собственным, — считать
- * чужим словарём и называть это семейством значило бы обещать то, чего нет. */
+ * The family is about models, the encoding about the number: the same file counts differently
+ * under `cl100k_base` and `o200k_base`, which is why the encoding is chosen next to the family
+ * instead of being implied. There is one family here, and that is not an omission: the others
+ * have no dictionary that could be called their own, and counting with someone else's while
+ * calling it a family would promise what does not exist. */
 
 export const TOKEN_FAMILIES = {
   openai: { tool: 'gpt-tokenizer', encodings: ['o200k_base', 'cl100k_base'] }
@@ -18,24 +18,25 @@ export const TOKEN_FAMILIES = {
 
 export const TOKEN_DEFAULTS = { family: 'openai', encoding: 'o200k_base' };
 
-/* Оценка без словаря. Коэффициент снят на текстах этого репозитория (русские
- * документы и код): `README.md` — 3,1 знака на токен, `WORKLOG.md` — около 3,0.
- * Для латиницы та же оценка завышает счёт (там примерно 4 знака на токен), поэтому
- * она и помечена приближением. */
+/* The estimate without a dictionary. The coefficient was taken from this repository's own
+ * texts (Russian documents and code): `README.md` gave 3.1 characters per token, the archived
+ * journal `worklog/archive/WORKLOG.md` about 3.0. For Latin script the same estimate overstates
+ * the count (about 4 characters per token there), which is why it is marked as an
+ * approximation. */
 export const CHARS_PER_TOKEN = 3;
 
-/* Форматы, для которых счёт токенов смысла не имеет: картинка, шрифт или архив —
- * это байты, и токенизатор разберёт их как что угодно, а число выйдет случайным.
- * Список нужен, чтобы метрика сказала это словами, а не выдала такой счёт за
- * посчитанный. SVG в него не входит намеренно: это текст, и его токены осмысленны. */
+/* Formats for which counting tokens makes no sense: a picture, a font or an archive is bytes,
+ * and the tokenizer would split them into anything at all, giving a random number. The list
+ * exists so that the metric says this in words instead of passing such a count off as counted.
+ * SVG is deliberately not here: it is text, and its tokens are meaningful. */
 export const BINARY_EXTS = [
   '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.avif',
   '.woff', '.woff2', '.ttf', '.otf', '.eot',
   '.pdf', '.zip', '.gz', '.tar', '.mp4', '.mp3', '.mov'
 ];
 
-/* Словарь загружается один раз на кодировку: за ним стоят мегабайты таблиц, и
- * платить за них на каждом файле было бы нечем оправдать. */
+/* A dictionary is loaded once per encoding: megabytes of tables stand behind it, and paying
+ * for them on every file would have no justification. */
 const probed = new Map();
 
 export function tokenizer(settings) {
@@ -51,26 +52,26 @@ function familyOf(settings) {
   return TOKEN_FAMILIES[asked] === undefined ? TOKEN_DEFAULTS.family : asked;
 }
 
-/* Счёт одного текста: словарём, если он есть, иначе оценкой. Оба ответа — число
- * условных единиц текста, и различает их не значение, а подпись метрики
- * (`accuracy`), поэтому выдача одного за другое невозможно. */
+/* Counting one text: with the dictionary if there is one, by estimate otherwise. Both answers
+ * are a number of text units, and what tells them apart is the metric label (`accuracy`) rather
+ * than the value, which is why one cannot be passed off as the other. */
 export function tokenCount(text, settings) {
   const { tool } = tokenizer(settings);
   if (tool === null) return estimate(text);
   return tool.encode(text).length;
 }
 
-/* Оценка по длине — единственное, что можно сказать без словаря. Знаки считаются
- * кодовыми точками: для не-ASCII это ближе к числу токенов, чем единицы UTF-16. */
+/* An estimate by length is all that can be said without a dictionary. Characters are counted
+ * as code points: for non-ASCII that is closer to the number of tokens than UTF-16 units. */
 export function estimate(text) {
   let chars = 0;
   for (const _ch of text) chars++;
   return Math.ceil(chars / CHARS_PER_TOKEN);
 }
 
-/* Бинарный ли файл: счёт токенов для него смысла не имеет. Список форматов ведёт
- * этот модуль, поэтому и подпись метрики, и пометка клетки спрашивают о файле
- * здесь, а не повторяют список у себя. */
+/* Whether the file is binary, since counting tokens means nothing for it. The list of formats
+ * is owned here, so both the metric label and the cell mark ask about a file here instead of
+ * keeping a list of their own. */
 export function isBinary(file) {
   return BINARY_EXTS.indexOf(path.extname(file).toLowerCase()) >= 0;
 }

package/src/tool.js

@@ -1,21 +1,20 @@
 import fs from 'fs';
 
-/* Метаданные самого пакета: имя и версия читаются из его же манифеста, чтобы не
- * держать вторую копию. Отдельный модуль потому, что эти данные описывают
- * упаковку, а не проект-потребитель, и нужны контракту данных. */
-
-/* Имя и версия пакета — из его же манифеста, чтобы не держать вторую копию; без
- * файла (чужaя сборка) остаётся заглушка: версия нужна только в данных, и
- * отсутствие манифеста не повод не собирать таблицу. */
+/* The package's own metadata: the name and the version are read from its manifest so that no second copy exists. A module
+ * of its own because these data describe the packaging rather than a consumer project, and the contract of the data needs
+ * them.
+ *
+ * With no manifest (someone else's build) the placeholder stays: the version is needed in the data alone, and a missing
+ * manifest is no reason not to build a report. */
 export let TOOL_PKG = { name: '@vernikr/size-report', version: '0.0.0' };
 try {
   TOOL_PKG = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 } catch (_e) {}
 
-/* Как пакет ставится в проект — та же git-ссылка на выпуск, которой учит `README.md`:
- * имени пакета в реестре здесь быть не может, оно занято чужим пакетом, и `add -D
- * <имя>` поставил бы его. Адрес и версия берутся из манифеста, поэтому совет об
- * установке не может разойтись с выпуском, а без адреса (`null`) звать нечего. */
+/* How the package is installed into a project — the git link to the release, the pinned form `README.md` teaches: the
+ * advice has to name the revision the documentation describes rather than whatever the registry serves as the latest one.
+ * The address and the version come from the manifest, so the advice cannot drift from the release, and with no address
+ * (`null`) there is nothing to name. */
 export function installSpec() {
   const repo = TOOL_PKG.repository === undefined ? ''
     : (typeof TOOL_PKG.repository === 'string' ? TOOL_PKG.repository : TOOL_PKG.repository.url || '');