From 1be96f7d4b3d5d333ff3179a4a9eb56fe073adbf Mon Sep 17 00:00:00 2001 From: zosimovaa Date: Sat, 10 Oct 2026 21:17:02 +0300 Subject: [PATCH] init commit --- openspec/changes/archive/.gitkeep | 0 openspec/config.yaml | 43 ++ openspec/schemas/function-driven/README.md | 166 ++++++ .../validate_format.cpython-312.pyc | Bin 0 -> 34077 bytes .../function-driven/capability-codes.md | 19 + .../patterns/database-table.md | 37 ++ .../patterns/message-contract.md | 57 ++ openspec/schemas/function-driven/schema.yaml | 281 ++++++++++ .../function-driven/templates/design.md | 21 + .../function-driven/templates/main-spec.md | 106 ++++ .../function-driven/templates/proposal.md | 29 + .../schemas/function-driven/templates/spec.md | 107 ++++ .../function-driven/templates/tasks.md | 15 + .../function-driven/validate_format.py | 494 ++++++++++++++++++ openspec/specs/.gitkeep | 0 15 files changed, 1375 insertions(+) create mode 100644 openspec/changes/archive/.gitkeep create mode 100644 openspec/config.yaml create mode 100644 openspec/schemas/function-driven/README.md create mode 100644 openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc create mode 100644 openspec/schemas/function-driven/capability-codes.md create mode 100644 openspec/schemas/function-driven/patterns/database-table.md create mode 100644 openspec/schemas/function-driven/patterns/message-contract.md create mode 100644 openspec/schemas/function-driven/schema.yaml create mode 100644 openspec/schemas/function-driven/templates/design.md create mode 100644 openspec/schemas/function-driven/templates/main-spec.md create mode 100644 openspec/schemas/function-driven/templates/proposal.md create mode 100644 openspec/schemas/function-driven/templates/spec.md create mode 100644 openspec/schemas/function-driven/templates/tasks.md create mode 100644 openspec/schemas/function-driven/validate_format.py create mode 100644 openspec/specs/.gitkeep 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 0000000000000000000000000000000000000000..90b5f27f63ad4ffe59cc10f0ee2cf1f3489d247f GIT binary patch literal 34077 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.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