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          — первый проход (размеры секций, адреса меток)
kvs_pass2.py          — второй проход (AST + pass1 → CSV с байтами)
kvs_builder.py        — сборщик ELF (CSV + pass1 → исполняемый файл)
kvs_data.py           — общие константы и данные
kvs_build.py          — главный сборочный скрипт (вызывает всё по порядку)
kvs_pass2_encoder_fixsize.py  — кодировщик инструкций фиксированного размера
kvs_pass2_encoder_mutsize.py  — кодировщик инструкций переменного размера + диспетчер
kvs_pass2_encoder.py          — реэкспорт из fixsize + mutsize (совместимость)

Стиль

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