|
1 | 1 | # Repository Guidelines |
2 | 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 |
| 3 | +## Source of Truth |
| 4 | +- Use `ai/project_structure.md` for task placement and naming rules. |
| 5 | +- Use `ai/task_structure.md` for the canonical TOML schema, field semantics, and allowed type signatures. |
| 6 | +- Use `ai/task_example.toml` as the formatting and ordering reference when creating or editing tasks. |
| 7 | +- If this file conflicts with the `ai/` docs, follow the `ai/` docs. |
| 8 | + |
| 9 | +## Project Structure |
| 10 | +- All tasks live under `tasks/`. |
| 11 | +- There are 4 task levels: `elementary`, `easy`, `medium`, `hard`. |
| 12 | +- Every task must have a unique `name`. |
| 13 | +- Every task has a `tags` array of strings. |
| 14 | +- The path for each task must be `tasks/<level>/<tags[0]>/<name>.toml`. |
| 15 | +- `preview/` contains the local React/Vite preview app. |
| 16 | +- Root scripts such as `test_solutions.py`, `check_task_names.py`, and `push_tasks.py` handle validation and publishing. |
| 17 | +- `release/` and `release.tar.gz` are generated build artifacts; do not edit them manually. |
| 18 | + |
| 19 | +## Build And Validation |
| 20 | +- `make check-names` verifies task-name uniqueness and filename alignment. |
| 21 | +- `python test_solutions.py tasks` validates all public tasks by parsing TOML, running `solution`, and checking `[[asserts]]`. |
| 22 | +- `make build` runs name checks, rebuilds `release/`, and validates public tasks. |
| 23 | +- `make preview` installs preview dependencies and starts the local UI. |
| 24 | +- `make build-and-preview` builds first, then starts the preview app. |
| 25 | + |
| 26 | +## Task Authoring Rules |
31 | 27 | - 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. |
| 28 | +- Optional fields: `limits`, `comment`. |
| 29 | +- Keep field order aligned with `ai/task_example.toml`. |
| 30 | +- `name` must be English and `snake_case`; the filename must match it exactly. |
| 31 | +- `description_en` and `description_ru` are Markdown strings rendered with math support; keep them concise. |
| 32 | +- Wrap mathematical notation in LaTeX using `$...$` or `$$...$$`. |
| 33 | +- `limits`, when present, should be a Markdown list of constraints using math notation only, without prose. |
| 34 | +- `examples` must be a fenced-style assertion block as a string, sorted by line length from shortest to longest. |
| 35 | +- `solution` must define `solution(...)`, stay concise, and avoid unnecessary imports or boilerplate. |
| 36 | +- `tags` may be empty, but when non-empty the first tag determines the directory name in the task path. |
| 37 | + |
| 38 | +## Signatures And Types |
| 39 | +- `input_signature` is an array of arguments, each with `argument_name` and a `type` object. |
| 40 | +- `output_signature` is an object containing a `type` object. |
| 41 | +- Only use types allowed by `ai/task_structure.md`. |
| 42 | +- Primitive names are `string`, `boolean`, `integer`, `float`, `array`, and `hash`. |
| 43 | +- Nested container types must follow the documented `nested` structure exactly. |
| 44 | + |
| 45 | +## Tests And Examples |
| 46 | +- Put validation cases in `[[asserts]]`. |
| 47 | +- Each assert must provide `arguments` in `input_signature` order and an `expected` value. |
| 48 | +- Optional assert `comment` values should be short and in English. |
| 49 | +- Cover edge cases, extreme values, and algorithmic corner cases. |
| 50 | +- Prefer realistic and varied test data over repetitive cases. |
| 51 | +- Recommended coverage is about 25-30 asserts per task. |
| 52 | +- All string data in asserts should be English. |
| 53 | + |
| 54 | +## Difficulty And Timing |
| 55 | +- `elementary`: target a 1-2 line solution. |
| 56 | +- `easy`: target a 2-6 line solution. |
| 57 | +- `medium`: target a 7-11 line solution. |
| 58 | +- `hard`: target a 12+ line solution. |
| 59 | +- Set `time_to_solve_sec` consistently with the project guidance documented in `ai/task_structure.md`. |
| 60 | + |
| 61 | +## Style Notes |
| 62 | +- Follow existing Python style in repository scripts: 4-space indentation and conventional import ordering. |
| 63 | +- If formatting TOML, preserve the aligned style used in `ai/task_example.toml` and repository task files. |
| 64 | +- Keep task text concise; avoid extra notes unless they materially clarify the contract. |
| 65 | + |
| 66 | +## Commit And PR Notes |
| 67 | +- Use short, imperative commit messages. |
| 68 | +- In PRs, list created or changed tasks and note the validation commands you ran. |
| 69 | +- Include preview screenshots only for UI changes under `preview/`. |
0 commit comments