beffroi-reporting/AGENT-TASKS.md

10 KiB

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

  • 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, CLI input documentation, and query documentation.