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:
Alexander Baranov
2026-08-25 18:10:59 +03:00
co-authored by Claude Opus 5
parent 693211cee9
commit 1ab02a257c
19 changed files with 1177 additions and 88 deletions
+12 -4
View File
@@ -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.
## Зафиксированные ограничения
+43 -3
View File
@@ -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, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
+4
View File
@@ -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
View File
@@ -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
View File
@@ -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
+2
View File
@@ -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
View File
@@ -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
+119 -9
View File
@@ -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
View File
@@ -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",
+21 -2
View File
@@ -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,
+39 -1
View File
@@ -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
+17 -4
View File
@@ -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": {
+7 -1
View File
@@ -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(
+4 -4
View File
@@ -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
+297
View File
@@ -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)
+2 -2
View File
@@ -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"
+159
View File
@@ -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"