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