fix(adopt,init): decide by evidence, refuse instead of defaulting
Running a full assess -> plan -> apply -> verify against Infra/LXD and Infra/Docker in throwaway worktrees, and a bootstrap into a scratch directory, surfaced the same two mistakes repeated across both commands: a shape was read where evidence was available, and a missing answer became a silent default rather than a refusal. adopt: - classify secret-shaped paths by content, not by filename. A live credential blocks; a file tracked against the repository's own ignore rules and a name-only match are warnings; findings name keys, never values. In Infra/Docker this turned 14 false blockers into 2 true ones and surfaced 14 files committed despite `**/.env`. - carry assess findings into the plan and refuse while an error-severity finding is unresolved. An owner may accept one through `acknowledgedFindings` with a reason; the acknowledgement enters the plan and therefore planHash, so approval covers it. - derive metadata.name from the git remote instead of the clone directory, and refuse to plan without a confirmed owner (runbook section 9). - propose content roots from the whole content vocabulary rather than the winning type's markers, and recognise N sibling directories sharing a marker file as one file-set root with a selector, as runbook 7.2 already specified. Authority defaulted rather than derived now asks. init: apply the guards adopt already had. Answers are validated against the vocabularies that already existed in constants (name, type, lifecycle, access) so init can no longer create a repository that fails its own validate; owners are required; a directory that already holds the planned paths is refused at plan time and pointed at adopt; and every path from a plan is confined before the first byte is written -- init wrote outside the repository from an edited plan. validate: mask fenced blocks and inline code spans before scanning for Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as a link and kept validate red for a reason unrelated to the repository. paths: allow "." as a whole content-root path, never as a segment, so the file-set root runbook 7.2 describes can be declared. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
693211cee9
commit
1ab02a257c
+12
-4
@@ -38,10 +38,13 @@ repoctl describe --repo NAME|PATH [--root PATH ...]
|
|||||||
repoctl context --repo NAME|PATH --intent INTENT
|
repoctl context --repo NAME|PATH --intent INTENT
|
||||||
[--include-related] [--materialize]
|
[--include-related] [--materialize]
|
||||||
[--budget-bytes N] [--strict]
|
[--budget-bytes N] [--strict]
|
||||||
repoctl init --repo PATH [--answers FILE] [--git-init|--no-git-init]
|
repoctl init --repo PATH --name NAME --type TYPE --owner NAME
|
||||||
|
[--answers FILE] [--title T] [--lifecycle L]
|
||||||
|
[--git-init|--no-git-init]
|
||||||
repoctl init --repo PATH --apply --plan FILE --approve SHA256
|
repoctl init --repo PATH --apply --plan FILE --approve SHA256
|
||||||
repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||||
[--answers FILE] [--strategy overlay|normalize]
|
[--answers FILE] [--owner NAME] [--type TYPE]
|
||||||
|
[--strategy overlay|normalize]
|
||||||
[--recipe ID] [--plan FILE] [--approve SHA256]
|
[--recipe ID] [--plan FILE] [--approve SHA256]
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -56,6 +59,8 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
|||||||
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
|
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
|
||||||
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
|
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
|
||||||
|
|
||||||
|
`init` проверяет ответы до сборки плана (`name` против `ID_PATTERN`, type/lifecycle/access против enum, обязательный owner), отказывается планировать в каталог, где уже лежит любой из создаваемых путей, и confine'ит каждый путь плана при записи. Отказы — конверты с кодами `INIT_*`, а не строки в stderr.
|
||||||
|
|
||||||
`init`:
|
`init`:
|
||||||
|
|
||||||
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
|
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
|
||||||
@@ -75,7 +80,10 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
|||||||
- для legacy root `kdb.yaml` предлагает небольшой `kdb/kdb.yaml` adapter;
|
- для legacy root `kdb.yaml` предлагает небольшой `kdb/kdb.yaml` adapter;
|
||||||
- если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
|
- если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
|
||||||
- существующие skills, handlers, KDB и agent instructions не переписывает;
|
- существующие skills, handlers, KDB и agent instructions не переписывает;
|
||||||
- tracked secret является blocker; untracked secret-shaped paths показываются path-only без содержимого;
|
- secret-shaped путь классифицируется по содержимому: живой credential — blocker, tracked вопреки ignore-правилам и совпадение только по имени — warnings, untracked — info; наружу выходят имена ключей, не значения;
|
||||||
|
- `plan` требует подтверждённого owner и отказывается строиться при неразрешённой находке severity `error`; принятие находки явное, с причиной, и входит в `planHash`;
|
||||||
|
- имя репозитория выводится из remote, а не из имени каталога клона;
|
||||||
|
- content roots предлагаются по всему словарю содержимого; репозиторий из однотипных каталогов объявляется одним `file-set` корнем с селектором;
|
||||||
- `documents-to-content-root` выполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;
|
- `documents-to-content-root` выполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;
|
||||||
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
|
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
|
||||||
- никогда не делает commit, push, clone или external operation.
|
- никогда не делает commit, push, clone или external operation.
|
||||||
@@ -109,7 +117,7 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
|||||||
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
||||||
- Normalization tests отложены вместе с самой normalization: `--strategy normalize` и recipes не реализованы и не предлагаются CLI.
|
- Normalization tests отложены вместе с самой normalization: `--strategy normalize` и recipes не реализованы и не предлагаются CLI.
|
||||||
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
||||||
- `Infra/LXD` используется только для read-only `assess` и `plan`; Git status до и после должен совпасть.
|
- `Infra/LXD` и `Infra/Docker` используются только для read-only `assess` и `plan`, либо для полного цикла в одноразовом `git worktree`; Git status рабочего дерева до и после должен совпасть.
|
||||||
- `Services/Antivirus` — пилот Wave 1, adopted по решению владельца. `apply` к нему выполняется осознанно: через утверждённый `planHash`, с предварительным прогоном на копии и последующим `verify --plan`. Остальные реальные репозитории остаются read-only до расширения wave.
|
- `Services/Antivirus` — пилот Wave 1, adopted по решению владельца. `apply` к нему выполняется осознанно: через утверждённый `planHash`, с предварительным прогоном на копии и последующим `verify --plan`. Остальные реальные репозитории остаются read-only до расширения wave.
|
||||||
|
|
||||||
## Зафиксированные ограничения
|
## Зафиксированные ограничения
|
||||||
|
|||||||
@@ -219,7 +219,11 @@ contentRoots:
|
|||||||
selector: "*/compose.y*ml"
|
selector: "*/compose.y*ml"
|
||||||
```
|
```
|
||||||
|
|
||||||
Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее.
|
Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее. Когда authority выбрана по умолчанию словаря, а не выведена из пары `generatedFrom`, assess помечает корень `ADOPT_SOURCE_MIRROR_AMBIGUOUS` и спрашивает владельца.
|
||||||
|
|
||||||
|
Content roots ищутся по всему словарю содержимого, а не только по маркерам предложенного type: `docs/` числится evidence для `project`, и привязка поиска к победившему типу означала, что в infrastructure-репозитории он не объявлялся никогда. Type отвечает на вопрос «для чего репозиторий», content roots — «что в нём лежит».
|
||||||
|
|
||||||
|
Репозиторий из однотипных каталогов (стек на каталог) не имеет одного каталога, на который можно показать, а перечисление двадцати описывает раскладку вместо содержимого. Когда не менее трёх каталогов первого уровня несут общий маркерный файл (`compose.y*ml`, `docker-compose.y*ml`, `Chart.yaml`, `main.tf`, `Dockerfile`), объявляется один `file-set` корень с `path: .` и селектором — форма `docker-stacks` из примера выше. `path: .` допустим только как целый путь content root и никогда как write target.
|
||||||
|
|
||||||
### 7.3. Найти знания и provenance
|
### 7.3. Найти знания и provenance
|
||||||
|
|
||||||
@@ -234,6 +238,8 @@ contentRoots:
|
|||||||
- freshness signals;
|
- freshness signals;
|
||||||
- наличие потенциальных secret-shaped paths или keys без вывода values.
|
- наличие потенциальных secret-shaped paths или keys без вывода values.
|
||||||
|
|
||||||
|
Содержимое secret-shaped файла читать разрешено — именно чтение отличает credential от документа о credentials, — но наружу выходят только имена ключей. Значения не попадают ни в findings, ни в логи, ни в assessment.
|
||||||
|
|
||||||
### 7.4. Найти agent entrypoints и automation
|
### 7.4. Найти agent entrypoints и automation
|
||||||
|
|
||||||
Определить:
|
Определить:
|
||||||
@@ -267,6 +273,9 @@ runbookOutput:
|
|||||||
path: Infra/LXD
|
path: Infra/LXD
|
||||||
baselineRevision: 0123456789abcdef
|
baselineRevision: 0123456789abcdef
|
||||||
dirty: false
|
dirty: false
|
||||||
|
identity:
|
||||||
|
name: optools-lxd
|
||||||
|
source: git-remote
|
||||||
classification:
|
classification:
|
||||||
proposedType: infrastructure-config
|
proposedType: infrastructure-config
|
||||||
confidence: high
|
confidence: high
|
||||||
@@ -311,10 +320,27 @@ Assessment MUST distinguish `detected`, `inferred` and `confirmed` values.
|
|||||||
|
|
||||||
Остальные безопасные defaults могут быть предложены в plan без отдельного диалога.
|
Остальные безопасные defaults могут быть предложены в plan без отдельного диалога.
|
||||||
|
|
||||||
|
Граница подтверждения — не рекомендация. `plan` MUST отказываться строиться без подтверждённого owner (`ADOPT_OWNER_UNKNOWN`): контракт с `owners: []` выглядит подтверждённым, хотя на вопрос никто не ответил.
|
||||||
|
|
||||||
|
Имя репозитория выводится из URL remote — последние два сегмента пути, приведённые к `metadata.name` (`.../OpTools/LXD.git` → `optools-lxd`). Каталог клона именем не является: два клона одного репозитория дали бы разные ответы, а worktree — третий. При отсутствии remote assess берёт имя каталога и помечает это `ADOPT_NAME_INFERRED`.
|
||||||
|
|
||||||
## 10. Phase 4 — adoption plan
|
## 10. Phase 4 — adoption plan
|
||||||
|
|
||||||
Plan строится относительно immutable baseline revision и содержит только операции `create`, `patch-managed-block` или `preserve`.
|
Plan строится относительно immutable baseline revision и содержит только операции `create`, `patch-managed-block` или `preserve`.
|
||||||
|
|
||||||
|
Plan MUST переносить findings из assessment в поле `findings` и MUST отказываться строиться, пока остаётся хотя бы одна неразрешённая находка severity `error` (`ADOPT_ASSESS_BLOCKERS_UNRESOLVED`). Иначе единственный жёсткий результат assessment теряется на следующем шаге, а `apply` и `verify` возвращают success поверх репозитория, о котором assess сказал «блокер».
|
||||||
|
|
||||||
|
Владелец может принять конкретную находку, перечислив её в `acknowledgedFindings` с обязательным `reason`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
acknowledgedFindings:
|
||||||
|
- code: ADOPT_SECRET_CONTENT_VERIFIED
|
||||||
|
path: airflow/.env
|
||||||
|
reason: rotation scheduled, tracked separately
|
||||||
|
```
|
||||||
|
|
||||||
|
Acknowledgement входит в plan, а значит в `planHash`, а значит в предмет approval: принять находку молча нельзя, и принятая находка не исчезает — `verify` возвращает её в `unresolvedFindings`.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
runbookOutput:
|
runbookOutput:
|
||||||
schema: stewardship/adoption-plan@0.1
|
schema: stewardship/adoption-plan@0.1
|
||||||
@@ -578,8 +604,13 @@ findingCodes:
|
|||||||
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
|
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
|
||||||
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
||||||
ADOPT_ENTRYPOINT_CONFLICT: blocker
|
ADOPT_ENTRYPOINT_CONFLICT: blocker
|
||||||
ADOPT_SECRET_TRACKED: blocker
|
ADOPT_SECRET_CONTENT_VERIFIED: blocker
|
||||||
|
ADOPT_SECRET_IGNORED_BUT_TRACKED: warning
|
||||||
|
ADOPT_SECRET_NAME_SHAPED: warning
|
||||||
ADOPT_SECRET_SHAPED_UNTRACKED: info
|
ADOPT_SECRET_SHAPED_UNTRACKED: info
|
||||||
|
ADOPT_NAME_INFERRED: info
|
||||||
|
ADOPT_ASSESS_BLOCKERS_UNRESOLVED: blocker
|
||||||
|
ADOPT_ACKNOWLEDGEMENT_INCOMPLETE: blocker
|
||||||
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
|
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
|
||||||
ADOPT_BASELINE_CHANGED: blocker
|
ADOPT_BASELINE_CHANGED: blocker
|
||||||
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
|
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
|
||||||
@@ -597,7 +628,16 @@ findingCodes:
|
|||||||
APPROVAL_FAILED: blocker
|
APPROVAL_FAILED: blocker
|
||||||
```
|
```
|
||||||
|
|
||||||
`ADOPT_SECRET_TRACKED` относится только к **tracked** путям. Untracked путь с secret-shaped именем получает отдельный `ADOPT_SECRET_SHAPED_UNTRACKED`, а путь, который репозиторий явно игнорирует, не сообщается вовсе: blocker-код, срабатывающий на игнорируемых файлах, приучает игнорировать blocker.
|
Secret-shaped путь классифицируется по тому, что о нём действительно известно, а не по имени файла. Один blocker на совпадение имени давал в реальном репозитории 14 ложных находок из 16 и приучал пропускать все шестнадцать.
|
||||||
|
|
||||||
|
| Код | Severity | Что установлено |
|
||||||
|
|---|---|---|
|
||||||
|
| `ADOPT_SECRET_CONTENT_VERIFIED` | blocker | в содержимом есть присваивание credential-ключа с реальным значением либо PEM private key block |
|
||||||
|
| `ADOPT_SECRET_IGNORED_BUT_TRACKED` | warning | путь отслеживается вопреки собственным ignore-правилам репозитория |
|
||||||
|
| `ADOPT_SECRET_NAME_SHAPED` | warning | совпало только имя; содержимое credential не несёт |
|
||||||
|
| `ADOPT_SECRET_SHAPED_UNTRACKED` | info | untracked и неигнорируемый путь |
|
||||||
|
|
||||||
|
Содержимое читается только чтобы отличить credential от документа о credentials, и наружу выходят **имена ключей**, никогда значения (см. 7.3). Значения вида `<SECRET:name>`, `${VAR}`, `{{ var }}`, `changeme` и подобные плейсхолдеры credential не считаются. Путь, который репозиторий игнорирует и который не отслеживается, не сообщается вовсе.
|
||||||
|
|
||||||
`ADOPT_WORKTREE_DIRTY` на этапе `assess` остаётся warning и не мешает планированию. На этапе `apply` он становится blocker, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
|
`ADOPT_WORKTREE_DIRTY` на этапе `assess` остаётся warning и не мешает планированию. На этапе `apply` он становится blocker, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
|
||||||
|
|
||||||
|
|||||||
@@ -819,6 +819,10 @@ Bootstrap предлагает, но не навязывает:
|
|||||||
|
|
||||||
Для существующего репозитория используется другая операция — `repoctl adopt`. Она не раскладывает старый repository как новый шаблон, а сначала картографирует уже существующие источники истины, agent instructions, KDB и штатные места результата.
|
Для существующего репозитория используется другая операция — `repoctl adopt`. Она не раскладывает старый repository как новый шаблон, а сначала картографирует уже существующие источники истины, agent instructions, KDB и штатные места результата.
|
||||||
|
|
||||||
|
Перед планом adoption обязана получить ответ на то, что нельзя вывести: кто владелец. Пустой список владельцев в контракте выглядит как подтверждённый ответ, хотя никто не отвечал, поэтому `plan` без владельца просто не строится. Имя репозитория при этом берётся из remote, а не из имени каталога, в который его склонировали.
|
||||||
|
|
||||||
|
Найденные секреты различаются по тому, что о них известно. Файл с живым паролем внутри — блокер: план не построится, пока владелец либо не уберёт секрет, либо не примет находку явно и с причиной. Файл, чьё имя лишь похоже на секрет (например, документ `SECRETS.md` про конвенцию плейсхолдеров), и файл, закоммиченный вопреки собственному `.gitignore`, — предупреждения. Содержимое при этом читается только для этой классификации, и наружу выходят имена ключей, но никогда значения.
|
||||||
|
|
||||||
По умолчанию adoption добавляет overlay и ничего не переносит. Если владелец отдельно просит упорядочить дерево, используется именованная normalization recipe. Например, `documents-to-content-root` оставляет в корне `README.md`, `AGENTS.md` и `CLAUDE.md`, переносит только подтверждённые длинные документы и одновременно переписывает contract, KDB, frontmatter и Markdown links.
|
По умолчанию adoption добавляет overlay и ничего не переносит. Если владелец отдельно просит упорядочить дерево, используется именованная normalization recipe. Например, `documents-to-content-root` оставляет в корне `README.md`, `AGENTS.md` и `CLAUDE.md`, переносит только подтверждённые длинные документы и одновременно переписывает contract, KDB, frontmatter и Markdown links.
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
|
|||||||
+25
-2
@@ -105,6 +105,16 @@ repoctl context --repo . --intent domain.action --output json
|
|||||||
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json
|
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Ответы проверяются до сборки плана, чтобы `init` не мог создать репозиторий, который не проходит собственный `validate`:
|
||||||
|
|
||||||
|
| Код | Когда |
|
||||||
|
|---|---|
|
||||||
|
| `INIT_ANSWERS_INCOMPLETE` | нет `--name` или `--type` |
|
||||||
|
| `INIT_NAME_INVALID` | имя не подходит под `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`; в сообщении есть готовая замена (`Services/Mail` → `services-mail`) |
|
||||||
|
| `INIT_TYPE_UNKNOWN`, `INIT_LIFECYCLE_UNKNOWN`, `INIT_ACCESS_UNKNOWN` | значение вне enum схемы |
|
||||||
|
| `INIT_OWNER_UNKNOWN` | владелец не подтверждён — та же граница, что у `adopt` |
|
||||||
|
| `INIT_PATH_COLLISION` | каталог уже содержит один из создаваемых путей; для существующего репозитория нужен `adopt`, а не `init` |
|
||||||
|
|
||||||
В ответе — полный список файлов, которые будут созданы (`ops/contract.yaml`, `kdb/kdb.yaml`, `AGENTS.md`, `CLAUDE.md`, `.claude/skills/*`, и т.д.) и `planHash`. Прочитайте план, убедитесь, что он ожидаем.
|
В ответе — полный список файлов, которые будут созданы (`ops/contract.yaml`, `kdb/kdb.yaml`, `AGENTS.md`, `CLAUDE.md`, `.claude/skills/*`, и т.д.) и `planHash`. Прочитайте план, убедитесь, что он ожидаем.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -120,11 +130,23 @@ repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planH
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
repoctl adopt --repo ../legacy-repo --mode assess --output json # инвентаризация, ничего не пишет
|
repoctl adopt --repo ../legacy-repo --mode assess --output json # инвентаризация, ничего не пишет
|
||||||
repoctl adopt --repo ../legacy-repo --mode plan --output json # предлагаемый diff + planHash, ничего не пишет
|
repoctl adopt --repo ../legacy-repo --mode plan --owner infra --output json # предлагаемый diff + planHash, ничего не пишет
|
||||||
repoctl adopt --repo ../legacy-repo --mode apply --plan plan.json --approve sha256:<planHash> --output json
|
repoctl adopt --repo ../legacy-repo --mode apply --plan plan.json --approve sha256:<planHash> --output json
|
||||||
repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт о совместимости после apply
|
repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт о совместимости после apply
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`plan` требует подтверждённого владельца — `--owner` (можно повторять) либо `owners:` в `--answers`; без него он отказывается строиться, а не выпускает контракт с пустым `owners`. Имя репозитория берётся из URL remote (последние два сегмента: `.../OpTools/LXD.git` → `optools-lxd`), либо задаётся `name:` в файле ответов.
|
||||||
|
|
||||||
|
`plan` также отказывается строиться, пока `assess` оставил находку severity `error` — например, файл с живым credential в git. Принять такую находку осознанно можно в файле ответов; `reason` обязателен, а сам acknowledgement входит в `planHash`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
owners: [infrastructure]
|
||||||
|
acknowledgedFindings:
|
||||||
|
- code: ADOPT_SECRET_CONTENT_VERIFIED
|
||||||
|
path: airflow/.env
|
||||||
|
reason: rotation scheduled, tracked separately
|
||||||
|
```
|
||||||
|
|
||||||
По умолчанию используется стратегия `overlay`: existing domain-native layout (например, `profiles-source/`, существующий `kdb.yaml` в корне) не перемещается и не переписывается — поверх него добавляется только недостающая метадата Stewardship. Если в репозитории уже занят путь `kdb/kdb.yaml`, `adopt` предложит `ops/knowledge.yaml` вместо конфликта. `apply` никогда не делает `git commit`, `push` или `clone`.
|
По умолчанию используется стратегия `overlay`: existing domain-native layout (например, `profiles-source/`, существующий `kdb.yaml` в корне) не перемещается и не переписывается — поверх него добавляется только недостающая метадата Stewardship. Если в репозитории уже занят путь `kdb/kdb.yaml`, `adopt` предложит `ops/knowledge.yaml` вместо конфликта. `apply` никогда не делает `git commit`, `push` или `clone`.
|
||||||
|
|
||||||
## Коды возврата
|
## Коды возврата
|
||||||
@@ -145,5 +167,6 @@ repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт
|
|||||||
- **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге.
|
- **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге.
|
||||||
- **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную).
|
- **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную).
|
||||||
- **`ADOPT_BASELINE_CHANGED`** — репозиторий изменился между `--mode plan` и `--mode apply` (кто-то создал файл из плана вручную); постройте план заново.
|
- **`ADOPT_BASELINE_CHANGED`** — репозиторий изменился между `--mode plan` и `--mode apply` (кто-то создал файл из плана вручную); постройте план заново.
|
||||||
- **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново.
|
- **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново. `INIT_PATH_COLLISION` на этапе плана означает, что каталог уже является репозиторием: используйте `adopt`.
|
||||||
|
- **`INIT_PATH_OUTSIDE_REPOSITORY`** — путь в файле плана ведёт наружу репозитория. План — обычный файл; если он был отредактирован вручную или перенесён между машинами, постройте его заново вместо правки.
|
||||||
- **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.
|
- **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.
|
||||||
|
|||||||
+12
-1
@@ -923,6 +923,10 @@ MCP является transport/discovery layer и MUST NOT становитьс
|
|||||||
|
|
||||||
### 18.1. `repoctl init`
|
### 18.1. `repoctl init`
|
||||||
|
|
||||||
|
`init` — единственный путь, где инструмент контролирует каждый байт результата, поэтому созданный им репозиторий MUST проходить `repoctl validate` по построению. Ответы MUST проверяться до сборки плана: `metadata.name` против `ID_PATTERN`, type против набора типов, lifecycle и access против своих enum. Owner MUST быть подтверждён — та же граница, что и в `adopt`: контракт не знает, какая команда его создала.
|
||||||
|
|
||||||
|
`init` MUST отказываться планировать в каталог, где уже лежит любой из создаваемых им путей, и указывать на `adopt` как на правильную операцию. `apply` MUST confine каждый путь из плана внутрь репозитория: план — обычный файл, который можно отредактировать вручную.
|
||||||
|
|
||||||
MVP bootstrap SHOULD:
|
MVP bootstrap SHOULD:
|
||||||
|
|
||||||
1. определить repository type;
|
1. определить repository type;
|
||||||
@@ -951,6 +955,9 @@ Adoption MUST:
|
|||||||
- создавать совместимый KDB index рядом, если канонический путь занят legacy-форматом;
|
- создавать совместимый KDB index рядом, если канонический путь занят legacy-форматом;
|
||||||
- показывать полный diff до записи;
|
- показывать полный diff до записи;
|
||||||
- разделять автоматически найденные факты и подтверждённые владельцем решения;
|
- разделять автоматически найденные факты и подтверждённые владельцем решения;
|
||||||
|
- отказываться строить plan без подтверждённого owner и выводить `metadata.name` из remote, а не из имени каталога клона;
|
||||||
|
- переносить findings из assessment в plan и отказываться строить plan, пока остаётся неразрешённая находка severity `error`; принятие такой находки MUST быть явным, с указанием причины, и входить в `planHash`;
|
||||||
|
- классифицировать secret-shaped пути по содержимому, а не только по имени, и не выводить значения — только имена ключей;
|
||||||
- допускать остановку после `assess` или `plan` без изменения репозитория;
|
- допускать остановку после `assess` или `plan` без изменения репозитория;
|
||||||
- при `overlay` изменять только repository-local metadata после явного подтверждения;
|
- при `overlay` изменять только repository-local metadata после явного подтверждения;
|
||||||
- при `normalize` изменять только paths из подтверждённой recipe и обновлять все contract/KDB/Markdown references атомарно;
|
- при `normalize` изменять только paths из подтверждённой recipe и обновлять все contract/KDB/Markdown references атомарно;
|
||||||
@@ -1159,7 +1166,11 @@ MVP считается готовым, когда:
|
|||||||
17. adoption LXD сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml` на месте;
|
17. adoption LXD сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml` на месте;
|
||||||
18. adoption Antivirus не перезаписывает существующий custom `kdb/kdb.yaml`.
|
18. adoption Antivirus не перезаписывает существующий custom `kdb/kdb.yaml`.
|
||||||
19. `documents-to-content-root` не перемещает `README.md`, `AGENTS.md`, `CLAUDE.md`, license и community files;
|
19. `documents-to-content-root` не перемещает `README.md`, `AGENTS.md`, `CLAUDE.md`, license и community files;
|
||||||
20. normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи.
|
20. normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи;
|
||||||
|
21. `adopt --mode plan` отказывается строиться без подтверждённого owner и при неразрешённой находке severity `error`;
|
||||||
|
22. содержимое secret-shaped файла может читаться для классификации, но значения не попадают ни в один вывод;
|
||||||
|
23. content roots предлагаются по всему словарю содержимого, а не только по маркерам предложенного type;
|
||||||
|
24. репозиторий из однотипных каталогов объявляется одним `file-set` корнем с селектором, а не N директориями.
|
||||||
|
|
||||||
## 25. Сквозной пример contract: infrastructure provider
|
## 25. Сквозной пример contract: infrastructure provider
|
||||||
|
|
||||||
|
|||||||
@@ -69,11 +69,13 @@ spec:
|
|||||||
- 3. Safety invariants
|
- 3. Safety invariants
|
||||||
- 6. Phase 1 — preflight
|
- 6. Phase 1 — preflight
|
||||||
- 7. Phase 2 — assessment
|
- 7. Phase 2 — assessment
|
||||||
|
- 9. Phase 3 — confirmation boundary
|
||||||
- 10. Phase 4 — adoption plan
|
- 10. Phase 4 — adoption plan
|
||||||
- 11. Compatibility rules
|
- 11. Compatibility rules
|
||||||
- 11.5. Normalization recipe documents-to-content-root
|
- 11.5. Normalization recipe documents-to-content-root
|
||||||
- 12. Phase 5 — apply
|
- 12. Phase 5 — apply
|
||||||
- 13. Phase 6 — verify
|
- 13. Phase 6 — verify
|
||||||
|
- 14. Finding codes
|
||||||
- id: stewardship-model
|
- id: stewardship-model
|
||||||
title: Understand or evolve the model
|
title: Understand or evolve the model
|
||||||
summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship
|
summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship
|
||||||
|
|||||||
+335
-39
@@ -125,6 +125,28 @@ _SECRET_BINARY_SUFFIXES = (
|
|||||||
".zip", ".gz", ".tar", ".7z", ".xz", ".mp4", ".exe", ".msi",
|
".zip", ".gz", ".tar", ".7z", ".xz", ".mp4", ".exe", ".msi",
|
||||||
)
|
)
|
||||||
_SECRET_SKIP_DIRS = {".git", ".venv", "node_modules", "__pycache__"}
|
_SECRET_SKIP_DIRS = {".git", ".venv", "node_modules", "__pycache__"}
|
||||||
|
# Reading content is what separates a credential from a document about
|
||||||
|
# credentials. Runbook 7.3 allows recording *keys* without emitting values, so
|
||||||
|
# these patterns are only ever used to produce key names.
|
||||||
|
_SECRET_KEY_RE = re.compile(
|
||||||
|
r"^[ \t]*(?:export[ \t]+)?(?P<key>"
|
||||||
|
# Words that name a credential wherever they appear in the key.
|
||||||
|
r"[A-Za-z0-9_.\-]*(?:PASSWORD|PASSWD|PASSPHRASE|SECRET|TOKEN|CREDENTIAL)[A-Za-z0-9_.\-]*"
|
||||||
|
r"|"
|
||||||
|
# "KEY" only as a suffix: AIRFLOW_FERNET_KEY is a credential, KEY_PATH and
|
||||||
|
# KEYBOARD_LAYOUT are not, and a bare substring match cannot tell them apart.
|
||||||
|
r"(?:[A-Za-z0-9_.\-]*[_.\-](?:KEY|APIKEY)|KEY|APIKEY)"
|
||||||
|
r")[ \t]*[:=][ \t]*(?P<value>\S.*)$",
|
||||||
|
re.IGNORECASE | re.MULTILINE,
|
||||||
|
)
|
||||||
|
_PEM_RE = re.compile(r"-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----")
|
||||||
|
_PLACEHOLDER_VALUES = {
|
||||||
|
"changeme", "change-me", "change_me", "example", "placeholder", "redacted",
|
||||||
|
"todo", "tbd", "xxx", "none", "null", "unset", "secret", "password",
|
||||||
|
}
|
||||||
|
# A credential large enough to matter is never in a multi-megabyte file, and
|
||||||
|
# reading one to decide would make assess proportional to repository size.
|
||||||
|
_SECRET_CONTENT_MAX_BYTES = 256 * 1024
|
||||||
|
|
||||||
# Weighted because presence alone is weak evidence: `docs/` exists in almost
|
# Weighted because presence alone is weak evidence: `docs/` exists in almost
|
||||||
# every repository and must not outvote a marker that actually identifies the
|
# every repository and must not outvote a marker that actually identifies the
|
||||||
@@ -162,8 +184,27 @@ _CONTENT_ROOT_SPECS: dict[str, dict[str, Any]] = {
|
|||||||
"deliverables": {"role": "deliverables", "authority": "source", "writePolicy": "managed"},
|
"deliverables": {"role": "deliverables", "authority": "source", "writePolicy": "managed"},
|
||||||
"decisions": {"role": "decisions", "authority": "source", "writePolicy": "managed"},
|
"decisions": {"role": "decisions", "authority": "source", "writePolicy": "managed"},
|
||||||
"docs": {"role": "documentation", "authority": "source", "writePolicy": "managed"},
|
"docs": {"role": "documentation", "authority": "source", "writePolicy": "managed"},
|
||||||
|
"scripts": {"role": "automation", "authority": "source", "writePolicy": "managed"},
|
||||||
|
"services": {"role": "services", "authority": "source", "writePolicy": "managed"},
|
||||||
|
"apps": {"role": "apps", "authority": "source", "writePolicy": "managed"},
|
||||||
|
"templates": {"role": "templates", "authority": "source", "writePolicy": "managed"},
|
||||||
|
"projects": {"role": "projects", "authority": "source", "writePolicy": "managed"},
|
||||||
}
|
}
|
||||||
|
|
||||||
|
# Runbook 7.2 declares a repository of sibling stack directories as one file-set
|
||||||
|
# root with a selector, not as N directory roots. Recognising the shape needs a
|
||||||
|
# marker the siblings share; a lone directory carrying one proves nothing.
|
||||||
|
_REPEATED_SHAPE_MARKERS: list[tuple[str, str, str]] = [
|
||||||
|
("compose.yaml", "*/compose.y*ml", "stacks"),
|
||||||
|
("compose.yml", "*/compose.y*ml", "stacks"),
|
||||||
|
("docker-compose.yaml", "*/docker-compose.y*ml", "stacks"),
|
||||||
|
("docker-compose.yml", "*/docker-compose.y*ml", "stacks"),
|
||||||
|
("Chart.yaml", "*/Chart.yaml", "charts"),
|
||||||
|
("main.tf", "*/main.tf", "desired"),
|
||||||
|
("Dockerfile", "*/Dockerfile", "images"),
|
||||||
|
]
|
||||||
|
_REPEATED_SHAPE_MIN_SIBLINGS = 3
|
||||||
|
|
||||||
|
|
||||||
def _finding(severity: str, code: str, path: str | None = None, message: str | None = None) -> dict[str, Any]:
|
def _finding(severity: str, code: str, path: str | None = None, message: str | None = None) -> dict[str, Any]:
|
||||||
item: dict[str, Any] = {"severity": severity, "code": code}
|
item: dict[str, Any] = {"severity": severity, "code": code}
|
||||||
@@ -174,6 +215,44 @@ def _finding(severity: str, code: str, path: str | None = None, message: str | N
|
|||||||
return item
|
return item
|
||||||
|
|
||||||
|
|
||||||
|
def _is_placeholder(value: str) -> bool:
|
||||||
|
"""True when an assignment's value is a stand-in rather than a live credential."""
|
||||||
|
value = value.strip().split("#", 1)[0].strip().strip("\"'").strip()
|
||||||
|
if not value:
|
||||||
|
return True
|
||||||
|
# `<SECRET:name>`, `${VAR}` and `{{ var }}` are all "filled in elsewhere".
|
||||||
|
if value.startswith(("<", "${", "{{")):
|
||||||
|
return True
|
||||||
|
return value.lower() in _PLACEHOLDER_VALUES
|
||||||
|
|
||||||
|
|
||||||
|
def _secret_content_evidence(path: Path) -> list[str]:
|
||||||
|
"""Return the *names* of credential-shaped keys carrying a real value.
|
||||||
|
|
||||||
|
Never returns, logs or stores a value: the caller puts this straight into a
|
||||||
|
finding message, and a scanner that leaks the secret it found is worse than
|
||||||
|
no scanner. Unreadable, oversized and binary files yield nothing rather than
|
||||||
|
raising, because assess must survive whatever an existing repository holds.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
if path.stat().st_size > _SECRET_CONTENT_MAX_BYTES:
|
||||||
|
return []
|
||||||
|
text = path.read_text(encoding="utf-8", errors="ignore")
|
||||||
|
except OSError:
|
||||||
|
return []
|
||||||
|
|
||||||
|
keys: list[str] = []
|
||||||
|
if _PEM_RE.search(text):
|
||||||
|
keys.append("PEM private key block")
|
||||||
|
for match in _SECRET_KEY_RE.finditer(text):
|
||||||
|
if _is_placeholder(match.group("value")):
|
||||||
|
continue
|
||||||
|
key = match.group("key")
|
||||||
|
if key not in keys:
|
||||||
|
keys.append(key)
|
||||||
|
return keys
|
||||||
|
|
||||||
|
|
||||||
def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, str]]:
|
def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, str]]:
|
||||||
"""Return (relative_path, "tracked" | "untracked") for secret-shaped filenames.
|
"""Return (relative_path, "tracked" | "untracked") for secret-shaped filenames.
|
||||||
|
|
||||||
@@ -212,6 +291,66 @@ def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, str]]:
|
|||||||
]
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def _classify_secret_paths(root: Path) -> list[dict[str, Any]]:
|
||||||
|
"""Sort secret-shaped paths into what is actually known about each one.
|
||||||
|
|
||||||
|
A single blocker keyed on the filename made 14 of 16 findings in a real
|
||||||
|
repository false, and taught the reader to skip all of them. The three
|
||||||
|
classes say different things and deserve different severities: content that
|
||||||
|
really is a credential blocks; a name-only match and a file committed
|
||||||
|
against the repository's own ignore rules are warnings worth acting on.
|
||||||
|
"""
|
||||||
|
candidates = _detect_secret_shaped_paths(root)
|
||||||
|
tracked_paths = [rel for rel, status in candidates if status == "tracked"]
|
||||||
|
# Without --no-index Git stays silent about tracked paths, which is exactly
|
||||||
|
# the contradiction being looked for here.
|
||||||
|
rule_matched = gitutil.ignored(root, tracked_paths, no_index=True)
|
||||||
|
|
||||||
|
findings: list[dict[str, Any]] = []
|
||||||
|
for rel, status in candidates:
|
||||||
|
if status != "tracked":
|
||||||
|
findings.append(
|
||||||
|
_finding(
|
||||||
|
"info",
|
||||||
|
"ADOPT_SECRET_SHAPED_UNTRACKED",
|
||||||
|
rel,
|
||||||
|
"Untracked and unignored secret-shaped path (path only, content not read)",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
if rel in rule_matched:
|
||||||
|
findings.append(
|
||||||
|
_finding(
|
||||||
|
"warning",
|
||||||
|
"ADOPT_SECRET_IGNORED_BUT_TRACKED",
|
||||||
|
rel,
|
||||||
|
"Tracked although the repository's own ignore rules exclude it",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
keys = _secret_content_evidence(root / rel)
|
||||||
|
if keys:
|
||||||
|
findings.append(
|
||||||
|
_finding(
|
||||||
|
"error",
|
||||||
|
"ADOPT_SECRET_CONTENT_VERIFIED",
|
||||||
|
rel,
|
||||||
|
"Credential-shaped assignment with a live value: " + ", ".join(keys),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
elif rel not in rule_matched:
|
||||||
|
findings.append(
|
||||||
|
_finding(
|
||||||
|
"warning",
|
||||||
|
"ADOPT_SECRET_NAME_SHAPED",
|
||||||
|
rel,
|
||||||
|
"Filename matches a secret-shaped pattern; content carries no credential",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
return findings
|
||||||
|
|
||||||
|
|
||||||
def _knowledge_format(path: Path) -> str:
|
def _knowledge_format(path: Path) -> str:
|
||||||
"""Return ``stewardship-yaml`` only when the file really is a KnowledgeBase.
|
"""Return ``stewardship-yaml`` only when the file really is a KnowledgeBase.
|
||||||
|
|
||||||
@@ -235,6 +374,111 @@ def _knowledge_entry(root: Path, rel: str) -> dict[str, str]:
|
|||||||
return {"path": rel, "format": fmt, "action": action}
|
return {"path": rel, "format": fmt, "action": action}
|
||||||
|
|
||||||
|
|
||||||
|
_NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$")
|
||||||
|
|
||||||
|
|
||||||
|
def _slug(*parts: str) -> str | None:
|
||||||
|
"""Join ``parts`` into a contract-legal ``metadata.name``, or None if impossible."""
|
||||||
|
joined = "-".join(part for part in parts if part)
|
||||||
|
slug = re.sub(r"[^a-z0-9]+", "-", joined.lower()).strip("-")
|
||||||
|
slug = re.sub(r"-{2,}", "-", slug)
|
||||||
|
return slug if slug and _NAME_RE.match(slug) else None
|
||||||
|
|
||||||
|
|
||||||
|
def _proposed_identity(root: Path) -> dict[str, str]:
|
||||||
|
"""Propose a repository name from the remote, falling back to the directory.
|
||||||
|
|
||||||
|
The directory basename is not an identity: it is wherever this clone happens
|
||||||
|
to sit, so two clones of one repository disagree and a worktree invents a
|
||||||
|
third answer. The remote path is something the owner chose. Two segments are
|
||||||
|
kept because the last one alone ("lxd", "docker") collides across groups.
|
||||||
|
"""
|
||||||
|
url = gitutil.remote_url(root)
|
||||||
|
if url:
|
||||||
|
path = re.sub(r"\.git$", "", url.split("#", 1)[0].rstrip("/"))
|
||||||
|
# Both ssh://host:port/a/b and scp-style host:a/b reduce to their segments.
|
||||||
|
segments = [seg for seg in re.split(r"[/:]", path) if seg]
|
||||||
|
name = _slug(*segments[-2:]) or _slug(*segments[-1:])
|
||||||
|
if name:
|
||||||
|
return {"name": name, "source": "git-remote"}
|
||||||
|
fallback = _slug(root.name) or "adopted-repository"
|
||||||
|
return {"name": fallback, "source": "directory"}
|
||||||
|
|
||||||
|
|
||||||
|
def _repeated_shape_root(root: Path, taken: set[str]) -> dict[str, Any] | None:
|
||||||
|
"""Propose one file-set root for N sibling directories sharing a marker file.
|
||||||
|
|
||||||
|
A repository holding a directory per stack has no single directory to point
|
||||||
|
at, and enumerating twenty of them describes the layout rather than the
|
||||||
|
content. Runbook 7.2 states the intended shape directly: `path: "."`,
|
||||||
|
`kind: file-set`, and a selector.
|
||||||
|
"""
|
||||||
|
directories = sorted(
|
||||||
|
entry.name
|
||||||
|
for entry in root.iterdir()
|
||||||
|
if entry.is_dir() and not entry.name.startswith(".") and entry.name not in taken
|
||||||
|
)
|
||||||
|
for marker, selector, role in _REPEATED_SHAPE_MARKERS:
|
||||||
|
members = [name for name in directories if (root / name / marker).is_file()]
|
||||||
|
if len(members) < _REPEATED_SHAPE_MIN_SIBLINGS:
|
||||||
|
continue
|
||||||
|
return {
|
||||||
|
"id": _slug(role) or "stacks",
|
||||||
|
"path": ".",
|
||||||
|
"role": role,
|
||||||
|
"kind": "file-set",
|
||||||
|
"selector": selector,
|
||||||
|
"authority": "source",
|
||||||
|
"writePolicy": "managed",
|
||||||
|
}
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _propose_content_roots(root: Path) -> list[dict[str, Any]]:
|
||||||
|
"""Propose content roots from every vocabulary, not only the winning type's.
|
||||||
|
|
||||||
|
Scoping the search to the proposed type meant an infrastructure repository
|
||||||
|
never had its `docs/` declared, because `docs` happens to be listed as
|
||||||
|
evidence for `project`. Type and content roots answer different questions:
|
||||||
|
what the repository is for, and what it actually holds.
|
||||||
|
"""
|
||||||
|
# Two different vocabularies: _TYPE_EVIDENCE says what a repository is for,
|
||||||
|
# _CONTENT_ROOT_SPECS says how a directory should be declared. A directory
|
||||||
|
# can be worth declaring without being evidence of any type.
|
||||||
|
markers = sorted(
|
||||||
|
{marker for _type, table in _TYPE_EVIDENCE for marker in table} | set(_CONTENT_ROOT_SPECS)
|
||||||
|
)
|
||||||
|
proposed: list[dict[str, Any]] = []
|
||||||
|
claimed: set[str] = set()
|
||||||
|
for marker in markers:
|
||||||
|
if not (root / marker).is_dir():
|
||||||
|
continue
|
||||||
|
spec = _CONTENT_ROOT_SPECS.get(
|
||||||
|
marker, {"role": marker, "authority": "source", "writePolicy": "managed"}
|
||||||
|
)
|
||||||
|
entry: dict[str, Any] = {
|
||||||
|
"id": marker.replace("/", "-").lower(),
|
||||||
|
"path": marker,
|
||||||
|
"role": spec["role"],
|
||||||
|
"kind": "directory",
|
||||||
|
"authority": spec["authority"],
|
||||||
|
"writePolicy": spec["writePolicy"],
|
||||||
|
}
|
||||||
|
sources = spec.get("generatedFrom") or []
|
||||||
|
if sources and all((root / source).exists() for source in sources):
|
||||||
|
entry["generatedFrom"] = [source.replace("/", "-").lower() for source in sources]
|
||||||
|
elif sources:
|
||||||
|
# Nothing generates it here, so it is the source in this repository.
|
||||||
|
entry.update(authority="source", writePolicy="managed", role=marker)
|
||||||
|
proposed.append(entry)
|
||||||
|
claimed.add(marker)
|
||||||
|
|
||||||
|
repeated = _repeated_shape_root(root, claimed)
|
||||||
|
if repeated and not any(entry["id"] == repeated["id"] for entry in proposed):
|
||||||
|
proposed.append(repeated)
|
||||||
|
return proposed
|
||||||
|
|
||||||
|
|
||||||
def _classify_type(root: Path) -> tuple[str, str, list[str], bool]:
|
def _classify_type(root: Path) -> tuple[str, str, list[str], bool]:
|
||||||
"""Propose a repository type, its confidence, its evidence, and whether it tied.
|
"""Propose a repository type, its confidence, its evidence, and whether it tied.
|
||||||
|
|
||||||
@@ -300,33 +544,21 @@ def assess(root: Path) -> dict[str, Any]:
|
|||||||
if entry["action"] == "wrap":
|
if entry["action"] == "wrap":
|
||||||
findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
|
findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
|
||||||
|
|
||||||
proposed_content_roots: list[dict[str, Any]] = []
|
proposed_content_roots = _propose_content_roots(root)
|
||||||
for repo_type, markers in _TYPE_EVIDENCE:
|
for content_root in proposed_content_roots:
|
||||||
if repo_type != proposed_type:
|
if content_root.get("authority") == "source" and not content_root.get("generatedFrom"):
|
||||||
continue
|
# Runbook 7.2: calling a generated mirror a source is the named
|
||||||
for marker in sorted(markers):
|
# mistake. Where the pairing is not evidenced by a generatedFrom
|
||||||
candidate = root / marker
|
# partner, "source" is this table's default rather than a finding
|
||||||
if not candidate.is_dir():
|
# about this repository, and the owner has to say which it is.
|
||||||
continue
|
findings.append(
|
||||||
spec = _CONTENT_ROOT_SPECS.get(
|
_finding(
|
||||||
marker, {"role": marker, "authority": "source", "writePolicy": "managed"}
|
"warning",
|
||||||
|
"ADOPT_SOURCE_MIRROR_AMBIGUOUS",
|
||||||
|
content_root["path"],
|
||||||
|
"Authority defaulted to source; confirm it is not a generated mirror",
|
||||||
|
)
|
||||||
)
|
)
|
||||||
content_root: dict[str, Any] = {
|
|
||||||
"id": marker.replace("/", "-").lower(),
|
|
||||||
"path": marker,
|
|
||||||
"role": spec["role"],
|
|
||||||
"authority": spec["authority"],
|
|
||||||
"writePolicy": spec["writePolicy"],
|
|
||||||
}
|
|
||||||
sources = spec.get("generatedFrom") or []
|
|
||||||
if sources and all((root / source).exists() for source in sources):
|
|
||||||
content_root["generatedFrom"] = [
|
|
||||||
source.replace("/", "-").lower() for source in sources
|
|
||||||
]
|
|
||||||
elif sources:
|
|
||||||
# Nothing generates it here, so it is the source in this repository.
|
|
||||||
content_root.update(authority="source", writePolicy="managed", role=marker)
|
|
||||||
proposed_content_roots.append(content_root)
|
|
||||||
|
|
||||||
collisions: list[str] = []
|
collisions: list[str] = []
|
||||||
for rel in _COLLISION_PATHS:
|
for rel in _COLLISION_PATHS:
|
||||||
@@ -335,18 +567,7 @@ def assess(root: Path) -> dict[str, Any]:
|
|||||||
if (root / "kdb" / "kdb.yaml").exists() and (root / "kdb.yaml").exists():
|
if (root / "kdb" / "kdb.yaml").exists() and (root / "kdb.yaml").exists():
|
||||||
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
|
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
|
||||||
|
|
||||||
for rel, status in _detect_secret_shaped_paths(root):
|
findings.extend(_classify_secret_paths(root))
|
||||||
if status == "tracked":
|
|
||||||
findings.append(_finding("error", "ADOPT_SECRET_TRACKED", rel, "Tracked path matches a secret-shaped filename pattern"))
|
|
||||||
else:
|
|
||||||
findings.append(
|
|
||||||
_finding(
|
|
||||||
"info",
|
|
||||||
"ADOPT_SECRET_SHAPED_UNTRACKED",
|
|
||||||
rel,
|
|
||||||
"Untracked and unignored secret-shaped path (path only, content not read)",
|
|
||||||
)
|
|
||||||
)
|
|
||||||
|
|
||||||
if dirty:
|
if dirty:
|
||||||
findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY"))
|
findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY"))
|
||||||
@@ -356,15 +577,36 @@ def assess(root: Path) -> dict[str, Any]:
|
|||||||
_finding("warning", "ADOPT_TYPE_AMBIGUOUS", None, f"Type evidence ties with {proposed_type}")
|
_finding("warning", "ADOPT_TYPE_AMBIGUOUS", None, f"Type evidence ties with {proposed_type}")
|
||||||
)
|
)
|
||||||
|
|
||||||
|
identity = _proposed_identity(root)
|
||||||
|
if identity["source"] == "directory":
|
||||||
|
findings.append(
|
||||||
|
_finding(
|
||||||
|
"info",
|
||||||
|
"ADOPT_NAME_INFERRED",
|
||||||
|
None,
|
||||||
|
f"No git remote; name {identity['name']!r} inferred from the directory",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
# Runbook section 9 lists owner among the answers that cannot be derived, so
|
||||||
|
# assess always asks. `plan` is where the refusal lives; failing assess on a
|
||||||
|
# question it exists to raise would make the read-only step unusable.
|
||||||
|
findings.append(
|
||||||
|
_finding("warning", "ADOPT_OWNER_UNKNOWN", None, "Owner is not confirmed yet")
|
||||||
|
)
|
||||||
|
|
||||||
questions: list[str] = []
|
questions: list[str] = []
|
||||||
confirmation_required = confidence != "high"
|
confirmation_required = confidence != "high"
|
||||||
if confirmation_required:
|
if confirmation_required:
|
||||||
questions.append("Confirm repository type and confidence evidence")
|
questions.append("Confirm repository type and confidence evidence")
|
||||||
questions.append("Confirm owner(s) and lifecycle")
|
questions.append("Confirm owner(s) and lifecycle")
|
||||||
|
questions.append(f"Confirm repository name (proposed {identity['name']!r} from {identity['source']})")
|
||||||
|
if any(f["code"] == "ADOPT_SOURCE_MIRROR_AMBIGUOUS" for f in findings):
|
||||||
|
questions.append("Confirm which content roots are sources and which are generated mirrors")
|
||||||
|
|
||||||
return {
|
return {
|
||||||
"schema": "stewardship/adoption-assessment@0.1",
|
"schema": "stewardship/adoption-assessment@0.1",
|
||||||
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
|
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
|
||||||
|
"identity": identity,
|
||||||
"classification": {
|
"classification": {
|
||||||
"proposedType": proposed_type,
|
"proposedType": proposed_type,
|
||||||
"confidence": confidence,
|
"confidence": confidence,
|
||||||
@@ -535,10 +777,52 @@ def build_plan(
|
|||||||
confirmed_lifecycle: str = "active",
|
confirmed_lifecycle: str = "active",
|
||||||
confirmed_type: str | None = None,
|
confirmed_type: str | None = None,
|
||||||
strategy: str = "overlay",
|
strategy: str = "overlay",
|
||||||
|
acknowledged: list[dict[str, Any]] | None = None,
|
||||||
) -> dict[str, Any]:
|
) -> dict[str, Any]:
|
||||||
if strategy != "overlay":
|
if strategy != "overlay":
|
||||||
raise ValueError("Only the overlay strategy is implemented; normalize requires an explicit recipe run")
|
raise ValueError("Only the overlay strategy is implemented; normalize requires an explicit recipe run")
|
||||||
|
|
||||||
|
if not confirmed_owners:
|
||||||
|
# Runbook section 9: owner is one of the answers adoption cannot derive.
|
||||||
|
# Emitting `owners: []` produced a contract that looked confirmed while
|
||||||
|
# nobody had answered, which is worse than refusing to build one.
|
||||||
|
raise AdoptionError(
|
||||||
|
"ADOPT_OWNER_UNKNOWN",
|
||||||
|
"Owners must be confirmed before a plan can be built (--owner, or owners: in --answers)",
|
||||||
|
)
|
||||||
|
|
||||||
|
# Questions the plan's own answers settle must not be carried forward as if
|
||||||
|
# they were still open: reaching this point means an owner was confirmed.
|
||||||
|
assessment_findings = [
|
||||||
|
dict(f) for f in assessment.get("findings", []) if f["code"] != "ADOPT_OWNER_UNKNOWN"
|
||||||
|
]
|
||||||
|
acknowledgements = [dict(item) for item in (acknowledged or [])]
|
||||||
|
for item in acknowledgements:
|
||||||
|
if not item.get("code") or not str(item.get("reason", "")).strip():
|
||||||
|
raise AdoptionError(
|
||||||
|
"ADOPT_ACKNOWLEDGEMENT_INCOMPLETE",
|
||||||
|
"Each acknowledged finding needs a code and a reason",
|
||||||
|
)
|
||||||
|
acknowledged_keys = {(item["code"], item.get("path")) for item in acknowledgements}
|
||||||
|
unresolved = [
|
||||||
|
f
|
||||||
|
for f in assessment_findings
|
||||||
|
if f["severity"] == "error"
|
||||||
|
and (f["code"], f.get("path")) not in acknowledged_keys
|
||||||
|
and (f["code"], None) not in acknowledged_keys
|
||||||
|
]
|
||||||
|
if unresolved:
|
||||||
|
# `assess` used to report a blocker and `plan` then returned success with
|
||||||
|
# an empty findings list, so the one hard result of the whole run was
|
||||||
|
# silently dropped one step later.
|
||||||
|
detail = ", ".join(
|
||||||
|
f"{f['code']}({f['path']})" if f.get("path") else f["code"] for f in unresolved
|
||||||
|
)
|
||||||
|
raise AdoptionError(
|
||||||
|
"ADOPT_ASSESS_BLOCKERS_UNRESOLVED",
|
||||||
|
f"assess left {len(unresolved)} unresolved error finding(s): {detail}",
|
||||||
|
)
|
||||||
|
|
||||||
baseline = assessment["repository"]["baselineRevision"]
|
baseline = assessment["repository"]["baselineRevision"]
|
||||||
classification = assessment["classification"]
|
classification = assessment["classification"]
|
||||||
repository_type = confirmed_type or classification["proposedType"]
|
repository_type = confirmed_type or classification["proposedType"]
|
||||||
@@ -563,14 +847,21 @@ def build_plan(
|
|||||||
"id": cr["id"],
|
"id": cr["id"],
|
||||||
"role": cr["role"],
|
"role": cr["role"],
|
||||||
"path": cr["path"],
|
"path": cr["path"],
|
||||||
"kind": "directory",
|
"kind": cr.get("kind", "directory"),
|
||||||
"authority": cr.get("authority", "source"),
|
"authority": cr.get("authority", "source"),
|
||||||
"writePolicy": cr.get("writePolicy", "managed"),
|
"writePolicy": cr.get("writePolicy", "managed"),
|
||||||
}
|
}
|
||||||
|
if cr.get("selector"):
|
||||||
|
entry["selector"] = cr["selector"]
|
||||||
if cr.get("generatedFrom"):
|
if cr.get("generatedFrom"):
|
||||||
entry["generatedFrom"] = cr["generatedFrom"]
|
entry["generatedFrom"] = cr["generatedFrom"]
|
||||||
content_roots.append(entry)
|
content_roots.append(entry)
|
||||||
for cr in content_roots:
|
for cr in content_roots:
|
||||||
|
# A file-set root sits at `.` with a selector; `./**` would forbid the
|
||||||
|
# whole repository, including the paths this plan has to write.
|
||||||
|
if cr.get("selector"):
|
||||||
|
forbidden.append(cr["selector"])
|
||||||
|
else:
|
||||||
forbidden.append(f"{cr['path']}/**")
|
forbidden.append(f"{cr['path']}/**")
|
||||||
|
|
||||||
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
|
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
|
||||||
@@ -664,6 +955,9 @@ def build_plan(
|
|||||||
"baselineRevision": baseline,
|
"baselineRevision": baseline,
|
||||||
"strategy": strategy,
|
"strategy": strategy,
|
||||||
"changes": changes,
|
"changes": changes,
|
||||||
|
# Carried so the plan is self-contained evidence of what assess saw, and
|
||||||
|
# so an acknowledgement is covered by planHash and therefore by approval.
|
||||||
|
"findings": assessment_findings,
|
||||||
"forbiddenChanges": sorted(set(forbidden)),
|
"forbiddenChanges": sorted(set(forbidden)),
|
||||||
"validations": [
|
"validations": [
|
||||||
"stewardship-schema",
|
"stewardship-schema",
|
||||||
@@ -673,6 +967,8 @@ def build_plan(
|
|||||||
],
|
],
|
||||||
"approval": {"required": True},
|
"approval": {"required": True},
|
||||||
}
|
}
|
||||||
|
if acknowledgements:
|
||||||
|
plan["acknowledgedFindings"] = acknowledgements
|
||||||
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||||
plan["planHash"] = plan_hash
|
plan["planHash"] = plan_hash
|
||||||
return plan
|
return plan
|
||||||
|
|||||||
@@ -7,6 +7,7 @@ domain artifacts. `init` never commits, pushes or creates a remote.
|
|||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import re
|
||||||
import subprocess
|
import subprocess
|
||||||
from dataclasses import dataclass
|
from dataclasses import dataclass
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
@@ -14,7 +15,14 @@ from typing import Any
|
|||||||
|
|
||||||
from . import io
|
from . import io
|
||||||
from .clock import DEFAULT_CLOCK
|
from .clock import DEFAULT_CLOCK
|
||||||
from .constants import API_VERSION
|
from .constants import (
|
||||||
|
ACCESS_VALUES,
|
||||||
|
API_VERSION,
|
||||||
|
ID_PATTERN,
|
||||||
|
LIFECYCLES,
|
||||||
|
REPOSITORY_TYPES,
|
||||||
|
)
|
||||||
|
from .paths import PathViolation, confined_path
|
||||||
from .skills_content import (
|
from .skills_content import (
|
||||||
REPO_HANDOFF_SKILL,
|
REPO_HANDOFF_SKILL,
|
||||||
REPOSITORY_ADOPTION_SKILL,
|
REPOSITORY_ADOPTION_SKILL,
|
||||||
@@ -56,6 +64,80 @@ SSH_RECOMMENDATION = (
|
|||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class BootstrapError(ValueError):
|
||||||
|
"""`init` refused to proceed, carrying a stable finding code.
|
||||||
|
|
||||||
|
Mirrors ``adoption.AdoptionError``: without a code the CLI can only print a
|
||||||
|
message, which breaks the machine-readable contract `--output json` makes.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, code: str, message: str) -> None:
|
||||||
|
super().__init__(f"{code}: {message}")
|
||||||
|
self.code = code
|
||||||
|
|
||||||
|
|
||||||
|
_NAME_RE = re.compile(ID_PATTERN)
|
||||||
|
|
||||||
|
|
||||||
|
def _suggest_name(value: str) -> str | None:
|
||||||
|
"""Offer a legal name for a rejected one, so the error is actionable."""
|
||||||
|
slug = re.sub(r"[^a-z0-9]+", "-", str(value).lower()).strip("-")
|
||||||
|
slug = re.sub(r"-{2,}", "-", slug)
|
||||||
|
return slug if slug and _NAME_RE.match(slug) else None
|
||||||
|
|
||||||
|
|
||||||
|
def validate_answers(data: dict[str, Any]) -> None:
|
||||||
|
"""Reject answers that would produce a repository failing `repoctl validate`.
|
||||||
|
|
||||||
|
`init` is the one path where the tool controls every byte it writes, so
|
||||||
|
emitting a contract that does not match its own schema has no excuse. The
|
||||||
|
vocabularies live in `constants` and were simply never consulted here.
|
||||||
|
"""
|
||||||
|
missing = [field for field in ("name", "repositoryType") if not data.get(field)]
|
||||||
|
if missing:
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_ANSWERS_INCOMPLETE", f"Missing required answers: {', '.join(missing)}"
|
||||||
|
)
|
||||||
|
|
||||||
|
name = data["name"]
|
||||||
|
if not isinstance(name, str) or not _NAME_RE.match(name):
|
||||||
|
suggestion = _suggest_name(name)
|
||||||
|
hint = f"; use {suggestion!r}" if suggestion else ""
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_NAME_INVALID",
|
||||||
|
f"Repository name {name!r} does not match {ID_PATTERN}{hint}",
|
||||||
|
)
|
||||||
|
|
||||||
|
if data["repositoryType"] not in REPOSITORY_TYPES:
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_TYPE_UNKNOWN",
|
||||||
|
f"Unknown repository type {data['repositoryType']!r}; expected one of "
|
||||||
|
+ ", ".join(sorted(REPOSITORY_TYPES)),
|
||||||
|
)
|
||||||
|
|
||||||
|
lifecycle = data.get("lifecycle", "active")
|
||||||
|
if lifecycle not in LIFECYCLES:
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_LIFECYCLE_UNKNOWN",
|
||||||
|
f"Unknown lifecycle {lifecycle!r}; expected one of " + ", ".join(sorted(LIFECYCLES)),
|
||||||
|
)
|
||||||
|
|
||||||
|
access = data.get("access")
|
||||||
|
if access is not None and access not in ACCESS_VALUES:
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_ACCESS_UNKNOWN",
|
||||||
|
f"Unknown access {access!r}; expected one of " + ", ".join(sorted(ACCESS_VALUES)),
|
||||||
|
)
|
||||||
|
|
||||||
|
# The same confirmation boundary `adopt` enforces. Which command created the
|
||||||
|
# contract does not change the fact that nobody answered the owner question.
|
||||||
|
if not data.get("owners"):
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_OWNER_UNKNOWN",
|
||||||
|
"Owners must be confirmed before a plan can be built (--owner, or owners: in --answers)",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
@dataclass
|
@dataclass
|
||||||
class BootstrapAnswers:
|
class BootstrapAnswers:
|
||||||
name: str
|
name: str
|
||||||
@@ -71,6 +153,7 @@ class BootstrapAnswers:
|
|||||||
|
|
||||||
@staticmethod
|
@staticmethod
|
||||||
def from_mapping(data: dict[str, Any]) -> BootstrapAnswers:
|
def from_mapping(data: dict[str, Any]) -> BootstrapAnswers:
|
||||||
|
validate_answers(data)
|
||||||
return BootstrapAnswers(
|
return BootstrapAnswers(
|
||||||
name=data["name"],
|
name=data["name"],
|
||||||
title=data.get("title", data["name"]),
|
title=data.get("title", data["name"]),
|
||||||
@@ -185,7 +268,14 @@ def _render_gitignore() -> str:
|
|||||||
return "ops/runs/\n.venv/\n__pycache__/\n"
|
return "ops/runs/\n.venv/\n__pycache__/\n"
|
||||||
|
|
||||||
|
|
||||||
def build_bootstrap_plan(answers: BootstrapAnswers) -> dict[str, Any]:
|
def build_bootstrap_plan(answers: BootstrapAnswers, root: Path | None = None) -> dict[str, Any]:
|
||||||
|
"""Build the plan, refusing up front what `apply` would refuse anyway.
|
||||||
|
|
||||||
|
``root`` is optional only so existing callers that plan without a target keep
|
||||||
|
working. When it is given, a path the repository already holds is reported
|
||||||
|
here rather than after the owner has read and approved a plan that could
|
||||||
|
never be applied.
|
||||||
|
"""
|
||||||
contract_text = _render_contract(answers)
|
contract_text = _render_contract(answers)
|
||||||
files = [
|
files = [
|
||||||
{"path": "ops/contract.yaml", "content": contract_text},
|
{"path": "ops/contract.yaml", "content": contract_text},
|
||||||
@@ -198,6 +288,16 @@ def build_bootstrap_plan(answers: BootstrapAnswers) -> dict[str, Any]:
|
|||||||
{"path": ".claude/skills/repository-adoption/SKILL.md", "content": REPOSITORY_ADOPTION_SKILL},
|
{"path": ".claude/skills/repository-adoption/SKILL.md", "content": REPOSITORY_ADOPTION_SKILL},
|
||||||
{"path": ".claude/skills/repo-handoff/SKILL.md", "content": REPO_HANDOFF_SKILL},
|
{"path": ".claude/skills/repo-handoff/SKILL.md", "content": REPO_HANDOFF_SKILL},
|
||||||
]
|
]
|
||||||
|
if root is not None:
|
||||||
|
occupied = [entry["path"] for entry in files if (root / entry["path"]).exists()]
|
||||||
|
if occupied:
|
||||||
|
raise BootstrapError(
|
||||||
|
"INIT_PATH_COLLISION",
|
||||||
|
"Repository already holds paths this plan would create: "
|
||||||
|
+ ", ".join(occupied)
|
||||||
|
+ ". Use `repoctl adopt` for an existing repository.",
|
||||||
|
)
|
||||||
|
|
||||||
plan: dict[str, Any] = {
|
plan: dict[str, Any] = {
|
||||||
"schema": "stewardship/bootstrap-plan@0.1",
|
"schema": "stewardship/bootstrap-plan@0.1",
|
||||||
"repository": answers.name,
|
"repository": answers.name,
|
||||||
@@ -219,15 +319,25 @@ def apply_bootstrap_plan(root: Path, plan: dict[str, Any], approve_hash: str) ->
|
|||||||
if approve_hash != plan["planHash"]:
|
if approve_hash != plan["planHash"]:
|
||||||
raise ValueError("Approval hash does not match plan hash")
|
raise ValueError("Approval hash does not match plan hash")
|
||||||
|
|
||||||
written: list[str] = []
|
# A plan is an ordinary file that can be hand-edited or moved between
|
||||||
|
# machines. `root / path` silently discards `root` for an absolute path and
|
||||||
|
# happily walks out of the repository for a relative one, so every target is
|
||||||
|
# confined before anything is written -- the same boundary `adopt` applies.
|
||||||
|
targets: list[tuple[str, Path, str]] = []
|
||||||
for file_entry in plan["files"]:
|
for file_entry in plan["files"]:
|
||||||
target = root / file_entry["path"]
|
rel_path = file_entry["path"]
|
||||||
|
try:
|
||||||
|
target = confined_path(root, rel_path)
|
||||||
|
except PathViolation as exc:
|
||||||
|
raise BootstrapError("INIT_PATH_OUTSIDE_REPOSITORY", f"{rel_path}: {exc}") from exc
|
||||||
if target.exists():
|
if target.exists():
|
||||||
raise FileExistsError(f"Refusing to overwrite existing file: {file_entry['path']}")
|
raise FileExistsError(f"Refusing to overwrite existing file: {rel_path}")
|
||||||
for file_entry in plan["files"]:
|
targets.append((rel_path, target, file_entry["content"]))
|
||||||
target = root / file_entry["path"]
|
|
||||||
io.write_text_atomic(target, file_entry["content"])
|
written: list[str] = []
|
||||||
written.append(file_entry["path"])
|
for rel_path, target, content in targets:
|
||||||
|
io.write_text_atomic(target, content)
|
||||||
|
written.append(rel_path)
|
||||||
|
|
||||||
if plan.get("gitInit") and not (root / ".git").exists():
|
if plan.get("gitInit") and not (root / ".git").exists():
|
||||||
subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
|
subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
|
||||||
|
|||||||
+39
-14
@@ -156,6 +156,8 @@ def cmd_init(args: argparse.Namespace) -> int:
|
|||||||
repo_path.mkdir(parents=True, exist_ok=True)
|
repo_path.mkdir(parents=True, exist_ok=True)
|
||||||
try:
|
try:
|
||||||
written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve)
|
written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve)
|
||||||
|
except bootstrap.BootstrapError as exc:
|
||||||
|
return _adoption_failure("init apply", exc, args.output)
|
||||||
except ValueError as exc:
|
except ValueError as exc:
|
||||||
_write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output)
|
_write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output)
|
||||||
return EXIT_APPROVAL
|
return EXIT_APPROVAL
|
||||||
@@ -182,26 +184,34 @@ def cmd_init(args: argparse.Namespace) -> int:
|
|||||||
if args.git_init:
|
if args.git_init:
|
||||||
answers_data["gitInit"] = True
|
answers_data["gitInit"] = True
|
||||||
|
|
||||||
missing = [f for f in ("name", "repositoryType") if f not in answers_data]
|
try:
|
||||||
if missing:
|
|
||||||
raise CliError(f"Missing required answers: {', '.join(missing)}", EXIT_INVALID_INPUT)
|
|
||||||
|
|
||||||
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
|
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
|
||||||
plan = bootstrap.build_bootstrap_plan(answers)
|
# Passing the target lets `plan` refuse a directory that is already a
|
||||||
|
# repository, instead of leaving the collision for `apply` to discover
|
||||||
|
# after the owner has reviewed and approved.
|
||||||
|
plan = bootstrap.build_bootstrap_plan(answers, repo_path)
|
||||||
|
except bootstrap.BootstrapError as exc:
|
||||||
|
return _adoption_failure("init plan", exc, args.output)
|
||||||
_write(build_envelope("init plan", "success", plan, []), args.output)
|
_write(build_envelope("init plan", "success", plan, []), args.output)
|
||||||
return EXIT_SUCCESS
|
return EXIT_SUCCESS
|
||||||
|
|
||||||
|
|
||||||
def _adoption_failure(command: str, exc: adoption.AdoptionError, output: str) -> int:
|
def _adoption_failure(
|
||||||
"""Report a refused adoption step as an envelope, not as a bare stderr line.
|
command: str, exc: adoption.AdoptionError | bootstrap.BootstrapError, output: str
|
||||||
|
) -> int:
|
||||||
|
"""Report a refused init/adoption step as an envelope, not a bare stderr line.
|
||||||
|
|
||||||
Every mode of `adopt` can now raise `AdoptionError`, including `plan`, which
|
Every mode of `adopt` can now raise `AdoptionError`, including `plan`, which
|
||||||
validates the managed block of an existing entrypoint and decides the
|
validates the managed block of an existing entrypoint and decides the
|
||||||
knowledge entrypoint by content. Letting those reach the top-level safety net
|
knowledge entrypoint by content, and `init` raises `BootstrapError` for
|
||||||
would print a message and exit, breaking the machine-readable contract that
|
answers that would produce an invalid repository. Letting those reach the
|
||||||
`--output json` promises.
|
top-level safety net would print a message and exit, breaking the
|
||||||
|
machine-readable contract that `--output json` promises.
|
||||||
"""
|
"""
|
||||||
_write(build_envelope(command, "failure", None, [Finding("error", exc.code, str(exc))]), output)
|
# `str(exc)` is already "CODE: message" and the finding carries the code, so
|
||||||
|
# rendering both repeats it back to the reader.
|
||||||
|
message = str(exc).removeprefix(f"{exc.code}: ")
|
||||||
|
_write(build_envelope(command, "failure", None, [Finding("error", exc.code, message)]), output)
|
||||||
return EXIT_APPROVAL if exc.code == "APPROVAL_FAILED" else EXIT_VALIDATION_FAILURE
|
return EXIT_APPROVAL if exc.code == "APPROVAL_FAILED" else EXIT_VALIDATION_FAILURE
|
||||||
|
|
||||||
|
|
||||||
@@ -226,7 +236,10 @@ def cmd_adopt(args: argparse.Namespace) -> int:
|
|||||||
answers = io.load_yaml(Path(args.answers))
|
answers = io.load_yaml(Path(args.answers))
|
||||||
else:
|
else:
|
||||||
answers = {}
|
answers = {}
|
||||||
name = answers.get("name") or repo_path.name.lower()
|
# The clone directory is not an identity; assess proposes one from the
|
||||||
|
# remote and only falls back to the directory when there is none.
|
||||||
|
name = answers.get("name") or assessment["identity"]["name"]
|
||||||
|
owners = list(args.owner or []) or answers.get("owners")
|
||||||
confirmed_type = args.type or answers.get("repositoryType")
|
confirmed_type = args.type or answers.get("repositoryType")
|
||||||
if confirmed_type is not None and confirmed_type not in REPOSITORY_TYPES:
|
if confirmed_type is not None and confirmed_type not in REPOSITORY_TYPES:
|
||||||
raise CliError(
|
raise CliError(
|
||||||
@@ -238,14 +251,21 @@ def cmd_adopt(args: argparse.Namespace) -> int:
|
|||||||
assessment,
|
assessment,
|
||||||
confirmed_name=name,
|
confirmed_name=name,
|
||||||
confirmed_title=answers.get("title"),
|
confirmed_title=answers.get("title"),
|
||||||
confirmed_owners=answers.get("owners"),
|
confirmed_owners=owners,
|
||||||
confirmed_lifecycle=answers.get("lifecycle", "active"),
|
confirmed_lifecycle=answers.get("lifecycle", "active"),
|
||||||
confirmed_type=confirmed_type,
|
confirmed_type=confirmed_type,
|
||||||
strategy=args.strategy,
|
strategy=args.strategy,
|
||||||
|
acknowledged=answers.get("acknowledgedFindings"),
|
||||||
)
|
)
|
||||||
except adoption.AdoptionError as exc:
|
except adoption.AdoptionError as exc:
|
||||||
return _adoption_failure("adopt plan", exc, args.output)
|
return _adoption_failure("adopt plan", exc, args.output)
|
||||||
_write(build_envelope("adopt plan", "success", plan, []), args.output)
|
# A plan that carried findings but reported none made the warnings assess
|
||||||
|
# raised invisible at exactly the step the owner reads before approving.
|
||||||
|
plan_findings = [
|
||||||
|
Finding(f["severity"], f["code"], f.get("message", f["code"]), path=f.get("path"))
|
||||||
|
for f in plan.get("findings", [])
|
||||||
|
]
|
||||||
|
_write(build_envelope("adopt plan", "success", plan, plan_findings), args.output)
|
||||||
return EXIT_SUCCESS
|
return EXIT_SUCCESS
|
||||||
|
|
||||||
if args.mode == "apply":
|
if args.mode == "apply":
|
||||||
@@ -342,6 +362,11 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
p_adopt.add_argument("--repo", required=True)
|
p_adopt.add_argument("--repo", required=True)
|
||||||
p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"])
|
p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"])
|
||||||
p_adopt.add_argument("--answers")
|
p_adopt.add_argument("--answers")
|
||||||
|
p_adopt.add_argument(
|
||||||
|
"--owner",
|
||||||
|
action="append",
|
||||||
|
help="Confirm an owner; required before a plan can be built",
|
||||||
|
)
|
||||||
p_adopt.add_argument(
|
p_adopt.add_argument(
|
||||||
"--type",
|
"--type",
|
||||||
dest="type",
|
dest="type",
|
||||||
|
|||||||
@@ -67,19 +67,38 @@ def dirty_paths(root: Path) -> set[str]:
|
|||||||
return paths
|
return paths
|
||||||
|
|
||||||
|
|
||||||
def ignored(root: Path, relative_paths: list[str]) -> set[str]:
|
def remote_url(root: Path, name: str = "origin") -> str | None:
|
||||||
|
"""Return the URL of remote ``name``, or None when it is not configured.
|
||||||
|
|
||||||
|
Read-only: this never contacts the remote, it only reads local config. Used
|
||||||
|
to derive a repository identity from something the owner actually chose,
|
||||||
|
instead of from whatever the clone directory happens to be called.
|
||||||
|
"""
|
||||||
|
result = _run(["remote", "get-url", name], root)
|
||||||
|
if result.returncode != 0:
|
||||||
|
return None
|
||||||
|
url = result.stdout.strip()
|
||||||
|
return url or None
|
||||||
|
|
||||||
|
|
||||||
|
def ignored(root: Path, relative_paths: list[str], *, no_index: bool = False) -> set[str]:
|
||||||
"""Return the subset of ``relative_paths`` that Git ignores.
|
"""Return the subset of ``relative_paths`` that Git ignores.
|
||||||
|
|
||||||
Used to keep the secret-shaped scan quiet about gitignored material and to
|
Used to keep the secret-shaped scan quiet about gitignored material and to
|
||||||
avoid walking large ignored trees. Returns an empty set when Git is
|
avoid walking large ignored trees. Returns an empty set when Git is
|
||||||
unavailable, so callers degrade to reporting everything rather than nothing.
|
unavailable, so callers degrade to reporting everything rather than nothing.
|
||||||
|
|
||||||
|
``no_index`` evaluates the ignore rules alone. By default `check-ignore`
|
||||||
|
stays silent about a tracked path even when a rule matches it, which hides
|
||||||
|
the case worth reporting most: a file the repository's own `.gitignore`
|
||||||
|
excludes and which was nevertheless committed.
|
||||||
"""
|
"""
|
||||||
if not relative_paths:
|
if not relative_paths:
|
||||||
return set()
|
return set()
|
||||||
# `check-ignore` needs the candidates on stdin; `_run` does not pipe input,
|
# `check-ignore` needs the candidates on stdin; `_run` does not pipe input,
|
||||||
# so issue the call directly here rather than widening the shared helper.
|
# so issue the call directly here rather than widening the shared helper.
|
||||||
result = subprocess.run(
|
result = subprocess.run(
|
||||||
["git", "check-ignore", "-z", "--stdin"],
|
["git", "check-ignore", "-z", "--stdin", *(["--no-index"] if no_index else [])],
|
||||||
cwd=root,
|
cwd=root,
|
||||||
input="\0".join(relative_paths),
|
input="\0".join(relative_paths),
|
||||||
capture_output=True,
|
capture_output=True,
|
||||||
|
|||||||
@@ -15,6 +15,9 @@ from .types import Finding
|
|||||||
|
|
||||||
_FENCE_RE = re.compile(r"^(```+|~~~+)(\S*)\s*$")
|
_FENCE_RE = re.compile(r"^(```+|~~~+)(\S*)\s*$")
|
||||||
_LINK_RE = re.compile(r"(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
|
_LINK_RE = re.compile(r"(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
|
||||||
|
# A backtick run closed by a run of the same length, per CommonMark. Non-greedy
|
||||||
|
# so `a` and `b` on one line stay two spans rather than one spanning both.
|
||||||
|
_INLINE_CODE_RE = re.compile(r"(?P<fence>`+)(?:(?!(?P=fence)).)*(?P=fence)", re.DOTALL)
|
||||||
_MERMAID_HEADERS = {
|
_MERMAID_HEADERS = {
|
||||||
"flowchart",
|
"flowchart",
|
||||||
"graph",
|
"graph",
|
||||||
@@ -141,10 +144,45 @@ def _check_fences(text: str, rel_path: str) -> list[Finding]:
|
|||||||
return findings
|
return findings
|
||||||
|
|
||||||
|
|
||||||
|
def _blank_out(text: str) -> str:
|
||||||
|
"""Replace ``text`` with spaces, keeping newlines so line numbers do not move."""
|
||||||
|
return "".join("\n" if char == "\n" else " " for char in text)
|
||||||
|
|
||||||
|
|
||||||
|
def mask_code(text: str) -> str:
|
||||||
|
"""Blank out fenced blocks and inline code spans, preserving every offset.
|
||||||
|
|
||||||
|
Link-shaped text inside code is not a link. A PowerShell snippet such as
|
||||||
|
`[string]([IO.File]::ReadAllText($path))` parses as a Markdown link and was
|
||||||
|
reported as a missing local target, which is enough to keep `validate` red in
|
||||||
|
a repository whose documentation quotes shell at all. Masking rather than
|
||||||
|
deleting keeps reported positions aligned with the real file.
|
||||||
|
"""
|
||||||
|
lines = text.splitlines(keepends=True)
|
||||||
|
masked: list[str] = []
|
||||||
|
open_marker: str | None = None
|
||||||
|
for line in lines:
|
||||||
|
match = _FENCE_RE.match(line.rstrip("\r\n"))
|
||||||
|
if open_marker is None:
|
||||||
|
if match:
|
||||||
|
open_marker = match.group(1)
|
||||||
|
masked.append(line)
|
||||||
|
continue
|
||||||
|
# Inside a fence: the body is masked, and the fence lines themselves are
|
||||||
|
# kept so `_check_fences` still sees a balanced pair if it ever reuses this.
|
||||||
|
if match and match.group(1)[0] == open_marker[0]:
|
||||||
|
open_marker = None
|
||||||
|
masked.append(line)
|
||||||
|
else:
|
||||||
|
masked.append(_blank_out(line))
|
||||||
|
joined = "".join(masked)
|
||||||
|
return _INLINE_CODE_RE.sub(lambda m: _blank_out(m.group(0)), joined)
|
||||||
|
|
||||||
|
|
||||||
def _check_local_links(repo_root: Path, rel_path: str, text: str) -> list[Finding]:
|
def _check_local_links(repo_root: Path, rel_path: str, text: str) -> list[Finding]:
|
||||||
findings: list[Finding] = []
|
findings: list[Finding] = []
|
||||||
base_dir = (repo_root / rel_path).parent
|
base_dir = (repo_root / rel_path).parent
|
||||||
for match in _LINK_RE.finditer(text):
|
for match in _LINK_RE.finditer(mask_code(text)):
|
||||||
target = match.group(1)
|
target = match.group(1)
|
||||||
if target.startswith(("http://", "https://", "mailto:", "#")):
|
if target.startswith(("http://", "https://", "mailto:", "#")):
|
||||||
continue
|
continue
|
||||||
|
|||||||
@@ -8,21 +8,34 @@ class PathViolation(ValueError):
|
|||||||
"""A resource path escapes the repository boundary."""
|
"""A resource path escapes the repository boundary."""
|
||||||
|
|
||||||
|
|
||||||
def normalize_resource_path(value: str) -> str:
|
def normalize_resource_path(value: str, *, allow_root: bool = False) -> str:
|
||||||
|
"""Normalize a repository-relative path, rejecting anything that could escape.
|
||||||
|
|
||||||
|
``allow_root`` permits the single value ``"."``. A content root may legitimately
|
||||||
|
be the repository itself -- a repository holding one stack per directory is
|
||||||
|
declared as ``path: "."`` with a selector, per adoption-runbook 7.2 -- but that
|
||||||
|
is only ever a whole path, never a segment, and never a write target.
|
||||||
|
"""
|
||||||
if not value or not isinstance(value, str):
|
if not value or not isinstance(value, str):
|
||||||
raise PathViolation("Path must be a non-empty string")
|
raise PathViolation("Path must be a non-empty string")
|
||||||
if "\\" in value or value.startswith(("/", "\\")) or ":" in value.split("/")[0]:
|
if "\\" in value or value.startswith(("/", "\\")) or ":" in value.split("/")[0]:
|
||||||
raise PathViolation("Path must be repository-relative and use '/' separators")
|
raise PathViolation("Path must be repository-relative and use '/' separators")
|
||||||
|
if value == ".":
|
||||||
|
if allow_root:
|
||||||
|
return "."
|
||||||
|
raise PathViolation("Path must name something inside the repository")
|
||||||
parts = value.split("/")
|
parts = value.split("/")
|
||||||
if any(part in {"", ".", ".."} for part in parts):
|
if any(part in {"", ".", ".."} for part in parts):
|
||||||
raise PathViolation("Path contains an unsafe segment")
|
raise PathViolation("Path contains an unsafe segment")
|
||||||
return "/".join(parts)
|
return "/".join(parts)
|
||||||
|
|
||||||
|
|
||||||
def confined_path(root: Path, value: str, *, must_exist: bool = False) -> Path:
|
def confined_path(
|
||||||
normalized = normalize_resource_path(value)
|
root: Path, value: str, *, must_exist: bool = False, allow_root: bool = False
|
||||||
|
) -> Path:
|
||||||
|
normalized = normalize_resource_path(value, allow_root=allow_root)
|
||||||
root_resolved = root.resolve(strict=True)
|
root_resolved = root.resolve(strict=True)
|
||||||
candidate = root_resolved.joinpath(*normalized.split("/"))
|
candidate = root_resolved if normalized == "." else root_resolved.joinpath(*normalized.split("/"))
|
||||||
# Walk up to the nearest ancestor that actually exists before resolving
|
# Walk up to the nearest ancestor that actually exists before resolving
|
||||||
# strictly: neither the candidate nor any number of its parent directories
|
# strictly: neither the candidate nor any number of its parent directories
|
||||||
# are guaranteed to exist yet (e.g. a document path with a missing parent
|
# are guaranteed to exist yet (e.g. a document path with a missing parent
|
||||||
|
|||||||
@@ -17,6 +17,15 @@
|
|||||||
"dirty": { "type": "boolean" }
|
"dirty": { "type": "boolean" }
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
"identity": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "source"],
|
||||||
|
"additionalProperties": false,
|
||||||
|
"properties": {
|
||||||
|
"name": { "type": "string" },
|
||||||
|
"source": { "enum": ["git-remote", "directory"] }
|
||||||
|
}
|
||||||
|
},
|
||||||
"classification": {
|
"classification": {
|
||||||
"type": "object",
|
"type": "object",
|
||||||
"required": ["proposedType", "confidence", "evidence", "confirmationRequired"],
|
"required": ["proposedType", "confidence", "evidence", "confirmationRequired"],
|
||||||
@@ -60,6 +69,8 @@
|
|||||||
"id": { "type": "string" },
|
"id": { "type": "string" },
|
||||||
"path": { "type": "string" },
|
"path": { "type": "string" },
|
||||||
"role": { "type": "string" },
|
"role": { "type": "string" },
|
||||||
|
"kind": { "enum": ["directory", "file", "file-set", "manifest"] },
|
||||||
|
"selector": { "type": "string" },
|
||||||
"authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
|
"authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
|
||||||
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
|
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
|
||||||
"generatedFrom": { "type": "array", "items": { "type": "string" } }
|
"generatedFrom": { "type": "array", "items": { "type": "string" } }
|
||||||
|
|||||||
@@ -28,6 +28,33 @@
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
"findings": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["severity", "code"],
|
||||||
|
"additionalProperties": false,
|
||||||
|
"properties": {
|
||||||
|
"severity": { "enum": ["info", "warning", "error"] },
|
||||||
|
"code": { "type": "string" },
|
||||||
|
"path": { "type": "string" },
|
||||||
|
"message": { "type": "string" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"acknowledgedFindings": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["code", "reason"],
|
||||||
|
"additionalProperties": false,
|
||||||
|
"properties": {
|
||||||
|
"code": { "type": "string" },
|
||||||
|
"path": { "type": "string" },
|
||||||
|
"reason": { "type": "string", "minLength": 1 }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
"forbiddenChanges": { "type": "array", "items": { "type": "string" } },
|
"forbiddenChanges": { "type": "array", "items": { "type": "string" } },
|
||||||
"validations": { "type": "array", "items": { "type": "string" } },
|
"validations": { "type": "array", "items": { "type": "string" } },
|
||||||
"approval": {
|
"approval": {
|
||||||
|
|||||||
@@ -184,7 +184,13 @@ def _check_content_root_paths(root: Path, spec: dict[str, Any], resource_name: s
|
|||||||
continue
|
continue
|
||||||
raw_path = item.get("path")
|
raw_path = item.get("path")
|
||||||
try:
|
try:
|
||||||
confined = confined_path(root, raw_path) if isinstance(raw_path, str) else None
|
# A content root may be the repository itself when the content is a
|
||||||
|
# set selected across it (runbook 7.2), unlike any other path field.
|
||||||
|
confined = (
|
||||||
|
confined_path(root, raw_path, allow_root=True)
|
||||||
|
if isinstance(raw_path, str)
|
||||||
|
else None
|
||||||
|
)
|
||||||
except PathViolation as exc:
|
except PathViolation as exc:
|
||||||
findings.append(
|
findings.append(
|
||||||
Finding(
|
Finding(
|
||||||
|
|||||||
@@ -35,7 +35,7 @@ def test_apply_does_not_touch_working_tree_before_approval(make_repo):
|
|||||||
repo = make_repo("adoption/lxd-legacy")
|
repo = make_repo("adoption/lxd-legacy")
|
||||||
before = sorted(p.relative_to(repo).as_posix() for p in repo.rglob("*") if p.is_file())
|
before = sorted(p.relative_to(repo).as_posix() for p in repo.rglob("*") if p.is_file())
|
||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
adoption.build_plan(repo, assessment, confirmed_name="infra-lxd")
|
adoption.build_plan(repo, assessment, confirmed_name="infra-lxd", confirmed_owners=["infrastructure"])
|
||||||
after = sorted(p.relative_to(repo).as_posix() for p in repo.rglob("*") if p.is_file())
|
after = sorted(p.relative_to(repo).as_posix() for p in repo.rglob("*") if p.is_file())
|
||||||
assert before == after
|
assert before == after
|
||||||
|
|
||||||
@@ -43,7 +43,7 @@ def test_apply_does_not_touch_working_tree_before_approval(make_repo):
|
|||||||
def test_apply_rejects_stale_baseline(make_repo):
|
def test_apply_rejects_stale_baseline(make_repo):
|
||||||
repo = make_repo("adoption/lxd-legacy")
|
repo = make_repo("adoption/lxd-legacy")
|
||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
plan = adoption.build_plan(repo, assessment, confirmed_name="infra-lxd")
|
plan = adoption.build_plan(repo, assessment, confirmed_name="infra-lxd", confirmed_owners=["infrastructure"])
|
||||||
plan["baselineRevision"] = "0" * 40
|
plan["baselineRevision"] = "0" * 40
|
||||||
with pytest.raises(ValueError):
|
with pytest.raises(ValueError):
|
||||||
adoption.apply_plan(repo, plan, plan["planHash"])
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
||||||
@@ -77,7 +77,7 @@ def test_assess_antivirus_legacy_detects_occupied_kdb_path(make_repo):
|
|||||||
def test_plan_antivirus_legacy_does_not_overwrite_existing_kdb(make_repo):
|
def test_plan_antivirus_legacy_does_not_overwrite_existing_kdb(make_repo):
|
||||||
repo = make_repo("adoption/antivirus-legacy")
|
repo = make_repo("adoption/antivirus-legacy")
|
||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
plan = adoption.build_plan(repo, assessment, confirmed_name="services-antivirus")
|
plan = adoption.build_plan(repo, assessment, confirmed_name="services-antivirus", confirmed_owners=["security"])
|
||||||
changes_by_path = {c["path"]: c for c in plan["changes"]}
|
changes_by_path = {c["path"]: c for c in plan["changes"]}
|
||||||
assert changes_by_path["kdb/kdb.yaml"]["action"] == "preserve"
|
assert changes_by_path["kdb/kdb.yaml"]["action"] == "preserve"
|
||||||
|
|
||||||
@@ -86,6 +86,6 @@ def test_apply_preserves_existing_antivirus_kdb_bytes(make_repo):
|
|||||||
repo = make_repo("adoption/antivirus-legacy")
|
repo = make_repo("adoption/antivirus-legacy")
|
||||||
original = (repo / "kdb" / "kdb.yaml").read_bytes()
|
original = (repo / "kdb" / "kdb.yaml").read_bytes()
|
||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
plan = adoption.build_plan(repo, assessment, confirmed_name="services-antivirus")
|
plan = adoption.build_plan(repo, assessment, confirmed_name="services-antivirus", confirmed_owners=["security"])
|
||||||
adoption.apply_plan(repo, plan, plan["planHash"])
|
adoption.apply_plan(repo, plan, plan["planHash"])
|
||||||
assert (repo / "kdb" / "kdb.yaml").read_bytes() == original
|
assert (repo / "kdb" / "kdb.yaml").read_bytes() == original
|
||||||
|
|||||||
@@ -0,0 +1,297 @@
|
|||||||
|
"""The gates adoption must not let through, and the evidence it must not invent.
|
||||||
|
|
||||||
|
Every case here comes from running `adopt` against two real repositories. Each
|
||||||
|
one passed before the fix and reported success on a repository that had live
|
||||||
|
credentials in git, no confirmed owner, a name taken from the clone directory,
|
||||||
|
and a contract that described almost none of its content.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import subprocess
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
from stewardship import adoption
|
||||||
|
|
||||||
|
BASE = {"README.md": "# Sample\n"}
|
||||||
|
|
||||||
|
|
||||||
|
def _owners_plan(repo, **kwargs):
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
return adoption.build_plan(
|
||||||
|
repo, assessment, confirmed_name="sample", confirmed_owners=["platform"], **kwargs
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _codes(findings, code):
|
||||||
|
return [f for f in findings if f["code"] == code]
|
||||||
|
|
||||||
|
|
||||||
|
# --- 1. secret classes ------------------------------------------------------
|
||||||
|
|
||||||
|
def test_document_about_secrets_is_a_warning_not_a_blocker(synthetic_repo) -> None:
|
||||||
|
"""A document explaining a placeholder convention carries no credential."""
|
||||||
|
repo = synthetic_repo(
|
||||||
|
{
|
||||||
|
**BASE,
|
||||||
|
"docs/SECRETS.md": (
|
||||||
|
"# Secrets convention\n\n"
|
||||||
|
"Profiles carry `<SECRET:name>` tokens instead of real credentials.\n"
|
||||||
|
"The AD-join password was removed from every profile.\n"
|
||||||
|
),
|
||||||
|
}
|
||||||
|
)
|
||||||
|
findings = adoption.assess(repo)["findings"]
|
||||||
|
assert _codes(findings, "ADOPT_SECRET_NAME_SHAPED")
|
||||||
|
assert not [f for f in findings if f["severity"] == "error"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_live_credential_blocks_and_never_echoes_the_value(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo(
|
||||||
|
{**BASE, "stack/.env": "TZ=Europe/Moscow\nPOSTGRES_PASSWORD=hunter2-live-value\n"}
|
||||||
|
)
|
||||||
|
findings = adoption.assess(repo)["findings"]
|
||||||
|
verified = _codes(findings, "ADOPT_SECRET_CONTENT_VERIFIED")
|
||||||
|
assert [f["severity"] for f in verified] == ["error"]
|
||||||
|
assert "POSTGRES_PASSWORD" in verified[0]["message"]
|
||||||
|
# Invariant: a scanner that leaks what it found is worse than none.
|
||||||
|
assert "hunter2-live-value" not in verified[0]["message"]
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
("line", "is_credential"),
|
||||||
|
[
|
||||||
|
("AIRFLOW_FERNET_KEY=Rabc123XYZ", True),
|
||||||
|
("OLLAMA_API_KEY=sk-live-1", True),
|
||||||
|
("DB_PASSPHRASE=s3kr3t", True),
|
||||||
|
# "KEY" as a bare substring cannot tell a credential from a file path.
|
||||||
|
("SSH_KEY_PATH=/home/u/.ssh/id", False),
|
||||||
|
("KEYBOARD_LAYOUT=us", False),
|
||||||
|
("BYPASS_CACHE=true", False),
|
||||||
|
("PASSENGER_ROOT=/x", False),
|
||||||
|
("TZ=Europe/Moscow", False),
|
||||||
|
# Placeholders, in the three shapes real repositories use.
|
||||||
|
("POSTGRES_PASSWORD=changeme", False),
|
||||||
|
("DB_PASSWORD=<SECRET:db>", False),
|
||||||
|
("API_TOKEN=${API_TOKEN}", False),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_key_pattern_precision(tmp_path: Path, line: str, is_credential: bool) -> None:
|
||||||
|
"""Which key names count, and which values read as placeholders.
|
||||||
|
|
||||||
|
Exercised against the content check directly: this is a pure decision about
|
||||||
|
a single line, and building a git repository per case bought only runtime.
|
||||||
|
"""
|
||||||
|
env = tmp_path / ".env"
|
||||||
|
env.write_text(line + "\n", encoding="utf-8")
|
||||||
|
assert bool(adoption._secret_content_evidence(env)) is is_credential
|
||||||
|
|
||||||
|
|
||||||
|
def test_pem_private_key_is_content_evidence(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo(
|
||||||
|
{**BASE, "certs/server.key": "-----BEGIN RSA PRIVATE KEY-----\nAAAA\n-----END RSA PRIVATE KEY-----\n"}
|
||||||
|
)
|
||||||
|
findings = adoption.assess(repo)["findings"]
|
||||||
|
assert _codes(findings, "ADOPT_SECRET_CONTENT_VERIFIED")
|
||||||
|
|
||||||
|
|
||||||
|
def test_file_committed_against_its_own_ignore_rule_is_reported(synthetic_repo) -> None:
|
||||||
|
"""The fact worth reporting most, and the one the filename check missed."""
|
||||||
|
repo = synthetic_repo({**BASE, ".gitignore": "**/.env\n", "stack/.env": "TZ=Europe/Moscow\n"}, git=False)
|
||||||
|
subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
|
||||||
|
subprocess.run(["git", "config", "user.email", "t@example.com"], cwd=repo, check=True)
|
||||||
|
subprocess.run(["git", "config", "user.name", "T"], cwd=repo, check=True)
|
||||||
|
subprocess.run(["git", "add", "-A", "-f"], cwd=repo, check=True)
|
||||||
|
subprocess.run(["git", "commit", "-q", "-m", "base"], cwd=repo, check=True)
|
||||||
|
|
||||||
|
findings = adoption.assess(repo)["findings"]
|
||||||
|
contradiction = _codes(findings, "ADOPT_SECRET_IGNORED_BUT_TRACKED")
|
||||||
|
assert [f["path"] for f in contradiction] == ["stack/.env"]
|
||||||
|
assert contradiction[0]["severity"] == "warning"
|
||||||
|
|
||||||
|
|
||||||
|
# --- 2. plan inherits findings and refuses on unresolved blockers -----------
|
||||||
|
|
||||||
|
def test_plan_refuses_while_an_assess_blocker_is_unresolved(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE, "stack/.env": "POSTGRES_PASSWORD=hunter2-live-value\n"})
|
||||||
|
with pytest.raises(adoption.AdoptionError) as excinfo:
|
||||||
|
_owners_plan(repo)
|
||||||
|
assert excinfo.value.code == "ADOPT_ASSESS_BLOCKERS_UNRESOLVED"
|
||||||
|
|
||||||
|
|
||||||
|
def test_acknowledgement_unblocks_and_is_recorded_in_the_plan(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE, "stack/.env": "POSTGRES_PASSWORD=hunter2-live-value\n"})
|
||||||
|
plan = _owners_plan(
|
||||||
|
repo,
|
||||||
|
acknowledged=[
|
||||||
|
{
|
||||||
|
"code": "ADOPT_SECRET_CONTENT_VERIFIED",
|
||||||
|
"path": "stack/.env",
|
||||||
|
"reason": "rotation scheduled",
|
||||||
|
}
|
||||||
|
],
|
||||||
|
)
|
||||||
|
assert plan["acknowledgedFindings"][0]["reason"] == "rotation scheduled"
|
||||||
|
assert any(f["code"] == "ADOPT_SECRET_CONTENT_VERIFIED" for f in plan["findings"])
|
||||||
|
|
||||||
|
|
||||||
|
def test_acknowledgement_changes_the_plan_hash(synthetic_repo) -> None:
|
||||||
|
"""Approval must cover the acknowledgement, not just the file changes."""
|
||||||
|
plain = synthetic_repo({**BASE}, name="plain")
|
||||||
|
without = _owners_plan(plain)
|
||||||
|
with_ack = _owners_plan(
|
||||||
|
plain, acknowledged=[{"code": "ADOPT_WORKTREE_DIRTY", "reason": "known"}]
|
||||||
|
)
|
||||||
|
assert without["planHash"] != with_ack["planHash"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_acknowledgement_without_a_reason_is_refused(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE})
|
||||||
|
with pytest.raises(adoption.AdoptionError) as excinfo:
|
||||||
|
_owners_plan(repo, acknowledged=[{"code": "ADOPT_SECRET_CONTENT_VERIFIED", "reason": " "}])
|
||||||
|
assert excinfo.value.code == "ADOPT_ACKNOWLEDGEMENT_INCOMPLETE"
|
||||||
|
|
||||||
|
|
||||||
|
def test_plan_carries_the_assessment_findings(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE, "docs/guide.md": "# G\n"})
|
||||||
|
plan = _owners_plan(repo)
|
||||||
|
assert any(f["code"] == "ADOPT_SOURCE_MIRROR_AMBIGUOUS" for f in plan["findings"])
|
||||||
|
# The plan's own answer settles this one, so it must not travel onward.
|
||||||
|
assert not any(f["code"] == "ADOPT_OWNER_UNKNOWN" for f in plan["findings"])
|
||||||
|
|
||||||
|
|
||||||
|
# --- 3. identity and owners -------------------------------------------------
|
||||||
|
|
||||||
|
def test_plan_refuses_without_confirmed_owners(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE})
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
with pytest.raises(adoption.AdoptionError) as excinfo:
|
||||||
|
adoption.build_plan(repo, assessment, confirmed_name="sample", confirmed_owners=[])
|
||||||
|
assert excinfo.value.code == "ADOPT_OWNER_UNKNOWN"
|
||||||
|
|
||||||
|
|
||||||
|
def test_name_comes_from_the_remote_keeping_its_namespace(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE}, name="whatever-this-clone-is-called")
|
||||||
|
subprocess.run(
|
||||||
|
["git", "remote", "add", "origin", "ssh://git@example.com:9922/corsus-it/OpTools/LXD.git"],
|
||||||
|
cwd=repo,
|
||||||
|
check=True,
|
||||||
|
)
|
||||||
|
identity = adoption.assess(repo)["identity"]
|
||||||
|
assert identity == {"name": "optools-lxd", "source": "git-remote"}
|
||||||
|
|
||||||
|
|
||||||
|
def test_scp_style_remote_is_understood(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE}, name="clone")
|
||||||
|
subprocess.run(["git", "remote", "add", "origin", "git@example.com:group/Repo.git"], cwd=repo, check=True)
|
||||||
|
assert adoption.assess(repo)["identity"]["name"] == "group-repo"
|
||||||
|
|
||||||
|
|
||||||
|
def test_directory_fallback_says_it_was_inferred(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE}, name="fallback-repo")
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
assert assessment["identity"] == {"name": "fallback-repo", "source": "directory"}
|
||||||
|
assert _codes(assessment["findings"], "ADOPT_NAME_INFERRED")
|
||||||
|
|
||||||
|
|
||||||
|
# --- 4. content roots -------------------------------------------------------
|
||||||
|
|
||||||
|
def test_docs_is_proposed_for_an_infrastructure_repository(synthetic_repo) -> None:
|
||||||
|
"""`docs` is listed as evidence for `project`, which used to hide it here."""
|
||||||
|
repo = synthetic_repo({**BASE, "profiles-source/a.yaml": "{}\n", "docs/guide.md": "# G\n"})
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
assert assessment["classification"]["proposedType"] == "infrastructure-config"
|
||||||
|
assert "docs" in {cr["path"] for cr in assessment["proposedContentRoots"]}
|
||||||
|
|
||||||
|
|
||||||
|
def test_sibling_stacks_become_one_file_set_root(synthetic_repo) -> None:
|
||||||
|
files = {**BASE}
|
||||||
|
for stack in ("grafana", "loki", "n8n"):
|
||||||
|
files[f"{stack}/compose.yaml"] = "services: {}\n"
|
||||||
|
repo = synthetic_repo(files)
|
||||||
|
roots = adoption.assess(repo)["proposedContentRoots"]
|
||||||
|
stacks = [cr for cr in roots if cr.get("kind") == "file-set"]
|
||||||
|
assert len(stacks) == 1
|
||||||
|
assert stacks[0]["path"] == "." and stacks[0]["selector"] == "*/compose.y*ml"
|
||||||
|
|
||||||
|
|
||||||
|
def test_two_siblings_are_not_a_repeated_shape(synthetic_repo) -> None:
|
||||||
|
files = {**BASE}
|
||||||
|
for stack in ("grafana", "loki"):
|
||||||
|
files[f"{stack}/compose.yaml"] = "services: {}\n"
|
||||||
|
repo = synthetic_repo(files)
|
||||||
|
assert not [cr for cr in adoption.assess(repo)["proposedContentRoots"] if cr.get("kind") == "file-set"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_file_set_root_does_not_forbid_the_whole_repository(synthetic_repo) -> None:
|
||||||
|
files = {**BASE}
|
||||||
|
for stack in ("grafana", "loki", "n8n"):
|
||||||
|
files[f"{stack}/compose.yaml"] = "services: {}\n"
|
||||||
|
repo = synthetic_repo(files)
|
||||||
|
plan = _owners_plan(repo)
|
||||||
|
assert "./**" not in plan["forbiddenChanges"]
|
||||||
|
assert "*/compose.y*ml" in plan["forbiddenChanges"]
|
||||||
|
# The plan must still be able to write what it authors.
|
||||||
|
written = {c["path"] for c in plan["changes"] if c["action"] == "create"}
|
||||||
|
assert not any(adoption.is_forbidden(path, plan["forbiddenChanges"]) for path in written)
|
||||||
|
|
||||||
|
|
||||||
|
def test_defaulted_authority_asks_instead_of_asserting(synthetic_repo) -> None:
|
||||||
|
repo = synthetic_repo({**BASE, "docs/guide.md": "# G\n"})
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
assert _codes(assessment["findings"], "ADOPT_SOURCE_MIRROR_AMBIGUOUS")
|
||||||
|
|
||||||
|
|
||||||
|
def test_evidenced_mirror_is_not_ambiguous(synthetic_repo) -> None:
|
||||||
|
"""`profiles` paired with `profiles-source` is derived, not defaulted."""
|
||||||
|
repo = synthetic_repo({**BASE, "profiles/a.yaml": "{}\n", "profiles-source/a.yaml": "{}\n"})
|
||||||
|
assessment = adoption.assess(repo)
|
||||||
|
mirror = next(cr for cr in assessment["proposedContentRoots"] if cr["path"] == "profiles")
|
||||||
|
assert mirror["authority"] == "mirror"
|
||||||
|
ambiguous = {f["path"] for f in _codes(assessment["findings"], "ADOPT_SOURCE_MIRROR_AMBIGUOUS")}
|
||||||
|
assert "profiles" not in ambiguous
|
||||||
|
|
||||||
|
|
||||||
|
# --- 5. markdown links are not found inside code ----------------------------
|
||||||
|
|
||||||
|
def test_link_shaped_code_is_not_a_link(tmp_path: Path) -> None:
|
||||||
|
from stewardship.markdown import check_markdown_file
|
||||||
|
|
||||||
|
(tmp_path / "CLAUDE.md").write_text(
|
||||||
|
"# Doc\n\n"
|
||||||
|
"Cast explicitly: `[string]([IO.File]::ReadAllText($path))`.\n\n"
|
||||||
|
"```powershell\n"
|
||||||
|
"see [also](nowhere/missing.md)\n"
|
||||||
|
"```\n",
|
||||||
|
encoding="utf-8",
|
||||||
|
)
|
||||||
|
assert check_markdown_file(tmp_path, "CLAUDE.md") == []
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_real_broken_link_is_still_reported(tmp_path: Path) -> None:
|
||||||
|
from stewardship.markdown import check_markdown_file
|
||||||
|
|
||||||
|
(tmp_path / "CLAUDE.md").write_text("# Doc\n\nSee [x](docs/missing.md).\n", encoding="utf-8")
|
||||||
|
codes = [f.code for f in check_markdown_file(tmp_path, "CLAUDE.md")]
|
||||||
|
assert codes == ["MARKDOWN_LINK_TARGET_MISSING"]
|
||||||
|
|
||||||
|
|
||||||
|
# --- path confinement: "." is a whole path, never a segment ------------------
|
||||||
|
|
||||||
|
def test_repository_root_is_a_legal_content_root_path() -> None:
|
||||||
|
from stewardship.paths import normalize_resource_path
|
||||||
|
|
||||||
|
assert normalize_resource_path(".", allow_root=True) == "."
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
("value", "allow_root"),
|
||||||
|
[(".", False), ("a/./b", True), ("../escape", True), ("a/../..", True)],
|
||||||
|
)
|
||||||
|
def test_dot_segments_stay_rejected(value: str, allow_root: bool) -> None:
|
||||||
|
from stewardship.paths import PathViolation, normalize_resource_path
|
||||||
|
|
||||||
|
with pytest.raises(PathViolation):
|
||||||
|
normalize_resource_path(value, allow_root=allow_root)
|
||||||
@@ -31,7 +31,7 @@ BASE = {"README.md": "# Sample\n", "policies/.gitkeep": ""}
|
|||||||
|
|
||||||
def _plan_for(repo):
|
def _plan_for(repo):
|
||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
return assessment, adoption.build_plan(repo, assessment, confirmed_name="sample")
|
return assessment, adoption.build_plan(repo, assessment, confirmed_name="sample", confirmed_owners=["platform"])
|
||||||
|
|
||||||
|
|
||||||
def _actions(plan):
|
def _actions(plan):
|
||||||
@@ -172,7 +172,7 @@ def test_both_canonical_paths_occupied_refuses_to_plan(synthetic_repo):
|
|||||||
assessment = adoption.assess(repo)
|
assessment = adoption.assess(repo)
|
||||||
|
|
||||||
with pytest.raises(adoption.AdoptionError) as excinfo:
|
with pytest.raises(adoption.AdoptionError) as excinfo:
|
||||||
adoption.build_plan(repo, assessment, confirmed_name="sample")
|
adoption.build_plan(repo, assessment, confirmed_name="sample", confirmed_owners=["platform"])
|
||||||
assert excinfo.value.code == "ADOPT_KNOWLEDGE_UNRESOLVED"
|
assert excinfo.value.code == "ADOPT_KNOWLEDGE_UNRESOLVED"
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,159 @@
|
|||||||
|
"""What `init` must refuse before it writes a repository.
|
||||||
|
|
||||||
|
`init` is the one path where the tool controls every byte of the result, so a
|
||||||
|
repository it creates must pass `repoctl validate` by construction. Each case
|
||||||
|
here produced a `success` envelope before the fix: an invalid contract, an
|
||||||
|
unconfirmed owner, a plan that could never be applied, or a write outside the
|
||||||
|
repository from a hand-edited plan.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import json
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
from stewardship import bootstrap, io
|
||||||
|
from stewardship.validate import validate_repository
|
||||||
|
|
||||||
|
VALID = {
|
||||||
|
"name": "services-mail",
|
||||||
|
"title": "Corporate mail service",
|
||||||
|
"owners": ["it-infrastructure"],
|
||||||
|
"repositoryType": "service-config",
|
||||||
|
"lifecycle": "production",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def _answers(**overrides):
|
||||||
|
data = dict(VALID)
|
||||||
|
data.update(overrides)
|
||||||
|
return data
|
||||||
|
|
||||||
|
|
||||||
|
# --- answers that would produce an invalid repository ------------------------
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
("overrides", "code"),
|
||||||
|
[
|
||||||
|
({"name": "Services/Mail"}, "INIT_NAME_INVALID"),
|
||||||
|
({"name": "Services Mail"}, "INIT_NAME_INVALID"),
|
||||||
|
({"name": "MAIL"}, "INIT_NAME_INVALID"),
|
||||||
|
({"name": "-leading-dash"}, "INIT_NAME_INVALID"),
|
||||||
|
({"repositoryType": "mail-server"}, "INIT_TYPE_UNKNOWN"),
|
||||||
|
({"lifecycle": "bogus"}, "INIT_LIFECYCLE_UNKNOWN"),
|
||||||
|
({"access": "semi-public"}, "INIT_ACCESS_UNKNOWN"),
|
||||||
|
({"owners": []}, "INIT_OWNER_UNKNOWN"),
|
||||||
|
({"name": ""}, "INIT_ANSWERS_INCOMPLETE"),
|
||||||
|
],
|
||||||
|
)
|
||||||
|
def test_answers_that_break_the_schema_are_refused(overrides, code) -> None:
|
||||||
|
with pytest.raises(bootstrap.BootstrapError) as excinfo:
|
||||||
|
bootstrap.BootstrapAnswers.from_mapping(_answers(**overrides))
|
||||||
|
assert excinfo.value.code == code
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_rejected_name_comes_with_a_usable_suggestion() -> None:
|
||||||
|
"""An error that only says "invalid" makes the owner guess the rule."""
|
||||||
|
with pytest.raises(bootstrap.BootstrapError) as excinfo:
|
||||||
|
bootstrap.BootstrapAnswers.from_mapping(_answers(name="Services/Mail"))
|
||||||
|
assert "'services-mail'" in str(excinfo.value)
|
||||||
|
|
||||||
|
|
||||||
|
def test_owner_refusal_names_both_ways_to_answer() -> None:
|
||||||
|
"""An error that only says "refused" leaves the reader guessing the flag."""
|
||||||
|
with pytest.raises(bootstrap.BootstrapError) as excinfo:
|
||||||
|
bootstrap.BootstrapAnswers.from_mapping(_answers(owners=[]))
|
||||||
|
message = str(excinfo.value)
|
||||||
|
assert "--owner" in message and "owners:" in message
|
||||||
|
|
||||||
|
|
||||||
|
# --- the created repository must validate ------------------------------------
|
||||||
|
|
||||||
|
def test_a_freshly_created_repository_validates(tmp_path: Path) -> None:
|
||||||
|
repo = tmp_path / "mail"
|
||||||
|
repo.mkdir()
|
||||||
|
answers = bootstrap.BootstrapAnswers.from_mapping(_answers())
|
||||||
|
plan = bootstrap.build_bootstrap_plan(answers, repo)
|
||||||
|
bootstrap.apply_bootstrap_plan(repo, plan, plan["planHash"])
|
||||||
|
(repo / ".git").mkdir()
|
||||||
|
|
||||||
|
report = validate_repository(repo)
|
||||||
|
assert not [f for f in report.findings if f.severity == "error"]
|
||||||
|
# Content-root directories are deliberately not created (bootstrap docstring:
|
||||||
|
# no placeholder directories), so those warnings are expected, not failures.
|
||||||
|
assert {f.code for f in report.findings} <= {"CONTENT_ROOT_PATH_MISSING"}
|
||||||
|
|
||||||
|
|
||||||
|
# --- collisions belong to plan, not to apply ---------------------------------
|
||||||
|
|
||||||
|
def test_plan_refuses_a_directory_that_is_already_a_repository(tmp_path: Path) -> None:
|
||||||
|
repo = tmp_path / "existing"
|
||||||
|
(repo / "ops").mkdir(parents=True)
|
||||||
|
(repo / "ops" / "contract.yaml").write_text("existing: true\n", encoding="utf-8")
|
||||||
|
answers = bootstrap.BootstrapAnswers.from_mapping(_answers())
|
||||||
|
with pytest.raises(bootstrap.BootstrapError) as excinfo:
|
||||||
|
bootstrap.build_bootstrap_plan(answers, repo)
|
||||||
|
assert excinfo.value.code == "INIT_PATH_COLLISION"
|
||||||
|
assert "adopt" in str(excinfo.value)
|
||||||
|
|
||||||
|
|
||||||
|
def test_planning_without_a_target_still_works(tmp_path: Path) -> None:
|
||||||
|
"""`root` is optional; omitting it plans without the collision check."""
|
||||||
|
answers = bootstrap.BootstrapAnswers.from_mapping(_answers())
|
||||||
|
assert bootstrap.build_bootstrap_plan(answers)["planHash"].startswith("sha256:")
|
||||||
|
|
||||||
|
|
||||||
|
# --- a plan is an editable file, so apply confines every path ----------------
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(
|
||||||
|
"escape",
|
||||||
|
["../ESCAPED.md", "../../ESCAPED.md", "ops/../../ESCAPED.md", "/etc/passwd", "C:/Windows/x"],
|
||||||
|
)
|
||||||
|
def test_apply_refuses_to_write_outside_the_repository(tmp_path: Path, escape: str) -> None:
|
||||||
|
repo = tmp_path / "inner"
|
||||||
|
repo.mkdir()
|
||||||
|
answers = bootstrap.BootstrapAnswers.from_mapping(_answers())
|
||||||
|
plan = bootstrap.build_bootstrap_plan(answers, repo)
|
||||||
|
plan["files"] = [{"path": escape, "content": "escaped\n"}]
|
||||||
|
plan.pop("planHash")
|
||||||
|
plan["planHash"] = io.sha256(plan)
|
||||||
|
|
||||||
|
with pytest.raises(bootstrap.BootstrapError) as excinfo:
|
||||||
|
bootstrap.apply_bootstrap_plan(repo, plan, plan["planHash"])
|
||||||
|
assert excinfo.value.code == "INIT_PATH_OUTSIDE_REPOSITORY"
|
||||||
|
assert not list(tmp_path.glob("ESCAPED.md"))
|
||||||
|
assert not list(tmp_path.parent.glob("ESCAPED.md"))
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_refused_escape_writes_nothing_at_all(tmp_path: Path) -> None:
|
||||||
|
"""Confinement runs over every entry before the first byte is written."""
|
||||||
|
repo = tmp_path / "inner"
|
||||||
|
repo.mkdir()
|
||||||
|
answers = bootstrap.BootstrapAnswers.from_mapping(_answers())
|
||||||
|
plan = bootstrap.build_bootstrap_plan(answers, repo)
|
||||||
|
plan["files"].append({"path": "../ESCAPED.md", "content": "escaped\n"})
|
||||||
|
plan.pop("planHash")
|
||||||
|
plan["planHash"] = io.sha256(plan)
|
||||||
|
|
||||||
|
with pytest.raises(bootstrap.BootstrapError):
|
||||||
|
bootstrap.apply_bootstrap_plan(repo, plan, plan["planHash"])
|
||||||
|
assert not (repo / "ops" / "contract.yaml").exists()
|
||||||
|
|
||||||
|
|
||||||
|
# --- refusals stay machine-readable ------------------------------------------
|
||||||
|
|
||||||
|
def test_refusals_are_envelopes_not_stderr_lines(tmp_path: Path, capsys) -> None:
|
||||||
|
from stewardship.cli import main
|
||||||
|
|
||||||
|
repo = tmp_path / "mail"
|
||||||
|
repo.mkdir()
|
||||||
|
exit_code = main(
|
||||||
|
["init", "--repo", str(repo), "--name", "Services/Mail",
|
||||||
|
"--type", "service-config", "--owner", "x", "--output", "json"]
|
||||||
|
)
|
||||||
|
envelope = json.loads(capsys.readouterr().out)
|
||||||
|
assert exit_code != 0
|
||||||
|
assert envelope["outcome"] == "failure"
|
||||||
|
assert envelope["findings"][0]["code"] == "INIT_NAME_INVALID"
|
||||||
Reference in New Issue
Block a user