В данном руководстве собрано подробное описание всех сервисных скриптов и вспомогательных утилит проекта. Они предназначены для автоматизации рутинных процессов, проверки контента, генерации необходимых ресурсов и поддержания кодовой базы в актуальном и чистом состоянии.
Файл: scripts/reports/extractMarkedText.js
Данный диагностический скрипт предназначен для извлечения коротких текстовых фрагментов из тегов с установленными атрибутами классов в статьях, что позволяет быстро проанализировать, какие именно текстовые данные используются внутри элементов разметки.
Запуск осуществляется с помощью команды в терминале:
yarn extract:marked-textТакже скрипт можно вызвать напрямую:
node scripts/reports/extractMarkedText.jsСкрипт в рекурсивном режиме производит обход категорий статей в директории src/pages/sections с целью поиска файлов с расширениями .tsx, .ts, .jsx, .js. Для каждого обнаруженного файла осуществляется разбор и поиск тегов с установленными атрибутами className или class, после чего извлекается их внутреннее текстовое содержимое. При этом учитывается ограничение на длину текста, которая не должна превышать двухсот восьмидесяти символов, а также глубина вложенности тегов, составляющая не более двух уровней.
На финальной стадии выполнения собранная информация группируется по именам файлов и по парам значений тега и класса. Итоговый отчет сохраняется в автоматически создаваемую директорию по пути scripts/logs/mark-extract-<timestamp>/, содержащую файл общего индекса index.log, каталоги с разбивкой по исходным файлам и по классам тегов. Стоит учитывать, что скрипт выполняет исключительно диагностическую роль, не внося никаких изменений в исходный код, поэтому необходимо следить за тем, чтобы файлы отчетов не попали в индекс системы контроля версий.
Файл: scripts/utilities/fileUtilities.js
Вспомогательный модуль, предоставляющий функцию для рекурсивного обхода файловой структуры проекта с автоматической фильтрацией путей на основе заданных правил игнорирования.
Импортируемая функция обхода имеет следующую сигнатуру:
walk(dir: string, callback: (filePath: string) => void): voidФункция принимает в качестве первого параметра путь к стартовой директории, а в качестве второго параметра функцию обратного вызова, которая поочередно выполняется для каждого найденного и прошедшего фильтрацию файла.
При выполнении обхода каталогов функция осуществляет автоматическую проверку каждого встреченного пути с помощью внешней функции проверки исключений из утилиты ignore. В случае, если путь удовлетворяет правилам игнорирования, он и все его дочерние элементы отбрасываются и не передаются в функцию обратного вызова. Данная утилита служит основой для обхода дерева файлов во многих других скриптах проекта, включая общий запускальщик scriptRunner.
Файл: scripts/maintenance/fixTokens.js
Сервисный скрипт, созданный для интерактивного исправления и форматирования токенов в файлах с расширением .tsx.
Запуск осуществляется с помощью команды в терминале:
node scripts/maintenance/fixTokens.jsПри старте скрипт предлагает пользователю в интерактивном режиме выбрать одну или несколько категорий для последующей обработки, среди которых доступны варианты для работы с файлами, изображениями, видеозаписями, аудиофайлами или клавишами. В процессе анализа файлов скрипт переводит текстовое содержимое внутри тегов <file>, <image>, <video> и <audio> в верхний регистр, а также нормализует пробелы вокруг символа сложения в тегах <key>.
Для каждого обнаруженного несоответствия скрипт приостанавливает выполнение и запрашивает подтверждение, предлагая ввести один из вариантов ответа, где символ y подтверждает текущее исправление, символ n отклоняет его, символ a включает автоподтверждение для всех аналогичных совпадений до конца сессии, а символ s добавляет исходное слово в список исключений для пропуска в будущем. Процесс обхода файлов базируется на функционале утилиты scriptRunner, а вся история выполненных изменений фиксируется в лог-файле по пути scripts/script_log.txt.
Файл: scripts/fonts/generateFontStyle.js
Скрипт автоматической генерации файла стилей шрифтов, который создает и перезаписывает файл src/styles/base/_fonts.scss на основе файлов шрифтов, расположенных в директории src/fonts.
Запуск выполняется командой в терминале:
node scripts/fonts/generateFontStyle.jsПоддерживаются параметры командной строки, включая параметр --fonts-root для задания альтернативного корневого пути к шрифтам со значением по умолчанию src/fonts, параметр --output для переопределения пути выходного файла стилей, по умолчанию указывающий на src/styles/base/_fonts.scss, флаг --dry-run для вывода результатов генерации в консоль без записи на диск, а также флаг --help для отображения справочной информации.
Скрипт осуществляет поиск вариативных шрифтов по маске файлов, содержащих VariableFont в расширении ttf, а также статических шрифтов в поддиректориях static. На основе структуры и наименований файлов автоматически вычисляются параметры начертания и веса шрифта с последующим исключением дублирующихся комбинаций.
После этого формируются два блока директив, где первый блок предназначен для браузеров с поддержкой вариативных шрифтов и использует конструкцию @supports (font-variation-settings: normal), а второй блок содержит правила для статических шрифтов в секции @supports not (font-variation-settings: normal). Приоритет отдается современным вариативным форматам, а в сгенерированный файл не добавляются автоматические служебные комментарии.
Файл: scripts/fonts/generateStaticFonts.js
Скрипт для генерации статических версий шрифтов в формате ttf из существующих вариативных файлов шрифтов, сохраняющий результаты в поддиректории статических шрифтов.
Запуск осуществляется командой в терминале:
node scripts/fonts/generateStaticFonts.jsДоступны параметры конфигурации, включая параметр --weights для перечисления нужных весов шрифтов через запятую, параметр --fonts-root для переопределения корневого каталога шрифтов со значением по умолчанию src/fonts, параметр --scan-root для автоматического поиска используемых весов в исходном коде проекта, по умолчанию сканирующий src, параметр --family для ограничения работы конкретными семействами шрифтов, а также флаги --overwrite для перезаписи файлов, --dry-run для имитации работы, --local-cache для указания пути локального npm-кэша и --help для вывода справки.
Сначала скрипт сканирует директорию шрифтов в поиске вариативных файлов, после чего определяет необходимый набор весов на основе переданных аргументов или автоматического разбора исходного кода проекта. Для каждого требуемого веса запускается инструмент генерации статических срезов шрифта, который сохраняет готовые файлы в подкаталоги static с именами, отражающими семейство, вес и наклон шрифта.
Процесс генерации пытается использовать установленное виртуальное окружение Python или системный интерпретатор с пакетом fontTools, а при их отсутствии переключается на выполнение JavaScript-версии библиотеки через менеджер пакетов npx, завершая работу ошибкой в случае отсутствия всех доступных бэкендов.
Файл: scripts/reports/generateVersionReports.js
Инструмент для анализа упоминаний версий в статьях и подготовки структурированных отчетов для последующего ручного редактирования.
Для запуска используется команда в терминале:
yarn report:versionsТакже скрипт можно вызвать напрямую:
node scripts/reports/generateVersionReports.jsСкрипт принимает параметр --sections для указания категорий статей, обрабатываемых в директории sections со значением по умолчанию aefaq,prfaq,psfaq, а также параметр --out для указания пути к папке результатов, по умолчанию создающий директорию с временной меткой в названии. Пример расширенного вызова с параметрами выглядит следующим образом:
node scripts/reports/generateVersionReports.js --sections aefaq,prfaq --out scripts/logs/custom-version-reportСкрипт проверяет текстовые файлы статей и формирует два выходных документа, первый из которых представляет собой текстовый файл version-occurrences.txt со всеми найденными совпадениями, напоминающими версии приложений, а второй является markdown-файлом version-actionable-checklist.md, содержащим готовый чек-лист для редакторов. В чек-лист попадают различные случаи некорректной разметки версий, включая упоминания приложений без указания конкретной мажорной версии, использование устаревших шаблонов версий, изолированные теги версий без привязки к названию приложения, а также приоритетные упоминания, требующие ручной верификации.
Скрипт не изменяет исходные файлы статей, а сгенерированные файлы логов сохраняются в игнорируемый каталог.
Файл: scripts/media/getMediaMetadata.js
Служебный скрипт для автоматического сбора геометрических размеров всех медиафайлов проекта и генерации единого объекта метаданных.
Скрипт интегрирован в конфигурацию сборщика проекта vite.config.ts и вызывается автоматически для предоставления данных через виртуальный модуль virtual:media-metadata. Возвращаемый объект имеет следующий вид:
Record<string, {width: number; height: number}>;В качестве ключей используются относительные пути медиафайлов от каталога public.
Скрипт производит сканирование директории public/media и обрабатывает изображения в форматах .png, .jpg, .jpeg, .gif, .webp, .svg, а также видеофайлы с расширениями .mp4, .webm, .mov, .mkv. Размеры изображений извлекаются с помощью библиотеки image-size, в то время как параметры видео определяются через утилиту ffprobe. При работе с видео также анализируются метаданные о повороте кадра для корректного расчета финальной ширины и высоты видеоряда.
Файл: scripts/utilities/ignore.js
Модуль конфигурации, содержащий централизованные правила исключения файлов и папок при автоматизированном анализе проекта.
Утилита импортируется другими скриптами и предоставляет доступ к нескольким переменным и функции проверки. В число экспортируемых элементов входят константа IGNORED_DIRS со списком игнорируемых директорий, включая .git, node_modules, dist, .yarn, public и другие, константа IGNORED_FILES, содержащая список конкретных игнорируемых файлов, таких как .env и lock-файлы, массив регулярных выражений и масок IGNORED_PATTERNS для сопоставления с именами файлов, включая *.log, *.local, *.sw?, а также функция shouldIgnore(path), которая принимает путь к файлу или папке и возвращает логическое значение, указывающее, следует ли пропустить этот элемент.
Функция проверки сопоставляет переданный ей путь с черным списком директорий, списком конкретных файлов и регулярными выражениями паттернов игнорирования. В случае совпадения по любому из критериев функция возвращает истинное значение, сигнализируя о необходимости пропуска. Основным потребителем данного модуля выступает файловая утилита fileUtilities для фильтрации структуры проекта при обходе.
Файл: scripts/utilities/interactiveUtilities.js
Общий интерфейс для взаимодействия с пользователем через командную строку при выполнении различных обслуживающих процедур.
Модуль экспортирует объект интерфейса чтения rl, а также две асинхронные функции:
rl
askForConfirmation(original: string, proposed: string): Promise<boolean>
confirmFileWrite(filePath: string): Promise<boolean>Функция askForConfirmation предназначена для согласования замены текстового фрагмента, а функция confirmFileWrite служит для подтверждения записи изменений в файл.
Функция подтверждения изменений предлагает пользователю четыре варианта действий при обработке текстовых замен, где ввод клавиши y подтверждает операцию для конкретного элемента, клавиша n отменяет её, клавиша a соглашается со всеми аналогичными изменениями до конца сессии, а клавиша s заносит исходную строку в список исключений для пропуска всех последующих вхождений. При подтверждении записи файлов пользователь может нажать клавишу ввода или Y для подтверждения сохранения, клавишу n для пропуска записи текущего файла, либо клавишу a для автоматического сохранения всех последующих модифицированных файлов.
Данные утилиты активно задействуются в интерактивных скриптах проекта, включая скрипты исправления токенов, перевода тегов в нижний регистр, удаления пустых строк, сортировки импортов и общий запускальщик.
Файл: scripts/content/lintContent.js
Основной инструмент проверки корректности контента и правильности использования служебной разметки в категориях статей в директории src/pages/sections.
Запуск проверки осуществляется вызовом команды в терминале:
yarn lint:contentТакже запуск возможен напрямую:
node scripts/content/lintContent.jsДля включения строгого режима проверки используется дополнительный аргумент --strict, повышающий критичность предупреждений до уровня ошибок:
node scripts/content/lintContent.js --strictСкрипт анализирует текстовое наполнение и JSX-структуру файлов статей, контролируя отсутствие HTML-тегов в текстовых свойствах, таких как заголовки, описания, теги и якоря. Дополнительно проверяется правильность оформления разделителей Divider, требующих обязательного выделения известных приложений и плагинов тегами mark, а также отсутствие вопросительных знаков в их тексте, что считается предупреждением в обычном режиме и ошибкой в строгом.
Скрипт также следит за наличием обязательных атрибутов у компонентов раскрывающихся списков DetailsSummary и NestedDetailsSummary, соответствием их якорей формату kebab-case, а также корректным разделением тегов запятыми и отсутствием их дублирования. Данный инструмент тесно связан со специализированными линтерами контента, проверяющими отсутствие HTML в строках и стиль оформления разделителей.
Файл: scripts/content/lintDividerStyle.js
Специализированный скрипт для валидации текстового содержимого внутри компонентов разделителей статей с целью поддержания стилевого единообразия.
Проверка запускается с помощью команды в терминале:
yarn lint:divider-styleТакже скрипт можно вызвать напрямую:
node scripts/content/lintDividerStyle.jsПоддерживается строгий режим проверки при передаче флага --strict в командной строке:
node scripts/content/lintDividerStyle.js --strictСкрипт сканирует категории статей в директории src/pages/sections, находя все файлы исходного кода и анализируя текстовые блоки внутри тегов разделителей. При обнаружении упоминаний известных приложений или плагинов без соответствующего оформления тегом mark с классами app или plugin скрипт завершает работу с ошибкой, а наличие вопросительных знаков расценивается как предупреждение в стандартном режиме и как ошибка в строгом.
Проверка опирается на статический список известных инструментов, который необходимо пополнять при добавлении новых часто используемых программ и плагинов в проекте. Скрипт рекомендуется запускать перед массовым обновлением структуры статей или фиксацией изменений контента.
Файл: scripts/content/lintNoHtmlInStrings.js
Линтер, запрещающий использование разметки HTML или JSX внутри строковых свойств компонентов, которые должны оставаться плоским текстом.
Запуск проверки производится командой в терминале:
yarn lint:no-html-stringsТакже запуск возможен напрямую:
node scripts/content/lintNoHtmlInStrings.jsСкрипт осуществляет обход категории статей в директории src/pages/sections и проверяет строковые свойства title, caption, tag и anchor у используемых компонентов. Обнаружение любых HTML-подобных тегов в значениях этих свойств приводит к падению скрипта с ошибкой.
Такое ограничение обусловлено тем, что эти строки применяются для построения поисковых индексов, генерации ссылок и навигации по якорям, а любое форматирование текста должно осуществляться внутри тела компонента, а не передаваться через текстовые атрибуты. В качестве примера некорректного кода можно рассмотреть передачу тегов mark внутри свойства title компонента раскрывающегося списка DetailsSummary:
<DetailsSummary
anchor="export"
title="Экспорт через <mark>Media Encoder</mark>"
>
<p>...</p>
</DetailsSummary>В данном случае правильным решением является сохранение title чисто текстовым, в то время как оформленный текст переносится непосредственно в содержимое ответа.
Файл: scripts/utilities/logger.js
Служебный модуль для протоколирования хода выполнения скриптов автоматизации в единый текстовый файл логов.
Утилита предоставляет функцию log, принимающую имя вызывающего скрипта и текстовое сообщение для записи:
log(scriptName: string, message: string): voidФункция формирует строку лога, в которую подставляет текущую метку времени в формате ISO, название скрипта в квадратных скобках и само сообщение, после чего дописывает её в конец файла scripts/script_log.txt. Пример сформированной строки содержит точную дату, время, имя скрипта и краткую информацию об успешном обновлении целевого файла проекта, такую как [2026-02-28T10:15:33.512Z] [sortImports] ✔ Обновлено: src/pages/AeFaqPage.tsx.
Файл: scripts/maintenance/lowercaseTags.js
Интерактивный скрипт для приведения значений атрибута ключевых слов к нижнему регистру в исходных файлах статей.
Запуск осуществляется с помощью вызова в консоли:
node scripts/maintenance/lowercaseTags.jsСкрипт производит поиск всех атрибутов tag в файлах исходного кода с расширением .tsx и вычисляет их эквиваленты в нижнем регистре. При обнаружении различий скрипт запрашивает подтверждение пользователя через интерактивный диалог, и в случае положительного ответа перезаписывает измененное содержимое файла на диск. Вся логика обхода и сохранения файлов построена на базе общей утилиты запуска скриптов scriptRunner, а история изменений пишется в общий технический лог.
Файл: scripts/maintenance/removeEmptyLines.js
Инструмент для автоматического удаления лишних пустых строк в файлах исходного кода проекта с предварительным подтверждением записи.
Для работы скрипта используется команда в терминале:
node scripts/maintenance/removeEmptyLines.jsСкрипт анализирует текстовое содержимое файлов, отфильтровывая строки, не содержащие значащих символов. При наличии изменений в структуре файла пользователю выводится запрос на подтверждение записи изменений, и в случае согласия файл перезаписывается на диске.
Несмотря на внутреннюю поддержку различных типов файлов, на практике область действия скрипта ограничена файлами TypeScript, поступающими из общего запускальщика scriptRunner. Для работы скрипт использует вспомогательные методы из интерактивного модуля.
Файл: scripts/utilities/scriptRunner.js
Универсальный управляющий модуль, координирующий выполнение интерактивных сценариев обработки файлов в проекте.
Основным методом является асинхронная функция запуска сценария runScript:
runScript(
scriptName: string,
processor: (
filePath: string,
originalContent: string,
rl: unknown,
askForConfirmation: unknown,
confirmFileWrite: unknown
) => Promise<string>
): Promise<void>Она принимает имя запускаемого процесса и пользовательскую функцию обработки файлов.
При запуске утилита фиксирует начало процесса в общем файле лога, после чего производит обход проекта, отбирая файлы с расширениями .ts и .tsx. Каждый найденный файл передается в функцию-обработчик вместе с методами интерактивного ввода. Если обработчик возвращает измененное текстовое содержимое, утилита перезаписывает файл на диске и заносит отметку об успехе в лог, после чего корректно закрывает интерфейс ввода и завершает сессию. Взаимодействие с данной утилитой тесно связано с работой вспомогательных инструментов, включая модули файловых утилит, интерактивных функций и логирования.
Файл: scripts/maintenance/sortImports.js
Скрипт автоматического упорядочивания импортируемых модулей в файлах исходного кода на TypeScript.
Запуск производится посредством команды в терминале:
node scripts/maintenance/sortImports.jsСкрипт анализирует блоки импорта в начале файлов, игнорируя файлы, где импорты расположены не на первых строках. Сортировка не применяется к базовым библиотекам React, компонентам маршрутизации и стилям.
Остальные импорты разделяются на группы внешних пакетов, абсолютных путей проекта и относительных путей с последующим алфавитным упорядочиванием внутри каждой группы. Перед сохранением изменений скрипт запрашивает подтверждение пользователя в консоли, используя методы интерактивного взаимодействия.