Integrate report template into main repository

[RobinWikoff]

Integrate report template into main repository

Summary

The feature/report-template branch contains a working report generation system that should be integrated into main. The implementation includes a Rust crate (uor-report) for PDF generation from structured YAML/JSON input, a Python prototype package for ReportLab-based PDF generation (staged for Streamlit UI integration), and an operational visualization pipeline for rendering ontology spine diagrams.

What exists on the branch

1. Rust report crate (report/)

A new workspace member crate uor-report that generates branded memo-style PDFs:

• report/src/schema.rs — MemoData struct with validation (date, subject, recipient, background, problem statement, updates, 3 additional sections, title, org name, logo path). Supports loading from YAML or JSON.
• report/src/generator.rs — genpdf-based PDF builder. US Letter (8.5×11"), 0.75" margins, DM Sans font family (Bold, Italic, Regular), structured layout: title (18pt) → metadata table (Date/Subject/Recipient) → 6 content sections with paragraph splitting.
• report/assets/ — DM Sans font files (Regular, Bold, Italic, BoldItalic .ttf) and uor-icon-black.png.
• report/examples/memo_input.yaml — Example input payload.

2. CLI binary (clients/src/bin/report.rs)

A clap-based entry point (uor-report) that takes --input (YAML/JSON path) and --output (defaults to report.pdf), loads the memo data, and generates the PDF.

3. Python prototype (public/01_robinwikoff/report_template/)

A parallel Python implementation designed as a stepping stone to Streamlit integration:

• memo/ package with 5 modules: schema.py (dataclass + validation), branding.py (DM Sans font registration), template.py (ReportLab flowables), generator.py (branded header/footer with logo, page numbering, letter-spacing), cli.py (argparse CLI)
• Dependencies: PyYAML>=6.0, reportlab>=4.0
• More polished branding than the Rust crate — includes header/footer on every page with logo + org name + page X of Y
• Example PDFs already generated
• README.md with usage instructions

4. Operational visualization pipeline (scripts/, public/01_robinwikoff/exploring_views/)

15 bash scripts generating ontology dependency analysis artifacts — all parse spec/src/namespaces/*.rs directly:

Category	Scripts	Outputs
CSV generators	Operational_Namespace_Tuples_csv.sh, _Matrix_csv.sh, _Summary_csv.sh, _Layers_csv.sh, LayersToNamespaces_csv.sh, _Classes_csv.sh, _Spine_Paths_csv.sh	Dependency pairs, adjacency matrix, per-namespace summary (22 cols), layer mappings, class inventory, 6 curated spine paths
SVG generators	Operational_Layered_Graph_svg.sh, _Mermaid_Graph_svg.sh, _Spine_Namespaces_svg.sh	Layered box diagram, dark-theme node graph, branded Mermaid flowchart (SVG + 300 DPI PNG)
Mermaid generators	Operational_Spine_mmd.sh, _Spine_cleaner_mmd.sh	Two .mmd variants of the operational spine
Prism surface	Prism_Surface_Grammar_Map_svg.sh, _Grammar_Split_svg.sh	Grammar surface visualizations
Orchestrator	Operational_All.sh	Runs all 11 operational sub-scripts

The SVG/PNG pipeline for the spine diagram uses: mmdc (Mermaid CLI) → Python SVG post-processing (3× marker scaling for visible arrowheads) → Puppeteer (SVG → PNG at deviceScaleFactor: 3) → Pillow (branded header compositing, 300 DPI output).

Actions needed

Must-have for merge

1. Add report/ crate to the workspace Cargo.toml members list and verify CI passes (cargo clippy, cargo test, cargo fmt --check)
2. Ensure report/ follows project lint rules — currently uses #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, missing_docs)] which matches the project standard
3. Verify clients/src/bin/report.rs builds and runs — cargo run --bin uor-report -- --input report/examples/memo_input.yaml --output /tmp/test.pdf
4. Decide on Python prototype location — currently in public/01_robinwikoff/report_template/. Options:
   • Keep in public/ as a reference/prototype (it won't affect Rust CI)
   • Move to a top-level report-py/ or similar
   • Remove from repo if only the Rust crate ships
5. Clean up .venv/ — a Python virtual environment is currently checked in under public/01_robinwikoff/report_template/.venv/ and should be .gitignore'd

Should-have

6. Add uor-report to the CI pipeline — at minimum run cargo test -p uor-report
7. Add report generation to the conformance suite or docs pipeline if desired
8. Wire logo_path in the Rust generator — the schema accepts it but the generator doesn't currently render a logo in the PDF header (the Python version does)

Nice-to-have

9. Integrate scripts/ into the build pipeline — the operational visualization scripts could be run as part of uor-build or a new uor-viz binary, producing CSVs and SVGs as build artifacts
10. Streamlit integration — wire the Python memo package into a Streamlit form (described in the prototype's README as the next step)

Branch reference

• Branch: feature/report-template
• Key commits:
  • 9aae86d — Add uor-report crate: Rust PDF report generator
  • d26725e — Stage T: Destructive correctness pass (ontology vocabulary changes, unrelated to report but on the same branch)
  • 5d487a3 — Bump version to 0.2.0
• Untracked local work: scripts/ directory (15 visualization scripts), various generated CSVs/SVGs/PNGs in public/01_robinwikoff/exploring_views/

File inventory (new files)

report/
├── Cargo.toml
├── assets/
│   ├── DMSans-Bold.ttf
│   ├── DMSans-BoldItalic.ttf
│   ├── DMSans-Italic.ttf
│   ├── DMSans-Regular.ttf
│   └── uor-icon-black.png
├── examples/
│   └── memo_input.yaml
└── src/
    ├── generator.rs
    ├── lib.rs
    └── schema.rs

clients/src/bin/report.rs   (new binary)

public/01_robinwikoff/report_template/
├── README.md
├── requirements.txt
├── memo_input_example.yaml
├── memo/
│   ├── __init__.py
│   ├── branding.py
│   ├── cli.py
│   ├── generator.py
│   ├── schema.py
│   └── template.py
└── assets/
    ├── DMSans-Variable.ttf
    ├── uor-icon-black.png
    └── uor-icon-live.png

scripts/                     (untracked)
├── Operational_All.sh
├── Operational_*.sh         (11 scripts)
└── Prism_Surface_*.sh       (2 scripts)