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

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

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

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 (см. .github/workflows/). Локально перед коммитом разработчики запускают cargo fmt и cargo clippy вручную.

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

Должен пройти ~9500+ тестов (на 0.5.1; точное число меняется с ростом кодовой базы). Перед ссылкой на pre-existing failure перепроверяйте его актуальность на main.

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

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'ы

  • При bump'е версии — AstraCode (vX.Y.Z) появляется во многих снапшотах. bash find astracode-rs/tui/src/status/snapshots -name '*.snap' \ | xargs sed -i 's/AstraCode (vOLD)/AstraCode (vX.Y.Z)/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

Включено в CI; локально разработчики запускают cargo fmt --check и cargo clippy перед коммитом.

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

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

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

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

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. Code style

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

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

Naming

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

Error handling

  • 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-config.yaml и git pre-commit hooks. Проверки кода выполняются в CI (.github/workflows/) и локально разработчиком вручную:

bash
cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

Поскольку git-хуки не настроены, git commit --no-verify не требуется.

10. Workflow для contributing

text
1. Создать ветку: git checkout -b feat/my-feature
2. Сделать правки
3. cargo fmt --all
4. 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 с описанием

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

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

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

  1. Id: добавить вариант в SlashCommandId в slash-commands/src/id.rs (порядок вариантов = порядок в меню): rust #[strum(serialize = "foo")] Foo, TUI реэкспортит его как SlashCommand автоматически (pub use astracode_slash_commands::SlashCommandId as SlashCommand).

  2. Метаданные: добавить запись SlashCommandSpec в реестр REGISTRY (slash-commands/src/commands.rs) — EN/RU description, usage, availability (during_task/in_side/requires_session), feature_gates, hidden_in_popup.

  3. Разрешение/алиасы: при необходимости добавить алиасы в id.rs::aliases().

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

  5. Диспатч: ветка в chatwidget/slash_dispatch.rs (TUI) и/или серверный handler в app-server (slashCommand/dispatch). Исчерпывающий match по SlashCommandId заставит завести хендлер.

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

  7. Тесты: обновить snapshot-тесты, добавить unit-тесты для логики. Реестр проверяется тестами на полноту (registry.rs — каждый SlashCommandId имеет запись).

  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 и 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

Просмотр текущего конфига — slash-команда /debug-config в TUI (отдельной CLI-подкоманды 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. Бенчмарки

Отдельной инфраструктуры бенчмарков (criterion, benches/, [[bench]]) в репозитории нет. Для оценки производительности используются profiling-инструменты (см. выше: perf, flamegraph) и integration-тесты в core/tests/.

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 в корне (см. также upstream codex'а).
ESC