## Problem `eca:doc:plugins` was made additive so that a site generating the documentation can never remove what it does not know about. That holds for the markdown pages and for the TOC, but **not** for the machine-readable catalog at `docs/api/plugins.json`. The TOC reads what is on disk and merges into it: ```php // DocsCommands.php, around line 377 // Merge with a potentially existing TOC on disk, append-only. $existingToc = $this->navToToc($existingNav, TRUE); $this->mergeTocAppendOnly($this->toc, $existingToc); ``` `writeCatalog()` does not: ```php // DocsCommands.php, around line 1266 private function writeCatalog(): void { ... file_put_contents(self::API_PATH . '/plugins.json', json_encode($catalog, ...)); } ``` `$this->catalog` holds one entry per plugin rendered in the current run, and `API_PATH` is never read anywhere in the class — it appears only in two `mkdir` calls and two writes. The catalog is therefore replaced wholesale by whatever the generating site happens to have installed. ### Measured Running the command from a site with fewer modules than the one that produced the committed file would have changed the ECA Guide repository like this: | | plugins in `plugins.json` | markdown pages | | --- | --- | --- | | committed | **825** | 1290 | | after a run elsewhere | **456** | 1301 | **369 plugins would have been deleted from the catalog**, and the markdown page count went *up* at the same time, because pages are only ever added. The loss is invisible in `docs/plugins/` and appears only inside a 3.2 MB JSON file that no CI job inspects. It was caught by chance, from a diffstat that looked wrong. The committed catalog also records `"eca_version": "unknown"` and a timestamp five weeks old, so nothing in the file says which site produced it. In practice the catalog can only be regenerated safely from one particular machine, and that machine is not identified anywhere. ## Steps to reproduce 1. Generate the documentation from a site with a broad set of ECA-providing modules and commit the result. 2. Run `drush eca:doc:plugins` from a second site with fewer modules installed. 3. `docs/api/plugins.json` now contains only the plugins the second site knows. No warning is emitted and the page count does not fall. ## Proposed resolution Make the catalog a **build artifact assembled from per-plugin data on disk**, rather than a monolith rewritten by whichever site ran last. Each run then rewrites only the files for the plugins it knows and cannot touch the rest, so the destructive case disappears by construction and no merge logic is needed inside the command. Two ways to store that per-plugin data, and the choice is worth discussing. ### Option A — front matter in the existing page The page already carries most of it in prose: label, config key, description, `Type:`, `Required:`, `Default:` and `Allowed values:`. Adding the machine-readable form to the front matter keeps one file per plugin and puts the data where a reader of the page can also reach it: ```yaml --- title: "Set file download access result" tags: - action - eca_access - eca action 3.1.3 eca_plugin: id: eca_access_set_file_download_result type: action provider: eca_access provider_name: "ECA Access" version_introduced: 3.1.3 is_derivative: false base_id: eca_access_set_file_download_result fields_may_be_incomplete: false key_sources: [form, default_configuration, config_schema] fields: - key: access_result label: "Access result" form_type: select required: false default: forbidden multiple: false source: form value_format: null options_site_dependent: false options_truncated: false options: - { value: forbidden, label: Forbidden } - { value: neutral, label: "Neutral (no opinion)" } --- ``` Six attributes exist only in the catalog today and would have to be carried explicitly, because the prose never renders them: | Attribute | Set on | | --- | --- | | `options_site_dependent` | 450 fields | | `value_format` | 466 fields | | `source` other than `form` | 140 fields | | `fields_may_be_incomplete` | 21 plugins | | `options_truncated` | 2 fields | | option **labels** (prose lists values only) | 178 fields with options | `version_introduced` also needs to be explicit, since the page prints "Available since" only when it is known and 418 of 825 entries are unknown, which makes its absence ambiguous. ### Option B — a sidecar file per plugin For example `docs/api/plugins/<type>/<id_fs>.json`, leaving the pages untouched. ### Either way A small script in the documentation pipeline collects the per-plugin data and writes `plugins.json`, which then stops being committed. Front matter has the advantage of keeping everything about a plugin in one file and of being visible to a reader. A sidecar has the advantage of not enlarging pages with data no reader needs. Front matter looks preferable **if** MkDocs tolerates the extra keys, which is worth confirming before choosing. ### What to avoid Rendering this data into prose and parsing it back out again in the pipeline. The six attributes above were never written into the prose, so a parser would silently drop them — and two of them are load-bearing for tooling: `options_site_dependent` is what lets a validator say "cannot be checked without a site" instead of reporting an error, and `value_format` supplies the expected format of a value. ## Interim mitigation Until this lands, a much smaller change removes most of the risk: have `writeCatalog()` compare against the counts already in the file and refuse, or at least warn loudly, when the new catalog is smaller. Silence is what makes the current behavior dangerous. ## Remaining tasks - Decide between front matter and sidecar files. - Confirm MkDocs ignores unknown front matter keys, if front matter is chosen. - Emit the per-plugin data, add the assembly step to the pipeline, stop committing the generated `plugins.json`. ## User interface changes None. ## API changes None in code. `docs/api/plugins.json` keeps its current shape; only the way it is produced changes. ## Data model changes None.