@vernikr/size-report 1.1.1

package/src/parse-worker.js

@@ -0,0 +1,34 @@
+import vm from 'vm';
+import { workerData } from 'worker_threads';
+
+/* Рабочий поток разбора: компилирует текст и отвечает причиной (или её
+ * отсутствием). Исполнения нет — `SourceTextModule` только разбирает текст,
+ * поэтому ни `import`, ни код модуля не выполняются: файл проекта остаётся
+ * чужим кодом, который никто не запускает.
+ *
+ * Флаги приходят от главного потока (`--experimental-vm-modules` — без него
+ * `vm.SourceTextModule` не существует, `--no-warnings` — иначе предупреждение об
+ * эксперименте ушло бы в вывод команды). Модуля может не быть: тогда ответ несёт
+ * `available: false`, и главный поток возвращается к запуску `node --check`.
+ *
+ * Готовность ответа отмечается в общей памяти: главный поток ждёт её синхронно
+ * (`Atomics.wait`), потому что измерение истории синхронное.
+ */
+const { port, sig } = workerData;
+const available = typeof vm.SourceTextModule === 'function';
+
+port.on('message', (req) => {
+  port.postMessage({ id: req.id, available: available, error: parse(req.text) });
+  Atomics.store(sig, 0, 1);
+  Atomics.notify(sig, 0);
+});
+
+function parse(text) {
+  if (!available) return null;
+  try {
+    new vm.SourceTextModule(text, { identifier: 'module' });
+    return null;
+  } catch (e) {
+    return e.name + ': ' + e.message;
+  }
+}

package/src/parse.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { Worker, MessageChannel, receiveMessageOnPort } from 'worker_threads';
+import { fileURLToPath } from 'url';
+
+/* Разбор модуля: один рабочий поток на прогон вместо запуска Node на каждую
+ * клетку.
+ *
+ * Зачем. Гард компиляции обязан понимать модуль (`import`/`export` в `.js` —
+ * обычное дело у проекта с бандлером, см. `strip.js`), а единственный разбор
+ * модуля без исполнения — `vm.SourceTextModule` — живёт только под флагом
+ * `--experimental-vm-modules`, которого у процесса нет. Раньше это решалось
+ * запуском `node --check` на каждую клетку: 97 мс на запуск и минуты на истории,
+ * где модуль меняется каждым коммитом.
+ *
+ * Как. Поток поднимается при первом модуле и живёт до конца прогона, поэтому
+ * скриптовые проекты за него не платят вовсе. Обмен синхронный — измерение
+ * истории синхронное: запрос уходит `postMessage`, готовность ответа отмечается
+ * в `SharedArrayBuffer`, а ответ забирается `receiveMessageOnPort` (тот же приём,
+ * что в примере Node для синхронного канала в поток). Поток `unref`-нут: команда
+ * заканчивается вместе со своей работой, а не вместе с потоком.
+ *
+ * Чем платит. Старт потока — разовая цена (~55 мс на машине замера), и разбор
+ * опирается на экспериментальный API: флаг `--experimental-vm-modules` передаётся
+ * самому потоку, поэтому команда пользователя не меняется. Текст передаётся в
+ * поток копией — на файлах в десятки мегабайт это десятки миллисекунд, всё ещё
+ * дешевле запуска процесса.
+ *
+ * Куда отступает. К запуску `node --check` — медленнее, но не мягче: когда файла
+ * потока нет (неполная упаковка), когда поток не ответил за отведённое время
+ * (умер) и когда в потоке не оказалось `vm.SourceTextModule` (Node без модулей
+ * vm). Отступление молчаливое: сломавшийся быстрый путь стоит секунд, а не
+ * правильности, и его место стережёт проверка способа разбора (`parseMode`).
+ */
+
+const WORKER_FILE = fileURLToPath(new URL('./parse-worker.js', import.meta.url));
+const FLAGS = ['--experimental-vm-modules', '--no-warnings'];
+const WAIT_MS = 2000;
+
+let parser = null;      // живой поток { worker, port, sig } или null
+let hopeless = false;   // поток не поднялся: второй раз не пробуем
+let seq = 0;
+let mode = null;        // 'thread' | 'node' — чем разобран последний модуль
+
+/* Причина, по которой текст не разбирается как модуль, или null, если
+ * разбирается. «Не удалось проверить» наружу не выходит никогда: разбор без
+ * потока уходит в `node --check`, а он отвечает тем же — причиной или её
+ * отсутствием. */
+export function moduleError(text) {
+  const fromThread = inThread(text);
+  if (fromThread !== undefined) {
+    mode = 'thread';
+    return fromThread;
+  }
+  mode = 'node';
+  return onNodeCheck(text);
+}
+
+/* Способ разбора последнего модуля. Нужен, чтобы быстрый путь не деградировал
+ * молча: проверка утверждает, что на проекте с модулями он действительно поток,
+ * а не прежний запуск. */
+export function parseMode() {
+  return mode;
+}
+
+function inThread(text) {
+  const live = start();
+  if (!live) return undefined;
+  const id = ++seq;
+  // Сначала ноль в том же слове, которым поток отмечает готовность: ответ,
+  // пришедший раньше ожидания, иначе было бы видно как «ещё не начинали».
+  Atomics.store(live.sig, 0, 0);
+  live.port.postMessage({ id: id, text: text });
+  if (Atomics.wait(live.sig, 0, 0, WAIT_MS) === 'timed-out') return bury();
+  for (;;) {
+    const got = receiveMessageOnPort(live.port);
+    if (!got) return bury();
+    if (got.message.id !== id) continue;   // прежний ответ (поток отвечал не нам)
+    if (got.message.available === false) return bury();
+    return got.message.error === null ? null : String(got.message.error);
+  }
+}
+
+function start() {
+  if (parser || hopeless) return parser;
+  if (!fs.existsSync(WORKER_FILE)) {
+    hopeless = true;
+    return null;
+  }
+  const sig = new Int32Array(new SharedArrayBuffer(4));
+  const { port1, port2 } = new MessageChannel();
+  try {
+    const worker = new Worker(WORKER_FILE, {
+      execArgv: FLAGS, workerData: { port: port2, sig: sig }, transferList: [port2]
+    });
+    // Без обработчика ошибка потока стала бы исключением процесса, а её место —
+    // в отступлении к запуску.
+    worker.on('error', bury);
+    worker.on('exit', bury);
+    worker.unref();
+    parser = { worker: worker, port: port1, sig: sig };
+  } catch (_e) {
+    hopeless = true;
+  }
+  return parser;
+}
+
+// Поток больше не годится: дальше разбираем запуском, и вернуться уже некуда.
+function bury() {
+  const dead = parser;
+  parser = null;
+  hopeless = true;
+  if (dead) dead.worker.terminate();
+  return undefined;
+}
+
+/* Отступление: `node --check` по временному файлу. Расширение `.mjs` здесь не
+ * косметика — у временного файла нет манифеста, и только расширение говорит
+ * Node, что текст надо читать как модуль. Причина берётся из `stderr`: там
+ * сначала эхо строки с ошибкой, потом сам `SyntaxError` и стек. */
+function onNodeCheck(text) {
+  const tmp = path.join(os.tmpdir(), 'size-table-guard-' + process.pid + '-mod.mjs');
+  try {
+    fs.writeFileSync(tmp, text);
+    execFileSync(process.execPath, ['--check', tmp], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return null;
+  } catch (e) {
+    const lines = String((e && e.stderr) || (e && e.message) || e).split('\n')
+      .map((l) => l.trim()).filter((l) => l !== '');
+    return lines.find((l) => /^\w*Error\b/.test(l)) || lines[0] || 'модуль не разбирается';
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}

package/src/refusal.js

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { TOOL_PKG } from './tool.js';
+
+/* Отказ и справка: код выхода, сообщение с готовой командой починки и текст
+ * «--help». Стоит ниже всех в цепочке — ни о настройках, ни о git не знает,
+ * поэтому его может звать любой модуль. */
+
+// Пакет — модуль, а подсказка в `loadConfig` цитирует путь самого движка: в ESM
+// `__filename` нет, поэтому путь берётся от `import.meta.url`.
+const __filename = fileURLToPath(import.meta.url);
+
+/* Отказ — это код выхода и одна строка с готовой командой починки: по коду
+ * ветвится агент (таблица кодов в `PLAN.md` §4.1), по тексту — человек. Стек
+ * наружу не отдаётся вовсе: подсказки в нём нет, зато есть пути машины. */
+export const EXIT = { OK: 0, VIOLATION: 1, CONFIG: 2, SHALLOW: 3, SENSOR: 4, INTERNAL: 5 };
+
+export class Refusal extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function refuse(code, message) {
+  throw new Refusal(code, message);
+}
+
+/* Причины отказа кодом 2 — одним списком, и он единственное место, где они
+ * перечислены словами: справка печатает их из него, таблица кодов в `README.md`
+ * сверяется с ним проверкой (`test/docs-commands.test.js`), а `refuseCause` не
+ * пропускает отказ, не назвавший причины. Поэтому «в документации сказано
+ * меньше, чем бывает» здесь не может случиться молча. Группы — по тому, откуда
+ * причина: разбор вызова, настройки и проект, история, хук, измерение. */
+export const CONFIG_CAUSES = [
+  ['командная строка', [
+    'незнакомый ключ', 'ключ без значения', 'повтор ключа', 'два режима сразу',
+    'лишнее слово', 'команда и режим', 'неизвестная команда', 'несовместимый ключ',
+    'нет ответа в JSON', 'два ответа сразу', 'нет коммита'
+  ]],
+  ['настройки и проект', [
+    'нет файла настроек', 'настройки не разобраны', 'настройки неверны',
+    'нет git', 'не git-репозиторий', 'конфиг уже есть'
+  ]],
+  ['история', ['нет такого коммита', 'коммит назван неточно', 'коммит вне истории']],
+  ['хук', ['чужой хук', 'чужой core.hooksPath', 'нечем звать инструмент']],
+  ['измерение', ['файл не JavaScript', 'минификатор не разобрал']]
+];
+
+/* Причина — объявленное имя, а не украшение текста: неназванная не доедет до
+ * пользователя, потому что это дефект инструмента, а не тупик человека. */
+export function refuseCause(cause, message) {
+  if (!CONFIG_CAUSES.some((g) => g[1].indexOf(cause) >= 0)) {
+    throw new Error('причина отказа не объявлена: ' + cause);
+  }
+  refuse(EXIT.CONFIG, message);
+}
+
+/* Строки справки про причины — из того же списка, поэтому справка не может
+ * разойтись с проверками. */
+const CAUSE_LINES = CONFIG_CAUSES.map((g) => '  ' + g[0] + ': ' + g[1].join(' · '));
+
+/* Как инструмент вызывается там, где его читают. Совет называет то, что лежит
+ * рядом, и никогда — имя пакета: `npx <имя>` запускает установленный пакет, только
+ * пока тот на месте, а в проекте без него имя уходит в реестр и запускает чужой
+ * пакет с тем же именем — текст, который должен выручать, приводит к чужому коду.
+ * Поэтому форма одна: путь внутри проекта (`node node_modules/<имя>/bin/size.js`) —
+ * в проекте с пакетом она работает, без пакета отказывает на месте и в сеть не идёт.
+ *
+ * Команда починки цитирует точку входа, а не сам движок: при импорте движок ничего
+ * не запускает, поэтому `--init` работает только через команду. Путь в репозитории
+ * пакета считается от места движка, а не от текущего каталога, — сообщение обязано
+ * работать из любого места проекта. */
+export function invocation() {
+  const local = path.join('node_modules', TOOL_PKG.name, 'bin', 'size.js');
+  if (fs.existsSync(path.resolve(process.cwd(), local))) return 'node ' + local;
+  const bin = path.resolve(path.dirname(__filename), '..', 'bin', 'size.js');
+  const shown = path.relative(process.cwd(), bin);
+  return 'node ' + (shown === '' || shown.indexOf('..') === 0 ? bin : shown);
+}
+
+export function cliCommand(flag) {
+  return invocation() + ' ' + flag;
+}
+
+/* Путь внутри готовой команды: пробел или кавычка в нём сломали бы копирование,
+ * поэтому такой путь берётся в кавычки — так его и приняла бы оболочка. */
+export function advicePath(p) {
+  return /[\s"'$`\\]/.test(p) ? JSON.stringify(p) : p;
+}
+
+export const USAGE = [
+  '@vernikr/size-report — таблица объёма файлов по коммитам.',
+  '',
+  'Запуск: ' + invocation() + ' [команда] [режим] [ключи]',
+  '',
+  'Команды:',
+  '  check [--json]    полнота: настройки, история, пути, датчики (код 1 — путь',
+  '                    истории не отслеживается и не объявлен исключением)',
+  '  explain <коммит>  почему у коммита нет строки (имя ревизии, sha или его начало)',
+  '  doctor [--json]   диагностика одним ответом: окружение, зависимости, настройки,',
+  '                    покрытие (код 0 — делать нечего, иначе — первый по важности)',
+  '  install-hook      поставить хуки post-commit и post-merge: отчёт пересобирается',
+  '                    сам после каждого коммита и слияния, а если он в git — ложится',
+  '                    отдельным коммитом',
+  '  uninstall-hook    убрать хук и его состояние (проект возвращается к прежнему)',
+  '  hook-run          то, что зовёт хук: пересборка и коммит отчёта (вручную не нужно)',
+  '',
+  'Режимы:',
+  '  --init [файл]   черновик настроек (--force — перезаписать существующий)',
+  '  --write         собрать таблицу в файл из настроек',
+  '  --data          данные контракта в stdout — для страницы и для агента',
+  '  --page [файл]   страница отчёта (по умолчанию рядом с таблицей)',
+  '  --json          прежняя форма данных в stdout',
+  '  (без режима)    проверить, что таблица совпадает с историей',
+  '',
+  'Ключи: --config <файл> — другие настройки; --help — эта справка.',
+  '',
+  '--json — форма ответа, а не отдельный режим, и правило у него одно: ответ бывает',
+  'ровно у четырёх вызовов. Без команды это прежняя форма данных, у check, explain',
+  'и doctor — их ответ; у остального ответа нет, и там --json — отказ, а не тишина.',
+  '',
+  'Запуск один: команда и режим не совмещаются, режим тоже один, и лишнее слово',
+  'вместе с незнакомым ключом — отказ с готовой командой, а не обычный прогон.',
+  '',
+  'Коды выхода: 0 — всё хорошо, 1 — расхождение с историей или неполнота, 2 — вызов,',
+  'настройки или окружение, 3 — неполная история, 4 — нет датчика, 5 — внутренняя',
+  'ошибка. У doctor свой порядок: 2, 3, 1, 4 — по важности находки, а не по тому,',
+  'что нашлось первым.',
+  '',
+  'Причины отказа кодом 2 (их же называет таблица кодов в README.md):'
+].concat(CAUSE_LINES, ['']).join('\n');

package/src/render.js

@@ -0,0 +1,131 @@
+import { fill, LOCALES } from './locales.js';
+import { METRICS, metricView } from './metrics.js';
+import { rowHref } from './journal.js';
+import { cellParts, commitParts, nowModel, rowModel, valueParts } from './derived.js';
+import { ARTIFACT_CSS, TABLE_CSS } from './css.js';
+
+/* Статический отчёт: стили, разметка клетки и таблицы, примечание. Производные
+ * величины берёт из общего расчёта («derived.js») — того же, который исполняет
+ * страница. */
+
+/* Оформление артефакта — своё плюс общая часть таблицы: ровно тот же текст
+ * таблицы получает и страница, поэтому оформление самой таблицы у двух отчётов
+ * одно. Что именно входит в каждую часть — в `src/css.js`. */
+const CSS = ARTIFACT_CSS + '\n' + TABLE_CSS;
+
+export function esc(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/* Разметка клетки строки-коммита: правила — в `cellParts`, здесь только тег и
+ * классы. Клетка-дельта: абсолютные числа стоят один раз в верхней строке, иначе
+ * крупное число повторялось бы в каждой строке и колонки расползались бы. */
+export function cellHtml(cell, first) {
+  const parts = cellParts(cell.value, cell.delta, '-');
+  const cls = 'num' + (first ? ' g' : '') + (parts.miss ? ' miss' : '');
+  if (parts.dir === null) return '<td class="' + cls + '">' + parts.text + '</td>';
+  return '<td class="' + cls + '"><span class="delta ' + parts.dir + '">' + parts.text + '</span></td>';
+}
+
+// Разметка клетки верхней строки: правила — в `valueParts`.
+export function valueHtml(value, first) {
+  const parts = valueParts(value);
+  return '<td class="num' + (first ? ' g' : '') + (parts.miss ? ' miss' : '') + '">' + parts.text + '</td>';
+}
+
+function commitCell(row, index, cfg) {
+  const loc = LOCALES[cfg.locale];
+  const parts = commitParts(row, cfg.rows.sha, rowHref(row.section, row.sha, cfg));
+  const when = '<span class="when">' + esc(parts.when) + '</span>';
+  const title = esc(parts.title);
+  const plain = row.section === null && parts.href === null;
+  const body = parts.href
+    ? '<a class="subj" title="' + title + '" href="' + esc(parts.href) + '">' + esc(parts.subject) + '</a>'
+    : '<span class="subj' + (plain ? ' plain' : '') + '" title="' + title + '">' + esc(parts.subject) + '</span>';
+  const markTitle = parts.mark.title === null
+    ? (cfg.journal ? fill(loc.note.noJournalMark, { journal: cfg.journal.path }) : loc.note.noJournal)
+    : parts.mark.title;
+  const id = cfg.rows.sha ? 'c-' + row.sha.slice(0, 7) : 'c-' + (index + 1);
+  return '<th class="c-commit" id="' + id + '">'
+    + '<div class="clip">' + when + body
+    + '<span class="sect" title="' + esc(markTitle) + '">' + esc(parts.mark.text) + '</span>'
+    + '</div></th>';
+}
+
+export function noteText(rows, cfg) {
+  const loc = LOCALES[cfg.locale];
+  const metrics = cfg.metrics.map((m) => {
+    const view = metricView(m, cfg);
+    return '<b>' + view.label + '</b> — ' + view.note;
+  }).join(loc.note.metricSep);
+  const journal = cfg.journal ? loc.note.journal : loc.note.noJournal;
+  return loc.note.intro + metrics + loc.note.metricEnd + fill(loc.note.numbers, { now: loc.now })
+    + (cfg.journal ? fill(journal, { journal: cfg.journal.path }) : journal)
+    + fill(loc.note.columns, { columns: cfg.columns.map((c) => c.label).join(', ') })
+    + fill(loc.note.rows, { rows: rows.length, command: cfg.fixCommand });
+}
+
+export function render(rows, cfg) {
+  const loc = LOCALES[cfg.locale];
+  const metrics = cfg.metrics;
+  const groupHead = (label, cls) => '<th colspan="' + metrics.length + '" class="' + cls + '">' + esc(label) + '</th>';
+  const subHead = () => metrics.map((m, i) => '<th' + (i === 0 ? ' class="g"' : '') + '>'
+    + esc(METRICS[m].label) + '</th>').join('');
+  const head = '<tr>'
+    + '<th rowspan="2" class="c-commit">' + esc(loc.commit) + '</th>'
+    + groupHead(loc.total, 'g')
+    + cfg.columns.map((c) => groupHead(c.label, 'g')).join('')
+    + '</tr>\n<tr>'
+    + subHead()
+    + cfg.columns.map(() => subHead()).join('')
+    + '</tr>';
+
+  /* Дельта считается к предыдущему коммиту (в списке ниже он идёт строкой ниже),
+   * а появление файла — рост на весь его объём: иначе сумма дельт по колонке не
+   * сходилась бы с текущим размером, и верхняя строка была бы недоказуемой. Всё
+   * это считает `rowModel` — тот же, что и на странице. */
+  const cellsHtml = (make) => (cells) => cells.map((c, mi) => make(c, mi === 0)).join('');
+  const rowCells = cellsHtml((c, first) => cellHtml(c, first));
+  const nowCells = cellsHtml((v, first) => valueHtml(v, first));
+  const blocksHtml = (model, one) => one(model.total) + model.files.map(one).join('');
+  const body = rows.map((row, i) => {
+    const prev = i === 0 ? null : rows[i - 1];
+    return '<tr>' + commitCell(row, i, cfg)
+      + blocksHtml(rowModel(row.cells, prev === null ? null : prev.cells, metrics), rowCells)
+      + '</tr>';
+  }).reverse().join('\n');
+
+  const nowRow = rows.length === 0 ? '' : '<tr class="now">'
+    + '<th class="c-commit">' + esc(loc.now) + '</th>'
+    + blocksHtml(nowModel(rows[rows.length - 1].cells, metrics), nowCells)
+    + '</tr>';
+
+  /* Подпись называет только то, что не меняется от самих служебных коммитов:
+   * число строк и список колонок. Иначе таблица считалась бы устаревшей сразу
+   * после собственного коммита — из-за пересчитанного «пропущено N» в тексте. */
+  return `<!doctype html>
+<html lang="${loc.html}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(cfg.title || loc.heading)}</title>
+<style>
+${CSS}
+</style>
+</head>
+<body>
+<h1>${esc(cfg.heading || loc.heading)}</h1>
+<p class="note">${noteText(rows, cfg)}</p>
+<table>
+<thead>
+${head}
+</thead>
+<tbody>
+${nowRow}
+${body}
+</tbody>
+</table>
+</body>
+</html>
+`;
+}

package/src/size-table.js

@@ -0,0 +1,86 @@
+/* Таблица объёма файлов по коммитам — переносимый генератор.
+ *
+ * Зачем. Объём проекта обсуждается числами регулярно (здесь — WORKLOG §19–§21),
+ * и каждый раз это был ручной замер двух ревизий. Генератор делает замер
+ * непрерывным: строка — коммит, колонка — файл, в клетке — изменение к
+ * предыдущему коммиту по каждой метрике (`raw` — файл как он есть,
+ * `min` — форма без комментариев и отступов), а абсолютные размеры стоят один
+ * раз, в верхней строке «сейчас» (иначе крупное число повторялось бы в каждой
+ * строке, и колонки расползались бы на экраны вширь).
+ *
+ * Источник правды — сам git: размеры берутся из блобов коммитов, а не из
+ * рабочего дерева. Поэтому таблица не зависит от того, что открыто в редакторе,
+ * и собирается заново по всей истории, а не дописывается инкрементально
+ * (инкрементальный файл пришлось бы чинить после любой правки старых чисел).
+ *
+ * **Проектное — в конфиге, механика — в пакете.** Движок не знает ни имён файлов
+ * проекта, ни имени журнала, ни языка подписей: колонки, метрики, журнал,
+ * локаль, куда писать — всё в `size-table.config.json` рядом с корнем
+ * репозитория (`--config` — другой путь). Поэтому пакет подключается к новому
+ * проекту как зависимость, а `size --init` подбирает там черновик конфига
+ * (какие расширения в проекте, где журнал, куда писать), который дальше
+ * правится глазами.
+ *
+ * Строку получает коммит, сдвинувший хотя бы одно число, включая merge: у
+ * слияния берётся дифф к первому родителю, поэтому его правки видны и в строке,
+ * и в переносе состояния. Не получают строку коммиты, тронувшие лишь сам файл
+ * таблицы (и всё, что перечислено в `skip`) — строка про коммит не может лежать
+ * внутри самого коммита (sha на момент сборки ещё неизвестен), поэтому
+ * обновление таблицы — отдельный коммит, — и коммиты, у которых все клетки
+ * вышли нулевыми (слияние, разрешённое ровно в то, что уже дала ветка): строка
+ * без единого числа читается как поломка. Отсюда же
+ * требование к конфигу: колонки обязаны покрывать всё, что коммит может
+ * изменить. Коммит мимо колонок дал бы строку без единого числа, а пустая
+ * клетка в таблице означает «файла в этой ревизии ещё нет» — читается как
+ * поломка (это стережёт тест).
+ * Если в конфиге выключить sha в строках (`rows.sha: false`), тот же инвариант
+ * начинает работать и для стратегии «пересобрать и дописать в тот же коммит»:
+ * без sha артефакт становится неподвижной точкой сборки.
+ *
+ * Запуск (из любого места репозитория; `size` — когда пакет установлен, иначе
+ * `node bin/size.js`):
+ *   size                    проверка: таблица совпадает с историей (CI)
+ *   size --write            перегенерировать таблицу
+ *   size --json             строки как JSON в stdout
+ *   size --data             данные для страницы и агента в stdout
+ *   size --page [файл]      собрать страницу отчёта
+ *   size --init [файл]      черновик конфига для нового проекта
+ *   size --config <путь>    другой файл настроек
+ *   size --help             справка и коды выхода
+ *
+ * Требуется полная история: на обрезанном клоне (shallow) скрипт отказывается
+ * работать, а не пишет молча короткую таблицу. В CI — `fetch-depth: 0`.
+ */
+
+/* Точка входа пакета — и только она: здесь нет ни одного расчёта, только
+ * реэкспорт. Механика разложена по швам, которые видно по зависимостям:
+ *
+ *   refusal, locales, journal, tool, css, derived        — ни на чём не стоят;
+ *   parse → parse-worker                               — разбор модуля вне процесса;
+ *   strip → refusal, parse                             — снятие балласта и гард;
+ *   metrics → strip                                    — реестр метрик;
+ *   git → refusal                                      — всё, что читается у git;
+ *   config → git, refusal, locales, metrics, data      — настройки проекта;
+ *   history → git, metrics, journal, refusal           — сборка по истории;
+ *   data → locales, metrics, journal, history, tool    — контракт со страницей;
+ *   render → locales, metrics, journal, derived        — статический артефакт;
+ *   page/build → locales, render                       — страница отчёта;
+ *   cli → все                                          — режимы и разбор ключей.
+ *
+ * Публичный API — то, чем пользуются `bin/size.js` и `test/`: список ниже не
+ * сокращается при разбиении (это проверяет `test/api.test.js`).
+ */
+export { main, initMode, sniffColumns, check, dataMode, pageMode } from './cli.js';
+export { reportData, categoryOf, CATEGORY_EXTS, CATEGORY_ORDER } from './data.js';
+export { measureHistory } from './history.js';
+export { render, noteText, cellHtml, valueHtml } from './render.js';
+export { pageHtml, pageScript, pageSource, stripModules } from './page/build.js';
+export { measureBlob, METRICS } from './metrics.js';
+export { minifyForm, strategyFor, stripCss, stripHtml, stripJs, stripLines, compactJson,
+  STRATEGIES } from './strip.js';
+export { parseSections, touchedSection, anchor, sectionLink, rowHref } from './journal.js';
+export { argValue, gitRoot, loadConfig, validateConfig, CONFIG_NAME, DEFAULT_CONFIG } from './config.js';
+export { assertFullHistory, blobAt, readBlobs, readHistory } from './git.js';
+export { LOCALES } from './locales.js';
+export { EXIT, Refusal, refuse, cliCommand, USAGE } from './refusal.js';
+export { cellParts, commitParts, deltaOf, group, nowModel, rowModel, totalsOf, valueParts } from './derived.js';