Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (88 loc) · 7.53 KB

AGENTS.md

File metadata and controls

117 lines (88 loc) · 7.53 KB
Raw

AGENTS.md

О проекте

Tenniarb - нативное macOS-приложение (AppKit) для моделирования диаграмм с вычислениями. Ключевая идея: структура + вычисления в формате .tenn.

  • Язык/платформа: Swift, Xcode project (Tenniarb.xcodeproj)
  • UI: программно (без storyboard/xib)
  • Вычисления: JavaScriptCore (ExecutionContext)
  • Markdown: пакет cmkdown (SwiftPM, см. Package.resolved)

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

  • Tenniarb/ - основной код приложения
  • Tenniarb/model/ - модель, операции, undo/redo, вычисления
  • Tenniarb/document/ - NSDocument-слой, парсинг/чтение/запись .tenn
  • Tenniarb/document/tenn/ - lexer/parser Tenn (TennLexer, TennParser)
  • Tenniarb/views/ + ViewController.swift + SceneDrawView.swift - UI и взаимодействие
  • Tenniarb/ElementScene.swift - рендер диаграмм/текста
  • go/ - Go-версия (план в ../my-tasks/tenniarb/roadmap.md), модуль github.com/haiodo/tenniarb/go. go/tenn - lexer, parser, printer; golden-тест на общих web/fixtures. Спецификация расширенного формата - docs/spec/tenn-scene.md.
  • web/ - TypeScript-версия (план в ../my-tasks/tenniarb/plan.md, раздел 3). npm workspaces packages/*, тесты node:test на .ts без компиляции. web/bench/ - бенчмарки рендера, вне workspaces. web/packages/mindmap - встраиваемый mind map без вычислений (план, раздел 6): текстовый протокол блока, бандл dist/mindmap.js.
  • TenniarbTests/ - unit tests (518 тестов, ~70% покрытия); PerformanceTests вынесены в схему Tenniarb-Performance. Схема скипает все остальные suite поимённо - при добавлении нового тестового класса список надо дополнить, иначе он попадёт в perf-прогон.
  • TenniarbUITests/ - UI tests (таргет собирается, но в схеме Tenniarb отключен: skipped = "YES")
  • .github/workflows/ - CI и release pipeline

Локальная сборка и тесты

Все команды собраны в Makefile, make help показывает список:

make build          # сборка Debug
make test           # unit-тесты (без performance)
make test-only T=TenniarbTests/LexerTests
make perf           # только performance-тесты (схема Tenniarb-Performance)
make lint           # SwiftLint
make lint-fix       # автокоррекции SwiftLint
make format         # swift-format --in-place
make format-check   # падает если код не отформатирован
make ci             # SwiftLint + Xcode-сборка и тесты (локально, для Swift-истории)
make clean
make web            # сборка web/packages
make web-test       # typecheck + тесты web/
make go-test        # go vet + go test для go/

Инструменты:

  • Линтер - SwiftLint (.swiftlint.yml), ставится через brew install swiftlint.
  • Форматтер - swift-format из Xcode toolchain (.swift-format), ставить нечего.

Performance-тесты исключены из основного прогона (36 сек из 36.5) через SkippedTests в схеме Tenniarb. -only-testing не перекрывает SkippedTests, поэтому для них заведена отдельная схема Tenniarb-Performance, а не флаг.

Если xcodebuild падает из-за plugin/runtime окружения Xcode, сначала привести локальный Xcode в рабочее состояние (xcodebuild -runFirstLaunch) и повторить.

Правила внесения изменений

  1. Пушит только владелец. Агент готовит правку и коммит, git push и релизы - на человеке.
  2. Сохранять совместимость формата .tenn.
  • Любые изменения в parser/lexer/persistence должны не ломать чтение существующих файлов.
  1. Не обходить ElementModelStore при изменениях модели из UI.
  • Операции должны идти через store, чтобы сохранялись undo/redo, уведомления и пересчет.
  1. Учитывать потокобезопасность вычислительного движка.
  • ExecutionContext синхронизирован через syncQueue; не добавлять доступ к JS-контексту в обход этой модели.
  1. Сохранять текущий стиль построения UI.
  • Окна/контроллеры создаются программно (Document, Application, AppDelegate), не добавлять storyboard/xib без явной необходимости.
  1. Не вносить случайные изменения в project.pbxproj.
  • Менять version/build settings только когда это часть задачи.

Минимальная валидация перед сдачей

  1. GUI-тесты открывают окна на машине владельца и забирают фокус: спрашивать разрешение перед GOWT_GUI_TEST=1 go test ./app .... Обычные go test ./... окна не открывают.

  2. Для любых Swift-изменений:

  • swiftlint lint --config .swiftlint.yml
  1. Для parser/lexer/persistence:
  • TenniarbTests/TennTests.swift
  • TenniarbTests/PersistenceTests.swift
  1. Для Markdown/рендера текста:
  • TenniarbTests/MarkDownTests.swift
  • релевантные участки в ElementScene.swift
  1. Для рендера/экспорта:
  • TenniarbTests/svh-generate/TestSVGGenerate.swift (если затронут экспорт/scene rendering)
  1. Для изменений в логике модели:
  • релевантные тесты + проверка, что undo/redo и refresh-события не регресснули.

CI и релизы

  • CI workflow (.github/workflows/ci.yml) проверяет Go (vet + тесты на macOS, Linux и Windows), web-пакеты (typecheck + тесты) и гоняет GUI-тесты под Xvfb. Swift-приложение больше не собирается в CI: Xcode-проект остаётся в дереве как история.
  • Release workflow (.github/workflows/release.yml) запускается по тегу:
    • собирает Release
    • архивирует Tenniarb.app в zip
    • публикует GitHub Release
    • обновляет MARKETING_VERSION в Tenniarb.xcodeproj/project.pbxproj на default branch

Перед изменениями release-логики проверять, что шаг обновления версии в project.pbxproj останется консистентным.

Что не является целью в обычной задаче

  • Рефакторинг всей архитектуры UI
  • Массовая смена формата .tenn
  • Смена схемы релизов/тегов без явного запроса