BSLexicon

Браузерный тренажёр языка 1С (BSL): пишешь код, исполняешь и отлаживаешь пошагово — без платформы 1С.

Демо · Концепция · Интеграция с книгами · Дорожная карта · Вклад

---

Что это

Инструмент для обучения и тренировки базового синтаксиса встроенного языка 1С (BSL). Сознательно реализуется только язык, а не платформа: никаких справочников, документов, регистров, форм, HTTP и криптографии. Зато то, что есть, можно наблюдать в исполнении — пошаговый отладчик показывает стек, переменные и их типы в реальном времени.

Педагогически тренажёр построен на принципе reading-first / PRIMM (Predict → Run → Investigate → Modify → Make): сначала читаем и предсказываем поведение чужого кода, потом меняем и пишем своё — в одной среде. Подробнее — в концепции.

Возможности

• ✅ Лексер + парсер BSL (подмножество MVP) → AST. Двуязычные ключевые слова (Если/If), регистронезависимость, строки с экранированием "", литералы дат '20240101', комментарии, доступ к членам (.Метод(), [индекс]), Новый, Для Каждого, Попытка..Исключение.
• ✅ Генераторный tree-walking интерпретатор — исполнение на главном потоке с моделью шага «один оператор = один yield» (вариант A из концепции, §6); процедуры/функции, стек вызовов, исключения (Попытка/ВызватьИсключение/ОписаниеОшибки), watchdog от бесконечных циклов.
• ✅ Пошаговая отладка в UI — step into/over/out, точки останова (клик в поле редактора), подсветка текущей строки, панель «Стек вызовов» с переменными по кадрам.
• ✅ Коллекции — Массив, Структура, Соответствие, СписокЗначений, ТаблицаЗначений (колонки/строки/ячейки, Итог/НайтиСтроки/ВыгрузитьКолонку): конструкторы, методы, индексы, Для Каждого. Ссылочная семантика, глубокая копия по Знач и живая визуализация содержимого в панели переменных.
• ✅ Даты — тип Дата (значимый), литералы '…', арифметика (Дата ± секунды, Дата − Дата), функции Дата/Год/Месяц/День/НачалоДня/ДобавитьМесяц/ТекущаяДата и др.
• ✅ Библиотека функций (34 глобальных): строковые (Лев/Прав/Сред/СтрНайти/СтрЗаменить/ СтрРазделить/СтрСоединить…), числовые (Цел/Окр/Макс/Мин), преобразования, даты, прочее.
• ✅ Живая инспекция переменных — имя, текущий тип (в т.ч. смена типа в рантайме), значение.
• ✅ Каталог языка (YAML) как единый источник правды + инвариант рантайм↔каталог (функции и методы) и doctest примеров в CI.
• ✅ Редактор Monaco + «Запустить», панели «Вывод» и «Переменные»; адаптив для телефонов. Собственная Monarch-подсветка BSL (ключевые слова двуязычно, строки/даты/числа/комментарии, функции и типы из каталога — отдельным цветом); пресеты-примеры по кнопкам.
• ✅ Синтакс-помощник: автодополнение, hover и signature help из каталога; панель-справочник по фактам из выгрузки 1С (697 функций и методов, поиск ru/en).
• 🚧 Дальше — синтакс-помощник (NL-поиск, объяснение ошибок, AI-тьютор, Фаза 2); опционально — апгрейд подсветки на TextMate-грамматику 1c-syntax.

Подробный скоуп MVP и что отложено — в концепции, §4.

Быстрый старт

npm install        # установка зависимостей
npm run dev        # дев-сервер Vite → http://localhost:5173
npm run verify     # типы + инвариант каталога + тесты (то же гоняет CI)
npm run build      # прод-сборка в dist/

Отдельные проверки:

npm run typecheck       # tsc --noEmit по всем проектам
npm run test            # vitest (ядро)
npm run check:catalog   # схема + инвариант рантайм↔каталог + doctest примеров

Архитектура

Принцип из концепции: чужой парсер — свой интерпретатор. Самое ценное (исполнитель с отладкой) пишем сами, потому что пошаговая отладка почти бесплатна лишь тогда, когда сам управляешь циклом вычисления.

                 исходник BSL
                      │
            ┌─────────▼─────────┐
            │   lexer → parser   │   src/core/lexer, src/core/parser
            └─────────┬─────────┘
                      │  AST
            ┌─────────▼─────────────────┐
            │  генераторный интерпретатор │  src/core/interpreter
            │  (yield на каждом операторе)│
            └─────────┬─────────────────┘
                      │  вывод · переменные · события шага
   ┌──────────────────▼──────────────────┐
   │ React-оболочка: Monaco + панели      │  src/app
   └─────────────────────────────────────┘

   Каталог языка (catalog/*.yaml) ── единый источник правды ──▶ рантайм
                                                            ├─▶ Monaco-провайдеры (автодополнение)
                                                            └─▶ панель-справочник (план)

Каталог и рантайм связаны инвариантом: функция в рантайме обязана иметь запись в каталоге и наоборот — иначе падает сборка (npm run check:catalog). Примеры из каталога прогоняются тем же интерпретатором как doctest, поэтому документация физически не расходится с поведением.

Структура репозитория

catalog/              Каталог языка (единый источник правды)
  schema.json         JSON-схема записи каталога
  functions/*.yaml    Глобальные функции (Сообщить, СокрЛП, ВРег, …)
  methods/*.yaml      Методы типов (Массив.Добавить, Структура.Вставить, …)
  types/*.yaml        Типы (Число, Строка, Массив, Структура, …)
src/
  core/               Ядро (чистый TS, без фреймворка)
    lexer/            Токены, двуязычные ключевые слова, лексер
    parser/           AST + рекурсивный парсер
    interpreter/      Значения, коллекции, область видимости, генераторный интерпретатор, функции/методы
    debugger/         DebugSession — драйвер пошаговой отладки поверх генератора
    index.ts          Публичный API ядра: run(), Interpreter, DebugSession, типы
  app/                React-оболочка: редактор + панели (вывод, переменные, стек)
scripts/
  check-catalog.ts    Валидация схемы + инвариант рантайм↔каталог + doctest
tests/                Тесты ядра (vitest)
docs/concept.md       Концепция проекта
.github/workflows/    CI (проверки) и деплой на GitHub Pages

Дорожная карта

Фаза	Содержание	Статус
0	Каталог языка (YAML) как единый источник правды	🟢 готова
1	Лексер/парсер → генераторный интерпретатор с отладкой; Monaco; панель-справочник; runnable-примеры	🟢 ядро MVP готово (язык с коллекциями/датами/исключениями, отладчик, подсветка, автодополнение/hover/справочник)
2	AI-тьютор поверх каталога (NL-поиск, объяснение ошибок) — Pages + тонкий прокси	⚪ план
3	Встраиваемый компонент с event-API → обёртка под LMS (LTI/xAPI/SCORM)	⚪ план

Технологии

TypeScript (strict) · React · Vite · Monaco Editor · Vitest · GitHub Actions → GitHub Pages. Ядро (src/core) не зависит от фреймворка и переиспользуемо как встраиваемый компонент.

Интеграция с книгами

BSLexicon принимает листинги по URL — книга формирует ссылку, читатель кликает и сразу видит готовый код в редакторе. Поддерживается ?code, ?gzcode (gzip для QR-кодов), ?source/?title (провенанс-баннер), ?embed=1 (режим iframe).

Подробности, примеры и готовые функции кодирования — в docs/book-integration/.

Вклад

Новые функции и типы добавляются записью в catalog/ + реализацией в рантайме — см. CONTRIBUTING.md. PR не пройдёт CI, пока каталог и рантайм не согласованы.

Лицензия

MIT © Miroshnichenko Alexandr