Перейти до вмісту
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-оригінал і його формули і завантаження файла у форму про інший випадок, де поведінку платформи лишили, а не переписали.