Skip to content

Latest commit

 

History

History
272 lines (257 loc) · 32.1 KB

status.md

File metadata and controls

272 lines (257 loc) · 32.1 KB

OneScriptJS — статус (компактная сводка)

Движок OneScript (язык 1С/BSL), переписанный на TypeScript. Работает в Node и браузере. Оригинал (эталон) — reference/OneScript/ (C#), не коммитится.

Формат наших скриптов — .osjs (OneScriptJS, браузер). .os — чужой формат ванильного C#-OneScript для бэкенда: движок его исполняет (общая грамматика BSL, эталонный корпус — внутренний регресс), но не блокирует и не переименовывает. Решение и границы — specs/013-osjs-format/spec.md.

Состояние

  • Перенос по старому плану T1–T49 закрыт: язык, стандартная библиотека, браузерная интеграция (DOM, события, декларативные data-os-*), xUnit-раннер и прогон эталонных тестов.
  • pnpm typecheck ✓, pnpm test ✓ — 849 тестов (85 файлов Vitest).
  • Текущая ветка — feat/src_import.
  • Прогон reference/OneScript/tests/*.os: 18/66 файлов проходят целиком; ошибка разбора осталась одна (annotations.os); events.os разбирается, но падает на ПодключитьСценарий (спека 004).
  • Старый docs/plan.md удалён: незавершённые работы вынесены в спецификации specs/; спеки 001, 008, 009, 010, 011, 012 и 013 реализованы, 002, 003, 005, 006, 007 — пока только spec.

Архитектура (слои)

src/lexer (токены) → src/parser (AST + препроцессор #) → src/runtime (values, scope+Ref, context, async (MaybePromise/drive/кванты), interpreter на генераторах с синхронным быстрым путём, enum, object, type, error-info, runner) → src/stdlib (global-context, collections, strings, math, bitwise, json, types, enums, format, tasks/фоновые задания) → src/browser/onescript.ts (script[type="text/osjs"]) и src/node/ (cli, context, files) → src/testing (xUnit-раннер).

Сборка: dist/onescript.js (браузер, IIFE), dist/node/index.{js,cjs,d.ts} (библиотека), dist/cli.mjs (CLI).

Что реализовано

  • Язык: переменные, если/иначеесли/иначе, циклы (Для/Пока/Для Каждого, Прервать/Продолжить), процедуры/функции (Знач/по ссылке), исключения, Перейти/метки, аннотации, тернарный ?(), Новый, препроцессор #.
  • Структура модуля: #Использовать → Перем → методы → исполняемый код; импорт после кода — ошибка. Локальные Перем — в начале метода; объявления после кода и вложенные методы — ошибка разбора (как в DefaultBslParser). Контекст операторов тоже проверяется: Возврат — только в методе (в функции со значением, в процедуре без), Прервать/Продолжить — только в цикле, ВызватьИсключение; — только в блоке Исключение.
  • Импорт файлов: #Использовать "<файл>" — модули-синглтоны с экспортными членами и классы (ПриСозданииОбъекта, Новый), кеш на run() и защита от циклов; Node читает через fs, браузер — через fetch по URL. Работает и из ЗагрузитьСценарийИзСтроки (относительно имени/текущего сценария).
  • Значения/типы: числа, строки, булево, даты, Null/Неопределено, Тип/ТипЗнч, перечисления (НаправлениеПоиска, СтатусСообщения, ХешФункция, ЦветКонсоли, КодировкаТекста, СпециальнаяПапка, ТипДиска, НаправлениеСортировки, СпособКодированияСтроки) и Символы.
  • Коллекции: Массив (многомерный), Структура, Соответствие (+ фиксированные), СписокЗначений, ТаблицаЗначений, ДеревоЗначений.
  • Двоичные данные: БуферДвоичныхДанных, ДвоичныеДанные (hex/Base64/строка, BOM).
  • Система: СистемнаяИнформация, УникальныйИдентификатор, переменные среды, ПустаяСтрока.
  • РегулярноеВыражение (совпадения/группы/имена в нумерации .NET).
  • ГенераторСлучайныхЧисел (диапазон uint32, воспроизводимость по seed).
  • Сценарии: ЗагрузитьСценарийИзСтроки, ЗагрузитьСценарий (файл, Node), ТекущийСценарий, СтартовыйСценарий (тип Сценарий).
  • Pow в decimal-точности 1С (29 значащих цифр для целой степени).
  • Валидация смещений ПобитовыйСдвиг*; методы тест-контекста (ПодробныеОписанияОшибок, ИмяВременногоФайла, ТестПровален, ПроверитьТип).
  • Динамическое исполнение: Выполнить (оператор) и Вычислить (функция) в текущей области видимости; 1/0 → «Деление на ноль»; переменная Для … По … после цикла = «по + 1»; НСтр извлекает язык из ru='…';en='…'.
  • BSL-события (спека 001): ДобавитьОбработчик/УдалитьОбработчик (+ AddHandler/ RemoveHandler), ВызватьСобытие/RaiseEvent, ЭтотОбъект/ThisObject; реестр подписок общий для исполнения, локальная и объектная формы обработчика, порядок подписки и дедупликация, диагностика «Ожидается имя события»/«Ожидается имя обработчика события»/«Метод объекта не обнаружен».
  • Браузер (Фаза 7): объект Документ, события DOM из BSL (Элемент.НаСобытие(Имя, Код), объект Событие), декларативные data-os-* — только в браузерной сборке, src/stdlib остаётся Node-совместимым; внешний .osjs по <script type="text/osjs" src="…"> — fetch от document.baseURI (спека 019).
  • Лексер: многострочные литералы с продолжением |.
  • stdlib: Сообщить (со статусом), строковые, математические, поразрядные (uint32), JSON, Формат (число/дата), файловые (Node: ЧтениеТекста/ЗаписьТекста/ОбъединитьПути), asserts (Ожидаем.Что(…).Равно(…) + сравнения/ЭтоНе/ИмеетДлину/Существует/Содержит), динамический Новый(Тип, …), двоичные данные (БуферДвоичныхДанных, ДвоичныеДанные, hex/Base64/строка).
  • Парсер: Перем a, b, c; (с Экспорт), пропущенные аргументы f(,23), конкатенация смежных строк "a" "b", ВызватьИсключение; (перевыброс), конец блока как терминатор оператора без ;, ключевые литералы как имена свойств (Структура.Истина), пустые операторы ;;.
  • Тестирование: xUnit-раннер runTests (ЮнитТестирование с Проверить*).
  • HTTP-клиент (спека 010): HTTPСоединение/HTTPConnection, HTTPЗапрос/HTTPRequest, HTTPОтвет/HTTPResponse с методами эталона (GET/POST/PUT/DELETE/PATCH/HEAD и произвольный метод), basic-auth, кодировки тела, gzip-нормализация. Вызовы синхронные: в браузере — синхронный XHR, в Node — дочерний процесс с fetch; прокси, SSL-сертификаты, файловое тело и потоки — вне scope.
  • Фоновые задания (спека 011): глобальное ФоновыеЗадания/BackgroundJobs (МенеджерФоновыхЗаданий), ФоновоеЗадание, перечисление СостояниеФоновогоЗадания, методы Выполнить/Очистить/ОжидатьВсе/ОжидатьЛюбое/ ОжидатьЗавершенияЗадач/ПолучитьФоновыеЗадания/ПолучитьТекущее, глобальная Приостановить/Sleep. Модель кооперативная: задания — логические потоки в одном JS-потоке с общим состоянием модуля; переключение в точках ожидания и по квантам (~10 мс), поэтому страница не блокируется. Настоящего параллелизма CPU, ТекущийПоток, БлокировкаРесурса и изоляции данных потоков нет (осознанное расхождение с эталонными потоками C#). Async-рантайм (генераторный интерпретатор с синхронным быстрым путём) стал фундаментом для Асинх/Ждать.
  • Асинхронные методы (спека 012): Асинх/Async перед Процедура/Функция, Ждать/Await и непрозрачное Обещание/Promise. Синтаксис/диагностика — из парсера эталона, семантика — 1C:Enterprise 8.3.18+: вызов async-функции/процедуры сразу возвращает Обещание, Ждать даёт результат или бросает ошибку в точке ожидания, повторное ожидание кэшируется, параметры — по значению, ошибки до первой приостановки сохраняются в Обещании, необработанные — уходят в console.error/stderr. Хост дожидается async-тела и всех Обещаний (flush). Осознанные расхождения: рантайм реализован (в эталоне только разбор); Ждать разрешён в теле модуля; async-процедура тоже возвращает Обещание.

Спецификации — работы в specs/

Спека Тема Состояние
001-bsl-event-handlers BSL-события: ДобавитьОбработчик/УдалитьОбработчик, ВызватьСобытие, ЭтотОбъект реализовано
002-nested-annotations Вложенные и именованные аннотации (парсер) spec
003-date-precision Точность и арифметика дат 1С (1/10000 с) spec
004-script-attach ПодключитьСценарий / ЗагрузитьСценарий из файла spec; ЗагрузитьСценарий (US3) реализован
005-system-settings config.os: ОбновитьНастройкиСистемы / ПолучитьЗначениеСистемнойНастройки spec
006-dynamic-names Разрешение имён в Выполнить/Вычислить («Неизвестный символ») spec
007-browser-playwright Приёмка в реальном браузере (Playwright) spec
008-use-directive #Использовать "<файл>": модули и классы из файлов реализовано
009-module-structure Порядок секций модуля и контекст операторов (паритет парсера) реализовано
010-http-client HTTP-клиент BSL: HTTPСоединение/HTTPЗапрос/HTTPОтвет реализовано
011-background-jobs Фоновые задания: ФоновыеЗадания, ФоновоеЗадание, Приостановить (кооперативная модель) реализовано
012-async-await Асинхронные методы: Асинх/Ждать, Обещание (поверх фоновых заданий) реализовано
013-osjs-format Формат .osjs — отделение от ванильного OneScript; .os — чужой формат, не блокируется реализовано
014-osjs-editor-tooling Редакторные инструменты .osjs: грамматика/описание языка и LSP-сервер (диагностика, подсказки, semantic tokens, навигация); расширение VS Code — позже реализовано
015-embedded-osjs-html Встроенный .osjs в HTML: редакторные инструменты внутри <script type="text/osjs"> («гость в HTML»); слой A (серверный режим) реализован, B/C после клиента VS Code слой A реализован
016-osjs-script-tag Каноническая форма встраивания — <script type="text/osjs">; удаление прежней формы, raw-text семантика, диагностика </script> (OSJS4001) реализовано (runtime + тесты + миграция; правила OSJS4001/4002 — в 015)
017-vscode-client Тонкий клиент VS Code: язык osjs + грамматика, запуск LSP-сервера, HTML-блоки по настройке, локальный .vsix реализовано (сборка/тесты + ручная приёмка в GUI VS Code)
018-embedded-language-mode Embedded language mode в VS Code: TextMate-инъекция <script type="text/osjs"> (подсветка/комментарии/скобки/фолдинг/word pattern) реализовано (грамматика/тесты/сборка + ручная приёмка в GUI VS Code)
019-osjs-src-attr Загрузка сценария по ссылке: <script type="text/osjs" src="…"> грузит внешний .osjs через fetch; импорты/ТекущийСценарий — от URL файла реализовано (runtime + тесты + пример examples/external.html)

Для незавершённых спек следующий шаг — /speckit-plan или /speckit-tasks в её каталоге; реализованы 001, 008, 009, 010, 011, 012, 013, 014, 016, 017, 018 и 019; 015 — слой A (серверный embedded-режим).

Редакторные инструменты для .osjs реализованы по спеке specs/014-osjs-editor-tooling/spec.md: editors/osjs/ — TextMate-грамматика source.osjs, конфигурация языка и метаданные (вендоренная MIT-копия 1c-syntax, см. NOTICE.md); src/lsp/ + src/node/lsp-server.ts — LSP-сервер по stdio (pnpm build:lsp → dist/lsp/server.mjs) с диагностикой (синтаксис + консервативные семантические проверки), completion, hover, semantic tokens, documentSymbol/definition; каталог API генерируется из справочника (pnpm build:catalog, drift-тест). Подключение — в любом LSP-клиенте, см. README и quickstart.md спеки. Тонкий клиент VS Code и установка из .vsix — отдельная следующая работа. Проверка: pnpm typecheck && pnpm test (708 тестов, включая протокольные in-process и smoke собранного сервера) и pnpm build; ручная проверка выполнена владельцем в Neovim 0.12.2 (конфиг ~/.config/nvim/lua/osjs.lua): подсветка (semantic tokens), диагностика, автодополнение (Сообщить), hover, переход к определению локального метода, переход в импортированный .osjs через #Использовать и outline (documentSymbol: регионы #Область с методами) подтверждены. Браузерная приёмка к инструментам неприменима: они не исполняют BSL и не входят в dist/onescript.js (конституция V).

Каноническая форма встраивания — <script type="text/osjs">: реализовано по спеке specs/016-osjs-script-tag/spec.md. Прежний кастомный элемент удалён (пользователей не было, обратная совместимость не требуется): браузерный вход собирает data blocks script[type="text/osjs"] в порядке документа и исполняет их последовательно в свежих контекстах; содержимое — raw text (<, >, & без экранирования; </script> обрывает блок); конституция поправлена до 3.0.0 (принцип II). Проверка: pnpm build && pnpm test (728 тестов, включая новый browser-script-tag и мигрированные browser-suite'ы, а также демо-страницы examples/); ручная проверка в реальном браузере выполнена владельцем — примеры работают на новой форме.

Загрузка внешнего .osjs по ссылке — реализовано по спеке specs/019-osjs-src-attr/spec.md: <script type="text/osjs" src="app.osjs"></script> скачивает файл через fetch (URL относительно document.baseURI) и исполняет его в контексте блока; inline-содержимое тега игнорируется, пустой src — фолбэк на inline. Внутри файла #Использовать разрешается от URL файла, ТекущийСценарий().Источник указывает на него; ошибки загрузки (404/CORS/сеть) уходят в console.error и не прерывают остальные блоки, документный порядок сохраняется. Каждый блок исполняется независимо (кеша нет). Пример — examples/external.html; тесты — browser-script-tag (внешний src) и browser-demo. Проверка: pnpm typecheck && pnpm test (849 тестов) и pnpm build зелёные; ручная проверка в реальном браузере выполнена владельцем — работает.

Встроенный .osjs в HTML — слой A реализован по спеке specs/015-embedded-osjs-html/spec.md («гость в HTML»): src/lsp/html-blocks.ts находит script[type="text/osjs"] в HTML, src/lsp/embedded.ts анализирует блоки анализатором 014 и переносит диапазоны в координаты HTML; сервер по languageId: html отдаёт диагностику (включая OSJS4001 Error для обрыва </script> и OSJS4002 Warning для <script/<!--), completion/hover/definition и semantic tokens — только внутри блоков, .html не заявляется и вне блоков молчит. Проверка: pnpm test (779 тестов, включая html-blocks/embedded/protocol) и pnpm build; headless-проверка в Neovim 0.12 пройдена: mapped-диагностика в HTML-координатах, OSJS4001 для обрыва </script>, semantic tokens и completion (Сообщить) внутри блоков. Ручная проверка в GUI Neovim выполнена владельцем полностью: mapped-диагностика, semantic tokens, completion/hover, gd (локальный символ и импорт #Использовать), изоляция блоков и отсутствие вмешательства вне блоков подтверждены (фикстура tests/fixtures/lsp/embedded/manual-check.html, раздел 5 quickstart.md спеки 015). Слой B — тонкий клиент VS Code — реализован по спеке specs/017-vscode-client/spec.md: extensions/vscode/ регистрирует язык osjs и грамматику, запускает LSP-сервер на Node-рантайме VS Code и по настройке onescriptjs.embeddedInHtml обслуживает HTML-блоки; сборка .vsix — pnpm build:vscode (dist/vscode/onescriptjs-0.1.0.vsix, 10 файлов, 0,24 МБ; сервер/грамматика/бандл внутри, без node_modules). Установка — code --install-extension …; автоматические проверки (790 тестов) и сборка пакета зелёные; ручная приёмка в GUI VS Code выполнена владельцем: hover/gd/автодополнение и прочее работают и в .osjs-файлах, и во встроенных блоках HTML. Следующий слой — C: грамматическая инъекция <script type="text/osjs">/embedded language mode. Сборка .vsix требует Node.js >= 22 (упаковщик); рантайму нужен только VS Code.

Слой C — embedded language mode — реализован по спеке specs/018-embedded-language-mode/spec.md: TextMate-инъекция editors/osjs/osjs-embedded.tmLanguage.json размечает содержимое script[type="text/osjs"] как meta.embedded.block.osjs и включает source.osjs; embeddedLanguages-мэппинг на язык osjs даёт в регионе BSL-комментарии/скобки/word pattern/фолдинг. Вне блока — HTML без изменений, .osjs не тронут; работает и без LSP-сервера. Проверка: pnpm test (838 тестов, включая scope-тесты на вендоренной HTML-грамматике VS Code 1.146.0) и pnpm build:vscode (.vsix 11 файлов, обе грамматики внутри). Ручная приёмка в GUI VS Code выполнена владельцем: подсветка, Ctrl+/, фолдинг #Область, word pattern/Emmet и прочие UI-кейсы работают (T014 закрыт).

Известные пробелы

  • VS Code embedded language mode (спека 018): ручная приёмка UI пройдена (подсветка/ комментарии/фолдинг/word pattern/Emmet); многострочный type-атрибут тега не поддерживается (TextMate построчный); работает только в VS Code-семействе (остальные — semantic tokens).
  • VS Code клиент (спека 017): ручная проверка в GUI пройдена (.osjs и HTML-блоки); .vsix не подписан и не публикуется в Marketplace; сборка расширения требует Node.js >= 22 (@vscode/vsce); HTML-подсветка — только semantic tokens (грамматической инъекции нет); engines.vscode ^1.91.0.
  • Встроенные блоки (спека 016): ручная проверка в браузере пройдена (примеры работают), но поведение data blocks под строгой CSP-политикой script-src отдельно не проверялось; happy-dom эмулирует DOMContentLoaded/readyState (в тестах — 'interactive'); динамически добавленные блоки не поддерживаются по решению владельца (v1).
  • Внешний .osjs по src (спека 019): кросс-доменная загрузка требует CORS, а CSP-политика страницы должна разрешать connect-src (data block при этом по-прежнему не исполняется браузером); содержимое внешнего файла из HTML редакторными инструментами не анализируется (это отдельный .osjs-документ); ТекущийСценарий().Источник — URL в percent-encoded нотации; кеша исполнения нет — каждый блок с одним URL исполняется отдельно.
  • Embedded-инструменты HTML (015, слой A): OSJS4001 — эвристика (обрыв определяется по незакрытой строке/parse-error у конца блока), возможны редкие ложные/пропуски; OSJS4002 — текстовый скан (срабатывает и в строках/комментариях BSL); outline BSL внутри HTML не реализуется; грамматической инъекции и клиента VS Code пока нет (подсветка — semantic tokens); headless- и ручная (GUI Neovim) проверки пройдены — все сценарии слоя A подтверждены; остаются известные ограничения: эвристика OSJS4001, текстовый скан OSJS4002, отсутствие грамматической инъекции и клиента VS Code (слои B/C).
  • LSP-инструменты (спека 014): ручная проверка выполнена в Neovim 0.12.2 — подсветка, диагностика, completion, hover, definition (локальный метод и импортированный .osjs), outline (documentSymbol) подтверждены; не проверялись визуально поведение .os (должен остаться без наших инструментов) и Zed/другие клиенты. Семантические проверки намеренно консервативные (Warning), локальные переменные для definition выводятся из присваиваний/Перем/счётчиков циклов.
  • definition для локальной переменной ищет последнее объявление до курсора; сложные области видимости (вложенные блоки с перекрытием имён) не моделируются.
  • annotations.os — после спеки 002 перестанет падать на разборе, но чтение аннотаций требует Рефлектор (вне scope 002).
  • events.os — требует 004 (ПодключитьСценарий, самоподключение файла): 8 сценариев событий уже воспроизведены в tests/events.test.ts (спека 001), полный прогон файла отложен до 004.
  • #Использовать (спека 008) импортирует только файлы: поиск библиотек по имени (lib.config, версии, OSCRIPT_LIB) не поддерживается; #Использовать asserts остаётся no-op. ЗагрузитьСценарийИзСтроки резолвит импорты (Node — с чтением с диска, браузер — только из предзагруженных источников).
  • eval.os: ТестДолжен_ПроверитьРаботоспособностьВПодключенныхСценариях требует #Использовать/библиотеки (спека 008 покрывает импорт файлов; поиск библиотек по имени остаётся вне scope), остальные — 004 (ЗагрузитьСценарий реализован) и Node-контекст (ОбъединитьПути).
  • date-behavior.os — заблокирован JSON/XML-подсистемами (ЗаписьJSON/ЧтениеJSON как объекты, XMLСтрока, ФорматДатыJSON), часовыми поясами и ЗначениеЗаполнено (вне 003).
  • Вне старого плана и спецификаций (нужны отдельные спеки): ТекстовыйДокумент, ЧасовойПояс, ХешированиеДанных, КвалификаторыЧисла/КвалификаторыСтроки, ЗначениеЗаполнено, ПолучитьИмяВременногоФайла; объектные ЗаписьJSON/ЧтениеJSON (сейчас функции с одним аргументом); Формат: ЧГ с кастомными размерами, ДП/ДД.
  • Процессы, COM, XML, прокси/SSL-сертификаты и файловые тела HTTP — вне scope первой очереди; HTTP-клиент реализован в спеке 010.
  • Асинхронность языка (Асинх/Ждать, Обещание) реализована (спека 012), но без отмены, таймаутов ожидания и КогдаВсе/КогдаЛюбой; async-конструкторы, async-обработчики событий с ожиданием, async-импорт модулей и async HTTP (fetch) — вне scope. Job, нацеленный на async-метод, получает Обещание как Результат и не ждёт его.
  • Фоновые задания: нет отмены, приоритетов и настоящего параллелизма; Приостановить и ожидания — единственные точки переключения основного скрипта; импортируемые модули рекомендуется держать синхронными; xUnit-раннер не поддерживает тесты с приостановкой (shortcut).