@vernikr/size-report 1.1.1

package/src/css.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+
+/* Оформление отчёта — обычные `.css` рядом с кодом, а не строки внутри модулей:
+ * то же правило, что и у программы страницы (`src/page/app.js`), — исходник видит
+ * редактор, а не только шаблонная строка. Читаются они с диска относительно
+ * своего места, поэтому работают и у того, кто поставил пакет.
+ *
+ * Наборов три, и у каждого своя роль:
+ *
+ *   1. `table.css` — **общая часть таблицы**: геометрия клеток, липкие шапка и
+ *      колонка коммита, подпись коммита, цвета дельт. Её берут оба вывода, поэтому
+ *      расхождению в оформлении самой таблицы взяться неоткуда. Файл — дословный
+ *      текст этой части, без шапки: он попадает в артефакт побайтово, а артефакт
+ *      заморожен эталоном паритета, и любая добавленная строка меняла бы
+ *      зафиксированный вывод проекта-потребителя.
+ *   2. `artifact.css` — оформление статического артефакта **сверх таблицы**: холст,
+ *      заголовок, примечание.
+ *   3. `page/app.css` — оформление страницы **сверх таблицы**: холст, панель
+ *      выбора, легенда, состояния пустоты и адаптации под узкое окно.
+ *
+ * Соглашение о цвете дельт задано один раз — в `table.css`: `.up` зелёный, `.down`
+ * красный (рост — «больше логики», а не тревога). Артефакт заморожен побайтово, и
+ * менять его цвета нельзя, не пересняв эталон; страница следует тому же
+ * соглашению, потому что два отчёта одной истории не могут показывать рост
+ * разными цветами. Смена соглашения — две строки в `table.css` и пересъёмка
+ * эталона артефакта; отдельного места у цвета дельт нет намеренно.
+ *
+ * Путь у `readCss` — от каталога `src/`: так его видит движок, где бы он ни лежал.
+ */
+
+export const TABLE_CSS = readCss('./table.css');
+export const ARTIFACT_CSS = readCss('./artifact.css');
+export const PAGE_CSS = readCss('./page/app.css');
+
+function readCss(name) {
+  return fs.readFileSync(new URL(name, import.meta.url), 'utf8').trim();
+}

package/src/data.js

@@ -0,0 +1,105 @@
+import path from 'path';
+import { LOCALES } from './locales.js';
+import { metricView } from './metrics.js';
+import { rowHref } from './journal.js';
+import { build, skipLine } from './history.js';
+import { TOOL_PKG } from './tool.js';
+
+/* Категории файлов и контракт со страницей: абсолютные значения и устройство
+ * таблицы, без единой производной величины. Всё, что страница считает сама,
+ * начинается там, где этот модуль заканчивается. */
+
+/* Категория файла — только для быстрых кнопок «включить/выключить группу» на
+ * странице: на числа она не влияет. Правило одно — расширение даёт категорию, всё
+ * остальное считается кодом; категория, заданная в настройках колонки, старше
+ * правила, и в данных видно, откуда она взялась (`categoryBy`): ручное решение
+ * объяснимо, а таблица расширений — догадка по имени файла. */
+export const CATEGORY_EXTS = {
+  docs: ['.md', '.markdown', '.rst', '.txt', '.adoc'],
+  chore: ['.json', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.conf', '.lock', '.editorconfig'],
+  assets: ['.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.woff', '.woff2', '.ttf', '.otf']
+};
+export const CATEGORY_ORDER = ['code', 'docs', 'chore', 'assets'];
+
+export function categoryOf(col) {
+  if (col.category) return { key: col.category, by: 'config' };
+  const ext = path.extname(col.paths[col.paths.length - 1]).toLowerCase();
+  const known = CATEGORY_ORDER.find((key) => (CATEGORY_EXTS[key] || []).indexOf(ext) >= 0);
+  return { key: known === undefined ? 'code' : known, by: 'auto' };
+}
+
+/* Контракт между движком и страницей: абсолютные значения и устройство таблицы —
+ * и ни одной производной величины. Дельты, суммы, «сейчас» и фильтры считает
+ * страница: движок не знает, что включено в просмотр, поэтому заранее посчитать
+ * сумму он не может. Числа в контракте те же, что в артефакте, — это та же правда,
+ * разложенная по полям.
+ *
+ * Причины пропущенных коммитов идут строками — и остаются ими: у страницы нет
+ * вопроса, на который пригодилось бы поле («почему у коммита нет строки» задают
+ * командой `explain`, и там причина уже разложена). */
+export function reportData(cfg, root) {
+  const { rows, state, dropped } = build(cfg, root);
+  const loc = LOCALES[cfg.locale];
+  const files = cfg.columns.map((col, i) => {
+    const cat = categoryOf(col);
+    return {
+      label: col.label,
+      path: state[i] === null ? null : state[i].path,
+      paths: col.paths,
+      category: cat.key,
+      categoryBy: cat.by
+    };
+  });
+  return {
+    schema: 1,
+    tool: { name: TOOL_PKG.name, version: TOOL_PKG.version },
+    report: {
+      locale: cfg.locale,
+      title: cfg.title || loc.heading,
+      heading: cfg.heading || loc.heading,
+      artifact: cfg.output,
+      fixCommand: cfg.fixCommand,
+      journal: cfg.journal === null ? null : { path: cfg.journal.path },
+      showSha: cfg.rows.sha
+    },
+    metrics: cfg.metrics.map((key) => Object.assign({ key: key }, metricView(key, cfg))),
+    categories: CATEGORY_ORDER.filter((key) => files.some((f) => f.category === key))
+      .map((key) => ({ key: key, label: loc.categories[key] })),
+    files: files,
+    rows: rows.map((r) => ({
+      sha: r.sha,
+      when: r.when,
+      subject: r.subject,
+      section: r.section === null ? null : { id: r.section.id, head: r.section.head, added: r.section.added },
+      href: rowHref(r.section, r.sha, cfg),
+      values: r.cells
+    })),
+    now: state.map((s) => (s === null ? null : s.cells)),
+    approx: approxMarks(rows, state, cfg),
+    skipped: dropped.map(skipLine)
+  };
+}
+
+/* Пометки приближённых клеток — по одной записи на метрику: строка знаков по
+ * клеткам строк и строка знаков по верхней строке «сейчас». '1' — число получено
+ * упрощением или оценкой, '0' — точное. Метрика без ни одной пометки в отчёте не
+ * появляется вовсе: все числа точны — молчание.
+ *
+ * Знак ставит движок там же, где считает число, — из того же правила, что и
+ * подпись метрики. Поэтому страница ничего про пути и форматы не выводит: она
+ * только показывает то, что сказано, и второго правила точности не заводит. */
+function approxMarks(rows, state, cfg) {
+  const out = {};
+  cfg.metrics.forEach((m) => {
+    const mark = (flags) => (flags !== null && flags[m] ? '1' : '0');
+    const inRows = rows.map((r) => r.approx.map(mark).join('')).join('');
+    const now = state.map((s) => mark(s === null ? null : s.approx)).join('');
+    if (inRows.indexOf('1') >= 0 || now.indexOf('1') >= 0) out[m] = { rows: inRows, now: now };
+  });
+  return out;
+}
+
+/* Производные величины живут в `src/derived.js`: их считает и артефакт (импорт
+ * ниже), и страница (получает тот же файл текстом). Второго расчёта той же
+ * таблицы нет вовсе, поэтому разойтись молча двум отчётам нечем — это стережёт
+ * `test/contract.test.js`. */

package/src/derived.js

@@ -0,0 +1,115 @@
+/* Производные величины отчёта: из абсолютных значений получаются итоги, дельты,
+ * содержимое клетки и подпись коммита.
+ *
+ * Единственное место, где это считается. Оба вывода пользуются этим файлом:
+ * статический артефакт импортирует его как обычный модуль, а страница получает
+ * его текст вклеенным в свой единственный файл (внешних ссылок страница иметь не
+ * может). Поэтому у этого файла два требования, и оба обязательны:
+ *
+ *   1. Ни импортов, ни состояния модуля — иначе текст нельзя вклеить;
+ *   2. Один `import` на строку и экспорт объявлением (`export function`), а не
+ *      списком имён: модульный синтаксис при вклейке снимается построчно, и
+ *      непонятая строка не должна молча попасть в страницу (`pageScript`).
+ *
+ * Расхождение двух отчётов возможно только здесь, поэтому и стеречь его надо
+ * здесь: `test/contract.test.js` сверяет числа страницы с числами артефакта и
+ * следит, чтобы у страницы не появилось своего расчёта. */
+
+// Разряды тонкими пробелами: toLocaleString зависит от ICU сборки Node, а строка
+// таблицы обязана совпадать побайтово на любой машине.
+export function group(n) {
+  return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, '\u2009');
+}
+
+/* Итог: сумма по включённым файлам. Выключенный файл не участвует ни в таблице,
+ * ни в сумме, — иначе «итого» отвечало бы не про то, что видно. */
+export function totalsOf(values, metrics, on) {
+  const out = {};
+  metrics.forEach((m) => { out[m] = 0; });
+  values.forEach((v, i) => {
+    if (v === null || (on !== undefined && !on[i])) return;
+    metrics.forEach((m) => { out[m] += v[m]; });
+  });
+  return out;
+}
+
+/* Дельта к предыдущему коммиту. Появление файла — рост на весь его объём: иначе
+ * сумма дельт по колонке не сходилась бы с текущим размером. */
+export function deltaOf(now, before) {
+  return before === null || before === undefined ? now : now - before;
+}
+
+/* Содержимое клетки строки-коммита: что в ней написано и каким цветом. Разметку
+ * из этого делает каждый вывод сам (строка HTML или узел DOM), а правила одни.
+ * Пустая клетка — «не менялось», `—` — файла в ревизии нет.
+ * `minus` — знак минуса: у артефакта он заморожен эталоном побайтово, страница
+ * ставит типографский. */
+export function cellParts(value, delta, minus) {
+  if (value === null) return { text: '—', dir: null, miss: true };
+  if (!delta) return { text: '', dir: null, miss: false };
+  return {
+    text: (delta > 0 ? '+' : minus) + group(Math.abs(delta)),
+    dir: delta > 0 ? 'up' : 'down',
+    miss: false
+  };
+}
+
+// Клетка верхней строки: абсолютный размер, без дельты.
+export function valueParts(value) {
+  return value === null ? { text: '—', miss: true } : { text: group(value), miss: false };
+}
+
+/* Строка-коммит: блок «общий объём» и по блоку на включённый файл, в каждом —
+ * клетка на метрику. Отбор включённых файлов происходит здесь, поэтому и таблица,
+ * и суммы считаются от одного выбора. */
+export function rowModel(values, prev, metrics, on) {
+  const total = totalsOf(values, metrics, on);
+  const prevTotal = prev === null ? null : totalsOf(prev, metrics, on);
+  const out = {
+    total: metrics.map((m) => ({
+      value: total[m],
+      delta: deltaOf(total[m], prevTotal === null ? null : prevTotal[m])
+    })),
+    files: []
+  };
+  values.forEach((v, i) => {
+    if (on !== undefined && !on[i]) return;
+    const before = prev === null || prev[i] === null ? null : prev[i];
+    out.files.push(metrics.map((m) => {
+      const value = v === null ? null : v[m];
+      const was = value === null || before === null ? null : before[m];
+      return { value: value, delta: value === null ? null : deltaOf(value, was) };
+    }));
+  });
+  return out;
+}
+
+/* Верхняя строка — абсолютные размеры на HEAD: абсолютное число стоит в таблице
+ * один раз, и именно с ним сходятся все дельты под ним. */
+export function nowModel(values, metrics, on) {
+  const total = totalsOf(values, metrics, on);
+  const files = [];
+  values.forEach((v, i) => {
+    if (on !== undefined && !on[i]) return;
+    files.push(metrics.map((m) => (v === null ? null : v[m])));
+  });
+  return { total: metrics.map((m) => total[m]), files: files };
+}
+
+/* Подпись коммита в терминах данных: что показать, чем подписать и куда вести.
+ * Ссылку считает `rowHref` движка — то же место, откуда её берёт контракт для
+ * страницы, поэтому оба вывода ведут туда же. Подпись всплывающей строки тоже
+ * здесь: два вывода не должны подписывать один коммит по-разному. */
+export function commitParts(row, showSha, href) {
+  const short = showSha ? row.sha.slice(0, 7) : '';
+  return {
+    when: row.when,
+    subject: row.subject,
+    short: short,
+    title: short === '' ? row.subject : row.subject + ' · ' + short,
+    href: href || null,
+    mark: row.section === null
+      ? { text: '—', title: null }
+      : { text: '§' + row.section.id + (row.section.added ? '' : '*'), title: row.section.head }
+  };
+}

package/src/doctor.js

@@ -0,0 +1,225 @@
+import { EXIT, Refusal, cliCommand } from './refusal.js';
+import { GIT_PINS, git, gitEnv } from './git.js';
+import { loadConfig } from './config.js';
+import { TOOL_PKG } from './tool.js';
+import { coverage, coverageText } from './check.js';
+import { hookStatus } from './hook.js';
+import { minifier } from './minify.js';
+import { tokenizer } from './tokens.js';
+
+/* Диагностика одним ответом (`size doctor`): отвечает ли машина за числа, чем
+ * считаются метрики здесь и сейчас, годятся ли настройки, всё ли из истории
+ * покрыто. Ничего своего он не считает: покрытие — тот же ответ, что даёт
+ * `size check` (`coverage`), окружение — факты этой машины, зависимости — те же
+ * загрузчики, которыми пользуются датчики. Второго расчёта в пакете нет.
+ *
+ * Правило ответа: `ok` значит «делать нечего», а у находки назван уровень.
+ * `action` — что-то надо сделать (и, где возможно, названа команда починки);
+ * `note` — наблюдение: знать полезно, делать нечего. Код выхода — первый по
+ * важности, а не «всё хорошо»: 2 — настройки нечитаемы (читать больше нечего),
+ * 3 — история обрезана, 1 — покрытие неполно, 4 — число приближённо. Порядок
+ * именно такой: сначала то, что мешает считать, потом то, что требует починки,
+ * потом честная оговорка о счёте. Хук в этот порядок не входит: отчёт собирается
+ * и без него, поэтому сломанный хук — находка без своего кода (вердикт `ok` при
+ * этом всё равно «есть дело»).
+ *
+ * Чего ответ не делает: не говорит, «правильно» ли выбраны колонки (это знает
+ * проект), и не угадывает там, где данных нет, — отсутствие ответа называется
+ * словами (`coverage: null` и находка с причиной).
+ */
+
+/* Окружение: что за машина и что она говорит о числах. Без ответа git ответ
+ * честно неполон (`git: null`), а не выдуман. */
+function environment(root) {
+  const env = {
+    node: process.version,
+    platform: process.platform,
+    root: root,
+    git: null,
+    shallow: null,
+    pins: GIT_PINS.slice(),
+    locale: gitEnv().LC_ALL
+  };
+  try {
+    env.git = git(root, ['--version']).trim();
+    env.shallow = git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true';
+  } catch (_e) {
+    // git не ответил — об этом скажет находка, а не выдуманное значение.
+  }
+  return env;
+}
+
+/* Зависимости: чем метрики считаются здесь и сейчас. Спрашиваются те же
+ * загрузчики, что и у датчиков (`minifier`, `tokenizer`), поэтому ответ не может
+ * разойтись с числом: без минификатора `min` считает упрощением, без словаря
+ * `tok` — оценкой.
+ *
+ * Загружается только то, о чём проект действительно спросил: словарь весит
+ * мегабайты, и трогать его ради строки «есть» значило бы заплатить за ответ,
+ * которого у чисел не было (то же правило, что у отчёта: `test/tokens.test.js`).
+ * Ненужный датчик назван не «неизвестным», а ненужным — на точность он не влияет,
+ * и это и есть ответ; «неизвестно» остаётся там, где настройки нечитаемы и
+ * спросить не у кого. */
+const UNREADABLE = 'неизвестно: настройки нечитаемы';
+
+/* Спрошено — спрашиваем загрузчик; не спрошено — говорим об этом словами и не
+ * платим за него. */
+function entry(asked, name, metric, load, note) {
+  if (asked !== true) return { name: name, metric: metric, present: null, note: note };
+  const { tool, version } = load();
+  return { name: name, metric: metric, present: tool !== null, version: version };
+}
+
+function dependencies(cfg) {
+  const asksMinify = cfg === null ? null : cfg.minify.engine === 'esbuild';
+  const asksTokens = cfg === null ? null : cfg.metrics.indexOf('tok') >= 0;
+  return [
+    entry(asksMinify, 'esbuild', 'min', () => minifier(),
+      asksMinify === null ? UNREADABLE : 'не спрашивается: «minify» считает снятием балласта'),
+    entry(asksTokens, 'gpt-tokenizer', 'tok', () => tokenizer(cfg.tokens),
+      asksTokens === null ? UNREADABLE : 'не спрашивается: метрики ' + cfg.metrics.join(' '))
+  ];
+}
+
+export function doctor(root, configFile) {
+  const rep = {
+    schema: 1,
+    ok: false,
+    tool: { name: TOOL_PKG.name, version: TOOL_PKG.version },
+    environment: environment(root),
+    config: null,
+    dependencies: null,
+    hooks: null,
+    coverage: null,
+    findings: [],
+    exit: EXIT.OK
+  };
+  let cfg = null;
+  try {
+    cfg = loadConfig(configFile, root);
+    rep.config = { file: configFile, ok: true, columns: cfg.columns.length, metrics: cfg.metrics };
+  } catch (e) {
+    // Отказ настроек здесь не отказ, а находка: диагностика затем и нужна, чтобы
+    // назвать причину и починку, — их и несёт текст отказа.
+    if (!(e instanceof Refusal)) throw e;
+    rep.config = { file: configFile, ok: false, problem: e.message };
+    rep.findings.push({ level: 'action', what: e.message });
+    rep.exit = e.code;
+  }
+  rep.dependencies = dependencies(cfg);
+  rep.hooks = hooksReport(root, cfg);
+  if (rep.hooks.installed && rep.hooks.enabled === false) {
+    rep.findings.push({
+      level: 'action',
+      what: 'хук установлен, но автоматика выключена настройкой hooks.enabled: отчёт обновляется руками',
+      fix: 'верните «"hooks": {"enabled": true}» в файл настроек или снимите хук: ' + cliCommand('uninstall-hook')
+    });
+  }
+  if (rep.hooks.installed && rep.hooks.last !== null && HOOK_BAD.indexOf(rep.hooks.last.result) >= 0) {
+    rep.findings.push({
+      level: 'action',
+      what: 'хук: последний запуск не пересобрал отчёт — ' + rep.hooks.last.why,
+      fix: 'починьте то, на что жалуется причина, и пересоберите отчёт: ' + cliCommand('--write')
+    });
+  }
+  if (cfg === null) {
+    rep.findings.push({
+      level: 'note',
+      what: 'покрытие не считалось: настройки нечитаемы — почините их и спросите снова'
+    });
+  } else {
+    try {
+      rep.coverage = coverage(cfg, root, configFile);
+    } catch (e) {
+      if (!(e instanceof Refusal)) throw e;
+      rep.findings.push({ level: 'action', what: e.message });
+      rep.exit = e.code;
+    }
+  }
+
+  /* Что попадает в находки, а что нет: в отчёте уже целиком стоит блок покрытия
+   * (тот же текст, что у `size check`), поэтому неполнота здесь второй раз не
+   * пересказывается — она меняет вердикт и код выхода. Находкой становится то,
+   * чего в блоке покрытия нет: нечитаемые настройки, обрезанная история, а по
+   * датчикам — их причина и починка (их `size check` печатает отдельной строкой
+   * `!`, а здесь они часть того же ответа). Неполнота старше приближения: из
+   * двух причин починки код выхода несёт ту, без которой чисел нет вовсе. */
+  if (rep.coverage !== null) {
+    rep.coverage.sensors.forEach((gap) => {
+      rep.findings.push({ level: 'action', what: gap.why, fix: gap.fix });
+    });
+    if (!rep.coverage.ok) rep.exit = EXIT.VIOLATION;
+    else if (rep.coverage.sensors.length > 0) rep.exit = EXIT.SENSOR;
+  }
+
+  /* «Делать нечего»: ни одной находки-действия и покрытие сосчитано и полно.
+   * Покрытие спрашивается отдельно, потому что его неполнота говорится не находкой,
+   * а блоком покрытия (см. выше), — а вердикт она менять обязана. */
+  rep.ok = rep.coverage !== null && rep.coverage.ok
+    && !rep.findings.some((f) => f.level === 'action');
+  return rep;
+}
+
+/* Итог последнего запуска хука словами: по нему человек понимает, что произошло
+ * после коммита, не заглядывая в `.git`. */
+const HOOK_RESULT = {
+  committed: 'отчёт пересобран и закоммичен',
+  rebuilt: 'отчёт пересобран без коммита',
+  unchanged: 'менять было нечего',
+  refused: 'отказ',
+  failed: 'ошибка',
+  skipped: 'пропущен'
+};
+// Итоги, которые требуют действий: отказ инструмента и его собственная ошибка.
+const HOOK_BAD = ['refused', 'failed'];
+
+/* Состояние хука: установлен ли, включён ли настройкой и чем кончился последний
+ * запуск. «Не установлен» — не находка: автоматика ставится явной командой,
+ * и её отсутствие — решение проекта, а не забывчивость. */
+function hooksReport(root, cfg) {
+  const status = hookStatus(root);
+  return {
+    installed: status.installed,
+    files: status.files,
+    enabled: cfg === null ? null : cfg.hooks.enabled,
+    last: status.last
+  };
+}
+
+function hookLine(hooks) {
+  if (!hooks.installed) return 'не установлен (ставится командой ' + cliCommand('install-hook') + ')';
+  const last = hooks.last === null
+    ? 'ещё не запускался'
+    : 'последний запуск ' + hooks.last.at + ' — ' + (HOOK_RESULT[hooks.last.result] || hooks.last.result)
+      + (hooks.last.commit ? ' (' + hooks.last.commit + ')' : '')
+      + (hooks.last.why ? ': ' + hooks.last.why.split('\n')[0] : '');
+  return hooks.files.join(', ') + (hooks.enabled === false ? ' (выключен настройкой)' : '') + '; ' + last;
+}
+
+/* Текст для человека. Покрытие печатает `coverageText` — тот же, что у
+ * `size check`: два ответа об одном не должны разойтись формулировками. */
+export function doctorText(rep) {
+  const env = rep.environment;
+  const lines = [];
+  lines.push((rep.ok ? '✓ ' : '✗ ') + rep.tool.name + ' ' + rep.tool.version + ': диагностика ' + env.root);
+  lines.push('  окружение: Node ' + env.node + ', ' + env.platform + ', '
+    + (env.git === null ? 'git недоступен' : env.git)
+    + (env.shallow === null ? '' : env.shallow ? ', история обрезана' : ', история полная'));
+  // Закрепления — механизм, а не украшение: движок ставит их сам на границе вызова,
+  // поэтому настройки машины на числа не влияют (проверка — `test/environment.test.js`).
+  lines.push('  git читается с закреплениями: ' + env.pins.join(', ') + '; локаль ' + env.locale
+    + ' (настройки машины на числа не влияют)');
+  lines.push('  настройки: ' + (rep.config.ok
+    ? rep.config.file + ' — ' + rep.config.columns + ' колонок, метрики ' + rep.config.metrics.join(' ')
+    : rep.config.file + ' — нечитаемы'));
+  lines.push('  зависимости: ' + rep.dependencies.map((d) => d.name
+    + (d.present === null ? ' — ' + d.note : d.present ? ' ' + d.version + ' есть' : ' нет')
+    + ' (' + d.metric + ')').join(', '));
+  lines.push('  хук: ' + hookLine(rep.hooks));
+  if (rep.coverage) lines.push(coverageText(rep.coverage));
+  rep.findings.forEach((f) => {
+    lines.push((f.level === 'action' ? '✗ ' : '· ') + f.what);
+    if (f.fix) lines.push('  починка: ' + f.fix);
+  });
+  return lines.join('\n');
+}

package/src/explain.js

@@ -0,0 +1,113 @@
+import { assertFullHistory, readHistory, resolveCommit } from './git.js';
+import { measureHistory } from './history.js';
+import { cliCommand, refuseCause } from './refusal.js';
+import { CONFIG_NAME } from './config.js';
+
+/* Почему у коммита нет строки — ответ на конкретный вопрос про конкретный коммит.
+ *
+ * Ответ строится на том же проходе, что и сам отчёт: причина берётся у движка, а
+ * не выводится здесь заново, — иначе два ответа о том же коммите разошлись бы. Но
+ * причина у движка одна на два случая («без изменения объёма» — это и «числа не
+ * сдвинулись», и «ни одного файла колонок»), потому что отчёту эта разница не
+ * нужна; здесь она и есть суть вопроса, поэтому к причине добавляются улики —
+ * какие файлы коммит тронул и что из них колонки, что исключено, а что не
+ * отслеживается вовсе. Улики читаются из тех же фактов (список изменённых путей
+ * коммита), так что выдумать их нельзя: чего нет в истории — о том молчание. */
+
+const REASON_TEXT = {
+  merge: 'коммит — слияние, а строки слияний скрыты настройкой «rows.merges: false»',
+  report: 'тронут только сам отчёт (и то, что перечислено в «skip»)',
+  outside: 'ни один файл коммита не отслеживается колонкой',
+  flat: 'числа не сдвинулись: файлы колонок тронуты, а объём не изменился'
+};
+
+export function explainCommit(cfg, root, target) {
+  assertFullHistory(root);
+  const commits = readHistory(root);
+  /* Имя ревизии разрешает git, и только если имени нет — ищем начало sha по
+   * списку коммитов: так у неоднозначного префикса остаётся человеческий отказ
+   * со списком подходящих, а у имени — правила git, а не наши. */
+  const resolved = resolveCommit(root, String(target));
+  const needle = String(target).toLowerCase();
+  const found = resolved === null
+    ? commits.filter((c) => c.sha.toLowerCase().indexOf(needle) === 0)
+    : commits.filter((c) => c.sha === resolved);
+  // Имя разрешилось, а коммита в отчёте нет: это не «нет коммита» — коммит есть,
+  // и сказать надо именно это, иначе человек пойдёт искать проблему в истории.
+  if (resolved !== null && found.length === 0) {
+    refuseCause('коммит вне истории', '«' + target + '» — это коммит ' + resolved.slice(0, 7)
+      + ', но его нет в истории отчёта: строки строятся по коммитам текущей ветки'
+      + '\n  починка: посмотрите историю отчёта: git log --oneline'
+      + ' (всю историю репозитория показывает git log --all)');
+  }
+  if (found.length === 0) {
+    refuseCause('нет такого коммита', '«' + target + '» — не имя ревизии и не начало sha'
+      + '\n  починка: посмотрите историю: git log --oneline');
+  }
+  if (found.length > 1) {
+    refuseCause('коммит назван неточно', 'префикс «' + target + '» неоднозначен: подходят '
+      + found.length + ' коммитов'
+      + '\n  ' + found.slice(0, 5).map((c) => c.sha.slice(0, 7) + ' ' + c.subject).join('\n  ')
+      + '\n  починка: назовите больше знаков');
+  }
+  const c = found[0];
+  const measured = measureHistory(cfg, root, commits);
+  const row = measured.rows.findIndex((r) => r.sha === c.sha);
+  const dropped = measured.dropped.find((d) => d.sha === c.sha);
+
+  const tracked = new Set();
+  cfg.columns.forEach((col) => col.paths.forEach((p) => tracked.add(p)));
+  const excluded = new Set([cfg.output].concat(cfg.skip || []));
+  const touched = { columns: [], excluded: [], untracked: [] };
+  c.files.forEach((f) => {
+    if (tracked.has(f)) { if (touched.columns.indexOf(f) < 0) touched.columns.push(f); return; }
+    if (excluded.has(f)) { if (touched.excluded.indexOf(f) < 0) touched.excluded.push(f); return; }
+    if (touched.untracked.indexOf(f) < 0) touched.untracked.push(f);
+  });
+
+  /* Разница, которой нет в строке отчёта: «без изменения объёма» у коммита мимо
+   * колонок означает не то же самое, что у коммита, тронувшего колонку. */
+  let reason = row >= 0 ? null : dropped.reason;
+  if (reason === 'flat' && touched.columns.length === 0) reason = 'outside';
+
+  const fix = {
+    merge: 'включите строки слияний: "rows": { "merges": true }',
+    report: 'не требуется: строка про коммит не может лежать внутри самого коммита — обновляйте отчёт отдельным коммитом',
+    outside: 'допишите ' + (touched.untracked.length > 0 ? 'эти пути' : 'тронутые файлы')
+      + ' колонкой или в «skip» файла ' + CONFIG_NAME,
+    flat: 'не требуется: числа не изменились — строка без единого числа читалась бы как поломка'
+  }[reason];
+
+  return {
+    schema: 1,
+    sha: c.sha,
+    subject: c.subject,
+    when: c.when,
+    row: row < 0 ? null : row + 1,
+    rows: measured.rows.length,
+    reason: reason,
+    touched: touched,
+    fix: fix === undefined ? null : fix
+  };
+}
+
+/* Отказ для объяснения даётся человеку текстом, а агенту — полем: «есть строка» и
+ * «нет строки» одинаково успешные ответы, поэтому код выхода 0 у обоих. */
+export function explainText(rep) {
+  const lines = [];
+  const where = '  коммит ' + rep.sha.slice(0, 7) + ' «' + rep.subject.slice(0, 60) + '»';
+  if (rep.row !== null) {
+    lines.push('✓ строка есть: ' + rep.row + '-я из ' + rep.rows + ' — объём изменился');
+  } else {
+    lines.push('— строка не нужна: ' + REASON_TEXT[rep.reason]);
+  }
+  lines.push(where);
+  if (rep.touched.columns.length > 0) lines.push('  тронуты колонки: ' + rep.touched.columns.join(', '));
+  if (rep.touched.excluded.length > 0) lines.push('  исключено настройками: ' + rep.touched.excluded.join(', '));
+  if (rep.touched.untracked.length > 0) {
+    lines.push('  мимо колонок и исключений: ' + rep.touched.untracked.join(', ')
+      + ' — за это отвечает проверка полноты: ' + cliCommand('check'));
+  }
+  if (rep.fix !== null) lines.push('  починка: ' + rep.fix);
+  return lines.join('\n');
+}