Перейти к содержимому
Leonidov.DEV

Читаемость в Node: зачем порту совпадать побайтно

Инженерия
Читаемость в Node: зачем порту совпадать побайтно

Балл читаемости это маленькое число с большим утверждением за ним: этот текст сложнее того. Если две системы считают его по-разному, утверждение превращается в шум, и первый спор на ревью идёт о том, чей инструмент прав. Читаемость в Node стала задачей портирования раньше, чем задачей про функцию.

Код: ReadSightJS, лицензия MIT.

Библиотека на PHP появилась первой. Пакет для Node это побайтно точный порт, и таковым его сделали три решения.

Решение 1: совпадение измеряют, а не обещают

В наборе тестов лежат эталонные векторы, собранные с PHP-реализации: списки поддерживаемых формул, метрики analyze, каждая применимая формула со своими inputs и повекторные слоги по всем 86 языкам с допуском 1e-9.

Без этих векторов порт расходится тихо. Кто-то округлил коэффициент, кто-то другой иначе расставил операции, и две панели расходятся на десятую балла целый год, пока это не заметят.

Решение 2: данные едут вместе с кодом

Пакет везёт языковые JSON, коэффициенты и шаблоны переносов .tex. В рантайме ничего не скачивается, а скомпилированные шаблоны ложатся в системный каталог кеша.

Выбор стоит размера пакета и покупает предсказуемость. Балл на ноутбуке, в CI и в контейнере считается из одних данных, а отсутствующий файл становится ошибкой сборки, а не неверным числом в продакшене.

Решение 3: зависимостей в рантайме нет

Шаблоны TeX, работа с Unicode и числа лежат внутри пакета, поэтому npm install добавляет один модуль, а не граф. ESM и CommonJS выходят вместе с описаниями типов.

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

Проблема слогов, названная честно

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

Поэтому en-us и en-gb идут на составном счётчике, ru, uk, be и bg на эвристике по гласным с vowelMode: "individual", а остальные 80 языков на счёте TeX. splitWord() всегда отдаёт точные точки переноса, а splitSyllables() может отдать приблизительные.

Записать это в README значит разницу между инструментом и ловушкой. Балл, который приблизителен в известном месте, можно доверять в остальных; балл, который делает вид, что точен везде, нельзя.

Чему учит порт

Совпадение это функция. Оно позволяет двум средам отвечать на один вопрос, и ради этого порты и существуют.

Ещё порт заставляет каноническую реализацию описать собственное поведение: округление, крайние случаи, пустой ввод, текст без букв. Порт это самая строгая форма ревью, какая достанется библиотеке.

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

Отдельно стоит помнить про окружение: Rust-крейт везёт данные внутри бинарника и не трогает файловую систему, Python-пакет кеширует шаблоны в системном каталоге. Это разные решения одной задачи, и оба должны давать одинаковый балл.

Куда попадает число

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

Пакет выходит под MIT, ставится одной командой и работает без сети после установки.

Проверяйте метрики на своих текстах, а не только на демо-примерах: формулы чувствительны к длине предложения.

Рядом: библиотека читаемости о PHP-оригинале и его формулах и загрузка файла в форму о другом случае, где поведение платформы оставили, а не переписали.