@vernikr/size-report 2.4.0 → 2.6.0

package/src/refusal.js

@@ -3,17 +3,17 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { TOOL_PKG } from './tool.js';
 
-/* Отказ и справка: код выхода, сообщение с готовой командой починки и текст
- * «--help». Стоит ниже всех в цепочке — ни о настройках, ни о git не знает,
- * поэтому его может звать любой модуль. */
+/* Refusal and help: an exit code, a message carrying the command that fixes the problem,
+ * and the `--help` text. It stands at the bottom of the chain — it knows neither the
+ * settings nor git — which is why any module may call it. */
 
-// Пакет — модуль, а подсказка в `loadConfig` цитирует путь самого движка: в ESM
-// `__filename` нет, поэтому путь берётся от `import.meta.url`.
+// ESM has no `__filename`, and `invocation()` needs the engine's own location: the path
+// comes from `import.meta.url`.
 const __filename = fileURLToPath(import.meta.url);
 
-/* Отказ — это код выхода и одна строка с готовой командой починки: по коду
- * ветвится агент (таблица кодов в `PLAN.md` §4.1), по тексту — человек. Стек
- * наружу не отдаётся вовсе: подсказки в нём нет, зато есть пути машины. */
+/* A refusal is an exit code and one line with the command that fixes it: an agent branches
+ * on the code (the table is in `USAGE` below), a human reads the text. The stack is never
+ * handed out — it holds no hint, only paths of the machine. */
 export const EXIT = { OK: 0, VIOLATION: 1, CONFIG: 2, SHALLOW: 3, SENSOR: 4, INTERNAL: 5 };
 
 export class Refusal extends Error {
@@ -27,51 +27,50 @@ export function refuse(code, message) {
   throw new Refusal(code, message);
 }
 
-/* Причины отказа кодом 2 — одним списком, и он единственное место, где они
- * перечислены словами: справка печатает их из него, таблица кодов в `README.md`
- * сверяется с ним проверкой (`test/docs-commands.test.js`), а `refuseCause` не
- * пропускает отказ, не назвавший причины. Поэтому «в документации сказано
- * меньше, чем бывает» здесь не может случиться молча. Группы — по тому, откуда
- * причина: разбор вызова, настройки и проект, история, хук, измерение. */
+/* The causes of a code-2 refusal in one list, and this is the only place where they are
+ * spelled out: the help prints them from it, the code table in `README.md` is checked
+ * against it (`test/docs-commands.test.js`), and `refuseCause` lets no refusal through
+ * without a named cause. So "the documentation says less than happens" cannot pass here
+ * silently. The groups say where a cause comes from: the command line, settings and the
+ * project, history, the hook, measurement. */
 export const CONFIG_CAUSES = [
-  ['командная строка', [
-    'незнакомый ключ', 'ключ без значения', 'повтор ключа', 'два режима сразу',
-    'лишнее слово', 'команда и режим', 'неизвестная команда', 'несовместимый ключ',
-    'нет ответа в JSON', 'два ответа сразу', 'нет коммита'
+  ['command line', [
+    'unknown flag', 'flag without a value', 'repeated flag', 'two modes at once',
+    'extra word', 'command and mode', 'unknown command', 'incompatible flag',
+    'no JSON answer', 'two answers at once', 'no commit'
   ]],
-  ['настройки и проект', [
-    'нет файла настроек', 'настройки не разобраны', 'настройки неверны',
-    'нет git', 'не git-репозиторий', 'конфиг уже есть'
+  ['settings and the project', [
+    'no settings file', 'settings not parsed', 'settings invalid',
+    'git missing', 'not a git repository', 'config already exists'
   ]],
-  ['история', ['нет такого коммита', 'коммит назван неточно', 'коммит вне истории']],
-  ['хук', ['чужой хук', 'чужой core.hooksPath', 'нечем звать инструмент']],
-  ['измерение', ['файл не JavaScript', 'минификатор не разобрал']]
+  ['history', ['no such commit', 'ambiguous commit', 'commit outside the history']],
+  ['hook', ['foreign hook', 'foreign core.hooksPath', 'no way to invoke the tool']],
+  ['measurement', ['file is not JavaScript', 'minifier did not parse']]
 ];
 
-/* Причина — объявленное имя, а не украшение текста: неназванная не доедет до
- * пользователя, потому что это дефект инструмента, а не тупик человека. */
+/* A cause is a declared name, not decoration of the text: an undeclared one never reaches
+ * the user, because that is a defect of the tool rather than a dead end for a human. */
 export function refuseCause(cause, message) {
   if (!CONFIG_CAUSES.some((g) => g[1].indexOf(cause) >= 0)) {
-    throw new Error('причина отказа не объявлена: ' + cause);
+    throw new Error('refusal cause is not declared: ' + cause);
   }
   refuse(EXIT.CONFIG, message);
 }
 
-/* Строки справки про причины — из того же списка, поэтому справка не может
- * разойтись с проверками. */
+/* The help lines about causes come from the same list, so the help cannot drift from the
+ * checks. */
 const CAUSE_LINES = CONFIG_CAUSES.map((g) => '  ' + g[0] + ': ' + g[1].join(' · '));
 
-/* Как инструмент вызывается там, где его читают. Совет называет то, что лежит
- * рядом, и никогда — имя пакета: `npx <имя>` запускает установленный пакет, только
- * пока тот на месте, а в проекте без него имя уходит в реестр и запускает чужой
- * пакет с тем же именем — текст, который должен выручать, приводит к чужому коду.
- * Поэтому форма одна: путь внутри проекта (`node node_modules/<имя>/bin/size.js`) —
- * в проекте с пакетом она работает, без пакета отказывает на месте и в сеть не идёт.
+/* How the tool is called where it is read. The advice names what lies nearby and never the package
+ * name: a path inside the project (`node node_modules/<name>/bin/size.js`) works where the package is
+ * installed and, where it is not, refuses on the spot; the name from the registry would instead fetch
+ * and run a revision the project never pinned (and the unscoped name there belongs to another package
+ * altogether). One form, therefore, and no trip to the network.
  *
- * Команда починки цитирует точку входа, а не сам движок: при импорте движок ничего
- * не запускает, поэтому `--init` работает только через команду. Путь в репозитории
- * пакета считается от места движка, а не от текущего каталога, — сообщение обязано
- * работать из любого места проекта. */
+ * The fix command quotes the entry point rather than the engine itself: importing the
+ * engine runs nothing, so `--init` works through the command only. Inside the package's own
+ * repository the path is computed from the engine's location rather than from the current
+ * directory — the message has to work from anywhere in the project. */
 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;
@@ -84,55 +83,55 @@ export function cliCommand(flag) {
   return invocation() + ' ' + flag;
 }
 
-/* Путь внутри готовой команды: пробел или кавычка в нём сломали бы копирование,
- * поэтому такой путь берётся в кавычки — так его и приняла бы оболочка. */
+/* A path inside a ready-made command: a space or a quote in it would break copying, so such
+ * a path is quoted the way a shell would accept it. */
 export function advicePath(p) {
   return /[\s"'$`\\]/.test(p) ? JSON.stringify(p) : p;
 }
 
 export const USAGE = [
-  '@vernikr/size-report — отчёт об объёме файлов по коммитам: один файл,',
-  'самодостаточная страница (данные, оформление и программа лежат в ней же).',
+  '@vernikr/size-report — a report on how the size of files grows commit by commit: one file,',
+  'a self-contained page (the data, the styling and the program live inside it).',
   '',
-  'Запуск: ' + invocation() + ' [команда] [режим] [ключи]',
+  'Usage: ' + invocation() + ' [command] [mode] [flags]',
   '',
-  'Команды:',
-  '  check [--json]    полнота: настройки, история, пути, датчики (код 1 — путь',
-  '                    истории не отслеживается и не объявлен исключением)',
-  '  explain <коммит>  почему у коммита нет строки (имя ревизии, sha или его начало)',
-  '  doctor [--json]   диагностика одним ответом: окружение, зависимости, настройки,',
-  '                    покрытие (код 0 — делать нечего, иначе — первый по важности)',
-  '  install-hook      поставить хуки post-commit и post-merge (они ставятся сами при',
-  '                    первом запуске в проекте): отчёт пересобирается после каждого',
-  '                    коммита и слияния, а если он в git — ложится отдельным коммитом',
-  '  uninstall-hook    убрать хук и его состояние (проект возвращается к прежнему)',
-  '  hook-run          то, что зовёт хук: пересборка и коммит отчёта (вручную не нужно)',
+  'Commands:',
+  '  check [--json]    completeness: settings, history, paths, sensors (code 1 — a path',
+  '                    of the history is not tracked and is not declared an exception)',
+  '  explain <commit>  why a commit got no row (a revision name, a sha or its beginning)',
+  '  doctor [--json]   diagnostics in one answer: environment, dependencies, settings,',
+  '                    coverage (code 0 — nothing to do, otherwise — the first by weight)',
+  '  install-hook      install the post-commit and post-merge hooks (they install themselves',
+  '                    on the first run in a project): the report is rebuilt after every',
+  '                    commit and merge and, if it is in git, lands as a commit of its own',
+  '  uninstall-hook    remove the hook and its state (the project goes back to what it was)',
+  '  hook-run          what the hook calls: rebuild the report and commit it (never by hand)',
   '',
-  'Режимы:',
-  '  --init [файл]   закрепить настройки файлом (--force — перезаписать существующий)',
-  '  --write [файл]  собрать отчёт в файл из настроек (каталог создаётся сам)',
-  '  --data          данные контракта в stdout — для отчёта и для агента',
-  '  --json          прежняя форма данных в stdout',
-  '  (без режима)    проверить, что отчёт совпадает с историей',
+  'Modes:',
+  '  --init [file]   pin the settings in a file (--force — overwrite an existing one)',
+  '  --write [file]  build the report into a file from the settings (the directory is made)',
+  '  --data          the contract data on stdout — for the report and for an agent',
+  '  --json          the former shape of the data on stdout',
+  '  (no mode)       check that the report matches the history',
   '',
-  'Ключи: --config <файл> — другие настройки; --help — эта справка.',
+  'Flags: --config <file> — other settings; --help — this help.',
   '',
-  '--json — форма ответа, а не отдельный режим, и правило у него одно: ответ бывает',
-  'ровно у четырёх вызовов. Без команды это прежняя форма данных, у check, explain',
-  'и doctor — их ответ; у остального ответа нет, и там --json — отказ, а не тишина.',
+  '--json is a shape of the answer rather than a mode of its own, and it has one rule: exactly',
+  'four calls answer. Without a command it is the former shape of the data, with check, explain',
+  'and doctor — theirs; the rest have no answer, and there --json is a refusal rather than silence.',
   '',
-  'Запуск один: команда и режим не совмещаются, режим тоже один, и лишнее слово',
-  'вместе с незнакомым ключом — отказ с готовой командой, а не обычный прогон.',
+  'One run at a time: a command and a mode do not combine, a mode is alone too, and an extra word',
+  'or an unknown flag is a refusal with a ready-made command rather than an ordinary run.',
   '',
-  'Настройки заводить не обязательно: без файла они выводятся из самого проекта',
-  '(колонки — по группам путей из дерева и истории, журнал и куда писать — оттуда же),',
-  'и об этом сказано в выводе. «--init» закрепляет выведенное файлом — дальше правят его;',
-  'файл, названный ключом «--config», обязан быть, иначе — отказ.',
+  'Settings are not obligatory: without a file they are derived from the project itself',
+  '(columns — from the path groups of the tree and the history, the journal and where to write —',
+  'from there too), and the output says so. `--init` pins what was derived in a file — after that',
+  'the file is edited; a file named by `--config` has to exist, and otherwise it is a refusal.',
   '',
-  'Коды выхода: 0 — всё хорошо, 1 — расхождение с историей или неполнота, 2 — вызов,',
-  'настройки или окружение, 3 — неполная история, 4 — нет датчика, 5 — внутренняя',
-  'ошибка. У doctor свой порядок: 2, 3, 1, 4 — по важности находки, а не по тому,',
-  'что нашлось первым.',
+  'Exit codes: 0 — all is well, 1 — a mismatch with the history or an incompleteness, 2 — the',
+  'call, the settings or the environment, 3 — an incomplete history, 4 — no sensor, 5 — an',
+  'internal error. doctor has an order of its own: 2, 3, 1, 4 — by the weight of a finding',
+  'rather than by what came first.',
   '',
-  'Причины отказа кодом 2 (их же называет таблица кодов в README.md):'
+  'Causes of a code-2 refusal (the code table in README.md names them too):'
 ].concat(CAUSE_LINES, ['']).join('\n');

package/src/size-table.js

@@ -1,81 +1,46 @@
-/* Таблица объёма файлов по коммитам — переносимый генератор.
- *
- * Зачем. Объём проекта обсуждается числами регулярно (здесь — WORKLOG §19–§21),
- * и каждый раз это был ручной замер двух ревизий. Генератор делает замер
- * непрерывным: строка — коммит, колонка — файл, в клетке — изменение к
- * предыдущему коммиту по каждой метрике (`raw` — файл как он есть,
- * `min` — форма без комментариев и отступов), а абсолютные размеры стоят один
- * раз, в верхней строке «сейчас» (иначе крупное число повторялось бы в каждой
- * строке, и колонки расползались бы на экраны вширь).
- *
- * Источник правды — сам git: размеры берутся из блобов коммитов, а не из
- * рабочего дерева. Поэтому таблица не зависит от того, что открыто в редакторе,
- * и собирается заново по всей истории, а не дописывается инкрементально
- * (инкрементальный файл пришлось бы чинить после любой правки старых чисел).
- *
- * **Проектное — в конфиге, механика — в пакете.** Движок не знает ни имён файлов
- * проекта, ни имени журнала, ни языка подписей: колонки, метрики, журнал,
- * локаль, куда писать — всё в `size-table.config.json` рядом с корнем
- * репозитория (`--config` — другой путь). Поэтому пакет подключается к новому
- * проекту как зависимость, а `size --init` подбирает там черновик конфига
- * (какие расширения в проекте, где журнал, куда писать), который дальше
- * правится глазами.
- *
- * Строку получает коммит, сдвинувший хотя бы одно число, включая merge: у
- * слияния берётся дифф к первому родителю, поэтому его правки видны и в строке,
- * и в переносе состояния. Не получают строку коммиты, тронувшие лишь сам файл
- * таблицы (и всё, что перечислено в `skip`) — строка про коммит не может лежать
- * внутри самого коммита (sha на момент сборки ещё неизвестен), поэтому
- * обновление таблицы — отдельный коммит, — и коммиты, у которых все клетки
- * вышли нулевыми (слияние, разрешённое ровно в то, что уже дала ветка): строка
- * без единого числа читается как поломка. Отсюда же
- * требование к конфигу: колонки обязаны покрывать всё, что коммит может
- * изменить. Коммит мимо колонок дал бы строку без единого числа, а пустая
- * клетка в таблице означает «файла в этой ревизии ещё нет» — читается как
- * поломка (это стережёт тест).
- * Если в конфиге выключить sha в строках (`rows.sha: false`), тот же инвариант
- * начинает работать и для стратегии «пересобрать и дописать в тот же коммит»:
- * без sha артефакт становится неподвижной точкой сборки.
- *
- * Отчёт один: самодостаточная страница (`size-report.html`), в которой лежат и
- * данные, и оформление, и программа. Второй формы того же отчёта нет намеренно: два
- * вывода одной истории разошлись бы молча, а выбрать, какой верный, было бы нечем.
- *
- * Запуск (из любого места репозитория; `size` — когда пакет установлен, иначе
- * `node bin/size.js`):
- *   size                    проверка: отчёт совпадает с историей (CI)
- *   size --write [файл]     перегенерировать отчёт
- *   size --json             строки как JSON в stdout
- *   size --data             данные для отчёта и агента в stdout
- *   size --init [файл]      закрепить настройки файлом (без него они выводятся из проекта)
- *   size --config <путь>    другой файл настроек
- *   size --help             справка и коды выхода
- *
- * Требуется полная история: на обрезанном клоне (shallow) скрипт отказывается
- * работать, а не пишет молча короткую таблицу. В CI — `fetch-depth: 0`.
+/* Size of files by commit — the portable generator.
+ *
+ * A row is a commit, a column is a file, a cell is the change against the previous commit
+ * for one metric; absolute sizes appear once, in the top "now" row, or a large number
+ * would repeat in every row and the columns would run off the screen.
+ *
+ * The source of truth is git itself: sizes come from the blobs of the commits, not from
+ * the working tree, so the table does not depend on what is open in an editor, and it is
+ * rebuilt from the whole history rather than appended to — an incremental file would have
+ * to be repaired after any change to an old number.
+ *
+ * **Project matters in the config, mechanics in the package.** The engine knows neither
+ * the file names of the project nor the name of its journal nor the language of the
+ * labels: columns, metrics, journal, locale and output path all live in
+ * `size-table.config.json` next to the repository root (`--config` names another path).
+ * That is why the package can be attached to a new project as a dependency, and why
+ * `size --init` can draft a config there (which extensions the project has, where its
+ * journal is, where to write), to be edited by eye afterwards.
+ *
+ * A commit gets a row when it moved at least one number, merges included: a merge is
+ * diffed against its first parent, so its edits show both in the row and in the carried
+ * state. No row goes to a commit that touched only the report itself (or anything else
+ * listed in `skip`) — a row about a commit cannot live inside that commit, whose sha is
+ * unknown while it is being built, and that is why a rebuilt report is a commit of its
+ * own — nor to a commit whose cells all came out zero (a merge resolved into exactly what
+ * the branch already gave): a row without a single number reads as a breakdown. Hence the
+ * requirement on the config: the columns must cover everything a commit can change,
+ * because a commit outside the columns would give such a row, while an empty cell already
+ * means "the file is not in that revision yet". With `rows.sha: false` the same invariant
+ * serves the other strategy — rebuild and amend into the same commit — because without
+ * the sha the artifact becomes a fixed point.
+ *
+ * One report: a single self-contained page holding the data, the styling and the program.
+ * A second form of the same report does not exist on purpose — two outputs of one history
+ * would diverge silently, with nothing to tell which one is right.
+ *
+ * The full history is required: on a shallow clone it refuses instead of silently writing
+ * a short table (`fetch-depth: 0` in CI). Modes and exit codes: `size --help`.
  */
 
-/* Точка входа пакета — и только она: здесь нет ни одного расчёта, только
- * реэкспорт. Механика разложена по швам, которые видно по зависимостям:
- *
- *   refusal, locales, journal, tool, css, derived        — ни на чём не стоят;
- *   parse → parse-worker                               — разбор модуля вне процесса;
- *   strip → refusal, parse                             — снятие балласта и гард;
- *   metrics → strip                                    — реестр метрик;
- *   git → refusal                                      — всё, что читается у git;
- *   project → git, refusal                            — что проект говорит о себе сам;
- *   config → project, git, refusal, locales, metrics, data — настройки проекта;
- *   history → git, metrics, journal, refusal           — сборка по истории;
- *   data → locales, metrics, journal, history, project, tool — контракт со страницей;
- *   page/build → locales, css                          — отчёт одним файлом;
- *   artifact → data, page/build                        — запись отчёта;
- *   modes → почти все                                  — что делать по запросу;
- *   init → config, project, refusal, artifact          — закрепление настроек файлом;
- *   cli → args, modes, init, config, refusal           — вход: разбор и доставка.
- *
- * Публичный API — то, чем пользуются `bin/size.js` и `test/`: список ниже не
- * сокращается при разбиении (это проверяет `test/api.test.js`).
- */
+/* The entry point of the package, and nothing else: no computation here, only re-exports.
+ * The mechanics are laid out along the seams visible in the imports. The public API is a
+ * frozen list — `test/api.test.js` does not let it shrink. */
 export { main } from './cli.js';
 export { initMode } from './init.js';
 export { sniffColumns } from './project.js';

package/src/strip/forms.js

@@ -1,15 +1,15 @@
 import { stripJs } from './js.js';
 
-/* Формы текста, у которых снятие балласта своё: разметка, стили, строки файла и
- * JSON. Разные формы — разные правила, и одно правило на все было бы либо
- * трусостью (не снимать ничего), либо порчей чужого синтаксиса. */
+/* Text forms with a stripping rule of their own: markup, styles, the lines of a file and
+ * JSON. One rule for all of them would either strip nothing at all or corrupt a syntax it was
+ * never taught. */
 
 export function stripCss(src) {
   return src.replace(/\/\*[\s\S]*?\*\//g, ' ');
 }
 
-/* HTML: комментарии разметки (включая маркеры вклеек `<!--icon …-->` и
- * `<!--/icon-->`), комментарии внутри <script> как JS и внутри <style> как CSS. */
+/* HTML: markup comments, and the comments inside <script> as JS and inside <style> as CSS —
+ * each part stripped by the rule of its own form rather than by the markup one. */
 export function stripHtml(src) {
   return src
     .replace(/<!--[\s\S]*?-->/g, '')

package/src/strip/guard.js

@@ -3,52 +3,52 @@ import vm from 'vm';
 import { refuseCause } from '../refusal.js';
 import { moduleError } from '../parse.js';
 
-/* Гард стриппера: он не имеет права выбросить что-то кроме комментариев и
- * отступов, поэтому результат обязан компилироваться. Проверяем только те
- * расширения, где содержимое — валидный JavaScript (список в конфиге,
- * `minify.guard`): TypeScript или JSX хостом не проверяются, и делать вид, что
- * проверили, было бы хуже, чем не проверять.
+/* The stripper's guard: it may throw away nothing but comments and indentation, so its result
+ * has to compile. Only the extensions whose content is valid JavaScript are checked (the list
+ * is `minify.guard` in the settings): TypeScript or JSX are not checked by the host, and
+ * pretending they were would be worse than not checking at all.
  *
- * Модуль или скрипт решает текст, а не расширение: проект с бандлером пишет
- * `import`/`export` прямо в `.js` (и с `type: module` в манифесте, и без него), а
- * `vm.Script` разбирает такой файл как скрипт и падает на самом `export`. Гард
- * обязан понимать оба формата, поэтому пробует тот, на который файл похож, и
- * принимает результат, если он разбирается хотя бы одним из двух способов.
- * От этого он не слабеет: настоящая поломка не разберётся ни скриптом, ни
- * модулем, и тогда наружу идёт причина того разбора, которым файл был.
+ * The text, not the extension, decides between a module and a script: a project with a
+ * bundler writes `import`/`export` straight into `.js` (with `type: module` in its manifest
+ * and without it), while `vm.Script` parses such a file as a script and fails on the very
+ * `export`. So the guard tries the shape the file looks like and accepts the result when
+ * either of the two parses it. That does not weaken it: a real breakage parses neither way,
+ * and then the reason reported is the one from the shape the file had.
  *
- * Модуль разбирает отдельный рабочий поток (`parse.js`): без него разбор модуля
- * стоил бы запуска Node на каждую клетку. Иначе конфиг вида `eslint.config.mjs`
- * остался бы без гарда, а без гарда его правка могла бы испортить «объём» молча.
+ * A module is parsed by a separate worker (`parse.js`), or the guard would cost a Node run per
+ * cell: without it a config like `eslint.config.mjs` would stay unguarded, and an edit of it
+ * could silently spoil the "volume" number.
  *
- * Когда не разбирается даже исходный текст, стриппер тут ни при чём: в этой
- * графе измеряется не JavaScript (TypeScript, JSX), и это отказ с командой
- * починки — правкой настроек. */
+ * When even the original text does not parse, the stripper is not to blame: the cell holds
+ * something other than JavaScript (TypeScript, JSX), and that is a refusal with a fix —
+ * changing the settings. */
 
 const MODULE_MARK = /^[ \t]*(?:import|export)\b/m;
 const MODULE_EXT = ['.mjs'];
 
 export function assertCompilable(min, rev, p, src) {
-  // Скрипт пробуется первым не ради формы, а ради цены: этот разбор идёт
-  // в процессе, а модуль — в рабочем потоке.
+  // The script is tried first for its price rather than its shape: it parses in this
+  // process, while a module goes to the worker.
   const asScript = scriptError(min, p);
   if (asScript === null) return;
   const asModule = moduleError(min);
   if (asModule === null) return;
   const shape = MODULE_EXT.indexOf(path.extname(p).toLowerCase()) >= 0 || MODULE_MARK.test(min);
   if (src !== undefined && scriptError(src, p) !== null && moduleError(src) !== null) {
-    refuseCause('файл не JavaScript', 'файл ' + p + ' — не JavaScript: его исходный текст не'
-      + ' разбирается ни как скрипт, ни как модуль, так что дело не в стриптере, а '
-      + path.extname(p) + ' стоит в minify.guard: ' + (shape ? asModule : asScript) + '\n'
-      + '  починка: уберите это расширение из minify.guard или задайте для него '
-      + 'minify.ext — например { "' + path.extname(p).toLowerCase() + '": "strip-lines" }');
+    refuseCause('file is not JavaScript', 'the file ' + p + ' is not JavaScript: its source text parses'
+      + ' neither as a script nor as a module, so the stripper is not to blame, while '
+      + path.extname(p) + ' stands in minify.guard: ' + (shape ? asModule : asScript) + '\n'
+      + '  fix: remove this extension from minify.guard or give it '
+      + 'minify.ext — for example { "' + path.extname(p).toLowerCase() + '": "strip-lines" }');
   }
-  // Причина — того разбора, которым файл был: обвинять в чужой форме незачем.
-  throw new Error('стриппер испортил ' + p + ' на ' + rev.slice(0, 7) + ': '
+  /* The reason comes from the parse the file actually was: blaming the other shape would explain nothing.
+   * A revision is optional: the assembler of the report's page squeezes a text it built itself, and there is no
+   * revision to name it by — then the message says only what broke. */
+  throw new Error('the stripper broke ' + p + (rev === '' ? '' : ' at ' + rev.slice(0, 7)) + ': '
     + (shape ? asModule : asScript));
 }
 
-// Разбор как скрипт — в процессе: дешевле и без временных файлов.
+// Parsing as a script happens in this process: cheaper, and without temporary files.
 function scriptError(text, p) {
   try {
     new vm.Script(text, { filename: p });