docmost-sync/test-strategy-report.md

Отчёт по тест-стратегии — docmost-sync — 2026-06-16

Двунаправленная синхронизация статей Docmost с локальным Markdown-git-хранилищем (git — хранилище состояния). Монорепо: корневое приложение-движок (src/) + библиотека packages/docmost-client (~7.5k LOC). Стек: TypeScript ESM, Node ≥ 20, Vitest 3.2.6. Все тесты лежат в корневом test/ (include: ['test/**/*.test.ts']).

1. Исполнительное резюме

• Проанализировано модулей: 9 (1 субагент module-testability-analyst на модуль, все завершились).
• Предложено тестов (unit / integration / contract / E2E): 50 / 7 / 1 / 2 (итого 60).
  • unit = 83 % (≥ 70 % ✓), integration = 12 % (≤ 20 % ✓), E2E = 3 % и 2 шт. (≤ 5 % и ≤ 10 ✓).
• Отклонено как малоценные: ≈ 60 символов/областей (декларативные spec-объекты схемы, тривиальные плоские мапперы, framework-обвязка, type-only интерфейсы, passthrough-обёртки).
• Покрытие сейчас (проверено v8 лично): 2.6 % statements по обоим пакетам (искажено огромным непокрытым docmost-client). Изолированно: корневое приложение ≈ 40 %, пакет docmost-client ≈ 0 % (поведенчески покрыт лишь collectRecentSince). Прогноз после Фаз 1–4: ≈ 60–65 % (чистые lib-модули 80 %+, корневое приложение ≈ 85 %, транспортный client.ts ≈ 40 %).

⚠️ Артефакт измерения покрытия. package.json пакета указывает main: dist/index.js, поэтому import from 'docmost-client' грузит скомпилированный dist/, а не src/. v8 меряет src/ → показывает client.ts 0 %, хотя collectRecentSince реально исполняется. Перед измерением покрытия добавить в vitest.config.ts alias docmost-client → packages/docmost-client/src/index.ts (или мерить по dist после сборки), иначе любые новые тесты библиотеки не отразятся в отчёте. @vitest/coverage-v8 и скрипт "coverage" в проекте отсутствуют — их нужно добавить.

2. Рекомендации по модулям

app-root (src/) — движок синка, конфиг, sanitize, round-trip-харнесс

• Извлечь в чистые функции: folderSegmentsFor (pull.ts:88, замкнута внутри main), firstDivergence/parseArgs (roundtrip.ts:101/64, не экспортированы).
• Unit добавить: firstDivergence (равные/разные деревья, путь расхождения, циклы) — ловит ложное «stable» при реальном расхождении (вся суть харнесса); nameForNode (коллизии имён сиблингов → перезапись файлов на диске); folderSegmentsFor (вложенность + защита от цикла parent A→B→A, иначе зависание); parseArgs; ветка invalid-value в loadSettingsOrExit (config-errors.ts:27-30, единственный значимый пробел).
• Integration добавить: pull.main с фейковым клиентом + временной директорией (один файл на страницу, верные папки, узлы без id пропускаются) — после R-App-4.
• НЕ тестировать: index.ts (тонкий CLI-passthrough, только console.log); envSchema (тестировать = тестировать Zod, покрыт через parseSettings); тело roundtrip.main (байт-стабильность уже покрыта roundtrip.test.ts); invokedDirectly-guard-блоки; sanitizeTitle/disambiguate/parseSettings/stripBlockIds (уже ~100 %).

client-core (packages/docmost-client/src/client.ts, ~2770 строк) — god-object REST+WS клиент

• Извлечь в чистые функции: валидаторы isSafeUrl/validateDocUrls/validateDocStructure (client.ts:905/941/1004), imageMimeFromPath/buildImageNode (1844/1864) — поднять в lib/ рядом с filters.ts; распаковку конвертов и clamp-логику пагинации (378-393, 1505) в pure-функции.
• Unit добавить: XSS-allowlist isSafeUrl+validateDocUrls (javascript:/data:/file:, пробельно-контрольный обход java\tscript:, на всех медиа-узлах) — высший приоритет по безопасности; validateDocStructure (глубина > 200, не-string type); расширить collectRecentSince (граница updatedAt === sinceIso, элементы без id/updatedAt); imageMimeFromPath+buildImageNode; paginateAll (стоп-условия, MAX_PAGES=50 + предупреждение, clamp 1..100, оба конверта) — после R-Client-2; appUrl/shareUrl/parseCommentContent; sandbox transformPage (node:vm: нет require/process/fs, таймаут 5 c, не-функция/не-doc → throw) — security.
• Integration добавить (после R-Client-1, инъекция HTTP): авто-реавторизация (401-интерсептор + дедуп login + getCollabTokenWithReauth: один retry, /auth/login не ретраится, loginPromise сбрасывается в finally); uploadImage (порядок guard ext→stat→read, > 20 MiB, пересборка FormData на 401, нет утечки тела ответа в ошибку); createPage (replay multipart на 401); checkNewComments (битая дата → throw, а не «ничего нового»; граница createdAt > since; флаг truncated).
• НЕ тестировать: тонкие REST-passthrough (getWorkspace/getSpaces/renamePage/movePage/ deletePage/restorePage/listTrash и пр.) — конверт data.data ?? data покрыть один раз извлечённой функцией; делегаты в node-ops/converter/diff (тестировать в их модулях); сами axios/yjs/hocuspocus.

markdown-conversion (lib/markdown-converter.ts + markdown-document.ts) — конвертер ProseMirror↔Markdown

• Unit добавить: табличная golden-матрица по типам узлов (заголовки, маркированные/кодовые спаны, ссылки с title, картинки с пробелами/скобками в src, кодоблоки с языком + срез хвостовых \n, GFM-таблицы с выравниванием, spanned-таблицы → <table>, blockquote, task-list, math a < b, mention/attachment/callout/details/columns/медиа, hr, hard break, неизвестный тип, пустой doc → ""); идемпотентность экранирования (escapeAttr стабилен на & ", encodeMdUrl пробел→%20), отступы вложенных списков (indentItemChildren); envelope parseDocmostMarkdown/serializeDocmostMarkdown (восстановление meta/body/comments, CRLF, «последний docmost:comments-блок побеждает», throw на битом JSON); edge/malformed-вход (null/{}/нет content, отсутствующие attrs, глубокая вложенность без переполнения стека).
• Integration добавить: property-тест round-trip идемпотентности — md→PM→md == md байт-в-байт
  • семантическая стабильность через stripBlockIds. Самый ценный тест проекта (фантомные git-диффы — ровно то, ради чего существует харнесс). Требует фабрику документов и генератор (см. §3).
• НЕ тестировать: интерфейс DocmostMdMeta; одиночный токен {{SUBPAGES}}; внутренности marked/@tiptap/html; underline/sub/sup как отдельные тесты — свернуть в один inline-marks-кейс.

prosemirror-schema (lib/docmost-schema.ts, ~1065 строк) — ~90 % декларативный конфиг

• Unit добавить (ровно 2, намеренно не раздуваем): sanitizeCssColor (:44) — allowlist против CSS/style-инъекции: принять named/hex3-8/rgb(a)/hsl(a), отвергнуть red; --x:url(), expression(...), red"><script>, пустое/не-string; clampCalloutType (:21) — нормализация enum + регистр + фолбэк info.
• НЕ тестировать: все Node.create/Mark.create/Extension.create spec-объекты (~26 шт.) и триплеты default/parseHTML/renderHTML — декларативные данные, тест тавтологичен; поведение узлов проверяется косвенно через round-trip (другой модуль). Closures textStyle.getAttrs, Highlight-guard, Column.width — покрыть HTML-фикстурами round-trip, не лезть в приватные closures.

node-ops (lib/node-ops.ts, ~897 строк) — чистые структурные операции над деревом узлов

• Unit добавить (все unit, высочайший ROI — JSON-вход/JSON-выход): insertNodeRelative (append/before/after, by-id/by-anchor, маршрутизация структурных узлов, throw-ветки, offset); insertTableRow (индекс/паддинг/наследование типа и colwidth заголовка, OOB→append); replaceNodeById (изоляция клонов на N совпадений, без рекурсии в подставленный узел); getNodeByRef (#n in/out-of-range, дубль id → первый, гарантия клона); updateTableCell (переиспользование id первого параграфа, сохранение colspan/rowspan, OOB→throw); deleteNodeById/deleteTableRow (throw vs тихий no-op); sanitizeForYjs+findUnstorableAttr (срез undefined, путь до bigint/function); buildOutline+readTable+ blockPlainText (cols из row-0, усечение, ragged-таблицы). Везде ассерт «вход не мутирован».
• Извлечь/рефактор: инъекция makeFreshId (:591, Math.random()) — для точных ассертов на id в insertTableRow/updateTableCell; иначе проверять формат+уникальность без рефактора.
• НЕ тестировать: интерфейсы OutlineEntry/InsertOptions; внутренние clone/isObject/matchesId/ truncate/makeCellParagraph/locateTable (покрыты транзитивно); недостижимый fallback structuredClone.

collaboration (lib/collaboration.ts, ~618 строк) — чистый верх + транспортный низ (Yjs/Hocuspocus/WS)

• Unit добавить (чистый верх, без рефактора): buildCollabWsUrl (http→ws, https→wss, срез /api, /collab ровно один раз, drop query/hash, fallback на битый URL); buildYDoc/assertYjsEncodable (валид кодируется; undefined-attr санитайзится; неэнкодируемый attr → ошибка с путём; dryRun==apply); bridgeTaskLists (ol со всеми чекбоксами → ul taskList, без фантомного orderedList); preprocessCallouts (::: внутри кодоблока не считается забором; незакрытый callout); replacePageContent (guard не-doc → throw).
• Unit (после рефактора R-Collab-1): ядро onSynced read-transform-write — пустой live-doc → дефолт, transform→null без записи, transform throw пробрасывается, фрагмент заменяется полностью. Защищает от потери данных при конкурентном редактировании (инвариант «без await между read и write»).
• Unit (после R-Collab-2): подавление ложного успеха — unsyncedChanges→0 при разрыве не считается успехом (флаг connectionLost); ловит «ложную персистенцию» / reconnect-шторм как успешную запись.
• Integration: mutatePageContent против mock-Hocuspocus-сервера (после R-Collab-2/3 + fake-таймеры).
• НЕ тестировать: updatePageContentRealtime (passthrough); глобальная мутация window/document/ WebSocket на импорте (env-обвязка); внутренности yjs/hocuspocus/marked.

transforms (lib/transforms.ts, ~477 строк) — чистые примитивы трансформации документа

• Unit добавить: commentsToFootnotes — перенумерация/порядок (маркеры не по порядку массива → [1]..[k] в порядке чтения, список заметок переупорядочен) и иммутабельность входа + throw на несогласованности ([9] при 3 заметках, нет heading/orderedList); insertMarkerAfter (сплит по нескольким text/mark-ранам, маркер plain, окружающие марки сохранены, scope beforeBlock); setCalloutRange (статичность regex lastIndex на двух text-узлах, только внутри callout, Unicode … и ASCII ...); mdToInlineNodes (срез префиксов комментарий:/N., граница **bold**-лида, пробел не теряется); walk/getList (полнота обхода, live-ссылка не клон).
• Извлечь/рефактор: инъекция freshId (:240) — опционально, для воспроизводимого dryRun.
• НЕ тестировать: blockText (re-export node-ops.blockPlainText); splitInlineBold (внутр.); clone/isObject/freshId; интерфейсы. Sandbox-eval (doc,ctx)=>doc живёт в client.ts, не здесь.

diff (lib/diff.ts, ~319 строк) — headless-дифф документов (чистый, детерминированный)

• Unit добавить: diffDocs (вставка/удаление/идентичность + пустые doc; счётчики inserted/deleted); подсчёт целостности (images/tables/callouts old→new, дедуп ссылки, разбитой на два рана; битая ссылка считается 1 раз); footnoteMarkers (граница body/notes по notesHeading, порядок чтения, кастомный/отсутствующий heading); coarse-fallback (форс-исключение precise-пути → нет throw, есть пометка о деградации, whitespace-блоки не репортятся); blockContextAt+ blocksChanged (усечение >80, не-пустой контекст ловит проглоченный catch, дедуп блоков).
• НЕ тестировать: getSchema(docmostExtensions) (обвязка); сам алгоритм recreateTransform/ChangeSet/simplifyChanges; интерфейсы; точный порядок строк секции Changes в markdown (порядок задаёт библиотека — проверять множества/счётчики).

client-utils (lib/auth-utils.ts + filters.ts + json-edit.ts + page-lock.ts, 345 строк)

• Unit добавить: applyTextEdits (json-edit.ts:45) — полный набор: single/replaceAll, multi-match без replaceAll → throw, «not found» vs «spans multiple formatting runs», литеральная вставка $&/$1 (явный foot-gun String.replace), обрезка пустых узлов, иммутабельность входа; withPageLock (page-lock.ts:16) — сериализация одной страницы, конкурентность разных, ошибка не «отравляет» очередь, реальный reject доходит до вызывающего (через deferred-промисы, не sleep); performLogin парсинг cookie (точное имя authToken ≠ authTokenRefresh, base64-= не обрезается); filterPage (условный spread: content === "" включается, не-string опускается); getCollabToken (распаковка data.data.token→data.token, err.status выживает, тело ответа не утекает без DEBUG); filterComment (?? vs ||: пустая строка markdownContent сохраняется).
• НЕ тестировать: filterWorkspace/filterSpace/filterGroup (плоские мапперы без ветвлений — максимум один общий shape-ассерт); интерфейсы TextEdit/TextEditResult; приватные collectText/countOccurrences/truncate.

3. Сквозные аспекты

• Contract-тесты (1 набор): между docmost-client и живым Docmost — записанные фикстуры/pact-стиль, проверяющие конверты ответов (data.data ?? data, items-vs-bare-array, meta.hasNextPage), от которых зависит весь клиент. Привязать к закреплённой версии Docmost; ловит дрейф контракта API.
• Property-based (через извлечение чистых функций): (1) round-trip Markdown — корона стратегии; (2) инварианты иммутабельности node-ops; (3) идемпотентность commentsToFootnotes/setCalloutRange. Рекомендуется dev-зависимость fast-check (с воспроизводимым seed + shrinking).
• Дымовые/нагрузочные: неприменимо (нет высоконагруженных путей); пропустить.
• Test-data factories (нужны): билдер ProseMirror-документов (узлы/марки) для golden+property-тестов; фабрика конвертов REST-ответов Docmost; фабрика login/Set-Cookie-ответа; корпус фикстур для round-trip (расширить test/fixtures/sample-doc.json).

4. Обнаруженные антипаттерны

• God-объект: DocmostClient — ~2770 строк, ~58 членов (auth + REST + WS + FS + comments + vm-sandbox) в одном классе (client.ts). Нет шва для изоляции одной ответственности.
• Скрытые побочные эффекты на импорте: глобальная мутация global.window/document/Element/WebSocket (collaboration.ts:13-19) — импорт модуля меняет глобал воркера; конструктор DocmostClient вешает axios-интерсептор и создаёт реальный axios.
• Нетестируемые синглтоны / общее состояние: модульная Map chains (page-lock.ts:11) — состояние течёт между тестами в одном воркере (изолировать pageId/vi.resetModules()); Math.random() в node-ops.ts:591 (makeFreshId) и transforms.ts:240 (freshId) — недетерминизм id.
• Порядко-зависимые тесты (риск): чтение process.env.DEBUG в auth-utils.ts (set/unset + restore); глобалы collaboration; общая chains-Map.
• Артефакт покрытия dist-vs-src: main: dist/index.js → тесты исполняют скомпилированный код, v8 меряет src → ложные 0 % (см. §1).
• Чистая логика в ловушке async main(): pull.ts/roundtrip.ts — поэтому 0 %/19 % при наличии тестируемой чистой логики.
• node:vm исполняет пользовательский JS (client.ts::transformPage, ~2491) — security, нужен явный тест на отсутствие escape (require/process/fs) и таймаут.
• Проглоченные ошибки: diff.ts:172 (catch{return ""} маскирует баг резолвера позиции); пустые catch в cleanup collaboration. Статичный lastIndex regex /g в transforms.ts:216.
• Нестабильные тесты (CI-история): н/д — CI-история отказов отсутствует (проект на Increment 1, тесты только базовые); пункт неактуален сейчас.

5. Необходимые рефакторинги перед написанием тестов

• R-App-1 — извлечь folderSegmentsFor на верхний уровень + экспортировать nameForNode. Блокирует: unit-тесты путей pull.ts (коллизии, защита от цикла).
• R-App-2 — экспортировать parseArgs и firstDivergence (roundtrip.ts). Блокирует: unit-тесты дивергенции и парсинга аргументов.
• R-App-4 — инъекция клиента + fs в pull.main. Блокирует: integration-тест pull.main.
• R-Client-1 — инъекция HTTP-клиента (axios-instance + multipart-poster). Блокирует: все integration-тесты REST (auth-реавторизация, uploadImage, createPage, checkNewComments).
• R-Client-2 — извлечь pure-функции маппинга ответов/конвертов/clamp. Блокирует: перевод ~15 кейсов из integration в быстрый unit (paginateAll, list-endpoints).
• R-Client-3 — инъекция collab-транспорта (mutatePageContent/provider-factory). Блокирует: unit-тесты оркестрации patch/insert/delete/table/comment.
• R-Client-4 — поднять чистые валидаторы (isSafeUrl/validateDocUrls/validateDocStructure/ imageMimeFromPath/buildImageNode) в lib/ или экспортировать. Блокирует: XSS-unit-тесты (высший приоритет).
• R-Collab-1 — извлечь тело onSynced в чистую applyTransformToYdoc(ydoc, transform). Блокирует: unit ядра read-transform-write (потеря данных).
• R-Collab-2 + R-Collab-3 — инъекция provider-factory и часов (fake-таймеры). Блокируют: тесты ложного успеха/таймаутов и integration mutatePageContent.
• R-NodeOps / R-Transforms — инъекция makeFreshId/freshId (опционально). Блокируют: только точные ассерты на id; без рефактора — проверять формат+уникальность.
• Инфраструктура — добавить @vitest/coverage-v8 + скрипт "coverage"; alias docmost-client→src в vitest.config.ts; dev-deps fast-check (property) и mock-ws/msw (integration). Эти изменения трогают конфиги/package.json — вне правки данного отчёта, заложить в Фазу 1.

6. План внедрения (по фазам)

• Фаза 1 — чистые unit, нулевой/малый рефактор (наивысший ROI). node-ops (8), transforms (5–6), diff (5), client-utils (6), guards схемы (2), golden-матрица + envelope конвертера (3), чистый верх collaboration (5), чистые валидаторы клиента после R-Client-4 (XSS + structure + image), расширение collectRecentSince, app-root после R-App-1/2 (5). Плюс инфраструктура покрытия/alias. ROI: мгновенно поднимает покрытие самой дефектоопасной чистой логики (потеря данных, XSS) почти без риска.
• Фаза 2 — корона: property-тест round-trip Markdown + фабрика документов. Ловит фантомные git-диффы и неидемпотентность — главный класс дефектов всего инструмента синхронизации.
• Фаза 3 — refactor-gated unit. R-Collab-1 → ядро onSynced (потеря данных при конкуренции); R-Client-2 → unit пагинации/list-endpoints; sandbox transformPage (security).
• Фаза 4 — integration с DI. R-Client-1/3 → авто-реавторизация, uploadImage, createPage, checkNewComments; R-Collab-2/3 → подавление ложного успеха + e2e против mock-WS; R-App-4 → pull.main.
• Фаза 5 — contract + E2E. 1 contract-набор против закреплённой версии Docmost; 2 E2E-смоука против docker-compose Docmost — user journeys: (1) «pull пространства в vault» (страницы → файлы с верной иерархией), (2) «round-trip страницы без фантомного diff».

7. Источники

• Отчёты 9 субагентов module-testability-analyst (app-root, client-core, markdown-conversion, prosemirror-schema, node-ops, collaboration, transforms, diff, client-utils).
• Вывод coverage-инструмента: vitest run --coverage (provider v8), запущен оркестратором лично; 6 тест-файлов / 33 теста зелёные; overall 2.6 % statements (артефакт dist-vs-src учтён).
• Фильтрация предложений:
  • Шаг 1 (кросс-модульный дедуп): снято ≈ 20 (поведение схемы → round-trip; делегаты client.ts → модули node-ops/converter/diff; blockText → node-ops).
  • Шаг 2 (skip-list): снято ≈ 40 (декларативные spec-объекты схемы ~26, плоские фильтры 3, type-only интерфейсы, framework-обвязка, index.ts, passthrough-обёртки).
  • Шаг 3 (бюджет пирамиды): E2E сведены к 2; множество per-endpoint integration свёрнуты в paginateAll
    • представительные кейсы.
  • Шаг 6 (adversarial): оставлены только тесты с конкретными ассертами, падающими при реалистичной поломке (отказ XSS-схем, байт-равенство round-trip, порядок перенумерации сносок); тавтологичные ассерты атрибутов схемы отброшены.