Балл читаемости это маленькое число с большим утверждением за ним: этот текст сложнее того. Если две системы считают его по-разному, утверждение превращается в шум, и первый спор на ревью идёт о том, чей инструмент прав. Читаемость в 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-оригинале и его формулах и загрузка файла в форму о другом случае, где поведение платформы оставили, а не переписали.