From 1ab02a257caaf9ce1c18cb327ec8029e92766df6 Mon Sep 17 00:00:00 2001 From: Alexander Baranov Date: Tue, 25 Aug 2026 18:10:59 +0300 Subject: [PATCH] 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 --- docs/PLAN.md | 16 +- docs/adoption-runbook.md | 46 ++- docs/guide.md | 4 + docs/repoctl.md | 27 +- docs/specification.md | 13 +- kdb/kdb.yaml | 2 + src/stewardship/adoption.py | 376 ++++++++++++++++-- src/stewardship/bootstrap.py | 128 +++++- src/stewardship/cli.py | 55 ++- src/stewardship/gitutil.py | 23 +- src/stewardship/markdown.py | 40 +- src/stewardship/paths.py | 21 +- .../schemas/adoption-assessment.schema.json | 11 + .../schemas/adoption-plan.schema.json | 27 ++ src/stewardship/validate.py | 8 +- tests/test_adoption.py | 8 +- tests/test_adoption_gates.py | 297 ++++++++++++++ tests/test_adoption_rules.py | 4 +- tests/test_bootstrap_gates.py | 159 ++++++++ 19 files changed, 1177 insertions(+), 88 deletions(-) create mode 100644 tests/test_adoption_gates.py create mode 100644 tests/test_bootstrap_gates.py diff --git a/docs/PLAN.md b/docs/PLAN.md index 2203f27..5355959 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -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. ## Зафиксированные ограничения diff --git a/docs/adoption-runbook.md b/docs/adoption-runbook.md index 303e6d4..9978684 100644 --- a/docs/adoption-runbook.md +++ b/docs/adoption-runbook.md @@ -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). Значения вида ``, `${VAR}`, `{{ var }}`, `changeme` и подобные плейсхолдеры credential не считаются. Путь, который репозиторий игнорирует и который не отслеживается, не сообщается вовсе. `ADOPT_WORKTREE_DIRTY` на этапе `assess` остаётся warning и не мешает планированию. На этапе `apply` он становится blocker, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие. diff --git a/docs/guide.md b/docs/guide.md index 8c54973..7c22044 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -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 diff --git a/docs/repoctl.md b/docs/repoctl.md index 9430f27..a68d1e7 100644 --- a/docs/repoctl.md +++ b/docs/repoctl.md @@ -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: --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 независимо от кодовой страницы консоли. diff --git a/docs/specification.md b/docs/specification.md index 939d0b9..eede15e 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -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 diff --git a/kdb/kdb.yaml b/kdb/kdb.yaml index f0be880..8094895 100644 --- a/kdb/kdb.yaml +++ b/kdb/kdb.yaml @@ -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 diff --git a/src/stewardship/adoption.py b/src/stewardship/adoption.py index bd78df4..c99009f 100644 --- a/src/stewardship/adoption.py +++ b/src/stewardship/adoption.py @@ -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" + # 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\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 + # ``, `${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 diff --git a/src/stewardship/bootstrap.py b/src/stewardship/bootstrap.py index 80389ae..40e121b 100644 --- a/src/stewardship/bootstrap.py +++ b/src/stewardship/bootstrap.py @@ -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) diff --git a/src/stewardship/cli.py b/src/stewardship/cli.py index 4bf3830..c8cb8ad 100644 --- a/src/stewardship/cli.py +++ b/src/stewardship/cli.py @@ -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", diff --git a/src/stewardship/gitutil.py b/src/stewardship/gitutil.py index 6eaffde..375692c 100644 --- a/src/stewardship/gitutil.py +++ b/src/stewardship/gitutil.py @@ -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, diff --git a/src/stewardship/markdown.py b/src/stewardship/markdown.py index 0be7451..fb3ccf1 100644 --- a/src/stewardship/markdown.py +++ b/src/stewardship/markdown.py @@ -15,6 +15,9 @@ from .types import Finding _FENCE_RE = re.compile(r"^(```+|~~~+)(\S*)\s*$") _LINK_RE = re.compile(r"(?`+)(?:(?!(?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 diff --git a/src/stewardship/paths.py b/src/stewardship/paths.py index f182122..991540c 100644 --- a/src/stewardship/paths.py +++ b/src/stewardship/paths.py @@ -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 diff --git a/src/stewardship/schemas/adoption-assessment.schema.json b/src/stewardship/schemas/adoption-assessment.schema.json index c50c45a..bd95728 100644 --- a/src/stewardship/schemas/adoption-assessment.schema.json +++ b/src/stewardship/schemas/adoption-assessment.schema.json @@ -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" } } diff --git a/src/stewardship/schemas/adoption-plan.schema.json b/src/stewardship/schemas/adoption-plan.schema.json index 7663491..e0c0ba3 100644 --- a/src/stewardship/schemas/adoption-plan.schema.json +++ b/src/stewardship/schemas/adoption-plan.schema.json @@ -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": { diff --git a/src/stewardship/validate.py b/src/stewardship/validate.py index 7a72cf7..89bb5a5 100644 --- a/src/stewardship/validate.py +++ b/src/stewardship/validate.py @@ -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( diff --git a/tests/test_adoption.py b/tests/test_adoption.py index 75f3467..4bc1081 100644 --- a/tests/test_adoption.py +++ b/tests/test_adoption.py @@ -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 diff --git a/tests/test_adoption_gates.py b/tests/test_adoption_gates.py new file mode 100644 index 0000000..2bf25ca --- /dev/null +++ b/tests/test_adoption_gates.py @@ -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 `` 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=", 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) diff --git a/tests/test_adoption_rules.py b/tests/test_adoption_rules.py index 8381cf7..b1b08c3 100644 --- a/tests/test_adoption_rules.py +++ b/tests/test_adoption_rules.py @@ -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" diff --git a/tests/test_bootstrap_gates.py b/tests/test_bootstrap_gates.py new file mode 100644 index 0000000..a9b0784 --- /dev/null +++ b/tests/test_bootstrap_gates.py @@ -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"