@vernikr/size-report 1.1.1

package/src/strip.js

@@ -0,0 +1,231 @@
+import path from 'path';
+import vm from 'vm';
+import { refuseCause } from './refusal.js';
+import { moduleError } from './parse.js';
+
+/* Снятие балласта: стрипперы комментариев и отступов для каждой формы текста и
+ * правило, какая форма к какому файлу применяется. Только преобразование
+ * текста — ни истории, ни настроек этот модуль не знает. */
+
+export function byteLen(text) {
+  return Buffer.byteLength(text, 'utf8');
+}
+
+/* Снятие комментариев и отступов — метрика «объём без балласта», а не
+ * минификация: пробелы внутри строк и порядок токенов не трогаются (это позволит
+ * сравнивать числа между языками и не зависит от чужого инструмента, которого в
+ * проекте нет). Строки и шаблоны проходят насквозь, блочный комментарий
+ * заменяется пробелом, чтобы `a` и `b` из `a` + блочный комментарий + `b` не
+ * склеились в одно имя, перевод строки после `//` сохраняется — он разделяет
+ * токены. */
+export function stripJs(src) {
+  let out = '';
+  let i = 0;
+  let last = '';   // последний значимый символ вывода: по нему решается, оператор «/» или регексп
+  let word = '';   // хвост последнего слова: после `return` идёт выражение, а не деление
+  while (i < src.length) {
+    const ch = src[i];
+    const next = src[i + 1];
+    // Комментарные пары проверяются до регекси: ни `/`, ни `*` не могут быть
+    // первым символом литерала регекспа, а вот `/*` в начале файла — обычное дело.
+    if (ch === '/' && next === '/') {
+      const nl = src.indexOf('\n', i);
+      i = nl === -1 ? src.length : nl;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      const end = src.indexOf('*/', i + 2);
+      out += ' ';
+      i = end === -1 ? src.length : end + 2;
+      continue;
+    }
+    if (ch === '/' && regexAllowed(last, word)) {
+      const end = endOfRegex(src, i);
+      out += src.slice(i, end);
+      i = end;
+      last = '/';
+      word = '';
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const end = endOfString(src, i, ch);
+      out += src.slice(i, end);
+      i = end;
+      last = ch;
+      word = '';
+      continue;
+    }
+    out += ch;
+    if (ch.trim() !== '') {
+      last = ch;
+      word = /[\w$]/.test(ch) ? word + ch : '';
+    }
+    i++;
+  }
+  return out;
+}
+
+/* Регексп начинается там, где ожидается операнд: после оператора, открывающей
+ * скобки или ключевого слова. Признак грубый, но его хватает: без него
+ * `replace(/\//g, …)` читалось бы как начало строчного комментария и резало
+ * строку (проверено гардом компиляции). */
+const REGEX_KEYWORDS = ['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'case', 'do', 'else', 'yield', 'await'];
+
+function regexAllowed(last, word) {
+  if (last === '') return true;
+  if (REGEX_KEYWORDS.indexOf(word) !== -1) return true;
+  return '([{,;:=!&|?+-*%~^<>'.indexOf(last) !== -1;
+}
+
+function endOfRegex(src, start) {
+  let i = start + 1;
+  let inClass = false;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === '\n') return start + 1; // наткнулись на строку — значит, это был не регексп
+    if (ch === '[') inClass = true;
+    else if (ch === ']') inClass = false;
+    else if (ch === '/' && !inClass) return i + 1;
+    i++;
+  }
+  return start + 1;
+}
+
+function endOfString(src, start, quote) {
+  let i = start + 1;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === quote) return i + 1;
+    // В шаблоне `${…}` живёт выражение, а в нём — свои строки.
+    if (quote === '`' && ch === '$' && src[i + 1] === '{') { i = endOfTemplateExpr(src, i + 2); continue; }
+    i++;
+  }
+  return src.length;
+}
+
+function endOfTemplateExpr(src, start) {
+  let depth = 1;
+  let i = start;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === '{') { depth++; i++; continue; }
+    if (ch === '}') { depth--; i++; if (depth === 0) return i; continue; }
+    if (ch === '"' || ch === "'" || ch === '`') { i = endOfString(src, i, ch); continue; }
+    i++;
+  }
+  return src.length;
+}
+
+export function stripCss(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, ' ');
+}
+
+/* HTML: комментарии разметки (включая маркеры вклеек `<!--icon …-->` и
+ * `<!--/icon-->`), комментарии внутри <script> как JS и внутри <style> как CSS. */
+export function stripHtml(src) {
+  return src
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/(<script\b[^>]*>)([\s\S]*?)(<\/script>)/gi, (_m, open, body, close) => open + stripJs(body) + close)
+    .replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_m, open, body, close) => open + stripCss(body) + close);
+}
+
+export function stripLines(text) {
+  return text.split('\n').map((l) => l.trim()).filter((l) => l !== '').join('\n');
+}
+
+export function compactJson(text) {
+  try { return JSON.stringify(JSON.parse(text)); } catch (_e) { return stripLines(text); }
+}
+
+/* Стратегия по расширению. Незнакомое расширение получает снятие отступов и
+ * пустых строк — безопасный минимум: снимать комментарии «на глаз» в синтаксисе,
+ * которого генератор не знает (например, `#` в YAML или отступы в Python),
+ * значило бы мерить уже другой файл. */
+const MINIFY_BY_EXT = {
+  '.js': 'strip-js', '.mjs': 'strip-js', '.cjs': 'strip-js',
+  '.html': 'strip-html', '.htm': 'strip-html',
+  '.css': 'strip-css', '.scss': 'strip-css', '.less': 'strip-css',
+  '.json': 'json', '.json5': 'json'
+};
+export const STRATEGIES = ['strip-js', 'strip-html', 'strip-css', 'json', 'strip-lines', 'none'];
+
+/* Стратегии, которые и есть минификация: JSON теряет только незначащие пробелы
+ * (числа приводятся к кратчайшей записи), и короче его не сделает никто. Остальные
+ * — упрощение: они снимают балласт, но не переименовывают и не перестраивают код,
+ * и обещать за них точное число нельзя. Список ведёт тот модуль, который владеет
+ * стратегиями; метрика по нему решает, точное у неё число или приближённое. */
+export const EXACT_STRATEGIES = ['json'];
+
+export function strategyFor(file, cfg) {
+  const ext = path.extname(file).toLowerCase();
+  return (cfg.minify.ext && cfg.minify.ext[ext]) || MINIFY_BY_EXT[ext] || 'strip-lines';
+}
+
+export function minifyForm(text, file, cfg) {
+  const how = strategyFor(file, cfg);
+  if (how === 'none') return text;
+  if (how === 'strip-js') return stripLines(stripJs(text));
+  if (how === 'strip-html') return stripLines(stripHtml(text));
+  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(', ') + ')');
+}
+
+/* Гард стриппера: он не имеет права выбросить что-то кроме комментариев и
+ * отступов, поэтому результат обязан компилироваться. Проверяем только те
+ * расширения, где содержимое — валидный JavaScript (список в конфиге,
+ * `minify.guard`): TypeScript или JSX хостом не проверяются, и делать вид, что
+ * проверили, было бы хуже, чем не проверять.
+ *
+ * Модуль или скрипт решает текст, а не расширение: проект с бандлером пишет
+ * `import`/`export` прямо в `.js` (и с `type: module` в манифесте, и без него), а
+ * `vm.Script` разбирает такой файл как скрипт и падает на самом `export`. Гард
+ * обязан понимать оба формата, поэтому пробует тот, на который файл похож, и
+ * принимает результат, если он разбирается хотя бы одним из двух способов.
+ * От этого он не слабеет: настоящая поломка не разберётся ни скриптом, ни
+ * модулем, и тогда наружу идёт причина того разбора, которым файл был.
+ *
+ * Модуль разбирает отдельный рабочий поток (`parse.js`): без него разбор модуля
+ * стоил бы запуска Node на каждую клетку. Иначе конфиг вида `eslint.config.mjs`
+ * остался бы без гарда, а без гарда его правка могла бы испортить «объём» молча.
+ *
+ * Когда не разбирается даже исходный текст, стриппер тут ни при чём: в этой
+ * графе измеряется не JavaScript (TypeScript, JSX), и это отказ с командой
+ * починки — правкой настроек. */
+const MODULE_MARK = /^[ \t]*(?:import|export)\b/m;
+const MODULE_EXT = ['.mjs'];
+
+export function assertCompilable(min, rev, p, src) {
+  // Скрипт пробуется первым не ради формы, а ради цены: этот разбор идёт
+  // в процессе, а модуль — в рабочем потоке.
+  const asScript = scriptError(min, p);
+  if (asScript === null) return;
+  const asModule = moduleError(min);
+  if (asModule === null) return;
+  const shape = MODULE_EXT.indexOf(path.extname(p).toLowerCase()) >= 0 || MODULE_MARK.test(min);
+  if (src !== undefined && scriptError(src, p) !== null && moduleError(src) !== null) {
+    refuseCause('файл не JavaScript', 'файл ' + p + ' — не JavaScript: его исходный текст не'
+      + ' разбирается ни как скрипт, ни как модуль, так что дело не в стриптере, а '
+      + path.extname(p) + ' стоит в minify.guard: ' + (shape ? asModule : asScript) + '\n'
+      + '  починка: уберите это расширение из minify.guard или задайте для него '
+      + 'minify.ext — например { "' + path.extname(p).toLowerCase() + '": "strip-lines" }');
+  }
+  // Причина — того разбора, которым файл был: обвинять в чужой форме незачем.
+  throw new Error('стриппер испортил ' + p + ' на ' + rev.slice(0, 7) + ': '
+    + (shape ? asModule : asScript));
+}
+
+// Разбор как скрипт — в процессе: дешевле и без временных файлов.
+function scriptError(text, p) {
+  try {
+    new vm.Script(text, { filename: p });
+    return null;
+  } catch (e) {
+    return e.message;
+  }
+}
+

package/src/table.css

@@ -0,0 +1,35 @@
+/* Гарнитура одна на всю таблицу; числа выравниваются по разрядам за счёт
+ * tabular-nums, а не за счёт моноширинного шрифта. */
+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 нижней границы), иначе строки накладывались бы друг на друга. */
+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);
+ * угол шапки — выше всех, иначе группы колонок наползают на «Коммит». */
+.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; }
+/* Ширину колонки задаёт этот блок. Без него содержимое ячейки выходило за её
+ * границы и рисовалось поверх соседних чисел: у ячейки таблицы нет обрезки. */
+.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; }
+/* Рост зелёный, спад красный — по договорённости с заказчиком (рост — «больше
+ * логики», а не тревога). */
+.up { color: #1e8449; }
+.down { color: #c0392b; }
+.miss { opacity: .5; }
+/* Верхняя строка — текущие размеры: она же и объясняет, к чему относятся дельты. */
+tr.now th, tr.now td { border-bottom: 2px solid rgba(127, 127, 127, .35); }
+tr.now .c-commit { font-weight: 600; }
+/* Подсветка строки — наложением, а не подменой фона: липкая колонка обязана
+ * оставаться непрозрачной, иначе под ней при скролле видны числа. */
+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

@@ -0,0 +1,76 @@
+import path from 'path';
+import { loadOptional } from './optional.js';
+
+/* Токенизатор — та же дисциплина, что у минификатора: необязательная зависимость с
+ * ленивой загрузкой (устройство — в `src/optional.js`). Отличие одно: токенизатор
+ * берёт любой текст, отказать ему не в чем, поэтому отсутствие зависимости — не
+ * отказ, а другой счёт: оценка по длине, помеченная приближением в подписи метрики.
+ *
+ * Семейство — про модели, кодировка — про число: один и тот же файл считается
+ * по-разному в `cl100k_base` и `o200k_base`, поэтому кодировка выбирается рядом с
+ * семейством, а не подразумевается. Семейство тут одно, и это не недоделка: у
+ * остальных нет словаря, который можно было бы назвать их собственным, — считать
+ * чужим словарём и называть это семейством значило бы обещать то, чего нет. */
+
+export const TOKEN_FAMILIES = {
+  openai: { tool: 'gpt-tokenizer', encodings: ['o200k_base', 'cl100k_base'] }
+};
+
+export const TOKEN_DEFAULTS = { family: 'openai', encoding: 'o200k_base' };
+
+/* Оценка без словаря. Коэффициент снят на текстах этого репозитория (русские
+ * документы и код): `README.md` — 3,1 знака на токен, `WORKLOG.md` — около 3,0.
+ * Для латиницы та же оценка завышает счёт (там примерно 4 знака на токен), поэтому
+ * она и помечена приближением. */
+export const CHARS_PER_TOKEN = 3;
+
+/* Форматы, для которых счёт токенов смысла не имеет: картинка, шрифт или архив —
+ * это байты, и токенизатор разберёт их как что угодно, а число выйдет случайным.
+ * Список нужен, чтобы метрика сказала это словами, а не выдала такой счёт за
+ * посчитанный. SVG в него не входит намеренно: это текст, и его токены осмысленны. */
+export const BINARY_EXTS = [
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.avif',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.pdf', '.zip', '.gz', '.tar', '.mp4', '.mp3', '.mov'
+];
+
+/* Словарь загружается один раз на кодировку: за ним стоят мегабайты таблиц, и
+ * платить за них на каждом файле было бы нечем оправдать. */
+const probed = new Map();
+
+export function tokenizer(settings) {
+  const encoding = (settings || TOKEN_DEFAULTS).encoding;
+  if (probed.has(encoding)) return probed.get(encoding);
+  const tool = loadOptional(TOKEN_FAMILIES[familyOf(settings)].tool + '/encoding/' + encoding);
+  probed.set(encoding, tool);
+  return tool;
+}
+
+function familyOf(settings) {
+  const asked = (settings || TOKEN_DEFAULTS).family;
+  return TOKEN_FAMILIES[asked] === undefined ? TOKEN_DEFAULTS.family : asked;
+}
+
+/* Счёт одного текста: словарём, если он есть, иначе оценкой. Оба ответа — число
+ * условных единиц текста, и различает их не значение, а подпись метрики
+ * (`accuracy`), поэтому выдача одного за другое невозможно. */
+export function tokenCount(text, settings) {
+  const { tool } = tokenizer(settings);
+  if (tool === null) return estimate(text);
+  return tool.encode(text).length;
+}
+
+/* Оценка по длине — единственное, что можно сказать без словаря. Знаки считаются
+ * кодовыми точками: для не-ASCII это ближе к числу токенов, чем единицы UTF-16. */
+export function estimate(text) {
+  let chars = 0;
+  for (const _ch of text) chars++;
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+/* Бинарный ли файл: счёт токенов для него смысла не имеет. Список форматов ведёт
+ * этот модуль, поэтому и подпись метрики, и пометка клетки спрашивают о файле
+ * здесь, а не повторяют список у себя. */
+export function isBinary(file) {
+  return BINARY_EXTS.indexOf(path.extname(file).toLowerCase()) >= 0;
+}

package/src/tool.js

@@ -0,0 +1,24 @@
+import fs from 'fs';
+
+/* Метаданные самого пакета: имя и версия читаются из его же манифеста, чтобы не
+ * держать вторую копию. Отдельный модуль потому, что эти данные описывают
+ * упаковку, а не проект-потребитель, и нужны контракту данных. */
+
+/* Имя и версия пакета — из его же манифеста, чтобы не держать вторую копию; без
+ * файла (чужaя сборка) остаётся заглушка: версия нужна только в данных, и
+ * отсутствие манифеста не повод не собирать таблицу. */
+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`) звать нечего. */
+export function installSpec() {
+  const repo = TOOL_PKG.repository === undefined ? ''
+    : (typeof TOOL_PKG.repository === 'string' ? TOOL_PKG.repository : TOOL_PKG.repository.url || '');
+  const m = repo.match(/github\.com[:/]+([^/\s]+\/[^/\s]+?)(?:\.git)?$/);
+  return m === null ? null : 'github:' + m[1] + '#v' + TOOL_PKG.version;
+}

package/templates/README.md

@@ -0,0 +1,79 @@
+# Шаблоны для подключаемого проекта
+
+Два файла, которые проект берёт как есть: настройки, проходящие проверку самого
+инструмента, и описание проверки в CI. Ставятся они вместе с пакетом, поэтому
+лежат в его поставке (`files` в `package.json`) и стерегутся проверкой
+`test/templates.test.js`: черновик обязан быть валидным, а команды описания —
+существовать в инструменте.
+
+| Файл | Куда | Что делать |
+|---|---|---|
+| `size-report.config.json` | `size-table.config.json` в корне проекта | **Поправить колонки** и, если нужно, остальное |
+| `ci.yml` | `.github/workflows/size-report.yml` | Ничего: файл работает как есть |
+
+## Настройки
+
+Скопируйте `size-report.config.json` в корень проекта под именем
+`size-table.config.json`. **Колонки в нём — пример**, а не список ваших файлов:
+в шаблоне стоят `README.md` и `package.json`, потому что они есть почти в любом
+проекте, и с ними первый отчёт соберётся сразу. Свои колонки даёт
+`size --init` (он подбирает крупнейшие файлы по расширениям) — можно взять его
+черновик целиком, а из шаблона перенести ключи, которых `--init` не пишет
+(`skip`, `rows`, `links.commitUrl`), или наоборот: скопировать шаблон и вписать
+колонки руками.
+
+Что стоит знать про значения шаблона:
+
+- `metrics: ["raw", "min", "tok"]` — три измерения отчёта. `min` считается
+  настоящим минификатором (`minify.engine: "esbuild"`), а `tok` — словарём
+  `o200k_base`. Оба едут необязательными зависимостями пакета и ставятся обычной
+  установкой; если их нет (установка без необязательных зависимостей, платформа
+  без них), инструмент работает, но честно говорит, что числа получены другим
+  счётом, и отдаёт **код 4** — это не ошибка настройки, а названное приближение.
+- `fixCommand` — команда, которую цитирует подпись отчёта и отказы. В шаблоне это
+  `node node_modules/@vernikr/size-report/bin/size.js --write` — путь к
+  установленному пакету внутри проекта. **Имени пакета как команды здесь быть не
+  может:** `npx <имя>` в проекте без установленного пакета уходит в реестр и тянет
+  пакет по сети, то есть совет, который должен выручать, зависит от доступа к
+  реестру и от того, что там лежит. Если в проекте есть свой
+  скрипт, например `pnpm run sizes`, — впишите его: подпись отчёта будет вести
+  к нему.
+- `journal: null` — ссылок на разделы журнала не будет. Если в проекте есть
+  `WORKLOG.md` или `CHANGELOG.md`, поставьте объект с `path`, `url`, `pattern` —
+  образец печатает `size --init`.
+- `paths` внутри колонки — псевдонимы одного файла: если файл переименовывали,
+  перечислите и старое имя, и новое, и колонка не разорвётся.
+- `output: "docs/size-table.html"` — файл таблицы; каталог инструмент создаст сам.
+
+## Проверка в CI
+
+Скопируйте `ci.yml` в `.github/workflows/size-report.yml` — правок он не требует,
+если проект на `pnpm`. Что он делает и почему именно так, написано в его
+комментариях; коротко: собирает таблицу заново и сверяет с файлом на диске,
+а затем снимает данные отчёта дважды — обычно и в среде, где настроек git нет
+вовсе (`GIT_CONFIG_GLOBAL=/dev/null`), — и сравнивает снимки побайтово. Второе и
+есть проверка того, что числа не зависят от машины.
+
+Своих секретов описание не требует и не должно: пакет ставится из публичного
+репозитория, а pnpm тянет его архив по HTTPS — ни ключа, ни токена ни установке,
+ни самой проверке не нужно. Если проект уйдёт на приватный registry или на свою
+копию пакета, шаг с ключом придётся добавить самому: заводить его в шаблоне за
+проект инструмент не должен.
+
+Для `npm` и `yarn` в файле сказано, какие две строки заменить.
+
+Проверки полноты (`pnpm exec size check`) в шаблоне намеренно нет: она требует,
+чтобы **каждый** путь истории был колонкой или исключением, — а колонки в шаблоне
+примерные, и на проекте, где они ещё не подобраны, такая проверка была бы красной
+не по делу. Когда колонки обрисуют проект, добавьте шаг сами: `check` назовёт
+пути, которые колонкой не отслеживаются, и коммиты, которые их завели; те, что
+считать не нужно, вписываются в `skip` — тот же список делает путь и исключением.
+Про один коммит отвечает `pnpm exec size explain <sha>`.
+
+## Чего в шаблонах нет
+
+Блока для файлов агентов проекта (`AGENTS.md` и подобных) здесь нет намеренно:
+требования такого файла не просят, а выдумывать формат чужого репозитория
+инструмент не должен. Что агенту нужно знать, он возьмёт из `size --help` и
+`size --data` — команды и данные описаны в `README.md` пакета, раздел
+«Для ИИ-агента».

package/templates/ci.yml

@@ -0,0 +1,67 @@
+# Проверка объёма для проекта, подключившего @vernikr/size-report.
+# Положите файл в .github/workflows/size-report.yml — правок он не требует.
+#
+# Что проверяется и почему так:
+#   * таблица объёма на диске сходится с историей git — это числа отчёта;
+#   * тот же снимок чисел, снятый в среде, где настроек git нет вовсе,
+#     совпадает побайтово: вывод инструмента не должен зависеть от того, что
+#     настроено на машине (BLOCKERS.md §B1, §B2).
+#
+# Секретов шаблон не требует и не может потребовать: пакет ставится из
+# публичного репозитория, а pnpm тянет его архив с codeload.github.com по HTTPS —
+# ни ключа, ни токена установке не нужно (проверено установкой в окружении без
+# настроек git и без помощника учётных данных; README пакета, §1). Если проект
+# уйдёт на приватный registry, шаг с ключом придётся добавить самому.
+#
+# Менеджер пакетов: ниже pnpm. Для npm — `npm ci` вместо `pnpm install`,
+# для yarn — `yarn --immutable`. Сама проверка — всегда одна и та же команда
+# `size`: локальный бинарь, поставленный установкой пакета (`pnpm exec size` после
+# `pnpm install`, `npm exec size` после `npm ci`).
+# Имени пакета как команды здесь нет намеренно: `npx <имя>` в проекте без
+# установленного пакета уходит в реестр и тянет пакет оттуда по сети, тогда как
+# шаг проверки обязан работать на том, что поставлено установкой.
+# Нужен явный путь — `node node_modules/@vernikr/size-report/bin/size.js`.
+#
+# Отчёт не в git? Такое тоже задумано требованиями (отчёт — выводимый артефакт):
+# тогда вместо шага «Таблица объёма совпадает с историей» поставьте сборку —
+# `pnpm exec size --write` — и этот шаг будет проверять, что отчёт собирается.
+
+name: size-report
+
+on: [push, pull_request]
+
+jobs:
+  size:
+    runs-on: ubuntu-latest
+    steps:
+      # История нужна целиком: таблица строится по коммитам, и на обрезанном
+      # клоне инструмент отказывается работать (код 3), а не пишет короткую.
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Установка
+        run: pnpm install --frozen-lockfile
+
+      # Проверка — та же команда `size` без ключей: она собирает таблицу заново
+      # и сверяет с файлом на диске. Своего набора тестов потребителю не нужно.
+      - name: Таблица объёма совпадает с историей
+        run: pnpm exec size
+
+      - name: Снимок чисел контракта
+        run: pnpm exec size --data > /tmp/size-report-data.json
+
+      - name: Снимок чисел без настроек git на машине
+        run: pnpm exec size --data > /tmp/size-report-data-null.json
+        env:
+          GIT_CONFIG_GLOBAL: /dev/null
+
+      - name: Числа не зависят от настроек машины
+        run: diff -u /tmp/size-report-data.json /tmp/size-report-data-null.json

package/templates/size-report.config.json

@@ -0,0 +1,53 @@
+{
+  "output": "docs/size-table.html",
+  "locale": "ru",
+  "title": "Объём файлов по коммитам",
+  "heading": "Объём файлов по коммитам",
+  "fixCommand": "node node_modules/@vernikr/size-report/bin/size.js --write",
+  "metrics": [
+    "raw",
+    "min",
+    "tok"
+  ],
+  "minify": {
+    "engine": "esbuild",
+    "ext": {},
+    "guard": [
+      ".js",
+      ".mjs",
+      ".cjs"
+    ]
+  },
+  "tokens": {
+    "family": "openai",
+    "encoding": "o200k_base"
+  },
+  "columns": [
+    {
+      "label": "README.md",
+      "paths": [
+        "README.md"
+      ],
+      "category": "docs"
+    },
+    {
+      "label": "package.json",
+      "paths": [
+        "package.json"
+      ],
+      "category": "chore"
+    }
+  ],
+  "journal": null,
+  "links": {
+    "commitUrl": ""
+  },
+  "rows": {
+    "merges": true,
+    "sha": true
+  },
+  "hooks": {
+    "enabled": true
+  },
+  "skip": []
+}