@vernikr/size-report 2.3.0 → 2.5.0

package/src/page/state.js

@@ -1,27 +1,22 @@
-/* Программа страницы отчёта: панель выбора с легендой и таблица.
+/* The page's choice state: what is switched on, how it survives a closing and how it travels as a link.
  *
- * Это обычный исходник, а не строка в движке: его видит линтер, и он же
- * вклеивается в собранную страницу (`pageScript` снимает модульный синтаксис —
- * импорт ниже и объявления с `export` из соседнего файла). Расчёт берётся из
- * производных величин, поэтому включение метрики, категории или файла зовёт тот
- * же расчёт, что считает статическую таблицу, и не может дать других чисел.
+ * An ordinary source file rather than a string inside the engine: a linter sees it, and it is pasted into the assembled
+ * page (`pageScript` strips module syntax — the `import` lines and the `export` keywords of the chapters). The numbers
+ * come from the derived quantities, so switching a metric, a category or a file calls the same calculation the report's
+ * numbers come from and cannot yield different ones.
  *
- * Страница — один файл без внешних ссылок, поэтому здесь нет ни динамического
- * импорта, ни загрузки чего-либо по сети: оформление приходит тем же файлом,
- * а разметка клеток повторяет статическую таблицу (`clip` и подпись коммита —
- * правила общей части оформления).
+ * The page is one file without external references, so there is no dynamic import here and nothing is loaded over the
+ * network: the styling arrives in the same file, and the cell markup follows the rules of the shared part of the styling
+ * (`clip`, a commit's caption).
  *
- * Панель помнит выбор читателя между открытиями и умеет передать его ссылкой
- * («Память выбора» ниже): запись привязана к паспорту отчёта и хранит только
- * выключенное по именам, поэтому чужая запись не применяется, а исчезнувшее имя
- * просто ничего не значит. Та же запись ложится в адрес — его и отправляют коллеге.
+ * The panel remembers the reader's choice between visits and can hand it over as a link ("the choice's memory" below):
+ * the record is tied to the report's passport and keeps only what is switched off, by name, so someone else's record is
+ * not applied while a vanished name simply means nothing. The same record goes into the address — which is what one
+ * sends to a colleague.
  *
- * Точность числа страница не выводит сама: пометки приближённых клеток приходят в
- * данных, от того же правила, по которому названа точность метрики. Из путей и
- * форматов страница такого вывода не делает — второго правила точности не будет. */
-
-/* Импорт — одной строкой: модульный синтаксис снимается при вклейке построчно,
- * и оставшаяся строка `import` попала бы в страницу (её ловит проверка). */
+ * The page does not derive a number's accuracy itself: the marks of approximate cells arrive in the data, from the same
+ * rule that names a metric's accuracy. The page draws no such conclusion from paths and formats — there will be no
+ * second rule of accuracy. */
 
 export const appData = JSON.parse(document.getElementById('data').textContent);
 export const appUi = JSON.parse(document.getElementById('ui').textContent);
@@ -29,42 +24,39 @@ export const appView = { metrics: {}, files: [], folded: {} };
 appData.metrics.forEach((m) => { appView.metrics[m.key] = true; });
 appData.files.forEach(() => { appView.files.push(true); });
 
-/* Описание метрики по ключу: подсказка приближённой клетки называет способ её
- * числа — тот же, что стоит в подписи метрики, поэтому двух ответов про «чем
- * посчитано» у страницы нет. */
+/* A metric's description by key: the tooltip of an approximate cell names the way its number was obtained — the same one
+ * that stands in the metric's caption, so the page holds no two answers about "counted with what". */
 export const appMetric = {};
 appData.metrics.forEach((m) => { appMetric[m.key] = m; });
 
-/* Колонка по пути файла: дерево страницы — дерево проекта (все пути каталога), а
- * числа есть только у колонок, поэтому лист дерева по этому указателю и решает,
- * галочка он или подпись. Имя берётся тем же правилом, что у записи выбора
- * (`appFileAt`), — дерево и память читателя разойтись не могут. */
+/* A column by a file's path: the page's tree is the project's tree (every path of the catalogue) while the numbers
+ * belong to columns only, so this pointer is what decides whether a leaf is a checkbox or a caption. The name follows the
+ * same rule as the choice's record (`appFileAt`), so the tree and the reader's memory cannot drift apart. */
 export const appMeasured = {};
 appData.files.forEach((_f, i) => { appMeasured[appFileAt(i)] = i; });
 
-/* Ссылка — это тот же выбор в адресе, под своим именем: чужой якорь страницы
- * ссылкой не считается, и спорить с ним нечем. */
+/* A link is that same choice in the address, under a name of its own: someone else's anchor on the page does not count
+ * as a link, and there is nothing to argue with it about. */
 const APP_LINK = '#size-report=';
 
-/* Три обстоятельства первой отрисовки, которые действуют только на ней:
- * адрес в ней не переписывается (его прислали читателю, а не наоборот), память
- * не трогается (присланная ссылка — не выбор читателя), а сообщение о ссылке
- * ещё не гаснет. */
+/* Three circumstances of the first drawing, which act on it alone: the address is not rewritten during it (it was sent to
+ * the reader rather than the other way), the memory is not touched (a link that came in is not the reader's choice), and
+ * the message about the link has not faded yet. */
 let appStartup = true;
 let appForeign = false;
 let appTransient = false;
 
-/* -------- память выбора читателя -------- */
+/* -------- the reader's memory of his choice -------- */
 
-/* Имя файла для записи — путь на HEAD, а если файла там уже нет, последний из
- * настроек: по нему файл и опознаётся в отчёте. */
+/* The name of a file for the record is its path at HEAD, or the last of the settings when the file is already gone from
+ * there: that is the name it is recognised by in the report. */
 export function appFileAt(i) {
   const f = appData.files[i];
   return f.path === null ? f.paths[0] : f.path;
 }
 
-/* Отпечаток паспорта: опознавательный знак записи, а не защита от подделки,
- * поэтому 32 бит достаточно (FNV-1a). */
+/* The passport's fingerprint: an identifying mark of a record rather than protection against forgery, so 32 bits are
+ * enough (FNV-1a). */
 function appHash(text) {
   let h = 2166136261;
   for (let i = 0; i < text.length; i++) {
@@ -74,22 +66,20 @@ function appHash(text) {
   return (h >>> 0).toString(16);
 }
 
-/* Паспорт отчёта: имя инструмента, схема данных, путь артефакта, заголовок и метки
- * колонок в порядке отчёта. Он и отделяет один отчёт от другого — по нему выбирается
- * ключ записи, поэтому выбор с чужого отчёта не подхватывается. Версии пакета и
- * верхушки истории в паспорте нет намеренно: это тот же отчёт — обновление
- * инструмента не меняет того, что значит колонка, а подросшая история это та же
- * история, к которой читатель и возвращается. */
+/* The report's passport: the tool's name, the data schema, the artifact's path, the title and the column labels in the
+ * report's order. It is what tells one report from another — the record's key is chosen by it, so a choice made in
+ * someone else's report is not picked up. The package version and the top of the history are absent on purpose: this is
+ * the same report — updating the tool does not change what a column means, while a grown history is the very history the
+ * reader comes back to. */
 function appPassport() {
   return appHash([appData.tool.name, appData.schema, appData.report.artifact,
     appData.report.title, appData.files.map((f) => f.label).join('|')].join('\n'));
 }
 const appKey = 'size-report:' + appPassport();
 
-/* Запись выбора — одна на всё: её кладут и в память, и в адрес, поэтому двух
- * форматов одного состояния не бывает. Хранится только выключенное, по именам:
- * «включено» и «записи нет» — одно и то же состояние, поэтому возврат всех галочек
- * убирает запись, а не оставляет след, неотличимый от выбора. */
+/* One record of the choice for everything: it goes both into the memory and into the address, so there are no two formats
+ * of one state. Only what is switched off is kept, by name: "switched on" and "no record" are the same state, which is
+ * why turning every checkbox back on removes the record instead of leaving a trace indistinguishable from a choice. */
 function appRecord() {
   const metrics = {};
   const files = {};
@@ -98,7 +88,7 @@ function appRecord() {
   return { v: 1, passport: appPassport(), metrics: metrics, files: files };
 }
 
-// Своя ли запись и того ли формата — одно правило и для памяти, и для адреса.
+// Whether a record is ours and of the right format — one rule for the memory and the address alike.
 function appRecordOk(rec) {
   return rec !== null && typeof rec === 'object' && rec.v === 1 && rec.passport === appPassport();
 }
@@ -111,34 +101,33 @@ export function appWrite() {
       if (empty) window.localStorage.removeItem(appKey);
       else window.localStorage.setItem(appKey, JSON.stringify(rec));
     } catch (_e) {
-      /* Памяти нет (браузер её не даёт этой странице): выбор не переживёт закрытия,
-       * а числа и разметка от этого не зависят. */
+      /* There is no memory (the browser grants this page none): the choice will not survive a closing, while the numbers
+       * and the markup do not depend on it. */
     }
   }
-  /* Адрес и есть ссылка для коллеги, поэтому он повторяет выбор. Но не на первой
-   * отрисовке и не тогда, когда ссылка оказалась чужой: присланный адрес — не наш,
-   * его читателю ещё читать. */
+  /* The address is the link for a colleague, which is why it repeats the choice. But not during the first drawing and not
+   * when the link turned out to be someone else's: an address that came in is not ours, and the reader has yet to read
+   * it. */
   if (appStartup || appForeign) return;
   try {
     window.history.replaceState(null, '', APP_LINK + encodeURIComponent(JSON.stringify(rec)));
   } catch (_e) {
-    /* Браузер не даёт менять адрес: ссылку тогда берут из памяти браузера. */
+    /* The browser grants no change of the address: the link is then taken from the browser's memory. */
   }
 }
 
-/* Сброс к «включено всё»: граница между «в отчёте этого больше нет» и
- * «выключено» — это запись, а не отсутствие значения. Ссылка несёт весь выбор
- * отправителя, поэтому применяется на чистом виде, а не поверх чужого. */
+/* A reset to "everything on": the border between "this is no longer in the report" and "switched off" is the record
+ * rather than a missing value. A link carries the sender's whole choice, which is why it is applied to a clean view rather
+ * than on top of someone else's. */
 function appAll() {
   appData.metrics.forEach((m) => { appView.metrics[m.key] = true; });
   appData.files.forEach((_f, i) => { appView.files[i] = true; });
 }
 
-/* Что говорит адрес. Отвечает либо своей записью, либо отказом (`linkForeign` —
- * ссылка другого отчёта, `linkBroken` — прочитать нечего): чужой или испорченный
- * выбор не применяется, но и не молчит — иначе читатель не поймёт, почему он видит
- * не то, что ему прислали. Адрес без имени ссылки не ссылка вовсе: молчание, чтобы
- * не спорить с обычными якорями страницы. */
+/* What the address says. It answers either with a record of ours or with a refusal (`linkForeign` — a link of another
+ * report, `linkBroken` — nothing to read): someone else's or a broken choice is not applied, but it does not stay silent
+ * either — otherwise the reader would not understand why he sees something other than what was sent to him. An address
+ * without the link's name is no link at all: silence, so as not to argue with the page's ordinary anchors. */
 function appLinkRead() {
   const hash = window.location.hash || '';
   if (hash.indexOf(APP_LINK) !== 0) return { rec: null, refused: null };
@@ -160,8 +149,8 @@ function appLinkRead() {
   return { rec: rec, refused: null, extra: appUnknown(rec) };
 }
 
-/* Сколько имён в ссылке этому отчёту неизвестны: о них читателю надо сказать —
- * иначе он будет искать в таблице то, чего в ней и не было. */
+/* How many names in the link are unknown to this report: the reader has to be told about them — otherwise he would look
+ * in the table for something that was never there. */
 function appUnknown(rec) {
   const known = {};
   const metricKeys = {};
@@ -173,19 +162,18 @@ function appUnknown(rec) {
   return n;
 }
 
-/* Сообщение о ссылке гаснет после первого же действия читателя: он его прочитал, а
- * постоянное предупреждение — это шум поверх чисел. */
+/* The message about the link fades after the reader's very first action: he has read it, and a permanent warning is noise
+ * on top of the numbers. */
 export function appNotice(text) {
   const el = document.getElementById('notice');
   el.textContent = text;
   el.hidden = text === '';
 }
 
-/* Что делает с адресом его событие — открытие страницы и перемена якоря на уже
- * открытой (браузер в этом случае документ не перезагружает, а лишь переставляет
- * якорь, поэтому без этого разбора ссылка работала бы только в новой вкладке).
- * Своя ссылка заменяет вид целиком: в ней весь выбор отправителя, а не разница с
- * чужим. Отказ объясняется словами — и не трогает ни вид, ни адрес. */
+/* What its event does with the address — opening the page and an anchor change on an already open one (the browser does
+ * not reload the document then, it only moves the anchor, so without this reading a link would work in a new tab alone).
+ * A link of ours replaces the view whole: it holds the sender's entire choice rather than a difference from someone
+ * else's. A refusal is explained in words — and touches neither the view nor the address. */
 export function appLinkUse() {
   const link = appLinkRead();
   if (link.rec !== null) {
@@ -201,9 +189,8 @@ export function appLinkUse() {
   return 'none';
 }
 
-/* Чтение: только своя запись — своей версии формата и своего паспорта. Запись
- * чужого отчёта лежит под другим ключом, а чужая, устаревшая или испорченная
- * равносильна её отсутствию. */
+/* Reading: only a record of ours — of our format version and our passport. Another report's record lies under another key,
+ * while a foreign, outdated or broken one amounts to its absence. */
 export function appRead() {
   let text = null;
   try {
@@ -221,10 +208,9 @@ export function appRead() {
   return appRecordOk(rec) ? rec : null;
 }
 
-/* Применение — по именам: файл опознаётся путём, метрика ключом. Имени, которого в
- * отчёте нет, ничего не соответствует (колонку перенаправили на другой путь,
- * метрику убрали из настроек), а появившиеся файлы и метрики остаются включёнными —
- * как их видит тот, кто открыл страницу впервые. */
+/* Applying goes by name: a file is recognised by its path, a metric by its key. A name the report does not hold matches
+ * nothing (a column was pointed at another path, a metric was dropped from the settings), while files and metrics that
+ * appeared stay switched on — the way someone opening the page for the first time sees them. */
 export function appApply(rec) {
   const metrics = rec.metrics || {};
   const files = rec.files || {};
@@ -232,13 +218,12 @@ export function appApply(rec) {
   appData.files.forEach((_f, i) => { if (files[appFileAt(i)] === false) appView.files[i] = false; });
 }
 
-/* -------- сложенное дерево -------- */
+/* -------- the folded tree -------- */
 
-/* Сложенные папки — память того же рода, что выбор, но своей записи: она про то,
- * сколько дерева видно, а не про то, какие числа читают. Поэтому в адрес она не
- * идёт: ссылку отправляют ради чисел, а разложенное дерево — дело смотрящего. Как и
- * у выбора, здесь помнится только сложенное (`true`), а имя папки — это путь
- * («src/page»), поэтому исчезнувшее имя просто ничего не значит. */
+/* Folded folders are a memory of the same kind as the choice, but of a record of their own: it is about how much of the
+ * tree is visible rather than about which numbers are read. Hence it does not go into the address: a link is sent for the
+ * sake of the numbers, while an unfolded tree is the onlooker's business. As with the choice, only what is folded is kept
+ * (`true`), and a folder's name is its path ("src/page"), so a vanished name simply means nothing. */
 const appFoldKey = appKey + ':tree';
 
 export function appFoldRead() {
@@ -268,7 +253,7 @@ export function appFoldSet(path, folded) {
     if (Object.keys(rec.folded).length === 0) window.localStorage.removeItem(appFoldKey);
     else window.localStorage.setItem(appFoldKey, JSON.stringify(rec));
   } catch (_e) {
-    /* Памяти нет: сложенное не переживёт закрытия страницы, а вид от этого не
-     * зависит — дерево сложено ровно так, как его сложил читатель сейчас. */
+    /* There is no memory: what is folded will not survive a closing, while the view does not depend on it — the tree is
+     * folded exactly the way the reader folded it just now. */
   }
 }

package/src/page/table.js

@@ -2,11 +2,10 @@ import { cellParts, commitParts, nowModel, rowModel, valueParts } from '../deriv
 import { appEl } from './dom.js';
 import { appData, appUi, appView, appMetric } from './state.js';
 
-/* Приближённая клетка: пометка берётся из данных движка, а не выводится здесь из
- * пути файла, — правило точности живёт там же, где считаются числа. У клетки
- * файла это её собственное число, у итога — худшее из вошедших в него, иначе
- * сумма обещала бы точность, которой нет у слагаемых. Возвращается описание
- * метрики (её способ и идёт в подсказку клетки) либо ничего. */
+/* An approximate cell: the mark comes from the engine's data rather than being derived here from a file's path — the rule
+ * of accuracy lives where the numbers are counted. For a file's cell it is that number itself, for a total the worst of
+ * what went into it, or the sum would promise an accuracy its terms do not have. Returns the metric's description (its way
+ * of counting is what goes into the cell's tooltip) or nothing. */
 export function appApprox(where, files, key) {
   const marks = appData.approx[key];
   if (marks === undefined) return null;
@@ -18,13 +17,13 @@ export function appApprox(where, files, key) {
   return null;
 }
 
-/* Класс клетки собирается в одном месте: и пометка приближения, и пропуск
- * («файла нет») — свойства самой клетки, а не её содержимого. */
+/* The cell's class is assembled in one place: both the mark of approximation and the gap ("no such file") are properties
+ * of the cell itself rather than of its content. */
 function appCellClass(first, miss, approx) {
   return 'num' + (first ? ' g' : '') + (miss ? ' miss' : '') + (approx === null ? '' : ' approx');
 }
 
-// Разметка клетки строки-коммита: правила — в cellParts, здесь только узел.
+// The markup of a commit row's cell: the rules live in cellParts, only the node is here.
 export function appCell(cell, first, approx) {
   const parts = cellParts(cell.value, cell.delta, '−');
   const td = appEl('td', appCellClass(first, parts.miss, approx));
@@ -34,7 +33,7 @@ export function appCell(cell, first, approx) {
   return td;
 }
 
-// Разметка клетки верхней строки: правила — в valueParts.
+// The markup of the top row's cell: the rules live in valueParts.
 export function appValueCell(value, first, approx) {
   const parts = valueParts(value);
   const td = appEl('td', appCellClass(first, parts.miss, approx));
@@ -43,9 +42,8 @@ export function appValueCell(value, first, approx) {
   return td;
 }
 
-/* Подпись коммита — той же разметкой, что в статической таблице: дата, тема,
- * метка раздела журнала. Ширину колонки и обрезку длинной темы задаёт общая часть
- * оформления, поэтому колонка не прыгает при переключении файлов. */
+/* 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);
@@ -69,9 +67,9 @@ export function appSubHead(metrics) {
   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. */
 export function appState(metricsCount, filesCount) {
   const state = document.getElementById('state');
   const text = metricsCount === 0 ? appUi.empty : (filesCount === 0 ? appUi.noFiles : '');
@@ -80,9 +78,9 @@ export function appState(metricsCount, filesCount) {
   document.getElementById('shell').hidden = metricsCount === 0;
 }
 
-/* Шапка: строка групп (итог и файлы) и строка метрик под ней. Метрики повторяются
- * на каждый файл, поэтому подшапка собирается один раз, а дальше её узлы
- * переезжают в следующие — копий разметки не заводится. */
+/* The header: a row of groups (the total and the files) and a row of metrics under it. The metrics repeat for every file,
+ * so the sub-header is assembled once and its nodes then move on into the following ones — no copies of the markup are
+ * made. */
 export function appHead(shown, files, metrics) {
   const head = appEl('tr');
   const commit = appEl('th', 'c-commit', appUi.commit);
@@ -107,9 +105,9 @@ export function appHead(shown, files, metrics) {
   return thead;
 }
 
-/* Строка-коммит: подпись и числа. Дельты считает общий расчёт (`rowModel`) — тот
- * же, что считает статическую таблицу; здесь только узлы. Пометка приближения —
- * своя у каждой клетки: у итога по всем вошедшим файлам, у файла — по нему самому. */
+/* 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 mark of approximation is each cell's own: for a total it
+ * covers every file that went into it, for a file that file alone. */
 export function appRow(r, metrics, files) {
   const row = appData.rows[r];
   const prev = r === 0 ? null : appData.rows[r - 1];
@@ -125,9 +123,8 @@ export function appRow(r, metrics, files) {
   return tr;
 }
 
-/* Тело: строки коммитов снизу вверх (свежие первыми) плюс верхняя строка «сейчас»
- * с абсолютными размерами на HEAD. Дельты под ней сходятся с ней, поэтому она и
- * стоит первой. */
+/* The body: the commit rows built 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(metrics, files) {
   const body = appEl('tbody');
   for (let r = appData.rows.length - 1; r >= 0; r--) body.appendChild(appRow(r, metrics, files));

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';