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

Библиотека читаемости: 4 порта и один одинаковый балл

Инженерия
Библиотека читаемости: 4 порта и один одинаковый балл

Один и тот же украинский абзац дал 11,2 в PHP и 11,9 в Python. Оба числа выглядели правдоподобно, оба ушли в дашборд клиента, и заметили это только на встрече, где два слайда не сошлись.

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

Так начинается портирование. Библиотека читаемости, написанная для PHP, переписывается на другой язык, потому что переехал конвейер, и через полгода никто не может сказать, какая реализация верная.

Сейчас моя библиотека читаемости работает на четырёх языках и возвращает одинаковые числа во всех. Дорога туда была не про математику, а про договорённость, что значит «одинаковые».

Зачем портировать

Подсчёт читаемости живёт там, где живёт текст. Сайту на PHP он нужен в команде WP-CLI. Сервису на Node в обработчике запроса. Конвейеру на Python до шага с эмбеддингами. Задаче на Rust, потому что пакетный прогон там быстрее.

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

Четыре пакета это PHP, Python, TypeScript и Rust, у каждого нет зависимостей в рантайме и данные языков лежат внутри.

Что расходится при переписывании

Сами формулы опубликованы и стабильны. Gunning Fog это фиксированное выражение над словами, предложениями и сложными словами. Неоднозначного в нём нет.

Расходится всё вокруг формулы.

Подсчёт символов первый. mb_strlen в PHP и String.length в JavaScript считают разное, поэтому слово с комбинирующим ударением это четыре символа в одном и два в другом, а индекс Coleman-Liau читает символы на сто слов.

Округление второе. Балл 11,25 округляется до 11 в одном языке и до 11,3 в другом, и дашборд, сравнивающий две системы, показывает разницу, которая есть артефакт форматирования.

Разбиение на слова третье. Составное слово через дефис это одно слово в одной реализации и два в другой, и это двигает среднюю длину предложения и все баллы вместе с ней.

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

Как заставить четыре реализации договориться

Ответ это общий набор тестов, и он занял три итерации.

Каждый случай это текст, язык и формула с ожидаемым значением, зафиксированным на заданной точности. Каждый порт читает ту же таблицу и валит сборку при расхождении с нулевым допуском. Не «достаточно близко», потому что близость и есть место, где живёт дрейф.

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

Эталон это не автоматически PHP. По каждому спорному случаю мы проверяем опубликованную формулу руками и решаем, какое поведение верное, а потом приводим к нему все порты. Дважды это решение было против PHP.

Что у портов общее

Один движок слогов: шаблоны переносов TeX по Frank M. Liang, применённые на каждый язык, с теми же списками исключений.

Один реестр формул: 17 формул, из них пять работают на любом языке и двенадцать несут опубликованные коэффициенты. Каждый язык объявляет, какие формулы поддерживает, поэтому английский получает девять, а немецкий восемь.

Один формат файла данных, сгенерированный один раз и скопированный, поэтому исправление коэффициента попадает во все четыре пакета в одном релизе.

Стоит ли это

Для одной реализации нет. Четыре реализации одной арифметики это счёт на поддержку, который имеет смысл только если альтернатива это сетевая зависимость в четырёх разных конвейерах.

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

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

Пакеты: Packagist, PyPI, npm, crates.io.