docs: добавлен текст документов для контрибьюетеров и плана развития

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. Конфиденциальность и безопасность
+
+* Участники разработки обязаны соблюдать требования конфиденциальности в отношении деталей реализации, касающихся безопасности.
+* Обсуждение уязвимостей и вопросов безопасности должно проводиться в установленном порядке.
+* Запрещается внесение изменений, которые могут компрометировать безопасность системы или создавать векторы атак.
+
+---
+
+### Примечания
+
+* Настоящий документ может быть дополнен в соответствии с требованиями проекта и стандартами безопасной разработки.
+* Все участники разработки должны быть ознакомлены с требованиями данного документа перед началом работы над проектом.
+

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. Качественные метрики
+
+* Полное соответствие грамматике языка Ъ+
+* Корректная обработка всех допустимых конструкций
+* Четкие и информативные сообщения об ошибках
+
+---
+
+### Примечания
+
+* План развития может корректироваться в зависимости от требований проекта и выявленных в процессе разработки особенностей.
+* Все изменения в плане должны быть согласованы и задокументированы.
+* Приоритеты могут пересматриваться в зависимости от критичности задач и требований безопасности.
+