administrator/kvs
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Обновить

Browse source
This commit is contained in:
mzhoot 2026-06-20 09:27:22 +03:00
parent 02c74f35c9
commit fa7511a36f
1 changed files with 41 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
AGENTS.md
View file

@ -1,4 +1,4 @@
```markdown
# AGENTS.md # AGENTS.md
## Правила для агентов и участников проекта КВС ## Правила для агентов и участников проекта КВС
@ -15,31 +15,56 @@
- Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные. - Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.
3. **Изоляция логики важнее DRY.** 3. **Изоляция логики важнее DRY.**
Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: `kvs_pass2_encoder_mutsize.py` содержит копии функций из `kvs_pass2_encoder_fixsize.py`, чтобы не импортировать их и оставаться полностью самостоятельным. Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: кодировщики фиксированного и переменного размера содержат копии функций, чтобы не импортировать их и оставаться полностью самостоятельными.
4. **Русские названия везде, кроме ELF.** 4. **Русские названия везде, кроме ELF.**
Внутри компилятора — русские имена секций, директив, регистров. В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`). - Внутри компилятора — русские имена секций, директив, регистров, инструкций.
- В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
- Имена файлов, переменных и функций в коде — **английские** (кроме русифицированных скриптов верхнего уровня).
### Структура проекта ### Структура проекта
``` ```
kvs_lexer.py — лексер (исходник → токены) квс_сборка.py — Главный сборочный скрипт (запускает все проходы по порядку)
kvs_parser.py — парсер (токены → AST) квс_лексер.py — Лексер (исходник → токены)
kvs_pass1.py — первый проход: генерация CSV с заглушками для неизвестных меток квс_парсер.py — Парсер (токены → AST)
kvs_pass2.py — второй проход: разрешение меток (замена заглушек на реальные адреса) квс_проход1.py — Первый проход: генерация CSV с заглушками для неизвестных меток
kvs_pass3.py — третий проход: подстановка констант в команды квс_проход2.py — Второй проход: разрешение меток (замена заглушек на реальные адреса)
kvs_pass4.py — четвёртый проход: перекодирование инструкций с подставленными значениями квс_проход3.py — Третий проход: подстановка констант в команды
kvs_builder.py — сборщик ELF (CSV → исполняемый файл) квс_проход4.py — Четвёртый проход: перекодирование инструкций с подставленными значениями
kvs_data.py — общие константы и данные (регистры, инструкции, функции) квс_проход5.py — Пятый проход: генерация корректных таблиц секций для совместимости с toolchain
kvs_encoder.py — фасад кодировщика (реэкспорт из fixsize + mutsize) квс_проход6.py — Шестой проход: постобработка и сортировка CSV для визуального анализа
kvs_encoder_fixsize.py — кодировщик инструкций фиксированного размера квс_финсбор.py — Сборщик ELF (CSV → исполняемый файл)
kvs_encoder_mutsize.py — кодировщик инструкций переменного размера + диспетчер kvs_data.py — Общие константы и данные (регистры, инструкции, функции)
kvs_build.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`, осмысленные. - Имена функций — `snake_case`, осмысленные.
- Размеры инструкций — явные числа, никаких `suffix`-трюков. - Размеры инструкций — явные числа, никаких `suffix`-трюков.
- Каждая директива резервирования — отдельная ветка `if`, а не словарь. - Каждая директива резервирования — отдельная ветка `if`, а не словарь.
- Для файлов, оставшихся на английском (`kvs_*.py`), комментарии допустимы на русском или английском — по усмотрению автора.
### Важно
- `kvs_build.py` переименован в `квс_сборка.py` — используйте актуальное имя.
- `kvs_builder.py` переименован в `квс_финсбор.py`.
- Все проходы (`kvs_pass*.py`) переименованы в `квс_проход*.py`.
- Кодировщики и `kvs_data.py` **не переименованы** — их имена остались на английском.
```