Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (71 loc) · 5.03 KB

AGENTS.md

File metadata and controls

83 lines (71 loc) · 5.03 KB
Raw

Repository Guidelines

Project Structure & Module Organization

This is an Elixir umbrella app with multiple sub-apps under apps/.

  • apps/codebattle/: Phoenix app with Elixir code in apps/codebattle/lib/, tests in apps/codebattle/test/, and frontend assets in apps/codebattle/assets/.
  • apps/runner/: task runner service and language images under apps/runner/images/.
  • config/, priv/, and top-level mix.exs provide shared configuration and releases.

Main Contexts & Helpers

Core domains expose context modules for public APIs:

  • Codebattle.Game.Context (apps/codebattle/lib/codebattle/game/context.ex): game lifecycle, live game access, and player actions.
  • Codebattle.Tournament.Context (apps/codebattle/lib/codebattle/tournament/context.ex): tournament CRUD, live supervision, and access checks.
  • Codebattle.Tournament.Round.Context (apps/codebattle/lib/codebattle/tournament/round/context.ex): round construction and persistence.
  • Codebattle.Playbook.Context (apps/codebattle/lib/codebattle/playbook/context.ex): game replay records and storage.
  • Codebattle.Event.Context (apps/codebattle/lib/codebattle/event/context.ex): event stages and tournament bootstrapping.
  • Codebattle.Bot.Context (apps/codebattle/lib/codebattle/bot/context.ex): bot selection and runtime start.

Helper modules live alongside their domains:

  • Game helpers: apps/codebattle/lib/codebattle/game/helpers.ex; tournament helpers: apps/codebattle/lib/codebattle/tournament/helpers.ex.
  • Operational utilities: apps/codebattle/lib/codebattle/utils/ (populate tasks/users/clans, release helpers).

Build, Test, and Development Commands

Run every repository command through the dev container. The host has no usable environment for this project, even where a matching toolchain is installed: _build, deps, node_modules, and priv/plts are Docker volumes rather than host directories, and PostgreSQL is reachable only as db:5432 inside the Compose network — it is deliberately not published to the host. A host-side mix test or pnpm run therefore compiles into a different tree and cannot reach the database.

  • Prefer an existing make target (listed below).
  • Otherwise use make dev-exec CMD='...' or ./bin/dev <command>; both route through docker compose exec into the container.
  • Never invoke mix, iex, pnpm, node, or go from a host shell, and do not drive docker compose by hand — use the dev-* targets so the Compose project name and project directory stay consistent.
  • The targets work unchanged from a host terminal or from a terminal inside the container: bin/dev detects CODEBATTLE_DEVCONTAINER=1 and execs directly instead of re-entering.

Host-only exceptions — these drive the host container engine and refuse to run inside the dev container:

  • Container lifecycle: make dev-build, dev-rebuild, dev-stop, dev-down, dev-logs, clean.
  • Image build and publish: make build-local, build-codebattle, build-arm, build-runner, push-codebattle, push-runner, push-codeabttle-arm, and the runner image Makefiles under apps/runner/images/. These orchestrate other containers; treat them as privileged and run them only on trusted code.
  • Ops tooling: make terraform-vars-generate, ansible-edit-secrets, ansible-vault-edit-production.

Common targets:

  • make format / make lint: format or check Elixir formatting.
  • make credo: run Credo static analysis.
  • make lint-js: OXC (oxlint) for frontend assets.
  • make server: start Phoenix (iex -S mix phx.server).
  • make test: ExUnit + coveralls JSON.
  • make test-code-checkers: image executor tests with CODEBATTLE_EXECUTOR=local.

For frontend-only tasks, use make test-fe, make check-js, or make dev-exec CMD='pnpm --dir apps/codebattle <command>' so pnpm remains in the development container.

Coding Style & Naming Conventions

  • Elixir formatting is enforced via mix format (see .formatter.exs).
  • Credo rules live in .credo.exs (120-char line limit).
  • JavaScript/React linting uses OXC (oxlint) via pnpm run lint.
  • Naming: descriptive Elixir modules; camelCase/PascalCase for JS files and components.

Testing Guidelines

  • Use make test as the canonical final repository test command; do not substitute a direct mix test run.
  • Run mix credo --strict and mix dialyzer as part of the final repository verification.
  • ExUnit tests live in apps/*/test/; coverage uses ExCoveralls with a 60% threshold.
  • Frontend tests use Vitest in apps/codebattle/.
  • Name tests after the module/component under test (e.g., user_stats_test.exs, UserStats.test.jsx).

Commit & Pull Request Guidelines

  • Recent commits use short, imperative summaries (e.g., "Fix editor", "Update logo").
  • Keep commits focused; include test results when relevant.
  • PRs should describe the change, list test commands run, and attach screenshots for UI updates.

Configuration & Runtime Notes

  • Releases are defined in mix.exs for codebattle and runner; runner images build via Makefiles in apps/runner/images/.