kvs/AGENTS.md

# AGENTS.md

## Правила для агентов и участников проекта КВС

КВС — русскоязычный ассемблер x86-64, написанный на Python, генерирующий ELF-файлы.

### Ограничения

1. **Никаких регулярных выражений (`re`).**  
   Разбор строк — только посимвольно, через циклы и сравнения. Это делает код переносимым на другие языки без изменений логики.

2. **Минимум ООП.**
   - Существующие классы (`Pass1`, `Pass2`, `Parser`) **не переписывать** без явной команды. Они работают — не трогай.
   - Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.

3. **Изоляция логики важнее DRY.**  
   Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: кодировщики фиксированного и переменного размера содержат копии функций, чтобы не импортировать их и оставаться полностью самостоятельными.

4. **Русские названия везде, кроме ELF.**  
   - Внутри компилятора — русские имена секций, директив, регистров, инструкций.
   - В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
   - Имена файлов, переменных и функций в коде — **английские** (кроме русифицированных скриптов верхнего уровня).

### Структура проекта

квс_сборка.py — Главный сборочный скрипт (запускает все проходы по порядку) квс_лексер.py — Лексер (исходник → токены) квс_парсер.py — Парсер (токены → AST) квс_проход1.py — Первый проход: генерация CSV с заглушками для неизвестных меток квс_проход2.py — Второй проход: разрешение меток (замена заглушек на реальные адреса) квс_проход3.py — Третий проход: подстановка констант в команды квс_проход4.py — Четвёртый проход: перекодирование инструкций с подставленными значениями квс_проход5.py — Пятый проход: генерация корректных таблиц секций для совместимости с toolchain квс_проход6.py — Шестой проход: постобработка и сортировка CSV для визуального анализа квс_финсбор.py — Сборщик ELF (CSV → исполняемый файл) kvs_data.py — Общие константы и данные (регистры, инструкции, функции) kvs_encoder.py — Фасад кодировщика (реэкспорт из fixsize + mutsize) kvs_encoder_fixsize.py — Кодировщик инструкций фиксированного размера kvs_encoder_mutsize.py — Кодировщик инструкций переменного размера + диспетчер

### Русификация

**Русифицированы (пользовательская часть):**
- Имена скриптов верхнего уровня: `квс_*.py` (кроме `квс_финсбор.py`, `квс_сборка.py`)
- Комментарии и документация в большинстве файлов
- Пользовательский синтаксис: инструкции, регистры, директивы

**Остались на английском:**
- Имена файлов: `kvs_data.py`, `kvs_encoder.py`, `kvs_encoder_fixsize.py`, `kvs_encoder_mutsize.py`
- Внутренние имена переменных, констант и функций внутри этих файлов
- Технические идентификаторы в коде (ключи словарей, имена функций)

### Стиль

- Комментарии и документация — на русском (в русифицированных файлах).
- Имена функций — `snake_case`, осмысленные.
- Размеры инструкций — явные числа, никаких `suffix`-трюков.
- Каждая директива резервирования — отдельная ветка `if`, а не словарь.
- Для файлов, оставшихся на английском (`kvs_*.py`), комментарии допустимы на русском или английском — по усмотрению автора.

### Важно

- `kvs_build.py` переименован в `квс_сборка.py` — используйте актуальное имя.
- `kvs_builder.py` переименован в `квс_финсбор.py`.
- Все проходы (`kvs_pass*.py`) переименованы в `квс_проход*.py`.
- Кодировщики и `kvs_data.py` **не переименованы** — их имена остались на английском.