@taskless-app/shared 0.1.34 → 0.1.36

package/dist/importPackage.js

@@ -0,0 +1,657 @@
+import { z } from "zod";
+// MOVE-7: ПАКЕТ ИМПОРТА — нейтральный формат, в который коннектор перекладывает
+// чужой сервис (Confluence, Notion, что угодно ещё). Ядро импорта читает ТОЛЬКО
+// его и про исходный сервис не знает ничего.
+//
+// ФОРМА ВЗЯТА ИЗ СПЕКИ: docs/superpowers/specs/2026-08-25-external-import-design.md,
+// раздел «Пакет импорта». Имена полей повторяют её пример один в один
+// (people/name, spaceId/parentId/authorId/assigneeId, on, file/mime/name) —
+// по спеке будут писаться MOVE-9 и все следующие коннекторы, и расхождение в
+// фундаменте размножилось бы на каждый из них.
+//
+// Почему формат живёт в shared, а не в api: потребителей у него минимум трое —
+// коннектор (пишет пакет), ядро импорта в api (читает и раскладывает по нашим
+// таблицам) и web (показывает человеку, что приехало и что попало в карантин).
+// Отсюда ограничение: shared публикуется в npm, поэтому здесь НЕТ ни Prisma,
+// ни путей на диске, ни импортов из api — только форма данных и чистые функции.
+//
+// ТЕЛО ЕДЕТ HTML, А НЕ ProseMirror. Иначе КАЖДЫЙ коннектор обязан знать схему
+// нашего редактора, а она живёт во фронтовом пакете и меняется по нашим
+// причинам. Перевод HTML → наш документ делает ядро, один раз на всех.
+//
+// ЧТО НАМЕРЕННО НЕ СДЕЛАНО. Сущности лежат в манифесте ЦЕЛИКОМ, а не по файлу
+// на страницу: пакет читается разом, и один JSON проще и коннектору, и ядру.
+// Когда появится экспорт, который в память не влезает, это будет formatVersion 2
+// — ради чего версия и заведена. Отдельно лежат только файлы вложений.
+/**
+ * Версия формата, которую пишет сегодняшний коннектор и понимает сегодняшнее
+ * ядро. Растёт на ЛОМАЮЩЕМ изменении формы; добавление необязательного поля
+ * версию не двигает — старое ядро прочитает такой пакет, не заметив нового поля.
+ *
+ * В примере спеки версии нет, но задача требует её прямо: «схема обязана быть
+ * версионированной, иначе завтрашний коннектор сломает вчерашний пакет».
+ */
+export const IMPORT_PACKAGE_FORMAT_VERSION = 1;
+/**
+ * Версии, которые ядро умеет читать. Отдельно от текущей, потому что читать мы
+ * обязаны шире, чем писать: пакет мог быть собран неделю назад и пролежать в
+ * очереди, пока ядро обновилось.
+ */
+export const SUPPORTED_IMPORT_PACKAGE_VERSIONS = [1];
+// Потолки — защита от «коннектор выгрузил сюда весь сервис одной строкой».
+export const IMPORT_EXTERNAL_ID_MAX = 400;
+export const IMPORT_TITLE_MAX = 1000;
+export const IMPORT_HTML_MAX = 5_000_000;
+export const IMPORT_FILE_PATH_MAX = 600;
+export const IMPORT_LABEL_MAX = 200;
+export const IMPORT_LABELS_MAX = 100;
+export const IMPORT_URL_MAX = 2000;
+export const IMPORT_SOURCE_MAX = 100;
+export const IMPORT_ATTACHMENT_REFS_MAX = 500;
+/**
+ * Машинное имя исходного сервиса. Без `:` и пробелов сознательно: на этом стоит
+ * однозначность ключа идемпотентности (`importEntityKey`).
+ */
+export const IMPORT_SOURCE_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * НЕВИДИМЫЕ СИМВОЛЫ — всё, чего человек в строке не увидит, а машина учтёт.
+ *
+ * Используется у `ImportExternalId` и `ImportAttachmentName` — оба алфавит не
+ * сужают (в отличие от `ImportFilePath`, который 2026-08-26 перешёл на белый
+ * список `IMPORT_FILE_PATH_RE` и вообще не пропускает ничего вне
+ * `[A-Za-z0-9._-]`, так что для него эта проверка стала бы мёртвым кодом —
+ * невидимые символы и суррогаты закрыты для пути уже тем, что их нет в
+ * алфавите). `externalId` и `name` сознательно не сужают алфавит (см. их
+ * комментарии): оба — либо чужой id, либо человекочитаемое имя файла, где
+ * скобки/пробелы/кириллица законны, поэтому для них нужен именно перечень
+ * запрещённых классов, а не белый список.
+ *
+ * Классами Unicode, а не перечнем кодов, потому что перечень тут всегда неполон:
+ *  • `Cc` — управляющие C0 (включая NUL), DEL и C1. NUL Postgres не хранит
+ *    в `text`;
+ *  • `Cf` — форматирующие: zero-width space, BOM, мягкий перенос,
+ *    bidi-переопределения. Ключ идемпотентности показывается человеку, а
+ *    такой символ делает две разные строки неразличимыми на глаз;
+ *  • `Zl`/`Zp` — разделители строки и абзаца: разрыв строки ломает однострочную
+ *    запись в лог прогона и в отчёт о карантине;
+ *  • `Default_Ignorable_Code_Point` — свойство, а не категория, и без него в
+ *    проверке оставалась дыра: селекторы вариаций (U+FE0F), монгольские FVS
+ *    (U+180B–U+180D) и combining grapheme joiner (U+034F) лежат в категории
+ *    `Mn`, то есть ни под один класс выше не подходят, — а невидимы ровно так
+ *    же. `p42` и `p42\u{FE0F}` давали ДВА РАЗНЫХ ключа идемпотентности,
+ *    неразличимых на экране карантина. Нашли верификаторы TERMES и SCARAB на
+ *    ревью MOVE-7;
+ *  • `U+2800` BRAILLE PATTERN BLANK — единственный код здесь перечнем, а не
+ *    классом, и это не лень. Свойства «рисуется пустым местом» в Unicode нет:
+ *    у него категория `So`, `Default_Ignorable` он не имеет, — а выглядит как
+ *    пустая ячейка в любом шрифте с Брайлем (тем же приёмом делают невидимые
+ *    ники в мессенджерах). Остальные известные пустые глифы — филлеры хангыля
+ *    (U+115F, U+1160, U+3164, U+FFA0), кхмерские U+17B4/U+17B5, монгольский
+ *    U+180E — все `Default_Ignorable` и ловятся строкой выше; проверено
+ *    перебором, U+2800 из них единственный выпадающий. Нашёл верификатор
+ *    MYRMEX третьим кругом на том же ревью.
+ *
+ * Пробелы категории `Zs` (в т.ч. неразрывный) сюда НЕ входят намеренно: они видны
+ * как пробел, а по краям строки их и так снимает отдельная проверка.
+ *
+ * Побочно под запрет попадают ZWJ и теговые символы, то есть составные эмодзи в
+ * качестве `externalId`. Машинного id такой формы у сервисов не бывает;
+ * появится — вырежется один класс, а не вся проверка.
+ */
+export const IMPORT_INVISIBLE_CHARS_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}\u{2800}]/u;
+/**
+ * ОДИНОЧНЫЙ (НЕПАРНЫЙ) СУРРОГАТ — не «невидимый символ», а вообще не символ, и
+ * поэтому его не ловит НИ ОДНО свойство Unicode: для `\p{...}`-классов такого
+ * кода просто не существует. Проверка отдельная именно по этой причине, а не
+ * ради красоты.
+ *
+ * Чем это хуже всего, что чинили выше. Невидимые символы дают два ключа,
+ * НЕРАЗЛИЧИМЫХ НА ГЛАЗ. Одиночные суррогаты дают два ключа, РАЗНЫХ по схеме и
+ * СОВПАДАЮЩИХ БАЙТ В БАЙТ после кодирования в UTF-8: все 2048 значений
+ * `U+D800`…`U+DFFF` схлопываются в один и тот же `U+FFFD`. То есть на границе
+ * с Postgres (колонка `text`, куда ключ и едет) две разные сущности становятся
+ * одной — прямая коллизия идемпотентности, а не косметика.
+ *
+ * И это не только про злой умысел: `JSON.parse` такую строку принимает молча,
+ * а получается она обычным наивным `slice(0, N)` где-нибудь выше по цепочке —
+ * если срез пришёлся на середину суррогатной пары (эмодзи, редкий CJK,
+ * математические знаки). Классические грабли обрезки, а не атака.
+ *
+ * Регулярка без флага `u` намеренно: она работает с UTF-16 code units, а
+ * искать надо ровно непарную половину пары. Нашёл верификатор HORNET
+ * четвёртым кругом на ревью MOVE-7.
+ *
+ * Используется у `ImportExternalId` и `ImportAttachmentName` — как и
+ * `IMPORT_INVISIBLE_CHARS_RE`, у `ImportFilePath` эта проверка стала
+ * избыточной: белый список `IMPORT_FILE_PATH_RE` не пропускает суррогат по
+ * построению.
+ */
+export const IMPORT_LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/**
+ * Идентификатор сущности В ИСХОДНОМ СЕРВИСЕ — основа идемпотентности: по нему
+ * повторный прогон находит уже перенесённое и обновляет, а не плодит копии.
+ * Обязан быть СТАБИЛЬНЫМ между выгрузками (id страницы — да, её заголовок — нет).
+ *
+ * Строка, а не число: у Confluence это число, у Notion — uuid, у следующего
+ * сервиса что-то третье. Алфавит поэтому НЕ сужаем до латиницы с цифрами: чужой
+ * сервис вправе выдавать что угодно, а коннектор, вынужденный перекодировать id,
+ * потерял бы ровно ту стабильность, на которой всё стоит.
+ *
+ * Но два класса символов запрещены, и оба — про то, что с этой строкой будет
+ * ДАЛЬШЕ:
+ *
+ *  • НЕВИДИМЫЕ (`IMPORT_INVISIBLE_CHARS_RE`). `externalId` уезжает в ключ
+ *    идемпотентности (`importEntityKey`), а тот — в колонку БД, в лог прогона и
+ *    в текст ошибок. Postgres не хранит NUL в `text`, так что пакет с таким id
+ *    падал бы уже на записи — в ядре импорта, далеко от места, где мусор
+ *    приехал. Остальные невидимые не роняют запись, но делают два разных ключа
+ *    неразличимыми для человека, который смотрит на карантин и решает, одна это
+ *    сущность или две. Печатность ключа — заявленный контракт, и держать его
+ *    обязана схема: сам `importEntityKey` чистая склейка и вход проверять не
+ *    может.
+ *
+ *  • КРАЙНИЕ ПРОБЕЛЫ. `"p42"` и `"p42 "` — разные ключи и потому разные
+ *    сущности, хотя различие невидимо глазом; такой пакет молча импортируется
+ *    дважды. Пробелы ВНУТРИ оставлены: они видны, ключ не ломают (свободная
+ *    часть в нём последняя) и у сервисов, где id это путь или заголовок, законны.
+ */
+export const ImportExternalId = z
+    .string()
+    .min(1)
+    .max(IMPORT_EXTERNAL_ID_MAX)
+    .refine((id) => !IMPORT_INVISIBLE_CHARS_RE.test(id), {
+    message: "externalId не должен содержать невидимых символов (управляющие, zero-width, bidi, разрывы строк) — он едет в ключ идемпотентности, в БД и в лог",
+})
+    .refine((id) => !IMPORT_LONE_SURROGATE_RE.test(id), {
+    message: "externalId не должен содержать непарных суррогатов: в UTF-8 они все схлопываются в один и тот же символ, и два разных id становятся одним ключом",
+})
+    .refine((id) => id === id.trim(), {
+    message: "externalId не должен начинаться или заканчиваться пробелом — невидимое различие даёт два разных ключа",
+});
+/**
+ * Момент времени из исходного сервиса — ISO 8601 СО СМЕЩЕНИЕМ. Смещение
+ * обязательно: у экспортов сплошь и рядом локальное время сервера, и без него
+ * даты уезжают на часовой пояс, а «кто раньше» перестаёт работать. Строка, а не
+ * Date, потому что пакет — это JSON на диске.
+ */
+export const ImportDate = z.string().datetime({ offset: true });
+/**
+ * ПУТЬ К ФАЙЛУ ВЛОЖЕНИЯ ВНУТРИ ПАКЕТА — относительный, от манифеста
+ * (`files/a3-scheme.png`). Спека говорит «манифест JSON плюс папка файлов», и
+ * подкаталог тут не украшение: в выгрузке Confluence вложений много, и два
+ * разных документа спокойно принесут по своему `image.png` — плоские имена их
+ * столкнут, папка нет.
+ *
+ * БЕЛЫЙ СПИСОК, А НЕ ПЕРЕЧЕНЬ ЗАПРЕЩЁННОГО. Четыре круга ревью на этом же
+ * пакете (MOVE-7) чинили контракт «путь печатный» отказом от всё новых и новых
+ * находок — управляющие ASCII, невидимый Unicode классами `Cf`/`Zl`/`Zp`,
+ * категория `Mn` через `Default_Ignorable_Code_Point`, отдельно Брайль
+ * `U+2800`, отдельно `%` из-за percent-декодирования при резолве. Каждый раунд
+ * закрывал настоящую дыру и открывал место для следующей: гонка за
+ * запрещённым принципиально неполна. Путь внутри пакета при этом выбирает
+ * сам коннектор — это не то поле, где живёт человекочитаемое имя (оно в
+ * `name` у `ImportAttachment`), поэтому сузить алфавит для него можно без
+ * потери: скобки, пробелы, кириллица никуда не делись, просто переехали в
+ * `name`.
+ *
+ * `^[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$` закрывает весь класс разом, по
+ * построению, а не перечислением:
+ *  • пробел, скобки, `%`, `\` — вне алфавита, схема их не пропустит;
+ *  • НЕВИДИМЫЙ Unicode и одиночные суррогаты — тоже вне алфавита: строка,
+ *    целиком состоящая из `A-Za-z0-9._-`, ни того, ни другого не содержит
+ *    физически. `IMPORT_INVISIBLE_CHARS_RE`/`IMPORT_LONE_SURROGATE_RE` здесь
+ *    больше не нужны — они остаются только у `ImportExternalId`, чей алфавит
+ *    сознательно не сужен (см. его комментарий);
+ *  • ведущий `/`, пустой сегмент (`files//a.png`), обратный слэш —
+ *    исключены формой регулярки (сегмент — непустая последовательность
+ *    разрешённых символов, разделитель ровно один `/`).
+ *
+ * Регулярка НЕ ловит сегменты `.` и `..` — они состоят из разрешённых
+ * символов и под неё подходят, поэтому запрет на них — отдельная проверка
+ * ниже, как и раньше.
+ */
+export const IMPORT_FILE_PATH_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+export const ImportFilePath = z
+    .string()
+    .min(1)
+    .max(IMPORT_FILE_PATH_MAX)
+    .regex(IMPORT_FILE_PATH_RE, {
+    message: "путь к файлу вложения — белый список [A-Za-z0-9._-], сегменты через «/»; человекочитаемое имя едет отдельным полем name",
+})
+    .refine((path) => path.split("/").every((segment) => segment !== "." && segment !== ".."), { message: "путь к файлу вложения не должен содержать сегментов «.» и «..»" });
+const ImportLabels = z.array(z.string().min(1).max(IMPORT_LABEL_MAX)).max(IMPORT_LABELS_MAX);
+const ImportAttachmentRefs = z.array(ImportExternalId).max(IMPORT_ATTACHMENT_REFS_MAX);
+/**
+ * Человек из исходного сервиса. Здесь он ПРИЗРАК: коннектор знает только то, что
+ * было в экспорте, а сопоставление с нашими пользователями — работа ядра
+ * (MOVE-10). Поэтому обязателен ровно `externalId`, а `name` — то, что показать
+ * человеку, пока сопоставления нет.
+ *
+ * `email` тут ПОДСКАЗКА ДЛЯ СОПОСТАВЛЕНИЯ, а не адрес входа: спека прямо
+ * запрещает класть чужую почту в наше уникальное поле `User.email`, иначе импорт
+ * становится способом занять чужой адрес.
+ */
+export const ImportPerson = z.object({
+    externalId: ImportExternalId,
+    name: z.string().min(1).max(IMPORT_TITLE_MAX),
+    email: z.string().email().max(IMPORT_TITLE_MAX).optional(),
+    /** Логин в исходном сервисе — вторая зацепка, когда почты в экспорте нет. */
+    username: z.string().min(1).max(IMPORT_TITLE_MAX).optional(),
+    avatarUrl: z.string().max(IMPORT_URL_MAX).optional(),
+});
+/**
+ * Пространство — верхний контейнер исходного сервиса (space в Confluence,
+ * teamspace в Notion). Во что оно превратится у нас, решает ядро.
+ */
+export const ImportSpace = z.object({
+    externalId: ImportExternalId,
+    title: z.string().min(1).max(IMPORT_TITLE_MAX),
+    descriptionHtml: z.string().max(IMPORT_HTML_MAX).optional(),
+    /** Ссылка на пространство в исходном сервисе — чтобы после переезда было куда вернуться. */
+    sourceUrl: z.string().max(IMPORT_URL_MAX).optional(),
+});
+/**
+ * Состояние спринта. ПЕРЕЧИСЛЕНИЕМ, в отличие от `status` у задачи, который
+ * едет строкой исходного сервиса, — и это не непоследовательность. Статусов у
+ * чужого трекера сколько угодно и своих, раскладывать их по нашим умеет только
+ * ядро с картой воркфлоу; состояний же спринта ровно три, и они одни и те же у
+ * Jira, YouTrack и у нас (`Sprint.state` в схеме: `planned | active |
+ * completed`). Перечисление здесь ловит опечатку коннектора на входе, а не
+ * через неделю в отчёте.
+ */
+export const IMPORT_SPRINT_STATES = ["planned", "active", "completed"];
+/**
+ * MOVE-28: СПРИНТ — итерация исходного трекера (sprint в Jira, sprint/веха в
+ * YouTrack). Первый шаг к переносу спринтов спринтами, а не меткой на задаче
+ * (MOVE-29): здесь только форма, ни выкачки, ни раскладки по нашим таблицам.
+ *
+ * `spaceId` ОБЯЗАТЕЛЕН — спринт принадлежит пространству, как страница (у
+ * задачи `spaceId` необязательный, потому что у плоских экспортов задача
+ * приезжает без проекта и уезжает в запасной; у спринта такого случая нет:
+ * итерация без доски бессмысленна, и коннектор, который не знает её
+ * пространства, обязан споткнуться здесь, а не создать бесхозный спринт).
+ *
+ * Как и везде в пакете, `externalId` — id ИЗ ЧУЖОГО СЕРВИСА, а не наш cuid.
+ * Даты необязательные: у планируемого спринта их сплошь и рядом нет.
+ */
+export const ImportSprint = z.object({
+    externalId: ImportExternalId,
+    spaceId: ImportExternalId,
+    name: z.string().min(1).max(IMPORT_TITLE_MAX),
+    /** Цель итерации — короткий текст, который человек писал в трекере. */
+    goal: z.string().max(IMPORT_TITLE_MAX).optional(),
+    startsAt: ImportDate.optional(),
+    endsAt: ImportDate.optional(),
+    state: z.enum(IMPORT_SPRINT_STATES),
+});
+/**
+ * К чему прицеплен комментарий (`on` из спеки). `id` здесь — `externalId` цели
+ * в исходном сервисе, не наш cuid.
+ */
+export const ImportCommentTarget = z.object({
+    kind: z.enum(["page", "task"]),
+    id: ImportExternalId,
+});
+/**
+ * Страница.
+ *
+ * ВНИМАНИЕ К ИМЕНАМ: `spaceId`, `parentId`, `authorId` — это `externalId` ИЗ
+ * ЧУЖОГО СЕРВИСА, а не ссылки на наши таблицы. Имена взяты из спеки, и по имени
+ * они читаются как внешние ключи на нашу базу — по сути это не так, наши id
+ * появятся только в ядре, когда сущность уже создана.
+ *
+ * Дерево едет ССЫЛКАМИ (`parentId`), а не вложенностью: вложенность заставила бы
+ * коннектор собирать дерево целиком в памяти и ломалась бы на циклах, которые в
+ * чужих экспортах встречаются. `null`/отсутствие — корень пространства.
+ */
+export const ImportPage = z.object({
+    externalId: ImportExternalId,
+    spaceId: ImportExternalId,
+    parentId: ImportExternalId.nullish(),
+    title: z.string().min(1).max(IMPORT_TITLE_MAX),
+    /** Тело в HTML — см. про ProseMirror в шапке файла. */
+    bodyHtml: z.string().max(IMPORT_HTML_MAX),
+    authorId: ImportExternalId.optional(),
+    /** Кто правил последним, если сервис это отдаёт, — иначе автор и правщик сливаются. */
+    lastEditorId: ImportExternalId.optional(),
+    createdAt: ImportDate,
+    updatedAt: ImportDate.optional(),
+    /** `externalId` вложений этой страницы — сами файлы в `attachments` манифеста. */
+    attachments: ImportAttachmentRefs.optional(),
+    labels: ImportLabels.optional(),
+    sourceUrl: z.string().max(IMPORT_URL_MAX).optional(),
+});
+/**
+ * Задача. Статус едет СТРОКОЙ ИСХОДНОГО СЕРВИСА, а не нашим enum'ом: у чужого
+ * трекера свои состояния, и раскладывать их по нашим — работа ядра, где для
+ * этого есть карта воркфлоу. Коннектор, который угадывает наш статус, обманет
+ * ровно один раз и незаметно.
+ *
+ * `spaceId`, `parentId`, `authorId`, `assigneeId` — тоже внешние id, см. `ImportPage`.
+ */
+export const ImportTask = z.object({
+    externalId: ImportExternalId,
+    spaceId: ImportExternalId.optional(),
+    parentId: ImportExternalId.nullish(),
+    title: z.string().min(1).max(IMPORT_TITLE_MAX),
+    descriptionHtml: z.string().max(IMPORT_HTML_MAX).optional(),
+    status: z.string().min(1).max(IMPORT_TITLE_MAX).optional(),
+    priority: z.string().min(1).max(IMPORT_TITLE_MAX).optional(),
+    authorId: ImportExternalId.optional(),
+    assigneeId: ImportExternalId.optional(),
+    /**
+     * MOVE-28: в каком спринте задача — `externalId` из `sprints`. Необязателен
+     * дважды: у источника без спринтов их нет вовсе, и внутри источника со
+     * спринтами задача может лежать в бэклоге.
+     */
+    sprintId: ImportExternalId.optional(),
+    createdAt: ImportDate,
+    updatedAt: ImportDate.optional(),
+    dueAt: ImportDate.optional(),
+    completedAt: ImportDate.optional(),
+    attachments: ImportAttachmentRefs.optional(),
+    labels: ImportLabels.optional(),
+    sourceUrl: z.string().max(IMPORT_URL_MAX).optional(),
+});
+/**
+ * Комментарий к странице или задаче. `parentId` — ответ на другой комментарий
+ * (ветка обсуждения), не владелец: владелец всегда в `on`.
+ */
+export const ImportComment = z.object({
+    externalId: ImportExternalId,
+    on: ImportCommentTarget,
+    parentId: ImportExternalId.nullish(),
+    authorId: ImportExternalId.optional(),
+    bodyHtml: z.string().max(IMPORT_HTML_MAX),
+    createdAt: ImportDate,
+    updatedAt: ImportDate.optional(),
+});
+/**
+ * Вложение. Метаданные здесь, БАЙТЫ — файлом внутри пакета (`file`). Владельца у
+ * вложения нет: на него ссылаются страница и задача через свой `attachments`,
+ * как и показано в спеке — один и тот же файл так может принадлежать нескольким
+ * сущностям, не размножаясь.
+ */
+/**
+ * Имя файла, каким его видит ЧЕЛОВЕК (в отличие от `file` — служебного пути,
+ * белый список для которого сузил алфавит до ASCII). `name` алфавит не сужает
+ * — скобки, пробелы, кириллица здесь как раз законны, это и есть то поле,
+ * куда они переехали из `ImportFilePath` (см. её комментарий). Но именно
+ * поэтому `name` — единственное поле в файле, которое ПОКАЗЫВАЕТСЯ человеку
+ * буквально как имя файла, и оставлять его вовсе без защиты от невидимых
+ * символов значило бы закрыть RTL-override-подмену расширения у `file` и
+ * `externalId` и оставить открытой ровно у того поля, где она опаснее всего:
+ * `"invoice‮fdp.exe"` пройдёт схему и отрисуется человеку как
+ * «invoice.pdf» при реальном `.exe`. Найдено ревью SPHINX на MOVE-7.
+ */
+export const ImportAttachmentName = z
+    .string()
+    .min(1)
+    .max(IMPORT_TITLE_MAX)
+    .refine((name) => !IMPORT_INVISIBLE_CHARS_RE.test(name), {
+    message: "имя файла вложения не должно содержать невидимых символов — RTL override подменяет видимое расширение",
+})
+    .refine((name) => !IMPORT_LONE_SURROGATE_RE.test(name), {
+    message: "имя файла вложения не должно содержать непарных суррогатов",
+});
+export const ImportAttachment = z.object({
+    externalId: ImportExternalId,
+    /** Относительный путь внутри пакета: `files/a3-scheme.png`. */
+    file: ImportFilePath,
+    /** Как файл назывался у человека — `file` в пакете может быть обеззаражен коннектором. */
+    name: ImportAttachmentName.optional(),
+    mime: z.string().min(1).max(IMPORT_TITLE_MAX).optional(),
+    byteSize: z.number().int().nonnegative().optional(),
+    authorId: ImportExternalId.optional(),
+    createdAt: ImportDate.optional(),
+});
+/**
+ * МАНИФЕСТ — то, что коннектор кладёт в `manifest.json`, а ядро читает первым и
+ * единственным входом. Все сущности здесь; рядом лежит только папка файлов.
+ */
+export const ImportPackageManifest = z.object({
+    /**
+     * Версия формата. Стоит ПЕРВЫМ полем и проверяется ДО остальной схемы (см.
+     * `parseImportPackageManifest`): пакет завтрашней версии обязан получить
+     * внятный отказ, а не ворох ошибок валидации, из которых не видно, что дело
+     * в версии.
+     */
+    formatVersion: z.number().int().positive(),
+    /**
+     * Машинное имя исходного сервиса (`confluence`). Входит в ключ
+     * идемпотентности: одинаковые `externalId` из разных сервисов — разные
+     * сущности, и без имени сервиса второй импорт «узнал» бы чужое.
+     */
+    source: z.string().min(1).max(IMPORT_SOURCE_MAX).regex(IMPORT_SOURCE_RE, {
+        message: "имя сервиса — машинное: строчные латинские буквы, цифры, дефис и подчёркивание",
+    }),
+    /** Адрес инсталляции — на self-hosted сервисах одного имени сервиса мало. */
+    sourceUrl: z.string().max(IMPORT_URL_MAX).optional(),
+    /** Когда снят экспорт (не когда собран пакет) — по нему видно, насколько данные протухли. */
+    exportedAt: ImportDate.optional(),
+    /** Чем собран пакет — чтобы по кривому импорту было видно, какой коннектор чинить. */
+    generator: z
+        .object({
+        name: z.string().min(1).max(IMPORT_SOURCE_MAX),
+        version: z.string().min(1).max(IMPORT_SOURCE_MAX).optional(),
+    })
+        .optional(),
+    people: z.array(ImportPerson).default([]),
+    spaces: z.array(ImportSpace).default([]),
+    /**
+     * MOVE-28. Секция НЕОБЯЗАТЕЛЬНАЯ, и `.default([])` здесь — вся обратная
+     * совместимость: пакет Confluence и уже выкачанные пакеты Jira/YouTrack
+     * секции не знают, разбираются как раньше и получают пустой список.
+     * `formatVersion` по этой же причине не двигается — см. её комментарий:
+     * версия растёт на ЛОМАЮЩЕМ изменении формы.
+     */
+    sprints: z.array(ImportSprint).default([]),
+    pages: z.array(ImportPage).default([]),
+    tasks: z.array(ImportTask).default([]),
+    comments: z.array(ImportComment).default([]),
+    attachments: z.array(ImportAttachment).default([]),
+});
+/** Виды сущностей пакета — по ним же строится ключ идемпотентности. */
+export const IMPORT_ENTITY_KINDS = [
+    "person",
+    "space",
+    "sprint",
+    "page",
+    "task",
+    "comment",
+    "attachment",
+];
+/**
+ * Вид сущности → список в манифесте. Таблицей, а не склейкой `kind + "s"`:
+ * у `person` список называется `people`, и правило «плюс s» тут врёт.
+ */
+export const IMPORT_ENTITY_FIELDS = {
+    person: "people",
+    space: "spaces",
+    sprint: "sprints",
+    page: "pages",
+    task: "tasks",
+    comment: "comments",
+    attachment: "attachments",
+};
+/**
+ * КЛЮЧ ИДЕМПОТЕНТНОСТИ. Собирается ЗДЕСЬ и только здесь: ядро, коннектор и отчёт
+ * о прогоне обязаны считать его одинаково, иначе повторный прогон не узнает уже
+ * перенесённое и создаст второй экземпляр всего. Это тот же тройной ключ, что у
+ * `ImportedEntity` в спеке (`source`, `kind`, `externalId`).
+ *
+ * Разделитель `:` однозначен, потому что свободная часть ровно одна и она
+ * ПОСЛЕДНЯЯ: `source` ограничен `IMPORT_SOURCE_RE`, `kind` — фиксированный
+ * перечень, двоеточий в них не бывает. `externalId` может содержать что угодно
+ * (в Notion как раз двоеточия) — на хвосте это разбор не ломает.
+ *
+ * Ключ ПЕЧАТНЫЙ — это КОНТРАКТ, и держится он не здесь: сама функция всего лишь
+ * склейка и вход не проверяет. Печатность обеспечивают `IMPORT_SOURCE_RE` и
+ * запрет невидимых символов в `ImportExternalId` (`IMPORT_INVISIBLE_CHARS_RE` —
+ * управляющие, zero-width, bidi, разрывы строк); звать ключ на строках, не
+ * прошедших схему, значит остаться без этой гарантии. Нужна она затем, что ключ
+ * поедет в колонку БД, в лог прогона и на экран карантина: Postgres не хранит
+ * NUL в `text`, а два ключа, различающиеся невидимым символом, человек не
+ * различит и в глаза.
+ */
+export function importEntityKey(source, kind, externalId) {
+    return `${source}:${kind}:${externalId}`;
+}
+export function isSupportedImportPackageVersion(version) {
+    return SUPPORTED_IMPORT_PACKAGE_VERSIONS.includes(version);
+}
+/**
+ * Сырой JSON манифеста → типизированный манифест или ВНЯТНЫЙ ОТКАЗ.
+ *
+ * Версия смотрится ДО схемы намеренно. Если бы `formatVersion` был просто
+ * `z.literal(1)`, пакет завтрашнего коннектора отвалился бы наравне с битым
+ * JSON — и человек, глядя на список ошибок полей, чинил бы не то.
+ *
+ * Не бросает: пакет приходит извне, и ядру нужен отказ, который можно положить в
+ * карантин и показать человеку, а не исключение.
+ */
+export function parseImportPackageManifest(raw) {
+    if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+        return {
+            ok: false,
+            error: { reason: "missing_version", message: "манифест должен быть объектом с полем formatVersion" },
+        };
+    }
+    const version = raw.formatVersion;
+    if (typeof version !== "number" || !Number.isInteger(version) || version <= 0) {
+        return {
+            ok: false,
+            error: {
+                reason: "missing_version",
+                message: "в манифесте нет версии формата (formatVersion) — это не пакет импорта",
+            },
+        };
+    }
+    if (!isSupportedImportPackageVersion(version)) {
+        return {
+            ok: false,
+            error: {
+                reason: "unsupported_version",
+                version,
+                supported: SUPPORTED_IMPORT_PACKAGE_VERSIONS,
+                message: `пакет формата версии ${version}, ядро понимает ` +
+                    `${SUPPORTED_IMPORT_PACKAGE_VERSIONS.join(", ")} — обновите Taskless или пересоберите пакет`,
+            },
+        };
+    }
+    const parsed = ImportPackageManifest.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: {
+                reason: "invalid",
+                issues: parsed.error.issues,
+                message: `манифест не проходит валидацию: ${parsed.error.issues.length} ошибок в полях`,
+            },
+        };
+    }
+    return { ok: true, manifest: parsed.data };
+}
+/**
+ * Проверка СВЯЗНОСТИ — то, что Zod не ловит по устройству: он проверяет каждую
+ * сущность отдельно, а пакет ломается на связях между ними.
+ *
+ * Ловит две вещи, и обе про идемпотентность:
+ *  • повторный `externalId` внутри вида — ключ перестаёт быть ключом, и
+ *    повторный прогон будет находить то одну сущность, то другую;
+ *  • ссылку в никуда (родитель, автор, пространство, владелец, вложение) — ядру
+ *    нечего с ней делать, а молча уронить связь значит потерять кусок дерева и
+ *    узнать об этом от человека через неделю.
+ *
+ * Отдаёт СПИСОК, а не бросает: пакет с десятком висячих ссылок должен уехать в
+ * карантин целиком и показаться человеку одним экраном. Что делать с проблемами
+ * — решает ядро (MOVE-11).
+ */
+export function checkImportPackageRefs(manifest) {
+    const problems = [];
+    // Один список «вид → его сущности» на обе фазы. Перечислять виды отдельно для
+    // множеств и отдельно для обхода нельзя: `Record<ImportEntityKind, …>` не даст
+    // забыть вид ЗДЕСЬ, а забытый вызов обхода не поймал бы никто — проверка
+    // дублей для нового вида молча перестала бы работать.
+    const entities = {
+        person: manifest.people,
+        space: manifest.spaces,
+        sprint: manifest.sprints,
+        page: manifest.pages,
+        task: manifest.tasks,
+        comment: manifest.comments,
+        attachment: manifest.attachments,
+    };
+    const ids = {};
+    for (const kind of IMPORT_ENTITY_KINDS) {
+        const seen = new Set();
+        ids[kind] = seen;
+        for (const entity of entities[kind]) {
+            if (seen.has(entity.externalId)) {
+                problems.push({
+                    kind,
+                    externalId: entity.externalId,
+                    problem: "duplicate_external_id",
+                    message: `${kind}: externalId «${entity.externalId}» встречается больше одного раза`,
+                });
+                continue;
+            }
+            seen.add(entity.externalId);
+        }
+    }
+    const ref = (kind, externalId, field, target, value) => {
+        if (value == null || ids[target].has(value))
+            return;
+        problems.push({
+            kind,
+            externalId,
+            problem: "dangling_ref",
+            field,
+            message: `${kind} «${externalId}»: ${field} ссылается на ${target} «${value}», которого нет в пакете`,
+        });
+    };
+    const attachmentRefs = (kind, externalId, refs) => {
+        for (const value of refs ?? [])
+            ref(kind, externalId, "attachments", "attachment", value);
+    };
+    // У пространства исходящих ссылок нет — оно верх дерева, обходить нечего.
+    for (const sprint of manifest.sprints) {
+        ref("sprint", sprint.externalId, "spaceId", "space", sprint.spaceId);
+    }
+    for (const page of manifest.pages) {
+        ref("page", page.externalId, "spaceId", "space", page.spaceId);
+        ref("page", page.externalId, "parentId", "page", page.parentId);
+        ref("page", page.externalId, "authorId", "person", page.authorId);
+        ref("page", page.externalId, "lastEditorId", "person", page.lastEditorId);
+        attachmentRefs("page", page.externalId, page.attachments);
+    }
+    for (const task of manifest.tasks) {
+        ref("task", task.externalId, "spaceId", "space", task.spaceId);
+        ref("task", task.externalId, "parentId", "task", task.parentId);
+        ref("task", task.externalId, "authorId", "person", task.authorId);
+        ref("task", task.externalId, "assigneeId", "person", task.assigneeId);
+        ref("task", task.externalId, "sprintId", "sprint", task.sprintId);
+        attachmentRefs("task", task.externalId, task.attachments);
+    }
+    for (const comment of manifest.comments) {
+        ref("comment", comment.externalId, "on.id", comment.on.kind === "page" ? "page" : "task", comment.on.id);
+        ref("comment", comment.externalId, "parentId", "comment", comment.parentId);
+        ref("comment", comment.externalId, "authorId", "person", comment.authorId);
+    }
+    for (const attachment of manifest.attachments) {
+        ref("attachment", attachment.externalId, "authorId", "person", attachment.authorId);
+    }
+    return problems;
+}
+/**
+ * Пути файлов, которые обязаны лежать в пакете. Ядру нужно ДО раскладки понять,
+ * полон ли пакет: недостающий файл на середине прогона — это половина импорта и
+ * ручная уборка.
+ */
+export function importPackageFilePaths(manifest) {
+    const paths = new Set();
+    for (const attachment of manifest.attachments)
+        paths.add(attachment.file);
+    return [...paths];
+}
+//# sourceMappingURL=importPackage.js.map