code-report-toolkit

Generate a product-level 11-page PDF report for any codebase, combining structured Chinese analysis with architecture diagrams.

Accepts both local project paths and GitHub URLs as input.

中文文档

---

Report Structure

Page	Title
0	Cover
1	TL;DR
2	Problem & Positioning
3	Core User Loop
4	Product Capability Structure
5	Key Design Decisions
6	Product Philosophy
7	Trade-offs
8	Reusable Design Patterns
9	Insights & Transfer
10	Core Summary

---

Installation

pip install reportlab playwright pillow pyyaml
playwright install chromium

---

Usage

This tool runs as a Claude Code Skill. Trigger it in Claude Code:

Analyze this project and generate a code report: <local path or GitHub URL>

Or invoke the skill directly:

Use the code-report-toolkit skill to analyze https://github.com/owner/repo

---

Workflow

Input (local path / GitHub URL)
    ↓ resolve_source.py
Prepare local source directory
    ↓ scan_project.py
Project scan (scan_result.json)
    ↓ code-analysis sub-skill
Text analysis report (analysis.md)
    ↓ prepare_report_bundle.py
Report bundle (report_bundle.json)
    ↓ diagram-renderer sub-skill (per diagram)
Architecture diagrams (PNG)
    ↓ build_pdf_html.py
Final PDF

---

Project Structure

code-report-toolkit/
├── SKILL.md                              # Main skill entry point
└── skills/
    ├── code-analysis/
    │   ├── SKILL.md                      # Code analysis sub-skill
    │   ├── REFERENCE.md                  # Report format specification
    │   └── scripts/
    │       ├── resolve_source.py         # Resolve input path / clone GitHub repo
    │       ├── scan_project.py           # Scan project structure → scan_result.json
    │       ├── analysis_progress.py      # Check completed sections in analysis.md
    │       ├── prepare_report_bundle.py  # Generate report_bundle.json
    │       ├── build_pdf_html.py         # HTML/CSS → PDF (recommended)
    │       ├── build_pdf.py              # ReportLab → PDF (fallback)
    │       └── templates/               # PDF style templates
    └── diagram-renderer/
        ├── SKILL.md                      # Diagram rendering sub-skill
        ├── REFERENCE.md                  # Color specs and element syntax
        ├── scripts/
        │   └── render_to_png.py         # .excalidraw → PNG
        └── templates/                   # 13 diagram type templates

---

Sub-Skills

code-analysis

Analyzes project source code and generates a structured analysis.md. Supports resume — if interrupted, re-running only writes missing sections.

diagram-renderer

Converts natural language diagram descriptions into PNG images. Pipeline: natural language → Excalidraw JSON → render → PNG.

Supports 13 diagram types: flowchart, hierarchy, comparison, matrix, mind map, relationship, timeline, swimlane, class diagram, sequence diagram, ER diagram, data flow diagram, and pattern structure.

---

Temporary Files

The following intermediate files are written to /tmp/ during execution:

File	Description
/tmp/prepared_source.json	Resolved source path info
/tmp/scan_result.json	Project scan result
/tmp/analysis.md	Text analysis report
/tmp/report_bundle.json	Diagram tasks + PDF input bundle
/tmp/diagrams/*.png	Generated architecture diagrams