From e7d18e6731e163e450fff052314ec556f5414599 Mon Sep 17 00:00:00 2001 From: ShishkaDanil <70168790+ShishkaDanil@users.noreply.github.com> Date: Sat, 3 Jan 2026 20:16:15 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=20=D1=82=D0=B5=D0=BA=D1=81=D1=82=20=D0=B4=D0=BE?= =?UTF-8?q?=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=BE=D0=B2=20=D0=B4=D0=BB?= =?UTF-8?q?=D1=8F=20=D0=BA=D0=BE=D0=BD=D1=82=D1=80=D0=B8=D0=B1=D1=8C=D1=8E?= =?UTF-8?q?=D0=B5=D1=82=D0=B5=D1=80=D0=BE=D0=B2=20=D0=B8=20=D0=BF=D0=BB?= =?UTF-8?q?=D0=B0=D0=BD=D0=B0=20=D1=80=D0=B0=D0=B7=D0=B2=D0=B8=D1=82=D0=B8?= =?UTF-8?q?=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/CONTRIBUTORS.md | 110 +++++++++++++++++++++++ docs/ROADMAP.md | 206 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 316 insertions(+) create mode 100644 docs/CONTRIBUTORS.md create mode 100644 docs/ROADMAP.md diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md new file mode 100644 index 0000000..86b2479 --- /dev/null +++ b/docs/CONTRIBUTORS.md @@ -0,0 +1,110 @@ +# Участники разработки + +## Правовые аспекты и требования к контрибуторам + +Настоящий документ устанавливает требования и процедуры для участников разработки программного изделия (ПИ) «Ъ» (компонент «Токенизатор») в рамках Проекта «Твердь». + +--- + +### 1. Общие положения + +Разработка ПИ ведется в соответствии с требованиями к безопасной разработке (SDL) и направлена на создание детерминированного системного программного обеспечения, предназначенного для сертификации на отсутствие недекларированных возможностей (НДВ). + +### 2. Требования к участникам разработки + +#### 2.1. Квалификационные требования + +Участники разработки должны обладать: + +* **Технической компетентностью:** Знание языка программирования Rust, понимание принципов компиляторостроения, лексического анализа и обработки формальных грамматик. +* **Безопасностью разработки:** Понимание принципов безопасной разработки программного обеспечения, знание методов защиты от внедрения уязвимостей. +* **Специализацией:** Опыт работы с системами, требующими сертификации, понимание специфики разработки для архитектур семейства «Эльбрус» и x86. + +#### 2.2. Обязательства участников + +* Соблюдение принципов безопасной разработки (SDL) на всех этапах жизненного цикла программного обеспечения. +* Обеспечение прослеживаемости всех изменений кода и документации. +* Строгое следование установленным стандартам кодирования и архитектурным решениям проекта. +* Гарантирование отсутствия недекларированных возможностей в реализуемом коде. + +### 3. Процедура внесения изменений + +#### 3.1. Подготовка изменений + +* Все изменения должны быть задокументированы с указанием мотивации и области применения. +* Изменения должны сопровождаться соответствующими тестами, обеспечивающими верификацию функциональности. +* Код должен соответствовать требованиям `no_std` окружения и не использовать внешние динамические библиотеки. + +#### 3.2. Процесс ревью + +* Все изменения проходят обязательное ревью кода с фокусом на безопасность и соответствие требованиям проекта. +* Особое внимание уделяется проверке отсутствия потенциальных векторов атак и скрытых возможностей. +* Изменения, затрагивающие критичные компоненты (токенизатор, обработка UTF-8, грамматика), требуют расширенного ревью. + +#### 3.3. Требования к коммитам + +* Коммиты должны содержать четкое описание внесенных изменений. +* Ссылки на соответствующие задачи и требования технического задания. +* Информация о влиянии изменений на безопасность и детерминизм системы. + +### 4. Области ответственности + +#### 4.1. Модули проекта + +| Модуль | Область ответственности | Критичность | +| :--- | :--- | :--- | +| `tokenizer.rs` | Основной лексический анализатор | Высокая | +| `token.rs` | Определения типов токенов | Высокая | +| `grammar.rs` | Правила и константы грамматики | Высокая | +| `dfa.rs` | Состояния детерминированного конечного автомата | Высокая | +| `utf8.rs` | Обработка UTF-8 последовательностей | Высокая | +| `position.rs` | Отслеживание позиций токенов | Средняя | +| `error.rs` | Обработка ошибок | Средняя | +| `comment.rs` | Обработка комментариев | Низкая | + +#### 4.2. Тестирование + +* Все новые функции должны сопровождаться соответствующими тестами. +* Особое внимание уделяется тестам для кириллических идентификаторов и обработки UTF-8. +* Интеграционные тесты должны покрывать критические сценарии использования. + +### 5. Контроль качества кода + +#### 5.1. Статический анализ + +* Код должен проходить статический анализ без ошибок и предупреждений. +* Использование механизмов строгой типизации языка Rust для обеспечения безопасности на этапе компиляции. +* Соблюдение принципов `no_std` разработки. + +#### 5.2. Проверка безопасности + +* Анализ на наличие потенциальных уязвимостей безопасности. +* Проверка отсутствия недекларированных возможностей. +* Верификация детерминизма реализуемых алгоритмов. + +### 6. Документирование + +#### 6.1. Требования к документации + +* Все публичные функции и структуры должны содержать документацию в формате Rust doc. +* Изменения в грамматике языка должны отражаться в файле `docs/grammar.md`. +* Критические архитектурные решения должны документироваться отдельно. + +#### 6.2. Обновление документации + +* Документация должна обновляться синхронно с изменениями кода. +* Изменения в API должны быть задокументированы с указанием причин и миграционных путей. + +### 7. Конфиденциальность и безопасность + +* Участники разработки обязаны соблюдать требования конфиденциальности в отношении деталей реализации, касающихся безопасности. +* Обсуждение уязвимостей и вопросов безопасности должно проводиться в установленном порядке. +* Запрещается внесение изменений, которые могут компрометировать безопасность системы или создавать векторы атак. + +--- + +### Примечания + +* Настоящий документ может быть дополнен в соответствии с требованиями проекта и стандартами безопасной разработки. +* Все участники разработки должны быть ознакомлены с требованиями данного документа перед началом работы над проектом. + diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..97b9a90 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,206 @@ +# План развития проекта (Roadmap) + +Настоящий документ определяет направления развития программного изделия (ПИ) «Ъ» (компонент «Токенизатор») в рамках Проекта «Твердь». + +--- + +### 1. Текущая стадия разработки + +Проект находится на стадии разработки базовой архитектуры и структуры токенизатора. Реализованы: + +* Структура проекта и модульная организация кода +* Определения типов токенов и грамматики языка +* Заглушки основных компонентов для последующей реализации +* Формальное описание грамматики языка Ъ+ в форме EBNF + +--- + +### 2. Краткосрочные цели (Этап 1: Лексический анализ) + +#### 2.1. Разработка фронтенд-части + +**Срок:** Текущий этап разработки + +**Задачи:** + +- [ ] Реализация модуля синтаксического разбора UTF-8 в режиме `no_std` + - Полная реализация функции `decode_utf8` в модуле `utf8.rs` + - Реализация итератора `Utf8Chars` для последовательного декодирования + - Тестирование на различных UTF-8 последовательностях (включая кириллицу) + +- [ ] Реализация обработки комментариев + - Полная реализация модуля `comment.rs` с поддержкой рекурсивной вложенности + - Обработка парных ограничителей `<[` и `]>` + - Тестирование вложенных комментариев различных уровней + +- [ ] Реализация детерминированного конечного автомата (ДКА) + - Полная реализация переходов между состояниями в модуле `dfa.rs` + - Обработка всех операторов и конструкций языка + - Поддержка различения операторов записи (`<<`) и сдвига (`<<<`) + +- [ ] Реализация основного токенизатора + - Полная реализация модуля `tokenizer.rs` + - Последовательная обработка входного потока данных + - Корректное отслеживание позиций токенов (строка, столбец) + +- [ ] Реализация обработки литералов + - Поддержка десятичных, шестнадцатеричных и двоичных литералов + - Обработка типизированных литералов с кириллическими суффиксами (`б8`, `ц8`, `бр`, `цр`, `в32` и т.д.) + - Поддержка разделителя разрядов (`_`) в числовых литералах + - Обработка вещественных литералов + +- [ ] Разработка тестов + - Интеграционные тесты для полного цикла токенизации + - Тесты для кириллических идентификаторов + - Тесты для латинских идентификаторов + - Тесты для всех операторов языка + - Тесты для вложенных комментариев + - Тесты для отслеживания позиций + +**Критерии завершения:** + +* Токенизатор успешно обрабатывает все конструкции языка Ъ+ согласно грамматике +* Все тесты проходят успешно +* Код соответствует требованиям `no_std` и безопасности +* Документация актуальна и полна + +--- + +### 3. Среднесрочные цели (Этап 2: Промежуточное представление) + +#### 3.1. Промежуточное представление и типизация + +**Срок:** Следующий этап после завершения токенизатора + +**Задачи:** + +- [ ] Проектирование структур данных абстрактного синтаксического дерева (AST) + - Определение узлов для всех конструкций языка + - Поддержка префиксов идентификаторов (`@`, `:`, `?`) + - Представление блоков, условий, циклов, функций + +- [ ] Реализация синтаксического анализатора (парсера) + - Парсинг на основе EBNF грамматики + - Построение AST из потока токенов + - Обработка ошибок парсинга с указанием позиций + +- [ ] Реализация механизмов статического вывода типов + - Вывод типов для констант и литералов + - Проверка типов для выражений + - Валидация типизированных литералов + +- [ ] Разработка системы ошибок + - Расширение модуля `error.rs` для синтаксических ошибок + - Детальные сообщения об ошибках с позициями + - Классификация ошибок по типам + +**Критерии завершения:** + +* Парсер успешно строит AST для всех корректных программ +* Вывод типов работает для всех допустимых конструкций +* Ошибки парсинга четко идентифицируются и документируются + +--- + +### 4. Долгосрочные цели (Этап 3: Генерация кода) + +#### 4.1. Генерация целевого кода + +**Срок:** После завершения парсера и типизации + +**Задачи:** + +- [ ] Реализация модуля генерации LLVM IR + - Генерация промежуточного представления для высокопроизводительных систем + - Поддержка архитектур x86 и ARM + - Оптимизации для конвейерного программирования (`|>`) + +- [ ] Разработка бэкенда для архитектуры «Эльбрус» + - Интеграция с компилятором LCC + - Использование промежуточного представления + - Поддержка предикатного исполнения (оператор `?`) + +- [ ] Обеспечение отладочной информации + - Генерация отладочных символов в формате DWARF + - Сквозная передача позиций из исходного кода в машинный код + - Поддержка отладки для обоих бэкендов + +- [ ] Оптимизации компилятора + - Оптимизация конвейерных операций + - Оптимизация предикатного исполнения для «Эльбрус» + - Статическая оптимизация выражений + +**Критерии завершения:** + +* Компилятор генерирует корректный код для обеих целевых архитектур +* Отладочная информация корректно передается через весь процесс компиляции +* Производительность сгенерированного кода соответствует требованиям + +--- + +### 5. Дополнительные направления развития + +#### 5.1. Расширение функциональности + +* Поддержка дополнительных оптимизаций для конвейерного программирования +* Расширенные возможности статического анализа +* Интеграция с инструментами статического анализа безопасности + +#### 5.2. Улучшение инструментария + +* Разработка инструментов для разработчиков (форматировщик кода, линтер) +* Интеграция с системами непрерывной интеграции (CI/CD) +* Автоматизация тестирования и верификации + +#### 5.3. Документация и обучение + +* Расширенная документация для разработчиков +* Руководства по использованию языка Ъ+ +* Примеры и учебные материалы + +--- + +### 6. Приоритеты и ограничения + +#### 6.1. Критические требования + +* **Безопасность:** Все изменения должны сохранять соответствие требованиям безопасной разработки +* **Детерминизм:** Обеспечение детерминированного поведения на всех этапах компиляции +* **Сертификация:** Поддержание возможности сертификации на отсутствие НДВ + +#### 6.2. Технические ограничения + +* Использование только `no_std` окружения +* Запрет на внешние динамические библиотеки +* Поддержка архитектур «Эльбрус» и x86 + +#### 6.3. Приоритеты разработки + +1. **Высокий приоритет:** Завершение токенизатора и базового парсера +2. **Средний приоритет:** Реализация типизации и базовой генерации кода +3. **Низкий приоритет:** Оптимизации и дополнительные инструменты + +--- + +### 7. Метрики успеха + +#### 7.1. Технические метрики + +* Покрытие тестами: не менее 90% для критичных модулей +* Отсутствие предупреждений статического анализатора +* Соответствие требованиям `no_std` для всех модулей + +#### 7.2. Качественные метрики + +* Полное соответствие грамматике языка Ъ+ +* Корректная обработка всех допустимых конструкций +* Четкие и информативные сообщения об ошибках + +--- + +### Примечания + +* План развития может корректироваться в зависимости от требований проекта и выявленных в процессе разработки особенностей. +* Все изменения в плане должны быть согласованы и задокументированы. +* Приоритеты могут пересматриваться в зависимости от критичности задач и требований безопасности. +