kvs/AGENTS.md

# AGENTS.md

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

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

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

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

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

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

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

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

```
kvs_lexer.py                 — лексер (исходник → токены)
kvs_parser.py                — парсер (токены → AST)
kvs_pass1.py                 — первый проход: генерация CSV с заглушками для неизвестных меток
kvs_pass2.py                 — второй проход: разрешение меток (замена заглушек на реальные адреса)
kvs_pass3.py                 — третий проход: подстановка констант в команды
kvs_pass4.py                 — четвёртый проход: перекодирование инструкций с подставленными значениями
kvs_builder.py               — сборщик ELF (CSV → исполняемый файл)
kvs_data.py                  — общие константы и данные (регистры, инструкции, функции)
kvs_encoder.py               — фасад кодировщика (реэкспорт из fixsize + mutsize)
kvs_encoder_fixsize.py       — кодировщик инструкций фиксированного размера
kvs_encoder_mutsize.py       — кодировщик инструкций переменного размера + диспетчер
kvs_build.py                 — главный сборочный скрипт (запускает все проходы по порядку)
```

### Стиль

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