commit 1be96f7d4b3d5d333ff3179a4a9eb56fe073adbf Author: zosimovaa Date: Sat Oct 10 21:17:02 2026 +0300 init commit diff --git a/openspec/changes/archive/.gitkeep b/openspec/changes/archive/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/openspec/config.yaml b/openspec/config.yaml new file mode 100644 index 0000000..95d1b50 --- /dev/null +++ b/openspec/config.yaml @@ -0,0 +1,43 @@ +schema: function-driven + +context: | + Актуальные спецификации проекта находятся в openspec/specs/. + Старые документы spec/specs/ устарели и не подтверждают текущее поведение. + Capability имеет отдельную бизнес-функцию или понятный результат и живёт + в иерархии доменов, например orders/snapshot-sync. + Requirement описывает одну завершённую техническую функцию. + Формат требований определяется локальной схемой function-driven. + Включай только сведения, влияющие на наблюдаемое поведение, устойчивый + контракт или обязательное техническое ограничение; не добавляй повторы и + пояснительный текст без такого влияния. + Пиши по-русски весь пояснительный текст каждого изменения OpenSpec: + в proposal.md, design.md, specs/**/*.md и tasks.md. Сохраняй обязательные + заголовки и синтаксис OpenSpec, имена API, SQL-полей, кодов, файлов, + инструментов, команд и идентификаторы без перевода. + +rules: + specs: + - Пиши пояснительный текст спецификаций по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. + - Каждый Requirement содержит ровно один Use case. Автор выбирает полный или сокращенный формат независимо от типа FR и предмета описания. + - Обычный FR без метки описывает логику, правила или последовательность шагов; специальные типы помечай в заголовке FR как [DB], [API] или [UI]. + - FR [DB] с таблицей БД оформляй по openspec/schemas/function-driven/patterns/database-table.md. + - Каждый HTTP endpoint описывай отдельным Requirement с полным Use case; сложные шаги выноси в FR и связывай со сценарием. + - Контракт endpoint помещай после FR в завершающий CONTRACT с подразделами Request и Response; не создавай для request/response отдельные FR. + - Таблицы тела запроса и ответа в CONTRACT оформляй по openspec/schemas/function-driven/patterns/message-contract.md; для каждого поля Response указывай источник или правило формирования значения. + - Сериализуемые контракты сообщений и технических логов описывай в FR [API] по openspec/schemas/function-driven/patterns/message-contract.md; один FR описывает одно направление. + - Детали находятся в локально нумерованных FR за пределами Scenario; шаги ссылаются на FR. + - Коды завершения сами передают смысл результата и связаны с FR о текстах и дальнейшем поведении. + - Для master spec используй templates/main-spec.md выбранной схемы; для delta используй templates/spec.md. + - Проверяй формат командой python3 openspec/schemas/function-driven/validate_format.py . + proposal: + - Сохраняй полные иерархические пути capabilities. + - Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. + design: + - Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований. + - Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. + tasks: + - Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. + - Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. + - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в pyproject.toml. Выполняй её после реализации и проверок; один change повышает версию ровно один раз. + - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и любых изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. + - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. diff --git a/openspec/schemas/function-driven/README.md b/openspec/schemas/function-driven/README.md new file mode 100644 index 0000000..f33b9fd --- /dev/null +++ b/openspec/schemas/function-driven/README.md @@ -0,0 +1,166 @@ +# Схема function-driven + +Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на +`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`. +Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes +с явно указанной `schema: spec-driven` продолжают использовать свою схему; +их миграция не является частью изменения формата master spec. + +## Уровни спецификации + +- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. +- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. +- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. +- FR — подробные правила и контракты сообщений за пределами Scenario; + контракт HTTP endpoint размещается в завершающем CONTRACT. + +В спецификацию включаются только сведения, влияющие на наблюдаемое поведение, +устойчивый контракт или обязательное техническое ограничение. Повторы и +пояснения без такого влияния удаляются. + +Для каждой capability зарегистрируй стабильный уникальный префикс в +[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь +capability: например, `configuration/application-settings` получает `CFG.AS`. +ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability. +В сочетании с уникальным префиксом это даёт уникальный ID в проекте. +ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`, +`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. +В новых и изменяемых Requirements используй составные ID. Неизменённые legacy +specs могут сохранять прежние ID до отдельного рефакторинга. + +## Формат Requirement + +Markdown-рендерер автоматически создаёт якоря из заголовков Requirement и FR. +Не добавляй HTML ``. Ссылки используй на slug заголовка; при +переименовании заголовка обновляй все ссылки на него. Семантический ID Requirement +остаётся в строке `**ID:**`; полный ID FR входит в заголовок и подпись ссылки. + +```text +### Requirement: Завершённая техническая функция +**ID:** AREA.CAP-01 +Система SHALL ... + +#### Scenario: Завершённый процесс +##### Участники +##### Предусловия +##### Основной поток +##### Альтернативы и ошибки +##### Результат +##### Коды завершения + +#### Функциональные требования +##### AREA.CAP-01.FR-01: Правило обработки +##### AREA.CAP-01.FR-02 [DB]: Структура таблицы +##### AREA.CAP-01.FR-03 [API]: Контракт сообщения +##### AREA.CAP-01.FR-04 [UI]: Требования к интерфейсу +``` + +В Scenario «Назначение» опционально и добавляется только при наличии сведений, +которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток — +нумерованные короткие шаги «Что делаем — как делаем», например: +«Получаем клиентов — вызываем GET /cp/users по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)». + +## Форматы Use case + +Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания. +Для каждого HTTP endpoint используй отдельный Requirement и полный Use case. + +```text +#### Scenario: Сокращенный use case: описание функции +##### Основной поток +1. Описываем первый аспект по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). +2. Уточняем второй аспект по [AREA.CAP-01.FR-02](#areacap-01fr-02-дополнительное-правило). +``` + +Сокращенный Use case не содержит участников, предусловий, альтернатив и ошибок, +результата и кодов завершения. + +Шаг, альтернатива или абзац Scenario содержит не более 240 знаков текста +без URL Markdown-ссылок. Сценарий не содержит Gherkin, блоков кода, таблиц +полей и подробных алгоритмов. Технические детали, тексты сообщений и логика находятся в FR; контракт HTTP +endpoint — в завершающем CONTRACT. Единственная таблица +Scenario — `Код | Смысл | Связанные FR`. + +Ссылки ведут на автоматически сгенерированные slugs заголовков FR, например +`[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-контракт-api-структура-бд-форма-ui)`. +Полный ID используется внутри Requirement и при ссылке на другую capability. +Адрес фрагмента соответствует заголовку FR назначения. Каждый код ссылается +хотя бы на один FR, в котором он описан. Смысл кода понятен без `stage` или текста исключения. +FR задаёт тексты, дальнейшие действия и связи с другими требованиями. +Одинаковая обработка нескольких диагностических причин допускает один код. +Промежуточные события trace не включаются в коды завершения. + +## Форматы FR + +Обычный FR не имеет метки типа и описывает логику, правила или последовательность шагов. Специальный формат указывается после ID в заголовке: `[DB]`, `[API]` или `[UI]`. Метка не входит в ID FR и не меняет ссылки на него. + +- [DB] описывает структуру базы данных по паттерну таблицы БД. +- FR [API] описывает контракт асинхронного сообщения или сериализуемой записи, включая технический лог. HTTP endpoint описывается в CONTRACT. +- [UI] зарезервирован для требований к интерфейсу; детальный паттерн будет добавлен отдельно. + +## HTTP-контракт в Requirement + +Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный +Use case; сложные правила шагов выносятся в FR. После всех FR, в конце +Requirement, размещается раздел CONTRACT с подразделами Request и Response. +В Request указываются один HTTP-метод и путь, тело и query-параметры. В +Response указываются HTTP status и таблица сериализуемого ответа. Не создавай +отдельные FR для частей HTTP-контракта. + +Таблица тела Request содержит пять колонок по +patterns/message-contract.md. Таблица Response содержит те же колонки и +последнюю колонку «Формирование значения», описывающую источник или правило +формирования каждого поля. Для отсутствующего тела запроса укажи это явно и не +добавляй пустую таблицу. + +## Паттерны FR + +FR, описывающий таблицу БД, оформляется по +[`patterns/database-table.md`](patterns/database-table.md): таблица содержит поля, +типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL. +Контракт сообщения или технического лога в FR оформляется по +[`patterns/message-contract.md`](patterns/message-contract.md): таблица задаёт направление, +поля, wire-типы, обязательность и ограничения. Один FR описывает одно направление. +В response-таблице также указывается источник или правило формирования каждого поля. +Другие паттерны добавляются отдельными файлами по мере появления потребности. + +## Шаблоны и delta specs + +- `templates/main-spec.md` — постоянная спецификация capability. +- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`. +- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow. + +ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration, +RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный +Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и +заголовки FR master spec, на которые ведут автоматически созданные slugs. Для +ссылок на неизменённые требования при проверке передай `--base `. + +Если смысловые коды или сообщения ещё не выдаются приложением, это явно +фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. +Форматирование спецификации само по себе не реализует этот контракт в приложении. + +## Проверки + +```sh +openspec schema validate function-driven +openspec validate orders/snapshot-sync --type spec --strict --no-interactive +python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md +``` + +Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`. +Можно передать несколько файлов или каталогов; проверка не изменяет их. + +Стандартный `openspec schema validate` проверяет workflow, зависимости и наличие +шаблонов. `openspec validate` проверяет стандартную структуру спецификации. +Отдельная `validate_format.py --require-qualified-ids ` проверяет +составные ID новых и изменённых Requirements; без флага валидатор также принимает +неизменённые legacy specs. Проверка охватывает один Scenario, +обычную структуру use case или формат сокращенного use case, ссылки шагов на FR, +форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков +в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, +таблицу кодов и её связь с FR. +Семантическую завершённость функции и понятность кода оценивает автор/reviewer. +Схема требует от автора запускать обе проверки; автоматического hook в CLI нет. + +Механизм схем и шаблонов: [официальная документация OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md). diff --git a/openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc b/openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc new file mode 100644 index 0000000..90b5f27 Binary files /dev/null and b/openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc differ diff --git a/openspec/schemas/function-driven/capability-codes.md b/openspec/schemas/function-driven/capability-codes.md new file mode 100644 index 0000000..14c0c2f --- /dev/null +++ b/openspec/schemas/function-driven/capability-codes.md @@ -0,0 +1,19 @@ +# Коды capabilities + +Каждому пути capability соответствует один стабильный короткий префикс. Полные +префиксы должны быть уникальны в проекте; при переименовании capability код не +переиспользуется для другой capability. + +| Путь capability | Префикс Requirement | +| --- | --- | +| `configuration/application-settings` | `CFG.AS` | +| `configuration/application-config-file` | `CFG.ACF` | +| `health/aggregation` | `HL.AG` | +| `api/http/control-api` | `API.HTTP.CA` | +| `runtime/application-lifecycle` | `RT.AL` | +| `runtime/application-identity` | `RT.AI` | +| `runtime/worker` | `RT.WK` | +| `workflow/orchestration` | `WF.OR` | +| `observability/business-tracing` | `OBS.BT` | +| `observability/technical-logging` | `OBS.TL` | + diff --git a/openspec/schemas/function-driven/patterns/database-table.md b/openspec/schemas/function-driven/patterns/database-table.md new file mode 100644 index 0000000..cb0d5a9 --- /dev/null +++ b/openspec/schemas/function-driven/patterns/database-table.md @@ -0,0 +1,37 @@ +# Паттерн FR: таблица базы данных + +Применяй паттерн, когда FR описывает структуру таблицы БД, а не SQL-команду её создания. + +## Формат + +Используй заголовок вида `.FR-NN [DB]: Таблица хранения <имя>` и назови таблицу и схему приложения перед таблицей полей. + +Таблицу полей оформляй с колонками в этом порядке: + +| Поле | Тип | Ограничения и значение по умолчанию | Назначение | +| --- | --- | --- | --- | +| `field_name` | `TYPE` | NULL или NOT NULL; при наличии DEFAULT укажи значение | Короткое назначение поля | + +Одна строка описывает одно поле. Указывай точный тип, nullability, default и ограничения, которые влияют на хранение или чтение данных. Называй назначение каждого поля. Не используй `—` или пустые ячейки вместо явного `NULL`, `NOT NULL` или отсутствия default. + +После таблицы перечисляй только ограничения таблицы, которых нет в строках: первичный и внешние ключи, уникальность, индексы, порядок выборки и владение данными. Не дублируй значения по умолчанию или назначение полей. Пиши DDL только если конкретный контракт невозможно выразить этой таблицей. + +## Пример + +```markdown +##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings + +Таблица `settings` создаётся в схеме приложения и содержит: + +| Поле | Тип | Ограничения и значение по умолчанию | Назначение | +| --- | --- | --- | --- | +| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | +| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | +| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | +| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | +| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | +| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении | +| `description` | `TEXT` | NULL | Пояснение к настройке | + +Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. +``` diff --git a/openspec/schemas/function-driven/patterns/message-contract.md b/openspec/schemas/function-driven/patterns/message-contract.md new file mode 100644 index 0000000..edb7a05 --- /dev/null +++ b/openspec/schemas/function-driven/patterns/message-contract.md @@ -0,0 +1,57 @@ +# Паттерн сериализуемого контракта + +Используй паттерн для полей сериализуемых request/response-контрактов. +Для HTTP endpoint таблицы находятся в разделах Request и Response блока +CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся +в типизированном FR [API]. + +## HTTP endpoint + +Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные +правила обработки указываются в FR, а контракт помещается в самом конце +Requirement: + +```markdown +#### CONTRACT + +##### Request + +Метод: `POST`; путь: `/resource`. Для endpoint без тела явно укажи отсутствие тела. + +##### Response + +HTTP status: `200` при успешном выполнении. + +| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения | +| --- | --- | --- | --- | --- | --- | +| `field_name` | `JSON type` | Обязательное | Формат и допустимые значения | Короткое назначение поля | Источник или правило вычисления значения | +``` + +Тело запроса при наличии описывай таблицей с пятью колонками: + +| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | +| --- | --- | --- | --- | --- | +| `field_name` | `JSON type` | Обязательное или опциональное | Формат, допустимые значения, nullable/default или явное отсутствие дополнительных ограничений и значений по умолчанию | Короткое назначение поля | + +Для response используй эти же колонки и добавь последней «Формирование +значения», чтобы для каждого поля указать источник значения или правило его +вычисления. + +Одна строка описывает одно поле. Указывай JSON-тип, а не тип языка реализации. +Для вложенных полей используй путь из имён полей; для массивов указывай тип +элемента. Обязательность задаёт наличие поля, а ограничения — nullability, +формат, допустимые значения и default. Условие присутствия опционального поля +укажи в ограничениях. Если дополнительных ограничений или значения по +умолчанию нет, укажи это явно. Не оставляй ячейки пустыми и не используй тире. + +Не создавай отдельные FR для HTTP request/response-контрактов. Не добавляй +таблицу для отсутствующего тела запроса. + +## Сообщение или технический лог в FR [API] + +Заголовок FR: `.FR-NN [API]: Контракт сообщения <имя>` либо +Контракт запроса / Контракт ответа. Сразу после заголовка укажи +`Тип контракта: request` для отправляемых данных или +`Тип контракта: response` для возвращаемых данных. Для отправляемого сообщения +используй request. Один FR описывает одно направление и содержит одну таблицу +по формату выше. diff --git a/openspec/schemas/function-driven/schema.yaml b/openspec/schemas/function-driven/schema.yaml new file mode 100644 index 0000000..b5c88d5 --- /dev/null +++ b/openspec/schemas/function-driven/schema.yaml @@ -0,0 +1,281 @@ +name: function-driven +version: 1 +description: Иерархические capabilities, завершённые технические функции и краткие use cases с локальными FR +artifacts: + - id: proposal + generates: proposal.md + description: Initial proposal document outlining the change + template: proposal.md + instruction: | + Пиши весь пояснительный текст артефакта изменения по-русски. Сохраняй + обязательные заголовки OpenSpec и технические идентификаторы, названия + API, файлов, инструментов, команд и коды без перевода. + + Create the proposal document that establishes WHY this change is needed. + + Sections: + - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now? + - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**. + - **Capabilities**: Identify which specs will be created or modified: + - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization. + - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes. + - **Impact**: Affected code, APIs, dependencies, or systems. + + IMPORTANT: The Capabilities section is critical. It creates the contract between + proposal and specs phases. Research existing specs before filling this in: + run `openspec list --specs` for the project's capability inventory, then + `openspec show "" --type spec --json --no-scenarios` for any that + look related - that returns a capability's purpose and requirement texts + without pulling whole spec files into context. Append `--store ""` to + both commands only for a registered standalone store, and keep `--type + spec`: a change and a spec sharing a name is otherwise an ambiguous-item + error. `openspec list` without `--specs` lists in-flight changes, not + specs - it never shows what the project already covers. Reuse an existing + capability's exact path instead of introducing a near-duplicate name. + The filtered read is only an overview. Before deciding what is already + covered or what should change, read each relevant spec in full, including + scenarios, with `openspec show "" --type spec` (same `--store` rule). + Each capability listed here will need a corresponding spec file. + + Every change must either declare at least one capability (new or + modified) or explicitly opt out of specs: `openspec validate` rejects a + change with zero deltas unless the change's `.openspec.yaml` sets + `skip_specs: true`. Use `skip_specs: true` only when no spec-level + behavior changes (pure refactor, tooling, docs) - specs describe + behavior, so if behavior does not change, no spec should change either. + Do not invent a requirement just to satisfy validation. + + Keep it concise (1-2 pages). Focus on the "why" not the "how" - + implementation details belong in design.md. + + This is the foundation - specs, design, and tasks all build on this. + requires: [] + + - id: specs + generates: "specs/**/*.md" + description: Detailed specifications for the change + template: spec.md + instruction: | + Пиши весь пояснительный текст спецификаций по-русски. Сохраняй + обязательные заголовки OpenSpec, идентификаторы, названия API и коды + без перевода. + + Создай спецификации наблюдаемого поведения и устойчивых контрактов. + Правила ниже применяются к master specs и к полным блокам ADDED/MODIFIED + в delta specs. Это пользовательский формат без Gherkin. + + Иерархия и границы: + - Capability имеет отдельную бизнес-функцию или понятный результат. + - Сохраняй полный иерархический путь, например orders/snapshot-sync. + - Один Requirement описывает одну завершённую техническую функцию. + - Не дроби один процесс на Requirements для чтения, валидации и записи. + - Каждый Requirement имеет стабильный ID вида CFG.AS-01 и ровно один Scenario. + - Префикс Requirement уникален для пути capability и регистрируется в + capability-codes.md: configuration/application-settings получает CFG.AS. + Номер Requirement уникален внутри capability, что делает полный ID + уникальным в проекте. Существующие, ещё не рефакторенные Requirements + могут сохранять старый ID. + - Заголовки OpenSpec: ### Requirement: и #### Scenario:. + - Описание Requirement содержит SHALL/MUST и наблюдаемый результат. + - Включай только сведения, меняющие наблюдаемое поведение, устойчивый + контракт или обязательное техническое ограничение. Удаляй повторы, + пояснения и формулировки, которые не меняют поведение и не снимают + неоднозначность контракта. + + Scenario: + - Поддерживаются два формата Use case: полный и сокращенный. Автор + выбирает формат по ситуации, независимо от типа FR и того, что + описывается: runtime-процесс, БД, API, UI или другая часть системы. + - Полный Use case содержит разделы Участники, Предусловия, + Основной поток, Альтернативы и ошибки, Результат, Коды завершения — + в таком порядке. + - Сокращенный Use case содержит только раздел `##### Основной поток`; + каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит + участников, предусловий, альтернатив и ошибок, результата или кодов + завершения и не задаёт отдельные runtime-развилки. + - В обычном сценарии Назначение опционально; добавляй только если оно + сообщает сведения, которых нет в заголовке. Контекст отсутствует. + - Основной поток — нумерованные короткие шаги «Что делаем — как делаем». + - Шаг runtime-сценария может назвать действие, endpoint или способ записи + и сослаться на FR. + - Каждый HTTP endpoint описывай в отдельном Requirement с полным Use case. + Сложные правила шага выноси в FR и связывай со сценарием ссылками. + - Основной поток и альтернативы обычного сценария включают коды + завершения, если они определены для этой функции. + - Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты + сообщений и дальнейшая логика располагаются за пределами Scenario. + - Единственная таблица Scenario — Коды завершения с колонками + Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE. + - Код сам сообщает смысл итога; дополнительный stage или свободный текст + не должен требоваться для понимания кода. События промежуточных шагов + не являются кодами завершения. Не создавай код для каждой диагностики. + - Каждая запись кода ссылается на локальные FR, определяющие дальнейшую + логику, текст или применимые правила результата. + - Каждый шаг, альтернатива и абзац сценария — не более 240 знаков + содержательного текста без адресов Markdown-ссылок. + - Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT. + + Функциональные требования: + - После Scenario, на уровне ####, идёт раздел Функциональные требования. + - Внутри: ##### CFG.AS-01.FR-01: <название>, ##### CFG.AS-01.FR-02 [DB]: <название>, ##### CFG.AS-01.FR-03 [API]: <название> и так далее. + - ID FR содержит ID Requirement и локальный номер: .FR-NN. + Номер начинается с FR-01 в каждом Requirement. + - FR содержит отдельное понятное правило или связанный контракт; не дроби + связную логику на множество атомарных FR. + - Обычный FR без метки описывает логику, правила или последовательность + шагов. Типизированный FR помечай сразу после ID меткой [DB], [API] + или [UI]; метка не входит в ID и не меняет slug ссылки. + - [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает + контракт сообщения или технического лога. Контракт HTTP endpoint + размещается в отдельном разделе CONTRACT. [UI] описывает требования к + UI; детальный паттерн будет добавлен отдельно. + - Для FR [DB] с таблицей БД следуй паттерну + `openspec/schemas/function-driven/patterns/database-table.md`. + - Для сериализуемого контракта сообщения в FR [API] следуй паттерну + `openspec/schemas/function-driven/patterns/message-contract.md`. + - Контракт HTTP endpoint не оформляй отдельными FR. После раздела + Функциональные требования добавляй завершающий раздел CONTRACT с + подразделами Request и Response в таком порядке. В Request указывай + один HTTP-метод и путь; для отсутствующего тела явно отмечай это. + Таблицы тела запроса и ответа оформляй по паттерну message-contract.md. + - В таблице Response раздела CONTRACT укажи для каждого поля источник + значения или правило его формирования в последней колонке. + - В таблице response-контракта FR [API] укажи для каждого поля источник + значения или правило его формирования в колонке «Формирование значения». + - Не добавляй HTML-якоря вида . Markdown генерирует + якоря из заголовков Requirement и FR. + - Ссылайся на FR по полному ID и slug его заголовка, например + [CFG.AS-01.FR-01](#cfgas-01fr-01-правило-обработки). Полный ID + используется и для ссылки внутри Requirement, и для ссылки на другой + Requirement. + - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. + - Сохраняй существующие ID. При изменении FR сохраняй его номер; + новые FR добавляй в конец. Порядок первого документа последовательный. + - Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие + сообщения/действия, если это часть контракта. Параметры сообщений + являются данными, а не скрытым значением кода. + - Если смысловой код спецификации отличается от действующего runtime, + явно опиши соответствие и статус реализации в FR. Не утверждай, + что новый код или текст уже возвращается приложением. + + Работа с OpenSpec: + - Создай specs//spec.md для каждой capability из proposal. + - Master spec использует шаблон templates/main-spec.md этой схемы. + - Delta spec использует templates/spec.md и разделы ## ADDED Requirements, + ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements. + - Для новой capability delta начинается с ## Purpose (50+ знаков). + Для существующей capability Purpose в delta не добавляй. + - MODIFIED содержит полный Requirement: ID, один Scenario и все FR. + Его заголовок должен совпадать с заголовком master spec. + - REMOVED содержит Reason и Migration; RENAMED использует FROM/TO. + Это операции над требованиями, не сценарии технических функций. + - При копировании блоков в delta сохраняй ID Requirements, номера и + заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в + неизменённый Requirement master spec, проверяй delta с --base . + - Не создавай delta для чистого форматирования, tooling или рефакторинга. + Для change без изменения поведения используй skip_specs: true. + - Проверь schema через openspec schema validate function-driven. + - Проверь spec через openspec validate и отдельно через + python3 openspec/schemas/function-driven/validate_format.py + --require-qualified-ids . Для неизменённых legacy specs + этот флаг не нужен. + Стандартный валидатор OpenSpec не проверяет все правила этого формата. + requires: + - proposal + + - id: design + generates: design.md + description: Technical design document with implementation details + template: design.md + instruction: | + Пиши весь пояснительный текст design по-русски. Сохраняй обязательные + заголовки OpenSpec и технические идентификаторы, названия файлов, + инструментов и команд без перевода. + + Create the design document that explains HOW to implement the change. + + When to include design.md (create only if any apply): + - Cross-cutting change (multiple services/modules) or new architectural pattern + - New external dependency or significant data model changes + - Security, performance, or migration complexity + - Ambiguity that benefits from technical decisions before coding + + Sections: + - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why"). + - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries. + - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision. + - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation + - **Migration Plan**: Steps to deploy, rollback strategy (if applicable) + - **Open Questions**: Unknowns that can safely be answered later without + changing the specs, the approach, or the task breakdown. Omit if none. + + Open questions are for genuinely deferrable unknowns, not decisions you + skipped. If a question would change the specs, the chosen approach, or + the task breakdown, resolve it now - ask the user instead of guessing. + + Focus on architecture and approach, not line-by-line implementation. + The proposal covers why and what; design covers how. Reference the + proposal for motivation and, once written, the specs for requirements - + if a section would only restate them, point to them instead. + + Good design docs explain the "why" behind technical decisions. + requires: + - proposal + + - id: tasks + generates: tasks.md + description: Implementation checklist with trackable tasks + template: tasks.md + instruction: | + Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные + идентификаторы, пути файлов, названия API, коды и команды без перевода. + + Create the task list that breaks down the implementation work. + + Before writing tasks, check design.md for Open Questions. If any of them + would change what gets built, resolve them with the user first - do not + bake an unstated assumption into the task list. + + **IMPORTANT: Follow the template below exactly.** The apply phase parses + checkbox format to track progress. A box holding only `x` counts as done, + upper or lower case and with any spacing, so `- [ x]` is done too. Every + other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as + unfinished. A line with no checkbox is not tracked at all. + + Guidelines: + - Group related tasks under ## numbered headings + - Each task MUST be a checkbox: `- [ ] X.Y Task description` + - Tasks should be small enough to complete in one session + - Order tasks by dependency (what must be done first?) + - Each task MUST state how to verify completion (a test, command, + observable behavior, or delivered artifact). Put the verification in + that task's checkbox description. Use a separate verification task only + when it checks broader integration or system behavior that spans + multiple implementation tasks. + + Example: + ``` + # Tasks + + ## 1. Setup + + - [ ] 1.1 Create new module structure and verify expected files are present + - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds + + ## 2. Core Implementation + + - [ ] 2.1 Implement data export function and verify the export test passes + - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters + ``` + + Reference specs for what needs to be built, design for how to build it. + requires: + - specs + - design + +apply: + requires: [ tasks ] + tracks: tasks.md + instruction: | + Read context files, work through pending tasks, mark complete as you go. + Pause if you hit blockers or need clarification. diff --git a/openspec/schemas/function-driven/templates/design.md b/openspec/schemas/function-driven/templates/design.md new file mode 100644 index 0000000..f3225e1 --- /dev/null +++ b/openspec/schemas/function-driven/templates/design.md @@ -0,0 +1,21 @@ +# Design + +## Context + + + +## Goals / Non-Goals + +**Goals:** + + +**Non-Goals:** + + +## Decisions + + + +## Risks / Trade-offs + + diff --git a/openspec/schemas/function-driven/templates/main-spec.md b/openspec/schemas/function-driven/templates/main-spec.md new file mode 100644 index 0000000..7dd2f81 --- /dev/null +++ b/openspec/schemas/function-driven/templates/main-spec.md @@ -0,0 +1,106 @@ +# Capability: <название> + +## Purpose + +<Бизнес-функция capability и понятный результат, не менее 50 знаков.> + + + +## Границы + +- <область ответственности capability>. + +## Requirements + +### Requirement: <название завершённой технической функции> + +**ID:** `AREA.CAP-01` + +Система SHALL <наблюдаемый результат завершённой функции>. + +#### Scenario: <название завершённого процесса> + +##### Участники + +- <участники процесса>. + +##### Предусловия + +- <условия начала процесса>. + +##### Основной поток + +1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт). +2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). + +##### Альтернативы и ошибки + +- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). + +##### Результат + +<Наблюдаемое состояние после завершения>. + +##### Коды завершения + +| Код | Смысл | Связанные FR | +| --- | --- | --- | +| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | +| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | + +#### Функциональные требования + +##### AREA.CAP-01.FR-01: Правило обработки + +<Обычный FR описывает логику, правило или последовательность шагов. Для +специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру +таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт +HTTP endpoint располагай в завершающем разделе CONTRACT.> + +##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение + +| Код | Текст сообщения | Дальнейшее поведение | +| --- | --- | --- | +| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> | +| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> | + +<При необходимости — параметры сообщений, связанные требования и соответствие +действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.> + + + + + + diff --git a/openspec/schemas/function-driven/templates/proposal.md b/openspec/schemas/function-driven/templates/proposal.md new file mode 100644 index 0000000..febb3fc --- /dev/null +++ b/openspec/schemas/function-driven/templates/proposal.md @@ -0,0 +1,29 @@ +# Proposal + +## Why + + + +## What Changes + + + +## Capabilities + +### New Capabilities + +- ``: + +### Modified Capabilities + +- ``: + +## Impact + + diff --git a/openspec/schemas/function-driven/templates/spec.md b/openspec/schemas/function-driven/templates/spec.md new file mode 100644 index 0000000..29d1784 --- /dev/null +++ b/openspec/schemas/function-driven/templates/spec.md @@ -0,0 +1,107 @@ +# Spec Delta + +## Purpose + + + + + +## ADDED Requirements + + + +### Requirement: <название завершённой технической функции> + +**ID:** `AREA.CAP-01` + +Система SHALL <наблюдаемый результат завершённой функции>. + +#### Scenario: <название завершённого процесса> + +##### Участники + +- <участники процесса>. + +##### Предусловия + +- <условия начала процесса>. + +##### Основной поток + +1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт). +2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). + +##### Альтернативы и ошибки + +- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). + +##### Результат + +<Наблюдаемое состояние после завершения>. + +##### Коды завершения + +| Код | Смысл | Связанные FR | +| --- | --- | --- | +| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | +| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | + +#### Функциональные требования + +##### AREA.CAP-01.FR-01: Правило обработки + +<Обычный FR описывает логику, правило или последовательность шагов. Для +специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру +таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт +HTTP endpoint располагай в завершающем разделе CONTRACT.> + +##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение + +| Код | Текст сообщения | Дальнейшее поведение | +| --- | --- | --- | +| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> | +| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> | + +<При необходимости — параметры сообщений, связанные требования и соответствие +действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.> + + + + + + diff --git a/openspec/schemas/function-driven/templates/tasks.md b/openspec/schemas/function-driven/templates/tasks.md new file mode 100644 index 0000000..427379c --- /dev/null +++ b/openspec/schemas/function-driven/templates/tasks.md @@ -0,0 +1,15 @@ +# Tasks + +## 1. + +- [ ] 1.1 +- [ ] 1.2 + +## 2. + +- [ ] 2.1 +- [ ] 2.2 + +## 3. Обновление версии + +- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`. diff --git a/openspec/schemas/function-driven/validate_format.py b/openspec/schemas/function-driven/validate_format.py new file mode 100644 index 0000000..04115da --- /dev/null +++ b/openspec/schemas/function-driven/validate_format.py @@ -0,0 +1,494 @@ +"""Read-only checks of function-driven Markdown conventions; no dependencies.""" + +from __future__ import annotations + +import argparse +import re +import unicodedata +from pathlib import Path +from urllib.parse import unquote + + +SECTIONS = ( + "Участники", "Предусловия", "Основной поток", "Альтернативы и ошибки", + "Результат", "Коды завершения", +) +CODE = re.compile(r"\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b") +LINK = re.compile(r"\[([^\]]+)\]\(#([^)]+)\)") +HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$") +LEGACY_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+" +QUALIFIED_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:\.[A-Z][A-Z0-9]*)+-\d{2,}" +REQUIREMENT_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}|{LEGACY_REQUIREMENT_ID_PATTERN})" +REQUIREMENT_ID = re.compile(rf"^\*\*ID:\*\* `({REQUIREMENT_ID_PATTERN})`$", re.MULTILINE) +FR_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}\.)?FR-\d{{2,}}" +FR_ID = re.compile(rf"^(?:(?P{QUALIFIED_REQUIREMENT_ID_PATTERN})\.)?(?PFR-\d{{2,}})$") +FR_HEADING = re.compile(rf"^##### ({FR_ID_PATTERN})(?: \[(DB|API|UI)\])?: (.+)$", re.MULTILINE) +HTML_ANCHOR = re.compile(r"]*\bid\s*=", re.IGNORECASE) +DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение") +CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение") +RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения") +CAPABILITY_CODES_PATH = Path(__file__).with_name("capability-codes.md") +CAPABILITY_CODE_ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|$") + + +def plain_text(value: str) -> str: + value = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", value) + return re.sub(r"^[\d.\-\s]+|[`*_]", "", value).strip() + + +def heading_slug(title: str) -> str: + """Build the heading fragment used by GitHub-style Markdown renderers.""" + title = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", title) + title = re.sub(r"[`*_~]", "", title).lower() + slug: list[str] = [] + for char in title: + category = unicodedata.category(char)[0] + if char.isspace(): + if slug and slug[-1] != "-": + slug.append("-") + elif char in {"-", "_"} or category in {"L", "M", "N"}: + slug.append(char) + return "".join(slug).strip("-") + + +def parse_fr_reference(label: str) -> tuple[str | None, str] | None: + """Return an optional requirement ID and the local FR number from a link label.""" + label = label.strip() + match = FR_ID.fullmatch(label) + if match: + return match.group("requirement"), match.group("number") + match = re.fullmatch( + rf"({LEGACY_REQUIREMENT_ID_PATTERN})\s*/\s*(FR-\d{{2,}})", label + ) + if match: + return match.group(1), match.group(2) + return None + + +def load_capability_codes() -> tuple[dict[str, str], list[str]]: + codes: dict[str, str] = {} + errors: list[str] = [] + try: + lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines() + except OSError as error: + return {}, [f"не удалось прочитать реестр capability codes: {error}"] + + prefixes: dict[str, str] = {} + for line in lines: + match = CAPABILITY_CODE_ROW.match(line) + if not match: + continue + capability_path, prefix = match.groups() + if capability_path in codes: + errors.append(f"путь capability повторяется в реестре: {capability_path}") + if prefix in prefixes: + errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}") + codes[capability_path] = prefix + prefixes[prefix] = capability_path + return codes, errors + + +def spec_capability_path(path: Path) -> str | None: + parts = path.parts + indexes = [index for index, part in enumerate(parts) if part == "specs"] + if not indexes: + return None + capability_parts = parts[indexes[-1] + 1:-1] + return "/".join(capability_parts) if capability_parts else None + + +def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]: + """Return generated heading fragments and fragments that target FR headings.""" + targets: set[str] = set() + fr_targets: dict[str, tuple[str, str]] = {} + duplicates: dict[str, int] = {} + requirement_id = "" + for line in text.splitlines(): + if line.startswith("### Requirement:"): + requirement_id = "" + id_match = REQUIREMENT_ID.match(line) + if id_match: + requirement_id = id_match.group(1) + + match = HEADING.match(line) + if not match: + continue + slug = heading_slug(match.group(2)) + if not slug: + continue + duplicate_index = duplicates.get(slug, 0) + duplicates[slug] = duplicate_index + 1 + target = slug if duplicate_index == 0 else f"{slug}-{duplicate_index}" + targets.add(target) + + fr_match = FR_HEADING.match(line) + if fr_match and requirement_id: + fr_id = FR_ID.fullmatch(fr_match.group(1)) + if fr_id: + fr_targets[target] = (requirement_id, fr_id.group("number")) + return targets, fr_targets + + +def requirement_blocks(text: str): + heading = re.compile(r"^## .*|^### Requirement: (.+)$", re.MULTILINE) + headings = list(heading.finditer(text)) + operation = "" + for index, match in enumerate(headings): + if not match.group(1): + operation = match.group().removeprefix("## ") + continue + if operation in {"REMOVED Requirements", "RENAMED Requirements"}: + continue + end = headings[index + 1].start() if index + 1 < len(headings) else len(text) + yield match.group(1), text[match.end():end] + + +def check_database_table_pattern(content: str) -> list[str]: + errors: list[str] = [] + tables: list[list[str]] = [] + current: list[str] = [] + for line in content.splitlines(): + if line.strip().startswith("|"): + current.append(line.strip()) + elif current: + tables.append(current) + current = [] + if current: + tables.append(current) + + if len(tables) != 1: + return ["паттерн таблицы БД требует ровно одну Markdown-таблицу"] + rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]] + if len(rows) < 3 or tuple(rows[0]) != DB_TABLE_COLUMNS: + return ["таблица БД должна иметь заголовки Поле, Тип, Ограничения и значение по умолчанию, Назначение"] + if len(rows[1]) != len(DB_TABLE_COLUMNS) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]): + errors.append("в таблице БД некорректная строка разделителя") + + field_names: set[str] = set() + for row in rows[2:]: + if len(row) != len(DB_TABLE_COLUMNS) or any(not cell for cell in row): + errors.append("каждая строка таблицы БД должна содержать четыре непустые ячейки") + continue + field_name = row[0].strip("`") + if field_name in field_names: + errors.append(f"поле `{field_name}` повторяется в таблице БД") + field_names.add(field_name) + return errors + + +def check_message_contract_pattern(content: str, direction: str | None = None) -> list[str]: + errors: list[str] = [] + contract_type_match = re.search(r"(?m)^Тип контракта: (request|response)$", content) + if direction is None and not contract_type_match: + errors.append("контракт должен явно указывать Тип контракта: request или response") + selected_direction = direction or (contract_type_match.group(1) if contract_type_match else "") + columns = ( + RESPONSE_CONTRACT_COLUMNS + if selected_direction == "response" + else CONTRACT_COLUMNS + ) + + tables: list[list[str]] = [] + current: list[str] = [] + for line in content.splitlines(): + if line.strip().startswith("|"): + current.append(line.strip()) + elif current: + tables.append(current) + current = [] + if current: + tables.append(current) + + if len(tables) != 1: + return errors + ["паттерн контракта требует ровно одну Markdown-таблицу"] + rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]] + if len(rows) < 3 or tuple(rows[0]) != columns: + required_columns = ", ".join(columns) + return errors + [f"таблица контракта должна содержать колонки: {required_columns}"] + if len(rows[1]) != len(columns) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]): + errors.append("в таблице контракта некорректная строка разделителя") + + field_names: set[str] = set() + for row in rows[2:]: + if len(row) != len(columns) or any(not cell for cell in row): + errors.append("каждая строка таблицы контракта должна содержать нужное число непустых ячеек") + continue + field_name = row[0].strip(chr(96)) + if field_name in field_names: + errors.append(f"поле контракта {field_name} повторяется") + field_names.add(field_name) + if row[2] not in {"Обязательное", "Опциональное"}: + errors.append(f"поле контракта {field_name} должно явно задавать обязательность") + + return errors + + +def check_http_endpoint_contract(content: str) -> list[str]: + errors: list[str] = [] + headings = re.findall(r"^##### (.+)$", content, re.MULTILINE) + if headings != ["Request", "Response"]: + return ["CONTRACT должен содержать только подразделы Request и Response в этом порядке"] + + request, response = re.split(r"^##### (?:Request|Response)\s*$", content, maxsplit=2, flags=re.MULTILINE)[1:] + if len(re.findall(r"(?m)^Метод: \x60?(?:GET|POST|PUT|PATCH|DELETE)\x60?; путь: \x60?/\S+", request)) != 1: + errors.append("в Request укажи один HTTP-метод и путь endpoint") + request_tables = sum(line.strip().startswith("|") for line in request.splitlines()) + if request_tables: + errors.extend(check_message_contract_pattern(request, "request")) + elif not re.search(r"Тело запроса(?: и query-параметры)? отсутств(?:ует|уют)", request): + errors.append("в Request укажи таблицу тела запроса или явно отметь его отсутствие") + + if not re.search(r"(?m)^HTTP status:", response): + errors.append("в Response укажи HTTP status") + errors.extend(check_message_contract_pattern(response, "response")) + return errors + + +def check_requirement( + name: str, + block: str, + targets: set[str], + fr_targets: dict[str, tuple[str, str]], + require_qualified_ids: bool = False, +) -> list[str]: + errors: list[str] = [] + ids = REQUIREMENT_ID.findall(block) + if len(ids) != 1: + return [f"{name}: нужен один стабильный **ID:** с префиксом capability и номером Requirement"] + requirement_id = ids[0] + is_qualified = "." in requirement_id + if require_qualified_ids and not is_qualified: + errors.append("новый или изменённый Requirement должен иметь составной ID capability, например CFG.AS-01") + level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE) + has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT" + expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"] + if ( + len(level_four) != len(expected_level_four) + 1 + or not level_four[0].startswith("Scenario: ") + or level_four[1:] != expected_level_four + ): + return [f"{name}: нужны один Scenario, Функциональные требования и опциональный завершающий CONTRACT"] + + scenario_heading = level_four[0].removeprefix("Scenario: ") + is_short_use_case = scenario_heading.startswith("Сокращенный use case:") + scenario, details = block.split("#### Функциональные требования", 1) + scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1] + if has_contract: + if is_short_use_case: + errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case") + details, contract_content = details.split("#### CONTRACT", 1) + errors.extend(check_http_endpoint_contract(contract_content)) + sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE) + narrative = "" + outcomes = "" + short_use_case_flow_lines: list[str] = [] + + if is_short_use_case: + if sections != ["Основной поток"]: + errors.append("сокращенный use case должен содержать только Основной поток") + before_flow, separator, flow = scenario.partition("##### Основной поток") + if not separator or before_flow.strip(): + errors.append("сокращенный use case содержит только раздел Основной поток") + short_use_case_flow_lines = [line.strip() for line in flow.splitlines() if line.strip()] + if any(not re.match(r"^\d+\. .+", line) for line in short_use_case_flow_lines): + errors.append("основной поток сокращенного use case содержит только нумерованные шаги") + if any(len(plain_text(line)) > 240 for line in short_use_case_flow_lines): + errors.append("шаг сокращенного use case длиннее 240 знаков; детали должны быть в FR") + else: + required = [section for section in sections if section != "Назначение"] + if required != list(SECTIONS) or sections.count("Назначение") > 1: + errors.append("разделы Scenario не соответствуют шаблону") + if "Назначение" in sections and sections[0] != "Назначение": + errors.append("опциональное Назначение должно предшествовать Участники") + for section in sections: + content = re.split(r"^##### ", scenario.split(f"##### {section}\n", 1)[1], maxsplit=1, flags=re.MULTILINE)[0] + if not content.strip(): + errors.append(f"пустой раздел Scenario: {section}") + + narrative, separator, outcomes = scenario.partition("##### Коды завершения") + if not separator: + errors.append("нет списка кодов завершения") + if re.search(r"^\s*\|", narrative, re.MULTILINE): + errors.append("техническая таблица должна находиться в FR") + for paragraph in re.split(r"\n\s*\n", narrative): + lines = [line for line in paragraph.splitlines() if line.strip() and not line.startswith("#")] + chunks = lines if all(re.match(r"^(?:\d+\.|-) ", line) for line in lines) else [" ".join(lines)] + if any(len(plain_text(chunk)) > 240 for chunk in chunks): + errors.append("абзац или шаг Scenario длиннее 240 знаков; перенеси детали в FR") + + if re.search(r"(?im)^\s*(?:[-*]\s*)?(?:\*\*)?(?:GIVEN|WHEN|THEN|AND|BUT)\b", scenario): + errors.append("Scenario содержит Gherkin") + if "```" in scenario or "~~~" in scenario: + errors.append("блок кода должен находиться в FR") + + flow = scenario.partition("##### Основной поток")[2] + if not is_short_use_case: + flow = flow.partition("##### Альтернативы и ошибки")[0] + steps = [int(number) for number in re.findall(r"^(\d+)\. ", flow, re.MULTILINE)] + if not steps or steps != list(range(1, len(steps) + 1)): + errors.append("основной поток должен содержать последовательные нумерованные шаги") + + raw_definitions = list(FR_HEADING.finditer(details)) + if len(raw_definitions) != len(re.findall(r"^##### ", details, re.MULTILINE)): + errors.append("подразделы Функциональных требований должны иметь заголовки с ID вида .FR-NN") + definitions: list[tuple[re.Match[str], re.Match[str]]] = [] + for match in raw_definitions: + fr_id_match = FR_ID.fullmatch(match.group(1)) + if not fr_id_match: + errors.append(f"некорректный ID FR в заголовке: {match.group(1)}") + continue + definitions.append((match, fr_id_match)) + numbers = [int(fr_id_match.group("number").removeprefix("FR-")) for _, fr_id_match in definitions] + if not numbers or numbers[0] != 1 or numbers != sorted(set(numbers)): + errors.append("FR должны начинаться с FR-01 и иметь уникальные возрастающие номера") + + fr_contents: dict[str, str] = {} + for index, (match, fr_id_match) in enumerate(definitions): + fr_id = fr_id_match.group("number") + expected_fr_id = f"{requirement_id}.{fr_id}" if is_qualified else fr_id + if match.group(1) != expected_fr_id: + errors.append(f"заголовок FR должен использовать полный ID {expected_fr_id}") + target = heading_slug(match.group(0).removeprefix("##### ")) + if fr_targets.get(target) != (requirement_id, fr_id): + errors.append(f"заголовок {match.group(1)} не создаёт ожидаемый Markdown-якорь") + next_definition = definitions[index + 1][0] if index + 1 < len(definitions) else None + end = next_definition.start() if next_definition else len(details) + fr_contents[fr_id] = details[match.end():end] + format_type = match.group(2) + title = match.group(3) + if format_type == "DB" or title.lower().startswith("таблица хранения "): + errors.extend(check_database_table_pattern(fr_contents[fr_id])) + if format_type == "API" and re.match(r"контракт (?:сообщения|запроса|ответа)\b", title, re.IGNORECASE): + errors.extend(check_message_contract_pattern(fr_contents[fr_id])) + if has_contract and format_type == "API": + errors.append("HTTP request/response-контракт описывается в CONTRACT, не в FR [API]") + + for label, raw_target in LINK.findall(block): + target = unquote(raw_target) + if target not in targets: + errors.append(f"ссылка {label} ведёт на отсутствующий Markdown-заголовок #{target}") + continue + linked_fr = parse_fr_reference(label) + if "FR-" in label and not linked_fr: + errors.append(f"ссылка {label} должна содержать полный ID FR") + if linked_fr: + target_fr = fr_targets.get(target) + linked_requirement, linked_number = linked_fr + if target_fr is None or target_fr[1] != linked_number: + errors.append(f"ссылка {label} должна вести на заголовок соответствующего FR") + if linked_requirement and target_fr and target_fr[0] != linked_requirement: + errors.append(f"ссылка {label} ведёт на FR другого Requirement") + if target_fr and "." in target_fr[0] and label != f"{target_fr[0]}.{target_fr[1]}": + errors.append(f"ссылка {label} должна использовать полный ID {target_fr[0]}.{target_fr[1]}") + + if is_short_use_case: + for step in short_use_case_flow_lines: + has_local_fr = False + for label, raw_target in LINK.findall(step): + linked_fr = parse_fr_reference(label) + target_fr = fr_targets.get(unquote(raw_target)) + expected_label = f"{requirement_id}.FR-{linked_fr[1].removeprefix('FR-')}" if linked_fr and is_qualified else (linked_fr[1] if linked_fr else "") + if linked_fr and target_fr == (requirement_id, linked_fr[1]) and label == expected_label: + has_local_fr = True + break + if not has_local_fr: + errors.append("каждый шаг сокращенного use case должен ссылаться на локальный FR") + else: + rows = [line for line in outcomes.splitlines() if line.startswith("|")] + if not rows or rows[0] != "| Код | Смысл | Связанные FR |": + errors.append("таблица завершения должна иметь колонки Код, Смысл, Связанные FR") + codes = [] + for row in rows[2:]: + cells = [cell.strip() for cell in row.strip("|").split("|")] + if len(cells) != 3 or not re.fullmatch(r"`[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+`", cells[0]): + errors.append("некорректная строка таблицы кодов завершения") + continue + code = cells[0].strip("`") + codes.append(code) + references = [ + fr_targets[target][1] + for _, raw_target in LINK.findall(cells[2]) + if (target := unquote(raw_target)) in fr_targets + and fr_targets[target][0] == requirement_id + ] + if not cells[1] or not references or not any(code in fr_contents[fr_id] for fr_id in references if fr_id in fr_contents): + errors.append(f"{code}: нужны смысл и ссылка на локальный FR, описывающий этот код") + if not codes or len(codes) != len(set(codes)): + errors.append("список кодов завершения пуст или содержит дубликаты") + if set(CODE.findall(narrative)) != set(codes): + errors.append("коды в потоке/альтернативах должны совпадать со списком завершения") + return [f"{requirement_id}: {error}" for error in errors] + +def validate( + path: Path, + base: Path | None = None, + require_qualified_ids: bool = False, + capability_codes: dict[str, str] | None = None, +) -> list[str]: + text = path.read_text(encoding="utf-8") + if HTML_ANCHOR.search(text): + return ["HTML-якоря запрещены; используйте автоматически сгенерированные Markdown-якоря заголовков"] + + targets, fr_targets = heading_targets(text) + if base: + base_targets, base_fr_targets = heading_targets(base.read_text(encoding="utf-8")) + targets.update(base_targets) + fr_targets.update(base_fr_targets) + + errors = [] + if capability_codes is None: + capability_codes, registry_errors = load_capability_codes() + errors.extend(registry_errors) + blocks = list(requirement_blocks(text)) + ids = REQUIREMENT_ID.findall(text) + if len(ids) != len(set(ids)): + errors.append("повторяющиеся ID Requirements") + capability_path = spec_capability_path(path) + for requirement_id in ids: + if "." not in requirement_id: + continue + prefix = capability_codes.get(capability_path or "") + if not prefix: + errors.append(f"для capability {capability_path or '<не определена>'} нет префикса в capability-codes.md") + elif not re.fullmatch(rf"{re.escape(prefix)}-\d{{2,}}", requirement_id): + errors.append(f"ID {requirement_id} не соответствует префиксу {prefix} для {capability_path}") + if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE): + errors.append("нет Requirements") + for name, block in blocks: + errors.extend(check_requirement(name, block, targets, fr_targets, require_qualified_ids)) + return errors + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("paths", nargs="*", type=Path, default=[Path("openspec/specs")]) + parser.add_argument("--base", type=Path, help="master spec referenced from a delta") + parser.add_argument( + "--require-qualified-ids", + action="store_true", + help="требовать составные ID у Requirements в новых или изменённых specs", + ) + args = parser.parse_args() + paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])}) + if not paths: + parser.error("не найдены spec.md") + capability_codes, registry_errors = load_capability_codes() + failed = False + for error in registry_errors: + print(f"ERROR {CAPABILITY_CODES_PATH}: {error}") + failed = True + for path in paths: + try: + errors = validate(path, args.base, args.require_qualified_ids, capability_codes) + except OSError as error: + errors = [str(error)] + for error in errors: + print(f"ERROR {path}: {error}") + if not errors: + print(f"OK {path}") + failed |= bool(errors) + return int(failed) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/openspec/specs/.gitkeep b/openspec/specs/.gitkeep new file mode 100644 index 0000000..e69de29