Skip to content

Commit c776001

Browse files
github-actions[bot]GitHub CopilotCopilotdsyme
authored
Add weekly-repo-map workflow (#243)
Adds a new weekly workflow that generates an ASCII tree map visualization of the repository's file structure and size distribution. The workflow: - Runs every Monday via schedule, or on-demand via workflow_dispatch - Uses standard bash tools (find, du) for language-agnostic analysis - Generates proportional size bars and file counts in a visual tree - Creates a GitHub issue with the tree map, key statistics, and file type breakdown - Closes the previous week's issue automatically Adapted from repo-tree-map.md in Peli's Agent Factory (gh-aw). Co-authored-by: GitHub Copilot <copilot@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Don Syme <dsyme@users.noreply.github.com>
1 parent b518fb6 commit c776001

3 files changed

Lines changed: 276 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com
2929
- [📰 Daily Repository Chronicle](docs/daily-repo-chronicle.md) - Transform daily repository activity into an engaging newspaper-style narrative with trend charts
3030
- [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination
3131
- [🔍 Discussion Task Miner](docs/discussion-task-miner.md) - Extract actionable improvement tasks from GitHub Discussions and create tracked issues
32+
- [🗺️ Weekly Repository Map](docs/weekly-repo-map.md) - Visualize repository file structure and size distribution with a weekly ASCII tree map
3233

3334
### Dependency Management Workflows
3435

‎docs/weekly-repo-map.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 🗺️ Weekly Repository Map
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Visualize your repository's file structure and size distribution with a weekly ASCII tree map**
6+
7+
The [Weekly Repository Map workflow](../workflows/weekly-repo-map.md?plain=1) analyzes your repository's structure every week using standard bash tools, then creates a GitHub issue containing an ASCII tree map visualization showing directory hierarchy, file sizes, and key statistics.
8+
9+
## Installation
10+
11+
Add the workflow to your repository:
12+
13+
```bash
14+
gh aw add https://github.com/githubnext/agentics/blob/main/workflows/weekly-repo-map.md
15+
```
16+
17+
Then compile:
18+
19+
```bash
20+
gh aw compile
21+
```
22+
23+
> **Note**: This workflow creates GitHub Issues with the `documentation` label.
24+
25+
## What It Does
26+
27+
The Weekly Repository Map runs every Monday and:
28+
29+
1. **Collects Repository Statistics** — Counts files, measures sizes, and maps the directory structure using standard bash tools
30+
2. **Generates ASCII Tree Map** — Creates a visual representation of the repository hierarchy with proportional size bars
31+
3. **Summarizes Key Metrics** — Reports file type distribution, largest files, and directory sizes
32+
4. **Creates an Issue** — Posts the complete visualization as a GitHub issue, closing the previous week's issue
33+
34+
## How It Works
35+
36+
````mermaid
37+
graph LR
38+
A[Collect File Statistics] --> B[Compute Sizes & Counts]
39+
B --> C[Generate ASCII Tree Map]
40+
C --> D[Compute Key Statistics]
41+
D --> E[Create Issue Report]
42+
````
43+
44+
### Output: GitHub Issues
45+
46+
Each run produces one issue containing:
47+
48+
- **Repository Overview** — Brief summary of the repository's structure and size
49+
- **ASCII Tree Map** — Visual directory hierarchy with size bars using box-drawing characters
50+
- **File Type Breakdown** — Count of files by extension
51+
- **Largest Files** — Top 10 files by size
52+
- **Directory Sizes** — Top directories ranked by total size
53+
54+
Example excerpt from an issue:
55+
56+
```
57+
Repository Tree Map
58+
===================
59+
60+
/ [1234 files, 45.2 MB]
61+
│
62+
├─ src/ [456 files, 28.5 MB] ██████████████████░░
63+
│ ├─ core/ [78 files, 5.2 MB] ████░░
64+
│ └─ utils/ [34 files, 3.1 MB] ███░░
65+
│
66+
├─ docs/ [234 files, 8.7 MB] ██████░░
67+
│
68+
└─ tests/ [78 files, 3.5 MB] ███░░
69+
```
70+
71+
## Configuration
72+
73+
The workflow uses these default settings:
74+
75+
| Setting | Default | Description |
76+
|---------|---------|-------------|
77+
| Schedule | Weekly on Monday | When to run the analysis |
78+
| Issue label | `documentation` | Label applied to created issues |
79+
| Max issues per run | 1 | Prevents duplicate reports |
80+
| Issue expiry | 7 days | Older issues are closed when a new one is posted |
81+
| Timeout | 10 minutes | Per-run time limit |
82+
83+
## Customization
84+
85+
```bash
86+
gh aw edit weekly-repo-map
87+
```
88+
89+
Common customizations:
90+
- **Change issue labels** — Set the `labels` field in `safe-outputs.create-issue` to labels that exist in your repository
91+
- **Adjust the schedule** — Change to run more or less frequently (e.g., daily or monthly)
92+
- **Customize exclusions** — Update the bash commands to exclude additional directories (e.g., `vendor/`, `dist/`)
93+
- **Adjust tree depth** — Edit the prompt to change how deep the tree visualization goes (default max is 3–4 levels)
94+
95+
## Related Workflows
96+
97+
- [Repository Quality Improver](repository-quality-improver.md) — Daily analysis of quality dimensions across your repository
98+
- [Daily File Diet](daily-file-diet.md) — Monitor for oversized source files and create targeted refactoring issues
99+
- [Weekly Issue Summary](weekly-issue-summary.md) — Weekly issue activity report with trend charts

‎workflows/weekly-repo-map.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
description: Generates a weekly ASCII tree map visualization of repository file structure and size distribution
3+
on:
4+
schedule: weekly on monday around 15:00
5+
workflow_dispatch:
6+
permissions:
7+
contents: read
8+
issues: read
9+
pull-requests: read
10+
engine: copilot
11+
tools:
12+
edit:
13+
bash:
14+
- "*"
15+
safe-outputs:
16+
create-issue:
17+
expires: 7d
18+
title-prefix: "[repo-map] "
19+
labels: [documentation]
20+
max: 1
21+
close-older-issues: true
22+
noop:
23+
timeout-minutes: 10
24+
strict: true
25+
---
26+
27+
# Repository Tree Map Generator
28+
29+
Generate a comprehensive ASCII tree map visualization of the repository file structure.
30+
31+
## Mission
32+
33+
Your task is to analyze the repository structure and create an ASCII tree map that visualizes:
34+
1. Directory hierarchy
35+
2. File sizes (relative visualization)
36+
3. File counts per directory
37+
4. Key statistics about the repository
38+
39+
## Analysis Steps
40+
41+
### 1. Collect Repository Statistics
42+
43+
Use bash tools to gather:
44+
- **Total file count** across the repository
45+
- **Total repository size** (excluding .git directory)
46+
- **File type distribution** (count by extension)
47+
- **Largest files** in the repository (top 10)
48+
- **Largest directories** by total size
49+
- **Directory depth** and structure
50+
51+
Example commands you might use:
52+
```bash
53+
# Count total files
54+
find . -type f -not -path "./.git/*" | wc -l
55+
56+
# Get repository size
57+
du -sh . --exclude=.git
58+
59+
# Count files by extension
60+
find . -type f -not -path "./.git/*" | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
61+
62+
# Find largest files
63+
find . -type f -not -path "./.git/*" -exec du -h {} + | sort -rh | head -10
64+
65+
# Directory sizes
66+
du -h --max-depth=2 --exclude=.git . | sort -rh | head -15
67+
```
68+
69+
### 2. Generate ASCII Tree Map
70+
71+
Create an ASCII visualization that shows:
72+
- **Directory tree structure** with indentation
73+
- **Size indicators** using symbols or bars (e.g., █ ▓ ▒ ░)
74+
- **File counts** in brackets [count]
75+
- **Relative size representation** (larger files/directories shown with more bars)
76+
77+
Example visualization format:
78+
```
79+
Repository Tree Map
80+
===================
81+
82+
/ [1234 files, 45.2 MB]
83+
│
84+
├─ src/ [456 files, 28.5 MB] ██████████████████░░
85+
│ ├─ core/ [78 files, 5.2 MB] ████░░
86+
│ ├─ utils/ [34 files, 3.1 MB] ███░░
87+
│ └─ tests/ [124 files, 12.8 MB] ████████░░
88+
│
89+
├─ docs/ [234 files, 8.7 MB] ██████░░
90+
│ └─ content/ [189 files, 7.2 MB] █████░░
91+
│
92+
├─ .github/ [45 files, 2.1 MB] ██░░
93+
│ └─ workflows/ [32 files, 1.4 MB] █░░
94+
│
95+
└─ tests/ [78 files, 3.5 MB] ███░░
96+
```
97+
98+
### Visualization Guidelines
99+
100+
- Use **box-drawing characters** for tree structure: │ ├ └ ─
101+
- Use **block characters** for size bars: █ ▓ ▒ ░
102+
- Scale the visualization bars **proportionally** to sizes
103+
- Keep the tree **readable** - don't go too deep (max 3-4 levels recommended)
104+
- Add **type indicators** using emojis:
105+
- 📁 for directories
106+
- 📄 for files
107+
- 🔧 for config files
108+
- 📚 for documentation
109+
- 🧪 for test files
110+
111+
### 3. Generate Key Statistics
112+
113+
Compute and include:
114+
- **Total repository size** (excluding .git)
115+
- **Total file count** by type (source, tests, docs, config, etc.)
116+
- **Largest files** (top 10 by size)
117+
- **Most file-dense directories** (top 5 by file count)
118+
- **File type breakdown** (e.g., .ts, .js, .py, .go, etc.)
119+
120+
### 4. Output Format
121+
122+
Create a GitHub issue with the complete tree map and statistics. Use proper markdown formatting with code blocks for the ASCII art.
123+
124+
Structure the issue body as follows:
125+
126+
```markdown
127+
### Repository Overview
128+
129+
Brief 1-2 sentence summary of the repository structure and size.
130+
131+
### File Structure
132+
133+
\`\`\`
134+
[Your ASCII tree map here]
135+
\`\`\`
136+
137+
### Key Statistics
138+
139+
#### By File Type
140+
[Table or list of file counts by extension]
141+
142+
#### Largest Files
143+
[Top 10 largest files with sizes]
144+
145+
#### Directory Sizes
146+
[Top directories by total size]
147+
```
148+
149+
## Important Notes
150+
151+
- **Exclude .git directory** from all calculations to avoid skewing results
152+
- **Exclude package manager directories** (node_modules, vendor, etc.) if present
153+
- **Handle special characters** in filenames properly
154+
- **Format sizes** in human-readable units (KB, MB, GB)
155+
- **Round percentages** to 1-2 decimal places
156+
- **Sort intelligently** - largest first for most sections
157+
- **Be creative** with the ASCII visualization but keep it readable
158+
- **Test your bash commands** before including them in analysis
159+
- The tree map should give a **quick visual understanding** of the repository structure and size distribution
160+
161+
## Security
162+
163+
Treat all repository content as trusted since you're analyzing the repository you're running in. However:
164+
- Don't execute any code files
165+
- Don't read sensitive files (.env, secrets, etc.)
166+
- Focus on file metadata (sizes, counts, names) rather than content
167+
168+
## Tips
169+
170+
Your terminal is already in the workspace root. No need to use `cd`.
171+
172+
**Important**: If no action is needed after completing your analysis, you **MUST** call the `noop` safe-output tool with a brief explanation. Failing to call any safe-output tool is the most common cause of safe-output workflow failures.
173+
174+
```json
175+
{"noop": {"message": "No action needed: [brief explanation of what was analyzed and why]"}}
176+
```

0 commit comments

Comments
 (0)