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
reportsandreportistcomponents, integration tests, publication staging, encryption, deployment, and the only publishing CI pipeline.beffroi.shis 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.shCLI. 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
reportsare authored reports and which JSON files are raw evidence. Specify thereportist/build.shsubcommands, argument/exit-code conventions,--force/--replacebehavior, 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 intoreporter/plugins/diagnostics, keeping the normalized evidence schema/rules and analyzer tests. Resolve sharedvisual/locally in Reportist rather than through a sibling path orBEFFROI_VISUAL_ROOT. Keep existing PDF parity and evidence validation tests passing. - T3. Add one Reportist CLI. Make
reporter/build.shthe 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.shdirectly to the new CLI. Keep only workspace-specific publication orchestration, packaging, tests, bootstrap and doctor here. Removescripts/render-capture.shand the redundant routing inscripts/workflow.sh; decide whetherworkflow-all.shis needed afterrender-allandanalyze-allland in Reportist. - T5. Make Reports content-only. Remove scripts, diagnostic plugin,
tests, schema/rules, visual assets, and Jenkinsfile from
reportsafter 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--replacerecovery. - 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
shfmtor 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.