|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | +- `tasks/` stores public tasks as `.toml` by difficulty (`elementary/`, `easy/`, `medium/`, `hard/`). |
| 5 | +- Each task file path must be `tasks/<level>/<tags[0]>/<name>.toml` (and the same layout in `private/`). |
| 6 | +- `preview/` contains the React/Vite web preview (`preview/src/`, `preview/server.mjs`). |
| 7 | +- Root-level Python scripts (`test_solutions.py`, `check_task_names.py`, `push_tasks.py`) automate validation and publishing. |
| 8 | +- `release/` is generated output (JSON artifacts); `release.tar.gz` is a packaged release. |
| 9 | + |
| 10 | +## Build, Test, and Development Commands |
| 11 | +- `make build` runs name checks then validates tasks and emits JSON to `release/`. |
| 12 | +- `make preview` installs preview deps and runs the local UI at `http://localhost:5173`. |
| 13 | +- `make build-and-preview` builds tasks and launches the preview app. |
| 14 | +- `python test_solutions.py tasks` runs the task solution test runner directly. |
| 15 | +- `make check-names` checks TOML `name` uniqueness and filename alignment. |
| 16 | + |
| 17 | +## Coding Style & Naming Conventions |
| 18 | +- `name` is required, English, and `snake_case`; file names must match `name` exactly and be unique case-insensitively. |
| 19 | +- Follow the task spec in `ai/task_structure.md` and the sample `ai/task_example.toml` for field order. |
| 20 | +- If formatting TOML, use Taplo settings from `taplo.toml` (aligned entries and key reordering). |
| 21 | +- For Python scripts, match existing 4-space indentation and import ordering. |
| 22 | + |
| 23 | +## Testing Guidelines |
| 24 | +- Task validation is executed via `test_solutions.py`; it parses TOML, runs `solution`, and verifies `[[asserts]]`. |
| 25 | +- Test cases live in each task file under `[[asserts]]`; include edge cases, extreme values, and failure-prone inputs. |
| 26 | +- Aim for 25–30 asserts per task; all string data in asserts must be English. |
| 27 | +- Keep `examples` as assertion lines sorted by string length (shortest first). |
| 28 | +- When adding tasks, run `make build` or `python test_solutions.py tasks` before submitting. |
| 29 | + |
| 30 | +## Task Format Essentials |
| 31 | +- Required fields: `name`, `description_en`, `description_ru`, `input_signature`, `output_signature`, `asserts`, `examples`, `solution`, `level`, `tags`, `time_to_solve_sec`. |
| 32 | +- `description_*` uses Markdown with LaTeX (`$...$`/`$$...$$`); keep text concise. |
| 33 | +- `level` maps to expected solution length: elementary (1–2 lines), easy (2–6), medium (7–11), hard (12+). |
| 34 | +- `time_to_solve_sec` follows project guidance (elementary 100–200, easy 200–300, medium 300–600, hard 600–90 as specified). |
| 35 | +- Use only allowed types from `ai/task_structure.md` for signatures. |
| 36 | + |
| 37 | +## Commit & Pull Request Guidelines |
| 38 | +- Recent history uses short, imperative summaries (e.g., “Fix env”). Keep messages concise and action-oriented. |
| 39 | +- PRs should describe the change, list new/updated tasks, and note any command output used for validation. |
| 40 | +- Include preview screenshots only when UI changes are made under `preview/`. |
| 41 | + |
| 42 | +## Configuration & Release Notes |
| 43 | +- Python dependencies live in `requirements.txt`; preview uses `pnpm` in `preview/`. |
| 44 | +- Generated files in `release/` are build artifacts; do not hand-edit them. |
0 commit comments