From 24717d6c251c0bfa71815ff4c80c346e459f7eca Mon Sep 17 00:00:00 2001 From: turegjorup Date: Thu, 9 Jul 2026 09:12:50 +0200 Subject: [PATCH 1/2] docs: refresh CLAUDE.md and agent docs for current tooling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audited the docs against the code. Corrections: - Stack: API Platform 4.1 → 4.3, image itkdev/php8.3-fpm → php8.4-fpm. - PHPStan level 6 → 8 (pr-readiness agent + the code-analysis comment, which also now notes Rector). - Drop the stale `ignore_error: true` fixtures rationale from the reload-fixtures agent (removed from the Taskfile in the mappings PR). - Note the CI-enforced index-mapping-drift gate (not just the local Stop hook) and document the test-suite layout (Contract/Consumer/Unit + tests/schemas) that has grown since CLAUDE.md was written. README is accurate (pins no versions) and left as-is. --- .claude/agents/pr-readiness.md | 3 ++- .claude/agents/reload-fixtures.md | 2 +- CLAUDE.md | 15 +++++++++++---- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/.claude/agents/pr-readiness.md b/.claude/agents/pr-readiness.md index 8d75b37..c5c7205 100644 --- a/.claude/agents/pr-readiness.md +++ b/.claude/agents/pr-readiness.md @@ -16,13 +16,14 @@ JS/CSS to lint). Stop early if a critical check fails. 4. **Twig coding standards**: `task coding-standards:twig:check` 5. **YAML coding standards**: `task coding-standards:yaml:check` 6. **Markdown coding standards**: `task coding-standards:markdown:check` -7. **PHPStan (level 6)**: `task code-analysis:phpstan` +7. **PHPStan (level 8)**: `task code-analysis:phpstan` 8. **Rector (dry-run)**: `task code-analysis:rector` — the `Rector` gate fails on any suggested change; run `task code-analysis:rector:apply` to fix. 9. **Test fixtures + API tests**: `task fixtures:load:test --yes && task api:test`. Tests hit a real Elasticsearch, so fixtures must be loaded first. If the load fails with "No alive nodes", run `docker compose up --detach --wait` and retry — see the `reload-fixtures` agent for the full recovery dance. 10. **API spec up to date** (mirrors `.github/workflows/api-spec.yml`): - `task api:spec:export` - `git diff --exit-code public/spec.yaml` — must be clean. + 1. **CHANGELOG updated**: `git diff develop -- CHANGELOG.md` should show at least one entry under `## [Unreleased]`. ## Output diff --git a/.claude/agents/reload-fixtures.md b/.claude/agents/reload-fixtures.md index 3f516b2..1008ce2 100644 --- a/.claude/agents/reload-fixtures.md +++ b/.claude/agents/reload-fixtures.md @@ -22,4 +22,4 @@ Two flavours of fixtures exist (see `src/Model/IndexName.php` for the seven inde - Poll the cluster health endpoint until it returns HTTP 200: `docker compose exec elasticsearch curl 'http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=5s' --verbose` - Re-run the fixture load command. -5. Report which indices were loaded and any non-fatal warnings (the Taskfile sets `ignore_error: true` because some fixtures emit a benign `Warning: Undefined array key "entityId"`). +5. Report which indices were loaded and any non-fatal warnings. diff --git a/CLAUDE.md b/CLAUDE.md index 479935f..505c2e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,8 +10,8 @@ API platform front-end for the Danish event database used by the municipality of `docker-compose.yml` is part of the standard ITK Dev Symfony image but is **not used for domain data** (the `migrations/` and `src/Entity/` directories are empty). -Stack: PHP 8.3+, Symfony 7.4, API Platform 4.1, Elasticsearch 8.x. Runs entirely in Docker via -`itkdev/php8.3-fpm` + nginx. +Stack: PHP 8.3+, Symfony 7.4, API Platform 4.3, Elasticsearch 8.x. Runs entirely in Docker via +`itkdev/php8.4-fpm` + nginx. ## Common commands @@ -46,14 +46,21 @@ The test harness creates each index with a **production-parity mapping** (`dynam `tests/resources/mappings/.json` — a hand-kept copy of the importer's `src/Model/Indexing/Mappings/`. `FixtureLoader::createIndex()` fails loudly if a mapping is missing, so the filter tests exercise real field semantics (`keyword` = exact/case-sensitive; `text` = tokenised) rather than Elasticsearch dynamic-mapping -artefacts. When the importer changes a mapping, update the matching file here (the `Stop` hook warns on drift). +artefacts. When the importer changes a mapping, update the matching file here — the `Stop` hook warns locally, +and the `index-mapping-drift` CI job fails if these diverge from the importer's committed `resources/mappings` +export (`.github/workflows/index-mapping-drift.yaml`). + +The suite is split into `tests/ApiPlatform/Contract/` (JSON-LD envelope + deep payload schemas via +`ContractSchemaTest`, `tests/schemas/`), `tests/ApiPlatform/Consumer/` (per-consumer contracts — +`AarhusguidenContractTest`, `Os2displayContractTest`), the per-resource `*Test`/`*FilterTest` (behavioural), and +`tests/Unit/` (filter DSL + `SearchParamsBuilder`, runnable with Elasticsearch stopped). ### Lint / static analysis ```shell task coding-standards:check # markdown + php-cs-fixer + twig-cs-fixer + prettier (yaml) task coding-standards:apply # auto-fix all of the above -task code-analysis # PHPStan, level 6 +task code-analysis # PHPStan (level 8) + Rector ``` CI (GitHub Actions `pr.yaml`) runs all of these — run them locally before opening a PR. From 7dc5c25518929b16504455dd0699dcd2c2f0212f Mon Sep 17 00:00:00 2001 From: turegjorup Date: Thu, 9 Jul 2026 09:15:36 +0200 Subject: [PATCH 2/2] docs: add CHANGELOG entry for docs refresh --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8522112..6ca2381 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ See [keep a changelog] for information about writing changes to this log. ## [Unreleased] +- [PR-59](https://github.com/itk-dev/event-database-api/pull/59) + Refresh CLAUDE.md/agent docs for current tooling (API Platform 4.3, php8.4 image, PHPStan level 8, test layout) - [PR-58](https://github.com/itk-dev/event-database-api/pull/58) Update dependencies in-constraint (Symfony 7.4.14 patch train, phpunit/php-cs-fixer/phpstan-symfony/flex) - [PR-57](https://github.com/itk-dev/event-database-api/pull/57)