From a250b3ce8e1178fd1a4d24f1cd378d6fe68a7c25 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 20:43:19 +0200 Subject: [PATCH] Plan content-only reports and unified Reportist build --- AGENT-TASKS.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 AGENT-TASKS.md diff --git a/AGENT-TASKS.md b/AGENT-TASKS.md new file mode 100644 index 0000000..cbcd14f --- /dev/null +++ b/AGENT-TASKS.md @@ -0,0 +1,129 @@ +# Repository roles and build consolidation + +This is a plan, not an implementation checklist already in progress. Preserve the +current 17-PDF legacy parity baseline during the migration. + +## Target ownership + +- **Macro repository (this checkout):** edition workspace, pinned `reports` and + `reportist` components, integration tests, publication staging, encryption, + deployment, and the only publishing CI pipeline. `beffroi.sh` is a thin + workspace entry point. +- **Reports:** authored YAML/JSON, raw diagnostic captures, and editorial text + such as README/source notes. No renderer, analyzer, scripts, visual assets, + tests, or Jenkinsfile. Keep diagnostic captures only if they are intended + report source data; otherwise put them in a separate data repository. +- **Reportist:** reusable Typst report and diagnostic plugins, shared visual + elements/themes, validation and analysis logic, fixtures/tests, and a single + public `build.sh` CLI. It renders one document without the macro checkout. + +Proposed command mapping (names can change before implementation): + +| Macro command | Reportist command or macro responsibility | +| --- | --- | +| `beffroi.sh report IN OUT` | `reportist/build.sh render report IN --output OUT` | +| `beffroi.sh diagnostic-pdf IN OUT` | `reportist/build.sh render diagnostic IN --output OUT` | +| `beffroi.sh capture-pdf IN OUT` | Alias to `render diagnostic`; remove after migration notice | +| `beffroi.sh diagnostic ...` | `reportist/build.sh analyze ...` and `render diagnostic ...`; macro chooses output paths | +| `beffroi.sh all DIR ...` | Macro publication assembly calling `reportist/build.sh render-all ...` for each source set | +| `beffroi.sh package/test/bootstrap/doctor` | Macro owns packaging, integration tests, checkout and environment checks | + +## Tasks, in dependency order + +- [ ] **T1. Freeze the contract.** Document which files in `reports` are authored + reports and which JSON files are raw evidence. Specify the `reportist/build.sh` + subcommands, argument/exit-code conventions, `--force`/`--replace` behavior, + and whether batch commands preserve relative paths. Test these contracts + from a standalone Reportist checkout. +- [ ] **T2. Move diagnostic implementation to Reportist.** Move + `reports/plugins/diagnostics/{renderer,tools,runtime,tests}` and its entry + scripts into `reporter/plugins/diagnostics`, keeping the normalized evidence + schema/rules and analyzer tests. Resolve shared `visual/` locally in Reportist + rather than through a sibling path or `BEFFROI_VISUAL_ROOT`. Keep existing + PDF parity and evidence validation tests passing. +- [ ] **T3. Add one Reportist CLI.** Make `reporter/build.sh` the supported route + for single report/diagnostic render, batch render, analysis, validation, and + YAML-to-JSON export. Move common option parsing, path normalization, safe + output staging, and overwrite handling into one helper used by its commands. + Avoid a generic schema/IR that constrains plugin document structure. +- [ ] **T4. Thin the macro launcher.** Map `beffroi.sh` directly to the new CLI. + Keep only workspace-specific publication orchestration, packaging, tests, + bootstrap and doctor here. Remove `scripts/render-capture.sh` and the + redundant routing in `scripts/workflow.sh`; decide whether `workflow-all.sh` + is needed after `render-all` and `analyze-all` land in Reportist. +- [ ] **T5. Make Reports content-only.** Remove scripts, diagnostic plugin, + tests, schema/rules, visual assets, and Jenkinsfile from `reports` after + Reportist owns and tests them. Keep authored source files and useful source + provenance. Retire historical adapter docs or move them to an archive outside + the content repository. Update submodule pins and links. +- [ ] **T6. Consolidate CI and publication.** Macro Jenkinsfile invokes + Reportist's CLI through `beffroi.sh`, tests all sources, builds staged output, + packages and publishes it. Remove component Jenkinsfiles if independent + component CI is no longer required; otherwise keep them test-only and update + stale messages. Verify clean checkout and `--replace` recovery. +- [ ] **T7. Remove confirmed dead paths and format remaining code.** Delete the + duplicate parity wrappers, unused logo copies and retired documentation + after checking external callers. Apply `shfmt` or equivalent consistent + formatting to remaining Bash, then retain one concise usage/README source + per public command. Do not delete the ignored legacy baseline until its + reference PDFs/text hashes are independently preserved. +- [ ] **T8. Prove the result.** From clean component checkouts, render every + stored report and capture. Compare all 17 PDFs to the recorded legacy text + hashes/page counts and raster pages where available. Test direct Reportist + usage, macro commands, invalid inputs, no-overwrite/replace behavior, + package contents, and CI with the actual worker dependencies. + +## Findings to address + +| Finding | Evidence | Planned action | +| --- | --- | --- | +| Reports owns code despite the content-only goal | `reports/plugins/diagnostics`, `reports/tests`, `reports/Jenkinsfile` | T2, T5, T6 | +| Diagnostic renderer depends on sibling checkout | `reports/plugins/diagnostics/render.sh` defaults `BEFFROI_VISUAL_ROOT` to `../../../reporter/visual` | T2 | +| Multiple entry points route the same render | `beffroi.sh` aliases, `scripts/render-capture.sh`, `scripts/workflow.sh`, both plugin `render.sh` files | T3, T4 | +| Repeated batch iteration and option handling | `reporter/tools/{render,validate,export-json}-all.sh`, diagnostic `analyse-all.sh`/`validate-all.sh`, `scripts/workflow-all.sh` | T3, T4 | +| `validate.sh` for reports compiles a whole PDF | `reporter/tools/validate.sh` | Keep until Typst validation can run the same model without PDF; test faster `typst eval` path in T3 | +| Obsolete parity wrappers repeat a full publication build | `scripts/check-regular-parity.py`, `scripts/check-diagnostic-parity.py` both call the same all-PDF checker | T7 | +| Stale CI and historical documentation | `reports/Jenkinsfile` still says adapter; `reports/docs/{adapter-contract,workflow,migration-inventory}.md` describe retired path | T5, T6 | +| Data repo has duplicate or suspect assets | `reports/assets/beffroi.png` and `beffroi_round.png` are absent from active renderer references; `reporter/visual/beffroi.png` is active | Verify provenance before T5 deletion | +| Bash style obscures control flow | compressed one-line parsers/loops in `beffroi.sh`, `reporter/tools/*.sh`, `scripts/workflow*.sh` | T3, T7 | +| Deprecated Typst CLI remains in active analysis | `reports/plugins/diagnostics/{analyse.sh,tools/validate.sh}` call `typst query` | Replace with `typst eval 'query(...).first().value' --in ...` during T2/T3 | + +## Shell preparation review + +Typst should own loading YAML/JSON, document normalization, analysis rules, +validation predicates, theme selection, and page composition. Typst can read +files and receive CLI inputs, but it is not the right place for directory +enumeration, source copying, hash calculation, atomic replacement, archive +encryption, Git operations, or CI deployment. Keep those in a small shell or +Python CLI. Do not move staging into Typst merely to reduce shell lines. + +| Active shell script | What it prepares | Decision | +| --- | --- | --- | +| `beffroi.sh` | Command routing and tool checks | **Keep, thin** to Reportist CLI and macro-only jobs. | +| `bootstrap.sh` | Submodules and tool checks | **Keep in macro**; Typst cannot manage Git checkout. | +| `scripts/build-publication.sh` | Enumerates sources, stages/replaces whole publication | **Keep in macro**, call Reportist CLI; preserve atomic replacement. | +| `scripts/package-reports.sh` | Encrypts/validates ZIP archives via Python/uv | **Keep in macro**; not a Typst job. | +| `scripts/check-components.sh` | Runs tests and PDF comparisons | **Keep in macro**, simplify after CLI migration. | +| `scripts/workflow.sh` | Routes analysis and two renderers, chooses output paths | **Fold into Reportist CLI/macro**; Typst keeps analysis logic. | +| `scripts/workflow-all.sh` | Finds captures and coordinates analysis/PDFs | **Fold into Reportist batch command**; enumeration stays outside Typst. | +| `scripts/render-capture.sh` | Forwards two arguments | **Delete** after alias migration. | +| `reporter/render.sh` | Stages renderer/theme/assets/input, compiles PDF | **Fold into Reportist CLI**; Typst owns report data checks/rendering, CLI owns staging. | +| `reporter/tools/render-all.sh` | Walks reports and invokes renderer | **Fold into Reportist CLI**; traversal stays outside Typst. | +| `reporter/tools/validate.sh` | Stages and compiles to check report | **Fold into Reportist CLI**; try Typst evaluation of shared checks. | +| `reporter/tools/validate-all.sh` | Walks reports for validation | **Fold into Reportist CLI**; traversal stays outside Typst. | +| `reporter/tools/export-json-all.sh` | Walks/stages YAML files and invokes Typst conversion | **Fold into Reportist CLI**; Typst keeps YAML decode/JSON encode. | +| `reporter/tests/test.sh` | Starts unit tests | **Keep test runner**, one line or document direct test command. | +| `reports/plugins/diagnostics/render.sh` | Stages capture, rules, themes, renderer and PDF | **Move/fold into Reportist CLI**; Typst owns parsing/normalization/rendering. | +| `reports/plugins/diagnostics/analyse.sh` | Hashes source, stages rules, evaluates/validates output | **Move/fold into Reportist CLI**; Typst owns rules, CLI owns hashes and atomic files. | +| `reports/plugins/diagnostics/analyse-all.sh` | Walks capture tree | **Move/fold into Reportist CLI**; traversal stays outside Typst. | +| `reports/plugins/diagnostics/tools/validate.sh` | Stages schema/evidence, hashes linked source | **Move/fold into Reportist CLI**; Typst owns field/evidence predicates, CLI owns filesystem/hash checks. | +| `reports/plugins/diagnostics/tools/validate-all.sh` | Walks diagnostic tree | **Move/fold into Reportist CLI**; traversal stays outside Typst. | +| `reports/plugins/diagnostics/tests/test.sh` | Creates uv venv and runs tests | **Move to Reportist tests**; dependency installation remains outside Typst. | +| `reports/tests/test.sh` | Runs content/plugin smoke tests | **Move plugin tests to Reportist**; macro tests source inventory. | + +`legacy/typst_reporter/*.sh` is a read-only reference implementation and is +excluded from the active script inventory. + +Typst capabilities checked against the [official data-loading documentation](https://typst.app/docs/reference/data-loading/), +[CLI input documentation](https://typst.app/docs/reference/foundations/sys/), +and [query documentation](https://typst.app/docs/reference/introspection/query/).