130 lines
10 KiB
Markdown
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/).
|