complete January 2019 webpack series

web/scripts/upgrade-2019-01-field.mjs

@@ -0,0 +1,261 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#039;');
+}
+
+function paragraph(text) {
+  return '<p>' + text + '</p>';
+}
+
+function heading(text) {
+  return '<h2>' + text + '</h2>';
+}
+
+function codeBlock(code) {
+  return '<pre><code>' + escapeHtml(String(code).trim()) + '</code></pre>';
+}
+
+function figure(src, alt, caption) {
+  return '<figure><img src="' + src + '" alt="' + alt + '" loading="lazy" /><figcaption>' + caption + '</figcaption></figure>';
+}
+
+function orderedList(items) {
+  return '<ol>' + items.map((item) => '<li>' + item + '</li>').join('') + '</ol>';
+}
+
+function bulletList(items) {
+  return '<ul>' + items.map((item) => '<li>' + item + '</li>').join('') + '</ul>';
+}
+
+function dataTable(headers, rows) {
+  const head = '<thead><tr>' + headers.map((header) => '<th scope="col">' + header + '</th>').join('') + '</tr></thead>';
+  const body = '<tbody>' + rows.map((row) => '<tr>' + row.map((cell) => '<td>' + cell + '</td>').join('') + '</tr>').join('') + '</tbody>';
+  return '<div class="table-scroll"><table>' + head + body + '</table></div>';
+}
+
+function sourceList(items) {
+  return '<ul>' + items.map((item) => '<li><a href="' + item.url + '" target="_blank" rel="noopener noreferrer">' + item.title + '</a> — ' + item.note + '</li>').join('') + '</ul>';
+}
+
+function visibleText(html) {
+  return html
+    .replace(/<[^>]*>/g, ' ')
+    .replaceAll('&nbsp;', ' ')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&#039;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function proseText(html) {
+  return visibleText(
+    html
+      .replace(/<pre><code>[\s\S]*?<\/code><\/pre>/g, '')
+      .replace(/<figure>[\s\S]*?<\/figure>/g, '')
+      .replace(/<div class="table-scroll">[\s\S]*?<\/div>/g, ''),
+  );
+}
+
+function createRevision(meta, bodyParts, sources) {
+  const bodyHtml = bodyParts.join('\n');
+  const proseLength = proseText(bodyHtml).length;
+
+  if (proseLength < 5000 || proseLength > 15000) {
+    throw new Error(meta.slug + ': prose length must be 5000–15000, got ' + proseLength);
+  }
+
+  if (sources.length < 2) {
+    throw new Error(meta.slug + ': at least two primary sources are required');
+  }
+
+  const contentHtml = [
+    bodyHtml,
+    heading('Проверяемые источники'),
+    sourceList(sources),
+  ].join('\n');
+
+  return {
+    ...meta,
+    contentHtml,
+    proseLength,
+  };
+}
+
+const webpackShimming = {
+  title: 'Webpack 4: Shimming',
+  url: 'https://v4.webpack.js.org/guides/shimming/',
+  note: 'назначение ProvidePlugin, legacy-модули с глобальными зависимостями и границы shim-подхода',
+};
+
+const webpackCodeSplitting = {
+  title: 'Webpack 4: Code Splitting',
+  url: 'https://v4.webpack.js.org/guides/code-splitting/',
+  note: 'entry, динамические импорты и дублирование модуля между несколькими entry',
+};
+
+const webpackStats = {
+  title: 'Webpack 4: Stats Data',
+  url: 'https://v4.webpack.js.org/api/stats/',
+  note: 'структура JSON-статистики сборки: assets, chunks, modules, errors и warnings',
+};
+
+const webpackDevtool = {
+  title: 'Webpack 4: devtool',
+  url: 'https://v4.webpack.js.org/configuration/devtool/',
+  note: 'варианты source map и компромиссы между удобством диагностики, скоростью и раскрытием исходного кода',
+};
+
+const jqueryExtend = {
+  title: 'jQuery API: jQuery.fn.extend()',
+  url: 'https://api.jquery.com/jQuery.fn.extend/',
+  note: 'плагин добавляет метод в прототип конкретного объекта jQuery, то есть в конкретный $.fn',
+};
+
+const fieldArticle = createRevision(
+  {
+    slug: 'editorial-2019-01-field-jquery-webpack',
+    title: 'jQuery + Webpack: почему legacy-плагин исчезает только в production',
+    categories: ['JavaScript', 'Webpack', 'jQuery', 'Разбор'],
+    cover: '/assets/editorial/2019/jquery-webpack-production-bridge-2019.svg',
+    excerpt: 'Плагин виден в development, но после production-сборки у $.fn нет метода. Разделяем три причины: глобал не создан, плагин выполнился рано или приложение держит второй jQuery.',
+    readingMinutes: 11,
+  },
+  [
+    paragraph('В development старый плагин маски ввода работает, а в production вызов <code>$(input).legacyMask()</code> падает: метода нет в <code>$.fn</code>. Цена ошибки выше сломанного поля — сборка может уйти в релиз с нерабочим оформлением или проверкой номера, а срочная правка начнёт менять Webpack вслепую.'),
+    paragraph('Разберём один вопрос: как доказать, что плагин потерялся именно на границе <code>window.jQuery</code>, порядка исполнения или второго экземпляра <code>jquery</code>, а не из-за минификации. Это учебный сценарий для Webpack 4 и jQuery; он показывает форму проверки. Ни production-бандл конкретного проекта, ни браузерную трассу я здесь не выдаю за выполненные.'),
+    heading('Сначала фиксируем, что именно исчезло'),
+    paragraph('Плагин jQuery обычно добавляет функцию в <code>$.fn</code>. Значит, выражение <code>typeof $.fn.legacyMask</code> отвечает не на вопрос «плагин подключён вообще», а на более полезный: установил ли он метод на тот экземпляр jQuery, которым пользуется код страницы. Официальный API описывает <code>jQuery.fn.extend()</code> как расширение прототипа jQuery. Если в окне живут два разных объекта jQuery, метод может оказаться только на одном из них.'),
+    paragraph('Development часто скрывает границу. На локальной странице jQuery мог приехать отдельным тегом <code>script</code> раньше vendor-файла, а dev-сервер мог не собрать второй entry в тот же путь. Production собирает зависимости в модули и чанки. Это не делает Webpack виновником: меняется способ доставки, и скрытая зависимость плагина от глобального объекта становится видна.'),
+    dataTable(
+      ['Наблюдение', 'Вероятная причина', 'Короткая проверка', 'Действие после проверки'],
+      [
+        ['<code>window.jQuery</code> пустой до старого плагина', 'Импорт есть только в области модуля', 'Остановиться перед загрузкой плагина и вывести <code>window.jQuery</code>', 'Создать явный legacy-мост до выполнения плагина'],
+        ['Метод есть у <code>window.jQuery.fn</code>, но нет у <code>$ .fn</code> приложения', 'Плагин и приложение держат разные экземпляры', 'Сравнить <code>window.jQuery === $</code>', 'Убрать второй путь резолвации и оставить одну зависимость'],
+        ['Метода нет у обоих объектов', 'Файл плагина не выполнился или выполнился до моста', 'Проверить порядок модулей, ошибку в Console и включение файла в stats', 'Подключить адаптер после моста, затем проверить production-артефакт'],
+        ['Сбой только при втором entry', 'jQuery попал в несколько entry или загрузка чанков не согласована', 'Посмотреть modules/chunks в <code>stats.json</code>', 'Настроить общую зависимость и проверить все точки входа'],
+      ],
+    ),
+    paragraph('В таблице есть важное ограничение: это дерево гипотез, не диагноз вашего сайта. Один и тот же текст ошибки может появиться при 404 vendor-файла, при CSP или при версии плагина, которая не совместима с закреплённой jQuery. Поэтому сначала собираем идентичности объектов и факт выполнения кода, а уже затем трогаем оптимизацию.'),
+    heading('Учебный пример: плагин читает window.jQuery'),
+    paragraph('Ниже минимальный legacy-файл. Он намеренно не импортирует jQuery: автор плагина рассчитывает, что глобальная переменная уже существует. Такой код неудобен для модулей, но он встречается в старых виджетах. Ошибка в примере воспроизводима без сервера: если в момент выполнения <code>root.jQuery</code> отсутствует, модуль бросает понятное исключение; если объект есть, метод появляется именно на его <code>fn</code>.'),
+    codeBlock(String.raw`
+// src/vendor/legacy-mask.js
+(function installLegacyMask(root) {
+  var $ = root.jQuery;
+
+  if (!$ || !$.fn) {
+    throw new Error('legacy-mask ожидает window.jQuery до своего запуска');
+  }
+
+  $.fn.legacyMask = function legacyMask() {
+    return this.addClass('has-legacy-mask');
+  };
+}(window));
+`),
+    paragraph('Соблазнительный вариант ниже выглядит как правильный порядок сверху вниз: сначала импорт, затем присваивание, затем импорт плагина. Но статический <code>import</code> описывает зависимость модуля, а не вызов, который исполняется на этой строке после предыдущего оператора. Зависимый <code>legacy-mask.js</code> должен быть подготовлен и выполнен до тела модуля <code>bootstrap.bad.js</code>; присваивание в <code>window</code> для него опаздывает.'),
+    codeBlock(String.raw`
+// src/bootstrap.bad.js
+import $ from 'jquery';
+import './vendor/legacy-mask';
+
+window.jQuery = window.$ = $; // для legacy-mask это уже поздно
+
+$('.js-phone').legacyMask();
+`),
+    paragraph('Для одного старого плагина не обязательно переводить весь код назад на CommonJS. Достаточно сделать маленький адаптер с явной границей. В нём <code>require()</code> вызывается после записи в <code>window</code>; поэтому legacy-файл получает именно тот объект, который импортировал bootstrap. Этот приём выбран здесь ради порядка выполнения, а не как общий стиль нового кода.'),
+    codeBlock(String.raw`
+// src/legacy-jquery-bridge.js
+import $ from 'jquery';
+
+window.jQuery = window.$ = $;
+require('./vendor/legacy-mask');
+
+export default $;
+
+// src/bootstrap.js
+import $ from './legacy-jquery-bridge';
+
+$('.js-phone').legacyMask();
+`),
+    paragraph('После такого моста минимальная проверка не должна ограничиваться отсутствием исключения. Нужно удостовериться, что глобальный объект и импорт имеют одну ссылку, а метод лежит на том же <code>$.fn</code>, с которым работает приложение. Так мы отделяем проблему порядка от ситуации, когда плагин успешно установился, но на чужой копии jQuery.'),
+    codeBlock(String.raw`
+// В Console страницы или во временном диагностическом модуле.
+import $ from './legacy-jquery-bridge';
+
+var report = {
+  hasGlobal: Boolean(window.jQuery),
+  sameInstance: window.jQuery === $,
+  pluginOnImport: typeof $.fn.legacyMask,
+  pluginOnGlobal: window.jQuery && typeof window.jQuery.fn.legacyMask,
+};
+
+console.table(report);
+console.assert(report.sameInstance, 'jQuery резолвится в разные экземпляры');
+console.assert(report.pluginOnImport === 'function', 'плагин не установлен на импорт');
+`),
+    heading('Почему ProvidePlugin не заменяет мост'),
+    paragraph('У <code>ProvidePlugin</code> другая задача. Документация Webpack 4 описывает его как способ сделать пакет переменной в модулях, которые компилирует Webpack, когда встречается нужный идентификатор. Это полезно для legacy-модуля, который обращается к свободной переменной <code>jQuery</code>, но не является автоматическим присваиванием свойства <code>window.jQuery</code>.'),
+    paragraph('Поэтому решение должно следовать из самого плагина. Если файл принимает <code>jQuery</code> как параметр или использует свободную переменную, можно проверить настройку <code>ProvidePlugin</code>. Если он явно читает <code>window.jQuery</code>, нужен мост в <code>window</code> либо отдельная настройка loader, которая документированно передаёт зависимость. Подменять оба варианта одной конфигурацией опасно: в development симптом может исчезнуть из-за случайного порядка тегов, а в production вернуться.'),
+    figure('/assets/editorial/2019/jquery-webpack-production-bridge-2019.svg', 'Схема диагностики legacy jQuery-плагина: неправильный статический импорт запускает плагин до назначения window.jQuery, а проверка равенства выявляет второй экземпляр jQuery', 'Проверка идёт от порядка исполнения к идентичности экземпляра: сначала мост, затем плагин, затем сравнение объектов.'),
+    heading('Как искать второй экземпляр без догадки по размеру bundle'),
+    paragraph('Два пакета не обязаны выглядеть как два одинаковых больших файла. Один экземпляр мог войти в entry страницы, другой — в зависимость виджета по другому пути или версии. Поэтому размер итогового JavaScript — слабое доказательство. Надёжнее сравнить объекты в рантайме и посмотреть список модулей в статистике именно той production-сборки, которая будет доставлена пользователю.'),
+    paragraph('Webpack 4 документирует JSON-статистику как представление assets, chunks и modules. В реальном репозитории её можно запросить отдельной командой. Команду ниже не запускали для этой статьи: она является маршрутом диагностики, который нужно выполнять в ветке проекта и сохранять рядом с версией lock-файла. Source map включается только на время разбора и только если правила публикации исходников это позволяют.'),
+    codeBlock(String.raw`
+# Команды для реального проекта, а не результат этого учебного примера.
+npx webpack --mode production --devtool source-map --profile --json > dist/stats.json
+npm ls jquery
+
+# В stats.json ищем пути и чанки, где встречается jquery.
+# Затем в браузере сравниваем window.jQuery с импортом из legacy-моста.
+`),
+    paragraph('Если <code>npm ls jquery</code> показывает несколько веток, это ещё не приговор: сборщик может дедуплицировать совместимые зависимости. Если в <code>stats.json</code> видны несколько модулей jQuery или разные resolved-пути, это также не доказывает, что два объекта дошли до страницы. Диагноз закрывается только вместе с равенством <code>window.jQuery === $</code>, фактом появления метода и сетевой записью тех чанков, которые фактически загрузил браузер.'),
+    heading('Порядок проверки production-сценария'),
+    orderedList([
+      'Зафиксировать точный симптом: имя метода, страницу, один input и версию собранных ассетов. Не менять конфигурацию до записи исходной ошибки.',
+      'В точке перед вызовом плагина вывести <code>window.jQuery</code>, импорт <code>$</code>, их равенство и тип <code>$.fn.legacyMask</code>. Это отделяет отсутствие глобала от второго экземпляра.',
+      'Открыть Network и убедиться, что нужные entry и lazy-chunk действительно получили ответ, а не старую страницу из кеша. Записать имена файлов и hash, не делать вывод по одному названию bundle.',
+      'Собрать production-статистику на той же версии lock-файла. Найти resolved-пути <code>jquery</code>, их chunks и причины подключения.',
+      'Если плагин читает глобал, создать один изолированный bridge до его загрузки; если он принимает импорт, удалить глобальную зависимость вместо добавления нового shim.',
+      'Повторить проверку на чистой странице и в каждом entry, где живёт виджет. Готовность — одинаковый объект jQuery и функция плагина на его <code>fn</code>, а не только исчезнувшая ошибка в Console.',
+    ]),
+    heading('Что считать исправлением'),
+    paragraph('Исправлением является не строка <code>window.$ = $</code> сама по себе. Нужен маленький контракт: bridge импортирует одну зависимость, публикует её в global до legacy-файла, подключает нужный side effect и экспортирует тот же объект приложению. Так следующий разработчик видит, где заканчивается старый API и почему этот файл нельзя переставить среди обычных импортов.'),
+    paragraph('Если обнаружен второй экземпляр, сначала устраняем причину его попадания в граф: разный resolved-путь, несовместимая версия или отдельный entry без общей оптимизации. Webpack 4 отдельно предупреждает, что несколько entry могут дублировать общий импорт; для этого есть SplitChunksPlugin. Но включить splitChunks «для лечения плагина» недостаточно: после изменения всё равно проверяем идентичность объектов и метод в runtime.'),
+    heading('Ограничения и границы примера'),
+    bulletList([
+      'Пример предполагает браузерный <code>window</code> и Webpack 4. В SSR, worker или тестовой среде global-объект другой; мост надо либо не исполнять на сервере, либо изолировать адаптером окружения.',
+      'Вызов <code>require()</code> оставлен только внутри legacy-моста ради наблюдаемого порядка. Он не является рекомендацией смешивать системы модулей во всём новом коде.',
+      'Source map может раскрывать пути и исходный код. Его нельзя включать в публичную production-доставку без проверки политики проекта; для расследования подойдёт защищённый артефакт.',
+      'CSP, 404 чанка, несовместимая версия плагина и кеш CDN могут дать похожий внешний симптом. Этот текст не заменяет Network, Console и точную версию зависимостей.',
+      'Глобальная jQuery — совместимость с конкретным legacy-файлом, а не архитектурная цель. Новый виджет лучше получает зависимость импортом и не меняет <code>window</code>.',
+    ]),
+    heading('Итог'),
+    paragraph('Когда <code>$.fn.legacyMask</code> пропадает только после production-сборки, не стоит первым делом отключать минификацию. Сначала проверяем порядок: есть ли <code>window.jQuery</code> до плагина. Затем проверяем идентичность: тот ли это объект, который импортирует приложение. После этого production-статистика и Network показывают, какой модуль и какой чанк нужно исправлять. Такой маршрут оставляет одно проверяемое условие готовности: плагин установлен на том же <code>$.fn</code>, которым пользуется экран.'),
+  ],
+  [webpackShimming, webpackCodeSplitting, webpackStats, webpackDevtool, jqueryExtend],
+);
+
+export const revisions = [fieldArticle]
+  .map(({ proseLength, ...revision }) => revision);
+
+const isDirectRun = process.argv[1]
+  && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  if (process.argv.includes('--print-revisions')) {
+    process.stdout.write(JSON.stringify(revisions, null, 2) + '\n');
+  } else {
+    process.stderr.write('Usage: node web/scripts/upgrade-2019-01-field.mjs --print-revisions\n');
+    process.exitCode = 1;
+  }
+}