0.4.11
Поиск по документации… ⌘K
17 · Техническая документация

17. Разработка

Краткое руководство для контрибьюторов: сборка, тесты, snapshot-тесты, стиль кода.

1. Подготовка окружения

Rust toolchain

bash
# Установить rustup, если ещё нет
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Активировать нужную версию из rust-toolchain.toml
cd astracode/astracode-rs
rustup show           # покажет используемую версию

Системные зависимости

Linux (Ubuntu/Debian):

bash
sudo apt install build-essential pkg-config libssl-dev libsqlite3-dev cmake clang bubblewrap git

macOS:

bash
xcode-select --install
brew install cmake llvm

IDE

Поддерживаются: - VS Code + rust-analyzer (рекомендуется). - RustRover. - Helix / Neovim с rust-analyzer LSP.

rustfmt и clippy запускаются в CI; локально их удобно прогонять через just fmt и just fix.

2. Сборка

bash
cd astracode-rs

# Дев-сборка (быстрая, без оптимизаций)
cargo build --bin astracode

# Релиз-сборка (медленная, но оптимизированная)
cargo build --release --bin astracode

# Конкретный крейт
cargo build -p astracode-tui
cargo build -p astracode-core-skills

Бинарник: - Дев: target/debug/astracode - Релиз: target/release/astracode

Запуск из исходников:

bash
cargo run --bin astracode -- --help
cargo run --release --bin astracode

3. Тесты

Полный прогон

bash
cargo test --workspace

Должен пройти весь набор тестов воркспейса (точное число растёт от версии к версии). Один тест (goal_menu_budget_limited_snapshot) падал и до изменений — это известный нестабильный тест, не блокирующий.

Конкретный крейт

bash
cargo test -p astracode-tui
cargo test -p astracode-core-skills

Конкретный тест

bash
cargo test --workspace cd_path_tab_completes_one_segment

С выводом

bash
cargo test -- --nocapture

Параллелизм

bash
cargo test -- --test-threads=4

По умолчанию tokio-тесты на runtime'е могут плохо параллелиться — можно --test-threads=1 для дебага.

4. Snapshot-тесты (insta)

Многие TUI-тесты используют insta — снимки ожидаемого вывода:

bash
# Прогнать
cargo insta test --workspace

# Просмотреть pending снапшоты
cargo insta review

# Принять все pending
cargo insta accept --workspace

# Отклонить все pending
cargo insta reject --workspace

Снапшоты лежат в */snapshots/*.snap рядом с тестами:

text
astracode-rs/tui/src/status/snapshots/
├── status_full_default.snap
└── ...

Когда обновлять snapshot'ы

  • При повышении версии — AstraCode (vX.Y.Z) появляется во многих снапшотах. bash find astracode-rs/tui/src/status/snapshots -name '*.snap' \ | xargs sed -i 's/AstraCode (v0.4.11)/AstraCode (v0.4.12)/g'
  • При изменении локализации.
  • При добавлении новых slash-команд (изменится slash_commands.snap).

⚠️ Не обновлять снапшоты «вслепую» через cargo insta accept без просмотра — это может скрыть регрессии.

5. Линтинг

bash
cargo fmt --all                     # форматирование
cargo fmt --all -- --check          # проверить (без правок)
cargo clippy --workspace --all-targets --all-features -- -D warnings

Удобные обёртки из justfile в корне репо:

bash
just fmt    # форматирование
just fix    # автоисправления (fmt + clippy --fix)

Те же проверки выполняются в CI.

6. Bazel (опционально)

Для воспроизводимых сборок:

bash
bazel build //astracode-rs/cli:astracode
bazel test //astracode-rs/...

MODULE.bazel в корне. Каждый крейт имеет BUILD.bazel. Используется в CI для гарантии бит-в-бит воспроизводимости.

7. Структура крейта

Типичный крейт:

text
astracode-rs/tui/
├── Cargo.toml
├── BUILD.bazel
├── src/
│   ├── lib.rs              # точка входа
│   ├── chatwidget.rs
│   ├── bottom_pane/
│   │   ├── mod.rs
│   │   ├── chat_composer.rs
│   │   └── ...
│   ├── chatwidget/
│   │   ├── mod.rs
│   │   └── ...
│   ├── snapshots/          # тестовые snapshots
│   └── tests/              # интеграционные тесты (если есть)
└── tests/                  # blackbox-тесты

8. Стиль кода

Общие правила

  • Форматтер: rustfmt (конфиг в rustfmt.toml).
  • Линтер: clippy без warnings (-D warnings).
  • Без TODO в main: либо фиксить, либо TODO с issue-номером.
  • Не комментировать тривиально: код должен говорить сам за себя.
  • Локализация: новые user-facing строки сразу в EN+RU.

Именование

  • snake_case для функций, переменных, модулей.
  • CamelCase для типов и enum-вариантов.
  • SCREAMING_SNAKE_CASE для констант.

Обработка ошибок

  • anyhow::Result<T> для bin/application code.
  • thiserror-based для библиотечных ошибок.
  • ? для пропагации — без unwrap() в production пути (кроме явно invariant'ов).

Локализация

Когда добавляете новый user-facing текст: 1. Если это slash-команда — обновить EN/RU описания в slash_command.rs + help_text.rs. 2. Если это сообщение об ошибке — найти соответствующий localize_* helper или создать новый. 3. Snapshot-тесты обновить.

9. Проверки перед коммитом

Автоматического pre-commit-фреймворка в репозитории нет (файла .pre-commit-config.yaml нет). Перед коммитом прогоните проверки вручную:

bash
just fmt              # форматирование (cargo fmt)
just fix              # автоисправления (fmt + clippy --fix)
cargo test            # тесты (или cargo test --workspace)

Эти же проверки выполняются в CI.

10. Процесс участия в разработке

text
1. Создать ветку: git checkout -b feat/my-feature
2. Сделать правки
3. just fmt
4. just fix   # либо cargo clippy --workspace --all-targets -- -D warnings
5. cargo test --workspace
6. cargo insta review   # если есть snapshot-изменения
7. git add -A && git commit -m "feat(tui): add ..."
8. git push origin feat/my-feature
9. Создать MR/PR в main с описанием

Commit messages — conventional commits style (см. 16-cicd.md).

11. Добавление новой slash-команды

Если хотите добавить /foo:

  1. Enum: добавить вариант в SlashCommand в tui/src/slash_command.rs: rust #[strum(serialize = "foo")] Foo,

  2. Описание: добавить EN/RU в description(): rust SlashCommand::Foo => match locale { En => "do foo", Ru => "сделать foo", },

  3. Флаги: при необходимости в available_during_task, available_in_side_conversation, supports_inline_args.

  4. Фильтр: если команда условная (feature-gate), добавить в bottom_pane/slash_commands.rs:builtins_for_input.

  5. Диспатч: ветка в chatwidget/slash_dispatch.rs: rust SlashCommand::Foo => self.handle_foo(args),

  6. Хелп: добавить overview-строку и per-command детали в help_text.rs.

  7. Тесты: обновить snapshot-тесты, добавить unit-тесты для логики.

  8. Документация: обновить 04-slash-commands.md.

12. Добавление нового поля в config

Если хотите добавить [foo].bar в config.toml:

  1. Тип: добавить в структуру в config/src/...: rust #[derive(Deserialize)] pub struct FooConfig { pub bar: Option<String>, }

  2. Дефолт: реализовать Default или указать в коде.

  3. Использование: пробросить в нужные места (через Config struct).

  4. Документация: обновить 03-configuration.md и docs/config.md (файл astracode-rs/config.md — лишь редирект на него).

  5. Тесты: добавить тесты на парсинг и валидацию.

13. Дебаг

bash
# Включить trace-логи
RUST_LOG=debug astracode

# Только конкретного модуля
RUST_LOG=astracode_core::agent=trace,astracode_mcp=debug astracode

# В файл
RUST_LOG=debug astracode 2> /tmp/astracode-debug.log

Просмотр текущего конфига (в TUI): /debug-config.

14. Профилирование

bash
# Сборка с debug-info
cargo build --release --bin astracode
RUSTFLAGS="-g" cargo build --release --bin astracode

# Использование с perf
perf record --call-graph dwarf ./target/release/astracode
perf report

# Memory profiling: heaptrack
heaptrack ./target/release/astracode

15. Бенчмарки

bash
cargo bench --workspace

Бенчмарки на crit (criterion.rs) лежат в */benches/.

16. Релизный чеклист

См. 16-cicd.md.

17. Полезные команды

bash
# Найти все TODO в коде
grep -rn "TODO\|FIXME\|XXX" astracode-rs/

# Размер крейтов
cargo tree --workspace --depth 0

# Зависимости конкретного крейта
cargo tree -p astracode-tui

# Найти неиспользуемые зависимости
cargo +nightly udeps --workspace

# Размер бинарника по символам
cargo bloat --release --bin astracode

# Время компиляции
cargo build --release --bin astracode --timings

18. Документация (rustdoc)

bash
cargo doc --workspace --no-deps --open

Откроет HTML-документацию по всем крейтам в браузере.

19. Структура workspace

См. 01-architecture.md для полной разбивки крейтов и их назначения.

20. Контакты и вопросы

  • Issue tracker: GitLab issues в основном репо.
  • Дискуссии: внутренние каналы команды.
  • Security: см. SECURITY.md в корне репо.
  • Лицензия: LICENSE в корне репозитория.
ESC