Plan content-only reports and unified Reportist build
Beffroi Reporting CI A component or integration check failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
Beffroi Reporting CI A component or integration check failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
86c164f116
commit
a250b3ce8e
|
|
@ -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/).
|
||||
Loading…
Reference in New Issue