ITMO Programs CLI

Консольная утилита на TypeScript для просмотра и анализа образовательных программ ИТМО. Она работает с локальными JSON-снимками, помогает искать программы и конкурсные группы, применять фильтры и получать машинно-читаемые ответы для скриптов и ИИ-инструментов.

Возможности

• полнотекстовый поиск по программам, группам, факультетам, направлениям, дисциплинам, атрибутам и трекам олимпиад;
• поиск по ID, ИСУ ID и слагу;
• фильтрация по форме и языку обучения, военной кафедре, сроку обучения, факультету, коду направления, бюджетным местам и проходному баллу;
• детальный просмотр программы или конкурсной группы;
• список факультетов и программ;
• статистика по выбранному снимку данных;
• интерактивная справка по полям JSON;
• JSON-режим для автоматизации и интеграции с другими инструментами;
• объединение нескольких JSON-файлов с удалением повторяющихся групп.

Стек

• Bun 1.3.6;
• TypeScript;
• Node.js API readline, fs и path;
• Chalk для цветного вывода.

Внешние серверы и база данных не нужны: приложение читает данные из каталога data и не выполняет сетевые запросы при запуске.

Данные

В репозитории находятся самостоятельные снимки данных по годам:

Файл	Группы	Программы
data/2024/data2024.json	80	91
data/2025/data2025.json	82	96
data/2026/data2026.json	80	95

Ожидаемый формат файла:

{
  "ok": true,
  "message": "ok",
  "result": {
    "groups": []
  }
}

Загрузчик принимает группы из result.groups, добавляет программам ссылку на родительскую группу во внутреннем поле _group и не повторяет группы с одним и тем же ID. Снимки содержат публичные ссылки ИТМО и отдельные внешние ссылки, которые регулируются условиями соответствующих правообладателей.

Архитектура

flowchart TD
    A[CLI arguments or interactive menu] --> B[Year selector]
    B --> C[JSON snapshot loader]
    C --> D[MergedData]
    D --> E[Search and filters]
    E --> F[Terminal formatter]
    E --> G[JSON output]

Loading

Основные модули:

• src/index.ts - точка входа и маршрутизация CLI-операций;
• src/args.ts - разбор аргументов и справка;
• src/loader.ts - поиск годов, чтение и объединение JSON;
• src/search.ts - поиск и справочники факультетов, направлений и атрибутов;
• src/filters.ts - фильтры и статистика;
• src/display.ts - форматирование терминального вывода;
• src/cli.ts - интерактивное меню;
• src/types.ts и src/translations.ts - модели данных и переводы.

Запуск локально

Требуется Bun 1.x или новее.

bun install --frozen-lockfile
bun run start

В интерактивном режиме выберите год, пункт меню и операцию. Для разработки доступен watch-режим:

bun run dev

CLI-аргументы

Без основной операции приложение открывает меню. В аргументном режиме оно загружает последний доступный год, если --year не указан, и завершает работу после одного запроса.

--help # справка
--year <год> # год снимка данных
--json # JSON без служебных сообщений
--search <запрос> # поиск по текстовым и идентификационным полям
--program-id <id> # программа по ID
--group-id <id> # группа по ID
--list # список программ
--stats # статистика

Фильтры применяются вместе с --list:

--study-mode <значение>
--language <язык>
--military <true|false>
--study-period <лет>
--has-budget <true|false>
--min-budget <количество>
--faculty <название>
--direction-code <код>
--has-pass-score <true|false>
--min-pass-score <балл>
--max-pass-score <балл>
--attribute <название>

Примеры:

bun run start -- --help
bun run start -- --year 2026 --stats --json
bun run start -- --year 2025 --search "data" --json
bun run start -- --year 2026 --program-id 8068 --json
bun run start -- --year 2026 --list --study-mode internal --has-budget true --json

В JSON-режиме служебная информация выводится в stderr, а результат запроса попадает в stdout. Это позволяет передавать ответ в jq или другой процесс:

bun run start -- --year 2026 --stats --json | jq '.stats'

Интерактивное меню

Пункт	Назначение
1	Поиск программ и групп
2	Фильтрация программ
3	Постраничный список программ
4	Программа по ID
5	Группа по ID
6	Список факультетов
7	Статистика
8	Справка по полям
0	Выход

Скриншоты для портфолио

Приложение является терминальным, поэтому для презентации подходят скриншоты терминала с локальным запуском. Рекомендуемый набор:

1. выбор года и главное меню после bun run start;
2. статистика через bun run start -- --year 2026 --stats;
3. поиск или фильтрация через команду с --json;
4. детальный просмотр программы через --program-id без --json.

Сохраняйте изображения в каталоге screenshots/ после проверки, что в кадре нет локальных путей, пользовательских данных и лишних сообщений терминала.

Структура проекта

Для просмотра дерева используйте:

tree -L 3

Ключевые пути:

data/ # годовые JSON-снимки
src/index.ts # запуск и маршрутизация
src/cli.ts # интерактивное меню
src/search.ts # поиск и справочники
src/filters.ts # фильтры и статистика
LICENSE # условия использования оригинального кода