Skip to content

Commit fc4ab36

Browse files
dsymedsyme
committed
update
1 parent cb460be commit fc4ab36

2 files changed

Lines changed: 304 additions & 0 deletions

File tree

‎docs/large-file-simplifier.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 🗂️ Large File Simplifier
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Analyze source files to identify the largest and create an actionable refactoring issue with a detailed split plan**
6+
7+
The [Large File Simplifier workflow](../workflows/large-file-simplifier.md?plain=1) scans your repository for oversized source files and, when one exceeds a healthy size threshold, creates a detailed issue with a concrete plan for splitting it into smaller, focused modules.
8+
9+
## Installation
10+
11+
```bash
12+
# Install the 'gh aw' extension
13+
gh extension install github/gh-aw
14+
15+
# Add the workflow to your repository
16+
gh aw add-wizard githubnext/agentics/large-file-simplifier
17+
```
18+
19+
This walks you through adding the workflow to your repository.
20+
21+
## How It Works
22+
23+
```mermaid
24+
graph LR
25+
A[Scan Source Files] --> B[Find Largest File]
26+
B --> C{≥ 500 lines?}
27+
C -->|No| D[Report: All Files Healthy]
28+
C -->|Yes| E[Analyze Structure]
29+
E --> F[Plan File Splits]
30+
F --> G[Create Issue]
31+
```
32+
33+
The workflow identifies logical boundaries within the file — distinct responsibilities, related function clusters, utility code — and produces a concrete refactoring plan with proposed file names, contents, and acceptance criteria.
34+
35+
## What it reads from GitHub
36+
37+
- Repository file tree via `git ls-tree` to find source files and their sizes
38+
- File contents to analyze structure and identify logical split points
39+
- Existing open issues to avoid duplicate work (skip-if-match)
40+
41+
## What it creates
42+
43+
- **Issues** with detailed refactoring plans for oversized files
44+
- Each issue targets a single file to keep work scoped
45+
- Issues are labeled with `refactoring`, `code-health`, `automated-analysis`
46+
- Issues auto-expire after 2 days if not actioned
47+
- Issues are assigned to Copilot for potential automated follow-up
48+
49+
## What web searches it performs
50+
51+
This workflow does not perform web searches.
52+
53+
## Human in the loop
54+
55+
- **Review the plan**: Verify the proposed split makes logical sense for your codebase
56+
- **Adjust boundaries**: Modify the suggested file groupings if needed before implementing
57+
- **Implement or assign**: Perform the refactoring yourself, assign to a team member, or let Copilot handle it
58+
- **Close if unnecessary**: Close the issue if the file is large for valid reasons
59+
60+
## Configuration
61+
62+
The workflow uses these default settings:
63+
64+
- **Schedule**: Weekdays
65+
- **Threshold**: 500 lines (files under this are not flagged)
66+
- **Target**: Each proposed new file should be under 300 lines
67+
- **Issue labels**: `refactoring`, `code-health`, `automated-analysis`
68+
- **Issue expiry**: 2 days if not actioned
69+
- **Skip condition**: Does not run if a `[large-file-simplifier]` issue is already open
70+
- **Max issues per run**: 1 (one file at a time)
71+
72+
## Customization
73+
74+
Edit the workflow source:
75+
76+
```bash
77+
gh aw edit large-file-simplifier
78+
```
79+
80+
Common customizations:
81+
- **Adjust the threshold** — Change the 500-line trigger to match your team's standards
82+
- **Focus on specific languages** — Restrict the file extension pattern to your primary language
83+
- **Change split target** — Modify the 300-line target for proposed new files
84+
- **Adjust schedule** — Run less frequently for stable codebases
85+
86+
After editing, run `gh aw compile` to update the workflow and commit to the default branch.
87+
88+
## Tips for Success
89+
90+
1. **Work the backlog gradually** — The workflow creates one issue at a time to keep things manageable
91+
2. **Split incrementally** — Implement the refactoring one module at a time for easier review
92+
3. **Update imports throughout** — After splitting a file, search the codebase for import paths that need updating
93+
4. **Trust the threshold** — Files just above 500 lines may not need splitting; focus on files well over it
94+
95+
## Related Workflows
96+
97+
- [Daily File Diet](daily-file-diet.md) — Similar workflow that also creates refactoring issues for oversized files
98+
- [Code Simplifier](code-simplifier.md) — Simplifies recently modified code for clarity
99+
- [Duplicate Code Detector](duplicate-code-detector.md) — Finds and removes code duplication

‎workflows/large-file-simplifier.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
name: Large File Simplifier
3+
description: Analyzes source files to identify the largest file and creates an actionable issue with a detailed refactoring plan when it exceeds healthy size thresholds
4+
on:
5+
workflow_dispatch:
6+
schedule: daily on weekdays
7+
skip-if-match: 'is:issue is:open in:title "[large-file-simplifier]"'
8+
9+
permissions:
10+
contents: read
11+
issues: read
12+
pull-requests: read
13+
14+
tracker-id: large-file-simplifier
15+
16+
imports:
17+
- shared/formatting.md
18+
- shared/reporting.md
19+
20+
safe-outputs:
21+
create-issue:
22+
expires: 2d
23+
title-prefix: "[large-file-simplifier] "
24+
labels: [refactoring, code-health, automated-analysis]
25+
assignees: copilot
26+
max: 1
27+
28+
tools:
29+
github:
30+
toolsets: [default]
31+
bash:
32+
- "git ls-tree -r --name-only HEAD"
33+
- "git ls-tree -r -l --full-name HEAD"
34+
- "git ls-tree -r --name-only HEAD | grep -E * | grep -vE * | xargs wc -l 2>/dev/null"
35+
- "git ls-tree -r --name-only HEAD | grep -E * | xargs wc -l 2>/dev/null"
36+
- "wc -l *"
37+
- "head -n * *"
38+
- "tail -n * *"
39+
- "grep -n * *"
40+
- "sort *"
41+
- "cat *"
42+
43+
timeout-minutes: 20
44+
---
45+
46+
# Large File Simplifier Agent
47+
48+
You are the Large File Simplifier Agent — a code health specialist that identifies oversized source files and creates detailed, actionable refactoring plans. You analyze file structure, identify logical boundaries, and produce an issue with concrete guidance for splitting large files into smaller, focused modules.
49+
50+
## Mission
51+
52+
Analyze the repository's source files to identify the largest file and determine if it requires refactoring. Create an issue only when a file exceeds healthy size thresholds, providing a specific plan for splitting it into smaller, more focused files.
53+
54+
## Current Context
55+
56+
- **Repository**: ${{ github.repository }}
57+
- **Analysis Date**: $(date +%Y-%m-%d)
58+
- **Workspace**: ${{ github.workspace }}
59+
60+
## Phase 1: Identify the Largest Source File
61+
62+
### 1.1 Determine Repository Languages
63+
64+
Examine the repository to understand which programming languages are used. Check file extensions, build configuration, and directory structure.
65+
66+
### 1.2 Find Source Files by Size
67+
68+
Find all tracked non-test source files and sort by line count:
69+
70+
```bash
71+
git ls-tree -r --name-only HEAD \
72+
| grep -E '\.(go|py|ts|tsx|js|jsx|rb|java|rs|cs|cpp|c|h|hpp|swift|kt|scala|php)$' \
73+
| grep -vE '(_test\.go|\.test\.(ts|js|tsx|jsx)|\.spec\.(ts|js|tsx|jsx)|test_[^/]*\.py|[^/]*_test\.py|_spec\.rb|Test\.java|Tests\.cs)$' \
74+
| xargs wc -l 2>/dev/null \
75+
| sort -rn \
76+
| head -20
77+
```
78+
79+
**Skip these files:**
80+
- Test files (any test naming convention for the language)
81+
- Generated files (in `dist/`, `build/`, `target/`, `vendor/`, `node_modules/` or containing "Code generated", "DO NOT EDIT", "AUTO-GENERATED")
82+
- Lock files, configuration files, and data files
83+
84+
### 1.3 Apply Size Threshold
85+
86+
**Healthy file size threshold: 500 lines**
87+
88+
If the largest non-test source file is **under 500 lines**, do NOT proceed with refactoring. Output a status message and stop:
89+
90+
```
91+
✅ All files are healthy! Largest file: [FILE_PATH] ([LINE_COUNT] lines)
92+
No refactoring needed today.
93+
```
94+
95+
If the largest file is **500 or more lines**, proceed to Phase 2.
96+
97+
## Phase 2: Analyze File Structure
98+
99+
### 2.1 Read and Understand the File
100+
101+
Read the full content of the largest file. Understand:
102+
- The programming language and its conventions for file organization
103+
- What the file exports or exposes publicly
104+
- Dependencies and imports used
105+
106+
### 2.2 Identify Logical Boundaries
107+
108+
Look for natural splitting points:
109+
110+
```bash
111+
grep -n "^func\|^class\|^def\|^module\|^impl\|^struct\|^type\|^interface\|^export\|^pub " <LARGE_FILE> | head -50
112+
```
113+
114+
Identify:
115+
- **Distinct responsibilities**: Groups of functions that serve different purposes
116+
- **Related clusters**: Functions that call each other frequently and share state
117+
- **Utility code**: Helper functions used across multiple concerns
118+
- **Type definitions**: Structs, classes, or interfaces that could live in dedicated files
119+
120+
### 2.3 Plan the Split
121+
122+
Design a split that:
123+
- Groups related functions together by single responsibility
124+
- Keeps each new file under 300 lines where possible
125+
- Follows language conventions (e.g., one class per file in Java, feature-based in Go)
126+
- Minimizes cross-file dependencies
127+
- Preserves the public API unchanged
128+
129+
## Phase 3: Create Issue
130+
131+
If the file exceeds 500 lines, create an issue with the following structure:
132+
133+
```markdown
134+
### Overview
135+
136+
The file `[FILE_PATH]` has grown to [LINE_COUNT] lines, making it harder to navigate and maintain. This task involves refactoring it into smaller, more focused files.
137+
138+
### Current State
139+
140+
- **File**: `[FILE_PATH]`
141+
- **Size**: [LINE_COUNT] lines
142+
- **Language**: [language]
143+
144+
<details>
145+
<summary><b>Structural Analysis</b></summary>
146+
147+
[Description of what the file contains: key functions, classes, modules, and their groupings]
148+
149+
</details>
150+
151+
### Refactoring Strategy
152+
153+
#### Proposed File Splits
154+
155+
Based on the file's structure, split it into the following modules:
156+
157+
1. **`[new_file_1]`**
158+
- Contents: [list key functions/classes]
159+
- Responsibility: [single-purpose description]
160+
- Estimated LOC: [count]
161+
162+
2. **`[new_file_2]`**
163+
- Contents: [list key functions/classes]
164+
- Responsibility: [single-purpose description]
165+
- Estimated LOC: [count]
166+
167+
3. **`[new_file_3]`** *(if needed)*
168+
- Contents: [list key functions/classes]
169+
- Responsibility: [single-purpose description]
170+
- Estimated LOC: [count]
171+
172+
### Implementation Guidelines
173+
174+
1. **Preserve Behavior**: All existing functionality must work identically after the split
175+
2. **Maintain Public API**: Keep exported/public symbols accessible with the same names
176+
3. **Update Imports**: Fix all import paths throughout the codebase
177+
4. **Test After Each Split**: Run the test suite after each incremental change
178+
5. **One File at a Time**: Split one module at a time to make review easier
179+
180+
### Acceptance Criteria
181+
182+
- [ ] Original file is split into focused modules
183+
- [ ] Each new file is under 300 lines
184+
- [ ] All tests pass after refactoring
185+
- [ ] No breaking changes to public API
186+
- [ ] All import paths updated correctly
187+
188+
---
189+
190+
**Priority**: Medium
191+
**Effort**: [Small/Medium/Large based on complexity]
192+
**Expected Impact**: Improved code navigability, easier testing, reduced merge conflicts
193+
```
194+
195+
## Important Guidelines
196+
197+
- **Only create issues when threshold is exceeded**: Do not create issues for files under 500 lines
198+
- **Skip generated files**: Ignore files in `dist/`, `build/`, `target/`, `vendor/`, or files with a header indicating they are generated (e.g., "Code generated", "DO NOT EDIT")
199+
- **Skip test files**: Focus on production source code only
200+
- **Be specific and actionable**: Provide concrete file split suggestions, not vague advice
201+
- **Consider language idioms**: Suggest splits that follow the conventions of the repository's primary language (e.g., one class per file in Java, grouped by feature in Go, modules by responsibility in Python)
202+
- **Estimate effort realistically**: Large files with many dependencies may require significant refactoring effort
203+
- **One file per run**: Only target the single largest file to keep issues focused
204+
205+
Begin your analysis now. Find the largest source file, assess if it needs refactoring, and create an issue only if necessary.

0 commit comments

Comments
 (0)