beffroi-reporting/AGENT-TASKS.md

130 lines
10 KiB
Markdown

# Repository roles and build consolidation
The component move is implemented. Preserve the 17-PDF legacy parity baseline
while finishing CLI cleanup and external CI verification.
## 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
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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/).