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
|
||||
[--include-related] [--materialize]
|
||||
[--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 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]
|
||||
```
|
||||
|
||||
@@ -56,6 +59,8 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
|
||||
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
|
||||
|
||||
`init` проверяет ответы до сборки плана (`name` против `ID_PATTERN`, type/lifecycle/access против enum, обязательный owner), отказывается планировать в каталог, где уже лежит любой из создаваемых путей, и confine'ит каждый путь плана при записи. Отказы — конверты с кодами `INIT_*`, а не строки в stderr.
|
||||
|
||||
`init`:
|
||||
|
||||
- собирает ответы через 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 KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
|
||||
- существующие 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;
|
||||
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
|
||||
- никогда не делает 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`.
|
||||
- Normalization tests отложены вместе с самой normalization: `--strategy normalize` и recipes не реализованы и не предлагаются CLI.
|
||||
- Самопроверка: `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.
|
||||
|
||||
## Зафиксированные ограничения
|
||||
|
||||
@@ -219,7 +219,11 @@ contentRoots:
|
||||
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
|
||||
|
||||
@@ -234,6 +238,8 @@ contentRoots:
|
||||
- freshness signals;
|
||||
- наличие потенциальных secret-shaped paths или keys без вывода values.
|
||||
|
||||
Содержимое secret-shaped файла читать разрешено — именно чтение отличает credential от документа о credentials, — но наружу выходят только имена ключей. Значения не попадают ни в findings, ни в логи, ни в assessment.
|
||||
|
||||
### 7.4. Найти agent entrypoints и automation
|
||||
|
||||
Определить:
|
||||
@@ -267,6 +273,9 @@ runbookOutput:
|
||||
path: Infra/LXD
|
||||
baselineRevision: 0123456789abcdef
|
||||
dirty: false
|
||||
identity:
|
||||
name: optools-lxd
|
||||
source: git-remote
|
||||
classification:
|
||||
proposedType: infrastructure-config
|
||||
confidence: high
|
||||
@@ -311,10 +320,27 @@ Assessment MUST distinguish `detected`, `inferred` and `confirmed` values.
|
||||
|
||||
Остальные безопасные 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
|
||||
|
||||
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
|
||||
runbookOutput:
|
||||
schema: stewardship/adoption-plan@0.1
|
||||
@@ -578,8 +604,13 @@ findingCodes:
|
||||
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
|
||||
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
||||
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_NAME_INFERRED: info
|
||||
ADOPT_ASSESS_BLOCKERS_UNRESOLVED: blocker
|
||||
ADOPT_ACKNOWLEDGEMENT_INCOMPLETE: blocker
|
||||
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
|
||||
ADOPT_BASELINE_CHANGED: blocker
|
||||
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
|
||||
@@ -597,7 +628,16 @@ findingCodes:
|
||||
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, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
|
||||
|
||||
|
||||
@@ -819,6 +819,10 @@ Bootstrap предлагает, но не навязывает:
|
||||
|
||||
Для существующего репозитория используется другая операция — `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.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Ответы проверяются до сборки плана, чтобы `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`. Прочитайте план, убедитесь, что он ожидаем.
|
||||
|
||||
```bash
|
||||
@@ -120,11 +130,23 @@ repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planH
|
||||
|
||||
```bash
|
||||
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 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`.
|
||||
|
||||
## Коды возврата
|
||||
@@ -145,5 +167,6 @@ repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт
|
||||
- **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге.
|
||||
- **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную).
|
||||
- **`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 независимо от кодовой страницы консоли.
|
||||
|
||||
+12
-1
@@ -923,6 +923,10 @@ MCP является transport/discovery layer и MUST NOT становитьс
|
||||
|
||||
### 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:
|
||||
|
||||
1. определить repository type;
|
||||
@@ -951,6 +955,9 @@ Adoption MUST:
|
||||
- создавать совместимый KDB index рядом, если канонический путь занят legacy-форматом;
|
||||
- показывать полный diff до записи;
|
||||
- разделять автоматически найденные факты и подтверждённые владельцем решения;
|
||||
- отказываться строить plan без подтверждённого owner и выводить `metadata.name` из remote, а не из имени каталога клона;
|
||||
- переносить findings из assessment в plan и отказываться строить plan, пока остаётся неразрешённая находка severity `error`; принятие такой находки MUST быть явным, с указанием причины, и входить в `planHash`;
|
||||
- классифицировать secret-shaped пути по содержимому, а не только по имени, и не выводить значения — только имена ключей;
|
||||
- допускать остановку после `assess` или `plan` без изменения репозитория;
|
||||
- при `overlay` изменять только repository-local metadata после явного подтверждения;
|
||||
- при `normalize` изменять только paths из подтверждённой recipe и обновлять все contract/KDB/Markdown references атомарно;
|
||||
@@ -1159,7 +1166,11 @@ MVP считается готовым, когда:
|
||||
17. adoption LXD сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml` на месте;
|
||||
18. adoption Antivirus не перезаписывает существующий custom `kdb/kdb.yaml`.
|
||||
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
|
||||
|
||||
|
||||
@@ -69,11 +69,13 @@ spec:
|
||||
- 3. Safety invariants
|
||||
- 6. Phase 1 — preflight
|
||||
- 7. Phase 2 — assessment
|
||||
- 9. Phase 3 — confirmation boundary
|
||||
- 10. Phase 4 — adoption plan
|
||||
- 11. Compatibility rules
|
||||
- 11.5. Normalization recipe documents-to-content-root
|
||||
- 12. Phase 5 — apply
|
||||
- 13. Phase 6 — verify
|
||||
- 14. Finding codes
|
||||
- id: stewardship-model
|
||||
title: Understand or evolve the model
|
||||
summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship
|
||||
|
||||
+336
-40
@@ -125,6 +125,28 @@ _SECRET_BINARY_SUFFIXES = (
|
||||
".zip", ".gz", ".tar", ".7z", ".xz", ".mp4", ".exe", ".msi",
|
||||
)
|
||||
_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
|
||||
# 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"},
|
||||
"decisions": {"role": "decisions", "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]:
|
||||
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
|
||||
|
||||
|
||||
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]]:
|
||||
"""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:
|
||||
"""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}
|
||||
|
||||
|
||||
_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]:
|
||||
"""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":
|
||||
findings.append(_finding("info", "ADOPT_KDB_LEGACY", rel))
|
||||
|
||||
proposed_content_roots: list[dict[str, Any]] = []
|
||||
for repo_type, markers in _TYPE_EVIDENCE:
|
||||
if repo_type != proposed_type:
|
||||
continue
|
||||
for marker in sorted(markers):
|
||||
candidate = root / marker
|
||||
if not candidate.is_dir():
|
||||
continue
|
||||
spec = _CONTENT_ROOT_SPECS.get(
|
||||
marker, {"role": marker, "authority": "source", "writePolicy": "managed"}
|
||||
proposed_content_roots = _propose_content_roots(root)
|
||||
for content_root in proposed_content_roots:
|
||||
if content_root.get("authority") == "source" and not content_root.get("generatedFrom"):
|
||||
# Runbook 7.2: calling a generated mirror a source is the named
|
||||
# mistake. Where the pairing is not evidenced by a generatedFrom
|
||||
# partner, "source" is this table's default rather than a finding
|
||||
# about this repository, and the owner has to say which it is.
|
||||
findings.append(
|
||||
_finding(
|
||||
"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] = []
|
||||
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():
|
||||
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
|
||||
|
||||
for rel, status in _detect_secret_shaped_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)",
|
||||
)
|
||||
)
|
||||
findings.extend(_classify_secret_paths(root))
|
||||
|
||||
if 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}")
|
||||
)
|
||||
|
||||
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] = []
|
||||
confirmation_required = confidence != "high"
|
||||
if confirmation_required:
|
||||
questions.append("Confirm repository type and confidence evidence")
|
||||
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 {
|
||||
"schema": "stewardship/adoption-assessment@0.1",
|
||||
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
|
||||
"identity": identity,
|
||||
"classification": {
|
||||
"proposedType": proposed_type,
|
||||
"confidence": confidence,
|
||||
@@ -535,10 +777,52 @@ def build_plan(
|
||||
confirmed_lifecycle: str = "active",
|
||||
confirmed_type: str | None = None,
|
||||
strategy: str = "overlay",
|
||||
acknowledged: list[dict[str, Any]] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
if strategy != "overlay":
|
||||
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"]
|
||||
classification = assessment["classification"]
|
||||
repository_type = confirmed_type or classification["proposedType"]
|
||||
@@ -563,15 +847,22 @@ def build_plan(
|
||||
"id": cr["id"],
|
||||
"role": cr["role"],
|
||||
"path": cr["path"],
|
||||
"kind": "directory",
|
||||
"kind": cr.get("kind", "directory"),
|
||||
"authority": cr.get("authority", "source"),
|
||||
"writePolicy": cr.get("writePolicy", "managed"),
|
||||
}
|
||||
if cr.get("selector"):
|
||||
entry["selector"] = cr["selector"]
|
||||
if cr.get("generatedFrom"):
|
||||
entry["generatedFrom"] = cr["generatedFrom"]
|
||||
content_roots.append(entry)
|
||||
for cr in content_roots:
|
||||
forbidden.append(f"{cr['path']}/**")
|
||||
# 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']}/**")
|
||||
|
||||
knowledge_entrypoint, knowledge_changes, knowledge_forbidden = _plan_knowledge(
|
||||
assessment, confirmed_name
|
||||
@@ -664,6 +955,9 @@ def build_plan(
|
||||
"baselineRevision": baseline,
|
||||
"strategy": strategy,
|
||||
"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)),
|
||||
"validations": [
|
||||
"stewardship-schema",
|
||||
@@ -673,6 +967,8 @@ def build_plan(
|
||||
],
|
||||
"approval": {"required": True},
|
||||
}
|
||||
if acknowledgements:
|
||||
plan["acknowledgedFindings"] = acknowledgements
|
||||
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||
plan["planHash"] = plan_hash
|
||||
return plan
|
||||
|
||||
@@ -7,6 +7,7 @@ domain artifacts. `init` never commits, pushes or creates a remote.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import subprocess
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
@@ -14,7 +15,14 @@ from typing import Any
|
||||
|
||||
from . import io
|
||||
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 (
|
||||
REPO_HANDOFF_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
|
||||
class BootstrapAnswers:
|
||||
name: str
|
||||
@@ -71,6 +153,7 @@ class BootstrapAnswers:
|
||||
|
||||
@staticmethod
|
||||
def from_mapping(data: dict[str, Any]) -> BootstrapAnswers:
|
||||
validate_answers(data)
|
||||
return BootstrapAnswers(
|
||||
name=data["name"],
|
||||
title=data.get("title", data["name"]),
|
||||
@@ -185,7 +268,14 @@ def _render_gitignore() -> str:
|
||||
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)
|
||||
files = [
|
||||
{"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/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] = {
|
||||
"schema": "stewardship/bootstrap-plan@0.1",
|
||||
"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"]:
|
||||
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"]:
|
||||
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():
|
||||
raise FileExistsError(f"Refusing to overwrite existing file: {file_entry['path']}")
|
||||
for file_entry in plan["files"]:
|
||||
target = root / file_entry["path"]
|
||||
io.write_text_atomic(target, file_entry["content"])
|
||||
written.append(file_entry["path"])
|
||||
raise FileExistsError(f"Refusing to overwrite existing file: {rel_path}")
|
||||
targets.append((rel_path, target, file_entry["content"]))
|
||||
|
||||
written: list[str] = []
|
||||
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():
|
||||
subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
|
||||
|
||||
+40
-15
@@ -156,6 +156,8 @@ def cmd_init(args: argparse.Namespace) -> int:
|
||||
repo_path.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
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:
|
||||
_write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output)
|
||||
return EXIT_APPROVAL
|
||||
@@ -182,26 +184,34 @@ def cmd_init(args: argparse.Namespace) -> int:
|
||||
if args.git_init:
|
||||
answers_data["gitInit"] = True
|
||||
|
||||
missing = [f for f in ("name", "repositoryType") if f not in answers_data]
|
||||
if missing:
|
||||
raise CliError(f"Missing required answers: {', '.join(missing)}", EXIT_INVALID_INPUT)
|
||||
|
||||
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
|
||||
plan = bootstrap.build_bootstrap_plan(answers)
|
||||
try:
|
||||
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
|
||||
# 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)
|
||||
return EXIT_SUCCESS
|
||||
|
||||
|
||||
def _adoption_failure(command: str, exc: adoption.AdoptionError, output: str) -> int:
|
||||
"""Report a refused adoption step as an envelope, not as a bare stderr line.
|
||||
def _adoption_failure(
|
||||
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
|
||||
validates the managed block of an existing entrypoint and decides the
|
||||
knowledge entrypoint by content. Letting those reach the top-level safety net
|
||||
would print a message and exit, breaking the machine-readable contract that
|
||||
`--output json` promises.
|
||||
knowledge entrypoint by content, and `init` raises `BootstrapError` for
|
||||
answers that would produce an invalid repository. Letting those reach the
|
||||
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
|
||||
|
||||
|
||||
@@ -226,7 +236,10 @@ def cmd_adopt(args: argparse.Namespace) -> int:
|
||||
answers = io.load_yaml(Path(args.answers))
|
||||
else:
|
||||
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")
|
||||
if confirmed_type is not None and confirmed_type not in REPOSITORY_TYPES:
|
||||
raise CliError(
|
||||
@@ -238,14 +251,21 @@ def cmd_adopt(args: argparse.Namespace) -> int:
|
||||
assessment,
|
||||
confirmed_name=name,
|
||||
confirmed_title=answers.get("title"),
|
||||
confirmed_owners=answers.get("owners"),
|
||||
confirmed_owners=owners,
|
||||
confirmed_lifecycle=answers.get("lifecycle", "active"),
|
||||
confirmed_type=confirmed_type,
|
||||
strategy=args.strategy,
|
||||
acknowledged=answers.get("acknowledgedFindings"),
|
||||
)
|
||||
except adoption.AdoptionError as exc:
|
||||
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
|
||||
|
||||
if args.mode == "apply":
|
||||
@@ -342,6 +362,11 @@ def build_parser() -> argparse.ArgumentParser:
|
||||
p_adopt.add_argument("--repo", required=True)
|
||||
p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"])
|
||||
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(
|
||||
"--type",
|
||||
dest="type",
|
||||
|
||||
@@ -67,19 +67,38 @@ def dirty_paths(root: Path) -> set[str]:
|
||||
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.
|
||||
|
||||
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
|
||||
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:
|
||||
return set()
|
||||
# `check-ignore` needs the candidates on stdin; `_run` does not pipe input,
|
||||
# so issue the call directly here rather than widening the shared helper.
|
||||
result = subprocess.run(
|
||||
["git", "check-ignore", "-z", "--stdin"],
|
||||
["git", "check-ignore", "-z", "--stdin", *(["--no-index"] if no_index else [])],
|
||||
cwd=root,
|
||||
input="\0".join(relative_paths),
|
||||
capture_output=True,
|
||||
|
||||
@@ -15,6 +15,9 @@ from .types import Finding
|
||||
|
||||
_FENCE_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 = {
|
||||
"flowchart",
|
||||
"graph",
|
||||
@@ -141,10 +144,45 @@ def _check_fences(text: str, rel_path: str) -> list[Finding]:
|
||||
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]:
|
||||
findings: list[Finding] = []
|
||||
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)
|
||||
if target.startswith(("http://", "https://", "mailto:", "#")):
|
||||
continue
|
||||
|
||||
@@ -8,21 +8,34 @@ class PathViolation(ValueError):
|
||||
"""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):
|
||||
raise PathViolation("Path must be a non-empty string")
|
||||
if "\\" in value or value.startswith(("/", "\\")) or ":" in value.split("/")[0]:
|
||||
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("/")
|
||||
if any(part in {"", ".", ".."} for part in parts):
|
||||
raise PathViolation("Path contains an unsafe segment")
|
||||
return "/".join(parts)
|
||||
|
||||
|
||||
def confined_path(root: Path, value: str, *, must_exist: bool = False) -> Path:
|
||||
normalized = normalize_resource_path(value)
|
||||
def confined_path(
|
||||
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)
|
||||
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
|
||||
# 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
|
||||
|
||||
@@ -17,6 +17,15 @@
|
||||
"dirty": { "type": "boolean" }
|
||||
}
|
||||
},
|
||||
"identity": {
|
||||
"type": "object",
|
||||
"required": ["name", "source"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"source": { "enum": ["git-remote", "directory"] }
|
||||
}
|
||||
},
|
||||
"classification": {
|
||||
"type": "object",
|
||||
"required": ["proposedType", "confidence", "evidence", "confirmationRequired"],
|
||||
@@ -60,6 +69,8 @@
|
||||
"id": { "type": "string" },
|
||||
"path": { "type": "string" },
|
||||
"role": { "type": "string" },
|
||||
"kind": { "enum": ["directory", "file", "file-set", "manifest"] },
|
||||
"selector": { "type": "string" },
|
||||
"authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
|
||||
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
|
||||
"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" } },
|
||||
"validations": { "type": "array", "items": { "type": "string" } },
|
||||
"approval": {
|
||||
|
||||
@@ -184,7 +184,13 @@ def _check_content_root_paths(root: Path, spec: dict[str, Any], resource_name: s
|
||||
continue
|
||||
raw_path = item.get("path")
|
||||
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:
|
||||
findings.append(
|
||||
Finding(
|
||||
|
||||
@@ -35,7 +35,7 @@ def test_apply_does_not_touch_working_tree_before_approval(make_repo):
|
||||
repo = make_repo("adoption/lxd-legacy")
|
||||
before = sorted(p.relative_to(repo).as_posix() for p in repo.rglob("*") if p.is_file())
|
||||
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())
|
||||
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):
|
||||
repo = make_repo("adoption/lxd-legacy")
|
||||
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
|
||||
with pytest.raises(ValueError):
|
||||
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):
|
||||
repo = make_repo("adoption/antivirus-legacy")
|
||||
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"]}
|
||||
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")
|
||||
original = (repo / "kdb" / "kdb.yaml").read_bytes()
|
||||
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"])
|
||||
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):
|
||||
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):
|
||||
@@ -172,7 +172,7 @@ def test_both_canonical_paths_occupied_refuses_to_plan(synthetic_repo):
|
||||
assessment = adoption.assess(repo)
|
||||
|
||||
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"
|
||||
|
||||
|
||||
|
||||
@@ -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