@vernikr/size-report 2.4.0 → 2.5.0

package/src/explain.js

@@ -3,56 +3,55 @@ import { measureHistory } from './history.js';
 import { cliCommand, refuseCause } from './refusal.js';
 import { outsideFix, pathRoles } from './config.js';
 
-/* Почему у коммита нет строки — ответ на конкретный вопрос про конкретный коммит.
+/* Why a commit has no row — the answer to one question about one commit.
  *
- * Ответ строится на том же проходе, что и сам отчёт: причина берётся у движка, а
- * не выводится здесь заново, — иначе два ответа о том же коммите разошлись бы. Но
- * причина у движка одна на два случая («без изменения объёма» — это и «числа не
- * сдвинулись», и «ни одного файла колонок»), потому что отчёту эта разница не
- * нужна; здесь она и есть суть вопроса, поэтому к причине добавляются улики —
- * какие файлы коммит тронул и что из них колонки, что исключено, а что не
- * отслеживается вовсе. Улики читаются из тех же фактов (список изменённых путей
- * коммита), так что выдумать их нельзя: чего нет в истории — о том молчание. */
+ * The answer is built on the same run as the report itself: the reason comes from the engine rather than
+ * being derived here anew, or two answers about one commit would drift apart. But the engine has one reason
+ * for two cases ("no change in volume" covers both "the numbers did not move" and "not a single column
+ * file"), because the report does not need that difference; here it is the whole question, so the reason is
+ * joined by evidence — which files the commit touched and which of them are columns, what is excluded, and
+ * what is not tracked at all. The evidence comes from the same facts (the commit's list of changed paths),
+ * so it cannot be invented: what the history does not hold, the answer is silent about. */
 
 const REASON_TEXT = {
-  merge: 'коммит — слияние, а строки слияний скрыты настройкой «rows.merges: false»',
-  report: 'тронут только сам отчёт (и то, что перечислено в «skip»)',
-  outside: 'ни один файл коммита не отслеживается колонкой',
-  flat: 'числа не сдвинулись: файлы колонок тронуты, а объём не изменился'
+  merge: 'the commit is a merge, and the rows of merges are hidden by the setting "rows.merges: false"',
+  report: 'only the report itself was touched (and what "skip" lists)',
+  outside: 'no file of the commit is tracked by a column',
+  flat: 'the numbers did not move: column files were touched, and the volume did not change'
 };
 
-/* Коммит по названию. Имя ревизии разрешает git, и только если имени нет — ищем
- * начало sha по списку коммитов: так у неоднозначного префикса остаётся
- * человеческий отказ со списком подходящих, а у имени — правила git, а не наши. */
+/* A commit by name. git resolves a revision name, and only when there is no such name do we look up a sha
+ * prefix in the list of commits: that way an ambiguous prefix keeps a human refusal listing the candidates,
+ * while a name follows git's rules rather than ours. */
 function lookup(root, commits, target) {
   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);
-  // Имя разрешилось, а коммита в отчёте нет: это не «нет коммита» — коммит есть,
-  // и сказать надо именно это, иначе человек пойдёт искать проблему в истории.
+  // The name resolved and the commit is missing from the report: that is not "no such commit" — the commit
+  // exists, and exactly that has to be said, or the person goes looking for a problem in the history.
   if (resolved !== null && found.length === 0) {
-    refuseCause('коммит вне истории', '«' + target + '» — это коммит ' + resolved.slice(0, 7)
-      + ', но его нет в истории отчёта: строки строятся по коммитам текущей ветки'
-      + '\n  починка: посмотрите историю отчёта: git log --oneline'
-      + ' (всю историю репозитория показывает git log --all)');
+    refuseCause('commit outside the history', '"' + target + '" is the commit ' + resolved.slice(0, 7)
+      + ', but it is not in the history of the report: rows are built over the commits of the current branch'
+      + '\n  fix: look at the history of the report: git log --oneline'
+      + ' (the whole history of the repository is shown by git log --all)');
   }
   if (found.length === 0) {
-    refuseCause('нет такого коммита', '«' + target + '» — не имя ревизии и не начало sha'
-      + '\n  починка: посмотрите историю: git log --oneline');
+    refuseCause('no such commit', '"' + target + '" is not a revision name and not the start of a sha'
+      + '\n  fix: look at the history: git log --oneline');
   }
   if (found.length > 1) {
-    refuseCause('коммит назван неточно', 'префикс «' + target + '» неоднозначен: подходят '
-      + found.length + ' коммитов'
+    refuseCause('ambiguous commit', 'the prefix "' + target + '" is ambiguous: ' + found.length + ' commits fit'
       + '\n  ' + found.slice(0, 5).map((c) => c.sha.slice(0, 7) + ' ' + c.subject).join('\n  ')
-      + '\n  починка: назовите больше знаков');
+      + '\n  fix: name more characters');
   }
   return found[0];
 }
 
-/* Улики: что коммит тронул — колонки, исключённое, мимо колонок. Суждение о роли пути
- * — одно и живёт в настройках (`pathRoles`), здесь только раскладка его ответа. */
+/* The evidence: what the commit touched — columns, excluded, past the columns. The judgement about a path's
+ * role is one and lives with the settings (`pathRoles`); here it is only sorted into buckets by that
+ * answer. */
 function touchedOf(cfg, files) {
   const role = pathRoles(cfg);
   const touched = { columns: [], excluded: [], untracked: [] };
@@ -65,14 +64,14 @@ function touchedOf(cfg, files) {
 }
 
 const FIX = {
-  merge: 'включите строки слияний: "rows": { "merges": true }',
-  report: 'не требуется: строка про коммит не может лежать внутри самого коммита — обновляйте отчёт отдельным коммитом',
-  flat: 'не требуется: числа не изменились — строка без единого числа читалась бы как поломка'
+  merge: 'turn on the rows of merges: "rows": { "merges": true }',
+  report: 'not needed: a row about the commit cannot lie inside that very commit — update the report separately',
+  flat: 'not needed: the volume did not change — a row without a single number would read as a breakage'
 };
 
-/* Починка по причине. У «мимо колонок» она одна на два ответа (`outsideFix`) и называет
- * пути. У коммита без файлов (`--allow-empty`) называть нечего — значит, починки нет
- * вовсе, а не команда без имён; этот случай и держит ветка. */
+/* The fix by reason. For "past the columns" it is one text for two answers (`outsideFix`) and names the
+ * paths. For a commit with no files (`--allow-empty`) there is nothing to name — so there is no fix at all
+ * rather than a command without names, and this branch is what holds that case. */
 function fixFor(reason, touched) {
   if (reason === 'outside') {
     return touched.untracked.length === 0 ? null : outsideFix(touched.untracked);
@@ -89,8 +88,8 @@ export function explainCommit(cfg, root, target) {
   const dropped = measured.dropped.find((d) => d.sha === c.sha);
   const touched = touchedOf(cfg, c.files);
 
-  /* Разница, которой нет в строке отчёта: «без изменения объёма» у коммита мимо
-   * колонок означает не то же самое, что у коммита, тронувшего колонку. */
+  /* The difference the report's row does not carry: "no change in volume" means something else for a commit
+   * past the columns than for one that touched a column. */
   let reason = row >= 0 ? null : dropped.reason;
   if (reason === 'flat' && touched.columns.length === 0) reason = 'outside';
   const fix = fixFor(reason, touched);
@@ -108,23 +107,23 @@ export function explainCommit(cfg, root, target) {
   };
 }
 
-/* Отказ для объяснения даётся человеку текстом, а агенту — полем: «есть строка» и
- * «нет строки» одинаково успешные ответы, поэтому код выхода 0 у обоих. */
+/* A refusal here reaches a person as text and an agent as a field: "there is a row" and "there is no row"
+ * are equally successful answers, hence exit code 0 for both. */
 export function explainText(rep) {
   const lines = [];
-  const where = '  коммит ' + rep.sha.slice(0, 7) + ' «' + rep.subject.slice(0, 60) + '»';
+  const where = '  commit ' + rep.sha.slice(0, 7) + ' "' + rep.subject.slice(0, 60) + '"';
   if (rep.row !== null) {
-    lines.push('✓ строка есть: ' + rep.row + '-я из ' + rep.rows + ' — объём изменился');
+    lines.push('✓ the row is there: ' + rep.row + ' of ' + rep.rows + ' — the volume changed');
   } else {
-    lines.push('— строка не нужна: ' + REASON_TEXT[rep.reason]);
+    lines.push('— no row needed: ' + 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.columns.length > 0) lines.push('  columns touched: ' + rep.touched.columns.join(', '));
+  if (rep.touched.excluded.length > 0) lines.push('  excluded by the settings: ' + rep.touched.excluded.join(', '));
   if (rep.touched.untracked.length > 0) {
-    lines.push('  мимо колонок и исключений: ' + rep.touched.untracked.join(', ')
-      + ' — за это отвечает проверка полноты: ' + cliCommand('check'));
+    lines.push('  past the columns and the exceptions: ' + rep.touched.untracked.join(', ')
+      + ' — the coverage check answers for this: ' + cliCommand('check'));
   }
-  if (rep.fix !== null) lines.push('  починка: ' + rep.fix);
+  if (rep.fix !== null) lines.push('  fix: ' + rep.fix);
   return lines.join('\n');
 }

package/src/git.js

@@ -1,26 +1,24 @@
 import { execFileSync, spawnSync } from 'child_process';
 import { EXIT, refuse } from './refusal.js';
 
-/* Единственная граница вызова git: закрепления настроек, блобы пачкой, история и
- * сверка с диском. Всё, что инструмент знает о содержимом репозитория, приходит
- * отсюда, — поэтому и закрепления задаются здесь, а не в каждом вызове. */
+/* The single boundary of git calls: pinned settings, blobs in batches, the history, and the
+ * comparison against the disk. Everything the tool knows about the repository's content comes
+ * from here — which is why the pins are set here rather than in every call. */
 
 export const MAX_BUF = 256 * 1024 * 1024;
-const FIELD = '\u0001'; // разделитель полей в формате git log
-
-/* Всё, что движок читает у git, читается с явно заданными настройками: их
- * значения по умолчанию берутся из настроек машины и меняют то, что попадает в
- * разбор. Без `core.quotePath=false` не-английские пути приходят закавыченными и
- * экранированными (`"docs/\320\267..."`): колонка с таким путём не находит файла,
- * а коммит, у которого она была единственным изменением объёма, теряет строку.
- * Остальные закрепления закрывают тот же класс — раскраска и блок подписи
- * подмешались бы в разбираемый поток, а перекодировка подписей — в подписи строк
- * отчёта. Закрепление задаётся здесь, а не в каждом вызове: иначе его забудет
- * следующий вызов.
+const FIELD = '\u0001'; // field separator of the `git log` format
+
+/* Everything the engine reads from git is read with explicitly pinned settings: their defaults
+ * come from the machine and change what ends up in the parse. Without `core.quotePath=false`
+ * non-English paths arrive quoted and escaped (`"docs/\320\267..."`): a column holding such a
+ * path finds no file, and a commit whose only change of volume it was loses its row. The other
+ * pins close the same class of defect — colouring and a signature block would mix into the parsed
+ * stream, and signature re-encoding into the row labels of the report. A pin is set here rather
+ * than in every call, or the next call would forget it.
  *
- * Локаль закрепляется заодно: разбор не должен зависеть от того, какие переводы
- * стоят на машине. Цена — сообщения самого git в неожиданных отказах идут
- * по-английски; сообщения инструмента остаются русскими. */
+ * The locale is pinned along with them: the parse must not depend on which translations the
+ * machine has. The price is that git's own messages in unexpected refusals come out in English,
+ * while the tool's own messages stay as they are. */
 export const GIT_PINS = [
   'core.quotePath=false',
   'color.ui=never',
@@ -44,11 +42,11 @@ export function git(root, args) {
   });
 }
 
-/* То же чтение, но с кодом возврата: там, где ненулевой код — ожидаемый ответ, а не
- * отказ (`git diff --quiet` отвечает 1 на расхождение). Исключение здесь означало бы
- * отказ инструмента там, где задан простой вопрос. `env` досыпается к окружению
- * границы — им хук собирает коммит отчёта в отдельном индексе, не трогая
- * настоящий (см. `src/hook.js`). */
+/* The same read, but with the exit code: where a non-zero code is an expected answer rather than
+ * a refusal (`git diff --quiet` answers 1 on a difference), an exception would mean the tool
+ * refusing where a simple question was asked. `env` is added on top of the boundary's
+ * environment — the hook builds the report commit in a separate index with it, leaving the real
+ * one untouched (`src/hook.js`). */
 export function gitTry(root, args, env) {
   const res = spawnSync('git', gitArgv(args), {
     cwd: root, encoding: 'utf8', maxBuffer: MAX_BUF,
@@ -57,15 +55,15 @@ export function gitTry(root, args, env) {
   return { status: res.status, stdout: res.stdout || '', stderr: res.stderr || '' };
 }
 
-/* Чтение блобов пачкой. `git cat-file --batch-check` отвечает про список пар
- * `ревизия:путь` (sha объекта и размер), `--batch` отдаёт содержимое. Один-два
- * процесса на всю историю вместо спавна `git show` на каждый файл — на тысячах
- * коммитов это разница между минутами и секундой. Побочно размер объекта
- * оказывается дешевле его чтения: метрике `raw` содержимое не нужно вовсе.
+/* Reading blobs in batches. `git cat-file --batch-check` answers about a list of `revision:path`
+ * pairs (the object sha and its size), `--batch` returns the content. One or two processes for
+ * the whole history instead of spawning `git show` per file: across thousands of commits that is
+ * the difference between minutes and a second. As a side effect the object size turns out cheaper
+ * than reading the object — the `raw` metric needs no content at all.
  *
- * Ответы позиционные (строка на запрос), поэтому запросы и ответы сопоставляются
- * по порядку — `ревизия:путь` git в ответе не повторяет. */
-const BLOB_CHUNK = 1000; // спек на пачку: ограничивает и stdin, и память
+ * The answers are positional (one line per request), so requests and answers are matched by
+ * order: git does not repeat the `revision:path` in an answer. */
+const BLOB_CHUNK = 1000; // specs per batch: it bounds both stdin and memory
 
 function catFileCheck(root, specs) {
   const out = execFileSync('git', gitArgv(['cat-file', '--batch-check=%(objectname) %(objecttype) %(objectsize)']), {
@@ -85,21 +83,21 @@ function catFileBatch(root, shas) {
     if (nl < 0) break;
     const f = buf.toString('utf8', i, nl).split(' ');
     i = nl + 1;
-    if (f.length < 3) continue; // «<спека> missing»
+    if (f.length < 3) continue; // "<spec> missing"
     const size = Number(f[2]);
     out.set(f[0], { size: size, text: buf.toString('utf8', i, i + size) });
-    i += size + 1; // перевод строки после содержимого
+    i += size + 1; // the newline that follows the content
   }
   return out;
 }
 
-/* Блобы для списка пар «ревизия:путь». `needText` — читать ли содержимое: метрике
- * `raw` хватает размера объекта, и тогда `--batch` не вызывается вовсе.
- * Одинаковые спеки и одинаковые блобы запрашиваются один раз (кэш по sha). */
+/* Blobs for a list of `revision:path` pairs. `needText` decides whether the content is read: the
+ * `raw` metric lives happily with the object size alone, and then `--batch` is not called at all.
+ * Identical specs and identical blobs are requested once (the cache is keyed by sha). */
 export function readBlobs(root, specs, needText) {
   const uniq = [...new Set(specs)];
   const out = new Map();
-  const texts = new Map(); // sha блоба → содержимое
+  const texts = new Map(); // blob sha → content
   for (let start = 0; start < uniq.length; start += BLOB_CHUNK) {
     const part = uniq.slice(start, start + BLOB_CHUNK);
     const lines = catFileCheck(root, part);
@@ -120,11 +118,10 @@ export function readBlobs(root, specs, needText) {
   return out;
 }
 
-/* Дерево HEAD: sha блобов всех файлов коммита. Это правда о содержимом HEAD,
- * добытая не тем же способом, что состояние движка (то читает блобы пачкой),
- * поэтому расхождение с ней и означает потерянную при переносе правку. Один вызов
- * на прогон; разбор идёт по NUL (`-z`), иначе пути с пробелами пришлось бы
- * раскодировать. */
+/* The HEAD tree: the blob shas of every file of the commit. This is the truth about the content
+ * of HEAD obtained by another route than the engine's state (which reads blobs in batches), so a
+ * disagreement with it means an edit lost while the state was carried forward. One call per run;
+ * the output is split by NUL (`-z`), or paths with spaces would have to be unquoted. */
 export function headTree(root) {
   const out = new Map();
   const tree = execFileSync('git', gitArgv(['ls-tree', '-r', '-z', 'HEAD']), {
@@ -138,12 +135,11 @@ export function headTree(root) {
   return out;
 }
 
-/* Файлы на диске — такими, какими их видит git: `hash-object` пропускает каждый
- * файл через те же переводы строк и фильтры, что и `git add` (`.gitattributes`,
- * `core.autocrlf`). Поэтому «файл на диске соответствует коммиту» — это сравнение
- * хешей, а не размеров: размер зависит от выкладки (при `core.autocrlf=true` на
- * диске CRLF, в git LF). Пути приходят списком, ответы позиционные — как у
- * `cat-file`. */
+/* The files on disk as git sees them: `hash-object` runs each file through the same line-ending
+ * conversions and filters as `git add` (`.gitattributes`, `core.autocrlf`). So "the file on disk
+ * matches the commit" is a comparison of hashes rather than of sizes — a size depends on the
+ * checkout (`core.autocrlf=true` gives CRLF on disk and LF inside git). Paths come as a list and
+ * the answers are positional, as with `cat-file`. */
 export function diskHashes(root, paths) {
   const out = new Map();
   const lines = execFileSync('git', gitArgv(['hash-object', '--stdin-paths']), {
@@ -153,31 +149,31 @@ export function diskHashes(root, paths) {
   return out;
 }
 
-/* Обратный перевод: то, что git выложил бы на диск для блоба этой ревизии и пути
- * (`--filters` применяет фильтры выкладки). Нужен там, где переводы строк git не
- * возвращает обратно: файл, в котором CRLF лежат в самом коммите, при
- * `core.autocrlf=true` выкладывается как есть, а «очистка» вернула бы LF, — сам
- * git про такие файлы предупреждает, а на диск кладёт именно это. */
+/* The reverse conversion: what git would write to disk for a blob of this revision and path
+ * (`--filters` applies the checkout filters). Needed where git does not undo its line endings: a
+ * file whose CRLF sits in the commit itself is written out as it is under `core.autocrlf=true`,
+ * while "cleaning" would turn it back into LF — git warns about such files and puts exactly this
+ * on disk. */
 export function diskForm(root, rev, p) {
   return execFileSync('git', gitArgv(['cat-file', '--filters', rev + ':' + p]), {
     cwd: root, maxBuffer: MAX_BUF, env: gitEnv()
   });
 }
 
-// Содержимое файла в ревизии или null, если файла там нет.
+// The content of a file in a revision, or null when the file is not there.
 export function blobAt(root, rev, p) {
   const blobs = readBlobs(root, [rev + ':' + p], true);
   const blob = blobs.get(rev + ':' + p);
   return blob === undefined ? null : blob.text;
 }
 
-/* Имя ревизии → sha коммита: `HEAD`, ветка, тег, `HEAD~1`, короткий или полный
- * sha. Правила имён остаются за git, а не переписываются здесь: свои разошлись бы
- * с ним на первом же `main~2` или `HEAD@{1}`, а `^{commit}` отсекает имена, ведущие
- * не к коммиту (тег на блоб, путь в дереве). Имя, начинающееся с дефиса, к git не
- * идёт вовсе: в `rev-parse` оно было бы ключом, а не ревизией.
- * Не разрешилось — `null`: «имени нет» и «имя неоднозначно» разбирает вызывающий,
- * у которого для этого есть список коммитов. */
+/* A revision name → the commit sha: `HEAD`, a branch, a tag, `HEAD~1`, a short or a full sha. The
+ * rules of names stay with git instead of being rewritten here: our own would part ways with it on
+ * the first `main~2` or `HEAD@{1}`, while `^{commit}` cuts off names that lead somewhere other
+ * than a commit (a tag on a blob, a path in the tree). A name starting with a dash never reaches
+ * git: in `rev-parse` it would be a flag rather than a revision.
+ * Unresolved gives `null`: "no such name" and "the name is ambiguous" are told apart by the
+ * caller, which has the commit list for that. */
 export function resolveCommit(root, name) {
   if (name === '' || name.charAt(0) === '-') return null;
   const res = gitTry(root, ['rev-parse', '--verify', '--quiet', name + '^{commit}']);
@@ -185,14 +181,13 @@ export function resolveCommit(root, name) {
   return res.status === 0 && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
 }
 
-/* История одним вызовом: заголовок коммита и список изменённых им путей.
- * `%ad` — дата автора в его собственной зоне (не в зоне машины), иначе таблица
- * собиралась бы в CI по UTC и расходилась бы с локальной сборкой.
- * `--diff-merges=first-parent` — иначе у merge-коммита списка путей нет вовсе
- * (git не показывает дифф слияния, пока не попросишь): правки разрешения
- * конфликта выпали бы и из строки, и из переноса состояния, а состояние на HEAD
- * разошлось бы с содержимым файла в дереве. С первым родителем у слияния видно
- * ровно то, что оно привнесло поверх своей ветки. */
+/* The history in one call: the commit header and the list of paths it changed. `%ad` is the
+ * author's date in the author's own zone rather than the machine's, or the table would be built in
+ * UTC in CI and disagree with a local build. `--diff-merges=first-parent` is there because a merge
+ * commit otherwise has no path list at all (git shows a merge diff only on request): edits made
+ * while resolving a conflict would drop out of both the row and the carried state, and the state
+ * at HEAD would disagree with the file content in the tree. Against the first parent a merge shows
+ * exactly what it brought on top of its branch. */
 export function readHistory(root) {
   const log = git(root, [
     'log', '--reverse', '--name-only', '--diff-merges=first-parent', '--date=format:%Y-%m-%d %H:%M',
@@ -214,8 +209,8 @@ export function readHistory(root) {
 
 export function assertFullHistory(root) {
   if (git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true') {
-    refuse(EXIT.SHALLOW, 'история обрезана (shallow clone): таблица строится по всей истории коммитов.\n'
-      + '  локально: git fetch --unshallow\n'
-      + '  в CI: actions/checkout с fetch-depth: 0');
+    refuse(EXIT.SHALLOW, 'the history is truncated (shallow clone): the table is built over the whole history of commits.\n'
+      + '  locally: git fetch --unshallow\n'
+      + '  in CI: actions/checkout with fetch-depth: 0');
   }
 }