chuvsu-js 4.1.5 → 5.0.0

package/dist/tt/webinars.d.ts

@@ -0,0 +1,7 @@
+import type { LessonOccurrence } from "./domain/types.js";
+import type { Webinar } from "./types.js";
+export type LessonWithWebinar = LessonOccurrence & {
+    webinar?: Webinar;
+};
+export declare function findWebinar(lesson: LessonOccurrence, webinars: Webinar[]): Webinar | undefined;
+export declare function attachWebinars(lessons: LessonOccurrence[], webinars: Webinar[]): LessonWithWebinar[];

package/dist/tt/webinars.js

@@ -0,0 +1,38 @@
+function normalize(value) {
+    return value
+        .toLocaleLowerCase("ru-RU")
+        .replace(/ё/gu, "е")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+export function findWebinar(lesson, webinars) {
+    return webinars.find((webinar) => {
+        if (!webinar.scheduled)
+            return false;
+        if (webinar.scheduledDate &&
+            webinar.scheduledDate !== lesson.scheduledDate)
+            return false;
+        if (webinar.slotNumber != null &&
+            webinar.slotNumber !== lesson.slotNumber) {
+            return false;
+        }
+        if (!lesson.time ||
+            webinar.time.start.hours !== lesson.time.start.hours ||
+            webinar.time.start.minutes !== lesson.time.start.minutes ||
+            webinar.time.end.hours !== lesson.time.end.hours ||
+            webinar.time.end.minutes !== lesson.time.end.minutes) {
+            return false;
+        }
+        if (normalize(webinar.subject) !== normalize(lesson.subject))
+            return false;
+        if (webinar.type && lesson.type && webinar.type !== lesson.type)
+            return false;
+        return true;
+    });
+}
+export function attachWebinars(lessons, webinars) {
+    return lessons.map((lesson) => {
+        const webinar = findWebinar(lesson, webinars);
+        return webinar ? { ...lesson, webinar } : lesson;
+    });
+}

package/docs/fixture-review.md

@@ -0,0 +1,56 @@
+# Журнал ручной проверки полных фикстур
+
+Дата проверки: 1 сентября 2026 года.
+
+Каждая строка каждого expected JSON лично сопоставлена с исходным HTML. При
+проверке учитывались метаданные источника, позиция записи, предмет, тип, день,
+слот, время, недели, чередование, аудитория, преподаватель и его реквизиты,
+группы, подгруппа, ДОТ, замены и переносы. Генератор expected-файлов и отдельный
+DOM-аудитор не использовались.
+
+| Эталон | Занятий | Результат |
+|---|---:|---|
+| group-10042-period-1.json | 38 | проверен |
+| group-10209-period-1.json | 22 | проверен |
+| group-10307-period-1.json | 31 | проверен |
+| group-10383-period-1.json | 27 | проверен |
+| group-10403-period-1.json | 5 | проверен |
+| group-10428-period-1.json | 30 | проверен |
+| group-10443-period-1.json | 19 | проверен |
+| group-10462-period-1.json | 26 | проверен |
+| group-10468-period-1.json | 20 | проверен |
+| group-10481-period-1.json | 4 | проверен |
+| group-10483-period-1.json | 4 | проверен |
+| group-10488-period-1.json | 4 | проверен |
+| group-7698-period-1.json | 21 | проверен |
+| group-8035-period-1.json | 9 | проверен |
+| group-8107-period-1.json | 21 | проверен |
+| group-8203-period-1.json | 26 | проверен |
+| group-8219-period-1.json | 22 | проверен |
+| group-8231-period-1.json | 49 | проверен |
+| group-8499-period-1.json | 28 | проверен |
+| group-8827-period-1.json | 65 | проверен, исправлено `к.иск.` |
+| group-8844-period-1.json | 25 | проверен |
+| group-8912-period-1.json | 42 | проверен |
+| group-8917-period-1.json | 43 | проверен |
+| group-8919-period-1.json | 59 | проверен |
+| group-9075-period-1.json | 40 | проверен |
+| group-9332-period-1.json | 24 | проверен |
+| group-9347-period-1.json | 22 | проверен |
+| group-9438-period-1.json | 19 | проверен |
+| group-9491-period-1.json | 16 | проверен |
+| group-9520-period-1.json | 26 | проверен |
+| group-9588-period-1.json | 8 | проверен |
+| group-9698-period-1.json | 37 | проверен, включая перенос |
+| group-9719-period-1.json | 44 | проверен |
+| group-9843-period-1.json | 24 | проверен |
+| teacher-1317-period-1.json | 7 | проверен, восстановлена ученая степень |
+| teacher-1907-period-1.json | 8 | проверен |
+| teacher-2317-period-1.json | 10 | проверен |
+| teacher-543-period-1.json | 39 | проверен, восстановлена ученая степень |
+| room-1438-period-1.json | 75 | проверен |
+| room-803-period-1.json | 48 | проверен, включая два переноса |
+| room-811-period-1.json | 54 | проверен |
+| room-814-period-1.json | 43 | проверен, исправлено ложное ДОТ у Федотовой |
+
+Итого: 42 файла, 1184 занятия.

package/docs/testing.md

@@ -0,0 +1,23 @@
+# Проверка расписания v5
+
+Эталонные JSON поддерживаются и изменяются только вручную. Генератора эталонов
+в репозитории нет. Все 42 полных JSON-эталона (1184 занятия) вручную сверены с
+соответствующими HTML-страницами. Проверены владелец, учебный год, период,
+позиция строки, предмет, тип, день, слот, фактическое время, недели,
+чередование, аудитория, преподаватель, группы, подгруппа, ДОТ, замены и
+переносы. Журнал проверки: [`fixture-review.md`](fixture-review.md).
+
+Для каждой страницы тест заново получает канонический результат и целиком
+сравнивает его с зафиксированным JSON. Детерминированный генератор ID в тесте
+нужен только для стабильных идентификаторов; он не создает и не изменяет
+эталоны. Дополнительно весь корпус проверяет объединение общих пар между
+страницами групп, преподавателей и аудиторий.
+
+Точечные примеры проверяют семестр, сессию, экзамены, консультации, подгруппы,
+ДОТ, замены, преподавателя «вместо», переносы и отсутствие данных. Доменные
+тесты проверяют ID, неоднозначность, объединение проекций, применение изменений
+и календарное раскрытие. `pnpm test:coverage` требует для ядра расписания не
+меньше 95% строк, 94% функций и 80% ветвей.
+
+Live-тест сравнивает парсер с текущими страницами портала, но не заменяет
+зафиксированные HTML и ручные эталоны.

package/docs/v5-architecture.md

@@ -0,0 +1,144 @@
+# Архитектура расписания chuvsu-js v5
+
+## Цели
+
+- Одна реальная пара хранится один раз, даже если разные страницы показывают
+  разные части информации о ней.
+- Серии и конкретные занятия получают устойчивые случайные ID, не зависящие от
+  изменяемых даты, аудитории и времени.
+- Семестровое расписание и сессия становятся форматами входных наблюдений одной
+  модели запросов.
+- TTL-кеш страниц не управляет временем жизни канонических ID.
+- Репозиторий, календарь и запросы работают в браузере без Node-сети и DOM.
+
+Версия 5 намеренно несовместима с v4; старые формы вызовов не сохраняются.
+
+## Границы пакетов
+
+- `chuvsu-js` и `chuvsu-js/node` — Node-клиенты, парсеры и ядро;
+- `chuvsu-js/browser` — репозиторий, `Schedule`, календарные функции, доменные
+  типы и импорт/экспорт снимков;
+- `chuvsu-js/parsers` — серверные HTML-парсеры без авторизованных клиентов.
+
+Браузерная точка входа не импортирует `undici`, `linkedom`, сертификаты или
+`Buffer`.
+
+## Наблюдение и каноническая сущность
+
+Строка страницы — не готовая пара, а `ScheduleObservation`. Владелец страницы
+является достоверным неявным фактом: страница группы доказывает участие группы,
+страница преподавателя — преподавателя, страница аудитории — аудиторию.
+
+Отсутствующие поля означают «источник не сообщил». Явное отсутствие передается
+как `null` на границе парсера и превращается в пустой `RelationSet` с
+`completeness: "complete"`.
+
+```text
+RelationSet<T> = {
+  values: T[]
+  completeness: "unknown" | "partial" | "complete"
+}
+```
+
+Это устраняет пустые строки и не позволяет принять нехватку данных за известное
+отсутствие.
+
+## Время и дата
+
+Номер и фактический интервал независимы:
+
+```text
+slotNumber?: number
+time?: { start: Time, end: Time }
+```
+
+Стандартная сетка звонков — только справочная информация и не переписывает
+утверждение портала. Сессия не получает вычисленный номер пары по ближайшему
+времени.
+
+Дата без времени — `LocalDate` (`YYYY-MM-DD`). В модели не используется
+полуночный `Date`, поэтому сериализация через UTC не может сдвинуть учебный день.
+
+## Серии и занятия
+
+`LessonSeries` описывает повторение в семестре: учебный год, период, день недели,
+необязательный диапазон недель, чередование, независимые номер и время, предмет,
+тип, связи, замены и происхождение данных. Отсутствующий диапазон означает, что
+источник не ограничил недели; фиктивные диапазоны вроде `0..0` запрещены.
+
+`LessonOccurrence` описывает конкретное занятие. У него есть `scheduledDate`,
+`nominalDate`, статус переноса, отдельное локальное время и, для семестровой
+пары, `seriesId`. Экзамен, консультация и другая строка сессии сразу становятся
+`LessonOccurrence` с датой из страницы: у них нет `recurrence` и диапазона недель.
+
+ID серии создается генератором и хранится в репозитории. ID семестрового
+занятия выводится из ID серии, учебной недели и порядкового номера возникновения;
+дата, время и аудитория в идентичность не входят. Строка сессии получает
+сохраненный `lessonId`.
+
+## Согласование наблюдений
+
+При загрузке источника репозиторий:
+
+1. Нормализует текст и ссылки на сущности.
+2. Сохраняет прежний ID, если наблюдение связано с уже известной строкой этого
+   источника.
+3. Для нового источника рассматривает только тот же учебный год, период и вид
+   сущности.
+4. Запрещает объединение разных дат конкретных занятий, разных дней недели,
+   непересекающихся недель и несовместимого чередования.
+5. Независимо оценивает совпадение номера и времени, а также предмета, типа,
+   групп, преподавателей и аудиторий.
+6. Объединяет только единственного кандидата с достаточным доказательством;
+   неоднозначность создает новый ID.
+7. Хранит происхождение всех утверждений и объединяет совместимые связи.
+8. Выбирает номер пары и интервал времени независимо по совокупности источников,
+   поэтому ни одна «самая полная» строка не перетирает остальные поля целиком.
+
+Результат проверяется в прямом и обратном порядке загрузки корпуса. Совпавшее
+время может сохранить идентичность при ошибочном номере пары, но разные дни или
+чередование не могут быть склеены похожими метаданными.
+
+## Справочник сущностей
+
+Репозиторий содержит справочник групп, преподавателей и аудиторий. Его наполняют
+поиск, списки и владельцы загруженных страниц. Сокращение преподавателя
+разрешается по фамилии и инициалам только при единственном совпадении.
+
+Загрузка расписания не делает скрытых сетевых запросов. Допустимы только явно
+вызванные `resolve*` со стратегией поиска или `preloadDirectory`.
+
+## Хранилища
+
+Есть три независимых слоя:
+
+1. TTL-кеш сетевых ответов и метаданных.
+2. Канонический репозиторий ID, наблюдений, связей и ревизии.
+3. Производные представления запросов, инвалидируемые ревизией.
+
+Снимок репозитория имеет `schemaVersion: 5`. Адаптер постоянного хранилища
+использует compare-and-set по ревизии.
+
+## Запросы
+
+`Schedule` — легкое синхронное представление владельца поверх репозитория:
+
+- `on(date)`;
+- `week(academicWeek?)`;
+- `weekday(day, options?)`;
+- `today()`, `tomorrow()`, `thisWeek()`;
+- `current()`;
+- `series()`.
+
+При раскрытии серии применяются недели, праздники, замены и переносы, после чего
+добавляются прямые занятия сессии.
+
+## Проверка
+
+Полностраничный корпус содержит 34 страницы групп, 4 преподавателей и 4
+аудиторий. Для каждой страницы есть полный вручную проверенный JSON-эталон;
+всего проверено 1184 занятия. Тест сравнивает весь канонический результат, а не
+отдельные поля. Генератора эталонов в репозитории нет. Журнал ручной проверки
+находится в [`fixture-review.md`](fixture-review.md). Отдельные тесты проверяют
+устойчивость ID, неоднозначность, объединение трех проекций, порядок запросов,
+локальные даты, три состояния связей и границу браузерного пакета.