Skip to content

AGENTS.md

Latest commit

 

History

History
199 lines (166 loc) · 14.9 KB

AGENTS.md

File metadata and controls

199 lines (166 loc) · 14.9 KB
Raw

AGENTS.md — OneScriptJS

Точка входа для AI-агентов и автоматизации (DSH-режим). Здесь: цель проекта, инструменты, команды, структура каталогов, карта «C# → TypeScript» и правила, которых обязан придерживаться каждый агент.

1. Что это за проект

OneScriptJS — переписанный на TypeScript движок OneScript (язык, совместимый с 1С/BSL). Требования из task.md:

  • запускаться на Node.js и в браузере;
  • подключаться в браузере как <script src="/onescript.js"></script>;
  • исполнять код из кастомного элемента <one-script>; Сообщить() — функция стандартной библиотеки, выводит в JavaScript console.log (пример — examples/hello.html).

Оригинал на C# лежит в reference/OneScript/ (игнорируется git-ом, см. .gitignore). Это справочный исходник, а не код нашего репозитория — его не менять.

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

2. Стек и инструменты

  • pnpm — менеджер пакетов. Как запускать в DSH-окружении — см. §6.
  • Node.js >= 20. В DSH-окружении использовать системный node из nvm, а не встроенный DSH-node (см. §6).
  • TypeScript — strict-режим (tsconfig.json).
  • Vite — сборка браузерного бандла и Node-библиотеки.
  • Vitest — юнит-тесты.

3. Команды

Действие Команда
Установить зависимости pnpm install
Проверка типов pnpm typecheck
Собрать браузерный бандл (dist/onescript.js) pnpm build:browser
Собрать Node-библиотеку (dist/node/) pnpm build:node
Полная сборка (типы + браузер + Node) pnpm build
Запустить тесты pnpm test
Проверить, что API задокументирован в справочнике pnpm check:docs
Тесты в watch-режиме pnpm test:watch
Dev-сервер (для examples/) pnpm build:browser && pnpm dev
Статическая сборка + preview pnpm demo

4. Структура каталогов

OneScriptJS/
├── AGENTS.md               ← этот файл
├── task.md                 ← исходное ТЗ
├── package.json
├── tsconfig.json / tsconfig.build.json
├── vite.config.ts          ← браузерная сборка (onescript.js)
├── vite.node.config.ts     ← Node-сборка (ESM + CJS)
├── vitest.config.ts
├── src/
│   ├── index.ts            ← точка входа библиотеки (Node / бандлеры)
│   └── browser/
│       └── onescript.ts  ← браузерная точка входа (<one-script>)
├── tests/                  ← юнит-тесты Vitest
├── examples/               ← HTML-примеры (hello.html — приёмочный сценарий)
├── docs/
│   ├── architecture.md     ← карта «C# → TypeScript» и план слоёв
│   ├── bsl-surface.md      ← синтаксис и stdlib BSL по эталонным тестам
│   ├── reference.md        ← справочник API (функции, объекты, перечисления)
│   └── status.md           ← статус переноса
└── reference/              ← исходник OneScript на C# (не коммитится)

5. Карта «C# → TypeScript» (кратко)

Подробнее — docs/architecture.md. Ключевые соответствия:

Слой (C#, reference/OneScript/src/) Назначение Куда в TypeScript
OneScript.Language лексер / препроцессор / парсер / AST src/lexer, src/parser, src/ast
OneScript.Core система типов, значения, контексты src/runtime (типы/значения)
ScriptEngine стековая ВМ, компилятор, фасад движка src/runtime (ВМ)
OneScript.StandardLibrary стандартная библиотека BSL src/stdlib
oscript, ScriptEngine.HostedScript CLI / хостинг src/node (CLI)
веб-обёртки браузерное исполнение src/browser/onescript.ts

6. Правила и конвенции

  1. Менеджер пакетов — только pnpm. В DSH-окружении встроенный DSH-node не может загружать нативные аддоны (macOS: «different Team IDs» у .node-библиотек rollup/esbuild), поэтому запускать pnpm нужно системным node из nvm:

    export PATH="$HOME/.nvm/versions/node/v24.22.0/bin:$PATH"
node "$DSH_PNPM" install   # $DSH_PNPM = путь к pnpm.mjs из load_workspace_dependencies
node "$DSH_PNPM" test

    На обычной машине (без DSH) достаточно pnpm install / pnpm test с node >= 20.

  2. TDD — сначала падающий тест (Vitest), потом минимальная реализация. Доступен скилл generic-superpowers-test-driven-development.

  3. Проверка перед «готово» — прогнать pnpm typecheck && pnpm test (и при необходимости pnpm build), показать вывод как доказательство (generic-superpowers-verification-before-completion). Менял API/stdlib — прогони pnpm check:docs и обнови справочник, если он отстал (правило 9).

  4. BSL-имена двуязычные — как в оригинале, поддерживать русские и английские алиасы идентификаторов (Сообщить/Message, Если/If и т.п.).

  5. Не трогать reference/ — только читать. Это эталон для сверки поведения.

  6. Коммиты — только по явной просьбе пользователя. Не коммитить reference/, node_modules/, dist/, coverage/.

  7. Стиль — 2 пробела, LF, строгий TypeScript; .editorconfig обязателен.

  8. Файлы в браузер — onescript.ts использует только браузерные API; общая логика живёт в src/, не в src/browser/.

  9. Синхронизация API и справочника — расширяешь stdlib или язык (новая функция, тип, объект, метод, свойство, перечисление; изменение сигнатуры или поведения) — в том же изменении обнови docs/reference.md. Справочник — часть definition of done, наравне с тестами; если меняются пользовательские сценарии, обнови также README и examples/. Расхождение ловят pnpm check:docs (имя из src/ не найдено в справочнике — exit 1) и Vitest-тест tests/check-api-docs.test.ts (входит в pnpm test).

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

7. Философия разработки: «ленивый сеньор» (Ponytail)

Базовый принцип: лучший код — тот, который ты не написал. Решай всю задачу минимальным количеством нового кода. Это не про «меньше токенов»: код остаётся маленьким, потому что он необходим, а не потому что его «ужали». По мотивам скила DietrichGebert/ponytail.

7.1. Прежде чем писать код

  • Прочитай задачу и код, который она меняет. Перечисли все места, куда должно дотянуться изменение: вызывающие, тесты, фикстуры, конфиг, экспорты.
  • Проверь, что изменение может сломать у пользователей: данные, которые оно уничтожит или раскроет, вызывающих, которые перестанут работать.
  • Это и есть scope. Дополнительные фичи — не scope.

7.2. Лестница решений — остановись на первой ступени, которая выдерживает

  1. Это вообще нужно? Пропусти фичи, опции и гибкость, которые никто не просил, и назови их одной строкой. Расплывчатый запрос получает минимальную версию.
  2. Уже есть в кодовой базе (хелпер, компонент, сервис, паттерн)? Используй так, как это делает окружающий код.
  3. Стандартная библиотека или нативная возможность платформы/браузера? Используй её, если в проекте нет своей.
  4. Уже установленная зависимость? Используй её. Не добавляй зависимость ради пары строк.
  5. Можно одной строкой, понятной с первого взгляда? Одной строкой.
  6. Иначе — минимальный код, который работает.

7.3. Лениться в решении, но не в самом изменении

  • Доводи до конца каждую часть задачи: вызывающих, тесты и фикстуры, которые ломает твоё изменение.
  • Никаких абстракций, обёрток, конвертаций типов, опций, конфигов, бойлерплейта и кода «на потом», который никто не просил. Удаление лучше добавления.
  • Сохраняй структуру кодовой базы: её слои, интерфейсы и конвенции.
  • Комментарий — только «почему», которое код не показывает, одной строкой.
  • Багфикс: прежде чем править, пройдись по всем вызывающим изменяемой функции и почини корневую причину один раз в общем коде.
  • Переносимый/объединяемый код сохраняет свои обработку ошибок и валидацию.
  • Новая нетривиальная логика (ветвление, цикл, парсер, деньги/безопасность, целый новый скрипт) оставляет один маленький тест — пишется по TDD из §6.2. Тривиальным изменениям тест не нужен.
  • Осознанное сокращение с известным лимитом помечай комментарием: shortcut: <лимит>, <когда апгрейдить>.

7.4. Никогда не вырезай

Валидацию на границах доверия, обработку ошибок, предотвращающую потерю данных, безопасность, доступность (a11y) и всё, что явно просил пользователь. Ленивый — не значит халатный.

7.5. Завершай ответ раскрытием

В конце каждого ответа одной-двумя строками укажи: что ты пропустил или не проверил, и какой риск пользователь должен знать.

8. Связанные документы

  • docs/reference.md — полный справочник API: функции с параметрами/возвратом, объекты с полями и методами, перечисления.
  • task.md — исходное ТЗ и приёмочный HTML-пример.
  • docs/architecture.md — карта слоёв и статус переноса.
  • specs/ — спецификации незавершённых работ (001–013); план и задачи создаются в каталоге конкретной спеки по мере готовности.
  • docs/bsl-surface.md — синтаксис и stdlib BSL (по reference/tests).
  • reference/OneScript/AGENTS.md — инструкции к оригиналу (для справки).
  • reference/OneScript/docs/developer_docs.md — архитектура C#-движка.
  • reference/OneScript/docs/contexts.md — как устроены контексты/методы BSL.