funora 0.0.1.dev2__py3-none-any.whl

funora/_skeleton.py

@@ -0,0 +1,752 @@
+"""Структурный скелет страницы.
+
+Фикстуры нужны, чтобы чинить парсер и ловить изменения разметки. Сохранять для
+этого настоящий HTML со страницы под авторизацией нельзя: там имена покупателей,
+тексты переписки, номера заказов. Редактирование такого HTML - подход, при котором
+вопрос «достаточно ли сработала редакция» остаётся открытым навсегда, а git-историю
+из форков и кэшей потом не вычистить.
+
+Скелет решает это иначе: он сохраняет всё, что нужно для селекторов, и не может
+содержать персональных данных.
+
+Слово «не может» точно для текста и значений атрибутов: там сохраняется подпись,
+а не значение, и обратного преобразования не существует. С путями в ссылках
+правило разное для своего хоста и для чужого.
+
+  * Структура сохраняется целиком: теги, вложенность, порядок, атрибут class.
+  * Каждый текстовый узел заменяется подписью ``T{длина}:{классы символов}``.
+  * Значение атрибута заменяется той же подписью с номером: ``T9:d#1``. Подпись
+    остаётся на месте - по ней видно длину и состав, - а номер добавляет ровно
+    одно сведение: два значения совпадают или нет. Без этого идентификатор
+    диалога, лежащий в ``data-id``, схлопывал пятьдесят диалогов в одну подпись.
+  * Строка запроса на своём хосте заменяется номером: ``/chat/?{q1}``. У диалога
+    путь один на всех, и весь идентификатор сидит там.
+  * Путь на своём хосте сохраняет форму, а сегменты с цифрами становятся
+    ``{n1}``, ``{n2}`` и так далее: ``/orders/12345`` превращается в
+    ``/orders/{n1}``. Видно, что это ссылка на заказ, и видно, тот же это заказ
+    или другой, - но не видно какой. Номер выдаётся по первому появлению
+    значения в пределах документа и между документами смысла не имеет.
+  * Путь на чужом хосте маскируется целиком: ``t.me/ivanpetrov`` превращается в
+    ``t.me/{t}``. Ссылки на чужие адреса пишут люди в переписке, и в них живёт
+    то, ради чего их и пишут. Прежнее правило маскировало сегмент только при
+    наличии цифр либо нелатинских знаков, и такое имя проходило дословно в
+    снимок, который лежит в открытом репозитории. Схема и имя хоста остаются:
+    они публичны и говорят, куда ведёт ссылка, не говоря, к кому.
+  * Содержимое script и style выбрасывается целиком.
+  * Результат остаётся разбираемым HTML: пустые элементы записываются парой
+    тегов, и только настоящие void-теги - одиночным. Это позволяет применять
+    скелет как фикстуру и проверять на нём селекторы тем же парсером, которым
+    разбирается настоящая страница.
+
+Классы символов в подписи: ``d`` цифры, ``a`` латиница, ``c`` кириллица,
+``s`` пробельные, ``p`` пунктуация ASCII, ``o`` прочее.
+
+Про нумерацию стоит знать три вещи, и все - про то, чего она НЕ делает.
+
+Она не касается текстовых узлов. Граница проведена по различию «разметка против
+содержимого»: равенство двух значений атрибута нужно проверкам, равенство двух
+сообщений переписки не нужно никому, а сведением о переписке является.
+
+Она не действует на чужих хостах. Там номер сам по себе был бы сведением о
+третьем лице - «эти два сообщения ведут на один аккаунт», - а никакой проверке
+он не нужен: ``t.me/{t}`` остаётся неразличимым всюду.
+
+Она не связывает документы. Один и тот же заказ получает разные номера в двух
+снимках, а разные заказы - одинаковые. Сравнивать снимки по номерам нельзя, и
+это ловушка, которую вводит сам формат.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from typing import Final
+from urllib.parse import urlparse
+
+from selectolax.parser import HTMLParser, Node
+
+from ._host import same_host
+from .errors import ValidationError
+from .skeleton_format import ACCEPTED_SKELETON_FORMATS
+from .skeleton_format import NUMBERED_SKELETON_FORMATS as GENERATED_NUMBERED_FORMATS
+from .skeleton_format import SKELETON_FORMAT as GENERATED_SKELETON_FORMAT
+
+__all__ = [
+    "skeletonize",
+    "text_signature",
+    "mask_path",
+    "SkeletonError",
+    "SKELETON_FORMAT",
+    "SUPPORTED_SKELETON_FORMATS",
+    "NUMBERED_SKELETON_FORMATS",
+    "DEFAULT_OWN_HOST",
+]
+
+#: Хост площадки. Пути на нём сохраняют форму, на чужих маскируются целиком.
+DEFAULT_OWN_HOST: Final[str] = "funpay.com"
+
+#: Имя формата, записываемое в описание происхождения фикстуры.
+#:
+#: Версия 1 записывала пустые элементы как ``<div/>`` и потому не разбиралась
+#: HTML-парсером. Версия 3 маскирует пути на чужих хостах целиком. Версия 4
+#: нумерует подписи идентификаторов пути. Версия 5 распространяет нумерацию на
+#: строку запроса и на значения атрибутов: без них пятьдесят диалогов страницы
+#: оставались неразличимы - идентификатор диалога лежит и там, и там, но не в
+#: пути.
+#: Величина берётся из порождённого файла, а не пишется здесь: формат снимков -
+#: общая проверочная база, и вторая реализация обязана строить такой же.
+SKELETON_FORMAT: Final[str] = GENERATED_SKELETON_FORMAT
+
+#: Версии, в которых идентификаторы различимы между собой.
+#:
+#: Нужны проверкам: снимок, снятый до нумерации, различимость восстановить не
+#: может, и требовать её от него нечестно. Перечень объявлен спецификацией, а не
+#: выведен из порядка версий - вывод по порядку сломался бы на первой же версии,
+#: поднятой по другой причине.
+NUMBERED_SKELETON_FORMATS: Final[frozenset[str]] = GENERATED_NUMBERED_FORMATS
+
+#: Форматы, которые проект умеет читать.
+#:
+#: Перечень нужен потому, что снимок не преобразуется в v4 автоматически:
+#: нумерация восстанавливает различимость только при захвате, а из уже
+#: замаскированного файла исходные значения не вернуть. Файлы прежних версий
+#: остаются пригодными для всего, что не зависит от различимости.
+SUPPORTED_SKELETON_FORMATS: Final[frozenset[str]] = ACCEPTED_SKELETON_FORMATS
+
+#: Атрибуты, значение которых обрабатывается как путь.
+#:
+#: data-href попал сюда не для красоты: ссылка на пользователя в списке заказов
+#: лежит именно в нём, а не в href, и без разбора как пути она превращалась в
+#: безликую подпись. Форма ``/users/{n}/`` говорит, куда ведёт ссылка, и не
+#: говорит, на кого.
+_URL_ATTRS: Final[frozenset[str]] = frozenset(
+    {"href", "src", "action", "formaction", "data-url", "data-href"}
+)
+
+#: Атрибуты, значение которых сохраняется как есть.
+_VERBATIM_ATTRS: Final[frozenset[str]] = frozenset({"class"})
+
+#: Атрибут имени поля формы. Сохраняется дословно, но только по форме.
+#:
+#: ЗАЧЕМ. Имя поля - протокольная константа: по нему собирается запрос, и без
+#: него форма нечитаема как договор. Снимок формы правки лота дал двадцать
+#: полей, и все двадцать имён вышли подписями вида T19:ap - то есть форма
+#: снята, а собрать по ней запрос нельзя.
+#:
+#: Узнать имена иначе можно было только СОХРАНИВ форму и записав запрос, то
+#: есть настоящей записью на площадке. Ради имён полей менять чужой лот - цена,
+#: которой платить не надо.
+#:
+#: ЧЕМ РИСКУЕМ. Имя выбирает площадка, а не человек: это csrf_token, price,
+#: fields[12345]. Чужого текста там не бывает - но проверяется это ФОРМОЙ, а не
+#: доверием: дословно сохраняется только то, что похоже на имя поля.
+#:
+#: Всё, что содержит пробел, кириллицу или иной знак, маскируется по общему
+#: правилу. Значение поля НЕ раскрывается никогда: в нём лежат цена, описание
+#: лота и сообщение покупателю.
+#:
+#: ТИП ПОЛЯ здесь же и по той же причине. Без него флажок неотличим от обычного
+#: поля: снимок формы правки лота дал type подписью T8:a, и разбор считал
+#: флажки текстовыми полями - то есть признак включённости лота, ради которого
+#: форму и снимали, со снимка не читался вовсе.
+#:
+#: Значения типа перечислены самим HTML: checkbox, hidden, text, submit. Чужого
+#: текста там не бывает, и проверяется это той же формой имени.
+_NAME_ATTRS: Final[frozenset[str]] = frozenset({"name", "type"})
+
+#: Форма имени поля берётся ГОТОВАЯ - _FIELD_NAME ниже. Второго описания одного
+#: правила заводить нельзя: копия расходится, и в этом же файле такое уже
+#: случалось с именем метода в адресе.
+
+#: Атрибуты, несущие метку языка.
+#:
+#: Сохраняются дословно, но только если значение вправду похоже на метку.
+#: Метка языка говорит о странице, а не о человеке: «ru» не сообщает о продавце
+#: ничего, чего не сообщал бы адрес площадки.
+#:
+#: Пока они маскировались, всякий снимок нёс в lang подпись, и разбор объявлял
+#: по нему локаль неподдержанной - собственные фикстуры заставляли реализацию
+#: говорить неправду.
+_LANGUAGE_ATTRS: Final[frozenset[str]] = frozenset({"lang", "hreflang"})
+
+#: Как выглядит метка языка по BCP 47.
+_LANGUAGE_TAG: Final[re.Pattern[str]] = re.compile(r"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$")
+
+#: Как выглядит ИМЯ ПОЛЯ - ключ объекта, который можно сохранить дословно.
+#:
+#: Ключом бывает и то, что написал человек, - в словаре, собранном из данных, -
+#: и один такой ключ отменяет правило для всего атрибута. Проверка та же, что у
+#: сборщика наблюдений: там на этом уже обожглись, записав вместе с ключами
+#: настоящие суммы операций.
+_FIELD_NAME: Final[re.Pattern[str]] = re.compile(r"^[A-Za-z_][A-Za-z0-9_.\[\]-]{0,64}$")
+
+#: Теги, содержимое которых не сохраняется.
+#:
+#: Выбрасывается только содержимое, атрибуты сохраняются по общим правилам. Путь
+#: в src обезличивается тем же преобразованием, что и остальные ссылки, поэтому
+#: прятать его незачем, а знать, какие скрипты грузит страница, нужно: по их
+#: путям обычно и виден адрес канала обновлений.
+_OPAQUE_TAGS: Final[frozenset[str]] = frozenset({"script", "style", "noscript", "template"})
+
+#: Теги, которые в HTML не имеют закрывающей пары.
+#:
+#: Список нужен затем, что запись ``<div/>`` в HTML не означает пустой элемент:
+#: разбор откроет div и вложит в него весь остаток документа. Для script это ещё
+#: хуже - его содержимое считается сырым текстом до закрывающего тега, которого
+#: нет, и в дерево не попадает вообще ничего. Скелет обязан читаться тем же
+#: парсером, что и страница, иначе он не годится ни в фикстуры, ни в проверку.
+_VOID_TAGS: Final[frozenset[str]] = frozenset(
+    {
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    }
+)
+
+#: Строгая форма подписи текстового узла.
+#:
+#: Проверка по этому выражению, а не по «начинается с T и содержит двоеточие»:
+#: строка вида ``Total: 500`` подходит под нестрогое условие и прошла бы
+#: самопроверку как подпись, унеся с собой настоящий текст страницы.
+_SIGNATURE_RE: Final[re.Pattern[str]] = re.compile(r"^T[1-9][0-9]*:[dacspo]+$")
+
+#: Подпись сегмента пути, содержащего цифры.
+_SEG_NUM: Final[str] = "{n}"
+
+#: Подпись сегмента пути, содержащего символы вне латиницы.
+_SEG_TEXT: Final[str] = "{t}"
+
+_RE_LATIN = re.compile(r"[A-Za-z]")
+_RE_DIGIT = re.compile(r"[0-9]")
+
+#: Признак того, что сегмент пути - идентификатор, а не слово маршрута.
+#:
+#: Цифра либо ЗАГЛАВНАЯ буква. Второе заведено версией v6: идентификаторы
+#: площадки - восемь заглавных латинских букв без единой цифры, и первый же
+#: снимок страницы отдельного заказа принёс /orders/SBVZKXAF/ дословно.
+#:
+#: Граница проведена по регистру потому, что слова маршрута пишутся строчными по
+#: соглашению об адресах. Ошибаться правило будет в сторону лишней маскировки, и
+#: это верная сторона.
+_RE_OPAQUE = re.compile(r"[0-9A-Z]")
+
+#: Имя метода в адресе: начинается со строчной, состоит из одних латинских
+#: букв, заглавные допускаются ВНУТРИ.
+#:
+#: РАСХОЖДЕНИЕ ДВУХ РЕАЛИЗАЦИЙ ОДНОГО ПРАВИЛА, и оно дорого обошлось. Браузерный
+#: сборщик получил это исключение 24.08.2026 - без него адрес загрузки файла
+#: /file/<имя метода> маскировался целиком, и операцию по такой записи собрать
+#: было нельзя. В Python правило не перенесли.
+#:
+#: Цена расхождения: снимок формы правки лота отдал адрес сохранения как
+#: /lots/{n12}. Имя метода - единственное, ради чего форму и снимали, - было
+#: скрыто, и добыть его предлагалось настоящим сохранением лота, то есть
+#: записью на площадке.
+#:
+#: Расширение доказуемо узкое. Сегмент из одних строчных букв правило пропускало
+#: и раньше: /orders/trade писался дословно. Меняется ровно одно - заглавная
+#: ВНУТРИ сегмента, который начинается со строчной и не имеет цифр. Ни один
+#: наблюдённый идентификатор площадки такой формы не имеет: восемь цифр у
+#: человека, девять у диалога, восемь ЗАГЛАВНЫХ у номера заказа - последний
+#: начинается с заглавной и остаётся замаскированным.
+_RE_ROUTE_NAME = re.compile(r"^[a-z][A-Za-z]{0,30}$")
+
+
+class SkeletonError(ValidationError):
+    """Скелет не удалось построить или он не прошёл самопроверку.
+
+    Наследуется от ValidationError, а не от встроенной ошибки языка. Прежде
+    здесь стоял RuntimeError, при том что класс экспортирован публично и
+    возникает у всякого, кто зовёт skeletonize: общий перехват FunoraError его
+    не ловил, и самопроверка, спасающая от утечки настоящего текста в снимок,
+    роняла процесс целиком вместо того, чтобы отдать отказ.
+
+    ValidationError - потому что произведённое значение непригодно: скелет,
+    не прошедший самопроверку, публиковать нельзя.
+    """
+
+
+def _char_class(ch: str) -> str:
+    """Определяет класс одного символа.
+
+    Args:
+        ch (str): Символ.
+
+    Returns:
+        str: Односимвольный код класса: d, a, c, s, p или o.
+    """
+    if ch.isspace():
+        return "s"
+    if ch.isdigit():
+        return "d"
+    if "A" <= ch <= "Z" or "a" <= ch <= "z":
+        return "a"
+    if "Ѐ" <= ch <= "ӿ":
+        return "c"
+    if ch.isascii() and not ch.isalnum():
+        return "p"
+    return "o"
+
+
+def text_signature(text: str) -> str:
+    """Строит подпись текстового узла.
+
+    Подпись сохраняет длину и состав текста, но не сам текст. Этого достаточно,
+    чтобы заметить изменение разметки и написать селектор, и недостаточно, чтобы
+    восстановить содержимое.
+
+    Args:
+        text (str): Исходный текст узла.
+
+    Returns:
+        str: Подпись вида ``T14:dps`` или пустая строка, если текст состоит
+        только из пробельных символов.
+    """
+    stripped = text.strip()
+    if not stripped:
+        return ""
+    normalized = unicodedata.normalize("NFC", stripped)
+    classes = "".join(sorted({_char_class(c) for c in normalized}))
+    return f"T{len(normalized)}:{classes}"
+
+
+def mask_path(
+    value: str,
+    own_host: str = DEFAULT_OWN_HOST,
+    ordinals: dict[str, int] | None = None,
+) -> str:
+    """Обезличивает значение атрибута, содержащего путь.
+
+    Правило разное для своего хоста и для чужого, и разница не в осторожности.
+
+    На своём хосте форма пути сохраняется: по ней узнаётся назначение ссылки,
+    а сегменты состоят из служебных слов площадки. Идентификатор заменяется
+    подписью, и признак его - цифра либо заглавная буква: идентификаторы
+    площадки бывают и вовсе без цифр, восемью заглавными латинскими буквами.
+
+    На чужом хосте маскируется весь путь. Ссылки на чужие адреса пишут люди в
+    переписке, и в них живёт то, ради чего их и пишут: ``t.me/ivanpetrov``,
+    ``vk.com/durov``. Прежнее правило маскировало сегмент, только если в нём
+    были цифры либо нелатинские знаки, - и такое имя проходило дословно в
+    снимок, который лежит в открытом репозитории. Имя хоста при этом остаётся:
+    оно публично и говорит, куда ведёт ссылка, не говоря, к кому.
+
+    Подпись идентификатора нумеруется в пределах документа: одинаковые значения
+    получают один номер, разные - разные. Без номеров восемь заказов на странице
+    неразличимы, и всякая проверка, опирающаяся на различимость, проходит
+    впустую, выглядя пройденной. Номер не раскрывает значения - он говорит
+    только, совпадают ли два.
+
+    Нумерация действует внутри одного документа и между документами смысла не
+    имеет: ``{n1}`` в двух снимках - разные вещи.
+
+    Args:
+        value (str): Исходное значение атрибута.
+        own_host (str): Хост площадки. Пути на нём сохраняют форму.
+        ordinals (dict[str, int] | None): Таблица номеров документа, общая для
+            всех его путей. None означает разовую маскировку вне документа: там
+            нумеровать не с чем и подпись остаётся безномерной.
+
+    Returns:
+        str: Обезличенный путь.
+    """
+    if not value:
+        return value
+
+    body = value
+    raw_query = ""
+    if "?" in body:
+        body, _, raw_query = body.partition("?")
+
+    host = urlparse(body).hostname
+    foreign = host is not None and not same_host(body, own_host)
+
+    query = ""
+    if raw_query:
+        # На чужом хосте строка запроса не разбирается и не нумеруется по той
+        # же причине, что и путь: там совпадение само по себе сведение о
+        # третьем лице. На своём разбирается по параметрам: имя выбирает
+        # площадка, значение - человек.
+        query = "?{q}" if foreign else "?" + _mask_query(raw_query, ordinals)
+
+    parts = body.split("/")
+    out: list[str] = []
+    for index, part in enumerate(parts):
+        if not part:
+            out.append(part)
+            continue
+        # Схема и имя хоста сохраняются всегда: они публичны и говорят, куда
+        # ведёт ссылка, не говоря, к кому. Схема нужна отдельно - по ней видно,
+        # защищено ли соединение.
+        if index == 0 and part.endswith(":"):
+            out.append(part)
+            continue
+        if foreign and host is not None and part.lower().split(":")[0] == host:
+            out.append(part)
+            continue
+        if foreign:
+            out.append(_SEG_TEXT)
+            continue
+        if _RE_ROUTE_NAME.match(part):
+            # Имя метода, а не идентификатор. То же исключение, что у браузерного
+            # сборщика: два описания одного правила обязаны совпадать, иначе
+            # снимок страницы и запись запроса говорят о площадке разное.
+            out.append(part)
+        elif _RE_OPAQUE.search(part):
+            out.append(_numbered(part, ordinals))
+        elif not part.isascii():
+            out.append(_SEG_TEXT)
+        else:
+            out.append(part)
+    return "/".join(out) + query
+
+
+def _mask_query(raw: str, ordinals: dict[str, int] | None) -> str:
+    """Обезличивает строку запроса, сохраняя ИМЕНА параметров.
+
+    ИМЯ ВЫБИРАЕТ ПЛОЩАДКА, ЗНАЧЕНИЕ - ЧЕЛОВЕК. Тот же довод, по которому
+    дословно сохраняются имена полей формы и имена методов в пути: имя - это
+    словарь площадки, а не чьи-то данные.
+
+    Цена прежнего правила названа в spec/extraction/market.yaml: идентификатор
+    ЧУЖОГО предложения лежит только в строке запроса ссылки, и снимок отдавал
+    её одной подписью «?{q7}». Из-за этого market.offers - объявленная
+    операция - не собиралась вовсе, а причиной называли модель.
+
+    Собирающий заново описывает то же правило, что браузерный сборщик, у
+    которого имена параметров сохранялись с самого начала: там записан
+    searchParams.keys(). Два описания одного правила разошлись, и разошлись
+    молча - ровно так же, как перед этим разошлось имя метода в пути.
+
+    ЗНАЧЕНИЕ НЕ РАСКРЫВАЕТСЯ НИКОГДА и по-прежнему нумеруется: одинаковые
+    значения получают один номер, и без этого пятьдесят диалогов страницы
+    неразличимы.
+
+    Аргументы:
+        raw (str): Строка запроса без ведущего знака вопроса.
+        ordinals (dict[str, int] | None): Таблица номеров документа.
+
+    Возвращает:
+        str: Обезличенная строка запроса.
+    """
+    out: list[str] = []
+    for pair in raw.split("&"):
+        name, sign, value = pair.partition("=")
+        if not _FIELD_NAME.match(name):
+            # Имя незнакомой формы маскируется целиком вместе со значением:
+            # раз оно не похоже на словарь площадки, оно может быть данными.
+            number = _ordinal(pair, "query", ordinals)
+            out.append("{q}" if number is None else f"{{q{number}}}")
+            continue
+        if not sign:
+            # Параметр без значения - одно только имя. Раскрывать нечего.
+            out.append(name)
+            continue
+        number = _ordinal(value, "query", ordinals)
+        out.append(f"{name}=" + ("{q}" if number is None else f"{{q{number}}}"))
+    return "&".join(out)
+
+
+def _ordinal(value: str, kind: str, ordinals: dict[str, int] | None) -> int | None:
+    """Выдаёт номер значения в пределах документа.
+
+    Номер выдаётся по первому появлению и повторно не выдаётся: два вхождения
+    одного значения получают один номер, два разных - разные. Само значение
+    никуда не попадает: таблица живёт в памяти и выбрасывается вместе с
+    документом.
+
+    Разряды нумеруются раздельно. Совпадение номера пути с номером атрибута
+    ничего не значило бы и только вводило бы в заблуждение: путь и подпись -
+    разные пространства значений.
+
+    Args:
+        value (str): Исходное значение.
+        kind (str): Разряд нумерации: путь, строка запроса, атрибут.
+        ordinals (dict[str, int] | None): Таблица номеров документа либо None,
+            если маскируется отдельное значение вне документа.
+
+    Returns:
+        int | None: Номер либо None, если нумеровать не с чем.
+    """
+    if ordinals is None:
+        return None
+    key = f"{kind}\x1f{value}"
+    if key not in ordinals:
+        # Номер отсчитывается внутри разряда, а не сквозным счётчиком: сквозной
+        # выдал бы заказу номер 7 только потому, что до него встретилось шесть
+        # чужих значений, и перестановка разметки меняла бы все номера сразу.
+        ordinals[key] = sum(1 for name in ordinals if name.startswith(f"{kind}\x1f")) + 1
+    return ordinals[key]
+
+
+def _numbered(part: str, ordinals: dict[str, int] | None) -> str:
+    """Возвращает подпись сегмента пути с номером в пределах документа.
+
+    Args:
+        part (str): Исходный сегмент пути.
+        ordinals (dict[str, int] | None): Таблица номеров документа.
+
+    Returns:
+        str: Подпись вида ``{n3}`` либо безномерная ``{n}``.
+    """
+    number = _ordinal(part, "path", ordinals)
+    return _SEG_NUM if number is None else f"{{n{number}}}"
+
+
+def _keys_look_like_field_names(value: object) -> bool:
+    """Сообщает, состоят ли ключи объекта из одних имён полей.
+
+    Проверяются ключи ВСЕХ уровней вложенности. Проверка одного уровня
+    пропустила бы словарь внутри словаря - а туда и складывают то, что пришло из
+    данных.
+
+    Args:
+        value (object): Разобранное значение JSON.
+
+    Returns:
+        bool: True, если ни один ключ на именование поля не притворяется.
+    """
+    if isinstance(value, dict):
+        return all(
+            isinstance(key, str)
+            and _FIELD_NAME.match(key) is not None
+            and _keys_look_like_field_names(item)
+            for key, item in value.items()
+        )
+    if isinstance(value, list):
+        return all(_keys_look_like_field_names(one) for one in value)
+    return True
+
+
+def _mask_json(value: object, ordinals: dict[str, int]) -> object:
+    """Маскирует значения объекта, сохраняя его ключи.
+
+    Дословно не сохраняется ни одно значение: правило про ключи, и только про
+    них. Читаемым становится ПУТЬ до значения, а не само значение.
+
+    Args:
+        value (object): Разобранное значение JSON.
+        ordinals (dict[str, int]): Таблица номеров документа.
+
+    Returns:
+        object: То же по строению, с замаскированными значениями.
+    """
+    if isinstance(value, dict):
+        return {key: _mask_json(item, ordinals) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_mask_json(one, ordinals) for one in value]
+    if isinstance(value, bool) or value is None:
+        # Булево и пустота значениями в смысле утечки не являются: они не несут
+        # ни имени, ни суммы, ни текста.
+        return value
+    # Число маскируется подписью СВОЕЙ ЗАПИСИ, а не остаётся числом:
+    # восьмизначное число - это идентификатор человека, а не количество.
+    return text_signature(str(value))
+
+
+def _mask_attr(name: str, value: str, ordinals: dict[str, int]) -> str:
+    """Обезличивает значение произвольного атрибута.
+
+    Args:
+        name (str): Имя атрибута в нижнем регистре.
+        value (str): Исходное значение.
+        ordinals (dict[str, int]): Таблица номеров документа.
+
+    Returns:
+        str: Значение, пригодное для хранения в репозитории.
+    """
+    if name in _VERBATIM_ATTRS:
+        return value
+    if name in _NAME_ATTRS and _FIELD_NAME.match(value.strip()):
+        # Условие про форму существенно ровно так же, как у метки языка:
+        # атрибут обычный, и положить в него можно что угодно.
+        return value.strip()
+    if name in _LANGUAGE_ATTRS and _LANGUAGE_TAG.match(value.strip()):
+        # Условие про форму существенно: атрибут обычный, и положить в него
+        # можно что угодно. Дословно сохраняется лишь то, что вправду похоже на
+        # метку языка, остальное маскируется по общему правилу.
+        return value.strip()
+    if name in _URL_ATTRS:
+        return mask_path(value, DEFAULT_OWN_HOST, ordinals)
+
+    # Атрибут-объект сохраняет КЛЮЧИ и маскирует значения - правило формата v8.
+    #
+    # Заведено ради одного места, и место это перекрывает семь операций: защитный
+    # токен площадки лежит в объекте JSON атрибута data-app-data. Пока атрибут
+    # маскировался целиком, разбор, достающий оттуда токен, проверить было не на
+    # чем.
+    #
+    # Правило узкое по построению: значение обязано быть объектом, и каждый его
+    # ключ - иметь вид имени поля. Один ключ, пришедший из данных, отменяет
+    # правило для всего атрибута.
+    #
+    # Проверка на фигурную скобку - про ЦЕНУ, а не про правильность: отсечь
+    # лишнее и без неё способна проверка типа разобранного. Она измерена, и
+    # потому осталась: на корне площадки одиннадцать с половиной тысяч значений
+    # атрибутов, из которых с фигурной скобки начинаются сорок семь. Разбор
+    # всех подряд обходится в девятнадцать раз дороже.
+    #
+    # Отсюда следствие для мутационной проверки: мутация, снимающая эту строку,
+    # ВЫЖИВАЕТ, и это верно. Она меняет цену, а не поведение, и ловить её
+    # набором проверок было бы ловлей часов - измерение времени в наборе даёт
+    # ложные срабатывания чаще, чем находит правду.
+    stripped = value.strip()
+    if stripped.startswith("{"):
+        try:
+            parsed = json.loads(stripped)
+        except ValueError:
+            parsed = None
+        if isinstance(parsed, dict) and _keys_look_like_field_names(parsed):
+            return json.dumps(_mask_json(parsed, ordinals), ensure_ascii=False, sort_keys=True)
+    if not value:
+        return value
+    sig = text_signature(value)
+    if not sig:
+        return ""
+    # К подписи атрибута добавляется номер. Подпись остаётся на месте: по ней
+    # видно длину и состав, и терять их нельзя - именно на длинах строились
+    # выводы о позициях сообщений. Номер добавляет ровно одно сведение: два
+    # значения совпадают или нет.
+    #
+    # На текстовые узлы это не распространяется. Атрибут - разметка, текст -
+    # содержимое; равенство двух сообщений переписки никакой проверке не нужно,
+    # а сведением о переписке является.
+    number = _ordinal(value, f"attr:{name}", ordinals)
+    return sig if number is None else f"{sig}#{number}"
+
+
+def _render(node: Node, out: list[str], depth: int, ordinals: dict[str, int]) -> None:
+    """Рекурсивно записывает узел в выходной буфер.
+
+    Args:
+        node (Node): Узел документа.
+        out (list[str]): Буфер строк результата.
+        depth (int): Текущая глубина вложенности, для отступов.
+        ordinals (dict[str, int]): Таблица номеров документа. Общая на весь
+            обход: номер выдаётся по первому появлению значения, и порядок
+            обхода делает нумерацию повторяемой.
+
+    Returns:
+        None: Результат накапливается в out.
+    """
+    tag = node.tag
+    pad = "  " * depth
+
+    if tag == "-text":
+        sig = text_signature(node.text_content or "")
+        if sig:
+            out.append(f"{pad}{sig}")
+        return
+
+    if tag in ("-comment", "_comment"):
+        return
+
+    attrs = node.attributes or {}
+    rendered: list[str] = []
+    for name in sorted(attrs):
+        raw = attrs[name]
+        if raw is None:
+            rendered.append(name)
+            continue
+        masked = _mask_attr(name.lower(), raw, ordinals)
+        # Кавычка экранируется, иначе значение рвёт собственный атрибут.
+        #
+        # До формата v8 это не имело значения: маскированное значение кавычек не
+        # содержало никогда. Атрибут-объект их содержит, и неэкранированный он
+        # сделал бы снимок неразбираемым - то есть бесполезным ровно для того,
+        # ради чего заводился.
+        rendered.append(f'{name}="{masked.replace(chr(34), "&quot;")}"')
+
+    head = tag if not rendered else tag + " " + " ".join(rendered)
+
+    if tag in _OPAQUE_TAGS:
+        out.append(f"{pad}<{head}></{tag}>")
+        return
+
+    children = list(node.iter(include_text=True))
+    if not children:
+        if tag in _VOID_TAGS:
+            out.append(f"{pad}<{head}/>")
+        else:
+            out.append(f"{pad}<{head}></{tag}>")
+        return
+
+    out.append(f"{pad}<{head}>")
+    for child in children:
+        _render(child, out, depth + 1, ordinals)
+    out.append(f"{pad}</{tag}>")
+
+
+def _self_check(skeleton: str) -> None:
+    """Проверяет, что в скелете не осталось человекочитаемого текста.
+
+    Самопроверка нужна, потому что скелет строится обходом дерева, а дерево
+    приходит от стороннего парсера: изменение его поведения не должно тихо
+    превратить безопасный формат в небезопасный.
+
+    Args:
+        skeleton (str): Готовый скелет.
+
+    Raises:
+        SkeletonError: Если найдена последовательность, похожая на текст.
+    """
+    for line in skeleton.splitlines():
+        body = line.strip()
+        if not body:
+            # Пустая строка появляется у сохранённого снимка в конце файла.
+            # Без этого условия готовую фикстуру нельзя перепроверить тем же
+            # кодом, которым она построена, - а перепроверять её придётся при
+            # каждой смене формата.
+            continue
+        if _SIGNATURE_RE.match(body):
+            continue
+        if not body.startswith("<"):
+            raise SkeletonError(f"строка не является ни подписью, ни тегом: {body[:60]}")
+        if any("Ѐ" <= ch <= "ӿ" for ch in body):
+            raise SkeletonError(f"кириллица в структурной строке: {body[:60]}")
+
+
+def skeletonize(html: str) -> str:
+    """Строит структурный скелет страницы.
+
+    Args:
+        html (str): Исходный HTML страницы.
+
+    Returns:
+        str: Скелет: дерево тегов с подписями текстовых узлов вместо текста.
+
+    Raises:
+        SkeletonError: Если разбор не удался или самопроверка нашла текст.
+    """
+    if not html or not html.strip():
+        raise SkeletonError("пустой документ")
+
+    try:
+        tree = HTMLParser(html)
+    except Exception as exc:
+        raise SkeletonError("документ не разбирается как HTML") from exc
+
+    root = tree.root
+    if root is None:
+        raise SkeletonError("документ не содержит корневого узла")
+
+    out: list[str] = []
+    # Таблица номеров создаётся на документ и живёт только во время обхода.
+    # Значений она не сохраняет никуда: нумерация нужна затем, чтобы по снимку
+    # было видно, какие ссылки совпадают, а какие нет.
+    _render(root, out, 0, {})
+    skeleton = "\n".join(out) + "\n"
+    _self_check(skeleton)
+    return skeleton