Как Modern Web Guidance модернизирует вашу базу кода и почему это важно

Большинство веб-разработок не происходит с нуля. Это происходит в существующих базах кода, в которых за годы накопились устаревшие обходные пути, полифилы и утилиты JavaScript (автоматическое изменение размера, пользовательские хаки для стилизации флажков, прослушиватели scrollHeight) для вещей, которые браузер теперь обрабатывает нативно. Но вот в чём проблема: старый код не ломается. Она работает, поэтому никто не сообщает об ошибке. Рефакторинг работающего кода, даже если он старый, также требует доверия, поэтому разработчики по понятным причинам неохотно идут на это.

С другой стороны, если вы не будете проводить рефакторинг старого кода, чтобы использовать современные веб-функции, это незаметно скажется на размере пакета, отзывчивости страницы и специальных возможностях. Хуже того, когда вы используете агентов кодирования в этих проектах, они копируют окружающие соглашения 2015 года вместе с устаревшими шаблонами из своих данных для обучения.

Когда вы создаете что-то новое, Modern Web Guidance направляет вашего агента к современным функциям Baseline. Для существующего кода Modern Web Guidance 1.0 добавляет рабочий процесс модернизации, который сканирует ваш проект на наличие устаревших шаблонов и помогает вашему агенту обновить их.

Что происходит при модернизации

Когда вы просите агента модернизировать проект (или напрямую выполняете команду legacy-scan), происходит следующее:

• Детерминированное локальное сканирование. HTML, CSS, JavaScript/TypeScript, компоненты фреймворков и файлы package.json быстро сканируются с помощью абстрактного синтаксического дерева (AST), DOM и синтаксических анализаторов CSS локально без вызовов LLM или затрат на токены.
• Устаревший каталог правил. Сканер, который при каждом запуске помечает слишком много объектов, игнорируется. Мы протестировали правила-кандидаты примерно на 45 000 репозиториев с открытым исходным кодом, разделенных пополам: правила были написаны и настроены на одной половине, а оценены на другой, ранее не использовавшейся. Мы отбросили больше правил, чем оставили, пропустив функции, не имеющие эквивалента в устаревшем коде, и отказавшись от замен только синтаксиса без реальной отдачи (например, переписывания работающих селекторов + или ~ в :has()). Чтобы правило поставлялось по умолчанию, оно должно достигать не менее 80 % точности статического сопоставителя и 90 % точности после проверки на невидимом коде.
• Контекстно-зависимая фильтрация ложных срабатываний. Каждое совпадение с правилом сопровождается явными рубриками keepWhen/dropWhen. Это указывает агенту на необходимость оценить окружающий код и отбросить намеренные резервные варианты, защитные конструкции CSS @supports или похожие элементы, прежде чем представлять свои выводы.
• Ограничено шаблонами устаревшего кода с высокой достоверностью (и их число растет). legacy-scan проверяет подмножество из примерно 200 руководств (около 20 %), в которых устаревший код можно обнаружить детерминированно без ложных срабатываний. Со временем мы расширяем этот охват. Для остальной части каталога агент ищет и извлекает руководства по мере того, как вы создаете.

Как запустить процесс модернизации

Для модернизации кода с помощью Modern Web Guidance требуется версия 1.0 или более поздняя. Установите или обновите его с помощью npm или магазина плагинов агента:

# Install Modern Web Guidance 1.0 in your project
npx modern-web-guidance@latest install

# Or update an existing installation
npx modern-web-guidance@latest update

Поскольку рабочий процесс модернизации является частью определения основного навыка, вы можете запустить сканер, используя естественный язык, попросив агента проверить наличие "устаревших шаблонов" или "модернизировать" хранилище или папку.

Примечание. Если вы укажете только один компонент, будет выполнен обычный поиск по руководству.

Ниже приведен пример запроса на сканирование всего хранилища.

Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.

Вы также можете указать определенную папку:

Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.

Сейчас вы можете запускать legacy-scan вручную в терминале. Автоматическая интеграция с конвейерами CI/CD находится в разработке.

Примеры шаблонов, которые он находит и исправляет

Правила, которые мы выбрали, направлены на устранение распространенных антипаттернов в четырех областях: формы и интерфейс, диалоговые окна и элементы управления, макет CSS, типографика и визуальный дизайн, а также безопасность. В таблице ниже приведены примеры устаревших шаблонов и их современных аналогов.

Примеры преобразования кода

По запросу агент программирования может преобразовать устаревшие антипаттерны в современные с помощью рабочего процесса модернизации. Вот несколько примеров:

Автоматически увеличивающиеся элементы <textarea>

Устаревший код JavaScript, измеряющий scrollHeight при каждом событии input, приводит к чрезмерной нагрузке на макет. Это может привести к проблемам с производительностью, в частности с показателем Interaction to Next Paint (INP). Используя рабочий процесс модернизации, ваш агент может это исправить:

// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
  textarea.style.height = 'auto';
  textarea.style.height = `${textarea.scrollHeight}px`;
});

Для этого больше не нужен JavaScript. Процесс модернизации поможет вашему агенту заменить его на CSS:

/* After: Native declarative field sizing */
textarea {
  field-sizing: content;
  min-block-size: 3lh;
  max-block-size: 15lh;
}

Декларативные всплывающие окна

Специальную логику модальных и всплывающих окон, использующую прослушиватели событий JavaScript, можно заменить стандартными HTML-атрибутами:

<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
  openBtn.addEventListener('click', () => menu.showPopover());
</script>

<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>

Отправка по нажатию клавиши Ввод в редакторе метода ввода

Незащищенные прослушиватели нажатия клавиши Ввод преждевременно запускают отправку сообщения, когда пользователи вводят текст в редакторах методов ввода (IME) для японского, китайского или корейского языков.

Агент добавляет защитные условия для состояния композиции:

// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    sendMessage();
  }
});


// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    if (e.isComposing || e.keyCode === 229) return;
    sendMessage();
  }
});

Как это работает: четыре этапа модернизации

Рефакторинг работающего кода в существующем приложении требует доверия, потому что никто не хочет автоматического оттока или незаметных регрессий. Поэтому у нас нет параметра --fix. Даже простые на первый взгляд изменения часто требуют рефакторинга на нескольких уровнях, например удаления императивного прослушивателя JS или пакета npm и переноса поведения в HTML и CSS. Это может привести к проблемам с поведением и поддержкой браузеров.

Вместо этого рабочий процесс модернизации запускает четырехэтапный цикл с вашим агентом кодирования:

1. Сканирование (legacy-scan). Агент запускает npx modern-web-guidance legacy-scan <path> --json, который предварительно проверяет файлы на наличие релевантных подстрок, чтобы запускать синтаксические анализаторы AST, CSS и HTML только для файлов и правил, которые могут содержать уязвимости. Если уязвимость доходит до этого этапа, то вероятность того, что она не является ложноположительным результатом, уже высока (около 92 %). Каждое совпадение включает в себя контрольный список проверки для агента.
2. Контекстная проверка (keepWhen/dropWhen). Поскольку у агента программирования открыт репозиторий, он проверяет код вокруг каждого совпадения на соответствие правилу. Если чтение scrollHeight является частью виртуализированной прокрутки, а не хака <textarea>, или если проверка @supports уже защищает свойство, результат автоматически удаляется.
3. Отчет. Агент обобщает проверенные результаты (отмечая, что legacy-scan охватывает подмножество руководств с детерминированными правилами, а также план модернизации, если вы попросили просмотреть план перед внесением изменений).
4. Получение руководства, рефакторинг и проверка тестов. Когда агент получает запрос на модернизацию, он запускает npx modern-web-guidance retrieve <guide-id>, чтобы получить нужное руководство. Он выполняет рефакторинг кода в соответствии с шаблонами совместимости Baseline, описанными в руководстве, и повторно запускает legacy-scan <path> для измененных файлов вместе с набором тестов проекта, чтобы подтвердить решение.

Попробовать

Независимо от того, запускаете ли вы одноразовую команду legacy-scan в терминале или просите агента по программированию модернизировать старый модуль, рабочий процесс модернизации поможет вам избавиться от устаревших элементов веб-платформы без шума традиционных линтеров.

Используйте Modern Web Guidance вместе с инструментами разработчика Chrome для агентов, чтобы перейти от статической модернизации кода к проверке, тестированию и отладке в браузере.

Дополнительные сведения

• Документация
• Каталог руководств
• Общедоступная панель оценки
• Хранилище GitHub
• Инструменты разработчика Chrome для агентов