@vernikr/size-report 1.2.0 → 1.3.0

package/src/history.js

@@ -36,112 +36,129 @@ function changesVolume(state, before, columns, metrics) {
   });
 }
 
-/* Проход по истории. Состояние колонки переносится вперёд, а перезамер делается
- * только для изменившихся в коммите файлов. Читается всё сразу: сначала план
- * «какие пары ревизия:путь понадобятся», затем один поход в git (`readBlobs`),
- * затем собственно измерение — иначе на каждый коммит приходилось бы по
- * git-вызову на колонку. Значения метрик кэшируются по sha блоба: ревизия с тем
- * же содержимым (откат, повторный merge) не пересчитывается.
- *
- * `known` — уже прочитанная история: проходам, которым она нужна ещё и сама по
- * себе (полнота покрытия), незачем звать `git log` второй раз. */
-export function measureHistory(cfg, root, known) {
-  const commits = known === undefined ? readHistory(root) : known;
-  const metrics = cfg.metrics;
-  // Текст журнала нужен всегда: ссылка в раздел — не метрика, но тоже чтение.
-  const needText = !!cfg.journal || metrics.some((m) => METRICS[m].needsText);
-  const skipPaths = [cfg.output].concat(cfg.skip || []);
-  const state = cfg.columns.map(() => null);
-  const rows = [];
-  const dropped = [];
-  const mixed = [];
-  let journalPrev = '';
-
+/* План чтения: какие пары «ревизия:путь» понадобятся и всё содержимое сразу — иначе
+ * на каждый коммит приходилось бы по git-вызову на колонку. Псевдонимов колонки,
+ * которых коммит коснулся, может быть и два: при выключенном распознавании
+ * переименований git отдаёт в одном коммите и старое имя, и новое. Собираются все —
+ * какой из них в коммите действительно есть, решается потом, по прочитанным блобам. */
+function readPlan(cfg, root, commits, needText) {
   const plan = commits.map((c) => {
     const changed = new Set(c.files);
-    /* Псевдонимов колонки, которых коммит коснулся, может быть и два: при
-     * выключенном распознавании переименований git отдаёт в одном коммите и старое
-     * имя, и новое. Собираются все — какой из них в коммите действительно есть,
-     * решается потом, по прочитанным блобам. */
     const picks = cfg.columns.map((col) => col.paths
       .filter((cand) => changed.has(cand))
       .map((path) => ({ path: path, spec: c.sha + ':' + path })));
     const journal = cfg.journal && changed.has(cfg.journal.path) ? c.sha + ':' + cfg.journal.path : null;
     return { picks: picks, journal: journal };
   });
-
   const specs = [];
   plan.forEach((p) => {
     p.picks.forEach((candidates) => { candidates.forEach((cand) => specs.push(cand.spec)); });
     if (p.journal !== null) specs.push(p.journal);
   });
-  const blobs = readBlobs(root, specs, needText);
+  return { plan: plan, blobs: readBlobs(root, specs, needText) };
+}
 
+/* Замер блоба с памятью на проход: ревизия с тем же содержимым (откат, повторный
+ * merge) не пересчитывается. */
+function measurer(cfg) {
   const measured = new Map(); // sha блоба + метрика → число
-  const measure = (name, blob, file, rev) => {
+  return (name, blob, file, rev) => {
     const key = blob.sha + '\u0000' + name;
     if (measured.has(key)) return measured.get(key);
     const value = measureBlob(name, blob, file, cfg, rev);
     measured.set(key, value);
     return value;
   };
+}
 
-  commits.forEach((c, ci) => {
-    let section = null;
-    if (plan[ci].journal !== null) {
-      const journalBlob = blobs.get(plan[ci].journal);
-      if (journalBlob !== undefined) {
-        section = touchedSection(journalPrev, journalBlob.text, cfg.journal.pattern);
-        journalPrev = journalBlob.text;
-      }
+/* Правки коммита в состояние: из псевдонимов берётся тот, который в коммите есть, а
+ * не первый по порядку настроек, — исчезнувшее имя в коммите отсутствует, и
+ * состояние, взятое по порядку, теряло файл (а сверка с деревом — отказывала). */
+function applyPicks(pass, c, picks) {
+  picks.forEach((candidates, i) => {
+    const pick = candidates.find((cand) => pass.blobs.get(cand.spec) !== undefined);
+    if (pick === undefined) {
+      // Путь в коммите есть, а файла по нему нет — файл удалён.
+      if (candidates.length > 0) pass.state[i] = null;
+      return;
     }
-
-    const before = state.slice();
-    plan[ci].picks.forEach((candidates, i) => {
-      /* Из псевдонимов берётся тот, который в коммите есть, а не первый по
-       * порядку настроек: исчезнувшее имя в коммите отсутствует, и состояние,
-       * взятое по порядку, теряло файл (а сверка с деревом — отказывала). */
-      const pick = candidates.find((cand) => blobs.get(cand.spec) !== undefined);
-      if (pick === undefined) {
-        // Путь в коммите есть, а файла по нему нет — файл удалён.
-        if (candidates.length > 0) state[i] = null;
-        return;
-      }
-      const blob = blobs.get(pick.spec);
-      const cells = {};
-      /* Приближённость числа — свойство пути, а не блоба: от расширения зависит,
-       * возьмёт ли формат минификатор. Поэтому она считается здесь, вместо с
-       * замером, и в кэш содержимого не попадает. */
-      const approx = {};
-      metrics.forEach((m) => {
-        cells[m] = measure(m, blob, pick.path, c.sha);
-        approx[m] = !pointExact(m, pick.path, cfg);
-      });
-      state[i] = { path: pick.path, sha: blob.sha, cells: cells, approx: approx };
+    const blob = pass.blobs.get(pick.spec);
+    const cells = {};
+    /* Приближённость числа — свойство пути, а не блоба: от расширения зависит,
+     * возьмёт ли формат минификатор. Поэтому она считается здесь, вместо с
+     * замером, и в кэш содержимого не попадает. */
+    const approx = {};
+    pass.metrics.forEach((m) => {
+      cells[m] = pass.measure(m, blob, pick.path, c.sha);
+      approx[m] = !pointExact(m, pick.path, pass.cfg);
     });
+    pass.state[i] = { path: pick.path, sha: blob.sha, cells: cells, approx: approx };
+  });
+}
 
-    if (c.parents.length > 1 && !cfg.rows.merges) { dropped.push({ sha: c.sha, reason: 'merge' }); return; }
-    if (c.files.length > 0 && c.files.every((f) => skipPaths.indexOf(f) >= 0)) {
-      dropped.push({ sha: c.sha, reason: 'report' });
-      return;
+/* Один коммит прохода: сдвиг состояния, затем — нужна ли коммиту строка. `pass`
+ * общий на весь проход (состояние, списки, память замеров), поэтому функция только
+ * двигает его вперёд. */
+function stepCommit(pass, c, ci) {
+  const plan = pass.plan[ci];
+  let section = null;
+  if (plan.journal !== null) {
+    const journalBlob = pass.blobs.get(plan.journal);
+    if (journalBlob !== undefined) {
+      section = touchedSection(pass.journalPrev, journalBlob.text, pass.cfg.journal.pattern);
+      pass.journalPrev = journalBlob.text;
     }
-    if (!changesVolume(state, before, cfg.columns, metrics)) {
-      dropped.push({ sha: c.sha, reason: 'flat' });
-      return;
-    }
-    if (c.files.some((f) => f === cfg.output)) mixed.push(c.sha.slice(0, 7));
+  }
 
-    rows.push({
-      sha: c.sha,
-      when: c.when,
-      subject: c.subject,
-      section: section,
-      cells: state.map((s) => (s === null ? null : s.cells)),
-      approx: state.map((s) => (s === null ? null : s.approx))
-    });
+  const before = pass.state.slice();
+  applyPicks(pass, c, plan.picks);
+
+  if (c.parents.length > 1 && !pass.cfg.rows.merges) { pass.dropped.push({ sha: c.sha, reason: 'merge' }); return; }
+  if (c.files.length > 0 && c.files.every((f) => pass.skipPaths.indexOf(f) >= 0)) {
+    pass.dropped.push({ sha: c.sha, reason: 'report' });
+    return;
+  }
+  if (!changesVolume(pass.state, before, pass.cfg.columns, pass.metrics)) {
+    pass.dropped.push({ sha: c.sha, reason: 'flat' });
+    return;
+  }
+  if (c.files.some((f) => f === pass.cfg.output)) pass.mixed.push(c.sha.slice(0, 7));
+
+  pass.rows.push({
+    sha: c.sha,
+    when: c.when,
+    subject: c.subject,
+    section: section,
+    cells: pass.state.map((s) => (s === null ? null : s.cells)),
+    approx: pass.state.map((s) => (s === null ? null : s.approx))
   });
+}
 
-  return { rows, dropped, mixed, state };
+/* Проход по истории. Состояние колонки переносится вперёд, а перезамер делается
+ * только для изменившихся в коммите файлов.
+ *
+ * `known` — уже прочитанная история: проходам, которым она нужна ещё и сама по
+ * себе (полнота покрытия), незачем звать `git log` второй раз. */
+export function measureHistory(cfg, root, known) {
+  const commits = known === undefined ? readHistory(root) : known;
+  // Текст журнала нужен всегда: ссылка в раздел — не метрика, но тоже чтение.
+  const needText = !!cfg.journal || cfg.metrics.some((m) => METRICS[m].needsText);
+  const reads = readPlan(cfg, root, commits, needText);
+  const pass = {
+    cfg: cfg,
+    metrics: cfg.metrics,
+    plan: reads.plan,
+    blobs: reads.blobs,
+    measure: measurer(cfg),
+    skipPaths: [cfg.output].concat(cfg.skip || []),
+    state: cfg.columns.map(() => null),
+    rows: [],
+    dropped: [],
+    mixed: [],
+    journalPrev: ''
+  };
+  commits.forEach((c, ci) => stepCommit(pass, c, ci));
+  return { rows: pass.rows, dropped: pass.dropped, mixed: pass.mixed, state: pass.state };
 }
 
 /* Сверка с рабочим деревом отвечает на два вопроса, и оба обязательны: состояние

package/src/hook.js

@@ -286,7 +286,8 @@ function record(root, fields, note) {
  * Подпись коммита не спрашивается: настройка машины не должна останавливать коммит.
  * Дешёвый индекс здесь — временный: настоящий трогается один раз, и только в записи
  * об отчёте, иначе после коммита дерево было бы грязным. */
-function commitReport(root, rel, file, message, branch, head) {
+function commitReport(root, job) {
+  const { rel, file, message, branch, head } = job;
   const fail = (why) => ({ ok: false, why: why });
   const blob = gitTry(root, ['hash-object', '-w', '--', file]);
   if (blob.status !== 0) return fail('git hash-object: ' + blob.stderr.trim());
@@ -374,31 +375,36 @@ function runLocked(root, configFile, sha) {
       '✗ size-report: внутренняя ошибка: ' + e.stack);
   }
 
-  const rel = path.relative(root, out.file);
+  return storeReport(root, cfg, branch, sha, out.file);
+}
+
+/* Запись отчёта после пересборки: не отслеживается — сказать словами, не
+ * изменился — ничего не делать, изменился — закоммитить. */
+function storeReport(root, cfg, branch, head, file) {
+  const rel = path.relative(root, file);
   if (gitTry(root, ['ls-files', '--error-unmatch', '--', rel]).status !== 0) {
     return record(root, {
       result: 'rebuilt',
-      head: sha,
+      head: head,
       report: cfg.output,
       why: 'отчёт не отслеживается git: пересобран, коммита нет'
     });
   }
   const diff = gitTry(root, ['diff', '--quiet', 'HEAD', '--', rel]);
   if (diff.status === 0) {
-    return record(root, { result: 'unchanged', head: sha, report: cfg.output });
+    return record(root, { result: 'unchanged', head: head, report: cfg.output });
   }
   if (diff.status !== 1) {
-    return record(root, { result: 'failed', head: sha, report: cfg.output, why: 'git diff: ' + diff.stderr.trim() },
+    return record(root, { result: 'failed', head: head, report: cfg.output, why: 'git diff: ' + diff.stderr.trim() },
       '✗ size-report: git diff -- ' + rel + ': ' + diff.stderr.trim());
   }
 
-  const message = 'chore(report): отчёт пересобран после ' + sha.slice(0, 7);
-  const commit = commitReport(root, rel, out.file, message, branch, sha);
+  const message = 'chore(report): отчёт пересобран после ' + head.slice(0, 7);
+  const commit = commitReport(root, { rel: rel, file: file, message: message, branch: branch, head: head });
   if (!commit.ok) {
-    return record(root, { result: 'refused', head: sha, report: cfg.output, why: commit.why },
+    return record(root, { result: 'refused', head: head, report: cfg.output, why: commit.why },
       '✗ size-report: коммит отчёта не прошёл: ' + commit.why);
   }
-  const made = commit.sha;
-  return record(root, { result: 'committed', head: sha, report: cfg.output, commit: made },
-    '✓ size-report: ' + cfg.output + ' пересобран и закоммичен (' + made + ')');
+  return record(root, { result: 'committed', head: head, report: cfg.output, commit: commit.sha },
+    '✓ size-report: ' + cfg.output + ' пересобран и закоммичен (' + commit.sha + ')');
 }

package/src/init.js

@@ -0,0 +1,75 @@
+import fs from 'fs';
+import path from 'path';
+import { CONFIG_NAME, derivedProfile, validateConfig } from './config.js';
+import { advicePath, cliCommand, refuseCause } from './refusal.js';
+import { writeFileEnsured } from './artifact.js';
+import { packageManager } from './project.js';
+
+/* Закрепление настроек файлом (`--init`): то, что проект вывел о себе сам
+ * (`src/project.js`), записывается туда, где его встретит следующий запуск.
+ *
+ * Отдельным модулем от вывода профиля: тот смотрит на проект впервые и почти всё о
+ * нём угадывает, а этот делает одну вещь — кладёт результат файлом и говорит, что
+ * записал. Требование к себе одно и оно жёсткое: **закреплённое обязано проходить
+ * ту же проверку, которой его встретит первый запуск** — иначе подсказка приводит
+ * человека в новый тупик (BLOCKERS §N2, REFACTOR R-0.4).
+ */
+
+/* Что сказать после записи: тем же порядком, что и раньше, — что записано, чем
+ * заменятся приближения и что делать дальше. Строки собираются списком, а не
+ * печатаются по ходу: тогда «что сказано» читается целиком. */
+function draftLines(root, target, cfg) {
+  const hasPkg = fs.existsSync(path.join(root, 'package.json'));
+  const manager = packageManager(root);
+  return [
+    '✓ настройки выведены из проекта и закреплены: ' + path.relative(root, target),
+    '  колонок: ' + cfg.columns.length + ' (' + cfg.columns.map((c) => c.label).slice(0, 6).join(', ')
+      + (cfg.columns.length > 6 ? ', …' : '') + ')',
+    '  исключено путей: ' + cfg.skip.length + ' (сам отчёт, замки зависимостей, карты, собранное)',
+    '  метрика min: настоящее сжатие (esbuild); без него — честное упрощение и код 4',
+    '  метрика tok: словарь o200k_base (gpt-tokenizer); без него — оценка по длине и код 4',
+    '  журнал: ' + (cfg.journal === null ? 'не найден — ссылки строк будут без разделов' : cfg.journal.path),
+    '  дальше: правьте колонки и метрики — какие файлы важны, знает только проект',
+    '          ' + (hasPkg
+      ? 'добавьте в package.json "sizes": "size --write" — тогда отчёт будет звать '
+        + manager + ' run sizes (проверка — без --write)'
+      : 'запуск: ' + cfg.fixCommand + ' (проверка — без --write)'),
+    '          ' + (hasPkg ? 'добавьте ' + manager + ' run test:sizes в CI' : 'добавьте проверку в CI')
+      + '; проверка — команда пакета, своих файлов в проект она не приносит'
+  ];
+}
+
+/* Пустой профиль — не отказ, а примечание: работа сделана, а колонки за человека не
+ * выберет никто. Поэтому «!», а не «✗»: знак и код выхода не имеют права говорить
+ * разное (каталог отказов считает такие знаки отдельно). */
+function noteNoColumns(root, target, cfg) {
+  if (cfg.columns.length > 0) return;
+  console.error('! в проекте не нашлось путей, которые можно взять колонками'
+    + ' (история пуста или в ней нет знакомых расширений): черновик записан без колонок'
+    + '\n  впишите их руками в ' + path.relative(root, target)
+    + ' — без колонок проверка настроек скажет «не задано ни одной колонки»');
+}
+
+export function initMode(root, file, force) {
+  const target = file ? path.resolve(root, file) : path.join(root, CONFIG_NAME);
+  if (fs.existsSync(target) && !force) {
+    // Совет называет тот же файл, о котором шла речь: `--init --force` без файла
+    // перезаписал бы черновиком умолчательное имя, а не тот файл, что человек звал.
+    const name = file === undefined || file === null ? CONFIG_NAME : advicePath(file);
+    refuseCause('конфиг уже есть', 'конфиг уже есть: ' + target
+      + '\n  починка: правьте его или перезапишите черновиком: ' + cliCommand('--init ' + name + ' --force'));
+  }
+  // Закреплённое — то же, чем проект работает без файла (вывод из проекта поверх
+  // умолчаний), и оно же обязано проходить ту же проверку, которой его встретит
+  // запуск: путь в тексте отказа — тот файл, куда оно легло. «Выведено» и «путь
+  // отказа» в файл не пишутся: это свойства не настроек, а того, откуда они взялись.
+  const cfg = derivedProfile(root);
+  if (cfg.columns.length > 0) validateConfig(Object.assign({}, cfg, { path: target }));
+  const written = Object.assign({}, cfg);
+  delete written.path;
+  delete written.derived;
+  writeFileEnsured(target, JSON.stringify(written, null, 2) + '\n');
+  noteNoColumns(root, target, cfg);
+  draftLines(root, target, cfg).forEach((line) => console.log(line));
+  return 0;
+}

package/src/modes.js

@@ -0,0 +1,190 @@
+import fs from 'fs';
+import path from 'path';
+import { EXIT } from './refusal.js';
+import { loadConfig } from './config.js';
+import { byteLen } from './strip.js';
+import { build, skipLine } from './history.js';
+import { reportData, rowShape } from './data.js';
+import { coverage, coverageText } from './check.js';
+import { explainCommit, explainText } from './explain.js';
+import { doctor, doctorText } from './doctor.js';
+import { hookRun, installHook, uninstallHook } from './hook.js';
+import { rebuild, writeFileEnsured } from './artifact.js';
+import { sensorGaps } from './metrics.js';
+import { render } from './render.js';
+import { totalsOf } from './derived.js';
+import { pageHtml } from './page/build.js';
+
+/* Режимы: что инструмент делает по запросу. Разбор аргументов — в `src/args.js`, а
+ * сюда приходит готовый план: какой режим, какой ключ, что печатать. Здесь же их
+ * общие мелочи (знак «!» о другом счёте, вердикт, размер словами) — один владелец
+ * на все режимы, потому что один и тот же счёт и один и тот же знак не должны
+ * разойтись между `--write`, `--data`, `--page` и `size check`.
+ *
+ * Что где: сборка и сверка таблицы (`--write`, проверка), данные и страница
+ * (`--data`, `--page`), полнота покрытия (`size check`), диагностика (`doctor`),
+ * хук и объяснение пропущенной строки. Файл знает про все остальные модули сразу —
+ * это его работа: связать их в одну команду.
+ */
+
+function kmb(bytes) {
+  return Math.round(bytes / 1024) + ' КБ';
+}
+
+/* Деградация — не ошибка, а факт отчёта: числа получены другим счётом (упрощение
+ * вместо сжатия, оценка вместо точного счёта), потому что необязательной
+ * зависимости нет. Факт печатается один раз на датчик и становится кодом 4 — иначе
+ * приближение уезжало бы в CI как успех. */
+function note(gaps) {
+  gaps.forEach((gap) => console.error('! ' + gap.why + '\n  починка: ' + gap.fix));
+  return gaps.length === 0 ? EXIT.OK : EXIT.SENSOR;
+}
+
+function sensorNote(cfg) {
+  return note(sensorGaps(cfg));
+}
+
+/* Вердикт режима вместе с заметками о датчиках: заметка печатается всегда — молчание
+ * о другом счёте читается как точное число, и расхождение остаётся без причины, — а
+ * код остаётся первым по важности. Нарушение старше приближения (тот же порядок, что
+ * у `size check` и у `doctor`): код 4 говорит «числа честные, но другим счётом», а
+ * когда таблица расходится, этого никто не проверял — расхождение может быть и
+ * настоящей правкой мимо отчёта. */
+function verdict(code, gaps) {
+  const sensors = note(gaps);
+  return code === EXIT.OK ? sensors : code;
+}
+
+export function check(cfg, want, root) {
+  const out = path.join(root, cfg.output);
+  if (!fs.existsSync(out)) {
+    console.error('✗ таблица размеров: нет файла ' + cfg.output + ' — соберите её: ' + cfg.fixCommand);
+    return 1;
+  }
+  const have = fs.readFileSync(out, 'utf8');
+  if (have === want) return 0;
+
+  const a = have.split('\n');
+  const b = want.split('\n');
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  console.error('✗ таблица размеров: ' + cfg.output + ' расходится с историей git (строка ' + (i + 1) + '):');
+  console.error('    в файле:    ' + (a[i] === undefined ? '<строк нет>' : a[i].trim().slice(0, 160)));
+  console.error('    по истории: ' + (b[i] === undefined ? '<строк нет>' : b[i].trim().slice(0, 160)));
+  const missing = [...want.matchAll(/id="c-([^"]+)"/g)].map((m) => m[1])
+    .filter((id) => have.indexOf('id="c-' + id + '"') === -1);
+  if (missing.length > 0) {
+    console.error('  строк нет в файле: ' + missing.length + ' (' + missing.slice(0, 5).join(', ')
+      + (missing.length > 5 ? ', …' : '') + ')');
+  }
+  console.error('  починка: ' + cfg.fixCommand + ' — и закоммитить ' + cfg.output + ' отдельным коммитом.');
+  return 1;
+}
+
+export function writeMode(cfg, root) {
+  const { rows, dropped, state, html } = rebuild(cfg, root);
+  console.log('✓ ' + cfg.output + ': ' + rows.length + ' строк × ' + cfg.columns.length + ' файлов, '
+    + kmb(byteLen(html)) + ' (пропущено без строки: ' + dropped.length + ' — '
+    + dropped.map(skipLine).join(', ') + ')');
+  console.log('  состояние на HEAD: ' + cfg.columns.map((c, i) => c.label + ' '
+    + (state[i] === null ? '—' : cfg.metrics.map((m) => state[i].cells[m]).join('/'))).join(', '));
+  return sensorNote(cfg);
+}
+
+export function checkMode(cfg, root) {
+  const { rows } = build(cfg, root);
+  const html = render(rows, cfg);
+  const code = check(cfg, html, root);
+  if (code === 0) {
+    console.log('✓ таблица размеров: ' + rows.length + ' коммитов × ' + cfg.columns.length + ' файлов '
+      + 'совпадает с историей (' + cfg.output + ', ' + kmb(byteLen(html)) + ')');
+  }
+  return verdict(code, sensorGaps(cfg));
+}
+
+/* Ответ команды: `--json` — машинная форма того же ответа, а не второй ответ.
+ * Одна на три команды, чтобы «кто печатает и в каком виде» не разошёлся между
+ * ними: разойтись он может только здесь, а байты ответа — то, чем пользуется
+ * агент. Текст берётся функцией: в машинной форме он не нужен вовсе. */
+function answer(rep, asJson, text) {
+  if (asJson) process.stdout.write(JSON.stringify(rep, null, 2) + '\n');
+  else console.log(text(rep));
+  return rep;
+}
+
+/* Полнота покрытия (`size check`): настройки, история, пути, датчики. Не путать с
+ * `checkMode` выше — тот про таблицу и историю («файл совпадает с тем, что
+ * сосчитано»), а этот про то, что сосчитано **всё**: ни один путь истории не
+ * прошёл мимо колонок. Разные вопросы, поэтому и разные команды: держать отчёт в
+ * git не обязательно, а вот полноту терять нельзя — она той же проверкой и
+ * заменяется. */
+export function coverageMode(cfg, root, configFile, asJson) {
+  const rep = answer(coverage(cfg, root, configFile), asJson, coverageText);
+  return verdict(rep.ok ? EXIT.OK : EXIT.VIOLATION, rep.sensors);
+}
+
+/* Диагностика одним ответом (`size doctor`): окружение, зависимости, настройки и
+ * покрытие — сборкой из тех же кусков, что и остальные режимы. Код выхода — не
+ * «что-то не так», а первый по важности (настройки → история → покрытие →
+ * приближение): по нему агент ветвится, а текст читает человек. */
+export function doctorMode(root, configFile, asJson) {
+  return answer(doctor(root, configFile), asJson, doctorText).exit;
+}
+
+/* Хук: установка, снятие и то, что он зовёт сам. Ставится и снимается только
+ * явной командой; `hook-run` зовётся хуком и всегда отвечает кодом 0 — коммит уже
+ * сделан, и валить его нечем (устройство и причины — `src/hook.js`). Строка о
+ * сделанном идёт в stderr: она часть вывода git, а не данных инструмента. */
+export function hookMode(verb, root, configFile) {
+  if (verb === 'hook-run') {
+    const rep = hookRun(root, configFile);
+    if (rep.note !== '') console.error(rep.note);
+    return rep.code;
+  }
+  const rep = verb === 'install-hook' ? installHook(root, loadConfig(configFile, root)) : uninstallHook(root);
+  rep.lines.forEach((line) => console.log(line));
+  return rep.code;
+}
+
+/* Объяснение пропущенной строки (`size explain <коммит>`): ответ есть у любого
+ * коммита, поэтому код выхода 0 и у «строка есть», и у «строки нет»; 2 — только
+ * когда названного коммита в истории нет или префикс подходит нескольким. */
+export function explainMode(cfg, root, target, asJson) {
+  answer(explainCommit(cfg, root, target), asJson, explainText);
+  return EXIT.OK;
+}
+
+/* Данные контракта в stdout — для страницы и для агента: та же правда, что в
+ * артефакте, но без вёрстки и без производных величин. Прежняя форма `--json`
+ * остаётся нетронутой: она заморожена эталоном паритета (fixtures/parity). */
+export function dataMode(cfg, root) {
+  process.stdout.write(JSON.stringify(reportData(cfg, root), null, 2) + '\n');
+  return sensorNote(cfg);
+}
+
+/* Страница отчёта: собирается тем же проходом по истории, что и артефакт — иначе
+ * два отчёта могли бы показывать разные числа. Файл кладётся рядом с таблицей,
+ * потому что он из неё и растёт. */
+const PAGE_NAME = 'size-report.html';
+
+export function pageMode(cfg, root, file) {
+  const data = reportData(cfg, root);
+  const target = file ? path.resolve(file) : path.join(root, path.dirname(cfg.output), PAGE_NAME);
+  const html = pageHtml(data, cfg);
+  writeFileEnsured(target, html);
+  console.log('✓ ' + path.relative(root, target) + ': ' + data.rows.length + ' строк × '
+    + data.files.length + ' файлов, ' + kmb(byteLen(html)));
+  return sensorNote(cfg);
+}
+
+export function jsonMode(cfg, root) {
+  const { rows, dropped } = build(cfg, root);
+  process.stdout.write(JSON.stringify({
+    columns: cfg.columns.map((c) => ({ label: c.label, paths: c.paths })),
+    metrics: cfg.metrics,
+    rows: rows.map((r) => Object.assign(rowShape(r),
+      { cells: r.cells, totals: totalsOf(r.cells, cfg.metrics) })),
+    skipped: dropped.map(skipLine)
+  }, null, 2) + '\n');
+  return sensorNote(cfg);
+}